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

package/dist/index.cjs

@@ -349,7 +349,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 {
@@ -388,7 +388,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;
@@ -488,10 +488,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;
@@ -520,12 +520,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
@@ -537,30 +537,40 @@ const movementDescriptionToLabel = {
     'do not move carer': 'S',
 };
 const symbolCommandDescriptionToLabel = {
-    'keep symbol command': '·',
-    'erase symbol command': '⌫',
+    'keep symbol command': 'K',
+    'erase symbol command': 'E',
 };
 // Reserved characters in the encoded pattern string:
-//   '*'  per-cell ifOtherSymbol (matches any symbol on that tape)
-//   '-'  the tape's blank symbol
+//   '*'  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
-//   '\\' escape prefix — to represent any of '*', '-', ',', '|', or '\\' as a
-//        *literal* alphabet symbol, prefix it with '\\' (e.g. '\\*' for literal '*').
+//   "'"  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, '\\*')
-        .replace(/-/g, '\\-')
-        .replace(/,/g, '\\,')
-        .replace(/\|/g, '\\|');
+        .replace(/'/g, "\\'");
 }
 function decodePatternDescription(description, alphabets) {
     if (!description) {
         return '?';
     }
     if (description === 'other symbol') {
-        return '*';
+        return IF_OTHER_MARKER;
     }
     try {
         const patternList = JSON.parse(description);
@@ -568,12 +578,12 @@ function decodePatternDescription(description, alphabets) {
             .map((pattern) => pattern
             .map((s, tapeIx) => {
             if (s === null) {
-                return '*';
+                return IF_OTHER_MARKER;
             }
             if (s === alphabets[tapeIx]?.[0]) {
-                return '-';
+                return BLANK_MARKER;
             }
-            return escapeAlphabetSymbol(s);
+            return `'${escapeAlphabetSymbol(s)}'`;
         })
             .join(','))
             .join('|');
@@ -611,19 +621,24 @@ function splitUnescaped(s, sep) {
     return parts;
 }
 function parsePatternString(s, alphabets) {
-    if (s === '*') {
+    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 (cell === IF_OTHER_MARKER) {
                 return null;
             }
-            if (cell === '-') {
+            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;
         });
     });
@@ -641,12 +656,17 @@ function parseMovementLabel(label) {
     return m;
 }
 function parseWriteSymbolLabel(label) {
-    if (label === '·') {
+    if (label === 'K') {
         return symbolCommands.keep;
     }
-    if (label === '⌫') {
+    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) {
@@ -654,7 +674,7 @@ function decodeWriteSymbol(symbol) {
         const description = symbol.description ?? '?';
         return symbolCommandDescriptionToLabel[description] ?? description;
     }
-    return symbol;
+    return `'${symbol}'`;
 }
 // Format converters (toMermaid / fromMermaid) live in ./graphFormats.
 
@@ -669,7 +689,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_overrodeHaltState, _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;
 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.
@@ -714,10 +734,18 @@ _DebugConfig_ownerState = new WeakMap(), _DebugConfig_before = new WeakMap(), _D
 class State {
     constructor(stateDefinition = null, name) {
         _State_id.set(this, id(this));
+        // Not `readonly` because `withOverriddenHaltState` and `fromGraph` set the
+        // composed name on a no-arg `new State()` to bypass the constructor's
+        // user-facing name validation (composite names contain `(` and `)`).
         _State_name.set(this, void 0);
-        _State_overrodeHaltState.set(this, null);
+        _State_overriddenHaltState.set(this, null);
+        // For wrapper states (produced by `withOverriddenHaltState`), points at the
+        // State whose transition map was wrapped. `null` on bare/atomic states.
+        // Used by `toGraph` to collapse the wrapper-and-its-bare pair into a single
+        // "wrapped bare" graph node — see the v7 emit redesign for #138.
+        _State_bareState.set(this, null);
         _State_symbolToDataMap.set(this, new Map());
-        // Shared mutable cell — withOverrodeHaltState wrappers reference the same
+        // Shared mutable cell — withOverriddenHaltState wrappers reference the same
         // object so that `state.debug = ...` (and nullings) propagate across them.
         // Note: toGraph / fromGraph deliberately do not serialize debug — debug is
         // a runtime concern, not part of the structural graph.
@@ -734,7 +762,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];
@@ -763,6 +791,9 @@ class State {
                 });
             });
         }
+        if (name !== undefined && /[()]/.test(name)) {
+            throw new Error(`invalid state name "${name}": must not contain '(' or ')' (reserved as wrapper-composition delimiters in withOverriddenHaltState)`);
+        }
         __classPrivateFieldSet$1(this, _State_name, name ?? `id:${__classPrivateFieldGet$1(this, _State_id, "f")}`, "f");
     }
     get id() {
@@ -774,8 +805,8 @@ class State {
     get isHalt() {
         return __classPrivateFieldGet$1(this, _State_id, "f") === 0;
     }
-    get overrodeHaltState() {
-        return __classPrivateFieldGet$1(this, _State_overrodeHaltState, "f");
+    get overriddenHaltState() {
+        return __classPrivateFieldGet$1(this, _State_overriddenHaltState, "f");
     }
     get ref() {
         return this;
@@ -803,7 +834,7 @@ class State {
         __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, value);
     }
     /** @internal — invoked by DebugConfig setters via module-private symbol. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overrodeHaltState = 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(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
         // #108 part 2: `.after` on haltState has no semantic anchor — halt is
@@ -850,11 +881,41 @@ class State {
         }
         throw new Error(`No nextState for symbol at state named ${__classPrivateFieldGet$1(this, _State_id, "f")}`);
     }
-    withOverrodeHaltState(overrodeHaltState) {
-        const state = new State(null, `${this.name}>${overrodeHaltState.name}`);
-        __classPrivateFieldSet$1(state, _State_symbolToDataMap, __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f"), "f");
-        __classPrivateFieldSet$1(state, _State_overrodeHaltState, overrodeHaltState, "f");
-        __classPrivateFieldSet$1(state, _State_debugRef, __classPrivateFieldGet$1(this, _State_debugRef, "f"), "f");
+    withOverriddenHaltState(overriddenHaltState) {
+        // 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(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.
@@ -867,7 +928,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
@@ -885,38 +946,104 @@ class State {
             id: __classPrivateFieldGet$1(state, _State_id, "f"),
             name: __classPrivateFieldGet$1(state, _State_name, "f"),
             isHalt: state.isHalt,
-            overrodeHaltState: __classPrivateFieldGet$1(state, _State_overrodeHaltState, "f")
-                ? { id: __classPrivateFieldGet$1(state, _State_overrodeHaltState, "f").id, name: __classPrivateFieldGet$1(state, _State_overrodeHaltState, "f").name }
+            overriddenHaltState: __classPrivateFieldGet$1(state, _State_overriddenHaltState, "f")
+                ? { id: __classPrivateFieldGet$1(state, _State_overriddenHaltState, "f").id, name: __classPrivateFieldGet$1(state, _State_overriddenHaltState, "f").name }
                 : null,
             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.
     static toGraph(initialState, tapeBlock) {
         const nodes = {};
-        const queue = [initialState];
         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 current = queue.shift();
-            if (__classPrivateFieldGet$1(current, _State_id, "f") in nodes) {
+            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(current, _State_id, "f"),
-                name: __classPrivateFieldGet$1(current, _State_name, "f"),
-                isHalt: current.isHalt,
+                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: [],
-                overrodeHaltStateId: __classPrivateFieldGet$1(current, _State_overrodeHaltState, "f")?.id ?? null,
+                overriddenHaltStateId: null,
             };
-            nodes[__classPrivateFieldGet$1(current, _State_id, "f")] = node;
-            if (__classPrivateFieldGet$1(current, _State_overrodeHaltState, "f")) {
-                queue.push(__classPrivateFieldGet$1(current, _State_overrodeHaltState, "f"));
-            }
-            for (const [sym, { command, nextState }] of __classPrivateFieldGet$1(current, _State_symbolToDataMap, "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;
                 }
                 node.transitions.push({
@@ -925,26 +1052,173 @@ class State {
                         symbol: decodeWriteSymbol(tc.symbol),
                         movement: decodeMovement(tc.movement.description),
                     })),
-                    nextStateId: target.id,
+                    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`.
     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();
             }
         }
@@ -961,19 +1235,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),
@@ -982,9 +1259,17 @@ class State {
                     nextState,
                 };
             }
-            bareStates[nodeId] = new State(stateDefinition, node.name);
-        }
-        // Pass 3: apply overrideHaltStates transitively.
+            // 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) => {
@@ -992,7 +1277,7 @@ class State {
                 return finalStates[nodeId];
             }
             const node = graph.nodes[nodeId];
-            if (node.isHalt) {
+            if (!node || node.isHalt) {
                 finalStates[nodeId] = haltState;
                 return haltState;
             }
@@ -1000,9 +1285,14 @@ class State {
                 throw new Error(`override-halt cycle at state #${nodeId}`);
             }
             inProgress.add(nodeId);
-            let state = bareStates[nodeId];
-            if (node.overrodeHaltStateId !== null) {
-                state = bareStates[nodeId].withOverrodeHaltState(getFinal(node.overrodeHaltStateId));
+            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;
@@ -1011,8 +1301,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]);
@@ -1025,6 +1315,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) {
@@ -1087,8 +1384,8 @@ class TuringMachine {
             __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f")[lockSymbol].lock(executionSymbol);
             const stack = __classPrivateFieldGet(this, _TuringMachine_stack, "f");
             let state = initialState;
-            if (state.overrodeHaltState) {
-                stack.push(state.overrodeHaltState);
+            if (state.overriddenHaltState) {
+                stack.push(state.overriddenHaltState);
             }
             let i = 0;
             while (!state.isHalt) {
@@ -1142,8 +1439,8 @@ class TuringMachine {
                     if (nextState.isHalt && stack.length) {
                         nextState = stack.pop();
                     }
-                    if (state !== nextState && nextState.overrodeHaltState) {
-                        stack.push(nextState.overrodeHaltState);
+                    if (state !== nextState && nextState.overriddenHaltState) {
+                        stack.push(nextState.overriddenHaltState);
                     }
                     state = nextState;
                 }
@@ -1167,36 +1464,215 @@ _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 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"
+function mermaidIdFor(id) {
+    return id < 0 ? `c${-id}` : `s${id}`;
+}
+// Inverse of mermaidIdFor.
+function parseMermaidId(s) {
+    if (s.startsWith('c')) {
+        return -Number(s.slice(1));
+    }
+    return Number(s.slice(1));
+}
+function frameSubgraphId(frameId) {
+    return `w_${frameId}`;
+}
 function toMermaid(graph) {
     const lines = [
         'flowchart TD',
         `%% alphabets: ${JSON.stringify(graph.alphabets)}`,
     ];
-    for (const node of Object.values(graph.nodes)) {
-        const id = `s${node.id}`;
-        if (node.isHalt) {
-            lines.push(`  ${id}(((halt)))`);
+    // 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);
+    // 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.frameId === null || node.isWrapper)
+            continue;
+        if (node.isHaltMarker) {
+            haltMarkerByFrame.set(node.frameId, node);
         }
-        else if (node.id === graph.initialId) {
-            lines.push(`  ${id}(("${node.name}"))`);
+        else {
+            let bucket = nodesByFrame.get(node.frameId);
+            if (!bucket) {
+                bucket = [];
+                nodesByFrame.set(node.frameId, bucket);
+            }
+            bucket.push(node);
+        }
+    }
+    // 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(`  ${mid}(((halt)))`);
         }
         else {
-            lines.push(`  ${id}["${node.name}"]`);
+            lines.push(`  ${mid}["${node.name}"]`);
+        }
+    }
+    // 2. Emit wrappers at top level.
+    for (const wrapper of wrapperNodes) {
+        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${wrapper.name}"]]`);
+    }
+    // 3. `idle` sentinel.
+    lines.push('  idle([idle])');
+    // 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)}["${node.name}"]`);
+        }
+        const haltMarker = haltMarkerByFrame.get(frameId);
+        if (haltMarker) {
+            lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
+        }
+        lines.push('  end');
+    }
+    // 5. Enter arrow.
+    lines.push(`  idle -. enter .-> ${mermaidIdFor(graph.initialId)}`);
+    // 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) {
+        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 (const node of Object.values(graph.nodes)) {
+    // 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) {
-            // Per-tape commands separated with ',' to mirror the pattern syntax.
-            const cmd = t.command.map((c) => `${c.symbol}/${c.movement}`).join(',');
-            const label = `${t.pattern} → ${cmd}`;
-            lines.push(`  s${node.id} -- "${label}" --> s${t.nextStateId}`);
+            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.
+        const callingWrappers = wrapperNodes.filter((w) => {
+            if (w.bareStateId === null)
+                return false;
+            const bare = graph.nodes[w.bareStateId];
+            return !!bare && 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}`);
         }
-        if (node.overrodeHaltStateId !== null) {
-            lines.push(`  s${node.id} -. onHalt .-> s${node.overrodeHaltStateId}`);
+        if (hasNonWrapperEntry.get(frameId)) {
+            lines.push(`  ${frameSubgraphId(frameId)} -. "halt" .-> s0`);
+        }
+    }
+    // 8. Wrapper-to-override arrows (regular solid).
+    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.
+    for (const node of nodes) {
+        if (node.isHalt || node.isHaltMarker || node.isWrapper)
+            continue;
+        for (const t of node.transitions) {
+            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}`;
+            lines.push(`  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`);
         }
     }
     return lines.join('\n');
 }
+// 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.
+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;
+        }
+    }
+    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
@@ -1208,11 +1684,26 @@ function toMermaid(graph) {
 //   per-tape segments are split on ','. If your alphabet contains '/' or ','
 //   as literal symbols, the parser cannot disambiguate. Stick to alphabets
 //   without those characters when round-tripping through Mermaid.
-const haltNodeRegex = /^s(\d+)\(\(\(halt\)\)\)$/;
-const initialNodeRegex = /^s(\d+)\(\("([^"]*)"\)\)$/;
-const regularNodeRegex = /^s(\d+)\["([^"]*)"\]$/;
-const transitionRegex = /^s(\d+)\s+--\s+"(.*)"\s+-->\s+s(\d+)$/;
-const onHaltRegex = /^s(\d+)\s+-\.\s+onHalt\s+\.->\s+s(\d+)$/;
+const haltNodeRegex = /^([sc]\d+)\(\(\(halt\)\)\)$/;
+const regularNodeRegex = /^(s\d+)\["([^"]*)"\]$/;
+const wrappedNodeRegex = /^(s\d+)\[\["([^"]*)"\]\]$/;
+const subgraphStartRegex = /^subgraph\s+w_(\d+)\["([^"]*)"\]$/;
+const subgraphEndRegex = /^end$/;
+const idleNodeRegex = /^idle\(\[idle\]\)$/;
+const enterArrowRegex = /^idle\s+-\.\s+enter\s+\.->\s+(s\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.*)$/;
@@ -1221,99 +1712,197 @@ function fromMermaid(text) {
     let alphabets = [];
     let initialId = null;
     const nodes = {};
+    let currentFrameId = null;
     const ensureNode = (id, opts = {}) => {
         if (!nodes[id]) {
             nodes[id] = {
                 id,
-                name: opts.name ?? `s${id}`,
+                name: opts.name ?? mermaidIdFor(id),
                 isHalt: opts.isHalt ?? false,
+                isHaltMarker: opts.isHaltMarker ?? false,
+                isWrapper: opts.isWrapper ?? false,
+                bareStateId: opts.bareStateId ?? null,
+                frameId: opts.frameId ?? null,
                 transitions: [],
-                overrodeHaltStateId: null,
+                overriddenHaltStateId: null,
             };
         }
         else {
-            if (opts.name !== undefined) {
+            if (opts.name !== undefined)
                 nodes[id].name = opts.name;
-            }
-            if (opts.isHalt !== undefined) {
+            if (opts.isHalt !== undefined)
                 nodes[id].isHalt = opts.isHalt;
-            }
+            if (opts.isHaltMarker !== undefined)
+                nodes[id].isHaltMarker = opts.isHaltMarker;
+            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;
         }
         return nodes[id];
     };
-    // First pass: alphabets + nodes.
+    // 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;
         }
+        const sgStart = line.match(subgraphStartRegex);
+        if (sgStart) {
+            currentFrameId = Number(sgStart[1]);
+            continue;
+        }
+        if (subgraphEndRegex.test(line)) {
+            currentFrameId = null;
+            continue;
+        }
+        if (idleNodeRegex.test(line))
+            continue;
         const hm = line.match(haltNodeRegex);
         if (hm) {
-            ensureNode(Number(hm[1]), { name: 'halt', isHalt: true });
+            const id = parseMermaidId(hm[1]);
+            const isHaltMarker = currentFrameId !== null;
+            ensureNode(id, {
+                name: 'halt',
+                isHalt: true,
+                isHaltMarker,
+                frameId: isHaltMarker ? currentFrameId : null,
+            });
             continue;
         }
-        const im = line.match(initialNodeRegex);
-        if (im) {
-            const id = Number(im[1]);
-            initialId = id;
-            ensureNode(id, { name: im[2] });
+        const wm = line.match(wrappedNodeRegex);
+        if (wm) {
+            ensureNode(parseMermaidId(wm[1]), {
+                name: wm[2],
+                isWrapper: true,
+            });
             continue;
         }
         const rm = line.match(regularNodeRegex);
         if (rm) {
-            ensureNode(Number(rm[1]), { name: rm[2] });
+            ensureNode(parseMermaidId(rm[1]), {
+                name: rm[2],
+                frameId: currentFrameId,
+            });
             continue;
         }
     }
     // Second pass: edges.
     for (const line of lines) {
-        const om = line.match(onHaltRegex);
-        if (om) {
-            ensureNode(Number(om[1])).overrodeHaltStateId = Number(om[2]);
+        const em = line.match(enterArrowRegex);
+        if (em) {
+            initialId = parseMermaidId(em[1]);
+            continue;
+        }
+        // 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;
         }
-        const tm = line.match(transitionRegex);
+        // `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]);
+            if (nodes[fromId] && 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 = Number(tm[1]);
+            const fromId = parseMermaidId(tm[1]);
             const label = tm[2];
-            const toId = Number(tm[3]);
+            const toId = parseMermaidId(tm[3]);
             const arrowIx = label.indexOf(' → ');
             if (arrowIx === -1) {
                 throw new Error(`fromMermaid: malformed edge label: "${label}"`);
             }
-            const pattern = label.slice(0, arrowIx);
-            const commandStr = label.slice(arrowIx + ' → '.length);
-            const command = commandStr.split(',').map((part) => {
-                const slashIx = part.lastIndexOf('/');
-                if (slashIx === -1) {
-                    throw new Error(`fromMermaid: malformed command part: "${part}"`);
+            const readLabel = label.slice(0, arrowIx);
+            const cmdLabel = label.slice(arrowIx + ' → '.length);
+            const stripBrackets = (s) => {
+                if (!s.startsWith('[') || !s.endsWith(']')) {
+                    throw new Error(`fromMermaid: malformed bracketed list: "${s}"`);
                 }
-                return {
-                    symbol: part.slice(0, slashIx),
-                    movement: part.slice(slashIx + 1),
-                };
+                const inner = s.slice(1, -1);
+                let i = 0;
+                while (i < inner.length) {
+                    if (inner[i] === '\\' && i + 1 < inner.length) {
+                        i += 2;
+                        continue;
+                    }
+                    if (inner[i] === '|') {
+                        throw new Error(`fromMermaid: compact in-bracket alternation "${s}" is not supported — `
+                            + 'each alternative must be its own bracketed pattern (e.g. "[\'^\']|[\'1\']").');
+                    }
+                    i += 1;
+                }
+                return inner;
+            };
+            const blockMatches = readLabel.match(/\[[^\]]*\]/g);
+            if (!blockMatches || blockMatches.length === 0) {
+                throw new Error(`fromMermaid: no bracketed read-list in label: "${label}"`);
+            }
+            const pattern = blockMatches.map(stripBrackets).join('|');
+            const slashIx = cmdLabel.indexOf(']/[');
+            if (slashIx === -1) {
+                throw new Error(`fromMermaid: malformed command label (expected \`[…]/[…]\`): "${cmdLabel}"`);
+            }
+            const writesPart = stripBrackets(cmdLabel.slice(0, slashIx + 1));
+            const movesPart = stripBrackets(cmdLabel.slice(slashIx + 2));
+            const writes = writesPart.split(',');
+            const moves = movesPart.split(',');
+            if (writes.length !== moves.length) {
+                throw new Error(`fromMermaid: write-cells (${writes.length}) and move-cells (${moves.length}) mismatch: "${cmdLabel}"`);
+            }
+            const command = writes.map((symbol, i) => ({ symbol, movement: moves[i] }));
+            const fromNode = ensureNode(fromId);
+            const transitionIx = fromNode.transitions.length;
+            fromNode.transitions.push({
+                pattern,
+                command,
+                nextStateId: toId,
+                id: `${fromId}-${transitionIx}`,
             });
-            ensureNode(fromId).transitions.push({ pattern, command, nextStateId: toId });
         }
     }
     if (initialId === null) {
-        throw new Error('fromMermaid: no initial state (double-paren node) found');
+        throw new Error('fromMermaid: no `idle -. enter .-> sN` arrow found');
     }
     return { initialId, alphabets, nodes };
 }
 
 function summarizeGraph(graph) {
     const nodes = Object.values(graph.nodes);
+    // `isHaltMarker` nodes are visualization sentinels — one per wrapper context,
+    // all corresponding to the singleton `haltState` at runtime. They don't
+    // count as distinct runtime states; matches the per-algorithm header in
+    // `library-binary-numbers/states.md`.
+    const runtimeStateCount = nodes.filter((n) => !n.isHaltMarker).length;
     let transitionCount = 0;
     let compositionEdgeCount = 0;
     let selfLoopCount = 0;
     for (const node of nodes) {
         transitionCount += node.transitions.length;
-        if (node.overrodeHaltStateId !== null) {
+        if (node.overriddenHaltStateId !== null) {
             compositionEdgeCount += 1;
         }
         for (const t of node.transitions) {
@@ -1322,7 +1911,7 @@ function summarizeGraph(graph) {
             }
         }
     }
-    // Longest withOverrodeHaltState chain. Walks node → overrodeHaltState recursively;
+    // Longest withOverriddenHaltState chain. Walks node → overriddenHaltState recursively;
     // a Set guards against cycles in the override graph (which throw at construction
     // time anyway, but being defensive costs little).
     const overrideDepthFrom = (id, visited) => {
@@ -1331,10 +1920,10 @@ function summarizeGraph(graph) {
         }
         visited.add(id);
         const node = graph.nodes[id];
-        if (!node || node.overrodeHaltStateId === null) {
+        if (!node || node.overriddenHaltStateId === null) {
             return 0;
         }
-        return 1 + overrideDepthFrom(node.overrodeHaltStateId, visited);
+        return 1 + overrideDepthFrom(node.overriddenHaltStateId, visited);
     };
     const maxCompositionDepth = nodes.reduce((max, node) => Math.max(max, overrideDepthFrom(node.id, new Set())), 0);
     // Cycle detection: tri-color DFS over the transition graph.
@@ -1377,7 +1966,7 @@ function summarizeGraph(graph) {
         visit(node.id);
     }
     return {
-        stateCount: nodes.length,
+        stateCount: runtimeStateCount,
         transitionCount,
         compositionEdgeCount,
         maxCompositionDepth,