Replace Furo dependency with in-tree Tailwind v4 theme port

[tony]

Summary

• Add gp-furo-theme — an in-tree Sphinx theme that reproduces vanilla Furo's HTML, behaviour, and visual surface, authored in pure Tailwind v4 CSS (no SASS).
• Add gp-furo-tokens — a TypeScript-only Tailwind v4 plugin that emits Furo's full token contract (light + dark) as body / body[data-theme="dark"] blocks.
• Add gp-sphinx-vite — Sphinx orchestration that auto-spawns pnpm exec vite build --watch under sphinx-autobuild, auto-installs node_modules/ when missing, and is a hard no-op in production wheels.
• Replace furo runtime dependency in sphinx-gp-theme with gp-furo-theme; inherit = furo → inherit = gp-furo in theme.conf. Furo (and its transitives accessible-pygments, sphinx-basic-ng) drop out of the workspace lock.
• Wire merge_sphinx_config(vite_orchestration=True) into docs/conf.py so contributors get live CSS/JS rebuild via just start with no extra command.
• Specialise light-mode Pygments Generic.Prompt (purple-500) and Generic.Output (cyan-600) so shell prompts + command output stay distinguishable from Generic.Subheading — mirrors dark-mode (monokai) pink + cyan asymmetry.

Changes by area

New package — packages/gp-furo-tokens/ (TypeScript-only)

File	Description
src/contract.ts	Zod literal-union of every --* identifier harvested from upstream Furo's SCSS (~153 names)
src/light.ts, src/dark.ts	Hex / var() / gradient values ported byte-verbatim — no OKLCH conversion (fidelity port)
src/plugin.ts	Tailwind v4 plugin((api) => api.addBase(...)) emitting body { … } body[data-theme="dark"] { … }
__tests__/contract.test.ts	Gates Zod schema vs upstream-SCSS name diff so drift fails CI

New package — packages/gp-furo-theme/ (Python + TypeScript + CSS)

• src/gp_furo_theme/ — verbatim port of upstream Furo's Python: _asset_hash, _html_page_context, _builder_inited, _overwrite_pygments_css, WrapTableAndMathInAContainerTransform, navigation.py. Strict-typed (Pygments styles are classes, not instances — fixed upstream's annotation in the port).
• src/gp_furo_theme/theme/gp-furo/ — all 20 Furo Jinja templates ported verbatim with single-line attribution headers.
• web/src/scripts/furo.ts — strict-typed re-author of furo.js (theme-toggle, mobile sidebar, scroll-spy, back-to-top). Wrapped in source-level IIFE to isolate function _() from doctools.js's const _ = Documentation.gettext.
• web/src/scripts/gumshoe.js + gumshoe.d.ts — vendored verbatim modulo a 4-line UMD→ESM boundary edit; typed surface restricted to what furo.ts consumes (.d.ts ends with export {}; so it's a module).
• web/src/styles/ — pure Tailwind v4 entry (index.css) plus per-component files (base.css, lists.css, tables.css, admonitions.css, code.css, api.css, search.css, scaffold.css, sidebar.css, toc.css, extensions.css, …). No @apply chains; component rules are plain CSS in component-scoped files.
• LICENSE-FURO at package root + per-template Jinja attribution + <!-- Generated with Sphinx … and Furo {{ furo_version }} --> HTML comment in base.html (license obligation).

New package — packages/gp-sphinx-vite/

File	Description
config.py	Pure detect_mode(config_value, argv, env) + GpSphinxViteConfig dataclass — no Sphinx dep, fully unit-testable
process.py	ViteProcess async subprocess wrapper, factories vite_watch_command() + pnpm_install_command()
bus.py	Thread + asyncio.new_event_loop().run_forever() bridge so sync Sphinx hooks can drive async I/O
hooks.py	builder-inited spawn, _ensure_node_modules() auto-install if missing, atexit + SIGINT/TERM/HUP teardown
__init__.py	Sphinx setup() registering gp_sphinx_vite_mode + gp_sphinx_vite_root config values

packages/sphinx-gp-theme/ — re-parent + Pygments tightening

• theme/theme.conf: inherit = furo → inherit = gp-furo; stylesheet = styles/furo-tw.css, css/custom.css, css/argparse-highlight.css
• pyproject.toml: furo → gp-furo-theme==0.0.1a13 in dependencies
• pygments_styles.py: Generic.Prompt bold #475569 → bold #a855f7 (purple-500); Generic.Output #475569 → #0891b2 (cyan-600). Closes light-mode asymmetry vs dark mode's pink-on-cyan.

packages/gp-sphinx/ — orchestration wiring

• merge_sphinx_config(..., vite_orchestration=True) parameter — when true, prepends gp_sphinx_vite to extensions and resolves gp_sphinx_vite_root via gp_furo_theme.get_vite_root().
• defaults.py DEFAULT_THEME unchanged (sphinx-gp-theme); cutover is invisible to consumers.

Tests

• tests/visual/test_visual_regression.py — Playwright pixel-diff suite: 12 pages × 2 modes × 3 viewports = 72 captures vs baseline-scss/ snapshots.
• tests/visual/test_furo_behaviors.py — 5 behavioural Playwright tests (theme-toggle cycling, mobile drawer, scroll-spy, back-to-top, skip-to-content focus).
• tests/visual/test_baseline_capture.py — re-capture script for baselines.
• tests/test_gp_sphinx_vite_*.py — 49 new unit + integration tests across config, process, bus, hooks (TDD against a fake-vite shell script).
• tests/test_gp_furo_theme_equivalence.py — HTML byte-equivalence vs upstream Furo (CSS half dropped post-pivot to Tailwind; pytest.importorskip("furo") so the file skips post-cutover).
• tests/test_gp_furo_theme_tw_contract.py — asserts the Tailwind output contains the selectors furo.ts toggles at runtime.
• tests/test_pygments_style.py — added 2 cases for the new gp + go light-mode colours; snapshot regenerated.

Docs + housekeeping

• docs/packages/gp-furo-theme.md, docs/packages/gp-furo-tokens.md, docs/packages/gp-sphinx-vite.md — package pages following the existing template.
• docs/redirects.txt — three new extensions/<name> packages/<name> entries.
• pnpm-workspace.yaml (new) — collapses lockfile + virtual store across gp-furo-tokens + gp-furo-theme/web.
• pyproject.toml — [tool.uv.sources] adds gp-furo-theme + gp-sphinx-vite workspace pins.
• scripts/ci/package_tools.py — smoke runners for the three new packages.
• CHANGES — release note describing the Tailwind v4 cutover and Furo drop.

Design decisions

Pure Tailwind v4, no SASS. Original plan ported Furo's SCSS verbatim via dart-sass. After landing that pipeline, the target shifted to the maintainer's preferred Tailwind v4 idiom (per-component plain CSS, no @apply chains, @theme inline token surface). The SCSS pipeline was unwound (step 9.14) and replaced with hand-authored component files. Visual fidelity (Playwright pixel diff) replaced source-byte fidelity (CSS AST equivalence) as the gating signal. Trade-off: ~6.5 kB CSS size delta vs upstream Furo (per-file headers + flatter rule structure), accepted because tokens + behaviour stay 1:1.

Token plugin emits at body, not :root. CSS variable aliases like --color-content-foreground: var(--color-foreground-primary) substitute their var() at the declaring element's scope and are frozen there. With aliases at :root, dark-mode overrides on body[data-theme="dark"] couldn't re-resolve them — dark pages rendered with light values. Mirrors upstream Furo's body { @include colors } pattern.

Source-level IIFE wrap, not Rollup format: 'iife'. Tried the Rollup option first; it errored with Invalid value for option "output.inlineDynamicImports" - multiple inputs are not supported because the Vite config has multiple entries. Wrapping the function body of furo.ts with (function (): void { … })(); achieves the same scope isolation without forcing a config rewrite. Closes the SyntaxError: Identifier '_' has already been declared regression where Rollup minified readTheme() to function _() and collided with doctools.js:147's const _ = Documentation.gettext.

box-sizing: content-box on .content only. Tailwind preflight sets universal box-sizing: border-box; upstream Furo's _scaffold.sass was authored against content-box. Scoping the override to .content (not the layout containers with explicit width: 15em, which behave identically under either model) restores the flex-grow distribution that fills .main correctly across the 7-breakpoint grid.

Auto-install node_modules/ instead of documenting a manual step. User invariant: git clean -fdx; cd docs; just clean; just start should always produce a working dev environment. gp_sphinx_vite.hooks._ensure_node_modules() runs pnpm install --frozen-lockfile synchronously through the existing AsyncioBus + ViteProcess infrastructure when <vite_root>/node_modules/ is missing. Failure is logged as a warning, not raised — docs build still proceeds without live JS/CSS rebuild.

Theme-toggle SVG visibility rules in @layer components, not @layer base. Tailwind layer cascade beats specificity: .theme-toggle svg { display: none } at @layer components was suppressing the activation rules at @layer base regardless of selector specificity. Co-locating both in @layer components resolves visibility cleanly. Caught a one-off rendering regression where the toggle button shipped at width=0.

sphinx-gp-theme keeps its project-specific layer. gp-furo-theme is a vanilla Furo port — no spa-nav.js, no projects sidebar, no IBM Plex tweaks, no Cloudflare Rocket Loader workaround. Those stay in sphinx-gp-theme and overlay on top of the gp-furo parent. Equivalence target for gp-furo-theme is therefore upstream Furo, not furo + sphinx-gp-theme.

Verification

Furo is no longer in the dependency tree:

$ uv tree | grep -ic '\bfuro\b'

Workspace registers the three new packages:

$ uv run python -c "from gp_sphinx_workspace import workspace_packages; print(sorted(workspace_packages()))" | tr ',' '\n' | grep -E 'gp-furo|gp-sphinx-vite'

sphinx-gp-theme re-parents on gp-furo:

$ grep -E '^inherit' packages/sphinx-gp-theme/src/sphinx_gp_theme/theme/theme.conf

License attribution survives the cutover:

$ test -f packages/gp-furo-theme/LICENSE-FURO && grep -c 'Ported from furo' packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/*.html

Vite orchestration auto-detects sphinx-autobuild:

$ uv run python -c "from gp_sphinx_vite.config import detect_mode; print(detect_mode(config_value='auto', argv=['sphinx-autobuild', 'docs/'], env={}))"

Test plan

• uv run ruff check . --fix --show-fixes — no lint diagnostics
• uv run ruff format . — formatting clean
• uv run mypy — strict type-check passes (mypy 1.x, Python 3.10 floor)
• uv run pytest --reruns 0 — full suite green (1281+ pytest, 12 syrupy snapshots, 12 vitest)
• just build-docs — production Sphinx build succeeds; vite orchestration no-ops as expected
• pnpm exec vitest run (in packages/gp-furo-tokens/) — token contract tests green
• tests/test_gp_furo_theme_equivalence.py::test_html_byte_equivalent_with_furo — verifies HTML structural parity vs upstream Furo (skipped post-cutover via importorskip)
• tests/visual/test_visual_regression.py — Playwright pixel diff vs SCSS-built baselines under threshold
• tests/visual/test_furo_behaviors.py — 5 behavioural tests (theme-toggle, mobile drawer, scroll-spy, back-to-top, skip-link)
• tests/test_gp_sphinx_vite_hooks.py::test_on_builder_inited_runs_install_when_node_modules_missing — auto-install behaviour
• tests/test_pygments_style.py::test_gp_sphinx_light_token_palette[generic-prompt-purple|generic-output-cyan] — light-mode Pygments parity
• Manual: git clean -fdx && cd docs && just clean && just start produces a working dev environment with no manual pnpm install; http://localhost:3124/ renders with zero 404s on furo-tw.css / furo.js and zero JS console errors

Notes for reviewers

• 38.7% of the file diff is binary baseline PNGs under tests/visual/__snapshots__/baseline-scss/ (72 captures × ~250 kB avg). They're load-bearing for the visual regression suite but contain no reviewable content — skip them.
• 20 Jinja templates under packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/ are byte-identical to upstream Furo modulo a single attribution header line.
• 44 CSS files removed in 9d86bc (drop SCSS pipeline) were vendored Furo SCSS that the Tailwind v4 rewrite (commits f982a58..2d0bfa0) replaced. The drop is mechanical, not a behaviour change.
• The branch was rebased onto current main (commit 9f62b7a resolves stray conflict markers + lockstep version bumps to 0.0.1a13).

[codecov-commenter]

Codecov Report

❌ Patch coverage is 78.11448% with 325 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.04%. Comparing base (ae8c5c7) to head (e92ce7a).

Files with missing lines	Patch %	Lines
tests/visual/test_furo_behaviors.py	22.00%	78 Missing ⚠️
tests/visual/test_visual_regression.py	40.96%	49 Missing ⚠️
tests/test_gp_furo_theme_equivalence.py	8.51%	43 Missing ⚠️
...ckages/gp-furo-theme/src/gp_furo_theme/__init__.py	79.88%	36 Missing ⚠️
...ages/gp-furo-theme/src/gp_furo_theme/navigation.py	19.44%	29 Missing ⚠️
tests/visual/conftest.py	46.87%	17 Missing ⚠️
...ackages/gp-sphinx-vite/src/gp_sphinx_vite/hooks.py	83.67%	16 Missing ⚠️
scripts/ci/package_tools.py	12.50%	14 Missing ⚠️
tests/visual/test_baseline_capture.py	66.66%	14 Missing ⚠️
packages/gp-sphinx-vite/src/gp_sphinx_vite/bus.py	88.88%	8 Missing ⚠️
... and 7 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #25      +/-   ##
==========================================
- Coverage   90.15%   89.04%   -1.11%     
==========================================
  Files         164      183      +19     
  Lines       13655    15138    +1483     
==========================================
+ Hits        12310    13480    +1170     
- Misses       1345     1658     +313     

☔ 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 6 issues:

1. bus.py calls logger.exception() inside a Future.add_done_callback — the callback runs outside any except block, so the traceback context is empty (CLAUDE.md says "Use logger.exception() only inside except blocks ... Use logger.error(..., exc_info=True) when you need the traceback outside an except block").

gp-sphinx/packages/gp-sphinx-vite/src/gp_sphinx_vite/bus.py

Lines 120 to 129 in 927ad9b

	def _log_exception(fut: t.Any) -> None:
	exc = fut.exception()
	if exc is not None:
	logger.exception(
	"background coroutine on %s raised", self._name, exc_info=exc
	)
	future.add_done_callback(_log_exception)

2. gp_furo_theme/__init__.py defines a module-level logger but never attaches logging.NullHandler() (CLAUDE.md says "Add NullHandler in library __init__.py files"; sibling packages gp_sphinx and sphinx_fonts follow the convention).

gp-sphinx/packages/gp-furo-theme/src/gp_furo_theme/__init__.py

Lines 45 to 49 in 927ad9b

	THEME_PATH = (pathlib.Path(__file__).parent / "theme" / THEME_NAME).resolve()
	logger = logging.getLogger(__name__)
	# GLOBAL STATE — populated by ``_builder_inited`` and consumed by

3. Same NullHandler omission in gp_sphinx_vite/__init__.py (CLAUDE.md says "Add NullHandler in library __init__.py files").

gp-sphinx/packages/gp-sphinx-vite/src/gp_sphinx_vite/__init__.py

Lines 38 to 42 in 927ad9b

	__version__ = "0.0.1a14"
	logger = logging.getLogger(__name__)

4. hooks.py logger.warning(...) message ends with a period (CLAUDE.md log message style says "No trailing punctuation").

gp-sphinx/packages/gp-sphinx-vite/src/gp_sphinx_vite/hooks.py

Lines 98 to 106 in 927ad9b

	if returncode != 0:
	logger.warning(
	"[vite] pnpm install failed (exit %d) in %s — skipping vite "
	"spawn. Run the install manually and restart sphinx-autobuild.",
	returncode,
	vite_root,
	)
	return False
	logger.info("[vite] pnpm install complete; proceeding to vite-watch spawn")

5. hooks.py module docstring at L19 references :func:_teardown`` but the actual public function is teardown (no underscore) at L178 — the `:func:` cross-reference will not resolve.

gp-sphinx/packages/gp-sphinx-vite/src/gp_sphinx_vite/hooks.py

Lines 17 to 25 in 927ad9b

	signal handlers installed at first spawn.
	Tear-down is the responsibility of :func:`_teardown`, which is wired
	to ``atexit`` and to ``SIGINT`` / ``SIGTERM`` / ``SIGHUP``.
	The handlers are passive about command construction: they call
	:func:`gp_sphinx_vite.process.vite_watch_command` for the default Vite
	argv. Tests monkey-patch that symbol when they want a fake-vite invocation.
	"""

6. AsyncioBus.start() after stop() silently spawns a fresh thread, contradicting the class docstring's "The bus is single-use. After stop() it is not safe to start again — construct a new instance" contract — stop() resets _thread = None, so start()'s idempotency guard passes through and re-spawns rather than raising.

gp-sphinx/packages/gp-sphinx-vite/src/gp_sphinx_vite/bus.py

Lines 48 to 78 in 927ad9b

	3. :meth:`stop` schedules the loop to stop, joins the thread.
	The bus is single-use. After ``stop()`` it is not safe to start
	again — construct a new instance.
	"""
	def __init__(self, *, name: str = "gp-sphinx-vite-bus") -> None:
	self._name = name
	self._loop: asyncio.AbstractEventLoop | None = None
	self._thread: threading.Thread | None = None
	self._ready = threading.Event()
	@property
	def is_running(self) -> bool:
	"""True iff the loop thread is alive."""
	return self._thread is not None and self._thread.is_alive()
	def start(self) -> None:
	"""Start the background event loop. Idempotent."""
	if self._thread is not None and self._thread.is_alive():
	return
	self._ready.clear()
	self._thread = threading.Thread(
	target=self._run,
	daemon=True,
	name=self._name,
	)
	self._thread.start()
	# Block until the loop has been assigned. Without this, a
	# call_sync() racing the thread startup would deref None.
	self._ready.wait()

🤖 Generated with Claude Code

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

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

The 6 commits since the previous review (b7d7d8a..e92ce7a) cleanly address all 6 findings from that round. The substantive change — the new _stopped flag in AsyncioBus enforcing the documented "single-use" contract — was specifically scrutinized for race ordering, dead-thread vs live-thread teardown symmetry, and conflict with the existing test_double_start_is_idempotent / test_stop_before_start_is_idempotent / test_can_construct_a_new_bus_after_stop tests. The two new regression tests (test_start_after_stop_raises_runtime_error, test_stop_before_start_does_not_lock_out_subsequent_start) pin the contract from both sides without contradicting prior coverage.

🤖 Generated with Claude Code

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