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

package/README.md

@@ -0,0 +1,21 @@
+# @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.
+
+## Scope
+
+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`.
+
+## Install
+
+```sh
+npm install @turing-machine-js/visuals @turing-machine-js/machine
+```

package/dist/applyHighlight.d.ts

@@ -0,0 +1,42 @@
+import type { GraphHighlight } from './types';
+import type { Graph } from '@turing-machine-js/machine';
+import type { GraphIndexes } from './graphIndexes';
+import type { HighlightOps, IndicatorOps, NodeKey } from './highlightOps';
+/**
+ * Pure highlight-rule evaluator. Given the current `highlight` (from
+ * `MachineView`'s `$derived`), the engine `graph`, derived `indexes`,
+ * and the previous strong-id (for pause-revisit pulse detection), emit
+ * a sequence of `ops` calls describing the resulting visual state.
+ *
+ * Strictly additive — the caller is expected to clear previously-applied
+ * highlight classes / edge marks / cluster activations BEFORE invoking
+ * this function. The function never reads back from the consumer.
+ *
+ * Returns the new prev-strong-id to thread into the next call. Pulse
+ * comparison uses the RAW strong id (not canonical), so wrapper-pause
+ * and bare-pause register as different positions and don't pulse each
+ * other. Updates only when `highlight.paused === true`; non-paused
+ * events (idle / RUNNING_AUTO ticks) leave it untouched. Null highlight
+ * resets it to null.
+ *
+ * See `docs/graph-highlight-and-breakpoints.md` for the 16 rules
+ * enumerated.
+ */
+export declare function applyHighlight(highlight: GraphHighlight | null, graph: Graph | null, indexes: GraphIndexes, prevStrongId: NodeKey | null, ops: HighlightOps): {
+    nextPrevStrongId: NodeKey | null;
+};
+/**
+ * Pure breakpoint-indicator rule evaluator. For each cached node key,
+ * emit `ops.setBreakpoint(key, on)` reflecting whether the node's
+ * canonical bare-id is in the `breakpoints` set.
+ *
+ * The 'idle' string sentinel never carries a breakpoint. All numeric
+ * keys are valid BP-class members:
+ *   - positive id   → regular state; canonical via bareIdOf (wrappers
+ *                     collapse to bare)
+ *   - 0             → haltState singleton (engine-wide; canonical = 0)
+ *   - negative id   → halt marker (per-frame visualization sentinel;
+ *                     bareIdOf maps to 0 — same class as the singleton)
+ * Consumers pass their iterable of cached node keys (e.g. `nodeCache.keys()`).
+ */
+export declare function applyIndicator(breakpoints: ReadonlySet<number>, graph: Graph | null, nodeIds: Iterable<NodeKey>, ops: IndicatorOps): void;

package/dist/applyHighlight.js

@@ -0,0 +1,191 @@
+import { bareIdOf, highlightExpand } from './graphUtils';
+/**
+ * Pure highlight-rule evaluator. Given the current `highlight` (from
+ * `MachineView`'s `$derived`), the engine `graph`, derived `indexes`,
+ * and the previous strong-id (for pause-revisit pulse detection), emit
+ * a sequence of `ops` calls describing the resulting visual state.
+ *
+ * Strictly additive — the caller is expected to clear previously-applied
+ * highlight classes / edge marks / cluster activations BEFORE invoking
+ * this function. The function never reads back from the consumer.
+ *
+ * Returns the new prev-strong-id to thread into the next call. Pulse
+ * comparison uses the RAW strong id (not canonical), so wrapper-pause
+ * and bare-pause register as different positions and don't pulse each
+ * other. Updates only when `highlight.paused === true`; non-paused
+ * events (idle / RUNNING_AUTO ticks) leave it untouched. Null highlight
+ * resets it to null.
+ *
+ * See `docs/graph-highlight-and-breakpoints.md` for the 16 rules
+ * enumerated.
+ */
+export function applyHighlight(highlight, graph, indexes, prevStrongId, ops) {
+    if (!highlight || !graph) {
+        return { nextPrevStrongId: null };
+    }
+    // §5 Halt-target retargeting: real halt (id 0) reached from an in-frame
+    // state retargets to the frame's halt marker (id = -frameId), so the
+    // visible edge lands inside the cluster.
+    let toId = highlight.toId;
+    if (toId === 0 && typeof highlight.fromId === 'number') {
+        const fromFrameId = indexes.nodeFrameMap.get(highlight.fromId);
+        if (fromFrameId !== undefined)
+            toId = -fromFrameId;
+    }
+    // §2 Equivalence-class expansion (asymmetric, via highlightExpand):
+    //   wrapper → [wrapper, bare]  (joined visual pair for wrapper-entry pause)
+    //   bare    → [bare]           (engine genuinely on the bare; no wrapper sync)
+    // From-side expansion only fires for positive numeric ids; the 'idle'
+    // sentinel is handled directly below. Halt markers / singleton fall
+    // through the direct-lookup branches.
+    const fromEqIds = typeof highlight.fromId === 'number'
+        ? highlightExpand(highlight.fromId, graph)
+        : [];
+    const toEqIds = toId !== null && toId > 0
+        ? highlightExpand(toId, graph)
+        : [];
+    // §3 Class application — from side.
+    if (highlight.fromId === 'idle') {
+        ops.addNodeClass('idle', 'mg-highlight-from');
+        if (highlight.strong === 'from')
+            ops.addNodeClass('idle', 'mg-highlight-strong');
+    }
+    for (const id of fromEqIds) {
+        ops.addNodeClass(id, 'mg-highlight-from');
+        if (highlight.strong === 'from')
+            ops.addNodeClass(id, 'mg-highlight-strong');
+    }
+    // §3 + §8 Class application — to side. Halt markers (toId < 0) and the
+    // real halt singleton (toId === 0; only possible when §5 didn't retarget)
+    // bypass the equivalence-class expansion via direct lookup.
+    if (toId !== null && toId <= 0) {
+        ops.addNodeClass(toId, 'mg-highlight-to');
+        if (highlight.strong === 'to')
+            ops.addNodeClass(toId, 'mg-highlight-strong');
+    }
+    for (const id of toEqIds) {
+        ops.addNodeClass(id, 'mg-highlight-to');
+        if (highlight.strong === 'to')
+            ops.addNodeClass(id, 'mg-highlight-strong');
+    }
+    // Edge highlight: the data-id token form mermaid emits.
+    const fromKey = highlight.fromId === 'idle' ? 'idle' : `s${highlight.fromId}`;
+    const toKey = toId === null ? null
+        : toId < 0 ? `c${-toId}` // halt marker
+            : `s${toId}`;
+    if (toKey !== null)
+        ops.highlightEdge(fromKey, toKey);
+    // §10 Wrapper-entry "call" edge: when to-side expanded to [wrapper, bare],
+    // light up the wrapper→bare connector so the joined pair has a visible link.
+    if (toEqIds.length > 1) {
+        const wrapperId = toEqIds.find((id) => graph.nodes[id]?.isWrapper);
+        const bareId = toEqIds.find((id) => !graph.nodes[id]?.isWrapper);
+        if (wrapperId !== undefined && bareId !== undefined) {
+            ops.highlightEdge(`s${wrapperId}`, `s${bareId}`);
+        }
+    }
+    // §6 Source return chain: just-fired transition landed on a frame's
+    // halt marker. Light up the post-pop trajectory before the next iter
+    // moves the strong node.
+    if (toId !== null && toId < 0) {
+        const frameId = -toId;
+        const wrappers = indexes.frameWrappersMap.get(frameId) ?? [];
+        for (const { wrapperId, overrideId } of wrappers) {
+            ops.highlightEdge(`w_${frameId}`, `s${wrapperId}`);
+            ops.addNodeClass(wrapperId, 'mg-highlight-to');
+            if (overrideId !== null) {
+                ops.highlightEdge(`s${wrapperId}`, `s${overrideId}`);
+                ops.addNodeClass(overrideId, 'mg-highlight-to');
+            }
+        }
+    }
+    // §7 Destination return chain: paused at a positive toId that's some
+    // wrapper W's override AND fromId is in W's frame — the engine just
+    // popped. The straight bare→override edge doesn't exist in the graph;
+    // light up the actual visible path bare → halt-marker → return →
+    // wrapper → override, plus the frame cluster.
+    if (typeof highlight.fromId === 'number' && toId !== null && toId > 0) {
+        const fromFrameId = indexes.nodeFrameMap.get(highlight.fromId);
+        if (fromFrameId !== undefined) {
+            const wrappers = indexes.frameWrappersMap.get(fromFrameId) ?? [];
+            const matching = wrappers.filter((w) => w.overrideId === toId);
+            if (matching.length > 0) {
+                ops.addNodeClass(-fromFrameId, 'mg-highlight-to');
+                ops.highlightEdge(`s${highlight.fromId}`, `c${fromFrameId}`);
+                for (const { wrapperId } of matching) {
+                    ops.highlightEdge(`w_${fromFrameId}`, `s${wrapperId}`);
+                    ops.addNodeClass(wrapperId, 'mg-highlight-to');
+                    ops.highlightEdge(`s${wrapperId}`, `s${toId}`);
+                }
+                ops.markFrameActive(fromFrameId);
+            }
+        }
+    }
+    // §9 Frame-active for the strong node. Wrappers are outside any frame
+    // so canonicalize via bareIdOf so the wrapper-entry pause still lights
+    // up the bare's enclosing cluster.
+    const strongId = highlight.strong === 'from' ? highlight.fromId : highlight.toId;
+    const strongIdCanonical = typeof strongId === 'number'
+        ? bareIdOf(strongId, graph)
+        : strongId;
+    if (typeof strongIdCanonical === 'number') {
+        const frameId = indexes.nodeFrameMap.get(strongIdCanonical);
+        if (frameId !== undefined)
+            ops.markFrameActive(frameId);
+    }
+    // §11 Pulse on same-state revisit. Uses RAW strongId — wrapper-pause
+    // and bare-pause are visually distinct positions even though they
+    // share #debugRef; pausing at wrapper then continuing into bare must
+    // not pulse. Idles never pulse and never update prevStrongId.
+    if (highlight.paused
+        && strongId !== null
+        && strongId === prevStrongId
+        && strongId !== undefined) {
+        ops.pulse(strongId);
+    }
+    // Scroll-into-view target: for wrapper-entry pauses, scroll to the
+    // BARE (not the wrapper) so the focus matches the displayed state
+    // name. The worker's `resolveDisplayName` returns the bare's name
+    // for wrapper iters (so the log reads "paused at walkToBlank ..."),
+    // but `toId` is the wrapper's id and `highlightExpand` lights up
+    // both nodes as strong. Without this canonicalization the scroll
+    // lands on the wrapper while the log line and user's mental focus
+    // are on the bare. Halt-related ids (≤ 0) are scrolled to as-is —
+    // `bareIdOf` would collapse them all to the halt singleton, which
+    // is structurally separate from the in-frame halt marker the user
+    // is paused near.
+    if (strongId !== null) {
+        let scrollTarget = strongId;
+        if (typeof strongId === 'number' && strongId > 0) {
+            const node = graph.nodes[strongId];
+            if (node?.isWrapper && node.bareStateId !== null) {
+                scrollTarget = node.bareStateId;
+            }
+        }
+        ops.scrollIntoView(scrollTarget);
+    }
+    const nextPrevStrongId = highlight.paused ? strongId : prevStrongId;
+    return { nextPrevStrongId };
+}
+/**
+ * Pure breakpoint-indicator rule evaluator. For each cached node key,
+ * emit `ops.setBreakpoint(key, on)` reflecting whether the node's
+ * canonical bare-id is in the `breakpoints` set.
+ *
+ * The 'idle' string sentinel never carries a breakpoint. All numeric
+ * keys are valid BP-class members:
+ *   - positive id   → regular state; canonical via bareIdOf (wrappers
+ *                     collapse to bare)
+ *   - 0             → haltState singleton (engine-wide; canonical = 0)
+ *   - negative id   → halt marker (per-frame visualization sentinel;
+ *                     bareIdOf maps to 0 — same class as the singleton)
+ * Consumers pass their iterable of cached node keys (e.g. `nodeCache.keys()`).
+ */
+export function applyIndicator(breakpoints, graph, nodeIds, ops) {
+    for (const key of nodeIds) {
+        const on = typeof key === 'number'
+            && graph !== null
+            && breakpoints.has(bareIdOf(key, graph));
+        ops.setBreakpoint(key, on);
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,22 @@
+import { type MachineState, type TapeCommand } from '@turing-machine-js/machine';
+export declare const MOVEMENT_LETTER: Map<symbol, "L" | "R" | "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 declare function formatCommand(tapeCommand: TapeCommand): string;
+/**
+ * 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 declare function formatStep(m: MachineState): string;

package/dist/format.js

@@ -0,0 +1,46 @@
+import { movements, symbolCommands } from '@turing-machine-js/machine';
+export const MOVEMENT_LETTER = new Map([
+    [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) {
+    let write;
+    if (tapeCommand.symbol === symbolCommands.keep) {
+        write = 'K';
+    }
+    else if (tapeCommand.symbol === symbolCommands.erase) {
+        write = 'E';
+    }
+    else {
+        write = `'${tapeCommand.symbol}'`;
+    }
+    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) {
+    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/dist/graphIndexes.d.ts

@@ -0,0 +1,31 @@
+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 declare function indexGraph(graph: Graph | null): GraphIndexes;

package/dist/graphIndexes.js

@@ -0,0 +1,58 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,37 @@
+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 declare function bareIdOf(id: number, graph: Graph | null): number;
+/**
+ * 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 declare function highlightExpand(id: number, graph: Graph | null): number[];
+/**
+ * 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 declare function equivalentIds(id: number, graph: Graph | null): number[];

package/dist/graphUtils.js

@@ -0,0 +1,76 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 declare function recordingOps(): {
+    highlight: HighlightOps;
+    indicator: IndicatorOps;
+    record: RecordedOp[];
+};

package/dist/highlightOps.js

@@ -0,0 +1,36 @@
+/**
+ * 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 }); },
+        },
+    };
+}