agentic-mermaid 0.4.1 → 0.5.3

package/docs/fork-differences.md

@@ -2,6 +2,16 @@
 
 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.
 
+Scope checked on **2026-10-17**: Agentic source at
+[`3ef2fb8`](https://github.com/adewale/agentic-mermaid/tree/3ef2fb8beff21359fb6e3b798e025a3d69311539),
+Beautiful main at
+[`2ac8bbbb`](https://github.com/lukilabs/beautiful-mermaid/tree/2ac8bbbb060ca0a65a6a21f3200bd99b1587b488)
+and the package comparator `beautiful-mermaid@1.1.3`. Source capability is not
+deployment evidence: Agentic source declares 0.4.2, while npm and the public
+site/MCP still serve 0.4.1 at this check. See [#378](https://github.com/adewale/agentic-mermaid/issues/378).
+Open PRs are proposals, not upstream releases; the related Zombie/C4 comparison
+and historical-version qualifications are in [`comparison.md`](./comparison.md#zombie-mermaid-and-c4-bloodlines).
+
 ## Live site
 
 The canonical live site is **[agentic-mermaid.dev](https://agentic-mermaid.dev/)** — a Cloudflare Workers Static Assets deployment built from [`website/`](../website):
@@ -10,6 +20,7 @@ The canonical live site is **[agentic-mermaid.dev](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/>
 
+<!-- complete: hosted-mcp-tools -->
 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`.
@@ -22,10 +33,11 @@ Every registered family is structured when narrowed; segment-preserving families
 
 ## New and expanded diagram support
 
-This fork renders a wider set of Mermaid families in both the gallery and editor:
+The checked source renders a wider set of Mermaid families in both the gallery and editor:
 
+<!-- complete: family-ids -->
 - Flowcharts and state diagrams
-- Architecture diagrams (`architecture-beta`)
+- Architecture diagrams (`architecture-beta`, or `architecture`)
 - Sequence diagrams
 - Class diagrams
 - ER diagrams
@@ -33,13 +45,14 @@ This fork renders a wider set of Mermaid families in both the gallery and editor
 - 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
+- Quadrant charts (`quadrantChart`)
 - 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
+- Sankey diagrams (`sankey`, `sankey-beta`) — CSV-style flows whose ribbon widths are conserved across stages (`FLOW_IMBALANCE` flags an unbalanced node)
 
-The live editor has registry-backed example coverage for every built-in family
+The source 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.
 
@@ -85,9 +98,9 @@ three aliases fail at import too, which is the easy case.
 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.
+The table above provides migration guidance. Installed package consumer tests
+check the shipped runtime exports and TypeScript declarations, including refusal
+of removed aliases.
 
 ## Mermaid config and source wrappers
 
@@ -100,6 +113,8 @@ This fork supports Mermaid-style source wrappers before diagram headers, includi
 
 These are merged with `options.mermaidConfig` where supported. XY chart and architecture rendering use this to honor Mermaid-compatible theme/config fields.
 
+Frontmatter is read as Mermaid reads it, with js-yaml's `JSON_SCHEMA` rules, and frontmatter that is not valid YAML rejects the diagram, as in Mermaid. `%%{init}%%` directives keep their lenient reader, because Mermaid reads them with `JSON.parse` rather than YAML.
+
 ## Showcase and editor discovery
 
 Users can discover fork features through:
@@ -112,18 +127,35 @@ Users can discover fork features through:
 ## 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.
+- The version-pinned Beautiful Mermaid 1.1.3 comparison records different decision-branch routing and subgraph-container attachment. Agentic uses facet-mid diamond ports and honors container direction overrides. Inspect the same-source [comparison page](https://agentic-mermaid.dev/comparisons/) for the deployed examples; selected similar or different renders do not establish general parity, merged ancestry or the status of an upstream issue.
+- Implemented here, with upstream proposals still open as of 2026-10-17:
+  fan-in grouping ([Beautiful Mermaid PR #69](https://github.com/lukilabs/beautiful-mermaid/pull/69))
+  and labeled fan-out trunk sharing with box-start connector placement
+  ([PR #113](https://github.com/lukilabs/beautiful-mermaid/pull/113)). Open proposals
+  are not evidence of upstream release inclusion or identical rendering.
 - 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
+## Parser semantics and migration boundaries
+
+**Membership has two stages: collect candidates, then resolve ownership.**
+Flowchart and ER use the shared **first-subgraph-to-close** rule for competing
+candidates: at each `end`, keep candidates not already owned by an earlier-closed
+subgraph, once each. An inner subgraph closes before its enclosing subgraph.
+Creation and membership are separate decisions:
 
-- **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:
+- Flowchart node statements and edge endpoints collect their identities in the
+  current subgraph, even when already known. A `style` statement that creates a
+  node does not collect it. References to a declared subgraph collect its group
+  identity, independently of whether its declaration precedes the reference.
+  Group references resolve after declarations close; the result is a tree, so
+  a reference cannot make a group contain itself or one of its ancestors.
+- ER collects entity declarations and entity endpoints of relations, even for
+  entities already named at top level. A prior top-level mention does not prevent
+  a later ER subgraph from keeping that entity. A style directive alone does not
+  collect an entity; a relation endpoint naming an already-opened group refers
+  to its boundary. A reference before that group's declaration creates an entity.
+
+For example:
 
   ```mermaid
   flowchart TB
@@ -139,22 +171,56 @@ Users can discover fork features through:
       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).
+Here `one` keeps `a1` and `a2`, and `three` keeps `c1` and `c2`. The earlier edge
+created `c1` and `a2` without assigning a group. When two subgraphs collect the
+same candidate, the one that closes first keeps it. A later cross-group link
+does not move an identity out of an already-closed owner. Serialization emits
+this resolved membership before links so the same rule applies on re-reading.
+
+The [Flowchart candidate collector](https://github.com/adewale/agentic-mermaid/blob/3ef2fb8beff21359fb6e3b798e025a3d69311539/src/parser.ts#L1276-L1321),
+[shared membership authority](https://github.com/adewale/agentic-mermaid/blob/3ef2fb8beff21359fb6e3b798e025a3d69311539/src/shared/subgraph-membership.ts)
+and [ER public-boundary regressions](https://github.com/adewale/agentic-mermaid/blob/3ef2fb8beff21359fb6e3b798e025a3d69311539/src/__tests__/er-subgraph-membership.test.ts)
+record this rule. Agreement on this grammar decision is not a promise of
+Mermaid pixel/layout parity. Current deliberate reader extensions and source
+preservation limits live in [`project/divergences.md`](./project/divergences.md).
+
+State resolves authored identities and scopes before building either the
+editable body or the render graph. A reference inside a composite can establish
+the scope of a later definition; a root reference alone establishes no parent.
+Each identity belongs to one scope, and a composite retains its first placement
+when reopened. Initial and final `[*]` endpoints each name one pseudostate per
+scope, with independent identities in concurrent regions. Generated region and
+endpoint names cannot alias authored names.
+The writer checks its emitted ownership against the typed body using that same
+resolver. An edit that cannot retain the requested scope returns an error;
+for example, moving a state to root while a transition inside its former
+composite would claim it again. Move or remove the conflicting transition first.
+
+Named floating notes (`note "text" as N`) retain their text and scope in
+`StateBody.floatingNotes`. Their identities are independent of state identities,
+so a state and a note may both be named `N`. The State operations
+`add_floating_note`, `set_floating_note_text` and `remove_floating_note` edit
+these annotations. Scope rename, removal and dissolution carry the annotations
+with their scope; serialization, SVG and terminal rendering preserve them.
+
+### ER parent endpoints
+
+ER's left endpoint can use `u` for the parent marker, independently of the four
+crow's-foot cardinalities. The native and typed models retain `parent`; SVG
+draws a hollow diamond and terminal output draws `◇` (`o` in plain ASCII). The
+writer and `add_relation` admit this marker only before the connector, where
+pinned Mermaid's lexer accepts it.
+
+### Sequence text controls
+
+Sequence `wrap:` and `nowrap:` are source controls, separated from text before
+entity decoding. Messages, notes, participant aliases, box titles and fragment
+captions retain the control; explicit controls override the diagram default.
+SVG measures wrapped text with a pixel budget; terminal output uses its own cell
+budget. An explicit `nowrap:` still preserves authored line breaks. Typed text
+edits retain the control, and typed strings beginning with control-like text are
+encoded as literal text. `set_message_wrap` and `set_fragment_message_wrap` accept
+`true`, `false`, or `null` to restore inheritance.
 
 ## What is intentionally not in this fork
 
@@ -164,3 +230,10 @@ Users can discover fork features through:
 ## 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.
+
+## Original upstream assertion runs
+
+The [original assertion runner](../eval/mermaid-upstream-assertions/README.md)
+executes pinned source test bodies rather than harvested input samples. Its
+family breakdown distinguishes native refusals, assertion mismatches, unmapped
+APIs, reference-control failures, skips and collection errors.

package/docs/getting-started.md

@@ -1,12 +1,10 @@
-# Getting started (library)
+# Getting started
 
-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.
+Render Mermaid source to SVG, PNG or terminal text. The examples below use
+`agentic-mermaid/agent`, one entry for rendering and typed editing in Node 22+
+or Bun 1.4.0+. Browser rendering has a separate asynchronous entry, shown below.
 
-> 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.
+For editing operations, continue with the [editing cookbook](agent-api-cookbook.md).
 
 ## Install
 
@@ -15,6 +13,8 @@ npm install agentic-mermaid
 # or: bun add agentic-mermaid / pnpm add agentic-mermaid
 ```
 
+### Repository development
+
 For repository development, install from source:
 
 ```bash
@@ -29,21 +29,13 @@ 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'
+import { writeFileSync } from 'node:fs'
+import { renderMermaidSVG } from 'agentic-mermaid/agent'
 
 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'))
+writeFileSync('diagram.svg', svg)
 ```
 
 ## Render to PNG
@@ -64,9 +56,11 @@ const png = renderMermaidPNG(`flowchart TD
 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.
+Portable PNG controls are `scale` (default `2`, for retina), `background`,
+the mutually exclusive `fitTo: { width? }` / `fitTo: { height? }`, and
+`minLabelPx` (legibility floor, default `9`; `0` disables the
+`BELOW_READABLE_SIZE` warning); 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.
 
@@ -76,7 +70,7 @@ Great for terminals, code reviews, and plain-text logs. Unicode box-drawing is t
 default; pass `{ useAscii: true }` for pure ASCII.
 
 ```ts
-import { renderMermaidASCII } from 'agentic-mermaid'
+import { renderMermaidASCII } from 'agentic-mermaid/agent'
 
 const unicode = renderMermaidASCII('flowchart LR\n  A --> B')
 const ascii = renderMermaidASCII('flowchart LR\n  A --> B', { useAscii: true })
@@ -93,7 +87,7 @@ Build a palette from two colors, or select one discovered through
 as CSS variables, so the SVG stays self-contained.
 
 ```ts
-import { renderMermaidSVG } from 'agentic-mermaid'
+import { renderMermaidSVG } from 'agentic-mermaid/agent'
 
 // Two-color palette
 const dark = renderMermaidSVG('flowchart TD\n  A --> B', {
@@ -118,52 +112,63 @@ Common `RenderOptions`: `bg`, `fg`, `font`, `transparent`, and `security`. See
 ### 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.
+the web-font `@import` and rejects output with external-fetch references. See
+[the security boundary](../SECURITY.md) for the guarantees and limits.
 
 ```ts
-import { renderMermaidSVG } from 'agentic-mermaid'
+import { renderMermaidSVG } from 'agentic-mermaid/agent'
 
+const userProvidedSource = 'flowchart TD\n  A --> B' // replace with input from your application
 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:
+Use the browser ESM entry in client components. It avoids the Node/native entry
+and loads only the selected diagram family:
 
-```tsx
-import { useMemo } from 'react'
-import { renderMermaidSVG } from 'agentic-mermaid'
+```ts
+import { renderMermaidSVGAsync } from 'agentic-mermaid/browser/lazy'
 
-function Diagram({ code }: { code: string }) {
-  const svg = useMemo(() => renderMermaidSVG(code), [code])
-  return <div dangerouslySetInnerHTML={{ __html: svg }} />
-}
+const svg = await renderMermaidSVGAsync('flowchart LR\n  A --> B', {
+  security: 'strict',
+  idPrefix: 'example-diagram', // use a unique prefix per inline diagram
+})
 ```
 
-See [`react.md`](./react.md) for the zero-flash, live-theme-switching setup.
+The returned string is not a DOM-insertion API. Follow [`browser.md`](./browser.md)
+for parsed-XML insertion and CSP policy, or the complete [`React component`](./react.md)
+for cancellation, unique IDs, error handling and live theme switching. For a
+server component or build step, the synchronous `agentic-mermaid` entry remains
+the simpler choice.
 
-## Which import path?
+## Other runtimes and advanced imports
 
-| 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` |
+| Runtime or task | Entry |
+| --- | --- |
+| Node/Bun rendering and typed editing, including native PNG | `agentic-mermaid/agent` |
+| Browser rendering with deferred family loading | `agentic-mermaid/browser/lazy` |
+| Typed editing in a browser or Worker, without native PNG | `agentic-mermaid/agent/core` |
+| Style utilities such as `fromShikiTheme`, or renderer host adapters | `agentic-mermaid` |
 
-`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.
+The root entry remains supported. The agent entry re-exports the synchronous
+renderers but does not include every root utility. See the
+[API reference](api.md) for the full exports and the [browser guide](browser.md)
+for runtime-specific integration.
 
 ## 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:
+install above, create a source file:
+
+```bash
+cat > diagram.mmd <<'MMD'
+flowchart LR
+  A --> B --> C
+MMD
+```
+
+Use the package runner so the command resolves without a global install:
 
 ```bash
 npx --no-install agentic-mermaid render diagram.mmd --format svg
@@ -179,4 +184,4 @@ an npm script, the shorter `am …` binary name is available automatically.
 - [`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).
+- [`agent-api-cookbook.md`](./agent-api-cookbook.md) — typed editing (parse → narrow → mutate → verify → serialize).

package/docs/layout-certification.md

@@ -0,0 +1,126 @@
+# Bounded layout certification
+
+All 17 native families expose layout evidence through the existing SVG, PNG,
+ASCII and layout receipt APIs. `verifyMermaid` includes graphical evidence;
+debug layout includes `paintCertification`, which `measureQuality` and
+`checkQuality` consume. Quality reports paint confidence under its own
+`paintCertification` metric; it does not change the label-fit score. A certificate reports `passed`, `failed` or `unverified`,
+its native coordinate unit, coverage, bounded work and limitations.
+
+```ts
+const result = renderMermaidSVGWithReceipt(source, { layoutSafety: 'strict' })
+console.log(result.receipt.layoutCertification)
+```
+
+The default `report` policy preserves explicit limitations. It still rejects
+proven native text/marker occlusion and enforces production layout-pass
+contracts. `strict` requires a passed final certificate, including for plain
+string renders; missing evidence, exhausted checks, custom graphical backends,
+and unverified interactive states cannot become successful strict renders.
+Output security remains a separate policy.
+
+## Pixel geometry
+
+The graphical checker consumes the admitted Scene from the exact positioned
+artifact and the retained family projection. It does not reparse source or run
+layout again. Text uses the original prepared runs and occupied bands. Typed
+paths, strokes, joins, caps, markers and composed transforms contribute paint
+envelopes. Unknown artwork and lowering-time text fallback are explicit.
+
+One outward viewport expansion can contain these envelopes without moving
+nodes, changing data values, rerouting relationships or changing membership.
+The final viewport is checked again. The SVG keeps its requested display
+dimensions and aspect ratio; its viewBox describes the expanded user-unit region. The receipt
+binds the proof to the secured SVG digest also used for PNG rasterization.
+
+Paint order determines occlusion. A later opaque rectangle that contains a
+whole occupied text region proves that text is hidden. Conservative path
+envelopes, rotated empty corners and partial intersections do not prove hidden
+ink; an unresolved candidate remains unverified. Tree visits and primitive
+comparisons share a 400,000-operation budget, in addition to the 100,000-pair
+limit. Identical marker artwork
+repainted by an owned carrier is evaluated at its final paint position.
+Occlusion scans stop at their explicit comparison budget instead of returning
+a successful result from an unfinished scan.
+
+These are native geometry guarantees. They do not prove every antialiased
+pixel for an arbitrary installed font, host stylesheet, custom backend or
+interactive state. Crisp palettes and role styles use the same retained native
+geometry; rough backends and shadow ink remain outside the proof. Declared translucency and intentional overlap between data
+marks retain their meaning. Text/source correspondence and quantitative chart
+placement remain separate from aesthetic preferences.
+
+## Terminal cells
+
+Terminal proof consumes the final native cell document and exact encoded
+output, independently of pixel geometry. It checks retained measured text,
+wide-grapheme continuations, typed stroke/marker glyphs, ownership,
+memberships, endpoint references and allocated containment frames. Encoded
+ANSI/HTML output is compared with the same retained cells. A renderer returning
+text without a native document is unverified.
+
+Receipt evaluation remains lazy under `report`: text-only callers do not pay
+for a certificate. Strict callers require it before receiving output. The scan
+has explicit operation, output-size and issue limits. Native representation
+choices, such as replacing a continuous curve with cells, are reported
+separately from cell-layout correctness. Unrelated edge shafts may share cells
+as straight perpendicular crossings; declared bundles retain their intentional
+joins. The checker uses each owner's painted direction, so a merged junction
+cannot lend one route another route's stroke.
+
+Explicitly connected routes prove a path through their final visible owned
+stroke and marker cells. An internally allocated immutable path can witness
+that proof, but every point is checked again after composition. Missing, stale
+or ambiguous witnesses use the same bounded traversal and cumulative budget.
+Other routes retain endpoint and marker checks without a complete path proof.
+Full correspondence with authored source remains the family renderer's contract.
+
+Class keeps a valid compact layout. If allocation fails or its actual contacts
+are invalid, bounded recovery reserves separate routes, endpoint labels and
+namespace crossings before painting. It keeps text upright in all four layout
+directions and preserves authored identities, markers and note targets. Unboxed
+interfaces keep their captions and publish the actual owned lollipop as their
+physical surface. Hyperlink footer rows and their complete text extents are
+reserved before recovery is painted; safe links stay inert and unsafe actions
+remain source-only under the existing security policy. Both representations
+still use the same final operation and output limits. An unfinished check cannot
+become a passed certificate.
+
+## Priority and pass budgets
+
+Preserve authored identities, labels, endpoints, membership and chart values.
+Then satisfy hard geometry and content visibility. Route clarity, crossings,
+bends, preferred ports, symmetry and compactness can improve within those
+constraints; a lower-priority preference cannot silently break a higher one.
+
+Production passes enforce their declared order, geometry freeze, metric
+allowances and renewed route certificates. Measurements come from actual
+before/after geometry. Metric requests are selective; enabling a budget does
+not request every rubric metric for every pass. Bounded final graph candidates
+cannot hide a pass-contract error behind another successful layout.
+
+Some priorities require explicit local tradeoffs. Separating ambiguous shared
+duplicate routes can justify a bounded crossing cost for that same proposal.
+Fewer bends alone cannot buy a new crossing. An actual repair of a route through
+a node, a diagonal or an invalid endpoint approach can justify a bounded bend
+cost or losing a preferred port. An endpoint approach is checked against the
+actual shape boundary, separately from its preferred attachment ports.
+Opposite-direction shafts sharing positive-length collinear ink are measured
+separately from ordinary crossings and deliberate same-direction fan trunks.
+A merely symmetric reciprocal lane must keep an already valid canonical
+contact. The owning regressions record these cases alongside the existing final
+hard checks.
+
+Final graph candidates first pass authored correspondence and hard geometry.
+The bounded preference comparison follows the
+[graph priority order](quality.md#layout-priorities-and-their-limits): readable
+group titles, crossings, padded label conflicts, avoidable bends, preferred
+endpoint contacts, peer alignment and canvas area. A candidate with a better
+lower-priority score cannot displace one with a better earlier score. This final
+comparison does not excuse a production pass-contract error.
+
+A repaired viewport with non-scaling strokes is unverified: keeping the display
+size changes the stroke extent in user units. Endpoint checks allow an arrow’s
+stroke to meet its declared endpoint’s owned outline; the marker body must stay
+outside the filled interior. Repaint equality includes resource geometry,
+orientation, stroke units and the composed transform.

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

@@ -1,7 +1,14 @@
 # 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.
-
+<!-- complete: local-mcp-tools -->
+Local `agentic-mermaid-mcp` and hosted MCP expose the same declarative `mutate`
+and `build` tools. Prefer them for ordered structured edits: JSON ops go through
+one shared validator, transaction, and verify-before-emit gate. `execute(code)`
+remains available for custom synchronous logic against `mermaid.*`. Locally it
+runs in `node:vm`, which is not an OS/container security boundary.
+The local helpers are `describe_sdk`, `render_png`, and `describe`.
+
+<!-- complete: hosted-mcp-tools -->
 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
@@ -16,13 +23,13 @@ Agents often need a multi-step diagram transaction:
 
 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
+## Declarative edits first; Code Mode for custom logic
 
-Code Mode stays the primary tool for multi-step logic. But `execute` asks the
+Code Mode handles custom multi-step logic. However, `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`
+all it wanted was to apply a few structured edits. Both surfaces therefore expose
+**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
@@ -41,14 +48,15 @@ gets wrong through `execute`. For everything richer, use `execute`, the CLI
 
 ## What the non-Code-Mode MCP tools are for
 
-Local MCP keeps only three helpers:
+Local MCP also provides 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.
+- `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`, `minLabelPx`, and mutually exclusive `fitTo.width`/`fitTo.height` controls; local additionally accepts trusted-host `fontDirs`/`loadSystemFonts` remedies. Both return deterministic configuration and raster-legibility warnings, with native hosts also reporting glyph coverage. 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.
+<!-- complete: hosted-mcp-tools -->
+The hosted endpoint adds the same direct discovery tool (`describe_sdk`) 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.
@@ -90,7 +98,7 @@ Example stdio `.mcp.json` entry:
   "mcpServers": {
     "agentic-mermaid": {
       "command": "npx",
-      "args": ["-y", "agentic-mermaid-mcp"]
+      "args": ["-y", "agentic-mermaid", "mcp"]
     }
   }
 }
@@ -99,10 +107,10 @@ Example stdio `.mcp.json` entry:
 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
+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.
+Add another non-Code-Mode MCP tool only with evidence that a real client cannot use `execute`, `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.