@turing-machine-js/machine 6.3.0 → 6.4.0

package/CHANGELOG.md

@@ -4,6 +4,96 @@ 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).
 
+## [6.4.0] - 2026-05-19
+
+Adds a new awaited hook on `TuringMachine.run`. Minor release, additive — no breaking changes. Closes [#163](https://github.com/mellonis/turing-machine-js/issues/163).
+
+### Added
+
+- **`onIter` callback** on `run()`: `onIter?: (m: MachineState) => void | Promise<void>`. Fires once per iteration at end-of-iter — *after* both `onPause(before, K)` and `onPause(after, K)` dispatches on the same yield. Awaited inline, so consumers returning a Promise suspend the run loop between iters. Unaffected by the `debug` master switch — `onIter` fires on every iter regardless of whether any `state.debug` breakpoints are armed.
+
+  Use cases the hook serves:
+  - **Per-iter throttle** (interactive debugger / animation UIs) — `await new Promise(r => setTimeout(r, intervalMs))` inside the callback gives a "wait between iters" pattern with no `state.debug` mutation.
+  - **Iter-correct bookkeeping** — for downstream libraries that maintain per-iter prev state (e.g. PostMachine's `arrivalPath` tracking), `onIter` is the natural "iter K is done" boundary, after all `onPause` hooks have read their own snapshots. Avoids the prev-advance-during-onStep ordering hazard.
+  - **Yield-to-other-work in batched runs** — a sync `await new Promise(r => queueMicrotask(r))` per iter lets long runs interleave with other event-loop work without owning the run loop.
+
+### Three-hook contract recap
+
+| Hook | Sync/Async | When | Use |
+|---|---|---|---|
+| `onStep` | Sync, not awaited | Mid-iter (between before/after) | Cheap tracer/logger, microtask-free hot loop |
+| `onPause` | Awaited | Conditional on `state.debug[when]` match | User-authored breakpoints / debugger UI |
+| `onIter` | Awaited | End of every iter | Per-iter coordination — throttle, prev-tracking, animation, yield-to-other-work |
+
+### Changed (docs)
+
+- README's **Throttle pattern** section rewritten to recommend `onIter` as the canonical hook. The v6.3.0 `onPause`-rearm workaround is superseded — that pattern still works (it's just the engine-native primitives), but `onIter` is the cleaner shape.
+
+### Compatibility
+
+- Default `onIter` is `undefined` → no behavior change for any existing consumer that doesn't opt in.
+- Sync consumers using only `onStep` pay zero microtask overhead — `onIter` is purely opt-in.
+- Peer-deps unchanged (`^6.0.0` includes 6.4.0 for the dependents).
+
+## [6.3.0] - 2026-05-19
+
+Corrective minor release. **Reverts v6.2.0's `await onStep` change** and restores the original sync `onStep` contract that held since the hook was introduced. See [GitHub release](https://github.com/mellonis/turing-machine-js/releases/tag/v6.3.0) for the full post-mortem.
+
+### Changed
+
+- **`TuringMachine.run`** — `await onStep(m)` reverted to `onStep(m)`; type narrowed back from `(m: MachineState) => void | Promise<void>` to `(m: MachineState) => void`. The original "Sync, ~free hook ... must not be async" contract is restored, with the docstring augmented to point readers at the new Throttle pattern section.
+
+### Removed
+
+- The v6.2.0 test `async onStep is awaited between iters (#158)` (no longer the contract).
+
+### Added (docs)
+
+- README: new **Throttle pattern** section under *Debugging breakpoints* showing the engine-native shape for per-iter throttle / "wait between iters" UIs — arm `state.debug.after = true` on the initial state, throttle inside `onPause`, rearm `m.nextState.debug.after = true` in the callback. Replaces the v6.2.0 throttle-in-`onStep` pattern.
+
+### Kept from v6.2.0 (independent improvements)
+
+- CI `typecheck` step + dependent packages' `tsconfig` `paths`/`rootDir` fix.
+
+### Migration
+
+- From v6.2.0: drop any `await` you wrote inside `onStep`. The engine ignores the returned Promise now. If you used the throttle-in-`onStep` pattern, migrate to the Throttle pattern section in the README.
+- From v6.1.0 or earlier: no change for you.
+
+## [6.2.0] - 2026-05-19 [SUPERSEDED by 6.3.0]
+
+> ⚠️ **This release was a mistake.** It overturned the sync `onStep` contract that had held since the hook was introduced, motivated by a downstream throttle use case that didn't actually need an engine API change. Restored to sync in [6.3.0](#630---2026-05-19). The `await onStep` semantic shipped briefly on npm; consumers should upgrade to 6.3.0 and use the README's Throttle pattern instead.
+
+### Changed
+
+- **`TuringMachine.run`** — `onStep` type widened from `(m) => void` to `(m) => void | Promise<void>`; the run loop now awaits each `onStep(m)` call.
+
+### Internal
+
+- CI `typecheck` step added (mirrors the spec-including tsconfig to catch TS errors in `*.spec.ts`).
+- Dependent packages' `tsconfig` `paths` and `rootDir` corrected — they now resolve `@turing-machine-js/machine` from source in CI (previously required a pre-built `dist/`).
+
+## [6.1.0] - 2026-05-16
+
+Minor release. One additive ergonomic improvement to `state.debug`, no breaking changes.
+
+### Added
+
+- **Lazy-init `DebugConfig` + `Object.seal` on instance ([#151](https://github.com/mellonis/turing-machine-js/pull/151), closes [#150](https://github.com/mellonis/turing-machine-js/issues/150)).** `state.debug` is now always a non-null `DebugConfig` instance, lazy-initialized on first read. Chained writes like `state.debug.before = true` work on a fresh state without a prior `state.debug = {}` setup step. The `DebugConfig` instance is `Object.seal`-ed — typos like `state.debug.bofore = true` throw `TypeError` (in strict mode — default for TS-emitted modules) instead of silently creating a useless own property.
+
+### Changed
+
+- **`state.debug` getter type narrowed** — `DebugConfig | null` → `DebugConfig`. Setter still accepts `null`; the semantic shifts to "reset filters" (next read returns a fresh empty config rather than literal `null`).
+- **Wrapper sharing preserved** — `withOverrodeHaltState`'s `#debugRef` cell continues to share a single `DebugConfig` instance across wrapper and original; first read on either lazy-creates, both subsequent reads return the same instance.
+
+### Migration
+
+No code changes required:
+- `state.debug?.X` patterns keep working (the `?.` is now redundant but correct).
+- `state.debug = { ... }` whole-object assignment works as before.
+- `state.debug = null` works as before, with the new "reset filters" semantic.
+- Consumer code checking `if (state.debug === null)` becomes dead code but doesn't crash; the narrowed getter type may surface TS warnings on those branches, safe to delete.
+
 ## [6.0.0] - 2026-05-09
 
 ### Changed (BREAKING)

package/README.md

@@ -516,36 +516,29 @@ If `onPause` is not provided, breaks fire-and-resume invisibly — the trajector
 
 **Caveat:** `haltState` is a module-level singleton. Setting `haltState.debug` affects every machine in the process; clear in `afterEach` / `finally` for test isolation.
 
-### Throttle pattern
+### Throttle pattern (v6.4.0+)
 
-For per-iter throttle / animation / "wait between steps" UIs, do the await inside `onPause`, not `onStep` — `onPause` is the engine's awaited callback. To make it fire on every iter (no user-set breakpoints needed), arm `.after = true` on the initial state and rearm `m.nextState.debug.after = true` inside the callback. The chain is self-propagating:
+For per-iter throttle / animation / "wait between steps" UIs, use the **`onIter`** hook — an awaited callback that fires once at the end of every iter, after both `onPause` dispatches on the same yield. It's the engine-native shape for per-iter coordination:
 
 ```ts
-initialState.debug.after = true; // first pause-point
-
 await machine.run({
   initialState,
-  debug: true,
-  onPause: async (m) => {
-    // m.debugBreak.after is true here on every iter.
-    await new Promise((r) => setTimeout(r, intervalMs)); // throttle
-
-    // Rearm for the next iter (engine processes m.nextState next).
-    // `state.debug` is shared across `withOverrodeHaltState` wrappers — a
-    // single arm reaches all of them.
-    if (!m.nextState.isHalt) m.nextState.debug.after = true;
+  onIter: async (m) => {
+    // Fires after before(m.state) / step / after(m.state) on iter m.step.
+    await new Promise((r) => setTimeout(r, intervalMs));
   },
 });
 ```
 
+`onIter` is unaffected by the `debug` master switch and unrelated to `state.debug` — it fires on every iter regardless of whether any breakpoints are armed. It coexists cleanly with user-authored `state.debug` breakpoints: on an iter with both `.before` and `.after` armed, the consumer sees `onPause(before)` → `onStep` → `onPause(after)` → `onIter`, in that order, on the same yield.
+
 A few details:
 
-- **Halting iter**: `m.nextState === haltState` on the last user iter. The example skips the rearm there. The halting iter's own `.after` already fired this callback (engine v5+ fixed [#108](https://github.com/mellonis/turing-machine-js/issues/108) part 1).
-- **`haltState.debug.after`**: throws on assignment (#108 part 2). Don't try to rearm onto haltState itself — pause for halt by checking `m.nextState.isHalt` in the callback before the rearm step.
-- **Coexists with user-authored breaks**: if a user state also has `.before = true` set by the consumer's own code, `onPause` fires twice on that iter (before + after). Tell them apart with `m.debugBreak`.
-- **Click-pause** during throttling: keep a flag set from the outside; check it inside `onPause` before the `setTimeout` and surface a "real" pause (await a resolvable Promise the UI controls) instead of the throttle one. The engine doesn't need to know — it just sees a longer awaited `onPause`.
+- **Halting iter**: `onIter` still fires on the iter whose `m.nextState === haltState`, after any halt-time `onPause` dispatches. Engine returns cleanly after that. Use this to land "halted" UI state in interactive consumers.
+- **Click-pause / external interruption**: keep a flag set from the outside; check it inside `onIter` and `await` a resolvable Promise the UI controls (instead of the bare `setTimeout`). The engine just sees a longer awaited `onIter` — no engine surface needed for the pause.
+- **Sync consumers should keep using `onStep`**: it's microtask-free; `onIter` adds one awaited boundary per iter. Use the right hook for the right verb (logging/tracing → `onStep`, throttle/coordination → `onIter`, user breakpoints → `onPause`).
 
-(v6.2.0 briefly widened `onStep` to async to enable a throttle-in-onStep pattern. That was a mistake — restored to sync in v6.3.0. The rearm-via-`onPause` pattern above is the engine-native shape.)
+(History: v6.2.0 briefly widened `onStep` to `void | Promise<void>` and added an inline `await`, motivated by this same throttle use case. That was a mistake — restored to sync in v6.3.0. v6.3.0 documented a workaround using `onPause` self-rearm on `state.debug.after = true`; that workaround is superseded by `onIter` in v6.4.0+.)
 
 ## Special objects
 
@@ -623,6 +616,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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).
 - **v6.2** *(superseded by v6.3.0)* — widened `onStep`'s signature to `(m) => void | Promise<void>` and added an inline `await onStep(...)` in the run loop, enabling throttle-in-`onStep` patterns. This overturned the docstring-stated contract that `onStep` is sync (microtask-free); the right place for per-iter throttling is `onPause` with self-rearm (see [Throttle pattern](#throttle-pattern)). Restored in v6.3.0.
 - **v6.3** — `onStep` reverted to its v6.0–v6.1 sync contract — `(m) => void`, called synchronously inside the run loop. The Throttle pattern section documents the engine-native shape for per-iter throttle / "wait between iters" UIs. No other API changes.
+- **v6.4** — New **`onIter`** hook on `run()`: awaited, fires once at the end of every iter (after both `onPause` dispatches on the same yield), unaffected by the `debug` master switch. Use for per-iter throttle / animation / coordination needing a suspend point; complements the existing sync `onStep` (tracing) and conditional `onPause` (user breakpoints). Three-hook contract is now `onStep` (sync, mid-iter) / `onPause` (awaited, on `state.debug` match) / `onIter` (awaited, end-of-iter). Additive — peer-deps unchanged. The v6.3.0 README's `onPause`-rearm throttle workaround is superseded.
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 

package/dist/classes/TuringMachine.d.ts

@@ -33,22 +33,14 @@ export default class TuringMachine {
         tapeBlock?: TapeBlock;
     });
     get tapeBlock(): TapeBlock;
-    run({ initialState, stepsLimit, onStep, onPause, debug, }: RunParameter & {
+    run({ initialState, stepsLimit, onStep, onPause, onIter, debug, }: 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.
          *
          * For per-iter throttle / coordination ("wait between iters" UIs):
-         * arm `state.debug.after = true` on each visited state and do the
-         * throttle inside `onPause` (which IS awaited). See the README's
-         * Throttle pattern section for a worked example.
-         *
-         * (v6.2.0 widened this to `void | Promise<void>` and added an inline
-         * `await`. That was a mistake — it drove the awaited contract into a
-         * hook that was deliberately documented as sync. Restored in v6.3.0;
-         * consumers needing per-iter await belong on the `onPause`-rearm
-         * pattern, not this hook.)
+         * use `onIter` (v6.4.0+, awaited at end-of-iter).
          */
         onStep?: (machineState: MachineState) => void;
         /**
@@ -65,6 +57,25 @@ export default class TuringMachine {
          * engine's reason for pausing).
          */
         onPause?: (machineState: MachineState) => void | Promise<void>;
+        /**
+         * Awaited hook fired ONCE at the end of every iteration (v6.4.0+), AFTER
+         * any `onPause(after, K)` dispatch on the same yield. Use for per-iter
+         * coordination that needs to suspend the run loop — throttling between
+         * iters (interactive debugger UIs), prev-state bookkeeping that must
+         * observe iter K's final state once all `onPause` hooks have read their
+         * own snapshots, yield-to-other-work in batched runs.
+         *
+         * Three-hook contract recap:
+         * - `onStep`: sync, microtask-free — tracing/logging during the iter
+         * - `onPause`: awaited, conditional on `state.debug[when]` match — user
+         *   breakpoints with iter-correct payload
+         * - `onIter`: awaited, unconditional — once per iter, at end-of-iter
+         *
+         * `onIter` is unaffected by the `debug` master switch — it fires on
+         * every iter regardless. Sync consumers should prefer `onStep` to avoid
+         * the per-iter microtask boundary `onIter` carries.
+         */
+        onIter?: (machineState: MachineState) => void | Promise<void>;
         /**
          * Master switch for `onPause` dispatch. When `false`, suppresses all
          * pause-fires (before and after) regardless of `state.debug` assignments.

package/dist/index.cjs

@@ -1060,7 +1060,7 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    async run({ initialState, stepsLimit = 1e5, onStep, onPause, debug = true, }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onPause, onIter, debug = true, }) {
         const generator = this.runStepByStep({ initialState, stepsLimit });
         for (const machineState of generator) {
             // Per-iter lifecycle: before → step → after. All three operate on the
@@ -1069,12 +1069,15 @@ class TuringMachine {
             if (debug && machineState.debugBreak?.before && onPause) {
                 await onPause({ ...machineState, debugBreak: { before: true } });
             }
-            if (onStep instanceof Function) {
+            if (onStep) {
                 onStep(machineState);
             }
             if (debug && machineState.debugBreak?.after && onPause) {
                 await onPause({ ...machineState, debugBreak: { after: true } });
             }
+            if (onIter) {
+                await onIter(machineState);
+            }
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {

package/dist/index.mjs

@@ -1058,7 +1058,7 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    async run({ initialState, stepsLimit = 1e5, onStep, onPause, debug = true, }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onPause, onIter, debug = true, }) {
         const generator = this.runStepByStep({ initialState, stepsLimit });
         for (const machineState of generator) {
             // Per-iter lifecycle: before → step → after. All three operate on the
@@ -1067,12 +1067,15 @@ class TuringMachine {
             if (debug && machineState.debugBreak?.before && onPause) {
                 await onPause({ ...machineState, debugBreak: { before: true } });
             }
-            if (onStep instanceof Function) {
+            if (onStep) {
                 onStep(machineState);
             }
             if (debug && machineState.debugBreak?.after && onPause) {
                 await onPause({ ...machineState, debugBreak: { after: true } });
             }
+            if (onIter) {
+                await onIter(machineState);
+            }
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
@@ -38,5 +38,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "6be43b1e88c4c562c9c11b495b285ff114f86b37"
+  "gitHead": "a8228b8a5f7f9acd1f6219af80db86368848cdbc"
 }