@turing-machine-js/machine 7.0.0-alpha.4 → 7.0.0-alpha.6

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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).
 
+## [7.0.0-alpha.6] - 2026-05-28
+
+Sixth v7 pre-release. Lands the debugger step controls ([#102](https://github.com/mellonis/turing-machine-js/issues/102), [PR #214](https://github.com/mellonis/turing-machine-js/pull/214)) and, in doing so, **reshapes the entire debug surface** into three clearly-separated entry points: `run()` is now pure synchronous execution (no callbacks), `runStepByStep` is the minimal pure-iteration primitive (no breakpoint detection), and a new **`DebugSession`** class owns all interactive debugging — events, step controls, throttle, and pause coordination. With #102 the **v7 milestone is feature-complete**; the stable v7.0.0 cut is the only remaining step. Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.
+
+**Pre-release — the API surface may still shift before stable v7.0.0.** Pin to a specific alpha for reproducibility: `@turing-machine-js/machine@7.0.0-alpha.6`.
+
+### Added
+
+- **`DebugSession`** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — `new DebugSession(machine, { initialState })`. The sole interactive-debugging surface (there is no `debugRun()` factory on `TuringMachine`). Emits `pause` / `step` / `iter` / `halt` events via `session.on(event, listener)`; `iter` listeners are **awaited** (the per-iter throttle / coordination point), `pause` / `step` / `halt` are fire-and-forget. Drive controls: `continue()`, `stepIn()`, `stepOver()`, `stepOut()`, external `pause()`, `stop()`, and `setRunInterval(ms)` for a per-iter throttle. Breakpoint detection (`state.debug` filters, `haltState.debug`) lives entirely here — `runStepByStep` no longer evaluates it. Concurrent sessions on one machine are rejected with a clear error (the underlying `TapeBlock` lock is single-active-run).
+
+- **`PauseInfo` / `PausedMachineState`** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — the `pause` event payload is a `MachineState & { pause: PauseInfo }` where `PauseInfo = { side: 'before' | 'after'; cause: 'breakpoint' | 'step' | 'manual' }`. Exactly one side per descriptor — `DebugSession` dispatches the two timings as separate `pause` events, so the v6 "both timings on one yield" shape no longer exists. `cause` precedence when an iter satisfies more than one trigger: `breakpoint > step > manual`; `'step'` / `'manual'` only ever fire on the `'before'` side.
+
+- **Depth-based step controls mirroring Chrome DevTools** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — `stepIn` = next iter at any depth; `stepOver` = next iter at `depth ≤ click-time depth` (nested `.withOverriddenHaltState(...)` subroutines run to completion, pause back at the starting level); `stepOut` = next iter at `depth < click-time depth` (current subroutine frame popped; throws at depth 0, mirroring DevTools' top-frame Step Out).
+
+- **`matchFilter` export** ([#102](https://github.com/mellonis/turing-machine-js/issues/102), `@internal`) — predicate evaluating a `DebugConfig` side-filter against a matched symbol. Exported for sibling-module use in `DebugSession`; NOT re-exported from the package root.
+
+### Changed
+
+- **`run()` is synchronous and callback-free** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — signature is now `run({ initialState, stepsLimit? }): void` (was `async … : Promise<void>` with `onPause` / `onStep` / `onIter` callbacks). Pure execution, no debug overhead. Reverses v4's `run` → `async run` change now that all callback machinery has moved to `DebugSession`. **Breaking** for callers awaiting `run()` or passing callbacks — construct a `DebugSession` instead.
+
+- **`runStepByStep` is the minimal pure-iteration primitive** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — it advances the machine and yields a plain `MachineState`; it evaluates no `state.debug` filters and stamps no pause field. All breakpoint detection moved to `DebugSession`. **Breaking** for consumers that read a pause / breakpoint field off raw yields.
+
+- **`haltState.debug` pause is delivered via `DebugSession`** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — still fires on the AFTER side of the halt-triggering iter (alpha.5 semantics: `m.state` is the triggering state, not `haltState`), but now arrives as a `pause` event with `{ side: 'after', cause: 'breakpoint' }` instead of a `debugBreak` field on the yield.
+
+### Removed
+
+- **`MachineState.debugBreak`** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — the per-yield `{ before?, after?, cause }` descriptor from the v4–alpha.5 debugger is **removed**. Its replacement is the one-sided `m.pause: { side, cause }` carried ONLY on a `DebugSession` `pause` event (`PausedMachineState`); raw `runStepByStep` yields carry no pause field. **Breaking from alpha.5** — consumers reading `m.debugBreak.before` / `.after` / `.cause` must move to a `DebugSession` and read `m.pause.side` / `m.pause.cause`.
+
+## [7.0.0-alpha.5] - 2026-05-25
+
+Fifth v7 pre-release. Adds per-iter `matchedTransition` to `MachineState` so consumers can resolve the firing transition by graph id without re-deriving from `(source, nextState)` ambiguous pairs ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` and moves the halt-imminent pause to the AFTER side of the halt-triggering iter so the wording + diagram cursor agree with the just-fired transition ([#207](https://github.com/mellonis/turing-machine-js/issues/207)), and renames the `GraphTransition.id` separator from `-` to `.` for parser-friendly splitting. Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.
+
+**Pre-release — the API surface may still shift before stable v7.0.0.** Pin to a specific alpha for reproducibility: `@turing-machine-js/machine@7.0.0-alpha.5`.
+
+### Added
+
+- **`MachineState.matchedTransition`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)) — every yielded `MachineState` from `run` / `runStepByStep` now carries `{ id: string, matchKinds: ('wildcard' | 'literal')[] }`. `id` is `${stateId}.${transitionIx}` and resolves directly in `toGraph`'s output via `graph.nodes[stateId].transitions.find(t => t.id === ...)`. For wrapper-entry iters, `id` references the BARE's transition (wrappers delegate via `bareState`). `matchKinds` is per-tape, length = tape count; `'wildcard'` iff the winning alternative held `ifOtherSymbol` at that position. Eliminates `(source, nextState)` resolution ambiguity for tools doing exact-edge highlighting, per-transition coverage maps, or wildcard-aware log formatting.
+
+- **`State.getMatchedTransition(symbol)`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)) — public method returning `{ nextState, matchedSymbol, ix }` for the symbol's transition. Same lookup `getNextState` does, plus the index — exposes the K used by `MachineState.matchedTransition.id` so callers needing both don't pay for the lookup twice.
+
+- **`TapeBlock.patternKinds(symbol, currentSymbols?)`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)) — public method returning per-tape `'wildcard' | 'literal'` for the matched alternative's selector. The engine uses it internally to populate `matchedTransition.matchKinds`; exposed for consumers wiring custom dispatch.
+
+- **`HaltState` typed alias** ([#207](https://github.com/mellonis/turing-machine-js/issues/207)) — the exported `haltState` singleton now carries a narrower TypeScript type (`State & { debug: boolean; ... }`) so `haltState.debug = true` is type-safe at the call site. Generic `State` references still see `DebugConfig` — runtime branches on `this.isHalt`.
+
+### Changed
+
+- **`GraphTransition.id` separator: `-` → `.`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)). Was `${stateId}-${patternIx}`, now `${stateId}.${patternIx}`. Aligns with `matchedTransition.id` and makes the id splittable without colliding with user-defined state names that may contain `-`. **Breaking** for any consumer parsing the old separator; alpha-channel only.
+
+- **`haltState.debug` is `boolean`** ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). Was `DebugConfig` with per-side `{ before?, after? }` filters; under v7 it's a single `boolean` flag. `haltState.debug = true` enables; `false` / `null` disables. **Object-shaped writes throw** (`{ before: true }`, `{ after: true }`, etc.). The pause fires on the AFTER side of the iter whose transition leads to halt — `m.state` is the triggering state (not haltState), `m.debugBreak.after === true`. Diagram + log narratives read naturally: the halt-bound transition has fired when the pause lands, and halt is the next thing. **Breaking** — pre-alpha.5 consumers using `haltState.debug = { before: true }` must switch to `haltState.debug = true`.
+
+  ⚠️ **Chained-form `haltState.debug.before = true` silently no-ops in non-strict mode.** The getter returns the boolean; assigning `.before` to a primitive is a JS no-op outside strict mode (`TypeError` in strict). The engine setter never sees the write. Use the whole-object form (`haltState.debug = true` / `= false` / `= null`).
+
+- **`State` internal: single `#getEntry` helper for `getCommand` / `getNextState` / `getMatchedTransition`** ([#206](https://github.com/mellonis/turing-machine-js/pull/206)). Internal refactor — no public API change. All three accessors now share one `.get()` lookup + unified throw message (`"No transition for symbol at state named ..."` — was per-method messages).
+
+- **Internal: dead-code typeof check on `state.debug` in `runStepByStep` removed; `patternKinds` defensive paths now have dedicated test coverage** ([#210](https://github.com/mellonis/turing-machine-js/pull/210)). Engine-internal cleanup that bumps overall coverage to 99.35% statements / 96.58% branches / 100% functions / 99.48% lines.
+
+### Docs
+
+- ⚠️ **README + CLAUDE.md** ([#209](https://github.com/mellonis/turing-machine-js/pull/209)) — warn that chained-form `haltState.debug.before = true` silently no-ops in non-strict mode (`new Function(...)`, `<script>` without `"use strict"`). Engine can't intercept (the write happens on a primitive after the getter returned); doc steers users to the whole-object form.
+
 ## [7.0.0-alpha.4] - 2026-05-23
 
 Fourth v7 pre-release. Adds an id-keyed lookup helper for the State graph ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), fixes two upstream issues surfaced while wiring the new helper into downstream tooling — a `toMermaid` label-grammar bug ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and a halt-stack lifetime bug in `runStepByStep` ([#196](https://github.com/mellonis/turing-machine-js/issues/196)) — and extracts graph serialization into its own module without API change ([#180](https://github.com/mellonis/turing-machine-js/issues/180)). Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.

package/README.md

@@ -307,13 +307,16 @@ The runtime. Owns one `TapeBlock` and drives a state graph until it reaches `hal
 ```javascript
 const machine = new TuringMachine({ tapeBlock });
 
-// Run to halt — `run()` returns a Promise<void>:
-await machine.run({ initialState, stepsLimit: 1e5 });
+// Run to halt — `run()` is synchronous, returns void:
+machine.run({ initialState, stepsLimit: 1e5 });
 
-// Or step-by-step (useful for visualization / debugging):
+// Or step-by-step (useful for tracing / observation):
 for (const step of machine.runStepByStep({ initialState })) {
   console.log(step.state.name, step.currentSymbols, '→', step.nextSymbols, step.movements);
 }
+
+// For interactive debugging (breakpoints, step-in / step-over / step-out,
+// throttle, click-pause), construct a DebugSession — see "Debugging" below.
 ```
 
 Each yielded `step` (`MachineState`) has these fields:
@@ -326,25 +329,52 @@ Each yielded `step` (`MachineState`) has these fields:
 | `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 |
+| `matchedTransition` | `{ id: string, matchKinds: ('wildcard'\|'literal')[] }` | the transition the engine picked for this iter — see *Matched transition* below |
 
 `stepsLimit` (default `1e5`) guards against runaway loops — exceeding it throws.
 
-#### Choosing between `run()` and `runStepByStep()`
+#### Choosing between `run()`, `runStepByStep()`, and `DebugSession`
 
-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:
+Three non-overlapping entry points, picked by the consumer's actual need:
 
-| | `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 |
+| | `run()` | `runStepByStep()` | `new DebugSession(machine, ...)` |
+|---|---|---|---|
+| Shape | sync, returns `void` | sync generator | async session with events |
+| Observation | none | per-iter via `.next()` | event-based (`pause`, `step`, `iter`, `halt`) |
+| Step controls | — | — | `continue / stepIn / stepOver / stepOut / pause / stop` |
+| Throttle | — | — | `setRunInterval(ms)` |
+| Breakpoint handling | not consulted — runs straight to halt | not consulted — yields every iter; `state.debug` is ignored | the only mode that *reacts* — fires a `pause` event |
+| Best for | run-to-halt with no observation overhead | tracing, snapshots, test harnesses, custom batching | UI debuggers, IDE extensions, educational demos |
+
+**Rule of thumb.** No observation → `run()`. Sync per-iter observation → iterate `runStepByStep()`. Anything interactive (breakpoints, step controls, throttle, click-pause) → construct a `DebugSession`.
+
+**Breakpoint detection lives only in `DebugSession`.** `runStepByStep` is the pure-iteration primitive — it advances the machine and reports a minimal `MachineState` with no pause/debug field, ignoring `state.debug` entirely. `DebugSession` is what evaluates the filters and turns a match into a `pause` event. (A consumer that wants its own breakpoint behavior on the raw generator can read `state.debug` itself.)
+
+### Matched transition
+
+Every yielded `MachineState` carries a `matchedTransition` describing which transition the engine picked for that iter. The engine already resolves this via `state.getNextState(symbol)` internally; this field exposes the resolution to consumers so visualizations, log formatters, and coverage maps don't have to re-derive an ambiguous `(source, nextState)` pair (which collides when multiple transitions on the same source share a destination) or parse pattern strings from `toGraph`.
+
+```ts
+matchedTransition: {
+  id: string;                               // resolvable in toGraph
+  matchKinds: ('wildcard' | 'literal')[];   // per-tape, length = tape count
+}
+```
+
+- **`id`** — `${stateId}.${transitionIx}`. Resolvable in `toGraph`'s output: `graph.nodes[stateId].transitions` has an entry with the matching `id`. For wrapper-entry iters (source is a wrapper produced by `withOverriddenHaltState`), `id` references the **bare's** transition — the wrapper's own `transitions` array in `toGraph` is empty because wrappers delegate, and the pattern actually lives on the bare. Detect by comparing `id.split('.')[0]` against `state.id`: different → wrapper delegation.
+
+- **`matchKinds`** — per-tape match kind for the matched alternative's selector at each tape position. `'wildcard'` if the position held `ifOtherSymbol` (catch-all) in the winning alternative; `'literal'` if it held a specific symbol or symbol-list. Length always equals tape count.
 
-**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.
+Example use:
 
-**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. 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. For per-iter throttle / "wait between steps" UIs, see [Throttle pattern](#throttle-pattern).
+```javascript
+for (const m of machine.runStepByStep({initialState})) {
+  const wildcardPositions = m.matchedTransition.matchKinds  // per-tape, e.g. ['wildcard', 'literal']
+    .map((k, i) => k === 'wildcard' ? i : -1)
+    .filter((i) => i >= 0);
+  console.log(`step ${m.step}: fired transition ${m.matchedTransition.id} (wildcards at tapes: ${wildcardPositions.join(',') || 'none'})`);
+}
+```
 
 ## Subroutine composition with `withOverriddenHaltState`
 
@@ -448,9 +478,29 @@ s.tags; // readonly ['subroutine-entry']
 
 See [§Diagram conventions § Tags](#tags) for the full emit shape.
 
-## Debugging breakpoints
+## Debugging
+
+The library exposes interactive debugging through the `DebugSession` class, constructed directly with a `TuringMachine`. Breakpoints are configured on the engine (`state.debug` / `haltState.debug`); the session dispatches them as events plus offers step-in / step-over / step-out controls, an external `pause()`, and a per-iter throttle.
 
-Any `State` can carry a runtime-mutable `debug` config that pauses execution at chosen points.
+```ts
+import { DebugSession } from '@turing-machine-js/machine';
+
+const session = new DebugSession(machine, { initialState });
+
+session.on('pause', (m) => {
+  console.log(`paused at ${m.state.name}, ${m.pause.side} side, cause: ${m.pause.cause}`);
+  session.stepIn();              // or stepOver(), stepOut(), continue(), stop()
+});
+session.on('step', (m) => { /* fires once per iter, mid-iter */ });
+session.on('iter', (m) => { /* fires once per iter, end-of-iter */ });
+session.on('halt', () => { /* fires on natural halt (not on stop()) */ });
+
+await session.start();           // resolves on halt or stop()
+```
+
+### Configuring breakpoints
+
+Breakpoints live on the engine, not on the session. The session reads `state.debug` / `haltState.debug` and fires a `pause` event when a filter matches.
 
 ```ts
 import { State, haltState, ifOtherSymbol } from '@turing-machine-js/machine';
@@ -467,38 +517,73 @@ myState.debug = { before: true };
 myState.debug = { before: [symA] };
 myState.debug = { before: [symA], after: [symA] };
 
-// Pause when the engine is about to enter halt (program exit OR subroutine pop):
-haltState.debug = { before: true };
+// Pause when the engine is about to enter halt (program exit OR subroutine pop).
+// haltState.debug is a `boolean` (#207) — halt is terminal, so there's only
+// one meaningful pause moment (post-triggering-iter, before halt processing).
+haltState.debug = true;
+haltState.debug = false;        // turn off
+haltState.debug = null;         // alias of false (reset)
 
-// Reset filters later — next read returns a fresh empty DebugConfig:
+// Reset filters later on a regular state — 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.
+> ⚠️ **`haltState.debug` is `boolean`-only.** Any object-shaped write (`{ before: true }`, `{ after: true }`, `{ before: true, after: true }`) throws at write time. The pause fires on the AFTER side of the iter whose transition leads to halt — `m.state` is the triggering state (not haltState), `m.pause.side === 'after'`.
 
-The `debug` field is mutable — toggle breakpoints at runtime without rebuilding the graph. The internal cell is shared with `state.withOverriddenHaltState(...)` 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`.
+> ⚠️ **Chained-form `haltState.debug.before = true` doesn't throw in non-strict mode** — this is a JavaScript primitive quirk, not engine behavior. The getter returns the boolean `false`; assigning `.before` to that boolean is a no-op in non-strict mode (silent), a `TypeError` in strict mode. The engine setter only sees whole-object writes (`haltState.debug = X`). **Always use the whole-object form: `haltState.debug = true` / `= false` / `= null`.**
 
-`run()` is async and accepts an `onPause` hook:
+The `debug` field is mutable — toggle breakpoints at runtime without rebuilding the graph. The internal cell is shared with `state.withOverriddenHaltState(...)` 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 is wrapped automatically. The instance is `Object.seal`-ed — typos like `state.debug.bofore = true` throw `TypeError` instead of silently creating a useless property.
 
-```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);
-  },
-});
-```
+**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.
 
-Both `before` and `after` for the same iteration fire on the iteration's own yield, in the order **before → step → after**. `m.state` is always the iteration's own state; the `m.debugBreak` flag (`{before: true}` or `{after: true}`) tells the consumer which timing fired.
+### DebugSession API
 
-If `onPause` is not provided, breaks fire-and-resume invisibly — the trajectory is identical to running without `debug` set.
+| Method | Description |
+|---|---|
+| `start(): Promise<void>` | Begin execution. Resolves on natural halt or after `stop()`. Single-use — a second call throws. |
+| `continue()` | Resume from a pause and run to the next breakpoint or halt. |
+| `stepIn()` | Resume and pause at the very next iter, regardless of depth — descends into any subroutine the current iter enters. Mirrors DevTools **Step Into**. |
+| `stepOver()` | Resume and pause at the next iter back at (or above) the click-time halt-stack depth (`depth ≤ clickTimeDepth`) — subroutines the stepped-over iter enters run to completion without pausing inside. Mirrors DevTools **Step Over**. |
+| `stepOut()` | Resume and pause at the next iter strictly shallower than the click-time depth (`depth < clickTimeDepth`) — i.e. once the current frame has been popped. Throws if the click-time depth is 0 (no enclosing frame to exit). Mirrors DevTools **Step Out**. |
+| `pause()` | Request a pause from outside the loop. Fires on the next iter with `cause: 'manual'`. If a breakpoint matches that same iter, the breakpoint wins (single pause, `cause: 'breakpoint'`). |
+| `stop()` | Terminate immediately. `halt` event does NOT fire. |
+| `setRunInterval(ms)` | Insert an awaited `setTimeout(ms)` at the end of each iter. `0` disables. Useful for visualization UIs. |
+| `on(event, listener) / off(event, listener)` | Register / unregister listeners. Multiple listeners per event are supported. Listener dispatch differs by event — see *Events* below. |
 
-**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).
+The three step controls are depth-based to mirror DevTools: from a pause at halt-stack depth `D`, `stepIn` pauses at the next iter (any depth), `stepOver` at the next iter with `depth ≤ D`, `stepOut` at the next iter with `depth < D`. For a *plain* iter (no subroutine entry) all of Into/Over coincide — they differ only under genuine nesting (a bare that itself enters a `withOverriddenHaltState` wrapper). One engine-specific nuance: composition is continuation-passing (`A.wohs(B)` = "run A, then B" — sequential, where `wohs` is `withOverriddenHaltState`), so a flat `.wohs()` chain has no real nesting and Over/Out behave the same there; the distinction appears only when a subroutine's body enters another wrapper.
 
-**Caveat:** `haltState` is a module-level singleton. Setting `haltState.debug` affects every machine in the process; clear in `afterEach` / `finally` for test isolation.
+### Events
+
+| Event | Argument | Dispatch | Fires |
+|---|---|---|---|
+| `pause` | `PausedMachineState` (`MachineState` + `pause: {side, cause}`) | Implicitly awaited via internal pause-promise — engine blocks until `continue / stepIn / stepOver / stepOut / stop` is called. Listener Promise itself is fire-and-forget. | A breakpoint matched, a step-mode endpoint was reached, or `session.pause()` was requested. |
+| `step` | `MachineState` | Fire-and-forget (sync hot-loop tracing). | Once per iter, between any before-pause and after-pause. |
+| `iter` | `MachineState` | **Awaited** (sequenced, blocks the engine). Use for throttle / per-iter coordination / step-boundary synthesis. | Once per iter, at end. After any after-pause. |
+| `halt` | (none) | Fire-and-forget. | Once, on natural halt. Does NOT fire when `stop()` was called. |
+
+### The pause descriptor: `m.pause`
+
+`pause` listeners receive a `PausedMachineState` — a plain `MachineState` plus a `pause: { side, cause }` descriptor (raw `runStepByStep` yields have no such field).
+
+- **`side`** — `'before'` or `'after'`. Exactly one: DebugSession dispatches the two timings as separate `pause` events, so a descriptor is always one-sided. (`'step'` / `'manual'` causes only ever fire on the `'before'` side.)
+- **`cause`** — distinguishes the origin:
+  - `'breakpoint'` — a `state.debug` filter matched, or `haltState.debug === true` triggered.
+  - `'step'` — a `stepIn` / `stepOver` / `stepOut` directive's natural endpoint was reached.
+  - `'manual'` — `session.pause()` was called from outside.
+
+**When an iter satisfies more than one trigger**, exactly **one** `pause` event fires — never two at the same iter — and `cause` is chosen by precedence:
+
+```
+breakpoint  >  step  >  manual
+```
+
+So a step-mode endpoint (or a pending manual pause) that lands exactly on a breakpoint reports `cause: 'breakpoint'`; a manual pause that coincides with a step endpoint reports `cause: 'step'`. Rationale: a breakpoint is the user's explicit, persistent intent ("always stop here"), so it's the most informative attribution; a step directive is a specific computed endpoint, more specific than the vaguer "pause soon" of a manual request. The step-mode is still consumed (one-shot rule below) regardless of which cause is reported — if the iter was the step's endpoint, the step is satisfied. Matches IDE convention (a breakpoint on the line you step onto reports as a breakpoint stop).
+
+### One-shot step-mode rule
+
+Every active step-mode (`stepIn` / `stepOver` / `stepOut`) is dropped on the next `pause` dispatch — whether that dispatch is the step's own endpoint, an inner breakpoint that fired sooner, or a manual pause. To keep stepping, call `stepIn` / `stepOver` / `stepOut` again from the new pause. Matches IDE convention.
 
 ### Setting breakpoints by graph id
 
@@ -532,25 +617,62 @@ if (e && sym) {
 
 ### Throttle pattern
 
-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:
+For per-iter throttle / animation / "wait between steps" UIs, use `session.setRunInterval(ms)`:
+
+```ts
+const session = new DebugSession(machine, { initialState });
+session.setRunInterval(50);     // 50ms between iters
+session.on('iter', (m) => { /* update UI with iter snapshot */ });
+await session.start();
+```
+
+The throttle inserts an awaited `setTimeout(ms)` at the end of every iter, after both `pause` dispatches (if any) and the `iter` event. Updates take effect on the next iter. `0` disables.
+
+### v7 migration from `run({onPause, onStep, onIter, debug})`
+
+v7 splits the v6 mixed-mode `run()` into three non-overlapping entry points. Old shape → new shape:
 
 ```ts
+// v6 — async run() with optional callbacks
 await machine.run({
   initialState,
-  onIter: async (m) => {
-    // Fires after before(m.state) / step / after(m.state) on iter m.step.
-    await new Promise((r) => setTimeout(r, intervalMs));
-  },
+  onStep: (m) => { ... },
+  onPause: async (m) => { ... },
+  onIter: async (m) => { ... },
+  debug: true,
 });
+
+// v7 — DebugSession for interactive use
+const session = new DebugSession(machine, { initialState });
+session.on('step', (m) => { ... });
+session.on('pause', (m) => { ...; session.continue(); });
+session.on('iter', (m) => { ... });
+await session.start();
+```
+
+Or, if you only used `run({ initialState })` with no callbacks, just drop the `await` — `run()` is now synchronous:
+
+```ts
+// v6
+await machine.run({ initialState });
+
+// v7
+machine.run({ initialState });
 ```
 
-`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.
+For sync per-iter tracing without breakpoint-driven flow, iterate the `runStepByStep` generator directly — `onStep` no longer exists:
 
-A few details:
+```ts
+// v6
+await machine.run({ initialState, onStep: (m) => trace(m) });
+
+// v7
+for (const m of machine.runStepByStep({ initialState })) {
+  trace(m);
+}
+```
 
-- **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`).
+The `debug: false` master switch is gone — in v7 the session is the only consumer of breakpoints; if you don't register a `pause` listener, breakpoints fire-and-resume invisibly (the session's `start()` still resolves cleanly), or you can use `runStepByStep` directly, which ignores `state.debug` altogether (its yields carry no pause field).
 
 (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+.)
 
@@ -708,8 +830,8 @@ Reading `['0',*] → [K,'0']/[R,R]`:
 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.
+- **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). *Superseded in v7 by #207: `haltState.debug` is now `boolean`, all object-shaped writes throw.*
+- **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 held through v6; **v7 removes it** — breakpoint detection moved into `DebugSession`, and the pause descriptor is now `m.pause: {side, cause}` on the `pause` event only.)
 - **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.

package/dist/classes/DebugSession.d.ts

@@ -0,0 +1,119 @@
+import State from './State';
+import TuringMachine, { type MachineState, type PausedMachineState } from './TuringMachine';
+/**
+ * Parameters mirror `TuringMachine.runStepByStep` / `run`. DebugSession passes
+ * them straight through to the engine generator.
+ */
+export type DebugSessionParameter = {
+    initialState: State;
+    stepsLimit?: number;
+};
+export type DebugSessionEvent = 'pause' | 'step' | 'iter' | 'halt';
+/**
+ * Listener signatures and dispatch contract by event:
+ *
+ * - `step` — fire-and-forget. Sync hot-loop tracing; listener Promise (if any)
+ *   is not awaited. Matches the v6 `onStep` contract.
+ * - `iter` — **AWAITED** (sequenced, blocks the engine). For per-iter
+ *   throttle / coordination / step-boundary synthesis where the engine
+ *   genuinely needs to wait for the listener's work before advancing.
+ *   Matches the v6 `onIter` contract.
+ * - `pause` — implicitly awaited via the session's internal `#pauseResolver`:
+ *   the engine pauses on the pause-promise, listeners fire (their Promises
+ *   are NOT awaited individually), and resume is signaled by an explicit
+ *   call to `session.continue()` / `stepIn` / `stepOver` / `stepOut` /
+ *   `stop` — fundamentally external to the listener's call site (UI click,
+ *   postMessage, timer, etc.).
+ * - `halt` — fire-and-forget. Terminal notification.
+ *
+ * `pause` listeners receive a `PausedMachineState` (a `MachineState` plus the
+ * one-sided `pause: {side, cause}` descriptor). `step` / `iter` listeners
+ * receive a plain `MachineState` — raw yields carry no pause info.
+ */
+export type DebugSessionListener<E extends DebugSessionEvent> = E extends 'halt' ? () => void | Promise<void> : E extends 'pause' ? (machineState: PausedMachineState) => void | Promise<void> : (machineState: MachineState) => void | Promise<void>;
+/**
+ * Interactive debugger session for `TuringMachine`. Owns the coordination
+ * layer that every UI debugger / IDE extension / educational demo would
+ * otherwise reimplement: breakpoint dispatch, step-in / step-over / step-out,
+ * click-pause from outside, per-iter throttle, pause/resume promise plumbing.
+ *
+ * Construction is direct — the engine class stays minimal and doesn't expose a
+ * `debugRun()` factory; consumers import both classes and write
+ * `new DebugSession(machine, {initialState})`.
+ *
+ * Lifecycle:
+ *   const session = new DebugSession(machine, {initialState});
+ *   session.on('pause', (m) => { ...; session.continue(); });
+ *   session.on('halt', () => { ... });
+ *   await session.start();           // resolves on natural halt or stop()
+ *
+ * Each session is single-use: `start()` may only be called once. Construct a
+ * fresh session to re-run.
+ */
+export default class DebugSession {
+    #private;
+    constructor(machine: TuringMachine, parameter: DebugSessionParameter);
+    on<E extends DebugSessionEvent>(event: E, listener: DebugSessionListener<E>): this;
+    off<E extends DebugSessionEvent>(event: E, listener: DebugSessionListener<E>): this;
+    stop(): void;
+    /**
+     * Request a pause from outside the run loop. The pause fires on the next
+     * iter's before-side with `cause: 'manual'`. If a breakpoint matches that
+     * same iter, the breakpoint takes precedence and the request is consumed
+     * silently (one pause, cause: 'breakpoint').
+     *
+     * No-op if the session is already paused — the next `continue` / step call
+     * resumes normal execution, then the flag fires on the iter AFTER that.
+     * Equivalent to a debouncing one-shot.
+     */
+    pause(): void;
+    /**
+     * Set the per-iter throttle delay in milliseconds. After each iter (including
+     * any pause + step + iter listeners on that iter), the loop awaits
+     * `setTimeout(ms)` before proceeding to the next iter. `0` disables the
+     * throttle.
+     *
+     * Useful for visualization UIs that want to animate execution at a fixed
+     * pace. Updates take effect on the next iter.
+     */
+    setRunInterval(ms: number): void;
+    /**
+     * Resume from the current pause, returning to normal execution until the
+     * next breakpoint or natural halt. No-op when called outside of a paused
+     * state.
+     */
+    continue(): void;
+    /**
+     * Resume and force a pause on the next iter regardless of whether that
+     * iter's `state.debug` filter matches. Step-mode is one-shot: any
+     * subsequent pause dispatch (this step-in's endpoint, an inner
+     * breakpoint, or a manual pause) drops it. To keep stepping, call
+     * stepIn() again from the new pause.
+     */
+    stepIn(): void;
+    /**
+     * Resume and pause at the next iter back at (or above) the click-time depth
+     * — i.e. `depth <= clickTimeDepth`. Frames the stepped-over iter pushes are
+     * run to completion without pausing inside (the engine's continuation-passing
+     * `withOverriddenHaltState` "calls"). Mirrors DevTools Step Over.
+     *
+     * For a plain iter (no frame push) this coincides with stepIn (next iter is
+     * already at the same depth). The Over-vs-In / Over-vs-Out distinction only
+     * appears under genuine nesting (a bare that itself enters a wrapper).
+     *
+     * One-shot: an inner breakpoint or any other pause drops the step-over
+     * intent. The endpoint pause carries `cause: 'step'`.
+     */
+    stepOver(): void;
+    /**
+     * Resume and pause at the next iter STRICTLY shallower than the click-time
+     * depth — `depth < clickTimeDepth` — i.e. once the current frame itself has
+     * been popped. Mirrors DevTools Step Out.
+     *
+     * Throws when the click-time depth is 0: there's no enclosing frame to exit
+     * (IDE convention — "step out of nothing" is a programming error, not a
+     * silent no-op).
+     */
+    stepOut(): void;
+    start(): Promise<void>;
+}

package/dist/classes/State.d.ts

@@ -73,11 +73,34 @@ export default class State {
      * code uses). Order matches insertion order of the underlying Set.
      */
     get tags(): readonly string[];
-    /** @internal — invoked by DebugConfig setters via module-private symbol. */
+    /** @internal — invoked by DebugConfig setters via module-private symbol.
+     *  haltState's `debug` setter rejects object writes before reaching
+     *  DebugConfig, so this validator only sees non-halt states. */
     [validateDebugFilter](fieldName: 'before' | 'after', filter: readonly symbol[] | true | undefined): void;
     getSymbol(tapeBlock: TapeBlock): symbol;
     getCommand(symbol: symbol): Command;
     getNextState(symbol: symbol): State | Reference;
+    /**
+     * Like `getNextState`, but also returns the matched Symbol and its index
+     * in this State's transition declaration order (= the `K` in `toGraph`'s
+     * `${stateId}.${K}` transition ids). Used by `TuringMachine.runStepByStep`
+     * to populate `MachineState.matchedTransition` for #205 — exposes which
+     * transition fired so consumers (UIs, log tools, coverage maps) can
+     * resolve the firing edge without re-deriving from `(source, nextState)`,
+     * which is ambiguous when multiple transitions on the same source go to
+     * the same destination.
+     *
+     * Throws (matching `getNextState` / `getCommand`) when no entry exists for
+     * the symbol. For wrappers (states produced by `withOverriddenHaltState`):
+     * the symbol-to-data map is shared with the bare via `bareState`, so the
+     * returned `ix` is a valid position into BOTH the wrapper's and the
+     * bare's transition iteration order — they're the same map.
+     */
+    getMatchedTransition(symbol: symbol): {
+        nextState: State | Reference;
+        matchedSymbol: symbol;
+        ix: number;
+    };
     withOverriddenHaltState(overriddenHaltState: State): State;
     /**
      * @internal
@@ -164,5 +187,26 @@ export default class State {
      */
     static collectStates(initialState: State, tapeBlock: TapeBlock): StateMap;
 }
-export declare const haltState: State;
+/**
+ * Typed alias for the haltState singleton (#207). Narrows `debug` from
+ * the generic-State `DebugConfig | boolean` union to plain `boolean`,
+ * giving compile-time type-safety at the singleton's call sites:
+ *
+ * ```ts
+ * haltState.debug = true;            // ok
+ * haltState.debug = false;           // ok
+ * haltState.debug = { before: true } // TS error
+ * const isOn = haltState.debug;      // typed `boolean`
+ * ```
+ *
+ * Anyone holding a `State` reference that happens to BE the singleton (e.g.
+ * via `state.getNextState(sym).ref === haltState`) sees the wider `State`
+ * type; runtime throws guide them to the right shape. The singleton export
+ * is the canonical access path.
+ */
+export type HaltState = State & {
+    get debug(): boolean;
+    set debug(value: boolean | null);
+};
+export declare const haltState: HaltState;
 export {};

package/dist/classes/TapeBlock.d.ts

@@ -23,6 +23,31 @@ export default class TapeBlock {
         currentSymbols?: string[];
         symbol: symbol;
     }): boolean;
+    /**
+     * For a Symbol returned by `this.symbol([...])` (or the catch-all
+     * `ifOtherSymbol`), returns the per-tape match kind for the
+     * **alternative that actually matched** given `currentSymbols`:
+     * `'wildcard'` if that tape position was `ifOtherSymbol` in the winning
+     * alternative, `'literal'` otherwise. Length always equals the tape
+     * count.
+     *
+     * Used by `TuringMachine.runStepByStep` to populate
+     * `MachineState.matchedTransition.matchKinds` for #205. The "winning
+     * alternative" disambiguation matters for alternations like
+     * `[[ifOtherSymbol, 'c'], ['a', 'b']]` — different alternatives can
+     * have different per-tape kinds, and only the alternative that matched
+     * the current head symbols is meaningful.
+     *
+     * - `ifOtherSymbol` (the State's catch-all transition fired): all
+     *   positions are `'wildcard'`.
+     * - Symbol with patternList: find the first alternative that matches
+     *   `currentSymbols` (same predicate as `isMatched`), return its
+     *   per-position kinds.
+     * - Symbol with no winning alternative under the given `currentSymbols`
+     *   (defensive — shouldn't happen if the caller resolved the Symbol via
+     *   the State's normal matching): fall back to all `'literal'`.
+     */
+    patternKinds(symbol: symbol, currentSymbols?: string[]): ('wildcard' | 'literal')[];
     replaceTape(tape: Tape, tapeIx?: number): void;
 }
 export {};