@turing-machine-js/machine 7.0.0-alpha.2 → 7.0.0-alpha.4

package/dist/index.mjs

@@ -173,6 +173,153 @@ class Reference {
 }
 _Reference_referenceBinding = new WeakMap();
 
+const movementDescriptionToLabel = {
+    'move caret left command': 'L',
+    'move caret right command': 'R',
+    'do not move carer': 'S',
+};
+const symbolCommandDescriptionToLabel = {
+    'keep symbol command': 'K',
+    'erase symbol command': 'E',
+};
+// Reserved characters in the encoded pattern string:
+//   '*'  ASCII asterisk (U+002A) — per-cell ifOtherSymbol, matches any symbol
+//        on that tape. ASCII (not a fancier glyph like U+1F7B0) so it renders
+//        in every Mermaid environment and every monospace font. A literal `*`
+//        in the alphabet is unambiguous from the marker because it's quoted
+//        (`'*'`).
+//   'B'  the tape's blank symbol shorthand (in read patterns). A literal `B`
+//        in the alphabet is unambiguous from the marker because it's quoted
+//        (`'B'`).
+//   ','  separates per-tape cells inside one pattern
+//   '|'  separates alternative patterns
+//   "'"  surrounds a literal alphabet symbol — e.g. `'0'` for literal `0`,
+//        `'X'` for literal `X`. The quoting is what visually separates literal
+//        symbols from the convention markers `*` / `B` and from the write
+//        commands `K` / `E`.
+//   '\\' escape prefix — to represent any of '*', 'B', ',', '|', "'", or '\\'
+//        as a *literal* alphabet symbol *inside* the quotes (e.g. `'\''` for
+//        a literal apostrophe).
+const IF_OTHER_MARKER = '*';
+const BLANK_MARKER = 'B';
+function escapeAlphabetSymbol(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'");
+}
+function decodePatternDescription(description, alphabets) {
+    if (!description) {
+        return '?';
+    }
+    if (description === 'other symbol') {
+        return IF_OTHER_MARKER;
+    }
+    try {
+        const patternList = JSON.parse(description);
+        return patternList
+            .map((pattern) => pattern
+            .map((s, tapeIx) => {
+            if (s === null) {
+                return IF_OTHER_MARKER;
+            }
+            if (s === alphabets[tapeIx]?.[0]) {
+                return BLANK_MARKER;
+            }
+            return `'${escapeAlphabetSymbol(s)}'`;
+        })
+            .join(','))
+            .join('|');
+    }
+    catch {
+        return description;
+    }
+}
+function decodeMovement(description) {
+    if (!description) {
+        return '?';
+    }
+    return movementDescriptionToLabel[description] ?? description;
+}
+function splitUnescaped(s, sep) {
+    const parts = [];
+    let current = '';
+    let i = 0;
+    while (i < s.length) {
+        if (s[i] === '\\' && i + 1 < s.length) {
+            current += s[i + 1];
+            i += 2;
+        }
+        else if (s[i] === sep) {
+            parts.push(current);
+            current = '';
+            i += 1;
+        }
+        else {
+            current += s[i];
+            i += 1;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+function parsePatternString(s, alphabets) {
+    if (s === IF_OTHER_MARKER) {
+        return null;
+    }
+    const alternatives = splitUnescaped(s, '|');
+    return alternatives.map((alt) => {
+        const cells = splitUnescaped(alt, ',');
+        return cells.map((cell, tapeIx) => {
+            if (cell === IF_OTHER_MARKER) {
+                return null;
+            }
+            if (cell === BLANK_MARKER) {
+                return alphabets[tapeIx]?.[0] ?? cell;
+            }
+            // Literal alphabet symbols are wrapped in single quotes by
+            // `decodePatternDescription` — strip them on the way back.
+            if (cell.length >= 2 && cell.startsWith("'") && cell.endsWith("'")) {
+                return cell.slice(1, -1);
+            }
+            return cell;
+        });
+    });
+}
+const movementLabelToSymbol = {
+    L: movements.left,
+    R: movements.right,
+    S: movements.stay,
+};
+function parseMovementLabel(label) {
+    const m = movementLabelToSymbol[label];
+    if (!m) {
+        throw new Error(`unknown movement label: ${label}`);
+    }
+    return m;
+}
+function parseWriteSymbolLabel(label) {
+    if (label === 'K') {
+        return symbolCommands.keep;
+    }
+    if (label === 'E') {
+        return symbolCommands.erase;
+    }
+    // Literal alphabet symbols are wrapped in single quotes by
+    // `decodeWriteSymbol` — strip them on the way back.
+    if (label.length >= 2 && label.startsWith("'") && label.endsWith("'")) {
+        return label.slice(1, -1);
+    }
+    return label;
+}
+function decodeWriteSymbol(symbol) {
+    if (typeof symbol === 'symbol') {
+        const description = symbol.description ?? '?';
+        return symbolCommandDescriptionToLabel[description] ?? description;
+    }
+    return `'${symbol}'`;
+}
+// Format converters (toMermaid / fromMermaid) live in ./graphFormats.
+
 var __classPrivateFieldSet$4 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
@@ -529,152 +676,512 @@ _TapeBlock_generateSymbolHint = { value: (patternList) => JSON.stringify(pattern
         .map((pattern) => pattern
         .map((symbol) => (symbol === ifOtherSymbol ? null : symbol)))) };
 
-const movementDescriptionToLabel = {
-    'move caret left command': 'L',
-    'move caret right command': 'R',
-    'do not move carer': 'S',
-};
-const symbolCommandDescriptionToLabel = {
-    'keep symbol command': 'K',
-    'erase symbol command': 'E',
-};
-// Reserved characters in the encoded pattern string:
-//   '*'  ASCII asterisk (U+002A) — per-cell ifOtherSymbol, matches any symbol
-//        on that tape. ASCII (not a fancier glyph like U+1F7B0) so it renders
-//        in every Mermaid environment and every monospace font. A literal `*`
-//        in the alphabet is unambiguous from the marker because it's quoted
-//        (`'*'`).
-//   'B'  the tape's blank symbol shorthand (in read patterns). A literal `B`
-//        in the alphabet is unambiguous from the marker because it's quoted
-//        (`'B'`).
-//   ','  separates per-tape cells inside one pattern
-//   '|'  separates alternative patterns
-//   "'"  surrounds a literal alphabet symbol — e.g. `'0'` for literal `0`,
-//        `'X'` for literal `X`. The quoting is what visually separates literal
-//        symbols from the convention markers `*` / `B` and from the write
-//        commands `K` / `E`.
-//   '\\' escape prefix — to represent any of '*', 'B', ',', '|', "'", or '\\'
-//        as a *literal* alphabet symbol *inside* the quotes (e.g. `'\''` for
-//        a literal apostrophe).
-const IF_OTHER_MARKER = '*';
-const BLANK_MARKER = 'B';
-function escapeAlphabetSymbol(s) {
-    return s
-        .replace(/\\/g, '\\\\')
-        .replace(/'/g, "\\'");
-}
-function decodePatternDescription(description, alphabets) {
-    if (!description) {
-        return '?';
-    }
-    if (description === 'other symbol') {
-        return IF_OTHER_MARKER;
-    }
-    try {
-        const patternList = JSON.parse(description);
-        return patternList
-            .map((pattern) => pattern
-            .map((s, tapeIx) => {
-            if (s === null) {
-                return IF_OTHER_MARKER;
+// Graph serialization/reconstruction for State graphs. Extracted from
+// `classes/State.ts` (#180) so the State class stays focused on the runtime
+// machinery (transitions, debug, halt-stack composition). Sibling-module
+// private access to State's internals goes through the `STATE_INTERNAL`
+// Symbol re-exported from State.ts — see the @internal JSDoc there.
+//
+// Public surface is preserved: `State.toGraph` and `State.fromGraph` static
+// methods continue to exist as thin delegates to the functions in this
+// module. New consumers (e.g. #195's planned `collectStates`) will live
+// here too and share the BFS-walk shape with `toGraph`.
+/**
+ * Walks the reachable graph from `initialState` and returns a serializable
+ * `Graph`. The walk is a BFS that visits each State exactly once (keyed by
+ * the State's internal id) and emits one `GraphNode` per State plus
+ * synthetic halt-marker nodes per callable-subtree frame.
+ *
+ * Round-trips losslessly with `fromGraph` in the sense that running the
+ * rebuilt machine on the same input produces the same output — but State
+ * instance identities are NOT preserved across the cycle.
+ *
+ * See `classes/State.ts` for the runtime model these graph nodes describe;
+ * see `utilities/graphFormats.ts` for the Mermaid-flavored serialization
+ * built on top of `Graph`.
+ */
+function toGraph(initialState, tapeBlock) {
+    const nodes = {};
+    const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
+    // Pass 1: BFS-discover all reachable States; emit one GraphNode per State
+    // (wrapper or bare/regular). Wrappers and bares are separate nodes.
+    const visited = new Set();
+    const queue = [initialState];
+    const bareIds = new Set(); // ids referenced as a wrapper's bareStateId
+    while (queue.length > 0) {
+        const state = queue.shift();
+        const stateInternal = state[STATE_INTERNAL]();
+        if (visited.has(stateInternal.id)) {
+            continue;
+        }
+        visited.add(stateInternal.id);
+        if (state.isHalt) {
+            if (!(0 in nodes)) {
+                nodes[0] = {
+                    id: 0,
+                    name: stateInternal.name,
+                    isHalt: true,
+                    isHaltMarker: false,
+                    isWrapper: false,
+                    bareStateId: null,
+                    frameId: null,
+                    transitions: [],
+                    overriddenHaltStateId: null,
+                    tags: [...stateInternal.tags],
+                };
             }
-            if (s === alphabets[tapeIx]?.[0]) {
-                return BLANK_MARKER;
+            continue;
+        }
+        // Wrapper? Emit wrapper node + queue bare and override target.
+        if (stateInternal.overriddenHaltState !== null && stateInternal.bareState !== null) {
+            const bareState = stateInternal.bareState;
+            const overrideTarget = stateInternal.overriddenHaltState;
+            const bareInternal = bareState[STATE_INTERNAL]();
+            const overrideInternal = overrideTarget[STATE_INTERNAL]();
+            nodes[stateInternal.id] = {
+                id: stateInternal.id,
+                name: stateInternal.name, // composite name like "A(target)"
+                isHalt: false,
+                isHaltMarker: false,
+                isWrapper: true,
+                bareStateId: bareInternal.id,
+                frameId: null,
+                transitions: [],
+                overriddenHaltStateId: overrideInternal.id,
+                tags: [...stateInternal.tags],
+            };
+            bareIds.add(bareInternal.id);
+            queue.push(bareState);
+            queue.push(overrideTarget);
+            continue;
+        }
+        // Regular (or bare) state — build node with transitions.
+        const node = {
+            id: stateInternal.id,
+            name: stateInternal.name,
+            isHalt: false,
+            isHaltMarker: false,
+            isWrapper: false,
+            bareStateId: null,
+            frameId: null,
+            transitions: [],
+            overriddenHaltStateId: null,
+            tags: [...stateInternal.tags],
+        };
+        nodes[stateInternal.id] = node;
+        let patternIx = 0;
+        for (const [sym, { command, nextState }] of stateInternal.symbolToDataMap) {
+            let target;
+            try {
+                target = nextState instanceof State ? nextState : nextState.ref;
             }
-            return `'${escapeAlphabetSymbol(s)}'`;
-        })
-            .join(','))
-            .join('|');
+            catch {
+                patternIx += 1;
+                continue;
+            }
+            const targetInternal = target[STATE_INTERNAL]();
+            node.transitions.push({
+                pattern: decodePatternDescription(sym.description, alphabets),
+                command: command.tapesCommands.map((tc) => ({
+                    symbol: decodeWriteSymbol(tc.symbol),
+                    movement: decodeMovement(tc.movement.description),
+                })),
+                nextStateId: targetInternal.id,
+                id: `${stateInternal.id}-${patternIx}`,
+            });
+            queue.push(target);
+            patternIx += 1;
+        }
+    }
+    // Always emit real halt as a sentinel, even if no transition targets it.
+    // It anchors the `subtree -. halt .-> s0` frame-level arrow whenever a
+    // frame demand-emits one, and it's the canonical machine-halt singleton.
+    if (!(0 in nodes)) {
+        nodes[0] = {
+            id: 0,
+            name: 'halt',
+            isHalt: true,
+            isHaltMarker: false,
+            isWrapper: false,
+            bareStateId: null,
+            frameId: null,
+            transitions: [],
+            overriddenHaltStateId: null,
+            tags: [...haltState[STATE_INTERNAL]().tags],
+        };
     }
-    catch {
-        return description;
+    // Pass 2: For each bare, compute its forward-reachable set (following
+    // transitions; stopping at halt and at wrappers — both are frame
+    // boundaries).
+    const computeReach = (startId) => {
+        const reach = new Set();
+        const stack = [startId];
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (reach.has(id)) {
+                continue;
+            }
+            const node = nodes[id];
+            // `nodes[id]` is always populated for `id` that the BFS reached, so
+            // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
+            // are real boundaries — both stop reach-set expansion.
+            if (node.isHalt || node.isWrapper) {
+                continue;
+            }
+            reach.add(id);
+            for (const t of node.transitions) {
+                const target = nodes[t.nextStateId];
+                if (!target || target.isHalt || target.isWrapper) {
+                    continue;
+                }
+                stack.push(t.nextStateId);
+            }
+        }
+        return reach;
+    };
+    const reachByBare = new Map();
+    for (const bareId of bareIds) {
+        reachByBare.set(bareId, computeReach(bareId));
+    }
+    // Pass 3: Union-find on bare overlaps. Two bares merge if their reach
+    // sets share any state. Canonical representative = smallest bare-id in
+    // the component.
+    const ufParent = new Map();
+    // Note: no path compression. The union policy below ("smaller id always
+    // becomes root") keeps the tree flat — every union targets bares[0] as
+    // the root, so any node's parent IS the root. Walking up never exceeds
+    // one step. Path compression would be dead code under this invariant.
+    const ufFind = (id) => {
+        if (!ufParent.has(id)) {
+            ufParent.set(id, id);
+        }
+        let root = id;
+        while (ufParent.get(root) !== root) {
+            root = ufParent.get(root);
+        }
+        return root;
+    };
+    const ufUnion = (a, b) => {
+        const ra = ufFind(a);
+        const rb = ufFind(b);
+        if (ra === rb)
+            return;
+        if (ra < rb) {
+            ufParent.set(rb, ra);
+        }
+        else {
+            ufParent.set(ra, rb);
+        }
+    };
+    for (const bareId of bareIds) {
+        ufFind(bareId);
+    }
+    // For each state, collect the bares that reach it; union all bares that
+    // share a state.
+    const stateToReachingBares = new Map();
+    for (const [bareId, reachSet] of reachByBare) {
+        for (const stateId of reachSet) {
+            let bares = stateToReachingBares.get(stateId);
+            if (!bares) {
+                bares = [];
+                stateToReachingBares.set(stateId, bares);
+            }
+            bares.push(bareId);
+        }
+    }
+    for (const bares of stateToReachingBares.values()) {
+        for (let i = 1; i < bares.length; i += 1) {
+            ufUnion(bares[0], bares[i]);
+        }
+    }
+    // Assign frameId to each in-reach state.
+    const frameIds = new Set();
+    for (const [stateId, bares] of stateToReachingBares) {
+        const frameId = ufFind(bares[0]);
+        nodes[stateId].frameId = frameId;
+        frameIds.add(frameId);
+    }
+    // Pass 4: Retarget halt-bound transitions for in-frame states to the
+    // frame's halt marker. Out-of-frame states (top-level dispatcher, override
+    // targets, etc.) keep their halt-bound transitions pointing at real halt.
+    for (const node of Object.values(nodes)) {
+        if (node.frameId === null) {
+            continue;
+        }
+        const haltMarkerId = -node.frameId;
+        for (const t of node.transitions) {
+            const target = nodes[t.nextStateId];
+            if (target && target.isHalt && !target.isHaltMarker) {
+                t.nextStateId = haltMarkerId;
+            }
+        }
     }
-}
-function decodeMovement(description) {
-    if (!description) {
-        return '?';
+    // Pass 5: Emit one halt marker per frame.
+    for (const frameId of frameIds) {
+        const haltMarkerId = -frameId;
+        nodes[haltMarkerId] = {
+            id: haltMarkerId,
+            name: 'halt',
+            isHalt: true,
+            isHaltMarker: true,
+            isWrapper: false,
+            bareStateId: null,
+            frameId,
+            transitions: [],
+            overriddenHaltStateId: null,
+            tags: [],
+        };
     }
-    return movementDescriptionToLabel[description] ?? description;
+    return { initialId: initialState[STATE_INTERNAL]().id, alphabets, nodes };
 }
-function splitUnescaped(s, sep) {
-    const parts = [];
-    let current = '';
-    let i = 0;
-    while (i < s.length) {
-        if (s[i] === '\\' && i + 1 < s.length) {
-            current += s[i + 1];
-            i += 2;
+/**
+ * Inverse of `toGraph`: rebuilds a State graph (and a fresh TapeBlock with
+ * the graph's alphabets) from a serialized Graph. Round-trips with `toGraph`
+ * in the sense that running the rebuilt machine on the same input gives the
+ * same output, but the rebuilt State instances have *new* internal IDs.
+ *
+ * Under the v7 callable-subtree model (#174), graph nodes split into:
+ *   - Wrapper nodes (`isWrapper: true`, no transitions) — reconstructed via
+ *     `bareStates[bareStateId].withOverriddenHaltState(finalStates[overriddenHaltStateId])`.
+ *   - Bare/regular nodes — constructed as normal States with transitions.
+ *   - Halt + halt-marker nodes — collapse to the singleton `haltState`.
+ */
+function fromGraph(graph) {
+    const alphabetObjs = graph.alphabets.map((syms) => new Alphabet(syms));
+    const tapeBlock = TapeBlock.fromAlphabets(alphabetObjs);
+    const ids = Object.keys(graph.nodes).map(Number);
+    // Pass 1: pre-create a Reference for each non-halt non-halt-marker node
+    // (both wrappers and regulars). Halt and halt-marker nodes collapse to the
+    // singleton `haltState` and need no ref.
+    const refs = {};
+    for (const nodeId of ids) {
+        const node = graph.nodes[nodeId];
+        if (!node.isHalt) {
+            refs[nodeId] = new Reference();
+        }
+    }
+    // Convert a parsed pattern back to the symbol key the State expects.
+    const patternToKey = (parsed) => {
+        if (parsed === null) {
+            return ifOtherSymbol;
+        }
+        const flat = [];
+        for (const row of parsed) {
+            for (const cell of row) {
+                flat.push(cell === null ? ifOtherSymbol : cell);
+            }
+        }
+        return tapeBlock.symbol(flat);
+    };
+    // Pass 2: build a State for each non-wrapper non-halt non-halt-marker
+    // node. Transitions point at refs so cycles work; haltState (and halt
+    // markers, which collapse to haltState) are used directly.
+    const bareStates = {};
+    for (const nodeId of ids) {
+        const node = graph.nodes[nodeId];
+        if (node.isHalt || node.isWrapper) {
+            continue;
         }
-        else if (s[i] === sep) {
-            parts.push(current);
-            current = '';
-            i += 1;
+        const stateDefinition = {};
+        for (const t of node.transitions) {
+            const key = patternToKey(parsePatternString(t.pattern, graph.alphabets));
+            const target = graph.nodes[t.nextStateId];
+            const nextState = !target || target.isHalt
+                ? haltState
+                : refs[t.nextStateId];
+            stateDefinition[key] = {
+                command: t.command.map((c) => ({
+                    symbol: parseWriteSymbolLabel(c.symbol),
+                    movement: parseMovementLabel(c.movement),
+                })),
+                nextState,
+            };
+        }
+        // Graph-sourced names may contain `(` and `)` (composite wrapper names —
+        // although wrappers go through a separate path below, defensive
+        // construction here keeps the bypass uniform). Construct without a name
+        // and assign `name` directly through the internal accessor's setter to
+        // skip the constructor's user-facing name validation.
+        const bare = new State(stateDefinition);
+        bare[STATE_INTERNAL]().name = node.name;
+        if (node.tags.length > 0) {
+            bare.tag(...node.tags);
+        }
+        bareStates[nodeId] = bare;
+    }
+    // Pass 3: resolve every node to its final State (memoized + cycle-safe).
+    // Wrappers compose lazily via `withOverriddenHaltState` once their bare
+    // and override are resolved.
+    const finalStates = {};
+    const inProgress = new Set();
+    const getFinal = (nodeId) => {
+        if (finalStates[nodeId]) {
+            return finalStates[nodeId];
+        }
+        const node = graph.nodes[nodeId];
+        if (!node || node.isHalt) {
+            finalStates[nodeId] = haltState;
+            return haltState;
+        }
+        if (inProgress.has(nodeId)) {
+            throw new Error(`override-halt cycle at state #${nodeId}`);
+        }
+        inProgress.add(nodeId);
+        let state;
+        if (node.isWrapper) {
+            const bare = getFinal(node.bareStateId);
+            const override = getFinal(node.overriddenHaltStateId);
+            state = bare.withOverriddenHaltState(override);
+            // Apply wrapper-scoped tags (#186). Tags don't leak across wrappers
+            // sharing a bare — the wrapper instance owns its own tag set, and
+            // engine #175 memoization returns the same instance for the same
+            // (bare, override) pair, so this is idempotent across rebuilds.
+            if (node.tags.length > 0) {
+                state.tag(...node.tags);
+            }
         }
         else {
-            current += s[i];
-            i += 1;
+            state = bareStates[nodeId];
+        }
+        inProgress.delete(nodeId);
+        finalStates[nodeId] = state;
+        return state;
+    };
+    for (const nodeId of ids) {
+        getFinal(nodeId);
+    }
+    // Pass 4: bind each ref to the resolved final State so cross-node
+    // transitions land on the right instance.
+    for (const nodeId of ids) {
+        if (!graph.nodes[nodeId].isHalt) {
+            refs[nodeId].bind(finalStates[nodeId]);
         }
     }
-    parts.push(current);
-    return parts;
+    return {
+        start: finalStates[graph.initialId],
+        tapeBlock,
+        states: finalStates,
+    };
 }
-function parsePatternString(s, alphabets) {
-    if (s === IF_OTHER_MARKER) {
-        return null;
-    }
-    const alternatives = splitUnescaped(s, '|');
-    return alternatives.map((alt) => {
-        const cells = splitUnescaped(alt, ',');
-        return cells.map((cell, tapeIx) => {
-            if (cell === IF_OTHER_MARKER) {
-                return null;
-            }
-            if (cell === BLANK_MARKER) {
-                return alphabets[tapeIx]?.[0] ?? cell;
+/**
+ * Returns a `Map<number, {state, transitionSymbols}>` keyed by engine
+ * `GraphNode.id`, giving downstream tooling direct access to the `State`
+ * instance + per-pattern Symbol references for breakpoint setup (#195).
+ *
+ * **Positional alignment contract.** For any `GraphTransition` whose id
+ * is `${N}-${K}`, `result.get(N)!.transitionSymbols[K]` is the Symbol
+ * the transition fires on (reference equality, not structural). The K-th
+ * entry is the K-th key from the source State's `#symbolToDataMap` in
+ * insertion order, including `ifOtherSymbol` when the user wrote one.
+ * Consumers filtering the catch-all path identity-compare against the
+ * engine-exported `ifOtherSymbol`.
+ *
+ * **Unbound-`Reference` slots.** `toGraph` increments `patternIx` even
+ * when a transition's `nextState` is an unresolved `Reference` (it
+ * `continue`s without pushing the GraphTransition). In that case
+ * `transitionSymbols[K]` is still set to the K-th Map key, but no
+ * `Graph.nodes[N].transitions` entry exists with id `${N}-${K}`. Sparse
+ * on the Graph side, dense on the `transitionSymbols` side — same
+ * indexing.
+ *
+ * **Coverage.** Map keys are the State-backed subset of `graph.nodes`:
+ * regulars + bares + wrappers + the halt singleton (id `0`). Synthetic
+ * halt markers (id `-frameId`) are excluded — they all reach the same
+ * `haltState` object at runtime, and the named consumer
+ * ([machines-demo#37](https://github.com/mellonis/machines-demo/issues/37))
+ * surfaces halt-pause via a separate UI control, not via clicks on
+ * halt glyphs. If a future consumer needs uniform-by-id lookup, the
+ * helper can be extended additively.
+ *
+ * **Halt-singleton warning.** `result.get(0)!.state === haltState` — the
+ * process-wide halt. Toggling `.debug` on that entry affects every
+ * machine in the runtime, not just the one this map was built from.
+ */
+function collectStates(initialState, tapeBlock) {
+    // Anchor on toGraph's authoritative id set — it knows the canonical
+    // ordering of wrapper/bare/regular emission and which nodes are
+    // synthetic halt markers we have to skip. Building our own BFS would
+    // duplicate that logic; reusing the Graph guarantees collectStates'
+    // id keys never drift from toGraph's GraphTransition ids.
+    const graph = toGraph(initialState, tapeBlock);
+    // Walk the State graph to associate each State instance with its
+    // engine id. The shape mirrors toGraph's Pass 1 — visit by id, branch
+    // on halt / wrapper / regular — but only collects the (id → State)
+    // mapping. Lighter than re-running the union-find passes; no
+    // GraphNode construction.
+    const stateById = new Map();
+    const visited = new Set();
+    const queue = [initialState];
+    while (queue.length > 0) {
+        const state = queue.shift();
+        const internal = state[STATE_INTERNAL]();
+        if (visited.has(internal.id))
+            continue;
+        visited.add(internal.id);
+        stateById.set(internal.id, state);
+        if (state.isHalt)
+            continue;
+        if (internal.bareState !== null && internal.overriddenHaltState !== null) {
+            queue.push(internal.bareState);
+            queue.push(internal.overriddenHaltState);
+            continue;
+        }
+        for (const { nextState } of internal.symbolToDataMap.values()) {
+            let target;
+            try {
+                target = nextState instanceof State ? nextState : nextState.ref;
             }
-            // Literal alphabet symbols are wrapped in single quotes by
-            // `decodePatternDescription` — strip them on the way back.
-            if (cell.length >= 2 && cell.startsWith("'") && cell.endsWith("'")) {
-                return cell.slice(1, -1);
+            catch {
+                continue; // unbound Reference — skip silently, matches toGraph
             }
-            return cell;
-        });
-    });
-}
-const movementLabelToSymbol = {
-    L: movements.left,
-    R: movements.right,
-    S: movements.stay,
-};
-function parseMovementLabel(label) {
-    const m = movementLabelToSymbol[label];
-    if (!m) {
-        throw new Error(`unknown movement label: ${label}`);
-    }
-    return m;
-}
-function parseWriteSymbolLabel(label) {
-    if (label === 'K') {
-        return symbolCommands.keep;
-    }
-    if (label === 'E') {
-        return symbolCommands.erase;
-    }
-    // Literal alphabet symbols are wrapped in single quotes by
-    // `decodeWriteSymbol` — strip them on the way back.
-    if (label.length >= 2 && label.startsWith("'") && label.endsWith("'")) {
-        return label.slice(1, -1);
+            queue.push(target);
+        }
     }
-    return label;
-}
-function decodeWriteSymbol(symbol) {
-    if (typeof symbol === 'symbol') {
-        const description = symbol.description ?? '?';
-        return symbolCommandDescriptionToLabel[description] ?? description;
+    // Build the result by iterating graph.nodes — the authoritative id set
+    // minus halt markers — and dispatching on node kind. The halt singleton
+    // entry's `state` reads from `stateById` (the BFS visited haltState if
+    // any path reached it) but falls back to the module-level singleton
+    // for graphs whose only halt presence is the always-emitted sentinel.
+    const result = new Map();
+    for (const idStr of Object.keys(graph.nodes)) {
+        const id = Number(idStr);
+        const node = graph.nodes[id];
+        if (node.isHaltMarker)
+            continue; // synthetic; collapses to haltState at id 0
+        if (node.isHalt) {
+            // The real halt — always the engine-wide singleton. Prefer the
+            // BFS-visited instance for identity-equality with whatever the
+            // caller has; fall back to the module singleton when the BFS
+            // didn't reach haltState (toGraph emits id 0 unconditionally).
+            result.set(id, {
+                state: stateById.get(0) ?? haltState,
+                transitionSymbols: [],
+            });
+            continue;
+        }
+        if (node.isWrapper) {
+            result.set(id, {
+                state: stateById.get(id),
+                transitionSymbols: [],
+            });
+            continue;
+        }
+        // Regular or bare State — enumerate `#symbolToDataMap.keys()` for
+        // the patternIx alignment. The K-th key is the Symbol that
+        // `${id}-${K}` GraphTransition fires on (positional contract).
+        const state = stateById.get(id);
+        const transitionSymbols = [...state[STATE_INTERNAL]().symbolToDataMap.keys()];
+        result.set(id, { state, transitionSymbols });
     }
-    return `'${symbol}'`;
+    return result;
 }
-// Format converters (toMermaid / fromMermaid) live in ./graphFormats.
+// Note on the import cycle with `State.ts`: stateGraph.ts value-imports
+// `State`, `STATE_INTERNAL`, `haltState`, and `ifOtherSymbol`; State.ts
+// value-imports `toGraph` and `fromGraph` for its static-method delegates.
+// ESM resolves cycles via live bindings — both modules see each other's
+// exports as long as nothing at module-load reads a binding before its
+// source module finishes evaluating. All references here live inside
+// function bodies, so the cycle is safe.
 
 var __classPrivateFieldSet$1 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
@@ -687,11 +1194,33 @@ var __classPrivateFieldGet$1 = (undefined && undefined.__classPrivateFieldGet) |
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef;
+var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_tags;
 const ifOtherSymbol = Symbol('other symbol');
 // Module-private symbol used by DebugConfig setters to call State's validator
 // without exposing the validator on the public surface.
 const validateDebugFilter = Symbol('validateDebugFilter');
+/**
+ * @internal
+ *
+ * Package-private accessor key for sibling modules in
+ * `packages/machine/src` (e.g. `utilities/stateGraph.ts`, and the planned
+ * `utilities/stateCollect.ts` for #195). Re-exported from this module so
+ * sibling files can import it; intentionally NOT re-exported from the
+ * package's public `index.ts`, so downstream consumers don't see it on
+ * the supported surface.
+ *
+ * Calling `state[STATE_INTERNAL]()` returns a getter/setter view onto the
+ * State's private fields. Reads are live (they close over `this`), so the
+ * view stays in sync with subsequent mutations on the State. There's one
+ * mutating setter on the view — `name` — used exclusively by
+ * `fromGraph` to assign graph-sourced composite names (e.g. `A(target)`)
+ * that the public name validator would reject; see the JSDoc on the
+ * accessor itself.
+ *
+ * Designed in #180 with #195 in mind so its surface doesn't need to grow
+ * when `collectStates` lands.
+ */
+const STATE_INTERNAL = Symbol('State.internal');
 class DebugConfig {
     constructor(ownerState, initial) {
         _DebugConfig_ownerState.set(this, void 0);
@@ -748,6 +1277,14 @@ class State {
         // Note: toGraph / fromGraph deliberately do not serialize debug — debug is
         // a runtime concern, not part of the structural graph.
         _State_debugRef.set(this, { current: null });
+        // Out-of-band tags applied to this State (#186). Tags are visualization
+        // and debugger-tooling metadata — they don't affect runtime transition
+        // lookup or `equivalentOn` comparisons. Stored as a Set for de-duplication;
+        // exposed via the `tags` getter as a frozen array snapshot. Lives on the
+        // State INSTANCE so wrappers (from `withOverriddenHaltState`) carry tags
+        // independently of their bare's tag set — see the #175 sharing test in
+        // State.spec.ts.
+        _State_tags.set(this, new Set());
         if (stateDefinition) {
             const keys = Object.getOwnPropertyNames(stateDefinition);
             if (keys.length) {
@@ -831,8 +1368,38 @@ class State {
         }
         __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, value);
     }
+    /**
+     * Add one or more tags to this State (#186). Tags are out-of-band metadata
+     * used by visualization (`toMermaid` emits `classDef`/`class` lines) and
+     * debugger tooling — they don't affect runtime transition lookup,
+     * `equivalentOn` comparisons, or any structural identity. Chainable.
+     */
+    tag(...tags) {
+        for (const t of tags) {
+            __classPrivateFieldGet$1(this, _State_tags, "f").add(t);
+        }
+        return this;
+    }
+    /**
+     * Remove one or more tags from this State (#186). Untagging a tag the
+     * State doesn't carry is a no-op. Chainable.
+     */
+    untag(...tags) {
+        for (const t of tags) {
+            __classPrivateFieldGet$1(this, _State_tags, "f").delete(t);
+        }
+        return this;
+    }
+    /**
+     * Frozen snapshot of this State's current tags (#186). The returned array
+     * is `Object.freeze`d — mutating it throws in strict mode (which TS-emitted
+     * code uses). Order matches insertion order of the underlying Set.
+     */
+    get tags() {
+        return Object.freeze([...__classPrivateFieldGet$1(this, _State_tags, "f")]);
+    }
     /** @internal — invoked by DebugConfig setters via module-private symbol. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), validateDebugFilter)](fieldName, filter) {
+    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_tags = new WeakMap(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
         // #108 part 2: `.after` on haltState has no semantic anchor — halt is
@@ -916,6 +1483,47 @@ class State {
         innerCache.set(overriddenHaltState, new WeakRef(state));
         return state;
     }
+    /**
+     * @internal
+     *
+     * Package-private getter/setter view onto this State's private fields,
+     * for sibling modules in `packages/machine/src` (currently `stateGraph.ts`
+     * for `toGraph` / `fromGraph`, and the planned `stateCollect.ts` for
+     * #195's `collectStates`).
+     *
+     * Read access is live — the getters close over `this`, so the view
+     * stays in sync with subsequent mutations on this State. There's a
+     * single mutating setter on the view, `name`, which exists to let
+     * `fromGraph` assign graph-sourced composite names (e.g. `A(target)`)
+     * to freshly-constructed bare States. The constructor's name validator
+     * rejects parens (reserved as wrapper-composition delimiters in
+     * `withOverriddenHaltState`); the setter intentionally bypasses that
+     * check because the same delimiters appear in legitimate wrapper-bare
+     * names round-tripped through the graph.
+     *
+     * Returns a fresh view object on every call — cheap enough for the
+     * BFS-once-per-build callers, and avoids holding a reference object on
+     * every State instance. Keep this surface tight: callers should only
+     * read what they need. Adding fields here is a deliberate decision —
+     * each adds to the implicit contract sibling modules can rely on.
+     */
+    [STATE_INTERNAL]() {
+        // Aliasing `this` so the nested object-literal getters/setters below
+        // can read/write the enclosing State's private fields — getters in an
+        // object literal can't be arrow functions, so the standard arrow-
+        // captures-`this` trick doesn't apply here.
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        return {
+            get id() { return __classPrivateFieldGet$1(self, _State_id, "f"); },
+            get name() { return __classPrivateFieldGet$1(self, _State_name, "f"); },
+            set name(v) { __classPrivateFieldSet$1(self, _State_name, v, "f"); },
+            get bareState() { return __classPrivateFieldGet$1(self, _State_bareState, "f"); },
+            get overriddenHaltState() { return __classPrivateFieldGet$1(self, _State_overriddenHaltState, "f"); },
+            get symbolToDataMap() { return __classPrivateFieldGet$1(self, _State_symbolToDataMap, "f"); },
+            get tags() { return __classPrivateFieldGet$1(self, _State_tags, "f"); },
+        };
+    }
     // Single-state introspection — no traversal, no tapeBlock required.
     // Returns id, name, halt-status, override-halt target, and the list of
     // transitions out of this state with decoded write/movement labels.
@@ -950,367 +1558,36 @@ class State {
             transitions,
         };
     }
-    // Walks the State graph and emits a `Graph` data structure. v7 callable-
-    // subtree emit shape (#174):
-    //
-    // Each `withOverriddenHaltState` wrapper produces TWO graph nodes:
-    //   - A wrapper node (`isWrapper: true`, `[[composite-name]]` shape) — the
-    //     call site. No transitions of its own. `bareStateId` points to the
-    //     bare's GraphNode; `overriddenHaltStateId` points to the override
-    //     target's GraphNode.
-    //   - A bare node (`isWrapper: false`, regular shape) — the callable body.
-    //     Has the bare's transitions. Shared across all wrappers that wrap
-    //     this bare (no per-context duplication).
-    //
-    // Frames are computed via union-find on bare reachability: two bares whose
-    // forward-reachable sets overlap merge into one frame. Each frame contains
-    // its bares + body states + a single halt marker (id = `-frameId`). The
-    // canonical `frameId` is the smallest bare-id in the component.
-    //
-    // Halt-bound transitions of any in-frame state are retargeted to the
-    // frame's halt marker. The frame's `subtree -. return .-> wrapper` and
-    // `subtree -. halt .-> s0` arrows are demand-emitted by `toMermaid` from
-    // the frame structure; they're not stored as graph edges.
+    /**
+     * Walks the reachable State graph from `initialState` and returns a
+     * serializable `Graph`. Thin delegate to `utilities/stateGraph.ts`'s
+     * `toGraph` (extracted in #180); see that module for the BFS shape and
+     * v7 callable-subtree emit semantics.
+     */
     static toGraph(initialState, tapeBlock) {
-        const nodes = {};
-        const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
-        // Pass 1: BFS-discover all reachable States; emit one GraphNode per State
-        // (wrapper or bare/regular). Wrappers and bares are separate nodes.
-        const visited = new Set();
-        const queue = [initialState];
-        const bareIds = new Set(); // ids referenced as a wrapper's bareStateId
-        while (queue.length > 0) {
-            const state = queue.shift();
-            if (visited.has(__classPrivateFieldGet$1(state, _State_id, "f"))) {
-                continue;
-            }
-            visited.add(__classPrivateFieldGet$1(state, _State_id, "f"));
-            if (state.isHalt) {
-                if (!(0 in nodes)) {
-                    nodes[0] = {
-                        id: 0,
-                        name: __classPrivateFieldGet$1(state, _State_name, "f"),
-                        isHalt: true,
-                        isHaltMarker: false,
-                        isWrapper: false,
-                        bareStateId: null,
-                        frameId: null,
-                        transitions: [],
-                        overriddenHaltStateId: null,
-                    };
-                }
-                continue;
-            }
-            // Wrapper? Emit wrapper node + queue bare and override target.
-            if (__classPrivateFieldGet$1(state, _State_overriddenHaltState, "f") !== null && __classPrivateFieldGet$1(state, _State_bareState, "f") !== null) {
-                const bareState = __classPrivateFieldGet$1(state, _State_bareState, "f");
-                const overrideTarget = __classPrivateFieldGet$1(state, _State_overriddenHaltState, "f");
-                nodes[__classPrivateFieldGet$1(state, _State_id, "f")] = {
-                    id: __classPrivateFieldGet$1(state, _State_id, "f"),
-                    name: __classPrivateFieldGet$1(state, _State_name, "f"), // composite name like "A(target)"
-                    isHalt: false,
-                    isHaltMarker: false,
-                    isWrapper: true,
-                    bareStateId: __classPrivateFieldGet$1(bareState, _State_id, "f"),
-                    frameId: null,
-                    transitions: [],
-                    overriddenHaltStateId: __classPrivateFieldGet$1(overrideTarget, _State_id, "f"),
-                };
-                bareIds.add(__classPrivateFieldGet$1(bareState, _State_id, "f"));
-                queue.push(bareState);
-                queue.push(overrideTarget);
-                continue;
-            }
-            // Regular (or bare) state — build node with transitions.
-            const node = {
-                id: __classPrivateFieldGet$1(state, _State_id, "f"),
-                name: __classPrivateFieldGet$1(state, _State_name, "f"),
-                isHalt: false,
-                isHaltMarker: false,
-                isWrapper: false,
-                bareStateId: null,
-                frameId: null,
-                transitions: [],
-                overriddenHaltStateId: null,
-            };
-            nodes[__classPrivateFieldGet$1(state, _State_id, "f")] = node;
-            let patternIx = 0;
-            for (const [sym, { command, nextState }] of __classPrivateFieldGet$1(state, _State_symbolToDataMap, "f")) {
-                let target;
-                try {
-                    target = nextState instanceof _a ? nextState : nextState.ref;
-                }
-                catch {
-                    patternIx += 1;
-                    continue;
-                }
-                node.transitions.push({
-                    pattern: decodePatternDescription(sym.description, alphabets),
-                    command: command.tapesCommands.map((tc) => ({
-                        symbol: decodeWriteSymbol(tc.symbol),
-                        movement: decodeMovement(tc.movement.description),
-                    })),
-                    nextStateId: __classPrivateFieldGet$1(target, _State_id, "f"),
-                    id: `${__classPrivateFieldGet$1(state, _State_id, "f")}-${patternIx}`,
-                });
-                queue.push(target);
-                patternIx += 1;
-            }
-        }
-        // Always emit real halt as a sentinel, even if no transition targets it.
-        // It anchors the `subtree -. halt .-> s0` frame-level arrow whenever a
-        // frame demand-emits one, and it's the canonical machine-halt singleton.
-        if (!(0 in nodes)) {
-            nodes[0] = {
-                id: 0,
-                name: 'halt',
-                isHalt: true,
-                isHaltMarker: false,
-                isWrapper: false,
-                bareStateId: null,
-                frameId: null,
-                transitions: [],
-                overriddenHaltStateId: null,
-            };
-        }
-        // Pass 2: For each bare, compute its forward-reachable set (following
-        // transitions; stopping at halt and at wrappers — both are frame
-        // boundaries).
-        const computeReach = (startId) => {
-            const reach = new Set();
-            const stack = [startId];
-            while (stack.length > 0) {
-                const id = stack.pop();
-                if (reach.has(id)) {
-                    continue;
-                }
-                const node = nodes[id];
-                if (!node || node.isHalt || node.isWrapper) {
-                    continue;
-                }
-                reach.add(id);
-                for (const t of node.transitions) {
-                    const target = nodes[t.nextStateId];
-                    if (!target || target.isHalt || target.isWrapper) {
-                        continue;
-                    }
-                    stack.push(t.nextStateId);
-                }
-            }
-            return reach;
-        };
-        const reachByBare = new Map();
-        for (const bareId of bareIds) {
-            reachByBare.set(bareId, computeReach(bareId));
-        }
-        // Pass 3: Union-find on bare overlaps. Two bares merge if their reach
-        // sets share any state. Canonical representative = smallest bare-id in
-        // the component.
-        const ufParent = new Map();
-        const ufFind = (id) => {
-            if (!ufParent.has(id)) {
-                ufParent.set(id, id);
-            }
-            let root = id;
-            while (ufParent.get(root) !== root) {
-                root = ufParent.get(root);
-            }
-            // Path compression
-            let cur = id;
-            while (ufParent.get(cur) !== root) {
-                const next = ufParent.get(cur);
-                ufParent.set(cur, root);
-                cur = next;
-            }
-            return root;
-        };
-        const ufUnion = (a, b) => {
-            const ra = ufFind(a);
-            const rb = ufFind(b);
-            if (ra === rb)
-                return;
-            if (ra < rb) {
-                ufParent.set(rb, ra);
-            }
-            else {
-                ufParent.set(ra, rb);
-            }
-        };
-        for (const bareId of bareIds) {
-            ufFind(bareId);
-        }
-        // For each state, collect the bares that reach it; union all bares that
-        // share a state.
-        const stateToReachingBares = new Map();
-        for (const [bareId, reachSet] of reachByBare) {
-            for (const stateId of reachSet) {
-                let bares = stateToReachingBares.get(stateId);
-                if (!bares) {
-                    bares = [];
-                    stateToReachingBares.set(stateId, bares);
-                }
-                bares.push(bareId);
-            }
-        }
-        for (const bares of stateToReachingBares.values()) {
-            for (let i = 1; i < bares.length; i += 1) {
-                ufUnion(bares[0], bares[i]);
-            }
-        }
-        // Assign frameId to each in-reach state.
-        const frameIds = new Set();
-        for (const [stateId, bares] of stateToReachingBares) {
-            const frameId = ufFind(bares[0]);
-            nodes[stateId].frameId = frameId;
-            frameIds.add(frameId);
-        }
-        // Pass 4: Retarget halt-bound transitions for in-frame states to the
-        // frame's halt marker. Out-of-frame states (top-level dispatcher, override
-        // targets, etc.) keep their halt-bound transitions pointing at real halt.
-        for (const node of Object.values(nodes)) {
-            if (node.frameId === null) {
-                continue;
-            }
-            const haltMarkerId = -node.frameId;
-            for (const t of node.transitions) {
-                const target = nodes[t.nextStateId];
-                if (target && target.isHalt && !target.isHaltMarker) {
-                    t.nextStateId = haltMarkerId;
-                }
-            }
-        }
-        // Pass 5: Emit one halt marker per frame.
-        for (const frameId of frameIds) {
-            const haltMarkerId = -frameId;
-            nodes[haltMarkerId] = {
-                id: haltMarkerId,
-                name: 'halt',
-                isHalt: true,
-                isHaltMarker: true,
-                isWrapper: false,
-                bareStateId: null,
-                frameId,
-                transitions: [],
-                overriddenHaltStateId: null,
-            };
-        }
-        return { initialId: __classPrivateFieldGet$1(initialState, _State_id, "f"), alphabets, nodes };
-    }
-    // Inverse of toGraph: rebuilds a State graph (and a fresh TapeBlock with the
-    // graph's alphabets) from a serialized Graph. Round-trips with toGraph in
-    // the sense that running the rebuilt machine on the same input gives the
-    // same output, but the rebuilt State instances have *new* internal IDs.
-    //
-    // Under the v7 callable-subtree model (#174), graph nodes split into:
-    //   - Wrapper nodes (`isWrapper: true`, no transitions) — reconstructed via
-    //     `bareStates[bareStateId].withOverriddenHaltState(finalStates[overriddenHaltStateId])`.
-    //   - Bare/regular nodes — constructed as normal States with transitions.
-    //   - Halt + halt-marker nodes — collapse to the singleton `haltState`.
+        return toGraph(initialState, tapeBlock);
+    }
+    /**
+     * Inverse of `toGraph`: rebuilds a State graph and a fresh TapeBlock
+     * from a serialized `Graph`. Thin delegate to `utilities/stateGraph.ts`'s
+     * `fromGraph` (extracted in #180); see that module for the
+     * reconstruction pass shape (Reference pre-create, bare build, wrapper
+     * resolution via `withOverriddenHaltState`, ref binding).
+     */
     static fromGraph(graph) {
-        const alphabetObjs = graph.alphabets.map((syms) => new Alphabet(syms));
-        const tapeBlock = TapeBlock.fromAlphabets(alphabetObjs);
-        const ids = Object.keys(graph.nodes).map(Number);
-        // Pass 1: pre-create a Reference for each non-halt non-halt-marker node
-        // (both wrappers and regulars). Halt and halt-marker nodes collapse to the
-        // singleton `haltState` and need no ref.
-        const refs = {};
-        for (const nodeId of ids) {
-            const node = graph.nodes[nodeId];
-            if (!node.isHalt) {
-                refs[nodeId] = new Reference();
-            }
-        }
-        // Convert a parsed pattern back to the symbol key the State expects.
-        const patternToKey = (parsed) => {
-            if (parsed === null) {
-                return ifOtherSymbol;
-            }
-            const flat = [];
-            for (const row of parsed) {
-                for (const cell of row) {
-                    flat.push(cell === null ? ifOtherSymbol : cell);
-                }
-            }
-            return tapeBlock.symbol(flat);
-        };
-        // Pass 2: build a State for each non-wrapper non-halt non-halt-marker
-        // node. Transitions point at refs so cycles work; haltState (and halt
-        // markers, which collapse to haltState) are used directly.
-        const bareStates = {};
-        for (const nodeId of ids) {
-            const node = graph.nodes[nodeId];
-            if (node.isHalt || node.isWrapper) {
-                continue;
-            }
-            const stateDefinition = {};
-            for (const t of node.transitions) {
-                const key = patternToKey(parsePatternString(t.pattern, graph.alphabets));
-                const target = graph.nodes[t.nextStateId];
-                const nextState = !target || target.isHalt
-                    ? haltState
-                    : refs[t.nextStateId];
-                stateDefinition[key] = {
-                    command: t.command.map((c) => ({
-                        symbol: parseWriteSymbolLabel(c.symbol),
-                        movement: parseMovementLabel(c.movement),
-                    })),
-                    nextState,
-                };
-            }
-            // Graph-sourced names may contain `(` and `)` (composite wrapper names —
-            // although wrappers go through a separate path below, defensive
-            // construction here keeps the bypass uniform). Construct without a name
-            // and assign `#name` directly to skip user-facing name validation.
-            const bare = new _a(stateDefinition);
-            __classPrivateFieldSet$1(bare, _State_name, node.name, "f");
-            bareStates[nodeId] = bare;
-        }
-        // Pass 3: resolve every node to its final State (memoized + cycle-safe).
-        // Wrappers compose lazily via `withOverriddenHaltState` once their bare
-        // and override are resolved.
-        const finalStates = {};
-        const inProgress = new Set();
-        const getFinal = (nodeId) => {
-            if (finalStates[nodeId]) {
-                return finalStates[nodeId];
-            }
-            const node = graph.nodes[nodeId];
-            if (!node || node.isHalt) {
-                finalStates[nodeId] = haltState;
-                return haltState;
-            }
-            if (inProgress.has(nodeId)) {
-                throw new Error(`override-halt cycle at state #${nodeId}`);
-            }
-            inProgress.add(nodeId);
-            let state;
-            if (node.isWrapper) {
-                const bare = getFinal(node.bareStateId);
-                const override = getFinal(node.overriddenHaltStateId);
-                state = bare.withOverriddenHaltState(override);
-            }
-            else {
-                state = bareStates[nodeId];
-            }
-            inProgress.delete(nodeId);
-            finalStates[nodeId] = state;
-            return state;
-        };
-        for (const nodeId of ids) {
-            getFinal(nodeId);
-        }
-        // Pass 4: bind each ref to the resolved final State so cross-node
-        // transitions land on the right instance.
-        for (const nodeId of ids) {
-            if (!graph.nodes[nodeId].isHalt) {
-                refs[nodeId].bind(finalStates[nodeId]);
-            }
-        }
-        return {
-            start: finalStates[graph.initialId],
-            tapeBlock,
-            states: finalStates,
-        };
+        return fromGraph(graph);
+    }
+    /**
+     * Returns a `Map<number, {state, transitionSymbols}>` keyed by engine
+     * `GraphNode.id`, exposing the live `State` instance + per-pattern
+     * Symbol references for each node so downstream tooling can mutate
+     * `state.debug` by numeric id and set per-pattern breakpoints by
+     * `GraphTransition.id` (#195). Thin delegate to
+     * `utilities/stateGraph.ts`'s `collectStates`; see that module for
+     * the alignment contract, coverage rules, and halt-singleton warning.
+     */
+    static collectStates(initialState, tapeBlock) {
+        return collectStates(initialState, tapeBlock);
     }
 }
 _a = State;
@@ -1333,7 +1610,7 @@ var __classPrivateFieldGet = (undefined && undefined.__classPrivateFieldGet) ||
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _TuringMachine_tapeBlock, _TuringMachine_stack;
+var _TuringMachine_tapeBlock;
 // True iff `filter` matches `symbol` per the DebugConfig semantics.
 // undefined / [] -> never; true -> always; symbol[] -> exact membership.
 function matchFilter(filter, symbol) {
@@ -1346,7 +1623,6 @@ function matchFilter(filter, symbol) {
 class TuringMachine {
     constructor({ tapeBlock, } = {}) {
         _TuringMachine_tapeBlock.set(this, void 0);
-        _TuringMachine_stack.set(this, []);
         if (!tapeBlock) {
             throw new Error('invalid tapeBlock');
         }
@@ -1380,7 +1656,14 @@ class TuringMachine {
         try {
             __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f")[lockSymbol].check(executionSymbol);
             __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f")[lockSymbol].lock(executionSymbol);
-            const stack = __classPrivateFieldGet(this, _TuringMachine_stack, "f");
+            // Halt-stack is run-scoped, not machine-scoped (#196). Declaring it
+            // local makes that lifetime explicit and prevents leftover entries
+            // from a previous `runStepByStep` call (e.g. a build-time peek that
+            // never drained the generator) from being popped during a subsequent
+            // halt-bound transition. Before this change `#stack` was an instance
+            // field and accumulated one extra push per call when the same machine
+            // was reused.
+            const stack = [];
             let state = initialState;
             if (state.overriddenHaltState) {
                 stack.push(state.overriddenHaltState);
@@ -1455,7 +1738,7 @@ class TuringMachine {
         }
     }
 }
-_TuringMachine_tapeBlock = new WeakMap(), _TuringMachine_stack = new WeakMap();
+_TuringMachine_tapeBlock = new WeakMap();
 
 // Format converters between a Graph (the data model produced by State.toGraph
 // and consumed by State.fromGraph) and external string representations.
@@ -1498,6 +1781,79 @@ function parseMermaidId(s) {
 function frameSubgraphId(frameId) {
     return `w_${frameId}`;
 }
+// User-controlled content (state names, tag names, alphabet symbols inside
+// edge labels) is interpolated into Mermaid label strings (`"..."` wrappers
+// on nodes, wrappers, subgraphs, and edges). Mermaid's grammar terminates
+// the string on a literal `"`, and labels render via HTML/foreignObject so
+// `<`, `>`, `&` get interpreted as markup. Statement terminators (`\n`,
+// `\r`), C0 controls (except `\t`), DEL, bidi controls, and lone UTF-16
+// surrogates are encoded as numeric entities so they can't confuse the
+// tokenizer or flip text direction silently (#194).
+//
+// Printable Unicode (Cyrillic, CJK, emoji, accented Latin, etc.) passes
+// through unchanged — a tape alphabet of Cyrillic or Brainfuck glyphs
+// stays readable in the emitted `.mmd`.
+//
+// Escape is applied at the leaf — to each user-supplied fragment BEFORE
+// it's composed into a label. Structural pieces this module emits (`<br>`
+// tag separator, ` ∪ ` bare-name join, `[`, `]`, `,`, `|`, `/`, ` → `,
+// the `callable subtree of `/`callable scope: ` prefixes) are NOT escaped;
+// only user-controlled content is. fromMermaid mirrors with
+// `unescapeMermaidLabel` on each extracted leaf AFTER structural parsing,
+// so a literal `<br>` inside a state name (encoded as `&lt;br&gt;`)
+// survives the tag-split and decodes back at the leaf.
+const MERMAID_LABEL_ESCAPE_RE = /[&"<>\n\r\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\u202A-\u202E\u2066-\u2069\uD800-\uDFFF]/g;
+function escapeMermaidLabel(s) {
+    return s.replace(MERMAID_LABEL_ESCAPE_RE, (ch) => {
+        switch (ch) {
+            case '&': return '&amp;';
+            case '"': return '&quot;';
+            case '<': return '&lt;';
+            case '>': return '&gt;';
+            case '\n': return '&#10;';
+            case '\r': return '&#13;';
+            default: return `&#${ch.charCodeAt(0)};`;
+        }
+    });
+}
+// Inverse of escapeMermaidLabel. Decodes the four named entities the
+// encoder emits (`&amp;`, `&quot;`, `&lt;`, `&gt;`) plus arbitrary
+// numeric entities (`&#NN;`, `&#xHH;`) — the latter to round-trip the
+// control / bidi / lone-surrogate cases from encode. Other named entities
+// pass through unchanged: fromMermaid is strict to the dialect toMermaid
+// emits, and a future-proof full HTML-entity decoder would muddle that.
+//
+// Replacement is single-pass: each `&...;` match is consumed once with
+// no re-scanning of the substitution, so nested-looking inputs like
+// `&amp;quot;` (literal `&quot;` as user text) decode to `&quot;` not `"`.
+const MERMAID_LABEL_UNESCAPE_RE = /&(?:(amp|quot|lt|gt)|#(\d+)|#x([0-9a-fA-F]+));/g;
+function unescapeMermaidLabel(s) {
+    return s.replace(MERMAID_LABEL_UNESCAPE_RE, (match, named, dec, hex) => {
+        switch (named) {
+            case 'amp': return '&';
+            case 'quot': return '"';
+            case 'lt': return '<';
+            case 'gt': return '>';
+            default: {
+                // Code units up to U+FFFF decode via fromCharCode so lone
+                // surrogates we encoded by UTF-16 code unit round-trip exactly.
+                // Hand-edited supplementary code points (`&#x1F600;`) use
+                // fromCodePoint to produce the right surrogate pair — but only
+                // when we didn't emit them ourselves, since encode runs per code
+                // unit.
+                if (dec !== undefined) {
+                    const n = Number.parseInt(dec, 10);
+                    return n <= 0xFFFF ? String.fromCharCode(n) : String.fromCodePoint(n);
+                }
+                if (hex !== undefined) {
+                    const n = Number.parseInt(hex, 16);
+                    return n <= 0xFFFF ? String.fromCharCode(n) : String.fromCodePoint(n);
+                }
+                return match;
+            }
+        }
+    });
+}
 function toMermaid(graph) {
     const lines = [
         'flowchart TD',
@@ -1530,6 +1886,25 @@ function toMermaid(graph) {
             bucket.push(node);
         }
     }
+    // Build the visible-label string for a node — name plus, if tagged, a
+    // `<br>tag1, tag2, ...` suffix so the rendered Mermaid shows both. Tags
+    // are the source of truth on the GraphNode; `<br>` is the universal
+    // Mermaid line-break that works across renderers without `classDef`-
+    // pseudo-element hacks (#186).
+    const labelOf = (node) => {
+        const name = escapeMermaidLabel(node.name);
+        if (node.tags.length === 0)
+            return name;
+        // Per-tag escape that ALSO encodes `,` — tags are joined with `, ` and
+        // split on `,` in `splitLabelTags`, so a literal comma in user tag
+        // content would be mistaken for a separator on the way back. `,` isn't
+        // in the base escape set because it's structural in edge labels
+        // (between per-tape cells in `writes`/`moves`), where the encode pass
+        // happens after composition — different context, different escape.
+        const tagFragments = node.tags
+            .map((t) => escapeMermaidLabel(t).replace(/,/g, '&#44;'));
+        return `${name}<br>${tagFragments.join(', ')}`;
+    };
     // 1. Emit top-level nodes (real halt, non-wrapper regulars outside any frame).
     for (const node of topLevelNodes) {
         const mid = mermaidIdFor(node.id);
@@ -1537,12 +1912,12 @@ function toMermaid(graph) {
             lines.push(`  ${mid}(((halt)))`);
         }
         else {
-            lines.push(`  ${mid}["${node.name}"]`);
+            lines.push(`  ${mid}["${labelOf(node)}"]`);
         }
     }
     // 2. Emit wrappers at top level.
     for (const wrapper of wrapperNodes) {
-        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${wrapper.name}"]]`);
+        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${labelOf(wrapper)}"]]`);
     }
     // 3. `idle` sentinel.
     lines.push('  idle([idle])');
@@ -1553,19 +1928,20 @@ function toMermaid(graph) {
         const frameBareNames = frameBares
             .slice()
             .sort((a, b) => a.id - b.id)
-            .map((n) => n.name);
+            .map((n) => escapeMermaidLabel(n.name));
         const label = frameBareNames.length > 1
             ? `callable scope: ${frameBareNames.join(' ∪ ')}`
             : `callable subtree of ${frameBareNames[0] ?? frameId}`;
         lines.push(`  subgraph ${frameSubgraphId(frameId)}["${label}"]`);
         // Inner nodes — sort by id for determinism.
         for (const node of (nodesByFrame.get(frameId) ?? []).slice().sort((a, b) => a.id - b.id)) {
-            lines.push(`    ${mermaidIdFor(node.id)}["${node.name}"]`);
+            lines.push(`    ${mermaidIdFor(node.id)}["${labelOf(node)}"]`);
         }
+        // Every frame has a halt marker — `State.toGraph`'s frame-emit pass
+        // creates one for each frame. Non-null assertion is safe; a defensive
+        // null check would be dead.
         const haltMarker = haltMarkerByFrame.get(frameId);
-        if (haltMarker) {
-            lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
-        }
+        lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
         lines.push('  end');
     }
     // 5. Enter arrow.
@@ -1618,29 +1994,31 @@ function toMermaid(graph) {
     for (const frameId of frameIds) {
         if (!haltMarkerHasIncoming.get(frameId))
             continue;
-        // Return arrow — collapsed `&` ribbon over all wrappers calling this frame.
+        // Return arrow — collapsed `&` ribbon over all wrappers calling this
+        // frame. Frames only exist because at least one wrapper's bareStateId
+        // points to a bare in the frame, so `callingWrappers` is always
+        // non-empty for any frame that reached this code path.
         const callingWrappers = wrapperNodes.filter((w) => {
-            if (w.bareStateId === null)
-                return false;
             const bare = graph.nodes[w.bareStateId];
-            return !!bare && bare.frameId === frameId;
+            return bare.frameId === frameId;
         });
-        if (callingWrappers.length > 0) {
-            const targets = callingWrappers
-                .slice()
-                .sort((a, b) => a.id - b.id)
-                .map((w) => mermaidIdFor(w.id))
-                .join(' & ');
-            lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
-        }
+        const targets = callingWrappers
+            .slice()
+            .sort((a, b) => a.id - b.id)
+            .map((w) => mermaidIdFor(w.id))
+            .join(' & ');
+        lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
         if (hasNonWrapperEntry.get(frameId)) {
             lines.push(`  ${frameSubgraphId(frameId)} -. "halt" .-> s0`);
         }
     }
     // 8. Wrapper-to-override arrows (regular solid).
+    //
+    // `wrapper.overriddenHaltStateId` is always non-null on wrapper nodes
+    // (set by `State.toGraph` for every `isWrapper: true` node — it's the
+    // wrapper's override target, which a wrapper by definition has). The
+    // non-null assertion is safe; a defensive null check would be dead.
     for (const wrapper of wrapperNodes) {
-        if (wrapper.overriddenHaltStateId === null)
-            continue;
         lines.push(`  ${mermaidIdFor(wrapper.id)} --> ${mermaidIdFor(wrapper.overriddenHaltStateId)}`);
     }
     // 9. Regular transitions for non-wrapper non-halt-marker non-halt nodes.
@@ -1652,18 +2030,84 @@ function toMermaid(graph) {
             const reads = alternatives.map((alt) => `[${alt}]`).join('|');
             const writes = `[${t.command.map((c) => c.symbol).join(',')}]`;
             const moves = `[${t.command.map((c) => c.movement).join(',')}]`;
-            const label = `${reads} → ${writes}/${moves}`;
+            // Escape the WHOLE composed label — structural separators ([, ], ,,
+            // |, /, ' → ') are all in our safe ASCII set and pass through
+            // unchanged; only embedded user alphabet symbols inside `'...'` get
+            // entity-encoded. fromMermaid unescapes the captured label as the
+            // first step before structural parsing.
+            const label = escapeMermaidLabel(`${reads} → ${writes}/${moves}`);
             lines.push(`  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`);
         }
     }
+    // 10. Tags (#186) — emit one `classDef tag_<name> fill:#...` per unique
+    //     tag across all nodes, then one `class <ids> tag_<name>` line per
+    //     tag listing every node that carries it (comma-joined for compact
+    //     emit). Tag-name → CSS-class identifier sanitization replaces any
+    //     char outside `[A-Za-z0-9_-]` with `_`; tag-name uniqueness in the
+    //     emit assumes user tags are already distinct after sanitization
+    //     (collisions are user error).
+    emitTagAnnotations(lines, nodes);
     return lines.join('\n');
 }
+// Default Mermaid `classDef` palette — 6 visually distinct fill+stroke pairs,
+// selected by tag-name hash so multi-tag diagrams look readable out of the
+// box without user configuration. Users who want different colors can edit
+// the emitted Mermaid before rendering or override post-emit.
+const TAG_PALETTE = [
+    ['#fef3c7', '#92400e'], // amber
+    ['#dbeafe', '#1e40af'], // blue
+    ['#dcfce7', '#166534'], // green
+    ['#fce7f3', '#9d174d'], // pink
+    ['#ede9fe', '#5b21b6'], // violet
+    ['#fee2e2', '#991b1b'], // red
+];
+function sanitizeTagName(tag) {
+    return tag.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+function tagColor(tag) {
+    // Cheap deterministic hash — sum of char codes mod palette length. Stable
+    // across runs; same tag name always picks the same color.
+    let h = 0;
+    for (let i = 0; i < tag.length; i += 1) {
+        h = (h + tag.charCodeAt(i)) % TAG_PALETTE.length;
+    }
+    return TAG_PALETTE[h];
+}
+function emitTagAnnotations(lines, nodes) {
+    // Collect nodes per tag in node-id order so output is deterministic.
+    const nodesByTag = new Map();
+    for (const node of nodes) {
+        for (const tag of node.tags) {
+            let list = nodesByTag.get(tag);
+            if (!list) {
+                list = [];
+                nodesByTag.set(tag, list);
+            }
+            list.push(node.id);
+        }
+    }
+    if (nodesByTag.size === 0)
+        return;
+    const sortedTags = [...nodesByTag.keys()].sort();
+    for (const tag of sortedTags) {
+        const sanitized = sanitizeTagName(tag);
+        const [fill, stroke] = tagColor(tag);
+        lines.push(`  classDef tag_${sanitized} fill:${fill},stroke:${stroke}`);
+    }
+    for (const tag of sortedTags) {
+        const sanitized = sanitizeTagName(tag);
+        const ids = nodesByTag.get(tag).map((id) => mermaidIdFor(id)).join(',');
+        lines.push(`  class ${ids} tag_${sanitized}`);
+    }
+}
 // Helper: identify "the bare states" that anchor a frame's name. A bare is a
 // node referenced as some wrapper's `bareStateId`. Body states (also in-frame
 // but not bare) are excluded from the frame label.
+//
+// The caller in `toMermaid` only passes non-wrapper, non-halt-marker nodes
+// (wrappers go to a separate bucket; halt markers go to `haltMarkerByFrame`).
+// No defensive `isHalt` / `isWrapper` guards needed here.
 function isFrameBare(node, graph) {
-    if (node.isWrapper || node.isHalt)
-        return false;
     for (const other of Object.values(graph.nodes)) {
         if (other.isWrapper && other.bareStateId === node.id) {
             return true;
@@ -1705,6 +2149,42 @@ const haltArrowRegex = /^w_(\d+)\s+-\.\s+"halt"\s+\.->\s+s0$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
 // the preceding \s* and a permissive (.+); see CodeQL js/polynomial-redos.
 const alphabetsRegex = /^%%\s*alphabets:\s*(\S.*)$/;
+// Tag annotation lines (#186). Matches both `classDef tag_<sanitized>` and
+// `class <id-list> tag_<sanitized>`. ClassDef declarations are decorative
+// (palette) and discarded on parse — toMermaid will regenerate them from
+// the tag set on re-emit. `class` lines carry the actual graph-node
+// assignments; we strip the `tag_` prefix and assign each tag to each
+// listed node's `tags` array.
+//
+// Inter-token gaps are fixed at single literal spaces (matching toMermaid's
+// canonical emit) rather than `\s+`. This avoids the polynomial-ReDoS
+// pattern CodeQL flags when `\s+` surrounds a content group (see also
+// `callArrowRegex` / `returnArrowRegex` tightening in PR #182).
+const classDefTagRegex = /^classDef tag_([A-Za-z0-9_-]+) .+$/;
+const classAssignTagRegex = /^class ([sc]\d+(?:,[sc]\d+)*) tag_([A-Za-z0-9_-]+)$/;
+// Splits a node label like `"A<br>hot, sampled"` into its name and tags (#186).
+// Labels without `<br>` have no tags. Tags are comma-joined; trimmed of
+// whitespace. The `<br>` is the single source of truth for tag-name parsing —
+// `class` lines are decorative-only and not consulted here.
+//
+// Mermaid-label entities (`&lt;`, `&quot;`, etc., #194) are decoded AFTER
+// structural splitting: the `<br>` separator and `,` tag delimiter survive
+// encode unchanged, and a user state name / tag containing a literal `<br>`
+// or `,` was encoded leaf-side so it can't be confused with the structural
+// form. Decode at the leaves recovers the original characters.
+function splitLabelTags(label) {
+    const brIx = label.indexOf('<br>');
+    if (brIx < 0) {
+        return { name: unescapeMermaidLabel(label), tags: [] };
+    }
+    const name = unescapeMermaidLabel(label.slice(0, brIx));
+    const tagsStr = label.slice(brIx + '<br>'.length);
+    const tags = tagsStr
+        .split(',')
+        .map((t) => unescapeMermaidLabel(t.trim()))
+        .filter((t) => t.length > 0);
+    return { name, tags };
+}
 function fromMermaid(text) {
     const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
     let alphabets = [];
@@ -1723,6 +2203,7 @@ function fromMermaid(text) {
                 frameId: opts.frameId ?? null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: opts.tags ? [...opts.tags] : [],
             };
         }
         else {
@@ -1738,6 +2219,12 @@ function fromMermaid(text) {
                 nodes[id].bareStateId = opts.bareStateId;
             if (opts.frameId !== undefined)
                 nodes[id].frameId = opts.frameId;
+            if (opts.tags !== undefined) {
+                for (const t of opts.tags) {
+                    if (!nodes[id].tags.includes(t))
+                        nodes[id].tags.push(t);
+                }
+            }
         }
         return nodes[id];
     };
@@ -1750,6 +2237,11 @@ function fromMermaid(text) {
             alphabets = JSON.parse(am[1]);
             continue;
         }
+        // Tag annotations (#186) — classDef lines are decorative and skipped;
+        // `class` lines are parsed in the edge pass since they reference nodes
+        // by id and need those nodes already created in the first pass.
+        if (classDefTagRegex.test(line))
+            continue;
         const sgStart = line.match(subgraphStartRegex);
         if (sgStart) {
             currentFrameId = Number(sgStart[1]);
@@ -1775,17 +2267,21 @@ function fromMermaid(text) {
         }
         const wm = line.match(wrappedNodeRegex);
         if (wm) {
+            const { name, tags } = splitLabelTags(wm[2]);
             ensureNode(parseMermaidId(wm[1]), {
-                name: wm[2],
+                name,
                 isWrapper: true,
+                tags,
             });
             continue;
         }
         const rm = line.match(regularNodeRegex);
         if (rm) {
+            const { name, tags } = splitLabelTags(rm[2]);
             ensureNode(parseMermaidId(rm[1]), {
-                name: rm[2],
+                name,
                 frameId: currentFrameId,
+                tags,
             });
             continue;
         }
@@ -1802,6 +2298,19 @@ function fromMermaid(text) {
         if (returnArrowRegex.test(line) || haltArrowRegex.test(line)) {
             continue;
         }
+        // Tag class-assignment line (#186): `class s1,s5 tag_hot` — adds
+        // the tag to each listed node. Tag-name preserved as written
+        // (sanitization on emit is lossy in principle; on parse we don't
+        // un-sanitize, since the original could have any characters).
+        const tagMatch = line.match(classAssignTagRegex);
+        if (tagMatch) {
+            const ids = tagMatch[1].split(',');
+            const tagName = tagMatch[2];
+            for (const idStr of ids) {
+                ensureNode(parseMermaidId(idStr), { tags: [tagName] });
+            }
+            continue;
+        }
         // `call` arrow — sets bareStateId on each source wrapper.
         const cm = line.match(callArrowRegex);
         if (cm) {
@@ -1818,7 +2327,12 @@ function fromMermaid(text) {
         if (wo) {
             const fromId = parseMermaidId(wo[1]);
             const toId = parseMermaidId(wo[2]);
-            if (nodes[fromId] && nodes[fromId].isWrapper) {
+            // The wrapper-override regex only matches `sN --> sM` (unlabeled);
+            // since `toMermaid` only emits this shape from wrappers, the source
+            // is guaranteed to be a wrapper if `fromMermaid`'s input came from
+            // `toMermaid`. `nodes[fromId]` is always populated (first pass emits
+            // node declarations before any edge parsing).
+            if (nodes[fromId].isWrapper) {
                 nodes[fromId].overriddenHaltStateId = toId;
                 continue;
             }
@@ -1828,7 +2342,12 @@ function fromMermaid(text) {
         const tm = line.match(labeledTransitionRegex);
         if (tm) {
             const fromId = parseMermaidId(tm[1]);
-            const label = tm[2];
+            // Decode the WHOLE captured label up front (#194). Structural
+            // separators (`[`, `]`, `,`, `|`, `/`, ` → `) are all safe ASCII
+            // outside the escape set and pass through encode unchanged, so it's
+            // safe to decode before structural parsing; only embedded alphabet
+            // symbols inside `'...'` get reconstituted.
+            const label = unescapeMermaidLabel(tm[2]);
             const toId = parseMermaidId(tm[3]);
             const arrowIx = label.indexOf(' → ');
             if (arrowIx === -1) {