fix(website): close the docs shell's nav-height and column-measure defects

[blove]

Polish pass over the /docs single-pane reading experience, picking up where the footer removal in #932 left off. I audited the shell end to end across 360–1920px before changing anything; three of the things I found are real defects, one is a parity gap, and several suspicions turned out to be fine and are left alone.

--nav-h was wrong by 15px from 768px to 1023px

The nav has three heights, not two. Padding steps at md (768px), but the tall hidden lg:flex link row only appears at lg (1024px), leaving a 66px nav in between:

viewport	real nav	--nav-h (before)	error
360–767	58px	58px	0
768–1023	66px	81px	+15px
1024+	81px	81px	0

Everything that offsets against the nav reads this one variable, so the whole tablet band overshot: dead space above the docs column, and the mobile drawer (top: calc(var(--nav-h) - 1px)) hanging 14px below the nav it is supposed to attach to — measured at 900px wide, nav bottom 66px, drawer top 80px.

This is the nav-height coupling that the migration comment in pages.css deferred to "a later project". It turned out to live in chrome.css, not in the docs shell, and it is site-wide rather than docs-only.

After: the breadcrumb moves from y=105 to y=90 at 900px, and the drawer sits flush.

overflow-x-hidden on the article: removed, not relocated

The fear behind keeping it is already covered — global.css sets body { overflow-x: clip }, with a comment explaining that hidden was rejected there precisely because it creates a scroll container and kills sticky descendants. The article's hidden made that same mistake locally: overflow-x: hidden computes overflow-y: auto, so every docs article was a scroll container (verified: computed overflow-y was auto with the class, visible without).

Before trusting the removal I swept all 123 docs URLs at 375px with the class removed — zero horizontal overflow. Wide code blocks and tables scroll inside their own overflow-x: auto containers, which is where the containment belongs.

The other half of that stale comment is also updated: the paddingTop: 80 hardcode was already replaced with var(--nav-h), and min-h-screen + padding-top don't stack under the global box-sizing: border-box.

One column edge

The breadcrumb/page-header block had no max-width while the article and prev/next rail both sat at max-w-3xl, so PageActions floated ~500px right of the column it belongs to (header right edge 1648 vs prose 1096 at 1920px). It now shares the same measure — header and prev/next right edges both land on 1048.

/docs/choosing-an-adapter gains the TOC rail

It carries as many headings as any library page (7 H2s plus H3s) but had no rail. It stays library-neutral, so it takes no breadcrumb or page header — both are keyed to a library it deliberately has not picked.

Audited and left alone

• Sticky behaviour is correct. The control plane and TOC both hold at top: --nav-h through a full 7723px scroll; align-self: flex-start intact; the sidebar pane scrolls internally (1335 vs 819).
• Page endings read deliberate. Articles: 48px gap → prev/next → 47px tail. The index ends flush on a tinted band.
• The TOC scroll-spy works. It looked dead under instrumentation, but that was the harness — a hidden browser pane suspends requestAnimationFrame, so the rAF-gated update never ran, and window.scrollTo there moves scrollY without emitting a scroll event at all. In a real browser it tracks correctly, and there is now a test proving it.
• .docs-index-body is a marker class with no CSS; the spec pinning it is untouched.

Tests

e2e/nav-height.spec.ts pins --nav-h to the rendered nav at all six breakpoint edges — jsdom cannot measure layout, so a real browser is the only place these two can be compared. e2e/docs-shell.spec.ts covers the TOC rail (which had no tests at all) and the shared column edge.

The existing horizontal-overflow guard in website.spec.ts was vacuous: it measured documentElement.scrollWidth, which the global body clip pins to the viewport width, so its 24 assertions could never fail — that is the test that supposedly protected the class removed here. It now measures whether content escapes its own column, exempting content inside its own horizontal scroller.

Every new and rewritten guard was mutation-tested against the defect it describes: reverting --nav-h fails 4 tablet-band tests; injecting a 2000px element fails the overflow guard by name; dropping the measure fails the column-edge test.

Verification

• npx vitest run — 447 passed / 59 files (unchanged from baseline)
• npx nx e2e website — 72 passed (59 pre-existing + 13 new)
• npx nx lint website — 0 errors, 27 pre-existing warnings
• npx nx build website — succeeds, production bundle budgets included

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
threadplane	Ready	Preview	Sep 1, 2026 11:18pm UTC

[github-actions]

Claude finished @blove's task in 0s —— View job

---

I'll analyze this and get back to you.

[github-actions]

Automated approval: this PR received an intelligent (AI) code review. See the review comments on this PR.

[github-actions]

Claude finished @blove's task in 0s —— View job

---

I'll analyze this and get back to you.