@turing-machine-js/machine 3.0.2 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.0] - 2026-05-09
+
+### Changed (BREAKING)
+
+- **Hook renamed: `onDebugBreak` → `onPause`** on `run()` ([#110](https://github.com/mellonis/turing-machine-js/issues/110)). Hard rename, no deprecation alias. The hook signature, payload shape, and dispatch semantics are unchanged — only the option key on `run()` differs. Resolution of the [#109 RFC](https://github.com/mellonis/turing-machine-js/issues/109): the hook now describes the consumer's relationship (this is where you can pause) rather than the engine's event (a debug break fired). The `m.debugBreak` payload field is unchanged.
+- **`haltState.debug.after` now throws on assignment** ([#108](https://github.com/mellonis/turing-machine-js/issues/108) part 2). Halt is terminal — there is no iteration-after-halt for an after-fire to anchor on. Symmetric `{ before: true, after: true }` writes also throw; use `{ before: true }`. Symbol-list filters on `haltState.debug.before` remain silent no-ops as in v4.
+
+### Fixed
+
+- **Halting iter's `state.debug.after` now fires** ([#108](https://github.com/mellonis/turing-machine-js/issues/108) part 1). Previously `pendingAfterFromPrev` set after the halting iter's yield was discarded when the `while (!state.isHalt)` loop exited — losing that after-fire. `run()` now drains a final after-fire after the loop when the prior yield armed one. Observable: a debugger UI sees a "we just halted because of state X's after-filter" event that was silent before.
+
+### Added
+
+- **`run({ debug: boolean })` flag** ([#106](https://github.com/mellonis/turing-machine-js/issues/106)). Master switch for `onPause` dispatch. When `false`, suppresses all pause-fires (before, after, and the post-loop after-drain) regardless of `state.debug` assignments. `onStep` is unaffected. Defaults to `true`. The `m.debugBreak` field is still populated on yields by the underlying generator (it's a property of the iteration); only `run()`'s hook dispatch is gated. Useful for toggling "debug mode" without editing `state.debug = ...` across the state graph.
+
+### Migration
+
+```diff
+  await machine.run({
+    initialState,
+-   onDebugBreak: (m) => { ... },
++   onPause: (m) => { ... },
+  });
+```
+
+```diff
+- haltState.debug = { before: true, after: true }; // throws in v5
++ haltState.debug = { before: true };
+```
+
+## [4.0.0] - 2026-05-07
+
+### Added
+
+- **`State.debug` field** — runtime-mutable per-state breakpoints with `{ before, after }` symbol filtering ([#98](https://github.com/mellonis/turing-machine-js/issues/98)). Backed by a shared `Ref` cell so `withOverrodeHaltState` wrappers see assignments propagated from the original state. Validator rejects symbols that aren't transition keys of the owning state (catches cross-tape-block / cross-state mistakes); for `haltState`, list filters are silent no-ops because halt has no resolved head symbol.
+- **`DebugConfig` class** — exported from the package. Per-property setters validate and freeze the stored array, so push / index-write throw `TypeError`. Plain-object input to `state.debug = { ... }` is wrapped in a `DebugConfig` instance automatically.
+- **`onDebugBreak` hook** on `run()` — awaited at every break (one or two times per yield: `after` from the previous step, then `before` for the current step). For `after` calls, `run()` substitutes the previous yield's snapshot so `m.state` corresponds to the state whose `after` fired. `onStep` always sees the original (un-substituted) yield.
+- **`haltState.debug.before = true`** — pauses on every halt entry (program exit AND subroutine return via halt-stack pop). Symbol-list filters on `haltState` are silent no-ops; only the `true` wildcard activates. `haltState` is a module-level singleton — clear in `afterEach` / `finally` for test isolation.
+- **`MachineState.debugBreak`** field — optional metadata on every yield from `runStepByStep`; consumers can opt in to reading it and mirror `run()`'s pause behavior if desired.
+
+### Changed (BREAKING)
+
+- **`run()` is now `async`** and returns `Promise<void>`. Existing callers must update to `await machine.run({ ... })` (or `void machine.run({ ... })` if intentionally discarding the result). Without an `onDebugBreak` hook, debug breaks fire-and-resume invisibly — the trajectory observed by `onStep` is identical to running with all `debug` fields cleared.
+
 ## [3.0.2] - 2026-05-04
 
 ### Fixed

package/README.md

@@ -34,7 +34,7 @@ const tape = new Tape({ alphabet, symbols: ['a', 'b', 'c', 'b', 'a'] });
 const tapeBlock = TapeBlock.fromTapes([tape]);
 const machine = new TuringMachine({ tapeBlock });
 
-machine.run({
+await machine.run({
   initialState: new State({
     [tapeBlock.symbol(['b'])]: {
       command: [{ symbol: '*', movement: movements.right }],
@@ -218,8 +218,8 @@ The runtime. Owns one `TapeBlock` and drives a state graph until it reaches `hal
 ```javascript
 const machine = new TuringMachine({ tapeBlock });
 
-// Run to halt:
-machine.run({ initialState, stepsLimit: 1e5 });
+// Run to halt — `run()` is async (v4+), it returns a Promise<void>:
+await machine.run({ initialState, stepsLimit: 1e5 });
 
 // Or step-by-step (useful for visualization / debugging):
 for (const step of machine.runStepByStep({ initialState })) {
@@ -229,6 +229,55 @@ for (const step of machine.runStepByStep({ initialState })) {
 
 `stepsLimit` (default `1e5`) guards against runaway loops — exceeding it throws.
 
+## Debugging breakpoints (v4+)
+
+Any `State` can carry a runtime-mutable `debug` config that pauses execution at chosen points.
+
+```ts
+import { State, haltState, ifOtherSymbol, type DebugConfig } from '@turing-machine-js/machine';
+
+const myState = new State({...});
+
+// Pause before applying any of myState's commands:
+myState.debug = { before: true };
+
+// Pause only when the head shows symA:
+myState.debug = { before: [symA] };
+
+// Pause both before and after for the same symbol — two pauses per visit:
+myState.debug = { before: [symA], after: [symA] };
+
+// Pause when the engine is about to enter halt (program exit OR subroutine pop):
+haltState.debug = { before: true };
+
+// Disable later:
+myState.debug = null;
+```
+
+The `debug` field is mutable — toggle breakpoints at runtime without rebuilding the graph. The internal cell is shared with `state.withOverrodeHaltState(...)` wrappers, so an assignment on the original is visible from every wrapper.
+
+`run()` is async and accepts an `onPause` hook:
+
+```ts
+await machine.run({
+  initialState,
+  onStep: (m) => { /* logger sees every step */ },
+  onPause: async (m) => {
+    // Awaited at every break — hold execution until you resolve.
+    if (m.debugBreak?.before) console.log('before:', m.state.name);
+    if (m.debugBreak?.after)  console.log('after:',  m.state.name);
+  },
+});
+```
+
+For `after` calls, `m` is the previous yield's snapshot — `m.state` is the state whose `after` filter fired. For `before` calls, `m` is the current iteration. `onStep` always sees the original (un-substituted) yield.
+
+If `onPause` is not provided, breaks fire-and-resume invisibly — the trajectory is identical to running without `debug` set.
+
+**Filter semantics:** `true` is a wildcard (match any symbol). `[ifOtherSymbol]` is NOT a wildcard — it matches only the catch-all resolution case (same meaning as in transition keys).
+
+**Caveat:** `haltState` is a module-level singleton. Setting `haltState.debug` affects every machine in the process; clear in `afterEach` / `finally` for test isolation.
+
 ## Special objects
 
 ### haltState

package/dist/classes/State.d.ts

@@ -4,6 +4,18 @@ import TapeBlock from './TapeBlock';
 import TapeCommand from './TapeCommand';
 import { type Graph } from '../utilities/graph';
 export declare const ifOtherSymbol: unique symbol;
+declare const validateDebugFilter: unique symbol;
+export declare class DebugConfig {
+    #private;
+    constructor(ownerState: State, initial?: {
+        before?: symbol[] | readonly symbol[] | true;
+        after?: symbol[] | readonly symbol[] | true;
+    });
+    get before(): readonly symbol[] | true | undefined;
+    set before(v: symbol[] | readonly symbol[] | true | undefined);
+    get after(): readonly symbol[] | true | undefined;
+    set after(v: symbol[] | readonly symbol[] | true | undefined);
+}
 export default class State {
     #private;
     constructor(stateDefinition?: Record<string | symbol, {
@@ -15,6 +27,13 @@ export default class State {
     get isHalt(): boolean;
     get overrodeHaltState(): State | null;
     get ref(): this;
+    get debug(): DebugConfig | null;
+    set debug(value: DebugConfig | {
+        before?: symbol[] | readonly symbol[] | true;
+        after?: symbol[] | readonly symbol[] | true;
+    } | null);
+    /** @internal — invoked by DebugConfig setters via module-private symbol. */
+    [validateDebugFilter](fieldName: 'before' | 'after', filter: readonly symbol[] | true | undefined): void;
     getSymbol(tapeBlock: TapeBlock): symbol;
     getCommand(symbol: symbol): Command;
     getNextState(symbol: symbol): State | Reference;
@@ -47,3 +66,4 @@ export default class State {
     };
 }
 export declare const haltState: State;
+export {};

package/dist/classes/TuringMachine.d.ts

@@ -11,6 +11,19 @@ export type MachineState = {
     nextSymbols: string[];
     movements: symbol[];
     nextState: State;
+    /**
+     * Set only when this iteration boundary is a debug break.
+     * Field is OMITTED entirely when no break fires (no `debugBreak: undefined`).
+     * At least one of `before` / `after` is `true` when the field is present.
+     *
+     * For consumers of the `runStepByStep` generator the `state` field reflects
+     * the current iteration regardless of timing; `run()` substitutes the prior
+     * yield's snapshot for `after` calls so consumers see the source state.
+     */
+    debugBreak?: {
+        before?: true;
+        after?: true;
+    };
 };
 export default class TuringMachine {
     #private;
@@ -18,9 +31,24 @@ export default class TuringMachine {
         tapeBlock?: TapeBlock;
     });
     get tapeBlock(): TapeBlock;
-    run({ initialState, stepsLimit, onStep }: RunParameter & {
+    run({ initialState, stepsLimit, onStep, onPause, }: RunParameter & {
+        /**
+         * Sync, ~free hook fired on every iteration. Use for logging/tracing —
+         * the hot loop runs this without a microtask boundary, so it must not
+         * be async.
+         */
         onStep?: (machineState: MachineState) => void;
-    }): void;
-    runStepByStep({ initialState, stepsLimit }: RunParameter): Generator<MachineState>;
+        /**
+         * Async hook fired only when `state.debug[when]` matches at the current
+         * iteration. The promise is awaited inline, so the consumer can suspend
+         * execution by deferring its resolution. Use for pause-capable inspection
+         * (debugger UIs, conditional breakpoints in tests).
+         *
+         * Renamed from `onDebugBreak` in v5.0.0. The `m.debugBreak` payload field
+         * keeps its name (it describes the engine's reason for pausing).
+         */
+        onPause?: (machineState: MachineState) => void | Promise<void>;
+    }): Promise<void>;
+    runStepByStep({ initialState, stepsLimit }: RunParameter): Generator<MachineState, MachineState | null>;
 }
 export {};

package/dist/index.cjs

@@ -186,13 +186,18 @@ var __classPrivateFieldGet$4 = (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 _Tape_alphabet, _Tape_symbols, _Tape_position, _Tape_viewportWidth;
+var _Tape_instances, _Tape_alphabet, _Tape_right, _Tape_left, _Tape_position, _Tape_viewportWidth, _Tape_viewportBuffer, _Tape_viewportDirty, _Tape_cellAt;
+const BLANK_INDEX = 0;
 class Tape {
     constructor({ alphabet, symbols = [], position = 0, viewportWidth = 1, }) {
+        _Tape_instances.add(this);
         _Tape_alphabet.set(this, void 0);
-        _Tape_symbols.set(this, void 0);
+        _Tape_right.set(this, []);
+        _Tape_left.set(this, []);
         _Tape_position.set(this, void 0);
         _Tape_viewportWidth.set(this, void 0);
+        _Tape_viewportBuffer.set(this, []);
+        _Tape_viewportDirty.set(this, true);
         const isSymbolsValid = symbols.every((symbol) => alphabet.has(symbol));
         if (!isSymbolsValid) {
             throw new Error('symbolList contains invalid symbol');
@@ -200,11 +205,10 @@ class Tape {
         __classPrivateFieldSet$4(this, _Tape_alphabet, new Alphabet(alphabet), "f");
         __classPrivateFieldSet$4(this, _Tape_position, position, "f");
         __classPrivateFieldSet$4(this, _Tape_viewportWidth, 1, "f");
-        const symbolsCopy = Array.from(symbols);
-        if (symbolsCopy.length === 0) {
-            symbolsCopy.push(__classPrivateFieldGet$4(this, _Tape_alphabet, "f").blankSymbol);
+        const initialSymbols = symbols.length === 0 ? [__classPrivateFieldGet$4(this, _Tape_alphabet, "f").blankSymbol] : symbols;
+        for (const symbol of initialSymbols) {
+            __classPrivateFieldGet$4(this, _Tape_right, "f").push(__classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol));
         }
-        __classPrivateFieldSet$4(this, _Tape_symbols, symbolsCopy.map((symbol) => __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol)), "f");
         this.viewportWidth = viewportWidth;
     }
     get alphabet() {
@@ -214,27 +218,46 @@ class Tape {
         return (__classPrivateFieldGet$4(this, _Tape_viewportWidth, "f") - 1) / 2;
     }
     get position() {
-        return __classPrivateFieldGet$4(this, _Tape_position, "f");
+        // Public contract: index of the head in the `symbols` array. With the
+        // two-array deque, `#position` is the head's logical position; adding
+        // `#left.length` shifts it back into "index from the leftmost backed cell".
+        return __classPrivateFieldGet$4(this, _Tape_position, "f") + __classPrivateFieldGet$4(this, _Tape_left, "f").length;
     }
     get symbol() {
-        return __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_symbols, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")]);
+        return __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_instances, "m", _Tape_cellAt).call(this, __classPrivateFieldGet$4(this, _Tape_position, "f")));
     }
     set symbol(symbol) {
         if (!__classPrivateFieldGet$4(this, _Tape_alphabet, "f").has(symbol)) {
             throw new Error('Invalid symbol');
         }
-        __classPrivateFieldGet$4(this, _Tape_symbols, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol);
+        const index = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol);
+        if (__classPrivateFieldGet$4(this, _Tape_position, "f") >= 0) {
+            __classPrivateFieldGet$4(this, _Tape_right, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")] = index;
+        }
+        else {
+            __classPrivateFieldGet$4(this, _Tape_left, "f")[-__classPrivateFieldGet$4(this, _Tape_position, "f") - 1] = index;
+        }
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
     }
     get symbols() {
-        return __classPrivateFieldGet$4(this, _Tape_symbols, "f")
-            .map((index) => __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(index));
+        const result = new Array(__classPrivateFieldGet$4(this, _Tape_left, "f").length + __classPrivateFieldGet$4(this, _Tape_right, "f").length);
+        for (let i = 0; i < __classPrivateFieldGet$4(this, _Tape_left, "f").length; i += 1) {
+            result[i] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_left, "f")[__classPrivateFieldGet$4(this, _Tape_left, "f").length - 1 - i]);
+        }
+        for (let i = 0; i < __classPrivateFieldGet$4(this, _Tape_right, "f").length; i += 1) {
+            result[__classPrivateFieldGet$4(this, _Tape_left, "f").length + i] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_right, "f")[i]);
+        }
+        return result;
     }
     get viewport() {
-        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$4(this, _Tape_alphabet, "f").get(index));
+        if (__classPrivateFieldGet$4(this, _Tape_viewportDirty, "f")) {
+            const start = __classPrivateFieldGet$4(this, _Tape_position, "f") - this.extraCellsCount;
+            for (let i = 0; i < __classPrivateFieldGet$4(this, _Tape_viewportWidth, "f"); i += 1) {
+                __classPrivateFieldGet$4(this, _Tape_viewportBuffer, "f")[i] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_instances, "m", _Tape_cellAt).call(this, start + i));
+            }
+            __classPrivateFieldSet$4(this, _Tape_viewportDirty, false, "f");
+        }
+        return [...__classPrivateFieldGet$4(this, _Tape_viewportBuffer, "f")];
     }
     get viewportWidth() {
         return __classPrivateFieldGet$4(this, _Tape_viewportWidth, "f");
@@ -248,27 +271,38 @@ class Tape {
             finalWidth += 1;
         }
         __classPrivateFieldSet$4(this, _Tape_viewportWidth, finalWidth, "f");
+        __classPrivateFieldGet$4(this, _Tape_viewportBuffer, "f").length = finalWidth;
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
         this.normalise();
     }
     left() {
         __classPrivateFieldSet$4(this, _Tape_position, __classPrivateFieldGet$4(this, _Tape_position, "f") - 1, "f");
         this.normalise();
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
     }
     normalise() {
-        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");
+        const minLogical = __classPrivateFieldGet$4(this, _Tape_position, "f") - this.extraCellsCount;
+        const maxLogical = __classPrivateFieldGet$4(this, _Tape_position, "f") + this.extraCellsCount;
+        while (-__classPrivateFieldGet$4(this, _Tape_left, "f").length > minLogical) {
+            __classPrivateFieldGet$4(this, _Tape_left, "f").push(BLANK_INDEX);
         }
-        while (__classPrivateFieldGet$4(this, _Tape_position, "f") + this.extraCellsCount >= __classPrivateFieldGet$4(this, _Tape_symbols, "f").length) {
-            __classPrivateFieldGet$4(this, _Tape_symbols, "f").push(0);
+        while (__classPrivateFieldGet$4(this, _Tape_right, "f").length - 1 < maxLogical) {
+            __classPrivateFieldGet$4(this, _Tape_right, "f").push(BLANK_INDEX);
         }
     }
     right() {
         __classPrivateFieldSet$4(this, _Tape_position, __classPrivateFieldGet$4(this, _Tape_position, "f") + 1, "f");
         this.normalise();
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
     }
 }
-_Tape_alphabet = new WeakMap(), _Tape_symbols = new WeakMap(), _Tape_position = new WeakMap(), _Tape_viewportWidth = new WeakMap();
+_Tape_alphabet = new WeakMap(), _Tape_right = new WeakMap(), _Tape_left = new WeakMap(), _Tape_position = new WeakMap(), _Tape_viewportWidth = new WeakMap(), _Tape_viewportBuffer = new WeakMap(), _Tape_viewportDirty = new WeakMap(), _Tape_instances = new WeakSet(), _Tape_cellAt = function _Tape_cellAt(logical) {
+    if (logical >= 0) {
+        return logical < __classPrivateFieldGet$4(this, _Tape_right, "f").length ? __classPrivateFieldGet$4(this, _Tape_right, "f")[logical] : BLANK_INDEX;
+    }
+    const ix = -logical - 1;
+    return ix < __classPrivateFieldGet$4(this, _Tape_left, "f").length ? __classPrivateFieldGet$4(this, _Tape_left, "f")[ix] : BLANK_INDEX;
+};
 
 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");
@@ -624,25 +658,64 @@ function decodeWriteSymbol(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;
+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 _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_id, _State_name, _State_overrodeHaltState, _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.
+const validateDebugFilter = Symbol('validateDebugFilter');
+class DebugConfig {
+    constructor(ownerState, initial) {
+        _DebugConfig_ownerState.set(this, void 0);
+        _DebugConfig_before.set(this, void 0);
+        _DebugConfig_after.set(this, void 0);
+        __classPrivateFieldSet$1(this, _DebugConfig_ownerState, ownerState, "f");
+        if (initial) {
+            if (initial.before !== undefined) {
+                this.before = initial.before;
+            }
+            if (initial.after !== undefined) {
+                this.after = initial.after;
+            }
+        }
+    }
+    get before() {
+        return __classPrivateFieldGet$1(this, _DebugConfig_before, "f");
+    }
+    set before(v) {
+        __classPrivateFieldGet$1(this, _DebugConfig_ownerState, "f")[validateDebugFilter]('before', v);
+        __classPrivateFieldSet$1(this, _DebugConfig_before, Array.isArray(v) ? Object.freeze([...v]) : v, "f");
+    }
+    get after() {
+        return __classPrivateFieldGet$1(this, _DebugConfig_after, "f");
+    }
+    set after(v) {
+        __classPrivateFieldGet$1(this, _DebugConfig_ownerState, "f")[validateDebugFilter]('after', v);
+        __classPrivateFieldSet$1(this, _DebugConfig_after, Array.isArray(v) ? Object.freeze([...v]) : v, "f");
+    }
+}
+_DebugConfig_ownerState = new WeakMap(), _DebugConfig_before = new WeakMap(), _DebugConfig_after = new WeakMap();
 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());
+        // Shared mutable cell — withOverrodeHaltState 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.
+        _State_debugRef.set(this, { current: null });
         if (stateDefinition) {
             const keys = Object.getOwnPropertyNames(stateDefinition);
             if (keys.length) {
@@ -701,6 +774,36 @@ class State {
     get ref() {
         return this;
     }
+    get debug() {
+        return __classPrivateFieldGet$1(this, _State_debugRef, "f").current;
+    }
+    set debug(value) {
+        if (value === null) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = null;
+            return;
+        }
+        if (value instanceof DebugConfig) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = value;
+            return;
+        }
+        __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) {
+        if (filter === undefined || filter === true)
+            return;
+        // haltState has no own transitions; symbol-list filters on it are silent
+        // no-ops at the engine level (spec §8.6), so accept any list shape here.
+        if (this.isHalt)
+            return;
+        for (const sym of filter) {
+            if (sym !== ifOtherSymbol && !__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(sym)) {
+                throw new Error(`State.debug.${fieldName}: symbol is not a transition key of this state `
+                    + `(state name: ${__classPrivateFieldGet$1(this, _State_name, "f")}). Common cause: symbol comes from a `
+                    + 'different tape block, or doesn\'t match any of this state\'s transitions.');
+            }
+        }
+    }
     getSymbol(tapeBlock) {
         const symbol = [...__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").keys()].find((currentSymbol) => tapeBlock.isMatched({
             symbol: currentSymbol,
@@ -726,6 +829,7 @@ class State {
         const state = new State(null, `${this.name}>${overrodeHaltState.name}`);
         __classPrivateFieldSet$1(state, _State_symbolToDataMap, __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f"), "f");
         __classPrivateFieldSet$1(state, _State_overrodeHaltState, overrodeHaltState, "f");
+        __classPrivateFieldSet$1(state, _State_debugRef, __classPrivateFieldGet$1(this, _State_debugRef, "f"), "f");
         return state;
     }
     // Single-state introspection — no traversal, no tapeBlock required.
@@ -896,7 +1000,6 @@ class State {
         };
     }
 }
-_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) {
@@ -911,6 +1014,15 @@ var __classPrivateFieldGet = (undefined && undefined.__classPrivateFieldGet) ||
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _TuringMachine_tapeBlock, _TuringMachine_stack;
+// True iff `filter` matches `symbol` per the DebugConfig semantics.
+// undefined / [] -> never; true -> always; symbol[] -> exact membership.
+function matchFilter(filter, symbol) {
+    if (filter === undefined)
+        return false;
+    if (filter === true)
+        return true;
+    return filter.includes(symbol);
+}
 class TuringMachine {
     constructor({ tapeBlock, } = {}) {
         _TuringMachine_tapeBlock.set(this, void 0);
@@ -923,12 +1035,22 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    run({ initialState, stepsLimit = 1e5, onStep }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onDebugBreak, }) {
         const generator = this.runStepByStep({ initialState, stepsLimit });
+        let prevYield = null;
         for (const machineState of generator) {
+            // 'after' (from prev step) — fire FIRST, with prev yield substituted as the source view.
+            if (machineState.debugBreak?.after && onDebugBreak && prevYield) {
+                await onDebugBreak({ ...prevYield, debugBreak: { after: true } });
+            }
+            // 'before' (current step) — pass current machineState with only the before flag.
+            if (machineState.debugBreak?.before && onDebugBreak) {
+                await onDebugBreak({ ...machineState, debugBreak: { before: true } });
+            }
             if (onStep instanceof Function) {
                 onStep(machineState);
             }
+            prevYield = machineState;
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {
@@ -942,6 +1064,7 @@ class TuringMachine {
                 stack.push(state.overrodeHaltState);
             }
             let i = 0;
+            let pendingAfterFromPrev = false;
             while (!state.isHalt) {
                 if (i === stepsLimit) {
                     throw new Error('Long execution');
@@ -951,10 +1074,12 @@ class TuringMachine {
                 const command = state.getCommand(symbol);
                 let nextState = state.getNextState(symbol).ref;
                 try {
+                    const beforeMatch = matchFilter(state.debug?.before, symbol)
+                        || (nextState.isHalt && nextState.debug?.before === true);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
-                    yield {
+                    const yielded = {
                         step: i,
                         state,
                         currentSymbols: __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").currentSymbols,
@@ -974,6 +1099,17 @@ class TuringMachine {
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
                     };
+                    if (pendingAfterFromPrev || beforeMatch) {
+                        const dbg = {};
+                        if (pendingAfterFromPrev)
+                            dbg.after = true;
+                        if (beforeMatch)
+                            dbg.before = true;
+                        yielded.debugBreak = dbg;
+                    }
+                    yield yielded;
+                    // Re-evaluate 'after' for THIS visit, to fire on the NEXT yield.
+                    pendingAfterFromPrev = matchFilter(state.debug?.after, symbol);
                     __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").applyCommand(command, executionSymbol);
                     if (nextState.isHalt && stack.length) {
                         nextState = stack.pop();
@@ -1304,6 +1440,7 @@ function runOnce(runnable, input, stepsLimit) {
 
 exports.Alphabet = Alphabet;
 exports.Command = Command;
+exports.DebugConfig = DebugConfig;
 exports.Reference = Reference;
 exports.State = State;
 exports.Tape = Tape;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { default as Alphabet } from './classes/Alphabet';
 export { default as Command } from './classes/Command';
 export { default as Reference } from './classes/Reference';
-export { default as State, haltState, ifOtherSymbol } from './classes/State';
+export { default as State, DebugConfig, haltState, ifOtherSymbol } from './classes/State';
 export { default as Tape } from './classes/Tape';
 export { default as TapeBlock } from './classes/TapeBlock';
 export { default as TapeCommand, movements, symbolCommands } from './classes/TapeCommand';

package/dist/index.mjs

@@ -184,13 +184,18 @@ var __classPrivateFieldGet$4 = (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 _Tape_alphabet, _Tape_symbols, _Tape_position, _Tape_viewportWidth;
+var _Tape_instances, _Tape_alphabet, _Tape_right, _Tape_left, _Tape_position, _Tape_viewportWidth, _Tape_viewportBuffer, _Tape_viewportDirty, _Tape_cellAt;
+const BLANK_INDEX = 0;
 class Tape {
     constructor({ alphabet, symbols = [], position = 0, viewportWidth = 1, }) {
+        _Tape_instances.add(this);
         _Tape_alphabet.set(this, void 0);
-        _Tape_symbols.set(this, void 0);
+        _Tape_right.set(this, []);
+        _Tape_left.set(this, []);
         _Tape_position.set(this, void 0);
         _Tape_viewportWidth.set(this, void 0);
+        _Tape_viewportBuffer.set(this, []);
+        _Tape_viewportDirty.set(this, true);
         const isSymbolsValid = symbols.every((symbol) => alphabet.has(symbol));
         if (!isSymbolsValid) {
             throw new Error('symbolList contains invalid symbol');
@@ -198,11 +203,10 @@ class Tape {
         __classPrivateFieldSet$4(this, _Tape_alphabet, new Alphabet(alphabet), "f");
         __classPrivateFieldSet$4(this, _Tape_position, position, "f");
         __classPrivateFieldSet$4(this, _Tape_viewportWidth, 1, "f");
-        const symbolsCopy = Array.from(symbols);
-        if (symbolsCopy.length === 0) {
-            symbolsCopy.push(__classPrivateFieldGet$4(this, _Tape_alphabet, "f").blankSymbol);
+        const initialSymbols = symbols.length === 0 ? [__classPrivateFieldGet$4(this, _Tape_alphabet, "f").blankSymbol] : symbols;
+        for (const symbol of initialSymbols) {
+            __classPrivateFieldGet$4(this, _Tape_right, "f").push(__classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol));
         }
-        __classPrivateFieldSet$4(this, _Tape_symbols, symbolsCopy.map((symbol) => __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol)), "f");
         this.viewportWidth = viewportWidth;
     }
     get alphabet() {
@@ -212,27 +216,46 @@ class Tape {
         return (__classPrivateFieldGet$4(this, _Tape_viewportWidth, "f") - 1) / 2;
     }
     get position() {
-        return __classPrivateFieldGet$4(this, _Tape_position, "f");
+        // Public contract: index of the head in the `symbols` array. With the
+        // two-array deque, `#position` is the head's logical position; adding
+        // `#left.length` shifts it back into "index from the leftmost backed cell".
+        return __classPrivateFieldGet$4(this, _Tape_position, "f") + __classPrivateFieldGet$4(this, _Tape_left, "f").length;
     }
     get symbol() {
-        return __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_symbols, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")]);
+        return __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_instances, "m", _Tape_cellAt).call(this, __classPrivateFieldGet$4(this, _Tape_position, "f")));
     }
     set symbol(symbol) {
         if (!__classPrivateFieldGet$4(this, _Tape_alphabet, "f").has(symbol)) {
             throw new Error('Invalid symbol');
         }
-        __classPrivateFieldGet$4(this, _Tape_symbols, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol);
+        const index = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").index(symbol);
+        if (__classPrivateFieldGet$4(this, _Tape_position, "f") >= 0) {
+            __classPrivateFieldGet$4(this, _Tape_right, "f")[__classPrivateFieldGet$4(this, _Tape_position, "f")] = index;
+        }
+        else {
+            __classPrivateFieldGet$4(this, _Tape_left, "f")[-__classPrivateFieldGet$4(this, _Tape_position, "f") - 1] = index;
+        }
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
     }
     get symbols() {
-        return __classPrivateFieldGet$4(this, _Tape_symbols, "f")
-            .map((index) => __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(index));
+        const result = new Array(__classPrivateFieldGet$4(this, _Tape_left, "f").length + __classPrivateFieldGet$4(this, _Tape_right, "f").length);
+        for (let i = 0; i < __classPrivateFieldGet$4(this, _Tape_left, "f").length; i += 1) {
+            result[i] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_left, "f")[__classPrivateFieldGet$4(this, _Tape_left, "f").length - 1 - i]);
+        }
+        for (let i = 0; i < __classPrivateFieldGet$4(this, _Tape_right, "f").length; i += 1) {
+            result[__classPrivateFieldGet$4(this, _Tape_left, "f").length + i] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_right, "f")[i]);
+        }
+        return result;
     }
     get viewport() {
-        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$4(this, _Tape_alphabet, "f").get(index));
+        if (__classPrivateFieldGet$4(this, _Tape_viewportDirty, "f")) {
+            const start = __classPrivateFieldGet$4(this, _Tape_position, "f") - this.extraCellsCount;
+            for (let i = 0; i < __classPrivateFieldGet$4(this, _Tape_viewportWidth, "f"); i += 1) {
+                __classPrivateFieldGet$4(this, _Tape_viewportBuffer, "f")[i] = __classPrivateFieldGet$4(this, _Tape_alphabet, "f").get(__classPrivateFieldGet$4(this, _Tape_instances, "m", _Tape_cellAt).call(this, start + i));
+            }
+            __classPrivateFieldSet$4(this, _Tape_viewportDirty, false, "f");
+        }
+        return [...__classPrivateFieldGet$4(this, _Tape_viewportBuffer, "f")];
     }
     get viewportWidth() {
         return __classPrivateFieldGet$4(this, _Tape_viewportWidth, "f");
@@ -246,27 +269,38 @@ class Tape {
             finalWidth += 1;
         }
         __classPrivateFieldSet$4(this, _Tape_viewportWidth, finalWidth, "f");
+        __classPrivateFieldGet$4(this, _Tape_viewportBuffer, "f").length = finalWidth;
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
         this.normalise();
     }
     left() {
         __classPrivateFieldSet$4(this, _Tape_position, __classPrivateFieldGet$4(this, _Tape_position, "f") - 1, "f");
         this.normalise();
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
     }
     normalise() {
-        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");
+        const minLogical = __classPrivateFieldGet$4(this, _Tape_position, "f") - this.extraCellsCount;
+        const maxLogical = __classPrivateFieldGet$4(this, _Tape_position, "f") + this.extraCellsCount;
+        while (-__classPrivateFieldGet$4(this, _Tape_left, "f").length > minLogical) {
+            __classPrivateFieldGet$4(this, _Tape_left, "f").push(BLANK_INDEX);
         }
-        while (__classPrivateFieldGet$4(this, _Tape_position, "f") + this.extraCellsCount >= __classPrivateFieldGet$4(this, _Tape_symbols, "f").length) {
-            __classPrivateFieldGet$4(this, _Tape_symbols, "f").push(0);
+        while (__classPrivateFieldGet$4(this, _Tape_right, "f").length - 1 < maxLogical) {
+            __classPrivateFieldGet$4(this, _Tape_right, "f").push(BLANK_INDEX);
         }
     }
     right() {
         __classPrivateFieldSet$4(this, _Tape_position, __classPrivateFieldGet$4(this, _Tape_position, "f") + 1, "f");
         this.normalise();
+        __classPrivateFieldSet$4(this, _Tape_viewportDirty, true, "f");
     }
 }
-_Tape_alphabet = new WeakMap(), _Tape_symbols = new WeakMap(), _Tape_position = new WeakMap(), _Tape_viewportWidth = new WeakMap();
+_Tape_alphabet = new WeakMap(), _Tape_right = new WeakMap(), _Tape_left = new WeakMap(), _Tape_position = new WeakMap(), _Tape_viewportWidth = new WeakMap(), _Tape_viewportBuffer = new WeakMap(), _Tape_viewportDirty = new WeakMap(), _Tape_instances = new WeakSet(), _Tape_cellAt = function _Tape_cellAt(logical) {
+    if (logical >= 0) {
+        return logical < __classPrivateFieldGet$4(this, _Tape_right, "f").length ? __classPrivateFieldGet$4(this, _Tape_right, "f")[logical] : BLANK_INDEX;
+    }
+    const ix = -logical - 1;
+    return ix < __classPrivateFieldGet$4(this, _Tape_left, "f").length ? __classPrivateFieldGet$4(this, _Tape_left, "f")[ix] : BLANK_INDEX;
+};
 
 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");
@@ -622,25 +656,64 @@ function decodeWriteSymbol(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;
+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 _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_id, _State_name, _State_overrodeHaltState, _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.
+const validateDebugFilter = Symbol('validateDebugFilter');
+class DebugConfig {
+    constructor(ownerState, initial) {
+        _DebugConfig_ownerState.set(this, void 0);
+        _DebugConfig_before.set(this, void 0);
+        _DebugConfig_after.set(this, void 0);
+        __classPrivateFieldSet$1(this, _DebugConfig_ownerState, ownerState, "f");
+        if (initial) {
+            if (initial.before !== undefined) {
+                this.before = initial.before;
+            }
+            if (initial.after !== undefined) {
+                this.after = initial.after;
+            }
+        }
+    }
+    get before() {
+        return __classPrivateFieldGet$1(this, _DebugConfig_before, "f");
+    }
+    set before(v) {
+        __classPrivateFieldGet$1(this, _DebugConfig_ownerState, "f")[validateDebugFilter]('before', v);
+        __classPrivateFieldSet$1(this, _DebugConfig_before, Array.isArray(v) ? Object.freeze([...v]) : v, "f");
+    }
+    get after() {
+        return __classPrivateFieldGet$1(this, _DebugConfig_after, "f");
+    }
+    set after(v) {
+        __classPrivateFieldGet$1(this, _DebugConfig_ownerState, "f")[validateDebugFilter]('after', v);
+        __classPrivateFieldSet$1(this, _DebugConfig_after, Array.isArray(v) ? Object.freeze([...v]) : v, "f");
+    }
+}
+_DebugConfig_ownerState = new WeakMap(), _DebugConfig_before = new WeakMap(), _DebugConfig_after = new WeakMap();
 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());
+        // Shared mutable cell — withOverrodeHaltState 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.
+        _State_debugRef.set(this, { current: null });
         if (stateDefinition) {
             const keys = Object.getOwnPropertyNames(stateDefinition);
             if (keys.length) {
@@ -699,6 +772,36 @@ class State {
     get ref() {
         return this;
     }
+    get debug() {
+        return __classPrivateFieldGet$1(this, _State_debugRef, "f").current;
+    }
+    set debug(value) {
+        if (value === null) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = null;
+            return;
+        }
+        if (value instanceof DebugConfig) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = value;
+            return;
+        }
+        __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) {
+        if (filter === undefined || filter === true)
+            return;
+        // haltState has no own transitions; symbol-list filters on it are silent
+        // no-ops at the engine level (spec §8.6), so accept any list shape here.
+        if (this.isHalt)
+            return;
+        for (const sym of filter) {
+            if (sym !== ifOtherSymbol && !__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(sym)) {
+                throw new Error(`State.debug.${fieldName}: symbol is not a transition key of this state `
+                    + `(state name: ${__classPrivateFieldGet$1(this, _State_name, "f")}). Common cause: symbol comes from a `
+                    + 'different tape block, or doesn\'t match any of this state\'s transitions.');
+            }
+        }
+    }
     getSymbol(tapeBlock) {
         const symbol = [...__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").keys()].find((currentSymbol) => tapeBlock.isMatched({
             symbol: currentSymbol,
@@ -724,6 +827,7 @@ class State {
         const state = new State(null, `${this.name}>${overrodeHaltState.name}`);
         __classPrivateFieldSet$1(state, _State_symbolToDataMap, __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f"), "f");
         __classPrivateFieldSet$1(state, _State_overrodeHaltState, overrodeHaltState, "f");
+        __classPrivateFieldSet$1(state, _State_debugRef, __classPrivateFieldGet$1(this, _State_debugRef, "f"), "f");
         return state;
     }
     // Single-state introspection — no traversal, no tapeBlock required.
@@ -894,7 +998,6 @@ class State {
         };
     }
 }
-_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) {
@@ -909,6 +1012,15 @@ var __classPrivateFieldGet = (undefined && undefined.__classPrivateFieldGet) ||
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _TuringMachine_tapeBlock, _TuringMachine_stack;
+// True iff `filter` matches `symbol` per the DebugConfig semantics.
+// undefined / [] -> never; true -> always; symbol[] -> exact membership.
+function matchFilter(filter, symbol) {
+    if (filter === undefined)
+        return false;
+    if (filter === true)
+        return true;
+    return filter.includes(symbol);
+}
 class TuringMachine {
     constructor({ tapeBlock, } = {}) {
         _TuringMachine_tapeBlock.set(this, void 0);
@@ -921,12 +1033,22 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    run({ initialState, stepsLimit = 1e5, onStep }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onDebugBreak, }) {
         const generator = this.runStepByStep({ initialState, stepsLimit });
+        let prevYield = null;
         for (const machineState of generator) {
+            // 'after' (from prev step) — fire FIRST, with prev yield substituted as the source view.
+            if (machineState.debugBreak?.after && onDebugBreak && prevYield) {
+                await onDebugBreak({ ...prevYield, debugBreak: { after: true } });
+            }
+            // 'before' (current step) — pass current machineState with only the before flag.
+            if (machineState.debugBreak?.before && onDebugBreak) {
+                await onDebugBreak({ ...machineState, debugBreak: { before: true } });
+            }
             if (onStep instanceof Function) {
                 onStep(machineState);
             }
+            prevYield = machineState;
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {
@@ -940,6 +1062,7 @@ class TuringMachine {
                 stack.push(state.overrodeHaltState);
             }
             let i = 0;
+            let pendingAfterFromPrev = false;
             while (!state.isHalt) {
                 if (i === stepsLimit) {
                     throw new Error('Long execution');
@@ -949,10 +1072,12 @@ class TuringMachine {
                 const command = state.getCommand(symbol);
                 let nextState = state.getNextState(symbol).ref;
                 try {
+                    const beforeMatch = matchFilter(state.debug?.before, symbol)
+                        || (nextState.isHalt && nextState.debug?.before === true);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
-                    yield {
+                    const yielded = {
                         step: i,
                         state,
                         currentSymbols: __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").currentSymbols,
@@ -972,6 +1097,17 @@ class TuringMachine {
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
                     };
+                    if (pendingAfterFromPrev || beforeMatch) {
+                        const dbg = {};
+                        if (pendingAfterFromPrev)
+                            dbg.after = true;
+                        if (beforeMatch)
+                            dbg.before = true;
+                        yielded.debugBreak = dbg;
+                    }
+                    yield yielded;
+                    // Re-evaluate 'after' for THIS visit, to fire on the NEXT yield.
+                    pendingAfterFromPrev = matchFilter(state.debug?.after, symbol);
                     __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").applyCommand(command, executionSymbol);
                     if (nextState.isHalt && stack.length) {
                         nextState = stack.pop();
@@ -1300,4 +1436,4 @@ function runOnce(runnable, input, stepsLimit) {
     };
 }
 
-export { Alphabet, Command, Reference, State, Tape, TapeBlock, TapeCommand, TuringMachine, equivalentOn, fromMermaid, haltState, ifOtherSymbol, movements, summarize, summarizeGraph, symbolCommands, toMermaid };
+export { Alphabet, Command, DebugConfig, Reference, State, Tape, TapeBlock, TapeCommand, TuringMachine, equivalentOn, fromMermaid, haltState, ifOtherSymbol, movements, summarize, summarizeGraph, symbolCommands, toMermaid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "3.0.2",
+  "version": "5.0.0",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
@@ -34,5 +34,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "0a78b4d0d40bbdbf79e3c53694adf930f0567b0a"
+  "gitHead": "ccf9a4743965c2a4ea6340ce1de8f6596e094251"
 }