@turing-machine-js/machine 7.0.0-alpha.1 → 7.0.0-alpha.3

package/dist/index.mjs

@@ -347,7 +347,7 @@ var __classPrivateFieldGet$2 = (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 _a, _TapeBlock_symbolToPatternListMap, _TapeBlock_lock, _TapeBlock_tapes, _TapeBlock_generateSymbolHint, _TapeBlock_buildPatternList, _TapeBlock_getSymbolForPatternList, _TapeBlock_symbol;
+var _a$1, _TapeBlock_symbolToPatternListMap, _TapeBlock_lock, _TapeBlock_tapes, _TapeBlock_generateSymbolHint, _TapeBlock_buildPatternList, _TapeBlock_getSymbolForPatternList, _TapeBlock_symbol;
 const symbolToPatternListMapSymbol = Symbol('symbol for symbolToPatternListMap setter');
 const lockSymbol = Symbol('capture symbol');
 class TapeBlock {
@@ -386,7 +386,7 @@ class TapeBlock {
                 symbol = storedPatternListSymbol;
             }
             else {
-                symbol = Symbol(__classPrivateFieldGet$2(_a, _a, "f", _TapeBlock_generateSymbolHint).call(_a, patternList));
+                symbol = Symbol(__classPrivateFieldGet$2(_a$1, _a$1, "f", _TapeBlock_generateSymbolHint).call(_a$1, patternList));
                 __classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f").set(symbol, patternList);
             }
             return symbol;
@@ -486,10 +486,10 @@ class TapeBlock {
     clone(cloneTapes = false) {
         let tapeBlock;
         if (cloneTapes) {
-            tapeBlock = _a.fromTapes(this.tapes.map((tape) => new Tape(tape)));
+            tapeBlock = _a$1.fromTapes(this.tapes.map((tape) => new Tape(tape)));
         }
         else {
-            tapeBlock = _a.fromAlphabets(this.alphabets);
+            tapeBlock = _a$1.fromAlphabets(this.alphabets);
         }
         tapeBlock[symbolToPatternListMapSymbol] = __classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f");
         return tapeBlock;
@@ -518,12 +518,12 @@ class TapeBlock {
         }
     }
 }
-_a = TapeBlock;
+_a$1 = TapeBlock;
 TapeBlock.fromAlphabets = (alphabets) => {
-    return new _a({ alphabets });
+    return new _a$1({ alphabets });
 };
 TapeBlock.fromTapes = (tapes) => {
-    return new _a({ tapes });
+    return new _a$1({ tapes });
 };
 _TapeBlock_generateSymbolHint = { value: (patternList) => JSON.stringify(patternList
         .map((pattern) => pattern
@@ -687,7 +687,7 @@ 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, _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.
@@ -748,6 +748,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) {
@@ -760,7 +768,7 @@ class State {
             symbols.forEach((symbol) => {
                 const { nextState } = stateDefinition[symbol];
                 const nextStateLocal = nextState ?? this;
-                if (!(nextStateLocal instanceof State) && !(nextStateLocal instanceof Reference)) {
+                if (!(nextStateLocal instanceof _a) && !(nextStateLocal instanceof Reference)) {
                     throw new Error('invalid nextState');
                 }
                 let { command } = stateDefinition[symbol];
@@ -831,8 +839,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
@@ -880,16 +918,40 @@ class State {
         throw new Error(`No nextState for symbol at state named ${__classPrivateFieldGet$1(this, _State_id, "f")}`);
     }
     withOverriddenHaltState(overriddenHaltState) {
-        // Construct with no name, then overwrite #name directly — the composed
-        // name contains `(` and `)` by design, which the constructor's user-facing
-        // validation would reject. Internal composition bypasses validation via
-        // private-field access (legal within the same class).
-        const state = new State();
-        __classPrivateFieldSet$1(state, _State_name, `${this.name}(${overriddenHaltState.name})`, "f");
-        __classPrivateFieldSet$1(state, _State_symbolToDataMap, __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f"), "f");
+        // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
+        // are dead at runtime anyway (only the outermost `.wohs()`'s override is
+        // pushed onto the halt-stack on entry; verified empirically). Composite
+        // name reflects runtime behavior, not construction history. See #176.
+        const bare = __classPrivateFieldGet$1(this, _State_bareState, "f") ?? this;
+        // Memoize by (bare, override) so identical args return the same instance
+        // (#175). The cache uses WeakMaps + WeakRefs so cached wrappers can be
+        // GC'd when nothing else holds them. Compounds with the chain-collapse
+        // above: `A.wohs(t1).wohs(t2)` keys as (A, t2) after the unwrap, hitting
+        // the same cache slot as a direct `A.wohs(t2)`.
+        let innerCache = __classPrivateFieldGet$1(_a, _a, "f", _State_wrapperCache).get(bare);
+        if (innerCache !== undefined) {
+            const ref = innerCache.get(overriddenHaltState);
+            if (ref !== undefined) {
+                const cached = ref.deref();
+                if (cached !== undefined) {
+                    return cached;
+                }
+            }
+        }
+        else {
+            innerCache = new WeakMap();
+            __classPrivateFieldGet$1(_a, _a, "f", _State_wrapperCache).set(bare, innerCache);
+        }
+        // Cache miss — construct with no name, then overwrite #name directly
+        // (composed names contain `(` and `)` which the constructor's user-facing
+        // validation would reject; private-field access bypasses that).
+        const state = new _a();
+        __classPrivateFieldSet$1(state, _State_name, `${bare.name}(${overriddenHaltState.name})`, "f");
+        __classPrivateFieldSet$1(state, _State_symbolToDataMap, __classPrivateFieldGet$1(bare, _State_symbolToDataMap, "f"), "f");
         __classPrivateFieldSet$1(state, _State_overriddenHaltState, overriddenHaltState, "f");
-        __classPrivateFieldSet$1(state, _State_debugRef, __classPrivateFieldGet$1(this, _State_debugRef, "f"), "f");
-        __classPrivateFieldSet$1(state, _State_bareState, this, "f");
+        __classPrivateFieldSet$1(state, _State_debugRef, __classPrivateFieldGet$1(bare, _State_debugRef, "f"), "f");
+        __classPrivateFieldSet$1(state, _State_bareState, bare, "f");
+        innerCache.set(overriddenHaltState, new WeakRef(state));
         return state;
     }
     // Single-state introspection — no traversal, no tapeBlock required.
@@ -902,7 +964,7 @@ class State {
         for (const [sym, { command, nextState }] of __classPrivateFieldGet$1(state, _State_symbolToDataMap, "f")) {
             let target = null;
             try {
-                target = nextState instanceof State ? nextState : nextState.ref;
+                target = nextState instanceof _a ? nextState : nextState.ref;
             }
             catch {
                 target = null; // unbound Reference
@@ -926,204 +988,278 @@ class State {
             transitions,
         };
     }
-    // Walks the State graph and emits a `Graph` data structure. v7 emit shape:
-    // wrapper-States (those with `#overriddenHaltState !== null`) are collapsed
-    // onto their bare's representation in the graph, with the wrapper's own `#id`
-    // used as the graph node id, `isWrapped: true`, and `overriddenHaltStateId`
-    // set to the override's collapsed id. A per-wrapper "halt marker" graph node
-    // (id = negative-of-the-wrapper-id, `isHalt: true, isHaltMarker: true`) is
-    // synthesized; the bare's halt-bound transitions are rewritten to target the
-    // halt marker instead of the real one.
+    // 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).
     //
-    // Halt-marker node ids use the negation of the wrapper's id so they sit in a
-    // disjoint integer range from real ids (which are always non-negative). Real
-    // halt is always id 0.
+    // 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.
     static toGraph(initialState, tapeBlock) {
         const nodes = {};
         const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
-        // Map from a wrapper-State to the "collapsed" graph node id used to refer
-        // to it in transitions. Same as the wrapper's `#id`, recorded for clarity
-        // when rewriting transition targets.
-        const wrapperGraphId = (s) => __classPrivateFieldGet$1(s, _State_id, "f");
-        const haltMarkerIdFor = (wrapper) => -__classPrivateFieldGet$1(wrapper, _State_id, "f");
-        // The `initialId` is the user-passed start. If it's a wrapper, the
-        // collapsed graph node uses its `#id`; otherwise its own `#id`.
-        const initialId = __classPrivateFieldGet$1(initialState, _State_id, "f");
-        const queue = [];
-        // Decide how to enqueue the start: if it's a wrapper, enqueue its bare with
-        // the wrapper as context; otherwise enqueue the state itself.
-        if (__classPrivateFieldGet$1(initialState, _State_overriddenHaltState, "f") && __classPrivateFieldGet$1(initialState, _State_bareState, "f")) {
-            queue.push({ state: __classPrivateFieldGet$1(initialState, _State_bareState, "f"), wrapperContext: initialState });
-        }
-        else {
-            queue.push({ state: initialState, wrapperContext: null });
-        }
+        // 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, wrapperContext } = queue.shift();
+            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) {
-                // Real halt — always id 0, single node.
                 if (!(0 in nodes)) {
                     nodes[0] = {
                         id: 0,
                         name: __classPrivateFieldGet$1(state, _State_name, "f"),
                         isHalt: true,
                         isHaltMarker: false,
-                        isWrapped: false,
+                        isWrapper: false,
+                        bareStateId: null,
+                        frameId: null,
                         transitions: [],
                         overriddenHaltStateId: null,
+                        tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
                     };
                 }
                 continue;
             }
-            if (wrapperContext !== null) {
-                // Process `state` (the bare) collapsed under `wrapperContext` (the
-                // wrapper). Graph node id = wrapper's id.
-                const collapsedId = wrapperGraphId(wrapperContext);
-                if (collapsedId in nodes) {
-                    continue;
-                }
-                const haltMarkerId = haltMarkerIdFor(wrapperContext);
-                const overrideTarget = __classPrivateFieldGet$1(wrapperContext, _State_overriddenHaltState, "f");
-                // The override target's collapsed id: if the override is itself a
-                // wrapper, its graph node id is `overrideTarget.#id` (its own wrapper
-                // id); otherwise its own bare id.
-                const overrideGraphId = __classPrivateFieldGet$1(overrideTarget, _State_overriddenHaltState, "f")
-                    ? wrapperGraphId(overrideTarget)
-                    : __classPrivateFieldGet$1(overrideTarget, _State_id, "f");
-                // Emit the halt-marker node if not already present (one per wrapper).
-                if (!(haltMarkerId in nodes)) {
-                    nodes[haltMarkerId] = {
-                        id: haltMarkerId,
-                        name: 'halt',
-                        isHalt: true,
-                        isHaltMarker: true,
-                        isWrapped: false,
-                        transitions: [],
-                        overriddenHaltStateId: null,
-                    };
-                }
-                // Build the collapsed node.
-                const collapsedNode = {
-                    id: collapsedId,
-                    name: __classPrivateFieldGet$1(state, _State_name, "f"),
+            // 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,
-                    isWrapped: true,
+                    isWrapper: true,
+                    bareStateId: __classPrivateFieldGet$1(bareState, _State_id, "f"),
+                    frameId: null,
                     transitions: [],
-                    overriddenHaltStateId: overrideGraphId,
+                    overriddenHaltStateId: __classPrivateFieldGet$1(overrideTarget, _State_id, "f"),
+                    tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
                 };
-                nodes[collapsedId] = collapsedNode;
-                let patternIx = 0;
-                for (const [sym, { command, nextState }] of __classPrivateFieldGet$1(state, _State_symbolToDataMap, "f")) {
-                    let target;
-                    try {
-                        target = nextState instanceof State ? nextState : nextState.ref;
-                    }
-                    catch {
-                        patternIx += 1;
-                        continue;
-                    }
-                    // Retarget transitions per Variant X conventions:
-                    // - target == haltState → halt marker (stays inside the subgraph)
-                    // - target == bare (self-loop) → the collapsed wrapper id
-                    // - target is itself a wrapper → that wrapper's collapsed id
-                    // - else → target's own id
-                    let nextStateId;
-                    if (target.isHalt) {
-                        nextStateId = haltMarkerId;
-                    }
-                    else if (target === state) {
-                        nextStateId = collapsedId;
-                    }
-                    else if (__classPrivateFieldGet$1(target, _State_overriddenHaltState, "f") && __classPrivateFieldGet$1(target, _State_bareState, "f")) {
-                        nextStateId = wrapperGraphId(target);
-                        queue.push({ state: __classPrivateFieldGet$1(target, _State_bareState, "f"), wrapperContext: target });
-                    }
-                    else {
-                        nextStateId = __classPrivateFieldGet$1(target, _State_id, "f");
-                        queue.push({ state: target, wrapperContext: null });
-                    }
-                    collapsedNode.transitions.push({
-                        pattern: decodePatternDescription(sym.description, alphabets),
-                        command: command.tapesCommands.map((tc) => ({
-                            symbol: decodeWriteSymbol(tc.symbol),
-                            movement: decodeMovement(tc.movement.description),
-                        })),
-                        nextStateId,
-                        id: `${collapsedId}-${patternIx}`,
-                    });
-                    patternIx += 1;
-                }
-                // Enqueue the override target so its own node is emitted.
-                if (__classPrivateFieldGet$1(overrideTarget, _State_overriddenHaltState, "f") && __classPrivateFieldGet$1(overrideTarget, _State_bareState, "f")) {
-                    queue.push({ state: __classPrivateFieldGet$1(overrideTarget, _State_bareState, "f"), wrapperContext: overrideTarget });
-                }
-                else {
-                    queue.push({ state: overrideTarget, wrapperContext: null });
-                }
-                continue;
-            }
-            // Non-wrapper context: emit `state` as a regular node.
-            if (__classPrivateFieldGet$1(state, _State_id, "f") in nodes) {
+                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,
-                isWrapped: false,
+                isWrapper: false,
+                bareStateId: null,
+                frameId: null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
             };
             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 State ? nextState : nextState.ref;
+                    target = nextState instanceof _a ? nextState : nextState.ref;
                 }
                 catch {
                     patternIx += 1;
                     continue;
                 }
-                let nextStateId;
-                if (__classPrivateFieldGet$1(target, _State_overriddenHaltState, "f") && __classPrivateFieldGet$1(target, _State_bareState, "f")) {
-                    // Transition into a wrapper — use its collapsed id.
-                    nextStateId = wrapperGraphId(target);
-                    queue.push({ state: __classPrivateFieldGet$1(target, _State_bareState, "f"), wrapperContext: target });
-                }
-                else {
-                    nextStateId = __classPrivateFieldGet$1(target, _State_id, "f");
-                    queue.push({ state: target, wrapperContext: null });
-                }
                 node.transitions.push({
                     pattern: decodePatternDescription(sym.description, alphabets),
                     command: command.tapesCommands.map((tc) => ({
                         symbol: decodeWriteSymbol(tc.symbol),
                         movement: decodeMovement(tc.movement.description),
                     })),
-                    nextStateId,
+                    nextStateId: __classPrivateFieldGet$1(target, _State_id, "f"),
                     id: `${__classPrivateFieldGet$1(state, _State_id, "f")}-${patternIx}`,
                 });
+                queue.push(target);
                 patternIx += 1;
             }
         }
-        return { initialId, alphabets, nodes };
+        // 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: [...__classPrivateFieldGet$1(haltState, _State_tags, "f")],
+            };
+        }
+        // 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;
+                }
+            }
+        }
+        // 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 { 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`.
     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 node so transitions can
-        // forward-declare their targets.
+        // 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) {
-            if (!graph.nodes[nodeId].isHalt) {
+            const node = graph.nodes[nodeId];
+            if (!node.isHalt) {
                 refs[nodeId] = new Reference();
             }
         }
@@ -1140,19 +1276,22 @@ class State {
             }
             return tapeBlock.symbol(flat);
         };
-        // Pass 2: build a "bare" State for each non-halt node (no override yet).
-        // nextState entries point at refs so cycles work; haltState is used directly.
+        // 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) {
+            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.isHalt ? haltState : refs[t.nextStateId];
+                const nextState = !target || target.isHalt
+                    ? haltState
+                    : refs[t.nextStateId];
                 stateDefinition[key] = {
                     command: t.command.map((c) => ({
                         symbol: parseWriteSymbolLabel(c.symbol),
@@ -1161,14 +1300,20 @@ class State {
                     nextState,
                 };
             }
-            // Graph-sourced names may contain `(` and `)` (composite wrapper names
-            // emitted by toGraph). Bypass the constructor's user-facing name
-            // validation by constructing without a name and assigning #name directly.
-            const bare = new State(stateDefinition);
+            // 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");
+            if (node.tags.length > 0) {
+                bare.tag(...node.tags);
+            }
             bareStates[nodeId] = bare;
         }
-        // Pass 3: apply overrideHaltStates transitively.
+        // 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) => {
@@ -1176,7 +1321,7 @@ class State {
                 return finalStates[nodeId];
             }
             const node = graph.nodes[nodeId];
-            if (node.isHalt) {
+            if (!node || node.isHalt) {
                 finalStates[nodeId] = haltState;
                 return haltState;
             }
@@ -1184,9 +1329,21 @@ class State {
                 throw new Error(`override-halt cycle at state #${nodeId}`);
             }
             inProgress.add(nodeId);
-            let state = bareStates[nodeId];
-            if (node.overriddenHaltStateId !== null) {
-                state = bareStates[nodeId].withOverriddenHaltState(getFinal(node.overriddenHaltStateId));
+            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 {
+                state = bareStates[nodeId];
             }
             inProgress.delete(nodeId);
             finalStates[nodeId] = state;
@@ -1195,8 +1352,8 @@ class State {
         for (const nodeId of ids) {
             getFinal(nodeId);
         }
-        // Pass 4: bind each ref to the FINAL (possibly wrapped) state so transitions
-        // resolve to the version that has its override-halt set.
+        // 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]);
@@ -1209,6 +1366,13 @@ class State {
         };
     }
 }
+_a = State;
+// Memoization cache for `withOverriddenHaltState`. Keyed by
+// (bare, override) — same args return the same wrapper instance (#175).
+// Two-level WeakMap so the outer entry is GC'd when the bare is collected;
+// WeakRef values let wrappers themselves be GC'd when nothing else holds
+// them, with cache misses simply reconstructing fresh wrappers.
+_State_wrapperCache = { value: new WeakMap() };
 const haltState = new State(null);
 
 var __classPrivateFieldSet = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
@@ -1352,19 +1516,25 @@ _TuringMachine_tapeBlock = new WeakMap(), _TuringMachine_stack = new WeakMap();
 // Currently only Mermaid flowchart syntax is supported. Future formats
 // (Graphviz, JSON-LD, custom DSL) belong here too.
 //
-// v7 emit shape (#138/#139):
-//   - Each wrapper-State collapses onto its bare's representation. The collapsed
-//     graph node has `isWrapped: true` and is emitted as Mermaid `[[…]]`
-//     (subroutine / double-walled-rectangle) shape, inside a `subgraph
-//     w_${id}["halt frame"] … end` block. A synthesized "halt marker" graph
-//     node (with `isHalt: true, isHaltMarker: true`, id = -wrapperId in graph
-//     data) sits inside the subgraph and serves as the local landing point for
-//     the bare's halt-bound transitions. The dotted onHalt edge runs from the
-//     `[[bare]]` directly to the override target, crossing the subgraph border.
-//   - Real halt (id 0) is emitted as `s0(((halt)))` outside any subgraph.
-//   - Halt marker nodes use the Mermaid id `c${absId}` (where `absId = -id`)
-//     since Mermaid IDs must match /[A-Za-z][A-Za-z0-9_]*/ — negative numbers
-//     are not legal syntax.
+// v7 callable-subtree emit (#174):
+//   - Each `withOverriddenHaltState` wrapper produces TWO graph nodes — a
+//     wrapper node (`[[composite-name]]`, OUTSIDE any subgraph) and a bare
+//     node (regular shape, INSIDE its callable subtree subgraph).
+//   - Subgraphs (one per frame): `subgraph w_${frameId}["callable subtree
+//     of NAME"]` (single bare) or `["callable scope: A ∪ B"]` (union).
+//   - Each frame has exactly one halt marker `c${frameId}(((halt)))` inside
+//     its subgraph; halt-bound transitions from in-frame states retarget to
+//     it. Always emitted (orphan signals dead wrapper).
+//   - Arrow conventions:
+//       solid `-->`        regular transitions, including wrapper-to-override.
+//       bold  `==>`        RESERVED for the wrapper-to-bare `call` arrow.
+//                          `&` ribbon collapses multi-wrapper-shares-bare.
+//       dotted `-.->`      frame-level dispatch (`return`, `halt`, `enter`).
+//   - The `return` arrow (subgraph → wrapper) is demand-emitted iff the
+//     frame's halt marker has at least one incoming edge AND the wrapper
+//     calls into the frame. The `halt` arrow (subgraph → s0) is emitted
+//     iff the halt marker has incoming AND there's at least one non-wrapper
+//     entry into the frame (cross-subgraph solid arrow from outside).
 // Maps a graph node id to its Mermaid id.
 //   - non-negative id N  → "sN"
 //   - negative id -N (halt marker) → "cN"
@@ -1378,108 +1548,256 @@ function parseMermaidId(s) {
     }
     return Number(s.slice(1));
 }
+function frameSubgraphId(frameId) {
+    return `w_${frameId}`;
+}
 function toMermaid(graph) {
     const lines = [
         'flowchart TD',
         `%% alphabets: ${JSON.stringify(graph.alphabets)}`,
     ];
-    // Sort nodes by id (ascending — real halt first at 0, regular states next,
-    // negative-id halt markers last). Deterministic emit lets `toMermaid` →
-    // `fromMermaid` → `toMermaid` round-trip stably (regression for #139).
+    // Sort nodes by id ascending — real halt (0) first, then regulars by their
+    // ids, then halt markers (negative) at the end. Deterministic emit lets
+    // toMermaid → fromMermaid → toMermaid round-trip stably (#139).
     const nodes = Object.values(graph.nodes).slice().sort((a, b) => a.id - b.id);
-    const wrappedNodes = nodes.filter((n) => n.isWrapped);
-    // Convention: wrapped node id N → halt marker id -N.
-    const haltMarkerIdFor = (wrappedId) => -wrappedId;
-    // Set of halt-marker ids that belong to some wrapper (= are inside a subgraph).
-    const haltMarkerIds = new Set();
-    for (const w of wrappedNodes) {
-        const haltMarkerId = haltMarkerIdFor(w.id);
-        if (haltMarkerId in graph.nodes) {
-            haltMarkerIds.add(haltMarkerId);
-        }
-    }
-    // Emit non-subgraph nodes first: real halt + regular non-wrapped nodes.
-    // No special round-shape `((…))` for the initial — the `idle -. enter .->`
-    // arrow emitted below is the sole "start here" signal.
+    // Bucket nodes for emit order.
+    const topLevelNodes = nodes.filter((n) => n.frameId === null && !n.isWrapper);
+    const wrapperNodes = nodes.filter((n) => n.isWrapper);
+    // Bares-and-bodies inside frames, grouped by frameId.
+    const nodesByFrame = new Map();
+    // Halt-marker per frame (kept separate so it always emits LAST inside the
+    // subgraph for deterministic shape).
+    const haltMarkerByFrame = new Map();
     for (const node of nodes) {
-        if (node.isWrapped || haltMarkerIds.has(node.id)) {
+        if (node.frameId === null || node.isWrapper)
             continue;
+        if (node.isHaltMarker) {
+            haltMarkerByFrame.set(node.frameId, node);
         }
-        const id = mermaidIdFor(node.id);
+        else {
+            let bucket = nodesByFrame.get(node.frameId);
+            if (!bucket) {
+                bucket = [];
+                nodesByFrame.set(node.frameId, bucket);
+            }
+            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) => {
+        if (node.tags.length === 0)
+            return node.name;
+        return `${node.name}<br>${node.tags.join(', ')}`;
+    };
+    // 1. Emit top-level nodes (real halt, non-wrapper regulars outside any frame).
+    for (const node of topLevelNodes) {
+        const mid = mermaidIdFor(node.id);
         if (node.isHalt) {
-            lines.push(`  ${id}(((halt)))`);
+            lines.push(`  ${mid}(((halt)))`);
         }
         else {
-            lines.push(`  ${id}["${node.name}"]`);
+            lines.push(`  ${mid}["${labelOf(node)}"]`);
         }
     }
-    // `idle` sentinel = pre-execution marker for the machine. Always emitted,
-    // with a labeled dotted arrow `idle -. enter .-> sN` to the initial state.
-    // Symmetric with the `onHalt` dotted convention used by wrapper redirects.
-    // Visual-only — `idle` is not a graph node.
+    // 2. Emit wrappers at top level.
+    for (const wrapper of wrapperNodes) {
+        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${labelOf(wrapper)}"]]`);
+    }
+    // 3. `idle` sentinel.
     lines.push('  idle([idle])');
-    // Emit one subgraph per wrapper, in sorted wrapped-id order.
-    for (const wrapped of wrappedNodes) {
-        const wrappedMid = mermaidIdFor(wrapped.id);
-        const haltMarkerId = haltMarkerIdFor(wrapped.id);
-        const haltMarkerMid = mermaidIdFor(haltMarkerId);
-        lines.push(`  subgraph w_${wrapped.id}["halt frame"]`);
-        lines.push(`    ${wrappedMid}[["${wrapped.name}"]]`);
-        if (haltMarkerId in graph.nodes) {
-            lines.push(`    ${haltMarkerMid}(((halt)))`);
-        }
+    // 4. Subgraph per frame.
+    const frameIds = [...nodesByFrame.keys()].sort((a, b) => a - b);
+    for (const frameId of frameIds) {
+        const frameBares = (nodesByFrame.get(frameId) ?? []).filter((n) => isFrameBare(n, graph));
+        const frameBareNames = frameBares
+            .slice()
+            .sort((a, b) => a.id - b.id)
+            .map((n) => 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)}["${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);
+        lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
         lines.push('  end');
     }
-    // Enter arrow: emitted after subgraphs so it visually points at the initial
-    // node (whether plain `[…]` or wrapped `[[…]]` inside a subgraph).
+    // 5. Enter arrow.
     lines.push(`  idle -. enter .-> ${mermaidIdFor(graph.initialId)}`);
-    // Emit transitions per-node in sorted node-id order. Within a node,
-    // transitions emit in their stored array order (which mirrors the source
-    // state's symbol-map insertion order — stable per State instance).
+    // 6. `call` arrows — grouped by bare (multi-wrapper-shares-bare collapses
+    // into a single `&` ribbon).
+    const wrappersByBare = new Map();
+    for (const wrapper of wrapperNodes) {
+        if (wrapper.bareStateId === null)
+            continue;
+        let group = wrappersByBare.get(wrapper.bareStateId);
+        if (!group) {
+            group = [];
+            wrappersByBare.set(wrapper.bareStateId, group);
+        }
+        group.push(wrapper);
+    }
+    const sortedBares = [...wrappersByBare.keys()].sort((a, b) => a - b);
+    for (const bareId of sortedBares) {
+        const wrappers = wrappersByBare.get(bareId).slice().sort((a, b) => a.id - b.id);
+        const sources = wrappers.map((w) => mermaidIdFor(w.id)).join(' & ');
+        lines.push(`  ${sources} == "call" ==> ${mermaidIdFor(bareId)}`);
+    }
+    // 7. Demand-emit `return` and `halt` arrows per frame.
+    // For each frame: check if its halt marker has incoming transitions.
+    const haltMarkerHasIncoming = new Map();
     for (const node of nodes) {
-        if (node.isHalt && !node.isHaltMarker) {
+        for (const t of node.transitions) {
+            const target = graph.nodes[t.nextStateId];
+            if (target && target.isHaltMarker && target.frameId !== null) {
+                haltMarkerHasIncoming.set(target.frameId, true);
+            }
+        }
+    }
+    // For each frame: check if there's at least one non-wrapper entry (a solid
+    // `-->` from OUTSIDE the frame into any node INSIDE).
+    const hasNonWrapperEntry = new Map();
+    for (const node of nodes) {
+        if (node.isWrapper)
+            continue;
+        for (const t of node.transitions) {
+            const target = graph.nodes[t.nextStateId];
+            if (target
+                && target.frameId !== null
+                && node.frameId !== target.frameId) {
+                hasNonWrapperEntry.set(target.frameId, true);
+            }
+        }
+    }
+    for (const frameId of frameIds) {
+        if (!haltMarkerHasIncoming.get(frameId))
             continue;
+        // 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) => {
+            const bare = graph.nodes[w.bareStateId];
+            return bare.frameId === frameId;
+        });
+        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) {
+        lines.push(`  ${mermaidIdFor(wrapper.id)} --> ${mermaidIdFor(wrapper.overriddenHaltStateId)}`);
+    }
+    // 9. Regular transitions for non-wrapper non-halt-marker non-halt nodes.
+    for (const node of nodes) {
+        if (node.isHalt || node.isHaltMarker || node.isWrapper)
+            continue;
         for (const t of node.transitions) {
-            // Bracketed-tape-block format (v7): each role-list — read alternatives,
-            // writes, movements — wraps in `[…]` to mark "this is a tape-block
-            // reading". Brackets stay even for single-tape machines; the `[…]` is
-            // the tape-block concept indicator.
-            //
-            //   Single-tape:                  ['X'] → [K]/[R]
-            //   Single-tape + alternation:    ['^']|['1']|['0'] → [K]/[S]
-            //   Two-tape:                     ['0','a'] → [K,'1']/[R,S]
-            //   Two-tape + alternation:       ['0','a']|['1','b'] → [K,K]/[R,L]
-            //
-            // Alternation is ALWAYS per-pattern-bracket — one full bracketed list
-            // per alternative — regardless of tape count. Pedagogically each
-            // alternative is its own drawn transition; a compact in-bracket form
-            // (`['^'|'1']`) would read as cross-product semantics in multi-tape
-            // (`['0'|'1','a'|'b']` = 4 combos, not 2 paired alternatives), so we
-            // avoid introducing it for the single-tape case too.
             const alternatives = t.pattern.split('|');
             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}`;
-            // Thicker `==>` arrow when the transition crosses INTO a wrapper —
-            // signals "this transition pushes that wrapper's override onto the
-            // runtime stack" (per `TuringMachine.run` line ~220's
-            // `if (state !== nextState && nextState.overriddenHaltState) push(...)`).
-            // Self-loops (state === nextState) don't push at runtime — keep the
-            // regular `-->` for those even when the target is wrapped.
-            const targetNode = graph.nodes[t.nextStateId];
-            const isEnteringWrapper = targetNode && targetNode.isWrapped && t.nextStateId !== node.id;
-            const lineSegment = isEnteringWrapper ? '==' : '--';
-            const arrowTip = isEnteringWrapper ? '==>' : '-->';
-            lines.push(`  ${mermaidIdFor(node.id)} ${lineSegment} "${label}" ${arrowTip} ${mermaidIdFor(t.nextStateId)}`);
-        }
-        if (node.overriddenHaltStateId !== null) {
-            lines.push(`  ${mermaidIdFor(node.id)} -. onHalt .-> ${mermaidIdFor(node.overriddenHaltStateId)}`);
+            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) {
+    for (const other of Object.values(graph.nodes)) {
+        if (other.isWrapper && other.bareStateId === node.id) {
+            return true;
+        }
+    }
+    return false;
+}
 // Inverse of toMermaid: parses the Mermaid output produced by toMermaid back
 // into a Graph. The parser is strict to the dialect toMermaid emits — it
 // recognises the specific node/edge shapes and the leading
@@ -1494,26 +1812,59 @@ function toMermaid(graph) {
 const haltNodeRegex = /^([sc]\d+)\(\(\(halt\)\)\)$/;
 const regularNodeRegex = /^(s\d+)\["([^"]*)"\]$/;
 const wrappedNodeRegex = /^(s\d+)\[\["([^"]*)"\]\]$/;
-const subgraphStartRegex = /^subgraph\s+w_\d+\["([^"]*)"\]$/;
+const subgraphStartRegex = /^subgraph\s+w_(\d+)\["([^"]*)"\]$/;
 const subgraphEndRegex = /^end$/;
 const idleNodeRegex = /^idle\(\[idle\]\)$/;
 const enterArrowRegex = /^idle\s+-\.\s+enter\s+\.->\s+(s\d+)$/;
-const transitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
-const thickTransitionRegex = /^([sc]\d+)\s+==\s+"(.*)"\s+==>\s+([sc]\d+)$/;
-const onHaltRegex = /^([sc]\d+)\s+-\.\s+onHalt\s+\.->\s+([sc]\d+)$/;
+// Regular labeled transition (solid `-->`).
+const labeledTransitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
+// Wrapper → override (unlabeled solid `-->`).
+const wrapperOverrideRegex = /^(s\d+)\s+-->\s+([sc]\d+)$/;
+// Call arrow (bold `==>`), with optional `&`-joined source ribbon.
+// Ribbon separator is fixed at " & " (single spaces around &) — toMermaid
+// emits exactly that form, so the parser is strict to it. The literal-space
+// form avoids CodeQL's polynomial-ReDoS flag on a `\s+&\s+` shape.
+const callArrowRegex = /^(s\d+(?: & s\d+)*)\s+==\s+"call"\s+==>\s+(s\d+)$/;
+// Return arrow (`w_N -. return .-> s_W` with optional `&` target ribbon).
+const returnArrowRegex = /^w_(\d+)\s+-\.\s+"return"\s+\.->\s+(s\d+(?: & s\d+)*)$/;
+// Halt arrow (`w_N -. halt .-> s0`).
+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.
+function splitLabelTags(label) {
+    const brIx = label.indexOf('<br>');
+    if (brIx < 0) {
+        return { name: label, tags: [] };
+    }
+    const name = label.slice(0, brIx);
+    const tagsStr = label.slice(brIx + '<br>'.length);
+    const tags = tagsStr.split(',').map((t) => 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 = [];
     let initialId = null;
     const nodes = {};
-    // Track the halt-marker ids that appeared inside a subgraph — they should be
-    // marked `isHaltMarker: true` even though they share the `(((halt)))` shape
-    // with the real halt at the top level.
-    const haltMarkerIds = new Set();
-    let inSubgraph = false;
+    let currentFrameId = null;
     const ensureNode = (id, opts = {}) => {
         if (!nodes[id]) {
             nodes[id] = {
@@ -1521,9 +1872,12 @@ function fromMermaid(text) {
                 name: opts.name ?? mermaidIdFor(id),
                 isHalt: opts.isHalt ?? false,
                 isHaltMarker: opts.isHaltMarker ?? false,
-                isWrapped: opts.isWrapped ?? false,
+                isWrapper: opts.isWrapper ?? false,
+                bareStateId: opts.bareStateId ?? null,
+                frameId: opts.frameId ?? null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: opts.tags ? [...opts.tags] : [],
             };
         }
         else {
@@ -1533,72 +1887,133 @@ function fromMermaid(text) {
                 nodes[id].isHalt = opts.isHalt;
             if (opts.isHaltMarker !== undefined)
                 nodes[id].isHaltMarker = opts.isHaltMarker;
-            if (opts.isWrapped !== undefined)
-                nodes[id].isWrapped = opts.isWrapped;
+            if (opts.isWrapper !== undefined)
+                nodes[id].isWrapper = opts.isWrapper;
+            if (opts.bareStateId !== undefined)
+                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];
     };
-    // First pass: alphabets + nodes (track subgraph context to mark halt markers).
+    // First pass: nodes + alphabets (track subgraph context for frameId).
     for (const line of lines) {
-        if (line === 'flowchart TD') {
+        if (line === 'flowchart TD')
             continue;
-        }
         const am = line.match(alphabetsRegex);
         if (am) {
             alphabets = JSON.parse(am[1]);
             continue;
         }
-        if (subgraphStartRegex.test(line)) {
-            inSubgraph = true;
+        // 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]);
             continue;
         }
         if (subgraphEndRegex.test(line)) {
-            inSubgraph = false;
+            currentFrameId = null;
             continue;
         }
-        // `idle([idle])` sentinel: a visual pre-execution marker. Not a graph
-        // node — skip declaration, parse the `idle -. enter .-> sN` arrow in the
-        // edge pass to set initialId.
-        if (idleNodeRegex.test(line)) {
+        if (idleNodeRegex.test(line))
             continue;
-        }
         const hm = line.match(haltNodeRegex);
         if (hm) {
             const id = parseMermaidId(hm[1]);
-            const isHaltMarker = inSubgraph || id < 0;
-            ensureNode(id, { name: 'halt', isHalt: true, isHaltMarker });
-            if (isHaltMarker) {
-                haltMarkerIds.add(id);
-            }
+            const isHaltMarker = currentFrameId !== null;
+            ensureNode(id, {
+                name: 'halt',
+                isHalt: true,
+                isHaltMarker,
+                frameId: isHaltMarker ? currentFrameId : null,
+            });
             continue;
         }
         const wm = line.match(wrappedNodeRegex);
         if (wm) {
-            ensureNode(parseMermaidId(wm[1]), { name: wm[2], isWrapped: true });
+            const { name, tags } = splitLabelTags(wm[2]);
+            ensureNode(parseMermaidId(wm[1]), {
+                name,
+                isWrapper: true,
+                tags,
+            });
             continue;
         }
         const rm = line.match(regularNodeRegex);
         if (rm) {
-            ensureNode(parseMermaidId(rm[1]), { name: rm[2] });
+            const { name, tags } = splitLabelTags(rm[2]);
+            ensureNode(parseMermaidId(rm[1]), {
+                name,
+                frameId: currentFrameId,
+                tags,
+            });
             continue;
         }
     }
     // Second pass: edges.
     for (const line of lines) {
-        // `idle -. enter .-> sN`: the sole source of initialId.
         const em = line.match(enterArrowRegex);
         if (em) {
             initialId = parseMermaidId(em[1]);
             continue;
         }
-        const om = line.match(onHaltRegex);
-        if (om) {
-            ensureNode(parseMermaidId(om[1])).overriddenHaltStateId = parseMermaidId(om[2]);
+        // Return/halt arrows are derivable from frame structure at the next
+        // toMermaid emit; consume but don't persist as graph data.
+        if (returnArrowRegex.test(line) || haltArrowRegex.test(line)) {
             continue;
         }
-        // Thick transition (`==> `) and regular transition (`-->`) share the same
-        // semantics — only the visual differs. Parse both via the same code path.
-        const tm = line.match(transitionRegex) ?? line.match(thickTransitionRegex);
+        // 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) {
+            const sources = cm[1].split(' & ');
+            const bareId = parseMermaidId(cm[2]);
+            for (const src of sources) {
+                ensureNode(parseMermaidId(src), { isWrapper: true, bareStateId: bareId });
+            }
+            continue;
+        }
+        // Wrapper → override (unlabeled solid `-->`). Only fires if the source
+        // node is a known wrapper (declared as `[[…]]`).
+        const wo = line.match(wrapperOverrideRegex);
+        if (wo) {
+            const fromId = parseMermaidId(wo[1]);
+            const toId = parseMermaidId(wo[2]);
+            // 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;
+            }
+            // Fall through — unlabeled solid from a non-wrapper is unexpected;
+            // treated as a malformed line and ignored by the labeled-regex below.
+        }
+        const tm = line.match(labeledTransitionRegex);
         if (tm) {
             const fromId = parseMermaidId(tm[1]);
             const label = tm[2];
@@ -1607,31 +2022,13 @@ function fromMermaid(text) {
             if (arrowIx === -1) {
                 throw new Error(`fromMermaid: malformed edge label: "${label}"`);
             }
-            // Bracketed-tape-block format (v7):
-            //   [<read-cells>]|[<read-cells>]... → [<write-cells>]/[<move-cells>]
-            // Each bracketed list is a tape-block reading; the outer `|` separates
-            // alternative read patterns. For single-tape machines with alternation,
-            // the compact form `[<alt1>|<alt2>|...]` (one bracket, alternatives
-            // inside) is also accepted; both forms decode to the same pattern
-            // string.
             const readLabel = label.slice(0, arrowIx);
             const cmdLabel = label.slice(arrowIx + ' → '.length);
-            // Strict per-pattern bracket form: `|` only between bracketed lists,
-            // never inside. The compact `['^'|'1']` form is rejected by design —
-            // every alternative must be its own bracketed pattern (`['^']|['1']`).
-            // Pedagogically: each transition is drawn explicitly; the compact form
-            // would read as cross-product semantics in multi-tape and confuse
-            // readers (`['0'|'1','a'|'b']` could mean 4 combos, not 2 paired alts).
-            // The rule applies to all bracketed lists — read alternatives, writes,
-            // and movements — because commands and movements have no alternation
-            // semantic either.
             const stripBrackets = (s) => {
                 if (!s.startsWith('[') || !s.endsWith(']')) {
                     throw new Error(`fromMermaid: malformed bracketed list: "${s}"`);
                 }
                 const inner = s.slice(1, -1);
-                // Walk the inner content; backslash escapes the next char (so `\|`
-                // inside a cell is a literal pipe, not the alternation separator).
                 let i = 0;
                 while (i < inner.length) {
                     if (inner[i] === '\\' && i + 1 < inner.length) {
@@ -1646,10 +2043,6 @@ function fromMermaid(text) {
                 }
                 return inner;
             };
-            // Match `[…]` blocks in the read label. Inner content is a tape-block
-            // reading (possibly with `|` for compact single-tape alternation).
-            // `[^\]]*` is the simple non-greedy match — works because cell content
-            // doesn't typically contain literal `]`.
             const blockMatches = readLabel.match(/\[[^\]]*\]/g);
             if (!blockMatches || blockMatches.length === 0) {
                 throw new Error(`fromMermaid: no bracketed read-list in label: "${label}"`);