agentic-mermaid 0.1.1 → 0.2.0

package/docs/design/system/source-preservation-ladder.md

@@ -1,52 +0,0 @@
-# Source preservation ladder
-
-Status: implemented as the Agentic Mermaid family-adoption contract.
-
-Agentic Mermaid edits source, not just pictures. Every family must declare how
-much source it can model and what happens when it encounters syntax outside the
-modeled subset. Silent loss is never an acceptable level.
-
-## Levels
-
-| Level | Name | Contract |
-|---|---|---|
-| L0 | reject/fail loud | The construct is not safely renderable/editable. Parsing or verification returns a named error/warning; no partial IR is serialized as if it were complete. |
-| L1 | whole-body opaque | The family header is recognized, but the body is preserved byte-for-byte as opaque source. Typed narrowers return `null`; render/verify may use a safe legacy/family parser. |
-| L2 | segment-preserving mixed body | Modeled statements are typed-editable; unmodeled blocks/directives/comments remain in ordered opaque segments and serialize without silent loss. |
-| L3 | canonical structured body | Accepted body syntax is modeled; parse → serialize → parse is stable. Unsupported syntax falls back to L1/L2 or fails loud. |
-| L4 | traceable structured model | L3 plus stable source spans, rendered regions, and action/analysis sidecars for load-bearing semantic objects. |
-
-## Construct policy
-
-| Construct class | Required behavior |
-|---|---|
-| Frontmatter / init directives / leading comments | Preserved in `meta.wrapperSource` and re-emitted verbatim by default; canonical wrapper synthesis is opt-in. |
-| In-body comments | Preserved by opaque bodies; structured bodies must either preserve them or report `COMMENT_DROPPED`. |
-| Unknown family syntax | Use L1 opaque preservation when rendering remains safe; otherwise L0 named failure. |
-| Mermaid v11 `@{ ... }` metadata | Must not create phantom nodes or silently drop targets. Current safety floor preserves opaque/unsupported forms and consumes supported label metadata conservatively. Full typed-shape vocabulary remains separate (#44). |
-| Actions/clicks | Never execute during parse/render/analysis. Preserve source intent and expose source-only metadata where modeled. |
-| Render regions | Stable IDs are required for L4 claims; V1 region coverage may be partial but must be documented and tested. |
-
-## Current family levels
-
-| Family | Body preservation level | L4 traceability status |
-|---|---|---|
-| flowchart | L3 for modeled graph syntax; L1 for unsupported syntax/metadata forms | Partial L4: nodes/edges/groups/labels/source map, route certs, action analysis, region MVP |
-| state | L3 structured body | Partial L4 via graph projection, source map, route certs, region MVP |
-| sequence | L2 segment-preserving structured body | Partial L4: participants/messages layout + lifeline certificates |
-| timeline | L3 structured body with opaque fallback | Partial L4: sections/periods/events layout regions/certs |
-| class | L3 structured body with opaque fallback | Partial L4: classes/members source map, geometry validators, orthogonal-box certs |
-| er | L3 structured body with opaque fallback | Partial L4: entities/attrs/cardinalities source map, geometry validators, orthogonal-box certs |
-| journey | L3 structured body with opaque fallback | Partial L4: sections/tasks regions/source map |
-| architecture | L3 structured body | Partial L4: groups/services/junctions/side-anchored certs |
-| xychart | L3 structured body with opaque fallback | Partial L4: plot/marks/labels source map + containment certs |
-| pie | L3 structured body with opaque fallback | Partial L4: slices/legend source map + containment certs |
-| quadrant | L3 structured body with opaque fallback | Partial L4: quadrants/points source map + containment certs |
-| gantt | L2/L3 structured body with schedule resolver and named schedule errors | Partial L4: sections/tasks source map, schedule analysis, containment certs |
-
-## Reviewer rule
-
-A family may advance levels incrementally, but it may not regress silently. New
-syntax support must add one of: typed modeling, opaque preservation, or a named
-failure with docs/tests. Mutation APIs require L3 for the affected construct;
-agents must verify before serializing.

package/docs/design/system/styles-rollout.md

@@ -1,216 +0,0 @@
-# Styles: the composable look system — naming, model, and rollout plan
-
-Status: v2, largely executed on PR #60 — the engine, the consolidated
-`style` primitive, and the product surfaces (CLI `--style`/`--seed` +
-`am styles`, MCP style args + typed SDK declaration, editor style picker
-with seed re-roll, agent docs) have landed; steps below are annotated.
-Nothing has shipped to npm yet, so remaining decisions stay free.
-
-The engine work is done: every diagram family lowers to a SceneGraph of
-semantic marks, and pluggable backends serialize those marks — crisp (the
-unchanged default), rough.js sketch, and hybrid (pressure ribbons, washes).
-
-**The headline is what users and their agents can construct, not what we
-ship.** The built-in looks are proof and raw material: the original sketch
-set (hand-drawn, excalidraw, pen-and-ink, freehand, watercolor, blueprint,
-tufte) plus coverage expanders for accessibility, print, operations,
-physical media, architecture, and editorial/report figures. The product is
-a small set of primitives with one combination rule, from which looks we
-never anticipated can emerge.
-
----
-
-## 1. One concept: style. A theme is a kind of style.
-
-The repo used to have three overlapping vocabularies: *themes* (the
-`THEMES` palette record + `themeVariables` + color options), early private
-role-face experiments, and the pre-consolidation *aesthetics*. Multiple words,
-shapes, and precedence stories answered one question: **how should this diagram look?**
-
-We collapse them into one primitive:
-
-> A **style** is a partial description of how diagrams look. Every field is
-> optional. A style that only sets colors is a palette. A style that sets
-> stroke character, fills, typography, and a palette is a full look.
-
-```ts
-interface StyleSpec {
-  // identity (optional — anonymous inline styles are fine)
-  name?: string
-  blurb?: string
-
-  // palette — the seven tokens every mark references
-  colors?: { bg?; fg?; line?; accent?; muted?; surface?; border? }
-
-  // typography
-  font?: string
-
-  // mark treatment (what the sketch backends read)
-  stroke?: 'crisp' | 'jittered' | 'freehand'
-  fill?: 'none' | 'hachure' | 'solid' | 'wash'
-  roughness?; bowing?; passes?; strokeWidth?; hachureAngle?; hachureGap?;
-  fillWeight?; washOpacity?; washEdge?
-  backdrop?: 'plain' | 'paper-ruled' | 'grid'
-
-  // advisory metadata (documented, never read by the engine)
-  intent?: 'premium' | 'draft' | 'lofi'
-  mono?: boolean
-}
-```
-
-So the answer to "what is the right relationship between styles and themes"
-is: **subsumption, not orthogonality**. A theme is a palette-only style.
-The existing `THEMES` entries register into the style registry at startup
-(their names keep working everywhere a style name is accepted), and
-`themeVariables`/color options remain as the *last* override layer for
-Mermaid compatibility. One registry, one lookup (`getStyle`), one list
-(`knownStyles`) — and the docs answer the theme question in a sentence
-instead of a precedence table.
-
-## 2. One combination rule: the stack
-
-The public option takes a name, a spec, or a **stack** of them:
-
-```ts
-interface RenderOptions {
-  style?: StyleInput | StyleInput[]   // StyleInput = string | StyleSpec
-  seed?: number                        // re-rolls ink wobble, never layout
-}
-
-// a full look
-renderMermaidSVG(src, { style: 'hand-drawn' })
-
-// hand-drawn geometry × dracula palette — "any style × any theme" is just stacking
-renderMermaidSVG(src, { style: ['hand-drawn', 'dracula'] })
-
-// stack a shared brand fragment and a local tweak on top
-renderMermaidSVG(src, { style: ['hand-drawn', acmeBrand, { colors: { accent: '#e11d48' } }] })
-```
-
-Merging is left→right, per field — the CSS intuition everyone already has.
-The full precedence story becomes one line:
-
-```
-defaults  <  style stack (left → right)  <  themeVariables  <  explicit color options
-```
-
-This one rule replaces separate theme/style/variant parameters. It is also the
-agent-native shape: an agent composes a look by concatenating fragments it
-was given, retrieved, or wrote itself.
-
-## 3. Simplifications this unlocks (missed in plan v1)
-
-1. **No `backend` field for authors.** Which backend a style needs is
-   derivable from what it asks for: `stroke: 'freehand'` or `fill: 'wash'`
-   ⇒ hybrid; any rough parameter or `stroke: 'jittered'` ⇒ rough; otherwise
-   ⇒ default. Authors describe the *look*; the engine picks the machinery.
-   (An explicit `backend` override remains for code-backed extensions, but
-   it disappears from the tutorial path.)
-2. **No aesthetic/style/theme triage.** One word in the API, the CLI, the
-   MCP schema, the docs. `THEMES` stays exported for compatibility of
-   in-repo code but is defined *as* registered palette-only styles.
-3. **No compatibility shims anywhere** — pre-release, the in-repo callers
-   of the old option just update.
-4. **`intent`/`mono` demote to advisory metadata.** The engine never
-   branches on them; they exist for pickers, galleries, and the authoring
-   rubric. (The mono *contract* stays a test on built-ins, not an engine
-   switch.)
-5. **One registry, one gallery.** `knownStyles()` drives the CLI list, the
-   editor picker, and the poster harness — registering a style is the only
-   step to appear in all three.
-6. **Fragments are the sharing unit.** A JSON file with three fields is a
-   complete, valid, shareable style. Packs are just arrays of named
-   fragments — no schemaVersion ceremony until a real need appears.
-
-## 4. Designed for emergence
-
-Following the "design for emergence" argument (UX Mag): when user needs are
-heterogeneous and unpredictable — and custom looks are exactly that — ship
-simple elements and combination rules, not finished solutions; keep the
-floor low, the ceiling high, and the walls wide.
-
-- **Low floor**: `style: 'hand-drawn'` — one string.
-- **Wide walls**: fragments compose across axes we don't enumerate. A
-  palette fragment × a line-character fragment × a typography fragment — we
-  ship full looks, but the space users can reach is
-  the product of every fragment anyone writes. Nobody designs "corporate
-  memo hand-drawn dark"; it emerges from a stack.
-- **High ceiling**: `registerBackend` + the SceneGraph types for the rare
-  code-backed capability (a new fill algorithm, a layout-aware dialect).
-  Styles stay data; code is the escape hatch, not the path.
-- **Safety rails that make wild combinations viable**: the prototype WCAG
-  contrast audit and text-halo policy showed the right contract. Production
-  now has deterministic stacking and built-in looks that route structural
-  ink through the active theme foreground; a full arbitrary-stack WCAG gate
-  remains the missing guardrail.
-- **Reproducible sharing**: determinism means `(source, stack, seed)` is a
-  complete, portable description of an image. A gist with a JSON fragment
-  IS the artifact. This is the hashtag/spreadsheet property: the unit of
-  user invention is trivially copyable.
-- **Agents as the emergence engine**: `docs/style-authoring.md` (spec
-  template + quality rubric + worked good/bad examples) is linked from
-  `llms.txt` and the agent instructions, so an agent can author a fragment
-  from a sentence ("make it look like our brand deck"), render it, check
-  contrast, and iterate — the loop that produced the 31-style prototype,
-  now available to every user's agent.
-- **Deliberately not built** (over-specification kills emergence): no
-  inheritance/`extends` graphs (stacking covers it), no per-diagram-family
-  style hooks in v1, no marketplace/registry service — a JSON fragment in
-  a repo is the distribution mechanism until the community proves a need.
-
-## 5. npm package changes
-
-First release ships as `agentic-mermaid` **0.x minor** (crisp default
-byte-identical, corpus-gated):
-
-- **API**: `RenderOptions.style` (name | spec | stack), `RenderOptions.seed`,
-  `registerStyle`, `getStyle`, `knownStyles`, `validateStyleSpec` (JSON
-  schema included in the package), and for extensions `registerBackend`,
-  `StyleBackend`, plus SceneGraph types (`SceneDoc`, `SceneNode`,
-  `SemanticChannels`, `SceneRole`). `THEMES` remains, redefined as
-  palette-only styles.
-- **Runtime dependencies**: `roughjs@4.6.6` and `perfect-freehand@1.2.3`,
-  pinned exactly — seeded geometry must not shift under a bump; a bump is a
-  golden-fixture change (`[approve-goldens]`). They are `dependencies`
-  because the `bun` export condition resolves raw `src/*.ts`; the Node dist
-  bundles them (~80 KB minified). A `agentic-mermaid/styles` subpath split
-  is the escape hatch if crisp-only weight ever matters.
-- **Docs in the box**: README leads with the matrix image, a one-string
-  quick start, and a *custom fragment stack* example; `docs/api.md` gets the
-  option + precedence line; CHANGELOG states the model in three sentences.
-- **Deferred**: styled PNG parity (blocked on bundling the OFL faces as
-  reviewed production assets — notices already exist); CLI/MCP surfaces
-  land in the rollout below.
-
-## 6. Rollout, emergence-first
-
-1. **Collapse the primitives**: rename `aesthetic` → `style`; make all
-   `StyleSpec` fields optional; implement the stack merge; register `THEMES`
-   as styles; infer backends. (Everything else builds on the final shape.)
-   *Status: DONE — resolveStyleStack / inferBackend / validateStyleSpec in
-   src/scene/style-registry.ts; RenderOptions.style is the union; public
-   role-key objects were removed before launch.*
-2. **Agent surface**: MCP render tool + SDK declaration accept `style`
-   (name | spec | stack) and `seed`; authoring guide linked for agents.
-3. **CLI**: `am render --style <name|file.json>` (repeatable = stack),
-   `--seed`, `am styles [--json]`; PNG threading with an explicit
-   font-fallback warning.
-4. **Editor**: style picker and palette picker for built-in looks; `seed` stays
-   an API/CLI/share-link field rather than a persistent topbar control.
-5. **README + gallery** generated from the registry.
-6. **Fonts for PNG parity** (OFL faces as reviewed assets).
-
-## 7. How we explain it
-
-- One sentence: *"A style is a small data record describing how diagrams
-  look; stack styles to combine them — a color-only style is a theme."*
-- Crisp stays the default, stated with receipts (corpus-verified byte
-  identity), and styling covers **all 12 diagram types uniformly**.
-- Three promises for the supported path: **readable** built-in stacks
-  (halos, theme-friendly structural ink, and generated evidence),
-  **deterministic** (`seed` shuffles ink, never layout — cacheable,
-  diffable, golden-testable), **portable** (a JSON fragment + seed
-  reproduces the image anywhere). A full WCAG gate for arbitrary user
-  fragments is still a follow-up.
-- The README example is a custom fragment stack, not a built-in name —
-  the message *is* the primary value.

package/docs/design/system/ugly-layouts.md

@@ -1,119 +0,0 @@
-# What Makes a Layout Ugly
-
-This document states the working definition of an *ugly* diagram layout that
-this project has converged on, and maps each defect to a detector. It is the
-specification for `eval/ugly-detector/` (which audits **rendered** output —
-SVG, PNG, ASCII — not just the internal geometry the rubric checks).
-
-## The one-line definition
-
-> **A layout is ugly when an edge's geometry isn't forced by the node
-> positions** — when it bends, floats, splays, crosses, or breaks symmetry in
-> a way a clearer alternative would avoid for the *same* layout. Every bend,
-> offset, and asymmetry should be the cheapest one the node positions allow,
-> or it shouldn't be there. Ugliness is **unexplained geometry**.
-
-## The defects (and how we detect them)
-
-Grouped by the layer they live in. The first group are **hard** — they must
-never appear in a finished render. The second are **soft** — present in good
-layouts only when forced, and ranked below.
-
-### Hard defects (a finished render must have zero)
-
-| Defect | What it looks like | Detector |
-|---|---|---|
-| **Diagonal segment** | an edge segment that is neither horizontal nor vertical, in an orthogonal drawing | segment with `|dx| > ε` AND `|dy| > ε` |
-| **Edge through a node** | an edge crossing a node's interior (occlusion) | segment intersects a non-endpoint node's body deeper than stroke width |
-| **Floating endpoint** | an edge ending at an arbitrary point on the outline, not a designated connection point | endpoint not within tolerance of the shape's outline / a designated port |
-| **Node overlap** | two node bodies overlapping | bbox/footprint intersection |
-| **Hitch / dogleg** | a short perpendicular jog on a run whose lane is clear | a segment much shorter than its collinear neighbours, perpendicular, with a clear straight alternative |
-| **Label off its route** | a label pill sitting away from the edge it names | label centroid far from its edge's polyline |
-
-### Soft ranking (good layouts minimize these, in this priority order)
-
-The operative priority, distilled from Purchase 1997/2002 and Ware 2002 and
-from the choices made across this project:
-
-1. **Straightness / continuity** — fewest bends; a multi-edge path reads as a
-   line. (Beats everything below.)
-2. **Designated-port attachment** — endpoints sit on a *named*, deterministic
-   connection point, not a target-determined float. **Subtlety we encode:**
-   straightness normally beats port-exactness (the strict-ports experiment was
-   measured and rejected), *except* when a designated port is reachable
-   **without costing a bend** — then take it. The diamond 8-port model exists
-   precisely to make E/F/G/K port-exact *and* straight/symmetric at once.
-3. **Symmetry / balance** — where the structure is symmetric (peer fan-ins,
-   reciprocal pairs), the drawing should be too: a centered hub, two equal
-   parallel lines, no peer privileged over another.
-4. **Fewest bends and crossings** — after the above.
-
-### Specific ugly shapes we have named
-
-- **Cramming at a sharp point** — two lines crowded onto a vertex when they
-  could be spread (the ±6 reciprocal-on-a-diamond-tip, before facet-mids).
-- **Pinch-then-splay / hourglass** — edges converging to a narrow pair of ports
-  then fanning back out to wider targets (the rejected F facet-mid+bend).
-- **A line through a shape's body** — routing the short way *through* a node
-  instead of around it (the rejected G facet-mid prototype).
-- **Asymmetry where symmetry is natural** — a fan-in hub stuck at the top of
-  its sources, or a reciprocal pair of unequal lengths.
-
-## Why detect from rendered output (not just geometry)
-
-The `assessLayout` rubric (`src/layout-rubric.ts`) checks the **internal
-geometry** (`PositionedGraph`). The ugly-detector checks the **rendered
-artifact** — the SVG/PNG/ASCII a consumer actually sees — so it:
-
-1. catches rendering bugs where clean geometry renders wrong;
-2. works on *any* diagram, including external SVGs and golden fixtures not
-   produced by our layout pass;
-3. validates the ASCII pipeline, which is a separate renderer that never sees
-   the `RouteCertificate` contracts.
-
-The three formats degrade in fidelity: **SVG** is the authoritative analysis
-(vector paths + shape geometry are recoverable exactly); **PNG** is a faithful
-raster of an SVG, so its check is "analyze the source SVG, plus a coarse
-pixel-orthogonality sanity pass"; **ASCII** is a glyph grid, so detection is
-limited to what the grid reveals (diagonal line glyphs, edge glyphs inside a
-box interior).
-
-## Running the audit
-
-```
-bun run audit:ugly                # render every corpus to SVG/PNG/ASCII, report
-bun run audit:ugly -- --verbose   # also list soft findings
-bun run audit:ugly -- --json      # machine-readable report
-```
-
-The runner (`eval/ugly-detector/audit.ts`) renders every diagram corpus in the
-project — the contact-sheet scenarios, the heuristic-tracker examples, the
-site samples, the layout-compare fixtures, and the ASCII/Unicode golden
-fixture sources — to all three formats and runs the detectors. It exits
-non-zero if any **hard** finding is present, so it doubles as a CI gate.
-`src/__tests__/ugly-detector.test.ts` pins the detector's behavior.
-
-### What the audit found (2026-06)
-
-Current result on PR #30 after the nested-subgraph route fixes:
-
-```text
-338 diagrams / 1009 format-audits
-0 hard layout defects
-0 soft layout findings
-6 render/corpus errors
-```
-
-The non-clean entries are **render errors** (a diagram type or config header a
-given renderer rejects), not layout defects, and are bucketed as such.
-
-Historical note: an earlier audit found one real hard defect — a
-cross-hierarchy edge into a nested subgraph missing the containing subgraph's
-offset. That is now fixed by hosting cross-hierarchy edges at their lowest
-common compound and by treating subgraph IDs as container endpoints; the
-regressions live in `src/__tests__/subgraph-direction.test.ts`.
-
-Two findings the audit initially raised were **detector** false positives, now
-fixed and regression-tested: a cylinder's footprint must union its cap ellipses
-(not just the body rect), and a sub-pixel endpoint jog within the curved-shape
-clip floor (~1.5px) is not a visible dogleg.

package/docs/layout-characterization/README.md

@@ -1,245 +0,0 @@
-# Characterising the layout system
-
-This folder bootstraps a **characterisation-test** suite for the layout
-algorithm, in the sense of
-[adewale/testing-best-practices](https://github.com/adewale/testing-best-practices):
-pin what the code does today, with worked examples + property-based tests, so
-the algorithm can be refactored safely and improved deliberately.
-
-It contains three layers — a **deep** characterisation of the flowchart/state
-grid engine, a **breadth** layer spanning every renderer, and a **visual-quality**
-approval layer for reviewable layout drift:
-
-| File | What it is |
-|------|------------|
-| [`contact-sheet.md`](./contact-sheet.md) | **Depth** — the minimum set of worked examples that exercise every load-bearing decision in the grid engine. One phenomenon per example. (Generated by `scripts/characterization/contact-sheet.ts`.) |
-| [`properties.md`](./properties.md) | **Depth** — the smallest load-bearing set of properties for the grid engine, with a minimality (mutation-kill) argument and academic grounding. |
-| [`../../src/__tests__/characterization-layout.test.ts`](../../src/__tests__/characterization-layout.test.ts) | **Depth** — those properties as executable `fast-check` tests (13 tests). |
-| [`contact-sheet-families.md`](./contact-sheet-families.md) | **Breadth** — one canonical example per renderer (all 12 families) + the universal-invariant coverage matrix. (Generated by `scripts/characterization/contact-sheet-families.ts`.) |
-| [`../../src/__tests__/characterization-families.test.ts`](../../src/__tests__/characterization-families.test.ts) | **Breadth** — the universal invariants extended across every family and public output surface, asserting only what holds per family (17 tests). |
-| [`visual-quality.md`](./visual-quality.md) | **Visual approval** — SVG snapshots, SVG/PNG fingerprints, and advisory graph-drawing metrics for all 12 families. (Generated by `scripts/characterization/visual-quality.ts`.) |
-| [`../../src/__tests__/characterization-generated-artifacts.test.ts`](../../src/__tests__/characterization-generated-artifacts.test.ts) | **Drift check** — fails when generated contact sheets, visual report, or SVG snapshots are stale. |
-
-No implementation code was changed to produce any of this.
-
-## Visual testing rule
-
-Snapshots and contact sheets are approval evidence, not the whole oracle. When a
-bug report says something **looks** wrong, add at least one executable visual
-contract that would fail before updating any golden file. Pick the cheapest
-contract that observes the thing users actually see:
-
-| Visual risk | Preferred contract | Examples |
-|-------------|--------------------|----------|
-| Route geometry, ports, label lanes, overlaps | Geometry/rubric invariant over positioned layout | `route-contracts*.test.ts`, `layout-rubric.test.ts`, `contact-sheet.test.ts` hard metrics |
-| Effective color, stroke thickness, blank/collapsed render, visible endpoint glyphs | Raster invariant with `@resvg/resvg-js` pixels | `visual-rendering-contracts.test.ts`, `helpers/raster.ts` |
-| ASCII/Unicode line style or marker placement | Row/region assertion on the rendered character grid | `ascii-edge-styles.test.ts` connector-row contracts |
-| Broad family drift that needs human judgement | Golden/snapshot/contact sheet after an invariant already guards the principle | `visual-quality.md`, `visual-snapshots/*.svg`, PR screenshots |
-| Parser, escaping, config, IDs, public API shape | Structural/string assertion | Parser/security/integration tests |
-
-The red-green loop for visual work is:
-
-1. Reproduce the bad rendering with the smallest diagram that shows the fault.
-2. Encode the visual principle as geometry, raster, or row-level evidence.
-3. Prove the test is sensitive: where practical, simulate the old behaviour or
-   run a temporary source-level sabotage before trusting the green run.
-4. Fix the implementation.
-5. Regenerate approval artifacts only after the invariant test passes and the
-   visual diff has been reviewed.
-
-## Relationship to PR 30
-
-PR 30 changed the right baseline for layout characterisation. It introduced the
-route-contract layer (`src/route-contracts.ts`), the deterministic graph-drawing
-rubric (`src/layout-rubric.ts`), route/contact-sheet gates
-(`src/__tests__/contact-sheet.test.ts`, `src/__tests__/layout-rubric.test.ts`),
-and the heuristic tracker (`eval/heuristic-tracker/`). Those tests now own the
-question "is this flowchart/state/architecture route geometrically valid and
-free of hitches, stale certificates, off-outline endpoints, and label-route
-ambiguity?"
-
-This directory owns a different question: "what observable layout behaviour did
-we approve, and did it drift deliberately?" After rebasing this PR over PR 30,
-`bun run characterization:check` reported only the visual-quality report plus
-the flowchart/state SVG snapshots as stale. That is the intended signal:
-flowchart/state are exactly the families PR 30's route-contract work should
-move, while the other renderer-family snapshots stayed unchanged. The correct
-course is therefore to approve the new flowchart/state baselines after the PR 30
-route gates pass, rather than add duplicate route-contract assertions here.
-
-For future layout changes:
-
-| If this changes | Use this gate | Review action |
-|-----------------|---------------|---------------|
-| Flowchart/state/architecture routing geometry | `bun test src/__tests__/contact-sheet.test.ts src/__tests__/layout-rubric.test.ts` and `bun run track` | Hard rubric violations must stay zero; baseline deltas must be explained as improvement or intended drift. |
-| Generated characterisation artifacts | `bun run characterization:check` | Regenerate the contact sheets / visual snapshots only after reviewing the visual diff. |
-| ASCII grid mechanics | `bun test src/__tests__/characterization-layout.test.ts` plus `bun run mutation-test:characterization` | Update P-properties only when the algorithm deliberately changes. |
-| Renderer-family dispatch/output surfaces | `bun test src/__tests__/characterization-families.test.ts` | Drift outside the PR's claimed layout surface is suspicious and needs a separate explanation. |
-
-## Coverage across renderers
-
-The **depth** layer targets the flowchart + `stateDiagram-v2` family (the
-hand-written grid + A\* engine — see next section for why). The **breadth** layer
-extends the universal invariants to every diagram family and public output
-surface: text (`renderMermaidASCII`), SVG (`renderMermaidSVG`), and PNG
-(`renderMermaidPNG`, which rasterizes the SVG path). It asserts only what is
-empirically true for each:
-
-| Invariant | Holds for |
-|-----------|-----------|
-| Dispatch totality (non-empty text/SVG and valid PNG signature) | **every** family and public output surface |
-| Sentinel label conservation | **every** family on text/SVG surfaces |
-| Determinism (byte-identical) | **every** family on text/SVG/PNG matrix cases (also pinned corpus-wide for ASCII by `ascii-determinism.test.ts`) |
-| Output hygiene (no `NaN` / `Infinity` / `undefined`, no ANSI when color is disabled) | **every** family on text/SVG surfaces |
-| No diagonals | **every** family on text output (xychart plots with block glyphs, not `/\`) |
-| Rectangular canvas (all rows one width) | box/graph families only: flowchart, state, sequence, class, er |
-| Layered placement, non-overlap, round-trip (P5–P10) | flowchart/state grid engine only |
-
-The chart, list, schedule, and architecture families (timeline, journey, xychart,
-pie, quadrant, gantt, architecture) emit ragged rows by design, so rectangularity is **not**
-asserted there — and that boundary is pinned as a known limit. The deep
-structural and layering properties are specific to the grid engine and do not
-generalise; each non-grid family has its own layout strategy (documented in
-`contact-sheet-families.md`) whose deep per-family invariants are the natural
-next increment.
-
-The visual-quality layer deliberately sits beside, not inside, the minimal
-property kernel. It records SVG snapshots, PNG hashes, crossings, bends, route
-length, area fill, label fit, and edge-label overlap risk for one canonical case
-per family. Those values are approval signals: a diff should be inspected and
-approved, not automatically interpreted as a semantic bug. PR 30's rubric is the
-hard correctness oracle for route-contract families; these snapshots are the
-cross-family drift ledger.
-
----
-
-## What "the layout algorithm" means here
-
-This project has **two** distinct layout engines:
-
-1. **ELK-based engine** (`src/layout-engine.ts`) — wraps Eclipse Layout Kernel's
-   *layered* (Sugiyama) algorithm to produce pixel coordinates for **SVG/PNG**.
-   The placement is a configured third-party black box; the bespoke part is the
-   post-processing (layer snapping, edge bundling, margin routing, shape
-   clipping).
-2. **ASCII grid engine** (`src/ascii/grid.ts` + `pathfinder.ts` +
-   `edge-routing.ts` + `edge-bundling.ts`) — a **hand-written** grid layout with
-   **A\* orthogonal edge routing** that renders flowcharts and state diagrams as
-   character art. It is a TypeScript port and extension of
-   [`AlexanderGrooff/mermaid-ascii`](https://github.com/AlexanderGrooff/mermaid-ascii).
-
-**This characterisation targets the ASCII grid engine.** It is the genuinely
-"ours" algorithm (the ELK one delegates placement), it is pure / synchronous /
-deterministic / dependency-free, and it is the surface the project already
-mutation-tests (`stryker.ascii.config.json`). It is therefore the ideal
-characterisation subject. The flowchart and `stateDiagram-v2` families share
-this exact pipeline (`src/ascii/index.ts`); the other families (sequence, class,
-ER, pie, quadrant, xychart, timeline, journey, architecture) have their own
-renderers and are out of scope here.
-
-### The pipeline in one line
-
-```
-parseMermaid → convertToAsciiGraph → createMapping (grid + A*) → drawGraph → canvasToString
-```
-
-`createMapping` (`grid.ts`) is the heart: it places each node as a **3×3 grid
-block**, assigns layers along the flow axis with a **stride of 4**, routes every
-edge with a **bounded, deterministic A\***, and bundles fan-in/fan-out edges onto
-shared trunks.
-
----
-
-## How the layout works (the load-bearing mechanics)
-
-- **Grid model.** Every node owns a 3×3 block of an integer grid; `gridCoord` is
-  its top-left cell, and the eight surrounding cells are edge attachment points.
-  Blocks are placed 4 grid units apart (3 cells + a 1-cell routing gutter).
-- **Layer assignment.** Roots (nodes with no incoming edge) go at level 0;
-  each child is placed one level (stride 4) along the **flow axis** (y for
-  TD/BT, x for LR/RL). TD and LR are the same code with x/y transposed; **BT =
-  TD then vertical flip**; **RL is currently treated as LR**.
-- **A\* routing.** Edges are routed cell-by-cell with A\* over the same grid that
-  tracks node occupancy. Moves are 4-directional only (⇒ **orthogonal**, no
-  diagonals); the heuristic is Manhattan distance + a corner penalty (prefers
-  straight runs); ties break FIFO (⇒ **deterministic**); the search is bounded
-  (⇒ **terminates**, returns `null` + a straight fallback if walled off).
-- **Edge bundling.** Sibling fan-out / fan-in edges of the same style merge onto
-  a single shared trunk that splits at one junction; labelled siblings (which
-  can't bundle) share a trunk prefix instead.
-- **Best-effort, not a solver.** For cyclic / dense graphs the multi-pass
-  placement can drop or overlap nodes. That limitation is real, current, and
-  pinned by property **P10** rather than hidden.
-
-A fuller mechanical anatomy (with `file:line` citations for all 30+ invariants)
-informed `properties.md`; the citations are inlined there.
-
----
-
-## How this connects to the testing literature
-
-- **Characterisation tests** (Feathers, *WELC* ch. 13): tests that document the
-  system's *actual* behaviour, not its intended behaviour — the safety net for
-  refactoring. The contact sheet is the worked-example form; the property suite
-  is the generalised form.
-- **Approval / golden tests** (Falco): the contact sheet is generated and
-  reviewed as a diff — a surprising change is a regression, an expected change
-  is the new approved baseline. The repo's `src/__tests__/testdata/` corpus is
-  the byte-level golden layer beneath it.
-- **Property-based testing** (fast-check): the kernel asserts **invariants** and
-  **metamorphic relations** rather than exact outputs, so it generalises across
-  thousands of generated graphs instead of a handful of fixtures.
-- **Mutation testing** (Stryker, already configured): the oracle for *which*
-  properties are load-bearing — a property is kept only if it kills a mutant no
-  other test kills. See the minimality argument in `properties.md`.
-- **Visual approval / metric drift:** `visual-quality.md` keeps the literature's
-  aesthetic objectives visible (crossings, bends, area, label overlap) without
-  turning them into brittle universal laws.
-
-Together: **goldens characterise, properties generalise, mutation proves which
-assertions do work, visual snapshots make quality drift reviewable.**
-
----
-
-## Reproduce
-
-```bash
-bun install
-
-# Executable characterisation kernels
-bun test src/__tests__/characterization-layout.test.ts     # grid engine (depth)
-bun test src/__tests__/characterization-families.test.ts   # all families (breadth)
-bun test src/__tests__/characterization-generated-artifacts.test.ts
-
-# Regenerate the contact sheets / visual report, then review the diff and commit
-bun run scripts/characterization/contact-sheet.ts
-bun run scripts/characterization/contact-sheet-families.ts
-bun run scripts/characterization/visual-quality.ts
-git diff docs/layout-characterization/
-
-# CI-friendly generated-artifact drift check
-bun run characterization:check
-
-# Route-contract correctness gates introduced by PR 30
-bun test src/__tests__/contact-sheet.test.ts src/__tests__/layout-rubric.test.ts
-bun run track
-
-# (optional) quick mutation evidence for the load-bearing ranges
-bun run mutation-test:characterization
-
-# exhaustive but slow: mutates the whole ASCII layout core
-bun run mutation-test:ascii
-```
-
-## Sources
-
-Layered graph drawing: Sugiyama–Tagawa–Toda (1981); Gansner–Koutsofios–North–Vo
-(1993, the `dot` algorithm, <https://www.graphviz.org/documentation/TSE93.pdf>);
-Brandes–Köpf (2002). A\*: Hart–Nilsson–Raphael (1968). Orthogonal routing:
-Tamassia (1987); Wybrow–Marriott–Stuckey (2009),
-<https://users.monash.edu/~mwybrow/papers/wybrow-gd-2009.pdf>. ELK:
-<https://eclipse.dev/elk/>. ASCII prior art: mermaid-ascii
-(<https://github.com/AlexanderGrooff/mermaid-ascii>), Graph::Easy. Testing:
-Feathers, *Working Effectively with Legacy Code* (2004); Falco, ApprovalTests
-(<https://approvaltests.com/>); Bartocci et al., property-based mutation testing
-(2023, <https://arxiv.org/pdf/2301.13615>).