agent-whiteboard 1.0.4 → 1.2.0

package/dist/server/quiz-submission.js

@@ -0,0 +1,116 @@
+// Quiz submit → wait_quiz handoff (F48, F49 in docs/03 §10).
+//
+// POST /quiz/submit stores the user's answers; wait_quiz / POST /wait-quiz
+// long-poll for them. Modeled on wait_click's single-flight interaction, but
+// carrying a payload. A submission made while no wait is armed is retained and
+// handed to the next wait_quiz — but only while the same quiz is still on the
+// canvas (identity of the Presentation object, which every render / history
+// load replaces).
+import { createSingleFlightInteraction } from "./interaction.js";
+import { parseQuizPayload } from "./quiz.js";
+import { getCanvas } from "./session.js";
+const interaction = createSingleFlightInteraction({ type: "timeout" }, { type: "superseded" });
+let waiting = false;
+/** Id of the newest wait — a superseded wait's cleanup must not clear `waiting` for its successor. */
+let latestWait = 0;
+let retained = null;
+function getActiveQuiz() {
+    const presentation = getCanvas().presentation;
+    const frame = presentation?.frames[0];
+    if (!presentation || !frame || frame.type !== "quiz")
+        return null;
+    const parsed = parseQuizPayload(frame.payload);
+    if (!parsed.ok)
+        return null;
+    return { presentation, quiz: parsed.quiz, mode: parsed.mode };
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export function submitQuiz(rawAnswers, rawScore) {
+    const active = getActiveQuiz();
+    if (!active)
+        return { ok: false, error: "no quiz on the canvas" };
+    if (!Array.isArray(rawAnswers))
+        return { ok: false, error: "answers must be an array" };
+    const byQuestion = new Map();
+    for (const a of rawAnswers) {
+        if (!isRecord(a) || typeof a.questionId !== "string" || !Array.isArray(a.selected) || !a.selected.every((s) => typeof s === "string")) {
+            return { ok: false, error: "each answer must be { questionId: string, selected: string[] }" };
+        }
+        if (byQuestion.has(a.questionId))
+            return { ok: false, error: `duplicate answer for question "${a.questionId}"` };
+        byQuestion.set(a.questionId, a.selected);
+    }
+    const answers = [];
+    for (const q of active.quiz.questions) {
+        const selected = byQuestion.get(q.id);
+        if (!selected || selected.length === 0)
+            return { ok: false, error: `question "${q.id}" is unanswered` };
+        if (new Set(selected).size !== selected.length)
+            return { ok: false, error: `duplicate options selected for question "${q.id}"` };
+        const known = new Set(q.options.map((o) => o.id));
+        if (!selected.every((s) => known.has(s)))
+            return { ok: false, error: `unknown option for question "${q.id}"` };
+        if (q.kind === "single" && selected.length !== 1)
+            return { ok: false, error: `question "${q.id}" is single-choice` };
+        answers.push({ questionId: q.id, selected });
+    }
+    for (const id of byQuestion.keys()) {
+        if (!active.quiz.questions.some((q) => q.id === id))
+            return { ok: false, error: `unknown question "${id}"` };
+    }
+    let score;
+    if (active.mode === "inline" && rawScore !== undefined) {
+        if (!isRecord(rawScore) || typeof rawScore.earned !== "number" || typeof rawScore.possible !== "number"
+            || !Number.isFinite(rawScore.earned) || !Number.isFinite(rawScore.possible)
+            || rawScore.earned < 0 || rawScore.possible < rawScore.earned) {
+            return { ok: false, error: "score must be { earned, possible } with 0 <= earned <= possible" };
+        }
+        score = { earned: rawScore.earned, possible: rawScore.possible };
+    }
+    const submission = {
+        presentation: active.presentation,
+        questions: active.quiz,
+        answers,
+        ...(score ? { score } : {}),
+    };
+    if (waiting) {
+        interaction.resolve({ type: "submitted", submission });
+    }
+    else {
+        retained = submission;
+    }
+    return { ok: true };
+}
+function toResult(s) {
+    return { ok: true, type: "submitted", questions: s.questions, answers: s.answers, ...(s.score ? { score: s.score } : {}) };
+}
+/** Long-polls for the user's submission (10-minute timeout, shared with wait_done/wait_click). */
+export async function waitForQuiz() {
+    const active = getActiveQuiz();
+    if (!active)
+        return { ok: false, error: "no quiz on the canvas — call render({ type: \"quiz\", ... }) first" };
+    if (retained) {
+        const r = retained;
+        retained = null;
+        if (r.presentation === active.presentation)
+            return toResult(r);
+    }
+    const myWait = ++latestWait;
+    waiting = true;
+    try {
+        const event = await interaction.await();
+        return event.type === "submitted" ? toResult(event.submission) : { ok: true, type: event.type };
+    }
+    finally {
+        if (myWait === latestWait)
+            waiting = false;
+    }
+}
+/** Drops retained/pending state — for tests only. */
+export function resetQuizSubmission() {
+    retained = null;
+    interaction.reset();
+    waiting = false;
+}

package/dist/server/quiz.js

@@ -0,0 +1,110 @@
+// Quiz payload parsing + validation (F44, F45, F47 in docs/03 §10).
+//
+// A quiz is a single-frame `render()` payload: JSON describing questions with
+// predefined options. Mode is derived from the answer key (F45): every
+// question has a `correct` option → "inline" (client scores); none do →
+// "deferred" (the agent scores via wait_quiz); a mix is rejected.
+const WEIGHT_EPSILON = 1e-6;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function fail(error) {
+    return { ok: false, error: `invalid quiz payload: ${error}` };
+}
+export function parseQuizPayload(payload) {
+    let raw;
+    try {
+        raw = JSON.parse(payload);
+    }
+    catch {
+        return fail("payload must be valid JSON");
+    }
+    if (!isRecord(raw))
+        return fail("payload must be a JSON object");
+    if (raw.title !== undefined && typeof raw.title !== "string")
+        return fail("title must be a string");
+    if (!Array.isArray(raw.questions) || raw.questions.length === 0) {
+        return fail("questions must be a non-empty array");
+    }
+    const questionIds = new Set();
+    let keyedCount = 0;
+    for (const [qi, q] of raw.questions.entries()) {
+        const where = `questions[${qi}]`;
+        if (!isRecord(q))
+            return fail(`${where} must be an object`);
+        if (typeof q.id !== "string" || q.id === "")
+            return fail(`${where}.id must be a non-empty string`);
+        if (questionIds.has(q.id))
+            return fail(`duplicate question id "${q.id}"`);
+        questionIds.add(q.id);
+        if (typeof q.text !== "string" || q.text === "")
+            return fail(`${where}.text must be a non-empty string`);
+        if (q.kind !== "single" && q.kind !== "multiple")
+            return fail(`${where}.kind must be "single" or "multiple"`);
+        if (q.scoring !== undefined && q.scoring !== "all_or_nothing" && q.scoring !== "partial") {
+            return fail(`${where}.scoring must be "all_or_nothing" or "partial"`);
+        }
+        if (q.scoring === "partial" && q.kind !== "multiple") {
+            return fail(`${where}: partial scoring is only valid for kind "multiple"`);
+        }
+        if (q.points !== undefined && (typeof q.points !== "number" || !Number.isFinite(q.points) || q.points <= 0)) {
+            return fail(`${where}.points must be a positive number`);
+        }
+        if (!Array.isArray(q.options) || q.options.length < 2) {
+            return fail(`${where}.options must be an array of at least 2 options`);
+        }
+        const optionIds = new Set();
+        let correctCount = 0;
+        let weightSum = 0;
+        let weightedCount = 0;
+        for (const [oi, o] of q.options.entries()) {
+            const ow = `${where}.options[${oi}]`;
+            if (!isRecord(o))
+                return fail(`${ow} must be an object`);
+            if (typeof o.id !== "string" || o.id === "")
+                return fail(`${ow}.id must be a non-empty string`);
+            if (optionIds.has(o.id))
+                return fail(`duplicate option id "${o.id}" in question "${q.id}"`);
+            optionIds.add(o.id);
+            if (typeof o.text !== "string" || o.text === "")
+                return fail(`${ow}.text must be a non-empty string`);
+            if (o.correct !== undefined && typeof o.correct !== "boolean")
+                return fail(`${ow}.correct must be a boolean`);
+            if (o.weight !== undefined) {
+                if (typeof o.weight !== "number" || !Number.isFinite(o.weight) || o.weight <= 0) {
+                    return fail(`${ow}.weight must be a positive number`);
+                }
+                if (o.correct !== true)
+                    return fail(`${ow}: weight is only valid on a correct option`);
+                if (q.scoring !== "partial")
+                    return fail(`${ow}: weight requires scoring "partial"`);
+                weightSum += o.weight;
+                weightedCount++;
+            }
+            if (o.correct === true)
+                correctCount++;
+        }
+        if (correctCount > 0)
+            keyedCount++;
+        if (correctCount > 0 && q.kind === "single" && correctCount !== 1) {
+            return fail(`question "${q.id}" is single-choice but has ${correctCount} correct options`);
+        }
+        if (correctCount > 0 && q.scoring === "partial") {
+            if (weightedCount !== correctCount) {
+                return fail(`question "${q.id}": every correct option needs a weight under partial scoring`);
+            }
+            if (Math.abs(weightSum - 1) > WEIGHT_EPSILON) {
+                return fail(`question "${q.id}": correct option weights must sum to 1 (got ${weightSum})`);
+            }
+        }
+    }
+    if (keyedCount !== 0 && keyedCount !== raw.questions.length) {
+        return fail("answer key is mixed: either every question has a correct option (inline) or none does (deferred)");
+    }
+    return { ok: true, quiz: raw, mode: keyedCount === 0 ? "deferred" : "inline" };
+}
+/** Returns null on success, an error string on failure (validateFrame convention). */
+export function validateQuizPayload(payload) {
+    const result = parseQuizPayload(payload);
+    return result.ok ? null : result.error;
+}

package/dist/server/render-core.js

@@ -5,7 +5,7 @@ import { cancelSlideshow } from "./slideshow.js";
 import { broadcastReplace, broadcastStepFrames } from "./ws.js";
 import { generateSnapshotId } from "./snapshot-writer.js";
 import { assembleStepFramesPayload, persistContent } from "./persist.js";
-import { validateFrame } from "./validate.js";
+import { validateFrame, validateRenderPayload } from "./validate.js";
 import { getCanvas, isStepSequence, seekStepFrame, setCanvas, setLastWorkspace, setStepFrames, stepCursor } from "./session.js";
 import { appendFrame, commitBuilder, createBuilder } from "./step-frames-builder.js";
 import { getViewport } from "./viewport-cache.js";
@@ -115,7 +115,8 @@ export function commitStepFramesResult(id, nodeToFrame) {
  */
 export async function applyLoadedSnapshotResult(frames, workspace, title, nodeToFrame, snapshotId, rawPayload) {
     for (const frame of frames) {
-        const validationError = await validateFrame(frame);
+        // A quiz is a single-frame render() type (F44): valid on its own, never inside a multi-frame sequence.
+        const validationError = frames.length === 1 ? await validateRenderPayload(frame.type, frame.payload) : await validateFrame(frame);
         if (validationError) {
             return { ok: false, error: validationError };
         }
@@ -125,7 +126,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 +162,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 +175,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 +184,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 +208,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);
+    });
+}

package/dist/server/routes/quiz.js

@@ -0,0 +1,12 @@
+import { submitQuiz, waitForQuiz } from "../quiz-submission.js";
+export function registerQuizRoutes(app) {
+    // Browser → server: the user's answers (and, for an inline quiz, the
+    // client-computed score). Resolves a pending wait_quiz, or is retained for the next one.
+    app.post("/quiz/submit", async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const result = submitQuiz(body.answers, body.score);
+        return c.json(result, result.ok ? 200 : 400);
+    });
+    // REST twin of the MCP wait_quiz tool.
+    app.post("/wait-quiz", async (c) => c.json(await waitForQuiz()));
+}

package/dist/server/routes/render.js

@@ -0,0 +1,184 @@
+import { signalClick, signalDone, waitForClick, waitForDone } from "../interaction.js";
+import { clearCanvas } from "../session.js";
+import { broadcast } from "../ws.js";
+import { FRAME_TYPES, RENDER_TYPES, nodeActionsSchema, nodeToFrameSchema, validateRenderPayload } from "../validate.js";
+import { cancelSlideshow } from "../slideshow.js";
+import { appendFrameAndBroadcast, commitRenderResult, commitStepFramesResult, initStepFramesResult, seekAndBroadcast, stepAndBroadcast, validateWorkspaceInput, } from "../render-core.js";
+import { setViewport } from "../viewport-cache.js";
+import { parsePort } from "../port.js";
+export function registerRenderRoutes(app) {
+    app.post("/render", async (c) => {
+        const body = await c.req.json();
+        const workspaceResult = validateWorkspaceInput(body.options?.workspace);
+        if (!workspaceResult.ok) {
+            return c.json({ ok: false, error: workspaceResult.error }, 400);
+        }
+        const { workspace } = workspaceResult;
+        if (typeof body.payload !== "string") {
+            return c.json({ ok: false, error: "payload must be a string" }, 400);
+        }
+        if (!RENDER_TYPES.includes(body.type)) {
+            return c.json({ ok: false, error: `type must be one of: ${RENDER_TYPES.join(", ")}` }, 400);
+        }
+        const type = body.type;
+        const { payload } = body;
+        const title = body.options?.title;
+        const validationError = await validateRenderPayload(type, payload);
+        if (validationError) {
+            return c.json({ ok: false, error: validationError });
+        }
+        const result = commitRenderResult(type, payload, workspace, title);
+        return c.json(result);
+    });
+    app.post("/step", async (c) => {
+        const body = await c.req.json();
+        if (body.direction !== "next" && body.direction !== "prev") {
+            return c.json({ ok: false, error: 'direction must be "next" or "prev"' }, 400);
+        }
+        return c.json(await stepAndBroadcast(body.direction));
+    });
+    app.post("/seek", async (c) => {
+        const body = await c.req.json();
+        if (typeof body.frame !== "number" || !Number.isInteger(body.frame)) {
+            return c.json({ ok: false, error: "frame must be an integer" }, 400);
+        }
+        return c.json(await seekAndBroadcast(body.frame));
+    });
+    app.post("/clear", (c) => {
+        cancelSlideshow({ persist: false }); // clear() must never produce a snapshot (F10)
+        clearCanvas();
+        broadcast({ action: "clear" });
+        return c.json({ ok: true });
+    });
+    // ── Incremental step-frames builder (v0.8) ───────────────────────────────────
+    app.post("/step-frames/init", async (c) => {
+        const body = await c.req.json();
+        if (typeof body.frame_type !== "string" || !FRAME_TYPES.includes(body.frame_type)) {
+            return c.json({
+                ok: false,
+                error: `frame_type must be one of: ${FRAME_TYPES.join(", ")}`,
+            }, 400);
+        }
+        const workspaceResult = validateWorkspaceInput(body.workspace);
+        if (!workspaceResult.ok) {
+            return c.json({ ok: false, error: workspaceResult.error }, 400);
+        }
+        const { workspace } = workspaceResult;
+        const title = typeof body.title === "string" ? body.title : undefined;
+        const { id } = initStepFramesResult(body.frame_type, workspace, title);
+        return c.json({ ok: true, id });
+    });
+    app.post("/step-frames/:id/frame", async (c) => {
+        const id = c.req.param("id");
+        const body = await c.req.json();
+        if (typeof body.payload !== "string") {
+            return c.json({ ok: false, error: "payload must be a string" }, 400);
+        }
+        const label = typeof body.label === "string" ? body.label : undefined;
+        const type = typeof body.type === "string" ? body.type : undefined;
+        const result = await appendFrameAndBroadcast(id, body.payload, label, type);
+        if (!result.ok) {
+            return c.json(result, result.error.includes("not found or expired") ? 404 : 400);
+        }
+        return c.json({ ok: true, frame_count: result.frame_count });
+    });
+    app.post("/step-frames/:id/commit", async (c) => {
+        const id = c.req.param("id");
+        let nodeToFrame;
+        try {
+            const body = await c.req.json();
+            if (body.node_to_frame !== undefined) {
+                const parsed = nodeToFrameSchema.safeParse(body.node_to_frame);
+                if (!parsed.success) {
+                    return c.json({ ok: false, error: "node_to_frame must be a map of node ID → frame index" }, 400);
+                }
+                nodeToFrame = parsed.data;
+            }
+        }
+        catch {
+            // No body or non-JSON body — commit with no node_to_frame.
+        }
+        const result = commitStepFramesResult(id, nodeToFrame);
+        if (!result.ok) {
+            return c.json(result, result.error.includes("not found or expired") ? 404 : 400);
+        }
+        return c.json(result);
+    });
+    // ── User events — bidirectionality (Sprint 10 experiment) ───────────────────
+    app.post("/user-done", async (c) => {
+        signalDone(); // wake any pending wait_done() MCP tool calls
+        // Also forward to channel relay if Claude Code was started with the channels flag.
+        try {
+            const channelPort = parsePort(process.env.CHANNEL_PORT, 3001, "CHANNEL_PORT");
+            await fetch(`http://127.0.0.1:${channelPort}/user-done`, { method: "POST" });
+        }
+        catch {
+            // Channel server not running, or CHANNEL_PORT misconfigured — ignore.
+        }
+        return c.json({ ok: true });
+    });
+    app.post("/wait-done", async (c) => {
+        await waitForDone();
+        return c.json({ ok: true });
+    });
+    // ── Node / edge click events (Phase 2 — Sprint 12) ───────────────────────────
+    app.post("/node-click", async (c) => {
+        const body = await c.req.json();
+        if (body.type !== "node" && body.type !== "edge") {
+            return c.json({ ok: false, error: 'type must be "node" or "edge"' }, 400);
+        }
+        const event = {
+            type: body.type,
+            id: body.id ?? "",
+            label: body.label ?? "",
+            action: body.action ?? null,
+        };
+        signalClick(event); // no-op if no wait_click() is pending
+        return c.json({ ok: true });
+    });
+    app.post("/wait-click", async (c) => {
+        let nodeActions = {};
+        try {
+            const body = await c.req.json();
+            if (body.node_actions !== undefined) {
+                const parsed = nodeActionsSchema.safeParse(body.node_actions);
+                if (!parsed.success) {
+                    return c.json({ ok: false, error: "node_actions must be a map of node ID → string[]" }, 400);
+                }
+                nodeActions = parsed.data;
+            }
+        }
+        catch {
+            // No body or non-JSON body — treat as plain click (node_actions stays {}).
+        }
+        broadcast({ action: "set_node_actions", node_actions: nodeActions, enabled: true });
+        const event = await waitForClick();
+        broadcast({ action: "set_node_actions", enabled: false });
+        return c.json({ ok: true, ...event });
+    });
+    // ── Mermaid viewport persistence (v0.19, F19/C3) ────────────────────────────
+    app.post("/viewport", async (c) => {
+        const body = await c.req.json();
+        if (typeof body.id !== "string" || body.id.length === 0) {
+            return c.json({ ok: false, error: "id must be a non-empty string" }, 400);
+        }
+        // frame (v0.26.1, bug B19/FR21): the cache key is now id:frameIndex, so each
+        // frame of a sequence persists its own manual viewport independently.
+        if (typeof body.frame !== "number" || !Number.isInteger(body.frame) || body.frame < 0) {
+            return c.json({ ok: false, error: "frame must be a non-negative integer" }, 400);
+        }
+        const { scale, positionX, positionY } = body;
+        if (typeof scale !== "number" || !Number.isFinite(scale)) {
+            return c.json({ ok: false, error: "scale must be a finite number" }, 400);
+        }
+        if (typeof positionX !== "number" || !Number.isFinite(positionX)) {
+            return c.json({ ok: false, error: "positionX must be a finite number" }, 400);
+        }
+        if (typeof positionY !== "number" || !Number.isFinite(positionY)) {
+            return c.json({ ok: false, error: "positionY must be a finite number" }, 400);
+        }
+        const viewport = { scale, positionX, positionY };
+        await setViewport(body.id, body.frame, viewport);
+        return c.json({ ok: true });
+    });
+}

package/dist/server/routes/slideshow.js

@@ -0,0 +1,52 @@
+import { FRAME_TYPES, validateFrame } from "../validate.js";
+import { cancelSlideshow, startSlideshow } from "../slideshow.js";
+import { validateWorkspaceInput } from "../render-core.js";
+export function registerSlideshowRoutes(app) {
+    app.post("/slideshow", async (c) => {
+        const body = await c.req.json();
+        if (!Array.isArray(body.slides) || body.slides.length === 0) {
+            return c.json({ ok: false, error: "slides must be a non-empty array" }, 400);
+        }
+        if (typeof body.delay_ms !== "number" || body.delay_ms <= 0) {
+            return c.json({ ok: false, error: "delay_ms must be a positive number" }, 400);
+        }
+        const workspaceResult = validateWorkspaceInput(body.workspace);
+        if (!workspaceResult.ok) {
+            return c.json({ ok: false, error: workspaceResult.error }, 400);
+        }
+        const { workspace } = workspaceResult;
+        const rawSlides = body.slides;
+        // Validate each slide — same rules as POST /render.
+        const validatedSlides = [];
+        for (let i = 0; i < rawSlides.length; i++) {
+            const s = rawSlides[i];
+            if (typeof s.type !== "string" || typeof s.payload !== "string") {
+                return c.json({
+                    ok: false,
+                    error: `slide[${i}]: "type" and "payload" must be strings`,
+                }, 400);
+            }
+            if (!FRAME_TYPES.includes(s.type)) {
+                return c.json({ ok: false, error: `slide[${i}]: type must be one of: ${FRAME_TYPES.join(", ")}` }, 400);
+            }
+            if (s.title !== undefined && typeof s.title !== "string") {
+                return c.json({ ok: false, error: `slide[${i}]: "title" must be a string` }, 400);
+            }
+            const err = await validateFrame({ type: s.type, payload: s.payload });
+            if (err) {
+                return c.json({ ok: false, error: `slide[${i}]: ${err}` });
+            }
+            validatedSlides.push({
+                type: s.type,
+                payload: s.payload,
+                ...(s.title !== undefined ? { title: s.title } : {}),
+            });
+        }
+        startSlideshow(validatedSlides, body.delay_ms, workspace);
+        return c.json({ ok: true });
+    });
+    app.post("/slideshow/stop", (c) => {
+        cancelSlideshow();
+        return c.json({ ok: true });
+    });
+}