docs: self-host fonts, eliminate layout shift, add SPA navigation

[tony]

Summary

Port documentation frontend improvements from tmuxp:

• docs(style): refine typography — headings, TOC, and body tmuxp#1021
• docs: self-host fonts, eliminate layout shift, add SPA navigation tmuxp#1022

Overhaul the docs frontend for faster, smoother page loads:

• Self-hosted fonts — IBM Plex Sans/Mono via Fontsource CDN with build-time download, caching, and preload to eliminate Flash of Unstyled Text (FOUT)
• Font fallback metrics — Capsize-derived size-adjust, ascent-override, descent-override on system fallbacks so text does not reflow when web fonts load
• Layout shift prevention — badge placeholder sizing and sidebar logo dimensions to eliminate Cumulative Layout Shift (CLS)
• SPA-like navigation — vanilla JS script (~170 lines, no deps) intercepts internal link clicks and swaps only the three DOM regions that change
• View Transitions API — smooth crossfade between pages during SPA navigation (instant swap on unsupported browsers)
• Typography refinements — kerning, ligatures, letter-spacing on body; optimizeSpeed on code blocks; Biome-inspired heading scale; wider TOC panel
• Sidebar visibility gate — prevent flash of active link state on initial load

See tmuxp PRs for full design rationale and test plan.

[codecov]

Codecov Report

❌ Patch coverage is 99.55947% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 51.19%. Comparing base (372bfb1) to head (7a7e83b).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
tests/docs/_ext/conftest.py	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #643      +/-   ##
==========================================
+ Coverage   46.55%   51.19%   +4.64%     
==========================================
  Files          22       25       +3     
  Lines        2363     2590     +227     
  Branches      389      402      +13     
==========================================
+ Hits         1100     1326     +226     
  Misses       1094     1094              
- Partials      169      170       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Found 2 issues. Checked for bugs and CLAUDE.md compliance.

---

Issue 1 — Bug: font_faces entry appended even when font download fails (score: 90)

libtmux/docs/_ext/sphinx_fonts.py

Lines 96 to 105 in c60f903

	if _download_font(url, cached):
	shutil.copy2(cached, fonts_dir / filename)
	font_faces.append(
	{
	"family": font["family"],
	"style": style,
	"weight": str(weight),
	"filename": filename,
	}
	)

font_faces.append(...) is outside the if _download_font(url, cached): block — it runs unconditionally whether the download succeeded or not. When a font fails to download (network offline, CDN error), the @font-face rule is still emitted referencing a .woff2 file that was never written to _static/fonts/. The browser will 404 on every font request and fall back to system fonts, defeating the purpose of the extension.

Fix: indent the font_faces.append(...) call one level to place it inside the if block, so only successfully-obtained fonts are registered.

---

Issue 2 — CI: docs-fonts branch trigger not reverted (score: 82)

libtmux/.github/workflows/docs.yml

Lines 6 to 7 in c60f903

	- master
	- docs-fonts

Commit 7b789ec9 adds docs-fonts to the push.branches trigger with the message "temporarily add docs-fonts branch to trigger". The corresponding tmuxp PR (which this is ported from) includes a revert commit that removes it before merging. This PR does not include that revert, so after merging the docs-fonts trigger will remain permanently. Any future branch named docs-fonts (or the current one if not deleted) will continue to trigger a full docs rebuild and deploy to production.

Fix: add a revert commit (or amend the workflow) to remove docs-fonts from push.branches before merging.

🤖 Generated with Claude Code
_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}