agent-whiteboard 1.0.0

package/dist/server/events.js

@@ -0,0 +1,90 @@
+// In-process event bus for user interaction signals.
+import { EventEmitter } from 'node:events';
+const bus = new EventEmitter();
+const WAIT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+// ── Done signal ───────────────────────────────────────────────────────────────
+let doneArmed = false;
+export function getDoneArmed() {
+    return doneArmed;
+}
+// Lazily imported to avoid circular dependency (ws.ts imports events.ts indirectly).
+let _broadcastFn = null;
+export function setBroadcastFn(fn) {
+    _broadcastFn = fn;
+}
+function broadcastDoneArmed(armed) {
+    _broadcastFn?.({ action: 'set_done_armed', armed });
+}
+/** Signal that the user clicked Done — wakes all pending waitForDone() calls. */
+export function signalDone() {
+    bus.emit('done');
+}
+/** Resolve when the user clicks Done (or after the timeout). */
+export function waitForDone() {
+    doneArmed = true;
+    broadcastDoneArmed(true);
+    return new Promise((resolve) => {
+        const onDone = () => {
+            clearTimeout(timer);
+            doneArmed = false;
+            broadcastDoneArmed(false);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            bus.off('done', onDone);
+            doneArmed = false;
+            broadcastDoneArmed(false);
+            resolve();
+        }, WAIT_TIMEOUT_MS);
+        bus.once('done', onDone);
+    });
+}
+// At most one pending waitForClick() at a time.
+let clickResolve = null;
+let clickTimer = null;
+/** Signal that the user clicked a node/edge — resolves the pending waitForClick(). No-op if none pending. */
+export function signalClick(event) {
+    if (!clickResolve)
+        return;
+    const resolve = clickResolve;
+    clickResolve = null;
+    if (clickTimer) {
+        clearTimeout(clickTimer);
+        clickTimer = null;
+    }
+    resolve(event);
+}
+/**
+ * Resolve when the user clicks a node/edge (or after the timeout).
+ * At most one call may be pending — a second call cancels and replaces the first.
+ */
+export function waitForClick() {
+    // Cancel any existing listener.
+    if (clickResolve) {
+        clickResolve({ type: 'timeout', id: '', label: '', action: null });
+        clickResolve = null;
+    }
+    if (clickTimer) {
+        clearTimeout(clickTimer);
+        clickTimer = null;
+    }
+    return new Promise((resolve) => {
+        clickResolve = resolve;
+        clickTimer = setTimeout(() => {
+            clickResolve = null;
+            clickTimer = null;
+            resolve({ type: 'timeout', id: '', label: '', action: null });
+        }, WAIT_TIMEOUT_MS);
+    });
+}
+/** Reset click state — for use in tests only. */
+export function resetClick() {
+    if (clickResolve) {
+        clickResolve({ type: 'timeout', id: '', label: '', action: null });
+        clickResolve = null;
+    }
+    if (clickTimer) {
+        clearTimeout(clickTimer);
+        clickTimer = null;
+    }
+}

package/dist/server/export-html.js

@@ -0,0 +1,461 @@
+import { readFileSync } from "fs";
+import { createRequire } from "module";
+import { createHash } from "crypto";
+import { Window } from "happy-dom";
+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>`;
+}
+function renderKatex(payload) {
+    return katex.renderToString(payload, { displayMode: true, throwOnError: false });
+}
+async function renderVegaLite(payload) {
+    const spec = JSON.parse(payload);
+    const vegaSpec = vl.compile(spec).spec;
+    const view = new vega.View(vega.parse(vegaSpec), { renderer: "none" });
+    return view.toSVG();
+}
+function renderSvgPayload(payload, purify) {
+    return purify.sanitize(payload, { USE_PROFILES: { svg: true } });
+}
+function renderHtmlPayload(payload, purify) {
+    return purify.sanitize(payload, { USE_PROFILES: { html: true } });
+}
+/**
+ * Pure string-transform primitive: wraps a CSS string in `@scope (<selector-list>)
+ * { ... }`, limiting selector matching to the given anchor ids' subtrees. Has no
+ * knowledge of *why* it's being called — used both to contain a payload's own
+ * embedded <style> tag (scopeEmbeddedStyles(), single anchor) and to scope the
+ * shared Bootstrap stylesheet across every html-type item/frame anchor in one
+ * export (v0.31 Sprint 70, multi-anchor).
+ */
+export function scopeCss(css, anchorIds) {
+    const selectorList = anchorIds.map((id) => `#${id}`).join(", ");
+    return `@scope (${selectorList}) {\n${css}\n}`;
+}
+/**
+ * Contains any <style> tag embedded in rendered "html"/"svg" content to the
+ * element it's meant to style, instead of leaking document-wide. A <style>
+ * element is normally document-scoped regardless of DOM nesting — a payload
+ * shipping its own theme stylesheet (e.g. a markdown->HTML converter's
+ * readable-width CSS, `body { max-width: 900px }`) would otherwise silently
+ * override the whole export's layout. `@scope` limits selector matching to
+ * `anchorId`'s subtree: a `body {}` rule then matches nothing (no `<body>`
+ * descendant exists there), while `table {}`/`code {}`/etc. still apply
+ * correctly to the payload's own content. Real root cause of bug B20 ("main
+ * too narrow") — see `01`/`03`/`04`. An earlier fix (`FORBID_TAGS: ["style"]`)
+ * closed the leak but also discarded the payload's own legitimate table/code
+ * formatting living in the same <style> block; scoping keeps both.
+ */
+function scopeEmbeddedStyles(html, anchorId) {
+    return html.replace(/<style>([\s\S]*?)<\/style>/gi, (_, css) => `<style>${scopeCss(css, [anchorId])}</style>`);
+}
+async function renderByType(type, payload, purify) {
+    switch (type) {
+        case "mermaid":
+            return renderMermaidContainer(payload);
+        case "katex":
+            return renderKatex(payload);
+        case "vega-lite":
+            return renderVegaLite(payload);
+        case "svg":
+            return renderSvgPayload(payload, purify);
+        case "html":
+            return renderHtmlPayload(payload, purify);
+        default:
+            throw new Error(`unsupported render type: ${type}`);
+    }
+}
+/**
+ * Renders a snapshot's already-resolved `frames[]` (v0.26 Sprint 43 — no more
+ * `JSON.parse(payload)` of a step-frames envelope; a sequence is just an
+ * array with more than one element). A single frame renders as one content
+ * block; multiple frames render as a step-frames section, each frame using
+ * its own already-resolved `type` (no `frame_type` fallback needed).
+ */
+async function renderFrames(frames, purify) {
+    if (frames.length > 1) {
+        const rendered = [];
+        for (const frame of frames) {
+            try {
+                const html = await renderByType(frame.type, frame.payload, purify);
+                rendered.push({ label: frame.label, html, type: frame.type });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                rendered.push({ label: frame.label, html: `<p class="export-error">${escapeHtml(msg)}</p>`, type: frame.type });
+            }
+        }
+        return { kind: "stepFrames", frames: rendered };
+    }
+    try {
+        const html = await renderByType(frames[0].type, frames[0].payload, purify);
+        return { kind: "html", html, type: frames[0].type };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { kind: "error", message: msg };
+    }
+}
+// ── HTML assembly ──────────────────────────────────────────────────────────
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function formatTimestampHuman(iso) {
+    try {
+        return new Date(iso).toLocaleString("en-US", {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+        });
+    }
+    catch {
+        return iso;
+    }
+}
+let cachedKatexCss;
+function getKatexCss() {
+    if (cachedKatexCss !== undefined)
+        return cachedKatexCss;
+    try {
+        const req = createRequire(import.meta.url);
+        const cssPath = req.resolve("katex/dist/katex.min.css");
+        cachedKatexCss = readFileSync(cssPath, "utf-8");
+    }
+    catch {
+        cachedKatexCss = "";
+    }
+    return cachedKatexCss;
+}
+let cachedBootstrapCss;
+/**
+ * Bootstrap's color system (alert/badge/table variants, etc.) is defined
+ * almost entirely via CSS custom properties set on `:root`. `@scope` only
+ * matches elements within the scope root's own subtree — `:root` (the
+ * `<html>` element) is an ancestor of the scope root, never a descendant,
+ * so a bare `:root` rule inside `@scope (#anchor) { ... }` never matches
+ * and its custom properties are silently never set. `:scope`, inside an
+ * `@scope` block, refers to the scope root element itself — properties set
+ * there still inherit normally to every descendant. Without this rewrite,
+ * colors/backgrounds silently fall back to initial values while
+ * non-variable properties (padding, etc.) keep working, producing
+ * unstyled-looking Bootstrap components with no error. Found via manual
+ * browser verification, v0.31 Sprint 71/70.
+ */
+function getBootstrapCss() {
+    if (cachedBootstrapCss !== undefined)
+        return cachedBootstrapCss;
+    try {
+        const req = createRequire(import.meta.url);
+        const cssPath = req.resolve("bootstrap/dist/css/bootstrap.min.css");
+        const raw = readFileSync(cssPath, "utf-8");
+        cachedBootstrapCss = raw.replace(/:root/g, ":scope");
+    }
+    catch {
+        cachedBootstrapCss = "";
+    }
+    return cachedBootstrapCss;
+}
+let cachedMermaidBundle;
+function getMermaidBundle() {
+    if (cachedMermaidBundle !== undefined)
+        return cachedMermaidBundle;
+    const req = createRequire(import.meta.url);
+    const bundlePath = req.resolve("mermaid/dist/mermaid.min.js");
+    const source = readFileSync(bundlePath, "utf-8");
+    // Guard against a literal "</script" sequence inside the bundle prematurely
+    // closing the inline <script> tag when parsed as HTML.
+    cachedMermaidBundle = source.replace(/<\/script/gi, "<\\/script");
+    return cachedMermaidBundle;
+}
+const cachedCdnAssets = new Map();
+/**
+ * Builds a pinned-version, SRI-hashed jsdelivr reference for an npm package's
+ * dist file. The hash is computed from the *locally installed* copy (same
+ * `package.json` version jsdelivr's npm mirror serves) rather than hardcoded,
+ * so it never drifts out of sync when mermaid/bootstrap/katex are
+ * version-bumped — no manual regeneration step required.
+ */
+function getCdnAsset(pkgName, distRelPath) {
+    const cacheKey = `${pkgName}/${distRelPath}`;
+    const cached = cachedCdnAssets.get(cacheKey);
+    if (cached)
+        return cached;
+    const req = createRequire(import.meta.url);
+    const filePath = req.resolve(`${pkgName}/${distRelPath}`);
+    const buffer = readFileSync(filePath);
+    const version = req(`${pkgName}/package.json`).version;
+    const integrity = `sha384-${createHash("sha384").update(buffer).digest("base64")}`;
+    const asset = {
+        url: `https://cdn.jsdelivr.net/npm/${pkgName}@${version}/${distRelPath}`,
+        integrity,
+    };
+    cachedCdnAssets.set(cacheKey, asset);
+    return asset;
+}
+function getMermaidCdnAsset() {
+    return getCdnAsset("mermaid", "dist/mermaid.min.js");
+}
+function getBootstrapCdnAsset() {
+    return getCdnAsset("bootstrap", "dist/css/bootstrap.min.css");
+}
+function getKatexCdnAsset() {
+    return getCdnAsset("katex", "dist/katex.min.css");
+}
+function cdnScriptTag(asset) {
+    return `<script src="${asset.url}" integrity="${asset.integrity}" crossorigin="anonymous"></script>`;
+}
+function cdnStylesheetTag(asset) {
+    return `<link rel="stylesheet" href="${asset.url}" integrity="${asset.integrity}" crossorigin="anonymous">`;
+}
+const LAYOUT_CSS = `
+  * { box-sizing: border-box; }
+  body { font-family: system-ui, -apple-system, sans-serif; margin: 0; display: flex; background: #f9f9f9; }
+  nav { width: 240px; min-width: 200px; padding: 24px 16px; background: #fff; border-right: 1px solid #e0e0e0; position: sticky; top: 0; height: 100vh; overflow-y: auto; flex-shrink: 0; }
+  nav h2 { font-size: 12px; color: #888; text-transform: uppercase; letter-spacing: 0.06em; margin: 0 0 12px; }
+  nav ul { list-style: none; margin: 0; padding: 0; }
+  nav li { margin: 2px 0; }
+  nav a { font-size: 13px; color: #2980b9; text-decoration: none; display: block; padding: 2px 0 2px 8px; }
+  nav a:hover { text-decoration: underline; }
+  nav .toc-ws { font-weight: 600; color: #333; font-size: 12px; margin-top: 10px; padding-left: 0 !important; }
+  nav .toc-ws > a { font-weight: 600; color: #333; padding-left: 0; }
+  nav .toc-frames { padding-left: 12px; }
+  nav .toc-frames a { font-size: 12px; color: #5b8ab8; }
+  main { flex: 1; padding: 32px 40px; min-width: 0; }
+  .workspace-section { margin-bottom: 48px; }
+  .workspace-heading { font-size: 20px; font-weight: 700; color: #222; margin: 0 0 20px; padding-bottom: 8px; border-bottom: 2px solid #e0e0e0; }
+  .item-section { margin-bottom: 28px; padding: 20px; background: #fff; border: 1px solid #e8e8e8; border-radius: 6px; box-shadow: 0 1px 3px rgba(0,0,0,0.04); overflow-x: auto; }
+  .item-heading { font-size: 15px; font-weight: 600; color: #333; margin: 0 0 4px; }
+  .item-meta { font-size: 12px; color: #888; margin: 0 0 16px; display: flex; align-items: center; gap: 8px; }
+  .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-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; }
+  pre, code { max-width: 100%; }
+`.trim();
+function assembleHtml(items, hasKatex, hasMermaid, mode) {
+    // Group by workspace, order workspaces by earliest item timestamp.
+    const wsMap = new Map();
+    for (const item of items) {
+        if (!wsMap.has(item.workspace))
+            wsMap.set(item.workspace, []);
+        wsMap.get(item.workspace).push(item);
+    }
+    for (const list of wsMap.values()) {
+        list.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    }
+    const workspaces = [...wsMap.entries()].sort(([, al], [, bl]) => al[0].timestamp.localeCompare(bl[0].timestamp));
+    let counter = 0;
+    const nextId = () => `item-${++counter}`;
+    let tocHtml = "";
+    let mainHtml = "";
+    const htmlAnchorIds = [];
+    for (const [ws, wsList] of workspaces) {
+        const wsAnchor = `ws-${ws.replace(/[^a-zA-Z0-9]/g, "-")}`;
+        tocHtml += `<li class="toc-ws"><a href="#${wsAnchor}">${escapeHtml(ws)}</a><ul>`;
+        mainHtml += `<section class="workspace-section" id="${wsAnchor}">`;
+        mainHtml += `<h2 class="workspace-heading">${escapeHtml(ws)}</h2>`;
+        for (const item of wsList) {
+            const itemId = nextId();
+            const label = item.title ?? formatTimestampHuman(item.timestamp);
+            const { content } = item;
+            if (content.kind === "stepFrames") {
+                // Parent link points at frame 0's anchor — same target as that
+                // frame's own submenu entry below (B22 in `01`).
+                tocHtml += `<li><a href="#${itemId}-frame-0">${escapeHtml(label)}</a><ul class="toc-frames">`;
+                for (let i = 0; i < content.frames.length; i++) {
+                    const frameLabel = content.frames[i].label ?? `Frame ${i + 1}`;
+                    tocHtml += `<li><a href="#${itemId}-frame-${i}">${escapeHtml(frameLabel)}</a></li>`;
+                }
+                tocHtml += `</ul></li>`;
+            }
+            else {
+                tocHtml += `<li><a href="#${itemId}">${escapeHtml(label)}</a></li>`;
+            }
+            mainHtml += `<section class="item-section" id="${itemId}">`;
+            mainHtml += `<h3 class="item-heading">${escapeHtml(item.title ?? "—")}</h3>`;
+            mainHtml += `<p class="item-meta"><span class="type-badge">${escapeHtml(item.type)}</span><span>${escapeHtml(formatTimestampHuman(item.timestamp))}</span></p>`;
+            if (content.kind === "error") {
+                mainHtml += `<p class="export-error">${escapeHtml(content.message)}</p>`;
+            }
+            else if (content.kind === "stepFrames") {
+                for (let i = 0; i < content.frames.length; i++) {
+                    const frame = content.frames[i];
+                    const frameId = `${itemId}-frame-${i}`;
+                    if (frame.type === "html")
+                        htmlAnchorIds.push(frameId);
+                    mainHtml += `<section class="frame-section" id="${frameId}">`;
+                    mainHtml += `<h4 class="frame-heading">${escapeHtml(frame.label ?? `Frame ${i + 1}`)}</h4>`;
+                    mainHtml += scopeEmbeddedStyles(frame.html, frameId);
+                    mainHtml += `</section>`;
+                }
+            }
+            else {
+                if (content.type === "html")
+                    htmlAnchorIds.push(itemId);
+                mainHtml += scopeEmbeddedStyles(content.html, itemId);
+            }
+            mainHtml += `</section>`;
+        }
+        tocHtml += `</ul></li>`;
+        mainHtml += `</section>`;
+    }
+    const hasBootstrap = htmlAnchorIds.length > 0;
+    const katexBlock = hasKatex
+        ? mode === "cdn"
+            ? `${cdnStylesheetTag(getKatexCdnAsset())}\n`
+            : `<style>${getKatexCss()}</style>\n`
+        : "";
+    // Bootstrap's bare-element scoping (@scope, bug B20) only works when the
+    // CSS is inlined as a <style> block — a CDN <link> can't be @scope-wrapped.
+    // cdn mode links Bootstrap unscoped anyway (accepted risk, see O4 in `02`);
+    // offline mode keeps the inlined+scoped behavior unchanged.
+    const bootstrapBlock = hasBootstrap
+        ? mode === "cdn"
+            ? `${cdnStylesheetTag(getBootstrapCdnAsset())}\n`
+            : `<style>${scopeCss(getBootstrapCss(), htmlAnchorIds)}</style>\n`
+        : "";
+    const mermaidInitScript = `<script>
+document.addEventListener("DOMContentLoaded", function () {
+  mermaid.initialize({ startOnLoad: false, securityLevel: "strict" });
+  mermaid.run({ querySelector: ".mermaid" });
+});
+</script>
+`;
+    const mermaidBlock = hasMermaid
+        ? mode === "cdn"
+            ? `${cdnScriptTag(getMermaidCdnAsset())}\n${mermaidInitScript}`
+            : `<script>${getMermaidBundle()}</script>\n${mermaidInitScript}`
+        : "";
+    const csp = mode === "cdn"
+        ? "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data:; object-src 'none'; base-uri 'none'"
+        : "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; object-src 'none'; base-uri 'none'";
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta http-equiv="Content-Security-Policy" content="${csp}">
+<title>Whiteboard Export</title>
+<style>${LAYOUT_CSS}</style>
+${katexBlock}${bootstrapBlock}</head>
+<body>
+<nav>
+<h2>Contents</h2>
+<ul>${tocHtml}</ul>
+</nav>
+<main>${mainHtml}</main>
+${mermaidBlock}</body>
+</html>`;
+}
+// ── Download filename ──────────────────────────────────────────────────────
+function buildDownloadFilename(workspaces) {
+    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())}`;
+    if (workspaces.length === 1) {
+        const sanitized = workspaces[0].replace(/[^a-zA-Z0-9_.-]/g, "-").slice(0, 24);
+        return `${sanitized}-${ts}.html`;
+    }
+    return `export-${ts}.html`;
+}
+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);
+    const purify = DOMPurify(win);
+    const rendered = [];
+    try {
+        for (const { workspace, record } of items) {
+            const content = await renderFrames(record.frames, purify);
+            rendered.push({
+                workspace,
+                type: badgeType(record.frames),
+                timestamp: record.timestamp,
+                title: record.title,
+                content,
+            });
+        }
+    }
+    finally {
+        restoreGlobals(savedGlobals);
+        win.close();
+    }
+    const hasKatex = itemsIncludeType(items, "katex");
+    const hasMermaid = itemsIncludeType(items, "mermaid");
+    const html = assembleHtml(rendered, hasKatex, hasMermaid, mode);
+    const uniqueWorkspaces = [...new Set(items.map((i) => i.workspace))];
+    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/index.js

@@ -0,0 +1,79 @@
+// Entry point — starts HTTP + WebSocket + MCP servers.
+//
+// Exports startServer() so it can be called as a library (e.g. from
+// bin/cli.js, the npx production entrypoint) without the auto-start-on-import
+// side effect below firing twice. Auto-start only happens when this file is
+// itself the process's main module (`tsx watch server/index.ts`, or a direct
+// `node dist/server/index.js` invocation) — see the isMainModule() check.
+import { serve } from "@hono/node-server";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { pathToFileURL } from "node:url";
+import { WebSocketServer } from "ws";
+import { createApp } from "./app.js";
+import { createMcpServer } from "./mcp.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
+// is enforced here rather than left as a documentation-only claim.
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+function assertLoopbackHost(host) {
+    if (LOOPBACK_HOSTS.has(host))
+        return;
+    if (process.env.ALLOW_NON_LOOPBACK === "1")
+        return;
+    throw new Error(`Refusing to bind to non-loopback HOST "${host}": this server has no authentication on any ` +
+        "endpoint and is designed for single-user, local-only use (see docs/02_assumptions-and-risks.md). " +
+        "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 HOST = process.env.HOST ?? "localhost";
+    assertLoopbackHost(HOST);
+    const app = createApp({ staticRoot: options.staticRoot });
+    // ── MCP (SSE) ──────────────────────────────────────────────────────────────
+    const mcpTransports = new Map();
+    app.get("/mcp", async (c) => {
+        const { incoming: req, outgoing: res } = c.env;
+        const transport = new SSEServerTransport("/mcp/message", res);
+        const sessionId = transport.sessionId;
+        mcpTransports.set(sessionId, transport);
+        transport.onclose = () => mcpTransports.delete(sessionId);
+        // Each connection needs its own McpServer instance — the SDK only allows
+        // one transport per instance and throws if connect() is called again.
+        const mcpServer = createMcpServer();
+        await mcpServer.connect(transport);
+        return new Promise(() => {
+            req.on("close", () => mcpTransports.delete(sessionId));
+        });
+    });
+    app.post("/mcp/message", async (c) => {
+        const sessionId = c.req.query("sessionId");
+        if (!sessionId)
+            return c.json({ error: "missing sessionId" }, 400);
+        const transport = mcpTransports.get(sessionId);
+        if (!transport)
+            return c.json({ error: "session not found" }, 404);
+        const { incoming: req, outgoing: res } = c.env;
+        await transport.handlePostMessage(req, res);
+        return new Promise(() => undefined);
+    });
+    // ── Start ──────────────────────────────────────────────────────────────────
+    const server = serve({ fetch: app.fetch, hostname: HOST, port: PORT }, () => {
+        console.log(`agent-whiteboard running at http://${HOST}:${PORT}`);
+        console.log(`MCP endpoint:  http://${HOST}:${PORT}/mcp`);
+        console.log(`WebSocket:     ws://${HOST}:${PORT}/stream`);
+        options.onReady?.();
+    });
+    const wss = new WebSocketServer({ server: server, path: "/stream" });
+    wss.on("connection", (ws) => {
+        addClient(ws);
+    });
+    return server;
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    return entry !== undefined && import.meta.url === pathToFileURL(entry).href;
+}
+if (isMainModule()) {
+    startServer();
+}