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

package/dist/{tool-failure-RLR8m9hq.js → tool-failure-YOFGHJCZ.js}

@@ -1,14 +1,14 @@
 import { m as isStringValue, n as isJsonObject, u as parseJsonText } from "./src-X9phtB2j.js";
-import { M as checkReferences, j as blocks, ot as ReviewInputError } from "./src-B2b8cCoI.js";
-import { l as boardTitle } from "./src-DLWol7GZ.js";
-import "./review-home-paths-LdGS4SpR.js";
-import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-CMacGbMp.js";
+import { M as checkReferences, j as blocks, ot as ReviewInputError } from "./src-BQDlJXkG.js";
+import { l as boardTitle } from "./src-CrrW7lcY.js";
+import "./review-home-paths-BmZX2qiz.js";
+import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-BCEbSPWU.js";
 import { N as devReviewHome } from "./s3-config-CjcLyFV5.js";
-import { t as findReviewPackageRoot } from "./package-paths-Cg6fnaGp.js";
-import { m as isMissingFileError } from "./thread-state-B7L1mpN_.js";
+import { t as findReviewPackageRoot } from "./package-paths-Dk7MOXxN.js";
+import { m as isMissingFileError } from "./thread-state-WTqSborE.js";
 import { createHash } from "node:crypto";
 import { z } from "zod";
-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";
 //#region src/animation-stage-kit.ts
 /** Every --wb-<name> the stage sets, by group, with what it is for. The
@@ -31,7 +31,9 @@ const STAGE_VARIABLES = [
 		"modified",
 		"added-bg",
 		"removed-bg",
-		"modified-bg"
+		"modified-bg",
+		"teal",
+		"violet"
 	]],
 	["Faces, by role: sans for labels and controls, mono for ids, paths and values, serif for prose, code for source text. Name no font yourself", [
 		"font-sans",
@@ -126,7 +128,7 @@ const CLASSES = [
 	[".wb-grid", "A grid of equal columns; set style=\"--wb-columns: 4\" (default 3)."],
 	[".wb-layers", "Children stacked in one place, for states that replace each other."],
 	[".wb-lane", "A position: relative track with a dashed center line, for a static token snapshot."],
-	[".wb-card", "A box with a title and note: put .wb-card-title and .wb-card-note inside. The scene's cards are these."],
+	[".wb-card", "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", "A centered box for a hand-made layout; a <small> inside is its second line."],
 	[".wb-well", "An inset area that groups parts, such as a process or a machine boundary."],
 	[".wb-rule", "A divider (<hr class=\"wb-rule\">)."],
@@ -138,7 +140,10 @@ const CLASSES = [
 	[".wb-prose", "A sentence of explanation, in the board's reading face."],
 	[".wb-mono, .wb-code", "Ids, paths and values in the mono face; .wb-code is inline code on a well."],
 	[".wb-muted, .wb-faint", "Text that recedes."],
-	[".wb-shape, .wb-shape-text", "An SVG shape drawn like a card, and the text inside it."]
+	[".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. */
 const STAGE_KIT_CSS = `:root { --wb-duration: 450ms; color-scheme: light dark; }
@@ -146,6 +151,7 @@ const STAGE_KIT_CSS = `:root { --wb-duration: 450ms; color-scheme: light dark; }
 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;
@@ -200,9 +206,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); }
@@ -266,10 +339,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);
@@ -288,6 +366,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);
@@ -322,16 +411,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;
@@ -348,7 +474,8 @@ function stageStyleReference() {
  * 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.map(([selector, use]) => ` *   ${selector.padEnd(26)} ${use}`).join("\n")}
@@ -363,10 +490,62 @@ ${STAGE_KIT_CSS}
 `;
 }
 //#endregion
+//#region src/review-api/animation-references.ts
+/** The README's H1 and the paragraph right after it. */
+function readmeHeading(file, text) {
+	const lines = text.split(/\r?\n/);
+	const start = lines.findIndex((line) => line.trim());
+	const title = lines[start]?.match(/^# (.+)$/)?.[1]?.trim();
+	const rest = lines.slice(start + 1);
+	const from = rest.findIndex((line) => line.trim());
+	const paragraph = [];
+	for (const line of from < 0 ? [] : rest.slice(from)) {
+		if (!line.trim() || line.startsWith("#")) break;
+		paragraph.push(line.trim());
+	}
+	const summary = paragraph.join(" ");
+	if (!title || !summary) throw new ReviewInputError(`${file} must open with "# Title" followed by a one-sentence summary paragraph.`);
+	return {
+		title,
+		summary
+	};
+}
+/** Every reference animation, sorted by name, each checked as a publish would
+* be. Strict (the default) throws on a broken reference, for the tests that
+* keep them valid; otherwise a broken one is left out, so an agent's checkout
+* and instructions never fail on a reference. */
+async function readAnimationReferences(root = findReviewPackageRoot(import.meta.url), { strict = true } = {}) {
+	const parent = path.join(root, "instructions", "animations");
+	let entries;
+	try {
+		entries = await readdir(parent, { withFileTypes: true });
+	} catch (error) {
+		if (isMissingFileError(error)) return [];
+		throw error;
+	}
+	const names = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+	return (await Promise.all(names.map(async (name) => {
+		const directory = path.join(parent, name);
+		const readme = path.join(directory, "README.md");
+		try {
+			await readAnimationFolder(directory);
+			return {
+				name,
+				directory,
+				...readmeHeading(readme, await readFile(readme, "utf8"))
+			};
+		} catch (error) {
+			if (!strict) return void 0;
+			throw new ReviewInputError(`Reference animation ${name}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}))).filter((reference) => reference !== void 0);
+}
+//#endregion
 //#region src/review-api/animation-drafts.ts
 const FILES = {
 	html: "animation.html",
 	frames: "frames.json",
+	markers: "markers.json",
 	scenarios: "scenarios.json",
 	block: "block.json",
 	checkout: "checkout.json"
@@ -378,10 +557,11 @@ const BLOCK_FIELDS = [
 	"height",
 	"pins"
 ];
-/** Every field an animation's files can set. */
+/** Every field an animation's or clip's files can set. */
 const FIELDS = [
 	"html",
 	"frames",
+	"markers",
 	"scenarios",
 	...BLOCK_FIELDS
 ];
@@ -396,21 +576,60 @@ async function writeReadOnly(file, content) {
 	await rm(file, { force: true });
 	await writeFile(file, content, { mode: 292 });
 }
-async function writeStageReference() {
+/** Copies `source` to `target` with every file read-only, replacing what was there. */
+async function copyReadOnly(source, target) {
+	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), 292);
+}
+async function writeStageReference(root = findReviewPackageRoot(import.meta.url)) {
 	const directory = path.join(devReviewHome(), "animation-drafts");
 	const styles = path.join(directory, "whiteboard.css");
 	const api = path.join(directory, "whiteboard.d.ts");
-	const source = path.join(findReviewPackageRoot(import.meta.url), "instructions", "whiteboard.d.ts");
-	await mkdir(directory, { recursive: true });
+	const copies = path.join(directory, "references");
+	const sources = await readAnimationReferences(root, { strict: false });
+	await mkdir(copies, { recursive: true });
 	await writeReadOnly(styles, stageStyleReference());
-	await writeReadOnly(api, await readFile(source, "utf8"));
+	await writeReadOnly(api, await readFile(path.join(root, "instructions", "whiteboard.d.ts"), "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
+	});
 	return {
 		styles,
-		api
+		api,
+		references: await Promise.all(sources.map(async (reference) => {
+			const copy = path.join(copies, reference.name);
+			await copyReadOnly(reference.directory, copy);
+			return {
+				...reference,
+				directory: copy
+			};
+		}))
 	};
 }
 /** The line that sends an agent to the references before it writes an animation. */
-const stageReferenceHint = ({ styles, api }) => `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.`;
+const stageReferenceHint = ({ styles, api, references }) => `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 }) {
+	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. */
+const stageReferenceText = (reference) => [stageReferenceHint(reference), ...referencesSection(reference)].join("\n\n");
 function draftDirectory(sessionId, targetId, dir) {
 	if (dir) return path.resolve(dir);
 	if (!handle.test(sessionId) || !handle.test(targetId)) throw new ReviewInputError("sessionId and targetId must be IDs.");
@@ -419,7 +638,7 @@ function draftDirectory(sessionId, targetId, dir) {
 const fingerprint = (block) => createHash("sha256").update(JSON.stringify(block)).digest("hex");
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
 function animationBlock(block, targetId) {
-	if (!isJsonObject(block) || block.type !== "animation") throw new ReviewInputError(`${targetId} is ${isJsonObject(block) ? `a ${String(block.type)}` : "not a component"}; only animations check out as files.`);
+	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 and clips check out as files.`);
 	return block;
 }
 /** Writes the block's files, replacing any earlier draft in the folder. */
@@ -434,7 +653,8 @@ async function checkoutAnimation(read, sessionId, targetId, dir) {
 		await writeFile(files[key], text);
 	};
 	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 !== void 0) await put("scenarios", json(block.scenarios));
 	await put("block", json(Object.fromEntries(Object.entries(block).filter(([key]) => BLOCK_FIELDS.includes(key)))));
 	await writeCheckout(directory, {
@@ -446,7 +666,8 @@ async function checkoutAnimation(read, sessionId, targetId, dir) {
 	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)}`
 	};
 }
@@ -458,7 +679,7 @@ async function readText(directory, name, required) {
 		return await readFile(path.join(directory, name), "utf8");
 	} catch (error) {
 		if (!isMissingFileError(error)) throw error;
-		if (required) throw new ReviewInputError(`${path.join(directory, name)} does not exist. Check the animation out with session_checkout, or write the file.`);
+		if (required) throw new ReviewInputError(`${path.join(directory, name)} does not exist. Check the animation or clip out with session_checkout, or write the file.`);
 		return;
 	}
 }
@@ -471,25 +692,40 @@ async function readJson(directory, name, required) {
 		throw new ReviewInputError(`${name}: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
-/** The animation a folder holds, as a block's fields, and where it came from. */
-async function readDraft(directory) {
-	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. */
+async function readAnimationFolder(directory) {
+	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)
+		readJson(directory, FILES.block, true)
 	]);
+	if (frames !== void 0 && markers !== void 0) 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 === void 0 && markers === void 0) 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.`);
 	const stray = Object.keys(block).filter((key) => !BLOCK_FIELDS.includes(key));
-	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}).`);
-	const fields = {
+	if (stray.length) throw new ReviewInputError(`${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 = markers === void 0 ? {
 		...block,
+		type: "animation",
 		html,
 		frames
+	} : {
+		...block,
+		type: "clip",
+		html,
+		markers
 	};
 	if (scenarios !== void 0) 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) {
+	const [fields, checkout] = await Promise.all([readAnimationFolder(directory), readJson(directory, FILES.checkout, false)]);
 	const parsed = checkoutSchema.safeParse(checkout);
 	return {
 		fields,
@@ -501,24 +737,21 @@ function located(issuePath) {
 	const [field, ...rest] = issuePath.map(String);
 	const at = rest.map((part) => /^\d+$/.test(part) ? `[${part}]` : `.${part}`).join("");
 	if (field === "html") return FILES.html;
-	if (field === "frames" || field === "scenarios") return `${FILES[field]} ${at.replace(/^\./, "") || "(top level)"}`;
+	if (field === "frames" || field === "markers" || field === "scenarios") return `${FILES[field]} ${at.replace(/^\./, "") || "(top level)"}`;
 	return `${FILES.block} ${field ?? ""}${at}`;
 }
 /** 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) {
 	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(parsed.error.issues.map((issue) => `${located(issue.path)}: ${issue.message}`).join("\n"));
 	checkReferences([parsed.data]);
 }
 /**
 * 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.
 */
 async function resolveDraftEdit(read, sessionId, edit) {
@@ -531,10 +764,7 @@ async function resolveDraftEdit(read, sessionId, edit) {
 		directory,
 		edit: {
 			...rest,
-			content: {
-				type: "animation",
-				...fields
-			}
+			content: fields
 		}
 	};
 	const targetId = String(rest.targetId);
@@ -544,13 +774,11 @@ async function resolveDraftEdit(read, sessionId, edit) {
 		directory,
 		edit: {
 			...rest,
-			content: {
-				type: "animation",
-				...fields
-			}
+			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 = {};
 	for (const field of FIELDS) if (JSON.stringify(fields[field]) !== JSON.stringify(current[field])) changes[field] = fields[field] ?? null;
 	return Object.keys(changes).length ? {
@@ -634,7 +862,7 @@ async function callPublicTool(client, tool, input, signal) {
 	};
 	if (tool.name === "session_get_instructions" && rest.topic === "animation") {
 		const instructions = await callAuthoringTool(client, tool, fields, signal);
-		const hint = stageReferenceHint(await writeStageReference());
+		const hint = stageReferenceText(await writeStageReference());
 		if (instructions instanceof ToolText) return new ToolText(`${instructions.text}\n\n${hint}`);
 		return isStringValue(instructions) ? `${instructions}\n\n${hint}` : instructions;
 	}
@@ -649,9 +877,45 @@ async function callPublicTool(client, tool, input, signal) {
 	const result = await callAuthoringTool(client, tool, fields, signal);
 	if (result instanceof ToolText) return result;
 	const published = withoutRepositoryIds(publicResult(result));
+	if (tool.name === "session_render" && isStringValue(sessionId) && isStringValue(rest.targetId)) return saveRenderedFrame(published, sessionId, rest.targetId);
 	if (draft && isStringValue(sessionId) && isJsonObject(published) && isStringValue(published.targetId)) await recordPublish(read, sessionId, published.targetId, draft.directory).catch(() => {});
 	return published;
 }
+/** A rendered frame's PNG, for an agent that reads images from a tool
+* result, and the rest of the result for its text. */
+function renderedImage(tool, result) {
+	if (tool.name !== "session_render" || result instanceof ToolText || !isJsonObject(result) || !isStringValue(result.png)) return { result };
+	const { png, ...rest } = result;
+	return {
+		image: {
+			data: png,
+			mimeType: "image/png"
+		},
+		result: rest
+	};
+}
+/** Writes the frame's PNG where the agent can open it with its own tools,
+* beside the animation drafts, and names the file in the result. A folder
+* that cannot be written leaves the image in the result alone. */
+async function saveRenderedFrame(result, sessionId, targetId) {
+	if (!isJsonObject(result) || !isStringValue(result.png)) return result;
+	const key = isJsonObject(result.frame) && isStringValue(result.frame.key) ? result.frame.key : "frame";
+	const file = path.join(devReviewHome(), "animation-renders", ...[
+		sessionId,
+		targetId,
+		`${key}.png`
+	].map((part) => part.replace(/[^\w.-]/g, "_")));
+	try {
+		await mkdir(path.dirname(file), { recursive: true });
+		await writeFile(file, Buffer.from(result.png, "base64"));
+	} catch {
+		return result;
+	}
+	return {
+		...result,
+		file
+	};
+}
 /** The read a draft compares and records against: session_get's JSON. */
 const INSPECT = {
 	name: "review_get",
@@ -712,4 +976,4 @@ function toolFailure(error, phase) {
 	};
 }
 //#endregion
-export { publicTool as i, RECOVERY as n, callPublicTool as r, toolFailure as t };
+export { renderedImage as a, publicTool as i, RECOVERY as n, callPublicTool as r, toolFailure as t };