@turing-machine-js/machine 6.0.1 → 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
 
@@ -82,7 +100,7 @@ Engine notation: `read → write/move`; `·` = keep, `⌫` = erase, `*` = `ifOth
 
 </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. `ifOtherSymbol` is the fallback key when nothing else matches; transitioning into `haltState` stops the run.
+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'`.
 
@@ -309,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):
@@ -332,6 +350,22 @@ Each yielded `step` (`MachineState`) has these fields:
 
 `stepsLimit` (default `1e5`) guards against runaway loops — exceeding it throws.
 
+#### 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.
@@ -430,34 +464,35 @@ flowchart TD
 
 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 (v4+)
+## 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;
 ```
 
 > ⚠️ **`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. Plain-object input (`state.debug = { before: true }`) is wrapped in a `DebugConfig` instance automatically; the wrapper's per-property setters validate and freeze the stored array, so `state.debug.before.push(...)` throws `TypeError`.
+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:
 
@@ -547,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
@@ -554,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) {

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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
@@ -34,5 +34,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "d7ebca4e8379a548e3ca97eb83e96387de2cda32"
+  "gitHead": "5a3e3ced5bacd541fefdf087f5b4301267be01d2"
 }