@turing-machine-js/machine 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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

package/README.md

@@ -256,13 +256,13 @@ 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 `onDebugBreak` hook:
+`run()` is async and accepts an `onPause` hook:
 
 ```ts
 await machine.run({
   initialState,
   onStep: (m) => { /* logger sees every step */ },
-  onDebugBreak: async (m) => {
+  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);
@@ -272,7 +272,7 @@ await machine.run({
 
 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 `onDebugBreak` is not provided, breaks fire-and-resume invisibly — the trajectory is identical to running without `debug` set.
+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).
 

package/dist/classes/TuringMachine.d.ts

@@ -31,10 +31,24 @@ export default class TuringMachine {
         tapeBlock?: TapeBlock;
     });
     get tapeBlock(): TapeBlock;
-    run({ initialState, stepsLimit, onStep, onDebugBreak, }: 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;
-        onDebugBreak?: (machineState: MachineState) => void | Promise<void>;
+        /**
+         * 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>;
+    runStepByStep({ initialState, stepsLimit }: RunParameter): Generator<MachineState, MachineState | null>;
 }
 export {};

package/package.json

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