agent-whiteboard 1.1.0 → 1.3.1

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.3.1",
   "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": {
@@ -9,6 +9,7 @@
   "files": [
     "bin",
     "dist",
+    "skills",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -49,6 +50,7 @@
     "test:e2e": "playwright test",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "check": "npm run typecheck && npm run lint && npm test && npm run build",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/skills/agent-whiteboard/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agent-whiteboard
+description: Core usage of the Agent Whiteboard MCP server — render diagrams, math, charts, HTML and quizzes to a local browser tab, pace the user with wait_done/wait_click, build step-by-step sequences, and export or share the result. Use whenever an explanation, analysis or design discussion would be clearer visually than as text, or when the user mentions the whiteboard.
+---
+
+# Agent Whiteboard — core
+
+The whiteboard is a browser tab you control through MCP tools. The user does not draw on it; you draw, they react (Done button, clicks, quiz Submit). Use it when a picture, formula, chart or interactive check beats a paragraph. If the tools are missing, the server is not running or not registered: tell the user to run `npx agent-whiteboard` and add it to `.mcp.json` (see the project README).
+
+## Rules that always apply
+1. **`workspace` is required** on `render`, `init_step_frames`, `list_snapshots`, `export_html`. Pick one short name per topic or session (`tcp-lesson`, `q3-sales`). Reuse it so the history stays grouped. Letters, digits, `-`, `_`, `.`, spaces only.
+2. **`render` replaces the canvas** and is single-frame. For a multi-frame sequence use `init_step_frames` → `append_frame` × N → `commit_step_frames`.
+3. **Never end a turn assuming the user has looked.** After showing something they must read, call `wait_done` (blocks until they click Done, 10-minute timeout). Say what to look at in chat *before* blocking.
+4. **Keep chat and canvas complementary.** Canvas = the visual; chat = the narration. Don't paste the diagram source into chat.
+5. Every `ok:false` response has an `error` string. Read it, fix the payload, retry once; don't loop blindly.
+
+## Choosing a render type
+| Need                                           | `type`      | Notes                                                                                                                                                                               |
+|------------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Flow, sequence, class, ER, gantt, pie, mindmap | `mermaid`   | Must start with a valid keyword (`graph`, `flowchart`, `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `mindmap`). Only `graph`/`flowchart` are reliably clickable. |
+| Formulas                                       | `katex`     | LaTeX, display mode.                                                                                                                                                                |
+| Data charts                                    | `vega-lite` | JSON spec as a string; inline `data.values`.                                                                                                                                        |
+| Custom layout, tables, callouts                | `html`      | Sanitized: inline styles only, no `<script>`/`<style>`.                                                                                                                             |
+| Hand-made illustrations                        | `svg`       | Inline markup.                                                                                                                                                                      |
+| Knowledge check                                | `quiz`      | See the `whiteboard-assessment` skill. `render()` only — not in slideshows or step-frames.                                                                                          |
+
+Keep each frame to one idea. Prefer 5–9 mermaid nodes; split big diagrams into frames.
+
+## Pacing and interaction tools
+- `wait_done` — user reviewed; continue. The default pacing tool.
+- `wait_click([node_actions])` — user clicks a node/edge of the current mermaid diagram; returns `{id, label, action}`. `node_actions` maps node id → menu strings (e.g. `{"Cache": ["Explain", "Show failure"]}`). A new `wait_click` or `wait_done` supersedes a pending one.
+- `wait_quiz` — user submits the quiz on screen; returns questions and answers.
+- `step(next|prev)` / `seek(frame)` — move through a committed step-frames sequence.
+- `slideshow(slides, delay_ms)` / `slideshow_stop` — unattended auto-advance (demos, ambient display). Not for teaching: the user can't pace it.
+
+## Step-frames pattern
+`init_step_frames(frame_type, workspace, title)` returns a builder id. Each `append_frame(id, payload, label)` is shown immediately, so the user watches it grow; interleave `wait_done` for a paced reveal. `type` on a frame overrides the sequence type (mix mermaid and katex). `commit_step_frames(id, node_to_frame)` finalizes and saves; `node_to_frame` lets the user click a node to jump to its frame. Builders expire after 30 minutes idle.
+
+## History, export, sharing
+- Every render/commit is saved under `~/.agent-whiteboard/<workspace>/`. `list_snapshots(workspace)` shows what exists; `export(id)` returns a snapshot's source.
+- `export_html(workspace, ids)` returns one self-contained HTML document (CDN-linked). Quizzes are replaced by a note. For offline files or a saved path use `POST /export-html` with `{"mode":"offline"}`.
+- Sharing a whole workspace with someone else: the browser's Import/export menu (zip). Tell the user; there is no MCP tool for it.
+
+## Specialised skills
+`whiteboard-teaching` (lessons, worked examples), `whiteboard-assessment` (quizzes), `whiteboard-analysis` (data and findings), `whiteboard-design` (architecture and decisions).

package/skills/whiteboard-analysis/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: whiteboard-analysis
+description: Present and explore data and findings on the Agent Whiteboard — Vega-Lite charts, iterative data exploration, findings walkthroughs and statistics or math derivations. Use when the user wants to analyse, visualise, compare or explain data or results. Builds on the agent-whiteboard skill.
+---
+
+# Analysis with the whiteboard
+
+Read `agent-whiteboard` first. The charts are Vega-Lite specs (`type="vega-lite"`, payload = JSON string).
+
+## Chart basics
+- Put data inline in `data.values`; keep it to a few hundred rows (summarise first if larger — aggregate in your own tooling, then chart the result).
+- Always set axis titles, units and a chart `title`. Choose the mark for the question: line = trend, bar = comparison, point = relationship, area/stack = composition.
+- Fix colour meaning across a session (the same series, the same colour) so successive charts compare visually.
+- The payload must be valid JSON; a failed render returns `ok:false` with the reason.
+
+## Workflow A — Data exploration loop
+1. Render the first chart with a clear `title`; say in chat what it shows.
+2. `wait_done`, then take the user's follow-up ("split by region", "log scale", "exclude 2020") and re-render. Each render is saved, so earlier versions stay in History for comparison.
+3. Summarise what changed between versions in one sentence each time.
+Keep the same `workspace` throughout (`<dataset>-exploration`).
+
+## Workflow B — Findings walkthrough
+Build a story with step-frames (`init_step_frames` → `append_frame` × N → `commit_step_frames`), mixing types per frame: `html` question/context → `vega-lite` evidence → `html` interpretation → `html` conclusion/next steps. Label frames "1. Question", "2. Evidence", … and `wait_done` between them when presenting live. End with `export_html(workspace, ids)` if the user wants a shareable report.
+
+## Workflow C — Statistics or math derivation
+Pair a `katex` frame (the formula or derivation step) with a `vega-lite` frame illustrating it (distribution, regression line, confidence band). One step per frame. State assumptions in an `html` frame first.
+
+## Workflow D — Compare two datasets or scenarios
+Two charts side by side use a single `vega-lite` spec with `hconcat`/`vconcat` or `facet`, not two renders. For before/after, use two step-frames with identical axes so toggling with `step` shows the change.
+
+## Honesty
+State sample size, time range and caveats on the canvas (`html` frame or chart subtitle), not only in chat. Don't truncate axes to exaggerate a difference unless you say so.

package/skills/whiteboard-assessment/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: whiteboard-assessment
+description: Run quizzes on the Agent Whiteboard — inline self-check quizzes scored in the browser, deferred quizzes graded by the agent via wait_quiz, teach-quiz-remediate loops and spaced review. Use when the user wants to be tested, to review knowledge, or after teaching a topic. Builds on the agent-whiteboard skill.
+---
+
+# Assessment with quizzes
+
+Read `agent-whiteboard` first. Quizzes are `render(type="quiz")` payloads; they cannot go in slideshows or step-frames.
+
+## Payload
+```json
+{ "title": "Check-in",
+  "questions": [
+    { "id": "q1", "text": "Which verb is idempotent?", "kind": "single",
+      "options": [{"id":"a","text":"PUT","correct":true},{"id":"b","text":"POST"}] },
+    { "id": "q2", "text": "Pick the primes", "kind": "multiple", "scoring": "partial", "points": 2,
+      "options": [{"id":"a","text":"2","correct":true,"weight":0.5},
+                  {"id":"b","text":"3","correct":true,"weight":0.5},
+                  {"id":"c","text":"4"}] } ] }
+```
+- Ids unique within the quiz / question. `kind`: `single` or `multiple`.
+- `scoring`: `all_or_nothing` (default; exact correct set earns `points`, default 1) or `partial` (multiple only; correct options carry `weight`s summing to 1; wrong picks earn nothing).
+- **Mode is decided by the key:** every question has a `correct` option → **inline**; none has → **deferred**; a mix is rejected.
+
+## Choose the mode
+| Inline (key in payload)                                                                     | Deferred (no key)                                                                                                    |
+|---------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
+| Instant self-check, learner sees per-question result and total                              | You see the answers and grade them with judgment                                                                     |
+| Key is visible in the page source — fine for self-study, wrong for anything you want hidden | Answers stay hidden; best for formal checks, nuanced "best answer" questions, or when you want to explain per answer |
+
+## Workflow 1 — Inline self-check
+`render` quiz with a key → tell the user to submit → `wait_quiz`. The result carries `answers` and `score {earned, possible}` (client-computed). Comment on the misses; don't re-score.
+
+## Workflow 2 — Deferred, agent-graded
+`render` quiz without a key → `wait_quiz` → returned `questions` + `answers` → grade yourself against what you taught. Report the score in chat, explain each wrong answer briefly, and optionally render a summary (`html` table) of right/wrong.
+
+## Workflow 3 — Teach, quiz, remediate
+After a lesson: 3–6 questions covering the lesson's key ideas (each tied to a frame you showed). Grade. For each miss, `seek` to or re-render the relevant visual and re-explain differently, then ask one fresh question on that point. Don't repeat the same wording.
+
+## Workflow 4 — Spaced review
+Use `list_snapshots(workspace)` to see earlier lessons (quiz snapshots reload as fresh quizzes). Re-quiz on earlier material with new questions rather than identical ones. Mention progress against the previous score only if you recorded it in chat.
+
+## Writing good questions
+- One concept per question; 3–5 options; plausible distractors drawn from real misconceptions.
+- Avoid "all of the above" and negatives; keep option lengths similar.
+- Use `multiple` + `partial` only when a set of facts is genuinely independent.
+
+## Gotchas
+- A submission made before you call `wait_quiz` is kept as long as that same quiz is still on screen. Re-rendering discards it.
+- `wait_quiz` times out after 10 minutes (`type: "timeout"`) and returns `ok:false` if no quiz is showing.
+- Answers and scores are never saved to history, and quizzes are omitted from HTML export.

package/skills/whiteboard-design/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: whiteboard-design
+description: Run design and architecture sessions on the Agent Whiteboard — system diagrams refined iteratively, option comparisons the user decides between by clicking, codebase explanations, and onboarding material. Use when discussing architecture, flows, trade-offs or explaining how a system works. Builds on the agent-whiteboard skill.
+---
+
+# Design and architecture with the whiteboard
+
+Read `agent-whiteboard` first. Mermaid is the main tool: `flowchart`/`graph` for structure and clicks, `sequenceDiagram` for interactions, `classDiagram`/`erDiagram` for models. State machines: draw them as a `flowchart` (the validator only accepts the keywords listed in the core skill).
+
+## Workflow A — Iterative system design
+1. Render a high-level `flowchart` (5–9 boxes). `wait_click` with `node_actions` for the components worth deepening, e.g. `{"API": ["Expand", "Alternatives"], "DB": ["Expand", "Scaling"]}`.
+2. On a click, render the zoomed diagram of that component (or a step-frames drill-down). Keep a breadcrumb in the `title` ("System › API").
+3. Return to the overview with the explored nodes marked, and repeat until the user is satisfied.
+Record decisions in chat as they are made.
+
+## Workflow B — Option comparison and decision
+Show 2–3 alternatives as separate frames in one step-frames sequence (same structure and axes so differences pop), followed by an `html` frame with a short comparison table (criteria × options, plain inline styles). Then ask for a decision with `wait_click` on a mermaid node per option, or simply ask in chat. Finish by rendering the chosen design and the decision rationale.
+
+## Workflow C — Explain existing code or a protocol
+Read the code first, then draw: component/flow diagram → sequence diagram for the key scenario → state or error paths. Step-frames with `wait_done` between frames work well for request lifecycles. Use real names from the code in node labels so the diagram maps to files.
+
+## Workflow D — Onboarding pack
+Compose a short slideshow of step-frames sequences (what the system is → how a request flows → where to find things), end with a quiz via `whiteboard-assessment`, and `export_html` the workspace so newcomers can read it without the tool.
+
+## Diagram hygiene
+- Label edges with the action or protocol, not just arrows.
+- Group with `subgraph` rather than adding nodes; keep one direction (`LR` or `TD`) per diagram.
+- Mark external systems and the part under discussion with different shapes or styles, consistently across frames.
+- Mermaid syntax errors come back as `ok:false`; fix and retry rather than simplifying the content away.

package/skills/whiteboard-teaching/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: whiteboard-teaching
+description: Teach or train a user with the Agent Whiteboard — concept explainers, progressive build-ups, worked examples, guided lessons and learner-driven branching. Use when the user wants to learn, be tutored, onboarded or trained on a topic and visuals would help. Builds on the agent-whiteboard skill.
+---
+
+# Teaching with the whiteboard
+
+Read `agent-whiteboard` first for the tool rules (workspace, `wait_done`, render types). This skill is the lesson craft.
+
+## Before you start
+Ask at most two things if unknown: the learner's current level and what they want to be able to do afterwards. Pick one workspace per lesson (`<topic>-lesson`).
+
+## Workflow A — Concept explainer (default loop)
+1. `render` one visual for one idea, with a `title`.
+2. Narrate in 2–4 sentences: what to look at, what it means.
+3. `wait_done`.
+4. Check understanding in one line ("What would happen if the server dropped the SYN?"), then continue or re-explain with a different visual.
+
+## Workflow B — Progressive build-up
+Use when the final picture is too big to show at once.
+1. `init_step_frames(frame_type, workspace, title)`.
+2. `append_frame` the simplest version, labelled "1. …". Narrate. `wait_done`.
+3. Each next frame adds *one* element to the previous one (copy the earlier source, add a line) so the learner sees only the delta.
+4. `commit_step_frames` at the end so the whole sequence can be replayed with `step`/`seek`. Add `node_to_frame` so they can click a node to revisit its frame.
+
+## Workflow C — Worked example (math or algorithm)
+One `katex` or `mermaid` frame per step: state before, operation, state after. Label frames by the operation ("Swap 3 and 5"). Pause with `wait_done` every 1–2 steps; for long derivations ask "want to try the next step yourself?" and wait in chat before revealing it.
+
+## Workflow D — Guided lesson
+Outline in chat (3–6 sections), then per section run A or B. Finish with a recap diagram that connects the sections, then a quiz (`whiteboard-assessment`). Keep the lesson in one workspace so it can be exported with `export_html`.
+
+## Workflow E — Learner-driven branching
+Render a mermaid map of the topic and call `wait_click` with `node_actions` such as `{"Cache": ["Explain", "Quiz me"]}`. Act on the returned `id`/`action`: explain that node, then re-render the map with visited nodes styled differently and arm `wait_click` again. Stop when the learner says so or all nodes are covered.
+
+## Style
+- One idea per frame; label every step; no more than ~9 nodes.
+- Reuse the same colours/shapes for the same concept across frames.
+- Ask before moving on if the learner seems lost; `seek` back to the relevant frame instead of re-rendering.
+- Don't dump the source of a diagram into chat.

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