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

package/src/fixtures/graphs/turing-callable-subtree.json

@@ -1,108 +0,0 @@
-{
-  "initialId": 5,
-  "alphabets": [
-    [
-      " ",
-      "a",
-      "b",
-      "*"
-    ]
-  ],
-  "nodes": {
-    "0": {
-      "id": 0,
-      "name": "id:0",
-      "isHalt": true,
-      "isHaltMarker": false,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": null,
-      "transitions": [],
-      "overriddenHaltStateId": null,
-      "tags": []
-    },
-    "3": {
-      "id": 3,
-      "name": "walkToBlank",
-      "isHalt": false,
-      "isHaltMarker": false,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": 3,
-      "transitions": [
-        {
-          "pattern": "B",
-          "command": [
-            {
-              "symbol": "K",
-              "movement": "S"
-            }
-          ],
-          "nextStateId": -3,
-          "id": "3.0"
-        },
-        {
-          "pattern": "*",
-          "command": [
-            {
-              "symbol": "K",
-              "movement": "R"
-            }
-          ],
-          "nextStateId": 3,
-          "id": "3.1"
-        }
-      ],
-      "overriddenHaltStateId": null,
-      "tags": []
-    },
-    "4": {
-      "id": 4,
-      "name": "writeMarker",
-      "isHalt": false,
-      "isHaltMarker": false,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": null,
-      "transitions": [
-        {
-          "pattern": "*",
-          "command": [
-            {
-              "symbol": "'*'",
-              "movement": "S"
-            }
-          ],
-          "nextStateId": 0,
-          "id": "4.0"
-        }
-      ],
-      "overriddenHaltStateId": null,
-      "tags": []
-    },
-    "5": {
-      "id": 5,
-      "name": "walkToBlank(writeMarker)",
-      "isHalt": false,
-      "isHaltMarker": false,
-      "isWrapper": true,
-      "bareStateId": 3,
-      "frameId": null,
-      "transitions": [],
-      "overriddenHaltStateId": 4,
-      "tags": []
-    },
-    "-3": {
-      "id": -3,
-      "name": "halt",
-      "isHalt": true,
-      "isHaltMarker": true,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": 3,
-      "transitions": [],
-      "overriddenHaltStateId": null,
-      "tags": []
-    }
-  }
-}

package/src/fixtures/graphs/turing-copy-two-tapes.json

@@ -1,87 +0,0 @@
-{
-  "initialId": 2,
-  "alphabets": [
-    [
-      "␣",
-      "a",
-      "b"
-    ],
-    [
-      "␣",
-      "a",
-      "b"
-    ]
-  ],
-  "nodes": {
-    "0": {
-      "id": 0,
-      "name": "id:0",
-      "isHalt": true,
-      "isHaltMarker": false,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": null,
-      "transitions": [],
-      "overriddenHaltStateId": null,
-      "tags": []
-    },
-    "2": {
-      "id": 2,
-      "name": "id:2",
-      "isHalt": false,
-      "isHaltMarker": false,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": null,
-      "transitions": [
-        {
-          "pattern": "'a',*",
-          "command": [
-            {
-              "symbol": "'a'",
-              "movement": "R"
-            },
-            {
-              "symbol": "'a'",
-              "movement": "R"
-            }
-          ],
-          "nextStateId": 2,
-          "id": "2.0"
-        },
-        {
-          "pattern": "'b',*",
-          "command": [
-            {
-              "symbol": "'b'",
-              "movement": "R"
-            },
-            {
-              "symbol": "'b'",
-              "movement": "R"
-            }
-          ],
-          "nextStateId": 2,
-          "id": "2.1"
-        },
-        {
-          "pattern": "B,*",
-          "command": [
-            {
-              "symbol": "K",
-              "movement": "S"
-            },
-            {
-              "symbol": "K",
-              "movement": "S"
-            }
-          ],
-          "nextStateId": 0,
-          "id": "2.2"
-        }
-      ],
-      "overriddenHaltStateId": null,
-      "tags": []
-    }
-  }
-}

package/src/fixtures/graphs/turing-replace-b.json

@@ -1,72 +0,0 @@
-{
-  "initialId": 1,
-  "alphabets": [
-    [
-      "␣",
-      "a",
-      "b",
-      "c",
-      "*"
-    ]
-  ],
-  "nodes": {
-    "0": {
-      "id": 0,
-      "name": "id:0",
-      "isHalt": true,
-      "isHaltMarker": false,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": null,
-      "transitions": [],
-      "overriddenHaltStateId": null,
-      "tags": []
-    },
-    "1": {
-      "id": 1,
-      "name": "id:1",
-      "isHalt": false,
-      "isHaltMarker": false,
-      "isWrapper": false,
-      "bareStateId": null,
-      "frameId": null,
-      "transitions": [
-        {
-          "pattern": "'b'",
-          "command": [
-            {
-              "symbol": "'*'",
-              "movement": "R"
-            }
-          ],
-          "nextStateId": 1,
-          "id": "1.0"
-        },
-        {
-          "pattern": "B",
-          "command": [
-            {
-              "symbol": "K",
-              "movement": "L"
-            }
-          ],
-          "nextStateId": 0,
-          "id": "1.1"
-        },
-        {
-          "pattern": "*",
-          "command": [
-            {
-              "symbol": "K",
-              "movement": "R"
-            }
-          ],
-          "nextStateId": 1,
-          "id": "1.2"
-        }
-      ],
-      "overriddenHaltStateId": null,
-      "tags": []
-    }
-  }
-}

package/src/format.spec.ts

@@ -1,100 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  Alphabet,
-  Tape,
-  TapeBlock,
-  TapeCommand,
-  TuringMachine,
-  State,
-  haltState,
-  movements,
-  symbolCommands,
-} from '@turing-machine-js/machine';
-import { formatCommand, formatStep } from './format';
-
-describe('formatCommand', () => {
-  it('formats a literal symbol write + right move', () => {
-    const tc = new TapeCommand({ symbol: 'X', movement: movements.right });
-    expect(formatCommand(tc)).toBe("'X'/R");
-  });
-
-  it('formats keep + stay as K/S', () => {
-    const tc = new TapeCommand({ movement: movements.stay });
-    // default symbol is symbolCommands.keep
-    expect(formatCommand(tc)).toBe('K/S');
-  });
-
-  it('formats erase + left as E/L', () => {
-    const tc = new TapeCommand({ symbol: symbolCommands.erase, movement: movements.left });
-    expect(formatCommand(tc)).toBe('E/L');
-  });
-
-  it('formats keep + right as K/R', () => {
-    const tc = new TapeCommand({ symbol: symbolCommands.keep, movement: movements.right });
-    expect(formatCommand(tc)).toBe('K/R');
-  });
-
-  it('formats a literal symbol write + left move', () => {
-    const tc = new TapeCommand({ symbol: 'a', movement: movements.left });
-    expect(formatCommand(tc)).toBe("'a'/L");
-  });
-});
-
-describe('formatStep', () => {
-  it("formats a single-tape iter: 'a' → 'b'/R", () => {
-    const alphabet = new Alphabet([' ', 'a', 'b']);
-    const tape = new Tape({ alphabet, symbols: ['a'] });
-    const tapeBlock = TapeBlock.fromTapes([tape]);
-    const machine = new TuringMachine({ tapeBlock });
-    const initialState = new State({
-      [tapeBlock.symbol(['a'])]: {
-        command: [{ symbol: 'b', movement: movements.right }],
-        nextState: haltState,
-      },
-    });
-    const gen = machine.runStepByStep({ initialState });
-    const m = gen.next().value!;
-
-    expect(formatStep(m)).toBe("['a'] → ['b']/[R]");
-  });
-
-  it('encodes keep as K when nextSymbol equals currentSymbol', () => {
-    const alphabet = new Alphabet([' ', 'a', 'b']);
-    const tape = new Tape({ alphabet, symbols: ['a'] });
-    const tapeBlock = TapeBlock.fromTapes([tape]);
-    const machine = new TuringMachine({ tapeBlock });
-    const initialState = new State({
-      [tapeBlock.symbol(['a'])]: {
-        command: [{ symbol: symbolCommands.keep, movement: movements.stay }],
-        nextState: haltState,
-      },
-    });
-    const gen = machine.runStepByStep({ initialState });
-    const m = gen.next().value!;
-
-    // keep → nextSymbols[0] === currentSymbols[0], so write cell is K
-    expect(formatStep(m)).toBe("['a'] → [K]/[S]");
-  });
-
-  it('formats a 2-tape iter with comma-separated entries', () => {
-    const alphabetA = new Alphabet([' ', 'a', 'b']);
-    const alphabetB = new Alphabet([' ', 'x', 'y']);
-    const tape1 = new Tape({ alphabet: alphabetA, symbols: ['a'] });
-    const tape2 = new Tape({ alphabet: alphabetB, symbols: ['x'] });
-    const tapeBlock = TapeBlock.fromTapes([tape1, tape2]);
-    const machine = new TuringMachine({ tapeBlock });
-    const initialState = new State({
-      [tapeBlock.symbol(['a', 'x'])]: {
-        command: [
-          { symbol: 'b', movement: movements.right },
-          { symbol: symbolCommands.keep, movement: movements.left },
-        ],
-        nextState: haltState,
-      },
-    });
-    const gen = machine.runStepByStep({ initialState });
-    const m = gen.next().value!;
-
-    expect(formatStep(m)).toBe("['a','x'] → ['b',K]/[R,L]");
-  });
-});

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];
-}