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

package/CHANGELOG.md

@@ -4,6 +4,88 @@ 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.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`.
+
+**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.4`.
+
+### Added
+
+- **`State.collectStates(initialState, tapeBlock)`** ([#195](https://github.com/mellonis/turing-machine-js/issues/195)). Static helper that returns a `Map<number, {state: State; transitionSymbols: symbol[]}>` keyed by engine `GraphNode.id`. Lets downstream tooling (graph renderers, debugger panels) mutate `state.debug` on a specific State by numeric id, and set per-pattern breakpoints by `GraphTransition.id`. The K-th `transitionSymbols` slot is positionally aligned with the GraphTransition whose id is `${stateId}-${K}`, so a consumer holding `(stateId, patternIx)` from the rendered graph reaches the firing Symbol with no walk.
+
+  ```ts
+  const stateMap = State.collectStates(initial, tapeBlock);
+
+  // State-level breakpoint by id (any pattern fires).
+  stateMap.get(clickedStateId)!.state.debug.before = true;
+
+  // Per-pattern breakpoint by GraphTransition.id ("${stateId}-${patternIx}").
+  const [n, k] = clickedEdgeId.split('-').map(Number);
+  const entry = stateMap.get(n)!;
+  entry.state.debug.before = [entry.transitionSymbols[k]!];
+  ```
+
+  Coverage: regular / bare states get the full `[...#symbolToDataMap.keys()]` including `ifOtherSymbol` at its natural slot; wrappers and the halt singleton get empty `transitionSymbols`; synthetic halt markers (`isHaltMarker: true`, id `= -frameId`) are excluded — they all collapse to `haltState` at runtime, and the named consumer surfaces halt-pause via a separate UI control, not via clicks on halt glyphs. The halt singleton entry at id `0` is the process-wide `haltState` — toggling its `.debug` affects every machine in the runtime, same caveat as direct `haltState.debug` writes.
+
+- **`StateMap` and `StateMapEntry` types** ([#195](https://github.com/mellonis/turing-machine-js/issues/195)). Exported from the package's public surface so TypeScript consumers can annotate `collectStates` results without re-deriving the shape.
+
+### Changed
+
+- **Graph serialization extracted to `utilities/stateGraph.ts`** ([#180](https://github.com/mellonis/turing-machine-js/issues/180)). `State.toGraph` and `State.fromGraph` move out of the State class into a sibling module, alongside the new `collectStates`. Public surface preserved — `State.toGraph` / `State.fromGraph` remain as thin static delegates. State.ts shrank ~440 lines and now focuses on the runtime machinery (transitions, debug, halt-stack composition) rather than mixing in serialization concerns. A new `@internal` `STATE_INTERNAL` Symbol-keyed accessor on `State` gives sibling modules in `packages/machine/src` getter/setter access to private fields (`id`, `name`, `bareState`, `overriddenHaltState`, `symbolToDataMap`, `tags`); not re-exported from the public `index.ts`, so external consumers can't observe it.
+
+### Fixed
+
+- **`toMermaid` edge labels containing literal `"` now parse correctly** ([#194](https://github.com/mellonis/turing-machine-js/issues/194)). Before: an alphabet that includes printable ASCII as literal symbols (e.g. a Brainfuck-flavored UTM whose data alphabet covers U+0020–U+007E) would emit an edge label like `s1 -- "['a'] → ['"']/[R]" --> s0`; Mermaid's parser terminated the string early on the inner `"`. After: user-supplied content (alphabet symbols, state names, tag names, frame bare names) is HTML-entity-escaped at the leaf — `&`, `"`, `<`, `>` to named entities; statement terminators (`\n`, `\r`), C0 controls minus `\t`, DEL, bidi controls, and lone UTF-16 surrogates to numeric entities. Printable Unicode (Cyrillic, CJK, accented Latin, etc.) passes through unchanged so non-ASCII alphabets stay readable in the emitted `.mmd`. `fromMermaid` mirrors with a single-pass entity decoder applied at the leaf, after structural parsing.
+
+- **`runStepByStep` halt-stack is now run-scoped, not machine-scoped** ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). Before: the `#stack` field on `TuringMachine` was an instance field; a build-time peek that didn't drain the generator (e.g. graph-construction utilities that ask for one yield to inspect the initial state) left leftover entries in the stack that were popped during the NEXT halt-bound transition, producing a "ghost iteration" and silently leaking memory across consecutive `runStepByStep` calls on the same machine. After: the halt stack is a local `const stack: State[] = []` declared inside `runStepByStep`, so each generator call starts with a clean stack and entries can't survive into the next call.
+
+### Compatibility
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4` on `@turing-machine-js/builder`, `@turing-machine-js/library-binary-numbers`, `@turing-machine-js/library-binary-numbers-bare`.
+
+### Migration from alpha.3
+
+Purely additive — no breaking changes. Existing code that doesn't call `State.collectStates` continues to work identically. `State.toGraph` / `State.fromGraph` behave identically (the delegate-to-stateGraph wiring is internal); no consumer changes needed.
+
+The `STATE_INTERNAL` accessor is `@internal` and not part of the supported surface; ignore it unless you're authoring a sibling module inside `packages/machine/src`.
+
+### Out of v7-alpha.4 (still pending for stable v7.0.0)
+
+- **[#102](https://github.com/mellonis/turing-machine-js/issues/102)** — debugger step-in / step-out / step-over primitives.
+
 ## [7.0.0-alpha.3] - 2026-05-21
 
 Third v7 pre-release. Adds first-class out-of-band tags on `State` ([#186](https://github.com/mellonis/turing-machine-js/issues/186)) — a metadata channel for visualization grouping and debugger labels that survives `toGraph` / `fromGraph` / `toMermaid` / `fromMermaid` round-trips. Driven by downstream [post-machine-js#86](https://github.com/mellonis/post-machine-js/issues/86), which will build a path-based registry and inline pseudo-command on top once this ships. Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.

package/README.md

@@ -242,6 +242,7 @@ Notable members and statics:
 - **`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.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).
 
 For visualization, pair `State.toGraph` with `toMermaid` to render the graph in any Mermaid-aware viewer (GitHub, VS Code, mermaid.live):
 
@@ -326,6 +327,7 @@ Each yielded `step` (`MachineState`) has these fields:
 | `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.
 
@@ -345,6 +347,35 @@ Both APIs are first-class — `run()` is built on top of `runStepByStep()` (see
 
 **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).
 
+### 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.
+
+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'})`);
+  },
+});
+```
+
 ## 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.
@@ -466,14 +497,20 @@ 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.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.
+
+> ⚠️ **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.
 
 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`.
 
@@ -499,6 +536,36 @@ If `onPause` is not provided, breaks fire-and-resume invisibly — the trajector
 
 **Caveat:** `haltState` is a module-level singleton. Setting `haltState.debug` affects every machine in the process; clear in `afterEach` / `finally` for test isolation.
 
+### Setting breakpoints by graph id
+
+Downstream UIs (graph renderers, debugger panels) often have only a numeric `GraphNode.id` — the user clicked a state node, or a transition edge in a rendered SVG. `State.collectStates(initial, tapeBlock)` returns a `Map` keyed by that numeric id, with the live `State` instance and the per-pattern `Symbol` array as its value:
+
+```ts
+import { State, ifOtherSymbol } from '@turing-machine-js/machine';
+
+const stateMap = State.collectStates(initial, tapeBlock);
+
+// Toggle a state-level breakpoint by id (any pattern triggers).
+const entry = stateMap.get(clickedStateId);
+if (entry) {
+  entry.state.debug.before = true;
+}
+
+// Per-pattern breakpoint by GraphTransition.id — the contract is
+// positional: `transitionSymbols[K]` is the Symbol that the
+// `${stateId}-${K}` GraphTransition fires on.
+const [n, k] = clickedEdgeId.split('-').map(Number);
+const e = stateMap.get(n);
+const sym = e?.transitionSymbols[k];
+if (e && sym) {
+  e.state.debug.before = [sym];
+}
+```
+
+**Coverage rules:** regular / bare states get the full `[...#symbolToDataMap.keys()]` including `ifOtherSymbol` at its natural slot; wrappers and the halt singleton get empty `transitionSymbols`; synthetic halt markers (Graph nodes with `id = -frameId`, one per callable-subtree frame) are excluded from the map. See `State.collectStates` JSDoc for the full contract.
+
+> ⚠️ `stateMap.get(0)!.state === haltState` — the entry at id `0` is the process-wide halt singleton. Toggling its `debug` affects every machine in the runtime, same caveat as direct `haltState.debug` writes.
+
 ### 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:
@@ -677,13 +744,15 @@ 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).
+- **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.1** — `state.debug` ergonomics: the field is now always a non-null `DebugConfig` instance (lazy-initialized on first read), so chained field writes like `state.debug.before = true` work on a fresh state without a prior whole-object assignment. The `DebugConfig` instance is `Object.seal`-ed, so typos like `state.debug.bofore = true` throw `TypeError` at write time instead of silently creating a useless property. `state.debug = null` continues to work but semantically means "reset filters" — the next read returns a fresh empty `DebugConfig` (#150).
 - **v6.2** *(superseded by v6.3.0)* — widened `onStep`'s signature to `(m) => void | Promise<void>` and added an inline `await onStep(...)` in the run loop, enabling throttle-in-`onStep` patterns. This overturned the docstring-stated contract that `onStep` is sync (microtask-free); the right place for per-iter throttling is `onPause` with self-rearm (see [Throttle pattern](#throttle-pattern)). Restored in v6.3.0.
 - **v6.3** — `onStep` reverted to its v6.0–v6.1 sync contract — `(m) => void`, called synchronously inside the run loop. The Throttle pattern section documents the engine-native shape for per-iter throttle / "wait between iters" UIs. No other API changes.
 - **v6.4** — New **`onIter`** hook on `run()`: awaited, fires once at the end of every iter (after both `onPause` dispatches on the same yield), unaffected by the `debug` master switch. Use for per-iter throttle / animation / coordination needing a suspend point; complements the existing sync `onStep` (tracing) and conditional `onPause` (user breakpoints). Three-hook contract is now `onStep` (sync, mid-iter) / `onPause` (awaited, on `state.debug` match) / `onIter` (awaited, end-of-iter). Additive — peer-deps unchanged. The v6.3.0 README's `onPause`-rearm throttle workaround is superseded.
-- **v7** *(latest alpha: alpha.3, 2026-05-21)* — Composition-representation overhaul + first-class state tags. **Pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.3`). Stable v7.0.0 still pending [#102](https://github.com/mellonis/turing-machine-js/issues/102) (debugger step-in/over/out primitives). Highlights across alphas:
+- **v7** *(latest alpha: alpha.4, 2026-05-23)* — Composition-representation overhaul + first-class state tags + id-keyed `State.collectStates` lookup. **Pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.4`). Stable v7.0.0 still pending [#102](https://github.com/mellonis/turing-machine-js/issues/102) (debugger step-in/over/out primitives). Highlights across alphas:
+
+  **alpha.4** — **`State.collectStates(initial, tapeBlock)`** ([#195](https://github.com/mellonis/turing-machine-js/issues/195)) returns a `Map<number, {state, transitionSymbols}>` keyed by `GraphNode.id` so downstream tooling can mutate `state.debug` by numeric id and set per-pattern breakpoints by `GraphTransition.id`. Graph serialization extracted to `utilities/stateGraph.ts` with a Symbol-keyed `@internal` accessor on `State` ([#180](https://github.com/mellonis/turing-machine-js/issues/180); no public-API change — the `State.toGraph` / `.fromGraph` statics remain as thin delegates). Two upstream fixes: `toMermaid` HTML-entity-escapes user content in labels so alphabets containing `"`, `<`, etc. parse correctly ([#194](https://github.com/mellonis/turing-machine-js/issues/194)); `runStepByStep`'s halt stack is now run-scoped, fixing a memory leak / ghost-iteration when the same `TuringMachine` instance is reused across calls ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). See [§Setting breakpoints by graph id](#setting-breakpoints-by-graph-id).
 
   **alpha.3** — first-class **State tags** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). `state.tag(...) / .untag(...) / .tags` API; `GraphNode.tags: string[]` round-trips through `toGraph`/`fromGraph`; `toMermaid` emits tags two ways simultaneously — inline via `<br>` in node labels (`sN["name<br>tag1, tag2"]`) and as `classDef`/`class` for color grouping. Tags live on the State instance (not on the shared `#symbolToDataMap`), so engine [#175](https://github.com/mellonis/turing-machine-js/issues/175) memoization doesn't leak tags across wrappers sharing a bare. See [§State tags](#state-tags).
 

package/dist/classes/State.d.ts

@@ -3,8 +3,31 @@ import Reference from './Reference';
 import TapeBlock from './TapeBlock';
 import TapeCommand from './TapeCommand';
 import { type Graph } from '../utilities/graph';
+import { type StateMap } from '../utilities/stateGraph';
 export declare const ifOtherSymbol: unique symbol;
 declare const validateDebugFilter: unique symbol;
+/**
+ * @internal
+ *
+ * Package-private accessor key for sibling modules in
+ * `packages/machine/src` (e.g. `utilities/stateGraph.ts`, and the planned
+ * `utilities/stateCollect.ts` for #195). Re-exported from this module so
+ * sibling files can import it; intentionally NOT re-exported from the
+ * package's public `index.ts`, so downstream consumers don't see it on
+ * the supported surface.
+ *
+ * Calling `state[STATE_INTERNAL]()` returns a getter/setter view onto the
+ * State's private fields. Reads are live (they close over `this`), so the
+ * view stays in sync with subsequent mutations on the State. There's one
+ * mutating setter on the view — `name` — used exclusively by
+ * `fromGraph` to assign graph-sourced composite names (e.g. `A(target)`)
+ * that the public name validator would reject; see the JSDoc on the
+ * accessor itself.
+ *
+ * Designed in #180 with #195 in mind so its surface doesn't need to grow
+ * when `collectStates` lands.
+ */
+export declare const STATE_INTERNAL: unique symbol;
 export declare class DebugConfig {
     #private;
     constructor(ownerState: State, initial?: {
@@ -50,12 +73,71 @@ 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.
+     *  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. */
     [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
+     *
+     * Package-private getter/setter view onto this State's private fields,
+     * for sibling modules in `packages/machine/src` (currently `stateGraph.ts`
+     * for `toGraph` / `fromGraph`, and the planned `stateCollect.ts` for
+     * #195's `collectStates`).
+     *
+     * Read access is live — the getters close over `this`, so the view
+     * stays in sync with subsequent mutations on this State. There's a
+     * single mutating setter on the view, `name`, which exists to let
+     * `fromGraph` assign graph-sourced composite names (e.g. `A(target)`)
+     * to freshly-constructed bare States. The constructor's name validator
+     * rejects parens (reserved as wrapper-composition delimiters in
+     * `withOverriddenHaltState`); the setter intentionally bypasses that
+     * check because the same delimiters appear in legitimate wrapper-bare
+     * names round-tripped through the graph.
+     *
+     * Returns a fresh view object on every call — cheap enough for the
+     * BFS-once-per-build callers, and avoids holding a reference object on
+     * every State instance. Keep this surface tight: callers should only
+     * read what they need. Adding fields here is a deliberate decision —
+     * each adds to the implicit contract sibling modules can rely on.
+     */
+    [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>;
+    };
     static inspect(state: State): {
         id: number;
         name: string;
@@ -76,12 +158,56 @@ export default class State {
             } | null;
         }>;
     };
+    /**
+     * Walks the reachable State graph from `initialState` and returns a
+     * serializable `Graph`. Thin delegate to `utilities/stateGraph.ts`'s
+     * `toGraph` (extracted in #180); see that module for the BFS shape and
+     * v7 callable-subtree emit semantics.
+     */
     static toGraph(initialState: State, tapeBlock: TapeBlock): Graph;
+    /**
+     * Inverse of `toGraph`: rebuilds a State graph and a fresh TapeBlock
+     * from a serialized `Graph`. Thin delegate to `utilities/stateGraph.ts`'s
+     * `fromGraph` (extracted in #180); see that module for the
+     * reconstruction pass shape (Reference pre-create, bare build, wrapper
+     * resolution via `withOverriddenHaltState`, ref binding).
+     */
     static fromGraph(graph: Graph): {
         start: State;
         tapeBlock: TapeBlock;
         states: Record<number, State>;
     };
+    /**
+     * Returns a `Map<number, {state, transitionSymbols}>` keyed by engine
+     * `GraphNode.id`, exposing the live `State` instance + per-pattern
+     * Symbol references for each node so downstream tooling can mutate
+     * `state.debug` by numeric id and set per-pattern breakpoints by
+     * `GraphTransition.id` (#195). Thin delegate to
+     * `utilities/stateGraph.ts`'s `collectStates`; see that module for
+     * the alignment contract, coverage rules, and halt-singleton warning.
+     */
+    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 {};

package/dist/classes/TuringMachine.d.ts

@@ -26,6 +26,29 @@ export type MachineState = {
         before?: true;
         after?: true;
     };
+    /**
+     * The transition the engine picked for this iter (#205). Always present
+     * — `runStepByStep` resolves it at the very start of every iter via
+     * `state.getMatchedTransition(symbol)`, well before any callback fires.
+     *
+     * - `id` — resolvable in `toGraph`'s output: `graph.nodes[…].transitions`
+     *   contains a `GraphTransition` whose `.id` equals this value. Format is
+     *   `${stateId}.${transitionIx}`. **For wrapper-entry iters (`state` is
+     *   produced by `withOverriddenHaltState`): the wrapper's own
+     *   `transitions` array in `toGraph` is empty because wrappers delegate
+     *   to the bare; this field carries the BARE's transition id, where the
+     *   pattern actually lives.** Consumers can detect this case by
+     *   comparing `id.split('.')[0]` against `state.id` — different = wrapper
+     *   delegation.
+     * - `matchKinds` — per-tape match kind for the picked transition's
+     *   pattern at each tape position. `'wildcard'` if the matched
+     *   alternative had `ifOtherSymbol` at that position, `'literal'`
+     *   otherwise. Length equals tape count.
+     */
+    matchedTransition: {
+        id: string;
+        matchKinds: ('wildcard' | 'literal')[];
+    };
 };
 export default class TuringMachine {
     #private;