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

package/src/format.ts

@@ -1,51 +0,0 @@
-import { movements, symbolCommands, type MachineState, type TapeCommand } from '@turing-machine-js/machine';
-
-export const MOVEMENT_LETTER = new Map<symbol, 'L' | 'R' | 'S'>([
-  [movements.left, 'L'],
-  [movements.right, 'R'],
-  [movements.stay, 'S'],
-]);
-
-/**
- * Render a single tape command in `WRITE/MOVE` form.
- * - Write: `'X'` (literal symbol) | `K` (keep) | `E` (erase = write blank).
- * - Move: `L` / `R` / `S` from `movements.*`.
- *
- * Matches the engine's edge-label vocabulary so formatted commands line up
- * with the write/move cells in `toMermaid`-emitted edge labels.
- */
-export function formatCommand(tapeCommand: TapeCommand): string {
-  let write: string;
-
-  if (tapeCommand.symbol === symbolCommands.keep) {
-    write = 'K';
-  } else if (tapeCommand.symbol === symbolCommands.erase) {
-    write = 'E';
-  } else {
-    write = `'${tapeCommand.symbol as string}'`;
-  }
-
-  const move = MOVEMENT_LETTER.get(tapeCommand.movement) ?? '?';
-
-  return `${write}/${move}`;
-}
-
-/**
- * Render one step's edge-label notation: `[reads] → [writes]/[moves]`.
- * Each role is wrapped in a single `[…]`; multi-tape entries are
- * comma-separated inside the brackets.
- *
- * Matches the engine's `toMermaid` emit so logged steps line up with
- * graph edge labels. Note: `nextSymbols` in `MachineState` is already
- * resolved (keep → current symbol, erase → blank) — `K` is inferred
- * by comparing `nextSymbols[i] === currentSymbols[i]`.
- */
-export function formatStep(m: MachineState): string {
-  const reads = m.currentSymbols.map((s) => `'${s}'`).join(',');
-  const writes = m.nextSymbols
-    .map((s, i) => (s === m.currentSymbols[i] ? 'K' : `'${s}'`))
-    .join(',');
-  const moves = m.movements.map((mv) => MOVEMENT_LETTER.get(mv) ?? '?').join(',');
-
-  return `[${reads}] → [${writes}]/[${moves}]`;
-}

package/src/graphIndexes.ts

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

package/src/graphUtils.spec.ts

@@ -1,112 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { bareIdOf, equivalentIds, highlightExpand } from './graphUtils';
-import type { Graph } from '@turing-machine-js/machine';
-
-/**
- * Tests for the pure breakpoint / highlight class helpers in
- * `graphUtils.ts`. These rules feed both the breakpoint indicator
- * (`applyIndicator`) and the context-menu "Shared with" info line
- * (`MachineGraph.svelte`); the upstream engine v7 collapses wrapper
- * states (`State.withOverriddenHaltState`) onto a shared `#debugRef`
- * with their bare, so the demo collapses them into one breakpoint per
- * equivalence class.
- *
- * Fixture: `turing-callable-subtree` has
- *   3  → bare `walkToBlank` (frameId 3)
- *   4  → `writeMarker` (override)
- *   5  → wrapper `walkToBlank(writeMarker)` (bareStateId 3)
- *   0  → halt singleton
- *   -3 → halt marker for frame 3
- */
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-function loadGraph(name: string): Graph {
-  const path = resolve(__dirname, './fixtures/graphs', `${name}.json`);
-  return JSON.parse(readFileSync(path, 'utf8')) as Graph;
-}
-
-describe('bareIdOf', () => {
-  const g = loadGraph('turing-callable-subtree');
-
-  it('maps a wrapper id to its bareStateId', () => {
-    expect(bareIdOf(5, g)).toBe(3);
-  });
-
-  it('returns the bare id unchanged for non-wrapper positive ids', () => {
-    expect(bareIdOf(3, g)).toBe(3);
-    expect(bareIdOf(4, g)).toBe(4);
-  });
-
-  it('collapses halt markers (negative ids) to the halt singleton (0)', () => {
-    expect(bareIdOf(-3, g)).toBe(0);
-  });
-
-  it('returns 0 for the halt singleton itself', () => {
-    expect(bareIdOf(0, g)).toBe(0);
-  });
-
-  it('returns the id unchanged when graph is null', () => {
-    expect(bareIdOf(5, null)).toBe(5);
-    expect(bareIdOf(-3, null)).toBe(-3);
-  });
-
-  it('returns the id unchanged when no node entry exists', () => {
-    expect(bareIdOf(999, g)).toBe(999);
-  });
-});
-
-describe('highlightExpand (asymmetric)', () => {
-  const g = loadGraph('turing-callable-subtree');
-
-  it('expands wrapper → [wrapper, bare]', () => {
-    expect(highlightExpand(5, g).sort()).toEqual([3, 5]);
-  });
-
-  it('does NOT expand bare → [bare] only (no wrapper sync from bare side)', () => {
-    expect(highlightExpand(3, g)).toEqual([3]);
-  });
-
-  it('returns [id] for a non-wrapper non-bare id', () => {
-    expect(highlightExpand(4, g)).toEqual([4]);
-  });
-
-  it('returns [id] when graph is null', () => {
-    expect(highlightExpand(5, null)).toEqual([5]);
-  });
-});
-
-describe('equivalentIds (symmetric class lookup)', () => {
-  const g = loadGraph('turing-callable-subtree');
-
-  it('returns [bare, ...wrappers] from a wrapper input', () => {
-    expect(equivalentIds(5, g).sort()).toEqual([3, 5]);
-  });
-
-  it('returns [bare, ...wrappers] from the bare input — symmetric', () => {
-    expect(equivalentIds(3, g).sort()).toEqual([3, 5]);
-  });
-
-  it('returns [singleton] for a stand-alone state', () => {
-    expect(equivalentIds(4, g)).toEqual([4]);
-  });
-
-  it('halt singleton (0) → [0, ...all halt markers]', () => {
-    const ids = equivalentIds(0, g).sort((a, b) => a - b);
-    expect(ids).toEqual([-3, 0]);
-  });
-
-  it('halt marker (-3) → same class as halt singleton (symmetric)', () => {
-    const ids = equivalentIds(-3, g).sort((a, b) => a - b);
-    expect(ids).toEqual([-3, 0]);
-  });
-
-  it('returns [id] when graph is null', () => {
-    expect(equivalentIds(5, null)).toEqual([5]);
-    expect(equivalentIds(0, null)).toEqual([0]);
-  });
-});

package/src/graphUtils.ts

@@ -1,74 +0,0 @@
-import type { Graph } from '@turing-machine-js/machine';
-
-/**
- * Normalize an engine `GraphNode.id` to its canonical representative for
- * breakpoint-class lookups (machines-demo#37). Wrappers produced by
- * `State.withOverriddenHaltState` share `#debugRef` with their bare state
- * engine-side (turing-machine-js v7 `State.ts`: `state.#debugRef =
- * bare.#debugRef`), so they form a single breakpoint from the user's POV.
- * This collapses any wrapper id to its bare's id; non-wrapper ids return
- * self. Used so the demo can store ONE canonical id per equivalence class
- * in its breakpoint set, and expand to all class members for indicator
- * rendering — keeping the worker-side toggle count to one per class
- * (multiple toggles on the shared ref would double-flip).
- */
-export function bareIdOf(id: number, graph: Graph | null): number {
-  if (!graph) return id;
-  // Halt markers (negative ids, one per frame) are visualization sentinels;
-  // at runtime they all collapse to the haltState singleton (id 0). For
-  // breakpoint purposes they're a single class — setting BP on any
-  // halt-related node sets it on the global haltState.
-  if (id < 0) return 0;
-  const node = graph.nodes[id];
-  if (node && node.isWrapper && node.bareStateId !== null) {
-    return node.bareStateId;
-  }
-  return id;
-}
-
-/**
- * Asymmetric expansion for the highlight effect (machines-demo#37).
- * Wrapper → `[wrapper, bare]` (the wrapper-entry pause is visually joined
- * to its bare, since the user thinks of them as one call site).
- * Bare → `[bare]` only (when the engine is genuinely on the bare — e.g. a
- * loop iter — the wrapper is not the "active" state and shouldn't get the
- * strong highlight).
- * Non-wrapper / non-bare ids return `[id]`.
- */
-export function highlightExpand(id: number, graph: Graph | null): number[] {
-  if (!graph) return [id];
-  const node = graph.nodes[id];
-  if (node?.isWrapper && node.bareStateId !== null) {
-    return [id, node.bareStateId];
-  }
-  return [id];
-}
-
-/**
- * All GraphNode ids in the same breakpoint equivalence class as `id`.
- * Symmetric — gives consumers the full list of nodes that share an engine
- * breakpoint, regardless of which class member is the input. Used by the
- * context-menu's "Shared with" info line so the user can see at a glance
- * which other nodes flip together.
- *
- * Halt class (canonical id 0): the halt singleton + every halt marker in
- * the graph. Wrapper/bare class: the bare + every wrapper pointing at it.
- * Singleton classes (regular states, idle sentinel proxies) return just
- * the input id.
- */
-export function equivalentIds(id: number, graph: Graph | null): number[] {
-  if (!graph) return [id];
-  const canonical = bareIdOf(id, graph);
-  if (canonical === 0) {
-    const ids: number[] = [0];
-    for (const node of Object.values(graph.nodes)) {
-      if (node.isHaltMarker) ids.push(node.id);
-    }
-    return ids;
-  }
-  const result = new Set<number>([canonical]);
-  for (const node of Object.values(graph.nodes)) {
-    if (node.isWrapper && node.bareStateId === canonical) result.add(node.id);
-  }
-  return [...result];
-}

package/src/highlightOps.ts

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

package/src/index.ts

@@ -1,10 +0,0 @@
-// Public API — extracted modules + Snippet recording surface.
-export type { NodeKey, HighlightClass, HighlightOps, IndicatorOps, RecordedOp } from './highlightOps';
-export { recordingOps } from './highlightOps';
-export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
-export type { GraphIndexes } from './graphIndexes';
-export { indexGraph } from './graphIndexes';
-export type { GraphHighlight, TapeSnapshot, Frame, Snippet } from './types';
-export { applyHighlight, applyIndicator } from './applyHighlight';
-export { formatCommand, formatStep } from './format';
-export { recordSnippet, type RecordSnippetOptions } from './recordSnippet';