agentic-mermaid 0.1.0 → 0.1.2

package/docs/features.md

@@ -1,147 +0,0 @@
-# Features — capability inventory
-
-What Agentic Mermaid can do, organized by capability area. The npm import paths are `agentic-mermaid` and `agentic-mermaid/agent`; implementation history lives in [`project/divergences.md`](./project/divergences.md); active backlog is only [`../TODO.md`](../TODO.md).
-
-## Core IR & editing loop
-
-- **Typed `ValidDiagram` IR** — parse Mermaid into a sealed, typed value.
-- **`parseMermaid(source)`** → `Result<ValidDiagram, ParseError[]>`. Never
-  throws on malformed input; structured errors.
-- **`mutate(d, op)`** — family-overloaded typed mutation. Ops per family:
-  flowchart (6), state (8), sequence (5), timeline (10), class (10), ER (7),
-  journey (10), architecture (10), xychart (8), pie (7), quadrant (7), gantt (9).
-- **`verifyMermaid(d, opts)`** — structural verification (no pixels).
-- **`serializeMermaid(d)`** — back to canonical source.
-- **Round-trip** — structured bodies serialize to canonical, idempotent
-  source; opaque bodies preserve original indentation/comments verbatim.
-- **Narrowers** — `asFlowchart`/`asState`/`asSequence`/`asTimeline`/`asClass`/`asEr`/
-  `asJourney`/`asArchitecture`/`asXyChart`/`asPie`/`asQuadrant`/`asGantt`
-  return `null` on a non-matching or source-level/opaque body (steers agents
-  off the unsafe path).
-
-## Diagram families (12)
-
-| Family | Parse/render/round-trip | Structured mutation |
-|---|---|---|
-| Flowchart | ✅ | ✅ (6 ops) |
-| State | ✅ | ✅ (8 ops via `asState`; `<<fork>>`/notes/`--`/`classDef` → opaque) |
-| Sequence | ✅ | ✅ (5 ops; alt/loop/note ride along verbatim as segments) |
-| Timeline | ✅ | ✅ (10 ops) |
-| Class | ✅ | ✅ (10 ops) |
-| ER | ✅ | ✅ (7 ops) |
-| Journey | ✅ | ✅ (10 ops via `asJourney`) |
-| XY chart | ✅ | ✅ (8 ops via `asXyChart`) |
-| Architecture | ✅ | ✅ (10 ops via `asArchitecture`) |
-| Pie | ✅ | ✅ (7 ops via `asPie`) |
-| Quadrant | ✅ | ✅ (7 ops via `asQuadrant`) |
-| Gantt | ✅ | ✅ (9 ops via `asGantt`; calendar directives/click/comments ride along verbatim as segments) |
-
-**Structured-or-opaque rule:** every family either has a structured body
-or preserves source verbatim. Constructs are never silently dropped.
-
-## Output formats
-
-Agentic Mermaid outputs **SVG, PNG, ASCII, Unicode, and JSON layout** from the same renderer foundation.
-
-- **Styles** — every SVG/PNG render accepts `style`: a full look
-  (`hand-drawn`, `excalidraw`, `pen-and-ink`, `freehand`, `watercolor`,
-  `blueprint`, `tufte`, `accessible-high-contrast`, `patent-drawing`,
-  `status-dashboard`, `ops-schematic`, `chalkboard`, `risograph`,
-  `architectural-plan`, `publication-figure`), any theme name (a theme is a
-  palette-only style), an inline JSON record, or a stack merged left → right
-  (`{ style: ['hand-drawn', 'dracula'] }`). `seed` re-rolls styled ink and
-  never moves layout. CLI: `am render --style … --seed N`, `am styles`;
-  MCP render tools take `style`/`seed`; RENDER_FAILED-gated verify means a
-  clean verify proves the styled source renders. Authoring guide, schema, and
-  cookbook: `docs/style-authoring.md`, `docs/schemas/style-spec.schema.json`,
-  and `docs/custom-style-cookbook.md`.
-
-- **SVG** — `renderMermaidSVG` (`compact`, `security:'strict'`, CSS
-  variable fonts, `idPrefix` namespacing). CLI exposes `--security strict`.
-- **ASCII / Unicode** — `renderMermaidASCII` (CJK/emoji width, FE0F/ZWJ,
-  `maxWidth` wrapping, trunk-shared fanouts).
-- **PNG** — `renderMermaidPNG(source, { fitTo, background, style, seed, fontDirs })` or `am render diagram.mmd --format png --output diagram.png` (offline `@resvg/resvg-js`; bundled DejaVu plus the built-in style faces,
-  cross-runtime deterministic on same-machine x86_64/ARM64 where Node + built `dist/` are present).
-- **JSON layout** — `layoutMermaid` / `am render --format json`; add `--certificates` (or `layoutMermaid(d, { debug: true })`) to include opt-in graph route certificates, family edge-route certificates (class/ER/architecture/sequence), region-containment certificates (timeline/charts), V1 region/action sidecars, exact ports, and side/slot/role assignments where applicable.
-- **ASCII with metadata** — `renderMermaidASCIIWithMeta` → `{ ascii, regions, warnings, routeParity }`
-  for TUI click-mapping.
-- **Reverse** — `asciiToMermaid` reconstructs flowchart source from ASCII
-  (best-effort, lossy, structural round-trip).
-
-## Verification tiers
-
-- **Tier 1 (structural, universal):** EMPTY_DIAGRAM, EDGE_MISANCHORED,
-  OFF_CANVAS, GROUP_BREACH, UNKNOWN_SHAPE, LABEL_OVERFLOW, UNRESOLVABLE_SCHEDULE,
-  RENDER_FAILED (a clean verify proves the source actually renders).
-- **Tier 2 (geometric — route tripwires for flowchart/state, anchor/overlap checks for class/ER):** NODE_OVERLAP, ROUTE_SELF_CROSS, and the route-contract tripwires ROUTE_HITCH, ROUTE_UNEXPLAINED_BEND, ROUTE_LABEL_ON_SHARED_TRUNK, ROUTE_CONTAINER_MISANCHOR, ROUTE_SHAPE_MISANCHOR, ROUTE_STALE_AFTER_NODE_MOVE.
-- **Tier 3 (lint, advisory):** DUPLICATE_EDGE, UNREACHABLE_NODE, DECISION_BRANCH_UNLABELED, COMMENT_DROPPED, UNSUPPORTED_SYNTAX, CONTENT_DROPPED_ON_ROUNDTRIP.
-- **Perceptual quality** — `measureQuality` / `checkQuality` (edge
-  crossings, label legibility, whitespace balance, …). See [`quality.md`](./quality.md).
-
-## Accessibility
-
-- `accTitle`→`<title>`, `accDescr`→`<desc>`, `role="img"`, `aria-labelledby`.
-- **AX tree** — `describeMermaid(d, {format:'json'})` → `{nodes, edges,
-  entryPoints, sinks}`; prose summary in `{format:'text'}`.
-- Auto-contrast node text on custom fills (WCAG luminance).
-- External CSS class emission (Mermaid `classDef` assignments → SVG classes).
-
-## Security
-
-- **Strict mode** (`security:'strict'`) — zero external-fetch references in
-  the SVG (no Google Fonts `@import`).
-- **`verifyNoExternalRefs(svg)`** — scanner / CI gate / agent self-check.
-- No `<image>`/`<script>`/external-href injection; click directives
-  sanitized. See [`../SECURITY.md`](../SECURITY.md).
-
-## CLI (`am`)
-
-`render` (svg/ascii/unicode/json with multi-input results; png uses one
-input plus `--output`; `--security strict`, `--watch`), `render-markdown` (skip bad blocks),
-`parse`, `verify`, `mutate` (`--op` or `--ops`), `preview` (strict standalone HTML + optional `--open`), `format`, `describe` (text/json),
-`capabilities --json` (including `families[].editPolicy` + `families[].mutationOps`), `batch --jsonl` (including mutate),
-`llms-txt`, `init-agent`, `--agent-instructions`. `mutate` verifies before emitting source; `init-agent` writes a non-clobbering `AGENTS.md` section, root `skills/` bundle, and `.mcp.json` sample into a consumer repo.
-Exit codes 0/2/3/4; parse and verify-failure errors include structured `error.details` arrays.
-
-## MCP server
-
-Local `agentic-mermaid-mcp` is Code Mode-first: `execute(code)` runs synchronous
-JavaScript in a local `node:vm` sandbox with a typed `mermaid.*` SDK declaration,
-plus narrow `render_png` and `describe` helpers. It supports stdio by default and
-HTTP/SSE via `agentic-mermaid-mcp --transport http`; local `render_png` can
-return base64 bytes or managed file/URL artifacts with MIME type, byte count, and
-SHA-256 metadata.
-
-The hosted endpoint at `https://agentic-mermaid.dev/mcp` is stateless
-Streamable HTTP. It exposes eight bounded MCP JSON-RPC tools: `execute` in a
-Cloudflare Dynamic Worker isolate, pure `render_svg` / `render_ascii` /
-`render_png` / `verify` / `describe`, and declarative `mutate` / `build` for
-structured edits. Hosted inputs are capped at 64 KB, PNG is base64-only, and the
-endpoint is a convenience surface rather than a REST render API.
-
-## Distribution
-
-- npm library (`agentic-mermaid` plus the `agentic-mermaid/agent` subpath) with Node-runnable bins (`am`, `agentic-mermaid`, `agentic-mermaid-mcp`).
-- **Single binary** — `bun run build:binary` → `dist/am`, standalone
-  executable, no runtime dependency (#1018).
-- **llms.txt** agent-discovery digest, derived from capabilities.
-
-## Guarantees & evidence
-
-- **Determinism** — byte-identical across repeated runs and processes for
-  SVG layout/ASCII; full-corpus ASCII repeated-run guard; cross-runtime guards
-  exist for bun ≡ node on same-machine x86_64/ARM64 when Node + built `dist/`
-  artifacts are present.
-- **Corpus gates** — 271-entry mermaid-js docs corpus + 132-case
-  MermaidSeqBench, gated in CI.
-- **Benchmarks** — `eval/benchmark/RESULTS.md` (measured vs mmdc, termaid).
-- **Agent-usage validation** — `eval/agent-usage/` scenarios,
-  anti-pattern linter, sandbox trace instrumentation, and stored Code Mode eval runner.
-- **Unit, browser/e2e, typecheck, build, binary-build, eval, and lint gates**
-  are part of the verification contract.
-
-## Not browser-dependent
-
-The entire core (parse/verify/mutate/serialize/ASCII/PNG/SVG) runs with no
-DOM, no headless browser, synchronously. This is the structural
-differentiator vs Puppeteer-based Mermaid CLIs.

package/docs/fork-differences.md

@@ -1,130 +0,0 @@
-# What is different about this fork?
-
-This document describes **Agentic Mermaid**, the `adewale/agentic-mermaid` fork, relative to upstream `lukilabs/beautiful-mermaid`. It is intentionally product/documentation focused; upstreamable changes should still be split into small PRs.
-
-## Live site
-
-The canonical live site is **[agentic-mermaid.dev](https://agentic-mermaid.dev/)** — a Cloudflare Workers Static Assets deployment built from [`website/`](../website):
-
-- Home & docs: <https://agentic-mermaid.dev/>
-- Live editor: <https://agentic-mermaid.dev/editor>
-- Family comparisons (Mermaid vs Beautiful Mermaid vs Agentic Mermaid): <https://agentic-mermaid.dev/comparisons/>
-
-Alongside the static surface (the public website, machine-readable manifests, schemas, recipes, and skill files), the Cloudflare Worker serves a stateless hosted MCP endpoint at `/mcp` (`https://agentic-mermaid.dev/mcp`) — eight tools: Code Mode `execute` in per-request Dynamic Worker isolates, the `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` pure tools, and the declarative `mutate`/`build` structured-edit tools. There is still no REST render API: `/mcp` speaks MCP JSON-RPC only.
-
-GitHub Pages is no longer a deployed surface; its samples-gallery generator has been retired. The live editor is served at [agentic-mermaid.dev/editor](https://agentic-mermaid.dev/editor) and built by `scripts/site/editor.ts` (also used by `website/build.ts`), and is exercised in a real browser by `e2e/browser.test.ts`.
-
-## Agent-native workflow (largest fork-vs-upstream gap)
-
-Agentic Mermaid is published as `agentic-mermaid` and adds a typed editing surface for AI agents under the `agentic-mermaid/agent` subpath export, plus an `am` CLI and an `agentic-mermaid-mcp` Code Mode MCP server (stdio plus opt-in HTTP/SSE transport with managed render artifacts). A render-only library forces an agent to regenerate the whole diagram to change one node; here, new diagrams are authored as source then parsed/verified/rendered, while existing structured diagrams go parse → narrow → mutate → verify → serialize.
-
-Twelve of the twelve families are structured-when-narrowed: flowchart (6 ops), state (8 ops via a dedicated `StateBody` and `asState`), sequence (5 ops, **segment-preserving** — notes/`alt`/`loop` blocks ride along verbatim while the ops stay live), timeline (10), class (10), ER (7), journey (10), XY chart (8), architecture (10), pie (7 via `asPie`), quadrant (7 via `asQuadrant`), and Gantt (9 via `asGantt`). Any unmodeled syntax still round-trips losslessly via preserved source (opaque fallback). Layout is deterministic and verified byte-identical across processes, and `verifyMermaid` returns structured warnings in three tiers (structural, geometric, lint) plus perceptual quality metrics (`measureQuality`) covering every family. See [`AGENT_NATIVE.md`](../AGENT_NATIVE.md) and [`Instructions_for_agents.md`](../Instructions_for_agents.md). Upstream has no equivalent; for a three-way functionality view including Mermaid itself, see [`comparison.md`](./comparison.md).
-
-## New and expanded diagram support
-
-This fork renders a wider set of Mermaid families in both the gallery and editor:
-
-- Flowcharts and state diagrams
-- Architecture diagrams (`architecture-beta`)
-- Sequence diagrams
-- Class diagrams
-- ER diagrams
-- Timeline diagrams (`timeline`)
-- User Journey diagrams (`journey`)
-- XY charts (`xychart` and `xychart-beta`)
-- Pie charts (`pie`, with `showData`)
-- Quadrant charts (`quadrantChart`) — not yet rendered anywhere else in the beautiful-mermaid network
-- Gantt charts (`gantt`) with date axes, sections, dependencies, milestones, exclusions, and vertical markers
-
-The live editor has registry-backed example coverage for every built-in family
-(`src/__tests__/editor-examples.test.ts`). Browser E2E still spot-checks several
-fork-added rendering paths: architecture, timeline, journey, and xychart.
-
-## Style + Palette SVG rendering
-
-The fork adds a consistent Style + Palette API across diagram families:
-
-```ts
-renderMermaidSVG(source, {
-  style: ['publication-figure', 'github-light'],
-  seed: 2,
-})
-```
-
-A style chooses the renderer treatment — for example `hand-drawn`, `watercolor`, `publication-figure`, or `ops-schematic`. A palette-only style chooses colors — for example `github-light`, `dracula`, or a custom JSON record with `colors`. Stacks merge left to right, so agents can keep visual requests out of Mermaid source while preserving deterministic geometry.
-
-## Mermaid config and source wrappers
-
-This fork supports Mermaid-style source wrappers before diagram headers, including:
-
-- YAML frontmatter
-- `%%{init: ...}%%` directives
-- `%%{initialize: ...}%%` directives
-- Mermaid comments before the header
-
-These are merged with `options.mermaidConfig` where supported. XY chart and architecture rendering use this to honor Mermaid-compatible theme/config fields.
-
-## Showcase and editor discovery
-
-Users can discover fork features through:
-
-1. The [examples page](https://agentic-mermaid.dev/examples/), including supported families, Style + Palette combinations, and the richer shared examples corpus.
-2. The [live editor](https://agentic-mermaid.dev/editor), which starts with examples for every supported diagram family.
-3. [`README.md`](../README.md) quick starts and docs routing.
-4. [`CHANGELOG.md`](../CHANGELOG.md) for user-facing change history.
-
-## Layout and quality work
-
-- A layout before/after comparison harness (`eval/layout-compare/`) and per-family `RenderedLayout` adapters so perceptual metrics gate layout changes with evidence. Debug JSON can also expose opt-in graph route certificates, family edge-route certificates, region-containment certificates, and region/action sidecars for tooling; default JSON stays compact.
-- Still different from the current upstream release (Beautiful Mermaid 1.1.3): decision-branch routing emits a diamond's branches from facet-mid ports as mirror-symmetric routes (the layout symmetry floor), and an edge to a subgraph attaches to its container with `direction` overrides honored inside it — a case upstream 1.1.3 still mis-routes (`mermaid-js/mermaid#2509` leaves it unsolved). Both are shown side by side on the [differences page](https://agentic-mermaid.dev/comparisons/).
-- Already upstreamed: fan-in grouping (upstream #68/#69) and labeled fan-out trunk sharing with box-start connector placement (#111/#112/#113, upstream PR #113) landed here first and now render identically in Beautiful Mermaid 1.1.3 — they are no longer fork-only.
-- ER cardinality parsing matches Mermaid's lexer exactly; malformed relationship lines error loudly instead of being silently dropped.
-
-## Parser and semantic divergences from Mermaid.js
-
-- **Subgraph membership is *first-defined-wins*.** A node belongs to the subgraph
-  where it is **first defined**, and a top-level reference counts as a definition —
-  so a node referenced at the top level and then listed inside a subgraph block
-  stays at the top level. Mermaid.js instead lets the subgraph *block* claim any
-  node it lists, regardless of a prior top-level reference. In the canonical Mermaid
-  docs example:
-
-  ```mermaid
-  flowchart TB
-      c1-->a2
-      subgraph one
-      a1-->a2
-      end
-      subgraph two
-      b1-->b2
-      end
-      subgraph three
-      c1-->c2
-      end
-  ```
-
-  Mermaid.js places `a2` inside `one` and `c1` inside `three`; this fork keeps `a2`
-  and `c1` at the top level (only `a1`/`c2` are inside those subgraphs). See it both
-  ways: [open in Mermaid Live](https://mermaid.live/edit#pako:eNp10DELwjAQBeC_Et7cDjpmcBBXJ50kyzW5NoU2V9KEIqX_XbSoRXB87z44eDOsOIZG3clkPcWkrkcTlFLK7sryQPs1jLlqIg1eSeC1oe2Zg_txaZK1qZ6u-u98ZN48tF-JAj3HnloHjdkgee7ZQBs4ril3yWBBAcpJLvdgoVPMXCBKbjx0Td3IBfLgKPGppSZS_yYDhZvIJ7Jrk8TzOsRrj-UBwvBYkQ)
-  · [open in the fork editor](https://agentic-mermaid.dev/editor#eyJzb3VyY2UiOiJmbG93Y2hhcnQgVEJcbiAgICBjMS0tPmEyXG4gICAgc3ViZ3JhcGggb25lXG4gICAgYTEtLT5hMlxuICAgIGVuZFxuICAgIHN1YmdyYXBoIHR3b1xuICAgIGIxLS0+YjJcbiAgICBlbmRcbiAgICBzdWJncmFwaCB0aHJlZVxuICAgIGMxLS0+YzJcbiAgICBlbmQifQ==).
-
-  This is a deliberate divergence, not a bug: it gives deterministic
-  *definition-scope* membership with no surprising re-parenting when a node is
-  mentioned again inside a container, consistent with the fork's goal of
-  predictable, source-preserving behavior rather than Mermaid pixel/layout parity
-  (see [#38](https://github.com/adewale/agentic-mermaid/issues/38)). Mermaid's own
-  users report *its* behavior as a bug (`mermaid-js/mermaid#738`, `#2707`). The rule
-  is inherited from upstream Beautiful Mermaid (introduced in its v1.0.0 rewrite),
-  not fork-invented, and is guarded by `src/__tests__/parser.test.ts` — a node
-  genuinely defined inside one subgraph and later referenced inside another
-  likewise stays in its first subgraph (it is never re-parented by a mere
-  reference).
-
-## What is intentionally not in this fork
-
-- No committed `dist/` artifacts.
-- No large bundled upstream PR: upstream contributions should remain focused and independently reviewable.
-
-## Upstreaming strategy
-
-The fork should continue extracting small upstreamable PRs from broad fork work. This file is not the backlog: parked fork-port ideas live only under `PARK-3` in `TODO.md` until one is promoted to a focused issue.

package/docs/getting-started.md

@@ -1,175 +0,0 @@
-# Getting started (library)
-
-A 5-minute guide for using `agentic-mermaid` as a plain rendering library: turn a
-Mermaid string into **SVG**, **PNG**, or **ASCII/Unicode**. No agents, no server,
-no browser — every function below runs synchronously in Node, Bun, or the browser.
-
-> Editing diagrams with the typed parse → mutate → verify → serialize API is a
-> separate surface — see the [agent API cookbook](./agent-api-cookbook.md). You do
-> not need any of that just to render.
-
-## Install
-
-```bash
-npm install agentic-mermaid
-# or: bun add agentic-mermaid / pnpm add agentic-mermaid
-```
-
-For repository development, install from source:
-
-```bash
-git clone https://github.com/adewale/agentic-mermaid
-cd agentic-mermaid && bun install && bun run build
-```
-
-## Render to SVG
-
-`renderMermaidSVG` takes Mermaid source and returns a self-contained SVG string.
-It supports all 12 diagram families (flowchart, sequence, class, ER, state, gantt,
-pie, …) — just pass the source.
-
-```ts
-import { renderMermaidSVG } from 'agentic-mermaid'
-
-const svg = renderMermaidSVG(`flowchart TD
-  Start --> Stop`)
-
-console.log(svg) // "<svg ...>...</svg>"
-```
-
-Write it to a file in Node/Bun:
-
-```ts
-import { writeFileSync } from 'node:fs'
-import { renderMermaidSVG } from 'agentic-mermaid'
-
-writeFileSync('diagram.svg', renderMermaidSVG('flowchart LR\n  A --> B --> C'))
-```
-
-## Render to PNG
-
-PNG rendering uses a bundled native rasterizer, so `renderMermaidPNG` lives on the
-`agentic-mermaid/agent` entry point. It returns a `Uint8Array` of PNG bytes.
-
-```ts
-import { writeFileSync } from 'node:fs'
-import { renderMermaidPNG } from 'agentic-mermaid/agent'
-
-const png = renderMermaidPNG(`flowchart TD
-  Start --> Stop`, {
-  fitTo: { width: 1200 }, // constrain output width (optional)
-  background: '#ffffff',  // PNG has no transparency by default
-})
-
-writeFileSync('diagram.png', png)
-```
-
-`PngOptions`: `scale` (default `2`, for retina), `background`, and
-`fitTo: { width?, height? }`.
-
-## Render to ASCII / Unicode
-
-Great for terminals, code reviews, and plain-text logs. Unicode box-drawing is the
-default; pass `{ useAscii: true }` for pure ASCII.
-
-```ts
-import { renderMermaidASCII } from 'agentic-mermaid'
-
-const unicode = renderMermaidASCII('flowchart LR\n  A --> B')
-const ascii = renderMermaidASCII('flowchart LR\n  A --> B', { useAscii: true })
-
-console.log(unicode)
-```
-
-See [`ascii.md`](./ascii.md) for supported families and cell-to-region metadata.
-
-## Theming
-
-Theme from two colors, or spread one of the 21 built-in themes. Colors are applied
-as CSS variables, so the SVG stays self-contained.
-
-```ts
-import { renderMermaidSVG, THEMES } from 'agentic-mermaid'
-
-// Two-color theme
-const dark = renderMermaidSVG('flowchart TD\n  A --> B', {
-  bg: '#1a1b26',
-  fg: '#a9b1d6',
-})
-
-// A built-in theme (zinc-light, tokyo-night, nord, dracula, catppuccin-mocha, …)
-const themed = renderMermaidSVG('flowchart TD\n  A --> B', {
-  ...THEMES['tokyo-night'],
-})
-
-// Transparent background, for embedding on any page
-const transparent = renderMermaidSVG('flowchart TD\n  A --> B', {
-  transparent: true,
-})
-```
-
-Common `RenderOptions`: `bg`, `fg`, `font`, `transparent`, and `security`. See
-[`theming.md`](./theming.md) for custom themes and Shiki/VS Code theme import.
-
-### Untrusted input
-
-If the Mermaid source is not yours, render with `security: 'strict'`. It disables
-the web-font `@import` and strips any external-fetch references from the output, so
-the SVG cannot phone home.
-
-```ts
-import { renderMermaidSVG } from 'agentic-mermaid'
-
-const safe = renderMermaidSVG(userProvidedSource, { security: 'strict' })
-```
-
-## In the browser and in frameworks
-
-`renderMermaidSVG` is synchronous and needs no DOM, so you can render during a
-component's render pass and drop the string straight into the markup. In React,
-memoize it to avoid re-rendering on every paint:
-
-```tsx
-import { useMemo } from 'react'
-import { renderMermaidSVG } from 'agentic-mermaid'
-
-function Diagram({ code }: { code: string }) {
-  const svg = useMemo(() => renderMermaidSVG(code), [code])
-  return <div dangerouslySetInnerHTML={{ __html: svg }} />
-}
-```
-
-See [`react.md`](./react.md) for the zero-flash, live-theme-switching setup.
-
-## Which import path?
-
-| You want | Import from |
-|---|---|
-| SVG | `agentic-mermaid` |
-| ASCII / Unicode | `agentic-mermaid` |
-| PNG (native rasterizer) | `agentic-mermaid/agent` |
-| Themes (`THEMES`, `fromShikiTheme`) | `agentic-mermaid` |
-| Everything in one path | `agentic-mermaid/agent` |
-| Typed editing (parse/mutate/verify) | `agentic-mermaid/agent` |
-
-`agentic-mermaid/agent` re-exports the renderers too, so if you would rather use a
-single import path for all formats, import everything from there.
-
-## Prefer the command line?
-
-The same renderers ship as the `am` CLI — no code required:
-
-```bash
-am render diagram.mmd --format svg
-am render diagram.mmd --format png --output diagram.png
-am render diagram.mmd --ascii
-```
-
-Run `am --help` for the full command set.
-
-## Next steps
-
-- [`diagram-families.md`](./diagram-families.md) — every supported family with examples.
-- [`theming.md`](./theming.md) — custom themes and Shiki import.
-- [`api.md`](./api.md) — the full option and function reference.
-- [`agent-api-cookbook.md`](./agent-api-cookbook.md) — typed editing (parse → mutate → verify → serialize).

package/docs/issue-derived-test-cases.md

@@ -1,156 +0,0 @@
-# Issue-derived test-case candidates
-
-These are public Mermaid / Beautiful Mermaid issues worth turning into small, educational fixtures. The goal is not to clone every upstream bug; it is to keep representative examples that teach the renderer/agent surface what users actually expect.
-
-## Already covered or newly covered
-
-- [mermaid-js/mermaid#5227 — Backwards arrows](https://github.com/mermaid-js/mermaid/issues/5227)
-  - Why it matters: feedback edges are common in auth/retry flows and should not scramble the primary left-to-right path.
-  - Current coverage: `src/__tests__/agent-auth-flow.test.ts` builds an auth flow through Agentic Mermaid mutations and asserts `C→B` / `F→E` route backwards while the primary LR path stays source-ordered.
-- [mermaid-js/mermaid#7645 — block loading of external images](https://github.com/mermaid-js/mermaid/issues/7645)
-  - Why it matters: agent-generated diagrams are untrusted input.
-  - Current coverage: strict SVG/security tests assert external-fetch references are removed.
-- [mermaid-js/mermaid#7695 — Trusted Types / CSP](https://github.com/mermaid-js/mermaid/issues/7695)
-  - Why it matters: generated SVG/HTML must be embeddable in locked-down apps.
-  - Current coverage: browser CSP/Trusted Types e2e exercises enforcement and strict render paths.
-- [mermaid-js/mermaid#5632 — screen-reader/accessibility support](https://github.com/mermaid-js/mermaid/issues/5632)
-  - Why it matters: diagrams need non-visual summaries for users and agents.
-  - Current coverage: `am describe` / `describeMermaid(...,{format:'json'})` expose an AX-style tree and docs sync tests guard the surface.
-- [lukilabs/beautiful-mermaid#119 — CJK label alignment](https://github.com/lukilabs/beautiful-mermaid/issues/119)
-  - Why it matters: ASCII renderers often break on fullwidth text.
-  - Current coverage: CJK width tests and ASCII rendering tests.
-- [lukilabs/beautiful-mermaid#115 — text contrast on custom fills](https://github.com/lukilabs/beautiful-mermaid/issues/115)
-  - Why it matters: themeable diagrams must remain readable.
-  - Current coverage: auto-contrast and theme/renderer contrast tests.
-- [lukilabs/beautiful-mermaid#111/#112 — ASCII fan-out trunks and box-start connectors](https://github.com/lukilabs/beautiful-mermaid/issues/111)
-  - Why it matters: sibling fan-outs should share a readable trunk and edge labels should stay on branches rather than forcing detours or floating connectors.
-  - Current coverage: `src/__tests__/ascii-pathfinder-trunk.test.ts` covers TD/LR labeled fan-out repros and bidirectional-label separation; `src/__tests__/ascii-box-start.test.ts` covers source-border connectors; ASCII determinism tests guard repeated routing stability; golden files pin exact ASCII/Unicode output.
-- [lukilabs/beautiful-mermaid#69 — fan-in grouping](https://github.com/lukilabs/beautiful-mermaid/pull/69)
-  - Why it matters: unrelated fan-in groups should not cross into ambiguous shared trunks.
-  - Current coverage: `src/__tests__/ascii-fan-in-grouping.test.ts` covers target-aware grouping and cycle guards.
-- [lukilabs/beautiful-mermaid#98 — nested-subgraph layout with direction](https://github.com/lukilabs/beautiful-mermaid/pull/98)
-  - Why it matters: subgraph direction overrides and container edges should not create phantom nodes or move children outside groups.
-  - Current coverage: `src/__tests__/subgraph-direction.test.ts` covers SVG geometry, ASCII one-row inner LR layout, subgraph-id edge attachment, 7-bit ASCII mode, nested child subgraph targets, styled/labeled container edges, and multi-edge containers; golden files pin exact ASCII/Unicode output.
-- [lukilabs/beautiful-mermaid#121 — ER/class ASCII label truncation and stray connectors](https://github.com/lukilabs/beautiful-mermaid/issues/121)
-  - Why it matters: ER/class ASCII labels and compartment text are semantic content, not decoration; long labels must not silently disappear when connectors are tight.
-  - Current coverage: exact ASCII/Unicode golden files cover class compartments/relationship labels and ER relationship labels. ER same-row layout now widens the inter-entity gap to preserve full labels.
-
-## High-value future fixtures
-
-- [mermaid-js/mermaid#6271 — unexpected graph direction](https://github.com/mermaid-js/mermaid/issues/6271)
-  - Suggested fixture: a graph whose author order implies a clear primary direction but whose cross/back edges tempt the layout engine to flip ranks. Assert source-order progression and bounded aspect ratio.
-- [mermaid-js/mermaid#7785 — collapsible subgraphs via `@{ view: collapsed }`](https://github.com/mermaid-js/mermaid/pull/7785)
-  - Suggested fixture: parse/render normal nested subgraphs today; when collapse metadata appears, either model it explicitly or preserve source as opaque. Never silently drop the `@{ ... }` meaning.
-- [Mermaid v11.3+ `@{ shape: ... }` typed node metadata](https://mermaid.js.org/syntax/flowchart.html) — **safety floor fixed as BUILD-23 / [#29](https://github.com/adewale/agentic-mermaid/issues/29); full typed-shape vocabulary remains #44**
-  - Why it matters: this syntax carries the ISO 5807/ANSI X3.5 flowchart symbol vocabulary (manual input, document, delay, preparation, …); Mermaid's docs use it extensively, so agent-generated sources will contain it.
-  - Current behavior (June 2026): the three issue #29 repro classes are pinned by `src/__tests__/flowchart-metadata.test.ts`; they no longer silently drop targets/edges or fabricate `shape`/`label` phantom nodes. Unsupported forms preserve source opaquely; supported label metadata renders as a conservative rectangle fallback.
-  - Future fixtures: #44 should model the full Mermaid v11 typed-shape vocabulary without weakening the no-silent-loss safety floor.
-- [Mermaid frontmatter `config.layout`/`config.look`](https://mermaid.js.org/intro/syntax-reference.html) — **wrapper-fidelity gaps found by probing the official examples, fixed as BUILD-21**
-  - Why it mattered: round-tripping a diagram through the editor flattened `config:`-nested frontmatter to top-level keys Mermaid ignores (silently killing the author's layout/look request on interop), duplicated `%%{init}%%` directives into synthesized frontmatter, and dropped leading comments.
-  - Current coverage: `src/__tests__/agent-wrapper-fidelity.test.ts` pins byte-verbatim wrapper round-trip (frontmatter, directives incl. multiline, leading comments, combined), mutation wrapper preservation, canonical-mode config nesting + directive folding, and the `COMMENT_DROPPED` lint matrix.
-
-## Fork-network layout search notes
-
-A May 2026 GitHub issue/PR search found recurring layout-quality themes in both Mermaid and Beautiful Mermaid:
-
-- [mermaid-js/mermaid#6049 — Flowchart ugly self linking nodes](https://github.com/mermaid-js/mermaid/issues/6049)
-  - Fixture status: `src/__tests__/aesthetic-issue-regressions.test.ts` renders a flowchart self-loop and asserts the loop has no hard geometric defects; `src/__tests__/layout-quality-heuristics.test.ts` keeps the broader self-loop clearance guard.
-- [mermaid-js/mermaid#5060 — Avoidable overlapping curves in flow-chart](https://github.com/mermaid-js/mermaid/issues/5060)
-  - Fixture status: `src/__tests__/aesthetic-issue-regressions.test.ts` renders repeated parallel labeled edges and asserts distinct edge paths, zero crossings, no hard defects, and separated label boxes.
-- [mermaid-js/mermaid#6046 — subgraph links should affect positioning more than inter-graph links](https://github.com/mermaid-js/mermaid/issues/6046)
-  - Fixture idea: nested subgraphs with invisible/loose links. Assert group order follows source intent and cross-group edges do not dominate internal layout.
-- [mermaid-js/mermaid#7492 — C4 overlapping labels/text overflow/crossing arrows](https://github.com/mermaid-js/mermaid/issues/7492)
-  - Fixture idea: labels near containers. Assert text stays inside boxes and edge labels keep minimum clearance from unrelated nodes.
-- [mermaid-js/mermaid#2792 — graph lines sometimes overlap boxes](https://github.com/mermaid-js/mermaid/issues/2792)
-  - Fixture status: `src/__tests__/aesthetic-issue-regressions.test.ts` renders a transitive route and asserts the ugly-detector reports no edge-through-node defect.
-- [lukilabs/beautiful-mermaid#83 — TD/TB flowchart layout flipping horizontal](https://github.com/lukilabs/beautiful-mermaid/issues/83)
-  - Fixture idea: vertical process with repeated feedback edges. Assert TD/TB diagrams remain height-dominant or within a bounded aspect ratio.
-- [lukilabs/beautiful-mermaid#68 — fan-in groups not target-aware](https://github.com/lukilabs/beautiful-mermaid/issues/68)
-  - Fixture idea: multiple roots feeding separate targets. Assert roots cluster by target and unrelated routes do not share misleading trunks.
-- [lukilabs/beautiful-mermaid#63 — misleading edge overlap in routing](https://github.com/lukilabs/beautiful-mermaid/pull/63)
-  - Fixture idea: two fan-in edges followed by two fan-out edges. Assert an outgoing branch does not visually reuse an unrelated incoming corridor.
-- [lukilabs/beautiful-mermaid#89 — CJK subgraph title layout drift](https://github.com/lukilabs/beautiful-mermaid/issues/89)
-  - Fixture idea: fullwidth group labels. Assert group header bounds account for CJK width.
-- [lukilabs/beautiful-mermaid#121 — ER/class ASCII labels truncated/overlapping](https://github.com/lukilabs/beautiful-mermaid/issues/121)
-  - Fixture status: representative class/ER golden files now assert labels survive and connectors remain attached; keep this theme in the generated matrix for longer label/attribute variants.
-
-## Aesthetic-issue coverage audit (issue-keyed)
-
-A June 2026 audit turned the 13 layout-aesthetic complaints in
-[`mermaid-layout-complaints.md`](./mermaid-layout-complaints.md) into an
-explicit coverage ledger. Direct issue-keyed fixtures now guard the complaints
-that can be expressed against supported diagram families; broader existing
-assertions are tagged where they already covered the behavior; unsupported,
-deferred, and policy-out-of-scope cases remain recorded below.
-
-- **Issue-keyed regression fixtures** —
-  [`src/__tests__/aesthetic-issue-regressions.test.ts`](../src/__tests__/aesthetic-issue-regressions.test.ts)
-  renders a small repro graph per complaint and asserts, through the real
-  renderer, that Agentic Mermaid does not exhibit it: `#6476` (avoidable edge
-  crossings → 0 on a planar bipartite graph), `#5601` (planar state diagram
-  stays planar), `#5060` (parallel labeled edges use distinct rendered paths,
-  keep labels separate, and produce no geometric defects),
-  `#2792` (transitive edge does not pass through an intervening node, via the
-  ugly-detector `edge-through-node` check), `#2131` (edge labels keep
-  clearance from unrelated nodes and from each other), and `#6336`/`#6049`
-  (state and flowchart self-loops render without hard defects).
-- **Tagged existing assertions** (now greppable by issue number): `#815`
-  (declared node/source order — `agent-auth-flow.test.ts`,
-  `layout-quality-heuristics.test.ts`), `#1984`/`#3262` (scale-collapse
-  whitespace + aspect — `agent-quality.test.ts`), `#1301` (long-range Gantt
-  axis labels stay clear of task bars — `gantt-layout.test.ts`), and `#1765` (activation/note/block
-  clearance — `sequence-layout.test.ts`).
-- **`#7492` (C4 overlapping labels/arrows)** — no fixture yet: the C4 family
-  is not rendered. Tracked under **BUILD-6** (new upstream families); add the
-  fixture when C4 lands.
-- **`#3723` (same-rank constraint) and `#5420` (manual node positioning)** —
-  documented **won't-do by policy**, no fixture. `#3723` is "watch-only"
-  (adopt only if Mermaid core standardizes a `config:` key — see C6); `#5420`
-  is out of scope (the agent loop is the substitute — see C1). Neither is a
-  bug we can regression-guard, because not implementing them is the decision.
-
-These guards assert "Agentic Mermaid does not exhibit the complaint," not
-"the upstream Mermaid bug is fixed" — every cited issue is a defect in
-mermaid-js's own dagre renderer, which this fork does not share (see
-[`mermaid-layout-complaints.md`](./mermaid-layout-complaints.md) R4).
-
-## Programmatic bad-layout heuristics
-
-Current useful heuristics:
-
-- `verifyMermaid` warnings: `OFF_CANVAS`, `GROUP_BREACH`, `NODE_OVERLAP`, `ROUTE_SELF_CROSS`, `LABEL_OVERFLOW`, `DUPLICATE_EDGE`, `UNREACHABLE_NODE`;
-- `measureQuality(layoutMermaid(d))` / `checkQuality(...)`: edge crossings, label legibility, whitespace balance, edge-label clearance from non-attached nodes, other edge labels, and other edge paths, and aspect ratio;
-- issue-keyed fixtures that gate selected repro diagrams individually, including zero crossings and label-vs-label box separation for parallel edge labels;
-- family-specific geometry assertions, such as Auth Flow's source-order progression and backward feedback-edge routing;
-- layout-quality heuristic tests for declared-direction progress (`TD`/`BT`/`LR`/`RL`), edge-vs-node collisions excluding attached endpoints, feedback-process cleanliness, root node vs top-level subgraph source order, and self-loop clearance;
-- PNG/SVG screenshot comparison for artifacts that layout JSON cannot see, such as rounded-fill raster artifacts.
-
-High-value next heuristics for layout-improvement corpora:
-
-- route corridor reuse by unrelated edge families;
-- target-aware fan-in/fan-out clustering score;
-- group-header text fit, especially with CJK/fullwidth labels.
-
-Convention-derived validator candidates (from the ANSI X3.5/ISO 5807
-drafting conventions catalogued in
-[`mermaid-layout-complaints.md`](./mermaid-layout-complaints.md) R3 —
-practitioner guides consistently name these as the top flowchart mistakes):
-
-- **unlabeled decision branches**: a diamond node with two or more outgoing
-  edges where any edge lacks a label — cheap Tier 3 lint candidate
-  (`DECISION_BRANCH_UNLABELED`); complements issue #25 §8.2 diamond port
-  semantics;
-- **entry/exit shape**: flowcharts conventionally have one start (a single
-  in-degree-0 node) and clearly marked endpoints (at least one sink) —
-  fits issue #26 workstream 14 as an analysis fact alongside the existing
-  graph entry/feedback-edge outputs, not as a hard error.
-
-These can drive a generated fixture matrix: vary direction, feedback-edge density, self-loops, parallel edges, label length, CJK labels, nested subgraphs, fan-in/fan-out shape, and styling. Each generated case should assert semantic preservation first, then one or more layout heuristics. Screenshot tests should be reserved for cases where the visual artifact is genuinely pixel/raster-level.
-
-## Test-design rules for issue fixtures
-
-- Prefer smallest meaningful source examples over screenshots alone.
-- Assert semantics first: labels, edges, groups, source-preserved metadata.
-- Add screenshot/SVG regression only when geometry/visual polish is the bug.
-- For unsupported Mermaid syntax, assert opaque/source-preserved fallback rather than lossy normalization.
-- For security issues, assert both removal of dangerous refs and preservation of safe SVG output.