agent-whiteboard 1.0.4 → 1.2.0

package/dist/server/export-html.js

@@ -1,47 +1,12 @@
 import { readFileSync } from "fs";
 import { createRequire } from "module";
 import { createHash } from "crypto";
-import { Window } from "happy-dom";
+import { JSDOM } from "jsdom";
 import katex from "katex";
 import * as vl from "vega-lite";
 import * as vega from "vega";
 import DOMPurify from "dompurify";
 import { badgeType } from "./snapshot-reader.js";
-function saveGlobals() {
-    const keys = [
-        "document", "window", "CSSStyleSheet", "SVGElement", "HTMLElement",
-        "Element", "DOMParser", "MutationObserver",
-        "requestAnimationFrame", "cancelAnimationFrame",
-    ];
-    const saved = new Map();
-    for (const k of keys)
-        saved.set(k, global[k]);
-    return saved;
-}
-function setGlobals(win) {
-    const g = global;
-    const w = win;
-    g["document"] = win.document;
-    g["window"] = win;
-    g["CSSStyleSheet"] = w["CSSStyleSheet"];
-    g["SVGElement"] = w["SVGElement"];
-    g["HTMLElement"] = w["HTMLElement"];
-    g["Element"] = w["Element"];
-    g["DOMParser"] = w["DOMParser"];
-    g["MutationObserver"] = w["MutationObserver"];
-    g["requestAnimationFrame"] = (fn) => setTimeout(() => fn(Date.now()), 16);
-    g["cancelAnimationFrame"] = clearTimeout;
-}
-function restoreGlobals(saved) {
-    for (const [k, v] of saved) {
-        if (v === undefined) {
-            delete global[k];
-        }
-        else {
-            global[k] = v;
-        }
-    }
-}
 // ── Renderers ──────────────────────────────────────────────────────────────
 function renderMermaidContainer(payload) {
     return `<pre class="mermaid">${escapeHtml(payload)}</pre>`;
@@ -59,7 +24,13 @@ function renderSvgPayload(payload, purify) {
     return purify.sanitize(payload, { USE_PROFILES: { svg: true } });
 }
 function renderHtmlPayload(payload, purify) {
-    return purify.sanitize(payload, { USE_PROFILES: { html: true } });
+    // ADD_TAGS: the "html" profile's default allowlist excludes <style> (unlike
+    // the "svg" profile below, which already allows it) — explicit here since
+    // scopeEmbeddedStyles() (B20) depends on <style> surviving sanitization.
+    // FORCE_BODY: without it, a leading <style> is parsed as implicit <head>
+    // content and silently dropped from DOMPurify's body-only output — ADD_TAGS
+    // alone isn't enough.
+    return purify.sanitize(payload, { USE_PROFILES: { html: true }, ADD_TAGS: ["style"], FORCE_BODY: true });
 }
 /**
  * Pure string-transform primitive: wraps a CSS string in `@scope (<selector-list>)
@@ -102,6 +73,9 @@ async function renderByType(type, payload, purify) {
             return renderSvgPayload(payload, purify);
         case "html":
             return renderHtmlPayload(payload, purify);
+        case "quiz":
+            // Quizzes are interactive and carry no static representation (F50) — export notes it instead of failing.
+            return '<p class="export-note">This item is an interactive quiz and is not included in HTML exports.</p>';
         default:
             throw new Error(`unsupported render type: ${type}`);
     }
@@ -276,6 +250,7 @@ const LAYOUT_CSS = `
   .type-badge { background: #e8f4fd; color: #2980b9; padding: 1px 7px; border-radius: 10px; font-size: 11px; font-weight: 600; }
   .frame-section { margin-top: 16px; padding: 12px 16px; border: 1px solid #f0f0f0; border-radius: 4px; background: #fafafa; overflow-x: auto; }
   .frame-heading { font-size: 12px; color: #777; margin: 0 0 10px; font-style: italic; }
+  .export-note { color: #555; background: #f4f5f6; padding: 10px 14px; border-radius: 4px; border-left: 3px solid #aaa; font-size: 13px; margin: 0; }
   .export-error { color: #c0392b; background: #fdf0f0; padding: 10px 14px; border-radius: 4px; border-left: 3px solid #e74c3c; font-size: 13px; margin: 0; }
   svg { max-width: 100%; height: auto; }
   table { max-width: 100%; border-collapse: collapse; }
@@ -412,10 +387,24 @@ function itemsIncludeType(items, type) {
     return items.some(({ record }) => record.frames.some((f) => f.type === type));
 }
 // ── Public entrypoint ──────────────────────────────────────────────────────
-async function generateExportHtmlInner(items, mode) {
-    const win = new Window();
-    const savedGlobals = saveGlobals();
-    setGlobals(win);
+/**
+ * Each call builds its own jsdom `Window` and passes it explicitly to
+ * `DOMPurify(win)` — sanitization runs entirely against that instance, never
+ * against Node's global object. KaTeX's `renderToString()` and Vega's
+ * `View.toSVG()` (via `renderer: "none"`) need no DOM at all. Because
+ * nothing here reads or writes `global.document`/`window`, concurrent calls
+ * (reachable from both `POST /export-html` and the `export_html` MCP tool,
+ * see bug B14 in `01`) can never stomp on each other's state — no
+ * serialization queue is needed.
+ *
+ * jsdom, not happy-dom: DOMPurify 3.4.8+ silently fails to sanitize
+ * descendant nodes against a happy-dom `Window` (upstream incompatibility,
+ * capricorn86/happy-dom#1810) — <script> tags and on* attributes pass
+ * through unstripped. DOMPurify's own maintainers recommend jsdom for
+ * server-side use; confirmed this sanitizes correctly against jsdom.
+ */
+export async function generateExportHtml(items, mode) {
+    const win = new JSDOM("").window;
     const purify = DOMPurify(win);
     const rendered = [];
     try {
@@ -431,7 +420,6 @@ async function generateExportHtmlInner(items, mode) {
         }
     }
     finally {
-        restoreGlobals(savedGlobals);
         win.close();
     }
     const hasKatex = itemsIncludeType(items, "katex");
@@ -441,21 +429,3 @@ async function generateExportHtmlInner(items, mode) {
     const downloadFilename = buildDownloadFilename(uniqueWorkspaces);
     return { html, downloadFilename };
 }
-// generateExportHtmlInner() patches global DOM state (document, window, ...)
-// for the duration of a call so happy-dom-backed rendering works, then
-// restores it in a `finally`. That save/set/restore isn't reentrant: two
-// overlapping calls (POST /export-html and the export_html MCP tool can run
-// concurrently) each save/restore against whatever the *other* call happened
-// to have in place at that moment, which can leave global DOM state pointing
-// at an already-closed Window once both settle (B14). A simple queue forces
-// calls to run one at a time, in the order they were made, so only one
-// call's globals are ever active at once.
-let exportQueue = Promise.resolve();
-export function generateExportHtml(items, mode) {
-    const result = exportQueue.then(() => generateExportHtmlInner(items, mode));
-    // Chain the queue off a version that never rejects, so one failed export
-    // doesn't permanently wedge every export queued after it; the caller of
-    // generateExportHtml() still sees the original rejection via `result`.
-    exportQueue = result.then(() => undefined, () => undefined);
-    return result;
-}

package/dist/server/export-zip.js

@@ -0,0 +1,83 @@
+import { createRequire } from "module";
+import archiver from "archiver";
+import { findSnapshotFileByIdInWorkspace } from "./snapshot-reader.js";
+/**
+ * Reads own package.json version via createRequire (works whether this
+ * module runs as server/export-zip.ts under tsx, one level below repo root,
+ * or as the compiled dist/server/export-zip.js, two levels below).
+ */
+function getAppVersion() {
+    const req = createRequire(import.meta.url);
+    for (const rel of ["../package.json", "../../package.json"]) {
+        try {
+            const pkg = req(rel);
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return "unknown";
+}
+function buildZipDownloadFilename(workspace) {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    const ts = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
+        `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const sanitized = workspace.replace(/[^a-zA-Z0-9_.-]/g, "-").slice(0, 24);
+    return `${sanitized}-${ts}.zip`;
+}
+/**
+ * Builds a downloadable zip (F36) of the given snapshots' raw JSON files
+ * plus a generated manifest.json — no rendering/sanitization pass, unlike
+ * generateExportHtml(). Every item must share the same workspace (the
+ * manifest format is single-workspace); a mixed-workspace list is rejected
+ * rather than silently exporting a subset. Ids that don't resolve to a file
+ * on disk are silently skipped (matching /export-html's per-item leniency);
+ * an all-miss request is rejected. Viewport-cache data is never included —
+ * this only ever touches the snapshot JSON files themselves.
+ */
+export async function generateExportZip(items, root) {
+    if (items.length === 0) {
+        return { ok: false, error: "items must be a non-empty array" };
+    }
+    const workspace = items[0].workspace;
+    if (items.some((item) => item.workspace !== workspace)) {
+        return { ok: false, error: "all items must belong to the same workspace" };
+    }
+    const files = [];
+    for (const item of items) {
+        const found = await findSnapshotFileByIdInWorkspace(workspace, item.id, root);
+        if (found !== null)
+            files.push(found);
+    }
+    if (files.length === 0) {
+        return { ok: false, error: "no valid items to export" };
+    }
+    const manifest = {
+        formatVersion: 1,
+        workspace,
+        exportedAt: new Date().toISOString(),
+        appVersion: getAppVersion(),
+        snapshots: files.map((f) => f.filename),
+    };
+    const archive = archiver("zip", { zlib: { level: 9 } });
+    const chunks = [];
+    archive.on("data", (chunk) => chunks.push(chunk));
+    const done = new Promise((resolve, reject) => {
+        archive.on("end", resolve);
+        archive.on("error", reject);
+    });
+    for (const f of files) {
+        archive.append(f.raw, { name: f.filename });
+    }
+    archive.append(JSON.stringify(manifest, null, 2), { name: "manifest.json" });
+    await archive.finalize();
+    await done;
+    return {
+        ok: true,
+        zip: Buffer.concat(chunks),
+        downloadFilename: buildZipDownloadFilename(workspace),
+    };
+}

package/dist/server/import-zip.js

@@ -0,0 +1,196 @@
+import { mkdir, mkdtemp, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import extract from "extract-zip";
+import { z } from "zod";
+import { isValidSnapshotFilename, validateWorkspaceInput } from "./validate.js";
+import { findSnapshotFileByIdInWorkspace } from "./snapshot-reader.js";
+const DEFAULT_LIMITS = {
+    maxEntryUncompressedBytes: 20 * 1024 * 1024, // 20MB — generous for a snapshot JSON file
+    maxTotalUncompressedBytes: 200 * 1024 * 1024, // 200MB total across the whole archive
+    maxEntries: 2000,
+};
+const manifestSchema = z.object({
+    formatVersion: z.number(),
+    workspace: z.string().min(1),
+    exportedAt: z.string(),
+    appVersion: z.string(),
+    snapshots: z.array(z.string()),
+});
+function parseIdTimestamp(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            id: typeof parsed.id === "string" ? parsed.id : undefined,
+            timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * F40 — picks the filename of the newest (by ISO-8601 timestamp string
+ * comparison, same convention as snapshot-reader.ts's own sort) entry among
+ * everything actually added/updated by this import, so the caller can load
+ * it and switch the client's active workspace as a side effect.
+ */
+function pickNewestFilename(entries) {
+    const withTimestamp = entries.filter((e) => e.timestamp !== undefined);
+    if (withTimestamp.length === 0)
+        return undefined;
+    return withTimestamp.reduce((newest, e) => (e.timestamp > newest.timestamp ? e : newest)).filename;
+}
+/**
+ * F39/NF55 — imports an uploaded workspace-export zip (F36's format).
+ * Extracts to a fresh temp directory first (never directly into the live
+ * snapshots tree) via `extract-zip`, which rejects any entry whose resolved
+ * path would escape that directory (zip-slip) as part of its own
+ * extraction — confirmed empirically, not just by reading its docs. Only
+ * `manifest.json` and the files it explicitly lists are ever trusted; a
+ * listed filename is re-validated with `isValidSnapshotFilename()` before
+ * being joined into any path, since the manifest itself is just JSON text
+ * an attacker could otherwise use to point outside the temp/destination
+ * directory even though the zip *entries* themselves are already safe.
+ */
+export async function importZip(zipBuffer, targetWorkspaceInput, mode, root, limits = {}) {
+    const { maxEntryUncompressedBytes, maxTotalUncompressedBytes, maxEntries } = { ...DEFAULT_LIMITS, ...limits };
+    const validated = validateWorkspaceInput(targetWorkspaceInput);
+    if (!validated.ok) {
+        return { ok: false, error: validated.error };
+    }
+    const targetWorkspace = validated.workspace;
+    const tempRoot = await mkdtemp(join(tmpdir(), "agent-whiteboard-import-"));
+    const zipPath = join(tempRoot, "upload.zip");
+    const extractDir = join(tempRoot, "extracted");
+    try {
+        await writeFile(zipPath, zipBuffer);
+        await mkdir(extractDir, { recursive: true });
+        let totalUncompressed = 0;
+        let entryCount = 0;
+        try {
+            await extract(zipPath, {
+                dir: extractDir,
+                onEntry: (entry) => {
+                    entryCount++;
+                    if (entryCount > maxEntries) {
+                        throw new Error("zip contains too many entries");
+                    }
+                    if (entry.uncompressedSize > maxEntryUncompressedBytes) {
+                        throw new Error("zip contains an entry that is too large");
+                    }
+                    totalUncompressed += entry.uncompressedSize;
+                    if (totalUncompressed > maxTotalUncompressedBytes) {
+                        throw new Error("zip's total uncompressed size is too large");
+                    }
+                },
+            });
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : "failed to extract zip" };
+        }
+        let manifestRaw;
+        try {
+            manifestRaw = await readFile(join(extractDir, "manifest.json"), "utf-8");
+        }
+        catch {
+            return { ok: false, error: "manifest.json is missing from the zip" };
+        }
+        let manifestJson;
+        try {
+            manifestJson = JSON.parse(manifestRaw);
+        }
+        catch {
+            return { ok: false, error: "manifest.json is not valid JSON" };
+        }
+        const manifestResult = manifestSchema.safeParse(manifestJson);
+        if (!manifestResult.success) {
+            return { ok: false, error: "manifest.json is malformed" };
+        }
+        const manifest = manifestResult.data;
+        const destDir = join(root, targetWorkspace);
+        const destExists = await stat(destDir).then(() => true, () => false);
+        // F40 — every added/updated file's {filename, timestamp}, so the newest
+        // one (by timestamp) can be reported back for the client's post-import
+        // POST /snapshots/load. Skipped files are deliberately excluded — nothing
+        // about them changed.
+        const changed = [];
+        if (mode === "create") {
+            if (destExists) {
+                return { ok: false, error: `workspace "${targetWorkspace}" already exists` };
+            }
+            await mkdir(destDir, { recursive: true });
+            let added = 0;
+            for (const filename of manifest.snapshots) {
+                if (!isValidSnapshotFilename(filename))
+                    continue;
+                const srcPath = join(extractDir, filename);
+                let raw;
+                try {
+                    raw = await readFile(srcPath, "utf-8");
+                }
+                catch {
+                    continue;
+                }
+                await writeFile(join(destDir, filename), raw, "utf-8");
+                added++;
+                changed.push({ filename, timestamp: parseIdTimestamp(raw).timestamp });
+            }
+            return { ok: true, workspace: targetWorkspace, added, updated: 0, skipped: 0, newestFilename: pickNewestFilename(changed) };
+        }
+        // mode === "merge"
+        if (!destExists) {
+            return { ok: false, error: `workspace "${targetWorkspace}" does not exist` };
+        }
+        let added = 0;
+        let updated = 0;
+        let skipped = 0;
+        for (const filename of manifest.snapshots) {
+            if (!isValidSnapshotFilename(filename))
+                continue;
+            let raw;
+            try {
+                raw = await readFile(join(extractDir, filename), "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const incoming = parseIdTimestamp(raw);
+            if (incoming.id === undefined) {
+                // Legacy/id-less (pre-v0.11) — always imported as new, never matched.
+                await writeFile(join(destDir, filename), raw, "utf-8");
+                added++;
+                changed.push({ filename, timestamp: incoming.timestamp });
+                continue;
+            }
+            const existing = await findSnapshotFileByIdInWorkspace(targetWorkspace, incoming.id, root);
+            if (existing === null) {
+                await writeFile(join(destDir, filename), raw, "utf-8");
+                added++;
+                changed.push({ filename, timestamp: incoming.timestamp });
+                continue;
+            }
+            const existingTimestamp = parseIdTimestamp(existing.raw).timestamp;
+            if (existingTimestamp === incoming.timestamp) {
+                skipped++;
+                continue;
+            }
+            if (existingTimestamp !== undefined && incoming.timestamp !== undefined && existingTimestamp > incoming.timestamp) {
+                // Destination already has the newer version — nothing to do.
+                skipped++;
+                continue;
+            }
+            // Incoming is newer — overwrite (at most one file per id afterward).
+            if (existing.filename !== filename) {
+                await unlink(join(destDir, existing.filename)).catch(() => { });
+            }
+            await writeFile(join(destDir, filename), raw, "utf-8");
+            updated++;
+            changed.push({ filename, timestamp: incoming.timestamp });
+        }
+        return { ok: true, workspace: targetWorkspace, added, updated, skipped, newestFilename: pickNewestFilename(changed) };
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true });
+    }
+}

package/dist/server/index.js

@@ -11,6 +11,7 @@ import { pathToFileURL } from "node:url";
 import { WebSocketServer } from "ws";
 import { createApp } from "./app.js";
 import { createMcpServer } from "./mcp.js";
+import { parsePort } from "./port.js";
 import { addClient } from "./ws.js";
 // F27 (v1.0) — the server has no authentication on any endpoint (accepted
 // trade-off, see docs/02_assumptions-and-risks.md), so single-user/local-only
@@ -26,7 +27,7 @@ function assertLoopbackHost(host) {
         "Set ALLOW_NON_LOOPBACK=1 if you understand the risk and want to override this.");
 }
 export function startServer(options = {}) {
-    const PORT = parseInt(process.env.PORT ?? "3000", 10);
+    const PORT = parsePort(process.env.PORT, 3000, "PORT");
     const HOST = process.env.HOST ?? "localhost";
     assertLoopbackHost(HOST);
     const app = createApp({ staticRoot: options.staticRoot });

package/dist/server/mcp.js

@@ -4,10 +4,11 @@ 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 { nodeActionsSchema, nodeToFrameSchema, validateFrame, validateRenderPayload } from "./validate.js";
 import { getSnapshotsRoot } from "./paths.js";
 import { cancelSlideshow, startSlideshow } from "./slideshow.js";
 import { waitForClick, waitForDone } from "./interaction.js";
+import { waitForQuiz } from "./quiz-submission.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";
@@ -25,18 +26,19 @@ export function createMcpServer() {
             '  • "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' +
+            '  • "quiz"        — JSON quiz: { title?, questions: [{ id, text, kind: "single"|"multiple", options: [{ id, text, correct?, weight? }], scoring?: "all_or_nothing"|"partial", points? }] }. Either every question marks its correct option(s) (inline: the browser scores it) or none does (deferred). "partial" scoring (multiple-choice only) needs a weight on each correct option, summing to 1. Valid in render() only — not in slideshow() or step-frames.\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"])
+                .enum(["mermaid", "svg", "html", "katex", "vega-lite", "quiz"])
                 .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."),
+                "For vega-lite and quiz: must be valid JSON. For svg/html/katex: any string."),
             options: z
                 .object({
                 workspace: z.string().describe("REQUIRED. Workspace name for snapshot routing. " +
@@ -55,7 +57,7 @@ export function createMcpServer() {
             };
         }
         const { workspace } = workspaceResult;
-        const validationError = await validateFrame({ type, payload });
+        const validationError = await validateRenderPayload(type, payload);
         if (validationError) {
             return {
                 content: [{ type: "text", text: JSON.stringify({ ok: false, error: validationError }) }],
@@ -76,9 +78,9 @@ export function createMcpServer() {
                 .enum(["next", "prev"])
                 .describe('"next" to advance, "prev" to rewind.'),
         }),
-    }, ({ direction }) => {
+    }, async ({ direction }) => {
         return {
-            content: [{ type: "text", text: JSON.stringify(stepAndBroadcast(direction)) }],
+            content: [{ type: "text", text: JSON.stringify(await stepAndBroadcast(direction)) }],
         };
     });
     // seek(frame) — jump the step cursor to an arbitrary frame index.
@@ -90,9 +92,9 @@ export function createMcpServer() {
         inputSchema: z.object({
             frame: z.number().int().nonnegative().describe("Zero-based frame index to jump to."),
         }),
-    }, ({ frame }) => {
+    }, async ({ frame }) => {
         return {
-            content: [{ type: "text", text: JSON.stringify(seekAndBroadcast(frame)) }],
+            content: [{ type: "text", text: JSON.stringify(await seekAndBroadcast(frame)) }],
         };
     });
     // clear() — reset the canvas.
@@ -224,6 +226,19 @@ export function createMcpServer() {
             content: [{ type: "text", text: JSON.stringify({ ok: true }) }],
         };
     });
+    // wait_quiz() — block until the user submits the quiz currently on the canvas.
+    server.registerTool("wait_quiz", {
+        description: 'Block until the user clicks Submit on the quiz currently on the whiteboard (render({ type: "quiz", ... })). ' +
+            'Returns { "ok": true, "type": "submitted", "questions": <the quiz>, "answers": [{ "questionId": "...", "selected": ["optionId", ...] }] } ' +
+            "— for an inline quiz also a client-computed \"score\": { earned, possible }; for a deferred quiz (no answer key in the payload) you evaluate and score the answers yourself. " +
+            "A submission made before you call wait_quiz() is kept and returned immediately, as long as that quiz is still on screen. " +
+            'Times out after 10 minutes with { "ok": true, "type": "timeout" }; a second wait_quiz() supersedes a pending one ({ "type": "superseded" }). ' +
+            'Returns { "ok": false, "error": "..." } if no quiz is on the canvas. ' +
+            "Example flow: render({ type: \"quiz\", ... }) → wait_quiz() → evaluate answers",
+        inputSchema: z.object({}),
+    }, async () => ({
+        content: [{ type: "text", text: JSON.stringify(await waitForQuiz()) }],
+    }));
     // 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" +
@@ -317,10 +332,10 @@ export function createMcpServer() {
             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 }) => {
+    }, async ({ id }) => {
         if (id !== undefined && id !== "") {
             const root = getSnapshotsRoot();
-            const payload = findSnapshotById(id, root);
+            const payload = await findSnapshotById(id, root);
             if (payload === null) {
                 return {
                     content: [{ type: "text", text: JSON.stringify({ ok: false, error: "graph not found" }) }],
@@ -349,7 +364,7 @@ export function createMcpServer() {
                 .describe("REQUIRED. Workspace name to list snapshots for. " +
                 "Alphanumeric, dashes, underscores, dots, spaces — no path separators or '..'."),
         }),
-    }, ({ workspace }) => {
+    }, async ({ workspace }) => {
         const workspaceResult = validateWorkspaceInput(workspace);
         if (!workspaceResult.ok) {
             return {
@@ -357,7 +372,7 @@ export function createMcpServer() {
             };
         }
         const root = getSnapshotsRoot();
-        const snapshots = listSnapshots(workspaceResult.workspace, root);
+        const snapshots = await listSnapshots(workspaceResult.workspace, root);
         return {
             content: [{ type: "text", text: JSON.stringify({ ok: true, snapshots }) }],
         };
@@ -402,7 +417,7 @@ export function createMcpServer() {
         const root = getSnapshotsRoot();
         const validItems = [];
         for (const id of ids) {
-            const record = findSnapshotByIdInWorkspace(validatedWorkspace, id, root);
+            const record = await findSnapshotByIdInWorkspace(validatedWorkspace, id, root);
             if (record !== null) {
                 validItems.push({ workspace: validatedWorkspace, id, record });
             }

package/dist/server/port.js

@@ -0,0 +1,18 @@
+/**
+ * Shared port-env-var validation (NF52) — used by index.ts's PORT and
+ * channel.ts/app.ts's CHANNEL_PORT, so an invalid value fails fast with a
+ * clear error instead of a low-level bind/listen/fetch failure.
+ *
+ * 0 is accepted (not just 1–65535): Node's listen()/serve() treat it as "let
+ * the OS assign a free port", which tests/unit/server/index.test.ts already
+ * relies on for ephemeral test binding.
+ */
+export function parsePort(value, fallback, envVarName) {
+    if (value === undefined)
+        return fallback;
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`Invalid ${envVarName} "${value}": must be an integer between 0 and 65535.`);
+    }
+    return port;
+}