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 tmux-python/tmuxp#1021
• docs: self-host fonts, eliminate layout shift, add SPA navigation tmux-python/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-commenter]

Codecov Report

❌ Patch coverage is 99.31741% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.52%. Comparing base (102f45a) to head (10d3369).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
docs/_ext/sphinx_fonts.py	98.82%	1 Missing ⚠️
docs/conf.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #50      +/-   ##
==========================================
+ Coverage   83.71%   85.52%   +1.80%     
==========================================
  Files          25       27       +2     
  Lines        2235     2528     +293     
==========================================
+ Hits         1871     2162     +291     
- Misses        364      366       +2     

☔ 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 1 issue:

1. Partial file left on OSError mid-download poisons the cache (_download_font): urlretrieve opens the destination file with open(filename, 'wb') before reading from the network. If an OSError occurs mid-download (e.g. disk-full), the exception is caught and False is returned — but the partial file remains on disk. On the next build, if dest.exists() returns True and the function returns True as if the file were valid, so shutil.copy2 copies the corrupt file into _static/fonts/. The browser then gets a 404-or-corrupt woff2 for that weight. Fix: delete dest before returning when the download fails (or write to a .tmp file and rename on success).

g/docs/_ext/sphinx_fonts.py

Lines 57 to 68 in d8fe69a

	def _download_font(url: str, dest: pathlib.Path) -> bool:
	if dest.exists():
	logger.debug("font cached: %s", dest.name)
	return True
	dest.parent.mkdir(parents=True, exist_ok=True)
	try:
	urllib.request.urlretrieve(url, dest)
	logger.info("downloaded font: %s", dest.name)
	except (urllib.error.URLError, OSError):
	logger.warning("failed to download font: %s", url)
	return False
	return True

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