agentic-mermaid 0.4.1 → 0.5.3

package/dist/zenuml.d.ts

@@ -0,0 +1,83 @@
+import { R as RenderOptions } from './types-BcS52Mjt.js';
+import { S as StyleInput } from './svg-styles-BdnoM7AT.js';
+
+/** Optional browser-only backend. No ZenUML dependency enters the default graph. */
+declare class ZenUMLBackendError extends Error {
+    readonly code: 'UNSUPPORTED_RUNTIME' | 'BACKEND_UNAVAILABLE' | 'INVALID_SOURCE' | 'RENDER_FAILED' | 'UNSUPPORTED_APPEARANCE';
+    constructor(code: 'UNSUPPORTED_RUNTIME' | 'BACKEND_UNAVAILABLE' | 'INVALID_SOURCE' | 'RENDER_FAILED' | 'UNSUPPORTED_APPEARANCE', message: string);
+}
+declare const UPSTREAM_ZENUML_CAPABILITIES: Readonly<{
+    maturity: "experimental";
+    sourcePreservation: true;
+    nativeParse: false;
+    typedEditing: false;
+    rendering: "optional-browser-iframe";
+    asynchronous: true;
+    terminal: false;
+    node: false;
+    cli: false;
+    mcp: false;
+    backend: "@zenuml/core@3.47.9";
+    nativeScene: false;
+    styles: false;
+    palettes: true;
+    rolePaints: true;
+    reusableSession: true;
+}>;
+interface UpstreamZenUMLRenderOptions {
+    timeoutMs?: number;
+    /** Named palettes or paint-only node/edge/group/label fragments. Native Look
+     * geometry, fonts and sketch effects are rejected, never silently ignored. */
+    style?: StyleInput | StyleInput[];
+}
+interface UpstreamZenUMLOptions extends UpstreamZenUMLRenderOptions {
+    /** URL of the shipped zenuml-frame.global.js, served by the consumer. */
+    backendURL: string | URL;
+}
+interface UpstreamZenUMLRenderer {
+    /** Requests are serialized; at most 32 calls may be pending per session. */
+    render(source: string, options?: UpstreamZenUMLRenderOptions): Promise<string>;
+    /** Release the isolated backend and reject active and queued requests. */
+    dispose(): void;
+}
+/** An explicitly owned session retains one isolated backend. Every render
+ * still parses and lays out its input; no source/SVG result cache is used. */
+declare function createUpstreamZenUMLRenderer(options: UpstreamZenUMLOptions): UpstreamZenUMLRenderer;
+/** One-shot rendering shares the session implementation and always releases
+ * its frame. Use createUpstreamZenUMLRenderer for repeated previews, then dispose it. */
+declare function renderUpstreamZenUMLSVG(source: string, options: UpstreamZenUMLOptions): Promise<string>;
+
+declare const ZENUML_CAPABILITIES: Readonly<{
+    maturity: "experimental";
+    sourcePreservation: true;
+    nativeParse: true;
+    typedEditing: true;
+    rendering: "native-scene";
+    asynchronous: true;
+    terminal: true;
+    node: true;
+    cli: true;
+    mcp: true;
+    backend: "native-sequence-scene";
+    nativeScene: true;
+    styles: true;
+    palettes: true;
+    rolePaints: true;
+    reusableSession: true;
+}>;
+interface ZenUMLRenderOptions extends RenderOptions {
+    /** Deadline for asynchronous dependency loading. Synchronous layout cannot
+     * be interrupted while the JavaScript event loop is executing it. */
+    timeoutMs?: number;
+}
+type ZenUMLOptions = ZenUMLRenderOptions;
+interface ZenUMLRenderer {
+    render(source: string, options?: ZenUMLRenderOptions): Promise<string>;
+    dispose(): void;
+}
+/** Native Zen sessions serialize rendering and retain no source/SVG results.
+ * Named defaults resolve at each request's synchronous admission boundary. */
+declare function createZenUMLRenderer(options?: ZenUMLOptions): ZenUMLRenderer;
+declare function renderZenUMLSVG(source: string, options?: ZenUMLOptions): Promise<string>;
+
+export { UPSTREAM_ZENUML_CAPABILITIES, type UpstreamZenUMLOptions, type UpstreamZenUMLRenderOptions, type UpstreamZenUMLRenderer, ZENUML_CAPABILITIES, ZenUMLBackendError, type ZenUMLOptions, type ZenUMLRenderOptions, type ZenUMLRenderer, createUpstreamZenUMLRenderer, createZenUMLRenderer, renderUpstreamZenUMLSVG, renderZenUMLSVG };

package/dist/zenuml.js

@@ -0,0 +1 @@
+import{f as e}from"./zenuml/chunks/chunk-42DXZ5C6.js";import"./zenuml/chunks/chunk-OXQWRSBM.js";import{e as t,j as n,k as r}from"./zenuml/chunks/chunk-QWX77U7G.js";import"./zenuml/chunks/chunk-RLJEI7YN.js";import"./zenuml/chunks/chunk-RZ6XK5CD.js";import"./zenuml/chunks/chunk-EVPSMEKN.js";var o=class extends Error{constructor(e,t){super(t),this.code=e,this.name="ZenUMLBackendError"}code},i=Object.freeze({maturity:"experimental",sourcePreservation:!0,nativeParse:!1,typedEditing:!1,rendering:"optional-browser-iframe",asynchronous:!0,terminal:!1,node:!1,cli:!1,mcp:!1,backend:"@zenuml/core@3.47.9",nativeScene:!1,styles:!1,palettes:!0,rolePaints:!0,reusableSession:!0});function s(e){try{return n(()=>{let n=r(e);return t(n,"ZenUML style",{allowUndefinedObjectProperties:!0}),n})}catch(e){throw new o("UNSUPPORTED_APPEARANCE",e instanceof Error?e.message:String(e))}}function a(e){let t;if(typeof document>"u"||typeof MessageChannel>"u")throw new o("UNSUPPORTED_RUNTIME","ZenUML rendering requires a browser document; use the optional browser backend.");try{t=new URL(e.backendURL,document.baseURI)}catch{throw new o("BACKEND_UNAVAILABLE","The ZenUML backend URL is invalid.")}if(!["http:","https:"].includes(t.protocol)||t.origin!==new URL(document.baseURI).origin)throw new o("BACKEND_UNAVAILABLE","The ZenUML frame script must be served from the same HTTP(S) origin.");let n=void 0===e.style?void 0:s(e.style),r=e.timeoutMs??3e4,i=!1,a=0,d=0,c,l,u,m=new Set,p=[],h=!1,f=e=>new o("BACKEND_UNAVAILABLE",e),U=()=>{c?.remove(),c=void 0,l=void 0,d=0},y=(e,n,r)=>new Promise((i,s)=>{d>=64&&U(),d++;let a=new MessageChannel,m=!1,p=()=>{m=!0,clearTimeout(y),a.port1.close(),a.port2.close(),u===h&&(u=void 0)},h=e=>{m||(p(),"INVALID_SOURCE"!==e.code&&U(),s(e))};u=h;let y=setTimeout(()=>h(f("ZenUML backend did not complete before its deadline.")),r);a.port1.onmessage=e=>{if(m)return;let t=e.data;t?.ok===!0&&"string"==typeof t.svg?(p(),i(t.svg)):h(new o(t?.code==="INVALID_SOURCE"?"INVALID_SOURCE":"RENDER_FAILED",String(t?.message??"ZenUML rendering failed.")))},Promise.resolve().then(()=>m?void 0:(()=>{if(l)return l;(c=document.createElement("iframe")).style.cssText="position:fixed;left:-100000px;top:0;width:1024px;height:768px;visibility:hidden;pointer-events:none;border:0",c.setAttribute("aria-hidden","true"),c.setAttribute("sandbox","allow-scripts allow-same-origin"),l=new Promise(e=>{c.onload=()=>e()});let e=t.href.replace(/&/g,"&amp;").replace(/"/g,"&quot;").replace(/</g,"&lt;").replace(/>/g,"&gt;");return c.srcdoc=`<!doctype html><html><head><script src="${e}"></script></head><body></body></html>`,(document.body??document.documentElement).append(c),l})()).then(()=>{m||u!==h||c?.contentWindow?.postMessage({type:"agentic-zenuml",source:e,appearance:n},t.origin,[a.port2])}).catch(()=>h(f("The ZenUML frame could not be loaded.")))});return{async render(e,t={}){if(i)throw f("The ZenUML renderer has been disposed.");if("string"!=typeof e||!/^\s*zenuml\b/.test(e)||!e.replace(/^\s*zenuml\b/,"").trim())throw new o("INVALID_SOURCE","Expected a nonempty ZenUML document.");if(a>=32)throw f("The ZenUML renderer already has 32 pending requests.");a++;let d,c,l,u,U,w=new Promise((e,t)=>{u=e,U=t}),L,b=new Promise((e,t)=>{L=t});b.catch(()=>{});let M=!1,E=()=>{M=!0,a--,m.delete(A);let e=p.indexOf(v);e>=0&&p.splice(e,1)},g=e=>{M||(E(),U(e))},A=e=>{L(e),g(e)},v=async()=>{if(!M)try{let t;if(i)throw f("The ZenUML renderer has been disposed.");if(void 0===c)t=await y(e,void 0,d);else{let n=performance.now(),r,o=new Promise((e,t)=>{r=setTimeout(()=>t(f("ZenUML palette admission did not complete before its deadline.")),d)}),s;try{s=await Promise.race([l,b,o])}finally{clearTimeout(r)}if(i)throw f("The ZenUML renderer has been disposed.");t=await y(e,s,Math.max(0,d-(performance.now()-n)))}M||(E(),u(t))}catch(e){g(e)}};m.add(A),p.push(v);try{if(d=t.timeoutMs??r,!Number.isFinite(d)||d<=0)throw f("timeoutMs must be positive and finite.");let e="style"in t?t.style:n;c=void 0===e?void 0:s(e),M||(l=void 0===c?Promise.resolve(void 0):import("./zenuml/chunks/appearance-UOQ5KA6O.js").then(e=>{try{return e.resolveZenUMLAppearance(c)}catch(e){throw new o("UNSUPPORTED_APPEARANCE",e instanceof Error?e.message:String(e))}},()=>{throw f("The ZenUML palette module could not be loaded.")})).catch(()=>{})}catch(e){g(e)}return h||(h=!0,queueMicrotask(async()=>{try{for(;p.length;)await p.shift()()}finally{h=!1}})),w},dispose(){i=!0;let e=f("The ZenUML renderer has been disposed.");for(let t of(u?.(e),m))t(e);U()}}}async function d(e,t){let n=a(t);try{return await n.render(e)}finally{n.dispose()}}var c=Object.freeze({maturity:"experimental",sourcePreservation:!0,nativeParse:!0,typedEditing:!0,rendering:"native-scene",asynchronous:!0,terminal:!0,node:!0,cli:!0,mcp:!0,backend:"native-sequence-scene",nativeScene:!0,styles:!0,palettes:!0,rolePaints:!0,reusableSession:!0});function l(t,n={},r=3e4){if(!t||"object"!=typeof t&&"function"!=typeof t)throw TypeError("ZenUML render options must be an object.");if("backendURL"in t)throw TypeError("backendURL belongs to createUpstreamZenUMLRenderer/renderUpstreamZenUMLSVG; native ZenUML needs no backend URL.");let{timeoutMs:o=r,...i}=t;if(!Number.isFinite(o)||o<=0)throw TypeError("timeoutMs must be positive and finite.");return{timeout:o,options:e({...n,...i})}}function u(e={}){let t=l(e),n=[],r=new Set,i=!1,s=0,a=!1,d=e=>new o("BACKEND_UNAVAILABLE",e);return{async render(e,c={}){if(i)throw d("The ZenUML renderer has been disposed.");if("string"!=typeof e||!e.trim())throw new o("INVALID_SOURCE","Expected a nonempty ZenUML document.");if(s>=32)throw d("The ZenUML renderer already has 32 pending requests.");s++;let u,m,p,h=new Promise((e,t)=>{m=e,p=t}),f,U=new Promise((e,t)=>{f=t});U.catch(()=>{});let y=!1,w,L=()=>{y=!0,clearTimeout(w),s--,r.delete(b);let e=n.indexOf(M);e>=0&&n.splice(e,1)},b=e=>{y||(f(e),L(),p(e))},M=async()=>{if(!y){w=setTimeout(()=>b(d("ZenUML rendering did not complete before its deadline.")),u.timeout);try{let t=async()=>{let[{default:t},{renderLoadedFamilySvg:n}]=await Promise.all([import("./zenuml/chunks/zenuml-EA2ZFRUX.js"),import("./zenuml/chunks/render-core-V5RQ737O.js")]);if(y)throw d("The ZenUML request is no longer active.");return n(e,u.options,t)},n=await Promise.race([t(),U]);y||(L(),m(n))}catch(e){b(e)}}};r.add(b),n.push(M);try{u=l(c,t.options,t.timeout)}catch(e){b(e)}return a||(a=!0,queueMicrotask(async()=>{try{for(;n.length;)await n.shift()()}finally{a=!1}})),h},dispose(){i=!0;let e=d("The ZenUML renderer has been disposed.");for(let t of r)t(e)}}}async function m(e,t={}){let n=u(t);try{return await n.render(e)}finally{n.dispose()}}export{i as UPSTREAM_ZENUML_CAPABILITIES,c as ZENUML_CAPABILITIES,o as ZenUMLBackendError,a as createUpstreamZenUMLRenderer,u as createZenUMLRenderer,d as renderUpstreamZenUMLSVG,m as renderZenUMLSVG};

package/docs/MCP-DIRECTORY-LISTINGS.md

@@ -49,9 +49,13 @@ from `verify.ok` alone.
 
 ## Directory record
 
+The root `server.json` prepares version `0.5.2`; this metadata change does not
+establish Registry publication. The directory observations below retain their
+recorded dates.
+
 | Directory | Registration input | Recorded status on 2026-07-30 |
 |---|---|---|
-| Official MCP Registry | Root [`server.json`](../server.json) | Active at version `0.4.0` |
+| Official MCP Registry | Root [`server.json`](../server.json) | Active at version `0.4.1` (published to npm and the Registry on 2026-07-31) |
 | OpenAI Plugins | Endpoint plus canonical fields above | Account-gated submission; tool titles and privacy notice captured in this repository |
 | Claude Connectors Directory | Endpoint plus canonical fields above | Account-gated Team/Enterprise submission; tool titles and privacy notice captured in this repository |
 | Cursor Directory | Repository and endpoint | Not found in directory; account-gated submission remains |

package/docs/README.md

@@ -1,105 +1,61 @@
 # Agentic Mermaid documentation
 
-This directory holds the long-form documentation. The root README is intentionally short and routes readers here. Consumer guides are included in the npm package; repository-only links use canonical GitHub URLs so this hub also works from an installed tarball.
-
-## User docs
-
-| Doc | Purpose |
-|---|---|
-| [`getting-started.md`](./getting-started.md) | Plain library use: render a Mermaid string to SVG/PNG/ASCII in 5 minutes. |
-| [`api.md`](./api.md) | Library, agent API, output functions, options, CLI/MCP pointers. |
-| [`diagram-families.md`](./diagram-families.md) | Supported Mermaid families, examples, and edit policy. |
-| [`theming.md`](./theming.md) | Two-color themes, built-in themes, custom themes, Shiki import. |
-| [`style-authoring.md`](./style-authoring.md) | Style model, stack semantics, field reference, rubric, and validation commands. |
-| [`custom-style-cookbook.md`](./custom-style-cookbook.md) | Complete custom style JSON files, screenshots, schema usage, CLI commands, and the documentation-only Cupertino-, Vercel-, and Cloudflare Workers-inspired prototypes. |
-| [`design/families/style-switch-contact-sheet.html`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/style-switch-contact-sheet.html) | Self-contained interactive contact sheet for every registered family and every built-in Look/Palette Style resource. |
-| [`custom-fonts.md`](./custom-fonts.md) | How custom Styles select and resolve fonts across SVG, PNG, browser, and MCP surfaces. |
-| [`react.md`](./react.md) | Zero-flash React rendering with CSS variables. |
-| [`browser.md`](./browser.md) | Framework-neutral pre-rendering, Alpine and plain-JS adapters, the classic `<script src>` bundle, and the shipped lazy all-family browser renderer. |
-| [`ascii.md`](./ascii.md) | Terminal output, ASCII vs Unicode, color modes, XY charts. |
-| [`config.md`](./config.md) | `mermaidConfig`, YAML frontmatter, and init directives. |
-| [`features.md`](./features.md) | Capability inventory. |
-| [`quality.md`](./quality.md) | Determinism, quality metrics, and visual-review guidance. |
-| [`testing-strategy.md`](./testing-strategy.md) | What we test, how, and why: oracle types, the proof-gate map, and honest gaps. |
-| [`fork-differences.md`](./fork-differences.md) | How Agentic Mermaid differs from upstream Beautiful Mermaid. |
-| [`comparison.md`](./comparison.md) | Functionality differences between Mermaid, Beautiful Mermaid, and Agentic Mermaid — and when to use each. |
-
-## Agent docs
-
-| Doc | Purpose |
-|---|---|
-| [`../Instructions_for_agents.md`](../Instructions_for_agents.md) | Canonical short guide; byte-identical to `am --agent-instructions`. |
-| [`../AGENT_NATIVE.md`](../AGENT_NATIVE.md) | Architecture/spec rationale for the agent-native surface. |
-| [`agent-api-cookbook.md`](./agent-api-cookbook.md) | Copy-pasteable library/CLI/MCP recipes. |
-| [`agent-mutation-policy.md`](./agent-mutation-policy.md) | Structured-vs-source-level edit policy. |
-| [`mcp-code-mode-rationale.md`](./mcp-code-mode-rationale.md) | Why MCP is Code Mode first. |
-| [`code-mode-impact.md`](./code-mode-impact.md) | Measured client/server impact, comparison with Cloudflare and Anthropic, and operational costs. |
-| [`mcp-http-transport.md`](./mcp-http-transport.md) | Local HTTP/SSE MCP quickstart plus hosted `/mcp` call-shape notes. |
-| [`agent-workflow-examples.md`](./agent-workflow-examples.md) | Runnable MCP/CLI and improvement-loop examples. |
-| [`../skills/`](../skills/) | Agent-agnostic skill bundles. |
-| [`../skill-evals/`](https://github.com/adewale/agentic-mermaid/tree/main/skill-evals) | Skill eval manifest, fixtures, and benchmark instructions. |
-
-## Contributor / project docs
-
-The design docs split into two tiers — **system** (how the engine works, cross-cutting) and
-**per-family** (how one diagram type works).
-
-### System design — how the engine works
-
-| Doc | Purpose |
-|---|---|
-| [`project/brand-primitives-plan.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/brand-primitives-plan.md) | Normative appearance/family-contract decision and A/B dependency/acceptance plan; live status is owned by root `TODO.md`. |
-| [`design/system/`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) | **Start here.** Current resolved-request, family-descriptor, positioned-artifact, and output-security architecture overview (dogfooded, drift-proof). |
-| [`design/system/route-contracts.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/route-contracts.md) | Route contracts: edge classification, direct-lane proofs, certifying straightener (issue #25). |
-| [`design/system/layout-rubric.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/layout-rubric.md) | Deterministic layout-quality rubric: metrics, CI gates, and property oracles. |
-| [`design/system/source-preservation-ladder.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/source-preservation-ladder.md) | The structured\|opaque family-adoption contract (levels L0–L4). |
-| [`design/mermaid-family-fidelity-audit.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/mermaid-family-fidelity-audit.md) | Mermaid 11.16 syntax accounting and Mermaid/Wikipedia visual-metaphor audit for every registered family. |
-| [`design/style-palette-compatibility.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/style-palette-compatibility.md) | Registry-derived exhaustive algebra plus complexity-aware variable-strength Style/Palette/family compatibility receipt. |
-| [`design/system/ugly-layouts.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/ugly-layouts.md) | Ugly-layout detector: catalogued failure shapes and heuristics. |
-
-### Per-family design notes
-
-| Doc | Purpose |
-|---|---|
-| [`design/families/`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/README.md) | Per-family hub: which families have a design note, and where each family's other surfaces live. |
-| [`design/families/architecture-beta.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/architecture-beta.md) | `architecture-beta` diagram-type implementation notes. |
-| [`design/families/gantt.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/gantt.md) | Gantt support specification and compatibility boundaries. |
-| [`design/families/gantt-research.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/gantt-research.md) | Gantt literature review and commercial UX survey. |
-| [`design/families/journey.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/journey.md) | Journey diagram implementation notes. |
-| [`design/families/xychart.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/xychart.md) | XY chart implementation notes. |
-| [`design/families/flowchart-parser-conformance.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/flowchart-parser-conformance.md) | Flowchart syntax conformance catalogue and unsupported-syntax warning policy (issue #36). |
-
-> All per-family notes live in `design/families/` and all cross-cutting notes in `design/system/`.
-
-### Project & process
-
-| Doc | Purpose |
-|---|---|
-| [`contributing/adding-diagram-types.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/adding-diagram-types.md) | How to add a Mermaid-supported diagram family. |
-| [`contributing/visual-review-evidence.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/visual-review-evidence.md) | Which reproducible visual artifacts are required for layout/rendering changes. |
-| [`contributing/diagram-family-citizenship.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/diagram-family-citizenship.md) | Enforced good-citizen checklist and matrix for family/surface drift (issue #41). |
-| [`contributing/harvesting-upstream-tests.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/harvesting-upstream-tests.md) | How to vendor upstream/fork test suites into an executable compatibility bench. |
-| [`contributing/releasing.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/releasing.md) | How to cut an npm release (GitHub Release → provenance publish) and flip the "published" copy. |
-| [`layout-characterization/README.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/layout-characterization/README.md) | Layout and visual testing approach: properties, contact sheets, raster contracts, and approval artifacts. |
-| [`svg-semantic-contract.md`](./svg-semantic-contract.md) | Typed Scene identity, geometry, references, and accessibility contract. |
-| [`mutation-testing.md`](./mutation-testing.md) | Mutation lanes, survivor handling, and fault-sensitivity evidence. |
-| [`project/divergences.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/divergences.md) | Deliberate divergences and guardrails. |
-| [`project/lessons-learned.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/lessons-learned.md) | Evergreen engineering lessons distilled from the archived fork narrative. |
-| [`project/agent-interface-contract-audit-2026-07.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/agent-interface-contract-audit-2026-07.md) | PR #162 defect provenance, review of PRs #157/#160, testing root causes, and recurrence controls. |
-| [`project/complexity-aware-test-portfolio-plan.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/complexity-aware-test-portfolio-plan.md) | Implemented measured migration from overlapping family/style matrices to automatic complexity-aware conformance, variable-strength interaction coverage, and periodic contact-sheet review. |
-| [`contributing/lessons-learned.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/lessons-learned.md) | Dated contributor process lessons (newest first). |
-| [`project/dogfooding-docs-strategy.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/dogfooding-docs-strategy.md) | How we render and pin our own docs with our own tools. |
-| [`project/archive/`](https://github.com/adewale/agentic-mermaid/tree/main/docs/project/archive) | Status-marked landing/completion evidence and frozen historical records; never live backlog authority. |
-| [`issue-derived-test-cases.md`](./issue-derived-test-cases.md) | Issue-derived regression coverage map. |
-| [`mermaid-layout-complaints.md`](./mermaid-layout-complaints.md) | Mermaid layout complaint catalog, root causes, and coverage scorecard. |
-
-## Root docs kept intentionally
-
-- [`../README.md`](../README.md) — landing page and quick starts.
-- [`../CHANGELOG.md`](../CHANGELOG.md) — release notes.
-- [`../SECURITY.md`](../SECURITY.md) — conventional security entrypoint.
-- [`../TODO.md`](https://github.com/adewale/agentic-mermaid/blob/main/TODO.md) — only active backlog with unchecked boxes.
-- [`../Instructions_for_agents.md`](../Instructions_for_agents.md) — canonical agent guide emitted by CLI.
-- [`../AGENT_NATIVE.md`](../AGENT_NATIVE.md) — agent-native architecture/spec entrypoint.
-- [`../PRODUCT.md`](https://github.com/adewale/agentic-mermaid/blob/main/PRODUCT.md) — canonical product brief (brand register).
-- [`../DESIGN.md`](https://github.com/adewale/agentic-mermaid/blob/main/DESIGN.md) — canonical website design system.
+Start with [Getting started](getting-started.md) to render a diagram. For an
+agent editing an existing diagram, use the
+[operating guide](../Instructions_for_agents.md), then the
+[editing cookbook](agent-api-cookbook.md).
+
+## Choose a task
+
+| Task | Guide |
+| --- | --- |
+| Render SVG, PNG or terminal text | [Getting started](getting-started.md) |
+| Choose a diagram type | [Family examples](diagram-families.md) · [Choosing a diagram](choosing-a-diagram.md) |
+| Edit a diagram through the API | [Editing cookbook](agent-api-cookbook.md) |
+| Connect an MCP client | [MCP setup and transports](mcp-http-transport.md) |
+| Render in a browser or React app | [Browser](browser.md) · [React](react.md) |
+| Set colors, typography or drawing style | [Theming](theming.md) · [Style authoring](style-authoring.md) · [Visual cookbook](custom-style-cookbook.md) |
+| Supply fonts | [Custom fonts](custom-fonts.md) |
+| Use ASCII or Unicode | [Terminal output](ascii.md) |
+| Configure Mermaid frontmatter or directives | [Configuration](config.md) |
+| Understand a warning or failed render | [Quality](quality.md) · [Warning reference](https://agentic-mermaid.dev/warnings/) · [Error reference](https://agentic-mermaid.dev/errors/) |
+
+## API and behavior
+
+- [API reference](api.md): functions, options, results and shared vocabulary.
+- [Editing limits](agent-mutation-policy.md): typed and source-preserving edits.
+- [Agent architecture](../AGENT_NATIVE.md): preservation, determinism and verification.
+- [Security](../SECURITY.md): strict output, offline rendering and server boundaries.
+- [Features](features.md) and [fork differences](fork-differences.md).
+- [Comparison](comparison.md): dated measurements and differences from other tools.
+- [Skills](../skills/): instructions for diagram authoring and editor work.
+
+Run `am capabilities --json` for the families and operations in your installed
+version. Use `am styles` to discover its styles. These commands are the current
+inventories; dated reports describe only the revisions they measured.
+
+## Contribute
+
+Repository-only documentation uses GitHub links so this index also works from
+an installed npm package.
+
+| Work | Start here |
+| --- | --- |
+| Understand the renderer | [System architecture](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) |
+| Work on one diagram family | [Family implementation notes](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/README.md) |
+| Add a family | [Adding diagram types](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/adding-diagram-types.md) |
+| Change layout or rendering | [Route contracts](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/route-contracts.md) · [Visual review](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/visual-review-evidence.md) |
+| Select validation | [Testing strategy](testing-strategy.md) |
+| Update documentation | [Doc consistency](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/doc-consistency.md) |
+| Prepare a release | [Release procedure](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/releasing.md) |
+
+## Project records
+
+[TODO.md](https://github.com/adewale/agentic-mermaid/blob/main/TODO.md) is the
+active backlog. The [project index](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/README.md)
+separates current plans from completed and superseded work. Historical research
+and benchmark receipts are context for those decisions, not additional release gates.
+
+See the [changelog](../CHANGELOG.md) for release notes and
+[Trident results](https://github.com/adewale/trident/blob/main/RESULTS.md) for
+performance measurements and their scope.

package/docs/agent-api-cookbook.md

@@ -12,7 +12,7 @@ Agentic Mermaid is not just a renderer. It is a structured edit loop:
 4. **Verify** before any commit point.
 5. **Serialize** only after inspecting `verify.ok`, `verify.warnings`, and, when relevant, `verify.layout`.
 
-For brand-new diagrams, author Mermaid source directly, then parse/verify/render. For existing modeled diagrams, prefer typed mutation so edits preserve structure and round-trip predictably.
+<!-- BEGIN GENERATED: new-diagram-policy -->New diagrams: author Mermaid source directly, then parse → verify → render or return it. `buildMermaid(kind, ops)` / `createMermaid(kind)` build a diagram from typed ops when you are generating one programmatically (for example, from data).<!-- END GENERATED: new-diagram-policy --> For existing modeled diagrams, prefer typed mutation so edits preserve structure and round-trip predictably.
 
 ## Pick the right channel
 
@@ -23,7 +23,11 @@ For brand-new diagrams, author Mermaid source directly, then parse/verify/render
 | Hosted MCP | No local install is available, or a client wants bounded HTTP tools | `https://agentic-mermaid.dev/mcp` tools: `execute`, render/verify/describe, `mutate`, `build` |
 | CLI | Shell-only verification, rendering, preview, or one-shot mutation | `am ...` |
 
-All channels expose the same core contract: parse, optionally narrow, mutate, verify, serialize/render. Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout.
+All channels expose the same core contract: parse, select the typed family when
+editing, mutate, verify, serialize/render. Selecting the family is called
+**narrowing**, not selecting one source object or fixing its coordinates. See
+the [shared vocabulary](./api.md#vocabulary). Agentic Mermaid outputs SVG, PNG,
+ASCII, Unicode, and JSON layout.
 
 ## Recipe: author a new diagram
 
@@ -239,6 +243,7 @@ am render diagram.mmd --format ascii > diagram.txt
 
 MCP channel:
 
+<!-- complete: hosted-mcp-tools -->
 - Local MCP: use Code Mode for parse/narrow/mutate/verify/serialize.
 - Local MCP: use the `render_png` helper for base64 PNG bytes when the host needs a raster artifact.
 - Local HTTP/SSE mode: use `render_png` with `output: "file"` or `output: "url"` when the host wants a managed artifact instead of inline base64.
@@ -281,20 +286,25 @@ Unsupported typed mutation is a stop signal, not a prompt to fake structure. Eit
 
 Tier 1 warnings are reliable structural/source checks. Do not suppress Tier 1 errors unless you fully understand the consequence.
 
-| Code | Meaning |
-|---|---|
-| `EMPTY_DIAGRAM` | Nothing renderable |
-| `EDGE_MISANCHORED` | Edge endpoint is not attached to a real target |
-| `OFF_CANVAS` | Node or edge segment lies outside canvas bounds |
-| `GROUP_BREACH` | Member lies outside its group bounds |
-| `UNKNOWN_SHAPE` | Shape fell back because the name is unrecognized |
-| `LABEL_OVERFLOW` | Label exceeds `labelCharCap` |
-| `UNRESOLVABLE_SCHEDULE` | Gantt parses but its schedule cannot resolve; render would fail |
-| `RENDER_FAILED` | Any family: verifies structurally but the strict render parser rejects the canonical source; `reason` carries the renderer error |
-
-Tier 2 warnings are advisory geometric checks — route tripwires for flowchart/state, plus boundary-anchor/overlap checks on class/ER entity boxes: `NODE_OVERLAP`, `ROUTE_SELF_CROSS`, and the route-contract tripwires `ROUTE_HITCH`, `ROUTE_UNEXPLAINED_BEND`, `ROUTE_LABEL_ON_SHARED_TRUNK`, `ROUTE_SELF_LOOP_OCCUPANCY`, `ROUTE_CONTAINER_MISANCHOR`, `ROUTE_SHAPE_MISANCHOR`, `ROUTE_STALE_AFTER_NODE_MOVE`.
-
-Tier 3 covers advisory lint plus caller-selected inspect-only Brand policy: `DUPLICATE_EDGE`, `UNREACHABLE_NODE`, `DECISION_BRANCH_UNLABELED`, `COMMENT_DROPPED`, `UNSUPPORTED_SYNTAX`, `CONTENT_DROPPED_ON_ROUNDTRIP`, `INEFFECTIVE_CONFIG`, `LOW_CONTRAST`, `BRAND_CONSTRAINT_WARNING`, `BRAND_CONSTRAINT_ERROR`. `LOW_CONTRAST` preserves authored paint and reports its foreground, final opaque background, ratio, and minimum; transparent output is not measured because its host backdrop is unknown. Brand constraints inspect final contrast, accent-area, or mono-role evidence without repainting or relayout. Advisory findings do not flip `verify.ok`; `BRAND_CONSTRAINT_ERROR` does only because the caller explicitly selected `action: "error"`.
+<!-- BEGIN GENERATED: warning-table:structural -->
+| Code | Severity | Description |
+|---|---|---|
+| `EMPTY_DIAGRAM` | error | Diagram contains no renderable elements |
+| `EDGE_MISANCHORED` | error | Edge endpoint does not attach to a real node / participant |
+| `OFF_CANVAS` | error | Node or edge segment lies outside the canvas |
+| `GROUP_BREACH` | error | Member node lies outside its group's bounds |
+| `UNKNOWN_SHAPE` | warning | Shape name unrecognized; default used |
+| `LABEL_OVERFLOW` | warning | A label's longest rendered line exceeds the character cap (default 40, `labelCharCap`): `<br>` and `\n` split lines, XML entities count as one character, and formatting tags are stripped. Families that draw text literally (Pie, Timeline, Gantt, XYChart, GitGraph, Radar) count `<br>` and tags as characters, as drawn. Payload includes `charCount` and `limit`. Character-based, no font-table dependency. |
+| `UNRESOLVABLE_SCHEDULE` | error | The diagram parses and round-trips but its semantics cannot resolve, so rendering will fail loudly. Emitted for structured gantt bodies whose scheduler raises a named `GANTT_*` error (unknown task reference, bad calendar date, dependency cycle, everything-excluded calendar); the payload's `reason` carries that error. |
+| `RENDER_FAILED` | error | Any family: the parser, the strict render parser, layout, or theme colors reject the source or its configuration, so rendering would fail; `origin` says which (`source` or `config`). Generalizes `UNRESOLVABLE_SCHEDULE`'s seam-closing — a clean verify proves the diagram actually renders; the payload's `reason` carries the renderer error. A defect in Agentic Mermaid itself is `INTERNAL_ERROR` instead. |
+| `INTERNAL_ERROR` | error | Agentic Mermaid hit an internal defect while drawing this source; it is not caused by the source. `defaultRender` says whether an ordinary render still produces output: `succeeds-unchecked` — it does, but the extra consistency checks verify runs failed, so its layout evidence cannot be trusted; `fails` — rendering throws. The payload's `reason` carries the internal error. Do not rewrite the diagram to work around it; report it with the source. |
+<!-- END GENERATED: warning-table:structural -->
+
+Tier 2 contains geometric checks. Measured `CONTENT_OCCLUDED` is an error; width-limit and route/overlap warnings are advisory: <!-- BEGIN GENERATED: warning-codes:geometric -->`NODE_OVERLAP`, `CONTENT_OCCLUDED`, `LAYOUT_LIMIT_EXCEEDED`, `ROUTE_SELF_CROSS`, `ROUTE_HITCH`, `ROUTE_UNEXPLAINED_BEND`, `ROUTE_LABEL_ON_SHARED_TRUNK`, `ROUTE_SELF_LOOP_OCCUPANCY`, `ROUTE_CONTAINER_MISANCHOR`, `ROUTE_SHAPE_MISANCHOR`, `ROUTE_STALE_AFTER_NODE_MOVE`<!-- END GENERATED: warning-codes:geometric -->.
+
+Tier 3 covers advisory lint plus caller-selected inspect-only Brand policy: <!-- BEGIN GENERATED: warning-codes:lint -->`DUPLICATE_EDGE`, `UNREACHABLE_NODE`, `DECISION_BRANCH_UNLABELED`, `FLOW_IMBALANCE`, `COMMENT_DROPPED`, `UNSUPPORTED_SYNTAX`, `CONTENT_DROPPED_ON_ROUNDTRIP`, `EVENT_SOURCE_TYPE`, `INEFFECTIVE_CONFIG`, `LOW_CONTRAST`, `LABELS_HIDDEN`, `SCALE_RANGE_EXCLUDES_ZERO`, `BAR_RANGE_EXCLUDES_ZERO`, `VALUES_OUTSIDE_RANGE`, `BRAND_CONSTRAINT_WARNING`, `BRAND_CONSTRAINT_ERROR`<!-- END GENERATED: warning-codes:lint -->. Advisory findings do not flip `verify.ok`; `BRAND_CONSTRAINT_ERROR` does only because the caller explicitly selected `action: "error"`.
+
+Each code's page under <https://agentic-mermaid.dev/warnings/> says what triggers it and how to clear it, and the tier tables in [`AGENT_NATIVE.md`](../AGENT_NATIVE.md#2-verifiable-rendering) describe every code; both are generated from `src/agent/warning-catalog.ts`.
 
 ## Common anti-patterns
 

package/docs/agent-mutation-policy.md

@@ -31,23 +31,13 @@ When a particular body does not narrow, agents are not told it can be safely edi
 
 ## Current split
 
-Structured mutation is exposed for every built-in renderable family when its modeled subset narrows:
-
-- flowchart/state;
-- sequence (segment-preserving: `alt`/`opt`/`loop`/`par` are typed fragments with read-back and mutation ops; Note/box/critical/activate/autonumber/title ride along verbatim as opaque-block segments. Top-level message indices stay separate from fragment-message indices. Only un-segmentable input, e.g. an unbalanced `end`, falls back to whole-body opaque);
-- timeline;
-- class;
-- ER;
-- journey (simple title/section/task bodies; BUILD-15);
-- architecture (modeled groups/services/junctions/edges; BUILD-17);
-- xychart (modeled title/axes/series; BUILD-16);
-- pie (title/showData/slices);
-- quadrant (title/axes/quadrant labels/points);
-- gantt (title/sections/tasks, with calendar directives and click/comment/accessibility lines preserved as opaque segments).
+Structured mutation is exposed for every built-in renderable family when its modeled subset narrows. `am capabilities --json` lists each family's narrower and `mutationOps`, and `describeOps(family)` gives the exact op fields; this page does not keep a second roster.
+
+Some families are segment-preserving rather than all-or-nothing: sequence keeps `alt`/`opt`/`loop`/`par` as typed fragments (with their own read-back and mutation ops) while Note/box/critical/activate/autonumber/title ride along verbatim, and its top-level message indices stay separate from fragment-message indices; gantt keeps calendar directives and click/comment lines as verbatim segments; ER keeps ordered typed and opaque-block segments. Only input that cannot be segmented (e.g. an unbalanced `end`) falls back to a whole-body opaque body.
 
 Opaque/source-level bodies:
 
-- any known-family diagram that falls back to an opaque body because it contains unmodeled syntax (e.g. architecture `{group}` boundary modifiers, accTitle/accDescr, malformed pie entries, out-of-range quadrant coordinates, or un-segmentable sequence/gantt syntax).
+- any known-family diagram that falls back to an opaque body because it contains unmodeled syntax (e.g. architecture `{group}` boundary modifiers, malformed pie entries, out-of-range quadrant coordinates, or un-segmentable sequence/gantt syntax).
 
 For source-level bodies, the safe loop is:
 
@@ -57,7 +47,73 @@ For source-level bodies, the safe loop is:
 4. verify;
 5. only then return or serialize.
 
-`am mutate` should return `UNSUPPORTED_FAMILY` for those bodies.
+Ordinary `am mutate` returns `UNSUPPORTED_FAMILY` for those bodies. Explicit
+source-preserving mutation supports four bounded operations on opaque inputs:
+
+- Class `add_member`: append an ordinary attribute or method declaration.
+- Class `remove_member`: remove an unambiguous member that owns one complete
+  physical line, without comments or directives. The index follows authored
+  member order, including annotations; selecting an annotation is refused.
+- Flowchart `set_label`: append a label override for an existing native node.
+- Flowchart `rename_node`: replace owned lexical node identities in declarations,
+  endpoints and group membership. Class assignments, styles, click/href
+  dependencies and colliding group identities are refused.
+
+These edits retain bytes outside the owned edit ranges and compare the complete
+native read-back with the requested change before committing. Unsupported or
+ambiguous ownership, dependency changes and semantic mismatches reject the edit
+atomically. A repeated label with no semantic change retains the exact source,
+including its final newline spelling.
+
+Rename does not rewrite dependent directives. A changing rename refuses sources
+with any `class`, `style`, `click` or `href` statement, even when it names another
+node. An explicit ID-equal label such as `A[A]` also refuses the change because
+the lexical edit would retain a label that ordinary rename changes. These
+refusals keep the edit within the scanner's proven ownership.
+
+Appending preserves the complete previous source as a prefix: each changing
+Flowchart label adds an override, and each Class member addition adds a reopened
+class block. Repeated edits therefore grow the document; this mode does not
+compact earlier declarations. Member removal and node rename instead replace
+only their owned ranges. Each changing edit still reparses the complete public
+diagram and rebuilds its source spans.
+
+```ts
+const edited = mutatePreservingSource(diagram, {
+  kind: 'set_label', target: 'A', label: 'Reviewed',
+})
+if (edited.ok) {
+  const verification = verifyMermaid(edited.value.diagram)
+  if (!verification.ok) throw new Error('verify failed')
+  // Inspect warnings and save exact source; do not canonicalize it.
+  await save(edited.value.source)
+}
+```
+
+The result is `{ source, diagram }`. Its exact `source` is the save artifact;
+the ordinary serializer may normalize the final newline. The diagram remains
+opaque and retains its portability warning. This API does not make invalid
+Mermaid syntax portable, admit every member/label payload, or expose opaque
+bodies through structural narrowers. Structured inputs should use `mutate`;
+the default mutation mode retains its structured-only contract.
+
+The same explicit mode is available through the workflow surfaces:
+
+- Library batches: `applyOps({ source, ops, mode: 'source-preserving' })`.
+- CLI: `am mutate diagram.mmd --op '<JSON>' --preserve-source`; JSONL mutation
+  requests use `preserveSource: true`.
+- Declarative MCP `mutate`: pass `mode: 'source-preserving'` with `source` and
+  `ops`.
+- Code Mode: `mermaid.mutatePreservingSource(diagram, op)` returns the same
+  `{ source, diagram }` result as the library. Returning that successful result
+  or its diagram produces a verified envelope with the exact edited source.
+- Editor adapter: programmatic `applyOps(source, ops, 'source-preserving')`
+  queues the edit in the persistent worker; it does not add an editor control.
+
+Batch success includes `mode: 'source-preserving'` and verification diagnostics.
+A failed batch emits no edited source, even when earlier operations succeeded.
+Builders have no original source and do not accept this mode. These entrypoints
+do not remove the portability warning or promise portable Mermaid export.
 
 ## Why not every syntax construct?
 
@@ -102,3 +158,18 @@ An opaque fallback path can become structurally mutable only when a scoped imple
 6. update CLI/MCP/capabilities/docs together.
 
 Until then, opaque/source-level editing is the honest behavior for that body.
+
+
+## Comments and transaction boundaries
+
+Flowchart and State body comments are retained in metadata beside semantic
+statement identities. Serialization re-emits safe standalone `%%` comments;
+inline placement may normalize. If an edit removes an anchor, its comment is
+retained at the end rather than discarded. Leading wrapper bytes retain their
+existing verbatim contract. Other families keep their existing segmented/opaque
+policies and report any known loss.
+
+Declarative edits, CLI batches, and builders apply checked operations to private
+intermediate bodies, then serialize and reparse once at commit. A failed operation
+returns its index and emits no edited source; the original diagram stays untouched.
+Single public `mutate` calls retain parser-closure checks at each call boundary.

package/docs/agent-workflow-examples.md

@@ -16,7 +16,7 @@ What it demonstrates:
 - CLI path: `am mutate auth-flow.mmd --ops ops.json --json` applies the same mutation batch and verifies before emitting source.
 - The example asserts both channels produce byte-identical Mermaid source for multiple non-trivial cases: an Auth Flow with decisions/feedback loops and an Order Domain ER diagram.
 
-This is the intended local equivalence story: MCP Code Mode and CLI/library can create the same diagram. The local non-Code-Mode helpers remain narrow (`describe_sdk`, `render_png`, `describe`); `describe_sdk` returns one family's version-matched mutation schema on demand. The hosted `/mcp` endpoint additionally offers direct pure render/verify/describe tools plus declarative `mutate`/`build` for bounded structured edits.
+This is the intended local equivalence story: MCP Code Mode and CLI/library can create the same diagram. Local MCP also exposes declarative `mutate`/`build` and the pure helpers `describe_sdk`, `render_png`, and `describe`; `describe_sdk` returns one family's version-matched mutation schema on demand. The hosted `/mcp` endpoint additionally offers direct pure render/verify tools; its declarative edits share the local implementation with a 64 KB input limit.
 
 ## Improve a diagram through an agent loop