@beehexa/hexasync-template-model 2608.21.4 → 2610.4.3

package/dist/flowRender.js

@@ -17,34 +17,401 @@
  * **1. Every subgraph emits its OWN direction.** Mermaid ignores the parent chart's direction inside a subgraph, so a
  * `TD` chart with `LR` stages needs the statement repeated per subgraph. (`PACKAGE-CONTRACT.md` §5 rule 1.)
  *
- * **2. Styling is PER ELEMENT — `style` and `linkStyle`, not `class`/`classDef`.** dashboard's own comment is the
- * evidence: *"`classDef` did NOT reliably apply to node shapes in v11 — edges highlighted but nodes/diamonds did
- * not."* A class-based overlay silently highlights the arrows and leaves the boxes plain.
+ * **2. Styling is PER ELEMENT — `style` and `linkStyle`, not `class`/`classDef`.** The Mermaid 12 definition
+ * baseline emits overlays as exact element-addressed statements; traversal classes are absent from those bytes.
  *
  * **3. …with ONE exception, and it is not a contradiction.** The VS Code extension uses `classDef` successfully — for
- * `stroke-width` only, never a fill — precisely so the **webview's stylesheet** can colour it from theme variables. A
- * literal colour would be wrong in one of light or dark. So: per-element `style` for anything carrying a COLOUR (which
- * the caller supplies), `classDef` for a shape hint a stylesheet should own. Both are offered; neither is guessed.
+ * `stroke-width` only, never a fill — precisely so the **webview's stylesheet** can colour that optional shape hint
+ * from theme variables. Run-state colors remain caller-supplied per-element `style` values; approved kind borders and
+ * polygon fill use deterministic role defaults which callers may override.
  *
- * **4. A `classDef` inside a `subgraph` is a PARSE ERROR in mermaid 11**, which is why class declarations are hoisted
- * to the end of the chart rather than emitted beside the nodes they name.
+ * **4. Shape-hint `classDef` declarations are chart-level output.** They are hoisted after every subgraph and emitted
+ * once, rather than repeated beside the nodes they name.
  *
- * **5. A colour is VALIDATED, and an unusable one drops the highlight rather than the chart.** Measured with the real
- * mermaid 11 parser: `#hex` and a bare identifier (`red`) parse; `rgba(…)`, `rgb(…)`, `hsl(…)` and `var(--x)` are
- * **parse errors** in `style` and `linkStyle` alike. dashboard's comment — ported here verbatim at first — said such
- * colours *"fall back to a stroke-only highlight"*, and that was false in both directions: a named colour never broke
- * anything, and an `rgba` did not degrade, it destroyed the diagram. A fill tint still needs exactly `#rrggbb`,
- * because the tint is 8-digit-hex alpha and has nothing to append to otherwise.
+ * **5. A colour is VALIDATED, and an unusable one drops the highlight rather than the chart.** The Mermaid 12
+ * characterization parses and renders the representative hex form and parses a bare named colour. Other CSS colour
+ * forms remain outside this emitter's declared literal grammar; no claim about Mermaid 12 accepting them is needed.
+ * A fill tint still needs exactly `#rrggbb`, because the tint has no alpha suffix to append otherwise.
  *
  * **6. The same `(model, opts)` always produces the same string.** No clock, no randomness, no ambient state — the
  * golden-diagram suite depends on it (AD-29), which is also why the overlay is an ARGUMENT and never state.
  */
 import { renderedNodeId } from './nodeAddress.js';
+import { expandOccurrences, mergeNodeOverlays } from './occurrenceExpansion.js';
+import { RUN_STATE_ERROR_MARKER, isCountableRepeat, repeatBadgeText, runStateAlternativeText, stepIconClassName, } from './stepGlyph.js';
+/** The complete, ordered shape vocabulary. No renderer path may invent another treatment. */
+export const APPROVED_NODE_TREATMENTS = [
+    'flow-start',
+    'flow-end',
+    'process',
+    'branch',
+    'subroutine',
+    'delay',
+    'exception',
+    'unimplemented',
+];
 /**
- * Words mermaid's flowchart grammar owns. A node id or class name spelled as one is a parse error.
+ * The hard boundary between deterministic definition generation and host DOM decoration.
  *
- * Verified against mermaid 11 by the Story 4.3 review: `end`, `graph`, `subgraph`, `style` and `class` each break the
- * parse, while `direction`, `o`, `x` and `0` do not — so this is the measured set rather than a cautious guess.
+ * Exported as data so adapters and contract tests can share one inventory instead of describing the boundary in
+ * prose that drifts. Stage 3 may make generated nodes operable; every visible or structural byte belongs here.
+ */
+export const FLOW_RENDER_STAGE_OWNERSHIP = {
+    generate: [
+        'shape',
+        'nodeId',
+        'labelText',
+        'accTitle',
+        'accDescr',
+        'iconClass',
+        'nodeStyle',
+        'edge',
+        'linkStyle',
+        'edgeColor',
+        'edgeDash',
+        'direction',
+        'repeatBadge',
+        'errorMarker',
+    ],
+    decorate: ['interaction'],
+};
+/**
+ * The nine runtime executors whose authoritative Epic 7 evidence records `NotImplementedException`.
+ *
+ * This is an explicit roster subset, never a name or family regex. `WorkerStepType` keeps every member tied to the
+ * vendored 51-row manifest vocabulary. Begin and End remain in the subset but terminal treatment takes precedence.
+ */
+export const UNIMPLEMENTED_WORKER_STEP_TYPES = [
+    'Begin',
+    'Composite',
+    'cURL',
+    'End',
+    'GraphQL',
+    'Liquid',
+    'OData',
+    'QueryDSL',
+    'Restful',
+];
+const UNIMPLEMENTED_WORKER_STEP_TYPE = {
+    Begin: true,
+    Composite: true,
+    cURL: true,
+    End: true,
+    GraphQL: true,
+    Liquid: true,
+    OData: true,
+    QueryDSL: true,
+    Restful: true,
+};
+const SUBROUTINE_WORKER_STEP_TYPE = {
+    PULLER: true,
+    PUSHER: true,
+    ENQUEUER: true,
+};
+/** Classify treatment from model facts only; labels and icon families are deliberately irrelevant. */
+export function classifyNodeTreatment(node) {
+    if (node.type === 'Begin')
+        return 'flow-start';
+    if (node.type === 'End')
+        return 'flow-end';
+    if (node.decides === true ||
+        node.type === 'IF' ||
+        node.type === 'SWITCH') {
+        return 'branch';
+    }
+    if (node.type !== undefined &&
+        SUBROUTINE_WORKER_STEP_TYPE[node.type] === true) {
+        return 'subroutine';
+    }
+    if (node.type === 'SLEEP')
+        return 'delay';
+    if (node.type === 'EXCEPTION' || node.type === 'Error')
+        return 'exception';
+    if (node.type !== undefined &&
+        UNIMPLEMENTED_WORKER_STEP_TYPE[node.type] === true) {
+        return 'unimplemented';
+    }
+    if (node.terminal === true)
+        return 'flow-end';
+    return 'process';
+}
+/** Deterministic approved light palette; valid host-resolved values may override these roles. */
+export const APPROVED_NODE_COLORS = {
+    fill: '#ffffff',
+    nodeBorder: '#64748b',
+    failStroke: '#b91c1c',
+    edge: '#64748b',
+    notTakenStroke: '#475569',
+    edgeLabelText: '#334155',
+    edgeLabelBg: '#ffffff',
+};
+/**
+ * The declared line-work roles (DESIGN.md `strokes:`). Blueprint carries state in the LINE, so weight and pattern
+ * are roles, not values a render path picks.
+ *
+ * They live here as data because FR59 forbids a width or dash-array literal inside an emitter function: a width literal
+ * typed into one of three emit sites is exactly how the shipped emitter ended up with three copies of one decision.
+ */
+export const STROKE_ROLES = {
+    /** Every node outline and every edge. */
+    hairline: '1px',
+    /** The failed node's outline, and nothing else on the canvas. */
+    emphasis: '2px',
+    /** Dash array for the branch-not-taken stroke. RUN STATE ONLY. */
+    dash: '6 3',
+};
+/** The four states DESIGN.md's state table draws as rows; `indeterminate` is the fifth reading, not a fifth state. */
+export const RUN_STATES = [
+    'ranOk',
+    'ranFailed',
+    'neverReached',
+    'branchNotTaken',
+];
+/** The drawn reading for a node the producer could not place. Counted apart from `RUN_STATES` on purpose. */
+export const INDETERMINATE_RUN_STATE = 'indeterminate';
+/**
+ * The five drawn readings, resolved from DESIGN.md's closed light palette (`colors:` 9-88, `node-*` components
+ * 171-195, the state table 389-400).
+ *
+ * Data, not code, for the same reason as `STROKE_ROLES`: FR59 forbids a colour, width, dash or opacity literal
+ * inside an emitter function. `opacity: '0.7'` is the ONLY numeric opacity in DESIGN.md (`node-unreached` line 187)
+ * and it exists once, here.
+ *
+ * Read the columns against the matrix they came from:
+ *  - **failed** is the only `emphasis`, the only `marker`, and the only non-white fill. All three unconditional.
+ *  - **never reached** is SOLID with a fully visible border and recedes by muted text + `opacity` on the card.
+ *  - **branch not taken** is DASHED at full neutral contrast and is NEVER dimmed.
+ *  - **indeterminate** is the neutral pair and carries nothing else, so it stays clickable and unremarkable.
+ */
+export const STATE_ROLES = {
+    ranOk: {
+        stroke: '#c2410c',
+        fill: APPROVED_NODE_COLORS.fill,
+        title: '#0f172a',
+        description: '#475569',
+        width: 'hairline',
+        dash: false,
+        opacity: undefined,
+        marker: false,
+    },
+    ranFailed: {
+        stroke: APPROVED_NODE_COLORS.failStroke,
+        fill: '#fee2e2',
+        title: '#991b1b',
+        description: '#7f1d1d',
+        width: 'emphasis',
+        dash: false,
+        opacity: undefined,
+        marker: true,
+    },
+    neverReached: {
+        stroke: '#7c8899',
+        fill: '#f8fafc',
+        title: '#64748b',
+        description: '#64748b',
+        width: 'hairline',
+        dash: false,
+        opacity: '0.7',
+        marker: false,
+    },
+    branchNotTaken: {
+        stroke: APPROVED_NODE_COLORS.notTakenStroke,
+        fill: APPROVED_NODE_COLORS.fill,
+        title: '#334155',
+        description: '#475569',
+        width: 'hairline',
+        dash: true,
+        opacity: undefined,
+        marker: false,
+    },
+    indeterminate: {
+        stroke: APPROVED_NODE_COLORS.nodeBorder,
+        fill: APPROVED_NODE_COLORS.fill,
+        title: '#0f172a',
+        description: '#475569',
+        width: 'hairline',
+        dash: false,
+        opacity: undefined,
+        marker: false,
+    },
+};
+/**
+ * The count badge's declared roles (DESIGN.md `count-badge` 218-222, `rounded.full`).
+ *
+ * Exported as DATA and not emitted as a `style` property, because Mermaid 12 has no way to paint a plate behind one
+ * span of a node label: the badge reaches the definition as label TEXT (`×997`) in the node's single label colour.
+ * A host that draws its own legend or inspector chip reads the plate roles from here, so the two surfaces cannot
+ * disagree about what a badge looks like. Emitting it as label text is what AD-23 requires anyway — run-state
+ * content is stage 1's, and `securityLevel: 'strict'` routes a label through DOMPurify.
+ */
+export const REPEAT_BADGE_ROLES = {
+    background: '#ffffff',
+    foreground: '#9a3412',
+    border: '#c2410c',
+    borderWidth: STROKE_ROLES.hairline,
+    radius: '9999px',
+};
+/** An opacity Mermaid will accept in a `style` statement: a decimal in `[0,1]`, nothing else. */
+function usableOpacity(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (!/^(?:0?\.\d+|0|1(?:\.0+)?)$/.test(trimmed))
+        return undefined;
+    /**
+     * `0` is rejected on purpose, and it is not a formatting quibble: Mermaid honours node opacity as
+     * `opacity:0 !important`, so `opacity:0` draws a node that is present in the DOM, present in the layout, and
+     * invisible — label included. A run reading that erases the step it describes is worse than no reading.
+     */
+    const numeric = Number(trimmed);
+    return numeric > 0 && numeric <= 1 ? trimmed : undefined;
+}
+/** Does this entry carry a `state` — the only thing that can give the typed reading chart-wide authority? */
+function carriesState(entry) {
+    // `?? undefined` folds a JSON `null` into "no state" without widening the declared type.
+    return (entry?.state ?? undefined) !== undefined;
+}
+/**
+ * Resolve one node's entry, given the resolved node fill (a roles-only entry's fill default) and whether the typed
+ * reading is authoritative for the chart. See `RenderOverlay.nodes` for the rules this implements.
+ */
+function resolveNodeState(entry, nodeFill, authoritative) {
+    const roles = entry?.roles;
+    const requestedRepeat = entry?.repeat;
+    const repeat = isCountableRepeat(requestedRepeat) ? requestedRepeat : undefined;
+    const declined = roles?.dash === true;
+    if (!carriesState(entry)) {
+        const stroke = overlayColor(roles?.stroke);
+        if (stroke !== undefined) {
+            /**
+             * ROLES-ONLY: exactly the roles given, and nothing the entry did not ask for.
+             *
+             * This is what lets a producer that can prove no state — the log-derived reading, where "started and never
+             * ended" is not a proven `ranFailed` — draw its caller colours byte-identically: no `color:`, no marker and no
+             * chart-wide reading unless it asks for them.
+             */
+            return {
+                state: undefined,
+                pass: 'roles',
+                style: {
+                    stroke,
+                    // `emphasis` or the default `hairline`; any other value — `dash` included, a pattern not a weight — is hairline.
+                    width: roles?.width === 'emphasis' ? STROKE_ROLES.emphasis : STROKE_ROLES.hairline,
+                    fill: overlayColor(roles?.fill) ?? nodeFill,
+                    color: overlayColor(roles?.title),
+                    opacity: usableOpacity(roles?.opacity),
+                    dash: declined ? STROKE_ROLES.dash : undefined,
+                },
+                declined,
+                reached: true,
+                marker: roles?.marker === true,
+                repeat,
+            };
+        }
+        // No state and no drawable stroke: no style of its own, unless the chart-wide reading draws it indeterminate.
+        if (!authoritative) {
+            return { state: undefined, pass: 'none', style: undefined, declined, reached: false, marker: false, repeat };
+        }
+    }
+    /**
+     * An unrecognised `state` READS AS `indeterminate`; it never throws.
+     *
+     * The union is a compile-time promise and an overlay is runtime data: it arrives as parsed JSON from an evidence
+     * producer or as a webview `postMessage` payload, where `state: 'running'` costs one keystroke. Indexed blind,
+     * `STATE_ROLES['running']` is `undefined` and the next property read takes down the WHOLE diagram — every node,
+     * over one node's bad field.
+     */
+    const requested = entry?.state;
+    const state = requested !== undefined && Object.hasOwn(STATE_ROLES, requested)
+        ? requested
+        : INDETERMINATE_RUN_STATE;
+    const declared = STATE_ROLES[state];
+    /**
+     * **The three non-chromatic channels follow the STATE, never the override.**
+     *
+     * `emphasis` width, the error marker and the dimming are the failure signals a reader without colour vision has,
+     * and UX-DR52 makes all three unconditional. Honouring an override on them let a caller put the marker and 2px on a
+     * `ranOk` node, take both off a `ranFailed` one, or dim a `branchNotTaken` node DESIGN.md says is never dimmed —
+     * each of which breaks "exactly one node on this canvas is 2px / marked / dashed / dimmed", the property the whole
+     * accessibility argument rests on.
+     *
+     * So beside a state `roles.width`, `roles.dash` and `roles.marker` are ignored, and `roles.opacity` may only retune
+     * a state that is already dimmed. COLOUR overrides stay fully honoured: a host resolving its own theme is exactly
+     * what AD-23 stage 2 asks for, and a colour cannot move a node into a channel it does not own.
+     */
+    const opacity = declared.opacity === undefined
+        ? undefined
+        : (usableOpacity(roles?.opacity) ?? declared.opacity);
+    /**
+     * A STATED entry outside the chart-wide reading can only be a DERIVED one (a caller state takes the chart): it keeps
+     * its label content, as it always has, and draws no style — only a caller statement restyles the drawing.
+     */
+    const drawn = authoritative;
+    return {
+        state,
+        pass: drawn ? 'state' : 'none',
+        style: drawn
+            ? {
+                stroke: overlayColor(roles?.stroke) ?? declared.stroke,
+                fill: overlayColor(roles?.fill) ?? declared.fill,
+                color: overlayColor(roles?.title) ?? declared.title,
+                width: STROKE_ROLES[declared.width],
+                dash: declared.dash ? STROKE_ROLES.dash : undefined,
+                opacity,
+            }
+            : undefined,
+        // A stateless entry drawn indeterminate keeps its declined dash; a stated one declines only as `branchNotTaken`.
+        declined: drawn && (carriesState(entry) ? state === 'branchNotTaken' : declined),
+        reached: drawn && (state === 'ranOk' || state === 'ranFailed'),
+        marker: declared.marker,
+        repeat,
+    };
+}
+/**
+ * Mermaid's own `maxTextSize` default, measured against 12.0.0 rather than read from a changelog.
+ *
+ * Exported as data because the number is the whole finding: 305 nodes (49 620 chars) of the measurement fixture draw
+ * fully and 310 (50 445 chars) draw one node. The ceiling is therefore a CHARACTER budget and scales with label
+ * length — a workflow with long step names hits it sooner, and Story 8.7's `accDescr`, which lists every node, spends
+ * part of the same budget.
+ */
+export const MERMAID_DEFAULT_MAX_TEXT_SIZE = 50_000;
+/**
+ * What a definition costs, for a caller that wants to REPORT rather than to be refused.
+ *
+ * The same arithmetic `renderMermaid` applies to `maxTextSize`, exported so a host can warn, offer to raise its own
+ * `maxTextSize`, or split a chart — all of which are better answers than an exception, and none of which the generator
+ * can choose on a caller's behalf.
+ */
+export function measureDefinitionBudget(definition, budget = MERMAID_DEFAULT_MAX_TEXT_SIZE) {
+    return {
+        characters: definition.length,
+        budget,
+        overBudget: definition.length > budget,
+    };
+}
+/**
+ * The refusal. Carries the numbers, because "too big" without them tells a host nothing it can act on.
+ *
+ * A throw and not a truncated string: the alternative the measurement documents — hand the host the oversized
+ * definition and let Mermaid quietly draw one node — is the exact failure this exists to prevent, and a caller that
+ * would rather warn than fail has `measureDefinitionBudget` and simply does not pass `maxTextSize`.
+ */
+export class DefinitionOverBudgetError extends Error {
+    budgetReport;
+    constructor(budgetReport) {
+        super(`Mermaid definition is ${budgetReport.characters} characters, over the host's maxTextSize of ${budgetReport.budget}. ` +
+            'Mermaid renders an oversized definition as a single node WITHOUT reporting an error, and mermaid.parse() ' +
+            'resolves on it, so this is refused here rather than drawn wrongly. Raise the host maxTextSize explicitly, ' +
+            'shorten labels, or split the chart.');
+        this.budgetReport = budgetReport;
+        this.name = 'DefinitionOverBudgetError';
+    }
+}
+/**
+ * Words reserved by the generator's established flowchart contract.
+ *
+ * These words remain generator-owned grammar tokens rather than accepted identifiers in this established contract.
  */
 const MERMAID_RESERVED = new Set([
     'end',
@@ -59,30 +426,193 @@ const MERMAID_RESERVED = new Set([
 ]);
 /** Mermaid's own spelling: a chart is `TD`, a subgraph is `TB`. */
 const subgraphDirection = (direction) => direction === 'TD' ? 'TB' : 'LR';
-/**
- * A label, safe inside `["…"]`.
- *
- * ⚠️ Escaping lives HERE, and Story 4.2's review is why it is written down: the frontend port moved escaping out of
- * the model layer without recording that it had moved, and **4 real labels carry a raw newline**
- * (`ShoplinePublicApp.yaml`). A renderer that forgets breaks a real connector's diagram.
- *
- * The `&` replacement comes FIRST, or the entities the later rules produce would themselves be re-escaped.
- */
-export function escapeLabel(value) {
+/** Escape authored text for an ordinary quoted Mermaid label. */
+function escapeLabelText(value) {
     return value
         .replace(/[\r\n]+/g, ' ')
         .replace(/&/g, '&amp;')
         .replace(/"/g, '&quot;')
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;')
-        .trim();
+        // A public label beginning with a backtick must remain plain text, not opt into Mermaid markdown.
+        .replace(/`/g, '&#96;');
+}
+/** Avoid `#` inside Mermaid's HTML-label style attributes; its Markdown pass rewrites a leading hash. */
+function htmlStyleColor(color) {
+    if (!color.startsWith('#'))
+        return color;
+    const hex = color.slice(1);
+    const expanded = hex.length === 3 || hex.length === 4
+        ? [...hex].map((digit) => `${digit}${digit}`).join('')
+        : hex;
+    if (expanded.length !== 6 && expanded.length !== 8)
+        return color;
+    const red = Number.parseInt(expanded.slice(0, 2), 16);
+    const green = Number.parseInt(expanded.slice(2, 4), 16);
+    const blue = Number.parseInt(expanded.slice(4, 6), 16);
+    if (expanded.length === 6)
+        return `rgb(${red},${green},${blue})`;
+    const alpha = Number.parseInt(expanded.slice(6, 8), 16) / 255;
+    return `rgba(${red},${green},${blue},${alpha})`;
+}
+function renderLabelAnatomy(anatomy, accent) {
+    /**
+     * Renderer-owned HTML is the only way to give Mermaid a measurable two-column card. Authored bytes remain text:
+     * every heading and description is escaped before entering the markup, and callers cannot opt into this path by
+     * forging public `label` bytes because `labelAnatomy` is the trust boundary.
+     */
+    const icon = anatomy.icon ?? '';
+    // Geometric diamonds are optically centered by their own ink box. Arrow/operator glyphs sit low on the
+    // alphabetic baseline in VS Code's UI font, so loose hosts may optically correct those without moving the tile.
+    const iconClass = icon === '◆'
+        ? 'hx-node-card__icon'
+        : 'hx-node-card__icon hx-node-card__icon--baseline';
+    const marker = anatomy.marker === undefined
+        ? ''
+        : `<span class='hx-node-card__marker' style='margin-right:4px'>${anatomy.marker}</span>`;
+    const badge = anatomy.badge === undefined
+        ? ''
+        : `<span class='hx-node-card__badge' style='margin-left:4px'>${anatomy.badge}</span>`;
+    const description = anatomy.description === undefined
+        ? ''
+        : `<span class='hx-node-card__subtitle' style='display:block;min-width:0;overflow-wrap:anywhere;font-size:11px;line-height:1.35'>${escapeLabelText(anatomy.description)}</span>`;
+    const iconColor = htmlStyleColor(accent);
+    const tint = `color-mix(in srgb,${iconColor} 16%,transparent)`;
+    const rim = `color-mix(in srgb,${iconColor} 38%,transparent)`;
+    return `<span class='hx-node-card' style='display:grid;width:240px;min-width:240px;box-sizing:border-box;grid-template-columns:44px minmax(0,1fr);align-items:stretch;column-gap:10px;font-family:inherit;font-size:11px;line-height:1.35;text-align:left'>` +
+        `<span class='${iconClass}' style='display:inline-flex;width:44px;min-height:44px;align-items:center;justify-content:center;align-self:stretch;box-sizing:border-box;border-radius:9px;background:${tint};box-shadow:inset 0 0 0 1px ${rim};color:${iconColor};font-size:32px;line-height:1'>${icon}</span>` +
+        `<span class='hx-node-card__copy' style='display:grid;min-width:0;grid-template-rows:auto auto;row-gap:2px'>` +
+        `<span class='hx-node-card__title' style='display:block;min-width:0;font-size:12px;font-weight:650;line-height:1.3'>${marker}<strong>${escapeLabelText(anatomy.heading)}</strong>${badge}</span>` +
+        description +
+        `</span>` +
+        `</span>`;
+}
+/** A public label escaped as plain text; only structural anatomy can enable Mermaid markdown. */
+export function escapeLabel(value) {
+    return escapeLabelText(value).trim();
+}
+/**
+ * A single-line Mermaid accessibility value.
+ *
+ * Accessibility directives are grammar, not quoted labels: every line/control separator must be collapsed before
+ * authored text reaches them. Ordinary punctuation and Unicode remain visible instead of being stripped.
+ */
+function alternativeText(value) {
+    return value
+        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/** Meaningful node text, independent of strict/loose presentation markup and icon glyphs. */
+function semanticNodeText(node, entry) {
+    /**
+     * The run reaches the text alternative or it reaches this reader not at all (NFR13).
+     *
+     * A screen reader sees no stroke, no weight, no dash, no opacity and no marker — every channel the four states are
+     * drawn in. Appended only for a node the overlay actually NAMES, so the no-overlay bytes cannot move, and
+     * `indeterminate` contributes nothing because "we could not tell" is not a fact about the run.
+     */
+    const run = runStateAlternativeText(entry);
+    const withRun = (text) => run === '' ? text : `${text} — ${run}`;
+    const anatomy = node.labelAnatomy;
+    if (anatomy === undefined) {
+        return withRun(alternativeText(node.label) || alternativeText(node.address) || 'Unnamed step');
+    }
+    const heading = alternativeText(anatomy.heading);
+    const description = anatomy.description === undefined ? '' : alternativeText(anatomy.description);
+    return withRun([heading || alternativeText(node.address) || 'Unnamed step', description]
+        .filter((part) => part !== '')
+        .join(' — '));
+}
+/** Exactly one title and description for every chart, in authored group/node order. */
+function accessibilityAlternative(groups, emptyLabel, overlayNodes, 
+/** Present exactly when the typed reading is chart-wide; the SAME resolution the style passes read. */
+readingOf) {
+    const populated = groups.filter((group) => group.nodes.length > 0);
+    if (populated.length === 0) {
+        const absent = alternativeText(emptyLabel) || 'No steps';
+        return ['Empty workflow', `${absent}.`];
+    }
+    const titled = populated
+        .map((group) => group.title === undefined ? '' : alternativeText(group.title))
+        .filter((title) => title !== '');
+    const title = titled.length === 0
+        ? 'Workflow'
+        : titled.length === 1
+            ? `${titled[0]} workflow`
+            : `${titled.join(', ')} workflows`;
+    const seenNodes = new Set();
+    const description = populated
+        .map((group) => {
+        const groupTitle = group.title === undefined ? '' : alternativeText(group.title);
+        const nodes = group.nodes
+            .filter((node) => {
+            if (seenNodes.has(node.address))
+                return false;
+            seenNodes.add(node.address);
+            return true;
+        })
+            /**
+             * The text channel is resolved through `resolveNodeState`, the SAME resolution the `style` pass uses.
+             *
+             * Not a tidiness point: while the typed overlay is active the drawing gives every node a reading, so the text
+             * has to as well, and an unrecognised state has to degrade to `indeterminate` identically in both. Sharing the
+             * resolver is the only way the two channels cannot drift apart. A roles-only entry claims no state, so under
+             * the chart-wide reading it is stated as the indeterminate one.
+             */
+            .map((node) => {
+            if (readingOf === undefined)
+                return semanticNodeText(node, overlayNodes[node.address]);
+            const resolved = readingOf(node.address);
+            return semanticNodeText(node, {
+                state: resolved.state ?? INDETERMINATE_RUN_STATE,
+                repeat: resolved.repeat,
+            });
+        })
+            .join('; ');
+        return groupTitle === '' ? nodes : `${groupTitle}: ${nodes}`;
+    })
+        .join('. ');
+    return [title, description];
+}
+/**
+ * Validate the many-to-one Mermaid-id projection once, before any node, group or edge bytes are emitted.
+ *
+ * Duplicate appearances of one node address remain harmless and are still de-duplicated during emission. A group id
+ * occupies Mermaid's same identifier namespace, so it is checked even when its canonical text equals a node address.
+ */
+function assertUniqueRenderedIds(groups, multiStage) {
+    const claimed = new Map();
+    const seenNodes = new Set();
+    const claim = (kind, address) => {
+        const rendered = renderedNodeId(address);
+        const existing = claimed.get(rendered);
+        if (existing !== undefined) {
+            if (kind === 'node' && existing.kind === 'node' && existing.address === address)
+                return;
+            throw new Error(`Mermaid rendered-id collision for "${rendered}": ${existing.kind} "${existing.address}" and ${kind} "${address}"`);
+        }
+        claimed.set(rendered, { kind, address });
+    };
+    for (const group of groups) {
+        if (multiStage && group.title !== undefined)
+            claim('group', group.key);
+        for (const node of group.nodes) {
+            if (seenNodes.has(node.address))
+                continue;
+            seenNodes.add(node.address);
+            claim('node', node.address);
+        }
+    }
 }
 /**
- * A label guaranteed non-empty — because an empty one is a **mermaid parse error that kills the whole diagram**.
+ * A label guaranteed non-empty, so every emitted node has visible text.
  *
- * ⛔ Story 4.3 review, CRITICAL-1, found with the real mermaid 11 parser. `escapeLabel` ends in `.trim()`, so a label
- * that is non-empty in the model can become `''`, and `["${''}"]` is rejected outright: *"Expecting …, got
- * 'STADIUMEND'"*. Not one blank node — **no chart at all**.
+ * `escapeLabel` ends in `.trim()`, so a label that is non-empty in the model can become `''`; the fallback prevents
+ * the emitter from producing an empty node label.
  *
  * Four reachable inputs, each verified end to end through the real builders: `if: ""` on an IF step (the route graph
  * maps it to the label `''`, since only `null`/`undefined` become `'?'`), `next: '   '`, `next: '\n'`, and a SWITCH
@@ -99,14 +629,25 @@ function safeLabel(value, fallback) {
     const escapedFallback = escapeLabel(fallback);
     return escapedFallback === '' ? '?' : escapedFallback;
 }
+/**
+ * The same choice `safeLabel` makes — label, else fallback, else `'?'` — but on the RAW text.
+ *
+ * `safeLabel` returns an ESCAPED string. Handing that to `renderLabelAnatomy`, which escapes what it is given,
+ * escaped it twice: a node with no `stepKey`/`type` labelled `Load & save` drew the visible text `Load &amp; save`
+ * the moment an overlay gave it a marker or a badge. Anatomy carries raw text by contract; only the emitter escapes.
+ */
+function rawHeading(value, fallback) {
+    const trimmed = value.trim();
+    if (trimmed !== '')
+        return trimmed;
+    const trimmedFallback = fallback.trim();
+    return trimmedFallback === '' ? '?' : trimmedFallback;
+}
 /**
  * A colour mermaid's grammar accepts in a `style` / `linkStyle` declaration.
  *
- * ⛔ Story 4.3 review, CRITICAL-2. Rule 5 below used to claim a non-hex colour *"falls back to a stroke-only
- * highlight, which is still clearly visible"*. Measured against the real parser, that is false in **both**
- * directions: a bare identifier like `red` parses fine (so withholding its fill achieved nothing), while
- * `rgba(255,0,0,.5)`, `rgb(…)`, `hsl(…)` and `var(--x)` are **parse errors** — in `style` AND in `linkStyle`, which
- * had no guard at all. So the documented safety net did not exist, and the chart died instead of degrading.
+ * The Mermaid 12 characterization proves a bare identifier like `red` parses and is emitted stroke-only.
+ * Function-valued colours and CSS variables are outside the emitter's literal grammar and are withheld.
  *
  * It matters more here than in the Vue caller it was ported from: this is a published library whose contract invites
  * the caller to supply a colour, and a theme token (`var(--vscode-focusBorder)`, an `rgba` from a palette) is the most
@@ -118,22 +659,82 @@ function usableColor(color) {
     if (color === undefined)
         return undefined;
     const trimmed = color.trim();
-    // `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, or a bare identifier — the two forms the grammar takes.
-    return /^#[0-9a-fA-F]{3,8}$/.test(trimmed) ||
+    // Mermaid accepts only CSS's legal hex lengths: RGB, RGBA, RRGGBB and RRGGBBAA.
+    return /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(trimmed) ||
         /^[A-Za-z][A-Za-z0-9-]*$/.test(trimmed)
         ? trimmed
         : undefined;
 }
-/** One node line, shaped by what the node is. */
-function nodeLine(node) {
+/**
+ * The OVERLAY colour grammar — narrower than `usableColor`, and deliberately so (Story 8.7, FR57/FR58).
+ *
+ * Every `fill:` the emitter writes must be opaque six-digit hex, and a run-state colour reaches both a stroke and a
+ * polygon fill, so six-digit hex is the only form the emitter can honour completely. `#f00`, `#f00a`, `#ff000080`
+ * and a bare identifier like `orange` parse but cannot be honoured, and the shipped behaviour — keep the stroke,
+ * silently drop the fill — is a half-applied highlight that reads as a different run state.
+ *
+ * So the whole highlight for that dimension is dropped: no node `style`, no `linkStyle`. AD-23 stage 2 and Story
+ * 10.3 both require a host to resolve its theme token to literal hex before calling, so nothing loses a capability
+ * it was meant to have.
+ */
+function overlayColor(color) {
+    if (color === undefined)
+        return undefined;
+    const trimmed = color.trim();
+    return /^#[0-9a-fA-F]{6}$/.test(trimmed) ? trimmed : undefined;
+}
+/** One node line, shaped by its approved treatment and labelled for the requested host fidelity. */
+function nodeLine(node, fidelity, accent, content) {
     const id = renderedNodeId(node.address);
-    // The address is the fallback: never empty, and it names the node a reader can look up.
-    const label = safeLabel(node.label, node.address);
-    if (node.decides === true)
-        return `    ${id}{"${label}"}`;
-    if (node.terminal === true)
-        return `    ${id}(["${label}"])`;
-    return `    ${id}["${label}"]`;
+    const sourceLabel = fidelity === 'loose' ? (node.looseLabel ?? node.label) : node.label;
+    const baseAnatomy = fidelity === 'loose'
+        ? (node.looseLabelAnatomy ?? (node.looseLabel === undefined ? node.labelAnatomy : undefined))
+        : node.labelAnatomy;
+    const marker = content?.marker === true ? RUN_STATE_ERROR_MARKER.glyph : undefined;
+    const badge = repeatBadgeText(content?.repeat);
+    /**
+     * Run-state content is grafted onto the anatomy HERE rather than in the composer, because the composer runs in the
+     * host that builds the model and the overlay is an ARGUMENT to this render (AD-29). `composeNodeLabelModel` takes
+     * the same content for a caller that composes its own labels; this path covers every model already built.
+     *
+     * A node with no anatomy — `composeNodeLabelModel`'s early return, a node with neither `stepKey` nor `type` — gets
+     * one synthesised from its plain label the moment it carries a marker or a badge. Dropping a run fact because a
+     * step had no key would hide a failure.
+     */
+    const anatomy = marker === undefined && badge === undefined
+        ? baseAnatomy
+        : {
+            ...(baseAnatomy ?? { heading: rawHeading(sourceLabel, node.address) }),
+            ...(marker ? { marker } : {}),
+            ...(badge ? { badge } : {}),
+        };
+    const treatment = classifyNodeTreatment(node);
+    const label = anatomy
+        ? renderLabelAnatomy(anatomy, accent)
+        : safeLabel(sourceLabel, node.address);
+    const iconFamily = treatment === 'exception'
+        ? 'terminal.error'
+        : treatment === 'unimplemented'
+            ? 'unmapped'
+            : treatment === 'delay'
+                ? 'wait.sleep'
+                : node.iconFamily;
+    const iconClass = `:::${stepIconClassName(iconFamily)}`;
+    switch (treatment) {
+        case 'flow-start':
+        case 'flow-end':
+            return `    ${id}(["${label}"])${iconClass}`;
+        case 'branch':
+            return `    ${id}{{"${label}"}}${iconClass}`;
+        case 'subroutine':
+            return `    ${id}[["${label}"]]${iconClass}`;
+        case 'delay':
+            return `    ${id}@{ shape: delay, label: "${label}" }`;
+        case 'process':
+        case 'exception':
+        case 'unimplemented':
+            return `    ${id}("${label}")${iconClass}`;
+    }
 }
 function edgeLine(edge) {
     const from = renderedNodeId(edge.from);
@@ -150,26 +751,160 @@ function edgeLine(edge) {
         : `    ${from} -->|"${label}"| ${to}`;
 }
 /**
- * A per-element node style: a strong border, plus a fill tint only when the colour admits one.
+ * A per-element node run-state style.
  *
- * The fill is 8-digit-hex alpha, so it needs exactly 6 hex digits to append to — which is the REAL reason a named
- * colour gets no fill. (Rule 5's comma story is true of `rgba(…)` and was never true of `red`; the caller's colour is
- * validated by `usableColor` before it reaches here, so the comma case can no longer arrive at all.)
+ * Width comes from the declared role table, never a literal, and the fill is the opaque node fill. The
+ * alpha-suffixed `fill:#rrggbb24` tint the shipped emitter wrote is gone: Mermaid does not apply an 8-digit fill
+ * reliably to a polygon, and FR58 caps a `fill:` value at seven characters.
  */
-function nodeStyle(address, color) {
-    const fill = /^#[0-9a-fA-F]{6}$/.test(color) ? `,fill:${color}24` : '';
-    return `  style ${renderedNodeId(address)} stroke:${color},stroke-width:3px${fill}`;
+function nodeStyle(node, color, fill, width, extra) {
+    /**
+     * The three Story 8.8 properties are appended CONDITIONALLY, each measured against Mermaid 12.0.0 on 2026-09-28 at
+     * `securityLevel: 'strict'`:
+     *
+     *  1. `opacity:0.7` is honoured on a plain rect AND on a hexagon polygon — it reaches the SVG as
+     *     `opacity:0.7 !important`.
+     *  2. `color:#hex` is honoured and reaches the label, but paints the WHOLE label one colour (see `resolveNodeState`).
+     *  3. `stroke-dasharray:6 3` is honoured on a NODE, not only on a `linkStyle`.
+     *
+     * Conditional and not unconditional because an always-emitted property would write `opacity:1` onto every node and
+     * move every overlay-free golden — the byte-identity AD-23 requires.
+     */
+    const properties = [
+        `stroke:${color}`,
+        `stroke-width:${width}`,
+        `fill:${fill}`,
+        ...(extra?.color === undefined ? [] : [`color:${extra.color}`]),
+        ...(extra?.opacity === undefined ? [] : [`opacity:${extra.opacity}`]),
+        ...(extra?.dash === undefined ? [] : [`stroke-dasharray:${extra.dash}`]),
+    ];
+    return `  style ${renderedNodeId(node.address)} ${properties.join(',')}`;
+}
+/** A node `style` statement from one resolved reading — the state pass and the roles-only pass both write this. */
+function resolvedNodeStyle(node, style) {
+    return nodeStyle(node, style.stroke, style.fill, style.width, {
+        color: style.color,
+        opacity: style.opacity,
+        dash: style.dash,
+    });
+}
+/** The base and kind roles, each host override checked and every unusable one falling back to the approved role. */
+function resolveNodeColors(requested) {
+    return {
+        // A fill reaches a polygon, so it obeys FR58's six-digit form rather than the looser stroke grammar.
+        fill: overlayColor(requested?.fill) ?? APPROVED_NODE_COLORS.fill,
+        nodeBorder: usableColor(requested?.nodeBorder) ?? APPROVED_NODE_COLORS.nodeBorder,
+        failStroke: usableColor(requested?.failStroke) ?? APPROVED_NODE_COLORS.failStroke,
+        edge: usableColor(requested?.edge) ?? APPROVED_NODE_COLORS.edge,
+        notTakenStroke: usableColor(requested?.notTakenStroke) ?? APPROVED_NODE_COLORS.notTakenStroke,
+        edgeLabelText: usableColor(requested?.edgeLabelText) ?? APPROVED_NODE_COLORS.edgeLabelText,
+        // The plate is a FILL, so it obeys FR58 rather than the looser stroke grammar.
+        edgeLabelBg: overlayColor(requested?.edgeLabelBg) ?? APPROVED_NODE_COLORS.edgeLabelBg,
+    };
+}
+/** Kind/polygon styling. Run state suppresses this complete statement when both dimensions collide. */
+function kindStyle(node, colors) {
+    const fill = colors.fill;
+    const treatment = classifyNodeTreatment(node);
+    if (treatment === 'branch') {
+        return `  style ${renderedNodeId(node.address)} fill:${fill}`;
+    }
+    const stroke = treatment === 'exception'
+        ? usableColor(colors.failStroke)
+        : treatment === 'unimplemented'
+            ? usableColor(colors.nodeBorder)
+            : undefined;
+    if (stroke === undefined)
+        return undefined;
+    return `  style ${renderedNodeId(node.address)} stroke:${stroke},fill:${fill}`;
 }
 /**
  * The diagram.
  *
  * Deterministic for a given `(groups, edges, opts)`: every list is emitted in the order given, duplicates are
  * collapsed by first appearance, and nothing consults the clock or the environment.
+ *
+ * The font each host must pin (AD-32(a)): this generator emits no font. A host picks one font string and passes
+ * it to mermaid as both `fontFamily` and `themeVariables.fontFamily` (mermaid copies the former into the latter
+ * only when the latter is unset), and makes the canvas container's CSS `font-family` resolve to that same string,
+ * so the boxes mermaid measures match the text the host paints. Write the string in CSS-canonical form (unquoted
+ * family names) so the resolved CSS value is byte-equal to what mermaid received. Known hosts:
+ * - dashboard-v2 flow canvas: `Inter, -apple-system, system-ui, sans-serif` (`typography.fontFamily.sans`), set
+ *   on both mermaid keys and on the render container.
+ * - VS Code webview (`src/webview/flowDiagram.ts`): `var(--vscode-font-family)`, which is also the preview body
+ *   CSS (`previewHtml.ts`).
+ * - Report page (`hexasync-template-report-render` `renderHtml.ts`): not pinned yet — it passes no font, so mermaid
+ *   uses its default while the body paints `-apple-system, Segoe UI, …`.
  */
-export function renderMermaid(groups, edges, opts = {}) {
+export function renderMermaid(authoredGroups, authoredEdges, opts = {}) {
+    return renderMermaidWithOccurrences(authoredGroups, authoredEdges, opts).definition;
+}
+/** `renderMermaid`, for a caller that also needs the occurrence facts the drawing carries. */
+export function renderMermaidWithOccurrences(authoredGroups, authoredEdges, opts = {}) {
+    /**
+     * The occurrence expansion runs FIRST — before the collision check, before a single byte (FR64).
+     *
+     * Not merely early: there is no later point at which it could run. `assertUniqueRenderedIds` is what proves two
+     * occurrence addresses do not project onto one mermaid id, and it can only see nodes that already exist. A host
+     * doing this afterwards would be rewriting a validated definition, which AD-32(b) forbids outright.
+     *
+     * With no plan `expandOccurrences` returns the very arrays passed in, so the whole feature costs a
+     * `plan === undefined` test on every no-run render.
+     */
+    const expansion = expandOccurrences(authoredGroups, authoredEdges, opts.occurrences);
+    const groups = expansion.groups;
+    const edges = expansion.edges;
+    // Empty when the caller expanded first (the two flow adapters do); each of those returns its OWN expansion's set.
+    const collapsedRanges = expansion.collapsedRanges;
     const direction = opts.direction ?? 'TD';
+    const fidelity = opts.fidelity ?? 'strict';
     const multiStage = opts.multiStage ?? groups.length > 1;
-    const lines = [`flowchart ${direction}`];
+    assertUniqueRenderedIds(groups, multiStage);
+    const emptyLabel = opts.emptyLabel ?? 'No steps';
+    /**
+     * TWO maps, and the distinction is the whole of Story 8.9's regression fix.
+     *
+     *  - `callerOverlayNodes` is what the CALLER stated, and it alone decides whether the typed overlay is in charge.
+     *  - `overlayNodes` is what each node's content and style are read from: the caller's statement over the derived
+     *    occurrence badge, merged FIELD BY FIELD so a failed range keeps both its state and its `×N`.
+     *
+     * Deciding activation from the merged map made a plan on one step restyle the whole chart — see
+     * `RenderOptions.occurrenceOverlay`.
+     */
+    const callerOverlayNodes = opts.overlay?.nodes;
+    const derivedOverlayNodes = mergeNodeOverlays(opts.occurrenceOverlay, expansion.nodes);
+    const overlayNodes = mergeNodeOverlays(derivedOverlayNodes, callerOverlayNodes);
+    const nodeColors = resolveNodeColors(opts.nodeColors);
+    /**
+     * Is the TYPED reading chart-wide? Decided ONCE, here, and read by every channel that depends on it.
+     *
+     * Only a CALLER entry that carries a `state` and names an address a group actually holds decides it — an entry
+     * naming nothing on the canvas is ignored in silence, and a roles-only or badge-only entry makes no state claim to
+     * be authoritative about. Once it is, EVERY drawn node draws a state and EVERY drawn node is described as one: a
+     * chart where some nodes carry a run reading and others carry none would leave a reader unable to tell "not
+     * reached" from "not described", which is the distinction CAP-7 exists for. The unnamed ones read `indeterminate`.
+     *
+     * Computed before the accessibility text because `accTitle`/`accDescr` are the first bytes emitted; every node in
+     * `groups` is drawn, so this is the same answer the style pass would reach from `drawn`.
+     */
+    const groupAddresses = new Set(groups.flatMap((group) => group.nodes.map((node) => node.address)));
+    const typedOverlayActive = Object.entries(callerOverlayNodes ?? {}).some(([address, entry]) => carriesState(entry) && groupAddresses.has(address));
+    const readings = new Map();
+    /** Each node's ONE resolution, shared by the label, `accDescr`, every style pass and `linkStyle`. */
+    const readingOf = (address) => {
+        let reading = readings.get(address);
+        if (reading === undefined) {
+            reading = resolveNodeState(overlayNodes[address], nodeColors.fill, typedOverlayActive);
+            readings.set(address, reading);
+        }
+        return reading;
+    };
+    const [accTitle, accDescr] = accessibilityAlternative(groups, emptyLabel, overlayNodes, typedOverlayActive ? readingOf : undefined);
+    const lines = [
+        `flowchart ${direction}`,
+        `  accTitle: ${accTitle}`,
+        `  accDescr: ${accDescr}`,
+    ];
     /**
      * Nothing to draw ⇒ SAY SO (Story 4.3 review, MED-1 / MEDIUM-3).
      *
@@ -178,10 +913,13 @@ export function renderMermaid(groups, edges, opts = {}) {
      * fourth answer where the note says one of three must be chosen.
      */
     if (groups.every((group) => group.nodes.length === 0)) {
-        return [
-            ...lines,
-            `    empty["${safeLabel(opts.emptyLabel ?? 'No steps', 'No steps')}"]`,
-        ].join('\n');
+        return {
+            definition: withinBudget([
+                ...lines,
+                `    empty("${safeLabel(emptyLabel, 'No steps')}"):::${stepIconClassName(undefined)}`,
+            ].join('\n'), opts.maxTextSize),
+            collapsedRanges,
+        };
     }
     const emitted = new Set();
     const push = (line) => {
@@ -191,6 +929,7 @@ export function renderMermaid(groups, edges, opts = {}) {
         lines.push(line);
     };
     const drawn = new Set();
+    const drawnNodes = new Map();
     for (const group of groups) {
         if (multiStage && group.title !== undefined) {
             lines.push(`  subgraph ${renderedNodeId(group.key)}["${escapeLabel(group.title)}"]`);
@@ -198,96 +937,190 @@ export function renderMermaid(groups, edges, opts = {}) {
             lines.push(`    direction ${subgraphDirection(direction)}`);
         }
         for (const node of group.nodes) {
-            push(nodeLine(node));
+            if (drawn.has(node.address))
+                continue;
+            const entry = overlayNodes[node.address];
+            // Both slots come from the shared resolution, so the label can never claim a marker the style pass did not draw.
+            const resolved = entry === undefined ? undefined : readingOf(node.address);
+            const content = resolved === undefined
+                ? undefined
+                : { marker: resolved.marker, ...(resolved.repeat === undefined ? {} : { repeat: resolved.repeat }) };
+            const accent = resolved?.style?.stroke ??
+                (classifyNodeTreatment(node) === 'exception' ? nodeColors.failStroke : nodeColors.nodeBorder);
+            push(nodeLine(node, fidelity, accent, content));
             drawn.add(node.address);
+            drawnNodes.set(node.address, node);
         }
         if (multiStage && group.title !== undefined)
             lines.push('  end');
     }
+    // Mermaid 12 rejects the `:::class` suffix on general-shape syntax, so delay hooks use its class statement form.
+    for (const node of drawnNodes.values()) {
+        if (classifyNodeTreatment(node) !== 'delay')
+            continue;
+        push(`  class ${renderedNodeId(node.address)} ${stepIconClassName('wait.sleep')}`);
+    }
+    let labelledEdgeDrawn = false;
     for (const edge of edges) {
         // An edge naming a node no group drew would render mermaid's own placeholder box, silently inventing a node.
         if (!drawn.has(edge.from) || !drawn.has(edge.to))
             continue;
-        push(edgeLine(edge));
+        const line = edgeLine(edge);
+        // Tested on the EMITTED line, so a label that escapes to nothing does not buy a plate it never shows.
+        if (line.includes('-->|'))
+            labelledEdgeDrawn = true;
+        push(line);
     }
     /**
      * The overlay — per element, and AFTER the nodes so a style statement always names something already drawn.
      *
-     * `errored` is applied second deliberately: a node that both ran and failed should read as failed.
-     */
-    /**
-     * Class declarations come BEFORE the overlay (Story 4.3 review, MED-4).
-     *
-     * The commit claimed *"a chart rendered with an overlay still begins with the chart rendered without one"* — true
-     * only while `shapeClasses` was absent, because the class block was emitted after the overlay and so shifted when an
-     * overlay appeared. Classes first makes the overlay genuinely the last thing in the file, so the additive property
-     * holds for every combination rather than the subset the tests happened to cover.
-     *
-     * Still hoisted out of every subgraph, which is what rule 4 is about, and still declared once per class name.
+     * Class declarations precede base/kind styles and the run-state overlay (Story 4.3 review, MED-4). They remain
+     * hoisted out of every subgraph and declared once per class name.
      */
     for (const shapeClass of opts.shapeClasses ?? []) {
         const members = shapeClass.addresses.filter((a) => drawn.has(a));
         if (members.length === 0)
             continue;
         /**
-         * The class NAME reaches mermaid verbatim, so a space or a RESERVED WORD is a parse error (review LOW). Refused
-         * rather than emitted, because one bad class name would cost the whole chart rather than one style.
-         *
-         * `end` is the one a caller would plausibly reach for — a terminal-node class — and it is exactly the word that
-         * closes a subgraph.
+         * The class NAME reaches Mermaid verbatim, so a space or a reserved word is a parse error. The `ic-` prefix is
+         * reserved for the asset-backed icon hook; allowing a caller-defined `classDef` there would make one class mean
+         * both shape and icon styling. Invalid or reserved names are refused rather than costing the whole chart.
          */
         if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(shapeClass.name) ||
-            MERMAID_RESERVED.has(shapeClass.name.toLowerCase())) {
+            MERMAID_RESERVED.has(shapeClass.name.toLowerCase()) ||
+            shapeClass.name.toLowerCase().startsWith('ic-')) {
             continue;
         }
         push(`  classDef ${shapeClass.name} ${shapeClass.declaration}`);
         push(`  class ${members.map((a) => renderedNodeId(a)).join(',')} ${shapeClass.name}`);
     }
-    const overlay = opts.overlay;
-    if (overlay) {
-        const traversedColor = usableColor(overlay.colors?.traversed);
-        const erroredColor = usableColor(overlay.colors?.errored);
-        if (traversedColor !== undefined) {
-            for (const address of overlay.traversed ?? []) {
-                if (drawn.has(address))
-                    push(nodeStyle(address, traversedColor));
-            }
-        }
-        if (erroredColor !== undefined) {
-            for (const address of overlay.errored ?? []) {
-                if (drawn.has(address))
-                    push(nodeStyle(address, erroredColor));
-            }
-        }
-        /**
-         * Edges are styled by INDEX (`linkStyle 3 …`), which is why the index has to be the one mermaid will assign — the
-         * position of the edge among those actually emitted, not among those the model holds.
-         */
-        const highlight = new Set([
-            ...(overlay.traversed ?? []),
-            ...(overlay.errored ?? []),
-        ]);
-        const drawnEdges = edges.filter((e) => drawn.has(e.from) && drawn.has(e.to));
-        const seenEdge = new Set();
-        let index = -1;
-        for (const edge of drawnEdges) {
-            const key = edgeLine(edge);
-            if (seenEdge.has(key))
-                continue;
-            seenEdge.add(key);
-            index += 1;
-            if (!highlight.has(edge.from) || !highlight.has(edge.to))
-                continue;
-            const color = (overlay.errored ?? []).includes(edge.to) ||
-                (overlay.errored ?? []).includes(edge.from)
-                ? erroredColor
-                : traversedColor;
-            if (color !== undefined) {
-                push(`  linkStyle ${index} stroke:${color},stroke-width:3px`);
-            }
+    /**
+     * Kind styling is suppressed for every node once the typed overlay is in charge, not only for the named ones, and
+     * for a node a roles-only entry draws.
+     *
+     * DESIGN.md `node-exception-kind` / `node-stub-kind`: *"Where the node also has a run state, the run state stroke
+     * wins and only the icon carries the kind."* Under the typed overlay every node has a run state, so every node's
+     * kind stroke yields and the icon family alone carries the kind — which is also the only way a node never ends up
+     * with two competing `style` statements.
+     */
+    for (const node of drawnNodes.values()) {
+        if (typedOverlayActive || readingOf(node.address).pass === 'roles')
+            continue;
+        const style = kindStyle(node, nodeColors);
+        if (style !== undefined)
+            push(style);
+    }
+    // One `style` statement per stated (or indeterminate) node, in DRAWING order.
+    for (const node of drawnNodes.values()) {
+        const reading = readingOf(node.address);
+        if (reading.pass === 'state' && reading.style !== undefined)
+            push(resolvedNodeStyle(node, reading.style));
+    }
+    /**
+     * Roles-only statements, in the OVERLAY's own entry order — the caller's entries first, then any derived ones.
+     *
+     * Not drawing order: the retired lists wrote every traversed style and then every errored one, so a producer that
+     * lists its entries the same way keeps those bytes even where a failing step is drawn before a reached one. The
+     * overlay is part of AD-22's tuple, so its entry order is a deterministic input.
+     *
+     * The failed node is the ONE element the GENERATOR draws at `emphasis` in the log reading. A caller-supplied
+     * `shapeClasses` declaration reaches Mermaid verbatim and is NOT role-checked, so a `classDef` body may carry its
+     * own `stroke-width` — that is the caller's statement about its own class, not a second run-state emphasis.
+     */
+    for (const address of new Set([...Object.keys(callerOverlayNodes ?? {}), ...Object.keys(overlayNodes)])) {
+        const node = drawnNodes.get(address);
+        if (node === undefined)
+            continue;
+        const reading = readingOf(address);
+        if (reading.pass === 'roles' && reading.style !== undefined)
+            push(resolvedNodeStyle(node, reading.style));
+    }
+    /**
+     * A `linkStyle` for EVERY drawn edge, not only the highlighted ones — DERIVED from the per-node readings.
+     *
+     * AD-23 makes stage 1 the sole owner of edge colour, so a neutral edge that carried no declaration was leaving its
+     * colour to whatever theme the host happened to load — three surfaces, three answers. Edges are styled by INDEX
+     * (`linkStyle 3 …`), which is why the index has to be the one mermaid will assign: the position of the edge among
+     * those actually EMITTED and deduped, not among those the model holds.
+     *
+     * The three-way rule (UX-DR16):
+     *   1. an edge entering a DECLINED node — `notTakenStroke`, dashed; the only dash on the canvas. Every inbound edge
+     *      of it, because a node the run never entered was entered by no route, and it outranks a walk because reading
+     *      a contradiction as declined cannot invent a traversal;
+     *   2. an edge whose both ends were REACHED — walked, in the stroke of the end drawn at `emphasis` (target first),
+     *      else the target's stroke, so an edge touching the failed node reads as failed;
+     *   3. everything else — the neutral `edge` role, solid.
+     *
+     * A roles-only entry with an unusable stroke is not reached, so its edges fall to rule 3 — exactly the bytes the
+     * no-overlay render produces.
+     */
+    const drawnEdges = edges.filter((e) => drawn.has(e.from) && drawn.has(e.to));
+    const seenEdge = new Set();
+    let index = -1;
+    for (const edge of drawnEdges) {
+        const key = edgeLine(edge);
+        if (seenEdge.has(key))
+            continue;
+        seenEdge.add(key);
+        index += 1;
+        const target = readingOf(edge.to);
+        if (target.declined) {
+            push(`  linkStyle ${index} stroke:${nodeColors.notTakenStroke},stroke-width:${STROKE_ROLES.hairline},stroke-dasharray:${STROKE_ROLES.dash}`);
+            continue;
         }
+        const source = readingOf(edge.from);
+        const walked = target.reached && source.reached
+            ? ([target, source].find((end) => end.style?.width === STROKE_ROLES.emphasis) ?? target).style?.stroke
+            : undefined;
+        push(`  linkStyle ${index} stroke:${walked ?? nodeColors.edge},stroke-width:${STROKE_ROLES.hairline}`);
+    }
+    /**
+     * The edge-label plate — a definition byte, not a host stylesheet (AD-23).
+     *
+     * MEASURED against Mermaid 12.0.0 in `story87RoleDrivenStyles.atdd.spec.ts`: `themeVariables.edgeLabelBackground`
+     * alone is NOT enough, because the shipped theme emits `.edgeLabel rect{opacity:0.5}` and `.labelBkg` as an
+     * `rgba(…, 0.5)` — the line still shows through the text. `themeCSS` is appended AFTER the theme's own rules, so
+     * it is what actually makes the plate opaque. `pointer-events:none` keeps the label non-interactive (stage 3 owns
+     * interaction, and a label is not a target).
+     *
+     * It rides an `%%{init}%%` directive placed after the `flowchart` line rather than YAML frontmatter, measured the
+     * same way: both apply, and only the directive keeps `^flowchart <dir>` as the definition's first bytes, which
+     * three host surfaces and every golden already depend on.
+     *
+     * Emitted only when a labelled edge was actually drawn: a chart with no label must not carry configuration for
+     * one.
+     */
+    if (labelledEdgeDrawn) {
+        const css = `.edgeLabel rect { opacity: 1; } ` +
+            `.labelBkg { background-color: ${nodeColors.edgeLabelBg}; } ` +
+            `.edgeLabel, .edgeLabel p, .edgeLabel span { background-color: ${nodeColors.edgeLabelBg}; color: ${nodeColors.edgeLabelText}; pointer-events: none; }`;
+        lines.splice(1, 0, `%%{init: {"themeVariables": {"edgeLabelBackground": "${nodeColors.edgeLabelBg}"}, "themeCSS": "${css}"} }%%`);
+    }
+    return { definition: withinBudget(lines.join('\n'), opts.maxTextSize), collapsedRanges };
+}
+/**
+ * The last gate before the definition leaves the generator.
+ *
+ * Applied to BOTH return paths, including the empty-flow one — not because a one-node chart can exceed a budget, but
+ * because a budget that some return paths honour is a budget a caller cannot rely on.
+ */
+function withinBudget(definition, maxTextSize) {
+    if (maxTextSize === undefined)
+        return definition;
+    /**
+     * A budget that is not a positive finite number is REFUSED, not ignored.
+     *
+     * `NaN > n` is false, so a non-finite budget silently disabled the check — and `maxTextSize: NaN` is exactly what a
+     * host reaches by passing `Number(config.get('maxTextSize'))` on an unset setting. A budget that cannot be compared
+     * is a caller error, and treating it as "no budget" is how the silent truncation this guards comes back.
+     */
+    if (!Number.isFinite(maxTextSize) || maxTextSize <= 0) {
+        throw new RangeError(`maxTextSize must be a positive finite number of characters; received ${String(maxTextSize)}.`);
     }
-    return lines.join('\n');
+    const report = measureDefinitionBudget(definition, maxTextSize);
+    if (report.overBudget)
+        throw new DefinitionOverBudgetError(report);
+    return definition;
 }
 /**
  * A titled section with a fenced diagram, and nothing else (rule 3).