## Summary
Two fixes to the documentation site.
**The contents rail went dark between headings.** The right-hand table
of contents lit an entry only while its heading was inside the viewport.
Partway through a section longer than the screen every heading sits
above or below it, so nothing was lit, the gold stretch collapsed to
zero height, and the column stopped following the reader. On the built
site before this change, 18 of 28 English pages had such stretches: 114
of 1264 scroll positions sampled every 120px. `sync()` in
`docs-site/docs/javascripts/toc-progress.js` now falls back to the
nearest heading above when none is in view and lights that entry alone.
The lit stretch and the column follow read the same list, so both pick
it up with no further change. Above the first heading nothing is lit,
since no section has begun there. The design spec states the rule, and
the rail's section comment in `evermind.css`, which still credited
Material with marking the section, now names what does.
**The tab icon differed from raven.evermind.ai.** The site drew its own
simplified EverMind mark, a single heavy lemniscate without the rings.
raven.evermind.ai links one 192px PNG of the full mark for its light,
dark and apple-touch icons alike. `theme.favicon` in
`docs-site/mkdocs.yml` now inlines that PNG byte for byte as a data URI,
since AGENTS.md section 7 keeps image files out of `docs-site/`. For
whoever refreshes it: that site's CDN answers any `Accept` naming
`image/avif` with a lossy AVIF re-encode (5178 bytes), and only a plain
`Accept: */*` returns the original PNG (5184 bytes). The comment above
the value says so.
Checked and deliberately left alone:
- The mark at the top of the navigation rail (`--em-mark` in
`evermind.css`) is a separate drawing and still the simplified one. This
change is the tab icon only.
- raven.evermind.ai also sets an apple-touch icon. Material emits no
such link, and adding one needs a template override, which is an `.html`
file that section 7 blocks.
- The favicon's identity is verified by the measurements below rather
than pinned by a test: a pinned hash would only detect change, and
comparing against the live site would put the network in the suite.
- `tests/integration/` is outside every CI job (`norecursedirs`), so the
e2e results below are local runs.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run --frozen --extra browser --group docs pytest
tests/integration/test_docs_site_controls_e2e.py
tests/integration/test_docs_site_search_e2e.py -n 0 -q`: 63 passed.
- `uv run --frozen --extra browser --group docs pytest
tests/test_docs_site.py -q`: 16 passed.
- The new
`test_table_of_contents_keeps_the_section_above_lit_between_headings`
computes, from the Sandbox page's own layout, every stretch between two
headings (or after the last) with none on screen, and checks the middle
of each. Against the unfixed script it fails (`at 1354px: assert [] ==
[2]`), and with the fix it passes.
- A sweep of every built page in headless Chrome at 1440x900, one sample
every 120px, checking the rule at each position: 0 violations over 1264
English, 1145 Chinese and 21 Overview positions after the change, and
wherever an entry is lit, the first one sits inside the contents column.
The unfixed script gives 114 violations over the same English positions.
- Favicon: each of the 63 built HTML files carries exactly one icon
link, and its decoded bytes match the PNG raven.evermind.ai links
(sha256 `4a5051e1781fac64...`). Drawn in Chrome at 16, 32 and 192px, the
docs icon and that PNG differ in 0 pixels.
- `mkdocs build --strict`, `scripts/check_source_language.py
origin/main...HEAD`, `scripts/check_large_files.py origin/main...HEAD`,
`scripts/check_commit_messages.py origin/main..HEAD`, commitlint,
`pre-commit run --from-ref origin/main --to-ref HEAD`, ruff and `git
diff --check`: all pass.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The last box is left blank because nothing needed it: no documentation
page describes the rail or the icon, and the design spec is updated in
this change.
## Risk
- Between headings, the entry of the section above now stays lit and the
contents column keeps it in view. While any heading is on screen the
behaviour is unchanged.
- The tab icon changes to the full mark. Each page's head now carries
about 6.9 KB of base64 for it, against about 0.6 KB for the previous
SVG.
- The new code relies on no browser API newer than
`Array.prototype.includes` (2016).
- The two halves touch disjoint files, so either can be reverted on its
own.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The inlined PNG was read chunk by chunk: standard chunks plus three
ImageMagick timestamps, and nothing after IEND. Inlining it adds no
third-party request, which hotlinking the CDN copy would have.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>