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

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this package will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.0.0-alpha.7] - 2026-05-30
+
+Lockstep re-alignment with the engine 7.0.0-alpha.7 bump (engine [#213](https://github.com/mellonis/turing-machine-js/issues/213) `CallFrame` extraction + [#223](https://github.com/mellonis/turing-machine-js/issues/223) `toMermaid` framed-wrapper emit fix). No source or behavior changes in this package since alpha.6.1. Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.6` → `^7.0.0-alpha.7`.
+
+## [7.0.0-alpha.6.1] - 2026-05-30
+
+### Added
+
+- `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/README.md

@@ -1,21 +1,247 @@
 # @turing-machine-js/visuals
 
-Pure highlight + graph-indexing logic for [`@turing-machine-js/machine`](../machine). No DOM, no Svelte, no Mermaid — consumers bring their own renderer and DOM applier.
+Pure highlight + graph-indexing logic for [`@turing-machine-js/machine`](../machine) — plus a renderer-agnostic edge-label formatter and a `recordSnippet` artifact recorder for prerecorded playback (article embeds, landing-page panels, terminal tools). No DOM, no Svelte, no Mermaid — consumers bring their own renderer.
 
-## Scope
+## When to reach for this
 
-Types and pure functions for:
-- Indexing an engine `Graph` for wrapper/bare lookup (`indexGraph`, `bareIdOf`, `highlightExpand`).
-- Applying highlight + indicator operations against a renderer-agnostic `HighlightOps` interface (`applyHighlight`, `applyIndicator`).
-
-See [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md) for the full set of rules these functions satisfy.
-
-## Versioning
-
-Lockstep with `@turing-machine-js/machine`.
+- You have an engine `Graph` (from `State.toGraph(initialState, tapeBlock)`) and want to render it with **runtime highlight cues** — `from → edge → to` triples that animate as the machine steps, breakpoint dots, frame-active subgraph marks, pulse-on-revisit. Implement a small `HighlightOps` object that wraps your renderer's DOM/canvas/ANSI primitives; `applyHighlight` decides *what* to highlight, your `HighlightOps` decides *how*.
+- You want a logged step's notation to **line up byte-for-byte** with the rendered state graph's edge labels. `formatStepNotation` mirrors the engine's `toMermaid` edge-label vocabulary; same `[reads] → [writes]/[moves]`, same `'X'` / `B` / `*='X'` / `K='X'` / `E` shortcuts.
+- You want to **record a machine run** as a self-contained playback artifact — for an article embed, a landing-page panel, a snapshot test, anything that needs to replay a run without booting an engine. `recordSnippet` produces a `Snippet` with one `Frame` per iter (tape state + per-tape `{ movement, read, write }` command + highlight + optional log line); a player walks frames forward AND backward without recomputing deltas.
 
 ## Install
 
 ```sh
 npm install @turing-machine-js/visuals @turing-machine-js/machine
 ```
+
+Both prereleases on npm `next`:
+
+```sh
+npm install @turing-machine-js/visuals@next @turing-machine-js/machine@next
+```
+
+Peer-deps on `@turing-machine-js/machine@^7.0.0-alpha.6` — visuals follows engine v7 alphas with occasional visuals-only patches (`7.0.0-alpha.6.1` added the formatter primitives + token surface on top of the lockstep alpha.6 engine release).
+
+## Public API
+
+### Types
+
+```ts
+// Highlight contract
+type NodeKey = number | 'idle';
+type HighlightClass = 'mg-highlight-from' | 'mg-highlight-to' | 'mg-highlight-strong';
+interface HighlightOps {
+  addNodeClass(id: NodeKey, cls: HighlightClass): void;
+  highlightEdge(fromKey: string, toKey: string): void;
+  markFrameActive(frameId: number): void;
+  pulse(id: NodeKey): void;
+  scrollIntoView(id: NodeKey): void;
+}
+interface IndicatorOps {
+  setBreakpoint(id: NodeKey, on: boolean): void;
+}
+type GraphHighlight = {
+  fromId: number | 'idle';
+  toId: number | null;
+  strong: 'from' | 'to';
+  paused: boolean;
+};
+type GraphIndexes = { /* node→frame, frame→wrappers, frame→label, etc. */ };
+
+// Recording artifact
+type TapeSnapshot = { symbols: string[]; position: number };
+type StepCommand = { movement: 'L' | 'R' | 'S'; symbol: string | null };
+type Frame = {
+  step: number;
+  tape: TapeSnapshot[];
+  commands?: { movement: 'L' | 'R' | 'S'; read: string; write: string }[];
+  highlight: GraphHighlight | null;
+  log?: string;
+};
+type Snippet = {
+  version: 1;
+  name?: string;
+  graph: Graph;
+  alphabets: string[][];
+  frames: Frame[];
+};
+
+// Token surface (renderer-agnostic alternative to formatStepNotation strings)
+type ReadToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'blank' }
+  | { kind: 'wildcard'; symbol: string };
+type WriteToken =
+  | { kind: 'literal'; symbol: string }
+  | { kind: 'erase' }
+  | { kind: 'keep'; readContext?: { symbol: string; isBlank: boolean } };
+type StepTokens = {
+  reads: readonly ReadToken[] | null;  // null = manual-Apply path (no transition fired)
+  writes: readonly WriteToken[];
+  moves: readonly ('L' | 'R' | 'S')[];
+};
+```
+
+### Functions
+
+```ts
+indexGraph(graph): GraphIndexes
+applyHighlight(highlight, graph, indexes, prev, ops): { nextPrev }
+applyIndicator(breakpoints, graph, ops): void
+bareIdOf(id, graph): number
+highlightExpand(id, graph): number[]
+equivalentIds(id, graph): number[]
+recordingOps(): { highlight: HighlightOps; indicator: IndicatorOps; record: RecordedOp[] }
+
+// Formatters
+formatStepNotation(reads, commands, blanks, matchKinds?): string
+tokenizeStep(reads, commands, blanks, matchKinds?): StepTokens
+formatTape(tape): string
+formatCommand(tapeCommand): string  // alpha.6 single-command formatter; kept for back-compat
+formatStep(machineState): string    // alpha.6 MachineState-based formatter; kept for back-compat
+
+// Recording
+recordSnippet({ machine, initialState, graph, alphabets, name?, maxSteps?, log? }): Snippet
+```
+
+The 16-rule contract `applyHighlight` satisfies is documented at [`docs/graph-highlight-and-breakpoints.md`](./docs/graph-highlight-and-breakpoints.md).
+
+## Example: applying highlight in a DOM renderer
+
+```ts
+import {
+  applyHighlight,
+  indexGraph,
+  type HighlightOps,
+  type GraphHighlight,
+} from '@turing-machine-js/visuals';
+import { State } from '@turing-machine-js/machine';
+
+// 1. Build your machine + Graph elsewhere (typical Svelte / React / vanilla code).
+const graph = State.toGraph(initialState, tapeBlock);
+const indexes = indexGraph(graph);
+
+// 2. Tiny DOM applier (illustrative — your renderer probably has a richer one).
+function domOps(svgRoot: SVGSVGElement): HighlightOps {
+  const node = (id: number | 'idle') =>
+    svgRoot.querySelector(`g.node[data-id="${id === 'idle' ? 'idle' : `s${id}`}"]`);
+  return {
+    addNodeClass: (id, cls) => node(id)?.classList.add(cls),
+    highlightEdge: (from, to) =>
+      svgRoot
+        .querySelector(`path[data-id^="L_${from}_${to}_"]`)
+        ?.classList.add('mg-highlight-edge'),
+    markFrameActive: (frameId) =>
+      svgRoot.querySelector(`g.cluster[data-id="w_${frameId}"]`)?.classList.add('mg-frame-active'),
+    pulse: (id) => node(id)?.classList.add('mg-pulse'),
+    scrollIntoView: (id) => node(id)?.scrollIntoView({ block: 'nearest', behavior: 'smooth' }),
+  };
+}
+
+// 3. On each engine pause / step: wipe previous highlight from the DOM, then apply the new one.
+//    HighlightOps is purely additive — the consumer is responsible for clearing
+//    `mg-highlight-*` classes before calling applyHighlight.
+let prev = null;
+function onMachineStep(highlight: GraphHighlight | null, svgRoot: SVGSVGElement) {
+  // Wipe.
+  for (const el of svgRoot.querySelectorAll(
+    '.mg-highlight-from, .mg-highlight-to, .mg-highlight-strong, .mg-highlight-edge, .mg-frame-active',
+  )) {
+    el.classList.remove(
+      'mg-highlight-from',
+      'mg-highlight-to',
+      'mg-highlight-strong',
+      'mg-highlight-edge',
+      'mg-frame-active',
+    );
+  }
+  if (!highlight) return;
+  const result = applyHighlight(highlight, graph, indexes, prev, domOps(svgRoot));
+  prev = result.nextPrev;
+}
+```
+
+## Example: rendering a step's edge-label notation
+
+```ts
+import { formatStepNotation, type StepCommand } from '@turing-machine-js/visuals';
+
+const commands: StepCommand[] = [
+  { movement: 'R', symbol: 'b' },        // write 'b', move right
+  { movement: 'L', symbol: null },       // keep current symbol, move left
+];
+const reads = ['a', 'x'];
+const blanks = [' ', ' '];
+const matchKinds = ['literal', 'wildcard'] as const;
+
+formatStepNotation(reads, commands, blanks, matchKinds);
+// => "['a',*='x'] → ['b',K='x']/[R,L]"
+```
+
+For manual-Apply rendering (no transition fired), pass `reads: null`:
+
+```ts
+formatStepNotation(null, [{ movement: 'R', symbol: 'b' }], [' '], null);
+// => "['b']/[R]"
+```
+
+## Example: tokenize for custom (non-string) rendering
+
+```ts
+import { tokenizeStep } from '@turing-machine-js/visuals';
+
+const tokens = tokenizeStep(['a'], [{ movement: 'R', symbol: 'b' }], [' '], ['literal']);
+// tokens.reads:  [{ kind: 'literal', symbol: 'a' }]
+// tokens.writes: [{ kind: 'literal', symbol: 'b' }]
+// tokens.moves:  ['R']
+
+// Now render however you want — HTML spans with CSS classes, ANSI escapes, JSON, etc.
+function readToHtml(t: typeof tokens.reads[0]) {
+  if (t.kind === 'wildcard') return `<span class="cell-wildcard">${t.symbol}</span>`;
+  if (t.kind === 'blank') return `<span class="cell-blank">␣</span>`;
+  return `<span class="cell-literal">${t.symbol}</span>`;
+}
+```
+
+## Example: recording a snippet
+
+```ts
+import { recordSnippet, formatStep } from '@turing-machine-js/visuals';
+import {
+  Alphabet, Tape, TapeBlock, TuringMachine, State, haltState, movements,
+} from '@turing-machine-js/machine';
+
+const alphabet = new Alphabet([' ', 'a', 'b']);
+const tape = new Tape({ alphabet, symbols: ['a', 'a', 'a'] });
+const tapeBlock = TapeBlock.fromTapes([tape]);
+const machine = new TuringMachine({ tapeBlock });
+const initialState = new State({
+  [tapeBlock.symbol(['a'])]: { command: [{ symbol: 'b', movement: movements.right }] },
+  [tapeBlock.symbol([' '])]: { nextState: haltState },
+});
+
+const snippet = recordSnippet({
+  machine,
+  initialState,
+  graph: State.toGraph(initialState, tapeBlock),
+  alphabets: [[' ', 'a', 'b']],
+  name: 'replace a with b',
+  log: (m) => formatStep(m),
+});
+
+// snippet.frames[0]    — initial state (no commands, highlight null)
+// snippet.frames[N]    — post-iter snapshot with per-tape commands { movement, read, write }
+//                        and a graph highlight ready to feed applyHighlight()
+// snippet.graph        — the same Graph the player should render
+// snippet.alphabets    — per-tape alphabet symbols (single-tape: length 1)
+```
+
+`Frame.commands` carries both `read` and `write` per tape so a player can step forward (write `write`, move per `movement`, flash if `write !== read`) AND backward (move opposite of `movement`, restore `read`) without diffing neighbouring frames.
+
+## Versioning
+
+Engine + builder + libraries bump in **lockstep** via `lerna version`. **Visuals breaks lockstep for additive consumer-package patches** (e.g., `7.0.0-alpha.6.1` added formatter primitives + the token surface without bumping the engine — there were no engine changes to justify ghost releases). Semver-prerelease caret semantics make this safe: peer `^7.0.0-alpha.6` accepts `7.0.0-alpha.6.1+` without consumers having to widen anything. When the next engine alpha needs to ship, all 5 packages bump back to lockstep.
+
+## License
+
+[GPL-3.0-or-later](../../LICENSE)

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.7",
   "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
   "engines": {
     "npm": ">=7.0.0"
@@ -25,7 +25,7 @@
     "visualization"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+    "@turing-machine-js/machine": "^7.0.0-alpha.7"
   },
   "scripts": {
     "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/visuals",
@@ -42,5 +42,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "7801a33fef2f6c30cf6e1c2780b1fbf58685f064"
+  "gitHead": "130d4fd8b964da21a408af2986295e8000828f78"
 }