@dev.fast/whiteboard 0.5.1 → 0.5.2-preview.20261104.146

package/src/animation-stage-kit.ts

@@ -21,6 +21,10 @@ export const STAGE_THEME = {
   "added-bg": "--diff-added-bg",
   "removed-bg": "--diff-removed-bg",
   "modified-bg": "--diff-modified-bg",
+  // Two more outline colours for telling kinds of card apart: the software
+  // map's storage colour, and the merged purple.
+  teal: "--map-storage-border",
+  violet: "--merged",
   // Each face by its role: the chrome's for labels, mono for what a
   // terminal would print, the reading face for prose, and the code font.
   "font-sans": "--chrome-font",
@@ -52,6 +56,8 @@ export const STAGE_VARIABLES: [note: string, names: string[]][] = [
       "added-bg",
       "removed-bg",
       "modified-bg",
+      "teal",
+      "violet",
     ],
   ],
   [
@@ -149,7 +155,7 @@ const CLASSES: [selector: string, use: string][] = [
   ],
   [
     ".wb-card",
-    "A box with a title and note: put .wb-card-title and .wb-card-note inside. The scene's cards are these.",
+    "A box with a title and note: a .wb-card-head holding a .wb-card-dot and the .wb-card-title, then a .wb-card-note. The scene's cards are these.",
   ],
   [
     ".wb-node",
@@ -178,6 +184,18 @@ const CLASSES: [selector: string, use: string][] = [
     ".wb-shape, .wb-shape-text",
     "An SVG shape drawn like a card, and the text inside it.",
   ],
+  [
+    ".wb-group",
+    "A washed box behind a scene's cards with a .wb-group-title; scene.group draws one.",
+  ],
+  [
+    ".wb-legend",
+    "A row of .wb-legend-entry glyphs and labels under a scene; scene.legend draws one.",
+  ],
+  [
+    "[data-wb-paint]",
+    'When an agent writes the block, its parts paint in: data-wb-paint="3" orders a part (numbers first, then document order), "none" shows it and its subtree at once; data-wb-paint-style="fade|draw|wipe|none" picks the effect.',
+  ],
 ];
 
 /** The CSS every stage loads before its own markup. */
@@ -186,6 +204,7 @@ export const STAGE_KIT_CSS = `:root { --wb-duration: 450ms; color-scheme: light
 button { color: inherit; font: inherit; }
 html, body { margin: 0; height: 100%; }
 html[data-wb-auto-size] body { height: auto; display: flow-root; }
+html[data-wb-unpainted] body { visibility: hidden; }
 body {
   overflow: hidden;
   background: transparent;
@@ -240,9 +259,76 @@ body {
 .wb-node { min-width: 88px; text-align: center; }
 .wb-node small { display: block; color: var(--wb-ink-faint); font-size: var(--wb-text-micro); }
 .wb-card-head { display: flex; align-items: center; gap: var(--wb-space-6); }
-.wb-card-dot { flex: none; width: 7px; height: 7px; border-radius: var(--wb-radius-round); background: var(--wb-ink-faint); }
+/* The dot says what state a card is in: it shows only with a tone or a
+   change mark, in that colour, so a plain card carries no unexplained mark. */
+.wb-card-dot { display: none; flex: none; width: 7px; height: 7px; border-radius: var(--wb-radius-round); background: var(--wb-ink-faint); }
+.wb-card:is([data-tone], [data-change]) .wb-card-dot { display: block; }
 .wb-card-title { min-width: 0; overflow-wrap: anywhere; font-weight: var(--wb-weight-semibold); }
 .wb-card-note { color: var(--wb-ink-muted); overflow-wrap: anywhere; font-size: var(--wb-text-micro); min-height: 12px; }
+
+/* A store's text sits in the middle of its drum or cylinder, as a label on
+   a tank does; a pill's too. */
+:where(.wb-card, .wb-node):is([data-form="cylinder"], [data-form="drum"], [data-form="pill"]) { align-items: center; text-align: center; }
+.wb-card:is([data-form="cylinder"], [data-form="drum"], [data-form="pill"]) :is(.wb-card-head, .wb-items) { justify-content: center; }
+/* Shapes: a card's or node's silhouette says what it stands for before
+   its title does. data-form is box (the default), pill, cut (a branch),
+   cylinder (a database), drum (a cache), stack (a queue), window (a
+   client) or bars (a service of this codebase). data-outline is solid,
+   dashed (outside the system) or dotted. data-color is the resting border
+   colour: ink, accent, teal or violet; a tone takes over while set. The
+   scene's cards take these as options. These rules and the change marks
+   weigh one class, as the card rules do: a hand-made layout's own rule for
+   its nodes, say position: absolute, comes later and wins. A tone or a
+   highlight still takes over. */
+:where(.wb-card, .wb-node)[data-form] { position: relative; }
+:where(.wb-card, .wb-node)[data-form]::before, :where(.wb-card, .wb-node)[data-form]::after { pointer-events: none; }
+:where(.wb-card, .wb-node)[data-form="pill"] { padding-inline: var(--wb-space-16); border-radius: var(--wb-radius-pill); }
+:where(.wb-card, .wb-node)[data-form="cut"] { border-radius: var(--wb-space-12); corner-shape: bevel; }
+:where(.wb-card, .wb-node)[data-form="cylinder"] { padding-top: var(--wb-space-28); padding-bottom: var(--wb-space-12); border-radius: 50% / var(--wb-space-10); }
+:where(.wb-card, .wb-node)[data-form="cylinder"]::before {
+  content: ""; position: absolute; inset: -1px -1px auto; height: var(--wb-space-20);
+  border: 1px solid; border-color: inherit; border-radius: 50%; background: inherit;
+}
+:where(.wb-card, .wb-node)[data-form="drum"] { padding-left: var(--wb-space-28); padding-right: var(--wb-space-16); border-radius: var(--wb-space-12) / 50%; }
+:where(.wb-card, .wb-node)[data-form="drum"]::before {
+  content: ""; position: absolute; inset: -1px auto -1px -1px; width: var(--wb-space-24);
+  border: 1px solid; border-color: inherit; border-radius: 50%; background: inherit;
+}
+:where(.wb-card, .wb-node)[data-form="stack"] {
+  margin-right: var(--wb-space-8); margin-bottom: var(--wb-space-8);
+  box-shadow: 4px 4px 0 -1px var(--wb-surface), 4px 4px 0 0 var(--wb-rule), 8px 8px 0 -1px var(--wb-surface), 8px 8px 0 0 var(--wb-rule);
+}
+:where(.wb-card, .wb-node)[data-form="window"] { padding-top: var(--wb-space-16); }
+:where(.wb-card, .wb-node)[data-form="window"]::before { content: ""; position: absolute; top: var(--wb-space-8); right: 0; left: 0; border-top: 1px solid; border-color: inherit; }
+:where(.wb-card, .wb-node)[data-form="bars"] { padding-inline: var(--wb-space-18); }
+:where(.wb-card, .wb-node)[data-form="bars"]::before, :where(.wb-card, .wb-node)[data-form="bars"]::after { content: ""; position: absolute; top: 0; bottom: 0; border-left: 1px solid; border-color: inherit; }
+:where(.wb-card, .wb-node)[data-form="bars"]::before { left: var(--wb-space-6); }
+:where(.wb-card, .wb-node)[data-form="bars"]::after { right: var(--wb-space-6); }
+/* What the change under review did to a part: its dot and a stripe down its
+   left edge in the change colour, at rest; a removed part's title is struck.
+   A frame's tone still colours the whole card over it. */
+:where(.wb-card, .wb-node)[data-change] { border-left-width: 3px; }
+:where(.wb-card, .wb-node)[data-change="added"] { border-left-color: var(--wb-added); }
+:where(.wb-card, .wb-node)[data-change="modified"] { border-left-color: var(--wb-modified); }
+:where(.wb-card, .wb-node)[data-change="removed"] { border-left-color: var(--wb-removed); }
+.wb-card[data-change="added"] .wb-card-dot { background: var(--wb-added); }
+.wb-card[data-change="modified"] .wb-card-dot { background: var(--wb-modified); }
+.wb-card[data-change="removed"] .wb-card-dot { background: var(--wb-removed); }
+.wb-card[data-change="removed"] .wb-card-title { color: var(--wb-ink-muted); text-decoration: line-through; }
+:where(.wb-card, .wb-node)[data-outline="dashed"] { border-style: dashed; }
+:where(.wb-card, .wb-node)[data-outline="dotted"] { border-style: dotted; }
+:where(.wb-card, .wb-node)[data-color="ink"] { border-color: var(--wb-ink); }
+:where(.wb-card, .wb-node)[data-color="accent"] { border-color: var(--wb-accent); }
+:where(.wb-card, .wb-node)[data-color="teal"] { border-color: var(--wb-teal); }
+:where(.wb-card, .wb-node)[data-color="violet"] { border-color: var(--wb-violet); }
+.wb-card[data-color="ink"] .wb-card-dot { background: var(--wb-ink); }
+.wb-card[data-color="accent"] .wb-card-dot { background: var(--wb-accent); }
+.wb-card[data-color="teal"] .wb-card-dot { background: var(--wb-teal); }
+.wb-card[data-color="violet"] .wb-card-dot { background: var(--wb-violet); }
+.wb-shape[data-color="ink"] { stroke: var(--wb-ink); }
+.wb-shape[data-color="accent"] { stroke: var(--wb-accent); }
+.wb-shape[data-color="teal"] { stroke: var(--wb-teal); }
+.wb-shape[data-color="violet"] { stroke: var(--wb-violet); }
 .wb-well { padding: var(--wb-space-12); border: 1px solid var(--wb-rule-soft); border-radius: var(--wb-radius-surface); background: var(--wb-well); }
 .wb-well :is(.wb-item, .wb-chip, .wb-badge, .wb-code) { background: var(--wb-surface); }
 .wb-rule { margin: var(--wb-space-12) 0; border: 0; border-top: 1px solid var(--wb-rule); }
@@ -306,10 +392,15 @@ body {
 .wb-shape[data-tone="modified"] { stroke: var(--wb-modified); fill: var(--wb-modified-bg); }
 .wb-shape[data-tone="muted"] { stroke-dasharray: 4 3; }
 :is(.wb-card, .wb-node)[data-wb-highlit] { border-color: var(--wb-accent); box-shadow: 0 0 0 3px var(--wb-accent-soft); }
+:is(.wb-card, .wb-node)[data-form="stack"][data-wb-highlit] {
+  box-shadow: 0 0 0 3px var(--wb-accent-soft), 4px 4px 0 -1px var(--wb-surface), 4px 4px 0 0 var(--wb-rule), 8px 8px 0 -1px var(--wb-surface), 8px 8px 0 0 var(--wb-rule);
+}
 .wb-shape[data-wb-highlit] { stroke: var(--wb-accent); stroke-width: 2; }
 
 /* Connectors and tokens. */
-.wb-arrows, .wb-tokens { position: fixed; inset: 0; width: 100%; height: 100%; overflow: visible; pointer-events: none; }
+/* Above the cards, which sit above their groups: an edge's head meets a
+   card's border, and a chip stays readable as it passes one. */
+.wb-arrows, .wb-tokens { position: fixed; inset: 0; z-index: 2; width: 100%; height: 100%; overflow: visible; pointer-events: none; }
 .wb-line {
   fill: none;
   stroke: var(--wb-ink-faint);
@@ -328,6 +419,17 @@ body {
 .wb-arrow[data-tone="removed"] .wb-line { stroke: var(--wb-removed); marker-end: url(#wb-head-removed); }
 .wb-arrow[data-tone="modified"] .wb-line { stroke: var(--wb-modified); marker-end: url(#wb-head-modified); }
 .wb-arrow[data-wb-headless] .wb-line { marker-end: none; }
+/* An edge carrying one of the frame's messages takes the marker, label too. */
+.wb-arrow[data-wb-sent] .wb-line { stroke: var(--wb-accent); marker-end: url(#wb-head-accent); }
+.wb-arrow[data-wb-sent] .wb-label { fill: var(--wb-accent); }
+.wb-arrow[data-wb-sent="added"] .wb-line { stroke: var(--wb-added); marker-end: url(#wb-head-added); }
+.wb-arrow[data-wb-sent="added"] .wb-label { fill: var(--wb-added); }
+.wb-arrow[data-wb-sent="removed"] .wb-line { stroke: var(--wb-removed); marker-end: url(#wb-head-removed); }
+.wb-arrow[data-wb-sent="removed"] .wb-label { fill: var(--wb-removed); }
+.wb-arrow[data-wb-sent="modified"] .wb-line { stroke: var(--wb-modified); marker-end: url(#wb-head-modified); }
+.wb-arrow[data-wb-sent="modified"] .wb-label { fill: var(--wb-modified); }
+.wb-arrow[data-wb-sent="muted"] .wb-line { stroke: var(--wb-ink-faint); marker-end: url(#wb-head); }
+.wb-arrow[data-wb-sent="muted"] .wb-label { fill: var(--wb-ink-muted); }
 .wb-label {
   fill: var(--wb-ink-muted);
   font: var(--wb-text-micro) var(--wb-font-mono);
@@ -362,16 +464,53 @@ body {
 .wb-token[data-labelled][data-tone="muted"] { color: var(--wb-token-muted-ink); }
 
 /* The scene. */
-.wb-scene { display: grid; gap: var(--wb-space-28) var(--wb-space-48); padding: var(--wb-space-24); align-items: start; justify-items: stretch; min-width: 0; }
-.wb-scene-compact { grid-template-columns: minmax(0, 1fr) !important; row-gap: var(--wb-space-48); }
-.wb-scene-compact > * { grid-column: 1 / -1 !important; grid-row: auto !important; }
-.wb-scene-fold { grid-template-columns: repeat(var(--wb-fold), minmax(0, 1fr)) !important; }
-.wb-scene-fold > * { grid-column: auto !important; grid-row: auto !important; }
-.wb-scene-fold > [data-wb-wide] { grid-column: 1 / -1 !important; }
+.wb-scene { display: grid; gap: var(--wb-space-28) var(--wb-space-48); padding: var(--wb-space-24); align-items: center; justify-items: stretch; min-width: 0; }
+/* A card is as wide as what it says, within bounds, and sits mid-column, so
+   a wide column does not stretch it into a slab. A table keeps its column;
+   a scene's own CSS may set any width. The scene sets its own min-width from
+   the columns its cards make, and the block scrolls it sideways when
+   narrower. */
+.wb-scene > .wb-card:not([data-kind="table"]) { justify-self: center; width: fit-content; min-width: 140px; max-width: 300px; }
 .wb-scene > [data-wb-state="before"], .wb-scene > [data-wb-state="after"],
 .wb-items > [data-wb-state="before"], .wb-items > [data-wb-state="after"],
 .wb-table tr[data-wb-state="before"], .wb-table tr[data-wb-state="after"] { display: none; }
 .wb-scene-top { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--wb-space-8); margin-bottom: var(--wb-space-4); }
+/* A group is a washed box behind the cards of its cells, bleeding into the
+   gaps around them, titled in its top-left. Cards paint over it. */
+.wb-scene > .wb-card { position: relative; z-index: 1; }
+/* Groups bleed into the gaps around their cells, so a grouped scene opens
+   its rows and columns to keep the boxes apart and give edges between
+   layers room to be read. The top bleed holds the title clear of the cards
+   below it, ring and all. */
+.wb-scene:has(> .wb-group) { row-gap: var(--wb-space-72); column-gap: var(--wb-space-72); padding: var(--wb-space-32) var(--wb-space-24); }
+.wb-group {
+  position: relative; z-index: 0; align-self: stretch; justify-self: stretch;
+  margin: calc(-1 * var(--wb-space-28)) calc(-1 * var(--wb-space-16)) calc(-1 * var(--wb-space-10));
+  border: 1px solid var(--wb-rule-soft); border-radius: var(--wb-radius-surface); background: var(--wb-well);
+  transition: opacity var(--wb-duration) ease;
+}
+.wb-group-title { position: absolute; top: var(--wb-space-4); left: var(--wb-space-12); color: var(--wb-ink-muted); font: var(--wb-text-micro)/var(--wb-leading-normal) var(--wb-font-mono); letter-spacing: var(--wb-tracking-chrome); text-transform: uppercase; white-space: nowrap; }
+.wb-group[data-color="accent"] { border-color: color-mix(in srgb, var(--wb-accent) 30%, transparent); background: color-mix(in srgb, var(--wb-accent) 7%, transparent); }
+.wb-group[data-color="accent"] .wb-group-title { color: var(--wb-accent); }
+.wb-group[data-color="teal"] { border-color: color-mix(in srgb, var(--wb-teal) 36%, transparent); background: color-mix(in srgb, var(--wb-teal) 8%, transparent); }
+.wb-group[data-color="teal"] .wb-group-title { color: var(--wb-teal); }
+.wb-group[data-color="violet"] { border-color: color-mix(in srgb, var(--wb-violet) 36%, transparent); background: color-mix(in srgb, var(--wb-violet) 8%, transparent); }
+.wb-group[data-color="violet"] .wb-group-title { color: var(--wb-violet); }
+.wb-group[data-color="ink"] { border-color: var(--wb-rule); }
+.wb-group[data-color="ink"] .wb-group-title { color: var(--wb-ink); }
+/* The legend: a card-like glyph per entry, drawn with the card rules and
+   scaled to 0.4 inside a box of the scaled size, and what it stands for.
+   A transform, not zoom: Electron's Chromium reports a zoomed element's
+   rect in unzoomed units, which made the stage measure itself 2.5x tall. */
+.wb-legend { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--wb-space-6) var(--wb-space-16); padding: 0 var(--wb-space-24) var(--wb-space-12); color: var(--wb-ink-muted); font: var(--wb-text-micro)/var(--wb-leading-normal) var(--wb-font-mono); letter-spacing: var(--wb-tracking-chrome); text-transform: uppercase; }
+.wb-legend-entry { display: inline-flex; align-items: center; gap: var(--wb-space-6); white-space: nowrap; }
+.wb-legend-box { position: relative; flex: none; width: 20px; height: 13px; }
+.wb-card.wb-legend-glyph { position: absolute; top: 0; left: 0; display: block; width: 50px; min-width: 0; height: 32px; padding: 0; transform: scale(0.4); transform-origin: 0 0; }
+.wb-card.wb-legend-glyph[data-form="cylinder"] { height: 44px; }
+/* Lines that scale to a pixel: the glyph's borders, its lid and rule marks,
+   and its change stripe are drawn 2.5x heavier before the 0.4 scale. */
+.wb-card.wb-legend-glyph, .wb-card.wb-legend-glyph::before, .wb-card.wb-legend-glyph::after { border-width: 2.5px; }
+.wb-card.wb-legend-glyph[data-change] { border-left-width: 7px; }
 :root[data-wb-instant] *, :root[data-wb-instant] *::before, :root[data-wb-instant] *::after {
   transition: none !important;
   animation-duration: 0s !important;
@@ -397,7 +536,8 @@ export function stageStyleReference(): string {
  * animation.html only for what they do not cover, written with the variables:
  * no literal colors, sizes or font names. data-tone="accent|added|removed|
  * modified|muted" colors any card, node, chip, badge, shape or table row;
- * data-highlight="frameKey ..." rings a card, node or shape in those frames.
+ * data-highlight="frameKey ..." rings a card, node or shape in those frames
+ * (in a clip, those markers).
  *
  * Classes:
 ${classes}

package/src/cli-runner.ts

@@ -1226,7 +1226,10 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
     program.command("login").description("Log in to Whiteboard with GitHub"),
     "plain",
   )
-    .option("--origin <url>", "Whiteboard service origin", DEFAULT_STORE_ORIGIN)
+    .option(
+      "--origin <url>",
+      `Whiteboard service origin (default: $DEV_REVIEW_SERVICE_ORIGIN or ${DEFAULT_STORE_ORIGIN})`,
+    )
     .option("--traces", "Also authorize GitHub repositories for hosted traces")
     .option("--no-browser", "Print the URL instead of opening a browser")
     .action(

package/src/fixtures/blocks/clip.json

@@ -0,0 +1,19 @@
+[
+  {
+    "id": "block-1",
+    "type": "clip",
+    "title": "Order status",
+    "height": 300,
+    "markers": [
+      { "key": "sent", "title": "Order sent" },
+      {
+        "key": "queued",
+        "title": "Status queued",
+        "caption": "The status line sets it.",
+        "code": ["status"]
+      }
+    ],
+    "code": { "status": "head/order.ts#L1" },
+    "html": "<div class=\"wb-row\"><div class=\"wb-node\" id=\"order\">order</div></div><div data-wb-code=\"status\"></div><script>whiteboard.clip().marker(\"sent\").add(\"#order\", { translateX: [0, 120], duration: 800 }).marker(\"queued\");</script>"
+  }
+]

package/src/review-api/README.md

@@ -55,6 +55,7 @@ All paths below are relative to `/reviews-api`.
 | `GET /:id/history`                                            | Saved versions with titles, timestamps and `author`: `"you"` for a person's save, else `"agent"` with the Ask `threadId` when one made it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `GET /:id/inspect`                                            | Agent reading view: nested text outline with IDs; `targetId` reads one component completely, `full=true` includes all content, `version` selects history. `format=json` returns raw data instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `POST /:id/open`                                              | Open the review in the attached Desktop; report an error when none is attached                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `GET /:id/render?targetId=anim-1&frame=a2`                    | Show that frame (or a clip at that marker) of the review open in the attached Desktop and return it: `type`, `frame` (key, title, position, count), `scenario`, `clipped`, `error` (what the stage's script threw, or null) and `png` (base64). 409 when no Desktop shows the review; 400 for a frame the block does not have                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `POST /commands`                                              | Apply one command; return review ID, version, and for an edit the target ID, its `type`, and — after an insert or replace — `children`: its first-level children as `{id,type}` (a container's blocks; a diagram's steps, or nodes then edges), so new components are addressable without a read. A `create` with `pullRequestUrl` returns the newest existing review for that PR instead (owner/repository matched case-insensitively) unless `operation.reuseExisting` is `false`: `created:false`, a `note`, its stored `target`, `headMoved`, and `working`/`otherReviewIds` when they apply; its target is never moved. A new review reports `created:true`. Either way the result carries `review`, the review's `GET /` catalog entry (target, origin, repository name and path). An interactive `create` also opens the new review in an attached Desktop unless `operation.open` is `false`, and reports `opened` with the open result or an `openError`; the review is saved either way |
 | `POST /commands {operation:{type:"lens_edit",reviewId,edit}}` | Write one file lens, credited to `activityId` when given: `insert {title,targets,afterId?}` (host id `lens-N`), `update {targetId,title?,targets?}` or `remove {targetId}`. Returns `{targetId, type:"lens", uncategorized}`, where `uncategorized` lists changed files and ranges no lens covers yet (at most 50 files)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `POST /:id/person-edit {baseVersion,title,document}`          | Save a person's whole board as their version; return `{reviewId,version,ids}`. See Person edits                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

package/src/review-api/agent-cli.ts

@@ -18,7 +18,7 @@ import {
 } from "./agent-client.js";
 import { type ReviewApiClient, ReviewApiError } from "./client.js";
 import { exitOnInstallUpdate } from "./install-update.js";
-import { callPublicTool, publicTool } from "./public-tools.js";
+import { callPublicTool, publicTool, renderedImage } from "./public-tools.js";
 import { RECOVERY } from "./recovery.js";
 import {
   ASK_THREAD_ENV,
@@ -212,7 +212,8 @@ export async function runReviewAgentCli(input: AgentCliInput): Promise<number> {
       durationMs: Date.now() - startedAt,
     });
 
-    const text = toolResultText(tool, result);
+    // A rendered frame is read from its file; its bytes stay out of stdout.
+    const text = toolResultText(tool, renderedImage(tool, result).result);
     input.stdout.write(text.endsWith("\n") ? text : text + "\n");
 
     return 0;

package/src/review-api/animation-drafts.ts

@@ -1,9 +1,18 @@
-// An animation checked out as files, so an agent edits it with its own file
-// tools and publishes the folder: the bytes travel by path, not through the
-// agent's output.
+// An animation or clip checked out as files, so an agent edits it with its
+// own file tools and publishes the folder: the bytes travel by path, not
+// through the agent's output. A clip's folder holds markers.json where an
+// animation's holds frames.json.
 
 import { createHash } from "node:crypto";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import {
+  chmod,
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  writeFile,
+} from "node:fs/promises";
 import path from "node:path";
 
 import {
@@ -24,9 +33,15 @@ import { isMissingFileError } from "@review/fs-utils.js";
 import { findReviewPackageRoot } from "@review/package-paths.js";
 import { z } from "zod";
 
+import {
+  type AnimationReference,
+  readAnimationReferences,
+} from "./animation-references.js";
+
 const FILES = {
   html: "animation.html",
   frames: "frames.json",
+  markers: "markers.json",
   scenarios: "scenarios.json",
   block: "block.json",
   checkout: "checkout.json",
@@ -35,8 +50,11 @@ const FILES = {
 /** The fields block.json holds: everything but the ones with files of their own. */
 const BLOCK_FIELDS = ["title", "code", "height", "pins"];
 
-/** Every field an animation's files can set. */
-const FIELDS = ["html", "frames", "scenarios", ...BLOCK_FIELDS];
+/** Every field an animation's or clip's files can set. */
+const FIELDS = ["html", "frames", "markers", "scenarios", ...BLOCK_FIELDS];
+
+/** The block types that check out as files. */
+type DraftType = "animation" | "clip";
 
 /** What checkout.json records: the block the folder came from, as it was. */
 const checkoutSchema = z.strictObject({
@@ -57,10 +75,12 @@ const handle = /^[\w-]{1,128}$/;
 
 /** The animation references, read-only beside the drafts so they always match
  * the Whiteboard that wrote them: whiteboard.css, the style kit every
- * animation loads, and whiteboard.d.ts, the API its scripts call. */
+ * animation loads, whiteboard.d.ts, the API its scripts call, and the
+ * reference animations an agent copies from. */
 export interface StageReference {
   styles: string;
   api: string;
+  references: AnimationReference[];
 }
 
 async function writeReadOnly(file: string, content: string): Promise<void> {
@@ -69,27 +89,83 @@ async function writeReadOnly(file: string, content: string): Promise<void> {
   await writeFile(file, content, { mode: 0o444 });
 }
 
-export async function writeStageReference(): Promise<StageReference> {
+/** Copies `source` to `target` with every file read-only, replacing what was there. */
+async function copyReadOnly(source: string, target: string): Promise<void> {
+  await rm(target, { recursive: true, force: true });
+  await cp(source, target, { recursive: true });
+
+  for (const entry of await readdir(target, {
+    recursive: true,
+    withFileTypes: true,
+  }))
+    if (entry.isFile())
+      await chmod(path.join(entry.parentPath, entry.name), 0o444);
+}
+
+export async function writeStageReference(
+  root = findReviewPackageRoot(import.meta.url),
+): Promise<StageReference> {
   const directory = path.join(devReviewHome(), "animation-drafts");
   const styles = path.join(directory, "whiteboard.css");
   const api = path.join(directory, "whiteboard.d.ts");
+  const copies = path.join(directory, "references");
+  const sources = await readAnimationReferences(root, { strict: false });
 
-  const source = path.join(
-    findReviewPackageRoot(import.meta.url),
-    "instructions",
-    "whiteboard.d.ts",
+  await mkdir(copies, { recursive: true });
+  await writeReadOnly(styles, stageStyleReference());
+  await writeReadOnly(
+    api,
+    await readFile(path.join(root, "instructions", "whiteboard.d.ts"), "utf8"),
   );
 
-  await mkdir(directory, { recursive: true });
-  await writeReadOnly(styles, stageStyleReference());
-  await writeReadOnly(api, await readFile(source, "utf8"));
+  const names = new Set(sources.map(({ name }) => name));
+
+  for (const stale of await readdir(copies))
+    if (!names.has(stale))
+      await rm(path.join(copies, stale), { recursive: true, force: true });
+
+  const references = await Promise.all(
+    sources.map(async (reference) => {
+      const copy = path.join(copies, reference.name);
 
-  return { styles, api };
+      await copyReadOnly(reference.directory, copy);
+
+      return { ...reference, directory: copy };
+    }),
+  );
+
+  return { styles, api, references };
 }
 
 /** The line that sends an agent to the references before it writes an animation. */
-export const stageReferenceHint = ({ styles, api }: StageReference) =>
-  `Before writing or restyling an animation's HTML, read ${styles} (the classes and --wb-* variables every animation loads) and ${api} (the whiteboard API its scripts call). Both are read-only and rewritten by Whiteboard.`;
+export const stageReferenceHint = ({
+  styles,
+  api,
+  references,
+}: StageReference) =>
+  `Before writing or restyling an animation's HTML, read ${styles} (the classes and --wb-* variables every animation loads) and ${api} (the whiteboard API its scripts call).${references.length ? ` Reference animations to start from are in ${path.dirname(references[0]!.directory)}: read the README of the closest one.` : ""} All are read-only and rewritten by Whiteboard.`;
+
+/** Lists the reference animations where the agent can read them. */
+function referencesSection({ references }: StageReference): string[] {
+  if (!references.length) return [];
+
+  return [
+    [
+      "## References",
+      "",
+      "Before you write an animation, read the README of the reference closest to what you are drawing, then copy its files into your draft folder as a starting point.",
+      "",
+      ...references.map(
+        ({ name, summary, directory }) =>
+          `- \`${name}\`: ${summary} ${directory}`,
+      ),
+    ].join("\n"),
+  ];
+}
+
+/** What follows the animation instructions: the hint, then the references. */
+export const stageReferenceText = (reference: StageReference) =>
+  [stageReferenceHint(reference), ...referencesSection(reference)].join("\n\n");
 
 export function draftDirectory(
   sessionId: string,
@@ -110,9 +186,12 @@ const fingerprint = (block: JsonValue) =>
 const json = (value: JsonValue) => `${JSON.stringify(value, null, 2)}\n`;
 
 function animationBlock(block: JsonValue, targetId: string): JsonObject {
-  if (!isJsonObject(block) || block.type !== "animation")
+  if (
+    !isJsonObject(block) ||
+    (block.type !== "animation" && block.type !== "clip")
+  )
     throw new ReviewInputError(
-      `${targetId} is ${isJsonObject(block) ? `a ${String(block.type)}` : "not a component"}; only animations check out as files.`,
+      `${targetId} is ${isJsonObject(block) ? `a ${String(block.type)}` : "not a component"}; only animations and clips check out as files.`,
     );
 
   return block;
@@ -143,7 +222,9 @@ export async function checkoutAnimation(
   };
 
   await put("html", String(block.html));
-  await put("frames", json(block.frames ?? []));
+
+  if (block.type === "clip") await put("markers", json(block.markers ?? []));
+  else await put("frames", json(block.frames ?? []));
 
   if (block.scenarios !== undefined)
     await put("scenarios", json(block.scenarios));
@@ -167,7 +248,8 @@ export async function checkoutAnimation(
   return {
     directory,
     files,
-    ...reference,
+    styles: reference.styles,
+    api: reference.api,
     next: `Edit these files with your file tools, then publish the folder: session_edit {sessionId, edit: {type: "update", targetId: "${targetId}", fromFiles: "${directory}"}}. ${stageReferenceHint(reference)}`,
   };
 }
@@ -184,7 +266,7 @@ async function readText(directory: string, name: string, required: boolean) {
 
     if (required)
       throw new ReviewInputError(
-        `${path.join(directory, name)} does not exist. Check the animation out with session_checkout, or write the file.`,
+        `${path.join(directory, name)} does not exist. Check the animation or clip out with session_checkout, or write the file.`,
       );
 
     return undefined;
@@ -205,16 +287,30 @@ async function readJson(directory: string, name: string, required: boolean) {
   }
 }
 
-/** The animation a folder holds, as a block's fields, and where it came from. */
-async function readDraft(directory: string) {
-  const [html, frames, scenarios, block, checkout] = await Promise.all([
+/** The animation or clip a folder holds, as a block's fields with its type,
+ * checked as a publish would be. frames.json makes it an animation and
+ * markers.json a clip. */
+export async function readAnimationFolder(
+  directory: string,
+): Promise<JsonObject & { type: DraftType }> {
+  const [html, frames, markers, scenarios, block] = await Promise.all([
     readText(directory, FILES.html, true),
-    readJson(directory, FILES.frames, true),
+    readJson(directory, FILES.frames, false),
+    readJson(directory, FILES.markers, false),
     readJson(directory, FILES.scenarios, false),
     readJson(directory, FILES.block, true),
-    readJson(directory, FILES.checkout, false),
   ]);
 
+  if (frames !== undefined && markers !== undefined)
+    throw new ReviewInputError(
+      `${directory} holds both ${FILES.frames} and ${FILES.markers}. Keep ${FILES.frames} for an animation or ${FILES.markers} for a clip, not both.`,
+    );
+
+  if (frames === undefined && markers === undefined)
+    throw new ReviewInputError(
+      `${path.join(directory, FILES.frames)} does not exist. Write ${FILES.frames} for an animation or ${FILES.markers} for a clip, or check one out with session_checkout.`,
+    );
+
   if (!isJsonObject(block))
     throw new ReviewInputError(`${FILES.block} must hold a JSON object.`);
 
@@ -222,15 +318,28 @@ async function readDraft(directory: string) {
 
   if (stray.length)
     throw new ReviewInputError(
-      `${FILES.block} holds only ${BLOCK_FIELDS.join(", ")}; move ${stray.join(", ")} out (html is ${FILES.html}, frames ${FILES.frames}, scenarios ${FILES.scenarios}).`,
+      `${FILES.block} holds only ${BLOCK_FIELDS.join(", ")}; move ${stray.join(", ")} out (html is ${FILES.html}, frames ${FILES.frames} or markers ${FILES.markers}, scenarios ${FILES.scenarios}).`,
     );
 
-  const fields: JsonObject = { ...block, html: html!, frames: frames! };
+  const fields: JsonObject & { type: DraftType } =
+    markers === undefined
+      ? { ...block, type: "animation", html: html!, frames: frames! }
+      : { ...block, type: "clip", html: html!, markers };
 
   if (scenarios !== undefined) fields.scenarios = scenarios;
 
   validate(fields);
 
+  return fields;
+}
+
+/** The animation a folder holds, as a block's fields, and where it came from. */
+async function readDraft(directory: string) {
+  const [fields, checkout] = await Promise.all([
+    readAnimationFolder(directory),
+    readJson(directory, FILES.checkout, false),
+  ]);
+
   const parsed = checkoutSchema.safeParse(checkout);
 
   return { fields, checkout: parsed.success ? parsed.data : undefined };
@@ -246,7 +355,7 @@ function located(issuePath: PropertyKey[]): string {
 
   if (field === "html") return FILES.html;
 
-  if (field === "frames" || field === "scenarios")
+  if (field === "frames" || field === "markers" || field === "scenarios")
     return `${FILES[field]} ${at.replace(/^\./, "") || "(top level)"}`;
 
   return `${FILES.block} ${field ?? ""}${at}`;
@@ -254,13 +363,9 @@ function located(issuePath: PropertyKey[]): string {
 
 /** Checks the files before anything is sent, so an issue names its file. The
  * host checks pins: agents write them without the repository it fills in. */
-function validate(fields: JsonObject) {
+function validate(fields: JsonObject & { type: DraftType }) {
   const { pins: _pins, ...rest } = fields;
-
-  const parsed = blocks.animation.schema.safeParse({
-    ...rest,
-    type: "animation",
-  });
+  const parsed = blocks[fields.type].schema.safeParse(rest);
 
   if (!parsed.success)
     throw new ReviewInputError(
@@ -274,8 +379,8 @@ function validate(fields: JsonObject) {
 
 /**
  * Turns an edit that names a draft folder into the edit the host takes: the
- * folder's animation as an insert's or replace's content, or as an update's
- * changed fields. An update from a checkout is refused once the block has
+ * folder's animation or clip as an insert's or replace's content, or as an
+ * update's changed fields. An update from a checkout is refused once the block has
  * changed since. Returns `unchanged` when the files match the block.
  */
 export async function resolveDraftEdit(
@@ -295,10 +400,7 @@ export async function resolveDraftEdit(
   const { fields, checkout } = await readDraft(directory);
 
   if (rest.type === "insert")
-    return {
-      directory,
-      edit: { ...rest, content: { type: "animation", ...fields } },
-    };
+    return { directory, edit: { ...rest, content: fields } };
 
   const targetId = String(rest.targetId);
   const current = animationBlock(await read(sessionId, targetId), targetId);
@@ -315,16 +417,18 @@ export async function resolveDraftEdit(
     );
 
   if (rest.type === "replace")
-    return {
-      directory,
-      edit: { ...rest, content: { type: "animation", ...fields } },
-    };
+    return { directory, edit: { ...rest, content: fields } };
 
   if (rest.type !== "update")
     throw new ReviewInputError(
       "fromFiles publishes an insert, replace or update.",
     );
 
+  if (current.type !== fields.type)
+    throw new ReviewInputError(
+      `${directory} holds ${fields.type === "clip" ? "a clip" : "an animation"} but ${targetId} is ${current.type === "clip" ? "a clip" : "an animation"}. Publish it with type "replace" to change its kind.`,
+    );
+
   const changes: JsonObject = {};
 
   for (const field of FIELDS)