sphinx-gp-mermaid: build-time Mermaid diagrams as dual inline SVG

[tony]

Summary

• Add sphinx-gp-mermaid, a workspace package rendering MyST mermaid fences to inline SVG at build time via mmdc (@mermaid-js/mermaid-cli) — no client-side mermaid runtime, no async pop-in, no layout shift, and diagrams ride SPA navigation as finished DOM.
• Render twice, toggle with CSS: each diagram produces a light and a dark SVG (palettes mapped to gp-furo tokens), both inlined and switched on body[data-theme]. Mermaid bakes id-scoped !important colors into its SVGs, so a single render cannot follow the theme toggle.
• Cache aggressively: SVGs are content-addressed under <confdir>/_mermaid_cache, keyed on render version + theme + full mermaid config JSON + source — styling changes bust the cache, and the cache survives rm -rf docs/_build. The extension excludes the directory from source discovery automatically.
• Degrade, don't fail: a missing or failing mmdc warns once per builder and falls back to the escaped diagram source; text/latex/man/texinfo builders emit a [diagram: <alt>] stand-in instead of crashing on the node.
• Route plain fences at conf level: merge_sphinx_config() sets myst_fence_as_directive = ["mermaid"] whenever the extension lands in the final extension list; explicit overrides still win.
• Provenance: extracted from tmuxp's docs/_ext/mermaid_inline.py (Docs: build-time mermaid + tmux-layout diagram rendering tmux-python/tmuxp#1071), where it is proven in production docs. tmuxp adopts this package in the companion PR.

Changes by area

New package: packages/sphinx-gp-mermaid

• sphinx_gp_mermaid/__init__.py: mermaid directive (:caption:, :alt:, :name:) → marker node → HTML write-phase visitor → mmdc subprocess → dual normalized SVGs in a <figure>. Renderer resolution walks mermaid_cmd config → <confdir>/node_modules/.bin/mmdc → PATH; puppeteer config is generated with --no-sandbox and a Chrome discovered in puppeteer's cache. SVG normalization rewrites mermaid's hardcoded my-svg id (attribute, scoped <style>, url(#…) marker refs) to a per-diagram-per-theme id, replaces width="100%" with explicit width/height from the root viewBox, and strips the inline max-width.
• _static/css/sphinx_gp_mermaid.css: ships inside the package and registers at builder-inited. Classes use the workspace namespace: gp-sphinx-diagram, gp-sphinx-diagram__variant--theme-{light,dark}, gp-sphinx-diagram__fallback.

Coordinator: gp_sphinx/config.py

• Fence routing auto-set when sphinx_gp_mermaid is active; documented with a doctest.

Workspace wiring

• Root pyproject.toml (uv source, dev group, isort first-party, doctest testpath), wheel smoke runner in scripts/ci/package_tools.py, ux cluster assignment in docs/_ext/package_reference.py, docs landing stub, and a legacy extensions/ redirect.

Tests: tests/ext/mermaid/

• Unit: SVG normalization, digest stability, palettes, visitor markup, renderer-missing fallback, cache idempotency, setup registration.
• Integration: a full HTML build over a stub fake_mmdc.py that honors the -i/-o/-c contract and bakes themeVariables.primaryColor into the SVG — proving the light and dark configs each cross the subprocess boundary; plus a text-builder build asserting the alt-text stand-in.
• Palette tripwire: scrapes gp-furo-tokens light.ts/dark.ts and asserts every non-font themeVariable equals its token value, so a token retune fails in CI instead of drifting silently.

Design decisions

• Dual render instead of client-side theming: mermaid's theming engine only accepts literal hex (derived colors are computed at render time), and its output styles are id-scoped with !important — one SVG cannot be re-themed by page CSS. Two renders share identical geometry, so the CSS display toggle never shifts layout.
• Conf-level fence routing: myst-parser snapshots myst_* config at its own config-inited, so an extension mutating config from setup() lands too late; merge_sphinx_config is the deterministic place.
• Opt-in, not DEFAULT_EXTENSIONS: rendering requires a node toolchain (mermaid-cli + headless Chrome). Auto-loading would push that onto every consumer for a capability few docs use today.
• Warn-once memo on the builder rather than a module global, keeping the extension's parallel_write_safe declaration honest.

Test plan

• uv run ruff check . and uv run ruff format . — clean
• uv run mypy . — strict, clean
• uv run py.test --reruns 0 — full suite including module doctests
• just build-docs — landing page renders; setup() replays cleanly through the package-reference recorder
• tests/ext/mermaid/test_integration.py — both fence spellings render, dual variants carry per-theme fills, normalization holds, options pass through, packaged CSS ships, cache is excluded and populated, figure markup snapshot is stable
• tests/ext/mermaid/test_palette_sync.py — palettes match gp-furo tokens in both themes
• Consumed end-to-end from tmuxp (companion PR): all existing production diagrams render from cache with zero re-renders

Companion PR

• Docs: consume sphinx-gp-mermaid, drop the vendored renderer tmux-python/tmuxp#1073 — adopts the package and drops its vendored copy

[codecov-commenter]

Codecov Report

❌ Patch coverage is 94.99037% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.50%. Comparing base (f554d4c) to head (e12a0ca).

Files with missing lines	Patch %	Lines
...phinx-gp-mermaid/src/sphinx_gp_mermaid/__init__.py	89.05%	22 Missing ⚠️
scripts/ci/package_tools.py	20.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #61      +/-   ##
==========================================
+ Coverage   92.43%   92.50%   +0.06%     
==========================================
  Files         258      263       +5     
  Lines       20327    20846     +519     
==========================================
+ Hits        18790    19283     +493     
- Misses       1537     1563      +26     

☔ View full report in Codecov by Harness.
📢 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.