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

package/dist/index.cjs

@@ -0,0 +1,514 @@
+'use strict';
+
+var machine = require('@turing-machine-js/machine');
+
+/**
+ * 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).
+ */
+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 }); },
+        },
+    };
+}
+
+/**
+ * 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).
+ */
+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]`.
+ */
+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.
+ */
+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];
+}
+
+/**
+ * Walk the engine graph once and build all derived lookups. Cheap;
+ * intended to run on every Build (graph identity changes per build).
+ */
+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 };
+}
+
+/**
+ * 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.
+ */
+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()`).
+ */
+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);
+    }
+}
+
+const MOVEMENT_LETTER = new Map([
+    [machine.movements.left, 'L'],
+    [machine.movements.right, 'R'],
+    [machine.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.
+ */
+function formatCommand(tapeCommand) {
+    let write;
+    if (tapeCommand.symbol === machine.symbolCommands.keep) {
+        write = 'K';
+    }
+    else if (tapeCommand.symbol === machine.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]`.
+ */
+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}]`;
+}
+
+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 === machine.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.
+ */
+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,
+    };
+}
+
+exports.applyHighlight = applyHighlight;
+exports.applyIndicator = applyIndicator;
+exports.bareIdOf = bareIdOf;
+exports.equivalentIds = equivalentIds;
+exports.formatCommand = formatCommand;
+exports.formatStep = formatStep;
+exports.highlightExpand = highlightExpand;
+exports.indexGraph = indexGraph;
+exports.recordSnippet = recordSnippet;
+exports.recordingOps = recordingOps;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+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';

package/dist/index.js

@@ -0,0 +1,6 @@
+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';