@turing-machine-js/visuals 7.0.0-alpha.6 → 7.0.0-alpha.6.1

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

package/dist/format.d.ts

@@ -1,4 +1,16 @@
 import { 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 declare const MOVEMENT_LETTER: Map<symbol, "L" | "R" | "S">;
 /**
  * Render a single tape command in `WRITE/MOVE` form.
@@ -20,3 +32,106 @@ export declare function formatCommand(tapeCommand: TapeCommand): string;
  * by comparing `nextSymbols[i] === currentSymbols[i]`.
  */
 export declare function formatStep(m: MachineState): string;
+/**
+ * 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 declare function tokenizeStep(reads: readonly string[] | null, commands: readonly StepCommand[], blanks: readonly string[], matchKinds?: readonly ('wildcard' | 'literal')[] | null): StepTokens;
+/**
+ * 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. Thin
+ * string renderer over `tokenizeStep`; see that function's docstring +
+ * `StepTokens` for the structured form most UIs should prefer.
+ *
+ * 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).
+ * - 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: 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 declare function formatStepNotation(reads: readonly string[] | null, commands: readonly StepCommand[], blanks: readonly string[], matchKinds?: readonly ('wildcard' | 'literal')[] | null): string;
+/** 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 declare function formatTape(tape: TapeSnapshot): string;

package/dist/index.cjs

@@ -411,6 +411,103 @@ function formatStep(m) {
     const moves = m.movements.map((mv) => MOVEMENT_LETTER.get(mv) ?? '?').join(',');
     return `[${reads}] → [${writes}]/[${moves}]`;
 }
+/**
+ * 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.
+ */
+function tokenizeStep(reads, commands, blanks, matchKinds) {
+    const writes = 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 = 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) {
+    if (t.kind === 'wildcard')
+        return `*='${t.symbol}'`;
+    if (t.kind === 'blank')
+        return 'B';
+    return `'${t.symbol}'`;
+}
+function renderWriteToken(t) {
+    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. Thin
+ * string renderer over `tokenizeStep`; see that function's docstring +
+ * `StepTokens` for the structured form most UIs should prefer.
+ *
+ * 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).
+ * - 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: 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).
+ */
+function formatStepNotation(reads, commands, blanks, matchKinds) {
+    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}`;
+}
+/** 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. */
+function formatTape(tape) {
+    return tape.symbols
+        .map((sym, i) => (i === tape.position ? `[${sym}]` : sym))
+        .join('');
+}
 
 const DEFAULT_MAX_STEPS = 1000;
 function snapshotTapes(machine) {
@@ -508,7 +605,10 @@ exports.bareIdOf = bareIdOf;
 exports.equivalentIds = equivalentIds;
 exports.formatCommand = formatCommand;
 exports.formatStep = formatStep;
+exports.formatStepNotation = formatStepNotation;
+exports.formatTape = formatTape;
 exports.highlightExpand = highlightExpand;
 exports.indexGraph = indexGraph;
 exports.recordSnippet = recordSnippet;
 exports.recordingOps = recordingOps;
+exports.tokenizeStep = tokenizeStep;

package/dist/index.d.ts

@@ -5,5 +5,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, tokenizeStep, type StepCommand, type ReadToken, type WriteToken, type StepTokens, } from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';

package/dist/index.mjs

@@ -409,6 +409,103 @@ function formatStep(m) {
     const moves = m.movements.map((mv) => MOVEMENT_LETTER.get(mv) ?? '?').join(',');
     return `[${reads}] → [${writes}]/[${moves}]`;
 }
+/**
+ * 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.
+ */
+function tokenizeStep(reads, commands, blanks, matchKinds) {
+    const writes = 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 = 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) {
+    if (t.kind === 'wildcard')
+        return `*='${t.symbol}'`;
+    if (t.kind === 'blank')
+        return 'B';
+    return `'${t.symbol}'`;
+}
+function renderWriteToken(t) {
+    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. Thin
+ * string renderer over `tokenizeStep`; see that function's docstring +
+ * `StepTokens` for the structured form most UIs should prefer.
+ *
+ * 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).
+ * - 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: 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).
+ */
+function formatStepNotation(reads, commands, blanks, matchKinds) {
+    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}`;
+}
+/** 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. */
+function formatTape(tape) {
+    return tape.symbols
+        .map((sym, i) => (i === tape.position ? `[${sym}]` : sym))
+        .join('');
+}
 
 const DEFAULT_MAX_STEPS = 1000;
 function snapshotTapes(machine) {
@@ -500,4 +597,4 @@ function recordSnippet(opts) {
     };
 }
 
-export { applyHighlight, applyIndicator, bareIdOf, equivalentIds, formatCommand, formatStep, highlightExpand, indexGraph, recordSnippet, recordingOps };
+export { applyHighlight, applyIndicator, bareIdOf, equivalentIds, formatCommand, formatStep, formatStepNotation, formatTape, highlightExpand, indexGraph, recordSnippet, recordingOps, tokenizeStep };

package/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"
@@ -42,5 +42,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "7801a33fef2f6c30cf6e1c2780b1fbf58685f064"
+  "gitHead": "4f5364293038aabea742235ea0cec2b135f0d6b7"
 }

package/dist/applyHighlight.js

@@ -1,191 +0,0 @@
-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, graph, indexes, prevStrongId, ops) {
-    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 = 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 = 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, graph, nodeIds, ops) {
-    for (const key of nodeIds) {
-        const on = typeof key === 'number'
-            && graph !== null
-            && breakpoints.has(bareIdOf(key, graph));
-        ops.setBreakpoint(key, on);
-    }
-}

package/dist/format.js

@@ -1,46 +0,0 @@
-import { movements, symbolCommands } from '@turing-machine-js/machine';
-export const MOVEMENT_LETTER = new Map([
-    [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) {
-    let write;
-    if (tapeCommand.symbol === symbolCommands.keep) {
-        write = 'K';
-    }
-    else if (tapeCommand.symbol === symbolCommands.erase) {
-        write = 'E';
-    }
-    else {
-        write = `'${tapeCommand.symbol}'`;
-    }
-    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) {
-    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}]`;
-}