@turing-machine-js/machine 2.0.2 → 3.0.1

package/dist/index.cjs

@@ -175,121 +175,13 @@ class Reference {
 }
 _Reference_referenceBinding = new WeakMap();
 
-var __classPrivateFieldGet$4 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    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 __classPrivateFieldSet$4 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _State_id, _State_name, _State_overrodeHaltState, _State_symbolToDataMap;
-const ifOtherSymbol = Symbol('other symbol');
-class State {
-    constructor(stateDefinition = null, name) {
-        _State_id.set(this, id(this));
-        _State_name.set(this, void 0);
-        _State_overrodeHaltState.set(this, null);
-        _State_symbolToDataMap.set(this, new Map());
-        if (stateDefinition) {
-            const keys = Object.getOwnPropertyNames(stateDefinition);
-            if (keys.length) {
-                throw new Error(`invalid state definition while constructing state #${__classPrivateFieldGet$4(this, _State_id, "f")}`);
-            }
-            const symbols = Object.getOwnPropertySymbols(stateDefinition);
-            if (symbols.length === 0) {
-                throw new Error(`invalid state definition while constructing state #${__classPrivateFieldGet$4(this, _State_id, "f")}`);
-            }
-            symbols.forEach((symbol) => {
-                const { nextState } = stateDefinition[symbol];
-                const nextStateLocal = nextState !== null && nextState !== void 0 ? nextState : this;
-                if (!(nextStateLocal instanceof State) && !(nextStateLocal instanceof Reference)) {
-                    throw new Error('invalid nextState');
-                }
-                let { command } = stateDefinition[symbol];
-                if (command == null) {
-                    command = new Command([
-                        new TapeCommand({}),
-                    ]);
-                }
-                if (!(command instanceof Command) && !Array.isArray(command)) {
-                    command = [command];
-                }
-                let commandLocal = command;
-                if (Array.isArray(command)) {
-                    try {
-                        commandLocal = new Command(command);
-                    }
-                    catch (error) {
-                    }
-                }
-                if (!(commandLocal instanceof Command)) {
-                    throw new Error('invalid command');
-                }
-                __classPrivateFieldGet$4(this, _State_symbolToDataMap, "f").set(symbol, {
-                    command: commandLocal,
-                    nextState: nextStateLocal,
-                });
-            });
-        }
-        __classPrivateFieldSet$4(this, _State_name, name !== null && name !== void 0 ? name : `id:${__classPrivateFieldGet$4(this, _State_id, "f")}`, "f");
-    }
-    get id() {
-        return __classPrivateFieldGet$4(this, _State_id, "f");
-    }
-    get name() {
-        return __classPrivateFieldGet$4(this, _State_name, "f");
-    }
-    get isHalt() {
-        return __classPrivateFieldGet$4(this, _State_id, "f") === 0;
-    }
-    get overrodeHaltState() {
-        return __classPrivateFieldGet$4(this, _State_overrodeHaltState, "f");
-    }
-    get ref() {
-        return this;
-    }
-    getSymbol(tapeBlock) {
-        const symbol = [...__classPrivateFieldGet$4(this, _State_symbolToDataMap, "f").keys()].find((currentSymbol) => tapeBlock.isMatched({
-            symbol: currentSymbol,
-        }));
-        if (symbol) {
-            return symbol;
-        }
-        return ifOtherSymbol;
-    }
-    getCommand(symbol) {
-        if (__classPrivateFieldGet$4(this, _State_symbolToDataMap, "f").has(symbol)) {
-            return __classPrivateFieldGet$4(this, _State_symbolToDataMap, "f").get(symbol).command;
-        }
-        throw new Error(`No command for symbol at state named ${__classPrivateFieldGet$4(this, _State_name, "f")}`);
-    }
-    getNextState(symbol) {
-        if (__classPrivateFieldGet$4(this, _State_symbolToDataMap, "f").has(symbol)) {
-            return __classPrivateFieldGet$4(this, _State_symbolToDataMap, "f").get(symbol).nextState;
-        }
-        throw new Error(`No nextState for symbol at state named ${__classPrivateFieldGet$4(this, _State_id, "f")}`);
-    }
-    withOverrodeHaltState(overrodeHaltState) {
-        const state = new State(null, `${this.name}>${overrodeHaltState.name}`);
-        __classPrivateFieldSet$4(state, _State_symbolToDataMap, __classPrivateFieldGet$4(this, _State_symbolToDataMap, "f"), "f");
-        __classPrivateFieldSet$4(state, _State_overrodeHaltState, overrodeHaltState, "f");
-        return state;
-    }
-}
-_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overrodeHaltState = new WeakMap(), _State_symbolToDataMap = new WeakMap();
-const haltState = new State(null);
-
-var __classPrivateFieldSet$3 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet$3 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+var __classPrivateFieldGet$4 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
     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);
@@ -305,46 +197,46 @@ class Tape {
         if (!isSymbolsValid) {
             throw new Error('symbolList contains invalid symbol');
         }
-        __classPrivateFieldSet$3(this, _Tape_alphabet, new Alphabet(alphabet), "f");
-        __classPrivateFieldSet$3(this, _Tape_position, position, "f");
-        __classPrivateFieldSet$3(this, _Tape_viewportWidth, viewportWidth, "f");
+        __classPrivateFieldSet$4(this, _Tape_alphabet, new Alphabet(alphabet), "f");
+        __classPrivateFieldSet$4(this, _Tape_position, position, "f");
+        __classPrivateFieldSet$4(this, _Tape_viewportWidth, viewportWidth, "f");
         const symbolsCopy = Array.from(symbols);
         if (symbolsCopy.length === 0) {
-            symbolsCopy.push(__classPrivateFieldGet$3(this, _Tape_alphabet, "f").blankSymbol);
+            symbolsCopy.push(__classPrivateFieldGet$4(this, _Tape_alphabet, "f").blankSymbol);
         }
-        __classPrivateFieldSet$3(this, _Tape_symbols, symbolsCopy.map((symbol) => __classPrivateFieldGet$3(this, _Tape_alphabet, "f").index(symbol)), "f");
+        __classPrivateFieldSet$4(this, _Tape_symbols, symbolsCopy.map((symbol) => __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol)), "f");
     }
     get alphabet() {
-        return __classPrivateFieldGet$3(this, _Tape_alphabet, "f");
+        return __classPrivateFieldGet$4(this, _Tape_alphabet, "f");
     }
     get extraCellsCount() {
-        return (__classPrivateFieldGet$3(this, _Tape_viewportWidth, "f") - 1) / 2;
+        return (__classPrivateFieldGet$4(this, _Tape_viewportWidth, "f") - 1) / 2;
     }
     get position() {
-        return __classPrivateFieldGet$3(this, _Tape_position, "f");
+        return __classPrivateFieldGet$4(this, _Tape_position, "f");
     }
     get symbol() {
-        return __classPrivateFieldGet$3(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$3(this, _Tape_symbols, "f")[__classPrivateFieldGet$3(this, _Tape_position, "f")]);
+        return __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_symbols, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")]);
     }
     set symbol(symbol) {
-        if (!__classPrivateFieldGet$3(this, _Tape_alphabet, "f").has(symbol)) {
+        if (!__classPrivateFieldGet$4(this, _Tape_alphabet, "f").has(symbol)) {
             throw new Error('Invalid symbol');
         }
-        __classPrivateFieldGet$3(this, _Tape_symbols, "f")[__classPrivateFieldGet$3(this, _Tape_position, "f")] = __classPrivateFieldGet$3(this, _Tape_alphabet, "f").index(symbol);
+        __classPrivateFieldGet$4(this, _Tape_symbols, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol);
     }
     get symbols() {
-        return __classPrivateFieldGet$3(this, _Tape_symbols, "f")
-            .map((index) => __classPrivateFieldGet$3(this, _Tape_alphabet, "f").get(index));
+        return __classPrivateFieldGet$4(this, _Tape_symbols, "f")
+            .map((index) => __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(index));
     }
     get viewport() {
-        const startIx = __classPrivateFieldGet$3(this, _Tape_position, "f") - this.extraCellsCount;
-        const endIx = __classPrivateFieldGet$3(this, _Tape_position, "f") + this.extraCellsCount + 1;
-        return __classPrivateFieldGet$3(this, _Tape_symbols, "f")
+        const startIx = __classPrivateFieldGet$4(this, _Tape_position, "f") - this.extraCellsCount;
+        const endIx = __classPrivateFieldGet$4(this, _Tape_position, "f") + this.extraCellsCount + 1;
+        return __classPrivateFieldGet$4(this, _Tape_symbols, "f")
             .slice(startIx, endIx)
-            .map((index) => __classPrivateFieldGet$3(this, _Tape_alphabet, "f").get(index));
+            .map((index) => __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(index));
     }
     get viewportWidth() {
-        return __classPrivateFieldGet$3(this, _Tape_viewportWidth, "f");
+        return __classPrivateFieldGet$4(this, _Tape_viewportWidth, "f");
     }
     set viewportWidth(width) {
         let finalWidth = width;
@@ -354,35 +246,35 @@ class Tape {
         if (finalWidth % 2 === 0) {
             finalWidth += 1;
         }
-        __classPrivateFieldSet$3(this, _Tape_viewportWidth, finalWidth, "f");
+        __classPrivateFieldSet$4(this, _Tape_viewportWidth, finalWidth, "f");
         this.normalise();
     }
     left() {
-        __classPrivateFieldSet$3(this, _Tape_position, __classPrivateFieldGet$3(this, _Tape_position, "f") - 1, "f");
+        __classPrivateFieldSet$4(this, _Tape_position, __classPrivateFieldGet$4(this, _Tape_position, "f") - 1, "f");
         this.normalise();
     }
     normalise() {
-        while (__classPrivateFieldGet$3(this, _Tape_position, "f") - this.extraCellsCount < 0) {
-            __classPrivateFieldGet$3(this, _Tape_symbols, "f").unshift(0);
-            __classPrivateFieldSet$3(this, _Tape_position, __classPrivateFieldGet$3(this, _Tape_position, "f") + 1, "f");
+        while (__classPrivateFieldGet$4(this, _Tape_position, "f") - this.extraCellsCount < 0) {
+            __classPrivateFieldGet$4(this, _Tape_symbols, "f").unshift(0);
+            __classPrivateFieldSet$4(this, _Tape_position, __classPrivateFieldGet$4(this, _Tape_position, "f") + 1, "f");
         }
-        while (__classPrivateFieldGet$3(this, _Tape_position, "f") + this.extraCellsCount >= __classPrivateFieldGet$3(this, _Tape_symbols, "f").length) {
-            __classPrivateFieldGet$3(this, _Tape_symbols, "f").push(0);
+        while (__classPrivateFieldGet$4(this, _Tape_position, "f") + this.extraCellsCount >= __classPrivateFieldGet$4(this, _Tape_symbols, "f").length) {
+            __classPrivateFieldGet$4(this, _Tape_symbols, "f").push(0);
         }
     }
     right() {
-        __classPrivateFieldSet$3(this, _Tape_position, __classPrivateFieldGet$3(this, _Tape_position, "f") + 1, "f");
+        __classPrivateFieldSet$4(this, _Tape_position, __classPrivateFieldGet$4(this, _Tape_position, "f") + 1, "f");
         this.normalise();
     }
 }
 _Tape_alphabet = new WeakMap(), _Tape_symbols = new WeakMap(), _Tape_position = new WeakMap(), _Tape_viewportWidth = new WeakMap();
 
-var __classPrivateFieldGet$2 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+var __classPrivateFieldGet$3 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
     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 __classPrivateFieldSet$2 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+var __classPrivateFieldSet$3 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
@@ -394,30 +286,30 @@ class Lock {
         _Lock_lockSymbol.set(this, null);
     }
     lock(symbol) {
-        if (__classPrivateFieldGet$2(this, _Lock_lockSymbol, "f") === null) {
-            __classPrivateFieldSet$2(this, _Lock_lockSymbol, symbol, "f");
+        if (__classPrivateFieldGet$3(this, _Lock_lockSymbol, "f") === null) {
+            __classPrivateFieldSet$3(this, _Lock_lockSymbol, symbol, "f");
         }
     }
     unlock(symbol) {
-        if (__classPrivateFieldGet$2(this, _Lock_lockSymbol, "f") === symbol) {
-            __classPrivateFieldSet$2(this, _Lock_lockSymbol, null, "f");
+        if (__classPrivateFieldGet$3(this, _Lock_lockSymbol, "f") === symbol) {
+            __classPrivateFieldSet$3(this, _Lock_lockSymbol, null, "f");
         }
     }
     check(symbol) {
-        if (__classPrivateFieldGet$2(this, _Lock_lockSymbol, "f") && __classPrivateFieldGet$2(this, _Lock_lockSymbol, "f") !== symbol) {
+        if (__classPrivateFieldGet$3(this, _Lock_lockSymbol, "f") && __classPrivateFieldGet$3(this, _Lock_lockSymbol, "f") !== symbol) {
             throw new Error('Lock check failed');
         }
     }
 }
 _Lock_lockSymbol = new WeakMap();
 
-var __classPrivateFieldSet$1 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+var __classPrivateFieldSet$2 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var __classPrivateFieldGet$1 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+var __classPrivateFieldGet$2 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
     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);
@@ -431,7 +323,7 @@ class TapeBlock {
         _TapeBlock_lock.set(this, new Lock());
         _TapeBlock_tapes.set(this, void 0);
         _TapeBlock_buildPatternList.set(this, (symbolList) => symbolList.reduce((result, symbol, ix) => {
-            const row = Math.floor(ix / __classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").length);
+            const row = Math.floor(ix / __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").length);
             if (!Array.isArray(result[row])) {
                 result[row] = [];
             }
@@ -447,7 +339,7 @@ class TapeBlock {
             if (patternList.some((pattern) => pattern.every((symbol) => symbol === ifOtherSymbol))) {
                 return ifOtherSymbol;
             }
-            const [storedPatternListSymbol] = [...__classPrivateFieldGet$1(this, _TapeBlock_symbolToPatternListMap, "f").entries()]
+            const [storedPatternListSymbol] = [...__classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f").entries()]
                 .find(([, storedPatternList]) => {
                 if (storedPatternList.length !== patternList.length) {
                     return false;
@@ -461,8 +353,8 @@ class TapeBlock {
                 symbol = storedPatternListSymbol;
             }
             else {
-                symbol = Symbol(__classPrivateFieldGet$1(_a, _a, "f", _TapeBlock_generateSymbolHint).call(_a, patternList));
-                __classPrivateFieldGet$1(this, _TapeBlock_symbolToPatternListMap, "f").set(symbol, patternList);
+                symbol = Symbol(__classPrivateFieldGet$2(_a, _a, "f", _TapeBlock_generateSymbolHint).call(_a, patternList));
+                __classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f").set(symbol, patternList);
             }
             return symbol;
         });
@@ -477,60 +369,60 @@ class TapeBlock {
             else if (Array.isArray(symbols)) {
                 localSymbols = [...symbols];
             }
-            if (localSymbols.length === 0 || localSymbols.length % __classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").length > 0) {
+            if (localSymbols.length === 0 || localSymbols.length % __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").length > 0) {
                 throw new Error('invalid symbol parameter');
             }
             const invalidSymbolIndex = localSymbols.findIndex((symbol, ix) => (symbol !== ifOtherSymbol
-                && !__classPrivateFieldGet$1(this, _TapeBlock_tapes, "f")[ix % __classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").length].alphabet.has(symbol)));
+                && !__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f")[ix % __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").length].alphabet.has(symbol)));
             if (invalidSymbolIndex >= 0) {
                 throw new Error('invalid symbol parameter');
             }
             if (localSymbols.every((symbol) => symbol === ifOtherSymbol)) {
                 return ifOtherSymbol;
             }
-            return __classPrivateFieldGet$1(this, _TapeBlock_getSymbolForPatternList, "f").call(this, __classPrivateFieldGet$1(this, _TapeBlock_buildPatternList, "f").call(this, localSymbols));
+            return __classPrivateFieldGet$2(this, _TapeBlock_getSymbolForPatternList, "f").call(this, __classPrivateFieldGet$2(this, _TapeBlock_buildPatternList, "f").call(this, localSymbols));
         });
-        __classPrivateFieldSet$1(this, _TapeBlock_tapes, [], "f");
+        __classPrivateFieldSet$2(this, _TapeBlock_tapes, [], "f");
         if ('alphabets' in argument) {
             const { alphabets } = argument;
             if (alphabets.length === 0) {
                 throw new Error('empty alphabet list');
             }
-            __classPrivateFieldSet$1(this, _TapeBlock_tapes, alphabets.map((alphabet) => new Tape({
+            __classPrivateFieldSet$2(this, _TapeBlock_tapes, alphabets.map((alphabet) => new Tape({
                 alphabet,
             })), "f");
         }
         else if ('tapes' in argument) {
-            __classPrivateFieldSet$1(this, _TapeBlock_tapes, argument.tapes, "f");
+            __classPrivateFieldSet$2(this, _TapeBlock_tapes, argument.tapes, "f");
         }
-        if (__classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").length === 0) {
+        if (__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").length === 0) {
             throw new Error('empty tape list');
         }
     }
     get alphabets() {
-        return [...__classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").map((tape) => tape.alphabet)];
+        return [...__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").map((tape) => tape.alphabet)];
     }
     get currentSymbols() {
-        return __classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").map((tape) => tape.symbol);
+        return __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").map((tape) => tape.symbol);
     }
     get [(_TapeBlock_symbolToPatternListMap = new WeakMap(), _TapeBlock_lock = new WeakMap(), _TapeBlock_tapes = new WeakMap(), _TapeBlock_buildPatternList = new WeakMap(), _TapeBlock_getSymbolForPatternList = new WeakMap(), _TapeBlock_symbol = new WeakMap(), lockSymbol)]() {
-        return __classPrivateFieldGet$1(this, _TapeBlock_lock, "f");
+        return __classPrivateFieldGet$2(this, _TapeBlock_lock, "f");
     }
     get symbol() {
-        return __classPrivateFieldGet$1(this, _TapeBlock_symbol, "f").bind(this);
+        return __classPrivateFieldGet$2(this, _TapeBlock_symbol, "f").bind(this);
     }
     get tapes() {
-        return [...__classPrivateFieldGet$1(this, _TapeBlock_tapes, "f")];
+        return [...__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f")];
     }
     set [symbolToPatternListMapSymbol](symbolToPatternListMap) {
-        __classPrivateFieldSet$1(this, _TapeBlock_symbolToPatternListMap, new Map(symbolToPatternListMap), "f");
+        __classPrivateFieldSet$2(this, _TapeBlock_symbolToPatternListMap, new Map(symbolToPatternListMap), "f");
     }
     applyCommand(command, executionSymbol = null) {
-        __classPrivateFieldGet$1(this, _TapeBlock_lock, "f").check(executionSymbol);
-        if (__classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").length !== command.tapesCommands.length) {
+        __classPrivateFieldGet$2(this, _TapeBlock_lock, "f").check(executionSymbol);
+        if (__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").length !== command.tapesCommands.length) {
             throw new Error('invalid command');
         }
-        __classPrivateFieldGet$1(this, _TapeBlock_tapes, "f").forEach((tape, ix) => {
+        __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").forEach((tape, ix) => {
             const { movement, symbol } = command.tapesCommands[ix];
             if (typeof symbol === 'string') {
                 tape.symbol = symbol;
@@ -566,28 +458,27 @@ class TapeBlock {
         else {
             tapeBlock = _a.fromAlphabets(this.alphabets);
         }
-        tapeBlock[symbolToPatternListMapSymbol] = __classPrivateFieldGet$1(this, _TapeBlock_symbolToPatternListMap, "f");
+        tapeBlock[symbolToPatternListMapSymbol] = __classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f");
         return tapeBlock;
     }
     isMatched({ currentSymbols = this.currentSymbols, symbol }) {
-        var _b;
         if (symbol === ifOtherSymbol) {
             return true;
         }
-        if (!__classPrivateFieldGet$1(this, _TapeBlock_symbolToPatternListMap, "f").has(symbol)) {
+        if (!__classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f").has(symbol)) {
             throw new Error('invalid symbol');
         }
-        const patternList = __classPrivateFieldGet$1(this, _TapeBlock_symbolToPatternListMap, "f").get(symbol);
-        return (_b = patternList === null || patternList === void 0 ? void 0 : patternList.some((pattern) => (pattern
+        const patternList = __classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f").get(symbol);
+        return patternList?.some((pattern) => (pattern
             .every((everySymbol, ix) => (everySymbol === ifOtherSymbol
-            || everySymbol === currentSymbols[ix]))))) !== null && _b !== void 0 ? _b : false;
+            || everySymbol === currentSymbols[ix])))) ?? false;
     }
     replaceTape(tape, tapeIx = 0) {
-        if (__classPrivateFieldGet$1(this, _TapeBlock_tapes, "f")[tapeIx] == null) {
+        if (__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f")[tapeIx] == null) {
             throw new Error('invalid tapeIx');
         }
-        if (tape.alphabet.symbols.join('') === __classPrivateFieldGet$1(this, _TapeBlock_tapes, "f")[tapeIx].alphabet.symbols.join('')) {
-            __classPrivateFieldGet$1(this, _TapeBlock_tapes, "f")[tapeIx] = tape;
+        if (tape.alphabet.symbols.join('') === __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f")[tapeIx].alphabet.symbols.join('')) {
+            __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f")[tapeIx] = tape;
         }
         else {
             throw new Error('invalid tape');
@@ -605,6 +496,408 @@ _TapeBlock_generateSymbolHint = { value: (patternList) => JSON.stringify(pattern
         .map((pattern) => pattern
         .map((symbol) => (symbol === ifOtherSymbol ? null : symbol)))) };
 
+const movementDescriptionToLabel = {
+    'move caret left command': 'L',
+    'move caret right command': 'R',
+    'do not move carer': 'S',
+};
+const symbolCommandDescriptionToLabel = {
+    'keep symbol command': '·',
+    'erase symbol command': '⌫',
+};
+// Reserved characters in the encoded pattern string:
+//   '*'  per-cell ifOtherSymbol (matches any symbol on that tape)
+//   '-'  the tape's blank symbol
+//   ','  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 '*').
+function escapeAlphabetSymbol(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/\*/g, '\\*')
+        .replace(/-/g, '\\-')
+        .replace(/,/g, '\\,')
+        .replace(/\|/g, '\\|');
+}
+function decodePatternDescription(description, alphabets) {
+    if (!description) {
+        return '?';
+    }
+    if (description === 'other symbol') {
+        return '*';
+    }
+    try {
+        const patternList = JSON.parse(description);
+        return patternList
+            .map((pattern) => pattern
+            .map((s, tapeIx) => {
+            if (s === null) {
+                return '*';
+            }
+            if (s === alphabets[tapeIx]?.[0]) {
+                return '-';
+            }
+            return escapeAlphabetSymbol(s);
+        })
+            .join(','))
+            .join('|');
+    }
+    catch {
+        return description;
+    }
+}
+function decodeMovement(description) {
+    if (!description) {
+        return '?';
+    }
+    return movementDescriptionToLabel[description] ?? description;
+}
+function splitUnescaped(s, sep) {
+    const parts = [];
+    let current = '';
+    let i = 0;
+    while (i < s.length) {
+        if (s[i] === '\\' && i + 1 < s.length) {
+            current += s[i + 1];
+            i += 2;
+        }
+        else if (s[i] === sep) {
+            parts.push(current);
+            current = '';
+            i += 1;
+        }
+        else {
+            current += s[i];
+            i += 1;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+function parsePatternString(s, alphabets) {
+    if (s === '*') {
+        return null;
+    }
+    const alternatives = splitUnescaped(s, '|');
+    return alternatives.map((alt) => {
+        const cells = splitUnescaped(alt, ',');
+        return cells.map((cell, tapeIx) => {
+            if (cell === '*') {
+                return null;
+            }
+            if (cell === '-') {
+                return alphabets[tapeIx]?.[0] ?? cell;
+            }
+            return cell;
+        });
+    });
+}
+const movementLabelToSymbol = {
+    L: movements.left,
+    R: movements.right,
+    S: movements.stay,
+};
+function parseMovementLabel(label) {
+    const m = movementLabelToSymbol[label];
+    if (!m) {
+        throw new Error(`unknown movement label: ${label}`);
+    }
+    return m;
+}
+function parseWriteSymbolLabel(label) {
+    if (label === '·') {
+        return symbolCommands.keep;
+    }
+    if (label === '⌫') {
+        return symbolCommands.erase;
+    }
+    return label;
+}
+function decodeWriteSymbol(symbol) {
+    if (typeof symbol === 'symbol') {
+        const description = symbol.description ?? '?';
+        return symbolCommandDescriptionToLabel[description] ?? description;
+    }
+    return symbol;
+}
+// Format converters (toMermaid / fromMermaid) live in ./graphFormats.
+
+var __classPrivateFieldGet$1 = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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 __classPrivateFieldSet$1 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _State_id, _State_name, _State_overrodeHaltState, _State_symbolToDataMap;
+const ifOtherSymbol = Symbol('other symbol');
+class State {
+    constructor(stateDefinition = null, name) {
+        _State_id.set(this, id(this));
+        _State_name.set(this, void 0);
+        _State_overrodeHaltState.set(this, null);
+        _State_symbolToDataMap.set(this, new Map());
+        if (stateDefinition) {
+            const keys = Object.getOwnPropertyNames(stateDefinition);
+            if (keys.length) {
+                throw new Error(`invalid state definition while constructing state #${__classPrivateFieldGet$1(this, _State_id, "f")}`);
+            }
+            const symbols = Object.getOwnPropertySymbols(stateDefinition);
+            if (symbols.length === 0) {
+                throw new Error(`invalid state definition while constructing state #${__classPrivateFieldGet$1(this, _State_id, "f")}`);
+            }
+            symbols.forEach((symbol) => {
+                const { nextState } = stateDefinition[symbol];
+                const nextStateLocal = nextState ?? this;
+                if (!(nextStateLocal instanceof State) && !(nextStateLocal instanceof Reference)) {
+                    throw new Error('invalid nextState');
+                }
+                let { command } = stateDefinition[symbol];
+                if (command == null) {
+                    command = new Command([
+                        new TapeCommand({}),
+                    ]);
+                }
+                if (!(command instanceof Command) && !Array.isArray(command)) {
+                    command = [command];
+                }
+                let commandLocal = command;
+                if (Array.isArray(command)) {
+                    try {
+                        commandLocal = new Command(command);
+                    }
+                    catch (error) {
+                    }
+                }
+                if (!(commandLocal instanceof Command)) {
+                    throw new Error('invalid command');
+                }
+                __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").set(symbol, {
+                    command: commandLocal,
+                    nextState: nextStateLocal,
+                });
+            });
+        }
+        __classPrivateFieldSet$1(this, _State_name, name ?? `id:${__classPrivateFieldGet$1(this, _State_id, "f")}`, "f");
+    }
+    get id() {
+        return __classPrivateFieldGet$1(this, _State_id, "f");
+    }
+    get name() {
+        return __classPrivateFieldGet$1(this, _State_name, "f");
+    }
+    get isHalt() {
+        return __classPrivateFieldGet$1(this, _State_id, "f") === 0;
+    }
+    get overrodeHaltState() {
+        return __classPrivateFieldGet$1(this, _State_overrodeHaltState, "f");
+    }
+    get ref() {
+        return this;
+    }
+    getSymbol(tapeBlock) {
+        const symbol = [...__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").keys()].find((currentSymbol) => tapeBlock.isMatched({
+            symbol: currentSymbol,
+        }));
+        if (symbol) {
+            return symbol;
+        }
+        return ifOtherSymbol;
+    }
+    getCommand(symbol) {
+        if (__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(symbol)) {
+            return __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol).command;
+        }
+        throw new Error(`No command for symbol at state named ${__classPrivateFieldGet$1(this, _State_name, "f")}`);
+    }
+    getNextState(symbol) {
+        if (__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(symbol)) {
+            return __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol).nextState;
+        }
+        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");
+        return state;
+    }
+    // Single-state introspection — no traversal, no tapeBlock required.
+    // Returns id, name, halt-status, override-halt target, and the list of
+    // transitions out of this state with decoded write/movement labels.
+    // Symbol patterns are returned as the raw description string from the
+    // interned JS Symbol (decode via decodePatternDescription if needed).
+    static inspect(state) {
+        const transitions = [];
+        for (const [sym, { command, nextState }] of __classPrivateFieldGet$1(state, _State_symbolToDataMap, "f")) {
+            let target = null;
+            try {
+                target = nextState instanceof State ? nextState : nextState.ref;
+            }
+            catch {
+                target = null; // unbound Reference
+            }
+            transitions.push({
+                rawPatternDescription: sym.description,
+                command: command.tapesCommands.map((tc) => ({
+                    symbol: decodeWriteSymbol(tc.symbol),
+                    movement: decodeMovement(tc.movement.description),
+                })),
+                nextState: target ? { id: target.id, name: target.name } : null,
+            });
+        }
+        return {
+            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 }
+                : null,
+            transitions,
+        };
+    }
+    static toGraph(initialState, tapeBlock) {
+        const nodes = {};
+        const queue = [initialState];
+        const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (__classPrivateFieldGet$1(current, _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,
+                transitions: [],
+                overrodeHaltStateId: __classPrivateFieldGet$1(current, _State_overrodeHaltState, "f")?.id ?? 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")) {
+                let target;
+                try {
+                    target = nextState instanceof State ? nextState : nextState.ref;
+                }
+                catch {
+                    continue;
+                }
+                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,
+                });
+                queue.push(target);
+            }
+        }
+        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.
+    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.
+        const refs = {};
+        for (const nodeId of ids) {
+            if (!graph.nodes[nodeId].isHalt) {
+                refs[nodeId] = new Reference();
+            }
+        }
+        // Convert a parsed pattern back to the symbol key the State expects.
+        const patternToKey = (parsed) => {
+            if (parsed === null) {
+                return ifOtherSymbol;
+            }
+            const flat = [];
+            for (const row of parsed) {
+                for (const cell of row) {
+                    flat.push(cell === null ? ifOtherSymbol : cell);
+                }
+            }
+            return tapeBlock.symbol(flat);
+        };
+        // Pass 2: build a "bare" State for each non-halt node (no override yet).
+        // nextState entries point at refs so cycles work; haltState is used directly.
+        const bareStates = {};
+        for (const nodeId of ids) {
+            const node = graph.nodes[nodeId];
+            if (node.isHalt) {
+                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];
+                stateDefinition[key] = {
+                    command: t.command.map((c) => ({
+                        symbol: parseWriteSymbolLabel(c.symbol),
+                        movement: parseMovementLabel(c.movement),
+                    })),
+                    nextState,
+                };
+            }
+            bareStates[nodeId] = new State(stateDefinition, node.name);
+        }
+        // Pass 3: apply overrideHaltStates transitively.
+        const finalStates = {};
+        const inProgress = new Set();
+        const getFinal = (nodeId) => {
+            if (finalStates[nodeId]) {
+                return finalStates[nodeId];
+            }
+            const node = graph.nodes[nodeId];
+            if (node.isHalt) {
+                finalStates[nodeId] = haltState;
+                return haltState;
+            }
+            if (inProgress.has(nodeId)) {
+                throw new Error(`override-halt cycle at state #${nodeId}`);
+            }
+            inProgress.add(nodeId);
+            let state = bareStates[nodeId];
+            if (node.overrodeHaltStateId !== null) {
+                state = bareStates[nodeId].withOverrodeHaltState(getFinal(node.overrodeHaltStateId));
+            }
+            inProgress.delete(nodeId);
+            finalStates[nodeId] = state;
+            return 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.
+        for (const nodeId of ids) {
+            if (!graph.nodes[nodeId].isHalt) {
+                refs[nodeId].bind(finalStates[nodeId]);
+            }
+        }
+        return {
+            start: finalStates[graph.initialId],
+            tapeBlock,
+            states: finalStates,
+        };
+    }
+}
+_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overrodeHaltState = new WeakMap(), _State_symbolToDataMap = new WeakMap();
+const haltState = new State(null);
+
 var __classPrivateFieldSet = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
@@ -704,6 +997,310 @@ class TuringMachine {
 }
 _TuringMachine_tapeBlock = new WeakMap(), _TuringMachine_stack = new WeakMap();
 
+// Format converters between a Graph (the data model produced by State.toGraph
+// and consumed by State.fromGraph) and external string representations.
+//
+// Currently only Mermaid flowchart syntax is supported. Future formats
+// (Graphviz, JSON-LD, custom DSL) belong here too.
+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)))`);
+        }
+        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}`);
+        }
+        if (node.overrodeHaltStateId !== null) {
+            lines.push(`  s${node.id} -. onHalt .-> s${node.overrodeHaltStateId}`);
+        }
+    }
+    return lines.join('\n');
+}
+// 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
+// `%% alphabets: [...]` comment. Hand-edited Mermaid that uses different
+// arrow styles or shapes will not parse.
+//
+// Caveats:
+// - Write-symbol cells in commands are split on '/' (last occurrence) and
+//   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+)$/;
+// 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.*)$/;
+function fromMermaid(text) {
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    let alphabets = [];
+    let initialId = null;
+    const nodes = {};
+    const ensureNode = (id, opts = {}) => {
+        if (!nodes[id]) {
+            nodes[id] = {
+                id,
+                name: opts.name ?? `s${id}`,
+                isHalt: opts.isHalt ?? false,
+                transitions: [],
+                overrodeHaltStateId: null,
+            };
+        }
+        else {
+            if (opts.name !== undefined) {
+                nodes[id].name = opts.name;
+            }
+            if (opts.isHalt !== undefined) {
+                nodes[id].isHalt = opts.isHalt;
+            }
+        }
+        return nodes[id];
+    };
+    // First pass: alphabets + nodes.
+    for (const line of lines) {
+        if (line === 'flowchart TD') {
+            continue;
+        }
+        const am = line.match(alphabetsRegex);
+        if (am) {
+            alphabets = JSON.parse(am[1]);
+            continue;
+        }
+        const hm = line.match(haltNodeRegex);
+        if (hm) {
+            ensureNode(Number(hm[1]), { name: 'halt', isHalt: true });
+            continue;
+        }
+        const im = line.match(initialNodeRegex);
+        if (im) {
+            const id = Number(im[1]);
+            initialId = id;
+            ensureNode(id, { name: im[2] });
+            continue;
+        }
+        const rm = line.match(regularNodeRegex);
+        if (rm) {
+            ensureNode(Number(rm[1]), { name: rm[2] });
+            continue;
+        }
+    }
+    // Second pass: edges.
+    for (const line of lines) {
+        const om = line.match(onHaltRegex);
+        if (om) {
+            ensureNode(Number(om[1])).overrodeHaltStateId = Number(om[2]);
+            continue;
+        }
+        const tm = line.match(transitionRegex);
+        if (tm) {
+            const fromId = Number(tm[1]);
+            const label = tm[2];
+            const toId = Number(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}"`);
+                }
+                return {
+                    symbol: part.slice(0, slashIx),
+                    movement: part.slice(slashIx + 1),
+                };
+            });
+            ensureNode(fromId).transitions.push({ pattern, command, nextStateId: toId });
+        }
+    }
+    if (initialId === null) {
+        throw new Error('fromMermaid: no initial state (double-paren node) found');
+    }
+    return { initialId, alphabets, nodes };
+}
+
+function summarizeGraph(graph) {
+    const nodes = Object.values(graph.nodes);
+    let transitionCount = 0;
+    let compositionEdgeCount = 0;
+    let selfLoopCount = 0;
+    for (const node of nodes) {
+        transitionCount += node.transitions.length;
+        if (node.overrodeHaltStateId !== null) {
+            compositionEdgeCount += 1;
+        }
+        for (const t of node.transitions) {
+            if (t.nextStateId === node.id) {
+                selfLoopCount += 1;
+            }
+        }
+    }
+    // Longest withOverrodeHaltState chain. Walks node → overrodeHaltState 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) => {
+        if (visited.has(id)) {
+            return 0;
+        }
+        visited.add(id);
+        const node = graph.nodes[id];
+        if (!node || node.overrodeHaltStateId === null) {
+            return 0;
+        }
+        return 1 + overrideDepthFrom(node.overrodeHaltStateId, 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.
+    const WHITE = 0;
+    const GREY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    for (const node of nodes) {
+        color.set(node.id, WHITE);
+    }
+    let hasCycles = false;
+    const visit = (id) => {
+        // No `if (hasCycles) return` guard at function entry: the recursive call
+        // pattern (outer for-loop checks before calling, inner loop checks after
+        // each recursive call) ensures visit() is never invoked when hasCycles
+        // is already true. Static analysis confirmed the guard was unreachable.
+        if (color.get(id) === GREY) {
+            hasCycles = true;
+            return;
+        }
+        if (color.get(id) === BLACK) {
+            return;
+        }
+        color.set(id, GREY);
+        const node = graph.nodes[id];
+        if (node) {
+            for (const t of node.transitions) {
+                visit(t.nextStateId);
+                if (hasCycles) {
+                    return;
+                }
+            }
+        }
+        color.set(id, BLACK);
+    };
+    for (const node of nodes) {
+        if (hasCycles) {
+            break;
+        }
+        visit(node.id);
+    }
+    return {
+        stateCount: nodes.length,
+        transitionCount,
+        compositionEdgeCount,
+        maxCompositionDepth,
+        selfLoopCount,
+        hasCycles,
+        tapeCount: graph.alphabets.length,
+        alphabetCardinalities: graph.alphabets.map((a) => a.length),
+    };
+}
+// Convenience: build the graph and summarize in one step.
+function summarize(state, tapeBlock) {
+    return summarizeGraph(State.toGraph(state, tapeBlock));
+}
+// Behavioral equivalence checking (the testing-tool counterpart to introspection)
+// lives in ./equivalence — kept separate because it runs machines and compares
+// outputs rather than examining structure.
+
+const defaultCompare = (a, b) => a === b;
+function equivalentOn(reference, candidate, cases, options = {}) {
+    const compareOutputs = options.compareOutputs ?? defaultCompare;
+    const compareSnapshots = options.compareSnapshots === undefined
+        ? defaultCompare
+        : options.compareSnapshots;
+    const stepsLimit = options.stepsLimit ?? 1e5;
+    const results = cases.map((c) => {
+        const pair = typeof c === 'string' ? { reference: c, candidate: c } : c;
+        const refRun = runOnce(reference, pair.reference, stepsLimit);
+        const candRun = runOnce(candidate, pair.candidate, stepsLimit);
+        const agree = compareOutputs(refRun.finalOutput, candRun.finalOutput);
+        let firstDivergenceStep = null;
+        if (!agree && compareSnapshots !== null) {
+            const minLen = Math.min(refRun.snapshots.length, candRun.snapshots.length);
+            for (let i = 0; i < minLen; i += 1) {
+                if (!compareSnapshots(refRun.snapshots[i], candRun.snapshots[i])) {
+                    firstDivergenceStep = i;
+                    break;
+                }
+            }
+            if (firstDivergenceStep === null && refRun.snapshots.length !== candRun.snapshots.length) {
+                firstDivergenceStep = minLen;
+            }
+        }
+        return {
+            case: pair,
+            agree,
+            referenceOutput: refRun.finalOutput,
+            candidateOutput: candRun.finalOutput,
+            referenceSteps: refRun.stepCount,
+            candidateSteps: candRun.stepCount,
+            firstDivergenceStep,
+        };
+    });
+    return {
+        results,
+        allAgree: results.every((r) => r.agree),
+    };
+}
+// Single-machine runner: snapshots the tape after each step and returns the
+// final output, the snapshot list, and the step count.
+function runOnce(runnable, input, stepsLimit) {
+    const tapeBlock = runnable.getTapeBlock();
+    const tape = new Tape({
+        alphabet: tapeBlock.tapes[0].alphabet,
+        symbols: input.split(''),
+    });
+    tapeBlock.replaceTape(tape);
+    const machine = new TuringMachine({ tapeBlock });
+    const snapshots = [];
+    let stepCount = 0;
+    // Iterate the generator manually (the yielded MachineState isn't needed —
+    // we only care about the side effects on the tape). At each yield the tape
+    // reflects the state BEFORE the current step's command; after the loop
+    // exits the tape has had every command applied.
+    const generator = machine.runStepByStep({ initialState: runnable.state, stepsLimit });
+    let result = generator.next();
+    while (!result.done) {
+        snapshots.push(tape.symbols.join(''));
+        stepCount += 1;
+        result = generator.next();
+    }
+    snapshots.push(tape.symbols.join(''));
+    return {
+        finalOutput: tape.symbols.join('').trim(),
+        snapshots,
+        stepCount,
+    };
+}
+
 exports.Alphabet = Alphabet;
 exports.Command = Command;
 exports.Reference = Reference;
@@ -712,7 +1309,12 @@ exports.Tape = Tape;
 exports.TapeBlock = TapeBlock;
 exports.TapeCommand = TapeCommand;
 exports.TuringMachine = TuringMachine;
+exports.equivalentOn = equivalentOn;
+exports.fromMermaid = fromMermaid;
 exports.haltState = haltState;
 exports.ifOtherSymbol = ifOtherSymbol;
 exports.movements = movements;
+exports.summarize = summarize;
+exports.summarizeGraph = summarizeGraph;
 exports.symbolCommands = symbolCommands;
+exports.toMermaid = toMermaid;