agentic-mermaid 0.1.1 → 0.2.0

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