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

package/dist/index.cjs

@@ -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, _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.
@@ -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,17 @@ 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}`);
+    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");
-        __classPrivateFieldSet$1(state, _State_overrodeHaltState, overrodeHaltState, "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");
         return state;
     }
     // Single-state introspection — no traversal, no tapeBlock required.
@@ -885,52 +922,196 @@ 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 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.
+    //
+    // 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.
     static toGraph(initialState, tapeBlock) {
         const nodes = {};
-        const queue = [initialState];
         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 });
+        }
         while (queue.length > 0) {
-            const current = queue.shift();
-            if (__classPrivateFieldGet$1(current, _State_id, "f") in nodes) {
+            const { state, wrapperContext } = queue.shift();
+            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,
+                        transitions: [],
+                        overriddenHaltStateId: null,
+                    };
+                }
+                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"),
+                    isHalt: false,
+                    isHaltMarker: false,
+                    isWrapped: true,
+                    transitions: [],
+                    overriddenHaltStateId: overrideGraphId,
+                };
+                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) {
                 continue;
             }
             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,
+                isWrapped: false,
                 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;
                 }
                 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: target.id,
+                    nextStateId,
+                    id: `${__classPrivateFieldGet$1(state, _State_id, "f")}-${patternIx}`,
                 });
-                queue.push(target);
+                patternIx += 1;
             }
         }
-        return { initialId: __classPrivateFieldGet$1(initialState, _State_id, "f"), alphabets, nodes };
+        return { initialId, 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
@@ -982,7 +1163,12 @@ class State {
                     nextState,
                 };
             }
-            bareStates[nodeId] = new State(stateDefinition, node.name);
+            // 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);
+            __classPrivateFieldSet$1(bare, _State_name, node.name, "f");
+            bareStates[nodeId] = bare;
         }
         // Pass 3: apply overrideHaltStates transitively.
         const finalStates = {};
@@ -1001,8 +1187,8 @@ class State {
             }
             inProgress.add(nodeId);
             let state = bareStates[nodeId];
-            if (node.overrodeHaltStateId !== null) {
-                state = bareStates[nodeId].withOverrodeHaltState(getFinal(node.overrodeHaltStateId));
+            if (node.overriddenHaltStateId !== null) {
+                state = bareStates[nodeId].withOverriddenHaltState(getFinal(node.overriddenHaltStateId));
             }
             inProgress.delete(nodeId);
             finalStates[nodeId] = state;
@@ -1060,7 +1246,7 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    async run({ initialState, stepsLimit = 1e5, onStep, onPause, debug = true, }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onPause, onIter, debug = true, }) {
         const generator = this.runStepByStep({ initialState, stepsLimit });
         for (const machineState of generator) {
             // Per-iter lifecycle: before → step → after. All three operate on the
@@ -1069,12 +1255,15 @@ class TuringMachine {
             if (debug && machineState.debugBreak?.before && onPause) {
                 await onPause({ ...machineState, debugBreak: { before: true } });
             }
-            if (onStep instanceof Function) {
+            if (onStep) {
                 onStep(machineState);
             }
             if (debug && machineState.debugBreak?.after && onPause) {
                 await onPause({ ...machineState, debugBreak: { after: true } });
             }
+            if (onIter) {
+                await onIter(machineState);
+            }
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {
@@ -1084,8 +1273,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) {
@@ -1139,8 +1328,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;
                 }
@@ -1164,32 +1353,131 @@ _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.
+// 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 toMermaid(graph) {
     const lines = [
         'flowchart TD',
         `%% alphabets: ${JSON.stringify(graph.alphabets)}`,
     ];
-    for (const node of Object.values(graph.nodes)) {
-        const id = `s${node.id}`;
+    // 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).
+    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.
+    for (const node of nodes) {
+        if (node.isWrapped || haltMarkerIds.has(node.id)) {
+            continue;
+        }
+        const id = mermaidIdFor(node.id);
         if (node.isHalt) {
             lines.push(`  ${id}(((halt)))`);
         }
-        else if (node.id === graph.initialId) {
-            lines.push(`  ${id}(("${node.name}"))`);
-        }
         else {
             lines.push(`  ${id}["${node.name}"]`);
         }
     }
-    for (const node of Object.values(graph.nodes)) {
-        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}`);
+    // `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.
+    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)))`);
+        }
+        lines.push('  end');
+    }
+    // Enter arrow: emitted after subgraphs so it visually points at the initial
+    // node (whether plain `[…]` or wrapped `[[…]]` inside a subgraph).
+    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).
+    for (const node of nodes) {
+        if (node.isHalt && !node.isHaltMarker) {
+            continue;
         }
-        if (node.overrodeHaltStateId !== null) {
-            lines.push(`  s${node.id} -. onHalt .-> s${node.overrodeHaltStateId}`);
+        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)}`);
         }
     }
     return lines.join('\n');
@@ -1205,11 +1493,16 @@ 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+)$/;
+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+)$/;
 // 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.*)$/;
@@ -1218,27 +1511,36 @@ function fromMermaid(text) {
     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;
     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,
+                isWrapped: opts.isWrapped ?? false,
                 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.isWrapped !== undefined)
+                nodes[id].isWrapped = opts.isWrapped;
         }
         return nodes[id];
     };
-    // First pass: alphabets + nodes.
+    // First pass: alphabets + nodes (track subgraph context to mark halt markers).
     for (const line of lines) {
         if (line === 'flowchart TD') {
             continue;
@@ -1248,69 +1550,154 @@ function fromMermaid(text) {
             alphabets = JSON.parse(am[1]);
             continue;
         }
+        if (subgraphStartRegex.test(line)) {
+            inSubgraph = true;
+            continue;
+        }
+        if (subgraphEndRegex.test(line)) {
+            inSubgraph = false;
+            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)) {
+            continue;
+        }
         const hm = line.match(haltNodeRegex);
         if (hm) {
-            ensureNode(Number(hm[1]), { name: 'halt', isHalt: true });
+            const id = parseMermaidId(hm[1]);
+            const isHaltMarker = inSubgraph || id < 0;
+            ensureNode(id, { name: 'halt', isHalt: true, isHaltMarker });
+            if (isHaltMarker) {
+                haltMarkerIds.add(id);
+            }
             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], isWrapped: true });
             continue;
         }
         const rm = line.match(regularNodeRegex);
         if (rm) {
-            ensureNode(Number(rm[1]), { name: rm[2] });
+            ensureNode(parseMermaidId(rm[1]), { name: rm[2] });
             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(Number(om[1])).overrodeHaltStateId = Number(om[2]);
+            ensureNode(parseMermaidId(om[1])).overriddenHaltStateId = parseMermaidId(om[2]);
             continue;
         }
-        const tm = line.match(transitionRegex);
+        // 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);
         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}"`);
+            // 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}"`);
                 }
-                return {
-                    symbol: part.slice(0, slashIx),
-                    movement: part.slice(slashIx + 1),
-                };
+                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) {
+                        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;
+            };
+            // 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}"`);
+            }
+            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) {
@@ -1319,7 +1706,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) => {
@@ -1328,10 +1715,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.
@@ -1374,7 +1761,7 @@ function summarizeGraph(graph) {
         visit(node.id);
     }
     return {
-        stateCount: nodes.length,
+        stateCount: runtimeStateCount,
         transitionCount,
         compositionEdgeCount,
         maxCompositionDepth,