agentic-mermaid 0.1.2 → 0.2.0

package/docs/mutation-testing.md

@@ -0,0 +1,285 @@
+# Mutation testing
+
+The original ASCII Stryker lane is scoped to the five layout modules where a
+silent logic regression is most expensive: `src/ascii/pathfinder.ts`,
+`src/ascii/edge-routing.ts`, `src/ascii/converter.ts`, `src/ascii/grid.ts`,
+`src/ascii/draw.ts`.
+The `ascii` profile in the single `stryker.config.mjs` authority executes the
+ASCII test files (goldens, invariants, properties, unit tests) per mutant.
+
+## Running
+
+```bash
+# One module (preferred — a full module takes 5–15 minutes):
+bun run mutation-test -- ascii --mutate 'src/ascii/pathfinder.ts'
+
+# All five:
+bun run mutation-test -- ascii
+
+# Discover every available profile:
+bun run mutation-test -- --list
+```
+
+(`bun run mutation-test -- families` covers the
+shared Architecture, XYChart, Mindmap, GitGraph, and Radar parser/layout/renderer
+cores plus Radar's structured editing body, and `bun run mutation-test -- routes` covers
+the route-contracts module
+(`docs/design/system/route-contracts.md`), all with the same policy.)
+
+Narrow lanes for PR-scale survivor harvests:
+
+```bash
+bun run mutation-test -- links            # text-embedded link-length parsing
+bun run mutation-test -- routes:certs     # route-certificate finality + stale-route audit
+bun run mutation-test -- routes:subgraph  # subgraph endpoint/LCA routing
+bun run sabotage:routes                # one-line revert checks against committed HEAD; expects focused tests to fail
+```
+
+JSON reports land in `reports/mutation/` (gitignored). The single executable
+config resolves route-certificate, subgraph-routing, and link-grammar ranges
+from source-adjacent markers; inserting code above the behavior cannot silently
+move those lanes onto unrelated lines.
+
+Beyond the lanes documented here, configs exist for every built-in renderable
+family through named profiles: flowchart uses `mutation-test -- routes`;
+XYChart, Architecture, and Radar share `mutation-test -- families`; State, Sequence,
+Timeline, Class, ER, Journey, Pie, Quadrant, Gantt, Mindmap, and GitGraph each
+have a focused command. These are **opt-in diagnostic survivor harvests**. They
+emit scores and JSON reports, but have no `thresholds.break` and are neither
+scheduled nor acceptance gates.
+
+Two bounded checks run automatically on each PR:
+
+- `mutation-test -- incremental` mutates one small, pure module in about one minute
+  and enforces its measured score.
+- `sabotage:routes` injects five named one-line regressions and requires the
+  focused behavioral tests to fail.
+
+This distinction is deliberate. Mutation testing is useful when it challenges
+a specific test or design assumption; family membership alone is not a reason
+to enroll code in an expensive recurring sweep. A local mutation score without
+a retained report is diagnostic evidence, not a repository acceptance claim.
+
+## Why broad scheduled mutation was retired (2026-07-14)
+
+The nightly workflow, its sharder, mutant-set oracle, aggregate verifier, and
+orchestration tests were retired and deleted. The operational evidence did
+not support maintaining them:
+
+- all 26 scheduled runs from 19 June through 14 July failed or were cancelled;
+- the workflow expanded from four route checks to every family while it was
+  still unable to produce a successful retained run;
+- the final repair grew to 39 coverage workers (41 jobs total), yet long lanes
+  still timed out and hosted runners disappeared before producing reports; and
+- rerunning unchanged mutation-relevant code consumed runner-hours without
+  adding information.
+
+The [last scheduled baseline](https://github.com/adewale/agentic-mermaid/actions/runs/29309167850),
+[calibration diagnostic](https://github.com/adewale/agentic-mermaid/actions/runs/29327418603),
+and [cancelled 41-job repair](https://github.com/adewale/agentic-mermaid/actions/runs/29340333016)
+are retained as historical evidence, not as acceptance authority. The focused
+configs, marker-based scopes, survivor classifications, incremental gate, and
+sabotage probes remain because they are independently useful.
+
+The causal record is in
+[`project/archive/mutation-infrastructure-postmortem-2026-07.md`](./project/archive/mutation-infrastructure-postmortem-2026-07.md).
+The durable stop rule is: after three consecutive scheduled failures, an owner
+must fix, narrow, disable, or delete the diagnostic before adding scope. Any new
+recurring lane also needs a demonstrated fault class, one complete retained
+baseline, a runner-minute budget, an owner, and a removal criterion. No single
+proxy—coverage, mutation score, assertion count, or matrix enrollment—is “the”
+adequacy signal.
+
+## Focused Mindmap/GitGraph historical local measurement (2026-07-10)
+
+These figures came from local runs. Their JSON reports are gitignored and no
+immutable CI artifact URL is committed, so they are diagnostic history—not a
+PR acceptance gate or a current break floor.
+
+| Lane | Mutants | Killed | Survived | Score |
+|---|---:|---:|---:|---:|
+| `bun run mutation-test -- mindmap` (`src/agent/mindmap-body.ts`) | 405 | 400 | 5 | **98.77%** |
+| `bun run mutation-test -- gitgraph` (`src/agent/gitgraph-body.ts`) | 303 | 294 | 9 | **97.03%** |
+
+The operation suites exercise every happy path, validation branch, source-order
+rewrite, recursive/cycle guard, null-clearing path, and verification warning.
+Mindmap's five survivors are two correlated node-syntax tuple guards plus
+three exception-path mutations around the node/body stability probes (two
+empty `catch` forms remain falsy; one `false`→`true` mutation is retained as a
+non-gating test gap). GitGraph's nine
+survivors are canonical serialization equivalents (trimming an already
+canonical header, explicit `NORMAL`, and optional attribute whitespace),
+merge-field guards implied by the discriminated model, or widened
+statement-kind guards that serialize identically on valid replay state. Reports
+are generated at `reports/mutation/{mindmap,gitgraph}-mutation.json`
+(gitignored); the committed configs make the runs reproducible. The measured
+scores above are not acceptance evidence: any separately owned acceptance claim
+must cite retained CI artifacts or a content-addressed report.
+
+## Policy
+
+A SURVIVED mutant is a test gap until shown otherwise. Either kill it with a
+test (and sabotage-verify the test), or classify it below with a reason.
+Don't chase 100%: performance-guard and unreachable-branch mutants are
+documented, not killed with synthetic inputs.
+
+## Baseline (June 2026, first scoped run)
+
+| File | Score | Killed+timeout | Survived |
+| --- | --- | --- | --- |
+| pathfinder.ts | 60.3% → 70.8% after `ascii-pathfinder-units.test.ts` | 184 → 216 | 121 → 89 |
+| edge-routing.ts | 55.1% | 163 | 133 |
+| converter.ts | 38.4% | 94 | 151 |
+| grid.ts | 70.1% | 421 | 180 |
+| layout/passes/index.ts:931-1165 (linkrank packing repair) | 49.86% → 65.07% after the geometry-characterization harvest (355 mutants; killed 176 → 230+1 timeout). The +54 kills were the repair's candidate ORDERING / ahead-node selection / push-delta arithmetic — invisible to HARD-metric assertions (a mutant picking a different clear lane still yields zero violations), pinned instead by per-repro geometry snapshots in `linkrank-packing.test.ts` (layout determinism makes them stable). | 355 | 124 — see classification below |
+| route-contracts.ts | 58.1% → 72.3% → 75.6% → 73.1% across the first three batches; 54.31% at 0b43c90, then 50.69% at 526d9cf after the slanted-family batch (shapePorts generalization, convex-polygon geometry: 2659 → 2740 mutants — absolute kills 1444 → 1381). The percentage fell on denominator growth (~3× since batch 3); residuals from that run are classified below. | 882 → 2740 | 50.69% (1381 killed) — historical snapshot |
+
+(Numbers from the June 2026 runs; regenerate rather than trusting this
+table — the report lands in `reports/mutation/`.)
+
+## Historical survivor classification
+
+This section explains the recorded run; it is not a secondary test backlog.
+Only root `TODO.md` can schedule a new fixture or survivor-harvest package.
+
+**linkrank lane residual (124 at the 65.07% run)**, classified:
+
+- **Unexercised branch in the recorded corpus**: the subgraph-scoped
+  `separationUnit` branch (walk the overlapped node's scope chain, push its
+  outermost subgraph unit) did not fire because the degenerate repro set had no
+  subgraphs. A subgraph + long-link shove-overlap fixture was not part of that run.
+- **Unexercised defensive fallbacks**: the `rungSource` feedback family and some
+  min-lane branches fire only on inputs the deterministic enumeration no longer
+  produces (0 residual signatures); every adopted route is still runtime-validated by
+  `routeClearOfNodes`, so a wrong fallback cannot ship a through-node route.
+- **Equivalent on the real input domain**: exact-tie tiebreaks (`flowGap !== 0` id
+  fallback), the `pairKey` separator literal (any injective separator), the defensive
+  round cap (`nodes.length * 4` — forward-only motion terminates before it), and the
+  candidate-list `slice(0, 16)` caps (lists are shorter in practice).
+
+**Killed by `src/__tests__/ascii-pathfinder-units.test.ts`** (32 mutants):
+`buildMoveDirs` preferred-direction ordering (it only decides ties between
+equal-cost A* paths, which the golden corpus never isolates; the unit tests
+pin `path[1]` per direction), `heuristic` corner-penalty logic, and
+`mergePath` straight-run detection (backtracks and mixed-delta steps must
+be preserved).
+
+**Accepted — performance guards, not behavior** (pathfinder): the #66
+bounded-search mutants (`next.x > boundX || next.y > boundY` weakenings,
+`maxIterations` arithmetic). They change how much work an unreachable-target
+search does before returning null, not what any reachable search returns.
+Timing the search was judged less reliable than the risk warranted.
+
+**Accepted — unreachable via convention** (pathfinder): the `dy`-dominant
+fallback in `buildMoveDirs` (lines ~157–159). All nine 3×3 `Direction`
+constants either match an explicit cardinal branch or have `|dx| >= |dy|`,
+so the branch only runs for synthetic Direction values. Candidate for
+simplification, not for synthetic-input tests.
+
+**Found dead code**: the first mutation run showed the audit-suggested sort
+tie-breaks on the two `b.index - a.index` comparators in
+`determineLabelLine` could never fire — segment `index` is unique by
+construction — so they were reverted. Only the width-sort tie-break (where
+ties are real) remains. Mutation testing earning its keep: it falsified an
+audit assumption the test suite couldn't.
+
+**Killed by `route-contracts.test.ts` survivor harvests** (170 mutants
+across five passes): RL/BT axis orientation (reciprocal-pair regressions in
+both reversed directions), every `directLaneBlockers` blocker kind at its
+exact ±4px clearance boundary on both axes (non-square obstacles so a
+swapped width/height changes the verdict), own-label lane capacity in
+rendered-pill units, the same-edgeIndex self-exclusion, sub-epsilon
+polyline simplification, the hitch deviation rounding, `findLabelSlot`
+stagger and pill-boundary arithmetic, the primary-over-feedback exemption
+asymmetry, the feedback path of `findRouteHitches`, shared-trunk detection
+on both axes at its collinearity/pill-extent boundaries, the ±2px line
+between the stale and shape-misanchor tripwires, container perimeter
+tolerance, and the container repair's horizontal-gap axis selection.
+
+**Accepted — equivalent on the real input domain** (route-contracts): the
+collinearity cross-product variants in `simplifyPolyline` behave identically
+for the orthogonal polylines ELK produces (several algebraic rearrangements
+preserve the zero/non-zero verdict for axis-aligned triples), and the
+`isMonotoneStaircase` diagonal/backward guards are defensive against passes
+that do not currently exist — real extracted routes are orthogonal and the
+backward case is already excluded by feedback classification upstream.
+
+**Accepted — performance guards** (route-contracts): the `seen`-set and
+stack mechanics inside `classifyRoutes`' DFS change traversal cost, not
+reachability verdicts, on the small graphs flowcharts produce.
+
+**Accepted — bounded-iteration guard** (route-contracts): the fixed-point
+loop's `round < 4` weakenings only change how many re-prove rounds run;
+the duplicate-edge regression pins one unblocking round, while three chained
+rounds were outside the recorded real-input corpus.
+
+**Residual observations from that run** (not scheduled):
+- `directLaneBlockers` label-rect axis ternaries retain a few survivors on
+  rect width/height swaps for near-square pills; the corpus lacked a multi-line
+  (taller than wide) label obstacle.
+- `findLabelSlot`'s rect-overlap conjunction retains sign-variant survivors
+  for rects that only graze on one axis; corner-touching fixtures were absent.
+- The audit's pill-hit prefilter (`hitsPill`) retains inclusive-vs-strict
+  comparison survivors for segments that exactly graze the pill border;
+  they only widen the prefilter the collinearity check still gates.
+- The container repair's reversed-order gaps (target above / left of source)
+  were absent; the recorded classification relied on symmetry with the two
+  covered directions.
+- `grid.ts` `ensureSubgraphSpacing` (~48 survivors): the overlap/min-spacing
+  resolution between root subgraphs is never triggered by the corpus —
+  placement upstream appeared to avoid overlaps, so the run could not
+  distinguish reachable behavior from defensive dead code.
+- `converter.ts` entry/exit attachment roles and phantom still-used checks
+  (`resolveSubgraphEdges` area): rendered-output invariants tolerate several
+  mutants because other mechanisms compensate; the run asserted rendered text,
+  not the intermediate resolved edge structure.
+- `edge-routing.ts` label segment filter (`width >= lenLabel && index > 1 &&
+  orientationMatches`): the labeled-fanout invariants pin the TD vertical-drop
+  case; LR orientation and the index>1 exclusion lack direct coverage.
+
+## Incremental per-PR profile
+
+A fast lane gates the small, pure faithfulness counter on every PR (the
+`mutation-incremental` CI job), separate from the opt-in diagnostic configs. It
+mutates `src/agent/structural-count.ts` (the counter + `faithfulnessWarning` +
+`isDrop`), run by the sub-second `structural-count.test.ts` unit runner. A full
+run is ~1 min, so it runs in full each PR.
+
+The 2026-07-14 post-Radar run scored **97.01%** (130 killed / 134 valid; regenerate to
+confirm, with the report in `reports/mutation/`), gated by
+`thresholds.break: 90`. The retained floor deliberately remains below the
+measured score; this result for one small pure module is not a repository policy
+or a reason to expand mutation scope.
+
+The survivor review found real valid-domain gaps rather than accepting a score:
+the State counter needed both a doubly nested composite and concurrent-region
+fixtures; ER needed a semantic-subgraph fixture and the public empty body with
+its optional `groups` field absent; and `nodes = services + junctions` needed an
+Architecture fixture containing a junction. These cases remain because they
+pin real behavior, not because they improve a metric.
+
+Four survivors are classified rather than killed with invalid inputs or by
+weakening the code's forward-compatibility tripwire:
+
+- two mutations to `case 'opaque': return null` are equivalent because the
+  exhaustive default also returns `null`; and
+- two mutations to the `default` branch are unreachable for the valid
+  discriminated union. Its `const _never: never = body` assignment is retained
+  so adding a family without a count remains a compile-time error.
+
+### Why `verify.ts`'s faithfulness wrapper is NOT in the gated mutate set
+
+Move 2 measured `roundtripFaithfulnessWarnings` (the I/O wrapper around the pure
+`faithfulnessWarning`): **26.67% kill / 11 survivors**. The survivors are all on
+the wrapper's defensive branches — `if (!reparsed.ok) …`, `if (!after) …`, and
+the `catch` — which no *real* diagram exercises: a structured diagram's
+serialization always re-parses, and re-parses structured (not opaque), and never
+throws. Those branches are therefore unkillable through real `verifyMermaid`
+inputs without a synthetic drop, and the *decision logic* they guard already
+lives in `faithfulnessWarning`, which the incremental lane currently measures
+at 97.01%. Adding the wrapper to the gated `mutate` would crater the score to
+~27% and force either
+a meaningless break threshold or a pile of accepted survivors. So the wrapper
+stays out of the gated set and is recorded here as I/O-glue equivalents; its
+logic is covered where it actually lives, where the current measured score is
+97.01%.

package/docs/quality.md

@@ -0,0 +1,224 @@
+# What "good looking" means in Agentic Mermaid
+
+A diagram is considered **good looking** when it satisfies, in order:
+
+1. **All Tier 1 structural checks pass.** No `EMPTY_DIAGRAM`, no
+   `EDGE_MISANCHORED`, no `OFF_CANVAS`, no `GROUP_BREACH`, no
+   `UNKNOWN_SHAPE`, no `LABEL_OVERFLOW` (default cap: 40 chars).
+   This is non-negotiable — fix the source before judging visuals.
+
+2. **Tier 2 geometric checks are within bounds.** `NODE_OVERLAP` count
+   and `ROUTE_SELF_CROSS` count are advisory but not catastrophic. A
+   diagram with a single intentional overlap (e.g., a self-loop) is
+   still considered good. The `ROUTE_*` codes (`ROUTE_HITCH`,
+   `ROUTE_UNEXPLAINED_BEND`, `ROUTE_LABEL_ON_SHARED_TRUNK`,
+   `ROUTE_CONTAINER_MISANCHOR`, `ROUTE_SHAPE_MISANCHOR`,
+   `ROUTE_STALE_AFTER_NODE_MOVE`) should always be zero — they are
+   route-contract tripwires (see `docs/design/system/route-contracts.md`), and
+   any hit means the layout pipeline regressed, not the diagram.
+
+3. **Perceptual metrics fall in the default `QualityBounds` band:**
+
+   | metric | meaning | default |
+   |---|---|---|
+   | `edgeCrossings` | pairs of edge segments that visually intersect | ≤ 5% of edge pairs |
+   | `labelLegibility` | fraction of node labels whose rendered length fits the node width | ≥ 85% |
+   | `whitespaceBalance` | node area ÷ canvas area | 5%–55% (too sparse AND too dense lose) |
+   | `labelEdgeProximity` | min pixel distance between any edge-label box and a non-attached node, another edge-label box, or another edge path (graph families; cross-family label/box occlusion is gated by `eval/overlap-audit` + `label-overlap-gate.test.ts`) | ≥ 4 px |
+   | `minimumNodeSpacing` | nearest gap between semantically distinct node/mark boxes; XY and Radar same-coordinate series adjacency/overlays are excluded | ≥ 8 px |
+   | `elementDensity` | nodes + edges per 10,000 canvas pixels | 0.02–6 |
+   | `minimumTextContrast` | WCAG contrast ratio between foreground and supplied background/surface colors; `null` when a requested paint cannot be resolved | ≥ 4.5:1 |
+   | `aspectRatio` | canvas w/h | 0.2–5.0 |
+
+   These are computed by `measureQuality(layout)` and gated by
+   `checkQuality(layout)`. They are **deterministic** and cheap — they
+   run on every PR.
+
+4. **LLM-as-judge median ≥ 4.0** on the configured stratified sample of the
+   Mermaid-docs corpus across three axes. Since QUAL-1, perceptual metrics and
+   judge sampling cover every registered renderer rather than only graph families:
+   - **Readability** — labels legible, arrows clear, no overlap chaos
+   - **Faithfulness** — every node and edge from the source is present
+   - **Aesthetics** — balanced layout, professional feel
+
+   This is **periodic**, not per-PR (model spend + nondeterminism). It
+   supports pre-release sign-off when explicitly run. See
+   `eval/llm-judge/judge.ts`.
+
+## The rubric (used by both the LLM judge and the perceptual checker)
+
+```
+Rate the rendered Mermaid diagram on three axes, 1 (poor) to 5 (excellent).
+
+1. Readability — Are all labels legible? Do labels overlap nodes or
+   edges? Are edges easy to follow? Are arrows pointing the right way?
+
+2. Faithfulness — Does the rendered diagram represent every node and
+   edge in the source? Any silently dropped content?
+
+3. Aesthetics — Is the layout balanced? Are nodes evenly spaced?
+   Are crossings minimized? Is the overall feel professional?
+
+Output strict JSON: { "readability": N, "faithfulness": N, "aesthetics": N, "notes": ["..."] }
+```
+
+## Why a definition matters
+
+Without one, "looks good" is a vibes-check, and vibes drift. The
+combination above gives:
+
+- **Verifiability** — every claim has a number behind it.
+- **Repeatability** — the metrics are deterministic; layouts don't
+  change between runs (ELK + the verified cross-runtime/cross-process
+  determinism we already prove).
+- **Tractability** — the Tier 1 + perceptual checks run in seconds on
+  any PR. The LLM judge is reserved for explicit pre-release or periodic
+  evaluation runs.
+- **Honest gaps** — `whitespaceBalance` band is rough; aspect-ratio is
+  a sanity check, not an aesthetic. We do not claim our metrics match
+  a human designer's eye — they catch the worst regressions.
+
+## Why the same Mermaid can look worse here than in Mermaid
+
+Agentic Mermaid is not Mermaid's renderer. It parses Mermaid source and
+renders through this project's own layout/style stack: ELK layered layout,
+source-order preservation, conservative node/diamond sizing, and the
+Agentic Mermaid theme system. Mermaid's default flowchart renderer uses
+its own Dagre/ELK configuration, text wrapping, spacing, and CSS. The same
+source can therefore have different rank choices, edge routes, node sizes,
+and aspect ratio.
+
+The Auth Flow regression is the concrete example. Mermaid can choose a more
+compact-looking rendering for the feedback loops; Agentic Mermaid now
+prioritizes semantic LR source order (`A → B → C → ... → H`) and routes
+`No` loops backward. That preserves author intent and avoids the earlier
+misordered layout, but it also makes the diagram wider. `verify.ok` still
+only means structurally valid; visual quality needs layout metrics,
+geometry assertions, screenshot/PNG review, or human inspection.
+
+## What we do NOT claim
+
+- **No universal Mermaid visual parity.** We aim for faithful, deterministic,
+  agent-verifiable output, not pixel/layout equivalence with Mermaid's own
+  renderer. When parity matters, compare rendered artifacts and add a
+  geometry/screenshot regression for that source.
+- **No pixel comparison for the whole corpus.** We render SVGs but don't compare
+  every corpus sample to a golden image. Mermaid-js itself uses an external
+  service (Applitools) for visual regression; we don't ship reference images.
+  If a glyph changes width by one pixel, our perceptual metrics may move
+  slightly, but the bands have headroom.
+- **Perceptual metrics cover every renderable family (QUAL-1).** `layoutMermaid`
+  now has `RenderedLayout` adapters for ALL renderable families, so
+  `measureQuality` / `checkQuality` and the comparison harness see real geometry
+  (not bytes-only) for each. The adapters parse `d.canonicalSource` via the
+  legacy per-family parser + layouter — the same geometry the SVG renderer draws
+  — so an opaque-but-renderable body is still measured; an invalid opaque body
+  degrades to an empty layout instead of throwing. What `nodes` / `edges` /
+  `groups` mean per family:
+
+  | Family        | nodes                              | edges        | groups               |
+  |---------------|------------------------------------|--------------|----------------------|
+  | flowchart     | graph nodes (ELK)                  | graph edges  | subgraphs            |
+  | state         | states (projected to a graph)      | transitions  | composites           |
+  | sequence      | actor boxes                        | messages     | —                    |
+  | timeline      | period + event boxes               | —            | —                    |
+  | class         | class boxes                        | relations    | —                    |
+  | er            | entity boxes                       | relations    | —                    |
+  | journey       | task boxes                         | —            | section frames       |
+  | architecture  | services + junctions               | edges        | groups (flattened)   |
+  | xychart       | bars + line-point markers          | —            | plot area            |
+  | pie           | slice label boxes (legend anchor + approx bbox) | — | —                    |
+  | quadrant      | plotted points                     | —            | quadrant regions     |
+  | gantt         | task bars + milestone diamonds     | —            | section bands        |
+  | mindmap       | hierarchy nodes                    | parent links | —                    |
+  | gitgraph      | commits                            | parent links | —                    |
+  | radar         | curve vertices (one ring per axis) | —            | axis spokes/grid     |
+
+  Families with no structural relations (pie/quadrant/xychart/journey/gantt/radar) carry an
+  honestly-empty `edges` array. Bounds is the family layout's canvas size.
+- **No font-substitution check.** Different OSes render different
+  default fonts. Our `labelLegibility` heuristic uses a 7 px-per-char
+  approximation; under condensed fonts it under-estimates fit.
+- **Contrast needs resolved paints.** `measureQuality(layout)` scores the crisp
+  default palette. For a custom style, pass `{ foreground, background,
+  surfaces }` as its second argument, or pass the actual rendered text/surface
+  associations as `textPairs`. Concrete named, hex, `rgb()`/`rgba()`, and
+  `hsl()`/`hsla()` paints—including alpha and `transparent`—are composited over
+  the supplied background. Any unresolved requested paint makes contrast
+  unmeasurable (`null`), and `checkQuality` reports a violation instead of
+  guessing or passing open. The generated visual-quality characterization reads
+  text and containing-surface paints from the rendered SVG.
+
+## ASCII determinism
+
+Loop 7 added an ASCII determinism guard at
+`src/__tests__/ascii-determinism.test.ts`. It hashes the output of
+`renderMermaidASCII()` over 10 invocations on three multi-edge fixtures
+and asserts a single SHA-256 across all 30 runs per fixture. The probe
+that motivated it (per the Loop 7 plan: "probe FIRST, then act") found
+the existing code already byte-identical across 10 runs — the test
+lands as a regression guard, not a behavior change.
+
+What the guard catches:
+- Any future introduction of `Math.random()` / `Date.now()` /
+  `performance.now()` into an ASCII rendering or pathfinder code path
+  (set size > 1 → fail).
+- Set / Map iteration-order surprises if a code path adopts a hash key
+  whose ordering changes between Bun and Node.
+
+What the guard covers now:
+- **Representative pathfinder fixtures** over 10 invocations.
+- **Full 271-entry mermaid-js docs corpus**: every entry must have a stable
+  ASCII outcome (byte hash or deterministic error) across repeated runs.
+
+What the guard does NOT yet cover:
+- **Cross-architecture byte equality** (x86_64 output hash compared directly
+  to ARM64 output hash from a recorded manifest).
+- **Input-order independence.** The current same-input tests do not
+  stress edge-insertion order. If this becomes release-gating, add a focused
+  property/differential test rather than treating corpus determinism as proof.
+
+## PNG determinism
+
+Loop 8 added PNG export via `@resvg/resvg-js` (pinned exact `2.6.2`,
+napi-rs native build). The rasterizer choice was hardened by the Loop 8
+critic pass:
+
+- `loadSystemFonts: false` is the default — fontconfig differs between
+  OSes and CI images, so system fonts would collapse cross-runtime
+  parity. (`loadSystemFonts: true` / `--system-fonts` is an explicit
+  opt-in for CJK/emoji coverage; determinism is the caller's tradeoff.)
+- Bundled `assets/fonts/Inter-*.ttf` (400/500/600/700) plus
+  `DejaVuSans.ttf` + `-Bold.ttf` ship with the package.
+  `defaultFontFamily: 'Inter'` — the family the SVG requests and the one
+  `src/text-metrics.ts` models, so raster text fits its measured boxes;
+  resvg falls back per-glyph to DejaVu for symbols Inter lacks.
+- SVG input passes `embedFontImport: false` so resvg doesn't fetch
+  Google Fonts at rasterization time. CSS variable `--font` still
+  declares family preference for browser consumers.
+
+What's tested:
+- `agent-png.test.ts` — PNG magic bytes, scale proportionality,
+  ValidDiagram input, and background variation.
+- `agent-png-determinism.test.ts` — repeated same-input SHA-256 stability
+  with a warm-up render to factor out napi initialization differences.
+  Plus length-stable defence against partial-buffer truncation
+  masquerading as a hash collision.
+- `agent-determinism.test.ts` "cross-runtime PNG" — renders in bun,
+  spawns Node on `dist/agent.js`, compares SHA-256 when Node and built `dist/`
+  artifacts are present. In bare `bun test` environments it skips rather than
+  pretending cross-runtime evidence exists. In the full local verification loop
+  after `bun run build`, bun ≡ node on same-machine x86_64 and ARM64 hosts
+  where those runtimes and native resvg are installed.
+
+What's NOT tested (honest gaps):
+- **Cross-architecture byte equality (x86_64 hash compared to ARM64 hash).**
+  The guard verifies Bun ≡ Node on the current machine/architecture, not that
+  two different CPU architectures emit identical PNG bytes to each other.
+- **Resvg version drift.** A future bump of `@resvg/resvg-js` may
+  change PNG bytes (zlib compression, font hinting). The version is
+  pinned exact (no caret) to prevent silent drift on `npm install`,
+  but a deliberate bump needs re-baseline.
+- **Different system fonts.** Bundled Inter (+ DejaVu fallback) is what
+  we render with; consumers post-processing the output font-substituted
+  SVGs will get different pixels. By design.

package/docs/react.md

@@ -0,0 +1,97 @@
+# React integration
+
+Agentic Mermaid renders synchronously to SVG strings, so React apps do not need iframe renderers, hidden browser sessions, or client-side Mermaid hydration.
+
+## Basic component
+
+```tsx
+import { useMemo } from 'react'
+import { renderMermaidSVG } from 'agentic-mermaid'
+
+export function MermaidDiagram({ source }: { source: string }) {
+  const svg = useMemo(
+    () => renderMermaidSVG(source, { security: 'strict' }),
+    [source],
+  )
+
+  return <div className="diagram" dangerouslySetInnerHTML={{ __html: svg }} />
+}
+```
+
+`security: 'strict'` removes external-fetch references and is the safest default for user- or agent-generated diagrams.
+
+## Theme from CSS variables
+
+```tsx
+const svg = renderMermaidSVG(source, {
+  bg: 'var(--diagram-bg)',
+  fg: 'var(--diagram-fg)',
+  accent: 'var(--diagram-accent)',
+  surface: 'var(--diagram-surface)',
+  border: 'var(--diagram-border)',
+  embedFontImport: false,
+})
+```
+
+```css
+.diagram-surface {
+  --diagram-bg: #ffffff;
+  --diagram-fg: #18181b;
+  --diagram-accent: #2563eb;
+  --diagram-surface: #f8fafc;
+  --diagram-border: #cbd5e1;
+}
+
+.dark .diagram-surface {
+  --diagram-bg: #0f172a;
+  --diagram-fg: #f8fafc;
+  --diagram-accent: #38bdf8;
+  --diagram-surface: #1e293b;
+  --diagram-border: #334155;
+}
+```
+
+Because the SVG keeps CSS variables in place, toggling `.dark` updates existing diagrams without re-rendering.
+
+## PNG export button
+
+PNG rendering returns bytes. In browser-oriented React apps, call the PNG helper from a server action/API route or other Node-capable boundary where `@resvg/resvg-js` is available.
+
+```ts
+import { renderMermaidPNG } from 'agentic-mermaid/agent'
+
+export function renderDiagramPng(source: string) {
+  return renderMermaidPNG(source, { fitTo: { width: 1200 }, background: '#fff' })
+}
+```
+
+For client-only exports, use the live editor/browser's existing download path or post the source to a server endpoint.
+
+## Error handling
+
+For untrusted source, parse or verify before rendering:
+
+```tsx
+import { parseRegisteredMermaid, verifyMermaid, renderMermaidSVG } from 'agentic-mermaid/agent'
+
+export function SafeDiagram({ source }: { source: string }) {
+  const result = useMemo(() => {
+    const parsed = parseRegisteredMermaid(source)
+    if (!parsed.ok) return { ok: false, message: parsed.error.map(e => e.message).join('\n') }
+
+    const verify = verifyMermaid(parsed.value)
+    if (!verify.ok) return { ok: false, message: verify.warnings.map(w => w.code).join(', ') }
+
+    return { ok: true, svg: renderMermaidSVG(parsed.value, { security: 'strict' }) }
+  }, [source])
+
+  if (!result.ok) return <pre>{result.message}</pre>
+  return <div dangerouslySetInnerHTML={{ __html: result.svg }} />
+}
+```
+
+## See also
+
+- [`api.md`](./api.md) for render options.
+- [`theming.md`](./theming.md) for palette and CSS-variable details.
+- [`config.md`](./config.md) for Mermaid frontmatter/init support.