@turing-machine-js/machine 6.0.0 → 6.1.0

package/README.md

@@ -3,7 +3,25 @@
 [![build](https://github.com/mellonis/turing-machine-js/actions/workflows/main.yml/badge.svg)](https://github.com/mellonis/turing-machine-js/actions/workflows/main.yml)
 ![npm (tag)](https://img.shields.io/npm/v/@turing-machine-js/machine)
 
-Some basic objects to build your own turing machine  
+A composable Turing-machine engine for JavaScript: multi-tape, subroutine composition via `withOverrodeHaltState`, Mermaid round-trip, and runtime breakpoints.
+
+<details>
+<summary>Table of contents</summary>
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Building from a state table](#building-from-a-state-table)
+- [Classes](#classes) — [`Alphabet`](#alphabet) · [`Tape`](#tape) · [`TapeBlock`](#tapeblock) · [`TapeCommand`](#tapecommand) · [`Command`](#command) · [`State`](#state) · [`Reference`](#reference) · [`TuringMachine`](#turingmachine)
+- [Subroutine composition with `withOverrodeHaltState`](#subroutine-composition-with-withoverrodehaltstate)
+- [Debugging breakpoints](#debugging-breakpoints)
+- [Special objects](#special-objects) — [`haltState`](#haltstate) · [`ifOtherSymbol`](#ifothersymbol) · [`movements`](#movements) · [`symbolCommands`](#symbolcommands)
+- [Introspection and testing](#introspection-and-testing)
+- [Versioning notes](#versioning-notes)
+- [Libraries](#libraries)
+- [Links](#links)
+
+</details>
+
 
 ## Install
 
@@ -46,13 +64,43 @@ await machine.run({
     [ifOtherSymbol]: {
       command: [{ movement: movements.right }],
     },
-  }),
+  }, 'replaceB'),
 });
 
 console.log(tape.symbols.join('').trim()); // a*c*a
 ```
 
-A `State` is keyed by JS `Symbol`s returned from `tapeBlock.symbol(pattern)` — the pattern lists the expected symbol under each tape's head. `ifOtherSymbol` is the fallback key when nothing else matches; transitioning into `haltState` stops the run.
+The state graph for the example above:
+
+```mermaid
+flowchart LR
+    S(("**replaceB**"))
+    H((("**halt**")))
+    S -- "b → *, R" --> S
+    S -- "_ → keep, L" --> H
+    S -- "any other → keep, R" --> S
+```
+
+*Reading the labels: `read → write, move`. `_` is the blank symbol.*
+
+<details>
+<summary>📊 Same diagram, generated by <code>toMermaid()</code> (the engine's actual output)</summary>
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","c","*"]]
+  s0(((halt)))
+  s1(("replaceB"))
+  s1 -- "b → */R" --> s1
+  s1 -- "- → ·/L" --> s0
+  s1 -- "* → ·/R" --> s1
+```
+
+Engine notation: `read → write/move`; `·` = keep, `⌫` = erase, `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `(("round"))` = the initial state passed to `toGraph`; `["square"]` = a state reachable from the initial state.
+
+</details>
+
+A `State` is keyed by JS `Symbol`s returned from `tapeBlock.symbol(pattern)` — the pattern lists the expected symbol under each tape's head. Sentinels and constants used throughout: [`ifOtherSymbol`](#ifothersymbol) is the fallback key when nothing else matches; transitioning into [`haltState`](#haltstate) stops the run; [`movements`](#movements)`.{left,right,stay}` direct head moves; [`symbolCommands`](#symbolcommands)`.{keep,erase}` are write shortcuts. Full definitions in [§Special objects](#special-objects).
 
 For multi-tape machines, pass one element per tape: `tapeBlock.symbol(['0', 'a'])` matches only when tape 1 is at `'0'` and tape 2 is at `'a'`.
 
@@ -143,6 +191,16 @@ tape.right();       // move head right; auto-extends with blanks at the edge
 tape.symbol = 'X';  // write the cell under head
 ```
 
+For visualization-friendly UIs, `Tape` exposes a fixed-width viewport centered on the head:
+
+```javascript
+const tape = new Tape({ alphabet, symbols: ['a', 'b', 'c'], viewportWidth: 7 });
+tape.viewport;       // 7-cell snapshot centered on the head, padded with blanks
+tape.viewportWidth;  // 7 (the constructor bumps even values to the next odd)
+```
+
+`viewportWidth` defaults to `1` and must be ≥ 1; `tape.viewport` always has exactly `viewportWidth` cells regardless of how many symbols the tape actually holds. Useful for rendering a sliding window in a UI; ignore if you only need `tape.symbols` / `tape.position`.
+
 ### TapeBlock
 
 A bundle of one or more `Tape`s that the machine reads/writes together in lock-step. Construct via either factory:
@@ -186,8 +244,7 @@ A node in the transition graph. Construct with a definition object whose keys ar
 ```javascript
 const s = new State({
   [tapeBlock.symbol(['1'])]: { command: { symbol: '0', movement: movements.right } },
-  [tapeBlock.symbol(['$'])]: { nextState: haltState },
-  [ifOtherSymbol]:           { command: { movement: movements.right } },
+  [tapeBlock.symbol(['$'])]: { command: { movement: movements.left }, nextState: haltState },
 }, 'name');
 ```
 
@@ -198,6 +255,32 @@ Notable members and statics:
 - **`State.toGraph(state, tapeBlock)`** — walks the reachable graph from `state` and returns a serializable `Graph` (states, transitions, alphabets).
 - **`State.fromGraph(graph)`** — inverse of `toGraph`: rebuilds `State` instances + a fresh `TapeBlock` from a `Graph`. Round-trips together with `toMermaid` / `fromMermaid`.
 
+For visualization, pair `State.toGraph` with `toMermaid` to render the graph in any Mermaid-aware viewer (GitHub, VS Code, mermaid.live):
+
+```javascript
+import { State, toMermaid } from '@turing-machine-js/machine';
+
+const graph = State.toGraph(s, tapeBlock);
+console.log(toMermaid(graph));
+```
+
+The string `toMermaid` produces is a real Mermaid flowchart that renders in-place anywhere Mermaid is supported:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","0","1","$"]]
+  s0(((halt)))
+  s1(("name"))
+  s1 -- "1 → 0/R" --> s1
+  s1 -- "$ → ·/L" --> s0
+```
+
+*Edge labels are `read → write/move`. `·` is the keep-current-symbol marker (no write); `L` / `R` / `S` are head moves.*
+
+> 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
+
+`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). It is *not* bytewise lossless: state IDs auto-reassign on each rebuild, and for `withOverrodeHaltState` wrappers the composite name gains a `>${override.name}` suffix on each pass (e.g., `scanToX>eraseHere` becomes `scanToX>eraseHere>eraseHere` on a second round-trip — tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138)).
+
 ### Reference
 
 A forward-declaration handle, used when a `State` needs to point at another `State` that doesn't exist yet (cyclic graphs). Construct unbound, pass as `nextState`, call `.bind(actualState)` once that state has been built.
@@ -209,7 +292,33 @@ const b = new State({ [symbol(['y'])]: { nextState: a  } }, 'b');
 ref.bind(b);   // a's transition now resolves to b at run time
 ```
 
-`reference.ref` returns the bound state and throws if the reference is still unbound when the machine runs.
+The resulting cycle:
+
+```mermaid
+flowchart LR
+    a(("**a**"))
+    b(("**b**"))
+    a -- "x" --> b
+    b -- "y" --> a
+```
+
+<details>
+<summary>📊 Same diagram, generated by <code>toMermaid()</code></summary>
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","x","y"]]
+  s1(("a"))
+  s2["b"]
+  s1 -- "x → ·/S" --> s2
+  s2 -- "y → ·/S" --> s1
+```
+
+`a` is round (the initial state passed to `toGraph`); `b` is square (reachable from `a`).
+
+</details>
+
+`reference.ref` returns the bound state and throws if the reference is still unbound when the machine runs. `bind()` is sticky — the first call wins; subsequent calls are silent no-ops that return the existing binding.
 
 ### TuringMachine
 
@@ -218,7 +327,7 @@ The runtime. Owns one `TapeBlock` and drives a state graph until it reaches `hal
 ```javascript
 const machine = new TuringMachine({ tapeBlock });
 
-// Run to halt — `run()` is async (v4+), it returns a Promise<void>:
+// Run to halt — `run()` returns a Promise<void>:
 await machine.run({ initialState, stepsLimit: 1e5 });
 
 // Or step-by-step (useful for visualization / debugging):
@@ -227,34 +336,163 @@ for (const step of machine.runStepByStep({ initialState })) {
 }
 ```
 
+Each yielded `step` (`MachineState`) has these fields:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `step` | `number` | 1-indexed iteration number |
+| `state` | `State` | the state about to execute |
+| `currentSymbols` | `string[]` | per-tape head symbols, before the command applies |
+| `nextSymbols` | `string[]` | per-tape symbols that will be written |
+| `movements` | `symbol[]` | per-tape head moves (`movements.left/right/stay`) |
+| `nextState` | `State` | the state that will execute next |
+| `debugBreak?` | `{ before?: true, after?: true }` | only set when `state.debug` matched on this iter — see *Debugging breakpoints* below |
+
 `stepsLimit` (default `1e5`) guards against runaway loops — exceeding it throws.
 
-## Debugging breakpoints (v4+)
+#### Choosing between `run()` and `runStepByStep()`
+
+Both APIs are first-class — `run()` is built on top of `runStepByStep()` (see [TuringMachine.ts](src/classes/TuringMachine.ts)), and both stay supported. They model different consumer needs:
+
+| | `run()` | `runStepByStep()` |
+|---|---|---|
+| Shape | async, returns `Promise<void>` | synchronous generator |
+| Iteration timing | owned by the engine | owned by the consumer (`.next()` per step) |
+| Lifecycle hooks | dispatches `onStep`, `onPause` (gated by the `debug` master switch) | none — yields raw `MachineState` |
+| How `state.debug` reaches the consumer | the `onPause` callback (when `debug: true`) | the optional `debugBreak` field on each yield (always populated; consumer decides what to do) |
+| Best for | run-to-halt with optional breakpoint UI; anything wanting the v6 per-iter `before → step → after` callbacks | synchronous test harnesses, visualizers that need tight control over step timing, custom batching |
+
+**Rule of thumb.** If your consumer reads `state.debug` and expects the engine to act on it (pause, fire callbacks), use `run()`. If you want pull-based iteration with full control over timing, use `runStepByStep()` — the `debugBreak` field is still on every yield, so you can inspect breakpoint metadata yourself.
+
+**Don't split one logical flow across both APIs.** A consumer that wants stepwise UI *and* hook-driven breakpoints should use `run({ onStep, onPause, debug })` exclusively, implementing "wait between steps" by awaiting a resolvable Promise inside `onStep`. Routing some operations through `runStepByStep()` and others through `run()` means `state.debug` only flows through one of the two paths — a subtle footgun where breakpoints silently disappear on whichever code path uses the generator directly.
+
+## Subroutine composition with `withOverrodeHaltState`
+
+`state.withOverrodeHaltState(other)` returns a copy of `state` whose would-be halt transitions fall through to `other` at run time. The original is left untouched. This is the engine's only composition primitive — bigger machines are built by stacking smaller halt-on-completion subroutines.
+
+```javascript
+import { Alphabet, State, TapeBlock, TuringMachine, Tape, haltState, ifOtherSymbol, movements, symbolCommands } from '@turing-machine-js/machine';
+
+const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
+const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+const { symbol } = tapeBlock;
+
+// Reusable subroutine 1: walk right until 'X', halt on it.
+const scanToX = new State({
+  [symbol(['X'])]: { nextState: haltState },
+  [ifOtherSymbol]: { command: { movement: movements.right } },
+}, 'scanToX');
+
+// Reusable subroutine 2: erase the head cell, halt.
+const eraseHere = new State({
+  [ifOtherSymbol]: { command: { symbol: symbolCommands.erase }, nextState: haltState },
+}, 'eraseHere');
+
+// Compose: scan to X, then ERASE it. scanToX is unmodified.
+const scanThenErase = scanToX.withOverrodeHaltState(eraseHere);
+
+const tape = new Tape({ alphabet, symbols: ['a', 'b', 'X', 'b', 'a'] });
+tapeBlock.replaceTape(tape);
+await new TuringMachine({ tapeBlock }).run({ initialState: scanThenErase });
+
+console.log(tape.symbols.join('')); // "ab ba" — the X at index 2 is gone, head landed there.
+```
+
+What changes between *running `scanToX` standalone* and *running the composed wrapper*:
+
+```mermaid
+flowchart LR
+    subgraph standalone["scanToX (standalone) — halts at X"]
+        direction LR
+        a1(("scanToX"))
+        h1(((halt)))
+        a1 -- "X → keep, S" --> h1
+        a1 -- "any other → keep, R" --> a1
+    end
+    subgraph composed["scanToX.withOverrodeHaltState(eraseHere) — halt is intercepted"]
+        direction LR
+        a2(("scanToX"))
+        b2(("eraseHere"))
+        h2(((halt)))
+        a2 -. "X → keep, S<br/>intercepted" .-> b2
+        a2 -- "any other → keep, R" --> a2
+        b2 -- "any → erase, S" --> h2
+    end
+```
+
+<details>
+<summary>📊 Both diagrams, generated by <code>toMermaid()</code></summary>
+
+`toMermaid(toGraph(scanToX, tapeBlock))` — the standalone subroutine:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1(("scanToX"))
+  s1 -- "X → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+```
+
+`toMermaid(toGraph(scanThenErase, tapeBlock))` — the wrapped composition:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1["scanToX"]
+  s2["eraseHere"]
+  s3(("scanToX>eraseHere"))
+  s1 -- "X → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s2 -- "* → ⌫/S" --> s0
+  s3 -- "X → ·/S" --> s0
+  s3 -- "* → ·/R" --> s1
+  s3 -. onHalt .-> s2
+```
+
+**Reading guide** — the wrapped diagram is denser than the simplified hand-drawn version above. To parse it:
+
+1. **Three non-halt nodes:** the wrapper `scanToX>eraseHere` (round, the initial state); `scanToX` (square, the original subroutine — unmodified); `eraseHere` (square, the override target). The wrapper appears as a *separate* state from `scanToX`-the-original because `withOverrodeHaltState` returns a new `State` instance — even though it shares the transition map.
+2. **Solid edges from the wrapper duplicate `scanToX`'s edges.** That's because the wrapper inherits the same `symbolToDataMap`. Importantly, the wrapper's `* → ·/R` edge points at *`scanToX`-the-original*, not at the wrapper itself — so after the first iteration, control transfers to `scanToX` and stays there.
+3. **The dotted `onHalt` edge is attached to the wrapper** but it doesn't fire on a single edge at runtime. Instead, the runtime pushes `eraseHere` onto an internal stack at startup, and *any* halt-bound transition reachable during the run (whether on the wrapper itself or on `scanToX`) gets redirected to `eraseHere` via stack-pop. The dotted edge is the engine's static fingerprint of "this graph was wrapped by `withOverrodeHaltState`."
+4. **What actually fires at runtime, on tape `['a','b','X','b','a']`:** the wrapper runs once, transferring to `scanToX`; `scanToX` self-loops on `* → ·/R` until it sees `X`; the `X → ·/S` edge tries to go to halt; the runtime pops `eraseHere` off the stack and substitutes it; `eraseHere` erases the cell and halts. The wrapper's own `X → ·/S → halt` edge in the diagram is *never traversed* because control left the wrapper after iteration 1.
+
+> 💡 **The engine's emit could be more user-friendly here.** Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) — the wrapper's duplicated edges and the misleading single-edge `onHalt` placement are candidates for a cleaner `toMermaid` output.
+
+</details>
+
+Wrappers nest: `inner.withOverrodeHaltState(middle).withOverrodeHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
+
+## Debugging breakpoints
 
 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';
+import { State, haltState, ifOtherSymbol } from '@turing-machine-js/machine';
 
 const myState = new State({...});
 
-// Pause before applying any of myState's commands:
-myState.debug = { before: true };
+// state.debug is always a DebugConfig instance — chained writes work
+// without prior whole-object assignment:
+myState.debug.before = true;
+myState.debug.after = [symA];
 
-// Pause only when the head shows symA:
+// Whole-object assignment also works for one-shot setup:
+myState.debug = { before: true };
 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:
+// Reset filters later — next read returns a fresh empty DebugConfig:
 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.
+> ⚠️ **`haltState.debug.after` throws.** Halt is terminal — there is no iteration-after-halt for an after-fire to anchor on. Assigning a truthy `.after` to `haltState.debug` (including `{ before: true, after: true }`) throws at write time. Symbol-list filters on `haltState.debug.before` are silent no-ops, since halt has no head symbol; only the wildcard `true` activates.
+
+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. `state.debug` is always a `DebugConfig` instance (lazy-initialized on first read); plain-object input (`state.debug = { before: true }`) is wrapped in a fresh `DebugConfig` automatically. The instance itself is `Object.seal`-ed — typos like `state.debug.bofore = true` throw `TypeError` instead of silently creating a useless property. Per-property setters validate and freeze the stored array, so `state.debug.before.push(...)` also throws `TypeError`.
 
 `run()` is async and accepts an `onPause` hook:
 
@@ -344,6 +582,17 @@ Together: use `summarize` to ask "is this machine the right shape?" (size, compo
 
 For visualization and round-tripping, see `State.toGraph` / `State.fromGraph` and `toMermaid` / `fromMermaid`.
 
+## Versioning notes
+
+API surface changes since v3, in past tense so the timing of each piece is explicit:
+
+- **v4** — `run()` became async (`Promise<void>`). Per-state runtime breakpoints landed (`state.debug.before` / `state.debug.after`); `run()` accepted an `onDebugBreak` hook. `MachineState` exposed on each yield.
+- **v5** — `onDebugBreak` renamed to `onPause`. New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without unsetting `state.debug` assignments. Assigning a truthy `.after` to `haltState.debug` now throws at write time (halt is terminal — no iteration-after-halt to anchor on).
+- **v6** — Per-iter lifecycle reordered to `before → step → after`, all firing on the same yield. Previously `after` fired on iter K+1's tick with a `prevYield` substitution dance; that substitution is gone. The `MachineState.debugBreak` field shape is unchanged across all three versions.
+- **v6.1** — `state.debug` ergonomics: the field is now always a non-null `DebugConfig` instance (lazy-initialized on first read), so chained field writes like `state.debug.before = true` work on a fresh state without a prior whole-object assignment. The `DebugConfig` instance is `Object.seal`-ed, so typos like `state.debug.bofore = true` throw `TypeError` at write time instead of silently creating a useless property. `state.debug = null` continues to work but semantically means "reset filters" — the next read returns a fresh empty `DebugConfig` (#150).
+
+For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
+
 ## Libraries
 
 - [@turing-machine-js/library-binary-numbers](https://github.com/mellonis/turing-machine-js/tree/master/packages/library-binary-numbers) — binary arithmetic with `^…$` markers, multi-number-per-tape support
@@ -351,4 +600,4 @@ For visualization and round-tripping, see `State.toGraph` / `State.fromGraph` an
 
 ## Links
 
-- [Turing Machine](https://en.wikipedia.org/wiki/Turing_machine) on the Wikipedia
+- [Turing Machine](https://en.wikipedia.org/wiki/Turing_machine) on Wikipedia

package/dist/classes/State.d.ts

@@ -27,7 +27,7 @@ export default class State {
     get isHalt(): boolean;
     get overrodeHaltState(): State | null;
     get ref(): this;
-    get debug(): DebugConfig | null;
+    get debug(): DebugConfig;
     set debug(value: DebugConfig | {
         before?: symbol[] | readonly symbol[] | true;
         after?: symbol[] | readonly symbol[] | true;

package/dist/index.cjs

@@ -688,6 +688,12 @@ class DebugConfig {
                 this.after = initial.after;
             }
         }
+        // Seal the instance so typos like `cfg.bofore = true` throw at write
+        // time (in strict mode, which TS-emitted modules use) instead of
+        // silently creating a useless own property. The class's `before`/`after`
+        // setters still work — they resolve through the prototype chain and
+        // write to private fields, neither of which Object.seal restricts.
+        Object.seal(this);
     }
     get before() {
         return __classPrivateFieldGet$1(this, _DebugConfig_before, "f");
@@ -775,6 +781,14 @@ class State {
         return this;
     }
     get debug() {
+        // Lazy-init: `state.debug` is never null at read time, so chained writes
+        // like `state.debug.before = true` work on a fresh state without a prior
+        // whole-object assignment. The setter still accepts `null` to reset the
+        // filters; the next read recreates a fresh empty `DebugConfig` on demand.
+        // See #150.
+        if (__classPrivateFieldGet$1(this, _State_debugRef, "f").current === null) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this);
+        }
         return __classPrivateFieldGet$1(this, _State_debugRef, "f").current;
     }
     set debug(value) {
@@ -790,10 +804,21 @@ class State {
     }
     /** @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)
+        if (filter === undefined)
+            return;
+        // #108 part 2: `.after` on haltState has no semantic anchor — halt is
+        // terminal, so there is no iteration-after-halt for an after-fire to
+        // attach to. Reject any truthy assignment (true OR list) at write time
+        // so misuse surfaces immediately rather than silently no-op'ing.
+        if (this.isHalt && fieldName === 'after') {
+            throw new Error('haltState.debug.after is not supported: halt is terminal, so there is '
+                + 'no iteration-after-halt for an after-fire to anchor on. Use '
+                + '{ before: true } to pause on halt entry.');
+        }
+        if (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.
+        // haltState has no own transitions; symbol-list filters on `before` are
+        // silent no-ops at the engine level (spec §8.6), so accept any list shape.
         if (this.isHalt)
             return;
         for (const sym of filter) {
@@ -1035,22 +1060,21 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    async run({ initialState, stepsLimit = 1e5, onStep, onDebugBreak, }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onPause, debug = true, }) {
         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 } });
+            // Per-iter lifecycle: before → step → after. All three operate on the
+            // same yielded MachineState, so the consumer sees a coherent ordering
+            // within each iteration without cross-tick coordination.
+            if (debug && machineState.debugBreak?.before && onPause) {
+                await onPause({ ...machineState, debugBreak: { before: true } });
             }
             if (onStep instanceof Function) {
                 onStep(machineState);
             }
-            prevYield = machineState;
+            if (debug && machineState.debugBreak?.after && onPause) {
+                await onPause({ ...machineState, debugBreak: { after: true } });
+            }
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {
@@ -1064,7 +1088,6 @@ class TuringMachine {
                 stack.push(state.overrodeHaltState);
             }
             let i = 0;
-            let pendingAfterFromPrev = false;
             while (!state.isHalt) {
                 if (i === stepsLimit) {
                     throw new Error('Long execution');
@@ -1074,8 +1097,12 @@ class TuringMachine {
                 const command = state.getCommand(symbol);
                 let nextState = state.getNextState(symbol).ref;
                 try {
+                    // Both before and after refer to THIS iter (#119 / v6.0.0).
+                    // The halting iter's after-fire just rides along on the iter's
+                    // own yield — no post-loop drain needed.
                     const beforeMatch = matchFilter(state.debug?.before, symbol)
                         || (nextState.isHalt && nextState.debug?.before === true);
+                    const afterMatch = matchFilter(state.debug?.after, symbol);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
@@ -1099,17 +1126,15 @@ class TuringMachine {
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
                     };
-                    if (pendingAfterFromPrev || beforeMatch) {
+                    if (beforeMatch || afterMatch) {
                         const dbg = {};
-                        if (pendingAfterFromPrev)
-                            dbg.after = true;
                         if (beforeMatch)
                             dbg.before = true;
+                        if (afterMatch)
+                            dbg.after = 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();

package/dist/index.mjs

@@ -686,6 +686,12 @@ class DebugConfig {
                 this.after = initial.after;
             }
         }
+        // Seal the instance so typos like `cfg.bofore = true` throw at write
+        // time (in strict mode, which TS-emitted modules use) instead of
+        // silently creating a useless own property. The class's `before`/`after`
+        // setters still work — they resolve through the prototype chain and
+        // write to private fields, neither of which Object.seal restricts.
+        Object.seal(this);
     }
     get before() {
         return __classPrivateFieldGet$1(this, _DebugConfig_before, "f");
@@ -773,6 +779,14 @@ class State {
         return this;
     }
     get debug() {
+        // Lazy-init: `state.debug` is never null at read time, so chained writes
+        // like `state.debug.before = true` work on a fresh state without a prior
+        // whole-object assignment. The setter still accepts `null` to reset the
+        // filters; the next read recreates a fresh empty `DebugConfig` on demand.
+        // See #150.
+        if (__classPrivateFieldGet$1(this, _State_debugRef, "f").current === null) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this);
+        }
         return __classPrivateFieldGet$1(this, _State_debugRef, "f").current;
     }
     set debug(value) {
@@ -788,10 +802,21 @@ class State {
     }
     /** @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)
+        if (filter === undefined)
+            return;
+        // #108 part 2: `.after` on haltState has no semantic anchor — halt is
+        // terminal, so there is no iteration-after-halt for an after-fire to
+        // attach to. Reject any truthy assignment (true OR list) at write time
+        // so misuse surfaces immediately rather than silently no-op'ing.
+        if (this.isHalt && fieldName === 'after') {
+            throw new Error('haltState.debug.after is not supported: halt is terminal, so there is '
+                + 'no iteration-after-halt for an after-fire to anchor on. Use '
+                + '{ before: true } to pause on halt entry.');
+        }
+        if (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.
+        // haltState has no own transitions; symbol-list filters on `before` are
+        // silent no-ops at the engine level (spec §8.6), so accept any list shape.
         if (this.isHalt)
             return;
         for (const sym of filter) {
@@ -1033,22 +1058,21 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    async run({ initialState, stepsLimit = 1e5, onStep, onDebugBreak, }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onPause, debug = true, }) {
         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 } });
+            // Per-iter lifecycle: before → step → after. All three operate on the
+            // same yielded MachineState, so the consumer sees a coherent ordering
+            // within each iteration without cross-tick coordination.
+            if (debug && machineState.debugBreak?.before && onPause) {
+                await onPause({ ...machineState, debugBreak: { before: true } });
             }
             if (onStep instanceof Function) {
                 onStep(machineState);
             }
-            prevYield = machineState;
+            if (debug && machineState.debugBreak?.after && onPause) {
+                await onPause({ ...machineState, debugBreak: { after: true } });
+            }
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {
@@ -1062,7 +1086,6 @@ class TuringMachine {
                 stack.push(state.overrodeHaltState);
             }
             let i = 0;
-            let pendingAfterFromPrev = false;
             while (!state.isHalt) {
                 if (i === stepsLimit) {
                     throw new Error('Long execution');
@@ -1072,8 +1095,12 @@ class TuringMachine {
                 const command = state.getCommand(symbol);
                 let nextState = state.getNextState(symbol).ref;
                 try {
+                    // Both before and after refer to THIS iter (#119 / v6.0.0).
+                    // The halting iter's after-fire just rides along on the iter's
+                    // own yield — no post-loop drain needed.
                     const beforeMatch = matchFilter(state.debug?.before, symbol)
                         || (nextState.isHalt && nextState.debug?.before === true);
+                    const afterMatch = matchFilter(state.debug?.after, symbol);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
@@ -1097,17 +1124,15 @@ class TuringMachine {
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
                     };
-                    if (pendingAfterFromPrev || beforeMatch) {
+                    if (beforeMatch || afterMatch) {
                         const dbg = {};
-                        if (pendingAfterFromPrev)
-                            dbg.after = true;
                         if (beforeMatch)
                             dbg.before = true;
+                        if (afterMatch)
+                            dbg.after = 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();

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
   },
-  "author": "Ruslan Gilmullin <mellonis14@gmain.com>",
+  "author": "Ruslan Gilmullin <mellonis@yandex.ru>",
   "homepage": "https://github.com/mellonis/turing-machine-js#readme",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -34,5 +34,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "6c7b2ac3055470b56c6882471767c746f5a9d7fb"
+  "gitHead": "5a3e3ced5bacd541fefdf087f5b4301267be01d2"
 }