agentic-mermaid 0.1.0 → 0.1.2

package/docs/ascii.md

@@ -1,103 +0,0 @@
-# ASCII and terminal output
-
-Agentic Mermaid can render Mermaid diagrams as terminal text. Unicode box drawing is the default; 7-bit ASCII is available for logs, email, CI output, and constrained terminals.
-
-## Quick start
-
-```ts
-import { renderMermaidASCII } from 'agentic-mermaid/agent'
-
-const unicode = renderMermaidASCII(`flowchart LR
-  API --> DB`)
-const ascii = renderMermaidASCII(`flowchart LR
-  API --> DB`, { useAscii: true })
-```
-
-CLI:
-
-```bash
-am render diagram.mmd --format ascii
-am render diagram.mmd --format unicode
-```
-
-## Options
-
-```ts
-renderMermaidASCII(source, {
-  useAscii: true,
-  paddingX: 4,
-  paddingY: 2,
-  boxBorderPadding: 1,
-  colorMode: 'none',
-})
-```
-
-| Option | Type | Default | Meaning |
-|---|---|---:|---|
-| `useAscii` | `boolean` | `false` | Use `+`, `-`, `|` instead of Unicode box drawing. |
-| `paddingX` | `number` | `5` | Horizontal spacing between boxes. |
-| `paddingY` | `number` | `5` | Vertical spacing between layers. |
-| `boxBorderPadding` | `number` | `1` | Padding inside node boxes. |
-| `colorMode` | `string` | `'auto'` | `'none'`, `'auto'`, `'ansi16'`, `'ansi256'`, `'truecolor'`, or `'html'`. |
-| `theme` | `Partial<AsciiTheme>` | — | Override terminal colors. |
-| `mermaidConfig` | `MermaidRuntimeConfig` | — | Mermaid-style runtime config. |
-
-## ASCII with metadata
-
-Agents and TUIs can use `renderMermaidASCIIWithMeta` to map terminal cells back to diagram regions:
-
-```ts
-import { renderMermaidASCIIWithMeta } from 'agentic-mermaid/agent'
-
-const { ascii, regions, warnings, routeParity } = renderMermaidASCIIWithMeta(source)
-```
-
-`regions` includes best-effort terminal spans for load-bearing node labels, edge labels where mapped, participant/task/chart labels, and subgraph label spans suitable for click mapping. It is not a full cell-by-cell box/edge hit-test tree yet. `routeParity` is an explicit V1 contract: ASCII/Unicode does not consume SVG route certificates directly; the converter seeds edges with shared `classifyRoutes()` route intent and the grid router maps that intent into terminal placement/routing. `warnings` reports structured degradation such as `ASCII_EDGE_REGION_UNMAPPED` when edge cell spans are not instrumented even though route drawing still follows the parity mapping.
-
-## Reversing simple flowcharts
-
-```ts
-import { asciiToMermaid } from 'agentic-mermaid/agent'
-
-const result = asciiToMermaid(ascii)
-if (result.ok) {
-  const source = result.value // reconstructed Mermaid source
-}
-```
-
-`asciiToMermaid` returns a `Result<string, ParseError[]>`: `result.value` holds the
-Mermaid source on success, and `result.error` lists parse errors (e.g. `NO_BOXES`)
-otherwise. This is best-effort and lossy. It is useful for simple linear flowcharts,
-not for reconstructing arbitrary Mermaid source.
-
-## Supported families
-
-ASCII/Unicode output is available from the public entrypoints for:
-
-- flowchart/state
-- sequence
-- class
-- ER
-- timeline
-- journey
-- XY chart
-- architecture
-- pie
-- quadrant
-- gantt
-
-PNG output is separate: use `renderMermaidPNG(source)` or `am render --format png --output file.png` when a raster artifact is required.
-
-## XY charts
-
-XY charts render to a compact terminal plot:
-
-```ts
-const chart = renderMermaidASCII(`xychart-beta
-  title "Latency"
-  x-axis [p50, p95, p99]
-  y-axis "ms" 0 --> 500
-  line [50, 180, 420]`)
-```
-
-Use SVG or PNG for publication-quality chart artifacts; use ASCII/Unicode for terminal summaries and agent-visible evidence.

package/docs/comparison.md

@@ -1,94 +0,0 @@
-# Mermaid, Beautiful Mermaid, and Agentic Mermaid
-
-Use this page to decide which of the three projects fits your task. The
-table maps what each one can do; the sections after it name what only each
-one does, and the final section tells you which to install for common jobs.
-
-- **[Mermaid](https://github.com/mermaid-js/mermaid)** (`mermaid`) is the
-  original. It defines the grammar that both other projects implement,
-  supports roughly 25 diagram types, and is rendered natively by GitHub,
-  GitLab, Notion, and Obsidian — which is why most diagrams-as-text you will
-  encounter are written in its language.
-- **[Beautiful Mermaid](https://github.com/lukilabs/beautiful-mermaid)**
-  (`beautiful-mermaid`, by Craft) re-implements Mermaid rendering as a
-  synchronous TypeScript library: it computes layout itself and emits SVG
-  strings, so it runs in Node, Bun, or an edge function with no browser and
-  no Puppeteer. Its theming derives a full palette from two colors and
-  accepts Shiki/VS Code themes directly, and it renders to ASCII/Unicode for
-  terminals. It is the foundation this fork is built on.
-- **Agentic Mermaid** (`agentic-mermaid`, this repo) extends Beautiful
-  Mermaid for programs that edit diagrams — AI agents foremost. It adds a
-  typed parse → mutate → verify → serialize loop, byte-identical output
-  across runs, structured verification, and CLI/MCP surfaces. The trade is
-  explicit: 12 diagram families against Mermaid's ~25, in exchange for the
-  guarantee that parsing and re-serializing a diagram never drops syntax.
-
-Facts below reflect Mermaid ~11.15 and the upstream `beautiful-mermaid`
-repository as of mid-2026; both projects move quickly, so check their
-changelogs for the current state.
-
-## At a glance
-
-| | Mermaid | Beautiful Mermaid | Agentic Mermaid |
-|---|---|---|---|
-| Primary job | Define and render the diagram language everywhere | Fast, beautiful, browserless rendering | Agent-safe diagram *editing* plus rendering |
-| Runtime | Browser DOM (Node via Puppeteer/`mermaid-cli`) | Pure TypeScript, zero DOM, synchronous | Pure TypeScript, zero DOM, synchronous |
-| Diagram types | ~25 (flowchart, sequence, class, state, ER, gantt, pie, mindmap, gitgraph, timeline, journey, quadrant, sankey, xychart, block, packet, kanban, architecture, radar, treemap, venn, ishikawa, wardley, treeview, event modeling, …) | 6 (flowchart, state, sequence, class, ER, XY chart) | 12 (those 6 + timeline, journey, architecture, pie, quadrant, gantt) |
-| Output formats | SVG (PNG/PDF via CLI tooling) | SVG, ASCII/Unicode | SVG, PNG (offline resvg), ASCII/Unicode, JSON layout |
-| Theming | Theme config + CSS | Two-color foundation, 15+ named themes, Shiki/VS Code compatibility, live CSS-variable switching | Style + Palette stacks: named looks, palette-only styles, custom JSON records, and deterministic seeds |
-| Parse to a typed AST for editing | — (internal parser, not an editing API) | — (render-only API) | ✅ `parseMermaid` → typed `ValidDiagram` |
-| Typed mutation ops | — | — | ✅ 12 of 12 families (97 ops total), structured-or-opaque, never lossy |
-| Structural verification | — | — | ✅ 3 warning tiers + perceptual quality metrics, all families |
-| Deterministic output | Not a goal (browser/layout variance) | Mostly stable, not a tested guarantee | ✅ byte-identical across runs/processes, CI-gated |
-| Round-trip guarantee (parse → serialize keeps your source) | — | — | ✅ verbatim for unmodeled syntax, canonical for structured bodies |
-| CLI | `mermaid-cli` (`mmdc`, Puppeteer-based) | — | `am` (render/verify/mutate/batch/preview/…, single-binary build) |
-| MCP / agent surface | Official hosted MCP (validation, PNG, Mermaid Chart integration) | — | Local Code Mode MCP (`execute`, `render_png`, `describe`) plus hosted `/mcp` (`execute`, render/verify/describe, `mutate`/`build`), `llms.txt`, agent skill |
-| Interactivity (click handlers, animations) | ✅ | Partial (tooltips) | Inherited where upstream has it; not a focus |
-| Ecosystem & docs | Vast — the de-facto standard, GitHub/GitLab/Notion render it natively | Growing, popular for terminal/AI use | Small; this repo |
-
-## What each does that the others don't
-
-**Only Mermaid:** the full diagram-type catalogue (gantt, mindmap, gitgraph,
-sankey, and the 11.x additions like kanban, radar, treemap, venn, wardley,
-treeview, event modeling); native rendering inside GitHub, GitLab, Notion,
-Obsidian, and hundreds of tools; the grammar itself — both other projects
-implement *Mermaid's* language, and compatibility with Mermaid is the
-correctness bar they measure against.
-
-**Only Beautiful Mermaid (vs Mermaid):** synchronous, dependency-light
-rendering with no browser; a deliberate two-color theming foundation with
-enriched palettes and Shiki theme compatibility; ASCII/Unicode terminal
-output. Agentic Mermaid inherits all of this — it is upstream's work, and
-credit belongs there.
-
-**Only Agentic Mermaid:** the typed editing loop. `parseMermaid` returns a
-sealed IR; family narrowers (`asFlowchart` … `asXyChart`) expose typed
-mutation ops; `verifyMermaid` returns structured warnings instead of asking
-an agent to eyeball pixels; `serializeMermaid` round-trips losslessly
-(structured-or-opaque: anything the parser doesn't model is preserved
-verbatim, never silently dropped). Plus offline PNG, JSON layout, an `am`
-CLI built for agents (exit codes, JSONL batch, `capabilities --json`
-self-discovery), a local Code Mode MCP server, a bounded hosted MCP endpoint
-for zero-install render/verify/describe and structured edits, and tested
-byte-identical determinism. Neither upstream project needed any of this: both serve humans who write
-diagrams once, while this surface serves programs that edit them repeatedly.
-
-## Choosing
-
-- Rendering inside a web app, or you need mindmap/gitgraph/any family
-  beyond the 12 here → **Mermaid**.
-- Fast, beautiful SVG/ASCII rendering of the core families in
-  Node/Bun/terminal, render-only → **Beautiful Mermaid**.
-- An AI agent (or any program) needs to *edit* diagrams safely, verify them
-  structurally, or guarantee reproducible output in CI → **Agentic Mermaid**.
-
-## Compatibility notes
-
-Agentic Mermaid aims to parse what Mermaid parses for its supported
-families and to reject what Mermaid rejects (e.g. ER cardinality tokens
-match Mermaid's lexer exactly). Where this fork's renderer accepts a
-construct it cannot model for editing, the diagram still parses, renders,
-verifies, and round-trips — it just doesn't expose typed mutation for the
-unmodeled part. Upstream-relevant fixes are extracted into small PRs back to
-`lukilabs/beautiful-mermaid` per the
-[upstreaming strategy](./fork-differences.md#upstreaming-strategy).

package/docs/config.md

@@ -1,105 +0,0 @@
-# Mermaid config support
-
-Agentic Mermaid accepts Mermaid-style runtime config through explicit render options, YAML frontmatter, and `%%{init: ...}%%` / `%%{initialize: ...}%%` directives.
-
-Round-trip behavior: the agent surface preserves these source wrappers
-byte-verbatim — `parseMermaid → serializeMermaid` and every `mutate` re-emit
-the original frontmatter/directives/leading comments untouched, so a
-`config.layout`/`config.look` request written for Mermaid survives an
-Agentic Mermaid edit loop. Canonical wrapper synthesis (config-nested
-frontmatter, directives folded) is opt-in via
-`serializeMermaid(d, { wrapper: 'canonical' })` or `am format
---canonical-wrapper`.
-
-## Explicit config
-
-```ts
-import { renderMermaidSVG } from 'agentic-mermaid'
-
-const svg = renderMermaidSVG(source, {
-  mermaidConfig: {
-    theme: 'base',
-    themeVariables: {
-      fontFamily: 'Inter, sans-serif',
-      primaryColor: '#eef2ff',
-      primaryTextColor: '#111827',
-      lineColor: '#64748b',
-    },
-  },
-})
-```
-
-Explicit options win over source-level config when both specify the same supported field.
-
-## YAML frontmatter
-
-```mermaid
----
-config:
-  theme: base
-  themeVariables:
-    primaryColor: '#eef2ff'
-    lineColor: '#64748b'
----
-flowchart TD
-  A --> B
-```
-
-## Init directives
-
-```mermaid
-%%{init: { "theme": "base", "themeVariables": { "fontFamily": "Inter" } }}%%
-flowchart TD
-  A --> B
-```
-
-Loose Mermaid-style object literals are accepted for documented config surfaces where Mermaid permits them.
-
-## Supported config surfaces
-
-Top-level:
-
-- `theme`
-- `themeVariables`
-- `fontFamily`
-- `fontSize`
-
-(The composable look system is a *render option*, not Mermaid config:
-`RenderOptions.style` — name | JSON record | stack — and
-`RenderOptions.seed`; see `docs/style-authoring.md`. Mermaid
-`themeVariables` and explicit color options still win over a style's
-palette, preserving Mermaid compatibility.)
-
-Family-specific:
-
-- `xyChart.width`, `xyChart.height`, `xyChart.chartOrientation`, `xyChart.showDataLabel`, `xyChart.titlePadding`, `xyChart.xAxisLabelPadding`, `xyChart.yAxisLabelPadding`, `xyChart.plotReservedSpacePercent`, `xyChart.plotColorPalette`, `xyChart.useMaxWidth`, `xyChart.useWidth`
-- `architecture.padding`, `architecture.iconSize`, `architecture.fontSize`
-- `timeline.disableMulticolor`, `timeline.padding`, `timeline.sectionFontSize`, `timeline.periodFontSize`, `timeline.eventFontSize`
-- `gantt.displayMode` (`compact` packs non-overlapping tasks in a section into shared rows)
-
-Unsupported fields are preserved at the source level where possible, but only documented fields are interpreted by renderers.
-
-## Security
-
-Use strict rendering for untrusted source:
-
-```ts
-renderMermaidSVG(source, { security: 'strict' })
-```
-
-Strict mode disables external-fetch references such as remote font imports. Agents should prefer strict mode unless the caller explicitly wants externally loaded fonts.
-
-## PNG and config
-
-PNG renders from the same SVG pipeline, so supported Mermaid config affects PNG too:
-
-```ts
-import { renderMermaidPNG } from 'agentic-mermaid/agent'
-
-const png = renderMermaidPNG(source, {
-  fitTo: { width: 1200 },
-  background: '#fff',
-})
-```
-
-For offline/deterministic PNG generation, avoid external font imports by relying on the bundled font fallback or by rendering with strict/offline SVG options where applicable.

package/docs/contributing/adding-diagram-types.md

@@ -1,144 +0,0 @@
-# Adding Mermaid Diagram Types
-
-Use this guide when adding a diagram type that Mermaid supports but Agentic Mermaid does not yet render.
-
-## Upstream Guidance
-
-Mermaid already documents the broad shape of a new diagram contribution:
-
-- [Mermaid: Adding a New Diagram/Chart](https://mermaid.js.org/community/new-diagram)
-- [Mermaid: Contributing](https://mermaid.js.org/community/contributing.html)
-
-Their guidance is useful for structure: new diagrams usually need parsing, rendering, styling, registration, examples, docs, and tests. They also call out cross-cutting concerns such as directives, accessibility, theming, and comments.
-
-That is necessary, but not sufficient for this repo. Agentic Mermaid also needs Mermaid syntax compatibility and output quality that matches the rest of the library.
-
-## 1. Confirm The Target
-
-- Verify the diagram is already supported by Mermaid.
-- Verify it is not already routed in `src/index.ts` or `src/ascii/index.ts`.
-- Add the family to the type-checked built-in family metadata manifest in `src/agent/families.ts` first. `BUILTIN_FAMILY_METADATA` is the reviewer-facing list for shipped families and has a compile-time coverage assertion against `DiagramKind`.
-- Update the [diagram-family citizenship matrix](./diagram-family-citizenship.md) in the same PR: every citizenship surface must be marked `satisfied` with evidence or `exception` with a tracked follow-up.
-- Prefer Mermaid's stable header if Mermaid supports both stable and beta forms.
-- Write down any known Mermaid features you are intentionally not implementing yet. Those gaps must be documented in the PR before merge.
-
-## 2. Start From Mermaid's Own Example
-
-Every new diagram PR should include at least one official Mermaid example.
-
-1. Open the Mermaid syntax page for that diagram type.
-2. Copy a representative example from the Mermaid site, ideally the main example a user is most likely to try first.
-3. Add that exact Mermaid source to this repo's tests.
-4. Render it with Agentic Mermaid and confirm the structure is recognizably similar to Mermaid's published example.
-5. Commit both the example source and the rendered artifact used to verify it.
-
-For this repo, that usually means:
-
-- a test that renders the Mermaid docs example
-- a committed golden SVG in `src/__tests__/testdata/svg/` when SVG fidelity matters
-- a screenshot or SVG preview attached to the PR description so reviewers do not have to run the branch to judge the result
-
-If the Mermaid example uses syntax we do not support yet, pick the closest official example we can support now and call out the remaining gap explicitly.
-
-## 3. Fit Agentic Mermaid's Architecture
-
-Prefer the same shape used by the existing diagram families:
-
-- `src/<type>/types.ts`
-- `src/<type>/parser.ts`
-- `src/<type>/layout.ts`
-- `src/<type>/renderer.ts`
-- `src/ascii/<type>.ts` when ASCII output is practical
-- routing in `src/index.ts` and `src/ascii/index.ts`
-- built-in family metadata in `src/agent/families.ts`
-- structured hooks in `src/agent/families-builtin.ts`
-
-Follow these repo standards:
-
-- Keep the parse -> layout -> render pipeline clean and deterministic.
-- Keep rendering DOM-free and synchronous.
-- Use shared theme helpers and CSS custom properties instead of hardcoded colors where theme tokens already exist.
-- Reuse existing text measurement, multiline, spacing, and escaping utilities before inventing new ones.
-- Match the repo's visual language: readable labels, balanced padding, clear hierarchy, and outputs that still look good across built-in themes and CSS-variable inputs.
-- If the diagram needs unusual rendering rules, add a short design note like [docs/design/families/xychart.md](../design/families/xychart.md).
-
-## 4. Mermaid Compatibility Checklist
-
-Before merge, verify that the new diagram:
-
-- accepts Mermaid's documented header and supported syntax variants
-- handles comments, quoted labels, escaping, and multiline labels when they apply
-- respects Mermaid frontmatter or config for that diagram type when the syntax supports it
-- fails clearly for unsupported Mermaid syntax instead of silently mis-rendering it
-- uses Mermaid terminology in parser types and errors where practical
-
-## 5. Required Tests
-
-New diagram support should normally include most of these layers:
-
-- An upstream test-suite harvest per [`harvesting-upstream-tests.md`](./harvesting-upstream-tests.md): vendor the family's mermaid grammar/semantics specs (and ASCII-fork inputs) into `eval/mermaid-<type>-bench/` with an executable exclusions ledger, and add the family's docs examples to the mermaid-docs corpus. For not-yet-built families, do the harvest BEFORE implementation — it surfaces the real semantics the docs omit.
-- Parser tests for valid syntax, invalid syntax, comments, quoted labels, multiline labels, and diagram-specific edge cases
-- Layout tests when layout rules are specialized, especially spacing, bounds, and overlap avoidance
-- Integration tests for parse -> layout -> render using a basic example, a realistic example, and an edge case
-- SVG snapshot or golden tests when visual structure matters, including at least one Mermaid docs example; follow [`visual-review-evidence.md`](./visual-review-evidence.md) for contact sheets, layout-compare, rubric galleries, and browser screenshot expectations
-- Theme and compatibility tests for dark/light themes, CSS variable inputs, and frontmatter/config handling where relevant
-- ASCII tests when ASCII rendering is supported, including Unicode mode and ASCII-safe mode; add exact fixtures under `src/__tests__/testdata/{ascii,unicode}/` and regenerate them with `bun run goldens:ascii`
-- Regression tests for easy-to-break behavior such as ordering, escaping, markers, label normalization, or routing
-- Sample coverage in `scripts/site/samples-data.ts` when the feature should appear on the visual samples page
-- Live editor coverage in `editor/js/examples.js`: add one basic example under the `Supported diagrams` category, add an explicit picker glyph, and let `src/__tests__/editor-examples.test.ts` prove it parses and renders. This is required for every registered built-in family, not just marketing-worthy ones.
-- Citizenship matrix coverage in `docs/contributing/diagram-family-citizenship.matrix.json`, with evidence paths for completed surfaces and tracked exceptions for deferred quality/compatibility work.
-- README updates for the new supported diagram type and any intentional compatibility gaps
-
-Use the existing naming pattern where possible:
-
-- `src/__tests__/<type>-parser.test.ts`
-- `src/__tests__/<type>-integration.test.ts`
-- `src/__tests__/<type>-ascii.test.ts`
-- `src/__tests__/<type>-layout.test.ts`
-
-Regression guard:
-
-- Confirm at least one new or changed test fails when the implementation is reverted or the new routing is removed.
-- Mention that verification in the PR description.
-
-## 6. Commands To Run
-
-Run the checks that fit the change:
-
-- `bun test src/__tests__/`
-- `bun run goldens:ascii:check` if you added or changed ASCII/Unicode fixtures
-- `npm run build`
-- `bun run samples` if you added or changed visual samples
-- `bun run bench` if the diagram type adds meaningful layout or rendering cost
-
-## 7. Agent-Native Typed Mutation (Required)
-
-Typed mutation is part of the definition of done for a new family, not a follow-up. Every renderable family ships a structured editing surface by default; source-level-only families are no longer accepted. Add, alongside the renderer pipeline above:
-
-- A body module `src/agent/<type>-body.ts` with a structured-or-opaque parser, a canonical serializer, a mutator (per-family ops), and a `verify` hook. Follow an existing module — `src/agent/journey-body.ts` (pilot), `src/agent/pie-body.ts`, or `src/agent/quadrant-body.ts` are clean templates.
-- Body + op types in `src/agent/types.ts` (e.g. `PieBody`, `PieMutationOp`), added to the `DiagramBody`, `AnyMutationOp`, and `MutableValidDiagram` unions, plus a narrower `as<Type>` and its `<Type>ValidDiagram` alias.
-- Structured hooks registered in `src/agent/families-builtin.ts` (replace any source-level-only registration), the narrower exported from `src/agent/index.ts`, and a `mutate` overload in `src/agent/mutate.ts`.
-- The surface sync the doc-sync tests enforce: `BUILTIN_FAMILY_METADATA` (`src/agent/families.ts`), `MUTATION_OPS_BY_FAMILY` (`src/cli/index.ts`), `SDK_DECLARATION` (`src/mcp/sdk-decl.ts`) + sandbox narrower wiring, `AGENT_NATIVE.md` op list and workflow, the `Instructions_for_agents.md` mirror + `llms.txt` regeneration, `am init-agent` generated snippets, editor examples, fixture-backed `skill-evals/shared-benchmark.json` cases, and the per-family docs/skill tables.
-- Tests: parse/narrow/mutate/verify/serialize, structured-or-opaque fallback cases (table-driven sad paths), a fast-check round-trip property test, and a differential test against the legacy renderer parser proving the canonical source you emit re-parses identically.
-
-**Structured-or-opaque law:** any line your parser does not model must be preserved verbatim (opaque fallback) — never silently dropped. Opaque bodies round-trip byte-verbatim; structured bodies serialize to canonical source and must be serialize-idempotent (parse → serialize → parse → serialize is byte-stable).
-
-**Wrapper law (1C):** the leading source wrapper — frontmatter block, `%%{init}%%`/`%%{initialize}%%` directives, `%%` comments before the header, blank lines — round-trips byte-verbatim through `serializeMermaid` and through mutation (`meta.wrapperSource`). Canonical wrapper synthesis (Mermaid's documented shape: `title`/`displayMode` top-level, everything else nested under `config:`, directives folded) is opt-in via `serializeMermaid(d, { wrapper: 'canonical' })` / `am format --canonical-wrapper`, and must never emit frontmatter Mermaid cannot read back (no flattened config keys).
-
-**In-body comment policy (2C):** structured bodies do not model in-body `%%` comments; their canonical serialization drops them, and that loss must be *announced* — parse records the casualties (`meta.droppedComments`, computed by diffing against the serialized output) and verify surfaces the Tier 3 `COMMENT_DROPPED` lint. Opaque bodies and preserved opaque segments keep comments verbatim. The destination state is segment-preserving comment retention (the BUILD-18 pattern); until a family ships that, dropping silently is a bug, dropping announced is the documented trade.
-
-**Enforcement:** the test `every registered renderable family ships typed mutation (default-by-default enforcement)` in `src/__tests__/agent-doc-sync.test.ts` fails CI if a registered family lacks mutate/serialize hooks, an ops declaration, or a narrower. A new family that registers source-level-only will not pass CI.
-
-## 8. Definition Of Done
-
-A new Mermaid-backed diagram type is ready when:
-
-- Mermaid's official example renders with recognizably similar structure
-- the PR includes the example source and the rendered evidence used to review it
-- parser, integration, and regression coverage exist for the important syntax paths
-- specialized layout, renderer, theme, and ASCII behavior are covered when applicable
-- output quality matches the rest of Agentic Mermaid
-- the agent-native typed mutation surface from section 7 is wired and tested (the default-by-default enforcement test passes)
-- the live editor has a basic working example and explicit glyph for the family
-- the shared skill-eval manifest has at least one fixture-backed case tagged for the family
-- intentional gaps versus Mermaid are documented