agentic-mermaid 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,18 +4,163 @@ This changelog tracks user-facing changes for **Agentic Mermaid**, a fork of `lu
 
 ## Unreleased
 
-_No changes yet._
+## 0.1.2 — 2026-07-21
+
+### Fixed
+- Updated the transitive `brace-expansion` development dependency to 5.0.7 so the high-severity dependency audit remains enforced without blocking CI on GHSA-3jxr-9vmj-r5cp. The override stays within `minimatch`'s declared compatible range and is exercised by the retained Stryker mutation lane.
+- Completed the 0.1.2 version projection across package, hosted MCP registry, generated agent guidance, and compatibility tests; host-version assertions now derive from the package authority instead of embedding the previous release.
+- Made installed-resource verification portable to Windows by applying `/proc/self/fd` and `/dev/fd` canonicalization only on Linux and macOS; other platforms retain the rooted post-open file-identity proof instead of probing a nonexistent `/dev/fd` path.
+- Made the editor/website generator's local file URL conversion portable to Windows by using `fileURLToPath` instead of passing `/D:/...` URL pathnames to `Bun.build`.
+
+### Changed
+- Simplified the published package to compiled ESM entries and removed the internal `./capabilities` and `./resources` subpaths. The supported library entries are `agentic-mermaid`, `agentic-mermaid/agent`, and the browser/workerd-safe `agentic-mermaid/agent/core`.
+- Consolidated mutation testing behind `bun run mutation-test -- <profile>`, projected editor and comparison examples from the family descriptor registry, and made website/Worker generated assets clean-build outputs instead of tracked source. Older entries below retain the command spellings that shipped at the time; use `bun run mutation-test -- routes` or `bun run mutation-test -- gantt` now.
+
+### Added
+- Implemented Section A of the rendering-contract
+  program: one immutable request and appearance waist, descriptor-owned
+  family/style/render-option discovery, typed connector terminals and backend
+  claims, explicit product/output parity, a version-pinned Mermaid compatibility
+  manifest, and versioned extension and resource contracts.
+- Completed the family-elevation program across all registered families: typed mutation operations, deterministic family layout rubrics/certificates, expanded semantic facts, exhaustive configuration wire-or-warn coverage, parser/serializer conformance, and a zero-exception citizenship matrix.
+- Added Flowchart v11 shape metadata and edge IDs; State notes/pseudostates/history/concurrency/paint; Sequence box/autonumber/create/destroy/standalone activation behavior; Class namespaces/generics/paint/cardinality allocation; ER bare entities/paint/ordered segments; vertical Timeline layout; Gantt dependency/critical-path overlays; XYChart legends and explicit orientation mutation; Pie wedge labels/donut/legend controls; Quadrant accessibility/style functions; deterministic side-constrained Architecture routing and offline icons; and first-class Mindmap and GitGraph families.
+- Added measured bold/italic Flowchart markdown rendering and support for a bare `flowchart` header, which defaults to top-down layout while remaining source-preserved at the typed-edit boundary.
+- Added a mechanically checked family-elevation ledger: all 72 original items and 18 completion packages have stable IDs, constrained statuses, ordinal work-plan correspondence, and named evidence. B01–B18 are done; final-head CI and post-fix review evidence is retained in the stable PR audit record.
+- Completed the Phase 0 honesty contract with generated serializer→agent/renderer-parser properties for every family, registry-complete lossless opaque diagnostics, and a typed `StateRuntimeConfig` that wires ten faithful fields while warning on legacy, invalid, unknown, or unavailable-renderer requests.
+- Added hard terminal-cell `targetWidth` rendering across library, CLI (`--target-width`), Code Mode, and hosted `render_ascii`, with typed `AsciiWidthError` diagnostics when geometry cannot fit.
+- Published one all-family SVG contract: deterministic `data-id`/`data-role`, normalized relation endpoints and ARIA semantics, complete local-reference namespacing, and typed Scene identity/accessibility records.
+- Added full Mindmap and GitGraph citizenship across library, CLI, Code Mode, local/hosted MCP, editor, website, docs, eval, packaging, and terminal rendering. Compatibility is pinned to Mermaid commit `f3dea58385fd5c7dd1f4e9c9c1876751ae6943cc`; all 26 Mindmap and 69 GitGraph official spec blocks are now imported, excluded, or explicitly classified in an executable revision/hash-bound oracle; generated GitGraph ids are deterministic `c<N>` values.
+- Added first-class Mermaid `radar-beta` charts across SVG/PNG/ASCII/Unicode, typed mutation, Code Mode/MCP, config diagnostics, styles, docs, website samples, and executable upstream provenance. Radar supports positional/keyed curves, circle/polygon graticules, accessibility metadata, same-line whitespace statements, palette-aware areas, deterministic semantic identities, and bounded geometry configuration.
+- Added focused Mindmap/GitGraph mutation lanes and exhaustive operation contracts. The latest 2026-07-10 local runs killed 400/405 Mindmap mutants (98.77%) and 294/303 GitGraph mutants (97.03%); the lanes are opt-in diagnostics without break floors or acceptance authority.
+- Added official Mermaid 11.16.0 comparison fixtures and reproducible SVG/terminal contact sheets for Mindmap and GitGraph. The evidence records AlexanderGrooff/mermaid-ascii 1.4.0's exact unsupported-family result instead of fabricating equivalent output.
+- Added exact executable-title evidence for every done family-elevation ledger row; CI now rejects uncited files, missing titles, duplicate IDs, empty evidence, and newly-done rows without a matching evidence entry.
+- Added a pinned official Mermaid 11.16 documentation showcase for all registered families and a registry-derived exhaustive non-default Look × Palette × family compatibility gate.
+- Completed the mandatory Section B public styling surface: descriptor-derived exact role records, named semantic slots, executable V1 `category` bindings, visible non-color cues, and inspect-only contrast/accent-area/mono-role constraints across SVG, PNG, and declared lossy terminal projections. Authored Mermaid paint and family semantics remain authoritative, and evidence-gated B4 BrandPack packaging remains unpromoted.
+- Added `renderMermaidWithActions()` with one inert, versioned action/region sidecar across SVG, PNG, ASCII, and Unicode; exact authored source spans; family-semantic rendered regions; and expanded deterministic spacing, density, overlap, and resolved-contrast metrics across all registered families.
+- Promoted the Cupertino-, Vercel-, and Cloudflare Workers-inspired research fixtures to the highest non-built-in evidence form: schema-validated public `StyleSpec` prototypes with executable family-specific fixtures, deterministic screenshots, role styles, inspect-only constraints, and semantic bindings/cues where the family exposes them. They remain documentation-only, unendorsed, and absent from built-in discovery.
+
+### Changed
+- Canonical serialization, terminal metadata, extension discovery, capability reports, quality tie-breaking, and evaluation artifacts now use locale-independent Unicode code-point ordering instead of ambient host collation.
+- Semantic binding admission now derives its explicit role union from roles with executable category consumers. Permanently inert targets such as `role: "node"` are rejected consistently by TypeScript, runtime validation, JSON Schema, generated SDK declarations, and final stack resolution.
+- Exact role properties, binding-family enrollment, public role types, runtime descriptors, schema, and docs now project from one role-style contract. Brand-constraint payloads likewise project from one descriptor record into TypeScript, runtime admission, JSON Schema, diagnostics, and an exhaustive evaluator map.
+- Terminal flowchart/state RL output now reverses the logical grid before text drawing instead of aliasing LR, and feedback edges can no longer enter primary fan-in/fan-out bundles and overwrite node labels in a three-node 2-cycle.
+- Every continuous painted text advance—including bundled, monospace, and custom faces—now receives a deterministic SVG `textLength`/`spacingAndGlyphs` projection matching the width reserved by layout across SVG and native/browser PNG. Independently positioned multiline tspans are fitted per line, nested formatting contributes inherited metrics, and explicit emitter-owned `textLength` remains authoritative.
+- Section B causal evidence now pins and executes the pre-feature commit instead of following moving `origin/main`; its receipt also hashes default, rough, and hybrid SVG+PNG sentinel probes across every registered family and links the separately approved brand-inspired prototypes.
+- Retired and deleted the broad scheduled mutation matrix and its sharding/oracle machinery after 26 consecutive failed or cancelled runs. The bounded incremental counter gate and five behavior-specific sabotage probes remain automatic; family lanes are opt-in diagnostics without acceptance floors.
+- Removed the accidental `cupertino` built-in registration and its private-face evidence path. Cupertino now exists only as an explicitly loaded, documentation-only public `StyleSpec` prototype; no compatibility alias is retained.
+- CLI, Code Mode, local/hosted MCP, editor, website, SVG, PNG, ASCII, and
+  Unicode now project shared options and capabilities from canonical
+  descriptors. Historical execution plans moved to the archive, copied family
+  and style menus were removed, and Section B branding work has one live owner.
+- Connector terminal evidence now preserves exact endpoints, routed contours,
+  hit geometry, stroke fields, label visuals, marker descriptors, and every
+  per-subpath marker placement behind an executable per-feature manifest.
+- Local MCP `render_png` now advertises managed-file side effects accurately, accepts `fontDirs`/`loadSystemFonts`, and returns deterministic configuration and font-coverage warnings in every output mode.
+- Agent evaluations, shipped-artifact fuzzing, website comparisons, fork documentation, and browser counts now cover every registered family; deployment catalogs carry the exact Git SHA and build time.
+- Configuration diagnostics now use fully qualified family paths consistently across source wrappers and explicit `mermaidConfig`; duplicate warnings are deterministically ordered and deduplicated.
+- Gantt calendar spans use the documented `(start, end]` exclusion boundary model and excluded-day shading is enabled by default; today markers remain caller-clocked.
+- Known command-inapplicable CLI flags and value-taking flags without values now exit 2 instead of being accepted as silent no-ops.
+- PNG coverage warnings now flow through local and hosted MCP renders; system-font mode reports qualified bundled-font uncertainty rather than suppressing it.
+- State `nodeSpacing`, `rankSpacing`, node padding/radius/font size, composite-title size, fork dimensions, note margin, and divider margin now affect rendering. Legacy or invalid `state.*` values and unsupported renderer selections emit qualified `INEFFECTIVE_CONFIG` diagnostics through source verification, library/Code Mode callbacks, CLI SVG/PNG envelopes, and hosted SVG/ASCII/PNG tools.
+- Built-in concrete palettes now normalize normal text to WCAG AA (4.5:1) and meaningful relation lines/markers to 3:1; already-compliant colors and unresolved CSS-variable palettes remain unchanged.
+- Mindmap now accepts official multiline Markdown Strings, renders bold/italic spans, recognizes `layout: tidy-tree`, and fails closed on malformed reserved decorations, accessibility directives, and shape delimiters. Its bilateral layout now sizes depth columns per side and colors first-level subtrees accessibly. GitGraph now renders frontmatter titles, stabilizes equal-order lanes by source order, validates cherry-picks against full ancestry, and packs 45° commit labels/tags from measured bounds with contrast-preserving backplates and stronger branch rails.
+- Editor supported-family diagnostics, characterization enrollment, and architecture documentation now derive from or are checked exactly against the runtime family registry.
+- Architecture edges now use deterministic side-constrained placement and orthogonal visibility-grid routing with explicit placement/facing/obstacle certificates. State, Class, ER, and Architecture terminal output is spatial and display-cell aware; Class compact namespaces and ER ordered typed/opaque segments remain editable without stale identity references.
+- **Output compatibility note:** semantic SVG identity/ARIA attributes, palette contrast normalization, corrected marker/routing geometry, and spatial terminal rendering intentionally change SVG/PNG/ASCII bytes and regenerated characterization hashes. Consumers that snapshot output bytes should review and re-pin; source parsing and deterministic repeatability remain stable.
+
+### Removed
+- Removed five stale, unreferenced website SVG snapshots and one obsolete terminal snapshot that were copied into the public deployment despite no page consuming them. The authored `.mmd` sources remain, `workflow-themeable.svg` remains generated from the current renderer, and a build contract now rejects checked-in renderer snapshots in `website/source/diagrams`.
+
+### Fixed
+- Prevented ASCII/Unicode action and label regions from absorbing matching text from neighboring nodes or edge labels, and from binding punctuation-only labels to box borders; multiline hit bounds now compare and claim display cells rather than UTF-16 offsets.
+- Preserved the exact Style, Palette, seed, and render configuration when opening every Examples, homepage, comparison, and warning reproducer in the Editor. Examples and the Editor now share one render-state resolver, and browser coverage checks every distinct handoff shape for complete SVG and appearance parity.
+- Restored public editor deep links after legacy hash decoding was removed. Website and checked-in links now share one bounded canonical deflate codec and current `palette` schema, with repository, generated-site, and real-browser navigation gates to catch producer/consumer drift before deployment.
+- Prevented the editor’s Style and Palette dropdowns from flashing during startup. Idempotent initialization closes no longer trigger the visible closing animation; real open-to-closed transitions retain it.
+- Corrected Class composition, aggregation, and lollipop marker anchors at both relationship ends in every layout direction. Diamond bodies now remain outside class surfaces and lollipops meet the boundary at their tangent in crisp and styled output.
+- Closed editor share/draft insertion, decompression, and share-hash DOM XSS risks; hardened imported render configuration and StyleSpec prototype/font/CSS boundaries; externalized executable scripts; and removed `unsafe-inline` from the production CSP. Editor and hosted SVG rendering now force strict security and reject active content or external references.
+- Closed unknown-family Flowchart fallthrough, connector-marker fidelity loss, and verified-resource time-of-check/time-of-use gaps. PNG/resource receipts now state whether bytes were verified, caller-supplied, system-provided, embedded, or unavailable.
+- Closed connector topology now has one path-only invariant across SVG,
+  sketch, bounds, hit testing, endpoint anchors, and terminal evidence. Marker
+  bounds honor SVG's default `markerUnits="strokeWidth"`, use typed marker
+  viewports for path geometry, and no longer diverge in rough/hybrid output.
+- Enforced JSON-RPC 2.0 envelopes and notification suppression across local and hosted MCP transports. Local bearer/Origin checks now cover SSE, messages, and artifacts, and SSE sessions have a fixed upper bound.
+- Rejected source-controlled Pie colors that could escape SVG attributes or styles; hardened cross-format color contrast and XML sinks.
+- Fixed successful-but-lossy Journey/State/Sequence/Class/ER/Architecture/Timeline/XYChart mutations and parser round trips, including accessibility metadata, history endpoints, boxed participants, labeled and generic classes, bare/aliased ER entities, post-alignment route anchors, event text containing clock-time colons, event-less Timeline periods, and explicit vertical orientation.
+- Typed paint and Mindmap decoration/metadata edits now reject line/comment delimiters that would serialize into new semantic statements; empty Mindmap icon decorations are rejected instead of being accepted and dropped; successful edits are grammar-closed and round-trip stable. The pinned GitGraph oracle also AST-expands constant-loop variants, and SVG identity tests compare exact node, group, and relation tuples rather than counts/endpoints alone.
+- Fixed quoted Flowchart shape labels containing their own delimiters, Unicode/CJK Flowchart identifiers, corrupt State/Class `:::class` text, ER `:::class` phantom identities, and comma-separated ER composite keys; ER display aliases now have typed `set_entity_label` mutation.
+- Fixed dense self-loop route/label collisions and reserved rank clearance so loop pills cannot cover adjacent nodes or primary-chain arrowheads; also fixed grapheme-splitting label wraps, terminal formatting leakage, ER relationship glyph fidelity, and State pseudostate visuals.
+- Finished grapheme/display-cell writes and measurements in Class, ER, Sequence blocks, Flowchart subgraphs, Pie, Quadrant, XYChart, validation, and TUI metadata; ER attribute comments are visible in terminal output.
+- Replaced Flowchart start-arrow reliance on `auto-start-reverse` with explicit pre-rotated geometry and balanced start/end cross-marker reference points, verified at raster pixels.
+- Fixed blank ER diagrams becoming opaque after ordered-segment promotion, preserving header-only ER as a structured typed-authoring canvas while keeping opaque-only tolerated subgraphs lossless.
+- Fixed label-less ER relations being silently dropped, XYChart `backgroundColor` being lost during PNG rasterization, and long Quadrant axis labels overprinting beyond their half-plot budgets.
+- Replaced delimiter-concatenated Mindmap/GitGraph Scene IDs with injective semantic identities, rejected already-reachable GitGraph cherry-picks, and aligned equal-order branch lanes across SVG and terminal renderers.
+- Closed the Radar audit gaps in public synthesis validation, upstream title/comment/options grammar, Style-face-aware measurement, independent frame dimensions, theme paint/typography propagation, styled-backend opacity, empty-curve ASCII output, tick geometry, and duplicate-ID stability.
+
+### Breaking
+- Removed the deprecated compatibility layer across library, agent, CLI, MCP,
+  editor, Style, Scene, and SVG surfaces. Library callers must use
+  `renderMermaidSVG` / `renderMermaidSVGAsync`, `renderMermaidASCII`, and
+  `parseRegisteredMermaid`; `AsciiWidthError.requestedWidth` replaces
+  `targetWidth`. The browser PNG raster callback no longer receives `scale`.
+  Agent callers must use `FlowchartMutationOp`, required Sequence statements,
+  and canonical message endpoint data instead of the removed mutation/type
+  aliases and projections.
+- CLI and MCP inputs now accept canonical spellings and nesting only: use
+  `am render --format ascii`, batch `format: "ascii"`, layout
+  `--format layout`, and `agentic-mermaid-mcp --transport http`. MCP render
+  appearance belongs under canonical nested options; hosted SVG uses
+  `palette`, not `theme`. Removed and unknown MCP flags now fail closed instead
+  of silently starting stdio.
+- Style discovery no longer exposes `THEMES`, compatibility-alias registration,
+  `default`, bare `tufte`, or dormant Style aliases. Use `crisp` and the
+  canonical-only `look:tufte`. Editor share links are deflate-only, accept
+  `palette` only, and drafts persist in `sessionStorage` for the current tab;
+  old plain-base64 links and persistent draft controls are not migrated.
+- Scene contract v2 removes public crisp/raw/prelude serialization carriers and
+  duplicate connector geometry/paint/marker fields. Connector marks and private
+  serialization sidecars are the sole authorities. External Scene families and
+  backends must declare `identity.compatibility.scene: "^2.0.0"`; v1 ranges are
+  rejected before callbacks run. The render receipt, Scene validation, family
+  descriptor, family conformance, and backend conformance generations were
+  advanced with the incompatible schemas.
+- Default SVG rendering no longer embeds font imports, an explicit empty
+  `idPrefix` is invalid, registered ASCII routing requires `routeClass`, opaque
+  State bodies use the canonical layout result, and unknown render failures use
+  one generic diagnostic instead of transport-specific fallbacks. Consumers
+  relying on historical SVG byte order, legacy ARIA/data-entity projections, or
+  built-in Scene object identity must migrate to the typed canonical contracts.
+- The duplicate light Tufte palette (`palette:tufte` and legacy theme `tufte`) and the ambiguous bare `tufte` Style input are removed and now fail as unknown. Use the sole light Tufte resource, `look:tufte`; the distinct `tufte-dark` palette is unchanged.
+- Consumers matching `INEFFECTIVE_CONFIG.field` for family-section keys must use the qualified path (for example `journey.boxMargin` rather than `boxMargin`).
+- Gantt exclusion-boundary semantics and default shading may change existing rendered calendars; CLI scripts relying on ignored known flags now fail fast with exit 2.
+- The transitional `FamilyPlugin` type alias has been removed; extension hosts should import `FamilyDescriptor`, which is the canonical registration and discovery contract.
+- Extension registration is now collision-safe and versioned. External families
+  use `family:*` identities and complete descriptors; external Scene backends
+  use `backend:*` identities, declare feature/operation capability evidence,
+  and pass executable conformance at registration instead of silently replacing
+  a prior implementation.
+- Declarative `StyleSpec.backend` has been removed. Style data now selects only safe appearance; trusted hosts that install executable Scene backends select them through `createMermaidRenderer`, `createMermaidPNGRenderer`, or `createMermaidBrowserPNGRenderer` with a host-only `backendPolicy`.
+- External Scene v1 path connectors now accept only one linear `M`/`L`/`Z`
+  contour whose vertices exactly match typed points; use polyline or await a
+  future curve-flattening contract instead of supplying divergent SVG and hit
+  geometry. The serializer-only `MarkerSerializationOptions.markerUnits`
+  override was removed; set units on the marker descriptor, the sole authority.
+
+## 0.1.1 — 2026-07-10
+
+### Added
+- **Standards-based agent discovery and MCP Registry publishing.** Agent guidance now states when to use Agentic Mermaid and when to keep diagrams local. The website publishes `/index.md`, negotiates it from `/` with `Vary: Accept`, and advertises machine-readable resources with RFC 8288 links. The npm package ships official `server.json` metadata, exposes the registry launch path as `npx -y agentic-mermaid mcp`, and publishes each new release to the MCP Registry after npm succeeds.
 
 ## 0.1.0 — 2026-07-09
 
 ### Added
+- **Journey and output-family foundation.** Journey gained deterministic geometry/paint and accessibility-aware rendering; ASCII/Unicode output became a first-class cross-family surface; PNG switched to bundled Inter metrics with DejaVu per-glyph fallback and introduced the public warning vocabulary used by verification/render tooling.
 - **Validated declarative edit boundary + `mutate`/`build` hosted MCP tools.** The untyped MCP/CLI JSON boundary now shape-validates every op before the mutator (field presence, primitive type, enum membership across all 12 families), so a malformed op — e.g. `add_class {name:'Duck'}` where `id` is expected — returns a prescriptive `INVALID_OP` naming the offending field and listing the valid ones, instead of silently producing `class undefined`. One choke point (`mutateChecked`) backs every untyped path: the new hosted `mutate` (edit a `source`) and `build` (author from a `family`) tools, the Code Mode facade, and the CLI `--op`/`--ops`. All return one canonical envelope `{ ok, family, source, verify }`. Code Mode `execute` now also marshals a returned diagram (or `Result` wrapping one) to that same envelope rather than failing "non-serializable"; other unserializable returns get a prescriptive plain-data hint.
 - **Blank-slate authoring on the typed path: `createMermaid(kind)` / `buildMermaid(kind, ops)`** (from direct agent feedback). `createMermaid` returns an empty structured `ValidDiagram` for any built-in family (overloads narrow the return per kind; `direction` option for flowchart/state); `buildMermaid` folds a typed mutation list over that empty diagram, with errors carrying the failing op's `opIndex`. Exposed in the library (`agentic-mermaid/agent`), the Code Mode `mermaid.*` SDK (results are trusted inputs to `mutate`/`verify`/`serialize`), and the SDK declaration. Creating a new diagram no longer requires hand-writing Mermaid source. To let empty diagrams be built up op by op, the journey/xychart "structured floor" now refuses only mutations that would *empty a non-empty* body, and the ER serializer emits label-less relations as `: ""` so they re-parse structured instead of falling back to opaque.
 - **Repo-wide fast-check seed policy**: every property suite now runs at one pinned global seed via a `bun test` preload (`src/__tests__/fc-seed.preload.ts`; `AM_FC_SEED=<int>` reproduces a specific roll, `AM_FC_SEED=random` restores finder-mode randomness). Suite-scoped seed overrides save/restore the global config instead of resetting it, and two meta-gates keep the policy from silently un-landing (a preload-wiring test plus an end-of-alphabet epilogue). Landed after a 1,368-run sweep (48/24/12 seeds per suite, scaled by runtime) found zero latent seed-dependent failures. Completes the determinism policy from the 2026-07 audit, which had been applied incident-by-incident to three suites (see `docs/testing-strategy.md` §4).
 - **Label-collision detection and gating (`eval/overlap-audit/`)**: an SVG-level overlap auditor (text boxes measured with the renderer's own text metrics, ownership from SVG group metadata or containment, rotation-aware, off-canvas detection) with a curated-corpus gate, deterministic 12-family fuzz generators, and a CI gate (`label-overlap-gate.test.ts`) holding the corpus at zero findings with per-family fuzz ratchets. Labels were previously unmeasured in every family.
 - **Certificate completeness is now a deterministic gate**: `certificate-completeness.test.ts` pins that every edge leaves the pipeline certified (tracked corpus + shrunk repros + fixed-seed duplicate-edge sweep), and the route-contracts property suite runs at a pinned fast-check seed instead of flaking ~1 CI run in 7.
 - **Scoped mutation lane for the link-rank packing repair** (`stryker.linkrank.config.json`), harvested from 49.86% to 65.07% via geometry-characterization snapshots; residual classified in `docs/mutation-testing.md`.
-- **Hosted MCP on Cloudflare** (`https://agentic-mermaid.dev/mcp`): the website Worker now serves a stateless Streamable HTTP MCP endpoint (JSON-RPC over POST, no sessions/SSE) with six tools — `execute`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`. Code Mode `execute` runs agent JavaScript in per-code Dynamic Worker isolates (Worker Loader binding; `globalOutbound: null`, empty env, `cpuMs` budget, `subRequests: 0`) against the same hardened `mermaid.*` facade as the local vm sandbox — semantics pinned by a differential test suite (`hosted-execute-differential.test.ts`), with two documented divergences (CPU-time vs wall-clock budgets; strict-module vs sloppy-vm implicit globals). Hosted `render_png` uses `@resvg/resvg-wasm` (pinned to the napi version) with the bundled DejaVu fonts and is documented as outside the byte-determinism contract. Deterministic `tools/call` responses are edge-cached (Cache API keyed on a hash of the canonicalized call), request bodies cap at 128KB and tool inputs at 64KB, and sync-only violations are rejected before any isolate spins. Transport guards: reflective CORS with Origin validation, `MCP-Protocol-Version` validation, and a batch fan-out cap. The `mermaid.*` Code Mode facade moved to runtime-neutral modules (`src/mcp/facade.ts`, `src/mcp/harness-runtime.ts`; `src/agent/core.ts` is the pure barrel without the napi PNG dependency) shared by the vm sandbox, the isolate harness, and the hosted server core (`src/mcp/hosted-server.ts`). The local stdio/HTTP MCP server is unchanged. Also fixes ELK instantiation under Cloudflare workerd (`src/elk-instance.ts` now flips elk-worker's environment sniff by temporarily defining `document` instead of deleting the undeletable `self`).
+- **Hosted MCP on Cloudflare** (`https://agentic-mermaid.dev/mcp`): the website Worker now serves a stateless Streamable HTTP MCP endpoint (JSON-RPC over POST, no sessions/SSE) with six tools — `execute`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`. Code Mode `execute` runs agent JavaScript in content-addressed Dynamic Worker isolates (Worker Loader binding; `globalOutbound: null`, empty env, `cpuMs` budget, `subRequests: 0`) against the same hardened `mermaid.*` facade as the local vm sandbox — semantics pinned by a differential test suite (`hosted-execute-differential.test.ts`), with two documented divergences (CPU-time vs wall-clock budgets; strict-module vs sloppy-vm implicit globals). Hosted `render_png` uses `@resvg/resvg-wasm` (pinned to the napi version) with the bundled DejaVu fonts and is documented as outside the byte-determinism contract. Eligible deterministic pure-tool results may be reused through a private Workers Cache API compute cache; JSON-RPC responses remain `cache-control: no-store`, and non-idempotent `execute` bypasses the cache. Request bodies cap at 128KB and tool inputs at 64KB, and sync-only violations are rejected before any isolate spins. Transport guards: reflective CORS with Origin validation, `MCP-Protocol-Version` validation, and a batch fan-out cap. The `mermaid.*` Code Mode facade moved to runtime-neutral modules (`src/mcp/facade.ts`, `src/mcp/harness-runtime.ts`; `src/agent/core.ts` is the pure barrel without the napi PNG dependency) shared by the vm sandbox, the isolate harness, and the hosted server core (`src/mcp/hosted-server.ts`). The local stdio/HTTP MCP server is unchanged. Also fixes ELK instantiation under Cloudflare workerd (`src/elk-instance.ts` now flips elk-worker's environment sniff by temporarily defining `document` instead of deleting the undeletable `self`).
 - **Layout-certificate closure for #26/#38**: `layoutMermaid(d, { debug: true })` and `am render --format json --certificates` now expose opt-in graph route certificates plus accepted family certificates for class/ER (`orthogonal-box`), architecture (`side-anchored`), sequence (`lifeline-message`/`self-message` with real self-loop geometry), and timeline/xychart/pie/quadrant/Gantt containment layouts. Default layout JSON remains certificate-free. Route certificates now include exact ports plus additive side/slot/role assignments, and ELK `FIXED_SIDE` hints are fed only for safe primary-forward edges whose endpoints are not incident to non-primary routes or direction-override subgraphs.
 - **Agent analysis and region/action sidecars**: `analyzeMermaid` / `analyzeMermaidSource` expose deterministic feedback-edge facts, source-only action records (unsafe `javascript:`/`data:`/`vbscript:` links marked unsafe, never executed), and Gantt critical-path/slack summaries. Debug layout JSON can include V1 `regions` and source-only `actions` sidecars for UI/tooling alignment; label regions now bound the label around its center rather than treating the center as a top-left corner.
 - **Port ranking** (issue #26 WS3, completing the yFiles cost model): a shape side carrying exactly one line uses its canonical port — for diamonds, the exact vertex; when no straight vertex lane exists, a single proof-gated Z from the vertex into the target's port outranks a straight lane floating on the facet (lines emit from points, upgraded back to straight by the fixed-point loop when obstacles move). Sides carrying several lines spread along the facet/flat region; fan-ins still merge at the target port; sharper shapes win conflicts and the source wins ties. Verified across all four directions, bi-directional pairs, and diamond-to-diamond chains by tests and the rubric battery. An unlabeled reciprocal pair (A→B with B→A) renders as **two equal parallel lines** straddling the shared centerline at `center ± 6` (primary low, feedback high) — equal deviation gives equal lengths on diamond facets, the way dot offsets reciprocal splines symmetrically about the spine; both pair members enroll in the fixed-point repair pool even when already straight, and any straightening that won on a non-preferred lane (an *upgradeable* success) is re-proved each round so the symmetric lane wins once the partner's geometry settles. Port-only shapes (circles) keep both lines on the exact port. A blocked vertex emit now prefers a **1-bend hook** into the target's *facing* cross-side port (the box's top/bottom in horizontal flow — the IBM flowcharting-manual entry) over the 2-bend Z into the flow-side port; an available fan-in merge at the flow-side port (shared arrowhead) outranks the hook, and a stub shorter than 8px keeps the Z. **Port-lane alignment** (`alignPortLanes`): a "straight but off both midpoints" edge — floating through the sliver where two side-spans overlap because ELK's balanced placement aligned the node with neither neighbor — is now fixed at the placement stage: one endpoint node slides along the cross axis so the two midpoint ports share a lane (port-aware coordinate assignment, Rüegg et al. GD'15), making the edge straight AND port-exact with no routing trade. Slides are proof-gated (shared lane clear of intermediate nodes; sibling edges bent with a perpendicular segment to absorb the shift, labels following translated runs; no node/corridor/label-pill collisions; no group members; aligned endpoints frozen against later re-breaking). The pass covers the whole PORT_EXACT shape catalog — circles, stadiums, hexagons, cylinders, pseudostates, and diamonds slide too (for port-only shapes this converts a forced 2-bend Z into a port-to-port straight; a source diamond with a fan-out never aligns, its vertex has capacity 1; stretched perpendicular segments are proved node-free across their swept corridor) — and an explained detour whose entry lands off-port now seeks a port-exact Z, so the edge left behind by an alignment still converges at the shared entry port. Docs-corpus effect: straight edges 97→101, multi-bend routes 7→5, port-exact endpoints 76.0%→78.2%. **Active fan-in centering**: an unlabeled equal-rank peer fan-in (≥2 distinct unlabeled forward sources stacked in one layer) now snaps the hub to the exact cross-axis barycenter of its sources — correcting ELK's ~20px Brandes–Köpf placement drift — so the incoming edges converge **mirror-symmetric** at the hub's single exact port instead of the old one-straight/one-Z asymmetry. Proof-gated (no node/corridor/label-pill collision; hub not in a group, not also emitting a forward edge; ELK-gridded large fan-ins correctly out of scope). Exact symmetry (0.00px barycenter error, ≤1.5px clipping floor on curved shapes) with zero hard-metric regressions; the trade is +2 bends per fan-in. The L–V contact-sheet scenarios now demonstrate the symmetric merge across every shape. **Diamond facet-mid ports (the 8-port model)**: diamonds gain four extra designated ports at their facet midpoints (NE/SE/SW/NW, all on the outline; `diamondFacetPorts`, recognized by `portAt`, certificates widen to `AnyPort`). Three uses: a diamond fan-out of two forward edges attaches them at the NE/SE facet-mids and slides the targets onto those lanes for **port-to-port straight** edges (E; the vertical case F correctly bails when the targets are too wide to align); a diamond↔diamond reciprocal pair attaches at the nearest facing facet-mids — two parallel lines *between* the diamonds, never through them (G); and a side input below a diamond whose facing port is claimed enters the **S vertex** instead of floating on the facet (K). `shapePorts` stays four-cardinal for every shape and `portAt` is byte-identical for non-diamonds, so this is strictly additive. Heuristic tracker (`bun run track`): 6 improvements, 0 regressions, 0 hard violations across 51 examples. The canonical scenarios are pinned as a **contact sheet** (`bun run contact:sheet` renders lettered scenarios A–S from `eval/visual-rubric/scenarios.ts`; `contact-sheet.test.ts` snapshot-pins each scenario's geometry and asserts zero hard rubric metrics, making the sheet a CI visual-regression gate, now A–V). **Parallelogram shapes** `[/text/]` and `[\text\]` (Mermaid lean_right/lean_left — the ISO 5807 input/output symbol) now parse, render, serialize, and round-trip correctly (previously misparsed as trapezoid/rectangle), and the whole slanted family — parallelograms, trapezoids, the asymmetric flag — joined the PORT_EXACT catalog: exact ports at the true side midpoints (slant midpoints / flag point), flat-side attachment spans, convex-polygon clipping, exact rubric outline oracles, randomized property coverage, and contact-sheet scenarios T–V. `verifyMermaid` gains the Tier-3 `DECISION_BRANCH_UNLABELED` lint (ISO 5807 10.3.1.2 / ANSI X3.5 4.10.2: every exit of a multi-exit decision shall be labeled with its condition value).
@@ -54,7 +199,7 @@ _No changes yet._
 - Style + Palette SVG styling via named looks, palette stacks, custom public JSON style records, and deterministic `seed` values.
 - Style + Palette showcase samples in the live examples surface.
 - Fork documentation describing differences from upstream in [`docs/fork-differences.md`](./docs/fork-differences.md).
-- Product/design context documents ([`docs/project/product.md`](./docs/project/product.md), [`docs/project/design.md`](./docs/project/design.md)) for future design-system aligned work.
+- Historical product/design context documents ([`docs/project/product.md`](https://github.com/adewale/agentic-mermaid/blob/8516976c679dccf758e68d47e7969c9b58ed3cb7/docs/project/product.md), [`docs/project/design.md`](https://github.com/adewale/agentic-mermaid/blob/8516976c679dccf758e68d47e7969c9b58ed3cb7/docs/project/design.md)) for future design-system aligned work.
 - Homepage sample search and category filters for browsing the full showcase.
 - Mobile editor pane switching for Code, Config, Preview, and Examples.
 - **Package-surface property fuzzing** (`src/__tests__/property-cli-surface-fuzz.test.ts`, `property-mcp-surface-fuzz.test.ts`): fast-check now drives the agent-facing package entry points that previously had only example-based coverage — the CLI argv parser (`parseArgs`, total-shape + verbatim-flag invariants), the `am batch` line handler (`runBatchLine`) and markdown-block renderer, and the MCP JSON-RPC router (`handleRequest`) plus the Code-Mode `execute` sandbox (`executeInSandbox`). The contract under test: a malformed request or hostile code yields a structured error / `{ok:false}` result, never an unhandled crash that would take down the stdio/HTTP server. These are crash-freedom/contract guards that would catch a future regression, complementing the engine-level parser fuzzing in `property-crash-freedom.test.ts`.
@@ -65,7 +210,7 @@ _No changes yet._
 - **0.1.0 release prep**: README, Getting started, and the generated website install card now make `npm install agentic-mermaid` the primary path; source-checkout instructions remain for repository development and pre-publish previews can still force source-install copy with `SITE_NPM_STATUS=source` or `SITE_NPM_PUBLISHED=0`.
 - **`LABEL_OVERFLOW` now measures the rendered label, not raw source chars** (from direct agent feedback: the cap counted `<br/>` tags and `&#160;` entities toward the 40-char limit, flagging legitimately-fine multi-line labels). The cap now applies to the longest *displayed* line — XML entities decode to one character, `<br>`/`\n` split lines, and formatting tags (`<b>`, `<i>`, …) are stripped — mirroring what the SVG renderer draws. `charCount` in the warning payload reports the rendered length. Applies to every family and to the opaque-body label extractors.
 - The local HTTP MCP startup line now names the plain-JSON `/rpc` endpoint alongside `/sse`, and `docs/mcp-http-transport.md` spells out which endpoints reply with SSE framing vs. plain `application/json` (from direct agent feedback: a script POSTing to the SSE session flow had to strip `data:` framing by hand).
-- The website MCP and security pages now carry an explicit privacy note: hosted tool calls send diagram source/code to the server and successful responses are edge-cached; local library/CLI/stdio need no network.
+- The website MCP and security pages now carry an explicit privacy note: hosted tool calls send diagram source/code to the server; eligible pure-tool results may be reused by a private server-side compute cache while HTTP responses remain `no-store`; local library/CLI/stdio need no network.
 - BUILD-20 now has a checked cross-family upstream parser/DB harvest under `eval/mermaid-upstream-suite-bench/` with a pinned Mermaid revision (`a2d9686451df7c4644a3eeca20535bbd4c5776b0`), repeatable `harvest:upstream` and `harvest:upstream:refresh-check` commands, exact structural assertions, BUILD-20 ownership on local compatibility exclusions, and a family-by-family manifest accounting for all 1,170 considered upstream parser/DB blocks: 658 imported source blocks, 512 documented exclusions, and 0 deferred blocks. The executable gate covers 648 cases including the existing 68-case Gantt companion bench, and `ratchet.json` fails CI if imported coverage drops or local-gap budgets grow.
 - **Breaking (unreleased agent surface, BUILD-19): flowchart ops no longer apply to state diagrams.** `asFlowchart` now returns `null` on a state diagram (its body kind is `'state'`, not `'flowchart'`); narrow with `asState` and use the state-shaped ops instead. The CLI `MUTATION_OPS_BY_FAMILY.state` list changed from the 6 flowchart ops to the 8 new state ops, and `mutateAny` narrows `asState` before `asFlowchart`. Every agent surface that said "state shares the flowchart body / narrow via asFlowchart" is updated to the new truth.
 - SVG appearance customization now uses Style + Palette render options; removed flat render style aliases are intentionally ignored.

package/LICENSES/Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -25,27 +25,27 @@ Use it when you want to describe a diagram in plain language and get back someth
 | An agent to draft the diagram | Mermaid source plus a verified render path |
 | Beautiful defaults | Built-in looks such as `watercolor`, `blueprint`, `hand-drawn`, and `publication-figure` |
 | Brand fit | Style + Palette stacks and custom JSON palettes you can keep in your repo |
-| Safe edits later | `parseMermaid` → family narrower → `mutate` → `verifyMermaid` → `serializeMermaid` |
+| Safe edits later | `parseRegisteredMermaid` → family narrower → `mutate` → `verifyMermaid` → `serializeMermaid` |
 | Reviewable artifacts | SVG, PNG, ASCII, Unicode, and JSON layout from the same source |
 
 The agent workflow is the guardrail behind the polish: agents should not guess from pixels, concatenate strings, or regenerate whole diagrams when a structured edit is available.
 
 ## Highlights
 
-- **12 diagram families** — flowchart, state, architecture, sequence, class, ER, timeline, journey, XY chart, pie, quadrant, and Gantt.
-- **SVG, PNG, ASCII, Unicode, JSON** — one deterministic layout foundation for docs, decks, terminals, and agent workflows.
+- **Descriptor-registered diagram families** — built-ins and namespaced extensions share one discovery and capability contract.
+- **SVG, PNG, ASCII, Unicode, JSON** — one resolved request with explicit graphical, terminal, and positioned-layout projections.
 - **Synchronous, zero-DOM SVG renderer** — no Puppeteer, no browser flash.
-- **Composable styles** — `{ style: ['hand-drawn', 'dracula'] }` stacks a look over a palette; 15 full looks cover sketch, watercolor, blueprint, accessibility, print, operational, physical-media, architecture, and editorial/report use cases. Custom styles are plain JSON records any agent can author (`docs/style-authoring.md`). `seed` re-rolls the ink, never the layout.
-- **21 built-in themes + Shiki compatibility** — a theme is a palette-only style: theme from two colors or a VS Code theme.
-- **Agent-native editing** — typed mutation for all twelve renderable families (flowchart/state, sequence, timeline, class, ER, journey, architecture, XY chart, pie, quadrant, Gantt); source-level round-trip only for opaque fallbacks (unmodeled syntax).
-- **CLI + MCP + library** — `am`, `agentic-mermaid-mcp`, `agentic-mermaid`, and `agentic-mermaid/agent`.
+- **Composable styles** — `{ style: ['hand-drawn', 'dracula'] }` stacks a look over a palette; discoverable full looks cover sketch, watercolor, blueprint, accessibility, print, operational, physical-media, architecture, and editorial/report use cases. Custom styles are plain JSON records any agent can author (`docs/style-authoring.md`). `seed` re-rolls the ink, never the layout.
+- **Discoverable palettes + Shiki compatibility** — a theme is a palette-only style: discover the canonical catalog at runtime, theme from two colors, or adapt a VS Code theme.
+- **Agent-native editing** — typed mutation for every registered renderable family; source-level round-trip only for opaque fallbacks containing unmodeled syntax.
+- **CLI + MCP + library** — `am`, `agentic-mermaid-mcp`, `agentic-mermaid`, `agentic-mermaid/agent`, and the browser/workerd-safe `agentic-mermaid/agent/core`. Audit reports and trusted host-resource helpers remain repository tooling instead of published runtime entry points.
 
 ## Installation
 
 ```bash
 npm install agentic-mermaid       # or: bun add agentic-mermaid / pnpm add agentic-mermaid
-am --help
-agentic-mermaid-mcp
+npx --no-install agentic-mermaid --help
+npx --no-install agentic-mermaid mcp
 ```
 
 For repository development, install from source and run the Bun entrypoints:
@@ -62,8 +62,10 @@ bun run bin/agentic-mermaid-mcp.ts   # MCP stdio server
 > **ESM-only.** `agentic-mermaid` ships ES modules (there is no CommonJS build);
 > `require()` consumers should use dynamic `import()` instead. Requires Node ≥ 18.
 >
-> The `am …` commands shown below assume the published bin. From a source
-> checkout, run them as `bun run bin/am.ts …` instead.
+> The `am …` examples below name the published bin. After a project-local npm
+> install, invoke it from a shell as `npx --no-install agentic-mermaid …` (or
+> from an npm script as `am …`). From a source checkout, use
+> `bun run bin/am.ts …` instead.
 
 ## Output quick starts
 
@@ -136,17 +138,17 @@ For multi-step MCP edits, connect `agentic-mermaid-mcp` and use Code Mode `execu
 
 Agentic Mermaid ships a Model Context Protocol server so MCP-capable agents can render and safely edit diagrams without shelling out.
 
-- **Self-hosted (default).** `agentic-mermaid-mcp` runs a stdio server exposing `execute` (Code Mode sandbox), `render_png`, and `describe`. Add `--transport http` for HTTP/SSE with managed PNG file/URL artifacts. See [`docs/mcp-http-transport.md`](./docs/mcp-http-transport.md) and [`docs/mcp-code-mode-rationale.md`](./docs/mcp-code-mode-rationale.md).
-- **Hosted.** A stateless Streamable HTTP endpoint is available at `https://agentic-mermaid.dev/mcp` (tools: `execute`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, `build`; 64 KB input caps). It is MCP JSON-RPC only, not a REST render API. Hosted `execute` runs the same `mermaid.*` facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.
+- **Self-hosted (default).** `agentic-mermaid-mcp` runs a stdio server exposing `execute` (Code Mode sandbox), `describe_sdk` (one family's mutation schema on demand), `render_png`, and `describe`. Package runners can use `npx -y agentic-mermaid mcp`; the `mcp` argument routes the package-name binary to the same stdio server. Add `--transport http` for HTTP/SSE with managed PNG file/URL artifacts. See [`docs/mcp-http-transport.md`](./docs/mcp-http-transport.md) and [`docs/mcp-code-mode-rationale.md`](./docs/mcp-code-mode-rationale.md).
+- **Hosted.** A stateless Streamable HTTP endpoint is available at `https://agentic-mermaid.dev/mcp` (tools: `execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, `build`; 64 KB input caps). Call `describe_sdk` for compact signatures or exact fields before authoring unfamiliar ops. It is MCP JSON-RPC only, not a REST render API. Hosted `execute` runs the same `mermaid.*` facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.
 
 Local-first is the default posture: prefer the library, CLI, or a self-hosted MCP for anything sensitive, offline, larger than the hosted caps, or needing local PNG file/URL artifacts. The hosted endpoint is a public, unauthenticated convenience for zero-install render/verify/describe and bounded structured edits.
 
 ## Structured edit example
 
 ```ts
-import { parseMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
 
-const parsed = parseMermaid('flowchart TD\n  API --> DB')
+const parsed = parseRegisteredMermaid('flowchart TD\n  API --> DB')
 if (!parsed.ok) throw new Error('parse failed')
 
 const flow = asFlowchart(parsed.value)
@@ -163,36 +165,27 @@ const source = serializeMermaid(next.value)
 
 Rules:
 
-- Use `asFlowchart` / `asState` / `asSequence` / `asTimeline` / `asClass` / `asEr` / `asJourney` / `asArchitecture` / `asXyChart` / `asPie` / `asQuadrant` / `asGantt` before mutating existing diagrams.
+- Use the matching exported `as<Family>` narrower before mutating an existing structured diagram.
 - Mutation ops use `kind`, not `type`.
 - Run `verifyMermaid` before every commit point.
 - Do not call `mutate` on opaque fallback bodies; the narrower returns `null` for unmodeled syntax.
 
 ## Supported diagram families
 
-| Family | Parse | Verify | Render | Structured mutate |
-|---|---:|---:|---:|---:|
-| Flowchart / state | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Sequence | ✓ | ✓ | SVG/PNG/ASCII | simple messages/participants |
-| Timeline | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Class | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| ER | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Journey | ✓ | ✓ | SVG/PNG/ASCII | modeled subset (BUILD-15) |
-| XY chart | ✓ | ✓ | SVG/PNG/ASCII | modeled subset (BUILD-16) |
-| Pie | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Quadrant | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Architecture | ✓ | ✓ | SVG/PNG/ASCII | modeled subset (BUILD-17) |
-| Gantt | ✓ | ✓ | SVG/PNG/ASCII | sections/tasks; calendar directives ride along verbatim |
-
-See [diagram families](./docs/diagram-families.md) for examples and compatibility notes.
+Family support and its executable evidence are projected from the
+`FamilyDescriptor` registry into the generated
+[Section A capability report](./docs/project/section-a-capability-report.md).
+See [diagram families](./docs/diagram-families.md) for syntax examples and
+compatibility notes.
 
 ## More documentation
 
-- [System architecture](./docs/design/system/README.md) — **start here** for how the engine works: the rendered three-stacks overview (dogfooded, drift-proof) routing to the design and route-contract docs.
+- [System architecture](./docs/design/system/README.md) — **start here** for the rendered resolved-request, family-descriptor, positioned-artifact, and output-security overview (dogfooded, drift-proof).
 - [API reference](./docs/api.md) — renderers, agent API, options, CLI/MCP pointers.
 - [Agent API cookbook](./docs/agent-api-cookbook.md) — practical recipes for agents.
 - [Theming](./docs/theming.md) — two-color themes, built-ins, Shiki compatibility.
 - [Custom style cookbook](./docs/custom-style-cookbook.md) — JSON style files, screenshots, schema usage, and CLI commands.
+- [Fonts in custom styles](./docs/custom-fonts.md) — font selection, SVG declarations, PNG directories, fallbacks, and browser usage.
 - [React integration](./docs/react.md) — zero-flash `useMemo` rendering.
 - [ASCII output](./docs/ascii.md) — terminal output, color modes, XY charts.
 - [Mermaid config](./docs/config.md) — frontmatter, init directives, runtime config.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+## Material Design Icons (curated Architecture icon paths)
+
+A size-bounded subset of SVG path data in `src/architecture/icons.ts` is
+derived from **@iconify-json/mdi 1.2.3**, the Iconify packaging of Material
+Design Icons.
+
+- Source: <https://www.npmjs.com/package/@iconify-json/mdi/v/1.2.3>
+- Upstream project: <https://github.com/Templarian/MaterialDesign>
+- License: **Apache License 2.0**
+- Packaged license copy: [`LICENSES/Apache-2.0.txt`](LICENSES/Apache-2.0.txt)
+- Canonical license URL: <https://www.apache.org/licenses/LICENSE-2.0>
+
+Only curated path data is bundled. Agentic Mermaid does not fetch Iconify packs
+at runtime and does not bundle the full npm package. The published
+`@iconify-json/mdi@1.2.3` tarball contains no upstream `NOTICE` file to
+reproduce.
+
+## Mermaid pinned test specifications
+
+The revision-bound oracle vendors two upstream Mermaid test specifications at
+`eval/mermaid-upstream-suite-bench/upstream-f3dea583/` solely to verify the
+26/69-block provenance inventory offline.
+
+- Source: <https://github.com/mermaid-js/mermaid/tree/f3dea58385fd5c7dd1f4e9c9c1876751ae6943cc>
+- Copyright: © 2014–2022 Knut Sveidqvist
+- License: **MIT**
+- Repository license copy: `eval/mermaid-upstream-suite-bench/upstream-f3dea583/LICENSE.mermaid.txt` (the upstream specs are verification-only and excluded from the npm package)