agentic-mermaid 0.1.0 → 0.1.2

package/skills/agentic-mermaid-diagram-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentic-mermaid-diagram-workflow
-description: Agent-agnostic skill for authoring and editing Mermaid diagrams with structured verification, typed mutation, round-trip serialization, and SVG, PNG, ASCII, Unicode, and JSON layout outputs. Structured mutation for all twelve renderable families (flowchart, state, sequence, timeline, class, ER, journey, architecture, xychart, pie, quadrant, gantt); source-level parse-and-render only for opaque fallbacks (unmodeled syntax).
+description: Agent-agnostic skill for authoring and editing Mermaid diagrams with structured verification, typed mutation, round-trip serialization, and graphical, terminal, and layout outputs. The live capability registry identifies renderable and mutable families; unmodeled syntax remains source-preserved.
 ---
 
 # Agentic Mermaid — diagram workflow
@@ -12,40 +12,20 @@ An agent-agnostic typed editing surface for Mermaid. New diagrams can be authore
 - `agentic-mermaid-mcp` connected → **Code Mode** (`references/code-mode.md`). Multi-step edits in one round-trip.
 - Can run JS/TS with imports → **library** (`agentic-mermaid/agent`). Same SDK.
 - Shell only → **CLI** (`references/cli.md`).
-- No local install, network only → **hosted MCP** at `https://agentic-mermaid.dev/mcp` (stateless streamable HTTP JSON-RPC; the `execute` Code Mode tool plus `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` and the declarative `mutate` (edit a `source`) / `build` (author from a `family`) tools — prefer `mutate`/`build` for structured edits; 64KB input caps).
-
-## Capability matrix
-
-| Family | parse | verify | render | mutate | serialize |
-|---|---|---|---|---|---|
-| Flowchart | ✓ | full (Tier 1+2) | ✓ | 6 ops | structured |
-| **State (modeled subset)** | ✓ | full (Tier 1+2) | ✓ | **8 ops** | structured |
-| State (`<<fork>>`/`<<choice>>`/notes/`--`/`classDef`, unmodeled) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| Sequence (simple) | ✓ | structural | ✓ | 5 ops | structured |
-| Sequence (notes/alt/loop/…) | ✓ | structural | ✓ | **5 ops** | structured-with-segments |
-| Sequence (un-segmentable, e.g. unbalanced `end`) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| Timeline (simple) | ✓ | structural | ✓ | 10 ops | structured |
-| Timeline (unmodeled syntax) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **Class (simple)** | ✓ | structural | ✓ | **10 ops** | structured |
-| Class (unmodeled syntax) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **ER (simple)** | ✓ | structural | ✓ | **7 ops** | structured |
-| ER (unmodeled syntax) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **Journey (simple)** | ✓ | structural | ✓ | **10 ops** | structured |
-| Journey (accTitle/accDescr, unmodeled) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **Architecture (modeled subset)** | ✓ | structural | ✓ | **10 ops** | structured |
-| Architecture (`{group}` boundary, accTitle/accDescr) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **XY chart (modeled subset)** | ✓ | structural | ✓ | **8 ops** | structured |
-| XY chart (quoted text, `;` lines, accTitle/accDescr) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **Pie (simple)** | ✓ | structural | ✓ | **7 ops** | structured |
-| Pie (accTitle/accDescr, malformed entries) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **Quadrant (modeled subset)** | ✓ | structural | ✓ | **7 ops** | structured |
-| Quadrant (styling `classDef`/`:::`, out-of-range coords) | ✓ | structural | ✓ | — (opaque) | verbatim |
-| **Gantt (modeled subset)** | ✓ | structural + schedule | ✓ | **9 ops** | structured-with-segments |
-| Gantt (duplicate ids / unclosed `accDescr`) | ✓ | structural | ✓ | — (opaque) | verbatim |
+- No local install, network only → **hosted MCP** at `https://agentic-mermaid.dev/mcp` (stateless streamable HTTP JSON-RPC; `execute` Code Mode, `describe_sdk` for one family's mutation schema on demand, `render_svg`/`render_ascii`/`render_png`/`verify`/`describe`, and the declarative `mutate` (edit a `source`) / `build` (author from a `family`) tools — prefer `mutate`/`build` for structured edits; 64KB input caps).
+
+## Capability discovery
+
+Run `am capabilities --json` (or call the equivalent SDK capability API) before
+choosing a family or mutation. Its registry-derived family entries expose the
+current narrower, operation schema, edit policy, output support, and minimal
+source example; the generated Section A matrix supplies explicit native,
+source-preserved, diagnosed, and absent states. This skill intentionally does
+not maintain a second family or operation table.
 
 Any diagram with constructs we don't model falls back to an **opaque** body: it still parses, renders, verifies, and round-trips losslessly — it just isn't offered for structured mutation (the narrower returns null). The parser never silently drops anything.
 
-State diagrams own a dedicated body (BUILD-19): narrow them with `asState` and apply state-shaped ops (`add_state`, `remove_state`, `rename_state`, `set_state_label`, `add_transition`, `remove_transition`, `set_transition_label`, `make_composite`). `asFlowchart` returns null on a state diagram. The modeled subset is simple states, transitions, `[*]` start/end pseudostates, composite blocks, and `direction`; anything else (`<<fork>>`/`<<choice>>`/`<<join>>`, history states, concurrency `--`, notes, `classDef`/`class`/`:::` styling) keeps the whole body opaque and round-trips verbatim.
+State diagrams own a dedicated body: `asState` models states/transitions, `[*]`, composites, stereotypes/history, concurrency regions, notes, bare declarations, and class/inline paint. `asFlowchart` returns null on a state diagram.
 
 Gantt diagrams are segment-preserving: `asGantt` keeps title/section/task ops live while calendar directives (`dateFormat`, `axisFormat`, `excludes`, `includes`, `weekend`, `weekday`, `todayMarker`, `tickInterval`, `inclusiveEndDates`, `topAxis`), `click` lines, comments, and accessibility lines ride along verbatim. Gantt rendering is deterministic and never reads the wall clock; pass `ganttToday` when rendering if a `todayMarker` should be visible.
 
@@ -53,10 +33,11 @@ Gantt diagrams are segment-preserving: `asGantt` keeps title/section/task ops li
 
 ## Workflow
 
-For new diagrams, author Mermaid source directly, then `parseMermaid` / `verifyMermaid` / render. For existing modeled diagrams:
+For new diagrams, author Mermaid source directly, then `parseRegisteredMermaid` / `verifyMermaid` / render. For existing modeled diagrams:
 
-1. `parseMermaid(source)` → `ValidDiagram`.
-2. `asFlowchart(d)` / `asState(d)` / `asSequence(d)` / `asTimeline(d)` / `asClass(d)` / `asEr(d)` / `asJourney(d)` / `asArchitecture(d)` / `asXyChart(d)` / `asPie(d)` / `asQuadrant(d)` / `asGantt(d)` to narrow before mutating.
+1. `parseRegisteredMermaid(source)` → `ValidDiagram`.
+2. Use the family entry's advertised narrower (for example `asFlowchart(d)` or
+   `asState(d)`) before mutating.
 3. `mutate(d, op)` (typed per family).
 4. `verifyMermaid(d)` — structured warnings; inspect `ok` / `warnings` / `layout`.
 5. On `!ok`, revert to the previous `ValidDiagram`, try another op.
@@ -67,7 +48,7 @@ Do not regenerate or concatenate source to edit an existing structured diagram w
 Minimal existing-flowchart pattern:
 
 ```ts
-const parsed = parseMermaid(source)
+const parsed = parseRegisteredMermaid(source)
 if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
 let cur = asFlowchart(parsed.value)
 if (!cur) return { phase: 'narrow', family: parsed.value.kind }

package/skills/agentic-mermaid-diagram-workflow/references/cli.md

@@ -3,7 +3,7 @@
 Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout through the CLI.
 
 ```text
-am render <file|-> --format svg|ascii|unicode|json
+am render <file|-> --format svg|ascii|unicode|layout
 am render <file> --format png --output file.png  # one-shot only; no watch/multi-input
 am preview <file|-> [--output preview.html] [--open] [--json] [--security strict]  # strict standalone HTML
 am verify <file|->            structured JSON warnings (exit 3 if not ok)
@@ -22,10 +22,9 @@ am --agent-instructions       canonical agent guide
 am <cmd> --help               per-command help
 ```
 
-`am verify` always emits JSON. `am mutate` dispatches by family across
-flowchart, state, sequence, timeline, class, ER, journey, architecture,
-xychart, pie, quadrant, and gantt; opaque fallback bodies return a structured
-`UNSUPPORTED_FAMILY` error. `am mutate` verifies before emitting source; verify
+`am verify` always emits JSON. `am mutate` dispatches across the live mutable
+family roster reported by `am capabilities --json`; opaque fallback bodies
+return a structured `UNSUPPORTED_FAMILY` error. `am mutate` verifies before emitting source; verify
 failure exits 3 and omits `source`. Use direct Mermaid source authoring plus
 `am verify`/`am render` for brand-new diagrams; reserve `am mutate` for
 existing structured diagrams. `am parse | am serialize` round-trips through JSON.

package/skills/agentic-mermaid-diagram-workflow/references/code-mode.md

@@ -1,7 +1,11 @@
 # Code Mode (structured edit channel)
 
 `agentic-mermaid-mcp` exposes a primary Code Mode tool, `execute(code)`, plus
-narrow `render_png` and `describe` helpers. The server runs JavaScript in a
+narrow `describe_sdk`, `render_png`, and `describe` helpers. The initial
+`execute` declaration contains only the core SDK. Call
+`describe_sdk({ family, detail: 'fields' })` before an unfamiliar mutation to
+load that family's exact schema; use `detail: 'signatures'` for a compact menu.
+The server runs JavaScript in a
 `node:vm` sandbox with `mermaid.*` as a global; the TypeScript declaration in
 the MCP prompt is for guidance, not transpilation. SDK-returned diagrams are
 read-only in Code Mode; use `mermaid.mutate(...)` for structured edits instead
@@ -12,31 +16,11 @@ verify-before-commit loop is one round-trip.
 ## SDK shape
 
 ```text
-mermaid.parseMermaid(source): Result<ValidDiagram, ParseError[]>
-mermaid.asFlowchart(d): FlowchartValidDiagram | null
-mermaid.asState(d):     StateValidDiagram | null
-mermaid.asSequence(d):  SequenceValidDiagram | null
-mermaid.asTimeline(d):  TimelineValidDiagram | null
-mermaid.asClass(d):     ClassValidDiagram | null
-mermaid.asEr(d):        ErValidDiagram | null
-mermaid.asJourney(d):   JourneyValidDiagram | null
-mermaid.asArchitecture(d): ArchitectureValidDiagram | null
-mermaid.asXyChart(d):   XyChartValidDiagram | null
-mermaid.asPie(d):       PieValidDiagram | null
-mermaid.asQuadrant(d):  QuadrantValidDiagram | null
-mermaid.asGantt(d):     GanttValidDiagram | null
-mermaid.mutate(flow,     FlowchartMutationOp): Result<FlowchartValidDiagram, MutationError>
-mermaid.mutate(state,    StateMutationOp):     Result<StateValidDiagram, MutationError>
-mermaid.mutate(seq,      SequenceMutationOp):  Result<SequenceValidDiagram, MutationError>
-mermaid.mutate(timeline, TimelineMutationOp):  Result<TimelineValidDiagram, MutationError>
-mermaid.mutate(klass,    ClassMutationOp):     Result<ClassValidDiagram, MutationError>
-mermaid.mutate(er,       ErMutationOp):        Result<ErValidDiagram, MutationError>
-mermaid.mutate(journey,  JourneyMutationOp):   Result<JourneyValidDiagram, MutationError>
-mermaid.mutate(arch,     ArchitectureMutationOp): Result<ArchitectureValidDiagram, MutationError>
-mermaid.mutate(xy,       XyChartMutationOp):   Result<XyChartValidDiagram, MutationError>
-mermaid.mutate(pie,      PieMutationOp):       Result<PieValidDiagram, MutationError>
-mermaid.mutate(quad,     QuadrantMutationOp):  Result<QuadrantValidDiagram, MutationError>
-mermaid.mutate(gantt,    GanttMutationOp):     Result<GanttValidDiagram, MutationError>
+mermaid.parseRegisteredMermaid(source): Result<ValidDiagram, ParseError[]>
+mermaid.asFlowchart(d): FlowchartValidDiagram | null  // example narrower
+mermaid.mutate(narrowed, op): Result<ValidDiagram, MutationError> // concrete overload preserves the family
+// Call describe_sdk({ family, detail: 'fields' }) for the registry-derived
+// narrower and exact family operation overloads.
 mermaid.verifyMermaid(input, { suppress?, labelCharCap? }): VerifyResult
 mermaid.describeMermaidFacts(d): string[]
 mermaid.checkMermaid(d, spec): { ok: boolean; missing: string[]; unexpected: string[]; facts: string[] }
@@ -45,7 +29,7 @@ mermaid.renderMermaidASCII(input, { useAscii?: boolean, ganttToday?: string, mer
 mermaid.renderMermaidSVG(input, { security?: 'default'|'strict', idPrefix?, ganttToday?: string, mermaidConfig?: MermaidRuntimeConfig }): string
 ```
 
-Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout. In Code Mode, render SVG and text through `mermaid.*`: `renderMermaidASCII(input, { useAscii: true })` returns ASCII and `useAscii: false` returns Unicode box-drawing text. Use the narrow MCP `render_png` helper or host/library code for PNG binary output; JSON layout is available on `verifyMermaid(...).layout` and through the CLI/library layout APIs. `MermaidRuntimeConfig` matches the runtime config surface: arbitrary Mermaid config keys plus `theme`, `fontFamily`, `themeVariables`, `timeline`, `xyChart`, `gantt`, `useMaxWidth`, `useWidth`, and `themeCSS`. `ganttToday` is a render option, not a clock read; pass it when a Gantt `todayMarker` should render.
+Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout. In Code Mode, render SVG and text through `mermaid.*`: `renderMermaidASCII(input, { useAscii: true })` returns ASCII and `useAscii: false` returns Unicode box-drawing text. Use the narrow MCP `render_png` helper or host/library code for PNG binary output; JSON layout is available on `verifyMermaid(...).layout` and through the CLI/library layout APIs. `MermaidRuntimeConfig` matches the runtime config surface: arbitrary Mermaid config keys plus `theme`, `fontFamily`, `themeVariables`, `timeline`, `xyChart`, `gantt`, `mindmap`, `gitGraph`, `useMaxWidth`, `useWidth`, and `themeCSS`. `ganttToday` is a render option, not a clock read; pass it when a Gantt `todayMarker` should render.
 
 All SDK methods are synchronous and pure. Code Mode does not support `async`/`await`, Promise jobs, or dynamic import. Layout is deterministic; there is no layout seed (the render option `seed` only re-rolls ink of styled looks — `style: name | record | stack` — and never moves geometry).
 
@@ -53,7 +37,7 @@ All SDK methods are synchronous and pure. Code Mode does not support `async`/`aw
 
 ```ts
 const source = 'flowchart LR\n  User --> Login\n  Login --> Dashboard'
-const parsed = mermaid.parseMermaid(source)
+const parsed = mermaid.parseRegisteredMermaid(source)
 if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
 const v = mermaid.verifyMermaid(parsed.value)
 if (!v.ok) return { phase: 'verify', warnings: v.warnings }
@@ -68,7 +52,7 @@ const ops = [
   { kind: 'add_node', id: 'Cache', label: 'Cache' },
   { kind: 'add_edge', from: 'API', to: 'Cache' },
 ]
-const r0 = mermaid.parseMermaid(source)
+const r0 = mermaid.parseRegisteredMermaid(source)
 if (!r0.ok) return { phase: 'parse', errors: r0.error }
 const flow = mermaid.asFlowchart(r0.value)
 if (!flow) return { phase: 'narrow', kind: r0.value.kind }
@@ -86,7 +70,7 @@ return { source: mermaid.serializeMermaid(cur) }
 ## Sequence pattern
 
 ```ts
-const r0 = mermaid.parseMermaid('sequenceDiagram\n  Alice->>Bob: Hi')
+const r0 = mermaid.parseRegisteredMermaid('sequenceDiagram\n  Alice->>Bob: Hi')
 if (!r0.ok) return { errors: r0.error }
 const seq = mermaid.asSequence(r0.value)
 if (!seq) return { kind: r0.value.kind, note: 'opaque — no structured sequence mutation' }
@@ -102,7 +86,7 @@ return { source: mermaid.serializeMermaid(r1.value) }
 ```ts
 const sources = ['flowchart TD\n  A --> C', 'timeline\n  2024 : A ships']
 return sources.map(src => {
-  const r = mermaid.parseMermaid(src)
+  const r = mermaid.parseRegisteredMermaid(src)
   if (!r.ok) return { err: r.error }
   const flow = mermaid.asFlowchart(r.value)
   if (!flow) return { skipped: true, family: r.value.kind, reason: 'no matching structured op' }

package/skills/agentic-mermaid-diagram-workflow/references/sequence.md

@@ -14,21 +14,17 @@ implicitly by first message reference.
 Arrows → style: `->>` sync, `-->>` reply, `->` async, `-->` async-dashed,
 `-x` lost, `--x` lost-dashed.
 
-MutationOps (5): add_participant, remove_participant (cascades to messages),
-add_message (implicit participants), remove_message (by index),
-set_message_text (by index).
+MutationOps include participant/top-level message edits plus `add_fragment`,
+`remove_fragment`, fragment/branch label edits, and fragment-message add/remove/
+text edits.
 
-IMPORTANT — segment-preserving fidelity (BUILD-18): a sequence diagram that uses
-Note/alt/opt/par/loop/critical/break/rect/activate/autonumber/title parses to a
-STRUCTURED body that keeps your participant/message ops live. The unmodeled lines
-ride along VERBATIM as opaque-block segments, so `asSequence` is non-null and you
-can add_message / set_message_text / remove_message as usual. Two rules: (1)
-`remove_message`/`set_message_text` indexes address only TOP-LEVEL messages —
-messages inside an alt/loop block are part of the verbatim segment and are never
-touched; (2) only an un-segmentable diagram (a stray `end`, an unclosed block)
-falls back to a whole-body OPAQUE body where `asSequence` returns null — for those,
-edit the preserved `body.source` intentionally, then re-parse and verify. Either
-way the round-trip is lossless and the parser never silently drops constructs.
+IMPORTANT — segment-preserving fidelity: `alt`, `opt`, `loop`, and `par` are
+typed fragments. Their messages appear in describe/facts/verify and fragment
+ops can author or edit them. Other constructs (Note/critical/break/rect/box/
+activate/autonumber/title) ride along VERBATIM as opaque-block segments while
+participant and top-level message ops remain live. Only an un-segmentable
+diagram (a stray `end`, an unclosed block) falls back to a whole-body OPAQUE
+body. Either way the parser never silently drops constructs.
 
 Verify Tier 1 only (no layout engine): EMPTY_DIAGRAM, EDGE_MISANCHORED
 (message references missing participant), LABEL_OVERFLOW (participant label or

package/skills/agentic-mermaid-live-editor/SKILL.md

@@ -1,264 +1,158 @@
 ---
 name: agentic-mermaid-live-editor-development
 description: >-
-  Agent-agnostic development skill for the Agentic Mermaid live editor.
-  Use when modifying scripts/site/editor.ts, adding Config options, changing the UI, adding
-  ASCII, PNG, or SVG export behavior, wiring new diagram options, or debugging
-  the editor page.
+  Develop and debug the Agentic Mermaid browser editor, including its modular UI,
+  render/verify pipeline, examples, configuration, exports, URL sharing, website
+  integration, and browser regression tests.
 ---
 
-# Agentic Mermaid — live editor development
+# Agentic Mermaid live editor development
 
-This skill is for coding agents modifying the repository. It is not tied to Claude, Cursor, Pi, or any other single coding agent. The editor renders diagrams through Agentic Mermaid and exposes SVG and PNG export actions; the renderer also supports ASCII output in the library/CLI surface.
+Edit the modular editor sources and preserve the contracts shared by the standalone editor and the deployed website.
 
-## Key files
+## Source map
 
-| File | Role |
-|------|------|
-| `scripts/site/editor.ts` | **Source of truth** — generates `editor.html` at build time (also used by `website/build.ts` for the Cloudflare `/editor`) |
-| `editor.html` | Generated output — never edit directly |
-| `src/browser.ts` | Bundles the renderer for the browser as `window.__mermaid` |
-| `src/types.ts` | `RenderOptions` — all supported render options |
-| `src/theme.ts` | `THEMES`, `buildStyleBlock`, `svgOpenTag` — CSS variable system |
-| `src/styles.ts` | `STROKE_WIDTHS`, `FONT_SIZES` — hardcoded constants |
-| `scripts/site/samples-data.ts` | Sample presets used by eval tooling; the editor uses its own inline `SAMPLES` array |
+| Path | Role |
+|---|---|
+| `editor/js/` | Editor behavior. Treat `sharing.js`, `rendering.js`, and `state.js` as contract sources. |
+| `editor/css/` | Editor styling. |
+| `editor/html/` | Top bar and workspace partials. |
+| `editor/examples.ts` | Canonical editor examples. |
+| `scripts/site/editor.ts` | Assemble the standalone `editor.html`. |
+| `website/build.ts` | Assemble the deployed `/editor/` and all public pages that link to it. |
+| `scripts/site/editor-state-url.ts` | Canonical build-time encoder and validator for editor-state URLs. |
+| `src/browser.ts` | Browser renderer API exposed as `window.__mermaid`. |
 
-## Build cycle
+Do not edit generated `editor.html` or `website/public/` files directly.
 
-```
-scripts/site/editor.ts  ──Bun.build──►  src/browser.ts bundle (inline JS)
-                         ──template──►   editor.html  (self-contained, ~1.7 MB)
-```
+## Build and test cycle
+
+Run the target that owns the changed surface:
 
-Run manually:
 ```bash
-bun run editor       # generates editor.html once
-bun run website:dev  # wrangler dev server for the Cloudflare site (serves /editor and the rest)
+bun run editor          # standalone editor.html
+bun run website         # production website/public, including /editor/
+bun run website:check   # committed generated inputs are current
+bun run typecheck
 ```
 
-**Always rebuild after editing `scripts/site/editor.ts`.** The HTML file is the deployed artifact.
-
----
-
-## Architecture overview
+For behavior changes, also run the focused editor unit tests and the browser lane. The browser lane requires Playwright Chromium and `AM_BROWSER_TESTS=1`.
 
-`scripts/site/editor.ts` is a TypeScript generator that:
-1. Calls `Bun.build()` to bundle `src/browser.ts` → inline JS string
-2. Constructs the full HTML page as a template literal
-3. Writes `editor.html`
+## State contract
 
-The page has **no runtime build step** — everything (renderer, UI logic, CSS) is inlined.
-
-### State model (in the client JS)
+Keep editor state in the canonical shape from `editor/js/state.js`:
 
 ```js
 state = {
-  theme: '',        // active diagram theme key ('' = Default)
-  zoom: 1,          // current preview zoom level
-  config: {},       // active RenderOptions overrides (from Config panel)
+  palette: 'paper',
+  style: 'crisp',
+  seed: 0,
+  zoom: 1,
+  config: {},
 }
-
-cfgColors  = { bg, fg, accent, line, muted, surface }  // color overrides
-cfgFont    = ''     // font name (bare, e.g. 'Inter')
-cfgPadding = 24     // padding px
-cfgEdgeStroke = 1   // edge line stroke width
-cfgNodeStroke = 1   // node border stroke width
-```
-
-### Render pipeline
-
-```
-editor input
-  → scheduleRender(debounce ms)
-    → doRender()
-      → buildOptions()        // merges theme (base) + config (overrides)
-      → renderMermaid(source, opts)   // window.__mermaid.renderMermaidSVGAsync
-      → previewInner.innerHTML = svg
-      → applyStrokeOverrides(svgEl)   // injects <style> for stroke widths
-      → applyZoom(state.zoom)         // sets SVG width/height from viewBox × zoom
-```
-
-**Important**: `buildOptions()` layers options as `Object.assign(themeBase, state.config)` — config always wins over theme.
-
----
-
-## How to add a Config option
-
-### Case A: RenderOptions already supports it (colors, font, padding)
-
-1. Add UI in the relevant `config-section` in the HTML template inside `scripts/site/editor.ts`
-2. Add a JS state variable (e.g. `var cfgFoo = defaultVal`)
-3. Update `readConfig()` to include it in `state.config`
-4. Wire input events
-5. Rebuild
-
-### Case B: Post-process SVG (stroke widths, opacity, etc.)
-
-Use CSS injection via `applyStrokeOverrides` pattern — no renderer changes needed:
-
-```js
-// After render:
-var style = document.createElementNS('http://www.w3.org/2000/svg', 'style');
-style.id = '__bm-my-override';
-style.textContent = 'rect { opacity: 0.8; }';
-svgEl.insertBefore(style, svgEl.firstChild);
 ```
 
-CSS rules override SVG presentation attributes (lower specificity). No `!important` needed.
-
-Call your override function in:
-- `doRender()` — after `previewInner.innerHTML = svg`
-- Any slider/input `change` handler directly (instant, no re-render)
+- `palette` stores the registered palette input name.
+- `style` stores the registered Look input name or `crisp`.
+- `seed` affects styled ink without changing layout.
+- `config` contains admitted serializable render options.
+- Browser chrome dark/light mode is separate from diagram appearance and must not rewrite `state.palette`.
 
-### Case C: Requires renderer support
+When adding state, update serialization, sanitization, restoration, control hydration, and tests together.
 
-Add to `RenderOptions` in `src/types.ts`, normalize through `resolveDiagramColors` in `src/color-resolver.ts` when it affects the semantic palette, then expose it through `svgOpenTag`/`buildStyleBlock` in `src/theme.ts` when the live editor needs a CSS-variable override.
-
----
+## Render and verification boundary
 
-## Adding a color field
-
-1. Add to `cfgColors` object: `cfgColors.myColor = ''`
-2. Add `THEME_COLOR_MAP` entry if the theme has a matching property
-3. Add HTML in the Colors section:
-```html
-<div class="color-field">
-  <span class="color-field-label">My Color</span>
-  <button class="color-edit-btn" data-cfg="myColor">
-    <span class="cfg-hex-label" id="cfg-myColor-label">—</span>
-    <span class="color-swatch" id="cfg-myColor-swatch"></span>
-  </button>
-</div>
-```
-4. Update `readConfig()`: `if (cfgColors.myColor) cfg.myColor = cfgColors.myColor`
-5. Ensure `refreshAllColorUIs()` covers it (it uses `Object.keys(cfgColors)` so automatic)
-
----
+Follow the pipeline in `editor/js/rendering.js`:
 
-## Adding a slider (Layout section)
-
-```html
-<div class="padding-field">
-  <div class="padding-row">
-    <label>My Setting</label>
-    <input class="padding-num" id="cfg-my-val" type="number" min="0" max="100" value="10" />
-  </div>
-  <input class="padding-slider" id="cfg-my-val-slider" type="range" min="0" max="100" value="10" />
-</div>
+```text
+editor input
+  -> scheduleRender()
+  -> doRender()
+  -> buildOptions()
+  -> renderMermaidSVGWithReceipt()
+  -> verifyNoExternalRefs()
+  -> insertStrictRenderedSvg()
+  -> verifyMermaid()
+  -> retain the receipt-bearing artifact only when verification succeeds
 ```
 
-```js
-var cfgMyVal = 10;
-var myNum    = document.getElementById('cfg-my-val');
-var mySlider = document.getElementById('cfg-my-val-slider');
-
-function setMyVal(v) {
-  v = Math.max(0, Math.min(100, parseFloat(v) || 10));
-  cfgMyVal = v;
-  myNum.value    = v;
-  mySlider.value = v;
-  // apply effect...
-}
-myNum.addEventListener('input',    function() { setMyVal(myNum.value); });
-mySlider.addEventListener('input', function() { setMyVal(mySlider.value); });
-```
+Keep `security: "strict"` and `embedFontImport: false` host-owned. Admit restored configuration through `SHARED_RENDER_OPTION_FIELDS` and `validateSerializableRenderOptions`; never trust hash or storage data directly. Insert one parsed SVG node with `replaceChildren`, not arbitrary shared HTML.
 
----
+Do not enable share or export actions from stale DOM. Require the current source, receipt digests, verified artifact, and preview SVG to agree.
 
-## Adding a sample preset
+## URL sharing contract
 
-Edit the `SAMPLES` array near the top of `scripts/site/editor.ts`:
+Treat the URL payload as a versioned producer/consumer boundary. The canonical state is:
 
 ```ts
 {
-  category: 'Flowchart',   // must match an existing cat or add a new button
-  title: 'My Sample',
-  source: `graph TD\n  A --> B`,
-},
-```
-
-If adding a new category, the category button is generated automatically from unique categories in `SAMPLES`.
-
----
-
-## Zoom system
-
-Zoom sets the SVG's **actual `width`/`height`** attributes (not CSS `transform: scale`), so the scroll container expands correctly.
-
-```js
-function applyZoom(z) {
-  state.zoom = clamp(z, 0.1, 8);
-  var nat = getSvgNaturalSize(svgEl);  // reads viewBox
-  svgEl.style.width  = nat.w * z + 'px';
-  svgEl.style.height = nat.h * z + 'px';
+  source: string
+  palette?: string
+  style?: string
+  seed?: number
+  config?: Record<string, unknown>
 }
 ```
 
-Always call `applyZoom(state.zoom)` after inserting a new SVG. Zoom is preserved across re-renders.
-
----
-
-## Theme ↔ dark mode sync
+The hash codec is:
 
-```
-applyColorMode(dark)
-  → sets :root.light / removes it (editor UI)
-  → if diagramThemeIsAuto: sets state.theme = 'zinc-dark' or ''
-  → refreshAllColorUIs()
-  → scheduleRender(0)
+```text
+deflate:<base64url(deflate-raw(UTF-8(JSON(state))))>
 ```
 
-`diagramThemeIsAuto = false` once the user manually picks a theme from the dropdown — their choice is then preserved across dark/light toggles.
+Use `editor/js/sharing.js` as the browser source of truth. For Node/build-time links, import `editorStateHref()` or `hostedEditorStateHref()` from `scripts/site/editor-state-url.ts`. Never hand-roll base64, compression, field names, or `/editor/` URL assembly in another producer.
 
----
+Keep these behaviors:
 
-## CSS variable system (diagram SVG)
+- Reject unknown fields such as the removed `theme` alias.
+- Bound encoded and decoded bytes.
+- Fail closed on corrupt, unsupported, or oversized hashes.
+- Do not restore a draft, query example, or plausible default after hash decode failure.
+- Use `?example=<id>` only for canonical editor examples; use a state hash for source/config/style snapshots.
+- Update the hash only after a current render verifies successfully.
 
-The renderer injects a `<style>` block into every SVG with derived vars:
-
-```
---bg, --fg  →  user-provided or defaults
---line, --accent, --muted, --surface, --border  →  optional overrides
---_line, --_arrow, --_node-fill, --_node-stroke  →  internal derived (color-mix)
-```
+When changing this contract, update the browser codec, build-time codec, every producer, checked-in deep links, and both unit and real-navigation tests in the same change.
 
-Config overrides work by setting `--bg`, `--fg` etc. on the SVG's inline `style` attribute via `svgOpenTag()`. Theme colors are the base; config values override them in `buildOptions()`.
+## Configuration controls
 
----
+For an existing render option:
 
-## URL sharing
+1. Add accessible controls in `editor/html/left-panel.html` or the relevant partial.
+2. Store UI state in `editor/js/config-panel.js`.
+3. Include the value in `readConfig()` and restore it in `hydrateConfigControls()`.
+4. Keep `state.config` serializable and admitted by the shared render-options schema.
+5. Render through `buildOptions()`; do not patch the preview into a state the renderer cannot reproduce.
 
-Source + theme are encoded in the URL hash:
+For new public options, update the library contract first, then the editor. Do not create an editor-only alias.
 
-```js
-// Encode
-btoa(unescape(encodeURIComponent(JSON.stringify({ source, theme }))))
+## Examples
 
-// Decode
-JSON.parse(decodeURIComponent(escape(atob(hash))))
-```
+Add or edit examples in `editor/examples.ts`. Preserve stable IDs because `/editor/?example=<id>`, the sidebar, website examples, and tests depend on them. Examples may supply source and admitted config; loading one must preserve the user-selected Palette unless the URL snapshot explicitly carries a palette.
 
-`updateHash()` is called after every successful render and on Copy URL.
+## Export behavior
 
----
+Keep SVG, PNG, ASCII, and Unicode exports derived from current receipt-bearing artifacts. Preserve strict SVG verification and self-hosted font handling. PNG scale changes output dimensions; it must not change diagram semantics or silently fall back after an error.
 
-## Export formats
+## Regression gates
 
-| Action | Implementation |
-|--------|----------------|
-| Save PNG | SVG → `<img>` → `<canvas>` → `toBlob('image/png')` → download |
-| Save SVG | `XMLSerializer.serializeToString(svgEl)` → Blob → download |
-| Copy Image | Same as PNG but `navigator.clipboard.write([new ClipboardItem(...)])` |
-| Copy URL | `updateHash()` then `navigator.clipboard.writeText(location.href)` |
+Use these tests when touching editor links or state:
 
-Scale (1x/2x/4x) multiplies canvas dimensions for PNG export.
+```bash
+bun test src/__tests__/editor-link-contract.test.ts
+bun test src/__tests__/editor-security-closures.test.ts
+bun test src/__tests__/website-build.test.ts
+AM_BROWSER_TESTS=1 bun test src/__tests__/website-browser-a11y.test.ts --timeout 600000
+```
 
----
+The repository-wide link contract must decode every checked-in hosted editor deep link. The website build contract must decode every generated HTML/JSON editor-state link and reject legacy hashes or unknown fields. The browser test must navigate from a real public page into the editor and verify that initialization preserves the hash and source.
 
 ## Common pitfalls
 
-- **Never edit `editor.html` directly** — it's overwritten on every build
-- **Avoid `\'` inside template literals** — use DOM API (`createElement`, `.textContent`) instead of `innerHTML` with quotes
-- **Stroke overrides via CSS injection must re-run after every render** — the SVG is replaced in `doRender()`
-- **`transform: scale()` breaks scrolling** — always use explicit `width`/`height` for zoom
-- **Font option is the bare name** (`Inter`, not `"Inter", sans-serif`) — the renderer wraps it internally
+- Updating a decoder without migrating every producer.
+- Updating unit fixtures to the new codec while leaving public links untouched.
+- Reintroducing `theme` where the editor state contract requires `palette`.
+- Testing the editor only with hashes manufactured inside the editor test suite.
+- Editing generated outputs instead of modular sources.
+- Letting dark/light chrome mutate diagram appearance.
+- Restoring drafts after a broken share URL, which can make unrelated local content look shared.
+- Enabling copy/export from a stale or unverified preview.