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

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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
+
+- **`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
+
+- 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`.
+
 ## [7.0.0-alpha.6.1] - 2026-05-30
 
 ### Added

package/README.md

@@ -1,21 +1,309 @@
 # @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
+
+// 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).
+
+## 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.
+
+## Example: playing a snippet
+
+```ts
+import {
+  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 applyFrame(): void {
+  const frame = player.currentFrame;
+  // (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;
+  }
+  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.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.
+
+## 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)

package/dist/index.cjs

@@ -599,6 +599,130 @@ function recordSnippet(opts) {
     };
 }
 
+var __classPrivateFieldSet = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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 _SnippetPlayer_snippet, _SnippetPlayer_lastIndex, _SnippetPlayer_index;
+/**
+ * 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).
+ *
+ * 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.
+ */
+class SnippetPlayer {
+    constructor(snippet) {
+        _SnippetPlayer_snippet.set(this, void 0);
+        _SnippetPlayer_lastIndex.set(this, void 0);
+        _SnippetPlayer_index.set(this, 0);
+        if (snippet.frames.length === 0) {
+            throw new Error('SnippetPlayer: snippet has no frames');
+        }
+        __classPrivateFieldSet(this, _SnippetPlayer_snippet, snippet, "f");
+        __classPrivateFieldSet(this, _SnippetPlayer_lastIndex, snippet.frames.length - 1, "f");
+    }
+    /** The frame at the current index. Live getter — re-reads on every access. */
+    get currentFrame() {
+        return __classPrivateFieldGet(this, _SnippetPlayer_snippet, "f").frames[__classPrivateFieldGet(this, _SnippetPlayer_index, "f")];
+    }
+    /** Current frame index (0 = initial state, `snippet.frames.length - 1` = final). */
+    get frameIndex() {
+        return __classPrivateFieldGet(this, _SnippetPlayer_index, "f");
+    }
+    /** True when `frameIndex === snippet.frames.length - 1`. */
+    get done() {
+        return __classPrivateFieldGet(this, _SnippetPlayer_index, "f") === __classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f");
+    }
+    /**
+     * Advance one frame. Returns `true` if advanced, `false` if already at the
+     * last frame (no-op in that case).
+     */
+    forward() {
+        if (__classPrivateFieldGet(this, _SnippetPlayer_index, "f") >= __classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f"))
+            return false;
+        __classPrivateFieldSet(this, _SnippetPlayer_index, __classPrivateFieldGet(this, _SnippetPlayer_index, "f") + 1, "f");
+        return true;
+    }
+    /**
+     * Retreat one frame. Returns `true` if retreated, `false` if already at
+     * the first frame (no-op in that case).
+     */
+    back() {
+        if (__classPrivateFieldGet(this, _SnippetPlayer_index, "f") <= 0)
+            return false;
+        __classPrivateFieldSet(this, _SnippetPlayer_index, __classPrivateFieldGet(this, _SnippetPlayer_index, "f") - 1, "f");
+        return true;
+    }
+    /** Jump to frame 0. */
+    reset() {
+        __classPrivateFieldSet(this, _SnippetPlayer_index, 0, "f");
+    }
+    /**
+     * Jump to a specific frame index. Throws `RangeError` if out of bounds
+     * (negative, beyond the last frame, or not an integer).
+     */
+    goTo(frameIndex) {
+        if (!Number.isInteger(frameIndex) || frameIndex < 0 || frameIndex > __classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f")) {
+            throw new RangeError(`SnippetPlayer.goTo: frame index ${frameIndex} out of bounds [0, ${__classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f")}]`);
+        }
+        __classPrivateFieldSet(this, _SnippetPlayer_index, frameIndex, "f");
+    }
+}
+_SnippetPlayer_snippet = new WeakMap(), _SnippetPlayer_lastIndex = new WeakMap(), _SnippetPlayer_index = new WeakMap();
+
+/**
+ * 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).
+ */
+function tapeViewport(snapshot, width, blank) {
+    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 = 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 };
+}
+
+exports.SnippetPlayer = SnippetPlayer;
 exports.applyHighlight = applyHighlight;
 exports.applyIndicator = applyIndicator;
 exports.bareIdOf = bareIdOf;
@@ -611,4 +735,5 @@ exports.highlightExpand = highlightExpand;
 exports.indexGraph = indexGraph;
 exports.recordSnippet = recordSnippet;
 exports.recordingOps = recordingOps;
+exports.tapeViewport = tapeViewport;
 exports.tokenizeStep = tokenizeStep;

package/dist/index.d.ts

@@ -7,3 +7,5 @@ export type { GraphHighlight, TapeSnapshot, Frame, Snippet } from './types';
 export { applyHighlight, applyIndicator } from './applyHighlight';
 export { formatCommand, formatStep, formatStepNotation, formatTape, tokenizeStep, type StepCommand, type ReadToken, type WriteToken, type StepTokens, } from './format';
 export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';
+export { SnippetPlayer } from './snippetPlayer';
+export { tapeViewport } from './tapeViewport';

package/dist/index.mjs

@@ -597,4 +597,127 @@ function recordSnippet(opts) {
     };
 }
 
-export { applyHighlight, applyIndicator, bareIdOf, equivalentIds, formatCommand, formatStep, formatStepNotation, formatTape, highlightExpand, indexGraph, recordSnippet, recordingOps, tokenizeStep };
+var __classPrivateFieldSet = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (undefined && undefined.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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 _SnippetPlayer_snippet, _SnippetPlayer_lastIndex, _SnippetPlayer_index;
+/**
+ * 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).
+ *
+ * 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.
+ */
+class SnippetPlayer {
+    constructor(snippet) {
+        _SnippetPlayer_snippet.set(this, void 0);
+        _SnippetPlayer_lastIndex.set(this, void 0);
+        _SnippetPlayer_index.set(this, 0);
+        if (snippet.frames.length === 0) {
+            throw new Error('SnippetPlayer: snippet has no frames');
+        }
+        __classPrivateFieldSet(this, _SnippetPlayer_snippet, snippet, "f");
+        __classPrivateFieldSet(this, _SnippetPlayer_lastIndex, snippet.frames.length - 1, "f");
+    }
+    /** The frame at the current index. Live getter — re-reads on every access. */
+    get currentFrame() {
+        return __classPrivateFieldGet(this, _SnippetPlayer_snippet, "f").frames[__classPrivateFieldGet(this, _SnippetPlayer_index, "f")];
+    }
+    /** Current frame index (0 = initial state, `snippet.frames.length - 1` = final). */
+    get frameIndex() {
+        return __classPrivateFieldGet(this, _SnippetPlayer_index, "f");
+    }
+    /** True when `frameIndex === snippet.frames.length - 1`. */
+    get done() {
+        return __classPrivateFieldGet(this, _SnippetPlayer_index, "f") === __classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f");
+    }
+    /**
+     * Advance one frame. Returns `true` if advanced, `false` if already at the
+     * last frame (no-op in that case).
+     */
+    forward() {
+        if (__classPrivateFieldGet(this, _SnippetPlayer_index, "f") >= __classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f"))
+            return false;
+        __classPrivateFieldSet(this, _SnippetPlayer_index, __classPrivateFieldGet(this, _SnippetPlayer_index, "f") + 1, "f");
+        return true;
+    }
+    /**
+     * Retreat one frame. Returns `true` if retreated, `false` if already at
+     * the first frame (no-op in that case).
+     */
+    back() {
+        if (__classPrivateFieldGet(this, _SnippetPlayer_index, "f") <= 0)
+            return false;
+        __classPrivateFieldSet(this, _SnippetPlayer_index, __classPrivateFieldGet(this, _SnippetPlayer_index, "f") - 1, "f");
+        return true;
+    }
+    /** Jump to frame 0. */
+    reset() {
+        __classPrivateFieldSet(this, _SnippetPlayer_index, 0, "f");
+    }
+    /**
+     * Jump to a specific frame index. Throws `RangeError` if out of bounds
+     * (negative, beyond the last frame, or not an integer).
+     */
+    goTo(frameIndex) {
+        if (!Number.isInteger(frameIndex) || frameIndex < 0 || frameIndex > __classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f")) {
+            throw new RangeError(`SnippetPlayer.goTo: frame index ${frameIndex} out of bounds [0, ${__classPrivateFieldGet(this, _SnippetPlayer_lastIndex, "f")}]`);
+        }
+        __classPrivateFieldSet(this, _SnippetPlayer_index, frameIndex, "f");
+    }
+}
+_SnippetPlayer_snippet = new WeakMap(), _SnippetPlayer_lastIndex = new WeakMap(), _SnippetPlayer_index = new WeakMap();
+
+/**
+ * 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).
+ */
+function tapeViewport(snapshot, width, blank) {
+    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 = 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 };
+}
+
+export { SnippetPlayer, applyHighlight, applyIndicator, bareIdOf, equivalentIds, formatCommand, formatStep, formatStepNotation, formatTape, highlightExpand, indexGraph, recordSnippet, recordingOps, tapeViewport, tokenizeStep };

package/dist/snippetPlayer.d.ts

@@ -0,0 +1,44 @@
+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).
+ *
+ * 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 declare class SnippetPlayer {
+    #private;
+    constructor(snippet: Snippet);
+    /** The frame at the current index. Live getter — re-reads on every access. */
+    get currentFrame(): Frame;
+    /** Current frame index (0 = initial state, `snippet.frames.length - 1` = final). */
+    get frameIndex(): number;
+    /** True when `frameIndex === snippet.frames.length - 1`. */
+    get 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
+     * (negative, beyond the last frame, or not an integer).
+     */
+    goTo(frameIndex: number): void;
+}

package/dist/tapeViewport.d.ts

@@ -0,0 +1,23 @@
+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 declare function tapeViewport(snapshot: TapeSnapshot, width: number, blank: string): {
+    cells: string[];
+    headIndex: number;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/visuals",
-  "version": "7.0.0-alpha.6.1",
+  "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"
@@ -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",
@@ -42,5 +42,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "4f5364293038aabea742235ea0cec2b135f0d6b7"
+  "gitHead": "2adf5ab059319427a9a449370f91b2ea8e926059"
 }