agent-whiteboard 1.1.0 → 1.2.0

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 };
         }

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

@@ -1,7 +1,7 @@
 import { signalClick, signalDone, waitForClick, waitForDone } from "../interaction.js";
 import { clearCanvas } from "../session.js";
 import { broadcast } from "../ws.js";
-import { FRAME_TYPES, nodeActionsSchema, nodeToFrameSchema, validateFrame } from "../validate.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";
@@ -17,13 +17,13 @@ export function registerRenderRoutes(app) {
         if (typeof body.payload !== "string") {
             return c.json({ ok: false, error: "payload must be a string" }, 400);
         }
-        if (!FRAME_TYPES.includes(body.type)) {
-            return c.json({ ok: false, error: `type must be one of: ${FRAME_TYPES.join(", ")}` }, 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 validateFrame({ type, payload });
+        const validationError = await validateRenderPayload(type, payload);
         if (validationError) {
             return c.json({ ok: false, error: validationError });
         }

package/dist/server/validate.js

@@ -1,6 +1,7 @@
 // Server-side payload validation helpers.
 import mermaid from "mermaid";
 import { z } from "zod";
+import { validateQuizPayload } from "./quiz.js";
 /**
  * Shared shape schemas for `node_actions` (wait_click) and `node_to_frame`
  * (commit_step_frames) — the single implementation both MCP's zod
@@ -138,3 +139,16 @@ export async function validateFrame(frame) {
     }
     return null;
 }
+/**
+ * Types accepted by render() — the frame types plus "quiz" (F44). Quiz is
+ * deliberately NOT a FRAME_TYPE: it is a single interactive page, not
+ * something that makes sense inside a slideshow or step-frames sequence
+ * (wait_quiz hands back one submission), so validateFrame() keeps rejecting it.
+ */
+export const RENDER_TYPES = [...FRAME_TYPES, "quiz"];
+/** The one validator for render() payloads, shared by POST /render and the MCP `render` tool. */
+export async function validateRenderPayload(type, payload) {
+    if (type === "quiz")
+        return validateQuizPayload(payload);
+    return validateFrame({ type, payload });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-whiteboard",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A domain-agnostic interactive whiteboard for AI teacher agents — render diagrams, math, charts, and HTML to a local browser tab via MCP tools.",
   "type": "module",
   "bin": {

package/dist/client/assets/channel-9qggtmY_.js

@@ -1 +0,0 @@
-import{a0 as o,a1 as n}from"./mermaid.core-DioArgDk.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/client/assets/classDiagram-ZZMXUADV-BUnGzX-0.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-TICWLB2K-DNZTRqyJ.js";import{_ as i}from"./mermaid.core-DioArgDk.js";import"./chunk-5VM5RSS4-yGvVHapR.js";import"./chunk-XXDRQBXY-BC_9L4PF.js";import"./chunk-POPQ4Y6H-DZP2a-yV.js";import"./chunk-F27PBJKO-BzFUf98n.js";import"./index-CFelVSRu.js";import"./step-BEQzeS8V.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};

package/dist/client/assets/classDiagram-v2-VYDZK3BY-BUnGzX-0.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-TICWLB2K-DNZTRqyJ.js";import{_ as i}from"./mermaid.core-DioArgDk.js";import"./chunk-5VM5RSS4-yGvVHapR.js";import"./chunk-XXDRQBXY-BC_9L4PF.js";import"./chunk-POPQ4Y6H-DZP2a-yV.js";import"./chunk-F27PBJKO-BzFUf98n.js";import"./index-CFelVSRu.js";import"./step-BEQzeS8V.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};