agent-whiteboard 1.0.0

package/dist/server/interaction.js

@@ -0,0 +1,135 @@
+// Interaction primitive (U7, D4 — v0.26 Sprints 46-47): one arm/await/resolve
+// mechanism for every server-side "wait for the browser user" signal.
+// `wait_done` and `wait_click` are configurations of it, distinguished only
+// by their resolution mode:
+//   - broadcast:     every pending await() gets its own listener; one
+//                     resolve() wakes all of them (wait_done — F9).
+//   - single-flight:  at most one pending await() at a time; a new arm on
+//                     this interaction, or an external supersede() call from
+//                     a different one taking over the return channel, cancels
+//                     the previous one with `type: "superseded"` rather than
+//                     leaving it to the plain-inactivity `"timeout"` (Sprint
+//                     47, OQ11 — wait_done() superseding a pending
+//                     wait_click() is the one cross-interaction case today).
+// `node_to_frame` (U4e) is the same primitive conceptually — arm on commit,
+// resolve on click — but its resolver runs entirely client-side (the browser
+// calls POST /seek directly instead of round-tripping through the agent), so
+// it has no server-side arm/await state and nothing here to share code with.
+// Its auto-restore (Sprint 47, OQ12) lives purely in canvasStore.ts's reducer.
+import { EventEmitter } from "node:events";
+export const INTERACTION_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+/** Every pending await() resolves independently; resolve() wakes all of them. */
+export function createBroadcastInteraction() {
+    const bus = new EventEmitter();
+    return {
+        resolve(event) {
+            bus.emit("resolve", event);
+        },
+        await() {
+            return new Promise((resolve) => {
+                const onResolve = (event) => {
+                    clearTimeout(timer);
+                    resolve(event);
+                };
+                const timer = setTimeout(() => {
+                    bus.off("resolve", onResolve);
+                    resolve(undefined);
+                }, INTERACTION_TIMEOUT_MS);
+                bus.once("resolve", onResolve);
+            });
+        },
+    };
+}
+/**
+ * At most one pending await() at a time. A new arm — either a fresh await()
+ * on this same interaction, or an external supersede() call from a different
+ * interaction taking over the return channel (D4, v0.26 Sprint 47 — e.g.
+ * wait_done() superseding a pending wait_click()) — cancels the previous one
+ * with `supersededEvent`. A pending await() left untouched for the full
+ * `INTERACTION_TIMEOUT_MS` resolves on its own with `timeoutEvent` instead.
+ */
+export function createSingleFlightInteraction(timeoutEvent, supersededEvent) {
+    let pending = null;
+    let timer = null;
+    function settle(event) {
+        const resolve = pending;
+        pending = null;
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        resolve?.(event);
+    }
+    return {
+        resolve(event) {
+            if (!pending)
+                return; // no-op when nothing is armed
+            settle(event);
+        },
+        await() {
+            if (pending)
+                settle(supersededEvent); // a new arm supersedes the previous one
+            return new Promise((resolve) => {
+                pending = resolve;
+                timer = setTimeout(() => settle(timeoutEvent), INTERACTION_TIMEOUT_MS);
+            });
+        },
+        supersede() {
+            if (!pending)
+                return; // no-op when nothing is armed
+            settle(supersededEvent);
+        },
+        reset() {
+            settle(timeoutEvent);
+        },
+    };
+}
+// ── Done signal (F9, U4a) ────────────────────────────────────────────────────
+let doneArmed = false;
+export function getDoneArmed() {
+    return doneArmed;
+}
+// Lazily imported to avoid circular dependency (ws.ts imports interaction.ts indirectly).
+let _broadcastFn = null;
+export function setBroadcastFn(fn) {
+    _broadcastFn = fn;
+}
+function broadcastDoneArmed(armed) {
+    _broadcastFn?.({ action: "set_done_armed", armed });
+}
+const doneInteraction = createBroadcastInteraction();
+/** Signal that the user clicked Done — wakes all pending waitForDone() calls. */
+export function signalDone() {
+    doneInteraction.resolve(undefined);
+}
+/** Resolve when the user clicks Done (or after the timeout). */
+export async function waitForDone() {
+    doneArmed = true;
+    broadcastDoneArmed(true);
+    // Arming Done takes over the return channel from a pending click (D4, one
+    // Interaction primitive) — supersede it rather than leaving it to time out.
+    clickInteraction.supersede();
+    await doneInteraction.await();
+    doneArmed = false;
+    broadcastDoneArmed(false);
+}
+const CLICK_TIMEOUT_EVENT = { type: "timeout", id: "", label: "", action: null };
+const CLICK_SUPERSEDED_EVENT = { type: "superseded", id: "", label: "", action: null };
+const clickInteraction = createSingleFlightInteraction(CLICK_TIMEOUT_EVENT, CLICK_SUPERSEDED_EVENT);
+/** Signal that the user clicked a node/edge — resolves the pending waitForClick(). No-op if none pending. */
+export function signalClick(event) {
+    clickInteraction.resolve(event);
+}
+/**
+ * Resolve when the user clicks a node/edge (or after the timeout).
+ * At most one call may be pending — a second `wait_click()` (or an arming
+ * `wait_done()`) supersedes it, resolving with `type: "superseded"` (v0.26
+ * Sprint 47, OQ11) rather than the plain-inactivity `type: "timeout"`.
+ */
+export function waitForClick() {
+    return clickInteraction.await();
+}
+/** Reset click state — for use in tests only. */
+export function resetClick() {
+    clickInteraction.reset();
+}

package/dist/server/mcp.js

@@ -0,0 +1,421 @@
+// MCP tool definitions and handlers.
+// Tools: render, clear, export, step.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { clearCanvas, exportCanvas } from "./session.js";
+import { broadcast } from "./ws.js";
+import { nodeActionsSchema, nodeToFrameSchema, validateFrame } from "./validate.js";
+import { getSnapshotsRoot } from "./paths.js";
+import { cancelSlideshow, startSlideshow } from "./slideshow.js";
+import { waitForClick, waitForDone } from "./interaction.js";
+import { findSnapshotById, findSnapshotByIdInWorkspace, listSnapshots } from "./snapshot-reader.js";
+import { generateExportHtml } from "./export-html.js";
+import { appendFrameAndBroadcast, commitRenderResult, commitStepFramesResult, initStepFramesResult, seekAndBroadcast, stepAndBroadcast, validateWorkspaceInput, } from "./render-core.js";
+export function createMcpServer() {
+    const server = new McpServer({
+        name: "agent-whiteboard",
+        version: "0.1.0",
+    });
+    // render(type, payload) — push content to the canvas.
+    server.registerTool("render", {
+        description: "Push content to the whiteboard canvas. The payload always replaces the current canvas state.\n" +
+            "Supported types:\n" +
+            '  • "mermaid"     — Mermaid diagram source. Must begin with a diagram keyword (graph, flowchart, sequenceDiagram, classDiagram, erDiagram, gantt, pie, mindmap). Example: render({ type: "mermaid", payload: "graph TD; A --> B" })\n' +
+            '  • "svg"         — Inline SVG markup. Example: render({ type: "svg", payload: "<svg>...</svg>" })\n' +
+            '  • "html"        — HTML fragment, styled with Bootstrap 5 (CSS-only build, always available — no need to link or import it). Use its component classes instead of hand-authored CSS: "card"/"card-body"/"card-title" for panels, "alert alert-info"/"alert-warning"/"alert-danger" for callouts, "badge bg-primary"/"bg-success" for tags, "table table-striped"/"table-bordered" for data tables. No Bootstrap JS is loaded — components that depend on it (dropdowns, modals, tooltips, popovers, collapses, carousels, offcanvas) render their static markup but are not interactive, so avoid them. Example: render({ type: "html", payload: "<div class="card"><div class="card-body"><h5 class="card-title">Hello</h5><span class="badge bg-success">Done</span></div></div>" })\n' +
+            '  • "katex"       — LaTeX string, rendered in display mode. Example: render({ type: "katex", payload: "E = mc^2" })\n' +
+            '  • "vega-lite"   — Vega-Lite JSON spec (must be valid JSON). Example: render({ type: "vega-lite", payload: "{"$schema":"...","mark":"bar",...}" })\n' +
+            "render() is single-frame only. For a step-through sequence (multiple frames navigable via step()/seek()), use init_step_frames()/append_frame()/commit_step_frames() instead (see below).\n" +
+            'options: { "workspace": "my-course", "title": "My diagram" }. workspace is REQUIRED — snapshot routing fails without it. title is optional.\n' +
+            'options.workspace: workspace name for snapshot routing. Must be alphanumeric with dashes, underscores, dots, or spaces — no path separators. No env var fallback: always pass explicitly.\n' +
+            'Example: render({ type: "mermaid", payload: "graph TD; A --> B", options: { workspace: "course_2", title: "System flow" } })',
+        inputSchema: z.object({
+            type: z
+                .enum(["mermaid", "svg", "html", "katex", "vega-lite"])
+                .describe("Content type."),
+            payload: z
+                .string()
+                .describe("The content source. For mermaid: must begin with a valid diagram keyword. " +
+                "For vega-lite: must be valid JSON. For svg/html/katex: any string."),
+            options: z
+                .object({
+                workspace: z.string().describe("REQUIRED. Workspace name for snapshot routing. " +
+                    "Alphanumeric, dashes, underscores, dots, spaces — no path separators or '..'. " +
+                    "Always pass explicitly — no env var fallback."),
+                title: z.string().optional(),
+            })
+                .describe('Required options object. workspace: snapshot destination (required). title: label above canvas (optional).'),
+        }),
+    }, async ({ type, payload, options }) => {
+        const title = options?.title;
+        const workspaceResult = validateWorkspaceInput(options?.workspace);
+        if (!workspaceResult.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: workspaceResult.error }) }],
+            };
+        }
+        const { workspace } = workspaceResult;
+        const validationError = await validateFrame({ type, payload });
+        if (validationError) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: validationError }) }],
+            };
+        }
+        const result = commitRenderResult(type, payload, workspace, title);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+        };
+    });
+    // step(direction) — advance or rewind the step cursor.
+    server.registerTool("step", {
+        description: 'Advance ("next") or rewind ("prev") the step cursor for a loaded step-frames sequence. ' +
+            'Returns { "ok": true, "current_frame": N, "total_frames": M }. ' +
+            'Returns { "ok": false, "error": "..." } if no step-frames sequence is loaded.',
+        inputSchema: z.object({
+            direction: z
+                .enum(["next", "prev"])
+                .describe('"next" to advance, "prev" to rewind.'),
+        }),
+    }, ({ direction }) => {
+        return {
+            content: [{ type: "text", text: JSON.stringify(stepAndBroadcast(direction)) }],
+        };
+    });
+    // seek(frame) — jump the step cursor to an arbitrary frame index.
+    server.registerTool("seek", {
+        description: 'Jump the step-frame cursor to an arbitrary frame index. ' +
+            'Useful for random-access navigation without repeated step() calls. ' +
+            'Returns { "ok": true, "current_frame": N, "total_frames": M }. ' +
+            'Returns { "ok": false, "error": "..." } if no step-frames sequence is loaded or frame is out of range.',
+        inputSchema: z.object({
+            frame: z.number().int().nonnegative().describe("Zero-based frame index to jump to."),
+        }),
+    }, ({ frame }) => {
+        return {
+            content: [{ type: "text", text: JSON.stringify(seekAndBroadcast(frame)) }],
+        };
+    });
+    // clear() — reset the canvas.
+    server.registerTool("clear", {
+        description: "Reset the whiteboard canvas to a blank state.",
+        inputSchema: z.object({}),
+    }, () => {
+        cancelSlideshow({ persist: false }); // clear() must never produce a snapshot (F10)
+        clearCanvas();
+        broadcast({ action: "clear" });
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true }) }],
+        };
+    });
+    // slideshow(slides, delay_ms, workspace) — auto-advance a playlist on a server-side timer.
+    server.registerTool("slideshow", {
+        description: "Load a playlist of slides and auto-advance the canvas on a server-side timer.\n" +
+            'slides: array of { type, payload, title? } — same types as render().\n' +
+            'delay_ms: interval in milliseconds between slides.\n' +
+            "workspace: REQUIRED — same rules as render(). Individual ticks are never persisted; when the " +
+            "slideshow ends (runs to completion, is stopped, or is superseded by a new render()/slideshow() call), " +
+            "whatever is last on screen is written as a single snapshot to this workspace.\n" +
+            "A new call cancels any running slideshow. Use slideshow_stop() to stop early.\n" +
+            'Example: slideshow({ slides: [{ type: "mermaid", payload: "graph TD; A-->B", title: "Slide 1" }], delay_ms: 3000, workspace: "course_2" })',
+        inputSchema: z.object({
+            slides: z
+                .array(z.object({
+                type: z.enum(["mermaid", "svg", "html", "katex", "vega-lite"]).describe("Content type."),
+                payload: z.string().describe("Content source."),
+                title: z.string().optional().describe("Optional label above the canvas."),
+            }))
+                .min(1)
+                .describe("Ordered list of slides."),
+            delay_ms: z
+                .number()
+                .positive()
+                .describe("Milliseconds between slide advances."),
+            workspace: z.string().describe("REQUIRED. Workspace to persist the finalize snapshot to (see description). " +
+                "Alphanumeric, dashes, underscores, dots, spaces — no path separators or '..'."),
+        }),
+    }, async ({ slides, delay_ms, workspace: rawWorkspace }) => {
+        const workspaceResult = validateWorkspaceInput(rawWorkspace);
+        if (!workspaceResult.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: workspaceResult.error }) }],
+            };
+        }
+        const { workspace } = workspaceResult;
+        // Validate each slide payload — same validator REST's /slideshow uses (NF18).
+        for (let i = 0; i < slides.length; i++) {
+            const s = slides[i];
+            const err = await validateFrame({ type: s.type, payload: s.payload });
+            if (err) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ ok: false, error: `slide[${i}]: ${err}` }) }],
+                };
+            }
+        }
+        startSlideshow(slides, delay_ms, workspace);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true }) }],
+        };
+    });
+    // slideshow_stop() — cancel the running slideshow.
+    server.registerTool("slideshow_stop", {
+        description: "Cancel the running slideshow timer. The last rendered slide remains on screen. " +
+            "No-op if no slideshow is running.",
+        inputSchema: z.object({}),
+    }, () => {
+        cancelSlideshow();
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true }) }],
+        };
+    });
+    // wait_click(node_actions?) — arm click listener, block until user clicks a node/edge.
+    server.registerTool("wait_click", {
+        description: "Arm the browser for a single node or edge click on the current Mermaid diagram. " +
+            "The browser highlights clickable elements; one click resolves the call.\n" +
+            "Optional node_actions: map of node ID → string[] — nodes with registered actions show a popup menu on click; user selects one.\n" +
+            "Returns { \"ok\": true, \"type\": \"node\"|\"edge\", \"id\": \"<id>\", \"label\": \"<label>\", \"action\": \"<string or null>\" }.\n" +
+            "  action is null when no popup was shown or user clicked without selecting; string value when menu item was selected.\n" +
+            "On timeout (10 min): returns { \"ok\": true, \"type\": \"timeout\" }.\n" +
+            "Applies to graph/flowchart diagrams reliably; other Mermaid types (sequenceDiagram, erDiagram, classDiagram) are best-effort — node IDs may be opaque or extraction may fail.\n" +
+            "Only one wait_click() may be pending at a time — a second wait_click() or an arming wait_done() supersedes it, returning { \"ok\": true, \"type\": \"superseded\" } to the superseded call instead of waiting out the full timeout.\n" +
+            "Example — plain click: render({ type: \"mermaid\", payload: \"graph TD; A-->B\" }) → wait_click() → handle result\n" +
+            "Example — popup menu: wait_click({ node_actions: { \"B\": [\"Explain\", \"Drill down\"] } }) → user clicks B → selects action",
+        inputSchema: z.object({
+            node_actions: nodeActionsSchema
+                .optional()
+                .describe("Optional map of node ID → action labels. " +
+                "Nodes with a non-empty entry show a popup menu on click; user selects one action. " +
+                "Nodes not in the map accept a plain click (no popup). " +
+                "Edge clicks are always plain (no popup)."),
+        }),
+    }, async ({ node_actions }) => {
+        // Arm the browser click listener, passing the node_actions map (or empty map for plain click).
+        broadcast({ action: "set_node_actions", node_actions: node_actions ?? {}, enabled: true });
+        const event = await waitForClick();
+        // Disarm the browser.
+        broadcast({ action: "set_node_actions", enabled: false });
+        if (event.type === "timeout" || event.type === "superseded") {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: true, type: event.type }) }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: true,
+                        type: event.type,
+                        id: event.id,
+                        label: event.label,
+                        action: event.action,
+                    }),
+                }],
+        };
+    });
+    // wait_done() — block until the user clicks Done in the browser.
+    server.registerTool("wait_done", {
+        description: "Block until the user clicks the Done button in the whiteboard browser. " +
+            "Call this immediately after render() when you want the user to review the diagram before you continue. " +
+            'Returns { "ok": true } when the user signals they are ready. ' +
+            "Example flow: render(...) → wait_done() → continue lesson",
+        inputSchema: z.object({}),
+    }, async () => {
+        await waitForDone();
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true }) }],
+        };
+    });
+    // init_step_frames(frame_type, workspace, title?) — begin an incremental step-frames build.
+    server.registerTool("init_step_frames", {
+        description: "Begin a step-frames sequence — a step-through diagram built one frame at a time and navigable afterwards via step()/seek(). This is the only way to create a multi-frame sequence (render() is single-frame only).\n" +
+            "Creates an empty skeleton in server memory, pushes a 0-frame placeholder to the browser, and returns a unique ID.\n" +
+            "Protocol: init_step_frames() → append_frame() × N (browser updates after each append) → commit_step_frames() (finalizes snapshot + state).\n" +
+            "frame_type: content type shared by all frames (e.g. 'mermaid') — every frame in the sequence must currently be this same type.\n" +
+            "workspace: same rules as render() — required.\n" +
+            "The ID expires after 30 minutes of inactivity (no append_frame or commit_step_frames call).\n" +
+            "Each append_frame() call is validated and pushed to the browser individually — the user watches the sequence grow one frame at a time; interleave wait_done() after each append_frame() call for a paced, user-acknowledged reveal.\n" +
+            'Returns { "ok": true, "id": "<uuid>" }. Error if workspace is missing/invalid or frame_type is unsupported.\n' +
+            'Example: init_step_frames({ frame_type: "mermaid", workspace: "my-course", title: "TCP Handshake" })',
+        inputSchema: z.object({
+            frame_type: z
+                .enum(["mermaid", "svg", "html", "katex", "vega-lite"])
+                .describe("Content type shared by all frames."),
+            workspace: z
+                .string()
+                .describe("REQUIRED. Workspace name for snapshot routing. " +
+                "Alphanumeric, dashes, underscores, dots, spaces — no path separators or '..'."),
+            title: z.string().optional().describe("Optional label displayed above the canvas."),
+        }),
+    }, ({ frame_type, workspace, title }) => {
+        const workspaceResult = validateWorkspaceInput(workspace);
+        if (!workspaceResult.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: workspaceResult.error }) }],
+            };
+        }
+        const { id } = initStepFramesResult(frame_type, workspaceResult.workspace, title);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, id }) }],
+        };
+    });
+    // append_frame(id, payload, label?) — add one frame to an in-progress sequence.
+    server.registerTool("append_frame", {
+        description: "Append one frame to an in-progress step-frames sequence identified by id.\n" +
+            "payload is validated against type ?? the sequence's frame_type (same hard gate as render()).\n" +
+            "After each valid append, immediately pushes the accumulated partial step-frames sequence to the browser (live preview positioned at the latest frame).\n" +
+            "Invalid payloads are rejected before any broadcast; prior frames and browser state are preserved — fix and retry the frame.\n" +
+            'Returns { "ok": true, "frame_count": N }. Error if id is unknown/expired or payload fails validation.\n' +
+            'Example: append_frame({ id: "<uuid>", payload: "graph TD; A --> B", label: "Step 1" })\n' +
+            'Example — mixing types in one sequence: append_frame({ id: "<uuid>", payload: "E = mc^2", type: "katex" }) inside a sequence whose frame_type is "mermaid".',
+        inputSchema: z.object({
+            id: z.string().describe("Builder ID returned by init_step_frames()."),
+            payload: z.string().describe("Frame content — validated against type ?? the sequence's frame_type."),
+            label: z.string().optional().describe("Optional display caption for this frame."),
+            type: z
+                .enum(["mermaid", "svg", "html", "katex", "vega-lite"])
+                .optional()
+                .describe("Optional per-frame type override. Defaults to the sequence's frame_type when omitted — set this to mix content types within one sequence."),
+        }),
+    }, async ({ id, payload, label, type }) => {
+        const result = await appendFrameAndBroadcast(id, payload, label, type);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: result.ok, ...(result.ok ? { frame_count: result.frame_count } : { error: result.error }) }) }],
+        };
+    });
+    // commit_step_frames(id) — finalise and render the assembled sequence.
+    server.registerTool("commit_step_frames", {
+        description: "Finalise an in-progress step-frames sequence (finalization only — the browser already shows the sequence via append_frame live previews).\n" +
+            "Assembles the full step-frames JSON, writes a snapshot, updates in-memory canvas state (so export() works), cancels any running slideshow, and deletes the builder entry.\n" +
+            "Still sends a final WebSocket broadcast for consistency (handles clear() called between appends).\n" +
+            "After commit, export() returns the assembled full step-frames JSON. step() and seek() work on the committed sequence.\n" +
+            "The builder entry is deleted after commit — the ID cannot be reused.\n" +
+            "Optional node_to_frame: node ID → frame index map. When set, the browser attaches click listeners automatically — clicking a mapped node jumps directly to its frame (no wait_click() call needed). wait_click() overrides node_to_frame for the duration of its call.\n" +
+            'Returns { "ok": true }. Error if id is unknown/expired or the sequence has zero frames.\n' +
+            'Example: commit_step_frames({ id: "<uuid>" })\n' +
+            'Example with node_to_frame: commit_step_frames({ id: "<uuid>", node_to_frame: { "A": 0, "B": 1, "C": 2 } })',
+        inputSchema: z.object({
+            id: z.string().describe("Builder ID returned by init_step_frames()."),
+            node_to_frame: nodeToFrameSchema
+                .optional()
+                .describe("Optional node ID → frame index map for autonomous browser navigation on click."),
+        }),
+    }, ({ id, node_to_frame }) => {
+        const result = commitStepFramesResult(id, node_to_frame);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+        };
+    });
+    // export(id?) — return the current canvas source spec, or a past snapshot by UUID.
+    server.registerTool("export", {
+        description: "Return the current canvas source spec, or a past snapshot by UUID. " +
+            'Without id: returns verbatim last render() payload. Response: { "ok": true, "data": "<source>" }. ' +
+            "For step-frames: returns the full original frames JSON string (not the current frame). " +
+            'data is an empty string if the canvas is empty or was cleared. ' +
+            'With optional id (UUID returned by render() or commit_step_frames()): scans snapshot files for a record whose id field matches and returns its payload. ' +
+            'Error if id provided but no matching snapshot found: { "ok": false, "error": "graph not found" }. ' +
+            "Old snapshots without an id field are not addressable by this mechanism.",
+        inputSchema: z.object({
+            id: z.string().optional().describe("Optional UUID returned by a previous render() or commit_step_frames() call. " +
+                "When provided, retrieves that specific snapshot's payload instead of the current canvas state."),
+        }),
+    }, ({ id }) => {
+        if (id !== undefined && id !== "") {
+            const root = getSnapshotsRoot();
+            const payload = findSnapshotById(id, root);
+            if (payload === null) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ ok: false, error: "graph not found" }) }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: true, data: payload }) }],
+            };
+        }
+        const data = exportCanvas();
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ ok: true, data }) },
+            ],
+        };
+    });
+    // list_snapshots(workspace) — list a workspace's snapshots for agent-driven export selection.
+    server.registerTool("list_snapshots", {
+        description: "List the snapshots stored for a workspace, so you can choose which ones to export via export_html().\n" +
+            'Returns { "ok": true, "snapshots": [{ "id", "timestamp", "type", "title"? }] }, sorted newest-first.\n' +
+            "Returns an empty array if the workspace has no snapshots or does not exist.\n" +
+            'Example: list_snapshots({ workspace: "my-course" })',
+        inputSchema: z.object({
+            workspace: z
+                .string()
+                .describe("REQUIRED. Workspace name to list snapshots for. " +
+                "Alphanumeric, dashes, underscores, dots, spaces — no path separators or '..'."),
+        }),
+    }, ({ workspace }) => {
+        const workspaceResult = validateWorkspaceInput(workspace);
+        if (!workspaceResult.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: workspaceResult.error }) }],
+            };
+        }
+        const root = getSnapshotsRoot();
+        const snapshots = listSnapshots(workspaceResult.workspace, root);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, snapshots }) }],
+        };
+    });
+    // export_html(workspace, ids) — agent-facing HTML export, returned inline.
+    server.registerTool("export_html", {
+        description: "Export 1..N snapshots from a workspace to a single self-contained HTML document " +
+            "(agent-facing equivalent of the browser HistoryPanel's 'Export selected'). " +
+            "Discover snapshot ids first with list_snapshots(workspace).\n" +
+            "Returns the assembled HTML as a string, inline in this response — this tool has no " +
+            "filesystem access and never writes to disk. Dependencies (Mermaid, Bootstrap, KaTeX) " +
+            "are linked from a CDN rather than embedded, which is what keeps the response small enough " +
+            "to return inline; the resulting file requires network access to render correctly when opened. " +
+            "If you need a fully offline-capable export (or to save the file to a specific path), use the " +
+            "REST endpoint POST /export-html with { items, mode: \"offline\" } instead — it streams the " +
+            "response for the caller to save wherever it likes.\n" +
+            'Returns { "ok": true, "html": "<!DOCTYPE html>..." }.\n' +
+            'Example: export_html({ workspace: "my-course", ids: ["<uuid-1>", "<uuid-2>"] })',
+        inputSchema: z.object({
+            workspace: z
+                .string()
+                .describe("REQUIRED. Workspace the snapshot ids belong to. " +
+                "Alphanumeric, dashes, underscores, dots, spaces — no path separators or '..'."),
+            ids: z
+                .array(z.string())
+                .min(1)
+                .describe("Non-empty array of snapshot UUIDs (from list_snapshots()), all scoped to workspace."),
+        }),
+    }, async ({ workspace, ids }) => {
+        const workspaceResult = validateWorkspaceInput(workspace);
+        if (!workspaceResult.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: workspaceResult.error }) }],
+            };
+        }
+        if (ids.length === 0) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: "ids must be a non-empty array" }) }],
+            };
+        }
+        const validatedWorkspace = workspaceResult.workspace;
+        const root = getSnapshotsRoot();
+        const validItems = [];
+        for (const id of ids) {
+            const record = findSnapshotByIdInWorkspace(validatedWorkspace, id, root);
+            if (record !== null) {
+                validItems.push({ workspace: validatedWorkspace, id, record });
+            }
+        }
+        if (validItems.length === 0) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: "no valid items to export" }) }],
+            };
+        }
+        const { html } = await generateExportHtml(validItems, "cdn");
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, html }) }],
+        };
+    });
+    return server;
+}

package/dist/server/paths.js

@@ -0,0 +1,11 @@
+import { homedir } from "os";
+import { join } from "path";
+/**
+ * Canonical snapshots-root resolver (F5, NF22) — the single implementation of
+ * `WHITEBOARD_SNAPSHOTS_DIR ?? ~/.agent-whiteboard`, replacing 10 independent
+ * copies of this expression previously scattered across app.ts, mcp.ts,
+ * snapshot.ts, and viewport-cache.ts.
+ */
+export function getSnapshotsRoot() {
+    return process.env.WHITEBOARD_SNAPSHOTS_DIR ?? join(homedir(), ".agent-whiteboard");
+}

package/dist/server/persist.js

@@ -0,0 +1,56 @@
+// Persist-trigger vocabulary + the one shared finalize/persist write path
+// (v0.25). Consolidates the near-duplicate saveSnapshot()-plus-backstop logic
+// that used to live independently in render-core.ts (commitRenderResult,
+// commitStepFramesResult) and slideshow.ts (finalizeSlideshow). See
+// docs/04_architecture.md §9.3 D2 and §9.4 (FR20/B15 — slideshow silently
+// never persisted because persistence was opt-in, not a required decision).
+import { saveSnapshot } from "./snapshot-writer.js";
+/**
+ * Source of truth for "which trigger does this command use" — the registry
+ * `getPersistTrigger()` enforces. Adding a new command without registering an
+ * entry here throws loudly instead of silently never persisting (the
+ * historical FR20/B15 bug: slideshow() had no entry anywhere and simply
+ * never called saveSnapshot()).
+ */
+const COMMAND_PERSIST_TRIGGERS = {
+    render: "immediate",
+    append_frame: "transient",
+    commit_step_frames: "on-finalize",
+    "slideshow-end": "on-finalize",
+    step: "never",
+    seek: "never",
+    clear: "never",
+    "history-load": "never",
+};
+/** Returns the declared trigger for a command, or throws if none is registered. */
+export function getPersistTrigger(command) {
+    const trigger = COMMAND_PERSIST_TRIGGERS[command];
+    if (trigger === undefined) {
+        throw new Error(`persist: no trigger declared for command "${command}" — every command path must register one of immediate | on-finalize | transient | never in server/persist.ts before it can persist anything`);
+    }
+    return trigger;
+}
+/**
+ * The one shared write path. Looks up `command`'s declared trigger:
+ * `immediate`/`on-finalize` write now; `transient`/`never` are deliberate
+ * no-ops. F10's "a write failure must never block rendering" backstop lives
+ * here once — `saveSnapshot()` already catches its own errors internally,
+ * this try/catch is a deliberate caller-level guarantee on top of that.
+ */
+export function persistContent(command, content) {
+    const trigger = getPersistTrigger(command);
+    if (trigger === "transient" || trigger === "never")
+        return {};
+    try {
+        const rawPayload = content.frames.length > 1 ? content.rawPayload : undefined;
+        const id = saveSnapshot(content.frames, { title: content.title, node_to_frame: content.nodeToFrame, workspace: content.workspace }, rawPayload, content.id);
+        return { id };
+    }
+    catch {
+        return {};
+    }
+}
+/** Assembles the step-frames JSON payload shape shared by commit/finalize paths. */
+export function assembleStepFramesPayload(frameType, frames) {
+    return JSON.stringify({ frame_type: frameType, frames });
+}

package/dist/server/presentation.js

@@ -0,0 +1,5 @@
+// Unified content model (U2, v0.26 — docs/04_architecture.md §9.1).
+// Frame is the one atomic renderable; Presentation is an ordered list of them.
+// Not yet the internal canvas-state representation — session.ts/canvasStore.ts
+// adopt this in Sprint 40/41. For now it's the shape validateFrame() validates.
+export {};