agentic-mermaid 0.1.1 → 0.2.0

package/docs/api.md

@@ -1,11 +1,59 @@
 # API reference
 
-Agentic Mermaid exposes two library surfaces:
+Agentic Mermaid exposes these library surfaces:
 
-- `agentic-mermaid` — renderer-focused public API for SVG and ASCII/Unicode output.
-- `agentic-mermaid/agent` — agent-native API with parse/narrow/mutate/verify/serialize plus SVG, PNG, and ASCII output helpers.
+- `agentic-mermaid` — runtime-neutral renderer API for SVG, ASCII/Unicode,
+  and host-injected browser PNG output.
+- `agentic-mermaid/agent` — agent-native API with
+  parse/narrow/mutate/verify/serialize plus SVG, native Node/Bun PNG, and ASCII
+  output helpers.
+- `agentic-mermaid/agent/core` — the same structured-edit, SVG, and ASCII
+  surface without the native PNG dependency; use this entry in browser and
+  workerd bundles.
+
+Capability reports, the pinned upstream manifest, and trusted Node-host
+resource resolution remain repository audit/host tooling rather than published
+runtime entry points.
 
 Use `agentic-mermaid/agent` when you want one import path for agents.
+Use `agentic-mermaid/agent/core` when the target runtime cannot load Node native
+addons.
+
+### Canonical requests and comparable receipts
+
+Every first-party renderer enters through the same immutable internal request
+boundary: source wrappers/config, the Style stack, colors, font, security, and
+shared options are normalized once. Receipt-bearing variants make that boundary
+observable without exporting its executable implementation types or changing
+the existing convenience return types:
+
+```ts
+import {
+  renderMermaidASCIIWithReceipt,
+  renderMermaidPNGWithReceipt,
+  renderMermaidSVGWithReceipt,
+} from 'agentic-mermaid/agent'
+
+const options = { style: 'hand-drawn', seed: 7, embedFontImport: false }
+const svg = renderMermaidSVGWithReceipt(source, options)
+const png = renderMermaidPNGWithReceipt(source, options)
+const text = renderMermaidASCIIWithReceipt(source, { ...options, colorMode: 'none' })
+
+console.assert(svg.receipt.sharedRequestDigest === png.receipt.sharedRequestDigest)
+console.assert(svg.receipt.appearanceDigest === text.receipt.appearanceDigest)
+```
+
+Each `RenderRequestReceipt` contains `version`, `output`,
+`sharedRequestDigest`, output-specific `requestDigest`, and
+`appearanceDigest`. Its `diagnostics` array records stable request-resolution,
+compatibility, applicability, projection, and output-policy decisions. In
+particular, `RENDER_OPTION_NOT_APPLICABLE` makes an authored family-scoped
+option that the selected family does not consume observable instead of letting
+it change request identity silently. CLI JSON results and local/hosted MCP
+render results expose the same receipt. Use `validateSerializableRenderOptions(value)` and
+`sharedRenderOptionsJsonSchema()` for untrusted advanced option objects, or
+`styleInputJsonSchema()` for a standalone convenience `style` field; unknown
+fields, `null`, functions, prototype keys, and non-finite values are rejected.
 
 ## Output helpers
 
@@ -18,7 +66,9 @@ const svg = renderMermaidSVG(`flowchart TD
   A --> B`, { security: 'strict' })
 ```
 
-`renderMermaidSVG(input, options?)` accepts a Mermaid source string or `ValidDiagram` and returns an SVG string.
+`renderMermaidSVG(input, options?)` accepts a Mermaid source string or any open
+`ParsedDiagram` envelope returned by `parseRegisteredMermaid` and returns an SVG
+string.
 
 ### PNG
 
@@ -35,20 +85,26 @@ const png = renderMermaidPNG(`flowchart TD
 writeFileSync('diagram.png', png)
 ```
 
-`renderMermaidPNG(input, options?)` accepts a Mermaid source string or `ValidDiagram` and returns `Uint8Array` PNG bytes.
+`renderMermaidPNG(input, options?)` accepts a Mermaid source string or any open
+`ParsedDiagram` envelope returned by `parseRegisteredMermaid` and returns
+`Uint8Array` PNG bytes. SVG, ASCII/Unicode, layout, native PNG, and browser PNG
+accept the same parsed-or-source input contract; an unregistered preserved
+envelope round-trips exactly and returns its stable capability diagnostic rather
+than falling through to Flowchart.
 
-`PngOptions`:
+`PngOptions` extends the shared `RenderOptions` contract used by SVG. The
+canonical machine-readable field set is returned by
+`sharedRenderOptionsJsonSchema()`; the table below contains only PNG-specific
+controls:
 
-| Option | Type | Default | Meaning |
+| Option | Type | Default | Availability and meaning |
 |---|---|---:|---|
-| `scale` | `number` | `2` | Zoom multiplier when `fitTo` is not set. |
-| `background` | `string` | `'white'` | PNG background color. |
-| `fitTo` | `{ width?: number; height?: number }` | — | Constrain output to a width or height. |
-| `style` | `StyleInput \| StyleInput[]` | — | Style name \| spec \| stack, same as `RenderOptions.style`. |
-| `seed` | `number` | `0` | Ink-wobble seed for styled looks, same as `RenderOptions.seed`. |
-| `fontDirs` | `string[]` | — | Extra font directories: custom styles that reference unbundled families, and scripts the bundled fonts don't cover (CJK, emoji). CLI: `--font-dirs <dirs>` (comma-separated). |
-| `loadSystemFonts` | `boolean` | `false` | Also load OS-installed fonts. Trades cross-machine determinism for glyph coverage; coverage warnings are skipped (system coverage is unknown). CLI: `--system-fonts`. |
-| `onWarning` | `(w: PngFontWarning) => void` | stderr | Receives `PNG_FONT_COVERAGE` warnings (characters no loaded font covers, grouped per script). Without a handler they are written to stderr — tofu is never silent. |
+| `scale` | `number` | `2` | Portable: native/browser library, CLI, and local/hosted MCP. Zoom multiplier when `fitTo` is not set. |
+| `background` | `string` | artifact background, then white | Portable on the same surfaces. Safe explicit PNG background color. |
+| `fitTo` | `{ width?: number; height?: number }` | — | Portable on the same surfaces. Constrain output to exactly one positive width or height. |
+| `fontDirs` | `string[]` | — | Trusted native-host input: Node/Bun library, CLI, and local MCP only. Extra font directories for unbundled families and scripts the bundled fonts do not cover. CLI: `--font-dirs <dirs>` (comma-separated). |
+| `loadSystemFonts` | `boolean` | `false` | Trusted native-host input on the same native surfaces. Trades cross-machine determinism for glyph coverage. CLI: `--system-fonts`. |
+| `onWarning` | `(w: PngFontWarning) => void` | stderr | Native library callback only. Receives `PNG_FONT_COVERAGE` warnings; callbacks never enter serializable requests or receipts. |
 
 PNG rasterization uses offline `@resvg/resvg-js` with bundled fonts for
 deterministic same-machine output: Inter (the default face — the same family
@@ -67,6 +123,48 @@ do not resolve CSS custom properties — `renderMermaidPNG` inlines the
 resolved family before rasterizing; do the same if you feed the raw SVG to
 your own pipeline.
 
+For complete custom-Style recipes using `font`, `fontDirs`, browser faces, and
+SVG font declarations, see [Fonts in custom styles](./custom-fonts.md).
+
+PNG output declares the shared sRGB policy with `sRGB` and `cICP` metadata,
+places `cICP` before image data, and deliberately emits no conflicting ICC
+profile. SVG and PNG consume the same resolved graphical colors before
+rasterization.
+
+#### Trusted host-selected graphical backends
+
+Executable backends are bound by the host, never selected by `RenderOptions` or
+serialized Style data. These factories apply the same canonical request,
+Scene-admission, SVG-security, receipt, PNG-output-policy, and color-profile
+contracts as their default counterparts:
+
+```ts
+import {
+  createMermaidBrowserPNGRenderer,
+  createMermaidRenderer,
+} from 'agentic-mermaid'
+import { createMermaidPNGRenderer } from 'agentic-mermaid/agent'
+
+const backendPolicy = { selectBackend: () => 'backend:acme/renderer' }
+const svgRenderer = createMermaidRenderer({ backendPolicy })
+const nodePngRenderer = createMermaidPNGRenderer({ backendPolicy })
+const browserPngRenderer = createMermaidBrowserPNGRenderer({
+  backendPolicy,
+  rasterize: async (securedSvg, context) => ({
+    png: await rasterizeWithCanvas(securedSvg, context.outputPolicy),
+  }),
+})
+```
+
+Register and conformance-check the named backend before constructing these
+renderers. The Node/Bun factory reuses the built-in `@resvg/resvg-js` adapter;
+the browser factory wraps a trusted injected rasterizer, which receives only
+the admitted and secured SVG plus the complete resolved portable output policy.
+Its rasterizer must apply `fitTo` and `background`, not only `scale`.
+`renderMermaidSVG`, `renderMermaidPNG`, and
+`renderMermaidPNGInBrowserWithReceipt` remain the compatible default-backend
+entry points.
+
 ### ASCII / Unicode
 
 ```ts
@@ -78,7 +176,16 @@ const ascii = renderMermaidASCII(`flowchart LR
   A --> B`, { useAscii: true })
 ```
 
-`renderMermaidASCII(input, options?)` accepts a Mermaid source string or `ValidDiagram` and returns terminal text.
+`renderMermaidASCII(input, options?)` accepts a Mermaid source string or any open
+`ParsedDiagram` envelope returned by `parseRegisteredMermaid` and returns terminal
+text.
+
+`AsciiRenderOptions` also extends the same shared `RenderOptions` contract.
+Terminal-only controls and the explicit losses involved in projecting a
+graphical appearance onto terminal cells are documented in
+[`ascii.md`](./ascii.md).
+`colorMode: 'html'` returns an escaped terminal projection through this same
+function; it is not a separate CLI output format or a `renderMermaidHTML` API.
 
 `AsciiRenderOptions`:
 
@@ -90,51 +197,107 @@ const ascii = renderMermaidASCII(`flowchart LR
 | `boxBorderPadding` | `number` | `1` | Inner box padding. |
 | `colorMode` | `string` | `'auto'` | `'none'`, `'auto'`, `'ansi16'`, `'ansi256'`, `'truecolor'`, or `'html'`. |
 | `theme` | `Partial<AsciiTheme>` | — | Override ASCII colors. |
-| `mermaidConfig` | `MermaidRuntimeConfig` | — | Mermaid-style runtime config. |
-| `ganttToday` | `string` | unset | Explicit "today" for the Gantt `todayMarker`; same deterministic clock behavior as SVG. |
-
-## SVG render options
-
-`renderMermaidSVG` accepts `RenderOptions`:
-
-| Option | Type | Default | Meaning |
-|---|---|---:|---|
-| `bg` | `string` | `#FFFFFF` | Background color or CSS variable. |
-| `fg` | `string` | `#27272A` | Foreground color or CSS variable. |
-| `line` | `string?` | — | Edge/connector color. |
-| `accent` | `string?` | — | Arrow heads and highlights. |
-| `muted` | `string?` | — | Secondary text/labels. |
-| `surface` | `string?` | — | Node fill tint. |
-| `border` | `string?` | — | Node stroke color. |
-| `font` | `string` | `Inter` | Font family. |
-| `style` | `string \| StyleSpec \| (string \| StyleSpec)[]` | — | How the diagram looks: a registered style name (`'hand-drawn'`, `'tufte'`, any palette like `'dracula'`), an inline public `StyleSpec`, or a stack merged left→right (`['hand-drawn', 'dracula']`). See `docs/style-authoring.md`. |
-| `seed` | `number` | `0` | Deterministic re-roll for stochastic styles — shuffles ink wobble, never layout. |
-| `transparent` | `boolean` | `false` | Transparent SVG background. |
-| `padding` | `number` | `40` | Canvas padding. |
-| `nodeSpacing` | `number` | `24` | Horizontal sibling spacing. |
-| `layerSpacing` | `number` | `40` | Vertical layer spacing. |
-| `componentSpacing` | `number` | `24` | Disconnected component spacing. |
-| `interactive` | `boolean` | `false` | XY chart hover tooltips. |
-| `shadow` | `boolean` | `false` | Explicit drop shadows. |
-| `mermaidConfig` | `MermaidRuntimeConfig` | — | Runtime Mermaid config. |
-| `embedFontImport` | `boolean` | `true` | Include Google Fonts `@import`; set false for offline SVG/PNG. |
-| `compact` | `boolean` | `false` | Compact SVG output while preserving agent hooks. |
-| `idPrefix` | `string` | `''` | Namespace generated SVG def ids. |
-| `security` | `'default' | 'strict'` | `'default'` | `strict` disables external-fetch references. |
-| `ganttToday` | `string` | unset | Explicit "today" for the Gantt `todayMarker` (date in the diagram's `dateFormat` or ISO `YYYY-MM-DD`). Gantt never reads the wall clock; without this the marker is not drawn. |
+| `targetWidth` | `number` | unset | Hard maximum line width in terminal display cells. Uses grapheme-safe fitting; impossible geometry throws `AsciiWidthError`. |
+| `maxWidth` | `number` | unset | Deprecated best-effort label wrapping. It does **not** guarantee the output width. Do not combine with `targetWidth`. |
+| `onProjectionDiagnostic` | `(diagnostic: TerminalProjectionDiagnostic) => void` | — | Host callback for explicit graphical-to-terminal projection losses; non-serializable and excluded from receipts. |
+
+`AsciiWidthError` has code `ASCII_TARGET_WIDTH_IMPOSSIBLE` plus
+`requestedWidth`, `requiredWidth`, `family`, and `reason` (`MINIMUM_GEOMETRY`,
+`UNBREAKABLE_GRAPHEME`, or `INVALID_WIDTH`). The same fields are returned by
+CLI JSON and hosted MCP errors. CLI: `am render diagram.mmd --format unicode
+--target-width 80`; hosted `render_ascii`: `{ source, targetWidth: 80 }`.
+Omitting both width options preserves the unconstrained output path.
+
+## Shared render options
+
+SVG, PNG, ASCII, and Unicode adapters accept this serializable `RenderOptions`
+field set. The built-in-family column exposes family applicability; the
+terminal column records whether text output consumes a field, projects it with
+an explicit diagnostic, or declares it inapplicable. Output-specific controls
+remain in their respective sections.
+
+<!-- BEGIN GENERATED SHARED RENDER OPTIONS -->
+| Option | Type | Effective default | Meaning | Built-in families | Terminal |
+|---|---|---|---|---|---|
+| `bg` | `string` | `#FFFFFF` | Background color or CSS variable. | all | consumed |
+| `fg` | `string` | `#27272A` | Primary foreground and text color. | all | consumed |
+| `line` | `string` | derived | Connector and secondary-line color. | all | consumed |
+| `accent` | `string` | derived | Arrowhead, highlight, and data accent color. | all | consumed |
+| `muted` | `string` | derived | Secondary text and label color. | all | projected — terminal themes have no dedicated muted-text role |
+| `surface` | `string` | derived | Node and group surface color. | all | projected — terminal cells do not paint graphical surfaces |
+| `border` | `string` | derived | Node and group border color. | all | consumed |
+| `font` | `string` | `Inter` | CSS font family or stack. | all | projected — the host terminal owns the font face |
+| `style` | `StyleInput \| StyleInput[]` | `crisp` | Registered Style/Palette name, inline StyleSpec, or left-to-right stack. | all | consumed |
+| `padding` | `number` | `40` | Canvas padding in SVG user units. | flowchart, state, architecture | not-applicable — terminal output uses paddingX, paddingY, and boxBorderPadding |
+| `nodeSpacing` | `number` | `24` | Horizontal spacing between sibling nodes. | flowchart, state, class, er, architecture | not-applicable — terminal layout has a cell-grid spacing contract |
+| `layerSpacing` | `number` | `40` | Vertical spacing between graph layers. | flowchart, state, class, er, architecture | not-applicable — terminal layout has a cell-grid spacing contract |
+| `wrappingWidth` | `number` | unset | Flowchart measured-label wrapping budget in pixels. | flowchart | not-applicable — terminal output uses maxWidth or targetWidth |
+| `componentSpacing` | `number` | extension-defined | Spacing between disconnected graph components for compatible extension families; no built-in family currently consumes it. | none — extension-defined | not-applicable — terminal layout has a cell-grid spacing contract |
+| `transparent` | `boolean` | `false` | Omit the painted SVG canvas background. | all | projected — terminal output has no painted canvas background |
+| `interactive` | `boolean` | `false` | Enable hover tooltips for supported chart data points. | xychart, pie, quadrant | projected — terminal output is a static semantic projection |
+| `shadow` | `boolean` | `false` | Paint explicit drop shadows on node shapes. | flowchart, state, sequence, timeline, class, er, journey, xychart, pie, quadrant, gantt, mindmap, gitgraph | projected — elevation projects to borders and labels |
+| `class` | `{ hierarchicalNamespaces?: boolean }` | `hierarchicalNamespaces: true` | Class-diagram rendering controls. | class | not-applicable — this option configures graphical class layout |
+| `architecture` | `{ visual?: ArchitectureVisualOverrides }` | built-in metrics | Sparse architecture renderer visual metric and paint overrides. | architecture | not-applicable — this option configures graphical architecture rendering |
+| `timeline` | `{ maxWidth?: number }` | `maxWidth`: unset | Timeline layout controls. | timeline | not-applicable — terminal output uses maxWidth or targetWidth |
+| `journey` | `{ experienceCurve?: boolean }` | `experienceCurve: true` | User-journey graphical controls. | journey | not-applicable — experience curves are graphical-only |
+| `gantt` | `{ dependencyArrows?: boolean; criticalPath?: boolean }` | both `false` | Gantt dependency and critical-path overlays. | gantt | not-applicable — graphical Gantt connector emphasis is not represented in cells |
+| `mermaidConfig` | `MermaidRuntimeConfig` | source config | Mermaid-style recursive runtime configuration. | all | consumed |
+| `embedFontImport` | `boolean` | `false` | Embed the Google Fonts import in SVG styles; PNG forces this off for offline rasterization. | all | not-applicable — terminal output embeds no web-font import |
+| `compact` | `boolean` | `false` | Compact SVG serialization while preserving agent hooks. | all | not-applicable — compact controls SVG serialization |
+| `idPrefix` | `string` | unset | Non-empty namespace for generated SVG definition IDs and local references. | all | not-applicable — terminal output has no SVG definition ids |
+| `security` | `'default' \| 'strict'` | `default` | Active SVG content is rejected in every mode; strict additionally rejects every external reference. Raw Mermaid themeCSS is rejected in both modes. | all | not-applicable — terminal text has its own control-character and HTML-color safety projection |
+| `ganttToday` | `string` | unset | Explicit deterministic date for the Gantt today marker. | gantt | consumed |
+| `seed` | `number` | `0` | Deterministic re-roll seed for stochastic Styles. | all | not-applicable — terminal glyph geometry is deterministic and has no stochastic ink |
+<!-- END GENERATED SHARED RENDER OPTIONS -->
+
+`Built-in families: all` means the field is family-neutral. `none —
+extension-defined` means no built-in currently consumes it. An external
+`FamilyDescriptor` opts into any family-scoped field it consumes through its
+frozen `applicableRenderOptions` array; an omitted or empty declaration means
+none, and authored values receive `RENDER_OPTION_NOT_APPLICABLE` in the render
+receipt.
+
+`onConfigDiagnostic?: (diagnostic: ConfigDiagnostic) => void` is deliberately
+outside the serializable field set. Library callers can collect qualified
+`INEFFECTIVE_CONFIG` warnings without changing output bytes; CLI, MCP, editor,
+and JSON Schema surfaces return diagnostics as data instead of accepting a
+function.
+
+### SVG semantic identity and accessibility
+
+All built-in families expose the same inspectable element contract:
+
+- every source-semantic Scene mark has a deterministic `data-id` and closed
+  `data-role`; identity is unique within one SVG (layout furniture retains typed
+  Scene identity without bloating the DOM);
+- source relations use `data-from` and `data-to`; source `className` tokens stay
+  on the identified element's `class` attribute;
+- typed relations expose `role="graphics-symbol"`,
+  `aria-roledescription="relation"`, and an `aria-label` derived from endpoints
+  plus the authored relation label;
+- public Scene types expose `SvgSemanticIdentity`,
+  `SvgSemanticAccessibility`, and `SvgRelationSemantics`;
+- `idPrefix` rewrites local DOM `id` references, not source-facing `data-id`.
+
+Built-in concrete palettes are contrast-normalized at render time: normal text
+roles meet WCAG AA 4.5:1 and meaningful relation lines/markers meet 3:1 against
+the page background. Unresolved runtime CSS variables cannot be statically
+certified and pass through unchanged. See
+[`svg-semantic-contract.md`](./svg-semantic-contract.md) for the complete contract.
 
 For JSON files, use
 [`docs/schemas/style-spec.schema.json`](./schemas/style-spec.schema.json). The
 same schema is exported from the npm package as
 `agentic-mermaid/style-spec.schema.json`; see
 [`custom-style-cookbook.md`](./custom-style-cookbook.md) for complete style
-files and screenshots.
+files and screenshots, and [`custom-fonts.md`](./custom-fonts.md) for font
+resolution across output surfaces.
 
 ## Agent edit API
 
 ```ts
 import {
-  parseMermaid,
+  parseRegisteredMermaid,
   asFlowchart,
   mutate,
   verifyMermaid,
@@ -150,43 +313,85 @@ Core functions:
 
 | Function | Purpose |
 |---|---|
-| `parseMermaid(source)` | Parse Mermaid source to `Result<ValidDiagram, ParseError[]>`. |
-| `asFlowchart(d)` / `asState(d)` / `asSequence(d)` / `asTimeline(d)` / `asClass(d)` / `asEr(d)` / `asJourney(d)` / `asArchitecture(d)` / `asXyChart(d)` / `asPie(d)` / `asQuadrant(d)` / `asGantt(d)` | Narrow to a mutable family or return `null`. |
+| `parseRegisteredMermaid(source)` | Parse Mermaid source to `Result<ValidDiagram, ParseError[]>`. |
+| Family narrower | Narrow to a mutable family or return `null`; obtain the current generated name from `am capabilities --json`. |
 | `mutate(d, op)` | Apply a kind-discriminated typed mutation. |
 | `verifyMermaid(d)` | Return structural warnings and layout evidence. |
 | `analyzeMermaid(d)` / `analyzeMermaidSource(source)` | Return deterministic non-rendering analysis: feedback edges, source-only action records, and Gantt critical-path/slack summary when available. |
 | `describeMermaidFacts(d)` / `checkMermaid(d, spec)` | Return deterministic semantic fact lines, or check required/forbidden facts such as `edge Processing -> [*] : done`, `member Duck +quack()`, `task Docs start after core`. |
 | `serializeMermaid(d)` | Emit source only after verifying. |
-| `layoutMermaid(d)` | Return layout JSON for quality/inspection; `layoutMermaid(d, { debug: true })` includes graph route certificates, family edge-route certificates (class/ER/architecture/sequence), region-containment certificates (timeline/charts), and V1 region/action sidecars. Edge certificates include exact ports plus side/slot/role port assignments where applicable. |
-| `measureQuality(layout)` / `checkQuality(layout)` | Perceptual quality metrics. |
+| `layoutMermaid(d)` | Return layout JSON for quality/inspection; `layoutMermaid(d, { debug: true })` includes graph route certificates, family edge-route certificates (class/ER/architecture/sequence), region-containment certificates (timeline/charts), and semantic region/action sidecars (`cluster`, `lane`, `band`, `compartment`, `plot`, `ring`). Edge certificates include exact ports plus side/slot/role port assignments where applicable. |
+| `renderMermaidWithActions(d, request)` | Render SVG, PNG, ASCII, or Unicode and return one inert action/hit-region sidecar for admitted Flowchart/Class/Gantt interactions and Sequence actor-menu links. An SVG href is `embedded-inert` only when matching inert metadata is present in the returned SVG; PNG/terminal actions, strict-mode hrefs, and all callbacks are `sidecar-only` and never execute. Terminal artifacts also return projection `warnings`, and terminal render failure throws instead of returning an empty success artifact. |
+| `measureQuality(layout, colors?)` / `checkQuality(layout, bounds?, colors?)` | Perceptual quality metrics, including fail-closed contrast (`null` when requested paints are unresolved), nearest-node spacing, and element density. Rendered audits can supply exact foreground/background associations through `textPairs`. |
 | `describeMermaid(d, { format })` | Prose, AX-tree, or facts summary (`format: "text" | "json" | "facts"`). |
 
-Typed mutation families:
-
-| Family | Narrower | Common ops |
-|---|---|---|
-| Flowchart | `asFlowchart` | `add_node`, `remove_node`, `rename_node`, `set_label`, `add_edge`, `remove_edge` |
-| State | `asState` | `add_state`, `remove_state`, `rename_state`, `set_state_label`, `add_transition`, `remove_transition`, `set_transition_label`, `make_composite` |
-| Sequence | `asSequence` | `add_participant`, `remove_participant`, `add_message`, `remove_message`, `set_message_text` |
-| Timeline | `asTimeline` | `set_title`, `add_section`, `add_period`, `add_event`, remove/set variants |
-| Class | `asClass` | `add_class`, `remove_class`, `rename_class`, `add_member`, `add_relation`, notes |
-| ER | `asEr` | `add_entity`, `remove_entity`, `rename_entity`, `add_attribute`, `add_relation` |
-| Journey | `asJourney` | `set_title`, `add_section`, `add_task`, `set_task_score`, `set_task_actors`, `rename_actor`, … |
-| XY chart | `asXyChart` | `set_title`, `set_x_axis`, `set_y_axis`, `add_series`, `set_series_values`, `reorder_series`, … |
-| Architecture | `asArchitecture` | `add_service`, `move_service`, `add_group`, `add_edge`, `rename_service`, … |
-| Pie | `asPie` | `set_title`, `set_show_data`, `add_slice`, `remove_slice`, `rename_slice`, `set_slice_value`, `reorder_slice` |
-| Quadrant | `asQuadrant` | `set_title`, `set_axis_labels`, `set_quadrant_label`, `add_point`, `remove_point`, `move_point`, `rename_point` |
-| Gantt | `asGantt` | `set_title`, `add_section`, `rename_section`, `add_task`, `set_task_status`, `set_task_dates`, … |
+The family registry is the operation authority. Use `am capabilities --json`
+for the current roster and field schemas, or call `describeOps(family)` and
+`opSignatures(family)` at runtime. The generated SDK declaration projects the
+same descriptors; this reference deliberately does not copy an exhaustive
+family/operation table.
 
 Opaque fallback bodies (any unmodeled syntax) are source-level-only: edit source deliberately, then parse and verify again.
 
+## Capability and extension discovery
+
+Repository audit tooling can import `createSectionACapabilityReport()` from
+`src/section-a-capability-report.ts`. It returns the JSON-safe, registry-derived
+request/backend/output/family/Scene matrix. `am capabilities --json` →
+`sectionA` intentionally exposes only its version, pin, digest, counts,
+no-absent status, and directions to this full report. Validate a stored snapshot with
+`validateSectionACapabilityReport(report)`. The generated human projection is
+[`project/section-a-capability-report.md`](./project/section-a-capability-report.md).
+Keeping this audit surface out of the package prevents the full characterization
+and upstream syntax corpora from entering renderer/browser bundles.
+
+Canonical extension identities are kind-qualified (`look:`, `palette:`,
+`backend:`, `family:`, `role:`, and `resource:`), versioned, provenance-bearing,
+and collision-safe. New graphical backends declare feature/operation-level
+Scene primitive capability claims; the registry rejects an empty, duplicate,
+cross-target, or otherwise invalid claim set. Every external backend, and every
+external family that supplies `lowerScene`, must also declare an explicit
+compatible `identity.compatibility.scene` range (Scene v2: `^2.0.0`). The host
+checks that range before running backend conformance or other executable
+witnesses; only the internal built-in enrollment path receives compatibility
+defaults.
+
+### Current customization and extension inventory
+
+This is the current authoritative inventory. Field-level `RenderOptions` and
+`StyleSpec` details remain in their generated tables above rather than being
+copied here.
+
+| Level | Public seam | What it can change | Boundary and availability |
+|---|---|---|---|
+| Mermaid-authored appearance | frontmatter/init config, theme variables, family style statements such as classes and link styles | Syntax-defined colors, labels, family geometry, and interaction metadata where the family advertises support | Source-level and family-dependent. Raw `themeCSS` is recognized but diagnosed at the render boundary because its selectors and markup can escape an imported SVG; use `StyleSpec` instead. |
+| One-off render overrides | `RenderOptions` | Palette channels, font family, spacing/geometry controls, deterministic seed, security, accessibility-related output options, and a Style stack | The generated field×surface matrix marks each serializable shared field `forwarded`, `host-enforced`, or `unavailable`. Hosted SVG and editor SVG enforce strict security with external font imports disabled; effective receipts reflect those constraints. Host callbacks are library-only and never enter receipts. |
+| One-off declarative style | inline `StyleSpec` or a left-to-right `StyleInput[]` stack | Safe palette, font, stroke/fill treatment, backdrop, exact semantic-role defaults, named semantic slots, V1 `category` bindings, non-color cues, and inspect-only contrast/accent-area/mono-role constraints | JSON-safe and executable-code-free. Bindings supply defaults beneath authored family paint and semantics; constraints diagnose final effective paint without repainting or relayout. This is the lowest-complexity custom Style path. |
+| Named Palette/Look | `registerStyle`, `getStyle`, `knownStyleDescriptors` | Installs a versioned `palette:` or `look:` name backed by exactly the same `StyleSpec` accepted inline | Descriptors expose one `kind` (`look` or `palette`), explicit `isDefault`, and one stable `inputName`. In-process host registry. A CLI/MCP/server sees a registration only when that host installs it at startup. |
+| Theme conversion | `fromShikiTheme` | Converts a Shiki-compatible editor theme into diagram colors | Pure library helper; the result is ordinary declarative color input. |
+| Live host retheming | CSS custom-property values in graphical color/font inputs | Lets a host page switch SVG palette and font values without re-rendering | SVG/browser-only and limited to safe property values; this is not a raw CSS rule or selector hook. Static outputs need values resolved under their rasterization environment to remain reproducible. |
+| Terminal output projection | `AsciiRenderOptions` (`useAscii`, `paddingX`, `paddingY`, `boxBorderPadding`, `colorMode`, `theme`, `targetWidth`/`maxWidth`, `onProjectionDiagnostic`) | Selects Unicode/ASCII encoding, cell spacing, width policy, ANSI/HTML colors, terminal-only theme overrides, and projection-loss reporting | Output-adapter customization, not a second shared Style system. Serializable fields have transport-specific availability; the diagnostic callback is host-only and remains outside receipts. |
+| Fonts and installed resources | `font`, Node PNG `fontDirs`/`loadSystemFonts`/`onWarning`, browser `BrowserPngRasterizer`, `ResourceManifest`, and repository host tooling via `NodeResourceResolver` | Selects a safe font stack, supplies host-dependent raster fonts, reports missing glyph coverage, or verifies bounded installed bytes | Font family names do not install fonts. Browser and warning callbacks remain outside serializable options and every digest. Node `fontDirs`/`loadSystemFonts` are trusted host inputs outside shared `RenderOptions` and the shared/appearance digests, but their resolved PNG output policy is included in the output-specific request digest; runtime provenance still marks host-dependent resources explicitly. Manifests require path, size, media-type, digest, and licence evidence and never fall back to network access. |
+| Graphical backend | `registerBackend`, `runBackendConformance`, `createMermaidRenderer`, `createMermaidPNGRenderer`, `createMermaidBrowserPNGRenderer` (each with a host-only `backendPolicy`) | Serializes the typed Scene contract with a different drawing implementation for SVG, native Node/Bun PNG, and injected-rasterizer browser PNG | Trusted in-process host only. Host registrations must explicitly declare compatible core and Scene ranges; identity/compatibility admission precedes executable conformance. Registration then must pass bounded, deterministic, semantic, well-formed, secure SVG conformance plus an exact witness for every first-party core primitive/feature/operation claim; namespaced extension claims without a core witness remain explicitly unverified. All listed factories use the same admitted and secured graphical request; PNG adapters do not reparse or rerender source. Serializable styles and `RenderOptions` cannot select arbitrary executable backends. |
+| Diagram family | `registerFamily`, `getFamilyConformanceReport`, `parseRegisteredMermaid`, `projectPositionedView` | Adds a namespaced language with detection, parse/preservation, verification, layout, Scene/SVG, terminal, and discovery claims | Every versioned `family:<owner/name>` descriptor declares a compatible core range and supplies one bounded canonical `example`. It also lists consumed family-scoped shared fields in `applicableRenderOptions`; omission means none, unknown or duplicate fields fail registration, and the frozen declaration appears in the capability report. Registration stages the frozen candidate, runs native claims twice through canonical parse/serialize, non-empty positive-bounds layout, strict SVG, portable PNG pre-raster, terminal, Scene and verify paths, and rolls back on failure, reentrancy or nondeterminism. Discovery reports `native` only beside a passed per-capability witness. Native tuples still require layout + `projectPositioned`, Scene requires layout + `lowerScene`, and extension verification requires its hook plus executable SVG. An external Scene family additionally declares a compatible Scene range, and its example witnesses every positive role/primitive cell. Built-in-only unions stay closed; extension bodies use the open envelope. Remote transports gain the family only when their trusted host installs it. |
+| Scene semantics | `SceneDoc`, typed connectors/markers/hit geometry, namespaced `SceneRole` | Lets a family/backend exchange identity, relationship, accessibility, geometry, and terminal-projection intent | This is a versioned typed contract, not a raw SVG hook. Unknown namespaced roles deliberately receive inert identity-only traits and cannot acquire core behavior by local-name collision. There is no public arbitrary primitive/trait mutation registry. |
+| Browser PNG host adapter | `renderMermaidPNGInBrowserWithReceipt(..., rasterize)` or reusable `createMermaidBrowserPNGRenderer({ rasterize, backendPolicy? })` | Supplies Canvas/OffscreenCanvas rasterization and reports font provenance | Trusted callback receives only the admitted, secured canonical SVG; the library re-applies the PNG color-profile gate and retains the same logical receipt as the native PNG path. |
+| Identity plumbing | `canonicalExtensionId`, `parseExtensionId`, `createExtensionIdentity`, `registerExtension`, `ExtensionCollisionError` | Gives kind-specific registries stable names, parsing, versions, provenance, compatibility ranges, and collision rejection | Low-level plumbing, not a stand-alone extension registry or rendering hook. Stable short inputs belong to kind-specific descriptors. |
+
+There is currently no BrandPack registry, public role-trait registration,
+arbitrary SVG/CSS hook, or Treatment hook. Semantic slots and the closed V1
+`category` binding API are ordinary `StyleSpec` fields; other Scene channels are
+not publicly bindable without new executable family witnesses. B4 remains the
+unpromoted, evidence-gated BrandPack distribution envelope only. A future
+Treatment seam is a separate decision and is not implied by B4.
+
 ## CLI
 
 ```bash
 am render diagram.mmd --format svg > diagram.svg
-am render diagram.mmd --format png --output diagram.png
+am render diagram.mmd --format png --output diagram.png --fit-width 1200 --bg '#fff'
 am render diagram.mmd --format ascii > diagram.txt
-am render diagram.mmd --format json --certificates > layout-with-routes.json
+am render diagram.mmd --format layout --certificates > layout-with-routes.json
 am verify diagram.mmd
 am describe diagram.mmd --format facts
 am mutate diagram.mmd --op '{"kind":"add_node","id":"Cache","label":"Cache"}' --json
@@ -194,18 +399,20 @@ am capabilities --json
 am init-agent --dir . --json
 ```
 
-PNG is single-input and requires `--output` so binary bytes are never accidentally printed to a terminal. `am init-agent` writes a non-clobbering agent-agnostic onboarding bundle (`AGENTS.md`, root `skills/`, and `.mcp.json`) into a consumer repo.
+PNG is single-input and requires `--output` so binary bytes are never accidentally printed to a terminal. Portable controls are `--scale`, `--bg`, and the mutually exclusive `--fit-width`/`--fit-height`; native-host font controls are `--font-dirs` and `--system-fonts`. `am init-agent` writes a non-clobbering agent-agnostic onboarding bundle (`AGENTS.md`, root `skills/`, and `.mcp.json`) into a consumer repo.
 
 ## MCP
 
-The published package exposes Node-runnable bins: `am`, `agentic-mermaid`, and `agentic-mermaid-mcp`.
+The published package exposes Node-runnable bins: `am`, the package-runner
+alias `agentic-mermaid`, and `agentic-mermaid-mcp`.
 
 Local `agentic-mermaid-mcp` is Code Mode-first and exposes:
 
 - `execute(code)` — primary Code Mode tool with global `mermaid.*` SDK.
-- `render_png` — narrow helper returning base64 PNG bytes, or managed file/URL artifacts via `output: "file"|"url"`.
+- `describe_sdk({ family, detail })` — version-matched compact signatures or exact mutation fields for one family.
+- `render_png` — narrow helper returning base64 PNG bytes, or managed file/URL artifacts via `output: "file"|"url"`; accepts portable `scale`/`background`/`fitTo`, plus local-only `fontDirs`/`loadSystemFonts`, and returns configuration/font-coverage warnings with every output mode.
 - `describe` — narrow summary helper; pass `format: "facts"` for deterministic semantic fact lines.
 
-Use Code Mode for multi-step parse/narrow/mutate/verify/serialize loops. Use `render_png` or host/library code for binary PNG output. The default transport is stdio; `agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000` starts the HTTP/SSE transport. HTTP mode serves managed artifacts from `/artifacts/<name>` with MIME type, byte count, and SHA-256 metadata in tool responses. Non-loopback HTTP binding requires `--auth-token`.
+Use Code Mode for multi-step parse/narrow/mutate/verify/serialize loops. Use `render_png` or host/library code for binary PNG output. The default transport is stdio; `agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000` starts the HTTP/SSE transport. HTTP mode serves managed artifacts from `/artifacts/<name>` with MIME type, byte count, and SHA-256 metadata in tool responses. Non-loopback HTTP binding requires `--auth-token`; that bearer token protects `/rpc`, `/sse`, `/message`, and `/artifacts/*`.
 
-A hosted Streamable HTTP endpoint also runs at `https://agentic-mermaid.dev/mcp`. It is MCP JSON-RPC only (not REST), stateless, public/unauthenticated, and capped at 64 KB inputs. Hosted tools are `execute`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, and `build`; hosted `execute` uses a Cloudflare Dynamic Worker isolate with no network, and hosted `render_png` returns base64 only. Prefer local CLI/library/MCP for sensitive diagrams, offline work, larger inputs, or file/URL PNG artifacts. See [`mcp-http-transport.md`](./mcp-http-transport.md) for JSON-RPC examples and option details.
+A hosted Streamable HTTP endpoint also runs at `https://agentic-mermaid.dev/mcp`. It is MCP JSON-RPC only (not REST), stateless, public/unauthenticated, and capped at 64 KB inputs. Hosted tools are `execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, and `build`; `describe_sdk` returns compact signatures or exact mutation fields for one family, hosted `execute` uses a Cloudflare Dynamic Worker isolate with no network, and hosted `render_png` returns base64 only while retaining portable `scale`/`background`/`fitTo`. Prefer local CLI/library/MCP for sensitive diagrams, offline work, larger inputs, native font controls, or file/URL PNG artifacts. See [`mcp-http-transport.md`](./mcp-http-transport.md) for JSON-RPC examples and option details.

package/docs/ascii.md

@@ -22,6 +22,12 @@ am render diagram.mmd --format unicode
 
 ## Options
 
+`AsciiRenderOptions` extends the canonical shared `RenderOptions` used by SVG
+and PNG, so Style stacks, colors, font choice, security policy, and other
+shared request fields enter through the same boundary. Call
+`sharedRenderOptionsJsonSchema()` for the machine-readable shared field set.
+The options below are terminal-specific.
+
 ```ts
 renderMermaidASCII(source, {
   useAscii: true,
@@ -29,6 +35,7 @@ renderMermaidASCII(source, {
   paddingY: 2,
   boxBorderPadding: 1,
   colorMode: 'none',
+  targetWidth: 80,
 })
 ```
 
@@ -40,7 +47,13 @@ renderMermaidASCII(source, {
 | `boxBorderPadding` | `number` | `1` | Padding inside node boxes. |
 | `colorMode` | `string` | `'auto'` | `'none'`, `'auto'`, `'ansi16'`, `'ansi256'`, `'truecolor'`, or `'html'`. |
 | `theme` | `Partial<AsciiTheme>` | — | Override terminal colors. |
-| `mermaidConfig` | `MermaidRuntimeConfig` | — | Mermaid-style runtime config. |
+| `maxWidth` | `number` | — | Deprecated best-effort label wrapping; the canvas may exceed it. |
+| `targetWidth` | `number` | — | Hard maximum in terminal display cells; impossible geometry throws `AsciiWidthError` with code `ASCII_TARGET_WIDTH_IMPOSSIBLE`. |
+
+HTML is an escaped terminal projection, selected programmatically with
+`renderMermaidASCII(source, { colorMode: 'html' })`. It is not a standalone
+`am render --format` value; CLI discovery advertises only directly supported
+artifact formats.
 
 ## ASCII with metadata
 
@@ -49,10 +62,10 @@ Agents and TUIs can use `renderMermaidASCIIWithMeta` to map terminal cells back
 ```ts
 import { renderMermaidASCIIWithMeta } from 'agentic-mermaid/agent'
 
-const { ascii, regions, warnings, routeParity } = renderMermaidASCIIWithMeta(source)
+const { ascii, regions, actions, warnings, routeParity } = renderMermaidASCIIWithMeta(source)
 ```
 
-`regions` includes best-effort terminal spans for load-bearing node labels, edge labels where mapped, participant/task/chart labels, and subgraph label spans suitable for click mapping. It is not a full cell-by-cell box/edge hit-test tree yet. `routeParity` is an explicit V1 contract: ASCII/Unicode does not consume SVG route certificates directly; the converter seeds edges with shared `classifyRoutes()` route intent and the grid router maps that intent into terminal placement/routing. `warnings` reports structured degradation such as `ASCII_EDGE_REGION_UNMAPPED` when edge cell spans are not instrumented even though route drawing still follows the parity mapping.
+`regions` includes best-effort terminal spans for load-bearing node labels, edge labels where mapped, participant/task/chart labels, and semantic containers such as clusters, sequence fragments, class compartments, chart plots, and radar rings. It is suitable for click mapping, but is not a full cell-by-cell box/edge hit-test tree. `actions` contains inert action metadata only; a host must decide whether and how to handle it. `routeParity` is an explicit V1 contract: ASCII/Unicode does not consume SVG route certificates directly; the converter seeds edges with shared `classifyRoutes()` route intent and the grid router maps that intent into terminal placement/routing. `warnings` reports structured degradation such as `ASCII_EDGE_REGION_UNMAPPED` when edge cell spans are not instrumented even though route drawing still follows the parity mapping.
 
 ## Reversing simple flowcharts
 
@@ -72,19 +85,16 @@ not for reconstructing arbitrary Mermaid source.
 
 ## Supported families
 
-ASCII/Unicode output is available from the public entrypoints for:
-
-- flowchart/state
-- sequence
-- class
-- ER
-- timeline
-- journey
-- XY chart
-- architecture
-- pie
-- quadrant
-- gantt
+Family support is registry-driven rather than maintained as a second list in
+this guide. Run `am capabilities --json` for live discovery; the generated
+[Section A capability matrix](./project/section-a-capability-report.md) records
+terminal projection support and named losses for every registered family.
+
+Style appearance is projected to terminal colors and glyphs. Use a
+receipt-bearing render API to compare its `appearanceDigest` with graphical
+outputs, and inspect projection diagnostics when a graphical feature has no
+terminal equivalent. `colorMode: 'auto'` disables color for non-TTY output,
+`TERM=dumb`, and `NO_COLOR` before considering color-depth hints.
 
 PNG output is separate: use `renderMermaidPNG(source)` or `am render --format png --output file.png` when a raster artifact is required.