agentic-mermaid 0.1.2 → 0.3.0

package/docs/fork-differences.md

@@ -0,0 +1,166 @@
+# 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`) — registry-checked tools: Code Mode `execute` in per-request Dynamic Worker isolates, `describe_sdk` for one family's mutation schema on demand, 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.
+
+Every registered family is structured when narrowed; segment-preserving families retain unsupported statements in source order, and any whole-body fallback round-trips losslessly. Layout is deterministic and verified byte-identical across processes, and `verifyMermaid` returns structured structural, geometric, and lint warnings plus perceptual quality metrics 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
+- Mindmaps (`mindmap`) with indentation-sensitive hierarchy, shapes, icons, and classes
+- Git graphs (`gitGraph`) with deterministic replayed commits, branches, merges, and cherry-picks
+- Radar charts (`radar-beta`) — spider/star charts plotting multivariate profiles across equi-angular axes from a shared center
+
+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.
+
+## Migrating from upstream: every export this fork does not have
+
+Upstream Beautiful Mermaid's entry point exports 16 names. Ten are still
+exported here with the same meaning: `renderMermaidSVG`, `renderMermaidASCII`,
+`renderMermaidSVGAsync`, `fromShikiTheme`, `DEFAULTS`, and the `RenderOptions`,
+`AsciiRenderOptions`, `DiagramColors`, `MermaidGraph`, and `PositionedGraph`
+types.
+
+These six are not, and each fails differently. `THEMES` is the one that bites
+hardest, because destructuring it yields `undefined` rather than an import
+error, so the failure lands later and elsewhere.
+
+| Upstream | Replacement | Notes |
+|---|---|---|
+| `THEMES` | `{ style: 'name' }` | Theme **names** survive as style names; the map does not. `THEMES['zinc-dark']` → `{ style: 'zinc-dark' }`. |
+| `ThemeName` | `string`, validated by `knownStyles()` | Style names are open — custom styles register at runtime — so there is no closed union to import. |
+| `parseMermaid` | `parseRegisteredMermaid` | **Different shape.** Upstream returns a `MermaidGraph` directly; this returns a result: `{ ok: true, value }` or `{ ok: false, error }`. Check `ok` instead of catching. |
+| `renderMermaid` | `renderMermaidSVGAsync` | Upstream alias for the async SVG renderer. |
+| `renderMermaidSync` | `renderMermaidSVG` | Upstream alias; `renderMermaidSVG` is already synchronous here. |
+| `renderMermaidAscii` | `renderMermaidASCII` | Casing-only alias upstream. This fork exports the capitalised spelling only. |
+
+So a `THEMES` port fails at runtime with `TypeError: Cannot read properties of
+undefined (reading 'zinc-dark')`, while `parseMermaid` fails at import — and the
+three aliases fail at import too, which is the easy case.
+
+`zinc-light`, `zinc-dark`, `dracula`, `nord`, `tokyo-night`, and the rest of the
+upstream theme names are all valid style names; `knownStyles()` lists every
+registered one.
+
+`src/__tests__/upstream-export-migration.test.ts` keeps this table honest: it
+reads upstream's own type declarations and fails if an upstream export is
+neither exported here nor documented above.
+
+## 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/#deflate:q1Yqzi8tSk5VslJKy8kvT85ILCpRCHGKyVNQUFBINtTVtUs0gnCKS5PSixILMhTy81IhIonI0ql5KWjqSsrzISJJIHVJuNVlFKVCTQRbmIxQqVQLAA).
+
+  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

@@ -0,0 +1,182 @@
+# 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 every registered diagram family (including flowchart, sequence,
+class, ER, state, Gantt, Mindmap, and GitGraph) — 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)
+```
+
+Portable PNG controls are `scale` (default `2`, for retina), `background`, and
+the mutually exclusive `fitTo: { width? }` / `fitTo: { height? }`; the same
+controls are available through the browser adapter, CLI, and local/hosted MCP.
+Node/Bun additionally accepts trusted-host `fontDirs`, `loadSystemFonts`, and
+the library-only `onWarning` callback.
+
+## 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
+
+Build a palette from two colors, or select one discovered through
+`knownStyleDescriptors()` or `am styles`. Colors are applied
+as CSS variables, so the SVG stays self-contained.
+
+```ts
+import { renderMermaidSVG } from 'agentic-mermaid'
+
+// Two-color palette
+const dark = renderMermaidSVG('flowchart TD\n  A --> B', {
+  bg: '#1a1b26',
+  fg: '#a9b1d6',
+})
+
+// A built-in palette (zinc-light, tokyo-night, nord, dracula, catppuccin-mocha, …)
+const themed = renderMermaidSVG('flowchart TD\n  A --> B', {
+  style: '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 Palettes 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` |
+| Palettes (`knownStyleDescriptors`, `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. After the local
+install above, use the package runner so the command resolves without a global
+install:
+
+```bash
+npx --no-install agentic-mermaid render diagram.mmd --format svg
+npx --no-install agentic-mermaid render diagram.mmd --format png --output diagram.png
+npx --no-install agentic-mermaid render diagram.mmd --format ascii
+```
+
+Run `npx --no-install agentic-mermaid --help` for the full command set. Inside
+an npm script, the shorter `am …` binary name is available automatically.
+
+## 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

@@ -0,0 +1,163 @@
+# Issue-derived coverage evidence
+
+Status: evidence and coverage inventory, not a fixture backlog. Root `TODO.md` is
+the sole authority for scheduled work. Uncovered fixture and heuristic ideas
+below are unscheduled unless a stable root TODO item promotes them.
+
+These public Mermaid / Beautiful Mermaid issues explain what the existing
+fixtures cover and preserve candidate evidence for future decisions. The goal is
+not to clone every upstream bug; it is to retain 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.
+
+## Candidate fixture evidence (unscheduled)
+
+- [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.
+  - Candidate coverage: #44 records the full Mermaid v11 typed-shape vocabulary without weakening the no-silent-loss safety floor; this ledger does not schedule it.
+- [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)
+  - Candidate fixture evidence: nested subgraphs with invisible/loose links; group order follows source intent and cross-group edges do not dominate internal layout.
+- [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)
+  - Candidate fixture evidence: vertical process with repeated feedback edges; 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)
+  - Candidate fixture evidence: multiple roots feeding separate targets; 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)
+  - Candidate fixture evidence: two fan-in edges followed by two fan-out edges; 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)
+  - Candidate fixture evidence: fullwidth group labels; 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`).
+- **`#3723` (same-rank constraint)** — planned under `BUILD-24` as typed
+  request/mutation metadata, not new Mermaid syntax; its fixture lands with
+  that implementation. **`#5420` (manual node positioning)** remains out of
+  scope: arbitrary coordinates and dragging are distinct from structural
+  auto-layout constraints. There is therefore no #5420 regression fixture.
+
+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.
+
+Candidate heuristic evidence (unscheduled):
+
+- 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.
+
+If promoted through root `TODO.md`, these could drive a generated fixture matrix
+varying direction, feedback-edge density, self-loops, parallel edges, label
+length, CJK labels, nested subgraphs, fan-in/fan-out shape, and styling. Each
+case would assert semantic preservation first, then one or more layout
+heuristics; screenshot tests would be reserved for genuinely pixel/raster-level
+artifacts.
+
+## Test-design rules for issue fixtures
+
+- Prefer smallest meaningful source examples over screenshots alone.
+- Assert semantics first: labels, edges, groups, source-preserved metadata.
+- Use 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.

package/docs/mcp-code-mode-rationale.md

@@ -0,0 +1,108 @@
+# MCP Code Mode rationale
+
+Local `agentic-mermaid-mcp` is intentionally Code Mode first. Its primary tool is `execute(code)`, which runs synchronous JavaScript against the typed `mermaid.*` SDK in a local `node:vm` sandbox. This is a local implementation inspired by Code Mode as a product shape; it is not Cloudflare Codemode, not backed by `@cloudflare/codemode`, and not an OS/container security boundary. The local helper tools (`describe_sdk`, `render_png`, and `describe`) are narrow conveniences, not a second full authoring API.
+
+There is now also a **hosted** MCP at `https://agentic-mermaid.dev/mcp` (stateless Streamable HTTP; see the [as-built record](./project/archive/hosted-mcp-cloudflare-plan.md)). It keeps `execute` but runs agent code in a per-request Cloudflare Dynamic Worker isolate (`globalOutbound: null`, empty env, `cpuMs` budget) instead of a local `node:vm` — there the isolate configuration *is* the security boundary — and adds `describe_sdk` plus direct `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` tools so schema discovery and common render/verify paths avoid a billable isolate, plus the declarative `mutate`/`build` tools (see below). Both share the same hardened `mermaid.*` facade; their semantics are pinned against each other by a differential test suite, with one explicit host-policy divergence: both hosted `renderMermaidSVG*` execute methods and the direct `render_svg` tool force `security: 'strict'` and `embedFontImport: false`, even if agent code asks for weaker values. Local Code Mode retains the library's caller-selectable policy.
+
+## Why the MCP server exists
+
+Agents often need a multi-step diagram transaction:
+
+1. parse source;
+2. narrow to a mutable family;
+3. apply one or more typed mutations;
+4. verify and inspect the result;
+5. serialize only after verify passes.
+
+As separate MCP tools, that workflow becomes many tool calls and loses useful in-call state. In Code Mode it is one call: the agent writes the small algorithm and the server preserves lineage/tracing inside the execution.
+
+## Code Mode first, plus a narrow declarative edit surface
+
+Code Mode stays the primary tool for multi-step logic. But `execute` asks the
+model to write correct sandboxed JavaScript, and a weaker model drives that
+poorly (serialization pitfalls, provenance rules, sync-only constraints) when
+all it wanted was to apply a few structured edits. So the hosted surface adds
+exactly **two** declarative tools — `mutate` (edit a `source`) and `build`
+(author from a `family`) — that take a JSON op list and return one canonical
+`{ ok, family, source, verify }` envelope. They run verify internally and only
+emit source when it passes, so the verify-before-commit contract holds without
+the model writing it. Both funnel through the same validated `mutateChecked`
+core as Code Mode's `mermaid.mutate`, so an op is rejected identically either
+way — there is no second implementation to drift.
+
+We still do **not** explode the surface into `parse`/`narrow`/`serialize`/… as
+separate tools: those are the composable steps `execute` exists to sequence in
+one call, and a full per-operation MCP API would multiply round trips, weaken
+in-call lineage, and be another public contract to keep in lockstep. `mutate`
+and `build` are the deliberate exception because a *structured edit* is the one
+workflow that (a) is common, (b) needs no arbitrary logic, and (c) a weak model
+gets wrong through `execute`. For everything richer, use `execute`, the CLI
+(`am mutate --ops`, `am verify`, `am render`), or a library import.
+
+## What the non-Code-Mode MCP tools are for
+
+Local MCP keeps only three helpers:
+
+- `describe_sdk({ family, detail })` returns version-matched mutation operations for one family without running Code Mode. `detail: "signatures"` returns a compact menu; `detail: "fields"` returns the exact field schema. The initial `execute` declaration stays limited to the core SDK, while `mermaid.describeOps` and `mermaid.opSignatures` expose the same registry inside an execution.
+
+- `render_png(source)` exists because PNG is binary output and returning base64 from a dedicated MCP tool is simpler than putting binary handling into Code Mode snippets. Local and hosted tools share portable `scale`, `background`, and mutually exclusive `fitTo.width`/`fitTo.height` controls; local additionally accepts trusted-host `fontDirs`/`loadSystemFonts` remedies and returns deterministic configuration/font-coverage warnings. For clients that cannot comfortably carry large base64 payloads, `render_png({source, output:"file"})` writes a managed local artifact and `output:"url"` returns an HTTP-served artifact when the server runs with HTTP/SSE transport. Because those modes create managed files, the local tool is annotated as non-read-only and non-idempotent.
+- `describe(source)` exists because one-shot natural-language summaries are common for screen readers, docs, and context compaction.
+
+The hosted endpoint adds the same direct discovery tool and direct pure tools (`render_svg`, `render_ascii`, `render_png`, `verify`, `describe`) because every hosted `execute` contacts a Dynamic Worker; schema discovery and common render/verify calls should be ordinary Worker invocations eligible for the private compute cache. Hosted `mutate` and `build` are the only declarative authoring tools, and they exist to apply typed op lists with the verify-before-emit contract without asking a weaker model to write JavaScript. They do not introduce a separate mutation engine.
+
+Direct render tools accept shared render fields only through the canonical
+nested `options` object, generated from the shared RenderOptions descriptors.
+Palette selection uses `options.style`; `theme` and top-level
+`bg`/`fg`/`style`/`seed` are not tool inputs.
+
+Local managed artifacts are generated under one exclusively owned server artifact directory with safe names, per-file and aggregate limits, persisted TTL cleanup, MIME type, byte count, and SHA-256 integrity metadata; they are not arbitrary user-chosen file writes. A second live owner fails closed instead of racing a stale manifest. Hosted `render_png` returns base64 only.
+
+## Equivalence example
+
+`examples/mcp-vs-cli-complex-diagrams.ts` builds the same complicated diagrams two ways: an Auth Flow flowchart with feedback loops and an Order Domain ER diagram.
+
+- MCP Code Mode: `tools/call execute` runs parse → narrow → mutate[] → verify → serialize.
+- CLI: `am mutate <diagram>.mmd --ops ops.json --json` runs the same typed mutation batch and verify-before-emit contract.
+
+The example asserts that both channels produce byte-identical Mermaid source for every case. This is the supported equivalence story: **MCP Code Mode and CLI/library can produce the same diagrams**. Hosted `mutate`/`build` are a bounded shortcut for the same typed op-list workflows, not a replacement for Code Mode when custom control flow is needed.
+
+## Transports
+
+The default transport is stdio for local MCP clients:
+
+```sh
+agentic-mermaid-mcp
+```
+
+HTTP/SSE reachability is available when a client needs a network endpoint. See [`mcp-http-transport.md`](./mcp-http-transport.md) for the full quickstart, JSON-RPC examples, option table, and security defaults:
+
+```sh
+agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000 \
+  --artifact-dir .agentic-mermaid-artifacts
+```
+
+The HTTP transport exposes `/sse` for MCP SSE sessions, `/message?sessionId=...` for session messages, `/rpc` for direct JSON-RPC tests/integrations, `/health`, and `/artifacts/<name>` for managed outputs. It binds to loopback by default; non-loopback binding requires `--auth-token`, and `/rpc`/`/message` require `content-type: application/json` so browser-simple CSRF posts are rejected. Use an explicit host only when you have reviewed the sandbox and artifact exposure boundary.
+
+Example stdio `.mcp.json` entry:
+
+```json
+{
+  "mcpServers": {
+    "agentic-mermaid": {
+      "command": "npx",
+      "args": ["-y", "agentic-mermaid-mcp"]
+    }
+  }
+}
+```
+
+Example HTTP launch command for clients that manage MCP SSE URLs separately:
+
+```sh
+npx -y agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000
+# non-loopback requires --auth-token <token>
+```
+
+## When to add more MCP tools
+
+Add another non-Code-Mode MCP tool only with evidence that a real client cannot use `execute`, hosted `mutate`/`build`, or the CLI/library path. Until then, keep the surface small: one compositional tool, direct pure render/verify/describe tools where they avoid hosted isolate cost, and the two declarative structured-edit tools.