agent-whiteboard 1.0.0

package/dist/server/render-core.js

@@ -0,0 +1,213 @@
+// Shared core logic for render / step-frames-create / append / commit /
+// workspace-validation — used identically by the REST handlers (app.ts) and
+// the MCP tool handlers (mcp.ts) so the two transports can never drift (NF12).
+import { cancelSlideshow } from "./slideshow.js";
+import { broadcastReplace, broadcastStepFrames } from "./ws.js";
+import { generateSnapshotId } from "./snapshot-writer.js";
+import { assembleStepFramesPayload, persistContent } from "./persist.js";
+import { validateFrame } from "./validate.js";
+import { getCanvas, isStepSequence, seekStepFrame, setCanvas, setLastWorkspace, setStepFrames, stepCursor } from "./session.js";
+import { appendFrame, commitBuilder, createBuilder } from "./step-frames-builder.js";
+import { getViewport } from "./viewport-cache.js";
+// Re-exported so app.ts/mcp.ts don't need to know it actually lives in
+// validate.ts — moved there (v0.28 Sprint 59) so snapshot-writer.ts can also
+// depend on it without a render-core.ts <-> snapshot-writer.ts import cycle.
+export { validateWorkspaceInput } from "./validate.js";
+/**
+ * Commits an already-validated render() payload: cancels any running
+ * slideshow, stores the canvas state, broadcasts to the browser, updates
+ * lastWorkspace, and writes the snapshot (F10 — a write failure must never
+ * block rendering). Shared by POST /render and the MCP `render` tool.
+ * render() is single-frame only (v0.26 Sprint 45) — multi-frame sequences are
+ * built exclusively via init_step_frames()/append_frame()/commit_step_frames().
+ */
+export function commitRenderResult(type, payload, workspace, title) {
+    cancelSlideshow();
+    // Generate the id before broadcasting so the browser can key its viewport
+    // report on it — a brand-new render() always mints a fresh id (F19/C3).
+    const newId = generateSnapshotId();
+    setCanvas(type, payload, title, newId);
+    broadcastReplace({ type, payload, title, id: newId, cursor: 0, total: 1 });
+    setLastWorkspace(workspace);
+    const { id: snapshotId } = persistContent("render", {
+        frames: [{ type, payload }],
+        title,
+        workspace,
+        id: newId,
+    });
+    return { ok: true, ...(snapshotId !== undefined ? { id: snapshotId } : {}) };
+}
+/**
+ * Creates an incremental step-frames builder entry and pushes the 0-frame
+ * placeholder to the browser. Callers validate `frameType`/`workspace`
+ * beforehand (REST via a runtime check, MCP via its zod schema). Shared by
+ * POST /step-frames/init and the MCP `init_step_frames` tool.
+ */
+export function initStepFramesResult(frameType, workspace, title) {
+    const id = createBuilder(frameType, workspace, title);
+    broadcastReplace({ type: "step-frames-placeholder", frameCount: 0, title });
+    return { id };
+}
+/**
+ * Appends a frame to an in-progress step-frames builder and, if accepted,
+ * pushes the accumulated partial sequence to the browser (live preview,
+ * v0.9). Shared by POST /step-frames/:id/frame and the MCP `append_frame` tool.
+ * Persist trigger: "transient" (server/persist.ts) — never touches disk;
+ * only `commit_step_frames()` persists.
+ */
+export async function appendFrameAndBroadcast(id, payload, label, type) {
+    const result = await appendFrame(id, payload, label, type);
+    if (result.ok) {
+        // Live preview: push the accumulated partial sequence to the browser.
+        // Reuse the builder id so the browser fits-to-view once on the first
+        // frame and treats subsequent appends as a continuation (F19/C3) — this
+        // is distinct from the final snapshot id minted at commit time.
+        const { frames, frame_type, title } = result;
+        broadcastStepFrames(frames, frame_type, frames.length - 1, id, title);
+    }
+    return result;
+}
+/**
+ * Finalises an in-progress step-frames builder entry: assembles the full
+ * JSON, cancels any running slideshow, updates in-memory canvas state,
+ * writes the snapshot (F10 backstop), and sends a final broadcast (handles
+ * clear() called between appends). Shared by POST /step-frames/:id/commit
+ * and the MCP `commit_step_frames` tool.
+ * `nodeToFrame` (v0.26 Sprint 45): optional node ID → frame index map for
+ * autonomous browser navigation (U4e) — this is its only entry point now that
+ * one-shot render(type="step-frames", options.node_to_frame) no longer exists.
+ */
+export function commitStepFramesResult(id, nodeToFrame) {
+    const result = commitBuilder(id);
+    if (!result.ok)
+        return result;
+    const { entry } = result;
+    const { frame_type, workspace, title, frames } = entry;
+    const assembledPayload = assembleStepFramesPayload(frame_type, frames);
+    const resolvedFrames = frames.map((f) => ({
+        type: f.type ?? frame_type,
+        payload: f.payload,
+        ...(f.label !== undefined ? { label: f.label } : {}),
+    }));
+    cancelSlideshow();
+    const commitId = generateSnapshotId();
+    setStepFrames(frames, frame_type, assembledPayload, title, nodeToFrame, commitId);
+    setLastWorkspace(workspace);
+    const { id: commitSnapshotId } = persistContent("commit_step_frames", {
+        frames: resolvedFrames,
+        rawPayload: assembledPayload,
+        title,
+        nodeToFrame,
+        workspace,
+        id: commitId,
+    });
+    // Final broadcast for consistency (handles clear() called between appends).
+    broadcastStepFrames(frames, frame_type, 0, commitId, title, nodeToFrame);
+    return { ok: true, ...(commitSnapshotId !== undefined ? { id: commitSnapshotId } : {}) };
+}
+/**
+ * Commits an already-parsed history-load snapshot (NF25, v0.28 Sprint 58):
+ * validates every frame, decides single-frame vs step-frames, updates
+ * in-memory canvas state, broadcasts to the browser, and updates
+ * lastWorkspace. Write-silent — persist trigger "never" (server/persist.ts),
+ * same as step()/seek()/clear(). Shared entry point for POST /snapshots/load;
+ * the handler is reduced to request-shape parsing + file loading.
+ */
+export async function applyLoadedSnapshotResult(frames, workspace, title, nodeToFrame, snapshotId, rawPayload) {
+    for (const frame of frames) {
+        const validationError = await validateFrame(frame);
+        if (validationError) {
+            return { ok: false, error: validationError };
+        }
+    }
+    // History-load always redisplays from frame 0 (F10 — cursor is always 0 at
+    // write time), so the viewport lookup is always for frame 0 (v0.26.1,
+    // B19/FR21 — composite id:frameIndex key). Looked up under the snapshot's
+    // own id, not a synthesized one — a synthesized id can never have a cache
+    // entry anyway.
+    const viewport = snapshotId !== undefined ? getViewport(snapshotId, 0) : undefined;
+    // A concrete id is required on every broadcast (v0.26 Sprint 42) — pre-v0.11
+    // snapshots may lack one (J1, `02`), so synthesize a fresh one here.
+    const resolvedId = snapshotId ?? generateSnapshotId();
+    if (frames.length > 1) {
+        const stepFrames = frames.map((f) => ({ payload: f.payload, type: f.type, ...(f.label !== undefined ? { label: f.label } : {}) }));
+        // rawPayload (v0.26 Sprint 43) carries the verbatim original step-frames
+        // envelope — reconstruct only if a hand-edited/pre-migration file lacks it.
+        const assembledRawPayload = rawPayload ?? assembleStepFramesPayload(frames[0].type, stepFrames);
+        setStepFrames(stepFrames, frames[0].type, assembledRawPayload, title, nodeToFrame, resolvedId);
+        broadcastReplace({
+            type: frames[0].type,
+            payload: frames[0].payload,
+            frameLabel: frames[0].label,
+            cursor: 0,
+            total: frames.length,
+            title,
+            nodeToFrame,
+            id: resolvedId,
+            viewport,
+        });
+    }
+    else {
+        setCanvas(frames[0].type, frames[0].payload, title, resolvedId);
+        broadcastReplace({ type: frames[0].type, payload: frames[0].payload, title, id: resolvedId, cursor: 0, total: 1, viewport });
+    }
+    setLastWorkspace(workspace);
+    persistContent("history-load", { frames, title, nodeToFrame, workspace, id: resolvedId });
+    return { ok: true };
+}
+/**
+ * Advances/rewinds the step cursor and broadcasts the resulting frame.
+ * Shared by POST /step and the MCP `step` tool (NF19 — previously duplicated
+ * verbatim between app.ts and mcp.ts, the one hot-path pair render-core.ts's
+ * own NF12 header comment didn't yet cover).
+ */
+export function stepAndBroadcast(direction) {
+    const result = stepCursor(direction);
+    if (!result) {
+        return { ok: false, error: "no step-frames sequence is loaded" };
+    }
+    const state = getCanvas();
+    if (isStepSequence(state)) {
+        const { frames, title, id } = state.presentation;
+        // Same id as when this sequence was created — tells the browser this is
+        // a continuation, not a new diagram (F19/C3). Each frame now re-fits or
+        // restores its own saved viewport independently (v0.26.1, bug B19/FR21) —
+        // no longer "must not re-fit" for the whole sequence.
+        const resolvedId = id ?? generateSnapshotId();
+        const viewport = getViewport(resolvedId, result.currentFrame);
+        broadcastStepFrames(frames, state.frameType, result.currentFrame, resolvedId, title, state.nodeToFrame, viewport);
+    }
+    return { ok: true, current_frame: result.currentFrame, total_frames: result.totalFrames };
+}
+/**
+ * Jumps the step cursor to an arbitrary frame index and broadcasts it.
+ * Shared by POST /seek and the MCP `seek` tool (NF19, see `stepAndBroadcast`).
+ */
+export function seekAndBroadcast(frame) {
+    const state = getCanvas();
+    if (!isStepSequence(state)) {
+        return { ok: false, error: "no step-frames sequence is loaded" };
+    }
+    const { frames, title, id } = state.presentation;
+    const total = frames.length;
+    if (frame < 0 || frame >= total) {
+        return { ok: false, error: `frame out of range: must be 0–${total - 1}` };
+    }
+    seekStepFrame(frame);
+    const f = frames[frame];
+    const resolvedId = id ?? generateSnapshotId();
+    broadcastReplace({
+        type: f.type,
+        payload: f.payload,
+        frameLabel: f.label,
+        cursor: frame,
+        total,
+        title,
+        nodeToFrame: state.nodeToFrame,
+        id: resolvedId,
+        // Per-frame restore (v0.26.1, bug B19/FR21) — each frame of a sequence
+        // re-fits or restores independently instead of sharing one viewport.
+        viewport: getViewport(resolvedId, frame),
+    });
+    return { ok: true, current_frame: frame, total_frames: total };
+}

package/dist/server/session.js

@@ -0,0 +1,103 @@
+// In-memory canvas state — single canvas, no persistence in v1.
+// Also tracks the workspace from the most recent render() call (used by history endpoints).
+//
+// Unified reducer (U3, v0.26 Sprint 40): a single Presentation + cursor +
+// driver model replaces the old 3-way CanvasState union (empty | single-type
+// | step-frames) — "step-frames" is no longer a branch anywhere in this file.
+// Every render becomes a Presentation of one or more Frames; `driver` records
+// whether the cursor moves ("manual", via step()/seek()) or is fixed
+// ("static", a single-frame render). `driver: "timed"` is reserved for the
+// slideshow-controller distinction a later sprint introduces — today
+// slideshow ticks reuse "manual" so that Prev/Next navigation during a
+// slideshow keeps working exactly as it did before this refactor (F7).
+/**
+ * Narrows a CanvasState to "a navigable multi-frame sequence is loaded" —
+ * the replacement for the old `canvas.type === "step-frames"` check, now
+ * expressed on the driver axis instead of a content-type tag.
+ */
+export function isStepSequence(state) {
+    return state.presentation !== null && state.driver === "manual";
+}
+let canvas = { presentation: null, driver: "static" };
+let lastWorkspace = "";
+export function getCanvas() {
+    return canvas;
+}
+export function getLastWorkspace() {
+    return lastWorkspace;
+}
+export function setLastWorkspace(workspace) {
+    lastWorkspace = workspace;
+}
+export function setCanvas(type, payload, title, id) {
+    const presentation = {
+        cursor: 0,
+        frames: [{ type, payload }],
+        ...(title !== undefined ? { title } : {}),
+        ...(id !== undefined ? { id } : {}),
+    };
+    canvas = { presentation, driver: "static" };
+}
+export function setStepFrames(frames, frameType, rawPayload, title, nodeToFrame, id) {
+    const resolvedFrames = frames.map((f) => ({
+        type: f.type ?? frameType,
+        payload: f.payload,
+        ...(f.label !== undefined ? { label: f.label } : {}),
+    }));
+    const presentation = {
+        cursor: 0,
+        frames: resolvedFrames,
+        ...(title !== undefined ? { title } : {}),
+        ...(id !== undefined ? { id } : {}),
+    };
+    canvas = {
+        presentation,
+        driver: "manual",
+        rawPayload,
+        frameType,
+        ...(nodeToFrame !== undefined ? { nodeToFrame } : {}),
+    };
+}
+/**
+ * Seek to a specific frame index in the loaded step-frames sequence.
+ * Used by the slideshow expander to advance the cursor to an arbitrary frame
+ * without resetting the full sequence. No-op if no step-frames sequence is loaded.
+ */
+export function seekStepFrame(index) {
+    if (!isStepSequence(canvas))
+        return;
+    canvas = { ...canvas, presentation: { ...canvas.presentation, cursor: index } };
+}
+/**
+ * Advance or rewind the step cursor.
+ * Returns the new cursor state, or null if no step-frames sequence is loaded.
+ */
+export function stepCursor(direction) {
+    if (!isStepSequence(canvas))
+        return null;
+    const total = canvas.presentation.frames.length;
+    const next = direction === "next"
+        ? Math.min(canvas.presentation.cursor + 1, total - 1)
+        : Math.max(canvas.presentation.cursor - 1, 0);
+    canvas = { ...canvas, presentation: { ...canvas.presentation, cursor: next } };
+    return { currentFrame: next, totalFrames: total };
+}
+export function clearCanvas() {
+    canvas = { presentation: null, driver: "static" };
+}
+/** Returns the current source spec, or empty string if canvas is blank. */
+export function exportCanvas() {
+    if (canvas.presentation === null)
+        return "";
+    if (canvas.rawPayload !== undefined)
+        return canvas.rawPayload;
+    return canvas.presentation.frames[0]?.payload ?? "";
+}
+/** Reset canvas to empty — for use in tests only. */
+export function resetCanvas() {
+    canvas = { presentation: null, driver: "static" };
+}
+/** Reset lastWorkspace to empty string — for use in tests only. */
+export function resetLastWorkspace() {
+    lastWorkspace = "";
+}

package/dist/server/slideshow.js

@@ -0,0 +1,83 @@
+// Slideshow — server-side timer that auto-advances slides on the canvas.
+// Phase 2 feature (Sprint 9). Slides are single frames only (v0.26 Sprint 45)
+// — a slide can no longer itself be a step-frames sequence; that expansion
+// path was removed along with "step-frames" as a top-level content type.
+import { broadcastReplace } from "./ws.js";
+import { getCanvas, setCanvas } from "./session.js";
+import { generateSnapshotId } from "./snapshot-writer.js";
+import { persistContent } from "./persist.js";
+function broadcastSlide(slide) {
+    // Fresh id per slide so the browser auto-fits (F19/C3) — without this the
+    // diagram never fits to view (stays at default scale/position).
+    const id = generateSnapshotId();
+    setCanvas(slide.type, slide.payload, slide.title, id);
+    broadcastReplace({ type: slide.type, payload: slide.payload, title: slide.title, id, cursor: 0, total: 1 });
+}
+let activeTimer = null;
+// Set for the lifetime of a slideshow "session" — from startSlideshow() until
+// the next cancelSlideshow() — even for a single-slide slideshow that never
+// starts a timer. Used only to know where to persist the finalize snapshot.
+let activeWorkspace;
+/**
+ * Persists whatever is currently on the canvas as a single snapshot, once,
+ * when a slideshow session ends (naturally or by cancellation) — mirroring
+ * commit_step_frames()'s "transient until finalized" pattern (F15): individual
+ * ticks never touch disk, only this final state does. No-op if no slideshow
+ * session is active, the canvas is empty, or (F10) the write itself fails —
+ * a persistence failure must never block anything else.
+ */
+function finalizeSlideshow() {
+    if (activeWorkspace === undefined)
+        return;
+    const canvas = getCanvas();
+    if (canvas.presentation === null)
+        return;
+    const { frames, title, id } = canvas.presentation;
+    persistContent("slideshow-end", {
+        frames,
+        title,
+        workspace: activeWorkspace,
+        id: id ?? generateSnapshotId(),
+    });
+}
+/**
+ * Start a slideshow. Stops after the last slide (no loop). Cancels any
+ * previously running slideshow.
+ */
+export function startSlideshow(slides, delay_ms, workspace) {
+    cancelSlideshow(); // finalizes + ends any previous session
+    activeWorkspace = workspace;
+    broadcastSlide(slides[0]);
+    if (slides.length === 1)
+        return; // single slide — no timer needed, but the session
+    // stays open (unfinalized) until the next cancelSlideshow() call
+    let index = 1;
+    activeTimer = setInterval(() => {
+        broadcastSlide(slides[index]);
+        index++;
+        if (index >= slides.length) {
+            cancelSlideshow(); // natural completion
+        }
+    }, delay_ms);
+}
+/**
+ * Cancel any running slideshow timer and end the current session. Last
+ * rendered slide stays on screen. By default this also finalizes (persists)
+ * that last slide as a single snapshot — the one exception is `clear()`,
+ * which must never produce a snapshot (F10); its call site passes
+ * `{ persist: false }`.
+ */
+export function cancelSlideshow(options = {}) {
+    const { persist = true } = options;
+    const wasActive = activeTimer !== null || activeWorkspace !== undefined;
+    if (wasActive && persist)
+        finalizeSlideshow();
+    if (activeTimer !== null) {
+        clearInterval(activeTimer);
+        activeTimer = null;
+    }
+    activeWorkspace = undefined;
+}
+export function isSlideshowRunning() {
+    return activeTimer !== null;
+}

package/dist/server/snapshot-reader.js

@@ -0,0 +1,190 @@
+import { readdirSync, readFileSync } from "fs";
+import { join } from "path";
+/** Shared "is this a valid Frame[]" predicate (F6/NF23) — the one implementation checking non-empty array + per-element shape. */
+export function isFrameArray(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((f) => f !== null &&
+            typeof f === "object" &&
+            typeof f.type === "string" &&
+            typeof f.payload === "string"));
+}
+/**
+ * Display "type badge" for a snapshot's frame list (v0.26 Sprint 43 — the
+ * unified schema has no top-level `type` field anymore). A multi-frame
+ * sequence badges as "step-frames", same literal value the old schema's
+ * `type` field held for one; a single frame badges as its own resolved type
+ * — this reproduces the exact old badge values for every real case,
+ * including the "1-frame step-frames === plain render" policy already
+ * applied to the WS contract (Sprint 42) and `rawPayload` (this schema).
+ */
+export function badgeType(frames) {
+    return frames.length > 1 ? "step-frames" : frames[0].type;
+}
+export function listSnapshots(workspace, dir) {
+    const workspaceDir = join(dir, workspace);
+    let files;
+    try {
+        files = readdirSync(workspaceDir).filter((f) => f.endsWith("_screen.json"));
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const filename of files) {
+        try {
+            const raw = readFileSync(join(workspaceDir, filename), "utf-8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.timestamp !== "string" || !isFrameArray(parsed.frames)) {
+                console.error(`[agent-whiteboard] snapshot-reader: skipping malformed file: ${filename}`);
+                continue;
+            }
+            const entry = {
+                filename,
+                timestamp: parsed.timestamp,
+                type: badgeType(parsed.frames),
+            };
+            if (typeof parsed.id === "string") {
+                entry.id = parsed.id;
+            }
+            if (typeof parsed.title === "string" && parsed.title.length > 0) {
+                entry.title = parsed.title;
+            }
+            entries.push(entry);
+        }
+        catch (err) {
+            console.error(`[agent-whiteboard] snapshot-reader: skipping unreadable file ${filename}:`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    // Sort newest-first by timestamp string (ISO 8601 sorts lexicographically).
+    entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    return entries;
+}
+/**
+ * Scan every workspace subdirectory under `dir` and return their snapshots grouped.
+ * Workspaces with no readable snapshots are omitted from the result.
+ */
+export function listAllSnapshots(dir, currentWorkspace) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    const groups = [];
+    for (const name of entries) {
+        const snapshots = listSnapshots(name, dir);
+        if (snapshots.length === 0)
+            continue;
+        groups.push({ name, isCurrent: name === currentWorkspace, snapshots });
+    }
+    groups.sort((a, b) => a.name.localeCompare(b.name));
+    return groups;
+}
+/**
+ * Read the raw content of a single snapshot file.
+ * Returns null if the file does not exist or cannot be read.
+ */
+export function loadSnapshotContent(workspace, dir, filename) {
+    try {
+        return readFileSync(join(dir, workspace, filename), "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort read of a snapshot file's `id` field, for viewport-cache cleanup on delete. */
+export function readSnapshotIdSafe(fullPath) {
+    try {
+        const raw = readFileSync(fullPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.id === "string" ? parsed.id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Scan all workspace subdirectories under `dir` for a snapshot whose `id` field matches.
+ * Returns the snapshot's original re-renderable payload string if found, or null if no
+ * match. `rawPayload` (the verbatim step-frames envelope) wins when present — this
+ * mirrors `session.ts`'s `exportCanvas()`: `rawPayload ?? frames[0].payload`.
+ * Old snapshots without an `id` field are silently skipped.
+ */
+export function findSnapshotById(id, dir) {
+    let workspaceDirs;
+    try {
+        workspaceDirs = readdirSync(dir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        return null;
+    }
+    for (const workspace of workspaceDirs) {
+        const workspaceDir = join(dir, workspace);
+        let files;
+        try {
+            files = readdirSync(workspaceDir).filter((f) => f.endsWith("_screen.json"));
+        }
+        catch {
+            continue;
+        }
+        for (const filename of files) {
+            try {
+                const raw = readFileSync(join(workspaceDir, filename), "utf-8");
+                const parsed = JSON.parse(raw);
+                if (parsed.id === id && isFrameArray(parsed.frames)) {
+                    return typeof parsed.rawPayload === "string" ? parsed.rawPayload : parsed.frames[0].payload;
+                }
+            }
+            catch (err) {
+                console.error(`[agent-whiteboard] snapshot-reader: skipping unreadable file ${filename}:`, err instanceof Error ? err.message : String(err));
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Scan a single workspace directory for a snapshot whose `id` field matches.
+ * Returns the full parsed record (frames, timestamp, title?, nodeToFrame?)
+ * needed by the export pipeline, or null if no match (or the workspace
+ * directory is absent). Old snapshots without an `id` field are silently
+ * skipped.
+ */
+export function findSnapshotByIdInWorkspace(workspace, id, dir) {
+    const workspaceDir = join(dir, workspace);
+    let files;
+    try {
+        files = readdirSync(workspaceDir).filter((f) => f.endsWith("_screen.json"));
+    }
+    catch {
+        return null;
+    }
+    for (const filename of files) {
+        try {
+            const raw = readFileSync(join(workspaceDir, filename), "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed.id === id && typeof parsed.timestamp === "string" && isFrameArray(parsed.frames)) {
+                const record = {
+                    frames: parsed.frames,
+                    timestamp: parsed.timestamp,
+                };
+                if (typeof parsed.title === "string") {
+                    record.title = parsed.title;
+                }
+                if (parsed.nodeToFrame !== null && typeof parsed.nodeToFrame === "object") {
+                    record.nodeToFrame = parsed.nodeToFrame;
+                }
+                return record;
+            }
+        }
+        catch (err) {
+            console.error(`[agent-whiteboard] snapshot-reader: skipping unreadable file ${filename}:`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    return null;
+}