@turing-machine-js/machine 7.0.0-alpha.5 → 7.0.0-alpha.7

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.7] - 2026-05-30
+
+Seventh v7 pre-release. Lands the `CallFrame` extraction ([#213](https://github.com/mellonis/turing-machine-js/issues/213), [PR #218](https://github.com/mellonis/turing-machine-js/pull/218)) and a `toMermaid` framed-wrapper emit fix ([#223](https://github.com/mellonis/turing-machine-js/issues/223), [PR #224](https://github.com/mellonis/turing-machine-js/pull/224)). 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.7`.
+
+### Added
+
+- **`CallFrame extends State`** ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) — `withOverriddenHaltState`'s wrapper is now a first-class `State` subclass instead of a `State` instance aliasing the bare's private `#symbolToDataMap` / `#debugRef`. Transition lookups and `debug` access delegate to the bare. `instanceof State` is preserved (no breaking surface change), and `instanceof CallFrame` becomes the wrapper discriminator. `CallFrame` is exported additively from the package root.
+
+### Fixed
+
+- **`toMermaid` framed-wrapper emit asymmetry** ([#223](https://github.com/mellonis/turing-machine-js/issues/223)) — `toGraph`'s reach-set previously tunneled through wrappers to their continuation but left the wrappers themselves outside the caller's frame, so framed-wrapper-continuations (e.g. `library-binary-numbers/minusOne`'s `goToNumberStart(invertNumberGoToNumberWithInversion)` inside `invertNumber`'s callable subtree) emitted at the top level, visually disconnected from their owner frame. Fix in `utilities/stateGraph.ts`'s `resolveAndPush` pushes the wrapper itself AND tunnels through `overriddenHaltStateId`, so both join the caller's frame; `utilities/graphFormats.ts` renders framed wrappers inside the owner subgraph with the same `[[…]]` shape. Unframed top-level wrappers still emit outside any subgraph. `library-binary-numbers/states.md` regenerated — only the `minusOne` diagram shape changed.
+
+## [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`.

package/README.md

@@ -5,6 +5,8 @@
 
 A composable Turing-machine engine for JavaScript: multi-tape, subroutine composition via `withOverriddenHaltState`, Mermaid round-trip, and runtime breakpoints.
 
+For runtime highlight + breakpoint rendering on top of the engine's `Graph`, plus a byte-identical edge-label formatter and snippet-recording artifacts, see the companion package [`@turing-machine-js/visuals`](../visuals).
+
 <details>
 <summary>Table of contents</summary>
 
@@ -239,7 +241,7 @@ const s = new State({
 Notable members and statics:
 
 - **`state.id`**, **`state.name`** — identity (`isHalt` is `id === 0`).
-- **`state.withOverriddenHaltState(other)`** — returns a copy whose would-be halt transitions fall through to `other`. The subroutine-call composition mechanism (see `library-binary-numbers/src/index.ts` for examples).
+- **`state.withOverriddenHaltState(other)`** — returns a `CallFrame` (a `State` subclass, so it flows anywhere a `State` does) whose would-be halt transitions fall through to `other`. The subroutine-call composition mechanism (see `library-binary-numbers/src/index.ts` for examples). `instanceof CallFrame` is the wrapper discriminator.
 - **`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`.
 - **`State.collectStates(state, tapeBlock)`** — walks the same graph and returns a `Map<number, {state, transitionSymbols}>` keyed by `GraphNode.id`. Use when downstream tooling holds a numeric id (e.g. a clicked node in a rendered graph) and needs the live `State` instance or the per-pattern `Symbol` for breakpoint setup. See [Setting breakpoints by graph id](#setting-breakpoints-by-graph-id).
@@ -307,13 +309,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,26 +331,26 @@ 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.** 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.
+**Rule of thumb.** No observation → `run()`. Sync per-iter observation → iterate `runStepByStep()`. Anything interactive (breakpoints, step controls, throttle, click-pause) → construct a `DebugSession`.
 
-**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).
+**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
 
@@ -365,20 +370,17 @@ matchedTransition: {
 Example use:
 
 ```javascript
-await machine.run({
-  initialState,
-  onStep: (m) => {
-    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'})`);
-  },
-});
+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`
 
-`state.withOverriddenHaltState(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.
+`state.withOverriddenHaltState(other)` returns a `CallFrame` — a `State` subclass that delegates transition lookups and `debug` to `state` (its *bare*) and whose would-be halt transitions fall through to `other` at run time. The bare is left untouched. Because a `CallFrame` is a `State`, it flows anywhere a `State` does (as a `nextState`, through `toGraph`/`fromGraph`); `instanceof CallFrame` distinguishes it from a plain state. 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';
@@ -447,7 +449,7 @@ flowchart TD
 
 **Reading guide** — the v7 callable-subtree emit (introduced in [#174](https://github.com/mellonis/turing-machine-js/issues/174)) models `withOverriddenHaltState` as a function call: the wrapper is the call site, the bare's subtree is the callable body.
 
-1. **`[[scanToX(eraseHere)]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node, drawn OUTSIDE any subgraph. It's the runtime entry point — `idle -. enter .->` arrives here — and shows the composite name (`bare(override)`). Wrappers have no transitions of their own; they delegate to the bare via the `call` arrow.
+1. **`[[scanToX(eraseHere)]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node. It's the runtime entry point — `idle -. enter .->` arrives here — and shows the composite name (`bare(override)`). Wrappers have no transitions of their own; they delegate to the bare via the `call` arrow. **Placement**: this top-level wrapper is drawn OUTSIDE any subgraph; a wrapper that participates in a caller's frame (e.g. an inner-call continuation of another wrapper, as in `library-binary-numbers/minusOne`) renders INSIDE its owner frame's subgraph with the same `[[…]]` shape (see [#223](https://github.com/mellonis/turing-machine-js/issues/223)).
 2. **`subgraph w_1["callable subtree of scanToX"]`** is the bare's callable subtree — the scope of code that runs when the wrapper is "called." It contains the bare `s1["scanToX"]`, any body states reachable from the bare, and a local halt marker `c1(((halt)))` where the bare's halt-bound transitions land.
 3. **The bold `==> call`** from wrapper to bare is the call arrow — visual signature of "wrapper invokes this callable subtree, pushing its override onto the runtime stack." Bold arrows are reserved for wrapper-to-bare calls; counting them in a diagram counts the wrappers in play.
 4. **The dotted `-. return .->`** from the subtree back to the wrapper is the return arrow — fires when the bare halts (lands on `c1`) and the stack pops. The wrapper's solid `--> s2` (to `eraseHere`) is the post-return continuation; ordinary transition under the function-call mental model.
@@ -472,15 +474,35 @@ s.untag('hot');
 s.tags; // readonly ['subroutine-entry']
 ```
 
-**Scoped to the wrapper instance.** Under [`withOverriddenHaltState` memoization (#175)](https://github.com/mellonis/turing-machine-js/issues/175), `A.wohs(t1)` and `A.wohs(t2)` are distinct wrapper instances even though they share `A`'s `#symbolToDataMap`. Tags live on the instance, so tagging one wrapper doesn't propagate to siblings sharing the same bare. Wrappers from `withOverriddenHaltState` start with an empty tag set (do not inherit from bare); the caller tags explicitly as needed.
+**Scoped to the wrapper instance.** Under [`withOverriddenHaltState` memoization (#175)](https://github.com/mellonis/turing-machine-js/issues/175), `A.wohs(t1)` and `A.wohs(t2)` are distinct `CallFrame` instances even though both delegate to the same bare `A`. Tags live on the frame instance, so tagging one wrapper doesn't propagate to siblings sharing the same bare. Wrappers from `withOverriddenHaltState` start with an empty tag set (do not inherit from bare); the caller tags explicitly as needed.
 
 **Round-trip preserved.** `state.toGraph` writes the tag set to `GraphNode.tags`; `state.fromGraph` reads it back and reapplies. `toMermaid` renders tags two ways: inline in the node label (`sN["name<br>tag1, tag2"]`, universal Mermaid line break) and as `classDef tag_<sanitized>` + `class sN tag_<sanitized>` lines for color grouping. `fromMermaid` splits the label on `<br>` as source of truth; the `class` lines are decorative and discarded on parse.
 
 See [§Diagram conventions § Tags](#tags) for the full emit shape.
 
-## Debugging breakpoints
+## Debugging
 
-Any `State` can carry a runtime-mutable `debug` config that pauses execution at chosen points.
+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.
+
+```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';
@@ -508,33 +530,64 @@ haltState.debug = null;         // alias of false (reset)
 myState.debug = null;
 ```
 
-> ⚠️ **`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.debugBreak.after === true`. Diagram + log narratives read naturally: the halt-bound transition has already fired when the pause lands, and halt is the next thing.
+> ⚠️ **`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'`.
 
-> ⚠️ **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`), so it can't intercept the chained form. **Always use the whole-object form: `haltState.debug = true` / `= false` / `= null`.** Modules built with `tsc` / ESM run in strict mode by default and surface this throw; `new Function(...)` and `<script>` without `"use strict"` run non-strict and silently no-op the chained write.
+> ⚠️ **An `after`-side breakpoint on the halt-triggering state collapses with `haltState.debug` into a single pause.** Both target the AFTER side of the *same* iter — the one whose transition leads to halt — and the engine fires at most one pause per iter-side, so you get one `pause` event (`side: 'after'`, `cause: 'breakpoint'`), not two. This is intentional: halt has no iteration of its own, so "after the triggering state" and "before halt" are the **same execution moment**. (Contrast two ordinary states `A → B`: `A`'s `after` and `B`'s `before` are *different* iters, so they fire as two pauses.) There is deliberately no flag to emit a second, ephemeral halt pause — one event for one real moment.
 
-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. A `CallFrame` (from `state.withOverriddenHaltState(...)`) delegates its `debug` to the bare, so an assignment on the original is visible from every wrapper and vice versa. `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).
 
-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.
+**Caveat:** `haltState` is a module-level singleton. Setting `haltState.debug` affects every machine in the process; clear in `afterEach` / `finally` for test isolation.
 
-If `onPause` is not provided, breaks fire-and-resume invisibly — the trajectory is identical to running without `debug` set.
+### DebugSession API
 
-**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).
+| 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. |
 
-**Caveat:** `haltState` is a module-level singleton. Setting `haltState.debug` affects every machine in the process; clear in `afterEach` / `finally` for test isolation.
+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.
+
+### 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
 
@@ -568,25 +621,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+.)
 
@@ -666,7 +756,7 @@ The full reference for reading `toMermaid` output — shapes, edge styles, and t
 |---|---|
 | `s0(((halt)))` | the halt state |
 | `sN["name"]` | a regular state (or a bare, when inside a subgraph) |
-| `sN[["composite-name"]]` | a `withOverriddenHaltState` wrapper (call site, outside any subgraph) — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) |
+| `sN[["composite-name"]]` | a `withOverriddenHaltState` wrapper (call site; outside any subgraph when top-level, INSIDE its owner frame's subgraph when its continuation chain participates in a caller's frame — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) and [#223](https://github.com/mellonis/turing-machine-js/issues/223)) |
 | `cN(((halt)))` inside a subgraph | halt marker (visualization aid; maps back to the singleton `haltState` at runtime) |
 | `idle([idle])` | pre-execution sentinel (not a real state) |
 
@@ -745,7 +835,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 
 - **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). *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 is unchanged across all three versions.
+- **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

@@ -74,9 +74,8 @@ export default class State {
      */
     get tags(): readonly string[];
     /** @internal — invoked by DebugConfig setters via module-private symbol.
-     *  Per #207, haltState no longer flows through DebugConfig (its `debug`
-     *  setter rejects object writes before construction), so the validator
-     *  only sees non-halt states here. */
+     *  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;
@@ -102,7 +101,7 @@ export default class State {
         matchedSymbol: symbol;
         ix: number;
     };
-    withOverriddenHaltState(overriddenHaltState: State): State;
+    withOverriddenHaltState(overriddenHaltState: State): CallFrame;
     /**
      * @internal
      *
@@ -210,4 +209,51 @@ export type HaltState = State & {
     set debug(value: boolean | null);
 };
 export declare const haltState: HaltState;
+/**
+ * A first-class call frame produced by `State.withOverriddenHaltState`
+ * (#213). A `CallFrame` is a `State` — `instanceof State` holds, so it flows
+ * anywhere a `State` does (as a `nextState`, through `toGraph`/`fromGraph`,
+ * etc.) — but it carries its own `bare` (the wrapped State) and `override`
+ * (the continuation pushed onto the run-stack on entry). `instanceof
+ * CallFrame` is the explicit wrapper discriminator.
+ *
+ * It owns no transitions of its own: lookups (`getSymbol`/`getCommand`/
+ * `getNextState`/`getMatchedTransition`) and `debug` DELEGATE to the bare,
+ * replacing the v6 field-aliasing (where a wrapper was a plain `State` whose
+ * private `#symbolToDataMap`/`#debugRef` were physically shared with the
+ * bare). `id`, `name` (composite `bare(override)`), and `tags` are its own
+ * (inherited State fields) — so memoized frames sharing a bare keep
+ * independent tags (#186), and the frame is never the halt singleton
+ * (fresh nonzero `#id` → `isHalt === false`).
+ */
+export declare class CallFrame extends State {
+    #private;
+    constructor(bare: State, override: State);
+    get bare(): State;
+    get overriddenHaltState(): State;
+    getSymbol(tapeBlock: TapeBlock): symbol;
+    getCommand(symbol: symbol): Command;
+    getNextState(symbol: symbol): State | Reference;
+    getMatchedTransition(symbol: symbol): {
+        nextState: State | Reference;
+        matchedSymbol: symbol;
+        ix: number;
+    };
+    get debug(): DebugConfig;
+    set debug(value: DebugConfig | {
+        before?: symbol[] | readonly symbol[] | true;
+        after?: symbol[] | readonly symbol[] | true;
+    } | null);
+    [STATE_INTERNAL](): {
+        readonly id: number;
+        name: string;
+        readonly bareState: State | null;
+        readonly overriddenHaltState: State | null;
+        readonly symbolToDataMap: Map<symbol, {
+            command: Command;
+            nextState: State | Reference;
+        }>;
+        readonly tags: ReadonlySet<string>;
+    };
+}
 export {};