agentic-mermaid 0.1.1 → 0.2.0

package/docs/code-mode-impact.md

@@ -0,0 +1,214 @@
+# Code Mode in Agentic Mermaid: impact, comparison, and costs
+
+Agentic Mermaid uses Code Mode to keep a diagram edit inside one execution:
+parse the source, narrow it to a mutable family, apply typed operations, verify
+the result, and serialize only after verification passes. This changes both
+the model-facing boundary and the execution boundary. The model writes a small
+algorithm instead of relaying each intermediate diagram through another tool
+call, while the server retains the trusted diagram lineage needed to reject
+forged or invalid edits.
+
+This document uses **local Code Mode** for the self-hosted MCP process running
+on the agent's machine and **hosted Code Mode** for the public
+`https://agentic-mermaid.dev/mcp` endpoint. Cloudflare calls the same split
+client-side and server-side Code Mode. The names describe where the sandbox
+runs, not where the model runs.
+
+## Local Code Mode
+
+The local `agentic-mermaid-mcp` exposes `execute(code)`, which runs synchronous
+JavaScript against the typed `mermaid.*` SDK in a hardened `node:vm` context.
+The execution can retain parsed diagrams between SDK calls, so the model does
+not have to copy an intermediate representation into another JSON request.
+That matters because Agentic Mermaid's mutation checks depend on provenance:
+SDK results are read-only, and structured changes must pass through
+`mermaid.mutate`.
+
+Running beside the agent also keeps diagram source local and avoids hosted
+compute charges. The local server can return managed PNG files or URLs through
+its direct `render_png` helper, while multi-step editing remains in `execute`.
+The [MCP Code Mode rationale](./mcp-code-mode-rationale.md) explains why those
+helpers stay narrow rather than recreating the full SDK as individual tools.
+
+Progressive SDK discovery removed the largest client-side cost. The initial
+`execute` declaration now contains the core SDK, while
+`describe_sdk({ family, detail })` returns the mutation schema for one diagram
+family. An agent that already knows an operation can skip discovery; an agent
+handling an unfamiliar family can request compact signatures or exact fields.
+
+## Hosted Code Mode
+
+The hosted endpoint puts the sandbox behind the MCP server, so an ordinary MCP
+client gets Code Mode without shipping its own execution environment. Each
+hosted `execute` runs in a Cloudflare Dynamic Worker configured with an empty
+environment, `globalOutbound: null`, no subrequests, and a bounded CPU budget.
+The isolate configuration is the security boundary. The hardened SDK facade is
+kept for behavioural parity with the local server.
+
+Hosted execution has a per-call cost, so common pure operations do not enter
+the sandbox. `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`,
+and `describe_sdk` run as ordinary Worker calls whose successful deterministic
+results can be reused by the private server-side Workers Cache. The JSON-RPC
+HTTP responses remain `cache-control: no-store`.
+Declarative `mutate` and `build` apply typed operation lists through the same
+mutation core and verify before returning source. They give smaller models a
+direct path for routine edits while reserving `execute` for control flow that
+the operation list cannot express.
+
+Local and hosted Code Mode share the same `mermaid.*` facade. Differential
+tests compare result envelopes, errors, trace behaviour, read-only enforcement,
+and serialization across both runtimes. The
+[hosted MCP as-built record](./project/archive/hosted-mcp-cloudflare-plan.md) documents
+the remaining runtime differences and abuse controls.
+
+## Measured effect
+
+[PR #157](https://github.com/adewale/agentic-mermaid/pull/157) measured the
+serialized declarations and tool lists with `o200k_base`. These counts are a
+stable before-and-after proxy, not a provider billing claim.
+
+| Model-facing surface | Before | After | Tokens saved |
+|---|---:|---:|---:|
+| `execute` SDK declaration | 10,527 | 903 | 9,624 (91.4%) |
+| Local `tools/list` | 11,781 | 1,840 | 9,941 (84.4%) |
+| Hosted `tools/list` | 15,646 | 2,969 | 12,677 (81.0%) |
+
+The median complete family schema is 495 tokens. A hosted client that loads the
+initial tool list and then requests that schema consumes 3,464 tokens, 77.9%
+less than the old hosted list. The largest family, flowchart, brings the total
+to 4,928 tokens, which is still 68.5% lower. Compact signature responses have a
+113-token median.
+
+The same PR ran four schema-sensitive edits against the exact before and after
+hosted tool lists. Each proposed mutation was replayed through the real
+`applyOps` implementation and checked against semantic facts.
+
+| Model | Before task-correct | After task-correct | After discovery |
+|---|---:|---:|---:|
+| `gpt-5.4-mini` | 3/4 | 4/4 | 4/4 |
+| `gpt-5.3-codex-spark` | 4/4 | 4/4 | 4/4 |
+| **Combined** | **7/8** | **8/8** | **8/8** |
+
+All 16 mutations across both conditions applied successfully. The one incorrect
+before-case omitted a requested Architecture edge label; the after-case kept
+it. The combined four-case prompt fell from 16,048 to 5,833 tokens, a 63.7%
+reduction even though the test prompt included all four family responses at
+once. A normal request discloses one family.
+
+This eval is evidence for the discovery change, not a broad model-quality
+claim. It covers four tasks and two small models. Larger task sets, more model
+families, and production latency measurements remain separate work.
+
+## Comparison with Cloudflare and Anthropic
+
+Agentic Mermaid applies Code Mode to a pure diagram library. Cloudflare and
+Anthropic apply the same technique to general tool catalogs, where generated
+code may call remote services and carry data between them. That scope
+difference explains most of the implementation differences.
+
+| Dimension | Agentic Mermaid | Cloudflare | Anthropic |
+|---|---|---|---|
+| Primary scope | One deterministic diagram SDK | MCP tools and large APIs | General tool catalogs |
+| Discovery | `describe_sdk` for one diagram family | Typed connectors, or `search` over an OpenAPI document | Tool Search, or filesystem-shaped tool definitions |
+| Model-written code | Synchronous JavaScript | Asynchronous JavaScript | Python in Programmatic Tool Calling |
+| Execution | Local `node:vm` or hosted Dynamic Worker | Dynamic Worker isolate | Anthropic Code Execution sandbox |
+| Calls made from code | Pure in-process SDK calls | MCP calls or an authenticated request callback | Developer-provided tools |
+| External effects | None beyond returned diagram artifacts | Allowed through host-controlled bindings and authorization | Allowed for tools that opt into programmatic calling |
+| Persistent state | None | Durable runtime options are available | Filesystem state and reusable skills are possible |
+
+### Cloudflare
+
+Cloudflare's first Code Mode implementation converted connected MCP tools into
+a TypeScript API and ran the model's JavaScript in a Dynamic Worker. Its current
+MCP patterns cover both a single `code` tool, where the complete generated API
+fits in the tool description, and `search` plus `execute`, where a large
+OpenAPI document stays inside the discovery sandbox. Authentication remains in
+the host callback rather than entering generated code.
+
+That general implementation supports asynchronous calls, remote APIs,
+authorization and, in the durable runtime, pause-and-resume approval. Agentic
+Mermaid does not need those facilities because its SDK calls are synchronous,
+pure, and confined to one diagram transaction. It does use the same Dynamic
+Worker substrate for hosted isolation, but it does not depend on
+`@cloudflare/codemode`.
+
+Cloudflare measured its server-side `search` and `execute` surface at roughly
+1,000 tokens for more than 2,500 API endpoints, 99.9% fewer than direct MCP
+definitions. Agentic Mermaid's percentage is not directly comparable because
+its catalog is smaller and its hosted tool list retains more direct helpers.
+
+Sources: [original Code Mode design](https://blog.cloudflare.com/code-mode/),
+[server-side API implementation](https://blog.cloudflare.com/code-mode-mcp/),
+and [current MCP server patterns](https://developers.cloudflare.com/agents/model-context-protocol/codemode/).
+
+### Anthropic
+
+Anthropic's November 2025 architecture generated a filesystem-like tree of MCP
+tool definitions so an agent could inspect only the files it needed. It also
+proposed a `search_tools` alternative with selectable detail levels. The code
+execution environment could filter large results, retain intermediate state,
+and pass data between tools without putting that data into the model context.
+
+Anthropic later shipped the mechanism as Tool Search and Programmatic Tool
+Calling. Deferred tools stay out of the initial prompt, while Python running in
+the Code Execution sandbox can pause for an allowed tool, process the result,
+and continue without sending that result through another model inference.
+Anthropic reported an 85% token reduction for Tool Search in a large catalog,
+along with accuracy gains on its MCP evaluations.
+
+Agentic Mermaid's `describe_sdk` follows the same progressive-disclosure
+principle but uses a family key instead of general search. Its execution model
+is intentionally smaller: no filesystem, no persistence, no arbitrary tool
+catalog, and no asynchronous callback loop.
+
+Sources: [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)
+and [advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use).
+
+## Costs and limits
+
+Progressive discovery moves schema tokens out of the initial prompt, but an
+unfamiliar edit now needs a `describe_sdk` call before `mutate`, `build`, or
+`execute`. That extra round trip is wasted on a small catalog whose definitions
+are used in every session. It pays off here because most diagram tasks use one
+registered family, and the old declarations devoted 93.1% of the hosted tool-list
+tokens to the full SDK and repeated mutation menus.
+
+Code execution also adds work that a direct tool does not need. A one-shot
+render, verification, or straightforward operation list should use the hosted
+direct tools. Models, especially smaller ones, can make JavaScript mistakes or
+violate the SDK's provenance and serialization rules; `mutate` and `build`
+exist because those failures were observed in practice.
+
+The local and hosted sandboxes have deliberate constraints:
+
+- Code Mode is synchronous. It rejects `async`/`await`, Promise jobs, dynamic
+  imports, finalizers, and queued microtasks.
+- Sandbox code has no filesystem, external network, environment variables, or
+  persistent workspace.
+- Local `node:vm` is hardened but is not an operating-system or container
+  security boundary. It is a local tool for trusted use.
+- Hosted execution contacts a billable Dynamic Worker on every call. Worker
+  Loader IDs are content-addressed so identical code can reuse a warm isolate,
+  while direct tools and their private compute cache keep routine work off that
+  path.
+- Hosted `execute` responses are never compute-cached: Code Mode exposes time
+  and randomness, so retaining the first result would violate its observable
+  contract.
+- Local timeouts use wall-clock time, while hosted limits use CPU time. Warm
+  hosted isolates can retain module globals, hosted output is capped, and
+  hosted PNG bytes are not part of the cross-runtime byte-determinism contract.
+
+Keeping intermediate results outside model context is useful only when code
+can decide what to discard. If the model must inspect each intermediate result
+to make a semantic judgment, direct calls may be more appropriate. Anthropic
+makes the same distinction for simple lookups and tasks where Claude should see
+all intermediate data.
+
+## Decision
+
+Because Agentic Mermaid's useful unit of work is a verified diagram
+transaction rather than a general agent computer, its Code Mode surface can
+stay narrow. The model receives the core SDK, requests one family schema when
+needed, and returns reviewable Mermaid source only after the same verifier used
+by the library and CLI has accepted it. That verified source is the outcome by
+which the extra sandbox and discovery call should be judged.

package/docs/comparison.md

@@ -19,11 +19,11 @@ one does, and the final section tells you which to install for common jobs.
 - **Agentic Mermaid** (`agentic-mermaid`, this repo) extends Beautiful
   Mermaid for programs that edit diagrams — AI agents foremost. It adds a
   typed parse → mutate → verify → serialize loop, byte-identical output
-  across runs, structured verification, and CLI/MCP surfaces. The trade is
-  explicit: 12 diagram families against Mermaid's ~25, in exchange for the
-  guarantee that parsing and re-serializing a diagram never drops syntax.
+  across runs, structured verification, and CLI/MCP surfaces. The trade is explicit: the checked registry covers a focused subset of Mermaid's
+  broader catalogue in exchange for the guarantee that parsing and re-serializing
+  a diagram never drops syntax.
 
-Facts below reflect Mermaid ~11.15 and the upstream `beautiful-mermaid`
+Facts below reflect Mermaid 11.16.0 and the upstream `beautiful-mermaid`
 repository as of mid-2026; both projects move quickly, so check their
 changelogs for the current state.
 
@@ -33,16 +33,16 @@ changelogs for the current state.
 |---|---|---|---|
 | Primary job | Define and render the diagram language everywhere | Fast, beautiful, browserless rendering | Agent-safe diagram *editing* plus rendering |
 | Runtime | Browser DOM (Node via Puppeteer/`mermaid-cli`) | Pure TypeScript, zero DOM, synchronous | Pure TypeScript, zero DOM, synchronous |
-| Diagram types | ~25 (flowchart, sequence, class, state, ER, gantt, pie, mindmap, gitgraph, timeline, journey, quadrant, sankey, xychart, block, packet, kanban, architecture, radar, treemap, venn, ishikawa, wardley, treeview, event modeling, …) | 6 (flowchart, state, sequence, class, ER, XY chart) | 12 (those 6 + timeline, journey, architecture, pie, quadrant, gantt) |
+| Diagram types | Broad Mermaid catalogue, including newer experimental families | Flowchart, state, sequence, class, ER, and XY chart | Registry-backed subset listed by `am capabilities --json` |
 | Output formats | SVG (PNG/PDF via CLI tooling) | SVG, ASCII/Unicode | SVG, PNG (offline resvg), ASCII/Unicode, JSON layout |
 | Theming | Theme config + CSS | Two-color foundation, 15+ named themes, Shiki/VS Code compatibility, live CSS-variable switching | Style + Palette stacks: named looks, palette-only styles, custom JSON records, and deterministic seeds |
-| Parse to a typed AST for editing | — (internal parser, not an editing API) | — (render-only API) | ✅ `parseMermaid` → typed `ValidDiagram` |
-| Typed mutation ops | — | — | ✅ 12 of 12 families (101 ops total), structured-or-opaque, never lossy |
+| Parse to a typed AST for editing | — (internal parser, not an editing API) | — (render-only API) | ✅ `parseRegisteredMermaid` → typed `ValidDiagram` |
+| Typed mutation | — | — | ✅ every registered family, structured-or-opaque and never lossy |
 | Structural verification | — | — | ✅ 3 warning tiers + perceptual quality metrics, all families |
 | Deterministic output | Not a goal (browser/layout variance) | Mostly stable, not a tested guarantee | ✅ byte-identical across runs/processes, CI-gated |
 | Round-trip guarantee (parse → serialize keeps your source) | — | — | ✅ verbatim for unmodeled syntax, canonical for structured bodies |
 | CLI | `mermaid-cli` (`mmdc`, Puppeteer-based) | — | `am` (render/verify/mutate/batch/preview/…, single-binary build) |
-| MCP / agent surface | Official hosted MCP (validation, PNG, Mermaid Chart integration) | — | Local Code Mode MCP (`execute`, `render_png`, `describe`) plus hosted `/mcp` (`execute`, render/verify/describe, `mutate`/`build`), `llms.txt`, agent skill |
+| MCP / agent surface | Official hosted MCP (validation, PNG, Mermaid Chart integration) | — | Local Code Mode MCP (`execute`, `describe_sdk`, `render_png`, `describe`) plus hosted `/mcp` (`execute`, progressive schema discovery, render/verify/describe, `mutate`/`build`), `llms.txt`, agent skill |
 | Interactivity (click handlers, animations) | ✅ | Partial (tooltips) | Inherited where upstream has it; not a focus |
 | Ecosystem & docs | Vast — the de-facto standard, GitHub/GitLab/Notion render it natively | Growing, popular for terminal/AI use | Small; this repo |
 
@@ -61,7 +61,7 @@ enriched palettes and Shiki theme compatibility; ASCII/Unicode terminal
 output. Agentic Mermaid inherits all of this — it is upstream's work, and
 credit belongs there.
 
-**Only Agentic Mermaid:** the typed editing loop. `parseMermaid` returns a
+**Only Agentic Mermaid:** the typed editing loop. `parseRegisteredMermaid` returns a
 sealed IR; family narrowers (`asFlowchart` … `asXyChart`) expose typed
 mutation ops; `verifyMermaid` returns structured warnings instead of asking
 an agent to eyeball pixels; `serializeMermaid` round-trips losslessly
@@ -73,10 +73,22 @@ for zero-install render/verify/describe and structured edits, and tested
 byte-identical determinism. Neither upstream project needed any of this: both serve humans who write
 diagrams once, while this surface serves programs that edit them repeatedly.
 
+## Mindmap/GitGraph and the terminal ecosystem
+
+The checked fixtures follow the official [Mindmap](https://mermaid.ai/open-source/syntax/mindmap.html) and [GitGraph](https://mermaid.ai/open-source/syntax/gitgraph.html) syntax pages and render from the same authored source in Mermaid 11.16.0 and Agentic Mermaid. See the captioned [Mindmap comparison](./design/families/mindmap.md#visual-evidence) and [GitGraph comparison](./design/families/gitgraph.md#visual-evidence). Compare semantic structure—labels, shapes, hierarchy, lanes, commits, parentage, tags, and bounds—not pixels, because the layout/style engines differ.
+
+[AlexanderGrooff/mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) 1.4.0 does not currently implement either family. Replaying the documented CLI against the same fixtures exits 1 with:
+
+```text
+unsupported graph type 'mindmap'. Supported types: graph TD, graph TB, graph LR, flowchart TD, flowchart TB, flowchart LR
+unsupported graph type 'gitGraph'. Supported types: graph TD, graph TB, graph LR, flowchart TD, flowchart TB, flowchart LR
+```
+
+Its [diagram coverage issue #74](https://github.com/AlexanderGrooff/mermaid-ascii/issues/74) tracks additional families. This is a capability difference, not a claim that an unsupported render is visually worse.
+
 ## Choosing
 
-- Rendering inside a web app, or you need mindmap/gitgraph/any family
-  beyond the 12 here → **Mermaid**.
+- Rendering inside a web app, or you need a family absent from `am capabilities --json` → **Mermaid**.
 - Fast, beautiful SVG/ASCII rendering of the core families in
   Node/Bun/terminal, render-only → **Beautiful Mermaid**.
 - An AI agent (or any program) needs to *edit* diagrams safely, verify them

package/docs/computational-aesthetics-prototype-plan.md

@@ -0,0 +1,252 @@
+# Computational-aesthetics prototype plan
+
+This is the revised plan for cheap, deterministic computational aesthetics in
+Agentic Mermaid. It covers pure functions over geometry and concrete sRGB. It
+does not turn a rubric into an optimizer, add learned scores, or introduce
+stochastic search.
+
+The governing rule is stricter than “the formula is deterministic”:
+
+> An aesthetic mechanism is ready only when its domain, runtime, product
+> reachability, and evidence are all explicit.
+
+Agentic Mermaid already operationalizes graph-layout research in
+`src/layout-rubric.ts` and `src/family-rubric.ts`. The work below extends that
+discipline to categorical color and whole-canvas composition without pretending
+that one scalar score certifies beauty.
+
+## Status
+
+- **shipped** — implemented on a product path with discriminating tests.
+- **prototype** — report-only until the evaluation harness justifies a weight.
+- **rejected** — considered, but redundant or insufficiently specified.
+
+| # | Idea | Status | Contract / next question |
+|---|---|---|---|
+| 1 | OKLCH constant-lightness categorical ramps | **shipped** | deterministic concrete-sRGB generation |
+| 2 | Minimum ΔE_OK collision floor | **shipped** | hard for 7–24 fills; best-effort and linear-time above 24 |
+| 3 | APCA plus WCAG background-visibility floors | **shipped** | every derived fill clears both for valid concrete backgrounds |
+| 10 | Common-region ownership purity | **shipped** | architecture, class, ER, and timeline ownership frames |
+| 12 | Separate typographic CPL warning | **rejected** | duplicates public universal `LABEL_OVERFLOW`; no independent signal |
+| 4 | Cohen-Or hue-harmony templates | **rejected as a default** | 4/360 cases retain {1,2,3}; experiment remains reproducible |
+| 5 | Purchase-normalized crosslessness `m_c` | prototype | does normalization discriminate across graph sizes? |
+| 6 | Consistent flow-direction metric | prototype | does it catch anything ELK does not already guarantee? |
+| 7 | Whole-canvas composition | prototype | which Ngo terms correlate with preference on our diagrams? |
+| 8 | Crossing-angle / RAC penalty | prototype | incremental value after crossing count |
+| 9 | Spine-straightness continuity | prototype | incremental value after {5,8} |
+| 11 | Proximity / MST purity | prototype | incremental value after common-region and composition metrics |
+| 13 | Information-theoretic order | prototype | is a pinned gzip ratio more than a coarse alignment proxy? |
+
+## What the first implementation taught us
+
+The audit and controlled rollout changed the plan in twelve ways.
+
+1. **Runtime is part of correctness.** A deterministic pairwise repair still
+   fails the product if an allowed 1,000-slice input takes seconds. The ΔE
+   guarantee is therefore bounded at 24 and the large-count path has expected
+   linear work. Portable CI asserts the real branch and its operation counts;
+   wall-clock observations live in `eval/palette-performance/report.json` with
+   their machine, protocol, input hashes, and limitations. Every prototype must
+   declare an input-size budget and a degraded-tail rule.
+
+2. **A threshold needs a corpus, not one friendly example.** The 0.10 ΔE claim
+   initially failed on shipped themes and custom accent/background pairs. The
+   contract now runs across every built-in theme, every count from 7 through
+   24, and adversarial saturated backgrounds. Future thresholds need the same
+   domain matrix before they can be called guarantees.
+
+3. **Use the perceptual quantity that controls the decision.** HSL lightness
+   misclassified a bright saturated yellow-green background as dark. Palette
+   polarity now uses OKLab lightness, and visibility repair searches both
+   lightness directions before falling back to a visible achromatic extreme.
+
+4. **A shared waist multiplies risk as well as value.** `pieSliceColors` already
+   reaches pie and radar, so one defect reaches both. Migrating four more
+   families remains valuable, but only after the waist has an explicit range,
+   a hard runtime bound, adversarial tests, and per-family visual review.
+
+5. **Reachability precedes novelty.** A test-only finding is not a product
+   capability. The proposed `LABEL_LINE_OVERLONG` finding was not surfaced by
+   verify, CLI, API, or MCP and overlapped the existing public
+   `LABEL_OVERFLOW` warning. It is removed rather than wired twice.
+
+6. **Independence applies before implementation too.** A new metric must state
+   which existing defect it detects that current metrics miss. Idea #12 fails
+   that test. Ideas {7,11} and {5,8,9} must pass it through ablation.
+
+7. **Semantic scope must follow every real model.** Common-region purity is not
+   architecture-only: class namespaces, ER groups, and timeline sections also
+   express ownership. Ancestor walks must be cycle-safe without arbitrary
+   depth cutoffs.
+
+8. **Visual evidence needs its own reproducibility contract.** The rollout now
+   freezes pre-change SVGs, extracts the categorical colors actually serialized
+   by each renderer, writes a machine-readable comparison, and hashes every
+   source input plus the generated report/contact sheet. `--check` fails when
+   code, baseline, metrics, or images drift.
+
+9. **A controlled rollout is a compatibility policy, not a global recolor.**
+   Counts up to six retain each family's existing derived colors byte-for-byte
+   (including Journey's established actor wheel). Authored
+   `plotColorPalette`, `actorColours`, `sectionFills`/`sectionColours`, and
+   `git0..7` remain authoritative. Only derived high-cardinality peer-category
+   colors change.
+
+10. **Harmony and categorical distinctness compete at this density.** Across
+    20 built-in themes × counts 7..24, the Cohen-Or/Matsuda experiment reduced
+    mean harmony loss from 8.8303° to 0.0084°, but reduced mean minimum ΔE_OK
+    from 0.1107 to 0.0456. Only 4/360 palettes retained {1,2,3}; no count above
+    seven passed. That rejects #4 as a default layer over this palette.
+
+11. **A measurement must not claim more than it measures.** The performance
+    corpus measures one palette-generation call, not a complete diagram render.
+    Most controlled families have one peer-category channel; Journey has two
+    independent channels (sections and actors). Following the
+    [testing-best-practices guidance](https://github.com/adewale/testing-best-practices/tree/e50479920006aa010850a2c37f9bee1e02b5badf),
+    CI gates deterministic complexity and evidence freshness, never a portable
+    millisecond threshold.
+
+12. **Normalize at the algorithm boundary without erasing compatibility.**
+    StyleSpec accepts concrete `#RGB`, named, `rgb()`, and `hsl()` colors, while
+    the perceptual math requires six-digit sRGB. The high-count path now
+    normalizes every parser-resolvable concrete color before repair. The ≤6
+    path deliberately preserves each family's historical spelling or fallback
+    policy byte-for-byte; a global normalizer at that boundary would be a
+    compatibility regression disguised as cleanup.
+
+## Shipped color contract and family reach
+
+The color work is a generation constraint, not evidence that the quality
+rubric predicts human preference. The neutral shared waist now reaches pie,
+radar, xychart, journey, mindmap, and gitgraph. SVG and terminal xychart/gitgraph
+use the same derived palette; the other terminal families do not currently
+encode peer categories with color.
+
+The scope rule for this rollout, and for any future shared-palette expansion,
+is explicit:
+
+> The scope is intentionally limited to families where color identifies peer
+> categories. Semantic colors—status, hierarchy, role, or user-authored
+> meaning—should not be automatically redistributed.
+
+| Property | 7–24 fills | More than 24 fills |
+|---|---|---|
+| deterministic | hard | hard |
+| valid concrete hex output | hard | hard |
+| WCAG ≥ 1.25 and APCA ≥ 15 vs concrete background | hard | hard |
+| unique fills | hard | best-effort |
+| minimum pairwise ΔE_OK ≥ 0.10 | hard | not claimed |
+| asymptotic repair cost | bounded `O(M·n²)`, with `n ≤ 24` and fixed corpus `M` | expected `O(n)` with average `O(1)` set membership |
+
+The established local palette is preserved when it meets the contract. If it
+does not, a deterministic farthest-point packing pass selects background-visible
+concrete sRGB candidates. Above 24, pairwise enforcement is skipped.
+
+## Prototype protocol
+
+Reuse the existing evaluator; do not create a second quality system.
+
+1. **Define the contract first.** State applicable families, input-size range,
+   asymptotic and wall-clock budgets, degraded-tail behavior, and exclusions.
+2. **Prove product reachability.** Identify the public result, warning, or
+   report that exposes the metric. A private helper plus unit test is not done.
+3. **Report before weighting.** Add the metric to the per-metric tracker with
+   zero score weight. A weight is a separate scoring-contract change.
+4. **Add trip fixtures.** Include healthy and deliberately bad examples that
+   make the metric move. Zero on every committed fixture is a guard, not a
+   demonstrated discriminator.
+5. **Measure the full domain.** Use the Mermaid docs corpus, heuristic tracker,
+   deterministic family fuzzers, all built-in themes where color is involved,
+   and adversarial boundary inputs.
+6. **Keep visual evidence.** Any generation or geometry change needs
+   before/after renders and snapshot review in every affected family. The
+   palette rollout operationalizes this rule in
+   `scripts/pr-assets/palette-rollout-evidence.ts`.
+7. **Gate determinism and cost.** Preserve byte identity and deterministically
+   assert that the intended bounded algorithmic path engaged. Keep p50/p95
+   observations over a fixed corpus in a separate, provenance-bound report;
+   do not use cross-machine wall time as a CI threshold. Idea #13 must also pin
+   codec and level.
+
+## Evaluation and graduation
+
+For a candidate metric M, record:
+
+- **coverage** — fraction of diagrams on which M varies;
+- **discrimination** — LCC/SROCC against a small blinded human A/B set;
+- **independence** — partial correlation after controlling for current metrics;
+- **stability** — sensitivity to harmless translation, scale, and equivalent
+  source ordering where those transforms should not matter;
+- **cost** — deterministic operation growth at the declared size boundary,
+  plus environment-qualified p50/p95 observations where useful;
+- **reach** — public surfaces and diagram families that consume the result.
+
+Graduate a metric from report-only only when it fires on trip fixtures, varies
+on the corpus, adds preference signal after current metrics, and stays inside
+its cost budget. Otherwise remove it or retain it explicitly as a correctness
+guard with no aesthetic weight.
+
+For combinations, run small ablations rather than blending everything. Treat
+each combination as a gated ladder: validate the cheaper base term, add one
+term, and stop when independence disappears.
+
+- **{1,2,3}:** lightness structure, categorical distance, and background
+  visibility are complementary and already ship as one generation contract.
+- **{1,2,3,4}:** the completed experiment found no useful Pareto front at
+  8–24 categories: hue-sector contraction almost eliminates harmony loss but
+  breaks minimum categorical distance. Do not ship this bundle as a default.
+- **{5,8}:** crossing prevalence and crossing quality should be complementary.
+- **{5,6,8}:** add direction only if #6 catches defects not explained by the
+  crossing pair or by ELK's existing directional constraints.
+- **{5,8,9}:** likely redundant; add #9 only if partial correlation survives.
+- **{7,10,11}:** composition, common region, and proximity span figure,
+  ownership, and local grouping scales, but need ablation because the signals
+  can collapse onto the same cluster structure.
+
+## Revised stack rank
+
+The rank uses five axes: user-visible value, independence from existing
+signals, product reach, bounded runtime, and validation burden. “Foundation” is
+not optional feature work. An arrow means “validate the new idea alone, then
+admit it to the combination”; it is not permission to ship an opaque aggregate.
+
+| Rank | Work package | Form | Why it is here | Stop / go gate |
+|---|---|---|---|---|
+| Foundation | **Keep {1,2,3,10}; reject #12** | shipped contract | Color and ownership have bounded, reachable contracts; the extra label warning is redundant. | keep the regression matrix green |
+| Delivered | **Controlled {1,2,3} family rollout** | shipped combination | 14/14 fixture violations corrected; 8/8 family/theme cases pass; ≤6 colors and authored overrides remain compatible; six rich website examples expose the peer mapping at inspectable size. | palette evidence, complexity, website, and family gates |
+| Rejected | **#4 → {1,2,3,4} color-harmony default** | completed experiment | 4/360 pass rate; mean minimum ΔE_OK falls 0.1107 → 0.0456. | reconsider only with a new constraint-preserving algorithm and blinded preference evidence |
+| Paused 1 | **#5 normalized crosslessness `m_c`** | telemetry, postponed | Still the cheapest next metric experiment, but telemetry work is intentionally deferred. | resume only on explicit telemetry restart |
+| Paused 2 | **#8 → {5,8} crossing-quality bundle** | telemetry, postponed | Clear ablation after #5. | #8 must add signal after #5 |
+| Paused 3 | **#6 → {5,6,8} directional-legibility bundle** | telemetry, postponed | Likely overlaps ELK behavior. | independent trip case first |
+| Paused 4 | **#7 whole-canvas composition** | telemetry, postponed | Potential figure-level value, high calibration burden. | stable, nonzero corpus coverage |
+| Paused 5 | **#11 → {7,10,11} multiscale grouping** | telemetry, postponed | Plausible value with high redundancy risk. | term-by-term ablation |
+| Paused 6 | **#9 → {5,8,9} edge-path bundle** | telemetry, postponed | Costlier and likely redundant. | partial-correlation survival |
+| Paused 7 | **#13 pinned-gzip order** | telemetry, postponed | Codec-sensitive and coarse. | beat simpler direct features |
+
+This supersedes the earlier ordering. The highest-ranked product change is now
+delivered and its evidence gate is permanent. The harmony experiment has also
+resolved its decision: it is not merely lower priority; this formulation is a
+bad default. With telemetry postponed, there is no authorized next aesthetic
+metric package. If telemetry resumes, it still starts with #5 and every later
+bundle remains conditional on ablation.
+
+## Scope boundaries
+
+- This plan covers measurement and closed-form generation, not optimization.
+- Flowchart/state subgraph purity remains in `layout-rubric.ts`; the generic
+  #10 implementation covers ownership frames projected by architecture, class,
+  ER, and timeline.
+- `LABEL_OVERFLOW` remains the public label-length signal. It applies the
+  caller-configurable cap to the longest rendered line after entity decoding,
+  line-break normalization, and formatting-tag removal. A second fixed CPL
+  warning would be redundant and less reachable.
+- The shared perceptual palette reaches only families where color denotes peer
+  categories: pie slices, radar curves, xychart series, journey actors/sections,
+  mindmap top-level branches, and gitgraph branches. Structural families use
+  color for roles, status, hierarchy, or authored semantics; automatic hue
+  spreading there would invent category meaning and can weaken brand/status
+  cues. Timeline/gantt/quadrant have family-specific categorical contracts and
+  are not silently swept into this rollout.
+- A score of 100 proves only that a renderer clears the measured hygiene floor;
+  it does not certify beauty. Each family still needs an aesthetic thesis and
+  human visual review.

package/docs/config.md

@@ -3,7 +3,7 @@
 Agentic Mermaid accepts Mermaid-style runtime config through explicit render options, YAML frontmatter, and `%%{init: ...}%%` / `%%{initialize: ...}%%` directives.
 
 Round-trip behavior: the agent surface preserves these source wrappers
-byte-verbatim — `parseMermaid → serializeMermaid` and every `mutate` re-emit
+byte-verbatim — `parseRegisteredMermaid → serializeMermaid` and every `mutate` re-emit
 the original frontmatter/directives/leading comments untouched, so a
 `config.layout`/`config.look` request written for Mermaid survives an
 Agentic Mermaid edit loop. Canonical wrapper synthesis (config-nested
@@ -29,7 +29,7 @@ const svg = renderMermaidSVG(source, {
 })
 ```
 
-Explicit options win over source-level config when both specify the same supported field.
+Explicit options win over source-level config when both specify the same supported field. `RenderOptions.onConfigDiagnostic` can collect warnings for explicit config that is unknown, invalid, or has no faithful effect; without a collector, explicit ineffective State config warns through `console.warn` rather than disappearing silently.
 
 ## YAML frontmatter
 
@@ -70,14 +70,30 @@ Top-level:
 `themeVariables` and explicit color options still win over a style's
 palette, preserving Mermaid compatibility.)
 
-Family-specific:
-
-- `xyChart.width`, `xyChart.height`, `xyChart.chartOrientation`, `xyChart.showDataLabel`, `xyChart.titlePadding`, `xyChart.xAxisLabelPadding`, `xyChart.yAxisLabelPadding`, `xyChart.plotReservedSpacePercent`, `xyChart.plotColorPalette`, `xyChart.useMaxWidth`, `xyChart.useWidth`
-- `architecture.padding`, `architecture.iconSize`, `architecture.fontSize`
-- `timeline.disableMulticolor`, `timeline.padding`, `timeline.sectionFontSize`, `timeline.periodFontSize`, `timeline.eventFontSize`
-- `gantt.displayMode` (`compact` packs non-overlapping tasks in a section into shared rows)
-
-Unsupported fields are preserved at the source level where possible, but only documented fields are interpreted by renderers.
+Family-specific config is **wire-or-warn**: every accepted key either changes
+output or produces `INEFFECTIVE_CONFIG` naming the field. Unknown keys also
+warn, so spelling mistakes cannot disappear silently. This contract covers all
+every registered family and both frontmatter and init directives.
+
+Notable wired sections include:
+
+- `flowchart`: spacing and measured wrapping;
+- `sequence`: actor/message/note spacing, dimensions, activations, and numbering;
+- `timeline`, `journey`, `class`, `er`, `architecture`, `xyChart`, `pie`,
+  `quadrantChart`, `mindmap`, and `gitGraph`: the fields documented in their
+  family design notes;
+- `gantt.displayMode` (`compact` packs non-overlapping tasks in a section into
+  shared rows).
+
+`state` has a typed `StateRuntimeConfig`. `nodeSpacing`, `rankSpacing`,
+`padding`, `radius`, `fontSize`, `compositTitleSize` (upstream spelling),
+`forkWidth`, `forkHeight`, `noteMargin`, and `dividerMargin` are wired to
+State-specific geometry/paint. `defaultRenderer: 'elk'` is satisfied;
+alternate renderer requests, invalid values, and legacy Dagre/fixed-metric
+calibration fields emit qualified `state.*` diagnostics. Unsupported fields
+and wrappers remain source-preserved. The executable all-family audit is
+`src/__tests__/unknown-config-wire-or-warn.test.ts`; the independent State key
+inventory and discriminating geometry probes are in `state-config.test.ts`.
 
 ## Security