agentic-mermaid 0.1.1 → 0.2.0

package/AGENT_NATIVE.md

@@ -26,7 +26,7 @@ D2 has a better language than Mermaid. The Beautiful Mermaid renderer foundation
 
 1. **Deterministic layout** — same input → structurally identical layout JSON across runs with the same ELK version. (Not "byte-identical SVG across versions" — that's a stronger claim that needs a forked ELK to actually deliver.)
 2. **Verifiable rendering** — structured "did this render cleanly?" check. Structural warnings (anchors, bounds, emptiness, group containment) are reliable; metric warnings (label fit, overlap) are best-effort because they depend on font-measurement parity with ELK.
-3. **Round-trippable** — `parseMermaid` produces a `ValidDiagram` that carries source needed to re-emit the diagram. For flowchart/state, sequence, timeline, class, ER, journey, architecture, xychart, pie, quadrant, and gantt, `mutate` operates on structured bodies; for opaque-fallback bodies, preserved source is the round-trip mechanism.
+3. **Round-trippable** — `parseRegisteredMermaid` produces a `ValidDiagram` that carries source needed to re-emit the diagram. For flowchart/state, sequence, timeline, class, ER, journey, architecture, xychart, pie, quadrant, gantt, mindmap, gitgraph, and radar, `mutate` operates on structured bodies; for opaque-fallback bodies, preserved source is the round-trip mechanism.
 
 (Composition — `@include`, templates, layered scenarios — was the fourth in earlier drafts and is deferred. Agents do not currently reach for composition; they paste and edit. Add when evidence demands.)
 
@@ -34,24 +34,9 @@ D2 has a better language than Mermaid. The Beautiful Mermaid renderer foundation
 
 ## Honest scope
 
-What the current Agentic Mermaid surface delivers and what it doesn't:
+The checked family roster, capability states, edit policies, narrowers, and mutation operations are generated from `FamilyDescriptor`: read [`docs/project/section-a-capability-report.md`](./docs/project/section-a-capability-report.md) or `am capabilities --json`, and use `describeOps(family)` for exact operation schemas. This rationale deliberately does not copy that live inventory.
 
-| Family | Parse / verify / render / round-trip | Structured mutation |
-|---|---|---|
-| Flowchart | Full | ✅ 6 ops |
-| State | Structured round-trip for the modeled subset (simple states/transitions/`[*]`/composites/direction); `<<fork>>`/`<<choice>>`/notes/`--`/`classDef` fall back to opaque losslessly | 8 ops via `asState` (BUILD-19) |
-| Sequence | Structured-with-segments (BUILD-18): participant/message ops stay live while Note/alt/loop/par/activate/autonumber/title ride along verbatim as opaque-block segments; only un-segmentable input (unbalanced `end`) falls back to whole-body opaque | ✅ 5 ops when structured |
-| Timeline | Full | ✅ 10 ops |
-| Class | Full | ✅ 10 ops |
-| ER | Full | ✅ 7 ops |
-| Journey | Full structured round-trip (title/sections/tasks) | 10 ops via `asJourney` (BUILD-15 pilot) |
-| Architecture | Structured round-trip for the modeled subset (groups/services/junctions/edges); `{group}` boundary edges + accTitle/accDescr fall back to opaque losslessly | 10 ops via `asArchitecture` (BUILD-17) |
-| XY chart | Structured round-trip for the modeled subset (title/axes/series); quoted text, `;` lines, accTitle/accDescr fall back to opaque losslessly | 8 ops via `asXyChart` (BUILD-16) |
-| Pie | Structured round-trip (title/showData/slices); accTitle/accDescr + malformed entries fall back to opaque losslessly | 7 ops via `asPie` |
-| Quadrant | Structured round-trip (title/axes/quadrant labels/points); styling + out-of-range coords fall back to opaque losslessly | 7 ops via `asQuadrant` |
-| Gantt | Structured-with-segments from day one ([`docs/design/families/gantt.md`](./docs/design/families/gantt.md)): title/section/task ops stay live while calendar directives, click lines, and comments ride along verbatim as opaque-block segments; duplicate task ids / unclosed accDescr fall back to whole-body opaque losslessly. Rendering is deterministic — the today marker needs a caller-supplied clock (`ganttToday`), never the wall clock | 9 ops via `asGantt` |
-
-The implication: for any opaque fallback, the agent's tool surface is *parse → verify → render → serialize*, not *parse → mutate → verify → serialize*. Cross-cutting edits on those bodies happen at the preserved source level (`body.source` for opaque bodies), not at the typed mutation layer. Code Mode opportunity #1 covers this for the cases where it matters.
+The generated edit policy decides where typed mutation is available. For an opaque fallback, the agent's tool surface is *parse → verify → render → serialize*, not *parse → mutate → verify → serialize*. Cross-cutting edits on those bodies happen at the preserved source level (`body.source` for opaque bodies), not at the typed mutation layer. Code Mode opportunity #1 covers this for the cases where it matters.
 
 ---
 
@@ -128,6 +113,7 @@ Correctly detect what they claim to detect, but the occurrence may be intentiona
 | `ROUTE_HITCH` | warning | An edge bends although a direct lane for it is provably clear (route-contract tripwire) |
 | `ROUTE_UNEXPLAINED_BEND` | warning | An edge contains a diagonal segment under orthogonal routing (route-contract tripwire) |
 | `ROUTE_LABEL_ON_SHARED_TRUNK` | warning | A label pill sits on a line segment another edge shares (route-contract tripwire) |
+| `ROUTE_SELF_LOOP_OCCUPANCY` | warning | A self-loop certificate has invalid side/boundary geometry or collides with another loop/label |
 | `ROUTE_CONTAINER_MISANCHOR` | warning | A container edge does not terminate on the container border (route-contract tripwire) |
 | `ROUTE_SHAPE_MISANCHOR` | warning | An endpoint is off the rendered shape boundary (route-contract tripwire) |
 | `ROUTE_STALE_AFTER_NODE_MOVE` | warning | An endpoint detached from its node entirely (route-contract tripwire) |
@@ -136,7 +122,7 @@ Codes are the contract surface agents reason about. Emitting an undocumented cod
 
 ### Tier 3 — Lint (advisory)
 
-Tier 3 warnings are family-specific quality hints for "common LLM mistakes" that parse and render but are probably not what the agent intended. They never flip `verify.ok`; callers decide whether to fail a style/quality gate.
+Tier 3 warnings are family-specific quality hints for "common LLM mistakes" that parse and render but are probably not what the agent intended. Advisory lint never flips `verify.ok`; an explicitly authored Brand constraint with `action: "error"` emits `BRAND_CONSTRAINT_ERROR` and does flip it.
 
 | Code | Severity | Description |
 |---|---|---|
@@ -147,8 +133,11 @@ Tier 3 warnings are family-specific quality hints for "common LLM mistakes" that
 | `UNSUPPORTED_SYNTAX` | warning | The source uses Mermaid syntax that is preserved losslessly but not fully modeled by local structured mutation/render semantics (for example flowchart edge IDs, edge metadata, click/href directives, or markdown strings). Payload includes `syntax`, optional `line`, and `message`. |
 | `CONTENT_DROPPED_ON_ROUNDTRIP` | warning | The structured `{nodes, edges, groups}` tally changed across a parse → serialize → re-parse cycle, so canonical serialization is silently dropping or duplicating content even though the bytes may re-parse (payload carries `before`/`after` counts). The faithfulness analogue of `COMMENT_DROPPED` — "100% parse success is not faithfulness". Runs on every verify, for every family; opaque bodies (byte-verbatim) are exempt. |
 | `INEFFECTIVE_CONFIG` | warning | A Mermaid config field was accepted (for config-shape compatibility) but has no effect on this family's geometry or paint — e.g. Journey's sequence-era fields (`boxMargin`, `rightAngles`, …). Payload names the `field`. Accepting-and-ignoring silently misleads migrating users; this lint says so. |
+| `LOW_CONTRAST` | warning | A concrete authored paint remains authoritative but misses a measurable contrast threshold against the final resolved opaque background. Payload names the `field`, `foreground`, `background`, measured `ratio`, and required `minimum`; verification diagnoses without repainting authored intent. Transparent output is not measured because its host backdrop is unknown. |
+| `BRAND_CONSTRAINT_WARNING` | warning | A caller-selected inspect-only `contrast`, `accent-area`, or `mono-role` Brand constraint failed or could not be measured. Payload reports the constraint, `measurement`, applicable role/mark, and concrete evidence without repainting or relayout. |
+| `BRAND_CONSTRAINT_ERROR` | error | The same inspect-only Brand constraint contract with `action: "error"`; it preserves authored output but flips `verify.ok` so a caller can enforce its declared brand policy. |
 
-`FamilyPlugin.verify` hooks are wired and run today; built-ins use them for Tier 1 structural warnings for class/ER and the central flowchart verifier emits the initial Tier 3 lint catalogue. Future lint codes should be added deliberately to `WARNING_TIER`, documented here, and covered by doc-sync tests.
+`FamilyDescriptor.verify` hooks are wired and run today; built-ins use them for Tier 1 structural warnings for class/ER and the central flowchart verifier emits the initial Tier 3 lint catalogue. Future lint codes should be added deliberately to `WARNING_TIER`, documented here, and covered by doc-sync tests.
 
 **Branded coordinate types** (`Finite`) prevent NaN / Infinity from reaching the renderer. `toFinite()` is the only constructor; it throws on invalid input.
 
@@ -183,44 +172,31 @@ type DiagramBody =
   | { kind: 'flowchart'; graph: MermaidGraph }
   | StateBody | SequenceBody | TimelineBody | ClassBody | ErBody
   | JourneyBody | ArchitectureBody | XyChartBody | PieBody | QuadrantBody | GanttBody
+  | MindmapBody | GitGraphBody | RadarBody
   | { kind: 'opaque'; family: DiagramKind; source: string }
 
-type MutableValidDiagram =
-  | FlowchartValidDiagram | StateValidDiagram | SequenceValidDiagram
-  | TimelineValidDiagram | ClassValidDiagram | ErValidDiagram
-  | JourneyValidDiagram | ArchitectureValidDiagram | XyChartValidDiagram
-  | PieValidDiagram | QuadrantValidDiagram | GanttValidDiagram
+type MutableValidDiagram = import('agentic-mermaid/agent').MutableValidDiagram
 ```
 
 ```ts
-parseMermaid(source: string):                                Result<ValidDiagram, ParseError[]>
+parseRegisteredMermaid(source: string):                                Result<ValidDiagram, ParseError[]>
 serializeMermaid(d: ValidDiagram):                           string
 synthesizeFromGraph(payload):                                Result<ValidDiagram, ParseError[]>
 createMermaid(kind, opts?):                                  MutableValidDiagram   // empty structured diagram; overloads narrow per kind
 buildMermaid(kind, ops, opts?):                              Result<MutableValidDiagram, MutationError & { opIndex: number }>
-mutate(d: FlowchartValidDiagram, op: FlowchartMutationOp):   Result<FlowchartValidDiagram, MutationError>
-mutate(d: StateValidDiagram,     op: StateMutationOp):       Result<StateValidDiagram, MutationError>
-mutate(d: SequenceValidDiagram,  op: SequenceMutationOp):    Result<SequenceValidDiagram, MutationError>
-mutate(d: TimelineValidDiagram,  op: TimelineMutationOp):    Result<TimelineValidDiagram, MutationError>
-mutate(d: ClassValidDiagram,     op: ClassMutationOp):       Result<ClassValidDiagram, MutationError>
-mutate(d: ErValidDiagram,        op: ErMutationOp):          Result<ErValidDiagram, MutationError>
-mutate(d: JourneyValidDiagram,   op: JourneyMutationOp):     Result<JourneyValidDiagram, MutationError>
-mutate(d: ArchitectureValidDiagram, op: ArchitectureMutationOp): Result<ArchitectureValidDiagram, MutationError>
-mutate(d: XyChartValidDiagram,   op: XyChartMutationOp):     Result<XyChartValidDiagram, MutationError>
-mutate(d: PieValidDiagram,       op: PieMutationOp):         Result<PieValidDiagram, MutationError>
-mutate(d: QuadrantValidDiagram,  op: QuadrantMutationOp):    Result<QuadrantValidDiagram, MutationError>
-mutate(d: GanttValidDiagram,     op: GanttMutationOp):       Result<GanttValidDiagram, MutationError>
-asFlowchart/asState/asSequence/asTimeline/asClass/asEr/asJourney/asArchitecture/asXyChart/asPie/asQuadrant/asGantt(d): narrowed diagram | null
+mutate(d, op):                                               Result<MutableValidDiagram, MutationError>
+// Concrete overloads preserve the narrowed family. Overloads and narrowers are
+// registry-derived; discover them with am capabilities --json and describeOps(family).
 ```
 
-**`mutate` is overloaded by family.** Flowchart/state, simple sequence, timeline, class, ER, journey, architecture, xychart, pie, quadrant, and gantt diagrams have first-class structured editing. Opaque-fallback diagrams are not typed for mutation, so agents get a compile-time/null-narrower stop rather than a lossy edit path.
+**`mutate` is overloaded by family.** A registry-declared narrower returns the family-specific mutable type or `null`; the generated capability entry and `describeOps(family)` own the live operation contract. Opaque-fallback diagrams are not typed for mutation, so agents get a compile-time/null-narrower stop rather than a lossy edit path.
 
 Two contracts:
 
-- `serializeMermaid(parseMermaid(s)) ≡ normalize(s)` for canonical input. For structured families this emits a fresh canonical form; for opaque families it emits preserved source with `meta` re-attached.
-- `parseMermaid(serializeMermaid(d)) ≡ d` for every `d` produced by `parseMermaid` or `mutate`.
+- `serializeMermaid(parseRegisteredMermaid(s)) ≡ normalize(s)` for canonical input. For structured families this emits a fresh canonical form; for opaque families it emits preserved source with `meta` re-attached.
+- `parseRegisteredMermaid(serializeMermaid(d)) ≡ d` for every `d` produced by `parseRegisteredMermaid` or `mutate`.
 
-**Flowchart MutationOp kinds** (6):
+**Flowchart MutationOp kinds** (the authoritative menu is generated from the registry; `shape` fields accept geometry names and documented v11 names/aliases, and edge targets accept authored edge IDs or endpoint forms):
 
 | Kind | Required | Optional | Inverse |
 |---|---|---|---|
@@ -230,73 +206,111 @@ Two contracts:
 | `set_label`   | `target`, `label` | —                 | `set_label(target, prev_label)` |
 | `add_edge`    | `from`, `to`      | `label`, `style`  | `remove_edge(id)` |
 | `remove_edge` | `id`              | —                 | `add_edge(from, to, label, style)` |
+| `set_shape`   | `id`, `shape`     | —                 | `set_shape(id, prev_shape)` |
+| `set_direction` | `direction`     | `subgraph` (sets that subgraph's override; omit = diagram) | `set_direction(prev_direction, subgraph)` |
+| `add_subgraph` | `id`             | `label`, `parent`, `members` (existing nodes MOVED in — the state `make_composite` precedent) | `remove_subgraph(id)` |
+| `remove_subgraph` | `id`          | `removeMembers` (default dissolves the box — members move to the parent scope; `true` deletes member nodes and their edges) | `add_subgraph(...)` |
+| `move_node`   | `id`, `subgraph \| null` (null = top level) | — | `move_node(id, prev_subgraph)` |
+| `define_class` | `name`, `style` (CSS-like pairs, parsed by the parser's own style grammar) | — | `define_class(name, prev_style)` |
+| `set_node_class` | `id`, `className \| null` | —      | `set_node_class(id, prev_class)` |
+| `set_node_style` | `id`, `style \| null` | —          | `set_node_style(id, prev_style)` |
 
-**State MutationOp kinds** (8, BUILD-19 — promoting state from a "parses AS flowchart" projection to a dedicated `StateBody` IR with state-shaped ops and a real `asState` narrower). Modeled grammar: simple states (`state "Label" as id`, `id : Label`), transitions `from --> to [: label]` where `from`/`to` may be the reserved pseudostate `[*]` (source = start, target = end, scoped per composite level), composite blocks `state X { … }` (nestable), and `direction`. Anything else (`<<fork>>`/`<<choice>>`/`<<join>>`, history states, concurrency `--`, notes, `classDef`/`class`/`:::` styling, bare `stateId` lines, hyphenated composite ids) keeps the whole body opaque and round-trips verbatim. `[*]` is contextual, not a state node:
+**State MutationOp kinds** (18, BUILD-19 + the family elevation — promoting state from a "parses AS flowchart" projection to a dedicated `StateBody` IR with state-shaped ops and a real `asState` narrower). Modeled grammar: simple states (`state "Label" as id`, `id : Label`), transitions `from --> to [: label]` where `from`/`to` may be the reserved pseudostate `[*]` (source = start, target = end, scoped per composite level) or a history reference (`[H]`, `Base[H*]`), composite blocks `state X { … }` (nestable), `direction`, pseudostate stereotypes (`state id <<fork|join|choice>>` plus the history forms `<<history>>`/`<<H>>`/`<<deephistory>>`/`<<H*>>`), and notes (`note left|right of X : text`, block form included). Concurrency `--`, `classDef`/`class`/`:::` styling, bare state lines, and hyphenated composite ids are modeled structurally. `[*]` is contextual, not a state node:
 
 | Kind | Required | Optional | Inverse |
 |---|---|---|---|
 | `add_state`            | `id`              | `label`, `parent` (composite) | `remove_state(id)` |
-| `remove_state`         | `id` (refused on a non-empty composite — remove children first) | — | `add_state(...)` |
+| `remove_state`         | `id` (refused on a non-empty composite unless `recursive`) | `recursive` (`true` removes the whole subtree; touching transitions/notes cascade, history refs `X[H]` included) | `add_state(...)` |
 | `rename_state`         | `from`, `to`      | — (rewrites transitions) | `rename_state(to, from)` |
 | `set_state_label`      | `id`, `label \| null` | —             | `set_state_label(id, prev_label)` |
 | `add_transition`       | `from`, `to` (`[*]` allowed) | `label`, `parent` | `remove_transition(from->to)` |
 | `remove_transition`    | `index` or `from`/`to` pair | `parent` | `add_transition(...)` |
 | `set_transition_label` | `label \| null` + (`index` or `from`/`to`) | `parent` | `set_transition_label(..., prev_label)` |
-| `make_composite`       | `id`, `members: string[]` | `label`  | (move members out, remove composite) |
-
-**Sequence MutationOp kinds** (5):
+| `make_composite`       | `id`, `members: string[]` | `label`  | `dissolve_composite(id)` |
+| `set_direction`        | `direction`       | `state` (composite override; omit/null = diagram) | `set_direction(prev, state)` |
+| `move_state`           | `id`, `parent \| null` (null = top level; a simple parent promotes to a composite) | — | `move_state(id, prev_parent)` |
+| `dissolve_composite`   | `id` (hoists children + inner transitions into the parent scope; rejects while transitions/notes still reference it) | — | `make_composite(id, members, label)` |
+| `add_note`             | `target`, `text`  | `side` (`left`/`right`, default `right`) | `remove_note(index)` |
+| `remove_note`          | `index`           | —                 | `add_note(target, side, text)` |
+| `set_note_text`        | `index`, `text`   | —                 | `set_note_text(index, prev_text)` |
+| `define_class`         | `name`, `style`   | —                 | restore previous definition |
+| `set_state_class`      | `id`, `className \| null` | —          | restore previous class |
+| `set_state_style`      | `id`, `style \| null` | —              | restore previous style |
+| `set_transition_style` | selector + `style \| null` | `parent`, `region` | restore previous style |
+
+**Sequence MutationOp kinds** (top-level message indices remain separate from typed fragment-message indices):
 
 | Kind | Required | Optional | Inverse |
 |---|---|---|---|
-| `add_participant`    | `id`                  | `label` | `remove_participant(id)` |
+| `add_participant`    | `id`                  | `label`, `participantKind` (`participant`/`actor`) | `remove_participant(id)` |
 | `remove_participant` | `id`                  | —       | `add_participant(id, label)` |
-| `add_message`        | `from`, `to`, `text`  | `style` (sync/async) | `remove_message(index)` |
+| `add_message`        | `from`, `to`, `text`  | `style` (sync/async), insert `index` (omitted = append) | `remove_message(index)` |
 | `remove_message`     | `index`               | —       | `add_message(...)` |
 | `set_message_text`   | `index`, `text`       | —       | `set_message_text(index, prev_text)` |
+| `move_message`       | `from`, `to` (source order IS the interaction timeline, so reorder is a first-class edit) | — | `move_message(to, from)` |
+| `set_participant_label` | `id`, `label`      | —       | `set_participant_label(id, prev_label)` |
+| `add_fragment` / `remove_fragment` / `set_fragment_label` | fragment kind or index | label/index | matching inverse |
+| `add_fragment_branch` / `set_fragment_branch_label` | fragment/branch indices | label | matching inverse |
+| `add_fragment_message` / `remove_fragment_message` / `set_fragment_message_text` | fragment index + message fields/index | branch/index/style | matching inverse |
 
-**Timeline MutationOp kinds** (10):
+**Timeline MutationOp kinds** (15 — the journey conventions from PR #141: `index?` on add ops is an insert position, move ops take the insert position after removal, and errors name the legal range):
 
 | Kind | Required | Inverse |
 |---|---|---|
 | `set_title`          | `title \| null`                                           | `set_title(prev_title)` |
-| `add_section`        | `label`                                                   | `remove_section(index)` |
+| `add_section`        | `label` (+ optional insert `index`)                       | `remove_section(index)` |
 | `remove_section`     | `index`                                                   | `add_section(label)` |
 | `set_section_label`  | `index`, `label`                                          | `set_section_label(index, prev_label)` |
-| `add_period`         | `sectionIndex`, `label` (+ optional `events: string[]`)   | `remove_period(sectionIndex, periodIndex)` |
+| `add_period`         | `sectionIndex`, `label` (+ optional `events: string[]`, insert `index`) | `remove_period(sectionIndex, periodIndex)` |
 | `remove_period`      | `sectionIndex`, `periodIndex`                             | `add_period(...)` |
 | `set_period_label`   | `sectionIndex`, `periodIndex`, `label`                    | `set_period_label(... prev_label)` |
-| `add_event`          | `sectionIndex`, `periodIndex`, `text`                     | `remove_event(... eventIndex)` |
+| `add_event`          | `sectionIndex`, `periodIndex`, `text` (+ optional insert `index`) | `remove_event(... eventIndex)` |
 | `remove_event`       | `sectionIndex`, `periodIndex`, `eventIndex`               | `add_event(...)` |
 | `set_event_text`     | `sectionIndex`, `periodIndex`, `eventIndex`, `text`       | `set_event_text(... prev_text)` |
+| `move_period`        | `fromSection`, `fromIndex`, `toSection`, `toIndex` (timeline order IS the chronology, so reorder is a first-class edit) | `move_period(toSection, toIndex, fromSection, fromIndex)` |
+| `move_event`         | `fromSection`, `fromPeriod`, `fromIndex`, `toSection`, `toPeriod`, `toIndex` | `move_event(...)` |
+| `move_section`       | `from`, `to`                                              | `move_section(to, from)` |
+| `set_accessibility_title`       | `title \| null`                                | `set_accessibility_title(prev)` |
+| `set_accessibility_description` | `description \| null`                          | `set_accessibility_description(prev)` |
 
-**Class MutationOp kinds** (10):
+**Class MutationOp kinds** (15):
 
 | Kind | Required | Inverse |
 |---|---|---|
 | `set_title`         | `title \| null`                                      | `set_title(prev_title)` |
-| `add_class`         | `id` (+ optional `label`, `members: string[]`)        | `remove_class(id)` |
+| `add_class`         | `id` (+ optional `label`, `generic`, `members: string[]`, `namespace` dot path) | `remove_class(id)` |
 | `remove_class`      | `id`                                                  | `add_class(id, label, members)` |
 | `rename_class`      | `from`, `to`                                          | `rename_class(to, from)` |
+| `set_class_generic` | `class`, `generic \| null`                            | `set_class_generic(class, prev_generic)` |
 | `add_member`        | `class`, `text`                                       | `remove_member(class, index)` |
 | `remove_member`     | `class`, `index`                                      | `add_member(class, text)` |
 | `add_relation`      | `from`, `to`, `relKind` (+ optional `label`)          | `remove_relation(index)` |
 | `remove_relation`   | `index`                                               | `add_relation(...)` |
 | `add_note`          | `text` (+ optional `for: class`)                       | `remove_note(index)` |
 | `remove_note`       | `index`                                               | `add_note(text, for)` |
+| `set_class_namespace` | `class`, `namespace \| null` (a dot path like `Platform.Auth`, declared on demand; null = top level) | `set_class_namespace(class, prev_namespace)` |
+| `define_class`        | `name`, `style`                                    | restore previous definition |
+| `set_css_class`       | `class`, `className \| null`                       | restore previous assignment |
+| `set_class_style`     | `class`, `style \| null`                           | restore previous style |
 
-**ER MutationOp kinds** (7):
+**ER MutationOp kinds** (12):
 
 | Kind | Required | Inverse |
 |---|---|---|
-| `add_entity`        | `id` (+ optional `attributes: string[]`)             | `remove_entity(id)` |
-| `remove_entity`     | `id`                                                  | `add_entity(id, attributes)` |
+| `add_entity`        | `id` (+ optional `label`, `attributes: string[]`)    | `remove_entity(id)` |
+| `remove_entity`     | `id`                                                  | `add_entity(id, label, attributes)` |
 | `rename_entity`     | `from`, `to`                                          | `rename_entity(to, from)` |
+| `set_entity_label`  | `entity`, `label \| null`                             | `set_entity_label(entity, previous_label)` |
 | `add_attribute`     | `entity`, `text`                                      | `remove_attribute(entity, index)` |
 | `remove_attribute`  | `entity`, `index`                                     | `add_attribute(entity, text)` |
 | `add_relation`      | `from`, `to`, `leftCard`, `rightCard` (+ `dashed`, `label`) | `remove_relation(index)` |
 | `remove_relation`   | `index`                                               | `add_relation(...)` |
+| `set_direction`     | `direction`                                           | restore previous direction |
+| `define_class`      | `name`, `style`                                       | restore previous definition |
+| `set_entity_class`  | `entity`, `className \| null`                        | restore previous assignment |
+| `set_entity_style`  | `entity`, `style \| null`                            | restore previous style |
 
-**Journey MutationOp kinds** (14, BUILD-15 — the pilot promotion from opaque-only fallback semantics to structured mutation via the FamilyPlugin registry; ordering + accessibility ops added with the Mermaid-classic renderer elevation, since journey order IS the timeline):
+**Journey MutationOp kinds** (promoted from opaque-only fallback semantics through the family-descriptor registry; ordering and accessibility are typed because Journey order is the timeline):
 
 | Kind | Required | Inverse |
 |---|---|---|
@@ -315,22 +329,31 @@ Two contracts:
 | `set_accessibility_title`       | `title \| null`                               | `set_accessibility_title(prev)` |
 | `set_accessibility_description` | `description \| null`                         | `set_accessibility_description(prev)` |
 
-**Architecture MutationOp kinds** (10, BUILD-17 — promoting the architecture-beta family to structured mutation via the FamilyPlugin registry, following the BUILD-15 journey pilot):
+**Architecture MutationOp kinds** (19):
 
 | Kind | Required | Inverse |
 |---|---|---|
-| `add_service`        | `id` (+ optional `label`, `icon`, `group`)               | `remove_service(id)` |
-| `remove_service`     | `id` (cascades its edges)                                | `add_service(...)` + re-add edges |
-| `rename_service`     | `from`, `to` (updates edges)                             | `rename_service(to, from)` |
-| `set_service_label`  | `id`, `label`                                            | `set_service_label(id, prev_label)` |
-| `set_service_icon`   | `id`, `icon: string \| null`                             | `set_service_icon(id, prev_icon)` |
-| `move_service`       | `id`, `group: string \| null`                            | `move_service(id, prev_group)` |
-| `add_group`          | `id` (+ optional `label`, `icon`, `parent`)              | `remove_group(id)` |
-| `remove_group`       | `id` (refused if non-empty — move members first)         | `add_group(...)` |
-| `add_edge`           | `from`, `to`, `fromSide`, `toSide` (+ optional `label`, `hasArrowStart`, `hasArrowEnd`) | `remove_edge(id)` |
-| `remove_edge`        | `index` or `id` (`from->to`)                             | `add_edge(...)` |
-
-**XY chart MutationOp kinds** (8, BUILD-16 — promoting the xychart family to structured mutation via the FamilyPlugin registry, following the BUILD-15 journey and BUILD-17 architecture pilots). Canonical number format is `String(n)` (shortest round-tripping decimal); all values must be finite. Modeled grammar covers bare (unquoted) titles/axis-names/series-names/categories; quoted text, multi-statement `;` lines, accTitle/accDescr, and any other unmodeled syntax fall back to opaque:
+| `set_title` | `title \| null` | `set_title(prev_title)` |
+| `set_accessibility_title` | `title \| null` | `set_accessibility_title(prev)` |
+| `set_accessibility_description` | `description \| null` | `set_accessibility_description(prev)` |
+| `add_service` | `id` (+ optional `label`, `icon`, `group`) | `remove_service(id)` |
+| `remove_service` | `id` (cascades edges/alignments) | `add_service(...)` + re-add edges |
+| `rename_service` | `from`, `to` (rewrites edges/alignments) | `rename_service(to, from)` |
+| `set_service_label` | `id`, `label` | `set_service_label(id, prev_label)` |
+| `set_service_icon` | `id`, `icon: string \| null` | `set_service_icon(id, prev_icon)` |
+| `move_service` | `id`, `group: string \| null` | `move_service(id, prev_group)` |
+| `add_junction` | `id` (+ optional `group`) | `remove_junction(id)` |
+| `remove_junction` | `id` (cascades edges/alignments) | `add_junction(...)` + re-add edges |
+| `rename_junction` | `from`, `to` (rewrites edges/alignments) | `rename_junction(to, from)` |
+| `move_junction` | `id`, `group: string \| null` | `move_junction(id, prev_group)` |
+| `add_group` | `id` (+ optional `label`, `icon`, `parent`) | `remove_group(id)` |
+| `set_group_label` | `id`, `label` | `set_group_label(id, prev_label)` |
+| `remove_group` | `id` (refused if non-empty) | `add_group(...)` |
+| `add_edge` | `from`, `to`, `fromSide`, `toSide` (+ optional boundaries/label/arrows) | `remove_edge(id)` |
+| `update_edge` | `index` (+ any endpoint/side/boundary/label/arrow fields) | `update_edge(index, previous fields)` |
+| `remove_edge` | `index` or `id` (`from->to`) | `add_edge(...)` |
+
+**XY chart MutationOp kinds** (10, BUILD-16 — promoting the xychart family to structured mutation via the family-descriptor registry, following the BUILD-15 journey and BUILD-17 architecture pilots). Canonical number format is `String(n)` (shortest round-tripping decimal); all values must be finite. Modeled grammar covers bare titles/axis-names/series-names/categories — quoted text whose content is bare parses and canonicalizes to unquoted form; embedded quotes/brackets, multi-statement `;` lines, accTitle/accDescr, and any other unmodeled syntax fall back to opaque:
 
 | Kind | Required | Inverse |
 |---|---|---|
@@ -342,8 +365,10 @@ Two contracts:
 | `set_series_values`  | `index`, `values: number[]`                              | `set_series_values(index, prev_values)` |
 | `set_series_name`    | `index`, `name: string \| null`                          | `set_series_name(index, prev_name)` |
 | `reorder_series`     | `from`, `to`                                             | `reorder_series(to, from)` |
+| `set_orientation`    | `horizontal: boolean` (`true` adds the `horizontal` header suffix; `false` drops it — vertical is the serialized default) | `set_orientation(prev)` |
+| `set_data_point`     | `seriesIndex`, `index`, `value` (finite; out-of-range indices name the valid ranges) | `set_data_point(seriesIndex, index, prev_value)` |
 
-**Pie MutationOp kinds** (7 — promoting the pie family to structured mutation via the FamilyPlugin registry, following the journey/architecture/xychart pilots). Slices are addressed by their (unique) label; values must be positive finite numbers. The header's `showData` flag and an optional `title` are modeled; any unmodeled line (accTitle/accDescr, malformed entry) falls back to opaque losslessly:
+**Pie MutationOp kinds** (7 — promoting the pie family to structured mutation via the family-descriptor registry, following the journey/architecture/xychart pilots). Slices are addressed by their (unique) label; values must be positive finite numbers. The header's `showData` flag and an optional `title` are modeled; any unmodeled line (accTitle/accDescr, malformed entry) falls back to opaque losslessly:
 
 | Kind | Required | Inverse |
 |---|---|---|
@@ -355,7 +380,7 @@ Two contracts:
 | `set_slice_value`    | `label`, `value` (> 0)                                   | `set_slice_value(label, prev_value)` |
 | `reorder_slice`      | `from`, `to`                                             | `reorder_slice(to, from)` |
 
-**Quadrant MutationOp kinds** (7 — promoting the quadrantChart family to structured mutation via the FamilyPlugin registry). Points are addressed by their (unique) label; coordinates must be in `[0, 1]`. Quadrant numbering follows Mermaid core (1=top-right, 2=top-left, 3=bottom-left, 4=bottom-right). Styling (`classDef`, `:::`), out-of-range coordinates, and any unmodeled line fall back to opaque losslessly:
+**Quadrant MutationOp kinds** (7 — promoting the quadrantChart family to structured mutation via the family-descriptor registry). Points are addressed by their (unique) label; coordinates must be in `[0, 1]`. Quadrant numbering follows Mermaid core (1=top-right, 2=top-left, 3=bottom-left, 4=bottom-right). Styling (`classDef`, `:::`), out-of-range coordinates, and any unmodeled line fall back to opaque losslessly:
 
 | Kind | Required | Inverse |
 |---|---|---|
@@ -367,7 +392,7 @@ Two contracts:
 | `move_point`         | `label`, `x`, `y` (in `[0,1]`)                           | `move_point(label, prev_x, prev_y)` |
 | `rename_point`       | `from`, `to`                                             | `rename_point(to, from)` |
 
-**Gantt MutationOp kinds** (9 — segment-preserving from day one per [`docs/design/families/gantt.md`](./docs/design/families/gantt.md)). Sections and tasks are addressed by index (`sectionIndex`, `taskIndex`); `taskId` is the Mermaid id used by `after`/`until`/`click`. Calendar directives (`dateFormat`, `excludes`, `includes`, `weekend`, `weekday`, `todayMarker`, `tickInterval`, `inclusiveEndDates`, `topAxis`), `click` lines, accTitle/accDescr, and comments ride along VERBATIM as opaque-block segments — preserved, source-level-editable, never typed-editable in v1. Every value an op writes is validated by rendering its canonical line and re-parsing it (correctness by construction), so labels with `:` or values with `,` are rejected rather than corrupting the source:
+**Gantt MutationOp kinds** (13 — segment-preserving from day one per [`docs/design/families/gantt.md`](./docs/design/families/gantt.md)). Sections and tasks are addressed by index (`sectionIndex`, `taskIndex`); `taskId` is the Mermaid id used by `after`/`until`/`click`. Calendar directives (`dateFormat`, `excludes`, `includes`, `weekend`, `weekday`, `todayMarker`, `tickInterval`, `inclusiveEndDates`, `topAxis`), `click` lines, accTitle/accDescr, and comments ride along VERBATIM as opaque-block segments — preserved, source-level-editable, never typed-editable in v1. Every value an op writes is validated by rendering its canonical line and re-parsing it (correctness by construction), so labels with `:` or values with `,` are rejected rather than corrupting the source. Gantt source order IS scheduling semantics (a task with an implicit start chains from the previous task in flat source order), so the move ops REJECT prescriptively whenever they would change an implicit-start task's predecessor — materialize an explicit start (`set_task_dates` or an `after` dependency) and retry:
 
 | Kind | Required | Inverse |
 |---|---|---|
@@ -375,32 +400,65 @@ Two contracts:
 | `add_section`        | `label`                                                   | `remove_section(index)` |
 | `rename_section`     | `index`, `label`                                          | `rename_section(index, prev_label)` |
 | `remove_section`     | `index` (drops its tasks too)                             | `add_section(...)` + `add_task(...)` |
-| `add_task`           | `sectionIndex`, `label`, `end` (+ optional `taskId`, `tags`, `start`) | `remove_task(sectionIndex, taskIndex)` |
+| `add_task`           | `sectionIndex`, `label`, `end` (+ optional `taskId`, `tags`, `start`, insert `index` — a mid-chain insert deliberately re-chains the follower) | `remove_task(sectionIndex, taskIndex)` |
 | `remove_task`        | `sectionIndex`, `taskIndex`                               | `add_task(...)` |
 | `rename_task`        | `sectionIndex`, `taskIndex`, `label`                      | `rename_task(..., prev_label)` |
 | `set_task_status`    | `sectionIndex`, `taskIndex`, `status: 'active' \| 'done' \| 'crit' \| null` (milestone/vert tags are never disturbed) | `set_task_status(..., prev_status)` |
 | `set_task_dates`     | `sectionIndex`, `taskIndex`, `start?: string \| null`, `end?: string` | `set_task_dates(..., prev_start, prev_end)` |
+| `set_task_flags`     | `sectionIndex`, `taskIndex`, `milestone?`, `vert?` (structural-tag toggles; `set_task_status` never touches them) | `set_task_flags(..., prev_flags)` |
+| `set_task_id`        | `sectionIndex`, `taskIndex`, `taskId \| null` (a rename REWRITES structured `after`/`until` references; REJECTS while opaque segments reference the id, and `null` rejects while ANY reference exists) | `set_task_id(..., prev_id)` |
+| `move_task`          | `fromSection`, `fromIndex`, `toSection`, `toIndex` (implicit-start guard above) | `move_task(toSection, toIndex, fromSection, fromIndex)` |
+| `move_section`       | `from`, `to` (implicit-start guard above)                 | `move_section(to, from)` |
+
+**Mindmap MutationOp kinds** (10; see [`docs/design/families/mindmap.md`](./docs/design/families/mindmap.md)):
+
+`add_node`, `remove_node`, `rename_node`, `set_label`, `move_node`, `set_shape`, `set_icon`, `set_node_class`, `set_accessibility_title`, `set_accessibility_description`.
+
+**GitGraph MutationOp kinds** (11; see [`docs/design/families/gitgraph.md`](./docs/design/families/gitgraph.md)):
+
+`append_commit`, `create_branch`, `checkout_branch`, `merge_branch`, `cherry_pick`, `set_commit_message`, `set_commit_type`, `set_commit_tags`, `rename_branch`, `set_accessibility_title`, `set_accessibility_description`.
+
+**Radar MutationOp kinds** (14 — promoting the `radar-beta` family to structured mutation via the FamilyPlugin registry). Axes and curves are addressed by unique ids; each curve carries exactly one finite value per axis, in axis order. The header keyword is `radar-beta`; order-independent and multiline `title`, `axis`/`curve`, and option declarations are modeled. Duplicate identities, vector mismatches, accessibility directives, and any unmodeled line fall back to opaque losslessly rather than weakening the typed invariant:
+
+| Kind | Required | Inverse |
+|---|---|---|
+| `set_title`         | `title \| null`                                        | `set_title(prev_title)` |
+| `add_axis`          | `id` (+ optional `label`, insert `index`, `fill`)      | `remove_axis(id)` |
+| `remove_axis`       | `id`                                                   | `add_axis(...)` |
+| `rename_axis`       | `from`, `to`                                           | `rename_axis(to, from)` |
+| `set_axis_label`    | `id`, `label \| null`                                  | `set_axis_label(id, prev_label)` |
+| `reorder_axis`      | `from`, `to` (permutes every curve's value vector)     | `reorder_axis(to, from)` |
+| `add_curve`         | `id`, `values` (one per axis) (+ optional `label`, insert `index`) | `remove_curve(id)` |
+| `remove_curve`      | `id`                                                   | `add_curve(...)` |
+| `set_curve_values`  | `id`, `values` (one per axis)                          | `set_curve_values(id, prev_values)` |
+| `set_curve_value`   | `curve`, `axis`, `value` (finite)                      | `set_curve_value(curve, axis, prev_value)` |
+| `set_curve_label`   | `id`, `label \| null`                                  | `set_curve_label(id, prev_label)` |
+| `rename_curve`      | `from`, `to`                                           | `rename_curve(to, from)` |
+| `reorder_curve`     | `from`, `to`                                           | `reorder_curve(to, from)` |
+| `set_config`        | optional `max`, `min`, `ticks` (`1..64`), `graticule`, `showLegend`; `null` resets each field | `set_config(prev_fields)` |
 
-**Structured-or-opaque rule (v4): never lossy.** The parser only produces a structured body when it fully understands every non-blank, non-comment line for most structured families. If the source contains *any* construct the parser doesn't model — `direction TB` in class, `accTitle` or out-of-range scores in journey, the `{group}` boundary modifier in architecture, quoted text or `curve basis` in xychart, a malformed entry in pie, or out-of-range coordinates in quadrant, etc. — parsing **falls back to an opaque body**. The diagram still parses, renders, verifies (structurally), and round-trips losslessly via preserved `body.source`; it simply isn't offered for structured mutation (structured-family narrowers return `null` on opaque fallbacks). This guarantees the parser never silently drops information. Earlier drafts dropped unrecognized lines on the floor; v4 does not.
+**Structured-or-opaque rule (v4): never lossy.** The parser only produces a structured body when it fully understands every non-blank, non-comment line for most structured families. If the source contains *any* construct the parser doesn't model — `direction TB` in class, out-of-range scores in journey, duplicate Architecture title declarations, a `;`-joined multi-statement line in xychart, a malformed entry in pie, or out-of-range coordinates in quadrant, etc. — parsing **falls back to an opaque body**. The diagram still parses, renders, verifies (structurally), and round-trips losslessly via preserved `body.source`; it simply isn't offered for structured mutation (structured-family narrowers return `null` on opaque fallbacks). This guarantees the parser never silently drops information. Earlier drafts dropped unrecognized lines on the floor; v4 does not.
 
-**Segment-preserving bodies (BUILD-18) — sequence ends the all-or-nothing cliff.** Sequence is the first family that does *not* go whole-body opaque on the first unmodeled line. Its body carries an ordered `statements: SequenceStatement[]` list (`participant` / `message` refs into the existing `participants`/`messages` arrays, plus `opaque-block` segments holding unmodeled lines VERBATIM). Block constructs (`alt|opt|loop|par|critical|break|rect … end`, nesting-tracked) become one opaque-block segment; `Note`/`activate`/`deactivate`/`autonumber`/`title` lines each join an adjacent segment. The participant/message ops stay live and address the top-level `messages` array exactly as before — **messages inside an opaque block are invisible to ops and are never touched.** Only an un-segmentable body (a stray `end`, an unclosed block) still falls back to whole-body opaque. Either way the round-trip is verbatim-lossless. Gantt adopts the same pattern from its first release: typed ops on title/sections/tasks, opaque-block segments for calendar directives/click/comments, whole-opaque only for duplicate ids or unclosed accDescr blocks. Class/ER/timeline segment-preservation is follow-up work.
+**Segment-preserving bodies (BUILD-18) — sequence ends the all-or-nothing cliff.** Sequence carries an ordered `statements: SequenceStatement[]` list. `alt|opt|loop|par` are typed fragments: their branches/messages participate in describe/facts/verify and have dedicated mutation ops. Other block constructs (`critical|break|rect|box … end`) and `Note`/`activate`/`deactivate`/`create`/`destroy`/`autonumber`/`title` remain VERBATIM opaque segments. Top-level message indices stay backward-compatible and distinct from fragment indices. Only an un-segmentable body (a stray `end`, an unclosed block) falls back to whole-body opaque. Gantt adopts the same pattern for calendar directives/click/comments. ER also uses ordered typed and opaque-block segments; Class and Timeline are the remaining follow-up work.
 
-For any opaque fallback, cross-cutting edits are source-level only: operate against preserved source intentionally, then re-parse and verify before returning. Every renderable family now ships structured mutation; a new family follows the same pattern as its definition of done: narrowed type + body parser + serializer + per-family ops + verify hook + round-trip property tests + doc sync (most recently gantt). See `docs/contributing/adding-diagram-types.md`.
+For any opaque fallback, cross-cutting edits are source-level only: operate against preserved source intentionally, then re-parse and verify before returning. Every renderable family now ships structured mutation; a new family follows the same pattern as its definition of done: narrowed type + body parser + serializer + per-family ops + verify hook + round-trip property tests + doc sync (most recently Mindmap and GitGraph). See `docs/contributing/adding-diagram-types.md`.
 
-Convention bans constructing `ValidDiagram` outside `parseMermaid`, `mutate`, `synthesizeFromGraph`, and `createMermaid`/`buildMermaid`.
+Convention bans constructing `ValidDiagram` outside `parseRegisteredMermaid`, `mutate`, `synthesizeFromGraph`, and `createMermaid`/`buildMermaid`.
 
 ---
 
 ## Public API
 
 ```ts
-parseMermaid(source: string):                              Result<ValidDiagram, ParseError[]>
+parseRegisteredMermaid(source: string):                              Result<ValidDiagram, ParseError[]>
 layoutMermaid(d: ValidDiagram):                            RenderedLayout
 renderMermaidASCII(input: ValidDiagram | string, opts?):   string
 renderMermaidPNG(input: ValidDiagram | string, opts?):     Uint8Array
 renderMermaidSVG(input: ValidDiagram | string, opts?):     string
 verifyMermaid(input: ValidDiagram | string, opts?: VerifyOptions): VerifyResult
 serializeMermaid(d: ValidDiagram):                         string
+// ASCII opts.targetWidth is a hard display-cell bound; impossible bounds throw
+// AsciiWidthError { code, requestedWidth, requiredWidth, family, reason }.
 
 // Mutation is overloaded by family. Opaque/source-only families don't typecheck.
 mutate(d: FlowchartValidDiagram, op: FlowchartMutationOp): Result<FlowchartValidDiagram, MutationError>
@@ -415,6 +473,9 @@ mutate(d: XyChartValidDiagram,   op: XyChartMutationOp):   Result<XyChartValidDi
 mutate(d: PieValidDiagram,       op: PieMutationOp):       Result<PieValidDiagram, MutationError>
 mutate(d: QuadrantValidDiagram,  op: QuadrantMutationOp):  Result<QuadrantValidDiagram, MutationError>
 mutate(d: GanttValidDiagram,     op: GanttMutationOp):     Result<GanttValidDiagram, MutationError>
+mutate(d: MindmapValidDiagram,   op: MindmapMutationOp):   Result<MindmapValidDiagram, MutationError>
+mutate(d: GitGraphValidDiagram,  op: GitGraphMutationOp):  Result<GitGraphValidDiagram, MutationError>
+mutate(d: RadarValidDiagram,     op: RadarMutationOp):     Result<RadarValidDiagram, MutationError>
 
 // Narrowing helpers; null when the diagram isn't of that family or is opaque/source-level.
 asFlowchart(d: ValidDiagram): FlowchartValidDiagram | null
@@ -429,6 +490,9 @@ asXyChart(d: ValidDiagram):   XyChartValidDiagram | null
 asPie(d: ValidDiagram):       PieValidDiagram | null
 asQuadrant(d: ValidDiagram):  QuadrantValidDiagram | null
 asGantt(d: ValidDiagram):     GanttValidDiagram | null
+asMindmap(d: ValidDiagram):   MindmapValidDiagram | null
+asGitGraph(d: ValidDiagram):  GitGraphValidDiagram | null
+asRadar(d: ValidDiagram):     RadarValidDiagram | null
 
 // Build a ValidDiagram from a JSON-safe graph payload without re-parsing
 // source. Used by `am parse | am serialize` shell pipelines.
@@ -455,9 +519,9 @@ There is no `LayoutContext`, no `SeededRNG`, no `Clock`, no font-metric table in
 - **Agent surface exposed via the `./agent` subpath export** on the `agentic-mermaid` package. Agentic Mermaid is the product/docs name, npm identity, and repository path (`adewale/agentic-mermaid`). The subpath export keeps renderer and agent surfaces side by side.
 - **Deterministic layout, verified.** Layout JSON is byte-identical across processes because ELK is configured for model-order layout with no random seed (see § (1)). No seed parameter is exposed because none affects output. Cross-machine byte equality across different CPU float behavior is not claimed; structural determinism within an ELK version is guaranteed and tested cross-process.
 - **IDs are content-hashed and stable** across runs (within an ELK version).
-- **`MermaidGraph` is kept** as an exported type — `ValidDiagram` wraps it in `body.graph` for flowchart, rather than replacing it. The original spec called for removal; the implementation showed it would break 61 test files and the Craft Agents consumer. The wrapping shape costs nothing.
+- **`MermaidGraph` is kept** as an exported type — `ValidDiagram` wraps it in `body.graph` for flowchart, rather than replacing it. The original spec called for removal; characterization showed it would break existing tests and the Craft Agents consumer. The wrapping shape costs nothing.
 - **`renderMermaidSVGAsync` is kept**. Removing it was a v1-aspiration that turned out to break consumers for no win at the agent surface.
-- **`mermaidConfig` precedence** (frontmatter < init < render options) is enforced by tests via a single merge function — unchanged from the existing pipeline.
+- **`mermaidConfig` precedence** is source frontmatter < init < explicit render options for supported family fields. Normalization merges source wrappers; family resolvers then reapply the original explicit section last. State has direct public-path precedence and geometry probes in `state-config.test.ts`.
 
 ---
 
@@ -468,7 +532,7 @@ Five artifacts, all derived from this doc:
 - **npm package** `agentic-mermaid` with the `agentic-mermaid/agent` subpath. The full TypeScript API, including ASCII, PNG, and SVG output helpers. Agents with shell access import the library directly and compose verbs in their own JS/TS runtime; no MCP wrapper required.
 - **`skills/agentic-mermaid-diagram-workflow/`** agent-agnostic skill bundle. Master `SKILL.md` routes by *both* diagram family and composition channel: it picks Code Mode when the MCP is connected, library import when the agent can run JS/TS with imports, the CLI for shell-only contexts. Per-family references (`flowchart.md`, `sequence.md`, etc.) describe syntax. Two channel references — `code-mode.md` (the canonical multi-step pattern) and `cli.md` (shell-only) — describe composition. Progressive disclosure means the LLM loads only what it needs. Family references sync from upstream Mermaid docs weekly via the shipped GitHub Action at `.github/workflows/sync-mermaid-docs.yml`, alongside our additions (LayoutWarning codes, MutationOp taxonomy).
 - **Substrate grep-lint** runs under `bun test` (not an uninstalled ESLint): `src/__tests__/agent-substrate-lint.test.ts` fails the build if `Math.random`, `Date.now`, or `performance.now` appear in `src/agent/**` or `src/layout-engine.ts`. This is real enforcement, executed in CI, not an aspirational config file.
-- **`agentic-mermaid-mcp`** Code Mode-style MCP server. The primary tool is `execute(code: string)`: the model writes JavaScript against the typed `mermaid.*` SDK declaration embedded in the system prompt; the server runs the code in a local `node:vm` sandbox with the library exposed as `mermaid` and the code's return value captured as the structured result. The server also exposes narrow `render_png` and `describe` helpers for binary output and summaries. The verify-before-commit loop becomes one round-trip rather than N. Hosting: local stdio launched by the MCP client (Claude Desktop, Claude Code, Cursor) — same deployment shape as filesystem-MCP, git-MCP, sqlite-MCP. No infrastructure on our side or the user's. The current MCP is not Cloudflare Codemode, not a Worker, not backed by `@cloudflare/codemode`, and not a drop-in Cloudflare integration. The `website/` Worker is a static Workers Static Assets deployment only; hosted MCP transport or a Cloudflare executor remain future options, not shipped artifacts.
+- **`agentic-mermaid-mcp`** Code Mode-style MCP server. The primary tool is `execute(code: string)`: the model writes JavaScript against the typed `mermaid.*` SDK declaration embedded in the system prompt. Local stdio/HTTP runs synchronous code in a `node:vm` sandbox. The hosted `/mcp` endpoint runs the same hardened facade in per-request Cloudflare Dynamic Worker isolates with bounded CPU/subrequests and no outbound network. Pure render/verify/describe helpers share transport-neutral behavior. Differential tests pin the common contract and explicitly name strict-module and CPU-time divergences; neither runtime depends on `@cloudflare/codemode`.
 - **`Instructions_for_agents.md`** at repo root, hard-capped under 100 lines. `am --agent-instructions` prints the same content at runtime; a doc-sync test asserts the two are byte-identical.
 
 No HTTP endpoint or editor WebSocket watch in v1. The skill teaches Code Mode for both paths: agents-with-shell write JS/TS against the imported library; agents-without-shell write JavaScript against the MCP's `mermaid.*` SDK. Same surface in both cases.
@@ -495,8 +559,8 @@ Agent-contract CLI verbs for explicit self-discovery, summaries, and batch opera
 The canonical runtime guide lives in `Instructions_for_agents.md` and is emitted byte-for-byte by `am --agent-instructions`; this spec intentionally does not duplicate the full snippet. The stable contract is:
 
 1. For new diagrams, `buildMermaid(kind, ops)` — or `createMermaid(kind)` then typed mutations — then `verifyMermaid` / render or return it. Author Mermaid source directly only for syntax the typed ops do not model.
-2. For existing diagrams, `parseMermaid(source)` → `ValidDiagram`.
-3. Narrow with `asFlowchart` / `asState` / `asSequence` / `asTimeline` / `asClass` / `asEr` / `asJourney` / `asArchitecture` / `asXyChart` / `asPie` / `asQuadrant` / `asGantt`; `null` means no structured mutation for that body.
+2. For existing diagrams, `parseRegisteredMermaid(source)` → `ValidDiagram`.
+3. Use the family entry's registry-advertised narrower; `null` means no structured mutation for that body.
 4. Apply typed `mutate` ops only to narrowed mutable bodies; Code Mode SDK-returned diagrams are read-only to block direct IR edits.
 5. Run `verifyMermaid(d)` at every commit point and inspect `ok` / `warnings` / `layout`.
 6. Only then `serializeMermaid(d)`.
@@ -546,15 +610,15 @@ MermaidSeqBench is wired as an external corpus signal; live model transcript eva
 
 - **Determinism is empirical, not proven.** It's established by cross-process test over a corpus + the drift sentinel, plus reading ELK's config (`considerModelOrder: NODES_AND_EDGES`, no `randomSeed`). An ELK upgrade could in principle change this; the cross-process test and sentinel would catch it. There is no layout seed to fall back on because seeding never affected geometry. (The render option `seed` is a *style* seed: it re-rolls the ink wobble of styled looks and never moves layout.)
 - **Determinism claim, precisely.** Layout JSON is byte-identical (after structural parse) across processes AND across JS runtimes (bun, node) on the same machine and same ELK version; this is verified on same-machine x86_64 and ARM64 when Node + built `dist/` are present. Direct cross-architecture byte equality (x86_64 output compared to ARM64 output) is still not a separate claim.
-- **Sequence structured coverage is segment-preserving (BUILD-18).** Participant declarations + simple messages are the mutable structured surface; Note/alt/loop/par/activate/autonumber/title now ride along as verbatim opaque-block *segments* in the same body, so the structured ops survive instead of going whole-body opaque. Messages inside opaque blocks are deliberately not modeled (invisible to ops). Only un-segmentable input (unbalanced `end`, unclosed block) falls back to whole-body opaque. The honest tradeoff is unchanged — never lossy — it just no longer sacrifices the structured ops at the first unmodeled line. (Class/ER/timeline segment work is a follow-up.)
-- **All twelve renderable families ship structured mutation; opaque fallbacks stay source-level only.** Pie and quadrant completed the promotion (7 ops each, via `asPie`/`asQuadrant`) and gantt ships segment-preserving structured mutation from its first release (9 ops via `asGantt`), so a narrower exists for every family kind; only opaque-fallback bodies (unmodeled syntax) remain deliberate, lossless source-level paths. (Journey was promoted by BUILD-15; architecture by BUILD-17; xychart by BUILD-16.)
+- **Sequence structured coverage is segment-preserving (BUILD-18).** Participant declarations, top-level messages, and direct-message `alt`/`opt`/`loop`/`par` fragments are typed; fragment messages participate in describe/facts/verify and dedicated mutation ops. Note/critical/break/rect/box/activate/autonumber/title and nested or otherwise unmodeled fragment content ride along as verbatim opaque-block *segments*, so the structured ops survive instead of going whole-body opaque. Messages inside those remaining opaque blocks are deliberately not modeled. Only un-segmentable input (unbalanced `end`, unclosed block) falls back to whole-body opaque. The honest tradeoff is unchanged — never lossy — it just no longer sacrifices the structured ops at the first unmodeled line. ER also has ordered typed and opaque-block segments; Class and Timeline are the remaining follow-up work.
+- **Every registered renderable family ships structured mutation; opaque fallbacks stay source-level only.** A typed narrower exists for every family kind; only opaque-fallback bodies for unmodeled syntax remain deliberate, lossless source-level paths.
 - **Live-model agent-usage eval is periodic, not PR CI.** Stored Code Mode scripts, sandbox traces, task oracles, and the committed pi-subagent transcript replay run in CI; API-backed release-model transcripts remain in `TODO.md` because they need model access and selected release tasks.
 - **Bloat in agent-facing docs.** `Instructions_for_agents.md` is hard-capped under 100 lines; doc-sync test enforces.
 
 ## What v4 delivers (vs. earlier drafts)
 
 - **Determinism is structural and verified cross-process** — not a seed apparatus. The seed/RNG/clock machinery and the font-metric table are *removed* (they did nothing).
-- **Mutation for all twelve renderable families** (flowchart/state, sequence, timeline, class, ER, journey, architecture, xychart, pie, quadrant, gantt), family-narrowed overloads, compile-time rejection of opaque/source-only fallback bodies.
+- **Mutation for every registered renderable family**, with family-narrowed overloads and compile-time rejection of opaque/source-only fallback bodies.
 - **Sequence parsing is lossless** — segment-preserving structured body (BUILD-18): Note/alt/loop/etc. ride along verbatim as opaque-block segments while the structured ops stay live; only un-segmentable input falls back to whole-body opaque; never silently drops constructs.
 - **Substrate enforcement is a real grep test** that runs under `bun test`, not an ESLint config that was never installed.
 - **`synthesizeFromGraph`** lets `am parse | am serialize` round-trip without `canonicalSource` on the wire.
@@ -578,7 +642,7 @@ Concrete consequences, in roughly descending impact:
 5. **No need to ship `diffDiagrams` or `explainDiagram`.** Already cut. Code Mode confirms the cut: an agent that wants structural diff writes it from `parse` + `ValidDiagram` inspection in JavaScript. Every "would be nice to have a verb for" becomes "write the code for it in `execute()`."
 6. **Library as the cross-tool agent interface for diagrams.** A Mermaid linter, a `mermaid → d2` converter, a `graphviz → mermaid` importer can each expose the same Code Mode shape. Any agent then writes one JavaScript snippet that composes across libraries. We've effectively defined the agent interface for diagrams in this language.
 7. **Benchmark eval at speed.** MermaidSeqBench (and any future eval) runs as one `execute()` per case rather than N round-trips. Internal velocity multiplier.
-8. **Potential future hosted-Worker path.** Cloudflare-hosted Agentic Mermaid is tracked as `TODO.md` BUILD-4. The repo now ships a static Workers Static Assets website under `website/`, but a hosted MCP/Code Mode wrapper remains separate. That wrapper could use `@cloudflare/codemode` + `DynamicWorkerExecutor` only after the security boundary, auth/rate limits, persistence, and CLI/MCP/library parity are scoped. The current repo does not ship that dependency or runtime; JavaScript snippets plus a TypeScript-shaped SDK declaration are the reusable design idea, not a current hosted execution deployment.
+8. **Hosted Worker path.** The shipped `/mcp` endpoint uses Cloudflare Dynamic Worker isolates through the platform loader binding, not `@cloudflare/codemode`. The runtime has explicit security/resource limits and differential parity with local Code Mode; remaining WAF and abuse-control operations are tracked separately in `TODO.md`.
 9. **The skill becomes runnable, not just descriptive.** `references/code-mode.md` ships canonical executable JavaScript snippets the agent copy-pastes into `execute()`. Skill stops being prose; starts being a library of executable patterns.
 10. **A future diagram REPL would be a thin transport.** An `am repl` could become an interactive Code Mode shell — paste JavaScript, get structured results, iterate. Same sandbox, different transport. It is not shipped and would need promotion to `TODO.md` before implementation.