agent-whiteboard 1.0.3 → 1.1.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>)
@@ -412,10 +383,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 +416,6 @@ async function generateExportHtmlInner(items, mode) {
         }
     }
     finally {
-        restoreGlobals(savedGlobals);
         win.close();
     }
     const hasKatex = itemsIncludeType(items, "katex");
@@ -441,21 +425,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

@@ -76,9 +76,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 +90,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.
@@ -317,10 +317,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 +349,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 +357,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 +402,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;
+}

package/dist/server/render-core.js

@@ -125,7 +125,7 @@ export async function applyLoadedSnapshotResult(frames, workspace, title, nodeTo
     // 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;
+    const viewport = snapshotId !== undefined ? await 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();
@@ -161,7 +161,7 @@ export async function applyLoadedSnapshotResult(frames, workspace, title, nodeTo
  * 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) {
+export async function stepAndBroadcast(direction) {
     const result = stepCursor(direction);
     if (!result) {
         return { ok: false, error: "no step-frames sequence is loaded" };
@@ -174,7 +174,7 @@ export function stepAndBroadcast(direction) {
         // 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);
+        const viewport = await 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 };
@@ -183,7 +183,7 @@ export function stepAndBroadcast(direction) {
  * 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) {
+export async function seekAndBroadcast(frame) {
     const state = getCanvas();
     if (!isStepSequence(state)) {
         return { ok: false, error: "no step-frames sequence is loaded" };
@@ -207,7 +207,7 @@ export function seekAndBroadcast(frame) {
         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),
+        viewport: await getViewport(resolvedId, frame),
     });
     return { ok: true, current_frame: frame, total_frames: total };
 }

package/dist/server/routes/export.js

@@ -0,0 +1,95 @@
+import { exportCanvas } from "../session.js";
+import { findSnapshotById, findSnapshotByIdInWorkspace } from "../snapshot-reader.js";
+import { validateWorkspaceInput } from "../render-core.js";
+import { generateExportHtml } from "../export-html.js";
+import { generateExportZip } from "../export-zip.js";
+import { getSnapshotsRoot } from "../paths.js";
+export function registerExportRoutes(app) {
+    app.get("/export", async (c) => {
+        const id = c.req.query("id");
+        if (id !== undefined && id !== "") {
+            const root = getSnapshotsRoot();
+            const payload = await findSnapshotById(id, root);
+            if (payload === null) {
+                return c.json({ ok: false, error: "graph not found" }, 404);
+            }
+            return c.json({ ok: true, data: payload });
+        }
+        return c.json({ ok: true, data: exportCanvas() });
+    });
+    // ── HTML Export (v0.13) ────────────────────────────────────────────────────
+    app.post("/export-html", async (c) => {
+        const body = await c.req.json();
+        if (!Array.isArray(body.items) || body.items.length === 0) {
+            return c.json({ ok: false, error: "items must be a non-empty array" }, 400);
+        }
+        // Default cdn (v0.32, F23): offline (fully embedded, today's pre-v0.32
+        // behavior) is opt-in via mode: "offline"; any other value falls back to cdn.
+        const mode = body.mode === "offline" ? "offline" : "cdn";
+        const root = getSnapshotsRoot();
+        const validItems = [];
+        for (const item of body.items) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const { workspace, id } = item;
+            if (typeof workspace !== "string")
+                continue;
+            const validated = validateWorkspaceInput(workspace);
+            if (!validated.ok)
+                continue;
+            if (typeof id !== "string")
+                continue;
+            const record = await findSnapshotByIdInWorkspace(validated.workspace, id, root);
+            if (record === null)
+                continue;
+            validItems.push({ workspace: validated.workspace, id, record });
+        }
+        if (validItems.length === 0) {
+            return c.json({ ok: false, error: "no valid items to export" }, 400);
+        }
+        const { html, downloadFilename } = await generateExportHtml(validItems, mode);
+        return new Response(html, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                "Content-Disposition": `attachment; filename="${downloadFilename}"`,
+            },
+        });
+    });
+    // ── Zip Export (v1.6, F36) ───────────────────────────────────────────────
+    app.post("/export-zip", async (c) => {
+        const body = await c.req.json();
+        if (!Array.isArray(body.items) || body.items.length === 0) {
+            return c.json({ ok: false, error: "items must be a non-empty array" }, 400);
+        }
+        const zipItems = [];
+        for (const item of body.items) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const { workspace, id } = item;
+            if (typeof workspace !== "string")
+                continue;
+            const validated = validateWorkspaceInput(workspace);
+            if (!validated.ok)
+                continue;
+            if (typeof id !== "string")
+                continue;
+            zipItems.push({ workspace: validated.workspace, id });
+        }
+        if (zipItems.length === 0) {
+            return c.json({ ok: false, error: "no valid items to export" }, 400);
+        }
+        const root = getSnapshotsRoot();
+        const result = await generateExportZip(zipItems, root);
+        if (!result.ok) {
+            return c.json({ ok: false, error: result.error }, 400);
+        }
+        return new Response(new Uint8Array(result.zip), {
+            status: 200,
+            headers: {
+                "Content-Type": "application/zip",
+                "Content-Disposition": `attachment; filename="${result.downloadFilename}"`,
+            },
+        });
+    });
+}

package/dist/server/routes/import.js

@@ -0,0 +1,24 @@
+import { bodyLimit } from "hono/body-limit";
+import { importZip } from "../import-zip.js";
+import { getSnapshotsRoot } from "../paths.js";
+// NF55 — a per-route override, larger than app.ts's global 10MB JSON cap
+// (app.ts excludes this path from that global middleware so the two caps
+// don't stack — the stricter one would otherwise always win).
+export const IMPORT_MAX_BODY_SIZE_BYTES = 50 * 1024 * 1024;
+export function registerImportRoutes(app) {
+    app.post("/import", bodyLimit({ maxSize: IMPORT_MAX_BODY_SIZE_BYTES }), async (c) => {
+        const body = await c.req.parseBody();
+        const file = body["file"];
+        if (!(file instanceof File)) {
+            return c.json({ ok: false, error: "file is required" }, 400);
+        }
+        const mode = body["mode"] === "merge" ? "merge" : "create";
+        const buffer = Buffer.from(await file.arrayBuffer());
+        const root = getSnapshotsRoot();
+        const result = await importZip(buffer, body["targetWorkspace"], mode, root);
+        if (!result.ok) {
+            return c.json({ ok: false, error: result.error }, 400);
+        }
+        return c.json(result);
+    });
+}