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

package/dist/applyHighlight.js

@@ -1,191 +0,0 @@
-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.js

@@ -1,46 +0,0 @@
-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.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 {};