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

package/dist/graphIndexes.js

@@ -1,58 +0,0 @@
-/**
- * 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) {
-    const nodeFrameMap = new Map();
-    const frameWrappersMap = new Map();
-    const frameLabelToId = new Map();
-    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();
-    for (const n of Object.values(graph.nodes)) {
-        if (n.isWrapper && n.bareStateId !== null)
-            bareIds.add(n.bareStateId);
-    }
-    const frameToBareNames = new Map();
-    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/dist/graphUtils.js

@@ -1,76 +0,0 @@
-/**
- * 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, graph) {
-    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, graph) {
-    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, graph) {
-    if (!graph)
-        return [id];
-    const canonical = bareIdOf(id, graph);
-    if (canonical === 0) {
-        const ids = [0];
-        for (const node of Object.values(graph.nodes)) {
-            if (node.isHaltMarker)
-                ids.push(node.id);
-        }
-        return ids;
-    }
-    const result = new Set([canonical]);
-    for (const node of Object.values(graph.nodes)) {
-        if (node.isWrapper && node.bareStateId === canonical)
-            result.add(node.id);
-    }
-    return [...result];
-}

package/dist/highlightOps.js

@@ -1,36 +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.
- */
-/**
- * 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() {
-    const record = [];
-    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/dist/index.js

@@ -1,6 +0,0 @@
-export { recordingOps } from './highlightOps';
-export { bareIdOf, highlightExpand, equivalentIds } from './graphUtils';
-export { indexGraph } from './graphIndexes';
-export { applyHighlight, applyIndicator } from './applyHighlight';
-export { formatCommand, formatStep } from './format';
-export { recordSnippet } from './recordSnippet';

package/dist/recordSnippet.js

@@ -1,92 +0,0 @@
-import { haltState, } from '@turing-machine-js/machine';
-import { MOVEMENT_LETTER } from './format';
-import { bareIdOf } from './graphUtils';
-const DEFAULT_MAX_STEPS = 1000;
-function snapshotTapes(machine) {
-    return machine.tapeBlock.tapes.map((t) => ({
-        symbols: [...t.symbols],
-        position: t.position,
-    }));
-}
-function deriveCommands(m) {
-    return m.movements.map((mv, i) => ({
-        movement: MOVEMENT_LETTER.get(mv) ?? 'S',
-        read: m.currentSymbols[i],
-        // nextSymbols is already resolved (keep → current symbol, erase → blank);
-        // when write === read the command was a keep (UI suppresses the flash).
-        write: m.nextSymbols[i],
-    }));
-}
-function deriveHighlight(m, graph) {
-    return {
-        fromId: bareIdOf(m.state.id, graph),
-        toId: m.nextState === haltState ? 0 : m.nextState.id,
-        strong: 'from',
-        paused: false,
-    };
-}
-/**
- * Record a full machine run into a `Snippet` — a self-contained playback
- * artifact suitable for embeds, articles, or landing-page panels.
- *
- * The returned snippet contains one frame per iteration plus a frame-0
- * initial-state snapshot. Recording stops when the machine halts or when
- * `maxSteps` iterations have been consumed (default 1000).
- *
- * Tape-timing note: `runStepByStep` yields BEFORE applying its command
- * (the command is applied after the yield resumes). The recorder uses a
- * one-step-delayed snapshot so each frame's `tape` reflects the
- * post-command state for that frame's iter.
- */
-export function recordSnippet(opts) {
-    const { machine, initialState, graph, alphabets, name, maxSteps = DEFAULT_MAX_STEPS, log, } = opts;
-    const frames = [
-        { step: 0, tape: snapshotTapes(machine), highlight: null },
-    ];
-    // pending holds everything for the frame whose tape snapshot is not yet
-    // available (because applyCommand hasn't fired yet). It is flushed at the
-    // start of the NEXT iter (when the tape reflects the previous command) and
-    // after the loop (when the final command has been applied).
-    let pending = null;
-    let prev = null;
-    try {
-        for (const m of machine.runStepByStep({ initialState, stepsLimit: maxSteps })) {
-            // At this point applyCommand for the PREVIOUS iter has already run
-            // (the generator called applyCommand before looping back to yield).
-            // So the current tape state = post-command of the previous iter.
-            if (pending !== null) {
-                frames.push({ ...pending, tape: snapshotTapes(machine) });
-            }
-            const commands = deriveCommands(m);
-            const highlight = deriveHighlight(m, graph);
-            const logLine = log ? log(m, prev) : undefined;
-            pending = {
-                step: m.step,
-                commands,
-                highlight,
-                ...(logLine !== undefined ? { log: logLine } : {}),
-            };
-            prev = m;
-        }
-    }
-    catch (e) {
-        // runStepByStep throws 'Long execution' when stepsLimit is hit.
-        // At that point applyCommand for the last yielded iter has run, so the
-        // tape is in the post-command state we want for the pending frame.
-        if (!(e instanceof Error) || e.message !== 'Long execution') {
-            throw e;
-        }
-    }
-    // Flush the last pending frame. After the loop (or after the catch), the
-    // tape reflects the post-command state of the final yielded iter.
-    if (pending !== null) {
-        frames.push({ ...pending, tape: snapshotTapes(machine) });
-    }
-    return {
-        version: 1,
-        ...(name !== undefined ? { name } : {}),
-        graph,
-        alphabets,
-        frames,
-    };
-}

package/dist/types.js

@@ -1 +0,0 @@
-export {};

package/src/applyHighlight.spec.ts

@@ -1,331 +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 { applyHighlight, applyIndicator } from './applyHighlight';
-import { indexGraph } from './graphIndexes';
-import { recordingOps, type RecordedOp } from './highlightOps';
-import type { GraphHighlight } from './types';
-import type { Graph } from '@turing-machine-js/machine';
-
-/**
- * Rule tests for `applyHighlight`. Section numbers mirror
- * `docs/graph-highlight-and-breakpoints.md` — any rule change must
- * update both the doc and the matching `describe` block here.
- *
- * Fixtures come from `tests/fixtures/graphs/`, which are committed
- * snapshots of `State.toGraph` output for each bundled example
- * (regenerable via `REGEN_FIXTURES=1 npm test`). Using real engine output
- * means these tests also catch any drift between engine emit and
- * rule expectations.
- *
- * Helpful fixture ids for `turing-callable-subtree`:
- *   bare walkToBlank             = 3   (frameId 3)
- *   writeMarker (override)       = 4
- *   wrapper walkToBlank(writeMarker) = 5  (bareStateId 3, overriddenHaltStateId 4)
- *   halt singleton               = 0
- *   frame halt marker            = -3  (id = -frameId)
- */
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const FIXTURE_DIR = resolve(__dirname, './fixtures/graphs');
-
-function loadGraph(name: string): Graph {
-  return JSON.parse(readFileSync(resolve(FIXTURE_DIR, `${name}.json`), 'utf-8'));
-}
-
-/** Run `applyHighlight` with a recording ops impl, return the ordered ops list. */
-function run(highlight: GraphHighlight | null, graph: Graph, prev: number | 'idle' | null = null): {
-  ops: RecordedOp[];
-  next: number | 'idle' | null;
-} {
-  const indexes = indexGraph(graph);
-  const { highlight: opsImpl, record } = recordingOps();
-  const { nextPrevStrongId } = applyHighlight(highlight, graph, indexes, prev, opsImpl);
-  return { ops: record, next: nextPrevStrongId };
-}
-
-describe('applyHighlight', () => {
-  describe('null/empty highlight', () => {
-    it('returns no-op with nextPrev=null when highlight is null', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { ops, next } = run(null, g, 3);
-      expect(ops).toEqual([]);
-      expect(next).toBeNull();
-    });
-  });
-
-  describe('§5 halt-target retargeting', () => {
-    it('rewrites toId=0 to -frameId when fromId is in a frame', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // Bare walkToBlank (id 3, frameId 3) halts → engine reports toId=0,
-      // should retarget to -3 (frame halt marker).
-      const { ops } = run({ fromId: 3, toId: 0, strong: 'from', paused: false }, g);
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      // halt marker -3 gets highlight-to; halt singleton 0 does not.
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: -3, cls: 'mg-highlight-to' });
-      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-to' });
-    });
-
-    it('does NOT retarget when fromId is outside any frame', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // writeMarker (id 4) is the wrapper's override-target; sits outside
-      // the frame (frameId: null), so its halt→halt-singleton stays as id 0.
-      const { ops } = run({ fromId: 4, toId: 0, strong: 'from', paused: false }, g);
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-to' });
-    });
-  });
-
-  describe('§2 + §3 wrapper/bare equivalence (asymmetric)', () => {
-    it('wrapper-strong expands to [wrapper, bare] — both get highlight-to + strong', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // Wrapper-entry pause: idle → wrapper(5), pauseBefore strong=to.
-      const { ops } = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g);
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-strong' });
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-to' });
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-strong' });
-    });
-
-    it('bare-strong stays bare only — does NOT light up wrapper', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // Bare-loop pause: prev=bare(3), to=bare(3), pauseBefore strong=to.
-      const { ops } = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g);
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-to' });
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 3, cls: 'mg-highlight-strong' });
-      // Wrapper 5 gets NOTHING from the to-side expansion.
-      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
-      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-strong' });
-    });
-  });
-
-  describe('§6 source return chain (toId < 0)', () => {
-    it('lights up return arrow + wrapper + override edge + override target', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // Just-fired halt-bound transition: from=bare(3), to=halt-marker(-3),
-      // strong=from (pause-after-style).
-      const { ops } = run({ fromId: 3, toId: -3, strong: 'from', paused: true }, g);
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
-      // Return arrow w_3 → wrapper(5).
-      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 'w_3', toKey: 's5' });
-      // Wrapper gets highlight-to.
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
-      // Wrapper → override edge.
-      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's4' });
-      // Override (writeMarker) gets highlight-to.
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 4, cls: 'mg-highlight-to' });
-    });
-  });
-
-  describe('§7 destination return chain (paused at override after pop)', () => {
-    it('lights the full path bare → halt-marker → return → wrapper → override + frame', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // Paused-before writeMarker: prev=bare(3) (last yield was bare's halt),
-      // current=writeMarker(4). strong=to. Bare is in frame 3; wrapper 5's
-      // override is 4 → matches.
-      const { ops } = run({ fromId: 3, toId: 4, strong: 'to', paused: true }, g);
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
-      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
-
-      // Halt marker lit.
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: -3, cls: 'mg-highlight-to' });
-      // bare → halt-marker edge.
-      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's3', toKey: 'c3' });
-      // Return arrow.
-      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 'w_3', toKey: 's5' });
-      // Wrapper highlight-to.
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 5, cls: 'mg-highlight-to' });
-      // Wrapper → override edge.
-      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's4' });
-      // Frame active (override sits outside frame, but the chain fired so
-      // we still mark the frame to show "we came out of THIS subtree").
-      expect(frameOps).toContainEqual({ op: 'markFrameActive', frameId: 3 });
-    });
-
-    it('does NOT fire when fromId is not in any frame', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // From idle → writeMarker(4): no frame on the from side, no chain.
-      const { ops } = run({ fromId: 'idle', toId: 4, strong: 'to', paused: true }, g);
-      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
-      expect(edgeOps).not.toContainEqual({ op: 'highlightEdge', fromKey: 's3', toKey: 'c3' });
-      expect(edgeOps).not.toContainEqual({ op: 'highlightEdge', fromKey: 'w_3', toKey: 's5' });
-    });
-  });
-
-  describe('§8 halt singleton (toId === 0, no retarget)', () => {
-    it('marks the halt singleton with highlight-to + strong', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // writeMarker (id 4, no frame) → halt singleton (0). strong=from
-      // (pause-after applying writeMarker's command).
-      const { ops } = run({ fromId: 4, toId: 0, strong: 'from', paused: true }, g);
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-to' });
-      // strong is 'from', so halt singleton is not strong.
-      expect(classOps).not.toContainEqual({ op: 'addNodeClass', id: 0, cls: 'mg-highlight-strong' });
-    });
-  });
-
-  describe('§9 frame-active', () => {
-    it('marks the frame when canonical strong is inside it (wrapper case)', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // Wrapper-entry pause: strong=wrapper(5). bareIdOf(5)=3. nodeFrameMap[3]=3.
-      const { ops } = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g);
-      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
-      expect(frameOps).toContainEqual({ op: 'markFrameActive', frameId: 3 });
-    });
-
-    it('marks the frame when bare is strong', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { ops } = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g);
-      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
-      expect(frameOps).toContainEqual({ op: 'markFrameActive', frameId: 3 });
-    });
-
-    it('does NOT mark a frame when strong is outside any frame', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // writeMarker (4, no frame) is strong.
-      const { ops } = run({ fromId: 4, toId: 0, strong: 'from', paused: true }, g);
-      const frameOps = ops.filter((o) => o.op === 'markFrameActive');
-      expect(frameOps).toEqual([]);
-    });
-  });
-
-  describe('§10 wrapper-entry call edge', () => {
-    it('highlights the wrapper → bare call edge when to-side expanded to both', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { ops } = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g);
-      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
-      expect(edgeOps).toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's3' });
-    });
-
-    it('does NOT highlight a call edge when to-side is bare only', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { ops } = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g);
-      const edgeOps = ops.filter((o) => o.op === 'highlightEdge');
-      // No s5→s3 call edge (bare doesn't expand to include wrapper).
-      expect(edgeOps).not.toContainEqual({ op: 'highlightEdge', fromKey: 's5', toKey: 's3' });
-    });
-  });
-
-  describe('§11 pause-revisit pulse (raw, not canonical)', () => {
-    it('does NOT pulse on wrapper-pause → bare-pause transition', () => {
-      const g = loadGraph('turing-callable-subtree');
-      // First pause: wrapper-entry. prev=null → no pulse. nextPrev=5 (wrapper).
-      const r1 = run({ fromId: 'idle', toId: 5, strong: 'to', paused: true }, g, null);
-      expect(r1.ops.find((o) => o.op === 'pulse')).toBeUndefined();
-      expect(r1.next).toBe(5);
-      // Second pause: bare loop iter. prev=5 (wrapper), strong=3 (bare).
-      // 5 !== 3 → NO pulse, even though they share #debugRef.
-      const r2 = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g, r1.next);
-      expect(r2.ops.find((o) => o.op === 'pulse')).toBeUndefined();
-      expect(r2.next).toBe(3);
-    });
-
-    it('pulses on same-state revisit (bare → bare)', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const r1 = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g, null);
-      expect(r1.ops.find((o) => o.op === 'pulse')).toBeUndefined();
-      const r2 = run({ fromId: 3, toId: 3, strong: 'to', paused: true }, g, r1.next);
-      expect(r2.ops).toContainEqual({ op: 'pulse', id: 3 });
-    });
-
-    it('does NOT update prev on non-paused (idle / RUNNING_AUTO) events', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const r = run({ fromId: 3, toId: 3, strong: 'from', paused: false }, g, 5);
-      expect(r.next).toBe(5); // unchanged
-    });
-
-    it('resets prev to null on null highlight', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const r = run(null, g, 3);
-      expect(r.next).toBeNull();
-    });
-  });
-
-  describe('scroll-into-view', () => {
-    it('scrolls to the strong node', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { ops } = run({ fromId: 3, toId: 4, strong: 'to', paused: true }, g);
-      expect(ops).toContainEqual({ op: 'scrollIntoView', id: 4 });
-    });
-
-    it('does not scroll when strong is null (no highlight)', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { ops } = run(null, g);
-      expect(ops.find((o) => o.op === 'scrollIntoView')).toBeUndefined();
-    });
-  });
-
-  describe('applyIndicator (§2 canonical breakpoint + §3 indicator class)', () => {
-    it('marks every member of the equivalence class when canonical id is in set', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { indicator, record } = recordingOps();
-      // BP set has the bare id (3). Both wrapper (5) and bare (3) should turn on.
-      applyIndicator(new Set([3]), g, [3, 4, 5, -3, 0, 'idle'], indicator);
-      const onIds = record
-        .filter((r): r is Extract<RecordedOp, { op: 'setBreakpoint' }> => r.op === 'setBreakpoint' && r.on)
-        .map((r) => r.id);
-      expect(onIds).toContain(3);
-      expect(onIds).toContain(5);
-      // writeMarker (4), halt-marker (-3), halt (0), idle: never on.
-      expect(onIds).not.toContain(4);
-      expect(onIds).not.toContain(-3);
-      expect(onIds).not.toContain(0);
-      expect(onIds).not.toContain('idle');
-    });
-
-    it('clears every node when the set is empty', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { indicator, record } = recordingOps();
-      applyIndicator(new Set(), g, [3, 4, 5, 'idle'], indicator);
-      const onCount = record.filter((r) => r.op === 'setBreakpoint' && r.on).length;
-      expect(onCount).toBe(0);
-      // Every node still gets an explicit off call (idempotent clears).
-      expect(record.length).toBe(4);
-    });
-
-    // machines-demo#37 — halt singleton (id 0) is a valid breakpoint
-    // target (engine-wide haltState). The set stores canonical id 0;
-    // both the halt singleton AND every halt marker (negative ids; one
-    // per frame) collapse to that class via `bareIdOf(-N, g) === 0`.
-    it('marks halt singleton AND every halt marker when 0 is in the set', () => {
-      const g = loadGraph('turing-callable-subtree');
-      const { indicator, record } = recordingOps();
-      applyIndicator(new Set([0]), g, [3, 4, 5, -3, 0, 'idle'], indicator);
-      const onIds = record
-        .filter((r): r is Extract<RecordedOp, { op: 'setBreakpoint' }> => r.op === 'setBreakpoint' && r.on)
-        .map((r) => r.id);
-      expect(onIds).toContain(0); // halt singleton
-      expect(onIds).toContain(-3); // halt marker for frame 3
-      // Regular and wrapper / bare nodes: never on.
-      expect(onIds).not.toContain(3);
-      expect(onIds).not.toContain(4);
-      expect(onIds).not.toContain(5);
-      expect(onIds).not.toContain('idle');
-    });
-  });
-
-  describe('regression: simple machines (no callable subtree)', () => {
-    it('lights from + to + strong + edge for a plain RUNNING_AUTO tick', () => {
-      const g = loadGraph('turing-replace-b');
-      // Pick any two ids that have a transition between them.
-      const nodes = Object.values(g.nodes).filter((n) => !n.isHalt && !n.isHaltMarker);
-      const src = nodes.find((n) => n.transitions.length > 0)!;
-      const transition = src.transitions[0];
-      const dst = transition.nextStateId;
-      const { ops } = run(
-        { fromId: src.id, toId: dst, strong: 'from', paused: false },
-        g,
-      );
-      const classOps = ops.filter((o) => o.op === 'addNodeClass');
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: src.id, cls: 'mg-highlight-from' });
-      expect(classOps).toContainEqual({ op: 'addNodeClass', id: src.id, cls: 'mg-highlight-strong' });
-    });
-  });
-});