agentic-mermaid 0.1.1 → 0.2.0

package/docs/custom-fonts.md

@@ -0,0 +1,265 @@
+# Fonts in custom styles
+
+A custom style chooses a font family; the environment that renders the
+diagram supplies the actual face. The public `StyleSpec` deliberately keeps
+those responsibilities separate:
+
+```json
+{
+  "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
+  "name": "acme-report",
+  "font": "'Acme Sans', Inter, system-ui",
+  "colors": {
+    "bg": "#fffdf8",
+    "fg": "#171512",
+    "accent": "#1d4ed8"
+  },
+  "stroke": "crisp"
+}
+```
+
+`font` is a CSS family name or family stack. It does not load a file, register
+a browser `FontFace`, or tell the PNG rasterizer where to find one. This keeps
+the same style usable across SVG and PNG while each output surface resolves
+fonts in its own way.
+
+For the rest of the Style model — inline specs, registration, stacking, and
+validation — see [Authoring styles](./style-authoring.md).
+
+## Quick recipe
+
+Save the JSON above as `acme-report.style.json`. For an SVG that declares the
+family without making an external font request:
+
+```bash
+am render diagram.mmd \
+  --format svg \
+  --style acme-report.style.json \
+  --security strict \
+  --output diagram.svg
+```
+
+For a PNG, point the local rasterizer at a directory containing the matching
+font faces:
+
+```bash
+am render diagram.mmd \
+  --format png \
+  --style acme-report.style.json \
+  --font-dirs ./fonts \
+  --output diagram.png
+```
+
+The same workflow through the library is:
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs'
+import {
+  renderMermaidPNG,
+  renderMermaidSVG,
+  validateStyleSpec,
+} from 'agentic-mermaid/agent'
+
+const source = readFileSync('diagram.mmd', 'utf8')
+const style = JSON.parse(readFileSync('acme-report.style.json', 'utf8'))
+const problems = validateStyleSpec(style)
+if (problems.length) throw new Error(problems.join('\n'))
+
+const svg = renderMermaidSVG(source, {
+  style,
+  security: 'strict',
+})
+writeFileSync('diagram.svg', svg)
+
+const png = renderMermaidPNG(source, {
+  style,
+  fontDirs: ['./fonts'],
+})
+writeFileSync('diagram.png', png)
+```
+
+## Which font value wins
+
+For `renderMermaidSVG`, font selection follows this precedence, from strongest
+to weakest:
+
+1. The render call's explicit `font` option.
+2. Mermaid `fontFamily` configuration.
+3. Mermaid `themeVariables.fontFamily` configuration.
+4. The resolved Style stack's `font` field.
+5. The default, Inter.
+
+`renderMermaidPNG` accepts the same shared `font` option and precedence as SVG.
+`fontDirs` makes faces available to the rasterizer but does not choose the
+family.
+
+Within a Style stack, later entries win. For example, `[style, 'dracula']`
+keeps the inline/file-loaded Style's font because `dracula` is a palette-only
+Style; a later Style that defines `font` would replace it. A file's `name`
+field does not register it automatically — give it a canonical `look:` or
+`palette:` name and call `registerStyle(style)` before using that identity in a
+library stack.
+
+`validateStyleSpec` checks that `font` is a string. It cannot prove that the
+family is installed, present under `fontDirs`, or available to a browser.
+
+## Resolution by output surface
+
+| Surface | Where the face comes from | Custom-font control |
+|---|---|---|
+| SVG library/CLI | Browser, viewing application, or host-page CSS | `font`, `embedFontImport`, `security` |
+| PNG library/CLI | Bundled faces, `fontDirs`, optionally OS fonts | `font`, `fontDirs`, `loadSystemFonts` / `--system-fonts` |
+| Live editor | Faces available to the editor page and browser | Font picker; no `fontDirs` |
+| Local MCP `render_png` | Bundled faces, `fontDirs`, optionally OS fonts | `fontDirs`, `loadSystemFonts` |
+| Hosted MCP `render_png` | Faces bundled into the Worker | No filesystem font input; use local MCP/library/CLI for custom directories |
+| ASCII, Unicode, JSON layout | Terminal/layout output has no font face | Style fonts do not apply |
+
+### SVG
+
+SVG output always declares the selected family through the root `--font` CSS
+custom property and a `font-family` rule. The SVG renderer does not read
+`fontDirs`.
+
+By default, a single plain family name such as `Acme Sans` produces a Google
+Fonts `@import`. Class and ER diagrams can also import JetBrains Mono for their
+monospace labels. Set `embedFontImport: false`, or use `security: 'strict'`, to
+omit all of those requests while keeping the family declaration:
+
+```ts
+const svg = renderMermaidSVG(source, {
+  style: { font: 'Acme Sans' },
+  embedFontImport: false,
+})
+```
+
+CSS variable references and family stacks are declared as-is and do not
+produce an import for the selected family:
+
+```ts
+renderMermaidSVG(source, {
+  style: { font: "'Acme Sans', Inter, system-ui" },
+})
+
+renderMermaidSVG(source, {
+  font: 'var(--brand-font, Inter)',
+})
+```
+
+The class/ER JetBrains Mono import still applies unless `embedFontImport` is
+false or strict security is enabled.
+
+If the selected family is unavailable when the SVG is viewed, normal CSS
+fallback applies. A family stack makes that fallback explicit.
+
+Raw SVG declares the family through `var(--font, ...)`. Some static SVG
+rasterizers, including resvg and librsvg, do not resolve CSS custom properties.
+Use `renderMermaidPNG` for Agentic Mermaid's built-in workaround, or resolve
+the font variable to a concrete `font-family` before feeding raw SVG to another
+static rasterizer.
+
+### Host-page and browser fonts
+
+An inline SVG can use a face registered by its host document. A stylesheet can
+map an installed face:
+
+```css
+@font-face {
+  font-family: "Acme Sans";
+  src: local("Acme Sans Regular"), local("AcmeSans-Regular");
+  font-weight: 400;
+}
+```
+
+Browser applications can also register bytes selected by the user:
+
+```ts
+const face = new FontFace('Acme Sans', await file.arrayBuffer(), {
+  weight: '400',
+})
+await face.load()
+document.fonts.add(face)
+await document.fonts.load('400 14px "Acme Sans"')
+```
+
+Register one `FontFace` or `@font-face` rule per required weight, or accept the
+browser's synthesized/fallback face for weights that are missing.
+
+Register the face in the same document that displays the SVG, and wait for it
+before displaying or raster-capturing the result. A raw SVG export still only
+declares the family; it does not serialize a dynamically registered `FontFace`.
+The public live editor can use faces already available to its page/browser,
+but it has no filesystem `fontDirs` option or arbitrary font-file input.
+
+### PNG
+
+`renderMermaidPNG` renders offline with `@resvg/resvg-js`. It loads:
+
+1. The bundled Inter faces used by the text-metrics model.
+2. DejaVu Sans as a per-glyph fallback for symbols Inter lacks.
+3. The bundled faces referenced by built-in Styles: Caveat, EB Garamond,
+   Architects Daughter, and Share Tech Mono.
+4. Any directories supplied through `fontDirs`.
+5. OS-installed fonts only when `loadSystemFonts: true` is requested.
+
+The CLI equivalents are `--font-dirs <dir[,dir...]>` and `--system-fonts`.
+Prefer a dedicated `fontDirs` directory when reproducible output matters.
+System-font loading makes the result depend on the machine's installed faces.
+
+The family stored inside the font file must match the intended family token in
+the Style's `font` value — normally the first family in its stack. Supply the
+weights the diagram uses; Agentic Mermaid commonly emits 400, 500, 600, and
+700. If an unbundled requested family cannot be resolved, PNG rasterization
+uses Inter, with DejaVu available for per-glyph fallback.
+
+## Diagnostics and layout limits
+
+`PNG_FONT_COVERAGE` warns when no loaded face contains a character, such as a
+CJK or emoji code point. It is a glyph-coverage check, not a family-presence
+check. If `Acme Sans` is missing but Inter covers every Latin character, the
+render can fall back without a coverage warning. Confirm custom-family output
+visually or with a font-specific render fixture.
+
+Diagram geometry uses the deterministic proportional measurement contract
+recorded in `TEXT_MEASUREMENT_CONTRACT`; it never reads ambient system-font
+state. Every continuous painted text advance—bundled, monospace, or custom—gets
+SVG `textLength` with `lengthAdjust="spacingAndGlyphs"`, because loading a font
+resource does not calibrate its metrics to the layout estimator. Independently
+positioned multiline tspans are fitted per line, while nested formatting
+contributes inherited size, weight, and tracking to that line's width. Explicit
+emitter-owned `textLength` remains authoritative. Native and browser PNG consume
+the same secured SVG, so a materially wider face cannot silently overflow its
+measured box. The tradeoff is explicit: unusually wide or narrow glyphs may be
+horizontally fitted rather than changing deterministic layout. Test long labels
+across target families for visual quality, especially for extreme proportions.
+
+## Troubleshooting
+
+**The custom family is not visible in PNG.** Check the font's internal family
+name, include the directory through `fontDirs`, supply the required weights,
+and make sure Mermaid `fontFamily` configuration in the source is not
+overriding the Style.
+
+**The SVG requests a font from the network.** Render with
+`security: 'strict'` or `embedFontImport: false`.
+
+**The SVG looks different in another viewer.** The other environment did not
+resolve the same family or selected a different fallback. Use a deliberate
+family stack and make the required face available to that viewer.
+
+**PNG warns about CJK or emoji.** Add a face covering those code points through
+`fontDirs`, or opt into `loadSystemFonts` when machine-dependent output is
+acceptable.
+
+## Related documentation
+
+- [Authoring styles](./style-authoring.md) — Style fields, stacks, registration,
+  validation, and the quality rubric.
+- [Custom style cookbook](./custom-style-cookbook.md) — complete JSON examples
+  and screenshots.
+- [API reference](./api.md) — `RenderOptions` and `PngOptions`.
+- [Security posture](../SECURITY.md) — strict SVG and external-reference
+  guarantees.
+- [PNG determinism](./quality.md#png-determinism) — bundled fonts and the
+  reproducibility tradeoff of system fonts.
+- [Bundled font inventory](../assets/fonts/FONT-LICENSES.md) — the faces shipped
+  with the package.

package/docs/custom-style-cookbook.md

@@ -26,6 +26,129 @@ const problems = validateStyleSpec(style)
 if (problems.length) throw new Error(problems.join('\n'))
 ```
 
+The `font` field names a family; the output environment still has to provide
+that face. See [Fonts in custom styles](./custom-fonts.md) for SVG behavior,
+PNG `fontDirs`, system fonts, fallbacks, and browser usage.
+
+## Public brand-inspired prototypes — documentation only
+
+These three files are the highest supported non-built-in form of a Style probe:
+version-controlled public `StyleSpec` records with schema validation, executable
+fixtures, deterministic screenshot gates, strict rendering, inspect-only
+constraints, and optional process-local registration. The reviewed image hashes
+are pinned in
+[`eval/style-prototype-evidence/visual-approval.json`](../eval/style-prototype-evidence/visual-approval.json).
+They are not package-owned built-ins, installed BrandPacks, claims of pixel
+equivalence, or endorsements.
+
+### Cupertino-inspired prototype
+
+Complete file:
+[`examples/styles/cupertino-prototype.style.json`](../examples/styles/cupertino-prototype.style.json).
+
+This is an implementation example, not a built-in Style. Agentic Mermaid ships
+the opt-in file but does not register `cupertino`, give it a package-owned
+runtime identity, expose it in a built-in catalog or picker, or retain a
+registered short name. Load the JSON explicitly when you want to study or
+adapt the prototype:
+
+![Documentation-only Cupertino prototype](./assets/style-cookbook/cupertino-prototype.png)
+
+```bash
+am render examples/styles/cupertino-prototype.mmd --format svg \
+  --style examples/styles/cupertino-prototype.style.json \
+  --options '{"shadow":true}' \
+  --output diagram.svg
+```
+
+Library hosts can opt into a reusable name without creating a built-in registry
+identity. Registration is explicit, process-local, and disposable:
+
+```ts
+import { readFileSync } from 'node:fs'
+import { registerStyle, renderMermaidSVG, validateStyleSpec } from 'agentic-mermaid'
+
+const prototype = JSON.parse(
+  readFileSync('examples/styles/cupertino-prototype.style.json', 'utf8'),
+)
+const source = readFileSync('examples/styles/cupertino-prototype.mmd', 'utf8')
+const problems = validateStyleSpec(prototype)
+if (problems.length) throw new Error(problems.join('\n'))
+
+const unregister = registerStyle(prototype)
+try {
+  const svg = renderMermaidSVG(source, {
+    style: 'look:cupertino-prototype',
+    shadow: true,
+  })
+} finally {
+  unregister()
+}
+```
+
+The public `StyleSpec` expresses the prototype's palette, font, weight-based
+role typography, surface-first border policy, padding, geometry, and inspect-only
+contrast/accent-area constraints. Its 10-unit node corners, 26-unit group
+corners, and 16-unit connector bend radius make the intended Cupertino-inspired
+curve discipline directly inspectable; `shadow` remains the shared render option
+supplying elevation. The file still does not claim pixel equivalence with an
+Apple interface: it uses bundled Inter rather than licensed SF Pro, has no
+motion/spring system, and provides no designed dark companion.
+
+Agentic Mermaid is independent of and not affiliated with Apple Inc.;
+“Cupertino” describes the prototype's design inspiration, not an Apple product
+or endorsed implementation.
+
+### Vercel-inspired prototype
+
+Complete file:
+[`examples/styles/vercel-inspired-prototype.style.json`](../examples/styles/vercel-inspired-prototype.style.json).
+
+![Documentation-only Vercel-inspired prototype](./assets/style-cookbook/vercel-inspired-prototype.png)
+
+```bash
+am verify examples/styles/vercel-inspired-prototype.mmd \
+  --style examples/styles/vercel-inspired-prototype.style.json
+am render examples/styles/vercel-inspired-prototype.mmd --format svg \
+  --style examples/styles/vercel-inspired-prototype.style.json > diagram.svg
+```
+
+This static prototype uses the public palette and role records for dark surfaces,
+hairlines, compact typography, and restrained geometry. Its executable XYChart
+fixture exercises `bar-0` and `line-0` category bindings through named semantic
+slots; contrast and accent-area policy remains inspect-only. It deliberately
+does not imitate Geist assets, Vercel motion, live application chrome, or a
+complete product design system.
+
+Agentic Mermaid is independent of and not affiliated with Vercel Inc.;
+“Vercel-inspired” describes visual research, not a Vercel product or endorsed
+implementation.
+
+### Cloudflare Workers-inspired prototype
+
+Complete file:
+[`examples/styles/cloudflare-workers-inspired-prototype.style.json`](../examples/styles/cloudflare-workers-inspired-prototype.style.json).
+
+![Documentation-only Cloudflare Workers-inspired prototype](./assets/style-cookbook/cloudflare-workers-inspired-prototype.png)
+
+```bash
+am verify examples/styles/cloudflare-workers-inspired-prototype.mmd \
+  --style examples/styles/cloudflare-workers-inspired-prototype.style.json
+am render examples/styles/cloudflare-workers-inspired-prototype.mmd --format svg \
+  --style examples/styles/cloudflare-workers-inspired-prototype.style.json > diagram.svg
+```
+
+This static prototype combines warm surface tokens, sans/mono role typography,
+Gantt section-category bindings, and visible `outline`/`pattern` cues. The cues
+survive no-color terminal projection where that family supports them; contrast
+and accent-area rules diagnose without repainting. It does not reproduce
+Cloudflare application chrome, motion, tinted multi-layer shadow systems, or a
+complete Workers design system.
+
+Agentic Mermaid is independent of and not affiliated with Cloudflare, Inc.;
+“Cloudflare Workers-inspired” describes visual research, not a Cloudflare
+product or endorsed implementation.
+
 ## Transit route map
 
 Complete file:
@@ -43,7 +166,7 @@ Use it when you want to test whether a style keeps connectors readable:
 ```json
 {
   "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
-  "name": "transit-route-map",
+  "name": "look:transit-route-map",
   "colors": {
     "bg": "#fbfbf8",
     "fg": "#171923",
@@ -53,8 +176,7 @@ Use it when you want to test whether a style keeps connectors readable:
   },
   "font": "DejaVu Sans",
   "stroke": "crisp",
-  "strokeWidth": 4,
-  "fill": "none"
+  "strokeWidth": 4
 }
 ```
 
@@ -66,8 +188,8 @@ Complete file:
 ![Mid-century report custom style](./assets/style-cookbook/mid-century-report.png)
 
 This is the easiest uncovered cluster to teach with today's StyleSpec. It is
-mostly palette, fill, typography, and page treatment. No new backend capability
-is needed.
+mostly palette, typography, and page treatment. No new backend capability is
+needed.
 
 Use it when you want a report figure with visible section bands and square
 technical connectors:
@@ -75,7 +197,7 @@ technical connectors:
 ```json
 {
   "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
-  "name": "mid-century-report",
+  "name": "look:mid-century-report",
   "colors": {
     "bg": "#f4ead8",
     "fg": "#24211d",
@@ -85,8 +207,7 @@ technical connectors:
   },
   "font": "DejaVu Sans",
   "stroke": "crisp",
-  "strokeWidth": 1.6,
-  "fill": "solid"
+  "strokeWidth": 1.6
 }
 ```
 
@@ -106,7 +227,7 @@ Use it when you need a dark page style that still keeps labels readable:
 ```json
 {
   "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
-  "name": "star-chart-atlas",
+  "name": "look:star-chart-atlas",
   "colors": {
     "bg": "#0b1026",
     "fg": "#ece4c4",

package/docs/diagram-families.md

@@ -2,22 +2,9 @@
 
 Agentic Mermaid supports Mermaid's common diagram families through a split pipeline: parse source, layout typed structures, render SVG/PNG/ASCII, and verify structural warnings.
 
-## Capability matrix
-
-| Family | Header(s) | Render | Structured mutation | Notes |
-|---|---|---|---|---|
-| Flowchart | `flowchart`, `graph` | SVG/PNG/ASCII | ✓ | 6 graph ops; narrow with `asFlowchart`. |
-| State | `stateDiagram-v2` | SVG/PNG/ASCII | ✓ | Dedicated `StateBody` (BUILD-19): narrow with `asState`, 8 state-shaped ops. `asFlowchart` returns null. |
-| Sequence | `sequenceDiagram` | SVG/PNG/ASCII | structured (5 ops) | Notes/alt/loop bodies are segment-preserving; un-segmentable syntax falls back to opaque. |
-| Timeline | `timeline` | SVG/PNG/ASCII | ✓ | Supports sections, periods, events, title changes. |
-| Class | `classDiagram` | SVG/PNG/ASCII | ✓ | Classes, members, relations, notes. |
-| ER | `erDiagram` | SVG/PNG/ASCII | ✓ | Entities, attributes, relations. |
-| Journey | `journey` | SVG/PNG/ASCII | structured (10 ops) | `asJourney` narrows documented Journey syntax: title, accTitle/accDescr, sections, scored tasks, and actors. |
-| XY chart | `xychart`, `xychart-beta` | SVG/PNG/ASCII | structured (8 ops) | Vertical/horizontal bar/line/mixed charts; modeled subset is structurally mutable via `asXyChart`. |
-| Pie | `pie` | SVG/PNG/ASCII | structured (7 ops) | `asPie` narrows title/showData/slices; malformed entries and accTitle/accDescr stay opaque. |
-| Quadrant | `quadrantChart` | SVG/PNG/ASCII | structured (7 ops) | `asQuadrant` narrows title/axes/quadrant labels/points; styling and out-of-range coords stay opaque. |
-| Architecture | `architecture-beta` | SVG/PNG/ASCII | structured (10 ops) | `asArchitecture` narrows the modeled subset (groups/services/junctions/edges); the `{group}` boundary modifier and accTitle/accDescr stay opaque. |
-| Gantt | `gantt` | SVG/PNG/ASCII | structured (9 ops) | `asGantt` narrows title/sections/tasks; calendar directives, `click` lines, and comments ride along verbatim as opaque segments. Deterministic: the today marker draws only from a caller-supplied `ganttToday`. See [design/families/gantt.md](./design/families/gantt.md). |
+## Capability authority
+
+The checked roster and per-family capability states are generated from `FamilyDescriptor` in the [Section A capability report](./project/section-a-capability-report.md). Agents can discover the live roster and operation shapes through `am capabilities --json`; its compact Section A summary links to the exhaustive audit. Library and Code Mode callers can use `describeOps(family)` for the exact mutation schema. This guide keeps examples and family-specific caveats, not a second inventory.
 
 Opaque fallback does not mean unsupported: those bodies parse, render, verify, and round-trip losslessly, but agents should edit preserved source deliberately instead of calling `mutate`.
 
@@ -39,7 +26,7 @@ stateDiagram-v2
   Idle --> Running
 ```
 
-State diagrams own a dedicated `StateBody` (BUILD-19): narrow with `asState` and apply the 8 typed ops (`add_state`, `remove_state`, `rename_state`, `set_state_label`, `add_transition`, `remove_transition`, `set_transition_label`, `make_composite`). The modeled subset is simple states, transitions, `[*]` start/end pseudostates, nestable composite blocks, and `direction`. Anything outside it — `<<fork>>`/`<<choice>>`/`<<join>>`, history states, concurrency `--`, notes, `classDef`/`class`/`:::` styling — falls back to a lossless opaque body and stays source-level. Verify still runs the full Tier 1 + Tier 2 geometric path by projecting the body to a graph.
+State diagrams own a dedicated `StateBody`: narrow with `asState`. States, transitions, start/end, composites, concurrency regions, fork/join/choice and history pseudostates, notes, declarations, direction, and paint are modeled. Use `describeOps('state')` for the current mutation schema; malformed or otherwise unmodeled syntax falls back losslessly and stays source-level. Verify runs the full Tier 1 + Tier 2 geometric path by projecting the body to a graph.
 
 ## Sequence
 
@@ -51,7 +38,7 @@ sequenceDiagram
   API-->>User: Session
 ```
 
-Simple participants/messages are structured. Rich Mermaid sequence blocks such as notes, `alt`, `loop`, and activation syntax are preserved as opaque source when not modeled.
+Participants and messages are structured. Rich statements such as notes, `alt`, `loop`, and activation syntax remain ordered verbatim segments while participant/message operations stay live; only un-segmentable input falls back to a whole opaque body.
 
 ## Timeline
 
@@ -98,7 +85,7 @@ journey
     Pay: 3: Customer, Gateway
 ```
 
-Journey diagrams narrow via `asJourney` and expose 10 structured ops (sections, tasks, scores, actors). Documented Mermaid accessibility directives (`accTitle`, inline `accDescr`, and block `accDescr { ... }`) stay structured and round-trip through canonical serialization. Malformed or unknown Journey syntax falls back to a lossless opaque body.
+Journey diagrams narrow via `asJourney`; discover the exact section, task, score, actor, ordering, and accessibility operation schema with `describeOps('journey')`. Documented Mermaid accessibility directives (`accTitle`, inline `accDescr`, and block `accDescr { ... }`) stay structured and round-trip through canonical serialization. Malformed or unknown Journey syntax falls back to a lossless opaque body.
 
 SVG rendering uses Mermaid's left-to-right Journey metaphor rather than the older Agentic card layout: sections span task columns, actors appear in a left legend, per-task actor dots show participation, and scores map to sentiment markers on a progression baseline. Mermaid `journey` config fields for actor colors, section fills/text colors, task/title fonts, task spacing, and actor label width are honored. Agentic Mermaid `style` and palette colors also reach Journey-specific surfaces such as section spans, actor dots, score markers, and the baseline.
 
@@ -112,7 +99,7 @@ xychart-beta
   line [50, 180, 420]
 ```
 
-The modeled subset (bare title, named/categorical/range axes, bar/line series with finite values) is structurally mutable: narrow with `asXyChart` and apply the 8 typed ops (`set_title`, `set_x_axis`, `set_y_axis`, `add_series`, `remove_series`, `set_series_values`, `set_series_name`, `reorder_series`). Quoted text, multi-statement `;` lines, and accTitle/accDescr fall back to opaque and stay source-level. See [`design/families/xychart.md`](./design/families/xychart.md) for compatibility details and layout notes.
+The modeled title, axes, orientation, and bar/line series are structurally mutable through `asXyChart`; use `describeOps('xychart')` for the exact schema. Unmodeled or malformed syntax falls back losslessly and stays source-level. See [`design/families/xychart.md`](./design/families/xychart.md) for compatibility details and layout notes.
 
 ## Pie
 
@@ -124,7 +111,7 @@ pie showData
   "Rats" : 15
 ```
 
-Pie charts accept the `pie` header with optional `showData`, an optional `title`, and `"label" : value` entries with positive numeric values. Slices render clockwise in source order. `showData` adds the raw value beside each legend label; the legend always shows the computed percentage. Malformed entries (negative/zero values, missing colon, unquoted labels) fall back to a lossless opaque body — never silently dropped — and the renderer still surfaces the loud error at render time. The ASCII renderer draws a proportional bar list. Pie is structured-when-narrowed: `asPie` exposes 7 ops (`set_title`, `set_show_data`, `add_slice`, `remove_slice`, `rename_slice`, `set_slice_value`, `reorder_slice`); slices are addressed by their unique label.
+Pie charts accept the `pie` header with optional `showData`, an optional `title`, and `"label" : value` entries with positive numeric values. Slices render clockwise in source order. `showData` adds the raw value beside each legend label; the legend always shows the computed percentage. Malformed entries (negative/zero values, missing colon, unquoted labels) fall back to a lossless opaque body — never silently dropped — and the renderer still surfaces the loud error at render time. The ASCII renderer draws a proportional bar list. Pie is structured when narrowed through `asPie`; slices are addressed by their unique label. The operation schema is generated from the registry rather than duplicated here.
 
 ## Quadrant
 
@@ -141,7 +128,20 @@ quadrantChart
   Campaign B: [0.45, 0.23]
 ```
 
-Quadrant charts accept the `quadrantChart` header, an optional `title`, `x-axis <left> --> <right>` and `y-axis <bottom> --> <top>` axis labels (the far side is optional), four `quadrant-1..quadrant-4 <label>` region labels, and `<Label>: [x, y]` points with coordinates in `[0, 1]`. Quadrant numbering follows Mermaid core: **1 = top-right, 2 = top-left, 3 = bottom-left, 4 = bottom-right**. The SVG renderer draws a square plot split into four theme-tinted quadrants with the points as circles; the ASCII renderer draws a bordered grid with a coordinate legend. Official point style metadata (`radius`, `color`, `stroke-color`, `stroke-width`) and `classDef` lines are accepted for render compatibility but are not modeled for typed mutation; the agent path preserves those charts as opaque source and emits `UNSUPPORTED_SYNTAX` as an advisory warning. Malformed lines — out-of-range/non-numeric coordinates, missing brackets, duplicate point labels, and unknown point style metadata — fall back to a lossless opaque body, never silently dropped, and the renderer still surfaces the loud error at render time. Quadrant is structured-when-narrowed: `asQuadrant` exposes 7 ops (`set_title`, `set_axis_labels`, `set_quadrant_label`, `add_point`, `remove_point`, `move_point`, `rename_point`); points are addressed by their unique label and coordinates stay in `[0, 1]`.
+Quadrant charts accept the `quadrantChart` header, an optional `title`, `x-axis <left> --> <right>` and `y-axis <bottom> --> <top>` axis labels (the far side is optional), four `quadrant-1..quadrant-4 <label>` region labels, and `<Label>: [x, y]` points with coordinates in `[0, 1]`. Quadrant numbering follows Mermaid core: **1 = top-right, 2 = top-left, 3 = bottom-left, 4 = bottom-right**. The SVG renderer draws a square plot split into four theme-tinted quadrants with the points as circles; the ASCII renderer draws a bordered grid with a coordinate legend. Official point style metadata (`radius`, `color`, `stroke-color`, `stroke-width`), `classDef` lines, and class assignments are modeled for rendering and typed mutation. Malformed lines — out-of-range/non-numeric coordinates, missing brackets, duplicate point labels, and unknown point style metadata — fall back to a lossless opaque body, never silently dropped, and the renderer still surfaces the loud error at render time. Quadrant is structured when narrowed through `asQuadrant`; points are addressed by their unique label and coordinates stay in `[0, 1]`. The operation schema is generated from the registry rather than duplicated here.
+
+## Radar
+
+```mermaid
+radar-beta
+  title Skills
+  axis speed["Speed"], power["Power"], range["Range"]
+  curve now["Current"]{4, 3, 5}
+  curve goal["Target"]{5, 5, 4}
+  max 5
+```
+
+Radar (spider) chart — multivariate profiles compared across equi-angular axes from a shared center; one closed translucent area per entity. The `radar-beta` header takes an optional `title`, `axis <id>["Label"], …` declarations, one `curve <id>["Label"]{v1, v2, …}` per entity (one value per axis, in axis order), and optional `max`/`min`/config lines. The SVG renderer draws the axis spokes, concentric grid, and per-curve polygons; the ASCII renderer draws a grouped proportional-bar table like pie. Malformed lines fall back to a lossless opaque body, never silently dropped. Radar is structured when narrowed through `asRadar`; axes and curves are addressed by their unique id. The operation schema is generated from the registry rather than duplicated here.
 
 ## Gantt
 
@@ -158,7 +158,32 @@ gantt
     another task    :24d
 ```
 
-Gantt charts accept the `gantt` header, `title`, calendar directives (`dateFormat`, `axisFormat`, `tickInterval`, `inclusiveEndDates`, `topAxis`, multiple `excludes`/`includes` lines, `weekend friday|saturday`, `weekday <day>`, `todayMarker`), `section` lines, and task lines `Label :[tags,] [id,] [start,] end` where tags are `active`/`done`/`crit`/`milestone`/`vert`, start is a date or `after id…`, and end is a date, a duration token (`ms s m h d w M y`, decimals allowed), or `until id…`. Dependencies resolve in a pure scheduler ([design/families/gantt.md](./design/families/gantt.md)): `after` starts at the latest referenced end, `until` ends at the earliest referenced start, working durations extend over excluded days, `includes` overrides `excludes`, and dependency cycles / unknown references / invalid dates are named structured errors (`GANTT_*`), never wall-clock fallbacks. Rendering is deterministic: the `todayMarker` draws only when the caller passes `ganttToday` (a date in the diagram's `dateFormat`), and `todayMarker off` always wins. `displayMode: compact` (frontmatter or `config.gantt`) packs non-overlapping tasks of a section into shared rows; `vert` markers draw a full-height line without consuming a task row. `click … href` is sanitized under strict security and `click … call` is parsed but never executed. Gantt is structured-when-narrowed AND segment-preserving: `asGantt` exposes 9 ops (`set_title`, `add_section`, `rename_section`, `remove_section`, `add_task`, `remove_task`, `rename_task`, `set_task_status`, `set_task_dates`) on title/sections/tasks while calendar directives, click lines, and comments ride along verbatim as opaque segments; duplicate task ids or an unclosed `accDescr` block fall back to a lossless whole-opaque body.
+Gantt charts accept the `gantt` header, `title`, calendar directives (`dateFormat`, `axisFormat`, `tickInterval`, `inclusiveEndDates`, `topAxis`, multiple `excludes`/`includes` lines, `weekend friday|saturday`, `weekday <day>`, `todayMarker`), `section` lines, and task lines `Label :[tags,] [id,] [start,] end` where tags are `active`/`done`/`crit`/`milestone`/`vert`, start is a date or `after id…`, and end is a date, a duration token (`ms s m h d w M y`, decimals allowed), or `until id…`. Dependencies resolve in a pure scheduler ([design/families/gantt.md](./design/families/gantt.md)): `after` starts at the latest referenced end, `until` ends at the earliest referenced start, working durations extend over excluded days, `includes` overrides `excludes`, and dependency cycles / unknown references / invalid dates are named structured errors (`GANTT_*`), never wall-clock fallbacks. Rendering is deterministic: the `todayMarker` draws only when the caller passes `ganttToday` (a date in the diagram's `dateFormat`), and `todayMarker off` always wins. `displayMode: compact` (frontmatter or `config.gantt`) packs non-overlapping tasks of a section into shared rows; `vert` markers draw a full-height line without consuming a task row. `click … href` is sanitized under strict security and `click … call` is parsed but never executed. Gantt is structured when narrowed and segment-preserving: `asGantt` edits title/sections/tasks while calendar directives, click lines, and comments ride along verbatim as opaque segments; duplicate task ids or an unclosed `accDescr` block fall back to a lossless whole-opaque body.
+
+## Mindmap
+
+```mermaid
+mindmap
+  root((Product))
+    Research
+      Evidence
+    Delivery
+```
+
+Mindmap uses indentation for parentage and supports Mermaid node shapes, `::icon(...)`, `:::class`, accessibility directives, deterministic tree layout, and structured mutation through `asMindmap`. Duplicate semantic ids are rejected. Use `describeOps('mindmap')` for the exact operation schema; see [`design/families/mindmap.md`](./design/families/mindmap.md).
+
+## GitGraph
+
+```mermaid
+gitGraph
+  commit id:"base"
+  branch feature
+  commit id:"work"
+  checkout main
+  merge feature id:"merge"
+```
+
+GitGraph replays commits and branch movement in source order and exposes structured mutation through `asGitGraph`. Generated ids are deterministic `c<N>` values and duplicate custom ids are rejected. Use `describeOps('gitgraph')` for the exact operation schema; see [`design/families/gitgraph.md`](./design/families/gitgraph.md).
 
 ## Architecture