why: The renderer is proven in tmuxp production docs; moving it into the
workspace package makes it installable by every gp-sphinx consumer.

what:
- Full pipeline: mermaid directive -> mermaid_inline node -> HTML
  write-phase visitor -> mmdc subprocess -> dual light/dark inline SVG
- Content-hash SVG cache under <confdir>/_mermaid_cache, keyed on
  render version, theme, full mermaid config JSON, and source; cache
  key inputs unchanged from the tmuxp version so existing caches hit
- mmdc resolution (config -> confdir node_modules -> PATH), puppeteer
  config generation with cached-Chrome discovery, graceful degradation
  to escaped source when the renderer is missing
- Config values: mermaid_cmd, mermaid_puppeteer_config
- CSS classes join the workspace namespace: gp-sphinx-diagram,
  gp-sphinx-diagram__variant--theme-{light,dark},
  gp-sphinx-diagram__fallback; stylesheet ships in the package's
  _static and registers at builder-inited
- Unit tests: SVG normalization, digest, palettes, visitor, fallback,
  cache idempotency, setup registration, static-path idempotence

why: The HTML-only visitor left text/latex/man/texinfo builds to crash
on an unhandled node, and the module-global warn-once flag contradicted
the extension's parallel_write_safe declaration.

what:
- text/man/latex/texinfo visitors emit an "[diagram: <alt>]" stand-in
  (alt falling back to caption), following sphinx.ext.graphviz
- Warn-once memo moves to a builder attribute (imgmath's pattern), so
  each writer process warns at most once and fresh builds start clean
- setup() excludes _mermaid_cache from source discovery at config-inited
- _render treats OSError (e.g. a resolved but non-executable command)
  as MermaidRendererMissing instead of crashing the build
- Tests: fallback-text cases, all four visitors, per-builder memo,
  PermissionError degradation, and a text-builder integration scenario

why: The unit suite never exercises the fence -> directive -> subprocess
-> dual-figure HTML pipeline, and the palette hexes are hand copies of
gp-furo-tokens values that could drift silently.

what:
- Full HTML build over a stub mmdc (a python script honouring the
  -i/-o/-c contract) that bakes themeVariables.primaryColor into the
  SVG, proving both theme configs cross the subprocess boundary
- Asserts both fence spellings render, SVG normalization, option
  passthrough (caption/alt/name), packaged CSS shipping, cache
  exclusion and population, and a stable figure-markup snapshot
- Palette tripwire: scrapes light.ts/dark.ts custom properties and
  checks every non-font themeVariable against its token (black/white
  keywords normalized), plus a coverage guard for new palette keys

why: myst-parser snapshots myst_* config at its own config-inited, so
sphinx_gp_mermaid cannot reliably register its fence routing from
setup(); conf level is the deterministic place, and consumers should
not need boilerplate for it.

what:
- merge_sphinx_config() sets myst_fence_as_directive = ["mermaid"]
  whenever sphinx_gp_mermaid lands in the final extension list
- Explicit myst_fence_as_directive overrides still win (overrides
  apply last)
- Tests: routing on with the extension, absent without it, override
  wins; docstring doctest documents the behavior

why: The extension declares parallel_write_safe, but a plain
write_text lets a parallel writer read a torn half-written SVG
from the shared confdir cache.

what:
- Write to a pid-suffixed .tmp sibling, then Path.replace onto
  the final path (POSIX-atomic; Sphinx's dump_search_index
  pattern)
- Assert cached content and no .tmp leftovers in the cache
  idempotency test

why: A :name:-ed diagram loses its anchor when mmdc is missing,
so cross-references to it 404 in degraded builds.

what:
- Hoist ids/fig_id computation above the render try block
- Emit fig_id on the fallback <pre>, matching the <figure> path
- Parametrized FallbackAnchorCase test for named and anonymous
  diagrams

why: Two identical diagrams on one page emitted identical
mermaid-<digest>-<theme> ids -- invalid duplicate DOM ids that
break the id-scoped styles and marker url() refs.

what:
- Count digest occurrences per translator (fresh per document,
  per worker process) and fold "-<n>" into repeat ids
- Occurrence 0 keeps today's id, so snapshots stay stable
- _svg_element_id gains occurrence kwarg + doctest
- Parametrized DuplicateDiagramCase visitor test

why: str.replace rewrote every "my-svg" substring, corrupting
visible label text such as "Deploy my-svg-viewer".

what:
- Compiled regex rewrites only id-token contexts: attribute
  values, #-refs/CSS selectors, and chart-desc-/chart-title-
  a11y ids
- Docstring contract + doctest for preserved label text
- NormalizeCase entries: label text preserved, a11y ids rewritten

why: The comment claimed myst-parser snapshots myst_* config at
config-inited; it actually snapshots at builder-inited
(create_myst_config). The code is right, the reason given wasn't.

what:
- Name the real event and tighten the comment to two lines

why: The package was missing from the categorized package
listing on the packages index.

what:
- Add sphinx-gp-mermaid bullet under Common libraries alongside
  its ux-cluster siblings; widen the section intro to cover
  shared page primitives

why: CSS standards reserve package-owned classes for
gp-sphinx-<pkg>__<thing>; gp-sphinx-diagram read as a Tier A
shared concept it isn't.

what:
- Rename gp-sphinx-diagram* -> gp-sphinx-mermaid* across the
  visitor, stylesheet, and tests (block/element/modifier shape
  unchanged, matching the gp-sphinx-fastmcp precedent)
- Re-record test_integration.ambr snapshot

why: The package shipped only a landing stub while its README
promised full documentation and every sibling carries the
how-to/reference/dependents tree.

what:
- how-to.md: authoring, renderer/CI install, theming/caching
  behavior, graceful degradation
- reference.md: autoconfigvalues + autodirectives + setup
- dependents.md + pyproject showcase opt-in

why: The package shipped no example diagrams, so readers had no way
to see what its dual light/dark output looks like across the range
of mermaid diagram types.

what:
- 11 diverse src/*.mmd sources (flowchart, sequence, class, state,
  er, gantt, pie, gitgraph, mindmap, timeline, block)
- Committed dual light/dark SVGs rendered through the extension's
  own pipeline (furo palette + id/size normalization)
- generate.py regenerator + pinned mermaid-cli toolchain manifest
- README gallery and a test pairing each source with its outputs

why: The docs never rendered a mermaid diagram — the extension
wasn't loaded and the committed example gallery was orphaned from
the site.

what:
- docs/_ext/mermaid_examples.py: a directive that inlines each
  committed example's source + its dual-theme SVG in the
  extension's gp-sphinx-mermaid figure markup (no live render)
- docs/conf.py: load sphinx_gp_mermaid (ships the toggle CSS) and
  the mermaid_examples directive
- Hermetic integration test asserting one dual-theme figure per
  committed source, no renderer invoked

why: mermaid was the only package without an examples.md; its
committed diagram gallery never appeared on the docs site.

what:
- examples.md: a {mermaid-examples} block, auto-discovered by the
  package landing as the Examples subpage
- Widen the docs-package-pages content guard to cover sphinx-gp-*
  and recognise the {mermaid-examples} live-demo marker

why: setup()'s doctest only checked callable(); its docs/_ext
siblings assert the directive registers. _figure_markup claims to
mirror the visitor but never tested the role/aria markup.

what:
- setup() doctest records add_directive and asserts the directive
  name + class registered
- _figure_markup doctest asserts role/aria-hidden/aria-label

why: The helper's glob now also admits sphinx-gp-* packages (to
cover the mermaid examples page), but its docstring still said
"autodoc / ux" only.

what:
- Widen the docstring to name the gp family

why: Record the new build-time Mermaid diagram package under the
forthcoming unreleased entry.