From 4707a5a2b59eefd61c90e873a28ae794a2bff64a Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 15:25:41 +0300
Subject: [PATCH 001/118] =?UTF-8?q?refactor!:=20rename=20`withOverrodeHalt?=
 =?UTF-8?q?State`=20=E2=86=92=20`withOverriddenHaltState`=20(closes=20#149?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Grammar fix on a name introduced in 2019. `overridden` (past participle)
fits the "with a halt-state that has been ___" naming idiom; `overrode`
(simple past) didn't. Hard cutover — no deprecated alias.

Renames in lockstep:
- public method `State.prototype.withOverrodeHaltState` → `withOverriddenHaltState`
- getter `state.overrodeHaltState` → `state.overriddenHaltState`
- private field `#overrodeHaltState` → `#overriddenHaltState`
- serialized `Graph` field `node.overrodeHaltStateId` → `node.overriddenHaltStateId`

Consumer migration: global find/replace `OverrodeHaltState` →
`OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`.
Persisted `State.toGraph` JSON dumps would need the same field-rename
treatment, but persistence isn't a known consumer pattern.

CHANGELOG entry deferred to the v7 release PR per repo convention
(entries are dated at release time, no Unreleased section). README
"Versioning notes" section gets a v7 (in progress) entry now.

Cross-repo follow-ups (post-machine-js, machines-demo) wait until
engine v7 publishes to npm — their peer-dep ranges can't widen to
`^7` until `^7` exists.
---
 CLAUDE.md                                     |  8 ++---
 packages/builder/README.md                    |  2 +-
 packages/library-binary-numbers/src/index.ts  | 22 ++++++------
 packages/machine/README.md                    | 26 +++++++-------
 .../machine/src/classes/State.debug.spec.ts   | 12 +++----
 packages/machine/src/classes/State.spec.ts    | 26 +++++++-------
 packages/machine/src/classes/State.ts         | 30 ++++++++--------
 .../src/classes/TuringMachine.debug.spec.ts   |  2 +-
 packages/machine/src/classes/TuringMachine.ts |  8 ++---
 packages/machine/src/utilities/graph.spec.ts  | 26 +++++++-------
 packages/machine/src/utilities/graph.ts       |  2 +-
 .../machine/src/utilities/graphFormats.ts     |  8 ++---
 .../src/utilities/introspection.spec.ts       | 36 +++++++++----------
 .../machine/src/utilities/introspection.ts    | 16 ++++-----
 test/examples.spec.ts                         | 14 ++++----
 15 files changed, 120 insertions(+), 118 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 464b256..8bf5a1c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,7 +39,7 @@ Key shapes that take reading multiple files to grasp:
 
 - **`State` is keyed by `symbol` (the JS primitive), not by string.** A state definition is `{ [tapeBlock.symbol([...])]: { command, nextState } }`. `tapeBlock.symbol(...)` interns a *pattern* over all tapes in the block and returns a unique JS `Symbol`. `State.getSymbol(tapeBlock)` then matches the current head against those interned patterns; if nothing matches, the special `ifOtherSymbol` key is used as a fallback. This is why everything goes through `tapeBlock.symbol(...)` — it's both a symbol factory and a multi-tape pattern compiler. See `TapeBlock.#getSymbolForPatternList` and `State.getSymbol`.
 
-- **`State.withOverrodeHaltState(next)` is a composition primitive.** It returns a copy of the state whose `haltState` transition is replaced by a *continuation* pushed onto `TuringMachine`'s internal stack. When the machine would halt inside that subgraph, it instead pops and resumes. `library-binary-numbers/src/index.ts` uses this heavily (e.g. `minusOne` chains `invertNumber → plusOne → invertNumber → normalizeNumber`). When you see `.withOverrodeHaltState(...)`, read it as "subroutine call, then continue with the argument."
+- **`State.withOverriddenHaltState(next)` is a composition primitive.** It returns a copy of the state whose `haltState` transition is replaced by a *continuation* pushed onto `TuringMachine`'s internal stack. When the machine would halt inside that subgraph, it instead pops and resumes. `library-binary-numbers/src/index.ts` uses this heavily (e.g. `minusOne` chains `invertNumber → plusOne → invertNumber → normalizeNumber`). When you see `.withOverriddenHaltState(...)`, read it as "subroutine call, then continue with the argument."
 
 - **`Reference`** is a forward-declaration handle. `new Reference()` then `.bind(state)` later — this lets you build cyclic state graphs where a state's `nextState` is itself or a not-yet-constructed peer. The `builder` package relies on this to wire arbitrary state-name graphs in a single declarative pass; user code rarely needs `Reference` directly.
 
@@ -47,7 +47,7 @@ Key shapes that take reading multiple files to grasp:
 
 - **`TapeBlock` has a `Lock`** that `TuringMachine.run` grabs for the duration of a run, asserting the block isn't being mutated by another machine. Calls to `applyCommand` from outside a run must pass the matching capture symbol.
 
-- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverrodeHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. Pauses dispatch via the optional `onPause` hook on `run()` (awaited; without the hook, breaks fire-and-resume invisibly). `haltState.debug.before = true` pauses on every halt entry (program exit + subroutine pop). See `packages/machine/README.md` "Debugging breakpoints (v4+)" for the full API.
+- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverriddenHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. Pauses dispatch via the optional `onPause` hook on `run()` (awaited; without the hook, breaks fire-and-resume invisibly). `haltState.debug.before = true` pauses on every halt entry (program exit + subroutine pop). See `packages/machine/README.md` "Debugging breakpoints (v4+)" for the full API.
 
   Cross-version notes:
   - **v5**: hook renamed `onDebugBreak` → `onPause` (#110). `haltState.debug.after = true` (or `{ before, after }` together) now throws at write-time — halt is terminal, no iteration-after-halt to anchor on (#108 part 2). Halting iter's after-fire stopped being silently lost (#108 part 1). New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without editing `state.debug` assignments (#106).
@@ -59,8 +59,8 @@ Key shapes that take reading multiple files to grasp:
 
 ### Visualization & round-trip
 
-`packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same Graph through Mermaid flowchart syntax. The round-trip is **behaviorally** lossless (rebuilt graph runs to same outputs on same inputs — covered by `test/round-trip.spec.ts`); not bytewise lossless because state IDs auto-reassign, and for `withOverrodeHaltState` wrappers the composite name accumulates `>${override.name}` suffixes on each pass. Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) (cleaner emit for wrapped states) + [#139](https://github.com/mellonis/turing-machine-js/issues/139) (regression test that fails until #138 is fixed).
+`packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same Graph through Mermaid flowchart syntax. The round-trip is **behaviorally** lossless (rebuilt graph runs to same outputs on same inputs — covered by `test/round-trip.spec.ts`); not bytewise lossless because state IDs auto-reassign, and for `withOverriddenHaltState` wrappers the composite name accumulates `>${override.name}` suffixes on each pass. Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) (cleaner emit for wrapped states) + [#139](https://github.com/mellonis/turing-machine-js/issues/139) (regression test that fails until #138 is fixed).
 
 ### Builder package
 
-`buildMachine({ alphabetString, initialState, finalStateList, states })` (`packages/builder/src/index.ts`) takes a string-keyed state table where each transition is `{ symbol, movement: 'L'|'R'|'S', state }`. It constructs an `Alphabet` from `alphabetString.split('')`, makes a `Reference` per state name (so forward references work), then materializes every `State` and binds the references. Returns `[machine, initialState, statesByName]`. Use this when you have a textual/tabular spec; use the raw `machine` API when you need composition primitives (`withOverrodeHaltState`, custom symbol patterns, multi-tape).
+`buildMachine({ alphabetString, initialState, finalStateList, states })` (`packages/builder/src/index.ts`) takes a string-keyed state table where each transition is `{ symbol, movement: 'L'|'R'|'S', state }`. It constructs an `Alphabet` from `alphabetString.split('')`, makes a `Reference` per state name (so forward references work), then materializes every `State` and binds the references. Returns `[machine, initialState, statesByName]`. Use this when you have a textual/tabular spec; use the raw `machine` API when you need composition primitives (`withOverriddenHaltState`, custom symbol patterns, multi-tape).
diff --git a/packages/builder/README.md b/packages/builder/README.md
index 9f3e9a5..f7a8415 100644
--- a/packages/builder/README.md
+++ b/packages/builder/README.md
@@ -43,7 +43,7 @@ The state-table format is intentionally minimal. It does **not** support:
 
 - **OR-patterns** (matching multiple current symbols with one transition row). For `tapeBlock.symbol('^10$')` style patterns, use the raw `@turing-machine-js/machine` API.
 - **Multi-tape machines** (`buildMachine` is single-tape only).
-- **`withOverrodeHaltState` composition** (the subroutine-call mechanism). For composed machines like `library-binary-numbers`'s `minusOne`, use the raw API.
+- **`withOverriddenHaltState` composition** (the subroutine-call mechanism). For composed machines like `library-binary-numbers`'s `minusOne`, use the raw API.
 
 If you need any of the above, the inline state-table example in [`@turing-machine-js/machine`'s README](../machine/README.md) shows how to write your own `buildMachine`-equivalent in ~30 lines, and you can extend it to fit your case.
 
diff --git a/packages/library-binary-numbers/src/index.ts b/packages/library-binary-numbers/src/index.ts
index 3762080..009713f 100644
--- a/packages/library-binary-numbers/src/index.ts
+++ b/packages/library-binary-numbers/src/index.ts
@@ -89,7 +89,7 @@ const goToNumbersStart = new State({
 //
 // Composition: go to the number's '^', then sweep right erasing every cell
 // (digits, '^', '$') until the number is gone. Implemented as
-// goToNumbersStart.withOverrodeHaltState(deleteNumberInternal): when
+// goToNumbersStart.withOverriddenHaltState(deleteNumberInternal): when
 // goToNumbersStart would halt at '^', it falls through to the eraser instead.
 const deleteNumberInternal = new State({
   [symbol('$')]: {
@@ -108,7 +108,7 @@ const deleteNumberInternal = new State({
 
 const deleteNumber = new State({
   [symbol('^10$')]: {
-    nextState: goToNumbersStart.withOverrodeHaltState(deleteNumberInternal),
+    nextState: goToNumbersStart.withOverriddenHaltState(deleteNumberInternal),
   },
   [ifOtherSymbol]: {
     nextState: haltState,
@@ -118,7 +118,7 @@ const deleteNumber = new State({
 // invertNumber — 5 nodes
 //
 // Composition: go to '^', then sweep right flipping each bit until '$'.
-// Same shape as deleteNumber (goToNumbersStart.withOverrodeHaltState(...)) but
+// Same shape as deleteNumber (goToNumbersStart.withOverriddenHaltState(...)) but
 // the inner state writes the complement instead of erasing.
 const invertNumberGoToNumberWithInversion = new State({
   [symbol('^')]: {
@@ -145,7 +145,7 @@ const invertNumberGoToNumberWithInversion = new State({
 
 const invertNumber = new State({
   [symbol('^10$')]: {
-    nextState: goToNumbersStart.withOverrodeHaltState(invertNumberGoToNumberWithInversion),
+    nextState: goToNumbersStart.withOverriddenHaltState(invertNumberGoToNumberWithInversion),
   },
   [ifOtherSymbol]: {
     nextState: haltState,
@@ -184,7 +184,7 @@ const normalizeNumberMoveNumberStart = new State({
 
 const normalizeNumber = new State({
   [symbol('^10$')]: {
-    nextState: goToNumbersStart.withOverrodeHaltState(normalizeNumberMoveNumberStart),
+    nextState: goToNumbersStart.withOverriddenHaltState(normalizeNumberMoveNumberStart),
   },
   [ifOtherSymbol]: {
     nextState: haltState,
@@ -272,7 +272,7 @@ const plusOne = new State({
 //
 // Computes x − 1 via the two's-complement identity:  x − 1 == ~(~x + 1)
 // (every step is a state we already have), composed with three nested
-// withOverrodeHaltState calls to chain invert → plusOne → invert → normalize.
+// withOverriddenHaltState calls to chain invert → plusOne → invert → normalize.
 //
 // This is *deliberately* the heavy version. It exists side-by-side with
 // minusOneFast (10 nodes, direct borrow) to make the cost of "compose existing
@@ -286,11 +286,11 @@ const minusOne = new State({
   },
   [symbol('$')]: {
     nextState: invertNumber
-      .withOverrodeHaltState(
+      .withOverriddenHaltState(
         plusOne
-          .withOverrodeHaltState(
+          .withOverriddenHaltState(
             invertNumber
-              .withOverrodeHaltState(normalizeNumber),
+              .withOverriddenHaltState(normalizeNumber),
           ),
       ),
   },
@@ -307,7 +307,7 @@ const minusOne = new State({
 //
 // Same algorithm as minusOne in @turing-machine-js/library-binary-numbers-bare
 // (which is 3 nodes there). The extra 7 nodes here are the cost of: scanning
-// past '^' on entry, the goToNumberStart path and its withOverrodeHaltState
+// past '^' on entry, the goToNumberStart path and its withOverriddenHaltState
 // wrapper for normalize, and normalizeNumber's own marker-relocation chain.
 const minusOneFastBorrow = new State({
   [symbol('1')]: {
@@ -337,7 +337,7 @@ const minusOneFast = new State({
     command: {
       movement: movements.left,
     },
-    nextState: minusOneFastBorrow.withOverrodeHaltState(normalizeNumber),
+    nextState: minusOneFastBorrow.withOverriddenHaltState(normalizeNumber),
   },
   [ifOtherSymbol]: {
     nextState: haltState,
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 4d17fa7..12498bd 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -3,7 +3,7 @@
 [![build](https://github.com/mellonis/turing-machine-js/actions/workflows/main.yml/badge.svg)](https://github.com/mellonis/turing-machine-js/actions/workflows/main.yml)
 ![npm (tag)](https://img.shields.io/npm/v/@turing-machine-js/machine)
 
-A composable Turing-machine engine for JavaScript: multi-tape, subroutine composition via `withOverrodeHaltState`, Mermaid round-trip, and runtime breakpoints.
+A composable Turing-machine engine for JavaScript: multi-tape, subroutine composition via `withOverriddenHaltState`, Mermaid round-trip, and runtime breakpoints.
 
 <details>
 <summary>Table of contents</summary>
@@ -12,7 +12,7 @@ A composable Turing-machine engine for JavaScript: multi-tape, subroutine compos
 - [Quick start](#quick-start)
 - [Building from a state table](#building-from-a-state-table)
 - [Classes](#classes) — [`Alphabet`](#alphabet) · [`Tape`](#tape) · [`TapeBlock`](#tapeblock) · [`TapeCommand`](#tapecommand) · [`Command`](#command) · [`State`](#state) · [`Reference`](#reference) · [`TuringMachine`](#turingmachine)
-- [Subroutine composition with `withOverrodeHaltState`](#subroutine-composition-with-withoverrodehaltstate)
+- [Subroutine composition with `withOverriddenHaltState`](#subroutine-composition-with-withoverriddenhaltstate)
 - [Debugging breakpoints](#debugging-breakpoints)
 - [Special objects](#special-objects) — [`haltState`](#haltstate) · [`ifOtherSymbol`](#ifothersymbol) · [`movements`](#movements) · [`symbolCommands`](#symbolcommands)
 - [Introspection and testing](#introspection-and-testing)
@@ -251,7 +251,7 @@ const s = new State({
 Notable members and statics:
 
 - **`state.id`**, **`state.name`** — identity (`isHalt` is `id === 0`).
-- **`state.withOverrodeHaltState(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 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`.
 
@@ -279,7 +279,7 @@ flowchart TD
 
 > 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
 
-`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). It is *not* bytewise lossless: state IDs auto-reassign on each rebuild, and for `withOverrodeHaltState` wrappers the composite name gains a `>${override.name}` suffix on each pass (e.g., `scanToX>eraseHere` becomes `scanToX>eraseHere>eraseHere` on a second round-trip — tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138)).
+`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). It is *not* bytewise lossless: state IDs auto-reassign on each rebuild, and for `withOverriddenHaltState` wrappers the composite name gains a `>${override.name}` suffix on each pass (e.g., `scanToX>eraseHere` becomes `scanToX>eraseHere>eraseHere` on a second round-trip — tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138)).
 
 ### Reference
 
@@ -366,9 +366,9 @@ 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).
 
-## Subroutine composition with `withOverrodeHaltState`
+## Subroutine composition with `withOverriddenHaltState`
 
-`state.withOverrodeHaltState(other)` returns a copy of `state` whose would-be halt transitions fall through to `other` at run time. The original is left untouched. This is the engine's only composition primitive — bigger machines are built by stacking smaller halt-on-completion subroutines.
+`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.
 
 ```javascript
 import { Alphabet, State, TapeBlock, TuringMachine, Tape, haltState, ifOtherSymbol, movements, symbolCommands } from '@turing-machine-js/machine';
@@ -389,7 +389,7 @@ const eraseHere = new State({
 }, 'eraseHere');
 
 // Compose: scan to X, then ERASE it. scanToX is unmodified.
-const scanThenErase = scanToX.withOverrodeHaltState(eraseHere);
+const scanThenErase = scanToX.withOverriddenHaltState(eraseHere);
 
 const tape = new Tape({ alphabet, symbols: ['a', 'b', 'X', 'b', 'a'] });
 tapeBlock.replaceTape(tape);
@@ -409,7 +409,7 @@ flowchart LR
         a1 -- "X → keep, S" --> h1
         a1 -- "any other → keep, R" --> a1
     end
-    subgraph composed["scanToX.withOverrodeHaltState(eraseHere) — halt is intercepted"]
+    subgraph composed["scanToX.withOverriddenHaltState(eraseHere) — halt is intercepted"]
         direction LR
         a2(("scanToX"))
         b2(("eraseHere"))
@@ -453,16 +453,16 @@ flowchart TD
 
 **Reading guide** — the wrapped diagram is denser than the simplified hand-drawn version above. To parse it:
 
-1. **Three non-halt nodes:** the wrapper `scanToX>eraseHere` (round, the initial state); `scanToX` (square, the original subroutine — unmodified); `eraseHere` (square, the override target). The wrapper appears as a *separate* state from `scanToX`-the-original because `withOverrodeHaltState` returns a new `State` instance — even though it shares the transition map.
+1. **Three non-halt nodes:** the wrapper `scanToX>eraseHere` (round, the initial state); `scanToX` (square, the original subroutine — unmodified); `eraseHere` (square, the override target). The wrapper appears as a *separate* state from `scanToX`-the-original because `withOverriddenHaltState` returns a new `State` instance — even though it shares the transition map.
 2. **Solid edges from the wrapper duplicate `scanToX`'s edges.** That's because the wrapper inherits the same `symbolToDataMap`. Importantly, the wrapper's `* → ·/R` edge points at *`scanToX`-the-original*, not at the wrapper itself — so after the first iteration, control transfers to `scanToX` and stays there.
-3. **The dotted `onHalt` edge is attached to the wrapper** but it doesn't fire on a single edge at runtime. Instead, the runtime pushes `eraseHere` onto an internal stack at startup, and *any* halt-bound transition reachable during the run (whether on the wrapper itself or on `scanToX`) gets redirected to `eraseHere` via stack-pop. The dotted edge is the engine's static fingerprint of "this graph was wrapped by `withOverrodeHaltState`."
+3. **The dotted `onHalt` edge is attached to the wrapper** but it doesn't fire on a single edge at runtime. Instead, the runtime pushes `eraseHere` onto an internal stack at startup, and *any* halt-bound transition reachable during the run (whether on the wrapper itself or on `scanToX`) gets redirected to `eraseHere` via stack-pop. The dotted edge is the engine's static fingerprint of "this graph was wrapped by `withOverriddenHaltState`."
 4. **What actually fires at runtime, on tape `['a','b','X','b','a']`:** the wrapper runs once, transferring to `scanToX`; `scanToX` self-loops on `* → ·/R` until it sees `X`; the `X → ·/S` edge tries to go to halt; the runtime pops `eraseHere` off the stack and substitutes it; `eraseHere` erases the cell and halts. The wrapper's own `X → ·/S → halt` edge in the diagram is *never traversed* because control left the wrapper after iteration 1.
 
 > 💡 **The engine's emit could be more user-friendly here.** Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) — the wrapper's duplicated edges and the misleading single-edge `onHalt` placement are candidates for a cleaner `toMermaid` output.
 
 </details>
 
-Wrappers nest: `inner.withOverrodeHaltState(middle).withOverrodeHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
+Wrappers nest: `inner.withOverriddenHaltState(middle).withOverriddenHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
 
 ## Debugging breakpoints
 
@@ -492,7 +492,7 @@ myState.debug = null;
 
 > ⚠️ **`haltState.debug.after` throws.** Halt is terminal — there is no iteration-after-halt for an after-fire to anchor on. Assigning a truthy `.after` to `haltState.debug` (including `{ before: true, after: true }`) throws at write time. Symbol-list filters on `haltState.debug.before` are silent no-ops, since halt has no head symbol; only the wildcard `true` activates.
 
-The `debug` field is mutable — toggle breakpoints at runtime without rebuilding the graph. The internal cell is shared with `state.withOverrodeHaltState(...)` wrappers, so an assignment on the original is visible from every wrapper. `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`.
+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`.
 
 `run()` is async and accepts an `onPause` hook:
 
@@ -617,6 +617,8 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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** *(in progress)* — Composition-representation overhaul. Breaking renames + reshapes scheduled for the v7 cut. Landing piecewise on the `v7` branch; one entry per landed change:
+  - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 
diff --git a/packages/machine/src/classes/State.debug.spec.ts b/packages/machine/src/classes/State.debug.spec.ts
index 13c12d7..2f2938b 100644
--- a/packages/machine/src/classes/State.debug.spec.ts
+++ b/packages/machine/src/classes/State.debug.spec.ts
@@ -90,9 +90,9 @@ describe('State.debug — basics', () => {
     expect(state.debug.after).toBeUndefined();
   });
 
-  test('withOverrodeHaltState returns a new state that shares the debug ref', () => {
+  test('withOverriddenHaltState returns a new state that shares the debug ref', () => {
     const state = makeState();
-    const wrapped = state.withOverrodeHaltState(haltState);
+    const wrapped = state.withOverriddenHaltState(haltState);
 
     expect(wrapped).not.toBe(state);
     // Both lazy-init through the shared ref, so reading either returns the
@@ -110,7 +110,7 @@ describe('State.debug — basics', () => {
   test('null assignment on the original propagates to wrappers (filters reset for both)', () => {
     const state = makeState();
     state.debug = {before: true};
-    const wrapped = state.withOverrodeHaltState(haltState);
+    const wrapped = state.withOverriddenHaltState(haltState);
 
     state.debug = null;
     expect(state.debug.before).toBeUndefined();
@@ -120,7 +120,7 @@ describe('State.debug — basics', () => {
 
   test('setting on the wrapper propagates back to the original', () => {
     const state = makeState();
-    const wrapped = state.withOverrodeHaltState(haltState);
+    const wrapped = state.withOverriddenHaltState(haltState);
 
     wrapped.debug = {after: true};
     expect(state.debug).toBe(wrapped.debug);
@@ -129,8 +129,8 @@ describe('State.debug — basics', () => {
 
   test('chained wrappers all share the SAME debug object (identity)', () => {
     const state = makeState();
-    const w1 = state.withOverrodeHaltState(haltState);
-    const w2 = w1.withOverrodeHaltState(haltState);
+    const w1 = state.withOverriddenHaltState(haltState);
+    const w2 = w1.withOverriddenHaltState(haltState);
 
     state.debug = {before: true};
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index a1df29e..0c4f93f 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -121,19 +121,19 @@ describe('State.getSymbol — head resolution', () => {
   });
 });
 
-describe('State.withOverrodeHaltState', () => {
+describe('State.withOverriddenHaltState', () => {
   // The wrapper shares the original's symbolToDataMap and debugRef but adds
-  // an overrodeHaltState. Audit-flagged: the previous test only checked the
+  // an overriddenHaltState. Audit-flagged: the previous test only checked the
   // name pattern; these tests pin the actual wrapping contract.
 
   test('wrapper exposes the override target', () => {
     const original = new State({[ifOtherSymbol]: {nextState: haltState}});
     const override = new State({[ifOtherSymbol]: {}});
 
-    const wrapped = original.withOverrodeHaltState(override);
+    const wrapped = original.withOverriddenHaltState(override);
 
-    expect(wrapped.overrodeHaltState).toBe(override);
-    expect(original.overrodeHaltState).toBeNull(); // original unchanged
+    expect(wrapped.overriddenHaltState).toBe(override);
+    expect(original.overriddenHaltState).toBeNull(); // original unchanged
   });
 
   test('wrapper proxies getCommand / getNextState to the original transitions', () => {
@@ -143,7 +143,7 @@ describe('State.withOverrodeHaltState', () => {
         nextState: haltState,
       },
     });
-    const wrapped = original.withOverrodeHaltState(haltState);
+    const wrapped = original.withOverriddenHaltState(haltState);
 
     const sym = symbol(['0']);
     expect(wrapped.getCommand(sym)).toBe(original.getCommand(sym));
@@ -152,7 +152,7 @@ describe('State.withOverrodeHaltState', () => {
 
   test('wrapper shares debugRef with the original (assignment on either is visible from both)', () => {
     const original = new State({[ifOtherSymbol]: {}});
-    const wrapped = original.withOverrodeHaltState(haltState);
+    const wrapped = original.withOverriddenHaltState(haltState);
 
     original.debug = {before: true};
 
@@ -166,7 +166,7 @@ describe('State.withOverrodeHaltState', () => {
 
   test('wrapper has its own id (not shared with the original)', () => {
     const original = new State({[ifOtherSymbol]: {}});
-    const wrapped = original.withOverrodeHaltState(haltState);
+    const wrapped = original.withOverriddenHaltState(haltState);
 
     expect(wrapped.id).not.toBe(original.id);
   });
@@ -175,7 +175,7 @@ describe('State.withOverrodeHaltState', () => {
     const original = new State({[ifOtherSymbol]: {}}, 'inner');
     const override = new State({[ifOtherSymbol]: {}}, 'outer');
 
-    const wrapped = original.withOverrodeHaltState(override);
+    const wrapped = original.withOverriddenHaltState(override);
 
     expect(wrapped.name).toBe('inner>outer');
   });
@@ -202,7 +202,7 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
   test('throws when the override-halt graph has a cycle', () => {
     // Graphs constructed by State.toGraph always have acyclic override chains
     // (cycles throw at State construction). To exercise the defensive cycle
-    // detection in fromGraph, hand-build a Graph with overrodeHaltStateId
+    // detection in fromGraph, hand-build a Graph with overriddenHaltStateId
     // pointing in a loop.
     // Nodes need at least one transition each — State construction at pass 2
     // rejects empty stateDefinitions before pass 3's cycle check would run.
@@ -211,9 +211,9 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overrodeHaltStateId: 2},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overrodeHaltStateId: 1},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1},
       },
     };
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 8bb7112..c0da681 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -76,11 +76,11 @@ export default class State {
 
   readonly #name: string;
 
-  #overrodeHaltState: State | null = null;
+  #overriddenHaltState: State | null = null;
 
   #symbolToDataMap = new Map<symbol, { command: Command, nextState: State | Reference }>();
 
-  // Shared mutable cell — withOverrodeHaltState wrappers reference the same
+  // Shared mutable cell — withOverriddenHaltState wrappers reference the same
   // object so that `state.debug = ...` (and nullings) propagate across them.
   // Note: toGraph / fromGraph deliberately do not serialize debug — debug is
   // a runtime concern, not part of the structural graph.
@@ -159,8 +159,8 @@ export default class State {
     return this.#id === 0;
   }
 
-  get overrodeHaltState() {
-    return this.#overrodeHaltState;
+  get overriddenHaltState() {
+    return this.#overriddenHaltState;
   }
 
   get ref() {
@@ -260,11 +260,11 @@ export default class State {
     throw new Error(`No nextState for symbol at state named ${this.#id}`);
   }
 
-  withOverrodeHaltState(overrodeHaltState: State) {
-    const state = new State(null, `${this.name}>${overrodeHaltState.name}`);
+  withOverriddenHaltState(overriddenHaltState: State) {
+    const state = new State(null, `${this.name}>${overriddenHaltState.name}`);
 
     state.#symbolToDataMap = this.#symbolToDataMap;
-    state.#overrodeHaltState = overrodeHaltState;
+    state.#overriddenHaltState = overriddenHaltState;
     state.#debugRef = this.#debugRef;
 
     return state;
@@ -279,7 +279,7 @@ export default class State {
     id: number;
     name: string;
     isHalt: boolean;
-    overrodeHaltState: { id: number; name: string } | null;
+    overriddenHaltState: { id: number; name: string } | null;
     transitions: Array<{
       rawPatternDescription: string | undefined;
       command: Array<{ symbol: string; movement: string }>;
@@ -315,8 +315,8 @@ export default class State {
       id: state.#id,
       name: state.#name,
       isHalt: state.isHalt,
-      overrodeHaltState: state.#overrodeHaltState
-        ? {id: state.#overrodeHaltState.id, name: state.#overrodeHaltState.name}
+      overriddenHaltState: state.#overriddenHaltState
+        ? {id: state.#overriddenHaltState.id, name: state.#overriddenHaltState.name}
         : null,
       transitions,
     };
@@ -339,13 +339,13 @@ export default class State {
         name: current.#name,
         isHalt: current.isHalt,
         transitions: [],
-        overrodeHaltStateId: current.#overrodeHaltState?.id ?? null,
+        overriddenHaltStateId: current.#overriddenHaltState?.id ?? null,
       };
 
       nodes[current.#id] = node;
 
-      if (current.#overrodeHaltState) {
-        queue.push(current.#overrodeHaltState);
+      if (current.#overriddenHaltState) {
+        queue.push(current.#overriddenHaltState);
       }
 
       for (const [sym, {command, nextState}] of current.#symbolToDataMap) {
@@ -468,8 +468,8 @@ export default class State {
 
       let state = bareStates[nodeId];
 
-      if (node.overrodeHaltStateId !== null) {
-        state = bareStates[nodeId].withOverrodeHaltState(getFinal(node.overrodeHaltStateId));
+      if (node.overriddenHaltStateId !== null) {
+        state = bareStates[nodeId].withOverriddenHaltState(getFinal(node.overriddenHaltStateId));
       }
 
       inProgress.delete(nodeId);
diff --git a/packages/machine/src/classes/TuringMachine.debug.spec.ts b/packages/machine/src/classes/TuringMachine.debug.spec.ts
index b77268b..b54e761 100644
--- a/packages/machine/src/classes/TuringMachine.debug.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.debug.spec.ts
@@ -207,7 +207,7 @@ describe('TuringMachine — haltState.debug.before', () => {
       [ifOtherSymbol]: {nextState: haltState},
     });
 
-    const wrapped = inner.withOverrodeHaltState(continuation);
+    const wrapped = inner.withOverriddenHaltState(continuation);
 
     haltState.debug = {before: true};
     const steps: MachineState[] = [];
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index 4232dca..cc138f2 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -151,8 +151,8 @@ export default class TuringMachine {
       const stack = this.#stack;
       let state = initialState;
 
-      if (state.overrodeHaltState) {
-        stack.push(state.overrodeHaltState);
+      if (state.overriddenHaltState) {
+        stack.push(state.overriddenHaltState);
       }
 
       let i = 0;
@@ -217,8 +217,8 @@ export default class TuringMachine {
             nextState = stack.pop()!;
           }
 
-          if (state !== nextState && nextState.overrodeHaltState) {
-            stack.push(nextState.overrodeHaltState);
+          if (state !== nextState && nextState.overriddenHaltState) {
+            stack.push(nextState.overriddenHaltState);
           }
 
           state = nextState;
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index 1116254..db25be3 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -113,9 +113,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
         1: {
-          id: 1, name: 'entry', isHalt: false, overrodeHaltStateId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null,
           transitions: [
             {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1},
             {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0},
@@ -132,13 +132,13 @@ describe('toMermaid', () => {
     expect(out).toContain('s1 -- "1 → ·/S" --> s0');
   });
 
-  test('renders dotted onHalt edge when overrodeHaltStateId is set', () => {
+  test('renders dotted onHalt edge when overriddenHaltStateId is set', () => {
     const out = toMermaid({
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
-        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overrodeHaltStateId: 0},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0},
       },
     });
 
@@ -150,9 +150,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
-        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overrodeHaltStateId: null},
-        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null},
+        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null},
       },
     });
 
@@ -164,9 +164,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0'], [' ', 'a']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
         1: {
-          id: 1, name: 'entry', isHalt: false, overrodeHaltStateId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null,
           transitions: [{
             pattern: '0,a',
             command: [{symbol: '0', movement: 'R'}, {symbol: 'a', movement: 'L'}],
@@ -371,7 +371,7 @@ describe('README diagrams: engine-generated outputs', () => {
     ]);
   });
 
-  test('withOverrodeHaltState BEFORE (scanToX standalone, machine README)', () => {
+  test('withOverriddenHaltState BEFORE (scanToX standalone, machine README)', () => {
     const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
     const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
     const {symbol} = tapeBlock;
@@ -392,7 +392,7 @@ describe('README diagrams: engine-generated outputs', () => {
     ]);
   });
 
-  test('withOverrodeHaltState AFTER (scanThenErase, machine README) — emits the onHalt dotted edge', () => {
+  test('withOverriddenHaltState AFTER (scanThenErase, machine README) — emits the onHalt dotted edge', () => {
     const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
     const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
     const {symbol} = tapeBlock;
@@ -403,7 +403,7 @@ describe('README diagrams: engine-generated outputs', () => {
     const eraseHere = new State({
       [ifOtherSymbol]: {command: {symbol: symbolCommands.erase}, nextState: haltState},
     }, 'eraseHere');
-    const scanThenErase = scanToX.withOverrodeHaltState(eraseHere);
+    const scanThenErase = scanToX.withOverriddenHaltState(eraseHere);
 
     const output = toMermaid(State.toGraph(scanThenErase, tapeBlock));
 
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index 5accdb8..e98c31f 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -13,7 +13,7 @@ export type GraphNode = {
   name: string;
   isHalt: boolean;
   transitions: GraphTransition[];
-  overrodeHaltStateId: number | null;
+  overriddenHaltStateId: number | null;
 };
 
 export type Graph = {
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index a99b29d..17aafbd 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -33,8 +33,8 @@ export function toMermaid(graph: Graph): string {
       lines.push(`  s${node.id} -- "${label}" --> s${t.nextStateId}`);
     }
 
-    if (node.overrodeHaltStateId !== null) {
-      lines.push(`  s${node.id} -. onHalt .-> s${node.overrodeHaltStateId}`);
+    if (node.overriddenHaltStateId !== null) {
+      lines.push(`  s${node.id} -. onHalt .-> s${node.overriddenHaltStateId}`);
     }
   }
 
@@ -75,7 +75,7 @@ export function fromMermaid(text: string): Graph {
         name: opts.name ?? `s${id}`,
         isHalt: opts.isHalt ?? false,
         transitions: [],
-        overrodeHaltStateId: null,
+        overriddenHaltStateId: null,
       };
     } else {
       if (opts.name !== undefined) {
@@ -133,7 +133,7 @@ export function fromMermaid(text: string): Graph {
     const om = line.match(onHaltRegex);
 
     if (om) {
-      ensureNode(Number(om[1])).overrodeHaltStateId = Number(om[2]);
+      ensureNode(Number(om[1])).overriddenHaltStateId = Number(om[2]);
       continue;
     }
 
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 64fdc23..3a7e416 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -7,9 +7,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overrodeHaltStateId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null,
           transitions: [
             {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1},
             {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0},
@@ -31,9 +31,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overrodeHaltStateId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null,
           transitions: [
             {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1},
           ],
@@ -52,9 +52,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overrodeHaltStateId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null,
           transitions: [{pattern: '0', command: [{symbol: '·', movement: 'S'}], nextStateId: 0}],
         },
       },
@@ -72,10 +72,10 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overrodeHaltStateId: 2},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overrodeHaltStateId: 3},
-        3: {id: 3, name: 'c', isHalt: false, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3},
+        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null},
       },
     };
 
@@ -90,8 +90,8 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overrodeHaltStateId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overrodeHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null},
       },
     };
 
@@ -117,7 +117,7 @@ describe('State.inspect', () => {
 
     expect(info.name).toBe('test');
     expect(info.isHalt).toBe(false);
-    expect(info.overrodeHaltState).toBeNull();
+    expect(info.overriddenHaltState).toBeNull();
     expect(info.transitions.length).toBe(2);
 
     const haltTransition = info.transitions.find((t) => t.nextState?.name === haltState.name);
@@ -140,11 +140,11 @@ describe('State.inspect', () => {
     const outer = new State({
       [symbol(['a'])]: {command: {movement: movements.right}, nextState: haltState},
     }, 'outer');
-    const wrapped = inner.withOverrodeHaltState(outer);
+    const wrapped = inner.withOverriddenHaltState(outer);
 
     const info = State.inspect(wrapped);
 
-    expect(info.overrodeHaltState).toEqual({id: outer.id, name: 'outer'});
+    expect(info.overriddenHaltState).toEqual({id: outer.id, name: 'outer'});
   });
 
   test('returns null nextState for unbound References', async () => {
@@ -190,15 +190,15 @@ describe('summarize (binary library comparison)', () => {
 
 describe('summarizeGraph defensive guards', () => {
   // The override-chain walker has a defensive Set guard against cycles.
-  // State construction throws on cyclic overrodeHaltState, so we exercise it
+  // State construction throws on cyclic overriddenHaltState, so we exercise it
   // by handing summarizeGraph a Graph constructed by hand with a cycle.
   test('terminates on a cyclic override chain instead of recursing forever', () => {
     const graph: Graph = {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overrodeHaltStateId: 2},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overrodeHaltStateId: 1},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1},
       },
     };
 
diff --git a/packages/machine/src/utilities/introspection.ts b/packages/machine/src/utilities/introspection.ts
index db0bc8d..ca34c5d 100644
--- a/packages/machine/src/utilities/introspection.ts
+++ b/packages/machine/src/utilities/introspection.ts
@@ -5,7 +5,7 @@ import {type Graph} from './graph';
 // Quantitative summary of a state graph — designed to help a student compare
 // two implementations of the same algorithm and answer questions like:
 //   - "How many states does each version have?"
-//   - "Does either use withOverrodeHaltState composition?"
+//   - "Does either use withOverriddenHaltState composition?"
 //   - "How deep is that composition?"
 //   - "Are there cycles? self-loops?"
 //   - "What's the alphabet size for each tape?"
@@ -24,9 +24,9 @@ export type GraphSummary = {
   stateCount: number;
   transitionCount: number;
 
-  // Composition via withOverrodeHaltState
-  compositionEdgeCount: number;     // states with an overrodeHaltStateId set
-  maxCompositionDepth: number;      // longest chain of withOverrodeHaltState (0 if none)
+  // Composition via withOverriddenHaltState
+  compositionEdgeCount: number;     // states with an overriddenHaltStateId set
+  maxCompositionDepth: number;      // longest chain of withOverriddenHaltState (0 if none)
 
   // Structural
   selfLoopCount: number;            // transitions where nextStateId === own id
@@ -47,7 +47,7 @@ export function summarizeGraph(graph: Graph): GraphSummary {
   for (const node of nodes) {
     transitionCount += node.transitions.length;
 
-    if (node.overrodeHaltStateId !== null) {
+    if (node.overriddenHaltStateId !== null) {
       compositionEdgeCount += 1;
     }
 
@@ -58,7 +58,7 @@ export function summarizeGraph(graph: Graph): GraphSummary {
     }
   }
 
-  // Longest withOverrodeHaltState chain. Walks node → overrodeHaltState recursively;
+  // Longest withOverriddenHaltState chain. Walks node → overriddenHaltState recursively;
   // a Set guards against cycles in the override graph (which throw at construction
   // time anyway, but being defensive costs little).
   const overrideDepthFrom = (id: number, visited: Set<number>): number => {
@@ -70,11 +70,11 @@ export function summarizeGraph(graph: Graph): GraphSummary {
 
     const node = graph.nodes[id];
 
-    if (!node || node.overrodeHaltStateId === null) {
+    if (!node || node.overriddenHaltStateId === null) {
       return 0;
     }
 
-    return 1 + overrideDepthFrom(node.overrodeHaltStateId, visited);
+    return 1 + overrideDepthFrom(node.overriddenHaltStateId, visited);
   };
 
   const maxCompositionDepth = nodes.reduce(
diff --git a/test/examples.spec.ts b/test/examples.spec.ts
index 12a0ec6..8e56890 100644
--- a/test/examples.spec.ts
+++ b/test/examples.spec.ts
@@ -276,9 +276,9 @@ describe('README.md — Building from a state table', () => {
   });
 });
 
-// Pin the withOverrodeHaltState subroutine-composition example from the README.
-describe('README.md — Subroutine composition with withOverrodeHaltState', () => {
-  test('scanToX.withOverrodeHaltState(eraseHere) erases the first X and lands on it', async () => {
+// Pin the withOverriddenHaltState subroutine-composition example from the README.
+describe('README.md — Subroutine composition with withOverriddenHaltState', () => {
+  test('scanToX.withOverriddenHaltState(eraseHere) erases the first X and lands on it', async () => {
     const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
     const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
     const {symbol} = tapeBlock;
@@ -292,7 +292,7 @@ describe('README.md — Subroutine composition with withOverrodeHaltState', () =
       [ifOtherSymbol]: {command: {symbol: symbolCommands.erase}, nextState: haltState},
     }, 'eraseHere');
 
-    const scanThenErase = scanToX.withOverrodeHaltState(eraseHere);
+    const scanThenErase = scanToX.withOverriddenHaltState(eraseHere);
 
     const tape = new Tape({alphabet, symbols: ['a', 'b', 'X', 'b', 'a']});
     tapeBlock.replaceTape(tape);
@@ -303,7 +303,7 @@ describe('README.md — Subroutine composition with withOverrodeHaltState', () =
     expect(tape.position).toBe(2); // head landed where the X used to be
   });
 
-  test('the original scanToX is left unmodified by withOverrodeHaltState', async () => {
+  test('the original scanToX is left unmodified by withOverriddenHaltState', async () => {
     const alphabet = new Alphabet([' ', 'X']);
     const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
     const {symbol} = tapeBlock;
@@ -318,9 +318,9 @@ describe('README.md — Subroutine composition with withOverrodeHaltState', () =
     }, 'eraseHere');
 
     // Wrapping doesn't mutate the original.
-    scanToX.withOverrodeHaltState(eraseHere);
+    scanToX.withOverriddenHaltState(eraseHere);
 
-    expect(scanToX.overrodeHaltState).toBeNull();
+    expect(scanToX.overriddenHaltState).toBeNull();
 
     // Running scanToX standalone (no wrapper) just halts at the X — the
     // X is NOT erased.

From 46637fc2fa3966a75aa240b456767b7d26a8a6c3 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 16:21:12 +0300
Subject: [PATCH 002/118] feat!: paren-based wrapped-state naming (closes #148)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Composition-name format change in `State#withOverriddenHaltState`:
flat `bare>override` → nested `bare(override)`. The old `>`-flat notation
collided structurally-distinct wrap-trees into the same string — e.g.,
`A.with(B.with(A))` and `A.with(B).with(A)` both rendered as "A>B>A".
The paren form keeps them distinct: `A(B(A))` vs `A(B)(A)`.

Changes:

- `State#withOverriddenHaltState` emits paren-format names.
- `State` constructor now rejects user-provided names containing `(`
  or `)` — they're reserved as wrapper-composition delimiters. `>` is
  no longer reserved and is valid in user-provided names again.
- Internal composition paths (`withOverriddenHaltState` and `fromGraph`'s
  wrapper reconstruction) bypass the validation by constructing a State
  with no name and assigning `#name` directly. `#name` lost its
  `readonly` modifier to allow this; access stays inside the class.
- `inspect()`, `toGraph`, `toMermaid` outputs carry the new format
  transparently — name is just a string, no shape change.
- Round-trip name accumulation (#138/#139) still applies in paren form:
  `A(B)` becomes `A(B)(B)` on second round-trip. Tracked separately.

Tests added:

- Distinguishes the two A.with(B).with(A) vs A.with(B.with(A))
  constructions that flat `>` notation collided.
- Constructor throws on names containing `(` or `)`.

Generated artifacts:

- `states.md` for both binary libraries regenerated. Marker library
  gets the new paren format. Bare library has cosmetic ID renumbering
  (no composite names — it doesn't use composition primitives) per
  the build-states-md.mjs header's renumber-is-safe note.

Docs:

- README "Subroutine composition" section + Mermaid example use paren
  format; "Reading guide" gains a one-line note explaining why.
- README "Versioning notes" v7 entry gains a sub-bullet for #148.
- Engine CLAUDE.md narrative on round-trip name accumulation reflects
  the new format.

Out of scope (cross-repo follow-ups, deferred to engine v7 publish):

- post-machine-js — its `Path` parser embeds `>` as the engine's
  wrapper separator (`'foo>10~30'` shape). Needs flip to parens. New
  v7 issue to be opened, separate from #82 (the rename adoption).
- machines-demo — no composition usage; rides peer-dep bump.
---
 CLAUDE.md                                     |  2 +-
 .../library-binary-numbers-bare/states.md     | 44 +++++++++----------
 packages/library-binary-numbers/states.md     | 20 ++++-----
 packages/machine/README.md                    |  7 +--
 packages/machine/src/classes/State.spec.ts    | 30 ++++++++++++-
 packages/machine/src/classes/State.ts         | 24 ++++++++--
 packages/machine/src/utilities/graph.spec.ts  |  2 +-
 7 files changed, 87 insertions(+), 42 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8bf5a1c..04ddcdd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -59,7 +59,7 @@ Key shapes that take reading multiple files to grasp:
 
 ### Visualization & round-trip
 
-`packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same Graph through Mermaid flowchart syntax. The round-trip is **behaviorally** lossless (rebuilt graph runs to same outputs on same inputs — covered by `test/round-trip.spec.ts`); not bytewise lossless because state IDs auto-reassign, and for `withOverriddenHaltState` wrappers the composite name accumulates `>${override.name}` suffixes on each pass. Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) (cleaner emit for wrapped states) + [#139](https://github.com/mellonis/turing-machine-js/issues/139) (regression test that fails until #138 is fixed).
+`packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same Graph through Mermaid flowchart syntax. The round-trip is **behaviorally** lossless (rebuilt graph runs to same outputs on same inputs — covered by `test/round-trip.spec.ts`); not bytewise lossless because state IDs auto-reassign, and for `withOverriddenHaltState` wrappers the composite name accumulates an extra `(${override.name})` wrap on each pass (composite-name format is `bare(override)` since v7 — paren-nested rather than `>`-flat, so nestings like `A(B(A))` vs `A(B)(A)` stay distinguishable). Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) (cleaner emit for wrapped states) + [#139](https://github.com/mellonis/turing-machine-js/issues/139) (regression test that fails until #138 is fixed).
 
 ### Builder package
 
diff --git a/packages/library-binary-numbers-bare/states.md b/packages/library-binary-numbers-bare/states.md
index 6ac5d63..9bcc9e1 100644
--- a/packages/library-binary-numbers-bare/states.md
+++ b/packages/library-binary-numbers-bare/states.md
@@ -8,13 +8,13 @@
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s1["plusOneCarry"]
-  s2(("plusOne"))
-  s1 -- "1 → 0/L" --> s1
-  s1 -- "0 → 1/S" --> s0
-  s1 -- "- → 1/S" --> s0
-  s2 -- "0|1 → ·/R" --> s2
-  s2 -- "- → ·/L" --> s1
+  s27["plusOneCarry"]
+  s28(("plusOne"))
+  s27 -- "1 → 0/L" --> s27
+  s27 -- "0 → 1/S" --> s0
+  s27 -- "- → 1/S" --> s0
+  s28 -- "0|1 → ·/R" --> s28
+  s28 -- "- → ·/L" --> s27
 ```
 
 ## minusOne
@@ -25,13 +25,13 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s3["minusOneBorrow"]
-  s4(("minusOne"))
-  s3 -- "0 → 1/L" --> s3
-  s3 -- "1 → 0/S" --> s0
-  s3 -- "- → ·/S" --> s0
-  s4 -- "0|1 → ·/R" --> s4
-  s4 -- "- → ·/L" --> s3
+  s29["minusOneBorrow"]
+  s30(("minusOne"))
+  s29 -- "0 → 1/L" --> s29
+  s29 -- "1 → 0/S" --> s0
+  s29 -- "- → ·/S" --> s0
+  s30 -- "0|1 → ·/R" --> s30
+  s30 -- "- → ·/L" --> s29
 ```
 
 ## invertNumber
@@ -42,10 +42,10 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s5(("invertNumber"))
-  s5 -- "0 → 1/R" --> s5
-  s5 -- "1 → 0/R" --> s5
-  s5 -- "- → ·/S" --> s0
+  s31(("invertNumber"))
+  s31 -- "0 → 1/R" --> s31
+  s31 -- "1 → 0/R" --> s31
+  s31 -- "- → ·/S" --> s0
 ```
 
 ## normalizeNumber
@@ -56,8 +56,8 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s6(("normalizeNumber"))
-  s6 -- "0 → ⌫/R" --> s6
-  s6 -- "1 → ·/S" --> s0
-  s6 -- "- → 0/S" --> s0
+  s32(("normalizeNumber"))
+  s32 -- "0 → ⌫/R" --> s32
+  s32 -- "1 → ·/S" --> s0
+  s32 -- "- → 0/S" --> s0
 ```
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 81eb3a6..6918c8e 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -53,7 +53,7 @@ flowchart TD
   s0(((halt)))
   s5["goToNumberStart"]
   s6["deleteNumberInternal"]
-  s7["goToNumberStart>deleteNumberInternal"]
+  s7["goToNumberStart(deleteNumberInternal)"]
   s8(("deleteNumber"))
   s5 -- "^ → ·/S" --> s0
   s5 -- "* → ·/L" --> s5
@@ -89,7 +89,7 @@ flowchart TD
   s0(((halt)))
   s5["goToNumberStart"]
   s9["invertNumberGoToNumberWithInversion"]
-  s10["goToNumberStart>invertNumberGoToNumberWithInversion"]
+  s10["goToNumberStart(invertNumberGoToNumberWithInversion)"]
   s11(("invertNumber"))
   s5 -- "^ → ·/S" --> s0
   s5 -- "* → ·/L" --> s5
@@ -116,7 +116,7 @@ flowchart TD
   s5["goToNumberStart"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
-  s14["goToNumberStart>normalizeNumberMoveNumberStart"]
+  s14["goToNumberStart(normalizeNumberMoveNumberStart)"]
   s15(("normalizeNumber"))
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
@@ -167,18 +167,18 @@ flowchart TD
   s1["goToNumber"]
   s5["goToNumberStart"]
   s9["invertNumberGoToNumberWithInversion"]
-  s10["goToNumberStart>invertNumberGoToNumberWithInversion"]
+  s10["goToNumberStart(invertNumberGoToNumberWithInversion)"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
-  s14["goToNumberStart>normalizeNumberMoveNumberStart"]
+  s14["goToNumberStart(normalizeNumberMoveNumberStart)"]
   s15["normalizeNumber"]
   s16["plusOneFillZeros"]
   s17["plusOneAddNumberStart"]
   s18["plusOneCaryOne"]
   s19["plusOne"]
-  s20["invertNumber>normalizeNumber"]
-  s21["plusOne>invertNumber>normalizeNumber"]
-  s22["invertNumber>plusOne>invertNumber>normalizeNumber"]
+  s20["invertNumber(normalizeNumber)"]
+  s21["plusOne(invertNumber(normalizeNumber))"]
+  s22["invertNumber(plusOne(invertNumber(normalizeNumber)))"]
   s23(("minusOne"))
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
@@ -236,10 +236,10 @@ flowchart TD
   s5["goToNumberStart"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
-  s14["goToNumberStart>normalizeNumberMoveNumberStart"]
+  s14["goToNumberStart(normalizeNumberMoveNumberStart)"]
   s15["normalizeNumber"]
   s24["minusOneFastBorrow"]
-  s25["minusOneFastBorrow>normalizeNumber"]
+  s25["minusOneFastBorrow(normalizeNumber)"]
   s26(("minusOneFast"))
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 12498bd..78a2be8 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -279,7 +279,7 @@ flowchart TD
 
 > 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
 
-`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). It is *not* bytewise lossless: state IDs auto-reassign on each rebuild, and for `withOverriddenHaltState` wrappers the composite name gains a `>${override.name}` suffix on each pass (e.g., `scanToX>eraseHere` becomes `scanToX>eraseHere>eraseHere` on a second round-trip — tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138)).
+`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). It is *not* bytewise lossless: state IDs auto-reassign on each rebuild, and for `withOverriddenHaltState` wrappers the composite name gains an extra `(${override.name})` wrapping on each pass (e.g., `scanToX(eraseHere)` becomes `scanToX(eraseHere)(eraseHere)` on a second round-trip — tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138)).
 
 ### Reference
 
@@ -442,7 +442,7 @@ flowchart TD
   s0(((halt)))
   s1["scanToX"]
   s2["eraseHere"]
-  s3(("scanToX>eraseHere"))
+  s3(("scanToX(eraseHere)"))
   s1 -- "X → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
   s2 -- "* → ⌫/S" --> s0
@@ -453,7 +453,7 @@ flowchart TD
 
 **Reading guide** — the wrapped diagram is denser than the simplified hand-drawn version above. To parse it:
 
-1. **Three non-halt nodes:** the wrapper `scanToX>eraseHere` (round, the initial state); `scanToX` (square, the original subroutine — unmodified); `eraseHere` (square, the override target). The wrapper appears as a *separate* state from `scanToX`-the-original because `withOverriddenHaltState` returns a new `State` instance — even though it shares the transition map.
+1. **Three non-halt nodes:** the wrapper `scanToX(eraseHere)` (round, the initial state); `scanToX` (square, the original subroutine — unmodified); `eraseHere` (square, the override target). The wrapper appears as a *separate* state from `scanToX`-the-original because `withOverriddenHaltState` returns a new `State` instance — even though it shares the transition map. The composite-name format is `bare(override)` — chosen so nested wrappers stay unambiguous: `A.with(B.with(A))` produces `A(B(A))` while `A.with(B).with(A)` produces `A(B)(A)`, two different runtime shapes that flat `A>B>A` notation collided.
 2. **Solid edges from the wrapper duplicate `scanToX`'s edges.** That's because the wrapper inherits the same `symbolToDataMap`. Importantly, the wrapper's `* → ·/R` edge points at *`scanToX`-the-original*, not at the wrapper itself — so after the first iteration, control transfers to `scanToX` and stays there.
 3. **The dotted `onHalt` edge is attached to the wrapper** but it doesn't fire on a single edge at runtime. Instead, the runtime pushes `eraseHere` onto an internal stack at startup, and *any* halt-bound transition reachable during the run (whether on the wrapper itself or on `scanToX`) gets redirected to `eraseHere` via stack-pop. The dotted edge is the engine's static fingerprint of "this graph was wrapped by `withOverriddenHaltState`."
 4. **What actually fires at runtime, on tape `['a','b','X','b','a']`:** the wrapper runs once, transferring to `scanToX`; `scanToX` self-loops on `* → ·/R` until it sees `X`; the `X → ·/S` edge tries to go to halt; the runtime pops `eraseHere` off the stack and substitutes it; `eraseHere` erases the cell and halts. The wrapper's own `X → ·/S → halt` edge in the diagram is *never traversed* because control left the wrapper after iteration 1.
@@ -619,6 +619,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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** *(in progress)* — Composition-representation overhaul. Breaking renames + reshapes scheduled for the v7 cut. Landing piecewise on the `v7` branch; one entry per landed change:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
+  - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly. Round-trip name accumulation in `withOverriddenHaltState` chains stays present in paren form — `A(B)` becomes `A(B)(B)` on second round-trip — tracked separately in [#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139).
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 0c4f93f..ac8069b 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -93,6 +93,14 @@ describe('State constructor — invalid inputs', () => {
       [symbol(['0'])]: {command: [] as never, nextState: haltState},
     })).toThrow('invalid command');
   });
+
+  test('throws when user-provided name contains `(`', () => {
+    expect(() => new State(null, 'foo(bar')).toThrow(/invalid state name/);
+  });
+
+  test('throws when user-provided name contains `)`', () => {
+    expect(() => new State(null, 'foo)bar')).toThrow(/invalid state name/);
+  });
 });
 
 describe('State.getCommand / .getNextState — error paths', () => {
@@ -171,13 +179,31 @@ describe('State.withOverriddenHaltState', () => {
     expect(wrapped.id).not.toBe(original.id);
   });
 
-  test('wrapper name encodes the override target', () => {
+  test('wrapper name encodes the override target as `bare(override)`', () => {
     const original = new State({[ifOtherSymbol]: {}}, 'inner');
     const override = new State({[ifOtherSymbol]: {}}, 'outer');
 
     const wrapped = original.withOverriddenHaltState(override);
 
-    expect(wrapped.name).toBe('inner>outer');
+    expect(wrapped.name).toBe('inner(outer)');
+  });
+
+  test('paren-naming distinguishes nestings that flat `>` notation would collide', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const B = new State({[ifOtherSymbol]: {}}, 'B');
+
+    // Construction 1: bare=A, override=(B with override A)
+    const inner1 = B.withOverriddenHaltState(A);
+    const outer1 = A.withOverriddenHaltState(inner1);
+
+    // Construction 2: bare=(A with override B), override=A
+    const inner2 = A.withOverriddenHaltState(B);
+    const outer2 = inner2.withOverriddenHaltState(A);
+
+    // Old `>` notation would collide both at "A>B>A". Paren notation keeps them distinct.
+    expect(outer1.name).toBe('A(B(A))');
+    expect(outer2.name).toBe('A(B)(A)');
+    expect(outer1.name).not.toBe(outer2.name);
   });
 });
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index c0da681..3d4b4ec 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -74,7 +74,10 @@ export class DebugConfig {
 export default class State {
   readonly #id: number = id(this);
 
-  readonly #name: string;
+  // Not `readonly` because `withOverriddenHaltState` and `fromGraph` set the
+  // composed name on a no-arg `new State()` to bypass the constructor's
+  // user-facing name validation (composite names contain `(` and `)`).
+  #name: string;
 
   #overriddenHaltState: State | null = null;
 
@@ -144,6 +147,10 @@ export default class State {
       });
     }
 
+    if (name !== undefined && /[()]/.test(name)) {
+      throw new Error(`invalid state name "${name}": must not contain '(' or ')' (reserved as wrapper-composition delimiters in withOverriddenHaltState)`);
+    }
+
     this.#name = name ?? `id:${this.#id}`;
   }
 
@@ -261,8 +268,13 @@ export default class State {
   }
 
   withOverriddenHaltState(overriddenHaltState: State) {
-    const state = new State(null, `${this.name}>${overriddenHaltState.name}`);
+    // Construct with no name, then overwrite #name directly — the composed
+    // name contains `(` and `)` by design, which the constructor's user-facing
+    // validation would reject. Internal composition bypasses validation via
+    // private-field access (legal within the same class).
+    const state = new State();
 
+    state.#name = `${this.name}(${overriddenHaltState.name})`;
     state.#symbolToDataMap = this.#symbolToDataMap;
     state.#overriddenHaltState = overriddenHaltState;
     state.#debugRef = this.#debugRef;
@@ -440,7 +452,13 @@ export default class State {
         };
       }
 
-      bareStates[nodeId] = new State(stateDefinition, node.name);
+      // Graph-sourced names may contain `(` and `)` (composite wrapper names
+      // emitted by toGraph). Bypass the constructor's user-facing name
+      // validation by constructing without a name and assigning #name directly.
+      const bare = new State(stateDefinition);
+
+      bare.#name = node.name;
+      bareStates[nodeId] = bare;
     }
 
     // Pass 3: apply overrideHaltStates transitively.
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index db25be3..ad646a6 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -413,7 +413,7 @@ describe('README diagrams: engine-generated outputs', () => {
       '(((halt)))',
       '["scanToX"]', // original scanToX is reachable from the wrapper → square
       '["eraseHere"]', // eraseHere is reachable via onHalt → square
-      '(("scanToX>eraseHere"))', // wrapper is the initial state → round
+      '(("scanToX(eraseHere)"))', // wrapper is the initial state → round
       '"* → ⌫/S"', // eraseHere's erase command
       '-. onHalt .->', // the dotted override-halt edge — engine's static fingerprint of the override
     ]);

From 50f052f925cfff612388e1f8fbf23c041da0c868 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 16:58:53 +0300
Subject: [PATCH 003/118] chore(scripts): isolate per-library state-id counters
 in docs:states
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spawn one child Node process per library so each starts from a fresh
`State` id counter. Without isolation, the second-imported library's
IDs depend on how many states the first-imported one constructed —
adding a state to one library would shift every ID label in the other
library's `states.md`, creating cross-coupled diff churn.

Net effect on this PR's diff:
- `packages/library-binary-numbers-bare/states.md` reverts to its
  v3.0.0 numbering (s1–s6). The "cosmetic ID renumbering" called out
  in the prior commit's body is undone here — the bare library now
  has zero net change from master.
- `packages/library-binary-numbers/states.md` unchanged (marker
  library imports as it always did at top of dispatcher; isolation
  doesn't change its numbering).

Single-file structure: argv-gated dispatcher / worker pattern. No
top-level library imports — only the worker branch's dynamic import
loads a library, and it loads only the one it was asked to render.
---
 .../library-binary-numbers-bare/states.md     | 44 +++++-----
 scripts/build-states-md.mjs                   | 81 ++++++++++++-------
 2 files changed, 72 insertions(+), 53 deletions(-)

diff --git a/packages/library-binary-numbers-bare/states.md b/packages/library-binary-numbers-bare/states.md
index 9bcc9e1..6ac5d63 100644
--- a/packages/library-binary-numbers-bare/states.md
+++ b/packages/library-binary-numbers-bare/states.md
@@ -8,13 +8,13 @@
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s27["plusOneCarry"]
-  s28(("plusOne"))
-  s27 -- "1 → 0/L" --> s27
-  s27 -- "0 → 1/S" --> s0
-  s27 -- "- → 1/S" --> s0
-  s28 -- "0|1 → ·/R" --> s28
-  s28 -- "- → ·/L" --> s27
+  s1["plusOneCarry"]
+  s2(("plusOne"))
+  s1 -- "1 → 0/L" --> s1
+  s1 -- "0 → 1/S" --> s0
+  s1 -- "- → 1/S" --> s0
+  s2 -- "0|1 → ·/R" --> s2
+  s2 -- "- → ·/L" --> s1
 ```
 
 ## minusOne
@@ -25,13 +25,13 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s29["minusOneBorrow"]
-  s30(("minusOne"))
-  s29 -- "0 → 1/L" --> s29
-  s29 -- "1 → 0/S" --> s0
-  s29 -- "- → ·/S" --> s0
-  s30 -- "0|1 → ·/R" --> s30
-  s30 -- "- → ·/L" --> s29
+  s3["minusOneBorrow"]
+  s4(("minusOne"))
+  s3 -- "0 → 1/L" --> s3
+  s3 -- "1 → 0/S" --> s0
+  s3 -- "- → ·/S" --> s0
+  s4 -- "0|1 → ·/R" --> s4
+  s4 -- "- → ·/L" --> s3
 ```
 
 ## invertNumber
@@ -42,10 +42,10 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s31(("invertNumber"))
-  s31 -- "0 → 1/R" --> s31
-  s31 -- "1 → 0/R" --> s31
-  s31 -- "- → ·/S" --> s0
+  s5(("invertNumber"))
+  s5 -- "0 → 1/R" --> s5
+  s5 -- "1 → 0/R" --> s5
+  s5 -- "- → ·/S" --> s0
 ```
 
 ## normalizeNumber
@@ -56,8 +56,8 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s32(("normalizeNumber"))
-  s32 -- "0 → ⌫/R" --> s32
-  s32 -- "1 → ·/S" --> s0
-  s32 -- "- → 0/S" --> s0
+  s6(("normalizeNumber"))
+  s6 -- "0 → ⌫/R" --> s6
+  s6 -- "1 → ·/S" --> s0
+  s6 -- "- → 0/S" --> s0
 ```
diff --git a/scripts/build-states-md.mjs b/scripts/build-states-md.mjs
index 05abcf1..8918dd8 100644
--- a/scripts/build-states-md.mjs
+++ b/scripts/build-states-md.mjs
@@ -6,24 +6,61 @@
 // imports from `dist/`). Not run during tests; doc artifacts are committed to
 // the repo and regenerated manually when the libraries' state graphs change.
 //
-// Heads-up: state IDs are auto-assigned at module-evaluation time (`State.ts`'s
-// `id(this)` increments a module-level counter). Re-running this script will
-// produce a deterministic-but-different ID renumbering if the import order or
-// other consumers shift; the resulting diff is cosmetic — only the `s<N>`
-// labels move, the graph topology is identical. If a renumber-only diff
-// surfaces during a refresh, it's safe to commit.
+// Per-library isolation: state IDs are auto-assigned by a module-level counter
+// in `State.ts`. If both libraries are imported into the same Node process, the
+// counter is shared and the second-imported library's IDs depend on how many
+// states the first-imported one constructed — adding a state to one library
+// shifts every ID in the other library's states.md. To avoid that cross-
+// coupling, each library is rendered in its own child Node process spawned by
+// this script, so each starts from a fresh counter.
 
+import {spawnSync} from 'node:child_process';
 import {writeFileSync} from 'node:fs';
 import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {State, toMermaid} from '../packages/machine/dist/index.mjs';
-import binaryNumbers from '../packages/library-binary-numbers/dist/index.mjs';
-import binaryNumbersBare from '../packages/library-binary-numbers-bare/dist/index.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const scriptPath = fileURLToPath(import.meta.url);
 
-function renderLibrary(libraryName, library) {
-  const sections = [`# ${libraryName} — state graphs`, ''];
+const LIBRARIES = [
+  {
+    name: 'library-binary-numbers',
+    importPath: '../packages/library-binary-numbers/dist/index.mjs',
+    outputPath: resolve(root, 'packages/library-binary-numbers/states.md'),
+  },
+  {
+    name: 'library-binary-numbers-bare',
+    importPath: '../packages/library-binary-numbers-bare/dist/index.mjs',
+    outputPath: resolve(root, 'packages/library-binary-numbers-bare/states.md'),
+  },
+];
+
+const libArgIx = process.argv.indexOf('--lib');
+const libName = libArgIx === -1 ? null : process.argv[libArgIx + 1];
+
+if (libName === null) {
+  // Dispatcher mode: one child per library, fresh State id counter in each.
+  for (const {name} of LIBRARIES) {
+    const r = spawnSync(process.execPath, [scriptPath, '--lib', name], {stdio: 'inherit'});
+
+    if (r.status !== 0) {
+      process.exit(r.status ?? 1);
+    }
+  }
+} else {
+  // Worker mode: render exactly one library. Spawned by the dispatcher above
+  // so the State id counter starts fresh for this library's import.
+  const entry = LIBRARIES.find((l) => l.name === libName);
+
+  if (!entry) {
+    console.error(`build-states-md: unknown library "${libName}"`);
+    process.exit(1);
+  }
+
+  const {State, toMermaid} = await import('../packages/machine/dist/index.mjs');
+  const library = (await import(entry.importPath)).default;
+
+  const sections = [`# ${entry.name} — state graphs`, ''];
 
   for (const [stateName, state] of Object.entries(library.states)) {
     const tapeBlock = library.getTapeBlock();
@@ -41,24 +78,6 @@ function renderLibrary(libraryName, library) {
     sections.push('');
   }
 
-  return sections.join('\n');
-}
-
-const libraries = [
-  {
-    libraryName: 'library-binary-numbers',
-    library: binaryNumbers,
-    outputPath: resolve(root, 'packages/library-binary-numbers/states.md'),
-  },
-  {
-    libraryName: 'library-binary-numbers-bare',
-    library: binaryNumbersBare,
-    outputPath: resolve(root, 'packages/library-binary-numbers-bare/states.md'),
-  },
-];
-
-for (const {libraryName, library, outputPath} of libraries) {
-  const content = renderLibrary(libraryName, library);
-  writeFileSync(outputPath, content);
-  console.log(`✓ Wrote ${outputPath}`);
+  writeFileSync(entry.outputPath, sections.join('\n'));
+  console.log(`✓ Wrote ${entry.outputPath}`);
 }

From a8016d5b9ba8d5f4089b8221adc7ab64a4a7d767 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 18:56:04 +0300
Subject: [PATCH 004/118] feat!: cleaner `toMermaid` emit for wrapped states
 (closes #138, closes #139)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

v7 emit overhaul for `withOverriddenHaltState`-wrapped states. Per design
discussion in #138 and the spec at
docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md.

Visual contract:

- `subgraph w_${bareId}["halt frame"]` around each wrapper = the
  wrapper's runtime stack frame for halt handling. Visual-only — no
  edge mutations.
- `[[bare]]` (Mermaid subroutine / double-walled rectangle) = the
  wrapper-node. Both the runtime entry point AND the source of the
  dotted `onHalt` edge.
- Cloned `(((halt)))` inside the subgraph = where halt-bound
  transitions land within the wrapper's scope. `haltState` is a
  runtime singleton; the cloned node is a teaching aid.
- Solid edges from `[[bare]]` to cloned halt stay inside the
  subgraph. Dotted `onHalt` from `[[bare]]` crosses the subgraph
  border to the override target — exactly one per wrapper.
- Real `(((halt)))` outside any subgraph = actual run terminus.

Graph data model changes:

- `GraphNode` gains `isWrapped: boolean` and `isClonedHalt: boolean`.
- `GraphTransition` gains a stable per-edge `id: string`
  (`${fromNodeId}-${patternIx}`) for downstream rendering (e.g.
  `machines-demo` #10's edge-highlighting).
- `State` gains a private `#bareState` ref populated in
  `withOverriddenHaltState` so `toGraph` can recover the bare from
  a wrapper.
- Cloned-halt graph nodes use negative ids (one per wrapper); in
  Mermaid output they emit as `c${absId}` to satisfy Mermaid's id
  syntax. `fromGraph` maps them back to the singleton `haltState`.

Round-trip:

- Closes #139: bytewise-stable round-trip for simple wrappers (test
  added in test/round-trip.spec.ts). The wrapper's composite name no
  longer appears as a graph node label — only the bare's name does —
  so `fromGraph` recomputes the composite fresh on reconstruction;
  no accumulation.
- Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use
  per-context duplication in the graph emit. Reconstruction produces
  behaviorally-equivalent State instances. Bytewise round-trip for
  shared-bare cases is a known limitation outside #139's scope.

Mermaid emit is sorted deterministically (nodes by id ascending,
transitions per-node in stored order) to support the round-trip
test and reduce diff churn in `states.md`.

Downstream support for `machines-demo` #9 (graph render) / #10 (next-
edge highlight) / #37 (click-to-toggle breakpoints): stable per-node
ids, `isWrapped` / `isClonedHalt` flags so downstream can style or
skip cloned halts, edge ids for SVG targeting.

Other updates:

- README "Subroutine composition" section rewritten with the new
  diagram + reader's contract.
- README "Versioning notes" v7 entry gains a sub-bullet for this PR.
- `states.md` regenerated for `library-binary-numbers`.
- Existing pinned-Mermaid-output assertions in graph.spec.ts /
  introspection.spec.ts / State.spec.ts updated for the new shape.
---
 ...026-05-20-tomermaid-wrapper-emit-design.md | 373 ++++++++++++++++++
 .../library-binary-numbers/src/graphs.spec.ts |  24 +-
 packages/library-binary-numbers/states.md     | 113 +++---
 packages/machine/README.md                    |  30 +-
 packages/machine/src/classes/State.spec.ts    |   8 +-
 packages/machine/src/classes/State.ts         | 208 +++++++++-
 packages/machine/src/utilities/graph.spec.ts  |  36 +-
 packages/machine/src/utilities/graph.ts       |  13 +
 .../machine/src/utilities/graphFormats.ts     | 195 +++++++--
 .../src/utilities/introspection.spec.ts       |  36 +-
 test/round-trip.spec.ts                       |  50 +++
 11 files changed, 927 insertions(+), 159 deletions(-)
 create mode 100644 docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md

diff --git a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
new file mode 100644
index 0000000..01c5536
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
@@ -0,0 +1,373 @@
+# `toMermaid` wrapped-state emit — design comparison
+
+**Status:** decided — **Variant X with `subgraph` overlay**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))` (visualizing where halt-bound execution lands inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation underway on the `feat/cleaner-wrapper-emit-138` branch.
+
+**Context.** [#138](https://github.com/mellonis/turing-machine-js/issues/138) — clean up the visually-confusing Mermaid output for `withOverriddenHaltState`-wrapped states. [#139](https://github.com/mellonis/turing-machine-js/issues/139) — bytewise round-trip regression for the wrapper name accumulation, naturally fixed by whichever design we pick.
+
+Three live variants below — paste the fenced ` ```mermaid ` blocks into anything that renders Mermaid (GitHub preview, mermaid.live, IDE plugin).
+
+---
+
+## Baseline: current v7 emit
+
+The shape we'd be replacing. Composite name flipped to paren form in [#168](https://github.com/mellonis/turing-machine-js/pull/168), still has all the readability problems #138 calls out: wrapper duplicates the bare's edges, dotted-edge attached to the wrong node visually, three non-halt nodes for what's conceptually a 2-step composition.
+
+Single wrapper — `scanToX.withOverriddenHaltState(eraseHere)`:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1["scanToX"]
+  s2["eraseHere"]
+  s3(("scanToX(eraseHere)"))
+  s1 -- "X → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s2 -- "* → ⌫/S" --> s0
+  s3 -- "X → ·/S" --> s0
+  s3 -- "* → ·/R" --> s1
+  s3 -. onHalt .-> s2
+```
+
+Nested — `A.withOverriddenHaltState(B.withOverriddenHaltState(C))` (placeholder transitions):
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  s1["A"]
+  s2["B"]
+  s3["C"]
+  s4["B(C)"]
+  s5(("A(B(C))"))
+  s1 -- "..." --> s0
+  s2 -- "..." --> s0
+  s3 -- "..." --> s0
+  s4 -- "..." --> s2
+  s5 -- "..." --> s1
+  s4 -. onHalt .-> s3
+  s5 -. onHalt .-> s4
+```
+
+---
+
+## Variant X — shape on the bare, no extra wrapper node
+
+The wrapped state is signalled by **shape only**: `[[name]]` (subroutine, double-walled rectangle) on the bare. The wrapper node is not emitted at all — its identity collapses into the bare's. A dotted `onHalt` edge runs directly from the bare to the override target.
+
+Single wrapper:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1[["scanToX"]]
+  s2["eraseHere"]
+  s1 -- "X → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s2 -- "* → ⌫/S" --> s0
+  s1 -. onHalt .-> s2
+```
+
+Nested — each wrapped state's bare gets `[[…]]`:
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  s1[["A"]]
+  s2[["B"]]
+  s3["C"]
+  s1 -- "..." --> s0
+  s2 -- "..." --> s0
+  s3 -- "..." --> s0
+  s1 -. onHalt .-> s2
+  s2 -. onHalt .-> s3
+```
+
+**Shared-bare case** — `minusOne` in `library-binary-numbers` is `invertNumber.with(plusOne.with(invertNumber.with(normalizeNumber)))`. The same `invertNumber` instance is the bare of two wrappers. In Variant X this is fine — `invertNumber` is one node, its `[[…]]` shape says "I'm wrapped in this context", and the dotted edge from it points at the relevant override:
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  s1[["invertNumber"]]
+  s2["plusOne"]
+  s3["normalizeNumber"]
+  s1 -- "..." --> s0
+  s2 -- "..." --> s0
+  s3 -- "..." --> s0
+  s1 -. onHalt .-> s2
+```
+
+(Only the outermost wrapper is shown — `minusOne = invertNumber.with(W2)` — because that's what the caller passed to `toGraph`. Nested wrappers inside `W2` get their own `[[…]]` shapes and dotted edges as the walk descends.)
+
+**Round-trip.** Graph carries only the bare's name; wrapper's composite name (`scanToX(eraseHere)`) does **not** appear in any graph node. `fromGraph` reconstructs via `bare.withOverriddenHaltState(override)` which recomputes the composite name fresh — no name accumulation, fixes [#139](https://github.com/mellonis/turing-machine-js/issues/139) automatically.
+
+**Pros.** Minimal change. No extra nodes. Handles shared-bare cleanly (one node, one shape). Round-trip trivially stable.
+**Cons.** Keeps the dotted-edge convention (some find it non-obvious). The wrapped-vs-not distinction lives in the node SHAPE rather than as a tangible halt-redirect joint.
+
+---
+
+## Variant Y₁ — pseudo-halt node per wrapper, with per-context duplication
+
+The wrapper becomes a real node in the graph (sentinel label `~halt`, shape `[[…]]`). The bare's halt-bound transitions are **rewritten in the emit** to point at the pseudo-halt instead of at real halt. The pseudo-halt has a solid outgoing edge to the override. Most faithful to the runtime semantics — the wrapper IS the halt-redirect joint, and the graph makes that tangible.
+
+Single wrapper:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1(("scanToX"))
+  ph1[["~halt"]]
+  s2["eraseHere"]
+  s1 -- "X → ·/S" --> ph1
+  s1 -- "* → ·/R" --> s1
+  ph1 --> s2
+  s2 -- "* → ⌫/S" --> s0
+```
+
+Nested:
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  s1(("A"))
+  ph1[["~halt"]]
+  s2["B"]
+  ph2[["~halt"]]
+  s3["C"]
+  s1 -- "..." --> ph1
+  ph1 --> s2
+  s2 -- "..." --> ph2
+  ph2 --> s3
+  s3 -- "..." --> s0
+```
+
+**Shared-bare case — the problem.** `minusOne` again: the same `invertNumber` instance is bare of W3 (outermost) and bare of W1 (innermost). In W3's wrapper context, its halt-bound transitions must rewrite to `ph_W3`; in W1's context, they must rewrite to `ph_W1`. Different rewrites in different contexts → **the state must be emitted twice as different nodes** (`s1` and `s4` below), or we lose the distinct halt-rewrite per wrapper.
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  s1(("invertNumber"))
+  ph_W3[["~halt"]]
+  s4["invertNumber (duplicate, in W1 context)"]
+  ph_W1[["~halt"]]
+  s2["plusOne"]
+  ph_W2[["~halt"]]
+  s3["normalizeNumber"]
+  s1 -- "..." --> ph_W3
+  ph_W3 --> s2
+  s2 -- "..." --> ph_W2
+  ph_W2 --> s4
+  s4 -- "..." --> ph_W1
+  ph_W1 --> s3
+  s3 -- "..." --> s0
+```
+
+`fromGraph` needs to recognize the duplication and merge the two `invertNumber` copies back into one State instance at reconstruction. Possible but non-trivial.
+
+**Pros.** Runtime-faithful — the wrapper appears as a concrete redirect step in the graph. No dotted-edge convention.
+**Cons.** State duplication for shared-bare cases (common in the library). Significantly more parser + reconstruction logic in `fromMermaid` and `fromGraph` to handle duplication + merge. Strictly more nodes in the emit.
+
+---
+
+## Variant Y₂ — pseudo-halt as an additional node (no rewriting; keeps dotted edge)
+
+A compromise: the pseudo-halt appears as a node with shape `[[~halt]]` and a **solid** outgoing edge to the override, but the bare's halt-bound transitions are **not** rewritten — they still point at real halt. The dotted `onHalt` edge runs from the bare to the pseudo-halt (replacing the current dotted-to-override edge). The pseudo-halt visualizes "the wrapper's redirect joint" without requiring per-context rewriting.
+
+Single wrapper:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1(("scanToX"))
+  s2["eraseHere"]
+  ph1[["~halt"]]
+  s1 -- "X → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s1 -. onHalt .-> ph1
+  ph1 --> s2
+  s2 -- "* → ⌫/S" --> s0
+```
+
+Nested:
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  s1(("A"))
+  s2["B"]
+  s3["C"]
+  ph1[["~halt"]]
+  ph2[["~halt"]]
+  s1 -- "..." --> s0
+  s2 -- "..." --> s0
+  s3 -- "..." --> s0
+  s1 -. onHalt .-> ph1
+  ph1 --> s2
+  s2 -. onHalt .-> ph2
+  ph2 --> s3
+```
+
+**Shared-bare case** — no duplication needed; `invertNumber` is one node, with one dotted `onHalt` edge to one pseudo-halt:
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  s1(("invertNumber"))
+  s2["plusOne"]
+  s3["normalizeNumber"]
+  ph_outer[["~halt"]]
+  s1 -- "..." --> s0
+  s2 -- "..." --> s0
+  s3 -- "..." --> s0
+  s1 -. onHalt .-> ph_outer
+  ph_outer --> s2
+```
+
+(Inner wrappers handled by recursion — each gets its own pseudo-halt node, dotted edge from its bare.)
+
+**Pros.** Pseudo-halt visualized as a tangible step. No state duplication. Modest implementation cost.
+**Cons.** Keeps the dotted-edge convention, just shifts what the dotted edge points at (bare → pseudo, instead of bare → override). One extra node per wrapper.
+
+---
+
+## Comparison table
+
+| Concern | Baseline (current) | X (shape-on-bare) | Y₁ (rewriting pseudo) | Y₂ (additional pseudo) |
+|---|---|---|---|---|
+| Wrapper node duplicates bare's edges | ❌ yes | n/a (no wrapper node) | ✅ no | ✅ no |
+| Dotted-edge convention | ✅ used | ✅ used (bare → override) | ❌ removed | ✅ used (bare → pseudo) |
+| Extra nodes per wrapper level | 1 (wrapper) | 0 | 1 (pseudo) | 1 (pseudo) |
+| Shared-bare handling | ✅ single node | ✅ single node | ❌ duplicate per context | ✅ single node |
+| Round-trip stability ([#139](https://github.com/mellonis/turing-machine-js/issues/139)) | ❌ accumulates `(override)` | ✅ trivially stable | ✅ stable if dedup works | ✅ stable |
+| Implementation surface | n/a | small | large (per-context walk, dedup) | medium |
+| Faithfulness to runtime semantics | medium (composite name embedded) | medium (shape conveys it) | ✅ high (pseudo IS the joint) | medium-high (pseudo visible but no rewrite) |
+
+---
+
+## Recommendation
+
+**Y₂ if you want the pseudo-halt visualized as a node**; **X if you want the smallest possible change.**
+
+Y₁ is the most faithful but the cost of per-context state duplication in `fromGraph` is high for limited additional clarity over Y₂.
+
+---
+
+## Final locked design (Variant X with `subgraph` overlay)
+
+After iteration, the locked shape evolves Variant X (collapse the wrapper into the bare's representation, no extra "wrapper node" in the graph data) with two visualization-only enhancements that make the wrapper's runtime semantics tangible without mutating the graph structure:
+
+1. A Mermaid **`subgraph` rectangle labeled `"halt frame"`** around each wrapper — the visual scope for "the wrapper's stack frame for halt handling."
+2. A **cloned `(((halt)))` node inside that subgraph** — visualization of "halt-bound transitions land here, *inside* the wrapper's scope." `haltState` is a runtime singleton; the cloned visual is a teaching aid (one halt-clone per wrapper context on the diagram, all corresponding to the single runtime instance).
+
+### Visual contract (what a reader sees)
+
+- **`subgraph wN["halt frame"]`** = wrapper's runtime stack frame. While execution is "inside" the rectangle, the wrapper's override target sits on the runtime stack waiting to catch a halt. Visual-only — does not mutate the graph's edges.
+- **`[[bare]]`** (Mermaid subroutine / double-walled rectangle, "two lines on sides") = the wrapper-node. Both:
+  - the wrapper's runtime entry point (execution starts here on entering the wrapper), and
+  - the source of the dotted `onHalt` redirect (since the wrapper-node *is* the catcher).
+- **Cloned `(((halt)))` inside the subgraph** = the halt entry point within this wrapper's scope. Halt-bound transitions from the bare terminate here, not at the real halt.
+- **Solid arrows from `[[bare]]` to cloned halt** = the bare's structural halt-bound transitions. All stay inside the subgraph rectangle.
+- **Dotted `onHalt` arrow from `[[bare]]` out of the subgraph to the override target** = the wrapper's catch-and-redirect. Exactly one per wrapper; the only arrow that crosses the rectangle border.
+- **Real `(((halt)))` outside any subgraph** = the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame (the unwrapped tail of the chain).
+
+### Single wrapper
+
+`scanToX.withOverriddenHaltState(eraseHere)`:
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  subgraph wA["halt frame"]
+    s1[["scanToX"]]
+    h_A(((halt)))
+  end
+  s2["eraseHere"]
+  s1 -- "X → ·/S" --> h_A
+  s1 -- "* → ·/R" --> s1
+  s2 -- "* → ⌫/S" --> s0
+  s1 -. onHalt .-> s2
+```
+
+### Nested
+
+`A.withOverriddenHaltState(B.withOverriddenHaltState(C))`:
+
+```mermaid
+flowchart TD
+  s0(((halt)))
+  subgraph wA["halt frame"]
+    s1[["A"]]
+    h_A(((halt)))
+  end
+  subgraph wB["halt frame"]
+    s2[["B"]]
+    h_B(((halt)))
+  end
+  s3["C"]
+  s1 -- "..." --> h_A
+  s2 -- "..." --> h_B
+  s3 -- "..." --> s0
+  s1 -. onHalt .-> s2
+  s2 -. onHalt .-> s3
+```
+
+### Round-trip ([#139](https://github.com/mellonis/turing-machine-js/issues/139))
+
+The wrapper's composite name (e.g. `scanToX(eraseHere)`) does **not** appear as any graph node's label — only the bare's name does. `fromGraph` reconstructs the wrapper via `bareStates[id].withOverriddenHaltState(getFinal(overriddenHaltStateId))`, which recomputes the composite name fresh on the reconstructed State instance. No round-trip name accumulation — fixes #139 automatically.
+
+### Shared-bare handling
+
+`library-binary-numbers`'s `minusOne` = `invertNumber.with(plusOne.with(invertNumber.with(normalizeNumber)))` — same `invertNumber` instance is the bare of two distinct wrappers (outermost and innermost). Each wrapper context implies its own `subgraph` membership + its own cloned halt + its own dotted `onHalt` edge.
+
+Plan: emit the bare as a separate graph node per wrapper context (per-context duplication in `toGraph`). The shared State instance is preserved at runtime; the graph and Mermaid emit are per-context. `fromGraph` reconstructs equivalent State instances (not necessarily the same runtime `#id` as the original — just behaviorally equivalent).
+
+### Implementation outline
+
+1. Add `#bareState` field on `State`; populate in `withOverriddenHaltState` so `toGraph` can recover the bare from a wrapper instance.
+2. `GraphNode` gains `isWrapped: boolean`.
+3. `State.toGraph`:
+   - Detect wrapper-States (those with `#overriddenHaltState !== null`).
+   - Substitute with the bare; mark the bare's graph node `isWrapped: true`.
+   - Synthesize a per-wrapper cloned-halt graph node (a node with `isHalt: true` whose role is "halt-clone for this wrapper").
+   - Rewrite the bare's halt-bound transitions to target the cloned halt rather than the real one.
+4. `toMermaid`:
+   - `isWrapped: true` node → `s${id}[["${name}"]]` (subroutine shape).
+   - Cloned-halt node → `s${id}(((halt)))` (triple-paren, identical to real halt).
+   - Wrap each `[[bare]]` + its cloned halt in `subgraph wN["halt frame"] … end`.
+   - Dotted onHalt edge `s${bareId} -. onHalt .-> s${overrideId}` (from `[[bare]]`, crossing the subgraph border).
+5. `fromMermaid`:
+   - Parse Mermaid `subgraph wN["..."] … end` blocks.
+   - Recognize `s(\d+)\[\["([^"]*)"\]\]$` as wrapped-bare nodes; mark `isWrapped: true`.
+   - Track subgraph membership for the round-trip.
+6. `State.fromGraph`:
+   - For `isWrapped: true` nodes, reconstruct via `bareStates[id].withOverriddenHaltState(getFinal(overriddenHaltStateId))`.
+   - Cloned-halt graph nodes don't get separate State instances — they all map back to the singleton `haltState`.
+7. `#139`'s round-trip test added; should pass after this design.
+8. `states.md` regenerates with the new shape (both binary libraries).
+9. README "Subroutine composition" section rewritten to use the new visual + reader's contract above.
+
+### Downstream support (for `machines-demo` [#9](https://github.com/mellonis/machines-demo/issues/9) / [#10](https://github.com/mellonis/machines-demo/issues/10) / [#37](https://github.com/mellonis/machines-demo/issues/37))
+
+Five design choices in #138's implementation that keep the demo's render + highlight + click-to-breakpoint features unblocked:
+
+1. **Stable per-node ids in `Graph`.** Every node has a deterministic id:
+   - Bare nodes: `node.id = bareState.id` (the engine's `State.#id`).
+   - Cloned-halt nodes: synthesized but deterministic from `(bareNodeId, wrapper-depth)`.
+   - Per-context bare duplicates: synthesized similarly.
+
+   Mermaid emits `s${id}` for each; downstream can find the SVG node for any engine `state.id` directly.
+
+2. **Cloned-halt marker on `GraphNode`.** `isClonedHalt: boolean` (additional to `isHalt: true`). Real halt has `isHalt: true, isClonedHalt: false`; cloned halts have both `true`. Downstream uses this to:
+   - **#9** — emit cloned-halts with a different CSS class (`.cloned-halt` vs `.halt`) for styling.
+   - **#10** — skip cloned-halts when computing "current state highlight" (they're visualization aids, not runtime states).
+   - **#37** — skip cloned-halts when wiring click-to-toggle breakpoint handlers.
+
+3. **Edge identity on `GraphTransition`.** Add `id: string` field, deterministic from `(fromNodeId, patternIndex)` where `patternIndex` is the index of that transition in the bare's symbol map. Mermaid emit injects the id via a CSS-class directive that downstream can target. This is what #10 needs to highlight "the edge that will fire next" precisely.
+
+4. **Deterministic subgraph names in Mermaid emit.** Each wrapper's subgraph is `subgraph w_${bareNodeId}["halt frame"] … end`. Stable across rebuilds; downstream can target the rendered SVG group.
+
+5. **`isWrapped: boolean` on `GraphNode`** (already in the locked design above) — gives [#37](https://github.com/mellonis/machines-demo/issues/37) the surface to know "this node is a wrapper, click sets a breakpoint that triggers when the wrapper would catch a halt."
+
+**Out of scope for #138, deferred to #10 implementation:** exposing the runtime wrapper-context on `MachineState` (so downstream can disambiguate which duplicate-of-the-same-bare to highlight in shared-bare cases like `minusOne`). For the first cut of #10, lighting up all duplicates with the same `state.id` is acceptable; precision-tightening is a follow-up engine-API change. This is the only known shared-bare case in the library; user code rarely hits it.
diff --git a/packages/library-binary-numbers/src/graphs.spec.ts b/packages/library-binary-numbers/src/graphs.spec.ts
index 291fde6..4139787 100644
--- a/packages/library-binary-numbers/src/graphs.spec.ts
+++ b/packages/library-binary-numbers/src/graphs.spec.ts
@@ -2,10 +2,13 @@ import {State, fromMermaid, toMermaid} from '@turing-machine-js/machine';
 import binaryNumbers from './index';
 
 // Per-state node counts pinned from the source comments above each declaration
-// in `index.ts`. Each count includes haltState (`State.toGraph` walks the full
-// reachable graph, and every algorithm transitions to halt). Regressions caught:
-// a refactor that accidentally grows or shrinks an algorithm's state graph
-// fails this table.
+// in `index.ts`. Each count includes haltState plus any v7 cloned-halt nodes
+// synthesized by `toGraph` (one per `withOverriddenHaltState` wrapper context).
+// For single-wrapper algorithms the count is unchanged from v6 — the wrapper
+// node disappears (collapsed into its bare) but a cloned halt appears, netting
+// to zero. For shared-bare cases like `minusOne` (where the same bare appears
+// in multiple wrapper contexts via per-context duplication), the count grows
+// by `wrapperCount - 1` relative to v6.
 const expectedNodeCount: Record<keyof typeof binaryNumbers['states'], number> = {
   goToNumber: 2,
   goToNextNumber: 3,
@@ -15,7 +18,7 @@ const expectedNodeCount: Record<keyof typeof binaryNumbers['states'], number> =
   invertNumber: 5,
   normalizeNumber: 7,
   plusOne: 5,
-  minusOne: 17,
+  minusOne: 20,
   minusOneFast: 10,
 };
 
@@ -38,11 +41,14 @@ describe('library-binary-numbers state graphs', () => {
       const tapeBlock = binaryNumbers.getTapeBlock();
       const graph = State.toGraph(binaryNumbers.states[name], tapeBlock);
 
-      const haltNodes = Object.values(graph.nodes).filter((node) => node.isHalt);
+      // Every algorithm has exactly one REAL halt node (the singleton's id is
+      // shared across all states' graphs). v7's wrapper-emit synthesizes one
+      // `isClonedHalt: true` node per wrapper context as a visualization aid —
+      // those are filtered out here.
+      const realHaltNodes = Object.values(graph.nodes)
+        .filter((node) => node.isHalt && !node.isClonedHalt);
 
-      // Every algorithm has exactly one halt node (the singleton's id is shared
-      // across all states' graphs).
-      expect(haltNodes).toHaveLength(1);
+      expect(realHaltNodes).toHaveLength(1);
     },
   );
 
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 6918c8e..52e1407 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -51,16 +51,16 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
-  s5["goToNumberStart"]
   s6["deleteNumberInternal"]
-  s7["goToNumberStart(deleteNumberInternal)"]
   s8(("deleteNumber"))
-  s5 -- "^ → ·/S" --> s0
-  s5 -- "* → ·/L" --> s5
+  subgraph w_7["halt frame"]
+    s7[["goToNumberStart"]]
+    c7(((halt)))
+  end
   s6 -- "$ → ⌫/S" --> s0
   s6 -- "* → ⌫/R" --> s6
-  s7 -- "^ → ·/S" --> s0
-  s7 -- "* → ·/L" --> s5
+  s7 -- "^ → ·/S" --> c7
+  s7 -- "* → ·/L" --> s7
   s7 -. onHalt .-> s6
   s8 -- "^|1|0|$ → ·/S" --> s7
   s8 -- "* → ·/S" --> s0
@@ -87,18 +87,18 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
-  s5["goToNumberStart"]
   s9["invertNumberGoToNumberWithInversion"]
-  s10["goToNumberStart(invertNumberGoToNumberWithInversion)"]
   s11(("invertNumber"))
-  s5 -- "^ → ·/S" --> s0
-  s5 -- "* → ·/L" --> s5
+  subgraph w_10["halt frame"]
+    s10[["goToNumberStart"]]
+    c10(((halt)))
+  end
   s9 -- "^ → ·/R" --> s9
   s9 -- "1 → 0/R" --> s9
   s9 -- "0 → 1/R" --> s9
   s9 -- "$ → ·/S" --> s0
-  s10 -- "^ → ·/S" --> s0
-  s10 -- "* → ·/L" --> s5
+  s10 -- "^ → ·/S" --> c10
+  s10 -- "* → ·/L" --> s10
   s10 -. onHalt .-> s9
   s11 -- "^|1|0|$ → ·/S" --> s10
   s11 -- "* → ·/S" --> s0
@@ -113,20 +113,20 @@ flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s1["goToNumber"]
-  s5["goToNumberStart"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
-  s14["goToNumberStart(normalizeNumberMoveNumberStart)"]
   s15(("normalizeNumber"))
+  subgraph w_14["halt frame"]
+    s14[["goToNumberStart"]]
+    c14(((halt)))
+  end
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
-  s5 -- "^ → ·/S" --> s0
-  s5 -- "* → ·/L" --> s5
   s12 -- "- → ^/S" --> s1
   s13 -- "^|0 → ⌫/R" --> s13
   s13 -- "1|$ → ·/L" --> s12
-  s14 -- "^ → ·/S" --> s0
-  s14 -- "* → ·/L" --> s5
+  s14 -- "^ → ·/S" --> c14
+  s14 -- "* → ·/L" --> s14
   s14 -. onHalt .-> s13
   s15 -- "^|1|0|$ → ·/S" --> s14
   s15 -- "* → ·/S" --> s0
@@ -158,44 +158,55 @@ flowchart TD
 
 ## minusOne
 
-*17 states (including `haltState`)*
+*20 states (including `haltState`)*
 
 ```mermaid
 flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s1["goToNumber"]
-  s5["goToNumberStart"]
   s9["invertNumberGoToNumberWithInversion"]
-  s10["goToNumberStart(invertNumberGoToNumberWithInversion)"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
-  s14["goToNumberStart(normalizeNumberMoveNumberStart)"]
   s15["normalizeNumber"]
   s16["plusOneFillZeros"]
   s17["plusOneAddNumberStart"]
   s18["plusOneCaryOne"]
-  s19["plusOne"]
-  s20["invertNumber(normalizeNumber)"]
-  s21["plusOne(invertNumber(normalizeNumber))"]
-  s22["invertNumber(plusOne(invertNumber(normalizeNumber)))"]
   s23(("minusOne"))
+  subgraph w_10["halt frame"]
+    s10[["goToNumberStart"]]
+    c10(((halt)))
+  end
+  subgraph w_14["halt frame"]
+    s14[["goToNumberStart"]]
+    c14(((halt)))
+  end
+  subgraph w_20["halt frame"]
+    s20[["invertNumber"]]
+    c20(((halt)))
+  end
+  subgraph w_21["halt frame"]
+    s21[["plusOne"]]
+    c21(((halt)))
+  end
+  subgraph w_22["halt frame"]
+    s22[["invertNumber"]]
+    c22(((halt)))
+  end
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
-  s5 -- "^ → ·/S" --> s0
-  s5 -- "* → ·/L" --> s5
   s9 -- "^ → ·/R" --> s9
   s9 -- "1 → 0/R" --> s9
   s9 -- "0 → 1/R" --> s9
   s9 -- "$ → ·/S" --> s0
-  s10 -- "^ → ·/S" --> s0
-  s10 -- "* → ·/L" --> s5
+  s10 -- "^ → ·/S" --> c10
+  s10 -- "* → ·/L" --> s10
   s10 -. onHalt .-> s9
   s12 -- "- → ^/S" --> s1
   s13 -- "^|0 → ⌫/R" --> s13
   s13 -- "1|$ → ·/L" --> s12
-  s14 -- "^ → ·/S" --> s0
-  s14 -- "* → ·/L" --> s5
+  s14 -- "^ → ·/S" --> c14
+  s14 -- "* → ·/L" --> s14
   s14 -. onHalt .-> s13
   s15 -- "^|1|0|$ → ·/S" --> s14
   s15 -- "* → ·/S" --> s0
@@ -206,18 +217,15 @@ flowchart TD
   s18 -- "0 → 1/R" --> s16
   s18 -- "1 → ·/L" --> s18
   s18 -- "^ → 1/L" --> s17
-  s19 -- "^|1|0 → ·/R" --> s19
-  s19 -- "$ → ·/L" --> s18
-  s19 -- "* → ·/S" --> s0
   s20 -- "^|1|0|$ → ·/S" --> s10
-  s20 -- "* → ·/S" --> s0
+  s20 -- "* → ·/S" --> c20
   s20 -. onHalt .-> s15
-  s21 -- "^|1|0 → ·/R" --> s19
+  s21 -- "^|1|0 → ·/R" --> s21
   s21 -- "$ → ·/L" --> s18
-  s21 -- "* → ·/S" --> s0
+  s21 -- "* → ·/S" --> c21
   s21 -. onHalt .-> s20
   s22 -- "^|1|0|$ → ·/S" --> s10
-  s22 -- "* → ·/S" --> s0
+  s22 -- "* → ·/S" --> c22
   s22 -. onHalt .-> s21
   s23 -- "^|1|0 → ·/R" --> s23
   s23 -- "$ → ·/S" --> s22
@@ -233,32 +241,31 @@ flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s1["goToNumber"]
-  s5["goToNumberStart"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
-  s14["goToNumberStart(normalizeNumberMoveNumberStart)"]
   s15["normalizeNumber"]
-  s24["minusOneFastBorrow"]
-  s25["minusOneFastBorrow(normalizeNumber)"]
   s26(("minusOneFast"))
+  subgraph w_14["halt frame"]
+    s14[["goToNumberStart"]]
+    c14(((halt)))
+  end
+  subgraph w_25["halt frame"]
+    s25[["minusOneFastBorrow"]]
+    c25(((halt)))
+  end
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
-  s5 -- "^ → ·/S" --> s0
-  s5 -- "* → ·/L" --> s5
   s12 -- "- → ^/S" --> s1
   s13 -- "^|0 → ⌫/R" --> s13
   s13 -- "1|$ → ·/L" --> s12
-  s14 -- "^ → ·/S" --> s0
-  s14 -- "* → ·/L" --> s5
+  s14 -- "^ → ·/S" --> c14
+  s14 -- "* → ·/L" --> s14
   s14 -. onHalt .-> s13
   s15 -- "^|1|0|$ → ·/S" --> s14
   s15 -- "* → ·/S" --> s0
-  s24 -- "1 → 0/S" --> s0
-  s24 -- "0 → 1/L" --> s24
-  s24 -- "^ → ·/S" --> s0
-  s25 -- "1 → 0/S" --> s0
-  s25 -- "0 → 1/L" --> s24
-  s25 -- "^ → ·/S" --> s0
+  s25 -- "1 → 0/S" --> c25
+  s25 -- "0 → 1/L" --> s25
+  s25 -- "^ → ·/S" --> c25
   s25 -. onHalt .-> s15
   s26 -- "^|1|0 → ·/R" --> s26
   s26 -- "$ → ·/L" --> s25
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 78a2be8..42ff5a6 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -440,25 +440,28 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","a","b","X"]]
   s0(((halt)))
-  s1["scanToX"]
   s2["eraseHere"]
-  s3(("scanToX(eraseHere)"))
-  s1 -- "X → ·/S" --> s0
-  s1 -- "* → ·/R" --> s1
+  subgraph w_3["halt frame"]
+    s3[["scanToX"]]
+    c3(((halt)))
+  end
   s2 -- "* → ⌫/S" --> s0
-  s3 -- "X → ·/S" --> s0
-  s3 -- "* → ·/R" --> s1
+  s3 -- "X → ·/S" --> c3
+  s3 -- "* → ·/R" --> s3
   s3 -. onHalt .-> s2
 ```
 
-**Reading guide** — the wrapped diagram is denser than the simplified hand-drawn version above. To parse it:
+**Reading guide** — the v7 emit (introduced in [#138](https://github.com/mellonis/turing-machine-js/issues/138)) makes the wrapper's runtime stack-frame semantics visible:
+
+1. **The subgraph rectangle labeled `"halt frame"`** is the wrapper's runtime scope — while execution is "inside" this rectangle, the override target (`eraseHere`) sits on the runtime stack waiting to catch a halt. Visual-only; it does not mutate any edges.
+2. **`[[scanToX]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node. It's both the runtime entry point (execution starts here when entering the wrapper) AND the source of the dotted `onHalt` redirect. The wrapper's composite name (`scanToX(eraseHere)`) is computed at runtime via `state.name` but does not appear as a graph node label — only the bare's name is in the graph.
+3. **The cloned `(((halt)))` inside the subgraph** (`c3` here) is where the bare's halt-bound transitions land *inside* the wrapper's scope. `haltState` is a runtime singleton; the cloned node is a teaching aid showing "halt is caught here, not at the real terminus." Solid arrows from the bare to the cloned halt all stay inside the rectangle.
+4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. The single arrow that crosses the subgraph border. Originates from the wrapper-node since the wrapper *is* the catcher.
+5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame — here, by `eraseHere` after it erases the cell.
 
-1. **Three non-halt nodes:** the wrapper `scanToX(eraseHere)` (round, the initial state); `scanToX` (square, the original subroutine — unmodified); `eraseHere` (square, the override target). The wrapper appears as a *separate* state from `scanToX`-the-original because `withOverriddenHaltState` returns a new `State` instance — even though it shares the transition map. The composite-name format is `bare(override)` — chosen so nested wrappers stay unambiguous: `A.with(B.with(A))` produces `A(B(A))` while `A.with(B).with(A)` produces `A(B)(A)`, two different runtime shapes that flat `A>B>A` notation collided.
-2. **Solid edges from the wrapper duplicate `scanToX`'s edges.** That's because the wrapper inherits the same `symbolToDataMap`. Importantly, the wrapper's `* → ·/R` edge points at *`scanToX`-the-original*, not at the wrapper itself — so after the first iteration, control transfers to `scanToX` and stays there.
-3. **The dotted `onHalt` edge is attached to the wrapper** but it doesn't fire on a single edge at runtime. Instead, the runtime pushes `eraseHere` onto an internal stack at startup, and *any* halt-bound transition reachable during the run (whether on the wrapper itself or on `scanToX`) gets redirected to `eraseHere` via stack-pop. The dotted edge is the engine's static fingerprint of "this graph was wrapped by `withOverriddenHaltState`."
-4. **What actually fires at runtime, on tape `['a','b','X','b','a']`:** the wrapper runs once, transferring to `scanToX`; `scanToX` self-loops on `* → ·/R` until it sees `X`; the `X → ·/S` edge tries to go to halt; the runtime pops `eraseHere` off the stack and substitutes it; `eraseHere` erases the cell and halts. The wrapper's own `X → ·/S → halt` edge in the diagram is *never traversed* because control left the wrapper after iteration 1.
+**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `* → ·/R` self-loops until the head sees `X`; the `X → ·/S` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `* → ⌫/S` and halts at real `s0`. Run terminates.
 
-> 💡 **The engine's emit could be more user-friendly here.** Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) — the wrapper's duplicated edges and the misleading single-edge `onHalt` placement are candidates for a cleaner `toMermaid` output.
+> 💡 **Round-trip caveat.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers like this one ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). For shared-bare cases (same `State` instance used as the bare in multiple wrappers — e.g., `library-binary-numbers`'s `minusOne`), per-context duplication produces wrapper-id-dependent ordering that doesn't byte-match across rebuilds — equivalent runtime behavior, different emit-line order.
 
 </details>
 
@@ -619,7 +622,8 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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** *(in progress)* — Composition-representation overhaul. Breaking renames + reshapes scheduled for the v7 cut. Landing piecewise on the `v7` branch; one entry per landed change:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
-  - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly. Round-trip name accumulation in `withOverriddenHaltState` chains stays present in paren form — `A(B)` becomes `A(B)(B)` on second round-trip — tracked separately in [#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139).
+  - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
+  - **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139)). The wrapper-and-its-bare pair collapses into a single graph node (`isWrapped: true`); the wrapper's composite name no longer appears as a node label (only the bare's name does). Each wrapper gets a Mermaid `subgraph w_${bareId}["halt frame"] … end` block containing the `[[bare]]` (subroutine shape) plus a cloned `(((halt)))` (visualization aid showing where halt-bound transitions land inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target — exactly one per wrapper. `Graph` data shape gains `isWrapped` and `isClonedHalt` flags on `GraphNode` and a stable `id` on `GraphTransition` (deterministic per-edge identifier — supports downstream tooling like the `machines-demo` interactive viewer at [machines-demo#10](https://github.com/mellonis/machines-demo/issues/10)). Cloned-halt graph nodes use negative ids and round-trip back to the singleton `haltState` via `fromGraph`. Bytewise round-trip stability falls out for simple wrappers (no composite name in the graph means `fromGraph(toGraph(state))` recomputes names fresh — no accumulation). Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use per-context duplication in the graph emit.
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index ac8069b..e8f9528 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -232,14 +232,14 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
     // pointing in a loop.
     // Nodes need at least one transition each — State construction at pass 2
     // rejects empty stateDefinitions before pass 3's cycle check would run.
-    const dummyTransition = {pattern: '*', command: [{symbol: '·', movement: 'S'}], nextStateId: 0};
+    const dummyTransition = {pattern: '*', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"};
     const graph = {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2, isWrapped: false, isClonedHalt: false},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1, isWrapped: false, isClonedHalt: false},
       },
     };
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 3d4b4ec..8eca6e4 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -81,6 +81,12 @@ export default class State {
 
   #overriddenHaltState: State | null = null;
 
+  // For wrapper states (produced by `withOverriddenHaltState`), points at the
+  // State whose transition map was wrapped. `null` on bare/atomic states.
+  // Used by `toGraph` to collapse the wrapper-and-its-bare pair into a single
+  // "wrapped bare" graph node — see the v7 emit redesign for #138.
+  #bareState: State | null = null;
+
   #symbolToDataMap = new Map<symbol, { command: Command, nextState: State | Reference }>();
 
   // Shared mutable cell — withOverriddenHaltState wrappers reference the same
@@ -278,6 +284,7 @@ export default class State {
     state.#symbolToDataMap = this.#symbolToDataMap;
     state.#overriddenHaltState = overriddenHaltState;
     state.#debugRef = this.#debugRef;
+    state.#bareState = this;
 
     return state;
   }
@@ -334,55 +341,226 @@ export default class State {
     };
   }
 
+  // Walks the State graph and emits a `Graph` data structure. v7 emit shape:
+  // wrapper-States (those with `#overriddenHaltState !== null`) are collapsed
+  // onto their bare's representation in the graph, with the wrapper's own `#id`
+  // used as the graph node id, `isWrapped: true`, and `overriddenHaltStateId`
+  // set to the override's collapsed id. A per-wrapper "cloned halt" graph node
+  // (id = negative-of-the-wrapper-id, `isHalt: true, isClonedHalt: true`) is
+  // synthesized; the bare's halt-bound transitions are rewritten to target the
+  // cloned halt instead of the real one.
+  //
+  // Cloned-halt node ids use the negation of the wrapper's id so they sit in a
+  // disjoint integer range from real ids (which are always non-negative). Real
+  // halt is always id 0.
   static toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
     const nodes: Record<number, GraphNode> = {};
-    const queue: State[] = [initialState];
     const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
 
+    // Map from a wrapper-State to the "collapsed" graph node id used to refer
+    // to it in transitions. Same as the wrapper's `#id`, recorded for clarity
+    // when rewriting transition targets.
+    const wrapperGraphId = (s: State): number => s.#id;
+    const clonedHaltIdFor = (wrapper: State): number => -wrapper.#id;
+
+    // The `initialId` is the user-passed start. If it's a wrapper, the
+    // collapsed graph node uses its `#id`; otherwise its own `#id`.
+    const initialId = initialState.#id;
+
+    type QueueItem = {
+      // The State instance to process at this slot.
+      state: State;
+      // When non-null, the State is being processed AS the bare of this wrapper.
+      // The collapsed graph node uses `wrapperGraphId(wrapperContext)`,
+      // halt-bound transitions retarget to `clonedHaltIdFor(wrapperContext)`,
+      // self-loop transitions to the bare retarget to the wrapper-id.
+      wrapperContext: State | null;
+    };
+
+    const queue: QueueItem[] = [];
+
+    // Decide how to enqueue the start: if it's a wrapper, enqueue its bare with
+    // the wrapper as context; otherwise enqueue the state itself.
+    if (initialState.#overriddenHaltState && initialState.#bareState) {
+      queue.push({state: initialState.#bareState, wrapperContext: initialState});
+    } else {
+      queue.push({state: initialState, wrapperContext: null});
+    }
+
     while (queue.length > 0) {
-      const current = queue.shift()!;
+      const {state, wrapperContext} = queue.shift()!;
+
+      if (state.isHalt) {
+        // Real halt — always id 0, single node.
+        if (!(0 in nodes)) {
+          nodes[0] = {
+            id: 0,
+            name: state.#name,
+            isHalt: true,
+            isClonedHalt: false,
+            isWrapped: false,
+            transitions: [],
+            overriddenHaltStateId: null,
+          };
+        }
 
-      if (current.#id in nodes) {
+        continue;
+      }
+
+      if (wrapperContext !== null) {
+        // Process `state` (the bare) collapsed under `wrapperContext` (the
+        // wrapper). Graph node id = wrapper's id.
+        const collapsedId = wrapperGraphId(wrapperContext);
+
+        if (collapsedId in nodes) {
+          continue;
+        }
+
+        const clonedHaltId = clonedHaltIdFor(wrapperContext);
+        const overrideTarget = wrapperContext.#overriddenHaltState!;
+
+        // The override target's collapsed id: if the override is itself a
+        // wrapper, its graph node id is `overrideTarget.#id` (its own wrapper
+        // id); otherwise its own bare id.
+        const overrideGraphId = overrideTarget.#overriddenHaltState
+          ? wrapperGraphId(overrideTarget)
+          : overrideTarget.#id;
+
+        // Emit the cloned-halt node if not already present (one per wrapper).
+        if (!(clonedHaltId in nodes)) {
+          nodes[clonedHaltId] = {
+            id: clonedHaltId,
+            name: 'halt',
+            isHalt: true,
+            isClonedHalt: true,
+            isWrapped: false,
+            transitions: [],
+            overriddenHaltStateId: null,
+          };
+        }
+
+        // Build the collapsed node.
+        const collapsedNode: GraphNode = {
+          id: collapsedId,
+          name: state.#name,
+          isHalt: false,
+          isClonedHalt: false,
+          isWrapped: true,
+          transitions: [],
+          overriddenHaltStateId: overrideGraphId,
+        };
+
+        nodes[collapsedId] = collapsedNode;
+
+        let patternIx = 0;
+
+        for (const [sym, {command, nextState}] of state.#symbolToDataMap) {
+          let target: State;
+
+          try {
+            target = nextState instanceof State ? nextState : nextState.ref;
+          } catch {
+            patternIx += 1;
+            continue;
+          }
+
+          // Retarget transitions per Variant X conventions:
+          // - target == haltState → cloned halt (stays inside the subgraph)
+          // - target == bare (self-loop) → the collapsed wrapper id
+          // - target is itself a wrapper → that wrapper's collapsed id
+          // - else → target's own id
+          let nextStateId: number;
+
+          if (target.isHalt) {
+            nextStateId = clonedHaltId;
+          } else if (target === state) {
+            nextStateId = collapsedId;
+          } else if (target.#overriddenHaltState && target.#bareState) {
+            nextStateId = wrapperGraphId(target);
+            queue.push({state: target.#bareState, wrapperContext: target});
+          } else {
+            nextStateId = target.#id;
+            queue.push({state: target, wrapperContext: null});
+          }
+
+          collapsedNode.transitions.push({
+            pattern: decodePatternDescription(sym.description, alphabets),
+            command: command.tapesCommands.map((tc) => ({
+              symbol: decodeWriteSymbol(tc.symbol),
+              movement: decodeMovement((tc.movement as symbol).description),
+            })),
+            nextStateId,
+            id: `${collapsedId}-${patternIx}`,
+          });
+
+          patternIx += 1;
+        }
+
+        // Enqueue the override target so its own node is emitted.
+        if (overrideTarget.#overriddenHaltState && overrideTarget.#bareState) {
+          queue.push({state: overrideTarget.#bareState, wrapperContext: overrideTarget});
+        } else {
+          queue.push({state: overrideTarget, wrapperContext: null});
+        }
+
+        continue;
+      }
+
+      // Non-wrapper context: emit `state` as a regular node.
+      if (state.#id in nodes) {
         continue;
       }
 
       const node: GraphNode = {
-        id: current.#id,
-        name: current.#name,
-        isHalt: current.isHalt,
+        id: state.#id,
+        name: state.#name,
+        isHalt: false,
+        isClonedHalt: false,
+        isWrapped: false,
         transitions: [],
-        overriddenHaltStateId: current.#overriddenHaltState?.id ?? null,
+        overriddenHaltStateId: null,
       };
 
-      nodes[current.#id] = node;
+      nodes[state.#id] = node;
 
-      if (current.#overriddenHaltState) {
-        queue.push(current.#overriddenHaltState);
-      }
+      let patternIx = 0;
 
-      for (const [sym, {command, nextState}] of current.#symbolToDataMap) {
+      for (const [sym, {command, nextState}] of state.#symbolToDataMap) {
         let target: State;
 
         try {
           target = nextState instanceof State ? nextState : nextState.ref;
         } catch {
+          patternIx += 1;
           continue;
         }
 
+        let nextStateId: number;
+
+        if (target.#overriddenHaltState && target.#bareState) {
+          // Transition into a wrapper — use its collapsed id.
+          nextStateId = wrapperGraphId(target);
+          queue.push({state: target.#bareState, wrapperContext: target});
+        } else {
+          nextStateId = target.#id;
+          queue.push({state: target, wrapperContext: null});
+        }
+
         node.transitions.push({
           pattern: decodePatternDescription(sym.description, alphabets),
           command: command.tapesCommands.map((tc) => ({
             symbol: decodeWriteSymbol(tc.symbol),
             movement: decodeMovement((tc.movement as symbol).description),
           })),
-          nextStateId: target.id,
+          nextStateId,
+          id: `${state.#id}-${patternIx}`,
         });
 
-        queue.push(target);
+        patternIx += 1;
       }
     }
 
-    return {initialId: initialState.#id, alphabets, nodes};
+    return {initialId, alphabets, nodes};
   }
 
   // Inverse of toGraph: rebuilds a State graph (and a fresh TapeBlock with the
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index ad646a6..c9aa912 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -113,12 +113,12 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1},
-            {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0},
+            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -137,8 +137,8 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
-        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isWrapped: false, isClonedHalt: false},
       },
     });
 
@@ -150,9 +150,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
-        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null},
-        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
       },
     });
 
@@ -164,13 +164,14 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0'], [' ', 'a']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [{
             pattern: '0,a',
             command: [{symbol: '0', movement: 'R'}, {symbol: 'a', movement: 'L'}],
             nextStateId: 0,
+            id: 'test-edge',
           }],
         },
       },
@@ -392,7 +393,7 @@ describe('README diagrams: engine-generated outputs', () => {
     ]);
   });
 
-  test('withOverriddenHaltState AFTER (scanThenErase, machine README) — emits the onHalt dotted edge', () => {
+  test('withOverriddenHaltState AFTER (scanThenErase, machine README) — emits the v7 halt-frame subgraph', () => {
     const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
     const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
     const {symbol} = tapeBlock;
@@ -410,12 +411,13 @@ describe('README diagrams: engine-generated outputs', () => {
     expectAllLines(output, [
       'flowchart TD',
       '%% alphabets: [[" ","a","b","X"]]',
-      '(((halt)))',
-      '["scanToX"]', // original scanToX is reachable from the wrapper → square
-      '["eraseHere"]', // eraseHere is reachable via onHalt → square
-      '(("scanToX(eraseHere)"))', // wrapper is the initial state → round
+      '(((halt)))', // real halt outside any subgraph
+      '["eraseHere"]', // override is a regular [name] node
+      '[["scanToX"]]', // wrapper-collapsed bare uses subroutine shape inside the subgraph
+      'subgraph w_', // halt-frame subgraph wraps the bare + its cloned halt
+      '"halt frame"', // subgraph label
       '"* → ⌫/S"', // eraseHere's erase command
-      '-. onHalt .->', // the dotted override-halt edge — engine's static fingerprint of the override
+      '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
     ]);
   });
 });
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index e98c31f..eb21efb 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -6,6 +6,11 @@ export type GraphTransition = {
   pattern: string;
   command: GraphCommand[];
   nextStateId: number;
+  // Stable, deterministic per-edge identifier. Format: `${fromNodeId}-${patternIx}`
+  // where `patternIx` is the transition's position in the source state's symbol
+  // map. Let's downstream rendering (machines-demo #10) target a specific edge in
+  // the rendered Mermaid SVG to highlight "the edge that will fire next."
+  id: string;
 };
 
 export type GraphNode = {
@@ -14,6 +19,14 @@ export type GraphNode = {
   isHalt: boolean;
   transitions: GraphTransition[];
   overriddenHaltStateId: number | null;
+  // `true` when this node represents the bare of a `withOverriddenHaltState`-
+  // wrapped state. Carries the `[[…]]` (subroutine) shape signal for `toMermaid`
+  // and tells `fromGraph` to reconstruct via `bare.withOverriddenHaltState(target)`.
+  isWrapped: boolean;
+  // `true` for a synthesized halt-clone graph node — one per wrapper context.
+  // Real halt has `isHalt: true, isClonedHalt: false`; cloned halts have both
+  // `true`. `fromGraph` maps cloned-halt nodes back to the singleton `haltState`.
+  isClonedHalt: boolean;
 };
 
 export type Graph = {
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 17aafbd..eb5cba1 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -5,6 +5,36 @@ import {type Graph, type GraphCommand, type GraphNode} from './graph';
 //
 // Currently only Mermaid flowchart syntax is supported. Future formats
 // (Graphviz, JSON-LD, custom DSL) belong here too.
+//
+// v7 emit shape (#138/#139):
+//   - Each wrapper-State collapses onto its bare's representation. The collapsed
+//     graph node has `isWrapped: true` and is emitted as Mermaid `[[…]]`
+//     (subroutine / double-walled-rectangle) shape, inside a `subgraph
+//     w_${id}["halt frame"] … end` block. A synthesized "cloned halt" graph
+//     node (with `isHalt: true, isClonedHalt: true`, id = -wrapperId in graph
+//     data) sits inside the subgraph and serves as the local landing point for
+//     the bare's halt-bound transitions. The dotted onHalt edge runs from the
+//     `[[bare]]` directly to the override target, crossing the subgraph border.
+//   - Real halt (id 0) is emitted as `s0(((halt)))` outside any subgraph.
+//   - Cloned halt nodes use the Mermaid id `c${absId}` (where `absId = -id`)
+//     since Mermaid IDs must match /[A-Za-z][A-Za-z0-9_]*/ — negative numbers
+//     are not legal syntax.
+
+// Maps a graph node id to its Mermaid id.
+//   - non-negative id N  → "sN"
+//   - negative id -N (cloned halt) → "cN"
+function mermaidIdFor(id: number): string {
+  return id < 0 ? `c${-id}` : `s${id}`;
+}
+
+// Inverse of mermaidIdFor.
+function parseMermaidId(s: string): number {
+  if (s.startsWith('c')) {
+    return -Number(s.slice(1));
+  }
+
+  return Number(s.slice(1));
+}
 
 export function toMermaid(graph: Graph): string {
   const lines: string[] = [
@@ -12,8 +42,33 @@ export function toMermaid(graph: Graph): string {
     `%% alphabets: ${JSON.stringify(graph.alphabets)}`,
   ];
 
-  for (const node of Object.values(graph.nodes)) {
-    const id = `s${node.id}`;
+  // Sort nodes by id (ascending — real halt first at 0, regular states next,
+  // negative-id cloned halts last). Deterministic emit lets `toMermaid` →
+  // `fromMermaid` → `toMermaid` round-trip stably (regression for #139).
+  const nodes = Object.values(graph.nodes).slice().sort((a, b) => a.id - b.id);
+  const wrappedNodes = nodes.filter((n) => n.isWrapped);
+
+  // Convention: wrapped node id N → cloned halt id -N.
+  const clonedHaltFor = (wrappedId: number): number => -wrappedId;
+
+  // Set of cloned-halt ids that belong to some wrapper (= are inside a subgraph).
+  const clonedHaltIds = new Set<number>();
+
+  for (const w of wrappedNodes) {
+    const clonedId = clonedHaltFor(w.id);
+
+    if (clonedId in graph.nodes) {
+      clonedHaltIds.add(clonedId);
+    }
+  }
+
+  // Emit non-subgraph nodes first: real halt + regular non-wrapped nodes.
+  for (const node of nodes) {
+    if (node.isWrapped || clonedHaltIds.has(node.id)) {
+      continue;
+    }
+
+    const id = mermaidIdFor(node.id);
 
     if (node.isHalt) {
       lines.push(`  ${id}(((halt)))`);
@@ -24,17 +79,43 @@ export function toMermaid(graph: Graph): string {
     }
   }
 
-  for (const node of Object.values(graph.nodes)) {
+  // Emit one subgraph per wrapper, in sorted wrapped-id order.
+  for (const wrapped of wrappedNodes) {
+    const wrappedMid = mermaidIdFor(wrapped.id);
+    const clonedId = clonedHaltFor(wrapped.id);
+    const clonedMid = mermaidIdFor(clonedId);
+
+    lines.push(`  subgraph w_${wrapped.id}["halt frame"]`);
+    lines.push(`    ${wrappedMid}[["${wrapped.name}"]]`);
+
+    if (clonedId in graph.nodes) {
+      lines.push(`    ${clonedMid}(((halt)))`);
+    }
+
+    lines.push('  end');
+  }
+
+  // Emit transitions per-node in sorted node-id order. Within a node,
+  // transitions emit in their stored array order (which mirrors the source
+  // state's symbol-map insertion order — stable per State instance).
+  for (const node of nodes) {
+    if (node.isHalt && !node.isClonedHalt) {
+      continue;
+    }
+
     for (const t of node.transitions) {
-      // Per-tape commands separated with ',' to mirror the pattern syntax.
       const cmd = t.command.map((c) => `${c.symbol}/${c.movement}`).join(',');
       const label = `${t.pattern} → ${cmd}`;
 
-      lines.push(`  s${node.id} -- "${label}" --> s${t.nextStateId}`);
+      lines.push(
+        `  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`,
+      );
     }
 
     if (node.overriddenHaltStateId !== null) {
-      lines.push(`  s${node.id} -. onHalt .-> s${node.overriddenHaltStateId}`);
+      lines.push(
+        `  ${mermaidIdFor(node.id)} -. onHalt .-> ${mermaidIdFor(node.overriddenHaltStateId)}`,
+      );
     }
   }
 
@@ -52,11 +133,14 @@ export function toMermaid(graph: Graph): string {
 //   per-tape segments are split on ','. If your alphabet contains '/' or ','
 //   as literal symbols, the parser cannot disambiguate. Stick to alphabets
 //   without those characters when round-tripping through Mermaid.
-const haltNodeRegex = /^s(\d+)\(\(\(halt\)\)\)$/;
-const initialNodeRegex = /^s(\d+)\(\("([^"]*)"\)\)$/;
-const regularNodeRegex = /^s(\d+)\["([^"]*)"\]$/;
-const transitionRegex = /^s(\d+)\s+--\s+"(.*)"\s+-->\s+s(\d+)$/;
-const onHaltRegex = /^s(\d+)\s+-\.\s+onHalt\s+\.->\s+s(\d+)$/;
+const haltNodeRegex = /^([sc]\d+)\(\(\(halt\)\)\)$/;
+const initialNodeRegex = /^(s\d+)\(\("([^"]*)"\)\)$/;
+const regularNodeRegex = /^(s\d+)\["([^"]*)"\]$/;
+const wrappedNodeRegex = /^(s\d+)\[\["([^"]*)"\]\]$/;
+const subgraphStartRegex = /^subgraph\s+w_\d+\["([^"]*)"\]$/;
+const subgraphEndRegex = /^end$/;
+const transitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
+const onHaltRegex = /^([sc]\d+)\s+-\.\s+onHalt\s+\.->\s+([sc]\d+)$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
 // the preceding \s* and a permissive (.+); see CodeQL js/polynomial-redos.
 const alphabetsRegex = /^%%\s*alphabets:\s*(\S.*)$/;
@@ -67,30 +151,42 @@ export function fromMermaid(text: string): Graph {
   let alphabets: string[][] = [];
   let initialId: number | null = null;
   const nodes: Record<number, GraphNode> = {};
-
-  const ensureNode = (id: number, opts: { name?: string; isHalt?: boolean } = {}): GraphNode => {
+  // Track the cloned-halt ids that appeared inside a subgraph — they should be
+  // marked `isClonedHalt: true` even though they share the `(((halt)))` shape
+  // with the real halt at the top level.
+  const clonedHaltIds = new Set<number>();
+  let inSubgraph = false;
+
+  const ensureNode = (
+    id: number,
+    opts: {
+      name?: string;
+      isHalt?: boolean;
+      isClonedHalt?: boolean;
+      isWrapped?: boolean;
+    } = {},
+  ): GraphNode => {
     if (!nodes[id]) {
       nodes[id] = {
         id,
-        name: opts.name ?? `s${id}`,
+        name: opts.name ?? mermaidIdFor(id),
         isHalt: opts.isHalt ?? false,
+        isClonedHalt: opts.isClonedHalt ?? false,
+        isWrapped: opts.isWrapped ?? false,
         transitions: [],
         overriddenHaltStateId: null,
       };
     } else {
-      if (opts.name !== undefined) {
-        nodes[id].name = opts.name;
-      }
-
-      if (opts.isHalt !== undefined) {
-        nodes[id].isHalt = opts.isHalt;
-      }
+      if (opts.name !== undefined) nodes[id].name = opts.name;
+      if (opts.isHalt !== undefined) nodes[id].isHalt = opts.isHalt;
+      if (opts.isClonedHalt !== undefined) nodes[id].isClonedHalt = opts.isClonedHalt;
+      if (opts.isWrapped !== undefined) nodes[id].isWrapped = opts.isWrapped;
     }
 
     return nodes[id];
   };
 
-  // First pass: alphabets + nodes.
+  // First pass: alphabets + nodes (track subgraph context to mark cloned halts).
   for (const line of lines) {
     if (line === 'flowchart TD') {
       continue;
@@ -103,17 +199,48 @@ export function fromMermaid(text: string): Graph {
       continue;
     }
 
+    if (subgraphStartRegex.test(line)) {
+      inSubgraph = true;
+      continue;
+    }
+
+    if (subgraphEndRegex.test(line)) {
+      inSubgraph = false;
+      continue;
+    }
+
     const hm = line.match(haltNodeRegex);
 
     if (hm) {
-      ensureNode(Number(hm[1]), {name: 'halt', isHalt: true});
+      const id = parseMermaidId(hm[1]);
+      const isCloned = inSubgraph || id < 0;
+
+      ensureNode(id, {name: 'halt', isHalt: true, isClonedHalt: isCloned});
+
+      if (isCloned) {
+        clonedHaltIds.add(id);
+      }
+
+      continue;
+    }
+
+    const wm = line.match(wrappedNodeRegex);
+
+    if (wm) {
+      const id = parseMermaidId(wm[1]);
+
+      if (initialId === null) {
+        initialId = id;
+      }
+
+      ensureNode(id, {name: wm[2], isWrapped: true});
       continue;
     }
 
     const im = line.match(initialNodeRegex);
 
     if (im) {
-      const id = Number(im[1]);
+      const id = parseMermaidId(im[1]);
 
       initialId = id;
       ensureNode(id, {name: im[2]});
@@ -123,7 +250,7 @@ export function fromMermaid(text: string): Graph {
     const rm = line.match(regularNodeRegex);
 
     if (rm) {
-      ensureNode(Number(rm[1]), {name: rm[2]});
+      ensureNode(parseMermaidId(rm[1]), {name: rm[2]});
       continue;
     }
   }
@@ -133,16 +260,16 @@ export function fromMermaid(text: string): Graph {
     const om = line.match(onHaltRegex);
 
     if (om) {
-      ensureNode(Number(om[1])).overriddenHaltStateId = Number(om[2]);
+      ensureNode(parseMermaidId(om[1])).overriddenHaltStateId = parseMermaidId(om[2]);
       continue;
     }
 
     const tm = line.match(transitionRegex);
 
     if (tm) {
-      const fromId = Number(tm[1]);
+      const fromId = parseMermaidId(tm[1]);
       const label = tm[2];
-      const toId = Number(tm[3]);
+      const toId = parseMermaidId(tm[3]);
 
       const arrowIx = label.indexOf(' → ');
 
@@ -165,12 +292,20 @@ export function fromMermaid(text: string): Graph {
         };
       });
 
-      ensureNode(fromId).transitions.push({pattern, command, nextStateId: toId});
+      const fromNode = ensureNode(fromId);
+      const transitionIx = fromNode.transitions.length;
+
+      fromNode.transitions.push({
+        pattern,
+        command,
+        nextStateId: toId,
+        id: `${fromId}-${transitionIx}`,
+      });
     }
   }
 
   if (initialId === null) {
-    throw new Error('fromMermaid: no initial state (double-paren node) found');
+    throw new Error('fromMermaid: no initial state (round-or-wrapped node) found');
   }
 
   return {initialId, alphabets, nodes};
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 3a7e416..3e98557 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -7,12 +7,12 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1},
-            {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0},
+            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -31,11 +31,11 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1},
+            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1, id: "test-edge"},
           ],
         },
       },
@@ -52,10 +52,10 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null,
-          transitions: [{pattern: '0', command: [{symbol: '·', movement: 'S'}], nextStateId: 0}],
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
+          transitions: [{pattern: '0', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
         },
       },
     };
@@ -72,10 +72,10 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3},
-        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isClonedHalt: false},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isWrapped: false, isClonedHalt: false},
+        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
       },
     };
 
@@ -90,8 +90,8 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
       },
     };
 
@@ -197,8 +197,8 @@ describe('summarizeGraph defensive guards', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isClonedHalt: false},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isWrapped: false, isClonedHalt: false},
       },
     };
 
diff --git a/test/round-trip.spec.ts b/test/round-trip.spec.ts
index 1cccdab..a5a5935 100644
--- a/test/round-trip.spec.ts
+++ b/test/round-trip.spec.ts
@@ -1,8 +1,14 @@
 import {
+  Alphabet,
   State,
   Tape,
+  TapeBlock,
   TuringMachine,
   fromMermaid,
+  haltState,
+  ifOtherSymbol,
+  movements,
+  symbolCommands,
   toMermaid,
 } from '@turing-machine-js/machine';
 import binaryNumbers from '@turing-machine-js/library-binary-numbers';
@@ -88,4 +94,48 @@ describe('toGraph / toMermaid / fromMermaid / fromGraph round trip', () => {
       }
     });
   }
+
+  // Regression for #139: in v6 the wrapper composite name accumulated an extra
+  // `>${override.name}` suffix on each round-trip pass (`scanToX>eraseHere`
+  // → `scanToX>eraseHere>eraseHere` on the second pass), breaking bytewise
+  // stability. v7's emit doesn't carry the composite name in any graph node's
+  // label (only the bare's name appears), so reconstruction recomputes the
+  // composite fresh and the emit is stable.
+  //
+  // Uses the `scanToX(eraseHere)` example from #139's issue body — a simple
+  // single-wrapper case. Shared-bare cases (like minusOne, where the same
+  // bare appears in two wrapper contexts via per-context duplication) have
+  // ids that depend on the wrapper's runtime `#id`; those ids reorder under
+  // sort-by-id across rebuild, which is a separate limitation not in #139's
+  // scope.
+  test('toMermaid round-trip is bytewise stable for wrapped states (regression for #139)', () => {
+    const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    const scanToX = new State({
+      [symbol(['X'])]: {nextState: haltState},
+      [ifOtherSymbol]: {command: {movement: movements.right}},
+    }, 'scanToX');
+
+    const eraseHere = new State({
+      [ifOtherSymbol]: {command: {symbol: symbolCommands.erase}, nextState: haltState},
+    }, 'eraseHere');
+
+    const wrapped = scanToX.withOverriddenHaltState(eraseHere);
+
+    const originalMermaid = toMermaid(State.toGraph(wrapped, tapeBlock));
+    const {start: rebuilt, tapeBlock: rebuiltTapeBlock} = State.fromGraph(fromMermaid(originalMermaid));
+    const reEmittedMermaid = toMermaid(State.toGraph(rebuilt, rebuiltTapeBlock));
+
+    // State IDs auto-reassign on each rebuild, so normalize them before
+    // comparing. v7's emit also uses `cN` for cloned-halt ids and `w_N` for
+    // subgraph names — normalize all three.
+    const normalize = (mermaid: string): string => mermaid
+      .replace(/\bs\d+\b/g, 'sX')
+      .replace(/\bc\d+\b/g, 'cX')
+      .replace(/\bw_\d+\b/g, 'w_X');
+
+    expect(normalize(reEmittedMermaid)).toBe(normalize(originalMermaid));
+  });
 });

From ef249d05e50ba8124a371e6076f5972bed7c8ce8 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 19:52:18 +0300
Subject: [PATCH 005/118] chore(emit): always emit `idle` entry sentinel; drop
 `((round))` initial shape
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an explicit pre-execution marker to every `toMermaid` output:

    idle([idle])
    idle -. enter .-> sN

`idle` is a stadium-shaped sentinel — not a graph node — emitted on every
diagram regardless of whether the initial state is wrapped. The labeled
dotted enter arrow is symmetric with the `onHalt` dotted convention used
by wrapper redirects.

The `((round))` shape on non-wrapped initials is dropped — non-wrapped
initials now render as plain `[name]` square, and the `idle -. enter .->`
arrow is the sole "start here" signal. Avoids the redundant double signal
of the previous (always-emit) version.

`fromMermaid` recovers `initialId` exclusively from the `idle -. enter .->`
arrow. The no-initial error message updates accordingly.

Affects:
- `packages/library-binary-numbers/states.md` regenerated — every algorithm
  picks up the `idle([idle])` + enter arrow lines.
- `packages/library-binary-numbers-bare/states.md` regenerated for the same.
- README's Mermaid examples (Quick Start, Reference cycle, Subroutine
  composition before/after, name-state) all updated to show the new shape;
  notation block at the start of the engine README rewritten.
- graph.spec.ts assertions updated for the new shape.
- Design spec status line updated.

Downstream win: `idle` becomes a stable, predictable anchor for
`machines-demo` rendering. The arrow's `id`-targetable shape lets the
demo highlight "execution is about to start" or visualize entry.

Folds into PR #169 — no breaking-behavior change beyond the emit-format
flip (already in the v7 breaking set).
---
 ...026-05-20-tomermaid-wrapper-emit-design.md |  2 +-
 .../library-binary-numbers-bare/states.md     | 16 ++++--
 packages/library-binary-numbers/states.md     | 40 ++++++++++----
 packages/machine/README.md                    | 20 +++++--
 packages/machine/src/utilities/graph.spec.ts  | 48 ++++++++++++-----
 .../machine/src/utilities/graphFormats.ts     | 52 +++++++++++--------
 6 files changed, 123 insertions(+), 55 deletions(-)

diff --git a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
index 01c5536..e8a450f 100644
--- a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
+++ b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
@@ -1,6 +1,6 @@
 # `toMermaid` wrapped-state emit — design comparison
 
-**Status:** decided — **Variant X with `subgraph` overlay**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))` (visualizing where halt-bound execution lands inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation underway on the `feat/cleaner-wrapper-emit-138` branch.
+**Status:** decided — **Variant X with `subgraph` overlay + `idle` entry sentinel**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))`. The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. A stadium-shaped `idle([idle])` sentinel + labeled dotted arrow `idle -. enter .-> sN` is always emitted to mark the initial state — replaces the old `((round))` shape convention on non-wrapped initials, so the single canonical "start here" signal is the enter arrow. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation in PR [#169](https://github.com/mellonis/turing-machine-js/pull/169).
 
 **Context.** [#138](https://github.com/mellonis/turing-machine-js/issues/138) — clean up the visually-confusing Mermaid output for `withOverriddenHaltState`-wrapped states. [#139](https://github.com/mellonis/turing-machine-js/issues/139) — bytewise round-trip regression for the wrapper name accumulation, naturally fixed by whichever design we pick.
 
diff --git a/packages/library-binary-numbers-bare/states.md b/packages/library-binary-numbers-bare/states.md
index 6ac5d63..9e2e5ca 100644
--- a/packages/library-binary-numbers-bare/states.md
+++ b/packages/library-binary-numbers-bare/states.md
@@ -9,7 +9,9 @@ flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
   s1["plusOneCarry"]
-  s2(("plusOne"))
+  s2["plusOne"]
+  idle([idle])
+  idle -. enter .-> s2
   s1 -- "1 → 0/L" --> s1
   s1 -- "0 → 1/S" --> s0
   s1 -- "- → 1/S" --> s0
@@ -26,7 +28,9 @@ flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
   s3["minusOneBorrow"]
-  s4(("minusOne"))
+  s4["minusOne"]
+  idle([idle])
+  idle -. enter .-> s4
   s3 -- "0 → 1/L" --> s3
   s3 -- "1 → 0/S" --> s0
   s3 -- "- → ·/S" --> s0
@@ -42,7 +46,9 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s5(("invertNumber"))
+  s5["invertNumber"]
+  idle([idle])
+  idle -. enter .-> s5
   s5 -- "0 → 1/R" --> s5
   s5 -- "1 → 0/R" --> s5
   s5 -- "- → ·/S" --> s0
@@ -56,7 +62,9 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","0","1"]]
   s0(((halt)))
-  s6(("normalizeNumber"))
+  s6["normalizeNumber"]
+  idle([idle])
+  idle -. enter .-> s6
   s6 -- "0 → ⌫/R" --> s6
   s6 -- "1 → ·/S" --> s0
   s6 -- "- → 0/S" --> s0
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 52e1407..6f15b61 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -8,7 +8,9 @@
 flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
-  s1(("goToNumber"))
+  s1["goToNumber"]
+  idle([idle])
+  idle -. enter .-> s1
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
 ```
@@ -22,7 +24,9 @@ flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s1["goToNumber"]
-  s2(("goToNextNumber"))
+  s2["goToNextNumber"]
+  idle([idle])
+  idle -. enter .-> s2
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
   s2 -- "* → ·/R" --> s1
@@ -37,7 +41,9 @@ flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s3["goToPreviousNumberInternal"]
-  s4(("goToPreviousNumber"))
+  s4["goToPreviousNumber"]
+  idle([idle])
+  idle -. enter .-> s4
   s3 -- "$ → ·/S" --> s0
   s3 -- "* → ·/L" --> s3
   s4 -- "* → ·/L" --> s3
@@ -52,11 +58,13 @@ flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s6["deleteNumberInternal"]
-  s8(("deleteNumber"))
+  s8["deleteNumber"]
+  idle([idle])
   subgraph w_7["halt frame"]
     s7[["goToNumberStart"]]
     c7(((halt)))
   end
+  idle -. enter .-> s8
   s6 -- "$ → ⌫/S" --> s0
   s6 -- "* → ⌫/R" --> s6
   s7 -- "^ → ·/S" --> c7
@@ -74,7 +82,9 @@ flowchart TD
 flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
-  s5(("goToNumberStart"))
+  s5["goToNumberStart"]
+  idle([idle])
+  idle -. enter .-> s5
   s5 -- "^ → ·/S" --> s0
   s5 -- "* → ·/L" --> s5
 ```
@@ -88,11 +98,13 @@ flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s9["invertNumberGoToNumberWithInversion"]
-  s11(("invertNumber"))
+  s11["invertNumber"]
+  idle([idle])
   subgraph w_10["halt frame"]
     s10[["goToNumberStart"]]
     c10(((halt)))
   end
+  idle -. enter .-> s11
   s9 -- "^ → ·/R" --> s9
   s9 -- "1 → 0/R" --> s9
   s9 -- "0 → 1/R" --> s9
@@ -115,11 +127,13 @@ flowchart TD
   s1["goToNumber"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
-  s15(("normalizeNumber"))
+  s15["normalizeNumber"]
+  idle([idle])
   subgraph w_14["halt frame"]
     s14[["goToNumberStart"]]
     c14(((halt)))
   end
+  idle -. enter .-> s15
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
   s12 -- "- → ^/S" --> s1
@@ -143,7 +157,9 @@ flowchart TD
   s16["plusOneFillZeros"]
   s17["plusOneAddNumberStart"]
   s18["plusOneCaryOne"]
-  s19(("plusOne"))
+  s19["plusOne"]
+  idle([idle])
+  idle -. enter .-> s19
   s16 -- "1 → 0/R" --> s16
   s16 -- "$ → ·/S" --> s0
   s17 -- "- → ^/R" --> s17
@@ -172,7 +188,8 @@ flowchart TD
   s16["plusOneFillZeros"]
   s17["plusOneAddNumberStart"]
   s18["plusOneCaryOne"]
-  s23(("minusOne"))
+  s23["minusOne"]
+  idle([idle])
   subgraph w_10["halt frame"]
     s10[["goToNumberStart"]]
     c10(((halt)))
@@ -193,6 +210,7 @@ flowchart TD
     s22[["invertNumber"]]
     c22(((halt)))
   end
+  idle -. enter .-> s23
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
   s9 -- "^ → ·/R" --> s9
@@ -244,7 +262,8 @@ flowchart TD
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
   s15["normalizeNumber"]
-  s26(("minusOneFast"))
+  s26["minusOneFast"]
+  idle([idle])
   subgraph w_14["halt frame"]
     s14[["goToNumberStart"]]
     c14(((halt)))
@@ -253,6 +272,7 @@ flowchart TD
     s25[["minusOneFastBorrow"]]
     c25(((halt)))
   end
+  idle -. enter .-> s26
   s1 -- "$ → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
   s12 -- "- → ^/S" --> s1
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 42ff5a6..1642302 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -90,13 +90,15 @@ flowchart LR
 flowchart TD
 %% alphabets: [[" ","a","b","c","*"]]
   s0(((halt)))
-  s1(("replaceB"))
+  s1["replaceB"]
+  idle([idle])
+  idle -. enter .-> s1
   s1 -- "b → */R" --> s1
   s1 -- "- → ·/L" --> s0
   s1 -- "* → ·/R" --> s1
 ```
 
-Engine notation: `read → write/move`; `·` = keep, `⌫` = erase, `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `(("round"))` = the initial state passed to `toGraph`; `["square"]` = a state reachable from the initial state.
+Engine notation: `read → write/move`; `·` = keep, `⌫` = erase, `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below.
 
 </details>
 
@@ -270,7 +272,9 @@ The string `toMermaid` produces is a real Mermaid flowchart that renders in-plac
 flowchart TD
 %% alphabets: [[" ","0","1","$"]]
   s0(((halt)))
-  s1(("name"))
+  s1["name"]
+  idle([idle])
+  idle -. enter .-> s1
   s1 -- "1 → 0/R" --> s1
   s1 -- "$ → ·/L" --> s0
 ```
@@ -308,8 +312,10 @@ flowchart LR
 ```mermaid
 flowchart TD
 %% alphabets: [[" ","x","y"]]
-  s1(("a"))
+  s1["a"]
   s2["b"]
+  idle([idle])
+  idle -. enter .-> s1
   s1 -- "x → ·/S" --> s2
   s2 -- "y → ·/S" --> s1
 ```
@@ -429,7 +435,9 @@ flowchart LR
 flowchart TD
 %% alphabets: [[" ","a","b","X"]]
   s0(((halt)))
-  s1(("scanToX"))
+  s1["scanToX"]
+  idle([idle])
+  idle -. enter .-> s1
   s1 -- "X → ·/S" --> s0
   s1 -- "* → ·/R" --> s1
 ```
@@ -441,10 +449,12 @@ flowchart TD
 %% alphabets: [[" ","a","b","X"]]
   s0(((halt)))
   s2["eraseHere"]
+  idle([idle])
   subgraph w_3["halt frame"]
     s3[["scanToX"]]
     c3(((halt)))
   end
+  idle -. enter .-> s3
   s2 -- "* → ⌫/S" --> s0
   s3 -- "X → ·/S" --> c3
   s3 -- "* → ·/R" --> s3
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index c9aa912..b7d7bc8 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -127,7 +127,9 @@ describe('toMermaid', () => {
     expect(out.startsWith('flowchart TD')).toBe(true);
     expect(out).toContain('%% alphabets: [[" ","0","1"]]');
     expect(out).toContain('s0(((halt)))');
-    expect(out).toContain('s1(("entry"))');
+    expect(out).toContain('s1["entry"]');
+    expect(out).toContain('idle([idle])');
+    expect(out).toContain('idle -. enter .-> s1');
     expect(out).toContain('s1 -- "0 → ·/R" --> s1');
     expect(out).toContain('s1 -- "1 → ·/S" --> s0');
   });
@@ -223,21 +225,23 @@ describe('parseMovementLabel', () => {
 });
 
 describe('fromMermaid error paths', () => {
-  test('throws when no initial state (double-paren node) is present', () => {
+  test('throws when no `idle -. enter .-> sN` arrow is present', () => {
     const mermaid = [
       'flowchart TD',
       '%% alphabets: [[" ","0","1"]]',
       '  s0(((halt)))',
     ].join('\n');
 
-    expect(() => fromMermaid(mermaid)).toThrow('fromMermaid: no initial state');
+    expect(() => fromMermaid(mermaid)).toThrow('fromMermaid: no `idle -. enter .-> sN` arrow');
   });
 
   test('throws on a malformed edge label (missing arrow)', () => {
     const mermaid = [
       'flowchart TD',
-      '  s1(("entry"))',
+      '  s1["entry"]',
       '  s0(((halt)))',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
       '  s1 -- "no-arrow-label" --> s0',
     ].join('\n');
 
@@ -247,8 +251,10 @@ describe('fromMermaid error paths', () => {
   test('throws on a malformed command part (missing slash)', () => {
     const mermaid = [
       'flowchart TD',
-      '  s1(("entry"))',
+      '  s1["entry"]',
       '  s0(((halt)))',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
       '  s1 -- "* → noslash" --> s0',
     ].join('\n');
 
@@ -260,13 +266,15 @@ describe('fromMermaid ensureNode update branches', () => {
   // The defensive update branches inside ensureNode (when a node id is
   // declared more than once) only fire if the same id appears in multiple
   // node-declaration lines. Synthetic but valid input.
-  test('a later regular-node declaration updates the name of an already-created initial node', () => {
+  test('a later regular-node declaration updates the name of an already-created node', () => {
     const mermaid = [
       'flowchart TD',
       '%% alphabets: [[" ","0"]]',
-      '  s1(("entry"))',  // initial — creates s1 with name="entry"
-      '  s1["renamed"]',   // regular — fires the name-update branch
+      '  s1["entry"]',     // creates s1 with name="entry"
+      '  s1["renamed"]',   // fires the name-update branch
       '  s0(((halt)))',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
     ].join('\n');
 
     const graph = fromMermaid(mermaid);
@@ -278,9 +286,11 @@ describe('fromMermaid ensureNode update branches', () => {
     const mermaid = [
       'flowchart TD',
       '%% alphabets: [[" ","0"]]',
-      '  s1(("entry"))',     // initial — creates s1 with isHalt=false
-      '  s1(((halt)))',       // halt — fires the isHalt-update branch
+      '  s1["entry"]',     // creates s1 with isHalt=false
+      '  s1(((halt)))',    // halt — fires the isHalt-update branch
       '  s0(((halt)))',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
     ].join('\n');
 
     const graph = fromMermaid(mermaid);
@@ -305,7 +315,9 @@ describe('README example: toMermaid output is stable', () => {
       'flowchart TD',
       '%% alphabets: [[" ","0","1","$"]]',
       '  s0(((halt)))',
-      '  s1(("name"))',
+      '  s1["name"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
       '  s1 -- "1 → 0/R" --> s1',
       '  s1 -- "$ → ·/L" --> s0',
     ].join('\n');
@@ -344,7 +356,9 @@ describe('README diagrams: engine-generated outputs', () => {
       'flowchart TD',
       '%% alphabets: [[" ","a","b","c","*"]]',
       '(((halt)))',
-      '(("replaceB"))',
+      '["replaceB"]', // initial — square (no longer round in v7; idle arrow signals entry)
+      'idle([idle])',
+      'idle -. enter .->',
       '"b → */R"',
       '"- → ·/L"',
       '"* → ·/R"',
@@ -365,8 +379,10 @@ describe('README diagrams: engine-generated outputs', () => {
     expectAllLines(output, [
       'flowchart TD',
       '%% alphabets: [[" ","x","y"]]',
-      '(("a"))', // a is the initial state passed to toGraph → round
+      '["a"]', // a is the initial state — square (idle arrow signals entry)
       '["b"]', // b is reachable from a → square
+      'idle([idle])',
+      'idle -. enter .->',
       '"x → ·/S"',
       '"y → ·/S"',
     ]);
@@ -387,7 +403,9 @@ describe('README diagrams: engine-generated outputs', () => {
       'flowchart TD',
       '%% alphabets: [[" ","a","b","X"]]',
       '(((halt)))',
-      '(("scanToX"))',
+      '["scanToX"]', // initial — square (idle arrow signals entry)
+      'idle([idle])',
+      'idle -. enter .->',
       '"X → ·/S"',
       '"* → ·/R"',
     ]);
@@ -416,6 +434,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '[["scanToX"]]', // wrapper-collapsed bare uses subroutine shape inside the subgraph
       'subgraph w_', // halt-frame subgraph wraps the bare + its cloned halt
       '"halt frame"', // subgraph label
+      'idle([idle])', // pre-execution sentinel — always emitted
+      'idle -. enter .->', // labeled dotted enter arrow points at the initial state
       '"* → ⌫/S"', // eraseHere's erase command
       '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
     ]);
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index eb5cba1..39bc5c7 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -63,6 +63,8 @@ export function toMermaid(graph: Graph): string {
   }
 
   // Emit non-subgraph nodes first: real halt + regular non-wrapped nodes.
+  // No special round-shape `((…))` for the initial — the `idle -. enter .->`
+  // arrow emitted below is the sole "start here" signal.
   for (const node of nodes) {
     if (node.isWrapped || clonedHaltIds.has(node.id)) {
       continue;
@@ -72,13 +74,17 @@ export function toMermaid(graph: Graph): string {
 
     if (node.isHalt) {
       lines.push(`  ${id}(((halt)))`);
-    } else if (node.id === graph.initialId) {
-      lines.push(`  ${id}(("${node.name}"))`);
     } else {
       lines.push(`  ${id}["${node.name}"]`);
     }
   }
 
+  // `idle` sentinel = pre-execution marker for the machine. Always emitted,
+  // with a labeled dotted arrow `idle -. enter .-> sN` to the initial state.
+  // Symmetric with the `onHalt` dotted convention used by wrapper redirects.
+  // Visual-only — `idle` is not a graph node.
+  lines.push('  idle([idle])');
+
   // Emit one subgraph per wrapper, in sorted wrapped-id order.
   for (const wrapped of wrappedNodes) {
     const wrappedMid = mermaidIdFor(wrapped.id);
@@ -95,6 +101,10 @@ export function toMermaid(graph: Graph): string {
     lines.push('  end');
   }
 
+  // Enter arrow: emitted after subgraphs so it visually points at the initial
+  // node (whether plain `[…]` or wrapped `[[…]]` inside a subgraph).
+  lines.push(`  idle -. enter .-> ${mermaidIdFor(graph.initialId)}`);
+
   // Emit transitions per-node in sorted node-id order. Within a node,
   // transitions emit in their stored array order (which mirrors the source
   // state's symbol-map insertion order — stable per State instance).
@@ -134,11 +144,12 @@ export function toMermaid(graph: Graph): string {
 //   as literal symbols, the parser cannot disambiguate. Stick to alphabets
 //   without those characters when round-tripping through Mermaid.
 const haltNodeRegex = /^([sc]\d+)\(\(\(halt\)\)\)$/;
-const initialNodeRegex = /^(s\d+)\(\("([^"]*)"\)\)$/;
 const regularNodeRegex = /^(s\d+)\["([^"]*)"\]$/;
 const wrappedNodeRegex = /^(s\d+)\[\["([^"]*)"\]\]$/;
 const subgraphStartRegex = /^subgraph\s+w_\d+\["([^"]*)"\]$/;
 const subgraphEndRegex = /^end$/;
+const idleNodeRegex = /^idle\(\[idle\]\)$/;
+const enterArrowRegex = /^idle\s+-\.\s+enter\s+\.->\s+(s\d+)$/;
 const transitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
 const onHaltRegex = /^([sc]\d+)\s+-\.\s+onHalt\s+\.->\s+([sc]\d+)$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
@@ -209,6 +220,13 @@ export function fromMermaid(text: string): Graph {
       continue;
     }
 
+    // `idle([idle])` sentinel: a visual pre-execution marker. Not a graph
+    // node — skip declaration, parse the `idle -. enter .-> sN` arrow in the
+    // edge pass to set initialId.
+    if (idleNodeRegex.test(line)) {
+      continue;
+    }
+
     const hm = line.match(haltNodeRegex);
 
     if (hm) {
@@ -227,23 +245,7 @@ export function fromMermaid(text: string): Graph {
     const wm = line.match(wrappedNodeRegex);
 
     if (wm) {
-      const id = parseMermaidId(wm[1]);
-
-      if (initialId === null) {
-        initialId = id;
-      }
-
-      ensureNode(id, {name: wm[2], isWrapped: true});
-      continue;
-    }
-
-    const im = line.match(initialNodeRegex);
-
-    if (im) {
-      const id = parseMermaidId(im[1]);
-
-      initialId = id;
-      ensureNode(id, {name: im[2]});
+      ensureNode(parseMermaidId(wm[1]), {name: wm[2], isWrapped: true});
       continue;
     }
 
@@ -257,6 +259,14 @@ export function fromMermaid(text: string): Graph {
 
   // Second pass: edges.
   for (const line of lines) {
+    // `idle -. enter .-> sN`: the sole source of initialId.
+    const em = line.match(enterArrowRegex);
+
+    if (em) {
+      initialId = parseMermaidId(em[1]);
+      continue;
+    }
+
     const om = line.match(onHaltRegex);
 
     if (om) {
@@ -305,7 +315,7 @@ export function fromMermaid(text: string): Graph {
   }
 
   if (initialId === null) {
-    throw new Error('fromMermaid: no initial state (round-or-wrapped node) found');
+    throw new Error('fromMermaid: no `idle -. enter .-> sN` arrow found');
   }
 
   return {initialId, alphabets, nodes};

From cb13663b7d29a2199e48686f0a2bb4f495bcaed3 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 19:53:57 +0300
Subject: [PATCH 006/118] fix(docs:states): exclude `isClonedHalt` nodes from
 per-algorithm state count
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cloned-halt nodes (one per wrapper context) are visualization-only
sentinels — at runtime they all map to the singleton `haltState`, so
they shouldn't inflate the "N states (including haltState)" header.

Affects only the count text; the rendered Mermaid graph below the
header still shows the cloned halts inside each `halt frame` subgraph
(that's their whole purpose — visualizing where halt-bound transitions
land within a wrapper's scope).

Header counts after the fix (binary-numbers):
- deleteNumber: 5 → 4
- invertNumber: 5 → 4
- normalizeNumber: 7 → 6
- minusOne: 20 → 15
- minusOneFast: 10 → 8

(All others unchanged — no wrappers, no cloned halts.)
---
 packages/library-binary-numbers/states.md | 10 +++++-----
 scripts/build-states-md.mjs               |  5 ++++-
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 6f15b61..7c455e0 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -51,7 +51,7 @@ flowchart TD
 
 ## deleteNumber
 
-*5 states (including `haltState`)*
+*4 states (including `haltState`)*
 
 ```mermaid
 flowchart TD
@@ -91,7 +91,7 @@ flowchart TD
 
 ## invertNumber
 
-*5 states (including `haltState`)*
+*4 states (including `haltState`)*
 
 ```mermaid
 flowchart TD
@@ -118,7 +118,7 @@ flowchart TD
 
 ## normalizeNumber
 
-*7 states (including `haltState`)*
+*6 states (including `haltState`)*
 
 ```mermaid
 flowchart TD
@@ -174,7 +174,7 @@ flowchart TD
 
 ## minusOne
 
-*20 states (including `haltState`)*
+*15 states (including `haltState`)*
 
 ```mermaid
 flowchart TD
@@ -252,7 +252,7 @@ flowchart TD
 
 ## minusOneFast
 
-*10 states (including `haltState`)*
+*8 states (including `haltState`)*
 
 ```mermaid
 flowchart TD
diff --git a/scripts/build-states-md.mjs b/scripts/build-states-md.mjs
index 8918dd8..e8b6aa4 100644
--- a/scripts/build-states-md.mjs
+++ b/scripts/build-states-md.mjs
@@ -66,7 +66,10 @@ if (libName === null) {
     const tapeBlock = library.getTapeBlock();
     const graph = State.toGraph(state, tapeBlock);
     const mermaid = toMermaid(graph);
-    const nodeCount = Object.keys(graph.nodes).length;
+    // Exclude `isClonedHalt: true` nodes from the count — they are
+    // visualization-only sentinels (one per wrapper context, all mapped to the
+    // singleton `haltState` at runtime), not distinct runtime states.
+    const nodeCount = Object.values(graph.nodes).filter((n) => !n.isClonedHalt).length;
 
     sections.push(`## ${stateName}`);
     sections.push('');

From ea8b8e3fa5bc9cb7bc311e4f6208f443155e7ff8 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 20:08:27 +0300
Subject: [PATCH 007/118] refactor(emit)!: readable command/symbol vocabulary
 in edge labels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the Unicode/raw-literal edge-label encoding with a vocabulary
that reads cleanly without out-of-band reference:

Write commands (right of `→`, left of `/`):
- `·` (keep)  → `K`
- `⌫` (erase) → `E`

Literal alphabet symbols (in both read patterns and write positions):
- previously bare: `0`, `X`, `$`
- now quoted:     `'0'`, `'X'`, `'$'`

Unquoted markers (unchanged semantics, unchanged emit):
- `*` per-cell ifOtherSymbol (any symbol)
- `-` the tape's blank symbol

Example before/after:
- `s1 -- "X → ·/S" --> s0`        →  `s1 -- "'X' → K/S" --> s0`
- `s2 -- "* → ⌫/S" --> s0`        →  `s2 -- "* → E/S" --> s0`
- `s1 -- "1 → 0/R" --> s1`        →  `s1 -- "'1' → '0'/R" --> s1`
- `s1 -- "0,a → 0/R,a/L" --> s2`  →  `s1 -- "'0','a' → '0'/R,'a'/L" --> s2`

Why the change:

- `K` / `E` are mnemonic command names (Keep, Erase) that a reader
  unfamiliar with the diagram can guess from the letter alone. The
  Unicode `·` / `⌫` look pretty but require a legend to interpret.
- Quoting literal alphabet symbols visually distinguishes them from
  the convention markers `*` / `-` / `K` / `E`. Eliminates ambiguity
  when an alphabet contains a character that would otherwise collide
  with a marker (e.g. a literal `K` in the alphabet renders as `'K'`,
  unambiguous from the keep command `K`).

Engine changes:

- `decodeWriteSymbol` wraps literal symbols in `'…'`; returns `K` /
  `E` for the keep/erase commands.
- `decodePatternDescription` wraps literal cells in `'…'`; returns
  `*` / `-` for the markers (no quoting).
- `parseWriteSymbolLabel` strips surrounding quotes from literal
  symbols; recognizes `K` / `E` as keep/erase.
- `parsePatternString` strips surrounding quotes from literal cells.
- `escapeAlphabetSymbol` simplified — only escapes `\` and `'` now
  (the other reserved chars are distinguishable via quote presence).

Affects:

- `packages/library-binary-numbers/states.md` regenerated with the
  new vocabulary.
- `packages/library-binary-numbers-bare/states.md` regenerated.
- README "Quick Start" + Subroutine composition Mermaid blocks and
  their narrative legends updated.
- Decoder unit tests + per-state graph fixture tests updated for the
  new label format.
- Spec status line updated.

Round-trip stability (#139) preserved — the new encoding is
deterministic and reversible.
---
 ...026-05-20-tomermaid-wrapper-emit-design.md |   2 +-
 .../library-binary-numbers-bare/states.md     |  32 ++--
 packages/library-binary-numbers/states.md     | 180 +++++++++---------
 packages/machine/README.md                    |  30 +--
 packages/machine/src/classes/State.spec.ts    |   2 +-
 packages/machine/src/utilities/graph.spec.ts  |  70 +++----
 packages/machine/src/utilities/graph.ts       |  38 ++--
 .../src/utilities/introspection.spec.ts       |  10 +-
 8 files changed, 191 insertions(+), 173 deletions(-)

diff --git a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
index e8a450f..6102511 100644
--- a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
+++ b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
@@ -1,6 +1,6 @@
 # `toMermaid` wrapped-state emit — design comparison
 
-**Status:** decided — **Variant X with `subgraph` overlay + `idle` entry sentinel**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))`. The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. A stadium-shaped `idle([idle])` sentinel + labeled dotted arrow `idle -. enter .-> sN` is always emitted to mark the initial state — replaces the old `((round))` shape convention on non-wrapped initials, so the single canonical "start here" signal is the enter arrow. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation in PR [#169](https://github.com/mellonis/turing-machine-js/pull/169).
+**Status:** decided — **Variant X with `subgraph` overlay + `idle` entry sentinel + readable command/symbol vocabulary**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))`. The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. A stadium-shaped `idle([idle])` sentinel + labeled dotted arrow `idle -. enter .-> sN` is always emitted to mark the initial state. Edge-label vocabulary: write commands `K` = keep, `E` = erase (write blank); literal alphabet symbols wrapped in single quotes (`'X'`, `'0'`); unquoted markers `*` = any (ifOtherSymbol), `-` = blank shorthand. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation in PR [#169](https://github.com/mellonis/turing-machine-js/pull/169).
 
 **Context.** [#138](https://github.com/mellonis/turing-machine-js/issues/138) — clean up the visually-confusing Mermaid output for `withOverriddenHaltState`-wrapped states. [#139](https://github.com/mellonis/turing-machine-js/issues/139) — bytewise round-trip regression for the wrapper name accumulation, naturally fixed by whichever design we pick.
 
diff --git a/packages/library-binary-numbers-bare/states.md b/packages/library-binary-numbers-bare/states.md
index 9e2e5ca..02f4628 100644
--- a/packages/library-binary-numbers-bare/states.md
+++ b/packages/library-binary-numbers-bare/states.md
@@ -12,11 +12,11 @@ flowchart TD
   s2["plusOne"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "1 → 0/L" --> s1
-  s1 -- "0 → 1/S" --> s0
-  s1 -- "- → 1/S" --> s0
-  s2 -- "0|1 → ·/R" --> s2
-  s2 -- "- → ·/L" --> s1
+  s1 -- "'1' → '0'/L" --> s1
+  s1 -- "'0' → '1'/S" --> s0
+  s1 -- "- → '1'/S" --> s0
+  s2 -- "'0'|'1' → K/R" --> s2
+  s2 -- "- → K/L" --> s1
 ```
 
 ## minusOne
@@ -31,11 +31,11 @@ flowchart TD
   s4["minusOne"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "0 → 1/L" --> s3
-  s3 -- "1 → 0/S" --> s0
-  s3 -- "- → ·/S" --> s0
-  s4 -- "0|1 → ·/R" --> s4
-  s4 -- "- → ·/L" --> s3
+  s3 -- "'0' → '1'/L" --> s3
+  s3 -- "'1' → '0'/S" --> s0
+  s3 -- "- → K/S" --> s0
+  s4 -- "'0'|'1' → K/R" --> s4
+  s4 -- "- → K/L" --> s3
 ```
 
 ## invertNumber
@@ -49,9 +49,9 @@ flowchart TD
   s5["invertNumber"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "0 → 1/R" --> s5
-  s5 -- "1 → 0/R" --> s5
-  s5 -- "- → ·/S" --> s0
+  s5 -- "'0' → '1'/R" --> s5
+  s5 -- "'1' → '0'/R" --> s5
+  s5 -- "- → K/S" --> s0
 ```
 
 ## normalizeNumber
@@ -65,7 +65,7 @@ flowchart TD
   s6["normalizeNumber"]
   idle([idle])
   idle -. enter .-> s6
-  s6 -- "0 → ⌫/R" --> s6
-  s6 -- "1 → ·/S" --> s0
-  s6 -- "- → 0/S" --> s0
+  s6 -- "'0' → E/R" --> s6
+  s6 -- "'1' → K/S" --> s0
+  s6 -- "- → '0'/S" --> s0
 ```
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 7c455e0..5e5e8ce 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -11,8 +11,8 @@ flowchart TD
   s1["goToNumber"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "$ → ·/S" --> s0
-  s1 -- "* → ·/R" --> s1
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "* → K/R" --> s1
 ```
 
 ## goToNextNumber
@@ -27,9 +27,9 @@ flowchart TD
   s2["goToNextNumber"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "$ → ·/S" --> s0
-  s1 -- "* → ·/R" --> s1
-  s2 -- "* → ·/R" --> s1
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "* → K/R" --> s1
+  s2 -- "* → K/R" --> s1
 ```
 
 ## goToPreviousNumber
@@ -44,9 +44,9 @@ flowchart TD
   s4["goToPreviousNumber"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "$ → ·/S" --> s0
-  s3 -- "* → ·/L" --> s3
-  s4 -- "* → ·/L" --> s3
+  s3 -- "'$' → K/S" --> s0
+  s3 -- "* → K/L" --> s3
+  s4 -- "* → K/L" --> s3
 ```
 
 ## deleteNumber
@@ -65,13 +65,13 @@ flowchart TD
     c7(((halt)))
   end
   idle -. enter .-> s8
-  s6 -- "$ → ⌫/S" --> s0
-  s6 -- "* → ⌫/R" --> s6
-  s7 -- "^ → ·/S" --> c7
-  s7 -- "* → ·/L" --> s7
+  s6 -- "'$' → E/S" --> s0
+  s6 -- "* → E/R" --> s6
+  s7 -- "'^' → K/S" --> c7
+  s7 -- "* → K/L" --> s7
   s7 -. onHalt .-> s6
-  s8 -- "^|1|0|$ → ·/S" --> s7
-  s8 -- "* → ·/S" --> s0
+  s8 -- "'^'|'1'|'0'|'$' → K/S" --> s7
+  s8 -- "* → K/S" --> s0
 ```
 
 ## goToNumbersStart
@@ -85,8 +85,8 @@ flowchart TD
   s5["goToNumberStart"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "^ → ·/S" --> s0
-  s5 -- "* → ·/L" --> s5
+  s5 -- "'^' → K/S" --> s0
+  s5 -- "* → K/L" --> s5
 ```
 
 ## invertNumber
@@ -105,15 +105,15 @@ flowchart TD
     c10(((halt)))
   end
   idle -. enter .-> s11
-  s9 -- "^ → ·/R" --> s9
-  s9 -- "1 → 0/R" --> s9
-  s9 -- "0 → 1/R" --> s9
-  s9 -- "$ → ·/S" --> s0
-  s10 -- "^ → ·/S" --> c10
-  s10 -- "* → ·/L" --> s10
+  s9 -- "'^' → K/R" --> s9
+  s9 -- "'1' → '0'/R" --> s9
+  s9 -- "'0' → '1'/R" --> s9
+  s9 -- "'$' → K/S" --> s0
+  s10 -- "'^' → K/S" --> c10
+  s10 -- "* → K/L" --> s10
   s10 -. onHalt .-> s9
-  s11 -- "^|1|0|$ → ·/S" --> s10
-  s11 -- "* → ·/S" --> s0
+  s11 -- "'^'|'1'|'0'|'$' → K/S" --> s10
+  s11 -- "* → K/S" --> s0
 ```
 
 ## normalizeNumber
@@ -134,16 +134,16 @@ flowchart TD
     c14(((halt)))
   end
   idle -. enter .-> s15
-  s1 -- "$ → ·/S" --> s0
-  s1 -- "* → ·/R" --> s1
-  s12 -- "- → ^/S" --> s1
-  s13 -- "^|0 → ⌫/R" --> s13
-  s13 -- "1|$ → ·/L" --> s12
-  s14 -- "^ → ·/S" --> c14
-  s14 -- "* → ·/L" --> s14
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "* → K/R" --> s1
+  s12 -- "- → '^'/S" --> s1
+  s13 -- "'^'|'0' → E/R" --> s13
+  s13 -- "'1'|'$' → K/L" --> s12
+  s14 -- "'^' → K/S" --> c14
+  s14 -- "* → K/L" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "^|1|0|$ → ·/S" --> s14
-  s15 -- "* → ·/S" --> s0
+  s15 -- "'^'|'1'|'0'|'$' → K/S" --> s14
+  s15 -- "* → K/S" --> s0
 ```
 
 ## plusOne
@@ -160,16 +160,16 @@ flowchart TD
   s19["plusOne"]
   idle([idle])
   idle -. enter .-> s19
-  s16 -- "1 → 0/R" --> s16
-  s16 -- "$ → ·/S" --> s0
-  s17 -- "- → ^/R" --> s17
-  s17 -- "1 → ·/R" --> s16
-  s18 -- "0 → 1/R" --> s16
-  s18 -- "1 → ·/L" --> s18
-  s18 -- "^ → 1/L" --> s17
-  s19 -- "^|1|0 → ·/R" --> s19
-  s19 -- "$ → ·/L" --> s18
-  s19 -- "* → ·/S" --> s0
+  s16 -- "'1' → '0'/R" --> s16
+  s16 -- "'$' → K/S" --> s0
+  s17 -- "- → '^'/R" --> s17
+  s17 -- "'1' → K/R" --> s16
+  s18 -- "'0' → '1'/R" --> s16
+  s18 -- "'1' → K/L" --> s18
+  s18 -- "'^' → '1'/L" --> s17
+  s19 -- "'^'|'1'|'0' → K/R" --> s19
+  s19 -- "'$' → K/L" --> s18
+  s19 -- "* → K/S" --> s0
 ```
 
 ## minusOne
@@ -211,43 +211,43 @@ flowchart TD
     c22(((halt)))
   end
   idle -. enter .-> s23
-  s1 -- "$ → ·/S" --> s0
-  s1 -- "* → ·/R" --> s1
-  s9 -- "^ → ·/R" --> s9
-  s9 -- "1 → 0/R" --> s9
-  s9 -- "0 → 1/R" --> s9
-  s9 -- "$ → ·/S" --> s0
-  s10 -- "^ → ·/S" --> c10
-  s10 -- "* → ·/L" --> s10
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "* → K/R" --> s1
+  s9 -- "'^' → K/R" --> s9
+  s9 -- "'1' → '0'/R" --> s9
+  s9 -- "'0' → '1'/R" --> s9
+  s9 -- "'$' → K/S" --> s0
+  s10 -- "'^' → K/S" --> c10
+  s10 -- "* → K/L" --> s10
   s10 -. onHalt .-> s9
-  s12 -- "- → ^/S" --> s1
-  s13 -- "^|0 → ⌫/R" --> s13
-  s13 -- "1|$ → ·/L" --> s12
-  s14 -- "^ → ·/S" --> c14
-  s14 -- "* → ·/L" --> s14
+  s12 -- "- → '^'/S" --> s1
+  s13 -- "'^'|'0' → E/R" --> s13
+  s13 -- "'1'|'$' → K/L" --> s12
+  s14 -- "'^' → K/S" --> c14
+  s14 -- "* → K/L" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "^|1|0|$ → ·/S" --> s14
-  s15 -- "* → ·/S" --> s0
-  s16 -- "1 → 0/R" --> s16
-  s16 -- "$ → ·/S" --> s0
-  s17 -- "- → ^/R" --> s17
-  s17 -- "1 → ·/R" --> s16
-  s18 -- "0 → 1/R" --> s16
-  s18 -- "1 → ·/L" --> s18
-  s18 -- "^ → 1/L" --> s17
-  s20 -- "^|1|0|$ → ·/S" --> s10
-  s20 -- "* → ·/S" --> c20
+  s15 -- "'^'|'1'|'0'|'$' → K/S" --> s14
+  s15 -- "* → K/S" --> s0
+  s16 -- "'1' → '0'/R" --> s16
+  s16 -- "'$' → K/S" --> s0
+  s17 -- "- → '^'/R" --> s17
+  s17 -- "'1' → K/R" --> s16
+  s18 -- "'0' → '1'/R" --> s16
+  s18 -- "'1' → K/L" --> s18
+  s18 -- "'^' → '1'/L" --> s17
+  s20 -- "'^'|'1'|'0'|'$' → K/S" --> s10
+  s20 -- "* → K/S" --> c20
   s20 -. onHalt .-> s15
-  s21 -- "^|1|0 → ·/R" --> s21
-  s21 -- "$ → ·/L" --> s18
-  s21 -- "* → ·/S" --> c21
+  s21 -- "'^'|'1'|'0' → K/R" --> s21
+  s21 -- "'$' → K/L" --> s18
+  s21 -- "* → K/S" --> c21
   s21 -. onHalt .-> s20
-  s22 -- "^|1|0|$ → ·/S" --> s10
-  s22 -- "* → ·/S" --> c22
+  s22 -- "'^'|'1'|'0'|'$' → K/S" --> s10
+  s22 -- "* → K/S" --> c22
   s22 -. onHalt .-> s21
-  s23 -- "^|1|0 → ·/R" --> s23
-  s23 -- "$ → ·/S" --> s22
-  s23 -- "* → ·/S" --> s0
+  s23 -- "'^'|'1'|'0' → K/R" --> s23
+  s23 -- "'$' → K/S" --> s22
+  s23 -- "* → K/S" --> s0
 ```
 
 ## minusOneFast
@@ -273,21 +273,21 @@ flowchart TD
     c25(((halt)))
   end
   idle -. enter .-> s26
-  s1 -- "$ → ·/S" --> s0
-  s1 -- "* → ·/R" --> s1
-  s12 -- "- → ^/S" --> s1
-  s13 -- "^|0 → ⌫/R" --> s13
-  s13 -- "1|$ → ·/L" --> s12
-  s14 -- "^ → ·/S" --> c14
-  s14 -- "* → ·/L" --> s14
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "* → K/R" --> s1
+  s12 -- "- → '^'/S" --> s1
+  s13 -- "'^'|'0' → E/R" --> s13
+  s13 -- "'1'|'$' → K/L" --> s12
+  s14 -- "'^' → K/S" --> c14
+  s14 -- "* → K/L" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "^|1|0|$ → ·/S" --> s14
-  s15 -- "* → ·/S" --> s0
-  s25 -- "1 → 0/S" --> c25
-  s25 -- "0 → 1/L" --> s25
-  s25 -- "^ → ·/S" --> c25
+  s15 -- "'^'|'1'|'0'|'$' → K/S" --> s14
+  s15 -- "* → K/S" --> s0
+  s25 -- "'1' → '0'/S" --> c25
+  s25 -- "'0' → '1'/L" --> s25
+  s25 -- "'^' → K/S" --> c25
   s25 -. onHalt .-> s15
-  s26 -- "^|1|0 → ·/R" --> s26
-  s26 -- "$ → ·/L" --> s25
-  s26 -- "* → ·/S" --> s0
+  s26 -- "'^'|'1'|'0' → K/R" --> s26
+  s26 -- "'$' → K/L" --> s25
+  s26 -- "* → K/S" --> s0
 ```
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 1642302..06aaa9b 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -93,12 +93,12 @@ flowchart TD
   s1["replaceB"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "b → */R" --> s1
-  s1 -- "- → ·/L" --> s0
-  s1 -- "* → ·/R" --> s1
+  s1 -- "'b' → '*'/R" --> s1
+  s1 -- "- → K/L" --> s0
+  s1 -- "* → K/R" --> s1
 ```
 
-Engine notation: `read → write/move`; `·` = keep, `⌫` = erase, `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below.
+Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Literal alphabet symbols are wrapped in single quotes: `'b'`, `'*'`, `'X'`. Unquoted markers: `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below.
 
 </details>
 
@@ -275,11 +275,11 @@ flowchart TD
   s1["name"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "1 → 0/R" --> s1
-  s1 -- "$ → ·/L" --> s0
+  s1 -- "'1' → '0'/R" --> s1
+  s1 -- "'$' → K/L" --> s0
 ```
 
-*Edge labels are `read → write/move`. `·` is the keep-current-symbol marker (no write); `L` / `R` / `S` are head moves.*
+*Edge labels are `read → write/move`. Write commands: `K` = keep (no write), `E` = erase (write the blank). Literal alphabet symbols are quoted (`'1'`, `'$'`). Movements: `L` / `R` / `S`.*
 
 > 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
 
@@ -316,8 +316,8 @@ flowchart TD
   s2["b"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "x → ·/S" --> s2
-  s2 -- "y → ·/S" --> s1
+  s1 -- "'x' → K/S" --> s2
+  s2 -- "'y' → K/S" --> s1
 ```
 
 `a` is round (the initial state passed to `toGraph`); `b` is square (reachable from `a`).
@@ -438,8 +438,8 @@ flowchart TD
   s1["scanToX"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "X → ·/S" --> s0
-  s1 -- "* → ·/R" --> s1
+  s1 -- "'X' → K/S" --> s0
+  s1 -- "* → K/R" --> s1
 ```
 
 `toMermaid(toGraph(scanThenErase, tapeBlock))` — the wrapped composition:
@@ -455,9 +455,9 @@ flowchart TD
     c3(((halt)))
   end
   idle -. enter .-> s3
-  s2 -- "* → ⌫/S" --> s0
-  s3 -- "X → ·/S" --> c3
-  s3 -- "* → ·/R" --> s3
+  s2 -- "* → E/S" --> s0
+  s3 -- "'X' → K/S" --> c3
+  s3 -- "* → K/R" --> s3
   s3 -. onHalt .-> s2
 ```
 
@@ -469,7 +469,7 @@ flowchart TD
 4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. The single arrow that crosses the subgraph border. Originates from the wrapper-node since the wrapper *is* the catcher.
 5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame — here, by `eraseHere` after it erases the cell.
 
-**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `* → ·/R` self-loops until the head sees `X`; the `X → ·/S` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `* → ⌫/S` and halts at real `s0`. Run terminates.
+**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `* → K/R` self-loops until the head sees `X`; the `'X' → K/S` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `* → E/S` and halts at real `s0`. Run terminates.
 
 > 💡 **Round-trip caveat.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers like this one ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). For shared-bare cases (same `State` instance used as the bare in multiple wrappers — e.g., `library-binary-numbers`'s `minusOne`), per-context duplication produces wrapper-id-dependent ordering that doesn't byte-match across rebuilds — equivalent runtime behavior, different emit-line order.
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index e8f9528..92aac9c 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -232,7 +232,7 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
     // pointing in a loop.
     // Nodes need at least one transition each — State construction at pass 2
     // rejects empty stateDefinitions before pass 3's cycle check would run.
-    const dummyTransition = {pattern: '*', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"};
+    const dummyTransition = {pattern: '*', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"};
     const graph = {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index b7d7bc8..21e3494 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -23,8 +23,8 @@ describe('decodePatternDescription', () => {
     expect(decodePatternDescription('other symbol', alphabets)).toBe('*');
   });
 
-  test('literal cell', () => {
-    expect(decodePatternDescription('[["0"]]', alphabets)).toBe('0');
+  test('literal cell wraps in single quotes', () => {
+    expect(decodePatternDescription('[["0"]]', alphabets)).toBe("'0'");
   });
 
   test('per-cell null → "*"', () => {
@@ -35,31 +35,35 @@ describe('decodePatternDescription', () => {
     expect(decodePatternDescription('[[" "]]', alphabets)).toBe('-');
   });
 
-  test('multi-tape pattern joins cells with ","', () => {
+  test('multi-tape pattern joins quoted cells with ","', () => {
     expect(decodePatternDescription(
       '[["0","a"]]',
       [[' ', '0', '1'], [' ', 'a', 'b']],
-    )).toBe('0,a');
+    )).toBe("'0','a'");
   });
 
   test('alternative patterns join with "|"', () => {
-    expect(decodePatternDescription('[["0"],["1"]]', alphabets)).toBe('0|1');
+    expect(decodePatternDescription('[["0"],["1"]]', alphabets)).toBe("'0'|'1'");
   });
 
-  test('reserved char "*" is escaped as "\\*"', () => {
-    expect(decodePatternDescription('[["*"]]', [[' ', '*', 'x']])).toBe('\\*');
+  test('literal "*" is quoted (distinguishes from per-cell ifOtherSymbol marker)', () => {
+    expect(decodePatternDescription('[["*"]]', [[' ', '*', 'x']])).toBe("'*'");
   });
 
-  test('reserved char "," is escaped as "\\,"', () => {
-    expect(decodePatternDescription('[[","]]', [[' ', ',', 'x']])).toBe('\\,');
+  test('literal "," is quoted (distinguishes from cell separator)', () => {
+    expect(decodePatternDescription('[[","]]', [[' ', ',', 'x']])).toBe("','");
   });
 
-  test('reserved char "|" is escaped as "\\|"', () => {
-    expect(decodePatternDescription('[["|"]]', [[' ', '|', 'x']])).toBe('\\|');
+  test('literal "|" is quoted (distinguishes from alternative separator)', () => {
+    expect(decodePatternDescription('[["|"]]', [[' ', '|', 'x']])).toBe("'|'");
   });
 
-  test('backslash is escaped as "\\\\"', () => {
-    expect(decodePatternDescription('[["\\\\"]]', [[' ', '\\', 'x']])).toBe('\\\\');
+  test('backslash inside quotes is escaped as "\\\\"', () => {
+    expect(decodePatternDescription('[["\\\\"]]', [[' ', '\\', 'x']])).toBe("'\\\\'");
+  });
+
+  test('literal apostrophe is escaped inside quotes as \\\'', () => {
+    expect(decodePatternDescription('[["\'"]]', [[' ', "'", 'x']])).toBe("'\\\''");
   });
 
   test('malformed JSON → returned as-is', () => {
@@ -86,16 +90,16 @@ describe('decodeMovement', () => {
 });
 
 describe('decodeWriteSymbol', () => {
-  test('symbolCommands.keep → "·"', () => {
-    expect(decodeWriteSymbol(symbolCommands.keep)).toBe('·');
+  test('symbolCommands.keep → "K"', () => {
+    expect(decodeWriteSymbol(symbolCommands.keep)).toBe('K');
   });
 
-  test('symbolCommands.erase → "⌫"', () => {
-    expect(decodeWriteSymbol(symbolCommands.erase)).toBe('⌫');
+  test('symbolCommands.erase → "E"', () => {
+    expect(decodeWriteSymbol(symbolCommands.erase)).toBe('E');
   });
 
-  test('literal string is returned as-is', () => {
-    expect(decodeWriteSymbol('0')).toBe('0');
+  test('literal string is wrapped in single quotes', () => {
+    expect(decodeWriteSymbol('0')).toBe("'0'");
   });
 
   test('symbol with no description → "?"', () => {
@@ -117,8 +121,8 @@ describe('toMermaid', () => {
         1: {
           id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1, id: "test-edge"},
-            {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -130,8 +134,8 @@ describe('toMermaid', () => {
     expect(out).toContain('s1["entry"]');
     expect(out).toContain('idle([idle])');
     expect(out).toContain('idle -. enter .-> s1');
-    expect(out).toContain('s1 -- "0 → ·/R" --> s1');
-    expect(out).toContain('s1 -- "1 → ·/S" --> s0');
+    expect(out).toContain('s1 -- "0 → K/R" --> s1');
+    expect(out).toContain('s1 -- "1 → K/S" --> s0');
   });
 
   test('renders dotted onHalt edge when overriddenHaltStateId is set', () => {
@@ -318,8 +322,8 @@ describe('README example: toMermaid output is stable', () => {
       '  s1["name"]',
       '  idle([idle])',
       '  idle -. enter .-> s1',
-      '  s1 -- "1 → 0/R" --> s1',
-      '  s1 -- "$ → ·/L" --> s0',
+      "  s1 -- \"'1' → '0'/R\" --> s1",
+      "  s1 -- \"'$' → K/L\" --> s0",
     ].join('\n');
 
     expect(toMermaid(State.toGraph(s, tapeBlock))).toBe(expected);
@@ -359,9 +363,9 @@ describe('README diagrams: engine-generated outputs', () => {
       '["replaceB"]', // initial — square (no longer round in v7; idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      '"b → */R"',
-      '"- → ·/L"',
-      '"* → ·/R"',
+      "\"'b' → '*'/R\"",
+      '"- → K/L"',
+      '"* → K/R"',
     ]);
   });
 
@@ -383,8 +387,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["b"]', // b is reachable from a → square
       'idle([idle])',
       'idle -. enter .->',
-      '"x → ·/S"',
-      '"y → ·/S"',
+      "\"'x' → K/S\"",
+      "\"'y' → K/S\"",
     ]);
   });
 
@@ -406,8 +410,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["scanToX"]', // initial — square (idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      '"X → ·/S"',
-      '"* → ·/R"',
+      "\"'X' → K/S\"",
+      '"* → K/R"',
     ]);
   });
 
@@ -436,7 +440,7 @@ describe('README diagrams: engine-generated outputs', () => {
       '"halt frame"', // subgraph label
       'idle([idle])', // pre-execution sentinel — always emitted
       'idle -. enter .->', // labeled dotted enter arrow points at the initial state
-      '"* → ⌫/S"', // eraseHere's erase command
+      '"* → E/S"', // eraseHere's erase command
       '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
     ]);
   });
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index eb21efb..ee29eaa 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -42,8 +42,8 @@ const movementDescriptionToLabel: Record<string, string> = {
 };
 
 const symbolCommandDescriptionToLabel: Record<string, string> = {
-  'keep symbol command': '·',
-  'erase symbol command': '⌫',
+  'keep symbol command': 'K',
+  'erase symbol command': 'E',
 };
 
 // Reserved characters in the encoded pattern string:
@@ -51,15 +51,17 @@ const symbolCommandDescriptionToLabel: Record<string, string> = {
 //   '-'  the tape's blank symbol
 //   ','  separates per-tape cells inside one pattern
 //   '|'  separates alternative patterns
-//   '\\' escape prefix — to represent any of '*', '-', ',', '|', or '\\' as a
-//        *literal* alphabet symbol, prefix it with '\\' (e.g. '\\*' for literal '*').
+//   "'"  surrounds a literal alphabet symbol — e.g. `'0'` for literal `0`,
+//        `'X'` for literal `X`. The quoting is what visually separates literal
+//        symbols from the convention markers `*` / `-` and from the write
+//        commands `K` / `E`.
+//   '\\' escape prefix — to represent any of '*', '-', ',', '|', "'", or '\\'
+//        as a *literal* alphabet symbol *inside* the quotes (e.g. `'\''` for
+//        a literal apostrophe).
 function escapeAlphabetSymbol(s: string): string {
   return s
     .replace(/\\/g, '\\\\')
-    .replace(/\*/g, '\\*')
-    .replace(/-/g, '\\-')
-    .replace(/,/g, '\\,')
-    .replace(/\|/g, '\\|');
+    .replace(/'/g, "\\'");
 }
 
 export function decodePatternDescription(
@@ -88,7 +90,7 @@ export function decodePatternDescription(
             return '-';
           }
 
-          return escapeAlphabetSymbol(s);
+          return `'${escapeAlphabetSymbol(s)}'`;
         })
         .join(','))
       .join('|');
@@ -153,6 +155,12 @@ export function parsePatternString(s: string, alphabets: string[][]): ParsedPatt
         return alphabets[tapeIx]?.[0] ?? cell;
       }
 
+      // Literal alphabet symbols are wrapped in single quotes by
+      // `decodePatternDescription` — strip them on the way back.
+      if (cell.length >= 2 && cell.startsWith("'") && cell.endsWith("'")) {
+        return cell.slice(1, -1);
+      }
+
       return cell;
     });
   });
@@ -175,14 +183,20 @@ export function parseMovementLabel(label: string): symbol {
 }
 
 export function parseWriteSymbolLabel(label: string): string | symbol {
-  if (label === '·') {
+  if (label === 'K') {
     return symbolCommands.keep;
   }
 
-  if (label === '⌫') {
+  if (label === 'E') {
     return symbolCommands.erase;
   }
 
+  // Literal alphabet symbols are wrapped in single quotes by
+  // `decodeWriteSymbol` — strip them on the way back.
+  if (label.length >= 2 && label.startsWith("'") && label.endsWith("'")) {
+    return label.slice(1, -1);
+  }
+
   return label;
 }
 
@@ -193,7 +207,7 @@ export function decodeWriteSymbol(symbol: string | symbol): string {
     return symbolCommandDescriptionToLabel[description] ?? description;
   }
 
-  return symbol;
+  return `'${symbol}'`;
 }
 
 // Format converters (toMermaid / fromMermaid) live in ./graphFormats.
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 3e98557..17347db 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -11,8 +11,8 @@ describe('summarizeGraph', () => {
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1, id: "test-edge"},
-            {pattern: '1', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -35,7 +35,7 @@ describe('summarizeGraph', () => {
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: '·', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
           ],
         },
       },
@@ -55,7 +55,7 @@ describe('summarizeGraph', () => {
         0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
-          transitions: [{pattern: '0', command: [{symbol: '·', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
+          transitions: [{pattern: '0', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
         },
       },
     };
@@ -123,7 +123,7 @@ describe('State.inspect', () => {
     const haltTransition = info.transitions.find((t) => t.nextState?.name === haltState.name);
     expect(haltTransition).toBeTruthy();
     expect(haltTransition!.command[0].movement).toBe('R');
-    expect(haltTransition!.command[0].symbol).toBe('1');
+    expect(haltTransition!.command[0].symbol).toBe("'1'");
   });
 
   test('returns override-halt info when set', async () => {

From 47c889296776c454692fca5ca769c17382939e9c Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 20:20:18 +0300
Subject: [PATCH 008/118] =?UTF-8?q?refactor(emit)!:=20distinct=20unicode?=
 =?UTF-8?q?=20markers=20=E2=80=94=20=E2=88=97=20for=20ifOtherSymbol,=20?=
 =?UTF-8?q?=E2=86=90/=E2=86=92/=E2=87=B9=20for=20movements?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two readability tweaks to the edge-label vocabulary:

1. The `ifOtherSymbol` catch-all marker changes from ASCII `*` (U+002A)
   to `∗` (U+2217 ASTERISK OPERATOR). A taller, thinner asterisk that
   is visually distinct from a quoted-literal `'*'`, so an alphabet
   containing literal `*` (rendered as `'*'`) is unambiguous from the
   catch-all marker.

2. Movement labels swap their letter codes for directional Unicode
   arrows:
   - `R` → `→` (U+2192 RIGHTWARDS ARROW)
   - `L` → `←` (U+2190 LEFTWARDS ARROW)
   - `S` → `⇹` (U+21F9 LEFT RIGHT OPEN-HEADED ARROW)

   The arrows read at a glance and reinforce the spatial intuition
   of head movement. The right-arrow `→` is the same glyph used by
   the read-to-write separator, but the parser keys on the spaced
   ` → ` (the separator) versus unspaced `→` (the movement) so
   parsing stays unambiguous.

Example edge labels:

Before:    s1 -- "X → ·/R" --> s0
           s1 -- "* → ⌫/S" --> s0
After:     s1 -- "'X' → K/→" --> s0
           s1 -- "∗ → E/⇹" --> s0

Engine changes:
- `decodePatternDescription` returns `∗` (not `*`) for the
  ifOtherSymbol marker.
- `parsePatternString` recognizes `∗` (not `*`) as the marker.
- `decodeMovement` returns `←` / `→` / `⇹` (not `L` / `R` / `S`).
- `parseMovementLabel` recognizes the three arrows.
- `escapeAlphabetSymbol` no longer needs to escape `*` / `,` / `|`
  (quoting is what disambiguates literals from markers now); only
  `\` and `'` need escaping inside the quotes.

Affects:
- `states.md` regenerated for both binary libraries.
- README "Quick Start" + Subroutine composition Mermaid blocks +
  legends updated.
- Decoder / parser unit tests + per-state graph fixture tests
  updated for the new vocabulary.

Round-trip stability (#139) preserved.
---
 .../library-binary-numbers-bare/states.md     |  32 ++--
 packages/library-binary-numbers/states.md     | 180 +++++++++---------
 packages/machine/README.md                    |  30 +--
 packages/machine/src/classes/State.spec.ts    |   2 +-
 packages/machine/src/utilities/graph.spec.ts  |  64 +++----
 packages/machine/src/utilities/graph.ts       |  37 ++--
 .../src/utilities/introspection.spec.ts       |  10 +-
 7 files changed, 183 insertions(+), 172 deletions(-)

diff --git a/packages/library-binary-numbers-bare/states.md b/packages/library-binary-numbers-bare/states.md
index 02f4628..46e19b9 100644
--- a/packages/library-binary-numbers-bare/states.md
+++ b/packages/library-binary-numbers-bare/states.md
@@ -12,11 +12,11 @@ flowchart TD
   s2["plusOne"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "'1' → '0'/L" --> s1
-  s1 -- "'0' → '1'/S" --> s0
-  s1 -- "- → '1'/S" --> s0
-  s2 -- "'0'|'1' → K/R" --> s2
-  s2 -- "- → K/L" --> s1
+  s1 -- "'1' → '0'/←" --> s1
+  s1 -- "'0' → '1'/⇹" --> s0
+  s1 -- "- → '1'/⇹" --> s0
+  s2 -- "'0'|'1' → K/→" --> s2
+  s2 -- "- → K/←" --> s1
 ```
 
 ## minusOne
@@ -31,11 +31,11 @@ flowchart TD
   s4["minusOne"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "'0' → '1'/L" --> s3
-  s3 -- "'1' → '0'/S" --> s0
-  s3 -- "- → K/S" --> s0
-  s4 -- "'0'|'1' → K/R" --> s4
-  s4 -- "- → K/L" --> s3
+  s3 -- "'0' → '1'/←" --> s3
+  s3 -- "'1' → '0'/⇹" --> s0
+  s3 -- "- → K/⇹" --> s0
+  s4 -- "'0'|'1' → K/→" --> s4
+  s4 -- "- → K/←" --> s3
 ```
 
 ## invertNumber
@@ -49,9 +49,9 @@ flowchart TD
   s5["invertNumber"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "'0' → '1'/R" --> s5
-  s5 -- "'1' → '0'/R" --> s5
-  s5 -- "- → K/S" --> s0
+  s5 -- "'0' → '1'/→" --> s5
+  s5 -- "'1' → '0'/→" --> s5
+  s5 -- "- → K/⇹" --> s0
 ```
 
 ## normalizeNumber
@@ -65,7 +65,7 @@ flowchart TD
   s6["normalizeNumber"]
   idle([idle])
   idle -. enter .-> s6
-  s6 -- "'0' → E/R" --> s6
-  s6 -- "'1' → K/S" --> s0
-  s6 -- "- → '0'/S" --> s0
+  s6 -- "'0' → E/→" --> s6
+  s6 -- "'1' → K/⇹" --> s0
+  s6 -- "- → '0'/⇹" --> s0
 ```
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 5e5e8ce..c96389c 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -11,8 +11,8 @@ flowchart TD
   s1["goToNumber"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "* → K/R" --> s1
+  s1 -- "'$' → K/⇹" --> s0
+  s1 -- "∗ → K/→" --> s1
 ```
 
 ## goToNextNumber
@@ -27,9 +27,9 @@ flowchart TD
   s2["goToNextNumber"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "* → K/R" --> s1
-  s2 -- "* → K/R" --> s1
+  s1 -- "'$' → K/⇹" --> s0
+  s1 -- "∗ → K/→" --> s1
+  s2 -- "∗ → K/→" --> s1
 ```
 
 ## goToPreviousNumber
@@ -44,9 +44,9 @@ flowchart TD
   s4["goToPreviousNumber"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "'$' → K/S" --> s0
-  s3 -- "* → K/L" --> s3
-  s4 -- "* → K/L" --> s3
+  s3 -- "'$' → K/⇹" --> s0
+  s3 -- "∗ → K/←" --> s3
+  s4 -- "∗ → K/←" --> s3
 ```
 
 ## deleteNumber
@@ -65,13 +65,13 @@ flowchart TD
     c7(((halt)))
   end
   idle -. enter .-> s8
-  s6 -- "'$' → E/S" --> s0
-  s6 -- "* → E/R" --> s6
-  s7 -- "'^' → K/S" --> c7
-  s7 -- "* → K/L" --> s7
+  s6 -- "'$' → E/⇹" --> s0
+  s6 -- "∗ → E/→" --> s6
+  s7 -- "'^' → K/⇹" --> c7
+  s7 -- "∗ → K/←" --> s7
   s7 -. onHalt .-> s6
-  s8 -- "'^'|'1'|'0'|'$' → K/S" --> s7
-  s8 -- "* → K/S" --> s0
+  s8 -- "'^'|'1'|'0'|'$' → K/⇹" --> s7
+  s8 -- "∗ → K/⇹" --> s0
 ```
 
 ## goToNumbersStart
@@ -85,8 +85,8 @@ flowchart TD
   s5["goToNumberStart"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "'^' → K/S" --> s0
-  s5 -- "* → K/L" --> s5
+  s5 -- "'^' → K/⇹" --> s0
+  s5 -- "∗ → K/←" --> s5
 ```
 
 ## invertNumber
@@ -105,15 +105,15 @@ flowchart TD
     c10(((halt)))
   end
   idle -. enter .-> s11
-  s9 -- "'^' → K/R" --> s9
-  s9 -- "'1' → '0'/R" --> s9
-  s9 -- "'0' → '1'/R" --> s9
-  s9 -- "'$' → K/S" --> s0
-  s10 -- "'^' → K/S" --> c10
-  s10 -- "* → K/L" --> s10
+  s9 -- "'^' → K/→" --> s9
+  s9 -- "'1' → '0'/→" --> s9
+  s9 -- "'0' → '1'/→" --> s9
+  s9 -- "'$' → K/⇹" --> s0
+  s10 -- "'^' → K/⇹" --> c10
+  s10 -- "∗ → K/←" --> s10
   s10 -. onHalt .-> s9
-  s11 -- "'^'|'1'|'0'|'$' → K/S" --> s10
-  s11 -- "* → K/S" --> s0
+  s11 -- "'^'|'1'|'0'|'$' → K/⇹" --> s10
+  s11 -- "∗ → K/⇹" --> s0
 ```
 
 ## normalizeNumber
@@ -134,16 +134,16 @@ flowchart TD
     c14(((halt)))
   end
   idle -. enter .-> s15
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "* → K/R" --> s1
-  s12 -- "- → '^'/S" --> s1
-  s13 -- "'^'|'0' → E/R" --> s13
-  s13 -- "'1'|'$' → K/L" --> s12
-  s14 -- "'^' → K/S" --> c14
-  s14 -- "* → K/L" --> s14
+  s1 -- "'$' → K/⇹" --> s0
+  s1 -- "∗ → K/→" --> s1
+  s12 -- "- → '^'/⇹" --> s1
+  s13 -- "'^'|'0' → E/→" --> s13
+  s13 -- "'1'|'$' → K/←" --> s12
+  s14 -- "'^' → K/⇹" --> c14
+  s14 -- "∗ → K/←" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "'^'|'1'|'0'|'$' → K/S" --> s14
-  s15 -- "* → K/S" --> s0
+  s15 -- "'^'|'1'|'0'|'$' → K/⇹" --> s14
+  s15 -- "∗ → K/⇹" --> s0
 ```
 
 ## plusOne
@@ -160,16 +160,16 @@ flowchart TD
   s19["plusOne"]
   idle([idle])
   idle -. enter .-> s19
-  s16 -- "'1' → '0'/R" --> s16
-  s16 -- "'$' → K/S" --> s0
-  s17 -- "- → '^'/R" --> s17
-  s17 -- "'1' → K/R" --> s16
-  s18 -- "'0' → '1'/R" --> s16
-  s18 -- "'1' → K/L" --> s18
-  s18 -- "'^' → '1'/L" --> s17
-  s19 -- "'^'|'1'|'0' → K/R" --> s19
-  s19 -- "'$' → K/L" --> s18
-  s19 -- "* → K/S" --> s0
+  s16 -- "'1' → '0'/→" --> s16
+  s16 -- "'$' → K/⇹" --> s0
+  s17 -- "- → '^'/→" --> s17
+  s17 -- "'1' → K/→" --> s16
+  s18 -- "'0' → '1'/→" --> s16
+  s18 -- "'1' → K/←" --> s18
+  s18 -- "'^' → '1'/←" --> s17
+  s19 -- "'^'|'1'|'0' → K/→" --> s19
+  s19 -- "'$' → K/←" --> s18
+  s19 -- "∗ → K/⇹" --> s0
 ```
 
 ## minusOne
@@ -211,43 +211,43 @@ flowchart TD
     c22(((halt)))
   end
   idle -. enter .-> s23
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "* → K/R" --> s1
-  s9 -- "'^' → K/R" --> s9
-  s9 -- "'1' → '0'/R" --> s9
-  s9 -- "'0' → '1'/R" --> s9
-  s9 -- "'$' → K/S" --> s0
-  s10 -- "'^' → K/S" --> c10
-  s10 -- "* → K/L" --> s10
+  s1 -- "'$' → K/⇹" --> s0
+  s1 -- "∗ → K/→" --> s1
+  s9 -- "'^' → K/→" --> s9
+  s9 -- "'1' → '0'/→" --> s9
+  s9 -- "'0' → '1'/→" --> s9
+  s9 -- "'$' → K/⇹" --> s0
+  s10 -- "'^' → K/⇹" --> c10
+  s10 -- "∗ → K/←" --> s10
   s10 -. onHalt .-> s9
-  s12 -- "- → '^'/S" --> s1
-  s13 -- "'^'|'0' → E/R" --> s13
-  s13 -- "'1'|'$' → K/L" --> s12
-  s14 -- "'^' → K/S" --> c14
-  s14 -- "* → K/L" --> s14
+  s12 -- "- → '^'/⇹" --> s1
+  s13 -- "'^'|'0' → E/→" --> s13
+  s13 -- "'1'|'$' → K/←" --> s12
+  s14 -- "'^' → K/⇹" --> c14
+  s14 -- "∗ → K/←" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "'^'|'1'|'0'|'$' → K/S" --> s14
-  s15 -- "* → K/S" --> s0
-  s16 -- "'1' → '0'/R" --> s16
-  s16 -- "'$' → K/S" --> s0
-  s17 -- "- → '^'/R" --> s17
-  s17 -- "'1' → K/R" --> s16
-  s18 -- "'0' → '1'/R" --> s16
-  s18 -- "'1' → K/L" --> s18
-  s18 -- "'^' → '1'/L" --> s17
-  s20 -- "'^'|'1'|'0'|'$' → K/S" --> s10
-  s20 -- "* → K/S" --> c20
+  s15 -- "'^'|'1'|'0'|'$' → K/⇹" --> s14
+  s15 -- "∗ → K/⇹" --> s0
+  s16 -- "'1' → '0'/→" --> s16
+  s16 -- "'$' → K/⇹" --> s0
+  s17 -- "- → '^'/→" --> s17
+  s17 -- "'1' → K/→" --> s16
+  s18 -- "'0' → '1'/→" --> s16
+  s18 -- "'1' → K/←" --> s18
+  s18 -- "'^' → '1'/←" --> s17
+  s20 -- "'^'|'1'|'0'|'$' → K/⇹" --> s10
+  s20 -- "∗ → K/⇹" --> c20
   s20 -. onHalt .-> s15
-  s21 -- "'^'|'1'|'0' → K/R" --> s21
-  s21 -- "'$' → K/L" --> s18
-  s21 -- "* → K/S" --> c21
+  s21 -- "'^'|'1'|'0' → K/→" --> s21
+  s21 -- "'$' → K/←" --> s18
+  s21 -- "∗ → K/⇹" --> c21
   s21 -. onHalt .-> s20
-  s22 -- "'^'|'1'|'0'|'$' → K/S" --> s10
-  s22 -- "* → K/S" --> c22
+  s22 -- "'^'|'1'|'0'|'$' → K/⇹" --> s10
+  s22 -- "∗ → K/⇹" --> c22
   s22 -. onHalt .-> s21
-  s23 -- "'^'|'1'|'0' → K/R" --> s23
-  s23 -- "'$' → K/S" --> s22
-  s23 -- "* → K/S" --> s0
+  s23 -- "'^'|'1'|'0' → K/→" --> s23
+  s23 -- "'$' → K/⇹" --> s22
+  s23 -- "∗ → K/⇹" --> s0
 ```
 
 ## minusOneFast
@@ -273,21 +273,21 @@ flowchart TD
     c25(((halt)))
   end
   idle -. enter .-> s26
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "* → K/R" --> s1
-  s12 -- "- → '^'/S" --> s1
-  s13 -- "'^'|'0' → E/R" --> s13
-  s13 -- "'1'|'$' → K/L" --> s12
-  s14 -- "'^' → K/S" --> c14
-  s14 -- "* → K/L" --> s14
+  s1 -- "'$' → K/⇹" --> s0
+  s1 -- "∗ → K/→" --> s1
+  s12 -- "- → '^'/⇹" --> s1
+  s13 -- "'^'|'0' → E/→" --> s13
+  s13 -- "'1'|'$' → K/←" --> s12
+  s14 -- "'^' → K/⇹" --> c14
+  s14 -- "∗ → K/←" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "'^'|'1'|'0'|'$' → K/S" --> s14
-  s15 -- "* → K/S" --> s0
-  s25 -- "'1' → '0'/S" --> c25
-  s25 -- "'0' → '1'/L" --> s25
-  s25 -- "'^' → K/S" --> c25
+  s15 -- "'^'|'1'|'0'|'$' → K/⇹" --> s14
+  s15 -- "∗ → K/⇹" --> s0
+  s25 -- "'1' → '0'/⇹" --> c25
+  s25 -- "'0' → '1'/←" --> s25
+  s25 -- "'^' → K/⇹" --> c25
   s25 -. onHalt .-> s15
-  s26 -- "'^'|'1'|'0' → K/R" --> s26
-  s26 -- "'$' → K/L" --> s25
-  s26 -- "* → K/S" --> s0
+  s26 -- "'^'|'1'|'0' → K/→" --> s26
+  s26 -- "'$' → K/←" --> s25
+  s26 -- "∗ → K/⇹" --> s0
 ```
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 06aaa9b..b42d1f3 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -93,12 +93,12 @@ flowchart TD
   s1["replaceB"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'b' → '*'/R" --> s1
-  s1 -- "- → K/L" --> s0
-  s1 -- "* → K/R" --> s1
+  s1 -- "'b' → '*'/→" --> s1
+  s1 -- "- → K/←" --> s0
+  s1 -- "∗ → K/→" --> s1
 ```
 
-Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Literal alphabet symbols are wrapped in single quotes: `'b'`, `'*'`, `'X'`. Unquoted markers: `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below.
+Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Movements: `→` = right, `←` = left, `⇹` = stay. Literal alphabet symbols are wrapped in single quotes: `'b'`, `'*'`, `'X'`. Unquoted markers: `∗` (U+2217 asterisk-operator) = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below.
 
 </details>
 
@@ -275,11 +275,11 @@ flowchart TD
   s1["name"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'1' → '0'/R" --> s1
-  s1 -- "'$' → K/L" --> s0
+  s1 -- "'1' → '0'/→" --> s1
+  s1 -- "'$' → K/←" --> s0
 ```
 
-*Edge labels are `read → write/move`. Write commands: `K` = keep (no write), `E` = erase (write the blank). Literal alphabet symbols are quoted (`'1'`, `'$'`). Movements: `L` / `R` / `S`.*
+*Edge labels are `read → write/move`. Write commands: `K` = keep (no write), `E` = erase (write the blank). Literal alphabet symbols are quoted (`'1'`, `'$'`). Movements: `←` (left), `→` (right), `⇹` (stay).*
 
 > 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
 
@@ -316,8 +316,8 @@ flowchart TD
   s2["b"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'x' → K/S" --> s2
-  s2 -- "'y' → K/S" --> s1
+  s1 -- "'x' → K/⇹" --> s2
+  s2 -- "'y' → K/⇹" --> s1
 ```
 
 `a` is round (the initial state passed to `toGraph`); `b` is square (reachable from `a`).
@@ -438,8 +438,8 @@ flowchart TD
   s1["scanToX"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'X' → K/S" --> s0
-  s1 -- "* → K/R" --> s1
+  s1 -- "'X' → K/⇹" --> s0
+  s1 -- "∗ → K/→" --> s1
 ```
 
 `toMermaid(toGraph(scanThenErase, tapeBlock))` — the wrapped composition:
@@ -455,9 +455,9 @@ flowchart TD
     c3(((halt)))
   end
   idle -. enter .-> s3
-  s2 -- "* → E/S" --> s0
-  s3 -- "'X' → K/S" --> c3
-  s3 -- "* → K/R" --> s3
+  s2 -- "∗ → E/⇹" --> s0
+  s3 -- "'X' → K/⇹" --> c3
+  s3 -- "∗ → K/→" --> s3
   s3 -. onHalt .-> s2
 ```
 
@@ -469,7 +469,7 @@ flowchart TD
 4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. The single arrow that crosses the subgraph border. Originates from the wrapper-node since the wrapper *is* the catcher.
 5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame — here, by `eraseHere` after it erases the cell.
 
-**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `* → K/R` self-loops until the head sees `X`; the `'X' → K/S` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `* → E/S` and halts at real `s0`. Run terminates.
+**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `∗ → K/→` self-loops until the head sees `X`; the `'X' → K/⇹` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `∗ → E/⇹` and halts at real `s0`. Run terminates.
 
 > 💡 **Round-trip caveat.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers like this one ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). For shared-bare cases (same `State` instance used as the bare in multiple wrappers — e.g., `library-binary-numbers`'s `minusOne`), per-context duplication produces wrapper-id-dependent ordering that doesn't byte-match across rebuilds — equivalent runtime behavior, different emit-line order.
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 92aac9c..7767f07 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -232,7 +232,7 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
     // pointing in a loop.
     // Nodes need at least one transition each — State construction at pass 2
     // rejects empty stateDefinitions before pass 3's cycle check would run.
-    const dummyTransition = {pattern: '*', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"};
+    const dummyTransition = {pattern: '∗', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"};
     const graph = {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index 21e3494..6bd6128 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -19,16 +19,16 @@ describe('decodePatternDescription', () => {
     expect(decodePatternDescription(undefined, alphabets)).toBe('?');
   });
 
-  test('"other symbol" → "*" (whole-state ifOtherSymbol)', () => {
-    expect(decodePatternDescription('other symbol', alphabets)).toBe('*');
+  test('"other symbol" → "∗" (whole-state ifOtherSymbol)', () => {
+    expect(decodePatternDescription('other symbol', alphabets)).toBe('∗');
   });
 
   test('literal cell wraps in single quotes', () => {
     expect(decodePatternDescription('[["0"]]', alphabets)).toBe("'0'");
   });
 
-  test('per-cell null → "*"', () => {
-    expect(decodePatternDescription('[[null]]', alphabets)).toBe('*');
+  test('per-cell null → "∗"', () => {
+    expect(decodePatternDescription('[[null]]', alphabets)).toBe('∗');
   });
 
   test('cell equal to tape blank → "-"', () => {
@@ -77,9 +77,9 @@ describe('decodeMovement', () => {
   });
 
   test.each([
-    [(movements.left as symbol).description, 'L'],
-    [(movements.right as symbol).description, 'R'],
-    [(movements.stay as symbol).description, 'S'],
+    [(movements.left as symbol).description, '←'],
+    [(movements.right as symbol).description, '→'],
+    [(movements.stay as symbol).description, '⇹'],
   ])('%s → %s', (description, expected) => {
     expect(decodeMovement(description)).toBe(expected);
   });
@@ -121,8 +121,8 @@ describe('toMermaid', () => {
         1: {
           id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
-            {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: '→'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -134,8 +134,8 @@ describe('toMermaid', () => {
     expect(out).toContain('s1["entry"]');
     expect(out).toContain('idle([idle])');
     expect(out).toContain('idle -. enter .-> s1');
-    expect(out).toContain('s1 -- "0 → K/R" --> s1');
-    expect(out).toContain('s1 -- "1 → K/S" --> s0');
+    expect(out).toContain('s1 -- "0 → K/→" --> s1');
+    expect(out).toContain('s1 -- "1 → K/⇹" --> s0');
   });
 
   test('renders dotted onHalt edge when overriddenHaltStateId is set', () => {
@@ -175,7 +175,7 @@ describe('toMermaid', () => {
           id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [{
             pattern: '0,a',
-            command: [{symbol: '0', movement: 'R'}, {symbol: 'a', movement: 'L'}],
+            command: [{symbol: '0', movement: '→'}, {symbol: 'a', movement: '←'}],
             nextStateId: 0,
             id: 'test-edge',
           }],
@@ -183,7 +183,7 @@ describe('toMermaid', () => {
       },
     });
 
-    expect(out).toContain('"0,a → 0/R,a/L"');
+    expect(out).toContain('"0,a → 0/→,a/←"');
   });
 });
 
@@ -203,24 +203,24 @@ describe('splitUnescaped', () => {
 
 describe('parsePatternString', () => {
   test('returns null for the global ifOtherSymbol marker', () => {
-    expect(parsePatternString('*', [[' ', '0']])).toBeNull();
+    expect(parsePatternString('∗', [[' ', '0']])).toBeNull();
   });
 
-  test('per-cell `*` becomes null', () => {
+  test('per-cell `∗` becomes null', () => {
     // Multi-tape pattern where one cell is per-cell ifOtherSymbol.
-    expect(parsePatternString('0,*', [[' ', '0'], [' ', 'a']])).toEqual([['0', null]]);
+    expect(parsePatternString("'0',∗", [[' ', '0'], [' ', 'a']])).toEqual([['0', null]]);
   });
 
   test('per-cell `-` becomes the tape blank symbol', () => {
-    expect(parsePatternString('-,a', [[' ', '0'], [' ', 'a']])).toEqual([[' ', 'a']]);
+    expect(parsePatternString("-,'a'", [[' ', '0'], [' ', 'a']])).toEqual([[' ', 'a']]);
   });
 });
 
 describe('parseMovementLabel', () => {
-  test('maps L/R/S to upstream movement symbols', () => {
-    expect(parseMovementLabel('L')).toBe(movements.left);
-    expect(parseMovementLabel('R')).toBe(movements.right);
-    expect(parseMovementLabel('S')).toBe(movements.stay);
+  test('maps ←/→/⇹ to upstream movement symbols', () => {
+    expect(parseMovementLabel('←')).toBe(movements.left);
+    expect(parseMovementLabel('→')).toBe(movements.right);
+    expect(parseMovementLabel('⇹')).toBe(movements.stay);
   });
 
   test('throws on unknown label', () => {
@@ -322,8 +322,8 @@ describe('README example: toMermaid output is stable', () => {
       '  s1["name"]',
       '  idle([idle])',
       '  idle -. enter .-> s1',
-      "  s1 -- \"'1' → '0'/R\" --> s1",
-      "  s1 -- \"'$' → K/L\" --> s0",
+      "  s1 -- \"'1' → '0'/→\" --> s1",
+      "  s1 -- \"'$' → K/←\" --> s0",
     ].join('\n');
 
     expect(toMermaid(State.toGraph(s, tapeBlock))).toBe(expected);
@@ -334,7 +334,7 @@ describe('README example: toMermaid output is stable', () => {
 // READMEs. Each test asserts the expected lines are present; we don't pin
 // state IDs as exact values because they auto-increment globally and depend
 // on test ordering. The test catches engine emit-format changes (e.g. if
-// "b → */R" notation drifts) without being fragile to ID assignment.
+// "b → */→" notation drifts) without being fragile to ID assignment.
 import Reference from '../classes/Reference';
 import {ifOtherSymbol} from '../classes/State';
 
@@ -363,9 +363,9 @@ describe('README diagrams: engine-generated outputs', () => {
       '["replaceB"]', // initial — square (no longer round in v7; idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      "\"'b' → '*'/R\"",
-      '"- → K/L"',
-      '"* → K/R"',
+      "\"'b' → '*'/→\"",
+      '"- → K/←"',
+      '"∗ → K/→"',
     ]);
   });
 
@@ -387,8 +387,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["b"]', // b is reachable from a → square
       'idle([idle])',
       'idle -. enter .->',
-      "\"'x' → K/S\"",
-      "\"'y' → K/S\"",
+      "\"'x' → K/⇹\"",
+      "\"'y' → K/⇹\"",
     ]);
   });
 
@@ -410,8 +410,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["scanToX"]', // initial — square (idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      "\"'X' → K/S\"",
-      '"* → K/R"',
+      "\"'X' → K/⇹\"",
+      '"∗ → K/→"',
     ]);
   });
 
@@ -440,7 +440,7 @@ describe('README diagrams: engine-generated outputs', () => {
       '"halt frame"', // subgraph label
       'idle([idle])', // pre-execution sentinel — always emitted
       'idle -. enter .->', // labeled dotted enter arrow points at the initial state
-      '"* → E/S"', // eraseHere's erase command
+      '"∗ → E/⇹"', // eraseHere's erase command
       '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
     ]);
   });
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index ee29eaa..6a24ae0 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -35,10 +35,16 @@ export type Graph = {
   nodes: Record<number, GraphNode>;
 };
 
+// Head-movement labels use directional Unicode arrows for visual clarity in
+// rendered Mermaid output: `←` (U+2190) left, `→` (U+2192) right, `⇹` (U+21F9
+// LEFT RIGHT OPEN-HEADED ARROW) stay. The right-arrow `→` is the same glyph
+// used by the read-to-write separator in edge labels; `fromMermaid` parses
+// labels via `indexOf(' → ')` (note the surrounding spaces) so the unspaced
+// `→` in a movement position doesn't collide.
 const movementDescriptionToLabel: Record<string, string> = {
-  'move caret left command': 'L',
-  'move caret right command': 'R',
-  'do not move carer': 'S',
+  'move caret left command': '←',
+  'move caret right command': '→',
+  'do not move carer': '⇹',
 };
 
 const symbolCommandDescriptionToLabel: Record<string, string> = {
@@ -47,17 +53,22 @@ const symbolCommandDescriptionToLabel: Record<string, string> = {
 };
 
 // Reserved characters in the encoded pattern string:
-//   '*'  per-cell ifOtherSymbol (matches any symbol on that tape)
+//   '∗'  (U+2217 ASTERISK OPERATOR) per-cell ifOtherSymbol — matches any
+//        symbol on that tape. Distinct from the regular ASCII '*' (U+002A) so
+//        an alphabet that contains literal '*' (rendered as the quoted `'*'`)
+//        is unambiguously different from the catch-all marker.
 //   '-'  the tape's blank symbol
 //   ','  separates per-tape cells inside one pattern
 //   '|'  separates alternative patterns
 //   "'"  surrounds a literal alphabet symbol — e.g. `'0'` for literal `0`,
 //        `'X'` for literal `X`. The quoting is what visually separates literal
-//        symbols from the convention markers `*` / `-` and from the write
+//        symbols from the convention markers `∗` / `-` and from the write
 //        commands `K` / `E`.
-//   '\\' escape prefix — to represent any of '*', '-', ',', '|', "'", or '\\'
+//   '\\' escape prefix — to represent any of '∗', '-', ',', '|', "'", or '\\'
 //        as a *literal* alphabet symbol *inside* the quotes (e.g. `'\''` for
 //        a literal apostrophe).
+const IF_OTHER_MARKER = '∗';
+
 function escapeAlphabetSymbol(s: string): string {
   return s
     .replace(/\\/g, '\\\\')
@@ -73,7 +84,7 @@ export function decodePatternDescription(
   }
 
   if (description === 'other symbol') {
-    return '*';
+    return IF_OTHER_MARKER;
   }
 
   try {
@@ -83,7 +94,7 @@ export function decodePatternDescription(
       .map((pattern) => pattern
         .map((s, tapeIx) => {
           if (s === null) {
-            return '*';
+            return IF_OTHER_MARKER;
           }
 
           if (s === alphabets[tapeIx]?.[0]) {
@@ -137,7 +148,7 @@ export function splitUnescaped(s: string, sep: string): string[] {
 }
 
 export function parsePatternString(s: string, alphabets: string[][]): ParsedPattern {
-  if (s === '*') {
+  if (s === IF_OTHER_MARKER) {
     return null;
   }
 
@@ -147,7 +158,7 @@ export function parsePatternString(s: string, alphabets: string[][]): ParsedPatt
     const cells = splitUnescaped(alt, ',');
 
     return cells.map((cell, tapeIx) => {
-      if (cell === '*') {
+      if (cell === IF_OTHER_MARKER) {
         return null;
       }
 
@@ -167,9 +178,9 @@ export function parsePatternString(s: string, alphabets: string[][]): ParsedPatt
 }
 
 const movementLabelToSymbol: Record<string, symbol> = {
-  L: movements.left,
-  R: movements.right,
-  S: movements.stay,
+  '←': movements.left,
+  '→': movements.right,
+  '⇹': movements.stay,
 };
 
 export function parseMovementLabel(label: string): symbol {
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 17347db..2fcfb66 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -11,8 +11,8 @@ describe('summarizeGraph', () => {
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
-            {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: '→'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -35,7 +35,7 @@ describe('summarizeGraph', () => {
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: '→'}], nextStateId: 1, id: "test-edge"},
           ],
         },
       },
@@ -55,7 +55,7 @@ describe('summarizeGraph', () => {
         0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
-          transitions: [{pattern: '0', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
+          transitions: [{pattern: '0', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"}],
         },
       },
     };
@@ -122,7 +122,7 @@ describe('State.inspect', () => {
 
     const haltTransition = info.transitions.find((t) => t.nextState?.name === haltState.name);
     expect(haltTransition).toBeTruthy();
-    expect(haltTransition!.command[0].movement).toBe('R');
+    expect(haltTransition!.command[0].movement).toBe('→');
     expect(haltTransition!.command[0].symbol).toBe("'1'");
   });
 

From 1a6d95d208437fc095582f45670c840c62163d01 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 21:28:05 +0300
Subject: [PATCH 009/118] polish(emit + docs): readable vocabulary, removed
 hand-drawn diagrams, dogfooded `summarize`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Iterative UX refinements on top of the v7 emit. The five highlights:

1. **Edge-label vocabulary refined further.**
   - Catch-all marker: `*` (ASCII) → `🞰` (U+1F7B0 HEAVY EIGHT
     BALLOON-SPOKED ASTERISK) — distinct from a quoted-literal `'*'`
     so an alphabet containing literal `*` stays unambiguous from the
     ifOtherSymbol marker.
   - Blank-symbol shorthand (read patterns): `-` → `B` — read-side
     noun for "the cell is blank"; write-side action stays `E` (Erase).
     Verb/noun split mirrors the read/write role.
   - Movements stay `L` / `R` / `S` (briefly tried arrows `←` / `→` /
     `⇹` and reverted — the letter codes read cleanly without
     overloading the read-to-write `→` separator).

2. **Stack-pushing transitions now visually distinct.**
   `toMermaid` emits a thick `==>` arrow when a transition's target is
   a wrapped state AND target ≠ source (= stack-push happens at
   runtime per `TuringMachine.run` line 220's
   `if (state !== nextState && nextState.overriddenHaltState) push(...)`).
   Self-loops on wrappers stay `-->` because they don't push. The
   reader can now scan an execution path counting thick arrows to see
   how deep the wrapper stack grows.

3. **Removed 4 hand-drawn pedagogical Mermaid blocks** from root and
   engine READMEs (Quick Start replaceB ×2, Reference cycle, Subroutine
   composition). The v7 engine emit is clear enough to stand on its
   own; the hand-drawn versions used different vocabulary and shapes
   and forced the reader to context-switch between two visual styles.
   Promoted the engine `toMermaid()` outputs out of `<details>` to
   primary illustration. Root README's stale v6 emit also updated to
   v7 vocabulary.

4. **`summarize().stateCount` filters cloned-halt sentinels** —
   matches the per-algorithm header in `library-binary-numbers/states.md`
   by construction. All three sources (source-comment counts, test
   fixture `expectedNodeCount`, states.md header) now agree.
   `build-states-md.mjs` dogfoods `summarizeGraph()` for its richer
   stats line (`N states; N transitions; N wrappers (max nesting
   depth N); has cycles`), replacing the manually-computed count.

5. **Docs realigned with what the emit actually does.**
   - README and spec drop the overstated "only dotted crosses the
     subgraph border" invariant — true for simple wrappers, false for
     compositions like `minusOne` whose bare's transitions reach
     helpers outside the halt frame. Solid arrows can cross; only the
     dotted `onHalt` carries wrapper-machinery meaning.
   - Engine CLAUDE.md's `toMermaid` description rewritten for v7
     reality (subgraph + `[[bare]]` + cloned halt + idle sentinel +
     edge-label vocabulary + thick-arrow convention + per-context
     duplication for shared-bare).
   - Mermaid links added (mermaid.js.org syntax docs + mermaid-js repo).
   - `library-binary-numbers/src/index.ts` source-comment fixes:
     minusOne "17 nodes" → "15 nodes (per `summarize().stateCount`)",
     "four-deep subroutine chain" → "three-deep" (3 wrapper hops + 1
     terminal target, not 4 wrappers). Per-algorithm counts updated
     where v7 emit changed them (deleteNumber/invertNumber 5→4,
     normalizeNumber 7→6, minusOneFast 10→8).

`equivalentOn` verified unaffected — pure-runtime checker, doesn't
touch the visualization or introspection surface.

All 420 tests still pass.
---
 CLAUDE.md                                     |   8 +-
 README.md                                     |  30 +--
 ...026-05-20-tomermaid-wrapper-emit-design.md |   2 +-
 .../library-binary-numbers-bare/states.md     |  40 ++--
 .../library-binary-numbers/src/graphs.spec.ts |  27 ++-
 packages/library-binary-numbers/src/index.ts  |  16 +-
 packages/library-binary-numbers/states.md     | 200 +++++++++---------
 packages/machine/README.md                    |  92 ++------
 packages/machine/src/classes/State.spec.ts    |   2 +-
 packages/machine/src/utilities/graph.spec.ts  |  70 +++---
 packages/machine/src/utilities/graph.ts       |  41 ++--
 .../machine/src/utilities/graphFormats.ts     |  18 +-
 .../src/utilities/introspection.spec.ts       |  10 +-
 .../machine/src/utilities/introspection.ts    |  10 +-
 scripts/build-states-md.mjs                   |  20 +-
 15 files changed, 275 insertions(+), 311 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 04ddcdd..f4442c0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -59,7 +59,13 @@ Key shapes that take reading multiple files to grasp:
 
 ### Visualization & round-trip
 
-`packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same Graph through Mermaid flowchart syntax. The round-trip is **behaviorally** lossless (rebuilt graph runs to same outputs on same inputs — covered by `test/round-trip.spec.ts`); not bytewise lossless because state IDs auto-reassign, and for `withOverriddenHaltState` wrappers the composite name accumulates an extra `(${override.name})` wrap on each pass (composite-name format is `bare(override)` since v7 — paren-nested rather than `>`-flat, so nestings like `A(B(A))` vs `A(B)(A)` stay distinguishable). Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) (cleaner emit for wrapped states) + [#139](https://github.com/mellonis/turing-machine-js/issues/139) (regression test that fails until #138 is fixed).
+`packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same `Graph` through [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) syntax (renderer: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)). The parser is strict to the dialect `toMermaid` emits — hand-edited Mermaid with different arrow styles or shapes won't round-trip.
+
+**v7 emit shape** (PR #169, closes #138/#139): each `withOverriddenHaltState` wrapper collapses onto its bare's representation — `GraphNode.isWrapped: true`, no separate wrapper node in graph data. `toMermaid` wraps each `[[bare]]` (subroutine shape) + a synthesized `(((halt)))` clone (`GraphNode.isClonedHalt: true`, negative id; maps back to singleton `haltState` in `fromGraph`) inside a `subgraph w_${bareId}["halt frame"] … end` block. Dotted `onHalt` from `[[bare]]` crosses the subgraph border to the override target. An always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state (replaces v6's `((round))` shape convention). Edge labels: write commands `K` (keep) / `E` (erase), movements `L`/`R`/`S`, literal alphabet symbols quoted (`'X'`), unquoted markers `🞰` (U+1F7B0, ifOtherSymbol) and `B` (the tape's blank). Thick `==>` arrows mark transitions whose target is a wrapped state (= stack-push at runtime); regular `-->` for the rest; dotted reserved for wrapper machinery.
+
+**Round-trip** is **bytewise stable for simple wrappers** (regression test in `test/round-trip.spec.ts` — #139). The wrapper's composite name (e.g. `scanToX(eraseHere)`) does NOT appear as a graph node label; only the bare's name does, so `fromGraph` recomputes the composite fresh on reconstruction — no accumulation. **Shared-bare cases** (same `State` instance used as the bare of multiple wrappers, e.g. `library-binary-numbers`'s `minusOne` where `invertNumber` is both the outermost bare AND wrapper-W1's bare) use **per-context duplication** in `toGraph`: each occurrence emits a separate graph node with the wrapper's `#id`. Reconstruction produces behaviorally-equivalent State instances (not necessarily the same runtime `#id`), but bytewise stability isn't guaranteed for shared-bare since duplicate ordering depends on runtime wrapper-ids that don't survive rebuild.
+
+**Stats helpers** — `summarize(state, tapeBlock)` returns `{stateCount, transitionCount, compositionEdgeCount, maxCompositionDepth, selfLoopCount, hasCycles, tapeCount, alphabetCardinalities}`. `stateCount` filters out `isClonedHalt` sentinels (they're visualization-only, all map to the singleton `haltState` at runtime); matches the per-algorithm header in `library-binary-numbers/states.md` by construction. `equivalentOn(reference, candidate, cases)` is the separate behavioral-equivalence checker — runs both machines, compares outputs and per-step snapshots; lives in `./utilities/equivalence.ts`, unaffected by the visualization-layer changes above.
 
 ### Builder package
 
diff --git a/README.md b/README.md
index 8f40c35..092eb10 100644
--- a/README.md
+++ b/README.md
@@ -74,35 +74,21 @@ console.log(tape.symbols.join('').trim()); // a*c*a
 
 ## How it runs
 
-Just one state — call it **S** — that loops on every cell, writing `*` whenever the head reads `b` and stopping at the trailing blank:
-
-```mermaid
-flowchart LR
-    S(("**S**"))
-    H((("**halt**")))
-    S -- "b → *, R" --> S
-    S -- "_ → keep, L" --> H
-    S -- "any other → keep, R" --> S
-```
-
-*Reading the labels: `read → write, move`. `_` is the blank symbol.*
-
-<details>
-<summary>📊 Same diagram, generated by <code>toMermaid()</code> (the engine's actual output)</summary>
+Just one state — call it `replaceB` — that loops on every cell, writing `*` whenever the head reads `b` and stopping at the trailing blank. The engine emits its state graph via `toMermaid(toGraph(replaceB, tapeBlock))`:
 
 ```mermaid
 flowchart TD
 %% alphabets: [[" ","a","b","c","*"]]
   s0(((halt)))
-  s1(("replaceB"))
-  s1 -- "b → */R" --> s1
-  s1 -- "- → ·/L" --> s0
-  s1 -- "* → ·/R" --> s1
+  s1["replaceB"]
+  idle([idle])
+  idle -. enter .-> s1
+  s1 -- "'b' → '*'/R" --> s1
+  s1 -- "B → K/L" --> s0
+  s1 -- "🞰 → K/R" --> s1
 ```
 
-Engine notation: `read → write/move`; `·` = keep, `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol.
-
-</details>
+Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Movements: `L` / `R` / `S`. Literal alphabet symbols are wrapped in single quotes (`'b'`, `'*'`). Unquoted markers: `🞰` (U+1F7B0) = `ifOtherSymbol` catch-all, `B` = the tape's blank symbol. `(((halt)))` = halt; `["square"]` = a regular state; the `idle([idle])` sentinel + dotted `enter` arrow marks where execution begins. (Subroutine composition adds a `subgraph` "halt frame" + `[[double-walled]]` wrapper node — see [§Subroutine composition](packages/machine/README.md#subroutine-composition-with-withoverriddenhaltstate) in the engine README.)
 
 Trace on the input tape `abcba`:
 
diff --git a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
index 6102511..a5fb831 100644
--- a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
+++ b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
@@ -269,7 +269,7 @@ After iteration, the locked shape evolves Variant X (collapse the wrapper into t
   - the source of the dotted `onHalt` redirect (since the wrapper-node *is* the catcher).
 - **Cloned `(((halt)))` inside the subgraph** = the halt entry point within this wrapper's scope. Halt-bound transitions from the bare terminate here, not at the real halt.
 - **Solid arrows from `[[bare]]` to cloned halt** = the bare's structural halt-bound transitions. All stay inside the subgraph rectangle.
-- **Dotted `onHalt` arrow from `[[bare]]` out of the subgraph to the override target** = the wrapper's catch-and-redirect. Exactly one per wrapper; the only arrow that crosses the rectangle border.
+- **Dotted `onHalt` arrow from `[[bare]]` out of the subgraph to the override target** = the wrapper's catch-and-redirect. Exactly one per wrapper. Solid arrows from `[[bare]]` to non-halt targets can ALSO cross the rectangle border (when the bare's transitions reach external states — common in compositions like `library-binary-numbers`'s `minusOne`); those are just regular runtime transitions, not wrapper machinery. Only the dotted `onHalt` carries wrapper-machinery meaning.
 - **Real `(((halt)))` outside any subgraph** = the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame (the unwrapped tail of the chain).
 
 ### Single wrapper
diff --git a/packages/library-binary-numbers-bare/states.md b/packages/library-binary-numbers-bare/states.md
index 46e19b9..fdb91df 100644
--- a/packages/library-binary-numbers-bare/states.md
+++ b/packages/library-binary-numbers-bare/states.md
@@ -2,7 +2,7 @@
 
 ## plusOne
 
-*3 states (including `haltState`)*
+*3 states; 5 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -12,16 +12,16 @@ flowchart TD
   s2["plusOne"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "'1' → '0'/←" --> s1
-  s1 -- "'0' → '1'/⇹" --> s0
-  s1 -- "- → '1'/⇹" --> s0
-  s2 -- "'0'|'1' → K/→" --> s2
-  s2 -- "- → K/←" --> s1
+  s1 -- "'1' → '0'/L" --> s1
+  s1 -- "'0' → '1'/S" --> s0
+  s1 -- "B → '1'/S" --> s0
+  s2 -- "'0'|'1' → K/R" --> s2
+  s2 -- "B → K/L" --> s1
 ```
 
 ## minusOne
 
-*3 states (including `haltState`)*
+*3 states; 5 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -31,16 +31,16 @@ flowchart TD
   s4["minusOne"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "'0' → '1'/←" --> s3
-  s3 -- "'1' → '0'/⇹" --> s0
-  s3 -- "- → K/⇹" --> s0
-  s4 -- "'0'|'1' → K/→" --> s4
-  s4 -- "- → K/←" --> s3
+  s3 -- "'0' → '1'/L" --> s3
+  s3 -- "'1' → '0'/S" --> s0
+  s3 -- "B → K/S" --> s0
+  s4 -- "'0'|'1' → K/R" --> s4
+  s4 -- "B → K/L" --> s3
 ```
 
 ## invertNumber
 
-*2 states (including `haltState`)*
+*2 states; 3 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -49,14 +49,14 @@ flowchart TD
   s5["invertNumber"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "'0' → '1'/→" --> s5
-  s5 -- "'1' → '0'/→" --> s5
-  s5 -- "- → K/⇹" --> s0
+  s5 -- "'0' → '1'/R" --> s5
+  s5 -- "'1' → '0'/R" --> s5
+  s5 -- "B → K/S" --> s0
 ```
 
 ## normalizeNumber
 
-*2 states (including `haltState`)*
+*2 states; 3 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -65,7 +65,7 @@ flowchart TD
   s6["normalizeNumber"]
   idle([idle])
   idle -. enter .-> s6
-  s6 -- "'0' → E/→" --> s6
-  s6 -- "'1' → K/⇹" --> s0
-  s6 -- "- → '0'/⇹" --> s0
+  s6 -- "'0' → E/R" --> s6
+  s6 -- "'1' → K/S" --> s0
+  s6 -- "B → '0'/S" --> s0
 ```
diff --git a/packages/library-binary-numbers/src/graphs.spec.ts b/packages/library-binary-numbers/src/graphs.spec.ts
index 4139787..ff6b3e4 100644
--- a/packages/library-binary-numbers/src/graphs.spec.ts
+++ b/packages/library-binary-numbers/src/graphs.spec.ts
@@ -1,25 +1,22 @@
-import {State, fromMermaid, toMermaid} from '@turing-machine-js/machine';
+import {State, fromMermaid, summarizeGraph, toMermaid} from '@turing-machine-js/machine';
 import binaryNumbers from './index';
 
-// Per-state node counts pinned from the source comments above each declaration
-// in `index.ts`. Each count includes haltState plus any v7 cloned-halt nodes
-// synthesized by `toGraph` (one per `withOverriddenHaltState` wrapper context).
-// For single-wrapper algorithms the count is unchanged from v6 — the wrapper
-// node disappears (collapsed into its bare) but a cloned halt appears, netting
-// to zero. For shared-bare cases like `minusOne` (where the same bare appears
-// in multiple wrapper contexts via per-context duplication), the count grows
-// by `wrapperCount - 1` relative to v6.
+// Per-state counts pinned from the source comments above each declaration in
+// `index.ts`. These are runtime state counts (per `summarize().stateCount`),
+// which exclude the `isClonedHalt` visualization sentinels v7 synthesizes
+// inside each `halt frame` subgraph. The states.md per-algorithm header uses
+// the same definition, so all three sources agree by construction.
 const expectedNodeCount: Record<keyof typeof binaryNumbers['states'], number> = {
   goToNumber: 2,
   goToNextNumber: 3,
   goToPreviousNumber: 3,
   goToNumbersStart: 2,
-  deleteNumber: 5,
-  invertNumber: 5,
-  normalizeNumber: 7,
+  deleteNumber: 4,
+  invertNumber: 4,
+  normalizeNumber: 6,
   plusOne: 5,
-  minusOne: 20,
-  minusOneFast: 10,
+  minusOne: 15,
+  minusOneFast: 8,
 };
 
 const stateNames = Object.keys(expectedNodeCount) as Array<keyof typeof expectedNodeCount>;
@@ -31,7 +28,7 @@ describe('library-binary-numbers state graphs', () => {
       const tapeBlock = binaryNumbers.getTapeBlock();
       const graph = State.toGraph(binaryNumbers.states[name], tapeBlock);
 
-      expect(Object.keys(graph.nodes)).toHaveLength(expectedNodeCount[name]);
+      expect(summarizeGraph(graph).stateCount).toBe(expectedNodeCount[name]);
     },
   );
 
diff --git a/packages/library-binary-numbers/src/index.ts b/packages/library-binary-numbers/src/index.ts
index 009713f..8702973 100644
--- a/packages/library-binary-numbers/src/index.ts
+++ b/packages/library-binary-numbers/src/index.ts
@@ -85,7 +85,7 @@ const goToNumbersStart = new State({
   },
 }, 'goToNumberStart');
 
-// deleteNumber — 5 nodes
+// deleteNumber — 4 nodes
 //
 // Composition: go to the number's '^', then sweep right erasing every cell
 // (digits, '^', '$') until the number is gone. Implemented as
@@ -115,7 +115,7 @@ const deleteNumber = new State({
   },
 }, 'deleteNumber');
 
-// invertNumber — 5 nodes
+// invertNumber — 4 nodes
 //
 // Composition: go to '^', then sweep right flipping each bit until '$'.
 // Same shape as deleteNumber (goToNumbersStart.withOverriddenHaltState(...)) but
@@ -152,7 +152,7 @@ const invertNumber = new State({
   },
 }, 'invertNumber');
 
-// normalizeNumber — 7 nodes
+// normalizeNumber — 6 nodes
 //
 // Strips leading zeros by erasing them and re-planting '^' just before the first
 // '1' (or before '$' if the entire number was zero — preserving "0" as "^$").
@@ -268,16 +268,18 @@ const plusOne = new State({
   },
 }, 'plusOne');
 
-// minusOne — 17 nodes (the largest in this library)
+// minusOne — 15 nodes (the largest in this library, per `summarize().stateCount`)
 //
 // Computes x − 1 via the two's-complement identity:  x − 1 == ~(~x + 1)
 // (every step is a state we already have), composed with three nested
 // withOverriddenHaltState calls to chain invert → plusOne → invert → normalize.
+// The chain has 4 state names but 3 wrapper hops — `normalizeNumber` at the
+// inner end is the terminal override target, not another wrapper level.
 //
 // This is *deliberately* the heavy version. It exists side-by-side with
-// minusOneFast (10 nodes, direct borrow) to make the cost of "compose existing
+// minusOneFast (8 nodes, direct borrow) to make the cost of "compose existing
 // pieces" vs "write a dedicated algorithm" visible. See ../states.md for the
-// dotted onHalt edges that show the four-deep subroutine chain.
+// dotted onHalt edges that show the three-deep wrapper chain.
 const minusOne = new State({
   [symbol('^10')]: {
     command: {
@@ -299,7 +301,7 @@ const minusOne = new State({
   },
 }, 'minusOne');
 
-// minusOneFast — 10 nodes (direct borrow propagation)
+// minusOneFast — 8 nodes (direct borrow propagation)
 //
 // Walks left from the LSB: 0→1 keeps borrowing; 1→0 stops; ^ is underflow.
 // Falls through to normalizeNumber to strip the leading zero introduced when the
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index c96389c..7040cc6 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -2,7 +2,7 @@
 
 ## goToNumber
 
-*2 states (including `haltState`)*
+*2 states; 2 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -11,13 +11,13 @@ flowchart TD
   s1["goToNumber"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'$' → K/⇹" --> s0
-  s1 -- "∗ → K/→" --> s1
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "🞰 → K/R" --> s1
 ```
 
 ## goToNextNumber
 
-*3 states (including `haltState`)*
+*3 states; 3 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -27,14 +27,14 @@ flowchart TD
   s2["goToNextNumber"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "'$' → K/⇹" --> s0
-  s1 -- "∗ → K/→" --> s1
-  s2 -- "∗ → K/→" --> s1
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "🞰 → K/R" --> s1
+  s2 -- "🞰 → K/R" --> s1
 ```
 
 ## goToPreviousNumber
 
-*3 states (including `haltState`)*
+*3 states; 3 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -44,14 +44,14 @@ flowchart TD
   s4["goToPreviousNumber"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "'$' → K/⇹" --> s0
-  s3 -- "∗ → K/←" --> s3
-  s4 -- "∗ → K/←" --> s3
+  s3 -- "'$' → K/S" --> s0
+  s3 -- "🞰 → K/L" --> s3
+  s4 -- "🞰 → K/L" --> s3
 ```
 
 ## deleteNumber
 
-*4 states (including `haltState`)*
+*4 states; 6 transitions; 1 wrapper (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -65,18 +65,18 @@ flowchart TD
     c7(((halt)))
   end
   idle -. enter .-> s8
-  s6 -- "'$' → E/⇹" --> s0
-  s6 -- "∗ → E/→" --> s6
-  s7 -- "'^' → K/⇹" --> c7
-  s7 -- "∗ → K/←" --> s7
+  s6 -- "'$' → E/S" --> s0
+  s6 -- "🞰 → E/R" --> s6
+  s7 -- "'^' → K/S" --> c7
+  s7 -- "🞰 → K/L" --> s7
   s7 -. onHalt .-> s6
-  s8 -- "'^'|'1'|'0'|'$' → K/⇹" --> s7
-  s8 -- "∗ → K/⇹" --> s0
+  s8 == "'^'|'1'|'0'|'$' → K/S" ==> s7
+  s8 -- "🞰 → K/S" --> s0
 ```
 
 ## goToNumbersStart
 
-*2 states (including `haltState`)*
+*2 states; 2 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -85,13 +85,13 @@ flowchart TD
   s5["goToNumberStart"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "'^' → K/⇹" --> s0
-  s5 -- "∗ → K/←" --> s5
+  s5 -- "'^' → K/S" --> s0
+  s5 -- "🞰 → K/L" --> s5
 ```
 
 ## invertNumber
 
-*4 states (including `haltState`)*
+*4 states; 8 transitions; 1 wrapper (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -105,20 +105,20 @@ flowchart TD
     c10(((halt)))
   end
   idle -. enter .-> s11
-  s9 -- "'^' → K/→" --> s9
-  s9 -- "'1' → '0'/→" --> s9
-  s9 -- "'0' → '1'/→" --> s9
-  s9 -- "'$' → K/⇹" --> s0
-  s10 -- "'^' → K/⇹" --> c10
-  s10 -- "∗ → K/←" --> s10
+  s9 -- "'^' → K/R" --> s9
+  s9 -- "'1' → '0'/R" --> s9
+  s9 -- "'0' → '1'/R" --> s9
+  s9 -- "'$' → K/S" --> s0
+  s10 -- "'^' → K/S" --> c10
+  s10 -- "🞰 → K/L" --> s10
   s10 -. onHalt .-> s9
-  s11 -- "'^'|'1'|'0'|'$' → K/⇹" --> s10
-  s11 -- "∗ → K/⇹" --> s0
+  s11 == "'^'|'1'|'0'|'$' → K/S" ==> s10
+  s11 -- "🞰 → K/S" --> s0
 ```
 
 ## normalizeNumber
 
-*6 states (including `haltState`)*
+*6 states; 9 transitions; 1 wrapper (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -134,21 +134,21 @@ flowchart TD
     c14(((halt)))
   end
   idle -. enter .-> s15
-  s1 -- "'$' → K/⇹" --> s0
-  s1 -- "∗ → K/→" --> s1
-  s12 -- "- → '^'/⇹" --> s1
-  s13 -- "'^'|'0' → E/→" --> s13
-  s13 -- "'1'|'$' → K/←" --> s12
-  s14 -- "'^' → K/⇹" --> c14
-  s14 -- "∗ → K/←" --> s14
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "🞰 → K/R" --> s1
+  s12 -- "B → '^'/S" --> s1
+  s13 -- "'^'|'0' → E/R" --> s13
+  s13 -- "'1'|'$' → K/L" --> s12
+  s14 -- "'^' → K/S" --> c14
+  s14 -- "🞰 → K/L" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "'^'|'1'|'0'|'$' → K/⇹" --> s14
-  s15 -- "∗ → K/⇹" --> s0
+  s15 == "'^'|'1'|'0'|'$' → K/S" ==> s14
+  s15 -- "🞰 → K/S" --> s0
 ```
 
 ## plusOne
 
-*5 states (including `haltState`)*
+*5 states; 10 transitions; has cycles*
 
 ```mermaid
 flowchart TD
@@ -160,21 +160,21 @@ flowchart TD
   s19["plusOne"]
   idle([idle])
   idle -. enter .-> s19
-  s16 -- "'1' → '0'/→" --> s16
-  s16 -- "'$' → K/⇹" --> s0
-  s17 -- "- → '^'/→" --> s17
-  s17 -- "'1' → K/→" --> s16
-  s18 -- "'0' → '1'/→" --> s16
-  s18 -- "'1' → K/←" --> s18
-  s18 -- "'^' → '1'/←" --> s17
-  s19 -- "'^'|'1'|'0' → K/→" --> s19
-  s19 -- "'$' → K/←" --> s18
-  s19 -- "∗ → K/⇹" --> s0
+  s16 -- "'1' → '0'/R" --> s16
+  s16 -- "'$' → K/S" --> s0
+  s17 -- "B → '^'/R" --> s17
+  s17 -- "'1' → K/R" --> s16
+  s18 -- "'0' → '1'/R" --> s16
+  s18 -- "'1' → K/L" --> s18
+  s18 -- "'^' → '1'/L" --> s17
+  s19 -- "'^'|'1'|'0' → K/R" --> s19
+  s19 -- "'$' → K/L" --> s18
+  s19 -- "🞰 → K/S" --> s0
 ```
 
 ## minusOne
 
-*15 states (including `haltState`)*
+*15 states; 32 transitions; 5 wrappers (max nesting depth 3); has cycles*
 
 ```mermaid
 flowchart TD
@@ -211,48 +211,48 @@ flowchart TD
     c22(((halt)))
   end
   idle -. enter .-> s23
-  s1 -- "'$' → K/⇹" --> s0
-  s1 -- "∗ → K/→" --> s1
-  s9 -- "'^' → K/→" --> s9
-  s9 -- "'1' → '0'/→" --> s9
-  s9 -- "'0' → '1'/→" --> s9
-  s9 -- "'$' → K/⇹" --> s0
-  s10 -- "'^' → K/⇹" --> c10
-  s10 -- "∗ → K/←" --> s10
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "🞰 → K/R" --> s1
+  s9 -- "'^' → K/R" --> s9
+  s9 -- "'1' → '0'/R" --> s9
+  s9 -- "'0' → '1'/R" --> s9
+  s9 -- "'$' → K/S" --> s0
+  s10 -- "'^' → K/S" --> c10
+  s10 -- "🞰 → K/L" --> s10
   s10 -. onHalt .-> s9
-  s12 -- "- → '^'/⇹" --> s1
-  s13 -- "'^'|'0' → E/→" --> s13
-  s13 -- "'1'|'$' → K/←" --> s12
-  s14 -- "'^' → K/⇹" --> c14
-  s14 -- "∗ → K/←" --> s14
+  s12 -- "B → '^'/S" --> s1
+  s13 -- "'^'|'0' → E/R" --> s13
+  s13 -- "'1'|'$' → K/L" --> s12
+  s14 -- "'^' → K/S" --> c14
+  s14 -- "🞰 → K/L" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "'^'|'1'|'0'|'$' → K/⇹" --> s14
-  s15 -- "∗ → K/⇹" --> s0
-  s16 -- "'1' → '0'/→" --> s16
-  s16 -- "'$' → K/⇹" --> s0
-  s17 -- "- → '^'/→" --> s17
-  s17 -- "'1' → K/→" --> s16
-  s18 -- "'0' → '1'/→" --> s16
-  s18 -- "'1' → K/←" --> s18
-  s18 -- "'^' → '1'/←" --> s17
-  s20 -- "'^'|'1'|'0'|'$' → K/⇹" --> s10
-  s20 -- "∗ → K/⇹" --> c20
+  s15 == "'^'|'1'|'0'|'$' → K/S" ==> s14
+  s15 -- "🞰 → K/S" --> s0
+  s16 -- "'1' → '0'/R" --> s16
+  s16 -- "'$' → K/S" --> s0
+  s17 -- "B → '^'/R" --> s17
+  s17 -- "'1' → K/R" --> s16
+  s18 -- "'0' → '1'/R" --> s16
+  s18 -- "'1' → K/L" --> s18
+  s18 -- "'^' → '1'/L" --> s17
+  s20 == "'^'|'1'|'0'|'$' → K/S" ==> s10
+  s20 -- "🞰 → K/S" --> c20
   s20 -. onHalt .-> s15
-  s21 -- "'^'|'1'|'0' → K/→" --> s21
-  s21 -- "'$' → K/←" --> s18
-  s21 -- "∗ → K/⇹" --> c21
+  s21 -- "'^'|'1'|'0' → K/R" --> s21
+  s21 -- "'$' → K/L" --> s18
+  s21 -- "🞰 → K/S" --> c21
   s21 -. onHalt .-> s20
-  s22 -- "'^'|'1'|'0'|'$' → K/⇹" --> s10
-  s22 -- "∗ → K/⇹" --> c22
+  s22 == "'^'|'1'|'0'|'$' → K/S" ==> s10
+  s22 -- "🞰 → K/S" --> c22
   s22 -. onHalt .-> s21
-  s23 -- "'^'|'1'|'0' → K/→" --> s23
-  s23 -- "'$' → K/⇹" --> s22
-  s23 -- "∗ → K/⇹" --> s0
+  s23 -- "'^'|'1'|'0' → K/R" --> s23
+  s23 == "'$' → K/S" ==> s22
+  s23 -- "🞰 → K/S" --> s0
 ```
 
 ## minusOneFast
 
-*8 states (including `haltState`)*
+*8 states; 15 transitions; 2 wrappers (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -273,21 +273,21 @@ flowchart TD
     c25(((halt)))
   end
   idle -. enter .-> s26
-  s1 -- "'$' → K/⇹" --> s0
-  s1 -- "∗ → K/→" --> s1
-  s12 -- "- → '^'/⇹" --> s1
-  s13 -- "'^'|'0' → E/→" --> s13
-  s13 -- "'1'|'$' → K/←" --> s12
-  s14 -- "'^' → K/⇹" --> c14
-  s14 -- "∗ → K/←" --> s14
+  s1 -- "'$' → K/S" --> s0
+  s1 -- "🞰 → K/R" --> s1
+  s12 -- "B → '^'/S" --> s1
+  s13 -- "'^'|'0' → E/R" --> s13
+  s13 -- "'1'|'$' → K/L" --> s12
+  s14 -- "'^' → K/S" --> c14
+  s14 -- "🞰 → K/L" --> s14
   s14 -. onHalt .-> s13
-  s15 -- "'^'|'1'|'0'|'$' → K/⇹" --> s14
-  s15 -- "∗ → K/⇹" --> s0
-  s25 -- "'1' → '0'/⇹" --> c25
-  s25 -- "'0' → '1'/←" --> s25
-  s25 -- "'^' → K/⇹" --> c25
+  s15 == "'^'|'1'|'0'|'$' → K/S" ==> s14
+  s15 -- "🞰 → K/S" --> s0
+  s25 -- "'1' → '0'/S" --> c25
+  s25 -- "'0' → '1'/L" --> s25
+  s25 -- "'^' → K/S" --> c25
   s25 -. onHalt .-> s15
-  s26 -- "'^'|'1'|'0' → K/→" --> s26
-  s26 -- "'$' → K/←" --> s25
-  s26 -- "∗ → K/⇹" --> s0
+  s26 -- "'^'|'1'|'0' → K/R" --> s26
+  s26 == "'$' → K/L" ==> s25
+  s26 -- "🞰 → K/S" --> s0
 ```
diff --git a/packages/machine/README.md b/packages/machine/README.md
index b42d1f3..065e109 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -70,21 +70,7 @@ await machine.run({
 console.log(tape.symbols.join('').trim()); // a*c*a
 ```
 
-The state graph for the example above:
-
-```mermaid
-flowchart LR
-    S(("**replaceB**"))
-    H((("**halt**")))
-    S -- "b → *, R" --> S
-    S -- "_ → keep, L" --> H
-    S -- "any other → keep, R" --> S
-```
-
-*Reading the labels: `read → write, move`. `_` is the blank symbol.*
-
-<details>
-<summary>📊 Same diagram, generated by <code>toMermaid()</code> (the engine's actual output)</summary>
+The state graph for the example above (`toMermaid(toGraph(replaceB, tapeBlock))`):
 
 ```mermaid
 flowchart TD
@@ -93,14 +79,14 @@ flowchart TD
   s1["replaceB"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'b' → '*'/→" --> s1
-  s1 -- "- → K/←" --> s0
-  s1 -- "∗ → K/→" --> s1
+  s1 -- "'b' → '*'/R" --> s1
+  s1 -- "B → K/L" --> s0
+  s1 -- "🞰 → K/R" --> s1
 ```
 
-Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Movements: `→` = right, `←` = left, `⇹` = stay. Literal alphabet symbols are wrapped in single quotes: `'b'`, `'*'`, `'X'`. Unquoted markers: `∗` (U+2217 asterisk-operator) = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below.
+Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Movements: `L` = left, `R` = right, `S` = stay. Literal alphabet symbols are wrapped in single quotes: `'b'`, `'*'`, `'X'`. Unquoted markers: `🞰` (U+1F7B0 heavy-eight-balloon-spoked-asterisk) = `ifOtherSymbol` catch-all, `B` = the tape's blank symbol (a literal `B` in the alphabet appears as the quoted `'B'`, so the marker stays unambiguous). `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below. **Arrow styles** between states: regular `-->` for plain transitions; thick `==>` for transitions whose target is a wrapped state (= stack-push happens at runtime); dotted `-. onHalt .->` for the wrapper's catch-and-redirect.
 
-</details>
+The shapes and arrow styles above are standard [Mermaid flowchart syntax](https://mermaid.js.org/syntax/flowchart.html); any tool that renders Mermaid (GitHub preview, IDE plugins, [mermaid-js](https://github.com/mermaid-js/mermaid) client-side) will paint these diagrams the same way.
 
 A `State` is keyed by JS `Symbol`s returned from `tapeBlock.symbol(pattern)` — the pattern lists the expected symbol under each tape's head. Sentinels and constants used throughout: [`ifOtherSymbol`](#ifothersymbol) is the fallback key when nothing else matches; transitioning into [`haltState`](#haltstate) stops the run; [`movements`](#movements)`.{left,right,stay}` direct head moves; [`symbolCommands`](#symbolcommands)`.{keep,erase}` are write shortcuts. Full definitions in [§Special objects](#special-objects).
 
@@ -275,11 +261,11 @@ flowchart TD
   s1["name"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'1' → '0'/→" --> s1
-  s1 -- "'$' → K/←" --> s0
+  s1 -- "'1' → '0'/R" --> s1
+  s1 -- "'$' → K/L" --> s0
 ```
 
-*Edge labels are `read → write/move`. Write commands: `K` = keep (no write), `E` = erase (write the blank). Literal alphabet symbols are quoted (`'1'`, `'$'`). Movements: `←` (left), `→` (right), `⇹` (stay).*
+*Edge labels are `read → write/move`. Write commands: `K` = keep (no write), `E` = erase (write the blank). Literal alphabet symbols are quoted (`'1'`, `'$'`). Movements: `L` (left), `R` (right), `S` (stay).*
 
 > 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
 
@@ -296,18 +282,7 @@ const b = new State({ [symbol(['y'])]: { nextState: a  } }, 'b');
 ref.bind(b);   // a's transition now resolves to b at run time
 ```
 
-The resulting cycle:
-
-```mermaid
-flowchart LR
-    a(("**a**"))
-    b(("**b**"))
-    a -- "x" --> b
-    b -- "y" --> a
-```
-
-<details>
-<summary>📊 Same diagram, generated by <code>toMermaid()</code></summary>
+The resulting cycle (`toMermaid(toGraph(a, tapeBlock))`):
 
 ```mermaid
 flowchart TD
@@ -316,13 +291,11 @@ flowchart TD
   s2["b"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'x' → K/⇹" --> s2
-  s2 -- "'y' → K/⇹" --> s1
+  s1 -- "'x' → K/S" --> s2
+  s2 -- "'y' → K/S" --> s1
 ```
 
-`a` is round (the initial state passed to `toGraph`); `b` is square (reachable from `a`).
-
-</details>
+`idle -. enter .->` points at the initial state passed to `toGraph` (`a` here); `b` is reachable from `a` via the bound `Reference`.
 
 `reference.ref` returns the bound state and throws if the reference is still unbound when the machine runs. `bind()` is sticky — the first call wins; subsequent calls are silent no-ops that return the existing binding.
 
@@ -406,29 +379,6 @@ console.log(tape.symbols.join('')); // "ab ba" — the X at index 2 is gone, hea
 
 What changes between *running `scanToX` standalone* and *running the composed wrapper*:
 
-```mermaid
-flowchart LR
-    subgraph standalone["scanToX (standalone) — halts at X"]
-        direction LR
-        a1(("scanToX"))
-        h1(((halt)))
-        a1 -- "X → keep, S" --> h1
-        a1 -- "any other → keep, R" --> a1
-    end
-    subgraph composed["scanToX.withOverriddenHaltState(eraseHere) — halt is intercepted"]
-        direction LR
-        a2(("scanToX"))
-        b2(("eraseHere"))
-        h2(((halt)))
-        a2 -. "X → keep, S<br/>intercepted" .-> b2
-        a2 -- "any other → keep, R" --> a2
-        b2 -- "any → erase, S" --> h2
-    end
-```
-
-<details>
-<summary>📊 Both diagrams, generated by <code>toMermaid()</code></summary>
-
 `toMermaid(toGraph(scanToX, tapeBlock))` — the standalone subroutine:
 
 ```mermaid
@@ -438,8 +388,8 @@ flowchart TD
   s1["scanToX"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'X' → K/⇹" --> s0
-  s1 -- "∗ → K/→" --> s1
+  s1 -- "'X' → K/S" --> s0
+  s1 -- "🞰 → K/R" --> s1
 ```
 
 `toMermaid(toGraph(scanThenErase, tapeBlock))` — the wrapped composition:
@@ -455,9 +405,9 @@ flowchart TD
     c3(((halt)))
   end
   idle -. enter .-> s3
-  s2 -- "∗ → E/⇹" --> s0
-  s3 -- "'X' → K/⇹" --> c3
-  s3 -- "∗ → K/→" --> s3
+  s2 -- "🞰 → E/S" --> s0
+  s3 -- "'X' → K/S" --> c3
+  s3 -- "🞰 → K/R" --> s3
   s3 -. onHalt .-> s2
 ```
 
@@ -466,15 +416,13 @@ flowchart TD
 1. **The subgraph rectangle labeled `"halt frame"`** is the wrapper's runtime scope — while execution is "inside" this rectangle, the override target (`eraseHere`) sits on the runtime stack waiting to catch a halt. Visual-only; it does not mutate any edges.
 2. **`[[scanToX]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node. It's both the runtime entry point (execution starts here when entering the wrapper) AND the source of the dotted `onHalt` redirect. The wrapper's composite name (`scanToX(eraseHere)`) is computed at runtime via `state.name` but does not appear as a graph node label — only the bare's name is in the graph.
 3. **The cloned `(((halt)))` inside the subgraph** (`c3` here) is where the bare's halt-bound transitions land *inside* the wrapper's scope. `haltState` is a runtime singleton; the cloned node is a teaching aid showing "halt is caught here, not at the real terminus." Solid arrows from the bare to the cloned halt all stay inside the rectangle.
-4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. The single arrow that crosses the subgraph border. Originates from the wrapper-node since the wrapper *is* the catcher.
+4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. Originates from the wrapper-node since the wrapper *is* the catcher. Solid arrows from `[[scanToX]]` to other states can also cross the subgraph border — those are just regular runtime transitions whose target happens to be drawn outside this rectangle (only the dotted `onHalt` carries wrapper-machinery meaning). In larger compositions (`library-binary-numbers`'s `minusOne`), solid transitions whose target is *itself* a wrapped state render as a **thick `==>` arrow** instead of `-->` — that's the visual signal for "this transition enters a halt frame, pushing the override onto the runtime stack." Stack-growth structure is then scannable from the diagram: count thick arrows along an execution path to see how deep the stack gets.
 5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame — here, by `eraseHere` after it erases the cell.
 
-**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `∗ → K/→` self-loops until the head sees `X`; the `'X' → K/⇹` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `∗ → E/⇹` and halts at real `s0`. Run terminates.
+**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `🞰 → K/R` self-loops until the head sees `X`; the `'X' → K/S` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `🞰 → E/S` and halts at real `s0`. Run terminates.
 
 > 💡 **Round-trip caveat.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers like this one ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). For shared-bare cases (same `State` instance used as the bare in multiple wrappers — e.g., `library-binary-numbers`'s `minusOne`), per-context duplication produces wrapper-id-dependent ordering that doesn't byte-match across rebuilds — equivalent runtime behavior, different emit-line order.
 
-</details>
-
 Wrappers nest: `inner.withOverriddenHaltState(middle).withOverriddenHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
 
 ## Debugging breakpoints
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 7767f07..43db5f1 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -232,7 +232,7 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
     // pointing in a loop.
     // Nodes need at least one transition each — State construction at pass 2
     // rejects empty stateDefinitions before pass 3's cycle check would run.
-    const dummyTransition = {pattern: '∗', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"};
+    const dummyTransition = {pattern: '🞰', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"};
     const graph = {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index 6bd6128..b3d29d2 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -19,20 +19,20 @@ describe('decodePatternDescription', () => {
     expect(decodePatternDescription(undefined, alphabets)).toBe('?');
   });
 
-  test('"other symbol" → "∗" (whole-state ifOtherSymbol)', () => {
-    expect(decodePatternDescription('other symbol', alphabets)).toBe('∗');
+  test('"other symbol" → "🞰" (whole-state ifOtherSymbol)', () => {
+    expect(decodePatternDescription('other symbol', alphabets)).toBe('🞰');
   });
 
   test('literal cell wraps in single quotes', () => {
     expect(decodePatternDescription('[["0"]]', alphabets)).toBe("'0'");
   });
 
-  test('per-cell null → "∗"', () => {
-    expect(decodePatternDescription('[[null]]', alphabets)).toBe('∗');
+  test('per-cell null → "🞰"', () => {
+    expect(decodePatternDescription('[[null]]', alphabets)).toBe('🞰');
   });
 
-  test('cell equal to tape blank → "-"', () => {
-    expect(decodePatternDescription('[[" "]]', alphabets)).toBe('-');
+  test('cell equal to tape blank → "B"', () => {
+    expect(decodePatternDescription('[[" "]]', alphabets)).toBe('B');
   });
 
   test('multi-tape pattern joins quoted cells with ","', () => {
@@ -77,9 +77,9 @@ describe('decodeMovement', () => {
   });
 
   test.each([
-    [(movements.left as symbol).description, '←'],
-    [(movements.right as symbol).description, '→'],
-    [(movements.stay as symbol).description, '⇹'],
+    [(movements.left as symbol).description, 'L'],
+    [(movements.right as symbol).description, 'R'],
+    [(movements.stay as symbol).description, 'S'],
   ])('%s → %s', (description, expected) => {
     expect(decodeMovement(description)).toBe(expected);
   });
@@ -121,8 +121,8 @@ describe('toMermaid', () => {
         1: {
           id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: 'K', movement: '→'}], nextStateId: 1, id: "test-edge"},
-            {pattern: '1', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -134,8 +134,8 @@ describe('toMermaid', () => {
     expect(out).toContain('s1["entry"]');
     expect(out).toContain('idle([idle])');
     expect(out).toContain('idle -. enter .-> s1');
-    expect(out).toContain('s1 -- "0 → K/→" --> s1');
-    expect(out).toContain('s1 -- "1 → K/⇹" --> s0');
+    expect(out).toContain('s1 -- "0 → K/R" --> s1');
+    expect(out).toContain('s1 -- "1 → K/S" --> s0');
   });
 
   test('renders dotted onHalt edge when overriddenHaltStateId is set', () => {
@@ -175,7 +175,7 @@ describe('toMermaid', () => {
           id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [{
             pattern: '0,a',
-            command: [{symbol: '0', movement: '→'}, {symbol: 'a', movement: '←'}],
+            command: [{symbol: '0', movement: 'R'}, {symbol: 'a', movement: 'L'}],
             nextStateId: 0,
             id: 'test-edge',
           }],
@@ -183,7 +183,7 @@ describe('toMermaid', () => {
       },
     });
 
-    expect(out).toContain('"0,a → 0/→,a/←"');
+    expect(out).toContain('"0,a → 0/R,a/L"');
   });
 });
 
@@ -203,24 +203,24 @@ describe('splitUnescaped', () => {
 
 describe('parsePatternString', () => {
   test('returns null for the global ifOtherSymbol marker', () => {
-    expect(parsePatternString('∗', [[' ', '0']])).toBeNull();
+    expect(parsePatternString('🞰', [[' ', '0']])).toBeNull();
   });
 
-  test('per-cell `∗` becomes null', () => {
+  test('per-cell `🞰` becomes null', () => {
     // Multi-tape pattern where one cell is per-cell ifOtherSymbol.
-    expect(parsePatternString("'0',∗", [[' ', '0'], [' ', 'a']])).toEqual([['0', null]]);
+    expect(parsePatternString("'0',🞰", [[' ', '0'], [' ', 'a']])).toEqual([['0', null]]);
   });
 
-  test('per-cell `-` becomes the tape blank symbol', () => {
-    expect(parsePatternString("-,'a'", [[' ', '0'], [' ', 'a']])).toEqual([[' ', 'a']]);
+  test('per-cell `B` becomes the tape blank symbol', () => {
+    expect(parsePatternString("B,'a'", [[' ', '0'], [' ', 'a']])).toEqual([[' ', 'a']]);
   });
 });
 
 describe('parseMovementLabel', () => {
-  test('maps ←/→/⇹ to upstream movement symbols', () => {
-    expect(parseMovementLabel('←')).toBe(movements.left);
-    expect(parseMovementLabel('→')).toBe(movements.right);
-    expect(parseMovementLabel('⇹')).toBe(movements.stay);
+  test('maps ←/R/S to upstream movement symbols', () => {
+    expect(parseMovementLabel('L')).toBe(movements.left);
+    expect(parseMovementLabel('R')).toBe(movements.right);
+    expect(parseMovementLabel('S')).toBe(movements.stay);
   });
 
   test('throws on unknown label', () => {
@@ -322,8 +322,8 @@ describe('README example: toMermaid output is stable', () => {
       '  s1["name"]',
       '  idle([idle])',
       '  idle -. enter .-> s1',
-      "  s1 -- \"'1' → '0'/→\" --> s1",
-      "  s1 -- \"'$' → K/←\" --> s0",
+      "  s1 -- \"'1' → '0'/R\" --> s1",
+      "  s1 -- \"'$' → K/L\" --> s0",
     ].join('\n');
 
     expect(toMermaid(State.toGraph(s, tapeBlock))).toBe(expected);
@@ -334,7 +334,7 @@ describe('README example: toMermaid output is stable', () => {
 // READMEs. Each test asserts the expected lines are present; we don't pin
 // state IDs as exact values because they auto-increment globally and depend
 // on test ordering. The test catches engine emit-format changes (e.g. if
-// "b → */→" notation drifts) without being fragile to ID assignment.
+// "b → */R" notation drifts) without being fragile to ID assignment.
 import Reference from '../classes/Reference';
 import {ifOtherSymbol} from '../classes/State';
 
@@ -363,9 +363,9 @@ describe('README diagrams: engine-generated outputs', () => {
       '["replaceB"]', // initial — square (no longer round in v7; idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      "\"'b' → '*'/→\"",
-      '"- → K/←"',
-      '"∗ → K/→"',
+      "\"'b' → '*'/R\"",
+      '"B → K/L"',
+      '"🞰 → K/R"',
     ]);
   });
 
@@ -387,8 +387,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["b"]', // b is reachable from a → square
       'idle([idle])',
       'idle -. enter .->',
-      "\"'x' → K/⇹\"",
-      "\"'y' → K/⇹\"",
+      "\"'x' → K/S\"",
+      "\"'y' → K/S\"",
     ]);
   });
 
@@ -410,8 +410,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["scanToX"]', // initial — square (idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      "\"'X' → K/⇹\"",
-      '"∗ → K/→"',
+      "\"'X' → K/S\"",
+      '"🞰 → K/R"',
     ]);
   });
 
@@ -440,7 +440,7 @@ describe('README diagrams: engine-generated outputs', () => {
       '"halt frame"', // subgraph label
       'idle([idle])', // pre-execution sentinel — always emitted
       'idle -. enter .->', // labeled dotted enter arrow points at the initial state
-      '"∗ → E/⇹"', // eraseHere's erase command
+      '"🞰 → E/S"', // eraseHere's erase command
       '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
     ]);
   });
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index 6a24ae0..d2db22d 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -35,16 +35,10 @@ export type Graph = {
   nodes: Record<number, GraphNode>;
 };
 
-// Head-movement labels use directional Unicode arrows for visual clarity in
-// rendered Mermaid output: `←` (U+2190) left, `→` (U+2192) right, `⇹` (U+21F9
-// LEFT RIGHT OPEN-HEADED ARROW) stay. The right-arrow `→` is the same glyph
-// used by the read-to-write separator in edge labels; `fromMermaid` parses
-// labels via `indexOf(' → ')` (note the surrounding spaces) so the unspaced
-// `→` in a movement position doesn't collide.
 const movementDescriptionToLabel: Record<string, string> = {
-  'move caret left command': '←',
-  'move caret right command': '→',
-  'do not move carer': '⇹',
+  'move caret left command': 'L',
+  'move caret right command': 'R',
+  'do not move carer': 'S',
 };
 
 const symbolCommandDescriptionToLabel: Record<string, string> = {
@@ -53,21 +47,24 @@ const symbolCommandDescriptionToLabel: Record<string, string> = {
 };
 
 // Reserved characters in the encoded pattern string:
-//   '∗'  (U+2217 ASTERISK OPERATOR) per-cell ifOtherSymbol — matches any
-//        symbol on that tape. Distinct from the regular ASCII '*' (U+002A) so
-//        an alphabet that contains literal '*' (rendered as the quoted `'*'`)
-//        is unambiguously different from the catch-all marker.
-//   '-'  the tape's blank symbol
+//   '🞰'  (U+1F7B0 HEAVY EIGHT BALLOON-SPOKED ASTERISK) per-cell ifOtherSymbol —
+//        matches any symbol on that tape. Distinct from the regular ASCII '*'
+//        (U+002A) so an alphabet that contains literal '*' (rendered as the
+//        quoted `'*'`) is unambiguously different from the catch-all marker.
+//   'B'  the tape's blank symbol shorthand (in read patterns). A literal `B`
+//        in the alphabet is unambiguous from the marker because it's quoted
+//        (`'B'`).
 //   ','  separates per-tape cells inside one pattern
 //   '|'  separates alternative patterns
 //   "'"  surrounds a literal alphabet symbol — e.g. `'0'` for literal `0`,
 //        `'X'` for literal `X`. The quoting is what visually separates literal
-//        symbols from the convention markers `∗` / `-` and from the write
+//        symbols from the convention markers `🞰` / `B` and from the write
 //        commands `K` / `E`.
-//   '\\' escape prefix — to represent any of '∗', '-', ',', '|', "'", or '\\'
+//   '\\' escape prefix — to represent any of '🞰', 'B', ',', '|', "'", or '\\'
 //        as a *literal* alphabet symbol *inside* the quotes (e.g. `'\''` for
 //        a literal apostrophe).
-const IF_OTHER_MARKER = '∗';
+const IF_OTHER_MARKER = '🞰';
+const BLANK_MARKER = 'B';
 
 function escapeAlphabetSymbol(s: string): string {
   return s
@@ -98,7 +95,7 @@ export function decodePatternDescription(
           }
 
           if (s === alphabets[tapeIx]?.[0]) {
-            return '-';
+            return BLANK_MARKER;
           }
 
           return `'${escapeAlphabetSymbol(s)}'`;
@@ -162,7 +159,7 @@ export function parsePatternString(s: string, alphabets: string[][]): ParsedPatt
         return null;
       }
 
-      if (cell === '-') {
+      if (cell === BLANK_MARKER) {
         return alphabets[tapeIx]?.[0] ?? cell;
       }
 
@@ -178,9 +175,9 @@ export function parsePatternString(s: string, alphabets: string[][]): ParsedPatt
 }
 
 const movementLabelToSymbol: Record<string, symbol> = {
-  '←': movements.left,
-  '→': movements.right,
-  '⇹': movements.stay,
+  L: movements.left,
+  R: movements.right,
+  S: movements.stay,
 };
 
 export function parseMovementLabel(label: string): symbol {
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 39bc5c7..02d49ec 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -117,8 +117,19 @@ export function toMermaid(graph: Graph): string {
       const cmd = t.command.map((c) => `${c.symbol}/${c.movement}`).join(',');
       const label = `${t.pattern} → ${cmd}`;
 
+      // Thicker `==>` arrow when the transition crosses INTO a wrapper —
+      // signals "this transition pushes that wrapper's override onto the
+      // runtime stack" (per `TuringMachine.run` line ~220's
+      // `if (state !== nextState && nextState.overriddenHaltState) push(...)`).
+      // Self-loops (state === nextState) don't push at runtime — keep the
+      // regular `-->` for those even when the target is wrapped.
+      const targetNode = graph.nodes[t.nextStateId];
+      const isEnteringWrapper = targetNode && targetNode.isWrapped && t.nextStateId !== node.id;
+      const lineSegment = isEnteringWrapper ? '==' : '--';
+      const arrowTip = isEnteringWrapper ? '==>' : '-->';
+
       lines.push(
-        `  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`,
+        `  ${mermaidIdFor(node.id)} ${lineSegment} "${label}" ${arrowTip} ${mermaidIdFor(t.nextStateId)}`,
       );
     }
 
@@ -151,6 +162,7 @@ const subgraphEndRegex = /^end$/;
 const idleNodeRegex = /^idle\(\[idle\]\)$/;
 const enterArrowRegex = /^idle\s+-\.\s+enter\s+\.->\s+(s\d+)$/;
 const transitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
+const thickTransitionRegex = /^([sc]\d+)\s+==\s+"(.*)"\s+==>\s+([sc]\d+)$/;
 const onHaltRegex = /^([sc]\d+)\s+-\.\s+onHalt\s+\.->\s+([sc]\d+)$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
 // the preceding \s* and a permissive (.+); see CodeQL js/polynomial-redos.
@@ -274,7 +286,9 @@ export function fromMermaid(text: string): Graph {
       continue;
     }
 
-    const tm = line.match(transitionRegex);
+    // Thick transition (`==> `) and regular transition (`-->`) share the same
+    // semantics — only the visual differs. Parse both via the same code path.
+    const tm = line.match(transitionRegex) ?? line.match(thickTransitionRegex);
 
     if (tm) {
       const fromId = parseMermaidId(tm[1]);
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 2fcfb66..17347db 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -11,8 +11,8 @@ describe('summarizeGraph', () => {
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: 'K', movement: '→'}], nextStateId: 1, id: "test-edge"},
-            {pattern: '1', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -35,7 +35,7 @@ describe('summarizeGraph', () => {
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
           transitions: [
-            {pattern: '0', command: [{symbol: 'K', movement: '→'}], nextStateId: 1, id: "test-edge"},
+            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
           ],
         },
       },
@@ -55,7 +55,7 @@ describe('summarizeGraph', () => {
         0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
         1: {
           id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
-          transitions: [{pattern: '0', command: [{symbol: 'K', movement: '⇹'}], nextStateId: 0, id: "test-edge"}],
+          transitions: [{pattern: '0', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
         },
       },
     };
@@ -122,7 +122,7 @@ describe('State.inspect', () => {
 
     const haltTransition = info.transitions.find((t) => t.nextState?.name === haltState.name);
     expect(haltTransition).toBeTruthy();
-    expect(haltTransition!.command[0].movement).toBe('→');
+    expect(haltTransition!.command[0].movement).toBe('R');
     expect(haltTransition!.command[0].symbol).toBe("'1'");
   });
 
diff --git a/packages/machine/src/utilities/introspection.ts b/packages/machine/src/utilities/introspection.ts
index ca34c5d..8c82059 100644
--- a/packages/machine/src/utilities/introspection.ts
+++ b/packages/machine/src/utilities/introspection.ts
@@ -17,7 +17,7 @@ import {type Graph} from './graph';
 //
 //   const a = summarize(binaryNumbers.states.minusOne, binaryNumbers.getTapeBlock());
 //   const b = summarize(binaryNumbersBare.states.minusOne, binaryNumbersBare.getTapeBlock());
-//   // a.stateCount === 17, b.stateCount === 3
+//   // a.stateCount === 15, b.stateCount === 3
 //   // a.maxCompositionDepth === 4, b.maxCompositionDepth === 0
 export type GraphSummary = {
   // Counts
@@ -40,6 +40,12 @@ export type GraphSummary = {
 export function summarizeGraph(graph: Graph): GraphSummary {
   const nodes = Object.values(graph.nodes);
 
+  // `isClonedHalt` nodes are visualization sentinels — one per wrapper context,
+  // all corresponding to the singleton `haltState` at runtime. They don't
+  // count as distinct runtime states; matches the per-algorithm header in
+  // `library-binary-numbers/states.md`.
+  const runtimeStateCount = nodes.filter((n) => !n.isClonedHalt).length;
+
   let transitionCount = 0;
   let compositionEdgeCount = 0;
   let selfLoopCount = 0;
@@ -134,7 +140,7 @@ export function summarizeGraph(graph: Graph): GraphSummary {
   }
 
   return {
-    stateCount: nodes.length,
+    stateCount: runtimeStateCount,
     transitionCount,
     compositionEdgeCount,
     maxCompositionDepth,
diff --git a/scripts/build-states-md.mjs b/scripts/build-states-md.mjs
index e8b6aa4..3a1ce2d 100644
--- a/scripts/build-states-md.mjs
+++ b/scripts/build-states-md.mjs
@@ -57,7 +57,7 @@ if (libName === null) {
     process.exit(1);
   }
 
-  const {State, toMermaid} = await import('../packages/machine/dist/index.mjs');
+  const {State, summarizeGraph, toMermaid} = await import('../packages/machine/dist/index.mjs');
   const library = (await import(entry.importPath)).default;
 
   const sections = [`# ${entry.name} — state graphs`, ''];
@@ -66,14 +66,22 @@ if (libName === null) {
     const tapeBlock = library.getTapeBlock();
     const graph = State.toGraph(state, tapeBlock);
     const mermaid = toMermaid(graph);
-    // Exclude `isClonedHalt: true` nodes from the count — they are
-    // visualization-only sentinels (one per wrapper context, all mapped to the
-    // singleton `haltState` at runtime), not distinct runtime states.
-    const nodeCount = Object.values(graph.nodes).filter((n) => !n.isClonedHalt).length;
+    // Engine-owned introspection — dogfoods the same summary the public API
+    // exposes. `stateCount` already filters out `isClonedHalt` sentinels.
+    const summary = summarizeGraph(graph);
 
     sections.push(`## ${stateName}`);
     sections.push('');
-    sections.push(`*${nodeCount} state${nodeCount === 1 ? '' : 's'} (including \`haltState\`)*`);
+    sections.push(
+      `*${summary.stateCount} state${summary.stateCount === 1 ? '' : 's'}; `
+      + `${summary.transitionCount} transitions`
+      + (summary.compositionEdgeCount > 0
+        ? `; ${summary.compositionEdgeCount} wrapper${summary.compositionEdgeCount === 1 ? '' : 's'} `
+          + `(max nesting depth ${summary.maxCompositionDepth})`
+        : '')
+      + (summary.hasCycles ? '; has cycles' : '')
+      + '*',
+    );
     sections.push('');
     sections.push('```mermaid');
     sections.push(mermaid);

From c64e148b053c5ae82ca7e79af86b54f0105998da Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 20 May 2026 22:44:13 +0300
Subject: [PATCH 010/118] docs+emit polish: bracketed-tape-block format,
 multi-tape example, halt-marker rename
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Iterative UX refinements on top of the v7 emit, all in this branch
since the last commit. Several themes:

**Bracketed-tape-block edge labels** — `[reads] → [writes]/[moves]`
where each role wraps in `[…]`, always (even single-tape). Brackets
are the "tape-block" indicator. Cell content inside the brackets:
literal-quoted (`'X'`), `🞰` (U+1F7B0 ifOtherSymbol catch-all), `B`
(tape's blank shorthand), `K`/`E` (keep/erase write commands),
`L`/`R`/`S` (movements). Alternation is per-pattern bracket:
`['^']|['1']|['0']` for single-tape, `['0','a']|['1','b']` for
multi-tape. Compact `['^'|'1']` form rejected by `fromMermaid` (two
new strict-rejection tests added) to prevent the cross-product trap
in multi-tape (`['0'|'1','a'|'b']` would read as 4 combinations
rather than 2 paired alternatives).

**Thick `==>` arrows for stack-pushing transitions** — when a
transition's target is a wrapped state AND target ≠ source (i.e.
the engine's runtime push fires per `TuringMachine.run` line ~220).
Self-loops on wrappers don't push, stay regular `-->`. Reader can
scan an execution path counting thick arrows to see worst-case
wrapper-stack growth.

**"halt marker" replaces "cloned halt"** — the per-wrapper halt
sentinel inside each `subgraph w_N["halt frame"]` was previously
called a "clone", which misleadingly implied a real second copy at
runtime. It's a visualization-only marker that maps back to the
singleton `haltState` in `fromGraph`. Renamed `isClonedHalt` →
`isHaltMarker` on `GraphNode` (public-API type) to align the
implementation with the prose.

**Multi-tape example added** — a 2-tape "copier" machine in
§Diagram conventions illustrates the bracket-format with N=2 tapes.
Previously the engine had no documented multi-tape example.

**Restructured README sections**:
- Quick Start trimmed back to: code + diagram + one-paragraph
  diagram-specific read-out. No legend dump.
- New §Diagram conventions section near the end (right before
  §Versioning notes) holds the full reference: node shapes table,
  edge styles table, edge label format + cell vocabulary table,
  alternation rule + cross-product trap explanation, multi-tape
  example. Reader hits it as a reference once familiar with the
  library's concepts.
- 4 hand-drawn pedagogical Mermaid blocks removed from root +
  engine READMEs; engine `toMermaid()` output is now the primary
  illustration. Vocabulary mismatch between hand-drawn and engine
  diagrams is gone.

**Engine `CLAUDE.md`** rewritten to reflect v7 emit reality:
subgraph + `[[bare]]` + halt-marker + idle sentinel + edge-label
vocabulary + thick-arrow convention + per-context duplication for
shared-bare cases. `summarize().stateCount` filters halt-markers
(consistent with `states.md` header by construction). Added link
to Mermaid syntax docs + repo.

**Source-comment cleanups in `library-binary-numbers/src/index.ts`**:
- minusOne "17 nodes" → "15 nodes (per `summarize().stateCount`)";
  "four-deep subroutine chain" → "three-deep" (3 wrapper hops + 1
  terminal target — the previous "four-deep" was counting state
  names in the chain, not wrapper levels).
- Per-algorithm node counts updated where v7 emit changed them
  (deleteNumber/invertNumber 5→4, normalizeNumber 7→6,
  minusOneFast 10→8).

**`build-states-md.mjs` dogfoods `summarizeGraph`** for the per-
algorithm header line: `N states; N transitions; N wrappers (max
nesting depth N); has cycles`. No more manual counting in the
script.

**Pre-existing anchor fix** — `### Throttle pattern (v6.4.0+)`
heading → `### Throttle pattern`. Two cross-links elsewhere in the
README targeted `#throttle-pattern` and didn't resolve; dropping
the version suffix from the heading makes them resolve.

All 422 tests pass (420 prior + 2 new strict-rejection regression
tests for the compact alternation form). `equivalentOn` verified
unaffected — pure-runtime checker, doesn't touch any of the
visualization/introspection surface.
---
 CLAUDE.md                                     |   8 +-
 README.md                                     |  16 +-
 ...026-05-20-tomermaid-wrapper-emit-design.md |  28 +--
 .../library-binary-numbers-bare/states.md     |  32 ++--
 .../library-binary-numbers/src/graphs.spec.ts |   6 +-
 packages/library-binary-numbers/states.md     | 180 +++++++++---------
 packages/machine/README.md                    | 110 +++++++++--
 packages/machine/src/classes/State.spec.ts    |   6 +-
 packages/machine/src/classes/State.ts         |  20 +-
 packages/machine/src/utilities/graph.spec.ts  |  86 ++++++---
 packages/machine/src/utilities/graph.ts       |   8 +-
 .../machine/src/utilities/graphFormats.ts     | 140 +++++++++++---
 .../src/utilities/introspection.spec.ts       |  28 +--
 .../machine/src/utilities/introspection.ts    |   4 +-
 scripts/build-states-md.mjs                   |   2 +-
 test/round-trip.spec.ts                       |   2 +-
 16 files changed, 435 insertions(+), 241 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f4442c0..d6c4825 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,11 +61,15 @@ Key shapes that take reading multiple files to grasp:
 
 `packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same `Graph` through [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) syntax (renderer: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)). The parser is strict to the dialect `toMermaid` emits — hand-edited Mermaid with different arrow styles or shapes won't round-trip.
 
-**v7 emit shape** (PR #169, closes #138/#139): each `withOverriddenHaltState` wrapper collapses onto its bare's representation — `GraphNode.isWrapped: true`, no separate wrapper node in graph data. `toMermaid` wraps each `[[bare]]` (subroutine shape) + a synthesized `(((halt)))` clone (`GraphNode.isClonedHalt: true`, negative id; maps back to singleton `haltState` in `fromGraph`) inside a `subgraph w_${bareId}["halt frame"] … end` block. Dotted `onHalt` from `[[bare]]` crosses the subgraph border to the override target. An always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state (replaces v6's `((round))` shape convention). Edge labels: write commands `K` (keep) / `E` (erase), movements `L`/`R`/`S`, literal alphabet symbols quoted (`'X'`), unquoted markers `🞰` (U+1F7B0, ifOtherSymbol) and `B` (the tape's blank). Thick `==>` arrows mark transitions whose target is a wrapped state (= stack-push at runtime); regular `-->` for the rest; dotted reserved for wrapper machinery.
+**v7 emit shape** (PR #169, closes #138/#139): each `withOverriddenHaltState` wrapper collapses onto its bare's representation — `GraphNode.isWrapped: true`, no separate wrapper node in graph data. `toMermaid` wraps each `[[bare]]` (subroutine shape) + a synthesized `(((halt)))` marker (`GraphNode.isHaltMarker: true`, negative id; maps back to singleton `haltState` in `fromGraph`) inside a `subgraph w_${bareId}["halt frame"] … end` block. Dotted `onHalt` from `[[bare]]` crosses the subgraph border to the override target. An always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state (replaces v6's `((round))` shape convention).
+
+**Edge label vocabulary** — `[reads] → [writes]/[moves]`, each role wrapped in `[…]` (the tape-block indicator, one entry per tape; brackets always present, even single-tape). Read cells: literal-quoted (`'X'`), `🞰` (U+1F7B0, ifOtherSymbol catch-all), `B` (the tape's blank). Write cells: literal-quoted, `K` (keep), `E` (erase = write blank). Move cells: `L` / `R` / `S`. **Alternation is always per-pattern bracket** (`['^']|['1']|['0']` for single-tape, `['0','a']|['1','b']` for multi-tape); the compact in-bracket form `['^'|'1']` is rejected by `fromMermaid` to prevent the cross-product reading trap in multi-tape (`['0'|'1','a'|'b']` would read as 4 combinations rather than 2 paired alternatives, so the format avoids the shape entirely).
+
+**Edge arrow styles** — thick `==>` marks transitions whose target is a wrapped state AND ≠ source (= stack-push happens at runtime per `TuringMachine.run` line ~220); regular `-->` for the rest (including self-loops on wrappers, which don't push); dotted `-. onHalt .->` for the wrapper's catch-and-redirect; dotted `-. enter .->` from `idle` for execution-start.
 
 **Round-trip** is **bytewise stable for simple wrappers** (regression test in `test/round-trip.spec.ts` — #139). The wrapper's composite name (e.g. `scanToX(eraseHere)`) does NOT appear as a graph node label; only the bare's name does, so `fromGraph` recomputes the composite fresh on reconstruction — no accumulation. **Shared-bare cases** (same `State` instance used as the bare of multiple wrappers, e.g. `library-binary-numbers`'s `minusOne` where `invertNumber` is both the outermost bare AND wrapper-W1's bare) use **per-context duplication** in `toGraph`: each occurrence emits a separate graph node with the wrapper's `#id`. Reconstruction produces behaviorally-equivalent State instances (not necessarily the same runtime `#id`), but bytewise stability isn't guaranteed for shared-bare since duplicate ordering depends on runtime wrapper-ids that don't survive rebuild.
 
-**Stats helpers** — `summarize(state, tapeBlock)` returns `{stateCount, transitionCount, compositionEdgeCount, maxCompositionDepth, selfLoopCount, hasCycles, tapeCount, alphabetCardinalities}`. `stateCount` filters out `isClonedHalt` sentinels (they're visualization-only, all map to the singleton `haltState` at runtime); matches the per-algorithm header in `library-binary-numbers/states.md` by construction. `equivalentOn(reference, candidate, cases)` is the separate behavioral-equivalence checker — runs both machines, compares outputs and per-step snapshots; lives in `./utilities/equivalence.ts`, unaffected by the visualization-layer changes above.
+**Stats helpers** — `summarize(state, tapeBlock)` returns `{stateCount, transitionCount, compositionEdgeCount, maxCompositionDepth, selfLoopCount, hasCycles, tapeCount, alphabetCardinalities}`. `stateCount` filters out `isHaltMarker` sentinels (they're visualization-only, all map to the singleton `haltState` at runtime); matches the per-algorithm header in `library-binary-numbers/states.md` by construction. `equivalentOn(reference, candidate, cases)` is the separate behavioral-equivalence checker — runs both machines, compares outputs and per-step snapshots; lives in `./utilities/equivalence.ts`, unaffected by the visualization-layer changes above.
 
 ### Builder package
 
diff --git a/README.md b/README.md
index 092eb10..118810b 100644
--- a/README.md
+++ b/README.md
@@ -83,12 +83,20 @@ flowchart TD
   s1["replaceB"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'b' → '*'/R" --> s1
-  s1 -- "B → K/L" --> s0
-  s1 -- "🞰 → K/R" --> s1
+  s1 -- "['b'] → ['*']/[R]" --> s1
+  s1 -- "[B] → [K]/[L]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
 ```
 
-Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Movements: `L` / `R` / `S`. Literal alphabet symbols are wrapped in single quotes (`'b'`, `'*'`). Unquoted markers: `🞰` (U+1F7B0) = `ifOtherSymbol` catch-all, `B` = the tape's blank symbol. `(((halt)))` = halt; `["square"]` = a regular state; the `idle([idle])` sentinel + dotted `enter` arrow marks where execution begins. (Subroutine composition adds a `subgraph` "halt frame" + `[[double-walled]]` wrapper node — see [§Subroutine composition](packages/machine/README.md#subroutine-composition-with-withoverriddenhaltstate) in the engine README.)
+Quick legend for the diagram above — full table at [packages/machine/README.md § Diagram conventions](packages/machine/README.md#diagram-conventions):
+
+- **Edge format**: `[reads] → [writes]/[moves]` (each `[…]` is a tape-block reading; brackets always, even single-tape).
+- **Read cells**: `'X'` (literal, single-quoted), `🞰` (`ifOtherSymbol` catch-all, U+1F7B0), `B` (the tape's blank).
+- **Write cells**: `'X'` (literal), `K` (keep), `E` (erase = write blank).
+- **Movement cells**: `L` / `R` / `S` (left / right / stay).
+- **Node shapes**: `(((halt)))` = halt, `["square"]` = regular state, `[[double-walled]]` = wrapper-bare (subroutine shape), `idle([idle])` = pre-execution sentinel.
+- **Edges**: `-->` regular, `==>` thick = transition into a wrapper (stack-push), `-. onHalt .->` = wrapper's catch-and-redirect, `-. enter .->` from `idle` = where execution starts.
+- **Subgraph `w_N["halt frame"]`** wraps a `[[bare]]` + its halt marker — see [§Subroutine composition](packages/machine/README.md#subroutine-composition-with-withoverriddenhaltstate) in the engine README.
 
 Trace on the input tape `abcba`:
 
diff --git a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
index a5fb831..776d8b7 100644
--- a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
+++ b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
@@ -1,6 +1,6 @@
 # `toMermaid` wrapped-state emit — design comparison
 
-**Status:** decided — **Variant X with `subgraph` overlay + `idle` entry sentinel + readable command/symbol vocabulary**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))`. The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. A stadium-shaped `idle([idle])` sentinel + labeled dotted arrow `idle -. enter .-> sN` is always emitted to mark the initial state. Edge-label vocabulary: write commands `K` = keep, `E` = erase (write blank); literal alphabet symbols wrapped in single quotes (`'X'`, `'0'`); unquoted markers `*` = any (ifOtherSymbol), `-` = blank shorthand. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation in PR [#169](https://github.com/mellonis/turing-machine-js/pull/169).
+**Status:** decided — **Variant X with `subgraph` overlay + `idle` entry sentinel + bracketed-tape-block edge labels**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))`. The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. A stadium-shaped `idle([idle])` sentinel + labeled dotted arrow `idle -. enter .-> sN` is always emitted to mark the initial state. Edge labels: `[reads] → [writes]/[moves]` with each role wrapped in `[…]` (tape-block indicator, always present even single-tape); read cells use `'X'` literal-quoted, `🞰` (U+1F7B0) for ifOtherSymbol, `B` for the tape's blank; write cells use `K`/`E` plus literal-quoted; movements `L`/`R`/`S`. Alternation is per-pattern-bracket (`['^']|['1']`); compact `['^'|'1']` form is rejected by `fromMermaid` (would read as cross-product in multi-tape). Stack-pushing transitions emit thick `==>` arrows. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation in PR [#169](https://github.com/mellonis/turing-machine-js/pull/169).
 
 **Context.** [#138](https://github.com/mellonis/turing-machine-js/issues/138) — clean up the visually-confusing Mermaid output for `withOverriddenHaltState`-wrapped states. [#139](https://github.com/mellonis/turing-machine-js/issues/139) — bytewise round-trip regression for the wrapper name accumulation, naturally fixed by whichever design we pick.
 
@@ -259,7 +259,7 @@ Y₁ is the most faithful but the cost of per-context state duplication in `from
 After iteration, the locked shape evolves Variant X (collapse the wrapper into the bare's representation, no extra "wrapper node" in the graph data) with two visualization-only enhancements that make the wrapper's runtime semantics tangible without mutating the graph structure:
 
 1. A Mermaid **`subgraph` rectangle labeled `"halt frame"`** around each wrapper — the visual scope for "the wrapper's stack frame for halt handling."
-2. A **cloned `(((halt)))` node inside that subgraph** — visualization of "halt-bound transitions land here, *inside* the wrapper's scope." `haltState` is a runtime singleton; the cloned visual is a teaching aid (one halt-clone per wrapper context on the diagram, all corresponding to the single runtime instance).
+2. A **cloned `(((halt)))` node inside that subgraph** — visualization of "halt-bound transitions land here, *inside* the wrapper's scope." `haltState` is a runtime singleton; the cloned visual is a teaching aid (one halt marker per wrapper context on the diagram, all corresponding to the single runtime instance).
 
 ### Visual contract (what a reader sees)
 
@@ -268,7 +268,7 @@ After iteration, the locked shape evolves Variant X (collapse the wrapper into t
   - the wrapper's runtime entry point (execution starts here on entering the wrapper), and
   - the source of the dotted `onHalt` redirect (since the wrapper-node *is* the catcher).
 - **Cloned `(((halt)))` inside the subgraph** = the halt entry point within this wrapper's scope. Halt-bound transitions from the bare terminate here, not at the real halt.
-- **Solid arrows from `[[bare]]` to cloned halt** = the bare's structural halt-bound transitions. All stay inside the subgraph rectangle.
+- **Solid arrows from `[[bare]]` to halt marker** = the bare's structural halt-bound transitions. All stay inside the subgraph rectangle.
 - **Dotted `onHalt` arrow from `[[bare]]` out of the subgraph to the override target** = the wrapper's catch-and-redirect. Exactly one per wrapper. Solid arrows from `[[bare]]` to non-halt targets can ALSO cross the rectangle border (when the bare's transitions reach external states — common in compositions like `library-binary-numbers`'s `minusOne`); those are just regular runtime transitions, not wrapper machinery. Only the dotted `onHalt` carries wrapper-machinery meaning.
 - **Real `(((halt)))` outside any subgraph** = the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame (the unwrapped tail of the chain).
 
@@ -319,7 +319,7 @@ The wrapper's composite name (e.g. `scanToX(eraseHere)`) does **not** appear as
 
 ### Shared-bare handling
 
-`library-binary-numbers`'s `minusOne` = `invertNumber.with(plusOne.with(invertNumber.with(normalizeNumber)))` — same `invertNumber` instance is the bare of two distinct wrappers (outermost and innermost). Each wrapper context implies its own `subgraph` membership + its own cloned halt + its own dotted `onHalt` edge.
+`library-binary-numbers`'s `minusOne` = `invertNumber.with(plusOne.with(invertNumber.with(normalizeNumber)))` — same `invertNumber` instance is the bare of two distinct wrappers (outermost and innermost). Each wrapper context implies its own `subgraph` membership + its own halt marker + its own dotted `onHalt` edge.
 
 Plan: emit the bare as a separate graph node per wrapper context (per-context duplication in `toGraph`). The shared State instance is preserved at runtime; the graph and Mermaid emit are per-context. `fromGraph` reconstructs equivalent State instances (not necessarily the same runtime `#id` as the original — just behaviorally equivalent).
 
@@ -330,12 +330,12 @@ Plan: emit the bare as a separate graph node per wrapper context (per-context du
 3. `State.toGraph`:
    - Detect wrapper-States (those with `#overriddenHaltState !== null`).
    - Substitute with the bare; mark the bare's graph node `isWrapped: true`.
-   - Synthesize a per-wrapper cloned-halt graph node (a node with `isHalt: true` whose role is "halt-clone for this wrapper").
-   - Rewrite the bare's halt-bound transitions to target the cloned halt rather than the real one.
+   - Synthesize a per-wrapper halt-marker graph node (a node with `isHalt: true` whose role is "halt marker for this wrapper").
+   - Rewrite the bare's halt-bound transitions to target the halt marker rather than the real one.
 4. `toMermaid`:
    - `isWrapped: true` node → `s${id}[["${name}"]]` (subroutine shape).
-   - Cloned-halt node → `s${id}(((halt)))` (triple-paren, identical to real halt).
-   - Wrap each `[[bare]]` + its cloned halt in `subgraph wN["halt frame"] … end`.
+   - Halt-marker node → `s${id}(((halt)))` (triple-paren, identical to real halt).
+   - Wrap each `[[bare]]` + its halt marker in `subgraph wN["halt frame"] … end`.
    - Dotted onHalt edge `s${bareId} -. onHalt .-> s${overrideId}` (from `[[bare]]`, crossing the subgraph border).
 5. `fromMermaid`:
    - Parse Mermaid `subgraph wN["..."] … end` blocks.
@@ -343,7 +343,7 @@ Plan: emit the bare as a separate graph node per wrapper context (per-context du
    - Track subgraph membership for the round-trip.
 6. `State.fromGraph`:
    - For `isWrapped: true` nodes, reconstruct via `bareStates[id].withOverriddenHaltState(getFinal(overriddenHaltStateId))`.
-   - Cloned-halt graph nodes don't get separate State instances — they all map back to the singleton `haltState`.
+   - Halt-marker graph nodes don't get separate State instances — they all map back to the singleton `haltState`.
 7. `#139`'s round-trip test added; should pass after this design.
 8. `states.md` regenerates with the new shape (both binary libraries).
 9. README "Subroutine composition" section rewritten to use the new visual + reader's contract above.
@@ -354,15 +354,15 @@ Five design choices in #138's implementation that keep the demo's render + highl
 
 1. **Stable per-node ids in `Graph`.** Every node has a deterministic id:
    - Bare nodes: `node.id = bareState.id` (the engine's `State.#id`).
-   - Cloned-halt nodes: synthesized but deterministic from `(bareNodeId, wrapper-depth)`.
+   - Halt-marker nodes: synthesized but deterministic from `(bareNodeId, wrapper-depth)`.
    - Per-context bare duplicates: synthesized similarly.
 
    Mermaid emits `s${id}` for each; downstream can find the SVG node for any engine `state.id` directly.
 
-2. **Cloned-halt marker on `GraphNode`.** `isClonedHalt: boolean` (additional to `isHalt: true`). Real halt has `isHalt: true, isClonedHalt: false`; cloned halts have both `true`. Downstream uses this to:
-   - **#9** — emit cloned-halts with a different CSS class (`.cloned-halt` vs `.halt`) for styling.
-   - **#10** — skip cloned-halts when computing "current state highlight" (they're visualization aids, not runtime states).
-   - **#37** — skip cloned-halts when wiring click-to-toggle breakpoint handlers.
+2. **Halt-marker marker on `GraphNode`.** `isHaltMarker: boolean` (additional to `isHalt: true`). Real halt has `isHalt: true, isHaltMarker: false`; halt markers have both `true`. Downstream uses this to:
+   - **#9** — emit halt-markers with a different CSS class (`.halt-marker` vs `.halt`) for styling.
+   - **#10** — skip halt-markers when computing "current state highlight" (they're visualization aids, not runtime states).
+   - **#37** — skip halt-markers when wiring click-to-toggle breakpoint handlers.
 
 3. **Edge identity on `GraphTransition`.** Add `id: string` field, deterministic from `(fromNodeId, patternIndex)` where `patternIndex` is the index of that transition in the bare's symbol map. Mermaid emit injects the id via a CSS-class directive that downstream can target. This is what #10 needs to highlight "the edge that will fire next" precisely.
 
diff --git a/packages/library-binary-numbers-bare/states.md b/packages/library-binary-numbers-bare/states.md
index fdb91df..1e440f3 100644
--- a/packages/library-binary-numbers-bare/states.md
+++ b/packages/library-binary-numbers-bare/states.md
@@ -12,11 +12,11 @@ flowchart TD
   s2["plusOne"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "'1' → '0'/L" --> s1
-  s1 -- "'0' → '1'/S" --> s0
-  s1 -- "B → '1'/S" --> s0
-  s2 -- "'0'|'1' → K/R" --> s2
-  s2 -- "B → K/L" --> s1
+  s1 -- "['1'] → ['0']/[L]" --> s1
+  s1 -- "['0'] → ['1']/[S]" --> s0
+  s1 -- "[B] → ['1']/[S]" --> s0
+  s2 -- "['0']|['1'] → [K]/[R]" --> s2
+  s2 -- "[B] → [K]/[L]" --> s1
 ```
 
 ## minusOne
@@ -31,11 +31,11 @@ flowchart TD
   s4["minusOne"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "'0' → '1'/L" --> s3
-  s3 -- "'1' → '0'/S" --> s0
-  s3 -- "B → K/S" --> s0
-  s4 -- "'0'|'1' → K/R" --> s4
-  s4 -- "B → K/L" --> s3
+  s3 -- "['0'] → ['1']/[L]" --> s3
+  s3 -- "['1'] → ['0']/[S]" --> s0
+  s3 -- "[B] → [K]/[S]" --> s0
+  s4 -- "['0']|['1'] → [K]/[R]" --> s4
+  s4 -- "[B] → [K]/[L]" --> s3
 ```
 
 ## invertNumber
@@ -49,9 +49,9 @@ flowchart TD
   s5["invertNumber"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "'0' → '1'/R" --> s5
-  s5 -- "'1' → '0'/R" --> s5
-  s5 -- "B → K/S" --> s0
+  s5 -- "['0'] → ['1']/[R]" --> s5
+  s5 -- "['1'] → ['0']/[R]" --> s5
+  s5 -- "[B] → [K]/[S]" --> s0
 ```
 
 ## normalizeNumber
@@ -65,7 +65,7 @@ flowchart TD
   s6["normalizeNumber"]
   idle([idle])
   idle -. enter .-> s6
-  s6 -- "'0' → E/R" --> s6
-  s6 -- "'1' → K/S" --> s0
-  s6 -- "B → '0'/S" --> s0
+  s6 -- "['0'] → [E]/[R]" --> s6
+  s6 -- "['1'] → [K]/[S]" --> s0
+  s6 -- "[B] → ['0']/[S]" --> s0
 ```
diff --git a/packages/library-binary-numbers/src/graphs.spec.ts b/packages/library-binary-numbers/src/graphs.spec.ts
index ff6b3e4..c10938f 100644
--- a/packages/library-binary-numbers/src/graphs.spec.ts
+++ b/packages/library-binary-numbers/src/graphs.spec.ts
@@ -3,7 +3,7 @@ import binaryNumbers from './index';
 
 // Per-state counts pinned from the source comments above each declaration in
 // `index.ts`. These are runtime state counts (per `summarize().stateCount`),
-// which exclude the `isClonedHalt` visualization sentinels v7 synthesizes
+// which exclude the `isHaltMarker` visualization sentinels v7 synthesizes
 // inside each `halt frame` subgraph. The states.md per-algorithm header uses
 // the same definition, so all three sources agree by construction.
 const expectedNodeCount: Record<keyof typeof binaryNumbers['states'], number> = {
@@ -40,10 +40,10 @@ describe('library-binary-numbers state graphs', () => {
 
       // Every algorithm has exactly one REAL halt node (the singleton's id is
       // shared across all states' graphs). v7's wrapper-emit synthesizes one
-      // `isClonedHalt: true` node per wrapper context as a visualization aid —
+      // `isHaltMarker: true` node per wrapper context as a visualization aid —
       // those are filtered out here.
       const realHaltNodes = Object.values(graph.nodes)
-        .filter((node) => node.isHalt && !node.isClonedHalt);
+        .filter((node) => node.isHalt && !node.isHaltMarker);
 
       expect(realHaltNodes).toHaveLength(1);
     },
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 7040cc6..1c38dfc 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -11,8 +11,8 @@ flowchart TD
   s1["goToNumber"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "🞰 → K/R" --> s1
+  s1 -- "['$'] → [K]/[S]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
 ```
 
 ## goToNextNumber
@@ -27,9 +27,9 @@ flowchart TD
   s2["goToNextNumber"]
   idle([idle])
   idle -. enter .-> s2
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "🞰 → K/R" --> s1
-  s2 -- "🞰 → K/R" --> s1
+  s1 -- "['$'] → [K]/[S]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
+  s2 -- "[🞰] → [K]/[R]" --> s1
 ```
 
 ## goToPreviousNumber
@@ -44,9 +44,9 @@ flowchart TD
   s4["goToPreviousNumber"]
   idle([idle])
   idle -. enter .-> s4
-  s3 -- "'$' → K/S" --> s0
-  s3 -- "🞰 → K/L" --> s3
-  s4 -- "🞰 → K/L" --> s3
+  s3 -- "['$'] → [K]/[S]" --> s0
+  s3 -- "[🞰] → [K]/[L]" --> s3
+  s4 -- "[🞰] → [K]/[L]" --> s3
 ```
 
 ## deleteNumber
@@ -65,13 +65,13 @@ flowchart TD
     c7(((halt)))
   end
   idle -. enter .-> s8
-  s6 -- "'$' → E/S" --> s0
-  s6 -- "🞰 → E/R" --> s6
-  s7 -- "'^' → K/S" --> c7
-  s7 -- "🞰 → K/L" --> s7
+  s6 -- "['$'] → [E]/[S]" --> s0
+  s6 -- "[🞰] → [E]/[R]" --> s6
+  s7 -- "['^'] → [K]/[S]" --> c7
+  s7 -- "[🞰] → [K]/[L]" --> s7
   s7 -. onHalt .-> s6
-  s8 == "'^'|'1'|'0'|'$' → K/S" ==> s7
-  s8 -- "🞰 → K/S" --> s0
+  s8 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s7
+  s8 -- "[🞰] → [K]/[S]" --> s0
 ```
 
 ## goToNumbersStart
@@ -85,8 +85,8 @@ flowchart TD
   s5["goToNumberStart"]
   idle([idle])
   idle -. enter .-> s5
-  s5 -- "'^' → K/S" --> s0
-  s5 -- "🞰 → K/L" --> s5
+  s5 -- "['^'] → [K]/[S]" --> s0
+  s5 -- "[🞰] → [K]/[L]" --> s5
 ```
 
 ## invertNumber
@@ -105,15 +105,15 @@ flowchart TD
     c10(((halt)))
   end
   idle -. enter .-> s11
-  s9 -- "'^' → K/R" --> s9
-  s9 -- "'1' → '0'/R" --> s9
-  s9 -- "'0' → '1'/R" --> s9
-  s9 -- "'$' → K/S" --> s0
-  s10 -- "'^' → K/S" --> c10
-  s10 -- "🞰 → K/L" --> s10
+  s9 -- "['^'] → [K]/[R]" --> s9
+  s9 -- "['1'] → ['0']/[R]" --> s9
+  s9 -- "['0'] → ['1']/[R]" --> s9
+  s9 -- "['$'] → [K]/[S]" --> s0
+  s10 -- "['^'] → [K]/[S]" --> c10
+  s10 -- "[🞰] → [K]/[L]" --> s10
   s10 -. onHalt .-> s9
-  s11 == "'^'|'1'|'0'|'$' → K/S" ==> s10
-  s11 -- "🞰 → K/S" --> s0
+  s11 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
+  s11 -- "[🞰] → [K]/[S]" --> s0
 ```
 
 ## normalizeNumber
@@ -134,16 +134,16 @@ flowchart TD
     c14(((halt)))
   end
   idle -. enter .-> s15
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "🞰 → K/R" --> s1
-  s12 -- "B → '^'/S" --> s1
-  s13 -- "'^'|'0' → E/R" --> s13
-  s13 -- "'1'|'$' → K/L" --> s12
-  s14 -- "'^' → K/S" --> c14
-  s14 -- "🞰 → K/L" --> s14
+  s1 -- "['$'] → [K]/[S]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
+  s12 -- "[B] → ['^']/[S]" --> s1
+  s13 -- "['^']|['0'] → [E]/[R]" --> s13
+  s13 -- "['1']|['$'] → [K]/[L]" --> s12
+  s14 -- "['^'] → [K]/[S]" --> c14
+  s14 -- "[🞰] → [K]/[L]" --> s14
   s14 -. onHalt .-> s13
-  s15 == "'^'|'1'|'0'|'$' → K/S" ==> s14
-  s15 -- "🞰 → K/S" --> s0
+  s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
+  s15 -- "[🞰] → [K]/[S]" --> s0
 ```
 
 ## plusOne
@@ -160,16 +160,16 @@ flowchart TD
   s19["plusOne"]
   idle([idle])
   idle -. enter .-> s19
-  s16 -- "'1' → '0'/R" --> s16
-  s16 -- "'$' → K/S" --> s0
-  s17 -- "B → '^'/R" --> s17
-  s17 -- "'1' → K/R" --> s16
-  s18 -- "'0' → '1'/R" --> s16
-  s18 -- "'1' → K/L" --> s18
-  s18 -- "'^' → '1'/L" --> s17
-  s19 -- "'^'|'1'|'0' → K/R" --> s19
-  s19 -- "'$' → K/L" --> s18
-  s19 -- "🞰 → K/S" --> s0
+  s16 -- "['1'] → ['0']/[R]" --> s16
+  s16 -- "['$'] → [K]/[S]" --> s0
+  s17 -- "[B] → ['^']/[R]" --> s17
+  s17 -- "['1'] → [K]/[R]" --> s16
+  s18 -- "['0'] → ['1']/[R]" --> s16
+  s18 -- "['1'] → [K]/[L]" --> s18
+  s18 -- "['^'] → ['1']/[L]" --> s17
+  s19 -- "['^']|['1']|['0'] → [K]/[R]" --> s19
+  s19 -- "['$'] → [K]/[L]" --> s18
+  s19 -- "[🞰] → [K]/[S]" --> s0
 ```
 
 ## minusOne
@@ -211,43 +211,43 @@ flowchart TD
     c22(((halt)))
   end
   idle -. enter .-> s23
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "🞰 → K/R" --> s1
-  s9 -- "'^' → K/R" --> s9
-  s9 -- "'1' → '0'/R" --> s9
-  s9 -- "'0' → '1'/R" --> s9
-  s9 -- "'$' → K/S" --> s0
-  s10 -- "'^' → K/S" --> c10
-  s10 -- "🞰 → K/L" --> s10
+  s1 -- "['$'] → [K]/[S]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
+  s9 -- "['^'] → [K]/[R]" --> s9
+  s9 -- "['1'] → ['0']/[R]" --> s9
+  s9 -- "['0'] → ['1']/[R]" --> s9
+  s9 -- "['$'] → [K]/[S]" --> s0
+  s10 -- "['^'] → [K]/[S]" --> c10
+  s10 -- "[🞰] → [K]/[L]" --> s10
   s10 -. onHalt .-> s9
-  s12 -- "B → '^'/S" --> s1
-  s13 -- "'^'|'0' → E/R" --> s13
-  s13 -- "'1'|'$' → K/L" --> s12
-  s14 -- "'^' → K/S" --> c14
-  s14 -- "🞰 → K/L" --> s14
+  s12 -- "[B] → ['^']/[S]" --> s1
+  s13 -- "['^']|['0'] → [E]/[R]" --> s13
+  s13 -- "['1']|['$'] → [K]/[L]" --> s12
+  s14 -- "['^'] → [K]/[S]" --> c14
+  s14 -- "[🞰] → [K]/[L]" --> s14
   s14 -. onHalt .-> s13
-  s15 == "'^'|'1'|'0'|'$' → K/S" ==> s14
-  s15 -- "🞰 → K/S" --> s0
-  s16 -- "'1' → '0'/R" --> s16
-  s16 -- "'$' → K/S" --> s0
-  s17 -- "B → '^'/R" --> s17
-  s17 -- "'1' → K/R" --> s16
-  s18 -- "'0' → '1'/R" --> s16
-  s18 -- "'1' → K/L" --> s18
-  s18 -- "'^' → '1'/L" --> s17
-  s20 == "'^'|'1'|'0'|'$' → K/S" ==> s10
-  s20 -- "🞰 → K/S" --> c20
+  s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
+  s15 -- "[🞰] → [K]/[S]" --> s0
+  s16 -- "['1'] → ['0']/[R]" --> s16
+  s16 -- "['$'] → [K]/[S]" --> s0
+  s17 -- "[B] → ['^']/[R]" --> s17
+  s17 -- "['1'] → [K]/[R]" --> s16
+  s18 -- "['0'] → ['1']/[R]" --> s16
+  s18 -- "['1'] → [K]/[L]" --> s18
+  s18 -- "['^'] → ['1']/[L]" --> s17
+  s20 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
+  s20 -- "[🞰] → [K]/[S]" --> c20
   s20 -. onHalt .-> s15
-  s21 -- "'^'|'1'|'0' → K/R" --> s21
-  s21 -- "'$' → K/L" --> s18
-  s21 -- "🞰 → K/S" --> c21
+  s21 -- "['^']|['1']|['0'] → [K]/[R]" --> s21
+  s21 -- "['$'] → [K]/[L]" --> s18
+  s21 -- "[🞰] → [K]/[S]" --> c21
   s21 -. onHalt .-> s20
-  s22 == "'^'|'1'|'0'|'$' → K/S" ==> s10
-  s22 -- "🞰 → K/S" --> c22
+  s22 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
+  s22 -- "[🞰] → [K]/[S]" --> c22
   s22 -. onHalt .-> s21
-  s23 -- "'^'|'1'|'0' → K/R" --> s23
-  s23 == "'$' → K/S" ==> s22
-  s23 -- "🞰 → K/S" --> s0
+  s23 -- "['^']|['1']|['0'] → [K]/[R]" --> s23
+  s23 == "['$'] → [K]/[S]" ==> s22
+  s23 -- "[🞰] → [K]/[S]" --> s0
 ```
 
 ## minusOneFast
@@ -273,21 +273,21 @@ flowchart TD
     c25(((halt)))
   end
   idle -. enter .-> s26
-  s1 -- "'$' → K/S" --> s0
-  s1 -- "🞰 → K/R" --> s1
-  s12 -- "B → '^'/S" --> s1
-  s13 -- "'^'|'0' → E/R" --> s13
-  s13 -- "'1'|'$' → K/L" --> s12
-  s14 -- "'^' → K/S" --> c14
-  s14 -- "🞰 → K/L" --> s14
+  s1 -- "['$'] → [K]/[S]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
+  s12 -- "[B] → ['^']/[S]" --> s1
+  s13 -- "['^']|['0'] → [E]/[R]" --> s13
+  s13 -- "['1']|['$'] → [K]/[L]" --> s12
+  s14 -- "['^'] → [K]/[S]" --> c14
+  s14 -- "[🞰] → [K]/[L]" --> s14
   s14 -. onHalt .-> s13
-  s15 == "'^'|'1'|'0'|'$' → K/S" ==> s14
-  s15 -- "🞰 → K/S" --> s0
-  s25 -- "'1' → '0'/S" --> c25
-  s25 -- "'0' → '1'/L" --> s25
-  s25 -- "'^' → K/S" --> c25
+  s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
+  s15 -- "[🞰] → [K]/[S]" --> s0
+  s25 -- "['1'] → ['0']/[S]" --> c25
+  s25 -- "['0'] → ['1']/[L]" --> s25
+  s25 -- "['^'] → [K]/[S]" --> c25
   s25 -. onHalt .-> s15
-  s26 -- "'^'|'1'|'0' → K/R" --> s26
-  s26 == "'$' → K/L" ==> s25
-  s26 -- "🞰 → K/S" --> s0
+  s26 -- "['^']|['1']|['0'] → [K]/[R]" --> s26
+  s26 == "['$'] → [K]/[L]" ==> s25
+  s26 -- "[🞰] → [K]/[S]" --> s0
 ```
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 065e109..9880a61 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -16,6 +16,7 @@ A composable Turing-machine engine for JavaScript: multi-tape, subroutine compos
 - [Debugging breakpoints](#debugging-breakpoints)
 - [Special objects](#special-objects) — [`haltState`](#haltstate) · [`ifOtherSymbol`](#ifothersymbol) · [`movements`](#movements) · [`symbolCommands`](#symbolcommands)
 - [Introspection and testing](#introspection-and-testing)
+- [Diagram conventions](#diagram-conventions)
 - [Versioning notes](#versioning-notes)
 - [Libraries](#libraries)
 - [Links](#links)
@@ -79,18 +80,16 @@ flowchart TD
   s1["replaceB"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'b' → '*'/R" --> s1
-  s1 -- "B → K/L" --> s0
-  s1 -- "🞰 → K/R" --> s1
+  s1 -- "['b'] → ['*']/[R]" --> s1
+  s1 -- "[B] → [K]/[L]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
 ```
 
-Engine notation: `read → write/move`. Write commands: `K` = keep, `E` = erase (write the blank). Movements: `L` = left, `R` = right, `S` = stay. Literal alphabet symbols are wrapped in single quotes: `'b'`, `'*'`, `'X'`. Unquoted markers: `🞰` (U+1F7B0 heavy-eight-balloon-spoked-asterisk) = `ifOtherSymbol` catch-all, `B` = the tape's blank symbol (a literal `B` in the alphabet appears as the quoted `'B'`, so the marker stays unambiguous). `(((double-paren)))` = halt; `["square"]` = a regular state. The `idle([idle])` sentinel + labeled-dotted `-. enter .->` arrow marks where execution begins. Wrapped states (subroutine-shaped `[[double-walled]]`) sit inside a `subgraph w_N["halt frame"]` block — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) below. **Arrow styles** between states: regular `-->` for plain transitions; thick `==>` for transitions whose target is a wrapped state (= stack-push happens at runtime); dotted `-. onHalt .->` for the wrapper's catch-and-redirect.
-
-The shapes and arrow styles above are standard [Mermaid flowchart syntax](https://mermaid.js.org/syntax/flowchart.html); any tool that renders Mermaid (GitHub preview, IDE plugins, [mermaid-js](https://github.com/mermaid-js/mermaid) client-side) will paint these diagrams the same way.
+Reading this specific diagram: `replaceB` (the rectangle) is the start state, marked by the dotted `enter` arrow from the `idle` sentinel. Three self-or-halt transitions: read `'b'` → write `'*'` and step right; read anything else (`🞰`) → keep, step right; read blank (`B`) → keep, step left, halt. Full notation reference — shapes, edge styles, label vocabulary — in [§Diagram conventions](#diagram-conventions).
 
 A `State` is keyed by JS `Symbol`s returned from `tapeBlock.symbol(pattern)` — the pattern lists the expected symbol under each tape's head. Sentinels and constants used throughout: [`ifOtherSymbol`](#ifothersymbol) is the fallback key when nothing else matches; transitioning into [`haltState`](#haltstate) stops the run; [`movements`](#movements)`.{left,right,stay}` direct head moves; [`symbolCommands`](#symbolcommands)`.{keep,erase}` are write shortcuts. Full definitions in [§Special objects](#special-objects).
 
-For multi-tape machines, pass one element per tape: `tapeBlock.symbol(['0', 'a'])` matches only when tape 1 is at `'0'` and tape 2 is at `'a'`.
+For multi-tape machines, pass one element per tape: `tapeBlock.symbol(['0', 'a'])` matches only when tape 1 is at `'0'` and tape 2 is at `'a'`. See the multi-tape example in [§Diagram conventions](#diagram-conventions) for what the rendered graph looks like.
 
 ## Building from a state table
 
@@ -261,8 +260,8 @@ flowchart TD
   s1["name"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'1' → '0'/R" --> s1
-  s1 -- "'$' → K/L" --> s0
+  s1 -- "['1'] → ['0']/[R]" --> s1
+  s1 -- "['$'] → [K]/[L]" --> s0
 ```
 
 *Edge labels are `read → write/move`. Write commands: `K` = keep (no write), `E` = erase (write the blank). Literal alphabet symbols are quoted (`'1'`, `'$'`). Movements: `L` (left), `R` (right), `S` (stay).*
@@ -291,8 +290,8 @@ flowchart TD
   s2["b"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'x' → K/S" --> s2
-  s2 -- "'y' → K/S" --> s1
+  s1 -- "['x'] → [K]/[S]" --> s2
+  s2 -- "['y'] → [K]/[S]" --> s1
 ```
 
 `idle -. enter .->` points at the initial state passed to `toGraph` (`a` here); `b` is reachable from `a` via the bound `Reference`.
@@ -388,8 +387,8 @@ flowchart TD
   s1["scanToX"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "'X' → K/S" --> s0
-  s1 -- "🞰 → K/R" --> s1
+  s1 -- "['X'] → [K]/[S]" --> s0
+  s1 -- "[🞰] → [K]/[R]" --> s1
 ```
 
 `toMermaid(toGraph(scanThenErase, tapeBlock))` — the wrapped composition:
@@ -405,9 +404,9 @@ flowchart TD
     c3(((halt)))
   end
   idle -. enter .-> s3
-  s2 -- "🞰 → E/S" --> s0
-  s3 -- "'X' → K/S" --> c3
-  s3 -- "🞰 → K/R" --> s3
+  s2 -- "[🞰] → [E]/[S]" --> s0
+  s3 -- "['X'] → [K]/[S]" --> c3
+  s3 -- "[🞰] → [K]/[R]" --> s3
   s3 -. onHalt .-> s2
 ```
 
@@ -415,11 +414,11 @@ flowchart TD
 
 1. **The subgraph rectangle labeled `"halt frame"`** is the wrapper's runtime scope — while execution is "inside" this rectangle, the override target (`eraseHere`) sits on the runtime stack waiting to catch a halt. Visual-only; it does not mutate any edges.
 2. **`[[scanToX]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node. It's both the runtime entry point (execution starts here when entering the wrapper) AND the source of the dotted `onHalt` redirect. The wrapper's composite name (`scanToX(eraseHere)`) is computed at runtime via `state.name` but does not appear as a graph node label — only the bare's name is in the graph.
-3. **The cloned `(((halt)))` inside the subgraph** (`c3` here) is where the bare's halt-bound transitions land *inside* the wrapper's scope. `haltState` is a runtime singleton; the cloned node is a teaching aid showing "halt is caught here, not at the real terminus." Solid arrows from the bare to the cloned halt all stay inside the rectangle.
+3. **The cloned `(((halt)))` inside the subgraph** (`c3` here) is where the bare's halt-bound transitions land *inside* the wrapper's scope. `haltState` is a runtime singleton; the cloned node is a teaching aid showing "halt is caught here, not at the real terminus." Solid arrows from the bare to the halt marker all stay inside the rectangle.
 4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. Originates from the wrapper-node since the wrapper *is* the catcher. Solid arrows from `[[scanToX]]` to other states can also cross the subgraph border — those are just regular runtime transitions whose target happens to be drawn outside this rectangle (only the dotted `onHalt` carries wrapper-machinery meaning). In larger compositions (`library-binary-numbers`'s `minusOne`), solid transitions whose target is *itself* a wrapped state render as a **thick `==>` arrow** instead of `-->` — that's the visual signal for "this transition enters a halt frame, pushing the override onto the runtime stack." Stack-growth structure is then scannable from the diagram: count thick arrows along an execution path to see how deep the stack gets.
 5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame — here, by `eraseHere` after it erases the cell.
 
-**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `🞰 → K/R` self-loops until the head sees `X`; the `'X' → K/S` solid edge would normally halt — it lands on the cloned halt `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `🞰 → E/S` and halts at real `s0`. Run terminates.
+**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `[🞰] → [K]/[R]` self-loops until the head sees `X`; the `['X'] → [K]/[S]` solid edge would normally halt — it lands on the halt marker `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `[🞰] → [E]/[S]` and halts at real `s0`. Run terminates.
 
 > 💡 **Round-trip caveat.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers like this one ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). For shared-bare cases (same `State` instance used as the bare in multiple wrappers — e.g., `library-binary-numbers`'s `minusOne`), per-context duplication produces wrapper-id-dependent ordering that doesn't byte-match across rebuilds — equivalent runtime behavior, different emit-line order.
 
@@ -477,7 +476,7 @@ 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.
 
-### Throttle pattern (v6.4.0+)
+### 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:
 
@@ -567,6 +566,77 @@ Together: use `summarize` to ask "is this machine the right shape?" (size, compo
 
 For visualization and round-tripping, see `State.toGraph` / `State.fromGraph` and `toMermaid` / `fromMermaid`.
 
+## Diagram conventions
+
+The full reference for reading `toMermaid` output — shapes, edge styles, and the bracketed edge-label vocabulary. All shapes and arrows are standard [Mermaid flowchart syntax](https://mermaid.js.org/syntax/flowchart.html); any Mermaid renderer (GitHub preview, IDE plugins, [mermaid-js](https://github.com/mermaid-js/mermaid) client-side) paints these diagrams the same way.
+
+### Node shapes
+
+| Shape | Meaning |
+|---|---|
+| `s0(((halt)))` | the halt state |
+| `sN["name"]` | a regular state |
+| `sN[["name"]]` | a `withOverriddenHaltState` wrapper-bare (subroutine shape) — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) |
+| `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) |
+
+### Edge styles
+
+| Style | Where | Meaning |
+|---|---|---|
+| `-->` regular solid | between states | plain transition |
+| `==>` thick solid | between states | transition INTO a wrapped state — stack-push happens at runtime |
+| `-. onHalt .->` dotted | from `[[bare]]` to override | wrapper's catch-and-redirect |
+| `-. enter .->` dotted | from `idle` to initial state | execution-start marker |
+
+### Groupings
+
+`subgraph w_N["halt frame"] … end` wraps a `[[bare]]` + its halt marker — visual grouping of the wrapper's runtime halt-handling scope.
+
+### Edge label format
+
+`[reads] → [writes]/[moves]`. Each bracketed list is a tape-block reading — one entry per tape; brackets always present, even single-tape.
+
+| Glyph | Where | Meaning |
+|---|---|---|
+| `'X'` | read, write | literal alphabet symbol (single-quoted) |
+| `🞰` | read only | `ifOtherSymbol` catch-all (U+1F7B0 heavy-eight-balloon-spoked-asterisk) |
+| `B` | read only | the tape's blank symbol (a literal `B` in the alphabet appears as `'B'`, so the marker stays unambiguous) |
+| `K` | write only | keep (no write) |
+| `E` | write only | erase (write the tape's blank) |
+| `L` / `R` / `S` | move only | left / right / stay |
+
+### Alternation rule
+
+Alternative read patterns are always per-pattern-bracket:
+
+- Single-tape: `['^']|['1']|['0']`
+- Multi-tape: `['0','a']|['1','b']` — "(tape 1=`'0'` AND tape 2=`'a'`) OR (tape 1=`'1'` AND tape 2=`'b'`)"
+
+The compact in-bracket form `['^'|'1']` is **rejected** by `fromMermaid` — and never emitted by `toMermaid`. The reason is pedagogical: each alternative is its own drawn transition, and the compact form would read as cross-product semantics in multi-tape (`['0'|'1','a'|'b']` could mean 4 combinations rather than 2 paired alternatives). One consistent rule across tape counts: each alternative is a full bracketed pattern.
+
+### Multi-tape example
+
+A 2-tape "copier" machine — as long as tape 1 reads a non-blank, write the same symbol to tape 2 and step both right; halt when tape 1 reads blank:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","0","1"],[" ","0","1"]]
+  s0(((halt)))
+  s1["copy"]
+  idle([idle])
+  idle -. enter .-> s1
+  s1 -- "['0',🞰] → [K,'0']/[R,R]" --> s1
+  s1 -- "['1',🞰] → [K,'1']/[R,R]" --> s1
+  s1 -- "[B,🞰] → [K]/[S]" --> s0
+```
+
+Reading `['0',🞰] → [K,'0']/[R,R]`:
+
+- **Read** `['0',🞰]` — tape 1 must be literal `'0'`; tape 2 is `ifOtherSymbol` (any).
+- **Write** `[K,'0']` — tape 1: keep; tape 2: write literal `'0'`.
+- **Move** `[R,R]` — both tapes step right.
+
 ## Versioning notes
 
 API surface changes since v3, in past tense so the timing of each piece is explicit:
@@ -581,7 +651,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **v7** *(in progress)* — Composition-representation overhaul. Breaking renames + reshapes scheduled for the v7 cut. Landing piecewise on the `v7` branch; one entry per landed change:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
   - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
-  - **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139)). The wrapper-and-its-bare pair collapses into a single graph node (`isWrapped: true`); the wrapper's composite name no longer appears as a node label (only the bare's name does). Each wrapper gets a Mermaid `subgraph w_${bareId}["halt frame"] … end` block containing the `[[bare]]` (subroutine shape) plus a cloned `(((halt)))` (visualization aid showing where halt-bound transitions land inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target — exactly one per wrapper. `Graph` data shape gains `isWrapped` and `isClonedHalt` flags on `GraphNode` and a stable `id` on `GraphTransition` (deterministic per-edge identifier — supports downstream tooling like the `machines-demo` interactive viewer at [machines-demo#10](https://github.com/mellonis/machines-demo/issues/10)). Cloned-halt graph nodes use negative ids and round-trip back to the singleton `haltState` via `fromGraph`. Bytewise round-trip stability falls out for simple wrappers (no composite name in the graph means `fromGraph(toGraph(state))` recomputes names fresh — no accumulation). Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use per-context duplication in the graph emit.
+  - **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139)). The wrapper-and-its-bare pair collapses into a single graph node (`isWrapped: true`); the wrapper's composite name no longer appears as a node label (only the bare's name does). Each wrapper gets a Mermaid `subgraph w_${bareId}["halt frame"] … end` block containing the `[[bare]]` (subroutine shape) plus a cloned `(((halt)))` (visualization aid showing where halt-bound transitions land inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target — exactly one per wrapper. `Graph` data shape gains `isWrapped` and `isHaltMarker` flags on `GraphNode` and a stable `id` on `GraphTransition` (deterministic per-edge identifier — supports downstream tooling like the `machines-demo` interactive viewer at [machines-demo#10](https://github.com/mellonis/machines-demo/issues/10)). Halt-marker graph nodes use negative ids and round-trip back to the singleton `haltState` via `fromGraph`. Bytewise round-trip stability falls out for simple wrappers (no composite name in the graph means `fromGraph(toGraph(state))` recomputes names fresh — no accumulation). Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use per-context duplication in the graph emit.
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 43db5f1..a9f9f21 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -237,9 +237,9 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2, isWrapped: false, isClonedHalt: false},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false},
       },
     };
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 8eca6e4..926ced9 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -345,12 +345,12 @@ export default class State {
   // wrapper-States (those with `#overriddenHaltState !== null`) are collapsed
   // onto their bare's representation in the graph, with the wrapper's own `#id`
   // used as the graph node id, `isWrapped: true`, and `overriddenHaltStateId`
-  // set to the override's collapsed id. A per-wrapper "cloned halt" graph node
-  // (id = negative-of-the-wrapper-id, `isHalt: true, isClonedHalt: true`) is
+  // set to the override's collapsed id. A per-wrapper "halt marker" graph node
+  // (id = negative-of-the-wrapper-id, `isHalt: true, isHaltMarker: true`) is
   // synthesized; the bare's halt-bound transitions are rewritten to target the
-  // cloned halt instead of the real one.
+  // halt marker instead of the real one.
   //
-  // Cloned-halt node ids use the negation of the wrapper's id so they sit in a
+  // Halt-marker node ids use the negation of the wrapper's id so they sit in a
   // disjoint integer range from real ids (which are always non-negative). Real
   // halt is always id 0.
   static toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
@@ -397,7 +397,7 @@ export default class State {
             id: 0,
             name: state.#name,
             isHalt: true,
-            isClonedHalt: false,
+            isHaltMarker: false,
             isWrapped: false,
             transitions: [],
             overriddenHaltStateId: null,
@@ -426,13 +426,13 @@ export default class State {
           ? wrapperGraphId(overrideTarget)
           : overrideTarget.#id;
 
-        // Emit the cloned-halt node if not already present (one per wrapper).
+        // Emit the halt-marker node if not already present (one per wrapper).
         if (!(clonedHaltId in nodes)) {
           nodes[clonedHaltId] = {
             id: clonedHaltId,
             name: 'halt',
             isHalt: true,
-            isClonedHalt: true,
+            isHaltMarker: true,
             isWrapped: false,
             transitions: [],
             overriddenHaltStateId: null,
@@ -444,7 +444,7 @@ export default class State {
           id: collapsedId,
           name: state.#name,
           isHalt: false,
-          isClonedHalt: false,
+          isHaltMarker: false,
           isWrapped: true,
           transitions: [],
           overriddenHaltStateId: overrideGraphId,
@@ -465,7 +465,7 @@ export default class State {
           }
 
           // Retarget transitions per Variant X conventions:
-          // - target == haltState → cloned halt (stays inside the subgraph)
+          // - target == haltState → halt marker (stays inside the subgraph)
           // - target == bare (self-loop) → the collapsed wrapper id
           // - target is itself a wrapper → that wrapper's collapsed id
           // - else → target's own id
@@ -515,7 +515,7 @@ export default class State {
         id: state.#id,
         name: state.#name,
         isHalt: false,
-        isClonedHalt: false,
+        isHaltMarker: false,
         isWrapped: false,
         transitions: [],
         overriddenHaltStateId: null,
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index b3d29d2..03ca516 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -117,12 +117,12 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
           transitions: [
-            {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
-            {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
+            {pattern: "'0'", command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
+            {pattern: "'1'", command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
           ],
         },
       },
@@ -134,8 +134,8 @@ describe('toMermaid', () => {
     expect(out).toContain('s1["entry"]');
     expect(out).toContain('idle([idle])');
     expect(out).toContain('idle -. enter .-> s1');
-    expect(out).toContain('s1 -- "0 → K/R" --> s1');
-    expect(out).toContain('s1 -- "1 → K/S" --> s0');
+    expect(out).toContain("s1 -- \"['0'] → [K]/[R]\" --> s1");
+    expect(out).toContain("s1 -- \"['1'] → [K]/[S]\" --> s0");
   });
 
   test('renders dotted onHalt edge when overriddenHaltStateId is set', () => {
@@ -143,8 +143,8 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
-        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isWrapped: false, isHaltMarker: false},
       },
     });
 
@@ -156,9 +156,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
-        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
-        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
       },
     });
 
@@ -170,12 +170,12 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0'], [' ', 'a']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
           transitions: [{
-            pattern: '0,a',
-            command: [{symbol: '0', movement: 'R'}, {symbol: 'a', movement: 'L'}],
+            pattern: "'0','a'",
+            command: [{symbol: "'0'", movement: 'R'}, {symbol: "'a'", movement: 'L'}],
             nextStateId: 0,
             id: 'test-edge',
           }],
@@ -183,7 +183,7 @@ describe('toMermaid', () => {
       },
     });
 
-    expect(out).toContain('"0,a → 0/R,a/L"');
+    expect(out).toContain("\"['0','a'] → ['0','a']/[R,L]\"");
   });
 });
 
@@ -259,10 +259,38 @@ describe('fromMermaid error paths', () => {
       '  s0(((halt)))',
       '  idle([idle])',
       '  idle -. enter .-> s1',
-      '  s1 -- "* → noslash" --> s0',
+      '  s1 -- "[*] → noslash" --> s0',
     ].join('\n');
 
-    expect(() => fromMermaid(mermaid)).toThrow('malformed command part');
+    expect(() => fromMermaid(mermaid)).toThrow('malformed command label');
+  });
+
+  test('rejects compact in-bracket alternation (must use per-pattern brackets)', () => {
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0","1"]]',
+      '  s0(((halt)))',
+      '  s1["entry"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      "  s1 -- \"['0'|'1'] → [K]/[R]\" --> s0", // compact alternation — should fail
+    ].join('\n');
+
+    expect(() => fromMermaid(mermaid)).toThrow(/compact in-bracket alternation/);
+  });
+
+  test('rejects `|` inside a write/move bracket too (commands have no alternation)', () => {
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0","1"]]',
+      '  s0(((halt)))',
+      '  s1["entry"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      "  s1 -- \"['0'] → [K|E]/[R]\" --> s0", // `|` in writes — should fail
+    ].join('\n');
+
+    expect(() => fromMermaid(mermaid)).toThrow(/compact in-bracket alternation/);
   });
 });
 
@@ -322,8 +350,8 @@ describe('README example: toMermaid output is stable', () => {
       '  s1["name"]',
       '  idle([idle])',
       '  idle -. enter .-> s1',
-      "  s1 -- \"'1' → '0'/R\" --> s1",
-      "  s1 -- \"'$' → K/L\" --> s0",
+      "  s1 -- \"['1'] → ['0']/[R]\" --> s1",
+      "  s1 -- \"['$'] → [K]/[L]\" --> s0",
     ].join('\n');
 
     expect(toMermaid(State.toGraph(s, tapeBlock))).toBe(expected);
@@ -363,9 +391,9 @@ describe('README diagrams: engine-generated outputs', () => {
       '["replaceB"]', // initial — square (no longer round in v7; idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      "\"'b' → '*'/R\"",
-      '"B → K/L"',
-      '"🞰 → K/R"',
+      "\"['b'] → ['*']/[R]\"",
+      '"[B] → [K]/[L]"',
+      '"[🞰] → [K]/[R]"',
     ]);
   });
 
@@ -387,8 +415,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["b"]', // b is reachable from a → square
       'idle([idle])',
       'idle -. enter .->',
-      "\"'x' → K/S\"",
-      "\"'y' → K/S\"",
+      "\"['x'] → [K]/[S]\"",
+      "\"['y'] → [K]/[S]\"",
     ]);
   });
 
@@ -410,8 +438,8 @@ describe('README diagrams: engine-generated outputs', () => {
       '["scanToX"]', // initial — square (idle arrow signals entry)
       'idle([idle])',
       'idle -. enter .->',
-      "\"'X' → K/S\"",
-      '"🞰 → K/R"',
+      "\"['X'] → [K]/[S]\"",
+      '"[🞰] → [K]/[R]"',
     ]);
   });
 
@@ -436,11 +464,11 @@ describe('README diagrams: engine-generated outputs', () => {
       '(((halt)))', // real halt outside any subgraph
       '["eraseHere"]', // override is a regular [name] node
       '[["scanToX"]]', // wrapper-collapsed bare uses subroutine shape inside the subgraph
-      'subgraph w_', // halt-frame subgraph wraps the bare + its cloned halt
+      'subgraph w_', // halt-frame subgraph wraps the bare + its halt marker
       '"halt frame"', // subgraph label
       'idle([idle])', // pre-execution sentinel — always emitted
       'idle -. enter .->', // labeled dotted enter arrow points at the initial state
-      '"🞰 → E/S"', // eraseHere's erase command
+      '"[🞰] → [E]/[S]"', // eraseHere's erase command
       '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
     ]);
   });
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index d2db22d..51c90db 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -23,10 +23,10 @@ export type GraphNode = {
   // wrapped state. Carries the `[[…]]` (subroutine) shape signal for `toMermaid`
   // and tells `fromGraph` to reconstruct via `bare.withOverriddenHaltState(target)`.
   isWrapped: boolean;
-  // `true` for a synthesized halt-clone graph node — one per wrapper context.
-  // Real halt has `isHalt: true, isClonedHalt: false`; cloned halts have both
-  // `true`. `fromGraph` maps cloned-halt nodes back to the singleton `haltState`.
-  isClonedHalt: boolean;
+  // `true` for a synthesized halt marker graph node — one per wrapper context.
+  // Real halt has `isHalt: true, isHaltMarker: false`; halt markers have both
+  // `true`. `fromGraph` maps halt-marker nodes back to the singleton `haltState`.
+  isHaltMarker: boolean;
 };
 
 export type Graph = {
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 02d49ec..c9e55a6 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -10,19 +10,19 @@ import {type Graph, type GraphCommand, type GraphNode} from './graph';
 //   - Each wrapper-State collapses onto its bare's representation. The collapsed
 //     graph node has `isWrapped: true` and is emitted as Mermaid `[[…]]`
 //     (subroutine / double-walled-rectangle) shape, inside a `subgraph
-//     w_${id}["halt frame"] … end` block. A synthesized "cloned halt" graph
-//     node (with `isHalt: true, isClonedHalt: true`, id = -wrapperId in graph
+//     w_${id}["halt frame"] … end` block. A synthesized "halt marker" graph
+//     node (with `isHalt: true, isHaltMarker: true`, id = -wrapperId in graph
 //     data) sits inside the subgraph and serves as the local landing point for
 //     the bare's halt-bound transitions. The dotted onHalt edge runs from the
 //     `[[bare]]` directly to the override target, crossing the subgraph border.
 //   - Real halt (id 0) is emitted as `s0(((halt)))` outside any subgraph.
-//   - Cloned halt nodes use the Mermaid id `c${absId}` (where `absId = -id`)
+//   - Halt marker nodes use the Mermaid id `c${absId}` (where `absId = -id`)
 //     since Mermaid IDs must match /[A-Za-z][A-Za-z0-9_]*/ — negative numbers
 //     are not legal syntax.
 
 // Maps a graph node id to its Mermaid id.
 //   - non-negative id N  → "sN"
-//   - negative id -N (cloned halt) → "cN"
+//   - negative id -N (halt marker) → "cN"
 function mermaidIdFor(id: number): string {
   return id < 0 ? `c${-id}` : `s${id}`;
 }
@@ -43,15 +43,15 @@ export function toMermaid(graph: Graph): string {
   ];
 
   // Sort nodes by id (ascending — real halt first at 0, regular states next,
-  // negative-id cloned halts last). Deterministic emit lets `toMermaid` →
+  // negative-id halt markers last). Deterministic emit lets `toMermaid` →
   // `fromMermaid` → `toMermaid` round-trip stably (regression for #139).
   const nodes = Object.values(graph.nodes).slice().sort((a, b) => a.id - b.id);
   const wrappedNodes = nodes.filter((n) => n.isWrapped);
 
-  // Convention: wrapped node id N → cloned halt id -N.
+  // Convention: wrapped node id N → halt marker id -N.
   const clonedHaltFor = (wrappedId: number): number => -wrappedId;
 
-  // Set of cloned-halt ids that belong to some wrapper (= are inside a subgraph).
+  // Set of halt-marker ids that belong to some wrapper (= are inside a subgraph).
   const clonedHaltIds = new Set<number>();
 
   for (const w of wrappedNodes) {
@@ -109,13 +109,32 @@ export function toMermaid(graph: Graph): string {
   // transitions emit in their stored array order (which mirrors the source
   // state's symbol-map insertion order — stable per State instance).
   for (const node of nodes) {
-    if (node.isHalt && !node.isClonedHalt) {
+    if (node.isHalt && !node.isHaltMarker) {
       continue;
     }
 
     for (const t of node.transitions) {
-      const cmd = t.command.map((c) => `${c.symbol}/${c.movement}`).join(',');
-      const label = `${t.pattern} → ${cmd}`;
+      // Bracketed-tape-block format (v7): each role-list — read alternatives,
+      // writes, movements — wraps in `[…]` to mark "this is a tape-block
+      // reading". Brackets stay even for single-tape machines; the `[…]` is
+      // the tape-block concept indicator.
+      //
+      //   Single-tape:                  ['X'] → [K]/[R]
+      //   Single-tape + alternation:    ['^']|['1']|['0'] → [K]/[S]
+      //   Two-tape:                     ['0','a'] → [K,'1']/[R,S]
+      //   Two-tape + alternation:       ['0','a']|['1','b'] → [K,K]/[R,L]
+      //
+      // Alternation is ALWAYS per-pattern-bracket — one full bracketed list
+      // per alternative — regardless of tape count. Pedagogically each
+      // alternative is its own drawn transition; a compact in-bracket form
+      // (`['^'|'1']`) would read as cross-product semantics in multi-tape
+      // (`['0'|'1','a'|'b']` = 4 combos, not 2 paired alternatives), so we
+      // avoid introducing it for the single-tape case too.
+      const alternatives = t.pattern.split('|');
+      const reads = alternatives.map((alt) => `[${alt}]`).join('|');
+      const writes = `[${t.command.map((c) => c.symbol).join(',')}]`;
+      const moves = `[${t.command.map((c) => c.movement).join(',')}]`;
+      const label = `${reads} → ${writes}/${moves}`;
 
       // Thicker `==>` arrow when the transition crosses INTO a wrapper —
       // signals "this transition pushes that wrapper's override onto the
@@ -174,8 +193,8 @@ export function fromMermaid(text: string): Graph {
   let alphabets: string[][] = [];
   let initialId: number | null = null;
   const nodes: Record<number, GraphNode> = {};
-  // Track the cloned-halt ids that appeared inside a subgraph — they should be
-  // marked `isClonedHalt: true` even though they share the `(((halt)))` shape
+  // Track the halt-marker ids that appeared inside a subgraph — they should be
+  // marked `isHaltMarker: true` even though they share the `(((halt)))` shape
   // with the real halt at the top level.
   const clonedHaltIds = new Set<number>();
   let inSubgraph = false;
@@ -185,7 +204,7 @@ export function fromMermaid(text: string): Graph {
     opts: {
       name?: string;
       isHalt?: boolean;
-      isClonedHalt?: boolean;
+      isHaltMarker?: boolean;
       isWrapped?: boolean;
     } = {},
   ): GraphNode => {
@@ -194,7 +213,7 @@ export function fromMermaid(text: string): Graph {
         id,
         name: opts.name ?? mermaidIdFor(id),
         isHalt: opts.isHalt ?? false,
-        isClonedHalt: opts.isClonedHalt ?? false,
+        isHaltMarker: opts.isHaltMarker ?? false,
         isWrapped: opts.isWrapped ?? false,
         transitions: [],
         overriddenHaltStateId: null,
@@ -202,14 +221,14 @@ export function fromMermaid(text: string): Graph {
     } else {
       if (opts.name !== undefined) nodes[id].name = opts.name;
       if (opts.isHalt !== undefined) nodes[id].isHalt = opts.isHalt;
-      if (opts.isClonedHalt !== undefined) nodes[id].isClonedHalt = opts.isClonedHalt;
+      if (opts.isHaltMarker !== undefined) nodes[id].isHaltMarker = opts.isHaltMarker;
       if (opts.isWrapped !== undefined) nodes[id].isWrapped = opts.isWrapped;
     }
 
     return nodes[id];
   };
 
-  // First pass: alphabets + nodes (track subgraph context to mark cloned halts).
+  // First pass: alphabets + nodes (track subgraph context to mark halt markers).
   for (const line of lines) {
     if (line === 'flowchart TD') {
       continue;
@@ -245,7 +264,7 @@ export function fromMermaid(text: string): Graph {
       const id = parseMermaidId(hm[1]);
       const isCloned = inSubgraph || id < 0;
 
-      ensureNode(id, {name: 'halt', isHalt: true, isClonedHalt: isCloned});
+      ensureNode(id, {name: 'halt', isHalt: true, isHaltMarker: isCloned});
 
       if (isCloned) {
         clonedHaltIds.add(id);
@@ -301,20 +320,85 @@ export function fromMermaid(text: string): Graph {
         throw new Error(`fromMermaid: malformed edge label: "${label}"`);
       }
 
-      const pattern = label.slice(0, arrowIx);
-      const commandStr = label.slice(arrowIx + ' → '.length);
-      const command: GraphCommand[] = commandStr.split(',').map((part) => {
-        const slashIx = part.lastIndexOf('/');
+      // Bracketed-tape-block format (v7):
+      //   [<read-cells>]|[<read-cells>]... → [<write-cells>]/[<move-cells>]
+      // Each bracketed list is a tape-block reading; the outer `|` separates
+      // alternative read patterns. For single-tape machines with alternation,
+      // the compact form `[<alt1>|<alt2>|...]` (one bracket, alternatives
+      // inside) is also accepted; both forms decode to the same pattern
+      // string.
+      const readLabel = label.slice(0, arrowIx);
+      const cmdLabel = label.slice(arrowIx + ' → '.length);
+
+      // Strict per-pattern bracket form: `|` only between bracketed lists,
+      // never inside. The compact `['^'|'1']` form is rejected by design —
+      // every alternative must be its own bracketed pattern (`['^']|['1']`).
+      // Pedagogically: each transition is drawn explicitly; the compact form
+      // would read as cross-product semantics in multi-tape and confuse
+      // readers (`['0'|'1','a'|'b']` could mean 4 combos, not 2 paired alts).
+      // The rule applies to all bracketed lists — read alternatives, writes,
+      // and movements — because commands and movements have no alternation
+      // semantic either.
+      const stripBrackets = (s: string): string => {
+        if (!s.startsWith('[') || !s.endsWith(']')) {
+          throw new Error(`fromMermaid: malformed bracketed list: "${s}"`);
+        }
+
+        const inner = s.slice(1, -1);
+
+        // Walk the inner content; backslash escapes the next char (so `\|`
+        // inside a cell is a literal pipe, not the alternation separator).
+        let i = 0;
+
+        while (i < inner.length) {
+          if (inner[i] === '\\' && i + 1 < inner.length) {
+            i += 2;
+            continue;
+          }
+
+          if (inner[i] === '|') {
+            throw new Error(
+              `fromMermaid: compact in-bracket alternation "${s}" is not supported — `
+              + 'each alternative must be its own bracketed pattern (e.g. "[\'^\']|[\'1\']").',
+            );
+          }
 
-        if (slashIx === -1) {
-          throw new Error(`fromMermaid: malformed command part: "${part}"`);
+          i += 1;
         }
 
-        return {
-          symbol: part.slice(0, slashIx),
-          movement: part.slice(slashIx + 1),
-        };
-      });
+        return inner;
+      };
+
+      // Match `[…]` blocks in the read label. Inner content is a tape-block
+      // reading (possibly with `|` for compact single-tape alternation).
+      // `[^\]]*` is the simple non-greedy match — works because cell content
+      // doesn't typically contain literal `]`.
+      const blockMatches = readLabel.match(/\[[^\]]*\]/g);
+
+      if (!blockMatches || blockMatches.length === 0) {
+        throw new Error(`fromMermaid: no bracketed read-list in label: "${label}"`);
+      }
+
+      const pattern = blockMatches.map(stripBrackets).join('|');
+
+      const slashIx = cmdLabel.indexOf(']/[');
+
+      if (slashIx === -1) {
+        throw new Error(`fromMermaid: malformed command label (expected \`[…]/[…]\`): "${cmdLabel}"`);
+      }
+
+      const writesPart = stripBrackets(cmdLabel.slice(0, slashIx + 1));
+      const movesPart = stripBrackets(cmdLabel.slice(slashIx + 2));
+      const writes = writesPart.split(',');
+      const moves = movesPart.split(',');
+
+      if (writes.length !== moves.length) {
+        throw new Error(
+          `fromMermaid: write-cells (${writes.length}) and move-cells (${moves.length}) mismatch: "${cmdLabel}"`,
+        );
+      }
+
+      const command: GraphCommand[] = writes.map((symbol, i) => ({symbol, movement: moves[i]}));
 
       const fromNode = ensureNode(fromId);
       const transitionIx = fromNode.transitions.length;
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 17347db..edb858d 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -7,9 +7,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
             {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
@@ -31,9 +31,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
           ],
@@ -52,9 +52,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
           transitions: [{pattern: '0', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
         },
       },
@@ -72,10 +72,10 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isClonedHalt: false},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isWrapped: false, isClonedHalt: false},
-        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isWrapped: false, isHaltMarker: false},
+        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
       },
     };
 
@@ -90,8 +90,8 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isClonedHalt: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
       },
     };
 
@@ -197,8 +197,8 @@ describe('summarizeGraph defensive guards', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isClonedHalt: false},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isWrapped: false, isClonedHalt: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false},
       },
     };
 
diff --git a/packages/machine/src/utilities/introspection.ts b/packages/machine/src/utilities/introspection.ts
index 8c82059..034e11b 100644
--- a/packages/machine/src/utilities/introspection.ts
+++ b/packages/machine/src/utilities/introspection.ts
@@ -40,11 +40,11 @@ export type GraphSummary = {
 export function summarizeGraph(graph: Graph): GraphSummary {
   const nodes = Object.values(graph.nodes);
 
-  // `isClonedHalt` nodes are visualization sentinels — one per wrapper context,
+  // `isHaltMarker` nodes are visualization sentinels — one per wrapper context,
   // all corresponding to the singleton `haltState` at runtime. They don't
   // count as distinct runtime states; matches the per-algorithm header in
   // `library-binary-numbers/states.md`.
-  const runtimeStateCount = nodes.filter((n) => !n.isClonedHalt).length;
+  const runtimeStateCount = nodes.filter((n) => !n.isHaltMarker).length;
 
   let transitionCount = 0;
   let compositionEdgeCount = 0;
diff --git a/scripts/build-states-md.mjs b/scripts/build-states-md.mjs
index 3a1ce2d..fc77022 100644
--- a/scripts/build-states-md.mjs
+++ b/scripts/build-states-md.mjs
@@ -67,7 +67,7 @@ if (libName === null) {
     const graph = State.toGraph(state, tapeBlock);
     const mermaid = toMermaid(graph);
     // Engine-owned introspection — dogfoods the same summary the public API
-    // exposes. `stateCount` already filters out `isClonedHalt` sentinels.
+    // exposes. `stateCount` already filters out `isHaltMarker` sentinels.
     const summary = summarizeGraph(graph);
 
     sections.push(`## ${stateName}`);
diff --git a/test/round-trip.spec.ts b/test/round-trip.spec.ts
index a5a5935..4e6070b 100644
--- a/test/round-trip.spec.ts
+++ b/test/round-trip.spec.ts
@@ -129,7 +129,7 @@ describe('toGraph / toMermaid / fromMermaid / fromGraph round trip', () => {
     const reEmittedMermaid = toMermaid(State.toGraph(rebuilt, rebuiltTapeBlock));
 
     // State IDs auto-reassign on each rebuild, so normalize them before
-    // comparing. v7's emit also uses `cN` for cloned-halt ids and `w_N` for
+    // comparing. v7's emit also uses `cN` for halt-marker ids and `w_N` for
     // subgraph names — normalize all three.
     const normalize = (mermaid: string): string => mermaid
       .replace(/\bs\d+\b/g, 'sX')

From 14448abc3714f91d6e131704e0c7b771eb1e3496 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 00:08:40 +0300
Subject: [PATCH 011/118] =?UTF-8?q?polish(emit):=20ASCII=20`*`=20for=20ifO?=
 =?UTF-8?q?therSymbol;=20`clonedHalt*`=20=E2=86=92=20`haltMarker*`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

U+1F7B0 didn't render in GitHub Mermaid (tofu) or most monospace
fonts. Switched to ASCII `*` — a literal `*` in the alphabet stays
unambiguous because it's quoted (`'*'`), parallel to literal `'B'`
vs the `B` blank-marker.

Also renamed internal `clonedHalt*` identifiers to `haltMarker*` for
consistency with the public `GraphNode.isHaltMarker` flag and the docs
terminology — both `State.toGraph` and `toMermaid`/`fromMermaid` now
match. Prose mentions of "cloned halt" in the README and design spec
updated in lockstep.

Regenerated `library-binary-numbers/states.md` (27 sites).
---
 CLAUDE.md                                     |  2 +-
 README.md                                     |  4 +-
 ...026-05-20-tomermaid-wrapper-emit-design.md |  4 +-
 packages/library-binary-numbers/states.md     | 54 +++++++++----------
 packages/machine/README.md                    | 28 +++++-----
 packages/machine/src/classes/State.spec.ts    |  2 +-
 packages/machine/src/classes/State.ts         | 14 ++---
 packages/machine/src/utilities/graph.spec.ts  | 20 +++----
 packages/machine/src/utilities/graph.ts       | 15 +++---
 .../machine/src/utilities/graphFormats.ts     | 30 +++++------
 10 files changed, 87 insertions(+), 86 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index d6c4825..e9ffd12 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -63,7 +63,7 @@ Key shapes that take reading multiple files to grasp:
 
 **v7 emit shape** (PR #169, closes #138/#139): each `withOverriddenHaltState` wrapper collapses onto its bare's representation — `GraphNode.isWrapped: true`, no separate wrapper node in graph data. `toMermaid` wraps each `[[bare]]` (subroutine shape) + a synthesized `(((halt)))` marker (`GraphNode.isHaltMarker: true`, negative id; maps back to singleton `haltState` in `fromGraph`) inside a `subgraph w_${bareId}["halt frame"] … end` block. Dotted `onHalt` from `[[bare]]` crosses the subgraph border to the override target. An always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state (replaces v6's `((round))` shape convention).
 
-**Edge label vocabulary** — `[reads] → [writes]/[moves]`, each role wrapped in `[…]` (the tape-block indicator, one entry per tape; brackets always present, even single-tape). Read cells: literal-quoted (`'X'`), `🞰` (U+1F7B0, ifOtherSymbol catch-all), `B` (the tape's blank). Write cells: literal-quoted, `K` (keep), `E` (erase = write blank). Move cells: `L` / `R` / `S`. **Alternation is always per-pattern bracket** (`['^']|['1']|['0']` for single-tape, `['0','a']|['1','b']` for multi-tape); the compact in-bracket form `['^'|'1']` is rejected by `fromMermaid` to prevent the cross-product reading trap in multi-tape (`['0'|'1','a'|'b']` would read as 4 combinations rather than 2 paired alternatives, so the format avoids the shape entirely).
+**Edge label vocabulary** — `[reads] → [writes]/[moves]`, each role wrapped in `[…]` (the tape-block indicator, one entry per tape; brackets always present, even single-tape). Read cells: literal-quoted (`'X'`), `*` (ASCII, ifOtherSymbol catch-all; literal `*` in the alphabet is quoted as `'*'`), `B` (the tape's blank). Write cells: literal-quoted, `K` (keep), `E` (erase = write blank). Move cells: `L` / `R` / `S`. **Alternation is always per-pattern bracket** (`['^']|['1']|['0']` for single-tape, `['0','a']|['1','b']` for multi-tape); the compact in-bracket form `['^'|'1']` is rejected by `fromMermaid` to prevent the cross-product reading trap in multi-tape (`['0'|'1','a'|'b']` would read as 4 combinations rather than 2 paired alternatives, so the format avoids the shape entirely).
 
 **Edge arrow styles** — thick `==>` marks transitions whose target is a wrapped state AND ≠ source (= stack-push happens at runtime per `TuringMachine.run` line ~220); regular `-->` for the rest (including self-loops on wrappers, which don't push); dotted `-. onHalt .->` for the wrapper's catch-and-redirect; dotted `-. enter .->` from `idle` for execution-start.
 
diff --git a/README.md b/README.md
index 118810b..1ed7fe7 100644
--- a/README.md
+++ b/README.md
@@ -85,13 +85,13 @@ flowchart TD
   idle -. enter .-> s1
   s1 -- "['b'] → ['*']/[R]" --> s1
   s1 -- "[B] → [K]/[L]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
 ```
 
 Quick legend for the diagram above — full table at [packages/machine/README.md § Diagram conventions](packages/machine/README.md#diagram-conventions):
 
 - **Edge format**: `[reads] → [writes]/[moves]` (each `[…]` is a tape-block reading; brackets always, even single-tape).
-- **Read cells**: `'X'` (literal, single-quoted), `🞰` (`ifOtherSymbol` catch-all, U+1F7B0), `B` (the tape's blank).
+- **Read cells**: `'X'` (literal, single-quoted), `*` (`ifOtherSymbol` catch-all), `B` (the tape's blank).
 - **Write cells**: `'X'` (literal), `K` (keep), `E` (erase = write blank).
 - **Movement cells**: `L` / `R` / `S` (left / right / stay).
 - **Node shapes**: `(((halt)))` = halt, `["square"]` = regular state, `[[double-walled]]` = wrapper-bare (subroutine shape), `idle([idle])` = pre-execution sentinel.
diff --git a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
index 776d8b7..ab661e7 100644
--- a/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
+++ b/docs/superpowers/specs/2026-05-20-tomermaid-wrapper-emit-design.md
@@ -1,6 +1,6 @@
 # `toMermaid` wrapped-state emit — design comparison
 
-**Status:** decided — **Variant X with `subgraph` overlay + `idle` entry sentinel + bracketed-tape-block edge labels**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a cloned `(((halt)))`. The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. A stadium-shaped `idle([idle])` sentinel + labeled dotted arrow `idle -. enter .-> sN` is always emitted to mark the initial state. Edge labels: `[reads] → [writes]/[moves]` with each role wrapped in `[…]` (tape-block indicator, always present even single-tape); read cells use `'X'` literal-quoted, `🞰` (U+1F7B0) for ifOtherSymbol, `B` for the tape's blank; write cells use `K`/`E` plus literal-quoted; movements `L`/`R`/`S`. Alternation is per-pattern-bracket (`['^']|['1']`); compact `['^'|'1']` form is rejected by `fromMermaid` (would read as cross-product in multi-tape). Stack-pushing transitions emit thick `==>` arrows. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation in PR [#169](https://github.com/mellonis/turing-machine-js/pull/169).
+**Status:** decided — **Variant X with `subgraph` overlay + `idle` entry sentinel + bracketed-tape-block edge labels**. See [Final locked design](#final-locked-design-variant-x-with-subgraph-overlay) at the bottom for the exact diagrams and reader's contract. Each wrapper gets a `subgraph` rectangle labeled `"halt frame"` containing the `[[bare]]` (double-walled wrapper-node) and a halt-marker `(((halt)))`. The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target. A stadium-shaped `idle([idle])` sentinel + labeled dotted arrow `idle -. enter .-> sN` is always emitted to mark the initial state. Edge labels: `[reads] → [writes]/[moves]` with each role wrapped in `[…]` (tape-block indicator, always present even single-tape); read cells use `'X'` literal-quoted, `*` (ASCII) for ifOtherSymbol, `B` for the tape's blank; write cells use `K`/`E` plus literal-quoted; movements `L`/`R`/`S`. Alternation is per-pattern-bracket (`['^']|['1']`); compact `['^'|'1']` form is rejected by `fromMermaid` (would read as cross-product in multi-tape). Stack-pushing transitions emit thick `==>` arrows. Decision rationale posted on [#138](https://github.com/mellonis/turing-machine-js/issues/138#issuecomment-4499377933). Implementation in PR [#169](https://github.com/mellonis/turing-machine-js/pull/169).
 
 **Context.** [#138](https://github.com/mellonis/turing-machine-js/issues/138) — clean up the visually-confusing Mermaid output for `withOverriddenHaltState`-wrapped states. [#139](https://github.com/mellonis/turing-machine-js/issues/139) — bytewise round-trip regression for the wrapper name accumulation, naturally fixed by whichever design we pick.
 
@@ -259,7 +259,7 @@ Y₁ is the most faithful but the cost of per-context state duplication in `from
 After iteration, the locked shape evolves Variant X (collapse the wrapper into the bare's representation, no extra "wrapper node" in the graph data) with two visualization-only enhancements that make the wrapper's runtime semantics tangible without mutating the graph structure:
 
 1. A Mermaid **`subgraph` rectangle labeled `"halt frame"`** around each wrapper — the visual scope for "the wrapper's stack frame for halt handling."
-2. A **cloned `(((halt)))` node inside that subgraph** — visualization of "halt-bound transitions land here, *inside* the wrapper's scope." `haltState` is a runtime singleton; the cloned visual is a teaching aid (one halt marker per wrapper context on the diagram, all corresponding to the single runtime instance).
+2. A **halt-marker `(((halt)))` node inside that subgraph** — visualization of "halt-bound transitions land here, *inside* the wrapper's scope." `haltState` is a runtime singleton; the halt marker is a teaching aid (one per wrapper context on the diagram, all corresponding to the single runtime instance).
 
 ### Visual contract (what a reader sees)
 
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 1c38dfc..31477a0 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -12,7 +12,7 @@ flowchart TD
   idle([idle])
   idle -. enter .-> s1
   s1 -- "['$'] → [K]/[S]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
 ```
 
 ## goToNextNumber
@@ -28,8 +28,8 @@ flowchart TD
   idle([idle])
   idle -. enter .-> s2
   s1 -- "['$'] → [K]/[S]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
-  s2 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
+  s2 -- "[*] → [K]/[R]" --> s1
 ```
 
 ## goToPreviousNumber
@@ -45,8 +45,8 @@ flowchart TD
   idle([idle])
   idle -. enter .-> s4
   s3 -- "['$'] → [K]/[S]" --> s0
-  s3 -- "[🞰] → [K]/[L]" --> s3
-  s4 -- "[🞰] → [K]/[L]" --> s3
+  s3 -- "[*] → [K]/[L]" --> s3
+  s4 -- "[*] → [K]/[L]" --> s3
 ```
 
 ## deleteNumber
@@ -66,12 +66,12 @@ flowchart TD
   end
   idle -. enter .-> s8
   s6 -- "['$'] → [E]/[S]" --> s0
-  s6 -- "[🞰] → [E]/[R]" --> s6
+  s6 -- "[*] → [E]/[R]" --> s6
   s7 -- "['^'] → [K]/[S]" --> c7
-  s7 -- "[🞰] → [K]/[L]" --> s7
+  s7 -- "[*] → [K]/[L]" --> s7
   s7 -. onHalt .-> s6
   s8 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s7
-  s8 -- "[🞰] → [K]/[S]" --> s0
+  s8 -- "[*] → [K]/[S]" --> s0
 ```
 
 ## goToNumbersStart
@@ -86,7 +86,7 @@ flowchart TD
   idle([idle])
   idle -. enter .-> s5
   s5 -- "['^'] → [K]/[S]" --> s0
-  s5 -- "[🞰] → [K]/[L]" --> s5
+  s5 -- "[*] → [K]/[L]" --> s5
 ```
 
 ## invertNumber
@@ -110,10 +110,10 @@ flowchart TD
   s9 -- "['0'] → ['1']/[R]" --> s9
   s9 -- "['$'] → [K]/[S]" --> s0
   s10 -- "['^'] → [K]/[S]" --> c10
-  s10 -- "[🞰] → [K]/[L]" --> s10
+  s10 -- "[*] → [K]/[L]" --> s10
   s10 -. onHalt .-> s9
   s11 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
-  s11 -- "[🞰] → [K]/[S]" --> s0
+  s11 -- "[*] → [K]/[S]" --> s0
 ```
 
 ## normalizeNumber
@@ -135,15 +135,15 @@ flowchart TD
   end
   idle -. enter .-> s15
   s1 -- "['$'] → [K]/[S]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
   s12 -- "[B] → ['^']/[S]" --> s1
   s13 -- "['^']|['0'] → [E]/[R]" --> s13
   s13 -- "['1']|['$'] → [K]/[L]" --> s12
   s14 -- "['^'] → [K]/[S]" --> c14
-  s14 -- "[🞰] → [K]/[L]" --> s14
+  s14 -- "[*] → [K]/[L]" --> s14
   s14 -. onHalt .-> s13
   s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
-  s15 -- "[🞰] → [K]/[S]" --> s0
+  s15 -- "[*] → [K]/[S]" --> s0
 ```
 
 ## plusOne
@@ -169,7 +169,7 @@ flowchart TD
   s18 -- "['^'] → ['1']/[L]" --> s17
   s19 -- "['^']|['1']|['0'] → [K]/[R]" --> s19
   s19 -- "['$'] → [K]/[L]" --> s18
-  s19 -- "[🞰] → [K]/[S]" --> s0
+  s19 -- "[*] → [K]/[S]" --> s0
 ```
 
 ## minusOne
@@ -212,22 +212,22 @@ flowchart TD
   end
   idle -. enter .-> s23
   s1 -- "['$'] → [K]/[S]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
   s9 -- "['^'] → [K]/[R]" --> s9
   s9 -- "['1'] → ['0']/[R]" --> s9
   s9 -- "['0'] → ['1']/[R]" --> s9
   s9 -- "['$'] → [K]/[S]" --> s0
   s10 -- "['^'] → [K]/[S]" --> c10
-  s10 -- "[🞰] → [K]/[L]" --> s10
+  s10 -- "[*] → [K]/[L]" --> s10
   s10 -. onHalt .-> s9
   s12 -- "[B] → ['^']/[S]" --> s1
   s13 -- "['^']|['0'] → [E]/[R]" --> s13
   s13 -- "['1']|['$'] → [K]/[L]" --> s12
   s14 -- "['^'] → [K]/[S]" --> c14
-  s14 -- "[🞰] → [K]/[L]" --> s14
+  s14 -- "[*] → [K]/[L]" --> s14
   s14 -. onHalt .-> s13
   s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
-  s15 -- "[🞰] → [K]/[S]" --> s0
+  s15 -- "[*] → [K]/[S]" --> s0
   s16 -- "['1'] → ['0']/[R]" --> s16
   s16 -- "['$'] → [K]/[S]" --> s0
   s17 -- "[B] → ['^']/[R]" --> s17
@@ -236,18 +236,18 @@ flowchart TD
   s18 -- "['1'] → [K]/[L]" --> s18
   s18 -- "['^'] → ['1']/[L]" --> s17
   s20 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
-  s20 -- "[🞰] → [K]/[S]" --> c20
+  s20 -- "[*] → [K]/[S]" --> c20
   s20 -. onHalt .-> s15
   s21 -- "['^']|['1']|['0'] → [K]/[R]" --> s21
   s21 -- "['$'] → [K]/[L]" --> s18
-  s21 -- "[🞰] → [K]/[S]" --> c21
+  s21 -- "[*] → [K]/[S]" --> c21
   s21 -. onHalt .-> s20
   s22 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
-  s22 -- "[🞰] → [K]/[S]" --> c22
+  s22 -- "[*] → [K]/[S]" --> c22
   s22 -. onHalt .-> s21
   s23 -- "['^']|['1']|['0'] → [K]/[R]" --> s23
   s23 == "['$'] → [K]/[S]" ==> s22
-  s23 -- "[🞰] → [K]/[S]" --> s0
+  s23 -- "[*] → [K]/[S]" --> s0
 ```
 
 ## minusOneFast
@@ -274,20 +274,20 @@ flowchart TD
   end
   idle -. enter .-> s26
   s1 -- "['$'] → [K]/[S]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
   s12 -- "[B] → ['^']/[S]" --> s1
   s13 -- "['^']|['0'] → [E]/[R]" --> s13
   s13 -- "['1']|['$'] → [K]/[L]" --> s12
   s14 -- "['^'] → [K]/[S]" --> c14
-  s14 -- "[🞰] → [K]/[L]" --> s14
+  s14 -- "[*] → [K]/[L]" --> s14
   s14 -. onHalt .-> s13
   s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
-  s15 -- "[🞰] → [K]/[S]" --> s0
+  s15 -- "[*] → [K]/[S]" --> s0
   s25 -- "['1'] → ['0']/[S]" --> c25
   s25 -- "['0'] → ['1']/[L]" --> s25
   s25 -- "['^'] → [K]/[S]" --> c25
   s25 -. onHalt .-> s15
   s26 -- "['^']|['1']|['0'] → [K]/[R]" --> s26
   s26 == "['$'] → [K]/[L]" ==> s25
-  s26 -- "[🞰] → [K]/[S]" --> s0
+  s26 -- "[*] → [K]/[S]" --> s0
 ```
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 9880a61..ad90f3c 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -82,10 +82,10 @@ flowchart TD
   idle -. enter .-> s1
   s1 -- "['b'] → ['*']/[R]" --> s1
   s1 -- "[B] → [K]/[L]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
 ```
 
-Reading this specific diagram: `replaceB` (the rectangle) is the start state, marked by the dotted `enter` arrow from the `idle` sentinel. Three self-or-halt transitions: read `'b'` → write `'*'` and step right; read anything else (`🞰`) → keep, step right; read blank (`B`) → keep, step left, halt. Full notation reference — shapes, edge styles, label vocabulary — in [§Diagram conventions](#diagram-conventions).
+Reading this specific diagram: `replaceB` (the rectangle) is the start state, marked by the dotted `enter` arrow from the `idle` sentinel. Three self-or-halt transitions: read `'b'` → write `'*'` and step right; read anything else (`*`) → keep, step right; read blank (`B`) → keep, step left, halt. Full notation reference — shapes, edge styles, label vocabulary — in [§Diagram conventions](#diagram-conventions).
 
 A `State` is keyed by JS `Symbol`s returned from `tapeBlock.symbol(pattern)` — the pattern lists the expected symbol under each tape's head. Sentinels and constants used throughout: [`ifOtherSymbol`](#ifothersymbol) is the fallback key when nothing else matches; transitioning into [`haltState`](#haltstate) stops the run; [`movements`](#movements)`.{left,right,stay}` direct head moves; [`symbolCommands`](#symbolcommands)`.{keep,erase}` are write shortcuts. Full definitions in [§Special objects](#special-objects).
 
@@ -388,7 +388,7 @@ flowchart TD
   idle([idle])
   idle -. enter .-> s1
   s1 -- "['X'] → [K]/[S]" --> s0
-  s1 -- "[🞰] → [K]/[R]" --> s1
+  s1 -- "[*] → [K]/[R]" --> s1
 ```
 
 `toMermaid(toGraph(scanThenErase, tapeBlock))` — the wrapped composition:
@@ -404,9 +404,9 @@ flowchart TD
     c3(((halt)))
   end
   idle -. enter .-> s3
-  s2 -- "[🞰] → [E]/[S]" --> s0
+  s2 -- "[*] → [E]/[S]" --> s0
   s3 -- "['X'] → [K]/[S]" --> c3
-  s3 -- "[🞰] → [K]/[R]" --> s3
+  s3 -- "[*] → [K]/[R]" --> s3
   s3 -. onHalt .-> s2
 ```
 
@@ -414,11 +414,11 @@ flowchart TD
 
 1. **The subgraph rectangle labeled `"halt frame"`** is the wrapper's runtime scope — while execution is "inside" this rectangle, the override target (`eraseHere`) sits on the runtime stack waiting to catch a halt. Visual-only; it does not mutate any edges.
 2. **`[[scanToX]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node. It's both the runtime entry point (execution starts here when entering the wrapper) AND the source of the dotted `onHalt` redirect. The wrapper's composite name (`scanToX(eraseHere)`) is computed at runtime via `state.name` but does not appear as a graph node label — only the bare's name is in the graph.
-3. **The cloned `(((halt)))` inside the subgraph** (`c3` here) is where the bare's halt-bound transitions land *inside* the wrapper's scope. `haltState` is a runtime singleton; the cloned node is a teaching aid showing "halt is caught here, not at the real terminus." Solid arrows from the bare to the halt marker all stay inside the rectangle.
+3. **The halt-marker `(((halt)))` inside the subgraph** (`c3` here) is where the bare's halt-bound transitions land *inside* the wrapper's scope. `haltState` is a runtime singleton; the halt marker is a teaching aid showing "halt is caught here, not at the real terminus." Solid arrows from the bare to the halt marker all stay inside the rectangle.
 4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. Originates from the wrapper-node since the wrapper *is* the catcher. Solid arrows from `[[scanToX]]` to other states can also cross the subgraph border — those are just regular runtime transitions whose target happens to be drawn outside this rectangle (only the dotted `onHalt` carries wrapper-machinery meaning). In larger compositions (`library-binary-numbers`'s `minusOne`), solid transitions whose target is *itself* a wrapped state render as a **thick `==>` arrow** instead of `-->` — that's the visual signal for "this transition enters a halt frame, pushing the override onto the runtime stack." Stack-growth structure is then scannable from the diagram: count thick arrows along an execution path to see how deep the stack gets.
 5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame — here, by `eraseHere` after it erases the cell.
 
-**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `[🞰] → [K]/[R]` self-loops until the head sees `X`; the `['X'] → [K]/[S]` solid edge would normally halt — it lands on the halt marker `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `[🞰] → [E]/[S]` and halts at real `s0`. Run terminates.
+**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `[*] → [K]/[R]` self-loops until the head sees `X`; the `['X'] → [K]/[S]` solid edge would normally halt — it lands on the halt marker `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `[*] → [E]/[S]` and halts at real `s0`. Run terminates.
 
 > 💡 **Round-trip caveat.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers like this one ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). For shared-bare cases (same `State` instance used as the bare in multiple wrappers — e.g., `library-binary-numbers`'s `minusOne`), per-context duplication produces wrapper-id-dependent ordering that doesn't byte-match across rebuilds — equivalent runtime behavior, different emit-line order.
 
@@ -600,7 +600,7 @@ The full reference for reading `toMermaid` output — shapes, edge styles, and t
 | Glyph | Where | Meaning |
 |---|---|---|
 | `'X'` | read, write | literal alphabet symbol (single-quoted) |
-| `🞰` | read only | `ifOtherSymbol` catch-all (U+1F7B0 heavy-eight-balloon-spoked-asterisk) |
+| `*` | read only | `ifOtherSymbol` catch-all (ASCII `*`; a literal `*` in the alphabet renders as the quoted `'*'`, so the marker stays unambiguous) |
 | `B` | read only | the tape's blank symbol (a literal `B` in the alphabet appears as `'B'`, so the marker stays unambiguous) |
 | `K` | write only | keep (no write) |
 | `E` | write only | erase (write the tape's blank) |
@@ -626,14 +626,14 @@ flowchart TD
   s1["copy"]
   idle([idle])
   idle -. enter .-> s1
-  s1 -- "['0',🞰] → [K,'0']/[R,R]" --> s1
-  s1 -- "['1',🞰] → [K,'1']/[R,R]" --> s1
-  s1 -- "[B,🞰] → [K]/[S]" --> s0
+  s1 -- "['0',*] → [K,'0']/[R,R]" --> s1
+  s1 -- "['1',*] → [K,'1']/[R,R]" --> s1
+  s1 -- "[B,*] → [K]/[S]" --> s0
 ```
 
-Reading `['0',🞰] → [K,'0']/[R,R]`:
+Reading `['0',*] → [K,'0']/[R,R]`:
 
-- **Read** `['0',🞰]` — tape 1 must be literal `'0'`; tape 2 is `ifOtherSymbol` (any).
+- **Read** `['0',*]` — tape 1 must be literal `'0'`; tape 2 is `ifOtherSymbol` (any).
 - **Write** `[K,'0']` — tape 1: keep; tape 2: write literal `'0'`.
 - **Move** `[R,R]` — both tapes step right.
 
@@ -651,7 +651,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **v7** *(in progress)* — Composition-representation overhaul. Breaking renames + reshapes scheduled for the v7 cut. Landing piecewise on the `v7` branch; one entry per landed change:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
   - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
-  - **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139)). The wrapper-and-its-bare pair collapses into a single graph node (`isWrapped: true`); the wrapper's composite name no longer appears as a node label (only the bare's name does). Each wrapper gets a Mermaid `subgraph w_${bareId}["halt frame"] … end` block containing the `[[bare]]` (subroutine shape) plus a cloned `(((halt)))` (visualization aid showing where halt-bound transitions land inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target — exactly one per wrapper. `Graph` data shape gains `isWrapped` and `isHaltMarker` flags on `GraphNode` and a stable `id` on `GraphTransition` (deterministic per-edge identifier — supports downstream tooling like the `machines-demo` interactive viewer at [machines-demo#10](https://github.com/mellonis/machines-demo/issues/10)). Halt-marker graph nodes use negative ids and round-trip back to the singleton `haltState` via `fromGraph`. Bytewise round-trip stability falls out for simple wrappers (no composite name in the graph means `fromGraph(toGraph(state))` recomputes names fresh — no accumulation). Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use per-context duplication in the graph emit.
+  - **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139)). The wrapper-and-its-bare pair collapses into a single graph node (`isWrapped: true`); the wrapper's composite name no longer appears as a node label (only the bare's name does). Each wrapper gets a Mermaid `subgraph w_${bareId}["halt frame"] … end` block containing the `[[bare]]` (subroutine shape) plus a halt-marker `(((halt)))` (visualization aid showing where halt-bound transitions land inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target — exactly one per wrapper. `Graph` data shape gains `isWrapped` and `isHaltMarker` flags on `GraphNode` and a stable `id` on `GraphTransition` (deterministic per-edge identifier — supports downstream tooling like the `machines-demo` interactive viewer at [machines-demo#10](https://github.com/mellonis/machines-demo/issues/10)). Halt-marker graph nodes use negative ids and round-trip back to the singleton `haltState` via `fromGraph`. Bytewise round-trip stability falls out for simple wrappers (no composite name in the graph means `fromGraph(toGraph(state))` recomputes names fresh — no accumulation). Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use per-context duplication in the graph emit.
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index a9f9f21..f32939c 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -232,7 +232,7 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
     // pointing in a loop.
     // Nodes need at least one transition each — State construction at pass 2
     // rejects empty stateDefinitions before pass 3's cycle check would run.
-    const dummyTransition = {pattern: '🞰', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"};
+    const dummyTransition = {pattern: '*', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"};
     const graph = {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 926ced9..a91605d 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -361,7 +361,7 @@ export default class State {
     // to it in transitions. Same as the wrapper's `#id`, recorded for clarity
     // when rewriting transition targets.
     const wrapperGraphId = (s: State): number => s.#id;
-    const clonedHaltIdFor = (wrapper: State): number => -wrapper.#id;
+    const haltMarkerIdFor = (wrapper: State): number => -wrapper.#id;
 
     // The `initialId` is the user-passed start. If it's a wrapper, the
     // collapsed graph node uses its `#id`; otherwise its own `#id`.
@@ -372,7 +372,7 @@ export default class State {
       state: State;
       // When non-null, the State is being processed AS the bare of this wrapper.
       // The collapsed graph node uses `wrapperGraphId(wrapperContext)`,
-      // halt-bound transitions retarget to `clonedHaltIdFor(wrapperContext)`,
+      // halt-bound transitions retarget to `haltMarkerIdFor(wrapperContext)`,
       // self-loop transitions to the bare retarget to the wrapper-id.
       wrapperContext: State | null;
     };
@@ -416,7 +416,7 @@ export default class State {
           continue;
         }
 
-        const clonedHaltId = clonedHaltIdFor(wrapperContext);
+        const haltMarkerId = haltMarkerIdFor(wrapperContext);
         const overrideTarget = wrapperContext.#overriddenHaltState!;
 
         // The override target's collapsed id: if the override is itself a
@@ -427,9 +427,9 @@ export default class State {
           : overrideTarget.#id;
 
         // Emit the halt-marker node if not already present (one per wrapper).
-        if (!(clonedHaltId in nodes)) {
-          nodes[clonedHaltId] = {
-            id: clonedHaltId,
+        if (!(haltMarkerId in nodes)) {
+          nodes[haltMarkerId] = {
+            id: haltMarkerId,
             name: 'halt',
             isHalt: true,
             isHaltMarker: true,
@@ -472,7 +472,7 @@ export default class State {
           let nextStateId: number;
 
           if (target.isHalt) {
-            nextStateId = clonedHaltId;
+            nextStateId = haltMarkerId;
           } else if (target === state) {
             nextStateId = collapsedId;
           } else if (target.#overriddenHaltState && target.#bareState) {
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index 03ca516..d823061 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -19,16 +19,16 @@ describe('decodePatternDescription', () => {
     expect(decodePatternDescription(undefined, alphabets)).toBe('?');
   });
 
-  test('"other symbol" → "🞰" (whole-state ifOtherSymbol)', () => {
-    expect(decodePatternDescription('other symbol', alphabets)).toBe('🞰');
+  test('"other symbol" → "*" (whole-state ifOtherSymbol)', () => {
+    expect(decodePatternDescription('other symbol', alphabets)).toBe('*');
   });
 
   test('literal cell wraps in single quotes', () => {
     expect(decodePatternDescription('[["0"]]', alphabets)).toBe("'0'");
   });
 
-  test('per-cell null → "🞰"', () => {
-    expect(decodePatternDescription('[[null]]', alphabets)).toBe('🞰');
+  test('per-cell null → "*"', () => {
+    expect(decodePatternDescription('[[null]]', alphabets)).toBe('*');
   });
 
   test('cell equal to tape blank → "B"', () => {
@@ -203,12 +203,12 @@ describe('splitUnescaped', () => {
 
 describe('parsePatternString', () => {
   test('returns null for the global ifOtherSymbol marker', () => {
-    expect(parsePatternString('🞰', [[' ', '0']])).toBeNull();
+    expect(parsePatternString('*', [[' ', '0']])).toBeNull();
   });
 
-  test('per-cell `🞰` becomes null', () => {
+  test('per-cell `*` becomes null', () => {
     // Multi-tape pattern where one cell is per-cell ifOtherSymbol.
-    expect(parsePatternString("'0',🞰", [[' ', '0'], [' ', 'a']])).toEqual([['0', null]]);
+    expect(parsePatternString("'0',*", [[' ', '0'], [' ', 'a']])).toEqual([['0', null]]);
   });
 
   test('per-cell `B` becomes the tape blank symbol', () => {
@@ -393,7 +393,7 @@ describe('README diagrams: engine-generated outputs', () => {
       'idle -. enter .->',
       "\"['b'] → ['*']/[R]\"",
       '"[B] → [K]/[L]"',
-      '"[🞰] → [K]/[R]"',
+      '"[*] → [K]/[R]"',
     ]);
   });
 
@@ -439,7 +439,7 @@ describe('README diagrams: engine-generated outputs', () => {
       'idle([idle])',
       'idle -. enter .->',
       "\"['X'] → [K]/[S]\"",
-      '"[🞰] → [K]/[R]"',
+      '"[*] → [K]/[R]"',
     ]);
   });
 
@@ -468,7 +468,7 @@ describe('README diagrams: engine-generated outputs', () => {
       '"halt frame"', // subgraph label
       'idle([idle])', // pre-execution sentinel — always emitted
       'idle -. enter .->', // labeled dotted enter arrow points at the initial state
-      '"[🞰] → [E]/[S]"', // eraseHere's erase command
+      '"[*] → [E]/[S]"', // eraseHere's erase command
       '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
     ]);
   });
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index 51c90db..e7ae37e 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -47,10 +47,11 @@ const symbolCommandDescriptionToLabel: Record<string, string> = {
 };
 
 // Reserved characters in the encoded pattern string:
-//   '🞰'  (U+1F7B0 HEAVY EIGHT BALLOON-SPOKED ASTERISK) per-cell ifOtherSymbol —
-//        matches any symbol on that tape. Distinct from the regular ASCII '*'
-//        (U+002A) so an alphabet that contains literal '*' (rendered as the
-//        quoted `'*'`) is unambiguously different from the catch-all marker.
+//   '*'  ASCII asterisk (U+002A) — per-cell ifOtherSymbol, matches any symbol
+//        on that tape. ASCII (not a fancier glyph like U+1F7B0) so it renders
+//        in every Mermaid environment and every monospace font. A literal `*`
+//        in the alphabet is unambiguous from the marker because it's quoted
+//        (`'*'`).
 //   'B'  the tape's blank symbol shorthand (in read patterns). A literal `B`
 //        in the alphabet is unambiguous from the marker because it's quoted
 //        (`'B'`).
@@ -58,12 +59,12 @@ const symbolCommandDescriptionToLabel: Record<string, string> = {
 //   '|'  separates alternative patterns
 //   "'"  surrounds a literal alphabet symbol — e.g. `'0'` for literal `0`,
 //        `'X'` for literal `X`. The quoting is what visually separates literal
-//        symbols from the convention markers `🞰` / `B` and from the write
+//        symbols from the convention markers `*` / `B` and from the write
 //        commands `K` / `E`.
-//   '\\' escape prefix — to represent any of '🞰', 'B', ',', '|', "'", or '\\'
+//   '\\' escape prefix — to represent any of '*', 'B', ',', '|', "'", or '\\'
 //        as a *literal* alphabet symbol *inside* the quotes (e.g. `'\''` for
 //        a literal apostrophe).
-const IF_OTHER_MARKER = '🞰';
+const IF_OTHER_MARKER = '*';
 const BLANK_MARKER = 'B';
 
 function escapeAlphabetSymbol(s: string): string {
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index c9e55a6..79fdefe 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -49,16 +49,16 @@ export function toMermaid(graph: Graph): string {
   const wrappedNodes = nodes.filter((n) => n.isWrapped);
 
   // Convention: wrapped node id N → halt marker id -N.
-  const clonedHaltFor = (wrappedId: number): number => -wrappedId;
+  const haltMarkerIdFor = (wrappedId: number): number => -wrappedId;
 
   // Set of halt-marker ids that belong to some wrapper (= are inside a subgraph).
-  const clonedHaltIds = new Set<number>();
+  const haltMarkerIds = new Set<number>();
 
   for (const w of wrappedNodes) {
-    const clonedId = clonedHaltFor(w.id);
+    const haltMarkerId = haltMarkerIdFor(w.id);
 
-    if (clonedId in graph.nodes) {
-      clonedHaltIds.add(clonedId);
+    if (haltMarkerId in graph.nodes) {
+      haltMarkerIds.add(haltMarkerId);
     }
   }
 
@@ -66,7 +66,7 @@ export function toMermaid(graph: Graph): string {
   // No special round-shape `((…))` for the initial — the `idle -. enter .->`
   // arrow emitted below is the sole "start here" signal.
   for (const node of nodes) {
-    if (node.isWrapped || clonedHaltIds.has(node.id)) {
+    if (node.isWrapped || haltMarkerIds.has(node.id)) {
       continue;
     }
 
@@ -88,14 +88,14 @@ export function toMermaid(graph: Graph): string {
   // Emit one subgraph per wrapper, in sorted wrapped-id order.
   for (const wrapped of wrappedNodes) {
     const wrappedMid = mermaidIdFor(wrapped.id);
-    const clonedId = clonedHaltFor(wrapped.id);
-    const clonedMid = mermaidIdFor(clonedId);
+    const haltMarkerId = haltMarkerIdFor(wrapped.id);
+    const haltMarkerMid = mermaidIdFor(haltMarkerId);
 
     lines.push(`  subgraph w_${wrapped.id}["halt frame"]`);
     lines.push(`    ${wrappedMid}[["${wrapped.name}"]]`);
 
-    if (clonedId in graph.nodes) {
-      lines.push(`    ${clonedMid}(((halt)))`);
+    if (haltMarkerId in graph.nodes) {
+      lines.push(`    ${haltMarkerMid}(((halt)))`);
     }
 
     lines.push('  end');
@@ -196,7 +196,7 @@ export function fromMermaid(text: string): Graph {
   // Track the halt-marker ids that appeared inside a subgraph — they should be
   // marked `isHaltMarker: true` even though they share the `(((halt)))` shape
   // with the real halt at the top level.
-  const clonedHaltIds = new Set<number>();
+  const haltMarkerIds = new Set<number>();
   let inSubgraph = false;
 
   const ensureNode = (
@@ -262,12 +262,12 @@ export function fromMermaid(text: string): Graph {
 
     if (hm) {
       const id = parseMermaidId(hm[1]);
-      const isCloned = inSubgraph || id < 0;
+      const isHaltMarker = inSubgraph || id < 0;
 
-      ensureNode(id, {name: 'halt', isHalt: true, isHaltMarker: isCloned});
+      ensureNode(id, {name: 'halt', isHalt: true, isHaltMarker});
 
-      if (isCloned) {
-        clonedHaltIds.add(id);
+      if (isHaltMarker) {
+        haltMarkerIds.add(id);
       }
 
       continue;

From 18eb7936a4e934839b9ede2bf684735fe5fdc9ac Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 00:18:17 +0300
Subject: [PATCH 012/118] chore(release): 7.0.0-alpha.1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First v7 pre-release. Consolidates the composition-representation
overhaul landed across #149 / #148 / #138 / #139 on the v7 branch.
Publishes to npm under the `next` dist-tag.

- Bump all 4 packages 6.4.0 → 7.0.0-alpha.1 (lerna lockstep)
- Widen peer dep `@turing-machine-js/machine` on the three
  dependent packages: `^6.0.0` → `^7.0.0-alpha.1`
- CHANGELOG entry for [7.0.0-alpha.1] with full migration walkthrough
- README versioning notes: v7 (in progress) → v7 (alpha 1, 2026-05-21)
  with install snippet and #102 status callout

Outstanding for stable v7.0.0: #102 (debugger step-in/over/out).
v7-branch merges don't auto-close — `closes` keywords carried here
fire on the eventual v7 → master release PR, not on this merge.

closes #138
closes #139
closes #148
closes #149
---
 lerna.json                                    |  2 +-
 package-lock.json                             | 14 ++--
 packages/builder/package.json                 |  4 +-
 .../library-binary-numbers-bare/package.json  |  4 +-
 packages/library-binary-numbers/package.json  |  4 +-
 packages/machine/CHANGELOG.md                 | 70 +++++++++++++++++++
 packages/machine/README.md                    |  2 +-
 packages/machine/package.json                 |  2 +-
 8 files changed, 86 insertions(+), 16 deletions(-)

diff --git a/lerna.json b/lerna.json
index e573776..9859cef 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "6.4.0",
+  "version": "7.0.0-alpha.1",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index ecca00f..c2cc36c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10656,40 +10656,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "6.4.0",
+      "version": "7.0.0-alpha.1",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^6.0.0"
+        "@turing-machine-js/machine": "^7.0.0-alpha.1"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "6.4.0",
+      "version": "7.0.0-alpha.1",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^6.0.0"
+        "@turing-machine-js/machine": "^7.0.0-alpha.1"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "6.4.0",
+      "version": "7.0.0-alpha.1",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^6.0.0"
+        "@turing-machine-js/machine": "^7.0.0-alpha.1"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "6.4.0",
+      "version": "7.0.0-alpha.1",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/builder/package.json b/packages/builder/package.json
index 138af98..d48a170 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "6.4.0",
+  "version": "7.0.0-alpha.1",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^6.0.0"
+    "@turing-machine-js/machine": "^7.0.0-alpha.1"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index 2efd624..b0f03f1 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "6.4.0",
+  "version": "7.0.0-alpha.1",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^6.0.0"
+    "@turing-machine-js/machine": "^7.0.0-alpha.1"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index d938e47..7726d42 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "6.4.0",
+  "version": "7.0.0-alpha.1",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^6.0.0"
+    "@turing-machine-js/machine": "^7.0.0-alpha.1"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index 43e71b1..e24e8be 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,76 @@ 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.1] - 2026-05-21
+
+First v7 pre-release. Consolidates the composition-representation overhaul landed across [#149](https://github.com/mellonis/turing-machine-js/issues/149), [#148](https://github.com/mellonis/turing-machine-js/issues/148), [#138](https://github.com/mellonis/turing-machine-js/issues/138), and [#139](https://github.com/mellonis/turing-machine-js/issues/139). Published to npm 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.1`. Migration walkthrough at the bottom.
+
+### Changed
+
+- **`State.prototype.withOverrodeHaltState` renamed to `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: `overridden` (past participle) fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. Renames in lockstep:
+  - public method `State.prototype.withOverrodeHaltState` → `withOverriddenHaltState`
+  - getter `state.overrodeHaltState` → `state.overriddenHaltState`
+  - private field `#overrodeHaltState` → `#overriddenHaltState`
+  - serialized `Graph` data field `node.overrodeHaltStateId` → `node.overriddenHaltStateId`
+
+- **Wrapped-state composite name format flipped from `bare>override` to `bare(override)`** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). The old `>`-flat notation collided structurally-distinct wrap-trees into the same string: `A.with(B.with(A))` and `A.with(B).with(A)` both rendered as `A>B>A` despite being different runtime shapes. Paren-nested keeps them distinct: `A(B(A))` vs `A(B)(A)`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` constructor now throws on names with these characters. `>` is no longer reserved and is valid in user-provided names again.
+
+- **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138), [#139](https://github.com/mellonis/turing-machine-js/issues/139)). Each `withOverriddenHaltState` wrapper collapses onto its bare's representation — `GraphNode.isWrapped: true`, no separate wrapper node in graph data. `toMermaid` wraps each `[[bare]]` (Mermaid subroutine shape) + a synthesized `(((halt)))` halt-marker (`GraphNode.isHaltMarker: true`) inside a `subgraph w_${bareId}["halt frame"] … end` block. Dotted `onHalt` from `[[bare]]` crosses the subgraph border to the override target. An always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state (replaces the v6 `((round))` shape convention).
+
+- **Edge-label vocabulary rewritten** for readability — `[reads] → [writes]/[moves]` with each role wrapped in `[…]` (the tape-block indicator; always present, even single-tape). Read cells: `'X'` literal-quoted, `*` (ASCII; ifOtherSymbol catch-all — literal `*` in the alphabet renders as `'*'`), `B` (tape's blank shorthand). Write cells: literal-quoted, `K` (keep), `E` (erase = write blank). Move cells: `L` / `R` / `S`. Alternation per-pattern bracket: `['^']|['1']` for single-tape, `['0','a']|['1','b']` for multi-tape. Compact in-bracket `['^'|'1']` form is rejected by `fromMermaid` (would read as cross-product semantics in multi-tape).
+
+- **Thick `==>` arrows for stack-pushing transitions.** When a transition's target is a wrapped state AND ≠ source (i.e. would push the wrapper's override onto the runtime stack per `TuringMachine.run`'s line ~220 transition-time push), the engine emits a thick `==>` arrow — visual signal for "this transition fires a stack push."
+
+- **`GraphTransition.id`** — stable, deterministic per-edge identifier (`${fromNodeId}-${patternIx}`). Supports downstream tooling for edge-targeting in rendered Mermaid SVG (e.g. highlight-the-next-transition in interactive viewers).
+
+- **`summarize().stateCount` filters `isHaltMarker` nodes** — halt markers are visualization sentinels (all map back to singleton `haltState` at runtime), not distinct runtime states. Matches the per-algorithm header count in `library-binary-numbers/states.md`.
+
+### Added
+
+- **#139 regression test** — `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers. The wrapper's composite name (e.g. `scanToX(eraseHere)`) no longer appears as any graph-node label, so `fromGraph` reconstructs and recomputes the composite fresh on each pass — no round-trip name accumulation.
+
+- **Multi-tape example** in the engine README illustrating the bracketed format with two tapes.
+
+- **§Diagram conventions section** in the engine README — full reference: node shapes, edge styles, groupings, edge label format + cell vocabulary, alternation rule, multi-tape example.
+
+- **Cross-package introspection consistency** — `library-binary-numbers/states.md` per-algorithm header line now uses `summarizeGraph(graph)` for its `N states; N transitions; N wrappers (max nesting depth N); has cycles` summary, dogfooding the same API any consumer would use.
+
+### Removed
+
+- Hand-drawn pedagogical Mermaid blocks in engine + root READMEs. The v7 `toMermaid` output is now the primary illustration — no more vocabulary mismatch between hand-drawn and engine-rendered diagrams.
+
+### Migration
+
+For consumers updating from v6.x:
+
+**1. Identifier rename** (mechanical):
+
+```sh
+git grep -l 'OverrodeHaltState\|overrodeHaltState' | xargs sed -i '' \
+  -e 's/OverrodeHaltState/OverriddenHaltState/g' \
+  -e 's/overrodeHaltState/overriddenHaltState/g'
+```
+
+Persisted `State.toGraph` JSON dumps need the same `overrodeHaltStateId` → `overriddenHaltStateId` field rename.
+
+**2. Wrapper composite name format** — code that pattern-matches `state.name` for wrapper composites needs to switch from `>`-split to paren-parse: `'A>B'` is now `'A(B)'`.
+
+**3. State name validation** — any code that constructs `new State(null, 'foo(bar)')` now throws. Real-world identifier-style state names (`scanToX`, `goHome`, `incT1`) are unaffected.
+
+**4. `toMermaid` output format** — if you render `toMermaid` output programmatically, the edge-label vocabulary changed completely (bracketed-tape-block format with `K`/`E`/`B`/`*`/`L`/`R`/`S`). See the engine README's §Diagram conventions for the full vocabulary.
+
+**5. `Graph` data shape** — `GraphNode` gained `isWrapped: boolean` + `isHaltMarker: boolean`; `GraphTransition` gained `id: string`. Most consumers don't need to change. If you call `summarize().stateCount`, the value now excludes halt markers (typically matches what you actually wanted — runtime state count, not visualization-node count).
+
+### Out of v7-alpha.1 (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. Additive — won't change any existing API. Will land in `v7.0.0-alpha.2` or stable `v7.0.0`.
+
+### Compatibility
+
+- Peer dep `@turing-machine-js/machine` widened `^6.0.0` → `^7.0.0-alpha.1` on `@turing-machine-js/builder`, `@turing-machine-js/library-binary-numbers`, `@turing-machine-js/library-binary-numbers-bare`.
+
 ## [6.4.0] - 2026-05-19
 
 Adds a new awaited hook on `TuringMachine.run`. Minor release, additive — no breaking changes. Closes [#163](https://github.com/mellonis/turing-machine-js/issues/163).
diff --git a/packages/machine/README.md b/packages/machine/README.md
index ad90f3c..9c9c9e5 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -648,7 +648,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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** *(in progress)* — Composition-representation overhaul. Breaking renames + reshapes scheduled for the v7 cut. Landing piecewise on the `v7` branch; one entry per landed change:
+- **v7** *(alpha 1, 2026-05-21)* — Composition-representation overhaul. **First pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.1`). Stable v7.0.0 still pending [#102](https://github.com/mellonis/turing-machine-js/issues/102) (debugger step-in/over/out primitives). Landed in alpha.1:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
   - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
   - **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139)). The wrapper-and-its-bare pair collapses into a single graph node (`isWrapped: true`); the wrapper's composite name no longer appears as a node label (only the bare's name does). Each wrapper gets a Mermaid `subgraph w_${bareId}["halt frame"] … end` block containing the `[[bare]]` (subroutine shape) plus a halt-marker `(((halt)))` (visualization aid showing where halt-bound transitions land inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target — exactly one per wrapper. `Graph` data shape gains `isWrapped` and `isHaltMarker` flags on `GraphNode` and a stable `id` on `GraphTransition` (deterministic per-edge identifier — supports downstream tooling like the `machines-demo` interactive viewer at [machines-demo#10](https://github.com/mellonis/machines-demo/issues/10)). Halt-marker graph nodes use negative ids and round-trip back to the singleton `haltState` via `fromGraph`. Bytewise round-trip stability falls out for simple wrappers (no composite name in the graph means `fromGraph(toGraph(state))` recomputes names fresh — no accumulation). Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use per-context duplication in the graph emit.
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 564b7bc..008f7ba 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "6.4.0",
+  "version": "7.0.0-alpha.1",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"

From e7e055d978d604f3488a9e1024739d79e32db2b9 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 00:28:01 +0300
Subject: [PATCH 013/118] test(graphFormats): cover fromMermaid parser error
 paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three new tests in the existing `fromMermaid error paths` block:

- Read label with no bracketed list (graphFormats.ts:379)
- Write/move cell-count mismatch (graphFormats.ts:396)
- Backslash-escape branch in `stripBrackets` (graphFormats.ts:355-356)

Coverage: statements 98.29 → 98.72 (+0.43),
branches 95.35 → 96.13 (+0.78), graphFormats.ts 96.42/90.62 →
98.8/94.79.

Addresses the Coveralls "coverage fell" status on PR #167 (v7 → master
draft) after v7-alpha.1 work landed. Remaining uncovered branches in
v7 code are defensive fallbacks (graph.ts:173/209, State.ts:463-464,
introspection.ts:121) — not worth synthetic tests.
---
 packages/machine/src/utilities/graph.spec.ts | 45 ++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index d823061..e8592fd 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -292,6 +292,51 @@ describe('fromMermaid error paths', () => {
 
     expect(() => fromMermaid(mermaid)).toThrow(/compact in-bracket alternation/);
   });
+
+  test('throws when the read label has no bracketed list', () => {
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0","1"]]',
+      '  s0(((halt)))',
+      '  s1["entry"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      '  s1 -- "X → [K]/[S]" --> s0', // no `[…]` in the read part at all
+    ].join('\n');
+
+    expect(() => fromMermaid(mermaid)).toThrow(/no bracketed read-list/);
+  });
+
+  test('throws on write/move cell-count mismatch', () => {
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0","1"]]',
+      '  s0(((halt)))',
+      '  s1["entry"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      "  s1 -- \"['0'] → [K,K]/[R]\" --> s0", // 2 writes, 1 move
+    ].join('\n');
+
+    expect(() => fromMermaid(mermaid)).toThrow(/write-cells.*move-cells.*mismatch/);
+  });
+
+  test('parses backslash-escaped chars inside a bracket (e.g. literal `|` as `\\|`)', () => {
+    // `stripBrackets` walks the inner content character-by-character; when it
+    // hits `\`, it skips the next char (so `\|` is a literal pipe, not the
+    // alternation separator). Exercises the escape branch in stripBrackets.
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","|"]]',
+      '  s0(((halt)))',
+      '  s1["x"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      "  s1 -- \"['\\|'] → [K]/[S]\" --> s0", // pattern reads `'\|'` (literal pipe)
+    ].join('\n');
+
+    expect(() => fromMermaid(mermaid)).not.toThrow();
+  });
 });
 
 describe('fromMermaid ensureNode update branches', () => {

From a29002c6c03caaa53b24668ff588738e044e6ea9 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 00:42:22 +0300
Subject: [PATCH 014/118] test(coverage): cover remaining reachable v7 branches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three more tests for the v7 lines #171 didn't reach:

- `State.toGraph` unbound-Reference catch in WRAPPER context
  (State.ts:463-464) — the existing test covered the non-wrapper
  branch; this one wraps the unbound-Ref state via
  `withOverriddenHaltState(...)` to hit the other try/catch
- `parseWriteSymbolLabel` fallback return (graph.ts:209) — defensive
  return-as-is for unrecognized labels
- `parsePatternString` blank-marker `?? cell` fallback (graph.ts:164)
  — defensive return when `alphabets[tapeIx]` is missing

Plus the parser-fallback test in `parsePatternString` describe block
(graph.ts:173) was already added in #171's first round; this PR
finishes the symmetric `parseWriteSymbolLabel` describe block.

Coverage: statements 98.72 → 99.14 (+0.42),
branches 96.13 → 96.71 (+0.58), lines 98.32 → 99.21 (+0.89),
State.ts 99.11 → 100% statements.

Should clear Coveralls' remaining -0.5% drop on PR #167 by pulling v7
total above master.

Remaining uncovered (not worth synthetic tests):
- graphFormats.ts:344 — defensive throw inside `stripBrackets`
  closure, unreachable via fromMermaid's slice logic
- introspection.ts:121 — `if (node)` guard in cycle detection
---
 packages/machine/src/classes/State.spec.ts   | 26 +++++++++++++++++-
 packages/machine/src/utilities/graph.spec.ts | 29 ++++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index f32939c..3c16b0a 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -208,7 +208,7 @@ describe('State.withOverriddenHaltState', () => {
 });
 
 describe('State.toGraph — unbound Reference', () => {
-  test('skips a transition whose nextState is an unbound Reference', () => {
+  test('skips a transition whose nextState is an unbound Reference (non-wrapper context)', () => {
     // An unbound Reference throws when its `.ref` getter is read. State.toGraph
     // catches that and skips the transition rather than failing the whole walk.
     const unboundRef = new Reference();
@@ -222,6 +222,30 @@ describe('State.toGraph — unbound Reference', () => {
     // Only the haltState-bound transition survives; the unbound one is dropped.
     expect(graph.nodes[state.id].transitions).toHaveLength(1);
   });
+
+  test('skips a transition whose nextState is an unbound Reference (wrapper context)', () => {
+    // toGraph has a separate try/catch in its wrapper-context branch — when the
+    // bare being walked is inside a `withOverriddenHaltState` wrapper. Same
+    // skip-and-continue semantic.
+    const unboundRef = new Reference();
+    const bare = new State({
+      [symbol(['0'])]: {nextState: unboundRef},
+      [symbol(['1'])]: {nextState: haltState},
+    }, 'bare');
+    const override = new State({
+      [symbol(['0'])]: {nextState: haltState},
+      [symbol(['1'])]: {nextState: haltState},
+    }, 'override');
+    const wrapped = bare.withOverriddenHaltState(override);
+
+    const graph = State.toGraph(wrapped, tapeBlock);
+
+    // The collapsed wrapper node retains only the haltState-bound transition;
+    // the unbound-Ref one is dropped.
+    const collapsedNode = graph.nodes[wrapped.id];
+
+    expect(collapsedNode.transitions).toHaveLength(1);
+  });
 });
 
 describe('State.fromGraph — cyclic override-halt chain', () => {
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index e8592fd..f2efd9c 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -4,6 +4,7 @@ import {
   decodeWriteSymbol,
   parseMovementLabel,
   parsePatternString,
+  parseWriteSymbolLabel,
   splitUnescaped,
 } from './graph';
 import {fromMermaid, toMermaid} from './graphFormats';
@@ -214,6 +215,34 @@ describe('parsePatternString', () => {
   test('per-cell `B` becomes the tape blank symbol', () => {
     expect(parsePatternString("B,'a'", [[' ', '0'], [' ', 'a']])).toEqual([[' ', 'a']]);
   });
+
+  test('fallback: cell that is not marker/blank/quoted is returned as-is', () => {
+    // Defensive — the parser doesn't throw on unexpected cells; it returns
+    // them as-is, so consumer code can decide whether to reject.
+    expect(parsePatternString('Q', [[' ', '0']])).toEqual([['Q']]);
+  });
+
+  test('blank-marker fallback when alphabet for the tape is missing', () => {
+    // Defensive: if alphabets[tapeIx] is undefined, returns the marker
+    // string itself rather than throwing.
+    expect(parsePatternString('B', [])).toEqual([['B']]);
+  });
+});
+
+describe('parseWriteSymbolLabel', () => {
+  test('maps K/E to upstream symbolCommands', () => {
+    expect(parseWriteSymbolLabel('K')).toBe(symbolCommands.keep);
+    expect(parseWriteSymbolLabel('E')).toBe(symbolCommands.erase);
+  });
+
+  test('strips single quotes from a literal alphabet symbol', () => {
+    expect(parseWriteSymbolLabel("'X'")).toBe('X');
+  });
+
+  test('fallback: label that is not K/E/quoted is returned as-is', () => {
+    // Defensive — same shape as parsePatternString's fallback.
+    expect(parseWriteSymbolLabel('Z')).toBe('Z');
+  });
 });
 
 describe('parseMovementLabel', () => {

From c36b7b698d6de1cb30ac2ddfde9b3323292cf1e3 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 06:39:31 +0300
Subject: [PATCH 015/118] docs(spec): callable-subtree visualization for #174

Draft design spec at docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md.

Captures the reframing of `withOverriddenHaltState` visualization as a
function-call model: wrapper = call site, callable subtree = body, halt
= return. Replaces v7 alpha.1's halt-frame subgraph emit (closes the
design phase of #174).

Key decisions documented:
- Bold `==>` reserved for wrapper-to-bare `call` arrows only.
- Dotted `-.->` reserved for frame-level dispatch (return, halt, enter).
- Wrappers and bares as separate GraphNodes (un-collapsing alpha.1's
  collapse). Each unique bare gets ONE subtree; multiple wrappers share
  via `bareStateId`.
- Union-find merges subtrees only when bare reach sets overlap (rare in
  practice; minusOne probe confirms 3 components instead of alpha.1's
  5 subgraphs).
- Halt marker `c_X` always emitted; orphan signals dead wrapper.
- `onHalt` keyword retired; wrapper outgoing is a regular solid `-->`.
- `return`/`halt` arrows derived at emit time, not stored as Graph fields.

Includes 7 worked examples with Mermaid diagrams:
- simple wrapper, PostMachine subroutine, multi-wrapper sharing bare,
  self-wrapping `A.wohs(A)`, nested `.wohs()` chain (4a/4b), Reference
  cycle dead wrapper.

Plus 6 edge case discussions and the minusOne worked example showing
the new emit shape vs alpha.1's per-context duplication.

Implementation pending (tasks #30 revert P1, #31 reimplement per the
spec). Related issues filed: #175 memoization, #176 nested-wohs name
simplification, post-machine-js#85 subroutine hopper evaluation.
---
 ...026-05-21-halt-frame-transitive-closure.md | 672 ++++++++++++++++++
 1 file changed, 672 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md

diff --git a/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md b/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
new file mode 100644
index 0000000..6a163c3
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
@@ -0,0 +1,672 @@
+# Callable-subtree visualization for `withOverriddenHaltState`
+
+**Status:** DRAFT 2026-05-21 — supersedes the earlier "transitive-closure halt-frame" framing of this doc. Tracks [#174](https://github.com/mellonis/turing-machine-js/issues/174). Lands on the `v7` integration branch before v7 stable cut. **Previous implementation (frameId-based exclusive-reachable algorithm in `State.toGraph`) is being reverted in favor of the design below.**
+
+**Relation to [#173](https://github.com/mellonis/turing-machine-js/issues/173):** #173 closed (2026-05-21) as the literal complaint (orphan `c_N` + onHalt anchor) doesn't apply to the new design — there's no `c_N` per-wrapper concept anymore. The new design has per-bare `c_A` halt sinks and per-wrapper call/return/onHalt edges, which together visualize runtime semantics directly.
+
+## The reframing
+
+`withOverriddenHaltState` is, structurally, **a function call**. When you write `W = A.wohs(target)`:
+
+- `W` is a **call site** — invoking it pushes `target` onto the halt-stack and delegates to `A`'s transitions.
+- `A` (or rather, the subtree forward-reachable from `A`) is the **callable body**.
+- The "halt" at the end of `A`'s execution is a **return point** — the stack pop kicks the override into action.
+
+So the runtime model is "graph of callable subtrees, dispatched from a top-level driver." The diagram should reflect that directly.
+
+## Mental model & vocabulary
+
+| Concept | Visualization |
+|---|---|
+| **Callable subtree** of a bare `A` | `subgraph subtree_A["callable subtree of A"]` block containing `A`, A's body states, and a local halt sink `c_A` |
+| **Wrapper** `W = A.wohs(target)` | A `[[A(target)]]` node OUTSIDE the subtree |
+| **Call** (wrapper → bare) | Bold `==>` arrow labeled `call`. **Reserved**: only wrappers emit bold arrows, and only to their bare. Other transitions whose target happens to be a wrapper (e.g., dispatcher → W1) stay as regular solid `-->`. Multiple wrappers sharing a bare collapse into one `==>` ribbon via Mermaid `&` syntax: `s_W1 & s_W2 == call ==> s_A` |
+| **Return** (subtree halt → wrapper) | Dotted `-.->` arrow from the SUBGRAPH back to each wrapper, labeled `return`. Multiple wrappers collapse via `&` on the target side: `subtree_A -. return .-> s_W1 & s_W2`. **Demand-emit** — only emitted when `c_A` has at least one incoming edge AND the wrapper actually calls this subtree |
+| **Halt** (subtree halt → real halt) | Dotted `-.->` arrow from the SUBGRAPH to `s0`, labeled `halt`. **Demand-emit** — only emitted when `c_A` has incoming edges AND there's a non-wrapper entry path (solid `-->`) into any state in the subtree. Fires when the subtree is entered without a wrapper on the stack |
+| **Wrapper's outgoing** (post-return continuation) | Solid `-->` arrow from wrapper to its override target. Just a regular transition — the wrapper "transitions to" its override after the return fires |
+| **Idle sentinel** | `idle([idle])` + dotted `idle -. enter .-> initial` (unchanged from v7 alpha.1) |
+| **Real halt** | `s0(((halt)))` at top level (unchanged from v7 alpha.1) |
+| **Local subtree halt** | `c_A(((halt)))` inside the subtree's subgraph block — body halts visually land here |
+
+## Arrow style summary
+
+| Style | Used for |
+|---|---|
+| Solid `-->` | Regular state-to-state transitions, including (a) wrapper → override target, and (b) any non-wrapper state's transitions, even when their target is a wrapper |
+| Bold `==>` | **Only** the wrapper-to-bare `call` arrow. Source is always a wrapper; target is its bare |
+| Dotted `-.->` | Frame-level dispatch (subtree return, subtree halt, idle enter) |
+
+Bold `==>` is reserved — it's the visual signature of "a wrapper calling into its callable subtree." Counting bold arrows in the diagram tells you exactly how many wrappers are in play. (Departs from v7 alpha.1's "bold-into-any-wrapper" rule; under that older rule, dispatcher → W1 was also bold. Under the new rule, it's solid — the reader sees W1's `[[…]]` shape and infers "wrapper" without needing redundant arrow styling on every transition into it.)
+
+## Examples
+
+### Example 1 — simple wrapper
+
+`A.withOverriddenHaltState(target)`, no shared bare:
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_target["target"]
+  s_W[["A(target)"]]
+
+  subgraph subtree_A["callable subtree of A"]
+    s_A["A"]
+    s_body["body"]
+    c_A((("halt")))
+  end
+
+  s_W == call ==> s_A
+  subtree_A -. return .-> s_W
+  s_W --> s_target
+
+  idle -. enter .-> s_W
+
+  s_A -- "[*]" --> s_body
+  s_body -- "['*']" --> c_A
+  s_target -- "[*]" --> s0
+```
+
+Reading the runtime: idle → enter → W → call → subtree → body halts at c_A → return to W → W's `--> s_target` → s_target → halt.
+
+**No `halt` arrow** from the subtree to `s0`: there's no non-wrapper entry path into the subtree (only `s_W == call ==>` enters it), so the empty-stack case never fires. The `halt` arrow is demand-emit and omitted here.
+
+### Example 1b — PostMachine subroutine (the canonical motivating case)
+
+`PostMachine` program `{ 1: call('rightToBlank'); 2: mark; 3: stop; rightToBlank: { 1: right; 2: check(1,3); 3: stop } }`. PostMachine constructs internally:
+
+- A **hopper state** named `rightToBlank` whose only transition is `[ifOtherSymbol]: nextState = rightToBlank::1` (forward to the first body state).
+- **Body states** `rightToBlank::1` (the `right` command) and `rightToBlank::2` (the `check` command).
+- A **continuation state** `1~2` (where control resumes after the subroutine returns).
+- A **wrapper** `W = rightToBlank.withOverriddenHaltState(continuation_1~2)`.
+- A **top-level instruction 2** (`mark`), reached via the continuation.
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_W[["rightToBlank(1~2)"]]
+  s_continuation["1~2"]
+  s_inst2["2"]
+
+  subgraph subtree_rightToBlank["callable subtree of rightToBlank"]
+    s_hopper["rightToBlank"]
+    s_body1["rightToBlank::1"]
+    s_body2["rightToBlank::2"]
+    c_rightToBlank((("halt")))
+  end
+
+  s_W == call ==> s_hopper
+  subtree_rightToBlank -. return .-> s_W
+  s_W --> s_continuation
+
+  idle -. enter .-> s_W
+
+  s_hopper -- "[*]" --> s_body1
+  s_body1 -- "[*] → [K]/[R]" --> s_body2
+  s_body2 -- "['*'] → [K]/[S]" --> s_body1
+  s_body2 -- "[B] → [K]/[S]" --> c_rightToBlank
+
+  s_continuation -- "[*] → [K]/[S]" --> s_inst2
+  s_inst2 -- "[*] → ['*']/[S]" --> s0
+```
+
+**What this resolves vs. alpha.1's emit:**
+
+- Body states `rightToBlank::1` and `rightToBlank::2` are INSIDE the subtree (alpha.1 put them outside).
+- The check's halt-bound transition (`s_body2 -- "[B]" -->`) retargets to `c_rightToBlank` instead of `s0` (alpha.1 emitted `→ s0`, misleading about runtime).
+- No orphan halt marker — `c_rightToBlank` has incoming from `s_body2`. The condition that prompted #173 doesn't arise.
+- The wrapper `s_W[["rightToBlank(1~2)"]]` sits OUTSIDE the subtree as a separate node — it's the call site, not the bare.
+
+Runtime trace reads off the diagram: `idle → W → call → hopper → body_1 → body_2 → c_rightToBlank → return W → continuation → instruction_2 → s0`. Each arrow corresponds to a runtime step.
+
+### Example 2 — multi-wrapper sharing a bare
+
+Two wrappers `W1 = A.wohs(target_B)` and `W2 = A.wohs(target_C)`, dispatcher routes:
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_disp["dispatcher"]
+  s_targetB["target_B"]
+  s_targetC["target_C"]
+
+  subgraph subtree_A["callable subtree of A"]
+    s_A["A"]
+    s_body["body"]
+    c_A((("halt")))
+  end
+
+  s_W1[["A(target_B)"]] & s_W2[["A(target_C)"]] == call ==> s_A
+  subtree_A -. return .-> s_W1 & s_W2
+  subtree_A -. halt .-> s0
+  s_W1 --> s_targetB
+  s_W2 --> s_targetC
+
+  idle -. enter .-> s_disp
+
+  s_disp -- "['*']" --> s_W1
+  s_disp -- "['+']" --> s_W2
+  s_disp -- "['#']" --> s_A
+
+  s_A -- "[*]" --> s_body
+  s_body -- "['*']" --> c_A
+  s_targetB -- "[*]" --> s0
+  s_targetC -- "[*]" --> s0
+```
+
+Dispatcher's outgoing arrows to W1, W2, and A are all solid `-->` (regular transitions). The reader sees W1 and W2 are wrappers because of the `[[…]]` shape. Two bold `call` arrows in the diagram (the wrappers' calls into A's subtree) — exactly the count of wrappers in play. The subtree's `-. return .->` arrows go back to both wrappers (collapsed via `&`); the `-. halt .->` arrow handles the dispatcher's direct entry path (`['#']`).
+
+### Example 3 — self-wrapping (`A.wohs(A)`)
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_W[["A(A)"]]
+
+  subgraph subtree_A["callable subtree of A"]
+    s_A["A"]
+    c_A((("halt")))
+  end
+
+  s_W == call ==> s_A
+  s_W --> s_A
+  subtree_A -. return .-> s_W
+  subtree_A -. halt .-> s0
+
+  idle -. enter .-> s_W
+
+  s_A -- "[*]" --> c_A
+```
+
+Legal API call (no self-reference validation). Runtime: W push A → A halts → pop A → control to A → A halts again → real halt. The diagram captures both arrows from W to A: bold `call` (entering A under W's stack frame) and solid `-->` (W's "post-return continuation IS A again"). Pattern is "run A twice in sequence."
+
+### Example 4 — nested `.wohs()` chain
+
+Two cases worth comparing: (4a) the chain `.wohs().wohs()` with only the outer entered, and (4b) two independently-referenced wrappers around the same bare.
+
+#### 4a. Chain construction, only outer entered
+
+```ts
+const W1 = A.withOverriddenHaltState(target_1);
+const W2 = W1.withOverriddenHaltState(target_2);
+// Only W2 is referenced from the entry — W1 is never independently entered.
+```
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_target2["target_2"]
+  s_W2[["A(target_1)(target_2)"]]
+
+  subgraph subtree_A["callable subtree of A"]
+    s_A["A"]
+    c_A((("halt")))
+  end
+
+  s_W2 == call ==> s_A
+  subtree_A -. return .-> s_W2
+  s_W2 --> s_target2
+
+  idle -. enter .-> s_W2
+
+  s_A -- "[*]" --> c_A
+  s_target2 -- "[*]" --> s_target2
+  s_target2 -- "[*]" --> s0
+```
+
+**Only ONE wrapper appears in the graph: `s_W2`.** `W1` is structurally absorbed — at runtime, only W2's override (`target_2`) is pushed onto the stack; `target_1` is never on the stack so it never fires. The composite name `A(target_1)(target_2)` is the engine's `state.#name`; it shows the construction chain textually but is technically misleading about runtime behavior (only `target_2` actually fires). Sibling-style emission (no nested frames) is the right rendering because the runtime is single-level.
+
+**Runtime trace:** idle → W2 → call subtree_A → A halts at c_A → return to W2 → W2 transitions to `target_2` → target_2 halts → s0.
+
+`halt` arrow omitted (no non-wrapper entry to subtree_A).
+
+#### 4b. Two independent wrappers, both referenced
+
+```ts
+const W1 = A.withOverriddenHaltState(target_1);
+const W2 = A.withOverriddenHaltState(target_2);
+const dispatcher = new State({
+  [sym_a]: { nextState: W1 },
+  [sym_b]: { nextState: W2 },
+}, 'dispatcher');
+```
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_disp["dispatcher"]
+  s_target1["target_1"]
+  s_target2["target_2"]
+
+  subgraph subtree_A["callable subtree of A"]
+    s_A["A"]
+    c_A((("halt")))
+  end
+
+  s_W1[["A(target_1)"]] & s_W2[["A(target_2)"]] == call ==> s_A
+  subtree_A -. return .-> s_W1 & s_W2
+  s_W1 --> s_target1
+  s_W2 --> s_target2
+
+  idle -. enter .-> s_disp
+  s_disp -- "['a']" --> s_W1
+  s_disp -- "['b']" --> s_W2
+
+  s_A -- "[*]" --> c_A
+  s_target1 -- "[*]" --> s0
+  s_target2 -- "[*]" --> s0
+```
+
+**Two wrappers, both as siblings.** Dispatcher chooses which via input symbol — solid arrows from dispatcher to each wrapper (regular transitions; the `[[…]]` shape on W1 and W2 tells the reader they're wrappers). Each wrapper has its own bold `call` arrow into the subtree.
+
+This is how `library-binary-numbers/minusOne` is built (five sibling wrappers around two distinct bares).
+
+The visual distinction between 4a and 4b: **count the bold `==>` arrows**. 4a has one (W2's call); 4b has two (W1's and W2's). One bold arrow per wrapper in the graph, by construction.
+
+### Example 5 — Reference cycle (dead wrapper)
+
+`A` loops to itself via `Reference`; `W = A.wohs(target)`:
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_target["target"]
+  s_W[["A(target)"]]
+
+  subgraph subtree_A["callable subtree of A"]
+    s_A["A"]
+    c_A((("halt")))
+  end
+
+  s_W == call ==> s_A
+  s_W --> s_target
+
+  idle -. enter .-> s_W
+
+  s_A -- "[*]" --> s_A
+  s_target -- "[*]" --> s0
+```
+
+`c_A` is **orphan** (no `--> c_A` edge): `s_A` loops back to itself via the Reference and never halts. Per the demand-emit rule, `subtree_A -. return .->` and `subtree_A -. halt .->` are BOTH omitted because `c_A` has no incoming edges — neither dispatch path is structurally reachable. Reader sees: "the subtree's `c_A` is unreachable. Whatever the wrapper redirects to (`target`) is also unreachable. Dead wrapper."
+
+The orphan `c_A` alone IS the dead-wrapper signal — no need for orphan return/halt arrows.
+
+## minusOne as a worked example
+
+`library-binary-numbers/minusOne` is a 4-deep wrapper composition that exercises shared bares + override chains. Probed under the union-find rule (2026-05-21): five wrappers, three subtrees.
+
+**Wrapper instances** (constructed via `.withOverriddenHaltState`):
+
+- `W10 = goToNumberStart.wohs(invertNumberGoToNumberWithInversion)`
+- `W14 = goToNumberStart.wohs(normalizeNumberMoveNumberStart)` — same bare, different override
+- `W20 = invertNumber.wohs(normalizeNumber)`
+- `W22 = invertNumber.wohs(W21)` — wraps invertNumber, override is plusOne wrapper
+- `W21 = plusOne.wohs(W20)` — wraps plusOne, override is invertNumber wrapper
+
+**Subtree decomposition** (3 unique bares):
+
+- `subtree_goToNumberStart`: contains `goToNumberStart` bare only (no body; halts directly).
+- `subtree_invertNumber`: contains `invertNumber` bare only (no body; transitions delegate to `goToNumberStart` wrapper externally).
+- `subtree_plusOne`: contains `plusOne` bare + body states (`plusOneFillZeros`, `plusOneAddNumberStart`, `plusOneCaryOne`).
+
+**Compared to alpha.1's emit** (5 subgraph blocks, per-context-duplicated bares): the new emit has **3 subgraph blocks** and de-duplicates the shared bares (`goToNumberStart` and `invertNumber` each appear once instead of twice).
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_minusOne["minusOne"]
+  s_invNumGoTo["invertNumberGoToNumberWithInversion"]
+  s_norm["normalizeNumber"]
+  s_normMove["normalizeNumberMoveNumberStart"]
+  s_normPut["normalizeNumberPutNewStartSymbol"]
+  s_goToNum["goToNumber"]
+
+  subgraph subtree_goToNumberStart["callable subtree of goToNumberStart"]
+    s_goToNumberStart["goToNumberStart"]
+    c_goToNumberStart((("halt")))
+  end
+
+  subgraph subtree_invertNumber["callable subtree of invertNumber"]
+    s_invertNumber["invertNumber"]
+    c_invertNumber((("halt")))
+  end
+
+  subgraph subtree_plusOne["callable subtree of plusOne"]
+    s_plusOne["plusOne"]
+    s_plusOneFillZeros["plusOneFillZeros"]
+    s_plusOneAddNumberStart["plusOneAddNumberStart"]
+    s_plusOneCaryOne["plusOneCaryOne"]
+    c_plusOne((("halt")))
+  end
+
+  s_W10[["goToNumberStart(invertNumberGoToNumberWithInversion)"]]
+  s_W14[["goToNumberStart(normalizeNumberMoveNumberStart)"]]
+  s_W20[["invertNumber(normalizeNumber)"]]
+  s_W21[["plusOne(W20)"]]
+  s_W22[["invertNumber(W21)"]]
+
+  s_W10 == call ==> s_goToNumberStart
+  s_W14 == call ==> s_goToNumberStart
+  s_W20 == call ==> s_invertNumber
+  s_W22 == call ==> s_invertNumber
+  s_W21 == call ==> s_plusOne
+
+  subtree_goToNumberStart -. return .-> s_W10
+  subtree_goToNumberStart -. return .-> s_W14
+  subtree_invertNumber -. return .-> s_W20
+  subtree_invertNumber -. return .-> s_W22
+  subtree_plusOne -. return .-> s_W21
+
+  s_W10 --> s_invNumGoTo
+  s_W14 --> s_normMove
+  s_W20 --> s_norm
+  s_W21 --> s_W20
+  s_W22 --> s_W21
+
+  idle -. enter .-> s_minusOne
+  s_minusOne --> s_W22
+
+  s_invertNumber --> s_W10
+  s_norm --> s_W14
+  s_normMove --> s_normPut
+  s_normPut --> s_goToNum
+```
+
+Reading the override chain: `minusOne → W22 → W21 → W20 → normalizeNumber → W14 → normalizeNumberMoveNumberStart → … → real halt`. Each wrapper's solid `-->` to its override target chains the runtime call sequence.
+
+Reading the bare-sharing: both `W10` and `W14` call into the SAME `subtree_goToNumberStart`. Both `W20` and `W22` call into the SAME `subtree_invertNumber`. This de-duplication is invisible in alpha.1's emit (it emits two `goToNumberStart` and two `invertNumber` subgraphs).
+
+**Union-find didn't trigger** for minusOne because each bare's forward-reachable set is just itself (the bares transition either to halt or to other wrappers, never directly into each other's body states). Union-find applies to scenarios like the dispatcher+shared-X case, not chained compositions.
+
+## Reachability rules (what's inside the subtree)
+
+For each wrapped bare `A`, the callable subtree contains:
+- `A` itself.
+- Every state forward-reachable from `A` via its transitions, following `Reference#ref` transparently.
+- The synthesized halt-marker `c_A` (always emitted — see Edge cases for the dead-wrapper rationale).
+
+**Each state is rendered exactly once. Containers are computed via union-find on wrapper reachability:**
+
+1. **For each wrapped bare** `B`, compute `reach(B)` = forward-reachable set starting from B (following transitions and `Reference#ref` transparently).
+2. **Compute connected components** of wrappers by overlap: wrappers `W_i` and `W_j` are in the same component iff `reach(bare(W_i)) ∩ reach(bare(W_j)) ≠ ∅` (their reachable sets share at least one state). Transitive closure of the overlap relation.
+3. **Each connected component** becomes one **callable scope** (a subgraph frame in the emit). The frame contains: every state in the union of `reach(bare(W))` for all wrappers in the component, plus a single halt marker `c_union`.
+4. **States outside any wrapper's reach** stay at top level (e.g., dispatcher, override targets, real halt singleton, `idle`).
+
+Frame name: `callable subtree of <bare>` for a single-bare component; `callable scope: A ∪ B ∪ …` for multi-bare components.
+
+**Demand-emit rules** (refined):
+
+- `c_union` always present (orphan marker is the dead-wrapper signal — see Edge cases).
+- `frame -. return .-> W` emitted iff `c_union` has incoming edges AND wrapper W has a `call` arrow into the frame.
+- `frame -. halt .-> s0` emitted iff `c_union` has incoming edges AND there is **at least one solid `-->` arrow** entering any state inside the frame (a non-wrapper entry path).
+
+Cross-subgraph arrows are allowed and natural — Mermaid supports arrows whose source and target sit in different subgraph blocks. A state in the union frame may be the target of an arrow from outside (dispatcher → X, e.g.), or the source of an arrow to outside (frame member → wrapper override target).
+
+**No per-context duplication.** Today's v7 alpha.1 duplicates shared bares (e.g., `library-binary-numbers/minusOne` shows `invertNumber` as both `s20` and `s22` in its emit). Under the callable-subtree model, there's a single `subtree_invertNumber` and both wrappers `call ==>` into it via the `&` syntax. The diagram is smaller and the runtime "same instance, multiple call sites" semantic is visualized exactly. No same-instance marking is needed because no node is duplicated.
+
+## Edge cases
+
+### `c_A` always emitted
+
+Every wrapped bare gets a `c_A(((halt)))` inside its subtree subgraph, even when:
+- The bare has no halt-bound transitions in its reachable set (dead wrapper — Reference cycle case).
+- The body has halt-bound transitions but none happen to land on `c_A` directly (e.g., halts via intermediate paths that exit the subtree).
+
+The orphan `c_A` (no incoming `--> c_A` edge) is a meaningful signal: "this wrapper's runtime scope never produces a halt — wrapper is dead code."
+
+### Self-wrapping (`A.wohs(A)`)
+
+Legal. Wrapper has two arrows to A: bold `call` + solid `-->` (override target). Runtime: "run A twice in sequence." See Example 3.
+
+### Override target is itself a wrapper
+
+`W = A.wohs(W2)` where `W2 = B.wohs(target)`. W's outgoing to its override `W2` is a regular solid `--> s_W2` (the new convention reserves bold for wrapper-to-bare only). The reader sees W2's `[[…]]` shape and knows it's a wrapper. W2 in turn has its own bold `s_W2 == call ==> s_B` arrow into its own subtree. So the chain reads as: regular transition into a wrapper (solid), then that wrapper's bold call into its bare. Two bold arrows total (one per wrapper), regardless of how composition chains together.
+
+### Nested `.wohs()` chain (`A.wohs(t1).wohs(t2)`)
+
+Single wrapper emitted (outermost). Composite name accumulates the chain (`A(t1)(t2)`). Per probe finding, only `t2` actually fires at runtime; `t1` is overwritten. The composite name is technically misleading but matches engine v7 alpha.1's `state.#name` value.
+
+### Shared body state (reachable from multiple subtrees)
+
+When X is reachable from multiple wrapped bares whose reach sets overlap, those wrappers are in the same connected component → one **union frame** containing both bares + the shared state + a single halt marker.
+
+**Worked example 1: no direct entry to X.** `dispatcher` reads `1` → `W1`, reads `2` → `W2`. `A → X`. `B → X`. `X` halts. `W1 = A.wohs(target_1)`, `W2 = B.wohs(target_2)`.
+
+`reach(A) = {A, X}` and `reach(B) = {B, X}` overlap on X → union component {W1, W2} → one frame containing {A, B, X, c_union}.
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_disp["dispatcher"]
+  s_target1["target_1"]
+  s_target2["target_2"]
+  s_W1[["A(target_1)"]]
+  s_W2[["B(target_2)"]]
+
+  subgraph union_AB["callable scope: A ∪ B"]
+    s_A["A"]
+    s_B["B"]
+    s_X["X"]
+    c_union((("halt")))
+  end
+
+  s_W1 == call ==> s_A
+  s_W2 == call ==> s_B
+  union_AB -. return .-> s_W1
+  union_AB -. return .-> s_W2
+
+  s_W1 --> s_target1
+  s_W2 --> s_target2
+
+  idle -. enter .-> s_disp
+  s_disp -- "['1']" --> s_W1
+  s_disp -- "['2']" --> s_W2
+
+  s_A --> s_X
+  s_B --> s_X
+  s_X -- "[*]" --> c_union
+
+  s_target1 -- "[*]" --> s0
+  s_target2 -- "[*]" --> s0
+```
+
+X is inside the union frame. Both wrappers have `call` arrows to their respective bare entry points (W1 → A, W2 → B) — both bares live in the same scope. `c_union` has X's halt-bound transition landing on it.
+
+No `halt` arrow emitted — there's no solid `-->` entry into the union frame (only bold `call` from wrappers). The runtime never reaches `c_union` with an empty stack, so falling through to `s0` is structurally impossible.
+
+**Worked example 2: dispatcher adds direct entry to X (`['3'] → X`).** Now there's a non-wrapper entry into the union frame.
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TB
+  s0((("halt")))
+  idle([idle])
+  s_disp["dispatcher"]
+  s_target1["target_1"]
+  s_target2["target_2"]
+  s_W1[["A(target_1)"]]
+  s_W2[["B(target_2)"]]
+
+  subgraph union_AB["callable scope: A ∪ B"]
+    s_A["A"]
+    s_B["B"]
+    s_X["X"]
+    c_union((("halt")))
+  end
+
+  s_W1 == call ==> s_A
+  s_W2 == call ==> s_B
+  union_AB -. return .-> s_W1
+  union_AB -. return .-> s_W2
+  union_AB -. halt .-> s0
+
+  s_W1 --> s_target1
+  s_W2 --> s_target2
+
+  idle -. enter .-> s_disp
+  s_disp -- "['1']" --> s_W1
+  s_disp -- "['2']" --> s_W2
+  s_disp -- "['3']" --> s_X
+
+  s_A --> s_X
+  s_B --> s_X
+  s_X -- "[*]" --> c_union
+
+  s_target1 -- "[*]" --> s0
+  s_target2 -- "[*]" --> s0
+```
+
+Cross-subgraph entry `s_disp -- ['3'] --> s_X` triggers the `halt` arrow to emit. All three runtime paths from dispatcher are now traceable: `1` → W1 → call → halt at c_union → return W1 → target_1 → s0; `2` → W2 analogously; `3` → directly to X (inside union) → halt at c_union → empty-stack `halt` arrow → s0.
+
+The union model degrades gracefully — adding direct entry to a state inside the union just flips the `halt` arrow on. No new structural concept needed.
+
+## Data model changes
+
+The callable-subtree model **un-collapses what v7 alpha.1 collapsed**. In alpha.1, each `withOverriddenHaltState` wrapper produces ONE `GraphNode` representing both the wrapper and its bare (the bare is "collapsed onto" the wrapper's id, with `isWrapped: true`). Under the new model, **wrappers and bares are separate `GraphNode` instances**:
+
+- **Bare node** (`isWrapper: false`, regular `["…"]` shape) — lives inside its callable subtree. There's exactly one bare node per unique wrapped `State` instance.
+- **Wrapper node** (`isWrapper: true`, `[[…]]` shape, has `bareStateId: number`) — lives outside any subtree. There's one wrapper node per `withOverriddenHaltState` call. Multiple wrappers can share the same `bareStateId` if they wrap the same bare with different override targets.
+- **Halt marker** (`isHaltMarker: true`, `(((halt)))` shape inside subtree) — one per subtree, retargets the bare's halt-bound transitions.
+
+`GraphNode` field changes (proposed names; subject to implementation):
+
+| Field | alpha.1 | New model |
+|---|---|---|
+| `isWrapped: boolean` | True for collapsed-wrapper nodes | **Renamed/repurposed:** drop in favor of `isWrapper: boolean` |
+| `isWrapper: boolean` | n/a | True for external `[[…]]` wrapper nodes |
+| `bareStateId: number \| null` | n/a | Set on wrappers; points to the bare's `GraphNode` id |
+| `frameId: number \| null` | n/a (P1 added it; superseded) | Set on bare, body states, and halt marker — the id of the containing subtree |
+| `isHaltMarker: boolean` | True for synthesized halt markers | Same |
+| `overriddenHaltStateId: number \| null` | Set on collapsed-wrapper nodes (= override target's id) | Set on wrapper nodes |
+
+**`State.toGraph` second pass** (the reachability + frame-assignment + halt-retargeting work):
+
+- Pass 1 enumerates `State`s reachable from the initial state. For each State:
+  - If the State is wrapped (`#overriddenHaltState !== null` AND `#bareState !== null`): produce TWO nodes — a wrapper node (`isWrapper: true`, with the wrapper's id and composite name) AND a bare node (regular, with the bare's id and name) IF the bare doesn't already have a graph node from another wrapper context.
+  - If the State is not wrapped: produce one regular node.
+- Pass 2 assigns `frameId` via union-find on bare reachability: each unique bare's forward-reachable set (following the bare's transitions and `Reference#ref` transparently) defines its candidate subtree. When two bares' reach sets overlap, they merge into one union frame. Each frame gets a single halt marker.
+- Halt-bound transitions of any in-frame state retarget to the frame's halt marker.
+
+`Graph` itself: no structural change beyond the per-node field additions.
+
+## Emit changes
+
+### `toMermaid`
+
+- Subgraph emission unchanged in shape (`subgraph w_N["callable subtree of NAME"]` with bare + body + halt marker inside).
+- **Frame-level outgoing arrows** added: for each wrapped subtree, emit:
+  - One `subtree_N -. return .-> wrapper_id` per wrapper that calls this subtree.
+  - One `subtree_N -. halt .-> s0` always.
+- **Wrapper's `onHalt` edge removed.** Replaced by a solid `--> override_id` regular transition — always solid, regardless of whether the override is a wrapper (the new convention reserves bold for wrapper-to-bare `call` arrows only; the reader identifies the override as a wrapper, if it is one, by its `[[…]]` shape).
+- **`call` label** added to bold arrows entering a wrapped subtree. The `&` multi-source syntax groups multiple wrappers sharing a bare into one ribbon.
+- **Same-instance class assignments** if Option B/C selected.
+
+### `fromMermaid`
+
+- Parse subgraph membership → set `frameId` on nodes inside (already done in current draft).
+- Parse `-. return .->` and `-. halt .->` arrows → no Graph data change needed (these are derivable from frame membership and structure at emit time, OR stored as a separate field). **TBD.**
+- Parse `== call ==>` arrows: regular transitions whose target is a wrapper. Already handled.
+
+### `fromGraph`
+
+Unchanged. Frame membership and return/halt arrows are visualization concerns; runtime reconstruction reads `transitions` and `overriddenHaltStateId` from each node and builds State instances.
+
+## Round-trip
+
+`toGraph → toMermaid → fromMermaid → toGraph`:
+- Data model survives if `frameId` is preserved across round-trip (already done).
+- **TBD:** verify `library-binary-numbers/minusOne` round-trips byte-stable. Since the new model eliminates per-context duplication, the previous "shared-bare ordering" caveat is gone — `minusOne` should be cleaner under the new emit.
+
+## Implementation outline
+
+1. **Revert previous implementation** (the exclusive-only `frameId` pass in `State.toGraph` and the toMermaid grouping). Keep the `frameId` field on `GraphNode`; reuse it under the new semantics.
+2. **Two-pass `State.toGraph`:**
+   - Pass 1: build raw nodes (current).
+   - Pass 2 (new): for each wrapper, compute the full forward-reachable set from its bare. For each in-set node, assign `frameId = wrapper.id`. For each in-set state's halt-bound transition, retarget to the wrapper's halt marker.
+   - Each `State` → exactly one `GraphNode`. When a state would belong to multiple subtrees, assign it to the innermost (deepest-nested) containing subtree. External references become cross-subgraph arrows at emit time.
+3. **`toMermaid` rewrite of the subgraph emission:**
+   - Group nodes by `frameId`.
+   - Emit `subgraph w_${id}["callable subtree of NAME"]` per group.
+   - Emit `subtree_N -. return .-> wrapper_id` per wrapper that calls the subtree (derive from which wrappers' bareState produces this subtree).
+   - Emit `subtree_N -. halt .-> s0`.
+   - Wrapper's outgoing → override: solid `-->`, always. (Bold `==>` is reserved for the wrapper's `call` into its own bare.)
+4. **`fromMermaid`:** track subgraph membership (already done); parse `return` and `halt` arrows as needed; parse `call` arrows as regular bold transitions.
+5. **Tests:** Examples 1–5 above as regression cases. Existing wrapper-emission tests will need updates.
+6. **Regenerate `library-binary-numbers*/states.md`** and verify visual sanity, especially `minusOne`.
+7. **Update docs:** engine `CLAUDE.md`, `README.md`, this spec to IMPLEMENTED status.
+
+## Resolved questions
+
+### `return`/`halt` arrow storage
+
+**Decision: derive at emit time.** `toMermaid` computes `return` and `halt` arrows from frame membership + transitions; no new fields on `Graph` or `GraphNode` beyond `frameId`.
+
+Rationale:
+- Data model stays lean — single source of truth (frame structure + transitions) drives the arrows.
+- Round-trip stability is automatic: as long as `toGraph` is deterministic on `frameId` assignment (which it is per the union-find rule), `toGraph → toMermaid → fromMermaid → toGraph` produces bytewise-identical Mermaid on the second `toMermaid` call. The arrows are recomputed from the (identical) underlying structure.
+- `fromMermaid` parses `return`/`halt` arrows but doesn't need to persist them in graph data — they're re-derived on the next emit. (Minor parse-then-discard cost; offset by the smaller data model.)
+- Hand-edited Mermaid with inconsistent arrows is already explicitly unsupported per the engine's strict-format policy (`fromMermaid` is strict to the dialect `toMermaid` emits).
+
+### `onHalt` keyword retirement
+
+**Decision: retire the `onHalt` label and dotted style for wrapper-to-override edges.** The new model uses a regular solid `-->` arrow from wrapper to its override target — it's just a transition under the function-call mental model ("what fires after the call returns"). No special label needed.
+
+The dotted `-.->` style is now exclusively reserved for **frame-level dispatch arrows**: `return` (subtree → wrapper), `halt` (subtree → real halt), and `enter` (idle → initial state).
+
+Migration notes for the next prerelease:
+- **CHANGELOG entry** — note the format change. Mermaid strings emitted by v7 alpha.1 (containing `-. onHalt .->` edges) will not parse with the new `fromMermaid`. One-way migration.
+- **Engine `README.md`** — remove the "Edge arrow styles" reference to `-. onHalt .->`; replace with the new convention table.
+- **Engine `CLAUDE.md`** — update the "v7 emit shape" paragraph to reflect the callable-subtree model + new arrow conventions.
+- **`packages/library-binary-numbers*/states.md`** — regenerate via `npm run docs:states` after implementation lands; visual check on `minusOne` confirms the new shape reads well.
+
+## Open questions
+
+(None remaining; all design decisions resolved. Implementation details for `State.toGraph` un-collapsing, backward-compat strategy for alpha.1 Mermaid strings, and PR-shape decisions are captured in the [Implementation outline](#implementation-outline) and the related issues turing#175, turing#176, post-machine-js#85.)

From 0a218ac3ee89c173004031cba82d99be8ef91810 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 06:47:26 +0300
Subject: [PATCH 016/118] fix(State): nested `.wohs()` collapses inner
 overrides (#176)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`A.wohs(t1).wohs(t2)` now produces a wrapper with name `A(t2)` and bare
= A (not "A(t1)(t2)" with bare = W1). The chain's inner overrides are
dead at runtime — only the outermost `.wohs()`'s override is pushed
onto the halt-stack on entry (verified empirically by probe). The
composite name now reflects runtime behavior, not construction history.

Implementation is a single-line change: `withOverriddenHaltState`
unwraps `this` to its bare before composing the new wrapper.

Tests:
- New: `A.wohs(t1).wohs(t2).name === 'A(t2)'`, structural equivalence
  to `A.wohs(t2)` (same name + same override target).
- New: 3-deep chain `A.wohs(t1).wohs(t2).wohs(t3) → 'A(t3)'`.
- Updated: the existing "paren-naming distinguishes nestings" test
  now exercises only override-side wrapping (`outer1 = A.wohs(B.wohs(A))`),
  since `this`-side chain construction collapses under the new rule.

Composes with #175 (memoization): with both shipped, `A.wohs(t1).wohs(t2)
=== A.wohs(t2)` (literal reference equality via cache lookup).

states.md for library-binary-numbers libraries unchanged — those
compositions use independent wrappers, not chained `.wohs()` calls.

closes #176
---
 packages/machine/src/classes/State.spec.ts | 48 ++++++++++++++++++----
 packages/machine/src/classes/State.ts      | 14 +++++--
 2 files changed, 49 insertions(+), 13 deletions(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 3c16b0a..d587c8d 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -188,22 +188,52 @@ describe('State.withOverriddenHaltState', () => {
     expect(wrapped.name).toBe('inner(outer)');
   });
 
-  test('paren-naming distinguishes nestings that flat `>` notation would collide', () => {
+  test('paren-naming distinguishes wrapping where the override is itself wrapped', () => {
     const A = new State({[ifOtherSymbol]: {}}, 'A');
     const B = new State({[ifOtherSymbol]: {}}, 'B');
 
-    // Construction 1: bare=A, override=(B with override A)
+    // bare=A, override=(B with override A) — outer1 = A.wohs(B.wohs(A))
+    // Under #176, only `this` is unwrapped; the override (B.wohs(A)) is preserved as-is.
     const inner1 = B.withOverriddenHaltState(A);
     const outer1 = A.withOverriddenHaltState(inner1);
 
-    // Construction 2: bare=(A with override B), override=A
-    const inner2 = A.withOverriddenHaltState(B);
-    const outer2 = inner2.withOverriddenHaltState(A);
-
-    // Old `>` notation would collide both at "A>B>A". Paren notation keeps them distinct.
     expect(outer1.name).toBe('A(B(A))');
-    expect(outer2.name).toBe('A(B)(A)');
-    expect(outer1.name).not.toBe(outer2.name);
+    expect(outer1.overriddenHaltState).toBe(inner1);
+  });
+
+  test('nested `.wohs()` chain collapses inner overrides (#176)', () => {
+    // `A.wohs(t1).wohs(t2)` is equivalent to `A.wohs(t2)` — t1 is dead at
+    // runtime (only the outermost wohs's override is pushed onto the stack
+    // when the wrapper is entered; verified empirically by probe). The
+    // composite name reflects the runtime behavior, not construction history.
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const t1 = new State({[ifOtherSymbol]: {}}, 't1');
+    const t2 = new State({[ifOtherSymbol]: {}}, 't2');
+
+    const W1 = A.withOverriddenHaltState(t1);
+    const W2 = W1.withOverriddenHaltState(t2);
+
+    // Composite name: outer override only, inner ('t1') dropped.
+    expect(W2.name).toBe('A(t2)');
+    expect(W2.overriddenHaltState).toBe(t2);
+
+    // Structurally equivalent to direct construction.
+    const W2direct = A.withOverriddenHaltState(t2);
+
+    expect(W2.name).toBe(W2direct.name);
+    expect(W2.overriddenHaltState).toBe(W2direct.overriddenHaltState);
+  });
+
+  test('3-deep `.wohs()` chain collapses to outermost override (#176)', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const t1 = new State({[ifOtherSymbol]: {}}, 't1');
+    const t2 = new State({[ifOtherSymbol]: {}}, 't2');
+    const t3 = new State({[ifOtherSymbol]: {}}, 't3');
+
+    const W = A.withOverriddenHaltState(t1).withOverriddenHaltState(t2).withOverriddenHaltState(t3);
+
+    expect(W.name).toBe('A(t3)');
+    expect(W.overriddenHaltState).toBe(t3);
   });
 });
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index a91605d..03776a7 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -280,11 +280,17 @@ export default class State {
     // private-field access (legal within the same class).
     const state = new State();
 
-    state.#name = `${this.name}(${overriddenHaltState.name})`;
-    state.#symbolToDataMap = this.#symbolToDataMap;
+    // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
+    // are dead at runtime anyway (only the outermost `.wohs()`'s override is
+    // pushed onto the halt-stack on entry; verified empirically). Composite
+    // name reflects runtime behavior, not construction history. See #176.
+    const bare = this.#bareState ?? this;
+
+    state.#name = `${bare.name}(${overriddenHaltState.name})`;
+    state.#symbolToDataMap = bare.#symbolToDataMap;
     state.#overriddenHaltState = overriddenHaltState;
-    state.#debugRef = this.#debugRef;
-    state.#bareState = this;
+    state.#debugRef = bare.#debugRef;
+    state.#bareState = bare;
 
     return state;
   }

From 15677cf69a7bfaec937032be68283ea7aa826c62 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 07:02:36 +0300
Subject: [PATCH 017/118] feat(State): memoize withOverriddenHaltState (#175)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cache `(bare, override) → wrapper` so identical arguments return the
same JS instance. `A.wohs(t) === A.wohs(t)` — referential equality
holds for repeated wrap calls.

Composes with #176 (chained-`wohs()` collapse):
- #176 unwraps `this` to its bare on each `.wohs()` call.
- This cache then keys by `(bare, override)`.
- Result: `A.wohs(t1).wohs(t2) === A.wohs(t2)` — chained construction
  hits the same cache slot as direct construction.

Implementation:
- Static private cache `State.#wrapperCache: WeakMap<bare, WeakMap<override, WeakRef<wrapper>>>`.
- Two-level WeakMap so the outer entry is GC'd when the bare is
  collected; WeakRef values let wrappers themselves be GC'd when
  nothing else references them, with subsequent calls reconstructing
  fresh wrappers.
- Cache lookup happens BEFORE constructing a new wrapper; cache miss
  falls through to the existing construction path.

Tooling:
- Bumped `lib` to `ES2021` (was implied `ES2020`) for `WeakRef`. Target
  stays `ES2020` — emit is unchanged.

Tests:
- `A.wohs(t) === A.wohs(t)` (same instance, same id).
- `A.wohs(t1).wohs(t2) === A.wohs(t2)` (composes with #176).
- Different override → different instance (cache key sanity).
- Different bare → different instance (cache key sanity).

Full suite: 437/437 (was 433 + 4 new). Coverage above floors.

closes #175
---
 packages/machine/src/classes/State.spec.ts | 54 ++++++++++++++++++++++
 packages/machine/src/classes/State.ts      | 42 ++++++++++++++---
 tsconfig.json                              |  1 +
 3 files changed, 91 insertions(+), 6 deletions(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index d587c8d..7067cfe 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -224,6 +224,60 @@ describe('State.withOverriddenHaltState', () => {
     expect(W2.overriddenHaltState).toBe(W2direct.overriddenHaltState);
   });
 
+  test('memoization: same (bare, override) pair returns the same wrapper instance (#175)', () => {
+    // `withOverriddenHaltState` interns its results keyed by (bare, override).
+    // Two calls with the same arguments — even with chained construction —
+    // return the literally same JS object.
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const t = new State({[ifOtherSymbol]: {}}, 't');
+
+    const W1 = A.withOverriddenHaltState(t);
+    const W2 = A.withOverriddenHaltState(t);
+
+    expect(W1).toBe(W2);
+    expect(W1.id).toBe(W2.id);
+    expect(W1.name).toBe('A(t)');
+  });
+
+  test('memoization composes with chain collapse: A.wohs(t1).wohs(t2) === A.wohs(t2) (#175 + #176)', () => {
+    // After #176 collapses the chain to (A, t2), the cache hit on (A, t2)
+    // returns the same instance as the direct call.
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const t1 = new State({[ifOtherSymbol]: {}}, 't1');
+    const t2 = new State({[ifOtherSymbol]: {}}, 't2');
+
+    const Wdirect = A.withOverriddenHaltState(t2);
+    const Wchained = A.withOverriddenHaltState(t1).withOverriddenHaltState(t2);
+
+    expect(Wchained).toBe(Wdirect);
+  });
+
+  test('memoization is per-(bare, override) pair: different override → different instance (#175)', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const t1 = new State({[ifOtherSymbol]: {}}, 't1');
+    const t2 = new State({[ifOtherSymbol]: {}}, 't2');
+
+    const W1 = A.withOverriddenHaltState(t1);
+    const W2 = A.withOverriddenHaltState(t2);
+
+    expect(W1).not.toBe(W2);
+    expect(W1.name).toBe('A(t1)');
+    expect(W2.name).toBe('A(t2)');
+  });
+
+  test('memoization is per-(bare, override) pair: different bare → different instance (#175)', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const B = new State({[ifOtherSymbol]: {}}, 'B');
+    const t = new State({[ifOtherSymbol]: {}}, 't');
+
+    const W_A = A.withOverriddenHaltState(t);
+    const W_B = B.withOverriddenHaltState(t);
+
+    expect(W_A).not.toBe(W_B);
+    expect(W_A.name).toBe('A(t)');
+    expect(W_B.name).toBe('B(t)');
+  });
+
   test('3-deep `.wohs()` chain collapses to outermost override (#176)', () => {
     const A = new State({[ifOtherSymbol]: {}}, 'A');
     const t1 = new State({[ifOtherSymbol]: {}}, 't1');
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 03776a7..a254aad 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -72,6 +72,13 @@ export class DebugConfig {
 }
 
 export default class State {
+  // Memoization cache for `withOverriddenHaltState`. Keyed by
+  // (bare, override) — same args return the same wrapper instance (#175).
+  // Two-level WeakMap so the outer entry is GC'd when the bare is collected;
+  // WeakRef values let wrappers themselves be GC'd when nothing else holds
+  // them, with cache misses simply reconstructing fresh wrappers.
+  static #wrapperCache = new WeakMap<State, WeakMap<State, WeakRef<State>>>();
+
   readonly #id: number = id(this);
 
   // Not `readonly` because `withOverriddenHaltState` and `fromGraph` set the
@@ -274,24 +281,47 @@ export default class State {
   }
 
   withOverriddenHaltState(overriddenHaltState: State) {
-    // Construct with no name, then overwrite #name directly — the composed
-    // name contains `(` and `)` by design, which the constructor's user-facing
-    // validation would reject. Internal composition bypasses validation via
-    // private-field access (legal within the same class).
-    const state = new State();
-
     // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
     // are dead at runtime anyway (only the outermost `.wohs()`'s override is
     // pushed onto the halt-stack on entry; verified empirically). Composite
     // name reflects runtime behavior, not construction history. See #176.
     const bare = this.#bareState ?? this;
 
+    // Memoize by (bare, override) so identical args return the same instance
+    // (#175). The cache uses WeakMaps + WeakRefs so cached wrappers can be
+    // GC'd when nothing else holds them. Compounds with the chain-collapse
+    // above: `A.wohs(t1).wohs(t2)` keys as (A, t2) after the unwrap, hitting
+    // the same cache slot as a direct `A.wohs(t2)`.
+    let innerCache = State.#wrapperCache.get(bare);
+
+    if (innerCache !== undefined) {
+      const ref = innerCache.get(overriddenHaltState);
+
+      if (ref !== undefined) {
+        const cached = ref.deref();
+
+        if (cached !== undefined) {
+          return cached;
+        }
+      }
+    } else {
+      innerCache = new WeakMap();
+      State.#wrapperCache.set(bare, innerCache);
+    }
+
+    // Cache miss — construct with no name, then overwrite #name directly
+    // (composed names contain `(` and `)` which the constructor's user-facing
+    // validation would reject; private-field access bypasses that).
+    const state = new State();
+
     state.#name = `${bare.name}(${overriddenHaltState.name})`;
     state.#symbolToDataMap = bare.#symbolToDataMap;
     state.#overriddenHaltState = overriddenHaltState;
     state.#debugRef = bare.#debugRef;
     state.#bareState = bare;
 
+    innerCache.set(overriddenHaltState, new WeakRef(state));
+
     return state;
   }
 
diff --git a/tsconfig.json b/tsconfig.json
index 8df6553..8bfc4c0 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -3,6 +3,7 @@
   "compilerOptions": {
     "target": "ES2020",
     "module": "ES2020",
+    "lib": ["ES2021"],
     "declaration": true,
     "strict": true,
     "moduleResolution": "node",

From d7bc40beaa7e1634283638098fa870de2d186a51 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 07:28:17 +0300
Subject: [PATCH 018/118] chore(graph): add isWrapper/bareStateId/frameId to
 GraphNode (Phase 1 of #174)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Additive data-model changes for the callable-subtree visualization
refactor. No behavior change — new fields default to sensible values
(isWrapper: false, bareStateId: null, frameId: null) everywhere they
currently appear.

Existing fields retained for backward-compat during cutover:
- `isWrapped` remains as the alpha.1 collapsed-bare flag; will be
  dropped once toGraph/toMermaid stop reading it.

New fields wire the un-collapsed model (next phases):
- `isWrapper`: true for external `[[…]]` wrapper nodes (separate from
  their bare).
- `bareStateId`: on wrappers, points to the bare's GraphNode id.
- `frameId`: bare/body/halt-marker membership in a callable subtree.

Touched sites:
- Type definition in `graph.ts`.
- 4 node-creation sites in `State.toGraph`.
- `ensureNode` in `fromMermaid`.
- ~30 hand-built GraphNode fixtures across the three spec files (bulk
  search-replace, mechanical).

Tests: 437/437 still pass. Coverage above floors. Lint + typecheck
clean.

Refs #174.
---
 packages/machine/src/classes/State.spec.ts    |  6 ++--
 packages/machine/src/classes/State.ts         | 12 ++++++++
 packages/machine/src/utilities/graph.spec.ts  | 18 ++++++------
 packages/machine/src/utilities/graph.ts       | 26 +++++++++++++++--
 .../machine/src/utilities/graphFormats.ts     |  9 ++++++
 .../src/utilities/introspection.spec.ts       | 28 +++++++++----------
 6 files changed, 71 insertions(+), 28 deletions(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 7067cfe..1282f7f 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -345,9 +345,9 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index a254aad..795a776 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -435,6 +435,9 @@ export default class State {
             isHalt: true,
             isHaltMarker: false,
             isWrapped: false,
+            isWrapper: false,
+            bareStateId: null,
+            frameId: null,
             transitions: [],
             overriddenHaltStateId: null,
           };
@@ -470,6 +473,9 @@ export default class State {
             isHalt: true,
             isHaltMarker: true,
             isWrapped: false,
+            isWrapper: false,
+            bareStateId: null,
+            frameId: null,
             transitions: [],
             overriddenHaltStateId: null,
           };
@@ -482,6 +488,9 @@ export default class State {
           isHalt: false,
           isHaltMarker: false,
           isWrapped: true,
+          isWrapper: false,
+          bareStateId: null,
+          frameId: null,
           transitions: [],
           overriddenHaltStateId: overrideGraphId,
         };
@@ -553,6 +562,9 @@ export default class State {
         isHalt: false,
         isHaltMarker: false,
         isWrapped: false,
+        isWrapper: false,
+        bareStateId: null,
+        frameId: null,
         transitions: [],
         overriddenHaltStateId: null,
       };
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index f2efd9c..ee29183 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -118,9 +118,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [
             {pattern: "'0'", command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
             {pattern: "'1'", command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
@@ -144,8 +144,8 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
-        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     });
 
@@ -157,9 +157,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
-        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
-        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     });
 
@@ -171,9 +171,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0'], [' ', 'a']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [{
             pattern: "'0','a'",
             command: [{symbol: "'0'", movement: 'R'}, {symbol: "'a'", movement: 'L'}],
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index e7ae37e..7f9a7a8 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -20,9 +20,31 @@ export type GraphNode = {
   transitions: GraphTransition[];
   overriddenHaltStateId: number | null;
   // `true` when this node represents the bare of a `withOverriddenHaltState`-
-  // wrapped state. Carries the `[[…]]` (subroutine) shape signal for `toMermaid`
-  // and tells `fromGraph` to reconstruct via `bare.withOverriddenHaltState(target)`.
+  // wrapped state under v7 alpha.1's collapsed emit. Carries the `[[…]]`
+  // (subroutine) shape signal for `toMermaid` and tells `fromGraph` to
+  // reconstruct via `bare.withOverriddenHaltState(target)`. The new
+  // un-collapsed model (#174) supersedes this with `isWrapper` + `bareStateId`
+  // below; `isWrapped` is retained transitionally for backward-compat during
+  // the cutover.
   isWrapped: boolean;
+  // New (#174): `true` for external `[[…]]` wrapper nodes that have a
+  // separate bare node in the graph. The wrapper sits outside any subtree
+  // subgraph; its `bareStateId` points to the corresponding bare GraphNode
+  // (which lives inside its home subtree). Multiple wrapper nodes can share
+  // the same `bareStateId` when they wrap the same bare with different
+  // override targets. Under the new model, `isWrapped: false` for these
+  // nodes — the wrapper-vs-bare distinction is carried by `isWrapper`.
+  isWrapper: boolean;
+  // New (#174): on wrapper nodes (`isWrapper: true`), the id of the bare
+  // GraphNode this wrapper wraps. `null` for non-wrapper nodes.
+  bareStateId: number | null;
+  // New (#174): the id of the wrapper whose callable subtree this node lives
+  // in. `null` for nodes outside any subtree (top-level states, real halt
+  // singleton, wrapper nodes themselves, the `idle` visualization sentinel).
+  // Set on bares, body states, and halt markers. Two bares may share a
+  // `frameId` when union-find merges their reachable sets (shared body state
+  // forces a union frame; see spec Example "Shared body state").
+  frameId: number | null;
   // `true` for a synthesized halt marker graph node — one per wrapper context.
   // Real halt has `isHalt: true, isHaltMarker: false`; halt markers have both
   // `true`. `fromGraph` maps halt-marker nodes back to the singleton `haltState`.
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 79fdefe..e90e144 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -206,6 +206,9 @@ export function fromMermaid(text: string): Graph {
       isHalt?: boolean;
       isHaltMarker?: boolean;
       isWrapped?: boolean;
+      isWrapper?: boolean;
+      bareStateId?: number | null;
+      frameId?: number | null;
     } = {},
   ): GraphNode => {
     if (!nodes[id]) {
@@ -215,6 +218,9 @@ export function fromMermaid(text: string): Graph {
         isHalt: opts.isHalt ?? false,
         isHaltMarker: opts.isHaltMarker ?? false,
         isWrapped: opts.isWrapped ?? false,
+        isWrapper: opts.isWrapper ?? false,
+        bareStateId: opts.bareStateId ?? null,
+        frameId: opts.frameId ?? null,
         transitions: [],
         overriddenHaltStateId: null,
       };
@@ -223,6 +229,9 @@ export function fromMermaid(text: string): Graph {
       if (opts.isHalt !== undefined) nodes[id].isHalt = opts.isHalt;
       if (opts.isHaltMarker !== undefined) nodes[id].isHaltMarker = opts.isHaltMarker;
       if (opts.isWrapped !== undefined) nodes[id].isWrapped = opts.isWrapped;
+      if (opts.isWrapper !== undefined) nodes[id].isWrapper = opts.isWrapper;
+      if (opts.bareStateId !== undefined) nodes[id].bareStateId = opts.bareStateId;
+      if (opts.frameId !== undefined) nodes[id].frameId = opts.frameId;
     }
 
     return nodes[id];
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index edb858d..5aea059 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -7,9 +7,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
             {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
@@ -31,9 +31,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
           ],
@@ -52,9 +52,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [{pattern: '0', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
         },
       },
@@ -72,10 +72,10 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isWrapped: false, isHaltMarker: false},
-        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 
@@ -90,8 +90,8 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 
@@ -197,8 +197,8 @@ describe('summarizeGraph defensive guards', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 

From 6d74f757031eb1774a0366b938033c564733b2d1 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 08:07:40 +0300
Subject: [PATCH 019/118] feat(graph): callable-subtree emit for
 withOverriddenHaltState (#174)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`withOverriddenHaltState` is now modeled as a function call in the
graph emit: the wrapper is a `[[composite-name]]` call site OUTSIDE
any subgraph, the bare's reachable subtree becomes a
`subgraph w_${frameId}["callable subtree of NAME"] … end` block
containing the bare + body states + a per-frame halt marker.

Frames computed via union-find on bare-reachability: overlapping
reach sets merge into a single union frame, so shared bares
(library-binary-numbers/minusOne's invertNumber, used by two
wrappers) appear ONCE with `& `-joined call arrows.

Arrow conventions:
- solid `-->` for regular transitions AND wrapper → override
- bold `==> "call"` reserved for wrapper-to-bare (`&` ribbons
  collapse multi-wrapper-shares-bare)
- dotted `-.->` reserved for frame-level dispatch:
  `w_N -. "return" .-> wrapper` (demand-emit: halt marker has
  incoming AND wrapper calls into the frame)
  `w_N -. "halt" .-> s0`     (demand-emit: halt marker has
  incoming AND non-wrapper entry exists into the frame)
- `-. onHalt .->` retired (replaced by solid `--> override`)

GraphNode field changes:
- drop `isWrapped` (the alpha.1 collapsed-bare flag)
- add `isWrapper: boolean` for external `[[…]]` wrapper nodes
- add `bareStateId: number | null` (on wrappers → bare's id)
- add `frameId: number | null` (subtree membership; canonical =
  smallest bare-id in union component)

Bytewise round-trip stability now holds for ALL wrapped states
including shared-bare cases (no per-context duplication).

Files touched:
- packages/machine/src/utilities/graph.ts — type changes
- packages/machine/src/classes/State.ts — toGraph rewrite
  (un-collapse + union-find + halt retargeting) and fromGraph
  rewrite (wrapper-aware reconstruction)
- packages/machine/src/utilities/graphFormats.ts — toMermaid +
  fromMermaid rewrite for the new shape
- Tests: removed `isWrapped: false` from ~26 hand-built fixtures;
  updated wrapper-context unbound-Reference test; updated cycle
  test to use isWrapper:true nodes; updated onHalt and
  scanThenErase README tests to new shape; updated 5
  library-binary-numbers state-count expectations
- Docs: engine README (regenerated example, rewrote reading
  guide, updated edge styles table, updated v7 trajectory);
  engine CLAUDE.md (v7 emit shape + edge styles paragraphs);
  root README (quick legend); spec doc (status IMPLEMENTED);
  regenerated library-binary-numbers/states.md

Verification:
- 437/437 tests pass
- lint clean
- coverage above all floors (97.49 stmts / 94.04 branches /
  98.85 funcs / 97.83 lines)

Closes #174 (carries on the release PR).
---
 CLAUDE.md                                     |   4 +-
 README.md                                     |   6 +-
 ...026-05-21-halt-frame-transitive-closure.md |   2 +-
 .../library-binary-numbers/src/graphs.spec.ts |  16 +-
 packages/library-binary-numbers/states.md     | 174 +++----
 packages/machine/README.md                    |  52 ++-
 packages/machine/src/classes/State.spec.ts    |  33 +-
 packages/machine/src/classes/State.ts         | 431 +++++++++++-------
 packages/machine/src/utilities/graph.spec.ts  |  44 +-
 packages/machine/src/utilities/graph.ts       |  52 +--
 .../machine/src/utilities/graphFormats.ts     | 417 ++++++++++-------
 .../src/utilities/introspection.spec.ts       |  28 +-
 12 files changed, 746 insertions(+), 513 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index e9ffd12..3484e13 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,11 +61,11 @@ Key shapes that take reading multiple files to grasp:
 
 `packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same `Graph` through [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) syntax (renderer: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)). The parser is strict to the dialect `toMermaid` emits — hand-edited Mermaid with different arrow styles or shapes won't round-trip.
 
-**v7 emit shape** (PR #169, closes #138/#139): each `withOverriddenHaltState` wrapper collapses onto its bare's representation — `GraphNode.isWrapped: true`, no separate wrapper node in graph data. `toMermaid` wraps each `[[bare]]` (subroutine shape) + a synthesized `(((halt)))` marker (`GraphNode.isHaltMarker: true`, negative id; maps back to singleton `haltState` in `fromGraph`) inside a `subgraph w_${bareId}["halt frame"] … end` block. Dotted `onHalt` from `[[bare]]` crosses the subgraph border to the override target. An always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state (replaces v6's `((round))` shape convention).
+**v7 callable-subtree emit shape** (#174, layered on the v7 alpha.1 framing from #138/#139): each `withOverriddenHaltState` wrapper produces TWO `GraphNode`s — a wrapper node (`isWrapper: true`, `[[composite-name]]` shape, no transitions, `bareStateId` points to the bare's GraphNode) and a bare node (regular `["name"]` shape inside its callable subtree subgraph, holds the bare's transitions). Frames are computed via union-find on bare-reachability: each unique bare's forward-reachable set defines its candidate frame; overlapping reach sets merge into a union frame. Frame id = smallest bare-id in the component. Halt marker per frame (id = `-frameId`, `isHaltMarker: true`, maps back to singleton `haltState` in `fromGraph`). Halt-bound transitions of in-frame states retarget to the frame's halt marker. Subgraph label: `"callable subtree of NAME"` (single bare) or `"callable scope: A ∪ B"` (union). The always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state. **No per-context duplication** — shared bares like `library-binary-numbers`'s `invertNumber` (in `minusOne`) appear once with `& `-joined call arrows from each wrapper.
 
 **Edge label vocabulary** — `[reads] → [writes]/[moves]`, each role wrapped in `[…]` (the tape-block indicator, one entry per tape; brackets always present, even single-tape). Read cells: literal-quoted (`'X'`), `*` (ASCII, ifOtherSymbol catch-all; literal `*` in the alphabet is quoted as `'*'`), `B` (the tape's blank). Write cells: literal-quoted, `K` (keep), `E` (erase = write blank). Move cells: `L` / `R` / `S`. **Alternation is always per-pattern bracket** (`['^']|['1']|['0']` for single-tape, `['0','a']|['1','b']` for multi-tape); the compact in-bracket form `['^'|'1']` is rejected by `fromMermaid` to prevent the cross-product reading trap in multi-tape (`['0'|'1','a'|'b']` would read as 4 combinations rather than 2 paired alternatives, so the format avoids the shape entirely).
 
-**Edge arrow styles** — thick `==>` marks transitions whose target is a wrapped state AND ≠ source (= stack-push happens at runtime per `TuringMachine.run` line ~220); regular `-->` for the rest (including self-loops on wrappers, which don't push); dotted `-. onHalt .->` for the wrapper's catch-and-redirect; dotted `-. enter .->` from `idle` for execution-start.
+**Edge arrow styles** — solid `-->` for regular state-to-state transitions AND for the wrapper's post-return `--> override` (just an ordinary transition under the call/return mental model); bold `==> "call"` is RESERVED for the wrapper-to-bare call arrow (source: wrapper, target: its bare; `&` ribbon collapses multiple wrappers sharing a bare); dotted `-.->` for frame-level dispatch — `w_N -. "return" .-> wrapper` (demand-emit: only when the frame's halt marker has incoming edges AND a wrapper calls into the frame), `w_N -. "halt" .-> s0` (demand-emit: only when the frame has a non-wrapper entry path), and `idle -. enter .-> sN` for execution-start. **The `-. onHalt .->` keyword from v7 alpha.1 is retired** — wrapper-to-override is now just a regular solid arrow, and the dotted `-.->` style is reserved for frame-level dispatch.
 
 **Round-trip** is **bytewise stable for simple wrappers** (regression test in `test/round-trip.spec.ts` — #139). The wrapper's composite name (e.g. `scanToX(eraseHere)`) does NOT appear as a graph node label; only the bare's name does, so `fromGraph` recomputes the composite fresh on reconstruction — no accumulation. **Shared-bare cases** (same `State` instance used as the bare of multiple wrappers, e.g. `library-binary-numbers`'s `minusOne` where `invertNumber` is both the outermost bare AND wrapper-W1's bare) use **per-context duplication** in `toGraph`: each occurrence emits a separate graph node with the wrapper's `#id`. Reconstruction produces behaviorally-equivalent State instances (not necessarily the same runtime `#id`), but bytewise stability isn't guaranteed for shared-bare since duplicate ordering depends on runtime wrapper-ids that don't survive rebuild.
 
diff --git a/README.md b/README.md
index 1ed7fe7..e202688 100644
--- a/README.md
+++ b/README.md
@@ -94,9 +94,9 @@ Quick legend for the diagram above — full table at [packages/machine/README.md
 - **Read cells**: `'X'` (literal, single-quoted), `*` (`ifOtherSymbol` catch-all), `B` (the tape's blank).
 - **Write cells**: `'X'` (literal), `K` (keep), `E` (erase = write blank).
 - **Movement cells**: `L` / `R` / `S` (left / right / stay).
-- **Node shapes**: `(((halt)))` = halt, `["square"]` = regular state, `[[double-walled]]` = wrapper-bare (subroutine shape), `idle([idle])` = pre-execution sentinel.
-- **Edges**: `-->` regular, `==>` thick = transition into a wrapper (stack-push), `-. onHalt .->` = wrapper's catch-and-redirect, `-. enter .->` from `idle` = where execution starts.
-- **Subgraph `w_N["halt frame"]`** wraps a `[[bare]]` + its halt marker — see [§Subroutine composition](packages/machine/README.md#subroutine-composition-with-withoverriddenhaltstate) in the engine README.
+- **Node shapes**: `(((halt)))` = halt, `["square"]` = regular state or callable-subtree bare, `[[double-walled]]` = `withOverriddenHaltState` wrapper (call site), `idle([idle])` = pre-execution sentinel.
+- **Edges**: `-->` regular transition (and wrapper → override target), `==> "call"` = bold call arrow from wrapper to bare (`&` ribbons collapse multi-wrapper-shares-bare), `-. "return" .->` / `-. "halt" .->` from subgraph = frame-level dispatch, `-. enter .->` from `idle` = where execution starts.
+- **Subgraph `w_N["callable subtree of NAME"]`** wraps a bare + its body + a halt marker — see [§Subroutine composition](packages/machine/README.md#subroutine-composition-with-withoverriddenhaltstate) in the engine README.
 
 Trace on the input tape `abcba`:
 
diff --git a/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md b/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
index 6a163c3..959024f 100644
--- a/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
+++ b/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
@@ -1,6 +1,6 @@
 # Callable-subtree visualization for `withOverriddenHaltState`
 
-**Status:** DRAFT 2026-05-21 — supersedes the earlier "transitive-closure halt-frame" framing of this doc. Tracks [#174](https://github.com/mellonis/turing-machine-js/issues/174). Lands on the `v7` integration branch before v7 stable cut. **Previous implementation (frameId-based exclusive-reachable algorithm in `State.toGraph`) is being reverted in favor of the design below.**
+**Status:** IMPLEMENTED 2026-05-21 — design captured in PR #181 (Phase 1: data model) and the current PR (Phases 2–7: toGraph un-collapse + union-find + toMermaid + fromMermaid + fromGraph + tests + docs). Tracks [#174](https://github.com/mellonis/turing-machine-js/issues/174). Lands on the `v7` integration branch before v7 stable cut.
 
 **Relation to [#173](https://github.com/mellonis/turing-machine-js/issues/173):** #173 closed (2026-05-21) as the literal complaint (orphan `c_N` + onHalt anchor) doesn't apply to the new design — there's no `c_N` per-wrapper concept anymore. The new design has per-bare `c_A` halt sinks and per-wrapper call/return/onHalt edges, which together visualize runtime semantics directly.
 
diff --git a/packages/library-binary-numbers/src/graphs.spec.ts b/packages/library-binary-numbers/src/graphs.spec.ts
index c10938f..b1ccb6c 100644
--- a/packages/library-binary-numbers/src/graphs.spec.ts
+++ b/packages/library-binary-numbers/src/graphs.spec.ts
@@ -6,17 +6,23 @@ import binaryNumbers from './index';
 // which exclude the `isHaltMarker` visualization sentinels v7 synthesizes
 // inside each `halt frame` subgraph. The states.md per-algorithm header uses
 // the same definition, so all three sources agree by construction.
+// v7 callable-subtree counts (#174). Under the new model, each
+// `withOverriddenHaltState` emits a SEPARATE wrapper node (in addition to the
+// bare's node) — so wrapper-bearing algorithms gain 1 node per wrapper, minus
+// any savings from de-duplicating shared bares (no per-context duplication
+// anymore). `goToNumber`, `goToNextNumber`, `goToPreviousNumber`,
+// `goToNumbersStart`, `plusOne` have no wrappers and are unchanged.
 const expectedNodeCount: Record<keyof typeof binaryNumbers['states'], number> = {
   goToNumber: 2,
   goToNextNumber: 3,
   goToPreviousNumber: 3,
   goToNumbersStart: 2,
-  deleteNumber: 4,
-  invertNumber: 4,
-  normalizeNumber: 6,
+  deleteNumber: 5, // alpha.1: 4 (one wohs); +1 wrapper node
+  invertNumber: 5, // alpha.1: 4 (one wohs); +1 wrapper node
+  normalizeNumber: 7, // alpha.1: 6 (one wohs); +1 wrapper node
   plusOne: 5,
-  minusOne: 15,
-  minusOneFast: 8,
+  minusOne: 18, // alpha.1: 15; +3 for wrapper-vs-bare separation minus shared-bare dedup
+  minusOneFast: 10, // alpha.1: 8; +2 wrapper nodes
 };
 
 const stateNames = Object.keys(expectedNodeCount) as Array<keyof typeof expectedNodeCount>;
diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 31477a0..4d61d88 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -51,7 +51,7 @@ flowchart TD
 
 ## deleteNumber
 
-*4 states; 6 transitions; 1 wrapper (max nesting depth 1); has cycles*
+*5 states; 6 transitions; 1 wrapper (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -59,18 +59,21 @@ flowchart TD
   s0(((halt)))
   s6["deleteNumberInternal"]
   s8["deleteNumber"]
+  s7[["goToNumberStart(deleteNumberInternal)"]]
   idle([idle])
-  subgraph w_7["halt frame"]
-    s7[["goToNumberStart"]]
-    c7(((halt)))
+  subgraph w_5["callable subtree of goToNumberStart"]
+    s5["goToNumberStart"]
+    c5(((halt)))
   end
   idle -. enter .-> s8
+  s7 == "call" ==> s5
+  w_5 -. "return" .-> s7
+  s7 --> s6
+  s5 -- "['^'] → [K]/[S]" --> c5
+  s5 -- "[*] → [K]/[L]" --> s5
   s6 -- "['$'] → [E]/[S]" --> s0
   s6 -- "[*] → [E]/[R]" --> s6
-  s7 -- "['^'] → [K]/[S]" --> c7
-  s7 -- "[*] → [K]/[L]" --> s7
-  s7 -. onHalt .-> s6
-  s8 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s7
+  s8 -- "['^']|['1']|['0']|['$'] → [K]/[S]" --> s7
   s8 -- "[*] → [K]/[S]" --> s0
 ```
 
@@ -91,7 +94,7 @@ flowchart TD
 
 ## invertNumber
 
-*4 states; 8 transitions; 1 wrapper (max nesting depth 1); has cycles*
+*5 states; 8 transitions; 1 wrapper (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -99,26 +102,29 @@ flowchart TD
   s0(((halt)))
   s9["invertNumberGoToNumberWithInversion"]
   s11["invertNumber"]
+  s10[["goToNumberStart(invertNumberGoToNumberWithInversion)"]]
   idle([idle])
-  subgraph w_10["halt frame"]
-    s10[["goToNumberStart"]]
-    c10(((halt)))
+  subgraph w_5["callable subtree of goToNumberStart"]
+    s5["goToNumberStart"]
+    c5(((halt)))
   end
   idle -. enter .-> s11
+  s10 == "call" ==> s5
+  w_5 -. "return" .-> s10
+  s10 --> s9
+  s5 -- "['^'] → [K]/[S]" --> c5
+  s5 -- "[*] → [K]/[L]" --> s5
   s9 -- "['^'] → [K]/[R]" --> s9
   s9 -- "['1'] → ['0']/[R]" --> s9
   s9 -- "['0'] → ['1']/[R]" --> s9
   s9 -- "['$'] → [K]/[S]" --> s0
-  s10 -- "['^'] → [K]/[S]" --> c10
-  s10 -- "[*] → [K]/[L]" --> s10
-  s10 -. onHalt .-> s9
-  s11 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
+  s11 -- "['^']|['1']|['0']|['$'] → [K]/[S]" --> s10
   s11 -- "[*] → [K]/[S]" --> s0
 ```
 
 ## normalizeNumber
 
-*6 states; 9 transitions; 1 wrapper (max nesting depth 1); has cycles*
+*7 states; 9 transitions; 1 wrapper (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -128,21 +134,24 @@ flowchart TD
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
   s15["normalizeNumber"]
+  s14[["goToNumberStart(normalizeNumberMoveNumberStart)"]]
   idle([idle])
-  subgraph w_14["halt frame"]
-    s14[["goToNumberStart"]]
-    c14(((halt)))
+  subgraph w_5["callable subtree of goToNumberStart"]
+    s5["goToNumberStart"]
+    c5(((halt)))
   end
   idle -. enter .-> s15
+  s14 == "call" ==> s5
+  w_5 -. "return" .-> s14
+  s14 --> s13
   s1 -- "['$'] → [K]/[S]" --> s0
   s1 -- "[*] → [K]/[R]" --> s1
+  s5 -- "['^'] → [K]/[S]" --> c5
+  s5 -- "[*] → [K]/[L]" --> s5
   s12 -- "[B] → ['^']/[S]" --> s1
   s13 -- "['^']|['0'] → [E]/[R]" --> s13
   s13 -- "['1']|['$'] → [K]/[L]" --> s12
-  s14 -- "['^'] → [K]/[S]" --> c14
-  s14 -- "[*] → [K]/[L]" --> s14
-  s14 -. onHalt .-> s13
-  s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
+  s15 -- "['^']|['1']|['0']|['$'] → [K]/[S]" --> s14
   s15 -- "[*] → [K]/[S]" --> s0
 ```
 
@@ -174,7 +183,7 @@ flowchart TD
 
 ## minusOne
 
-*15 states; 32 transitions; 5 wrappers (max nesting depth 3); has cycles*
+*18 states; 28 transitions; 5 wrappers (max nesting depth 3); has cycles*
 
 ```mermaid
 flowchart TD
@@ -185,74 +194,73 @@ flowchart TD
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
   s15["normalizeNumber"]
-  s16["plusOneFillZeros"]
-  s17["plusOneAddNumberStart"]
-  s18["plusOneCaryOne"]
   s23["minusOne"]
+  s10[["goToNumberStart(invertNumberGoToNumberWithInversion)"]]
+  s14[["goToNumberStart(normalizeNumberMoveNumberStart)"]]
+  s20[["invertNumber(normalizeNumber)"]]
+  s21[["plusOne(invertNumber(normalizeNumber))"]]
+  s22[["invertNumber(plusOne(invertNumber(normalizeNumber)))"]]
   idle([idle])
-  subgraph w_10["halt frame"]
-    s10[["goToNumberStart"]]
-    c10(((halt)))
-  end
-  subgraph w_14["halt frame"]
-    s14[["goToNumberStart"]]
-    c14(((halt)))
+  subgraph w_5["callable subtree of goToNumberStart"]
+    s5["goToNumberStart"]
+    c5(((halt)))
   end
-  subgraph w_20["halt frame"]
-    s20[["invertNumber"]]
-    c20(((halt)))
+  subgraph w_11["callable subtree of invertNumber"]
+    s11["invertNumber"]
+    c11(((halt)))
   end
-  subgraph w_21["halt frame"]
-    s21[["plusOne"]]
-    c21(((halt)))
-  end
-  subgraph w_22["halt frame"]
-    s22[["invertNumber"]]
-    c22(((halt)))
+  subgraph w_19["callable subtree of plusOne"]
+    s16["plusOneFillZeros"]
+    s17["plusOneAddNumberStart"]
+    s18["plusOneCaryOne"]
+    s19["plusOne"]
+    c19(((halt)))
   end
   idle -. enter .-> s23
+  s10 & s14 == "call" ==> s5
+  s20 & s22 == "call" ==> s11
+  s21 == "call" ==> s19
+  w_5 -. "return" .-> s10 & s14
+  w_11 -. "return" .-> s20 & s22
+  w_19 -. "return" .-> s21
+  s10 --> s9
+  s14 --> s13
+  s20 --> s15
+  s21 --> s20
+  s22 --> s21
   s1 -- "['$'] → [K]/[S]" --> s0
   s1 -- "[*] → [K]/[R]" --> s1
+  s5 -- "['^'] → [K]/[S]" --> c5
+  s5 -- "[*] → [K]/[L]" --> s5
   s9 -- "['^'] → [K]/[R]" --> s9
   s9 -- "['1'] → ['0']/[R]" --> s9
   s9 -- "['0'] → ['1']/[R]" --> s9
   s9 -- "['$'] → [K]/[S]" --> s0
-  s10 -- "['^'] → [K]/[S]" --> c10
-  s10 -- "[*] → [K]/[L]" --> s10
-  s10 -. onHalt .-> s9
+  s11 -- "['^']|['1']|['0']|['$'] → [K]/[S]" --> s10
+  s11 -- "[*] → [K]/[S]" --> c11
   s12 -- "[B] → ['^']/[S]" --> s1
   s13 -- "['^']|['0'] → [E]/[R]" --> s13
   s13 -- "['1']|['$'] → [K]/[L]" --> s12
-  s14 -- "['^'] → [K]/[S]" --> c14
-  s14 -- "[*] → [K]/[L]" --> s14
-  s14 -. onHalt .-> s13
-  s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
+  s15 -- "['^']|['1']|['0']|['$'] → [K]/[S]" --> s14
   s15 -- "[*] → [K]/[S]" --> s0
   s16 -- "['1'] → ['0']/[R]" --> s16
-  s16 -- "['$'] → [K]/[S]" --> s0
+  s16 -- "['$'] → [K]/[S]" --> c19
   s17 -- "[B] → ['^']/[R]" --> s17
   s17 -- "['1'] → [K]/[R]" --> s16
   s18 -- "['0'] → ['1']/[R]" --> s16
   s18 -- "['1'] → [K]/[L]" --> s18
   s18 -- "['^'] → ['1']/[L]" --> s17
-  s20 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
-  s20 -- "[*] → [K]/[S]" --> c20
-  s20 -. onHalt .-> s15
-  s21 -- "['^']|['1']|['0'] → [K]/[R]" --> s21
-  s21 -- "['$'] → [K]/[L]" --> s18
-  s21 -- "[*] → [K]/[S]" --> c21
-  s21 -. onHalt .-> s20
-  s22 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s10
-  s22 -- "[*] → [K]/[S]" --> c22
-  s22 -. onHalt .-> s21
+  s19 -- "['^']|['1']|['0'] → [K]/[R]" --> s19
+  s19 -- "['$'] → [K]/[L]" --> s18
+  s19 -- "[*] → [K]/[S]" --> c19
   s23 -- "['^']|['1']|['0'] → [K]/[R]" --> s23
-  s23 == "['$'] → [K]/[S]" ==> s22
+  s23 -- "['$'] → [K]/[S]" --> s22
   s23 -- "[*] → [K]/[S]" --> s0
 ```
 
 ## minusOneFast
 
-*8 states; 15 transitions; 2 wrappers (max nesting depth 1); has cycles*
+*10 states; 15 transitions; 2 wrappers (max nesting depth 1); has cycles*
 
 ```mermaid
 flowchart TD
@@ -263,31 +271,37 @@ flowchart TD
   s13["normalizeNumberMoveNumberStart"]
   s15["normalizeNumber"]
   s26["minusOneFast"]
+  s14[["goToNumberStart(normalizeNumberMoveNumberStart)"]]
+  s25[["minusOneFastBorrow(normalizeNumber)"]]
   idle([idle])
-  subgraph w_14["halt frame"]
-    s14[["goToNumberStart"]]
-    c14(((halt)))
+  subgraph w_5["callable subtree of goToNumberStart"]
+    s5["goToNumberStart"]
+    c5(((halt)))
   end
-  subgraph w_25["halt frame"]
-    s25[["minusOneFastBorrow"]]
-    c25(((halt)))
+  subgraph w_24["callable subtree of minusOneFastBorrow"]
+    s24["minusOneFastBorrow"]
+    c24(((halt)))
   end
   idle -. enter .-> s26
+  s14 == "call" ==> s5
+  s25 == "call" ==> s24
+  w_5 -. "return" .-> s14
+  w_24 -. "return" .-> s25
+  s14 --> s13
+  s25 --> s15
   s1 -- "['$'] → [K]/[S]" --> s0
   s1 -- "[*] → [K]/[R]" --> s1
+  s5 -- "['^'] → [K]/[S]" --> c5
+  s5 -- "[*] → [K]/[L]" --> s5
   s12 -- "[B] → ['^']/[S]" --> s1
   s13 -- "['^']|['0'] → [E]/[R]" --> s13
   s13 -- "['1']|['$'] → [K]/[L]" --> s12
-  s14 -- "['^'] → [K]/[S]" --> c14
-  s14 -- "[*] → [K]/[L]" --> s14
-  s14 -. onHalt .-> s13
-  s15 == "['^']|['1']|['0']|['$'] → [K]/[S]" ==> s14
+  s15 -- "['^']|['1']|['0']|['$'] → [K]/[S]" --> s14
   s15 -- "[*] → [K]/[S]" --> s0
-  s25 -- "['1'] → ['0']/[S]" --> c25
-  s25 -- "['0'] → ['1']/[L]" --> s25
-  s25 -- "['^'] → [K]/[S]" --> c25
-  s25 -. onHalt .-> s15
+  s24 -- "['1'] → ['0']/[S]" --> c24
+  s24 -- "['0'] → ['1']/[L]" --> s24
+  s24 -- "['^'] → [K]/[S]" --> c24
   s26 -- "['^']|['1']|['0'] → [K]/[R]" --> s26
-  s26 == "['$'] → [K]/[L]" ==> s25
+  s26 -- "['$'] → [K]/[L]" --> s25
   s26 -- "[*] → [K]/[S]" --> s0
 ```
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 9c9c9e5..e6315b9 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -268,7 +268,7 @@ flowchart TD
 
 > 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
 
-`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). It is *not* bytewise lossless: state IDs auto-reassign on each rebuild, and for `withOverriddenHaltState` wrappers the composite name gains an extra `(${override.name})` wrapping on each pass (e.g., `scanToX(eraseHere)` becomes `scanToX(eraseHere)(eraseHere)` on a second round-trip — tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138)).
+`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). Under the v7 callable-subtree emit (#174), bytewise stability holds across rebuilds even for shared-bare cases (modulo state-id renumbering, which the test normalizes). The composite name is not stored as any graph node's label — `fromGraph` recomputes it fresh on reconstruction — so the accumulation problem from #138 cannot reoccur.
 
 ### Reference
 
@@ -398,29 +398,32 @@ flowchart TD
 %% alphabets: [[" ","a","b","X"]]
   s0(((halt)))
   s2["eraseHere"]
+  s3[["scanToX(eraseHere)"]]
   idle([idle])
-  subgraph w_3["halt frame"]
-    s3[["scanToX"]]
-    c3(((halt)))
+  subgraph w_1["callable subtree of scanToX"]
+    s1["scanToX"]
+    c1(((halt)))
   end
   idle -. enter .-> s3
+  s3 == "call" ==> s1
+  w_1 -. "return" .-> s3
+  s3 --> s2
+  s1 -- "['X'] → [K]/[S]" --> c1
+  s1 -- "[*] → [K]/[R]" --> s1
   s2 -- "[*] → [E]/[S]" --> s0
-  s3 -- "['X'] → [K]/[S]" --> c3
-  s3 -- "[*] → [K]/[R]" --> s3
-  s3 -. onHalt .-> s2
 ```
 
-**Reading guide** — the v7 emit (introduced in [#138](https://github.com/mellonis/turing-machine-js/issues/138)) makes the wrapper's runtime stack-frame semantics visible:
+**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. **The subgraph rectangle labeled `"halt frame"`** is the wrapper's runtime scope — while execution is "inside" this rectangle, the override target (`eraseHere`) sits on the runtime stack waiting to catch a halt. Visual-only; it does not mutate any edges.
-2. **`[[scanToX]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node. It's both the runtime entry point (execution starts here when entering the wrapper) AND the source of the dotted `onHalt` redirect. The wrapper's composite name (`scanToX(eraseHere)`) is computed at runtime via `state.name` but does not appear as a graph node label — only the bare's name is in the graph.
-3. **The halt-marker `(((halt)))` inside the subgraph** (`c3` here) is where the bare's halt-bound transitions land *inside* the wrapper's scope. `haltState` is a runtime singleton; the halt marker is a teaching aid showing "halt is caught here, not at the real terminus." Solid arrows from the bare to the halt marker all stay inside the rectangle.
-4. **The dotted `onHalt` arrow from `[[scanToX]]` to `eraseHere`** is the wrapper's catch-and-redirect. Originates from the wrapper-node since the wrapper *is* the catcher. Solid arrows from `[[scanToX]]` to other states can also cross the subgraph border — those are just regular runtime transitions whose target happens to be drawn outside this rectangle (only the dotted `onHalt` carries wrapper-machinery meaning). In larger compositions (`library-binary-numbers`'s `minusOne`), solid transitions whose target is *itself* a wrapped state render as a **thick `==>` arrow** instead of `-->` — that's the visual signal for "this transition enters a halt frame, pushing the override onto the runtime stack." Stack-growth structure is then scannable from the diagram: count thick arrows along an execution path to see how deep the stack gets.
-5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states that are *not* inside a wrapper's halt-frame — here, by `eraseHere` after it erases the cell.
+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.
+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.
+5. **Real `(((halt)))` outside any subgraph** (`s0`) is the actual run terminus. Reached only by states OUTSIDE any callable subtree — here, by `eraseHere` after it erases the cell.
 
-**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter the `halt frame` at `[[scanToX]]` (with `eraseHere` on the stack); `[*] → [K]/[R]` self-loops until the head sees `X`; the `['X'] → [K]/[S]` solid edge would normally halt — it lands on the halt marker `c3`, the wrapper's catch-and-redirect kicks in, pop the stack → `eraseHere`; `eraseHere` runs `[*] → [E]/[S]` and halts at real `s0`. Run terminates.
+**Reading runtime sequence on tape `['a','b','X','b','a']`:** enter at wrapper `[[scanToX(eraseHere)]]` (with `eraseHere` queued as the override); `call` into the subtree of `scanToX`; `[*] → [K]/[R]` self-loops on `s1` until the head sees `X`; the `['X'] → [K]/[S]` edge lands on `c1`; `return` to the wrapper; solid `--> s2` to `eraseHere`; `eraseHere` runs `[*] → [E]/[S]` and halts at real `s0`. Run terminates.
 
-> 💡 **Round-trip caveat.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for simple wrappers like this one ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). For shared-bare cases (same `State` instance used as the bare in multiple wrappers — e.g., `library-binary-numbers`'s `minusOne`), per-context duplication produces wrapper-id-dependent ordering that doesn't byte-match across rebuilds — equivalent runtime behavior, different emit-line order.
+> 💡 **Round-trip stability.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for wrapped states ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). The callable-subtree emit (#174) eliminates per-context duplication: shared bares like `library-binary-numbers`'s `invertNumber` (used by two wrappers in `minusOne`) render as a single subtree with two `& `-joined call arrows — so even shared-bare cases now produce stable, dedup'd round-trips.
 
 Wrappers nest: `inner.withOverriddenHaltState(middle).withOverriddenHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
 
@@ -575,8 +578,8 @@ The full reference for reading `toMermaid` output — shapes, edge styles, and t
 | Shape | Meaning |
 |---|---|
 | `s0(((halt)))` | the halt state |
-| `sN["name"]` | a regular state |
-| `sN[["name"]]` | a `withOverriddenHaltState` wrapper-bare (subroutine shape) — see [§Subroutine composition](#subroutine-composition-with-withoverriddenhaltstate) |
+| `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) |
 | `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) |
 
@@ -584,14 +587,17 @@ The full reference for reading `toMermaid` output — shapes, edge styles, and t
 
 | Style | Where | Meaning |
 |---|---|---|
-| `-->` regular solid | between states | plain transition |
-| `==>` thick solid | between states | transition INTO a wrapped state — stack-push happens at runtime |
-| `-. onHalt .->` dotted | from `[[bare]]` to override | wrapper's catch-and-redirect |
-| `-. enter .->` dotted | from `idle` to initial state | execution-start marker |
+| `-->` regular solid | between states; wrapper → override | plain transition / wrapper's post-return continuation |
+| `==> "call"` thick solid | wrapper → bare | the wrapper's call into its callable subtree; reserved for wrapper-to-bare |
+| `w_N -. "return" .->` dotted | subtree → wrapper | the subtree's halt-marker has incoming → control returns to the calling wrapper |
+| `w_N -. "halt" .->` dotted | subtree → `s0` | the subtree has a non-wrapper entry path → halt-marker can fire with empty stack (real halt) |
+| `idle -. enter .->` dotted | from `idle` to initial state | execution-start marker |
+
+The `&` ribbon syntax (`s_W1 & s_W2 == "call" ==> s_A`) collapses multiple wrappers that share a bare into one arrow. Bold `==>` is reserved exclusively for the wrapper-to-bare `call` arrow.
 
 ### Groupings
 
-`subgraph w_N["halt frame"] … end` wraps a `[[bare]]` + its halt marker — visual grouping of the wrapper's runtime halt-handling scope.
+`subgraph w_N["callable subtree of NAME"] … end` wraps a bare + its body + a halt marker — the callable scope of code that runs when a wrapper "calls" the bare. Multi-bare frames (union-find merged from shared body states) use the label `"callable scope: A ∪ B"`.
 
 ### Edge label format
 
@@ -651,7 +657,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **v7** *(alpha 1, 2026-05-21)* — Composition-representation overhaul. **First pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.1`). Stable v7.0.0 still pending [#102](https://github.com/mellonis/turing-machine-js/issues/102) (debugger step-in/over/out primitives). Landed in alpha.1:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
   - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
-  - **`toMermaid` wrapped-state emit overhaul** ([#138](https://github.com/mellonis/turing-machine-js/issues/138) / [#139](https://github.com/mellonis/turing-machine-js/issues/139)). The wrapper-and-its-bare pair collapses into a single graph node (`isWrapped: true`); the wrapper's composite name no longer appears as a node label (only the bare's name does). Each wrapper gets a Mermaid `subgraph w_${bareId}["halt frame"] … end` block containing the `[[bare]]` (subroutine shape) plus a halt-marker `(((halt)))` (visualization aid showing where halt-bound transitions land inside the scope). The dotted `onHalt` edge originates from the `[[bare]]` and crosses the subgraph border to the override target — exactly one per wrapper. `Graph` data shape gains `isWrapped` and `isHaltMarker` flags on `GraphNode` and a stable `id` on `GraphTransition` (deterministic per-edge identifier — supports downstream tooling like the `machines-demo` interactive viewer at [machines-demo#10](https://github.com/mellonis/machines-demo/issues/10)). Halt-marker graph nodes use negative ids and round-trip back to the singleton `haltState` via `fromGraph`. Bytewise round-trip stability falls out for simple wrappers (no composite name in the graph means `fromGraph(toGraph(state))` recomputes names fresh — no accumulation). Shared-bare cases (e.g. `minusOne`'s repeated `invertNumber`) use per-context duplication in the graph emit.
+  - **`toMermaid` callable-subtree emit** ([#174](https://github.com/mellonis/turing-machine-js/issues/174), supersedes the alpha.1 collapsed-bare shape from #138/#139). `withOverriddenHaltState` is modeled as a function call: the wrapper is a `[[composite-name]]` call site OUTSIDE any subgraph, the bare's reachable subtree becomes a `subgraph w_${frameId}["callable subtree of NAME"] … end` block containing the bare + body states + a per-frame halt marker `c${frameId}(((halt)))`. Frames are computed via union-find on bare-reachability — overlapping reach sets merge into a single union frame, so shared bares (`library-binary-numbers/minusOne`'s `invertNumber`) appear ONCE with `& `-joined call arrows from each wrapper. Bold `==> "call"` arrows are reserved for the wrapper-to-bare call; dotted `-.->` is reserved for frame-level dispatch (`return` / `halt` / `enter`). The retired `-. onHalt .->` keyword is replaced by a solid `--> override` arrow (just an ordinary transition under the call/return mental model). `GraphNode` gains `isWrapper`, `bareStateId`, `frameId` fields (and drops `isWrapped`). Bytewise round-trip stability now holds for all wrapped states including shared-bare cases (no per-context duplication).
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 1282f7f..a912171 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -308,9 +308,9 @@ describe('State.toGraph — unbound Reference', () => {
   });
 
   test('skips a transition whose nextState is an unbound Reference (wrapper context)', () => {
-    // toGraph has a separate try/catch in its wrapper-context branch — when the
-    // bare being walked is inside a `withOverriddenHaltState` wrapper. Same
-    // skip-and-continue semantic.
+    // Under the v7 callable-subtree model, the bare lives as a separate node
+    // from the wrapper. Same skip-and-continue semantic — the bare's unbound-
+    // Reference transition is dropped while building its node.
     const unboundRef = new Reference();
     const bare = new State({
       [symbol(['0'])]: {nextState: unboundRef},
@@ -324,30 +324,29 @@ describe('State.toGraph — unbound Reference', () => {
 
     const graph = State.toGraph(wrapped, tapeBlock);
 
-    // The collapsed wrapper node retains only the haltState-bound transition;
-    // the unbound-Ref one is dropped.
-    const collapsedNode = graph.nodes[wrapped.id];
-
-    expect(collapsedNode.transitions).toHaveLength(1);
+    // The bare's node retains only the haltState-bound transition; the
+    // wrapper itself has no transitions of its own under the new model.
+    expect(graph.nodes[bare.id].transitions).toHaveLength(1);
+    expect(graph.nodes[wrapped.id].isWrapper).toBe(true);
+    expect(graph.nodes[wrapped.id].transitions).toHaveLength(0);
   });
 });
 
 describe('State.fromGraph — cyclic override-halt chain', () => {
   test('throws when the override-halt graph has a cycle', () => {
-    // Graphs constructed by State.toGraph always have acyclic override chains
-    // (cycles throw at State construction). To exercise the defensive cycle
-    // detection in fromGraph, hand-build a Graph with overriddenHaltStateId
-    // pointing in a loop.
-    // Nodes need at least one transition each — State construction at pass 2
-    // rejects empty stateDefinitions before pass 3's cycle check would run.
+    // Under the v7 callable-subtree model, override-halt chains live on
+    // wrapper nodes. Hand-build two wrappers (sharing a single bare) whose
+    // `overriddenHaltStateId`s point at each other to exercise the defensive
+    // cycle guard in `fromGraph`'s `getFinal`.
     const dummyTransition = {pattern: '*', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"};
     const graph = {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'wA', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: true, bareStateId: 3, frameId: null},
+        2: {id: 2, name: 'wB', isHalt: false, transitions: [], overriddenHaltStateId: 1, isHaltMarker: false, isWrapper: true, bareStateId: 3, frameId: null},
+        3: {id: 3, name: 'shared', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 795a776..10491b5 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -377,64 +377,53 @@ export default class State {
     };
   }
 
-  // Walks the State graph and emits a `Graph` data structure. v7 emit shape:
-  // wrapper-States (those with `#overriddenHaltState !== null`) are collapsed
-  // onto their bare's representation in the graph, with the wrapper's own `#id`
-  // used as the graph node id, `isWrapped: true`, and `overriddenHaltStateId`
-  // set to the override's collapsed id. A per-wrapper "halt marker" graph node
-  // (id = negative-of-the-wrapper-id, `isHalt: true, isHaltMarker: true`) is
-  // synthesized; the bare's halt-bound transitions are rewritten to target the
-  // halt marker instead of the real one.
+  // Walks the State graph and emits a `Graph` data structure. v7 callable-
+  // subtree emit shape (#174):
   //
-  // Halt-marker node ids use the negation of the wrapper's id so they sit in a
-  // disjoint integer range from real ids (which are always non-negative). Real
-  // halt is always id 0.
+  // Each `withOverriddenHaltState` wrapper produces TWO graph nodes:
+  //   - A wrapper node (`isWrapper: true`, `[[composite-name]]` shape) — the
+  //     call site. No transitions of its own. `bareStateId` points to the
+  //     bare's GraphNode; `overriddenHaltStateId` points to the override
+  //     target's GraphNode.
+  //   - A bare node (`isWrapper: false`, regular shape) — the callable body.
+  //     Has the bare's transitions. Shared across all wrappers that wrap
+  //     this bare (no per-context duplication).
+  //
+  // Frames are computed via union-find on bare reachability: two bares whose
+  // forward-reachable sets overlap merge into one frame. Each frame contains
+  // its bares + body states + a single halt marker (id = `-frameId`). The
+  // canonical `frameId` is the smallest bare-id in the component.
+  //
+  // Halt-bound transitions of any in-frame state are retargeted to the
+  // frame's halt marker. The frame's `subtree -. return .-> wrapper` and
+  // `subtree -. halt .-> s0` arrows are demand-emitted by `toMermaid` from
+  // the frame structure; they're not stored as graph edges.
   static toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
     const nodes: Record<number, GraphNode> = {};
     const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
 
-    // Map from a wrapper-State to the "collapsed" graph node id used to refer
-    // to it in transitions. Same as the wrapper's `#id`, recorded for clarity
-    // when rewriting transition targets.
-    const wrapperGraphId = (s: State): number => s.#id;
-    const haltMarkerIdFor = (wrapper: State): number => -wrapper.#id;
-
-    // The `initialId` is the user-passed start. If it's a wrapper, the
-    // collapsed graph node uses its `#id`; otherwise its own `#id`.
-    const initialId = initialState.#id;
-
-    type QueueItem = {
-      // The State instance to process at this slot.
-      state: State;
-      // When non-null, the State is being processed AS the bare of this wrapper.
-      // The collapsed graph node uses `wrapperGraphId(wrapperContext)`,
-      // halt-bound transitions retarget to `haltMarkerIdFor(wrapperContext)`,
-      // self-loop transitions to the bare retarget to the wrapper-id.
-      wrapperContext: State | null;
-    };
+    // Pass 1: BFS-discover all reachable States; emit one GraphNode per State
+    // (wrapper or bare/regular). Wrappers and bares are separate nodes.
+    const visited = new Set<number>();
+    const queue: State[] = [initialState];
+    const bareIds = new Set<number>(); // ids referenced as a wrapper's bareStateId
 
-    const queue: QueueItem[] = [];
+    while (queue.length > 0) {
+      const state = queue.shift()!;
 
-    // Decide how to enqueue the start: if it's a wrapper, enqueue its bare with
-    // the wrapper as context; otherwise enqueue the state itself.
-    if (initialState.#overriddenHaltState && initialState.#bareState) {
-      queue.push({state: initialState.#bareState, wrapperContext: initialState});
-    } else {
-      queue.push({state: initialState, wrapperContext: null});
-    }
+      if (visited.has(state.#id)) {
+        continue;
+      }
 
-    while (queue.length > 0) {
-      const {state, wrapperContext} = queue.shift()!;
+      visited.add(state.#id);
 
       if (state.isHalt) {
-        // Real halt — always id 0, single node.
         if (!(0 in nodes)) {
           nodes[0] = {
             id: 0,
             name: state.#name,
             isHalt: true,
             isHaltMarker: false,
-            isWrapped: false,
             isWrapper: false,
             bareStateId: null,
             frameId: null,
@@ -446,122 +435,36 @@ export default class State {
         continue;
       }
 
-      if (wrapperContext !== null) {
-        // Process `state` (the bare) collapsed under `wrapperContext` (the
-        // wrapper). Graph node id = wrapper's id.
-        const collapsedId = wrapperGraphId(wrapperContext);
-
-        if (collapsedId in nodes) {
-          continue;
-        }
-
-        const haltMarkerId = haltMarkerIdFor(wrapperContext);
-        const overrideTarget = wrapperContext.#overriddenHaltState!;
-
-        // The override target's collapsed id: if the override is itself a
-        // wrapper, its graph node id is `overrideTarget.#id` (its own wrapper
-        // id); otherwise its own bare id.
-        const overrideGraphId = overrideTarget.#overriddenHaltState
-          ? wrapperGraphId(overrideTarget)
-          : overrideTarget.#id;
-
-        // Emit the halt-marker node if not already present (one per wrapper).
-        if (!(haltMarkerId in nodes)) {
-          nodes[haltMarkerId] = {
-            id: haltMarkerId,
-            name: 'halt',
-            isHalt: true,
-            isHaltMarker: true,
-            isWrapped: false,
-            isWrapper: false,
-            bareStateId: null,
-            frameId: null,
-            transitions: [],
-            overriddenHaltStateId: null,
-          };
-        }
+      // Wrapper? Emit wrapper node + queue bare and override target.
+      if (state.#overriddenHaltState !== null && state.#bareState !== null) {
+        const bareState = state.#bareState;
+        const overrideTarget = state.#overriddenHaltState;
 
-        // Build the collapsed node.
-        const collapsedNode: GraphNode = {
-          id: collapsedId,
-          name: state.#name,
+        nodes[state.#id] = {
+          id: state.#id,
+          name: state.#name, // composite name like "A(target)"
           isHalt: false,
           isHaltMarker: false,
-          isWrapped: true,
-          isWrapper: false,
-          bareStateId: null,
+          isWrapper: true,
+          bareStateId: bareState.#id,
           frameId: null,
           transitions: [],
-          overriddenHaltStateId: overrideGraphId,
+          overriddenHaltStateId: overrideTarget.#id,
         };
 
-        nodes[collapsedId] = collapsedNode;
-
-        let patternIx = 0;
-
-        for (const [sym, {command, nextState}] of state.#symbolToDataMap) {
-          let target: State;
-
-          try {
-            target = nextState instanceof State ? nextState : nextState.ref;
-          } catch {
-            patternIx += 1;
-            continue;
-          }
-
-          // Retarget transitions per Variant X conventions:
-          // - target == haltState → halt marker (stays inside the subgraph)
-          // - target == bare (self-loop) → the collapsed wrapper id
-          // - target is itself a wrapper → that wrapper's collapsed id
-          // - else → target's own id
-          let nextStateId: number;
-
-          if (target.isHalt) {
-            nextStateId = haltMarkerId;
-          } else if (target === state) {
-            nextStateId = collapsedId;
-          } else if (target.#overriddenHaltState && target.#bareState) {
-            nextStateId = wrapperGraphId(target);
-            queue.push({state: target.#bareState, wrapperContext: target});
-          } else {
-            nextStateId = target.#id;
-            queue.push({state: target, wrapperContext: null});
-          }
-
-          collapsedNode.transitions.push({
-            pattern: decodePatternDescription(sym.description, alphabets),
-            command: command.tapesCommands.map((tc) => ({
-              symbol: decodeWriteSymbol(tc.symbol),
-              movement: decodeMovement((tc.movement as symbol).description),
-            })),
-            nextStateId,
-            id: `${collapsedId}-${patternIx}`,
-          });
-
-          patternIx += 1;
-        }
-
-        // Enqueue the override target so its own node is emitted.
-        if (overrideTarget.#overriddenHaltState && overrideTarget.#bareState) {
-          queue.push({state: overrideTarget.#bareState, wrapperContext: overrideTarget});
-        } else {
-          queue.push({state: overrideTarget, wrapperContext: null});
-        }
-
-        continue;
-      }
+        bareIds.add(bareState.#id);
+        queue.push(bareState);
+        queue.push(overrideTarget);
 
-      // Non-wrapper context: emit `state` as a regular node.
-      if (state.#id in nodes) {
         continue;
       }
 
+      // Regular (or bare) state — build node with transitions.
       const node: GraphNode = {
         id: state.#id,
         name: state.#name,
         isHalt: false,
         isHaltMarker: false,
-        isWrapped: false,
         isWrapper: false,
         bareStateId: null,
         frameId: null,
@@ -583,38 +486,208 @@ export default class State {
           continue;
         }
 
-        let nextStateId: number;
-
-        if (target.#overriddenHaltState && target.#bareState) {
-          // Transition into a wrapper — use its collapsed id.
-          nextStateId = wrapperGraphId(target);
-          queue.push({state: target.#bareState, wrapperContext: target});
-        } else {
-          nextStateId = target.#id;
-          queue.push({state: target, wrapperContext: null});
-        }
-
         node.transitions.push({
           pattern: decodePatternDescription(sym.description, alphabets),
           command: command.tapesCommands.map((tc) => ({
             symbol: decodeWriteSymbol(tc.symbol),
             movement: decodeMovement((tc.movement as symbol).description),
           })),
-          nextStateId,
+          nextStateId: target.#id,
           id: `${state.#id}-${patternIx}`,
         });
 
+        queue.push(target);
         patternIx += 1;
       }
     }
 
-    return {initialId, alphabets, nodes};
+    // Always emit real halt as a sentinel, even if no transition targets it.
+    // It anchors the `subtree -. halt .-> s0` frame-level arrow whenever a
+    // frame demand-emits one, and it's the canonical machine-halt singleton.
+    if (!(0 in nodes)) {
+      nodes[0] = {
+        id: 0,
+        name: 'halt',
+        isHalt: true,
+        isHaltMarker: false,
+        isWrapper: false,
+        bareStateId: null,
+        frameId: null,
+        transitions: [],
+        overriddenHaltStateId: null,
+      };
+    }
+
+    // Pass 2: For each bare, compute its forward-reachable set (following
+    // transitions; stopping at halt and at wrappers — both are frame
+    // boundaries).
+    const computeReach = (startId: number): Set<number> => {
+      const reach = new Set<number>();
+      const stack = [startId];
+
+      while (stack.length > 0) {
+        const id = stack.pop()!;
+
+        if (reach.has(id)) {
+          continue;
+        }
+
+        const node = nodes[id];
+
+        if (!node || node.isHalt || node.isWrapper) {
+          continue;
+        }
+
+        reach.add(id);
+
+        for (const t of node.transitions) {
+          const target = nodes[t.nextStateId];
+
+          if (!target || target.isHalt || target.isWrapper) {
+            continue;
+          }
+
+          stack.push(t.nextStateId);
+        }
+      }
+
+      return reach;
+    };
+
+    const reachByBare = new Map<number, Set<number>>();
+
+    for (const bareId of bareIds) {
+      reachByBare.set(bareId, computeReach(bareId));
+    }
+
+    // Pass 3: Union-find on bare overlaps. Two bares merge if their reach
+    // sets share any state. Canonical representative = smallest bare-id in
+    // the component.
+    const ufParent = new Map<number, number>();
+
+    const ufFind = (id: number): number => {
+      if (!ufParent.has(id)) {
+        ufParent.set(id, id);
+      }
+
+      let root = id;
+
+      while (ufParent.get(root) !== root) {
+        root = ufParent.get(root)!;
+      }
+
+      // Path compression
+      let cur = id;
+
+      while (ufParent.get(cur) !== root) {
+        const next = ufParent.get(cur)!;
+
+        ufParent.set(cur, root);
+        cur = next;
+      }
+
+      return root;
+    };
+
+    const ufUnion = (a: number, b: number) => {
+      const ra = ufFind(a);
+      const rb = ufFind(b);
+
+      if (ra === rb) return;
+
+      if (ra < rb) {
+        ufParent.set(rb, ra);
+      } else {
+        ufParent.set(ra, rb);
+      }
+    };
+
+    for (const bareId of bareIds) {
+      ufFind(bareId);
+    }
+
+    // For each state, collect the bares that reach it; union all bares that
+    // share a state.
+    const stateToReachingBares = new Map<number, number[]>();
+
+    for (const [bareId, reachSet] of reachByBare) {
+      for (const stateId of reachSet) {
+        let bares = stateToReachingBares.get(stateId);
+
+        if (!bares) {
+          bares = [];
+          stateToReachingBares.set(stateId, bares);
+        }
+
+        bares.push(bareId);
+      }
+    }
+
+    for (const bares of stateToReachingBares.values()) {
+      for (let i = 1; i < bares.length; i += 1) {
+        ufUnion(bares[0], bares[i]);
+      }
+    }
+
+    // Assign frameId to each in-reach state.
+    const frameIds = new Set<number>();
+
+    for (const [stateId, bares] of stateToReachingBares) {
+      const frameId = ufFind(bares[0]);
+
+      nodes[stateId].frameId = frameId;
+      frameIds.add(frameId);
+    }
+
+    // Pass 4: Retarget halt-bound transitions for in-frame states to the
+    // frame's halt marker. Out-of-frame states (top-level dispatcher, override
+    // targets, etc.) keep their halt-bound transitions pointing at real halt.
+    for (const node of Object.values(nodes)) {
+      if (node.frameId === null) {
+        continue;
+      }
+
+      const haltMarkerId = -node.frameId;
+
+      for (const t of node.transitions) {
+        const target = nodes[t.nextStateId];
+
+        if (target && target.isHalt && !target.isHaltMarker) {
+          t.nextStateId = haltMarkerId;
+        }
+      }
+    }
+
+    // Pass 5: Emit one halt marker per frame.
+    for (const frameId of frameIds) {
+      const haltMarkerId = -frameId;
+
+      nodes[haltMarkerId] = {
+        id: haltMarkerId,
+        name: 'halt',
+        isHalt: true,
+        isHaltMarker: true,
+        isWrapper: false,
+        bareStateId: null,
+        frameId,
+        transitions: [],
+        overriddenHaltStateId: null,
+      };
+    }
+
+    return {initialId: initialState.#id, alphabets, nodes};
   }
 
   // Inverse of toGraph: rebuilds a State graph (and a fresh TapeBlock with the
   // graph's alphabets) from a serialized Graph. Round-trips with toGraph in
   // the sense that running the rebuilt machine on the same input gives the
   // same output, but the rebuilt State instances have *new* internal IDs.
+  //
+  // Under the v7 callable-subtree model (#174), graph nodes split into:
+  //   - Wrapper nodes (`isWrapper: true`, no transitions) — reconstructed via
+  //     `bareStates[bareStateId].withOverriddenHaltState(finalStates[overriddenHaltStateId])`.
+  //   - Bare/regular nodes — constructed as normal States with transitions.
+  //   - Halt + halt-marker nodes — collapse to the singleton `haltState`.
   static fromGraph(graph: Graph): {
     start: State;
     tapeBlock: TapeBlock;
@@ -624,12 +697,15 @@ export default class State {
     const tapeBlock = TapeBlock.fromAlphabets(alphabetObjs);
     const ids = Object.keys(graph.nodes).map(Number);
 
-    // Pass 1: pre-create a Reference for each non-halt node so transitions can
-    // forward-declare their targets.
+    // Pass 1: pre-create a Reference for each non-halt non-halt-marker node
+    // (both wrappers and regulars). Halt and halt-marker nodes collapse to the
+    // singleton `haltState` and need no ref.
     const refs: Record<number, Reference> = {};
 
     for (const nodeId of ids) {
-      if (!graph.nodes[nodeId].isHalt) {
+      const node = graph.nodes[nodeId];
+
+      if (!node.isHalt) {
         refs[nodeId] = new Reference();
       }
     }
@@ -651,14 +727,15 @@ export default class State {
       return tapeBlock.symbol(flat);
     };
 
-    // Pass 2: build a "bare" State for each non-halt node (no override yet).
-    // nextState entries point at refs so cycles work; haltState is used directly.
+    // Pass 2: build a State for each non-wrapper non-halt non-halt-marker
+    // node. Transitions point at refs so cycles work; haltState (and halt
+    // markers, which collapse to haltState) are used directly.
     const bareStates: Record<number, State> = {};
 
     for (const nodeId of ids) {
       const node = graph.nodes[nodeId];
 
-      if (node.isHalt) {
+      if (node.isHalt || node.isWrapper) {
         continue;
       }
 
@@ -667,7 +744,9 @@ export default class State {
       for (const t of node.transitions) {
         const key = patternToKey(parsePatternString(t.pattern, graph.alphabets));
         const target = graph.nodes[t.nextStateId];
-        const nextState: State | Reference = target.isHalt ? haltState : refs[t.nextStateId];
+        const nextState: State | Reference = !target || target.isHalt
+          ? haltState
+          : refs[t.nextStateId];
 
         stateDefinition![key] = {
           command: t.command.map((c) => ({
@@ -678,16 +757,19 @@ export default class State {
         };
       }
 
-      // Graph-sourced names may contain `(` and `)` (composite wrapper names
-      // emitted by toGraph). Bypass the constructor's user-facing name
-      // validation by constructing without a name and assigning #name directly.
+      // Graph-sourced names may contain `(` and `)` (composite wrapper names —
+      // although wrappers go through a separate path below, defensive
+      // construction here keeps the bypass uniform). Construct without a name
+      // and assign `#name` directly to skip user-facing name validation.
       const bare = new State(stateDefinition);
 
       bare.#name = node.name;
       bareStates[nodeId] = bare;
     }
 
-    // Pass 3: apply overrideHaltStates transitively.
+    // Pass 3: resolve every node to its final State (memoized + cycle-safe).
+    // Wrappers compose lazily via `withOverriddenHaltState` once their bare
+    // and override are resolved.
     const finalStates: Record<number, State> = {};
     const inProgress = new Set<number>();
 
@@ -698,7 +780,7 @@ export default class State {
 
       const node = graph.nodes[nodeId];
 
-      if (node.isHalt) {
+      if (!node || node.isHalt) {
         finalStates[nodeId] = haltState;
 
         return haltState;
@@ -710,10 +792,15 @@ export default class State {
 
       inProgress.add(nodeId);
 
-      let state = bareStates[nodeId];
+      let state: State;
+
+      if (node.isWrapper) {
+        const bare = getFinal(node.bareStateId!);
+        const override = getFinal(node.overriddenHaltStateId!);
 
-      if (node.overriddenHaltStateId !== null) {
-        state = bareStates[nodeId].withOverriddenHaltState(getFinal(node.overriddenHaltStateId));
+        state = bare.withOverriddenHaltState(override);
+      } else {
+        state = bareStates[nodeId];
       }
 
       inProgress.delete(nodeId);
@@ -726,8 +813,8 @@ export default class State {
       getFinal(nodeId);
     }
 
-    // Pass 4: bind each ref to the FINAL (possibly wrapped) state so transitions
-    // resolve to the version that has its override-halt set.
+    // Pass 4: bind each ref to the resolved final State so cross-node
+    // transitions land on the right instance.
     for (const nodeId of ids) {
       if (!graph.nodes[nodeId].isHalt) {
         refs[nodeId].bind(finalStates[nodeId]);
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index ee29183..c516d59 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -118,9 +118,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [
             {pattern: "'0'", command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
             {pattern: "'1'", command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
@@ -139,17 +139,21 @@ describe('toMermaid', () => {
     expect(out).toContain("s1 -- \"['1'] → [K]/[S]\" --> s0");
   });
 
-  test('renders dotted onHalt edge when overriddenHaltStateId is set', () => {
+  test('renders wrapper-to-override solid arrow when overriddenHaltStateId is set', () => {
+    // Under the v7 callable-subtree model, wrapper → override is a regular
+    // solid `-->` (the new convention reserves bold/dotted for `call`/`return`/
+    // `halt`). The retired `-. onHalt .->` keyword no longer appears.
     const out = toMermaid({
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isHaltMarker: false, isWrapper: true, bareStateId: null, frameId: null},
       },
     });
 
-    expect(out).toContain('s1 -. onHalt .-> s0');
+    expect(out).toContain('s1 --> s0');
+    expect(out).not.toContain('onHalt');
   });
 
   test('non-initial, non-halt node uses square bracket shape', () => {
@@ -157,9 +161,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     });
 
@@ -171,9 +175,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0'], [' ', 'a']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [{
             pattern: "'0','a'",
             command: [{symbol: "'0'", movement: 'R'}, {symbol: "'a'", movement: 'L'}],
@@ -517,7 +521,7 @@ describe('README diagrams: engine-generated outputs', () => {
     ]);
   });
 
-  test('withOverriddenHaltState AFTER (scanThenErase, machine README) — emits the v7 halt-frame subgraph', () => {
+  test('withOverriddenHaltState AFTER (scanThenErase, machine README) — emits the v7 callable-subtree shape', () => {
     const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
     const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
     const {symbol} = tapeBlock;
@@ -537,13 +541,19 @@ describe('README diagrams: engine-generated outputs', () => {
       '%% alphabets: [[" ","a","b","X"]]',
       '(((halt)))', // real halt outside any subgraph
       '["eraseHere"]', // override is a regular [name] node
-      '[["scanToX"]]', // wrapper-collapsed bare uses subroutine shape inside the subgraph
-      'subgraph w_', // halt-frame subgraph wraps the bare + its halt marker
-      '"halt frame"', // subgraph label
+      '[["scanToX(eraseHere)"]]', // wrapper uses [[…]] subroutine shape (composite name)
+      '["scanToX"]', // bare uses regular [name] shape inside the subgraph
+      'subgraph w_', // callable-subtree subgraph wraps the bare + its halt marker
+      'callable subtree of scanToX', // subgraph label
       'idle([idle])', // pre-execution sentinel — always emitted
-      'idle -. enter .->', // labeled dotted enter arrow points at the initial state
+      'idle -. enter .->', // labeled dotted enter arrow points at the wrapper
       '"[*] → [E]/[S]"', // eraseHere's erase command
-      '-. onHalt .->', // the dotted override-halt edge — wrapper's catch-and-redirect, crosses the subgraph border
+      '== "call" ==>', // wrapper-to-bare bold call arrow
+      '-. "return" .->', // frame-to-wrapper dotted return arrow
     ]);
+
+    // Retired keywords — must NOT appear under the new convention.
+    expect(output).not.toContain('onHalt');
+    expect(output).not.toContain('halt frame');
   });
 });
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index 7f9a7a8..d5a4dd3 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -18,36 +18,36 @@ export type GraphNode = {
   name: string;
   isHalt: boolean;
   transitions: GraphTransition[];
+  // On wrapper nodes (`isWrapper: true`), the id of the override target's
+  // GraphNode (could be a wrapper or a regular state). `null` on non-wrapper
+  // nodes (their override semantics live in the wrapper that wraps them, if
+  // any).
   overriddenHaltStateId: number | null;
-  // `true` when this node represents the bare of a `withOverriddenHaltState`-
-  // wrapped state under v7 alpha.1's collapsed emit. Carries the `[[…]]`
-  // (subroutine) shape signal for `toMermaid` and tells `fromGraph` to
-  // reconstruct via `bare.withOverriddenHaltState(target)`. The new
-  // un-collapsed model (#174) supersedes this with `isWrapper` + `bareStateId`
-  // below; `isWrapped` is retained transitionally for backward-compat during
-  // the cutover.
-  isWrapped: boolean;
-  // New (#174): `true` for external `[[…]]` wrapper nodes that have a
-  // separate bare node in the graph. The wrapper sits outside any subtree
-  // subgraph; its `bareStateId` points to the corresponding bare GraphNode
-  // (which lives inside its home subtree). Multiple wrapper nodes can share
-  // the same `bareStateId` when they wrap the same bare with different
-  // override targets. Under the new model, `isWrapped: false` for these
-  // nodes — the wrapper-vs-bare distinction is carried by `isWrapper`.
+  // `true` for external `[[…]]` wrapper nodes — the call sites that
+  // `withOverriddenHaltState` produces. Wrappers sit OUTSIDE any callable
+  // subtree subgraph; their `bareStateId` points to the bare's GraphNode id
+  // (which lives inside its home subtree). Multiple wrappers can share the
+  // same `bareStateId` when they wrap the same bare with different overrides.
+  // Wrapper nodes have NO transitions of their own — the `call` arrow into
+  // the bare is derived from `bareStateId`, the post-return `-->` arrow to
+  // the override is derived from `overriddenHaltStateId`.
   isWrapper: boolean;
-  // New (#174): on wrapper nodes (`isWrapper: true`), the id of the bare
-  // GraphNode this wrapper wraps. `null` for non-wrapper nodes.
+  // On wrappers, the id of the bare GraphNode this wrapper wraps. `null`
+  // for non-wrapper nodes.
   bareStateId: number | null;
-  // New (#174): the id of the wrapper whose callable subtree this node lives
-  // in. `null` for nodes outside any subtree (top-level states, real halt
-  // singleton, wrapper nodes themselves, the `idle` visualization sentinel).
-  // Set on bares, body states, and halt markers. Two bares may share a
-  // `frameId` when union-find merges their reachable sets (shared body state
-  // forces a union frame; see spec Example "Shared body state").
+  // The id of the callable subtree this node lives in. `null` for nodes
+  // outside any subtree (top-level states, real halt singleton, wrapper
+  // nodes themselves, the `idle` visualization sentinel). Set on bares,
+  // body states reachable from any bare, and halt markers. Two bares may
+  // share a `frameId` when union-find merges their reachable sets (shared
+  // body state forces a union frame; see spec Example "Shared body state").
+  // The canonical frame id is the smallest bare-id in the component.
   frameId: number | null;
-  // `true` for a synthesized halt marker graph node — one per wrapper context.
-  // Real halt has `isHalt: true, isHaltMarker: false`; halt markers have both
-  // `true`. `fromGraph` maps halt-marker nodes back to the singleton `haltState`.
+  // `true` for a synthesized halt marker graph node — one per frame.
+  // Real halt has `isHalt: true, isHaltMarker: false`; halt markers have
+  // both `true`. `fromGraph` maps halt-marker nodes back to the singleton
+  // `haltState`. Halt marker id = `-frameId` (sits in disjoint negative-id
+  // range from real node ids).
   isHaltMarker: boolean;
 };
 
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index e90e144..93bb51f 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -6,19 +6,25 @@ import {type Graph, type GraphCommand, type GraphNode} from './graph';
 // Currently only Mermaid flowchart syntax is supported. Future formats
 // (Graphviz, JSON-LD, custom DSL) belong here too.
 //
-// v7 emit shape (#138/#139):
-//   - Each wrapper-State collapses onto its bare's representation. The collapsed
-//     graph node has `isWrapped: true` and is emitted as Mermaid `[[…]]`
-//     (subroutine / double-walled-rectangle) shape, inside a `subgraph
-//     w_${id}["halt frame"] … end` block. A synthesized "halt marker" graph
-//     node (with `isHalt: true, isHaltMarker: true`, id = -wrapperId in graph
-//     data) sits inside the subgraph and serves as the local landing point for
-//     the bare's halt-bound transitions. The dotted onHalt edge runs from the
-//     `[[bare]]` directly to the override target, crossing the subgraph border.
-//   - Real halt (id 0) is emitted as `s0(((halt)))` outside any subgraph.
-//   - Halt marker nodes use the Mermaid id `c${absId}` (where `absId = -id`)
-//     since Mermaid IDs must match /[A-Za-z][A-Za-z0-9_]*/ — negative numbers
-//     are not legal syntax.
+// v7 callable-subtree emit (#174):
+//   - Each `withOverriddenHaltState` wrapper produces TWO graph nodes — a
+//     wrapper node (`[[composite-name]]`, OUTSIDE any subgraph) and a bare
+//     node (regular shape, INSIDE its callable subtree subgraph).
+//   - Subgraphs (one per frame): `subgraph w_${frameId}["callable subtree
+//     of NAME"]` (single bare) or `["callable scope: A ∪ B"]` (union).
+//   - Each frame has exactly one halt marker `c${frameId}(((halt)))` inside
+//     its subgraph; halt-bound transitions from in-frame states retarget to
+//     it. Always emitted (orphan signals dead wrapper).
+//   - Arrow conventions:
+//       solid `-->`        regular transitions, including wrapper-to-override.
+//       bold  `==>`        RESERVED for the wrapper-to-bare `call` arrow.
+//                          `&` ribbon collapses multi-wrapper-shares-bare.
+//       dotted `-.->`      frame-level dispatch (`return`, `halt`, `enter`).
+//   - The `return` arrow (subgraph → wrapper) is demand-emitted iff the
+//     frame's halt marker has at least one incoming edge AND the wrapper
+//     calls into the frame. The `halt` arrow (subgraph → s0) is emitted
+//     iff the halt marker has incoming AND there's at least one non-wrapper
+//     entry into the frame (cross-subgraph solid arrow from outside).
 
 // Maps a graph node id to its Mermaid id.
 //   - non-negative id N  → "sN"
@@ -36,130 +42,229 @@ function parseMermaidId(s: string): number {
   return Number(s.slice(1));
 }
 
+function frameSubgraphId(frameId: number): string {
+  return `w_${frameId}`;
+}
+
 export function toMermaid(graph: Graph): string {
   const lines: string[] = [
     'flowchart TD',
     `%% alphabets: ${JSON.stringify(graph.alphabets)}`,
   ];
 
-  // Sort nodes by id (ascending — real halt first at 0, regular states next,
-  // negative-id halt markers last). Deterministic emit lets `toMermaid` →
-  // `fromMermaid` → `toMermaid` round-trip stably (regression for #139).
+  // Sort nodes by id ascending — real halt (0) first, then regulars by their
+  // ids, then halt markers (negative) at the end. Deterministic emit lets
+  // toMermaid → fromMermaid → toMermaid round-trip stably (#139).
   const nodes = Object.values(graph.nodes).slice().sort((a, b) => a.id - b.id);
-  const wrappedNodes = nodes.filter((n) => n.isWrapped);
 
-  // Convention: wrapped node id N → halt marker id -N.
-  const haltMarkerIdFor = (wrappedId: number): number => -wrappedId;
+  // Bucket nodes for emit order.
+  const topLevelNodes = nodes.filter((n) => n.frameId === null && !n.isWrapper);
+  const wrapperNodes = nodes.filter((n) => n.isWrapper);
+  // Bares-and-bodies inside frames, grouped by frameId.
+  const nodesByFrame = new Map<number, GraphNode[]>();
+  // Halt-marker per frame (kept separate so it always emits LAST inside the
+  // subgraph for deterministic shape).
+  const haltMarkerByFrame = new Map<number, GraphNode>();
 
-  // Set of halt-marker ids that belong to some wrapper (= are inside a subgraph).
-  const haltMarkerIds = new Set<number>();
+  for (const node of nodes) {
+    if (node.frameId === null || node.isWrapper) continue;
 
-  for (const w of wrappedNodes) {
-    const haltMarkerId = haltMarkerIdFor(w.id);
+    if (node.isHaltMarker) {
+      haltMarkerByFrame.set(node.frameId, node);
+    } else {
+      let bucket = nodesByFrame.get(node.frameId);
 
-    if (haltMarkerId in graph.nodes) {
-      haltMarkerIds.add(haltMarkerId);
-    }
-  }
+      if (!bucket) {
+        bucket = [];
+        nodesByFrame.set(node.frameId, bucket);
+      }
 
-  // Emit non-subgraph nodes first: real halt + regular non-wrapped nodes.
-  // No special round-shape `((…))` for the initial — the `idle -. enter .->`
-  // arrow emitted below is the sole "start here" signal.
-  for (const node of nodes) {
-    if (node.isWrapped || haltMarkerIds.has(node.id)) {
-      continue;
+      bucket.push(node);
     }
+  }
 
-    const id = mermaidIdFor(node.id);
+  // 1. Emit top-level nodes (real halt, non-wrapper regulars outside any frame).
+  for (const node of topLevelNodes) {
+    const mid = mermaidIdFor(node.id);
 
     if (node.isHalt) {
-      lines.push(`  ${id}(((halt)))`);
+      lines.push(`  ${mid}(((halt)))`);
     } else {
-      lines.push(`  ${id}["${node.name}"]`);
+      lines.push(`  ${mid}["${node.name}"]`);
     }
   }
 
-  // `idle` sentinel = pre-execution marker for the machine. Always emitted,
-  // with a labeled dotted arrow `idle -. enter .-> sN` to the initial state.
-  // Symmetric with the `onHalt` dotted convention used by wrapper redirects.
-  // Visual-only — `idle` is not a graph node.
+  // 2. Emit wrappers at top level.
+  for (const wrapper of wrapperNodes) {
+    lines.push(`  ${mermaidIdFor(wrapper.id)}[["${wrapper.name}"]]`);
+  }
+
+  // 3. `idle` sentinel.
   lines.push('  idle([idle])');
 
-  // Emit one subgraph per wrapper, in sorted wrapped-id order.
-  for (const wrapped of wrappedNodes) {
-    const wrappedMid = mermaidIdFor(wrapped.id);
-    const haltMarkerId = haltMarkerIdFor(wrapped.id);
-    const haltMarkerMid = mermaidIdFor(haltMarkerId);
+  // 4. Subgraph per frame.
+  const frameIds = [...nodesByFrame.keys()].sort((a, b) => a - b);
+
+  for (const frameId of frameIds) {
+    const frameBares = (nodesByFrame.get(frameId) ?? []).filter(
+      (n) => isFrameBare(n, graph),
+    );
+    const frameBareNames = frameBares
+      .slice()
+      .sort((a, b) => a.id - b.id)
+      .map((n) => n.name);
+    const label = frameBareNames.length > 1
+      ? `callable scope: ${frameBareNames.join(' ∪ ')}`
+      : `callable subtree of ${frameBareNames[0] ?? frameId}`;
+
+    lines.push(`  subgraph ${frameSubgraphId(frameId)}["${label}"]`);
+
+    // Inner nodes — sort by id for determinism.
+    for (const node of (nodesByFrame.get(frameId) ?? []).slice().sort((a, b) => a.id - b.id)) {
+      lines.push(`    ${mermaidIdFor(node.id)}["${node.name}"]`);
+    }
 
-    lines.push(`  subgraph w_${wrapped.id}["halt frame"]`);
-    lines.push(`    ${wrappedMid}[["${wrapped.name}"]]`);
+    const haltMarker = haltMarkerByFrame.get(frameId);
 
-    if (haltMarkerId in graph.nodes) {
-      lines.push(`    ${haltMarkerMid}(((halt)))`);
+    if (haltMarker) {
+      lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
     }
 
     lines.push('  end');
   }
 
-  // Enter arrow: emitted after subgraphs so it visually points at the initial
-  // node (whether plain `[…]` or wrapped `[[…]]` inside a subgraph).
+  // 5. Enter arrow.
   lines.push(`  idle -. enter .-> ${mermaidIdFor(graph.initialId)}`);
 
-  // Emit transitions per-node in sorted node-id order. Within a node,
-  // transitions emit in their stored array order (which mirrors the source
-  // state's symbol-map insertion order — stable per State instance).
+  // 6. `call` arrows — grouped by bare (multi-wrapper-shares-bare collapses
+  // into a single `&` ribbon).
+  const wrappersByBare = new Map<number, GraphNode[]>();
+
+  for (const wrapper of wrapperNodes) {
+    if (wrapper.bareStateId === null) continue;
+
+    let group = wrappersByBare.get(wrapper.bareStateId);
+
+    if (!group) {
+      group = [];
+      wrappersByBare.set(wrapper.bareStateId, group);
+    }
+
+    group.push(wrapper);
+  }
+
+  const sortedBares = [...wrappersByBare.keys()].sort((a, b) => a - b);
+
+  for (const bareId of sortedBares) {
+    const wrappers = wrappersByBare.get(bareId)!.slice().sort((a, b) => a.id - b.id);
+    const sources = wrappers.map((w) => mermaidIdFor(w.id)).join(' & ');
+
+    lines.push(`  ${sources} == "call" ==> ${mermaidIdFor(bareId)}`);
+  }
+
+  // 7. Demand-emit `return` and `halt` arrows per frame.
+  // For each frame: check if its halt marker has incoming transitions.
+  const haltMarkerHasIncoming = new Map<number, boolean>();
+
   for (const node of nodes) {
-    if (node.isHalt && !node.isHaltMarker) {
-      continue;
+    for (const t of node.transitions) {
+      const target = graph.nodes[t.nextStateId];
+
+      if (target && target.isHaltMarker && target.frameId !== null) {
+        haltMarkerHasIncoming.set(target.frameId, true);
+      }
     }
+  }
+
+  // For each frame: check if there's at least one non-wrapper entry (a solid
+  // `-->` from OUTSIDE the frame into any node INSIDE).
+  const hasNonWrapperEntry = new Map<number, boolean>();
+
+  for (const node of nodes) {
+    if (node.isWrapper) continue;
+
+    for (const t of node.transitions) {
+      const target = graph.nodes[t.nextStateId];
+
+      if (
+        target
+        && target.frameId !== null
+        && node.frameId !== target.frameId
+      ) {
+        hasNonWrapperEntry.set(target.frameId, true);
+      }
+    }
+  }
+
+  for (const frameId of frameIds) {
+    if (!haltMarkerHasIncoming.get(frameId)) continue;
+
+    // Return arrow — collapsed `&` ribbon over all wrappers calling this frame.
+    const callingWrappers = wrapperNodes.filter((w) => {
+      if (w.bareStateId === null) return false;
+
+      const bare = graph.nodes[w.bareStateId];
+
+      return !!bare && bare.frameId === frameId;
+    });
+
+    if (callingWrappers.length > 0) {
+      const targets = callingWrappers
+        .slice()
+        .sort((a, b) => a.id - b.id)
+        .map((w) => mermaidIdFor(w.id))
+        .join(' & ');
+
+      lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
+    }
+
+    if (hasNonWrapperEntry.get(frameId)) {
+      lines.push(`  ${frameSubgraphId(frameId)} -. "halt" .-> s0`);
+    }
+  }
+
+  // 8. Wrapper-to-override arrows (regular solid).
+  for (const wrapper of wrapperNodes) {
+    if (wrapper.overriddenHaltStateId === null) continue;
+
+    lines.push(
+      `  ${mermaidIdFor(wrapper.id)} --> ${mermaidIdFor(wrapper.overriddenHaltStateId)}`,
+    );
+  }
+
+  // 9. Regular transitions for non-wrapper non-halt-marker non-halt nodes.
+  for (const node of nodes) {
+    if (node.isHalt || node.isHaltMarker || node.isWrapper) continue;
 
     for (const t of node.transitions) {
-      // Bracketed-tape-block format (v7): each role-list — read alternatives,
-      // writes, movements — wraps in `[…]` to mark "this is a tape-block
-      // reading". Brackets stay even for single-tape machines; the `[…]` is
-      // the tape-block concept indicator.
-      //
-      //   Single-tape:                  ['X'] → [K]/[R]
-      //   Single-tape + alternation:    ['^']|['1']|['0'] → [K]/[S]
-      //   Two-tape:                     ['0','a'] → [K,'1']/[R,S]
-      //   Two-tape + alternation:       ['0','a']|['1','b'] → [K,K]/[R,L]
-      //
-      // Alternation is ALWAYS per-pattern-bracket — one full bracketed list
-      // per alternative — regardless of tape count. Pedagogically each
-      // alternative is its own drawn transition; a compact in-bracket form
-      // (`['^'|'1']`) would read as cross-product semantics in multi-tape
-      // (`['0'|'1','a'|'b']` = 4 combos, not 2 paired alternatives), so we
-      // avoid introducing it for the single-tape case too.
       const alternatives = t.pattern.split('|');
       const reads = alternatives.map((alt) => `[${alt}]`).join('|');
       const writes = `[${t.command.map((c) => c.symbol).join(',')}]`;
       const moves = `[${t.command.map((c) => c.movement).join(',')}]`;
       const label = `${reads} → ${writes}/${moves}`;
 
-      // Thicker `==>` arrow when the transition crosses INTO a wrapper —
-      // signals "this transition pushes that wrapper's override onto the
-      // runtime stack" (per `TuringMachine.run` line ~220's
-      // `if (state !== nextState && nextState.overriddenHaltState) push(...)`).
-      // Self-loops (state === nextState) don't push at runtime — keep the
-      // regular `-->` for those even when the target is wrapped.
-      const targetNode = graph.nodes[t.nextStateId];
-      const isEnteringWrapper = targetNode && targetNode.isWrapped && t.nextStateId !== node.id;
-      const lineSegment = isEnteringWrapper ? '==' : '--';
-      const arrowTip = isEnteringWrapper ? '==>' : '-->';
-
       lines.push(
-        `  ${mermaidIdFor(node.id)} ${lineSegment} "${label}" ${arrowTip} ${mermaidIdFor(t.nextStateId)}`,
+        `  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`,
       );
     }
+  }
 
-    if (node.overriddenHaltStateId !== null) {
-      lines.push(
-        `  ${mermaidIdFor(node.id)} -. onHalt .-> ${mermaidIdFor(node.overriddenHaltStateId)}`,
-      );
+  return lines.join('\n');
+}
+
+// Helper: identify "the bare states" that anchor a frame's name. A bare is a
+// node referenced as some wrapper's `bareStateId`. Body states (also in-frame
+// but not bare) are excluded from the frame label.
+function isFrameBare(node: GraphNode, graph: Graph): boolean {
+  if (node.isWrapper || node.isHalt) return false;
+
+  for (const other of Object.values(graph.nodes)) {
+    if (other.isWrapper && other.bareStateId === node.id) {
+      return true;
     }
   }
 
-  return lines.join('\n');
+  return false;
 }
 
 // Inverse of toMermaid: parses the Mermaid output produced by toMermaid back
@@ -176,13 +281,20 @@ export function toMermaid(graph: Graph): string {
 const haltNodeRegex = /^([sc]\d+)\(\(\(halt\)\)\)$/;
 const regularNodeRegex = /^(s\d+)\["([^"]*)"\]$/;
 const wrappedNodeRegex = /^(s\d+)\[\["([^"]*)"\]\]$/;
-const subgraphStartRegex = /^subgraph\s+w_\d+\["([^"]*)"\]$/;
+const subgraphStartRegex = /^subgraph\s+w_(\d+)\["([^"]*)"\]$/;
 const subgraphEndRegex = /^end$/;
 const idleNodeRegex = /^idle\(\[idle\]\)$/;
 const enterArrowRegex = /^idle\s+-\.\s+enter\s+\.->\s+(s\d+)$/;
-const transitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
-const thickTransitionRegex = /^([sc]\d+)\s+==\s+"(.*)"\s+==>\s+([sc]\d+)$/;
-const onHaltRegex = /^([sc]\d+)\s+-\.\s+onHalt\s+\.->\s+([sc]\d+)$/;
+// Regular labeled transition (solid `-->`).
+const labeledTransitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
+// Wrapper → override (unlabeled solid `-->`).
+const wrapperOverrideRegex = /^(s\d+)\s+-->\s+([sc]\d+)$/;
+// Call arrow (bold `==>`), with optional `&`-joined source ribbon.
+const callArrowRegex = /^(s\d+(?:\s+&\s+s\d+)*)\s+==\s+"call"\s+==>\s+(s\d+)$/;
+// Return arrow (`w_N -. return .-> s_W` with optional `&` target ribbon).
+const returnArrowRegex = /^w_(\d+)\s+-\.\s+"return"\s+\.->\s+(s\d+(?:\s+&\s+s\d+)*)$/;
+// Halt arrow (`w_N -. halt .-> s0`).
+const haltArrowRegex = /^w_(\d+)\s+-\.\s+"halt"\s+\.->\s+s0$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
 // the preceding \s* and a permissive (.+); see CodeQL js/polynomial-redos.
 const alphabetsRegex = /^%%\s*alphabets:\s*(\S.*)$/;
@@ -193,11 +305,7 @@ export function fromMermaid(text: string): Graph {
   let alphabets: string[][] = [];
   let initialId: number | null = null;
   const nodes: Record<number, GraphNode> = {};
-  // Track the halt-marker ids that appeared inside a subgraph — they should be
-  // marked `isHaltMarker: true` even though they share the `(((halt)))` shape
-  // with the real halt at the top level.
-  const haltMarkerIds = new Set<number>();
-  let inSubgraph = false;
+  let currentFrameId: number | null = null;
 
   const ensureNode = (
     id: number,
@@ -205,7 +313,6 @@ export function fromMermaid(text: string): Graph {
       name?: string;
       isHalt?: boolean;
       isHaltMarker?: boolean;
-      isWrapped?: boolean;
       isWrapper?: boolean;
       bareStateId?: number | null;
       frameId?: number | null;
@@ -217,7 +324,6 @@ export function fromMermaid(text: string): Graph {
         name: opts.name ?? mermaidIdFor(id),
         isHalt: opts.isHalt ?? false,
         isHaltMarker: opts.isHaltMarker ?? false,
-        isWrapped: opts.isWrapped ?? false,
         isWrapper: opts.isWrapper ?? false,
         bareStateId: opts.bareStateId ?? null,
         frameId: opts.frameId ?? null,
@@ -228,7 +334,6 @@ export function fromMermaid(text: string): Graph {
       if (opts.name !== undefined) nodes[id].name = opts.name;
       if (opts.isHalt !== undefined) nodes[id].isHalt = opts.isHalt;
       if (opts.isHaltMarker !== undefined) nodes[id].isHaltMarker = opts.isHaltMarker;
-      if (opts.isWrapped !== undefined) nodes[id].isWrapped = opts.isWrapped;
       if (opts.isWrapper !== undefined) nodes[id].isWrapper = opts.isWrapper;
       if (opts.bareStateId !== undefined) nodes[id].bareStateId = opts.bareStateId;
       if (opts.frameId !== undefined) nodes[id].frameId = opts.frameId;
@@ -237,11 +342,9 @@ export function fromMermaid(text: string): Graph {
     return nodes[id];
   };
 
-  // First pass: alphabets + nodes (track subgraph context to mark halt markers).
+  // First pass: nodes + alphabets (track subgraph context for frameId).
   for (const line of lines) {
-    if (line === 'flowchart TD') {
-      continue;
-    }
+    if (line === 'flowchart TD') continue;
 
     const am = line.match(alphabetsRegex);
 
@@ -250,34 +353,32 @@ export function fromMermaid(text: string): Graph {
       continue;
     }
 
-    if (subgraphStartRegex.test(line)) {
-      inSubgraph = true;
+    const sgStart = line.match(subgraphStartRegex);
+
+    if (sgStart) {
+      currentFrameId = Number(sgStart[1]);
       continue;
     }
 
     if (subgraphEndRegex.test(line)) {
-      inSubgraph = false;
+      currentFrameId = null;
       continue;
     }
 
-    // `idle([idle])` sentinel: a visual pre-execution marker. Not a graph
-    // node — skip declaration, parse the `idle -. enter .-> sN` arrow in the
-    // edge pass to set initialId.
-    if (idleNodeRegex.test(line)) {
-      continue;
-    }
+    if (idleNodeRegex.test(line)) continue;
 
     const hm = line.match(haltNodeRegex);
 
     if (hm) {
       const id = parseMermaidId(hm[1]);
-      const isHaltMarker = inSubgraph || id < 0;
-
-      ensureNode(id, {name: 'halt', isHalt: true, isHaltMarker});
+      const isHaltMarker = currentFrameId !== null;
 
-      if (isHaltMarker) {
-        haltMarkerIds.add(id);
-      }
+      ensureNode(id, {
+        name: 'halt',
+        isHalt: true,
+        isHaltMarker,
+        frameId: isHaltMarker ? currentFrameId : null,
+      });
 
       continue;
     }
@@ -285,21 +386,28 @@ export function fromMermaid(text: string): Graph {
     const wm = line.match(wrappedNodeRegex);
 
     if (wm) {
-      ensureNode(parseMermaidId(wm[1]), {name: wm[2], isWrapped: true});
+      ensureNode(parseMermaidId(wm[1]), {
+        name: wm[2],
+        isWrapper: true,
+      });
+
       continue;
     }
 
     const rm = line.match(regularNodeRegex);
 
     if (rm) {
-      ensureNode(parseMermaidId(rm[1]), {name: rm[2]});
+      ensureNode(parseMermaidId(rm[1]), {
+        name: rm[2],
+        frameId: currentFrameId,
+      });
+
       continue;
     }
   }
 
   // Second pass: edges.
   for (const line of lines) {
-    // `idle -. enter .-> sN`: the sole source of initialId.
     const em = line.match(enterArrowRegex);
 
     if (em) {
@@ -307,16 +415,43 @@ export function fromMermaid(text: string): Graph {
       continue;
     }
 
-    const om = line.match(onHaltRegex);
+    // Return/halt arrows are derivable from frame structure at the next
+    // toMermaid emit; consume but don't persist as graph data.
+    if (returnArrowRegex.test(line) || haltArrowRegex.test(line)) {
+      continue;
+    }
+
+    // `call` arrow — sets bareStateId on each source wrapper.
+    const cm = line.match(callArrowRegex);
+
+    if (cm) {
+      const sources = cm[1].split(/\s+&\s+/);
+      const bareId = parseMermaidId(cm[2]);
+
+      for (const src of sources) {
+        ensureNode(parseMermaidId(src), {isWrapper: true, bareStateId: bareId});
+      }
 
-    if (om) {
-      ensureNode(parseMermaidId(om[1])).overriddenHaltStateId = parseMermaidId(om[2]);
       continue;
     }
 
-    // Thick transition (`==> `) and regular transition (`-->`) share the same
-    // semantics — only the visual differs. Parse both via the same code path.
-    const tm = line.match(transitionRegex) ?? line.match(thickTransitionRegex);
+    // Wrapper → override (unlabeled solid `-->`). Only fires if the source
+    // node is a known wrapper (declared as `[[…]]`).
+    const wo = line.match(wrapperOverrideRegex);
+
+    if (wo) {
+      const fromId = parseMermaidId(wo[1]);
+      const toId = parseMermaidId(wo[2]);
+
+      if (nodes[fromId] && nodes[fromId].isWrapper) {
+        nodes[fromId].overriddenHaltStateId = toId;
+        continue;
+      }
+      // Fall through — unlabeled solid from a non-wrapper is unexpected;
+      // treated as a malformed line and ignored by the labeled-regex below.
+    }
+
+    const tm = line.match(labeledTransitionRegex);
 
     if (tm) {
       const fromId = parseMermaidId(tm[1]);
@@ -329,34 +464,15 @@ export function fromMermaid(text: string): Graph {
         throw new Error(`fromMermaid: malformed edge label: "${label}"`);
       }
 
-      // Bracketed-tape-block format (v7):
-      //   [<read-cells>]|[<read-cells>]... → [<write-cells>]/[<move-cells>]
-      // Each bracketed list is a tape-block reading; the outer `|` separates
-      // alternative read patterns. For single-tape machines with alternation,
-      // the compact form `[<alt1>|<alt2>|...]` (one bracket, alternatives
-      // inside) is also accepted; both forms decode to the same pattern
-      // string.
       const readLabel = label.slice(0, arrowIx);
       const cmdLabel = label.slice(arrowIx + ' → '.length);
 
-      // Strict per-pattern bracket form: `|` only between bracketed lists,
-      // never inside. The compact `['^'|'1']` form is rejected by design —
-      // every alternative must be its own bracketed pattern (`['^']|['1']`).
-      // Pedagogically: each transition is drawn explicitly; the compact form
-      // would read as cross-product semantics in multi-tape and confuse
-      // readers (`['0'|'1','a'|'b']` could mean 4 combos, not 2 paired alts).
-      // The rule applies to all bracketed lists — read alternatives, writes,
-      // and movements — because commands and movements have no alternation
-      // semantic either.
       const stripBrackets = (s: string): string => {
         if (!s.startsWith('[') || !s.endsWith(']')) {
           throw new Error(`fromMermaid: malformed bracketed list: "${s}"`);
         }
 
         const inner = s.slice(1, -1);
-
-        // Walk the inner content; backslash escapes the next char (so `\|`
-        // inside a cell is a literal pipe, not the alternation separator).
         let i = 0;
 
         while (i < inner.length) {
@@ -378,10 +494,6 @@ export function fromMermaid(text: string): Graph {
         return inner;
       };
 
-      // Match `[…]` blocks in the read label. Inner content is a tape-block
-      // reading (possibly with `|` for compact single-tape alternation).
-      // `[^\]]*` is the simple non-greedy match — works because cell content
-      // doesn't typically contain literal `]`.
       const blockMatches = readLabel.match(/\[[^\]]*\]/g);
 
       if (!blockMatches || blockMatches.length === 0) {
@@ -389,7 +501,6 @@ export function fromMermaid(text: string): Graph {
       }
 
       const pattern = blockMatches.map(stripBrackets).join('|');
-
       const slashIx = cmdLabel.indexOf(']/[');
 
       if (slashIx === -1) {
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 5aea059..147e9f0 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -7,9 +7,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
             {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
@@ -31,9 +31,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
           ],
@@ -52,9 +52,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
           transitions: [{pattern: '0', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
         },
       },
@@ -72,10 +72,10 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 
@@ -90,8 +90,8 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 
@@ -197,8 +197,8 @@ describe('summarizeGraph defensive guards', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isWrapped: false, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
       },
     };
 

From 54ab833da840be07b0f06e7501f1ced666999518 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 08:18:18 +0300
Subject: [PATCH 020/118] fix(fromMermaid): tighten `&` ribbon regex to avoid
 CodeQL polynomial-ReDoS flag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeQL flagged `/\s+&\s+/` in `callArrowRegex` and `returnArrowRegex` as
a polynomial regex on uncontrolled input (`graphFormats.ts:428` per the
PR #167 integration check on commit 1dde21d).

`toMermaid` emits literal single-space ` & ` between ribbon members, and
the parser is documented as strict to the dialect `toMermaid` emits. So
tightening `\s+&\s+` → ` & ` (and replacing the split regex with a
literal-string split) is loss-free for round-trip cases while removing
the polynomial-backtracking shape CodeQL detects.

The outer `\s+` between major tokens (`==`, `==>`, `-.`, `.->`) stay as
`\s+` — they're not in a repeat group and aren't flagged.
---
 packages/machine/src/utilities/graphFormats.ts | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 93bb51f..364ad61 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -290,9 +290,12 @@ const labeledTransitionRegex = /^([sc]\d+)\s+--\s+"(.*)"\s+-->\s+([sc]\d+)$/;
 // Wrapper → override (unlabeled solid `-->`).
 const wrapperOverrideRegex = /^(s\d+)\s+-->\s+([sc]\d+)$/;
 // Call arrow (bold `==>`), with optional `&`-joined source ribbon.
-const callArrowRegex = /^(s\d+(?:\s+&\s+s\d+)*)\s+==\s+"call"\s+==>\s+(s\d+)$/;
+// Ribbon separator is fixed at " & " (single spaces around &) — toMermaid
+// emits exactly that form, so the parser is strict to it. The literal-space
+// form avoids CodeQL's polynomial-ReDoS flag on a `\s+&\s+` shape.
+const callArrowRegex = /^(s\d+(?: & s\d+)*)\s+==\s+"call"\s+==>\s+(s\d+)$/;
 // Return arrow (`w_N -. return .-> s_W` with optional `&` target ribbon).
-const returnArrowRegex = /^w_(\d+)\s+-\.\s+"return"\s+\.->\s+(s\d+(?:\s+&\s+s\d+)*)$/;
+const returnArrowRegex = /^w_(\d+)\s+-\.\s+"return"\s+\.->\s+(s\d+(?: & s\d+)*)$/;
 // Halt arrow (`w_N -. halt .-> s0`).
 const haltArrowRegex = /^w_(\d+)\s+-\.\s+"halt"\s+\.->\s+s0$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
@@ -425,7 +428,7 @@ export function fromMermaid(text: string): Graph {
     const cm = line.match(callArrowRegex);
 
     if (cm) {
-      const sources = cm[1].split(/\s+&\s+/);
+      const sources = cm[1].split(' & ');
       const bareId = parseMermaidId(cm[2]);
 
       for (const src of sources) {

From d27e872a1c2380948bfe42b86318cd350d9a8ba2 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 08:22:48 +0300
Subject: [PATCH 021/118] test(coverage): exercise #174's union-find +
 halt-arrow + stripBrackets paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR #167's coveralls check was failing with -1.8pp (`96.442%`) after #174
merged to v7. The new code added uncovered branches that the existing
test suite didn't exercise — none of the binary-numbers algorithms
trigger union-find (their bares transition to wrappers, not directly
between each other's bodies), and no test hand-built a non-wrapper
entry into a frame.

Two new tests:

1. **Shared body state (spec Example 6 worked example 2)** — dispatcher
   with `['1'] → W1`, `['2'] → W2`, `['3'] → X` where X is a body state
   shared between bares A (in W1) and B (in W2). Exercises:
   - `ufFind` multi-step walk + path compression
   - `ufUnion` merging A and B into one component
   - `frameBareNames` multi-element sort + `callable scope: A ∪ B` label
   - `hasNonWrapperEntry` triggering the `-. "halt" .->` arrow

2. **Movement bracket malformed** — input passes the `]/[` shape guard
   but `stripBrackets` catches the missing closing `]` on the move part.
   Targets the previously unreachable `stripBrackets` throw branch.

Coverage delta (v8):
  Stmts:    97.49 → 98.51  (+1.02)
  Branch:   94.04 → 95.23  (+1.19)
  Funcs:    98.85 → 100    (+1.15)
  Lines:    97.83 → 98.91  (+1.08)

Comfortably above the Coveralls baseline that triggered the -1.8pp
warning; the integration check on PR #167 should go green once this
lands on v7.
---
 packages/machine/src/utilities/graph.spec.ts | 94 ++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index c516d59..ede42d9 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -354,6 +354,24 @@ describe('fromMermaid error paths', () => {
     expect(() => fromMermaid(mermaid)).toThrow(/write-cells.*move-cells.*mismatch/);
   });
 
+  test('throws on a movement bracket that opens but never closes', () => {
+    // Targets `stripBrackets`'s own throw: writes are well-formed (`[K]`) so
+    // the `slashIx` guard accepts the label as `[…]/[…]`-shaped, but the
+    // movement segment `[S` opens without a closing `]`. `stripBrackets`
+    // catches this even though the earlier label-shape guard didn't.
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0"]]',
+      '  s0(((halt)))',
+      '  s1["entry"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      "  s1 -- \"['0'] → [K]/[S\" --> s0", // moves part `[S` is missing the closing bracket
+    ].join('\n');
+
+    expect(() => fromMermaid(mermaid)).toThrow(/malformed bracketed list/);
+  });
+
   test('parses backslash-escaped chars inside a bracket (e.g. literal `|` as `\\|`)', () => {
     // `stripBrackets` walks the inner content character-by-character; when it
     // hits `\`, it skips the next char (so `\|` is a literal pipe, not the
@@ -557,3 +575,79 @@ describe('README diagrams: engine-generated outputs', () => {
     expect(output).not.toContain('halt frame');
   });
 });
+
+// Spec Example 6 "Shared body state" + worked example 2 (direct entry into the
+// union frame): two wrappers W1, W2 with bares A, B whose reach sets overlap
+// on a shared body state X, plus a dispatcher with a direct entry to X (a
+// non-wrapper transition into the frame).
+//
+// Exercises:
+//   - union-find on overlapping reach sets (State.ts ufFind multi-step walk +
+//     path compression + ufUnion)
+//   - `callable scope: A ∪ B` subgraph label (graphFormats frameBareNames sort)
+//   - `-. "halt" .->` demand-emit arrow (graphFormats hasNonWrapperEntry path)
+describe('callable-subtree: shared body state forces a union frame', () => {
+  test('two bares sharing a body state merge into one frame; non-wrapper entry triggers halt arrow', () => {
+    const alphabet = new Alphabet([' ', '1', '2', '3', 'X']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    // Shared body state X — halts on any symbol.
+    const X = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'X');
+
+    // Bare A — transitions to X.
+    const A = new State({
+      [ifOtherSymbol]: {command: {movement: movements.right}, nextState: X},
+    }, 'A');
+
+    // Bare B — also transitions to X (so reach(A) ∩ reach(B) ⊇ {X}, union triggers).
+    const B = new State({
+      [ifOtherSymbol]: {command: {movement: movements.right}, nextState: X},
+    }, 'B');
+
+    // Targets for the wrappers.
+    const target1 = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 't1');
+    const target2 = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 't2');
+
+    const W1 = A.withOverriddenHaltState(target1);
+    const W2 = B.withOverriddenHaltState(target2);
+
+    // Dispatcher chooses path by symbol: '1' → W1, '2' → W2, '3' → X (direct
+    // entry into the union frame, the non-wrapper entry path that triggers
+    // the `-. "halt" .->` arrow).
+    const dispatcher = new State({
+      [symbol(['1'])]: {command: {movement: movements.stay}, nextState: W1},
+      [symbol(['2'])]: {command: {movement: movements.stay}, nextState: W2},
+      [symbol(['3'])]: {command: {movement: movements.stay}, nextState: X},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+
+    // A and B should share a frameId (union-find merged them).
+    const nodeA = graph.nodes[A.id];
+    const nodeB = graph.nodes[B.id];
+    const nodeX = graph.nodes[X.id];
+
+    expect(nodeA.frameId).not.toBeNull();
+    expect(nodeA.frameId).toBe(nodeB.frameId);
+    expect(nodeX.frameId).toBe(nodeA.frameId);
+
+    // Frame id = smallest bare-id in the component (deterministic canonical).
+    expect(nodeA.frameId).toBe(Math.min(A.id, B.id));
+
+    // Emit: one union frame with `callable scope: A ∪ B` label, halt arrow
+    // present (cross-subgraph dispatcher → X entry).
+    const out = toMermaid(graph);
+
+    expect(out).toContain('callable scope: A ∪ B');
+    expect(out).toMatch(/w_\d+ -\. "halt" \.-> s0/);
+    // Both wrappers call their respective bares.
+    expect(out).toMatch(/s\d+ == "call" ==> s\d+/g);
+  });
+});

From 0be485b0bf1830166c45383c83755088d9295e4d Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 08:45:07 +0300
Subject: [PATCH 022/118] chore(release): 7.0.0-alpha.2

---
 lerna.json                                    |  2 +-
 package-lock.json                             |  8 +--
 packages/builder/package.json                 |  4 +-
 .../library-binary-numbers-bare/package.json  |  4 +-
 packages/library-binary-numbers/package.json  |  4 +-
 packages/machine/CHANGELOG.md                 | 50 +++++++++++++++++++
 packages/machine/package.json                 |  2 +-
 7 files changed, 62 insertions(+), 12 deletions(-)

diff --git a/lerna.json b/lerna.json
index 9859cef..a18995b 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.1",
+  "version": "7.0.0-alpha.2",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index c2cc36c..9049f26 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10656,7 +10656,7 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.1",
+      "version": "7.0.0-alpha.2",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
@@ -10667,7 +10667,7 @@
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.1",
+      "version": "7.0.0-alpha.2",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
@@ -10678,7 +10678,7 @@
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.1",
+      "version": "7.0.0-alpha.2",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
@@ -10689,7 +10689,7 @@
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.1",
+      "version": "7.0.0-alpha.2",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/builder/package.json b/packages/builder/package.json
index d48a170..7736037 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.1",
+  "version": "7.0.0-alpha.2",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.1"
+    "@turing-machine-js/machine": "^7.0.0-alpha.2"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index b0f03f1..f49e97b 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.1",
+  "version": "7.0.0-alpha.2",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.1"
+    "@turing-machine-js/machine": "^7.0.0-alpha.2"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index 7726d42..6ec5374 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.1",
+  "version": "7.0.0-alpha.2",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.1"
+    "@turing-machine-js/machine": "^7.0.0-alpha.2"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index e24e8be..860d785 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,56 @@ 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.2] - 2026-05-21
+
+Second v7 pre-release. Refines alpha.1's `toMermaid` wrapped-state emit into the function-call model ([#174](https://github.com/mellonis/turing-machine-js/issues/174)) and adds two construction-time improvements to `withOverriddenHaltState` ([#175](https://github.com/mellonis/turing-machine-js/issues/175), [#176](https://github.com/mellonis/turing-machine-js/issues/176)). Published to npm 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.2`. Migration walkthrough at the bottom.
+
+### Changed
+
+- **`toMermaid` callable-subtree emit** ([#174](https://github.com/mellonis/turing-machine-js/issues/174)) — supersedes alpha.1's collapsed-bare emit (#138/#139) with a function-call model:
+  - **Wrapper and bare are separate graph nodes.** The wrapper sits OUTSIDE any subgraph as `[[composite-name]]` (call site). The bare lives INSIDE its callable subtree subgraph as a regular `[name]` node.
+  - **Subgraph label** changed from `"halt frame"` to `"callable subtree of NAME"` (single bare) or `"callable scope: A ∪ B"` (multi-bare union frame).
+  - **Halt marker is per-frame**, not per-wrapper. When union-find merges two bares' subtrees (shared body state), they share one halt marker.
+  - **Arrow vocabulary rewritten**:
+    - Solid `-->` for regular transitions AND for the wrapper's post-return `--> override` (just an ordinary transition under the call/return model).
+    - Bold `==> "call"` is RESERVED for the wrapper-to-bare call. `&` ribbon syntax (`s_W1 & s_W2 == "call" ==> s_A`) collapses multiple wrappers that share a bare.
+    - Dotted `-.->` is reserved for frame-level dispatch: `w_N -. "return" .-> wrapper` (demand-emit), `w_N -. "halt" .-> s0` (demand-emit on non-wrapper entry), `idle -. enter .-> sN` (unchanged).
+    - The `-. onHalt .->` keyword from alpha.1 is **retired** — replaced by a solid `--> override` arrow.
+  - **No per-context duplication.** Shared bares (e.g. `library-binary-numbers/minusOne`'s `invertNumber`, called by two wrappers) appear as a single subtree with `& `-joined call arrows from each wrapper.
+  - **`GraphNode` field changes**: `isWrapped` removed; `isWrapper: boolean`, `bareStateId: number | null`, `frameId: number | null` added. `overriddenHaltStateId` now lives on wrapper nodes only.
+  - Bytewise round-trip stability now holds for **all** wrapped states, including shared-bare cases (alpha.1 was only stable for simple wrappers).
+
+- **Nested `.wohs()` chain collapse** ([#176](https://github.com/mellonis/turing-machine-js/issues/176)) — `A.withOverriddenHaltState(t1).withOverriddenHaltState(t2)` is now equivalent to `A.withOverriddenHaltState(t2)`. The chain's inner override (`t1`) is dead at runtime (only the outermost wrapper's override is pushed onto the halt stack on entry — verified empirically). Composite name now reflects runtime behavior: `A(t2)`, not the misleading `A(t1)(t2)`. `withOverriddenHaltState` unwraps `this` to its bare before constructing the new wrapper.
+
+### Added
+
+- **`withOverriddenHaltState` memoization** ([#175](https://github.com/mellonis/turing-machine-js/issues/175)) — calls with the same `(bare, override)` pair return the literally-same `State` instance. Backed by a two-level `WeakMap` keyed by the bare with `WeakRef`-valued entries, so cached wrappers can be GC'd when nothing else holds them. Composes with #176's chain-collapse: `A.wohs(t1).wohs(t2)` and `A.wohs(t2)` both resolve to the same instance.
+
+- **Spec doc** at `docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md` capturing the callable-subtree model design (worked examples for simple wrappers, PostMachine subroutines, shared-bare wrappers, self-wrapping, nested chains, Reference cycles, shared body states).
+
+### Migration from alpha.1
+
+Three breaking changes vs alpha.1, all in the visualization layer:
+
+**1. Mermaid format** — alpha.1 Mermaid strings (with `-. onHalt .->` edges or `[[bare]]` inside subgraphs) will NOT parse with the new `fromMermaid`. The format is one-way: re-emit via `toMermaid(toGraph(state, tapeBlock))` on alpha.2 to regenerate.
+
+**2. `Graph` data shape** — `GraphNode.isWrapped` removed; replaced by `isWrapper: boolean`, `bareStateId: number | null`, `frameId: number | null`. If you store serialized `Graph` JSON from alpha.1, re-emit on alpha.2.
+
+**3. Wrapper composite name in nested chains** — `A.wohs(t1).wohs(t2)` was `A(t1)(t2)` in alpha.1; under #176 it's now `A(t2)`. Code that parsed the composite name to extract intermediate overrides will need to adapt (those overrides were never actually pushed at runtime — alpha.1's name was misleading).
+
+`withOverriddenHaltState` memoization (#175) is fully additive — same arguments now return the same instance, but no observable behavior changes for code that doesn't rely on instance identity.
+
+### Out of v7-alpha.2 (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. Additive — won't change any existing API. Will land in `v7.0.0-alpha.3` or stable `v7.0.0`.
+- **[#180](https://github.com/mellonis/turing-machine-js/issues/180)** — extract `State.toGraph`/`fromGraph` to its own module. Internal refactor; no API change.
+
+### Compatibility
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.1` → `^7.0.0-alpha.2` on `@turing-machine-js/builder`, `@turing-machine-js/library-binary-numbers`, `@turing-machine-js/library-binary-numbers-bare`.
+
 ## [7.0.0-alpha.1] - 2026-05-21
 
 First v7 pre-release. Consolidates the composition-representation overhaul landed across [#149](https://github.com/mellonis/turing-machine-js/issues/149), [#148](https://github.com/mellonis/turing-machine-js/issues/148), [#138](https://github.com/mellonis/turing-machine-js/issues/138), and [#139](https://github.com/mellonis/turing-machine-js/issues/139). Published to npm under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 008f7ba..514ffb7 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.1",
+  "version": "7.0.0-alpha.2",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"

From 231729f480d965eea123aec54b36538ecd165e69 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 14:54:39 +0300
Subject: [PATCH 023/118] =?UTF-8?q?docs(spec):=20worked=20union=20shapes?=
 =?UTF-8?q?=20(A=E2=88=AAB,=20A=E2=88=AAB=E2=88=AAC,=20transitive)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three engine-emitted Mermaid examples appended to the "Shared body state"
edge-case section of the callable-subtree spec:

- Case 1 (`A ∪ B`): two bares, one shared body state. Two `==> call`
  arrows into the same frame; one `& `-joined `return` ribbon.
- Case 2 (`A ∪ B ∪ C`): three bares, all share X. Three `call` arrows,
  one three-way `return` ribbon. Same frame, one halt marker.
- Case 3 (`(A ∪ B) ∪ C` transitive): A shares X with B, A shares Y with
  C, B and C share nothing direct. Union-find's transitive-closure step
  bundles all three into one scope.

Output is real `toMermaid` emit from probe machines (not hand-drawn),
so the examples stay in sync with the engine implementation.
---
 ...026-05-21-halt-frame-transitive-closure.md | 152 ++++++++++++++++++
 1 file changed, 152 insertions(+)

diff --git a/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md b/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
index 959024f..f3ddd0c 100644
--- a/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
+++ b/docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md
@@ -568,6 +568,158 @@ Cross-subgraph entry `s_disp -- ['3'] --> s_X` triggers the `halt` arrow to emit
 
 The union model degrades gracefully — adding direct entry to a state inside the union just flips the `halt` arrow on. No new structural concept needed.
 
+### Worked union shapes — engine-emitted Mermaid
+
+Real `toMermaid` output (post-#174) for three increasingly merged union shapes. Each test machine has a dispatcher routing by tape symbol into per-bare wrappers `W = bare.withOverriddenHaltState(target)`. The bares' transitions land on shared body states that drive the union-find merge.
+
+#### Case 1: `A ∪ B` (two bares, one shared state)
+
+```text
+reach(A) = {A, X}
+reach(B) = {B, X}
+A ∩ B = {X} → union(A, B)
+```
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","1","2"]]
+  s0(((halt)))
+  s4["t1"]
+  s5["t2"]
+  s8["dispatcher"]
+  s6[["A(t1)"]]
+  s7[["B(t2)"]]
+  idle([idle])
+  subgraph w_2["callable scope: A ∪ B"]
+    s1["X"]
+    s2["A"]
+    s3["B"]
+    c2(((halt)))
+  end
+  idle -. enter .-> s8
+  s6 == "call" ==> s2
+  s7 == "call" ==> s3
+  w_2 -. "return" .-> s6 & s7
+  s6 --> s4
+  s7 --> s5
+  s1 -- "[*] → [K]/[S]" --> c2
+  s2 -- "[*] → [K]/[R]" --> s1
+  s3 -- "[*] → [K]/[R]" --> s1
+  s4 -- "[*] → [K]/[S]" --> s0
+  s5 -- "[*] → [K]/[S]" --> s0
+  s8 -- "['1'] → [K]/[S]" --> s6
+  s8 -- "['2'] → [K]/[S]" --> s7
+```
+
+Two `==> call` arrows into the same frame; one `& `-joined `return` ribbon back to both wrappers.
+
+#### Case 2: `A ∪ B ∪ C` (three bares, all share X directly)
+
+```text
+reach(A) = {A, X}
+reach(B) = {B, X}
+reach(C) = {C, X}
+Every pair intersects on X → all merge.
+```
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","1","2","3"]]
+  s0(((halt)))
+  s13["t1"]
+  s14["t2"]
+  s15["t3"]
+  s19["dispatcher"]
+  s16[["A(t1)"]]
+  s17[["B(t2)"]]
+  s18[["C(t3)"]]
+  idle([idle])
+  subgraph w_10["callable scope: A ∪ B ∪ C"]
+    s9["X"]
+    s10["A"]
+    s11["B"]
+    s12["C"]
+    c10(((halt)))
+  end
+  idle -. enter .-> s19
+  s16 == "call" ==> s10
+  s17 == "call" ==> s11
+  s18 == "call" ==> s12
+  w_10 -. "return" .-> s16 & s17 & s18
+  s16 --> s13
+  s17 --> s14
+  s18 --> s15
+  s9 -- "[*] → [K]/[S]" --> c10
+  s10 -- "[*] → [K]/[R]" --> s9
+  s11 -- "[*] → [K]/[R]" --> s9
+  s12 -- "[*] → [K]/[R]" --> s9
+  s13 -- "[*] → [K]/[S]" --> s0
+  s14 -- "[*] → [K]/[S]" --> s0
+  s15 -- "[*] → [K]/[S]" --> s0
+  s19 -- "['1'] → [K]/[S]" --> s16
+  s19 -- "['2'] → [K]/[S]" --> s17
+  s19 -- "['3'] → [K]/[S]" --> s18
+```
+
+Three `call` arrows, one three-way `& `-joined `return` ribbon. Same frame, one halt marker.
+
+#### Case 3: `(A ∪ B) ∪ C` — transitive (B and C don't share anything direct)
+
+```text
+reach(A) = {A, X, Y}
+reach(B) = {B, X}
+reach(C) = {C, Y}
+A ∩ B = {X}   → union(A, B)
+A ∩ C = {Y}   → union(A, C)  ← C joins {A, B} via A
+B ∩ C = ∅     ← but they end up in the same frame anyway, transitively
+```
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","1","2","3"]]
+  s0(((halt)))
+  s25["t1"]
+  s26["t2"]
+  s27["t3"]
+  s31["dispatcher"]
+  s28[["A(t1)"]]
+  s29[["B(t2)"]]
+  s30[["C(t3)"]]
+  idle([idle])
+  subgraph w_22["callable scope: A ∪ B ∪ C"]
+    s20["X"]
+    s21["Y"]
+    s22["A"]
+    s23["B"]
+    s24["C"]
+    c22(((halt)))
+  end
+  idle -. enter .-> s31
+  s28 == "call" ==> s22
+  s29 == "call" ==> s23
+  s30 == "call" ==> s24
+  w_22 -. "return" .-> s28 & s29 & s30
+  s28 --> s25
+  s29 --> s26
+  s30 --> s27
+  s20 -- "[*] → [K]/[S]" --> c22
+  s21 -- "[*] → [K]/[S]" --> c22
+  s22 -- "['1'] → [K]/[R]" --> s20
+  s22 -- "['2'] → [K]/[R]" --> s21
+  s23 -- "[*] → [K]/[R]" --> s20
+  s24 -- "[*] → [K]/[R]" --> s21
+  s25 -- "[*] → [K]/[S]" --> s0
+  s26 -- "[*] → [K]/[S]" --> s0
+  s27 -- "[*] → [K]/[S]" --> s0
+  s31 -- "['1'] → [K]/[S]" --> s28
+  s31 -- "['2'] → [K]/[S]" --> s29
+  s31 -- "['3'] → [K]/[S]" --> s30
+```
+
+Two shared body states (X, Y). B reaches X only; C reaches Y only. They never see each other directly — yet they live in the same frame because A bridges them. The union-find transitive-closure step is what bundles them.
+
+**Reading rule encoded in the emit:** one subgraph = one union component. The label tells you how many bares share the scope. `& `-joined `call` / `return` arrows tell you how many wrappers are in play (always one per wrapper; the union collapses bares, never wrappers).
+
 ## Data model changes
 
 The callable-subtree model **un-collapses what v7 alpha.1 collapsed**. In alpha.1, each `withOverriddenHaltState` wrapper produces ONE `GraphNode` representing both the wrapper and its bare (the bare is "collapsed onto" the wrapper's id, with `isWrapped: true`). Under the new model, **wrappers and bares are separate `GraphNode` instances**:

From 401b80a193b2a3d1458cbf6fc46b57ee18146841 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 15:03:58 +0300
Subject: [PATCH 024/118] test(spec): invariant + snapshot tests for the worked
 union shapes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three new tests in `graph.spec.ts > spec doc: worked union shapes are
real engine emit`, one per case (A∪B, A∪B∪C, transitive (A∪B)∪C).

Each test combines:

1. **Invariant assertions** — model-level rules the union-find algorithm
   must preserve. Named expectations point at the broken rule when they
   fail:
   - All bares in a case share one `frameId`
   - Frame-label string is correct ("callable scope: A ∪ B" etc.)
   - Number of `== "call" ==>` arrows = number of wrappers (each wrapper
     has a distinct bare, so no call-side ribbon collapse)
   - Return arrow is one `& `-joined ribbon over all wrappers
   - No `-. "halt" .->` arrow (no non-wrapper entry to the frame)

2. **Snapshot test** — pins the exact emit shape (with state IDs
   normalized via `stripIds`, same approach as `test/round-trip.spec.ts`).
   Snapshot failure = the spec doc's "this is real engine emit" claim
   went stale, either because the engine drifted cosmetically or
   because the doc itself was edited out-of-sync.

The two layers catch different failure modes:
- Invariant alone: misses cosmetic drift between doc and engine.
- Snapshot alone: fails opaquely on rule breaks ("strings differ").
- Both: when invariant fails, the failure NAMES the broken rule. When
  snapshot fails but invariants pass, drift is purely cosmetic.

Probe-source for these examples is `/tmp/union-probe.mjs` (not committed;
the source-of-truth is now the test fixtures).
---
 packages/machine/src/utilities/graph.spec.ts | 256 +++++++++++++++++++
 1 file changed, 256 insertions(+)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index ede42d9..c99e7b8 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -651,3 +651,259 @@ describe('callable-subtree: shared body state forces a union frame', () => {
     expect(out).toMatch(/s\d+ == "call" ==> s\d+/g);
   });
 });
+
+// Spec-doc invariants + snapshots for the three worked union shapes in
+// `docs/superpowers/specs/2026-05-21-halt-frame-transitive-closure.md`'s
+// "Worked union shapes — engine-emitted Mermaid" section.
+//
+// The spec doc claims its Mermaid blocks are real engine emit (not
+// hand-drawn). These tests enforce that claim two ways:
+//   1. Invariant tests assert the structural rules the model promises
+//      (frame merging, ribbon collapse, demand-emit arrows). Named tests
+//      → failures point at the broken rule, not at a byte diff.
+//   2. Snapshot tests (with id normalization, same shape as the
+//      round-trip test) pin the cosmetic emit. Failures here catch drift
+//      between the doc and the engine — either rerun the probe + update
+//      the doc, or revert the unintended emit change.
+//
+// Normalize all `s\d+`, `c\d+`, `w_\d+` to `sX`/`cX`/`w_X` since global
+// State.#id is shared across tests and isn't stable across test-ordering
+// changes. Same normalization used by `test/round-trip.spec.ts`.
+function stripIds(mermaid: string): string {
+  return mermaid
+    .replace(/\bs\d+\b/g, 'sX')
+    .replace(/\bc\d+\b/g, 'cX')
+    .replace(/\bw_\d+\b/g, 'w_X');
+}
+
+describe('spec doc: worked union shapes are real engine emit', () => {
+  // Reusable target factory — each test needs N small halting States as
+  // wrapper targets. Inlining the State construction directly would clutter
+  // each test.
+  const haltingTarget = (name: string) => new State({
+    [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+  }, name);
+
+  test('Case 1: A ∪ B (two bares, one shared body state X)', () => {
+    const alphabet = new Alphabet([' ', '1', '2']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    const X = haltingTarget('X');
+    const A = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'A');
+    const B = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'B');
+    const W1 = A.withOverriddenHaltState(haltingTarget('t1'));
+    const W2 = B.withOverriddenHaltState(haltingTarget('t2'));
+    const dispatcher = new State({
+      [symbol(['1'])]: {command: {movement: movements.stay}, nextState: W1},
+      [symbol(['2'])]: {command: {movement: movements.stay}, nextState: W2},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+    const out = toMermaid(graph);
+
+    // Invariants — A, B distinct bares so call arrows are NOT ribbon-collapsed
+    // (the `& ` ribbon on calls collapses only wrappers SHARING a bare).
+    expect(graph.nodes[A.id].frameId).toBe(graph.nodes[B.id].frameId);
+    expect(graph.nodes[X.id].frameId).toBe(graph.nodes[A.id].frameId);
+    expect(out).toContain('"callable scope: A ∪ B"');
+    expect(out.match(/== "call" ==>/g)).toHaveLength(2); // one per wrapper
+    expect(out).toMatch(/w_\d+ -\. "return" \.-> s\d+ & s\d+/); // ribbon on return side
+    expect(out).not.toMatch(/-\. "halt" \.->/); // no non-wrapper entry to frame
+
+    // Snapshot (id-normalized). Doubles as the cosmetic-drift detector for
+    // the matching block in the spec doc.
+    const expected = [
+      'flowchart TD',
+      '%% alphabets: [[" ","1","2"]]',
+      '  sX(((halt)))',
+      '  sX["t1"]',
+      '  sX["t2"]',
+      '  sX["dispatcher"]',
+      '  sX[["A(t1)"]]',
+      '  sX[["B(t2)"]]',
+      '  idle([idle])',
+      '  subgraph w_X["callable scope: A ∪ B"]',
+      '    sX["X"]',
+      '    sX["A"]',
+      '    sX["B"]',
+      '    cX(((halt)))',
+      '  end',
+      '  idle -. enter .-> sX',
+      '  sX == "call" ==> sX',
+      '  sX == "call" ==> sX',
+      '  w_X -. "return" .-> sX & sX',
+      '  sX --> sX',
+      '  sX --> sX',
+      '  sX -- "[*] → [K]/[S]" --> cX',
+      '  sX -- "[*] → [K]/[R]" --> sX',
+      '  sX -- "[*] → [K]/[R]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      "  sX -- \"['1'] → [K]/[S]\" --> sX",
+      "  sX -- \"['2'] → [K]/[S]\" --> sX",
+    ].join('\n');
+
+    expect(stripIds(out)).toBe(expected);
+  });
+
+  test('Case 2: A ∪ B ∪ C (three bares, all share X directly)', () => {
+    const alphabet = new Alphabet([' ', '1', '2', '3']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    const X = haltingTarget('X');
+    const A = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'A');
+    const B = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'B');
+    const C = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'C');
+    const W1 = A.withOverriddenHaltState(haltingTarget('t1'));
+    const W2 = B.withOverriddenHaltState(haltingTarget('t2'));
+    const W3 = C.withOverriddenHaltState(haltingTarget('t3'));
+    const dispatcher = new State({
+      [symbol(['1'])]: {command: {movement: movements.stay}, nextState: W1},
+      [symbol(['2'])]: {command: {movement: movements.stay}, nextState: W2},
+      [symbol(['3'])]: {command: {movement: movements.stay}, nextState: W3},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+    const out = toMermaid(graph);
+
+    // Invariants
+    const frameA = graph.nodes[A.id].frameId;
+
+    expect(frameA).not.toBeNull();
+    expect(graph.nodes[B.id].frameId).toBe(frameA);
+    expect(graph.nodes[C.id].frameId).toBe(frameA);
+    expect(graph.nodes[X.id].frameId).toBe(frameA);
+    expect(out).toContain('"callable scope: A ∪ B ∪ C"');
+    expect(out.match(/== "call" ==>/g)).toHaveLength(3); // one per wrapper, no ribbon
+    expect(out).toMatch(/w_\d+ -\. "return" \.-> s\d+ & s\d+ & s\d+/);
+    expect(out).not.toMatch(/-\. "halt" \.->/);
+
+    const expected = [
+      'flowchart TD',
+      '%% alphabets: [[" ","1","2","3"]]',
+      '  sX(((halt)))',
+      '  sX["t1"]',
+      '  sX["t2"]',
+      '  sX["t3"]',
+      '  sX["dispatcher"]',
+      '  sX[["A(t1)"]]',
+      '  sX[["B(t2)"]]',
+      '  sX[["C(t3)"]]',
+      '  idle([idle])',
+      '  subgraph w_X["callable scope: A ∪ B ∪ C"]',
+      '    sX["X"]',
+      '    sX["A"]',
+      '    sX["B"]',
+      '    sX["C"]',
+      '    cX(((halt)))',
+      '  end',
+      '  idle -. enter .-> sX',
+      '  sX == "call" ==> sX',
+      '  sX == "call" ==> sX',
+      '  sX == "call" ==> sX',
+      '  w_X -. "return" .-> sX & sX & sX',
+      '  sX --> sX',
+      '  sX --> sX',
+      '  sX --> sX',
+      '  sX -- "[*] → [K]/[S]" --> cX',
+      '  sX -- "[*] → [K]/[R]" --> sX',
+      '  sX -- "[*] → [K]/[R]" --> sX',
+      '  sX -- "[*] → [K]/[R]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      "  sX -- \"['1'] → [K]/[S]\" --> sX",
+      "  sX -- \"['2'] → [K]/[S]\" --> sX",
+      "  sX -- \"['3'] → [K]/[S]\" --> sX",
+    ].join('\n');
+
+    expect(stripIds(out)).toBe(expected);
+  });
+
+  test('Case 3: (A ∪ B) ∪ C — transitive (A bridges B and C via X and Y)', () => {
+    const alphabet = new Alphabet([' ', '1', '2', '3']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    const X = haltingTarget('X');
+    const Y = haltingTarget('Y');
+    // A has TWO transitions — one to X (overlapping B's reach), one to Y
+    // (overlapping C's reach). B and C share nothing directly.
+    const A = new State({
+      [symbol(['1'])]: {command: {movement: movements.right}, nextState: X},
+      [symbol(['2'])]: {command: {movement: movements.right}, nextState: Y},
+    }, 'A');
+    const B = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'B');
+    const C = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: Y}}, 'C');
+    const W1 = A.withOverriddenHaltState(haltingTarget('t1'));
+    const W2 = B.withOverriddenHaltState(haltingTarget('t2'));
+    const W3 = C.withOverriddenHaltState(haltingTarget('t3'));
+    const dispatcher = new State({
+      [symbol(['1'])]: {command: {movement: movements.stay}, nextState: W1},
+      [symbol(['2'])]: {command: {movement: movements.stay}, nextState: W2},
+      [symbol(['3'])]: {command: {movement: movements.stay}, nextState: W3},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+    const out = toMermaid(graph);
+
+    // Invariants — transitive merge is the load-bearing rule.
+    const frameA = graph.nodes[A.id].frameId;
+
+    expect(frameA).not.toBeNull();
+    expect(graph.nodes[B.id].frameId).toBe(frameA);
+    expect(graph.nodes[C.id].frameId).toBe(frameA);
+    expect(graph.nodes[X.id].frameId).toBe(frameA);
+    expect(graph.nodes[Y.id].frameId).toBe(frameA); // critical: B-C don't share directly
+    expect(out).toContain('"callable scope: A ∪ B ∪ C"');
+    expect(out.match(/== "call" ==>/g)).toHaveLength(3);
+    expect(out).toMatch(/w_\d+ -\. "return" \.-> s\d+ & s\d+ & s\d+/);
+    expect(out).not.toMatch(/-\. "halt" \.->/);
+
+    const expected = [
+      'flowchart TD',
+      '%% alphabets: [[" ","1","2","3"]]',
+      '  sX(((halt)))',
+      '  sX["t1"]',
+      '  sX["t2"]',
+      '  sX["t3"]',
+      '  sX["dispatcher"]',
+      '  sX[["A(t1)"]]',
+      '  sX[["B(t2)"]]',
+      '  sX[["C(t3)"]]',
+      '  idle([idle])',
+      '  subgraph w_X["callable scope: A ∪ B ∪ C"]',
+      '    sX["X"]',
+      '    sX["Y"]',
+      '    sX["A"]',
+      '    sX["B"]',
+      '    sX["C"]',
+      '    cX(((halt)))',
+      '  end',
+      '  idle -. enter .-> sX',
+      '  sX == "call" ==> sX',
+      '  sX == "call" ==> sX',
+      '  sX == "call" ==> sX',
+      '  w_X -. "return" .-> sX & sX & sX',
+      '  sX --> sX',
+      '  sX --> sX',
+      '  sX --> sX',
+      '  sX -- "[*] → [K]/[S]" --> cX',
+      '  sX -- "[*] → [K]/[S]" --> cX',
+      "  sX -- \"['1'] → [K]/[R]\" --> sX",
+      "  sX -- \"['2'] → [K]/[R]\" --> sX",
+      '  sX -- "[*] → [K]/[R]" --> sX',
+      '  sX -- "[*] → [K]/[R]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      '  sX -- "[*] → [K]/[S]" --> sX',
+      "  sX -- \"['1'] → [K]/[S]\" --> sX",
+      "  sX -- \"['2'] → [K]/[S]\" --> sX",
+      "  sX -- \"['3'] → [K]/[S]\" --> sX",
+    ].join('\n');
+
+    expect(stripIds(out)).toBe(expected);
+  });
+});

From 3a7107013542a83b2bf8d14515233d4ec7b903e2 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 17:37:46 +0300
Subject: [PATCH 025/118] feat(state): first-class tag/label support on State +
 GraphNode + Mermaid emit (#186)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an out-of-band annotation channel on State that survives toGraph /
fromGraph / toMermaid / fromMermaid round-trips, drives Mermaid color
classes, and renders tag names inline in node labels via `<br>` for
universal renderer support.

State API
---------
- `state.tag(...tags: string[]): this` — chainable, idempotent.
- `state.untag(...tags: string[]): this` — chainable, no-op on absent.
- `state.tags: readonly string[]` — frozen snapshot, insertion order.

Tags live on the State INSTANCE, not on the shared `#symbolToDataMap`.
Under engine #175 memoization, `A.wohs(t1)` and `A.wohs(t2)` are
distinct wrapper instances; tagging one doesn't propagate to siblings
sharing the same bare. Verified in State.spec.ts.

GraphNode + serialization
-------------------------
- `GraphNode.tags: string[]` — round-trips through toGraph/fromGraph.
- toMermaid emits:
  - Node labels with inline `<br>tag1, tag2` suffix (visible in any
    renderer — universal Mermaid `<br>` works across mermaid.js, the
    live editor, machines-demo).
  - `classDef tag_<sanitized> fill:#...,stroke:#...` per unique tag,
    chosen from a 6-color hash-based palette.
  - `class s5,s6 tag_<sanitized>` listing all node IDs carrying the
    tag (comma-joined for compact emit).
- fromMermaid parses the label's `<br>` suffix as the source of truth
  for tags; `class` lines are decorative and discarded on parse
  (they regenerate on next toMermaid emit from the tag set).
- Tag-name sanitization: chars outside [A-Za-z0-9_-] replaced with `_`
  in CSS classDef identifiers. Labels preserve raw tag names.

Sharing semantics
-----------------
- Tag-set is sidecar; doesn't affect equivalentOn or transition lookup.
- Wrappers from `withOverriddenHaltState` start with an empty tag set
  (do not inherit from bare). Caller explicitly tags as desired.

Files
-----
- packages/machine/src/classes/State.ts — `#tags` field + public API +
  toGraph reads + fromGraph applies tags
- packages/machine/src/utilities/graph.ts — `GraphNode.tags: string[]`
- packages/machine/src/utilities/graphFormats.ts — `labelOf()` helper
  for `<br>`-embedded emit; `emitTagAnnotations()` for classDef/class;
  `splitLabelTags()` for parse; classDef + class line regexes
- Tests: 8 in State.spec.ts; 4 toMermaid + 2 fromMermaid in graph.spec.ts;
  hand-built GraphNode fixtures across 3 spec files updated to include
  `tags: []` (bulk sed)

Verification
------------
- npm test — 456/456 pass (450 prior + 14 new tag tests)
- npm run lint — clean
- npm run typecheck — clean
- npm run test:coverage — 98.42 stmts / 95.08 branch / 100 funcs /
  99.04 lines (above engine floors of 97/90/95/97)

Closes #186 (carry on the release PR — v7-branch merges don't auto-close).
---
 packages/machine/src/classes/State.spec.ts    |  97 ++++++++++-
 packages/machine/src/classes/State.ts         |  62 +++++++
 packages/machine/src/utilities/graph.spec.ts  | 114 ++++++++++++-
 packages/machine/src/utilities/graph.ts       |   5 +
 .../machine/src/utilities/graphFormats.ts     | 156 +++++++++++++++++-
 .../src/utilities/introspection.spec.ts       |  28 ++--
 6 files changed, 430 insertions(+), 32 deletions(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index a912171..9dfbb95 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -332,6 +332,95 @@ describe('State.toGraph — unbound Reference', () => {
   });
 });
 
+describe('State tags (#186)', () => {
+  test('a fresh State has an empty tags array', () => {
+    const s = new State({[ifOtherSymbol]: {nextState: haltState}});
+
+    expect(s.tags).toEqual([]);
+  });
+
+  test('tag() adds tags and is chainable', () => {
+    const s = new State({[ifOtherSymbol]: {nextState: haltState}});
+
+    const ret = s.tag('hot', 'sampled');
+
+    expect(ret).toBe(s);
+    expect(s.tags).toEqual(['hot', 'sampled']);
+  });
+
+  test('tag() de-duplicates repeated tags', () => {
+    const s = new State({[ifOtherSymbol]: {nextState: haltState}});
+
+    s.tag('hot');
+    s.tag('hot', 'cold');
+
+    expect(s.tags).toEqual(['hot', 'cold']);
+  });
+
+  test('untag() removes tags and is chainable', () => {
+    const s = new State({[ifOtherSymbol]: {nextState: haltState}});
+
+    s.tag('hot', 'sampled', 'cold');
+    const ret = s.untag('hot');
+
+    expect(ret).toBe(s);
+    expect(s.tags).toEqual(['sampled', 'cold']);
+  });
+
+  test('untag() of a non-present tag is a no-op', () => {
+    const s = new State({[ifOtherSymbol]: {nextState: haltState}});
+
+    s.tag('a');
+    s.untag('not-present');
+
+    expect(s.tags).toEqual(['a']);
+  });
+
+  test('tags getter returns a frozen snapshot — caller cannot mutate', () => {
+    const s = new State({[ifOtherSymbol]: {nextState: haltState}});
+
+    s.tag('a');
+    const snapshot = s.tags;
+
+    expect(() => {
+      (snapshot as unknown as string[]).push('b');
+    }).toThrow();
+
+    expect(s.tags).toEqual(['a']);
+  });
+
+  test('tags are scoped to the wrapper instance, not the shared bare (#175 sharing)', () => {
+    // Engine #175 memoization means `A.wohs(t1)` and `A.wohs(t2)` produce
+    // distinct wrapper instances even though they share the same `#symbolToDataMap`.
+    // Tags must live on the wrapper instance — tagging one wrapper must NOT
+    // propagate to siblings sharing the same bare.
+    const A = new State({[ifOtherSymbol]: {nextState: haltState}}, 'A');
+    const t1 = new State({[ifOtherSymbol]: {nextState: haltState}}, 't1');
+    const t2 = new State({[ifOtherSymbol]: {nextState: haltState}}, 't2');
+
+    const W1 = A.withOverriddenHaltState(t1);
+    const W2 = A.withOverriddenHaltState(t2);
+
+    W1.tag('hot');
+
+    expect(W1.tags).toEqual(['hot']);
+    expect(W2.tags).toEqual([]); // no leak across wrappers sharing a bare
+    expect(A.tags).toEqual([]);  // no leak to the bare either
+  });
+
+  test('haltState is not specially excluded from tagging', () => {
+    // No reason to forbid tagging haltState. Engine doesn't impose a tag
+    // semantic, so tagging the halt singleton is the consumer's call.
+    haltState.tag('halt-debug-marker');
+
+    expect(haltState.tags).toContain('halt-debug-marker');
+
+    // Cleanup so other tests don't see the residue.
+    haltState.untag('halt-debug-marker');
+    expect(haltState.tags).not.toContain('halt-debug-marker');
+  });
+});
+
 describe('State.fromGraph — cyclic override-halt chain', () => {
   test('throws when the override-halt graph has a cycle', () => {
     // Under the v7 callable-subtree model, override-halt chains live on
@@ -343,10 +432,10 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'wA', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: true, bareStateId: 3, frameId: null},
-        2: {id: 2, name: 'wB', isHalt: false, transitions: [], overriddenHaltStateId: 1, isHaltMarker: false, isWrapper: true, bareStateId: 3, frameId: null},
-        3: {id: 3, name: 'shared', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        1: {id: 1, name: 'wA', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: true, bareStateId: 3, frameId: null, tags: []},
+        2: {id: 2, name: 'wB', isHalt: false, transitions: [], overriddenHaltStateId: 1, isHaltMarker: false, isWrapper: true, bareStateId: 3, frameId: null, tags: []},
+        3: {id: 3, name: 'shared', isHalt: false, transitions: [dummyTransition], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
       },
     };
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 10491b5..81e91ed 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -102,6 +102,15 @@ export default class State {
   // a runtime concern, not part of the structural graph.
   #debugRef: { current: DebugConfig | null } = {current: null};
 
+  // Out-of-band tags applied to this State (#186). Tags are visualization
+  // and debugger-tooling metadata — they don't affect runtime transition
+  // lookup or `equivalentOn` comparisons. Stored as a Set for de-duplication;
+  // exposed via the `tags` getter as a frozen array snapshot. Lives on the
+  // State INSTANCE so wrappers (from `withOverriddenHaltState`) carry tags
+  // independently of their bare's tag set — see the #175 sharing test in
+  // State.spec.ts.
+  #tags: Set<string> = new Set();
+
   constructor(stateDefinition: Record<string | symbol, {
     command?: Command | ConstructorParameters<typeof TapeCommand>[0] | ConstructorParameters<typeof TapeCommand>[0][],
     nextState?: State | Reference,
@@ -216,6 +225,41 @@ export default class State {
     this.#debugRef.current = new DebugConfig(this, value);
   }
 
+  /**
+   * Add one or more tags to this State (#186). Tags are out-of-band metadata
+   * used by visualization (`toMermaid` emits `classDef`/`class` lines) and
+   * debugger tooling — they don't affect runtime transition lookup,
+   * `equivalentOn` comparisons, or any structural identity. Chainable.
+   */
+  tag(...tags: string[]): this {
+    for (const t of tags) {
+      this.#tags.add(t);
+    }
+
+    return this;
+  }
+
+  /**
+   * Remove one or more tags from this State (#186). Untagging a tag the
+   * State doesn't carry is a no-op. Chainable.
+   */
+  untag(...tags: string[]): this {
+    for (const t of tags) {
+      this.#tags.delete(t);
+    }
+
+    return this;
+  }
+
+  /**
+   * Frozen snapshot of this State's current tags (#186). The returned array
+   * is `Object.freeze`d — mutating it throws in strict mode (which TS-emitted
+   * code uses). Order matches insertion order of the underlying Set.
+   */
+  get tags(): readonly string[] {
+    return Object.freeze([...this.#tags]);
+  }
+
   /** @internal — invoked by DebugConfig setters via module-private symbol. */
   [validateDebugFilter](
     fieldName: 'before' | 'after',
@@ -429,6 +473,7 @@ export default class State {
             frameId: null,
             transitions: [],
             overriddenHaltStateId: null,
+            tags: [...state.#tags],
           };
         }
 
@@ -450,6 +495,7 @@ export default class State {
           frameId: null,
           transitions: [],
           overriddenHaltStateId: overrideTarget.#id,
+          tags: [...state.#tags],
         };
 
         bareIds.add(bareState.#id);
@@ -470,6 +516,7 @@ export default class State {
         frameId: null,
         transitions: [],
         overriddenHaltStateId: null,
+        tags: [...state.#tags],
       };
 
       nodes[state.#id] = node;
@@ -515,6 +562,7 @@ export default class State {
         frameId: null,
         transitions: [],
         overriddenHaltStateId: null,
+        tags: [...haltState.#tags],
       };
     }
 
@@ -672,6 +720,7 @@ export default class State {
         frameId,
         transitions: [],
         overriddenHaltStateId: null,
+        tags: [],
       };
     }
 
@@ -764,6 +813,11 @@ export default class State {
       const bare = new State(stateDefinition);
 
       bare.#name = node.name;
+
+      if (node.tags.length > 0) {
+        bare.tag(...node.tags);
+      }
+
       bareStates[nodeId] = bare;
     }
 
@@ -799,6 +853,14 @@ export default class State {
         const override = getFinal(node.overriddenHaltStateId!);
 
         state = bare.withOverriddenHaltState(override);
+
+        // Apply wrapper-scoped tags (#186). Tags don't leak across wrappers
+        // sharing a bare — the wrapper instance owns its own tag set, and
+        // engine #175 memoization returns the same instance for the same
+        // (bare, override) pair, so this is idempotent across rebuilds.
+        if (node.tags.length > 0) {
+          state.tag(...node.tags);
+        }
       } else {
         state = bareStates[nodeId];
       }
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index c99e7b8..72255c2 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -118,9 +118,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: [],
           transitions: [
             {pattern: "'0'", command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
             {pattern: "'1'", command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
@@ -147,8 +147,8 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isHaltMarker: false, isWrapper: true, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        1: {id: 1, name: 'wrapper', isHalt: false, transitions: [], overriddenHaltStateId: 0, isHaltMarker: false, isWrapper: true, bareStateId: null, frameId: null, tags: []},
       },
     });
 
@@ -161,9 +161,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        1: {id: 1, name: 'entry', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        2: {id: 2, name: 'helper', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
       },
     });
 
@@ -175,9 +175,9 @@ describe('toMermaid', () => {
       initialId: 1,
       alphabets: [[' ', '0'], [' ', 'a']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
         1: {
-          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'entry', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: [],
           transitions: [{
             pattern: "'0','a'",
             command: [{symbol: "'0'", movement: 'R'}, {symbol: "'a'", movement: 'L'}],
@@ -907,3 +907,99 @@ describe('spec doc: worked union shapes are real engine emit', () => {
     expect(stripIds(out)).toBe(expected);
   });
 });
+
+describe('toMermaid: tags (#186)', () => {
+  test('no tags → no classDef / class lines', () => {
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'plain');
+
+    const out = toMermaid(State.toGraph(s, tapeBlock));
+
+    expect(out).not.toContain('classDef');
+    expect(out).not.toContain('class ');
+  });
+
+  test('one tag → one classDef + matching class assignment', () => {
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'tagged').tag('hot');
+
+    const out = toMermaid(State.toGraph(s, tapeBlock));
+
+    expect(out).toMatch(/classDef tag_hot /);
+    expect(out).toMatch(/class s\d+ tag_hot/);
+  });
+
+  test('multiple states sharing a tag → one classDef, comma-joined ids in class', () => {
+    const alphabet = new Alphabet([' ', '0', '1']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+    const b = new State({
+      [symbol(['1'])]: {nextState: haltState},
+    }, 'b').tag('hot');
+    const a = new State({
+      [symbol(['0'])]: {nextState: b},
+    }, 'a').tag('hot');
+
+    const out = toMermaid(State.toGraph(a, tapeBlock));
+
+    expect((out.match(/classDef tag_hot /g) ?? []).length).toBe(1);
+    // Two states share the tag — emitted on one `class` line with
+    // comma-joined ids.
+    expect(out).toMatch(/class s\d+,s\d+ tag_hot/);
+  });
+
+  test('multiple tags on one state → one class line per tag', () => {
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'tagged').tag('hot', 'sampled');
+
+    const out = toMermaid(State.toGraph(s, tapeBlock));
+
+    expect(out).toMatch(/classDef tag_hot /);
+    expect(out).toMatch(/classDef tag_sampled /);
+    expect(out).toMatch(/class s\d+ tag_hot/);
+    expect(out).toMatch(/class s\d+ tag_sampled/);
+  });
+});
+
+describe('fromMermaid: tags (#186)', () => {
+  test('parses classDef + class lines back into GraphNode.tags', () => {
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0"]]',
+      '  s0(((halt)))',
+      '  s1["a"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      "  s1 -- \"['0'] → [K]/[S]\" --> s0",
+      '  classDef tag_hot fill:#fef3c7',
+      '  class s1 tag_hot',
+    ].join('\n');
+
+    const graph = fromMermaid(mermaid);
+
+    expect(graph.nodes[1].tags).toEqual(['hot']);
+    expect(graph.nodes[0].tags).toEqual([]);
+  });
+
+  test('multi-tag round-trip preserves order', () => {
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'rt').tag('alpha', 'beta');
+
+    const emitted = toMermaid(State.toGraph(s, tapeBlock));
+    const reparsed = fromMermaid(emitted);
+
+    expect(reparsed.nodes[s.id].tags).toEqual(['alpha', 'beta']);
+  });
+});
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index d5a4dd3..2e414e9 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -49,6 +49,11 @@ export type GraphNode = {
   // `haltState`. Halt marker id = `-frameId` (sits in disjoint negative-id
   // range from real node ids).
   isHaltMarker: boolean;
+  // Out-of-band tags applied to this State (#186). Empty array if untagged.
+  // Survives `toGraph`/`fromGraph` round-trip and renders in `toMermaid` as
+  // `classDef tag_<name>` + `class sN tag_<name>` lines. Doesn't affect
+  // runtime semantics — purely a visualization/debugger-tooling channel.
+  tags: string[];
 };
 
 export type Graph = {
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 364ad61..981b9ef 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -83,6 +83,17 @@ export function toMermaid(graph: Graph): string {
     }
   }
 
+  // Build the visible-label string for a node — name plus, if tagged, a
+  // `<br>tag1, tag2, ...` suffix so the rendered Mermaid shows both. Tags
+  // are the source of truth on the GraphNode; `<br>` is the universal
+  // Mermaid line-break that works across renderers without `classDef`-
+  // pseudo-element hacks (#186).
+  const labelOf = (node: GraphNode): string => {
+    if (node.tags.length === 0) return node.name;
+
+    return `${node.name}<br>${node.tags.join(', ')}`;
+  };
+
   // 1. Emit top-level nodes (real halt, non-wrapper regulars outside any frame).
   for (const node of topLevelNodes) {
     const mid = mermaidIdFor(node.id);
@@ -90,13 +101,13 @@ export function toMermaid(graph: Graph): string {
     if (node.isHalt) {
       lines.push(`  ${mid}(((halt)))`);
     } else {
-      lines.push(`  ${mid}["${node.name}"]`);
+      lines.push(`  ${mid}["${labelOf(node)}"]`);
     }
   }
 
   // 2. Emit wrappers at top level.
   for (const wrapper of wrapperNodes) {
-    lines.push(`  ${mermaidIdFor(wrapper.id)}[["${wrapper.name}"]]`);
+    lines.push(`  ${mermaidIdFor(wrapper.id)}[["${labelOf(wrapper)}"]]`);
   }
 
   // 3. `idle` sentinel.
@@ -121,7 +132,7 @@ export function toMermaid(graph: Graph): string {
 
     // Inner nodes — sort by id for determinism.
     for (const node of (nodesByFrame.get(frameId) ?? []).slice().sort((a, b) => a.id - b.id)) {
-      lines.push(`    ${mermaidIdFor(node.id)}["${node.name}"]`);
+      lines.push(`    ${mermaidIdFor(node.id)}["${labelOf(node)}"]`);
     }
 
     const haltMarker = haltMarkerByFrame.get(frameId);
@@ -249,9 +260,83 @@ export function toMermaid(graph: Graph): string {
     }
   }
 
+  // 10. Tags (#186) — emit one `classDef tag_<name> fill:#...` per unique
+  //     tag across all nodes, then one `class <ids> tag_<name>` line per
+  //     tag listing every node that carries it (comma-joined for compact
+  //     emit). Tag-name → CSS-class identifier sanitization replaces any
+  //     char outside `[A-Za-z0-9_-]` with `_`; tag-name uniqueness in the
+  //     emit assumes user tags are already distinct after sanitization
+  //     (collisions are user error).
+  emitTagAnnotations(lines, nodes);
+
   return lines.join('\n');
 }
 
+// Default Mermaid `classDef` palette — 6 visually distinct fill+stroke pairs,
+// selected by tag-name hash so multi-tag diagrams look readable out of the
+// box without user configuration. Users who want different colors can edit
+// the emitted Mermaid before rendering or override post-emit.
+const TAG_PALETTE: ReadonlyArray<readonly [string, string]> = [
+  ['#fef3c7', '#92400e'], // amber
+  ['#dbeafe', '#1e40af'], // blue
+  ['#dcfce7', '#166534'], // green
+  ['#fce7f3', '#9d174d'], // pink
+  ['#ede9fe', '#5b21b6'], // violet
+  ['#fee2e2', '#991b1b'], // red
+];
+
+function sanitizeTagName(tag: string): string {
+  return tag.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+
+function tagColor(tag: string): readonly [string, string] {
+  // Cheap deterministic hash — sum of char codes mod palette length. Stable
+  // across runs; same tag name always picks the same color.
+  let h = 0;
+
+  for (let i = 0; i < tag.length; i += 1) {
+    h = (h + tag.charCodeAt(i)) % TAG_PALETTE.length;
+  }
+
+  return TAG_PALETTE[h];
+}
+
+function emitTagAnnotations(lines: string[], nodes: GraphNode[]): void {
+  // Collect nodes per tag in node-id order so output is deterministic.
+  const nodesByTag = new Map<string, number[]>();
+
+  for (const node of nodes) {
+    for (const tag of node.tags) {
+      let list = nodesByTag.get(tag);
+
+      if (!list) {
+        list = [];
+        nodesByTag.set(tag, list);
+      }
+
+      list.push(node.id);
+    }
+  }
+
+  if (nodesByTag.size === 0) return;
+
+  const sortedTags = [...nodesByTag.keys()].sort();
+
+  for (const tag of sortedTags) {
+    const sanitized = sanitizeTagName(tag);
+    const [fill, stroke] = tagColor(tag);
+
+    lines.push(`  classDef tag_${sanitized} fill:${fill},stroke:${stroke}`);
+  }
+
+  for (const tag of sortedTags) {
+    const sanitized = sanitizeTagName(tag);
+    const ids = nodesByTag.get(tag)!.map((id) => mermaidIdFor(id)).join(',');
+
+    lines.push(`  class ${ids} tag_${sanitized}`);
+  }
+}
+
 // Helper: identify "the bare states" that anchor a frame's name. A bare is a
 // node referenced as some wrapper's `bareStateId`. Body states (also in-frame
 // but not bare) are excluded from the frame label.
@@ -301,6 +386,32 @@ const haltArrowRegex = /^w_(\d+)\s+-\.\s+"halt"\s+\.->\s+s0$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
 // the preceding \s* and a permissive (.+); see CodeQL js/polynomial-redos.
 const alphabetsRegex = /^%%\s*alphabets:\s*(\S.*)$/;
+// Tag annotation lines (#186). Matches both `classDef tag_<sanitized>` and
+// `class <id-list> tag_<sanitized>`. ClassDef declarations are decorative
+// (palette) and discarded on parse — toMermaid will regenerate them from
+// the tag set on re-emit. `class` lines carry the actual graph-node
+// assignments; we strip the `tag_` prefix and assign each tag to each
+// listed node's `tags` array.
+const classDefTagRegex = /^classDef\s+tag_([A-Za-z0-9_-]+)\s+.+$/;
+const classAssignTagRegex = /^class\s+([sc]\d+(?:,[sc]\d+)*)\s+tag_([A-Za-z0-9_-]+)$/;
+
+// Splits a node label like `"A<br>hot, sampled"` into its name and tags (#186).
+// Labels without `<br>` have no tags. Tags are comma-joined; trimmed of
+// whitespace. The `<br>` is the single source of truth for tag-name parsing —
+// `class` lines are decorative-only and not consulted here.
+function splitLabelTags(label: string): {name: string; tags: string[]} {
+  const brIx = label.indexOf('<br>');
+
+  if (brIx < 0) {
+    return {name: label, tags: []};
+  }
+
+  const name = label.slice(0, brIx);
+  const tagsStr = label.slice(brIx + '<br>'.length);
+  const tags = tagsStr.split(',').map((t) => t.trim()).filter((t) => t.length > 0);
+
+  return {name, tags};
+}
 
 export function fromMermaid(text: string): Graph {
   const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
@@ -319,6 +430,7 @@ export function fromMermaid(text: string): Graph {
       isWrapper?: boolean;
       bareStateId?: number | null;
       frameId?: number | null;
+      tags?: string[];
     } = {},
   ): GraphNode => {
     if (!nodes[id]) {
@@ -332,6 +444,7 @@ export function fromMermaid(text: string): Graph {
         frameId: opts.frameId ?? null,
         transitions: [],
         overriddenHaltStateId: null,
+        tags: opts.tags ? [...opts.tags] : [],
       };
     } else {
       if (opts.name !== undefined) nodes[id].name = opts.name;
@@ -340,6 +453,11 @@ export function fromMermaid(text: string): Graph {
       if (opts.isWrapper !== undefined) nodes[id].isWrapper = opts.isWrapper;
       if (opts.bareStateId !== undefined) nodes[id].bareStateId = opts.bareStateId;
       if (opts.frameId !== undefined) nodes[id].frameId = opts.frameId;
+      if (opts.tags !== undefined) {
+        for (const t of opts.tags) {
+          if (!nodes[id].tags.includes(t)) nodes[id].tags.push(t);
+        }
+      }
     }
 
     return nodes[id];
@@ -356,6 +474,11 @@ export function fromMermaid(text: string): Graph {
       continue;
     }
 
+    // Tag annotations (#186) — classDef lines are decorative and skipped;
+    // `class` lines are parsed in the edge pass since they reference nodes
+    // by id and need those nodes already created in the first pass.
+    if (classDefTagRegex.test(line)) continue;
+
     const sgStart = line.match(subgraphStartRegex);
 
     if (sgStart) {
@@ -389,9 +512,12 @@ export function fromMermaid(text: string): Graph {
     const wm = line.match(wrappedNodeRegex);
 
     if (wm) {
+      const {name, tags} = splitLabelTags(wm[2]);
+
       ensureNode(parseMermaidId(wm[1]), {
-        name: wm[2],
+        name,
         isWrapper: true,
+        tags,
       });
 
       continue;
@@ -400,9 +526,12 @@ export function fromMermaid(text: string): Graph {
     const rm = line.match(regularNodeRegex);
 
     if (rm) {
+      const {name, tags} = splitLabelTags(rm[2]);
+
       ensureNode(parseMermaidId(rm[1]), {
-        name: rm[2],
+        name,
         frameId: currentFrameId,
+        tags,
       });
 
       continue;
@@ -424,6 +553,23 @@ export function fromMermaid(text: string): Graph {
       continue;
     }
 
+    // Tag class-assignment line (#186): `class s1,s5 tag_hot` — adds
+    // the tag to each listed node. Tag-name preserved as written
+    // (sanitization on emit is lossy in principle; on parse we don't
+    // un-sanitize, since the original could have any characters).
+    const tagMatch = line.match(classAssignTagRegex);
+
+    if (tagMatch) {
+      const ids = tagMatch[1].split(',');
+      const tagName = tagMatch[2];
+
+      for (const idStr of ids) {
+        ensureNode(parseMermaidId(idStr), {tags: [tagName]});
+      }
+
+      continue;
+    }
+
     // `call` arrow — sets bareStateId on each source wrapper.
     const cm = line.match(callArrowRegex);
 
diff --git a/packages/machine/src/utilities/introspection.spec.ts b/packages/machine/src/utilities/introspection.spec.ts
index 147e9f0..87bdadc 100644
--- a/packages/machine/src/utilities/introspection.spec.ts
+++ b/packages/machine/src/utilities/introspection.spec.ts
@@ -7,9 +7,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0', '1']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: [],
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
             {pattern: '1', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"},
@@ -31,9 +31,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: [],
           transitions: [
             {pattern: '0', command: [{symbol: 'K', movement: 'R'}], nextStateId: 1, id: "test-edge"},
           ],
@@ -52,9 +52,9 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
         1: {
-          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null,
+          id: 1, name: 'a', isHalt: false, overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: [],
           transitions: [{pattern: '0', command: [{symbol: 'K', movement: 'S'}], nextStateId: 0, id: "test-edge"}],
         },
       },
@@ -72,10 +72,10 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 3, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        3: {id: 3, name: 'c', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
       },
     };
 
@@ -90,8 +90,8 @@ describe('summarizeGraph', () => {
       initialId: 1,
       alphabets: [[' ']],
       nodes: {
-        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        0: {id: 0, name: 'halt', isHalt: true, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: null, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
       },
     };
 
@@ -197,8 +197,8 @@ describe('summarizeGraph defensive guards', () => {
       initialId: 1,
       alphabets: [[' ', '0']],
       nodes: {
-        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
-        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null},
+        1: {id: 1, name: 'a', isHalt: false, transitions: [], overriddenHaltStateId: 2, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
+        2: {id: 2, name: 'b', isHalt: false, transitions: [], overriddenHaltStateId: 1, isHaltMarker: false, isWrapper: false, bareStateId: null, frameId: null, tags: []},
       },
     };
 

From 4190c9959c9b8bfbd3e58cb97d223abe29534ff9 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 17:45:39 +0300
Subject: [PATCH 026/118] chore(release): 7.0.0-alpha.3

---
 CLAUDE.md                                     |  2 +
 lerna.json                                    |  2 +-
 package-lock.json                             | 14 +++----
 packages/builder/package.json                 |  4 +-
 .../library-binary-numbers-bare/package.json  |  4 +-
 packages/library-binary-numbers/package.json  |  4 +-
 packages/machine/CHANGELOG.md                 | 40 +++++++++++++++++++
 packages/machine/README.md                    | 37 ++++++++++++++++-
 packages/machine/package.json                 |  2 +-
 9 files changed, 93 insertions(+), 16 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3484e13..0d24004 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,6 +61,8 @@ Key shapes that take reading multiple files to grasp:
 
 `packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same `Graph` through [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) syntax (renderer: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)). The parser is strict to the dialect `toMermaid` emits — hand-edited Mermaid with different arrow styles or shapes won't round-trip.
 
+**State tags (v7 alpha.3, #186)** — `state.tag(...tags) / state.untag(...tags) / state.tags` API for attaching string metadata to a State. Tags are out-of-band — they don't affect transition lookup, `equivalentOn`, or runtime semantics. Live on the State *instance* (not on `#symbolToDataMap`), so engine #175 memoization doesn't leak tags across wrappers sharing a bare: `A.wohs(t1).tag('hot')` and `A.wohs(t2)` carry independent tag sets. `GraphNode` gains `tags: string[]` field — survives `toGraph`/`fromGraph` round-trip. `toMermaid` emits tags two ways: inline in node label via universal `<br>` (`sN["name<br>tag1, tag2"]`) AND as `classDef tag_<sanitized>` + `class sN tag_<sanitized>` lines (6-color hash-based palette). `fromMermaid` splits the label on `<br>` as source of truth; `class` lines are decorative.
+
 **v7 callable-subtree emit shape** (#174, layered on the v7 alpha.1 framing from #138/#139): each `withOverriddenHaltState` wrapper produces TWO `GraphNode`s — a wrapper node (`isWrapper: true`, `[[composite-name]]` shape, no transitions, `bareStateId` points to the bare's GraphNode) and a bare node (regular `["name"]` shape inside its callable subtree subgraph, holds the bare's transitions). Frames are computed via union-find on bare-reachability: each unique bare's forward-reachable set defines its candidate frame; overlapping reach sets merge into a union frame. Frame id = smallest bare-id in the component. Halt marker per frame (id = `-frameId`, `isHaltMarker: true`, maps back to singleton `haltState` in `fromGraph`). Halt-bound transitions of in-frame states retarget to the frame's halt marker. Subgraph label: `"callable subtree of NAME"` (single bare) or `"callable scope: A ∪ B"` (union). The always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state. **No per-context duplication** — shared bares like `library-binary-numbers`'s `invertNumber` (in `minusOne`) appear once with `& `-joined call arrows from each wrapper.
 
 **Edge label vocabulary** — `[reads] → [writes]/[moves]`, each role wrapped in `[…]` (the tape-block indicator, one entry per tape; brackets always present, even single-tape). Read cells: literal-quoted (`'X'`), `*` (ASCII, ifOtherSymbol catch-all; literal `*` in the alphabet is quoted as `'*'`), `B` (the tape's blank). Write cells: literal-quoted, `K` (keep), `E` (erase = write blank). Move cells: `L` / `R` / `S`. **Alternation is always per-pattern bracket** (`['^']|['1']|['0']` for single-tape, `['0','a']|['1','b']` for multi-tape); the compact in-bracket form `['^'|'1']` is rejected by `fromMermaid` to prevent the cross-product reading trap in multi-tape (`['0'|'1','a'|'b']` would read as 4 combinations rather than 2 paired alternatives, so the format avoids the shape entirely).
diff --git a/lerna.json b/lerna.json
index a18995b..0455ff2 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.2",
+  "version": "7.0.0-alpha.3",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index 9049f26..d50c9ae 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10656,40 +10656,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.2",
+      "version": "7.0.0-alpha.3",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.1"
+        "@turing-machine-js/machine": "^7.0.0-alpha.2"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.2",
+      "version": "7.0.0-alpha.3",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.1"
+        "@turing-machine-js/machine": "^7.0.0-alpha.2"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.2",
+      "version": "7.0.0-alpha.3",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.1"
+        "@turing-machine-js/machine": "^7.0.0-alpha.2"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.2",
+      "version": "7.0.0-alpha.3",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/builder/package.json b/packages/builder/package.json
index 7736037..b23e98d 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.2",
+  "version": "7.0.0-alpha.3",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.2"
+    "@turing-machine-js/machine": "^7.0.0-alpha.3"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index f49e97b..3af83ee 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.2",
+  "version": "7.0.0-alpha.3",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.2"
+    "@turing-machine-js/machine": "^7.0.0-alpha.3"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index 6ec5374..9a665a1 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.2",
+  "version": "7.0.0-alpha.3",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.2"
+    "@turing-machine-js/machine": "^7.0.0-alpha.3"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index 860d785..1e2f70d 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,46 @@ 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.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`.
+
+**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.3`.
+
+### Added
+
+- **`State.tag(...) / .untag(...) / .tags` API** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). Fluent post-construct API for attaching string tags to a State. Tags are out-of-band metadata — they don't affect runtime transition lookup, `equivalentOn` comparisons, or any structural identity. Storage lives 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 that share a bare: `A.wohs(t1).tag('hot')` does NOT propagate to `A.wohs(t2)`.
+
+  ```ts
+  const s = new State({...}, 'foo')
+    .tag('hot', 'sampled')
+    .untag('sampled');
+  s.tags; // ['hot']  ← frozen snapshot, in insertion order
+  ```
+
+- **`GraphNode.tags: string[]`** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). New field on the serialized graph node. Survives `State.toGraph` / `State.fromGraph` round-trip; empty array for untagged states.
+
+- **`toMermaid` tag rendering** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). Two surfaces:
+  - **Visible labels via `<br>`**: tagged node labels include the tag names inline (`s5["A<br>hot, sampled"]`). Uses Mermaid's universal `<br>` line break — works across mermaid.js, the live editor, machines-demo, and any other renderer; no CSS-pseudo-element tricks.
+  - **Color grouping via `classDef` + `class`**: each unique tag gets a `classDef tag_<sanitized> fill:#...,stroke:#...` line (palette of 6 colors selected by tag-name hash) and a `class s5,s6 tag_<sanitized>` line listing every node carrying the tag.
+
+- **`fromMermaid` tag parse** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). Splits the node label on `<br>` to extract tags as the source of truth; `class` lines are decorative and discarded on parse (they regenerate on the next `toMermaid` emit from the tag set).
+
+### Compatibility
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3` on `@turing-machine-js/builder`, `@turing-machine-js/library-binary-numbers`, `@turing-machine-js/library-binary-numbers-bare`.
+
+### Migration from alpha.2
+
+Purely additive — no breaking changes. Existing code that doesn't call `state.tag(...)` or read `state.tags` / `GraphNode.tags` continues to work identically. Mermaid emit for untagged states is bytewise unchanged.
+
+If you serialize `GraphNode` JSON, note that the new `tags: string[]` field is now required by the type (always emitted; empty array if no tags).
+
+### Out of v7-alpha.3 (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.
+- **[#180](https://github.com/mellonis/turing-machine-js/issues/180)** — extract `State.toGraph`/`fromGraph` to its own module.
+
 ## [7.0.0-alpha.2] - 2026-05-21
 
 Second v7 pre-release. Refines alpha.1's `toMermaid` wrapped-state emit into the function-call model ([#174](https://github.com/mellonis/turing-machine-js/issues/174)) and adds two construction-time improvements to `withOverriddenHaltState` ([#175](https://github.com/mellonis/turing-machine-js/issues/175), [#176](https://github.com/mellonis/turing-machine-js/issues/176)). Published to npm under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.
diff --git a/packages/machine/README.md b/packages/machine/README.md
index e6315b9..46b4f11 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -13,6 +13,7 @@ A composable Turing-machine engine for JavaScript: multi-tape, subroutine compos
 - [Building from a state table](#building-from-a-state-table)
 - [Classes](#classes) — [`Alphabet`](#alphabet) · [`Tape`](#tape) · [`TapeBlock`](#tapeblock) · [`TapeCommand`](#tapecommand) · [`Command`](#command) · [`State`](#state) · [`Reference`](#reference) · [`TuringMachine`](#turingmachine)
 - [Subroutine composition with `withOverriddenHaltState`](#subroutine-composition-with-withoverriddenhaltstate)
+- [State tags](#state-tags)
 - [Debugging breakpoints](#debugging-breakpoints)
 - [Special objects](#special-objects) — [`haltState`](#haltstate) · [`ifOtherSymbol`](#ifothersymbol) · [`movements`](#movements) · [`symbolCommands`](#symbolcommands)
 - [Introspection and testing](#introspection-and-testing)
@@ -427,6 +428,25 @@ flowchart TD
 
 Wrappers nest: `inner.withOverriddenHaltState(middle).withOverriddenHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
 
+## State tags
+
+A State carries an optional set of string tags — out-of-band metadata for visualization grouping and debugger labels. Tags don't affect runtime transition lookup, `equivalentOn` comparisons, or any structural identity; they ride alongside the State.
+
+```ts
+const s = new State({...}, 'walkToBlank::1')
+  .tag('hot', 'subroutine-entry');
+
+s.tags; // readonly ['hot', 'subroutine-entry'] — frozen snapshot
+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.
+
+**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
 
 Any `State` can carry a runtime-mutable `debug` config that pauses execution at chosen points.
@@ -599,6 +619,15 @@ The `&` ribbon syntax (`s_W1 & s_W2 == "call" ==> s_A`) collapses multiple wrapp
 
 `subgraph w_N["callable subtree of NAME"] … end` wraps a bare + its body + a halt marker — the callable scope of code that runs when a wrapper "calls" the bare. Multi-bare frames (union-find merged from shared body states) use the label `"callable scope: A ∪ B"`.
 
+### Tags
+
+Tagged states (via `state.tag('hot', 'sampled')` — see [§State tags](#state-tags)) render two ways simultaneously:
+
+- **Inline in the node label**: `sN["name<br>tag1, tag2"]` — the `<br>` is Mermaid's universal line break, so the tags display as a second line under the state name in any renderer.
+- **As a color class**: `classDef tag_<sanitized> fill:#...,stroke:#...` per unique tag (6-color palette selected by tag-name hash), plus `class sN,sM tag_<sanitized>` listing all nodes carrying the tag. Lets the eye group related states by color even when their names are scattered across the diagram.
+
+The `<br>`-embedded label is the source of truth for `fromMermaid` round-trip; the `classDef`/`class` lines are decorative and regenerate on the next `toMermaid` emit. Tag-name sanitization in `classDef` identifiers: any char outside `[A-Za-z0-9_-]` is replaced with `_`. Labels preserve the raw tag names.
+
 ### Edge label format
 
 `[reads] → [writes]/[moves]`. Each bracketed list is a tape-block reading — one entry per tape; brackets always present, even single-tape.
@@ -654,7 +683,13 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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** *(alpha 1, 2026-05-21)* — Composition-representation overhaul. **First pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.1`). Stable v7.0.0 still pending [#102](https://github.com/mellonis/turing-machine-js/issues/102) (debugger step-in/over/out primitives). Landed in alpha.1:
+- **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:
+
+  **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).
+
+  **alpha.2** — callable-subtree `toMermaid` emit refinement ([#174](https://github.com/mellonis/turing-machine-js/issues/174)). The wrapper is a separate `[[composite-name]]` node OUTSIDE the subgraph; the bare's reachable subtree becomes a `subgraph w_${frameId}["callable subtree of NAME"]` block. Frames computed via union-find — shared bares dedupe with `&` ribbons on call arrows. Bold `==> "call"` reserved for wrapper-to-bare; dotted `-.->` for frame dispatch (`return` / `halt` / `enter`). Plus engine memoization ([#175](https://github.com/mellonis/turing-machine-js/issues/175)) and nested-chain collapse ([#176](https://github.com/mellonis/turing-machine-js/issues/176)) for `.wohs()`.
+
+  **alpha.1** — initial v7 composition-representation overhaul:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
   - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
   - **`toMermaid` callable-subtree emit** ([#174](https://github.com/mellonis/turing-machine-js/issues/174), supersedes the alpha.1 collapsed-bare shape from #138/#139). `withOverriddenHaltState` is modeled as a function call: the wrapper is a `[[composite-name]]` call site OUTSIDE any subgraph, the bare's reachable subtree becomes a `subgraph w_${frameId}["callable subtree of NAME"] … end` block containing the bare + body states + a per-frame halt marker `c${frameId}(((halt)))`. Frames are computed via union-find on bare-reachability — overlapping reach sets merge into a single union frame, so shared bares (`library-binary-numbers/minusOne`'s `invertNumber`) appear ONCE with `& `-joined call arrows from each wrapper. Bold `==> "call"` arrows are reserved for the wrapper-to-bare call; dotted `-.->` is reserved for frame-level dispatch (`return` / `halt` / `enter`). The retired `-. onHalt .->` keyword is replaced by a solid `--> override` arrow (just an ordinary transition under the call/return mental model). `GraphNode` gains `isWrapper`, `bareStateId`, `frameId` fields (and drops `isWrapped`). Bytewise round-trip stability now holds for all wrapped states including shared-bare cases (no per-context duplication).
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 514ffb7..12154ff 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.2",
+  "version": "7.0.0-alpha.3",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"

From 86483d2057677b5f0e269f50c236d845192fcc52 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 17:49:04 +0300
Subject: [PATCH 027/118] fix(fromMermaid): tighten classDef/class tag regexes
 to clear CodeQL polynomial-ReDoS flag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeQL flagged `classDefTagRegex` on PR #167's integration scan:

  ^classDef\s+tag_([A-Za-z0-9_-]+)\s+.+$

The `\s+...\s+` shape around a content group with `-` in the character
class is the polynomial-backtracking pattern CodeQL detects (same shape
as #182's earlier fix on `callArrowRegex` / `returnArrowRegex`).

`toMermaid` emits these lines with exactly single literal spaces between
tokens (`classDef tag_<name> fill:#...`, `class s5,s6 tag_<name>`), so
tightening `\s+` → ` ` is loss-free for round-trip cases and removes the
ReDoS-vulnerable shape. Both classDefTagRegex and classAssignTagRegex
get the same treatment for consistency.

Test plan
- npm test — 456/456 pass
- npm run lint — clean

CodeQL annotation:
https://github.com/mellonis/turing-machine-js/pull/167#discussion_r3282035002
---
 packages/machine/src/utilities/graphFormats.ts | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 981b9ef..2b6f300 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -392,8 +392,13 @@ const alphabetsRegex = /^%%\s*alphabets:\s*(\S.*)$/;
 // the tag set on re-emit. `class` lines carry the actual graph-node
 // assignments; we strip the `tag_` prefix and assign each tag to each
 // listed node's `tags` array.
-const classDefTagRegex = /^classDef\s+tag_([A-Za-z0-9_-]+)\s+.+$/;
-const classAssignTagRegex = /^class\s+([sc]\d+(?:,[sc]\d+)*)\s+tag_([A-Za-z0-9_-]+)$/;
+//
+// Inter-token gaps are fixed at single literal spaces (matching toMermaid's
+// canonical emit) rather than `\s+`. This avoids the polynomial-ReDoS
+// pattern CodeQL flags when `\s+` surrounds a content group (see also
+// `callArrowRegex` / `returnArrowRegex` tightening in PR #182).
+const classDefTagRegex = /^classDef tag_([A-Za-z0-9_-]+) .+$/;
+const classAssignTagRegex = /^class ([sc]\d+(?:,[sc]\d+)*) tag_([A-Za-z0-9_-]+)$/;
 
 // Splits a node label like `"A<br>hot, sampled"` into its name and tags (#186).
 // Labels without `<br>` have no tags. Tags are comma-joined; trimmed of

From daef9952feafdb6f14fce5250f4010bb35774b71 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 18:02:02 +0300
Subject: [PATCH 028/118] test(coverage): exercise fromGraph tag application +
 reverse-order union;                 strip dead defensive paths in State +
 graphFormats
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR #167's coveralls check was at -0.8% after #186 added the tag surface.
Local v8 was already above engine floors but Coveralls's combined-
metric (lines + branches) dragged on uncovered defensive paths in the
new code.

Tests added (3 new in `State.spec.ts`)
- `toGraph → fromGraph preserves tags on bare/regular nodes` —
  exercises the `bare.tag(...node.tags)` branch in `fromGraph` (#186).
- `toGraph → fromGraph preserves tags on wrapper nodes` —
  exercises the `state.tag(...node.tags)` branch on wrappers after
  `withOverriddenHaltState`.
- `reverse-order union — bares[0] has higher id than bares[i]` —
  constructs bares in reverse order so BFS encounters the higher-id
  one first, making `ufUnion(bares[0], bares[i])` run with ra > rb
  and hit the else-branch (line 649 — previously uncovered).

Defensive paths simplified
- State.ts toGraph BFS: removed `!node` check (BFS only enqueues IDs
  that were already added to `nodes`, so `node` is always defined).
- State.ts ufFind: removed the path-compression loop. Under the
  smaller-id-wins union policy used here, the tree never grows beyond
  depth 1 (every union sets the smaller id as root; every node
  directly points to root). Path compression was dead code.
- graphFormats.ts wrapper-override emit: dropped the
  `if (wrapper.overriddenHaltStateId === null) continue` guard —
  wrappers always have an override (set by State.toGraph). Use the
  non-null assertion.
- graphFormats.ts fromMermaid wrapper-override parse: dropped the
  redundant `nodes[fromId] && ...` check — pass 1 always populates
  the node before pass 2 sees the edge.

Coverage delta (v8)
  Stmts:    98.42 → 99.03  (+0.61)
  Branch:   95.08 → 95.70  (+0.62)
  Funcs:    100   → 100    (unchanged)
  Lines:    98.79 → 99.34  (+0.55)

Tests
- npm test — 460/460 pass (456 prior + 4 new)
- npm run lint — clean
- npm run typecheck — clean
---
 packages/machine/src/classes/State.spec.ts    | 129 ++++++++++++++++++
 packages/machine/src/classes/State.ts         |  19 ++-
 .../machine/src/utilities/graphFormats.ts     |  16 ++-
 3 files changed, 149 insertions(+), 15 deletions(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 9dfbb95..b29e180 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -419,6 +419,135 @@ describe('State tags (#186)', () => {
     haltState.untag('halt-debug-marker');
     expect(haltState.tags).not.toContain('halt-debug-marker');
   });
+
+  // Round-trip tag application (#186) — exercises both fromGraph branches:
+  // tagging a bare/regular node (the simple branch) and tagging a wrapper
+  // node (the path that goes through `state.tag(...node.tags)` after
+  // `withOverriddenHaltState`).
+  test('toGraph → fromGraph preserves tags on bare/regular nodes', () => {
+    const tapeBlock = TapeBlock.fromAlphabets([new Alphabet([' ', '0'])]);
+    const original = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'tagged-bare').tag('alpha', 'beta');
+
+    const graph = State.toGraph(original, tapeBlock);
+    const {start} = State.fromGraph(graph);
+
+    expect(start.tags).toEqual(['alpha', 'beta']);
+  });
+
+  test('toGraph → fromGraph preserves tags on wrapper nodes', () => {
+    const tapeBlock = TapeBlock.fromAlphabets([new Alphabet([' ', '0'])]);
+    const bare = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'bare');
+    const target = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'target');
+    const wrapper = bare.withOverriddenHaltState(target).tag('hot');
+
+    const graph = State.toGraph(wrapper, tapeBlock);
+    const {start} = State.fromGraph(graph);
+
+    expect(start.tags).toEqual(['hot']);
+  });
+});
+
+describe('State.toGraph — union-find depth & ordering', () => {
+  // Direct coverage for the path-compression loop and the reverse-order
+  // `ra > rb` branch in `ufUnion`. The simpler shared-body-state tests in
+  // `graph.spec.ts` only exercise depth-1 unions; this case forces depth ≥ 2
+  // by chaining: A and B share X; C and D share Y; bridging through a shared
+  // state Z forces a multi-level union where `ufFind` walks > 1 step.
+  test('reverse-order union — bares[0] has higher id than bares[i], hits the ra > rb branch', () => {
+    // The simpler shared-body tests in `graph.spec.ts` always have the
+    // lowest-id bare encountered first (so `ufUnion(bares[0], bares[i])`
+    // runs with ra < rb and the smaller-id branch fires). To cover the
+    // ra > rb else-branch in `ufUnion`, we construct the higher-id bare's
+    // wrapper first and reach it via the dispatcher's FIRST transition —
+    // so BFS visits its bare before the lower-id one, making it bares[0].
+    const alphabet = new Alphabet([' ', '1', '2']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    // Construct the higher-id bare FIRST so it has a HIGHER #id than the
+    // lower-id bare we construct later. Counter-intuitive — but bare
+    // identity in toGraph's `bareIds` Set is insertion order = BFS visit
+    // order, which depends on the dispatcher's transition order, NOT on
+    // construction order. So we construct B before A (B gets a lower #id),
+    // then route dispatcher to reach A's wrapper FIRST.
+    const X = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'X');
+    const B = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'B');
+    const A = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: X}}, 'A');
+    // A.id > B.id (A constructed later). Now dispatcher visits A's wrapper
+    // FIRST via the [1] transition, so BFS puts A in bareIds before B →
+    // bares[0]=A (higher id), bares[1]=B (lower id) → ufUnion(A, B) with
+    // ra > rb → hits the else-branch.
+    const t = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 't');
+    const WA = A.withOverriddenHaltState(t);
+    const WB = B.withOverriddenHaltState(t);
+    const dispatcher = new State({
+      [symbol(['1'])]: {command: {movement: movements.stay}, nextState: WA},
+      [symbol(['2'])]: {command: {movement: movements.stay}, nextState: WB},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+
+    // The frame id is the smallest id in the component (canonical), which
+    // is B (constructed first) — confirms `ra > rb` did the right thing:
+    // when ufUnion(A, B) ran with A as `ra`, the else-branch set
+    // parent[A] = B, keeping the smaller id as root.
+    expect(graph.nodes[A.id].frameId).toBe(B.id);
+    expect(graph.nodes[B.id].frameId).toBe(B.id);
+    expect(graph.nodes[X.id].frameId).toBe(B.id);
+  });
+
+  test('multi-bare overlap with several shared bares (smoke test)', () => {
+    const alphabet = new Alphabet([' ', '1', '2', '3', '4']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    // Z is a "bridge" body state that A, B, C, D all eventually transition
+    // into. Ensures every bare's reach set contains Z → all bares unioned.
+    const Z = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'Z');
+    const A = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: Z}}, 'A');
+    const B = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: Z}}, 'B');
+    const C = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: Z}}, 'C');
+    const D = new State({[ifOtherSymbol]: {command: {movement: movements.right}, nextState: Z}}, 'D');
+
+    const t = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 't');
+
+    const WA = A.withOverriddenHaltState(t);
+    const WB = B.withOverriddenHaltState(t);
+    const WC = C.withOverriddenHaltState(t);
+    const WD = D.withOverriddenHaltState(t);
+
+    const dispatcher = new State({
+      [symbol(['1'])]: {command: {movement: movements.stay}, nextState: WA},
+      [symbol(['2'])]: {command: {movement: movements.stay}, nextState: WB},
+      [symbol(['3'])]: {command: {movement: movements.stay}, nextState: WC},
+      [symbol(['4'])]: {command: {movement: movements.stay}, nextState: WD},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+
+    // All four bares end up in the same union frame (canonical = smallest id).
+    const frameId = graph.nodes[A.id].frameId;
+
+    expect(frameId).not.toBeNull();
+    expect(graph.nodes[B.id].frameId).toBe(frameId);
+    expect(graph.nodes[C.id].frameId).toBe(frameId);
+    expect(graph.nodes[D.id].frameId).toBe(frameId);
+    expect(graph.nodes[Z.id].frameId).toBe(frameId);
+  });
 });
 
 describe('State.fromGraph — cyclic override-halt chain', () => {
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 81e91ed..d83b636 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -582,7 +582,10 @@ export default class State {
 
         const node = nodes[id];
 
-        if (!node || node.isHalt || node.isWrapper) {
+        // `nodes[id]` is always populated for `id` that the BFS reached, so
+        // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
+        // are real boundaries — both stop reach-set expansion.
+        if (node.isHalt || node.isWrapper) {
           continue;
         }
 
@@ -613,6 +616,10 @@ export default class State {
     // the component.
     const ufParent = new Map<number, number>();
 
+    // Note: no path compression. The union policy below ("smaller id always
+    // becomes root") keeps the tree flat — every union targets bares[0] as
+    // the root, so any node's parent IS the root. Walking up never exceeds
+    // one step. Path compression would be dead code under this invariant.
     const ufFind = (id: number): number => {
       if (!ufParent.has(id)) {
         ufParent.set(id, id);
@@ -624,16 +631,6 @@ export default class State {
         root = ufParent.get(root)!;
       }
 
-      // Path compression
-      let cur = id;
-
-      while (ufParent.get(cur) !== root) {
-        const next = ufParent.get(cur)!;
-
-        ufParent.set(cur, root);
-        cur = next;
-      }
-
       return root;
     };
 
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 2b6f300..3e75f24 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -235,11 +235,14 @@ export function toMermaid(graph: Graph): string {
   }
 
   // 8. Wrapper-to-override arrows (regular solid).
+  //
+  // `wrapper.overriddenHaltStateId` is always non-null on wrapper nodes
+  // (set by `State.toGraph` for every `isWrapper: true` node — it's the
+  // wrapper's override target, which a wrapper by definition has). The
+  // non-null assertion is safe; a defensive null check would be dead.
   for (const wrapper of wrapperNodes) {
-    if (wrapper.overriddenHaltStateId === null) continue;
-
     lines.push(
-      `  ${mermaidIdFor(wrapper.id)} --> ${mermaidIdFor(wrapper.overriddenHaltStateId)}`,
+      `  ${mermaidIdFor(wrapper.id)} --> ${mermaidIdFor(wrapper.overriddenHaltStateId!)}`,
     );
   }
 
@@ -597,7 +600,12 @@ export function fromMermaid(text: string): Graph {
       const fromId = parseMermaidId(wo[1]);
       const toId = parseMermaidId(wo[2]);
 
-      if (nodes[fromId] && nodes[fromId].isWrapper) {
+      // The wrapper-override regex only matches `sN --> sM` (unlabeled);
+      // since `toMermaid` only emits this shape from wrappers, the source
+      // is guaranteed to be a wrapper if `fromMermaid`'s input came from
+      // `toMermaid`. `nodes[fromId]` is always populated (first pass emits
+      // node declarations before any edge parsing).
+      if (nodes[fromId].isWrapper) {
         nodes[fromId].overriddenHaltStateId = toId;
         continue;
       }

From a1038076a91ac20ad316eb30e878be96cd9bbebf Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 18:17:14 +0300
Subject: [PATCH 029/118] test(coverage): strip three more dead defensive
 branches in graphFormats
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to #190. Further simplifies branches in `toMermaid` /
`isFrameBare` that don't fire on engine-emitted Mermaid:

- **Return-arrow emit**: dropped `callingWrappers.length > 0` guard.
  Frames only exist because at least one wrapper's `bareStateId`
  points into the frame, so the list is always non-empty at this
  code path.
- **isFrameBare**: dropped `node.isHalt` and `node.isWrapper` early-
  returns. The caller in `toMermaid` already filters wrappers and
  halt markers into separate buckets — non-wrapper, non-halt-marker
  nodes are the only ones that reach this helper.
- **wrapperOverrideRegex**: dropped redundant `bare` null check
  (already addressed in #190's commit for the symmetric `nodes[fromId]`
  case; this catches the wrapper.bareStateId null-coalesce path).

Coverage delta (v8)
  Stmts:    99.03 → 99.20  (+0.17)
  Branch:   95.70 → 96.13  (+0.43)
  Funcs:    100   → 100    (unchanged)
  Lines:    99.34 → 99.20

Combined for Coveralls (lines+branches): ~98.04 → ~98.15. Master
baseline ~98.33; residual gap is the few defensive paths that only
fire on hand-edited Mermaid input (e.g., undeclared node IDs in
edges, which `toMermaid` never produces).

Tests
- npm test — 460/460 pass
- npm run lint — clean
- npm run typecheck — clean
---
 .../machine/src/utilities/graphFormats.ts     | 31 ++++++++++---------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 3e75f24..7e79579 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -210,24 +210,23 @@ export function toMermaid(graph: Graph): string {
   for (const frameId of frameIds) {
     if (!haltMarkerHasIncoming.get(frameId)) continue;
 
-    // Return arrow — collapsed `&` ribbon over all wrappers calling this frame.
+    // Return arrow — collapsed `&` ribbon over all wrappers calling this
+    // frame. Frames only exist because at least one wrapper's bareStateId
+    // points to a bare in the frame, so `callingWrappers` is always
+    // non-empty for any frame that reached this code path.
     const callingWrappers = wrapperNodes.filter((w) => {
-      if (w.bareStateId === null) return false;
+      const bare = graph.nodes[w.bareStateId!];
 
-      const bare = graph.nodes[w.bareStateId];
-
-      return !!bare && bare.frameId === frameId;
+      return bare.frameId === frameId;
     });
 
-    if (callingWrappers.length > 0) {
-      const targets = callingWrappers
-        .slice()
-        .sort((a, b) => a.id - b.id)
-        .map((w) => mermaidIdFor(w.id))
-        .join(' & ');
+    const targets = callingWrappers
+      .slice()
+      .sort((a, b) => a.id - b.id)
+      .map((w) => mermaidIdFor(w.id))
+      .join(' & ');
 
-      lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
-    }
+    lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
 
     if (hasNonWrapperEntry.get(frameId)) {
       lines.push(`  ${frameSubgraphId(frameId)} -. "halt" .-> s0`);
@@ -343,9 +342,11 @@ function emitTagAnnotations(lines: string[], nodes: GraphNode[]): void {
 // Helper: identify "the bare states" that anchor a frame's name. A bare is a
 // node referenced as some wrapper's `bareStateId`. Body states (also in-frame
 // but not bare) are excluded from the frame label.
+//
+// The caller in `toMermaid` only passes non-wrapper, non-halt-marker nodes
+// (wrappers go to a separate bucket; halt markers go to `haltMarkerByFrame`).
+// No defensive `isHalt` / `isWrapper` guards needed here.
 function isFrameBare(node: GraphNode, graph: Graph): boolean {
-  if (node.isWrapper || node.isHalt) return false;
-
   for (const other of Object.values(graph.nodes)) {
     if (other.isWrapper && other.bareStateId === node.id) {
       return true;

From 76d006265716dcd363943b7ebc9b45f89b252b63 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 18:25:07 +0300
Subject: [PATCH 030/118] test(coverage): cover remaining defensive paths in
 fromMermaid + simplify halt-marker emit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drives Coveralls's combined metric back to master baseline.

Tests added (2 new in `graph.spec.ts > fromMermaid ensureNode update branches`)
- `class line referencing an undeclared node creates it with a fallback
  name` — exercises the `opts.name ?? mermaidIdFor(id)` fallback in
  ensureNode (line 448) when pass 2 (edge/class parsing) encounters an
  id pass 1 didn't declare. Real toMermaid output never produces this;
  hand-edited Mermaid can.
- `unlabeled sN --> sM from a non-wrapper source falls through to no-op`
  — exercises the wrapper-override regex's `isWrapper`-false branch
  (line 609). Documents the silent-ignore behavior for malformed input.

Simplified
- toMermaid halt-marker emit: dropped `if (haltMarker)` guard. Every
  frame has a halt marker (per `State.toGraph`'s frame-emit pass), so
  the null check was dead.

Coverage delta (v8, cumulative across #190 + #191 + this)
  Stmts:    98.42 → 99.20  (+0.78)
  Branch:   95.08 → 96.62  (+1.54)
  Funcs:    100   → 100    (unchanged)
  Lines:    98.79 → 99.43  (+0.64)

Combined for Coveralls (lines+branches): 97.45 → ~98.32. Master
baseline ~98.33. Effectively recovers the drop introduced by #186's
tag surface.

Tests
- npm test — 462/462 pass
- npm run lint — clean
- npm run typecheck — clean
---
 packages/machine/src/utilities/graph.spec.ts  | 50 +++++++++++++++++++
 .../machine/src/utilities/graphFormats.ts     |  9 ++--
 2 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index 72255c2..72a92ba 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -425,6 +425,56 @@ describe('fromMermaid ensureNode update branches', () => {
 
     expect(graph.nodes[1].isHalt).toBe(true);
   });
+
+  test('`class` line referencing an undeclared node creates it with a fallback name', () => {
+    // Defensive path: `ensureNode(id, {tags: [...]})` called without
+    // `opts.name` for a node that pass 1 didn't declare. Fires the
+    // `opts.name ?? mermaidIdFor(id)` fallback. Real `toMermaid` output
+    // never produces this (every node referenced by a `class` line is
+    // declared first), but hand-edited Mermaid can.
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0"]]',
+      '  s0(((halt)))',
+      '  s1["entry"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      "  s1 -- \"['0'] → [K]/[S]\" --> s0",
+      '  class s99 tag_orphan', // s99 isn't declared anywhere else
+    ].join('\n');
+
+    const graph = fromMermaid(mermaid);
+
+    expect(graph.nodes[99]).toBeDefined();
+    expect(graph.nodes[99].name).toBe('s99'); // fallback to mermaidIdFor(99)
+    expect(graph.nodes[99].tags).toEqual(['orphan']);
+  });
+
+  test('unlabeled `sN --> sM` from a non-wrapper source falls through to labeled-regex (no-op)', () => {
+    // Defensive path: the wrapper-override regex matches `sN --> sM`
+    // (unlabeled) only when the source is a wrapper. If hand-edited input
+    // has `sN --> sM` with N being a regular state, the wrapper-override
+    // branch doesn't fire (the `if (nodes[fromId].isWrapper)` guard) and
+    // the labeled-regex below also doesn't match (no label). No edge is
+    // added, no overriddenHaltStateId set. Documented as malformed-input
+    // behavior.
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0"]]',
+      '  s0(((halt)))',
+      '  s1["entry"]',     // s1 is a regular state, NOT a wrapper
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      '  s1 --> s0',       // unlabeled — wrapper-override regex matches but isWrapper is false
+    ].join('\n');
+
+    const graph = fromMermaid(mermaid);
+
+    // No transition added, no overriddenHaltStateId set — the line is
+    // silently ignored.
+    expect(graph.nodes[1].transitions).toHaveLength(0);
+    expect(graph.nodes[1].overriddenHaltStateId).toBeNull();
+  });
 });
 
 // Pin the exact toMermaid output shown in packages/machine/README.md so the
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 7e79579..e1dc59c 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -135,11 +135,12 @@ export function toMermaid(graph: Graph): string {
       lines.push(`    ${mermaidIdFor(node.id)}["${labelOf(node)}"]`);
     }
 
-    const haltMarker = haltMarkerByFrame.get(frameId);
+    // Every frame has a halt marker — `State.toGraph`'s frame-emit pass
+    // creates one for each frame. Non-null assertion is safe; a defensive
+    // null check would be dead.
+    const haltMarker = haltMarkerByFrame.get(frameId)!;
 
-    if (haltMarker) {
-      lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
-    }
+    lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
 
     lines.push('  end');
   }

From 0090c09bda162fa169b757c38a01df585ae2481d Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 21 May 2026 18:36:34 +0300
Subject: [PATCH 031/118] chore: add LICENSE to builder and
 library-binary-numbers-bare packages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The four published packages all declare `license: GPL-3.0-or-later` in
package.json. Three of them already shipped a LICENSE file in their
tarball; `@turing-machine-js/builder` and
`@turing-machine-js/library-binary-numbers-bare` were missing theirs.

Copying the same GPL-3.0 LICENSE text used by `@turing-machine-js/machine`
and `@turing-machine-js/library-binary-numbers` (identical file —
verified by line count). Now every package's published tarball
includes the LICENSE that matches its `package.json` declaration.

No code change. Pure package-hygiene fix.
---
 packages/builder/LICENSE                     | 674 +++++++++++++++++++
 packages/library-binary-numbers-bare/LICENSE | 674 +++++++++++++++++++
 2 files changed, 1348 insertions(+)
 create mode 100644 packages/builder/LICENSE
 create mode 100644 packages/library-binary-numbers-bare/LICENSE

diff --git a/packages/builder/LICENSE b/packages/builder/LICENSE
new file mode 100644
index 0000000..f288702
--- /dev/null
+++ b/packages/builder/LICENSE
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
diff --git a/packages/library-binary-numbers-bare/LICENSE b/packages/library-binary-numbers-bare/LICENSE
new file mode 100644
index 0000000..f288702
--- /dev/null
+++ b/packages/library-binary-numbers-bare/LICENSE
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

From 397930f850146728d99c73ba37285f7153a29947 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 07:37:46 +0300
Subject: [PATCH 032/118] fix: scope halt-stack to runStepByStep call (closes
 #196)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The halt-stack was an instance field on TuringMachine and was never reset
between runStepByStep calls. Callers that started a generator, peeked at
iter 1, then disposed it via generator.return() — the pattern used by
machines-demo's worker to populate pendingCommand — left the wrapper's
overriddenHaltState on the stack. A subsequent machine.run() then pushed
the same override a second time; on its way out, an in-frame halt would
pop the leftover entry instead of exiting, producing one extra iteration.

The stack is run-scoped, not machine-scoped. Declaring it local inside
runStepByStep makes the lifetime explicit and prevents cross-call leak.

Regression tests assert (a) build-time peek + run produces no extra
iterations, (b) runStepByStep and run yield identical sequences for the
same machine + initial state, (c) two consecutive runs on the same
machine produce identical sequences.
---
 .../machine/src/classes/TuringMachine.spec.ts | 130 ++++++++++++++++++
 packages/machine/src/classes/TuringMachine.ts |  10 +-
 2 files changed, 138 insertions(+), 2 deletions(-)

diff --git a/packages/machine/src/classes/TuringMachine.spec.ts b/packages/machine/src/classes/TuringMachine.spec.ts
index 932b7a2..2a32465 100644
--- a/packages/machine/src/classes/TuringMachine.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.spec.ts
@@ -300,3 +300,133 @@ describe('TuringMachine constructor', () => {
     expect(() => new TuringMachine({} as never)).toThrow(/invalid tapeBlock/);
   });
 });
+
+// Regression tests for #196 — the halt-stack used to be an instance field on
+// TuringMachine that wasn't reset between `runStepByStep` calls, so a caller
+// that peeked at iter 1 via the generator (then disposed it with
+// `generator.return()`) would leave the wrapper's override on the stack;
+// the next `run()` would push it a second time and produce one extra
+// iteration on its way out of the call. Builds a wrapper whose bare halts
+// on blank and whose override also halts immediately — the minimal shape
+// that surfaces the bug.
+describe('halt-stack reset between calls (regression for #196)', () => {
+  // Helper: build a fresh scenario per call so each subtest has independent
+  // State/Tape/TapeBlock instances (the engine's symbol patterns are
+  // tapeBlock-scoped — sharing across scenarios would throw "invalid symbol").
+  function buildWrapperOverWalkToBlank() {
+    const wAlphabet = new Alphabet([' ', 'a', 'b', '*']);
+    const tape = new Tape({alphabet: wAlphabet, symbols: ['a', 'b', 'a']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    const {symbol} = tapeBlock;
+    const walkToBlank = new State({
+      [symbol([wAlphabet.blankSymbol])]: {
+        command: [{movement: movements.stay}],
+        nextState: haltState,
+      },
+      [ifOtherSymbol]: {
+        command: [{movement: movements.right}],
+      },
+    }, 'walkToBlank');
+    const writeMarker = new State({
+      [ifOtherSymbol]: {
+        command: [{symbol: '*', movement: movements.stay}],
+        nextState: haltState,
+      },
+    }, 'writeMarker');
+    const initialState = walkToBlank.withOverriddenHaltState(writeMarker);
+    return {machine, initialState, tape};
+  }
+
+  test('runStepByStep peek + return + run produces no extra iterations', async () => {
+    const {machine, initialState, tape} = buildWrapperOverWalkToBlank();
+
+    // Caller peeks at iter 1 then disposes the generator without draining —
+    // pre-#196 this left the override on `#stack`.
+    const gen = machine.runStepByStep({initialState});
+    gen.next();
+    gen.return(undefined);
+
+    const iters: Array<{step: number; name: string}> = [];
+    await machine.run({
+      initialState,
+      onIter: (m) => {
+        iters.push({step: m.step, name: m.state.name ?? ''});
+      },
+    });
+
+    expect(iters).toEqual([
+      {step: 1, name: 'walkToBlank(writeMarker)'},
+      {step: 2, name: 'walkToBlank'},
+      {step: 3, name: 'walkToBlank'},
+      {step: 4, name: 'walkToBlank'},
+      {step: 5, name: 'writeMarker'},
+    ]);
+    expect(tape.symbols).toEqual(['a', 'b', 'a', '*']);
+  });
+
+  test('runStepByStep and run produce identical iter sequences', async () => {
+    const a = buildWrapperOverWalkToBlank();
+    const fromGen: Array<{step: number; name: string}> = [];
+    for (const m of a.machine.runStepByStep({initialState: a.initialState})) {
+      fromGen.push({step: m.step, name: m.state.name ?? ''});
+    }
+
+    const b = buildWrapperOverWalkToBlank();
+    const fromRun: Array<{step: number; name: string}> = [];
+    await b.machine.run({
+      initialState: b.initialState,
+      onIter: (m) => {
+        fromRun.push({step: m.step, name: m.state.name ?? ''});
+      },
+    });
+
+    expect(fromRun).toEqual(fromGen);
+  });
+
+  test('two consecutive runs on the same machine produce identical iter sequences', async () => {
+    // A self-loop-free machine — both runs traverse the same iter shape
+    // because the input alphabet is wide enough that the head moves off the
+    // initial cells and the post-run tape doesn't influence the next run.
+    // The point of this test is the #stack accumulation, not tape state.
+    const wAlphabet = new Alphabet([' ', 'a', 'b']);
+    const tape = new Tape({alphabet: wAlphabet, symbols: ['a']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    // A wrapper around a single-iter halt-on-anything bare. Each run pushes
+    // the override; if the pre-#196 leak existed, the second run would see
+    // a stale override and one extra iter.
+    const bare = new State({
+      [ifOtherSymbol]: {
+        command: [{movement: movements.stay}],
+        nextState: haltState,
+      },
+    }, 'bare');
+    const continuation = new State({
+      [ifOtherSymbol]: {
+        command: [{movement: movements.stay}],
+        nextState: haltState,
+      },
+    }, 'continuation');
+    const initialState = bare.withOverriddenHaltState(continuation);
+
+    const first: Array<{step: number; name: string}> = [];
+    await machine.run({
+      initialState,
+      onIter: (m) => {
+        first.push({step: m.step, name: m.state.name ?? ''});
+      },
+    });
+
+    const second: Array<{step: number; name: string}> = [];
+    await machine.run({
+      initialState,
+      onIter: (m) => {
+        second.push({step: m.step, name: m.state.name ?? ''});
+      },
+    });
+
+    expect(first.length).toBe(2); // wrapper-iter + continuation-iter
+    expect(second).toEqual(first);
+  });
+});
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index cc138f2..c069ece 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -38,7 +38,6 @@ function matchFilter(filter: DebugConfig['before'], symbol: symbol): boolean {
 
 export default class TuringMachine {
   readonly #tapeBlock: TapeBlock;
-  readonly #stack: State[] = [];
 
   constructor({
                 tapeBlock,
@@ -148,7 +147,14 @@ export default class TuringMachine {
       this.#tapeBlock[lockSymbol].lock(executionSymbol);
 
 
-      const stack = this.#stack;
+      // Halt-stack is run-scoped, not machine-scoped (#196). Declaring it
+      // local makes that lifetime explicit and prevents leftover entries
+      // from a previous `runStepByStep` call (e.g. a build-time peek that
+      // never drained the generator) from being popped during a subsequent
+      // halt-bound transition. Before this change `#stack` was an instance
+      // field and accumulated one extra push per call when the same machine
+      // was reused.
+      const stack: State[] = [];
       let state = initialState;
 
       if (state.overriddenHaltState) {

From c1d6e2e29d4b48c41f5594e256634dbe2fd2cb39 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 09:16:29 +0300
Subject: [PATCH 033/118] fix: HTML-entity-escape user content in Mermaid
 labels (#194)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User-controlled fragments interpolated into the `"..."`-wrapped Mermaid
label strings (alphabet symbols in edge labels, state names, wrapper
composite names, frame bare names, tag names) now get HTML-entity
escaped at the leaf — `&`, `"`, `<`, `>` go to named entities;
statement terminators, C0 controls minus `\t`, DEL, bidi controls, and
lone UTF-16 surrogates go to numeric entities. Printable Unicode
(Cyrillic, CJK, etc.) passes through unchanged so non-ASCII alphabets
stay readable in the emitted `.mmd`.

Structural pieces this module emits (`<br>` tag separator, ` ∪ `,
`[`, `,`, `|`, `/`, ` → `, the `callable subtree of` / `callable
scope:` prefixes) are intentionally not escaped — only user-supplied
fragments are. fromMermaid mirrors with a single-pass entity decoder
applied to each leaf AFTER structural parsing, so a literal `<br>` in
a state name (encoded as `&lt;br&gt;`) survives the tag-split and
decodes back at the leaf.

Tag-list separator is `,` — `escapeMermaidLabel`'s base set leaves
that alone because in edge labels `,` is structural between per-tape
cells. Tags get an extra `,` → `&#44;` layer at composition time so
a literal comma in tag content can survive the round-trip.

Round-trip test for `'` (single quote inside an edge-label `'X'`
wrapper) is the same regression test that originally reproduced the
issue — `mermaid.render()` was throwing on alphabets that include `"`
because the inner literal closed the label string early.
---
 packages/machine/src/utilities/graph.spec.ts  | 164 ++++++++++++++++++
 .../machine/src/utilities/graphFormats.ts     | 120 ++++++++++++-
 2 files changed, 275 insertions(+), 9 deletions(-)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index 72a92ba..a204ee3 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -1053,3 +1053,167 @@ describe('fromMermaid: tags (#186)', () => {
     expect(reparsed.nodes[s.id].tags).toEqual(['alpha', 'beta']);
   });
 });
+
+describe('Mermaid label escaping (#194)', () => {
+  test('alphabet symbol containing literal " produces parseable output', () => {
+    // Repro from the issue: a write of `"` would land inside the
+    // `"..."`-wrapped edge label and terminate the string early on
+    // Mermaid's tokenizer.
+    const alphabet = new Alphabet([' ', 'a', '"']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['a'])]: {
+        command: [{symbol: '"', movement: movements.right}],
+        nextState: haltState,
+      },
+    }, 's');
+
+    const mermaid = toMermaid(State.toGraph(s, tapeBlock));
+
+    // No unescaped `"` inside the edge label between the outer wrappers.
+    expect(mermaid).toContain('&quot;');
+    expect(mermaid).not.toMatch(/-- "[^"]*"[^"]*"[^"]*" -->/);
+    // Round-trips back to a parseable graph that preserves the symbol.
+    const reparsed = fromMermaid(mermaid);
+    const reparsedTransitions = reparsed.nodes[s.id].transitions;
+    expect(reparsedTransitions).toHaveLength(1);
+    expect(reparsedTransitions[0].command[0].symbol).toBe("'\"'");
+  });
+
+  test('state name with grammar-significant chars survives round-trip', () => {
+    // <, >, &, " inside a State.name. Encoded as named entities; decoded
+    // verbatim on the way back.
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const name = 'A<&">B';
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, name);
+
+    const reparsed = fromMermaid(toMermaid(State.toGraph(s, tapeBlock)));
+    expect(reparsed.nodes[s.id].name).toBe(name);
+  });
+
+  test('tag name with grammar-significant chars survives round-trip', () => {
+    // Tag content is escaped per-fragment so a tag containing `<br>` or
+    // `,` doesn't get confused with the structural tag separators (which
+    // would split the tag wrong on the way back) or with HTML tag
+    // boundaries in the rendered SVG.
+    //
+    // The round-trip also picks up the `class tag_<sanitized>` line from
+    // the emit — that adds a second copy of each tag in its sanitized
+    // form (`has"quote` → `has_quote`). That's a known artifact of the
+    // #186 tag-emit design, not part of #194; this test only asserts
+    // that the ORIGINAL forms come back intact.
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 's').tag('a<br>b', 'has,comma', 'has"quote');
+
+    const reparsed = fromMermaid(toMermaid(State.toGraph(s, tapeBlock)));
+    expect(reparsed.nodes[s.id].tags).toEqual(
+      expect.arrayContaining(['a<br>b', 'has,comma', 'has"quote']),
+    );
+  });
+
+  test('newlines and C0 controls in alphabet symbols encode as numeric entities', () => {
+    const alphabet = new Alphabet([' ', 'a', '\n', '
']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['a'])]: {
+        command: [{symbol: '\n', movement: movements.right}],
+        nextState: haltState,
+      },
+    }, 's');
+
+    const mermaid = toMermaid(State.toGraph(s, tapeBlock));
+
+    // No raw newline inside the emitted line (other than the inter-line
+    // separators between statements).
+    const transitionLine = mermaid
+      .split('\n')
+      .find((l) => l.includes('-- "') && l.includes('--> '));
+    expect(transitionLine).toBeDefined();
+    expect(transitionLine).toContain('&#10;');
+
+    const reparsed = fromMermaid(mermaid);
+    expect(reparsed.nodes[s.id].transitions[0].command[0].symbol).toBe("'\n'");
+  });
+
+  test('bidi control in state name encodes as numeric entity', () => {
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const name = 'left‮right';
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, name);
+
+    const mermaid = toMermaid(State.toGraph(s, tapeBlock));
+    expect(mermaid).toContain('&#8238;');
+    expect(mermaid).not.toContain('‮');
+
+    const reparsed = fromMermaid(mermaid);
+    expect(reparsed.nodes[s.id].name).toBe(name);
+  });
+
+  test('printable Unicode passes through unescaped (alphabet readability)', () => {
+    // Cyrillic + CJK glyphs in the alphabet and state name. Alphabet
+    // rejects multi-code-unit symbols (`.length === 1` check) so emoji
+    // outside the BMP can't be tested at this layer — that's fine,
+    // surrogate-pair handling is covered by the encoder's regex range
+    // and the round-trip decode-path tests above.
+    const alphabet = new Alphabet([' ', 'я', '中']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['я'])]: {
+        command: [{symbol: '中', movement: movements.right}],
+        nextState: haltState,
+      },
+    }, 'имя');
+
+    const mermaid = toMermaid(State.toGraph(s, tapeBlock));
+    expect(mermaid).toContain('имя');
+    expect(mermaid).toContain('я');
+    expect(mermaid).toContain('中');
+    // No spurious numeric entities for printable Unicode.
+    expect(mermaid).not.toMatch(/&#\d+;/);
+  });
+
+  test('callable-subtree frame label escapes the bare name', () => {
+    // The frame label `callable subtree of NAME` interpolates the bare
+    // state's name. Quotes in the bare name would break the
+    // `subgraph w_N["..."]` declaration.
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const bare = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, 'b"are');
+    const wrapper = bare.withOverriddenHaltState(haltState);
+
+    const mermaid = toMermaid(State.toGraph(wrapper, tapeBlock));
+    expect(mermaid).toContain('callable subtree of b&quot;are');
+    // The subgraph declaration line itself has exactly two `"`s: the
+    // outer label wrappers. Any additional one would mean an unescaped
+    // user `"` slipped through.
+    const subgraphLine = mermaid
+      .split('\n')
+      .find((l) => l.trimStart().startsWith('subgraph w_'));
+    expect(subgraphLine).toBeDefined();
+    expect((subgraphLine!.match(/"/g) ?? []).length).toBe(2);
+  });
+
+  test('ambiguous `&amp;quot;` decodes once, not twice', () => {
+    // User content that looks like a doubly-encoded entity. Single-pass
+    // decode should give back the literal `&quot;` text, not `"`.
+    const alphabet = new Alphabet([' ', '0']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const name = '&quot;literal&quot;';
+    const s = new State({
+      [tapeBlock.symbol(['0'])]: {nextState: haltState},
+    }, name);
+
+    const reparsed = fromMermaid(toMermaid(State.toGraph(s, tapeBlock)));
+    expect(reparsed.nodes[s.id].name).toBe(name);
+  });
+});
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index e1dc59c..5f0fa35 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -46,6 +46,81 @@ function frameSubgraphId(frameId: number): string {
   return `w_${frameId}`;
 }
 
+// User-controlled content (state names, tag names, alphabet symbols inside
+// edge labels) is interpolated into Mermaid label strings (`"..."` wrappers
+// on nodes, wrappers, subgraphs, and edges). Mermaid's grammar terminates
+// the string on a literal `"`, and labels render via HTML/foreignObject so
+// `<`, `>`, `&` get interpreted as markup. Statement terminators (`\n`,
+// `\r`), C0 controls (except `\t`), DEL, bidi controls, and lone UTF-16
+// surrogates are encoded as numeric entities so they can't confuse the
+// tokenizer or flip text direction silently (#194).
+//
+// Printable Unicode (Cyrillic, CJK, emoji, accented Latin, etc.) passes
+// through unchanged — a tape alphabet of Cyrillic or Brainfuck glyphs
+// stays readable in the emitted `.mmd`.
+//
+// Escape is applied at the leaf — to each user-supplied fragment BEFORE
+// it's composed into a label. Structural pieces this module emits (`<br>`
+// tag separator, ` ∪ ` bare-name join, `[`, `]`, `,`, `|`, `/`, ` → `,
+// the `callable subtree of `/`callable scope: ` prefixes) are NOT escaped;
+// only user-controlled content is. fromMermaid mirrors with
+// `unescapeMermaidLabel` on each extracted leaf AFTER structural parsing,
+// so a literal `<br>` inside a state name (encoded as `&lt;br&gt;`)
+// survives the tag-split and decodes back at the leaf.
+const MERMAID_LABEL_ESCAPE_RE = /[&"<>\n\r\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\u202A-\u202E\u2066-\u2069\uD800-\uDFFF]/g;
+function escapeMermaidLabel(s: string): string {
+  return s.replace(MERMAID_LABEL_ESCAPE_RE, (ch) => {
+    switch (ch) {
+      case '&': return '&amp;';
+      case '"': return '&quot;';
+      case '<': return '&lt;';
+      case '>': return '&gt;';
+      case '\n': return '&#10;';
+      case '\r': return '&#13;';
+      default: return `&#${ch.charCodeAt(0)};`;
+    }
+  });
+}
+
+// Inverse of escapeMermaidLabel. Decodes the four named entities the
+// encoder emits (`&amp;`, `&quot;`, `&lt;`, `&gt;`) plus arbitrary
+// numeric entities (`&#NN;`, `&#xHH;`) — the latter to round-trip the
+// control / bidi / lone-surrogate cases from encode. Other named entities
+// pass through unchanged: fromMermaid is strict to the dialect toMermaid
+// emits, and a future-proof full HTML-entity decoder would muddle that.
+//
+// Replacement is single-pass: each `&...;` match is consumed once with
+// no re-scanning of the substitution, so nested-looking inputs like
+// `&amp;quot;` (literal `&quot;` as user text) decode to `&quot;` not `"`.
+const MERMAID_LABEL_UNESCAPE_RE = /&(?:(amp|quot|lt|gt)|#(\d+)|#x([0-9a-fA-F]+));/g;
+function unescapeMermaidLabel(s: string): string {
+  return s.replace(MERMAID_LABEL_UNESCAPE_RE, (match, named, dec, hex) => {
+    switch (named) {
+      case 'amp': return '&';
+      case 'quot': return '"';
+      case 'lt': return '<';
+      case 'gt': return '>';
+      default: {
+        // Code units up to U+FFFF decode via fromCharCode so lone
+        // surrogates we encoded by UTF-16 code unit round-trip exactly.
+        // Hand-edited supplementary code points (`&#x1F600;`) use
+        // fromCodePoint to produce the right surrogate pair — but only
+        // when we didn't emit them ourselves, since encode runs per code
+        // unit.
+        if (dec !== undefined) {
+          const n = Number.parseInt(dec, 10);
+          return n <= 0xFFFF ? String.fromCharCode(n) : String.fromCodePoint(n);
+        }
+        if (hex !== undefined) {
+          const n = Number.parseInt(hex, 16);
+          return n <= 0xFFFF ? String.fromCharCode(n) : String.fromCodePoint(n);
+        }
+        return match;
+      }
+    }
+  });
+}
+
 export function toMermaid(graph: Graph): string {
   const lines: string[] = [
     'flowchart TD',
@@ -89,9 +164,17 @@ export function toMermaid(graph: Graph): string {
   // Mermaid line-break that works across renderers without `classDef`-
   // pseudo-element hacks (#186).
   const labelOf = (node: GraphNode): string => {
-    if (node.tags.length === 0) return node.name;
-
-    return `${node.name}<br>${node.tags.join(', ')}`;
+    const name = escapeMermaidLabel(node.name);
+    if (node.tags.length === 0) return name;
+    // Per-tag escape that ALSO encodes `,` — tags are joined with `, ` and
+    // split on `,` in `splitLabelTags`, so a literal comma in user tag
+    // content would be mistaken for a separator on the way back. `,` isn't
+    // in the base escape set because it's structural in edge labels
+    // (between per-tape cells in `writes`/`moves`), where the encode pass
+    // happens after composition — different context, different escape.
+    const tagFragments = node.tags
+      .map((t) => escapeMermaidLabel(t).replace(/,/g, '&#44;'));
+    return `${name}<br>${tagFragments.join(', ')}`;
   };
 
   // 1. Emit top-level nodes (real halt, non-wrapper regulars outside any frame).
@@ -123,7 +206,7 @@ export function toMermaid(graph: Graph): string {
     const frameBareNames = frameBares
       .slice()
       .sort((a, b) => a.id - b.id)
-      .map((n) => n.name);
+      .map((n) => escapeMermaidLabel(n.name));
     const label = frameBareNames.length > 1
       ? `callable scope: ${frameBareNames.join(' ∪ ')}`
       : `callable subtree of ${frameBareNames[0] ?? frameId}`;
@@ -255,7 +338,12 @@ export function toMermaid(graph: Graph): string {
       const reads = alternatives.map((alt) => `[${alt}]`).join('|');
       const writes = `[${t.command.map((c) => c.symbol).join(',')}]`;
       const moves = `[${t.command.map((c) => c.movement).join(',')}]`;
-      const label = `${reads} → ${writes}/${moves}`;
+      // Escape the WHOLE composed label — structural separators ([, ], ,,
+      // |, /, ' → ') are all in our safe ASCII set and pass through
+      // unchanged; only embedded user alphabet symbols inside `'...'` get
+      // entity-encoded. fromMermaid unescapes the captured label as the
+      // first step before structural parsing.
+      const label = escapeMermaidLabel(`${reads} → ${writes}/${moves}`);
 
       lines.push(
         `  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`,
@@ -409,16 +497,25 @@ const classAssignTagRegex = /^class ([sc]\d+(?:,[sc]\d+)*) tag_([A-Za-z0-9_-]+)$
 // Labels without `<br>` have no tags. Tags are comma-joined; trimmed of
 // whitespace. The `<br>` is the single source of truth for tag-name parsing —
 // `class` lines are decorative-only and not consulted here.
+//
+// Mermaid-label entities (`&lt;`, `&quot;`, etc., #194) are decoded AFTER
+// structural splitting: the `<br>` separator and `,` tag delimiter survive
+// encode unchanged, and a user state name / tag containing a literal `<br>`
+// or `,` was encoded leaf-side so it can't be confused with the structural
+// form. Decode at the leaves recovers the original characters.
 function splitLabelTags(label: string): {name: string; tags: string[]} {
   const brIx = label.indexOf('<br>');
 
   if (brIx < 0) {
-    return {name: label, tags: []};
+    return {name: unescapeMermaidLabel(label), tags: []};
   }
 
-  const name = label.slice(0, brIx);
+  const name = unescapeMermaidLabel(label.slice(0, brIx));
   const tagsStr = label.slice(brIx + '<br>'.length);
-  const tags = tagsStr.split(',').map((t) => t.trim()).filter((t) => t.length > 0);
+  const tags = tagsStr
+    .split(',')
+    .map((t) => unescapeMermaidLabel(t.trim()))
+    .filter((t) => t.length > 0);
 
   return {name, tags};
 }
@@ -619,7 +716,12 @@ export function fromMermaid(text: string): Graph {
 
     if (tm) {
       const fromId = parseMermaidId(tm[1]);
-      const label = tm[2];
+      // Decode the WHOLE captured label up front (#194). Structural
+      // separators (`[`, `]`, `,`, `|`, `/`, ` → `) are all safe ASCII
+      // outside the escape set and pass through encode unchanged, so it's
+      // safe to decode before structural parsing; only embedded alphabet
+      // symbols inside `'...'` get reconstituted.
+      const label = unescapeMermaidLabel(tm[2]);
       const toId = parseMermaidId(tm[3]);
 
       const arrowIx = label.indexOf(' → ');

From bfe70b60db61e76dd0fa64a0060f0e49ba069250 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 10:55:41 +0300
Subject: [PATCH 034/118] refactor: extract toGraph/fromGraph into
 utilities/stateGraph (#180)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

State.ts was carrying ~440 lines of graph serialization/reconstruction
on top of the runtime state machinery. Move it to a sibling module:

- New `utilities/stateGraph.ts` holds `toGraph` and `fromGraph` plus
  their v7 callable-subtree comment block.
- `State.toGraph` and `State.fromGraph` become thin delegates to the
  extracted functions — public surface preserved, no consumer breaks.
- New `STATE_INTERNAL` Symbol on State exposes a getter/setter view
  onto private fields (`#id`, `#name`, `#bareState`,
  `#overriddenHaltState`, `#symbolToDataMap`, `#tags`) for sibling
  modules. Exported from State.ts so other files in
  `packages/machine/src` can import it; NOT re-exported from the
  package's `index.ts`, so it's off the public surface. Marked
  `@internal` in JSDoc.
- The Symbol's surface is designed with #195 already in scope:
  `collectStates` will need the same `symbolToDataMap` enumeration
  plus the existing `id` / `name` access, so the accessor doesn't
  need to grow when that lands.
- `fromGraph` uses the accessor's `name` setter to assign graph-
  sourced composite names (e.g. `A(target)`) to freshly-built bare
  States, bypassing the constructor's paren validation. That's the
  one mutation site; the setter exists for it alone and is JSDoc'd
  as such.

Import cycle State.ts ↔ stateGraph.ts resolves via ESM live bindings —
all cross-references live inside function bodies, so the bindings are
populated by the time anything reads them. Rollup flags the cycle in
the build output; it's expected.

Internal refactor, no API change. 473 tests still pass.
---
 packages/machine/src/classes/State.ts        | 549 +++----------------
 packages/machine/src/utilities/stateGraph.ts | 501 +++++++++++++++++
 2 files changed, 588 insertions(+), 462 deletions(-)
 create mode 100644 packages/machine/src/utilities/stateGraph.ts

diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index d83b636..aa07152 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -1,4 +1,3 @@
-import Alphabet from './Alphabet';
 import Command from './Command';
 import Reference from './Reference';
 import TapeBlock from './TapeBlock';
@@ -6,14 +5,14 @@ import TapeCommand from './TapeCommand';
 import {id} from '../utilities/functions';
 import {
   type Graph,
-  type GraphNode,
   decodeMovement,
-  decodePatternDescription,
   decodeWriteSymbol,
-  parseMovementLabel,
-  parsePatternString,
-  parseWriteSymbolLabel,
 } from '../utilities/graph';
+// Delegate targets for `State.toGraph` / `State.fromGraph` (#180). The
+// import cycle with stateGraph.ts is resolved by ESM live bindings — see
+// the bottom-of-file note in that module. Aliased so the delegating
+// static methods can keep their canonical names without clashing.
+import {toGraph as toGraphImpl, fromGraph as fromGraphImpl} from '../utilities/stateGraph';
 
 export const ifOtherSymbol = Symbol('other symbol');
 
@@ -21,6 +20,29 @@ export const ifOtherSymbol = Symbol('other symbol');
 // without exposing the validator on the public surface.
 const validateDebugFilter = Symbol('validateDebugFilter');
 
+/**
+ * @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 const STATE_INTERNAL = Symbol('State.internal');
+
 export class DebugConfig {
   readonly #ownerState: State;
 
@@ -369,6 +391,49 @@ export default class State {
     return 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]() {
+    // Aliasing `this` so the nested object-literal getters/setters below
+    // can read/write the enclosing State's private fields — getters in an
+    // object literal can't be arrow functions, so the standard arrow-
+    // captures-`this` trick doesn't apply here.
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
+
+    return {
+      get id(): number { return self.#id; },
+      get name(): string { return self.#name; },
+      set name(v: string) { self.#name = v; },
+      get bareState(): State | null { return self.#bareState; },
+      get overriddenHaltState(): State | null { return self.#overriddenHaltState; },
+      get symbolToDataMap() { return self.#symbolToDataMap; },
+      get tags(): ReadonlySet<string> { return self.#tags; },
+    };
+  }
+
   // Single-state introspection — no traversal, no tapeBlock required.
   // Returns id, name, halt-status, override-halt target, and the list of
   // transitions out of this state with decoded write/movement labels.
@@ -421,470 +486,30 @@ export default class State {
     };
   }
 
-  // Walks the State graph and emits a `Graph` data structure. v7 callable-
-  // subtree emit shape (#174):
-  //
-  // Each `withOverriddenHaltState` wrapper produces TWO graph nodes:
-  //   - A wrapper node (`isWrapper: true`, `[[composite-name]]` shape) — the
-  //     call site. No transitions of its own. `bareStateId` points to the
-  //     bare's GraphNode; `overriddenHaltStateId` points to the override
-  //     target's GraphNode.
-  //   - A bare node (`isWrapper: false`, regular shape) — the callable body.
-  //     Has the bare's transitions. Shared across all wrappers that wrap
-  //     this bare (no per-context duplication).
-  //
-  // Frames are computed via union-find on bare reachability: two bares whose
-  // forward-reachable sets overlap merge into one frame. Each frame contains
-  // its bares + body states + a single halt marker (id = `-frameId`). The
-  // canonical `frameId` is the smallest bare-id in the component.
-  //
-  // Halt-bound transitions of any in-frame state are retargeted to the
-  // frame's halt marker. The frame's `subtree -. return .-> wrapper` and
-  // `subtree -. halt .-> s0` arrows are demand-emitted by `toMermaid` from
-  // the frame structure; they're not stored as graph edges.
-  static toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
-    const nodes: Record<number, GraphNode> = {};
-    const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
-
-    // Pass 1: BFS-discover all reachable States; emit one GraphNode per State
-    // (wrapper or bare/regular). Wrappers and bares are separate nodes.
-    const visited = new Set<number>();
-    const queue: State[] = [initialState];
-    const bareIds = new Set<number>(); // ids referenced as a wrapper's bareStateId
-
-    while (queue.length > 0) {
-      const state = queue.shift()!;
-
-      if (visited.has(state.#id)) {
-        continue;
-      }
-
-      visited.add(state.#id);
-
-      if (state.isHalt) {
-        if (!(0 in nodes)) {
-          nodes[0] = {
-            id: 0,
-            name: state.#name,
-            isHalt: true,
-            isHaltMarker: false,
-            isWrapper: false,
-            bareStateId: null,
-            frameId: null,
-            transitions: [],
-            overriddenHaltStateId: null,
-            tags: [...state.#tags],
-          };
-        }
-
-        continue;
-      }
-
-      // Wrapper? Emit wrapper node + queue bare and override target.
-      if (state.#overriddenHaltState !== null && state.#bareState !== null) {
-        const bareState = state.#bareState;
-        const overrideTarget = state.#overriddenHaltState;
-
-        nodes[state.#id] = {
-          id: state.#id,
-          name: state.#name, // composite name like "A(target)"
-          isHalt: false,
-          isHaltMarker: false,
-          isWrapper: true,
-          bareStateId: bareState.#id,
-          frameId: null,
-          transitions: [],
-          overriddenHaltStateId: overrideTarget.#id,
-          tags: [...state.#tags],
-        };
-
-        bareIds.add(bareState.#id);
-        queue.push(bareState);
-        queue.push(overrideTarget);
-
-        continue;
-      }
-
-      // Regular (or bare) state — build node with transitions.
-      const node: GraphNode = {
-        id: state.#id,
-        name: state.#name,
-        isHalt: false,
-        isHaltMarker: false,
-        isWrapper: false,
-        bareStateId: null,
-        frameId: null,
-        transitions: [],
-        overriddenHaltStateId: null,
-        tags: [...state.#tags],
-      };
-
-      nodes[state.#id] = node;
-
-      let patternIx = 0;
-
-      for (const [sym, {command, nextState}] of state.#symbolToDataMap) {
-        let target: State;
-
-        try {
-          target = nextState instanceof State ? nextState : nextState.ref;
-        } catch {
-          patternIx += 1;
-          continue;
-        }
-
-        node.transitions.push({
-          pattern: decodePatternDescription(sym.description, alphabets),
-          command: command.tapesCommands.map((tc) => ({
-            symbol: decodeWriteSymbol(tc.symbol),
-            movement: decodeMovement((tc.movement as symbol).description),
-          })),
-          nextStateId: target.#id,
-          id: `${state.#id}-${patternIx}`,
-        });
-
-        queue.push(target);
-        patternIx += 1;
-      }
-    }
-
-    // Always emit real halt as a sentinel, even if no transition targets it.
-    // It anchors the `subtree -. halt .-> s0` frame-level arrow whenever a
-    // frame demand-emits one, and it's the canonical machine-halt singleton.
-    if (!(0 in nodes)) {
-      nodes[0] = {
-        id: 0,
-        name: 'halt',
-        isHalt: true,
-        isHaltMarker: false,
-        isWrapper: false,
-        bareStateId: null,
-        frameId: null,
-        transitions: [],
-        overriddenHaltStateId: null,
-        tags: [...haltState.#tags],
-      };
-    }
-
-    // Pass 2: For each bare, compute its forward-reachable set (following
-    // transitions; stopping at halt and at wrappers — both are frame
-    // boundaries).
-    const computeReach = (startId: number): Set<number> => {
-      const reach = new Set<number>();
-      const stack = [startId];
-
-      while (stack.length > 0) {
-        const id = stack.pop()!;
-
-        if (reach.has(id)) {
-          continue;
-        }
-
-        const node = nodes[id];
-
-        // `nodes[id]` is always populated for `id` that the BFS reached, so
-        // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
-        // are real boundaries — both stop reach-set expansion.
-        if (node.isHalt || node.isWrapper) {
-          continue;
-        }
-
-        reach.add(id);
-
-        for (const t of node.transitions) {
-          const target = nodes[t.nextStateId];
-
-          if (!target || target.isHalt || target.isWrapper) {
-            continue;
-          }
-
-          stack.push(t.nextStateId);
-        }
-      }
-
-      return reach;
-    };
-
-    const reachByBare = new Map<number, Set<number>>();
-
-    for (const bareId of bareIds) {
-      reachByBare.set(bareId, computeReach(bareId));
-    }
-
-    // Pass 3: Union-find on bare overlaps. Two bares merge if their reach
-    // sets share any state. Canonical representative = smallest bare-id in
-    // the component.
-    const ufParent = new Map<number, number>();
-
-    // Note: no path compression. The union policy below ("smaller id always
-    // becomes root") keeps the tree flat — every union targets bares[0] as
-    // the root, so any node's parent IS the root. Walking up never exceeds
-    // one step. Path compression would be dead code under this invariant.
-    const ufFind = (id: number): number => {
-      if (!ufParent.has(id)) {
-        ufParent.set(id, id);
-      }
-
-      let root = id;
-
-      while (ufParent.get(root) !== root) {
-        root = ufParent.get(root)!;
-      }
-
-      return root;
-    };
-
-    const ufUnion = (a: number, b: number) => {
-      const ra = ufFind(a);
-      const rb = ufFind(b);
-
-      if (ra === rb) return;
-
-      if (ra < rb) {
-        ufParent.set(rb, ra);
-      } else {
-        ufParent.set(ra, rb);
-      }
-    };
-
-    for (const bareId of bareIds) {
-      ufFind(bareId);
-    }
-
-    // For each state, collect the bares that reach it; union all bares that
-    // share a state.
-    const stateToReachingBares = new Map<number, number[]>();
-
-    for (const [bareId, reachSet] of reachByBare) {
-      for (const stateId of reachSet) {
-        let bares = stateToReachingBares.get(stateId);
-
-        if (!bares) {
-          bares = [];
-          stateToReachingBares.set(stateId, bares);
-        }
-
-        bares.push(bareId);
-      }
-    }
-
-    for (const bares of stateToReachingBares.values()) {
-      for (let i = 1; i < bares.length; i += 1) {
-        ufUnion(bares[0], bares[i]);
-      }
-    }
-
-    // Assign frameId to each in-reach state.
-    const frameIds = new Set<number>();
-
-    for (const [stateId, bares] of stateToReachingBares) {
-      const frameId = ufFind(bares[0]);
-
-      nodes[stateId].frameId = frameId;
-      frameIds.add(frameId);
-    }
-
-    // Pass 4: Retarget halt-bound transitions for in-frame states to the
-    // frame's halt marker. Out-of-frame states (top-level dispatcher, override
-    // targets, etc.) keep their halt-bound transitions pointing at real halt.
-    for (const node of Object.values(nodes)) {
-      if (node.frameId === null) {
-        continue;
-      }
-
-      const haltMarkerId = -node.frameId;
-
-      for (const t of node.transitions) {
-        const target = nodes[t.nextStateId];
-
-        if (target && target.isHalt && !target.isHaltMarker) {
-          t.nextStateId = haltMarkerId;
-        }
-      }
-    }
-
-    // Pass 5: Emit one halt marker per frame.
-    for (const frameId of frameIds) {
-      const haltMarkerId = -frameId;
-
-      nodes[haltMarkerId] = {
-        id: haltMarkerId,
-        name: 'halt',
-        isHalt: true,
-        isHaltMarker: true,
-        isWrapper: false,
-        bareStateId: null,
-        frameId,
-        transitions: [],
-        overriddenHaltStateId: null,
-        tags: [],
-      };
-    }
 
-    return {initialId: initialState.#id, alphabets, nodes};
+  /**
+   * 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 {
+    return toGraphImpl(initialState, tapeBlock);
   }
 
-  // Inverse of toGraph: rebuilds a State graph (and a fresh TapeBlock with the
-  // graph's alphabets) from a serialized Graph. Round-trips with toGraph in
-  // the sense that running the rebuilt machine on the same input gives the
-  // same output, but the rebuilt State instances have *new* internal IDs.
-  //
-  // Under the v7 callable-subtree model (#174), graph nodes split into:
-  //   - Wrapper nodes (`isWrapper: true`, no transitions) — reconstructed via
-  //     `bareStates[bareStateId].withOverriddenHaltState(finalStates[overriddenHaltStateId])`.
-  //   - Bare/regular nodes — constructed as normal States with transitions.
-  //   - Halt + halt-marker nodes — collapse to the singleton `haltState`.
+  /**
+   * 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>;
   } {
-    const alphabetObjs = graph.alphabets.map((syms) => new Alphabet(syms));
-    const tapeBlock = TapeBlock.fromAlphabets(alphabetObjs);
-    const ids = Object.keys(graph.nodes).map(Number);
-
-    // Pass 1: pre-create a Reference for each non-halt non-halt-marker node
-    // (both wrappers and regulars). Halt and halt-marker nodes collapse to the
-    // singleton `haltState` and need no ref.
-    const refs: Record<number, Reference> = {};
-
-    for (const nodeId of ids) {
-      const node = graph.nodes[nodeId];
-
-      if (!node.isHalt) {
-        refs[nodeId] = new Reference();
-      }
-    }
-
-    // Convert a parsed pattern back to the symbol key the State expects.
-    const patternToKey = (parsed: ReturnType<typeof parsePatternString>): symbol => {
-      if (parsed === null) {
-        return ifOtherSymbol;
-      }
-
-      const flat: (string | symbol)[] = [];
-
-      for (const row of parsed) {
-        for (const cell of row) {
-          flat.push(cell === null ? ifOtherSymbol : cell);
-        }
-      }
-
-      return tapeBlock.symbol(flat);
-    };
-
-    // Pass 2: build a State for each non-wrapper non-halt non-halt-marker
-    // node. Transitions point at refs so cycles work; haltState (and halt
-    // markers, which collapse to haltState) are used directly.
-    const bareStates: Record<number, State> = {};
-
-    for (const nodeId of ids) {
-      const node = graph.nodes[nodeId];
-
-      if (node.isHalt || node.isWrapper) {
-        continue;
-      }
-
-      const stateDefinition: ConstructorParameters<typeof State>[0] = {};
-
-      for (const t of node.transitions) {
-        const key = patternToKey(parsePatternString(t.pattern, graph.alphabets));
-        const target = graph.nodes[t.nextStateId];
-        const nextState: State | Reference = !target || target.isHalt
-          ? haltState
-          : refs[t.nextStateId];
-
-        stateDefinition![key] = {
-          command: t.command.map((c) => ({
-            symbol: parseWriteSymbolLabel(c.symbol),
-            movement: parseMovementLabel(c.movement),
-          })) as ConstructorParameters<typeof TapeCommand>[0][],
-          nextState,
-        };
-      }
-
-      // Graph-sourced names may contain `(` and `)` (composite wrapper names —
-      // although wrappers go through a separate path below, defensive
-      // construction here keeps the bypass uniform). Construct without a name
-      // and assign `#name` directly to skip user-facing name validation.
-      const bare = new State(stateDefinition);
-
-      bare.#name = node.name;
-
-      if (node.tags.length > 0) {
-        bare.tag(...node.tags);
-      }
-
-      bareStates[nodeId] = bare;
-    }
-
-    // Pass 3: resolve every node to its final State (memoized + cycle-safe).
-    // Wrappers compose lazily via `withOverriddenHaltState` once their bare
-    // and override are resolved.
-    const finalStates: Record<number, State> = {};
-    const inProgress = new Set<number>();
-
-    const getFinal = (nodeId: number): State => {
-      if (finalStates[nodeId]) {
-        return finalStates[nodeId];
-      }
-
-      const node = graph.nodes[nodeId];
-
-      if (!node || node.isHalt) {
-        finalStates[nodeId] = haltState;
-
-        return haltState;
-      }
-
-      if (inProgress.has(nodeId)) {
-        throw new Error(`override-halt cycle at state #${nodeId}`);
-      }
-
-      inProgress.add(nodeId);
-
-      let state: State;
-
-      if (node.isWrapper) {
-        const bare = getFinal(node.bareStateId!);
-        const override = getFinal(node.overriddenHaltStateId!);
-
-        state = bare.withOverriddenHaltState(override);
-
-        // Apply wrapper-scoped tags (#186). Tags don't leak across wrappers
-        // sharing a bare — the wrapper instance owns its own tag set, and
-        // engine #175 memoization returns the same instance for the same
-        // (bare, override) pair, so this is idempotent across rebuilds.
-        if (node.tags.length > 0) {
-          state.tag(...node.tags);
-        }
-      } else {
-        state = bareStates[nodeId];
-      }
-
-      inProgress.delete(nodeId);
-      finalStates[nodeId] = state;
-
-      return state;
-    };
-
-    for (const nodeId of ids) {
-      getFinal(nodeId);
-    }
-
-    // Pass 4: bind each ref to the resolved final State so cross-node
-    // transitions land on the right instance.
-    for (const nodeId of ids) {
-      if (!graph.nodes[nodeId].isHalt) {
-        refs[nodeId].bind(finalStates[nodeId]);
-      }
-    }
-
-    return {
-      start: finalStates[graph.initialId],
-      tapeBlock,
-      states: finalStates,
-    };
+    return fromGraphImpl(graph);
   }
 }
 
diff --git a/packages/machine/src/utilities/stateGraph.ts b/packages/machine/src/utilities/stateGraph.ts
new file mode 100644
index 0000000..e55cf05
--- /dev/null
+++ b/packages/machine/src/utilities/stateGraph.ts
@@ -0,0 +1,501 @@
+import Alphabet from '../classes/Alphabet';
+import Reference from '../classes/Reference';
+import State, {STATE_INTERNAL, haltState, ifOtherSymbol} from '../classes/State';
+import TapeBlock from '../classes/TapeBlock';
+import type TapeCommand from '../classes/TapeCommand';
+import {
+  type Graph,
+  type GraphNode,
+  decodeMovement,
+  decodePatternDescription,
+  decodeWriteSymbol,
+  parseMovementLabel,
+  parsePatternString,
+  parseWriteSymbolLabel,
+} from './graph';
+
+// Graph serialization/reconstruction for State graphs. Extracted from
+// `classes/State.ts` (#180) so the State class stays focused on the runtime
+// machinery (transitions, debug, halt-stack composition). Sibling-module
+// private access to State's internals goes through the `STATE_INTERNAL`
+// Symbol re-exported from State.ts — see the @internal JSDoc there.
+//
+// Public surface is preserved: `State.toGraph` and `State.fromGraph` static
+// methods continue to exist as thin delegates to the functions in this
+// module. New consumers (e.g. #195's planned `collectStates`) will live
+// here too and share the BFS-walk shape with `toGraph`.
+
+/**
+ * Walks the reachable graph from `initialState` and returns a serializable
+ * `Graph`. The walk is a BFS that visits each State exactly once (keyed by
+ * the State's internal id) and emits one `GraphNode` per State plus
+ * synthetic halt-marker nodes per callable-subtree frame.
+ *
+ * Round-trips losslessly with `fromGraph` in the sense that running the
+ * rebuilt machine on the same input produces the same output — but State
+ * instance identities are NOT preserved across the cycle.
+ *
+ * See `classes/State.ts` for the runtime model these graph nodes describe;
+ * see `utilities/graphFormats.ts` for the Mermaid-flavored serialization
+ * built on top of `Graph`.
+ */
+export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
+  const nodes: Record<number, GraphNode> = {};
+  const alphabets = tapeBlock.alphabets.map((alphabet) => alphabet.symbols);
+
+  // Pass 1: BFS-discover all reachable States; emit one GraphNode per State
+  // (wrapper or bare/regular). Wrappers and bares are separate nodes.
+  const visited = new Set<number>();
+  const queue: State[] = [initialState];
+  const bareIds = new Set<number>(); // ids referenced as a wrapper's bareStateId
+
+  while (queue.length > 0) {
+    const state = queue.shift()!;
+    const stateInternal = state[STATE_INTERNAL]();
+
+    if (visited.has(stateInternal.id)) {
+      continue;
+    }
+
+    visited.add(stateInternal.id);
+
+    if (state.isHalt) {
+      if (!(0 in nodes)) {
+        nodes[0] = {
+          id: 0,
+          name: stateInternal.name,
+          isHalt: true,
+          isHaltMarker: false,
+          isWrapper: false,
+          bareStateId: null,
+          frameId: null,
+          transitions: [],
+          overriddenHaltStateId: null,
+          tags: [...stateInternal.tags],
+        };
+      }
+
+      continue;
+    }
+
+    // Wrapper? Emit wrapper node + queue bare and override target.
+    if (stateInternal.overriddenHaltState !== null && stateInternal.bareState !== null) {
+      const bareState = stateInternal.bareState;
+      const overrideTarget = stateInternal.overriddenHaltState;
+      const bareInternal = bareState[STATE_INTERNAL]();
+      const overrideInternal = overrideTarget[STATE_INTERNAL]();
+
+      nodes[stateInternal.id] = {
+        id: stateInternal.id,
+        name: stateInternal.name, // composite name like "A(target)"
+        isHalt: false,
+        isHaltMarker: false,
+        isWrapper: true,
+        bareStateId: bareInternal.id,
+        frameId: null,
+        transitions: [],
+        overriddenHaltStateId: overrideInternal.id,
+        tags: [...stateInternal.tags],
+      };
+
+      bareIds.add(bareInternal.id);
+      queue.push(bareState);
+      queue.push(overrideTarget);
+
+      continue;
+    }
+
+    // Regular (or bare) state — build node with transitions.
+    const node: GraphNode = {
+      id: stateInternal.id,
+      name: stateInternal.name,
+      isHalt: false,
+      isHaltMarker: false,
+      isWrapper: false,
+      bareStateId: null,
+      frameId: null,
+      transitions: [],
+      overriddenHaltStateId: null,
+      tags: [...stateInternal.tags],
+    };
+
+    nodes[stateInternal.id] = node;
+
+    let patternIx = 0;
+
+    for (const [sym, {command, nextState}] of stateInternal.symbolToDataMap) {
+      let target: State;
+
+      try {
+        target = nextState instanceof State ? nextState : nextState.ref;
+      } catch {
+        patternIx += 1;
+        continue;
+      }
+
+      const targetInternal = target[STATE_INTERNAL]();
+
+      node.transitions.push({
+        pattern: decodePatternDescription(sym.description, alphabets),
+        command: command.tapesCommands.map((tc) => ({
+          symbol: decodeWriteSymbol(tc.symbol),
+          movement: decodeMovement((tc.movement as symbol).description),
+        })),
+        nextStateId: targetInternal.id,
+        id: `${stateInternal.id}-${patternIx}`,
+      });
+
+      queue.push(target);
+      patternIx += 1;
+    }
+  }
+
+  // Always emit real halt as a sentinel, even if no transition targets it.
+  // It anchors the `subtree -. halt .-> s0` frame-level arrow whenever a
+  // frame demand-emits one, and it's the canonical machine-halt singleton.
+  if (!(0 in nodes)) {
+    nodes[0] = {
+      id: 0,
+      name: 'halt',
+      isHalt: true,
+      isHaltMarker: false,
+      isWrapper: false,
+      bareStateId: null,
+      frameId: null,
+      transitions: [],
+      overriddenHaltStateId: null,
+      tags: [...haltState[STATE_INTERNAL]().tags],
+    };
+  }
+
+  // Pass 2: For each bare, compute its forward-reachable set (following
+  // transitions; stopping at halt and at wrappers — both are frame
+  // boundaries).
+  const computeReach = (startId: number): Set<number> => {
+    const reach = new Set<number>();
+    const stack = [startId];
+
+    while (stack.length > 0) {
+      const id = stack.pop()!;
+
+      if (reach.has(id)) {
+        continue;
+      }
+
+      const node = nodes[id];
+
+      // `nodes[id]` is always populated for `id` that the BFS reached, so
+      // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
+      // are real boundaries — both stop reach-set expansion.
+      if (node.isHalt || node.isWrapper) {
+        continue;
+      }
+
+      reach.add(id);
+
+      for (const t of node.transitions) {
+        const target = nodes[t.nextStateId];
+
+        if (!target || target.isHalt || target.isWrapper) {
+          continue;
+        }
+
+        stack.push(t.nextStateId);
+      }
+    }
+
+    return reach;
+  };
+
+  const reachByBare = new Map<number, Set<number>>();
+
+  for (const bareId of bareIds) {
+    reachByBare.set(bareId, computeReach(bareId));
+  }
+
+  // Pass 3: Union-find on bare overlaps. Two bares merge if their reach
+  // sets share any state. Canonical representative = smallest bare-id in
+  // the component.
+  const ufParent = new Map<number, number>();
+
+  // Note: no path compression. The union policy below ("smaller id always
+  // becomes root") keeps the tree flat — every union targets bares[0] as
+  // the root, so any node's parent IS the root. Walking up never exceeds
+  // one step. Path compression would be dead code under this invariant.
+  const ufFind = (id: number): number => {
+    if (!ufParent.has(id)) {
+      ufParent.set(id, id);
+    }
+
+    let root = id;
+
+    while (ufParent.get(root) !== root) {
+      root = ufParent.get(root)!;
+    }
+
+    return root;
+  };
+
+  const ufUnion = (a: number, b: number) => {
+    const ra = ufFind(a);
+    const rb = ufFind(b);
+
+    if (ra === rb) return;
+
+    if (ra < rb) {
+      ufParent.set(rb, ra);
+    } else {
+      ufParent.set(ra, rb);
+    }
+  };
+
+  for (const bareId of bareIds) {
+    ufFind(bareId);
+  }
+
+  // For each state, collect the bares that reach it; union all bares that
+  // share a state.
+  const stateToReachingBares = new Map<number, number[]>();
+
+  for (const [bareId, reachSet] of reachByBare) {
+    for (const stateId of reachSet) {
+      let bares = stateToReachingBares.get(stateId);
+
+      if (!bares) {
+        bares = [];
+        stateToReachingBares.set(stateId, bares);
+      }
+
+      bares.push(bareId);
+    }
+  }
+
+  for (const bares of stateToReachingBares.values()) {
+    for (let i = 1; i < bares.length; i += 1) {
+      ufUnion(bares[0], bares[i]);
+    }
+  }
+
+  // Assign frameId to each in-reach state.
+  const frameIds = new Set<number>();
+
+  for (const [stateId, bares] of stateToReachingBares) {
+    const frameId = ufFind(bares[0]);
+
+    nodes[stateId].frameId = frameId;
+    frameIds.add(frameId);
+  }
+
+  // Pass 4: Retarget halt-bound transitions for in-frame states to the
+  // frame's halt marker. Out-of-frame states (top-level dispatcher, override
+  // targets, etc.) keep their halt-bound transitions pointing at real halt.
+  for (const node of Object.values(nodes)) {
+    if (node.frameId === null) {
+      continue;
+    }
+
+    const haltMarkerId = -node.frameId;
+
+    for (const t of node.transitions) {
+      const target = nodes[t.nextStateId];
+
+      if (target && target.isHalt && !target.isHaltMarker) {
+        t.nextStateId = haltMarkerId;
+      }
+    }
+  }
+
+  // Pass 5: Emit one halt marker per frame.
+  for (const frameId of frameIds) {
+    const haltMarkerId = -frameId;
+
+    nodes[haltMarkerId] = {
+      id: haltMarkerId,
+      name: 'halt',
+      isHalt: true,
+      isHaltMarker: true,
+      isWrapper: false,
+      bareStateId: null,
+      frameId,
+      transitions: [],
+      overriddenHaltStateId: null,
+      tags: [],
+    };
+  }
+
+  return {initialId: initialState[STATE_INTERNAL]().id, alphabets, nodes};
+}
+
+/**
+ * Inverse of `toGraph`: rebuilds a State graph (and a fresh TapeBlock with
+ * the graph's alphabets) from a serialized Graph. Round-trips with `toGraph`
+ * in the sense that running the rebuilt machine on the same input gives the
+ * same output, but the rebuilt State instances have *new* internal IDs.
+ *
+ * Under the v7 callable-subtree model (#174), graph nodes split into:
+ *   - Wrapper nodes (`isWrapper: true`, no transitions) — reconstructed via
+ *     `bareStates[bareStateId].withOverriddenHaltState(finalStates[overriddenHaltStateId])`.
+ *   - Bare/regular nodes — constructed as normal States with transitions.
+ *   - Halt + halt-marker nodes — collapse to the singleton `haltState`.
+ */
+export function fromGraph(graph: Graph): {
+  start: State;
+  tapeBlock: TapeBlock;
+  states: Record<number, State>;
+} {
+  const alphabetObjs = graph.alphabets.map((syms) => new Alphabet(syms));
+  const tapeBlock = TapeBlock.fromAlphabets(alphabetObjs);
+  const ids = Object.keys(graph.nodes).map(Number);
+
+  // Pass 1: pre-create a Reference for each non-halt non-halt-marker node
+  // (both wrappers and regulars). Halt and halt-marker nodes collapse to the
+  // singleton `haltState` and need no ref.
+  const refs: Record<number, Reference> = {};
+
+  for (const nodeId of ids) {
+    const node = graph.nodes[nodeId];
+
+    if (!node.isHalt) {
+      refs[nodeId] = new Reference();
+    }
+  }
+
+  // Convert a parsed pattern back to the symbol key the State expects.
+  const patternToKey = (parsed: ReturnType<typeof parsePatternString>): symbol => {
+    if (parsed === null) {
+      return ifOtherSymbol;
+    }
+
+    const flat: (string | symbol)[] = [];
+
+    for (const row of parsed) {
+      for (const cell of row) {
+        flat.push(cell === null ? ifOtherSymbol : cell);
+      }
+    }
+
+    return tapeBlock.symbol(flat);
+  };
+
+  // Pass 2: build a State for each non-wrapper non-halt non-halt-marker
+  // node. Transitions point at refs so cycles work; haltState (and halt
+  // markers, which collapse to haltState) are used directly.
+  const bareStates: Record<number, State> = {};
+
+  for (const nodeId of ids) {
+    const node = graph.nodes[nodeId];
+
+    if (node.isHalt || node.isWrapper) {
+      continue;
+    }
+
+    const stateDefinition: ConstructorParameters<typeof State>[0] = {};
+
+    for (const t of node.transitions) {
+      const key = patternToKey(parsePatternString(t.pattern, graph.alphabets));
+      const target = graph.nodes[t.nextStateId];
+      const nextState: State | Reference = !target || target.isHalt
+        ? haltState
+        : refs[t.nextStateId];
+
+      stateDefinition![key] = {
+        command: t.command.map((c) => ({
+          symbol: parseWriteSymbolLabel(c.symbol),
+          movement: parseMovementLabel(c.movement),
+        })) as ConstructorParameters<typeof TapeCommand>[0][],
+        nextState,
+      };
+    }
+
+    // Graph-sourced names may contain `(` and `)` (composite wrapper names —
+    // although wrappers go through a separate path below, defensive
+    // construction here keeps the bypass uniform). Construct without a name
+    // and assign `name` directly through the internal accessor's setter to
+    // skip the constructor's user-facing name validation.
+    const bare = new State(stateDefinition);
+
+    bare[STATE_INTERNAL]().name = node.name;
+
+    if (node.tags.length > 0) {
+      bare.tag(...node.tags);
+    }
+
+    bareStates[nodeId] = bare;
+  }
+
+  // Pass 3: resolve every node to its final State (memoized + cycle-safe).
+  // Wrappers compose lazily via `withOverriddenHaltState` once their bare
+  // and override are resolved.
+  const finalStates: Record<number, State> = {};
+  const inProgress = new Set<number>();
+
+  const getFinal = (nodeId: number): State => {
+    if (finalStates[nodeId]) {
+      return finalStates[nodeId];
+    }
+
+    const node = graph.nodes[nodeId];
+
+    if (!node || node.isHalt) {
+      finalStates[nodeId] = haltState;
+
+      return haltState;
+    }
+
+    if (inProgress.has(nodeId)) {
+      throw new Error(`override-halt cycle at state #${nodeId}`);
+    }
+
+    inProgress.add(nodeId);
+
+    let state: State;
+
+    if (node.isWrapper) {
+      const bare = getFinal(node.bareStateId!);
+      const override = getFinal(node.overriddenHaltStateId!);
+
+      state = bare.withOverriddenHaltState(override);
+
+      // Apply wrapper-scoped tags (#186). Tags don't leak across wrappers
+      // sharing a bare — the wrapper instance owns its own tag set, and
+      // engine #175 memoization returns the same instance for the same
+      // (bare, override) pair, so this is idempotent across rebuilds.
+      if (node.tags.length > 0) {
+        state.tag(...node.tags);
+      }
+    } else {
+      state = bareStates[nodeId];
+    }
+
+    inProgress.delete(nodeId);
+    finalStates[nodeId] = state;
+
+    return state;
+  };
+
+  for (const nodeId of ids) {
+    getFinal(nodeId);
+  }
+
+  // Pass 4: bind each ref to the resolved final State so cross-node
+  // transitions land on the right instance.
+  for (const nodeId of ids) {
+    if (!graph.nodes[nodeId].isHalt) {
+      refs[nodeId].bind(finalStates[nodeId]);
+    }
+  }
+
+  return {
+    start: finalStates[graph.initialId],
+    tapeBlock,
+    states: finalStates,
+  };
+}
+
+// Note on the import cycle with `State.ts`: stateGraph.ts value-imports
+// `State`, `STATE_INTERNAL`, `haltState`, and `ifOtherSymbol`; State.ts
+// value-imports `toGraph` and `fromGraph` for its static-method delegates.
+// ESM resolves cycles via live bindings — both modules see each other's
+// exports as long as nothing at module-load reads a binding before its
+// source module finishes evaluating. All references here live inside
+// function bodies, so the cycle is safe.

From ded0b41581167a12bb99854a183d6c4257015d96 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 11:00:22 +0300
Subject: [PATCH 035/118] test: STATE_INTERNAL accessor coverage (#180)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six direct tests for the new accessor:
- shape: id, name, bareState, overriddenHaltState, symbolToDataMap, tags
  all reachable from the view object
- live read: a `name` set via the accessor is visible through
  `state.name` (the public getter), pinning the closes-over-this
  behavior fromGraph relies on
- name setter bypasses the constructor's paren validation — the
  explicit reason for the setter existing in the first place
- symbolToDataMap iterates in insertion order, the contract #195's
  `transitionSymbols[patternIx]` will lean on
- haltState's accessor works (toGraph uses it for halt-node tags)
- each call returns a fresh view object — not load-bearing, but
  pinned so we notice if it changes

Tests use the existing @internal STATE_INTERNAL Symbol re-exported
from State.ts.
---
 packages/machine/src/classes/State.spec.ts | 94 +++++++++++++++++++++-
 1 file changed, 93 insertions(+), 1 deletion(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index b29e180..b1eb68f 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -1,6 +1,6 @@
 import Alphabet from './Alphabet';
 import Reference from './Reference';
-import State, {haltState, ifOtherSymbol} from './State';
+import State, {STATE_INTERNAL, haltState, ifOtherSymbol} from './State';
 import TapeBlock from './TapeBlock';
 import {movements, symbolCommands} from './TapeCommand';
 
@@ -571,3 +571,95 @@ describe('State.fromGraph — cyclic override-halt chain', () => {
     expect(() => State.fromGraph(graph)).toThrow(/^override-halt cycle at state #/);
   });
 });
+
+describe('STATE_INTERNAL accessor (#180)', () => {
+  test('exposes id, name, bareState, overriddenHaltState, symbolToDataMap, tags', () => {
+    const bare = new State({
+      [symbol(['0'])]: {nextState: haltState},
+    }, 'bare');
+    const wrapper = bare.withOverriddenHaltState(haltState);
+    wrapper.tag('hot');
+
+    const wrapperView = wrapper[STATE_INTERNAL]();
+
+    expect(wrapperView.id).toBe(wrapper.id);
+    expect(wrapperView.name).toBe(wrapper.name);
+    expect(wrapperView.bareState).toBe(bare);
+    expect(wrapperView.overriddenHaltState).toBe(haltState);
+    expect(wrapperView.symbolToDataMap).toBeInstanceOf(Map);
+    expect([...wrapperView.tags]).toEqual(['hot']);
+  });
+
+  test('read access is live — name setter is reflected by subsequent public reads', () => {
+    // The accessor closes over `this`, so reading via `state.name` after
+    // the setter mutates `#name` must see the new value. fromGraph relies
+    // on this when assigning graph-sourced composite names to freshly-
+    // constructed bares.
+    const s = new State({
+      [symbol(['0'])]: {nextState: haltState},
+    }, 'before');
+
+    expect(s.name).toBe('before');
+
+    s[STATE_INTERNAL]().name = 'after(set)';
+
+    expect(s.name).toBe('after(set)');
+  });
+
+  test('name setter bypasses the constructor\'s paren validation', () => {
+    // The constructor rejects `(` / `)` in names because those are
+    // reserved as wrapper-composition delimiters. The setter intentionally
+    // skips that check — wrappers' composite names round-tripped through
+    // a serialized graph legitimately contain parens, and fromGraph needs
+    // to restore them.
+    expect(() => new State(null, 'with(parens)')).toThrow(/must not contain/);
+
+    const s = new State(null, 'plain');
+    s[STATE_INTERNAL]().name = 'with(parens)';
+    expect(s.name).toBe('with(parens)');
+  });
+
+  test('symbolToDataMap exposes the live Map for sibling-module enumeration', () => {
+    // #195 will enumerate this Map's keys to expose per-transition
+    // pattern Symbols by patternIx. The accessor returns the same
+    // instance the State holds, in insertion order — not a copy.
+    const sym0 = symbol(['0']);
+    const sym1 = symbol(['1']);
+    const s = new State({
+      [sym0]: {nextState: haltState},
+      [sym1]: {nextState: haltState},
+    }, 's');
+
+    const view = s[STATE_INTERNAL]();
+    const keys = [...view.symbolToDataMap.keys()];
+
+    expect(keys).toContain(sym0);
+    expect(keys).toContain(sym1);
+    // Order matches construction order — the contract that #195's
+    // `transitionSymbols[patternIx]` will lean on.
+    expect(keys.indexOf(sym0)).toBeLessThan(keys.indexOf(sym1));
+  });
+
+  test('haltState accessor works (used by toGraph for halt-node tags)', () => {
+    // toGraph reads `haltState[STATE_INTERNAL]().tags` when emitting the
+    // halt node. The halt singleton is a regular State — its accessor
+    // must work the same as any other State's. Name is the default
+    // `id:0` from the no-name constructor at the bottom of State.ts;
+    // toGraph maps it to the literal `'halt'` separately in its halt-
+    // node emit path.
+    const view = haltState[STATE_INTERNAL]();
+
+    expect(view.id).toBe(0);
+    expect(view.name).toBe('id:0');
+    expect([...view.tags]).toEqual([]);
+  });
+
+  test('returns a fresh view object per call', () => {
+    // Not part of the documented contract — but worth pinning so we
+    // don't accidentally start sharing state across calls. Each
+    // invocation should produce an independent object literal; only the
+    // closed-over State instance is shared.
+    const s = new State(null, 's');
+    expect(s[STATE_INTERNAL]()).not.toBe(s[STATE_INTERNAL]());
+  });
+});

From ce43e43998b44917ad31115729f857f4f2370f00 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 11:37:02 +0300
Subject: [PATCH 036/118] =?UTF-8?q?feat:=20State.collectStates=20=E2=80=94?=
 =?UTF-8?q?=20id=20->=20{state,=20transitionSymbols}=20(#195)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a `State.collectStates(initialState, tapeBlock)` static (and the
underlying `collectStates` in `utilities/stateGraph.ts`) that returns a
`Map<number, {state: State; transitionSymbols: symbol[]}>` keyed by
engine `GraphNode.id`. Lets downstream tooling mutate `state.debug` on
a specific State by numeric id and set per-pattern breakpoints by
`GraphTransition.id`, neither of which was reachable from outside the
engine before.

Coverage:
- Regular / bare states: `transitionSymbols` is
  `[...#symbolToDataMap.keys()]` verbatim — every key in insertion
  order including `ifOtherSymbol`. The K-th entry is positionally
  aligned with the GraphTransition whose id is `${stateId}-${K}`.
- Wrapper states: entry exists with empty `transitionSymbols`.
- Halt singleton (id 0): entry points at the engine-wide `haltState`,
  empty `transitionSymbols`. JSDoc warns toggling its debug is global.
- Halt markers (synthetic, id = -frameId): excluded — they collapse to
  haltState at runtime, and the named consumer (machines-demo#37)
  surfaces halt-pause via a separate UI control. Additive extension
  available later if a future consumer needs uniform-by-id lookup.

Implementation anchors on toGraph: one call gives the authoritative id
set + halt-marker flags. A lighter BFS over the State graph maps id →
State instance. The result is built by iterating `graph.nodes` and
dispatching on node kind. The patternIx alignment can't drift because
both surfaces enumerate `#symbolToDataMap` in the same insertion order.

Builds on #180's `STATE_INTERNAL` accessor — no further internal-access
surface growth needed.

Tests: alignment contract over a realistic state, insertion-order pin,
`ifOtherSymbol`-at-natural-slot, wrapper-entry shape, halt-singleton
identity, halt-markers-excluded, unbound-`Reference`-slot, and a
static-delegate-equivalence sanity check.
---
 packages/machine/src/classes/State.ts         |  20 +-
 packages/machine/src/index.ts                 |   1 +
 .../machine/src/utilities/stateGraph.spec.ts  | 189 ++++++++++++++++++
 packages/machine/src/utilities/stateGraph.ts  | 148 ++++++++++++++
 4 files changed, 357 insertions(+), 1 deletion(-)
 create mode 100644 packages/machine/src/utilities/stateGraph.spec.ts

diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index aa07152..b6e38be 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -12,7 +12,12 @@ import {
 // import cycle with stateGraph.ts is resolved by ESM live bindings — see
 // the bottom-of-file note in that module. Aliased so the delegating
 // static methods can keep their canonical names without clashing.
-import {toGraph as toGraphImpl, fromGraph as fromGraphImpl} from '../utilities/stateGraph';
+import {
+  type StateMap,
+  collectStates as collectStatesImpl,
+  fromGraph as fromGraphImpl,
+  toGraph as toGraphImpl,
+} from '../utilities/stateGraph';
 
 export const ifOtherSymbol = Symbol('other symbol');
 
@@ -511,6 +516,19 @@ export default class State {
   } {
     return fromGraphImpl(graph);
   }
+
+  /**
+   * 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 {
+    return collectStatesImpl(initialState, tapeBlock);
+  }
 }
 
 export const haltState = new State(null);
diff --git a/packages/machine/src/index.ts b/packages/machine/src/index.ts
index 72298a3..79386c3 100644
--- a/packages/machine/src/index.ts
+++ b/packages/machine/src/index.ts
@@ -7,6 +7,7 @@ export { default as TapeBlock } from './classes/TapeBlock';
 export { default as TapeCommand, movements, symbolCommands } from './classes/TapeCommand';
 export { default as TuringMachine, type MachineState } from './classes/TuringMachine';
 export { type Graph, type GraphNode, type GraphTransition, type GraphCommand } from './utilities/graph';
+export { type StateMap, type StateMapEntry } from './utilities/stateGraph';
 export { toMermaid, fromMermaid } from './utilities/graphFormats';
 export { summarize, summarizeGraph, type GraphSummary } from './utilities/introspection';
 export {
diff --git a/packages/machine/src/utilities/stateGraph.spec.ts b/packages/machine/src/utilities/stateGraph.spec.ts
new file mode 100644
index 0000000..0432052
--- /dev/null
+++ b/packages/machine/src/utilities/stateGraph.spec.ts
@@ -0,0 +1,189 @@
+import Alphabet from '../classes/Alphabet';
+import Reference from '../classes/Reference';
+import State, {haltState, ifOtherSymbol} from '../classes/State';
+import TapeBlock from '../classes/TapeBlock';
+import {movements} from '../classes/TapeCommand';
+import {collectStates, toGraph} from './stateGraph';
+
+const alphabet = new Alphabet(' 01'.split(''));
+const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+const {symbol} = tapeBlock;
+
+describe('collectStates (#195)', () => {
+  test('alignment contract: every GraphTransition.id maps to transitionSymbols[K]', () => {
+    // For every transition emitted by toGraph, the (stateId, patternIx)
+    // pair extracted from its id should index back to the firing Symbol
+    // via stateMap.get(stateId).transitionSymbols[patternIx]. This is
+    // the load-bearing primitive the issue identifies — a single test
+    // pinning it across the whole machine catches any drift between
+    // toGraph's patternIx counter and collectStates' Map.keys() walk.
+    const sym0 = symbol(['0']);
+    const sym1 = symbol(['1']);
+    const branch = new State({
+      [sym0]: {nextState: haltState},
+      [sym1]: {command: [{symbol: '0', movement: movements.right}], nextState: haltState},
+    }, 'branch');
+
+    const graph = toGraph(branch, tapeBlock);
+    const stateMap = collectStates(branch, tapeBlock);
+
+    let assertions = 0;
+    for (const node of Object.values(graph.nodes)) {
+      for (const t of node.transitions) {
+        const [nStr, kStr] = t.id.split('-');
+        const n = Number(nStr);
+        const k = Number(kStr);
+        const entry = stateMap.get(n);
+        expect(entry).toBeDefined();
+        // Positional alignment by index, identity equality of the
+        // Symbol (not structural). Symbols are interned per-pattern by
+        // tapeBlock.symbol — re-creating the pattern returns the same
+        // Symbol, so we can compare against the recreated keys here.
+        expect(entry!.transitionSymbols[k]).toBeDefined();
+        assertions += 1;
+      }
+    }
+    // Sanity: the test would pass vacuously if no transitions existed.
+    expect(assertions).toBeGreaterThan(0);
+  });
+
+  test('transitionSymbols matches #symbolToDataMap insertion order', () => {
+    // Construction order: sym0 first, then sym1. collectStates surfaces
+    // the same order as transitionSymbols[0], [1]. The contract is by
+    // reference equality.
+    const sym0 = symbol(['0']);
+    const sym1 = symbol(['1']);
+    const s = new State({
+      [sym0]: {nextState: haltState},
+      [sym1]: {command: [{symbol: '0', movement: movements.right}], nextState: haltState},
+    }, 's');
+
+    const entry = collectStates(s, tapeBlock).get(s.id)!;
+
+    expect(entry.transitionSymbols[0]).toBe(sym0);
+    expect(entry.transitionSymbols[1]).toBe(sym1);
+  });
+
+  test('ifOtherSymbol is included at its natural slot', () => {
+    // A state that wrote ifOtherSymbol BETWEEN two literal-pattern
+    // entries — the catch-all sits at index 1 in #symbolToDataMap, so
+    // transitionSymbols[1] === ifOtherSymbol by reference.
+    const sym0 = symbol(['0']);
+    const sym1 = symbol(['1']);
+    const s = new State({
+      [sym0]: {nextState: haltState},
+      [ifOtherSymbol]: {nextState: haltState},
+      [sym1]: {command: [{symbol: '0', movement: movements.right}], nextState: haltState},
+    }, 's');
+
+    const entry = collectStates(s, tapeBlock).get(s.id)!;
+
+    expect(entry.transitionSymbols).toHaveLength(3);
+    expect(entry.transitionSymbols[0]).toBe(sym0);
+    expect(entry.transitionSymbols[1]).toBe(ifOtherSymbol);
+    expect(entry.transitionSymbols[2]).toBe(sym1);
+  });
+
+  test('wrapper entries have empty transitionSymbols and point at the wrapper instance', () => {
+    const bare = new State({
+      [symbol(['0'])]: {nextState: haltState},
+    }, 'bare');
+    const wrapper = bare.withOverriddenHaltState(haltState);
+
+    const stateMap = collectStates(wrapper, tapeBlock);
+    const wrapperEntry = stateMap.get(wrapper.id);
+
+    expect(wrapperEntry).toBeDefined();
+    expect(wrapperEntry!.state).toBe(wrapper);
+    expect(wrapperEntry!.transitionSymbols).toEqual([]);
+  });
+
+  test('halt singleton entry at id 0 points at haltState with empty transitionSymbols', () => {
+    const s = new State({
+      [symbol(['0'])]: {nextState: haltState},
+    }, 's');
+
+    const haltEntry = collectStates(s, tapeBlock).get(0)!;
+
+    expect(haltEntry.state).toBe(haltState);
+    expect(haltEntry.transitionSymbols).toEqual([]);
+  });
+
+  test('halt markers (negative ids) are excluded from the map', () => {
+    // A wrapper produces a callable-subtree frame, which gets a synthetic
+    // halt marker with id = -frameId. collectStates must skip it — the
+    // marker is visualization-only.
+    const bare = new State({
+      [symbol(['0'])]: {nextState: haltState},
+    }, 'bare');
+    const wrapper = bare.withOverriddenHaltState(haltState);
+
+    const graph = toGraph(wrapper, tapeBlock);
+    const stateMap = collectStates(wrapper, tapeBlock);
+
+    const haltMarkerIds = Object.keys(graph.nodes)
+      .map(Number)
+      .filter((id) => graph.nodes[id].isHaltMarker);
+
+    // Sanity: the test would be vacuous if the graph had no halt marker.
+    expect(haltMarkerIds.length).toBeGreaterThan(0);
+
+    for (const id of haltMarkerIds) {
+      expect(stateMap.has(id)).toBe(false);
+    }
+
+    // Map coverage: every non-halt-marker GraphNode has a stateMap entry.
+    const expectedIds = Object.keys(graph.nodes)
+      .map(Number)
+      .filter((id) => !graph.nodes[id].isHaltMarker);
+    expect(stateMap.size).toBe(expectedIds.length);
+  });
+
+  test('unbound Reference: transitionSymbols[K] is defined but no GraphTransition matches', () => {
+    // Construct a state whose first pattern points at an unbound
+    // Reference. toGraph's BFS catches the unbound-ref error and
+    // `continue`s — patternIx still advances, so the slot exists in
+    // #symbolToDataMap.keys() but no GraphTransition is emitted for it.
+    const danglingRef = new Reference();
+    const sym0 = symbol(['0']);
+    const sym1 = symbol(['1']);
+    const s = new State({
+      [sym0]: {nextState: danglingRef}, // unbound — no GraphTransition emitted
+      [sym1]: {command: [{symbol: '0', movement: movements.right}], nextState: haltState},
+    }, 's');
+
+    const graph = toGraph(s, tapeBlock);
+    const stateMap = collectStates(s, tapeBlock);
+    const entry = stateMap.get(s.id)!;
+
+    // Both Map keys present in transitionSymbols, in insertion order.
+    expect(entry.transitionSymbols).toHaveLength(2);
+    expect(entry.transitionSymbols[0]).toBe(sym0);
+    expect(entry.transitionSymbols[1]).toBe(sym1);
+
+    // No GraphTransition with id `${s.id}-0` (the unbound-ref slot);
+    // the one for slot 1 (the bound transition) DOES exist.
+    const node = graph.nodes[s.id];
+    const ids = node.transitions.map((t) => t.id);
+    expect(ids).not.toContain(`${s.id}-0`);
+    expect(ids).toContain(`${s.id}-1`);
+  });
+});
+
+describe('State.collectStates (#195) — static delegate', () => {
+  test('returns the same shape as the module function', () => {
+    const s = new State({
+      [symbol(['0'])]: {nextState: haltState},
+    }, 's');
+
+    const fromStatic = State.collectStates(s, tapeBlock);
+    const fromModule = collectStates(s, tapeBlock);
+
+    expect(fromStatic.size).toBe(fromModule.size);
+    for (const [id, entry] of fromModule) {
+      const staticEntry = fromStatic.get(id)!;
+      expect(staticEntry.state).toBe(entry.state);
+      expect(staticEntry.transitionSymbols).toEqual(entry.transitionSymbols);
+    }
+  });
+});
diff --git a/packages/machine/src/utilities/stateGraph.ts b/packages/machine/src/utilities/stateGraph.ts
index e55cf05..7187161 100644
--- a/packages/machine/src/utilities/stateGraph.ts
+++ b/packages/machine/src/utilities/stateGraph.ts
@@ -492,6 +492,154 @@ export function fromGraph(graph: Graph): {
   };
 }
 
+/**
+ * One entry in the `StateMap` returned by `collectStates` (#195).
+ *
+ * - `state`: the live `State` instance for this Graph node. For the halt
+ *   singleton at id `0`, this is the engine-wide `haltState` — toggling
+ *   `state.debug` on that entry affects every machine in the process.
+ * - `transitionSymbols`: per-pattern Symbols in `#symbolToDataMap` insertion
+ *   order, aligned positionally with `GraphTransition.id` patternIx. For
+ *   wrappers and the halt singleton this is `[]` (no own transitions).
+ */
+export type StateMapEntry = {
+  state: State;
+  transitionSymbols: symbol[];
+};
+
+/**
+ * Numeric `GraphNode.id` → `StateMapEntry`. Returned by `collectStates`
+ * (#195). Halt markers (synthetic nodes with `id = -frameId`) are NOT
+ * included — they're visualization-only and all collapse to the
+ * `haltState` singleton already exposed at id `0`.
+ */
+export type StateMap = Map<number, StateMapEntry>;
+
+/**
+ * Returns a `Map<number, {state, transitionSymbols}>` keyed by engine
+ * `GraphNode.id`, giving downstream tooling direct access to the `State`
+ * instance + per-pattern Symbol references for breakpoint setup (#195).
+ *
+ * **Positional alignment contract.** For any `GraphTransition` whose id
+ * is `${N}-${K}`, `result.get(N)!.transitionSymbols[K]` is the Symbol
+ * the transition fires on (reference equality, not structural). The K-th
+ * entry is the K-th key from the source State's `#symbolToDataMap` in
+ * insertion order, including `ifOtherSymbol` when the user wrote one.
+ * Consumers filtering the catch-all path identity-compare against the
+ * engine-exported `ifOtherSymbol`.
+ *
+ * **Unbound-`Reference` slots.** `toGraph` increments `patternIx` even
+ * when a transition's `nextState` is an unresolved `Reference` (it
+ * `continue`s without pushing the GraphTransition). In that case
+ * `transitionSymbols[K]` is still set to the K-th Map key, but no
+ * `Graph.nodes[N].transitions` entry exists with id `${N}-${K}`. Sparse
+ * on the Graph side, dense on the `transitionSymbols` side — same
+ * indexing.
+ *
+ * **Coverage.** Map keys are the State-backed subset of `graph.nodes`:
+ * regulars + bares + wrappers + the halt singleton (id `0`). Synthetic
+ * halt markers (id `-frameId`) are excluded — they all reach the same
+ * `haltState` object at runtime, and the named consumer
+ * ([machines-demo#37](https://github.com/mellonis/machines-demo/issues/37))
+ * surfaces halt-pause via a separate UI control, not via clicks on
+ * halt glyphs. If a future consumer needs uniform-by-id lookup, the
+ * helper can be extended additively.
+ *
+ * **Halt-singleton warning.** `result.get(0)!.state === haltState` — the
+ * process-wide halt. Toggling `.debug` on that entry affects every
+ * machine in the runtime, not just the one this map was built from.
+ */
+export function collectStates(initialState: State, tapeBlock: TapeBlock): StateMap {
+  // Anchor on toGraph's authoritative id set — it knows the canonical
+  // ordering of wrapper/bare/regular emission and which nodes are
+  // synthetic halt markers we have to skip. Building our own BFS would
+  // duplicate that logic; reusing the Graph guarantees collectStates'
+  // id keys never drift from toGraph's GraphTransition ids.
+  const graph = toGraph(initialState, tapeBlock);
+
+  // Walk the State graph to associate each State instance with its
+  // engine id. The shape mirrors toGraph's Pass 1 — visit by id, branch
+  // on halt / wrapper / regular — but only collects the (id → State)
+  // mapping. Lighter than re-running the union-find passes; no
+  // GraphNode construction.
+  const stateById = new Map<number, State>();
+  const visited = new Set<number>();
+  const queue: State[] = [initialState];
+
+  while (queue.length > 0) {
+    const state = queue.shift()!;
+    const internal = state[STATE_INTERNAL]();
+
+    if (visited.has(internal.id)) continue;
+    visited.add(internal.id);
+
+    stateById.set(internal.id, state);
+
+    if (state.isHalt) continue;
+
+    if (internal.bareState !== null && internal.overriddenHaltState !== null) {
+      queue.push(internal.bareState);
+      queue.push(internal.overriddenHaltState);
+      continue;
+    }
+
+    for (const {nextState} of internal.symbolToDataMap.values()) {
+      let target: State;
+
+      try {
+        target = nextState instanceof State ? nextState : nextState.ref;
+      } catch {
+        continue; // unbound Reference — skip silently, matches toGraph
+      }
+
+      queue.push(target);
+    }
+  }
+
+  // Build the result by iterating graph.nodes — the authoritative id set
+  // minus halt markers — and dispatching on node kind. The halt singleton
+  // entry's `state` reads from `stateById` (the BFS visited haltState if
+  // any path reached it) but falls back to the module-level singleton
+  // for graphs whose only halt presence is the always-emitted sentinel.
+  const result: StateMap = new Map();
+
+  for (const idStr of Object.keys(graph.nodes)) {
+    const id = Number(idStr);
+    const node = graph.nodes[id];
+
+    if (node.isHaltMarker) continue; // synthetic; collapses to haltState at id 0
+
+    if (node.isHalt) {
+      // The real halt — always the engine-wide singleton. Prefer the
+      // BFS-visited instance for identity-equality with whatever the
+      // caller has; fall back to the module singleton when the BFS
+      // didn't reach haltState (toGraph emits id 0 unconditionally).
+      result.set(id, {
+        state: stateById.get(0) ?? haltState,
+        transitionSymbols: [],
+      });
+      continue;
+    }
+
+    if (node.isWrapper) {
+      result.set(id, {
+        state: stateById.get(id)!,
+        transitionSymbols: [],
+      });
+      continue;
+    }
+
+    // Regular or bare State — enumerate `#symbolToDataMap.keys()` for
+    // the patternIx alignment. The K-th key is the Symbol that
+    // `${id}-${K}` GraphTransition fires on (positional contract).
+    const state = stateById.get(id)!;
+    const transitionSymbols = [...state[STATE_INTERNAL]().symbolToDataMap.keys()];
+    result.set(id, {state, transitionSymbols});
+  }
+
+  return result;
+}
+
 // Note on the import cycle with `State.ts`: stateGraph.ts value-imports
 // `State`, `STATE_INTERNAL`, `haltState`, and `ifOtherSymbol`; State.ts
 // value-imports `toGraph` and `fromGraph` for its static-method delegates.

From c1d85ec584dfb2a9e013db330ad50775bb9c68b6 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 12:05:39 +0300
Subject: [PATCH 037/118] docs+test: README section for collectStates +
 halt-fallback coverage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: add `State.collectStates` to the static-API list (next to
  toGraph/fromGraph) and a "Setting breakpoints by graph id" subsection
  inside Debugging breakpoints showing the by-id and by-transition-id
  patterns + the halt-singleton warning.
- One more spec: halt singleton falls back to the module-level
  `haltState` when the BFS never reaches it (initial state with a
  self-loop and no halt-bound transitions). Closes the last branch in
  collectStates that the existing tests left uncovered — `stateById`
  hits id 0 only when some transition actually targets haltState; the
  `?? haltState` fallback fires for graphs whose only halt presence
  is toGraph's unconditional sentinel.

Coverage on stateGraph.ts: 94.31% → 95.45% branches.
---
 packages/machine/README.md                    | 31 +++++++++++++++++++
 .../machine/src/utilities/stateGraph.spec.ts  | 17 ++++++++++
 2 files changed, 48 insertions(+)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index 46b4f11..c526a42 100644
--- a/packages/machine/README.md
+++ b/packages/machine/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):
 
@@ -499,6 +500,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:
diff --git a/packages/machine/src/utilities/stateGraph.spec.ts b/packages/machine/src/utilities/stateGraph.spec.ts
index 0432052..0472dd0 100644
--- a/packages/machine/src/utilities/stateGraph.spec.ts
+++ b/packages/machine/src/utilities/stateGraph.spec.ts
@@ -109,6 +109,23 @@ describe('collectStates (#195)', () => {
     expect(haltEntry.transitionSymbols).toEqual([]);
   });
 
+  test('halt singleton falls back to the module singleton when BFS never reaches haltState', () => {
+    // No transition targets haltState — the BFS visits only `looping`,
+    // so `stateById` has no entry at id 0. `toGraph` still emits the
+    // halt sentinel unconditionally (it anchors `subtree -. halt .-> s0`
+    // edges), so id 0 IS in `graph.nodes`. collectStates must fall back
+    // to the module-level `haltState` for the entry's `.state` field —
+    // pinning that fallback path here.
+    const looping = new State({
+      [symbol(['0'])]: {}, // nextState defaults to self → self-loop, no halt reached
+    }, 'loop');
+
+    const entry = collectStates(looping, tapeBlock).get(0)!;
+
+    expect(entry.state).toBe(haltState);
+    expect(entry.transitionSymbols).toEqual([]);
+  });
+
   test('halt markers (negative ids) are excluded from the map', () => {
     // A wrapper produces a callable-subtree frame, which gets a synthetic
     // halt marker with id = -frameId. collectStates must skip it — the

From 202c3418e4dab83586c0cbb0a31d52783c74b643 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 12:09:20 +0300
Subject: [PATCH 038/118] =?UTF-8?q?docs:=20CLAUDE.md=20=E2=80=94=20collect?=
 =?UTF-8?q?States=20+=20STATE=5FINTERNAL=20accessor=20pattern?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds two paragraphs to the engine CLAUDE.md's "Visualization & round-trip"
section:

- `State.collectStates` API and its alignment contract (the load-bearing
  positional pairing with GraphTransition.id patternIx).
- `STATE_INTERNAL` Symbol accessor pattern — what it exposes, who can
  use it (sibling modules under `packages/machine/src` only, not
  re-exported from `index.ts`), and the single-site `name` setter
  rationale for `fromGraph`'s composite-name assignment.

Mentions that toGraph/fromGraph/collectStates all live in
`utilities/stateGraph.ts` post-#180 and that the static methods on
`State` are thin delegates.
---
 CLAUDE.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 0d24004..a338203 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,6 +61,10 @@ Key shapes that take reading multiple files to grasp:
 
 `packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same `Graph` through [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) syntax (renderer: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)). The parser is strict to the dialect `toMermaid` emits — hand-edited Mermaid with different arrow styles or shapes won't round-trip.
 
+**`State.collectStates(state, tapeBlock)`** (v7, #195) — returns a `Map<number, {state, transitionSymbols}>` keyed by engine `GraphNode.id`. For each id: the live `State` instance and the per-pattern `Symbol[]` from `#symbolToDataMap` in insertion order. The K-th `transitionSymbols` slot is positionally aligned with the GraphTransition whose id is `${stateId}-${K}`, so consumers holding `(stateId, patternIx)` from a rendered graph reach the firing Symbol with no walk. `ifOtherSymbol` is included 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. Halt-singleton entry at id `0` is the process-wide singleton — JSDoc warns toggling its `debug` affects every machine in the runtime.
+
+**`STATE_INTERNAL` Symbol accessor** (v7, #180) — `state[STATE_INTERNAL]()` returns a getter/setter view onto `State`'s private fields (`id`, `name`, `bareState`, `overriddenHaltState`, `symbolToDataMap`, `tags`). `@internal`-marked. Exported from `classes/State.ts` for sibling-module use in `packages/machine/src` (currently `utilities/stateGraph.ts`); NOT re-exported from the package's public `index.ts`. The `name` setter is the one mutation site, used by `fromGraph` to assign graph-sourced composite names (e.g. `A(target)`) that the constructor's paren-validator would reject. New utility modules in `packages/machine/src` that need private-field access route through this accessor rather than growing per-module bypasses. `toGraph`/`fromGraph`/`collectStates` all live in `utilities/stateGraph.ts` (extracted from `classes/State.ts` in #180); `State.toGraph` / `.fromGraph` / `.collectStates` statics remain as thin delegates for backwards compat.
+
 **State tags (v7 alpha.3, #186)** — `state.tag(...tags) / state.untag(...tags) / state.tags` API for attaching string metadata to a State. Tags are out-of-band — they don't affect transition lookup, `equivalentOn`, or runtime semantics. Live on the State *instance* (not on `#symbolToDataMap`), so engine #175 memoization doesn't leak tags across wrappers sharing a bare: `A.wohs(t1).tag('hot')` and `A.wohs(t2)` carry independent tag sets. `GraphNode` gains `tags: string[]` field — survives `toGraph`/`fromGraph` round-trip. `toMermaid` emits tags two ways: inline in node label via universal `<br>` (`sN["name<br>tag1, tag2"]`) AND as `classDef tag_<sanitized>` + `class sN tag_<sanitized>` lines (6-color hash-based palette). `fromMermaid` splits the label on `<br>` as source of truth; `class` lines are decorative.
 
 **v7 callable-subtree emit shape** (#174, layered on the v7 alpha.1 framing from #138/#139): each `withOverriddenHaltState` wrapper produces TWO `GraphNode`s — a wrapper node (`isWrapper: true`, `[[composite-name]]` shape, no transitions, `bareStateId` points to the bare's GraphNode) and a bare node (regular `["name"]` shape inside its callable subtree subgraph, holds the bare's transitions). Frames are computed via union-find on bare-reachability: each unique bare's forward-reachable set defines its candidate frame; overlapping reach sets merge into a union frame. Frame id = smallest bare-id in the component. Halt marker per frame (id = `-frameId`, `isHaltMarker: true`, maps back to singleton `haltState` in `fromGraph`). Halt-bound transitions of in-frame states retarget to the frame's halt marker. Subgraph label: `"callable subtree of NAME"` (single bare) or `"callable scope: A ∪ B"` (union). The always-emitted `idle([idle])` stadium sentinel + `idle -. enter .-> sN` arrow marks the initial state. **No per-context duplication** — shared bares like `library-binary-numbers`'s `invertNumber` (in `minusOne`) appear once with `& `-joined call arrows from each wrapper.

From 7d726c1cc9a54df82b3af13fb9a46ccc7574e508 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 12:29:34 +0300
Subject: [PATCH 039/118] chore: backfill v7-alpha CHANGELOG entries for side
 packages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`@turing-machine-js/builder`, `@turing-machine-js/library-binary-numbers`,
and `@turing-machine-js/library-binary-numbers-bare` shipped at every v7
alpha in version-lockstep with `@turing-machine-js/machine`, but their
CHANGELOGs were never updated past 6.4.0 — three alpha tarballs went out
without a CHANGELOG entry each.

CHANGELOG entries don't land retroactively on already-published npm
versions; this fills the gap so the NEXT published tarball (alpha.4)
will carry the prior alpha history alongside its own entry. Without
this, alpha.4's CHANGELOG would jump from 6.4.0 directly to 7.0.0-alpha.4
on consumers' offline view (`npm view`, IDE extensions, etc.).

Entries are the standard lockstep boilerplate — no source or behavior
change in these packages, plus the per-alpha peer-dep widening that did
occur (verified against the alpha.1/alpha.2/alpha.3 release commits):

- alpha.1: peer dep `^6.0.0` → `^7.0.0-alpha.1`
- alpha.2: peer dep `^7.0.0-alpha.1` → `^7.0.0-alpha.2`
- alpha.3: peer dep `^7.0.0-alpha.2` → `^7.0.0-alpha.3`

The engine's own CHANGELOG already covered these alphas; only the three
dependent packages were behind.
---
 packages/builder/CHANGELOG.md                     | 12 ++++++++++++
 packages/library-binary-numbers-bare/CHANGELOG.md | 12 ++++++++++++
 packages/library-binary-numbers/CHANGELOG.md      | 12 ++++++++++++
 3 files changed, 36 insertions(+)

diff --git a/packages/builder/CHANGELOG.md b/packages/builder/CHANGELOG.md
index 3ef8afc..5230e38 100644
--- a/packages/builder/CHANGELOG.md
+++ b/packages/builder/CHANGELOG.md
@@ -4,6 +4,18 @@ 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.3] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.3 — first-class out-of-band State tags ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3`.
+
+## [7.0.0-alpha.2] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.2 — `toMermaid` callable-subtree emit refinement ([#174](https://github.com/mellonis/turing-machine-js/issues/174)), `withOverriddenHaltState` memoization ([#175](https://github.com/mellonis/turing-machine-js/issues/175)), nested `.wohs()` chain collapse ([#176](https://github.com/mellonis/turing-machine-js/issues/176)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.1` → `^7.0.0-alpha.2`.
+
+## [7.0.0-alpha.1] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.1 — composition-representation overhaul: `withOverrodeHaltState` → `withOverriddenHaltState` ([#149](https://github.com/mellonis/turing-machine-js/issues/149)), paren-based wrapped-state naming `A(B)` ([#148](https://github.com/mellonis/turing-machine-js/issues/148)), `toMermaid` callable-subtree emit alpha.1 collapsed-bare shape ([#138](https://github.com/mellonis/turing-machine-js/issues/138), [#139](https://github.com/mellonis/turing-machine-js/issues/139)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^6.0.0` → `^7.0.0-alpha.1`.
+
 ## [6.4.0] - 2026-05-19
 
 Released in lockstep with `@turing-machine-js/machine` 6.4.0. No source or behavior changes in this package.
diff --git a/packages/library-binary-numbers-bare/CHANGELOG.md b/packages/library-binary-numbers-bare/CHANGELOG.md
index 28c4dc6..cebb6a8 100644
--- a/packages/library-binary-numbers-bare/CHANGELOG.md
+++ b/packages/library-binary-numbers-bare/CHANGELOG.md
@@ -4,6 +4,18 @@ 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.3] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.3 — first-class out-of-band State tags ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3`.
+
+## [7.0.0-alpha.2] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.2 — `toMermaid` callable-subtree emit refinement ([#174](https://github.com/mellonis/turing-machine-js/issues/174)), `withOverriddenHaltState` memoization ([#175](https://github.com/mellonis/turing-machine-js/issues/175)), nested `.wohs()` chain collapse ([#176](https://github.com/mellonis/turing-machine-js/issues/176)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.1` → `^7.0.0-alpha.2`.
+
+## [7.0.0-alpha.1] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.1 — composition-representation overhaul: `withOverrodeHaltState` → `withOverriddenHaltState` ([#149](https://github.com/mellonis/turing-machine-js/issues/149)), paren-based wrapped-state naming `A(B)` ([#148](https://github.com/mellonis/turing-machine-js/issues/148)), `toMermaid` callable-subtree emit alpha.1 collapsed-bare shape ([#138](https://github.com/mellonis/turing-machine-js/issues/138), [#139](https://github.com/mellonis/turing-machine-js/issues/139)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^6.0.0` → `^7.0.0-alpha.1`.
+
 ## [6.4.0] - 2026-05-19
 
 Released in lockstep with `@turing-machine-js/machine` 6.4.0. No source or behavior changes in this package.
diff --git a/packages/library-binary-numbers/CHANGELOG.md b/packages/library-binary-numbers/CHANGELOG.md
index 1310a02..1efaaf5 100644
--- a/packages/library-binary-numbers/CHANGELOG.md
+++ b/packages/library-binary-numbers/CHANGELOG.md
@@ -4,6 +4,18 @@ 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.3] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.3 — first-class out-of-band State tags ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3`.
+
+## [7.0.0-alpha.2] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.2 — `toMermaid` callable-subtree emit refinement ([#174](https://github.com/mellonis/turing-machine-js/issues/174)), `withOverriddenHaltState` memoization ([#175](https://github.com/mellonis/turing-machine-js/issues/175)), nested `.wohs()` chain collapse ([#176](https://github.com/mellonis/turing-machine-js/issues/176)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.1` → `^7.0.0-alpha.2`.
+
+## [7.0.0-alpha.1] - 2026-05-21
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.1 — composition-representation overhaul: `withOverrodeHaltState` → `withOverriddenHaltState` ([#149](https://github.com/mellonis/turing-machine-js/issues/149)), paren-based wrapped-state naming `A(B)` ([#148](https://github.com/mellonis/turing-machine-js/issues/148)), `toMermaid` callable-subtree emit alpha.1 collapsed-bare shape ([#138](https://github.com/mellonis/turing-machine-js/issues/138), [#139](https://github.com/mellonis/turing-machine-js/issues/139)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^6.0.0` → `^7.0.0-alpha.1`.
+
 ## [6.4.0] - 2026-05-19
 
 Released in lockstep with `@turing-machine-js/machine` 6.4.0. No source or behavior changes in this package.

From 910f09b39cb674b5917baacfccf07261824a7b6e Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 12:40:15 +0300
Subject: [PATCH 040/118] chore(release): 7.0.0-alpha.4
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fourth v7 pre-release. Lockstep version bump across all four packages
from 7.0.0-alpha.3 → 7.0.0-alpha.4. Peer dep `@turing-machine-js/machine`
widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4` on the three side packages.

Shipping:
- Added: State.collectStates(initial, tapeBlock) returning
  Map<number, {state, transitionSymbols}> keyed by GraphNode.id, for
  id-based debugger lookup (#195, PR #200).
- Changed: State.toGraph / State.fromGraph extracted to
  utilities/stateGraph.ts with a Symbol-keyed STATE_INTERNAL accessor on
  State; public surface preserved via thin static delegates (#180,
  PR #199).
- Fixed: toMermaid HTML-entity-escapes user content in labels — fixes
  edge-label parse error when alphabets contain `"`, `<`, etc.
  (#194, PR #198).
- Fixed: runStepByStep halt stack scoped to the call rather than the
  TuringMachine instance — fixes memory leak / ghost-iteration on
  consecutive runStepByStep calls (#196, PR #197).

CHANGELOG entry added to each of the four packages. README
versioning-notes section updated to reflect alpha.4 + new highlights
paragraph. Pre-release stays on the `next` dist-tag at publish time.
---
 lerna.json                                    |  2 +-
 package-lock.json                             | 14 +++---
 packages/builder/CHANGELOG.md                 |  4 ++
 packages/builder/package.json                 |  4 +-
 .../library-binary-numbers-bare/CHANGELOG.md  |  4 ++
 .../library-binary-numbers-bare/package.json  |  4 +-
 packages/library-binary-numbers/CHANGELOG.md  |  4 ++
 packages/library-binary-numbers/package.json  |  4 +-
 packages/machine/CHANGELOG.md                 | 50 +++++++++++++++++++
 packages/machine/README.md                    |  4 +-
 packages/machine/package.json                 |  2 +-
 11 files changed, 80 insertions(+), 16 deletions(-)

diff --git a/lerna.json b/lerna.json
index 0455ff2..32f00eb 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.3",
+  "version": "7.0.0-alpha.4",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index d50c9ae..44832f2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10656,40 +10656,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.3",
+      "version": "7.0.0-alpha.4",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.2"
+        "@turing-machine-js/machine": "^7.0.0-alpha.3"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.3",
+      "version": "7.0.0-alpha.4",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.2"
+        "@turing-machine-js/machine": "^7.0.0-alpha.3"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.3",
+      "version": "7.0.0-alpha.4",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.2"
+        "@turing-machine-js/machine": "^7.0.0-alpha.3"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.3",
+      "version": "7.0.0-alpha.4",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/builder/CHANGELOG.md b/packages/builder/CHANGELOG.md
index 5230e38..e0b4d57 100644
--- a/packages/builder/CHANGELOG.md
+++ b/packages/builder/CHANGELOG.md
@@ -4,6 +4,10 @@ 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.4] - 2026-05-23
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.4 — adds `State.collectStates` ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), extracts graph serialization into `utilities/stateGraph.ts` ([#180](https://github.com/mellonis/turing-machine-js/issues/180)), fixes `toMermaid` label escape ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and `runStepByStep` halt-stack scope ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4`.
+
 ## [7.0.0-alpha.3] - 2026-05-21
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.3 — first-class out-of-band State tags ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3`.
diff --git a/packages/builder/package.json b/packages/builder/package.json
index b23e98d..043928b 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.3",
+  "version": "7.0.0-alpha.4",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.3"
+    "@turing-machine-js/machine": "^7.0.0-alpha.4"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/CHANGELOG.md b/packages/library-binary-numbers-bare/CHANGELOG.md
index cebb6a8..c7ff61e 100644
--- a/packages/library-binary-numbers-bare/CHANGELOG.md
+++ b/packages/library-binary-numbers-bare/CHANGELOG.md
@@ -4,6 +4,10 @@ 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.4] - 2026-05-23
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.4 — adds `State.collectStates` ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), extracts graph serialization into `utilities/stateGraph.ts` ([#180](https://github.com/mellonis/turing-machine-js/issues/180)), fixes `toMermaid` label escape ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and `runStepByStep` halt-stack scope ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4`.
+
 ## [7.0.0-alpha.3] - 2026-05-21
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.3 — first-class out-of-band State tags ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3`.
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index 3af83ee..9bb71a5 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.3",
+  "version": "7.0.0-alpha.4",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.3"
+    "@turing-machine-js/machine": "^7.0.0-alpha.4"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/CHANGELOG.md b/packages/library-binary-numbers/CHANGELOG.md
index 1efaaf5..1855a54 100644
--- a/packages/library-binary-numbers/CHANGELOG.md
+++ b/packages/library-binary-numbers/CHANGELOG.md
@@ -4,6 +4,10 @@ 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.4] - 2026-05-23
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.4 — adds `State.collectStates` ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), extracts graph serialization into `utilities/stateGraph.ts` ([#180](https://github.com/mellonis/turing-machine-js/issues/180)), fixes `toMermaid` label escape ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and `runStepByStep` halt-stack scope ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4`.
+
 ## [7.0.0-alpha.3] - 2026-05-21
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.3 — first-class out-of-band State tags ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3`.
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index 9a665a1..4e0c508 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.3",
+  "version": "7.0.0-alpha.4",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.3"
+    "@turing-machine-js/machine": "^7.0.0-alpha.4"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index 1e2f70d..3803c70 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,56 @@ 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.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`.
diff --git a/packages/machine/README.md b/packages/machine/README.md
index c526a42..580e3d8 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -714,7 +714,9 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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).
 
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 12154ff..505d29f 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.3",
+  "version": "7.0.0-alpha.4",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"

From 6fac7ad6274f94f084330977c8484bbb6545ddd3 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 23 May 2026 13:23:11 +0300
Subject: [PATCH 041/118] test: raise v7 coverage to cover graphFormats +
 stateGraph gaps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Recovers the 0.5% Coveralls drop flagged on PR #167 (v7 → master
integration). Master sits at 98.291%; before this PR v7 was at
97.805%. After: stmts 99.33% / branches 96.49% / funcs 100% /
lines 99.47% — comfortably above master and above the 97/90/95/97
floors.

Three changes:

1. `\r` escape test (graphFormats.spec via graph.spec.ts). Pins the
   carriage-return case in `escapeMermaidLabel` — the existing `\n`
   test only covered one of the two statement-terminator cases.

2. Hex numeric entity decode test (graph.spec.ts). `toMermaid` only
   emits decimal entities, but `fromMermaid` accepts hex (`&#xHH;`)
   for hand-edited `.mmd` files. Defensive path now exercised by a
   constructed-Mermaid-input test.

3. `c8 ignore` annotations on two genuinely unreachable branches:
   - `graphFormats.ts` line 118: the `return match;` fallback in
     `unescapeMermaidLabel`'s switch — the regex shape guarantees
     one of `named` / `dec` / `hex` is always set, so the default
     branch is dead.
   - `stateGraph.ts` line 191: the `if (node.isHalt || node.isWrapper)
     continue;` check in `computeReach` — the push site below already
     filters halt/wrapper targets, and the initial push is always a
     bare, so this branch can't fire in practice. (Same branch existed
     uncovered on master pre-#180, where the code lived in State.ts.)

Net result on the Coveralls delta: +0.49% statements, +0.77% branches,
+0.52% lines vs the pre-fix v7 state. Brings v7 above master's
98.291%, clearing the failing `coverage/coveralls` status on PR #167.
---
 packages/machine/src/utilities/graph.spec.ts  | 40 +++++++++++++++++++
 .../machine/src/utilities/graphFormats.ts     |  2 +
 packages/machine/src/utilities/stateGraph.ts  |  3 ++
 3 files changed, 45 insertions(+)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index a204ee3..a3aeee7 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -1203,6 +1203,46 @@ describe('Mermaid label escaping (#194)', () => {
     expect((subgraphLine!.match(/"/g) ?? []).length).toBe(2);
   });
 
+  test('carriage return in alphabet symbol encodes as &#13;', () => {
+    // Sibling of the `\n` test above — pins the second statement-terminator
+    // branch in escapeMermaidLabel so coverage doesn't drift if someone
+    // adds another escape category and forgets the `\r` case.
+    const alphabet = new Alphabet([' ', 'a', '\r']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const s = new State({
+      [tapeBlock.symbol(['a'])]: {
+        command: [{symbol: '\r', movement: movements.right}],
+        nextState: haltState,
+      },
+    }, 's');
+
+    const mermaid = toMermaid(State.toGraph(s, tapeBlock));
+    expect(mermaid).toContain('&#13;');
+
+    const reparsed = fromMermaid(mermaid);
+    expect(reparsed.nodes[s.id].transitions[0].command[0].symbol).toBe("'\r'");
+  });
+
+  test('hex numeric entity `&#xHH;` decodes (hand-edited Mermaid support)', () => {
+    // `toMermaid` only emits decimal numeric entities (`&#NN;`), but
+    // `fromMermaid` accepts hex too for hand-edited `.mmd` files where a
+    // user might write `&#x22;` instead of `&quot;`. Pin the hex-decode
+    // branch in unescapeMermaidLabel by constructing a minimal Mermaid
+    // graph that uses a hex entity in a node name.
+    const mermaid = [
+      'flowchart TD',
+      '%% alphabets: [[" ","0"]]',
+      '  s0(((halt)))',
+      '  s1["a&#x22;b"]',
+      '  idle([idle])',
+      '  idle -. enter .-> s1',
+      '  s1 -- "[\'0\'] → [K]/[S]" --> s0',
+    ].join('\n');
+
+    const graph = fromMermaid(mermaid);
+    expect(graph.nodes[1].name).toBe('a"b');
+  });
+
   test('ambiguous `&amp;quot;` decodes once, not twice', () => {
     // User content that looks like a doubly-encoded entity. Single-pass
     // decode should give back the literal `&quot;` text, not `"`.
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index 5f0fa35..d2231e4 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -115,6 +115,8 @@ function unescapeMermaidLabel(s: string): string {
           const n = Number.parseInt(hex, 16);
           return n <= 0xFFFF ? String.fromCharCode(n) : String.fromCodePoint(n);
         }
+        /* c8 ignore next 2 — defensive: the regex shape guarantees one of
+           named / dec / hex is always set, so this fallback is unreachable. */
         return match;
       }
     }
diff --git a/packages/machine/src/utilities/stateGraph.ts b/packages/machine/src/utilities/stateGraph.ts
index 7187161..86569a0 100644
--- a/packages/machine/src/utilities/stateGraph.ts
+++ b/packages/machine/src/utilities/stateGraph.ts
@@ -187,6 +187,9 @@ export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
       // `nodes[id]` is always populated for `id` that the BFS reached, so
       // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
       // are real boundaries — both stop reach-set expansion.
+      /* c8 ignore next 3 — defensive: the push site below already filters
+         halt/wrapper targets, and the initial push is always a bare, so
+         this branch is unreachable in practice. */
       if (node.isHalt || node.isWrapper) {
         continue;
       }

From dbe9b143d54d48ac868759e31554bacb36ad4d21 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sun, 24 May 2026 22:10:06 +0300
Subject: [PATCH 042/118] feat: MachineState.matchedTransition + .-separated
 transition ids (#205)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The engine already resolves which transition fired (state.getNextState
walks #symbolToDataMap), then discards that info. Expose it on every
yielded MachineState so visualizations, log formatters, and coverage
maps don't re-derive an ambiguous (source, nextState) and don't parse
the pattern strings emitted by toGraph.

  matchedTransition: { id: string; matchKinds: ('wildcard' | 'literal')[] }

- id is resolvable in toGraph: graph.nodes[…].transitions has a matching
  id.
- For wrapper-entry iters (source produced by withOverriddenHaltState),
  id references the BARE's transition — the wrapper's own transitions
  array is empty post-#138 and the pattern lives on the bare.
- matchKinds is per-tape, length = tape count, 'wildcard' iff the
  winning alternative had ifOtherSymbol at that position.

Breaking: toGraph transition id format changed \`\${stateId}-\${ix}\` →
\`\${stateId}.\${ix}\` so matchedTransition.id and GraphTransition.id
share one shape. The `.` separator also avoids the hyphen reading as a
minus sign next to negative halt-marker ids in adjacent contexts.

New accessors carrying the data:
- State.getMatchedTransition(symbol) — same lookup as getNextState,
  also returns matchedSymbol and ix.
- TapeBlock.patternKinds(symbol, currentSymbols?) — winning-alternative
  per-tape kind for a given Symbol.
---
 packages/machine/src/classes/State.ts         |  41 ++++
 packages/machine/src/classes/TapeBlock.ts     |  56 +++++
 .../TuringMachine.matchedTransition.spec.ts   | 197 ++++++++++++++++++
 .../machine/src/classes/TuringMachine.spec.ts |  19 ++
 packages/machine/src/classes/TuringMachine.ts |  43 +++-
 .../machine/src/utilities/stateGraph.spec.ts  |   9 +-
 packages/machine/src/utilities/stateGraph.ts  |  16 +-
 7 files changed, 371 insertions(+), 10 deletions(-)
 create mode 100644 packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts

diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index b6e38be..45a35fc 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -351,6 +351,47 @@ export default class State {
     throw new Error(`No nextState for symbol at state named ${this.#id}`);
   }
 
+  /**
+   * 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`) 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,
+  } {
+    const entry = this.#symbolToDataMap.get(symbol);
+
+    if (entry === undefined) {
+      throw new Error(`No nextState for symbol at state named ${this.#id}`);
+    }
+
+    // Iteration order on a Map is insertion order; index lookup is O(N),
+    // acceptable since this fires at most once per iter and N (transitions
+    // per state) is typically tiny. If hot-path measurement ever flags it,
+    // cache as `#symbolToIxMap` mirror.
+    let ix = 0;
+
+    for (const key of this.#symbolToDataMap.keys()) {
+      if (key === symbol) break;
+      ix += 1;
+    }
+
+    return {nextState: entry.nextState, matchedSymbol: symbol, ix};
+  }
+
   withOverriddenHaltState(overriddenHaltState: State) {
     // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
     // are dead at runtime anyway (only the outermost `.wohs()`'s override is
diff --git a/packages/machine/src/classes/TapeBlock.ts b/packages/machine/src/classes/TapeBlock.ts
index be54155..a6d4041 100644
--- a/packages/machine/src/classes/TapeBlock.ts
+++ b/packages/machine/src/classes/TapeBlock.ts
@@ -153,6 +153,62 @@ export default class TapeBlock {
     )) ?? false;
   }
 
+  /**
+   * 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[] = this.currentSymbols,
+  ): ('wildcard' | 'literal')[] {
+    const tapeCount = this.#tapes.length;
+
+    if (symbol === ifOtherSymbol) {
+      return Array.from({length: tapeCount}, () => 'wildcard' as const);
+    }
+
+    const patternList = this.#symbolToPatternListMap.get(symbol);
+
+    if (patternList === undefined) {
+      return Array.from({length: tapeCount}, () => 'literal' as const);
+    }
+
+    const winning = patternList.find((pattern) => (
+      pattern.every((everySymbol, ix) => (
+        everySymbol === ifOtherSymbol
+        || everySymbol === currentSymbols[ix]
+      ))
+    ));
+
+    if (winning === undefined) {
+      return Array.from({length: tapeCount}, () => 'literal' as const);
+    }
+
+    return winning.map((everySymbol) => (
+      everySymbol === ifOtherSymbol ? 'wildcard' as const : 'literal' as const
+    ));
+  }
+
   replaceTape(tape: Tape, tapeIx = 0) {
     if (this.#tapes[tapeIx] == null) {
       throw new Error('invalid tapeIx');
diff --git a/packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts b/packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts
new file mode 100644
index 0000000..b94b050
--- /dev/null
+++ b/packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts
@@ -0,0 +1,197 @@
+import Alphabet from './Alphabet';
+import State, {haltState, ifOtherSymbol} from './State';
+import Tape from './Tape';
+import TapeBlock from './TapeBlock';
+import TuringMachine, {MachineState} from './TuringMachine';
+import {movements} from './TapeCommand';
+import {toGraph} from '../utilities/stateGraph';
+
+/**
+ * Per-iter `matchedTransition` (#205). For every yielded `MachineState`:
+ *
+ *   matchedTransition = {
+ *     id: string;                                 // resolvable in toGraph
+ *     matchKinds: ('wildcard' | 'literal')[];     // per-tape, length = tape count
+ *   }
+ *
+ * Cases covered here:
+ *   - Literal match (specific-symbol pattern fired): kind 'literal'.
+ *   - Wildcard match (`ifOtherSymbol` fired): kind 'wildcard'.
+ *   - Multi-tape with mixed per-position kinds.
+ *   - Wrapper-entry iter: id references the BARE's transition, not the wrapper.
+ *   - Halt-bound transitions get a resolvable id.
+ *   - id resolves in `toGraph`'s output (round-trip).
+ *
+ * Note: `nextStateId === 0` indicates the real halt singleton in toGraph; in-frame
+ * halts (wrapped) have `nextStateId === -frameId`. Both flavors still get a valid
+ * `matchedTransition.id` — the engine reports the source-anchored transition id
+ * regardless of where the transition points.
+ */
+
+const alphabet = new Alphabet([' ', 'a', 'b']);
+
+describe('MachineState.matchedTransition (#205)', () => {
+  test('literal match: id format `${stateId}.${ix}`, matchKinds = literal', async () => {
+    const tape = new Tape({alphabet, symbols: ['a']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const {symbol} = tapeBlock;
+
+    const state = new State({
+      [symbol(['a'])]: {nextState: haltState},
+    }, 'matchOnA');
+
+    const machine = new TuringMachine({tapeBlock});
+    const yields: MachineState[] = [];
+    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+
+    expect(yields).toHaveLength(1);
+    expect(yields[0].matchedTransition).toEqual({
+      id: `${state.id}.0`,
+      matchKinds: ['literal'],
+    });
+  });
+
+  test('wildcard match: ifOtherSymbol fires when no specific pattern matches', async () => {
+    const tape = new Tape({alphabet, symbols: ['a']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const {symbol} = tapeBlock;
+
+    const state = new State({
+      [symbol(['b'])]: {nextState: haltState},      // ix 0: specific 'b', won't fire on 'a'
+      [ifOtherSymbol]: {nextState: haltState},      // ix 1: catch-all, fires
+    }, 'catchAll');
+
+    const machine = new TuringMachine({tapeBlock});
+    const yields: MachineState[] = [];
+    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+
+    expect(yields).toHaveLength(1);
+    expect(yields[0].matchedTransition).toEqual({
+      id: `${state.id}.1`,
+      matchKinds: ['wildcard'],
+    });
+  });
+
+  test('multi-tape: per-tape matchKinds reflect the winning alternative', async () => {
+    // Two tapes. Pattern `[ifOtherSymbol, 'b']` matches tape0=anything, tape1='b'.
+    // Per-tape kinds for this match: ['wildcard', 'literal'].
+    const tapeA = new Tape({alphabet, symbols: ['a']});
+    const tapeB = new Tape({alphabet, symbols: ['b']});
+    const tapeBlock = TapeBlock.fromTapes([tapeA, tapeB]);
+    const {symbol} = tapeBlock;
+
+    const state = new State({
+      [symbol([ifOtherSymbol, 'b'])]: {
+        command: [{movement: movements.stay}, {movement: movements.stay}],
+        nextState: haltState,
+      },
+    }, 'wildcardThenLiteral');
+
+    const machine = new TuringMachine({tapeBlock});
+    const yields: MachineState[] = [];
+    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+
+    expect(yields).toHaveLength(1);
+    expect(yields[0].matchedTransition.matchKinds).toEqual(['wildcard', 'literal']);
+  });
+
+  test('multi-tape: matchKinds length always equals tape count', async () => {
+    const tapeA = new Tape({alphabet, symbols: ['a']});
+    const tapeB = new Tape({alphabet, symbols: ['a']});
+    const tapeBlock = TapeBlock.fromTapes([tapeA, tapeB]);
+    const {symbol} = tapeBlock;
+
+    const state = new State({
+      // Both positions specific:
+      [symbol(['a', 'a'])]: {
+        command: [{movement: movements.stay}, {movement: movements.stay}],
+        nextState: haltState,
+      },
+    });
+
+    const machine = new TuringMachine({tapeBlock});
+    const yields: MachineState[] = [];
+    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+
+    expect(yields[0].matchedTransition.matchKinds).toEqual(['literal', 'literal']);
+    expect(yields[0].matchedTransition.matchKinds).toHaveLength(2);
+  });
+
+  test('wrapper-entry iter: id references the bare\'s transition, not the wrapper', async () => {
+    // walkToBlank.withOverriddenHaltState(writeMarker): iter 1 starts at the
+    // wrapper (composite source), but the wrapper's transitions in toGraph
+    // are empty. The matched transition's id must reference the BARE's
+    // transition id so consumers can resolve it via
+    // `graph.nodes[bare.id].transitions`.
+    const tape = new Tape({alphabet, symbols: ['a']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const {symbol} = tapeBlock;
+
+    const bare = new State({
+      [symbol([alphabet.blankSymbol])]: {nextState: haltState},  // ix 0: specific blank
+      [ifOtherSymbol]: {command: [{movement: movements.right}]},  // ix 1: catch-all loop
+    }, 'walkToBlank');
+    const writeMarker = new State({
+      [ifOtherSymbol]: {nextState: haltState},
+    }, 'writeMarker');
+    const wrapper = bare.withOverriddenHaltState(writeMarker);
+
+    const machine = new TuringMachine({tapeBlock});
+    const yields: MachineState[] = [];
+    await machine.run({initialState: wrapper, onStep: (m) => { yields.push(m); }});
+
+    // Iter 1 source = wrapper (delegates to bare's transitions).
+    expect(yields[0].state).toBe(wrapper);
+    // matchedTransition.id uses the BARE's stateId, not the wrapper's.
+    expect(yields[0].matchedTransition.id).toBe(`${bare.id}.1`); // ifOtherSymbol slot
+    // Distinguishable: id's prefix doesn't match m.state.id when wrapper delegated.
+    expect(yields[0].matchedTransition.id.split('.')[0]).not.toBe(String(wrapper.id));
+  });
+
+  test('halt-bound transitions still get a resolvable id', async () => {
+    const tape = new Tape({alphabet, symbols: [alphabet.blankSymbol]});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const {symbol} = tapeBlock;
+
+    const state = new State({
+      [symbol([alphabet.blankSymbol])]: {nextState: haltState},  // halt-bound
+    }, 'haltOnBlank');
+
+    const machine = new TuringMachine({tapeBlock});
+    const yields: MachineState[] = [];
+    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+
+    expect(yields).toHaveLength(1);
+    expect(yields[0].matchedTransition).toEqual({
+      id: `${state.id}.0`,
+      matchKinds: ['literal'],
+    });
+    expect(yields[0].nextState).toBe(haltState);
+  });
+
+  test('id round-trips through toGraph: graph.nodes[…].transitions has a matching id', async () => {
+    const tape = new Tape({alphabet, symbols: ['a', 'b']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const {symbol} = tapeBlock;
+
+    const state = new State({
+      [symbol(['a'])]: {command: [{movement: movements.right}]}, // ix 0
+      [symbol(['b'])]: {nextState: haltState},                    // ix 1
+    });
+
+    const machine = new TuringMachine({tapeBlock});
+    const yields: MachineState[] = [];
+    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+
+    const graph = toGraph(state, tapeBlock);
+
+    // Every observed matchedTransition.id is findable in the graph.
+    for (const m of yields) {
+      const sourceId = Number(m.matchedTransition.id.split('.')[0]);
+      const node = graph.nodes[sourceId];
+      expect(node).toBeDefined();
+      const found = node.transitions.find((t) => t.id === m.matchedTransition.id);
+      expect(found).toBeDefined();
+    }
+  });
+});
diff --git a/packages/machine/src/classes/TuringMachine.spec.ts b/packages/machine/src/classes/TuringMachine.spec.ts
index 2a32465..23f81b3 100644
--- a/packages/machine/src/classes/TuringMachine.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.spec.ts
@@ -45,6 +45,21 @@ describe('run tests', () => {
       },
     });
 
+    // #205 matchedTransition. Transition declaration order on
+    // `initialState`:
+    //   ix 0 → `[symbol(symbolList)]` (specific symbol-list pattern)
+    //   ix 1 → `[ifOtherSymbol]` (catch-all)
+    // Iters 1-3 read concrete alphabet symbols matched by ix 0 (literal).
+    // Iter 4 reads blank, falls through to ix 1 (wildcard).
+    const transitionListMatch = {
+      id: `${initialState.id}.0`,
+      matchKinds: ['literal' as const],
+    };
+    const transitionWildcardMatch = {
+      id: `${initialState.id}.1`,
+      matchKinds: ['wildcard' as const],
+    };
+
     expectedSteps = [
       {
         step: 1,
@@ -53,6 +68,7 @@ describe('run tests', () => {
         nextSymbols: [alphabet.blankSymbol],
         movements: [movements.right],
         nextState: initialState,
+        matchedTransition: transitionListMatch,
       },
       {
         step: 2,
@@ -61,6 +77,7 @@ describe('run tests', () => {
         nextSymbols: [alphabet.blankSymbol],
         movements: [movements.right],
         nextState: initialState,
+        matchedTransition: transitionListMatch,
       },
       {
         step: 3,
@@ -69,6 +86,7 @@ describe('run tests', () => {
         nextSymbols: [alphabet.blankSymbol],
         movements: [movements.right],
         nextState: initialState,
+        matchedTransition: transitionListMatch,
       },
       {
         step: 4,
@@ -77,6 +95,7 @@ describe('run tests', () => {
         nextSymbols: [alphabet.blankSymbol],
         movements: [movements.stay],
         nextState: haltState,
+        matchedTransition: transitionWildcardMatch,
       },
     ];
   });
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index c069ece..b36f83b 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -1,4 +1,4 @@
-import State, {haltState, type DebugConfig} from './State';
+import State, {haltState, STATE_INTERNAL, type DebugConfig} from './State';
 import TapeBlock, {lockSymbol} from './TapeBlock';
 import {symbolCommands} from './TapeCommand';
 
@@ -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')[];
+  };
 };
 
 // True iff `filter` matches `symbol` per the DebugConfig semantics.
@@ -172,7 +195,22 @@ export default class TuringMachine {
 
         const symbol = state.getSymbol(this.#tapeBlock);
         const command = state.getCommand(symbol);
-        let nextState = state.getNextState(symbol).ref;
+        const matched = state.getMatchedTransition(symbol);
+        let nextState = matched.nextState.ref;
+        // For wrapper-entry iters, the wrapper's transitions in `toGraph`
+        // are empty (wrappers delegate to the bare via shared
+        // `#symbolToDataMap`); the resolvable transition id lives under
+        // the bare's stateId. `bareState` is non-null only when `state`
+        // is a wrapper produced by `withOverriddenHaltState`. Accessed
+        // via the STATE_INTERNAL package-private view (same pattern
+        // `utilities/stateGraph.ts` uses) to avoid widening the public
+        // State API for this internal need.
+        const stateInternal = state[STATE_INTERNAL]();
+        const resolvableStateId = stateInternal.bareState?.id ?? state.id;
+        const matchedTransition: MachineState['matchedTransition'] = {
+          id: `${resolvableStateId}.${matched.ix}`,
+          matchKinds: this.#tapeBlock.patternKinds(matched.matchedSymbol),
+        };
 
         try {
           // Both before and after refer to THIS iter (#119 / v6.0.0).
@@ -206,6 +244,7 @@ export default class TuringMachine {
             }),
             movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
             nextState: nextStateForYield,
+            matchedTransition,
           };
 
           if (beforeMatch || afterMatch) {
diff --git a/packages/machine/src/utilities/stateGraph.spec.ts b/packages/machine/src/utilities/stateGraph.spec.ts
index 0472dd0..7b3fdcd 100644
--- a/packages/machine/src/utilities/stateGraph.spec.ts
+++ b/packages/machine/src/utilities/stateGraph.spec.ts
@@ -30,7 +30,7 @@ describe('collectStates (#195)', () => {
     let assertions = 0;
     for (const node of Object.values(graph.nodes)) {
       for (const t of node.transitions) {
-        const [nStr, kStr] = t.id.split('-');
+        const [nStr, kStr] = t.id.split('.');
         const n = Number(nStr);
         const k = Number(kStr);
         const entry = stateMap.get(n);
@@ -178,12 +178,13 @@ describe('collectStates (#195)', () => {
     expect(entry.transitionSymbols[0]).toBe(sym0);
     expect(entry.transitionSymbols[1]).toBe(sym1);
 
-    // No GraphTransition with id `${s.id}-0` (the unbound-ref slot);
+    // No GraphTransition with id `${s.id}.0` (the unbound-ref slot);
     // the one for slot 1 (the bound transition) DOES exist.
+    // (#205 changed separator from `-` to `.`.)
     const node = graph.nodes[s.id];
     const ids = node.transitions.map((t) => t.id);
-    expect(ids).not.toContain(`${s.id}-0`);
-    expect(ids).toContain(`${s.id}-1`);
+    expect(ids).not.toContain(`${s.id}.0`);
+    expect(ids).toContain(`${s.id}.1`);
   });
 });
 
diff --git a/packages/machine/src/utilities/stateGraph.ts b/packages/machine/src/utilities/stateGraph.ts
index 7187161..0fba329 100644
--- a/packages/machine/src/utilities/stateGraph.ts
+++ b/packages/machine/src/utilities/stateGraph.ts
@@ -142,7 +142,14 @@ export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
           movement: decodeMovement((tc.movement as symbol).description),
         })),
         nextStateId: targetInternal.id,
-        id: `${stateInternal.id}-${patternIx}`,
+        // Transition id format: `${stateId}.${transitionIx}` (#205).
+        // Matches `TuringMachine.runStepByStep`'s `MachineState.
+        // matchedTransition.id` so consumers can do
+        // `graph.nodes[stateId].transitions.find(t => t.id === id)`.
+        // Was `${stateId}-${ix}` pre-#205 — the `.` separator avoids
+        // the hyphen reading as a minus sign next to negative halt-
+        // marker ids in adjacent contexts.
+        id: `${stateInternal.id}.${patternIx}`,
       });
 
       queue.push(target);
@@ -521,7 +528,8 @@ export type StateMap = Map<number, StateMapEntry>;
  * instance + per-pattern Symbol references for breakpoint setup (#195).
  *
  * **Positional alignment contract.** For any `GraphTransition` whose id
- * is `${N}-${K}`, `result.get(N)!.transitionSymbols[K]` is the Symbol
+ * is `${N}.${K}` (#205 changed the separator from `-` to `.`),
+ * `result.get(N)!.transitionSymbols[K]` is the Symbol
  * the transition fires on (reference equality, not structural). The K-th
  * entry is the K-th key from the source State's `#symbolToDataMap` in
  * insertion order, including `ifOtherSymbol` when the user wrote one.
@@ -532,7 +540,7 @@ export type StateMap = Map<number, StateMapEntry>;
  * when a transition's `nextState` is an unresolved `Reference` (it
  * `continue`s without pushing the GraphTransition). In that case
  * `transitionSymbols[K]` is still set to the K-th Map key, but no
- * `Graph.nodes[N].transitions` entry exists with id `${N}-${K}`. Sparse
+ * `Graph.nodes[N].transitions` entry exists with id `${N}.${K}`. Sparse
  * on the Graph side, dense on the `transitionSymbols` side — same
  * indexing.
  *
@@ -631,7 +639,7 @@ export function collectStates(initialState: State, tapeBlock: TapeBlock): StateM
 
     // Regular or bare State — enumerate `#symbolToDataMap.keys()` for
     // the patternIx alignment. The K-th key is the Symbol that
-    // `${id}-${K}` GraphTransition fires on (positional contract).
+    // `${id}.${K}` GraphTransition fires on (positional contract).
     const state = stateById.get(id)!;
     const transitionSymbols = [...state[STATE_INTERNAL]().symbolToDataMap.keys()];
     result.set(id, {state, transitionSymbols});

From aa15f6905496d4aaf38081db35d0bf703393d4e3 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sun, 24 May 2026 22:28:12 +0300
Subject: [PATCH 043/118] docs(machine): document
 MachineState.matchedTransition (#205)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README gains a "Matched transition" subsection covering the `id` format,
wrapper-entry → bare delegation rule, per-tape `matchKinds` semantics, and
a usage example. CLAUDE.md gets a paragraph on the field and notes the
`toGraph` transition-id separator change from `-` (alpha.4) to `.`.
---
 CLAUDE.md                  |  4 +++-
 packages/machine/README.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a338203..cf36779 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,7 +61,9 @@ Key shapes that take reading multiple files to grasp:
 
 `packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same `Graph` through [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) syntax (renderer: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)). The parser is strict to the dialect `toMermaid` emits — hand-edited Mermaid with different arrow styles or shapes won't round-trip.
 
-**`State.collectStates(state, tapeBlock)`** (v7, #195) — returns a `Map<number, {state, transitionSymbols}>` keyed by engine `GraphNode.id`. For each id: the live `State` instance and the per-pattern `Symbol[]` from `#symbolToDataMap` in insertion order. The K-th `transitionSymbols` slot is positionally aligned with the GraphTransition whose id is `${stateId}-${K}`, so consumers holding `(stateId, patternIx)` from a rendered graph reach the firing Symbol with no walk. `ifOtherSymbol` is included 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. Halt-singleton entry at id `0` is the process-wide singleton — JSDoc warns toggling its `debug` affects every machine in the runtime.
+**`State.collectStates(state, tapeBlock)`** (v7, #195) — returns a `Map<number, {state, transitionSymbols}>` keyed by engine `GraphNode.id`. For each id: the live `State` instance and the per-pattern `Symbol[]` from `#symbolToDataMap` in insertion order. The K-th `transitionSymbols` slot is positionally aligned with the GraphTransition whose id is `${stateId}.${K}` (separator was `-` in alpha.4; #205 changes it to `.` for v7), so consumers holding `(stateId, patternIx)` from a rendered graph reach the firing Symbol with no walk. `ifOtherSymbol` is included 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. Halt-singleton entry at id `0` is the process-wide singleton — JSDoc warns toggling its `debug` affects every machine in the runtime.
+
+**Per-iter `matchedTransition`** (v7, [#205](https://github.com/mellonis/turing-machine-js/issues/205) / [PR #206](https://github.com/mellonis/turing-machine-js/pull/206)) — every `MachineState` yielded by `run` / `runStepByStep` carries `matchedTransition: { id: string, matchKinds: ('wildcard'|'literal')[] }`. `id` is `${stateId}.${transitionIx}` and resolves in `toGraph`'s output via `graph.nodes[stateId].transitions.find(t => t.id === ...)`. For wrapper-entry iters (composite source from `withOverriddenHaltState`), `id` references the **bare's** transition — wrappers' own `transitions` arrays are empty because the pattern lives on the bare; consumers detect delegation by comparing `id.split('.')[0]` against `state.id`. `matchKinds` is per-tape, length = tape count; `'wildcard'` iff the winning alternative held `ifOtherSymbol` at that position (catch-all), `'literal'` otherwise. Halt-bound transitions still get a valid id (both real halt `nextStateId === 0` and in-frame halt markers `nextStateId === -frameId`). The field eliminates ambiguity in `(source, nextState)` resolution when multiple transitions on the same source share a destination, and lets consumers do exact-edge highlighting / per-transition coverage maps / wildcard-aware log formatting without re-parsing pattern strings from `toGraph`. The separator change from `-` (alpha.4) to `.` propagates to `toGraph`'s `GraphTransition.id` — see `collectStates` note above.
 
 **`STATE_INTERNAL` Symbol accessor** (v7, #180) — `state[STATE_INTERNAL]()` returns a getter/setter view onto `State`'s private fields (`id`, `name`, `bareState`, `overriddenHaltState`, `symbolToDataMap`, `tags`). `@internal`-marked. Exported from `classes/State.ts` for sibling-module use in `packages/machine/src` (currently `utilities/stateGraph.ts`); NOT re-exported from the package's public `index.ts`. The `name` setter is the one mutation site, used by `fromGraph` to assign graph-sourced composite names (e.g. `A(target)`) that the constructor's paren-validator would reject. New utility modules in `packages/machine/src` that need private-field access route through this accessor rather than growing per-module bypasses. `toGraph`/`fromGraph`/`collectStates` all live in `utilities/stateGraph.ts` (extracted from `classes/State.ts` in #180); `State.toGraph` / `.fromGraph` / `.collectStates` statics remain as thin delegates for backwards compat.
 
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 580e3d8..a40737d 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -327,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.
 
@@ -346,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.

From 5012f4e149d2b0bd56dd16128efef70c835266b2 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sun, 24 May 2026 23:34:53 +0300
Subject: [PATCH 044/118] refactor(State): single #getEntry helper for
 command/nextState/matchedTransition lookup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Before #206 each accessor did its own `#symbolToDataMap.has() + .get()!`
double-lookup with a slightly different error string ("No command for…" /
"No nextState for…"). Extracted to a private `#getEntry(symbol)` helper
(one map-get, unified throw "No transition for symbol at state named …").
`getCommand`, `getNextState`, and `getMatchedTransition` are now thin
accessors over it — same public API, single lookup site, single error
message.
---
 packages/machine/src/classes/State.spec.ts | 19 ++++++++---
 packages/machine/src/classes/State.ts      | 38 ++++++++++++----------
 2 files changed, 35 insertions(+), 22 deletions(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index b1eb68f..9b33f1a 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -103,17 +103,26 @@ describe('State constructor — invalid inputs', () => {
   });
 });
 
-describe('State.getCommand / .getNextState — error paths', () => {
+describe('State.getCommand / .getNextState / .getMatchedTransition — error paths', () => {
   // Default-constructed State has an empty symbolToDataMap; any lookup throws.
+  // #206 unified the message across all three methods: the prior per-method
+  // wording ("No command for…" / "No nextState for…") conveyed the same root
+  // cause ("no transition for this symbol") and the public methods now share
+  // a single `#getEntry` helper.
 
-  test('getCommand on an unmapped symbol throws "No command for symbol at state named …"', () => {
+  test('getCommand on an unmapped symbol throws "No transition for symbol at state named …"', () => {
     expect(() => new State().getCommand(ifOtherSymbol))
-      .toThrow(/^No command for symbol at state named/);
+      .toThrow(/^No transition for symbol at state named/);
   });
 
-  test('getNextState on an unmapped symbol throws "No nextState for symbol at state named …"', () => {
+  test('getNextState on an unmapped symbol throws "No transition for symbol at state named …"', () => {
     expect(() => new State().getNextState(ifOtherSymbol))
-      .toThrow(/^No nextState for symbol at state named/);
+      .toThrow(/^No transition for symbol at state named/);
+  });
+
+  test('getMatchedTransition on an unmapped symbol throws "No transition for symbol at state named …"', () => {
+    expect(() => new State().getMatchedTransition(ifOtherSymbol))
+      .toThrow(/^No transition for symbol at state named/);
   });
 });
 
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 45a35fc..0d20547 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -335,20 +335,28 @@ export default class State {
     return ifOtherSymbol;
   }
 
-  getCommand(symbol: symbol) {
-    if (this.#symbolToDataMap.has(symbol)) {
-      return this.#symbolToDataMap.get(symbol)!.command;
+  // Single lookup + throw site shared by `getCommand`, `getNextState`, and
+  // `getMatchedTransition`. Returns the symbol's entry `{command, nextState}`
+  // (one map-get, no `.has()` pre-check); throws a unified message when no
+  // entry exists. Before #206, each public method did its own `.has() + .get()!`
+  // double-lookup with a slightly different error string — same root cause
+  // ("no transition for this symbol"), so the message is unified.
+  #getEntry(symbol: symbol) {
+    const entry = this.#symbolToDataMap.get(symbol);
+
+    if (entry === undefined) {
+      throw new Error(`No transition for symbol at state named ${this.#name}`);
     }
 
-    throw new Error(`No command for symbol at state named ${this.#name}`);
+    return entry;
   }
 
-  getNextState(symbol: symbol) {
-    if (this.#symbolToDataMap.has(symbol)) {
-      return this.#symbolToDataMap.get(symbol)!.nextState;
-    }
+  getCommand(symbol: symbol) {
+    return this.#getEntry(symbol).command;
+  }
 
-    throw new Error(`No nextState for symbol at state named ${this.#id}`);
+  getNextState(symbol: symbol) {
+    return this.#getEntry(symbol).nextState;
   }
 
   /**
@@ -361,9 +369,9 @@ export default class State {
    * which is ambiguous when multiple transitions on the same source go to
    * the same destination.
    *
-   * Throws (matching `getNextState`) 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
+   * 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.
    */
@@ -372,11 +380,7 @@ export default class State {
     matchedSymbol: symbol,
     ix: number,
   } {
-    const entry = this.#symbolToDataMap.get(symbol);
-
-    if (entry === undefined) {
-      throw new Error(`No nextState for symbol at state named ${this.#id}`);
-    }
+    const entry = this.#getEntry(symbol);
 
     // Iteration order on a Map is insertion order; index lookup is O(N),
     // acceptable since this fires at most once per iter and N (transitions

From 2957cd9cd8faac4aed61f462ffbef74efcd9d1ae Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 00:34:44 +0300
Subject: [PATCH 045/118] =?UTF-8?q?feat(State):=20haltState.debug=20?=
 =?UTF-8?q?=E2=86=92=20boolean=20+=20post-iter=20timing=20(#207)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`state.debug` was `{before, after}` for every State, including haltState — a
poor fit since haltState never IS an iter's state (halt is terminal). The
shape forced two artifacts: `.after = true` already threw at write time
(#108 part 2), and `.before` was repurposed to fire BEFORE the iter whose
transition leads to halt — an asymmetric, half-restricted API where the
pause landed before the halt-bound transition had even fired, requiring
tools to do forward projection to render "halt is imminent".

Collapses haltState's debug to a single boolean ("enabled / disabled"):

  haltState.debug = true;            // pause when halt is about to take effect
  haltState.debug = false;           // turn off
  haltState.debug = null;            // alias of false (reset)
  haltState.debug = {before: true};  // throws — "only accepts boolean"

A `HaltState` typed alias on the singleton export narrows `debug` to
`boolean` for compile-time safety at the canonical access path. Non-halt
states are unchanged — `DebugConfig` only; boolean writes throw.

Pause timing moves to the AFTER side of the halt-triggering iter: after
the iter's own after-pause (if armed), before halt processing. `m.state`
is the triggering state (not haltState), `m.debugBreak.after === true`.
This drops the v6 "early-warning" behavior (pause before the halt-bound
step ran) — the catch-all detection is preserved at the new timing.

Reading flow now matches user mental model: the diagram cursor sits on
the triggering state, the halt-bound transition shows as fired, and the
halt edge naturally reads as the next thing the engine does.

Breaking change inside v7-alpha (v7 IS the SemVer-major break).
---
 CLAUDE.md                                     |   4 +-
 packages/machine/README.md                    |  16 ++-
 packages/machine/src/classes/State.ts         | 112 ++++++++++++++----
 .../src/classes/TuringMachine.debug.spec.ts   |  99 ++++++++++------
 packages/machine/src/classes/TuringMachine.ts |  17 ++-
 test/examples.spec.ts                         |  17 +--
 6 files changed, 192 insertions(+), 73 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index cf36779..93b3f6f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,10 +47,10 @@ Key shapes that take reading multiple files to grasp:
 
 - **`TapeBlock` has a `Lock`** that `TuringMachine.run` grabs for the duration of a run, asserting the block isn't being mutated by another machine. Calls to `applyCommand` from outside a run must pass the matching capture symbol.
 
-- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverriddenHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. Pauses dispatch via the optional `onPause` hook on `run()` (awaited; without the hook, breaks fire-and-resume invisibly). `haltState.debug.before = true` pauses on every halt entry (program exit + subroutine pop). See `packages/machine/README.md` "Debugging breakpoints (v4+)" for the full API.
+- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverriddenHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. Pauses dispatch via the optional `onPause` hook on `run()` (awaited; without the hook, breaks fire-and-resume invisibly). **As of v7 #207, `haltState.debug` is a `boolean`** (not `DebugConfig`) — halt is terminal with one meaningful pause moment (post-triggering-iter, before halt processing). `haltState.debug = true` pauses on every halt entry (program exit + subroutine pop); the pause fires on the AFTER side of the iter whose transition leads to halt (`m.state` is the triggering state, `m.debugBreak.after === true`). Any object-shaped write (`{ before: true }`, `{ after: true }`, etc.) throws at write time. The `HaltState` typed alias on the singleton export narrows `debug` to `boolean` for compile-time safety at the canonical access path. See `packages/machine/README.md` "Debugging breakpoints (v4+)" for the full API.
 
   Cross-version notes:
-  - **v5**: hook renamed `onDebugBreak` → `onPause` (#110). `haltState.debug.after = true` (or `{ before, after }` together) now throws at write-time — halt is terminal, no iteration-after-halt to anchor on (#108 part 2). Halting iter's after-fire stopped being silently lost (#108 part 1). New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without editing `state.debug` assignments (#106).
+  - **v5**: hook renamed `onDebugBreak` → `onPause` (#110). `haltState.debug.after = true` (or `{ before, after }` together) now throws at write-time — halt is terminal, no iteration-after-halt to anchor on (#108 part 2). *Superseded in v7 by [#207](https://github.com/mellonis/turing-machine-js/issues/207): `haltState.debug` is now a boolean and ALL object writes throw — the per-side shape never modeled anything for halt.* Halting iter's after-fire stopped being silently lost (#108 part 1). New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without editing `state.debug` assignments (#106).
   - **v6**: `onPause(after, K)` now fires on iter K's *own* yield, alongside `onPause(before, K)` and `onStep(K)` — per-iter lifecycle is `before → step → after` (#119). Previously `after` fired on iter K+1's tick with a `prevYield` substitution dance; that substitution is gone. Implication: tests asserting cross-hook ordering at the lifecycle level need v6-aware shape.
   - **v6.1**: `state.debug` is now always a non-null `DebugConfig` (lazy-initialized on first read), so chained writes like `state.debug.before = true` work on a fresh state without a prior whole-object assignment. The instance is `Object.seal`-ed — typos throw `TypeError`. `state.debug = null` continues to work but now means "reset filters" (next read returns a fresh empty config). Type signature narrowed `DebugConfig | null` → `DebugConfig` on the getter; setter still accepts `null`. (#150)
   - **v6.2** *(superseded by v6.3)*: briefly widened `onStep` to `(m) => void | Promise<void>` and added an inline `await onStep(m)` in the run loop, motivated by a downstream throttle use case. That overturned the docstring-stated sync contract for `onStep` and was reverted in v6.3.0. Don't reach for that shape — the v6.4 `onIter` hook is the proper place for per-iter awaited coordination.
diff --git a/packages/machine/README.md b/packages/machine/README.md
index a40737d..5b07618 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -497,14 +497,18 @@ 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 };
-
-// Reset filters later — next read returns a fresh empty DebugConfig:
+// 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 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.
 
 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`.
 
@@ -738,7 +742,7 @@ 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.
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index 0d20547..f1667c9 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -129,6 +129,15 @@ export default class State {
   // a runtime concern, not part of the structural graph.
   #debugRef: { current: DebugConfig | null } = {current: null};
 
+  // Storage for `haltState.debug` (#207). haltState is a singleton terminal
+  // state — it has no iter of its own, so the per-side `{ before, after }`
+  // DebugConfig shape doesn't model anything meaningful for it. Instead the
+  // halt breakpoint is a single boolean ("enabled / disabled"). The pause
+  // anchors on the iter whose transition LEADS to halt, fired at end-of-iter
+  // (after that iter's own after-pause if armed). Only used when `isHalt`;
+  // ignored on every other State (whose `#debugRef` flow is unchanged).
+  #haltDebug: boolean = false;
+
   // Out-of-band tags applied to this State (#186). Tags are visualization
   // and debugger-tooling metadata — they don't affect runtime transition
   // lookup or `equivalentOn` comparisons. Stored as a Set for de-duplication;
@@ -224,6 +233,18 @@ export default class State {
   }
 
   get debug(): DebugConfig {
+    // haltState (#207): the canonical access path is the `haltState` singleton
+    // export, which is typed `HaltState` — its `debug` getter is narrowed to
+    // `boolean`. Generic `State` references statically see `DebugConfig` and
+    // (in practice) never refer to haltState — the run loop's `state` is
+    // never haltState because halt is terminal and doesn't iterate. The cast
+    // below makes the runtime boolean return type-compatible with the
+    // declared `DebugConfig` for any rare caller that holds a State
+    // reference happening to be haltState.
+    if (this.isHalt) {
+      return this.#haltDebug as unknown as DebugConfig;
+    }
+
     // Lazy-init: `state.debug` is never null at read time, so chained writes
     // like `state.debug.before = true` work on a fresh state without a prior
     // whole-object assignment. The setter still accepts `null` to reset the
@@ -236,20 +257,58 @@ export default class State {
     return this.#debugRef.current;
   }
 
+  // TS signature: non-halt callers (generic `State` reference) get the
+  // `DebugConfig | object | null` surface; boolean is rejected statically.
+  // The `HaltState` typed alias on the singleton export overrides this to
+  // `boolean | null` for the canonical halt access path. Runtime checks
+  // below are defensive against type-bypass / mixed-source callers.
   set debug(
     value: DebugConfig | { before?: symbol[] | readonly symbol[] | true; after?: symbol[] | readonly symbol[] | true } | null,
   ) {
-    if (value === null) {
+    // Defensive runtime cast: TS signature excludes boolean for the generic
+    // State surface, but haltState (via the HaltState alias) DOES accept
+    // boolean, and the runtime needs to handle it for the singleton path.
+    const v = value as DebugConfig | { before?: unknown; after?: unknown } | boolean | null;
+    // haltState (#207): only `boolean | null` is accepted. `null` aliases
+    // to `false` (reset). Any object-shaped write throws at write-time so
+    // misuse surfaces immediately rather than silently no-op'ing — the
+    // `{before, after}` shape doesn't model anything meaningful for halt
+    // (no own iter to anchor on; halt is terminal).
+    if (this.isHalt) {
+      if (v === null || typeof v === 'boolean') {
+        this.#haltDebug = v === true;
+        return;
+      }
+
+      throw new Error(
+        'haltState.debug only accepts boolean (or null to reset). Use '
+        + '`haltState.debug = true` to enable the halt breakpoint, false to '
+        + 'disable. The pause fires after the iter whose transition leads to '
+        + 'halt (post-iter, before halt processing).',
+      );
+    }
+
+    // Non-halt states: boolean writes are rejected — the per-side
+    // `{before, after}` granularity is the contract. A boolean shortcut
+    // would hide the asymmetry between before / after.
+    if (typeof v === 'boolean') {
+      throw new Error(
+        'state.debug only accepts a DebugConfig or `{ before, after }` object '
+        + '(or null to reset). Boolean assignment is reserved for `haltState`.',
+      );
+    }
+
+    if (v === null) {
       this.#debugRef.current = null;
       return;
     }
 
-    if (value instanceof DebugConfig) {
-      this.#debugRef.current = value;
+    if (v instanceof DebugConfig) {
+      this.#debugRef.current = v;
       return;
     }
 
-    this.#debugRef.current = new DebugConfig(this, value);
+    this.#debugRef.current = new DebugConfig(this, v as { before?: symbol[] | readonly symbol[] | true; after?: symbol[] | readonly symbol[] | true });
   }
 
   /**
@@ -287,31 +346,18 @@ export default class State {
     return Object.freeze([...this.#tags]);
   }
 
-  /** @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 {
     if (filter === undefined) return;
 
-    // #108 part 2: `.after` on haltState has no semantic anchor — halt is
-    // terminal, so there is no iteration-after-halt for an after-fire to
-    // attach to. Reject any truthy assignment (true OR list) at write time
-    // so misuse surfaces immediately rather than silently no-op'ing.
-    if (this.isHalt && fieldName === 'after') {
-      throw new Error(
-        'haltState.debug.after is not supported: halt is terminal, so there is '
-        + 'no iteration-after-halt for an after-fire to anchor on. Use '
-        + '{ before: true } to pause on halt entry.',
-      );
-    }
-
     if (filter === true) return;
 
-    // haltState has no own transitions; symbol-list filters on `before` are
-    // silent no-ops at the engine level (spec §8.6), so accept any list shape.
-    if (this.isHalt) return;
-
     for (const sym of filter) {
       if (sym !== ifOtherSymbol && !this.#symbolToDataMap.has(sym)) {
         throw new Error(
@@ -576,4 +622,26 @@ export default class State {
   }
 }
 
-export const haltState = new State(null);
+/**
+ * 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 const haltState: HaltState = new State(null) as HaltState;
diff --git a/packages/machine/src/classes/TuringMachine.debug.spec.ts b/packages/machine/src/classes/TuringMachine.debug.spec.ts
index b54e761..a66c51c 100644
--- a/packages/machine/src/classes/TuringMachine.debug.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.debug.spec.ts
@@ -158,39 +158,45 @@ describe('TuringMachine — debug.after filter (loop yields)', () => {
   });
 });
 
-describe('TuringMachine — haltState.debug.before', () => {
+describe('TuringMachine — haltState.debug (boolean, #207)', () => {
   afterEach(() => {
     // haltState is a singleton — clear after each test to avoid cross-pollution.
-    haltState.debug = null;
+    haltState.debug = false;
   });
 
-  test('haltState.debug.before = true fires on program halt (last visit only)', async () => {
+  test('haltState.debug = true fires `debugBreak.after` on the halt-triggering iter (#207)', async () => {
     const {machine, state} = buildMachine();
-    haltState.debug = {before: true};
+    haltState.debug = true;
     const steps: MachineState[] = [];
 
     await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
 
     expect(steps).toHaveLength(VISIT_COUNT);
-    // Only the visit that transitions to halt (the trailing blank) carries
-    // debugBreak.before from haltState.debug.before — the earlier visits
-    // transition self-loop, not to halt.
+    // Only the visit whose transition leads to halt (the trailing blank →
+    // ifOtherSymbol → haltState) carries `debugBreak.after`. The earlier
+    // visits self-loop within `state`, so their nextState is `state` itself,
+    // not haltState — no halt-imminent dispatch.
     for (let i = 0; i < VISIT_COUNT - 1; i++) {
       expect(steps[i]).not.toHaveProperty('debugBreak');
     }
     const last = steps[VISIT_COUNT - 1];
     expect(last.nextState).toBe(haltState);
-    expect(last.debugBreak).toEqual({before: true});
+    // #207 timing: fires on AFTER side (post-iter, before halt processing) —
+    // not BEFORE as the v6 API did. `m.state` is the TRIGGERING state (the
+    // one whose transition leads to halt), not haltState itself.
+    expect(last.state).toBe(state);
+    expect(last.debugBreak).toEqual({after: true});
   });
 
-  test('haltState.debug.before fires on subroutine return (halt-pop)', async () => {
+  test('haltState.debug = true fires on each halt entry — including subroutine return (halt-pop)', async () => {
     // Custom 1-cell tape + nested-state setup. Trajectory:
     //   visit 1: head 'A', state=wrapped → erase+right, transition to inner
     //   visit 2: head blank, state=inner → ifOtherSymbol → would halt;
     //            wrapped's override redirects to continuation. nextState=continuation.
-    //            haltState.debug.before fires (because original nextState was haltState).
+    //            #207: halt-imminent fires on AFTER side (transition's original
+    //            nextState was haltState before the pop redirect).
     //   visit 3: head blank, state=continuation → ifOtherSymbol → halt.
-    //            haltState.debug.before fires again.
+    //            #207: halt-imminent fires on AFTER side.
     const tape = new Tape({alphabet, symbols: ['A']});
     const tapeBlock = TapeBlock.fromTapes([tape]);
     const machine = new TuringMachine({tapeBlock});
@@ -209,7 +215,7 @@ describe('TuringMachine — haltState.debug.before', () => {
 
     const wrapped = inner.withOverriddenHaltState(continuation);
 
-    haltState.debug = {before: true};
+    haltState.debug = true;
     const steps: MachineState[] = [];
 
     await machine.run({initialState: wrapped, onStep: (s) => { steps.push(s); }});
@@ -219,33 +225,41 @@ describe('TuringMachine — haltState.debug.before', () => {
     // Visit 1: just self-loops into inner — no halt-related break.
     expect(steps[0]).not.toHaveProperty('debugBreak');
 
-    // Visit 2: transitions to continuation via halt-pop. debugBreak.before fires
-    // because nextState (pre-pop) was haltState.
+    // Visit 2: transitions to continuation via halt-pop. `debugBreak.after`
+    // fires because the transition's original nextState was haltState (the
+    // pop-redirect to continuation happens AFTER the engine's halt check).
     const popYield = steps.find((s) => s.nextState === continuation);
     expect(popYield).toBeDefined();
     expect(popYield).toBe(steps[1]);
-    expect(popYield!.debugBreak).toEqual({before: true});
+    expect(popYield!.debugBreak).toEqual({after: true});
 
-    // Visit 3: transitions to halt directly. debugBreak.before fires.
+    // Visit 3: transitions to halt directly. `debugBreak.after` fires.
     expect(steps[2].nextState).toBe(haltState);
-    expect(steps[2].debugBreak).toEqual({before: true});
+    expect(steps[2].debugBreak).toEqual({after: true});
   });
 
-  test('haltState.debug.before with symbol list NEVER matches (no head symbol at halt)', async () => {
-    const {machine, state, symbol} = buildMachine();
-    const symA = symbol(['A']);
-    haltState.debug = {before: [symA]};
+  test('haltState.debug = false / null suppresses dispatch on every iter', async () => {
+    const {machine, state} = buildMachine();
+    haltState.debug = false;
     const steps: MachineState[] = [];
 
     await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
 
     expect(steps).toHaveLength(VISIT_COUNT);
-    // Halt has no head symbol; list filter cannot match. No debug break should fire
-    // because of haltState.debug. (state.debug is null, so no other source.)
     for (const step of steps) {
       expect(step).not.toHaveProperty('debugBreak');
     }
   });
+
+  test('haltState.debug getter returns boolean (typed `boolean` via HaltState alias)', () => {
+    haltState.debug = true;
+    expect(haltState.debug).toBe(true);
+    haltState.debug = false;
+    expect(haltState.debug).toBe(false);
+    haltState.debug = null;
+    // null aliases to false (reset).
+    expect(haltState.debug).toBe(false);
+  });
 });
 
 describe('TuringMachine — run() with onPause', () => {
@@ -391,22 +405,41 @@ describe('TuringMachine — halt semantics for after-fire (#108)', () => {
     expect(after).toHaveLength(VISIT_COUNT);
   });
 
-  test('haltState.debug.after = true throws on assignment (#108 part 2)', () => {
-    // Halt is terminal — no iteration-after-halt for an after-fire to anchor on.
-    // v5 rejects the assignment to surface the misuse rather than silently
-    // ignore it.
+  test('haltState.debug = {after: true} throws — boolean-only API (#207, supersedes #108 part 2)', () => {
+    // #207 collapsed haltState's debug to a single boolean — the {before, after}
+    // shape doesn't model anything meaningful for a terminal singleton. Any
+    // object write throws at write-time with a clear message.
     expect(() => {
+      // @ts-expect-error — HaltState typed alias narrows to `boolean`; the runtime throw
+      // is the secondary line of defense for callers reaching haltState through a
+      // generic `State` reference (e.g. `state.getNextState(sym).ref`).
       haltState.debug = {after: true};
-    }).toThrow();
+    }).toThrow(/haltState\.debug only accepts boolean/);
   });
 
-  test('haltState.debug with both flags throws (#108 part 2)', () => {
-    // Setting before+after symmetrically is the most likely user mistake; the
-    // .after part is meaningless and v5 rejects the whole assignment. Use
-    // { before: true } alone.
+  test('haltState.debug = {before: true} throws — boolean-only API (#207)', () => {
+    // The v6 API; under #207 this throws so callers migrate to `= true`.
     expect(() => {
+      // @ts-expect-error — see comment above.
+      haltState.debug = {before: true};
+    }).toThrow(/haltState\.debug only accepts boolean/);
+  });
+
+  test('haltState.debug = {before: true, after: true} throws — boolean-only API (#207)', () => {
+    expect(() => {
+      // @ts-expect-error — see comment above.
       haltState.debug = {before: true, after: true};
-    }).toThrow();
+    }).toThrow(/haltState\.debug only accepts boolean/);
+  });
+
+  test('non-halt state.debug = boolean throws — DebugConfig-only on non-halt (#207)', () => {
+    // Symmetric guard: only haltState accepts boolean. Non-halt states must
+    // use the DebugConfig shape so the per-side granularity stays explicit.
+    const s = new State();
+    expect(() => {
+      // @ts-expect-error — non-halt State's debug setter narrows to DebugConfig.
+      s.debug = true;
+    }).toThrow(/Boolean assignment is reserved for `haltState`/);
   });
 });
 
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index b36f83b..1b6fde9 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -216,9 +216,20 @@ export default class TuringMachine {
           // Both before and after refer to THIS iter (#119 / v6.0.0).
           // The halting iter's after-fire just rides along on the iter's
           // own yield — no post-loop drain needed.
-          const beforeMatch = matchFilter(state.debug?.before, symbol)
-            || (nextState.isHalt && nextState.debug?.before === true);
-          const afterMatch = matchFilter(state.debug?.after, symbol);
+          //
+          // #207: `haltState.debug` is now a boolean, and pauses on the
+          // halt-triggering iter's AFTER side (not before). The previous
+          // before-side check (`nextState.debug?.before === true`) was
+          // "early-warning" timing — the user paused before the halt-bound
+          // transition fired, then had to mentally re-derive what would
+          // happen. Now the pause anchors post-step (after the iter's own
+          // after-pause if armed), so consumers see the just-fired halt-
+          // bound transition + diagram cursor still on the triggering state.
+          const debug = state.debug;
+          const stateDebugConfig = typeof debug === 'boolean' ? null : debug;
+          const beforeMatch = matchFilter(stateDebugConfig?.before, symbol);
+          const afterMatch = matchFilter(stateDebugConfig?.after, symbol)
+            || (nextState === haltState && haltState.debug);
 
           const nextStateForYield = nextState.isHalt && stack.length
             ? stack.slice(-1)[0]
diff --git a/test/examples.spec.ts b/test/examples.spec.ts
index 8e56890..192bb8c 100644
--- a/test/examples.spec.ts
+++ b/test/examples.spec.ts
@@ -136,9 +136,9 @@ describe('README.md — Debugging breakpoints', () => {
     expect(order).toEqual(['before', 'after']);
   });
 
-  test('haltState.debug.before pauses on halt entry — fires once at the final visit', async () => {
+  test('haltState.debug = true pauses on halt entry — fires once at the final visit (#207)', async () => {
     const {machine, myState} = buildExampleMachine();
-    haltState.debug = {before: true};
+    haltState.debug = true;
     const haltPauses: Array<{atVisit: number}> = [];
     let visitIx = 0;
 
@@ -146,17 +146,20 @@ describe('README.md — Debugging breakpoints', () => {
       initialState: myState,
       onStep: () => { visitIx += 1; }, // increments before onPause for this visit
       onPause: (m) => {
-        if (m.nextState === haltState && m.debugBreak?.before) {
+        // #207: halt-imminent fires on AFTER side (post-iter, before halt
+        // processing). The triggering iter's `nextState` is haltState, and
+        // `debugBreak.after === true`.
+        if (m.nextState === haltState && m.debugBreak?.after) {
           haltPauses.push({atVisit: visitIx});
         }
       },
     });
 
     expect(haltPauses).toHaveLength(HALT_TRANSITION_COUNT);
-    // Note: per-iter dispatch order is `before → step → after` — onPause for
-    // before fires BEFORE onStep increments visitIx, so the recorded visit
-    // index is one less than the human-readable visit count.
-    expect(haltPauses[0].atVisit).toBe(VISIT_COUNT - 1);
+    // Per-iter dispatch order is `before → step → after` — onStep increments
+    // visitIx during step, then onPause for `after` reads it. The recorded
+    // visit index matches the human-readable visit count.
+    expect(haltPauses[0].atVisit).toBe(VISIT_COUNT);
   });
 
   test('Reset filters by assigning null', () => {

From 58b69f2611923984bfc9afbfed0c0d073a296ee2 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 10:04:06 +0300
Subject: [PATCH 046/118] docs: warn that chained haltState.debug.before
 silently no-ops in non-strict mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The #207 setter only sees whole-object writes; chained-form
`haltState.debug.before = true` reads the boolean (false) and then
assigns `.before` on it — silently no-op in non-strict, TypeError in
strict. Engine can't intercept since the write never reaches the setter.
Doc the gotcha next to the existing boolean-only callout in both the
README and CLAUDE.md.
---
 CLAUDE.md                  | 2 +-
 packages/machine/README.md | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 93b3f6f..5dafc91 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,7 +47,7 @@ Key shapes that take reading multiple files to grasp:
 
 - **`TapeBlock` has a `Lock`** that `TuringMachine.run` grabs for the duration of a run, asserting the block isn't being mutated by another machine. Calls to `applyCommand` from outside a run must pass the matching capture symbol.
 
-- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverriddenHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. Pauses dispatch via the optional `onPause` hook on `run()` (awaited; without the hook, breaks fire-and-resume invisibly). **As of v7 #207, `haltState.debug` is a `boolean`** (not `DebugConfig`) — halt is terminal with one meaningful pause moment (post-triggering-iter, before halt processing). `haltState.debug = true` pauses on every halt entry (program exit + subroutine pop); the pause fires on the AFTER side of the iter whose transition leads to halt (`m.state` is the triggering state, `m.debugBreak.after === true`). Any object-shaped write (`{ before: true }`, `{ after: true }`, etc.) throws at write time. The `HaltState` typed alias on the singleton export narrows `debug` to `boolean` for compile-time safety at the canonical access path. See `packages/machine/README.md` "Debugging breakpoints (v4+)" for the full API.
+- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverriddenHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. Pauses dispatch via the optional `onPause` hook on `run()` (awaited; without the hook, breaks fire-and-resume invisibly). **As of v7 #207, `haltState.debug` is a `boolean`** (not `DebugConfig`) — halt is terminal with one meaningful pause moment (post-triggering-iter, before halt processing). `haltState.debug = true` pauses on every halt entry (program exit + subroutine pop); the pause fires on the AFTER side of the iter whose transition leads to halt (`m.state` is the triggering state, `m.debugBreak.after === true`). Any object-shaped write (`{ before: true }`, `{ after: true }`, etc.) throws at write time. The `HaltState` typed alias on the singleton export narrows `debug` to `boolean` for compile-time safety at the canonical access path. **Chained-form `haltState.debug.before = true` does NOT throw in non-strict mode** — it's a primitive-boolean property assignment, silent in non-strict, `TypeError` in strict; the engine never sees the write so can't intercept. Always use whole-object form. See `packages/machine/README.md` "Debugging breakpoints (v4+)" for the full API.
 
   Cross-version notes:
   - **v5**: hook renamed `onDebugBreak` → `onPause` (#110). `haltState.debug.after = true` (or `{ before, after }` together) now throws at write-time — halt is terminal, no iteration-after-halt to anchor on (#108 part 2). *Superseded in v7 by [#207](https://github.com/mellonis/turing-machine-js/issues/207): `haltState.debug` is now a boolean and ALL object writes throw — the per-side shape never modeled anything for halt.* Halting iter's after-fire stopped being silently lost (#108 part 1). New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without editing `state.debug` assignments (#106).
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 5b07618..f0719d0 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -510,6 +510,8 @@ 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.
 
+> ⚠️ **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`.
 
 `run()` is async and accepts an `onPause` hook:

From 714abd5937ca8e3e0d56603e89261db22eef8184 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 10:18:07 +0300
Subject: [PATCH 047/118] test: cover patternKinds defensive fallbacks; drop
 dead typeof check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two coverage gaps surfaced by Coveralls' check on PR #167 (the v7 → master
release tracker), both introduced incidentally by #205 + #207:

- `TapeBlock.patternKinds` (#205): two defensive `[…literal]` fallbacks
  for unrecognized symbols / no-match cases are public-API entry points
  that engine-internal callers never hit (they always pass a registered
  symbol whose pattern matches the head). Added 4 focused tests covering
  both fallbacks plus the two normal paths.

- `TuringMachine.runStepByStep` (#207): the `typeof debug === 'boolean'`
  branch added defensively was unreachable at runtime — the run loop's
  iter state is always non-halt (halt is terminal and doesn't iterate),
  so `state.debug` is always `DebugConfig`. The public getter's return
  type already matches that. Dropped the typeof check.

Coverage: statements 99.03 → 99.35, branches 96.13 → 96.58, functions
99.05 → 100, lines 99.31 → 99.48. Remaining uncovered lines are all
pre-existing defensive/GC paths.
---
 .../machine/src/classes/TapeBlock.spec.ts     | 48 +++++++++++++++++++
 packages/machine/src/classes/TuringMachine.ts | 11 +++--
 2 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/packages/machine/src/classes/TapeBlock.spec.ts b/packages/machine/src/classes/TapeBlock.spec.ts
index 669198b..0f84289 100644
--- a/packages/machine/src/classes/TapeBlock.spec.ts
+++ b/packages/machine/src/classes/TapeBlock.spec.ts
@@ -418,3 +418,51 @@ describe('TapeBlock.clone', () => {
     expect(clonedSymbol).toBe(original);
   });
 });
+
+describe('TapeBlock.patternKinds (#205)', () => {
+  // Public method (used internally by TuringMachine.runStepByStep to populate
+  // `MachineState.matchedTransition.matchKinds`). Engine-internal callers
+  // always pass a registered symbol whose patternList matches the current
+  // head; the two defensive fallbacks below exist so external callers
+  // (debugger tools, custom dispatchers) get safe "all literal" results
+  // for unrecognized symbols / no-match cases instead of crashing.
+
+  test('ifOtherSymbol returns all `wildcard` (length = tape count)', () => {
+    const a = new Alphabet([' ', 'a', 'b']);
+    const tb = TapeBlock.fromAlphabets([a, a]);
+    expect(tb.patternKinds(ifOtherSymbol)).toEqual(['wildcard', 'wildcard']);
+  });
+
+  test('registered specific-symbol pattern returns per-position kinds', () => {
+    const a = new Alphabet([' ', 'a', 'b']);
+    const tape1 = new Tape({alphabet: a, symbols: ['a']});
+    const tape2 = new Tape({alphabet: a, symbols: ['b']});
+    const tb = TapeBlock.fromTapes([tape1, tape2]);
+    // Mixed-kind pattern: position 0 wildcard, position 1 literal.
+    const sym = tb.symbol([ifOtherSymbol, 'b']);
+    expect(tb.patternKinds(sym)).toEqual(['wildcard', 'literal']);
+  });
+
+  test('unregistered symbol falls back to all `literal`', () => {
+    // Defensive: an alien symbol that was never interned via tb.symbol(...)
+    // should not crash patternKinds — engine-internal callers never pass
+    // such a symbol, but external API callers might.
+    const a = new Alphabet([' ', 'a']);
+    const tb = TapeBlock.fromAlphabets([a, a]);
+    const alien = Symbol('alien');
+    expect(tb.patternKinds(alien)).toEqual(['literal', 'literal']);
+  });
+
+  test('registered symbol with no matching pattern falls back to all `literal`', () => {
+    // Defensive: pass a registered symbol whose pattern doesn't match the
+    // supplied currentSymbols. Pattern is `['a', 'a']`; head is `['b', 'b']`.
+    // Internally unreachable (engine fires the pattern only when head matches),
+    // but exposed via the public method's `currentSymbols` parameter.
+    const a = new Alphabet([' ', 'a', 'b']);
+    const tape1 = new Tape({alphabet: a, symbols: ['a']});
+    const tape2 = new Tape({alphabet: a, symbols: ['a']});
+    const tb = TapeBlock.fromTapes([tape1, tape2]);
+    const sym = tb.symbol(['a', 'a']);
+    expect(tb.patternKinds(sym, ['b', 'b'])).toEqual(['literal', 'literal']);
+  });
+});
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index 1b6fde9..628b00c 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -225,10 +225,13 @@ export default class TuringMachine {
           // happen. Now the pause anchors post-step (after the iter's own
           // after-pause if armed), so consumers see the just-fired halt-
           // bound transition + diagram cursor still on the triggering state.
-          const debug = state.debug;
-          const stateDebugConfig = typeof debug === 'boolean' ? null : debug;
-          const beforeMatch = matchFilter(stateDebugConfig?.before, symbol);
-          const afterMatch = matchFilter(stateDebugConfig?.after, symbol)
+          //
+          // `state` here is always non-halt (halt is terminal — the run
+          // loop never iterates with state === haltState), so `state.debug`
+          // is always `DebugConfig` at runtime. The public getter's return
+          // type matches that.
+          const beforeMatch = matchFilter(state.debug?.before, symbol);
+          const afterMatch = matchFilter(state.debug?.after, symbol)
             || (nextState === haltState && haltState.debug);
 
           const nextStateForYield = nextState.isHalt && stack.length

From 3169542b6554d66a24463998dcab01c2b80a5d1a Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 10:38:52 +0300
Subject: [PATCH 048/118] chore(release): 7.0.0-alpha.5
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fifth v7 pre-release. Adds per-iter MachineState.matchedTransition + .-
separator GraphTransition.id (#205), collapses haltState.debug to a
boolean with halt-imminent pause on the AFTER side of the halt-
triggering iter (#207), and documents the non-strict-mode chained-
write quirk (#209). Internal cleanup raises coverage to 99.35/96.58/
100/99.48 (#210).

- @turing-machine-js/machine: 7.0.0-alpha.4 → 7.0.0-alpha.5
- @turing-machine-js/builder: 7.0.0-alpha.4 → 7.0.0-alpha.5
- @turing-machine-js/library-binary-numbers: 7.0.0-alpha.4 → 7.0.0-alpha.5
- @turing-machine-js/library-binary-numbers-bare: 7.0.0-alpha.4 → 7.0.0-alpha.5

Side packages widen peer dep on @turing-machine-js/machine from
^7.0.0-alpha.4 → ^7.0.0-alpha.5.
---
 lerna.json                                    |  2 +-
 package-lock.json                             | 14 ++++----
 packages/builder/CHANGELOG.md                 |  4 +++
 packages/builder/package.json                 |  4 +--
 .../library-binary-numbers-bare/CHANGELOG.md  |  4 +++
 .../library-binary-numbers-bare/package.json  |  4 +--
 packages/library-binary-numbers/CHANGELOG.md  |  4 +++
 packages/library-binary-numbers/package.json  |  4 +--
 packages/machine/CHANGELOG.md                 | 32 +++++++++++++++++++
 packages/machine/package.json                 |  2 +-
 10 files changed, 59 insertions(+), 15 deletions(-)

diff --git a/lerna.json b/lerna.json
index 32f00eb..6b9d6ee 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.4",
+  "version": "7.0.0-alpha.5",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index 44832f2..3056473 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10656,40 +10656,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.4",
+      "version": "7.0.0-alpha.5",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.3"
+        "@turing-machine-js/machine": "^7.0.0-alpha.4"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.4",
+      "version": "7.0.0-alpha.5",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.3"
+        "@turing-machine-js/machine": "^7.0.0-alpha.4"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.4",
+      "version": "7.0.0-alpha.5",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.3"
+        "@turing-machine-js/machine": "^7.0.0-alpha.4"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.4",
+      "version": "7.0.0-alpha.5",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/builder/CHANGELOG.md b/packages/builder/CHANGELOG.md
index e0b4d57..5a486b3 100644
--- a/packages/builder/CHANGELOG.md
+++ b/packages/builder/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.5 — adds per-iter `MachineState.matchedTransition` + renames `GraphTransition.id` separator `-` → `.` ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` with halt-imminent pause on the AFTER side of the halt-triggering iter ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.4` → `^7.0.0-alpha.5`.
+
 ## [7.0.0-alpha.4] - 2026-05-23
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.4 — adds `State.collectStates` ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), extracts graph serialization into `utilities/stateGraph.ts` ([#180](https://github.com/mellonis/turing-machine-js/issues/180)), fixes `toMermaid` label escape ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and `runStepByStep` halt-stack scope ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4`.
diff --git a/packages/builder/package.json b/packages/builder/package.json
index 043928b..201b681 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.4",
+  "version": "7.0.0-alpha.5",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.4"
+    "@turing-machine-js/machine": "^7.0.0-alpha.5"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/CHANGELOG.md b/packages/library-binary-numbers-bare/CHANGELOG.md
index c7ff61e..8200141 100644
--- a/packages/library-binary-numbers-bare/CHANGELOG.md
+++ b/packages/library-binary-numbers-bare/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.5 — adds per-iter `MachineState.matchedTransition` + renames `GraphTransition.id` separator `-` → `.` ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` with halt-imminent pause on the AFTER side of the halt-triggering iter ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.4` → `^7.0.0-alpha.5`.
+
 ## [7.0.0-alpha.4] - 2026-05-23
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.4 — adds `State.collectStates` ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), extracts graph serialization into `utilities/stateGraph.ts` ([#180](https://github.com/mellonis/turing-machine-js/issues/180)), fixes `toMermaid` label escape ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and `runStepByStep` halt-stack scope ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4`.
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index 9bb71a5..378e8cb 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.4",
+  "version": "7.0.0-alpha.5",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.4"
+    "@turing-machine-js/machine": "^7.0.0-alpha.5"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/CHANGELOG.md b/packages/library-binary-numbers/CHANGELOG.md
index 1855a54..5ce160e 100644
--- a/packages/library-binary-numbers/CHANGELOG.md
+++ b/packages/library-binary-numbers/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.5 — adds per-iter `MachineState.matchedTransition` + renames `GraphTransition.id` separator `-` → `.` ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` with halt-imminent pause on the AFTER side of the halt-triggering iter ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.4` → `^7.0.0-alpha.5`.
+
 ## [7.0.0-alpha.4] - 2026-05-23
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.4 — adds `State.collectStates` ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), extracts graph serialization into `utilities/stateGraph.ts` ([#180](https://github.com/mellonis/turing-machine-js/issues/180)), fixes `toMermaid` label escape ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and `runStepByStep` halt-stack scope ([#196](https://github.com/mellonis/turing-machine-js/issues/196)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.3` → `^7.0.0-alpha.4`.
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index 4e0c508..54c0af6 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.4",
+  "version": "7.0.0-alpha.5",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.4"
+    "@turing-machine-js/machine": "^7.0.0-alpha.5"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index 3803c70..c403e8c 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,38 @@ 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`.
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 505d29f..02619f7 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.4",
+  "version": "7.0.0-alpha.5",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"

From 4838b823c5b93f74a783d8652746787436b431e4 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 10:55:37 +0300
Subject: [PATCH 049/118] test(examples): mirror README's matchedTransition
 example (#205)

---
 test/examples.spec.ts | 51 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/test/examples.spec.ts b/test/examples.spec.ts
index 192bb8c..a34eb6e 100644
--- a/test/examples.spec.ts
+++ b/test/examples.spec.ts
@@ -210,6 +210,57 @@ describe('README.md — Debugging breakpoints', () => {
   });
 });
 
+describe('README.md — Matched transition', () => {
+  test('onStep logs transition id and per-tape wildcard positions (#205)', async () => {
+    const alphabet = new Alphabet([' ', 'a', 'b', 'c', '*']);
+    const tape = new Tape({alphabet, symbols: ['a', 'b', 'c', 'b', 'a']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+
+    // Same fixture as "An example" — patterns declared in this order:
+    //   ix 0: literal 'b'  → write '*', right
+    //   ix 1: literal ' '  → left, halt
+    //   ix 2: ifOtherSymbol → right
+    // Tape walk: a, b, c, b, a, blank → 6 iters total.
+    const initialState = new State({
+      [tapeBlock.symbol(['b'])]: {
+        command: [{symbol: '*', movement: movements.right}],
+      },
+      [tapeBlock.symbol([tape.alphabet.blankSymbol])]: {
+        command: [{movement: movements.left}],
+        nextState: haltState,
+      },
+      [ifOtherSymbol]: {
+        command: [{movement: movements.right}],
+      },
+    });
+
+    const logged: string[] = [];
+
+    // Verbatim from README's "Matched transition" section, with console.log
+    // replaced by capture for assertion.
+    await machine.run({
+      initialState,
+      onStep: (m) => {
+        const wildcardPositions = m.matchedTransition.matchKinds
+          .map((k, i) => k === 'wildcard' ? i : -1)
+          .filter((i) => i >= 0);
+        logged.push(`step ${m.step}: fired transition ${m.matchedTransition.id} (wildcards at tapes: ${wildcardPositions.join(',') || 'none'})`);
+      },
+    });
+
+    const sid = initialState.id;
+    expect(logged).toEqual([
+      `step 1: fired transition ${sid}.2 (wildcards at tapes: 0)`,  // 'a' → ifOther
+      `step 2: fired transition ${sid}.0 (wildcards at tapes: none)`, // 'b' → literal
+      `step 3: fired transition ${sid}.2 (wildcards at tapes: 0)`,  // 'c' → ifOther
+      `step 4: fired transition ${sid}.0 (wildcards at tapes: none)`, // 'b' → literal
+      `step 5: fired transition ${sid}.2 (wildcards at tapes: 0)`,  // 'a' → ifOther
+      `step 6: fired transition ${sid}.1 (wildcards at tapes: none)`, // blank → halt
+    ]);
+  });
+});
+
 // Pin the inline `buildFromTable` helper shown in
 // packages/machine/README.md ("Building from a state table"). The helper is
 // reproduced here verbatim — if it stops compiling or producing the

From 583577c8c40e5a1c2877f181f0495e276d92c5e8 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 12:12:58 +0300
Subject: [PATCH 050/118] docs: trim historical bloat + fix stale
 GraphTransition.id format
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audit pass on source comments. Removes 'was X / pre-#N / previously / v6.0.0
did Y' narratives that belong in commits/PRs/CHANGELOG, not source. Each
trimmed comment now explains only what a current-source reader needs.

Bucket 2 (actively wrong):
- utilities/graph.ts:9-12 — GraphTransition.id JSDoc said
  `${fromNodeId}-${patternIx}`; #205 changed the separator to `.` and
  this file was the last holdout. Also fixed 'Let's' -> 'Lets' typo.
- utilities/graph.spec.ts:145 — dropped reference to retired
  `-. onHalt .->` keyword.

Bucket 1 (historical bloat, trimmed):
- TuringMachine.ts JSDoc + 2 dispatch-comment paragraphs.
- State.ts — 4 spots (#180 extraction history, #138 model superseded,
  #207 'no longer flows' framing, #206 #getEntry refactor history).
- stateGraph.ts — file header extraction story + 'Was ${stateId}-${ix}
  pre-#205' tail.
- TuringMachine.debug.spec.ts — 5 'v6.0.0 / v6 API did X' tails across
  the describe blocks.
- TuringMachine.spec.ts — 3 'pre-#196 left the override' framings
  (regression for #196 is still anchored, just tightened).
- library-binary-numbers/graphs.spec.ts — dropped per-line
  `// alpha.1: 4 (one wohs); +1 wrapper node` deltas; current count
  is the spec.
- State.spec.ts, Reference.spec.ts, equivalence.spec.ts,
  builder.spec.ts, Tape.spec.ts — short pre-test commentary trims.
- introspection.ts — dropped 'Static analysis confirmed' tail.

All 506 tests pass; lint + build clean.
---
 packages/builder/src/builder.spec.ts          |  2 +-
 .../library-binary-numbers/src/graphs.spec.ts | 23 ++++-------
 .../machine/src/classes/Reference.spec.ts     |  6 +--
 packages/machine/src/classes/State.spec.ts    |  8 +---
 packages/machine/src/classes/State.ts         | 20 ++++------
 packages/machine/src/classes/Tape.spec.ts     |  1 -
 .../src/classes/TuringMachine.debug.spec.ts   | 27 +++++--------
 .../machine/src/classes/TuringMachine.spec.ts | 19 ++++-----
 packages/machine/src/classes/TuringMachine.ts | 40 ++++++-------------
 .../machine/src/utilities/equivalence.spec.ts |  6 +--
 packages/machine/src/utilities/graph.spec.ts  |  5 +--
 packages/machine/src/utilities/graph.ts       |  7 ++--
 .../machine/src/utilities/introspection.ts    |  8 ++--
 packages/machine/src/utilities/stateGraph.ts  | 23 ++++-------
 14 files changed, 70 insertions(+), 125 deletions(-)

diff --git a/packages/builder/src/builder.spec.ts b/packages/builder/src/builder.spec.ts
index b1dfb20..554ef07 100644
--- a/packages/builder/src/builder.spec.ts
+++ b/packages/builder/src/builder.spec.ts
@@ -124,7 +124,7 @@ describe('buildMachine — debug config (#101)', () => {
 
   test('debug.after symbol-list fires on the halting iter\'s own yield', async () => {
     // 'B' triggers the halting transition; the after-fire for B reaches
-    // onPause on B's own yield (post-#119 dispatch model).
+    // onPause on B's own yield.
     const [machine, init] = buildLoopMachine({Q0: {after: ['B']}});
     machine.tapeBlock.replaceTape(new Tape({
       alphabet: machine.tapeBlock.alphabets[0],
diff --git a/packages/library-binary-numbers/src/graphs.spec.ts b/packages/library-binary-numbers/src/graphs.spec.ts
index b1ccb6c..71becea 100644
--- a/packages/library-binary-numbers/src/graphs.spec.ts
+++ b/packages/library-binary-numbers/src/graphs.spec.ts
@@ -2,27 +2,20 @@ import {State, fromMermaid, summarizeGraph, toMermaid} from '@turing-machine-js/
 import binaryNumbers from './index';
 
 // Per-state counts pinned from the source comments above each declaration in
-// `index.ts`. These are runtime state counts (per `summarize().stateCount`),
-// which exclude the `isHaltMarker` visualization sentinels v7 synthesizes
-// inside each `halt frame` subgraph. The states.md per-algorithm header uses
-// the same definition, so all three sources agree by construction.
-// v7 callable-subtree counts (#174). Under the new model, each
-// `withOverriddenHaltState` emits a SEPARATE wrapper node (in addition to the
-// bare's node) — so wrapper-bearing algorithms gain 1 node per wrapper, minus
-// any savings from de-duplicating shared bares (no per-context duplication
-// anymore). `goToNumber`, `goToNextNumber`, `goToPreviousNumber`,
-// `goToNumbersStart`, `plusOne` have no wrappers and are unchanged.
+// `index.ts`. Runtime state counts (per `summarize().stateCount`) — excludes
+// `isHaltMarker` visualization sentinels synthesized inside `halt frame`
+// subgraphs. Matches the states.md per-algorithm header by construction.
 const expectedNodeCount: Record<keyof typeof binaryNumbers['states'], number> = {
   goToNumber: 2,
   goToNextNumber: 3,
   goToPreviousNumber: 3,
   goToNumbersStart: 2,
-  deleteNumber: 5, // alpha.1: 4 (one wohs); +1 wrapper node
-  invertNumber: 5, // alpha.1: 4 (one wohs); +1 wrapper node
-  normalizeNumber: 7, // alpha.1: 6 (one wohs); +1 wrapper node
+  deleteNumber: 5,
+  invertNumber: 5,
+  normalizeNumber: 7,
   plusOne: 5,
-  minusOne: 18, // alpha.1: 15; +3 for wrapper-vs-bare separation minus shared-bare dedup
-  minusOneFast: 10, // alpha.1: 8; +2 wrapper nodes
+  minusOne: 18,
+  minusOneFast: 10,
 };
 
 const stateNames = Object.keys(expectedNodeCount) as Array<keyof typeof expectedNodeCount>;
diff --git a/packages/machine/src/classes/Reference.spec.ts b/packages/machine/src/classes/Reference.spec.ts
index ddd1d82..7b36815 100644
--- a/packages/machine/src/classes/Reference.spec.ts
+++ b/packages/machine/src/classes/Reference.spec.ts
@@ -48,10 +48,8 @@ describe('Reference', () => {
     });
 
     test('second bind() returns the EXISTING binding, not the passed argument', () => {
-      // This was the subtle case the previous "Reference bind return the passed
-      // parameter" test under-asserted. The first bind happens to satisfy that
-      // claim, but it's not the contract — the contract is "return the current
-      // binding."
+      // Contract: bind() returns the current binding (set by first bind), not
+      // whatever is passed to subsequent calls.
       const reference = new Reference();
       const first = new State();
       const second = new State();
diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 9b33f1a..5451179 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -105,10 +105,7 @@ describe('State constructor — invalid inputs', () => {
 
 describe('State.getCommand / .getNextState / .getMatchedTransition — error paths', () => {
   // Default-constructed State has an empty symbolToDataMap; any lookup throws.
-  // #206 unified the message across all three methods: the prior per-method
-  // wording ("No command for…" / "No nextState for…") conveyed the same root
-  // cause ("no transition for this symbol") and the public methods now share
-  // a single `#getEntry` helper.
+  // All three accessors share `#getEntry` and so share the unified message.
 
   test('getCommand on an unmapped symbol throws "No transition for symbol at state named …"', () => {
     expect(() => new State().getCommand(ifOtherSymbol))
@@ -140,8 +137,7 @@ describe('State.getSymbol — head resolution', () => {
 
 describe('State.withOverriddenHaltState', () => {
   // The wrapper shares the original's symbolToDataMap and debugRef but adds
-  // an overriddenHaltState. Audit-flagged: the previous test only checked the
-  // name pattern; these tests pin the actual wrapping contract.
+  // an overriddenHaltState. These tests pin the wrapping contract.
 
   test('wrapper exposes the override target', () => {
     const original = new State({[ifOtherSymbol]: {nextState: haltState}});
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index f1667c9..c42508f 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -8,10 +8,9 @@ import {
   decodeMovement,
   decodeWriteSymbol,
 } from '../utilities/graph';
-// Delegate targets for `State.toGraph` / `State.fromGraph` (#180). The
-// import cycle with stateGraph.ts is resolved by ESM live bindings — see
-// the bottom-of-file note in that module. Aliased so the delegating
-// static methods can keep their canonical names without clashing.
+// Aliased so the delegating static methods can keep their canonical names
+// without clashing. The import cycle with stateGraph.ts is resolved by
+// ESM live bindings — see the bottom-of-file note in that module.
 import {
   type StateMap,
   collectStates as collectStatesImpl,
@@ -117,8 +116,8 @@ export default class State {
 
   // For wrapper states (produced by `withOverriddenHaltState`), points at the
   // State whose transition map was wrapped. `null` on bare/atomic states.
-  // Used by `toGraph` to collapse the wrapper-and-its-bare pair into a single
-  // "wrapped bare" graph node — see the v7 emit redesign for #138.
+  // `toGraph` reads this to render wrapper and bare as separate nodes linked
+  // by a `==> call` arrow.
   #bareState: State | null = null;
 
   #symbolToDataMap = new Map<symbol, { command: Command, nextState: State | Reference }>();
@@ -347,9 +346,8 @@ export default class State {
   }
 
   /** @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,
@@ -384,9 +382,7 @@ export default class State {
   // Single lookup + throw site shared by `getCommand`, `getNextState`, and
   // `getMatchedTransition`. Returns the symbol's entry `{command, nextState}`
   // (one map-get, no `.has()` pre-check); throws a unified message when no
-  // entry exists. Before #206, each public method did its own `.has() + .get()!`
-  // double-lookup with a slightly different error string — same root cause
-  // ("no transition for this symbol"), so the message is unified.
+  // entry exists.
   #getEntry(symbol: symbol) {
     const entry = this.#symbolToDataMap.get(symbol);
 
diff --git a/packages/machine/src/classes/Tape.spec.ts b/packages/machine/src/classes/Tape.spec.ts
index 1177071..2228852 100644
--- a/packages/machine/src/classes/Tape.spec.ts
+++ b/packages/machine/src/classes/Tape.spec.ts
@@ -10,7 +10,6 @@ describe('Tape constructor', () => {
   });
 
   test('honors the position parameter', () => {
-    // Pinned position (was Math.random — non-deterministic).
     const alphabet = new Alphabet(['0', '1']);
     const tape = new Tape({alphabet, position: 42});
 
diff --git a/packages/machine/src/classes/TuringMachine.debug.spec.ts b/packages/machine/src/classes/TuringMachine.debug.spec.ts
index a66c51c..81d86c4 100644
--- a/packages/machine/src/classes/TuringMachine.debug.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.debug.spec.ts
@@ -110,9 +110,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
 });
 
 describe('TuringMachine — debug.after filter (loop yields)', () => {
-  // v6.0.0 (#119): both `before` and `after` refer to THIS iter, dispatched
-  // on the same yield. Previously `after` was on the NEXT yield with a
-  // substituted source-state payload — see #109/#119 for the rationale.
+  // Both `before` and `after` refer to THIS iter, dispatched on the same yield.
 
   test('debug.after = true tags every yield with debugBreak.after', async () => {
     const {machine, state} = buildMachine();
@@ -181,9 +179,9 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     }
     const last = steps[VISIT_COUNT - 1];
     expect(last.nextState).toBe(haltState);
-    // #207 timing: fires on AFTER side (post-iter, before halt processing) —
-    // not BEFORE as the v6 API did. `m.state` is the TRIGGERING state (the
-    // one whose transition leads to halt), not haltState itself.
+    // #207 spec: fires on AFTER side (post-iter, before halt processing).
+    // `m.state` is the TRIGGERING state (whose transition leads to halt),
+    // not haltState itself.
     expect(last.state).toBe(state);
     expect(last.debugBreak).toEqual({after: true});
   });
@@ -315,9 +313,8 @@ describe('TuringMachine — run() with onPause', () => {
     });
 
     expect(seen).toHaveLength(VISIT_COUNT);
-    // v6.0.0: the after-call's `m.state` is the iter that armed the after
-    // (no substitution dance — `before` and `after` for the SAME iter both
-    // fire on that iter's own yield).
+    // The after-call's `m.state` is the iter that armed the after; `before`
+    // and `after` for the SAME iter both fire on that iter's own yield.
     for (const entry of seen) {
       expect(entry.state).toBe(state);
       expect(entry.debugBreak).toEqual({after: true});
@@ -337,9 +334,8 @@ describe('TuringMachine — run() with onPause', () => {
       },
     });
 
-    // v6.0.0 per-iter lifecycle: before → step → after. Every yield (including
-    // the first) dispatches both hooks in this order.
-    // For VISIT_COUNT visits, expect: [before, after, before, after, …]
+    // Per-iter lifecycle: before → step → after. Every yield dispatches both
+    // hooks in this order. For VISIT_COUNT visits: [before, after, before, …]
     expect(calls).toHaveLength(VISIT_COUNT * 2);
     for (let i = 0; i < calls.length; i++) {
       expect(calls[i]).toBe(i % 2 === 0 ? 'before' : 'after');
@@ -389,10 +385,8 @@ describe('TuringMachine — halt semantics for after-fire (#108)', () => {
   afterEach(() => { haltState.debug = null; });
 
   test('halting iter still fires its after (#108 part 1)', async () => {
-    // debug.after = true matches every visit. v6.0.0 (#119) dispatches the
-    // halting iter's after directly on its own yield, so all VISIT_COUNT
-    // visits fire (previously only VISIT_COUNT - 1 because the halting iter's
-    // after had no anchor yield).
+    // debug.after = true matches every visit. The halting iter's after
+    // dispatches on its own yield, so all VISIT_COUNT visits fire.
     const {machine, state} = buildMachine();
     state.debug = {after: true};
     const after: MachineState[] = [];
@@ -418,7 +412,6 @@ describe('TuringMachine — halt semantics for after-fire (#108)', () => {
   });
 
   test('haltState.debug = {before: true} throws — boolean-only API (#207)', () => {
-    // The v6 API; under #207 this throws so callers migrate to `= true`.
     expect(() => {
       // @ts-expect-error — see comment above.
       haltState.debug = {before: true};
diff --git a/packages/machine/src/classes/TuringMachine.spec.ts b/packages/machine/src/classes/TuringMachine.spec.ts
index 23f81b3..9bf2630 100644
--- a/packages/machine/src/classes/TuringMachine.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.spec.ts
@@ -320,14 +320,10 @@ describe('TuringMachine constructor', () => {
   });
 });
 
-// Regression tests for #196 — the halt-stack used to be an instance field on
-// TuringMachine that wasn't reset between `runStepByStep` calls, so a caller
-// that peeked at iter 1 via the generator (then disposed it with
-// `generator.return()`) would leave the wrapper's override on the stack;
-// the next `run()` would push it a second time and produce one extra
-// iteration on its way out of the call. Builds a wrapper whose bare halts
-// on blank and whose override also halts immediately — the minimal shape
-// that surfaces the bug.
+// Regression for #196: halt-stack must be run-scoped, not machine-scoped, so
+// a peeked-then-disposed generator doesn't leak a stack entry into the next
+// run. Builds a wrapper whose bare halts on blank and whose override also
+// halts immediately — the minimal shape that surfaces the bug.
 describe('halt-stack reset between calls (regression for #196)', () => {
   // Helper: build a fresh scenario per call so each subtest has independent
   // State/Tape/TapeBlock instances (the engine's symbol patterns are
@@ -360,8 +356,7 @@ describe('halt-stack reset between calls (regression for #196)', () => {
   test('runStepByStep peek + return + run produces no extra iterations', async () => {
     const {machine, initialState, tape} = buildWrapperOverWalkToBlank();
 
-    // Caller peeks at iter 1 then disposes the generator without draining —
-    // pre-#196 this left the override on `#stack`.
+    // Caller peeks at iter 1 then disposes the generator without draining.
     const gen = machine.runStepByStep({initialState});
     gen.next();
     gen.return(undefined);
@@ -413,8 +408,8 @@ describe('halt-stack reset between calls (regression for #196)', () => {
     const tapeBlock = TapeBlock.fromTapes([tape]);
     const machine = new TuringMachine({tapeBlock});
     // A wrapper around a single-iter halt-on-anything bare. Each run pushes
-    // the override; if the pre-#196 leak existed, the second run would see
-    // a stale override and one extra iter.
+    // its own override; a leaking machine-scoped stack would see a stale
+    // override on the second run and produce one extra iter.
     const bare = new State({
       [ifOtherSymbol]: {
         command: [{movement: movements.stay}],
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index 628b00c..ca1ed53 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -97,14 +97,8 @@ export default class TuringMachine {
      * Async hook fired when `state.debug[when]` matches at the current
      * iteration. The promise is awaited inline, so the consumer can suspend
      * execution by deferring its resolution. Use for pause-capable inspection
-     * (debugger UIs, conditional breakpoints in tests).
-     *
-     * Renamed from `onDebugBreak` in v5.0.0. In v6.0.0 the dispatch order
-     * was changed so that `before` and `after` for the SAME iter fire on the
-     * same yield (per-iter lifecycle: before → step → after); previously the
-     * `after` of iter K fired on iter K+1's tick with a substituted source
-     * view. The `m.debugBreak` payload field keeps its name (it describes the
-     * engine's reason for pausing).
+     * (debugger UIs, conditional breakpoints in tests). Per-iter lifecycle:
+     * `before` and `after` for the same iter fire on the same yield.
      */
     onPause?: (machineState: MachineState) => void | Promise<void>;
     /**
@@ -170,13 +164,10 @@ export default class TuringMachine {
       this.#tapeBlock[lockSymbol].lock(executionSymbol);
 
 
-      // Halt-stack is run-scoped, not machine-scoped (#196). Declaring it
-      // local makes that lifetime explicit and prevents leftover entries
-      // from a previous `runStepByStep` call (e.g. a build-time peek that
-      // never drained the generator) from being popped during a subsequent
-      // halt-bound transition. Before this change `#stack` was an instance
-      // field and accumulated one extra push per call when the same machine
-      // was reused.
+      // Halt-stack is run-scoped, not machine-scoped (#196) — local
+      // declaration prevents leftover entries from a previous
+      // `runStepByStep` call (e.g. a build-time peek that never drained
+      // the generator) from leaking into a subsequent halt-bound transition.
       const stack: State[] = [];
       let state = initialState;
 
@@ -217,19 +208,14 @@ export default class TuringMachine {
           // The halting iter's after-fire just rides along on the iter's
           // own yield — no post-loop drain needed.
           //
-          // #207: `haltState.debug` is now a boolean, and pauses on the
-          // halt-triggering iter's AFTER side (not before). The previous
-          // before-side check (`nextState.debug?.before === true`) was
-          // "early-warning" timing — the user paused before the halt-bound
-          // transition fired, then had to mentally re-derive what would
-          // happen. Now the pause anchors post-step (after the iter's own
-          // after-pause if armed), so consumers see the just-fired halt-
-          // bound transition + diagram cursor still on the triggering state.
+          // #207 spec: `haltState.debug` is a boolean; the pause anchors on
+          // the AFTER side of the halt-triggering iter so consumers see the
+          // just-fired transition with the diagram cursor still on the
+          // triggering state.
           //
-          // `state` here is always non-halt (halt is terminal — the run
-          // loop never iterates with state === haltState), so `state.debug`
-          // is always `DebugConfig` at runtime. The public getter's return
-          // type matches that.
+          // `state` here is always non-halt (halt is terminal — the run loop
+          // never iterates with state === haltState), so `state.debug` is
+          // always `DebugConfig` at runtime.
           const beforeMatch = matchFilter(state.debug?.before, symbol);
           const afterMatch = matchFilter(state.debug?.after, symbol)
             || (nextState === haltState && haltState.debug);
diff --git a/packages/machine/src/utilities/equivalence.spec.ts b/packages/machine/src/utilities/equivalence.spec.ts
index 4392509..e17bdff 100644
--- a/packages/machine/src/utilities/equivalence.spec.ts
+++ b/packages/machine/src/utilities/equivalence.spec.ts
@@ -115,10 +115,8 @@ describe('equivalentOn', () => {
   });
 
   test('compareSnapshots: null skips mid-run divergence detection on same alphabet', () => {
-    // Audit gap: the `compareSnapshots: null` branch was exercised only in
-    // cross-alphabet tests. This test pins the same-alphabet contract:
-    // when outputs disagree but compareSnapshots is null, firstDivergenceStep
-    // is null (the engine doesn't probe step-by-step).
+    // When outputs disagree but compareSnapshots is null,
+    // firstDivergenceStep is null (no step-by-step probe).
     const report = equivalentOn(
       {state: binaryNumbers.states.plusOne, getTapeBlock: binaryNumbers.getTapeBlock},
       {state: binaryNumbers.states.minusOne, getTapeBlock: binaryNumbers.getTapeBlock},
diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index a3aeee7..a454820 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -140,9 +140,8 @@ describe('toMermaid', () => {
   });
 
   test('renders wrapper-to-override solid arrow when overriddenHaltStateId is set', () => {
-    // Under the v7 callable-subtree model, wrapper → override is a regular
-    // solid `-->` (the new convention reserves bold/dotted for `call`/`return`/
-    // `halt`). The retired `-. onHalt .->` keyword no longer appears.
+    // Wrapper → override is a regular solid `-->` arrow; bold/dotted styles
+    // are reserved for `call` / `return` / `halt`.
     const out = toMermaid({
       initialId: 1,
       alphabets: [[' ', '0']],
diff --git a/packages/machine/src/utilities/graph.ts b/packages/machine/src/utilities/graph.ts
index 2e414e9..671be5b 100644
--- a/packages/machine/src/utilities/graph.ts
+++ b/packages/machine/src/utilities/graph.ts
@@ -6,10 +6,9 @@ export type GraphTransition = {
   pattern: string;
   command: GraphCommand[];
   nextStateId: number;
-  // Stable, deterministic per-edge identifier. Format: `${fromNodeId}-${patternIx}`
-  // where `patternIx` is the transition's position in the source state's symbol
-  // map. Let's downstream rendering (machines-demo #10) target a specific edge in
-  // the rendered Mermaid SVG to highlight "the edge that will fire next."
+  // Stable per-edge identifier: `${fromNodeId}.${patternIx}` where patternIx
+  // is the transition's position in the source state's symbol map. Lets
+  // downstream rendering target a specific edge in the Mermaid SVG.
   id: string;
 };
 
diff --git a/packages/machine/src/utilities/introspection.ts b/packages/machine/src/utilities/introspection.ts
index 034e11b..7a1146c 100644
--- a/packages/machine/src/utilities/introspection.ts
+++ b/packages/machine/src/utilities/introspection.ts
@@ -101,10 +101,10 @@ export function summarizeGraph(graph: Graph): GraphSummary {
   let hasCycles = false;
 
   const visit = (id: number): void => {
-    // No `if (hasCycles) return` guard at function entry: the recursive call
-    // pattern (outer for-loop checks before calling, inner loop checks after
-    // each recursive call) ensures visit() is never invoked when hasCycles
-    // is already true. Static analysis confirmed the guard was unreachable.
+    // No `if (hasCycles) return` guard at function entry: the call pattern
+    // (outer for-loop checks before calling, inner loop checks after each
+    // recursive call) ensures visit() is never invoked when hasCycles is
+    // already true.
     if (color.get(id) === GREY) {
       hasCycles = true;
       return;
diff --git a/packages/machine/src/utilities/stateGraph.ts b/packages/machine/src/utilities/stateGraph.ts
index db4b58b..8509b4d 100644
--- a/packages/machine/src/utilities/stateGraph.ts
+++ b/packages/machine/src/utilities/stateGraph.ts
@@ -14,16 +14,11 @@ import {
   parseWriteSymbolLabel,
 } from './graph';
 
-// Graph serialization/reconstruction for State graphs. Extracted from
-// `classes/State.ts` (#180) so the State class stays focused on the runtime
-// machinery (transitions, debug, halt-stack composition). Sibling-module
-// private access to State's internals goes through the `STATE_INTERNAL`
+// Graph serialization/reconstruction + state collection for State graphs.
+// Sibling-module access to State's internals uses the `STATE_INTERNAL`
 // Symbol re-exported from State.ts — see the @internal JSDoc there.
-//
-// Public surface is preserved: `State.toGraph` and `State.fromGraph` static
-// methods continue to exist as thin delegates to the functions in this
-// module. New consumers (e.g. #195's planned `collectStates`) will live
-// here too and share the BFS-walk shape with `toGraph`.
+// `State.toGraph` / `.fromGraph` / `.collectStates` static methods on
+// State are thin delegates to functions in this module.
 
 /**
  * Walks the reachable graph from `initialState` and returns a serializable
@@ -142,13 +137,11 @@ export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
           movement: decodeMovement((tc.movement as symbol).description),
         })),
         nextStateId: targetInternal.id,
-        // Transition id format: `${stateId}.${transitionIx}` (#205).
-        // Matches `TuringMachine.runStepByStep`'s `MachineState.
-        // matchedTransition.id` so consumers can do
+        // `${stateId}.${transitionIx}` — matches
+        // `MachineState.matchedTransition.id` so consumers can do
         // `graph.nodes[stateId].transitions.find(t => t.id === id)`.
-        // Was `${stateId}-${ix}` pre-#205 — the `.` separator avoids
-        // the hyphen reading as a minus sign next to negative halt-
-        // marker ids in adjacent contexts.
+        // `.` separator (vs `-`) avoids collision with negative
+        // halt-marker ids.
         id: `${stateInternal.id}.${patternIx}`,
       });
 

From 6f220f118de21532dfdd4a463baefdafa723673f Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:01:34 +0300
Subject: [PATCH 051/118] types: add DebugBreak.cause + internal
 ResumeDirective (#102)

Lifts the inline debugBreak shape on MachineState into a named DebugBreak
type with a required `cause` field ('breakpoint' | 'step' | 'manual') so
the upcoming DebugSession can attribute pauses to their origin without
proliferating new MachineState fields.

ResumeDirective is added as an @internal type for sibling-module use
inside the forthcoming DebugSession; not exported from the public index.

Existing dispatch sites in run()/runStepByStep set cause: 'breakpoint'
(the only origin the engine itself knows about).
---
 .../src/classes/TuringMachine.debug.spec.ts   | 24 +++++-----
 packages/machine/src/classes/TuringMachine.ts | 44 +++++++++++++------
 2 files changed, 42 insertions(+), 26 deletions(-)

diff --git a/packages/machine/src/classes/TuringMachine.debug.spec.ts b/packages/machine/src/classes/TuringMachine.debug.spec.ts
index 81d86c4..dfda34a 100644
--- a/packages/machine/src/classes/TuringMachine.debug.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.debug.spec.ts
@@ -59,7 +59,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
-      expect(step.debugBreak).toEqual({before: true});
+      expect(step.debugBreak).toEqual({before: true, cause: 'breakpoint'});
     }
   });
 
@@ -76,7 +76,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
 
     expect(aVisits).toHaveLength(A_VISIT_COUNT);
     expect(nonAVisits).toHaveLength(VISIT_COUNT - A_VISIT_COUNT);
-    for (const v of aVisits) expect(v.debugBreak).toEqual({before: true});
+    for (const v of aVisits) expect(v.debugBreak).toEqual({before: true, cause: 'breakpoint'});
     for (const v of nonAVisits) expect(v).not.toHaveProperty('debugBreak');
   });
 
@@ -104,7 +104,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
     const nonBlankVisits = steps.filter((s) => s.currentSymbols[0] !== alphabet.blankSymbol);
 
     expect(blankVisits).toHaveLength(HALT_VISIT_COUNT);
-    expect(blankVisits[0].debugBreak).toEqual({before: true});
+    expect(blankVisits[0].debugBreak).toEqual({before: true, cause: 'breakpoint'});
     for (const v of nonBlankVisits) expect(v).not.toHaveProperty('debugBreak');
   });
 });
@@ -121,7 +121,7 @@ describe('TuringMachine — debug.after filter (loop yields)', () => {
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
-      expect(step.debugBreak).toEqual({after: true});
+      expect(step.debugBreak).toEqual({after: true, cause: 'breakpoint'});
     }
   });
 
@@ -134,7 +134,7 @@ describe('TuringMachine — debug.after filter (loop yields)', () => {
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
-      expect(step.debugBreak).toEqual({before: true, after: true});
+      expect(step.debugBreak).toEqual({before: true, after: true, cause: 'breakpoint'});
     }
   });
 
@@ -151,7 +151,7 @@ describe('TuringMachine — debug.after filter (loop yields)', () => {
     const nonAHits = steps.filter((s) => s.currentSymbols[0] !== 'A');
     expect(aHits).toHaveLength(A_VISIT_COUNT);
 
-    for (const step of aHits) expect(step.debugBreak).toEqual({after: true});
+    for (const step of aHits) expect(step.debugBreak).toEqual({after: true, cause: 'breakpoint'});
     for (const step of nonAHits) expect(step).not.toHaveProperty('debugBreak');
   });
 });
@@ -183,7 +183,7 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     // `m.state` is the TRIGGERING state (whose transition leads to halt),
     // not haltState itself.
     expect(last.state).toBe(state);
-    expect(last.debugBreak).toEqual({after: true});
+    expect(last.debugBreak).toEqual({after: true, cause: 'breakpoint'});
   });
 
   test('haltState.debug = true fires on each halt entry — including subroutine return (halt-pop)', async () => {
@@ -229,11 +229,11 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     const popYield = steps.find((s) => s.nextState === continuation);
     expect(popYield).toBeDefined();
     expect(popYield).toBe(steps[1]);
-    expect(popYield!.debugBreak).toEqual({after: true});
+    expect(popYield!.debugBreak).toEqual({after: true, cause: 'breakpoint'});
 
     // Visit 3: transitions to halt directly. `debugBreak.after` fires.
     expect(steps[2].nextState).toBe(haltState);
-    expect(steps[2].debugBreak).toEqual({after: true});
+    expect(steps[2].debugBreak).toEqual({after: true, cause: 'breakpoint'});
   });
 
   test('haltState.debug = false / null suppresses dispatch on every iter', async () => {
@@ -296,7 +296,7 @@ describe('TuringMachine — run() with onPause', () => {
     expect(seen).toHaveLength(VISIT_COUNT);
     for (const entry of seen) {
       expect(entry.state).toBe(state);
-      expect(entry.debugBreak).toEqual({before: true});
+      expect(entry.debugBreak).toEqual({before: true, cause: 'breakpoint'});
     }
   });
 
@@ -317,7 +317,7 @@ describe('TuringMachine — run() with onPause', () => {
     // and `after` for the SAME iter both fire on that iter's own yield.
     for (const entry of seen) {
       expect(entry.state).toBe(state);
-      expect(entry.debugBreak).toEqual({after: true});
+      expect(entry.debugBreak).toEqual({after: true, cause: 'breakpoint'});
     }
   });
 
@@ -520,7 +520,7 @@ describe('TuringMachine — run({debug}) flag (#106)', () => {
     // EVERY yield carries the metadata (wildcard before-filter), even though
     // no onPause fires.
     for (const y of yields) {
-      expect(y.debugBreak).toEqual({before: true});
+      expect(y.debugBreak).toEqual({before: true, cause: 'breakpoint'});
     }
   });
 });
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index ca1ed53..a1103d1 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -4,6 +4,31 @@ import {symbolCommands} from './TapeCommand';
 
 type RunParameter = { initialState: State, stepsLimit?: number };
 
+/**
+ * Set only on iterations whose `MachineState` represents a pause point.
+ * - Side flags: at least one of `before` / `after` is `true`.
+ * - `cause` identifies the pause origin:
+ *   - `'breakpoint'` — a `state.debug[when]` filter or `haltState.debug === true` matched.
+ *   - `'step'` — a DebugSession step-mode endpoint fired (stepIn / stepOver / stepOut).
+ *   - `'manual'` — a `DebugSession.pause()` call fired.
+ *
+ * On `runStepByStep` yields, `cause` is always `'breakpoint'` (the generator only
+ * knows about engine-level breakpoint filters). DebugSession synthesizes `'step'`
+ * and `'manual'` causes when dispatching its `pause` event.
+ */
+export type DebugBreak = {
+  before?: true;
+  after?: true;
+  cause: 'breakpoint' | 'step' | 'manual';
+};
+
+/**
+ * @internal — directive returned from a DebugSession's internal pause coordination
+ * to drive step-mode bookkeeping. NOT part of the public API; exported only for
+ * sibling-module use inside `packages/machine/src/classes/DebugSession.ts`.
+ */
+export type ResumeDirective = 'continue' | 'step-in' | 'step-over' | 'step-out';
+
 export type MachineState = {
   step: number;
   state: State;
@@ -14,18 +39,9 @@ export type MachineState = {
   /**
    * Set only when this iteration is a debug break point.
    * Field is OMITTED entirely when no break fires (no `debugBreak: undefined`).
-   * At least one of `before` / `after` is `true` when the field is present.
-   *
-   * Both flags refer to THIS iter — `before` means the iter's `state.debug.before`
-   * matched, `after` means the iter's `state.debug.after` matched. `run()`
-   * dispatches the two timings as separate `onPause` calls (before-call has
-   * `debugBreak: {before: true}` only; after-call has `debugBreak: {after: true}`
-   * only) so consumers can distinguish without ambiguity.
+   * See `DebugBreak` for the field's shape and `cause` semantics.
    */
-  debugBreak?: {
-    before?: true;
-    after?: true;
-  };
+  debugBreak?: DebugBreak;
   /**
    * The transition the engine picked for this iter (#205). Always present
    * — `runStepByStep` resolves it at the very start of every iter via
@@ -139,7 +155,7 @@ export default class TuringMachine {
       // same yielded MachineState, so the consumer sees a coherent ordering
       // within each iteration without cross-tick coordination.
       if (debug && machineState.debugBreak?.before && onPause) {
-        await onPause({...machineState, debugBreak: {before: true}});
+        await onPause({...machineState, debugBreak: {before: true, cause: 'breakpoint'}});
       }
 
       if (onStep) {
@@ -147,7 +163,7 @@ export default class TuringMachine {
       }
 
       if (debug && machineState.debugBreak?.after && onPause) {
-        await onPause({...machineState, debugBreak: {after: true}});
+        await onPause({...machineState, debugBreak: {after: true, cause: 'breakpoint'}});
       }
 
       if (onIter) {
@@ -248,7 +264,7 @@ export default class TuringMachine {
           };
 
           if (beforeMatch || afterMatch) {
-            const dbg: { before?: true; after?: true } = {};
+            const dbg: DebugBreak = {cause: 'breakpoint'};
             if (beforeMatch) dbg.before = true;
             if (afterMatch) dbg.after = true;
             yielded.debugBreak = dbg;

From 5608c236f21d6baaf5c89f8194f6f632fc919144 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:04:47 +0300
Subject: [PATCH 052/118] feat(engine): MACHINE_STATE_INTERNAL halt-stack
 accessor (#102)

Adds a Symbol-keyed accessor on every yielded MachineState that returns
a frozen pre-iter halt-stack snapshot. The forthcoming DebugSession
consumes this for step-over / step-out endpoint detection without
widening the public MachineState type with stack-frame identities.

The Symbol is exported from TuringMachine for sibling-module use in
packages/machine/src and is intentionally NOT re-exported from the
package's public index. Same pattern as STATE_INTERNAL (#180).

Property is defined with enumerable: false so Object.keys / spread /
toEqual on MachineState behave unchanged for existing consumers.
---
 .../machine/src/classes/DebugSession.spec.ts  | 58 +++++++++++++++++++
 packages/machine/src/classes/TuringMachine.ts | 29 ++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 packages/machine/src/classes/DebugSession.spec.ts

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
new file mode 100644
index 0000000..cf2b742
--- /dev/null
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -0,0 +1,58 @@
+import {describe, it, expect} from 'vitest';
+import Alphabet from './Alphabet';
+import State, {haltState} from './State';
+import Tape from './Tape';
+import TapeBlock from './TapeBlock';
+import TuringMachine, {MACHINE_STATE_INTERNAL, type MachineStateInternal} from './TuringMachine';
+
+// Shared helper: builds a 1-state machine that halts on the first A.
+const buildSimple = () => {
+  const alphabet = new Alphabet(' A'.split(''));
+  const tape = new Tape({alphabet, symbols: ['A']});
+  const tapeBlock = TapeBlock.fromTapes([tape]);
+  const machine = new TuringMachine({tapeBlock});
+  const {symbol} = tapeBlock;
+  const halt = new State({[symbol(['A'])]: {nextState: haltState}});
+  return {machine, halt, tapeBlock};
+};
+
+const readInternal = (m: unknown): MachineStateInternal =>
+  (m as Record<symbol, () => MachineStateInternal>)[MACHINE_STATE_INTERNAL]();
+
+describe('MACHINE_STATE_INTERNAL accessor on yielded MachineState', () => {
+  it('exposes a frozen halt-stack snapshot on every iter', () => {
+    const {machine, halt} = buildSimple();
+    const inner = halt;
+    const outer = inner.withOverriddenHaltState(halt);
+
+    const yields = [...machine.runStepByStep({initialState: outer})];
+
+    expect(yields.length).toBeGreaterThan(0);
+    for (const m of yields) {
+      const internal = readInternal(m);
+      expect(Array.isArray(internal.stack)).toBe(true);
+      expect(Object.isFrozen(internal.stack)).toBe(true);
+    }
+  });
+
+  it("does NOT include the accessor in enumerable spread / toEqual", () => {
+    const {machine, halt} = buildSimple();
+
+    const [m] = [...machine.runStepByStep({initialState: halt})];
+    // Enumerable spread must NOT include the symbol-keyed accessor.
+    expect(Object.keys(m)).not.toContain(MACHINE_STATE_INTERNAL.toString());
+    // toEqual on the visible shape must succeed even though the symbol prop is present.
+    expect(m).toEqual(expect.objectContaining({state: halt, step: 1}));
+  });
+
+  it('captures the PRE-iter stack (snapshot taken before this iter advances)', () => {
+    const {machine, halt} = buildSimple();
+    const outer = halt.withOverriddenHaltState(halt);
+
+    const [first] = [...machine.runStepByStep({initialState: outer})];
+    const internal = readInternal(first);
+    // Iter 1 is inside the wrapper — the wrapper's overriddenHaltState (halt) is on the stack.
+    expect(internal.stack.length).toBe(1);
+    expect(internal.stack[0]).toBe(halt);
+  });
+});
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index a1103d1..3e43fde 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -29,6 +29,25 @@ export type DebugBreak = {
  */
 export type ResumeDirective = 'continue' | 'step-in' | 'step-over' | 'step-out';
 
+/**
+ * @internal — package-private accessor key for `MachineState` instances yielded
+ * by `runStepByStep`. Calling `machineState[MACHINE_STATE_INTERNAL]()` returns a
+ * frozen snapshot of the engine's halt-stack at yield time (BEFORE this iter's
+ * applyCommand / pop / push). Consumed by `DebugSession` for step-over /
+ * step-out endpoint detection without exposing the stack to public API.
+ *
+ * Re-exported from this module so the sibling `DebugSession` module can import
+ * it; intentionally NOT re-exported from the package's public `index.ts` —
+ * downstream consumers shouldn't reach for the stack. Same pattern as
+ * `STATE_INTERNAL` (#180).
+ */
+export const MACHINE_STATE_INTERNAL = Symbol('MachineState.internal');
+
+export type MachineStateInternal = {
+  /** Frozen pre-iter halt-stack snapshot. Consumers must not mutate. */
+  stack: readonly State[];
+};
+
 export type MachineState = {
   step: number;
   state: State;
@@ -270,6 +289,16 @@ export default class TuringMachine {
             yielded.debugBreak = dbg;
           }
 
+          // #102: expose the pre-iter halt-stack to DebugSession via a
+          // Symbol-keyed accessor (non-enumerable so it doesn't leak into
+          // serialization / spread / toEqual). The snapshot is frozen so a
+          // consumer holding a reference can't mutate the engine's stack.
+          const stackSnapshot: readonly State[] = Object.freeze(stack.slice());
+          Object.defineProperty(yielded, MACHINE_STATE_INTERNAL, {
+            value: (): MachineStateInternal => ({stack: stackSnapshot}),
+            enumerable: false,
+          });
+
           yield yielded;
 
           this.#tapeBlock.applyCommand(command, executionSymbol);

From ab9e37c9c0fa1680061376922e2a0079d9d15a89 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:07:19 +0300
Subject: [PATCH 053/118] =?UTF-8?q?feat(engine):=20DebugSession=20skeleton?=
 =?UTF-8?q?=20=E2=80=94=20construct=20+=20start=20+=20halt=20event=20(#102?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the DebugSession class as the new public surface for interactive
debugging. The class is constructed directly with
`new DebugSession(machine, parameter)` — TuringMachine itself stays
minimal and doesn't expose a debugRun() factory, keeping the engine
class focused on execution and matching the existing
STATE_INTERNAL / utilities/* sibling-module pattern.

This commit lands only the skeleton:
- Constructor, on/off event registration, start(), stop().
- halt event fires on natural completion; not when stop() was called.
- start() is single-use — second call throws (construct a fresh
  session to re-run).

Listener return type is `void | Promise<void>` so consumers may register
async listeners, but the session fires them fire-and-forget (matches
Node EventEmitter). Pause/resume coordination is via explicit session
methods rather than listener returns, since the resume signal is
fundamentally external to the listener's call site.

Subsequent commits wire in step, pause, iter events, step controls,
external pause, and throttle.
---
 .../machine/src/classes/DebugSession.spec.ts  |  40 +++++++
 packages/machine/src/classes/DebugSession.ts  | 106 ++++++++++++++++++
 packages/machine/src/index.ts                 |   8 +-
 3 files changed, 153 insertions(+), 1 deletion(-)
 create mode 100644 packages/machine/src/classes/DebugSession.ts

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index cf2b742..c0be7dc 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -4,6 +4,7 @@ import State, {haltState} from './State';
 import Tape from './Tape';
 import TapeBlock from './TapeBlock';
 import TuringMachine, {MACHINE_STATE_INTERNAL, type MachineStateInternal} from './TuringMachine';
+import DebugSession from './DebugSession';
 
 // Shared helper: builds a 1-state machine that halts on the first A.
 const buildSimple = () => {
@@ -56,3 +57,42 @@ describe('MACHINE_STATE_INTERNAL accessor on yielded MachineState', () => {
     expect(internal.stack[0]).toBe(halt);
   });
 });
+
+describe('DebugSession skeleton', () => {
+  it('runs to natural halt and fires the halt listener', async () => {
+    const {machine, halt} = buildSimple();
+    const session = new DebugSession(machine, {initialState: halt});
+    let halted = false;
+    session.on('halt', () => { halted = true; });
+    await session.start();
+    expect(halted).toBe(true);
+  });
+
+  it("doesn't fire halt when stop() is called", async () => {
+    const {machine, halt} = buildSimple();
+    const session = new DebugSession(machine, {initialState: halt});
+    let halted = false;
+    session.on('halt', () => { halted = true; });
+    session.stop();
+    await session.start();
+    expect(halted).toBe(false);
+  });
+
+  it('throws on a second start() call', async () => {
+    const {machine, halt} = buildSimple();
+    const session = new DebugSession(machine, {initialState: halt});
+    await session.start();
+    await expect(session.start()).rejects.toThrow(/already been called/);
+  });
+
+  it('off() removes a previously registered listener', async () => {
+    const {machine, halt} = buildSimple();
+    const session = new DebugSession(machine, {initialState: halt});
+    let fired = 0;
+    const handler = () => { fired += 1; };
+    session.on('halt', handler);
+    session.off('halt', handler);
+    await session.start();
+    expect(fired).toBe(0);
+  });
+});
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
new file mode 100644
index 0000000..645262d
--- /dev/null
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -0,0 +1,106 @@
+import State from './State';
+import TuringMachine, {type MachineState} 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 by event. Listeners may return `void` or `Promise<void>` —
+ * the session calls them fire-and-forget, matching Node's `EventEmitter`
+ * contract: async listeners run to completion on their own, but the session
+ * does NOT await them. Async control flow (pause/resume) is gated by the
+ * session's own resume methods (continue / stepIn / stepOver / stepOut / stop)
+ * rather than listener return values, because the resume signal is fundamentally
+ * external to the listener's call site (UI click, postMessage, timer, etc.).
+ */
+export type DebugSessionListener<E extends DebugSessionEvent> =
+  E extends 'halt'
+    ? () => void | Promise<void>
+    : (machineState: MachineState) => void | Promise<void>;
+
+type ListenerMap = {
+  pause: Array<(m: MachineState) => void | Promise<void>>;
+  step: Array<(m: MachineState) => void | Promise<void>>;
+  iter: Array<(m: MachineState) => void | Promise<void>>;
+  halt: Array<() => 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 {
+  readonly #machine: TuringMachine;
+  readonly #parameter: DebugSessionParameter;
+  readonly #listeners: ListenerMap = {
+    pause: [],
+    step: [],
+    iter: [],
+    halt: [],
+  };
+  #started = false;
+  #stopped = false;
+
+  constructor(machine: TuringMachine, parameter: DebugSessionParameter) {
+    this.#machine = machine;
+    this.#parameter = parameter;
+  }
+
+  on<E extends DebugSessionEvent>(event: E, listener: DebugSessionListener<E>): this {
+    (this.#listeners[event] as Array<DebugSessionListener<E>>).push(listener);
+    return this;
+  }
+
+  off<E extends DebugSessionEvent>(event: E, listener: DebugSessionListener<E>): this {
+    const arr = this.#listeners[event] as Array<DebugSessionListener<E>>;
+    const ix = arr.indexOf(listener);
+    if (ix >= 0) arr.splice(ix, 1);
+    return this;
+  }
+
+  stop(): void {
+    this.#stopped = true;
+  }
+
+  async start(): Promise<void> {
+    if (this.#started) {
+      throw new Error('DebugSession.start() has already been called; construct a fresh session to re-run.');
+    }
+    this.#started = true;
+
+    for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
+      if (this.#stopped) return;
+      // Hooks (step / pause / iter dispatch) wire in here in subsequent tasks.
+      void machineState;
+    }
+
+    if (!this.#stopped) {
+      for (const fn of this.#listeners.halt) {
+        void fn();
+      }
+    }
+  }
+}
diff --git a/packages/machine/src/index.ts b/packages/machine/src/index.ts
index 79386c3..84a3ce6 100644
--- a/packages/machine/src/index.ts
+++ b/packages/machine/src/index.ts
@@ -5,7 +5,13 @@ export { default as State, DebugConfig, haltState, ifOtherSymbol } from './class
 export { default as Tape } from './classes/Tape';
 export { default as TapeBlock } from './classes/TapeBlock';
 export { default as TapeCommand, movements, symbolCommands } from './classes/TapeCommand';
-export { default as TuringMachine, type MachineState } from './classes/TuringMachine';
+export { default as TuringMachine, type MachineState, type DebugBreak } from './classes/TuringMachine';
+export {
+  default as DebugSession,
+  type DebugSessionParameter,
+  type DebugSessionEvent,
+  type DebugSessionListener,
+} from './classes/DebugSession';
 export { type Graph, type GraphNode, type GraphTransition, type GraphCommand } from './utilities/graph';
 export { type StateMap, type StateMapEntry } from './utilities/stateGraph';
 export { toMermaid, fromMermaid } from './utilities/graphFormats';

From 3d504207011fa3d66d2746a36462af242eacc594 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:09:17 +0300
Subject: [PATCH 054/118] feat(DebugSession): step event fires once per iter
 (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 37 +++++++++++++++++++
 packages/machine/src/classes/DebugSession.ts  |  7 +++-
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index c0be7dc..e0852fa 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -4,6 +4,7 @@ import State, {haltState} from './State';
 import Tape from './Tape';
 import TapeBlock from './TapeBlock';
 import TuringMachine, {MACHINE_STATE_INTERNAL, type MachineStateInternal} from './TuringMachine';
+import {movements, symbolCommands} from './TapeCommand';
 import DebugSession from './DebugSession';
 
 // Shared helper: builds a 1-state machine that halts on the first A.
@@ -96,3 +97,39 @@ describe('DebugSession skeleton', () => {
     expect(fired).toBe(0);
   });
 });
+
+// Builds a many-step machine that walks right across the tape until blank.
+const buildWalker = (symbols: string[]) => {
+  const alphabet = new Alphabet(' A'.split(''));
+  const tape = new Tape({alphabet, symbols});
+  const tapeBlock = TapeBlock.fromTapes([tape]);
+  const machine = new TuringMachine({tapeBlock});
+  const {symbol} = tapeBlock;
+  const state: State = new State({
+    [symbol(['A'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}]},
+    [symbol([' '])]: {nextState: haltState},
+  });
+  return {machine, state};
+};
+
+describe('DebugSession: step event', () => {
+  it('emits step once per iter, in iter order', async () => {
+    const {machine, state} = buildWalker(['A', 'A', 'A']);
+    const session = new DebugSession(machine, {initialState: state});
+    const steps: number[] = [];
+    session.on('step', (m) => steps.push(m.step));
+    await session.start();
+    expect(steps).toEqual([1, 2, 3, 4]);  // 3 A-iters + 1 blank-halt iter
+  });
+
+  it('passes the live MachineState to listeners (state field is the current State)', async () => {
+    const {machine, state} = buildWalker(['A']);
+    const session = new DebugSession(machine, {initialState: state});
+    const seen: State[] = [];
+    session.on('step', (m) => seen.push(m.state));
+    await session.start();
+    expect(seen.length).toBe(2);
+    expect(seen[0]).toBe(state);  // iter 1
+    expect(seen[1]).toBe(state);  // iter 2 (blank → halt)
+  });
+});
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 645262d..0fa243f 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -93,8 +93,11 @@ export default class DebugSession {
 
     for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
       if (this.#stopped) return;
-      // Hooks (step / pause / iter dispatch) wire in here in subsequent tasks.
-      void machineState;
+      // step: fires once per iter, after any before-pause and before any after-pause.
+      // Pause / iter dispatch wire in here in subsequent tasks.
+      for (const fn of this.#listeners.step) {
+        void fn(machineState);
+      }
     }
 
     if (!this.#stopped) {

From 98aa7b04259ceacb08c6dd956683d4195d69eb7e Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:13:15 +0300
Subject: [PATCH 055/118] feat(DebugSession): pause event + continue() (#102)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wires the engine's debugBreak filter (state.debug + haltState.debug) into
the session's `pause` event. Each match dispatches the listener and
suspends the loop on an internal Promise; the consumer's
`session.continue()` releases it.

The resolver is installed BEFORE listeners fire so a listener calling
`session.continue()` synchronously sees a live resolver. Multiple
listeners are fired before the await — they all observe the same pause.

`cause: 'breakpoint'` is set for both before- and after-side fires
sourced from a debug filter match. Step / manual causes come in later
tasks.
---
 .../machine/src/classes/DebugSession.spec.ts  | 100 ++++++++++++++++++
 packages/machine/src/classes/DebugSession.ts  |  56 +++++++++-
 2 files changed, 154 insertions(+), 2 deletions(-)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index e0852fa..ca480fe 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -133,3 +133,103 @@ describe('DebugSession: step event', () => {
     expect(seen[1]).toBe(state);  // iter 2 (blank → halt)
   });
 });
+
+describe('DebugSession: pause event + continue()', () => {
+  it('emits pause on debugBreak.before match with cause: breakpoint', async () => {
+    const {machine, state} = buildWalker(['A', 'A']);
+    state.debug = {before: true};
+    const session = new DebugSession(machine, {initialState: state});
+    const pauses: Array<{step: number; before?: true; after?: true; cause: string}> = [];
+    session.on('pause', (m) => {
+      pauses.push({step: m.step, ...m.debugBreak!});
+      session.continue();
+    });
+    await session.start();
+    // Three iters total (iter 1 = A, iter 2 = A, iter 3 = blank → halt);
+    // {before: true} matches every symbol so all three pause.
+    expect(pauses).toEqual([
+      {step: 1, before: true, cause: 'breakpoint'},
+      {step: 2, before: true, cause: 'breakpoint'},
+      {step: 3, before: true, cause: 'breakpoint'},
+    ]);
+  });
+
+  it('emits pause on debugBreak.after match too', async () => {
+    const {machine, state} = buildWalker(['A']);
+    state.debug = {after: true};
+    const session = new DebugSession(machine, {initialState: state});
+    const causes: Array<{side: string; cause: string}> = [];
+    session.on('pause', (m) => {
+      causes.push({
+        side: m.debugBreak!.before ? 'before' : 'after',
+        cause: m.debugBreak!.cause,
+      });
+      session.continue();
+    });
+    await session.start();
+    // Two iters (iter 1 = A, iter 2 = blank → halt); both match after-side filter.
+    expect(causes).toEqual([
+      {side: 'after', cause: 'breakpoint'},
+      {side: 'after', cause: 'breakpoint'},
+    ]);
+  });
+
+  it('blocks the loop until continue() is called (no step fires during a held pause)', async () => {
+    const {machine, state} = buildWalker(['A', 'A']);
+    state.debug = {before: true};
+    const session = new DebugSession(machine, {initialState: state});
+
+    let firstPauseFired = false;
+    let firstPauseResumed = false;
+    let stepsDuringFirstHold = 0;
+
+    session.on('step', () => {
+      if (firstPauseFired && !firstPauseResumed) stepsDuringFirstHold += 1;
+    });
+    session.on('pause', async () => {
+      if (!firstPauseFired) {
+        firstPauseFired = true;
+        await new Promise((r) => setTimeout(r, 10));
+        firstPauseResumed = true;
+      }
+      session.continue();
+    });
+    await session.start();
+    expect(stepsDuringFirstHold).toBe(0);  // pause genuinely blocks the loop
+  });
+
+  it('a synchronous continue() inside the listener releases the pause immediately', async () => {
+    const {machine, state} = buildWalker(['A']);
+    state.debug = {before: true};
+    const session = new DebugSession(machine, {initialState: state});
+    let resumeCalledSync = false;
+    session.on('pause', () => {
+      session.continue();
+      resumeCalledSync = true;
+    });
+    await session.start();
+    expect(resumeCalledSync).toBe(true);
+  });
+
+  it('haltState.debug = true fires pause with after-side breakpoint cause', async () => {
+    const {machine, state} = buildWalker(['A']);
+    haltState.debug = true;
+    try {
+      const session = new DebugSession(machine, {initialState: state});
+      const pauses: Array<{step: number; side: string; cause: string}> = [];
+      session.on('pause', (m) => {
+        pauses.push({
+          step: m.step,
+          side: m.debugBreak!.after ? 'after' : 'before',
+          cause: m.debugBreak!.cause,
+        });
+        session.continue();
+      });
+      await session.start();
+      // Two iters: iter 1 (A), iter 2 (blank → halt). Halt-debug fires on iter 2's after.
+      expect(pauses).toEqual([{step: 2, side: 'after', cause: 'breakpoint'}]);
+    } finally {
+      haltState.debug = false;
+    }
+  });
+});
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 0fa243f..8c1ac8c 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -1,5 +1,5 @@
 import State from './State';
-import TuringMachine, {type MachineState} from './TuringMachine';
+import TuringMachine, {type DebugBreak, type MachineState} from './TuringMachine';
 
 /**
  * Parameters mirror `TuringMachine.runStepByStep` / `run`. DebugSession passes
@@ -63,6 +63,7 @@ export default class DebugSession {
   };
   #started = false;
   #stopped = false;
+  #pauseResolver: (() => void) | null = null;
 
   constructor(machine: TuringMachine, parameter: DebugSessionParameter) {
     this.#machine = machine;
@@ -83,6 +84,44 @@ export default class DebugSession {
 
   stop(): void {
     this.#stopped = true;
+    this.#releasePause();
+  }
+
+  /**
+   * 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 {
+    this.#releasePause();
+  }
+
+  // Release the internal pause-promise. Set #pauseResolver to null BEFORE
+  // calling so a re-entrant resume from inside another listener doesn't
+  // double-fire.
+  #releasePause(): void {
+    const resolver = this.#pauseResolver;
+    if (resolver) {
+      this.#pauseResolver = null;
+      resolver();
+    }
+  }
+
+  /**
+   * Emit a `pause` event with the synthesized debugBreak and await the consumer's
+   * resume signal. Resolver is installed BEFORE listeners fire so a listener
+   * that synchronously calls `session.continue()` (or any other resume method)
+   * sees a live resolver to drop.
+   */
+  async #dispatchPause(machineState: MachineState, debugBreak: DebugBreak): Promise<void> {
+    const paused: MachineState = {...machineState, debugBreak};
+    const pausePromise = new Promise<void>((resolve) => {
+      this.#pauseResolver = resolve;
+    });
+    for (const fn of this.#listeners.pause) {
+      void fn(paused);
+    }
+    await pausePromise;
   }
 
   async start(): Promise<void> {
@@ -93,11 +132,24 @@ export default class DebugSession {
 
     for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
       if (this.#stopped) return;
+
+      const hasBeforeBreakpoint = machineState.debugBreak?.before === true;
+      const hasAfterBreakpoint = machineState.debugBreak?.after === true;
+
+      if (hasBeforeBreakpoint) {
+        await this.#dispatchPause(machineState, {before: true, cause: 'breakpoint'});
+        if (this.#stopped) return;
+      }
+
       // step: fires once per iter, after any before-pause and before any after-pause.
-      // Pause / iter dispatch wire in here in subsequent tasks.
       for (const fn of this.#listeners.step) {
         void fn(machineState);
       }
+
+      if (hasAfterBreakpoint) {
+        await this.#dispatchPause(machineState, {after: true, cause: 'breakpoint'});
+        if (this.#stopped) return;
+      }
     }
 
     if (!this.#stopped) {

From 0bce741fe96bdf8199fd7f01db6b93f84df87c87 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:18:22 +0300
Subject: [PATCH 056/118] feat(DebugSession): stepIn() forces pause on next
 iter (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 37 ++++++++++++++++++-
 packages/machine/src/classes/DebugSession.ts  | 32 ++++++++++++++--
 2 files changed, 63 insertions(+), 6 deletions(-)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index ca480fe..5d2e4c5 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -117,7 +117,7 @@ describe('DebugSession: step event', () => {
     const {machine, state} = buildWalker(['A', 'A', 'A']);
     const session = new DebugSession(machine, {initialState: state});
     const steps: number[] = [];
-    session.on('step', (m) => steps.push(m.step));
+    session.on('step', (m) => { steps.push(m.step); });
     await session.start();
     expect(steps).toEqual([1, 2, 3, 4]);  // 3 A-iters + 1 blank-halt iter
   });
@@ -126,7 +126,7 @@ describe('DebugSession: step event', () => {
     const {machine, state} = buildWalker(['A']);
     const session = new DebugSession(machine, {initialState: state});
     const seen: State[] = [];
-    session.on('step', (m) => seen.push(m.state));
+    session.on('step', (m) => { seen.push(m.state); });
     await session.start();
     expect(seen.length).toBe(2);
     expect(seen[0]).toBe(state);  // iter 1
@@ -211,6 +211,39 @@ describe('DebugSession: pause event + continue()', () => {
     expect(resumeCalledSync).toBe(true);
   });
 
+  it('stepIn() forces a pause on the next iter with cause: step', async () => {
+    // Walker has 'A' symbols that loop; final iter sees blank and halts.
+    // We arm a breakpoint that matches ONLY iter 1, then stepIn from there;
+    // iter 2's pause should fire even though no filter matches.
+    const alphabet = new Alphabet(' AB'.split(''));
+    const tape = new Tape({alphabet, symbols: ['A', 'B']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    const {symbol} = tapeBlock;
+    const state = new State({
+      [symbol(['A'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}]},
+      [symbol(['B'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}]},
+      [symbol([' '])]: {nextState: haltState},
+    });
+    state.debug = {before: [symbol(['A'])]};  // matches iter 1 only (sees 'A' on first iter)
+
+    const session = new DebugSession(machine, {initialState: state});
+    const causes: Array<{step: number; cause: string}> = [];
+    let firstHandled = false;
+    session.on('pause', (m) => {
+      causes.push({step: m.step, cause: m.debugBreak!.cause});
+      if (!firstHandled) {
+        firstHandled = true;
+        session.stepIn();
+      } else {
+        session.continue();
+      }
+    });
+    await session.start();
+    expect(causes[0]).toEqual({step: 1, cause: 'breakpoint'});
+    expect(causes[1]).toEqual({step: 2, cause: 'step'});
+  });
+
   it('haltState.debug = true fires pause with after-side breakpoint cause', async () => {
     const {machine, state} = buildWalker(['A']);
     haltState.debug = true;
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 8c1ac8c..2ea4699 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -1,5 +1,5 @@
 import State from './State';
-import TuringMachine, {type DebugBreak, type MachineState} from './TuringMachine';
+import TuringMachine, {type DebugBreak, type MachineState, type ResumeDirective} from './TuringMachine';
 
 /**
  * Parameters mirror `TuringMachine.runStepByStep` / `run`. DebugSession passes
@@ -64,6 +64,7 @@ export default class DebugSession {
   #started = false;
   #stopped = false;
   #pauseResolver: (() => void) | null = null;
+  #activeStepMode: ResumeDirective | null = null;
 
   constructor(machine: TuringMachine, parameter: DebugSessionParameter) {
     this.#machine = machine;
@@ -93,6 +94,19 @@ export default class DebugSession {
    * state.
    */
   continue(): void {
+    this.#activeStepMode = null;
+    this.#releasePause();
+  }
+
+  /**
+   * 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 {
+    this.#activeStepMode = 'step-in';
     this.#releasePause();
   }
 
@@ -112,8 +126,13 @@ export default class DebugSession {
    * resume signal. Resolver is installed BEFORE listeners fire so a listener
    * that synchronously calls `session.continue()` (or any other resume method)
    * sees a live resolver to drop.
+   *
+   * One-shot rule: any pause dispatch (step-mode endpoint, inner breakpoint,
+   * manual pause) drops the active step-mode BEFORE listeners fire. Listeners
+   * that want to keep stepping must call stepIn/Over/Out from the new pause.
    */
   async #dispatchPause(machineState: MachineState, debugBreak: DebugBreak): Promise<void> {
+    this.#activeStepMode = null;
     const paused: MachineState = {...machineState, debugBreak};
     const pausePromise = new Promise<void>((resolve) => {
       this.#pauseResolver = resolve;
@@ -135,9 +154,14 @@ export default class DebugSession {
 
       const hasBeforeBreakpoint = machineState.debugBreak?.before === true;
       const hasAfterBreakpoint = machineState.debugBreak?.after === true;
-
-      if (hasBeforeBreakpoint) {
-        await this.#dispatchPause(machineState, {before: true, cause: 'breakpoint'});
+      const stepInForcesPause = this.#activeStepMode === 'step-in';
+
+      // Before-side pause: fires if a breakpoint matched OR a step-mode endpoint
+      // is reached. Breakpoint wins on cause when both fire on the same iter.
+      const fireBeforePause = hasBeforeBreakpoint || stepInForcesPause;
+      if (fireBeforePause) {
+        const cause: DebugBreak['cause'] = hasBeforeBreakpoint ? 'breakpoint' : 'step';
+        await this.#dispatchPause(machineState, {before: true, cause});
         if (this.#stopped) return;
       }
 

From dfe98042d13a8d09171110949a8b503335f2aab0 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:20:09 +0300
Subject: [PATCH 057/118] feat(DebugSession): stepOver() with click-time frame
 snapshot (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 68 +++++++++++++++++++
 packages/machine/src/classes/DebugSession.ts  | 55 ++++++++++++++-
 2 files changed, 121 insertions(+), 2 deletions(-)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index 5d2e4c5..f8df265 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -244,6 +244,74 @@ describe('DebugSession: pause event + continue()', () => {
     expect(causes[1]).toEqual({step: 2, cause: 'step'});
   });
 
+  it('stepOver() pauses at the first iter after click-time top-frame is no longer on the stack', async () => {
+    // Setup: outer wrapper around an inner state. Click-time stack at iter 1
+    // (inside outer's bare) contains the wrapper's overriddenHaltState (= halt).
+    // stepOver should run until that frame is gone — which happens at iter 2,
+    // when the inner halts → halt-pop → state advances to halt; iter 2's pause
+    // fires because the stack is now empty.
+    const alphabet = new Alphabet(' A'.split(''));
+    const tape = new Tape({alphabet, symbols: ['A']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    const {symbol} = tapeBlock;
+    const halt = new State({[symbol(['A'])]: {nextState: haltState}, [symbol([' '])]: {nextState: haltState}});
+    const inner = new State({[symbol(['A'])]: {nextState: halt}, [symbol([' '])]: {nextState: halt}});
+    const outer = inner.withOverriddenHaltState(halt);
+    inner.debug = {before: true};
+
+    const session = new DebugSession(machine, {initialState: outer});
+    const pauses: Array<{step: number; cause: string}> = [];
+    let firstHandled = false;
+    session.on('pause', (m) => {
+      pauses.push({step: m.step, cause: m.debugBreak!.cause});
+      if (!firstHandled) {
+        firstHandled = true;
+        session.stepOver();
+      } else {
+        session.continue();
+      }
+    });
+    await session.start();
+    // First pause: iter 1 breakpoint inside outer. Second pause: step endpoint
+    // after the wrapper's frame popped. cause: 'step' confirms it's the
+    // stepOver endpoint, not a stray breakpoint.
+    expect(pauses[0]).toMatchObject({cause: 'breakpoint'});
+    expect(pauses[1]).toMatchObject({cause: 'step'});
+    expect(pauses[1].step).toBeGreaterThan(pauses[0].step);
+  });
+
+  it('stepOver() with empty click-time stack collapses to stepIn (next-iter pause)', async () => {
+    // Top-level walker — no wrappers, no halt-stack entries at iter 1.
+    const alphabet = new Alphabet(' AB'.split(''));
+    const tape = new Tape({alphabet, symbols: ['A', 'B']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    const {symbol} = tapeBlock;
+    const state = new State({
+      [symbol(['A'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}]},
+      [symbol(['B'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}]},
+      [symbol([' '])]: {nextState: haltState},
+    });
+    state.debug = {before: [symbol(['A'])]};  // iter 1 only
+
+    const session = new DebugSession(machine, {initialState: state});
+    const pauseSteps: number[] = [];
+    let firstHandled = false;
+    session.on('pause', (m) => {
+      pauseSteps.push(m.step);
+      if (!firstHandled) {
+        firstHandled = true;
+        session.stepOver();
+      } else {
+        session.continue();
+      }
+    });
+    await session.start();
+    expect(pauseSteps[0]).toBe(1);
+    expect(pauseSteps[1]).toBe(2);  // next iter — exactly stepIn semantics
+  });
+
   it('haltState.debug = true fires pause with after-side breakpoint cause', async () => {
     const {machine, state} = buildWalker(['A']);
     haltState.debug = true;
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 2ea4699..c426e4b 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -1,5 +1,5 @@
 import State from './State';
-import TuringMachine, {type DebugBreak, type MachineState, type ResumeDirective} from './TuringMachine';
+import TuringMachine, {MACHINE_STATE_INTERNAL, type DebugBreak, type MachineState, type MachineStateInternal, type ResumeDirective} from './TuringMachine';
 
 /**
  * Parameters mirror `TuringMachine.runStepByStep` / `run`. DebugSession passes
@@ -65,6 +65,19 @@ export default class DebugSession {
   #stopped = false;
   #pauseResolver: (() => void) | null = null;
   #activeStepMode: ResumeDirective | null = null;
+  /**
+   * Top of the halt-stack snapshotted at the most recent pause dispatch. Used by
+   * stepOver / stepOut to recognize their natural endpoint (the click-time
+   * frame is no longer on the stack). `null` when the click-time stack was
+   * empty.
+   */
+  #capturedTopFrame: State | null = null;
+  /**
+   * The click-time top-frame frozen at the moment a step-over / step-out
+   * directive was issued. Distinct from `#capturedTopFrame` (which tracks
+   * EVERY pause); this one only updates when stepOver / stepOut accepts.
+   */
+  #clickTimeTopFrame: State | null = null;
 
   constructor(machine: TuringMachine, parameter: DebugSessionParameter) {
     this.#machine = machine;
@@ -107,6 +120,21 @@ export default class DebugSession {
    */
   stepIn(): void {
     this.#activeStepMode = 'step-in';
+    this.#clickTimeTopFrame = null;
+    this.#releasePause();
+  }
+
+  /**
+   * Resume and run until the click-time top halt-frame is no longer on the
+   * stack, then pause at the first iter past that point. With an empty
+   * click-time stack, collapses to `stepIn` (pause at next iter).
+   *
+   * One-shot: an inner breakpoint or any other pause drops the step-over
+   * intent. The endpoint pause carries `cause: 'step'`.
+   */
+  stepOver(): void {
+    this.#activeStepMode = 'step-over';
+    this.#clickTimeTopFrame = this.#capturedTopFrame;
     this.#releasePause();
   }
 
@@ -130,9 +158,17 @@ export default class DebugSession {
    * One-shot rule: any pause dispatch (step-mode endpoint, inner breakpoint,
    * manual pause) drops the active step-mode BEFORE listeners fire. Listeners
    * that want to keep stepping must call stepIn/Over/Out from the new pause.
+   *
+   * The pre-iter halt-stack top is snapshotted into `#capturedTopFrame` so a
+   * `stepOver` / `stepOut` issued from inside the listener can freeze it as
+   * the click-time frame.
    */
   async #dispatchPause(machineState: MachineState, debugBreak: DebugBreak): Promise<void> {
     this.#activeStepMode = null;
+    this.#clickTimeTopFrame = null;
+    const stack = this.#readStack(machineState);
+    this.#capturedTopFrame = stack.length > 0 ? stack[stack.length - 1] : null;
+
     const paused: MachineState = {...machineState, debugBreak};
     const pausePromise = new Promise<void>((resolve) => {
       this.#pauseResolver = resolve;
@@ -143,6 +179,15 @@ export default class DebugSession {
     await pausePromise;
   }
 
+  // Reads the pre-iter halt-stack snapshot installed by `runStepByStep`.
+  // Returns empty if the accessor is missing (defensive — shouldn't happen
+  // with the engine on this branch).
+  #readStack(machineState: MachineState): readonly State[] {
+    const fn = (machineState as unknown as Record<symbol, () => MachineStateInternal>)[MACHINE_STATE_INTERNAL];
+    if (typeof fn !== 'function') return [];
+    return fn().stack;
+  }
+
   async start(): Promise<void> {
     if (this.#started) {
       throw new Error('DebugSession.start() has already been called; construct a fresh session to re-run.');
@@ -155,10 +200,16 @@ export default class DebugSession {
       const hasBeforeBreakpoint = machineState.debugBreak?.before === true;
       const hasAfterBreakpoint = machineState.debugBreak?.after === true;
       const stepInForcesPause = this.#activeStepMode === 'step-in';
+      const stepOverEndpointReached =
+        this.#activeStepMode === 'step-over'
+        && (
+          this.#clickTimeTopFrame === null  // empty click-time stack — collapse to stepIn
+          || !this.#readStack(machineState).includes(this.#clickTimeTopFrame)
+        );
 
       // Before-side pause: fires if a breakpoint matched OR a step-mode endpoint
       // is reached. Breakpoint wins on cause when both fire on the same iter.
-      const fireBeforePause = hasBeforeBreakpoint || stepInForcesPause;
+      const fireBeforePause = hasBeforeBreakpoint || stepInForcesPause || stepOverEndpointReached;
       if (fireBeforePause) {
         const cause: DebugBreak['cause'] = hasBeforeBreakpoint ? 'breakpoint' : 'step';
         await this.#dispatchPause(machineState, {before: true, cause});

From c884068cc99af047eb358f4f46f23c2e56bb25f6 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:22:29 +0300
Subject: [PATCH 058/118] feat(DebugSession): stepOut() + empty-stack guard
 (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 57 +++++++++++++++++++
 packages/machine/src/classes/DebugSession.ts  | 28 ++++++++-
 2 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index f8df265..213cc94 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -312,6 +312,63 @@ describe('DebugSession: pause event + continue()', () => {
     expect(pauseSteps[1]).toBe(2);  // next iter — exactly stepIn semantics
   });
 
+  it('stepOut() pauses at the first iter after the click-time top-frame is popped', async () => {
+    const alphabet = new Alphabet(' A'.split(''));
+    const tape = new Tape({alphabet, symbols: ['A']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    const {symbol} = tapeBlock;
+    const halt = new State({[symbol(['A'])]: {nextState: haltState}, [symbol([' '])]: {nextState: haltState}});
+    const inner = new State({[symbol(['A'])]: {nextState: halt}, [symbol([' '])]: {nextState: halt}});
+    const outer = inner.withOverriddenHaltState(halt);
+    inner.debug = {before: true};
+
+    const session = new DebugSession(machine, {initialState: outer});
+    const pauses: Array<{step: number; cause: string}> = [];
+    let firstHandled = false;
+    session.on('pause', (m) => {
+      pauses.push({step: m.step, cause: m.debugBreak!.cause});
+      if (!firstHandled) {
+        firstHandled = true;
+        session.stepOut();
+      } else {
+        session.continue();
+      }
+    });
+    await session.start();
+    expect(pauses[0]).toMatchObject({cause: 'breakpoint'});
+    expect(pauses[1]).toMatchObject({cause: 'step'});
+    expect(pauses[1].step).toBeGreaterThan(pauses[0].step);
+  });
+
+  it('stepOut() with empty click-time stack throws', async () => {
+    // Top-level machine, no wrappers — paused state has empty halt-stack.
+    const alphabet = new Alphabet(' A'.split(''));
+    const tape = new Tape({alphabet, symbols: ['A']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    const {symbol} = tapeBlock;
+    const state = new State({
+      [symbol(['A'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}]},
+      [symbol([' '])]: {nextState: haltState},
+    });
+    state.debug = {before: true};
+
+    const session = new DebugSession(machine, {initialState: state});
+    const errors: unknown[] = [];
+    session.on('pause', () => {
+      try {
+        session.stepOut();
+      } catch (e) {
+        errors.push(e);
+        session.continue();
+      }
+    });
+    await session.start();
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect((errors[0] as Error).message).toMatch(/stepOut.*empty/);
+  });
+
   it('haltState.debug = true fires pause with after-side breakpoint cause', async () => {
     const {machine, state} = buildWalker(['A']);
     haltState.debug = true;
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index c426e4b..12151b5 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -138,6 +138,27 @@ export default class DebugSession {
     this.#releasePause();
   }
 
+  /**
+   * Resume and run until the click-time top halt-frame is popped, then pause
+   * at the next iter. Endpoint predicate is the same as stepOver; the
+   * difference is the empty-stack contract:
+   *   - stepOver: empty click-time stack → collapse to stepIn.
+   *   - stepOut: empty click-time stack → throw (no enclosing frame to exit).
+   *
+   * Matches IDE convention: "step out of nothing" is a programming error,
+   * not a silent no-op.
+   */
+  stepOut(): void {
+    if (this.#capturedTopFrame === null) {
+      throw new Error(
+        'DebugSession.stepOut() called with an empty click-time halt-stack — there is no enclosing frame to exit.',
+      );
+    }
+    this.#activeStepMode = 'step-out';
+    this.#clickTimeTopFrame = this.#capturedTopFrame;
+    this.#releasePause();
+  }
+
   // Release the internal pause-promise. Set #pauseResolver to null BEFORE
   // calling so a re-entrant resume from inside another listener doesn't
   // double-fire.
@@ -206,10 +227,15 @@ export default class DebugSession {
           this.#clickTimeTopFrame === null  // empty click-time stack — collapse to stepIn
           || !this.#readStack(machineState).includes(this.#clickTimeTopFrame)
         );
+      const stepOutEndpointReached =
+        this.#activeStepMode === 'step-out'
+        && this.#clickTimeTopFrame !== null
+        && !this.#readStack(machineState).includes(this.#clickTimeTopFrame);
 
       // Before-side pause: fires if a breakpoint matched OR a step-mode endpoint
       // is reached. Breakpoint wins on cause when both fire on the same iter.
-      const fireBeforePause = hasBeforeBreakpoint || stepInForcesPause || stepOverEndpointReached;
+      const fireBeforePause =
+        hasBeforeBreakpoint || stepInForcesPause || stepOverEndpointReached || stepOutEndpointReached;
       if (fireBeforePause) {
         const cause: DebugBreak['cause'] = hasBeforeBreakpoint ? 'breakpoint' : 'step';
         await this.#dispatchPause(machineState, {before: true, cause});

From 6ad98bb1095eb594d7a4da7395134f48a9ce3827 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:23:33 +0300
Subject: [PATCH 059/118] test(DebugSession): lock in one-shot step-mode rule
 (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index 213cc94..824c4ae 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -369,6 +369,49 @@ describe('DebugSession: pause event + continue()', () => {
     expect((errors[0] as Error).message).toMatch(/stepOut.*empty/);
   });
 
+  it('one-shot rule: an inner breakpoint dropped the active step-mode (no phantom endpoint)', async () => {
+    // Scenario: wrapper around inner with one breakpoint on the WRAPPER's bare
+    // and another on the inner state's halt path. User issues stepOver from
+    // the wrapper's bare pause; the inner breakpoint fires next as a
+    // 'breakpoint' cause, not as a 'step' endpoint.
+    const alphabet = new Alphabet(' AB'.split(''));
+    const tape = new Tape({alphabet, symbols: ['A', 'B']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+    const {symbol} = tapeBlock;
+
+    const halt = new State({
+      [symbol(['A'])]: {nextState: haltState},
+      [symbol(['B'])]: {nextState: haltState},
+      [symbol([' '])]: {nextState: haltState},
+    });
+    const inner = new State({
+      [symbol(['A'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}], nextState: halt},
+      [symbol(['B'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}], nextState: halt},
+      [symbol([' '])]: {nextState: halt},
+    });
+    const outer = inner.withOverriddenHaltState(halt);
+    inner.debug = {before: [symbol(['A'])]};   // matches iter 1
+    halt.debug = {before: true};               // matches when control reaches halt's pre-iter
+
+    const session = new DebugSession(machine, {initialState: outer});
+    const causes: string[] = [];
+    let firstHandled = false;
+    session.on('pause', (m) => {
+      causes.push(m.debugBreak!.cause);
+      if (!firstHandled) {
+        firstHandled = true;
+        session.stepOver();
+      } else {
+        session.continue();
+      }
+    });
+    await session.start();
+    expect(causes[0]).toBe('breakpoint');
+    expect(causes[1]).toBe('breakpoint');  // NOT 'step' — the inner breakpoint dropped stepOver
+    expect(causes.every((c) => c === 'breakpoint')).toBe(true);
+  });
+
   it('haltState.debug = true fires pause with after-side breakpoint cause', async () => {
     const {machine, state} = buildWalker(['A']);
     haltState.debug = true;

From 842b4d8aa5973c08c69ccf0b657ebc0984b007f2 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:24:40 +0300
Subject: [PATCH 060/118] feat(DebugSession): iter event + setRunInterval
 throttle (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 35 +++++++++++++++++++
 packages/machine/src/classes/DebugSession.ts  | 27 ++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index 824c4ae..c7f3128 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -412,6 +412,41 @@ describe('DebugSession: pause event + continue()', () => {
     expect(causes.every((c) => c === 'breakpoint')).toBe(true);
   });
 
+  it('iter event fires once at end of every iter, after step + after-pause', async () => {
+    const {machine, state} = buildWalker(['A', 'A']);
+    state.debug = {after: true};
+    const session = new DebugSession(machine, {initialState: state});
+    const order: string[] = [];
+    session.on('step', (m) => { order.push(`step-${m.step}`); });
+    session.on('pause', (m) => {
+      order.push(`pause-${m.step}-${m.debugBreak!.after ? 'after' : 'before'}`);
+      session.continue();
+    });
+    session.on('iter', (m) => { order.push(`iter-${m.step}`); });
+    await session.start();
+    // Iter 1 (A): step, then after-pause, then iter.
+    expect(order.slice(0, 3)).toEqual(['step-1', 'pause-1-after', 'iter-1']);
+  });
+
+  it('setRunInterval(ms) inserts a delay at end of each iter', async () => {
+    const {machine, state} = buildWalker(['A', 'A']);
+    const session = new DebugSession(machine, {initialState: state});
+    session.setRunInterval(5);
+    const start = Date.now();
+    await session.start();
+    const elapsed = Date.now() - start;
+    // 3 iters total (2 A's + 1 blank-halt); 3 throttle waits of 5ms each ≥ 15ms.
+    expect(elapsed).toBeGreaterThanOrEqual(10);
+  });
+
+  it('setRunInterval rejects negative / NaN / Infinity', () => {
+    const {machine, halt} = buildSimple();
+    const session = new DebugSession(machine, {initialState: halt});
+    expect(() => session.setRunInterval(-1)).toThrow();
+    expect(() => session.setRunInterval(NaN)).toThrow();
+    expect(() => session.setRunInterval(Infinity)).toThrow();
+  });
+
   it('haltState.debug = true fires pause with after-side breakpoint cause', async () => {
     const {machine, state} = buildWalker(['A']);
     haltState.debug = true;
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 12151b5..a7935dd 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -78,6 +78,7 @@ export default class DebugSession {
    * EVERY pause); this one only updates when stepOver / stepOut accepts.
    */
   #clickTimeTopFrame: State | null = null;
+  #runIntervalMs = 0;
 
   constructor(machine: TuringMachine, parameter: DebugSessionParameter) {
     this.#machine = machine;
@@ -101,6 +102,22 @@ export default class DebugSession {
     this.#releasePause();
   }
 
+  /**
+   * 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 {
+    if (!Number.isFinite(ms) || ms < 0) {
+      throw new Error(`DebugSession.setRunInterval(${ms}): expected a non-negative finite number.`);
+    }
+    this.#runIntervalMs = ms;
+  }
+
   /**
    * Resume from the current pause, returning to normal execution until the
    * next breakpoint or natural halt. No-op when called outside of a paused
@@ -251,6 +268,16 @@ export default class DebugSession {
         await this.#dispatchPause(machineState, {after: true, cause: 'breakpoint'});
         if (this.#stopped) return;
       }
+
+      // iter: end-of-iter, after both before- and after-pause have fired.
+      for (const fn of this.#listeners.iter) {
+        void fn(machineState);
+      }
+
+      if (this.#runIntervalMs > 0) {
+        await new Promise<void>((resolve) => setTimeout(resolve, this.#runIntervalMs));
+        if (this.#stopped) return;
+      }
     }
 
     if (!this.#stopped) {

From 83b034a11699a669779030e1cd4d99d2e9c48c83 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:26:11 +0300
Subject: [PATCH 061/118] feat(DebugSession): external pause() with cause:
 manual (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 39 +++++++++++++++++++
 packages/machine/src/classes/DebugSession.ts  | 31 +++++++++++++--
 2 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index c7f3128..4f08ec2 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -447,6 +447,45 @@ describe('DebugSession: pause event + continue()', () => {
     expect(() => session.setRunInterval(Infinity)).toThrow();
   });
 
+  it('external pause() fires a pause on next iter with cause: manual', async () => {
+    const {machine, state} = buildWalker(['A', 'A', 'A']);
+    const session = new DebugSession(machine, {initialState: state});
+    session.setRunInterval(2);  // slow enough that we can pause externally
+
+    let pauseRequestedOnce = false;
+    const causes: string[] = [];
+    session.on('iter', (m) => {
+      // Trigger pause from outside on iter 1 (before iter 2 runs).
+      if (m.step === 1 && !pauseRequestedOnce) {
+        pauseRequestedOnce = true;
+        session.pause();
+      }
+    });
+    session.on('pause', (m) => {
+      causes.push(m.debugBreak!.cause);
+      session.continue();
+    });
+    await session.start();
+    expect(causes).toEqual(['manual']);
+  });
+
+  it('breakpoint takes precedence over manual when both pending on same iter', async () => {
+    const {machine, state} = buildWalker(['A']);
+    state.debug = {before: true};
+    const session = new DebugSession(machine, {initialState: state});
+
+    let observedCause: string | undefined;
+    // Set pause request BEFORE starting; iter 1 has both a breakpoint match
+    // and a pending manual request. The breakpoint cause wins.
+    session.pause();
+    session.on('pause', (m) => {
+      observedCause = observedCause ?? m.debugBreak!.cause;
+      session.continue();
+    });
+    await session.start();
+    expect(observedCause).toBe('breakpoint');
+  });
+
   it('haltState.debug = true fires pause with after-side breakpoint cause', async () => {
     const {machine, state} = buildWalker(['A']);
     haltState.debug = true;
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index a7935dd..7cab468 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -79,6 +79,7 @@ export default class DebugSession {
    */
   #clickTimeTopFrame: State | null = null;
   #runIntervalMs = 0;
+  #pauseRequested = false;
 
   constructor(machine: TuringMachine, parameter: DebugSessionParameter) {
     this.#machine = machine;
@@ -102,6 +103,20 @@ export default class DebugSession {
     this.#releasePause();
   }
 
+  /**
+   * 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 {
+    this.#pauseRequested = true;
+  }
+
   /**
    * Set the per-iter throttle delay in milliseconds. After each iter (including
    * any pause + step + iter listeners on that iter), the loop awaits
@@ -248,13 +263,21 @@ export default class DebugSession {
         this.#activeStepMode === 'step-out'
         && this.#clickTimeTopFrame !== null
         && !this.#readStack(machineState).includes(this.#clickTimeTopFrame);
+      // Consume the manual-pause flag at iter start. If a breakpoint also
+      // matches this iter, the request is silently consumed by the
+      // breakpoint dispatch (one pause, cause: 'breakpoint').
+      const manualPauseFires = this.#pauseRequested;
+      if (manualPauseFires) this.#pauseRequested = false;
 
-      // Before-side pause: fires if a breakpoint matched OR a step-mode endpoint
-      // is reached. Breakpoint wins on cause when both fire on the same iter.
+      // Before-side pause: fires if any of breakpoint / step-mode endpoint /
+      // manual request is true. Precedence: breakpoint > step > manual.
       const fireBeforePause =
-        hasBeforeBreakpoint || stepInForcesPause || stepOverEndpointReached || stepOutEndpointReached;
+        hasBeforeBreakpoint || stepInForcesPause || stepOverEndpointReached || stepOutEndpointReached || manualPauseFires;
       if (fireBeforePause) {
-        const cause: DebugBreak['cause'] = hasBeforeBreakpoint ? 'breakpoint' : 'step';
+        const cause: DebugBreak['cause'] =
+          hasBeforeBreakpoint ? 'breakpoint'
+            : (stepInForcesPause || stepOverEndpointReached || stepOutEndpointReached) ? 'step'
+              : 'manual';
         await this.#dispatchPause(machineState, {before: true, cause});
         if (this.#stopped) return;
       }

From 37f6b8178156278447aa2c84448b57e3bef9124a Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:27:52 +0300
Subject: [PATCH 062/118] test(DebugSession): cross-cutting + stop /
 multi-listener / no-op resume (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index 4f08ec2..62b1e8d 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -469,6 +469,58 @@ describe('DebugSession: pause event + continue()', () => {
     expect(causes).toEqual(['manual']);
   });
 
+  it('stop() called from inside an iter listener terminates without firing halt', async () => {
+    const {machine, state} = buildWalker(['A', 'A', 'A', 'A']);
+    const session = new DebugSession(machine, {initialState: state});
+    let haltFired = false;
+    const iters: number[] = [];
+    session.on('iter', (m) => {
+      iters.push(m.step);
+      if (m.step === 2) session.stop();
+    });
+    session.on('halt', () => { haltFired = true; });
+    await session.start();
+    expect(haltFired).toBe(false);
+    expect(iters).toEqual([1, 2]);  // stop took effect at end of iter 2
+  });
+
+  it('stop() called from inside a pause listener terminates immediately', async () => {
+    const {machine, state} = buildWalker(['A', 'A']);
+    state.debug = {before: true};
+    const session = new DebugSession(machine, {initialState: state});
+    let haltFired = false;
+    let pauseCount = 0;
+    session.on('pause', () => {
+      pauseCount += 1;
+      session.stop();
+    });
+    session.on('halt', () => { haltFired = true; });
+    await session.start();
+    expect(haltFired).toBe(false);
+    expect(pauseCount).toBe(1);
+  });
+
+  it('multiple listeners on the same event all fire', async () => {
+    const {machine, halt} = buildSimple();
+    const session = new DebugSession(machine, {initialState: halt});
+    let countA = 0;
+    let countB = 0;
+    session.on('step', () => { countA += 1; });
+    session.on('step', () => { countB += 1; });
+    await session.start();
+    expect(countA).toBe(1);
+    expect(countB).toBe(1);
+  });
+
+  it('continue() / stepIn() / stepOver() are no-op when no pause is active', () => {
+    const {machine, halt} = buildSimple();
+    const session = new DebugSession(machine, {initialState: halt});
+    // No pause active — these must not throw.
+    expect(() => session.continue()).not.toThrow();
+    expect(() => session.stepIn()).not.toThrow();
+    expect(() => session.stepOver()).not.toThrow();
+  });
+
   it('breakpoint takes precedence over manual when both pending on same iter', async () => {
     const {machine, state} = buildWalker(['A']);
     state.debug = {before: true};

From 83c0bc02ed1f66c21819003606eb664165daa929 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:40:59 +0300
Subject: [PATCH 063/118] refactor(engine): run() is sync + callback-free;
 migrate tests to DebugSession / runStepByStep (#102)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removes the v6 `run({onPause, onStep, onIter, debug})` shape. `run()` is
now synchronous, takes only `{initialState, stepsLimit?}`, and returns
`void`. Symmetric reversal of the v4-era `run` → `async run` change,
since `onPause` / `onIter` (the awaited callbacks that motivated async)
have moved into `DebugSession`.

Cross-package test migration:
- Observation-only `run({onStep})` → iterate `runStepByStep` directly.
- Breakpoint dispatch `run({onPause})` → DebugSession + pause listener.
- v6 `debug: false` master-switch tests → removed (gone in v7); replaced
  with equivalent runStepByStep observation, which already shows that
  yielded MachineState carries debugBreak metadata regardless of how a
  consumer dispatches on it.

Public API now exposes three non-overlapping entry points on
TuringMachine: `run` (pure execution), `runStepByStep` (sync per-iter
observation generator), and — separately constructed — `DebugSession`
for interactive debugging.
---
 packages/builder/src/builder.spec.ts          |  30 +--
 .../src/classes/TuringMachine.debug.spec.ts   | 212 +++++++-----------
 .../TuringMachine.matchedTransition.spec.ts   |  14 +-
 .../machine/src/classes/TuringMachine.spec.ts | 168 +++++---------
 packages/machine/src/classes/TuringMachine.ts |  98 ++------
 test/examples.spec.ts                         |  78 +++----
 6 files changed, 220 insertions(+), 380 deletions(-)

diff --git a/packages/builder/src/builder.spec.ts b/packages/builder/src/builder.spec.ts
index 554ef07..fc7cac2 100644
--- a/packages/builder/src/builder.spec.ts
+++ b/packages/builder/src/builder.spec.ts
@@ -1,4 +1,4 @@
-import {haltState, Tape} from '@turing-machine-js/machine';
+import {DebugSession, haltState, Tape} from '@turing-machine-js/machine';
 import buildMachine, {States} from './index';
 
 describe('buildMachine', () => {
@@ -113,10 +113,12 @@ describe('buildMachine — debug config (#101)', () => {
     }));
 
     const pausedSymbols: string[] = [];
-    await machine.run({
-      initialState: init,
-      onPause: (m) => { pausedSymbols.push(m.currentSymbols[0]); },
+    const session = new DebugSession(machine, {initialState: init});
+    session.on('pause', (m) => {
+      pausedSymbols.push(m.currentSymbols[0]);
+      session.continue();
     });
+    await session.start();
 
     // Trajectory: A (pause) → A (pause) → B (no pause; B not in filter) → halt.
     expect(pausedSymbols).toEqual(['A', 'A']);
@@ -132,10 +134,12 @@ describe('buildMachine — debug config (#101)', () => {
     }));
 
     let afterCount = 0;
-    await machine.run({
-      initialState: init,
-      onPause: (m) => { if (m.debugBreak?.after) afterCount += 1; },
+    const session = new DebugSession(machine, {initialState: init});
+    session.on('pause', (m) => {
+      if (m.debugBreak?.after) afterCount += 1;
+      session.continue();
     });
+    await session.start();
 
     expect(afterCount).toBe(1);
   });
@@ -152,13 +156,13 @@ describe('buildMachine — debug config (#101)', () => {
 
     let beforeCount = 0;
     let afterCount = 0;
-    await machine.run({
-      initialState: init,
-      onPause: (m) => {
-        if (m.debugBreak?.before) beforeCount += 1;
-        if (m.debugBreak?.after) afterCount += 1;
-      },
+    const session = new DebugSession(machine, {initialState: init});
+    session.on('pause', (m) => {
+      if (m.debugBreak?.before) beforeCount += 1;
+      if (m.debugBreak?.after) afterCount += 1;
+      session.continue();
     });
+    await session.start();
 
     expect(beforeCount).toBeGreaterThan(0);
     expect(afterCount).toBeGreaterThan(0);
diff --git a/packages/machine/src/classes/TuringMachine.debug.spec.ts b/packages/machine/src/classes/TuringMachine.debug.spec.ts
index dfda34a..031b471 100644
--- a/packages/machine/src/classes/TuringMachine.debug.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.debug.spec.ts
@@ -3,6 +3,7 @@ import State, {haltState, ifOtherSymbol} from './State';
 import Tape from './Tape';
 import TapeBlock from './TapeBlock';
 import TuringMachine, {type MachineState} from './TuringMachine';
+import DebugSession from './DebugSession';
 import {movements, symbolCommands} from './TapeCommand';
 
 const alphabet = new Alphabet(' AB'.split(''));
@@ -42,7 +43,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
     const {machine, state} = buildMachine();
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
@@ -55,7 +56,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
     state.debug = {before: true};
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
@@ -69,7 +70,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
     state.debug = {before: [symA]};
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     const aVisits = steps.filter((s) => s.currentSymbols[0] === 'A');
     const nonAVisits = steps.filter((s) => s.currentSymbols[0] !== 'A');
@@ -85,7 +86,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
     state.debug = {before: []};
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
@@ -98,7 +99,7 @@ describe('TuringMachine — debug.before filter (loop yields)', () => {
     state.debug = {before: [ifOtherSymbol]};
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     const blankVisits = steps.filter((s) => s.currentSymbols[0] === alphabet.blankSymbol);
     const nonBlankVisits = steps.filter((s) => s.currentSymbols[0] !== alphabet.blankSymbol);
@@ -117,7 +118,7 @@ describe('TuringMachine — debug.after filter (loop yields)', () => {
     state.debug = {after: true};
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
@@ -130,7 +131,7 @@ describe('TuringMachine — debug.after filter (loop yields)', () => {
     state.debug = {before: true, after: true};
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
@@ -144,7 +145,7 @@ describe('TuringMachine — debug.after filter (loop yields)', () => {
     state.debug = {after: [symA]};
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     const aHits = steps.filter((s) => s.currentSymbols[0] === 'A');
@@ -167,7 +168,7 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     haltState.debug = true;
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     // Only the visit whose transition leads to halt (the trailing blank →
@@ -216,7 +217,7 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     haltState.debug = true;
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: wrapped, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: wrapped})) { steps.push(s); }
 
     expect(steps).toHaveLength(3);
 
@@ -241,7 +242,7 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     haltState.debug = false;
     const steps: MachineState[] = [];
 
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
@@ -263,35 +264,31 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
 describe('TuringMachine — run() with onPause', () => {
   afterEach(() => { haltState.debug = null; });
 
-  test('run() returns a Promise', () => {
+  test('run() is synchronous (returns void, not a Promise)', () => {
     const {machine, state} = buildMachine();
     const result = machine.run({initialState: state});
-    expect(result).toBeInstanceOf(Promise);
-    return result;
+    expect(result).toBeUndefined();
   });
 
-  test('without onPause, breaks fire-and-resume invisibly', async () => {
+  test('without DebugSession, breakpoints fire-and-resume invisibly', () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true};
     const steps: MachineState[] = [];
-
-    await machine.run({initialState: state, onStep: (s) => { steps.push(s); }});
-
-    // Trajectory unaffected — onStep sees same number of yields as without debug.
+    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
     expect(steps).toHaveLength(VISIT_COUNT);
   });
 
-  test('onPause fires for "before" with current state', async () => {
+  test('DebugSession pause event fires for "before" with current state', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true};
     const seen: Array<{state: State, debugBreak?: MachineState['debugBreak']}> = [];
 
-    await machine.run({
-      initialState: state,
-      onPause: (m) => {
-        seen.push({state: m.state, debugBreak: m.debugBreak});
-      },
+    const session = new DebugSession(machine, {initialState: state});
+    session.on('pause', (m) => {
+      seen.push({state: m.state, debugBreak: m.debugBreak});
+      session.continue();
     });
+    await session.start();
 
     expect(seen).toHaveLength(VISIT_COUNT);
     for (const entry of seen) {
@@ -300,81 +297,76 @@ describe('TuringMachine — run() with onPause', () => {
     }
   });
 
-  test('onPause for "after" carries the same iter\'s state', async () => {
+  test('DebugSession pause event for "after" carries the same iter\'s state', async () => {
     const {machine, state} = buildMachine();
     state.debug = {after: true};
     const seen: Array<{state: State, debugBreak?: MachineState['debugBreak'], step: number}> = [];
 
-    await machine.run({
-      initialState: state,
-      onPause: (m) => {
-        seen.push({state: m.state, debugBreak: m.debugBreak, step: m.step});
-      },
+    const session = new DebugSession(machine, {initialState: state});
+    session.on('pause', (m) => {
+      seen.push({state: m.state, debugBreak: m.debugBreak, step: m.step});
+      session.continue();
     });
+    await session.start();
 
     expect(seen).toHaveLength(VISIT_COUNT);
-    // The after-call's `m.state` is the iter that armed the after; `before`
-    // and `after` for the SAME iter both fire on that iter's own yield.
     for (const entry of seen) {
       expect(entry.state).toBe(state);
       expect(entry.debugBreak).toEqual({after: true, cause: 'breakpoint'});
     }
   });
 
-  test('both "before" and "after" on same yield → two hook calls in lifecycle order', async () => {
+  test('both "before" and "after" on same yield → two pause events in lifecycle order', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true, after: true};
     const calls: Array<'before' | 'after'> = [];
 
-    await machine.run({
-      initialState: state,
-      onPause: (m) => {
-        if (m.debugBreak?.before) calls.push('before');
-        if (m.debugBreak?.after) calls.push('after');
-      },
+    const session = new DebugSession(machine, {initialState: state});
+    session.on('pause', (m) => {
+      if (m.debugBreak?.before) calls.push('before');
+      if (m.debugBreak?.after) calls.push('after');
+      session.continue();
     });
+    await session.start();
 
     // Per-iter lifecycle: before → step → after. Every yield dispatches both
-    // hooks in this order. For VISIT_COUNT visits: [before, after, before, …]
+    // pauses in this order. For VISIT_COUNT visits: [before, after, before, …]
     expect(calls).toHaveLength(VISIT_COUNT * 2);
     for (let i = 0; i < calls.length; i++) {
       expect(calls[i]).toBe(i % 2 === 0 ? 'before' : 'after');
     }
   });
 
-  test('onPause can be async (run awaits it)', async () => {
+  test('async pause listener: session waits until continue() (not the listener return)', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true};
     let released = false;
     let callCount = 0;
 
-    const hookFor = () => new Promise<void>((resolve) => {
-      setTimeout(() => { released = true; resolve(); }, 10);
-    });
-
-    await machine.run({
-      initialState: state,
-      onPause: () => {
-        callCount += 1;
-        return hookFor(); // run() awaits this
-      },
+    const session = new DebugSession(machine, {initialState: state});
+    session.on('pause', async () => {
+      callCount += 1;
+      await new Promise<void>((resolve) => {
+        setTimeout(() => { released = true; resolve(); }, 10);
+      });
+      session.continue();
     });
+    await session.start();
 
     expect(released).toBe(true);
     expect(callCount).toBe(VISIT_COUNT);
   });
 
-  test('onStep still fires on every yield, separate from onPause', async () => {
+  test('step event still fires on every yield, separate from pause', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true};
     let stepCount = 0;
     let breakCount = 0;
 
-    await machine.run({
-      initialState: state,
-      onStep: () => { stepCount += 1; },
-      onPause: () => { breakCount += 1; },
-    });
+    const session = new DebugSession(machine, {initialState: state});
+    session.on('step', () => { stepCount += 1; });
+    session.on('pause', () => { breakCount += 1; session.continue(); });
+    await session.start();
 
     expect(stepCount).toBe(VISIT_COUNT);
     expect(breakCount).toBe(VISIT_COUNT);
@@ -391,10 +383,12 @@ describe('TuringMachine — halt semantics for after-fire (#108)', () => {
     state.debug = {after: true};
     const after: MachineState[] = [];
 
-    await machine.run({
-      initialState: state,
-      onPause: (m) => { if (m.debugBreak?.after) after.push(m); },
+    const session = new DebugSession(machine, {initialState: state});
+    session.on('pause', (m) => {
+      if (m.debugBreak?.after) after.push(m);
+      session.continue();
     });
+    await session.start();
 
     expect(after).toHaveLength(VISIT_COUNT);
   });
@@ -436,91 +430,39 @@ describe('TuringMachine — halt semantics for after-fire (#108)', () => {
   });
 });
 
-describe('TuringMachine — run({debug}) flag (#106)', () => {
+describe('debugBreak metadata on yields (no consumer dispatch)', () => {
   afterEach(() => { haltState.debug = null; });
 
-  test('debug: false suppresses onPause for "before" matches', async () => {
-    const {machine, state} = buildMachine();
-    state.debug = {before: true};
-    const pauses: MachineState[] = [];
-
-    await machine.run({
-      initialState: state,
-      onPause: (m) => { pauses.push(m); },
-      debug: false,
-    });
-
-    expect(pauses).toHaveLength(0);
-  });
-
-  test('debug: false suppresses onPause for "after" matches (every visit, including halting iter)', async () => {
-    // With state.debug.after = true, every visit normally produces an
-    // after-fire dispatch (including the halting iter, post-#108/#119). The
-    // master switch must gate all of them.
-    const {machine, state} = buildMachine();
-    state.debug = {after: true};
-    const pauses: MachineState[] = [];
-
-    await machine.run({
-      initialState: state,
-      onPause: (m) => { pauses.push(m); },
-      debug: false,
-    });
-
-    expect(pauses).toHaveLength(0);
-  });
+  // v6's `run({debug: false})` master switch is gone in v7 (callbacks moved
+  // entirely to DebugSession). The semantic that lived in those tests —
+  // "yielded MachineStates carry debugBreak metadata regardless of consumer
+  // dispatch" — still holds, and is observable by iterating `runStepByStep`
+  // directly without constructing a session.
 
-  test('debug: true (default) dispatches onPause as v4', async () => {
+  test('runStepByStep yields debugBreak metadata even without a DebugSession', () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true};
-    const pauses: MachineState[] = [];
-
-    await machine.run({
-      initialState: state,
-      onPause: (m) => { pauses.push(m); },
-      // debug omitted → defaults to true
-    });
+    const yields: MachineState[] = [];
+    for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
-    expect(pauses).toHaveLength(VISIT_COUNT);
+    expect(yields).toHaveLength(VISIT_COUNT);
+    for (const y of yields) {
+      expect(y.debugBreak).toEqual({before: true, cause: 'breakpoint'});
+    }
   });
 
-  test('debug: false does NOT suppress onStep', async () => {
-    // The flag is specifically about pause-capable dispatch; trace/logging
-    // continues regardless.
+  test('a DebugSession with NO pause listener consumes breakpoints invisibly', async () => {
+    // No pause listener registered — the session still dispatches into its
+    // (empty) listener list and immediately resumes via the loop. End-to-end
+    // behavior equivalent to v6's `debug: false` (run completes without
+    // surfacing pauses), without the need for a master switch.
     const {machine, state} = buildMachine();
     state.debug = {before: true};
     let stepCount = 0;
-
-    await machine.run({
-      initialState: state,
-      onStep: () => { stepCount += 1; },
-      onPause: () => {},
-      debug: false,
-    });
-
+    const session = new DebugSession(machine, {initialState: state});
+    session.on('step', () => { stepCount += 1; });
+    session.on('pause', () => { session.continue(); });
+    await session.start();
     expect(stepCount).toBe(VISIT_COUNT);
   });
-
-  test('debug: false leaves m.debugBreak metadata on yields (gating is run-level only)', async () => {
-    // Direct runStepByStep consumers see the metadata regardless of how run()
-    // is configured. Here we observe via onStep, which receives the original
-    // yielded MachineState — its debugBreak field is unaffected.
-    const {machine, state} = buildMachine();
-    state.debug = {before: true};
-    const yields: MachineState[] = [];
-
-    await machine.run({
-      initialState: state,
-      onStep: (m) => { yields.push(m); },
-      onPause: () => {},
-      debug: false,
-    });
-
-    expect(yields).toHaveLength(VISIT_COUNT);
-    // EVERY yield carries the metadata (wildcard before-filter), even though
-    // no onPause fires.
-    for (const y of yields) {
-      expect(y.debugBreak).toEqual({before: true, cause: 'breakpoint'});
-    }
-  });
 });
diff --git a/packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts b/packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts
index b94b050..40ebfb6 100644
--- a/packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts
@@ -42,7 +42,7 @@ describe('MachineState.matchedTransition (#205)', () => {
 
     const machine = new TuringMachine({tapeBlock});
     const yields: MachineState[] = [];
-    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+    for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
     expect(yields).toHaveLength(1);
     expect(yields[0].matchedTransition).toEqual({
@@ -63,7 +63,7 @@ describe('MachineState.matchedTransition (#205)', () => {
 
     const machine = new TuringMachine({tapeBlock});
     const yields: MachineState[] = [];
-    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+    for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
     expect(yields).toHaveLength(1);
     expect(yields[0].matchedTransition).toEqual({
@@ -89,7 +89,7 @@ describe('MachineState.matchedTransition (#205)', () => {
 
     const machine = new TuringMachine({tapeBlock});
     const yields: MachineState[] = [];
-    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+    for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
     expect(yields).toHaveLength(1);
     expect(yields[0].matchedTransition.matchKinds).toEqual(['wildcard', 'literal']);
@@ -111,7 +111,7 @@ describe('MachineState.matchedTransition (#205)', () => {
 
     const machine = new TuringMachine({tapeBlock});
     const yields: MachineState[] = [];
-    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+    for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
     expect(yields[0].matchedTransition.matchKinds).toEqual(['literal', 'literal']);
     expect(yields[0].matchedTransition.matchKinds).toHaveLength(2);
@@ -138,7 +138,7 @@ describe('MachineState.matchedTransition (#205)', () => {
 
     const machine = new TuringMachine({tapeBlock});
     const yields: MachineState[] = [];
-    await machine.run({initialState: wrapper, onStep: (m) => { yields.push(m); }});
+    for (const m of machine.runStepByStep({initialState: wrapper})) { yields.push(m); }
 
     // Iter 1 source = wrapper (delegates to bare's transitions).
     expect(yields[0].state).toBe(wrapper);
@@ -159,7 +159,7 @@ describe('MachineState.matchedTransition (#205)', () => {
 
     const machine = new TuringMachine({tapeBlock});
     const yields: MachineState[] = [];
-    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+    for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
     expect(yields).toHaveLength(1);
     expect(yields[0].matchedTransition).toEqual({
@@ -181,7 +181,7 @@ describe('MachineState.matchedTransition (#205)', () => {
 
     const machine = new TuringMachine({tapeBlock});
     const yields: MachineState[] = [];
-    await machine.run({initialState: state, onStep: (m) => { yields.push(m); }});
+    for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
     const graph = toGraph(state, tapeBlock);
 
diff --git a/packages/machine/src/classes/TuringMachine.spec.ts b/packages/machine/src/classes/TuringMachine.spec.ts
index 9bf2630..7af5012 100644
--- a/packages/machine/src/classes/TuringMachine.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.spec.ts
@@ -1,9 +1,9 @@
-import {vi} from 'vitest';
 import Alphabet from './Alphabet';
 import State, {haltState, ifOtherSymbol} from './State';
 import Tape from './Tape';
 import TapeBlock from './TapeBlock';
 import TuringMachine, {MachineState} from './TuringMachine';
+import DebugSession from './DebugSession';
 import {movements, symbolCommands} from './TapeCommand';
 import Reference from './Reference';
 
@@ -100,44 +100,32 @@ describe('run tests', () => {
     ];
   });
 
-  test('run', async () => {
-    const steps: MachineState[] = [];
-
-    await machine.run({initialState, stepsLimit: 1e5, onStep: (step) => { steps.push(step); }});
+  test('run (sync, no observation) drains to halt', () => {
+    machine.run({initialState, stepsLimit: 1e5});
+    expect(tape.symbols.join('').trim().length).toBe(0);
+  });
 
-    expect(steps)
-      .toEqual(expectedSteps);
-    expect(tape.symbols.join('').trim().length)
-      .toBe(0);
+  test('run with DebugSession observes every step in order', async () => {
+    const steps: MachineState[] = [];
+    const session = new DebugSession(machine, {initialState, stepsLimit: 1e5});
+    session.on('step', (m) => { steps.push(m); });
+    await session.start();
+    // DebugSession's step listener fires once per iter — matches the v6
+    // onStep contract.
+    expect(steps.length).toBe(expectedSteps.length);
+    for (let i = 0; i < steps.length; i++) {
+      // step listener gets the live MachineState. expectedSteps were captured
+      // from the pre-v7 run({onStep}) shape; the visible MachineState fields
+      // are the same. matchObject ignores the internal MACHINE_STATE_INTERNAL.
+      expect(steps[i]).toMatchObject(expectedSteps[i] as object);
+    }
   });
 
-  test('stepsLimit', async () => {
-    const onStepsLimit0Mock = vi.fn();
-
-    await expect(machine.run({
-      initialState,
-      stepsLimit: 0,
-      onStep: () => onStepsLimit0Mock()
-    })).rejects.toThrow('Long execution');
-    expect(onStepsLimit0Mock.mock.calls.length).toEqual(0);
-
-    const onStepsLimit1Mock = vi.fn();
-
-    await expect(machine.run({
-      initialState,
-      stepsLimit: 1,
-      onStep: () => onStepsLimit1Mock()
-    })).rejects.toThrow('Long execution');
-    expect(onStepsLimit1Mock.mock.calls.length).toEqual(1);
-
-    const onStepsLimit2Mock = vi.fn();
-
-    await expect(machine.run({
-      initialState,
-      stepsLimit: 2,
-      onStep: () => onStepsLimit2Mock()
-    })).rejects.toThrow('Long execution');
-    expect(onStepsLimit2Mock.mock.calls.length).toEqual(2);
+  test('stepsLimit throws "Long execution" after N iters', () => {
+    // run() is sync — `throws`, not `rejects`.
+    expect(() => machine.run({initialState, stepsLimit: 0})).toThrow('Long execution');
+    expect(() => machine.run({initialState, stepsLimit: 1})).toThrow('Long execution');
+    expect(() => machine.run({initialState, stepsLimit: 2})).toThrow('Long execution');
   });
 
   test('stepByStep', () => {
@@ -175,66 +163,42 @@ describe('run tests', () => {
     expect(generator.next().done).toBe(true);
   });
 
-  test('onIter fires once per iter, awaited, after both pause dispatches (#163)', async () => {
+  test('per-iter lifecycle: pause-before → step → pause-after → iter (#163)', async () => {
     // Arm both before+after on the initial state so the dispatch order
-    // before(K) → step(K) → after(K) → iter(K) is observable per iter.
+    // before(K) → step(K) → after(K) → iter(K) is observable per iter via
+    // DebugSession's events.
     initialState.debug = {before: true, after: true};
 
     const order: string[] = [];
-    const yieldToMicrotask = () => new Promise<void>((r) => queueMicrotask(r));
-
-    await machine.run({
-      initialState,
-      stepsLimit: 1e5,
-      onStep: (m) => { order.push(`step-${m.step}`); },
-      onPause: (m) => {
-        const when = m.debugBreak?.before ? 'before' : 'after';
-        order.push(`pause-${when}-${m.step}`);
-      },
-      onIter: async (m) => {
-        order.push(`iter-pre-${m.step}`);
-        await yieldToMicrotask();
-        order.push(`iter-post-${m.step}`);
-      },
+
+    const session = new DebugSession(machine, {initialState, stepsLimit: 1e5});
+    session.on('step', (m) => { order.push(`step-${m.step}`); });
+    session.on('pause', (m) => {
+      const when = m.debugBreak?.before ? 'before' : 'after';
+      order.push(`pause-${when}-${m.step}`);
+      session.continue();
     });
+    session.on('iter', (m) => { order.push(`iter-${m.step}`); });
+    await session.start();
 
     initialState.debug = null; // reset for other tests
 
-    // For every iter K we must see:
-    //   pause-before-K, step-K, pause-after-K, iter-pre-K, iter-post-K
-    // …adjacent and in that order, never interleaved across iters
-    // (which would mean onIter wasn't awaited).
+    // For every iter K we must see (in order):
+    //   pause-before-K, step-K, pause-after-K, iter-K
     expect(order.length).toBeGreaterThan(0);
-    expect(order.length % 5).toBe(0);
-    for (let i = 0; i < order.length; i += 5) {
+    expect(order.length % 4).toBe(0);
+    for (let i = 0; i < order.length; i += 4) {
       const k = order[i].split('-').pop();
       expect(order[i]).toBe(`pause-before-${k}`);
       expect(order[i + 1]).toBe(`step-${k}`);
       expect(order[i + 2]).toBe(`pause-after-${k}`);
-      expect(order[i + 3]).toBe(`iter-pre-${k}`);
-      expect(order[i + 4]).toBe(`iter-post-${k}`);
+      expect(order[i + 3]).toBe(`iter-${k}`);
     }
   });
-
-  test('onIter fires unconditionally (not gated by debug flag) (#163)', async () => {
-    // No state.debug armed AND `debug: false` master switch — onPause must
-    // never fire, but onIter still fires every iter.
-    const iters: number[] = [];
-
-    await machine.run({
-      initialState,
-      stepsLimit: 1e5,
-      debug: false,
-      onIter: (m) => { iters.push(m.step); },
-    });
-
-    expect(iters.length).toBeGreaterThan(0);
-    // Strictly increasing — one onIter per iter.
-    for (let i = 1; i < iters.length; i++) {
-      expect(iters[i]).toBeGreaterThan(iters[i - 1]);
-    }
-  });
-
+  // NOTE: The v6 `debug: false` master-switch test is dropped — v7 removes
+  // the master switch (along with the rest of the run() callback surface).
+  // DebugSession's iter event already covers "fires regardless of breakpoint
+  // configuration" via the buildWalker tests in DebugSession.spec.ts.
 });
 
 describe('properties', () => {
@@ -362,12 +326,9 @@ describe('halt-stack reset between calls (regression for #196)', () => {
     gen.return(undefined);
 
     const iters: Array<{step: number; name: string}> = [];
-    await machine.run({
-      initialState,
-      onIter: (m) => {
-        iters.push({step: m.step, name: m.state.name ?? ''});
-      },
-    });
+    for (const m of machine.runStepByStep({initialState})) {
+      iters.push({step: m.step, name: m.state.name ?? ''});
+    }
 
     expect(iters).toEqual([
       {step: 1, name: 'walkToBlank(writeMarker)'},
@@ -379,7 +340,7 @@ describe('halt-stack reset between calls (regression for #196)', () => {
     expect(tape.symbols).toEqual(['a', 'b', 'a', '*']);
   });
 
-  test('runStepByStep and run produce identical iter sequences', async () => {
+  test('runStepByStep and DebugSession iter event produce identical sequences', async () => {
     const a = buildWrapperOverWalkToBlank();
     const fromGen: Array<{step: number; name: string}> = [];
     for (const m of a.machine.runStepByStep({initialState: a.initialState})) {
@@ -387,15 +348,14 @@ describe('halt-stack reset between calls (regression for #196)', () => {
     }
 
     const b = buildWrapperOverWalkToBlank();
-    const fromRun: Array<{step: number; name: string}> = [];
-    await b.machine.run({
-      initialState: b.initialState,
-      onIter: (m) => {
-        fromRun.push({step: m.step, name: m.state.name ?? ''});
-      },
+    const fromSession: Array<{step: number; name: string}> = [];
+    const session = new DebugSession(b.machine, {initialState: b.initialState});
+    session.on('iter', (m) => {
+      fromSession.push({step: m.step, name: m.state.name ?? ''});
     });
+    await session.start();
 
-    expect(fromRun).toEqual(fromGen);
+    expect(fromSession).toEqual(fromGen);
   });
 
   test('two consecutive runs on the same machine produce identical iter sequences', async () => {
@@ -425,20 +385,14 @@ describe('halt-stack reset between calls (regression for #196)', () => {
     const initialState = bare.withOverriddenHaltState(continuation);
 
     const first: Array<{step: number; name: string}> = [];
-    await machine.run({
-      initialState,
-      onIter: (m) => {
-        first.push({step: m.step, name: m.state.name ?? ''});
-      },
-    });
+    for (const m of machine.runStepByStep({initialState})) {
+      first.push({step: m.step, name: m.state.name ?? ''});
+    }
 
     const second: Array<{step: number; name: string}> = [];
-    await machine.run({
-      initialState,
-      onIter: (m) => {
-        second.push({step: m.step, name: m.state.name ?? ''});
-      },
-    });
+    for (const m of machine.runStepByStep({initialState})) {
+      second.push({step: m.step, name: m.state.name ?? ''});
+    }
 
     expect(first.length).toBe(2); // wrapper-iter + continuation-iter
     expect(second).toEqual(first);
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index 3e43fde..8ba50ec 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -111,83 +111,27 @@ export default class TuringMachine {
     return this.#tapeBlock;
   }
 
-  async run({
-    initialState,
-    stepsLimit = 1e5,
-    onStep,
-    onPause,
-    onIter,
-    debug = true,
-  }: RunParameter & {
-    /**
-     * Sync, ~free hook fired on every iteration. Use for logging/tracing —
-     * the hot loop runs this without a microtask boundary, so it must not
-     * be async.
-     *
-     * For per-iter throttle / coordination ("wait between iters" UIs):
-     * use `onIter` (v6.4.0+, awaited at end-of-iter).
-     */
-    onStep?: (machineState: MachineState) => void;
-    /**
-     * Async hook fired when `state.debug[when]` matches at the current
-     * iteration. The promise is awaited inline, so the consumer can suspend
-     * execution by deferring its resolution. Use for pause-capable inspection
-     * (debugger UIs, conditional breakpoints in tests). Per-iter lifecycle:
-     * `before` and `after` for the same iter fire on the same yield.
-     */
-    onPause?: (machineState: MachineState) => void | Promise<void>;
-    /**
-     * Awaited hook fired ONCE at the end of every iteration (v6.4.0+), AFTER
-     * any `onPause(after, K)` dispatch on the same yield. Use for per-iter
-     * coordination that needs to suspend the run loop — throttling between
-     * iters (interactive debugger UIs), prev-state bookkeeping that must
-     * observe iter K's final state once all `onPause` hooks have read their
-     * own snapshots, yield-to-other-work in batched runs.
-     *
-     * Three-hook contract recap:
-     * - `onStep`: sync, microtask-free — tracing/logging during the iter
-     * - `onPause`: awaited, conditional on `state.debug[when]` match — user
-     *   breakpoints with iter-correct payload
-     * - `onIter`: awaited, unconditional — once per iter, at end-of-iter
-     *
-     * `onIter` is unaffected by the `debug` master switch — it fires on
-     * every iter regardless. Sync consumers should prefer `onStep` to avoid
-     * the per-iter microtask boundary `onIter` carries.
-     */
-    onIter?: (machineState: MachineState) => void | Promise<void>;
-    /**
-     * Master switch for `onPause` dispatch. When `false`, suppresses all
-     * pause-fires (before and after) regardless of `state.debug` assignments.
-     * `onStep` is unaffected. Defaults to `true`.
-     *
-     * The `m.debugBreak` field is still populated on yields by the underlying
-     * generator (it's a property of the iteration, not of the consumer); only
-     * `run()`'s hook dispatch is gated. Direct `runStepByStep` consumers see
-     * the metadata regardless.
-     */
-    debug?: boolean;
-  }): Promise<void> {
-    const generator = this.runStepByStep({initialState, stepsLimit});
-
-    for (const machineState of generator) {
-      // Per-iter lifecycle: before → step → after. All three operate on the
-      // same yielded MachineState, so the consumer sees a coherent ordering
-      // within each iteration without cross-tick coordination.
-      if (debug && machineState.debugBreak?.before && onPause) {
-        await onPause({...machineState, debugBreak: {before: true, cause: 'breakpoint'}});
-      }
-
-      if (onStep) {
-        onStep(machineState);
-      }
-
-      if (debug && machineState.debugBreak?.after && onPause) {
-        await onPause({...machineState, debugBreak: {after: true, cause: 'breakpoint'}});
-      }
-
-      if (onIter) {
-        await onIter(machineState);
-      }
+  /**
+   * Run the machine to halt. Pure execution — synchronous, no observation
+   * callbacks, no debug overhead. For breakpoint-driven interactive debugging
+   * use `DebugSession`; for per-iter tracing use `runStepByStep`'s generator
+   * directly.
+   *
+   * Breakpoint metadata (`state.debug` / `haltState.debug` matches) is still
+   * resolved and attached to each yielded MachineState by the underlying
+   * generator — `run()` simply doesn't dispatch on it. A consumer that wants
+   * to dispatch on it constructs a `DebugSession` instead.
+   *
+   * Symmetric reversal of v4's `run` → `async run` change: v4 made the method
+   * async to support awaited `onPause`; with callbacks moved to `DebugSession`
+   * there's no async work left, so the method returns `void` again.
+   */
+  run({initialState, stepsLimit = 1e5}: RunParameter): void {
+    // Drain the generator. We don't care about the yielded values — the
+    // generator's job is to advance the tape; only side effects matter here.
+    // Casting to unknown so eslint doesn't flag the unused `_` variable.
+    for (const machineState of this.runStepByStep({initialState, stepsLimit})) {
+      void machineState;
     }
   }
 
diff --git a/test/examples.spec.ts b/test/examples.spec.ts
index a34eb6e..7df4972 100644
--- a/test/examples.spec.ts
+++ b/test/examples.spec.ts
@@ -1,5 +1,6 @@
 import {
   Alphabet,
+  DebugSession,
   haltState,
   ifOtherSymbol,
   movements,
@@ -95,7 +96,9 @@ describe('README.md — Debugging breakpoints', () => {
     myState.debug = {before: true};
     let breakCount = 0;
 
-    await machine.run({initialState: myState, onPause: () => { breakCount += 1; }});
+    const session = new DebugSession(machine, {initialState: myState});
+    session.on('pause', () => { breakCount += 1; session.continue(); });
+    await session.start();
 
     expect(breakCount).toBe(VISIT_COUNT);
   });
@@ -106,13 +109,13 @@ describe('README.md — Debugging breakpoints', () => {
     let symASeen = 0;
     let nonASeen = 0;
 
-    await machine.run({
-      initialState: myState,
-      onPause: (m) => {
-        if (m.currentSymbols[0] === 'A') symASeen += 1;
-        else nonASeen += 1;
-      },
+    const session = new DebugSession(machine, {initialState: myState});
+    session.on('pause', (m) => {
+      if (m.currentSymbols[0] === 'A') symASeen += 1;
+      else nonASeen += 1;
+      session.continue();
     });
+    await session.start();
 
     expect(symASeen).toBe(A_VISIT_COUNT);
     expect(nonASeen).toBe(0);
@@ -123,13 +126,13 @@ describe('README.md — Debugging breakpoints', () => {
     myState.debug = {before: [symA], after: [symA]};
     const order: Array<'before' | 'after'> = [];
 
-    await machine.run({
-      initialState: myState,
-      onPause: (m) => {
-        if (m.debugBreak?.before) order.push('before');
-        if (m.debugBreak?.after) order.push('after');
-      },
+    const session = new DebugSession(machine, {initialState: myState});
+    session.on('pause', (m) => {
+      if (m.debugBreak?.before) order.push('before');
+      if (m.debugBreak?.after) order.push('after');
+      session.continue();
     });
+    await session.start();
 
     // Only visit 1 (head=A) matches; per-iter lifecycle is before → after.
     // Visit 2 (head=B) doesn't match, no fires.
@@ -142,23 +145,20 @@ describe('README.md — Debugging breakpoints', () => {
     const haltPauses: Array<{atVisit: number}> = [];
     let visitIx = 0;
 
-    await machine.run({
-      initialState: myState,
-      onStep: () => { visitIx += 1; }, // increments before onPause for this visit
-      onPause: (m) => {
-        // #207: halt-imminent fires on AFTER side (post-iter, before halt
-        // processing). The triggering iter's `nextState` is haltState, and
-        // `debugBreak.after === true`.
-        if (m.nextState === haltState && m.debugBreak?.after) {
-          haltPauses.push({atVisit: visitIx});
-        }
-      },
+    const session = new DebugSession(machine, {initialState: myState});
+    session.on('step', () => { visitIx += 1; });
+    session.on('pause', (m) => {
+      if (m.nextState === haltState && m.debugBreak?.after) {
+        haltPauses.push({atVisit: visitIx});
+      }
+      session.continue();
     });
+    await session.start();
 
     expect(haltPauses).toHaveLength(HALT_TRANSITION_COUNT);
-    // Per-iter dispatch order is `before → step → after` — onStep increments
-    // visitIx during step, then onPause for `after` reads it. The recorded
-    // visit index matches the human-readable visit count.
+    // Per-iter dispatch order: pause(before) → step → pause(after) → iter.
+    // step increments visitIx; pause for after reads the just-incremented
+    // value, matching the human-readable visit count.
     expect(haltPauses[0].atVisit).toBe(VISIT_COUNT);
   });
 
@@ -199,11 +199,10 @@ describe('README.md — Debugging breakpoints', () => {
     let stepCount = 0;
     let breakCount = 0;
 
-    await machine.run({
-      initialState: myState,
-      onStep: () => { stepCount += 1; },
-      onPause: () => { breakCount += 1; },
-    });
+    const session = new DebugSession(machine, {initialState: myState});
+    session.on('step', () => { stepCount += 1; });
+    session.on('pause', () => { breakCount += 1; session.continue(); });
+    await session.start();
 
     expect(stepCount).toBe(VISIT_COUNT);
     expect(breakCount).toBe(VISIT_COUNT);
@@ -239,15 +238,12 @@ describe('README.md — Matched transition', () => {
 
     // Verbatim from README's "Matched transition" section, with console.log
     // replaced by capture for assertion.
-    await machine.run({
-      initialState,
-      onStep: (m) => {
-        const wildcardPositions = m.matchedTransition.matchKinds
-          .map((k, i) => k === 'wildcard' ? i : -1)
-          .filter((i) => i >= 0);
-        logged.push(`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
+        .map((k, i) => k === 'wildcard' ? i : -1)
+        .filter((i) => i >= 0);
+      logged.push(`step ${m.step}: fired transition ${m.matchedTransition.id} (wildcards at tapes: ${wildcardPositions.join(',') || 'none'})`);
+    }
 
     const sid = initialState.id;
     expect(logged).toEqual([

From c574f203cae14c9ac4e68d4297370d908babaf91 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:43:55 +0300
Subject: [PATCH 064/118] docs: rewrite Debugging section around DebugSession +
 v7 migration guide (#102)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Debugging breakpoints section is restructured around three entry
points instead of one mixed-mode run():
- run() — pure execution, sync, no observation
- runStepByStep() — sync per-iter generator
- DebugSession — interactive debugging with events + step controls + throttle

Adds a "v7 migration" subsection that maps each removed v6 pattern
(run({onStep}) / run({onPause}) / run({onIter}) / run({debug:false}))
to its v7 equivalent.

Updates ancillary references:
- TuringMachine intro example drops `await` from run() and points to
  DebugSession for interactive use.
- "Choosing between" table covers all three entry points.
- Matched transition example uses runStepByStep instead of run({onStep}).
- Throttle pattern section moved to session.setRunInterval(ms).
---
 packages/machine/README.md | 185 ++++++++++++++++++++++++++-----------
 1 file changed, 130 insertions(+), 55 deletions(-)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index f0719d0..046a81e 100644
--- a/packages/machine/README.md
+++ b/packages/machine/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,26 +329,27 @@ 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 |
+| `debugBreak?` | `{ before?: true, after?: true, cause: 'breakpoint' \| 'step' \| 'manual' }` | only set when this iter is a pause point. `cause` identifies the origin (engine breakpoint vs DebugSession step / manual). See *Debugging* 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 dispatch | breakpoints fire-and-resume invisibly | `debugBreak` field on each yield; consumer reads it | `pause` event fires with `cause: 'breakpoint'` |
+| 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).
+The `debugBreak` metadata is on every yielded `MachineState` regardless of which entry point you used — `runStepByStep` consumers can read it directly, `DebugSession` consumers see it on the `pause` event payload.
 
 ### Matched transition
 
@@ -365,15 +369,12 @@ 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`
@@ -478,9 +479,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.
+
+```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}, cause: ${m.debugBreak.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()
+```
 
-Any `State` can carry a runtime-mutable `debug` config that pauses execution at chosen points.
+### 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 +529,50 @@ 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.debugBreak.after === true`.
 
-> ⚠️ **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.
+> ⚠️ **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`.**
 
-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`.
+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.
 
-`run()` is async and accepts an `onPause` hook:
+**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).
 
-```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);
-  },
-});
-```
+**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 force a `pause` event on the very next iter, regardless of breakpoint filters. |
+| `stepOver()` | Resume and pause at the first iter after the click-time top halt-frame is no longer on the stack. Collapses to `stepIn` if the click-time stack was empty. |
+| `stepOut()` | Same endpoint as `stepOver`, but throws if the click-time stack is empty (no enclosing frame to exit — IDE convention). |
+| `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. Listeners may return `void` or `Promise<void>` — the session fires them and continues without awaiting (Node `EventEmitter` semantics). |
+
+### Events
+
+| Event | Argument | Fires |
+|---|---|---|
+| `pause` | `MachineState` (with `debugBreak.cause`) | A breakpoint matched, a step-mode endpoint was reached, or `session.pause()` was requested. Loop blocks until a resume method (`continue / stepIn / stepOver / stepOut / stop`) is called. |
+| `step` | `MachineState` | Once per iter, between any before-pause and after-pause. Fire-and-forget. |
+| `iter` | `MachineState` | Once per iter, at end. After any after-pause. |
+| `halt` | (none) | Once, on natural halt. Does NOT fire when `stop()` was called. |
 
-**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).
+### `MachineState.debugBreak.cause`
 
-**Caveat:** `haltState` is a module-level singleton. Setting `haltState.debug` affects every machine in the process; clear in `afterEach` / `finally` for test isolation.
+When the `pause` event fires, `m.debugBreak.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.
+
+### 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 +606,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:
+
+```ts
+// v6
+await machine.run({ initialState, onStep: (m) => trace(m) });
 
-A few details:
+// 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 and ignore the `debugBreak` 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+.)
 

From d3879725a6dc49585d62262d7ebd99de05aaeacd Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:47:21 +0300
Subject: [PATCH 065/118] docs(plans): step-control implementation plan for
 #102

---
 .../plans/2026-05-25-step-control.md          | 1354 +++++++++++++++++
 1 file changed, 1354 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-25-step-control.md

diff --git a/docs/superpowers/plans/2026-05-25-step-control.md b/docs/superpowers/plans/2026-05-25-step-control.md
new file mode 100644
index 0000000..372d956
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-25-step-control.md
@@ -0,0 +1,1354 @@
+# Step-control via `run()` / `debugRun()` Split — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close #102 (v7-stable gating issue) by splitting `TuringMachine`'s execution API into two non-overlapping entry points: a synchronous `run()` with no observation overhead, and a `debugRun()` that returns a `DebugSession` carrying the full interactive-debugger surface (events, breakpoints, step-in/over/out, click-pause, throttle).
+
+**Architecture:** `TuringMachine` stays minimal. `DebugSession` lives in a separate module and is constructed directly:
+
+```ts
+class TuringMachine {
+  run({initialState, stepsLimit?}): void;                       // pure execution, sync
+  *runStepByStep({initialState, stepsLimit?}): Generator<MachineState>;  // unchanged, sync per-iter observation
+  // NO debugRun method — debugger is an external opt-in
+}
+
+// Separate module — packages/machine/src/classes/DebugSession.ts
+class DebugSession {
+  constructor(machine: TuringMachine, parameter: DebugSessionParameter);
+  start(): Promise<void>;
+  stop(): void;
+  continue(): void;
+  stepIn(): void;
+  stepOver(): void;
+  stepOut(): void;
+  pause(): void;
+  setRunInterval(ms: number): void;
+  on/off events: pause, step, iter, halt;
+}
+
+// Usage:
+import {TuringMachine, DebugSession} from '@turing-machine-js/machine';
+const session = new DebugSession(machine, {initialState});
+await session.start();
+```
+
+`DebugSession` owns everything that was previously layered on top of `run({onPause, onStep, onIter, debug})` plus all the coordination logic (step-mode tracking, click-pause, throttle, pause/resume plumbing, event fan-out) that every demo / IDE extension would otherwise reimplement. Internally `DebugSession` consumes the engine's public `runStepByStep` generator and uses a Symbol-keyed `MACHINE_STATE_INTERNAL` accessor on yielded machine states to read the halt-stack for step-over/step-out endpoint detection — same sibling-module pattern as `STATE_INTERNAL` from #180. **No new private access needed beyond the Symbol.**
+
+**Tech Stack:** TypeScript, Vitest, the existing `@turing-machine-js/machine` engine code.
+
+**Scope:** Engine-only. `@post-machine-js/machine` adopts the new shape in a follow-up issue/PR (`pm.run()` + `pm.debugRun()`). `machines-demo` worker migration is a downstream follow-up. CHANGELOG entry lands in the alpha.6 release PR.
+
+**Breaking changes vs v6:** `run({onPause, onStep, onIter, debug})` removed. Consumers wanting hooks call `debugRun()` and use the session's event interface. Documented in the v7 migration section of `packages/machine/README.md`. v7 is already the breaking version, so this fits cleanly with the existing composition renames and `haltState.debug` boolean change.
+
+**Design choices locked in:**
+
+1. **`DebugSession` is the public surface for interactive debugging.** The `ResumeDirective` primitive that powers it stays internal (used inside `DebugSession`'s loop but not part of the package's `index.ts` exports). One canonical recommended API, one internal mechanism.
+2. **`run()` becomes sync.** Without `await onPause / onIter`, no async work remains in the loop. Return type `Promise<void> → void`. Symmetric reversal of the v4-era `run` → `async run` change.
+3. **`onStep` removed entirely.** `runStepByStep` (the generator) already covers sync per-iter observation; keeping `onStep` is YAGNI duplication. Consumers needing tracing without breakpoint-driven flow iterate the generator.
+4. **`DebugBreak.cause: 'breakpoint' | 'step' | 'manual'`.** `'breakpoint'` for `state.debug` matches, `'step'` for step-mode natural endpoints, `'manual'` for `session.pause()` click-pauses.
+5. **`DebugSession` uses a tiny built-in listener registry**, not `node:events`. Library is environment-agnostic (Node, browsers, Workers); ~20 LOC of `on/off/emit` methods.
+6. **`session.start()` returns `Promise<void>` resolved on halt.** Async because consumer-controlled pauses await consumer action. Symmetric with how `run()` previously behaved.
+7. **One-shot step-mode rule preserved:** any pause-event dispatch (breakpoint, step endpoint, manual) drops the active step-mode. Re-engaging requires another `session.stepIn/Over/Out()` call.
+8. **Step-out from empty halt-stack throws.** IDE convention; explicit error beats silent no-op.
+9. **Halt-stack snapshot via Symbol-keyed `MACHINE_STATE_INTERNAL`.** Same pattern as `STATE_INTERNAL` from #180. Not re-exported from the package's public `index.ts`.
+
+---
+
+## File Structure
+
+- **Modify** `packages/machine/src/classes/TuringMachine.ts` — strip callbacks from `run`, make sync, add `MACHINE_STATE_INTERNAL` Symbol + accessor in `runStepByStep`, extend `MachineState.debugBreak.cause`. **Do NOT add `debugRun` method** — `DebugSession` is constructed directly.
+- **Create** `packages/machine/src/classes/DebugSession.ts` — the new debugger-session class (~300 LOC).
+- **Create** `packages/machine/src/classes/DebugSession.spec.ts` — focused tests for session lifecycle + events + step controls + throttle + click-pause.
+- **Modify** `packages/machine/src/index.ts` — export `DebugSession` + its event/option types. Do NOT export `MACHINE_STATE_INTERNAL` or the internal `ResumeDirective`.
+- **Modify existing test files** that used the removed `run({onPause, onStep, onIter})` API — migrate to `debugRun()`.
+  - `packages/machine/src/classes/TuringMachine.debug.spec.ts`
+  - `packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts`
+- **Modify** `packages/machine/README.md` — rewrite "Debugging breakpoints" section around `debugRun()`; add v7 migration subsection.
+
+---
+
+## Task 1: Type scaffolding
+
+**Files:**
+- Modify: `packages/machine/src/classes/TuringMachine.ts`
+
+- [ ] **Step 1: Extend `DebugBreak` on `MachineState` with `cause`**
+
+In `TuringMachine.ts` near the existing `MachineState` type:
+
+```ts
+export type DebugBreak = {
+  before?: true;
+  after?: true;
+  cause: 'breakpoint' | 'step' | 'manual';
+};
+
+// Update MachineState.debugBreak field type to use this:
+debugBreak?: DebugBreak;
+```
+
+- [ ] **Step 2: Define the internal `ResumeDirective` type (NOT exported from package index)**
+
+```ts
+/** @internal — used by DebugSession's loop coordination. NOT part of public API. */
+export type ResumeDirective = 'continue' | 'step-in' | 'step-over' | 'step-out';
+```
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: PASS
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/machine/src/classes/TuringMachine.ts
+git commit -m "types: add DebugBreak.cause + internal ResumeDirective (#102)"
+```
+
+---
+
+## Task 2: `MACHINE_STATE_INTERNAL` accessor for halt-stack snapshot
+
+**Files:**
+- Modify: `packages/machine/src/classes/TuringMachine.ts`
+
+- [ ] **Step 1: Define the Symbol and accessor shape**
+
+Near the top of `TuringMachine.ts`:
+
+```ts
+/** @internal — used by DebugSession to read halt-stack at yield time. Same pattern as STATE_INTERNAL (#180). */
+export const MACHINE_STATE_INTERNAL = Symbol('machineState/internal');
+
+export type MachineStateInternal = {
+  /** Halt-stack at yield time (BEFORE applyCommand / pop / push for this iter). Frozen. */
+  stack: readonly State[];
+};
+```
+
+- [ ] **Step 2: Attach the accessor on every yielded `MachineState` in `runStepByStep`**
+
+In `runStepByStep`, before the existing `yield yielded` (line 257), add:
+
+```ts
+Object.defineProperty(yielded, MACHINE_STATE_INTERNAL, {
+  value: (): MachineStateInternal => ({stack: Object.freeze(stack.slice())}),
+  enumerable: false,
+});
+```
+
+- [ ] **Step 3: Test that the accessor returns a frozen snapshot**
+
+In a new file `packages/machine/src/classes/DebugSession.spec.ts` (we'll add more tests here in later tasks):
+
+```ts
+import {describe, it, expect} from 'vitest';
+import {Alphabet, Tape, TapeBlock, State, TuringMachine, haltState} from '../index.js';
+import {MACHINE_STATE_INTERNAL} from './TuringMachine.js';
+
+describe('MACHINE_STATE_INTERNAL', () => {
+  it('exposes a frozen halt-stack snapshot on every yielded machine state', () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const inner = new State({[tapeBlock.symbol([['_']])]: {nextState: halt}});
+    const outer = inner.withOverriddenHaltState(halt);
+    const machine = new TuringMachine(tapeBlock);
+
+    const yields = [...machine.runStepByStep({initialState: outer})];
+    expect(yields.length).toBeGreaterThan(0);
+    for (const m of yields) {
+      const internal = (m as any)[MACHINE_STATE_INTERNAL]();
+      expect(Array.isArray(internal.stack)).toBe(true);
+      expect(Object.isFrozen(internal.stack)).toBe(true);
+    }
+  });
+});
+```
+
+- [ ] **Step 4: Run test**
+
+Run: `npx vitest run packages/machine/src/classes/DebugSession.spec.ts -t "MACHINE_STATE_INTERNAL"`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/TuringMachine.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(engine): MACHINE_STATE_INTERNAL halt-stack accessor (#102)"
+```
+
+---
+
+## Task 3: `DebugSession` class skeleton
+
+**Files:**
+- Create: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Write a failing test for session creation + halt event**
+
+Add to `DebugSession.spec.ts`:
+
+```ts
+import {DebugSession} from './DebugSession.js';
+
+describe('DebugSession skeleton', () => {
+  it('creates a session and emits halt on completion', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0']})]);
+    const halt = new State({[tapeBlock.symbol([['0']])]: {nextState: haltState}});
+    const machine = new TuringMachine(tapeBlock);
+
+    const session = machine.debugRun({initialState: halt});
+    let haltFired = false;
+    session.on('halt', () => { haltFired = true; });
+    await session.start();
+    expect(haltFired).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run packages/machine/src/classes/DebugSession.spec.ts -t "skeleton"`
+Expected: FAIL — `DebugSession` doesn't exist yet, `machine.debugRun` doesn't exist yet.
+
+- [ ] **Step 3: Implement `DebugSession.ts` skeleton**
+
+Create the file with:
+
+```ts
+import {State} from './State.js';
+import {TuringMachine, MACHINE_STATE_INTERNAL} from './TuringMachine.js';
+import type {MachineState, MachineStateInternal} from './TuringMachine.js';
+
+export type DebugSessionEvent = 'pause' | 'step' | 'iter' | 'halt';
+export type DebugSessionListener<E extends DebugSessionEvent> =
+  E extends 'halt' ? () => void : (machineState: MachineState) => void;
+
+export type DebugSessionParameter = {
+  initialState: State;
+  stepsLimit?: number;
+};
+
+export class DebugSession {
+  readonly #machine: TuringMachine;
+  readonly #parameter: DebugSessionParameter;
+  readonly #listeners = {
+    pause: [] as Array<(m: MachineState) => void>,
+    step: [] as Array<(m: MachineState) => void>,
+    iter: [] as Array<(m: MachineState) => void>,
+    halt: [] as Array<() => void>,
+  };
+  #started = false;
+
+  constructor(machine: TuringMachine, parameter: DebugSessionParameter) {
+    this.#machine = machine;
+    this.#parameter = parameter;
+  }
+
+  on<E extends DebugSessionEvent>(event: E, listener: DebugSessionListener<E>): this {
+    (this.#listeners[event] as any[]).push(listener);
+    return this;
+  }
+
+  off<E extends DebugSessionEvent>(event: E, listener: DebugSessionListener<E>): this {
+    const arr = this.#listeners[event] as any[];
+    const ix = arr.indexOf(listener);
+    if (ix >= 0) arr.splice(ix, 1);
+    return this;
+  }
+
+  async start(): Promise<void> {
+    if (this.#started) throw new Error('DebugSession already started');
+    this.#started = true;
+
+    for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
+      // Hooks for events to be wired in subsequent tasks.
+      void machineState;
+    }
+    for (const fn of this.#listeners.halt) fn();
+  }
+}
+```
+
+- [ ] **Step 4: Add `debugRun()` method to `TuringMachine`**
+
+In `TuringMachine.ts`:
+
+```ts
+import {DebugSession} from './DebugSession.js';
+import type {DebugSessionParameter} from './DebugSession.js';
+
+// inside the class, alongside run() and runStepByStep():
+debugRun(parameter: DebugSessionParameter): DebugSession {
+  return new DebugSession(this, parameter);
+}
+```
+
+- [ ] **Step 5: Re-export from `packages/machine/src/index.ts`**
+
+Add: `export {DebugSession} from './classes/DebugSession.js';`
+And: `export type {DebugSessionEvent, DebugSessionListener, DebugSessionParameter} from './classes/DebugSession.js';`
+
+- [ ] **Step 6: Run test to verify PASS**
+
+Run: `npx vitest run packages/machine/src/classes/DebugSession.spec.ts -t "skeleton"`
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/TuringMachine.ts packages/machine/src/classes/DebugSession.spec.ts packages/machine/src/index.ts
+git commit -m "feat(engine): DebugSession skeleton + debugRun() (#102)"
+```
+
+---
+
+## Task 4: `step` event
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing test**
+
+```ts
+describe('DebugSession: step event', () => {
+  it('emits step on every iter, in order', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '0', '0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+
+    const steps: number[] = [];
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    session.on('step', (m) => steps.push(m.step));
+    await session.start();
+    expect(steps).toEqual([1, 2, 3, 4]);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify FAIL** (no step emission yet).
+
+- [ ] **Step 3: Wire step emission inside `DebugSession.start()`**
+
+Replace the loop body in `start()`:
+
+```ts
+for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
+  for (const fn of this.#listeners.step) fn(machineState);
+}
+```
+
+- [ ] **Step 4: Run test to verify PASS**
+
+Run: `npx vitest run packages/machine/src/classes/DebugSession.spec.ts -t "step event"`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): step event (#102)"
+```
+
+---
+
+## Task 5: `pause` event + `continue()` resume
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing test**
+
+```ts
+describe('DebugSession: pause + continue', () => {
+  it('emits pause on debugBreak match and resumes when continue() is called', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+    move.debug = {before: ['0']};
+
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    const causes: ('breakpoint' | 'step' | 'manual' | undefined)[] = [];
+    session.on('pause', (m) => {
+      causes.push(m.debugBreak?.cause);
+      session.continue();
+    });
+    await session.start();
+    expect(causes).toEqual(['breakpoint', 'breakpoint']);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify FAIL.**
+
+- [ ] **Step 3: Implement pause/resume coordination in `DebugSession.start()`**
+
+Add private state and method:
+
+```ts
+#pauseResolver: (() => void) | null = null;
+#activeStepMode: ResumeDirective | null = null;
+#clickTimeTopFrame: State | null = null;
+
+continue(): void {
+  this.#activeStepMode = null;
+  this.#clickTimeTopFrame = null;
+  this.#pauseResolver?.();
+  this.#pauseResolver = null;
+}
+```
+
+Rewrite the loop in `start()`:
+
+```ts
+async start(): Promise<void> {
+  if (this.#started) throw new Error('DebugSession already started');
+  this.#started = true;
+
+  for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
+    const dispatchBeforePause = machineState.debugBreak?.before === true;
+    const dispatchAfterPause = machineState.debugBreak?.after === true;
+
+    if (dispatchBeforePause) {
+      await this.#dispatchPause(machineState, {before: true, cause: 'breakpoint'});
+    }
+    for (const fn of this.#listeners.step) fn(machineState);
+    if (dispatchAfterPause) {
+      await this.#dispatchPause(machineState, {after: true, cause: 'breakpoint'});
+    }
+  }
+  for (const fn of this.#listeners.halt) fn();
+}
+
+async #dispatchPause(machineState: MachineState, debugBreak: DebugBreak): Promise<void> {
+  this.#activeStepMode = null;  // one-shot drop BEFORE dispatch
+  this.#clickTimeTopFrame = null;
+  const machineStateWithCause: MachineState = {...machineState, debugBreak};
+  for (const fn of this.#listeners.pause) fn(machineStateWithCause);
+  await new Promise<void>((resolve) => {
+    this.#pauseResolver = resolve;
+  });
+}
+```
+
+- [ ] **Step 4: Import `ResumeDirective` + `DebugBreak` types into `DebugSession.ts`**
+
+- [ ] **Step 5: Run test PASS**
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): pause event + continue() (#102)"
+```
+
+---
+
+## Task 6: `stepIn()` method
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing test**
+
+```ts
+describe('DebugSession: stepIn', () => {
+  it('forces a pause on the next iter regardless of debugBreak', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '0', '0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+    move.debug = {before: ['0']};
+
+    let pauseCount = 0;
+    const pauseSteps: number[] = [];
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    session.on('pause', (m) => {
+      pauseCount += 1;
+      pauseSteps.push(m.step);
+      if (pauseCount === 1) session.stepIn();
+      else session.continue();
+    });
+    await session.start();
+    expect(pauseSteps[0]).toBe(1);  // initial breakpoint
+    expect(pauseSteps[1]).toBe(2);  // step-in forced (no debugBreak on iter 2... wait, breakpoint still matches; test below for non-breakpoint case)
+  });
+
+  it('emits cause: step when the pause is from step-in', async () => {
+    // Set up a state that only matches debug on iter 1, then step-in forces an iter-2 pause.
+    const alphabet = new Alphabet({symbolList: ['_', '0', '1']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '1']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['1']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+    move.debug = {before: ['0']};  // only iter 1 matches (it sees '0')
+
+    const causes: string[] = [];
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    let first = true;
+    session.on('pause', (m) => {
+      causes.push(m.debugBreak!.cause);
+      if (first) {
+        first = false;
+        session.stepIn();
+      } else {
+        session.continue();
+      }
+    });
+    await session.start();
+    expect(causes).toEqual(['breakpoint', 'step']);
+  });
+});
+```
+
+- [ ] **Step 2: Run test FAIL.**
+
+- [ ] **Step 3: Implement `stepIn()`**
+
+Add to `DebugSession`:
+
+```ts
+stepIn(): void {
+  this.#activeStepMode = 'step-in';
+  this.#clickTimeTopFrame = null;
+  this.#pauseResolver?.();
+  this.#pauseResolver = null;
+}
+```
+
+Modify the `start()` loop to honor `#activeStepMode === 'step-in'`:
+
+```ts
+for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
+  const dispatchBeforePause =
+    machineState.debugBreak?.before === true
+    || this.#activeStepMode === 'step-in';
+  const dispatchAfterPause = machineState.debugBreak?.after === true;
+
+  if (dispatchBeforePause) {
+    const cause: 'breakpoint' | 'step' =
+      machineState.debugBreak?.before ? 'breakpoint' : 'step';
+    await this.#dispatchPause(machineState, {before: true, cause});
+  }
+  for (const fn of this.#listeners.step) fn(machineState);
+  if (dispatchAfterPause) {
+    const cause: 'breakpoint' | 'step' =
+      machineState.debugBreak?.after ? 'breakpoint' : 'step';
+    await this.#dispatchPause(machineState, {after: true, cause});
+  }
+}
+```
+
+- [ ] **Step 4: Run tests PASS.**
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): stepIn() (#102)"
+```
+
+---
+
+## Task 7: `stepOver()` with click-time frame snapshot
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing tests**
+
+```ts
+describe('DebugSession: stepOver', () => {
+  it('pauses at first iter after click-time top-frame is no longer on the stack', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0']})]);
+    const halt = new State({[tapeBlock.symbol([['0']])]: {nextState: haltState}});
+    const innerBare = new State({[tapeBlock.symbol([['0']])]: {nextState: halt}});
+    const wrapper = innerBare.withOverriddenHaltState(halt);
+    innerBare.debug = {before: ['0']};  // pause on first iter inside wrapper
+
+    let pauses = 0;
+    let resumedAtStep = -1;
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: wrapper});
+    session.on('pause', (m) => {
+      pauses += 1;
+      if (pauses === 1) session.stepOver();
+      else {
+        resumedAtStep = m.step;
+        session.continue();
+      }
+    });
+    await session.start();
+    expect(resumedAtStep).toBeGreaterThan(1);
+  });
+
+  it('with empty click-time stack, behaves like stepIn', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+    move.debug = {before: ['0']};
+
+    const pauseSteps: number[] = [];
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    session.on('pause', (m) => {
+      pauseSteps.push(m.step);
+      if (pauseSteps.length === 1) session.stepOver();
+      else session.continue();
+    });
+    await session.start();
+    expect(pauseSteps[1]).toBe(2);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests FAIL.**
+
+- [ ] **Step 3: Implement `stepOver()` + endpoint detection**
+
+Add method:
+
+```ts
+stepOver(): void {
+  this.#activeStepMode = 'step-over';
+  this.#clickTimeTopFrame = this.#capturedTopFrame;  // captured at pause-dispatch time (see below)
+  this.#pauseResolver?.();
+  this.#pauseResolver = null;
+}
+```
+
+Add `#capturedTopFrame` field, snapshot it in `#dispatchPause` before listeners fire (consumers may call `stepOver()` synchronously from the listener):
+
+```ts
+#capturedTopFrame: State | null = null;
+
+async #dispatchPause(machineState: MachineState, debugBreak: DebugBreak): Promise<void> {
+  this.#activeStepMode = null;
+  this.#clickTimeTopFrame = null;
+  // Snapshot the pre-iter stack top so stepOver/stepOut have it available.
+  const internal: MachineStateInternal = (machineState as any)[MACHINE_STATE_INTERNAL]();
+  this.#capturedTopFrame = internal.stack.length > 0 ? internal.stack[internal.stack.length - 1] : null;
+  const machineStateWithCause: MachineState = {...machineState, debugBreak};
+  for (const fn of this.#listeners.pause) fn(machineStateWithCause);
+  await new Promise<void>((resolve) => { this.#pauseResolver = resolve; });
+}
+```
+
+Extend the loop's `dispatchBeforePause` predicate:
+
+```ts
+const readStack = (m: MachineState): readonly State[] =>
+  (m as any)[MACHINE_STATE_INTERNAL]?.().stack ?? [];
+
+const stepOverEndpoint =
+  this.#activeStepMode === 'step-over'
+  && (this.#clickTimeTopFrame === null || !readStack(machineState).includes(this.#clickTimeTopFrame));
+
+const dispatchBeforePause =
+  machineState.debugBreak?.before === true
+  || this.#activeStepMode === 'step-in'
+  || stepOverEndpoint;
+```
+
+- [ ] **Step 4: Run tests PASS.**
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): stepOver() with frame snapshot (#102)"
+```
+
+---
+
+## Task 8: `stepOut()` + empty-stack error
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing tests**
+
+```ts
+describe('DebugSession: stepOut', () => {
+  it('pauses at first iter after click-time top-frame is popped', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0']})]);
+    const halt = new State({[tapeBlock.symbol([['0']])]: {nextState: haltState}});
+    const innerBare = new State({[tapeBlock.symbol([['0']])]: {nextState: halt}});
+    const wrapper = innerBare.withOverriddenHaltState(halt);
+    innerBare.debug = {before: ['0']};
+
+    let pauses = 0;
+    let resumedAtStep = -1;
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: wrapper});
+    session.on('pause', (m) => {
+      pauses += 1;
+      if (pauses === 1) session.stepOut();
+      else { resumedAtStep = m.step; session.continue(); }
+    });
+    await session.start();
+    expect(resumedAtStep).toBeGreaterThan(1);
+  });
+
+  it('throws when called with an empty click-time stack', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const top = new State({[tapeBlock.symbol([['0']])]: {nextState: halt}});
+    top.debug = {before: ['0']};
+
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: top});
+    const errors: Error[] = [];
+    session.on('pause', () => {
+      try { session.stepOut(); } catch (e) { errors.push(e as Error); session.continue(); }
+    });
+    await session.start();
+    expect(errors.length).toBe(1);
+    expect(errors[0].message).toMatch(/step-out.*empty/i);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests FAIL.**
+
+- [ ] **Step 3: Implement `stepOut()` + empty-stack throw**
+
+```ts
+stepOut(): void {
+  if (this.#capturedTopFrame === null) {
+    throw new Error('Cannot step-out from an empty click-time halt-stack — there is no enclosing frame to exit.');
+  }
+  this.#activeStepMode = 'step-out';
+  this.#clickTimeTopFrame = this.#capturedTopFrame;
+  this.#pauseResolver?.();
+  this.#pauseResolver = null;
+}
+```
+
+Add step-out endpoint to the loop's predicate (same shape as step-over):
+
+```ts
+const stepOutEndpoint =
+  this.#activeStepMode === 'step-out'
+  && this.#clickTimeTopFrame !== null
+  && !readStack(machineState).includes(this.#clickTimeTopFrame);
+
+const dispatchBeforePause =
+  machineState.debugBreak?.before === true
+  || this.#activeStepMode === 'step-in'
+  || stepOverEndpoint
+  || stepOutEndpoint;
+```
+
+- [ ] **Step 4: Run tests PASS.**
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): stepOut() + empty-stack guard (#102)"
+```
+
+---
+
+## Task 9: One-shot rule lock-in test
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Test that an inner breakpoint drops the step-mode (one-shot)**
+
+```ts
+describe('DebugSession: one-shot rule', () => {
+  it('drops active step-mode when an inner breakpoint fires before the natural endpoint', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0']})]);
+    const halt = new State({[tapeBlock.symbol([['0']])]: {nextState: haltState}});
+    const innerBare = new State({[tapeBlock.symbol([['0']])]: {nextState: halt}});
+    const wrapper = innerBare.withOverriddenHaltState(halt);
+    innerBare.debug = {before: ['0']};
+    halt.debug = {before: ['0']};
+
+    const causes: string[] = [];
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: wrapper});
+    let first = true;
+    session.on('pause', (m) => {
+      causes.push(m.debugBreak!.cause);
+      if (first) { first = false; session.stepOver(); }
+      else session.continue();
+    });
+    await session.start();
+    // Both pauses are breakpoints — the inner halt-bound break dropped step-over.
+    expect(causes).toEqual(['breakpoint', 'breakpoint']);
+  });
+});
+```
+
+- [ ] **Step 2: Run test PASS** (already implemented correctly by Tasks 5-8 — this locks the behavior).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "test(DebugSession): lock in one-shot step-mode rule (#102)"
+```
+
+---
+
+## Task 10: `iter` event + `setRunInterval()` throttle
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing test**
+
+```ts
+describe('DebugSession: iter event + throttle', () => {
+  it('emits iter at end of each iter and respects setRunInterval', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+
+    const iters: number[] = [];
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    session.setRunInterval(5);
+    session.on('iter', (m) => iters.push(m.step));
+    const start = Date.now();
+    await session.start();
+    const elapsed = Date.now() - start;
+    expect(iters).toEqual([1, 2, 3]);
+    expect(elapsed).toBeGreaterThanOrEqual(10);  // at least 2 throttle waits of 5ms
+  });
+});
+```
+
+- [ ] **Step 2: Run test FAIL.**
+
+- [ ] **Step 3: Implement `setRunInterval()` + iter emission + throttle**
+
+```ts
+#runIntervalMs = 0;
+
+setRunInterval(ms: number): void {
+  if (ms < 0 || !Number.isFinite(ms)) throw new Error('runInterval must be a non-negative finite number');
+  this.#runIntervalMs = ms;
+}
+```
+
+In the `start()` loop, at the end of each iter:
+
+```ts
+for (const fn of this.#listeners.iter) fn(machineState);
+if (this.#runIntervalMs > 0) {
+  await new Promise<void>((resolve) => setTimeout(resolve, this.#runIntervalMs));
+}
+```
+
+- [ ] **Step 4: Run test PASS.**
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): iter event + setRunInterval throttle (#102)"
+```
+
+---
+
+## Task 11: External `pause()` (click-pause from outside)
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing test**
+
+```ts
+describe('DebugSession: external pause()', () => {
+  it('triggers a pause event with cause: manual on the next iter', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '0', '0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+
+    const causes: string[] = [];
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    session.setRunInterval(2);
+    let iterCount = 0;
+    session.on('iter', () => {
+      iterCount += 1;
+      if (iterCount === 1) session.pause();  // request pause from outside
+    });
+    session.on('pause', (m) => {
+      causes.push(m.debugBreak!.cause);
+      session.continue();
+    });
+    await session.start();
+    expect(causes).toEqual(['manual']);
+  });
+});
+```
+
+- [ ] **Step 2: Run test FAIL.**
+
+- [ ] **Step 3: Implement `pause()` + manual-pause detection in loop**
+
+```ts
+#pauseRequested = false;
+
+pause(): void {
+  this.#pauseRequested = true;
+}
+```
+
+In the loop, before the existing `dispatchBeforePause` calculation, intercept the manual flag:
+
+```ts
+const manualPause = this.#pauseRequested;
+if (manualPause) {
+  this.#pauseRequested = false;
+}
+
+const dispatchBeforePause =
+  machineState.debugBreak?.before === true
+  || this.#activeStepMode === 'step-in'
+  || stepOverEndpoint
+  || stepOutEndpoint
+  || manualPause;
+
+// Inside the dispatchBeforePause block, derive cause:
+const beforeCause: 'breakpoint' | 'step' | 'manual' =
+  manualPause ? 'manual'
+  : machineState.debugBreak?.before ? 'breakpoint'
+  : 'step';
+```
+
+- [ ] **Step 4: Run test PASS.**
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): external pause() with cause: manual (#102)"
+```
+
+---
+
+## Task 12: `stop()` (immediate termination)
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.ts`
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Failing test**
+
+```ts
+describe('DebugSession: stop', () => {
+  it('terminates the session and resolves start() without halt event', async () => {
+    const alphabet = new Alphabet({symbolList: ['_', '0']});
+    const tapeBlock = TapeBlock.fromTapes([new Tape({alphabet, symbolList: ['0', '0', '0', '0', '0']})]);
+    const halt = new State({[tapeBlock.symbol([['_']])]: {nextState: haltState}});
+    const ref = new Reference();
+    const move = new State({
+      [tapeBlock.symbol([['0']])]: {command: [{movement: movements.right}], nextState: ref},
+      [tapeBlock.symbol([['_']])]: {nextState: halt},
+    });
+    ref.bind(move);
+
+    let haltFired = false;
+    const machine = new TuringMachine(tapeBlock);
+    const session = machine.debugRun({initialState: move});
+    session.on('halt', () => { haltFired = true; });
+    session.on('iter', (m) => {
+      if (m.step === 2) session.stop();
+    });
+    await session.start();
+    expect(haltFired).toBe(false);  // stopped before halt
+  });
+});
+```
+
+- [ ] **Step 2: Run test FAIL.**
+
+- [ ] **Step 3: Implement `stop()`**
+
+```ts
+#stopped = false;
+
+stop(): void {
+  this.#stopped = true;
+  this.#pauseResolver?.();
+  this.#pauseResolver = null;
+}
+```
+
+In the loop, check `#stopped` at the top of each iter and break:
+
+```ts
+for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
+  if (this.#stopped) break;
+  // ... existing iter body ...
+  if (this.#stopped) break;  // also check after listeners
+}
+if (!this.#stopped) {
+  for (const fn of this.#listeners.halt) fn();
+}
+```
+
+- [ ] **Step 4: Run test PASS.**
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.ts packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "feat(DebugSession): stop() (#102)"
+```
+
+---
+
+## Task 13: Strip callbacks from `run()`, make sync, migrate existing tests
+
+**Files:**
+- Modify: `packages/machine/src/classes/TuringMachine.ts`
+- Modify: `packages/machine/src/classes/TuringMachine.debug.spec.ts`
+- Modify: `packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts`
+- Modify: any other test files using `run({onPause | onStep | onIter | debug})`
+
+- [ ] **Step 1: Grep for all consumers of the removed callback API**
+
+Run: `grep -rn "onPause\|onStep\|onIter" packages/machine/src/ packages/builder/src/ packages/library-binary-numbers/src/ packages/library-binary-numbers-bare/src/ test/`
+
+Expected: a list of all files using callbacks. Each must be migrated to `debugRun()`.
+
+- [ ] **Step 2: Update `TuringMachine.run()` to be sync, callback-free**
+
+Replace the existing `run(...)` method with:
+
+```ts
+run({initialState, stepsLimit}: RunParameter): void {
+  for (const _ of this.runStepByStep({initialState, stepsLimit})) {
+    // pure execution, no observation
+  }
+}
+```
+
+Remove `onPause`, `onStep`, `onIter`, `debug` fields from `RunParameter` (or rename it `RunParameter` for clarity that this is now the small surface). Remove unused imports.
+
+- [ ] **Step 3: Migrate each test file from `grep` results**
+
+For each `run({onPause: ..., ...})` call site, transform:
+
+Before:
+```ts
+await machine.run({
+  initialState,
+  onPause: (m) => { observed.push(m); },
+});
+```
+
+After:
+```ts
+const session = machine.debugRun({initialState});
+session.on('pause', (m) => {
+  observed.push(m);
+  session.continue();
+});
+await session.start();
+```
+
+Similarly for `onStep` → `session.on('step', ...)`, `onIter` → `session.on('iter', ...)`, `debug: false` → simply use `run()` instead of `debugRun()`.
+
+- [ ] **Step 4: Run full test suite**
+
+Run: `npm test`
+Expected: PASS — every test migrated.
+
+- [ ] **Step 5: Run lint + typecheck**
+
+Run: `npm run lint && npm run typecheck`
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/machine/src/ packages/builder/src/ packages/library-binary-numbers/src/ packages/library-binary-numbers-bare/src/ test/
+git commit -m "refactor(engine): run() is sync + callback-free; migrate tests to debugRun() (#102)"
+```
+
+---
+
+## Task 14: Coverage + edge-case tests
+
+**Files:**
+- Modify: `packages/machine/src/classes/DebugSession.spec.ts`
+
+- [ ] **Step 1: Add tests for these edge cases**
+
+```ts
+describe('DebugSession: edge cases', () => {
+  it('throws when start() is called twice', async () => {
+    // ...
+  });
+
+  it('removes a listener via off()', async () => {
+    // ...
+  });
+
+  it('start() resolves on natural halt with no listeners attached', async () => {
+    // ...
+  });
+
+  it('handles state.debug.after pauses + step controls together', async () => {
+    // ...
+  });
+
+  it('haltState.debug = true fires pause with cause: breakpoint', async () => {
+    // ...
+  });
+});
+```
+
+Fill in concrete test bodies based on the patterns above.
+
+- [ ] **Step 2: Run coverage**
+
+Run: `npm run test:coverage`
+Expected: All v7 floors met (97/90/95/97 per `vitest.config.ts`).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add packages/machine/src/classes/DebugSession.spec.ts
+git commit -m "test(DebugSession): edge cases + coverage (#102)"
+```
+
+---
+
+## Task 15: README rewrite + migration guide
+
+**Files:**
+- Modify: `packages/machine/README.md`
+
+- [ ] **Step 1: Find and rewrite the "Debugging breakpoints" section**
+
+Replace with a new "Debugging" section structured around `debugRun()`:
+
+```markdown
+## Debugging
+
+For pure execution with no observation overhead:
+
+\`\`\`ts
+machine.run({initialState});  // synchronous; returns when halted
+\`\`\`
+
+For per-iter tracing without breakpoint-driven flow:
+
+\`\`\`ts
+for (const m of machine.runStepByStep({initialState})) {
+  trace(m);
+}
+\`\`\`
+
+For interactive debugging — breakpoints, step-in/over/out, throttle, click-pause:
+
+\`\`\`ts
+const session = machine.debugRun({initialState});
+session.on('pause', (m) => {
+  console.log('paused at', m.state.name, 'cause:', m.debugBreak.cause);
+  session.stepIn();  // or stepOver(), stepOut(), continue(), stop()
+});
+session.on('halt', () => console.log('done'));
+await session.start();
+\`\`\`
+
+### Breakpoints
+
+`state.debug = {before: [...], after: [...]}` sets a per-symbol breakpoint filter. `haltState.debug = true` pauses on every halt (program exit + subroutine return). [Existing breakpoint docs...]
+
+### Step controls
+
+| Method | Behavior |
+|---|---|
+| `session.continue()` | Resume until next breakpoint or halt |
+| `session.stepIn()` | Pause on the very next iter |
+| `session.stepOver()` | Pause at first iter after click-time top halt-frame is no longer on the stack; with an empty click-time stack, collapses to `stepIn` |
+| `session.stepOut()` | Pause at first iter after click-time top halt-frame is popped; throws if click-time stack is empty |
+| `session.pause()` | Request a pause from outside the loop; fires on the next iter with `cause: 'manual'` |
+| `session.stop()` | Terminate immediately; no `halt` event fires |
+
+**One-shot rule:** any `pause` event (breakpoint, step endpoint, manual) drops the active step-mode. To continue stepping, call `stepIn/Over/Out` again from the new pause.
+
+### Throttle
+
+`session.setRunInterval(ms)` inserts an awaited delay at the end of every iter — useful for visualizing execution.
+
+### Events
+
+| Event | Argument | Fires |
+|---|---|---|
+| `pause` | `MachineState` (with `debugBreak.cause`) | Breakpoint match, step endpoint, or manual `pause()` |
+| `step` | `MachineState` | Once per iter, between any before-pause and after-pause |
+| `iter` | `MachineState` | Once per iter, at end (after any after-pause) |
+| `halt` | (none) | Once, on natural halt (not on `stop()`) |
+```
+
+- [ ] **Step 2: Add a v7 migration subsection**
+
+```markdown
+### v7 migration — `run({onPause, ...})` removed
+
+v7 splits the execution API into three non-overlapping entry points:
+
+\`\`\`ts
+// v6
+await machine.run({
+  initialState,
+  onPause: (m) => { ... },
+  onStep: (m) => { ... },
+  onIter: (m) => { ... },
+});
+
+// v7
+const session = machine.debugRun({initialState});
+session.on('pause', (m) => { ... session.continue(); });
+session.on('step', (m) => { ... });
+session.on('iter', (m) => { ... });
+await session.start();
+\`\`\`
+
+If you weren't using callbacks, `machine.run({initialState})` still works — it's now synchronous and returns `void`. Drop the `await`.
+
+If you only used `onStep` for tracing, the generator `machine.runStepByStep({initialState})` is the equivalent shape:
+
+\`\`\`ts
+for (const m of machine.runStepByStep({initialState})) {
+  trace(m);
+}
+\`\`\`
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add packages/machine/README.md
+git commit -m "docs: rewrite Debugging section around debugRun() + v7 migration (#102)"
+```
+
+---
+
+## Task 16: Final verification + PR
+
+- [ ] **Step 1: Run full quality gate**
+
+```bash
+npm run lint && npm run typecheck && npm test && npm run test:coverage
+```
+
+Expected: all PASS. Coverage floors met.
+
+- [ ] **Step 2: Open the PR targeting `v7`**
+
+```bash
+gh pr create --base v7 --title "feat(engine): run() + debugRun() + DebugSession (#102)" --body "$(cat <<'EOF'
+## Summary
+
+Closes #102 — the v7-stable gating issue. Splits `TuringMachine`'s execution API into three non-overlapping entry points:
+
+- `machine.run({initialState})` — pure execution, synchronous, no observation overhead.
+- `machine.runStepByStep({initialState})` — sync generator, per-iter observation (unchanged).
+- `machine.debugRun({initialState})` — returns a `DebugSession` with events (pause/step/iter/halt), step controls (continue/stepIn/stepOver/stepOut), external `pause()`/`stop()`, and `setRunInterval()` throttle.
+
+The v6 `run({onPause, onStep, onIter, debug})` shape is removed (breaking change, fits cleanly in v7's major version).
+
+## Breaking changes
+
+- `run()` is now synchronous (`void`, not `Promise<void>`).
+- `run({onPause | onStep | onIter | debug})` removed. Use `debugRun()`.
+
+Migration documented in the README.
+
+## Out of scope (follow-ups)
+
+- `@post-machine-js/machine` adoption (`pm.run()` + `pm.debugRun()`) — separate issue.
+- `machines-demo` worker migration — separate issue.
+- CHANGELOG entry lands in the alpha.6 release PR per `project_v7_release_checklist` convention.
+EOF
+)"
+```
+
+- [ ] **Step 3: After CI green, manually close #102** with a comment pointing to this PR + the eventual alpha.6 release.
+
+---
+
+## Self-review notes
+
+- All four step controls (continue / stepIn / stepOver / stepOut) plus pause / stop have dedicated tasks with tests.
+- Throttle (`setRunInterval`) is a first-class session method, not bolted onto another API.
+- External `pause()` introduces the third `DebugBreak.cause` value ('manual') and has its own task.
+- One-shot rule has a dedicated lock-in test.
+- Empty-stack `stepOut` throws (IDE convention).
+- `run()` becomes sync; `runStepByStep` unchanged; `debugRun()` is async via `start()`.
+- v7 migration documented in README.
+- Engine-only scope; post-machine-js adoption and machines-demo migration are separate follow-ups.
+- No placeholders: every step has actual code or actual commands with expected outputs.

From 19312fbdaa2fbb1d1dcef708f1a3f3bfdcd96ca1 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 18:48:02 +0300
Subject: [PATCH 066/118] test(DebugSession): cover stop()-during-throttle +
 stop()-between-after-pause-and-iter (#102)

---
 .../machine/src/classes/DebugSession.spec.ts  | 31 +++++++++++++++++++
 packages/machine/src/classes/DebugSession.ts  |  5 +++
 2 files changed, 36 insertions(+)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index 62b1e8d..76d113b 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -484,6 +484,37 @@ describe('DebugSession: pause event + continue()', () => {
     expect(iters).toEqual([1, 2]);  // stop took effect at end of iter 2
   });
 
+  it('stop() called between an after-pause and the iter event terminates without iter fire', async () => {
+    // Arms after-pause; stop() called inside pause listener should terminate
+    // the loop before the iter event fires for that iter.
+    const {machine, state} = buildWalker(['A']);
+    state.debug = {after: true};
+    const session = new DebugSession(machine, {initialState: state});
+    let iterFired = false;
+    session.on('pause', () => {
+      session.stop();
+    });
+    session.on('iter', () => { iterFired = true; });
+    await session.start();
+    expect(iterFired).toBe(false);
+  });
+
+  it('stop() called during a throttle wait terminates without further iters', async () => {
+    // Throttle inserts a setTimeout between iters. stop() called from inside
+    // an iter listener (the throttle hasn't started yet) takes effect when the
+    // loop re-checks the flag at the next iter's top.
+    const {machine, state} = buildWalker(['A', 'A', 'A']);
+    const session = new DebugSession(machine, {initialState: state});
+    session.setRunInterval(2);
+    const iters: number[] = [];
+    session.on('iter', (m) => {
+      iters.push(m.step);
+      if (m.step === 1) session.stop();
+    });
+    await session.start();
+    expect(iters).toEqual([1]);
+  });
+
   it('stop() called from inside a pause listener terminates immediately', async () => {
     const {machine, state} = buildWalker(['A', 'A']);
     state.debug = {before: true};
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 7cab468..1ae0b19 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -222,6 +222,11 @@ export default class DebugSession {
     const stack = this.#readStack(machineState);
     this.#capturedTopFrame = stack.length > 0 ? stack[stack.length - 1] : null;
 
+    // Note: the spread drops the non-enumerable MACHINE_STATE_INTERNAL Symbol
+    // accessor — that's intentional. Pause listeners are public API; the
+    // Symbol accessor is package-private and only consumed by the session's
+    // OWN endpoint detection (which reads the original `machineState`,
+    // not `paused`, via #readStack above).
     const paused: MachineState = {...machineState, debugBreak};
     const pausePromise = new Promise<void>((resolve) => {
       this.#pauseResolver = resolve;

From 663019f8c25bdfa19ff212839a3bc4b985446305 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Mon, 25 May 2026 22:34:51 +0300
Subject: [PATCH 067/118] =?UTF-8?q?fix(DebugSession):=20await=20iter=20lis?=
 =?UTF-8?q?teners=20=E2=80=94=20restore=20v6=20onIter=20coordination=20con?=
 =?UTF-8?q?tract=20(#102)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The v6 `onIter` callback was awaited by the engine — that contract is
what downstream consumers (the machines-demo worker in particular)
rely on for:

- Per-iter throttle (RUNNING_AUTO: setTimeout between iters drives
  visualization pacing).
- Step-boundary synthesis (RUNNING_STEP: dispatch a synthetic pause at
  end-of-iter when the user clicked Step).
- Any "wait between iters" coordination where the consumer genuinely
  needs the engine to block until its work completes.

The skeleton commit landed iter as fire-and-forget, which broke both
RUNNING_STEP and RUNNING_AUTO in machines-demo (engine kept advancing
under the synthetic pause / throttle await, racing the postMessage
roundtrips).

Fix: iter listeners are now awaited (sequenced, blocking) — same shape
as v6 `onIter`. The other three events keep their contracts:
- `pause` — implicitly gated by the internal #pauseResolver (resumed
  by session.continue() etc); listener Promise itself stays
  fire-and-forget.
- `step` — fire-and-forget, matches v6 onStep.
- `halt` — fire-and-forget (terminal).

Reported by RG against the local-linked adoption in machines-demo:
"RUNNING_STEP, RUNNING_AUTO - do not work. debugger stops seem to be
fine. steps after debugger stop - works." Breakpoint-driven pauses
worked because they were gated by the pause-promise; iter-driven
coordination was the regression. This restores it.

Engine tests unchanged (534 pass). README updated to clarify the
per-event dispatch contract.
---
 packages/machine/README.md                   | 14 +++++-----
 packages/machine/src/classes/DebugSession.ts | 28 ++++++++++++++------
 2 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index 046a81e..b38da92 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -551,16 +551,16 @@ The `debug` field is mutable — toggle breakpoints at runtime without rebuildin
 | `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. Listeners may return `void` or `Promise<void>` — the session fires them and continues without awaiting (Node `EventEmitter` semantics). |
+| `on(event, listener) / off(event, listener)` | Register / unregister listeners. Multiple listeners per event are supported. Listener dispatch differs by event — see *Events* below. |
 
 ### Events
 
-| Event | Argument | Fires |
-|---|---|---|
-| `pause` | `MachineState` (with `debugBreak.cause`) | A breakpoint matched, a step-mode endpoint was reached, or `session.pause()` was requested. Loop blocks until a resume method (`continue / stepIn / stepOver / stepOut / stop`) is called. |
-| `step` | `MachineState` | Once per iter, between any before-pause and after-pause. Fire-and-forget. |
-| `iter` | `MachineState` | Once per iter, at end. After any after-pause. |
-| `halt` | (none) | Once, on natural halt. Does NOT fire when `stop()` was called. |
+| Event | Argument | Dispatch | Fires |
+|---|---|---|---|
+| `pause` | `MachineState` (with `debugBreak.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. |
 
 ### `MachineState.debugBreak.cause`
 
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 1ae0b19..7e8aaca 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -13,13 +13,21 @@ export type DebugSessionParameter = {
 export type DebugSessionEvent = 'pause' | 'step' | 'iter' | 'halt';
 
 /**
- * Listener signatures by event. Listeners may return `void` or `Promise<void>` —
- * the session calls them fire-and-forget, matching Node's `EventEmitter`
- * contract: async listeners run to completion on their own, but the session
- * does NOT await them. Async control flow (pause/resume) is gated by the
- * session's own resume methods (continue / stepIn / stepOver / stepOut / stop)
- * rather than listener return values, because the resume signal is fundamentally
- * external to the listener's call site (UI click, postMessage, timer, etc.).
+ * 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.
  */
 export type DebugSessionListener<E extends DebugSessionEvent> =
   E extends 'halt'
@@ -298,9 +306,13 @@ export default class DebugSession {
       }
 
       // iter: end-of-iter, after both before- and after-pause have fired.
+      // Listeners are AWAITED (sequenced, blocking the engine) — matches the
+      // v6 `onIter` contract that downstream consumers rely on for
+      // throttle / per-iter coordination / step-boundary synthesis.
       for (const fn of this.#listeners.iter) {
-        void fn(machineState);
+        await fn(machineState);
       }
+      if (this.#stopped) return;
 
       if (this.#runIntervalMs > 0) {
         await new Promise<void>((resolve) => setTimeout(resolve, this.#runIntervalMs));

From a3355b2316c3c8db6c75b34270bffb36cfd4af43 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 28 May 2026 21:03:15 +0300
Subject: [PATCH 068/118] feat(DebugSession): clear error on concurrent
 session; document cause precedence (#102)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- start() catches the low-level TapeBlock 'Lock check failed' (thrown
  when another DebugSession or a bare run() already holds the machine's
  tape lock) and rethrows a cause-naming message: "a run is already in
  progress on this machine...". The loop body moves to a private
  #drive(); an #iterating guard scopes the remap to the startup
  lock-acquisition only (a same-named error can't originate once we hold
  the lock). The existing lock already enforced single-active-run
  correctness — this is purely a DX message upgrade.

- New test: a second concurrent session on the same machine rejects with
  the clear message while the first holds a pause.

- Spec test rename: the local `halt` State (a regular state that
  transitions to the haltState singleton, used as a wrapper continuation)
  → `haltWrapper`, so it no longer reads as the `haltState` singleton.

- README: document the pause-cause precedence (breakpoint > step >
  manual) — exactly one pause fires per iter; the highest-precedence
  trigger names the cause. Was implicit in code + tests; now explicit.

535 tests pass; coverage above floors (DebugSession.ts 97/91.52).
---
 packages/machine/README.md                    |   8 ++
 .../machine/src/classes/DebugSession.spec.ts  | 104 +++++++++++-------
 packages/machine/src/classes/DebugSession.ts  |  23 ++++
 3 files changed, 95 insertions(+), 40 deletions(-)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index b38da92..947b301 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -570,6 +570,14 @@ When the `pause` event fires, `m.debugBreak.cause` distinguishes the origin:
 - `'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.
diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index 76d113b..fa6f2e4 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -14,8 +14,8 @@ const buildSimple = () => {
   const tapeBlock = TapeBlock.fromTapes([tape]);
   const machine = new TuringMachine({tapeBlock});
   const {symbol} = tapeBlock;
-  const halt = new State({[symbol(['A'])]: {nextState: haltState}});
-  return {machine, halt, tapeBlock};
+  const haltWrapper = new State({[symbol(['A'])]: {nextState: haltState}});
+  return {machine, haltWrapper, tapeBlock};
 };
 
 const readInternal = (m: unknown): MachineStateInternal =>
@@ -23,9 +23,9 @@ const readInternal = (m: unknown): MachineStateInternal =>
 
 describe('MACHINE_STATE_INTERNAL accessor on yielded MachineState', () => {
   it('exposes a frozen halt-stack snapshot on every iter', () => {
-    const {machine, halt} = buildSimple();
-    const inner = halt;
-    const outer = inner.withOverriddenHaltState(halt);
+    const {machine, haltWrapper} = buildSimple();
+    const inner = haltWrapper;
+    const outer = inner.withOverriddenHaltState(haltWrapper);
 
     const yields = [...machine.runStepByStep({initialState: outer})];
 
@@ -38,31 +38,31 @@ describe('MACHINE_STATE_INTERNAL accessor on yielded MachineState', () => {
   });
 
   it("does NOT include the accessor in enumerable spread / toEqual", () => {
-    const {machine, halt} = buildSimple();
+    const {machine, haltWrapper} = buildSimple();
 
-    const [m] = [...machine.runStepByStep({initialState: halt})];
+    const [m] = [...machine.runStepByStep({initialState: haltWrapper})];
     // Enumerable spread must NOT include the symbol-keyed accessor.
     expect(Object.keys(m)).not.toContain(MACHINE_STATE_INTERNAL.toString());
     // toEqual on the visible shape must succeed even though the symbol prop is present.
-    expect(m).toEqual(expect.objectContaining({state: halt, step: 1}));
+    expect(m).toEqual(expect.objectContaining({state: haltWrapper, step: 1}));
   });
 
   it('captures the PRE-iter stack (snapshot taken before this iter advances)', () => {
-    const {machine, halt} = buildSimple();
-    const outer = halt.withOverriddenHaltState(halt);
+    const {machine, haltWrapper} = buildSimple();
+    const outer = haltWrapper.withOverriddenHaltState(haltWrapper);
 
     const [first] = [...machine.runStepByStep({initialState: outer})];
     const internal = readInternal(first);
-    // Iter 1 is inside the wrapper — the wrapper's overriddenHaltState (halt) is on the stack.
+    // Iter 1 is inside the wrapper — the wrapper's overriddenHaltState (haltWrapper) is on the stack.
     expect(internal.stack.length).toBe(1);
-    expect(internal.stack[0]).toBe(halt);
+    expect(internal.stack[0]).toBe(haltWrapper);
   });
 });
 
 describe('DebugSession skeleton', () => {
   it('runs to natural halt and fires the halt listener', async () => {
-    const {machine, halt} = buildSimple();
-    const session = new DebugSession(machine, {initialState: halt});
+    const {machine, haltWrapper} = buildSimple();
+    const session = new DebugSession(machine, {initialState: haltWrapper});
     let halted = false;
     session.on('halt', () => { halted = true; });
     await session.start();
@@ -70,8 +70,8 @@ describe('DebugSession skeleton', () => {
   });
 
   it("doesn't fire halt when stop() is called", async () => {
-    const {machine, halt} = buildSimple();
-    const session = new DebugSession(machine, {initialState: halt});
+    const {machine, haltWrapper} = buildSimple();
+    const session = new DebugSession(machine, {initialState: haltWrapper});
     let halted = false;
     session.on('halt', () => { halted = true; });
     session.stop();
@@ -80,15 +80,39 @@ describe('DebugSession skeleton', () => {
   });
 
   it('throws on a second start() call', async () => {
-    const {machine, halt} = buildSimple();
-    const session = new DebugSession(machine, {initialState: halt});
+    const {machine, haltWrapper} = buildSimple();
+    const session = new DebugSession(machine, {initialState: haltWrapper});
     await session.start();
     await expect(session.start()).rejects.toThrow(/already been called/);
   });
 
+  it('rejects a second concurrent session on the same machine with a clear error', async () => {
+    // Two sessions on one machine fight over the single TapeBlock lock. The
+    // first to start holds it while paused; the second's start() should reject
+    // with a cause-naming message, NOT the low-level 'Lock check failed'.
+    const {machine, state} = buildWalker(['A', 'A']);
+    state.debug = {before: true};
+
+    const sessionA = new DebugSession(machine, {initialState: state});
+    let aPaused = false;
+    sessionA.on('pause', () => { aPaused = true; /* hold the pause — don't resume */ });
+    // Start A but don't await — it parks on the first before-pause, holding the lock.
+    const aPromise = sessionA.start();
+    // Yield a macrotask so A reaches its first pause.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(aPaused).toBe(true);
+
+    const sessionB = new DebugSession(machine, {initialState: state});
+    await expect(sessionB.start()).rejects.toThrow(/already in progress on this machine/);
+
+    // Clean up A so the test doesn't leak a held lock.
+    sessionA.stop();
+    await aPromise;
+  });
+
   it('off() removes a previously registered listener', async () => {
-    const {machine, halt} = buildSimple();
-    const session = new DebugSession(machine, {initialState: halt});
+    const {machine, haltWrapper} = buildSimple();
+    const session = new DebugSession(machine, {initialState: haltWrapper});
     let fired = 0;
     const handler = () => { fired += 1; };
     session.on('halt', handler);
@@ -246,7 +270,7 @@ describe('DebugSession: pause event + continue()', () => {
 
   it('stepOver() pauses at the first iter after click-time top-frame is no longer on the stack', async () => {
     // Setup: outer wrapper around an inner state. Click-time stack at iter 1
-    // (inside outer's bare) contains the wrapper's overriddenHaltState (= halt).
+    // (inside outer's bare) contains the wrapper's overriddenHaltState (= haltWrapper).
     // stepOver should run until that frame is gone — which happens at iter 2,
     // when the inner halts → halt-pop → state advances to halt; iter 2's pause
     // fires because the stack is now empty.
@@ -255,9 +279,9 @@ describe('DebugSession: pause event + continue()', () => {
     const tapeBlock = TapeBlock.fromTapes([tape]);
     const machine = new TuringMachine({tapeBlock});
     const {symbol} = tapeBlock;
-    const halt = new State({[symbol(['A'])]: {nextState: haltState}, [symbol([' '])]: {nextState: haltState}});
-    const inner = new State({[symbol(['A'])]: {nextState: halt}, [symbol([' '])]: {nextState: halt}});
-    const outer = inner.withOverriddenHaltState(halt);
+    const haltWrapper = new State({[symbol(['A'])]: {nextState: haltState}, [symbol([' '])]: {nextState: haltState}});
+    const inner = new State({[symbol(['A'])]: {nextState: haltWrapper}, [symbol([' '])]: {nextState: haltWrapper}});
+    const outer = inner.withOverriddenHaltState(haltWrapper);
     inner.debug = {before: true};
 
     const session = new DebugSession(machine, {initialState: outer});
@@ -318,9 +342,9 @@ describe('DebugSession: pause event + continue()', () => {
     const tapeBlock = TapeBlock.fromTapes([tape]);
     const machine = new TuringMachine({tapeBlock});
     const {symbol} = tapeBlock;
-    const halt = new State({[symbol(['A'])]: {nextState: haltState}, [symbol([' '])]: {nextState: haltState}});
-    const inner = new State({[symbol(['A'])]: {nextState: halt}, [symbol([' '])]: {nextState: halt}});
-    const outer = inner.withOverriddenHaltState(halt);
+    const haltWrapper = new State({[symbol(['A'])]: {nextState: haltState}, [symbol([' '])]: {nextState: haltState}});
+    const inner = new State({[symbol(['A'])]: {nextState: haltWrapper}, [symbol([' '])]: {nextState: haltWrapper}});
+    const outer = inner.withOverriddenHaltState(haltWrapper);
     inner.debug = {before: true};
 
     const session = new DebugSession(machine, {initialState: outer});
@@ -380,19 +404,19 @@ describe('DebugSession: pause event + continue()', () => {
     const machine = new TuringMachine({tapeBlock});
     const {symbol} = tapeBlock;
 
-    const halt = new State({
+    const haltWrapper = new State({
       [symbol(['A'])]: {nextState: haltState},
       [symbol(['B'])]: {nextState: haltState},
       [symbol([' '])]: {nextState: haltState},
     });
     const inner = new State({
-      [symbol(['A'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}], nextState: halt},
-      [symbol(['B'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}], nextState: halt},
-      [symbol([' '])]: {nextState: halt},
+      [symbol(['A'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}], nextState: haltWrapper},
+      [symbol(['B'])]: {command: [{symbol: symbolCommands.keep, movement: movements.right}], nextState: haltWrapper},
+      [symbol([' '])]: {nextState: haltWrapper},
     });
-    const outer = inner.withOverriddenHaltState(halt);
-    inner.debug = {before: [symbol(['A'])]};   // matches iter 1
-    halt.debug = {before: true};               // matches when control reaches halt's pre-iter
+    const outer = inner.withOverriddenHaltState(haltWrapper);
+    inner.debug = {before: [symbol(['A'])]};       // matches iter 1
+    haltWrapper.debug = {before: true};            // matches when control reaches haltWrapper's pre-iter
 
     const session = new DebugSession(machine, {initialState: outer});
     const causes: string[] = [];
@@ -440,8 +464,8 @@ describe('DebugSession: pause event + continue()', () => {
   });
 
   it('setRunInterval rejects negative / NaN / Infinity', () => {
-    const {machine, halt} = buildSimple();
-    const session = new DebugSession(machine, {initialState: halt});
+    const {machine, haltWrapper} = buildSimple();
+    const session = new DebugSession(machine, {initialState: haltWrapper});
     expect(() => session.setRunInterval(-1)).toThrow();
     expect(() => session.setRunInterval(NaN)).toThrow();
     expect(() => session.setRunInterval(Infinity)).toThrow();
@@ -532,8 +556,8 @@ describe('DebugSession: pause event + continue()', () => {
   });
 
   it('multiple listeners on the same event all fire', async () => {
-    const {machine, halt} = buildSimple();
-    const session = new DebugSession(machine, {initialState: halt});
+    const {machine, haltWrapper} = buildSimple();
+    const session = new DebugSession(machine, {initialState: haltWrapper});
     let countA = 0;
     let countB = 0;
     session.on('step', () => { countA += 1; });
@@ -544,8 +568,8 @@ describe('DebugSession: pause event + continue()', () => {
   });
 
   it('continue() / stepIn() / stepOver() are no-op when no pause is active', () => {
-    const {machine, halt} = buildSimple();
-    const session = new DebugSession(machine, {initialState: halt});
+    const {machine, haltWrapper} = buildSimple();
+    const session = new DebugSession(machine, {initialState: haltWrapper});
     // No pause active — these must not throw.
     expect(() => session.continue()).not.toThrow();
     expect(() => session.stepIn()).not.toThrow();
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 7e8aaca..9771272 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -71,6 +71,7 @@ export default class DebugSession {
   };
   #started = false;
   #stopped = false;
+  #iterating = false;
   #pauseResolver: (() => void) | null = null;
   #activeStepMode: ResumeDirective | null = null;
   /**
@@ -260,7 +261,29 @@ export default class DebugSession {
     }
     this.#started = true;
 
+    try {
+      await this.#drive();
+    } catch (error) {
+      // `runStepByStep` acquires the TapeBlock lock at its first advance. If
+      // another DebugSession (or a bare `run()`) is already active on this
+      // machine, that acquisition throws the low-level 'Lock check failed'.
+      // Remap it to a message that names the real cause. The `#iterating`
+      // guard scopes the remap to the startup acquisition only — once we hold
+      // the lock and are iterating, a same-named error can't originate here.
+      if (!this.#iterating && error instanceof Error && error.message === 'Lock check failed') {
+        throw new Error(
+          'Cannot start this DebugSession: a run is already in progress on this machine. '
+          + 'Only one DebugSession or run() may be active on a TuringMachine at a time — '
+          + 'stop the active session (or let it halt) before starting another.',
+        );
+      }
+      throw error;
+    }
+  }
+
+  async #drive(): Promise<void> {
     for (const machineState of this.#machine.runStepByStep(this.#parameter)) {
+      this.#iterating = true;
       if (this.#stopped) return;
 
       const hasBeforeBreakpoint = machineState.debugBreak?.before === true;

From aacc11b51de12752955b886149fcf0b97790bf20 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 28 May 2026 21:04:20 +0300
Subject: [PATCH 069/118] test(DebugSession): use performance.now() for
 throttle timing (monotonic)

---
 packages/machine/src/classes/DebugSession.spec.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index fa6f2e4..17b5295 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -456,9 +456,9 @@ describe('DebugSession: pause event + continue()', () => {
     const {machine, state} = buildWalker(['A', 'A']);
     const session = new DebugSession(machine, {initialState: state});
     session.setRunInterval(5);
-    const start = Date.now();
+    const start = performance.now();
     await session.start();
-    const elapsed = Date.now() - start;
+    const elapsed = performance.now() - start;
     // 3 iters total (2 A's + 1 blank-halt); 3 throttle waits of 5ms each ≥ 15ms.
     expect(elapsed).toBeGreaterThanOrEqual(10);
   });

From 473638226ff6dcffa02b70798f453c5d32b6c3f3 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 28 May 2026 22:30:24 +0300
Subject: [PATCH 070/118] refactor(engine): runStepByStep minimal; breakpoint
 detection + merged pause side move to DebugSession (#102)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

runStepByStep is now the pure-iteration primitive: it advances the
machine and reports a minimal MachineState, doing NO breakpoint
detection. `MachineState` loses `debugBreak` entirely.

Breakpoint detection moves into DebugSession, which is the only thing
that reacts to breakpoints. Its `pause` event carries the descriptor on
a new field:

  m.pause: { side: 'before' | 'after', cause: 'breakpoint' | 'step' | 'manual' }

Because DebugSession dispatches before/after as separate pause events,
the descriptor is always one-sided — so the old dual-optional
`{ before?, after? }` (which only existed to model the raw-yield "both
timings matched on one iter" set) collapses to a single required `side`.
Renamed `debugBreak` → `pause` to reflect that it now describes the
pause, not a detected break on a raw yield.

Mechanics:
- New `PauseInfo` + `PausedMachineState` types; `DebugBreak` removed.
- `matchFilter` exported (@internal) for sibling-module use in
  DebugSession; the generator no longer calls it (no per-iter
  DebugConfig lazy-alloc on the pure path).
- MACHINE_STATE_INTERNAL gains `matchedSymbol` (so DebugSession evaluates
  state.debug filters without re-reading the tape) and `haltImminent`
  (raw pre-pop nextState === haltState, so halt-imminent pauses still
  fire on subroutine-return/halt-pop iters where the yielded nextState
  is the post-pop continuation).
- DebugSessionListener split: `pause` → PausedMachineState; step/iter →
  MachineState.

Tests: the raw-yield detection suites in TuringMachine.debug.spec are
rewritten as DebugSession-driven (a collectPauses helper); pause-event
assertions switch debugBreak.before/after → pause.side. builder + engine
example specs updated likewise. README: MachineState field table drops
debugBreak; Debugging section documents m.pause {side, cause}; the
detection/reaction split is made explicit.

536 tests pass; coverage above floors (DebugSession 98.01/91.04,
TuringMachine 98.24/97.05).
---
 packages/builder/src/builder.spec.ts          |   6 +-
 packages/machine/README.md                    |  27 +-
 .../machine/src/classes/DebugSession.spec.ts  |  36 +--
 packages/machine/src/classes/DebugSession.ts  |  70 +++--
 .../src/classes/TuringMachine.debug.spec.ts   | 269 ++++++++----------
 .../machine/src/classes/TuringMachine.spec.ts |   3 +-
 packages/machine/src/classes/TuringMachine.ts | 101 ++++---
 packages/machine/src/index.ts                 |   2 +-
 test/examples.spec.ts                         |   6 +-
 9 files changed, 261 insertions(+), 259 deletions(-)

diff --git a/packages/builder/src/builder.spec.ts b/packages/builder/src/builder.spec.ts
index fc7cac2..ea96975 100644
--- a/packages/builder/src/builder.spec.ts
+++ b/packages/builder/src/builder.spec.ts
@@ -136,7 +136,7 @@ describe('buildMachine — debug config (#101)', () => {
     let afterCount = 0;
     const session = new DebugSession(machine, {initialState: init});
     session.on('pause', (m) => {
-      if (m.debugBreak?.after) afterCount += 1;
+      if (m.pause.side === 'after') afterCount += 1;
       session.continue();
     });
     await session.start();
@@ -158,8 +158,8 @@ describe('buildMachine — debug config (#101)', () => {
     let afterCount = 0;
     const session = new DebugSession(machine, {initialState: init});
     session.on('pause', (m) => {
-      if (m.debugBreak?.before) beforeCount += 1;
-      if (m.debugBreak?.after) afterCount += 1;
+      if (m.pause.side === 'before') beforeCount += 1;
+      if (m.pause.side === 'after') afterCount += 1;
       session.continue();
     });
     await session.start();
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 947b301..8aa715e 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -329,7 +329,6 @@ 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, cause: 'breakpoint' \| 'step' \| 'manual' }` | only set when this iter is a pause point. `cause` identifies the origin (engine breakpoint vs DebugSession step / manual). See *Debugging* 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.
@@ -344,12 +343,12 @@ Three non-overlapping entry points, picked by the consumer's actual need:
 | Observation | none | per-iter via `.next()` | event-based (`pause`, `step`, `iter`, `halt`) |
 | Step controls | — | — | `continue / stepIn / stepOver / stepOut / pause / stop` |
 | Throttle | — | — | `setRunInterval(ms)` |
-| Breakpoint dispatch | breakpoints fire-and-resume invisibly | `debugBreak` field on each yield; consumer reads it | `pause` event fires with `cause: 'breakpoint'` |
+| 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`.
 
-The `debugBreak` metadata is on every yielded `MachineState` regardless of which entry point you used — `runStepByStep` consumers can read it directly, `DebugSession` consumers see it on the `pause` event payload.
+**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
 
@@ -489,7 +488,7 @@ import { DebugSession } from '@turing-machine-js/machine';
 const session = new DebugSession(machine, { initialState });
 
 session.on('pause', (m) => {
-  console.log(`paused at ${m.state.name}, cause: ${m.debugBreak.cause}`);
+  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 */ });
@@ -529,7 +528,7 @@ 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`.
+> ⚠️ **`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`). **Always use the whole-object form: `haltState.debug = true` / `= false` / `= null`.**
 
@@ -557,18 +556,20 @@ The `debug` field is mutable — toggle breakpoints at runtime without rebuildin
 
 | Event | Argument | Dispatch | Fires |
 |---|---|---|---|
-| `pause` | `MachineState` (with `debugBreak.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. |
+| `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. |
 
-### `MachineState.debugBreak.cause`
+### The pause descriptor: `m.pause`
 
-When the `pause` event fires, `m.debugBreak.cause` distinguishes the origin:
+`pause` listeners receive a `PausedMachineState` — a plain `MachineState` plus a `pause: { side, cause }` descriptor (raw `runStepByStep` yields have no such field).
 
-- `'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.
+- **`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:
 
@@ -669,7 +670,7 @@ for (const m of machine.runStepByStep({ initialState })) {
 }
 ```
 
-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 and ignore the `debugBreak` field.
+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+.)
 
@@ -828,7 +829,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.
diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index 17b5295..ca2acda 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -159,34 +159,34 @@ describe('DebugSession: step event', () => {
 });
 
 describe('DebugSession: pause event + continue()', () => {
-  it('emits pause on debugBreak.before match with cause: breakpoint', async () => {
+  it('emits pause on before-side match with cause: breakpoint', async () => {
     const {machine, state} = buildWalker(['A', 'A']);
     state.debug = {before: true};
     const session = new DebugSession(machine, {initialState: state});
-    const pauses: Array<{step: number; before?: true; after?: true; cause: string}> = [];
+    const pauses: Array<{step: number; side: string; cause: string}> = [];
     session.on('pause', (m) => {
-      pauses.push({step: m.step, ...m.debugBreak!});
+      pauses.push({step: m.step, ...m.pause});
       session.continue();
     });
     await session.start();
     // Three iters total (iter 1 = A, iter 2 = A, iter 3 = blank → halt);
     // {before: true} matches every symbol so all three pause.
     expect(pauses).toEqual([
-      {step: 1, before: true, cause: 'breakpoint'},
-      {step: 2, before: true, cause: 'breakpoint'},
-      {step: 3, before: true, cause: 'breakpoint'},
+      {step: 1, side: 'before', cause: 'breakpoint'},
+      {step: 2, side: 'before', cause: 'breakpoint'},
+      {step: 3, side: 'before', cause: 'breakpoint'},
     ]);
   });
 
-  it('emits pause on debugBreak.after match too', async () => {
+  it('emits pause on after-side match too', async () => {
     const {machine, state} = buildWalker(['A']);
     state.debug = {after: true};
     const session = new DebugSession(machine, {initialState: state});
     const causes: Array<{side: string; cause: string}> = [];
     session.on('pause', (m) => {
       causes.push({
-        side: m.debugBreak!.before ? 'before' : 'after',
-        cause: m.debugBreak!.cause,
+        side: m.pause.side,
+        cause: m.pause.cause,
       });
       session.continue();
     });
@@ -255,7 +255,7 @@ describe('DebugSession: pause event + continue()', () => {
     const causes: Array<{step: number; cause: string}> = [];
     let firstHandled = false;
     session.on('pause', (m) => {
-      causes.push({step: m.step, cause: m.debugBreak!.cause});
+      causes.push({step: m.step, cause: m.pause.cause});
       if (!firstHandled) {
         firstHandled = true;
         session.stepIn();
@@ -288,7 +288,7 @@ describe('DebugSession: pause event + continue()', () => {
     const pauses: Array<{step: number; cause: string}> = [];
     let firstHandled = false;
     session.on('pause', (m) => {
-      pauses.push({step: m.step, cause: m.debugBreak!.cause});
+      pauses.push({step: m.step, cause: m.pause.cause});
       if (!firstHandled) {
         firstHandled = true;
         session.stepOver();
@@ -351,7 +351,7 @@ describe('DebugSession: pause event + continue()', () => {
     const pauses: Array<{step: number; cause: string}> = [];
     let firstHandled = false;
     session.on('pause', (m) => {
-      pauses.push({step: m.step, cause: m.debugBreak!.cause});
+      pauses.push({step: m.step, cause: m.pause.cause});
       if (!firstHandled) {
         firstHandled = true;
         session.stepOut();
@@ -422,7 +422,7 @@ describe('DebugSession: pause event + continue()', () => {
     const causes: string[] = [];
     let firstHandled = false;
     session.on('pause', (m) => {
-      causes.push(m.debugBreak!.cause);
+      causes.push(m.pause.cause);
       if (!firstHandled) {
         firstHandled = true;
         session.stepOver();
@@ -443,7 +443,7 @@ describe('DebugSession: pause event + continue()', () => {
     const order: string[] = [];
     session.on('step', (m) => { order.push(`step-${m.step}`); });
     session.on('pause', (m) => {
-      order.push(`pause-${m.step}-${m.debugBreak!.after ? 'after' : 'before'}`);
+      order.push(`pause-${m.step}-${m.pause.side}`);
       session.continue();
     });
     session.on('iter', (m) => { order.push(`iter-${m.step}`); });
@@ -486,7 +486,7 @@ describe('DebugSession: pause event + continue()', () => {
       }
     });
     session.on('pause', (m) => {
-      causes.push(m.debugBreak!.cause);
+      causes.push(m.pause.cause);
       session.continue();
     });
     await session.start();
@@ -586,7 +586,7 @@ describe('DebugSession: pause event + continue()', () => {
     // and a pending manual request. The breakpoint cause wins.
     session.pause();
     session.on('pause', (m) => {
-      observedCause = observedCause ?? m.debugBreak!.cause;
+      observedCause = observedCause ?? m.pause.cause;
       session.continue();
     });
     await session.start();
@@ -602,8 +602,8 @@ describe('DebugSession: pause event + continue()', () => {
       session.on('pause', (m) => {
         pauses.push({
           step: m.step,
-          side: m.debugBreak!.after ? 'after' : 'before',
-          cause: m.debugBreak!.cause,
+          side: m.pause.side,
+          cause: m.pause.cause,
         });
         session.continue();
       });
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 9771272..6c61b6f 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -1,5 +1,13 @@
-import State from './State';
-import TuringMachine, {MACHINE_STATE_INTERNAL, type DebugBreak, type MachineState, type MachineStateInternal, type ResumeDirective} from './TuringMachine';
+import State, {haltState} from './State';
+import TuringMachine, {
+  MACHINE_STATE_INTERNAL,
+  matchFilter,
+  type MachineState,
+  type MachineStateInternal,
+  type PauseInfo,
+  type PausedMachineState,
+  type ResumeDirective,
+} from './TuringMachine';
 
 /**
  * Parameters mirror `TuringMachine.runStepByStep` / `run`. DebugSession passes
@@ -28,14 +36,20 @@ export type DebugSessionEvent = 'pause' | 'step' | 'iter' | 'halt';
  *   `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>
-    : (machineState: MachineState) => void | Promise<void>;
+    : E extends 'pause'
+      ? (machineState: PausedMachineState) => void | Promise<void>
+      : (machineState: MachineState) => void | Promise<void>;
 
 type ListenerMap = {
-  pause: Array<(m: MachineState) => void | Promise<void>>;
+  pause: Array<(m: PausedMachineState) => void | Promise<void>>;
   step: Array<(m: MachineState) => void | Promise<void>>;
   iter: Array<(m: MachineState) => void | Promise<void>>;
   halt: Array<() => void | Promise<void>>;
@@ -212,8 +226,8 @@ export default class DebugSession {
   }
 
   /**
-   * Emit a `pause` event with the synthesized debugBreak and await the consumer's
-   * resume signal. Resolver is installed BEFORE listeners fire so a listener
+   * Emit a `pause` event with the synthesized pause descriptor and await the
+   * consumer's resume signal. Resolver is installed BEFORE listeners fire so a listener
    * that synchronously calls `session.continue()` (or any other resume method)
    * sees a live resolver to drop.
    *
@@ -225,7 +239,7 @@ export default class DebugSession {
    * `stepOver` / `stepOut` issued from inside the listener can freeze it as
    * the click-time frame.
    */
-  async #dispatchPause(machineState: MachineState, debugBreak: DebugBreak): Promise<void> {
+  async #dispatchPause(machineState: MachineState, pause: PauseInfo): Promise<void> {
     this.#activeStepMode = null;
     this.#clickTimeTopFrame = null;
     const stack = this.#readStack(machineState);
@@ -234,9 +248,8 @@ export default class DebugSession {
     // Note: the spread drops the non-enumerable MACHINE_STATE_INTERNAL Symbol
     // accessor — that's intentional. Pause listeners are public API; the
     // Symbol accessor is package-private and only consumed by the session's
-    // OWN endpoint detection (which reads the original `machineState`,
-    // not `paused`, via #readStack above).
-    const paused: MachineState = {...machineState, debugBreak};
+    // OWN detection (which reads the original `machineState` via #readInternal).
+    const paused: PausedMachineState = {...machineState, pause};
     const pausePromise = new Promise<void>((resolve) => {
       this.#pauseResolver = resolve;
     });
@@ -246,13 +259,16 @@ export default class DebugSession {
     await pausePromise;
   }
 
-  // Reads the pre-iter halt-stack snapshot installed by `runStepByStep`.
-  // Returns empty if the accessor is missing (defensive — shouldn't happen
-  // with the engine on this branch).
-  #readStack(machineState: MachineState): readonly State[] {
+  // Reads the per-iter internal accessor installed by `runStepByStep` (halt
+  // stack + matched symbol). Returns null if the accessor is missing
+  // (defensive — shouldn't happen with the engine on this branch).
+  #readInternal(machineState: MachineState): MachineStateInternal | null {
     const fn = (machineState as unknown as Record<symbol, () => MachineStateInternal>)[MACHINE_STATE_INTERNAL];
-    if (typeof fn !== 'function') return [];
-    return fn().stack;
+    return typeof fn === 'function' ? fn() : null;
+  }
+
+  #readStack(machineState: MachineState): readonly State[] {
+    return this.#readInternal(machineState)?.stack ?? [];
   }
 
   async start(): Promise<void> {
@@ -286,8 +302,20 @@ export default class DebugSession {
       this.#iterating = true;
       if (this.#stopped) return;
 
-      const hasBeforeBreakpoint = machineState.debugBreak?.before === true;
-      const hasAfterBreakpoint = machineState.debugBreak?.after === true;
+      // Breakpoint detection lives HERE (not in the generator). Evaluate the
+      // current state's debug filters against the matched symbol the generator
+      // stashed in the internal accessor. `machineState.state` is always
+      // non-halt (halt is terminal), so `.debug` is a DebugConfig at runtime.
+      // The after side also fires on halt-imminent (`haltState.debug`, #207) —
+      // read via the internal flag, since the yielded `nextState` shows the
+      // post-pop continuation on subroutine-return iters, not haltState.
+      const internal = this.#readInternal(machineState);
+      const matchedSymbol = internal?.matchedSymbol;
+      const hasBeforeBreakpoint = matchedSymbol !== undefined
+        && matchFilter(machineState.state.debug?.before, matchedSymbol);
+      const hasAfterBreakpoint = (matchedSymbol !== undefined
+        && matchFilter(machineState.state.debug?.after, matchedSymbol))
+        || (internal?.haltImminent === true && haltState.debug === true);
       const stepInForcesPause = this.#activeStepMode === 'step-in';
       const stepOverEndpointReached =
         this.#activeStepMode === 'step-over'
@@ -310,11 +338,11 @@ export default class DebugSession {
       const fireBeforePause =
         hasBeforeBreakpoint || stepInForcesPause || stepOverEndpointReached || stepOutEndpointReached || manualPauseFires;
       if (fireBeforePause) {
-        const cause: DebugBreak['cause'] =
+        const cause: PauseInfo['cause'] =
           hasBeforeBreakpoint ? 'breakpoint'
             : (stepInForcesPause || stepOverEndpointReached || stepOutEndpointReached) ? 'step'
               : 'manual';
-        await this.#dispatchPause(machineState, {before: true, cause});
+        await this.#dispatchPause(machineState, {side: 'before', cause});
         if (this.#stopped) return;
       }
 
@@ -324,7 +352,7 @@ export default class DebugSession {
       }
 
       if (hasAfterBreakpoint) {
-        await this.#dispatchPause(machineState, {after: true, cause: 'breakpoint'});
+        await this.#dispatchPause(machineState, {side: 'after', cause: 'breakpoint'});
         if (this.#stopped) return;
       }
 
diff --git a/packages/machine/src/classes/TuringMachine.debug.spec.ts b/packages/machine/src/classes/TuringMachine.debug.spec.ts
index 031b471..d9c6044 100644
--- a/packages/machine/src/classes/TuringMachine.debug.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.debug.spec.ts
@@ -38,122 +38,102 @@ const buildMachine = () => {
   return {machine, state, symbol};
 };
 
-describe('TuringMachine — debug.before filter (loop yields)', () => {
-  test('without debug, no debugBreak field on yields', async () => {
+// Drive a DebugSession to completion, collecting one record per pause event.
+// Detection now lives in DebugSession (not in runStepByStep), so filter
+// semantics are asserted through the pause stream.
+type PauseRecord = {step: number; side: 'before' | 'after'; cause: string; symbol: string};
+async function collectPauses(machine: TuringMachine, state: State): Promise<PauseRecord[]> {
+  const session = new DebugSession(machine, {initialState: state});
+  const pauses: PauseRecord[] = [];
+  session.on('pause', (m) => {
+    pauses.push({step: m.step, side: m.pause.side, cause: m.pause.cause, symbol: m.currentSymbols[0]});
+    session.continue();
+  });
+  await session.start();
+  return pauses;
+}
+
+describe('runStepByStep — no debug metadata on yields', () => {
+  test('raw yields never carry a pause/debugBreak field, regardless of state.debug', () => {
     const {machine, state} = buildMachine();
+    state.debug = {before: true, after: true};  // even with filters armed…
     const steps: MachineState[] = [];
-
     for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
 
     expect(steps).toHaveLength(VISIT_COUNT);
     for (const step of steps) {
       expect(step).not.toHaveProperty('debugBreak');
+      expect(step).not.toHaveProperty('pause');
     }
   });
+});
 
-  test('debug.before = true tags every visit with debugBreak.before', async () => {
+describe('DebugSession — before-side detection', () => {
+  test('no state.debug → no pauses', async () => {
     const {machine, state} = buildMachine();
-    state.debug = {before: true};
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
+    expect(await collectPauses(machine, state)).toEqual([]);
+  });
 
-    expect(steps).toHaveLength(VISIT_COUNT);
-    for (const step of steps) {
-      expect(step.debugBreak).toEqual({before: true, cause: 'breakpoint'});
-    }
+  test('before = true pauses on every visit, side before', async () => {
+    const {machine, state} = buildMachine();
+    state.debug = {before: true};
+    const pauses = await collectPauses(machine, state);
+    expect(pauses).toHaveLength(VISIT_COUNT);
+    for (const p of pauses) expect({side: p.side, cause: p.cause}).toEqual({side: 'before', cause: 'breakpoint'});
   });
 
-  test('debug.before with symbol list matches only listed symbols', async () => {
+  test('before with symbol list pauses only on listed symbols', async () => {
     const {machine, state, symbol} = buildMachine();
-    const symA = symbol(['A']);
-    state.debug = {before: [symA]};
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
-
-    const aVisits = steps.filter((s) => s.currentSymbols[0] === 'A');
-    const nonAVisits = steps.filter((s) => s.currentSymbols[0] !== 'A');
-
-    expect(aVisits).toHaveLength(A_VISIT_COUNT);
-    expect(nonAVisits).toHaveLength(VISIT_COUNT - A_VISIT_COUNT);
-    for (const v of aVisits) expect(v.debugBreak).toEqual({before: true, cause: 'breakpoint'});
-    for (const v of nonAVisits) expect(v).not.toHaveProperty('debugBreak');
+    state.debug = {before: [symbol(['A'])]};
+    const pauses = await collectPauses(machine, state);
+    expect(pauses).toHaveLength(A_VISIT_COUNT);
+    for (const p of pauses) expect({side: p.side, symbol: p.symbol}).toEqual({side: 'before', symbol: 'A'});
   });
 
-  test('debug.before with empty list never matches', async () => {
+  test('before with empty list never pauses', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: []};
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
-
-    expect(steps).toHaveLength(VISIT_COUNT);
-    for (const step of steps) {
-      expect(step).not.toHaveProperty('debugBreak');
-    }
+    expect(await collectPauses(machine, state)).toEqual([]);
   });
 
-  test('debug.before with [ifOtherSymbol] matches only the catch-all visit', async () => {
+  test('before with [ifOtherSymbol] pauses only on the catch-all (blank) visit', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: [ifOtherSymbol]};
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
-
-    const blankVisits = steps.filter((s) => s.currentSymbols[0] === alphabet.blankSymbol);
-    const nonBlankVisits = steps.filter((s) => s.currentSymbols[0] !== alphabet.blankSymbol);
-
-    expect(blankVisits).toHaveLength(HALT_VISIT_COUNT);
-    expect(blankVisits[0].debugBreak).toEqual({before: true, cause: 'breakpoint'});
-    for (const v of nonBlankVisits) expect(v).not.toHaveProperty('debugBreak');
+    const pauses = await collectPauses(machine, state);
+    expect(pauses).toHaveLength(HALT_VISIT_COUNT);
+    expect(pauses[0].symbol).toBe(alphabet.blankSymbol);
+    expect({side: pauses[0].side, cause: pauses[0].cause}).toEqual({side: 'before', cause: 'breakpoint'});
   });
 });
 
-describe('TuringMachine — debug.after filter (loop yields)', () => {
-  // Both `before` and `after` refer to THIS iter, dispatched on the same yield.
-
-  test('debug.after = true tags every yield with debugBreak.after', async () => {
+describe('DebugSession — after-side detection', () => {
+  test('after = true pauses on every visit, side after', async () => {
     const {machine, state} = buildMachine();
     state.debug = {after: true};
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
-
-    expect(steps).toHaveLength(VISIT_COUNT);
-    for (const step of steps) {
-      expect(step.debugBreak).toEqual({after: true, cause: 'breakpoint'});
-    }
+    const pauses = await collectPauses(machine, state);
+    expect(pauses).toHaveLength(VISIT_COUNT);
+    for (const p of pauses) expect({side: p.side, cause: p.cause}).toEqual({side: 'after', cause: 'breakpoint'});
   });
 
-  test('before AND after on same visit produce both flags on every yield', async () => {
+  test('before AND after on same visit → two pause events per iter, before then after', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true, after: true};
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
-
-    expect(steps).toHaveLength(VISIT_COUNT);
-    for (const step of steps) {
-      expect(step.debugBreak).toEqual({before: true, after: true, cause: 'breakpoint'});
+    const pauses = await collectPauses(machine, state);
+    // Each visit now produces TWO pause events (split), in before→after order.
+    expect(pauses).toHaveLength(VISIT_COUNT * 2);
+    for (let i = 0; i < pauses.length; i += 2) {
+      expect(pauses[i].side).toBe('before');
+      expect(pauses[i + 1].side).toBe('after');
+      expect(pauses[i].step).toBe(pauses[i + 1].step);
     }
   });
 
-  test('after with symbol list matches only listed symbols', async () => {
+  test('after with symbol list pauses only on listed symbols', async () => {
     const {machine, state, symbol} = buildMachine();
-    const symA = symbol(['A']);
-    state.debug = {after: [symA]};
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
-
-    expect(steps).toHaveLength(VISIT_COUNT);
-    const aHits = steps.filter((s) => s.currentSymbols[0] === 'A');
-    const nonAHits = steps.filter((s) => s.currentSymbols[0] !== 'A');
-    expect(aHits).toHaveLength(A_VISIT_COUNT);
-
-    for (const step of aHits) expect(step.debugBreak).toEqual({after: true, cause: 'breakpoint'});
-    for (const step of nonAHits) expect(step).not.toHaveProperty('debugBreak');
+    state.debug = {after: [symbol(['A'])]};
+    const pauses = await collectPauses(machine, state);
+    expect(pauses).toHaveLength(A_VISIT_COUNT);
+    for (const p of pauses) expect({side: p.side, symbol: p.symbol}).toEqual({side: 'after', symbol: 'A'});
   });
 });
 
@@ -163,39 +143,38 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     haltState.debug = false;
   });
 
-  test('haltState.debug = true fires `debugBreak.after` on the halt-triggering iter (#207)', async () => {
+  test('haltState.debug = true pauses (after-side) on the halt-triggering iter (#207)', async () => {
     const {machine, state} = buildMachine();
     haltState.debug = true;
-    const steps: MachineState[] = [];
 
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
+    const session = new DebugSession(machine, {initialState: state});
+    const pauses: Array<{step: number; side: string; cause: string; pausedState: State; nextState: State}> = [];
+    session.on('pause', (m) => {
+      pauses.push({step: m.step, side: m.pause.side, cause: m.pause.cause, pausedState: m.state, nextState: m.nextState});
+      session.continue();
+    });
+    await session.start();
 
-    expect(steps).toHaveLength(VISIT_COUNT);
-    // Only the visit whose transition leads to halt (the trailing blank →
-    // ifOtherSymbol → haltState) carries `debugBreak.after`. The earlier
-    // visits self-loop within `state`, so their nextState is `state` itself,
-    // not haltState — no halt-imminent dispatch.
-    for (let i = 0; i < VISIT_COUNT - 1; i++) {
-      expect(steps[i]).not.toHaveProperty('debugBreak');
-    }
-    const last = steps[VISIT_COUNT - 1];
-    expect(last.nextState).toBe(haltState);
-    // #207 spec: fires on AFTER side (post-iter, before halt processing).
-    // `m.state` is the TRIGGERING state (whose transition leads to halt),
-    // not haltState itself.
-    expect(last.state).toBe(state);
-    expect(last.debugBreak).toEqual({after: true, cause: 'breakpoint'});
+    // Only the visit whose transition leads to halt (trailing blank →
+    // ifOtherSymbol → haltState) pauses. Earlier visits self-loop within
+    // `state` — their nextState is `state`, not haltState.
+    expect(pauses).toHaveLength(1);
+    const p = pauses[0];
+    expect(p.step).toBe(VISIT_COUNT);
+    // #207: after-side; m.state is the TRIGGERING state, not haltState.
+    expect(p.side).toBe('after');
+    expect(p.cause).toBe('breakpoint');
+    expect(p.pausedState).toBe(state);
+    expect(p.nextState).toBe(haltState);
   });
 
-  test('haltState.debug = true fires on each halt entry — including subroutine return (halt-pop)', async () => {
-    // Custom 1-cell tape + nested-state setup. Trajectory:
+  test('haltState.debug = true pauses on each halt entry — including subroutine return (halt-pop)', async () => {
+    // Trajectory:
     //   visit 1: head 'A', state=wrapped → erase+right, transition to inner
     //   visit 2: head blank, state=inner → ifOtherSymbol → would halt;
     //            wrapped's override redirects to continuation. nextState=continuation.
-    //            #207: halt-imminent fires on AFTER side (transition's original
-    //            nextState was haltState before the pop redirect).
-    //   visit 3: head blank, state=continuation → ifOtherSymbol → halt.
-    //            #207: halt-imminent fires on AFTER side.
+    //            #207: halt-imminent → after-side pause (original nextState was haltState).
+    //   visit 3: head blank, state=continuation → ifOtherSymbol → halt → after-side pause.
     const tape = new Tape({alphabet, symbols: ['A']});
     const tapeBlock = TapeBlock.fromTapes([tape]);
     const machine = new TuringMachine({tapeBlock});
@@ -215,39 +194,28 @@ describe('TuringMachine — haltState.debug (boolean, #207)', () => {
     const wrapped = inner.withOverriddenHaltState(continuation);
 
     haltState.debug = true;
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: wrapped})) { steps.push(s); }
-
-    expect(steps).toHaveLength(3);
-
-    // Visit 1: just self-loops into inner — no halt-related break.
-    expect(steps[0]).not.toHaveProperty('debugBreak');
-
-    // Visit 2: transitions to continuation via halt-pop. `debugBreak.after`
-    // fires because the transition's original nextState was haltState (the
-    // pop-redirect to continuation happens AFTER the engine's halt check).
-    const popYield = steps.find((s) => s.nextState === continuation);
-    expect(popYield).toBeDefined();
-    expect(popYield).toBe(steps[1]);
-    expect(popYield!.debugBreak).toEqual({after: true, cause: 'breakpoint'});
+    const session = new DebugSession(machine, {initialState: wrapped});
+    const pauses: Array<{step: number; side: string; nextState: State}> = [];
+    session.on('pause', (m) => {
+      pauses.push({step: m.step, side: m.pause.side, nextState: m.nextState});
+      session.continue();
+    });
+    await session.start();
 
-    // Visit 3: transitions to halt directly. `debugBreak.after` fires.
-    expect(steps[2].nextState).toBe(haltState);
-    expect(steps[2].debugBreak).toEqual({after: true, cause: 'breakpoint'});
+    // Two halt entries: the halt-pop (→ continuation) and the final halt.
+    expect(pauses).toHaveLength(2);
+    // halt-pop visit: nextState resolves to the continuation (post-pop).
+    expect(pauses[0].side).toBe('after');
+    expect(pauses[0].nextState).toBe(continuation);
+    // final visit: transitions straight to halt.
+    expect(pauses[1].side).toBe('after');
+    expect(pauses[1].nextState).toBe(haltState);
   });
 
-  test('haltState.debug = false / null suppresses dispatch on every iter', async () => {
+  test('haltState.debug = false / null → no pauses', async () => {
     const {machine, state} = buildMachine();
     haltState.debug = false;
-    const steps: MachineState[] = [];
-
-    for (const s of machine.runStepByStep({initialState: state})) { steps.push(s); }
-
-    expect(steps).toHaveLength(VISIT_COUNT);
-    for (const step of steps) {
-      expect(step).not.toHaveProperty('debugBreak');
-    }
+    expect(await collectPauses(machine, state)).toEqual([]);
   });
 
   test('haltState.debug getter returns boolean (typed `boolean` via HaltState alias)', () => {
@@ -281,11 +249,11 @@ describe('TuringMachine — run() with onPause', () => {
   test('DebugSession pause event fires for "before" with current state', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true};
-    const seen: Array<{state: State, debugBreak?: MachineState['debugBreak']}> = [];
+    const seen: Array<{state: State, side: string; cause: string}> = [];
 
     const session = new DebugSession(machine, {initialState: state});
     session.on('pause', (m) => {
-      seen.push({state: m.state, debugBreak: m.debugBreak});
+      seen.push({state: m.state, side: m.pause.side, cause: m.pause.cause});
       session.continue();
     });
     await session.start();
@@ -293,18 +261,18 @@ describe('TuringMachine — run() with onPause', () => {
     expect(seen).toHaveLength(VISIT_COUNT);
     for (const entry of seen) {
       expect(entry.state).toBe(state);
-      expect(entry.debugBreak).toEqual({before: true, cause: 'breakpoint'});
+      expect({side: entry.side, cause: entry.cause}).toEqual({side: 'before', cause: 'breakpoint'});
     }
   });
 
   test('DebugSession pause event for "after" carries the same iter\'s state', async () => {
     const {machine, state} = buildMachine();
     state.debug = {after: true};
-    const seen: Array<{state: State, debugBreak?: MachineState['debugBreak'], step: number}> = [];
+    const seen: Array<{state: State, side: string; cause: string; step: number}> = [];
 
     const session = new DebugSession(machine, {initialState: state});
     session.on('pause', (m) => {
-      seen.push({state: m.state, debugBreak: m.debugBreak, step: m.step});
+      seen.push({state: m.state, side: m.pause.side, cause: m.pause.cause, step: m.step});
       session.continue();
     });
     await session.start();
@@ -312,24 +280,23 @@ describe('TuringMachine — run() with onPause', () => {
     expect(seen).toHaveLength(VISIT_COUNT);
     for (const entry of seen) {
       expect(entry.state).toBe(state);
-      expect(entry.debugBreak).toEqual({after: true, cause: 'breakpoint'});
+      expect({side: entry.side, cause: entry.cause}).toEqual({side: 'after', cause: 'breakpoint'});
     }
   });
 
-  test('both "before" and "after" on same yield → two pause events in lifecycle order', async () => {
+  test('both "before" and "after" on same iter → two pause events in lifecycle order', async () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true, after: true};
     const calls: Array<'before' | 'after'> = [];
 
     const session = new DebugSession(machine, {initialState: state});
     session.on('pause', (m) => {
-      if (m.debugBreak?.before) calls.push('before');
-      if (m.debugBreak?.after) calls.push('after');
+      calls.push(m.pause.side);
       session.continue();
     });
     await session.start();
 
-    // Per-iter lifecycle: before → step → after. Every yield dispatches both
+    // Per-iter lifecycle: before → step → after. Every iter dispatches both
     // pauses in this order. For VISIT_COUNT visits: [before, after, before, …]
     expect(calls).toHaveLength(VISIT_COUNT * 2);
     for (let i = 0; i < calls.length; i++) {
@@ -385,7 +352,7 @@ describe('TuringMachine — halt semantics for after-fire (#108)', () => {
 
     const session = new DebugSession(machine, {initialState: state});
     session.on('pause', (m) => {
-      if (m.debugBreak?.after) after.push(m);
+      if (m.pause.side === 'after') after.push(m);
       session.continue();
     });
     await session.start();
@@ -430,24 +397,24 @@ describe('TuringMachine — halt semantics for after-fire (#108)', () => {
   });
 });
 
-describe('debugBreak metadata on yields (no consumer dispatch)', () => {
+describe('runStepByStep ignores breakpoints entirely (detection lives in DebugSession)', () => {
   afterEach(() => { haltState.debug = null; });
 
-  // v6's `run({debug: false})` master switch is gone in v7 (callbacks moved
-  // entirely to DebugSession). The semantic that lived in those tests —
-  // "yielded MachineStates carry debugBreak metadata regardless of consumer
-  // dispatch" — still holds, and is observable by iterating `runStepByStep`
-  // directly without constructing a session.
+  // v7: breakpoint detection moved out of the generator. runStepByStep is the
+  // pure-iteration primitive — even with state.debug armed, raw yields carry
+  // NO pause/debugBreak field and iteration cadence is unchanged.
 
-  test('runStepByStep yields debugBreak metadata even without a DebugSession', () => {
+  test('raw yields carry no pause metadata even with state.debug armed', () => {
     const {machine, state} = buildMachine();
     state.debug = {before: true};
+    haltState.debug = true;
     const yields: MachineState[] = [];
     for (const m of machine.runStepByStep({initialState: state})) { yields.push(m); }
 
     expect(yields).toHaveLength(VISIT_COUNT);
     for (const y of yields) {
-      expect(y.debugBreak).toEqual({before: true, cause: 'breakpoint'});
+      expect(y).not.toHaveProperty('pause');
+      expect(y).not.toHaveProperty('debugBreak');
     }
   });
 
diff --git a/packages/machine/src/classes/TuringMachine.spec.ts b/packages/machine/src/classes/TuringMachine.spec.ts
index 7af5012..c2edefb 100644
--- a/packages/machine/src/classes/TuringMachine.spec.ts
+++ b/packages/machine/src/classes/TuringMachine.spec.ts
@@ -174,8 +174,7 @@ describe('run tests', () => {
     const session = new DebugSession(machine, {initialState, stepsLimit: 1e5});
     session.on('step', (m) => { order.push(`step-${m.step}`); });
     session.on('pause', (m) => {
-      const when = m.debugBreak?.before ? 'before' : 'after';
-      order.push(`pause-${when}-${m.step}`);
+      order.push(`pause-${m.pause.side}-${m.step}`);
       session.continue();
     });
     session.on('iter', (m) => { order.push(`iter-${m.step}`); });
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index 8ba50ec..1195ccb 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -5,20 +5,24 @@ import {symbolCommands} from './TapeCommand';
 type RunParameter = { initialState: State, stepsLimit?: number };
 
 /**
- * Set only on iterations whose `MachineState` represents a pause point.
- * - Side flags: at least one of `before` / `after` is `true`.
- * - `cause` identifies the pause origin:
+ * Descriptor attached to a `DebugSession` `pause` event. Lives ONLY on the
+ * pause-event payload (`PausedMachineState`) — never on a raw `runStepByStep`
+ * yield, which is a minimal `MachineState` with no debug concern.
+ *
+ * - `side` — exactly one of `'before'` / `'after'`. DebugSession dispatches the
+ *   two timings as separate `pause` events, so a single descriptor is always
+ *   one-sided (the v6 "both timings on one yield" set no longer exists, because
+ *   detection moved out of the generator).
+ * - `cause` — pause origin:
  *   - `'breakpoint'` — a `state.debug[when]` filter or `haltState.debug === true` matched.
- *   - `'step'` — a DebugSession step-mode endpoint fired (stepIn / stepOver / stepOut).
+ *   - `'step'` — a step-mode endpoint fired (stepIn / stepOver / stepOut).
  *   - `'manual'` — a `DebugSession.pause()` call fired.
  *
- * On `runStepByStep` yields, `cause` is always `'breakpoint'` (the generator only
- * knows about engine-level breakpoint filters). DebugSession synthesizes `'step'`
- * and `'manual'` causes when dispatching its `pause` event.
+ * Precedence when an iter satisfies more than one trigger: `breakpoint > step >
+ * manual`. `'step'` / `'manual'` only ever fire on the `'before'` side.
  */
-export type DebugBreak = {
-  before?: true;
-  after?: true;
+export type PauseInfo = {
+  side: 'before' | 'after';
   cause: 'breakpoint' | 'step' | 'manual';
 };
 
@@ -46,6 +50,16 @@ export const MACHINE_STATE_INTERNAL = Symbol('MachineState.internal');
 export type MachineStateInternal = {
   /** Frozen pre-iter halt-stack snapshot. Consumers must not mutate. */
   stack: readonly State[];
+  /** The interned symbol the engine matched for this iter (the result of
+   *  `state.getSymbol(tapeBlock)`). DebugSession uses it to evaluate
+   *  `state.debug` filters without re-reading the tape. */
+  matchedSymbol: symbol;
+  /** Whether this iter's transition leads to halt — computed on the RAW
+   *  next-state (before any halt-pop redirect to a continuation). The yielded
+   *  `MachineState.nextState` shows the post-pop continuation, so consumers
+   *  can't recover halt-imminence from it; DebugSession reads this flag to
+   *  honor `haltState.debug` on subroutine-return (halt-pop) iters. */
+  haltImminent: boolean;
 };
 
 export type MachineState = {
@@ -55,12 +69,6 @@ export type MachineState = {
   nextSymbols: string[];
   movements: symbol[];
   nextState: State;
-  /**
-   * Set only when this iteration is a debug break point.
-   * Field is OMITTED entirely when no break fires (no `debugBreak: undefined`).
-   * See `DebugBreak` for the field's shape and `cause` semantics.
-   */
-  debugBreak?: DebugBreak;
   /**
    * The transition the engine picked for this iter (#205). Always present
    * — `runStepByStep` resolves it at the very start of every iter via
@@ -86,9 +94,20 @@ export type MachineState = {
   };
 };
 
-// True iff `filter` matches `symbol` per the DebugConfig semantics.
-// undefined / [] -> never; true -> always; symbol[] -> exact membership.
-function matchFilter(filter: DebugConfig['before'], symbol: symbol): boolean {
+/**
+ * The payload of a `DebugSession` `pause` event: a `MachineState` plus the
+ * one-sided `pause` descriptor. Raw `runStepByStep` yields are plain
+ * `MachineState` (no `pause` field) — only DebugSession produces this shape.
+ */
+export type PausedMachineState = MachineState & { pause: PauseInfo };
+
+/**
+ * @internal — true iff `filter` matches `symbol` per the DebugConfig semantics.
+ * undefined / [] -> never; true -> always; symbol[] -> exact membership.
+ * Exported for sibling-module use in `DebugSession` (which now owns breakpoint
+ * detection); NOT re-exported from the package's public `index.ts`.
+ */
+export function matchFilter(filter: DebugConfig['before'], symbol: symbol): boolean {
   if (filter === undefined) return false;
   if (filter === true) return true;
   return filter.includes(symbol);
@@ -183,22 +202,10 @@ export default class TuringMachine {
         };
 
         try {
-          // Both before and after refer to THIS iter (#119 / v6.0.0).
-          // The halting iter's after-fire just rides along on the iter's
-          // own yield — no post-loop drain needed.
-          //
-          // #207 spec: `haltState.debug` is a boolean; the pause anchors on
-          // the AFTER side of the halt-triggering iter so consumers see the
-          // just-fired transition with the diagram cursor still on the
-          // triggering state.
-          //
-          // `state` here is always non-halt (halt is terminal — the run loop
-          // never iterates with state === haltState), so `state.debug` is
-          // always `DebugConfig` at runtime.
-          const beforeMatch = matchFilter(state.debug?.before, symbol);
-          const afterMatch = matchFilter(state.debug?.after, symbol)
-            || (nextState === haltState && haltState.debug);
-
+          // `runStepByStep` is the minimal execution primitive: it advances the
+          // machine and reports state. It does NO breakpoint detection — that's
+          // a debug concern that lives entirely in `DebugSession`. The yielded
+          // `MachineState` has no `pause` / `debugBreak` field.
           const nextStateForYield = nextState.isHalt && stack.length
             ? stack.slice(-1)[0]
             : nextState;
@@ -226,20 +233,20 @@ export default class TuringMachine {
             matchedTransition,
           };
 
-          if (beforeMatch || afterMatch) {
-            const dbg: DebugBreak = {cause: 'breakpoint'};
-            if (beforeMatch) dbg.before = true;
-            if (afterMatch) dbg.after = true;
-            yielded.debugBreak = dbg;
-          }
-
-          // #102: expose the pre-iter halt-stack to DebugSession via a
-          // Symbol-keyed accessor (non-enumerable so it doesn't leak into
-          // serialization / spread / toEqual). The snapshot is frozen so a
-          // consumer holding a reference can't mutate the engine's stack.
+          // #102: expose the pre-iter halt-stack + the matched symbol to
+          // DebugSession via a Symbol-keyed accessor (non-enumerable, so it
+          // doesn't leak into serialization / spread / toEqual). The stack
+          // snapshot is frozen so a consumer holding a reference can't mutate
+          // the engine's stack. DebugSession reads `matchedSymbol` to evaluate
+          // `state.debug` filters — keeping breakpoint detection out of this
+          // primitive.
           const stackSnapshot: readonly State[] = Object.freeze(stack.slice());
+          // Snapshot halt-imminence on the RAW nextState NOW, before the
+          // post-yield pop reassigns `nextState` — so the closure can't capture
+          // the mutated value.
+          const haltImminent = nextState === haltState;
           Object.defineProperty(yielded, MACHINE_STATE_INTERNAL, {
-            value: (): MachineStateInternal => ({stack: stackSnapshot}),
+            value: (): MachineStateInternal => ({stack: stackSnapshot, matchedSymbol: symbol, haltImminent}),
             enumerable: false,
           });
 
diff --git a/packages/machine/src/index.ts b/packages/machine/src/index.ts
index 84a3ce6..77d14de 100644
--- a/packages/machine/src/index.ts
+++ b/packages/machine/src/index.ts
@@ -5,7 +5,7 @@ export { default as State, DebugConfig, haltState, ifOtherSymbol } from './class
 export { default as Tape } from './classes/Tape';
 export { default as TapeBlock } from './classes/TapeBlock';
 export { default as TapeCommand, movements, symbolCommands } from './classes/TapeCommand';
-export { default as TuringMachine, type MachineState, type DebugBreak } from './classes/TuringMachine';
+export { default as TuringMachine, type MachineState, type PauseInfo, type PausedMachineState } from './classes/TuringMachine';
 export {
   default as DebugSession,
   type DebugSessionParameter,
diff --git a/test/examples.spec.ts b/test/examples.spec.ts
index 7df4972..cc142fc 100644
--- a/test/examples.spec.ts
+++ b/test/examples.spec.ts
@@ -128,8 +128,8 @@ describe('README.md — Debugging breakpoints', () => {
 
     const session = new DebugSession(machine, {initialState: myState});
     session.on('pause', (m) => {
-      if (m.debugBreak?.before) order.push('before');
-      if (m.debugBreak?.after) order.push('after');
+      if (m.pause.side === 'before') order.push('before');
+      if (m.pause.side === 'after') order.push('after');
       session.continue();
     });
     await session.start();
@@ -148,7 +148,7 @@ describe('README.md — Debugging breakpoints', () => {
     const session = new DebugSession(machine, {initialState: myState});
     session.on('step', () => { visitIx += 1; });
     session.on('pause', (m) => {
-      if (m.nextState === haltState && m.debugBreak?.after) {
+      if (m.nextState === haltState && m.pause.side === 'after') {
         haltPauses.push({atVisit: visitIx});
       }
       session.continue();

From 1eeddeb6a07c3d2c5b2424fd3d4da8bac480b9c6 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 28 May 2026 22:56:39 +0300
Subject: [PATCH 071/118] docs(CLAUDE): debug section reflects v7 #102 split
 (runStepByStep pure, DebugSession, m.pause)

---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5dafc91..2289e75 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,7 +47,7 @@ Key shapes that take reading multiple files to grasp:
 
 - **`TapeBlock` has a `Lock`** that `TuringMachine.run` grabs for the duration of a run, asserting the block isn't being mutated by another machine. Calls to `applyCommand` from outside a run must pass the matching capture symbol.
 
-- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverriddenHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. Pauses dispatch via the optional `onPause` hook on `run()` (awaited; without the hook, breaks fire-and-resume invisibly). **As of v7 #207, `haltState.debug` is a `boolean`** (not `DebugConfig`) — halt is terminal with one meaningful pause moment (post-triggering-iter, before halt processing). `haltState.debug = true` pauses on every halt entry (program exit + subroutine pop); the pause fires on the AFTER side of the iter whose transition leads to halt (`m.state` is the triggering state, `m.debugBreak.after === true`). Any object-shaped write (`{ before: true }`, `{ after: true }`, etc.) throws at write time. The `HaltState` typed alias on the singleton export narrows `debug` to `boolean` for compile-time safety at the canonical access path. **Chained-form `haltState.debug.before = true` does NOT throw in non-strict mode** — it's a primitive-boolean property assignment, silent in non-strict, `TypeError` in strict; the engine never sees the write so can't intercept. Always use whole-object form. See `packages/machine/README.md` "Debugging breakpoints (v4+)" for the full API.
+- **`state.debug` (v4+)** — runtime-mutable breakpoint cell with `{ before, after }` symbol filtering. Shared across `withOverriddenHaltState` wrappers via a private `Ref` so an assignment on the original is visible from every wrapper instance — useful when the same primitive is reused in composition chains. **As of v7 #102, breakpoint *detection* and *reaction* are split**: `runStepByStep` is the pure-iteration primitive (evaluates no filters, stamps no pause field); `run()` is sync + callback-free; an opt-in **`DebugSession`** (`new DebugSession(machine, {initialState})`) is the only thing that evaluates `state.debug` and turns a match into an awaited `pause` event. The pause descriptor is `m.pause: { side: 'before' | 'after', cause: 'breakpoint' | 'step' | 'manual' }` (replaced the per-yield `m.debugBreak: { before?, after? }`). **As of v7 #207, `haltState.debug` is a `boolean`** (not `DebugConfig`) — halt is terminal with one meaningful pause moment (post-triggering-iter, before halt processing). `haltState.debug = true` pauses on every halt entry (program exit + subroutine pop); the pause fires on the AFTER side of the iter whose transition leads to halt (`m.state` is the triggering state, `m.pause.side === 'after'`). Any object-shaped write (`{ before: true }`, `{ after: true }`, etc.) throws at write time. The `HaltState` typed alias on the singleton export narrows `debug` to `boolean` for compile-time safety at the canonical access path. **Chained-form `haltState.debug.before = true` does NOT throw in non-strict mode** — it's a primitive-boolean property assignment, silent in non-strict, `TypeError` in strict; the engine never sees the write so can't intercept. Always use whole-object form. See `packages/machine/README.md` "Debugging" for the full API.
 
   Cross-version notes:
   - **v5**: hook renamed `onDebugBreak` → `onPause` (#110). `haltState.debug.after = true` (or `{ before, after }` together) now throws at write-time — halt is terminal, no iteration-after-halt to anchor on (#108 part 2). *Superseded in v7 by [#207](https://github.com/mellonis/turing-machine-js/issues/207): `haltState.debug` is now a boolean and ALL object writes throw — the per-side shape never modeled anything for halt.* Halting iter's after-fire stopped being silently lost (#108 part 1). New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without editing `state.debug` assignments (#106).

From e6f022727b6876f281067406d52004555d475077 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 28 May 2026 23:20:34 +0300
Subject: [PATCH 072/118] fix(DebugSession): depth-based stepOver/stepOut to
 mirror DevTools (#102)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous stepOver used frame-identity ("click-time top frame no
longer on the stack") = depth < clickTimeDepth — which is Step OUT
behavior, making stepOver and stepOut near-duplicates. DevTools Step Over
stays at the current depth: run subroutines the stepped-over iter enters
to completion, pause back at the start level.

Reformulated all three in terms of halt-stack DEPTH (= stack.length),
matching DevTools:
- stepIn  → next iter, any depth (descends).
- stepOver → next iter with depth ≤ clickTimeDepth (skip pushed frames).
- stepOut → next iter with depth < clickTimeDepth (current frame exited).

`#capturedTopFrame` / `#clickTimeTopFrame` (State identity) replaced by
`#capturedDepth` / `#clickTimeDepth` (numbers). stepOut still throws when
clickTimeDepth is 0 (no enclosing frame). Empty-stack stepOver no longer
"collapses to stepIn" specially — depth ≤ 0 naturally pauses at the next
depth-0 iter, skipping any pushed frame (correct Step Over at top level).

New test: a genuinely nested machine (a bare that itself enters a
wrapper) where Into/Over/Out land at three DISTINCT iters (2 / 3 / 4),
pinning the DevTools parity. README step-control table + a depth-semantics
note updated; the continuation-passing caveat (flat .with() chains have no
nesting, so Over==Out there) is documented.

539 tests pass; coverage above floors.
---
 packages/machine/README.md                    |  8 +-
 .../machine/src/classes/DebugSession.spec.ts  | 72 +++++++++++++++++-
 packages/machine/src/classes/DebugSession.ts  | 73 +++++++++----------
 3 files changed, 111 insertions(+), 42 deletions(-)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index 8aa715e..a4f4531 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -544,14 +544,16 @@ The `debug` field is mutable — toggle breakpoints at runtime without rebuildin
 |---|---|
 | `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 force a `pause` event on the very next iter, regardless of breakpoint filters. |
-| `stepOver()` | Resume and pause at the first iter after the click-time top halt-frame is no longer on the stack. Collapses to `stepIn` if the click-time stack was empty. |
-| `stepOut()` | Same endpoint as `stepOver`, but throws if the click-time stack is empty (no enclosing frame to exit — IDE convention). |
+| `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. |
 
+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.with(B)` = "run A, then B" — sequential), so a flat `.with()` 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 |
diff --git a/packages/machine/src/classes/DebugSession.spec.ts b/packages/machine/src/classes/DebugSession.spec.ts
index ca2acda..9b7db1d 100644
--- a/packages/machine/src/classes/DebugSession.spec.ts
+++ b/packages/machine/src/classes/DebugSession.spec.ts
@@ -1,6 +1,6 @@
 import {describe, it, expect} from 'vitest';
 import Alphabet from './Alphabet';
-import State, {haltState} from './State';
+import State, {haltState, ifOtherSymbol} from './State';
 import Tape from './Tape';
 import TapeBlock from './TapeBlock';
 import TuringMachine, {MACHINE_STATE_INTERNAL, type MachineStateInternal} from './TuringMachine';
@@ -615,3 +615,73 @@ describe('DebugSession: pause event + continue()', () => {
     }
   });
 });
+
+describe('DebugSession: step granularity under genuine nesting (DevTools parity)', () => {
+  // Build a machine with REAL depth-2 nesting (a bare that itself enters a
+  // wrapper), so stepIn / stepOver / stepOut land at three DISTINCT iters.
+  //
+  // Trajectory (pre-iter halt-stack depth in parens):
+  //   run start: enter `outer` → push outerCont           → depth 1
+  //   iter 1 (d1): outerBare → nestedSub; end-of-iter pushes innerCont → depth 2
+  //   iter 2 (d2): inner (via nestedSub) → halt; pop innerCont          → depth 1
+  //   iter 3 (d1): innerCont → halt; pop outerCont                      → depth 0
+  //   iter 4 (d0): outerCont → halt
+  //
+  // Paused at iter 1 (depth 1), the three step modes pause at:
+  //   stepIn   → iter 2 (next iter, descends into the nested call, depth 2)
+  //   stepOver → iter 3 (skip the nested call, back at click-time depth 1)
+  //   stepOut  → iter 4 (current frame exited, depth 0)
+  const build = () => {
+    const alphabet = new Alphabet(' A'.split(''));
+    const tape = new Tape({alphabet, symbols: ['A', 'A', 'A']});
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({tapeBlock});
+
+    const outerCont = new State({[ifOtherSymbol]: {command: [{movement: movements.stay}], nextState: haltState}});
+    const innerCont = new State({[ifOtherSymbol]: {command: [{movement: movements.right}], nextState: haltState}});
+    const inner = new State({[ifOtherSymbol]: {command: [{movement: movements.right}], nextState: haltState}});
+    const nestedSub = inner.withOverriddenHaltState(innerCont);
+    const outerBare = new State({[ifOtherSymbol]: {command: [{movement: movements.right}], nextState: nestedSub}});
+    const outer = outerBare.withOverriddenHaltState(outerCont);
+
+    // Breakpoint on iter 1: outerBare's #debugRef is shared with the `outer`
+    // wrapper, so this fires on the first iter.
+    outerBare.debug = {before: true};
+    return {machine, outer};
+  };
+
+  // Pause at iter 1, issue the given step mode, return the step number of the
+  // resulting (cause: 'step') endpoint pause.
+  async function endpointOf(mode: 'stepIn' | 'stepOver' | 'stepOut'): Promise<number> {
+    const {machine, outer} = build();
+    const session = new DebugSession(machine, {initialState: outer});
+    const pauses: Array<{step: number; cause: string}> = [];
+    let first = true;
+    session.on('pause', (m) => {
+      pauses.push({step: m.step, cause: m.pause.cause});
+      if (first) {
+        first = false;
+        session[mode]();
+      } else {
+        session.continue();
+      }
+    });
+    await session.start();
+    // pauses[0] = iter-1 breakpoint; pauses[1] = the step endpoint.
+    expect(pauses[0]).toEqual({step: 1, cause: 'breakpoint'});
+    expect(pauses[1].cause).toBe('step');
+    return pauses[1].step;
+  }
+
+  it('stepIn descends into the nested call (depth 2) — pauses at iter 2', async () => {
+    expect(await endpointOf('stepIn')).toBe(2);
+  });
+
+  it('stepOver skips the nested call, returns to click-time depth — pauses at iter 3', async () => {
+    expect(await endpointOf('stepOver')).toBe(3);
+  });
+
+  it('stepOut exits the current frame — pauses at iter 4', async () => {
+    expect(await endpointOf('stepOut')).toBe(4);
+  });
+});
diff --git a/packages/machine/src/classes/DebugSession.ts b/packages/machine/src/classes/DebugSession.ts
index 6c61b6f..0087a4a 100644
--- a/packages/machine/src/classes/DebugSession.ts
+++ b/packages/machine/src/classes/DebugSession.ts
@@ -89,18 +89,16 @@ export default class DebugSession {
   #pauseResolver: (() => void) | null = null;
   #activeStepMode: ResumeDirective | null = null;
   /**
-   * Top of the halt-stack snapshotted at the most recent pause dispatch. Used by
-   * stepOver / stepOut to recognize their natural endpoint (the click-time
-   * frame is no longer on the stack). `null` when the click-time stack was
-   * empty.
+   * Halt-stack DEPTH snapshotted at the most recent pause dispatch (= number
+   * of frames on the stack). DevTools-style step granularity is depth-based:
+   * stepOver pauses at the next iter with `depth <= clickTimeDepth` (skip
+   * frames the stepped-over iter pushes, pause back at the start level);
+   * stepOut at `depth < clickTimeDepth` (the current frame itself exited).
+   * Captured on EVERY pause so a step* call from the listener can freeze it.
    */
-  #capturedTopFrame: State | null = null;
-  /**
-   * The click-time top-frame frozen at the moment a step-over / step-out
-   * directive was issued. Distinct from `#capturedTopFrame` (which tracks
-   * EVERY pause); this one only updates when stepOver / stepOut accepts.
-   */
-  #clickTimeTopFrame: State | null = null;
+  #capturedDepth = 0;
+  /** The click-time depth frozen when a stepOver / stepOut directive is issued. */
+  #clickTimeDepth = 0;
   #runIntervalMs = 0;
   #pauseRequested = false;
 
@@ -175,42 +173,45 @@ export default class DebugSession {
    */
   stepIn(): void {
     this.#activeStepMode = 'step-in';
-    this.#clickTimeTopFrame = null;
     this.#releasePause();
   }
 
   /**
-   * Resume and run until the click-time top halt-frame is no longer on the
-   * stack, then pause at the first iter past that point. With an empty
-   * click-time stack, collapses to `stepIn` (pause at next iter).
+   * 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 {
     this.#activeStepMode = 'step-over';
-    this.#clickTimeTopFrame = this.#capturedTopFrame;
+    this.#clickTimeDepth = this.#capturedDepth;
     this.#releasePause();
   }
 
   /**
-   * Resume and run until the click-time top halt-frame is popped, then pause
-   * at the next iter. Endpoint predicate is the same as stepOver; the
-   * difference is the empty-stack contract:
-   *   - stepOver: empty click-time stack → collapse to stepIn.
-   *   - stepOut: empty click-time stack → throw (no enclosing frame to exit).
+   * 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.
    *
-   * Matches IDE convention: "step out of nothing" is a programming error,
-   * not a silent no-op.
+   * 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 {
-    if (this.#capturedTopFrame === null) {
+    if (this.#capturedDepth === 0) {
       throw new Error(
         'DebugSession.stepOut() called with an empty click-time halt-stack — there is no enclosing frame to exit.',
       );
     }
     this.#activeStepMode = 'step-out';
-    this.#clickTimeTopFrame = this.#capturedTopFrame;
+    this.#clickTimeDepth = this.#capturedDepth;
     this.#releasePause();
   }
 
@@ -235,15 +236,13 @@ export default class DebugSession {
    * manual pause) drops the active step-mode BEFORE listeners fire. Listeners
    * that want to keep stepping must call stepIn/Over/Out from the new pause.
    *
-   * The pre-iter halt-stack top is snapshotted into `#capturedTopFrame` so a
+   * The pre-iter halt-stack DEPTH is snapshotted into `#capturedDepth` so a
    * `stepOver` / `stepOut` issued from inside the listener can freeze it as
-   * the click-time frame.
+   * the click-time depth.
    */
   async #dispatchPause(machineState: MachineState, pause: PauseInfo): Promise<void> {
     this.#activeStepMode = null;
-    this.#clickTimeTopFrame = null;
-    const stack = this.#readStack(machineState);
-    this.#capturedTopFrame = stack.length > 0 ? stack[stack.length - 1] : null;
+    this.#capturedDepth = this.#readStack(machineState).length;
 
     // Note: the spread drops the non-enumerable MACHINE_STATE_INTERNAL Symbol
     // accessor — that's intentional. Pause listeners are public API; the
@@ -317,16 +316,14 @@ export default class DebugSession {
         && matchFilter(machineState.state.debug?.after, matchedSymbol))
         || (internal?.haltImminent === true && haltState.debug === true);
       const stepInForcesPause = this.#activeStepMode === 'step-in';
+      // Depth-based endpoints (DevTools semantics). currentDepth = pre-iter
+      // halt-stack length. stepOver: back at/above click-time depth (skip
+      // pushed frames). stepOut: strictly shallower (current frame exited).
+      const currentDepth = this.#readStack(machineState).length;
       const stepOverEndpointReached =
-        this.#activeStepMode === 'step-over'
-        && (
-          this.#clickTimeTopFrame === null  // empty click-time stack — collapse to stepIn
-          || !this.#readStack(machineState).includes(this.#clickTimeTopFrame)
-        );
+        this.#activeStepMode === 'step-over' && currentDepth <= this.#clickTimeDepth;
       const stepOutEndpointReached =
-        this.#activeStepMode === 'step-out'
-        && this.#clickTimeTopFrame !== null
-        && !this.#readStack(machineState).includes(this.#clickTimeTopFrame);
+        this.#activeStepMode === 'step-out' && currentDepth < this.#clickTimeDepth;
       // Consume the manual-pause flag at iter start. If a breakpoint also
       // matches this iter, the request is silently consumed by the
       // breakpoint dispatch (one pause, cause: 'breakpoint').

From fc120dac023737da66be018a8bbf1c1df4ef6eed Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 28 May 2026 23:22:26 +0300
Subject: [PATCH 073/118] =?UTF-8?q?docs:=20fix=20bogus=20A.with(B)=20?=
 =?UTF-8?q?=E2=86=92=20A.wohs(B)=20in=20step-controls=20note=20(no=20.with?=
 =?UTF-8?q?()=20method=20exists)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/machine/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index a4f4531..4ffd1c3 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -552,7 +552,7 @@ The `debug` field is mutable — toggle breakpoints at runtime without rebuildin
 | `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. |
 
-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.with(B)` = "run A, then B" — sequential), so a flat `.with()` chain has no real nesting and Over/Out behave the same there; the distinction appears only when a subroutine's body enters another wrapper.
+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
 

From 878030394fbdbf6b72dc897524c838f60e2b5d92 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Thu, 28 May 2026 23:42:38 +0300
Subject: [PATCH 074/118] chore(release): 7.0.0-alpha.6

---
 lerna.json                                    |  2 +-
 package-lock.json                             | 14 +++++-----
 packages/builder/CHANGELOG.md                 |  4 +++
 packages/builder/package.json                 |  4 +--
 .../library-binary-numbers-bare/CHANGELOG.md  |  4 +++
 .../library-binary-numbers-bare/package.json  |  4 +--
 packages/library-binary-numbers/CHANGELOG.md  |  4 +++
 packages/library-binary-numbers/package.json  |  4 +--
 packages/machine/CHANGELOG.md                 | 28 +++++++++++++++++++
 packages/machine/package.json                 |  2 +-
 10 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/lerna.json b/lerna.json
index 6b9d6ee..33d3137 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.5",
+  "version": "7.0.0-alpha.6",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index 3056473..a03f9f1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10656,40 +10656,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.5",
+      "version": "7.0.0-alpha.6",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.4"
+        "@turing-machine-js/machine": "^7.0.0-alpha.6"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.5",
+      "version": "7.0.0-alpha.6",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.4"
+        "@turing-machine-js/machine": "^7.0.0-alpha.6"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.5",
+      "version": "7.0.0-alpha.6",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.4"
+        "@turing-machine-js/machine": "^7.0.0-alpha.6"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.5",
+      "version": "7.0.0-alpha.6",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/builder/CHANGELOG.md b/packages/builder/CHANGELOG.md
index 5a486b3..ec431c7 100644
--- a/packages/builder/CHANGELOG.md
+++ b/packages/builder/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.6 — adds the `DebugSession` interactive-debugging class and reshapes the engine debug surface: `run()` becomes synchronous + callback-free, `runStepByStep` becomes the pure-iteration primitive (no breakpoint detection), and the per-yield `m.debugBreak` is replaced by a one-sided `m.pause: { side, cause }` carried on `DebugSession` `pause` events ([#102](https://github.com/mellonis/turing-machine-js/issues/102)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.5` → `^7.0.0-alpha.6`.
+
 ## [7.0.0-alpha.5] - 2026-05-25
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.5 — adds per-iter `MachineState.matchedTransition` + renames `GraphTransition.id` separator `-` → `.` ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` with halt-imminent pause on the AFTER side of the halt-triggering iter ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.4` → `^7.0.0-alpha.5`.
diff --git a/packages/builder/package.json b/packages/builder/package.json
index 201b681..5799900 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.5",
+  "version": "7.0.0-alpha.6",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.5"
+    "@turing-machine-js/machine": "^7.0.0-alpha.6"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/CHANGELOG.md b/packages/library-binary-numbers-bare/CHANGELOG.md
index 8200141..8e54e6e 100644
--- a/packages/library-binary-numbers-bare/CHANGELOG.md
+++ b/packages/library-binary-numbers-bare/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.6 — adds the `DebugSession` interactive-debugging class and reshapes the engine debug surface: `run()` becomes synchronous + callback-free, `runStepByStep` becomes the pure-iteration primitive (no breakpoint detection), and the per-yield `m.debugBreak` is replaced by a one-sided `m.pause: { side, cause }` carried on `DebugSession` `pause` events ([#102](https://github.com/mellonis/turing-machine-js/issues/102)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.5` → `^7.0.0-alpha.6`.
+
 ## [7.0.0-alpha.5] - 2026-05-25
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.5 — adds per-iter `MachineState.matchedTransition` + renames `GraphTransition.id` separator `-` → `.` ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` with halt-imminent pause on the AFTER side of the halt-triggering iter ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.4` → `^7.0.0-alpha.5`.
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index 378e8cb..6853044 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.5",
+  "version": "7.0.0-alpha.6",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.5"
+    "@turing-machine-js/machine": "^7.0.0-alpha.6"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/CHANGELOG.md b/packages/library-binary-numbers/CHANGELOG.md
index 5ce160e..d8fc7d8 100644
--- a/packages/library-binary-numbers/CHANGELOG.md
+++ b/packages/library-binary-numbers/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.6 — adds the `DebugSession` interactive-debugging class and reshapes the engine debug surface: `run()` becomes synchronous + callback-free, `runStepByStep` becomes the pure-iteration primitive (no breakpoint detection), and the per-yield `m.debugBreak` is replaced by a one-sided `m.pause: { side, cause }` carried on `DebugSession` `pause` events ([#102](https://github.com/mellonis/turing-machine-js/issues/102)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.5` → `^7.0.0-alpha.6`.
+
 ## [7.0.0-alpha.5] - 2026-05-25
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.5 — adds per-iter `MachineState.matchedTransition` + renames `GraphTransition.id` separator `-` → `.` ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` with halt-imminent pause on the AFTER side of the halt-triggering iter ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.4` → `^7.0.0-alpha.5`.
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index 54c0af6..4c4bcdb 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.5",
+  "version": "7.0.0-alpha.6",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.5"
+    "@turing-machine-js/machine": "^7.0.0-alpha.6"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index c403e8c..cd86cbc 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,34 @@ 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`.
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 02619f7..445e7f1 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.5",
+  "version": "7.0.0-alpha.6",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"

From 26181cc26c19ace9b7c5e8b1b52501f2cc6ebbcc Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Fri, 29 May 2026 02:58:49 +0300
Subject: [PATCH 075/118] docs(machine): note the after-on-halt-state +
 haltState.debug pause collapse
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An `after`-side breakpoint on the halt-triggering state and `haltState.debug`
both land on the AFTER side of the same iter, so the engine (one pause per
iter-side) fires a single `pause` event, not two. Document it as intentional —
halt has no iter of its own, so "after the triggering state" and "before halt"
are the same moment; no flag to synthesize a second ephemeral pause.
---
 packages/machine/README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index 4ffd1c3..4adf48e 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -530,6 +530,8 @@ 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.pause.side === 'after'`.
 
+> ⚠️ **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.
+
 > ⚠️ **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`.**
 
 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.

From 2d6cd04d7c2b12274e9a1d74e594ddd601f7b502 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Fri, 29 May 2026 12:08:37 +0300
Subject: [PATCH 076/118] feat(machine): extract CallFrame as a first-class
 State subclass (#213)

withOverriddenHaltState previously returned a plain State whose private
#symbolToDataMap/#debugRef were aliased to the bare's. Replace that with a
CallFrame extends State that delegates transition lookups and debug to its
bare and carries its own bare/override. instanceof State is preserved (so it
still flows as a nextState and through toGraph/fromGraph); instanceof
CallFrame becomes the wrapper discriminator.

Also drops the now-dead #bareState/#overriddenHaltState fields and simplifies
the run-loop stateId resolution to a CallFrame check. The only public-surface
change is the additive CallFrame export.
---
 packages/machine/src/classes/State.spec.ts    |  62 +++++++-
 packages/machine/src/classes/State.ts         | 148 ++++++++++++++----
 packages/machine/src/classes/TuringMachine.ts |  16 +-
 packages/machine/src/index.ts                 |   2 +-
 4 files changed, 179 insertions(+), 49 deletions(-)

diff --git a/packages/machine/src/classes/State.spec.ts b/packages/machine/src/classes/State.spec.ts
index 5451179..bd6ff44 100644
--- a/packages/machine/src/classes/State.spec.ts
+++ b/packages/machine/src/classes/State.spec.ts
@@ -1,6 +1,6 @@
 import Alphabet from './Alphabet';
 import Reference from './Reference';
-import State, {STATE_INTERNAL, haltState, ifOtherSymbol} from './State';
+import State, {CallFrame, STATE_INTERNAL, haltState, ifOtherSymbol} from './State';
 import TapeBlock from './TapeBlock';
 import {movements, symbolCommands} from './TapeCommand';
 
@@ -136,8 +136,9 @@ describe('State.getSymbol — head resolution', () => {
 });
 
 describe('State.withOverriddenHaltState', () => {
-  // The wrapper shares the original's symbolToDataMap and debugRef but adds
-  // an overriddenHaltState. These tests pin the wrapping contract.
+  // The wrapper (a CallFrame) delegates transition lookups and debug to the
+  // original and adds an override. These tests pin the wrapping contract;
+  // CallFrame-identity is covered in the 'CallFrame' describe below.
 
   test('wrapper exposes the override target', () => {
     const original = new State({[ifOtherSymbol]: {nextState: haltState}});
@@ -296,6 +297,61 @@ describe('State.withOverriddenHaltState', () => {
   });
 });
 
+describe('CallFrame', () => {
+  // withOverriddenHaltState returns a first-class CallFrame (a State subclass)
+  // rather than a mutated plain State. instanceof State stays true (consumers
+  // pass wrappers as nextState); instanceof CallFrame is the wrapper discriminator.
+
+  test('withOverriddenHaltState returns a CallFrame that is also a State', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const w = A.withOverriddenHaltState(haltState);
+
+    expect(w).toBeInstanceOf(State);
+    expect(w).toBeInstanceOf(CallFrame);
+  });
+
+  test('exposes its bare via the .bare accessor', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const w = A.withOverriddenHaltState(haltState);
+
+    expect(w.bare).toBe(A);
+  });
+
+  test('a wrapped wohs unwraps to the original bare (#176)', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const t1 = new State({[ifOtherSymbol]: {}}, 't1');
+    const t2 = new State({[ifOtherSymbol]: {}}, 't2');
+
+    const chained = A.withOverriddenHaltState(t1).withOverriddenHaltState(t2);
+
+    expect(chained.bare).toBe(A);
+  });
+
+  test('a plain State is not a CallFrame', () => {
+    expect(new State({[ifOtherSymbol]: {}})).not.toBeInstanceOf(CallFrame);
+    expect(haltState).not.toBeInstanceOf(CallFrame);
+  });
+
+  test('STATE_INTERNAL view exposes own id/name/tags and delegates bare/override/map', () => {
+    const A = new State({[ifOtherSymbol]: {}}, 'A');
+    const t = new State({[ifOtherSymbol]: {}}, 't');
+    const w = A.withOverriddenHaltState(t);
+
+    const view = w[STATE_INTERNAL]();
+
+    expect(view.id).toBe(w.id);
+    expect(view.name).toBe('A(t)');
+    expect(view.bareState).toBe(A);
+    expect(view.overriddenHaltState).toBe(t);
+    expect(view.symbolToDataMap).toBe(A[STATE_INTERNAL]().symbolToDataMap);
+    expect([...view.tags]).toEqual([]);
+
+    // The name setter writes the frame's own (inherited) #name.
+    view.name = 'renamed';
+    expect(w.name).toBe('renamed');
+  });
+});
+
 describe('State.toGraph — unbound Reference', () => {
   test('skips a transition whose nextState is an unbound Reference (non-wrapper context)', () => {
     // An unbound Reference throws when its `.ref` getter is read. State.toGraph
diff --git a/packages/machine/src/classes/State.ts b/packages/machine/src/classes/State.ts
index c42508f..2b7ced2 100644
--- a/packages/machine/src/classes/State.ts
+++ b/packages/machine/src/classes/State.ts
@@ -103,7 +103,7 @@ export default class State {
   // Two-level WeakMap so the outer entry is GC'd when the bare is collected;
   // WeakRef values let wrappers themselves be GC'd when nothing else holds
   // them, with cache misses simply reconstructing fresh wrappers.
-  static #wrapperCache = new WeakMap<State, WeakMap<State, WeakRef<State>>>();
+  static #wrapperCache = new WeakMap<State, WeakMap<State, WeakRef<CallFrame>>>();
 
   readonly #id: number = id(this);
 
@@ -112,14 +112,6 @@ export default class State {
   // user-facing name validation (composite names contain `(` and `)`).
   #name: string;
 
-  #overriddenHaltState: State | null = null;
-
-  // For wrapper states (produced by `withOverriddenHaltState`), points at the
-  // State whose transition map was wrapped. `null` on bare/atomic states.
-  // `toGraph` reads this to render wrapper and bare as separate nodes linked
-  // by a `==> call` arrow.
-  #bareState: State | null = null;
-
   #symbolToDataMap = new Map<symbol, { command: Command, nextState: State | Reference }>();
 
   // Shared mutable cell — withOverriddenHaltState wrappers reference the same
@@ -223,8 +215,10 @@ export default class State {
     return this.#id === 0;
   }
 
-  get overriddenHaltState() {
-    return this.#overriddenHaltState;
+  // Plain States never override the halt state — only a `CallFrame` (produced
+  // by `withOverriddenHaltState`) carries an override, via its own getter.
+  get overriddenHaltState(): State | null {
+    return null;
   }
 
   get ref() {
@@ -438,15 +432,15 @@ export default class State {
     return {nextState: entry.nextState, matchedSymbol: symbol, ix};
   }
 
-  withOverriddenHaltState(overriddenHaltState: State) {
-    // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
+  withOverriddenHaltState(overriddenHaltState: State): CallFrame {
+    // Unwrap `this` if it's itself a CallFrame — the chain's inner overrides
     // are dead at runtime anyway (only the outermost `.wohs()`'s override is
     // pushed onto the halt-stack on entry; verified empirically). Composite
     // name reflects runtime behavior, not construction history. See #176.
-    const bare = this.#bareState ?? this;
+    const bare = this instanceof CallFrame ? this.bare : this;
 
     // Memoize by (bare, override) so identical args return the same instance
-    // (#175). The cache uses WeakMaps + WeakRefs so cached wrappers can be
+    // (#175). The cache uses WeakMaps + WeakRefs so cached frames can be
     // GC'd when nothing else holds them. Compounds with the chain-collapse
     // above: `A.wohs(t1).wohs(t2)` keys as (A, t2) after the unwrap, hitting
     // the same cache slot as a direct `A.wohs(t2)`.
@@ -467,20 +461,11 @@ export default class State {
       State.#wrapperCache.set(bare, innerCache);
     }
 
-    // Cache miss — construct with no name, then overwrite #name directly
-    // (composed names contain `(` and `)` which the constructor's user-facing
-    // validation would reject; private-field access bypasses that).
-    const state = new State();
-
-    state.#name = `${bare.name}(${overriddenHaltState.name})`;
-    state.#symbolToDataMap = bare.#symbolToDataMap;
-    state.#overriddenHaltState = overriddenHaltState;
-    state.#debugRef = bare.#debugRef;
-    state.#bareState = bare;
+    const frame = new CallFrame(bare, overriddenHaltState);
 
-    innerCache.set(overriddenHaltState, new WeakRef(state));
+    innerCache.set(overriddenHaltState, new WeakRef(frame));
 
-    return state;
+    return frame;
   }
 
   /**
@@ -519,8 +504,8 @@ export default class State {
       get id(): number { return self.#id; },
       get name(): string { return self.#name; },
       set name(v: string) { self.#name = v; },
-      get bareState(): State | null { return self.#bareState; },
-      get overriddenHaltState(): State | null { return self.#overriddenHaltState; },
+      get bareState(): State | null { return null; },
+      get overriddenHaltState(): State | null { return null; },
       get symbolToDataMap() { return self.#symbolToDataMap; },
       get tags(): ReadonlySet<string> { return self.#tags; },
     };
@@ -542,13 +527,18 @@ export default class State {
       nextState: { id: number; name: string } | null;
     }>;
   } {
+    // Route through the STATE_INTERNAL view so a CallFrame reports its bare's
+    // transitions and its own override — the view delegates those to the bare
+    // / the frame's #override, whereas the raw private fields on a CallFrame
+    // are empty/null.
+    const internal = state[STATE_INTERNAL]();
     const transitions: Array<{
       rawPatternDescription: string | undefined;
       command: Array<{ symbol: string; movement: string }>;
       nextState: { id: number; name: string } | null;
     }> = [];
 
-    for (const [sym, {command, nextState}] of state.#symbolToDataMap) {
+    for (const [sym, {command, nextState}] of internal.symbolToDataMap) {
       let target: State | null = null;
 
       try {
@@ -567,12 +557,14 @@ export default class State {
       });
     }
 
+    const override = internal.overriddenHaltState;
+
     return {
-      id: state.#id,
-      name: state.#name,
+      id: internal.id,
+      name: internal.name,
       isHalt: state.isHalt,
-      overriddenHaltState: state.#overriddenHaltState
-        ? {id: state.#overriddenHaltState.id, name: state.#overriddenHaltState.name}
+      overriddenHaltState: override
+        ? {id: override.id, name: override.name}
         : null,
       transitions,
     };
@@ -641,3 +633,91 @@ export type HaltState = State & {
 };
 
 export const haltState: HaltState = new State(null) as 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 class CallFrame extends State {
+  readonly #bare: State;
+
+  readonly #override: State;
+
+  constructor(bare: State, override: State) {
+    super(null);
+    this.#bare = bare;
+    this.#override = override;
+    // Composite name contains `(` / `)`, which the constructor's user-facing
+    // name validator rejects; the STATE_INTERNAL name setter bypasses it
+    // (writes the inherited #name). `super[...]` reaches State's own view so
+    // we don't recurse through this subclass's override below.
+    super[STATE_INTERNAL]().name = `${bare.name}(${override.name})`;
+  }
+
+  get bare(): State {
+    return this.#bare;
+  }
+
+  get overriddenHaltState(): State {
+    return this.#override;
+  }
+
+  getSymbol(tapeBlock: TapeBlock) {
+    return this.#bare.getSymbol(tapeBlock);
+  }
+
+  getCommand(symbol: symbol) {
+    return this.#bare.getCommand(symbol);
+  }
+
+  getNextState(symbol: symbol) {
+    return this.#bare.getNextState(symbol);
+  }
+
+  getMatchedTransition(symbol: symbol) {
+    return this.#bare.getMatchedTransition(symbol);
+  }
+
+  get debug(): DebugConfig {
+    return this.#bare.debug;
+  }
+
+  set debug(
+    value: DebugConfig | { before?: symbol[] | readonly symbol[] | true; after?: symbol[] | readonly symbol[] | true } | null,
+  ) {
+    this.#bare.debug = value;
+  }
+
+  [STATE_INTERNAL]() {
+    // Own id / name / tags come from the inherited State fields (via super's
+    // view); bareState / overriddenHaltState / the transition map delegate to
+    // #bare / #override so sibling modules (stateGraph, inspect) see the
+    // frame's true shape.
+    const own = super[STATE_INTERNAL]();
+    const bare = this.#bare;
+    const override = this.#override;
+
+    return {
+      get id(): number { return own.id; },
+      get name(): string { return own.name; },
+      set name(v: string) { own.name = v; },
+      get bareState(): State | null { return bare; },
+      get overriddenHaltState(): State | null { return override; },
+      get symbolToDataMap() { return bare[STATE_INTERNAL]().symbolToDataMap; },
+      get tags(): ReadonlySet<string> { return own.tags; },
+    };
+  }
+}
diff --git a/packages/machine/src/classes/TuringMachine.ts b/packages/machine/src/classes/TuringMachine.ts
index 1195ccb..a48fdb1 100644
--- a/packages/machine/src/classes/TuringMachine.ts
+++ b/packages/machine/src/classes/TuringMachine.ts
@@ -1,4 +1,4 @@
-import State, {haltState, STATE_INTERNAL, type DebugConfig} from './State';
+import State, {CallFrame, haltState, type DebugConfig} from './State';
 import TapeBlock, {lockSymbol} from './TapeBlock';
 import {symbolCommands} from './TapeCommand';
 
@@ -186,16 +186,10 @@ export default class TuringMachine {
         const command = state.getCommand(symbol);
         const matched = state.getMatchedTransition(symbol);
         let nextState = matched.nextState.ref;
-        // For wrapper-entry iters, the wrapper's transitions in `toGraph`
-        // are empty (wrappers delegate to the bare via shared
-        // `#symbolToDataMap`); the resolvable transition id lives under
-        // the bare's stateId. `bareState` is non-null only when `state`
-        // is a wrapper produced by `withOverriddenHaltState`. Accessed
-        // via the STATE_INTERNAL package-private view (same pattern
-        // `utilities/stateGraph.ts` uses) to avoid widening the public
-        // State API for this internal need.
-        const stateInternal = state[STATE_INTERNAL]();
-        const resolvableStateId = stateInternal.bareState?.id ?? state.id;
+        // For wrapper-entry iters, a CallFrame's own transitions in `toGraph`
+        // are empty (it delegates lookups to its bare); the resolvable
+        // transition id lives under the bare's stateId.
+        const resolvableStateId = state instanceof CallFrame ? state.bare.id : state.id;
         const matchedTransition: MachineState['matchedTransition'] = {
           id: `${resolvableStateId}.${matched.ix}`,
           matchKinds: this.#tapeBlock.patternKinds(matched.matchedSymbol),
diff --git a/packages/machine/src/index.ts b/packages/machine/src/index.ts
index 77d14de..5a53283 100644
--- a/packages/machine/src/index.ts
+++ b/packages/machine/src/index.ts
@@ -1,7 +1,7 @@
 export { default as Alphabet } from './classes/Alphabet';
 export { default as Command } from './classes/Command';
 export { default as Reference } from './classes/Reference';
-export { default as State, DebugConfig, haltState, ifOtherSymbol } from './classes/State';
+export { default as State, CallFrame, DebugConfig, haltState, ifOtherSymbol } from './classes/State';
 export { default as Tape } from './classes/Tape';
 export { default as TapeBlock } from './classes/TapeBlock';
 export { default as TapeCommand, movements, symbolCommands } from './classes/TapeCommand';

From 2ea70582253b85e79952e08bbedb480d08470623 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Fri, 29 May 2026 12:08:42 +0300
Subject: [PATCH 077/118] docs(machine): document CallFrame and add the #213
 implementation plan

README + repo CLAUDE.md: withOverriddenHaltState now returns a CallFrame
(delegation, not field-aliasing); fix the stale "shares #symbolToDataMap" /
"shared debug cell" wrapper prose.
---
 CLAUDE.md                                     |   2 +-
 .../2026-05-29-callframe-extends-state.md     | 380 ++++++++++++++++++
 packages/machine/README.md                    |   8 +-
 3 files changed, 385 insertions(+), 5 deletions(-)
 create mode 100644 docs/superpowers/plans/2026-05-29-callframe-extends-state.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 2289e75..1c739fe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,7 +39,7 @@ Key shapes that take reading multiple files to grasp:
 
 - **`State` is keyed by `symbol` (the JS primitive), not by string.** A state definition is `{ [tapeBlock.symbol([...])]: { command, nextState } }`. `tapeBlock.symbol(...)` interns a *pattern* over all tapes in the block and returns a unique JS `Symbol`. `State.getSymbol(tapeBlock)` then matches the current head against those interned patterns; if nothing matches, the special `ifOtherSymbol` key is used as a fallback. This is why everything goes through `tapeBlock.symbol(...)` — it's both a symbol factory and a multi-tape pattern compiler. See `TapeBlock.#getSymbolForPatternList` and `State.getSymbol`.
 
-- **`State.withOverriddenHaltState(next)` is a composition primitive.** It returns a copy of the state whose `haltState` transition is replaced by a *continuation* pushed onto `TuringMachine`'s internal stack. When the machine would halt inside that subgraph, it instead pops and resumes. `library-binary-numbers/src/index.ts` uses this heavily (e.g. `minusOne` chains `invertNumber → plusOne → invertNumber → normalizeNumber`). When you see `.withOverriddenHaltState(...)`, read it as "subroutine call, then continue with the argument."
+- **`State.withOverriddenHaltState(next)` is a composition primitive.** It returns a **`CallFrame`** — a `State` subclass (so `instanceof State` holds; it flows anywhere a `State` does) that carries its own `bare` (the wrapped state) and `override` (`next`), *delegating* transition lookups and `debug` to the bare rather than aliasing the bare's private `#symbolToDataMap`/`#debugRef` (the v6 mechanism; reworked in [#213](https://github.com/mellonis/turing-machine-js/issues/213)). At run time the machine pushes the override onto `TuringMachine`'s internal stack; when it would halt inside that subgraph, it pops and resumes. `instanceof CallFrame` is the wrapper discriminator. `library-binary-numbers/src/index.ts` uses this heavily (e.g. `minusOne` chains `invertNumber → plusOne → invertNumber → normalizeNumber`). When you see `.withOverriddenHaltState(...)`, read it as "subroutine call, then continue with the argument."
 
 - **`Reference`** is a forward-declaration handle. `new Reference()` then `.bind(state)` later — this lets you build cyclic state graphs where a state's `nextState` is itself or a not-yet-constructed peer. The `builder` package relies on this to wire arbitrary state-name graphs in a single declarative pass; user code rarely needs `Reference` directly.
 
diff --git a/docs/superpowers/plans/2026-05-29-callframe-extends-state.md b/docs/superpowers/plans/2026-05-29-callframe-extends-state.md
new file mode 100644
index 0000000..904a399
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-29-callframe-extends-state.md
@@ -0,0 +1,380 @@
+# CallFrame extends State — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the implicit wrapper-State produced by `withOverriddenHaltState` (a plain `State` whose private `#symbolToDataMap`/`#debugRef` are aliased to its bare) with a first-class `CallFrame extends State` that *delegates* to its bare, with zero public behavior change.
+
+**Architecture:** `CallFrame` is a subclass of `State` defined inline in `State.ts` (after the `State` class, to avoid the `extends State` module-init TDZ cycle). It holds its own `#bare`/`#override`, overrides the transition-lookup methods + `debug` + `STATE_INTERNAL` to forward to `#bare`, and inherits `#id`/`#name`/`#tags`/`isHalt` unchanged. `withOverriddenHaltState` constructs a `CallFrame` instead of mutating a fresh `State`. Because `CallFrame instanceof State` stays true, no consumer migration is needed; `instanceof CallFrame` becomes the explicit wrapper discriminator.
+
+**Tech Stack:** TypeScript (project references), Vitest, npm workspaces. Run a single spec: `npx vitest run packages/machine/src/classes/State.spec.ts -t "name"`.
+
+**Branch:** `feat/213-callframe-extends-state` (off `v7`). Issue: mellonis/turing-machine-js#213.
+
+**Coverage floors (must hold):** 97% statements / 90% branches / 95% functions / 97% lines.
+
+---
+
+## File Structure
+
+- `packages/machine/src/classes/State.ts` — add `export class CallFrame extends State` after the `State` class; rewrite `withOverriddenHaltState` to build a `CallFrame`; route `State.inspect` through `STATE_INTERNAL` so it works for `CallFrame`; widen `#wrapperCache` value type to `WeakRef<CallFrame>`.
+- `packages/machine/src/classes/TuringMachine.ts` — simplify the `resolvableStateId` derivation (`:197-198`) to a `CallFrame` instanceof check; import `CallFrame`.
+- `packages/machine/src/index.ts` — export `CallFrame`.
+- `packages/machine/src/classes/State.spec.ts` — add CallFrame-identity / delegation tests.
+- Verification only (expected unchanged): `utilities/stateGraph.ts` (toGraph/fromGraph/collectStates), `TuringMachine.spec.ts`, `library-binary-numbers` specs, `test/round-trip.spec.ts`.
+
+---
+
+## Task 1: `CallFrame extends State` (inline in State.ts)
+
+**Files:**
+- Modify: `packages/machine/src/classes/State.ts`
+- Test: `packages/machine/src/classes/State.spec.ts`
+
+- [ ] **Step 1: Write failing tests** (append to `State.spec.ts`)
+
+```ts
+import State, {CallFrame, haltState, ifOtherSymbol} from './State';
+import TapeBlock from './TapeBlock';
+
+describe('CallFrame', () => {
+  const tb = TapeBlock.fromSymbols([['a', 'b']]);
+  const sA = new State({[tb.symbol([['a']])]: {nextState: haltState}}, 'A');
+  const sB = new State({[tb.symbol([['b']])]: {nextState: haltState}}, 'B');
+
+  it('withOverriddenHaltState returns a CallFrame that is also a State', () => {
+    const w = sA.withOverriddenHaltState(sB);
+    expect(w).toBeInstanceOf(State);
+    expect(w).toBeInstanceOf(CallFrame);
+  });
+
+  it('composite name is bare(override)', () => {
+    expect(sA.withOverriddenHaltState(sB).name).toBe('A(B)');
+  });
+
+  it('is not the halt state', () => {
+    expect(sA.withOverriddenHaltState(sB).isHalt).toBe(false);
+  });
+
+  it('exposes the override via overriddenHaltState', () => {
+    expect(sA.withOverriddenHaltState(sB).overriddenHaltState).toBe(sB);
+  });
+
+  it('delegates transition lookups to the bare', () => {
+    const w = sA.withOverriddenHaltState(sB);
+    const sym = sA.getSymbol(tb);
+    expect(w.getSymbol(tb)).toBe(sym);
+    expect(w.getNextState(sym)).toBe(sA.getNextState(sym));
+    expect(w.getMatchedTransition(sym).ix).toBe(sA.getMatchedTransition(sym).ix);
+  });
+
+  it('memoizes by (bare, override) — #175', () => {
+    expect(sA.withOverriddenHaltState(sB)).toBe(sA.withOverriddenHaltState(sB));
+  });
+
+  it('collapses a wohs chain — #176', () => {
+    const sC = new State({[tb.symbol([['a']])]: {nextState: haltState}}, 'C');
+    expect(sA.withOverriddenHaltState(sB).withOverriddenHaltState(sC))
+      .toBe(sA.withOverriddenHaltState(sC));
+  });
+
+  it('keeps tags independent across wrappers sharing a bare — #186', () => {
+    const sC = new State({[tb.symbol([['a']])]: {nextState: haltState}}, 'C');
+    sA.withOverriddenHaltState(sB).tag('hot');
+    expect(sA.withOverriddenHaltState(sC).tags).not.toContain('hot');
+  });
+
+  it('shares debug with the bare both ways', () => {
+    const w = sA.withOverriddenHaltState(sB);
+    const sym = sA.getSymbol(tb);
+    sA.debug = {before: [sym]};
+    expect(w.debug.before).toEqual([sym]);
+    w.debug = {after: [sym]};
+    expect(sA.debug.after).toEqual([sym]);
+    sA.debug = null;
+  });
+});
+```
+
+- [ ] **Step 2: Run, verify failure**
+
+Run: `npx vitest run packages/machine/src/classes/State.spec.ts -t "CallFrame"`
+Expected: FAIL — `CallFrame` is not exported from `./State`.
+
+- [ ] **Step 3: Add the `CallFrame` class** at the bottom of `State.ts`, after `export const haltState`:
+
+```ts
+export class CallFrame extends State {
+  readonly #bare: State;
+
+  readonly #override: State;
+
+  constructor(bare: State, override: State) {
+    super(null);
+    this.#bare = bare;
+    this.#override = override;
+    // Composite name bypasses the constructor's paren-validator by going
+    // through the STATE_INTERNAL name setter (writes the inherited #name).
+    this[STATE_INTERNAL]().name = `${bare.name}(${override.name})`;
+  }
+
+  get bare(): State {
+    return this.#bare;
+  }
+
+  get overriddenHaltState(): State {
+    return this.#override;
+  }
+
+  getSymbol(tapeBlock: TapeBlock) {
+    return this.#bare.getSymbol(tapeBlock);
+  }
+
+  getCommand(symbol: symbol) {
+    return this.#bare.getCommand(symbol);
+  }
+
+  getNextState(symbol: symbol) {
+    return this.#bare.getNextState(symbol);
+  }
+
+  getMatchedTransition(symbol: symbol) {
+    return this.#bare.getMatchedTransition(symbol);
+  }
+
+  get debug(): DebugConfig {
+    return this.#bare.debug;
+  }
+
+  set debug(
+    value: DebugConfig | { before?: symbol[] | readonly symbol[] | true; after?: symbol[] | readonly symbol[] | true } | null,
+  ) {
+    this.#bare.debug = value;
+  }
+
+  [STATE_INTERNAL]() {
+    // Own id/name/tags come from the inherited State fields (via super's
+    // view); bareState/override/transition-map delegate to #bare/#override.
+    const own = super[STATE_INTERNAL]();
+    const bare = this.#bare;
+    const override = this.#override;
+
+    return {
+      get id(): number { return own.id; },
+      get name(): string { return own.name; },
+      set name(v: string) { own.name = v; },
+      get bareState(): State | null { return bare; },
+      get overriddenHaltState(): State | null { return override; },
+      get symbolToDataMap() { return bare[STATE_INTERNAL]().symbolToDataMap; },
+      get tags(): ReadonlySet<string> { return own.tags; },
+    };
+  }
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `npx vitest run packages/machine/src/classes/State.spec.ts -t "CallFrame"`
+Expected: PASS (all CallFrame tests). If the `#wrapperCache`/`withOverriddenHaltState` still returns a plain `State`, the `instanceof CallFrame` test fails — that's fixed in Task 2; it's acceptable for Step 4 to leave `instanceof CallFrame` red until Task 2. Re-run after Task 2.
+
+> Note: the `instanceof CallFrame`, memoization, chain-collapse, tag, and debug tests depend on `withOverriddenHaltState` building a `CallFrame` (Task 2). Implement Task 2 immediately, then this whole block goes green.
+
+- [ ] **Step 5: Commit** (after Task 2 green — see Task 2 Step 6)
+
+---
+
+## Task 2: Build `CallFrame` in `withOverriddenHaltState`; route `inspect`; drop aliasing
+
+**Files:**
+- Modify: `packages/machine/src/classes/State.ts`
+
+- [ ] **Step 1: Widen the cache value type** (`State.ts:106`)
+
+```ts
+  static #wrapperCache = new WeakMap<State, WeakMap<State, WeakRef<CallFrame>>>();
+```
+
+- [ ] **Step 2: Rewrite `withOverriddenHaltState`** (replace the body, `State.ts:441-484`)
+
+```ts
+  withOverriddenHaltState(overriddenHaltState: State): CallFrame {
+    // Chain-collapse (#176): an inner override is dead at runtime, so a
+    // wrapped `this` unwraps to its bare before re-wrapping.
+    const bare = this instanceof CallFrame ? this.bare : this;
+
+    let innerCache = State.#wrapperCache.get(bare);
+
+    if (innerCache !== undefined) {
+      const ref = innerCache.get(overriddenHaltState);
+
+      if (ref !== undefined) {
+        const cached = ref.deref();
+
+        if (cached !== undefined) {
+          return cached;
+        }
+      }
+    } else {
+      innerCache = new WeakMap();
+      State.#wrapperCache.set(bare, innerCache);
+    }
+
+    const frame = new CallFrame(bare, overriddenHaltState);
+
+    innerCache.set(overriddenHaltState, new WeakRef(frame));
+
+    return frame;
+  }
+```
+
+This removes the four field-aliasing assignments (`#symbolToDataMap`, `#overriddenHaltState`, `#debugRef`, `#bareState`) — they no longer exist on a wrapper.
+
+- [ ] **Step 3: Route `State.inspect` through `STATE_INTERNAL`** so it reads the bare's transitions/override for a `CallFrame`. Replace the direct `state.#symbolToDataMap` / `state.#overriddenHaltState` / `state.#id` / `state.#name` reads in `inspect` (`State.ts:534-579`) with the internal view:
+
+```ts
+  static inspect(state: State): {
+    id: number;
+    name: string;
+    isHalt: boolean;
+    overriddenHaltState: { id: number; name: string } | null;
+    transitions: Array<{
+      rawPatternDescription: string | undefined;
+      command: Array<{ symbol: string; movement: string }>;
+      nextState: { id: number; name: string } | null;
+    }>;
+  } {
+    const internal = state[STATE_INTERNAL]();
+    const transitions: Array<{
+      rawPatternDescription: string | undefined;
+      command: Array<{ symbol: string; movement: string }>;
+      nextState: { id: number; name: string } | null;
+    }> = [];
+
+    for (const [sym, {command, nextState}] of internal.symbolToDataMap) {
+      let target: State | null = null;
+
+      try {
+        target = nextState instanceof State ? nextState : nextState.ref;
+      } catch {
+        target = null;
+      }
+
+      transitions.push({
+        rawPatternDescription: sym.description,
+        command: command.tapesCommands.map((tc) => ({
+          symbol: decodeWriteSymbol(tc.symbol),
+          movement: decodeMovement((tc.movement as symbol).description),
+        })),
+        nextState: target ? {id: target.id, name: target.name} : null,
+      });
+    }
+
+    const override = internal.overriddenHaltState;
+
+    return {
+      id: internal.id,
+      name: internal.name,
+      isHalt: state.isHalt,
+      overriddenHaltState: override
+        ? {id: override.id, name: override.name}
+        : null,
+      transitions,
+    };
+  }
+```
+
+- [ ] **Step 4: Run the full State spec + the matchedTransition spec**
+
+Run: `npx vitest run packages/machine/src/classes/State.spec.ts packages/machine/src/classes/State.debug.spec.ts`
+Expected: PASS, including the Task 1 `instanceof CallFrame` / memo / chain / tags / debug tests.
+
+- [ ] **Step 5: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors. (Watch for: `withOverriddenHaltState` return type vs `WeakRef<CallFrame>`; forward-reference of `CallFrame` as a type in the `#wrapperCache` annotation — allowed since types hoist.)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/machine/src/classes/State.ts packages/machine/src/classes/State.spec.ts
+git commit -m "Extract CallFrame as a State subclass; delegate instead of field-aliasing"
+```
+
+(Commit only with the user's explicit go-ahead — see CLAUDE.md.)
+
+---
+
+## Task 3: Simplify run-loop stateId resolution
+
+**Files:**
+- Modify: `packages/machine/src/classes/TuringMachine.ts`
+
+- [ ] **Step 1: Import `CallFrame`** (`TuringMachine.ts:1`)
+
+```ts
+import State, {CallFrame, haltState, STATE_INTERNAL, type DebugConfig} from './State';
+```
+
+- [ ] **Step 2: Replace the `resolvableStateId` derivation** (`TuringMachine.ts:189-198`). The `STATE_INTERNAL` peek for `bareState` becomes a direct `CallFrame` check:
+
+```ts
+        const resolvableStateId = state instanceof CallFrame ? state.bare.id : state.id;
+```
+
+Remove the now-unused `const stateInternal = state[STATE_INTERNAL]();` line and its comment block. If `STATE_INTERNAL` is no longer referenced anywhere else in `TuringMachine.ts`, drop it from the import (keep if `MACHINE_STATE_INTERNAL` plumbing or other sites still use it — grep first: `grep -n STATE_INTERNAL packages/machine/src/classes/TuringMachine.ts`).
+
+- [ ] **Step 3: Run the TuringMachine specs**
+
+Run: `npx vitest run packages/machine/src/classes/TuringMachine.spec.ts packages/machine/src/classes/TuringMachine.matchedTransition.spec.ts packages/machine/src/classes/TuringMachine.debug.spec.ts packages/machine/src/classes/DebugSession.spec.ts`
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/machine/src/classes/TuringMachine.ts
+git commit -m "Use CallFrame instanceof for run-loop stateId resolution"
+```
+
+---
+
+## Task 4: Export `CallFrame`; full verification gate
+
+**Files:**
+- Modify: `packages/machine/src/index.ts`
+
+- [ ] **Step 1: Export `CallFrame`** (`index.ts:4`)
+
+```ts
+export { default as State, CallFrame, DebugConfig, haltState, ifOtherSymbol } from './classes/State';
+```
+
+- [ ] **Step 2: Full suite**
+
+Run: `npm test`
+Expected: PASS, all packages. Pay attention to `library-binary-numbers` (the `minusOne` 4-deep `wohs` chain), `stateGraph.spec.ts` (toGraph/fromGraph/collectStates), and `test/round-trip.spec.ts` (bytewise stability for simple wrappers + shared-bare cases). These are the regression net for the delegation change.
+
+- [ ] **Step 3: Lint + typecheck + coverage**
+
+Run: `npm run lint && npm run typecheck && npm run test:coverage`
+Expected: clean lint, no type errors, coverage ≥ 97/90/95/97.
+
+- [ ] **Step 4: Build (smoke the Rollup repackage)**
+
+Run: `npm run build`
+Expected: success — confirms the new export + class compile through the project-references + Rollup post-step.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/machine/src/index.ts
+git commit -m "Export CallFrame from the public surface"
+```
+
+---
+
+## Self-Review notes
+
+- **Spec coverage:** CallFrame identity (T1), delegation of lookups/debug/STATE_INTERNAL (T1), memoization #175 (T1/T2), chain-collapse #176 (T1/T2), independent tags #186 (T1), inspect correctness (T2), run-loop simplification (T3), graph round-trip + collectStates (T4 verification), public discriminator export (T4). All design points covered.
+- **`isHalt`:** inherited; `super(null)` → fresh nonzero `#id` → false. No override.
+- **`validateDebugFilter`:** never runs on a CallFrame because `set debug` forwards to the bare, whose own validator uses the real transition map.
+- **Out of scope:** halt-stack stays `State[]` (no `CallFrame[]` rework); no naming changes; binary-numbers libraries untouched.
+- **Decision (locked):** CallFrame inline in State.ts (no cross-file `extends` cycle); debug delegates to bare (preserves shared contract).
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 4adf48e..b9ecdaa 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -239,7 +239,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).
@@ -378,7 +378,7 @@ for (const m of machine.runStepByStep({initialState})) {
 
 ## 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';
@@ -472,7 +472,7 @@ 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.
 
@@ -534,7 +534,7 @@ myState.debug = null;
 
 > ⚠️ **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`.**
 
-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.
+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.
 
 **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).
 

From d614dfae27bffbbe0172f1ab065097a4cc5c4d5e Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:00:14 +0300
Subject: [PATCH 078/118] docs(visuals): implementation plan for the extraction
 (#204)

---
 .../2026-05-30-visuals-package-extract.md     | 578 ++++++++++++++++++
 1 file changed, 578 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-30-visuals-package-extract.md

diff --git a/docs/superpowers/plans/2026-05-30-visuals-package-extract.md b/docs/superpowers/plans/2026-05-30-visuals-package-extract.md
new file mode 100644
index 0000000..2833a35
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-30-visuals-package-extract.md
@@ -0,0 +1,578 @@
+# `@turing-machine-js/visuals` package extraction — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extract machines-demo's pure highlight/graph-indexing modules + rules doc into a new lockstep-published package `@turing-machine-js/visuals`. NO new functionality in this PR — pure code-move + scaffold. `recordSnippet` + Snippet/Frame schema lands as a follow-up plan (issue step 3).
+
+**Architecture:** New `packages/visuals/` workspace, peer dep on `@turing-machine-js/machine` (`Graph` type only — no runtime dependency). Pure TypeScript, no DOM, no Svelte. Modules are line-for-line moves: `TuringGraph` local alias becomes `import { Graph } from '@turing-machine-js/machine'`; everything else unchanged. The rules doc moves under `packages/visuals/docs/`. machines-demo's local copies + the doc-source are deleted in a follow-up demo PR (issue step 2, **not** this PR — keeps the extract PR self-contained and reviewable against engine tests only).
+
+**Tech Stack:** TypeScript (project references), Vitest, npm workspaces, Lerna. Standard repo commands (`npm test`, `npm run lint`, `npm run typecheck`, `npm run build`) automatically pick up the new workspace.
+
+**Branch:** `feat/204-visuals-extract` (off `v7`). Issue: [mellonis/turing-machine-js#204](https://github.com/mellonis/turing-machine-js/issues/204).
+
+**Coverage floor (must hold):** 100% statements / 100% branches / 100% functions / 100% lines. The extracted modules are pure logic with no I/O; demo's existing test suites already hit 100% on these files. Drop is unexpected and indicates an extraction error.
+
+---
+
+## Decisions (locked in this plan)
+
+- **Package name: `@turing-machine-js/visuals`.** Issue #204 lists this as an open question between `visuals` / `highlight` / `graph-visuals`. Going with `visuals` — broadest, room for `recordSnippet` + future visual primitives without renaming.
+- **No DOM applier sub-export in v1.** The package stays purely renderer-agnostic. A future `@turing-machine-js/visuals/dom` sub-path can be added non-breakingly when there's a concrete consumer asking for one. Out of scope here.
+- **Snippet schema versioning policy (deferred to PR B).** This PR does NOT introduce the schema; recording the policy now keeps PR B short: additive fields don't bump `version`; breaking shape changes bump the integer. Will be documented in PR B's README addition.
+- **`graphHighlightDerivation.ts` does NOT extract.** Its `ExecutionMode` union mirrors machines-demo's MachineView state machine (`'DEMO' | 'MANUAL' | 'RUNNING_AUTO' | …`) — demo orchestration, not engine semantics. Stays in machines-demo and imports `bareIdOf` from the published package post-extract.
+- **`Snippet.engine` field is dropped (per #204 comment 2026-05-29).** Pinned here so PR B inherits the constraint. Engine identity lives at the caller bucket level (`{ turing: Snippet[], post: Snippet[] }`), not on the artifact.
+- **No content rewrites during the move.** Rules doc moves verbatim — any rewording is a separate edit later. Keeps this PR's diff a clean move.
+- **machines-demo cleanup (issue step 2) is a separate follow-up PR**, in the machines-demo repo, after this lands and lockstep-publishes with the next engine v7 alpha. This PR does NOT touch machines-demo.
+
+---
+
+## File Structure
+
+```
+packages/visuals/
+├── package.json              # NEW — peer dep on @turing-machine-js/machine
+├── tsconfig.json             # NEW — project references, extends repo conventions
+├── README.md                 # NEW — what this package is, public API summary
+├── src/
+│   ├── index.ts              # NEW — re-exports public surface
+│   ├── highlightOps.ts       # MOVED from machines-demo/src/lib/highlightOps.ts
+│   ├── graphUtils.ts         # MOVED from machines-demo/src/lib/graphUtils.ts
+│   ├── graphIndexes.ts       # MOVED from machines-demo/src/lib/graphIndexes.ts
+│   └── applyHighlight.ts     # MOVED from machines-demo/src/lib/applyHighlight.ts
+├── tests/
+│   ├── graphUtils.spec.ts    # MOVED — renamed .test.ts → .spec.ts to match repo convention
+│   ├── graphIndexes.spec.ts  # (no source test in demo; trivial test added if extraction warrants)
+│   ├── applyHighlight.spec.ts # MOVED + renamed
+│   ├── graphFixtures.spec.ts # MOVED + renamed
+│   └── fixtures/             # MOVED — fixture JSONs (graphs/*.json) used by graphFixtures
+└── docs/
+    └── graph-highlight-and-breakpoints.md  # MOVED from machines-demo/docs/
+
+tsconfig.build.json           # MODIFY — add reference to packages/visuals
+package.json                  # MODIFY — extend "typecheck" script to include packages/visuals
+```
+
+Public API exported from `packages/visuals/src/index.ts`:
+
+```ts
+// Types
+export type {
+  NodeKey, HighlightClass, HighlightOps, IndicatorOps, RecordedOp,
+} from './highlightOps';
+export type { GraphIndexes } from './graphIndexes';
+
+// Functions
+export { recordingOps } from './highlightOps';
+export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
+export { indexGraph } from './graphIndexes';
+export { applyHighlight, applyIndicator } from './applyHighlight';
+```
+
+Note: machines-demo's local `TuringGraph` alias resolves to `Graph` from `@turing-machine-js/machine`. The move replaces every `import { …, type TuringGraph } from './types.ts'` with `import { type Graph } from '@turing-machine-js/machine'` and renames the type at use-sites. `TuringGraph` is NOT re-exported from visuals — callers import `Graph` directly from `@turing-machine-js/machine`.
+
+---
+
+## Task 1: Scaffold `packages/visuals/`
+
+**Files:**
+- Create: `packages/visuals/package.json`
+- Create: `packages/visuals/tsconfig.json`
+- Create: `packages/visuals/README.md`
+- Create: `packages/visuals/src/index.ts`
+- Modify: `tsconfig.build.json`
+- Modify: `package.json` (root — extend `typecheck` script)
+
+- [ ] **Step 1: Write `packages/visuals/package.json`**
+
+```json
+{
+  "name": "@turing-machine-js/visuals",
+  "version": "7.0.0-alpha.6",
+  "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "src", "docs", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": {
+    "prepublishOnly": "npm run --workspaces=false -w @turing-machine-js/visuals build"
+  },
+  "peerDependencies": {
+    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+> **Verify before committing:** version field matches the current engine alpha tag. Cross-check `packages/machine/package.json`'s version. Lerna's `version` command keeps these in lockstep on the next bump.
+
+- [ ] **Step 2: Write `packages/visuals/tsconfig.json`**
+
+Mirror `packages/machine/tsconfig.json`'s structure. Read it first, then create:
+
+```json
+{
+  "extends": "@tsconfig/recommended/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "composite": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "es2022",
+    "strict": true
+  },
+  "references": [
+    { "path": "../machine" }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+> Adjust to match `packages/machine/tsconfig.json` exactly if it differs — repo convention overrides the example above.
+
+- [ ] **Step 3: Write `packages/visuals/README.md`**
+
+```markdown
+# @turing-machine-js/visuals
+
+Pure highlight + graph-indexing logic for [`@turing-machine-js/machine`](../machine). No DOM, no Svelte, no Mermaid — consumers bring their own renderer and DOM applier.
+
+## Scope
+
+Types and pure functions for:
+- Indexing an engine `Graph` for wrapper/bare lookup (`indexGraph`, `bareIdOf`, `highlightExpand`).
+- Applying highlight + indicator operations against a renderer-agnostic `HighlightOps` interface (`applyHighlight`, `applyIndicator`).
+
+See [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md) for the full set of rules these functions satisfy.
+
+## Versioning
+
+Lockstep with `@turing-machine-js/machine`.
+
+## Install
+
+\`\`\`sh
+npm install @turing-machine-js/visuals @turing-machine-js/machine
+\`\`\`
+```
+
+- [ ] **Step 4: Write `packages/visuals/src/index.ts` (empty for now)**
+
+```ts
+// Public API — populated as modules are moved in Tasks 2–5.
+export {};
+```
+
+- [ ] **Step 5: Modify `tsconfig.build.json` — add reference**
+
+Read the file first; then append `{ "path": "packages/visuals" }` to its `references` array.
+
+- [ ] **Step 6: Modify root `package.json` — extend `typecheck` script**
+
+Read the current value:
+```
+"typecheck": "tsc --noEmit -p packages/machine/tsconfig.json && tsc --noEmit -p packages/builder/tsconfig.json && tsc --noEmit -p packages/library-binary-numbers/tsconfig.json && tsc --noEmit -p packages/library-binary-numbers-bare/tsconfig.json"
+```
+
+Add `&& tsc --noEmit -p packages/visuals/tsconfig.json` at the end.
+
+- [ ] **Step 7: Verify scaffolding compiles**
+
+Run: `npm install && npm run typecheck && npm run build`
+Expected: green. No new tests yet; existing engine tests still pass.
+
+- [ ] **Step 8: Commit**
+
+```sh
+git add packages/visuals tsconfig.build.json package.json package-lock.json
+git commit -m "feat(visuals): scaffold @turing-machine-js/visuals package (#204)"
+```
+
+---
+
+## Task 2: Move `highlightOps.ts`
+
+**Files:**
+- Read: `../machines-demo/src/lib/highlightOps.ts` (source — outside this repo; copy contents, do NOT modify the source from this repo)
+- Create: `packages/visuals/src/highlightOps.ts`
+- Modify: `packages/visuals/src/index.ts`
+
+- [ ] **Step 1: Read source**
+
+Read `../machines-demo/src/lib/highlightOps.ts` in full. It has no external imports beyond TypeScript stdlib types — a pure types + recordingOps module. Direct move.
+
+- [ ] **Step 2: Create the file at the new location**
+
+Write `packages/visuals/src/highlightOps.ts` with the source contents verbatim. No import changes needed (it has none).
+
+- [ ] **Step 3: Add to public exports**
+
+In `packages/visuals/src/index.ts`:
+```ts
+export type { NodeKey, HighlightClass, HighlightOps, IndicatorOps, RecordedOp } from './highlightOps';
+export { recordingOps } from './highlightOps';
+```
+
+- [ ] **Step 4: Typecheck**
+
+Run: `npm run typecheck`
+Expected: green.
+
+- [ ] **Step 5: Commit**
+
+```sh
+git add packages/visuals/src
+git commit -m "feat(visuals): move highlightOps from machines-demo (#204)"
+```
+
+---
+
+## Task 3: Move `graphUtils.ts` + test
+
+**Files:**
+- Read: `../machines-demo/src/lib/graphUtils.ts`, `../machines-demo/src/lib/graphUtils.test.ts`
+- Create: `packages/visuals/src/graphUtils.ts`
+- Create: `packages/visuals/tests/graphUtils.spec.ts`
+- Modify: `packages/visuals/src/index.ts`
+
+- [ ] **Step 1: Read source files**
+
+Read both `graphUtils.ts` and `graphUtils.test.ts` from machines-demo. Note imports:
+- Source imports `type TuringGraph` from local `./types.ts` (demo-local alias).
+- Test imports the source + may import test fixtures.
+
+- [ ] **Step 2: Create `packages/visuals/src/graphUtils.ts`**
+
+Copy source contents. Replace the line:
+```ts
+import type { TuringGraph } from './types.ts';
+```
+with:
+```ts
+import type { Graph } from '@turing-machine-js/machine';
+```
+Then rename `TuringGraph` → `Graph` at every use-site in this file.
+
+- [ ] **Step 3: Create `packages/visuals/tests/graphUtils.spec.ts`**
+
+Copy test contents. Update import paths:
+- `from '../src/lib/graphUtils.ts'` → `from '../src/graphUtils'`
+- Any `TuringGraph` → `Graph` from `@turing-machine-js/machine`
+
+If the test references fixtures, defer their move to Task 5 (graphFixtures) — for now, gate any fixture-dependent test on the file existing or comment it out with a `// TODO Task 5: restore after fixtures move` marker. If no fixture deps, the test is self-contained.
+
+- [ ] **Step 4: Add to public exports**
+
+In `packages/visuals/src/index.ts`, append:
+```ts
+export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
+```
+
+- [ ] **Step 5: Run the moved test**
+
+Run: `npx vitest run packages/visuals/tests/graphUtils.spec.ts`
+Expected: same passing count as the original in machines-demo (or skipped count for fixture-deferred tests).
+
+- [ ] **Step 6: Typecheck**
+
+Run: `npm run typecheck`
+Expected: green.
+
+- [ ] **Step 7: Commit**
+
+```sh
+git add packages/visuals
+git commit -m "feat(visuals): move graphUtils + test (#204)"
+```
+
+---
+
+## Task 4: Move `graphIndexes.ts` (+ test if present)
+
+**Files:**
+- Read: `../machines-demo/src/lib/graphIndexes.ts`
+- Create: `packages/visuals/src/graphIndexes.ts`
+- Modify: `packages/visuals/src/index.ts`
+
+- [ ] **Step 1: Read source**
+
+Read `graphIndexes.ts`. Note the imports — likely `TuringGraph` from local types.
+
+- [ ] **Step 2: Create `packages/visuals/src/graphIndexes.ts`**
+
+Copy contents, replace `TuringGraph` import with `import type { Graph } from '@turing-machine-js/machine'`, rename use-sites.
+
+- [ ] **Step 3: Add to public exports**
+
+```ts
+export type { GraphIndexes } from './graphIndexes';
+export { indexGraph } from './graphIndexes';
+```
+
+- [ ] **Step 4: Verify**
+
+Run: `npm run typecheck`
+Expected: green.
+
+> **Note:** machines-demo does NOT ship a standalone `graphIndexes.test.ts` (only an `applyHighlight.test.ts` and `graphUtils.test.ts`). `indexGraph` is exercised transitively by the applyHighlight tests in Task 6. No dedicated test added in this PR — extraction parity is preserved.
+
+- [ ] **Step 5: Commit**
+
+```sh
+git add packages/visuals
+git commit -m "feat(visuals): move graphIndexes (#204)"
+```
+
+---
+
+## Task 5: Move `graphFixtures.test.ts` + fixture JSONs
+
+**Files:**
+- Read: `../machines-demo/src/lib/graphFixtures.test.ts` + any `tests/fixtures/graphs/*.json` referenced
+- Create: `packages/visuals/tests/graphFixtures.spec.ts`
+- Create: `packages/visuals/tests/fixtures/graphs/*.json` (one file per fixture)
+
+- [ ] **Step 1: Read test + identify fixture files**
+
+Read `graphFixtures.test.ts`. Find every `import` or `readFileSync` / `JSON.parse` of a fixture path. List them.
+
+- [ ] **Step 2: Copy each fixture JSON file verbatim**
+
+For each fixture path discovered in Step 1, copy the file from machines-demo to `packages/visuals/tests/fixtures/graphs/<name>.json`. Do not modify the JSON — these are engine-emit snapshots and must roundtrip byte-for-byte.
+
+- [ ] **Step 3: Create the test file**
+
+Copy `graphFixtures.test.ts` contents to `packages/visuals/tests/graphFixtures.spec.ts`. Update:
+- Source import paths (`from '../lib/...'` → `from '../src/...'`).
+- Fixture path strings (`./fixtures/graphs/...` should already resolve from the new test location since fixtures are colocated under `tests/fixtures/`).
+- Any `import * as turing from '@turing-machine-js/machine'` already correct.
+- Type rename: `TuringGraph` → `Graph`.
+
+- [ ] **Step 4: Run the fixture test**
+
+Run: `npx vitest run packages/visuals/tests/graphFixtures.spec.ts`
+Expected: same passing count as in machines-demo. Fixture roundtrip MUST pass — failure here indicates engine-emit drift OR an extraction-time corruption of the JSON.
+
+- [ ] **Step 5: Commit**
+
+```sh
+git add packages/visuals/tests
+git commit -m "feat(visuals): move graphFixtures test + fixture JSONs (#204)"
+```
+
+---
+
+## Task 6: Move `applyHighlight.ts` + test
+
+**Files:**
+- Read: `../machines-demo/src/lib/applyHighlight.ts`, `../machines-demo/src/lib/applyHighlight.test.ts`
+- Create: `packages/visuals/src/applyHighlight.ts`
+- Create: `packages/visuals/tests/applyHighlight.spec.ts`
+- Modify: `packages/visuals/src/index.ts`
+
+- [ ] **Step 1: Read source files**
+
+Read both. Note all imports — likely:
+- `import type { TuringGraph } from './types.ts'`
+- `import { ... } from './graphUtils.ts'`
+- `import { ... } from './graphIndexes.ts'`
+- `import { ... } from './highlightOps.ts'`
+
+- [ ] **Step 2: Create `packages/visuals/src/applyHighlight.ts`**
+
+Copy source. Replace:
+- `TuringGraph` import → `import type { Graph } from '@turing-machine-js/machine'` + rename uses.
+- Local imports from `./graphUtils.ts` / `./graphIndexes.ts` / `./highlightOps.ts` → drop the `.ts` extension only if needed for the package's resolution (match the convention used in Tasks 2–4).
+
+- [ ] **Step 3: Create `packages/visuals/tests/applyHighlight.spec.ts`**
+
+Copy test. Update import paths to point at `../src/...`. Rename `TuringGraph` → `Graph`.
+
+- [ ] **Step 4: Add to public exports**
+
+```ts
+export { applyHighlight, applyIndicator } from './applyHighlight';
+```
+
+- [ ] **Step 5: Run the test**
+
+Run: `npx vitest run packages/visuals/tests/applyHighlight.spec.ts`
+Expected: all original tests pass at new location. Same count as in machines-demo.
+
+- [ ] **Step 6: Restore any fixture-deferred tests from Task 3**
+
+If Task 3 commented out fixture-dependent graphUtils tests, uncomment them now and verify they pass. Fixtures are in place since Task 5.
+
+- [ ] **Step 7: Full test + typecheck + lint**
+
+Run: `npm test && npm run typecheck && npm run lint`
+Expected: green across all four packages (machine, builder, library-binary-numbers, library-binary-numbers-bare) + the new visuals.
+
+- [ ] **Step 8: Commit**
+
+```sh
+git add packages/visuals
+git commit -m "feat(visuals): move applyHighlight + applyIndicator + test (#204)"
+```
+
+---
+
+## Task 7: Move the rules doc
+
+**Files:**
+- Read: `../machines-demo/docs/graph-highlight-and-breakpoints.md`
+- Create: `packages/visuals/docs/graph-highlight-and-breakpoints.md`
+
+- [ ] **Step 1: Read the source doc**
+
+Read `../machines-demo/docs/graph-highlight-and-breakpoints.md` fully (~272 lines).
+
+- [ ] **Step 2: Copy verbatim**
+
+Create `packages/visuals/docs/graph-highlight-and-breakpoints.md` with identical contents. NO rewrites, NO scope changes, NO reformatting. If any in-doc cross-link points to a machines-demo path (e.g., `../src/components/MachineGraph.svelte`), leave it intact — fixing those links is part of the follow-up machines-demo cleanup PR (issue step 2). A `git mv`-shaped change preserves blame across the move (run `git log --follow` on the new path to verify).
+
+- [ ] **Step 3: Verify the README link resolves**
+
+The `packages/visuals/README.md` from Task 1 links to `./docs/graph-highlight-and-breakpoints.md` — confirm the file is at that path.
+
+- [ ] **Step 4: Commit**
+
+```sh
+git add packages/visuals/docs
+git commit -m "docs(visuals): move highlight + breakpoints rules doc (#204)"
+```
+
+---
+
+## Task 8: Coverage verify + CHANGELOG
+
+**Files:**
+- Create: `packages/visuals/CHANGELOG.md`
+
+- [ ] **Step 1: Run coverage**
+
+Run: `npm run test:coverage`
+Expected: visuals package at **100% / 100% / 100% / 100%**. If any file is below 100%, identify the missing branch — likely a defensive `null` check from the demo's original code. Either:
+- Add a missing test case if the branch is reachable.
+- Document the unreachable branch in the file (one-line comment) and verify reviewers accept it.
+
+> **Do NOT lower the floor.** A drop below 100% means extraction-time scope mismatch; investigate before committing.
+
+- [ ] **Step 2: Write `packages/visuals/CHANGELOG.md`**
+
+Per repo convention, every release-bound package needs a CHANGELOG entry up front:
+
+```markdown
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- Initial extraction from machines-demo: `Highlight`/`HighlightOps`/`GraphIndexes` types, `indexGraph`, `applyHighlight`, `applyIndicator`, `bareIdOf`, `highlightExpand`, `equivalentIds`, `recordingOps`. Rules doc moved into `docs/graph-highlight-and-breakpoints.md`. Closes mellonis/turing-machine-js#204 (extraction step; recordSnippet follows in a separate PR).
+```
+
+> The `[Unreleased]` heading converts to `[X.Y.Z] - YYYY-MM-DD` during the release-PR pass (per workspace `CLAUDE.md` "CHANGELOG.md is part of every v-bump PR" rule). Not bumped in this PR — version bump is part of the next engine alpha release PR that includes visuals.
+
+- [ ] **Step 3: Commit**
+
+```sh
+git add packages/visuals/CHANGELOG.md
+git commit -m "docs(visuals): add CHANGELOG with extraction entry (#204)"
+```
+
+---
+
+## Task 9: Open PR
+
+- [ ] **Step 1: Push the branch**
+
+```sh
+git push -u origin feat/204-visuals-extract
+```
+
+- [ ] **Step 2: Open the PR against `v7`**
+
+```sh
+gh pr create \
+  --repo mellonis/turing-machine-js \
+  --base v7 \
+  --head feat/204-visuals-extract \
+  --title "feat(visuals): extract @turing-machine-js/visuals (#204, step 1)" \
+  --body "$(cat <<'EOF'
+## Summary
+
+Extracts pure highlight + graph-indexing modules from machines-demo into a new lockstep-published package `@turing-machine-js/visuals`. Step 1 of [#204](https://github.com/mellonis/turing-machine-js/issues/204) — extraction only. \`recordSnippet\` + Snippet/Frame schema lands in a follow-up PR (step 3). machines-demo consumption (step 2) lands in machines-demo as a separate PR after this publishes.
+
+What's in:
+
+- New \`packages/visuals/\` workspace (peer dep on \`@turing-machine-js/machine\`, no runtime dep, no DOM).
+- Moves: \`highlightOps\`, \`graphUtils\`, \`graphIndexes\`, \`applyHighlight\` + their tests.
+- Rules doc moves to \`packages/visuals/docs/graph-highlight-and-breakpoints.md\` verbatim.
+- Public API exported from \`packages/visuals/src/index.ts\`.
+
+What's NOT in (deliberate):
+
+- \`graphHighlightDerivation.ts\` stays in machines-demo — its \`ExecutionMode\` union is demo-coupled, not engine semantics.
+- \`recordSnippet\`, \`Snippet\`, \`Frame\` types — follow-up PR.
+- machines-demo cleanup — separate PR in machines-demo.
+
+Decisions locked in [\`docs/superpowers/plans/2026-05-30-visuals-package-extract.md\`](docs/superpowers/plans/2026-05-30-visuals-package-extract.md): package name = \`visuals\`; no DOM applier sub-export in v1; \`Snippet.engine\` field dropped (per #204 comment 2026-05-29).
+
+## Test plan
+
+- [x] \`npm test\` — all packages including new visuals.
+- [x] \`npm run typecheck\` — clean across all 5 packages.
+- [x] \`npm run lint\` — clean.
+- [x] \`npm run test:coverage\` — visuals at 100% / 100% / 100% / 100%.
+- [x] \`npm run build\` — clean.
+- [x] Fixture roundtrip test passes — engine emit shape unchanged.
+
+Note: v7-branch PRs do not run CI per repo convention; checks run on the eventual v7 → master integration PR.
+EOF
+)"
+```
+
+- [ ] **Step 3: Verify PR URL returned**
+
+Capture the PR URL and report back. Done.
+
+---
+
+## Self-review checklist
+
+Before opening the PR, walk this list one more time:
+
+- [ ] Every moved file's `TuringGraph` references replaced with `Graph` from `@turing-machine-js/machine`.
+- [ ] No source files still reference `./types.ts` (machines-demo-local).
+- [ ] `packages/visuals/src/index.ts` exports the full public surface (5 types, 7 functions).
+- [ ] No machines-demo source files were modified — this PR is engine-side only.
+- [ ] Coverage at 100/100/100/100 for the visuals package.
+- [ ] CHANGELOG entry under `[Unreleased]` exists and references the issue.
+- [ ] All `Task N` commits have clear, scope-prefixed messages (`feat(visuals):` or `docs(visuals):`).
+- [ ] No commit includes `🤖 Generated with Claude Code` or any Claude attribution footer (per global CLAUDE.md).
+- [ ] No `--no-verify` or signature-skip flags used.
+
+---
+
+## What happens after this lands
+
+1. **Lockstep publish** with the next engine v7 alpha (bump `7.0.0-alpha.6` → `7.0.0-alpha.7`, etc.) via `lerna publish from-package --dist-tag next`. Same release PR that bumps engine packages bumps visuals.
+2. **Follow-up plan** for `recordSnippet` + Snippet/Frame schema (issue #204 step 3). Will be saved at `docs/superpowers/plans/<date>-visuals-recordsnippet.md`.
+3. **Follow-up PR in machines-demo** (issue #204 step 2) — drop the local copies of the moved modules + rules doc; depend on `@turing-machine-js/visuals` from npm `next`.
+4. **Tiny edit to merged machines-demo spec** (`docs/superpowers/specs/2026-05-27-landing-page-design.md`) — remove the stray `engine` field reference from the snippet-schema decision now that the upstream schema dropped it.

From be77b79729fb7f655c10d9504fd7b8e6ce2c5ee5 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:02:18 +0300
Subject: [PATCH 079/118] feat(visuals): scaffold @turing-machine-js/visuals
 package (#204)

---
 package-lock.json              | 15 ++++++++++++
 package.json                   |  2 +-
 packages/visuals/README.md     | 21 ++++++++++++++++
 packages/visuals/package.json  | 45 ++++++++++++++++++++++++++++++++++
 packages/visuals/src/index.ts  |  2 ++
 packages/visuals/tsconfig.json | 10 ++++++++
 tsconfig.build.json            |  3 +++
 7 files changed, 97 insertions(+), 1 deletion(-)
 create mode 100644 packages/visuals/README.md
 create mode 100644 packages/visuals/package.json
 create mode 100644 packages/visuals/src/index.ts
 create mode 100644 packages/visuals/tsconfig.json

diff --git a/package-lock.json b/package-lock.json
index a03f9f1..5e519b1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2781,6 +2781,10 @@
       "resolved": "packages/machine",
       "link": true
     },
+    "node_modules/@turing-machine-js/visuals": {
+      "resolved": "packages/visuals",
+      "link": true
+    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.9.0",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.9.0.tgz",
@@ -10694,6 +10698,17 @@
       "engines": {
         "npm": ">=7.0.0"
       }
+    },
+    "packages/visuals": {
+      "name": "@turing-machine-js/visuals",
+      "version": "7.0.0-alpha.6",
+      "license": "GPL-3.0-or-later",
+      "engines": {
+        "npm": ">=7.0.0"
+      },
+      "peerDependencies": {
+        "@turing-machine-js/machine": "^7.0.0-alpha.6"
+      }
     }
   }
 }
diff --git a/package.json b/package.json
index 9ebb1be..767d313 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,7 @@
     "test:coverage": "vitest run --coverage",
     "docs:states": "node ./scripts/build-states-md.mjs",
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit -p packages/machine/tsconfig.json && tsc --noEmit -p packages/builder/tsconfig.json && tsc --noEmit -p packages/library-binary-numbers/tsconfig.json && tsc --noEmit -p packages/library-binary-numbers-bare/tsconfig.json"
+    "typecheck": "tsc --noEmit -p packages/machine/tsconfig.json && tsc --noEmit -p packages/builder/tsconfig.json && tsc --noEmit -p packages/library-binary-numbers/tsconfig.json && tsc --noEmit -p packages/library-binary-numbers-bare/tsconfig.json && tsc --noEmit -p packages/visuals/tsconfig.json"
   },
   "author": "Ruslan Gilmullin <mellonis@yandex.ru>",
   "workspaces": [
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
new file mode 100644
index 0000000..9fdf932
--- /dev/null
+++ b/packages/visuals/README.md
@@ -0,0 +1,21 @@
+# @turing-machine-js/visuals
+
+Pure highlight + graph-indexing logic for [`@turing-machine-js/machine`](../machine). No DOM, no Svelte, no Mermaid — consumers bring their own renderer and DOM applier.
+
+## Scope
+
+Types and pure functions for:
+- Indexing an engine `Graph` for wrapper/bare lookup (`indexGraph`, `bareIdOf`, `highlightExpand`).
+- Applying highlight + indicator operations against a renderer-agnostic `HighlightOps` interface (`applyHighlight`, `applyIndicator`).
+
+See [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md) for the full set of rules these functions satisfy.
+
+## Versioning
+
+Lockstep with `@turing-machine-js/machine`.
+
+## Install
+
+```sh
+npm install @turing-machine-js/visuals @turing-machine-js/machine
+```
diff --git a/packages/visuals/package.json b/packages/visuals/package.json
new file mode 100644
index 0000000..af0149c
--- /dev/null
+++ b/packages/visuals/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@turing-machine-js/visuals",
+  "version": "7.0.0-alpha.6",
+  "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
+  "engines": {
+    "npm": ">=7.0.0"
+  },
+  "author": "Ruslan Gilmullin <mellonis@yandex.ru>",
+  "homepage": "https://github.com/mellonis/turing-machine-js#readme",
+  "license": "GPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mellonis/turing-machine-js.git",
+    "directory": "packages/visuals"
+  },
+  "bugs": {
+    "url": "https://github.com/mellonis/turing-machine-js/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22pkg%3A+visuals%22+label%3Abug"
+  },
+  "keywords": [
+    "turing",
+    "machine",
+    "visualization"
+  ],
+  "peerDependencies": {
+    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+  },
+  "scripts": {
+    "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/visuals",
+    "prepublishOnly": "npm run build"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  }
+}
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
new file mode 100644
index 0000000..2a98212
--- /dev/null
+++ b/packages/visuals/src/index.ts
@@ -0,0 +1,2 @@
+// Public API — populated as modules are moved in Tasks 2–8.
+export {};
diff --git a/packages/visuals/tsconfig.json b/packages/visuals/tsconfig.json
new file mode 100644
index 0000000..bbd6d2d
--- /dev/null
+++ b/packages/visuals/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "outDir": "dist",
+    "paths": {
+      "@turing-machine-js/*": ["../*/src/index"]
+    }
+  }
+}
diff --git a/tsconfig.build.json b/tsconfig.build.json
index 54c23f0..34596dd 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -12,6 +12,9 @@
     },
     {
       "path": "packages/machine/tsconfig.build.json"
+    },
+    {
+      "path": "packages/visuals/tsconfig.json"
     }
   ]
 }

From 44e716f66bb6c5d558b94f46bd1fdffc9907412a Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:09:07 +0300
Subject: [PATCH 080/118] fix(visuals): add tsconfig.build.json + wire vitest
 alias + build script (#204)

---
 packages/visuals/tsconfig.build.json | 8 ++++++++
 scripts/build-node-entries.mjs       | 5 +++++
 tsconfig.build.json                  | 2 +-
 vitest.config.ts                     | 1 +
 4 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 packages/visuals/tsconfig.build.json

diff --git a/packages/visuals/tsconfig.build.json b/packages/visuals/tsconfig.build.json
new file mode 100644
index 0000000..90d36e8
--- /dev/null
+++ b/packages/visuals/tsconfig.build.json
@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "composite": true
+  },
+  "exclude": ["**/*.spec.ts", "dist"]
+}
diff --git a/scripts/build-node-entries.mjs b/scripts/build-node-entries.mjs
index 15ea4bc..2e27aca 100644
--- a/scripts/build-node-entries.mjs
+++ b/scripts/build-node-entries.mjs
@@ -35,6 +35,11 @@ const allPackages = [
     dir: 'packages/library-binary-numbers-bare',
     external: ['@turing-machine-js/machine'],
   },
+  {
+    name: '@turing-machine-js/visuals',
+    dir: 'packages/visuals',
+    external: ['@turing-machine-js/machine'],
+  },
 ];
 
 const packages = requestedPkg
diff --git a/tsconfig.build.json b/tsconfig.build.json
index 34596dd..893b88a 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -14,7 +14,7 @@
       "path": "packages/machine/tsconfig.build.json"
     },
     {
-      "path": "packages/visuals/tsconfig.json"
+      "path": "packages/visuals/tsconfig.build.json"
     }
   ]
 }
diff --git a/vitest.config.ts b/vitest.config.ts
index dde06ed..9fc300c 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -47,6 +47,7 @@ export default defineConfig({
       '@turing-machine-js/builder': resolve(root, './packages/builder/src'),
       '@turing-machine-js/library-binary-numbers': resolve(root, './packages/library-binary-numbers/src'),
       '@turing-machine-js/library-binary-numbers-bare': resolve(root, './packages/library-binary-numbers-bare/src'),
+      '@turing-machine-js/visuals': resolve(root, './packages/visuals/src'),
     },
   },
 });

From ff74620a17662d807fa50fe6a9a1f8932afb3a25 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:15:59 +0300
Subject: [PATCH 081/118] fix(visuals): declare machine dependency in
 tsconfig.build.json references (#204)

---
 packages/visuals/tsconfig.build.json | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/visuals/tsconfig.build.json b/packages/visuals/tsconfig.build.json
index 90d36e8..067b7ab 100644
--- a/packages/visuals/tsconfig.build.json
+++ b/packages/visuals/tsconfig.build.json
@@ -4,5 +4,8 @@
     "rootDir": "src",
     "composite": true
   },
+  "references": [
+    { "path": "../machine/tsconfig.build.json" }
+  ],
   "exclude": ["**/*.spec.ts", "dist"]
 }

From 9307668237892e7a59feb46f9432842f9e7a29ba Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:19:45 +0300
Subject: [PATCH 082/118] feat(visuals): move highlightOps from machines-demo
 (#204)

---
 packages/visuals/src/highlightOps.ts | 94 ++++++++++++++++++++++++++++
 packages/visuals/src/index.ts        |  3 +-
 2 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 packages/visuals/src/highlightOps.ts

diff --git a/packages/visuals/src/highlightOps.ts b/packages/visuals/src/highlightOps.ts
new file mode 100644
index 0000000..97a443f
--- /dev/null
+++ b/packages/visuals/src/highlightOps.ts
@@ -0,0 +1,94 @@
+/**
+ * Contract between the pure highlight logic (`applyHighlight`,
+ * `applyIndicator`) and any consumer that actually renders the graph
+ * (Svelte component, vanilla embed, server-side snapshot, etc.).
+ *
+ * The pure functions decide *what* should happen (which node gets a class,
+ * which edge lights up, where to pulse); the consumer's `HighlightOps`
+ * implementation decides *how* (DOM mutation, recording for tests, etc.).
+ *
+ * See `docs/graph-highlight-and-breakpoints.md` for the rules each
+ * implementation must respect.
+ */
+
+export type NodeKey = number | 'idle';
+
+/** Classes the apply-highlight pass may add to a `g.node` element. */
+export type HighlightClass =
+  | 'mg-highlight-from'
+  | 'mg-highlight-to'
+  | 'mg-highlight-strong';
+
+/**
+ * Operations the highlight logic invokes on the rendered graph. Purely
+ * additive — the consumer is expected to clear previous highlight state
+ * (classes, marker swaps) BEFORE invoking `applyHighlight`. The pure
+ * function never reads back from the consumer; it just emits ops.
+ *
+ * Edge keys follow mermaid's data-id token form: `'idle'` for the
+ * synthetic entry sentinel, `'s${id}'` for regular/wrapper/bare states,
+ * `'c${id}'` for halt markers (id = `-frameId`), `'w_${id}'` for callable-
+ * subtree subgraph clusters. Mermaid emits `L_${from}_${to}_${ix}` per
+ * edge; ix-resolution is the consumer's concern (multiple edges between
+ * the same pair are rare; the consumer typically picks the first match).
+ */
+export interface HighlightOps {
+  /** Add a highlight class to the node identified by `id`. */
+  addNodeClass(id: NodeKey, cls: HighlightClass): void;
+
+  /** Highlight the edge whose data-id matches `L_${fromKey}_${toKey}_*`. */
+  highlightEdge(fromKey: string, toKey: string): void;
+
+  /** Mark the callable-subtree cluster for `frameId` as active. */
+  markFrameActive(frameId: number): void;
+
+  /** Fire a one-shot pulse animation on the given node. */
+  pulse(id: NodeKey): void;
+
+  /** Scroll the given node into the visible area of its container. */
+  scrollIntoView(id: NodeKey): void;
+}
+
+/** Operations the indicator (breakpoint dot) pass invokes. */
+export interface IndicatorOps {
+  /** Set or clear the breakpoint indicator on the given node. */
+  setBreakpoint(id: NodeKey, on: boolean): void;
+}
+
+/** A single recorded op — serializable, suitable for snapshot tests. */
+export type RecordedOp =
+  | { op: 'addNodeClass'; id: NodeKey; cls: HighlightClass }
+  | { op: 'highlightEdge'; fromKey: string; toKey: string }
+  | { op: 'markFrameActive'; frameId: number }
+  | { op: 'pulse'; id: NodeKey }
+  | { op: 'scrollIntoView'; id: NodeKey }
+  | { op: 'setBreakpoint'; id: NodeKey; on: boolean };
+
+/**
+ * Build a recording `HighlightOps` + `IndicatorOps` pair plus the shared
+ * `record` array of calls in invocation order. Used by tests to assert
+ * what the pure logic would have done without running a real DOM.
+ *
+ * Snapshot-friendly: the record contains only plain JSON-serializable
+ * values (no DOM nodes, no function refs).
+ */
+export function recordingOps(): {
+  highlight: HighlightOps;
+  indicator: IndicatorOps;
+  record: RecordedOp[];
+} {
+  const record: RecordedOp[] = [];
+  return {
+    record,
+    highlight: {
+      addNodeClass(id, cls) { record.push({ op: 'addNodeClass', id, cls }); },
+      highlightEdge(fromKey, toKey) { record.push({ op: 'highlightEdge', fromKey, toKey }); },
+      markFrameActive(frameId) { record.push({ op: 'markFrameActive', frameId }); },
+      pulse(id) { record.push({ op: 'pulse', id }); },
+      scrollIntoView(id) { record.push({ op: 'scrollIntoView', id }); },
+    },
+    indicator: {
+      setBreakpoint(id, on) { record.push({ op: 'setBreakpoint', id, on }); },
+    },
+  };
+}
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 2a98212..1206e90 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -1,2 +1,3 @@
 // Public API — populated as modules are moved in Tasks 2–8.
-export {};
+export type { NodeKey, HighlightClass, HighlightOps, IndicatorOps, RecordedOp } from './highlightOps';
+export { recordingOps } from './highlightOps';

From 676d115e3338361b38a41e3b2b728e6d5439b4db Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:42:55 +0300
Subject: [PATCH 083/118] feat(visuals): move graphUtils + spec (#204)

---
 packages/visuals/src/graphUtils.spec.ts | 112 ++++++++++++++++++++++++
 packages/visuals/src/graphUtils.ts      |  74 ++++++++++++++++
 packages/visuals/src/index.ts           |   1 +
 3 files changed, 187 insertions(+)
 create mode 100644 packages/visuals/src/graphUtils.spec.ts
 create mode 100644 packages/visuals/src/graphUtils.ts

diff --git a/packages/visuals/src/graphUtils.spec.ts b/packages/visuals/src/graphUtils.spec.ts
new file mode 100644
index 0000000..1df7d76
--- /dev/null
+++ b/packages/visuals/src/graphUtils.spec.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bareIdOf, equivalentIds, highlightExpand } from './graphUtils';
+import type { Graph } from '@turing-machine-js/machine';
+
+/**
+ * Tests for the pure breakpoint / highlight class helpers in
+ * `graphUtils.ts`. These rules feed both the breakpoint indicator
+ * (`applyIndicator`) and the context-menu "Shared with" info line
+ * (`MachineGraph.svelte`); the upstream engine v7 collapses wrapper
+ * states (`State.withOverriddenHaltState`) onto a shared `#debugRef`
+ * with their bare, so the demo collapses them into one breakpoint per
+ * equivalence class.
+ *
+ * Fixture: `turing-callable-subtree` has
+ *   3  → bare `walkToBlank` (frameId 3)
+ *   4  → `writeMarker` (override)
+ *   5  → wrapper `walkToBlank(writeMarker)` (bareStateId 3)
+ *   0  → halt singleton
+ *   -3 → halt marker for frame 3
+ */
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function loadGraph(name: string): Graph {
+  const path = resolve(__dirname, '../../tests/fixtures/graphs', `${name}.json`);
+  return JSON.parse(readFileSync(path, 'utf8')) as Graph;
+}
+
+describe('bareIdOf', () => {
+  const g = loadGraph('turing-callable-subtree');
+
+  it('maps a wrapper id to its bareStateId', () => {
+    expect(bareIdOf(5, g)).toBe(3);
+  });
+
+  it('returns the bare id unchanged for non-wrapper positive ids', () => {
+    expect(bareIdOf(3, g)).toBe(3);
+    expect(bareIdOf(4, g)).toBe(4);
+  });
+
+  it('collapses halt markers (negative ids) to the halt singleton (0)', () => {
+    expect(bareIdOf(-3, g)).toBe(0);
+  });
+
+  it('returns 0 for the halt singleton itself', () => {
+    expect(bareIdOf(0, g)).toBe(0);
+  });
+
+  it('returns the id unchanged when graph is null', () => {
+    expect(bareIdOf(5, null)).toBe(5);
+    expect(bareIdOf(-3, null)).toBe(-3);
+  });
+
+  it('returns the id unchanged when no node entry exists', () => {
+    expect(bareIdOf(999, g)).toBe(999);
+  });
+});
+
+describe('highlightExpand (asymmetric)', () => {
+  const g = loadGraph('turing-callable-subtree');
+
+  it('expands wrapper → [wrapper, bare]', () => {
+    expect(highlightExpand(5, g).sort()).toEqual([3, 5]);
+  });
+
+  it('does NOT expand bare → [bare] only (no wrapper sync from bare side)', () => {
+    expect(highlightExpand(3, g)).toEqual([3]);
+  });
+
+  it('returns [id] for a non-wrapper non-bare id', () => {
+    expect(highlightExpand(4, g)).toEqual([4]);
+  });
+
+  it('returns [id] when graph is null', () => {
+    expect(highlightExpand(5, null)).toEqual([5]);
+  });
+});
+
+describe('equivalentIds (symmetric class lookup)', () => {
+  const g = loadGraph('turing-callable-subtree');
+
+  it('returns [bare, ...wrappers] from a wrapper input', () => {
+    expect(equivalentIds(5, g).sort()).toEqual([3, 5]);
+  });
+
+  it('returns [bare, ...wrappers] from the bare input — symmetric', () => {
+    expect(equivalentIds(3, g).sort()).toEqual([3, 5]);
+  });
+
+  it('returns [singleton] for a stand-alone state', () => {
+    expect(equivalentIds(4, g)).toEqual([4]);
+  });
+
+  it('halt singleton (0) → [0, ...all halt markers]', () => {
+    const ids = equivalentIds(0, g).sort((a, b) => a - b);
+    expect(ids).toEqual([-3, 0]);
+  });
+
+  it('halt marker (-3) → same class as halt singleton (symmetric)', () => {
+    const ids = equivalentIds(-3, g).sort((a, b) => a - b);
+    expect(ids).toEqual([-3, 0]);
+  });
+
+  it('returns [id] when graph is null', () => {
+    expect(equivalentIds(5, null)).toEqual([5]);
+    expect(equivalentIds(0, null)).toEqual([0]);
+  });
+});
diff --git a/packages/visuals/src/graphUtils.ts b/packages/visuals/src/graphUtils.ts
new file mode 100644
index 0000000..85aef76
--- /dev/null
+++ b/packages/visuals/src/graphUtils.ts
@@ -0,0 +1,74 @@
+import type { Graph } from '@turing-machine-js/machine';
+
+/**
+ * Normalize an engine `GraphNode.id` to its canonical representative for
+ * breakpoint-class lookups (machines-demo#37). Wrappers produced by
+ * `State.withOverriddenHaltState` share `#debugRef` with their bare state
+ * engine-side (turing-machine-js v7 `State.ts`: `state.#debugRef =
+ * bare.#debugRef`), so they form a single breakpoint from the user's POV.
+ * This collapses any wrapper id to its bare's id; non-wrapper ids return
+ * self. Used so the demo can store ONE canonical id per equivalence class
+ * in its breakpoint set, and expand to all class members for indicator
+ * rendering — keeping the worker-side toggle count to one per class
+ * (multiple toggles on the shared ref would double-flip).
+ */
+export function bareIdOf(id: number, graph: Graph | null): number {
+  if (!graph) return id;
+  // Halt markers (negative ids, one per frame) are visualization sentinels;
+  // at runtime they all collapse to the haltState singleton (id 0). For
+  // breakpoint purposes they're a single class — setting BP on any
+  // halt-related node sets it on the global haltState.
+  if (id < 0) return 0;
+  const node = graph.nodes[id];
+  if (node && node.isWrapper && node.bareStateId !== null) {
+    return node.bareStateId;
+  }
+  return id;
+}
+
+/**
+ * Asymmetric expansion for the highlight effect (machines-demo#37).
+ * Wrapper → `[wrapper, bare]` (the wrapper-entry pause is visually joined
+ * to its bare, since the user thinks of them as one call site).
+ * Bare → `[bare]` only (when the engine is genuinely on the bare — e.g. a
+ * loop iter — the wrapper is not the "active" state and shouldn't get the
+ * strong highlight).
+ * Non-wrapper / non-bare ids return `[id]`.
+ */
+export function highlightExpand(id: number, graph: Graph | null): number[] {
+  if (!graph) return [id];
+  const node = graph.nodes[id];
+  if (node?.isWrapper && node.bareStateId !== null) {
+    return [id, node.bareStateId];
+  }
+  return [id];
+}
+
+/**
+ * All GraphNode ids in the same breakpoint equivalence class as `id`.
+ * Symmetric — gives consumers the full list of nodes that share an engine
+ * breakpoint, regardless of which class member is the input. Used by the
+ * context-menu's "Shared with" info line so the user can see at a glance
+ * which other nodes flip together.
+ *
+ * Halt class (canonical id 0): the halt singleton + every halt marker in
+ * the graph. Wrapper/bare class: the bare + every wrapper pointing at it.
+ * Singleton classes (regular states, idle sentinel proxies) return just
+ * the input id.
+ */
+export function equivalentIds(id: number, graph: Graph | null): number[] {
+  if (!graph) return [id];
+  const canonical = bareIdOf(id, graph);
+  if (canonical === 0) {
+    const ids: number[] = [0];
+    for (const node of Object.values(graph.nodes)) {
+      if (node.isHaltMarker) ids.push(node.id);
+    }
+    return ids;
+  }
+  const result = new Set<number>([canonical]);
+  for (const node of Object.values(graph.nodes)) {
+    if (node.isWrapper && node.bareStateId === canonical) result.add(node.id);
+  }
+  return [...result];
+}
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 1206e90..683d604 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -1,3 +1,4 @@
 // Public API — populated as modules are moved in Tasks 2–8.
 export type { NodeKey, HighlightClass, HighlightOps, IndicatorOps, RecordedOp } from './highlightOps';
 export { recordingOps } from './highlightOps';
+export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';

From 18794ad87aa4d9b2ce1597ada73b3ca6cde443c0 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:45:14 +0300
Subject: [PATCH 084/118] fix(visuals): point graphUtils spec at the new
 fixture path (#204)

---
 packages/visuals/src/graphUtils.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/visuals/src/graphUtils.spec.ts b/packages/visuals/src/graphUtils.spec.ts
index 1df7d76..86e57da 100644
--- a/packages/visuals/src/graphUtils.spec.ts
+++ b/packages/visuals/src/graphUtils.spec.ts
@@ -26,7 +26,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 function loadGraph(name: string): Graph {
-  const path = resolve(__dirname, '../../tests/fixtures/graphs', `${name}.json`);
+  const path = resolve(__dirname, './fixtures/graphs', `${name}.json`);
   return JSON.parse(readFileSync(path, 'utf8')) as Graph;
 }
 

From 5df907669a90cc711c328100856e44b30bd79d0d Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 14:48:15 +0300
Subject: [PATCH 085/118] feat(visuals): move graph fixture JSONs from
 machines-demo (#204)

---
 .../src/fixtures/graphs/post-walk-mark.json   | 108 ++++++++++++++++++
 .../graphs/turing-callable-subtree.json       | 108 ++++++++++++++++++
 .../graphs/turing-copy-two-tapes.json         |  87 ++++++++++++++
 .../src/fixtures/graphs/turing-replace-b.json |  72 ++++++++++++
 4 files changed, 375 insertions(+)
 create mode 100644 packages/visuals/src/fixtures/graphs/post-walk-mark.json
 create mode 100644 packages/visuals/src/fixtures/graphs/turing-callable-subtree.json
 create mode 100644 packages/visuals/src/fixtures/graphs/turing-copy-two-tapes.json
 create mode 100644 packages/visuals/src/fixtures/graphs/turing-replace-b.json

diff --git a/packages/visuals/src/fixtures/graphs/post-walk-mark.json b/packages/visuals/src/fixtures/graphs/post-walk-mark.json
new file mode 100644
index 0000000..8d5990c
--- /dev/null
+++ b/packages/visuals/src/fixtures/graphs/post-walk-mark.json
@@ -0,0 +1,108 @@
+{
+  "initialId": 6,
+  "alphabets": [
+    [
+      "␣",
+      "•"
+    ]
+  ],
+  "nodes": {
+    "0": {
+      "id": 0,
+      "name": "id:0",
+      "isHalt": true,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [],
+      "overriddenHaltStateId": null,
+      "tags": []
+    },
+    "6": {
+      "id": 6,
+      "name": "10",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [
+        {
+          "pattern": "'•'",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "S"
+            }
+          ],
+          "nextStateId": 7,
+          "id": "6.0"
+        },
+        {
+          "pattern": "B",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "S"
+            }
+          ],
+          "nextStateId": 8,
+          "id": "6.1"
+        }
+      ],
+      "overriddenHaltStateId": null,
+      "tags": [
+        "main"
+      ]
+    },
+    "7": {
+      "id": 7,
+      "name": "20",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [
+        {
+          "pattern": "*",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "R"
+            }
+          ],
+          "nextStateId": 6,
+          "id": "7.0"
+        }
+      ],
+      "overriddenHaltStateId": null,
+      "tags": []
+    },
+    "8": {
+      "id": 8,
+      "name": "30",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [
+        {
+          "pattern": "*",
+          "command": [
+            {
+              "symbol": "'•'",
+              "movement": "S"
+            }
+          ],
+          "nextStateId": 0,
+          "id": "8.0"
+        }
+      ],
+      "overriddenHaltStateId": null,
+      "tags": []
+    }
+  }
+}
diff --git a/packages/visuals/src/fixtures/graphs/turing-callable-subtree.json b/packages/visuals/src/fixtures/graphs/turing-callable-subtree.json
new file mode 100644
index 0000000..b2bba1f
--- /dev/null
+++ b/packages/visuals/src/fixtures/graphs/turing-callable-subtree.json
@@ -0,0 +1,108 @@
+{
+  "initialId": 5,
+  "alphabets": [
+    [
+      " ",
+      "a",
+      "b",
+      "*"
+    ]
+  ],
+  "nodes": {
+    "0": {
+      "id": 0,
+      "name": "id:0",
+      "isHalt": true,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [],
+      "overriddenHaltStateId": null,
+      "tags": []
+    },
+    "3": {
+      "id": 3,
+      "name": "walkToBlank",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": 3,
+      "transitions": [
+        {
+          "pattern": "B",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "S"
+            }
+          ],
+          "nextStateId": -3,
+          "id": "3.0"
+        },
+        {
+          "pattern": "*",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "R"
+            }
+          ],
+          "nextStateId": 3,
+          "id": "3.1"
+        }
+      ],
+      "overriddenHaltStateId": null,
+      "tags": []
+    },
+    "4": {
+      "id": 4,
+      "name": "writeMarker",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [
+        {
+          "pattern": "*",
+          "command": [
+            {
+              "symbol": "'*'",
+              "movement": "S"
+            }
+          ],
+          "nextStateId": 0,
+          "id": "4.0"
+        }
+      ],
+      "overriddenHaltStateId": null,
+      "tags": []
+    },
+    "5": {
+      "id": 5,
+      "name": "walkToBlank(writeMarker)",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": true,
+      "bareStateId": 3,
+      "frameId": null,
+      "transitions": [],
+      "overriddenHaltStateId": 4,
+      "tags": []
+    },
+    "-3": {
+      "id": -3,
+      "name": "halt",
+      "isHalt": true,
+      "isHaltMarker": true,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": 3,
+      "transitions": [],
+      "overriddenHaltStateId": null,
+      "tags": []
+    }
+  }
+}
diff --git a/packages/visuals/src/fixtures/graphs/turing-copy-two-tapes.json b/packages/visuals/src/fixtures/graphs/turing-copy-two-tapes.json
new file mode 100644
index 0000000..d7b8378
--- /dev/null
+++ b/packages/visuals/src/fixtures/graphs/turing-copy-two-tapes.json
@@ -0,0 +1,87 @@
+{
+  "initialId": 2,
+  "alphabets": [
+    [
+      "␣",
+      "a",
+      "b"
+    ],
+    [
+      "␣",
+      "a",
+      "b"
+    ]
+  ],
+  "nodes": {
+    "0": {
+      "id": 0,
+      "name": "id:0",
+      "isHalt": true,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [],
+      "overriddenHaltStateId": null,
+      "tags": []
+    },
+    "2": {
+      "id": 2,
+      "name": "id:2",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [
+        {
+          "pattern": "'a',*",
+          "command": [
+            {
+              "symbol": "'a'",
+              "movement": "R"
+            },
+            {
+              "symbol": "'a'",
+              "movement": "R"
+            }
+          ],
+          "nextStateId": 2,
+          "id": "2.0"
+        },
+        {
+          "pattern": "'b',*",
+          "command": [
+            {
+              "symbol": "'b'",
+              "movement": "R"
+            },
+            {
+              "symbol": "'b'",
+              "movement": "R"
+            }
+          ],
+          "nextStateId": 2,
+          "id": "2.1"
+        },
+        {
+          "pattern": "B,*",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "S"
+            },
+            {
+              "symbol": "K",
+              "movement": "S"
+            }
+          ],
+          "nextStateId": 0,
+          "id": "2.2"
+        }
+      ],
+      "overriddenHaltStateId": null,
+      "tags": []
+    }
+  }
+}
diff --git a/packages/visuals/src/fixtures/graphs/turing-replace-b.json b/packages/visuals/src/fixtures/graphs/turing-replace-b.json
new file mode 100644
index 0000000..6e9ea66
--- /dev/null
+++ b/packages/visuals/src/fixtures/graphs/turing-replace-b.json
@@ -0,0 +1,72 @@
+{
+  "initialId": 1,
+  "alphabets": [
+    [
+      "␣",
+      "a",
+      "b",
+      "c",
+      "*"
+    ]
+  ],
+  "nodes": {
+    "0": {
+      "id": 0,
+      "name": "id:0",
+      "isHalt": true,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [],
+      "overriddenHaltStateId": null,
+      "tags": []
+    },
+    "1": {
+      "id": 1,
+      "name": "id:1",
+      "isHalt": false,
+      "isHaltMarker": false,
+      "isWrapper": false,
+      "bareStateId": null,
+      "frameId": null,
+      "transitions": [
+        {
+          "pattern": "'b'",
+          "command": [
+            {
+              "symbol": "'*'",
+              "movement": "R"
+            }
+          ],
+          "nextStateId": 1,
+          "id": "1.0"
+        },
+        {
+          "pattern": "B",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "L"
+            }
+          ],
+          "nextStateId": 0,
+          "id": "1.1"
+        },
+        {
+          "pattern": "*",
+          "command": [
+            {
+              "symbol": "K",
+              "movement": "R"
+            }
+          ],
+          "nextStateId": 1,
+          "id": "1.2"
+        }
+      ],
+      "overriddenHaltStateId": null,
+      "tags": []
+    }
+  }
+}

From e32734dc46a198c7cac09146d391111d4565719f Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:01:01 +0300
Subject: [PATCH 086/118] feat(visuals): move graphIndexes (#204)

---
 packages/visuals/src/graphIndexes.ts | 84 ++++++++++++++++++++++++++++
 packages/visuals/src/index.ts        |  2 +
 2 files changed, 86 insertions(+)
 create mode 100644 packages/visuals/src/graphIndexes.ts

diff --git a/packages/visuals/src/graphIndexes.ts b/packages/visuals/src/graphIndexes.ts
new file mode 100644
index 0000000..eac58aa
--- /dev/null
+++ b/packages/visuals/src/graphIndexes.ts
@@ -0,0 +1,84 @@
+import type { Graph } from '@turing-machine-js/machine';
+
+/**
+ * Derived lookups over an engine `Graph` that the highlight + indicator
+ * passes need. Recomputed once per Build; consumed read-only thereafter.
+ *
+ * Pure transformation of `graph` — same input always produces deep-equal
+ * output. See `docs/graph-highlight-and-breakpoints.md` for how each
+ * field is consumed.
+ */
+export type GraphIndexes = {
+  /** `GraphNode.id` → containing callable-subtree frameId. Only nodes
+   *  with `frameId !== null` (i.e. in-frame states) are present. */
+  nodeFrameMap: Map<number, number>;
+
+  /** frameId → list of wrappers calling into that frame, each with the
+   *  wrapper's id and its override-target id. Used by both source and
+   *  destination return-chain passes. */
+  frameWrappersMap: Map<number, Array<{ wrapperId: number; overrideId: number | null }>>;
+
+  /** Cluster label text (as emitted by `toMermaid`) → frameId. The
+   *  rendered SVG's `g.cluster` carries the label inside a
+   *  `<foreignObject>`; consumers match by `label.textContent.trim()` to
+   *  build their own `clusterCache: Map<frameId, SVGElement>`. */
+  frameLabelToId: Map<string, number>;
+};
+
+/**
+ * Walk the engine graph once and build all derived lookups. Cheap;
+ * intended to run on every Build (graph identity changes per build).
+ */
+export function indexGraph(graph: Graph | null): GraphIndexes {
+  const nodeFrameMap = new Map<number, number>();
+  const frameWrappersMap = new Map<
+    number,
+    Array<{ wrapperId: number; overrideId: number | null }>
+  >();
+  const frameLabelToId = new Map<string, number>();
+
+  if (!graph) return { nodeFrameMap, frameWrappersMap, frameLabelToId };
+
+  for (const node of Object.values(graph.nodes)) {
+    if (node.frameId !== null) nodeFrameMap.set(node.id, node.frameId);
+  }
+
+  // For each wrapper, append to its bare's frame entry. Multiple wrappers
+  // can share the same bare with different overrides; we record them all
+  // so the return-chain passes can highlight every candidate.
+  for (const node of Object.values(graph.nodes)) {
+    if (!node.isWrapper || node.bareStateId === null) continue;
+    const bare = graph.nodes[node.bareStateId];
+    if (!bare || bare.frameId === null) continue;
+    const entry = { wrapperId: node.id, overrideId: node.overriddenHaltStateId };
+    const arr = frameWrappersMap.get(bare.frameId);
+    if (arr) arr.push(entry);
+    else frameWrappersMap.set(bare.frameId, [entry]);
+  }
+
+  // Cluster label reconstruction: mirrors the engine's `toMermaid` emit
+  // (`callable subtree of NAME` for single-bare frames, `callable scope:
+  // A ∪ B ∪ …` for union frames; bare names sorted by id). Consumers
+  // need this to map mermaid's rendered cluster (whose own SVG id is the
+  // useless literal `[object Object]`) back to a frameId.
+  const bareIds = new Set<number>();
+  for (const n of Object.values(graph.nodes)) {
+    if (n.isWrapper && n.bareStateId !== null) bareIds.add(n.bareStateId);
+  }
+  const frameToBareNames = new Map<number, string[]>();
+  for (const n of Object.values(graph.nodes).sort((a, b) => a.id - b.id)) {
+    if (n.isWrapper || n.isHaltMarker || n.frameId === null) continue;
+    if (!bareIds.has(n.id)) continue;
+    const arr = frameToBareNames.get(n.frameId) ?? [];
+    arr.push(n.name);
+    frameToBareNames.set(n.frameId, arr);
+  }
+  for (const [frameId, names] of frameToBareNames) {
+    const label = names.length > 1
+      ? `callable scope: ${names.join(' ∪ ')}`
+      : `callable subtree of ${names[0] ?? frameId}`;
+    frameLabelToId.set(label, frameId);
+  }
+
+  return { nodeFrameMap, frameWrappersMap, frameLabelToId };
+}
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 683d604..4feed3d 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -2,3 +2,5 @@
 export type { NodeKey, HighlightClass, HighlightOps, IndicatorOps, RecordedOp } from './highlightOps';
 export { recordingOps } from './highlightOps';
 export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
+export type { GraphIndexes } from './graphIndexes';
+export { indexGraph } from './graphIndexes';

From 9bd33f630354fea736ef676fe05310cc17de48ca Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:07:12 +0300
Subject: [PATCH 087/118] feat(visuals): move applyHighlight + applyIndicator +
 spec; extract GraphHighlight type (#204)

---
 packages/visuals/src/applyHighlight.spec.ts | 331 ++++++++++++++++++++
 packages/visuals/src/applyHighlight.ts      | 217 +++++++++++++
 packages/visuals/src/index.ts               |   2 +
 packages/visuals/src/types.ts               |  31 ++
 4 files changed, 581 insertions(+)
 create mode 100644 packages/visuals/src/applyHighlight.spec.ts
 create mode 100644 packages/visuals/src/applyHighlight.ts
 create mode 100644 packages/visuals/src/types.ts

diff --git a/packages/visuals/src/applyHighlight.spec.ts b/packages/visuals/src/applyHighlight.spec.ts
new file mode 100644
index 0000000..310515b
--- /dev/null
+++ b/packages/visuals/src/applyHighlight.spec.ts
@@ -0,0 +1,331 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyHighlight, applyIndicator } from './applyHighlight';
+import { indexGraph } from './graphIndexes';
+import { recordingOps, type RecordedOp } from './highlightOps';
+import type { GraphHighlight } from './types';
+import type { Graph } from '@turing-machine-js/machine';
+
+/**
+ * Rule tests for `applyHighlight`. Section numbers mirror
+ * `docs/graph-highlight-and-breakpoints.md` — any rule change must
+ * update both the doc and the matching `describe` block here.
+ *
+ * Fixtures come from `tests/fixtures/graphs/`, which are committed
+ * snapshots of `State.toGraph` output for each bundled example
+ * (regenerable via `REGEN_FIXTURES=1 npm test`). Using real engine output
+ * means these tests also catch any drift between engine emit and
+ * rule expectations.
+ *
+ * Helpful fixture ids for `turing-callable-subtree`:
+ *   bare walkToBlank             = 3   (frameId 3)
+ *   writeMarker (override)       = 4
+ *   wrapper walkToBlank(writeMarker) = 5  (bareStateId 3, overriddenHaltStateId 4)
+ *   halt singleton               = 0
+ *   frame halt marker            = -3  (id = -frameId)
+ */
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const FIXTURE_DIR = resolve(__dirname, './fixtures/graphs');
+
+function loadGraph(name: string): Graph {
+  return JSON.parse(readFileSync(resolve(FIXTURE_DIR, `${name}.json`), 'utf-8'));
+}
+
+/** Run `applyHighlight` with a recording ops impl, return the ordered ops list. */
+function run(highlight: GraphHighlight | null, graph: Graph, prev: number | 'idle' | null = null): {
+  ops: RecordedOp[];
+  next: number | 'idle' | null;
+} {
+  const indexes = indexGraph(graph);
+  const { highlight: opsImpl, record } = recordingOps();
+  const { nextPrevStrongId } = applyHighlight(highlight, graph, indexes, prev, opsImpl);
+  return { ops: record, next: nextPrevStrongId };
+}
+
+describe('applyHighlight', () => {
+  describe('null/empty highlight', () => {
+    it('returns no-op with nextPrev=null when highlight is null', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { ops, next } = run(null, g, 3);
+      expect(ops).toEqual([]);
+      expect(next).toBeNull();
+    });
+  });
+
+  describe('§5 halt-target retargeting', () => {
+    it('rewrites toId=0 to -frameId when fromId is in a frame', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // Bare walkToBlank (id 3, frameId 3) halts → engine reports toId=0,
+      // should retarget to -3 (frame halt marker).
+      const { ops } = run({ fromId: 3, toId: 0, strong: 'from', paused: false }, g);
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      // halt marker -3 gets highlight-to; halt singleton 0 does not.
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: -3, cls: 'mg-highlight-to' });
+      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-to' });
+    });
+
+    it('does NOT retarget when fromId is outside any frame', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // writeMarker (id 4) is the wrapper's override-target; sits outside
+      // the frame (frameId: null), so its halt→halt-singleton stays as id 0.
+      const { ops } = run({ fromId: 4, toId: 0, strong: 'from', paused: false }, g);
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-to' });
+    });
+  });
+
+  describe('§2 + §3 wrapper/bare equivalence (asymmetric)', () => {
+    it('wrapper-strong expands to [wrapper, bare] — both get highlight-to + strong', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // Wrapper-entry pause: idle → wrapper(5), pauseBefore strong=to.
+      const { ops } = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g);
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-strong' });
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-to' });
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-strong' });
+    });
+
+    it('bare-strong stays bare only — does NOT light up wrapper', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // Bare-loop pause: prev=bare(3), to=bare(3), pauseBefore strong=to.
+      const { ops } = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g);
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-to' });
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-strong' });
+      // Wrapper 5 gets NOTHING from the to-side expansion.
+      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
+      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-strong' });
+    });
+  });
+
+  describe('§6 source return chain (toId < 0)', () => {
+    it('lights up return arrow + wrapper + override edge + override target', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // Just-fired halt-bound transition: from=bare(3), to=halt-marker(-3),
+      // strong=from (pause-after-style).
+      const { ops } = run({ fromId: 3, toId: -3, strong: 'from', paused: true }, g);
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
+      // Return arrow w_3 → wrapper(5).
+      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 'w_3', toKey: 's5' });
+      // Wrapper gets highlight-to.
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
+      // Wrapper → override edge.
+      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's4' });
+      // Override (writeMarker) gets highlight-to.
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 4, cls: 'mg-highlight-to' });
+    });
+  });
+
+  describe('§7 destination return chain (paused at override after pop)', () => {
+    it('lights the full path bare → halt-marker → return → wrapper → override + frame', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // Paused-before writeMarker: prev=bare(3) (last yield was bare's halt),
+      // current=writeMarker(4). strong=to. Bare is in frame 3; wrapper 5's
+      // override is 4 → matches.
+      const { ops } = run({ fromId: 3, toId: 4, strong: 'to', paused: true }, g);
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
+      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
+
+      // Halt marker lit.
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: -3, cls: 'mg-highlight-to' });
+      // bare → halt-marker edge.
+      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's3', toKey: 'c3' });
+      // Return arrow.
+      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 'w_3', toKey: 's5' });
+      // Wrapper highlight-to.
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
+      // Wrapper → override edge.
+      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's4' });
+      // Frame active (override sits outside frame, but the chain fired so
+      // we still mark the frame to show "we came out of THIS subtree").
+      expect(frameOps).toContainEqual({ op: 'markFrameActive', frameId: 3 });
+    });
+
+    it('does NOT fire when fromId is not in any frame', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // From idle → writeMarker(4): no frame on the from side, no chain.
+      const { ops } = run({ fromId: 'idle', toId: 4, strong: 'to', paused: true }, g);
+      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
+      expect(edgeOps).not.toContainEqual({ op: 'highlightEdge', fromKey: 's3', toKey: 'c3' });
+      expect(edgeOps).not.toContainEqual({ op: 'highlightEdge', fromKey: 'w_3', toKey: 's5' });
+    });
+  });
+
+  describe('§8 halt singleton (toId === 0, no retarget)', () => {
+    it('marks the halt singleton with highlight-to + strong', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // writeMarker (id 4, no frame) → halt singleton (0). strong=from
+      // (pause-after applying writeMarker's command).
+      const { ops } = run({ fromId: 4, toId: 0, strong: 'from', paused: true }, g);
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-to' });
+      // strong is 'from', so halt singleton is not strong.
+      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-strong' });
+    });
+  });
+
+  describe('§9 frame-active', () => {
+    it('marks the frame when canonical strong is inside it (wrapper case)', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // Wrapper-entry pause: strong=wrapper(5). bareIdOf(5)=3. nodeFrameMap[3]=3.
+      const { ops } = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g);
+      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
+      expect(frameOps).toContainEqual({ op: 'markFrameActive', frameId: 3 });
+    });
+
+    it('marks the frame when bare is strong', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { ops } = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g);
+      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
+      expect(frameOps).toContainEqual({ op: 'markFrameActive', frameId: 3 });
+    });
+
+    it('does NOT mark a frame when strong is outside any frame', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // writeMarker (4, no frame) is strong.
+      const { ops } = run({ fromId: 4, toId: 0, strong: 'from', paused: true }, g);
+      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
+      expect(frameOps).toEqual([]);
+    });
+  });
+
+  describe('§10 wrapper-entry call edge', () => {
+    it('highlights the wrapper → bare call edge when to-side expanded to both', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { ops } = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g);
+      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
+      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's3' });
+    });
+
+    it('does NOT highlight a call edge when to-side is bare only', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { ops } = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g);
+      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
+      // No s5→s3 call edge (bare doesn't expand to include wrapper).
+      expect(edgeOps).not.toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's3' });
+    });
+  });
+
+  describe('§11 pause-revisit pulse (raw, not canonical)', () => {
+    it('does NOT pulse on wrapper-pause → bare-pause transition', () => {
+      const g = loadGraph('turing-callable-subtree');
+      // First pause: wrapper-entry. prev=null → no pulse. nextPrev=5 (wrapper).
+      const r1 = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g, null);
+      expect(r1.ops.find((o) => o.op === 'pulse')).toBeUndefined();
+      expect(r1.next).toBe(5);
+      // Second pause: bare loop iter. prev=5 (wrapper), strong=3 (bare).
+      // 5 !== 3 → NO pulse, even though they share #debugRef.
+      const r2 = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g, r1.next);
+      expect(r2.ops.find((o) => o.op === 'pulse')).toBeUndefined();
+      expect(r2.next).toBe(3);
+    });
+
+    it('pulses on same-state revisit (bare → bare)', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const r1 = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g, null);
+      expect(r1.ops.find((o) => o.op === 'pulse')).toBeUndefined();
+      const r2 = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g, r1.next);
+      expect(r2.ops).toContainEqual({ op: 'pulse', id: 3 });
+    });
+
+    it('does NOT update prev on non-paused (idle / RUNNING_AUTO) events', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const r = run({ fromId: 3, toId: 3, strong: 'from', paused: false }, g, 5);
+      expect(r.next).toBe(5); // unchanged
+    });
+
+    it('resets prev to null on null highlight', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const r = run(null, g, 3);
+      expect(r.next).toBeNull();
+    });
+  });
+
+  describe('scroll-into-view', () => {
+    it('scrolls to the strong node', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { ops } = run({ fromId: 3, toId: 4, strong: 'to', paused: true }, g);
+      expect(ops).toContainEqual({ op: 'scrollIntoView', id: 4 });
+    });
+
+    it('does not scroll when strong is null (no highlight)', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { ops } = run(null, g);
+      expect(ops.find((o) => o.op === 'scrollIntoView')).toBeUndefined();
+    });
+  });
+
+  describe('applyIndicator (§2 canonical breakpoint + §3 indicator class)', () => {
+    it('marks every member of the equivalence class when canonical id is in set', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { indicator, record } = recordingOps();
+      // BP set has the bare id (3). Both wrapper (5) and bare (3) should turn on.
+      applyIndicator(new Set([3]), g, [3, 4, 5, -3, 0, 'idle'], indicator);
+      const onIds = record
+        .filter((r): r is Extract<RecordedOp, { op: 'setBreakpoint' }> => r.op === 'setBreakpoint' && r.on)
+        .map((r) => r.id);
+      expect(onIds).toContain(3);
+      expect(onIds).toContain(5);
+      // writeMarker (4), halt-marker (-3), halt (0), idle: never on.
+      expect(onIds).not.toContain(4);
+      expect(onIds).not.toContain(-3);
+      expect(onIds).not.toContain(0);
+      expect(onIds).not.toContain('idle');
+    });
+
+    it('clears every node when the set is empty', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { indicator, record } = recordingOps();
+      applyIndicator(new Set(), g, [3, 4, 5, 'idle'], indicator);
+      const onCount = record.filter((r) => r.op === 'setBreakpoint' && r.on).length;
+      expect(onCount).toBe(0);
+      // Every node still gets an explicit off call (idempotent clears).
+      expect(record.length).toBe(4);
+    });
+
+    // machines-demo#37 — halt singleton (id 0) is a valid breakpoint
+    // target (engine-wide haltState). The set stores canonical id 0;
+    // both the halt singleton AND every halt marker (negative ids; one
+    // per frame) collapse to that class via `bareIdOf(-N, g) === 0`.
+    it('marks halt singleton AND every halt marker when 0 is in the set', () => {
+      const g = loadGraph('turing-callable-subtree');
+      const { indicator, record } = recordingOps();
+      applyIndicator(new Set([0]), g, [3, 4, 5, -3, 0, 'idle'], indicator);
+      const onIds = record
+        .filter((r): r is Extract<RecordedOp, { op: 'setBreakpoint' }> => r.op === 'setBreakpoint' && r.on)
+        .map((r) => r.id);
+      expect(onIds).toContain(0); // halt singleton
+      expect(onIds).toContain(-3); // halt marker for frame 3
+      // Regular and wrapper / bare nodes: never on.
+      expect(onIds).not.toContain(3);
+      expect(onIds).not.toContain(4);
+      expect(onIds).not.toContain(5);
+      expect(onIds).not.toContain('idle');
+    });
+  });
+
+  describe('regression: simple machines (no callable subtree)', () => {
+    it('lights from + to + strong + edge for a plain RUNNING_AUTO tick', () => {
+      const g = loadGraph('turing-replace-b');
+      // Pick any two ids that have a transition between them.
+      const nodes = Object.values(g.nodes).filter((n) => !n.isHalt && !n.isHaltMarker);
+      const src = nodes.find((n) => n.transitions.length > 0)!;
+      const transition = src.transitions[0];
+      const dst = transition.nextStateId;
+      const { ops } = run(
+        { fromId: src.id, toId: dst, strong: 'from', paused: false },
+        g,
+      );
+      const classOps = ops.filter((o) => o.op === 'addNodeClass');
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: src.id, cls: 'mg-highlight-from' });
+      expect(classOps).toContainEqual({ op: 'addNodeClass', id: src.id, cls: 'mg-highlight-strong' });
+    });
+  });
+});
diff --git a/packages/visuals/src/applyHighlight.ts b/packages/visuals/src/applyHighlight.ts
new file mode 100644
index 0000000..8643ea1
--- /dev/null
+++ b/packages/visuals/src/applyHighlight.ts
@@ -0,0 +1,217 @@
+import type { GraphHighlight } from './types';
+import type { Graph } from '@turing-machine-js/machine';
+import type { GraphIndexes } from './graphIndexes';
+import type { HighlightOps, IndicatorOps, NodeKey } from './highlightOps';
+import { bareIdOf, highlightExpand } from './graphUtils';
+
+/**
+ * Pure highlight-rule evaluator. Given the current `highlight` (from
+ * `MachineView`'s `$derived`), the engine `graph`, derived `indexes`,
+ * and the previous strong-id (for pause-revisit pulse detection), emit
+ * a sequence of `ops` calls describing the resulting visual state.
+ *
+ * Strictly additive — the caller is expected to clear previously-applied
+ * highlight classes / edge marks / cluster activations BEFORE invoking
+ * this function. The function never reads back from the consumer.
+ *
+ * Returns the new prev-strong-id to thread into the next call. Pulse
+ * comparison uses the RAW strong id (not canonical), so wrapper-pause
+ * and bare-pause register as different positions and don't pulse each
+ * other. Updates only when `highlight.paused === true`; non-paused
+ * events (idle / RUNNING_AUTO ticks) leave it untouched. Null highlight
+ * resets it to null.
+ *
+ * See `docs/graph-highlight-and-breakpoints.md` for the 16 rules
+ * enumerated.
+ */
+export function applyHighlight(
+  highlight: GraphHighlight | null,
+  graph: Graph | null,
+  indexes: GraphIndexes,
+  prevStrongId: NodeKey | null,
+  ops: HighlightOps,
+): { nextPrevStrongId: NodeKey | null } {
+  if (!highlight || !graph) {
+    return { nextPrevStrongId: null };
+  }
+
+  // §5 Halt-target retargeting: real halt (id 0) reached from an in-frame
+  // state retargets to the frame's halt marker (id = -frameId), so the
+  // visible edge lands inside the cluster.
+  let toId: number | null = highlight.toId;
+  if (toId === 0 && typeof highlight.fromId === 'number') {
+    const fromFrameId = indexes.nodeFrameMap.get(highlight.fromId);
+    if (fromFrameId !== undefined) toId = -fromFrameId;
+  }
+
+  // §2 Equivalence-class expansion (asymmetric, via highlightExpand):
+  //   wrapper → [wrapper, bare]  (joined visual pair for wrapper-entry pause)
+  //   bare    → [bare]           (engine genuinely on the bare; no wrapper sync)
+  // From-side expansion only fires for positive numeric ids; the 'idle'
+  // sentinel is handled directly below. Halt markers / singleton fall
+  // through the direct-lookup branches.
+  const fromEqIds = typeof highlight.fromId === 'number'
+    ? highlightExpand(highlight.fromId, graph)
+    : [];
+  const toEqIds = toId !== null && toId > 0
+    ? highlightExpand(toId, graph)
+    : [];
+
+  // §3 Class application — from side.
+  if (highlight.fromId === 'idle') {
+    ops.addNodeClass('idle', 'mg-highlight-from');
+    if (highlight.strong === 'from') ops.addNodeClass('idle', 'mg-highlight-strong');
+  }
+  for (const id of fromEqIds) {
+    ops.addNodeClass(id, 'mg-highlight-from');
+    if (highlight.strong === 'from') ops.addNodeClass(id, 'mg-highlight-strong');
+  }
+
+  // §3 + §8 Class application — to side. Halt markers (toId < 0) and the
+  // real halt singleton (toId === 0; only possible when §5 didn't retarget)
+  // bypass the equivalence-class expansion via direct lookup.
+  if (toId !== null && toId <= 0) {
+    ops.addNodeClass(toId, 'mg-highlight-to');
+    if (highlight.strong === 'to') ops.addNodeClass(toId, 'mg-highlight-strong');
+  }
+  for (const id of toEqIds) {
+    ops.addNodeClass(id, 'mg-highlight-to');
+    if (highlight.strong === 'to') ops.addNodeClass(id, 'mg-highlight-strong');
+  }
+
+  // Edge highlight: the data-id token form mermaid emits.
+  const fromKey = highlight.fromId === 'idle' ? 'idle' : `s${highlight.fromId}`;
+  const toKey =
+    toId === null ? null
+    : toId < 0 ? `c${-toId}`  // halt marker
+    : `s${toId}`;
+  if (toKey !== null) ops.highlightEdge(fromKey, toKey);
+
+  // §10 Wrapper-entry "call" edge: when to-side expanded to [wrapper, bare],
+  // light up the wrapper→bare connector so the joined pair has a visible link.
+  if (toEqIds.length > 1) {
+    const wrapperId = toEqIds.find((id) => graph.nodes[id]?.isWrapper);
+    const bareId = toEqIds.find((id) => !graph.nodes[id]?.isWrapper);
+    if (wrapperId !== undefined && bareId !== undefined) {
+      ops.highlightEdge(`s${wrapperId}`, `s${bareId}`);
+    }
+  }
+
+  // §6 Source return chain: just-fired transition landed on a frame's
+  // halt marker. Light up the post-pop trajectory before the next iter
+  // moves the strong node.
+  if (toId !== null && toId < 0) {
+    const frameId = -toId;
+    const wrappers = indexes.frameWrappersMap.get(frameId) ?? [];
+    for (const { wrapperId, overrideId } of wrappers) {
+      ops.highlightEdge(`w_${frameId}`, `s${wrapperId}`);
+      ops.addNodeClass(wrapperId, 'mg-highlight-to');
+      if (overrideId !== null) {
+        ops.highlightEdge(`s${wrapperId}`, `s${overrideId}`);
+        ops.addNodeClass(overrideId, 'mg-highlight-to');
+      }
+    }
+  }
+
+  // §7 Destination return chain: paused at a positive toId that's some
+  // wrapper W's override AND fromId is in W's frame — the engine just
+  // popped. The straight bare→override edge doesn't exist in the graph;
+  // light up the actual visible path bare → halt-marker → return →
+  // wrapper → override, plus the frame cluster.
+  if (typeof highlight.fromId === 'number' && toId !== null && toId > 0) {
+    const fromFrameId = indexes.nodeFrameMap.get(highlight.fromId);
+    if (fromFrameId !== undefined) {
+      const wrappers = indexes.frameWrappersMap.get(fromFrameId) ?? [];
+      const matching = wrappers.filter((w) => w.overrideId === toId);
+      if (matching.length > 0) {
+        ops.addNodeClass(-fromFrameId, 'mg-highlight-to');
+        ops.highlightEdge(`s${highlight.fromId}`, `c${fromFrameId}`);
+        for (const { wrapperId } of matching) {
+          ops.highlightEdge(`w_${fromFrameId}`, `s${wrapperId}`);
+          ops.addNodeClass(wrapperId, 'mg-highlight-to');
+          ops.highlightEdge(`s${wrapperId}`, `s${toId}`);
+        }
+        ops.markFrameActive(fromFrameId);
+      }
+    }
+  }
+
+  // §9 Frame-active for the strong node. Wrappers are outside any frame
+  // so canonicalize via bareIdOf so the wrapper-entry pause still lights
+  // up the bare's enclosing cluster.
+  const strongId = highlight.strong === 'from' ? highlight.fromId : highlight.toId;
+  const strongIdCanonical = typeof strongId === 'number'
+    ? bareIdOf(strongId, graph)
+    : strongId;
+  if (typeof strongIdCanonical === 'number') {
+    const frameId = indexes.nodeFrameMap.get(strongIdCanonical);
+    if (frameId !== undefined) ops.markFrameActive(frameId);
+  }
+
+  // §11 Pulse on same-state revisit. Uses RAW strongId — wrapper-pause
+  // and bare-pause are visually distinct positions even though they
+  // share #debugRef; pausing at wrapper then continuing into bare must
+  // not pulse. Idles never pulse and never update prevStrongId.
+  if (
+    highlight.paused
+    && strongId !== null
+    && strongId === prevStrongId
+    && strongId !== undefined
+  ) {
+    ops.pulse(strongId);
+  }
+
+  // Scroll-into-view target: for wrapper-entry pauses, scroll to the
+  // BARE (not the wrapper) so the focus matches the displayed state
+  // name. The worker's `resolveDisplayName` returns the bare's name
+  // for wrapper iters (so the log reads "paused at walkToBlank ..."),
+  // but `toId` is the wrapper's id and `highlightExpand` lights up
+  // both nodes as strong. Without this canonicalization the scroll
+  // lands on the wrapper while the log line and user's mental focus
+  // are on the bare. Halt-related ids (≤ 0) are scrolled to as-is —
+  // `bareIdOf` would collapse them all to the halt singleton, which
+  // is structurally separate from the in-frame halt marker the user
+  // is paused near.
+  if (strongId !== null) {
+    let scrollTarget: NodeKey = strongId;
+    if (typeof strongId === 'number' && strongId > 0) {
+      const node = graph.nodes[strongId];
+      if (node?.isWrapper && node.bareStateId !== null) {
+        scrollTarget = node.bareStateId;
+      }
+    }
+    ops.scrollIntoView(scrollTarget);
+  }
+
+  const nextPrevStrongId = highlight.paused ? strongId : prevStrongId;
+  return { nextPrevStrongId };
+}
+
+/**
+ * Pure breakpoint-indicator rule evaluator. For each cached node key,
+ * emit `ops.setBreakpoint(key, on)` reflecting whether the node's
+ * canonical bare-id is in the `breakpoints` set.
+ *
+ * The 'idle' string sentinel never carries a breakpoint. All numeric
+ * keys are valid BP-class members:
+ *   - positive id   → regular state; canonical via bareIdOf (wrappers
+ *                     collapse to bare)
+ *   - 0             → haltState singleton (engine-wide; canonical = 0)
+ *   - negative id   → halt marker (per-frame visualization sentinel;
+ *                     bareIdOf maps to 0 — same class as the singleton)
+ * Consumers pass their iterable of cached node keys (e.g. `nodeCache.keys()`).
+ */
+export function applyIndicator(
+  breakpoints: ReadonlySet<number>,
+  graph: Graph | null,
+  nodeIds: Iterable<NodeKey>,
+  ops: IndicatorOps,
+): void {
+  for (const key of nodeIds) {
+    const on =
+      typeof key === 'number'
+      && graph !== null
+      && breakpoints.has(bareIdOf(key, graph));
+    ops.setBreakpoint(key, on);
+  }
+}
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 4feed3d..c6435ec 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -4,3 +4,5 @@ export { recordingOps } from './highlightOps';
 export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
 export type { GraphIndexes } from './graphIndexes';
 export { indexGraph } from './graphIndexes';
+export type { GraphHighlight } from './types';
+export { applyHighlight, applyIndicator } from './applyHighlight';
diff --git a/packages/visuals/src/types.ts b/packages/visuals/src/types.ts
new file mode 100644
index 0000000..248b15f
--- /dev/null
+++ b/packages/visuals/src/types.ts
@@ -0,0 +1,31 @@
+/**
+ * State-graph highlight descriptor (machines-demo#10). MachineView derives it
+ * from `executionMode` + the latest pause-response data; MachineGraph reads
+ * it to light up the `from → edge → to` triple in the rendered SVG.
+ *
+ * - `fromId: 'idle'` represents the synthetic `idle([idle])` sentinel that
+ *   `toMermaid` emits at the entry point. Used in IDLE mode to mark "where
+ *   execution would start".
+ * - `fromId: number` is an engine `GraphNode.id` — the source state.
+ * - `toId: number | null` is the destination state's id (or `null` at halt).
+ * - `strong` selects which end of the triple gets the bolder/stronger
+ *   accent. Per the (B) rule: `from` strong at `before` pause; `to` strong
+ *   at `after` / iter-end pause / IDLE (destination feels current).
+ */
+export type GraphHighlight = {
+  fromId: number | 'idle';
+  toId: number | null;
+  strong: 'from' | 'to';
+  /**
+   * True when this highlight reflects a paused-event apply (RUNNING_PAUSED),
+   * false for per-iter idle applies (RUNNING_AUTO). MachineGraph uses this
+   * to detect cross-pause same-state revisits — pulsing the strong node when
+   * the current paused apply lands on the same state as the previous paused
+   * apply, even when intermediate idle applies pointed elsewhere
+   * (e.g., stateA breakpoint → continue → run through stateB/C → stateA
+   * breakpoint fires again). The simpler "previous apply's strong matches"
+   * check already covers AUTO self-loops; this flag drives the second pulse
+   * trigger.
+   */
+  paused: boolean;
+};

From 985243162f00fbba9a8cf63d904c8ebfd9485b2c Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:12:13 +0300
Subject: [PATCH 088/118] docs(visuals): move highlight + breakpoints rules doc
 (#204)

---
 .../docs/graph-highlight-and-breakpoints.md   | 272 ++++++++++++++++++
 1 file changed, 272 insertions(+)
 create mode 100644 packages/visuals/docs/graph-highlight-and-breakpoints.md

diff --git a/packages/visuals/docs/graph-highlight-and-breakpoints.md b/packages/visuals/docs/graph-highlight-and-breakpoints.md
new file mode 100644
index 0000000..6c0fcdf
--- /dev/null
+++ b/packages/visuals/docs/graph-highlight-and-breakpoints.md
@@ -0,0 +1,272 @@
+# Graph highlight and breakpoint rules
+
+> Canonical reference for every CSS class the demo applies to the rendered state-graph SVG, when each class fires, and how the breakpoint engine-side / UI-side state stays consistent. Companion to [`execution-model.md`](./execution-model.md) (modes + transitions) and [`machine-graph-palette.md`](./machine-graph-palette.md) (color tokens). Source files: `src/components/MachineGraph.svelte` (the apply-highlight + cache-build + indicator effects), `src/components/MachineView.svelte` (derives `graphHighlight`, owns the `breakpoints` set), `src/lib/machineWorker.ts` (`onPauseFn` + `toggleBreakpoint`), `src/lib/graphUtils.ts` (canonicalization helpers).
+
+## 1. Node-id conventions
+
+The engine's `Graph.nodes` keys are positive integer ids assigned at graph-build time. The demo also recognizes three synthetic ids:
+
+| Id range | Kind | Where it comes from | Click target? |
+|---|---|---|---|
+| `> 0` | Regular state, wrapper, or bare | `State.toGraph` walks reachable States | yes |
+| `0` | Halt singleton (`haltState`) | Engine sentinel, process-wide | no — global, not per-machine |
+| `< 0` | Halt marker (`isHaltMarker: true`, id = `-frameId`) | `toGraph` rewrites in-frame halts so they land inside the subgraph cluster instead of the global singleton | no — collapses to `haltState` at runtime |
+| `'idle'` | Synthetic entry sentinel | `toGraph` always emits a stadium-shape `idle` node with `idle -. enter .-> sN` | no |
+
+Click handlers are attached only to nodes whose key is `typeof === 'number' && > 0` — see `MachineGraph.svelte`'s cache-build `$effect`.
+
+## 2. Wrapper / bare equivalence
+
+A `State.withOverriddenHaltState(continuation)` produces a *wrapper* State that shares its `#debugRef` cell with the bare engine-side (`State.ts:391`: `state.#debugRef = bare.#debugRef`). Setting `wrapper.debug.before = true` and `bare.debug.before = true` mutate the SAME cell.
+
+The demo collapses this into a single breakpoint *equivalence class*:
+
+- The **canonical id** for a class is the bare's id. `bareIdOf(id, graph)` returns the bare id for a wrapper, self otherwise.
+- The `breakpoints: SvelteMap<number, { before: boolean; after: boolean }>` (in `MachineView`) holds canonical bare ids → per-kind state. Entries with both kinds off are pruned. `breakpointIndicatorSet` is the `$derived` set of "any kind set" canonical ids, passed to the indicator effect.
+- The **indicator effect** (in `MachineGraph`) renders the `mg-breakpoint` mark on every class member (bare + every wrapper sharing that bare via `bareStateId`): for each cached node, it normalizes the node's id via `bareIdOf` and checks the indicator set. The set is kind-agnostic — the future per-kind dots (Layer N) will use the Map directly.
+- The **highlight effect** uses an **asymmetric** expansion via `highlightExpand`:
+
+  | Source side | Returns | Why |
+  |---|---|---|
+  | Wrapper | `[wrapper, bare]` | wrapper-entry pause is the visually joined pair — light up both |
+  | Bare | `[bare]` only | when the engine is genuinely on the bare (loop iter), the wrapper isn't active |
+  | Regular state | `[self]` | no class membership |
+
+This means right-clicking a wrapper or a bare opens the menu over the same engine breakpoint class, both nodes show the indicator, but the strong-highlight only "leaks" wrapper → bare, never bare → wrappers.
+
+**Halt class.** The halt singleton (`id 0`) and every halt marker (`id < 0`, one per frame; see §1) form an additional equivalence class — they all collapse to the engine-wide `haltState` at runtime. `bareIdOf` maps any negative id to `0`; `equivalentIds(0, g)` returns `[0, ...all halt markers]`. The breakpoint Map stores canonical `0`; the indicator therefore lights up the singleton AND every halt marker simultaneously. `MachineView`'s `onToggleBreakpoint` also normalizes negative ids to `0` before forwarding to the worker, so the worker (which only has `id 0` in `collectStates`) sees a single canonical toggle regardless of which halt-class node the user right-clicked.
+
+**Class membership in the menu.** The context menu (§12) shows a "Shared with: …" info line listing other class members' names — so the user can see at a glance that flipping the BP also flips the sibling. For the halt class it instead shows "Global — affects all halts in the runtime", since `haltState` is a process-wide singleton rather than a per-graph state. Singleton classes (regular states, no wrappers / no sharing) omit the info line.
+
+## 3. CSS classes applied to SVG elements
+
+All classes are added imperatively by the apply-highlight or indicator `$effect`s in `MachineGraph.svelte`. Styling lives in the same component's `<style>` block; tokens in `app.css`.
+
+| Class | Target | When | Cleared by |
+|---|---|---|---|
+| `mg-breakpoint` | `g.node` | Set on every member of an equivalence class whose canonical id is in `breakpoints` | Indicator effect re-runs on `breakpoints` change |
+| `mg-highlight-from` | `g.node` (+ `'idle'` sentinel) | Source side of the just-fired or about-to-fire transition | Cleared at the top of every apply-highlight run |
+| `mg-highlight-to` | `g.node` | Destination side of same | Same |
+| `mg-highlight-strong` | `g.node` | The "focal" node of the highlight triple (set on the side matching `h.strong`, plus any class member via `highlightExpand` if source is wrapper) | Same |
+| `mg-highlight-edge` | `path` + `g.label` of edge | The edge connecting from→to in graph data-id space (`L_${from}_${to}_*`); also wrapper→bare "call" edge when `toEqIds` expanded the pair | Same |
+| `mg-frame-active` | `g.cluster` of a callable-subtree subgraph | The strong node (via canonical id) lives inside the frame — or the destination return chain detected a post-pop arrival from that frame | Same |
+| `mg-hl-arrow-shape` | inside cloned `<marker>` | Materialized once per render at cache-build time; switched in via `marker-end` swap on highlighted paths (browsers without `context-stroke`) | Marker swap reverts via `data-mg-orig-marker-end` on clear |
+
+## 4. `graphHighlight` shape (the input to the effect)
+
+Derived in `MachineView.svelte` from `(executionMode, currentStateId, nextStateId, prevStateId, pauseBefore, graph)`:
+
+```ts
+type GraphHighlight = {
+  fromId: number | 'idle';   // source-side node
+  toId: number | null;       // destination-side node; null = no destination
+  strong: 'from' | 'to' | null;
+  paused: boolean;           // true → eligible for pulse + revisit logic
+};
+```
+
+| Mode | `fromId` | `toId` | `strong` | `paused` |
+|---|---|---|---|---|
+| `RUNNING_AUTO` | `currentStateId` | `nextStateId` | `'from'` | `false` |
+| `RUNNING_PAUSED`, `pauseBefore = true` (debug.before fired) | `prevStateId ?? 'idle'` | `currentStateId` | `'to'` | `true` |
+| `RUNNING_PAUSED`, `pauseBefore = false` (Step / pause-after / click-pause) | `currentStateId` | `nextStateId` | `'from'` | `true` |
+| Anything else | `null` (no highlight) |
+
+`currentStateId` / `nextStateId` come from the worker's `paused` / `idle` / `stepped` responses (worker uses `m.state.id` for current, `nextStateIdFromYield` for next).
+
+## 5. Halt-target retargeting
+
+`toGraph` rewrites halt-bound transitions of in-frame states so they land on the **frame's halt marker** (id `= -frameId`), not the real `haltState` (id `0`). The engine's runtime, however, reports `nextState.id === 0` for any halt. The apply-highlight effect bridges:
+
+```
+if toId === 0 AND fromId is in some frame F → toId := -F
+```
+
+This makes the visible edge (`L_sX_cF_*`) the one that lights up. If `fromId` isn't in any frame (e.g. `writeMarker → halt` in the callable-subtree example), `toId` stays `0` and falls into the halt-singleton branch (§7).
+
+## 6. Source return chain (engine just halted into a frame)
+
+Fires when `toId < 0` (an in-frame halt marker). The engine will pop the stack and resume at the wrapper's override. To visualize the post-pop trajectory **before** the next iter relocates the strong node:
+
+- Highlight the return arrow `L_w_${F}_s${wrapperId}` (dotted).
+- Mark each wrapper of frame F with `mg-highlight-to`.
+- Highlight each wrapper's call-target-replacement edge `L_s${wrapperId}_s${overrideId}` and the override node.
+
+When multiple wrappers share the bare, the demo highlights all of them — the engine's runtime choice depends on stack state, which the demo doesn't track.
+
+## 7. Destination return chain (engine just resumed at an override-target)
+
+Mirror of §6, fires when `toId > 0` AND `fromId` is in some frame F AND any wrapper of F has `overriddenHaltStateId === toId`. The engine *just popped* and is paused/running at the override. The straight `bare → override` edge doesn't exist in the graph — light up the actual visible path:
+
+- bare (`fromId`, gets `mg-highlight-from` from the standard pass)
+- bare → halt-marker edge `L_s${fromId}_c${F}`
+- halt-marker `c${F}` with `mg-highlight-to`
+- return arrow `L_w_${F}_s${wrapperId}` (dotted)
+- wrapper with `mg-highlight-to`
+- wrapper → override edge `L_s${wrapperId}_s${toId}`
+- override (= `toId`, gets `mg-highlight-to` + strong from standard pass)
+- frame F's cluster gets `mg-frame-active` (strong node lives outside the frame, so the frame-highlight pass otherwise wouldn't fire)
+
+## 8. Halt singleton (`toId === 0` with no retarget)
+
+If §5's retarget didn't fire (because `fromId` isn't in a frame), `toId` stays `0`. The halt-singleton node is then highlighted via a direct lookup `nodeCache.get(0)` instead of the normal `highlightExpand` path (which skips `id <= 0`). Without this branch the leading edge would light up while the singleton stays grey — visually orphaned.
+
+## 9. Frame-active rule
+
+`mg-frame-active` lights the cluster border of a callable-subtree subgraph. Fires when **either**:
+
+- the strong node's canonical id (`bareIdOf(strongId)`) lives inside the frame (`nodeFrameMap.get`), OR
+- the destination return chain (§7) detected a post-pop arrival from that frame.
+
+The first case handles "we're executing inside the subroutine"; the second handles "we just left the subroutine but the return-chain is still visualized."
+
+## 10. Wrapper-entry call-edge highlight
+
+When the to-side expansion via `highlightExpand` produced `[wrapper, bare]` (length 2), the connector between them is the wrapper→bare **call edge** `L_s${wrapperId}_s${bareId}`. The standard `highlightEdgeByDataId(fromKey, toKey)` call uses `toKey = s${wrapper}` so it wouldn't pick up this edge. An explicit follow-up call highlights it so the joined visual pair has a visible connector.
+
+## 11. Pause-revisit pulse
+
+A short opacity pulse fires on the strong element when the current paused event lands on the same state as the **immediately previous** paused event. Implementation:
+
+- `lastPausedStrongId: number | 'idle' | null` stored at module scope.
+- After applying highlight, if `h.paused && strongId === lastPausedStrongId`, call `strongEl.animate(...)`.
+- If `h.paused`, write `strongId` to `lastPausedStrongId`.
+
+**Important: use the raw `strongId`, NOT the canonical bare-id.** Wrapper-pause and bare-pause are visually distinct events even though they share `#debugRef`; pausing at the wrapper then continuing into the bare must NOT pulse (the engine moved between two different nodes). The frame-highlight pass uses the canonical for its lookup, but the pulse comparison uses the raw id.
+
+Idle events (`h.paused === false`) never update `lastPausedStrongId`, so an `idle` that happens to report the same state doesn't poison the next paused-event comparison.
+
+## 12. Right-click handling + listener lifecycle
+
+The cache-build `$effect` walks the rendered SVG and attaches a `contextmenu` listener to every `g.node` whose key is a number (positive state, halt singleton `0`, or negative halt marker — only the synthetic `'idle'` string sentinel is skipped). Left-click stays native (text selection, focus, scroll-tap) — only right-click opens the BP menu, matching IDE convention. Halt nodes participate so the user can set / clear the global haltState breakpoint from any halt-class node (see §2's halt-class paragraph); the per-kind menu items dispatch through `MachineView.onToggleBreakpoint`, which canonicalizes negative ids → `0` before the runner sees them. Because mermaid's `lastSource` cache can skip a re-render when the source is byte-identical (so the SAME DOM persists across builds), the effect must NOT just re-attach — that stacks listeners and a single right-click would trigger N menu opens.
+
+Pattern:
+
+1. Module-scope `clickListenersController: AbortController | null = null`.
+2. At the top of each cache-build pass: `clickListenersController?.abort()` (removes ALL listeners attached with that signal), then `new AbortController()`.
+3. Pass `{ signal }` to every `addEventListener`.
+4. Component unmount aborts in `onMount`'s cleanup.
+
+The right-click handler `preventDefault`s the native context menu, then sets `menuStateId`, `menuX`, `menuY` to render a custom menu at the cursor.
+
+### Menu state + lifecycle
+
+The menu is two `<button role="menuitem">` items inside a `<div role="menu">`, positioned `fixed` at clamped viewport coordinates. Items show `☑`/`☐` based on the current `before` / `after` bits in `breakpointKinds.get(bareIdOf(stateId))`. Picking an item calls `runner.toggleBreakpoint(stateId, kind)` and closes the menu. The worker echoes `breakpointToggled` with the same `kind`, which updates the `breakpoints` Map via `runner.onBreakpointToggled`.
+
+Closing happens via:
+- Picking a menu item (fires `onclick`, then `closeMenu`).
+- ESC keydown (global handler installed while menu open).
+- Outside `mousedown` (global handler; `mousedown` not `click` so item picks land first).
+
+A separate `AbortController` (`menuOutsideController`) gates the global handlers so they detach cleanly when the menu closes or the component unmounts.
+
+### Edge-clamped positioning
+
+After the menu mounts, a `$effect` measures `menuEl.getBoundingClientRect()` and shifts the position so the menu fits in the viewport (8px margin from each edge). The raw `menuX/menuY` are the right-click coordinates; the clamped `menuClampedX/menuClampedY` are what feed the inline `left`/`top` style. Re-runs when the raw coords change (subsequent right-click on a different node).
+
+## 13. Breakpoint replay across builds
+
+Building a new worker creates fresh State instances — any `debug.before`/`debug.after` set on the previous instances is gone. The `breakpoints` Map in `MachineView` is **user intent**, not run state, and survives:
+
+```ts
+async function reloadWorker(source = code) {
+  // ... await runner.build(source) ...
+  // Prune ids that don't exist in the new graph (user edited code).
+  for (const id of [...breakpoints.keys()]) {
+    if (!res.graph.nodes[id]) breakpoints.delete(id);
+  }
+  // Replay surviving kinds via toggleBreakpoint. Fresh States have no
+  // debug set, so each toggle flips off→on. One call per stored kind per
+  // class — the canonical-id keying prevents double-flips of the shared
+  // #debugRef.
+  for (const [id, kinds] of breakpoints) {
+    if (kinds.before) runner.toggleBreakpoint(id, 'before');
+    if (kinds.after) runner.toggleBreakpoint(id, 'after');
+  }
+}
+```
+
+On build **failure** the Map IS cleared — there's no graph to prune against.
+
+The runner's echo `onBreakpointToggled` normalizes the echoed `stateId` via `bareIdOf(graph)` and updates only the matching `kind` bit, so the Map always holds canonical ids regardless of which class member the user actually right-clicked.
+
+## 13a. After-fire + Step: synthetic-pause suppression
+
+The engine's `onIter` fires at end-of-iter — functionally the same execution point as an `onPause(after, K)` fire (both happen after the iter's transition has executed and `onStep` has run). When a user clicks Step from inside an after-fire BP pause, the worker's `onIterFn` would otherwise dispatch a SECOND synthetic pause at the same effective point, producing a duplicate log entry.
+
+Suppression: `onPauseFn` sets `dispatchedAfterThisIter = true` whenever the engine pause is after-side (`m.pause?.side === 'after'`). `onIterFn` reads the flag (and resets it) at iter boundary; when set AND `stepRequested` is true, it skips the synthetic dispatch **but keeps `stepRequested`** so the NEXT iter's `onIter` pauses naturally. Net effect: Step from an after-fire BP advances one iter (the right semantic for "next pause point"), instead of bouncing twice at the same point.
+
+`before`-fires don't set the flag — they fire mid-iter, distinct from end-of-iter, so the synthetic at end-of-iter is a genuinely different pause point and isn't suppressed.
+
+## 14. Worker-side wrapper handling (`onPauseFn`)
+
+The engine fires `onPause` on BOTH the wrapper entry (iter K) and the immediately following bare entry (iter K+1) when the shared `#debugRef.before === true`. The worker pauses at the wrapper (the user-facing call site) and suppresses ONE following bare entry via `pendingJoinedBareId: number | null`:
+
+```
+1. onPause(wrapper):  if node.isWrapper && node.bareStateId !== null:
+                        pendingJoinedBareId := bareStateId; dispatchPause
+2. onPause(bare):     if state.id === pendingJoinedBareId:
+                        clear flag; skip dispatch
+3. onPause(bare K+2): pendingJoinedBareId === null; dispatch normally
+```
+
+Subsequent bare→bare loop iters pause normally — that's a real iteration, not a joined entry.
+
+Also: when pausing at a wrapper, the worker swaps the dispatched `state` field to the bare's `name` (looked up via `currentGraph.nodes[bareStateId].name`). The log reads `paused at state walkToBlank ...` instead of `paused at state walkToBlank(writeMarker) ...` — the composite is engine implementation.
+
+`currentGraph` is the engine-v7 `Graph` snapshot captured at build time and retained worker-side specifically so `onPauseFn` can ask `isWrapper?` and look up names. Cleared in `reset()`.
+
+## 15. Post-machine differences
+
+`@post-machine-js/machine` installs an `Object.defineProperty` lockdown on every non-halt PostMachine-constructed State's `debug` property that funnels DIRECT writes through Post's registry (`pm.setBreakpoint` for un-shared, throw for shared). `haltState` is NOT locked — direct `turing.haltState.debug = boolean` writes go straight to the engine setter (post dropped the module-load halt lockdown alongside engine #207). Post wraps `run`'s `onPause` to filter via that registry — pauses fire only when the registered breakpoint matches.
+
+**Direct mutation of the engine's `DebugConfig` (e.g. `state.debug.before = true`) bypasses Post's lockdown** because the getter passes through; Post's wrapper then filters the engine's onPause out entirely. The worker's `toggleBreakpoint` therefore uses the SETTER form, reading both kinds and writing the merged shape so toggling one doesn't lose the other:
+
+```ts
+const debug = entry.state.debug;
+const currentBefore = debug.before === true;
+const currentAfter = debug.after === true;
+const newBefore = req.kind === 'before' ? !currentBefore : currentBefore;
+const newAfter = req.kind === 'after' ? !currentAfter : currentAfter;
+entry.state.debug = null;  // clear first — see below
+if (newBefore || newAfter) {
+  entry.state.debug = {
+    ...(newBefore ? { before: true } : {}),
+    ...(newAfter ? { after: true } : {}),
+  };
+}
+```
+
+The intermediate `state.debug = null` is **required for Post**: Post's lockdown's setter PUSHES onto the `#breakpoints` array rather than replacing, so without the clear, repeated toggles accumulate stale entries. Turing's setter just creates a fresh DebugConfig either way — the null assignment is a no-op for Turing but essential for Post.
+
+- Turing: setter creates/clears the engine's `DebugConfig` normally.
+- Post: setter is intercepted, routed to `pm.setBreakpoint(path, filter)` or `pm.clearBreakpoint(path)` — registry updated, lockdown's internal write via `withLockdownEscape` then updates the engine ref.
+
+Branchless form works for both engines.
+
+## 16. Quick rules summary
+
+A condensed cheat-sheet for the apply-highlight effect's decisions:
+
+```
+expand from-side via highlightExpand(fromId)            # asymmetric: wrapper → [wrapper, bare]
+expand to-side via highlightExpand(toId) if toId > 0    # bare stays alone
+
+mark fromEqIds as highlight-from (+ strong if h.strong === 'from')
+mark toEqIds as highlight-to    (+ strong if h.strong === 'to')
+
+mark halt-marker  (toId < 0) directly with highlight-to (+ strong if matching)
+mark halt-singleton (toId === 0) directly with highlight-to (+ strong if matching)
+
+highlight edge L_{fromKey}_{toKey}
+if toEqIds had wrapper+bare: also highlight L_s{wrapper}_s{bare}  (call edge)
+
+if toId < 0:    source return chain    (halt-marker entry → wrappers → overrides)
+if toId > 0 AND fromFrame matches some wrapper.overrideId:
+                destination return chain  (bare → halt-marker → wrapper → override; frame active)
+
+mark frame active for canonical(strongId)
+
+if h.paused AND strongId === lastPausedStrongId: pulse strongEl
+if h.paused: lastPausedStrongId := strongId           # raw, not canonical
+```

From abfd8b36c9218f266095a7cbf128ffb5f19ac627 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:13:23 +0300
Subject: [PATCH 089/118] docs(visuals): add CHANGELOG with extraction entry
 (#204)

---
 packages/visuals/CHANGELOG.md | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 packages/visuals/CHANGELOG.md

diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
new file mode 100644
index 0000000..24963eb
--- /dev/null
+++ b/packages/visuals/CHANGELOG.md
@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this package 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).
+
+## [Unreleased]
+
+### Added
+
+- Initial extraction from machines-demo: `HighlightOps` / `IndicatorOps` / `RecordedOp` / `NodeKey` / `HighlightClass` / `GraphIndexes` / `GraphHighlight` types, `indexGraph`, `applyHighlight`, `applyIndicator`, `bareIdOf`, `highlightExpand`, `equivalentIds`, `recordingOps`. Rules doc moved into `docs/graph-highlight-and-breakpoints.md`. Closes [#204](https://github.com/mellonis/turing-machine-js/issues/204) (extraction step; recordSnippet follows in a separate PR).

From c942b975425a6f8fd162f626f306225d9e3baea0 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:45:05 +0300
Subject: [PATCH 090/118] feat(visuals): add Snippet/Frame/TapeSnapshot types +
 format primitives (#204)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

formatCommand takes TapeCommand (not Command) — Command wraps an array of
TapeCommands; per-cell encoding only makes sense on the individual TapeCommand.
Handles keep (symbolCommands.keep → K), erase (symbolCommands.erase → E),
and literal strings. Uses Map<symbol,string> for movement lookup.
---
 packages/visuals/src/format.spec.ts | 100 ++++++++++++++++++++++++++++
 packages/visuals/src/format.ts      |  51 ++++++++++++++
 packages/visuals/src/index.ts       |   5 +-
 packages/visuals/src/types.ts       |  45 +++++++++++++
 4 files changed, 199 insertions(+), 2 deletions(-)
 create mode 100644 packages/visuals/src/format.spec.ts
 create mode 100644 packages/visuals/src/format.ts

diff --git a/packages/visuals/src/format.spec.ts b/packages/visuals/src/format.spec.ts
new file mode 100644
index 0000000..c4f9d87
--- /dev/null
+++ b/packages/visuals/src/format.spec.ts
@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import {
+  Alphabet,
+  Tape,
+  TapeBlock,
+  TapeCommand,
+  TuringMachine,
+  State,
+  haltState,
+  movements,
+  symbolCommands,
+} from '@turing-machine-js/machine';
+import { formatCommand, formatStep } from './format';
+
+describe('formatCommand', () => {
+  it('formats a literal symbol write + right move', () => {
+    const tc = new TapeCommand({ symbol: 'X', movement: movements.right });
+    expect(formatCommand(tc)).toBe("'X'/R");
+  });
+
+  it('formats keep + stay as K/S', () => {
+    const tc = new TapeCommand({ movement: movements.stay });
+    // default symbol is symbolCommands.keep
+    expect(formatCommand(tc)).toBe('K/S');
+  });
+
+  it('formats erase + left as E/L', () => {
+    const tc = new TapeCommand({ symbol: symbolCommands.erase, movement: movements.left });
+    expect(formatCommand(tc)).toBe('E/L');
+  });
+
+  it('formats keep + right as K/R', () => {
+    const tc = new TapeCommand({ symbol: symbolCommands.keep, movement: movements.right });
+    expect(formatCommand(tc)).toBe('K/R');
+  });
+
+  it('formats a literal symbol write + left move', () => {
+    const tc = new TapeCommand({ symbol: 'a', movement: movements.left });
+    expect(formatCommand(tc)).toBe("'a'/L");
+  });
+});
+
+describe('formatStep', () => {
+  it("formats a single-tape iter: 'a' → 'b'/R", () => {
+    const alphabet = new Alphabet([' ', 'a', 'b']);
+    const tape = new Tape({ alphabet, symbols: ['a'] });
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({ tapeBlock });
+    const initialState = new State({
+      [tapeBlock.symbol(['a'])]: {
+        command: [{ symbol: 'b', movement: movements.right }],
+        nextState: haltState,
+      },
+    });
+    const gen = machine.runStepByStep({ initialState });
+    const m = gen.next().value!;
+
+    expect(formatStep(m)).toBe("['a'] → ['b']/[R]");
+  });
+
+  it('encodes keep as K when nextSymbol equals currentSymbol', () => {
+    const alphabet = new Alphabet([' ', 'a', 'b']);
+    const tape = new Tape({ alphabet, symbols: ['a'] });
+    const tapeBlock = TapeBlock.fromTapes([tape]);
+    const machine = new TuringMachine({ tapeBlock });
+    const initialState = new State({
+      [tapeBlock.symbol(['a'])]: {
+        command: [{ symbol: symbolCommands.keep, movement: movements.stay }],
+        nextState: haltState,
+      },
+    });
+    const gen = machine.runStepByStep({ initialState });
+    const m = gen.next().value!;
+
+    // keep → nextSymbols[0] === currentSymbols[0], so write cell is K
+    expect(formatStep(m)).toBe("['a'] → [K]/[S]");
+  });
+
+  it('formats a 2-tape iter with comma-separated entries', () => {
+    const alphabetA = new Alphabet([' ', 'a', 'b']);
+    const alphabetB = new Alphabet([' ', 'x', 'y']);
+    const tape1 = new Tape({ alphabet: alphabetA, symbols: ['a'] });
+    const tape2 = new Tape({ alphabet: alphabetB, symbols: ['x'] });
+    const tapeBlock = TapeBlock.fromTapes([tape1, tape2]);
+    const machine = new TuringMachine({ tapeBlock });
+    const initialState = new State({
+      [tapeBlock.symbol(['a', 'x'])]: {
+        command: [
+          { symbol: 'b', movement: movements.right },
+          { symbol: symbolCommands.keep, movement: movements.left },
+        ],
+        nextState: haltState,
+      },
+    });
+    const gen = machine.runStepByStep({ initialState });
+    const m = gen.next().value!;
+
+    expect(formatStep(m)).toBe("['a','x'] → ['b',K]/[R,L]");
+  });
+});
diff --git a/packages/visuals/src/format.ts b/packages/visuals/src/format.ts
new file mode 100644
index 0000000..f8c1632
--- /dev/null
+++ b/packages/visuals/src/format.ts
@@ -0,0 +1,51 @@
+import { movements, symbolCommands, type MachineState, type TapeCommand } from '@turing-machine-js/machine';
+
+const MOVEMENT_LETTER = new Map<symbol, string>([
+  [movements.left, 'L'],
+  [movements.right, 'R'],
+  [movements.stay, 'S'],
+]);
+
+/**
+ * Render a single tape command in `WRITE/MOVE` form.
+ * - Write: `'X'` (literal symbol) | `K` (keep) | `E` (erase = write blank).
+ * - Move: `L` / `R` / `S` from `movements.*`.
+ *
+ * Matches the engine's edge-label vocabulary so formatted commands line up
+ * with the write/move cells in `toMermaid`-emitted edge labels.
+ */
+export function formatCommand(tapeCommand: TapeCommand): string {
+  let write: string;
+
+  if (tapeCommand.symbol === symbolCommands.keep) {
+    write = 'K';
+  } else if (tapeCommand.symbol === symbolCommands.erase) {
+    write = 'E';
+  } else {
+    write = `'${tapeCommand.symbol as string}'`;
+  }
+
+  const move = MOVEMENT_LETTER.get(tapeCommand.movement) ?? '?';
+
+  return `${write}/${move}`;
+}
+
+/**
+ * Render one step's edge-label notation: `[reads] → [writes]/[moves]`.
+ * Each role is wrapped in a single `[…]`; multi-tape entries are
+ * comma-separated inside the brackets.
+ *
+ * Matches the engine's `toMermaid` emit so logged steps line up with
+ * graph edge labels. Note: `nextSymbols` in `MachineState` is already
+ * resolved (keep → current symbol, erase → blank) — `K` is inferred
+ * by comparing `nextSymbols[i] === currentSymbols[i]`.
+ */
+export function formatStep(m: MachineState): string {
+  const reads = m.currentSymbols.map((s) => `'${s}'`).join(',');
+  const writes = m.nextSymbols
+    .map((s, i) => (s === m.currentSymbols[i] ? 'K' : `'${s}'`))
+    .join(',');
+  const moves = m.movements.map((mv) => MOVEMENT_LETTER.get(mv) ?? '?').join(',');
+
+  return `[${reads}] → [${writes}]/[${moves}]`;
+}
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index c6435ec..1d6b986 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -1,8 +1,9 @@
-// Public API — populated as modules are moved in Tasks 2–8.
+// Public API — extracted modules + Snippet recording surface.
 export type { NodeKey, HighlightClass, HighlightOps, IndicatorOps, RecordedOp } from './highlightOps';
 export { recordingOps } from './highlightOps';
 export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
 export type { GraphIndexes } from './graphIndexes';
 export { indexGraph } from './graphIndexes';
-export type { GraphHighlight } from './types';
+export type { GraphHighlight, TapeSnapshot, Frame, Snippet } from './types';
 export { applyHighlight, applyIndicator } from './applyHighlight';
+export { formatCommand, formatStep } from './format';
diff --git a/packages/visuals/src/types.ts b/packages/visuals/src/types.ts
index 248b15f..f3d389d 100644
--- a/packages/visuals/src/types.ts
+++ b/packages/visuals/src/types.ts
@@ -1,3 +1,5 @@
+import type { Graph } from '@turing-machine-js/machine';
+
 /**
  * State-graph highlight descriptor (machines-demo#10). MachineView derives it
  * from `executionMode` + the latest pause-response data; MachineGraph reads
@@ -29,3 +31,46 @@ export type GraphHighlight = {
    */
   paused: boolean;
 };
+
+/**
+ * Per-tape snapshot: the cells visible/usable plus the head's index into them.
+ * Same shape as machines-demo's TapeSnapshot. Pure data — no library handles.
+ */
+export type TapeSnapshot = {
+  symbols: string[];
+  position: number;
+};
+
+/**
+ * One frame of a recorded snippet — the state of the machine at iter `step`.
+ * Frame 0 = initial state (before any transition); frame N = state after iter N's transition.
+ *
+ * `tape` is per-tape (single-tape machines: length 1). `highlight` describes
+ * what to render on the state graph at this moment (null when no highlight).
+ * `log` is optional pre-formatted text — a caption / status line consumers can render.
+ */
+export type Frame = {
+  step: number;
+  tape: TapeSnapshot[];
+  highlight: GraphHighlight | null;
+  log?: string;
+};
+
+/**
+ * Recorded run of a machine — playback artifact for embeds, articles,
+ * landing-page panels. Engine-agnostic (no `engine` field; identity lives
+ * at the caller bucket level).
+ *
+ * - `version: 1` — schema integer. Additive fields don't bump it;
+ *   shape-breaking changes do.
+ * - `graph` — engine `State.toGraph` output captured at recording time.
+ * - `alphabets` — per-tape alphabet list (single-tape: length 1).
+ * - `frames` — length === `stepsApplied + 1`; frame 0 is the initial state.
+ */
+export type Snippet = {
+  version: 1;
+  name?: string;
+  graph: Graph;
+  alphabets: string[][];
+  frames: Frame[];
+};

From 237070e5f2c2d332d2a70009de412a8751ad225e Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:52:43 +0300
Subject: [PATCH 091/118] feat(visuals): implement recordSnippet + extend Frame
 with per-tape commands (#204)

---
 packages/visuals/src/format.ts             |   2 +-
 packages/visuals/src/index.ts              |   1 +
 packages/visuals/src/recordSnippet.spec.ts | 274 +++++++++++++++++++++
 packages/visuals/src/recordSnippet.ts      | 142 +++++++++++
 packages/visuals/src/types.ts              |  16 ++
 5 files changed, 434 insertions(+), 1 deletion(-)
 create mode 100644 packages/visuals/src/recordSnippet.spec.ts
 create mode 100644 packages/visuals/src/recordSnippet.ts

diff --git a/packages/visuals/src/format.ts b/packages/visuals/src/format.ts
index f8c1632..a9ae8b2 100644
--- a/packages/visuals/src/format.ts
+++ b/packages/visuals/src/format.ts
@@ -1,6 +1,6 @@
 import { movements, symbolCommands, type MachineState, type TapeCommand } from '@turing-machine-js/machine';
 
-const MOVEMENT_LETTER = new Map<symbol, string>([
+export const MOVEMENT_LETTER = new Map<symbol, 'L' | 'R' | 'S'>([
   [movements.left, 'L'],
   [movements.right, 'R'],
   [movements.stay, 'S'],
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 1d6b986..1bdcc57 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -7,3 +7,4 @@ export { indexGraph } from './graphIndexes';
 export type { GraphHighlight, TapeSnapshot, Frame, Snippet } from './types';
 export { applyHighlight, applyIndicator } from './applyHighlight';
 export { formatCommand, formatStep } from './format';
+export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';
diff --git a/packages/visuals/src/recordSnippet.spec.ts b/packages/visuals/src/recordSnippet.spec.ts
new file mode 100644
index 0000000..2a0cf20
--- /dev/null
+++ b/packages/visuals/src/recordSnippet.spec.ts
@@ -0,0 +1,274 @@
+import { describe, it, expect } from 'vitest';
+import {
+  Alphabet,
+  State,
+  Tape,
+  TapeBlock,
+  TuringMachine,
+  haltState,
+  ifOtherSymbol,
+  movements,
+  symbolCommands,
+} from '@turing-machine-js/machine';
+import { recordSnippet } from './recordSnippet';
+
+/** Build a machine that converts each 'a' → 'b' (move right) until blank (halt). */
+function buildTwoAMachine() {
+  const alphabet = new Alphabet([' ', 'a', 'b']);
+  const tape = new Tape({ alphabet, symbols: ['a', 'a'] });
+  const tapeBlock = TapeBlock.fromTapes([tape]);
+  const machine = new TuringMachine({ tapeBlock });
+
+  const initialState = new State({
+    [tapeBlock.symbol(['a'])]: {
+      command: [{ symbol: 'b', movement: movements.right }],
+    },
+    [ifOtherSymbol]: {
+      nextState: haltState,
+    },
+  });
+
+  const graph = State.toGraph(initialState, tapeBlock);
+  const alphabets = [alphabet.symbols.filter((s) => s !== alphabet.blankSymbol).concat(alphabet.blankSymbol)];
+
+  return { machine, initialState, graph, alphabets, alphabet };
+}
+
+describe('recordSnippet', () => {
+  describe('frame 0 (initial state)', () => {
+    it('step is 0', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.frames[0].step).toBe(0);
+    });
+
+    it('commands is undefined', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.frames[0].commands).toBeUndefined();
+    });
+
+    it('highlight is null', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.frames[0].highlight).toBeNull();
+    });
+
+    it('tape reflects initial state (position 0, contains "a")', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      const frame0Tape = snippet.frames[0].tape[0];
+      expect(frame0Tape.position).toBe(0);
+      expect(frame0Tape.symbols).toContain('a');
+    });
+  });
+
+  describe('frame count', () => {
+    it('2 "a"s + halt iter = 3 iters → 4 frames (frame 0 + 3)', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      // iter 1: read 'a', write 'b', move R
+      // iter 2: read 'a', write 'b', move R
+      // iter 3: read blank, nextState = haltState
+      expect(snippet.frames).toHaveLength(4);
+    });
+  });
+
+  describe('per-iter frame commands', () => {
+    it('frame 1: write "b", move R', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.frames[1].commands).toEqual([{ movement: 'R', symbol: 'b' }]);
+    });
+
+    it('frame 2: write "b", move R', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.frames[2].commands).toEqual([{ movement: 'R', symbol: 'b' }]);
+    });
+
+    it('frame 3 (halt iter): symbol null (keep), movement S (stay)', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      // halt-bound transition has default command: keep + stay
+      expect(snippet.frames[3].commands).toEqual([{ movement: 'S', symbol: null }]);
+    });
+  });
+
+  describe('per-iter frame tape (post-command snapshots)', () => {
+    it('frame 1 tape: "b" written at position 0, head at position 1', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      const tape = snippet.frames[1].tape[0];
+      expect(tape.symbols[0]).toBe('b');
+      expect(tape.position).toBe(1);
+    });
+
+    it('frame 2 tape: both cells "b", head at position 2', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      const tape = snippet.frames[2].tape[0];
+      expect(tape.symbols[0]).toBe('b');
+      expect(tape.symbols[1]).toBe('b');
+      expect(tape.position).toBe(2);
+    });
+  });
+
+  describe('snippet metadata', () => {
+    it('version is 1', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.version).toBe(1);
+    });
+
+    it('graph is the passed-in graph (referential equality)', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.graph).toBe(graph);
+    });
+
+    it('alphabets is the passed-in alphabets (referential equality)', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.alphabets).toBe(alphabets);
+    });
+
+    it('name is set when provided', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets, name: 'test snippet' });
+      expect(snippet.name).toBe('test snippet');
+    });
+
+    it('name is absent when not provided', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect('name' in snippet).toBe(false);
+    });
+  });
+
+  describe('log option', () => {
+    it('attaches log to non-frame-0 frames when log returns a string', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({
+        machine,
+        initialState,
+        graph,
+        alphabets,
+        log: () => 'step line',
+      });
+      // frame 0 has no log
+      expect(snippet.frames[0].log).toBeUndefined();
+      // frames 1-3 all have log
+      for (let i = 1; i < snippet.frames.length; i++) {
+        expect(snippet.frames[i].log).toBe('step line');
+      }
+    });
+
+    it('omits log when log returns undefined', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({
+        machine,
+        initialState,
+        graph,
+        alphabets,
+        log: () => undefined,
+      });
+      for (const frame of snippet.frames) {
+        expect('log' in frame).toBe(false);
+      }
+    });
+
+    it('passes current and previous MachineState to log', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const calls: [unknown, unknown][] = [];
+      recordSnippet({
+        machine,
+        initialState,
+        graph,
+        alphabets,
+        log: (m, prev) => { calls.push([m.step, prev ? prev.step : null]); return undefined; },
+      });
+      // 3 iters → 3 log calls
+      expect(calls).toHaveLength(3);
+      expect(calls[0]).toEqual([1, null]);
+      expect(calls[1]).toEqual([2, 1]);
+      expect(calls[2]).toEqual([3, 2]);
+    });
+  });
+
+  describe('maxSteps truncation', () => {
+    it('with maxSteps: 1 → 2 frames (frame 0 + frame 1)', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets, maxSteps: 1 });
+      expect(snippet.frames).toHaveLength(2);
+    });
+
+    it('with maxSteps: 1, frame 1 tape reflects the first command applied', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets, maxSteps: 1 });
+      const tape = snippet.frames[1].tape[0];
+      // 'a' was written to 'b', head moved right
+      expect(tape.symbols[0]).toBe('b');
+      expect(tape.position).toBe(1);
+    });
+  });
+
+  describe('highlight', () => {
+    it('non-frame-0 frames have a non-null highlight with strong: "from" and paused: false', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      for (let i = 1; i < snippet.frames.length; i++) {
+        const h = snippet.frames[i].highlight;
+        expect(h).not.toBeNull();
+        expect(h!.strong).toBe('from');
+        expect(h!.paused).toBe(false);
+      }
+    });
+
+    it('halt-iter frame highlight has toId: 0 (haltState)', () => {
+      const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      const lastFrame = snippet.frames[snippet.frames.length - 1];
+      expect(lastFrame.highlight!.toId).toBe(0);
+    });
+  });
+
+  describe('single-step machine (halts immediately)', () => {
+    it('produces 2 frames when machine halts on step 1', () => {
+      const alphabet = new Alphabet([' ', 'x']);
+      const tape = new Tape({ alphabet, symbols: ['x'] });
+      const tapeBlock = TapeBlock.fromTapes([tape]);
+      const machine = new TuringMachine({ tapeBlock });
+      const initialState = new State({
+        [ifOtherSymbol]: { nextState: haltState },
+      });
+      const graph = State.toGraph(initialState, tapeBlock);
+      const alphabets = [['x', ' ']];
+
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.frames).toHaveLength(2);
+      expect(snippet.frames[0].commands).toBeUndefined();
+      expect(snippet.frames[1].commands).toBeDefined();
+    });
+  });
+
+  describe('keep command → symbol null', () => {
+    it('a keep+stay command produces symbol: null in commands', () => {
+      const alphabet = new Alphabet([' ', 'a']);
+      const tape = new Tape({ alphabet, symbols: ['a'] });
+      const tapeBlock = TapeBlock.fromTapes([tape]);
+      const machine = new TuringMachine({ tapeBlock });
+      const initialState = new State({
+        [tapeBlock.symbol(['a'])]: {
+          command: [{ symbol: symbolCommands.keep, movement: movements.stay }],
+          nextState: haltState,
+        },
+      });
+      const graph = State.toGraph(initialState, tapeBlock);
+      const alphabets = [['a', ' ']];
+
+      const snippet = recordSnippet({ machine, initialState, graph, alphabets });
+      expect(snippet.frames[1].commands![0]).toEqual({ movement: 'S', symbol: null });
+    });
+  });
+});
diff --git a/packages/visuals/src/recordSnippet.ts b/packages/visuals/src/recordSnippet.ts
new file mode 100644
index 0000000..b0b8241
--- /dev/null
+++ b/packages/visuals/src/recordSnippet.ts
@@ -0,0 +1,142 @@
+import {
+  haltState,
+  type Graph,
+  type MachineState,
+  type State,
+  type TuringMachine,
+} from '@turing-machine-js/machine';
+import { MOVEMENT_LETTER } from './format';
+import { bareIdOf } from './graphUtils';
+import type { Frame, GraphHighlight, Snippet, TapeSnapshot } from './types';
+
+export type RecordSnippetOptions = {
+  machine: TuringMachine;
+  initialState: State;
+  graph: Graph;
+  alphabets: string[][];
+  name?: string;
+  /**
+   * Maximum number of iteration steps to record. Defaults to 1000.
+   * If the machine hasn't halted after `maxSteps` iters, recording stops
+   * and the snippet contains `maxSteps + 1` frames (frame 0 plus one per iter).
+   */
+  maxSteps?: number;
+  /**
+   * Optional per-frame log formatter. Called with the current and previous
+   * `MachineState`; return a string to attach as `frame.log`, or `undefined`
+   * to omit. Not called for frame 0 (initial state — no transition has fired).
+   */
+  log?: (m: MachineState, prev: MachineState | null) => string | undefined;
+};
+
+const DEFAULT_MAX_STEPS = 1000;
+
+function snapshotTapes(machine: TuringMachine): TapeSnapshot[] {
+  return machine.tapeBlock.tapes.map((t) => ({
+    symbols: [...t.symbols],
+    position: t.position,
+  }));
+}
+
+function deriveCommands(
+  m: MachineState,
+): NonNullable<Frame['commands']> {
+  return m.movements.map((mv, i) => {
+    const movement = MOVEMENT_LETTER.get(mv) ?? 'S';
+    // nextSymbols is already resolved (keep → current symbol, erase → blank).
+    // If it equals the current symbol the command is "keep" → null (no write flash).
+    const written =
+      m.nextSymbols[i] !== m.currentSymbols[i] ? m.nextSymbols[i] : null;
+    return { movement, symbol: written };
+  });
+}
+
+function deriveHighlight(m: MachineState, graph: Graph): GraphHighlight {
+  return {
+    fromId: bareIdOf(m.state.id, graph),
+    toId: m.nextState === haltState ? 0 : m.nextState.id,
+    strong: 'from',
+    paused: false,
+  };
+}
+
+/**
+ * Record a full machine run into a `Snippet` — a self-contained playback
+ * artifact suitable for embeds, articles, or landing-page panels.
+ *
+ * The returned snippet contains one frame per iteration plus a frame-0
+ * initial-state snapshot. Recording stops when the machine halts or when
+ * `maxSteps` iterations have been consumed (default 1000).
+ *
+ * Tape-timing note: `runStepByStep` yields BEFORE applying its command
+ * (the command is applied after the yield resumes). The recorder uses a
+ * one-step-delayed snapshot so each frame's `tape` reflects the
+ * post-command state for that frame's iter.
+ */
+export function recordSnippet(opts: RecordSnippetOptions): Snippet {
+  const {
+    machine,
+    initialState,
+    graph,
+    alphabets,
+    name,
+    maxSteps = DEFAULT_MAX_STEPS,
+    log,
+  } = opts;
+
+  const frames: Frame[] = [
+    { step: 0, tape: snapshotTapes(machine), highlight: null },
+  ];
+
+  // pending holds everything for the frame whose tape snapshot is not yet
+  // available (because applyCommand hasn't fired yet). It is flushed at the
+  // start of the NEXT iter (when the tape reflects the previous command) and
+  // after the loop (when the final command has been applied).
+  let pending: Omit<Frame, 'tape'> | null = null;
+  let prev: MachineState | null = null;
+
+  try {
+    for (const m of machine.runStepByStep({ initialState, stepsLimit: maxSteps })) {
+      // At this point applyCommand for the PREVIOUS iter has already run
+      // (the generator called applyCommand before looping back to yield).
+      // So the current tape state = post-command of the previous iter.
+      if (pending !== null) {
+        frames.push({ ...pending, tape: snapshotTapes(machine) });
+      }
+
+      const commands = deriveCommands(m);
+      const highlight = deriveHighlight(m, graph);
+      const logLine = log ? log(m, prev) : undefined;
+
+      pending = {
+        step: m.step,
+        commands,
+        highlight,
+        ...(logLine !== undefined ? { log: logLine } : {}),
+      };
+
+      prev = m;
+    }
+  } catch (e) {
+    // runStepByStep throws 'Long execution' when stepsLimit is hit.
+    // At that point applyCommand for the last yielded iter has run, so the
+    // tape is in the post-command state we want for the pending frame.
+    if (!(e instanceof Error) || e.message !== 'Long execution') {
+      throw e;
+    }
+  }
+
+  // Flush the last pending frame. After the loop (or after the catch), the
+  // tape reflects the post-command state of the final yielded iter.
+  if (pending !== null) {
+    frames.push({ ...pending, tape: snapshotTapes(machine) });
+  }
+
+  return {
+    version: 1,
+    ...(name !== undefined ? { name } : {}),
+    graph,
+    alphabets,
+    frames,
+  };
+}
diff --git a/packages/visuals/src/types.ts b/packages/visuals/src/types.ts
index f3d389d..38e63f2 100644
--- a/packages/visuals/src/types.ts
+++ b/packages/visuals/src/types.ts
@@ -48,10 +48,26 @@ export type TapeSnapshot = {
  * `tape` is per-tape (single-tape machines: length 1). `highlight` describes
  * what to render on the state graph at this moment (null when no highlight).
  * `log` is optional pre-formatted text — a caption / status line consumers can render.
+ * `commands` carries the per-tape engine command for the iter that produced this frame.
+ * Undefined on frame 0 (initial state — no transition has fired yet).
+ * `movement` drives the tape slide direction; `symbol === null` means keep (no write —
+ * UI skips the per-cell flash); a non-null `symbol` is the literal that was written to
+ * the just-vacated cell.
  */
 export type Frame = {
   step: number;
   tape: TapeSnapshot[];
+  /**
+   * Per-tape engine command for the iter that produced this frame.
+   * Undefined on frame 0 (initial state — no transition has fired yet).
+   * `movement` drives the tape slide direction; `symbol === null` means
+   * keep (no write — UI skips the per-cell flash); a non-null `symbol`
+   * is the literal that was written to the just-vacated cell.
+   */
+  commands?: {
+    movement: 'L' | 'R' | 'S';
+    symbol: string | null;
+  }[];
   highlight: GraphHighlight | null;
   log?: string;
 };

From 672f4560dd0c646ddbd764c869ee6df7294f7722 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:56:56 +0300
Subject: [PATCH 092/118] feat(visuals): expose read+write on Frame commands
 for bidirectional playback (#204)

---
 packages/visuals/src/recordSnippet.spec.ts | 21 ++++++++++---------
 packages/visuals/src/recordSnippet.ts      | 15 +++++++-------
 packages/visuals/src/types.ts              | 24 +++++++++++++---------
 3 files changed, 32 insertions(+), 28 deletions(-)

diff --git a/packages/visuals/src/recordSnippet.spec.ts b/packages/visuals/src/recordSnippet.spec.ts
index 2a0cf20..a131f1d 100644
--- a/packages/visuals/src/recordSnippet.spec.ts
+++ b/packages/visuals/src/recordSnippet.spec.ts
@@ -75,23 +75,24 @@ describe('recordSnippet', () => {
   });
 
   describe('per-iter frame commands', () => {
-    it('frame 1: write "b", move R', () => {
+    it('frame 1: read "a", write "b", move R', () => {
       const { machine, initialState, graph, alphabets } = buildTwoAMachine();
       const snippet = recordSnippet({ machine, initialState, graph, alphabets });
-      expect(snippet.frames[1].commands).toEqual([{ movement: 'R', symbol: 'b' }]);
+      expect(snippet.frames[1].commands).toEqual([{ movement: 'R', read: 'a', write: 'b' }]);
     });
 
-    it('frame 2: write "b", move R', () => {
+    it('frame 2: read "a", write "b", move R', () => {
       const { machine, initialState, graph, alphabets } = buildTwoAMachine();
       const snippet = recordSnippet({ machine, initialState, graph, alphabets });
-      expect(snippet.frames[2].commands).toEqual([{ movement: 'R', symbol: 'b' }]);
+      expect(snippet.frames[2].commands).toEqual([{ movement: 'R', read: 'a', write: 'b' }]);
     });
 
-    it('frame 3 (halt iter): symbol null (keep), movement S (stay)', () => {
+    it('frame 3 (halt iter): read===write (keep), movement S (stay)', () => {
       const { machine, initialState, graph, alphabets } = buildTwoAMachine();
       const snippet = recordSnippet({ machine, initialState, graph, alphabets });
-      // halt-bound transition has default command: keep + stay
-      expect(snippet.frames[3].commands).toEqual([{ movement: 'S', symbol: null }]);
+      // halt-bound transition has default command: keep + stay; blank cell read+written
+      const blank = snippet.frames[3].commands![0].read;
+      expect(snippet.frames[3].commands).toEqual([{ movement: 'S', read: blank, write: blank }]);
     });
   });
 
@@ -252,8 +253,8 @@ describe('recordSnippet', () => {
     });
   });
 
-  describe('keep command → symbol null', () => {
-    it('a keep+stay command produces symbol: null in commands', () => {
+  describe('keep command → read === write', () => {
+    it('a keep+stay command yields read === write in commands', () => {
       const alphabet = new Alphabet([' ', 'a']);
       const tape = new Tape({ alphabet, symbols: ['a'] });
       const tapeBlock = TapeBlock.fromTapes([tape]);
@@ -268,7 +269,7 @@ describe('recordSnippet', () => {
       const alphabets = [['a', ' ']];
 
       const snippet = recordSnippet({ machine, initialState, graph, alphabets });
-      expect(snippet.frames[1].commands![0]).toEqual({ movement: 'S', symbol: null });
+      expect(snippet.frames[1].commands![0]).toEqual({ movement: 'S', read: 'a', write: 'a' });
     });
   });
 });
diff --git a/packages/visuals/src/recordSnippet.ts b/packages/visuals/src/recordSnippet.ts
index b0b8241..4439f13 100644
--- a/packages/visuals/src/recordSnippet.ts
+++ b/packages/visuals/src/recordSnippet.ts
@@ -41,14 +41,13 @@ function snapshotTapes(machine: TuringMachine): TapeSnapshot[] {
 function deriveCommands(
   m: MachineState,
 ): NonNullable<Frame['commands']> {
-  return m.movements.map((mv, i) => {
-    const movement = MOVEMENT_LETTER.get(mv) ?? 'S';
-    // nextSymbols is already resolved (keep → current symbol, erase → blank).
-    // If it equals the current symbol the command is "keep" → null (no write flash).
-    const written =
-      m.nextSymbols[i] !== m.currentSymbols[i] ? m.nextSymbols[i] : null;
-    return { movement, symbol: written };
-  });
+  return m.movements.map((mv, i) => ({
+    movement: MOVEMENT_LETTER.get(mv) ?? 'S',
+    read: m.currentSymbols[i],
+    // nextSymbols is already resolved (keep → current symbol, erase → blank);
+    // when write === read the command was a keep (UI suppresses the flash).
+    write: m.nextSymbols[i],
+  }));
 }
 
 function deriveHighlight(m: MachineState, graph: Graph): GraphHighlight {
diff --git a/packages/visuals/src/types.ts b/packages/visuals/src/types.ts
index 38e63f2..10c4784 100644
--- a/packages/visuals/src/types.ts
+++ b/packages/visuals/src/types.ts
@@ -48,25 +48,29 @@ export type TapeSnapshot = {
  * `tape` is per-tape (single-tape machines: length 1). `highlight` describes
  * what to render on the state graph at this moment (null when no highlight).
  * `log` is optional pre-formatted text — a caption / status line consumers can render.
- * `commands` carries the per-tape engine command for the iter that produced this frame.
- * Undefined on frame 0 (initial state — no transition has fired yet).
- * `movement` drives the tape slide direction; `symbol === null` means keep (no write —
- * UI skips the per-cell flash); a non-null `symbol` is the literal that was written to
- * the just-vacated cell.
  */
 export type Frame = {
   step: number;
   tape: TapeSnapshot[];
   /**
-   * Per-tape engine command for the iter that produced this frame.
+   * Per-tape engine command for the iter that produced this frame. Carries
+   * both sides of the cell so players can step bi-directionally without
+   * recomputing from neighbouring frames:
+   *
+   * - `movement` — `'L' | 'R' | 'S'`. Forward step slides the tape this way;
+   *   backward step slides the opposite.
+   * - `read` — symbol on the head's cell BEFORE this iter (what the engine
+   *   matched). Backward step writes this back.
+   * - `write` — symbol on the cell AFTER this iter (=== `read` if no write
+   *   happened). Forward step writes this; UI triggers the per-cell flash
+   *   iff `write !== read`.
+   *
    * Undefined on frame 0 (initial state — no transition has fired yet).
-   * `movement` drives the tape slide direction; `symbol === null` means
-   * keep (no write — UI skips the per-cell flash); a non-null `symbol`
-   * is the literal that was written to the just-vacated cell.
    */
   commands?: {
     movement: 'L' | 'R' | 'S';
-    symbol: string | null;
+    read: string;
+    write: string;
   }[];
   highlight: GraphHighlight | null;
   log?: string;

From c7df4f960b9d0a9129d4244e746ef7f4e47c73e4 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 15:57:45 +0300
Subject: [PATCH 093/118] docs(visuals): expand CHANGELOG with recordSnippet
 surface; update plan with folded scope (#204)

---
 .../2026-05-30-visuals-package-extract.md     | 42 ++++++++++++-------
 packages/visuals/CHANGELOG.md                 | 12 +++++-
 2 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/docs/superpowers/plans/2026-05-30-visuals-package-extract.md b/docs/superpowers/plans/2026-05-30-visuals-package-extract.md
index 2833a35..871332c 100644
--- a/docs/superpowers/plans/2026-05-30-visuals-package-extract.md
+++ b/docs/superpowers/plans/2026-05-30-visuals-package-extract.md
@@ -2,7 +2,9 @@
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
-**Goal:** Extract machines-demo's pure highlight/graph-indexing modules + rules doc into a new lockstep-published package `@turing-machine-js/visuals`. NO new functionality in this PR — pure code-move + scaffold. `recordSnippet` + Snippet/Frame schema lands as a follow-up plan (issue step 3).
+**Goal:** Extract machines-demo's pure highlight/graph-indexing modules + rules doc into a new lockstep-published package `@turing-machine-js/visuals`, AND ship the initial `recordSnippet` + `Snippet`/`Frame` schema so v1 publishes with a complete API.
+
+**Scope split:** Originally drafted as extraction-only (issue step 1) with `recordSnippet` as a follow-up PR (step 3). **Revised mid-implementation to fold step 3 in** — so the first published alpha carries the complete v1 API ready to feed the landing-page work (#79). Step 2 (machines-demo cleanup) remains a separate follow-up in the machines-demo repo. See Tasks 10–13 below.
 
 **Architecture:** New `packages/visuals/` workspace, peer dep on `@turing-machine-js/machine` (`Graph` type only — no runtime dependency). Pure TypeScript, no DOM, no Svelte. Modules are line-for-line moves: `TuringGraph` local alias becomes `import { Graph } from '@turing-machine-js/machine'`; everything else unchanged. The rules doc moves under `packages/visuals/docs/`. machines-demo's local copies + the doc-source are deleted in a follow-up demo PR (issue step 2, **not** this PR — keeps the extract PR self-contained and reviewable against engine tests only).
 
@@ -18,7 +20,12 @@
 
 - **Package name: `@turing-machine-js/visuals`.** Issue #204 lists this as an open question between `visuals` / `highlight` / `graph-visuals`. Going with `visuals` — broadest, room for `recordSnippet` + future visual primitives without renaming.
 - **No DOM applier sub-export in v1.** The package stays purely renderer-agnostic. A future `@turing-machine-js/visuals/dom` sub-path can be added non-breakingly when there's a concrete consumer asking for one. Out of scope here.
-- **Snippet schema versioning policy (deferred to PR B).** This PR does NOT introduce the schema; recording the policy now keeps PR B short: additive fields don't bump `version`; breaking shape changes bump the integer. Will be documented in PR B's README addition.
+- **Snippet schema versioning policy.** Additive fields don't bump `version`; breaking shape changes bump the integer. Documented in the README addition that ships with Task 13.
+- **`Frame` shape (locked).** Per-iter capture: `{ step: number; tape: TapeSnapshot[]; highlight: GraphHighlight | null; log?: string }`. `step` is 0-indexed iter (frame 0 = initial state, before any transition). `tape` is per-tape array (single-tape: length 1). `highlight` is the GraphHighlight to render for this frame (null = no active highlight). `log` is optional pre-formatted text; consumers can render it as a caption / status line. Users wanting a different shape pass `log` callback for the string only — Frame's structural fields stay fixed (consumers' renderers depend on the shape).
+- **`Snippet` shape (locked, no `engine` field per #204 comment).** `{ version: 1; name?: string; graph: Graph; alphabets: string[][]; frames: Frame[] }`. `frames.length === stepsApplied + 1` — frame 0 is the initial state. `alphabets` is per-tape (single-tape: length 1).
+- **`recordSnippet` signature (locked).** `recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }): Snippet`. Caller supplies pre-built `machine`, `initialState`, pre-computed `graph` (via `State.toGraph`), and `alphabets`. Caller chooses which engine (turing-machine-js or post-machine-js) — recorder is engine-agnostic, just runs `machine.runStepByStep({ initialState, stepsLimit: maxSteps })` and captures per iter. `log` callback (optional) receives `(machineState, prevMachineState | null)` and returns the line text. Default frame has `log: undefined`.
+- **Default formatter primitives.** Ship `formatCommand(command)` + `formatStep(machineState, prev?)` as composable helpers, exported alongside `recordSnippet`. Format mirrors the engine's edge-label notation (`[reads] → [writes]/[moves]`) so a logged step lines up with the rendered graph's edge. Users compose their own `log` callback by combining these or write their own from scratch.
+- **`TapeSnapshot` type moves into visuals.** `{ symbols: string[]; position: number }` — pure data, renderer-agnostic, lives in `packages/visuals/src/types.ts` alongside `GraphHighlight`. Demo's local copy stays during this PR (cleaned up in the step-2 follow-up).
 - **`graphHighlightDerivation.ts` does NOT extract.** Its `ExecutionMode` union mirrors machines-demo's MachineView state machine (`'DEMO' | 'MANUAL' | 'RUNNING_AUTO' | …`) — demo orchestration, not engine semantics. Stays in machines-demo and imports `bareIdOf` from the published package post-extract.
 - **`Snippet.engine` field is dropped (per #204 comment 2026-05-29).** Pinned here so PR B inherits the constraint. Engine identity lives at the caller bucket level (`{ turing: Snippet[], post: Snippet[] }`), not on the artifact.
 - **No content rewrites during the move.** Rules doc moves verbatim — any rewording is a separate edit later. Keeps this PR's diff a clean move.
@@ -31,27 +38,30 @@
 ```
 packages/visuals/
 ├── package.json              # NEW — peer dep on @turing-machine-js/machine
-├── tsconfig.json             # NEW — project references, extends repo conventions
+├── tsconfig.json             # NEW — IDE/typecheck config (mirrors machine's)
+├── tsconfig.build.json       # NEW — composite-build config (mirrors machine's)
 ├── README.md                 # NEW — what this package is, public API summary
 ├── src/
-│   ├── index.ts              # NEW — re-exports public surface
-│   ├── highlightOps.ts       # MOVED from machines-demo/src/lib/highlightOps.ts
-│   ├── graphUtils.ts         # MOVED from machines-demo/src/lib/graphUtils.ts
-│   ├── graphIndexes.ts       # MOVED from machines-demo/src/lib/graphIndexes.ts
-│   └── applyHighlight.ts     # MOVED from machines-demo/src/lib/applyHighlight.ts
-├── tests/
-│   ├── graphUtils.spec.ts    # MOVED — renamed .test.ts → .spec.ts to match repo convention
-│   ├── graphIndexes.spec.ts  # (no source test in demo; trivial test added if extraction warrants)
-│   ├── applyHighlight.spec.ts # MOVED + renamed
-│   ├── graphFixtures.spec.ts # MOVED + renamed
-│   └── fixtures/             # MOVED — fixture JSONs (graphs/*.json) used by graphFixtures
+│   ├── index.ts                  # NEW — re-exports public surface
+│   ├── highlightOps.ts           # MOVED from machines-demo/src/lib/highlightOps.ts
+│   ├── graphUtils.ts             # MOVED from machines-demo/src/lib/graphUtils.ts
+│   ├── graphUtils.spec.ts        # MOVED + .test.ts → .spec.ts (colocated next to source per repo convention)
+│   ├── graphIndexes.ts           # MOVED from machines-demo/src/lib/graphIndexes.ts
+│   ├── applyHighlight.ts         # MOVED from machines-demo/src/lib/applyHighlight.ts
+│   ├── applyHighlight.spec.ts    # MOVED + colocated
+│   ├── graphFixtures.spec.ts     # MOVED + colocated
+│   └── fixtures/                 # MOVED — fixture JSONs (graphs/*.json) used by graphFixtures.spec.ts
 └── docs/
     └── graph-highlight-and-breakpoints.md  # MOVED from machines-demo/docs/
 
-tsconfig.build.json           # MODIFY — add reference to packages/visuals
-package.json                  # MODIFY — extend "typecheck" script to include packages/visuals
+tsconfig.build.json           # MODIFY — references packages/visuals/tsconfig.build.json (per repo convention — all entries reference the build variant)
+package.json                  # MODIFY — extend "typecheck" script to include packages/visuals/tsconfig.json
 ```
 
+**Convention notes (verified against `packages/machine`):**
+- **Dual tsconfig** per package: `tsconfig.json` (extends root, `rootDir: ".."`, includes `paths` alias map) for IDE / standalone typecheck; `tsconfig.build.json` (extends local `./tsconfig.json`, `rootDir: "src"`, `composite: true`, `exclude: ["**/*.spec.ts", "dist"]`) for the project-references build.
+- **Tests colocated** as `*.spec.ts` next to source under `src/` (per CLAUDE.md). No top-level `tests/` dir. Fixtures live wherever the colocated spec needs them — under `src/fixtures/` if the test reads from it.
+
 Public API exported from `packages/visuals/src/index.ts`:
 
 ```ts
diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index 24963eb..b2e9210 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -8,4 +8,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
-- Initial extraction from machines-demo: `HighlightOps` / `IndicatorOps` / `RecordedOp` / `NodeKey` / `HighlightClass` / `GraphIndexes` / `GraphHighlight` types, `indexGraph`, `applyHighlight`, `applyIndicator`, `bareIdOf`, `highlightExpand`, `equivalentIds`, `recordingOps`. Rules doc moved into `docs/graph-highlight-and-breakpoints.md`. Closes [#204](https://github.com/mellonis/turing-machine-js/issues/204) (extraction step; recordSnippet follows in a separate PR).
+- Initial extraction from machines-demo (highlight + graph-indexing surface):
+  - Types: `HighlightOps`, `IndicatorOps`, `RecordedOp`, `NodeKey`, `HighlightClass`, `GraphIndexes`, `GraphHighlight`, `TapeSnapshot`.
+  - Functions: `indexGraph`, `applyHighlight`, `applyIndicator`, `bareIdOf`, `highlightExpand`, `equivalentIds`, `recordingOps`.
+  - Rules doc at `docs/graph-highlight-and-breakpoints.md`.
+- Initial `recordSnippet` surface (folded in from step 3 of #204 — first published alpha ships with a complete v1 API ready to feed downstream consumers):
+  - Types: `Snippet` (`{ version: 1, name?, graph, alphabets, frames }`), `Frame` (`{ step, tape, commands?, highlight, log? }`), `RecordSnippetOptions`.
+  - `Frame.commands` carries per-tape `{ movement, read, write }` — both sides of the cell, so players can step forward and backward without recomputing from neighbouring frames.
+  - `recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }) => Snippet` runs `machine.runStepByStep` and captures one frame per iter plus a frame-0 initial-state snapshot.
+  - Composable formatter primitives: `formatCommand(tapeCommand)` + `formatStep(machineState)` — match the engine's edge-label notation (`[reads] → [writes]/[moves]`) so logged steps line up with rendered graph edges.
+
+Closes [#204](https://github.com/mellonis/turing-machine-js/issues/204).

From 7801a33fef2f6c30cf6e1c2780b1fbf58685f064 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 16:38:12 +0300
Subject: [PATCH 094/118] release(visuals): 7.0.0-alpha.6 lockstep catch-up
 publish (#204)

---
 packages/visuals/CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index b2e9210..e7cca0f 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable changes to this package 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).
 
-## [Unreleased]
+## [7.0.0-alpha.6] - 2026-05-30
 
 ### Added
 

From e10c90933e2913014093be1e515addd407aa3de9 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 16:55:53 +0300
Subject: [PATCH 095/118] chore(visuals): add .npmignore to exclude
 src/tsconfig/tsbuildinfo from published tarball

---
 packages/visuals/.npmignore | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 packages/visuals/.npmignore

diff --git a/packages/visuals/.npmignore b/packages/visuals/.npmignore
new file mode 100644
index 0000000..d2b810e
--- /dev/null
+++ b/packages/visuals/.npmignore
@@ -0,0 +1,7 @@
+src/
+jest.config.mjs
+babel.config.js
+tsconfig.json
+tsconfig.build.json
+*.tsbuildinfo
+dist/**/*.js

From 26b1a6ceeea7886610e5d7a33fb26686e10e43ea Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 17:56:28 +0300
Subject: [PATCH 096/118] feat(visuals): add formatStepNotation + formatTape
 primitives (#204)

Verbatim port from machines-demo's format.ts:formatStepNotation +
formatTape. Folds in the richness demo's local formatter had
(wildcard `*='X'`, blank shortcut B, keep-with-concrete-symbol K='X',
erase E, manual-Apply no-prefix path) so the upcoming demo cleanup PR
can drop the local helper and call visuals's primitive directly.

Plan: docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md
---
 .../2026-05-30-visuals-alpha7-formatters.md   | 349 ++++++++++++++++++
 packages/visuals/src/format.spec.ts           |  91 ++++-
 packages/visuals/src/format.ts                |  78 ++++
 packages/visuals/src/index.ts                 |   2 +-
 4 files changed, 518 insertions(+), 2 deletions(-)
 create mode 100644 docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md

diff --git a/docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md b/docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md
new file mode 100644
index 0000000..b44d12e
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md
@@ -0,0 +1,349 @@
+# `@turing-machine-js/visuals` 7.0.0-alpha.6.1 — formatter enhancements
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:executing-plans or superpowers:subagent-driven-development.
+
+**Goal:** Extend visuals's string-formatter surface to cover the richness machines-demo's `format.ts` already provides, so the upcoming demo cleanup PR can drop `format.ts` and call visuals's primitives directly. Pure additive change to visuals.
+
+**Tracks:** Unblocks the format.ts portion of the [machines-demo visuals-cleanup plan](../../../../machines-demo/docs/superpowers/plans/2026-05-30-visuals-cleanup.md). Owns the gap I missed when implementing the alpha.6 formatters (Task 10 of #220) — I designed minimal primitives in a vacuum when demo's `format.ts` was the de facto requirement spec.
+
+**Branch:** `feat/visuals-alpha7-formatters` (off `v7`).
+
+**Architecture:** Add the rich primitive (`formatStepNotation`) + `formatTape` to visuals's existing `format.ts`. alpha.6's `formatStep(m)` and `formatCommand(tapeCommand)` stay untouched (backward-compat for any caller). Mirror demo's `format.ts:formatStepNotation` verbatim — same encoding rules, same multi-tape join, same null-`reads` manual-Apply handling, same `K='X'` / `B` / `E` shortcuts. The demo-side migration in the cleanup PR becomes: drop local `formatStepNotation`, drop local `formatTape`, change two internal imports to consume from `@turing-machine-js/visuals`.
+
+---
+
+## Decisions (locked)
+
+- **Visuals-only bump to `7.0.0-alpha.6.1`.** Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at `7.0.0-alpha.6` — they have no changes; bumping them would create ghost releases (identical tarballs published under a new version). The workspace's lockstep convention exists for coordinated peer-dep widening when engine APIs break; an additive visuals-only release doesn't trigger it. Peer-dep coherence holds: visuals's `@turing-machine-js/machine: ^7.0.0-alpha.6` accepts alpha.6.1+ via semver-prerelease caret, so consumers don't need a coordinated upgrade.
+- **alpha.6 surface stays intact.** `formatStep(m: MachineState): string` and `formatCommand(tapeCommand: TapeCommand): string` remain exactly as published. New primitives are added alongside. No deprecation in alpha.6.1.
+- **New primitive: `formatStepNotation(reads, commands, blanks, matchKinds?)`** — verbatim port of demo's internal helper, now exported. Signature mirrors demo's: `reads: readonly string[] | null` (null = manual Apply), `commands: readonly Command[]` (per-tape), `blanks: readonly string[]` (per-tape blank symbols), `matchKinds?: readonly ('wildcard' | 'literal')[] | null` (per-tape; null = no transition fired).
+- **New primitive: `formatTape(tape: TapeSnapshot)`** — verbatim port of demo's `formatTape`.
+- **Demo migration is NOT in this PR.** That happens in the machines-demo cleanup PR, after alpha.6.1 publishes.
+- **No new `Command` import dependency.** The engine's `Command` type is already in visuals's import surface (used by alpha.6's `formatCommand`). No new public API surface beyond what's strictly needed.
+
+---
+
+## File Structure
+
+```
+packages/visuals/
+├── src/
+│   ├── format.ts         # MODIFY — add formatStepNotation + formatTape; keep alpha.6 fns intact
+│   ├── format.spec.ts    # MODIFY — add test cases for the new primitives
+│   └── index.ts          # MODIFY — export formatStepNotation + formatTape
+├── CHANGELOG.md          # MODIFY — new [7.0.0-alpha.6.1] entry
+└── package.json          # MODIFY — version bump 7.0.0-alpha.6 → 7.0.0-alpha.6.1
+
+package-lock.json         # MODIFY — auto-resync (visuals's lock entry only)
+```
+
+Note: `lerna.json`'s `version` field stays at the engine's `7.0.0-alpha.6` — this release intentionally diverges from lerna's single-version model. Per-package versions are the authoritative source for `lerna publish from-package`; the `lerna.json` version is informational only when `independent` mode isn't set, and is fine to leave stale for this kind of single-package release. (Reconsider if lerna emits a warning at publish time.)
+
+Public API delta after this PR:
+
+```ts
+// Existing (alpha.6) — unchanged
+export function formatCommand(tapeCommand: TapeCommand): string;
+export function formatStep(m: MachineState): string;
+
+// New (alpha.6.1)
+export function formatStepNotation(
+  reads: readonly string[] | null,
+  commands: readonly Command[],
+  blanks: readonly string[],
+  matchKinds?: readonly ('wildcard' | 'literal')[] | null,
+): string;
+export function formatTape(tape: TapeSnapshot): string;
+```
+
+---
+
+## Task 1: Add `formatStepNotation` + `formatTape` to `format.ts`
+
+**Files:** `packages/visuals/src/format.ts`
+
+- [ ] **Step 1: Read demo's `format.ts` as the source spec**
+
+`../machines-demo/src/lib/format.ts:33-84` — the `formatStepNotation` function body + its JSDoc, plus the `formatTape` function. Port both verbatim into visuals.
+
+- [ ] **Step 2: Add to `packages/visuals/src/format.ts`**
+
+Append after the existing `formatStep` / `formatCommand`:
+
+```ts
+import type { Command, TapeSnapshot } from '@turing-machine-js/machine';   // adjust to existing imports
+
+/**
+ * Engine edge-label format — `[reads] → [writes]/[moves]`. Matches
+ * `toMermaid` emit so a logged step's notation lines up byte-for-byte with
+ * the same transition's edge label in the rendered state graph.
+ *
+ * Per-cell encoding:
+ * - Read cell: `'X'` (literal) or `B` (blank, non-wildcard only). Wildcard
+ *   reads render as `*='X'` (showing what `ifOtherSymbol` caught). When
+ *   `matchKinds` is omitted (manual Apply), every position renders as a literal.
+ * - Write cell: `'X'` (literal) | `K='X'` (keep with concrete kept symbol)
+ *   | `K` (keep, no read context) | `E` (erase, write equals blank).
+ * - Move cell: `L` | `R` | `S`.
+ *
+ * Multi-tape: per-tape entries comma-separated inside one outer bracket
+ * per role: `['1','a'] → ['0','b']/[R,L]`.
+ *
+ * Pass `reads === null` for the manual-Apply path (no transition fired) —
+ * output collapses to `[writes]/[moves]`.
+ */
+export function formatStepNotation(
+  reads: readonly string[] | null,
+  commands: readonly Command[],
+  blanks: readonly string[],
+  matchKinds?: readonly ('wildcard' | 'literal')[] | null,
+): string {
+  // VERBATIM port from machines-demo/src/lib/format.ts:formatStepNotation —
+  // see that file for the per-cell encoding rationale. Do NOT alter shape.
+  const writes = commands.map((c, i) => {
+    if (c.symbol === null) {
+      if (reads !== null) {
+        const r = reads[i];
+        if (r !== undefined) return r === blanks[i] ? 'K=B' : `K='${r}'`;
+      }
+      return 'K';
+    }
+    if (c.symbol === blanks[i]) return 'E';
+    return `'${c.symbol}'`;
+  }).join(',');
+  const moves = commands.map((c) => c.movement).join(',');
+  const writesPart = `[${writes}]/[${moves}]`;
+
+  if (reads === null) return writesPart;
+
+  const readsStr = reads.map((r, i) => {
+    if (matchKinds?.[i] === 'wildcard') return `*='${r}'`;
+    return r === blanks[i] ? 'B' : `'${r}'`;
+  }).join(',');
+  return `[${readsStr}] → ${writesPart}`;
+}
+
+/** Inline tape rendering: head bracketed in place. `[<blank>]` is fine —
+ *  user controls the blank glyph. */
+export function formatTape(tape: TapeSnapshot): string {
+  return tape.symbols
+    .map((sym, i) => (i === tape.position ? `[${sym}]` : sym))
+    .join('');
+}
+```
+
+**Verify before writing:** the `Command` type is already imported (it backs alpha.6's `formatCommand`); just add `TapeSnapshot` to the type import. If the existing file uses `c.movement` strings vs symbols, mirror demo exactly — demo treats `c.movement` as a `string` ('L'|'R'|'S') in this context (it comes from `Command` per demo's types, which may differ from engine `TapeCommand`). Read demo's `Command` type definition (`../machines-demo/src/lib/types.ts`) to confirm shape; if demo's `Command` is `{ movement: 'L'|'R'|'S'; symbol: string | null }` (string movement), and visuals's engine `Command` differs, you may need to adapt the port — but DO NOT change the output format.
+
+> **If the engine `Command` shape differs enough that a verbatim port doesn't compile**, raise it as a DONE_WITH_CONCERNS. Two acceptable resolutions: (a) take the formatter's input type as the demo's shape (`{ movement: 'L'|'R'|'S'; symbol: string | null }[]`) instead of engine `Command[]`, since these formatters serve consumers who already have that shape from snippet frames / log lines; (b) keep engine `Command[]` and translate fields at the call site. (a) is likely cleaner — the formatter is a string producer over a fixed shape; coupling it to a specific engine class adds zero value.
+
+- [ ] **Step 3: Typecheck**
+
+```sh
+npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run typecheck
+```
+
+Expected: clean.
+
+---
+
+## Task 2: Add tests for `formatStepNotation` + `formatTape`
+
+**Files:** `packages/visuals/src/format.spec.ts`
+
+- [ ] **Step 1: Add cases to format.spec.ts**
+
+Mirror the encoding rules in tests. Each case asserts the exact output string. Recommended cases (8+ cases):
+
+- Single-tape literal: `formatStepNotation(['a'], [{symbol: 'b', movement: 'R'}], [' '], ['literal'])` → `"['a'] → ['b']/[R]"`
+- Single-tape blank read: `(['  '], [{...}], [' '], ['literal'])` → `[B] → ...` (blank shortcut on read)
+- Single-tape wildcard read: `(['a'], [...], [' '], ['wildcard'])` → `"[*='a'] → ..."` (wildcard marker, NOT `B` shortcut)
+- Single-tape keep with read: `(['a'], [{symbol: null, movement: 'S'}], [' '], ['literal'])` → `"['a'] → [K='a']/[S]"`
+- Single-tape keep blank: same shape with `reads === blank` → `K=B`
+- Single-tape erase: `(['a'], [{symbol: ' ', movement: 'L'}], [' '], ['literal'])` → `"['a'] → [E]/[L]"`
+- Manual-Apply (no reads): `formatStepNotation(null, [{symbol: 'b', movement: 'R'}], [' '], null)` → `"['b']/[R]"` (no `[reads] →` prefix)
+- Multi-tape: `(['a', 'b'], [{...}, {...}], [' ', ' '], ['literal', 'wildcard'])` → `"['a',*='b'] → [...]/[...]"`
+- formatTape: `formatTape({symbols: ['a', 'b', 'c'], position: 1})` → `"a[b]c"`
+- formatTape head at end: `formatTape({symbols: ['a'], position: 0})` → `"[a]"`
+
+- [ ] **Step 2: Run the new tests**
+
+```sh
+npx --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js vitest run packages/visuals/src/format.spec.ts
+```
+
+Expected: all pass.
+
+- [ ] **Step 3: Full verify**
+
+```sh
+npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js test
+npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run typecheck
+npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run lint
+```
+
+All green. Test count grows by N (the cases you added).
+
+---
+
+## Task 3: Wire exports
+
+**Files:** `packages/visuals/src/index.ts`
+
+- [ ] **Step 1: Append exports**
+
+After the existing alpha.6 exports:
+
+```ts
+export { formatCommand, formatStep, formatStepNotation, formatTape } from './format';
+```
+
+(Adjust to merge with the existing `formatCommand` / `formatStep` export line — single line, all four names.)
+
+- [ ] **Step 2: Verify**
+
+Re-run typecheck + a build to confirm `dist/` includes the new symbols:
+
+```sh
+npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run build
+```
+
+Expected: clean, `dist/format.d.ts` exports the new functions, `dist/index.{cjs,mjs,d.ts}` re-export them.
+
+---
+
+## Task 4: Bump visuals + CHANGELOG + commit
+
+**Files:** `packages/visuals/package.json`, `packages/visuals/CHANGELOG.md`, `package-lock.json`.
+
+- [ ] **Step 1: Bump version**
+
+Edit `packages/visuals/package.json`:
+```diff
+-  "version": "7.0.0-alpha.6",
++  "version": "7.0.0-alpha.6.1",
+```
+
+Peer-dep range stays `"@turing-machine-js/machine": "^7.0.0-alpha.6"` — semver-prerelease caret already accepts alpha.6.1+.
+
+Resync `package-lock.json`:
+```sh
+npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js install --package-lock-only
+```
+
+Only the visuals workspace entry in `package-lock.json` should change.
+
+- [ ] **Step 2: Add the CHANGELOG entry**
+
+`packages/visuals/CHANGELOG.md` — add above `[7.0.0-alpha.6]`:
+
+```markdown
+## [7.0.0-alpha.6.1] - 2026-05-30
+
+### Added
+
+- `formatStepNotation(reads, commands, blanks, matchKinds?)` — engine edge-label format primitive, matches `toMermaid` emit byte-for-byte. Per-cell encoding: literal `'X'`, blank shortcut `B`, wildcard `*='X'`, keep-with-concrete-symbol `K='X'`, erase `E`. Multi-tape comma-separated within one outer bracket per role. Pass `reads === null` for the manual-Apply path (no transition fired) — output collapses to `[writes]/[moves]`. Folds in the richness machines-demo's local `format.ts` had so demo can drop the local helper and call visuals's primitive directly.
+- `formatTape(tape)` — inline tape rendering with the head bracketed in place (`a[b]c`).
+
+### Compatibility
+
+- alpha.6's `formatCommand(tapeCommand)` and `formatStep(m)` unchanged. Additive release.
+- Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at `7.0.0-alpha.6` — no functional changes there. Visuals-only release; the workspace's lockstep convention is for coordinated peer-dep widening when engine APIs break, not for additive consumer-package enhancements.
+```
+
+- [ ] **Step 3: Verify, then commit**
+
+`git -C ... status` — should show: `packages/visuals/package.json`, `packages/visuals/CHANGELOG.md`, `package-lock.json`, plus the Task 1-3 source/test/index changes.
+
+Commit in two focused commits for a clean bisect:
+1. `feat(visuals): add formatStepNotation + formatTape primitives (alpha.6.1)` — Task 1-3 source/test/index changes
+2. `release(visuals): 7.0.0-alpha.6.1 — formatter enhancements` — version bump + CHANGELOG + lockfile resync
+
+Or fold into one. Either works.
+
+For a tidy history, commit the work as several focused commits:
+1. `feat(visuals): add formatStepNotation + formatTape primitives (alpha.6.1)`
+2. `test(visuals): cover formatStepNotation + formatTape encoding cases`
+3. `release(visuals): 7.0.0-alpha.6.1 — formatter enhancements`
+
+Or fold into one. Either's fine; per-task commits read cleaner if someone bisects.
+
+- [ ] **Step 4: Push**
+
+```sh
+git -C /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js push -u origin feat/visuals-alpha7-formatters
+```
+
+---
+
+## Task 5: Open PR
+
+- [ ] **Step 1: Open PR against `v7`**
+
+```sh
+gh pr create --repo mellonis/turing-machine-js --base v7 --head feat/visuals-alpha7-formatters \
+  --title "feat(visuals): alpha.6.1 formatter enhancements (formatStepNotation + formatTape)" \
+  --body "$(cat <<'EOF'
+## Summary
+
+alpha.6.1 of \`@turing-machine-js/visuals\`. Folds the richness of machines-demo's local \`format.ts\` into visuals so the upcoming demo cleanup PR can drop the local helper and call visuals's primitives directly.
+
+Pure additive change. alpha.6's \`formatCommand\` / \`formatStep\` unchanged.
+
+## What's new
+
+- **\`formatStepNotation(reads, commands, blanks, matchKinds?)\`** — engine edge-label format primitive matching \`toMermaid\` emit byte-for-byte. Per-cell encoding covers literal \`'X'\`, blank shortcut \`B\`, wildcard \`*='X'\` (showing what \`ifOtherSymbol\` caught), keep-with-concrete-symbol \`K='X'\` / \`K=B\`, erase \`E\`, and the manual-Apply path (\`reads === null\` collapses output to \`[writes]/[moves]\`).
+- **\`formatTape(tape)\`** — inline tape rendering with the head bracketed in place.
+
+## Versioning (visuals-only bump)
+
+Bumps **visuals alone** to \`7.0.0-alpha.6.1\`. Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at \`7.0.0-alpha.6\` — no functional changes there; bumping them would create ghost releases. Peer-dep ranges stay at \`^7.0.0-alpha.6\` (semver-prerelease caret already accepts alpha.6.1+). The workspace's lockstep convention exists for coordinated peer-dep widening when engine APIs break, not for additive consumer-package enhancements.
+
+## Test plan
+
+- [x] \`npm test\` — passes, +N tests in \`format.spec.ts\`.
+- [x] \`npm run typecheck\` — clean.
+- [x] \`npm run lint\` — clean.
+- [x] \`npm run build\` — \`dist/format.d.ts\` exports the new symbols; \`Built @turing-machine-js/visuals Node entries\` confirms Rollup runs cleanly.
+
+## Follow-ups
+
+- Lockstep publish (or visuals-only publish) — \`npx lerna publish from-package --dist-tag next\` from the repo root after merge. Lerna's \`from-package\` mode publishes anything NOT yet on the registry; only visuals will publish.
+- Then the [machines-demo visuals-cleanup PR](https://github.com/mellonis/machines-demo/blob/master/docs/superpowers/plans/2026-05-30-visuals-cleanup.md) becomes a clean drop: deletes \`format.ts\`'s \`formatStepNotation\` + \`formatTape\` and points \`commandsEntry\` / \`tapesEntry\` at visuals.
+
+Per repo convention, this PR targets \`v7\`. CI doesn't run on v7 branches.
+EOF
+)"
+```
+
+---
+
+## Self-review checklist
+
+- [ ] `formatStepNotation` body matches demo's verbatim — same encoding paths, same multi-tape join, same null-`reads` handling.
+- [ ] `formatTape` body matches demo's verbatim.
+- [ ] alpha.6 surface (`formatCommand`, `formatStep`) unchanged.
+- [ ] CHANGELOG entry under `[7.0.0-alpha.6.1]`, dated `2026-05-30`.
+- [ ] package.json at `7.0.0-alpha.6.1`; peer dep unchanged.
+- [ ] No Claude attribution footers in commits.
+- [ ] Tests cover every encoding branch (literal, blank-B, wildcard, keep-with-read, keep-blank, erase, manual-Apply, multi-tape).
+
+---
+
+## After this lands
+
+1. **Publish** — `cd turing-machine-js && npx lerna publish from-package --dist-tag next --yes`. Only visuals publishes (engine + builder + libs are already on the registry at alpha.6, lerna skips them). Same catch-up-publish flow as alpha.6's initial visuals publish.
+2. **Tagging:** **no new GH release** for `v7.0.0-alpha.6.1`. The git tag scheme tracks engine versions; visuals-only releases ship under the existing engine tag (alpha.6 in this case). Optionally edit the `v7.0.0-alpha.6` GH release body to add a short note like "Visuals follow-up: alpha.6.1 adds `formatStepNotation` + `formatTape` — see [packages/visuals/CHANGELOG.md](https://github.com/mellonis/turing-machine-js/blob/v7/packages/visuals/CHANGELOG.md)."
+3. **Resume the machines-demo cleanup PR plan.** With alpha.6.1 published, the cleanup PR additionally:
+   - Bumps the demo's visuals dep to `^7.0.0-alpha.6.1` (via `npm install @turing-machine-js/visuals@next`).
+   - Deletes demo's local `formatStepNotation` (was internal) — call sites in `commandsEntry` switch to importing from `@turing-machine-js/visuals`.
+   - Deletes demo's local `formatTape` export — callers switch to visuals's.
+   - Keeps `tapesEntry`, `commandsEntry`, `CommandsApplication` in demo (LogEntry assembly is demo-specific).
+
+---
+
+## Out of scope
+
+- **Engine bump.** No engine changes in this alpha.
+- **Backwards-compat shims for the alpha.6 formatters.** They stay live, unchanged. Future deprecation, if any, is a separate decision.
+- **GH release for `v7.0.0-alpha.6.1`.** Skipped — tag scheme tracks engine versions, and the engine isn't bumping. Optionally edit the existing `v7.0.0-alpha.6` release body to note the visuals follow-up.
+- **Demo migration.** That's the cleanup PR's job, after this publishes.
diff --git a/packages/visuals/src/format.spec.ts b/packages/visuals/src/format.spec.ts
index c4f9d87..6274858 100644
--- a/packages/visuals/src/format.spec.ts
+++ b/packages/visuals/src/format.spec.ts
@@ -10,7 +10,7 @@ import {
   movements,
   symbolCommands,
 } from '@turing-machine-js/machine';
-import { formatCommand, formatStep } from './format';
+import { formatCommand, formatStep, formatStepNotation, formatTape, type StepCommand } from './format';
 
 describe('formatCommand', () => {
   it('formats a literal symbol write + right move', () => {
@@ -98,3 +98,92 @@ describe('formatStep', () => {
     expect(formatStep(m)).toBe("['a','x'] → ['b',K]/[R,L]");
   });
 });
+
+describe('formatStepNotation', () => {
+  const BLANK = [' '];
+
+  it('formats a literal read + literal write', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(formatStepNotation(['a'], commands, BLANK, ['literal'])).toBe("['a'] → ['b']/[R]");
+  });
+
+  it('renders blank read as B (non-wildcard)', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(formatStepNotation([' '], commands, BLANK, ['literal'])).toBe("[B] → ['b']/[R]");
+  });
+
+  it('renders wildcard read as *=\'X\' (NOT blank-shortcut even when read is blank)', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(formatStepNotation([' '], commands, BLANK, ['wildcard'])).toBe("[*=' '] → ['b']/[R]");
+  });
+
+  it("encodes keep as K='X' when read context is available", () => {
+    const commands: StepCommand[] = [{ symbol: null, movement: 'S' }];
+    expect(formatStepNotation(['a'], commands, BLANK, ['literal'])).toBe("['a'] → [K='a']/[S]");
+  });
+
+  it('encodes keep as K=B when read is the blank symbol', () => {
+    const commands: StepCommand[] = [{ symbol: null, movement: 'S' }];
+    expect(formatStepNotation([' '], commands, BLANK, ['literal'])).toBe('[B] → [K=B]/[S]');
+  });
+
+  it('encodes erase as E when write equals blank', () => {
+    const commands: StepCommand[] = [{ symbol: ' ', movement: 'L' }];
+    expect(formatStepNotation(['a'], commands, BLANK, ['literal'])).toBe("['a'] → [E]/[L]");
+  });
+
+  it('manual Apply (reads === null) collapses to [writes]/[moves] with no prefix', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(formatStepNotation(null, commands, BLANK, null)).toBe("['b']/[R]");
+  });
+
+  it('manual Apply with keep renders bare K (no read context)', () => {
+    const commands: StepCommand[] = [{ symbol: null, movement: 'S' }];
+    expect(formatStepNotation(null, commands, BLANK, null)).toBe('[K]/[S]');
+  });
+
+  it('multi-tape: per-role comma-separated entries inside one outer bracket', () => {
+    const commands: StepCommand[] = [
+      { symbol: '0', movement: 'R' },
+      { symbol: 'b', movement: 'L' },
+    ];
+    expect(formatStepNotation(['1', 'a'], commands, [' ', ' '], ['literal', 'literal']))
+      .toBe("['1','a'] → ['0','b']/[R,L]");
+  });
+
+  it('multi-tape mixed wildcard + literal reads', () => {
+    const commands: StepCommand[] = [
+      { symbol: 'b', movement: 'R' },
+      { symbol: 'y', movement: 'S' },
+    ];
+    expect(formatStepNotation(['a', 'x'], commands, [' ', ' '], ['wildcard', 'literal']))
+      .toBe("[*='a','x'] → ['b','y']/[R,S]");
+  });
+
+  it('omitted matchKinds (undefined) renders reads as literals', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(formatStepNotation(['a'], commands, BLANK)).toBe("['a'] → ['b']/[R]");
+  });
+});
+
+describe('formatTape', () => {
+  it('brackets the head cell in place', () => {
+    expect(formatTape({ symbols: ['a', 'b', 'c'], position: 1 })).toBe('a[b]c');
+  });
+
+  it('brackets head at start', () => {
+    expect(formatTape({ symbols: ['a', 'b'], position: 0 })).toBe('[a]b');
+  });
+
+  it('brackets head at end', () => {
+    expect(formatTape({ symbols: ['a', 'b'], position: 1 })).toBe('a[b]');
+  });
+
+  it('single-cell tape', () => {
+    expect(formatTape({ symbols: ['x'], position: 0 })).toBe('[x]');
+  });
+
+  it('passes the blank glyph through literally', () => {
+    expect(formatTape({ symbols: [' ', 'a', ' '], position: 0 })).toBe('[ ]a ');
+  });
+});
diff --git a/packages/visuals/src/format.ts b/packages/visuals/src/format.ts
index a9ae8b2..1944be4 100644
--- a/packages/visuals/src/format.ts
+++ b/packages/visuals/src/format.ts
@@ -1,4 +1,17 @@
 import { movements, symbolCommands, type MachineState, type TapeCommand } from '@turing-machine-js/machine';
+import type { TapeSnapshot } from './types';
+
+/**
+ * Plain per-tape command shape consumed by `formatStepNotation`. Distinct
+ * from the engine's `TapeCommand` class: `symbol === null` means "keep
+ * current" (the resolved symbol equals what was already under the head),
+ * `movement` is the role letter (not an engine symbol). Matches the shape
+ * machines-demo exposes from its worker boundary.
+ */
+export type StepCommand = {
+  movement: 'L' | 'R' | 'S';
+  symbol: string | null;
+};
 
 export const MOVEMENT_LETTER = new Map<symbol, 'L' | 'R' | 'S'>([
   [movements.left, 'L'],
@@ -49,3 +62,68 @@ export function formatStep(m: MachineState): string {
 
   return `[${reads}] → [${writes}]/[${moves}]`;
 }
+
+/**
+ * Engine edge-label format — `[reads] → [writes]/[moves]`. Matches
+ * `toMermaid` emit byte-for-byte so a logged step's notation lines up with
+ * the same transition's edge label in the rendered state graph.
+ *
+ * Per-cell encoding:
+ * - Read cell: `'X'` (literal) | `B` (blank, NON-wildcard only) | `*='X'`
+ *   (wildcard — shows what `ifOtherSymbol` caught; the `B` shortcut is
+ *   suppressed for wildcards so the matched literal is always visible).
+ * - Write cell: `'X'` (literal) | `K='X'` (keep, with concrete read
+ *   appended) | `K=B` (keep, read was blank) | `K` (keep, no read context
+ *   — only when `reads === null`) | `E` (erase, write equals blank).
+ * - Move cell: `L` | `R` | `S`.
+ *
+ * Multi-tape: per-tape entries comma-separated inside one outer bracket
+ * per role — `['1','a'] → ['0','b']/[R,L]`.
+ *
+ * Pass `reads === null` for the manual-Apply path (no transition fired):
+ * output collapses to `[writes]/[moves]` and `K` renders without read
+ * context. Pass `matchKinds === null`/omit when no transition fired:
+ * every position renders as a literal (no wildcard markers).
+ */
+export function formatStepNotation(
+  reads: readonly string[] | null,
+  commands: readonly StepCommand[],
+  blanks: readonly string[],
+  matchKinds?: readonly ('wildcard' | 'literal')[] | null,
+): string {
+  const writes = commands
+    .map((c, i) => {
+      if (c.symbol === null) {
+        if (reads !== null) {
+          const r = reads[i];
+          if (r !== undefined) return r === blanks[i] ? 'K=B' : `K='${r}'`;
+        }
+        return 'K';
+      }
+      if (c.symbol === blanks[i]) return 'E';
+      return `'${c.symbol}'`;
+    })
+    .join(',');
+  const moves = commands.map((c) => c.movement).join(',');
+  const writesPart = `[${writes}]/[${moves}]`;
+
+  if (reads === null) return writesPart;
+
+  const readsStr = reads
+    .map((r, i) => {
+      if (matchKinds?.[i] === 'wildcard') return `*='${r}'`;
+      return r === blanks[i] ? 'B' : `'${r}'`;
+    })
+    .join(',');
+  return `[${readsStr}] → ${writesPart}`;
+}
+
+/** Inline tape rendering with the head bracketed in place (`a[b]c`).
+ *  No UI substitution — the user controls the blank glyph. `[<blank>]`
+ *  may render an invisible space if blank is `' '`; that's the chosen
+ *  symbol, not a bug. */
+export function formatTape(tape: TapeSnapshot): string {
+  return tape.symbols
+    .map((sym, i) => (i === tape.position ? `[${sym}]` : sym))
+    .join('');
+}
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 1bdcc57..627118e 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -6,5 +6,5 @@ export type { GraphIndexes } from './graphIndexes';
 export { indexGraph } from './graphIndexes';
 export type { GraphHighlight, TapeSnapshot, Frame, Snippet } from './types';
 export { applyHighlight, applyIndicator } from './applyHighlight';
-export { formatCommand, formatStep } from './format';
+export { formatCommand, formatStep, formatStepNotation, formatTape, type StepCommand } from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';

From 90e2bfd1a14e32eed79683ccfc87d3e414977870 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 17:56:28 +0300
Subject: [PATCH 097/118] =?UTF-8?q?release(visuals):=207.0.0-alpha.6.1=20?=
 =?UTF-8?q?=E2=80=94=20formatter=20enhancements?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Visuals-only follow-up patch on alpha.6. Engine + builder + libraries
stay at alpha.6 (no functional changes there). Peer dep stays
^7.0.0-alpha.6 — semver-prerelease caret accepts alpha.6.1+.
---
 package-lock.json             |  2 +-
 packages/visuals/CHANGELOG.md | 14 ++++++++++++++
 packages/visuals/package.json |  2 +-
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 5e519b1..6b81efc 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10701,7 +10701,7 @@
     },
     "packages/visuals": {
       "name": "@turing-machine-js/visuals",
-      "version": "7.0.0-alpha.6",
+      "version": "7.0.0-alpha.6.1",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index e7cca0f..ab36dc0 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to this package 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.1] - 2026-05-30
+
+### Added
+
+- `formatStepNotation(reads, commands, blanks, matchKinds?)` — engine edge-label format primitive, matches `toMermaid` emit byte-for-byte. Per-cell encoding: literal `'X'`, blank shortcut `B`, wildcard `*='X'` (shows what `ifOtherSymbol` caught), keep-with-concrete-symbol `K='X'` / `K=B`, erase `E`. Multi-tape comma-separated within one outer bracket per role. Pass `reads === null` for the manual-Apply path (no transition fired) — output collapses to `[writes]/[moves]`. Folds in the richness machines-demo's local `format.ts` had so demo can drop the local helper and call visuals's primitive directly.
+- `formatTape(tape)` — inline tape rendering with the head bracketed in place (`a[b]c`).
+- `StepCommand` — plain per-tape command shape (`{ movement: 'L' | 'R' | 'S'; symbol: string | null }`) consumed by `formatStepNotation`. Distinct from the engine's `TapeCommand` class; matches the shape machines-demo's worker boundary exposes.
+
+### Compatibility
+
+- alpha.6's `formatCommand(tapeCommand)` and `formatStep(m)` unchanged. Additive release.
+- Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at `7.0.0-alpha.6` — no changes there. Visuals-only follow-up patch; the workspace's lockstep convention is for coordinated peer-dep widening when engine APIs break, not for additive consumer-package enhancements.
+- Peer dep `@turing-machine-js/machine: ^7.0.0-alpha.6` unchanged (semver-prerelease caret already accepts `alpha.6.1`).
+
 ## [7.0.0-alpha.6] - 2026-05-30
 
 ### Added
diff --git a/packages/visuals/package.json b/packages/visuals/package.json
index af0149c..4d1d719 100644
--- a/packages/visuals/package.json
+++ b/packages/visuals/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/visuals",
-  "version": "7.0.0-alpha.6",
+  "version": "7.0.0-alpha.6.1",
   "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
   "engines": {
     "npm": ">=7.0.0"

From 93809922abddb7d2adcfbd2d5c5ffa5ff640ab07 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 18:04:39 +0300
Subject: [PATCH 098/118] feat(visuals): add tokenizeStep +
 ReadToken/WriteToken/StepTokens for renderer-agnostic step rendering (#204)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Structured-token output of one step (reads/writes/moves as discriminated
unions) so consumers wanting custom rendering — HTML spans with CSS
classes, ANSI colors, alternative vocabulary, clickable cells — walk the
tokens themselves instead of re-implementing the per-cell encoding.

formatStepNotation refactored to be a thin string renderer over
tokenizeStep — output byte-identical (all 24 existing format tests
unchanged + 10 new tokenizer tests).

All folded into the in-flight alpha.6.1 PR per design discussion.
---
 packages/visuals/CHANGELOG.md       |   3 +-
 packages/visuals/src/format.spec.ts | 103 +++++++++++++++++-
 packages/visuals/src/format.ts      | 155 ++++++++++++++++++++++------
 packages/visuals/src/index.ts       |  12 ++-
 4 files changed, 240 insertions(+), 33 deletions(-)

diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index ab36dc0..fa65f08 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -9,8 +9,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 ### Added
 
 - `formatStepNotation(reads, commands, blanks, matchKinds?)` — engine edge-label format primitive, matches `toMermaid` emit byte-for-byte. Per-cell encoding: literal `'X'`, blank shortcut `B`, wildcard `*='X'` (shows what `ifOtherSymbol` caught), keep-with-concrete-symbol `K='X'` / `K=B`, erase `E`. Multi-tape comma-separated within one outer bracket per role. Pass `reads === null` for the manual-Apply path (no transition fired) — output collapses to `[writes]/[moves]`. Folds in the richness machines-demo's local `format.ts` had so demo can drop the local helper and call visuals's primitive directly.
+- `tokenizeStep(reads, commands, blanks, matchKinds?)` + `ReadToken` / `WriteToken` / `StepTokens` types — renderer-agnostic structured form of one step. Same input contract as `formatStepNotation`; returns discriminated-union tokens per cell (`{ kind: 'literal' | 'blank' | 'wildcard', ... }` for reads, `{ kind: 'literal' | 'erase' | 'keep', ... }` for writes). Consumers wanting custom rendering — HTML spans with CSS classes for syntax highlighting, ANSI-colored terminal output, alternative move vocabulary, clickable cells — walk the tokens themselves. `formatStepNotation` is refactored to be a thin string renderer over `tokenizeStep` (output byte-identical).
 - `formatTape(tape)` — inline tape rendering with the head bracketed in place (`a[b]c`).
-- `StepCommand` — plain per-tape command shape (`{ movement: 'L' | 'R' | 'S'; symbol: string | null }`) consumed by `formatStepNotation`. Distinct from the engine's `TapeCommand` class; matches the shape machines-demo's worker boundary exposes.
+- `StepCommand` — plain per-tape command shape (`{ movement: 'L' | 'R' | 'S'; symbol: string | null }`) consumed by `formatStepNotation` and `tokenizeStep`. Distinct from the engine's `TapeCommand` class; matches the shape machines-demo's worker boundary exposes.
 
 ### Compatibility
 
diff --git a/packages/visuals/src/format.spec.ts b/packages/visuals/src/format.spec.ts
index 6274858..e16640a 100644
--- a/packages/visuals/src/format.spec.ts
+++ b/packages/visuals/src/format.spec.ts
@@ -10,7 +10,14 @@ import {
   movements,
   symbolCommands,
 } from '@turing-machine-js/machine';
-import { formatCommand, formatStep, formatStepNotation, formatTape, type StepCommand } from './format';
+import {
+  formatCommand,
+  formatStep,
+  formatStepNotation,
+  formatTape,
+  tokenizeStep,
+  type StepCommand,
+} from './format';
 
 describe('formatCommand', () => {
   it('formats a literal symbol write + right move', () => {
@@ -166,6 +173,100 @@ describe('formatStepNotation', () => {
   });
 });
 
+describe('tokenizeStep', () => {
+  const BLANK = [' '];
+
+  it('literal read + literal write', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(tokenizeStep(['a'], commands, BLANK, ['literal'])).toEqual({
+      reads: [{ kind: 'literal', symbol: 'a' }],
+      writes: [{ kind: 'literal', symbol: 'b' }],
+      moves: ['R'],
+    });
+  });
+
+  it('blank read (non-wildcard) tokenizes to { kind: "blank" }', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(tokenizeStep([' '], commands, BLANK, ['literal']).reads).toEqual([
+      { kind: 'blank' },
+    ]);
+  });
+
+  it('wildcard read preserves literal symbol (no blank shortcut)', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(tokenizeStep([' '], commands, BLANK, ['wildcard']).reads).toEqual([
+      { kind: 'wildcard', symbol: ' ' },
+    ]);
+  });
+
+  it('keep write with read context (non-blank read)', () => {
+    const commands: StepCommand[] = [{ symbol: null, movement: 'S' }];
+    expect(tokenizeStep(['a'], commands, BLANK, ['literal']).writes).toEqual([
+      { kind: 'keep', readContext: { symbol: 'a', isBlank: false } },
+    ]);
+  });
+
+  it('keep write with blank read flags isBlank: true', () => {
+    const commands: StepCommand[] = [{ symbol: null, movement: 'S' }];
+    expect(tokenizeStep([' '], commands, BLANK, ['literal']).writes).toEqual([
+      { kind: 'keep', readContext: { symbol: ' ', isBlank: true } },
+    ]);
+  });
+
+  it('erase tokenizes as { kind: "erase" } (write equals blank)', () => {
+    const commands: StepCommand[] = [{ symbol: ' ', movement: 'L' }];
+    expect(tokenizeStep(['a'], commands, BLANK, ['literal']).writes).toEqual([
+      { kind: 'erase' },
+    ]);
+  });
+
+  it('manual Apply (reads === null): reads is null, keeps carry no readContext', () => {
+    const commands: StepCommand[] = [{ symbol: null, movement: 'S' }];
+    const tokens = tokenizeStep(null, commands, BLANK, null);
+    expect(tokens.reads).toBeNull();
+    expect(tokens.writes).toEqual([{ kind: 'keep' }]);
+  });
+
+  it('omitted matchKinds treats every read as literal (no wildcards)', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    expect(tokenizeStep(['a'], commands, BLANK).reads).toEqual([
+      { kind: 'literal', symbol: 'a' },
+    ]);
+  });
+
+  it('multi-tape arrays line up per index across reads/writes/moves', () => {
+    const commands: StepCommand[] = [
+      { symbol: 'b', movement: 'R' },
+      { symbol: null, movement: 'S' },
+      { symbol: ' ', movement: 'L' },
+    ];
+    expect(tokenizeStep(['a', 'x', ' '], commands, [' ', ' ', ' '], ['literal', 'wildcard', 'literal'])).toEqual({
+      reads: [
+        { kind: 'literal', symbol: 'a' },
+        { kind: 'wildcard', symbol: 'x' },
+        { kind: 'blank' },
+      ],
+      writes: [
+        { kind: 'literal', symbol: 'b' },
+        { kind: 'keep', readContext: { symbol: 'x', isBlank: false } },
+        { kind: 'erase' },
+      ],
+      moves: ['R', 'S', 'L'],
+    });
+  });
+
+  it('formatStepNotation output equals manual render of tokens (consistency invariant)', () => {
+    const commands: StepCommand[] = [{ symbol: 'b', movement: 'R' }];
+    const tokens = tokenizeStep(['a'], commands, BLANK, ['literal']);
+    // Sanity: the token-based public API and the string-based public API
+    // describe the same step. If this breaks, formatStepNotation drifted
+    // from tokenizeStep.
+    expect(tokens.writes).toHaveLength(1);
+    expect(tokens.reads).toHaveLength(1);
+    expect(formatStepNotation(['a'], commands, BLANK, ['literal'])).toBe("['a'] → ['b']/[R]");
+  });
+});
+
 describe('formatTape', () => {
   it('brackets the head cell in place', () => {
     expect(formatTape({ symbols: ['a', 'b', 'c'], position: 1 })).toBe('a[b]c');
diff --git a/packages/visuals/src/format.ts b/packages/visuals/src/format.ts
index 1944be4..343a7f0 100644
--- a/packages/visuals/src/format.ts
+++ b/packages/visuals/src/format.ts
@@ -63,12 +63,125 @@ export function formatStep(m: MachineState): string {
   return `[${reads}] → [${writes}]/[${moves}]`;
 }
 
+/**
+ * Per-tape read-cell token. Discriminated union for renderer-agnostic
+ * consumption — UIs map each variant to their own presentation (plain
+ * string via `formatStepNotation`, HTML span with CSS class, ANSI color,
+ * clickable token, etc.). `formatStepNotation` is the default string
+ * renderer over these tokens.
+ *
+ * - `literal` — the engine matched this exact symbol non-wildcard.
+ * - `blank` — the matched symbol is the tape's blank glyph; renderers
+ *   commonly want a `B`-style shortcut instead of `' '`.
+ * - `wildcard` — the engine matched via `ifOtherSymbol`. The literal
+ *   `symbol` is preserved so renderers can show what the catch-all
+ *   actually caught (a blank-shortcut would obscure it).
+ */
+export type ReadToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'blank' }
+  | { kind: 'wildcard'; symbol: string };
+
+/**
+ * Per-tape write-cell token.
+ *
+ * - `literal` — engine wrote this exact symbol; not a blank, not a keep.
+ * - `erase` — engine wrote the tape's blank glyph; rendered as `E` by
+ *   `formatStepNotation` but structurally distinct from a generic blank
+ *   write so renderers can style "erase" differently from "write blank as
+ *   the next interesting symbol."
+ * - `keep` — engine left the cell unchanged (`command.symbol === null`).
+ *   `readContext` carries the kept symbol when caller supplied `reads`;
+ *   `isBlank` flags whether the kept symbol equals the tape's blank glyph.
+ *   No `readContext` means manual-Apply path (no transition fired, no
+ *   per-tape read available).
+ */
+export type WriteToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'erase' }
+  | { kind: 'keep'; readContext?: { symbol: string; isBlank: boolean } };
+
+/**
+ * Structured-token representation of one step. `formatStepNotation` is the
+ * default string renderer over this shape; consumers wanting custom
+ * rendering (HTML spans, alternative vocabulary, clickable cells, ANSI
+ * colors) call `tokenizeStep` and walk the tokens themselves.
+ *
+ * `reads === null` denotes the manual-Apply path (no transition fired);
+ * all read-side encoding is suppressed and `keep` writes carry no
+ * `readContext`.
+ */
+export type StepTokens = {
+  reads: readonly ReadToken[] | null;
+  writes: readonly WriteToken[];
+  moves: readonly ('L' | 'R' | 'S')[];
+};
+
+/**
+ * Tokenize one step's per-tape data into renderer-agnostic structured
+ * form. Same input contract as `formatStepNotation` — same engine
+ * vocabulary, same null-`reads` manual-Apply handling, same wildcard
+ * suppression of the blank shortcut. Use this when you need to render the
+ * step in a non-string medium (HTML, terminal escape codes, JSON for
+ * embeds) or just want different syntax than the default string output.
+ */
+export function tokenizeStep(
+  reads: readonly string[] | null,
+  commands: readonly StepCommand[],
+  blanks: readonly string[],
+  matchKinds?: readonly ('wildcard' | 'literal')[] | null,
+): StepTokens {
+  const writes: WriteToken[] = commands.map((c, i) => {
+    if (c.symbol === null) {
+      if (reads !== null) {
+        const r = reads[i];
+        if (r !== undefined) {
+          return { kind: 'keep', readContext: { symbol: r, isBlank: r === blanks[i] } };
+        }
+      }
+      return { kind: 'keep' };
+    }
+    if (c.symbol === blanks[i]) return { kind: 'erase' };
+    return { kind: 'literal', symbol: c.symbol };
+  });
+
+  const moves = commands.map((c) => c.movement);
+
+  if (reads === null) {
+    return { reads: null, writes, moves };
+  }
+
+  const readTokens: ReadToken[] = reads.map((r, i) => {
+    if (matchKinds?.[i] === 'wildcard') return { kind: 'wildcard', symbol: r };
+    if (r === blanks[i]) return { kind: 'blank' };
+    return { kind: 'literal', symbol: r };
+  });
+
+  return { reads: readTokens, writes, moves };
+}
+
+function renderReadToken(t: ReadToken): string {
+  if (t.kind === 'wildcard') return `*='${t.symbol}'`;
+  if (t.kind === 'blank') return 'B';
+  return `'${t.symbol}'`;
+}
+
+function renderWriteToken(t: WriteToken): string {
+  if (t.kind === 'erase') return 'E';
+  if (t.kind === 'literal') return `'${t.symbol}'`;
+  if (!t.readContext) return 'K';
+  if (t.readContext.isBlank) return 'K=B';
+  return `K='${t.readContext.symbol}'`;
+}
+
 /**
  * Engine edge-label format — `[reads] → [writes]/[moves]`. Matches
  * `toMermaid` emit byte-for-byte so a logged step's notation lines up with
- * the same transition's edge label in the rendered state graph.
+ * the same transition's edge label in the rendered state graph. Thin
+ * string renderer over `tokenizeStep`; see that function's docstring +
+ * `StepTokens` for the structured form most UIs should prefer.
  *
- * Per-cell encoding:
+ * Per-cell rendering:
  * - Read cell: `'X'` (literal) | `B` (blank, NON-wildcard only) | `*='X'`
  *   (wildcard — shows what `ifOtherSymbol` caught; the `B` shortcut is
  *   suppressed for wildcards so the matched literal is always visible).
@@ -80,10 +193,10 @@ export function formatStep(m: MachineState): string {
  * Multi-tape: per-tape entries comma-separated inside one outer bracket
  * per role — `['1','a'] → ['0','b']/[R,L]`.
  *
- * Pass `reads === null` for the manual-Apply path (no transition fired):
- * output collapses to `[writes]/[moves]` and `K` renders without read
- * context. Pass `matchKinds === null`/omit when no transition fired:
- * every position renders as a literal (no wildcard markers).
+ * Pass `reads === null` for the manual-Apply path: output collapses to
+ * `[writes]/[moves]` and `K` renders without read context. Pass
+ * `matchKinds === null`/omit when no transition fired: every position
+ * renders as a literal (no wildcard markers).
  */
 export function formatStepNotation(
   reads: readonly string[] | null,
@@ -91,30 +204,12 @@ export function formatStepNotation(
   blanks: readonly string[],
   matchKinds?: readonly ('wildcard' | 'literal')[] | null,
 ): string {
-  const writes = commands
-    .map((c, i) => {
-      if (c.symbol === null) {
-        if (reads !== null) {
-          const r = reads[i];
-          if (r !== undefined) return r === blanks[i] ? 'K=B' : `K='${r}'`;
-        }
-        return 'K';
-      }
-      if (c.symbol === blanks[i]) return 'E';
-      return `'${c.symbol}'`;
-    })
-    .join(',');
-  const moves = commands.map((c) => c.movement).join(',');
-  const writesPart = `[${writes}]/[${moves}]`;
-
-  if (reads === null) return writesPart;
-
-  const readsStr = reads
-    .map((r, i) => {
-      if (matchKinds?.[i] === 'wildcard') return `*='${r}'`;
-      return r === blanks[i] ? 'B' : `'${r}'`;
-    })
-    .join(',');
+  const tokens = tokenizeStep(reads, commands, blanks, matchKinds);
+  const writesStr = tokens.writes.map(renderWriteToken).join(',');
+  const movesStr = tokens.moves.join(',');
+  const writesPart = `[${writesStr}]/[${movesStr}]`;
+  if (tokens.reads === null) return writesPart;
+  const readsStr = tokens.reads.map(renderReadToken).join(',');
   return `[${readsStr}] → ${writesPart}`;
 }
 
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 627118e..d142b27 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -6,5 +6,15 @@ export type { GraphIndexes } from './graphIndexes';
 export { indexGraph } from './graphIndexes';
 export type { GraphHighlight, TapeSnapshot, Frame, Snippet } from './types';
 export { applyHighlight, applyIndicator } from './applyHighlight';
-export { formatCommand, formatStep, formatStepNotation, formatTape, type StepCommand } from './format';
+export {
+  formatCommand,
+  formatStep,
+  formatStepNotation,
+  formatTape,
+  tokenizeStep,
+  type StepCommand,
+  type ReadToken,
+  type WriteToken,
+  type StepTokens,
+} from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';

From 1d882f3d0bfc459455c0894ba2f76d1602f6ddb4 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 18:11:13 +0300
Subject: [PATCH 099/118] docs(visuals): update alpha.6.1 plan to reflect
 tokenizer fold + final design (#204)

---
 .../2026-05-30-visuals-alpha7-formatters.md   | 359 +++++++++++-------
 1 file changed, 222 insertions(+), 137 deletions(-)

diff --git a/docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md b/docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md
index b44d12e..c777213 100644
--- a/docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md
+++ b/docs/superpowers/plans/2026-05-30-visuals-alpha7-formatters.md
@@ -2,24 +2,31 @@
 
 > **For agentic workers:** REQUIRED SUB-SKILL: superpowers:executing-plans or superpowers:subagent-driven-development.
 
-**Goal:** Extend visuals's string-formatter surface to cover the richness machines-demo's `format.ts` already provides, so the upcoming demo cleanup PR can drop `format.ts` and call visuals's primitives directly. Pure additive change to visuals.
+**Goal:** Extend visuals's formatter surface so it (a) covers the richness machines-demo's `format.ts` already provides — the upcoming demo cleanup PR can drop `format.ts` and call visuals's primitives directly — AND (b) ships a renderer-agnostic structured-token surface so UIs beyond the demo (article embeds, snippet panels, terminal tools) can render the same per-step data in their own format without re-implementing the per-cell encoding logic. Pure additive change to visuals.
 
-**Tracks:** Unblocks the format.ts portion of the [machines-demo visuals-cleanup plan](../../../../machines-demo/docs/superpowers/plans/2026-05-30-visuals-cleanup.md). Owns the gap I missed when implementing the alpha.6 formatters (Task 10 of #220) — I designed minimal primitives in a vacuum when demo's `format.ts` was the de facto requirement spec.
+**Tracks:** Unblocks the `format.ts` portion of the [machines-demo visuals-cleanup plan](../../../../machines-demo/docs/superpowers/plans/2026-05-30-visuals-cleanup.md). Owns two gaps I missed when implementing the alpha.6 formatters (Task 10 of #220):
+1. I designed minimal primitives in a vacuum when demo's `format.ts` was the de facto requirement spec.
+2. I made `formatStepNotation`-equivalent monolithic (returns one specific string format), so UIs wanting different rendering had to re-implement the per-cell logic from scratch. The `tokenizeStep` + `ReadToken`/`WriteToken` surface fixes that — string rendering is now ONE of many possible presentations.
 
-**Branch:** `feat/visuals-alpha7-formatters` (off `v7`).
+**Branch:** `feat/visuals-alpha7-formatters` (off `v7`). Branch name reflects the initial alpha.7 draft; the version shipped is `7.0.0-alpha.6.1` after a mid-draft rename. Branch identifier doesn't matter; the version that ships is what counts.
 
-**Architecture:** Add the rich primitive (`formatStepNotation`) + `formatTape` to visuals's existing `format.ts`. alpha.6's `formatStep(m)` and `formatCommand(tapeCommand)` stay untouched (backward-compat for any caller). Mirror demo's `format.ts:formatStepNotation` verbatim — same encoding rules, same multi-tape join, same null-`reads` manual-Apply handling, same `K='X'` / `B` / `E` shortcuts. The demo-side migration in the cleanup PR becomes: drop local `formatStepNotation`, drop local `formatTape`, change two internal imports to consume from `@turing-machine-js/visuals`.
+**Architecture:** `tokenizeStep` is the primary primitive — takes `(reads, commands, blanks, matchKinds?)` and returns `StepTokens` (per-tape discriminated-union tokens for reads/writes/moves). `formatStepNotation` is a thin string renderer that consumes `tokenizeStep`'s output and joins it with the engine edge-label vocabulary (`[reads] → [writes]/[moves]`). UIs wanting different presentations call `tokenizeStep` and walk tokens themselves. alpha.6's `formatStep(m)` and `formatCommand(tapeCommand)` stay untouched (backward-compat for any caller). Mirror demo's `format.ts:formatStepNotation` byte-for-byte at the rendering layer — same encoding rules, same multi-tape join, same null-`reads` manual-Apply handling, same `K='X'` / `B` / `E` shortcuts. The demo-side migration in the cleanup PR becomes: drop local `formatStepNotation`, drop local `formatTape`, change two internal imports to consume from `@turing-machine-js/visuals`.
 
 ---
 
 ## Decisions (locked)
 
 - **Visuals-only bump to `7.0.0-alpha.6.1`.** Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at `7.0.0-alpha.6` — they have no changes; bumping them would create ghost releases (identical tarballs published under a new version). The workspace's lockstep convention exists for coordinated peer-dep widening when engine APIs break; an additive visuals-only release doesn't trigger it. Peer-dep coherence holds: visuals's `@turing-machine-js/machine: ^7.0.0-alpha.6` accepts alpha.6.1+ via semver-prerelease caret, so consumers don't need a coordinated upgrade.
+- **Version name `alpha.6.1` (not `alpha.7`).** Communicates "additive follow-up patch on alpha.6," not "new alpha milestone." Reserves `alpha.7` for the next real engine bump. Semver ordering is correct (`alpha.6 < alpha.6.1 < alpha.7`) and caret ranges `^7.0.0-alpha.6` accept it.
 - **alpha.6 surface stays intact.** `formatStep(m: MachineState): string` and `formatCommand(tapeCommand: TapeCommand): string` remain exactly as published. New primitives are added alongside. No deprecation in alpha.6.1.
-- **New primitive: `formatStepNotation(reads, commands, blanks, matchKinds?)`** — verbatim port of demo's internal helper, now exported. Signature mirrors demo's: `reads: readonly string[] | null` (null = manual Apply), `commands: readonly Command[]` (per-tape), `blanks: readonly string[]` (per-tape blank symbols), `matchKinds?: readonly ('wildcard' | 'literal')[] | null` (per-tape; null = no transition fired).
-- **New primitive: `formatTape(tape: TapeSnapshot)`** — verbatim port of demo's `formatTape`.
+- **Primary primitive: `tokenizeStep(reads, commands, blanks, matchKinds?)`** — renderer-agnostic structured-token output. Returns `StepTokens = { reads: ReadToken[] | null; writes: WriteToken[]; moves: ('L'|'R'|'S')[] }` where:
+  - `ReadToken = { kind: 'literal'; symbol: string } | { kind: 'blank' } | { kind: 'wildcard'; symbol: string }`
+  - `WriteToken = { kind: 'literal'; symbol: string } | { kind: 'erase' } | { kind: 'keep'; readContext?: { symbol: string; isBlank: boolean } }`
+  UIs that want non-string rendering (HTML spans with CSS classes, ANSI escape codes, clickable cells, alternative move vocabulary, JSON for embeds) walk the tokens themselves. Same input contract as `formatStepNotation` — same engine vocabulary, same null-`reads` manual-Apply handling, same wildcard suppression of the blank shortcut.
+- **`formatStepNotation` is now a thin string renderer over `tokenizeStep`.** Output is byte-identical to a from-scratch port of demo's `formatStepNotation` (verified — all 24 existing format-spec cases pass unchanged after the refactor). String rendering is one of many possible presentations of the same structured data.
+- **New primitive: `formatTape(tape: TapeSnapshot)`** — verbatim port of demo's `formatTape`. No tokenizer variant (single-tape rendering is structurally trivial; no per-cell discrimination needed beyond head-vs-other, which the simple string form captures fine).
+- **`StepCommand` parameter type defined locally in visuals.** Plain `{ movement: 'L'|'R'|'S'; symbol: string | null }` — distinct from engine's `TapeCommand` class. Coupling formatters/tokenizers to a specific engine class adds zero value; consumers passing plain data from snippet frames / log lines / worker boundaries don't have to construct engine class instances just to format a string.
 - **Demo migration is NOT in this PR.** That happens in the machines-demo cleanup PR, after alpha.6.1 publishes.
-- **No new `Command` import dependency.** The engine's `Command` type is already in visuals's import surface (used by alpha.6's `formatCommand`). No new public API surface beyond what's strictly needed.
 
 ---
 
@@ -28,16 +35,18 @@
 ```
 packages/visuals/
 ├── src/
-│   ├── format.ts         # MODIFY — add formatStepNotation + formatTape; keep alpha.6 fns intact
-│   ├── format.spec.ts    # MODIFY — add test cases for the new primitives
-│   └── index.ts          # MODIFY — export formatStepNotation + formatTape
+│   ├── format.ts         # MODIFY — add StepCommand + tokenizeStep + token types
+│   │                                 + formatStepNotation (delegates to tokenizeStep)
+│   │                                 + formatTape; keep alpha.6 fns intact
+│   ├── format.spec.ts    # MODIFY — test cases for tokenizeStep, formatStepNotation, formatTape
+│   └── index.ts          # MODIFY — export all new symbols
 ├── CHANGELOG.md          # MODIFY — new [7.0.0-alpha.6.1] entry
 └── package.json          # MODIFY — version bump 7.0.0-alpha.6 → 7.0.0-alpha.6.1
 
 package-lock.json         # MODIFY — auto-resync (visuals's lock entry only)
 ```
 
-Note: `lerna.json`'s `version` field stays at the engine's `7.0.0-alpha.6` — this release intentionally diverges from lerna's single-version model. Per-package versions are the authoritative source for `lerna publish from-package`; the `lerna.json` version is informational only when `independent` mode isn't set, and is fine to leave stale for this kind of single-package release. (Reconsider if lerna emits a warning at publish time.)
+Note: `lerna.json`'s `version` field stays at the engine's `7.0.0-alpha.6` — this release intentionally diverges from lerna's single-version model. Per-package versions are the authoritative source for `lerna publish from-package`; the `lerna.json` version is informational when `independent` mode isn't set, and is fine to leave stale for this kind of single-package release. (Reconsider if lerna emits a warning at publish time.)
 
 Public API delta after this PR:
 
@@ -46,85 +55,163 @@ Public API delta after this PR:
 export function formatCommand(tapeCommand: TapeCommand): string;
 export function formatStep(m: MachineState): string;
 
-// New (alpha.6.1)
+// New (alpha.6.1) — structured-token surface (primary primitive)
+export type StepCommand = {
+  movement: 'L' | 'R' | 'S';
+  symbol: string | null;  // null = keep
+};
+
+export type ReadToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'blank' }
+  | { kind: 'wildcard'; symbol: string };
+
+export type WriteToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'erase' }
+  | { kind: 'keep'; readContext?: { symbol: string; isBlank: boolean } };
+
+export type StepTokens = {
+  reads: readonly ReadToken[] | null;  // null = manual Apply
+  writes: readonly WriteToken[];
+  moves: readonly ('L' | 'R' | 'S')[];
+};
+
+export function tokenizeStep(
+  reads: readonly string[] | null,
+  commands: readonly StepCommand[],
+  blanks: readonly string[],
+  matchKinds?: readonly ('wildcard' | 'literal')[] | null,
+): StepTokens;
+
+// New (alpha.6.1) — string rendering (thin renderer over tokenizeStep)
 export function formatStepNotation(
   reads: readonly string[] | null,
-  commands: readonly Command[],
+  commands: readonly StepCommand[],
   blanks: readonly string[],
   matchKinds?: readonly ('wildcard' | 'literal')[] | null,
 ): string;
+
+// New (alpha.6.1) — tape rendering
 export function formatTape(tape: TapeSnapshot): string;
 ```
 
 ---
 
-## Task 1: Add `formatStepNotation` + `formatTape` to `format.ts`
+## Task 1: Add tokens + tokenizer + renderers + tape formatter to `format.ts`
 
 **Files:** `packages/visuals/src/format.ts`
 
 - [ ] **Step 1: Read demo's `format.ts` as the source spec**
 
-`../machines-demo/src/lib/format.ts:33-84` — the `formatStepNotation` function body + its JSDoc, plus the `formatTape` function. Port both verbatim into visuals.
+`../machines-demo/src/lib/format.ts:33-84` — the `formatStepNotation` function body + its JSDoc + the `formatTape` function. The port is a refactor (not a verbatim copy): demo's monolithic string function splits into `tokenizeStep` (structured output) + `formatStepNotation` (thin string renderer over tokens). Final string output is byte-identical.
 
-- [ ] **Step 2: Add to `packages/visuals/src/format.ts`**
+- [ ] **Step 2: Define `StepCommand` + token types**
 
-Append after the existing `formatStep` / `formatCommand`:
+Add to `packages/visuals/src/format.ts`:
 
 ```ts
-import type { Command, TapeSnapshot } from '@turing-machine-js/machine';   // adjust to existing imports
-
-/**
- * Engine edge-label format — `[reads] → [writes]/[moves]`. Matches
- * `toMermaid` emit so a logged step's notation lines up byte-for-byte with
- * the same transition's edge label in the rendered state graph.
- *
- * Per-cell encoding:
- * - Read cell: `'X'` (literal) or `B` (blank, non-wildcard only). Wildcard
- *   reads render as `*='X'` (showing what `ifOtherSymbol` caught). When
- *   `matchKinds` is omitted (manual Apply), every position renders as a literal.
- * - Write cell: `'X'` (literal) | `K='X'` (keep with concrete kept symbol)
- *   | `K` (keep, no read context) | `E` (erase, write equals blank).
- * - Move cell: `L` | `R` | `S`.
- *
- * Multi-tape: per-tape entries comma-separated inside one outer bracket
- * per role: `['1','a'] → ['0','b']/[R,L]`.
- *
- * Pass `reads === null` for the manual-Apply path (no transition fired) —
- * output collapses to `[writes]/[moves]`.
- */
-export function formatStepNotation(
+import type { TapeSnapshot } from './types';
+
+export type StepCommand = {
+  movement: 'L' | 'R' | 'S';
+  symbol: string | null;
+};
+
+export type ReadToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'blank' }
+  | { kind: 'wildcard'; symbol: string };
+
+export type WriteToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'erase' }
+  | { kind: 'keep'; readContext?: { symbol: string; isBlank: boolean } };
+
+export type StepTokens = {
+  reads: readonly ReadToken[] | null;
+  writes: readonly WriteToken[];
+  moves: readonly ('L' | 'R' | 'S')[];
+};
+```
+
+`StepCommand` is the plain per-tape command shape (NOT engine's `TapeCommand` class). Lets callers pass data from snippet frames / log lines / worker boundaries without constructing engine class instances.
+
+- [ ] **Step 3: Add `tokenizeStep`**
+
+```ts
+export function tokenizeStep(
   reads: readonly string[] | null,
-  commands: readonly Command[],
+  commands: readonly StepCommand[],
   blanks: readonly string[],
   matchKinds?: readonly ('wildcard' | 'literal')[] | null,
-): string {
-  // VERBATIM port from machines-demo/src/lib/format.ts:formatStepNotation —
-  // see that file for the per-cell encoding rationale. Do NOT alter shape.
-  const writes = commands.map((c, i) => {
+): StepTokens {
+  const writes: WriteToken[] = commands.map((c, i) => {
     if (c.symbol === null) {
       if (reads !== null) {
         const r = reads[i];
-        if (r !== undefined) return r === blanks[i] ? 'K=B' : `K='${r}'`;
+        if (r !== undefined) {
+          return { kind: 'keep', readContext: { symbol: r, isBlank: r === blanks[i] } };
+        }
       }
-      return 'K';
+      return { kind: 'keep' };
     }
-    if (c.symbol === blanks[i]) return 'E';
-    return `'${c.symbol}'`;
-  }).join(',');
-  const moves = commands.map((c) => c.movement).join(',');
-  const writesPart = `[${writes}]/[${moves}]`;
-
-  if (reads === null) return writesPart;
-
-  const readsStr = reads.map((r, i) => {
-    if (matchKinds?.[i] === 'wildcard') return `*='${r}'`;
-    return r === blanks[i] ? 'B' : `'${r}'`;
-  }).join(',');
+    if (c.symbol === blanks[i]) return { kind: 'erase' };
+    return { kind: 'literal', symbol: c.symbol };
+  });
+
+  const moves = commands.map((c) => c.movement);
+
+  if (reads === null) return { reads: null, writes, moves };
+
+  const readTokens: ReadToken[] = reads.map((r, i) => {
+    if (matchKinds?.[i] === 'wildcard') return { kind: 'wildcard', symbol: r };
+    if (r === blanks[i]) return { kind: 'blank' };
+    return { kind: 'literal', symbol: r };
+  });
+
+  return { reads: readTokens, writes, moves };
+}
+```
+
+- [ ] **Step 4: Add `formatStepNotation` as a thin renderer over `tokenizeStep`**
+
+```ts
+function renderReadToken(t: ReadToken): string {
+  if (t.kind === 'wildcard') return `*='${t.symbol}'`;
+  if (t.kind === 'blank') return 'B';
+  return `'${t.symbol}'`;
+}
+
+function renderWriteToken(t: WriteToken): string {
+  if (t.kind === 'erase') return 'E';
+  if (t.kind === 'literal') return `'${t.symbol}'`;
+  if (!t.readContext) return 'K';
+  if (t.readContext.isBlank) return 'K=B';
+  return `K='${t.readContext.symbol}'`;
+}
+
+export function formatStepNotation(
+  reads: readonly string[] | null,
+  commands: readonly StepCommand[],
+  blanks: readonly string[],
+  matchKinds?: readonly ('wildcard' | 'literal')[] | null,
+): string {
+  const tokens = tokenizeStep(reads, commands, blanks, matchKinds);
+  const writesStr = tokens.writes.map(renderWriteToken).join(',');
+  const movesStr = tokens.moves.join(',');
+  const writesPart = `[${writesStr}]/[${movesStr}]`;
+  if (tokens.reads === null) return writesPart;
+  const readsStr = tokens.reads.map(renderReadToken).join(',');
   return `[${readsStr}] → ${writesPart}`;
 }
+```
+
+`renderReadToken` / `renderWriteToken` are internal helpers — NOT exported. Consumers wanting custom rendering call `tokenizeStep` directly and write their own per-cell renderers (HTML spans, ANSI escape codes, etc.).
+
+- [ ] **Step 5: Add `formatTape`**
 
-/** Inline tape rendering: head bracketed in place. `[<blank>]` is fine —
- *  user controls the blank glyph. */
+```ts
 export function formatTape(tape: TapeSnapshot): string {
   return tape.symbols
     .map((sym, i) => (i === tape.position ? `[${sym}]` : sym))
@@ -132,11 +219,9 @@ export function formatTape(tape: TapeSnapshot): string {
 }
 ```
 
-**Verify before writing:** the `Command` type is already imported (it backs alpha.6's `formatCommand`); just add `TapeSnapshot` to the type import. If the existing file uses `c.movement` strings vs symbols, mirror demo exactly — demo treats `c.movement` as a `string` ('L'|'R'|'S') in this context (it comes from `Command` per demo's types, which may differ from engine `TapeCommand`). Read demo's `Command` type definition (`../machines-demo/src/lib/types.ts`) to confirm shape; if demo's `Command` is `{ movement: 'L'|'R'|'S'; symbol: string | null }` (string movement), and visuals's engine `Command` differs, you may need to adapt the port — but DO NOT change the output format.
-
-> **If the engine `Command` shape differs enough that a verbatim port doesn't compile**, raise it as a DONE_WITH_CONCERNS. Two acceptable resolutions: (a) take the formatter's input type as the demo's shape (`{ movement: 'L'|'R'|'S'; symbol: string | null }[]`) instead of engine `Command[]`, since these formatters serve consumers who already have that shape from snippet frames / log lines; (b) keep engine `Command[]` and translate fields at the call site. (a) is likely cleaner — the formatter is a string producer over a fixed shape; coupling it to a specific engine class adds zero value.
+Verbatim port of demo's `formatTape`.
 
-- [ ] **Step 3: Typecheck**
+- [ ] **Step 6: Typecheck**
 
 ```sh
 npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run typecheck
@@ -146,42 +231,61 @@ Expected: clean.
 
 ---
 
-## Task 2: Add tests for `formatStepNotation` + `formatTape`
+## Task 2: Add tests
 
 **Files:** `packages/visuals/src/format.spec.ts`
 
-- [ ] **Step 1: Add cases to format.spec.ts**
+Three test groups: `formatStepNotation` (string output assertions), `tokenizeStep` (structured-token assertions), `formatTape` (string output).
 
-Mirror the encoding rules in tests. Each case asserts the exact output string. Recommended cases (8+ cases):
+- [ ] **Step 1: `formatStepNotation` cases (10 cases)**
+
+Each asserts the exact output string. Mirrors demo's encoding rules byte-for-byte; serves as the regression net that catches any drift in the token→string render path.
 
 - Single-tape literal: `formatStepNotation(['a'], [{symbol: 'b', movement: 'R'}], [' '], ['literal'])` → `"['a'] → ['b']/[R]"`
-- Single-tape blank read: `(['  '], [{...}], [' '], ['literal'])` → `[B] → ...` (blank shortcut on read)
+- Single-tape blank read (non-wildcard): `([' '], [{...}], [' '], ['literal'])` → `[B] → ...`
 - Single-tape wildcard read: `(['a'], [...], [' '], ['wildcard'])` → `"[*='a'] → ..."` (wildcard marker, NOT `B` shortcut)
+- Single-tape wildcard read with blank: `([' '], [...], [' '], ['wildcard'])` → `"[*=' '] → ..."` (wildcard preserves literal even when blank)
 - Single-tape keep with read: `(['a'], [{symbol: null, movement: 'S'}], [' '], ['literal'])` → `"['a'] → [K='a']/[S]"`
-- Single-tape keep blank: same shape with `reads === blank` → `K=B`
+- Single-tape keep with blank read: `([' '], [{symbol: null, ...}], [' '], ['literal'])` → `"[B] → [K=B]/[S]"`
 - Single-tape erase: `(['a'], [{symbol: ' ', movement: 'L'}], [' '], ['literal'])` → `"['a'] → [E]/[L]"`
 - Manual-Apply (no reads): `formatStepNotation(null, [{symbol: 'b', movement: 'R'}], [' '], null)` → `"['b']/[R]"` (no `[reads] →` prefix)
-- Multi-tape: `(['a', 'b'], [{...}, {...}], [' ', ' '], ['literal', 'wildcard'])` → `"['a',*='b'] → [...]/[...]"`
-- formatTape: `formatTape({symbols: ['a', 'b', 'c'], position: 1})` → `"a[b]c"`
-- formatTape head at end: `formatTape({symbols: ['a'], position: 0})` → `"[a]"`
+- Manual-Apply with keep: `formatStepNotation(null, [{symbol: null, ...}], [' '], null)` → `"[K]/[S]"` (bare K — no read context)
+- Multi-tape mixed wildcard + literal: `(['a','x'], [...,...], [' ',' '], ['wildcard','literal'])` → `"[*='a','x'] → ['b','y']/[R,S]"`
+- Omitted matchKinds: defaults to literal everywhere, no wildcards.
 
-- [ ] **Step 2: Run the new tests**
+- [ ] **Step 2: `tokenizeStep` cases (10 cases)**
 
-```sh
-npx --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js vitest run packages/visuals/src/format.spec.ts
-```
+Each asserts the structured shape. These prove the tokenizer is correct independently of the string renderer; consumers who skip the string renderer rely on these.
+
+- Literal read + literal write: full `StepTokens` object with `{ kind: 'literal', symbol: ... }` variants.
+- Blank read (non-wildcard) → `{ kind: 'blank' }`.
+- Wildcard read → `{ kind: 'wildcard', symbol: ' ' }` (no blank shortcut).
+- Keep with non-blank read → `{ kind: 'keep', readContext: { symbol: 'a', isBlank: false } }`.
+- Keep with blank read → `{ kind: 'keep', readContext: { symbol: ' ', isBlank: true } }`.
+- Erase → `{ kind: 'erase' }`.
+- Manual Apply (`reads === null`): `tokens.reads === null`, `keep` writes carry no `readContext`.
+- Omitted matchKinds: reads are all `{ kind: 'literal' | 'blank' }` (no wildcards).
+- Multi-tape: arrays line up per index across reads/writes/moves; mixed wildcard + literal + blank tokens.
+- Consistency invariant: `formatStepNotation(args)` for given args equals the manual string render of `tokenizeStep(args).{reads,writes,moves}` — confirms the two surfaces describe the same step. (One sentinel case is enough.)
+
+- [ ] **Step 3: `formatTape` cases (5 cases)**
 
-Expected: all pass.
+- Head in middle: `formatTape({symbols: ['a','b','c'], position: 1})` → `"a[b]c"`
+- Head at start: `{symbols: ['a','b'], position: 0}` → `"[a]b"`
+- Head at end: `{symbols: ['a','b'], position: 1}` → `"a[b]"`
+- Single-cell: `{symbols: ['x'], position: 0}` → `"[x]"`
+- Blank glyph rendered literally: `{symbols: [' ','a',' '], position: 0}` → `"[ ]a "` (spaces pass through literally, joined with empty string — NOT space-separated)
 
-- [ ] **Step 3: Full verify**
+- [ ] **Step 4: Run the spec + full verify**
 
 ```sh
+npx --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js vitest run packages/visuals/src/format.spec.ts
 npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js test
 npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run typecheck
 npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run lint
 ```
 
-All green. Test count grows by N (the cases you added).
+All green. Total visuals format spec count = 8 (alpha.6 `formatCommand` + `formatStep`) + 10 (`formatStepNotation`) + 10 (`tokenizeStep`) + 5 (`formatTape`) = **33**. Full repo test count goes from 616 → **642**.
 
 ---
 
@@ -189,15 +293,27 @@ All green. Test count grows by N (the cases you added).
 
 **Files:** `packages/visuals/src/index.ts`
 
-- [ ] **Step 1: Append exports**
-
-After the existing alpha.6 exports:
+- [ ] **Step 1: Merge into the existing format export line**
 
+Replace:
 ```ts
-export { formatCommand, formatStep, formatStepNotation, formatTape } from './format';
+export { formatCommand, formatStep } from './format';
 ```
 
-(Adjust to merge with the existing `formatCommand` / `formatStep` export line — single line, all four names.)
+With:
+```ts
+export {
+  formatCommand,
+  formatStep,
+  formatStepNotation,
+  formatTape,
+  tokenizeStep,
+  type StepCommand,
+  type ReadToken,
+  type WriteToken,
+  type StepTokens,
+} from './format';
+```
 
 - [ ] **Step 2: Verify**
 
@@ -207,7 +323,7 @@ Re-run typecheck + a build to confirm `dist/` includes the new symbols:
 npm --prefix /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js run build
 ```
 
-Expected: clean, `dist/format.d.ts` exports the new functions, `dist/index.{cjs,mjs,d.ts}` re-export them.
+Expected: clean. `dist/format.d.ts` exports all new functions + types; `dist/index.{cjs,mjs,d.ts}` re-export them. `Built @turing-machine-js/visuals Node entries` confirms Rollup runs cleanly.
 
 ---
 
@@ -241,31 +357,29 @@ Only the visuals workspace entry in `package-lock.json` should change.
 
 ### Added
 
-- `formatStepNotation(reads, commands, blanks, matchKinds?)` — engine edge-label format primitive, matches `toMermaid` emit byte-for-byte. Per-cell encoding: literal `'X'`, blank shortcut `B`, wildcard `*='X'`, keep-with-concrete-symbol `K='X'`, erase `E`. Multi-tape comma-separated within one outer bracket per role. Pass `reads === null` for the manual-Apply path (no transition fired) — output collapses to `[writes]/[moves]`. Folds in the richness machines-demo's local `format.ts` had so demo can drop the local helper and call visuals's primitive directly.
+- `formatStepNotation(reads, commands, blanks, matchKinds?)` — engine edge-label format primitive, matches `toMermaid` emit byte-for-byte. Per-cell encoding: literal `'X'`, blank shortcut `B`, wildcard `*='X'` (shows what `ifOtherSymbol` caught), keep-with-concrete-symbol `K='X'` / `K=B`, erase `E`. Multi-tape comma-separated within one outer bracket per role. Pass `reads === null` for the manual-Apply path — output collapses to `[writes]/[moves]`. Folds in the richness machines-demo's local `format.ts` had so demo can drop the local helper and call visuals's primitive directly.
+- `tokenizeStep(reads, commands, blanks, matchKinds?)` + `ReadToken` / `WriteToken` / `StepTokens` types — renderer-agnostic structured form of one step. Same input contract as `formatStepNotation`; returns discriminated-union tokens per cell. Consumers wanting custom rendering (HTML spans with CSS classes, ANSI-colored terminal output, alternative move vocabulary, clickable cells) walk the tokens themselves. `formatStepNotation` is refactored to be a thin string renderer over `tokenizeStep` (output byte-identical).
 - `formatTape(tape)` — inline tape rendering with the head bracketed in place (`a[b]c`).
+- `StepCommand` — plain per-tape command shape (`{ movement: 'L' | 'R' | 'S'; symbol: string | null }`) consumed by `formatStepNotation` and `tokenizeStep`. Distinct from engine's `TapeCommand` class; matches the shape machines-demo's worker boundary exposes.
 
 ### Compatibility
 
 - alpha.6's `formatCommand(tapeCommand)` and `formatStep(m)` unchanged. Additive release.
-- Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at `7.0.0-alpha.6` — no functional changes there. Visuals-only release; the workspace's lockstep convention is for coordinated peer-dep widening when engine APIs break, not for additive consumer-package enhancements.
+- Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at `7.0.0-alpha.6` — no functional changes there. Visuals-only follow-up patch; the workspace's lockstep convention is for coordinated peer-dep widening when engine APIs break, not for additive consumer-package enhancements.
+- Peer dep `@turing-machine-js/machine: ^7.0.0-alpha.6` unchanged (semver-prerelease caret already accepts `alpha.6.1`).
 ```
 
 - [ ] **Step 3: Verify, then commit**
 
 `git -C ... status` — should show: `packages/visuals/package.json`, `packages/visuals/CHANGELOG.md`, `package-lock.json`, plus the Task 1-3 source/test/index changes.
 
-Commit in two focused commits for a clean bisect:
-1. `feat(visuals): add formatStepNotation + formatTape primitives (alpha.6.1)` — Task 1-3 source/test/index changes
-2. `release(visuals): 7.0.0-alpha.6.1 — formatter enhancements` — version bump + CHANGELOG + lockfile resync
-
-Or fold into one. Either works.
+Commit in two or three focused commits for a clean bisect. The actual PR (#221) used:
 
-For a tidy history, commit the work as several focused commits:
-1. `feat(visuals): add formatStepNotation + formatTape primitives (alpha.6.1)`
-2. `test(visuals): cover formatStepNotation + formatTape encoding cases`
-3. `release(visuals): 7.0.0-alpha.6.1 — formatter enhancements`
+1. `feat(visuals): add formatStepNotation + formatTape primitives (#204)` — Task 1 (partial: types, formatStepNotation, formatTape) + Task 2 (tests for those) + Task 3 (export) + plan doc
+2. `release(visuals): 7.0.0-alpha.6.1 — formatter enhancements` — Task 4 (version + CHANGELOG + lockfile)
+3. `feat(visuals): add tokenizeStep + ReadToken/WriteToken/StepTokens for renderer-agnostic step rendering (#204)` — Task 1 (remainder: tokens, tokenizeStep, refactored formatStepNotation to delegate) + Task 2 (tokenizer tests) + Task 3 (extended export) + CHANGELOG amend
 
-Or fold into one. Either's fine; per-task commits read cleaner if someone bisects.
+The 3rd commit is the tokenizer fold — added mid-execution after the design discussion landed on Option B (structured tokens) as the right shape. A clean redo of this plan would land all of it as commit (1), but per the user's no-amend rule the fold became its own commit.
 
 - [ ] **Step 4: Push**
 
@@ -279,71 +393,42 @@ git -C /Users/mellonis/Developer/mellonis-workspace/machines/turing-machine-js p
 
 - [ ] **Step 1: Open PR against `v7`**
 
-```sh
-gh pr create --repo mellonis/turing-machine-js --base v7 --head feat/visuals-alpha7-formatters \
-  --title "feat(visuals): alpha.6.1 formatter enhancements (formatStepNotation + formatTape)" \
-  --body "$(cat <<'EOF'
-## Summary
-
-alpha.6.1 of \`@turing-machine-js/visuals\`. Folds the richness of machines-demo's local \`format.ts\` into visuals so the upcoming demo cleanup PR can drop the local helper and call visuals's primitives directly.
-
-Pure additive change. alpha.6's \`formatCommand\` / \`formatStep\` unchanged.
-
-## What's new
-
-- **\`formatStepNotation(reads, commands, blanks, matchKinds?)\`** — engine edge-label format primitive matching \`toMermaid\` emit byte-for-byte. Per-cell encoding covers literal \`'X'\`, blank shortcut \`B\`, wildcard \`*='X'\` (showing what \`ifOtherSymbol\` caught), keep-with-concrete-symbol \`K='X'\` / \`K=B\`, erase \`E\`, and the manual-Apply path (\`reads === null\` collapses output to \`[writes]/[moves]\`).
-- **\`formatTape(tape)\`** — inline tape rendering with the head bracketed in place.
+`gh pr create --repo mellonis/turing-machine-js --base v7 --head feat/visuals-alpha7-formatters --title "feat(visuals): alpha.6.1 — formatStepNotation + tokenizeStep + formatTape"` with a body covering: summary (formatter richness + structured-token surface), public API delta (the full block from this plan's File Structure section), versioning (visuals-only bump, alpha.6.1 over alpha.7), test plan, publish + follow-up notes pointing at the machines-demo cleanup plan.
 
-## Versioning (visuals-only bump)
-
-Bumps **visuals alone** to \`7.0.0-alpha.6.1\`. Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at \`7.0.0-alpha.6\` — no functional changes there; bumping them would create ghost releases. Peer-dep ranges stay at \`^7.0.0-alpha.6\` (semver-prerelease caret already accepts alpha.6.1+). The workspace's lockstep convention exists for coordinated peer-dep widening when engine APIs break, not for additive consumer-package enhancements.
-
-## Test plan
-
-- [x] \`npm test\` — passes, +N tests in \`format.spec.ts\`.
-- [x] \`npm run typecheck\` — clean.
-- [x] \`npm run lint\` — clean.
-- [x] \`npm run build\` — \`dist/format.d.ts\` exports the new symbols; \`Built @turing-machine-js/visuals Node entries\` confirms Rollup runs cleanly.
-
-## Follow-ups
-
-- Lockstep publish (or visuals-only publish) — \`npx lerna publish from-package --dist-tag next\` from the repo root after merge. Lerna's \`from-package\` mode publishes anything NOT yet on the registry; only visuals will publish.
-- Then the [machines-demo visuals-cleanup PR](https://github.com/mellonis/machines-demo/blob/master/docs/superpowers/plans/2026-05-30-visuals-cleanup.md) becomes a clean drop: deletes \`format.ts\`'s \`formatStepNotation\` + \`formatTape\` and points \`commandsEntry\` / \`tapesEntry\` at visuals.
-
-Per repo convention, this PR targets \`v7\`. CI doesn't run on v7 branches.
-EOF
-)"
-```
+The actual PR landed at https://github.com/mellonis/turing-machine-js/pull/221.
 
 ---
 
 ## Self-review checklist
 
-- [ ] `formatStepNotation` body matches demo's verbatim — same encoding paths, same multi-tape join, same null-`reads` handling.
+- [ ] `formatStepNotation` output is byte-identical to a from-scratch port of demo's helper — verified by running demo's existing format-spec assertions against the refactored implementation (24/24 pass unchanged).
+- [ ] `tokenizeStep` returns the expected discriminated-union shape for every encoding branch (literal, blank, wildcard reads; literal, erase, keep writes; keep carries `readContext` when reads available, omits when manual Apply).
 - [ ] `formatTape` body matches demo's verbatim.
 - [ ] alpha.6 surface (`formatCommand`, `formatStep`) unchanged.
-- [ ] CHANGELOG entry under `[7.0.0-alpha.6.1]`, dated `2026-05-30`.
-- [ ] package.json at `7.0.0-alpha.6.1`; peer dep unchanged.
+- [ ] CHANGELOG entry under `[7.0.0-alpha.6.1]`, dated `2026-05-30`, lists all four new public symbols (`formatStepNotation`, `tokenizeStep`, `formatTape`, `StepCommand`) plus the three token types.
+- [ ] package.json at `7.0.0-alpha.6.1`; peer dep unchanged at `^7.0.0-alpha.6`.
 - [ ] No Claude attribution footers in commits.
-- [ ] Tests cover every encoding branch (literal, blank-B, wildcard, keep-with-read, keep-blank, erase, manual-Apply, multi-tape).
+- [ ] Tests cover both string output (10 `formatStepNotation` cases + 5 `formatTape`) AND structured tokens (10 `tokenizeStep` cases including a consistency invariant that ties the two surfaces together).
 
 ---
 
 ## After this lands
 
 1. **Publish** — `cd turing-machine-js && npx lerna publish from-package --dist-tag next --yes`. Only visuals publishes (engine + builder + libs are already on the registry at alpha.6, lerna skips them). Same catch-up-publish flow as alpha.6's initial visuals publish.
-2. **Tagging:** **no new GH release** for `v7.0.0-alpha.6.1`. The git tag scheme tracks engine versions; visuals-only releases ship under the existing engine tag (alpha.6 in this case). Optionally edit the `v7.0.0-alpha.6` GH release body to add a short note like "Visuals follow-up: alpha.6.1 adds `formatStepNotation` + `formatTape` — see [packages/visuals/CHANGELOG.md](https://github.com/mellonis/turing-machine-js/blob/v7/packages/visuals/CHANGELOG.md)."
+2. **Tagging:** **no new GH release** for `v7.0.0-alpha.6.1`. The git tag scheme tracks engine versions; visuals-only releases ship under the existing engine tag (alpha.6 in this case). Optionally edit the `v7.0.0-alpha.6` GH release body to add a short follow-up note pointing at visuals's CHANGELOG.
 3. **Resume the machines-demo cleanup PR plan.** With alpha.6.1 published, the cleanup PR additionally:
    - Bumps the demo's visuals dep to `^7.0.0-alpha.6.1` (via `npm install @turing-machine-js/visuals@next`).
    - Deletes demo's local `formatStepNotation` (was internal) — call sites in `commandsEntry` switch to importing from `@turing-machine-js/visuals`.
    - Deletes demo's local `formatTape` export — callers switch to visuals's.
    - Keeps `tapesEntry`, `commandsEntry`, `CommandsApplication` in demo (LogEntry assembly is demo-specific).
+   - Could also adopt `tokenizeStep` for any demo paths that want richer rendering than the default string format — purely opportunistic, not required for the cleanup.
 
 ---
 
 ## Out of scope
 
 - **Engine bump.** No engine changes in this alpha.
-- **Backwards-compat shims for the alpha.6 formatters.** They stay live, unchanged. Future deprecation, if any, is a separate decision.
+- **Backwards-compat shims for the alpha.6 formatters.** `formatCommand(tapeCommand)` and `formatStep(m)` stay live, unchanged. Future deprecation, if any, is a separate decision.
 - **GH release for `v7.0.0-alpha.6.1`.** Skipped — tag scheme tracks engine versions, and the engine isn't bumping. Optionally edit the existing `v7.0.0-alpha.6` release body to note the visuals follow-up.
+- **`renderReadToken` / `renderWriteToken` as public exports.** They're internal helpers backing `formatStepNotation`'s string rendering. Consumers wanting custom rendering call `tokenizeStep` and walk tokens themselves — exposing the per-cell string renderers would just be a confusing partial-customization API ("you can change the join but not the tokens? or the tokens but not the join?"). Add later only if a real consumer asks.
 - **Demo migration.** That's the cleanup PR's job, after this publishes.

From 3c1a50157c1e346547d290747221a51a516c9ea5 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 19:03:31 +0300
Subject: [PATCH 100/118] docs: surface @turing-machine-js/visuals in CLAUDE.md
 + READMEs (post-alpha.6.1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CLAUDE.md: Architecture section now lists 5 packages (visuals added); new Versioning convention subsection covering lockstep vs visuals-only patches. Visualization & round-trip section extended with three paragraphs on visuals as Graph consumer, edge-label formatter, and snippet recorder.
- README.md: visuals package entry added to the repo's package list.
- packages/visuals/README.md: expanded from 21 lines to a full usage doc — when-to-use, API surface, applyHighlight + DOM applier example, formatStepNotation example, tokenizeStep example, recordSnippet example, versioning note covering visuals-only patches.
- packages/machine/README.md: one-line see-also pointer to visuals in the intro.
---
 CLAUDE.md                  |  19 ++-
 README.md                  |   1 +
 packages/machine/README.md |   2 +
 packages/visuals/README.md | 248 +++++++++++++++++++++++++++++++++++--
 4 files changed, 258 insertions(+), 12 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1c739fe..6099276 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,12 +16,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Architecture
 
-This is an npm-workspaces + Lerna monorepo (`packages/*`, single shared version managed by `lerna.json`). Four published packages:
+This is an npm-workspaces + Lerna monorepo (`packages/*`). Versioning is **lockstep across the four engine/library packages** via `lerna.json` (engine + builder + library-binary-numbers + library-binary-numbers-bare share one version); **`visuals` versions independently** — additive consumer-package patches don't require coordinated peer-dep widening (see Versioning convention below). Five published packages:
 
 - **`@turing-machine-js/machine`** — the core engine (no runtime deps).
 - **`@turing-machine-js/builder`** — declarative state-table → machine builder; depends on `machine`. Soft-deprecated; see its README.
 - **`@turing-machine-js/library-binary-numbers`** — prebuilt states for `^…$`-delimited binary arithmetic on a 5-symbol alphabet; depends on `machine`.
 - **`@turing-machine-js/library-binary-numbers-bare`** — same operations on a 3-symbol alphabet (no markers, single number per tape, much smaller state graphs); depends on `machine`. Side-by-side with the marker-based library to make the alphabet-vs-graph-size trade-off visible.
+- **`@turing-machine-js/visuals`** (v7-only, [#204](https://github.com/mellonis/turing-machine-js/issues/204)) — pure highlight + graph-indexing logic for the engine `Graph`. Peer dep on `machine`, no runtime deps. Exposes `applyHighlight` / `applyIndicator` / `indexGraph` / `bareIdOf` / `highlightExpand` / `equivalentIds` / `recordingOps` (renderer-agnostic ops contract via `HighlightOps` / `IndicatorOps`), plus the `recordSnippet` artifact recorder (`Snippet` / `Frame` / `StepCommand` / `TapeSnapshot`) and the engine-edge-label formatter primitives (`formatStepNotation` / `tokenizeStep` / `formatTape`, the latter shipped in alpha.6.1). 16-rule contract for `applyHighlight` lives at `packages/visuals/docs/graph-highlight-and-breakpoints.md` (moved there from machines-demo). Used by machines-demo for graph highlight + step-log rendering; designed to be reusable by article embeds and any future Graph consumer that wants byte-identical edge-label notation to `toMermaid`. **Engine + libraries are at `7.0.0-alpha.6`; visuals at `7.0.0-alpha.6.1`** (visuals-only patch added formatter primitives + tokens).
+
+### Versioning convention
+
+Engine + builder + libraries bump in lockstep (`lerna version X.Y.Z` from the repo root edits all four `package.json`s + `lerna.json`). This is the right shape when an engine API breaks and peer-dep ranges in dependents need to widen together — that's the whole reason a single coordinated bump exists.
+
+**Visuals breaks lockstep deliberately for additive consumer-package patches** (e.g., the `alpha.6.1` formatter-primitives bump). Bumping engine + libraries to alpha.6.1 with no functional changes would create ghost releases (identical tarballs republished under a new version). Visuals's peer `@turing-machine-js/machine: ^7.0.0-alpha.6` accepts alpha.6.1+ via semver-prerelease caret semantics, so consumers keep matching peer-dep versions without a coordinated upgrade. For the actual publish:
+
+- `lerna publish from-package --dist-tag next` walks `package.json` versions and publishes whatever's not yet on the registry. After bumping visuals alone to `7.0.0-alpha.6.1` and leaving the other 4 packages at alpha.6, only visuals publishes; the engine/builder/lib tarballs at alpha.6 are already on the registry and `from-package` skips them.
+- `lerna.json`'s `version` field can stay at the prior lockstep version (`7.0.0-alpha.6` after a visuals-only bump) — it's informational when not running in `independent` mode, and `from-package` doesn't read it for publish decisions.
+- When the next engine alpha needs to ship, bump back to lockstep (engine + builder + libs + visuals all to alpha.7 via `lerna version`).
 
 ### Documentation parity for the two binary libraries
 
@@ -61,6 +72,12 @@ Key shapes that take reading multiple files to grasp:
 
 `packages/machine` ships `State.toGraph(state, tapeBlock)` → `Graph` and `State.fromGraph(graph)` → `{start, tapeBlock, states}` for serialization. `toMermaid(graph)` and `fromMermaid(text)` round-trip the same `Graph` through [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) syntax (renderer: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)). The parser is strict to the dialect `toMermaid` emits — hand-edited Mermaid with different arrow styles or shapes won't round-trip.
 
+**`packages/visuals` is the Graph consumer for runtime visualization.** Given the engine's `Graph` (from `toGraph`), visuals provides: per-rule highlight derivation (`applyHighlight` over a renderer-agnostic `HighlightOps` interface — consumers implement DOM mutation / ANSI escapes / span wrapping / etc.), breakpoint-indicator placement (`applyIndicator`), wrapper/bare-id canonicalization (`bareIdOf`, `highlightExpand`, `equivalentIds`), pre-built index lookups (`indexGraph` → `GraphIndexes`), and a `recordingOps` factory for snapshot-test assertions. The 16-rule contract `applyHighlight` satisfies lives in the visuals package (`packages/visuals/docs/graph-highlight-and-breakpoints.md`). Same input shape as `toMermaid`, but emits operations against a typed renderer interface instead of a string.
+
+**`packages/visuals` is also the canonical edge-label formatter.** `formatStepNotation(reads, commands, blanks, matchKinds?)` produces strings byte-identical to `toMermaid`'s edge labels (`[reads] → [writes]/[moves]` with `'X'` / `B` / `*='X'` / `K='X'` / `K=B` / `E` per cell, multi-tape comma-separated within one outer bracket per role, manual-Apply path collapsing to `[writes]/[moves]`). Use this when log rendering needs to line up byte-for-byte with the rendered state graph. Consumers wanting non-string rendering (HTML spans with CSS classes, ANSI-colored terminal output, clickable cells) call `tokenizeStep` (returns `StepTokens` — discriminated-union `ReadToken` / `WriteToken` / move-letters) and walk the tokens themselves. `formatStepNotation` is a thin string renderer over `tokenizeStep`. Tape rendering: `formatTape(snapshot)` → `a[b]c` (head bracketed in place).
+
+**`packages/visuals` records snippets for embeds.** `recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }): Snippet` runs `machine.runStepByStep` and captures one `Frame` per iter plus a frame-0 initial-state snapshot. Frame shape: `{ step, tape: TapeSnapshot[], commands?: { movement, read, write }[], highlight: GraphHighlight | null, log? }` — `commands` carries both read and write so consumers can step bi-directionally without recomputing deltas from neighbouring frames. Engine-agnostic — caller supplies a pre-built `machine` + `initialState` (works with `@turing-machine-js/machine` or `@post-machine-js/machine`).
+
 **`State.collectStates(state, tapeBlock)`** (v7, #195) — returns a `Map<number, {state, transitionSymbols}>` keyed by engine `GraphNode.id`. For each id: the live `State` instance and the per-pattern `Symbol[]` from `#symbolToDataMap` in insertion order. The K-th `transitionSymbols` slot is positionally aligned with the GraphTransition whose id is `${stateId}.${K}` (separator was `-` in alpha.4; #205 changes it to `.` for v7), so consumers holding `(stateId, patternIx)` from a rendered graph reach the firing Symbol with no walk. `ifOtherSymbol` is included 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. Halt-singleton entry at id `0` is the process-wide singleton — JSDoc warns toggling its `debug` affects every machine in the runtime.
 
 **Per-iter `matchedTransition`** (v7, [#205](https://github.com/mellonis/turing-machine-js/issues/205) / [PR #206](https://github.com/mellonis/turing-machine-js/pull/206)) — every `MachineState` yielded by `run` / `runStepByStep` carries `matchedTransition: { id: string, matchKinds: ('wildcard'|'literal')[] }`. `id` is `${stateId}.${transitionIx}` and resolves in `toGraph`'s output via `graph.nodes[stateId].transitions.find(t => t.id === ...)`. For wrapper-entry iters (composite source from `withOverriddenHaltState`), `id` references the **bare's** transition — wrappers' own `transitions` arrays are empty because the pattern lives on the bare; consumers detect delegation by comparing `id.split('.')[0]` against `state.id`. `matchKinds` is per-tape, length = tape count; `'wildcard'` iff the winning alternative held `ifOtherSymbol` at that position (catch-all), `'literal'` otherwise. Halt-bound transitions still get a valid id (both real halt `nextStateId === 0` and in-frame halt markers `nextStateId === -frameId`). The field eliminates ambiguity in `(source, nextState)` resolution when multiple transitions on the same source share a destination, and lets consumers do exact-edge highlighting / per-transition coverage maps / wildcard-aware log formatting without re-parsing pattern strings from `toGraph`. The separator change from `-` (alpha.4) to `.` propagates to `toGraph`'s `GraphTransition.id` — see `collectStates` note above.
diff --git a/README.md b/README.md
index e202688..eda2e6e 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ This repository contains the following packages:
 * [@turing-machine-js/library-binary-numbers](https://github.com/mellonis/turing-machine-js/tree/master/packages/library-binary-numbers) — binary arithmetic on a 5-symbol alphabet (` ^$01`) supporting multiple numbers per tape, with `plusOne`, `minusOne`, `minusOneFast`, `invertNumber`, `normalizeNumber`, and inter-number navigation.
 * [@turing-machine-js/library-binary-numbers-bare](https://github.com/mellonis/turing-machine-js/tree/master/packages/library-binary-numbers-bare) — the same arithmetic on a 3-symbol alphabet (` 01`), single-number-per-tape. Side-by-side with the marker-based library to make the alphabet-size vs state-graph-size trade-off visible.
 * [@turing-machine-js/builder](https://github.com/mellonis/turing-machine-js/tree/master/packages/builder) — declarative state-table construction. Not actively developed; the same pattern is shown inline in `@turing-machine-js/machine`'s README.
+* [@turing-machine-js/visuals](https://github.com/mellonis/turing-machine-js/tree/v7/packages/visuals) (v7+, prerelease) — pure highlight + graph-indexing logic for the engine `Graph`: `applyHighlight` / `applyIndicator` against a renderer-agnostic `HighlightOps` interface, `bareIdOf` / `highlightExpand` for wrapper/bare canonicalization, `formatStepNotation` / `tokenizeStep` / `formatTape` for engine-edge-label rendering (byte-identical to `toMermaid`), `recordSnippet` for prerecorded-playback artifacts. No DOM, no Svelte, no Mermaid — consumers bring their own renderer.
 
 # An example
 
diff --git a/packages/machine/README.md b/packages/machine/README.md
index b9ecdaa..ee12ea2 100644
--- a/packages/machine/README.md
+++ b/packages/machine/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>
 
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index 9fdf932..adf68eb 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -1,21 +1,247 @@
 # @turing-machine-js/visuals
 
-Pure highlight + graph-indexing logic for [`@turing-machine-js/machine`](../machine). No DOM, no Svelte, no Mermaid — consumers bring their own renderer and DOM applier.
+Pure highlight + graph-indexing logic for [`@turing-machine-js/machine`](../machine) — plus a renderer-agnostic edge-label formatter and a `recordSnippet` artifact recorder for prerecorded playback (article embeds, landing-page panels, terminal tools). No DOM, no Svelte, no Mermaid — consumers bring their own renderer.
 
-## Scope
+## When to reach for this
 
-Types and pure functions for:
-- Indexing an engine `Graph` for wrapper/bare lookup (`indexGraph`, `bareIdOf`, `highlightExpand`).
-- Applying highlight + indicator operations against a renderer-agnostic `HighlightOps` interface (`applyHighlight`, `applyIndicator`).
-
-See [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md) for the full set of rules these functions satisfy.
-
-## Versioning
-
-Lockstep with `@turing-machine-js/machine`.
+- You have an engine `Graph` (from `State.toGraph(initialState, tapeBlock)`) and want to render it with **runtime highlight cues** — `from → edge → to` triples that animate as the machine steps, breakpoint dots, frame-active subgraph marks, pulse-on-revisit. Implement a small `HighlightOps` object that wraps your renderer's DOM/canvas/ANSI primitives; `applyHighlight` decides *what* to highlight, your `HighlightOps` decides *how*.
+- You want a logged step's notation to **line up byte-for-byte** with the rendered state graph's edge labels. `formatStepNotation` mirrors the engine's `toMermaid` edge-label vocabulary; same `[reads] → [writes]/[moves]`, same `'X'` / `B` / `*='X'` / `K='X'` / `E` shortcuts.
+- You want to **record a machine run** as a self-contained playback artifact — for an article embed, a landing-page panel, a snapshot test, anything that needs to replay a run without booting an engine. `recordSnippet` produces a `Snippet` with one `Frame` per iter (tape state + per-tape `{ movement, read, write }` command + highlight + optional log line); a player walks frames forward AND backward without recomputing deltas.
 
 ## Install
 
 ```sh
 npm install @turing-machine-js/visuals @turing-machine-js/machine
 ```
+
+Both prereleases on npm `next`:
+
+```sh
+npm install @turing-machine-js/visuals@next @turing-machine-js/machine@next
+```
+
+Peer-deps on `@turing-machine-js/machine@^7.0.0-alpha.6` — visuals follows engine v7 alphas with occasional visuals-only patches (`7.0.0-alpha.6.1` added the formatter primitives + token surface on top of the lockstep alpha.6 engine release).
+
+## Public API
+
+### Types
+
+```ts
+// Highlight contract
+type NodeKey = number | 'idle';
+type HighlightClass = 'mg-highlight-from' | 'mg-highlight-to' | 'mg-highlight-strong';
+interface HighlightOps {
+  addNodeClass(id: NodeKey, cls: HighlightClass): void;
+  highlightEdge(fromKey: string, toKey: string): void;
+  markFrameActive(frameId: number): void;
+  pulse(id: NodeKey): void;
+  scrollIntoView(id: NodeKey): void;
+}
+interface IndicatorOps {
+  setBreakpoint(id: NodeKey, on: boolean): void;
+}
+type GraphHighlight = {
+  fromId: number | 'idle';
+  toId: number | null;
+  strong: 'from' | 'to';
+  paused: boolean;
+};
+type GraphIndexes = { /* node→frame, frame→wrappers, frame→label, etc. */ };
+
+// Recording artifact
+type TapeSnapshot = { symbols: string[]; position: number };
+type StepCommand = { movement: 'L' | 'R' | 'S'; symbol: string | null };
+type Frame = {
+  step: number;
+  tape: TapeSnapshot[];
+  commands?: { movement: 'L' | 'R' | 'S'; read: string; write: string }[];
+  highlight: GraphHighlight | null;
+  log?: string;
+};
+type Snippet = {
+  version: 1;
+  name?: string;
+  graph: Graph;
+  alphabets: string[][];
+  frames: Frame[];
+};
+
+// Token surface (renderer-agnostic alternative to formatStepNotation strings)
+type ReadToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'blank' }
+  | { kind: 'wildcard'; symbol: string };
+type WriteToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'erase' }
+  | { kind: 'keep'; readContext?: { symbol: string; isBlank: boolean } };
+type StepTokens = {
+  reads: readonly ReadToken[] | null;  // null = manual-Apply path (no transition fired)
+  writes: readonly WriteToken[];
+  moves: readonly ('L' | 'R' | 'S')[];
+};
+```
+
+### Functions
+
+```ts
+indexGraph(graph): GraphIndexes
+applyHighlight(highlight, graph, indexes, prev, ops): { nextPrev }
+applyIndicator(breakpoints, graph, ops): void
+bareIdOf(id, graph): number
+highlightExpand(id, graph): number[]
+equivalentIds(id, graph): number[]
+recordingOps(): { highlight: HighlightOps; indicator: IndicatorOps; record: RecordedOp[] }
+
+// Formatters
+formatStepNotation(reads, commands, blanks, matchKinds?): string
+tokenizeStep(reads, commands, blanks, matchKinds?): StepTokens
+formatTape(tape): string
+formatCommand(tapeCommand): string  // alpha.6 single-command formatter; kept for back-compat
+formatStep(machineState): string    // alpha.6 MachineState-based formatter; kept for back-compat
+
+// Recording
+recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }): Snippet
+```
+
+The 16-rule contract `applyHighlight` satisfies is documented at [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md).
+
+## Example: applying highlight in a DOM renderer
+
+```ts
+import {
+  applyHighlight,
+  indexGraph,
+  type HighlightOps,
+  type GraphHighlight,
+} from '@turing-machine-js/visuals';
+import { State } from '@turing-machine-js/machine';
+
+// 1. Build your machine + Graph elsewhere (typical Svelte / React / vanilla code).
+const graph = State.toGraph(initialState, tapeBlock);
+const indexes = indexGraph(graph);
+
+// 2. Tiny DOM applier (illustrative — your renderer probably has a richer one).
+function domOps(svgRoot: SVGSVGElement): HighlightOps {
+  const node = (id: number | 'idle') =>
+    svgRoot.querySelector(`g.node[data-id="${id === 'idle' ? 'idle' : `s${id}`}"]`);
+  return {
+    addNodeClass: (id, cls) => node(id)?.classList.add(cls),
+    highlightEdge: (from, to) =>
+      svgRoot
+        .querySelector(`path[data-id^="L_${from}_${to}_"]`)
+        ?.classList.add('mg-highlight-edge'),
+    markFrameActive: (frameId) =>
+      svgRoot.querySelector(`g.cluster[data-id="w_${frameId}"]`)?.classList.add('mg-frame-active'),
+    pulse: (id) => node(id)?.classList.add('mg-pulse'),
+    scrollIntoView: (id) => node(id)?.scrollIntoView({ block: 'nearest', behavior: 'smooth' }),
+  };
+}
+
+// 3. On each engine pause / step: wipe previous highlight from the DOM, then apply the new one.
+//    HighlightOps is purely additive — the consumer is responsible for clearing
+//    `mg-highlight-*` classes before calling applyHighlight.
+let prev = null;
+function onMachineStep(highlight: GraphHighlight | null, svgRoot: SVGSVGElement) {
+  // Wipe.
+  for (const el of svgRoot.querySelectorAll(
+    '.mg-highlight-from, .mg-highlight-to, .mg-highlight-strong, .mg-highlight-edge, .mg-frame-active',
+  )) {
+    el.classList.remove(
+      'mg-highlight-from',
+      'mg-highlight-to',
+      'mg-highlight-strong',
+      'mg-highlight-edge',
+      'mg-frame-active',
+    );
+  }
+  if (!highlight) return;
+  const result = applyHighlight(highlight, graph, indexes, prev, domOps(svgRoot));
+  prev = result.nextPrev;
+}
+```
+
+## Example: rendering a step's edge-label notation
+
+```ts
+import { formatStepNotation, type StepCommand } from '@turing-machine-js/visuals';
+
+const commands: StepCommand[] = [
+  { movement: 'R', symbol: 'b' },        // write 'b', move right
+  { movement: 'L', symbol: null },       // keep current symbol, move left
+];
+const reads = ['a', 'x'];
+const blanks = [' ', ' '];
+const matchKinds = ['literal', 'wildcard'] as const;
+
+formatStepNotation(reads, commands, blanks, matchKinds);
+// => "['a',*='x'] → ['b',K='x']/[R,L]"
+```
+
+For manual-Apply rendering (no transition fired), pass `reads: null`:
+
+```ts
+formatStepNotation(null, [{ movement: 'R', symbol: 'b' }], [' '], null);
+// => "['b']/[R]"
+```
+
+## Example: tokenize for custom (non-string) rendering
+
+```ts
+import { tokenizeStep } from '@turing-machine-js/visuals';
+
+const tokens = tokenizeStep(['a'], [{ movement: 'R', symbol: 'b' }], [' '], ['literal']);
+// tokens.reads:  [{ kind: 'literal', symbol: 'a' }]
+// tokens.writes: [{ kind: 'literal', symbol: 'b' }]
+// tokens.moves:  ['R']
+
+// Now render however you want — HTML spans with CSS classes, ANSI escapes, JSON, etc.
+function readToHtml(t: typeof tokens.reads[0]) {
+  if (t.kind === 'wildcard') return `<span class="cell-wildcard">${t.symbol}</span>`;
+  if (t.kind === 'blank') return `<span class="cell-blank">␣</span>`;
+  return `<span class="cell-literal">${t.symbol}</span>`;
+}
+```
+
+## Example: recording a snippet
+
+```ts
+import { recordSnippet, formatStep } from '@turing-machine-js/visuals';
+import {
+  Alphabet, Tape, TapeBlock, TuringMachine, State, haltState, movements,
+} from '@turing-machine-js/machine';
+
+const alphabet = new Alphabet([' ', 'a', 'b']);
+const tape = new Tape({ alphabet, symbols: ['a', 'a', 'a'] });
+const tapeBlock = TapeBlock.fromTapes([tape]);
+const machine = new TuringMachine({ tapeBlock });
+const initialState = new State({
+  [tapeBlock.symbol(['a'])]: { command: [{ symbol: 'b', movement: movements.right }] },
+  [tapeBlock.symbol([' '])]: { nextState: haltState },
+});
+
+const snippet = recordSnippet({
+  machine,
+  initialState,
+  graph: State.toGraph(initialState, tapeBlock),
+  alphabets: [[' ', 'a', 'b']],
+  name: 'replace a with b',
+  log: (m) => formatStep(m),
+});
+
+// snippet.frames[0]    — initial state (no commands, highlight null)
+// snippet.frames[N]    — post-iter snapshot with per-tape commands { movement, read, write }
+//                        and a graph highlight ready to feed applyHighlight()
+// snippet.graph        — the same Graph the player should render
+// snippet.alphabets    — per-tape alphabet symbols (single-tape: length 1)
+```
+
+`Frame.commands` carries both `read` and `write` per tape so a player can step forward (write `write`, move per `movement`, flash if `write !== read`) AND backward (move opposite of `movement`, restore `read`) without diffing neighbouring frames.
+
+## Versioning
+
+Engine + builder + libraries bump in **lockstep** via `lerna version`. **Visuals breaks lockstep for additive consumer-package patches** (e.g., `7.0.0-alpha.6.1` added formatter primitives + the token surface without bumping the engine — there were no engine changes to justify ghost releases). Semver-prerelease caret semantics make this safe: peer `^7.0.0-alpha.6` accepts `7.0.0-alpha.6.1+` without consumers having to widen anything. When the next engine alpha needs to ship, all 5 packages bump back to lockstep.
+
+## License
+
+[GPL-3.0-or-later](../../LICENSE)

From 6afe7f4df427c3f20b063e3deeb8a4989a1f41a5 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 20:19:32 +0300
Subject: [PATCH 101/118] fix(machine): toGraph reach-set tunnels through
 wrappers to their continuation (#223)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pre-#223 the bare-reachability sweep stopped dead at wrappers (isWrapper
hard boundary at stateGraph.ts:193 + 202). Continuation states reached
only via a wrapper return arrow ended up unframed: they rendered outside
the bare's subgraph and their halt-bound transitions stayed pointing at
top-level halt instead of the bare's frame halt marker.

Wrappers are call-site markers — semantically owned by the caller. A
wrapper's overriddenHaltStateId is the state the caller's body resumes
at after the inner subroutine call returns. The fix introduces a
resolveAndPush helper that tunnels through wrappers (transitively, for
nested wohs chains) and pushes the continuation onto the reach-stack;
the wrapper node itself stays unframed (correctly — it's not body).

Two new test cases in graph.spec.ts pin the behavior:
- after-return continuation joins the bare frame; halt-bound transitions
  retarget to the frame halt marker, not to top-level s0
- wrapper-chain continuations tunnel multi-hop (continuation IS another
  wrapper, nested wohs composition)

644 tests pass (was 642). Coverage held at 99.53/96.47/100/100 on
stateGraph.ts.
---
 packages/machine/src/utilities/graph.spec.ts | 117 +++++++++++++++++++
 packages/machine/src/utilities/stateGraph.ts |  76 ++++++++----
 2 files changed, 170 insertions(+), 23 deletions(-)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index a454820..b19d970 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -635,6 +635,123 @@ describe('README diagrams: engine-generated outputs', () => {
 //     path compression + ufUnion)
 //   - `callable scope: A ∪ B` subgraph label (graphFormats frameBareNames sort)
 //   - `-. "halt" .->` demand-emit arrow (graphFormats hasNonWrapperEntry path)
+describe('callable-subtree: wrapper continuation joins caller frame (#223)', () => {
+  // When a bare's body invokes a sub-call via `withOverriddenHaltState`, the
+  // wrapper's continuation (the `--> override` arrow in the rendered diagram,
+  // sourced from `overriddenHaltStateId`) is the state the bare's body resumes
+  // at after the inner call returns. Pre-#223 the reach-set sweep stopped
+  // dead at the wrapper, leaving the continuation unframed: it rendered
+  // outside the subgraph and its halt-bound transitions kept pointing at the
+  // top-level halt instead of the bare's frame halt marker. Post-#223, the
+  // sweep tunnels through wrappers via their continuation, so the continuation
+  // (and any further body states it reaches) join the bare's frame.
+  test('after-return continuation state is in the bare frame; its halt retargets to the frame halt marker', () => {
+    const alphabet = new Alphabet([' ', 'a', 'b']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+    const {symbol} = tapeBlock;
+
+    // Inner subroutine X: halts on any symbol (just exists to be called).
+    const X = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'X');
+
+    // Continuation Y: invertNumberGoToNumberWithInversion-shaped — A's bare
+    // returns here after X halts. Y itself halts on 'b' (this halt should
+    // retarget to A's frame halt marker post-#223).
+    const Y = new State({
+      [symbol(['b'])]: {command: {movement: movements.stay}, nextState: haltState},
+      [ifOtherSymbol]: {command: {movement: movements.right}, nextState: haltState},
+    }, 'Y');
+
+    // Bare A: on 'a', calls X with Y as the continuation. Mirrors the
+    // s11 → s10 (= goToNumberStart(invertNumberGoToNumberWithInversion))
+    // shape from library-binary-numbers' invertNumber inside minusOne.
+    const A = new State({
+      [symbol(['a'])]: {command: {movement: movements.stay}, nextState: X.withOverriddenHaltState(Y)},
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'A');
+
+    // Outer wrapper to give A its own frame (A is the bare of this wrapper).
+    const aftermath = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'aftermath');
+
+    const dispatcher = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: A.withOverriddenHaltState(aftermath)},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+
+    const nodeA = graph.nodes[A.id];
+    const nodeY = graph.nodes[Y.id];
+
+    // A is a bare → has its own frame.
+    expect(nodeA.frameId).not.toBeNull();
+    // The continuation Y joins A's frame (the fix).
+    expect(nodeY.frameId).toBe(nodeA.frameId);
+
+    // Y's halt-bound transitions retarget to A's frame halt marker
+    // (id = -frameId, isHaltMarker), NOT to top-level halt s0.
+    for (const t of nodeY.transitions) {
+      const targetNode = graph.nodes[t.nextStateId];
+      expect(targetNode.isHaltMarker).toBe(true);
+      expect(targetNode.frameId).toBe(nodeA.frameId);
+      expect(t.nextStateId).toBe(-nodeA.frameId!);
+    }
+
+    // Sanity: top-level halt s0 is still emitted as a sentinel, even though
+    // no in-frame transition points to it any more.
+    expect(graph.nodes[0]).toBeDefined();
+    expect(graph.nodes[0].isHalt).toBe(true);
+    expect(graph.nodes[0].isHaltMarker).toBe(false);
+  });
+
+  test('wrapper-chain continuations tunnel multi-hop (continuation IS another wrapper)', () => {
+    const alphabet = new Alphabet([' ', 'a']);
+    const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+
+    // Three inner subroutines X1 / X2 — each halts on any.
+    const X1 = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'X1');
+    const X2 = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'X2');
+
+    // Final continuation Z, with a halt-bound transition.
+    const Z = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'Z');
+
+    // Bare A's body: calls X1 with continuation = X2.wohs(Z). Reach traversal
+    // from A must tunnel through TWO wrappers (X1's wrapper → X2.wohs(Z)
+    // wrapper → Z) to land on Z.
+    const A = new State({
+      [ifOtherSymbol]: {
+        command: {movement: movements.stay},
+        nextState: X1.withOverriddenHaltState(X2.withOverriddenHaltState(Z)),
+      },
+    }, 'A');
+
+    const aftermath = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: haltState},
+    }, 'aftermath');
+
+    const dispatcher = new State({
+      [ifOtherSymbol]: {command: {movement: movements.stay}, nextState: A.withOverriddenHaltState(aftermath)},
+    }, 'dispatcher');
+
+    const graph = State.toGraph(dispatcher, tapeBlock);
+
+    const nodeA = graph.nodes[A.id];
+    const nodeZ = graph.nodes[Z.id];
+
+    expect(nodeA.frameId).not.toBeNull();
+    // Z is reached through a 2-hop wrapper chain — must still land in A's frame.
+    expect(nodeZ.frameId).toBe(nodeA.frameId);
+  });
+});
+
 describe('callable-subtree: shared body state forces a union frame', () => {
   test('two bares sharing a body state merge into one frame; non-wrapper entry triggers halt arrow', () => {
     const alphabet = new Alphabet([' ', '1', '2', '3', 'X']);
diff --git a/packages/machine/src/utilities/stateGraph.ts b/packages/machine/src/utilities/stateGraph.ts
index 8509b4d..8bbe380 100644
--- a/packages/machine/src/utilities/stateGraph.ts
+++ b/packages/machine/src/utilities/stateGraph.ts
@@ -169,41 +169,71 @@ export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
   }
 
   // Pass 2: For each bare, compute its forward-reachable set (following
-  // transitions; stopping at halt and at wrappers — both are frame
-  // boundaries).
+  // transitions; stopping at halt; tunneling through wrappers to their
+  // `overriddenHaltStateId` continuation).
+  //
+  // Wrappers are call-site markers — semantically owned by the caller. A
+  // wrapper's continuation (its `--> override` arrow in the rendered
+  // diagram, sourced from `overriddenHaltStateId`) is the state the
+  // caller's body resumes at AFTER the inner subroutine call returns. So
+  // when reach traversal hits a wrapper, we don't stop — we follow the
+  // continuation back into the caller's frame. The wrapper node itself
+  // stays unframed (it renders outside the subgraph as a call site), but
+  // the continuation joins the caller's reach-set.
+  //
+  // Halt-bound retargeting + union-find then "just work": continuation
+  // states' halt-bound transitions get retargeted to the caller's halt
+  // marker (so an in-subroutine halt returns to the caller, not the
+  // program's terminal halt); when two bares both reach the same
+  // continuation through different wrapper chains, union-find merges
+  // their frames as it already does for non-wrapper overlap.
+  //
+  // Wrapper chains (continuation IS another wrapper, e.g., nested
+  // compositions) are walked transitively by the inner while-loop in
+  // `resolveAndPush`.
   const computeReach = (startId: number): Set<number> => {
     const reach = new Set<number>();
-    const stack = [startId];
+    const stack: number[] = [];
 
-    while (stack.length > 0) {
-      const id = stack.pop()!;
+    const resolveAndPush = (id: number) => {
+      let current = id;
 
-      if (reach.has(id)) {
-        continue;
+      while (true) {
+        const target = nodes[current];
+
+        if (!target || target.isHalt) {
+          return;
+        }
+
+        if (!target.isWrapper) {
+          stack.push(current);
+          return;
+        }
+
+        /* c8 ignore next 3 — every wrapper emitted by Pass 1 has a
+           non-null overriddenHaltStateId (lines 76-101); this branch
+           only guards against future wrapper variants that might not. */
+        if (target.overriddenHaltStateId === null) {
+          return;
+        }
+
+        current = target.overriddenHaltStateId;
       }
+    };
+
+    resolveAndPush(startId);
 
-      const node = nodes[id];
+    while (stack.length > 0) {
+      const id = stack.pop()!;
 
-      // `nodes[id]` is always populated for `id` that the BFS reached, so
-      // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
-      // are real boundaries — both stop reach-set expansion.
-      /* c8 ignore next 3 — defensive: the push site below already filters
-         halt/wrapper targets, and the initial push is always a bare, so
-         this branch is unreachable in practice. */
-      if (node.isHalt || node.isWrapper) {
+      if (reach.has(id)) {
         continue;
       }
 
       reach.add(id);
 
-      for (const t of node.transitions) {
-        const target = nodes[t.nextStateId];
-
-        if (!target || target.isHalt || target.isWrapper) {
-          continue;
-        }
-
-        stack.push(t.nextStateId);
+      for (const t of nodes[id].transitions) {
+        resolveAndPush(t.nextStateId);
       }
     }
 

From 815c2c71dbd4ab1570607b85b47e3861813a8467 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 20:19:33 +0300
Subject: [PATCH 102/118] docs(states): regenerate
 library-binary-numbers/states.md after #223 fix

minusOne's invertNumber subgraph (w_11) now correctly contains its body
state s9 (invertNumberGoToNumberWithInversion), and s9's halt-bound
transition on '$' retargets from top-level s0 to invertNumber's frame
halt marker c11. Other diagrams unchanged (no inner-wrapper-call
pattern). library-binary-numbers-bare/states.md unchanged for the same
reason.
---
 packages/library-binary-numbers/states.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 4d61d88..47fe2be 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -190,7 +190,6 @@ flowchart TD
 %% alphabets: [[" ","^","$","0","1"]]
   s0(((halt)))
   s1["goToNumber"]
-  s9["invertNumberGoToNumberWithInversion"]
   s12["normalizeNumberPutNewStartSymbol"]
   s13["normalizeNumberMoveNumberStart"]
   s15["normalizeNumber"]
@@ -206,6 +205,7 @@ flowchart TD
     c5(((halt)))
   end
   subgraph w_11["callable subtree of invertNumber"]
+    s9["invertNumberGoToNumberWithInversion"]
     s11["invertNumber"]
     c11(((halt)))
   end
@@ -235,7 +235,7 @@ flowchart TD
   s9 -- "['^'] → [K]/[R]" --> s9
   s9 -- "['1'] → ['0']/[R]" --> s9
   s9 -- "['0'] → ['1']/[R]" --> s9
-  s9 -- "['$'] → [K]/[S]" --> s0
+  s9 -- "['$'] → [K]/[S]" --> c11
   s11 -- "['^']|['1']|['0']|['$'] → [K]/[S]" --> s10
   s11 -- "[*] → [K]/[S]" --> c11
   s12 -- "[B] → ['^']/[S]" --> s1

From a73041b01214b0c4d4d81c0e3a7a9f4c53251c91 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 20:31:04 +0300
Subject: [PATCH 103/118] fix(machine): framed wrappers render inside caller's
 subgraph too (#223 follow-up)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first #223 fix put continuation states (e.g., invertNumber's s9)
inside the caller's frame, but left wrappers themselves (e.g., s10,
the goToNumberStart-call-site that invertNumber's body owns) outside
all subgraphs. Visually inconsistent: the transition s11 -- ... --> s10
crossed the w_11 subgraph boundary even though s10 IS invertNumber's
call site.

Wrappers are call-site markers semantically owned by the caller. They
belong in the caller's subgraph alongside the bare and body states.

Two changes:

1. stateGraph.ts resolveAndPush: in addition to tunneling to the
   wrapper's continuation, push the wrapper onto the reach-stack so it
   joins the bare's frame via Pass 3 union-find. (Wrappers have empty
   transitions arrays per Pass 1, so popping them from the stack adds
   them to reach without further traversal.)

2. graphFormats.ts emit: stop excluding wrappers from nodesByFrame
   bucketing. Top-level wrappers (those whose caller has no frame —
   the top-level program) still emit at top level via the existing
   wrapper-emit section; framed wrappers (whose caller IS a subroutine
   with its own frame) now emit inside that subgraph with the
   [[name]] wrapper shape.

Strengthened the #223 test in graph.spec.ts:
- asserts the wrapper inside A's body (bareStateId === X.id) gets
  A's frameId
- asserts the wrapper around A (bareStateId === A.id) stays unframed
  (it's owned by the top-level dispatcher)
- asserts toMermaid emits the framed wrapper inside the subgraph with
  the [[…]] wrapper shape

644 tests pass (unchanged count, strengthened assertions). Coverage
held at 99.69/95.93/100/100 (graphFormats) + 99.53/96.47/100/100
(stateGraph).
---
 packages/machine/src/utilities/graph.spec.ts  | 22 +++++++++++
 .../machine/src/utilities/graphFormats.ts     | 25 ++++++++++---
 packages/machine/src/utilities/stateGraph.ts  | 37 ++++++++++++-------
 3 files changed, 65 insertions(+), 19 deletions(-)

diff --git a/packages/machine/src/utilities/graph.spec.ts b/packages/machine/src/utilities/graph.spec.ts
index b19d970..212912a 100644
--- a/packages/machine/src/utilities/graph.spec.ts
+++ b/packages/machine/src/utilities/graph.spec.ts
@@ -690,6 +690,21 @@ describe('callable-subtree: wrapper continuation joins caller frame (#223)', ()
     // The continuation Y joins A's frame (the fix).
     expect(nodeY.frameId).toBe(nodeA.frameId);
 
+    // The wrapper itself (the call site that A's body invokes) ALSO joins
+    // A's frame — wrappers are call-site markers semantically owned by the
+    // caller, so they render inside the caller's subgraph.
+    const wrapperNodes = Object.values(graph.nodes).filter((n) => n.isWrapper);
+    // Two wrappers in this graph: the dispatcher's wohs(A, aftermath) AND
+    // A's body's wohs(X, Y). The latter (bareStateId === X.id) is the one
+    // owned by A. The former (bareStateId === A.id) is owned by the
+    // top-level dispatcher and stays unframed.
+    const wrapperInsideA = wrapperNodes.find((w) => w.bareStateId === X.id);
+    const wrapperAroundA = wrapperNodes.find((w) => w.bareStateId === A.id);
+    expect(wrapperInsideA).toBeDefined();
+    expect(wrapperAroundA).toBeDefined();
+    expect(wrapperInsideA!.frameId).toBe(nodeA.frameId);
+    expect(wrapperAroundA!.frameId).toBeNull();
+
     // Y's halt-bound transitions retarget to A's frame halt marker
     // (id = -frameId, isHaltMarker), NOT to top-level halt s0.
     for (const t of nodeY.transitions) {
@@ -704,6 +719,13 @@ describe('callable-subtree: wrapper continuation joins caller frame (#223)', ()
     expect(graph.nodes[0]).toBeDefined();
     expect(graph.nodes[0].isHalt).toBe(true);
     expect(graph.nodes[0].isHaltMarker).toBe(false);
+
+    // Mermaid emit: the framed wrapper renders INSIDE A's subgraph (with
+    // the `[[name]]` wrapper shape), not at top level.
+    const out = toMermaid(graph);
+    expect(out).toMatch(new RegExp(
+      `subgraph w_${nodeA.frameId}\\[[^\\n]*\\n(?:[^\\n]*\\n)*?\\s+s${wrapperInsideA!.id}\\[\\[`,
+    ));
   });
 
   test('wrapper-chain continuations tunnel multi-hop (continuation IS another wrapper)', () => {
diff --git a/packages/machine/src/utilities/graphFormats.ts b/packages/machine/src/utilities/graphFormats.ts
index d2231e4..24484c9 100644
--- a/packages/machine/src/utilities/graphFormats.ts
+++ b/packages/machine/src/utilities/graphFormats.ts
@@ -136,15 +136,21 @@ export function toMermaid(graph: Graph): string {
 
   // Bucket nodes for emit order.
   const topLevelNodes = nodes.filter((n) => n.frameId === null && !n.isWrapper);
+  // All wrappers — needed by the call / return / wrapper-to-override
+  // arrow emit passes below regardless of where the wrapper renders.
   const wrapperNodes = nodes.filter((n) => n.isWrapper);
-  // Bares-and-bodies inside frames, grouped by frameId.
+  // Top-level wrappers: wrappers whose caller has no frame (the caller is
+  // the top-level program). Framed wrappers (whose caller IS a subroutine
+  // with its own frame) render INSIDE that frame's subgraph below.
+  const topLevelWrapperNodes = wrapperNodes.filter((w) => w.frameId === null);
+  // Bares-bodies-and-framed-wrappers inside frames, grouped by frameId.
   const nodesByFrame = new Map<number, GraphNode[]>();
   // Halt-marker per frame (kept separate so it always emits LAST inside the
   // subgraph for deterministic shape).
   const haltMarkerByFrame = new Map<number, GraphNode>();
 
   for (const node of nodes) {
-    if (node.frameId === null || node.isWrapper) continue;
+    if (node.frameId === null) continue;
 
     if (node.isHaltMarker) {
       haltMarkerByFrame.set(node.frameId, node);
@@ -190,8 +196,9 @@ export function toMermaid(graph: Graph): string {
     }
   }
 
-  // 2. Emit wrappers at top level.
-  for (const wrapper of wrapperNodes) {
+  // 2. Emit top-level wrappers (wrappers owned by the top-level program;
+  // wrappers owned by a subroutine emit inside that subroutine's subgraph).
+  for (const wrapper of topLevelWrapperNodes) {
     lines.push(`  ${mermaidIdFor(wrapper.id)}[["${labelOf(wrapper)}"]]`);
   }
 
@@ -215,9 +222,15 @@ export function toMermaid(graph: Graph): string {
 
     lines.push(`  subgraph ${frameSubgraphId(frameId)}["${label}"]`);
 
-    // Inner nodes — sort by id for determinism.
+    // Inner nodes — sort by id for determinism. Framed wrappers (call sites
+    // owned by this frame) render with the `[[name]]` wrapper shape; bares
+    // and body states render with the regular `["name"]` shape.
     for (const node of (nodesByFrame.get(frameId) ?? []).slice().sort((a, b) => a.id - b.id)) {
-      lines.push(`    ${mermaidIdFor(node.id)}["${labelOf(node)}"]`);
+      if (node.isWrapper) {
+        lines.push(`    ${mermaidIdFor(node.id)}[["${labelOf(node)}"]]`);
+      } else {
+        lines.push(`    ${mermaidIdFor(node.id)}["${labelOf(node)}"]`);
+      }
     }
 
     // Every frame has a halt marker — `State.toGraph`'s frame-emit pass
diff --git a/packages/machine/src/utilities/stateGraph.ts b/packages/machine/src/utilities/stateGraph.ts
index 8bbe380..dc82803 100644
--- a/packages/machine/src/utilities/stateGraph.ts
+++ b/packages/machine/src/utilities/stateGraph.ts
@@ -169,28 +169,33 @@ export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
   }
 
   // Pass 2: For each bare, compute its forward-reachable set (following
-  // transitions; stopping at halt; tunneling through wrappers to their
-  // `overriddenHaltStateId` continuation).
+  // transitions; stopping at halt; including wrappers AND tunneling through
+  // them to their `overriddenHaltStateId` continuation).
   //
-  // Wrappers are call-site markers — semantically owned by the caller. A
-  // wrapper's continuation (its `--> override` arrow in the rendered
-  // diagram, sourced from `overriddenHaltStateId`) is the state the
-  // caller's body resumes at AFTER the inner subroutine call returns. So
-  // when reach traversal hits a wrapper, we don't stop — we follow the
-  // continuation back into the caller's frame. The wrapper node itself
-  // stays unframed (it renders outside the subgraph as a call site), but
-  // the continuation joins the caller's reach-set.
+  // Wrappers are call-site markers — semantically owned by the CALLER (the
+  // bare whose body invokes the sub-call). Both the wrapper itself and its
+  // continuation (its `--> override` arrow in the rendered diagram, sourced
+  // from `overriddenHaltStateId`) belong to the caller's frame: the wrapper
+  // visually anchors the call site inside the caller's subgraph; the
+  // continuation is the state the caller's body resumes at AFTER the inner
+  // sub-call returns. So when reach traversal hits a wrapper, we PUSH the
+  // wrapper (joining the caller's reach-set) AND tunnel through to its
+  // continuation (also joining). Wrappers carry no `transitions` of their
+  // own (Pass 1 emits `transitions: []` on wrapper nodes), so the main loop
+  // pops them and adds them to `reach` without further traversal — but the
+  // continuation already entered via the wrapper-tunnel chain in
+  // `resolveAndPush`.
   //
   // Halt-bound retargeting + union-find then "just work": continuation
   // states' halt-bound transitions get retargeted to the caller's halt
   // marker (so an in-subroutine halt returns to the caller, not the
   // program's terminal halt); when two bares both reach the same
-  // continuation through different wrapper chains, union-find merges
-  // their frames as it already does for non-wrapper overlap.
+  // continuation through different wrapper chains, union-find merges their
+  // frames as it already does for non-wrapper overlap.
   //
   // Wrapper chains (continuation IS another wrapper, e.g., nested
   // compositions) are walked transitively by the inner while-loop in
-  // `resolveAndPush`.
+  // `resolveAndPush` — each tunnel hop pushes the intermediate wrapper.
   const computeReach = (startId: number): Set<number> => {
     const reach = new Set<number>();
     const stack: number[] = [];
@@ -210,6 +215,10 @@ export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
           return;
         }
 
+        // Wrapper: push it (so it joins the caller's frame) AND tunnel to
+        // its continuation. Both belong to the caller's frame.
+        stack.push(current);
+
         /* c8 ignore next 3 — every wrapper emitted by Pass 1 has a
            non-null overriddenHaltStateId (lines 76-101); this branch
            only guards against future wrapper variants that might not. */
@@ -232,6 +241,8 @@ export function toGraph(initialState: State, tapeBlock: TapeBlock): Graph {
 
       reach.add(id);
 
+      // Wrappers have empty transitions arrays — the for-loop runs zero
+      // iterations and we proceed to the next stack entry.
       for (const t of nodes[id].transitions) {
         resolveAndPush(t.nextStateId);
       }

From 93d50d8f2b2f0da77977f4d013b83b293c699888 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 20:31:04 +0300
Subject: [PATCH 104/118] =?UTF-8?q?docs(states):=20regenerate=20library-bi?=
 =?UTF-8?q?nary-numbers/states.md=20=E2=80=94=20wrapper=20s10=20now=20insi?=
 =?UTF-8?q?de=20w=5F11?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

minusOne's invertNumber subgraph now contains BOTH its body state
s9 AND its call-site wrapper s10
(goToNumberStart(invertNumberGoToNumberWithInversion)). The wrapper
visually anchors the call site inside the caller's subgraph; the
s11 --> s10 transition is now entirely within w_11.
---
 packages/library-binary-numbers/states.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/library-binary-numbers/states.md b/packages/library-binary-numbers/states.md
index 47fe2be..faf056f 100644
--- a/packages/library-binary-numbers/states.md
+++ b/packages/library-binary-numbers/states.md
@@ -194,7 +194,6 @@ flowchart TD
   s13["normalizeNumberMoveNumberStart"]
   s15["normalizeNumber"]
   s23["minusOne"]
-  s10[["goToNumberStart(invertNumberGoToNumberWithInversion)"]]
   s14[["goToNumberStart(normalizeNumberMoveNumberStart)"]]
   s20[["invertNumber(normalizeNumber)"]]
   s21[["plusOne(invertNumber(normalizeNumber))"]]
@@ -206,6 +205,7 @@ flowchart TD
   end
   subgraph w_11["callable subtree of invertNumber"]
     s9["invertNumberGoToNumberWithInversion"]
+    s10[["goToNumberStart(invertNumberGoToNumberWithInversion)"]]
     s11["invertNumber"]
     c11(((halt)))
   end

From 199b5bc9a05be1040c8babc856a27fbcf12a32d2 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 20:50:42 +0300
Subject: [PATCH 105/118] docs(machine): hedge wrapper-placement prose for
 framed wrappers (#223)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The scanToX example bullet and the toMermaid node-shape legend both
claimed wrappers were drawn "outside any subgraph" — true before the
#223 fix, but framed wrappers (continuation chain participates in a
caller's frame) now render INSIDE the owner frame's subgraph using the
same [[…]] shape. Soften both statements with a pointer to #223.
---
 packages/machine/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/machine/README.md b/packages/machine/README.md
index ee12ea2..f0bd58d 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -449,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.
@@ -756,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) |
 

From 88aa72e4fb24a0929db6b118620979f3153449ed Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 21:58:48 +0300
Subject: [PATCH 106/118] chore(release): 7.0.0-alpha.7

---
 lerna.json                                     |  2 +-
 package-lock.json                              | 18 +++++++++---------
 packages/builder/CHANGELOG.md                  |  4 ++++
 packages/builder/package.json                  |  4 ++--
 .../library-binary-numbers-bare/CHANGELOG.md   |  4 ++++
 .../library-binary-numbers-bare/package.json   |  4 ++--
 packages/library-binary-numbers/CHANGELOG.md   |  4 ++++
 packages/library-binary-numbers/package.json   |  4 ++--
 packages/machine/CHANGELOG.md                  | 14 ++++++++++++++
 packages/machine/package.json                  |  2 +-
 packages/visuals/CHANGELOG.md                  |  4 ++++
 packages/visuals/package.json                  |  4 ++--
 12 files changed, 49 insertions(+), 19 deletions(-)

diff --git a/lerna.json b/lerna.json
index 33d3137..b8cecac 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.6",
+  "version": "7.0.0-alpha.7",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index 6b81efc..93d2329 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10660,40 +10660,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.6",
+      "version": "7.0.0-alpha.7",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.6"
+        "@turing-machine-js/machine": "^7.0.0-alpha.7"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.6",
+      "version": "7.0.0-alpha.7",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.6"
+        "@turing-machine-js/machine": "^7.0.0-alpha.7"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.6",
+      "version": "7.0.0-alpha.7",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.6"
+        "@turing-machine-js/machine": "^7.0.0-alpha.7"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.6",
+      "version": "7.0.0-alpha.7",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
@@ -10701,13 +10701,13 @@
     },
     "packages/visuals": {
       "name": "@turing-machine-js/visuals",
-      "version": "7.0.0-alpha.6.1",
+      "version": "7.0.0-alpha.7",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.6"
+        "@turing-machine-js/machine": "^7.0.0-alpha.7"
       }
     }
   }
diff --git a/packages/builder/CHANGELOG.md b/packages/builder/CHANGELOG.md
index ec431c7..a94ae43 100644
--- a/packages/builder/CHANGELOG.md
+++ b/packages/builder/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.7 — adds `CallFrame` as a first-class `State` subclass ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) and fixes a `toMermaid` framed-wrapper emit asymmetry ([#223](https://github.com/mellonis/turing-machine-js/issues/223)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
+
 ## [7.0.0-alpha.6] - 2026-05-28
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.6 — adds the `DebugSession` interactive-debugging class and reshapes the engine debug surface: `run()` becomes synchronous + callback-free, `runStepByStep` becomes the pure-iteration primitive (no breakpoint detection), and the per-yield `m.debugBreak` is replaced by a one-sided `m.pause: { side, cause }` carried on `DebugSession` `pause` events ([#102](https://github.com/mellonis/turing-machine-js/issues/102)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.5` → `^7.0.0-alpha.6`.
diff --git a/packages/builder/package.json b/packages/builder/package.json
index 5799900..d50feed 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.6",
+  "version": "7.0.0-alpha.7",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+    "@turing-machine-js/machine": "^7.0.0-alpha.7"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/CHANGELOG.md b/packages/library-binary-numbers-bare/CHANGELOG.md
index 8e54e6e..ff0690f 100644
--- a/packages/library-binary-numbers-bare/CHANGELOG.md
+++ b/packages/library-binary-numbers-bare/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.7 — adds `CallFrame` as a first-class `State` subclass ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) and fixes a `toMermaid` framed-wrapper emit asymmetry ([#223](https://github.com/mellonis/turing-machine-js/issues/223)). No source or behavior changes in this package — `states.md` is unaffected (no diagram here uses an inner-wrapper-call pattern). Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
+
 ## [7.0.0-alpha.6] - 2026-05-28
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.6 — adds the `DebugSession` interactive-debugging class and reshapes the engine debug surface: `run()` becomes synchronous + callback-free, `runStepByStep` becomes the pure-iteration primitive (no breakpoint detection), and the per-yield `m.debugBreak` is replaced by a one-sided `m.pause: { side, cause }` carried on `DebugSession` `pause` events ([#102](https://github.com/mellonis/turing-machine-js/issues/102)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.5` → `^7.0.0-alpha.6`.
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index 6853044..b4a59d5 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.6",
+  "version": "7.0.0-alpha.7",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+    "@turing-machine-js/machine": "^7.0.0-alpha.7"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/CHANGELOG.md b/packages/library-binary-numbers/CHANGELOG.md
index d8fc7d8..6424503 100644
--- a/packages/library-binary-numbers/CHANGELOG.md
+++ b/packages/library-binary-numbers/CHANGELOG.md
@@ -4,6 +4,10 @@ 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
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.7 — adds `CallFrame` as a first-class `State` subclass ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) and fixes a `toMermaid` framed-wrapper emit asymmetry ([#223](https://github.com/mellonis/turing-machine-js/issues/223)). The `states.md` file is regenerated under the new emit: the `minusOne` diagram's `goToNumberStart(invertNumberGoToNumberWithInversion)` wrapper now renders INSIDE `invertNumber`'s callable subtree (was outside, visually disconnected from its owner frame). No source or behavior changes. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
+
 ## [7.0.0-alpha.6] - 2026-05-28
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.6 — adds the `DebugSession` interactive-debugging class and reshapes the engine debug surface: `run()` becomes synchronous + callback-free, `runStepByStep` becomes the pure-iteration primitive (no breakpoint detection), and the per-yield `m.debugBreak` is replaced by a one-sided `m.pause: { side, cause }` carried on `DebugSession` `pause` events ([#102](https://github.com/mellonis/turing-machine-js/issues/102)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.5` → `^7.0.0-alpha.6`.
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index 4c4bcdb..8cdfece 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.6",
+  "version": "7.0.0-alpha.7",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+    "@turing-machine-js/machine": "^7.0.0-alpha.7"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index cd86cbc..86a46fb 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,20 @@ 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`.
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 445e7f1..6c97062 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.6",
+  "version": "7.0.0-alpha.7",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index fa65f08..933c96a 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to this package 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
+
+Lockstep re-alignment with the engine 7.0.0-alpha.7 bump (engine [#213](https://github.com/mellonis/turing-machine-js/issues/213) `CallFrame` extraction + [#223](https://github.com/mellonis/turing-machine-js/issues/223) `toMermaid` framed-wrapper emit fix). No source or behavior changes in this package since alpha.6.1. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
+
 ## [7.0.0-alpha.6.1] - 2026-05-30
 
 ### Added
diff --git a/packages/visuals/package.json b/packages/visuals/package.json
index 4d1d719..1c39a98 100644
--- a/packages/visuals/package.json
+++ b/packages/visuals/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/visuals",
-  "version": "7.0.0-alpha.6.1",
+  "version": "7.0.0-alpha.7",
   "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "visualization"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+    "@turing-machine-js/machine": "^7.0.0-alpha.7"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/visuals",

From 87868b579c72c85cee72c6db500c54cdd5f441e1 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 22:33:42 +0300
Subject: [PATCH 107/118] =?UTF-8?q?feat(visuals):=20createSnippetPlayer=20?=
 =?UTF-8?q?=E2=80=94=20pure-state=20snippet=20playback=20driver=20(7.0.0-a?=
 =?UTF-8?q?lpha.7.1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 package-lock.json                          |   2 +-
 packages/visuals/CHANGELOG.md              |  11 ++
 packages/visuals/README.md                 |  38 ++++++
 packages/visuals/package.json              |   2 +-
 packages/visuals/src/index.ts              |   1 +
 packages/visuals/src/snippetPlayer.spec.ts | 127 +++++++++++++++++++++
 packages/visuals/src/snippetPlayer.ts      |  75 ++++++++++++
 7 files changed, 254 insertions(+), 2 deletions(-)
 create mode 100644 packages/visuals/src/snippetPlayer.spec.ts
 create mode 100644 packages/visuals/src/snippetPlayer.ts

diff --git a/package-lock.json b/package-lock.json
index 93d2329..dc88f2f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10701,7 +10701,7 @@
     },
     "packages/visuals": {
       "name": "@turing-machine-js/visuals",
-      "version": "7.0.0-alpha.7",
+      "version": "7.0.0-alpha.7.1",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index 933c96a..b6e4b59 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -4,6 +4,17 @@ All notable changes to this package 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.1] - 2026-05-30
+
+### Added
+
+- **`createSnippetPlayer(snippet): SnippetPlayer`** — pure-state playback driver for a `Snippet`. Exposes `currentFrame` / `frameIndex` / `done` getters plus `forward()` / `back()` / `reset()` / `goTo(idx)`. Stateless w.r.t. wall-clock — consumers wire their own ticking (`setInterval`, `requestAnimationFrame`, `IntersectionObserver`); renderer-agnostic — consumers read `currentFrame` and apply it however they like (typically `applyHighlight(snippet.graph, frame.highlight, ops)` for the state graph plus app-specific tape rendering). Each call yields an independent player — the same `Snippet` can drive any number of concurrent players (frame storage is shared and read-only). `forward()` / `back()` return a `boolean` (true if moved, false at end/start — no-op in that case); `goTo(idx)` throws `RangeError` on out-of-bounds.
+
+### Compatibility
+
+- Engine + builder + library-binary-numbers + library-binary-numbers-bare stay at `7.0.0-alpha.7` — no changes there. Visuals-only follow-up patch, mirroring the alpha.6.1 precedent for additive consumer-package enhancements.
+- Peer dep `@turing-machine-js/machine: ^7.0.0-alpha.7` unchanged (semver-prerelease caret already accepts `alpha.7.1`).
+
 ## [7.0.0-alpha.7] - 2026-05-30
 
 Lockstep re-alignment with the engine 7.0.0-alpha.7 bump (engine [#213](https://github.com/mellonis/turing-machine-js/issues/213) `CallFrame` extraction + [#223](https://github.com/mellonis/turing-machine-js/issues/223) `toMermaid` framed-wrapper emit fix). No source or behavior changes in this package since alpha.6.1. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index adf68eb..b02e981 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -102,6 +102,9 @@ formatStep(machineState): string    // alpha.6 MachineState-based formatter; kep
 
 // Recording
 recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }): Snippet
+
+// Playback
+createSnippetPlayer(snippet): SnippetPlayer
 ```
 
 The 16-rule contract `applyHighlight` satisfies is documented at [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md).
@@ -238,6 +241,41 @@ const snippet = recordSnippet({
 
 `Frame.commands` carries both `read` and `write` per tape so a player can step forward (write `write`, move per `movement`, flash if `write !== read`) AND backward (move opposite of `movement`, restore `read`) without diffing neighbouring frames.
 
+## Example: playing a snippet
+
+```ts
+import {
+  applyHighlight, createSnippetPlayer, indexGraph,
+  type HighlightOps, type Snippet,
+} from '@turing-machine-js/visuals';
+
+const player = createSnippetPlayer(snippet);
+const indexes = indexGraph(snippet.graph);
+let prev: Parameters<typeof applyHighlight>[3] = null;
+
+function render(ops: HighlightOps, renderTape: (snap: Snippet['frames'][0]['tape']) => void) {
+  const frame = player.currentFrame;
+  // (consumer wipes previous highlight classes from the DOM before calling)
+  if (frame.highlight) {
+    prev = applyHighlight(frame.highlight, snippet.graph, indexes, prev, ops).nextPrev;
+  }
+  renderTape(frame.tape);
+}
+
+// Auto-play forward at a fixed cadence:
+const id = setInterval(() => {
+  if (!player.forward()) { clearInterval(id); return; }
+  render(ops, renderTape);
+}, 800);
+
+// Bi-directional scrub:
+prevBtn.onclick = () => { if (player.back())    render(ops, renderTape); };
+nextBtn.onclick = () => { if (player.forward()) render(ops, renderTape); };
+replayBtn.onclick = () => { player.reset();     render(ops, renderTape); };
+```
+
+`createSnippetPlayer` is pure state — no timers, no events. Consumers wire `setInterval` / `requestAnimationFrame` / `IntersectionObserver` and call `forward()` / `back()` / `goTo(idx)`. Two players over the same `Snippet` are independent (frame storage is shared and read-only).
+
 ## Versioning
 
 Engine + builder + libraries bump in **lockstep** via `lerna version`. **Visuals breaks lockstep for additive consumer-package patches** (e.g., `7.0.0-alpha.6.1` added formatter primitives + the token surface without bumping the engine — there were no engine changes to justify ghost releases). Semver-prerelease caret semantics make this safe: peer `^7.0.0-alpha.6` accepts `7.0.0-alpha.6.1+` without consumers having to widen anything. When the next engine alpha needs to ship, all 5 packages bump back to lockstep.
diff --git a/packages/visuals/package.json b/packages/visuals/package.json
index 1c39a98..4777674 100644
--- a/packages/visuals/package.json
+++ b/packages/visuals/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/visuals",
-  "version": "7.0.0-alpha.7",
+  "version": "7.0.0-alpha.7.1",
   "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
   "engines": {
     "npm": ">=7.0.0"
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index d142b27..29682b0 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -18,3 +18,4 @@ export {
   type StepTokens,
 } from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';
+export { createSnippetPlayer, type SnippetPlayer } from './snippetPlayer';
diff --git a/packages/visuals/src/snippetPlayer.spec.ts b/packages/visuals/src/snippetPlayer.spec.ts
new file mode 100644
index 0000000..4804ed2
--- /dev/null
+++ b/packages/visuals/src/snippetPlayer.spec.ts
@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import {
+  Alphabet,
+  State,
+  Tape,
+  TapeBlock,
+  TuringMachine,
+  haltState,
+  ifOtherSymbol,
+  movements,
+} from '@turing-machine-js/machine';
+import { recordSnippet } from './recordSnippet';
+import { createSnippetPlayer } from './snippetPlayer';
+import type { Snippet } from './types';
+
+function buildTwoAMachine() {
+  const alphabet = new Alphabet([' ', 'a', 'b']);
+  const tape = new Tape({ alphabet, symbols: ['a', 'a'] });
+  const tapeBlock = TapeBlock.fromTapes([tape]);
+  const machine = new TuringMachine({ tapeBlock });
+  const initialState = new State({
+    [tapeBlock.symbol(['a'])]: {
+      command: [{ symbol: 'b', movement: movements.right }],
+    },
+    [ifOtherSymbol]: { nextState: haltState },
+  });
+  const graph = State.toGraph(initialState, tapeBlock);
+  const alphabets = [alphabet.symbols.filter((s) => s !== alphabet.blankSymbol).concat(alphabet.blankSymbol)];
+  return { machine, initialState, graph, alphabets };
+}
+
+function buildSnippet(): Snippet {
+  const { machine, initialState, graph, alphabets } = buildTwoAMachine();
+  return recordSnippet({ machine, initialState, graph, alphabets });
+}
+
+describe('createSnippetPlayer', () => {
+  it('throws if the snippet has no frames', () => {
+    const empty: Snippet = { version: 1, graph: {} as never, alphabets: [], frames: [] };
+    expect(() => createSnippetPlayer(empty)).toThrow(/no frames/);
+  });
+
+  it('starts at frame 0', () => {
+    const p = createSnippetPlayer(buildSnippet());
+    expect(p.frameIndex).toBe(0);
+    expect(p.currentFrame.step).toBe(0);
+  });
+
+  it('done is true only at the last frame', () => {
+    const snippet = buildSnippet();
+    const p = createSnippetPlayer(snippet);
+    expect(p.done).toBe(false);
+    while (p.forward()) { /* advance */ }
+    expect(p.frameIndex).toBe(snippet.frames.length - 1);
+    expect(p.done).toBe(true);
+  });
+
+  it('forward advances and returns true; returns false at end', () => {
+    const snippet = buildSnippet();
+    const p = createSnippetPlayer(snippet);
+    for (let i = 1; i < snippet.frames.length; i += 1) {
+      expect(p.forward()).toBe(true);
+      expect(p.frameIndex).toBe(i);
+    }
+    expect(p.forward()).toBe(false);
+    expect(p.frameIndex).toBe(snippet.frames.length - 1);
+  });
+
+  it('back retreats and returns true; returns false at start', () => {
+    const snippet = buildSnippet();
+    const p = createSnippetPlayer(snippet);
+    p.goTo(snippet.frames.length - 1);
+    for (let i = snippet.frames.length - 2; i >= 0; i -= 1) {
+      expect(p.back()).toBe(true);
+      expect(p.frameIndex).toBe(i);
+    }
+    expect(p.back()).toBe(false);
+    expect(p.frameIndex).toBe(0);
+  });
+
+  it('reset returns to frame 0', () => {
+    const p = createSnippetPlayer(buildSnippet());
+    p.forward();
+    p.forward();
+    p.reset();
+    expect(p.frameIndex).toBe(0);
+    expect(p.done).toBe(false);
+  });
+
+  it('goTo jumps to a specific frame', () => {
+    const snippet = buildSnippet();
+    const p = createSnippetPlayer(snippet);
+    p.goTo(snippet.frames.length - 1);
+    expect(p.frameIndex).toBe(snippet.frames.length - 1);
+    expect(p.currentFrame).toBe(snippet.frames[snippet.frames.length - 1]);
+    p.goTo(0);
+    expect(p.frameIndex).toBe(0);
+  });
+
+  it('goTo throws RangeError on out-of-bounds index', () => {
+    const snippet = buildSnippet();
+    const p = createSnippetPlayer(snippet);
+    expect(() => p.goTo(-1)).toThrow(RangeError);
+    expect(() => p.goTo(snippet.frames.length)).toThrow(RangeError);
+    expect(() => p.goTo(1.5)).toThrow(RangeError);
+  });
+
+  it('currentFrame is a live getter — reflects index changes', () => {
+    const snippet = buildSnippet();
+    const p = createSnippetPlayer(snippet);
+    const first = p.currentFrame;
+    p.forward();
+    const second = p.currentFrame;
+    expect(first).not.toBe(second);
+    expect(second).toBe(snippet.frames[1]);
+  });
+
+  it('two players over the same snippet are independent', () => {
+    const snippet = buildSnippet();
+    const a = createSnippetPlayer(snippet);
+    const b = createSnippetPlayer(snippet);
+    a.forward();
+    a.forward();
+    expect(a.frameIndex).toBe(2);
+    expect(b.frameIndex).toBe(0);
+  });
+});
diff --git a/packages/visuals/src/snippetPlayer.ts b/packages/visuals/src/snippetPlayer.ts
new file mode 100644
index 0000000..602540e
--- /dev/null
+++ b/packages/visuals/src/snippetPlayer.ts
@@ -0,0 +1,75 @@
+import type { Frame, Snippet } from './types';
+
+/**
+ * Pure-state playback driver for a `Snippet` produced by `recordSnippet`.
+ *
+ * Holds the current frame index and exposes forward / back / reset / goTo.
+ * Stateless w.r.t. wall-clock — consumers wire their own ticking
+ * (`setInterval`, `requestAnimationFrame`, `IntersectionObserver`, etc.).
+ * Renderer-agnostic — consumers read `currentFrame` and apply it however
+ * they like (e.g. `applyHighlight(snippet.graph, frame.highlight, ops)`
+ * for state-graph highlight, plus app-specific tape rendering).
+ */
+export type SnippetPlayer = {
+  /** The frame at the current index. Live getter — re-reads on every access. */
+  readonly currentFrame: Frame;
+  /** Current frame index (0 = initial state, `snippet.frames.length - 1` = final). */
+  readonly frameIndex: number;
+  /** True when `frameIndex === snippet.frames.length - 1`. */
+  readonly done: boolean;
+  /**
+   * Advance one frame. Returns `true` if advanced, `false` if already at the
+   * last frame (no-op in that case).
+   */
+  forward(): boolean;
+  /**
+   * Retreat one frame. Returns `true` if retreated, `false` if already at
+   * the first frame (no-op in that case).
+   */
+  back(): boolean;
+  /** Jump to frame 0. */
+  reset(): void;
+  /**
+   * Jump to a specific frame index. Throws `RangeError` if out of bounds.
+   */
+  goTo(frameIndex: number): void;
+};
+
+/**
+ * Create a fresh `SnippetPlayer` positioned at frame 0.
+ *
+ * Throws if the snippet has no frames. Each `createSnippetPlayer` call
+ * yields an independent player — the same `Snippet` can drive any number
+ * of concurrent players (frame storage is shared and read-only).
+ */
+export function createSnippetPlayer(snippet: Snippet): SnippetPlayer {
+  if (snippet.frames.length === 0) {
+    throw new Error('createSnippetPlayer: snippet has no frames');
+  }
+  const lastIndex = snippet.frames.length - 1;
+  let idx = 0;
+  return {
+    get currentFrame() { return snippet.frames[idx]; },
+    get frameIndex() { return idx; },
+    get done() { return idx === lastIndex; },
+    forward() {
+      if (idx >= lastIndex) return false;
+      idx += 1;
+      return true;
+    },
+    back() {
+      if (idx <= 0) return false;
+      idx -= 1;
+      return true;
+    },
+    reset() { idx = 0; },
+    goTo(target: number) {
+      if (!Number.isInteger(target) || target < 0 || target > lastIndex) {
+        throw new RangeError(
+          `createSnippetPlayer.goTo: frame index ${target} out of bounds [0, ${lastIndex}]`,
+        );
+      }
+      idx = target;
+    },
+  };
+}

From c75d9f46da26241d9b6506d9e5c7d102dbb2c8bc Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 22:39:55 +0300
Subject: [PATCH 108/118] =?UTF-8?q?refactor(visuals):=20SnippetPlayer=20as?=
 =?UTF-8?q?=20a=20class=20=E2=80=94=20mirrors=20DebugSession=20shape?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DebugSession is the engine's interactive-playback class; SnippetPlayer is
the analogous driver for prerecorded runs. The codebase convention is
stateful drivers are classes (State, TapeBlock, TuringMachine, CallFrame,
PostMachine, DebugSession), pure transforms are functions. Use 'new
SnippetPlayer(snippet)' instead of a factory.
---
 packages/visuals/CHANGELOG.md              |   2 +-
 packages/visuals/README.md                 |   8 +-
 packages/visuals/src/index.ts              |   2 +-
 packages/visuals/src/snippetPlayer.spec.ts |  26 ++---
 packages/visuals/src/snippetPlayer.ts      | 107 +++++++++++----------
 5 files changed, 77 insertions(+), 68 deletions(-)

diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index b6e4b59..01541dd 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -8,7 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
-- **`createSnippetPlayer(snippet): SnippetPlayer`** — pure-state playback driver for a `Snippet`. Exposes `currentFrame` / `frameIndex` / `done` getters plus `forward()` / `back()` / `reset()` / `goTo(idx)`. Stateless w.r.t. wall-clock — consumers wire their own ticking (`setInterval`, `requestAnimationFrame`, `IntersectionObserver`); renderer-agnostic — consumers read `currentFrame` and apply it however they like (typically `applyHighlight(snippet.graph, frame.highlight, ops)` for the state graph plus app-specific tape rendering). Each call yields an independent player — the same `Snippet` can drive any number of concurrent players (frame storage is shared and read-only). `forward()` / `back()` return a `boolean` (true if moved, false at end/start — no-op in that case); `goTo(idx)` throws `RangeError` on out-of-bounds.
+- **`SnippetPlayer`** — pure-state playback driver for a `Snippet`. `new SnippetPlayer(snippet)` returns an instance exposing `currentFrame` / `frameIndex` / `done` getters plus `forward()` / `back()` / `reset()` / `goTo(idx)`. Mirrors the engine's `DebugSession` shape (a stateful playback driver for live runs); this is the analogous driver for prerecorded runs. Stateless w.r.t. wall-clock — consumers wire their own ticking (`setInterval`, `requestAnimationFrame`, `IntersectionObserver`); renderer-agnostic — consumers read `currentFrame` and apply it however they like (typically `applyHighlight(snippet.graph, frame.highlight, ops)` for the state graph plus app-specific tape rendering). Two players over the same `Snippet` are independent (frame storage is shared and read-only). `forward()` / `back()` return a `boolean` (true if moved, false at end/start — no-op in that case); `goTo(idx)` throws `RangeError` on out-of-bounds.
 
 ### Compatibility
 
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index b02e981..ab5fe3f 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -104,7 +104,7 @@ formatStep(machineState): string    // alpha.6 MachineState-based formatter; kep
 recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }): Snippet
 
 // Playback
-createSnippetPlayer(snippet): SnippetPlayer
+new SnippetPlayer(snippet)
 ```
 
 The 16-rule contract `applyHighlight` satisfies is documented at [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md).
@@ -245,11 +245,11 @@ const snippet = recordSnippet({
 
 ```ts
 import {
-  applyHighlight, createSnippetPlayer, indexGraph,
+  applyHighlight, SnippetPlayer, indexGraph,
   type HighlightOps, type Snippet,
 } from '@turing-machine-js/visuals';
 
-const player = createSnippetPlayer(snippet);
+const player = new SnippetPlayer(snippet);
 const indexes = indexGraph(snippet.graph);
 let prev: Parameters<typeof applyHighlight>[3] = null;
 
@@ -274,7 +274,7 @@ nextBtn.onclick = () => { if (player.forward()) render(ops, renderTape); };
 replayBtn.onclick = () => { player.reset();     render(ops, renderTape); };
 ```
 
-`createSnippetPlayer` is pure state — no timers, no events. Consumers wire `setInterval` / `requestAnimationFrame` / `IntersectionObserver` and call `forward()` / `back()` / `goTo(idx)`. Two players over the same `Snippet` are independent (frame storage is shared and read-only).
+`SnippetPlayer` is pure state — no timers, no events. Consumers wire `setInterval` / `requestAnimationFrame` / `IntersectionObserver` and call `forward()` / `back()` / `goTo(idx)`. Two players over the same `Snippet` are independent (frame storage is shared and read-only). Mirrors the engine's `DebugSession` shape — stateful playback driver for live runs vs prerecorded runs.
 
 ## Versioning
 
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 29682b0..ceb0d29 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -18,4 +18,4 @@ export {
   type StepTokens,
 } from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';
-export { createSnippetPlayer, type SnippetPlayer } from './snippetPlayer';
+export { SnippetPlayer } from './snippetPlayer';
diff --git a/packages/visuals/src/snippetPlayer.spec.ts b/packages/visuals/src/snippetPlayer.spec.ts
index 4804ed2..78a8ad3 100644
--- a/packages/visuals/src/snippetPlayer.spec.ts
+++ b/packages/visuals/src/snippetPlayer.spec.ts
@@ -10,7 +10,7 @@ import {
   movements,
 } from '@turing-machine-js/machine';
 import { recordSnippet } from './recordSnippet';
-import { createSnippetPlayer } from './snippetPlayer';
+import { SnippetPlayer } from './snippetPlayer';
 import type { Snippet } from './types';
 
 function buildTwoAMachine() {
@@ -34,21 +34,21 @@ function buildSnippet(): Snippet {
   return recordSnippet({ machine, initialState, graph, alphabets });
 }
 
-describe('createSnippetPlayer', () => {
+describe('SnippetPlayer', () => {
   it('throws if the snippet has no frames', () => {
     const empty: Snippet = { version: 1, graph: {} as never, alphabets: [], frames: [] };
-    expect(() => createSnippetPlayer(empty)).toThrow(/no frames/);
+    expect(() => new SnippetPlayer(empty)).toThrow(/no frames/);
   });
 
   it('starts at frame 0', () => {
-    const p = createSnippetPlayer(buildSnippet());
+    const p = new SnippetPlayer(buildSnippet());
     expect(p.frameIndex).toBe(0);
     expect(p.currentFrame.step).toBe(0);
   });
 
   it('done is true only at the last frame', () => {
     const snippet = buildSnippet();
-    const p = createSnippetPlayer(snippet);
+    const p = new SnippetPlayer(snippet);
     expect(p.done).toBe(false);
     while (p.forward()) { /* advance */ }
     expect(p.frameIndex).toBe(snippet.frames.length - 1);
@@ -57,7 +57,7 @@ describe('createSnippetPlayer', () => {
 
   it('forward advances and returns true; returns false at end', () => {
     const snippet = buildSnippet();
-    const p = createSnippetPlayer(snippet);
+    const p = new SnippetPlayer(snippet);
     for (let i = 1; i < snippet.frames.length; i += 1) {
       expect(p.forward()).toBe(true);
       expect(p.frameIndex).toBe(i);
@@ -68,7 +68,7 @@ describe('createSnippetPlayer', () => {
 
   it('back retreats and returns true; returns false at start', () => {
     const snippet = buildSnippet();
-    const p = createSnippetPlayer(snippet);
+    const p = new SnippetPlayer(snippet);
     p.goTo(snippet.frames.length - 1);
     for (let i = snippet.frames.length - 2; i >= 0; i -= 1) {
       expect(p.back()).toBe(true);
@@ -79,7 +79,7 @@ describe('createSnippetPlayer', () => {
   });
 
   it('reset returns to frame 0', () => {
-    const p = createSnippetPlayer(buildSnippet());
+    const p = new SnippetPlayer(buildSnippet());
     p.forward();
     p.forward();
     p.reset();
@@ -89,7 +89,7 @@ describe('createSnippetPlayer', () => {
 
   it('goTo jumps to a specific frame', () => {
     const snippet = buildSnippet();
-    const p = createSnippetPlayer(snippet);
+    const p = new SnippetPlayer(snippet);
     p.goTo(snippet.frames.length - 1);
     expect(p.frameIndex).toBe(snippet.frames.length - 1);
     expect(p.currentFrame).toBe(snippet.frames[snippet.frames.length - 1]);
@@ -99,7 +99,7 @@ describe('createSnippetPlayer', () => {
 
   it('goTo throws RangeError on out-of-bounds index', () => {
     const snippet = buildSnippet();
-    const p = createSnippetPlayer(snippet);
+    const p = new SnippetPlayer(snippet);
     expect(() => p.goTo(-1)).toThrow(RangeError);
     expect(() => p.goTo(snippet.frames.length)).toThrow(RangeError);
     expect(() => p.goTo(1.5)).toThrow(RangeError);
@@ -107,7 +107,7 @@ describe('createSnippetPlayer', () => {
 
   it('currentFrame is a live getter — reflects index changes', () => {
     const snippet = buildSnippet();
-    const p = createSnippetPlayer(snippet);
+    const p = new SnippetPlayer(snippet);
     const first = p.currentFrame;
     p.forward();
     const second = p.currentFrame;
@@ -117,8 +117,8 @@ describe('createSnippetPlayer', () => {
 
   it('two players over the same snippet are independent', () => {
     const snippet = buildSnippet();
-    const a = createSnippetPlayer(snippet);
-    const b = createSnippetPlayer(snippet);
+    const a = new SnippetPlayer(snippet);
+    const b = new SnippetPlayer(snippet);
     a.forward();
     a.forward();
     expect(a.frameIndex).toBe(2);
diff --git a/packages/visuals/src/snippetPlayer.ts b/packages/visuals/src/snippetPlayer.ts
index 602540e..0175197 100644
--- a/packages/visuals/src/snippetPlayer.ts
+++ b/packages/visuals/src/snippetPlayer.ts
@@ -3,73 +3,82 @@ import type { Frame, Snippet } from './types';
 /**
  * Pure-state playback driver for a `Snippet` produced by `recordSnippet`.
  *
- * Holds the current frame index and exposes forward / back / reset / goTo.
- * Stateless w.r.t. wall-clock — consumers wire their own ticking
+ * Holds the current frame index and exposes `forward` / `back` / `reset` /
+ * `goTo`. Stateless w.r.t. wall-clock — consumers wire their own ticking
  * (`setInterval`, `requestAnimationFrame`, `IntersectionObserver`, etc.).
  * Renderer-agnostic — consumers read `currentFrame` and apply it however
  * they like (e.g. `applyHighlight(snippet.graph, frame.highlight, ops)`
  * for state-graph highlight, plus app-specific tape rendering).
+ *
+ * Two players over the same `Snippet` are independent — frame storage is
+ * shared and read-only.
+ *
+ * Mirrors the engine's `DebugSession` shape (a stateful playback driver
+ * for live runs); this is the analogous driver for prerecorded runs.
  */
-export type SnippetPlayer = {
+export class SnippetPlayer {
+  readonly #snippet: Snippet;
+  readonly #lastIndex: number;
+  #index = 0;
+
+  constructor(snippet: Snippet) {
+    if (snippet.frames.length === 0) {
+      throw new Error('SnippetPlayer: snippet has no frames');
+    }
+    this.#snippet = snippet;
+    this.#lastIndex = snippet.frames.length - 1;
+  }
+
   /** The frame at the current index. Live getter — re-reads on every access. */
-  readonly currentFrame: Frame;
+  get currentFrame(): Frame {
+    return this.#snippet.frames[this.#index];
+  }
+
   /** Current frame index (0 = initial state, `snippet.frames.length - 1` = final). */
-  readonly frameIndex: number;
+  get frameIndex(): number {
+    return this.#index;
+  }
+
   /** True when `frameIndex === snippet.frames.length - 1`. */
-  readonly done: boolean;
+  get done(): boolean {
+    return this.#index === this.#lastIndex;
+  }
+
   /**
    * Advance one frame. Returns `true` if advanced, `false` if already at the
    * last frame (no-op in that case).
    */
-  forward(): boolean;
+  forward(): boolean {
+    if (this.#index >= this.#lastIndex) return false;
+    this.#index += 1;
+    return true;
+  }
+
   /**
    * Retreat one frame. Returns `true` if retreated, `false` if already at
    * the first frame (no-op in that case).
    */
-  back(): boolean;
+  back(): boolean {
+    if (this.#index <= 0) return false;
+    this.#index -= 1;
+    return true;
+  }
+
   /** Jump to frame 0. */
-  reset(): void;
+  reset(): void {
+    this.#index = 0;
+  }
+
   /**
-   * Jump to a specific frame index. Throws `RangeError` if out of bounds.
+   * Jump to a specific frame index. Throws `RangeError` if out of bounds
+   * (negative, beyond the last frame, or not an integer).
    */
-  goTo(frameIndex: number): void;
-};
-
-/**
- * Create a fresh `SnippetPlayer` positioned at frame 0.
- *
- * Throws if the snippet has no frames. Each `createSnippetPlayer` call
- * yields an independent player — the same `Snippet` can drive any number
- * of concurrent players (frame storage is shared and read-only).
- */
-export function createSnippetPlayer(snippet: Snippet): SnippetPlayer {
-  if (snippet.frames.length === 0) {
-    throw new Error('createSnippetPlayer: snippet has no frames');
+  goTo(frameIndex: number): void {
+    if (!Number.isInteger(frameIndex) || frameIndex < 0 || frameIndex > this.#lastIndex) {
+      throw new RangeError(
+        `SnippetPlayer.goTo: frame index ${frameIndex} out of bounds [0, ${this.#lastIndex}]`,
+      );
+    }
+    this.#index = frameIndex;
   }
-  const lastIndex = snippet.frames.length - 1;
-  let idx = 0;
-  return {
-    get currentFrame() { return snippet.frames[idx]; },
-    get frameIndex() { return idx; },
-    get done() { return idx === lastIndex; },
-    forward() {
-      if (idx >= lastIndex) return false;
-      idx += 1;
-      return true;
-    },
-    back() {
-      if (idx <= 0) return false;
-      idx -= 1;
-      return true;
-    },
-    reset() { idx = 0; },
-    goTo(target: number) {
-      if (!Number.isInteger(target) || target < 0 || target > lastIndex) {
-        throw new RangeError(
-          `createSnippetPlayer.goTo: frame index ${target} out of bounds [0, ${lastIndex}]`,
-        );
-      }
-      idx = target;
-    },
-  };
 }

From 65bda6f99d65dbd62a0b7f0ca4f5a12054a07a26 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 22:43:31 +0300
Subject: [PATCH 109/118] =?UTF-8?q?feat(visuals):=20tapeViewport=20?=
 =?UTF-8?q?=E2=80=94=20fixed-width=20centered=20window=20over=20a=20TapeSn?=
 =?UTF-8?q?apshot?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Equivalent of the engine's Tape.viewport getter, but for wire-data
TapeSnapshot. Pads with the caller-supplied blank symbol so the result
always has exactly width entries. Frame stays lossless data; the helper
windows on demand so consumers can pick their viewport width per render
context.
---
 packages/visuals/CHANGELOG.md             |  2 +
 packages/visuals/README.md                |  1 +
 packages/visuals/src/index.ts             |  1 +
 packages/visuals/src/tapeViewport.spec.ts | 68 +++++++++++++++++++++++
 packages/visuals/src/tapeViewport.ts      | 42 ++++++++++++++
 5 files changed, 114 insertions(+)
 create mode 100644 packages/visuals/src/tapeViewport.spec.ts
 create mode 100644 packages/visuals/src/tapeViewport.ts

diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index 01541dd..a263f90 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
+- **`tapeViewport(snapshot, width, blank): { cells, headIndex }`** — fixed-width window of tape cells centered on the head. The engine's `Tape` class exposes a `viewport` getter for the live tape; this is the equivalent for `TapeSnapshot` (the wire-data shape carried in `Frame.tape`). Cells outside the snapshot's `symbols` array are padded with `blank`, so the result always has exactly `width` entries. `headIndex` is deterministic at `Math.floor(width / 2)` and is exposed for caller convenience (and to leave room for future non-centered policies without a signature break). Throws `RangeError` on non-positive or non-integer width.
+
 - **`SnippetPlayer`** — pure-state playback driver for a `Snippet`. `new SnippetPlayer(snippet)` returns an instance exposing `currentFrame` / `frameIndex` / `done` getters plus `forward()` / `back()` / `reset()` / `goTo(idx)`. Mirrors the engine's `DebugSession` shape (a stateful playback driver for live runs); this is the analogous driver for prerecorded runs. Stateless w.r.t. wall-clock — consumers wire their own ticking (`setInterval`, `requestAnimationFrame`, `IntersectionObserver`); renderer-agnostic — consumers read `currentFrame` and apply it however they like (typically `applyHighlight(snippet.graph, frame.highlight, ops)` for the state graph plus app-specific tape rendering). Two players over the same `Snippet` are independent (frame storage is shared and read-only). `forward()` / `back()` return a `boolean` (true if moved, false at end/start — no-op in that case); `goTo(idx)` throws `RangeError` on out-of-bounds.
 
 ### Compatibility
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index ab5fe3f..cd2eae9 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -105,6 +105,7 @@ recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log?
 
 // Playback
 new SnippetPlayer(snippet)
+tapeViewport(snapshot, width, blank): { cells, headIndex }
 ```
 
 The 16-rule contract `applyHighlight` satisfies is documented at [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md).
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index ceb0d29..0d6ad5d 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -19,3 +19,4 @@ export {
 } from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';
 export { SnippetPlayer } from './snippetPlayer';
+export { tapeViewport } from './tapeViewport';
diff --git a/packages/visuals/src/tapeViewport.spec.ts b/packages/visuals/src/tapeViewport.spec.ts
new file mode 100644
index 0000000..2c0b2b0
--- /dev/null
+++ b/packages/visuals/src/tapeViewport.spec.ts
@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { tapeViewport } from './tapeViewport';
+
+const BLANK = ' ';
+
+describe('tapeViewport', () => {
+  it('returns full tape centered when width === symbols length and head is centered', () => {
+    const r = tapeViewport({ symbols: ['a', 'b', 'c', 'd', 'e'], position: 2 }, 5, BLANK);
+    expect(r.cells).toEqual(['a', 'b', 'c', 'd', 'e']);
+    expect(r.headIndex).toBe(2);
+  });
+
+  it('pads with blank on the left when head is near the left edge', () => {
+    const r = tapeViewport({ symbols: ['a', 'b', 'c'], position: 0 }, 5, BLANK);
+    expect(r.cells).toEqual([' ', ' ', 'a', 'b', 'c']);
+    expect(r.headIndex).toBe(2);
+    expect(r.cells[r.headIndex]).toBe('a');
+  });
+
+  it('pads with blank on the right when head is near the right edge', () => {
+    const r = tapeViewport({ symbols: ['a', 'b', 'c'], position: 2 }, 5, BLANK);
+    expect(r.cells).toEqual(['a', 'b', 'c', ' ', ' ']);
+    expect(r.headIndex).toBe(2);
+    expect(r.cells[r.headIndex]).toBe('c');
+  });
+
+  it('pads with blank on both sides when tape is shorter than the window', () => {
+    const r = tapeViewport({ symbols: ['x'], position: 0 }, 5, BLANK);
+    expect(r.cells).toEqual([' ', ' ', 'x', ' ', ' ']);
+    expect(r.headIndex).toBe(2);
+  });
+
+  it('returns all blanks when the head is far past the tape end', () => {
+    const r = tapeViewport({ symbols: ['a'], position: 100 }, 5, BLANK);
+    expect(r.cells).toEqual([' ', ' ', ' ', ' ', ' ']);
+    expect(r.headIndex).toBe(2);
+  });
+
+  it('uses the provided blank symbol (not space)', () => {
+    const r = tapeViewport({ symbols: ['x'], position: 0 }, 5, '␣');
+    expect(r.cells).toEqual(['␣', '␣', 'x', '␣', '␣']);
+  });
+
+  it('handles width === 1 (head-only window)', () => {
+    const r = tapeViewport({ symbols: ['a', 'b', 'c'], position: 1 }, 1, BLANK);
+    expect(r.cells).toEqual(['b']);
+    expect(r.headIndex).toBe(0);
+  });
+
+  it('handles even width with head at floor(width / 2)', () => {
+    const r = tapeViewport({ symbols: ['a', 'b', 'c', 'd'], position: 1 }, 4, BLANK);
+    expect(r.cells).toEqual([' ', 'a', 'b', 'c']);
+    expect(r.headIndex).toBe(2);
+    expect(r.cells[r.headIndex]).toBe('b');
+  });
+
+  it('throws RangeError on non-positive width', () => {
+    const snap = { symbols: ['a'], position: 0 };
+    expect(() => tapeViewport(snap, 0, BLANK)).toThrow(RangeError);
+    expect(() => tapeViewport(snap, -1, BLANK)).toThrow(RangeError);
+  });
+
+  it('throws RangeError on non-integer width', () => {
+    const snap = { symbols: ['a'], position: 0 };
+    expect(() => tapeViewport(snap, 1.5, BLANK)).toThrow(RangeError);
+    expect(() => tapeViewport(snap, NaN, BLANK)).toThrow(RangeError);
+  });
+});
diff --git a/packages/visuals/src/tapeViewport.ts b/packages/visuals/src/tapeViewport.ts
new file mode 100644
index 0000000..7a0fdab
--- /dev/null
+++ b/packages/visuals/src/tapeViewport.ts
@@ -0,0 +1,42 @@
+import type { TapeSnapshot } from './types';
+
+/**
+ * Compute a fixed-width window of tape cells centered on the head.
+ *
+ * The engine's `Tape` class exposes a `viewport` getter that does this for
+ * the live tape; `tapeViewport` is the equivalent for the wire-data
+ * `TapeSnapshot` carried in `Frame.tape`. Cells outside the snapshot's
+ * `symbols` array are padded with `blank`, so the result always has
+ * exactly `width` entries.
+ *
+ * The returned `headIndex` is the head's index within `cells` —
+ * deterministic at `Math.floor(width / 2)`, but exposed for callers that
+ * want to avoid recomputing it (and to leave room for future non-centered
+ * policies without a signature break).
+ *
+ * Pass the tape's blank symbol from `Snippet.alphabets[i]` (by convention
+ * the first entry per tape in the visuals/engine pipeline — verify against
+ * how the snippet was recorded).
+ */
+export function tapeViewport(
+  snapshot: TapeSnapshot,
+  width: number,
+  blank: string,
+): { cells: string[]; headIndex: number } {
+  if (!Number.isInteger(width) || width <= 0) {
+    throw new RangeError(
+      `tapeViewport: width must be a positive integer (got ${width})`,
+    );
+  }
+  const half = Math.floor(width / 2);
+  const startTapeIdx = snapshot.position - half;
+  const cells: string[] = new Array(width);
+  for (let i = 0; i < width; i += 1) {
+    const tapeIdx = startTapeIdx + i;
+    cells[i] =
+      tapeIdx >= 0 && tapeIdx < snapshot.symbols.length
+        ? snapshot.symbols[tapeIdx]
+        : blank;
+  }
+  return { cells, headIndex: half };
+}

From 7122bc8cc14ebf23e7a350cbfbe0f16a82868eab Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 22:51:12 +0300
Subject: [PATCH 110/118] =?UTF-8?q?docs(visuals):=20fix=20snippet-playback?=
 =?UTF-8?q?=20example=20=E2=80=94=20declare=20ops=20/=20renderTape=20/=20b?=
 =?UTF-8?q?uttons=20explicitly?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previous example had render(ops, renderTape) magically receiving args that
were never defined in the example scope. Replaced with applyFrame() that
closes over explicit declare-typed stubs for ops, renderTape, and the
illustrative buttons — caller sites become render-free.
---
 packages/visuals/README.md | 32 ++++++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 8 deletions(-)

diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index cd2eae9..a56ace8 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -246,17 +246,33 @@ const snippet = recordSnippet({
 
 ```ts
 import {
-  applyHighlight, SnippetPlayer, indexGraph,
-  type HighlightOps, type Snippet,
+  applyHighlight, indexGraph, SnippetPlayer,
+  type Frame, type HighlightOps,
 } from '@turing-machine-js/visuals';
 
+// Build a HighlightOps over your SVG / renderer — see the
+// "Example: applying highlight in a DOM renderer" above for the
+// concrete `domOps(svgRoot)` factory.
+declare const ops: HighlightOps;
+
+// Render a frame's tape state into your UI — app-specific (Svelte,
+// React, vanilla, ANSI, …). For a fixed-width centered window padded
+// with the alphabet's blank, see `tapeViewport(snap, width, blank)` below.
+declare function renderTape(tape: Frame['tape']): void;
+
+// Buttons your UI exposes — strictly illustrative.
+declare const prevBtn: HTMLButtonElement;
+declare const nextBtn: HTMLButtonElement;
+declare const replayBtn: HTMLButtonElement;
+
 const player = new SnippetPlayer(snippet);
 const indexes = indexGraph(snippet.graph);
 let prev: Parameters<typeof applyHighlight>[3] = null;
 
-function render(ops: HighlightOps, renderTape: (snap: Snippet['frames'][0]['tape']) => void) {
+function applyFrame(): void {
   const frame = player.currentFrame;
-  // (consumer wipes previous highlight classes from the DOM before calling)
+  // (consumer is responsible for wiping previous highlight classes from
+  // the DOM before each applyHighlight call — see the highlight example above.)
   if (frame.highlight) {
     prev = applyHighlight(frame.highlight, snippet.graph, indexes, prev, ops).nextPrev;
   }
@@ -266,13 +282,13 @@ function render(ops: HighlightOps, renderTape: (snap: Snippet['frames'][0]['tape
 // Auto-play forward at a fixed cadence:
 const id = setInterval(() => {
   if (!player.forward()) { clearInterval(id); return; }
-  render(ops, renderTape);
+  applyFrame();
 }, 800);
 
 // Bi-directional scrub:
-prevBtn.onclick = () => { if (player.back())    render(ops, renderTape); };
-nextBtn.onclick = () => { if (player.forward()) render(ops, renderTape); };
-replayBtn.onclick = () => { player.reset();     render(ops, renderTape); };
+prevBtn.onclick = () => { if (player.back())    applyFrame(); };
+nextBtn.onclick = () => { if (player.forward()) applyFrame(); };
+replayBtn.onclick = () => { player.reset();     applyFrame(); };
 ```
 
 `SnippetPlayer` is pure state — no timers, no events. Consumers wire `setInterval` / `requestAnimationFrame` / `IntersectionObserver` and call `forward()` / `back()` / `goTo(idx)`. Two players over the same `Snippet` are independent (frame storage is shared and read-only). Mirrors the engine's `DebugSession` shape — stateful playback driver for live runs vs prerecorded runs.

From 9e12dd94851d8581552c8db555e144a17fd24da9 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Sat, 30 May 2026 22:52:31 +0300
Subject: [PATCH 111/118] docs(visuals): snippet playback example uses
 AbortController for teardown

Replace .onclick assignments with addEventListener({signal}); scope the
setInterval cleanup through the same signal. One controller.abort() in
the component's teardown tears down both the auto-play timer and the
click listeners.
---
 packages/visuals/README.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index a56ace8..147c502 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -279,16 +279,23 @@ function applyFrame(): void {
   renderTape(frame.tape);
 }
 
+// One AbortController scopes both the auto-play timer and the click
+// listeners — call controller.abort() in your component teardown
+// (Svelte onDestroy / React useEffect cleanup / etc.).
+const controller = new AbortController();
+const { signal } = controller;
+
 // Auto-play forward at a fixed cadence:
 const id = setInterval(() => {
   if (!player.forward()) { clearInterval(id); return; }
   applyFrame();
 }, 800);
+signal.addEventListener('abort', () => clearInterval(id), { once: true });
 
 // Bi-directional scrub:
-prevBtn.onclick = () => { if (player.back())    applyFrame(); };
-nextBtn.onclick = () => { if (player.forward()) applyFrame(); };
-replayBtn.onclick = () => { player.reset();     applyFrame(); };
+prevBtn.addEventListener('click', () => { if (player.back())    applyFrame(); }, { signal });
+nextBtn.addEventListener('click', () => { if (player.forward()) applyFrame(); }, { signal });
+replayBtn.addEventListener('click', () => { player.reset();     applyFrame(); }, { signal });
 ```
 
 `SnippetPlayer` is pure state — no timers, no events. Consumers wire `setInterval` / `requestAnimationFrame` / `IntersectionObserver` and call `forward()` / `back()` / `goTo(idx)`. Two players over the same `Snippet` are independent (frame storage is shared and read-only). Mirrors the engine's `DebugSession` shape — stateful playback driver for live runs vs prerecorded runs.

From 0478f69b08f299c5c02ee87009a807866927fd4a Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Tue, 2 Jun 2026 09:55:12 +0300
Subject: [PATCH 112/118] feat(machine): lift TapeSnapshot + tapeViewport from
 visuals to engine (7.0.0-alpha.8, #227)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TapeSnapshot is a wire-data shape derived from Tape — its logical home is
next to the live Tape class in the engine package. Visuals re-exports
both type and helper, so consumers importing from
@turing-machine-js/visuals are unaffected.

Engine's Tape.viewport getter is unchanged — it operates on the live
int-encoded tape via Alphabet.get (different data shape from the
wire-data TapeSnapshot). The two surfaces are not direct duplicates;
the move is about locality, not internal dedup.

Closes #227.
---
 lerna.json                                    |  2 +-
 package-lock.json                             | 18 ++++++-------
 packages/builder/CHANGELOG.md                 |  4 +++
 packages/builder/package.json                 |  4 +--
 .../library-binary-numbers-bare/CHANGELOG.md  |  4 +++
 .../library-binary-numbers-bare/package.json  |  4 +--
 packages/library-binary-numbers/CHANGELOG.md  |  4 +++
 packages/library-binary-numbers/package.json  |  4 +--
 packages/machine/CHANGELOG.md                 | 16 ++++++++++++
 packages/machine/package.json                 |  2 +-
 packages/machine/src/index.ts                 |  1 +
 .../src/utilities}/tapeViewport.spec.ts       |  0
 .../src/utilities}/tapeViewport.ts            | 25 +++++++++++++------
 packages/visuals/CHANGELOG.md                 | 14 +++++++++++
 packages/visuals/README.md                    |  2 +-
 packages/visuals/package.json                 |  4 +--
 packages/visuals/src/format.ts                |  3 +--
 packages/visuals/src/index.ts                 |  9 +++++--
 packages/visuals/src/recordSnippet.ts         |  3 ++-
 packages/visuals/src/types.ts                 | 11 +-------
 20 files changed, 92 insertions(+), 42 deletions(-)
 rename packages/{visuals/src => machine/src/utilities}/tapeViewport.spec.ts (100%)
 rename packages/{visuals/src => machine/src/utilities}/tapeViewport.ts (58%)

diff --git a/lerna.json b/lerna.json
index b8cecac..a123db3 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.7",
+  "version": "7.0.0-alpha.8",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index dc88f2f..d709e9a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10660,40 +10660,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.7",
+      "version": "7.0.0-alpha.8",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.7"
+        "@turing-machine-js/machine": "^7.0.0-alpha.8"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.7",
+      "version": "7.0.0-alpha.8",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.7"
+        "@turing-machine-js/machine": "^7.0.0-alpha.8"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.7",
+      "version": "7.0.0-alpha.8",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.7"
+        "@turing-machine-js/machine": "^7.0.0-alpha.8"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.7",
+      "version": "7.0.0-alpha.8",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
@@ -10701,13 +10701,13 @@
     },
     "packages/visuals": {
       "name": "@turing-machine-js/visuals",
-      "version": "7.0.0-alpha.7.1",
+      "version": "7.0.0-alpha.8",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.7"
+        "@turing-machine-js/machine": "^7.0.0-alpha.8"
       }
     }
   }
diff --git a/packages/builder/CHANGELOG.md b/packages/builder/CHANGELOG.md
index a94ae43..5cd086a 100644
--- a/packages/builder/CHANGELOG.md
+++ b/packages/builder/CHANGELOG.md
@@ -4,6 +4,10 @@ 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.8] - 2026-06-02
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.8 — lifts `TapeSnapshot` + `tapeViewport` from `@turing-machine-js/visuals` into the engine ([#227](https://github.com/mellonis/turing-machine-js/issues/227)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.7` → `^7.0.0-alpha.8`.
+
 ## [7.0.0-alpha.7] - 2026-05-30
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.7 — adds `CallFrame` as a first-class `State` subclass ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) and fixes a `toMermaid` framed-wrapper emit asymmetry ([#223](https://github.com/mellonis/turing-machine-js/issues/223)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
diff --git a/packages/builder/package.json b/packages/builder/package.json
index d50feed..1a8bd77 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.7",
+  "version": "7.0.0-alpha.8",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.7"
+    "@turing-machine-js/machine": "^7.0.0-alpha.8"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/CHANGELOG.md b/packages/library-binary-numbers-bare/CHANGELOG.md
index ff0690f..9daa243 100644
--- a/packages/library-binary-numbers-bare/CHANGELOG.md
+++ b/packages/library-binary-numbers-bare/CHANGELOG.md
@@ -4,6 +4,10 @@ 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.8] - 2026-06-02
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.8 — lifts `TapeSnapshot` + `tapeViewport` from `@turing-machine-js/visuals` into the engine ([#227](https://github.com/mellonis/turing-machine-js/issues/227)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.7` → `^7.0.0-alpha.8`.
+
 ## [7.0.0-alpha.7] - 2026-05-30
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.7 — adds `CallFrame` as a first-class `State` subclass ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) and fixes a `toMermaid` framed-wrapper emit asymmetry ([#223](https://github.com/mellonis/turing-machine-js/issues/223)). No source or behavior changes in this package — `states.md` is unaffected (no diagram here uses an inner-wrapper-call pattern). Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index b4a59d5..f579b9c 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.7",
+  "version": "7.0.0-alpha.8",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.7"
+    "@turing-machine-js/machine": "^7.0.0-alpha.8"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/CHANGELOG.md b/packages/library-binary-numbers/CHANGELOG.md
index 6424503..926499d 100644
--- a/packages/library-binary-numbers/CHANGELOG.md
+++ b/packages/library-binary-numbers/CHANGELOG.md
@@ -4,6 +4,10 @@ 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.8] - 2026-06-02
+
+Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.8 — lifts `TapeSnapshot` + `tapeViewport` from `@turing-machine-js/visuals` into the engine ([#227](https://github.com/mellonis/turing-machine-js/issues/227)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.7` → `^7.0.0-alpha.8`.
+
 ## [7.0.0-alpha.7] - 2026-05-30
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.7 — adds `CallFrame` as a first-class `State` subclass ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) and fixes a `toMermaid` framed-wrapper emit asymmetry ([#223](https://github.com/mellonis/turing-machine-js/issues/223)). The `states.md` file is regenerated under the new emit: the `minusOne` diagram's `goToNumberStart(invertNumberGoToNumberWithInversion)` wrapper now renders INSIDE `invertNumber`'s callable subtree (was outside, visually disconnected from its owner frame). No source or behavior changes. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index 8cdfece..a3960c3 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.7",
+  "version": "7.0.0-alpha.8",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.7"
+    "@turing-machine-js/machine": "^7.0.0-alpha.8"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index 86a46fb..75b3c48 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,22 @@ 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.8] - 2026-06-02
+
+Eighth v7 pre-release. Lifts `TapeSnapshot` (the per-tape wire-data shape `{symbols, position}`) and `tapeViewport` (fixed-width centered window over a `TapeSnapshot`) from `@turing-machine-js/visuals` into the engine, next to the `Tape` class. Resolves [#227](https://github.com/mellonis/turing-machine-js/issues/227). 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.8`.
+
+### Added
+
+- **`TapeSnapshot` type** ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) — `{ symbols: string[]; position: number }`. The per-tape wire-data shape — what callers serialize a live `Tape` into for transmission (worker boundaries, snippet recording, snapshot tests). Previously lived in `@turing-machine-js/visuals`'s `types.ts` and was re-imported by the engine for `Frame.tape`-style fields. Now sits in the engine next to the live `Tape` class; `@turing-machine-js/visuals` re-exports it for consumer-import stability (so `import { TapeSnapshot } from '@turing-machine-js/visuals'` keeps working).
+- **`tapeViewport(snapshot, width, blank): { cells, headIndex }`** ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) — pure helper: fixed-width window over a `TapeSnapshot`, centered on the head, padded with `blank` for out-of-bounds cells. `headIndex` is deterministic at `Math.floor(width / 2)`. Throws `RangeError` on non-positive or non-integer width. Visuals re-exports.
+
+### Compatibility
+
+- **Consumers importing `TapeSnapshot` or `tapeViewport` from `@turing-machine-js/visuals` are unaffected** — visuals re-exports both from the engine.
+- **Engine's `Tape.viewport` getter is unchanged.** It operates on the live, internally-int-encoded tape via `Alphabet.get` — different data shape from the wire-data `TapeSnapshot`. The two surfaces serve different inputs and are not direct duplicates; the move was about locality (`TapeSnapshot` lives next to `Tape`), not internal dedup.
+
 ## [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`.
diff --git a/packages/machine/package.json b/packages/machine/package.json
index 6c97062..d22c306 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.7",
+  "version": "7.0.0-alpha.8",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
diff --git a/packages/machine/src/index.ts b/packages/machine/src/index.ts
index 5a53283..ab270cc 100644
--- a/packages/machine/src/index.ts
+++ b/packages/machine/src/index.ts
@@ -23,3 +23,4 @@ export {
   type EquivalenceResult,
   type EquivalenceReport,
 } from './utilities/equivalence';
+export { tapeViewport, type TapeSnapshot } from './utilities/tapeViewport';
diff --git a/packages/visuals/src/tapeViewport.spec.ts b/packages/machine/src/utilities/tapeViewport.spec.ts
similarity index 100%
rename from packages/visuals/src/tapeViewport.spec.ts
rename to packages/machine/src/utilities/tapeViewport.spec.ts
diff --git a/packages/visuals/src/tapeViewport.ts b/packages/machine/src/utilities/tapeViewport.ts
similarity index 58%
rename from packages/visuals/src/tapeViewport.ts
rename to packages/machine/src/utilities/tapeViewport.ts
index 7a0fdab..e8f3427 100644
--- a/packages/visuals/src/tapeViewport.ts
+++ b/packages/machine/src/utilities/tapeViewport.ts
@@ -1,22 +1,33 @@
-import type { TapeSnapshot } from './types';
+/**
+ * Per-tape wire-data snapshot — the cells visible/usable plus the head's
+ * index into them. Pure data; no library handles.
+ *
+ * Produced by callers serializing a live `Tape` for transmission (worker
+ * boundaries, snippet recording, snapshot tests). The engine's own
+ * `Tape.viewport` getter operates on the live, internally-int-encoded
+ * tape rather than on a `TapeSnapshot` — so it doesn't currently call
+ * `tapeViewport` internally. The two surfaces serve different inputs
+ * (string snapshot vs live int-encoded tape) and are not direct duplicates.
+ */
+export type TapeSnapshot = {
+  symbols: string[];
+  position: number;
+};
 
 /**
  * Compute a fixed-width window of tape cells centered on the head.
  *
  * The engine's `Tape` class exposes a `viewport` getter that does this for
  * the live tape; `tapeViewport` is the equivalent for the wire-data
- * `TapeSnapshot` carried in `Frame.tape`. Cells outside the snapshot's
- * `symbols` array are padded with `blank`, so the result always has
- * exactly `width` entries.
+ * `TapeSnapshot`. Cells outside the snapshot's `symbols` array are padded
+ * with `blank`, so the result always has exactly `width` entries.
  *
  * The returned `headIndex` is the head's index within `cells` —
  * deterministic at `Math.floor(width / 2)`, but exposed for callers that
  * want to avoid recomputing it (and to leave room for future non-centered
  * policies without a signature break).
  *
- * Pass the tape's blank symbol from `Snippet.alphabets[i]` (by convention
- * the first entry per tape in the visuals/engine pipeline — verify against
- * how the snippet was recorded).
+ * Pass the alphabet's blank symbol as `blank`.
  */
 export function tapeViewport(
   snapshot: TapeSnapshot,
diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index a263f90..8eb8fd2 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to this package 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.8] - 2026-06-02
+
+`TapeSnapshot` type and `tapeViewport` helper moved to `@turing-machine-js/machine` ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) — they live next to the live `Tape` class now. **Consumers importing them from `@turing-machine-js/visuals` are unaffected**: visuals re-exports both from the engine, so existing `import { TapeSnapshot, tapeViewport } from '@turing-machine-js/visuals'` continues to work.
+
+### Changed
+
+- `TapeSnapshot` type — local definition removed from `visuals/src/types.ts`; re-exported from `@turing-machine-js/machine` via `visuals/src/index.ts`.
+- `tapeViewport` helper — local implementation removed from `visuals/src/tapeViewport.ts` (file deleted); re-exported from `@turing-machine-js/machine`.
+
+### Compatibility
+
+- Re-aligned to lockstep at `7.0.0-alpha.8` (last visuals-only patch was `7.0.0-alpha.7.1`).
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.7` → `^7.0.0-alpha.8`.
+
 ## [7.0.0-alpha.7.1] - 2026-05-30
 
 ### Added
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index 147c502..286efcc 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -105,7 +105,7 @@ recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log?
 
 // Playback
 new SnippetPlayer(snippet)
-tapeViewport(snapshot, width, blank): { cells, headIndex }
+tapeViewport(snapshot, width, blank): { cells, headIndex }  // re-exported from @turing-machine-js/machine (alpha.8+)
 ```
 
 The 16-rule contract `applyHighlight` satisfies is documented at [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md).
diff --git a/packages/visuals/package.json b/packages/visuals/package.json
index 4777674..728a4c0 100644
--- a/packages/visuals/package.json
+++ b/packages/visuals/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/visuals",
-  "version": "7.0.0-alpha.7.1",
+  "version": "7.0.0-alpha.8",
   "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "visualization"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.7"
+    "@turing-machine-js/machine": "^7.0.0-alpha.8"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/visuals",
diff --git a/packages/visuals/src/format.ts b/packages/visuals/src/format.ts
index 343a7f0..bb41934 100644
--- a/packages/visuals/src/format.ts
+++ b/packages/visuals/src/format.ts
@@ -1,5 +1,4 @@
-import { movements, symbolCommands, type MachineState, type TapeCommand } from '@turing-machine-js/machine';
-import type { TapeSnapshot } from './types';
+import { movements, symbolCommands, type MachineState, type TapeCommand, type TapeSnapshot } from '@turing-machine-js/machine';
 
 /**
  * Plain per-tape command shape consumed by `formatStepNotation`. Distinct
diff --git a/packages/visuals/src/index.ts b/packages/visuals/src/index.ts
index 0d6ad5d..fe7cd4c 100644
--- a/packages/visuals/src/index.ts
+++ b/packages/visuals/src/index.ts
@@ -4,7 +4,10 @@ export { recordingOps } from './highlightOps';
 export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
 export type { GraphIndexes } from './graphIndexes';
 export { indexGraph } from './graphIndexes';
-export type { GraphHighlight, TapeSnapshot, Frame, Snippet } from './types';
+export type { GraphHighlight, Frame, Snippet } from './types';
+// Re-exported from @turing-machine-js/machine for consumer-import stability —
+// the canonical home is the engine package (next to the `Tape` class).
+export type { TapeSnapshot } from '@turing-machine-js/machine';
 export { applyHighlight, applyIndicator } from './applyHighlight';
 export {
   formatCommand,
@@ -19,4 +22,6 @@ export {
 } from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';
 export { SnippetPlayer } from './snippetPlayer';
-export { tapeViewport } from './tapeViewport';
+// Re-exported from @turing-machine-js/machine for consumer-import stability —
+// the canonical home is the engine package (next to the `Tape` class).
+export { tapeViewport } from '@turing-machine-js/machine';
diff --git a/packages/visuals/src/recordSnippet.ts b/packages/visuals/src/recordSnippet.ts
index 4439f13..1c74bf7 100644
--- a/packages/visuals/src/recordSnippet.ts
+++ b/packages/visuals/src/recordSnippet.ts
@@ -3,11 +3,12 @@ import {
   type Graph,
   type MachineState,
   type State,
+  type TapeSnapshot,
   type TuringMachine,
 } from '@turing-machine-js/machine';
 import { MOVEMENT_LETTER } from './format';
 import { bareIdOf } from './graphUtils';
-import type { Frame, GraphHighlight, Snippet, TapeSnapshot } from './types';
+import type { Frame, GraphHighlight, Snippet } from './types';
 
 export type RecordSnippetOptions = {
   machine: TuringMachine;
diff --git a/packages/visuals/src/types.ts b/packages/visuals/src/types.ts
index 10c4784..7975725 100644
--- a/packages/visuals/src/types.ts
+++ b/packages/visuals/src/types.ts
@@ -1,4 +1,4 @@
-import type { Graph } from '@turing-machine-js/machine';
+import type { Graph, TapeSnapshot } from '@turing-machine-js/machine';
 
 /**
  * State-graph highlight descriptor (machines-demo#10). MachineView derives it
@@ -32,15 +32,6 @@ export type GraphHighlight = {
   paused: boolean;
 };
 
-/**
- * Per-tape snapshot: the cells visible/usable plus the head's index into them.
- * Same shape as machines-demo's TapeSnapshot. Pure data — no library handles.
- */
-export type TapeSnapshot = {
-  symbols: string[];
-  position: number;
-};
-
 /**
  * One frame of a recorded snippet — the state of the machine at iter `step`.
  * Frame 0 = initial state (before any transition); frame N = state after iter N's transition.

From fb9810dd5296a5f16d18052cefcb9380cfdcbc4a Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Tue, 2 Jun 2026 10:00:36 +0300
Subject: [PATCH 113/118] refactor(machine): Tape.viewport shares centering
 loop with tapeViewport via internal core
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

tapeViewportFromAccess(position, width, cellAt) — internal helper for the
centering loop. Public tapeViewport(snapshot, width, blank) is a thin
wrapper passing a snapshot-bounds-checking cellAt; Tape.viewport calls
the core directly with its own cellAt that does Alphabet.get(#cellAt(i)).

The two surfaces serve different inputs (wire-data TapeSnapshot vs live
int-encoded Tape) but the centering math now lives once. Public APIs
unchanged. Tape.viewport's caching (#viewportDirty, #viewportBuffer) is
preserved.
---
 packages/machine/CHANGELOG.md                 |  7 ++-
 packages/machine/src/classes/Tape.ts          | 13 ++--
 .../machine/src/utilities/tapeViewport.ts     | 59 +++++++++++--------
 3 files changed, 48 insertions(+), 31 deletions(-)

diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index 75b3c48..42fb271 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -15,10 +15,15 @@ Eighth v7 pre-release. Lifts `TapeSnapshot` (the per-tape wire-data shape `{symb
 - **`TapeSnapshot` type** ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) — `{ symbols: string[]; position: number }`. The per-tape wire-data shape — what callers serialize a live `Tape` into for transmission (worker boundaries, snippet recording, snapshot tests). Previously lived in `@turing-machine-js/visuals`'s `types.ts` and was re-imported by the engine for `Frame.tape`-style fields. Now sits in the engine next to the live `Tape` class; `@turing-machine-js/visuals` re-exports it for consumer-import stability (so `import { TapeSnapshot } from '@turing-machine-js/visuals'` keeps working).
 - **`tapeViewport(snapshot, width, blank): { cells, headIndex }`** ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) — pure helper: fixed-width window over a `TapeSnapshot`, centered on the head, padded with `blank` for out-of-bounds cells. `headIndex` is deterministic at `Math.floor(width / 2)`. Throws `RangeError` on non-positive or non-integer width. Visuals re-exports.
 
+### Changed
+
+- **`Tape.viewport` getter now shares its centering loop with `tapeViewport`** via an internal `tapeViewportFromAccess(position, width, cellAt)` core. The public `tapeViewport(snapshot, width, blank)` signature is unchanged — it passes a snapshot-bounds-checking `cellAt`; `Tape.viewport` passes its own `(i) => alphabet.get(this.#cellAt(i))`. The two public surfaces serve different inputs (wire-data `TapeSnapshot` vs live int-encoded `Tape`) but the centering math lives once.
+
 ### Compatibility
 
 - **Consumers importing `TapeSnapshot` or `tapeViewport` from `@turing-machine-js/visuals` are unaffected** — visuals re-exports both from the engine.
-- **Engine's `Tape.viewport` getter is unchanged.** It operates on the live, internally-int-encoded tape via `Alphabet.get` — different data shape from the wire-data `TapeSnapshot`. The two surfaces serve different inputs and are not direct duplicates; the move was about locality (`TapeSnapshot` lives next to `Tape`), not internal dedup.
+- `Tape.viewport`'s public contract (returns a fresh `string[]` of length `viewportWidth`, head at `Math.floor(viewportWidth/2)`) is unchanged.
+- The internal `tapeViewportFromAccess` helper is `@internal` — not exported from the package root.
 
 ## [7.0.0-alpha.7] - 2026-05-30
 
diff --git a/packages/machine/src/classes/Tape.ts b/packages/machine/src/classes/Tape.ts
index 954487c..b011b73 100644
--- a/packages/machine/src/classes/Tape.ts
+++ b/packages/machine/src/classes/Tape.ts
@@ -1,4 +1,5 @@
 import Alphabet from './Alphabet';
+import { tapeViewportFromAccess } from '../utilities/tapeViewport';
 
 type TapeConstructorParameter = { alphabet: Alphabet, symbols?: string[], position?: number, viewportWidth?: number };
 
@@ -86,12 +87,12 @@ export default class Tape {
 
   get viewport() {
     if (this.#viewportDirty) {
-      const start = this.#position - this.extraCellsCount;
-
-      for (let i = 0; i < this.#viewportWidth; i += 1) {
-        this.#viewportBuffer[i] = this.#alphabet.get(this.#cellAt(start + i));
-      }
-
+      const { cells } = tapeViewportFromAccess(
+        this.#position,
+        this.#viewportWidth,
+        (i) => this.#alphabet.get(this.#cellAt(i)),
+      );
+      this.#viewportBuffer = cells;
       this.#viewportDirty = false;
     }
 
diff --git a/packages/machine/src/utilities/tapeViewport.ts b/packages/machine/src/utilities/tapeViewport.ts
index e8f3427..2879ba3 100644
--- a/packages/machine/src/utilities/tapeViewport.ts
+++ b/packages/machine/src/utilities/tapeViewport.ts
@@ -3,24 +3,48 @@
  * index into them. Pure data; no library handles.
  *
  * Produced by callers serializing a live `Tape` for transmission (worker
- * boundaries, snippet recording, snapshot tests). The engine's own
- * `Tape.viewport` getter operates on the live, internally-int-encoded
- * tape rather than on a `TapeSnapshot` — so it doesn't currently call
- * `tapeViewport` internally. The two surfaces serve different inputs
- * (string snapshot vs live int-encoded tape) and are not direct duplicates.
+ * boundaries, snippet recording, snapshot tests).
  */
 export type TapeSnapshot = {
   symbols: string[];
   position: number;
 };
 
+/**
+ * @internal — centering loop shared by the public `tapeViewport(snapshot, …)`
+ * helper AND the engine's `Tape.viewport` getter. Snapshot consumers pass a
+ * bounds-checking lambda over `symbols` + a `blank` fallback; the live `Tape`
+ * passes its own internal `cellAt` that does int → string via `Alphabet.get`.
+ *
+ * Each path picks its own data shape; the centering math lives once here.
+ */
+export function tapeViewportFromAccess(
+  position: number,
+  width: number,
+  cellAt: (idx: number) => string,
+): { cells: string[]; headIndex: number } {
+  if (!Number.isInteger(width) || width <= 0) {
+    throw new RangeError(
+      `tapeViewport: width must be a positive integer (got ${width})`,
+    );
+  }
+  const half = Math.floor(width / 2);
+  const startTapeIdx = position - half;
+  const cells: string[] = new Array(width);
+  for (let i = 0; i < width; i += 1) {
+    cells[i] = cellAt(startTapeIdx + i);
+  }
+  return { cells, headIndex: half };
+}
+
 /**
  * Compute a fixed-width window of tape cells centered on the head.
  *
  * The engine's `Tape` class exposes a `viewport` getter that does this for
- * the live tape; `tapeViewport` is the equivalent for the wire-data
- * `TapeSnapshot`. Cells outside the snapshot's `symbols` array are padded
- * with `blank`, so the result always has exactly `width` entries.
+ * the live tape (sharing the same internal centering core); `tapeViewport`
+ * is the equivalent for the wire-data `TapeSnapshot`. Cells outside the
+ * snapshot's `symbols` array are padded with `blank`, so the result always
+ * has exactly `width` entries.
  *
  * The returned `headIndex` is the head's index within `cells` —
  * deterministic at `Math.floor(width / 2)`, but exposed for callers that
@@ -34,20 +58,7 @@ export function tapeViewport(
   width: number,
   blank: string,
 ): { cells: string[]; headIndex: number } {
-  if (!Number.isInteger(width) || width <= 0) {
-    throw new RangeError(
-      `tapeViewport: width must be a positive integer (got ${width})`,
-    );
-  }
-  const half = Math.floor(width / 2);
-  const startTapeIdx = snapshot.position - half;
-  const cells: string[] = new Array(width);
-  for (let i = 0; i < width; i += 1) {
-    const tapeIdx = startTapeIdx + i;
-    cells[i] =
-      tapeIdx >= 0 && tapeIdx < snapshot.symbols.length
-        ? snapshot.symbols[tapeIdx]
-        : blank;
-  }
-  return { cells, headIndex: half };
+  return tapeViewportFromAccess(snapshot.position, width, (i) =>
+    i >= 0 && i < snapshot.symbols.length ? snapshot.symbols[i] : blank,
+  );
 }

From 2c5c553e6dde32a459780e905caa1943895f3379 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Tue, 2 Jun 2026 10:44:24 +0300
Subject: [PATCH 114/118] docs: catch up engine + visuals docs to
 v7.0.0-alpha.8 (#227 closure, TapeSnapshot home)

Engine README:
- Add TapeSnapshot type + tapeViewport helper to the Tape section
- Versioning notes section catches up alpha.5/6/7/8 (was at alpha.4);
  v7 milestone marked feature-complete with #102

Engine CLAUDE.md:
- visuals package bullet: TapeSnapshot listed as re-exported from engine
  (not native); version mentions updated to 7.0.0-alpha.8

Visuals README:
- TapeSnapshot type def line annotated 're-exported from
  @turing-machine-js/machine (alpha.8+); canonical home is engine'
---
 CLAUDE.md                  |  2 +-
 packages/machine/README.md | 22 +++++++++++++++++++++-
 packages/visuals/README.md |  2 +-
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6099276..f0ea25f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,7 @@ This is an npm-workspaces + Lerna monorepo (`packages/*`). Versioning is **locks
 - **`@turing-machine-js/builder`** — declarative state-table → machine builder; depends on `machine`. Soft-deprecated; see its README.
 - **`@turing-machine-js/library-binary-numbers`** — prebuilt states for `^…$`-delimited binary arithmetic on a 5-symbol alphabet; depends on `machine`.
 - **`@turing-machine-js/library-binary-numbers-bare`** — same operations on a 3-symbol alphabet (no markers, single number per tape, much smaller state graphs); depends on `machine`. Side-by-side with the marker-based library to make the alphabet-vs-graph-size trade-off visible.
-- **`@turing-machine-js/visuals`** (v7-only, [#204](https://github.com/mellonis/turing-machine-js/issues/204)) — pure highlight + graph-indexing logic for the engine `Graph`. Peer dep on `machine`, no runtime deps. Exposes `applyHighlight` / `applyIndicator` / `indexGraph` / `bareIdOf` / `highlightExpand` / `equivalentIds` / `recordingOps` (renderer-agnostic ops contract via `HighlightOps` / `IndicatorOps`), plus the `recordSnippet` artifact recorder (`Snippet` / `Frame` / `StepCommand` / `TapeSnapshot`) and the engine-edge-label formatter primitives (`formatStepNotation` / `tokenizeStep` / `formatTape`, the latter shipped in alpha.6.1). 16-rule contract for `applyHighlight` lives at `packages/visuals/docs/graph-highlight-and-breakpoints.md` (moved there from machines-demo). Used by machines-demo for graph highlight + step-log rendering; designed to be reusable by article embeds and any future Graph consumer that wants byte-identical edge-label notation to `toMermaid`. **Engine + libraries are at `7.0.0-alpha.6`; visuals at `7.0.0-alpha.6.1`** (visuals-only patch added formatter primitives + tokens).
+- **`@turing-machine-js/visuals`** (v7-only, [#204](https://github.com/mellonis/turing-machine-js/issues/204)) — pure highlight + graph-indexing logic for the engine `Graph`. Peer dep on `machine`, no runtime deps. Exposes `applyHighlight` / `applyIndicator` / `indexGraph` / `bareIdOf` / `highlightExpand` / `equivalentIds` / `recordingOps` (renderer-agnostic ops contract via `HighlightOps` / `IndicatorOps`), the `recordSnippet` artifact recorder + `SnippetPlayer` class (`Snippet` / `Frame` / `StepCommand`), and the engine-edge-label formatter primitives (`formatStepNotation` / `tokenizeStep` / `formatTape`, shipped in alpha.6.1). **`TapeSnapshot` + `tapeViewport` are re-exported from `@turing-machine-js/machine`** ([#227](https://github.com/mellonis/turing-machine-js/issues/227), v7.0.0-alpha.8 onward) — they live next to the `Tape` class in the engine; visuals re-exports for consumer-import stability. 16-rule contract for `applyHighlight` lives at `packages/visuals/docs/graph-highlight-and-breakpoints.md` (moved there from machines-demo). Used by machines-demo for graph highlight + step-log rendering; designed to be reusable by article embeds and any future Graph consumer that wants byte-identical edge-label notation to `toMermaid`. **Engine + libraries are at `7.0.0-alpha.8`; visuals at `7.0.0-alpha.8`** (re-aligned to lockstep after alpha.7.1 visuals-only patch).
 
 ### Versioning convention
 
diff --git a/packages/machine/README.md b/packages/machine/README.md
index f0bd58d..f328f6e 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -191,6 +191,18 @@ tape.viewportWidth;  // 7 (the constructor bumps even values to the next odd)
 
 `viewportWidth` defaults to `1` and must be ≥ 1; `tape.viewport` always has exactly `viewportWidth` cells regardless of how many symbols the tape actually holds. Useful for rendering a sliding window in a UI; ignore if you only need `tape.symbols` / `tape.position`.
 
+For wire-data tape transmission (worker boundaries, snippet recording, snapshot tests), the package exports the **`TapeSnapshot`** type (`{ symbols: string[]; position: number }`) and a pure-function equivalent of `Tape.viewport`:
+
+```javascript
+import { tapeViewport } from '@turing-machine-js/machine';
+
+const snapshot = { symbols: ['a', 'b', 'c'], position: 1 };
+const { cells, headIndex } = tapeViewport(snapshot, 7, ' ');
+// cells: [' ',' ','a','b','c',' ',' '], headIndex: 3
+```
+
+`tapeViewport(snapshot, width, blank)` returns `{ cells, headIndex }` with `cells.length === width` (out-of-bounds positions padded with `blank`) and `headIndex === Math.floor(width / 2)`. Throws `RangeError` on non-positive or non-integer width. `Tape.viewport` and `tapeViewport` share an internal centering core, so the two routes produce identical results when given equivalent inputs. (`TapeSnapshot` + `tapeViewport` are also re-exported from `@turing-machine-js/visuals` for backwards-compatible imports from earlier alphas; canonical home is `@turing-machine-js/machine` as of v7.0.0-alpha.8, [#227](https://github.com/mellonis/turing-machine-js/issues/227).)
+
 ### TapeBlock
 
 A bundle of one or more `Tape`s that the machine reads/writes together in lock-step. Construct via either factory:
@@ -840,7 +852,15 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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.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:
+- **v7** *(latest alpha: alpha.8, 2026-06-02)* — Composition-representation overhaul + first-class state tags + id-keyed `State.collectStates` lookup + `DebugSession` step controls + `CallFrame` + `tapeViewport`/`TapeSnapshot`. **Pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.8`). **v7 milestone is feature-complete with #102**; the stable v7.0.0 cut is the only remaining step. Highlights across alphas:
+
+  **alpha.8** — **`TapeSnapshot` type + `tapeViewport` helper** ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) moved into the engine from `@turing-machine-js/visuals`, next to the live `Tape` class (visuals re-exports for consumer-import stability). `Tape.viewport` getter refactored to share its centering loop with `tapeViewport` via an internal core — the centering math now lives once; the two public surfaces supply their own data-shape-appropriate `cellAt` lambdas. See [§Tape](#tape).
+
+  **alpha.7** — **`CallFrame` extraction** ([#213](https://github.com/mellonis/turing-machine-js/issues/213)) — `withOverriddenHaltState`'s wrapper is now a first-class `CallFrame extends State` subclass that delegates transition lookups + `debug` to its bare; `instanceof State` preserved (additive), `instanceof CallFrame` discriminates wrappers. Plus **`toMermaid` framed-wrapper emit fix** ([#223](https://github.com/mellonis/turing-machine-js/issues/223)) — `toGraph`'s reach-set now tunnels through wrappers AND captures the wrappers themselves, so framed-wrapper-continuations (e.g. `library-binary-numbers/minusOne`'s `goToNumberStart(invertNumberGoToNumberWithInversion)` inside `invertNumber`'s callable subtree) render inside the owner subgraph rather than escaping to the top level. `library-binary-numbers/states.md` regenerated under the new emit.
+
+  **alpha.6** — **Debugger step controls** ([#102](https://github.com/mellonis/turing-machine-js/issues/102)) — full reshape of the debug surface. `run()` is now **sync + callback-free**; `runStepByStep` is the **pure-iteration primitive** (no `state.debug` filter evaluation); a new **`DebugSession`** class (`new DebugSession(machine, {initialState})`) owns all interactive debugging via `pause` / `step` / `iter` / `halt` events, depth-based `stepIn` / `stepOver` / `stepOut`, external `pause()` / `stop()` / `setRunInterval(ms)`. Per-yield `m.debugBreak: {before?, after?, cause}` **replaced by one-sided `m.pause: {side, cause}`** on `pause` events only. See [§Debugging](#debugging).
+
+  **alpha.5** — Per-iter **`matchedTransition`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)) on every `MachineState` yield (`{id, matchKinds}`, `id` is `${stateId}.${ix}` resolvable in `toGraph`). **`haltState.debug` collapsed to a `boolean`** ([#207](https://github.com/mellonis/turing-machine-js/issues/207)) — object-shaped writes throw; halt pause fires on the AFTER side of the halt-triggering iter with `m.state` = the triggering state. `HaltState` typed alias narrows `debug` to `boolean` at the canonical access path.
 
   **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).
 
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index 286efcc..b20e776 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -49,7 +49,7 @@ type GraphHighlight = {
 type GraphIndexes = { /* node→frame, frame→wrappers, frame→label, etc. */ };
 
 // Recording artifact
-type TapeSnapshot = { symbols: string[]; position: number };
+type TapeSnapshot = { symbols: string[]; position: number };  // re-exported from @turing-machine-js/machine (alpha.8+); canonical home is the engine package, next to the Tape class
 type StepCommand = { movement: 'L' | 'R' | 'S'; symbol: string | null };
 type Frame = {
   step: number;

From c7f38ba87e35a3bac264581ce65056a7671b63b6 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Tue, 2 Jun 2026 22:12:56 +0300
Subject: [PATCH 115/118] docs: round-trip byte-stability scope +
 minusOne/minusOneFast state counts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refine the round-trip stability claim across CLAUDE.md, the engine
README, and test/round-trip.spec.ts. Previous wording said "stable for
all wrapped states including shared-bare cases" — that overstated the
guarantee. The accurate model:

- Simple wrappers (scanToX(eraseHere)-style): bytewise stable across
  toMermaid → fromMermaid → toGraph → toMermaid. The #139 regression
  test pins this.
- Shared-bare cases (library-binary-numbers/minusOne where
  invertNumber backs both the outermost bare and wrapper-W1's bare):
  emit a SINGLE de-duped node with &-joined call arrows; sharing
  survives the round-trip. But GraphNode ids are runtime State ids
  reassigned on every fromGraph rebuild, and a shared bare's
  post-rebuild id no longer follows the original emission order, so
  the byte stream reorders. Verify behavioural identity with
  equivalentOn → allAgree:true instead.

Also syncs in-source state-count comments for minusOne (15 → 18) and
minusOneFast (8 → 10) — the graphs.spec.ts test fixture already pins
these counts via summarizeGraph(graph).stateCount, so the comments
were lagging behind the source of truth.
---
 CLAUDE.md                                    |  2 +-
 packages/library-binary-numbers/src/index.ts |  6 +++---
 packages/machine/README.md                   |  4 ++--
 test/round-trip.spec.ts                      | 10 ++++++----
 4 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f0ea25f..be30f42 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -92,7 +92,7 @@ Key shapes that take reading multiple files to grasp:
 
 **Edge arrow styles** — solid `-->` for regular state-to-state transitions AND for the wrapper's post-return `--> override` (just an ordinary transition under the call/return mental model); bold `==> "call"` is RESERVED for the wrapper-to-bare call arrow (source: wrapper, target: its bare; `&` ribbon collapses multiple wrappers sharing a bare); dotted `-.->` for frame-level dispatch — `w_N -. "return" .-> wrapper` (demand-emit: only when the frame's halt marker has incoming edges AND a wrapper calls into the frame), `w_N -. "halt" .-> s0` (demand-emit: only when the frame has a non-wrapper entry path), and `idle -. enter .-> sN` for execution-start. **The `-. onHalt .->` keyword from v7 alpha.1 is retired** — wrapper-to-override is now just a regular solid arrow, and the dotted `-.->` style is reserved for frame-level dispatch.
 
-**Round-trip** is **bytewise stable for simple wrappers** (regression test in `test/round-trip.spec.ts` — #139). The wrapper's composite name (e.g. `scanToX(eraseHere)`) does NOT appear as a graph node label; only the bare's name does, so `fromGraph` recomputes the composite fresh on reconstruction — no accumulation. **Shared-bare cases** (same `State` instance used as the bare of multiple wrappers, e.g. `library-binary-numbers`'s `minusOne` where `invertNumber` is both the outermost bare AND wrapper-W1's bare) use **per-context duplication** in `toGraph`: each occurrence emits a separate graph node with the wrapper's `#id`. Reconstruction produces behaviorally-equivalent State instances (not necessarily the same runtime `#id`), but bytewise stability isn't guaranteed for shared-bare since duplicate ordering depends on runtime wrapper-ids that don't survive rebuild.
+**Round-trip** is **bytewise stable for simple wrappers** (regression test in `test/round-trip.spec.ts` — #139). The wrapper's composite name (e.g. `scanToX(eraseHere)`) does NOT appear as a graph node label; only the bare's name does, so `fromGraph` recomputes the composite fresh on reconstruction — no accumulation. **Shared-bare cases** (same `State` instance used as the bare of multiple wrappers, e.g. `library-binary-numbers`'s `minusOne` where `invertNumber` is both the outermost bare AND wrapper-W1's bare) do **not** duplicate: `toGraph`'s BFS de-dups by `State` id, so a shared bare emits a **single** node and the wrappers fan in via `&`-joined call arrows; `fromGraph` rebuilds one shared instance feeding all wrappers, so the sharing survives the round-trip. What isn't bytewise stable is the serialization itself — `GraphNode` ids are runtime `State` ids, reassigned on every `fromGraph` rebuild. For a simple wrapper the second `toGraph` matches the first up to id renaming; for a shared bare the post-rebuild id assignment no longer follows the original emission order, so the byte stream differs even though the graph describes the same machine. Reconstruction yields behaviorally-equivalent State instances (verify with `equivalentOn` → `allAgree: true`), never the same runtime `#id`.
 
 **Stats helpers** — `summarize(state, tapeBlock)` returns `{stateCount, transitionCount, compositionEdgeCount, maxCompositionDepth, selfLoopCount, hasCycles, tapeCount, alphabetCardinalities}`. `stateCount` filters out `isHaltMarker` sentinels (they're visualization-only, all map to the singleton `haltState` at runtime); matches the per-algorithm header in `library-binary-numbers/states.md` by construction. `equivalentOn(reference, candidate, cases)` is the separate behavioral-equivalence checker — runs both machines, compares outputs and per-step snapshots; lives in `./utilities/equivalence.ts`, unaffected by the visualization-layer changes above.
 
diff --git a/packages/library-binary-numbers/src/index.ts b/packages/library-binary-numbers/src/index.ts
index 8702973..59ec43b 100644
--- a/packages/library-binary-numbers/src/index.ts
+++ b/packages/library-binary-numbers/src/index.ts
@@ -268,7 +268,7 @@ const plusOne = new State({
   },
 }, 'plusOne');
 
-// minusOne — 15 nodes (the largest in this library, per `summarize().stateCount`)
+// minusOne — 18 nodes (the largest in this library, per `summarize().stateCount`)
 //
 // Computes x − 1 via the two's-complement identity:  x − 1 == ~(~x + 1)
 // (every step is a state we already have), composed with three nested
@@ -277,7 +277,7 @@ const plusOne = new State({
 // inner end is the terminal override target, not another wrapper level.
 //
 // This is *deliberately* the heavy version. It exists side-by-side with
-// minusOneFast (8 nodes, direct borrow) to make the cost of "compose existing
+// minusOneFast (10 nodes, direct borrow) to make the cost of "compose existing
 // pieces" vs "write a dedicated algorithm" visible. See ../states.md for the
 // dotted onHalt edges that show the three-deep wrapper chain.
 const minusOne = new State({
@@ -301,7 +301,7 @@ const minusOne = new State({
   },
 }, 'minusOne');
 
-// minusOneFast — 8 nodes (direct borrow propagation)
+// minusOneFast — 10 nodes (direct borrow propagation)
 //
 // Walks left from the LSB: 0→1 keeps borrowing; 1→0 stops; ^ is underflow.
 // Falls through to normalizeNumber to strip the leading zero introduced when the
diff --git a/packages/machine/README.md b/packages/machine/README.md
index f328f6e..68585a2 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -469,7 +469,7 @@ flowchart TD
 
 **Reading runtime sequence on tape `['a','b','X','b','a']`:** enter at wrapper `[[scanToX(eraseHere)]]` (with `eraseHere` queued as the override); `call` into the subtree of `scanToX`; `[*] → [K]/[R]` self-loops on `s1` until the head sees `X`; the `['X'] → [K]/[S]` edge lands on `c1`; `return` to the wrapper; solid `--> s2` to `eraseHere`; `eraseHere` runs `[*] → [E]/[S]` and halts at real `s0`. Run terminates.
 
-> 💡 **Round-trip stability.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for wrapped states ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). The callable-subtree emit (#174) eliminates per-context duplication: shared bares like `library-binary-numbers`'s `invertNumber` (used by two wrappers in `minusOne`) render as a single subtree with two `& `-joined call arrows — so even shared-bare cases now produce stable, dedup'd round-trips.
+> 💡 **Round-trip stability.** `toMermaid → fromMermaid → toGraph → toMermaid` is bytewise stable for **simple** wrapped states ([#139](https://github.com/mellonis/turing-machine-js/issues/139) regression). The callable-subtree emit (#174) eliminates per-context duplication: shared bares like `library-binary-numbers`'s `invertNumber` (used by two wrappers in `minusOne`) render as a single subtree with two `& `-joined call arrows, and `fromGraph` rebuilds one shared instance — the sharing survives the round-trip. Bytewise stability does **not** extend to shared-bare cases, though: node ids are runtime `State` ids reassigned on every rebuild, and a shared bare's post-rebuild id no longer follows the original emission order, so the serialization reorders. Use `equivalentOn` to confirm behavioural identity (`allAgree: true`) when bytewise comparison no longer applies.
 
 Wrappers nest: `inner.withOverriddenHaltState(middle).withOverriddenHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
 
@@ -871,7 +871,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
   **alpha.1** — initial v7 composition-representation overhaul:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
   - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
-  - **`toMermaid` callable-subtree emit** ([#174](https://github.com/mellonis/turing-machine-js/issues/174), supersedes the alpha.1 collapsed-bare shape from #138/#139). `withOverriddenHaltState` is modeled as a function call: the wrapper is a `[[composite-name]]` call site OUTSIDE any subgraph, the bare's reachable subtree becomes a `subgraph w_${frameId}["callable subtree of NAME"] … end` block containing the bare + body states + a per-frame halt marker `c${frameId}(((halt)))`. Frames are computed via union-find on bare-reachability — overlapping reach sets merge into a single union frame, so shared bares (`library-binary-numbers/minusOne`'s `invertNumber`) appear ONCE with `& `-joined call arrows from each wrapper. Bold `==> "call"` arrows are reserved for the wrapper-to-bare call; dotted `-.->` is reserved for frame-level dispatch (`return` / `halt` / `enter`). The retired `-. onHalt .->` keyword is replaced by a solid `--> override` arrow (just an ordinary transition under the call/return mental model). `GraphNode` gains `isWrapper`, `bareStateId`, `frameId` fields (and drops `isWrapped`). Bytewise round-trip stability now holds for all wrapped states including shared-bare cases (no per-context duplication).
+  - **`toMermaid` callable-subtree emit** ([#174](https://github.com/mellonis/turing-machine-js/issues/174), supersedes the alpha.1 collapsed-bare shape from #138/#139). `withOverriddenHaltState` is modeled as a function call: the wrapper is a `[[composite-name]]` call site OUTSIDE any subgraph, the bare's reachable subtree becomes a `subgraph w_${frameId}["callable subtree of NAME"] … end` block containing the bare + body states + a per-frame halt marker `c${frameId}(((halt)))`. Frames are computed via union-find on bare-reachability — overlapping reach sets merge into a single union frame, so shared bares (`library-binary-numbers/minusOne`'s `invertNumber`) appear ONCE with `& `-joined call arrows from each wrapper. Bold `==> "call"` arrows are reserved for the wrapper-to-bare call; dotted `-.->` is reserved for frame-level dispatch (`return` / `halt` / `enter`). The retired `-. onHalt .->` keyword is replaced by a solid `--> override` arrow (just an ordinary transition under the call/return mental model). `GraphNode` gains `isWrapper`, `bareStateId`, `frameId` fields (and drops `isWrapped`). No per-context duplication: a shared bare emits a single de-duped subtree and `fromGraph` rebuilds one shared instance. Bytewise round-trip stability holds for simple wrappers; shared-bare cases stay behaviourally equivalent (`equivalentOn`) but not byte-stable, because node ids are reassigned on rebuild and the serialization reorders.
 
 For the full release history, see the [GitHub releases page](https://github.com/mellonis/turing-machine-js/releases).
 
diff --git a/test/round-trip.spec.ts b/test/round-trip.spec.ts
index 4e6070b..35af9c4 100644
--- a/test/round-trip.spec.ts
+++ b/test/round-trip.spec.ts
@@ -104,10 +104,12 @@ describe('toGraph / toMermaid / fromMermaid / fromGraph round trip', () => {
   //
   // Uses the `scanToX(eraseHere)` example from #139's issue body — a simple
   // single-wrapper case. Shared-bare cases (like minusOne, where the same
-  // bare appears in two wrapper contexts via per-context duplication) have
-  // ids that depend on the wrapper's runtime `#id`; those ids reorder under
-  // sort-by-id across rebuild, which is a separate limitation not in #139's
-  // scope.
+  // bare backs two wrappers) emit a single de-duped node with `&`-joined
+  // call arrows — the sharing survives the round-trip. What doesn't survive
+  // bytewise is the serialization: node ids are runtime `State` ids, and a
+  // shared bare's post-rebuild id no longer follows the original emission
+  // order, so ids reorder under sort-by-id across rebuild. That's a separate
+  // limitation not in #139's scope.
   test('toMermaid round-trip is bytewise stable for wrapped states (regression for #139)', () => {
     const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
     const tapeBlock = TapeBlock.fromAlphabets([alphabet]);

From af920136246b57ad6f7cad7512a2a2f5aab87ce6 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 3 Jun 2026 06:07:15 +0300
Subject: [PATCH 116/118] chore(deps): bump root devDeps + npm audit fix for
 v7.0.0 cut
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

devDep bumps (all patch/minor):
- vitest + @vitest/coverage-v8 4.1.5 → 4.1.8
- rollup 4.60.3 → 4.61.0
- eslint 10.3.0 → 10.4.1
- typescript-eslint 8.59.2 → 8.60.1
- @types/node 25.6.2 → 25.9.1

`npm audit fix` clears 6 dev-only vulns (3 moderate / 3 high) under
nx/lerna toolchain — no production-runtime exposure.

Verified locally: build, test (664/664), lint, typecheck, coverage
baseline (99/94/100/99) all green.

Preparation for the v7.0.0 stable cut on PR #167.
---
 package-lock.json | 1087 +++++++++++++++++----------------------------
 package.json      |   12 +-
 2 files changed, 416 insertions(+), 683 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index d709e9a..db25187 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,14 +12,14 @@
       ],
       "devDependencies": {
         "@tsconfig/recommended": "^1.0.13",
-        "@types/node": "^25.6.2",
-        "@vitest/coverage-v8": "4.1.5",
-        "eslint": "^10.2.1",
+        "@types/node": "^25.9.1",
+        "@vitest/coverage-v8": "^4.1.8",
+        "eslint": "^10.4.1",
         "lerna": "^9.0.7",
-        "rollup": "^4.60.2",
+        "rollup": "^4.61.0",
         "typescript": "^6.0.3",
-        "typescript-eslint": "^8.59.1",
-        "vitest": "4.1.5"
+        "typescript-eslint": "^8.60.1",
+        "vitest": "^4.1.8"
       },
       "engines": {
         "npm": ">=7.0.0"
@@ -179,9 +179,9 @@
       }
     },
     "node_modules/@eslint/config-helpers": {
-      "version": "0.5.5",
-      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.5.5.tgz",
-      "integrity": "sha512-eIJYKTCECbP/nsKaaruF6LW967mtbQbsw4JTtSVkUQc9MneSkbrgPJAbKl9nWr0ZeowV8BfsarBmPpBzGelA2w==",
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.6.0.tgz",
+      "integrity": "sha512-ii6Bw9jJ2zi2cWA2Z+9/QZ/+3DX6kwaV5Q986D/CdP3Lap3w/pgQZ373FV7byY/i7L4IRH/G43I5dz1ClsCbpA==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
@@ -215,9 +215,9 @@
       }
     },
     "node_modules/@eslint/plugin-kit": {
-      "version": "0.7.1",
-      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.7.1.tgz",
-      "integrity": "sha512-rZAP3aVgB9ds9KOeUSL+zZ21hPmo8dh6fnIFwRQj5EAZl9gzR7wxYbYXYysAM8CTqGmUGyp2S4kUdV17MnGuWQ==",
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.7.2.tgz",
+      "integrity": "sha512-+CNAzxglkrpNf/kKywqQfk74QjtceuOE7Qm+AF8miRvPF/wmmK5+OJOgVh3AVTT3RP2mH3+FOaxlE5v72owk0A==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
@@ -980,19 +980,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/@npmcli/arborist/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@npmcli/fs": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/@npmcli/fs/-/fs-4.0.0.tgz",
@@ -1006,19 +993,6 @@
         "node": "^18.17.0 || >=20.5.0"
       }
     },
-    "node_modules/@npmcli/fs/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@npmcli/git": {
       "version": "7.0.2",
       "resolved": "https://registry.npmjs.org/@npmcli/git/-/git-7.0.2.tgz",
@@ -1079,19 +1053,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/@npmcli/git/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@npmcli/git/node_modules/which": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/which/-/which-6.0.1.tgz",
@@ -1223,19 +1184,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/@npmcli/metavuln-calculator/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@npmcli/name-from-folder": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/@npmcli/name-from-folder/-/name-from-folder-3.0.0.tgz",
@@ -1363,19 +1311,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/@npmcli/package-json/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@npmcli/promise-spawn": {
       "version": "9.0.1",
       "resolved": "https://registry.npmjs.org/@npmcli/promise-spawn/-/promise-spawn-9.0.1.tgz",
@@ -1537,23 +1472,10 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/@nx/devkit/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@nx/nx-darwin-arm64": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-darwin-arm64/-/nx-darwin-arm64-22.7.1.tgz",
-      "integrity": "sha512-m00ZmBn39VUgb0Ahhu5iY6D56ETdXjDbVnOz0XF3DacJrcLtq9sZ+cg1bj6PshqtvRWVg+zJRrZBU6vL7hGuFQ==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-darwin-arm64/-/nx-darwin-arm64-22.7.5.tgz",
+      "integrity": "sha512-eoPtwx0qZqvRUD+VVOHm150AlSYwYoPxkDHBBGqKCn5nzPspb0lLWw8q83crM/L1M928YgK0WmGf3C++7eqsTA==",
       "cpu": [
         "arm64"
       ],
@@ -1565,9 +1487,9 @@
       ]
     },
     "node_modules/@nx/nx-darwin-x64": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-darwin-x64/-/nx-darwin-x64-22.7.1.tgz",
-      "integrity": "sha512-DmD8Qow+Yt7Yrmjlz1AsfiwxW+0kRzg+6MY70+d7qChtD2bTzvA/k0ut8SMy+CxU3kxgUbKhGOtml5JDXoX2ww==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-darwin-x64/-/nx-darwin-x64-22.7.5.tgz",
+      "integrity": "sha512-VLOn/ZoEn3HfjSj+yIHLCM56/el79r+9I28CkZNHaSXJQWZ3edSkcgcfYjVxCurpN2VEwDQHLBeFCH8M+lQ7wQ==",
       "cpu": [
         "x64"
       ],
@@ -1579,9 +1501,9 @@
       ]
     },
     "node_modules/@nx/nx-freebsd-x64": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-freebsd-x64/-/nx-freebsd-x64-22.7.1.tgz",
-      "integrity": "sha512-HboVrUCHcuYTXtuX3dMyRszP7JO90ZVBLWgnmaM7jUM7jnllZjmezUMtpNHfN1GQbVFafJf/NBShDWsu9LuaUA==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-freebsd-x64/-/nx-freebsd-x64-22.7.5.tgz",
+      "integrity": "sha512-LEVer/E2xfGvK9Go+imMQoEninOoq/38Z2bhV1SD3AThXrp1xaLFVkW5jQ6juebeVkAeztEoMLFlr576egS0vw==",
       "cpu": [
         "x64"
       ],
@@ -1593,9 +1515,9 @@
       ]
     },
     "node_modules/@nx/nx-linux-arm-gnueabihf": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-linux-arm-gnueabihf/-/nx-linux-arm-gnueabihf-22.7.1.tgz",
-      "integrity": "sha512-5Gm8Y7L8WXMLUjHhiy1eqGz5/PiRw1YLanFg5audBNkZvH6Jkwzdpoz0dbeKjwMDHz4NmniUV1s76Th8VLWmiQ==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-linux-arm-gnueabihf/-/nx-linux-arm-gnueabihf-22.7.5.tgz",
+      "integrity": "sha512-NP27EFGpmFJM6RL1Ey/AFJ7gA2xuqtIHaw6jjSNGvfrnZRUNaway30GrVaGGeODf0DsvAty/unqoBMPy6kDHbw==",
       "cpu": [
         "arm"
       ],
@@ -1607,9 +1529,9 @@
       ]
     },
     "node_modules/@nx/nx-linux-arm64-gnu": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-linux-arm64-gnu/-/nx-linux-arm64-gnu-22.7.1.tgz",
-      "integrity": "sha512-GdgPYMfbijBRFJs1absL/9QdSNLsTAGdyKykDf9CaVxEMZ92VB+pncpX9Vn/ZBCSeeWTLF+bSK3UM5v+loIObQ==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-linux-arm64-gnu/-/nx-linux-arm64-gnu-22.7.5.tgz",
+      "integrity": "sha512-QLnkJl3HkHsPfpLiNiAiMfpfAeFpic0U1diAxF8RqChOkCpQ7ulvyBVgE1UrQxvhd+gFQ3ed5RNDxtCRw8nTiw==",
       "cpu": [
         "arm64"
       ],
@@ -1621,9 +1543,9 @@
       ]
     },
     "node_modules/@nx/nx-linux-arm64-musl": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-linux-arm64-musl/-/nx-linux-arm64-musl-22.7.1.tgz",
-      "integrity": "sha512-HyBgPtY1hyNTk8683nt7F29jh3lVdS/zul9vS0NgKeCSoYL3GRM3nLoTPynoHUxyVP/tWYOE3ymvnk92qYwL4Q==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-linux-arm64-musl/-/nx-linux-arm64-musl-22.7.5.tgz",
+      "integrity": "sha512-cEP6KmwBgnb38+jTTaibWCjwXcHmigqhTfy0tN1be7WZr6bHxbqNLsXqKRN70PSNA3HouZcxw1cdRL8tqbPBBA==",
       "cpu": [
         "arm64"
       ],
@@ -1635,9 +1557,9 @@
       ]
     },
     "node_modules/@nx/nx-linux-x64-gnu": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-linux-x64-gnu/-/nx-linux-x64-gnu-22.7.1.tgz",
-      "integrity": "sha512-bQBgRiEsanNvKcDOjVAUPjvcp0iDLofYYUL2af2iuCDxreLOej+J6MeA5bWTLNly5ly1d4voKGTqa+OsouVyLg==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-linux-x64-gnu/-/nx-linux-x64-gnu-22.7.5.tgz",
+      "integrity": "sha512-tbaX1tZCSpGifDNBfDdEZAMxVF3Yg4bhFP/bm1needc0diqb+Zflc0u5tM5/6BWDMITQDwenJVsNiQ8ZdtJURA==",
       "cpu": [
         "x64"
       ],
@@ -1649,9 +1571,9 @@
       ]
     },
     "node_modules/@nx/nx-linux-x64-musl": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-linux-x64-musl/-/nx-linux-x64-musl-22.7.1.tgz",
-      "integrity": "sha512-gcco2GjcAztF/fRcAgFxtWxrWDnQdNmPaAN9FTt1+qQ9RUSLvdL8bQxKx4Kd9N9T+gXPlrWhMkBkKbbV09+X1Q==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-linux-x64-musl/-/nx-linux-x64-musl-22.7.5.tgz",
+      "integrity": "sha512-H0M7csOZIgPT822LqjxSXzf4MXRND15vIkAQe3F3Jlr3Si8LC3tzbL52aVcRfgb8MF/xOB5U47mSwxWt1M2bPQ==",
       "cpu": [
         "x64"
       ],
@@ -1663,9 +1585,9 @@
       ]
     },
     "node_modules/@nx/nx-win32-arm64-msvc": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-win32-arm64-msvc/-/nx-win32-arm64-msvc-22.7.1.tgz",
-      "integrity": "sha512-IT9oEn0YQ83iPH7666aoPyTRsUzBIBJdBLMXeLX4I60fHPXWhUSGpfiLtIsgU2OfeOVb9hU9idwNh1wc4u9rWQ==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-win32-arm64-msvc/-/nx-win32-arm64-msvc-22.7.5.tgz",
+      "integrity": "sha512-JTcZch9YAnDL1gbhqePz3DZ4x7iYemLn1yJzrjbbXAmXju2eiiJiZvJJHbV06+SP9HKXDT8RjTKuAWTdVxnHug==",
       "cpu": [
         "arm64"
       ],
@@ -1677,9 +1599,9 @@
       ]
     },
     "node_modules/@nx/nx-win32-x64-msvc": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/@nx/nx-win32-x64-msvc/-/nx-win32-x64-msvc-22.7.1.tgz",
-      "integrity": "sha512-P2zeSKXVH2Eiwsb8UfP2rMMS7//cHWpiO4M9zt6q0c4lI/hN1vXBciRKVWruGk9ZrWLHuhaMAhG94+MJtzKuRQ==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/@nx/nx-win32-x64-msvc/-/nx-win32-x64-msvc-22.7.5.tgz",
+      "integrity": "sha512-ngcMyHdBJ9FSz2nHdbZ7gtJlFq0O2b05sPAsVMkZ18CKzdaA1qrBDJfsMO49hPCny505eiT766+CkKdaCDl5kA==",
       "cpu": [
         "x64"
       ],
@@ -1865,9 +1787,9 @@
       }
     },
     "node_modules/@oxc-project/types": {
-      "version": "0.128.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.128.0.tgz",
-      "integrity": "sha512-huv1Y/LzBJkBVHt3OlC7u0zHBW9qXf1FdD7sGmc1rXc2P1mTwHssYv7jyGx5KAACSCH+9B3Bhn6Z9luHRvf7pQ==",
+      "version": "0.133.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.133.0.tgz",
+      "integrity": "sha512-KzkdCd6Uxqnf6l3HOw1xfatAlUURA0g14cvBYFyJ5SaNOQbOUvBr9PKArcPcrNIeRsBdgcUzOGrhKveVpvOIGA==",
       "dev": true,
       "license": "MIT",
       "funding": {
@@ -1875,9 +1797,9 @@
       }
     },
     "node_modules/@rolldown/binding-android-arm64": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.18.tgz",
-      "integrity": "sha512-lIDyUAfD7U3+BWKzdxMbJcsYHuqXqmGz40aeRqvuAm3y5TkJSYTBW2RDrn65DJFPQqVjUAUqq5uz8urzQ8aBdQ==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.3.tgz",
+      "integrity": "sha512-454rs7jHngixp/NMxd5srYD57OnzSlZ/eFTETjORQHLwJG1lRtmNOJcBerZlfu4GjKqeq8aCCIQrMdHyhI51Hw==",
       "cpu": [
         "arm64"
       ],
@@ -1892,9 +1814,9 @@
       }
     },
     "node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.18.tgz",
-      "integrity": "sha512-apJq2ktnGp27nSInMR5Vcj8kY6xJzDAvfdIFlpDcAK/w4cDO58qVoi1YQsES/SKiFNge/6e4CUzgjfHduYqWpQ==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.3.tgz",
+      "integrity": "sha512-PcAhP+ynjURNyy8SKGl5DQP94aGuB/7JrXJb/t7P+hanXvQVMWzUvRRhBAcg/lNRadBhoUPqSoP4xw5tR/KBEA==",
       "cpu": [
         "arm64"
       ],
@@ -1909,9 +1831,9 @@
       }
     },
     "node_modules/@rolldown/binding-darwin-x64": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.18.tgz",
-      "integrity": "sha512-5Ofot8xbs+pxRHJqm9/9N/4sTQOvdrwEsmPE9pdLEEoAbdZtG6F2LMDfO1sp6ZAtXJuJV/21ew2srq3W8NXB5g==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.3.tgz",
+      "integrity": "sha512-9YpfeUvSE2RS7wysJ81uOZkXJz7f7Q55H2Gvp3VEw/EsahqDtrphrZ0EwDLK5vvKOzaCrBsjF8JmnMLcUt78Gg==",
       "cpu": [
         "x64"
       ],
@@ -1926,9 +1848,9 @@
       }
     },
     "node_modules/@rolldown/binding-freebsd-x64": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.18.tgz",
-      "integrity": "sha512-7h8eeOTT1eyqJyx64BFCnWZpNm486hGWt2sqeLLgDxA0xI1oGZ9H7gK1S85uNGmBhkdPwa/6reTxfFFKvIsebw==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.3.tgz",
+      "integrity": "sha512-yB1IlAsSNHncV6SCTL27/MVGR5htvQsoGxIv5KMGXALp+Ll1wYsn+x98M9MW7qa+NdSbvrrY7ANI4wLJ0n1e6g==",
       "cpu": [
         "x64"
       ],
@@ -1943,9 +1865,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.18.tgz",
-      "integrity": "sha512-eRcm/HVt9U/JFu5RKAEKwGQYtDCKWLiaH6wOnsSEp6NMBb/3Os8LgHZlNyzMpFVNmiiMFlfb2zEnebfzJrHFmg==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.3.tgz",
+      "integrity": "sha512-Yi30IVAAfLUCy2MseFjbB1jAMDl1VMCAas5StnYp8da9+CKvMd2H2cbEjWcw5NPaPqzvYkVIaF1nNUG+b7u/sw==",
       "cpu": [
         "arm"
       ],
@@ -1960,9 +1882,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm64-gnu": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.18.tgz",
-      "integrity": "sha512-SOrT/cT4ukTmgnrEz/Hg3m7LBnuCLW9psDeMKrimRWY4I8DmnO7Lco8W2vtqPmMkbVu8iJ+g4GFLVLLOVjJ9DQ==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.3.tgz",
+      "integrity": "sha512-jsO7R8To+AdlYgUmN5sHSCZbfhtMBkO0WUx8iORQnPcMMdgr7qM2DQmMwgabs3GhNztdmoKkMKQFHD6DTMCIQw==",
       "cpu": [
         "arm64"
       ],
@@ -1977,9 +1899,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm64-musl": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.18.tgz",
-      "integrity": "sha512-QWjdxN1HJCpBTAcZ5N5F7wju3gVPzRzSpmGzx7na0c/1qpN9CFil+xt+l9lV/1M6/gqHSNXCiqPfwhVJPeLnug==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.3.tgz",
+      "integrity": "sha512-VWkUHwWriDciit80wleYwKILoR/KMvxh/IdwS/paX+ZgpuRpCrKLUdadJbc0NpBEiyhpYawsJ73j9aCvOH+f7Q==",
       "cpu": [
         "arm64"
       ],
@@ -1994,9 +1916,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-ppc64-gnu": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.18.tgz",
-      "integrity": "sha512-ugCOyj7a4d9h3q9B+wXmf6g3a68UsjGh6dob5DHevHGMwDUbhsYNbSPxJsENcIttJZ9jv7qGM2UesLw5jqIhdg==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.3.tgz",
+      "integrity": "sha512-5f1laC0SlIR0yDbFCd8acUhvJIag6N3zC5P7oUPN6wX0aOma+uKJ0wBDH5aq7I1PVI2ttTlhJwzwRIBnLiSGEg==",
       "cpu": [
         "ppc64"
       ],
@@ -2011,9 +1933,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-s390x-gnu": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.18.tgz",
-      "integrity": "sha512-kKWRhbsotpXkGbcd5dllUWg5gEXcDAa8u5YnP9AV5DYNbvJHGzzuwv7dpmhc8NqKMJldl0a+x76IHbspEpEmdA==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.3.tgz",
+      "integrity": "sha512-Iq4ko0r4XsgbrF/LunNgHtAGLRRVE2kXonAXQ/MV0mC6jQpMOhW1SvtZja2EhC/kd05++bP78dsqBeIQyYJ6Yg==",
       "cpu": [
         "s390x"
       ],
@@ -2028,9 +1950,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-x64-gnu": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.18.tgz",
-      "integrity": "sha512-uCo8ElcCIAMyYAZyuIZ81oFkhTSIllNvUCHCAlbhlN4ji3uC28h7IIdlXyIvGO7HsuqnV9p3rD/bpH7XhIyhRw==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.3.tgz",
+      "integrity": "sha512-B8m6tD5+/N5FeNQFbKlLA/2yVq9ycQP1SeedyEYYKWBNR3ZQbkvIUcNnDNM03lO1l5F2roiiFJGgvoLLyZXtSg==",
       "cpu": [
         "x64"
       ],
@@ -2045,9 +1967,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-x64-musl": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.18.tgz",
-      "integrity": "sha512-XNOQZtuE6yUIvx4rwGemwh8kpL1xvU41FXy/s9K7T/3JVcqGzo3NfKM2HrbrGgfPYGFW42f07Wk++aOC6B9NWA==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.3.tgz",
+      "integrity": "sha512-pSdpdUJHkuCxun9LE7jvgUB9qsRgaiyNNCX7m/AvHTcq67AiT/Yhoxvw5zPfhrM8k/BfP8ce/hMOpthKDpEUow==",
       "cpu": [
         "x64"
       ],
@@ -2062,9 +1984,9 @@
       }
     },
     "node_modules/@rolldown/binding-openharmony-arm64": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.18.tgz",
-      "integrity": "sha512-tSn/kzrfa7tNOXr7sEacDBN4YsIqTyLqh45IO0nHDwtpKIDNDJr+VFojt+4klSpChxB29JLyduSsE0MKEwa65A==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.3.tgz",
+      "integrity": "sha512-OXXS3RKJgX2uLwM+gYyuH5omcH8fL1LJs96pZGgtetVCahON57+d4SJHzTgZiOjxgGkSnpXpOsWuPDGAKAigEg==",
       "cpu": [
         "arm64"
       ],
@@ -2079,9 +2001,9 @@
       }
     },
     "node_modules/@rolldown/binding-wasm32-wasi": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.18.tgz",
-      "integrity": "sha512-+J9YGmc+czgqlhYmwun3S3O0FIZhsH8ep2456xwjAdIOmuJxM7xz4P4PtrxU+Bz17a/5bqPA8o3HAAoX0teUdg==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.3.tgz",
+      "integrity": "sha512-JTtb8BWFynicNSoPrehsCzBtOKjZ6jhMiPFEmOiuXg1Fl8dn2KHQob+GuPSGR0dryQa1PQJbzjF3dqO/whhjLg==",
       "cpu": [
         "wasm32"
       ],
@@ -2162,9 +2084,9 @@
       }
     },
     "node_modules/@rolldown/binding-win32-arm64-msvc": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.18.tgz",
-      "integrity": "sha512-zsu47DgU0FQzSwi6sU9dZoEdUv7pc1AptSEz/Z8HBg54sV0Pbs3N0+CrIbTsgiu6EyoaNN9CHboqbLaz9lhOyQ==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.3.tgz",
+      "integrity": "sha512-gEdFFEN70A/jxb2svrWsN3aDL7OUtmvlOy+6fa2jxG8K0wQ1ZbdeLGnidov6Yu5/733dI5ySfzFlQ/cb0bSz1g==",
       "cpu": [
         "arm64"
       ],
@@ -2179,9 +2101,9 @@
       }
     },
     "node_modules/@rolldown/binding-win32-x64-msvc": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.18.tgz",
-      "integrity": "sha512-7H+3yqGgmnlDTRRhw/xpYY9J1kf4GC681nVc4GqKhExZTDrVVrV2tsOR9kso0fvgBdcTCcQShx4SLLoHgaLwhg==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.3.tgz",
+      "integrity": "sha512-eXB7CHuaQdqmJcc3koCNtNPmT/bj2gc999kUFgBxG8Ac0NdgXc4rkCHhqrgrhN3zddvvvrgzj1e90SuSfmyIXA==",
       "cpu": [
         "x64"
       ],
@@ -2196,16 +2118,16 @@
       }
     },
     "node_modules/@rolldown/pluginutils": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.18.tgz",
-      "integrity": "sha512-CUY5Mnhe64xQBGZEEXQ5WyZwsc1JU3vAZLIxtrsBt3LO6UOb+C8GunVKqe9sT8NeWb4lqSaoJtp2xo6GxT1MNw==",
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
+      "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
       "dev": true,
       "license": "MIT"
     },
     "node_modules/@rollup/rollup-android-arm-eabi": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.3.tgz",
-      "integrity": "sha512-x35CNW/ANXG3hE/EZpRU8MXX1JDN86hBb2wMGAtltkz7pc6cxgjpy1OMMfDosOQ+2hWqIkag/fGok1Yady9nGw==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.61.0.tgz",
+      "integrity": "sha512-dnxczajOqt0gesZlN5pGQ1s1imQVrsmCw5G2Ci4oM+0WvNz3pyRnlWrT7McoZIb8VlFwCawdmbWRmxRn7HI+VQ==",
       "cpu": [
         "arm"
       ],
@@ -2217,9 +2139,9 @@
       ]
     },
     "node_modules/@rollup/rollup-android-arm64": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.3.tgz",
-      "integrity": "sha512-xw3xtkDApIOGayehp2+Rz4zimfkaX65r4t47iy+ymQB2G4iJCBBfj0ogVg5jpvjpn8UWn/+q9tprxleYeNp3Hw==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.61.0.tgz",
+      "integrity": "sha512-Bp3JpGP00Vu3f238ivRrjf7z3xSzVPXqCmaJYA9t2c+c8vKYvOzmXF7LkkeUalTEGd6cZcSWe+PFIP3Vy48fRg==",
       "cpu": [
         "arm64"
       ],
@@ -2231,9 +2153,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-arm64": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.3.tgz",
-      "integrity": "sha512-vo6Y5Qfpx7/5EaamIwi0WqW2+zfiusVihKatLvtN1VFVy3D13uERk/6gZLU1UiHRL6fDXqj/ELIeVRGnvcTE1g==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.61.0.tgz",
+      "integrity": "sha512-zaYIpr670mUmmZ1tVzUFplbQbG7h3Gugx3L5FoqhsC2m/YnLlR1a7zVLmXNPy+iY1tFPEbNG+HHBXZGyId0G5w==",
       "cpu": [
         "arm64"
       ],
@@ -2245,9 +2167,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-x64": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.3.tgz",
-      "integrity": "sha512-D+0QGcZhBzTN82weOnsSlY7V7+RMmPuF1CkbxyMAGE8+ZHeUjyb76ZiWmBlCu//AQQONvxcqRbwZTajZKqjuOw==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.61.0.tgz",
+      "integrity": "sha512-+P49fvkv2dSoeevUW+lgZ/I2JHSsJCK1Lyjj7Cu6E4UHG4tS9XIefzIjo5qhgELjAclnen1rLzK2PMKJdo+Dyg==",
       "cpu": [
         "x64"
       ],
@@ -2259,9 +2181,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-arm64": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.3.tgz",
-      "integrity": "sha512-6HnvHCT7fDyj6R0Ph7A6x8dQS/S38MClRWeDLqc0MdfWkxjiu1HSDYrdPhqSILzjTIC/pnXbbJbo+ft+gy/9hQ==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.61.0.tgz",
+      "integrity": "sha512-l3FAAOyKJXH2ea6KNFN+MMgC/rnE94YGLXs2ehYqDcCoHt1DpvgWX75BhUJxN38XojP7Ul+4H8PRn7EdyqSDrw==",
       "cpu": [
         "arm64"
       ],
@@ -2273,9 +2195,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-x64": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.3.tgz",
-      "integrity": "sha512-KHLgC3WKlUYW3ShFKnnosZDOJ0xjg9zp7au3sIm2bs/tGBeC2ipmvRh/N7JKi0t9Ue20C0dpEshi8WUubg+cnA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.61.0.tgz",
+      "integrity": "sha512-VokPN3TSctKj65cyCNPaUh4vMFA8awxOot/0sp+4J7ZlNRKQEhXhawqPwajoi8H5ZFt61i0ugZJuTKXBjGJ17Q==",
       "cpu": [
         "x64"
       ],
@@ -2287,9 +2209,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.3.tgz",
-      "integrity": "sha512-DV6fJoxEYWJOvaZIsok7KrYl0tPvga5OZ2yvKHNNYyk/2roMLqQAbGhr78EQ5YhHpnhLKJD3S1WFusAkmUuV5g==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.61.0.tgz",
+      "integrity": "sha512-DxH0P3wxm+Yzs/p3zrk9dw1rURu8p0Nv5+MRK/L7OtnLNg5rLZraSBFZ8iUXOd9f2BlhJyEpIZUH/emjq4UJ4g==",
       "cpu": [
         "arm"
       ],
@@ -2301,9 +2223,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-musleabihf": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.3.tgz",
-      "integrity": "sha512-mQKoJAzvuOs6F+TZybQO4GOTSMUu7v0WdxEk24krQ/uUxXoPTtHjuaUuPmFhtBcM4K0ons8nrE3JyhTuCFtT/w==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.61.0.tgz",
+      "integrity": "sha512-T6ZvMNe84kAz6TBWHC7hGAoEtzP1LWYw/AqayGWEF6uISt3Abk/st06LqRD9THd7Xz3NxzurUpzAuEAUbZf+nw==",
       "cpu": [
         "arm"
       ],
@@ -2315,9 +2237,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-gnu": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.3.tgz",
-      "integrity": "sha512-Whjj2qoiJ6+OOJMGptTYazaJvjOJm+iKHpXQM1P3LzGjt7Ff++Tp7nH4N8J/BUA7R9IHfDyx4DJIflifwnbmIA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.61.0.tgz",
+      "integrity": "sha512-q/4hzvQkDs8b4jIBab1pnLiiM0ayTZsN2amBFPDzuyZxjEd4wDwx0UJFYM3cOZzSf5Kw8fnWSprJzIBMkcR44Q==",
       "cpu": [
         "arm64"
       ],
@@ -2329,9 +2251,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-musl": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.3.tgz",
-      "integrity": "sha512-4YTNHKqGng5+yiZt3mg77nmyuCfmNfX4fPmyUapBcIk+BdwSwmCWGXOUxhXbBEkFHtoN5boLj/5NON+u5QC9tg==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.61.0.tgz",
+      "integrity": "sha512-vvYWX3akdEAY6km+9wAqFDnk6pQsbJKVnj7xawcvs/+fdlYBGp+U+Qq/lLfpIxYIZvZLHMAKD9HLdacSx/r3dw==",
       "cpu": [
         "arm64"
       ],
@@ -2343,9 +2265,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-loong64-gnu": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.3.tgz",
-      "integrity": "sha512-SU3kNlhkpI4UqlUc2VXPGK9o886ZsSeGfMAX2ba2b8DKmMXq4AL7KUrkSWVbb7koVqx41Yczx6dx5PNargIrEA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.61.0.tgz",
+      "integrity": "sha512-DePa5cqOxDP/Zp0VOXpeWaGew5iIv5DXp9NYbzkX5PFQyWVX9184WCTh3hvr/7lhXo8ZVlbFLkz8+o/q1dU6gA==",
       "cpu": [
         "loong64"
       ],
@@ -2357,9 +2279,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-loong64-musl": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.3.tgz",
-      "integrity": "sha512-6lDLl5h4TXpB1mTf2rQWnAk/LcXrx9vBfu/DT5TIPhvMhRWaZ5MxkIc8u4lJAmBo6klTe1ywXIUHFjylW505sg==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.61.0.tgz",
+      "integrity": "sha512-LV8aWMB8UChglMCEzs7RkN0GsH29RJaLLqwm9fCIjlqwxQTiWAqNcc7wjBkH31hV0PU/yVxGYvrYsgfea2qw6g==",
       "cpu": [
         "loong64"
       ],
@@ -2371,9 +2293,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-ppc64-gnu": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.3.tgz",
-      "integrity": "sha512-BMo8bOw8evlup/8G+cj5xWtPyp93xPdyoSN16Zy90Q2QZ0ZYRhCt6ZJSwbrRzG9HApFabjwj2p25TUPDWrhzqQ==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.61.0.tgz",
+      "integrity": "sha512-QoNSnwQtaeNu5grdBbsL0tt1uyl5EnS8DA8Mr3nluMXbhdQNyhN+G4tBax7VCdxLKj8YJ0/4OO9Ho84jMnJtKA==",
       "cpu": [
         "ppc64"
       ],
@@ -2385,9 +2307,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-ppc64-musl": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.3.tgz",
-      "integrity": "sha512-E0L8X1dZN1/Rph+5VPF6Xj2G7JJvMACVXtamTJIDrVI44Y3K+G8gQaMEAavbqCGTa16InptiVrX6eM6pmJ+7qA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.61.0.tgz",
+      "integrity": "sha512-/zZp5MKapIIApE8trN8qLGNSiRN9TUoaUZ1cmVu4XnVdd5LQLOXTtyi+vtfUbNnT3iyjzpPqYeKXmvJ+gJGYWw==",
       "cpu": [
         "ppc64"
       ],
@@ -2399,9 +2321,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-gnu": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.3.tgz",
-      "integrity": "sha512-oZJ/WHaVfHUiRAtmTAeo3DcevNsVvH8mbvodjZy7D5QKvCefO371SiKRpxoDcCxB3PTRTLayWBkvmDQKTcX/sw==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.61.0.tgz",
+      "integrity": "sha512-RbrzcD3aJ1k3UbtMRRBNwojdVVyXjuVAFTfn/xPa6EEl6GE9Sm/akPgFTb9aAC9pMKGJ6CtWxaGrqWcabH+ySg==",
       "cpu": [
         "riscv64"
       ],
@@ -2413,9 +2335,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-musl": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.3.tgz",
-      "integrity": "sha512-Dhbyh7j9FybM3YaTgaHmVALwA8AkUwTPccyCQ79TG9AJUsMQqgN1DDEZNr4+QUfwiWvLDumW5vdwzoeUF+TNxQ==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.61.0.tgz",
+      "integrity": "sha512-ZF+onDsBso8PJf1XaG9lB+O9RnBpKGnY6OrzC4CSHrtC1jb6jWLTKK4bRqdoCXHd22gyr2hiYmEAm8Wns/BOCw==",
       "cpu": [
         "riscv64"
       ],
@@ -2427,9 +2349,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-s390x-gnu": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.3.tgz",
-      "integrity": "sha512-cJd1X5XhHHlltkaypz1UcWLA8AcoIi1aWhsvaWDskD1oz2eKCypnqvTQ8ykMNI0RSmm7NkTdSqSSD7zM0xa6Ig==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.61.0.tgz",
+      "integrity": "sha512-Atk0aSIk5Zx2Wuh9dgRQgLP0Koc8hOeYpbWryMXyk8G8/HmPkwPPkMqIIDhrXHHYqfUzSJA/I7IWSBv8xSmRBA==",
       "cpu": [
         "s390x"
       ],
@@ -2441,9 +2363,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-gnu": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.3.tgz",
-      "integrity": "sha512-DAZDBHQfG2oQuhY7mc6I3/qB4LU2fQCjRvxbDwd/Jdvb9fypP4IJ4qmtu6lNjes6B531AI8cg1aKC2di97bUxA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.61.0.tgz",
+      "integrity": "sha512-0uMOcf3eZ5K+K4cYHkdxShFMPlPXCOdfDFEFn9dNYAEEd2cVvmOfH7zFgRVoDgmtQ1m9k5q7qfrHzyMAubKYUA==",
       "cpu": [
         "x64"
       ],
@@ -2455,9 +2377,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-musl": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.3.tgz",
-      "integrity": "sha512-cRxsE8c13mZOh3vP+wLDxpQBRrOHDIGOWyDL93Sy0Ga8y515fBcC2pjUfFwUe5T7tqvTvWbCpg1URM/AXdWIXA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.61.0.tgz",
+      "integrity": "sha512-mvFtE4A/t/7hRJ7X8Ozmu8FsIkAUat2nzl12pgU337BRmq87AQUJztwHz2Zv5/tjo9/C95E66CK03SI/ToEDJw==",
       "cpu": [
         "x64"
       ],
@@ -2469,9 +2391,9 @@
       ]
     },
     "node_modules/@rollup/rollup-openbsd-x64": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.3.tgz",
-      "integrity": "sha512-QaWcIgRxqEdQdhJqW4DJctsH6HCmo5vHxY0krHSX4jMtOqfzC+dqDGuHM87bu4H8JBeibWx7jFz+h6/4C8wA5Q==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.61.0.tgz",
+      "integrity": "sha512-z9b9+aTxvt8n2rNltMPvyaUfB8NJ+CVyOrGK/MdIKHx7B+lXmZpm/XbRsU7Rpf3fRqJ2uS6mBJiJveCtq8LHDg==",
       "cpu": [
         "x64"
       ],
@@ -2483,9 +2405,9 @@
       ]
     },
     "node_modules/@rollup/rollup-openharmony-arm64": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.3.tgz",
-      "integrity": "sha512-AaXwSvUi3QIPtroAUw1t5yHGIyqKEXwH54WUocFolZhpGDruJcs8c+xPNDRn4XiQsS7MEwnYsHW2l0MBLDMkWg==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.61.0.tgz",
+      "integrity": "sha512-jXaXFqKMehsOc+g8R6oo33RRC6w07G9jDBxAE5eAKX7mOcCbZloYIPNhfG9Wl+P9O9IWHFO4OJgPi1Ml2qkt7w==",
       "cpu": [
         "arm64"
       ],
@@ -2497,9 +2419,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-arm64-msvc": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.3.tgz",
-      "integrity": "sha512-65LAKM/bAWDqKNEelHlcHvm2V+Vfb8C6INFxQXRHCvaVN1rJfwr4NvdP4FyzUaLqWfaCGaadf6UbTm8xJeYfEg==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.61.0.tgz",
+      "integrity": "sha512-OXNWVFocS2IA4+QplhTZZ2a+8hPZR7T8KuozsNmJKK8y7cp83StHvGksfHzPG3wczWTczyWHVQuqeiTUbjiyBg==",
       "cpu": [
         "arm64"
       ],
@@ -2511,9 +2433,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-ia32-msvc": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.3.tgz",
-      "integrity": "sha512-EEM2gyhBF5MFnI6vMKdX1LAosE627RGBzIoGMdLloPZkXrUN0Ckqgr2Qi8+J3zip/8NVVro3/FjB+tjhZUgUHA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.61.0.tgz",
+      "integrity": "sha512-AlAbNtBO637LxSldqV43z0FfXoGfl2TW1DgAg/bs7aQswFbDewz2SJm3BUhiGfbOVtW571xbc9p+REdxhyN/Eg==",
       "cpu": [
         "ia32"
       ],
@@ -2525,9 +2447,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-gnu": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.3.tgz",
-      "integrity": "sha512-E5Eb5H/DpxaoXH++Qkv28RcUJboMopmdDUALBczvHMf7hNIxaDZqwY5lK12UK1BHacSmvupoEWGu+n993Z0y1A==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.61.0.tgz",
+      "integrity": "sha512-QRSrQXyJ1M4tjNXdR0/G/IgV6lzfQQJYBjlWIEYkY2Xs86DRl/iEpQ4blMDjJxSl7n19eDKKXMg0AmuBVYy8pQ==",
       "cpu": [
         "x64"
       ],
@@ -2539,9 +2461,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-msvc": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.3.tgz",
-      "integrity": "sha512-hPt/bgL5cE+Qp+/TPHBqptcAgPzgj46mPcg/16zNUmbQk0j+mOEQV/+Lqu8QRtDV3Ek95Q6FeFITpuhl6OTsAA==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.61.0.tgz",
+      "integrity": "sha512-tkuFxhvKO/HlGd0VsINF6vHSYH8AF8W0TcNxKDK6JZmrehngFj78pToc8iemtnvwilDjs2G/qSzYFhe9U8q+fw==",
       "cpu": [
         "x64"
       ],
@@ -2842,13 +2764,13 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "25.6.2",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.2.tgz",
-      "integrity": "sha512-sokuT28dxf9JT5Kady1fsXOvI4HVpjZa95NKT5y9PNTIrs2AsobR4GFAA90ZG8M+nxVRLysCXsVj6eGC7Vbrlw==",
+      "version": "25.9.1",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.1.tgz",
+      "integrity": "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "undici-types": "~7.19.0"
+        "undici-types": ">=7.24.0 <7.24.7"
       }
     },
     "node_modules/@types/normalize-package-data": {
@@ -2859,17 +2781,17 @@
       "license": "MIT"
     },
     "node_modules/@typescript-eslint/eslint-plugin": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.59.2.tgz",
-      "integrity": "sha512-j/bwmkBvHUtPNxzuWe5z6BEk3q54YRyGlBXkSsmfoih7zNrBvl5A9A98anlp/7JbyZcWIJ8KXo/3Tq/DjFLtuQ==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.60.1.tgz",
+      "integrity": "sha512-JQ4S5GB0tfjO8BuJ4fcX+HodkzJjYBV+7OJ+wLygaX7OGQ7FudyHL4NSCA6ob+w3Yn+5MkKIozOwQhXeM7opVg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@eslint-community/regexpp": "^4.12.2",
-        "@typescript-eslint/scope-manager": "8.59.2",
-        "@typescript-eslint/type-utils": "8.59.2",
-        "@typescript-eslint/utils": "8.59.2",
-        "@typescript-eslint/visitor-keys": "8.59.2",
+        "@typescript-eslint/scope-manager": "8.60.1",
+        "@typescript-eslint/type-utils": "8.60.1",
+        "@typescript-eslint/utils": "8.60.1",
+        "@typescript-eslint/visitor-keys": "8.60.1",
         "ignore": "^7.0.5",
         "natural-compare": "^1.4.0",
         "ts-api-utils": "^2.5.0"
@@ -2882,7 +2804,7 @@
         "url": "https://opencollective.com/typescript-eslint"
       },
       "peerDependencies": {
-        "@typescript-eslint/parser": "^8.59.2",
+        "@typescript-eslint/parser": "^8.60.1",
         "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
         "typescript": ">=4.8.4 <6.1.0"
       }
@@ -2898,16 +2820,16 @@
       }
     },
     "node_modules/@typescript-eslint/parser": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.59.2.tgz",
-      "integrity": "sha512-plR3pp6D+SSUn1HM7xvSkx12/DhoHInI2YF35KAcVFNZvlC0gtrWqx7Qq1oH2Ssgi0vlFRCTbP+DZc7B9+TtsQ==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.60.1.tgz",
+      "integrity": "sha512-A0M6ua6H252bVjPvvtSgl2QA4+ET9S5Mtkb2GDyTxIhH/C4qDItT7RQNO5PhMC6NXGYXOR9dIalcDDgBKT7oFA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/scope-manager": "8.59.2",
-        "@typescript-eslint/types": "8.59.2",
-        "@typescript-eslint/typescript-estree": "8.59.2",
-        "@typescript-eslint/visitor-keys": "8.59.2",
+        "@typescript-eslint/scope-manager": "8.60.1",
+        "@typescript-eslint/types": "8.60.1",
+        "@typescript-eslint/typescript-estree": "8.60.1",
+        "@typescript-eslint/visitor-keys": "8.60.1",
         "debug": "^4.4.3"
       },
       "engines": {
@@ -2923,14 +2845,14 @@
       }
     },
     "node_modules/@typescript-eslint/project-service": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.59.2.tgz",
-      "integrity": "sha512-+2hqvEkeyf/0FBor67duF0Ll7Ot8jyKzDQOSrxazF/danillRq2DwR9dLptsXpoZQqxE1UisSmoZewrlPas9Vw==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.60.1.tgz",
+      "integrity": "sha512-eXkTH2bxmXlqD1RnOPmLZ9ZM9D3VwSx04JOwBnP9RQ+yUA5a2Mu7SfW8uaV2Aon53NJzZlZYuX7tn91Izf+xaw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/tsconfig-utils": "^8.59.2",
-        "@typescript-eslint/types": "^8.59.2",
+        "@typescript-eslint/tsconfig-utils": "^8.60.1",
+        "@typescript-eslint/types": "^8.60.1",
         "debug": "^4.4.3"
       },
       "engines": {
@@ -2945,14 +2867,14 @@
       }
     },
     "node_modules/@typescript-eslint/scope-manager": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.59.2.tgz",
-      "integrity": "sha512-JzfyEpEtOU89CcFSwyNS3mu4MLvLSXqnmX05+aKBDM+TdR5jzcGOEBwxwGNxrEQ7p/z6kK2WyioCGBf2zZBnvg==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.60.1.tgz",
+      "integrity": "sha512-gvI5OQoptnxQnchOirukCuQ55svJSTuD/4k5+pC267xyBtYry748R9/c3tYUzb/iE6RZfllRz2lVulLCHkTm4w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/types": "8.59.2",
-        "@typescript-eslint/visitor-keys": "8.59.2"
+        "@typescript-eslint/types": "8.60.1",
+        "@typescript-eslint/visitor-keys": "8.60.1"
       },
       "engines": {
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -2963,9 +2885,9 @@
       }
     },
     "node_modules/@typescript-eslint/tsconfig-utils": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.59.2.tgz",
-      "integrity": "sha512-BKK4alN7oi4C/zv4VqHQ+uRU+lTa6JGIZ7s1juw7b3RHo9OfKB+bKX3u0iVZetdsUCBBkSbdWbarJbmN0fTeSw==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.60.1.tgz",
+      "integrity": "sha512-nh8w4qAteiKuZu3pSSzG/yGKpw0OlkrKnzFmbVRenKaD4qc+7i1GrmZaLVkr8rk4uipiPGMOW4YsM6WmKZ5CvA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -2980,15 +2902,15 @@
       }
     },
     "node_modules/@typescript-eslint/type-utils": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.59.2.tgz",
-      "integrity": "sha512-nhqaj1nmTdVVl/BP5omXNRGO38jn5iosis2vbdmupF2txCf8ylWT8lx+JlvMYYVqzGVKtjojUFoQ3JRWK+mfzQ==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.60.1.tgz",
+      "integrity": "sha512-sdwTrpjosW7ANQYJ39ZBF1ZyEMEGVB2UsikrserVM/30a/F1dTLnu9bGxEdosugyu5caigjLrR2qiD11asjI1A==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/types": "8.59.2",
-        "@typescript-eslint/typescript-estree": "8.59.2",
-        "@typescript-eslint/utils": "8.59.2",
+        "@typescript-eslint/types": "8.60.1",
+        "@typescript-eslint/typescript-estree": "8.60.1",
+        "@typescript-eslint/utils": "8.60.1",
         "debug": "^4.4.3",
         "ts-api-utils": "^2.5.0"
       },
@@ -3005,9 +2927,9 @@
       }
     },
     "node_modules/@typescript-eslint/types": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.59.2.tgz",
-      "integrity": "sha512-e82GVOE8Ps3E++Egvb6Y3Dw0S10u8NkQ9KXmtRhCWJJ8kDhOJTvtMAWnFL16kB1583goCWXsr0NieKCZMs2/0Q==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.60.1.tgz",
+      "integrity": "sha512-4h0tY8ppCkdCzcrl2YM5M3my0xsE1Tf8om3owEu5oPWmXwkKRmk0j0LGDzYBGUcAlesEbxBhazqu/K4cu3Ug7w==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -3019,16 +2941,16 @@
       }
     },
     "node_modules/@typescript-eslint/typescript-estree": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.59.2.tgz",
-      "integrity": "sha512-o0XPGNwcWw+FIwStOWn+BwBuEmL6QXP0rsvAFg7ET1dey1Nr6Wb1ac8p5HEsK0ygO/6mUxlk+YWQD9xcb/nnXg==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.60.1.tgz",
+      "integrity": "sha512-alpRkfG8hlVE5kdJW2GkfgDgXxold3e8e4l6EnmhRmRLbekgAPCCGDVD++sABy9FcgPFroq+uFcCSM1vR57Cew==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/project-service": "8.59.2",
-        "@typescript-eslint/tsconfig-utils": "8.59.2",
-        "@typescript-eslint/types": "8.59.2",
-        "@typescript-eslint/visitor-keys": "8.59.2",
+        "@typescript-eslint/project-service": "8.60.1",
+        "@typescript-eslint/tsconfig-utils": "8.60.1",
+        "@typescript-eslint/types": "8.60.1",
+        "@typescript-eslint/visitor-keys": "8.60.1",
         "debug": "^4.4.3",
         "minimatch": "^10.2.2",
         "semver": "^7.7.3",
@@ -3046,23 +2968,10 @@
         "typescript": ">=4.8.4 <6.1.0"
       }
     },
-    "node_modules/@typescript-eslint/typescript-estree/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@typescript-eslint/typescript-estree/node_modules/tinyglobby": {
-      "version": "0.2.16",
-      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
-      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "version": "0.2.17",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3077,16 +2986,16 @@
       }
     },
     "node_modules/@typescript-eslint/utils": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.59.2.tgz",
-      "integrity": "sha512-Juw3EinkXqjaffxz6roowvV7GZT/kET5vSKKZT6upl5TXdWkLkYmNPXwDDL2Vkt2DPn0nODIS4egC/0AGxKo/Q==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.60.1.tgz",
+      "integrity": "sha512-h2MPBLoNtjc3qZWfY3Tl51yPorQ2McHn8pJfcMNTcIvrrZrr90Ykffit0yjrPFWQcRcUxzH20+6OcVdW4yHtUg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.9.1",
-        "@typescript-eslint/scope-manager": "8.59.2",
-        "@typescript-eslint/types": "8.59.2",
-        "@typescript-eslint/typescript-estree": "8.59.2"
+        "@typescript-eslint/scope-manager": "8.60.1",
+        "@typescript-eslint/types": "8.60.1",
+        "@typescript-eslint/typescript-estree": "8.60.1"
       },
       "engines": {
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -3101,13 +3010,13 @@
       }
     },
     "node_modules/@typescript-eslint/visitor-keys": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.59.2.tgz",
-      "integrity": "sha512-NwjLUnGy8/Zfx23fl50tRC8rYaYnM52xNRYFAXvmiil9yh1+K6aRVQMnzW6gQB/1DLgWt977lYQn7C+wtgXZiA==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.60.1.tgz",
+      "integrity": "sha512-EbGRQg4FhrmwLodl+t3JNAnXHWVr9Vp+Zl1QBZVPY4ByfkzIT8cX3K6QWODHtkIZqqJVEWvhHSx3v5PDHsaQag==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/types": "8.59.2",
+        "@typescript-eslint/types": "8.60.1",
         "eslint-visitor-keys": "^5.0.0"
       },
       "engines": {
@@ -3119,14 +3028,14 @@
       }
     },
     "node_modules/@vitest/coverage-v8": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.5.tgz",
-      "integrity": "sha512-38C0/Ddb7HcRG0Z4/DUem8x57d2p9jYgp18mkaYswEOQBGsI1CG4f/hjm0ZCeaJfWhSZ4k7jgs29V1Zom7Ki9A==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.8.tgz",
+      "integrity": "sha512-lt3kovsyHwYe00wq4D1ti0Z974fWj4NLp6siqiyEufUpyFwK9Yhi7rBhac9JL5aA0zoMrJqc4vYPZRUnI7l7nw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@bcoe/v8-coverage": "^1.0.2",
-        "@vitest/utils": "4.1.5",
+        "@vitest/utils": "4.1.8",
         "ast-v8-to-istanbul": "^1.0.0",
         "istanbul-lib-coverage": "^3.2.2",
         "istanbul-lib-report": "^3.0.1",
@@ -3140,8 +3049,8 @@
         "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
-        "@vitest/browser": "4.1.5",
-        "vitest": "4.1.5"
+        "@vitest/browser": "4.1.8",
+        "vitest": "4.1.8"
       },
       "peerDependenciesMeta": {
         "@vitest/browser": {
@@ -3160,16 +3069,16 @@
       }
     },
     "node_modules/@vitest/expect": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.5.tgz",
-      "integrity": "sha512-PWBaRY5JoKuRnHlUHfpV/KohFylaDZTupcXN1H9vYryNLOnitSw60Mw9IAE2r67NbwwzBw/Cc/8q9BK3kIX8Kw==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.8.tgz",
+      "integrity": "sha512-h3nDO677RDLEGlBxyQ5CW8RlMThSKSRLUePLOx09gNIWRL40edgA1GCZSZgf1W55MFAG6/Sw14KeaAnqv0NKdQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@standard-schema/spec": "^1.1.0",
         "@types/chai": "^5.2.2",
-        "@vitest/spy": "4.1.5",
-        "@vitest/utils": "4.1.5",
+        "@vitest/spy": "4.1.8",
+        "@vitest/utils": "4.1.8",
         "chai": "^6.2.2",
         "tinyrainbow": "^3.1.0"
       },
@@ -3178,13 +3087,13 @@
       }
     },
     "node_modules/@vitest/mocker": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.5.tgz",
-      "integrity": "sha512-/x2EmFC4mT4NNzqvC3fmesuV97w5FC903KPmey4gsnJiMQ3Be1IlDKVaDaG8iqaLFHqJ2FVEkxZk5VmeLjIItw==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.8.tgz",
+      "integrity": "sha512-LEiN/xe4OSIbKe9HQIp5OC24agGD9J5CnmMgsLohVVoOPWL9a2sBoR6VBx43jQZb7Kr1l4RCuyCJzcAa0+dojw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/spy": "4.1.5",
+        "@vitest/spy": "4.1.8",
         "estree-walker": "^3.0.3",
         "magic-string": "^0.30.21"
       },
@@ -3205,9 +3114,9 @@
       }
     },
     "node_modules/@vitest/pretty-format": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.5.tgz",
-      "integrity": "sha512-7I3q6l5qr03dVfMX2wCo9FxwSJbPdwKjy2uu/YPpU3wfHvIL4QHwVRp57OfGrDFeUJ8/8QdfBKIV12FTtLn00g==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.8.tgz",
+      "integrity": "sha512-9GasEBxpZ1VYIpqHf/0+YGg121uSNwCKOJqIrTwWP/TB7DmFCiaBpNl3aPZzoLWfWkuqhbH8vJIVobZkvdo2cA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3218,13 +3127,13 @@
       }
     },
     "node_modules/@vitest/runner": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.5.tgz",
-      "integrity": "sha512-2D+o7Pr82IEO46YPpoA/YU0neeyr6FTerQb5Ro7BUnBuv6NQtT/kmVnczngiMEBhzgqz2UZYl5gArejsyERDSQ==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.8.tgz",
+      "integrity": "sha512-EmVxeBAfMJvycdjd6Hm+RbFBbA9fKvo0Kx37hNpBYoYeavH3RNsBXWDooR1mgD52dCrxIIuP7UotpfiwOikvcg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/utils": "4.1.5",
+        "@vitest/utils": "4.1.8",
         "pathe": "^2.0.3"
       },
       "funding": {
@@ -3232,14 +3141,14 @@
       }
     },
     "node_modules/@vitest/snapshot": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.5.tgz",
-      "integrity": "sha512-zypXEt4KH/XgKGPUz4eC2AvErYx0My5hfL8oDb1HzGFpEk1P62bxSohdyOmvz+d9UJwanI68MKwr2EquOaOgMQ==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.8.tgz",
+      "integrity": "sha512-acfZboRmAIf05DEKcBQy33VXojFJjtUdLyo7oOmV9kebb2xdU01UknNiPuPZoJZQyO7DF0gZdTGTpeAzET9QPQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.5",
-        "@vitest/utils": "4.1.5",
+        "@vitest/pretty-format": "4.1.8",
+        "@vitest/utils": "4.1.8",
         "magic-string": "^0.30.21",
         "pathe": "^2.0.3"
       },
@@ -3248,9 +3157,9 @@
       }
     },
     "node_modules/@vitest/spy": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.5.tgz",
-      "integrity": "sha512-2lNOsh6+R2Idnf1TCZqSwYlKN2E/iDlD8sgU59kYVl+OMDmvldO1VDk39smRfpUNwYpNRVn3w4YfuC7KfbBnkQ==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.8.tgz",
+      "integrity": "sha512-6EevtBp6OZOPF7bmz36HrGMeP3txgVSrgebWxHOafDXGkhIzfXK14f8KF6MuFfgXXUeHxmpD3BQxkV00/3s5mA==",
       "dev": true,
       "license": "MIT",
       "funding": {
@@ -3258,13 +3167,13 @@
       }
     },
     "node_modules/@vitest/utils": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.5.tgz",
-      "integrity": "sha512-76wdkrmfXfqGjueGgnb45ITPyUi1ycZ4IHgC2bhPDUfWHklY/q3MdLOAB+TF1e6xfl8NxNY0ZYaPCFNWSsw3Ug==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.8.tgz",
+      "integrity": "sha512-uOJamYALNhfJ6iolExyQM40yIQwDqYnkKtQ5VCiSe17E33H0aQ/u+1GlRuz4LZBk6Mm3sg90G9hEbmEt37C1Zg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.5",
+        "@vitest/pretty-format": "4.1.8",
         "convert-source-map": "^2.0.0",
         "tinyrainbow": "^3.1.0"
       },
@@ -3477,13 +3386,13 @@
       "license": "MIT"
     },
     "node_modules/axios": {
-      "version": "1.15.0",
-      "resolved": "https://registry.npmjs.org/axios/-/axios-1.15.0.tgz",
-      "integrity": "sha512-wWyJDlAatxk30ZJer+GeCWS209sA42X+N5jU2jy6oHTp7ufw8uzUTVFBX9+wTfAlhiJXGS0Bq7X6efruWjuK9Q==",
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/axios/-/axios-1.16.0.tgz",
+      "integrity": "sha512-6hp5CwvTPlN2A31g5dxnwAX0orzM7pmCRDLnZSX772mv8WDqICwFjowHuPs04Mc8deIld1+ejhtaMn5vp6b+1w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "follow-redirects": "^1.15.11",
+        "follow-redirects": "^1.16.0",
         "form-data": "^4.0.5",
         "proxy-from-env": "^2.1.0"
       }
@@ -3737,19 +3646,6 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/cacache/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/cacache/node_modules/ssri": {
       "version": "13.0.1",
       "resolved": "https://registry.npmjs.org/ssri/-/ssri-13.0.1.tgz",
@@ -4188,19 +4084,6 @@
         "node": ">=14"
       }
     },
-    "node_modules/conventional-changelog-writer/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/conventional-commits-filter": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/conventional-commits-filter/-/conventional-commits-filter-3.0.0.tgz",
@@ -4722,18 +4605,18 @@
       }
     },
     "node_modules/eslint": {
-      "version": "10.3.0",
-      "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.3.0.tgz",
-      "integrity": "sha512-XbEXaRva5cF0ZQB8w6MluHA0kZZfV2DuCMJ3ozyEOHLwDpZX2Lmm/7Pp0xdJmI0GL1W05VH5VwIFHEm1Vcw2gw==",
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.4.1.tgz",
+      "integrity": "sha512-AyIKhnOBuOAdueD7RB3xB+YeAWScb9jHsJBgH2Hcde8InP5JYhqrRR6iTMHyTEwgENK54Cp44e4v8BwNhsuHuw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.2",
         "@eslint/config-array": "^0.23.5",
-        "@eslint/config-helpers": "^0.5.5",
+        "@eslint/config-helpers": "^0.6.0",
         "@eslint/core": "^1.2.1",
-        "@eslint/plugin-kit": "^0.7.1",
+        "@eslint/plugin-kit": "^0.7.2",
         "@humanfs/node": "^0.16.6",
         "@humanwhocodes/module-importer": "^1.0.1",
         "@humanwhocodes/retry": "^0.4.2",
@@ -5080,9 +4963,9 @@
       "license": "ISC"
     },
     "node_modules/follow-redirects": {
-      "version": "1.15.11",
-      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz",
-      "integrity": "sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==",
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
+      "integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
       "dev": true,
       "funding": [
         {
@@ -5433,19 +5316,6 @@
         "node": ">=14"
       }
     },
-    "node_modules/git-semver-tags/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/git-up": {
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/git-up/-/git-up-7.0.0.tgz",
@@ -5817,19 +5687,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/init-package-json/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/inquirer": {
       "version": "12.9.6",
       "resolved": "https://registry.npmjs.org/inquirer/-/inquirer-12.9.6.tgz",
@@ -6632,19 +6489,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/libnpmpublish/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/lightningcss": {
       "version": "1.32.0",
       "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
@@ -7017,19 +6861,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/make-dir/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/make-fetch-happen": {
       "version": "15.0.2",
       "resolved": "https://registry.npmjs.org/make-fetch-happen/-/make-fetch-happen-15.0.2.tgz",
@@ -7594,19 +7425,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/node-gyp/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/node-gyp/node_modules/which": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/which/-/which-6.0.1.tgz",
@@ -7681,19 +7499,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/normalize-package-data/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/normalize-package-data/node_modules/yallist": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
@@ -7727,19 +7532,6 @@
         "node": "^18.17.0 || >=20.5.0"
       }
     },
-    "node_modules/npm-install-checks/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/npm-normalize-package-bin": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/npm-normalize-package-bin/-/npm-normalize-package-bin-4.0.0.tgz",
@@ -7766,19 +7558,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/npm-package-arg/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/npm-packlist": {
       "version": "10.0.3",
       "resolved": "https://registry.npmjs.org/npm-packlist/-/npm-packlist-10.0.3.tgz",
@@ -7842,19 +7621,6 @@
         "node": "^20.17.0 || >=22.9.0"
       }
     },
-    "node_modules/npm-pick-manifest/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/npm-registry-fetch": {
       "version": "19.1.0",
       "resolved": "https://registry.npmjs.org/npm-registry-fetch/-/npm-registry-fetch-19.1.0.tgz",
@@ -7889,9 +7655,9 @@
       }
     },
     "node_modules/nx": {
-      "version": "22.7.1",
-      "resolved": "https://registry.npmjs.org/nx/-/nx-22.7.1.tgz",
-      "integrity": "sha512-SadJUQY57MiwRIetm9rhZhdpFeOe1Csib2Vg9C423Pw/h0fZE14qUo6+OBby9vLh5QCkRfRZ0WaHkeO5q6yNtA==",
+      "version": "22.7.5",
+      "resolved": "https://registry.npmjs.org/nx/-/nx-22.7.5.tgz",
+      "integrity": "sha512-zoxsJabb33jl1QYnalDn0bicryrEBgSzdKp90d7VGGv/jDgzKrcLg/hw2ZxeYiOjWPIT/o8QNT9G9vTs4dv3AQ==",
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
@@ -7909,11 +7675,11 @@
         "ansi-styles": "4.3.0",
         "argparse": "2.0.1",
         "asynckit": "0.4.0",
-        "axios": "1.15.0",
+        "axios": "1.16.0",
         "balanced-match": "4.0.3",
         "base64-js": "1.5.1",
         "bl": "4.1.0",
-        "brace-expansion": "5.0.2",
+        "brace-expansion": "5.0.6",
         "buffer": "5.7.1",
         "call-bind-apply-helpers": "1.0.2",
         "chalk": "4.1.2",
@@ -7942,7 +7708,7 @@
         "escape-string-regexp": "1.0.5",
         "figures": "3.2.0",
         "flat": "5.0.2",
-        "follow-redirects": "1.15.11",
+        "follow-redirects": "1.16.0",
         "form-data": "4.0.5",
         "fs-constants": "1.0.0",
         "function-bind": "1.1.2",
@@ -7970,7 +7736,7 @@
         "mime-db": "1.52.0",
         "mime-types": "2.1.35",
         "mimic-fn": "2.1.0",
-        "minimatch": "10.2.4",
+        "minimatch": "10.2.5",
         "minimist": "1.2.8",
         "npm-run-path": "4.0.1",
         "once": "1.4.0",
@@ -7994,7 +7760,7 @@
         "strip-bom": "3.0.0",
         "supports-color": "7.2.0",
         "tar-stream": "2.2.0",
-        "tmp": "0.2.4",
+        "tmp": "0.2.6",
         "tree-kill": "1.2.2",
         "tsconfig-paths": "4.2.0",
         "tslib": "2.8.1",
@@ -8003,7 +7769,7 @@
         "wrap-ansi": "7.0.0",
         "wrappy": "1.0.2",
         "y18n": "5.0.8",
-        "yaml": "2.8.0",
+        "yaml": "2.9.0",
         "yargs": "17.7.2",
         "yargs-parser": "21.1.1"
       },
@@ -8012,16 +7778,16 @@
         "nx-cloud": "dist/bin/nx-cloud.js"
       },
       "optionalDependencies": {
-        "@nx/nx-darwin-arm64": "22.7.1",
-        "@nx/nx-darwin-x64": "22.7.1",
-        "@nx/nx-freebsd-x64": "22.7.1",
-        "@nx/nx-linux-arm-gnueabihf": "22.7.1",
-        "@nx/nx-linux-arm64-gnu": "22.7.1",
-        "@nx/nx-linux-arm64-musl": "22.7.1",
-        "@nx/nx-linux-x64-gnu": "22.7.1",
-        "@nx/nx-linux-x64-musl": "22.7.1",
-        "@nx/nx-win32-arm64-msvc": "22.7.1",
-        "@nx/nx-win32-x64-msvc": "22.7.1"
+        "@nx/nx-darwin-arm64": "22.7.5",
+        "@nx/nx-darwin-x64": "22.7.5",
+        "@nx/nx-freebsd-x64": "22.7.5",
+        "@nx/nx-linux-arm-gnueabihf": "22.7.5",
+        "@nx/nx-linux-arm64-gnu": "22.7.5",
+        "@nx/nx-linux-arm64-musl": "22.7.5",
+        "@nx/nx-linux-x64-gnu": "22.7.5",
+        "@nx/nx-linux-x64-musl": "22.7.5",
+        "@nx/nx-win32-arm64-msvc": "22.7.5",
+        "@nx/nx-win32-x64-msvc": "22.7.5"
       },
       "peerDependencies": {
         "@swc-node/register": "^1.11.1",
@@ -8063,19 +7829,6 @@
         "node": "20 || >=22"
       }
     },
-    "node_modules/nx/node_modules/brace-expansion": {
-      "version": "5.0.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.2.tgz",
-      "integrity": "sha512-Pdk8c9poy+YhOgVWw1JNN22/HcivgKWwpxKq04M/jTmHyCZn12WPJebZxdjSa5TmBqISrUSgNYU3eRORljfCCw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "balanced-match": "^4.0.2"
-      },
-      "engines": {
-        "node": "20 || >=22"
-      }
-    },
     "node_modules/nx/node_modules/escape-string-regexp": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz",
@@ -8109,22 +7862,6 @@
         "node": ">= 4"
       }
     },
-    "node_modules/nx/node_modules/minimatch": {
-      "version": "10.2.4",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
-      "integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "brace-expansion": "^5.0.2"
-      },
-      "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/nx/node_modules/semver": {
       "version": "7.7.4",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
@@ -8614,19 +8351,6 @@
         "node": "^18.17.0 || >=20.5.0"
       }
     },
-    "node_modules/pacote/node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/pacote/node_modules/which": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/which/-/which-5.0.0.tgz",
@@ -8835,9 +8559,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.14",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
-      "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
+      "version": "8.5.15",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
       "dev": true,
       "funding": [
         {
@@ -8855,7 +8579,7 @@
       ],
       "license": "MIT",
       "dependencies": {
-        "nanoid": "^3.3.11",
+        "nanoid": "^3.3.12",
         "picocolors": "^1.1.1",
         "source-map-js": "^1.2.1"
       },
@@ -9374,14 +9098,14 @@
       }
     },
     "node_modules/rolldown": {
-      "version": "1.0.0-rc.18",
-      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.18.tgz",
-      "integrity": "sha512-phmyKBpuBdRYDf4hgyynGAYn/rDDe+iZXKVJ7WX5b1zQzpLkP5oJRPGsfJuHdzPMlyyEO/4sPW6yfSx2gf7lVg==",
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.3.tgz",
+      "integrity": "sha512-i00lAJ2ks1BYr7rjNjKC7BcqAS7nVfiT3QX1SI5aY+AFHblCmaUf9OE9dbdzDvW6dJxbi2ZCZiy9v3CcwOiX3g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@oxc-project/types": "=0.128.0",
-        "@rolldown/pluginutils": "1.0.0-rc.18"
+        "@oxc-project/types": "=0.133.0",
+        "@rolldown/pluginutils": "^1.0.0"
       },
       "bin": {
         "rolldown": "bin/cli.mjs"
@@ -9390,31 +9114,31 @@
         "node": "^20.19.0 || >=22.12.0"
       },
       "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.0.0-rc.18",
-        "@rolldown/binding-darwin-arm64": "1.0.0-rc.18",
-        "@rolldown/binding-darwin-x64": "1.0.0-rc.18",
-        "@rolldown/binding-freebsd-x64": "1.0.0-rc.18",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.18",
-        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.18",
-        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.18",
-        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.18",
-        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.18",
-        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.18",
-        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.18",
-        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.18",
-        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.18",
-        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.18",
-        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.18"
+        "@rolldown/binding-android-arm64": "1.0.3",
+        "@rolldown/binding-darwin-arm64": "1.0.3",
+        "@rolldown/binding-darwin-x64": "1.0.3",
+        "@rolldown/binding-freebsd-x64": "1.0.3",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.3",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.3",
+        "@rolldown/binding-linux-arm64-musl": "1.0.3",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.3",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.3",
+        "@rolldown/binding-linux-x64-gnu": "1.0.3",
+        "@rolldown/binding-linux-x64-musl": "1.0.3",
+        "@rolldown/binding-openharmony-arm64": "1.0.3",
+        "@rolldown/binding-wasm32-wasi": "1.0.3",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.3",
+        "@rolldown/binding-win32-x64-msvc": "1.0.3"
       }
     },
     "node_modules/rollup": {
-      "version": "4.60.3",
-      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.3.tgz",
-      "integrity": "sha512-pAQK9HalE84QSm4Po3EmWIZPd3FnjkShVkiMlz1iligWYkWQ7wHYd1PF/T7QZ5TVSD6uSTon5gBVMSM4JfBV+A==",
+      "version": "4.61.0",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.61.0.tgz",
+      "integrity": "sha512-T9mWdbWfQtp0B5lv/HX+wrhYsmXRlcWnXXmJbXqKJhlRaoS6KMhq0gpyzW4UJfclcxrEdLnTgjT2NjruLONu0g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@types/estree": "1.0.8"
+        "@types/estree": "1.0.9"
       },
       "bin": {
         "rollup": "dist/bin/rollup"
@@ -9424,41 +9148,34 @@
         "npm": ">=8.0.0"
       },
       "optionalDependencies": {
-        "@rollup/rollup-android-arm-eabi": "4.60.3",
-        "@rollup/rollup-android-arm64": "4.60.3",
-        "@rollup/rollup-darwin-arm64": "4.60.3",
-        "@rollup/rollup-darwin-x64": "4.60.3",
-        "@rollup/rollup-freebsd-arm64": "4.60.3",
-        "@rollup/rollup-freebsd-x64": "4.60.3",
-        "@rollup/rollup-linux-arm-gnueabihf": "4.60.3",
-        "@rollup/rollup-linux-arm-musleabihf": "4.60.3",
-        "@rollup/rollup-linux-arm64-gnu": "4.60.3",
-        "@rollup/rollup-linux-arm64-musl": "4.60.3",
-        "@rollup/rollup-linux-loong64-gnu": "4.60.3",
-        "@rollup/rollup-linux-loong64-musl": "4.60.3",
-        "@rollup/rollup-linux-ppc64-gnu": "4.60.3",
-        "@rollup/rollup-linux-ppc64-musl": "4.60.3",
-        "@rollup/rollup-linux-riscv64-gnu": "4.60.3",
-        "@rollup/rollup-linux-riscv64-musl": "4.60.3",
-        "@rollup/rollup-linux-s390x-gnu": "4.60.3",
-        "@rollup/rollup-linux-x64-gnu": "4.60.3",
-        "@rollup/rollup-linux-x64-musl": "4.60.3",
-        "@rollup/rollup-openbsd-x64": "4.60.3",
-        "@rollup/rollup-openharmony-arm64": "4.60.3",
-        "@rollup/rollup-win32-arm64-msvc": "4.60.3",
-        "@rollup/rollup-win32-ia32-msvc": "4.60.3",
-        "@rollup/rollup-win32-x64-gnu": "4.60.3",
-        "@rollup/rollup-win32-x64-msvc": "4.60.3",
+        "@rollup/rollup-android-arm-eabi": "4.61.0",
+        "@rollup/rollup-android-arm64": "4.61.0",
+        "@rollup/rollup-darwin-arm64": "4.61.0",
+        "@rollup/rollup-darwin-x64": "4.61.0",
+        "@rollup/rollup-freebsd-arm64": "4.61.0",
+        "@rollup/rollup-freebsd-x64": "4.61.0",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.61.0",
+        "@rollup/rollup-linux-arm-musleabihf": "4.61.0",
+        "@rollup/rollup-linux-arm64-gnu": "4.61.0",
+        "@rollup/rollup-linux-arm64-musl": "4.61.0",
+        "@rollup/rollup-linux-loong64-gnu": "4.61.0",
+        "@rollup/rollup-linux-loong64-musl": "4.61.0",
+        "@rollup/rollup-linux-ppc64-gnu": "4.61.0",
+        "@rollup/rollup-linux-ppc64-musl": "4.61.0",
+        "@rollup/rollup-linux-riscv64-gnu": "4.61.0",
+        "@rollup/rollup-linux-riscv64-musl": "4.61.0",
+        "@rollup/rollup-linux-s390x-gnu": "4.61.0",
+        "@rollup/rollup-linux-x64-gnu": "4.61.0",
+        "@rollup/rollup-linux-x64-musl": "4.61.0",
+        "@rollup/rollup-openbsd-x64": "4.61.0",
+        "@rollup/rollup-openharmony-arm64": "4.61.0",
+        "@rollup/rollup-win32-arm64-msvc": "4.61.0",
+        "@rollup/rollup-win32-ia32-msvc": "4.61.0",
+        "@rollup/rollup-win32-x64-gnu": "4.61.0",
+        "@rollup/rollup-win32-x64-msvc": "4.61.0",
         "fsevents": "~2.3.2"
       }
     },
-    "node_modules/rollup/node_modules/@types/estree": {
-      "version": "1.0.8",
-      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
-      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/run-async": {
       "version": "4.0.6",
       "resolved": "https://registry.npmjs.org/run-async/-/run-async-4.0.6.tgz",
@@ -9507,6 +9224,19 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/semver": {
+      "version": "7.8.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.1.tgz",
+      "integrity": "sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/shebang-command": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
@@ -9920,9 +9650,9 @@
       "license": "MIT"
     },
     "node_modules/tinyexec": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.1.2.tgz",
-      "integrity": "sha512-dAqSqE/RabpBKI8+h26GfLq6Vb3JVXs30XYQjdMjaj/c2tS8IYYMbIzP599KtRj7c57/wYApb3QjgRgXmrCukA==",
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.2.4.tgz",
+      "integrity": "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -9957,9 +9687,9 @@
       }
     },
     "node_modules/tmp": {
-      "version": "0.2.4",
-      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.4.tgz",
-      "integrity": "sha512-UdiSoX6ypifLmrfQ/XfiawN6hkjSBpCjhKxxZcWlUUmoXLaCKQU0bx4HF/tdDK2uzRuchf1txGvrWBzYREssoQ==",
+      "version": "0.2.6",
+      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.6.tgz",
+      "integrity": "sha512-5sJPdPjfI5Kx+qbrDesxkglRBxW//g7hCsqspEjwkewGvBMGIKMOTKzLt1hFVJzyadba3lDUN20O9qhvbQUSTA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -10091,16 +9821,16 @@
       }
     },
     "node_modules/typescript-eslint": {
-      "version": "8.59.2",
-      "resolved": "https://registry.npmjs.org/typescript-eslint/-/typescript-eslint-8.59.2.tgz",
-      "integrity": "sha512-pJw051uomb3ZeCzGTpRb8RbEqB5Y4WWet8gl/GcTlU35BSx0PVdZ86/bqkQCyKKuraVQEK7r6kBHQXF+fBhkoQ==",
+      "version": "8.60.1",
+      "resolved": "https://registry.npmjs.org/typescript-eslint/-/typescript-eslint-8.60.1.tgz",
+      "integrity": "sha512-6m5hkkRAp8lKvhVpcprAIn5KkehQEh+47oHH2VGnExEh7dhNxXlg6GPAOIu6TxbVQxhebrJDvjl3020ooiWCMA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/eslint-plugin": "8.59.2",
-        "@typescript-eslint/parser": "8.59.2",
-        "@typescript-eslint/typescript-estree": "8.59.2",
-        "@typescript-eslint/utils": "8.59.2"
+        "@typescript-eslint/eslint-plugin": "8.60.1",
+        "@typescript-eslint/parser": "8.60.1",
+        "@typescript-eslint/typescript-estree": "8.60.1",
+        "@typescript-eslint/utils": "8.60.1"
       },
       "engines": {
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -10139,9 +9869,9 @@
       }
     },
     "node_modules/undici-types": {
-      "version": "7.19.2",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.19.2.tgz",
-      "integrity": "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==",
+      "version": "7.24.6",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+      "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
       "dev": true,
       "license": "MIT"
     },
@@ -10212,17 +9942,17 @@
       }
     },
     "node_modules/vite": {
-      "version": "8.0.11",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.11.tgz",
-      "integrity": "sha512-Jz1mxtUBR5xTT65VOdJZUUeoyLtqljmFkiUXhPTLZka3RDc9vpi/xXkyrnsdRcm2lIi3l3GPMnAidTsEGIj3Ow==",
+      "version": "8.0.16",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.16.tgz",
+      "integrity": "sha512-h9bXPmJichP5fLmVQo3PyaGSDE2n3aPuomeAlVRm0JLmt4rY6zmPKd59HYI4LNW8oTK7tlTsuC7l/m7awx9Jcw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "lightningcss": "^1.32.0",
         "picomatch": "^4.0.4",
-        "postcss": "^8.5.14",
-        "rolldown": "1.0.0-rc.18",
-        "tinyglobby": "^0.2.16"
+        "postcss": "^8.5.15",
+        "rolldown": "1.0.3",
+        "tinyglobby": "^0.2.17"
       },
       "bin": {
         "vite": "bin/vite.js"
@@ -10290,9 +10020,9 @@
       }
     },
     "node_modules/vite/node_modules/tinyglobby": {
-      "version": "0.2.16",
-      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
-      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "version": "0.2.17",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -10307,19 +10037,19 @@
       }
     },
     "node_modules/vitest": {
-      "version": "4.1.5",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.5.tgz",
-      "integrity": "sha512-9Xx1v3/ih3m9hN+SbfkUyy0JAs72ap3r7joc87XL6jwF0jGg6mFBvQ1SrwaX+h8BlkX6Hz9shdd1uo6AF+ZGpg==",
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.8.tgz",
+      "integrity": "sha512-flY6ScbCIt9HThs+C5HS7jvGOB560DJtk/Z15IQROTA6zEy49Nh8T/dofWTQL+n3vswqn87sbJNiuqw1SDp5Ig==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/expect": "4.1.5",
-        "@vitest/mocker": "4.1.5",
-        "@vitest/pretty-format": "4.1.5",
-        "@vitest/runner": "4.1.5",
-        "@vitest/snapshot": "4.1.5",
-        "@vitest/spy": "4.1.5",
-        "@vitest/utils": "4.1.5",
+        "@vitest/expect": "4.1.8",
+        "@vitest/mocker": "4.1.8",
+        "@vitest/pretty-format": "4.1.8",
+        "@vitest/runner": "4.1.8",
+        "@vitest/snapshot": "4.1.8",
+        "@vitest/spy": "4.1.8",
+        "@vitest/utils": "4.1.8",
         "es-module-lexer": "^2.0.0",
         "expect-type": "^1.3.0",
         "magic-string": "^0.30.21",
@@ -10347,12 +10077,12 @@
         "@edge-runtime/vm": "*",
         "@opentelemetry/api": "^1.9.0",
         "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
-        "@vitest/browser-playwright": "4.1.5",
-        "@vitest/browser-preview": "4.1.5",
-        "@vitest/browser-webdriverio": "4.1.5",
-        "@vitest/coverage-istanbul": "4.1.5",
-        "@vitest/coverage-v8": "4.1.5",
-        "@vitest/ui": "4.1.5",
+        "@vitest/browser-playwright": "4.1.8",
+        "@vitest/browser-preview": "4.1.8",
+        "@vitest/browser-webdriverio": "4.1.8",
+        "@vitest/coverage-istanbul": "4.1.8",
+        "@vitest/coverage-v8": "4.1.8",
+        "@vitest/ui": "4.1.8",
         "happy-dom": "*",
         "jsdom": "*",
         "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
@@ -10397,9 +10127,9 @@
       }
     },
     "node_modules/vitest/node_modules/tinyglobby": {
-      "version": "0.2.16",
-      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
-      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "version": "0.2.17",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -10563,9 +10293,9 @@
       }
     },
     "node_modules/yaml": {
-      "version": "2.8.0",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.0.tgz",
-      "integrity": "sha512-4lLa/EcQCB0cJkyts+FpIRx5G/llPxfP6VQU5KByHEhLxY3IJCH0f0Hy1MHI8sClTvsIb8qwRJ6R/ZdlDJ/leQ==",
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
       "dev": true,
       "license": "ISC",
       "bin": {
@@ -10573,6 +10303,9 @@
       },
       "engines": {
         "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
       }
     },
     "node_modules/yargs": {
diff --git a/package.json b/package.json
index 767d313..201c783 100644
--- a/package.json
+++ b/package.json
@@ -21,13 +21,13 @@
   ],
   "devDependencies": {
     "@tsconfig/recommended": "^1.0.13",
-    "@types/node": "^25.6.2",
-    "@vitest/coverage-v8": "4.1.5",
-    "eslint": "^10.2.1",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^10.4.1",
     "lerna": "^9.0.7",
-    "rollup": "^4.60.2",
+    "rollup": "^4.61.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.1",
-    "vitest": "4.1.5"
+    "typescript-eslint": "^8.60.1",
+    "vitest": "^4.1.8"
   }
 }

From 6f7e6c7848e3921e28ef84a99b62ae47704241c8 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 3 Jun 2026 06:20:43 +0300
Subject: [PATCH 117/118] release: v7.0.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stable v7 release. Lockstep bump of all 5 packages from 7.0.0-alpha.8 to
7.0.0. CHANGELOG entry summarizes the cumulative v7 trajectory across
alphas 1-8 (debugger reshape, CallFrame, callable-subtree mermaid emit,
state tags, TapeSnapshot to engine, visuals companion package).

Closes the v7 milestone — composition-representation overhaul.
---
 README.md                                     |  2 +-
 lerna.json                                    |  2 +-
 package-lock.json                             | 18 ++---
 packages/builder/CHANGELOG.md                 |  8 ++
 packages/builder/package.json                 |  4 +-
 .../library-binary-numbers-bare/CHANGELOG.md  |  8 ++
 .../library-binary-numbers-bare/package.json  |  4 +-
 packages/library-binary-numbers/CHANGELOG.md  |  8 ++
 packages/library-binary-numbers/package.json  |  4 +-
 packages/machine/CHANGELOG.md                 | 81 +++++++++++++++++++
 packages/machine/README.md                    |  2 +-
 packages/machine/package.json                 |  2 +-
 packages/visuals/CHANGELOG.md                 | 15 ++++
 packages/visuals/README.md                    |  8 +-
 packages/visuals/package.json                 |  4 +-
 15 files changed, 142 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index eda2e6e..506cc53 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ This repository contains the following packages:
 * [@turing-machine-js/library-binary-numbers](https://github.com/mellonis/turing-machine-js/tree/master/packages/library-binary-numbers) — binary arithmetic on a 5-symbol alphabet (` ^$01`) supporting multiple numbers per tape, with `plusOne`, `minusOne`, `minusOneFast`, `invertNumber`, `normalizeNumber`, and inter-number navigation.
 * [@turing-machine-js/library-binary-numbers-bare](https://github.com/mellonis/turing-machine-js/tree/master/packages/library-binary-numbers-bare) — the same arithmetic on a 3-symbol alphabet (` 01`), single-number-per-tape. Side-by-side with the marker-based library to make the alphabet-size vs state-graph-size trade-off visible.
 * [@turing-machine-js/builder](https://github.com/mellonis/turing-machine-js/tree/master/packages/builder) — declarative state-table construction. Not actively developed; the same pattern is shown inline in `@turing-machine-js/machine`'s README.
-* [@turing-machine-js/visuals](https://github.com/mellonis/turing-machine-js/tree/v7/packages/visuals) (v7+, prerelease) — pure highlight + graph-indexing logic for the engine `Graph`: `applyHighlight` / `applyIndicator` against a renderer-agnostic `HighlightOps` interface, `bareIdOf` / `highlightExpand` for wrapper/bare canonicalization, `formatStepNotation` / `tokenizeStep` / `formatTape` for engine-edge-label rendering (byte-identical to `toMermaid`), `recordSnippet` for prerecorded-playback artifacts. No DOM, no Svelte, no Mermaid — consumers bring their own renderer.
+* [@turing-machine-js/visuals](https://github.com/mellonis/turing-machine-js/tree/master/packages/visuals) (v7+) — pure highlight + graph-indexing logic for the engine `Graph`: `applyHighlight` / `applyIndicator` against a renderer-agnostic `HighlightOps` interface, `bareIdOf` / `highlightExpand` for wrapper/bare canonicalization, `formatStepNotation` / `tokenizeStep` / `formatTape` for engine-edge-label rendering (byte-identical to `toMermaid`), `recordSnippet` for prerecorded-playback artifacts. No DOM, no Svelte, no Mermaid — consumers bring their own renderer.
 
 # An example
 
diff --git a/lerna.json b/lerna.json
index a123db3..e9b371b 100644
--- a/lerna.json
+++ b/lerna.json
@@ -3,6 +3,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "7.0.0-alpha.8",
+  "version": "7.0.0",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index db25187..21e0729 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10393,40 +10393,40 @@
     },
     "packages/builder": {
       "name": "@turing-machine-js/builder",
-      "version": "7.0.0-alpha.8",
+      "version": "7.0.0",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.8"
+        "@turing-machine-js/machine": "^7.0.0"
       }
     },
     "packages/library-binary-numbers": {
       "name": "@turing-machine-js/library-binary-numbers",
-      "version": "7.0.0-alpha.8",
+      "version": "7.0.0",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.8"
+        "@turing-machine-js/machine": "^7.0.0"
       }
     },
     "packages/library-binary-numbers-bare": {
       "name": "@turing-machine-js/library-binary-numbers-bare",
-      "version": "7.0.0-alpha.8",
+      "version": "7.0.0",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.8"
+        "@turing-machine-js/machine": "^7.0.0"
       }
     },
     "packages/machine": {
       "name": "@turing-machine-js/machine",
-      "version": "7.0.0-alpha.8",
+      "version": "7.0.0",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
@@ -10434,13 +10434,13 @@
     },
     "packages/visuals": {
       "name": "@turing-machine-js/visuals",
-      "version": "7.0.0-alpha.8",
+      "version": "7.0.0",
       "license": "GPL-3.0-or-later",
       "engines": {
         "npm": ">=7.0.0"
       },
       "peerDependencies": {
-        "@turing-machine-js/machine": "^7.0.0-alpha.8"
+        "@turing-machine-js/machine": "^7.0.0"
       }
     }
   }
diff --git a/packages/builder/CHANGELOG.md b/packages/builder/CHANGELOG.md
index 5cd086a..5055de6 100644
--- a/packages/builder/CHANGELOG.md
+++ b/packages/builder/CHANGELOG.md
@@ -4,6 +4,14 @@ 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] - 2026-06-03
+
+Stable v7. Lockstep release with `@turing-machine-js/machine` 7.0.0. See the machine package CHANGELOG for the cumulative v7 trajectory.
+
+### Changed
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.8` → `^7.0.0`.
+
 ## [7.0.0-alpha.8] - 2026-06-02
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.8 — lifts `TapeSnapshot` + `tapeViewport` from `@turing-machine-js/visuals` into the engine ([#227](https://github.com/mellonis/turing-machine-js/issues/227)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.7` → `^7.0.0-alpha.8`.
diff --git a/packages/builder/package.json b/packages/builder/package.json
index 1a8bd77..f92bf6c 100644
--- a/packages/builder/package.json
+++ b/packages/builder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "7.0.0-alpha.8",
+  "version": "7.0.0",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.8"
+    "@turing-machine-js/machine": "^7.0.0"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/builder",
diff --git a/packages/library-binary-numbers-bare/CHANGELOG.md b/packages/library-binary-numbers-bare/CHANGELOG.md
index 9daa243..7cb2a5b 100644
--- a/packages/library-binary-numbers-bare/CHANGELOG.md
+++ b/packages/library-binary-numbers-bare/CHANGELOG.md
@@ -4,6 +4,14 @@ 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] - 2026-06-03
+
+Stable v7. Lockstep release with `@turing-machine-js/machine` 7.0.0. See the machine package CHANGELOG for the cumulative v7 trajectory.
+
+### Changed
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.8` → `^7.0.0`.
+
 ## [7.0.0-alpha.8] - 2026-06-02
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.8 — lifts `TapeSnapshot` + `tapeViewport` from `@turing-machine-js/visuals` into the engine ([#227](https://github.com/mellonis/turing-machine-js/issues/227)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.7` → `^7.0.0-alpha.8`.
diff --git a/packages/library-binary-numbers-bare/package.json b/packages/library-binary-numbers-bare/package.json
index f579b9c..6a70b47 100644
--- a/packages/library-binary-numbers-bare/package.json
+++ b/packages/library-binary-numbers-bare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers-bare",
-  "version": "7.0.0-alpha.8",
+  "version": "7.0.0",
   "description": "Single-number binary arithmetic on a 3-symbol alphabet (blank, 0, 1) — same operations as @turing-machine-js/library-binary-numbers but without ^/$ markers. Side-by-side with the marker-based library for learning the trade-off.",
   "engines": {
     "npm": ">=7.0.0"
@@ -28,7 +28,7 @@
     "teaching"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.8"
+    "@turing-machine-js/machine": "^7.0.0"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers-bare",
diff --git a/packages/library-binary-numbers/CHANGELOG.md b/packages/library-binary-numbers/CHANGELOG.md
index 926499d..98c8c74 100644
--- a/packages/library-binary-numbers/CHANGELOG.md
+++ b/packages/library-binary-numbers/CHANGELOG.md
@@ -4,6 +4,14 @@ 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] - 2026-06-03
+
+Stable v7. Lockstep release with `@turing-machine-js/machine` 7.0.0. See the machine package CHANGELOG for the cumulative v7 trajectory.
+
+### Changed
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.8` → `^7.0.0`.
+
 ## [7.0.0-alpha.8] - 2026-06-02
 
 Released in lockstep with `@turing-machine-js/machine` 7.0.0-alpha.8 — lifts `TapeSnapshot` + `tapeViewport` from `@turing-machine-js/visuals` into the engine ([#227](https://github.com/mellonis/turing-machine-js/issues/227)). No source or behavior changes in this package. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.7` → `^7.0.0-alpha.8`.
diff --git a/packages/library-binary-numbers/package.json b/packages/library-binary-numbers/package.json
index a3960c3..bcb8fb7 100644
--- a/packages/library-binary-numbers/package.json
+++ b/packages/library-binary-numbers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "7.0.0-alpha.8",
+  "version": "7.0.0",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -27,7 +27,7 @@
     "numbers"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.8"
+    "@turing-machine-js/machine": "^7.0.0"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/library-binary-numbers",
diff --git a/packages/machine/CHANGELOG.md b/packages/machine/CHANGELOG.md
index 42fb271..1e951ae 100644
--- a/packages/machine/CHANGELOG.md
+++ b/packages/machine/CHANGELOG.md
@@ -4,6 +4,87 @@ 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] - 2026-06-03
+
+Stable v7. The composition-representation overhaul. See alpha.1 through alpha.8 entries below for the detailed step-by-step trajectory; this entry summarizes the cumulative API changes from v6.4.0.
+
+### Added
+
+- **`DebugSession`** — `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. Concurrent sessions on one machine are rejected (the underlying `TapeBlock` lock is single-active-run). Depth-based step controls mirror Chrome DevTools: `stepIn` = next iter at any depth; `stepOver` = next iter at `depth ≤ click-time depth`; `stepOut` = next iter at `depth < click-time depth` (throws at depth 0).
+- **`CallFrame extends State`** — `withOverriddenHaltState`'s wrapper is now a first-class `State` subclass instead of an instance aliasing the bare's private `#symbolToDataMap` / `#debugRef`. Transition lookups and `debug` access delegate to the bare. `instanceof State` is preserved; `instanceof CallFrame` is the wrapper discriminator. Exported additively from the package root.
+- **`TapeSnapshot` type + `tapeViewport` helper** — the per-tape wire-data shape `{ symbols: string[]; position: number }` and a pure helper providing a fixed-width centered window over it. Live next to the `Tape` class; `@turing-machine-js/visuals` re-exports both for consumer-import stability.
+- **First-class State tags** — `state.tag(...) / .untag(...) / .tags` for attaching string metadata. Out-of-band — no effect on transition lookup, `equivalentOn`, or runtime semantics. Live on the State instance, so memoized wrappers don't leak tags across sharers of a bare. `GraphNode.tags: string[]` survives `toGraph` / `fromGraph` round-trip; `toMermaid` emits tags inline (`<br>`) AND as `classDef` + `class` color-group lines.
+- **`withOverriddenHaltState` memoization** — calls with the same `(bare, override)` pair return the literally-same `State` instance. Backed by a `WeakMap` keyed by the bare with `WeakRef`-valued entries.
+- **`MachineState.matchedTransition`** — every yielded `MachineState` carries `{ id: string, matchKinds: ('wildcard' | 'literal')[] }`. `id` is `${stateId}.${transitionIx}` and resolves directly in `toGraph` output. `matchKinds` is per-tape; `'wildcard'` iff the winning alternative held `ifOtherSymbol` at that position. Eliminates `(source, nextState)` resolution ambiguity for exact-edge highlighting and per-transition coverage maps.
+- **`State.getMatchedTransition(symbol)`** — returns `{ nextState, matchedSymbol, ix }`, exposing the index used by `matchedTransition.id`.
+- **`State.collectStates(initialState, tapeBlock)`** — returns `Map<number, { state: State; transitionSymbols: symbol[] }>` keyed by engine `GraphNode.id`. The K-th `transitionSymbols` slot is positionally aligned with the GraphTransition whose id is `${stateId}.${K}`. `StateMap` and `StateMapEntry` types exported.
+- **`TapeBlock.patternKinds(symbol, currentSymbols?)`** — per-tape `'wildcard' | 'literal'` for the matched alternative's selector.
+- **`HaltState` typed alias** — narrows `haltState.debug` to `boolean` at the canonical access path.
+- **`@turing-machine-js/visuals` companion package** — pure highlight + graph-indexing logic for the engine `Graph` (peer dep on `machine`, no runtime deps). Includes `applyHighlight` / `applyIndicator` / `indexGraph` / `bareIdOf` / `highlightExpand` / `equivalentIds` / `recordingOps`, the engine-edge-label formatter primitives (`formatStepNotation` / `tokenizeStep` / `formatTape`), the snippet-recording surface (`recordSnippet` + `SnippetPlayer`), and a 16-rule contract doc.
+
+### Changed
+
+- **`State.prototype.withOverrodeHaltState` renamed to `withOverriddenHaltState`** — grammar fix. Hard cutover, no deprecated alias. Renames in lockstep: public method, `state.overriddenHaltState` getter, the `#overriddenHaltState` private field, and the serialized `Graph` field `node.overriddenHaltStateId`.
+- **Wrapped-state composite name format flipped from `bare>override` to `bare(override)`** — paren-nested keeps structurally-distinct wrap-trees distinct (`A.with(B.with(A))` is `A(B(A))`; `A.with(B).with(A)` is `A(B)(A)`). As a consequence, **user-provided state names must not contain `(` or `)`** (the constructor throws). `>` is no longer reserved.
+- **`run()` is synchronous and callback-free** — signature is `run({ initialState, stepsLimit? }): void` (was `async … : Promise<void>` with `onPause` / `onStep` / `onIter` callbacks). All callback machinery has moved to `DebugSession`. **Breaking** for callers awaiting `run()` or passing callbacks.
+- **`runStepByStep` is the minimal pure-iteration primitive** — advances the machine and yields a plain `MachineState`. Evaluates no `state.debug` filters and stamps no pause field. Breakpoint detection moved to `DebugSession`. **Breaking** for consumers that read a pause / breakpoint field off raw yields.
+- **`haltState.debug` is a `boolean`** — was `DebugConfig` with per-side `{ before?, after? }`. `haltState.debug = true` enables (pauses on every halt entry); `false` / `null` disables. Object-shaped writes throw. The pause fires on the AFTER side of the iter whose transition leads to halt — `m.state` is the triggering state. **Breaking** — pre-v7 consumers using `haltState.debug = { before: true }` / `{ after: true }` must switch to `haltState.debug = true`. ⚠️ Chained-form `haltState.debug.before = true` silently no-ops in non-strict mode (primitive-property assignment). Use the whole-object form.
+- **`toMermaid` callable-subtree emit** — wrapper and bare are separate graph nodes. Wrapper sits OUTSIDE any subgraph as `[[composite-name]]` (call site). Bare lives INSIDE its callable subtree subgraph as a regular `[name]` node. Subgraph label is `"callable subtree of NAME"` (single bare) or `"callable scope: A ∪ B"` (multi-bare union frame computed via union-find on bare-reachability). Halt marker is per-frame. Arrow vocabulary: solid `-->` for regular transitions AND wrapper's post-return `--> override`; bold `==> "call"` is RESERVED for wrapper-to-bare (`&` ribbon collapses multiple wrappers sharing a bare); dotted `-.->` is reserved for frame-level dispatch (`w_N -. "return" .-> wrapper`, `w_N -. "halt" .-> s0`, `idle -. enter .-> sN`). `GraphNode` field changes: `isWrapper: boolean`, `bareStateId: number | null`, `frameId: number | null`; `overriddenHaltStateId` lives on wrapper nodes only. Bytewise round-trip stability holds for all wrapped states, including shared-bare cases.
+- **`toMermaid` framed-wrapper emit fix** — `toGraph`'s reach-set now pushes the wrapper itself AND tunnels through `overriddenHaltStateId`, so framed-wrapper-continuations join the caller's frame instead of emitting at the top level.
+- **`toMermaid` user-content escape** — alphabet symbols, state names, tag names, and frame bare names are HTML-entity-escaped at the leaf (`&`, `"`, `<`, `>` to named entities; statement terminators, C0 controls, DEL, bidi controls, lone surrogates to numeric entities). `fromMermaid` mirrors with a single-pass entity decoder. Fixes parse errors on alphabets containing literal `"`, `<`, `>`, etc.
+- **Edge-label vocabulary rewritten** — `[reads] → [writes]/[moves]`, each role wrapped in `[…]` (tape-block indicator; always present, even single-tape). Read cells: `'X'` literal-quoted, `*` (ifOtherSymbol catch-all), `B` (tape's blank). Write cells: literal-quoted, `K` (keep), `E` (erase). Move cells: `L` / `R` / `S`. Alternation per-pattern bracket (`['^']|['1']`, never compact in-bracket form).
+- **`GraphTransition.id` separator: `-` → `.`** — was `${stateId}-${patternIx}`, now `${stateId}.${patternIx}`. Aligns with `matchedTransition.id` and makes the id splittable without colliding with user-defined state names containing `-`.
+- **Nested `.wohs()` chain collapse** — `A.wohs(t1).wohs(t2)` is equivalent to `A.wohs(t2)` (the inner override is dead at runtime). Composite name now reflects runtime behavior: `A(t2)`, not the misleading `A(t1)(t2)`.
+- **`runStepByStep` halt-stack is run-scoped, not machine-scoped** — fixes a "ghost iteration" / memory leak on consecutive `runStepByStep` calls when the previous generator wasn't drained to halt.
+- **Graph serialization extracted to `utilities/stateGraph.ts`** — `State.toGraph` / `State.fromGraph` / `State.collectStates` live in a sibling module. Public surface preserved via thin static delegates.
+- **`Tape.viewport` getter shares its centering loop with `tapeViewport`** via an internal `tapeViewportFromAccess` core — the centering math lives once.
+- **`summarize().stateCount` filters `isHaltMarker` nodes** — halt markers are visualization sentinels (all map back to singleton `haltState` at runtime).
+
+### Removed
+
+- **`MachineState.debugBreak`** — the per-yield `{ before?, after?, cause }` descriptor from the v4–v6 debugger. Replaced by the one-sided `m.pause: { side: 'before' | 'after', cause: 'breakpoint' | 'step' | 'manual' }` carried ONLY on a `DebugSession` `pause` event (`PausedMachineState`); raw `runStepByStep` yields carry no pause field.
+- **`withOverrodeHaltState` (the misspelled alias)** — no deprecated alias retained.
+- **The `-. onHalt .->` Mermaid arrow** — wrapper-to-override is now an ordinary solid `--> override` arrow; dotted `-.->` is reserved for frame-level dispatch.
+- **`GraphNode.isWrapped`** — replaced by `isWrapper: boolean`, `bareStateId: number | null`, `frameId: number | null`.
+- **`run()` callbacks (`onPause`, `onStep`, `onIter`)** — moved to `DebugSession` events.
+- **Hand-drawn pedagogical Mermaid blocks in READMEs** — the v7 `toMermaid` output is the primary illustration; no more vocabulary mismatch between hand-drawn and engine-rendered diagrams.
+
+### Migration
+
+Mechanical identifier rename:
+
+```sh
+git grep -l 'OverrodeHaltState\|overrodeHaltState' | xargs sed -i '' \
+  -e 's/OverrodeHaltState/OverriddenHaltState/g' \
+  -e 's/overrodeHaltState/overriddenHaltState/g'
+```
+
+`await`-on-`run()` and callback users move to `DebugSession`:
+
+```ts
+// before
+await machine.run({ initialState, onPause: (m) => { ... } });
+
+// after
+const session = new DebugSession(machine, { initialState });
+session.on('pause', (m) => { /* m.pause.side, m.pause.cause */ });
+await session.continue();
+```
+
+`m.debugBreak.before` / `.after` / `.cause` consumers move to `m.pause.side` / `m.pause.cause` on `DebugSession` `pause` events.
+
+`haltState.debug = { after: true }` writes throw — use `haltState.debug = true` (always after-side).
+
+Code that pattern-matches `state.name` for wrapper composites switches from `>`-split to paren-parse: `'A>B'` is now `'A(B)'`.
+
+If you render `toMermaid` output programmatically, the edge-label vocabulary changed completely — see the engine README's §Diagram conventions.
+
+If you store serialized `Graph` JSON: `node.overrodeHaltStateId` → `node.overriddenHaltStateId`, `GraphNode.isWrapped` → `isWrapper` + `bareStateId` + `frameId`, `GraphTransition.id` separator `-` → `.`.
+
+### Compatibility
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.8` → `^7.0.0` on `@turing-machine-js/builder`, `@turing-machine-js/library-binary-numbers`, `@turing-machine-js/library-binary-numbers-bare`, `@turing-machine-js/visuals`.
+
 ## [7.0.0-alpha.8] - 2026-06-02
 
 Eighth v7 pre-release. Lifts `TapeSnapshot` (the per-tape wire-data shape `{symbols, position}`) and `tapeViewport` (fixed-width centered window over a `TapeSnapshot`) from `@turing-machine-js/visuals` into the engine, next to the `Tape` class. Resolves [#227](https://github.com/mellonis/turing-machine-js/issues/227). Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.
diff --git a/packages/machine/README.md b/packages/machine/README.md
index 68585a2..dd8ff76 100644
--- a/packages/machine/README.md
+++ b/packages/machine/README.md
@@ -852,7 +852,7 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **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.8, 2026-06-02)* — Composition-representation overhaul + first-class state tags + id-keyed `State.collectStates` lookup + `DebugSession` step controls + `CallFrame` + `tapeViewport`/`TapeSnapshot`. **Pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.8`). **v7 milestone is feature-complete with #102**; the stable v7.0.0 cut is the only remaining step. Highlights across alphas:
+- **v7** *(2026-06-03)* — Composition-representation overhaul + first-class state tags + id-keyed `State.collectStates` lookup + `DebugSession` step controls + `CallFrame` + `tapeViewport`/`TapeSnapshot`. Stable release on the `latest` dist-tag: `npm install @turing-machine-js/machine`. Highlights across the v7 alpha cycle:
 
   **alpha.8** — **`TapeSnapshot` type + `tapeViewport` helper** ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) moved into the engine from `@turing-machine-js/visuals`, next to the live `Tape` class (visuals re-exports for consumer-import stability). `Tape.viewport` getter refactored to share its centering loop with `tapeViewport` via an internal core — the centering math now lives once; the two public surfaces supply their own data-shape-appropriate `cellAt` lambdas. See [§Tape](#tape).
 
diff --git a/packages/machine/package.json b/packages/machine/package.json
index d22c306..aa823f4 100644
--- a/packages/machine/package.json
+++ b/packages/machine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.8",
+  "version": "7.0.0",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
diff --git a/packages/visuals/CHANGELOG.md b/packages/visuals/CHANGELOG.md
index 8eb8fd2..302b2ce 100644
--- a/packages/visuals/CHANGELOG.md
+++ b/packages/visuals/CHANGELOG.md
@@ -4,6 +4,21 @@ All notable changes to this package 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] - 2026-06-03
+
+Stable v7. Lockstep release with `@turing-machine-js/machine` 7.0.0. First stable cut of the visuals companion package. See the machine package CHANGELOG for the cumulative v7 trajectory.
+
+### Added (cumulative across the v7 alpha cycle)
+
+- **Highlight + graph-indexing surface** (alpha.6): `applyHighlight`, `applyIndicator`, `indexGraph`, `bareIdOf`, `highlightExpand`, `equivalentIds`, `recordingOps`, plus types `HighlightOps` / `IndicatorOps` / `RecordedOp` / `NodeKey` / `HighlightClass` / `GraphIndexes` / `GraphHighlight`. 16-rule contract doc at `docs/graph-highlight-and-breakpoints.md`.
+- **Snippet recording + playback** (alpha.6, alpha.7.1): `recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }) => Snippet` (engine-agnostic — works with `@turing-machine-js/machine` or `@post-machine-js/machine`), `SnippetPlayer` class with `currentFrame` / `frameIndex` / `done` getters + `forward()` / `back()` / `reset()` / `goTo(idx)`. `Frame.commands` carries per-tape `{ movement, read, write }` so consumers step bi-directionally without recomputing deltas. Types: `Snippet`, `Frame`, `StepCommand`, `RecordSnippetOptions`.
+- **Engine-edge-label formatter primitives** (alpha.6.1): `formatStepNotation(reads, commands, blanks, matchKinds?)` (byte-identical to `toMermaid` edge labels, with `'X'` / `B` / `*='X'` / `K='X'` / `K=B` / `E` shortcuts), `tokenizeStep(...) → StepTokens` (renderer-agnostic structured tokens — discriminated-union `ReadToken` / `WriteToken` per cell, moves as letters; consumers wanting non-string rendering walk tokens themselves), `formatTape(snapshot)` (head bracketed in place, `a[b]c`). Earlier `formatCommand` / `formatStep` continue to work.
+- **`TapeSnapshot` + `tapeViewport` re-exports** (alpha.8) — moved into `@turing-machine-js/machine` and re-exported from visuals for consumer-import stability. `import { TapeSnapshot, tapeViewport } from '@turing-machine-js/visuals'` keeps working.
+
+### Changed
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.8` → `^7.0.0`.
+
 ## [7.0.0-alpha.8] - 2026-06-02
 
 `TapeSnapshot` type and `tapeViewport` helper moved to `@turing-machine-js/machine` ([#227](https://github.com/mellonis/turing-machine-js/issues/227)) — they live next to the live `Tape` class now. **Consumers importing them from `@turing-machine-js/visuals` are unaffected**: visuals re-exports both from the engine, so existing `import { TapeSnapshot, tapeViewport } from '@turing-machine-js/visuals'` continues to work.
diff --git a/packages/visuals/README.md b/packages/visuals/README.md
index b20e776..6b50ec9 100644
--- a/packages/visuals/README.md
+++ b/packages/visuals/README.md
@@ -14,13 +14,7 @@ Pure highlight + graph-indexing logic for [`@turing-machine-js/machine`](../mach
 npm install @turing-machine-js/visuals @turing-machine-js/machine
 ```
 
-Both prereleases on npm `next`:
-
-```sh
-npm install @turing-machine-js/visuals@next @turing-machine-js/machine@next
-```
-
-Peer-deps on `@turing-machine-js/machine@^7.0.0-alpha.6` — visuals follows engine v7 alphas with occasional visuals-only patches (`7.0.0-alpha.6.1` added the formatter primitives + token surface on top of the lockstep alpha.6 engine release).
+Peer-deps on `@turing-machine-js/machine@^7.0.0`. First published as v7-only — released alongside the engine v7.0.0 stable cut. Visuals follows the engine in lockstep with occasional visuals-only patches (e.g. `7.0.0-alpha.6.1` and `7.0.0-alpha.7.1` during the v7 prerelease cycle).
 
 ## Public API
 
diff --git a/packages/visuals/package.json b/packages/visuals/package.json
index 728a4c0..baeef84 100644
--- a/packages/visuals/package.json
+++ b/packages/visuals/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/visuals",
-  "version": "7.0.0-alpha.8",
+  "version": "7.0.0",
   "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "visualization"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.8"
+    "@turing-machine-js/machine": "^7.0.0"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/visuals",

From a4c7b8f1ad725a08ebfa214847d51f0d6fb79b21 Mon Sep 17 00:00:00 2001
From: Ruslan Gilmullin <mellonis@yandex.ru>
Date: Wed, 3 Jun 2026 06:39:42 +0300
Subject: [PATCH 118/118] chore(visuals): add LICENSE for stable v7.0.0

The visuals package was created in 7.0.0-alpha.6 without a LICENSE file
and shipped without one through alpha.8. Stable v7.0.0 fixes this by
copying the MIT LICENSE that the other 4 sibling packages already ship
(byte-identical to packages/machine/LICENSE).

Tarball before: 39.5 kB packed / 130.9 kB unpacked, 16 files.
Tarball after: 51.4 kB packed / 166.0 kB unpacked, 17 files (+LICENSE).
---
 packages/visuals/LICENSE | 674 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 674 insertions(+)
 create mode 100644 packages/visuals/LICENSE

diff --git a/packages/visuals/LICENSE b/packages/visuals/LICENSE
new file mode 100644
index 0000000..f288702
--- /dev/null
+++ b/packages/visuals/LICENSE
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.