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

package/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`.

package/README.md

@@ -5,6 +5,8 @@
 
 A composable Turing-machine engine for JavaScript: multi-tape, subroutine composition via `withOverriddenHaltState`, Mermaid round-trip, and runtime breakpoints.
 
+For runtime highlight + breakpoint rendering on top of the engine's `Graph`, plus a byte-identical edge-label formatter and snippet-recording artifacts, see the companion package [`@turing-machine-js/visuals`](../visuals).
+
 <details>
 <summary>Table of contents</summary>
 
@@ -239,7 +241,7 @@ const s = new State({
 Notable members and statics:
 
 - **`state.id`**, **`state.name`** — identity (`isHalt` is `id === 0`).
-- **`state.withOverriddenHaltState(other)`** — returns a copy whose would-be halt transitions fall through to `other`. The subroutine-call composition mechanism (see `library-binary-numbers/src/index.ts` for examples).
+- **`state.withOverriddenHaltState(other)`** — returns a `CallFrame` (a `State` subclass, so it flows anywhere a `State` does) whose would-be halt transitions fall through to `other`. The subroutine-call composition mechanism (see `library-binary-numbers/src/index.ts` for examples). `instanceof CallFrame` is the wrapper discriminator.
 - **`State.toGraph(state, tapeBlock)`** — walks the reachable graph from `state` and returns a serializable `Graph` (states, transitions, alphabets).
 - **`State.fromGraph(graph)`** — inverse of `toGraph`: rebuilds `State` instances + a fresh `TapeBlock` from a `Graph`. Round-trips together with `toMermaid` / `fromMermaid`.
 - **`State.collectStates(state, tapeBlock)`** — walks the same graph and returns a `Map<number, {state, transitionSymbols}>` keyed by `GraphNode.id`. Use when downstream tooling holds a numeric id (e.g. a clicked node in a rendered graph) and needs the live `State` instance or the per-pattern `Symbol` for breakpoint setup. See [Setting breakpoints by graph id](#setting-breakpoints-by-graph-id).
@@ -378,7 +380,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';
@@ -447,7 +449,7 @@ flowchart TD
 
 **Reading guide** — the v7 callable-subtree emit (introduced in [#174](https://github.com/mellonis/turing-machine-js/issues/174)) models `withOverriddenHaltState` as a function call: the wrapper is the call site, the bare's subtree is the callable body.
 
-1. **`[[scanToX(eraseHere)]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node, drawn OUTSIDE any subgraph. It's the runtime entry point — `idle -. enter .->` arrives here — and shows the composite name (`bare(override)`). Wrappers have no transitions of their own; they delegate to the bare via the `call` arrow.
+1. **`[[scanToX(eraseHere)]]` (Mermaid subroutine / double-walled-rectangle shape)** is the wrapper node. It's the runtime entry point — `idle -. enter .->` arrives here — and shows the composite name (`bare(override)`). Wrappers have no transitions of their own; they delegate to the bare via the `call` arrow. **Placement**: this top-level wrapper is drawn OUTSIDE any subgraph; a wrapper that participates in a caller's frame (e.g. an inner-call continuation of another wrapper, as in `library-binary-numbers/minusOne`) renders INSIDE its owner frame's subgraph with the same `[[…]]` shape (see [#223](https://github.com/mellonis/turing-machine-js/issues/223)).
 2. **`subgraph w_1["callable subtree of scanToX"]`** is the bare's callable subtree — the scope of code that runs when the wrapper is "called." It contains the bare `s1["scanToX"]`, any body states reachable from the bare, and a local halt marker `c1(((halt)))` where the bare's halt-bound transitions land.
 3. **The bold `==> call`** from wrapper to bare is the call arrow — visual signature of "wrapper invokes this callable subtree, pushing its override onto the runtime stack." Bold arrows are reserved for wrapper-to-bare calls; counting them in a diagram counts the wrappers in play.
 4. **The dotted `-. return .->`** from the subtree back to the wrapper is the return arrow — fires when the bare halts (lands on `c1`) and the stack pops. The wrapper's solid `--> s2` (to `eraseHere`) is the post-return continuation; ordinary transition under the function-call mental model.
@@ -472,7 +474,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.
 
@@ -530,9 +532,11 @@ 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.
+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).
 
@@ -752,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) |
 

package/dist/classes/State.d.ts

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

package/dist/index.cjs

@@ -853,33 +853,70 @@ function toGraph(initialState, tapeBlock) {
         };
     }
     // 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; including wrappers AND tunneling through
+    // them to their `overriddenHaltStateId` continuation).
+    //
+    // 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.
+    //
+    // Wrapper chains (continuation IS another wrapper, e.g., nested
+    // compositions) are walked transitively by the inner while-loop in
+    // `resolveAndPush` — each tunnel hop pushes the intermediate wrapper.
     const computeReach = (startId) => {
         const reach = new Set();
-        const stack = [startId];
+        const stack = [];
+        const resolveAndPush = (id) => {
+            let current = id;
+            while (true) {
+                const target = nodes[current];
+                if (!target || target.isHalt) {
+                    return;
+                }
+                if (!target.isWrapper) {
+                    stack.push(current);
+                    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. */
+                if (target.overriddenHaltStateId === null) {
+                    return;
+                }
+                current = target.overriddenHaltStateId;
+            }
+        };
+        resolveAndPush(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.
-            /* 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;
-            }
             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);
+            // 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);
             }
         }
         return reach;
@@ -1240,7 +1277,7 @@ var __classPrivateFieldGet$2 = (undefined && undefined.__classPrivateFieldGet) |
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_instances, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_haltDebug, _State_tags, _State_getEntry;
+var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_instances, _a, _State_wrapperCache, _State_id, _State_name, _State_symbolToDataMap, _State_debugRef, _State_haltDebug, _State_tags, _State_getEntry, _CallFrame_bare, _CallFrame_override;
 const ifOtherSymbol = Symbol('other symbol');
 // Module-private symbol used by DebugConfig setters to call State's validator
 // without exposing the validator on the public surface.
@@ -1312,12 +1349,6 @@ class State {
         // composed name on a no-arg `new State()` to bypass the constructor's
         // user-facing name validation (composite names contain `(` and `)`).
         _State_name.set(this, void 0);
-        _State_overriddenHaltState.set(this, 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.
-        _State_bareState.set(this, null);
         _State_symbolToDataMap.set(this, new Map());
         // Shared mutable cell — withOverriddenHaltState wrappers reference the same
         // object so that `state.debug = ...` (and nullings) propagate across them.
@@ -1395,8 +1426,10 @@ class State {
     get isHalt() {
         return __classPrivateFieldGet$2(this, _State_id, "f") === 0;
     }
+    // Plain States never override the halt state — only a `CallFrame` (produced
+    // by `withOverriddenHaltState`) carries an override, via its own getter.
     get overriddenHaltState() {
-        return __classPrivateFieldGet$2(this, _State_overriddenHaltState, "f");
+        return null;
     }
     get ref() {
         return this;
@@ -1498,7 +1531,7 @@ class State {
     /** @internal — invoked by DebugConfig setters via module-private symbol.
      *  haltState's `debug` setter rejects object writes before reaching
      *  DebugConfig, so this validator only sees non-halt states. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_haltDebug = new WeakMap(), _State_tags = new WeakMap(), _State_instances = new WeakSet(), validateDebugFilter)](fieldName, filter) {
+    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_haltDebug = new WeakMap(), _State_tags = new WeakMap(), _State_instances = new WeakSet(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
         if (filter === true)
@@ -1557,13 +1590,13 @@ class State {
         return { nextState: entry.nextState, matchedSymbol: symbol, ix };
     }
     withOverriddenHaltState(overriddenHaltState) {
-        // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
+        // 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 = __classPrivateFieldGet$2(this, _State_bareState, "f") ?? 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)`.
@@ -1581,17 +1614,9 @@ class State {
             innerCache = new WeakMap();
             __classPrivateFieldGet$2(_a, _a, "f", _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 _a();
-        __classPrivateFieldSet$2(state, _State_name, `${bare.name}(${overriddenHaltState.name})`, "f");
-        __classPrivateFieldSet$2(state, _State_symbolToDataMap, __classPrivateFieldGet$2(bare, _State_symbolToDataMap, "f"), "f");
-        __classPrivateFieldSet$2(state, _State_overriddenHaltState, overriddenHaltState, "f");
-        __classPrivateFieldSet$2(state, _State_debugRef, __classPrivateFieldGet$2(bare, _State_debugRef, "f"), "f");
-        __classPrivateFieldSet$2(state, _State_bareState, bare, "f");
-        innerCache.set(overriddenHaltState, new WeakRef(state));
-        return state;
+        const frame = new CallFrame(bare, overriddenHaltState);
+        innerCache.set(overriddenHaltState, new WeakRef(frame));
+        return frame;
     }
     /**
      * @internal
@@ -1634,8 +1659,8 @@ class State {
             get id() { return __classPrivateFieldGet$2(self, _State_id, "f"); },
             get name() { return __classPrivateFieldGet$2(self, _State_name, "f"); },
             set name(v) { __classPrivateFieldSet$2(self, _State_name, v, "f"); },
-            get bareState() { return __classPrivateFieldGet$2(self, _State_bareState, "f"); },
-            get overriddenHaltState() { return __classPrivateFieldGet$2(self, _State_overriddenHaltState, "f"); },
+            get bareState() { return null; },
+            get overriddenHaltState() { return null; },
             get symbolToDataMap() { return __classPrivateFieldGet$2(self, _State_symbolToDataMap, "f"); },
             get tags() { return __classPrivateFieldGet$2(self, _State_tags, "f"); },
         };
@@ -1646,8 +1671,13 @@ class State {
     // Symbol patterns are returned as the raw description string from the
     // interned JS Symbol (decode via decodePatternDescription if needed).
     static inspect(state) {
+        // 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 = [];
-        for (const [sym, { command, nextState }] of __classPrivateFieldGet$2(state, _State_symbolToDataMap, "f")) {
+        for (const [sym, { command, nextState }] of internal.symbolToDataMap) {
             let target = null;
             try {
                 target = nextState instanceof _a ? nextState : nextState.ref;
@@ -1664,12 +1694,13 @@ class State {
                 nextState: target ? { id: target.id, name: target.name } : null,
             });
         }
+        const override = internal.overriddenHaltState;
         return {
-            id: __classPrivateFieldGet$2(state, _State_id, "f"),
-            name: __classPrivateFieldGet$2(state, _State_name, "f"),
+            id: internal.id,
+            name: internal.name,
             isHalt: state.isHalt,
-            overriddenHaltState: __classPrivateFieldGet$2(state, _State_overriddenHaltState, "f")
-                ? { id: __classPrivateFieldGet$2(state, _State_overriddenHaltState, "f").id, name: __classPrivateFieldGet$2(state, _State_overriddenHaltState, "f").name }
+            overriddenHaltState: override
+                ? { id: override.id, name: override.name }
                 : null,
             transitions,
         };
@@ -1714,6 +1745,79 @@ _a = State;
 // them, with cache misses simply reconstructing fresh wrappers.
 _State_wrapperCache = { value: new WeakMap() };
 const haltState = new State(null);
+/**
+ * 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`).
+ */
+class CallFrame extends State {
+    constructor(bare, override) {
+        super(null);
+        _CallFrame_bare.set(this, void 0);
+        _CallFrame_override.set(this, void 0);
+        __classPrivateFieldSet$2(this, _CallFrame_bare, bare, "f");
+        __classPrivateFieldSet$2(this, _CallFrame_override, override, "f");
+        // 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() {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f");
+    }
+    get overriddenHaltState() {
+        return __classPrivateFieldGet$2(this, _CallFrame_override, "f");
+    }
+    getSymbol(tapeBlock) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getSymbol(tapeBlock);
+    }
+    getCommand(symbol) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getCommand(symbol);
+    }
+    getNextState(symbol) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getNextState(symbol);
+    }
+    getMatchedTransition(symbol) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getMatchedTransition(symbol);
+    }
+    get debug() {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").debug;
+    }
+    set debug(value) {
+        __classPrivateFieldGet$2(this, _CallFrame_bare, "f").debug = value;
+    }
+    [(_CallFrame_bare = new WeakMap(), _CallFrame_override = new WeakMap(), 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 = __classPrivateFieldGet$2(this, _CallFrame_bare, "f");
+        const override = __classPrivateFieldGet$2(this, _CallFrame_override, "f");
+        return {
+            get id() { return own.id; },
+            get name() { return own.name; },
+            set name(v) { own.name = v; },
+            get bareState() { return bare; },
+            get overriddenHaltState() { return override; },
+            get symbolToDataMap() { return bare[STATE_INTERNAL]().symbolToDataMap; },
+            get tags() { return own.tags; },
+        };
+    }
+}
 
 var __classPrivateFieldSet$1 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
@@ -1810,16 +1914,10 @@ 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 = {
                     id: `${resolvableStateId}.${matched.ix}`,
                     matchKinds: __classPrivateFieldGet$1(this, _TuringMachine_tapeBlock, "f").patternKinds(matched.matchedSymbol),
@@ -2321,14 +2419,20 @@ function toMermaid(graph) {
     const nodes = Object.values(graph.nodes).slice().sort((a, b) => a.id - b.id);
     // 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();
     // Halt-marker per frame (kept separate so it always emits LAST inside the
     // subgraph for deterministic shape).
     const haltMarkerByFrame = new Map();
     for (const node of nodes) {
-        if (node.frameId === null || node.isWrapper)
+        if (node.frameId === null)
             continue;
         if (node.isHaltMarker) {
             haltMarkerByFrame.set(node.frameId, node);
@@ -2371,8 +2475,9 @@ function toMermaid(graph) {
             lines.push(`  ${mid}["${labelOf(node)}"]`);
         }
     }
-    // 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)}"]]`);
     }
     // 3. `idle` sentinel.
@@ -2389,9 +2494,16 @@ function toMermaid(graph) {
             ? `callable scope: ${frameBareNames.join(' ∪ ')}`
             : `callable subtree of ${frameBareNames[0] ?? frameId}`;
         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
         // creates one for each frame. Non-null assertion is safe; a defensive
@@ -3029,6 +3141,7 @@ function runOnce(runnable, input, stepsLimit) {
 }
 
 exports.Alphabet = Alphabet;
+exports.CallFrame = CallFrame;
 exports.Command = Command;
 exports.DebugConfig = DebugConfig;
 exports.DebugSession = DebugSession;

package/dist/index.d.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';

package/dist/index.mjs

@@ -851,33 +851,70 @@ function toGraph(initialState, tapeBlock) {
         };
     }
     // 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; including wrappers AND tunneling through
+    // them to their `overriddenHaltStateId` continuation).
+    //
+    // 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.
+    //
+    // Wrapper chains (continuation IS another wrapper, e.g., nested
+    // compositions) are walked transitively by the inner while-loop in
+    // `resolveAndPush` — each tunnel hop pushes the intermediate wrapper.
     const computeReach = (startId) => {
         const reach = new Set();
-        const stack = [startId];
+        const stack = [];
+        const resolveAndPush = (id) => {
+            let current = id;
+            while (true) {
+                const target = nodes[current];
+                if (!target || target.isHalt) {
+                    return;
+                }
+                if (!target.isWrapper) {
+                    stack.push(current);
+                    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. */
+                if (target.overriddenHaltStateId === null) {
+                    return;
+                }
+                current = target.overriddenHaltStateId;
+            }
+        };
+        resolveAndPush(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.
-            /* 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;
-            }
             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);
+            // 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);
             }
         }
         return reach;
@@ -1238,7 +1275,7 @@ var __classPrivateFieldGet$2 = (undefined && undefined.__classPrivateFieldGet) |
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_instances, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_haltDebug, _State_tags, _State_getEntry;
+var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_instances, _a, _State_wrapperCache, _State_id, _State_name, _State_symbolToDataMap, _State_debugRef, _State_haltDebug, _State_tags, _State_getEntry, _CallFrame_bare, _CallFrame_override;
 const ifOtherSymbol = Symbol('other symbol');
 // Module-private symbol used by DebugConfig setters to call State's validator
 // without exposing the validator on the public surface.
@@ -1310,12 +1347,6 @@ class State {
         // composed name on a no-arg `new State()` to bypass the constructor's
         // user-facing name validation (composite names contain `(` and `)`).
         _State_name.set(this, void 0);
-        _State_overriddenHaltState.set(this, 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.
-        _State_bareState.set(this, null);
         _State_symbolToDataMap.set(this, new Map());
         // Shared mutable cell — withOverriddenHaltState wrappers reference the same
         // object so that `state.debug = ...` (and nullings) propagate across them.
@@ -1393,8 +1424,10 @@ class State {
     get isHalt() {
         return __classPrivateFieldGet$2(this, _State_id, "f") === 0;
     }
+    // Plain States never override the halt state — only a `CallFrame` (produced
+    // by `withOverriddenHaltState`) carries an override, via its own getter.
     get overriddenHaltState() {
-        return __classPrivateFieldGet$2(this, _State_overriddenHaltState, "f");
+        return null;
     }
     get ref() {
         return this;
@@ -1496,7 +1529,7 @@ class State {
     /** @internal — invoked by DebugConfig setters via module-private symbol.
      *  haltState's `debug` setter rejects object writes before reaching
      *  DebugConfig, so this validator only sees non-halt states. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_haltDebug = new WeakMap(), _State_tags = new WeakMap(), _State_instances = new WeakSet(), validateDebugFilter)](fieldName, filter) {
+    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_haltDebug = new WeakMap(), _State_tags = new WeakMap(), _State_instances = new WeakSet(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
         if (filter === true)
@@ -1555,13 +1588,13 @@ class State {
         return { nextState: entry.nextState, matchedSymbol: symbol, ix };
     }
     withOverriddenHaltState(overriddenHaltState) {
-        // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
+        // 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 = __classPrivateFieldGet$2(this, _State_bareState, "f") ?? 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)`.
@@ -1579,17 +1612,9 @@ class State {
             innerCache = new WeakMap();
             __classPrivateFieldGet$2(_a, _a, "f", _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 _a();
-        __classPrivateFieldSet$2(state, _State_name, `${bare.name}(${overriddenHaltState.name})`, "f");
-        __classPrivateFieldSet$2(state, _State_symbolToDataMap, __classPrivateFieldGet$2(bare, _State_symbolToDataMap, "f"), "f");
-        __classPrivateFieldSet$2(state, _State_overriddenHaltState, overriddenHaltState, "f");
-        __classPrivateFieldSet$2(state, _State_debugRef, __classPrivateFieldGet$2(bare, _State_debugRef, "f"), "f");
-        __classPrivateFieldSet$2(state, _State_bareState, bare, "f");
-        innerCache.set(overriddenHaltState, new WeakRef(state));
-        return state;
+        const frame = new CallFrame(bare, overriddenHaltState);
+        innerCache.set(overriddenHaltState, new WeakRef(frame));
+        return frame;
     }
     /**
      * @internal
@@ -1632,8 +1657,8 @@ class State {
             get id() { return __classPrivateFieldGet$2(self, _State_id, "f"); },
             get name() { return __classPrivateFieldGet$2(self, _State_name, "f"); },
             set name(v) { __classPrivateFieldSet$2(self, _State_name, v, "f"); },
-            get bareState() { return __classPrivateFieldGet$2(self, _State_bareState, "f"); },
-            get overriddenHaltState() { return __classPrivateFieldGet$2(self, _State_overriddenHaltState, "f"); },
+            get bareState() { return null; },
+            get overriddenHaltState() { return null; },
             get symbolToDataMap() { return __classPrivateFieldGet$2(self, _State_symbolToDataMap, "f"); },
             get tags() { return __classPrivateFieldGet$2(self, _State_tags, "f"); },
         };
@@ -1644,8 +1669,13 @@ class State {
     // Symbol patterns are returned as the raw description string from the
     // interned JS Symbol (decode via decodePatternDescription if needed).
     static inspect(state) {
+        // 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 = [];
-        for (const [sym, { command, nextState }] of __classPrivateFieldGet$2(state, _State_symbolToDataMap, "f")) {
+        for (const [sym, { command, nextState }] of internal.symbolToDataMap) {
             let target = null;
             try {
                 target = nextState instanceof _a ? nextState : nextState.ref;
@@ -1662,12 +1692,13 @@ class State {
                 nextState: target ? { id: target.id, name: target.name } : null,
             });
         }
+        const override = internal.overriddenHaltState;
         return {
-            id: __classPrivateFieldGet$2(state, _State_id, "f"),
-            name: __classPrivateFieldGet$2(state, _State_name, "f"),
+            id: internal.id,
+            name: internal.name,
             isHalt: state.isHalt,
-            overriddenHaltState: __classPrivateFieldGet$2(state, _State_overriddenHaltState, "f")
-                ? { id: __classPrivateFieldGet$2(state, _State_overriddenHaltState, "f").id, name: __classPrivateFieldGet$2(state, _State_overriddenHaltState, "f").name }
+            overriddenHaltState: override
+                ? { id: override.id, name: override.name }
                 : null,
             transitions,
         };
@@ -1712,6 +1743,79 @@ _a = State;
 // them, with cache misses simply reconstructing fresh wrappers.
 _State_wrapperCache = { value: new WeakMap() };
 const haltState = new State(null);
+/**
+ * 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`).
+ */
+class CallFrame extends State {
+    constructor(bare, override) {
+        super(null);
+        _CallFrame_bare.set(this, void 0);
+        _CallFrame_override.set(this, void 0);
+        __classPrivateFieldSet$2(this, _CallFrame_bare, bare, "f");
+        __classPrivateFieldSet$2(this, _CallFrame_override, override, "f");
+        // 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() {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f");
+    }
+    get overriddenHaltState() {
+        return __classPrivateFieldGet$2(this, _CallFrame_override, "f");
+    }
+    getSymbol(tapeBlock) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getSymbol(tapeBlock);
+    }
+    getCommand(symbol) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getCommand(symbol);
+    }
+    getNextState(symbol) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getNextState(symbol);
+    }
+    getMatchedTransition(symbol) {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").getMatchedTransition(symbol);
+    }
+    get debug() {
+        return __classPrivateFieldGet$2(this, _CallFrame_bare, "f").debug;
+    }
+    set debug(value) {
+        __classPrivateFieldGet$2(this, _CallFrame_bare, "f").debug = value;
+    }
+    [(_CallFrame_bare = new WeakMap(), _CallFrame_override = new WeakMap(), 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 = __classPrivateFieldGet$2(this, _CallFrame_bare, "f");
+        const override = __classPrivateFieldGet$2(this, _CallFrame_override, "f");
+        return {
+            get id() { return own.id; },
+            get name() { return own.name; },
+            set name(v) { own.name = v; },
+            get bareState() { return bare; },
+            get overriddenHaltState() { return override; },
+            get symbolToDataMap() { return bare[STATE_INTERNAL]().symbolToDataMap; },
+            get tags() { return own.tags; },
+        };
+    }
+}
 
 var __classPrivateFieldSet$1 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
@@ -1808,16 +1912,10 @@ 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 = {
                     id: `${resolvableStateId}.${matched.ix}`,
                     matchKinds: __classPrivateFieldGet$1(this, _TuringMachine_tapeBlock, "f").patternKinds(matched.matchedSymbol),
@@ -2319,14 +2417,20 @@ function toMermaid(graph) {
     const nodes = Object.values(graph.nodes).slice().sort((a, b) => a.id - b.id);
     // 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();
     // Halt-marker per frame (kept separate so it always emits LAST inside the
     // subgraph for deterministic shape).
     const haltMarkerByFrame = new Map();
     for (const node of nodes) {
-        if (node.frameId === null || node.isWrapper)
+        if (node.frameId === null)
             continue;
         if (node.isHaltMarker) {
             haltMarkerByFrame.set(node.frameId, node);
@@ -2369,8 +2473,9 @@ function toMermaid(graph) {
             lines.push(`  ${mid}["${labelOf(node)}"]`);
         }
     }
-    // 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)}"]]`);
     }
     // 3. `idle` sentinel.
@@ -2387,9 +2492,16 @@ function toMermaid(graph) {
             ? `callable scope: ${frameBareNames.join(' ∪ ')}`
             : `callable subtree of ${frameBareNames[0] ?? frameId}`;
         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
         // creates one for each frame. Non-null assertion is safe; a defensive
@@ -3026,4 +3138,4 @@ function runOnce(runnable, input, stepsLimit) {
     };
 }
 
-export { Alphabet, Command, DebugConfig, DebugSession, Reference, State, Tape, TapeBlock, TapeCommand, TuringMachine, equivalentOn, fromMermaid, haltState, ifOtherSymbol, movements, summarize, summarizeGraph, symbolCommands, toMermaid };
+export { Alphabet, CallFrame, Command, DebugConfig, DebugSession, Reference, State, Tape, TapeBlock, TapeCommand, TuringMachine, equivalentOn, fromMermaid, haltState, ifOtherSymbol, movements, summarize, summarizeGraph, symbolCommands, toMermaid };

package/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"
@@ -38,5 +38,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "0b44e44db9da4a2f50bb46e5f723382345fdc687"
+  "gitHead": "130d4fd8b964da21a408af2986295e8000828f78"
 }