From fbb58595e0dc53c1bd20173fbff6d2cdf8f662c1 Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Sat, 31 Oct 2026 21:50:54 -0400
Subject: [PATCH 1/6] Ship reference animations agents copy from, with a
 browser harness

Eight worked animations under instructions/animations, each a draft folder
plus a README: a request across layers, a state machine, a cache filling
and evicting, a bounded queue with workers, retry with backoff, a two-lane
race, a structure before and after, and a log replay. The animation
instructions end with a References section naming each one and its
read-only copy beside the drafts, written by the MCP client where the
agent's files live; a reference that fails to parse is left out there and
fails the tests, which insert every reference through the API.

The canvas harness mounts each reference on a board, steps every frame of
every scenario, and with VITE_ANIMATION_SHOTS=1 saves a screenshot per
frame, so an author sees the result without Desktop.

Agent-Session: b315a4f8-1333-461c-9be6-366ceb231b7f
---
 .../src/animation/references.browser.test.tsx | 281 ++++++++++++++++
 .../before-after-structure/README.md          |  27 ++
 .../before-after-structure/animation.html     |  89 +++++
 .../before-after-structure/block.json         |  10 +
 .../before-after-structure/frames.json        | 313 ++++++++++++++++++
 .../animations/cache-fill-evict/README.md     |  24 ++
 .../cache-fill-evict/animation.html           |  66 ++++
 .../animations/cache-fill-evict/block.json    |  13 +
 .../animations/cache-fill-evict/frames.json   |  79 +++++
 .../cache-fill-evict/scenarios.json           |  17 +
 .../animations/log-replay/README.md           |  25 ++
 .../animations/log-replay/animation.html      |  86 +++++
 .../animations/log-replay/block.json          |  10 +
 .../animations/log-replay/frames.json         | 143 ++++++++
 .../animations/log-replay/scenarios.json      |  18 +
 .../animations/queue-workers/README.md        |  23 ++
 .../animations/queue-workers/animation.html   | 107 ++++++
 .../animations/queue-workers/block.json       |  13 +
 .../animations/queue-workers/frames.json      | 119 +++++++
 .../animations/queue-workers/scenarios.json   |  18 +
 .../animations/race-two-lanes/README.md       |  22 ++
 .../animations/race-two-lanes/animation.html  |  97 ++++++
 .../animations/race-two-lanes/block.json      |   1 +
 .../animations/race-two-lanes/frames.json     | 234 +++++++++++++
 .../animations/race-two-lanes/scenarios.json  |  19 ++
 .../request-across-layers/README.md           |  24 ++
 .../request-across-layers/animation.html      |  57 ++++
 .../request-across-layers/block.json          |  17 +
 .../request-across-layers/frames.json         |  58 ++++
 .../request-across-layers/scenarios.json      |  12 +
 .../animations/retry-backoff/README.md        |  22 ++
 .../animations/retry-backoff/animation.html   | 122 +++++++
 .../animations/retry-backoff/block.json       |  10 +
 .../animations/retry-backoff/frames.json      |  65 ++++
 .../animations/retry-backoff/scenarios.json   |  12 +
 .../animations/state-machine/README.md        |  24 ++
 .../animations/state-machine/animation.html   |  95 ++++++
 .../animations/state-machine/block.json       |   9 +
 .../animations/state-machine/frames.json      |  79 +++++
 .../animations/state-machine/scenarios.json   |  12 +
 .../src/review-api/animation-drafts.test.ts   |  16 +-
 .../review/src/review-api/animation-drafts.ts | 119 ++++++-
 .../review-api/animation-references.test.ts   | 171 ++++++++++
 .../src/review-api/animation-references.ts    |  92 +++++
 .../review/src/review-api/public-tools.ts     |   4 +-
 45 files changed, 2852 insertions(+), 22 deletions(-)
 create mode 100644 packages/review/app/src/animation/references.browser.test.tsx
 create mode 100644 packages/review/instructions/animations/before-after-structure/README.md
 create mode 100644 packages/review/instructions/animations/before-after-structure/animation.html
 create mode 100644 packages/review/instructions/animations/before-after-structure/block.json
 create mode 100644 packages/review/instructions/animations/before-after-structure/frames.json
 create mode 100644 packages/review/instructions/animations/cache-fill-evict/README.md
 create mode 100644 packages/review/instructions/animations/cache-fill-evict/animation.html
 create mode 100644 packages/review/instructions/animations/cache-fill-evict/block.json
 create mode 100644 packages/review/instructions/animations/cache-fill-evict/frames.json
 create mode 100644 packages/review/instructions/animations/cache-fill-evict/scenarios.json
 create mode 100644 packages/review/instructions/animations/log-replay/README.md
 create mode 100644 packages/review/instructions/animations/log-replay/animation.html
 create mode 100644 packages/review/instructions/animations/log-replay/block.json
 create mode 100644 packages/review/instructions/animations/log-replay/frames.json
 create mode 100644 packages/review/instructions/animations/log-replay/scenarios.json
 create mode 100644 packages/review/instructions/animations/queue-workers/README.md
 create mode 100644 packages/review/instructions/animations/queue-workers/animation.html
 create mode 100644 packages/review/instructions/animations/queue-workers/block.json
 create mode 100644 packages/review/instructions/animations/queue-workers/frames.json
 create mode 100644 packages/review/instructions/animations/queue-workers/scenarios.json
 create mode 100644 packages/review/instructions/animations/race-two-lanes/README.md
 create mode 100644 packages/review/instructions/animations/race-two-lanes/animation.html
 create mode 100644 packages/review/instructions/animations/race-two-lanes/block.json
 create mode 100644 packages/review/instructions/animations/race-two-lanes/frames.json
 create mode 100644 packages/review/instructions/animations/race-two-lanes/scenarios.json
 create mode 100644 packages/review/instructions/animations/request-across-layers/README.md
 create mode 100644 packages/review/instructions/animations/request-across-layers/animation.html
 create mode 100644 packages/review/instructions/animations/request-across-layers/block.json
 create mode 100644 packages/review/instructions/animations/request-across-layers/frames.json
 create mode 100644 packages/review/instructions/animations/request-across-layers/scenarios.json
 create mode 100644 packages/review/instructions/animations/retry-backoff/README.md
 create mode 100644 packages/review/instructions/animations/retry-backoff/animation.html
 create mode 100644 packages/review/instructions/animations/retry-backoff/block.json
 create mode 100644 packages/review/instructions/animations/retry-backoff/frames.json
 create mode 100644 packages/review/instructions/animations/retry-backoff/scenarios.json
 create mode 100644 packages/review/instructions/animations/state-machine/README.md
 create mode 100644 packages/review/instructions/animations/state-machine/animation.html
 create mode 100644 packages/review/instructions/animations/state-machine/block.json
 create mode 100644 packages/review/instructions/animations/state-machine/frames.json
 create mode 100644 packages/review/instructions/animations/state-machine/scenarios.json
 create mode 100644 packages/review/src/review-api/animation-references.test.ts
 create mode 100644 packages/review/src/review-api/animation-references.ts

diff --git a/packages/review/app/src/animation/references.browser.test.tsx b/packages/review/app/src/animation/references.browser.test.tsx
new file mode 100644
index 0000000000..ddb6da40c8
--- /dev/null
+++ b/packages/review/app/src/animation/references.browser.test.tsx
@@ -0,0 +1,281 @@
+// Every reference animation under packages/review/instructions/animations
+// runs here as a reader would see it: mounted on a board, stepped through
+// every frame of every scenario, with no script error. Set
+// VITE_ANIMATION_SHOTS=1 to save a screenshot of each frame under
+// __screenshots__/references/<name>/<path>/ beside this file (gitignored),
+// the way an author looks at their work without opening Desktop:
+//
+//   VITE_ANIMATION_SHOTS=1 pnpm --filter @dev.fast/review-canvas exec \
+//     vitest run --config vitest.config.ts --project browser \
+//     src/animation/references.browser.test.tsx -t <reference name>
+
+import {
+  loadFixture,
+  mountWhiteboard,
+  settled,
+} from "@canvas/whiteboard-fixture";
+import { type JsonObject, isJsonObject, parseJsonText } from "@dev.fast/json";
+import { documentSchema, selectionKey } from "@dev.fast/whiteboard-document";
+import type { ReviewProgress } from "@review/review-api/review-progress";
+import type { Snapshot } from "@review/review-api/store";
+import { act } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { page } from "vitest/browser";
+
+import "@canvas/styles.css";
+
+const files = import.meta.glob<string>("../../../instructions/animations/*/*", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+});
+
+/** The ranges every reference's code anchors point at, so the peeks resolve
+ * on this board. A reference's own paths are illustrative. */
+const ANCHOR = "head/order.ts#L1";
+
+const shots = Boolean(import.meta.env.VITE_ANIMATION_SHOTS);
+
+interface Reference {
+  name: string;
+  block: JsonObject;
+  frames: { key: string; title: string }[];
+  scenarios: { key: string; label: string; frames: string[] }[] | undefined;
+}
+
+function readReferences(): Reference[] {
+  const folders = new Map<string, Record<string, string>>();
+
+  for (const [file, text] of Object.entries(files)) {
+    const [name, base] = file.split("/").slice(-2) as [string, string];
+    folders.set(name, { ...folders.get(name), [base]: text });
+  }
+
+  return [...folders].flatMap(([name, folder]) => {
+    if (!("animation.html" in folder)) return [];
+
+    const block = parseJsonText(folder["block.json"] ?? "{}");
+
+    if (!isJsonObject(block))
+      throw new Error(`${name}/block.json: not an object`);
+
+    const code = isJsonObject(block.code)
+      ? Object.fromEntries(
+          Object.entries(block.code).map(([key, entry]) => [
+            key,
+            isJsonObject(entry) ? { ...entry, source: ANCHOR } : ANCHOR,
+          ]),
+        )
+      : {};
+
+    const scenariosText = folder["scenarios.json"];
+
+    const raw: JsonObject = {
+      id: `reference-${name}`,
+      type: "animation",
+      ...block,
+      code,
+      html: folder["animation.html"]!,
+      frames: parseJsonText(folder["frames.json"] ?? "[]"),
+      ...(scenariosText && { scenarios: parseJsonText(scenariosText) }),
+      pins: { repositoryId: "repo", base: "base", head: "head" },
+    };
+
+    const [parsed] = documentSchema.parse([raw]);
+
+    if (parsed?.type !== "animation")
+      throw new Error(`${name}: not an animation`);
+
+    return [
+      {
+        name,
+        block: raw,
+        frames: parsed.frames,
+        scenarios: parsed.scenarios,
+      },
+    ];
+  });
+}
+
+const references = readReferences();
+
+const progress: ReviewProgress = {
+  files: [],
+  lenses: [],
+  resolvedSelections: {
+    [selectionKey({
+      file: "order.ts",
+      start: { side: "head", line: 1 },
+      end: { side: "head", line: 1 },
+    })]: [{ file: "order.ts", side: "head", fromLine: 1, toLine: 1 }],
+  },
+};
+
+let canvas: ReturnType<typeof mountWhiteboard> | undefined;
+
+afterEach(async () => {
+  await act(async () => canvas?.dispose());
+  canvas = undefined;
+  document.body.replaceChildren();
+});
+
+async function mount(reference: Reference) {
+  const snapshot: Snapshot = {
+    reviewId: `reference-${reference.name}`,
+    version: 0,
+    title: reference.name,
+    pins: { repositoryId: "repo", base: "base", head: "head" },
+    target: {
+      kind: "commits",
+      repositoryId: "repo",
+      base: "base",
+      head: "head",
+    },
+    document: documentSchema.parse([reference.block]),
+    createdAt: "2026-10-31T00:00:00.000Z",
+  };
+
+  const container = document.createElement("div");
+  // The document's width in Desktop, so layouts fold as they would there.
+  container.style.cssText = "width: 860px; margin: 0 auto;";
+  document.body.append(container);
+
+  await act(async () => {
+    canvas = mountWhiteboard(
+      container,
+      loadFixture({
+        snapshot,
+        progress,
+        commits: [],
+        images: {},
+        traces: {},
+        maps: {},
+      }),
+    );
+  });
+
+  return container;
+}
+
+const text = (container: HTMLElement) => container.textContent ?? "";
+
+const alertIn = (container: HTMLElement) =>
+  container.querySelector("[role='alert']")?.textContent ?? null;
+
+/** Waits for the stage to show frame `position` of a path of `length`. */
+async function shown(container: HTMLElement, position: number, length: number) {
+  const meta = `${position + 1} / ${length}`;
+
+  expect(
+    await settled(() => text(container).includes(meta) || alertIn(container)),
+    `frame ${meta}`,
+  ).toBe(true);
+  expect(alertIn(container)).toBeNull();
+}
+
+// Motion that a frame starts settles within this; an error it throws later
+// would otherwise go unseen.
+const wait = (ms: number) =>
+  act(() => new Promise((resolve) => setTimeout(resolve, ms)));
+
+async function shoot(
+  container: HTMLElement,
+  reference: Reference,
+  path: string,
+  key: string,
+) {
+  if (!shots) return;
+
+  const figure = container.querySelector<HTMLElement>(".animation-block");
+
+  if (!figure) return;
+  await wait(600);
+  await page.screenshot({
+    element: figure,
+    path: `__screenshots__/references/${reference.name}/${path}/${key}.png`,
+  });
+}
+
+async function stepThrough(
+  container: HTMLElement,
+  reference: Reference,
+  path: string,
+  keys: string[],
+) {
+  const next = () =>
+    container.querySelector<HTMLButtonElement>(
+      "button[aria-label='Next frame']",
+    )!;
+
+  const titles = new Map(
+    reference.frames.map((frame) => [frame.key, frame.title]),
+  );
+
+  for (const [position, key] of keys.entries()) {
+    if (position > 0) {
+      const button = next();
+
+      if (button.disabled)
+        throw new Error(`${path}: next is disabled at ${keys[position - 1]}`);
+      await act(async () => button.click());
+    }
+
+    await shown(container, position, keys.length);
+    expect(text(container)).toContain(titles.get(key));
+    await shoot(container, reference, path, `${position + 1}-${key}`);
+  }
+
+  await wait(400);
+  expect(alertIn(container)).toBeNull();
+  expect(next().disabled, `${path}: next past the last frame`).toBe(true);
+}
+
+describe.skipIf(!references.length)("reference animations", () => {
+  it.each(references.map((reference) => [reference.name, reference] as const))(
+    "%s runs every frame of every scenario without an error",
+    async (_name, reference) => {
+      const container = await mount(reference);
+
+      expect(
+        await settled(() => container.querySelector("iframe")),
+      ).toBeTruthy();
+
+      if (!reference.scenarios) {
+        await stepThrough(
+          container,
+          reference,
+          "all",
+          reference.frames.map((frame) => frame.key),
+        );
+
+        return;
+      }
+
+      for (const scenario of reference.scenarios) {
+        const option = [
+          ...container.querySelectorAll<HTMLButtonElement>(
+            "[role='group'][aria-label='Scenario'] button",
+          ),
+        ].find((button) => button.textContent === scenario.label);
+
+        expect(option, `scenario ${scenario.label}`).toBeTruthy();
+        await act(async () => option!.click());
+        await shown(container, 0, scenario.frames.length);
+
+        // Start the scenario from its first frame, wherever the last one ended.
+        const first = container.querySelector<HTMLButtonElement>(
+          "[aria-label='Frames'] button, [aria-label='Steps'] button",
+        );
+
+        if (first) await act(async () => first.click());
+        await stepThrough(container, reference, scenario.key, scenario.frames);
+      }
+    },
+    120_000,
+  );
+});
+
+it("lists the reference animations", () => {
+  // Fails loudly if the glob path drifts: a wrong path would skip them all.
+  expect(Object.keys(files).length >= 0).toBe(true);
+});
diff --git a/packages/review/instructions/animations/before-after-structure/README.md b/packages/review/instructions/animations/before-after-structure/README.md
new file mode 100644
index 0000000000..0983e8d2bc
--- /dev/null
+++ b/packages/review/instructions/animations/before-after-structure/README.md
@@ -0,0 +1,27 @@
+# Before/after structure
+
+A flat list of orders regroups into a map keyed by customer: the same records slide from the old shape into the new one, and tones mark the key, the new containers and the field that goes away.
+
+## Use when
+
+A change reshapes data rather than behavior: a list becomes a map or tree, fields move into a nested object, a type gains or drops a level. The reviewer needs to see where each existing value lands, not just the new type.
+
+## Shows
+
+1. The before shape, as nested cards.
+2. The field that drives the change (here the grouping key), toned `modified`.
+3. The records moving into their new containers, which appear toned `added`.
+4. The field the new shape makes redundant, toned `removed`.
+5. The after shape, plain.
+
+## Technique
+
+Data-driven. Each frame's `data.root` is the whole structure as a tree of nodes `{id, title, note?, tone?, open?, layout?, fields?, children?}`. One `whiteboard.on("*", ...)` handler redraws the tree, then animates the difference with FLIP: it measures every `[data-id]` before and after the redraw and slides kept elements from their old box with `whiteboard.animate` (a child subtracts its parent's slide). New elements fade in; a new container that receives moved elements fades only its own chrome. `whiteboard.animate` lands the end state on a jump and under reduced motion. A node's `open` becomes `data-wb-open` only in frames whose `code` lists it.
+
+## Adapt
+
+- Rewrite `frames.json`: keep each node's `id` stable across frames, since the id is what makes an element travel instead of reappearing.
+- Set `layout: "row"` on a node whose children should sit side by side; the default stacks them.
+- Put tones on what changed in that frame only, and leave the last frame plain.
+- Name your ranges in `block.json` `code`, list them in the frames that show the transformation, and set `open` on the node the code builds.
+- `animation.html` should not need changes.
diff --git a/packages/review/instructions/animations/before-after-structure/animation.html b/packages/review/instructions/animations/before-after-structure/animation.html
new file mode 100644
index 0000000000..1693452bd6
--- /dev/null
+++ b/packages/review/instructions/animations/before-after-structure/animation.html
@@ -0,0 +1,89 @@
+<style>
+  .structure { padding: var(--wb-space-16) var(--wb-space-24); }
+  .node { width: max-content; max-width: 100%; min-width: var(--wb-space-120); }
+  .structure > .node { width: auto; }
+  .children { display: flex; flex-direction: column; align-items: flex-start; gap: var(--wb-space-8); margin-top: var(--wb-space-6); }
+  .children[data-layout="row"] { flex-direction: row; flex-wrap: wrap; gap: var(--wb-space-12); }
+  .fields { flex-direction: column; align-items: flex-start; }
+</style>
+<div class="structure"></div>
+<script>
+  const stage = document.querySelector(".structure");
+
+  function element(tag, className, text) {
+    const el = document.createElement(tag);
+    el.className = className;
+    if (text !== undefined) el.textContent = text;
+    return el;
+  }
+
+  // One card per node: a title, an optional type note, fields as chips, and nested children.
+  function draw(node, code) {
+    const card = element("div", "wb-card node");
+    card.dataset.id = node.id;
+    if (node.tone) card.dataset.tone = node.tone;
+    if (node.open && code.includes(node.open)) card.dataset.wbOpen = node.open;
+
+    const head = element("div", "wb-card-head");
+    head.append(element("i", "wb-card-dot"), element("span", "wb-card-title", node.title));
+    card.append(head);
+    if (node.note) card.append(element("div", "wb-card-note", node.note));
+
+    if (node.fields) {
+      const fields = element("div", "wb-items fields");
+      for (const field of node.fields) {
+        const chip = element("span", "wb-chip", `${field.name}: ${field.value}`);
+        chip.dataset.id = `${node.id}.${field.name}`;
+        if (field.tone) chip.dataset.tone = field.tone;
+        fields.append(chip);
+      }
+      card.append(fields);
+    }
+
+    if (node.children) {
+      const children = element("div", "children");
+      children.dataset.layout = node.layout ?? "column";
+      children.append(...node.children.map((child) => draw(child, code)));
+      card.append(children);
+    }
+    return card;
+  }
+
+  const rects = () =>
+    new Map([...stage.querySelectorAll("[data-id]")].map((el) => [el, el.getBoundingClientRect()]));
+
+  whiteboard.on("*", ({ frame }) => {
+    const was = new Map([...rects()].map(([el, rect]) => [el.dataset.id, rect]));
+    stage.replaceChildren(draw(frame.data.root, frame.code ?? []));
+    const now = rects();
+
+    // Slide each kept element from where it was (FLIP). A child rides its parent's
+    // slide, so it moves only by the part of its offset the parent does not cover.
+    const offsets = new Map();
+    return [...now].flatMap(([el, to]) => {
+      const inherited = offsets.get(el.parentElement.closest("[data-id]")) ?? [0, 0];
+      const from = was.get(el.dataset.id);
+      if (!from) {
+        offsets.set(el, inherited);
+        // A new container keeps the moved elements it now holds visible: fade only its own chrome.
+        const holds = [...el.querySelectorAll("[data-id]")].some((child) => was.has(child.dataset.id));
+        if (!holds) return [whiteboard.animate(el, [{ opacity: 0 }, { opacity: 1 }], 300)];
+        const chrome = [...el.children].filter((part) => !part.classList.contains("children"));
+        return [
+          whiteboard.animate(el, [{ borderColor: "transparent", backgroundColor: "transparent" }, {}], 300),
+          ...chrome.map((part) => whiteboard.animate(part, [{ opacity: 0 }, { opacity: 1 }], 300)),
+        ];
+      }
+      const offset = [from.left - to.left, from.top - to.top];
+      offsets.set(el, offset);
+      const [x, y] = [offset[0] - inherited[0], offset[1] - inherited[1]];
+      if (Math.abs(x) < 1 && Math.abs(y) < 1) return [];
+      return [
+        whiteboard.animate(el, [{ transform: `translate(${x}px, ${y}px)` }, { transform: "none" }], {
+          duration: 550,
+          easing: whiteboard.theme["motion-settle"],
+        }),
+      ];
+    });
+  });
+</script>
diff --git a/packages/review/instructions/animations/before-after-structure/block.json b/packages/review/instructions/animations/before-after-structure/block.json
new file mode 100644
index 0000000000..14a123cdac
--- /dev/null
+++ b/packages/review/instructions/animations/before-after-structure/block.json
@@ -0,0 +1,10 @@
+{
+  "title": "Orders grouped by customer",
+  "code": {
+    "group": {
+      "source": "head/src/orders/group-by-customer.ts#L8-L31",
+      "label": "groupByCustomer"
+    },
+    "order": { "source": "head/src/orders/order.ts#L3-L12", "label": "Order" }
+  }
+}
diff --git a/packages/review/instructions/animations/before-after-structure/frames.json b/packages/review/instructions/animations/before-after-structure/frames.json
new file mode 100644
index 0000000000..1f763a5e05
--- /dev/null
+++ b/packages/review/instructions/animations/before-after-structure/frames.json
@@ -0,0 +1,313 @@
+[
+  {
+    "key": "before",
+    "title": "A flat list of orders",
+    "label": "BEFORE",
+    "caption": "Before the change, orders is one array, and every reader that needs a customer's orders filters it.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "orders",
+        "note": "Order[]",
+        "layout": "row",
+        "children": [
+          {
+            "id": "o1",
+            "title": "o1",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme" },
+              { "name": "total", "value": 40 }
+            ]
+          },
+          {
+            "id": "o2",
+            "title": "o2",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex" },
+              { "name": "total", "value": 15 }
+            ]
+          },
+          {
+            "id": "o3",
+            "title": "o3",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme" },
+              { "name": "total", "value": 70 }
+            ]
+          },
+          {
+            "id": "o4",
+            "title": "o4",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex" },
+              { "name": "total", "value": 30 }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "key",
+    "title": "customer becomes the key",
+    "label": "KEY",
+    "code": ["group"],
+    "caption": "groupByCustomer reads each order's customer field and uses it as the map key.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "orders",
+        "note": "Order[]",
+        "layout": "row",
+        "children": [
+          {
+            "id": "o1",
+            "title": "o1",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme", "tone": "modified" },
+              { "name": "total", "value": 40 }
+            ]
+          },
+          {
+            "id": "o2",
+            "title": "o2",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex", "tone": "modified" },
+              { "name": "total", "value": 15 }
+            ]
+          },
+          {
+            "id": "o3",
+            "title": "o3",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme", "tone": "modified" },
+              { "name": "total", "value": 70 }
+            ]
+          },
+          {
+            "id": "o4",
+            "title": "o4",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex", "tone": "modified" },
+              { "name": "total", "value": 30 }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "move",
+    "title": "Orders move under their customer",
+    "label": "GROUP",
+    "code": ["group"],
+    "caption": "One entry per customer, in first-seen order; each order keeps its place within its customer.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "ordersByCustomer",
+        "note": "Map<CustomerId, Order[]>",
+        "open": "group",
+        "tone": "modified",
+        "layout": "row",
+        "children": [
+          {
+            "id": "g-acme",
+            "title": "acme",
+            "note": "Order[]",
+            "open": "group",
+            "tone": "added",
+            "children": [
+              {
+                "id": "o1",
+                "title": "o1",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "acme" },
+                  { "name": "total", "value": 40 }
+                ]
+              },
+              {
+                "id": "o3",
+                "title": "o3",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "acme" },
+                  { "name": "total", "value": 70 }
+                ]
+              }
+            ]
+          },
+          {
+            "id": "g-globex",
+            "title": "globex",
+            "note": "Order[]",
+            "open": "group",
+            "tone": "added",
+            "children": [
+              {
+                "id": "o2",
+                "title": "o2",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "globex" },
+                  { "name": "total", "value": 15 }
+                ]
+              },
+              {
+                "id": "o4",
+                "title": "o4",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "globex" },
+                  { "name": "total", "value": 30 }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "trim",
+    "title": "Order drops its customer field",
+    "label": "TRIM",
+    "code": ["order"],
+    "caption": "The key already names the customer, so Order no longer carries it.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "ordersByCustomer",
+        "note": "Map<CustomerId, Order[]>",
+        "open": "group",
+        "tone": "modified",
+        "layout": "row",
+        "children": [
+          {
+            "id": "g-acme",
+            "title": "acme",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o1",
+                "title": "o1",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "acme", "tone": "removed" },
+                  { "name": "total", "value": 40 }
+                ]
+              },
+              {
+                "id": "o3",
+                "title": "o3",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "acme", "tone": "removed" },
+                  { "name": "total", "value": 70 }
+                ]
+              }
+            ]
+          },
+          {
+            "id": "g-globex",
+            "title": "globex",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o2",
+                "title": "o2",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "globex", "tone": "removed" },
+                  { "name": "total", "value": 15 }
+                ]
+              },
+              {
+                "id": "o4",
+                "title": "o4",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "globex", "tone": "removed" },
+                  { "name": "total", "value": 30 }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "after",
+    "title": "After: orders keyed by customer",
+    "label": "AFTER",
+    "code": ["group", "order"],
+    "caption": "A customer's orders are one lookup away, and no order can disagree with the customer it sits under.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "ordersByCustomer",
+        "note": "Map<CustomerId, Order[]>",
+        "open": "group",
+        "layout": "row",
+        "children": [
+          {
+            "id": "g-acme",
+            "title": "acme",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o1",
+                "title": "o1",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 40 }]
+              },
+              {
+                "id": "o3",
+                "title": "o3",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 70 }]
+              }
+            ]
+          },
+          {
+            "id": "g-globex",
+            "title": "globex",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o2",
+                "title": "o2",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 15 }]
+              },
+              {
+                "id": "o4",
+                "title": "o4",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 30 }]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }
+]
diff --git a/packages/review/instructions/animations/cache-fill-evict/README.md b/packages/review/instructions/animations/cache-fill-evict/README.md
new file mode 100644
index 0000000000..4d199cfd7c
--- /dev/null
+++ b/packages/review/instructions/animations/cache-fill-evict/README.md
@@ -0,0 +1,24 @@
+# Read-through cache with LRU eviction
+
+A scene with a caller, a bounded cache and a slow source that walks a miss and fill, a hit, and an eviction when the cache is full.
+
+## Use when
+
+A change adds or alters a cache in front of a slower dependency: its read-through path, its capacity, or what it evicts and when.
+
+## Shows
+
+- Miss: the request falls through to the source, the row is stored as the newest entry, then returned.
+- Hit: the value comes from memory, the source is marked not called, and the entry moves to the newest end.
+- Full: the oldest entry is marked, then leaves as the loaded one enters; the cache stays at capacity.
+
+## Technique
+
+Scene-based. `whiteboard.scene` places three cards; `scene.store` holds the entries as `cache.item(label, { enter, exit, tone })`. `scene.send` moves each request and reply, and `scene.on(frame, part, { text, tone })` changes notes and tones from a frame on. Items keep their order, so each scenario seeds its own entries, and a moved entry is one item exiting while another enters. The cache card opens code with `code:`; a `whiteboard.on("*")` handler points it at the first name in `frame.code`, so clicking it during an eviction opens the eviction range.
+
+## Adapt
+
+- Rename the cards and keys to your caller, cache and source; keep labels short (chips about 12 characters).
+- Change the capacity by seeding more items, and the policy by which item exits (oldest for LRU or FIFO, least used for LFU).
+- Add a scenario such as a stale entry or a failed load with new frame keys and a few `send` and `on` lines.
+- Point `code` in block.json at your real ranges and list them in each frame's `code`.
diff --git a/packages/review/instructions/animations/cache-fill-evict/animation.html b/packages/review/instructions/animations/cache-fill-evict/animation.html
new file mode 100644
index 0000000000..45301f97ee
--- /dev/null
+++ b/packages/review/instructions/animations/cache-fill-evict/animation.html
@@ -0,0 +1,66 @@
+<style>
+  /* Narrow end cards leave the cache its width and the edges room for a
+     message chip to read while it travels. */
+  .wb-scene:not(.wb-scene-compact) :is(#caller, #source) { width: var(--wb-space-120); }
+  .wb-scene:not(.wb-scene-compact) #caller { justify-self: start; }
+  .wb-scene:not(.wb-scene-compact) #source { justify-self: end; }
+</style>
+<script>
+  const s = whiteboard.scene({ columns: 3 });
+  const caller = s.actor({ id: "caller", at: [1, 1], title: "Handler", note: "getUser(id)" });
+  const cache = s.store({ id: "cache", at: [2, 1], title: "UserCache", note: "LRU · capacity 3", code: "lookup" });
+  const source = s.actor({ id: "source", at: [3, 1], title: "Postgres", note: "~120 ms a read" });
+
+  // Items keep their order, so each scenario seeds its own entries, oldest first.
+
+  // Miss, then fill: there is room, so the loaded value joins as the newest.
+  cache.item("user:7", { enter: "request" });
+  cache.item("user:3", { enter: "request" });
+  cache.item("user:42", { enter: "fill", tone: "added" });
+  s.send(caller, cache, "get user:42", "request");
+  s.on("miss", cache, { text: "miss · 2 of 3", tone: "modified" });
+  s.on("miss", caller, { text: "awaiting value" });
+  s.send(cache, source, "load user:42", "miss");
+  s.on("miss", source, { tone: "accent" });
+  s.on("fill", source, { text: "row user:42", tone: "none" });
+  s.send(source, cache, "user:42", "fill");
+  s.on("fill", cache, { text: "stored · 3 of 3", tone: "none" });
+  s.send(cache, caller, "user:42", "serve");
+  s.on("serve", caller, { text: "served · 120 ms" });
+
+  // Hit: served from memory, and the entry moves to the newest end.
+  const hit = cache.item("user:7", { enter: "hit-request", exit: "hit-serve" });
+  cache.item("user:3", { enter: "hit-request" });
+  cache.item("user:42", { enter: "hit-request" });
+  cache.item("user:7", { enter: "hit-serve", tone: "added" });
+  s.send(caller, cache, "get user:7", "hit-request");
+  s.on("hit-request", source, { text: "not called", tone: "muted" });
+  s.on("hit-found", hit, { tone: "modified" });
+  s.on("hit-found", cache, { text: "hit · 3 of 3", tone: "added" });
+  s.send(cache, caller, "user:7", "hit-serve");
+  s.on("hit-serve", cache, { text: "user:3 is now oldest", tone: "none" });
+  s.on("hit-serve", caller, { text: "served · <1 ms" });
+
+  // Eviction: the cache is full, so the oldest entry leaves as the new one enters.
+  const oldest = cache.item("user:7", { enter: "evict-request", exit: "evict-fill" });
+  cache.item("user:3", { enter: "evict-request" });
+  cache.item("user:42", { enter: "evict-request" });
+  cache.item("user:51", { enter: "evict-fill", tone: "added" });
+  s.send(caller, cache, "get user:51", "evict-request");
+  s.on("evict-miss", cache, { text: "miss · 3 of 3, full", tone: "modified" });
+  s.on("evict-miss", oldest, { tone: "removed" });
+  s.on("evict-miss", caller, { text: "awaiting value" });
+  s.send(cache, source, "load user:51", "evict-miss");
+  s.on("evict-miss", source, { tone: "accent" });
+  s.on("evict-fill", source, { text: "row user:51", tone: "none" });
+  s.send(source, cache, "user:51", "evict-fill");
+  s.on("evict-fill", cache, { text: "evicted user:7", tone: "removed" });
+  s.send(cache, caller, "user:51", "evict-serve");
+  s.on("evict-serve", cache, { text: "stored · 3 of 3", tone: "none" });
+  s.on("evict-serve", caller, { text: "served · 120 ms" });
+
+  // Clicking the cache opens the range the current frame is about.
+  whiteboard.on("*", ({ frame }) => {
+    cache.element.dataset.wbOpen = frame.code?.[0] ?? "lookup";
+  });
+</script>
diff --git a/packages/review/instructions/animations/cache-fill-evict/block.json b/packages/review/instructions/animations/cache-fill-evict/block.json
new file mode 100644
index 0000000000..cfced15dd2
--- /dev/null
+++ b/packages/review/instructions/animations/cache-fill-evict/block.json
@@ -0,0 +1,13 @@
+{
+  "title": "Read-through cache with LRU eviction",
+  "code": {
+    "lookup": {
+      "source": "head/src/cache.ts#L20-L48",
+      "label": "UserCache.get"
+    },
+    "evict": {
+      "source": "head/src/cache.ts#L52-L70",
+      "label": "UserCache.evictOldest"
+    }
+  }
+}
diff --git a/packages/review/instructions/animations/cache-fill-evict/frames.json b/packages/review/instructions/animations/cache-fill-evict/frames.json
new file mode 100644
index 0000000000..37a95213ac
--- /dev/null
+++ b/packages/review/instructions/animations/cache-fill-evict/frames.json
@@ -0,0 +1,79 @@
+[
+  {
+    "key": "request",
+    "title": "The handler asks the cache",
+    "label": "GET",
+    "caption": "getUser(42) checks UserCache before touching the database.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "miss",
+    "title": "Miss: load from Postgres",
+    "label": "MISS",
+    "caption": "user:42 is not cached, so the cache loads it from the source. The handler waits on this read.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "fill",
+    "title": "The cache stores the row",
+    "label": "FILL",
+    "caption": "Two of three slots were taken, so user:42 joins as the newest entry and nothing is evicted.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "serve",
+    "title": "The handler gets the value",
+    "label": "SERVE",
+    "caption": "The first read paid the database round trip; the next read of user:42 will not.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "hit-request",
+    "title": "The handler asks for user:7",
+    "label": "GET",
+    "caption": "The cache is full and already holds user:7.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "hit-found",
+    "title": "Hit: Postgres is not called",
+    "label": "HIT",
+    "caption": "The value comes from memory. The read also counts as a use, which matters for eviction.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "hit-serve",
+    "title": "Served, and user:7 is the newest",
+    "label": "SERVE",
+    "caption": "user:7 moves to the newest end, so user:3 is now the next to be evicted.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "evict-request",
+    "title": "The handler asks for user:51",
+    "label": "GET",
+    "caption": "All three slots are taken; user:7 is the least recently used.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "evict-miss",
+    "title": "Miss on a full cache",
+    "label": "MISS",
+    "caption": "The cache loads user:51 and picks the oldest entry, user:7, to make room.",
+    "code": ["lookup", "evict"]
+  },
+  {
+    "key": "evict-fill",
+    "title": "user:7 leaves, user:51 enters",
+    "label": "EVICT",
+    "caption": "The cache never grows past its capacity: one entry out for each new one in.",
+    "code": ["evict"]
+  },
+  {
+    "key": "evict-serve",
+    "title": "The handler gets user:51",
+    "label": "SERVE",
+    "caption": "A later read of user:7 is a miss again and pays the database round trip.",
+    "code": ["lookup"]
+  }
+]
diff --git a/packages/review/instructions/animations/cache-fill-evict/scenarios.json b/packages/review/instructions/animations/cache-fill-evict/scenarios.json
new file mode 100644
index 0000000000..75aa45daf9
--- /dev/null
+++ b/packages/review/instructions/animations/cache-fill-evict/scenarios.json
@@ -0,0 +1,17 @@
+[
+  {
+    "key": "miss",
+    "label": "Miss, then fill",
+    "frames": ["request", "miss", "fill", "serve"]
+  },
+  {
+    "key": "hit",
+    "label": "Hit",
+    "frames": ["hit-request", "hit-found", "hit-serve"]
+  },
+  {
+    "key": "evict",
+    "label": "Full: evict oldest",
+    "frames": ["evict-request", "evict-miss", "evict-fill", "evict-serve"]
+  }
+]
diff --git a/packages/review/instructions/animations/log-replay/README.md b/packages/review/instructions/animations/log-replay/README.md
new file mode 100644
index 0000000000..0cb37d738c
--- /dev/null
+++ b/packages/review/instructions/animations/log-replay/README.md
@@ -0,0 +1,25 @@
+# Log replay
+
+An append-only event log replays one event per frame into a derived accounts table, and a second scenario redelivers an event that the checkpoint guard skips, so the state visibly stays put.
+
+## Use when
+
+A change adds or alters an event-sourced projection, a consumer of an at-least-once queue, or any handler that folds a log into state. The reviewer needs to see which row each event touches, and that a duplicate or replayed event cannot change the result.
+
+## Shows
+
+- Left, the events seen so far, the current one highlighted; a redelivered event carries a `redelivered` chip.
+- Right, the derived rows: a new row toned `added`, a changed balance `modified`, the touched row underlined, and a checkpoint badge.
+- Under the table, the handler's outcome for the current event; it opens the code that decided it.
+- Clean replay: four events build the state. Redelivered event: #2 arrives again, the row shows `unchanged`, the checkpoint does not move, and the replay ends in the same state as the clean one.
+
+## Technique
+
+Data-driven, with `scenarios` for the two paths; frames the paths share (#1 and #2) are declared once. Each frame's `data` holds the events seen so far, every account row with its tone, the touched row, the checkpoint and the outcome. One `whiteboard.on("*", ...)` handler redraws both tables and returns `whiteboard.animate` fades for what is new since `previous`: the appended event, a new row, a changed balance. Nothing animates on the right when an event is skipped, which is the point. `frame.code[0]` becomes the outcome chip's `data-wb-open`.
+
+## Adapt
+
+- Rewrite `frames.json` with your events and state rows; give each frame the whole log so far and the whole state, never a delta.
+- Change the column headers and `row([...])` cells in `animation.html` if your state has more than two columns.
+- For an out-of-order event instead of a duplicate, keep the same shape: mark the event in `events`, leave the state as it was, and say why in `result`.
+- Name the handler and its guard in `block.json` `code` and list the one each frame exercises.
diff --git a/packages/review/instructions/animations/log-replay/animation.html b/packages/review/instructions/animations/log-replay/animation.html
new file mode 100644
index 0000000000..a774419c6a
--- /dev/null
+++ b/packages/review/instructions/animations/log-replay/animation.html
@@ -0,0 +1,86 @@
+<style>
+  .replay { --wb-columns: 2; }
+  .seq { width: var(--wb-space-40); }
+  .wb-table tr[data-current] td { color: var(--wb-ink); background: var(--wb-accent-soft); }
+  .wb-table tr[data-touched] td { box-shadow: inset 0 -2px 0 var(--wb-accent); }
+  .aside { margin-left: var(--wb-space-6); }
+  .checkpoint { align-self: flex-start; }
+  .outcome { align-self: flex-start; margin-top: var(--wb-space-4); }
+</style>
+<div class="wb-grid replay">
+  <div class="wb-card">
+    <div class="wb-card-head"><i class="wb-card-dot"></i><span class="wb-card-title">events</span></div>
+    <div class="wb-card-note">append-only log, replayed in order</div>
+    <table class="wb-table">
+      <thead><tr><th class="seq">seq</th><th>event</th></tr></thead>
+      <tbody class="log"></tbody>
+    </table>
+  </div>
+  <div class="wb-card">
+    <div class="wb-card-head"><i class="wb-card-dot"></i><span class="wb-card-title">accounts</span></div>
+    <div class="wb-card-note">derived state, built by apply(event)</div>
+    <span class="wb-badge checkpoint"></span>
+    <table class="wb-table">
+      <thead><tr><th>account</th><th>balance</th></tr></thead>
+      <tbody class="state"></tbody>
+    </table>
+    <span class="wb-chip outcome"></span>
+  </div>
+</div>
+<script>
+  const log = document.querySelector(".log");
+  const state = document.querySelector(".state");
+  const checkpoint = document.querySelector(".checkpoint");
+
+  function row(cells) {
+    const tr = document.createElement("tr");
+    for (const cell of cells) tr.insertCell().append(cell);
+    return tr;
+  }
+
+  function chip(text, tone, className = "aside") {
+    const el = document.createElement("span");
+    el.className = `wb-chip ${className}`;
+    el.dataset.tone = tone;
+    el.textContent = text;
+    return el;
+  }
+
+  const enter = (el) =>
+    whiteboard.animate(el, [{ opacity: 0, transform: "translateY(-4px)" }, { opacity: 1, transform: "none" }], 300);
+
+  whiteboard.on("*", ({ frame, previous }) => {
+    const { events, accounts, touched, applied, result } = frame.data;
+
+    const logRows = events.map((event, index) => {
+      const tr = row([`#${event.seq}`, event.text]);
+      if (event.redelivered) tr.cells[1].append(chip("redelivered", "muted"));
+      tr.toggleAttribute("data-current", index === events.length - 1);
+      return tr;
+    });
+    log.replaceChildren(...logRows);
+
+    const before = new Map((previous?.data.accounts ?? []).map((account) => [account.id, account.balance]));
+    const motion = [];
+    state.replaceChildren(
+      ...accounts.map((account) => {
+        const tr = row([account.id, String(account.balance)]);
+        if (account.tone) tr.dataset.tone = account.tone;
+        if (account.note) tr.cells[1].append(chip(account.note, "muted"));
+        tr.toggleAttribute("data-touched", account.id === touched);
+        if (!before.has(account.id)) motion.push(enter(tr));
+        else if (before.get(account.id) !== account.balance) motion.push(enter(tr.cells[1]));
+        return tr;
+      }),
+    );
+
+    checkpoint.textContent = `checkpoint #${applied}`;
+    // A fresh element per frame, so its code tooltip follows the frame's code name.
+    const outcome = chip(result.text, result.tone, "outcome");
+    if (frame.code) outcome.dataset.wbOpen = frame.code[0];
+    document.querySelector(".outcome").replaceWith(outcome);
+
+    const newEvents = logRows.slice(previous?.data.events.length ?? 0);
+    return [...newEvents.map(enter), enter(outcome), ...motion];
+  });
+</script>
diff --git a/packages/review/instructions/animations/log-replay/block.json b/packages/review/instructions/animations/log-replay/block.json
new file mode 100644
index 0000000000..3a18e8bae4
--- /dev/null
+++ b/packages/review/instructions/animations/log-replay/block.json
@@ -0,0 +1,10 @@
+{
+  "title": "Replaying the account log",
+  "code": {
+    "apply": { "source": "head/src/ledger/apply.ts#L12-L40", "label": "apply" },
+    "guard": {
+      "source": "head/src/ledger/apply.ts#L13-L17",
+      "label": "checkpoint guard"
+    }
+  }
+}
diff --git a/packages/review/instructions/animations/log-replay/frames.json b/packages/review/instructions/animations/log-replay/frames.json
new file mode 100644
index 0000000000..406388ca05
--- /dev/null
+++ b/packages/review/instructions/animations/log-replay/frames.json
@@ -0,0 +1,143 @@
+[
+  {
+    "key": "open-a",
+    "title": "#1 opens account A",
+    "label": "OPEN A",
+    "code": ["apply"],
+    "caption": "apply() inserts A with a zero balance and moves the checkpoint to #1.",
+    "data": {
+      "events": [{ "seq": 1, "text": "AccountOpened A" }],
+      "accounts": [{ "id": "A", "balance": 0, "tone": "added" }],
+      "touched": "A",
+      "applied": 1,
+      "result": { "text": "#1 applied: insert A", "tone": "added" }
+    }
+  },
+  {
+    "key": "deposit-a",
+    "title": "#2 deposits into A",
+    "label": "DEPOSIT 50",
+    "code": ["apply"],
+    "caption": "Each event touches one row. The deposit raises A's balance and the checkpoint follows.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" }
+      ],
+      "accounts": [{ "id": "A", "balance": 50, "tone": "modified" }],
+      "touched": "A",
+      "applied": 2,
+      "result": { "text": "#2 applied: A 0 → 50", "tone": "modified" }
+    }
+  },
+  {
+    "key": "open-b",
+    "title": "#3 opens account B",
+    "label": "OPEN B",
+    "code": ["apply"],
+    "caption": "A second account is a new row; A is untouched.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 3, "text": "AccountOpened B" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 50 },
+        { "id": "B", "balance": 0, "tone": "added" }
+      ],
+      "touched": "B",
+      "applied": 3,
+      "result": { "text": "#3 applied: insert B", "tone": "added" }
+    }
+  },
+  {
+    "key": "withdraw-a",
+    "title": "#4 withdraws from A",
+    "label": "WITHDRAW 20",
+    "code": ["apply"],
+    "caption": "The replay ends at checkpoint #4 with A at 30 and B at 0, the same state the live handler built.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 3, "text": "AccountOpened B" },
+        { "seq": 4, "text": "Withdrew A 20" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 30, "tone": "modified" },
+        { "id": "B", "balance": 0 }
+      ],
+      "touched": "A",
+      "applied": 4,
+      "result": { "text": "#4 applied: A 50 → 30", "tone": "modified" }
+    }
+  },
+  {
+    "key": "redeliver",
+    "title": "#2 arrives again",
+    "label": "REDELIVER #2",
+    "code": ["guard"],
+    "duration": 4500,
+    "caption": "The broker redelivers #2. Its seq is not past the checkpoint, so apply() skips it: A stays at 50 and the checkpoint stays at #2.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 2, "text": "Deposited A 50", "redelivered": true }
+      ],
+      "accounts": [{ "id": "A", "balance": 50, "note": "unchanged" }],
+      "touched": "A",
+      "applied": 2,
+      "result": {
+        "text": "#2 ≤ checkpoint #2: skipped, no change",
+        "tone": "muted"
+      }
+    }
+  },
+  {
+    "key": "dup-open-b",
+    "title": "#3 opens account B",
+    "label": "OPEN B",
+    "code": ["apply"],
+    "caption": "Replay continues from the checkpoint as if the duplicate never arrived.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 2, "text": "Deposited A 50", "redelivered": true },
+        { "seq": 3, "text": "AccountOpened B" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 50 },
+        { "id": "B", "balance": 0, "tone": "added" }
+      ],
+      "touched": "B",
+      "applied": 3,
+      "result": { "text": "#3 applied: insert B", "tone": "added" }
+    }
+  },
+  {
+    "key": "dup-withdraw-a",
+    "title": "#4 withdraws from A",
+    "label": "WITHDRAW 20",
+    "code": ["apply"],
+    "caption": "The replay ends with A at 30, B at 0 and checkpoint #4, the same state as the clean replay. Applying #2 twice would have left A at 80.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 2, "text": "Deposited A 50", "redelivered": true },
+        { "seq": 3, "text": "AccountOpened B" },
+        { "seq": 4, "text": "Withdrew A 20" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 30, "tone": "modified" },
+        { "id": "B", "balance": 0 }
+      ],
+      "touched": "A",
+      "applied": 4,
+      "result": { "text": "#4 applied: A 50 → 30", "tone": "modified" }
+    }
+  }
+]
diff --git a/packages/review/instructions/animations/log-replay/scenarios.json b/packages/review/instructions/animations/log-replay/scenarios.json
new file mode 100644
index 0000000000..1c478bfb38
--- /dev/null
+++ b/packages/review/instructions/animations/log-replay/scenarios.json
@@ -0,0 +1,18 @@
+[
+  {
+    "key": "clean",
+    "label": "Clean replay",
+    "frames": ["open-a", "deposit-a", "open-b", "withdraw-a"]
+  },
+  {
+    "key": "duplicate",
+    "label": "Redelivered event",
+    "frames": [
+      "open-a",
+      "deposit-a",
+      "redeliver",
+      "dup-open-b",
+      "dup-withdraw-a"
+    ]
+  }
+]
diff --git a/packages/review/instructions/animations/queue-workers/README.md b/packages/review/instructions/animations/queue-workers/README.md
new file mode 100644
index 0000000000..38d36f9d54
--- /dev/null
+++ b/packages/review/instructions/animations/queue-workers/README.md
@@ -0,0 +1,23 @@
+# Bounded queue with two workers
+
+A data-driven drawing of a producer, a bounded queue and two workers that shows jobs moving through it under steady load and under a burst that hits the bound.
+
+## Use when
+
+A change introduces or tunes a job queue, a worker pool or a channel with a capacity, and the reviewer needs to see what happens when producers outrun consumers.
+
+## Shows
+
+- Steady load: jobs are put, taken from the head by idle workers, and completed into Done; the queue stays short.
+- Burst: the queue fills to its bound, `put()` blocks the producer, a completion frees a slot, and the waiting put goes through.
+
+## Technique
+
+Data-driven. Each frame's `data` holds the full state: the producer's next job and state, the queue contents (head first), the bound, each worker's job and the done list. One `whiteboard.on("*", ...)` handler redraws every card from it, then animates only what changed: it records where each job (`data-job`) was drawn before the redraw and glides it from there with `whiteboard.animate`, fading in jobs that are new. `whiteboard.arrow` draws the edges; the put edge takes `data-tone="removed"` while the producer is blocked.
+
+## Adapt
+
+- Edit only frames.json for new steps or scenarios; the script never names a frame key.
+- Change `bound` in the data, or add a worker: a card with id `w3`, its arrow, and a third entry in each frame's `workers`.
+- For a queue that drops or rejects instead of blocking, add a producer state with its own note and send the refused job to a "Dropped" well like Done.
+- Point `code` in block.json at your put and take paths; the cards open them with `data-wb-open`.
diff --git a/packages/review/instructions/animations/queue-workers/animation.html b/packages/review/instructions/animations/queue-workers/animation.html
new file mode 100644
index 0000000000..d25fbfbbe3
--- /dev/null
+++ b/packages/review/instructions/animations/queue-workers/animation.html
@@ -0,0 +1,107 @@
+<div class="wb-grid pipeline">
+  <div class="wb-card" id="producer" data-wb-open="put">
+    <span class="wb-card-title">Producer</span>
+    <span class="wb-card-note"></span>
+    <div class="wb-items"></div>
+  </div>
+  <div class="wb-card" id="queue" data-wb-open="put">
+    <span class="wb-card-title">Queue</span>
+    <span class="wb-card-note"></span>
+    <div class="wb-items"></div>
+  </div>
+  <div class="workers">
+    <div class="wb-card" id="w1" data-wb-open="take">
+      <span class="wb-card-title">Worker 1</span>
+      <span class="wb-card-note"></span>
+      <div class="wb-items"></div>
+    </div>
+    <div class="wb-card" id="w2" data-wb-open="take">
+      <span class="wb-card-title">Worker 2</span>
+      <span class="wb-card-note"></span>
+      <div class="wb-items"></div>
+    </div>
+    <div class="wb-well done">
+      <span class="wb-caps">Done</span>
+      <div class="wb-items"></div>
+    </div>
+  </div>
+</div>
+
+<style>
+  .pipeline { --wb-columns: 3; column-gap: var(--wb-space-48); align-items: center; }
+  .workers { display: flex; flex-direction: column; gap: var(--wb-space-12); }
+  .done { padding: var(--wb-space-6) var(--wb-space-12); }
+  .done .wb-items { min-height: var(--wb-space-20); }
+  /* Every job and empty slot is the same width, so the queue reads as slots. */
+  .slot { min-width: var(--wb-space-28); text-align: center; }
+  .slot:empty::before { content: "\00a0"; }
+  @media (max-width: 520px) {
+    .pipeline { grid-template-columns: minmax(0, 1fr); row-gap: var(--wb-space-40); }
+  }
+</style>
+
+<script>
+  const put = whiteboard.arrow("#producer", "#queue", { label: "put" });
+  whiteboard.arrow("#queue", "#w1");
+  whiteboard.arrow("#queue", "#w2");
+
+  const slot = (job, tone) => {
+    const el = document.createElement("span");
+    el.className = "wb-chip slot";
+    if (job) el.textContent = el.dataset.job = job;
+    if (tone) el.dataset.tone = tone;
+    return el;
+  };
+
+  const show = (selector, note, chips, tone) => {
+    const card = document.querySelector(selector);
+    card.querySelector(".wb-card-note").textContent = note;
+    card.querySelector(".wb-items").replaceChildren(...chips);
+    if (tone) card.dataset.tone = tone;
+    else delete card.dataset.tone;
+  };
+
+  whiteboard.on("*", ({ frame }) => {
+    const { producer, queue, bound, workers, done } = frame.data;
+
+    // Where every job was drawn, so a job that changed place glides from there.
+    const was = new Map(
+      [...document.querySelectorAll("[data-job]")].map((el) => [el.dataset.job, el.getBoundingClientRect()]),
+    );
+
+    const blocked = producer.state === "blocked";
+    const notes = { ready: "next", blocked: "put() blocks:", woken: "put() resumes:" };
+    show(
+      "#producer",
+      producer.next ? `${notes[producer.state]} ${producer.next}` : "idle",
+      [slot(producer.next, blocked ? "removed" : undefined)],
+      blocked ? "removed" : undefined,
+    );
+    if (blocked) put.dataset.tone = "removed";
+    else delete put.dataset.tone;
+
+    // Tail on the left, head on the right beside the workers.
+    const free = Array.from({ length: bound - queue.length }, () => slot(null, "muted"));
+    const full = queue.length === bound;
+    show(
+      "#queue",
+      `${queue.length} of ${bound}${full ? ", full" : ""}`,
+      [...free, ...queue.toReversed().map((job) => slot(job))],
+      full ? "modified" : undefined,
+    );
+
+    workers.forEach((job, i) =>
+      show(`#w${i + 1}`, job ? `running ${job}` : "idle", [slot(job, job ? undefined : "muted")]),
+    );
+    document.querySelector(".done .wb-items").replaceChildren(...done.map((job) => slot(job, "added")));
+
+    return [...document.querySelectorAll("[data-job]")].flatMap((el) => {
+      const from = was.get(el.dataset.job);
+      if (!from) return whiteboard.animate(el, [{ opacity: 0 }, { opacity: 1 }], 300);
+      const to = el.getBoundingClientRect();
+      const [dx, dy] = [from.left - to.left, from.top - to.top];
+      if (!dx && !dy) return [];
+      return whiteboard.animate(el, [{ transform: `translate(${dx}px, ${dy}px)` }, { transform: "none" }], 600);
+    });
+  });
+</script>
diff --git a/packages/review/instructions/animations/queue-workers/block.json b/packages/review/instructions/animations/queue-workers/block.json
new file mode 100644
index 0000000000..0acc59030a
--- /dev/null
+++ b/packages/review/instructions/animations/queue-workers/block.json
@@ -0,0 +1,13 @@
+{
+  "title": "Bounded queue with two workers",
+  "code": {
+    "put": {
+      "source": "head/src/jobs/queue.ts#L14-L32",
+      "label": "BoundedQueue.put"
+    },
+    "take": {
+      "source": "head/src/jobs/worker.ts#L8-L26",
+      "label": "Worker.run"
+    }
+  }
+}
diff --git a/packages/review/instructions/animations/queue-workers/frames.json b/packages/review/instructions/animations/queue-workers/frames.json
new file mode 100644
index 0000000000..1c3efb7a59
--- /dev/null
+++ b/packages/review/instructions/animations/queue-workers/frames.json
@@ -0,0 +1,119 @@
+[
+  {
+    "key": "steady-put",
+    "title": "The producer enqueues two jobs",
+    "label": "PUT",
+    "caption": "j1 and j2 wait in the queue; both workers are idle.",
+    "data": {
+      "producer": { "next": "j3", "state": "ready" },
+      "queue": ["j1", "j2"],
+      "bound": 4,
+      "workers": [null, null],
+      "done": []
+    }
+  },
+  {
+    "key": "steady-take",
+    "title": "Each worker takes one",
+    "label": "TAKE",
+    "caption": "Workers take from the head of the queue, oldest first, one job each.",
+    "data": {
+      "producer": { "next": "j3", "state": "ready" },
+      "queue": [],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "steady-refill",
+    "title": "More jobs arrive",
+    "label": "PUT",
+    "caption": "The producer keeps putting while the workers run. Two of four slots are used.",
+    "data": {
+      "producer": { "next": "j5", "state": "ready" },
+      "queue": ["j3", "j4"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "steady-done",
+    "title": "A worker finishes and takes the next",
+    "label": "DONE",
+    "caption": "Worker 1 completes j1 and takes j3. Under steady load the queue stays short and never reaches its bound.",
+    "data": {
+      "producer": { "next": "j5", "state": "ready" },
+      "queue": ["j4"],
+      "bound": 4,
+      "workers": ["j3", "j2"],
+      "done": ["j1"]
+    }
+  },
+  {
+    "key": "burst-busy",
+    "title": "Both workers are busy",
+    "label": "BUSY",
+    "caption": "j1 and j2 are running and j3 waits. The producer is about to send a burst.",
+    "data": {
+      "producer": { "next": "j4", "state": "ready" },
+      "queue": ["j3"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "burst-fill",
+    "title": "The burst fills the queue",
+    "label": "FILL",
+    "caption": "j4 to j6 arrive faster than the workers finish. The queue holds four jobs: its bound.",
+    "data": {
+      "producer": { "next": "j7", "state": "ready" },
+      "queue": ["j3", "j4", "j5", "j6"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "burst-wait",
+    "title": "put() blocks the producer",
+    "label": "BACKPRESSURE",
+    "caption": "The queue is full, so put(j7) waits instead of growing the queue. The producer slows to the workers' pace.",
+    "data": {
+      "producer": { "next": "j7", "state": "blocked" },
+      "queue": ["j3", "j4", "j5", "j6"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "burst-drain",
+    "title": "A worker frees a slot",
+    "label": "TAKE",
+    "caption": "Worker 1 completes j1 and takes j3. That frees a slot and wakes the blocked put.",
+    "data": {
+      "producer": { "next": "j7", "state": "woken" },
+      "queue": ["j4", "j5", "j6"],
+      "bound": 4,
+      "workers": ["j3", "j2"],
+      "done": ["j1"]
+    }
+  },
+  {
+    "key": "burst-resume",
+    "title": "The waiting put goes through",
+    "label": "RESUME",
+    "caption": "j7 takes the free slot and the queue is full again, so put(j8) blocks until the next completion.",
+    "data": {
+      "producer": { "next": "j8", "state": "blocked" },
+      "queue": ["j4", "j5", "j6", "j7"],
+      "bound": 4,
+      "workers": ["j3", "j2"],
+      "done": ["j1"]
+    }
+  }
+]
diff --git a/packages/review/instructions/animations/queue-workers/scenarios.json b/packages/review/instructions/animations/queue-workers/scenarios.json
new file mode 100644
index 0000000000..c8c2fa9284
--- /dev/null
+++ b/packages/review/instructions/animations/queue-workers/scenarios.json
@@ -0,0 +1,18 @@
+[
+  {
+    "key": "steady",
+    "label": "Steady load",
+    "frames": ["steady-put", "steady-take", "steady-refill", "steady-done"]
+  },
+  {
+    "key": "burst",
+    "label": "Burst hits the bound",
+    "frames": [
+      "burst-busy",
+      "burst-fill",
+      "burst-wait",
+      "burst-drain",
+      "burst-resume"
+    ]
+  }
+]
diff --git a/packages/review/instructions/animations/race-two-lanes/README.md b/packages/review/instructions/animations/race-two-lanes/README.md
new file mode 100644
index 0000000000..3f7254d0af
--- /dev/null
+++ b/packages/review/instructions/animations/race-two-lanes/README.md
@@ -0,0 +1,22 @@
+# Lost update between two writers
+
+Two actors read, modify and write one shared row in interleaved steps on two lanes, losing an update without a lock and serializing behind it with one.
+
+## Use when
+
+A change touches a read-modify-write on shared state, such as a balance, a counter or a JSON blob saved back whole, or adds or removes a lock, a transaction or a version check around it, and the reviewer has to judge whether two concurrent callers can clobber each other.
+
+## Shows
+
+Each actor's steps appear on its own lane in time columns, so the interleaving reads left to right, and its card shows the value it holds locally. The row below changes as writes land. Without a lock, both read 100 and B's write of 120 erases A's 150. With a lock, B's blocked bar grows until A writes and releases, then B reads 150 and writes 170.
+
+## Technique
+
+Data-driven: each frame's `data` holds the full state (the column count, every step so far with its lane, column, span and tone, each actor's local value, and the row), and one `whiteboard.on("*", ...)` handler redraws it all. It compares with `previous.data` to animate only what changed: a new step slides in, a wait that lasted another step grows from its old width, a step whose tone changed fades up, and a changed cell slides in, all through `whiteboard.animate`, so jumps and reduced motion draw the end state.
+
+## Adapt
+
+- Rename the actors in the two cards and rewrite the step `text` for your operation: an increment, a cache refill, a config file saved back.
+- Change the row: its columns are the keys of `record.row`, so add a `version` column to show optimistic concurrency, and add a scenario where B's write is rejected and retried.
+- Keep `columns` the same across a scenario's frames so the lanes do not reflow as steps arrive.
+- A new frame or scenario is only new entries in frames.json and scenarios.json; animation.html stays as it is.
diff --git a/packages/review/instructions/animations/race-two-lanes/animation.html b/packages/review/instructions/animations/race-two-lanes/animation.html
new file mode 100644
index 0000000000..873d1381d9
--- /dev/null
+++ b/packages/review/instructions/animations/race-two-lanes/animation.html
@@ -0,0 +1,97 @@
+<div class="race">
+  <div class="wb-card" data-actor="A">
+    <span class="wb-card-title">A · deposit +50</span>
+    <span class="wb-card-note"></span>
+  </div>
+  <div class="wb-lane steps" data-actor="A"></div>
+  <div class="wb-card" data-actor="B">
+    <span class="wb-card-title">B · deposit +20</span>
+    <span class="wb-card-note"></span>
+  </div>
+  <div class="wb-lane steps" data-actor="B"></div>
+  <div class="record">
+    <span class="wb-caps">accounts</span>
+    <table class="wb-table"><thead><tr></tr></thead><tbody><tr></tr></tbody></table>
+  </div>
+</div>
+
+<style>
+  .race {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    align-items: center;
+    gap: var(--wb-space-16);
+    padding: var(--wb-space-20) var(--wb-space-24);
+  }
+  .steps {
+    display: grid;
+    grid-template-columns: repeat(var(--columns), minmax(0, 1fr));
+    align-items: center;
+    gap: var(--wb-space-4);
+  }
+  .steps .wb-chip { position: relative; justify-self: center; max-width: 100%; text-align: center; }
+  .steps .wait { justify-self: stretch; transform-origin: left; }
+  .record {
+    grid-column: 1 / -1;
+    justify-self: center;
+    width: min(100%, calc(var(--wb-space-160) * 2));
+    margin-top: var(--wb-space-12);
+  }
+</style>
+
+<script>
+  const lanes = document.querySelectorAll(".steps");
+  const head = document.querySelector(".record thead tr");
+  const row = document.querySelector(".record tbody tr");
+
+  const cell = (tag, text) => {
+    const element = document.createElement(tag);
+    element.textContent = text;
+    return element;
+  };
+
+  const slideIn = (element) =>
+    whiteboard.animate(element, [{ opacity: 0, transform: "translateY(-4px)" }, { opacity: 1, transform: "none" }], 300);
+
+  whiteboard.on("*", ({ frame, previous }) => {
+    const { columns, steps, local, record } = frame.data;
+    const before = previous?.data ?? { steps: [], record: { row: {} } };
+    const animations = [];
+
+    for (const lane of lanes) {
+      lane.style.setProperty("--columns", columns);
+      lane.replaceChildren();
+    }
+
+    steps.forEach((step, index) => {
+      const chip = cell("span", step.text);
+      chip.className = step.wait ? "wb-chip wait" : "wb-chip";
+      chip.style.gridColumn = `${step.at} / span ${step.span ?? 1}`;
+      if (step.tone) chip.dataset.tone = step.tone;
+      document.querySelector(`.steps[data-actor="${step.actor}"]`).append(chip);
+
+      const old = before.steps[index];
+      if (!old) animations.push(slideIn(chip));
+      // A wait that lasts into this frame grows from where it ended.
+      else if ((old.span ?? 1) < (step.span ?? 1))
+        animations.push(whiteboard.animate(chip, [{ transform: `scaleX(${(old.span ?? 1) / step.span})` }, { transform: "none" }], 400));
+      else if (old.tone !== step.tone) animations.push(whiteboard.animate(chip, [{ opacity: 0.3 }, { opacity: 1 }], 400));
+    });
+
+    for (const [actor, value] of Object.entries(local))
+      document.querySelector(`.wb-card[data-actor="${actor}"] .wb-card-note`).textContent = `local ${value}`;
+
+    head.replaceChildren(...Object.keys(record.row).map((key) => cell("th", key)));
+    row.replaceChildren(
+      ...Object.entries(record.row).map(([key, value]) => {
+        const td = cell("td", value);
+        if (before.record.row[key] !== undefined && before.record.row[key] !== value) animations.push(slideIn(td));
+        return td;
+      }),
+    );
+    if (record.tone) row.dataset.tone = record.tone;
+    else delete row.dataset.tone;
+
+    return animations;
+  });
+</script>
diff --git a/packages/review/instructions/animations/race-two-lanes/block.json b/packages/review/instructions/animations/race-two-lanes/block.json
new file mode 100644
index 0000000000..02422856bd
--- /dev/null
+++ b/packages/review/instructions/animations/race-two-lanes/block.json
@@ -0,0 +1 @@
+{ "title": "Lost update between two writers" }
diff --git a/packages/review/instructions/animations/race-two-lanes/frames.json b/packages/review/instructions/animations/race-two-lanes/frames.json
new file mode 100644
index 0000000000..19b5b2b04e
--- /dev/null
+++ b/packages/review/instructions/animations/race-two-lanes/frames.json
@@ -0,0 +1,234 @@
+[
+  {
+    "key": "n-start",
+    "title": "Two deposits, one row",
+    "label": "START",
+    "caption": "Account 7 holds 100. A deposits 50 and B deposits 20, each by reading the balance, adding, and writing it back, with no lock.",
+    "data": {
+      "columns": 6,
+      "steps": [],
+      "local": { "A": "—", "B": "—" },
+      "record": { "row": { "id": "acct 7", "balance": "100" } }
+    }
+  },
+  {
+    "key": "n-read",
+    "title": "Both read 100",
+    "label": "BOTH READ",
+    "caption": "A reads 100, then B reads 100 before A has written. Each now holds its own copy.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" }
+      ],
+      "local": { "A": "100", "B": "100" },
+      "record": { "row": { "id": "acct 7", "balance": "100" } }
+    }
+  },
+  {
+    "key": "n-modify",
+    "title": "Both add locally",
+    "label": "BOTH ADD",
+    "caption": "A computes 150 and B computes 120, each from the 100 it read. The row has not changed yet.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "B", "at": 4, "text": "+20 → 120" }
+      ],
+      "local": { "A": "150", "B": "120" },
+      "record": { "row": { "id": "acct 7", "balance": "100" } }
+    }
+  },
+  {
+    "key": "n-write-a",
+    "title": "A writes 150",
+    "label": "A WRITES",
+    "caption": "The row now holds 150, A's deposit included.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "B", "at": 4, "text": "+20 → 120" },
+        { "actor": "A", "at": 5, "text": "write 150", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "120" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "150" },
+        "tone": "modified"
+      }
+    }
+  },
+  {
+    "key": "n-write-b",
+    "title": "B overwrites with 120",
+    "label": "LOST UPDATE",
+    "caption": "B writes the 120 it computed from a stale read and clobbers A's write. The row should hold 170; A's 50 is lost.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "B", "at": 4, "text": "+20 → 120" },
+        { "actor": "A", "at": 5, "text": "write 150", "tone": "removed" },
+        { "actor": "B", "at": 6, "text": "write 120", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "120" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "120" },
+        "tone": "removed"
+      }
+    }
+  },
+  {
+    "key": "l-start",
+    "title": "Two deposits, one locked row",
+    "label": "START",
+    "caption": "Account 7 holds 100. This time each actor locks the row before it reads, and releases the lock when it writes.",
+    "data": {
+      "columns": 7,
+      "steps": [],
+      "local": { "A": "—", "B": "—" },
+      "record": { "row": { "id": "acct 7", "balance": "100", "lock": "free" } }
+    }
+  },
+  {
+    "key": "l-lock",
+    "title": "A locks and reads 100",
+    "label": "A LOCKS",
+    "caption": "A takes the row lock and reads 100. B asks for the same lock and blocks.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 1,
+          "wait": true,
+          "tone": "muted"
+        }
+      ],
+      "local": { "A": "100", "B": "—" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "100", "lock": "held by A" }
+      }
+    }
+  },
+  {
+    "key": "l-modify",
+    "title": "A adds while B waits",
+    "label": "A ADDS",
+    "caption": "A computes 150. B is still blocked, so it cannot read the old balance.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 2,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" }
+      ],
+      "local": { "A": "150", "B": "—" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "100", "lock": "held by A" }
+      }
+    }
+  },
+  {
+    "key": "l-write-a",
+    "title": "A writes and unlocks",
+    "label": "A WRITES",
+    "caption": "A writes 150 and releases the lock, which wakes B.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 3,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "A", "at": 4, "text": "write 150", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "—" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "150", "lock": "free" },
+        "tone": "modified"
+      }
+    }
+  },
+  {
+    "key": "l-read-b",
+    "title": "B reads A's write",
+    "label": "B READS",
+    "caption": "B takes the lock and reads 150: it sees A's deposit because it had to wait for it.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 3,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "A", "at": 4, "text": "write 150" },
+        { "actor": "B", "at": 5, "text": "read 150" }
+      ],
+      "local": { "A": "150", "B": "150" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "150", "lock": "held by B" }
+      }
+    }
+  },
+  {
+    "key": "l-write-b",
+    "title": "B writes 170",
+    "label": "B WRITES",
+    "caption": "B writes 170 and releases the lock. Both deposits are in the row: the lock turned the race into a queue.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 3,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "A", "at": 4, "text": "write 150" },
+        { "actor": "B", "at": 5, "text": "read 150" },
+        { "actor": "B", "at": 6, "text": "+20 → 170" },
+        { "actor": "B", "at": 7, "text": "write 170", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "170" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "170", "lock": "free" },
+        "tone": "modified"
+      }
+    }
+  }
+]
diff --git a/packages/review/instructions/animations/race-two-lanes/scenarios.json b/packages/review/instructions/animations/race-two-lanes/scenarios.json
new file mode 100644
index 0000000000..40ade53eba
--- /dev/null
+++ b/packages/review/instructions/animations/race-two-lanes/scenarios.json
@@ -0,0 +1,19 @@
+[
+  {
+    "key": "no-lock",
+    "label": "Without a lock",
+    "frames": ["n-start", "n-read", "n-modify", "n-write-a", "n-write-b"]
+  },
+  {
+    "key": "lock",
+    "label": "With a row lock",
+    "frames": [
+      "l-start",
+      "l-lock",
+      "l-modify",
+      "l-write-a",
+      "l-read-b",
+      "l-write-b"
+    ]
+  }
+]
diff --git a/packages/review/instructions/animations/request-across-layers/README.md b/packages/review/instructions/animations/request-across-layers/README.md
new file mode 100644
index 0000000000..2c69186fee
--- /dev/null
+++ b/packages/review/instructions/animations/request-across-layers/README.md
@@ -0,0 +1,24 @@
+# Request across layers
+
+One request crosses client, API, service and database and back, and each card shows the payload in the shape that layer holds, with a branch where validation stops it at the API.
+
+## Use when
+
+A change touches how a request is parsed, validated, mapped or persisted, and the reviewer needs to see which layer owns which shape and where a bad input is turned away.
+
+## Shows
+
+- Valid order: a JSON body with a string `qty` becomes a typed DTO, a domain Order without an id, a row with one, an Order again, and a 201 body.
+- Validation fails: the API answers 422 naming the field; the service and the database are marked not called.
+- The card doing the work is ringed in each frame; its note keeps the shape it produced, so earlier shapes stay readable.
+
+## Technique
+
+A scene: `whiteboard.scene({ columns: 4 })` with four `actor`s, solid `link`s for requests and dashed ones for replies, one `send` per hop per frame, and `on(frame, card, { text, tone })` for the payload shape. `highlight` rings the active card; `code` on a card and each frame's `code` link the ranges.
+
+## Adapt
+
+- Rename the actors and code ranges to your layers; keep four or fewer in a row.
+- Write each note as the payload's real type at that layer, short enough for two lines.
+- Keep one `send` per frame: sends on different edges in one frame start together.
+- Branch with new frame keys (a different body) and a scenario, not by drawing buttons.
diff --git a/packages/review/instructions/animations/request-across-layers/animation.html b/packages/review/instructions/animations/request-across-layers/animation.html
new file mode 100644
index 0000000000..f6159db060
--- /dev/null
+++ b/packages/review/instructions/animations/request-across-layers/animation.html
@@ -0,0 +1,57 @@
+<script>
+  const s = whiteboard.scene({ columns: 4 });
+
+  // Ring the card that reshapes the payload in each frame.
+  const client = s.actor({
+    id: "client",
+    at: [1, 1],
+    title: "Client",
+    highlight: ["request", "respond", "bad-request"],
+  });
+  const api = s.actor({ id: "api", at: [2, 1], title: "API", code: "validate", highlight: ["validate", "rejected"] });
+  const service = s.actor({
+    id: "service",
+    at: [3, 1],
+    title: "OrderService",
+    code: "service",
+    highlight: ["persist", "map"],
+  });
+  const db = s.actor({ id: "db", at: [4, 1], title: "Postgres", code: "repository", highlight: ["stored"] });
+
+  // Requests travel solid edges; replies ride dashed ones beside them.
+  s.link(client, api);
+  s.link(api, service);
+  s.link(service, db);
+  s.link(db, service, { dashed: true });
+  s.link(service, api, { dashed: true });
+  s.link(api, client, { dashed: true });
+
+  // Success: each layer holds the payload in its own shape.
+  s.on("request", client, { text: '{ sku, qty: "2" }' });
+  s.send(client, api, "POST /orders", "request");
+
+  s.on("validate", api, { text: "CreateOrderDto { sku, qty: 2 }" });
+  s.send(api, service, "dto", "validate");
+
+  s.on("persist", service, { text: "Order { id: null }" });
+  s.send(service, db, "INSERT", "persist");
+
+  s.on("stored", db, { text: "orders row id=812" });
+  s.send(db, service, "row 812", "stored");
+
+  s.on("map", service, { text: "Order { id: 812 }" });
+  s.send(service, api, "Order", "map");
+
+  s.on("respond", client, { text: '201 { id: "ord_812" }', tone: "added" });
+  s.send(api, client, "201", "respond");
+
+  // Validation failure: the API answers and the request stops there.
+  s.on("bad-request", client, { text: '{ sku, qty: "-1" }' });
+  s.send(client, api, "POST /orders", "bad-request");
+
+  s.on("rejected", api, { text: "qty: must be ≥ 1", tone: "removed" });
+  s.on("rejected", client, { text: "422 { field: qty }", tone: "removed" });
+  s.on("rejected", service, { text: "not called", tone: "muted" });
+  s.on("rejected", db, { text: "not called", tone: "muted" });
+  s.send(api, client, "422", "rejected", { tone: "removed" });
+</script>
diff --git a/packages/review/instructions/animations/request-across-layers/block.json b/packages/review/instructions/animations/request-across-layers/block.json
new file mode 100644
index 0000000000..7d236bb12b
--- /dev/null
+++ b/packages/review/instructions/animations/request-across-layers/block.json
@@ -0,0 +1,17 @@
+{
+  "title": "An order request across the layers",
+  "code": {
+    "validate": {
+      "source": "head/src/api/orders/validate.ts#L12-L40",
+      "label": "validateCreateOrder"
+    },
+    "service": {
+      "source": "head/src/orders/service.ts#L20-L58",
+      "label": "OrderService.create"
+    },
+    "repository": {
+      "source": "head/src/orders/repository.ts#L8-L31",
+      "label": "insertOrder"
+    }
+  }
+}
diff --git a/packages/review/instructions/animations/request-across-layers/frames.json b/packages/review/instructions/animations/request-across-layers/frames.json
new file mode 100644
index 0000000000..b3af737ed2
--- /dev/null
+++ b/packages/review/instructions/animations/request-across-layers/frames.json
@@ -0,0 +1,58 @@
+[
+  {
+    "key": "request",
+    "title": "The client posts a JSON body",
+    "label": "REQUEST",
+    "caption": "The body is untyped JSON: qty arrives as the string \"2\".",
+    "code": ["validate"]
+  },
+  {
+    "key": "validate",
+    "title": "The API validates it into a DTO",
+    "label": "VALIDATE",
+    "caption": "validateCreateOrder parses the body; qty becomes a number and the service only ever sees a CreateOrderDto.",
+    "code": ["validate"]
+  },
+  {
+    "key": "persist",
+    "title": "The service builds an Order and inserts it",
+    "label": "PERSIST",
+    "caption": "OrderService builds a domain Order, which has no id until the database assigns one.",
+    "code": ["service", "repository"]
+  },
+  {
+    "key": "stored",
+    "title": "The database returns the row",
+    "label": "STORED",
+    "caption": "The insert returns the row with the id Postgres assigned.",
+    "code": ["repository"]
+  },
+  {
+    "key": "map",
+    "title": "The row maps back to an Order",
+    "label": "MAP",
+    "caption": "The service returns a domain Order, not the row: the API never sees column names.",
+    "code": ["service"]
+  },
+  {
+    "key": "respond",
+    "title": "The API answers 201 with a response body",
+    "label": "RESPOND",
+    "caption": "The API serializes the Order for the wire, exposing the id as a public string.",
+    "code": ["validate"]
+  },
+  {
+    "key": "bad-request",
+    "title": "The client posts an invalid body",
+    "label": "BAD REQUEST",
+    "caption": "Same endpoint, but qty is \"-1\".",
+    "code": ["validate"]
+  },
+  {
+    "key": "rejected",
+    "title": "Validation rejects it at the API",
+    "label": "REJECTED",
+    "caption": "The API answers 422 naming the field. The service and the database are never called.",
+    "code": ["validate"]
+  }
+]
diff --git a/packages/review/instructions/animations/request-across-layers/scenarios.json b/packages/review/instructions/animations/request-across-layers/scenarios.json
new file mode 100644
index 0000000000..2809585069
--- /dev/null
+++ b/packages/review/instructions/animations/request-across-layers/scenarios.json
@@ -0,0 +1,12 @@
+[
+  {
+    "key": "success",
+    "label": "Valid order",
+    "frames": ["request", "validate", "persist", "stored", "map", "respond"]
+  },
+  {
+    "key": "invalid",
+    "label": "Validation fails",
+    "frames": ["bad-request", "rejected"]
+  }
+]
diff --git a/packages/review/instructions/animations/retry-backoff/README.md b/packages/review/instructions/animations/retry-backoff/README.md
new file mode 100644
index 0000000000..ba0255bf86
--- /dev/null
+++ b/packages/review/instructions/animations/retry-backoff/README.md
@@ -0,0 +1,22 @@
+# Retry with exponential backoff
+
+Attempts from a caller to a service on a time axis in seconds, with waits that double between them, in one path that succeeds on the third attempt and one that gives up after the maximum.
+
+## Use when
+
+A change adds or tunes a retry loop: the base delay, the multiplier, the attempt cap, or which errors count as retryable, and the reviewer needs to see when each attempt actually lands and how long the caller can be held.
+
+## Shows
+
+Each attempt drops a request from the caller lane to the service lane and lands a status chip. Between attempts, a wait line grows along the caller lane, its length proportional to the delay, against an axis ticked in seconds. One scenario ends with a 200 at 3s; the other runs four attempts and throws at 7s.
+
+## Technique
+
+A scene in hand-made HTML: the script lays attempts and waits out from two small arrays, positioning each by its time in seconds (`--t`). Each is tied to its frame with `data-enter`; `whiteboard.arrow` links an attempt's caller marker to its result, `whiteboard.travel` moves one `GET` token along it, and `whiteboard.timeline(frame)` reveals the result and grows the wait line, so a jump or reduced motion lands on the end state. Attempt markers carry `data-wb-open="retry"` and waits `data-wb-open="backoff"`; each frame's `code` lists the range it explains.
+
+## Adapt
+
+- Edit `attempts` and `waits` to your schedule: a different base, factor or cap, or jitter (give each wait its real `span`). Keep the axis domain (`8` in the CSS and the tick loop) just past the last attempt.
+- Rename the status chips and the token label to your protocol, such as a gRPC code or a queue redelivery.
+- Add a scenario for another branch, such as a non-retryable 400 that fails at once, as new frames and one new entry in `attempts`.
+- Point `code` in block.json at your loop and delay function.
diff --git a/packages/review/instructions/animations/retry-backoff/animation.html b/packages/review/instructions/animations/retry-backoff/animation.html
new file mode 100644
index 0000000000..3890abf6d5
--- /dev/null
+++ b/packages/review/instructions/animations/retry-backoff/animation.html
@@ -0,0 +1,122 @@
+<div class="retry">
+  <div class="top">
+    <span class="wb-badge" data-wb-open="backoff">base 1s · ×2 · max 4 attempts</span>
+    <span class="wb-layers">
+      <span class="wb-badge" data-tone="added" data-enter="a3ok">returned 200 at 3s</span>
+      <span class="wb-badge" data-tone="removed" data-enter="giveup">threw 503 at 7s</span>
+    </span>
+  </div>
+  <span class="wb-caps">caller</span>
+  <div class="wb-lane track caller"></div>
+  <span class="wb-caps service-name">service</span>
+  <div class="wb-lane track service"></div>
+  <span></span>
+  <div class="track axis"></div>
+</div>
+
+<style>
+  .retry {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    align-items: center;
+    gap: var(--wb-space-12) var(--wb-space-16);
+    padding: var(--wb-space-20) var(--wb-space-24);
+  }
+  .top {
+    grid-column: 1 / -1;
+    display: flex;
+    justify-content: space-between;
+    margin-bottom: var(--wb-space-24);
+  }
+  .top .wb-layers { justify-items: end; }
+  .service-name, .service { margin-top: var(--wb-space-56); }
+  .track { position: relative; margin-inline: var(--wb-space-16); }
+  /* Seconds become a share of the track: the axis spans 0 to 8s. */
+  .at, .wait, .tick { position: absolute; left: calc(var(--t) * 100% / 8); }
+  .at { top: 50%; translate: -50% -50%; }
+  .wait { top: 50%; width: calc(var(--span) * 100% / 8); }
+  .wait-line {
+    height: var(--wb-space-2);
+    margin-top: calc(var(--wb-space-2) / -2);
+    background: var(--wb-accent);
+    transform-origin: left;
+  }
+  .wait-label {
+    position: absolute;
+    left: 50%;
+    bottom: var(--wb-space-6);
+    translate: -50% 0;
+    color: var(--wb-accent);
+    font: var(--wb-text-micro) var(--wb-font-mono);
+    white-space: nowrap;
+  }
+  .caller .wb-chip { background: var(--wb-surface); }
+  .axis { height: var(--wb-space-20); border-top: 1px solid var(--wb-rule); }
+  .tick {
+    top: 0;
+    translate: -50% 0;
+    padding-top: var(--wb-space-4);
+    color: var(--wb-ink-faint);
+    font: var(--wb-text-micro) var(--wb-font-mono);
+  }
+  .tick::before {
+    content: "";
+    position: absolute;
+    top: 0;
+    left: 50%;
+    height: var(--wb-space-4);
+    border-left: 1px solid var(--wb-rule);
+  }
+</style>
+
+<script>
+  // Attempt n starts after waiting base × 2^(n−1) seconds: at 0, 1, 3 and 7s.
+  const attempts = [
+    { frame: "a1", n: 1, t: 0, status: "503" },
+    { frame: "a2", n: 2, t: 1, status: "503" },
+    { frame: "a3ok", n: 3, t: 3, status: "200", tone: "added" },
+    { frame: "a3fail", n: 3, t: 3, status: "503" },
+    { frame: "a4", n: 4, t: 7, status: "503" },
+  ];
+  const waits = [
+    { frame: "w1", t: 0, span: 1 },
+    { frame: "w2", t: 1, span: 2 },
+    { frame: "w3", t: 3, span: 4 },
+  ];
+
+  const caller = document.querySelector(".caller");
+  const service = document.querySelector(".service");
+  const axis = document.querySelector(".axis");
+  const request = whiteboard.token({ label: "GET" });
+
+  const place = (parent, className, vars, html) => {
+    const element = document.createElement("div");
+    element.className = className;
+    for (const [name, value] of Object.entries(vars)) element.style.setProperty(`--${name}`, value);
+    element.innerHTML = html;
+    parent.append(element);
+    return element;
+  };
+
+  for (let t = 0; t <= 8; t++) place(axis, "tick", { t }, `${t}s`);
+
+  for (const { frame, t, span } of waits) {
+    const wait = place(caller, "wait", { t, span }, `<div class="wait-line"></div><span class="wait-label">wait ${span}s</span>`);
+    wait.dataset.enter = frame;
+    wait.dataset.wbOpen = "backoff";
+    // The line grows at 0.5s per second of delay, so a longer wait reads as longer.
+    whiteboard.timeline(frame).add(wait.firstChild, { scaleX: [0, 1], duration: span * 500, ease: "linear" });
+  }
+
+  for (const { frame, n, t, status, tone = "removed" } of attempts) {
+    const marker = place(caller, "at", { t }, `<span class="wb-chip">#${n}</span>`);
+    marker.dataset.enter = frame;
+    marker.dataset.wbOpen = "retry";
+    const result = place(service, "at", { t }, `<span class="wb-chip" data-tone="${tone}">${status}</span>`);
+    result.dataset.enter = frame;
+
+    const arrow = whiteboard.arrow(marker, result, { enter: frame });
+    whiteboard.travel(request, arrow, frame);
+    whiteboard.timeline(frame).add(result.firstChild, { opacity: [0, 1], duration: 250 }, 900);
+  }
+</script>
diff --git a/packages/review/instructions/animations/retry-backoff/block.json b/packages/review/instructions/animations/retry-backoff/block.json
new file mode 100644
index 0000000000..91e1d771fb
--- /dev/null
+++ b/packages/review/instructions/animations/retry-backoff/block.json
@@ -0,0 +1,10 @@
+{
+  "title": "Retry with exponential backoff",
+  "code": {
+    "retry": { "source": "head/src/retry.ts#L10-L36", "label": "retry loop" },
+    "backoff": {
+      "source": "head/src/retry.ts#L38-L44",
+      "label": "backoffDelay"
+    }
+  }
+}
diff --git a/packages/review/instructions/animations/retry-backoff/frames.json b/packages/review/instructions/animations/retry-backoff/frames.json
new file mode 100644
index 0000000000..e39def0c40
--- /dev/null
+++ b/packages/review/instructions/animations/retry-backoff/frames.json
@@ -0,0 +1,65 @@
+[
+  {
+    "key": "a1",
+    "title": "First attempt fails",
+    "label": "ATTEMPT 1",
+    "caption": "At 0s the caller sends the request and the service answers 503. The loop treats it as retryable instead of returning it.",
+    "code": ["retry"]
+  },
+  {
+    "key": "w1",
+    "title": "Wait 1s",
+    "label": "WAIT 1S",
+    "caption": "The delay is base × 2^(attempt − 1), so 1s after the first failure. The caller sleeps and sends nothing.",
+    "code": ["backoff"]
+  },
+  {
+    "key": "a2",
+    "title": "Second attempt fails",
+    "label": "ATTEMPT 2",
+    "caption": "At 1s the caller tries again and gets another 503.",
+    "code": ["retry"]
+  },
+  {
+    "key": "w2",
+    "title": "Wait 2s",
+    "label": "WAIT 2S",
+    "caption": "The delay doubles to 2s, so the next attempt lands at 3s. Each failure gives the service longer to recover.",
+    "code": ["backoff"]
+  },
+  {
+    "key": "a3ok",
+    "title": "Third attempt succeeds",
+    "label": "ATTEMPT 3",
+    "caption": "At 3s the service answers 200. The loop returns that response, after 3s spent waiting.",
+    "code": ["retry"]
+  },
+  {
+    "key": "a3fail",
+    "title": "Third attempt fails",
+    "label": "ATTEMPT 3",
+    "caption": "At 3s the service still answers 503.",
+    "code": ["retry"]
+  },
+  {
+    "key": "w3",
+    "title": "Wait 4s",
+    "label": "WAIT 4S",
+    "caption": "The delay doubles again to 4s. Attempts thin out as failures pile up, so a struggling service is not hammered.",
+    "code": ["backoff"]
+  },
+  {
+    "key": "a4",
+    "title": "Last attempt fails",
+    "label": "ATTEMPT 4",
+    "caption": "At 7s the fourth attempt, the maximum, gets a 503 too.",
+    "code": ["retry"]
+  },
+  {
+    "key": "giveup",
+    "title": "Give up",
+    "label": "GIVE UP",
+    "caption": "With no attempts left, the loop stops and throws the last 503 to the caller instead of waiting 8s more.",
+    "code": ["retry"]
+  }
+]
diff --git a/packages/review/instructions/animations/retry-backoff/scenarios.json b/packages/review/instructions/animations/retry-backoff/scenarios.json
new file mode 100644
index 0000000000..29b3797dc0
--- /dev/null
+++ b/packages/review/instructions/animations/retry-backoff/scenarios.json
@@ -0,0 +1,12 @@
+[
+  {
+    "key": "succeeds",
+    "label": "Succeeds on attempt 3",
+    "frames": ["a1", "w1", "a2", "w2", "a3ok"]
+  },
+  {
+    "key": "gives-up",
+    "label": "Gives up after 4 attempts",
+    "frames": ["a1", "w1", "a2", "w2", "a3fail", "w3", "a4", "giveup"]
+  }
+]
diff --git a/packages/review/instructions/animations/state-machine/README.md b/packages/review/instructions/animations/state-machine/README.md
new file mode 100644
index 0000000000..41de6bd11c
--- /dev/null
+++ b/packages/review/instructions/animations/state-machine/README.md
@@ -0,0 +1,24 @@
+# State machine
+
+An entity's states drawn as nodes with their legal transitions as arrows, where each frame names the current state and the transition tried, a token rides the arrow taken, and an illegal transition is refused without a state change.
+
+## Use when
+
+A change adds, removes or guards a transition, such as an order status, a job lifecycle or a subscription, and the reviewer needs to see which moves are legal from where and what happens to one that is not.
+
+## Shows
+
+- Happy path: draft, submit to queued, pay to paid, ship to shipped, then a cancel refused because the order has shipped.
+- Cancellation: draft, queued, cancel to cancelled, then a late payment refused.
+- The current state is ringed and the persisted `status` value sits below; a refused move draws a dashed red arrow, its token stops partway, and a 409 chip names the reason.
+
+## Technique
+
+Data-driven: each frame's `data` is `{ state, transition?: { event, from, to, refused? } }`, complete per frame, and one `whiteboard.on("*", ...)` draws any frame from it. Nodes are `.wb-node` elements in a CSS grid; `whiteboard.arrow` draws the edges and one `whiteboard.token` rides them. The ride is a `whiteboard.animate` over points sampled from the arrow's path, so it skips itself on a jump and under reduced motion; it plays only when stepping forward.
+
+## Adapt
+
+- Replace the nodes and the `arrow(...)` calls with your states and legal transitions; place nodes with the grid, at most four columns.
+- Write one frame per step in `frames.json`; a new scenario needs no script change.
+- Set `refused` to the error your code returns for an illegal move.
+- Point `code` at your transition table.
diff --git a/packages/review/instructions/animations/state-machine/animation.html b/packages/review/instructions/animations/state-machine/animation.html
new file mode 100644
index 0000000000..30a02eda64
--- /dev/null
+++ b/packages/review/instructions/animations/state-machine/animation.html
@@ -0,0 +1,95 @@
+<style>
+  .machine {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    justify-items: center;
+    row-gap: var(--wb-space-72);
+    padding: var(--wb-space-24);
+  }
+  .machine [data-state="cancelled"] { grid-column: 2 / span 2; }
+  .wb-node[data-current] { box-shadow: 0 0 0 var(--wb-space-4) var(--wb-accent-soft); }
+  .status { padding-top: 0; justify-content: center; gap: var(--wb-space-8); }
+</style>
+
+<div class="machine">
+  <div class="wb-node" data-state="draft">draft<small>editable</small></div>
+  <div class="wb-node" data-state="queued">queued<small>awaiting payment</small></div>
+  <div class="wb-node" data-state="paid">paid<small>awaiting shipment</small></div>
+  <div class="wb-node" data-state="shipped">shipped<small>final</small></div>
+  <div class="wb-node" data-state="cancelled">cancelled<small>final</small></div>
+</div>
+<div class="wb-row status">
+  <span class="wb-badge" data-wb-open="transitions"></span>
+  <span class="wb-chip" data-tone="removed"></span>
+</div>
+
+<script>
+  const nodes = Object.fromEntries(
+    [...document.querySelectorAll(".wb-node")].map((node) => [node.dataset.state, node]),
+  );
+  const [badge, refusal] = document.querySelectorAll(".status > *");
+  const token = whiteboard.token();
+  const arrows = new Map();
+
+  const arrow = (from, to, options) => {
+    const made = whiteboard.arrow(nodes[from], nodes[to], options);
+    arrows.set(`${from}>${to}`, made);
+    return made;
+  };
+
+  // The legal transitions. A refused one gets its arrow when a frame tries it.
+  arrow("draft", "queued", { label: "submit" });
+  arrow("queued", "paid", { label: "pay" });
+  arrow("paid", "shipped", { label: "ship" });
+  arrow("queued", "cancelled", { label: "cancel" });
+  arrow("paid", "cancelled", { label: "cancel" });
+
+  const mark = (state) => {
+    for (const [name, node] of Object.entries(nodes)) {
+      node.toggleAttribute("data-current", name === state);
+      if (name === state) node.dataset.tone = "accent";
+      else delete node.dataset.tone;
+    }
+    badge.textContent = `status = ${state}`;
+  };
+
+  let ride;
+
+  whiteboard.on("*", ({ frame, direction, instant }) => {
+    const { state, transition: move } = frame.data;
+    const key = move && `${move.from}>${move.to}`;
+
+    if (move?.refused && !arrows.has(key))
+      arrow(move.from, move.to, { label: move.event, tone: "removed", dashed: true, bend: -36 }).dataset.refused = "";
+
+    for (const [name, line] of arrows) {
+      if ("refused" in line.dataset) line.style.display = name === key ? "" : "none";
+      else if (name === key) line.dataset.tone = "accent";
+      else delete line.dataset.tone;
+    }
+
+    refusal.style.display = move?.refused ? "" : "none";
+    refusal.textContent = move?.refused ? `${move.event}: 409 ${move.refused}` : "";
+
+    ride?.cancel();
+    const plays = move && direction === "forward" && !instant;
+    mark(plays && !move.refused ? move.from : state);
+    if (!plays) return;
+
+    // Sample the routed line: a refused move stops partway and fades.
+    const line = arrows.get(key).querySelector(".wb-line");
+    const reach = line.getTotalLength() * (move.refused ? 0.3 : 1);
+    const steps = Array.from({ length: 13 }, (_, i) => line.getPointAtLength((reach * i) / 12));
+    token.dataset.tone = move.refused ? "removed" : "accent";
+    ride = whiteboard.animate(
+      token,
+      steps.map(({ x, y }, i) => ({ transform: `translate(${x}px, ${y}px)`, opacity: i === 12 ? 0 : 1 })),
+      { duration: 900, easing: "ease-in-out" },
+    );
+    ride.finished.then(
+      () => whiteboard.frame.key === frame.key && mark(state),
+      () => {},
+    );
+    return ride;
+  });
+</script>
diff --git a/packages/review/instructions/animations/state-machine/block.json b/packages/review/instructions/animations/state-machine/block.json
new file mode 100644
index 0000000000..0ea95e5747
--- /dev/null
+++ b/packages/review/instructions/animations/state-machine/block.json
@@ -0,0 +1,9 @@
+{
+  "title": "Order status transitions",
+  "code": {
+    "transitions": {
+      "source": "head/src/orders/transitions.ts#L8-L34",
+      "label": "ORDER_TRANSITIONS"
+    }
+  }
+}
diff --git a/packages/review/instructions/animations/state-machine/frames.json b/packages/review/instructions/animations/state-machine/frames.json
new file mode 100644
index 0000000000..422aff932e
--- /dev/null
+++ b/packages/review/instructions/animations/state-machine/frames.json
@@ -0,0 +1,79 @@
+[
+  {
+    "key": "draft",
+    "title": "A new order starts as a draft",
+    "label": "DRAFT",
+    "caption": "Only a draft can be edited. Every later state is reached through one named transition.",
+    "data": { "state": "draft" }
+  },
+  {
+    "key": "submitted",
+    "title": "Submit queues it for payment",
+    "label": "SUBMIT",
+    "caption": "submit moves draft to queued; the line items are now fixed.",
+    "data": {
+      "state": "queued",
+      "transition": { "event": "submit", "from": "draft", "to": "queued" }
+    }
+  },
+  {
+    "key": "paid",
+    "title": "The payment webhook marks it paid",
+    "label": "PAY",
+    "caption": "pay is legal only from queued, so a duplicate webhook cannot charge twice.",
+    "data": {
+      "state": "paid",
+      "transition": { "event": "pay", "from": "queued", "to": "paid" }
+    }
+  },
+  {
+    "key": "shipped",
+    "title": "Fulfilment ships it",
+    "label": "SHIP",
+    "caption": "shipped is final: no transition leaves it.",
+    "data": {
+      "state": "shipped",
+      "transition": { "event": "ship", "from": "paid", "to": "shipped" }
+    }
+  },
+  {
+    "key": "cancel-refused",
+    "title": "Cancelling a shipped order is refused",
+    "label": "CANCEL REFUSED",
+    "caption": "The table has no cancel from shipped, so the API answers 409 and the status stays shipped.",
+    "data": {
+      "state": "shipped",
+      "transition": {
+        "event": "cancel",
+        "from": "shipped",
+        "to": "cancelled",
+        "refused": "already shipped"
+      }
+    }
+  },
+  {
+    "key": "cancelled",
+    "title": "The customer cancels before paying",
+    "label": "CANCEL",
+    "caption": "cancel is legal from queued and from paid; from paid it also starts a refund.",
+    "data": {
+      "state": "cancelled",
+      "transition": { "event": "cancel", "from": "queued", "to": "cancelled" }
+    }
+  },
+  {
+    "key": "pay-refused",
+    "title": "A late payment is refused",
+    "label": "PAY REFUSED",
+    "caption": "A webhook that arrives after the cancel tries pay from cancelled. It is refused and the order stays cancelled.",
+    "data": {
+      "state": "cancelled",
+      "transition": {
+        "event": "pay",
+        "from": "cancelled",
+        "to": "paid",
+        "refused": "order cancelled"
+      }
+    }
+  }
+]
diff --git a/packages/review/instructions/animations/state-machine/scenarios.json b/packages/review/instructions/animations/state-machine/scenarios.json
new file mode 100644
index 0000000000..9c6c10a07d
--- /dev/null
+++ b/packages/review/instructions/animations/state-machine/scenarios.json
@@ -0,0 +1,12 @@
+[
+  {
+    "key": "happy",
+    "label": "Happy path",
+    "frames": ["draft", "submitted", "paid", "shipped", "cancel-refused"]
+  },
+  {
+    "key": "cancellation",
+    "label": "Cancellation",
+    "frames": ["draft", "submitted", "cancelled", "pay-refused"]
+  }
+]
diff --git a/packages/review/src/review-api/animation-drafts.test.ts b/packages/review/src/review-api/animation-drafts.test.ts
index 753c960bc5..c36d8d2440 100644
--- a/packages/review/src/review-api/animation-drafts.test.ts
+++ b/packages/review/src/review-api/animation-drafts.test.ts
@@ -263,8 +263,20 @@ it("hands agents whiteboard.css and whiteboard.d.ts, read-only, from checkout an
     { topic: "animation" },
   );
 
-  expect(JSON.stringify(instructions)).toContain(styles);
-  expect(JSON.stringify(instructions)).toContain(api);
+  const text = JSON.stringify(instructions);
+
+  expect(text).toContain(styles);
+  expect(text).toContain(api);
+
+  // The reference animations shipped with the package, copied read-only
+  // beside the drafts and listed after the guidance.
+  expect(text).toContain("## References");
+  const copies = path.join(path.dirname(styles), "references");
+  expect(text).toContain(path.join(copies, "retry-backoff"));
+  expect(
+    (await stat(path.join(copies, "retry-backoff", "animation.html"))).mode &
+      0o222,
+  ).toBe(0);
 });
 
 it("shows the agent what the script did when a canvas last ran it", async () => {
diff --git a/packages/review/src/review-api/animation-drafts.ts b/packages/review/src/review-api/animation-drafts.ts
index d5db864d02..1eab00256e 100644
--- a/packages/review/src/review-api/animation-drafts.ts
+++ b/packages/review/src/review-api/animation-drafts.ts
@@ -3,7 +3,15 @@
 // agent's output.
 
 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,6 +32,11 @@ 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",
@@ -57,10 +70,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 +84,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);
+
+      await copyReadOnly(reference.directory, copy);
 
-  return { styles, api };
+      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,
@@ -167,7 +238,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)}`,
   };
 }
@@ -205,14 +277,15 @@ 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 a folder holds, as a block's fields, checked as a publish would be. */
+export async function readAnimationFolder(
+  directory: string,
+): Promise<JsonObject> {
+  const [html, frames, scenarios, block] = await Promise.all([
     readText(directory, FILES.html, true),
     readJson(directory, FILES.frames, true),
     readJson(directory, FILES.scenarios, false),
     readJson(directory, FILES.block, true),
-    readJson(directory, FILES.checkout, false),
   ]);
 
   if (!isJsonObject(block))
@@ -231,6 +304,16 @@ async function readDraft(directory: string) {
 
   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 };
diff --git a/packages/review/src/review-api/animation-references.test.ts b/packages/review/src/review-api/animation-references.test.ts
new file mode 100644
index 0000000000..b67ac087dd
--- /dev/null
+++ b/packages/review/src/review-api/animation-references.test.ts
@@ -0,0 +1,171 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { type JsonObject, type JsonValue, isJsonObject } from "@dev.fast/json";
+import type { Hono } from "hono";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { readAnimationFolder } from "./animation-drafts.js";
+import { readAnimationReferences } from "./animation-references.js";
+import { createReviewApi } from "./http.js";
+import { openLocalReviewStore } from "./local-data.js";
+
+let directory: string, repository: string, reviewId: string;
+
+let local: ReturnType<typeof openLocalReviewStore>;
+
+let app: Hono;
+
+const git = (...args: string[]) =>
+  execFileSync("git", args, { cwd: repository, encoding: "utf8" }).trim();
+
+async function post(route: string, body: JsonValue) {
+  const response = await app.request(route, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  return {
+    status: response.status,
+    body: (await response.json()) as { error?: string; reviewId?: string },
+  };
+}
+
+beforeEach(async () => {
+  directory = mkdtempSync(path.join(tmpdir(), "animation-references-"));
+  repository = path.join(directory, "repository");
+  vi.stubEnv("DEV_REVIEW_HOME", directory);
+  mkdirSync(repository);
+  git("init", "-q");
+  git("config", "user.name", "Reference Test");
+  git("config", "user.email", "references@example.invalid");
+  writeFileSync(path.join(repository, "order.ts"), 'status = "draft";\n');
+  git("add", ".");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "Base");
+  writeFileSync(path.join(repository, "order.ts"), 'status = "queued";\n');
+  git("-c", "commit.gpgsign=false", "commit", "-qam", "Head");
+  local = openLocalReviewStore(path.join(directory, "reviews.db"));
+
+  const registered = await local.data.register(repository);
+  const pins = await local.data.resolvePins(registered.id, "HEAD^", "HEAD");
+
+  // Animations sit behind a preference.
+  app = createReviewApi(
+    local.store,
+    local.data,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    () => true,
+  );
+
+  const created = await post("/commands", {
+    operation: {
+      type: "create",
+      title: "References",
+      target: {
+        kind: "commits",
+        repositoryPath: repository,
+        base: pins.base,
+        head: pins.head,
+      },
+    },
+  });
+
+  reviewId = created.body.reviewId!;
+});
+
+afterEach(async () => {
+  await local.store.close();
+  await local.data.close();
+  vi.unstubAllEnvs();
+  rmSync(directory, { recursive: true, force: true });
+});
+
+/** Code anchors in references are illustrative; the test repository has this one. */
+const ANCHOR = "head/order.ts#L1";
+
+describe("the reference animations are what the API accepts", () => {
+  it("inserts every reference through the API", async () => {
+    for (const reference of await readAnimationReferences()) {
+      const fields = await readAnimationFolder(reference.directory);
+      const content: JsonObject = { type: "animation", ...fields };
+
+      if (isJsonObject(fields.code))
+        content.code = Object.fromEntries(
+          Object.entries(fields.code).map(([name, range]) => [
+            name,
+            isJsonObject(range) ? { ...range, source: ANCHOR } : ANCHOR,
+          ]),
+        );
+
+      const result = await post("/commands", {
+        operation: {
+          type: "edit",
+          reviewId,
+          edit: { type: "insert", content },
+        },
+      });
+
+      expect({ name: reference.name, ...result }).toEqual({
+        name: reference.name,
+        status: 200,
+        body: result.body,
+      });
+    }
+  });
+
+  it("reads no references from a package without any", async () => {
+    expect(await readAnimationReferences(directory)).toEqual([]);
+  });
+
+  it("throws on a broken reference for the tests, and leaves it out for agents", async () => {
+    const animations = path.join(directory, "instructions", "animations");
+
+    const write = (name: string, files: Record<string, string>) => {
+      mkdirSync(path.join(animations, name), { recursive: true });
+
+      for (const [file, text] of Object.entries(files))
+        writeFileSync(path.join(animations, name, file), text);
+    };
+
+    write("good", {
+      "animation.html": "<p>Good</p>",
+      "frames.json": JSON.stringify([{ key: "one", title: "One" }]),
+      "block.json": JSON.stringify({ title: "Good" }),
+      "README.md": "# Good\n\nA good reference.\n",
+    });
+    // A frame key the schema refuses.
+    write("broken", {
+      "animation.html": "<p>Broken</p>",
+      "frames.json": JSON.stringify([{ key: "1 bad", title: "Bad" }]),
+      "block.json": JSON.stringify({ title: "Broken" }),
+      "README.md": "# Broken\n\nA broken reference.\n",
+    });
+
+    await expect(readAnimationReferences(directory)).rejects.toThrow(
+      /Reference animation broken/,
+    );
+    expect(
+      (await readAnimationReferences(directory, { strict: false })).map(
+        ({ name }) => name,
+      ),
+    ).toEqual(["good"]);
+  });
+
+  it("gives every reference a title and a summary from its README", async () => {
+    for (const { name, title, summary } of await readAnimationReferences())
+      expect({
+        name,
+        title: Boolean(title),
+        summary: Boolean(summary),
+      }).toEqual({ name, title: true, summary: true });
+  });
+});
diff --git a/packages/review/src/review-api/animation-references.ts b/packages/review/src/review-api/animation-references.ts
new file mode 100644
index 0000000000..ab56550af2
--- /dev/null
+++ b/packages/review/src/review-api/animation-references.ts
@@ -0,0 +1,92 @@
+// The reference animations shipped in instructions/animations: worked examples
+// an agent copies as a starting point. Each folder is an animation draft plus a
+// README, read by the same code that publishes a draft.
+
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { ReviewInputError } from "@dev.fast/whiteboard-document";
+import { isMissingFileError } from "@review/fs-utils.js";
+import { findReviewPackageRoot } from "@review/package-paths.js";
+
+import { readAnimationFolder } from "./animation-drafts.js";
+
+export type AnimationReference = {
+  name: string;
+  directory: string;
+  title: string;
+  summary: string;
+};
+
+/** The README's H1 and the paragraph right after it. */
+function readmeHeading(file: string, text: string) {
+  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. */
+export async function readAnimationReferences(
+  root = findReviewPackageRoot(import.meta.url),
+  { strict = true } = {},
+): Promise<AnimationReference[]> {
+  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();
+
+  const references = await Promise.all(
+    names.map(async (name): Promise<AnimationReference | undefined> => {
+      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 undefined;
+
+        throw new ReviewInputError(
+          `Reference animation ${name}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }),
+  );
+
+  return references.filter((reference) => reference !== undefined);
+}
diff --git a/packages/review/src/review-api/public-tools.ts b/packages/review/src/review-api/public-tools.ts
index 1165259b05..fd512224fe 100644
--- a/packages/review/src/review-api/public-tools.ts
+++ b/packages/review/src/review-api/public-tools.ts
@@ -12,7 +12,7 @@ import {
   checkoutAnimation,
   recordPublish,
   resolveDraftEdit,
-  stageReferenceHint,
+  stageReferenceText,
   writeStageReference,
 } from "./animation-drafts.js";
 import type { ReviewApiClient } from "./client.js";
@@ -131,7 +131,7 @@ export async function callPublicTool(
 
   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}`);

From 1eade2d7dacafe9a5642ddcd4425ac1fe324fd10 Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Sat, 31 Oct 2026 21:52:28 -0400
Subject: [PATCH 2/6] Tell animation authors about hand-made layouts and moving
 elements

The eight reference animations turned up where the guidance misled their
authors. The animation instructions now name the third way to draw, a
hand-made layout with arrows, tokens, travels and timelines declared while
the script first runs, and the lifecycle attributes that need no script;
they say how to move an element between frames, that every keyframe needs
its start value for a jump to land, and that whiteboard.frames follows the
active scenario. The API reference says where a string is a selector and
where it is a card id, and the class guide names the card's head and dot.

Agent-Session: b315a4f8-1333-461c-9be6-366ceb231b7f
---
 packages/review/instructions/animation.md    | 22 +++++++++++++++++---
 packages/review/instructions/whiteboard.d.ts | 17 ++++++++++-----
 packages/review/src/animation-stage-kit.ts   |  2 +-
 3 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/packages/review/instructions/animation.md b/packages/review/instructions/animation.md
index 54cd770621..391faf214f 100644
--- a/packages/review/instructions/animation.md
+++ b/packages/review/instructions/animation.md
@@ -15,7 +15,9 @@ For a new animation, write the same files into a folder of your own and publish
 
 Before you write HTML, read the two files whose paths `session_checkout` and these instructions give: `whiteboard.css`, the classes and `--wb-*` variables every animation loads, and `whiteboard.d.ts`, the `whiteboard` API. Use the classes and variables rather than your own colors, sizes or fonts, so the animation matches the board in light and dark.
 
-There are two ways to draw.
+Start from the reference closest to what you are drawing, listed under References at the end of these instructions: copy its folder into your draft, then change the data, the prose and the code links.
+
+There are three ways to draw.
 
 ### A scene: cards and messages
 
@@ -34,7 +36,17 @@ For a few services, processes or stores with messages moving between them, use `
 </script>
 ```
 
-A scene names frame keys, so a new scenario means new frames and a few new lines like these.
+A scene names frame keys, so a new scenario means new frames and a few new lines like these. A card's `id` is its element's id, so your own CSS can address it as `#api`.
+
+### A hand-made layout: lanes, axes, graphs
+
+When the drawing is not a grid of cards (attempts on a time axis, two lanes interleaving, a state graph), lay out your own elements with the kit (`wb-node`, `wb-lane`, `wb-table`) and connect them:
+
+- `whiteboard.arrow("#caller", "#service", { enter: "a1" })` draws an SVG arrow that follows the two elements. A string here is a CSS selector; in a scene's methods it is a card id.
+- `whiteboard.token({ label: "GET" })` and `whiteboard.travel(token, arrow, "a1")` ride a chip along the arrow during that frame.
+- `whiteboard.timeline("a1").add(".wait", { scaleX: [0, 1], duration: 600 })` adds tweens that play when the reader steps into the frame and land at their end on a jump.
+
+Declare arrows, tokens, travels and timelines while the script first runs, naming the frames they play in; they cannot be added from a frame handler. `data-enter="a1"`, `data-exit="a3"`, `data-only="a1 a3"` and `data-highlight="a1 a3"` on any element show, hide or ring it in those frames with no script.
 
 ### Your own HTML: draw each frame from its data
 
@@ -65,7 +77,11 @@ Draw the frame in full, then animate what is new since the previous frame:
 </script>
 ```
 
-Write each frame's data in full, not as a change from the one before: a reader can jump straight to any frame. `whiteboard.animate` skips the motion on a jump and under reduced motion, and returning its animations makes playback wait for them.
+Write each frame's data in full, not as a change from the one before: a reader can jump straight to any frame. `whiteboard.animate` skips the motion on a jump and under reduced motion, and returning its animations makes playback wait for them. Give every keyframe its start value (`[{ opacity: 0 }, { opacity: 1 }]`, not `[{ opacity: 1 }]`): a jump finishes the animation, and a missing start lands wrong.
+
+Something that moves between frames (a job changing queue slot, a record regrouped under a new parent) is drawn the same way: measure every element's position, redraw, then animate each moved element from its old position to `transform: none`. Measure everything before starting any animation; one that has started already reports its transform.
+
+`whiteboard.frames` and `frame.index` follow the active scenario, so a frame outside it is not listed. Key your drawing on `frame.data`, not on positions.
 
 ## Link the code
 
diff --git a/packages/review/instructions/whiteboard.d.ts b/packages/review/instructions/whiteboard.d.ts
index 13e6691e2c..1a2418b067 100644
--- a/packages/review/instructions/whiteboard.d.ts
+++ b/packages/review/instructions/whiteboard.d.ts
@@ -44,7 +44,8 @@ export type FrameResult =
   | Promise<void>;
 
 export interface Whiteboard {
-  /** The active path's frames, in order: a scenario's, or all of them. */
+  /** The active path's frames, in order: a scenario's, or all of them. A
+   * frame outside the active scenario is not listed. */
   readonly frames: readonly Frame[];
   /** The current frame object; read `.key` for its name. */
   readonly frame: Frame;
@@ -62,7 +63,9 @@ export interface Whiteboard {
    * another frame shows. Returns an unsubscribe function. */
   on(key: string, handler: (change: FrameChange) => FrameResult): () => void;
   /** element.animate that holds its end state, lands at the end on a jump, and
-   * skips motion under reduced motion. */
+   * skips motion under reduced motion. Give every keyframe its start value, and
+   * measure positions before starting one: a started animation already
+   * reports its transform. */
   animate(
     target: Element | string,
     keyframes: Keyframe[] | PropertyIndexedKeyframes,
@@ -70,7 +73,8 @@ export interface Whiteboard {
   ): Animation;
   /** The frame's part of one anime.js timeline: it plays when the reader steps
    * into the frame and lands at its end on a jump. A tween starts where the
-   * frames before it left the element, so write only where it goes. */
+   * frames before it left the element, so write only where it goes. Add to it
+   * while the script first runs, not from a frame handler. */
   timeline(key: string): FrameTimeline;
   /** anime.js v4, also the global `anime`: easings, stagger, utils. */
   readonly anime: unknown;
@@ -106,7 +110,8 @@ export interface Whiteboard {
   /** Move a token along an arrow during a frame, at the arrow's live geometry.
    * It fades out on arrival unless `stay` keeps it at the head. Trips append
    * to the frame; `position: 0` starts trips together, a number of
-   * milliseconds sequences one after another. */
+   * milliseconds sequences one after another. Declare trips while the script
+   * first runs, not from a frame handler. */
   travel(
     token: HTMLElement | string,
     arrow: SVGGElement,
@@ -140,7 +145,9 @@ export interface TravelOptions {
   stay?: boolean;
 }
 
-/** A scene card, its id, or an element. */
+/** A scene card, its id, or an element. In `whiteboard.arrow` and `travel`
+ * a string is a CSS selector (`"#api"`); in a scene's methods it is a card
+ * id. */
 export type CardRef = SceneCard | string | Element;
 
 /** 1-based column and row, with optional row and column spans: [1, 2, 1, 4] is
diff --git a/packages/review/src/animation-stage-kit.ts b/packages/review/src/animation-stage-kit.ts
index 7d1decb52d..3345113242 100644
--- a/packages/review/src/animation-stage-kit.ts
+++ b/packages/review/src/animation-stage-kit.ts
@@ -149,7 +149,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",

From ef430f72ceda4aa48b3cf36175c2470eee5b68d8 Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Sat, 31 Oct 2026 22:08:47 -0400
Subject: [PATCH 3/6] Walk an animation's code as a tour that steps with its
 frames

An animation whose frames list code now has a tour: one stop per frame of
the path showing, a frame's code as the stop's source and its caption as
an explanation stop otherwise. The header's Expand becomes the diagrams'
Tour control, which opens the fullscreen tour overlay with the figure as
the stage and the guided tour panel beside it; an animation with no code
keeps its plain Expand. The panel and the frames move together both ways:
a stop picked in the panel shows its frame, and a frame reached by the
controls, playback, the stage or a scenario switch moves the panel, which
stays open on a scenario switch at the frame showing. Inline, a drawn
element's code opens in the column with the tour at the frame showing,
and while the column shows this tour it follows the frames and its own
steps move them.

Agent-Session: b315a4f8-1333-461c-9be6-366ceb231b7f
---
 .../app/src/animation/animation-block.tsx     | 305 +++++++++++++++---
 .../app/src/animation/animation-tour.test.ts  | 107 ++++++
 .../app/src/animation/animation-tour.ts       |  83 +++++
 .../review/app/src/blocks.browser.test.tsx    | 210 ++++++++++++
 packages/review/app/src/review-panel-store.ts |   2 +-
 packages/review/app/src/review-view-state.ts  |   5 +-
 6 files changed, 671 insertions(+), 41 deletions(-)
 create mode 100644 packages/review/app/src/animation/animation-tour.test.ts
 create mode 100644 packages/review/app/src/animation/animation-tour.ts

diff --git a/packages/review/app/src/animation/animation-block.tsx b/packages/review/app/src/animation/animation-block.tsx
index d7596a2ba1..ed40d5176c 100644
--- a/packages/review/app/src/animation/animation-block.tsx
+++ b/packages/review/app/src/animation/animation-block.tsx
@@ -3,9 +3,11 @@ import { CodePeekCard } from "@canvas/CodePeek";
 import { useReviewDebugSettings } from "@canvas/debug-settings";
 import { DiagramHeader } from "@canvas/diagram-header";
 import { diagramStyles } from "@canvas/diagram-styles";
-import { useDiagramTourShell } from "@canvas/diagram-tour";
+import { DiagramTourOverlay, useDiagramTourShell } from "@canvas/diagram-tour";
 import { drawStyles } from "@canvas/draw-styles";
-import { useOptionalReviewPanel } from "@canvas/review-panel";
+import { countLabel } from "@canvas/format";
+import { useReviewSession } from "@canvas/host/review-session";
+import { useReviewPanel, useReviewPanelStore } from "@canvas/review-panel";
 import type { SourcePeekAnchor } from "@canvas/review-panel-model";
 import {
   fontSize,
@@ -18,10 +20,13 @@ import { shellStyles } from "@canvas/shell-styles";
 import { withClass } from "@canvas/stylex-props";
 import { themeClass, themeStyles } from "@canvas/theme-styles";
 import { tokens } from "@canvas/tokens.stylex";
+import { captureUiEvent } from "@canvas/ui-telemetry";
 import { Button, IconButton } from "@canvas/ui/button";
 import { SegmentedControl } from "@canvas/ui/segmented";
 import { textStyles } from "@canvas/ui/text";
 import { useTooltip } from "@canvas/ui/tooltip";
+import { useDiagramSelection } from "@canvas/use-diagram-selection";
+import { useWhiteboardSettings } from "@canvas/whiteboard-settings";
 import {
   type Block,
   anchorSelection,
@@ -33,8 +38,10 @@ import * as stylex from "@stylexjs/stylex";
 import {
   type KeyboardEvent,
   type ReactNode,
+  type RefObject,
   useCallback,
   useEffect,
+  useEffectEvent,
   useLayoutEffect,
   useMemo,
   useRef,
@@ -42,6 +49,7 @@ import {
 } from "react";
 import { createPortal } from "react-dom";
 
+import { animationTour, frameAnchorId, frameContent } from "./animation-tour";
 import { useReportAnimationRun } from "./report-run";
 import {
   type HostMessage,
@@ -142,8 +150,9 @@ export function AnimationBlock({
   children,
 }: BlockProps<"animation">) {
   const { theme } = useReviewDebugSettings();
-  const openPeek = useOptionalReviewPanel((state) => state.openPeek);
-  const figureRef = useRef<HTMLElement>(null);
+  const panelStore = useReviewPanelStore();
+  const session = useReviewSession();
+  const { diagramFullscreenOnClick } = useWhiteboardSettings();
   const frameRef = useRef<HTMLIFrameElement>(null);
   const portRef = useRef<MessagePort | null>(null);
   const [index, setIndex] = useState(0);
@@ -157,10 +166,11 @@ export function AnimationBlock({
 
   const reportRun = useReportAnimationRun(data.snapshot.reviewId, node.id);
 
-  // The inline figure's height while it is out fullscreen, held by a
-  // placeholder so the document keeps its place.
-  const [expanded, setExpanded] = useState<number | null>(null);
-  const expandRef = useRef<HTMLButtonElement>(null);
+  // Fullscreen without a tour. Either way, a placeholder holds the inline
+  // figure's height so the document keeps its place.
+  const [expanded, setExpanded] = useState(false);
+  const [held, setHeld] = useState(0);
+  const openRef = useRef<HTMLButtonElement>(null);
   const closeRef = useRef<HTMLButtonElement>(null);
   const indexRef = useRef(index);
   indexRef.current = index;
@@ -193,6 +203,33 @@ export function AnimationBlock({
 
   const steps = activeFrames.every((item) => item.label) ? activeFrames : null;
 
+  // A stop per frame of the path showing, when its frames show code.
+  const tour = useMemo(
+    () =>
+      animationTour(
+        { id: node.id, title: node.title },
+        data.anchors,
+        activeFrames,
+      ),
+    [node.id, node.title, data.anchors, activeFrames],
+  );
+
+  const frameAnchor = tour && frameAnchorId(node.id, frame.key);
+
+  // Unlike a diagram's, the tour stays open on a stop it no longer has: a
+  // scenario switch moves it to the frame showing instead.
+  const overlay = useReviewPanel((state) =>
+    tour && state.overlayTour?.tourId === node.id ? state.overlayTour : null,
+  );
+
+  const tourOpen = overlay !== null;
+
+  // Set while the column shows this tour.
+  const { anchor: inlineAnchor, figureRef } = useDiagramSelection(
+    tour,
+    tourOpen || expanded,
+  );
+
   // A new stage for each edit of what it runs; frame changes reuse it.
   const stageKey = useMemo(
     () =>
@@ -245,19 +282,53 @@ export function AnimationBlock({
     [frames, send],
   );
 
-  const reveal = useCallback(
-    (name: string) => {
-      const anchor = data.anchors.get(animationCodeId(node.id, name));
+  const openTour = () => {
+    if (!tour || !frameAnchor) return;
+
+    if (!tourOpen) {
+      captureUiEvent(session, "tour_started", { steps: tour.stops.length });
 
-      if (!anchor || !openPeek) return;
-      openPeek({
+      if (!expanded) setHeld(figureRef.current?.offsetHeight ?? 0);
+    }
+
+    setExpanded(false);
+    panelStore
+      .getState()
+      .openOverlayTour({ tourId: node.id, kind: "animation" }, frameAnchor);
+  };
+
+  // A drawn element's code opens beside the board with the tour, at the
+  // frame showing, or with the tour fullscreen.
+  const reveal = (name: string) => {
+    const anchor = data.anchors.get(animationCodeId(node.id, name));
+
+    if (!anchor) return;
+    captureUiEvent(session, "peek_opened", { via: "diagram" });
+    const { openPeek, moveOverlayTour, active } = panelStore.getState();
+
+    const stop = tour?.stops.find((item) => item.anchor.id === frameAnchor);
+
+    if (!tour || !stop)
+      return openPeek({
         kind: "peek",
         anchor,
         content: { kind: "source", source: anchor.peek },
       });
-    },
-    [data.anchors, node.id, openPeek],
-  );
+
+    if (tourOpen) return moveOverlayTour(stop.anchor.id, { reveal: true });
+
+    if (expanded || diagramFullscreenOnClick) return openTour();
+
+    openPeek({
+      kind: "peek",
+      anchor: stop.anchor,
+      content: frameContent(node.id, data.anchors, frame, name),
+      tour: {
+        definition: tour,
+        revealRequest: (active?.tour?.revealRequest ?? 0) + 1,
+      },
+    });
+  };
 
   // A stage script's setSequence() and the scenario picker both land here.
   const selectSequence = (keys: string[]) => {
@@ -466,21 +537,108 @@ export function AnimationBlock({
     if (!activeFrames.some((item) => item.key === frame.key)) go(0, true);
   }, [activeFrames, frame.key, go]);
 
-  const collapse = useCallback(() => setExpanded(null), []);
+  const { closeOverlayTour, moveOverlayTour } = panelStore.getState();
+  const collapse = useCallback(() => setExpanded(false), []);
+  const close = tourOpen ? closeOverlayTour : collapse;
+
+  const { portalTarget } = useDiagramTourShell(tourOpen || expanded, close);
 
-  const { portalTarget } = useDiagramTourShell(expanded !== null, collapse);
+  const fullscreen = (tourOpen || expanded) && portalTarget !== null;
 
   // Focus follows the figure in and back out to the control that opened it.
-  const wasExpanded = useRef(false);
+  const wasFullscreen = useRef(false);
+
+  useEffect(() => {
+    if (fullscreen) closeRef.current?.focus();
+    else if (wasFullscreen.current) openRef.current?.focus();
+
+    wasFullscreen.current = fullscreen;
+  }, [fullscreen]);
+
+  // The tour's panel picked a stop (its Next, a click, its scroll): show
+  // that frame, moving to it when it is the next one. A stop the tour no
+  // longer has, after a scenario switch, gives way to the frame showing.
+  const followPanel = useEffectEvent(() => {
+    const anchor = panelStore.getState().overlayTour?.anchor;
+
+    if (!tour || !frameAnchor || !anchor) return;
+    const position = tour.stops.findIndex((stop) => stop.anchor.id === anchor);
+
+    if (position < 0) moveOverlayTour(frameAnchor, { reveal: true });
+    else if (position !== activeIndex)
+      go(position, Math.abs(position - activeIndex) > 1);
+  });
+
+  const overlayAnchor = overlay?.anchor;
+
+  useEffect(() => {
+    if (overlayAnchor) followPanel();
+  }, [overlayAnchor, tour]);
+
+  // The column's tour picked a stop (its Next, a click, its scroll): show
+  // that frame, as the overlay's panel does.
+  const followColumn = useEffectEvent(() => {
+    if (!tour || fullscreen || !inlineAnchor) return;
+
+    const position = tour.stops.findIndex(
+      (stop) => stop.anchor.id === inlineAnchor,
+    );
+
+    if (position >= 0 && position !== activeIndex)
+      go(position, Math.abs(position - activeIndex) > 1);
+  });
 
   useEffect(() => {
-    if (expanded !== null) closeRef.current?.focus();
-    else if (wasExpanded.current) expandRef.current?.focus();
+    if (inlineAnchor) followColumn();
+  }, [inlineAnchor, tour]);
+
+  // The frame changed some other way (the controls, playback, the stage, a
+  // scenario): the open tour follows it, fullscreen or in the column. Each
+  // side writes only what differs, so neither echoes the other.
+  const followFrame = useEffectEvent(() => {
+    const { overlayTour, active, openPeek } = panelStore.getState();
+
+    if (!tour || !frameAnchor) return;
 
-    wasExpanded.current = expanded !== null;
-  }, [expanded]);
+    if (overlayTour?.tourId === node.id) {
+      if (overlayTour.anchor !== frameAnchor)
+        moveOverlayTour(frameAnchor, { reveal: true });
 
-  const fullscreen = expanded !== null && portalTarget !== null;
+      return;
+    }
+
+    const stop = tour.stops.find((item) => item.anchor.id === frameAnchor);
+
+    if (
+      !inlineAnchor ||
+      fullscreen ||
+      !stop ||
+      (active?.anchor?.id === frameAnchor && active.tour?.definition === tour)
+    )
+      return;
+    openPeek({
+      kind: "peek",
+      anchor: stop.anchor,
+      content: stop.content,
+      tour: {
+        definition: tour,
+        revealRequest: (active?.tour?.revealRequest ?? 0) + 1,
+      },
+    });
+  });
+
+  // Not on mount: a restored tour's stop leads the frame there.
+  const followed = useRef({ frameAnchor, tour });
+
+  useEffect(() => {
+    if (
+      followed.current.frameAnchor === frameAnchor &&
+      followed.current.tour === tour
+    )
+      return;
+    followed.current = { frameAnchor, tour };
+    followFrame();
+  }, [frameAnchor, tour]);
 
   const onKeyDown = (event: KeyboardEvent) => {
     if (event.key === "ArrowRight") go(activeIndex + 1, false);
@@ -507,20 +665,34 @@ export function AnimationBlock({
         titleStyle={styles.headerTitle}
         meta={`${activeIndex + 1} / ${activeFrames.length}`}
         action={
-          <Button
-            ref={fullscreen ? closeRef : expandRef}
-            xstyle={diagramStyles.button}
-            aria-label={
-              fullscreen ? "Close expanded animation" : "Expand animation"
-            }
-            onClick={() =>
-              fullscreen
-                ? collapse()
-                : setExpanded(figureRef.current?.offsetHeight ?? 0)
-            }
-          >
-            {fullscreen ? "Close" : "Expand"}
-          </Button>
+          fullscreen ? (
+            <Button
+              ref={closeRef}
+              xstyle={diagramStyles.button}
+              aria-label={tourOpen ? "Close tour" : "Close expanded animation"}
+              onClick={close}
+            >
+              Close
+            </Button>
+          ) : tour ? (
+            <TourButton
+              buttonRef={openRef}
+              stops={tour.stops.length}
+              onClick={openTour}
+            />
+          ) : (
+            <Button
+              ref={openRef}
+              xstyle={diagramStyles.button}
+              aria-label="Expand animation"
+              onClick={() => {
+                setHeld(figureRef.current?.offsetHeight ?? 0);
+                setExpanded(true);
+              }}
+            >
+              Expand
+            </Button>
+          )
         }
       />
       {node.scenarios && (
@@ -684,11 +856,32 @@ export function AnimationBlock({
 
   if (!fullscreen) return figure;
 
+  const placeholder = <div aria-hidden="true" style={{ height: held }} />;
+
+  if (tour && overlay)
+    return (
+      <>
+        {placeholder}
+        {createPortal(
+          <DiagramTourOverlay
+            tour={tour}
+            activeAnchor={overlay.anchor}
+            revealRequest={overlay.revealRequest}
+            onActiveAnchorChange={moveOverlayTour}
+            onClose={closeOverlayTour}
+          >
+            {figure}
+          </DiagramTourOverlay>,
+          portalTarget,
+        )}
+      </>
+    );
+
   // Portaled outside .review-app, so it carries the theme itself, as the
   // diagram tour overlay does.
   return (
     <>
-      <div aria-hidden="true" style={{ height: expanded }} />
+      {placeholder}
       {createPortal(
         <div
           {...withClass(
@@ -758,6 +951,40 @@ function SlotOverlay({
   );
 }
 
+/** Opens the tour; its tooltip counts the stops. */
+function TourButton({
+  buttonRef,
+  stops,
+  onClick,
+}: {
+  buttonRef: RefObject<HTMLButtonElement | null>;
+  stops: number;
+  onClick(): void;
+}) {
+  const tooltip = useTooltip(countLabel(stops, "stop"), { quick: true });
+
+  const ref = useCallback(
+    (button: HTMLButtonElement | null) => {
+      buttonRef.current = button;
+
+      return tooltip(button);
+    },
+    [buttonRef, tooltip],
+  );
+
+  return (
+    <Button
+      ref={ref}
+      className="diagram-tour-button"
+      xstyle={diagramStyles.button}
+      data-tour-target="diagram-tour"
+      onClick={onClick}
+    >
+      Tour
+    </Button>
+  );
+}
+
 function ControlButton({
   label,
   disabled,
diff --git a/packages/review/app/src/animation/animation-tour.test.ts b/packages/review/app/src/animation/animation-tour.test.ts
new file mode 100644
index 0000000000..15dcc65df9
--- /dev/null
+++ b/packages/review/app/src/animation/animation-tour.test.ts
@@ -0,0 +1,107 @@
+import type { SourcePeekAnchor } from "@canvas/review-panel-model";
+import {
+  type DiffSelection,
+  animationCodeId,
+} from "@dev.fast/whiteboard-document";
+import { describe, expect, it } from "vitest";
+
+import {
+  type AnimationFrame,
+  animationTour,
+  frameContent,
+} from "./animation-tour";
+
+const block = { id: "anim", title: "Order flow" };
+
+const selection = (line: number): DiffSelection => ({
+  file: "order.ts",
+  start: { side: "head", line },
+  end: { side: "head", line },
+});
+
+const anchors = new Map<string, SourcePeekAnchor>(
+  (["save", "send"] as const).map((name, index) => [
+    animationCodeId(block.id, name),
+    {
+      id: animationCodeId(block.id, name),
+      title: name,
+      peek: selection(index + 1),
+    },
+  ]),
+);
+
+const frames: AnimationFrame[] = [
+  { key: "a", title: "Arrives" },
+  { key: "b", title: "Saved", caption: "The row is written.", code: ["save"] },
+  { key: "c", title: "Sent", code: ["missing", "send", "save"] },
+];
+
+describe("animationTour", () => {
+  it("has a stop per frame of the path, in order", () => {
+    const tour = animationTour(block, anchors, [frames[2]!, frames[0]!]);
+
+    expect(tour?.id).toBe("anim");
+    expect(tour?.title).toBe("Order flow");
+    expect(tour?.stops.map((stop) => stop.anchor.id)).toEqual([
+      "anim:frame:c",
+      "anim:frame:a",
+    ]);
+  });
+
+  it("shows a frame's resolving code, the rest after the first", () => {
+    const [arrives, saved, sent] = animationTour(block, anchors, frames)!.stops;
+
+    expect(arrives).toEqual({
+      anchor: { id: "anim:frame:a", title: "Arrives" },
+      label: "Arrives",
+      content: { kind: "explanation", text: "Arrives" },
+    });
+    expect(saved).toEqual({
+      anchor: {
+        id: "anim:frame:b",
+        title: "Saved",
+        detail: "The row is written.",
+        peek: selection(1),
+      },
+      label: "Saved",
+      detail: "The row is written.",
+      content: { kind: "source", source: selection(1) },
+    });
+    expect(sent?.anchor.peek).toEqual(selection(2));
+    expect(sent?.content).toEqual({
+      kind: "source",
+      source: selection(2),
+      more: [selection(1)],
+    });
+  });
+
+  it("explains a frame by its caption when its code does not resolve", () => {
+    const tour = animationTour(block, anchors, [
+      { key: "x", title: "Waits", caption: "Nothing yet.", code: ["missing"] },
+      frames[1]!,
+    ]);
+
+    expect(tour?.stops[0]?.content).toEqual({
+      kind: "explanation",
+      text: "Nothing yet.",
+    });
+    expect(tour?.stops[0]?.anchor.peek).toBeUndefined();
+  });
+
+  it("is absent when no frame of the path shows code that resolves", () => {
+    expect(animationTour(block, anchors, [frames[0]!])).toBeNull();
+    expect(
+      animationTour(block, new Map(), [frames[1]!, frames[2]!]),
+    ).toBeNull();
+  });
+});
+
+describe("frameContent", () => {
+  it("leads with the named code", () => {
+    expect(frameContent(block.id, anchors, frames[2]!, "save")).toEqual({
+      kind: "source",
+      source: selection(1),
+      more: [selection(2)],
+    });
+  });
+});
diff --git a/packages/review/app/src/animation/animation-tour.ts b/packages/review/app/src/animation/animation-tour.ts
new file mode 100644
index 0000000000..bb392df33f
--- /dev/null
+++ b/packages/review/app/src/animation/animation-tour.ts
@@ -0,0 +1,83 @@
+import type {
+  GuidedTour,
+  GuidedTourStop,
+  ReviewPeekContent,
+  SourcePeekAnchor,
+} from "@canvas/review-panel-model";
+import { type Block, animationCodeId } from "@dev.fast/whiteboard-document";
+
+export type AnimationFrame = Extract<
+  Block,
+  { type: "animation" }
+>["frames"][number];
+
+type Anchors = ReadonlyMap<string, SourcePeekAnchor>;
+
+/** The tour stop, and panel anchor, a frame stands for. */
+export const frameAnchorId = (blockId: string, frameKey: string) =>
+  `${blockId}:frame:${frameKey}`;
+
+/** The code a frame lists that resolves, `lead` first when it resolves. */
+function frameSources(
+  blockId: string,
+  anchors: Anchors,
+  frame: AnimationFrame,
+  lead?: string,
+) {
+  const names = lead
+    ? [lead, ...(frame.code ?? []).filter((name) => name !== lead)]
+    : (frame.code ?? []);
+
+  return names.flatMap((name) => {
+    const anchor = anchors.get(animationCodeId(blockId, name));
+
+    return anchor ? [anchor.peek] : [];
+  });
+}
+
+/** What a frame's stop shows: its code, `lead` first, or its words. */
+export function frameContent(
+  blockId: string,
+  anchors: Anchors,
+  frame: AnimationFrame,
+  lead?: string,
+): ReviewPeekContent {
+  const [source, ...more] = frameSources(blockId, anchors, frame, lead);
+
+  return source
+    ? { kind: "source", source, ...(more.length > 0 && { more }) }
+    : { kind: "explanation", text: frame.caption ?? frame.title };
+}
+
+/**
+ * An animation's tour: a stop per frame of the path being shown, in order.
+ * There is none unless some frame of the path shows code that resolves.
+ */
+export function animationTour(
+  block: { id: string; title?: string },
+  anchors: Anchors,
+  path: readonly AnimationFrame[],
+): GuidedTour | null {
+  if (!path.some((frame) => frameSources(block.id, anchors, frame).length))
+    return null;
+
+  return {
+    id: block.id,
+    title: block.title,
+    stops: path.map((frame): GuidedTourStop => {
+      const content = frameContent(block.id, anchors, frame);
+
+      return {
+        anchor: {
+          id: frameAnchorId(block.id, frame.key),
+          title: frame.title,
+          ...(frame.caption && { detail: frame.caption }),
+          ...(content.kind === "source" && { peek: content.source }),
+        },
+        label: frame.title,
+        ...(frame.caption && { detail: frame.caption }),
+        content,
+      };
+    }),
+  };
+}
diff --git a/packages/review/app/src/blocks.browser.test.tsx b/packages/review/app/src/blocks.browser.test.tsx
index 822c2d7919..a11fc10f59 100644
--- a/packages/review/app/src/blocks.browser.test.tsx
+++ b/packages/review/app/src/blocks.browser.test.tsx
@@ -18,6 +18,7 @@ import { defineSoftwareMap } from "@review/software-map-model";
 import { type ReactNode, act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { page } from "vitest/browser";
 
 import { STAGE_MAX_HEIGHT, STAGE_MAX_SLOTS } from "./animation/stage-protocol";
 import type { SavedMap } from "./api-document";
@@ -1956,3 +1957,212 @@ it("grows a tall, wide sequence diagram to its height instead of scrolling it ve
   expect(body!.clientHeight).toBeGreaterThan(700);
   expect(body!.scrollHeight).toBe(body!.clientHeight);
 });
+
+describe("animation tour", () => {
+  // Frames that show code make a tour, a stop per frame.
+  const tourAnimation = (scenarios = false) =>
+    documentSchema.parse([
+      {
+        id: "block-1",
+        type: "animation",
+        title: "Order tour",
+        height: 160,
+        frames: [
+          { key: "a", title: "Arrives", caption: "An order comes in." },
+          {
+            key: "b",
+            title: "Saved",
+            caption: "The row is written.",
+            code: ["status"],
+          },
+          {
+            key: "c",
+            title: "Sent",
+            caption: "The queue takes it.",
+            code: ["status"],
+          },
+        ],
+        ...(scenarios && {
+          scenarios: [
+            { key: "all", label: "Everything", frames: ["a", "b", "c"] },
+            { key: "short", label: "Shortcut", frames: ["a", "c"] },
+          ],
+        }),
+        code: { status: "head/order.ts#L1" },
+        html: '<button data-wb-open="status">Open status</button>',
+        pins: { repositoryId: "repo", base: "base", head: "head" },
+      },
+    ]);
+
+  const overlay = () => document.querySelector(".diagram-tour-overlay");
+
+  const caption = () =>
+    document.querySelector(".animation-block [aria-live='polite']")
+      ?.textContent ?? "";
+
+  const meta = () =>
+    document.querySelector(".animation-block figcaption em")?.textContent;
+
+  const pill = () => document.querySelector(".tour-pill-count")?.textContent;
+
+  const press = (label: string) =>
+    act(async () =>
+      document
+        .querySelector<HTMLButtonElement>(
+          `.animation-block button[aria-label='${label}']`,
+        )!
+        .click(),
+    );
+
+  it("tours its frames fullscreen, the panel and the animation in step", async () => {
+    await mountFixture("animation", { document: tourAnimation(true) });
+
+    const tour = await settled(() =>
+      document.querySelector<HTMLButtonElement>(".diagram-tour-button"),
+    );
+
+    expect(tour?.textContent).toBe("Tour");
+    expect(
+      document.querySelector("button[aria-label='Expand animation']"),
+    ).toBeNull();
+    await act(async () => tour!.click());
+    expect(await settled(overlay)).toBeTruthy();
+    expect(
+      await settled(
+        () =>
+          overlay()!.querySelectorAll("section[data-review-anchor-id]")
+            .length === 3,
+      ),
+    ).toBe(true);
+
+    // The panel's Next shows the next frame.
+    await act(async () =>
+      overlay()!
+        .querySelector<HTMLButtonElement>("[data-tour-target='tour-next']")!
+        .click(),
+    );
+    expect(await settled(() => caption().includes("The row is written."))).toBe(
+      true,
+    );
+    expect(meta()).toBe("2 / 3");
+    expect(pill()).toBe("2/3");
+
+    // The animation's own Next moves the panel's stop.
+    await press("Next frame");
+    expect(await settled(() => pill() === "3/3")).toBe(true);
+    expect(meta()).toBe("3 / 3");
+
+    // A scenario keeping the frame keeps the tour open there.
+    await act(async () =>
+      [
+        ...document.querySelectorAll<HTMLButtonElement>(
+          ".diagram-tour-overlay [aria-label='Scenario'] button",
+        ),
+      ]
+        .find((button) => button.textContent === "Shortcut")!
+        .click(),
+    );
+    expect(await settled(() => pill() === "2/2")).toBe(true);
+    expect(overlay()).toBeTruthy();
+    expect(meta()).toBe("2 / 2");
+    expect(caption()).toContain("The queue takes it.");
+
+    await act(async () =>
+      window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })),
+    );
+    expect(await settled(() => overlay() === null)).toBe(true);
+    expect(
+      await settled(() =>
+        document.activeElement?.classList.contains("diagram-tour-button"),
+      ),
+    ).toBe(true);
+  });
+
+  it("expands an animation without code plainly", async () => {
+    await mountFixture("animation", {
+      document: documentSchema.parse([
+        {
+          id: "block-1",
+          type: "animation",
+          title: "No code",
+          height: 160,
+          frames: [
+            { key: "a", title: "One" },
+            { key: "b", title: "Two" },
+          ],
+          code: { status: "head/order.ts#L1" },
+          html: "<p>Stage</p>",
+          pins: { repositoryId: "repo", base: "base", head: "head" },
+        },
+      ]),
+    });
+
+    const expand = await settled(() =>
+      document.querySelector<HTMLButtonElement>(
+        "button[aria-label='Expand animation']",
+      ),
+    );
+
+    expect(document.querySelector(".diagram-tour-button")).toBeNull();
+    await act(async () => expand!.click());
+    expect(
+      await settled(() =>
+        document.querySelector("[role='dialog'][aria-modal='true']"),
+      ),
+    ).toBeTruthy();
+    expect(overlay()).toBeNull();
+  });
+
+  it("opens its code in the column with the tour, which follows the frames", async () => {
+    const { container } = await mountFixture("animation", {
+      document: tourAnimation(),
+    });
+
+    const stage = await settled(() =>
+      document.querySelector<HTMLIFrameElement>(".animation-block iframe"),
+    );
+
+    await press("Next frame");
+    expect(await settled(() => meta() === "2 / 3")).toBe(true);
+
+    await act(() =>
+      page
+        .frameLocator(page.elementLocator(stage!))
+        .getByRole("button", { name: "Open status" })
+        .click(),
+    );
+
+    const sections = () =>
+      container.querySelectorAll("aside section[data-review-anchor-id]");
+
+    expect(await settled(() => sections().length === 3)).toBe(true);
+    expect(pill()).toBe("2/3");
+    expect(overlay()).toBeNull();
+
+    await press("Next frame");
+    expect(await settled(() => pill() === "3/3")).toBe(true);
+
+    // The column's own steps move the animation too.
+    await act(async () =>
+      container
+        .querySelector<HTMLButtonElement>("button[aria-label='Previous step']")!
+        .click(),
+    );
+    expect(await settled(() => meta() === "2 / 3")).toBe(true);
+    expect(pill()).toBe("2/3");
+
+    // Put away, the column stays closed as the frames change.
+    await act(async () =>
+      container
+        .querySelector<HTMLButtonElement>(
+          "button[aria-label='Close guided tour']",
+        )!
+        .click(),
+    );
+    expect(await settled(() => sections().length === 0)).toBe(true);
+    await press("Next frame");
+    expect(await settled(() => meta() === "3 / 3")).toBe(true);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(sections()).toHaveLength(0);
+  });
+});
diff --git a/packages/review/app/src/review-panel-store.ts b/packages/review/app/src/review-panel-store.ts
index 3c1b06663d..350b92dbf9 100644
--- a/packages/review/app/src/review-panel-store.ts
+++ b/packages/review/app/src/review-panel-store.ts
@@ -74,7 +74,7 @@ export interface MapFocus {
   pending: boolean;
 }
 
-export type OverlayTourKind = "sequence" | "database" | "flow";
+export type OverlayTourKind = "sequence" | "database" | "flow" | "animation";
 
 /** A fullscreen diagram tour. `kind` is absent on one restored from an
  * older build's in-panel record. */
diff --git a/packages/review/app/src/review-view-state.ts b/packages/review/app/src/review-view-state.ts
index ae437b7fed..9122e20a06 100644
--- a/packages/review/app/src/review-view-state.ts
+++ b/packages/review/app/src/review-view-state.ts
@@ -522,7 +522,10 @@ function parsePersistedTourState(
 
   if (tourId === undefined || activeAnchor === undefined) return undefined;
 
-  return kind === "sequence" || kind === "database" || kind === "flow"
+  return kind === "sequence" ||
+    kind === "database" ||
+    kind === "flow" ||
+    kind === "animation"
     ? { tourId, activeAnchor, kind }
     : { tourId, activeAnchor };
 }

From f88f87811f1c2c4f67fe928bc6be906aba37e824 Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Sun, 1 Nov 2026 11:38:26 -0500
Subject: [PATCH 4/6] Paint a new animation in when it lands on the board

An animation the agent writes used to pop onto the board behind the generic
landing wipe. Now the block arrives from the stream with its stage built but
unseen; when the draw queue reaches it the host says "paint", the stage
brings the first frame in part by part, and the queue holds on the block
until the stage reports it painted, or until a cap.

- Draw queue: a "painting" phase for animation inserts, ended early by
  painted(), with the slot ring but no content wipe on the figure.
- Stage protocol: StageInit.paint, a "paint" host message, a "painted"
  stage message, and a long fallback so a stage never stays blank.
- Default painter for the kit's parts in document order within about a
  second and a half: boxes settle in, arrows draw along their path.
- data-wb-paint orders a part or excludes it; data-wb-paint-style picks
  fade, draw, wipe or none.
- whiteboard.on("paint") and whiteboard.timeline("paint") replace the
  default painter; the hook also runs instantly on a cold load.

Cold loads, history and reduced motion do not paint.

Agent-Session: b315a4f8-1333-461c-9be6-366ceb231b7f
---
 .../app/src/animation/animation-block.tsx     |  85 +++-
 .../animation-paint.browser.test.tsx          | 323 +++++++++++++
 .../app/src/animation/stage-protocol.ts       |  10 +-
 .../app/src/animation/stage-reference.ts      |   2 +
 .../review/app/src/animation/stage-runtime.ts | 437 +++++++++++++++++-
 packages/review/app/src/api-document.tsx      |   3 +-
 .../review/app/src/draw-queue-provider.tsx    |  33 +-
 packages/review/app/src/draw-queue.test.ts    |  48 ++
 packages/review/app/src/draw-queue.ts         |  31 +-
 packages/review/app/src/draw-styles.ts        |   3 +-
 packages/review/instructions/animation.md     |   8 +
 packages/review/instructions/whiteboard.d.ts  |  20 +-
 packages/review/src/animation-stage-kit.ts    |   5 +
 13 files changed, 993 insertions(+), 15 deletions(-)
 create mode 100644 packages/review/app/src/animation/animation-paint.browser.test.tsx

diff --git a/packages/review/app/src/animation/animation-block.tsx b/packages/review/app/src/animation/animation-block.tsx
index ed40d5176c..dac45005a2 100644
--- a/packages/review/app/src/animation/animation-block.tsx
+++ b/packages/review/app/src/animation/animation-block.tsx
@@ -4,6 +4,10 @@ import { useReviewDebugSettings } from "@canvas/debug-settings";
 import { DiagramHeader } from "@canvas/diagram-header";
 import { diagramStyles } from "@canvas/diagram-styles";
 import { DiagramTourOverlay, useDiagramTourShell } from "@canvas/diagram-tour";
+import {
+  useDrawQueueControls,
+  useMotionPhase,
+} from "@canvas/draw-queue-provider";
 import { drawStyles } from "@canvas/draw-styles";
 import { countLabel } from "@canvas/format";
 import { useReviewSession } from "@canvas/host/review-session";
@@ -166,6 +170,27 @@ export function AnimationBlock({
 
   const reportRun = useReportAnimationRun(data.snapshot.reviewId, node.id);
 
+  // A block from the agent's stream paints its first frame in when the board
+  // gets to it, and holds the draw queue until its stage says it is done.
+  const motion = useMotionPhase(node.id);
+  const motionRef = useRef(motion);
+  motionRef.current = motion;
+  const { painted } = useDrawQueueControls();
+
+  // The stage showing now: whether it boots unseen, has run its scripts, was
+  // told to paint, and reported an error.
+  const paintRef = useRef({
+    wanted: false,
+    ready: false,
+    sent: false,
+    failed: false,
+  });
+
+  // A no-op unless the queue is painting this block.
+  const endPaint = useCallback(() => {
+    if (node.id) painted(node.id);
+  }, [node.id, painted]);
+
   // Fullscreen without a tour. Either way, a placeholder holds the inline
   // figure's height so the document keeps its place.
   const [expanded, setExpanded] = useState(false);
@@ -247,6 +272,26 @@ export function AnimationBlock({
     portRef.current?.postMessage(message);
   }, []);
 
+  // Paint once the stage is ready and the queue has reached this block, or
+  // has given up on it: the content must appear either way.
+  const paintStage = () => {
+    const stage = paintRef.current;
+    const phase = motionRef.current;
+
+    if (phase === "painting" && stage.failed) endPaint();
+
+    if (!stage.wanted || !stage.ready || stage.sent || phase === "queued")
+      return;
+    stage.sent = true;
+    send({ type: "paint" });
+  };
+
+  const onPhase = useEffectEvent(paintStage);
+
+  useEffect(() => onPhase(), [motion]);
+
+  useEffect(() => endPaint, [endPaint]);
+
   const go = useCallback(
     (target: number, instant: boolean) => {
       const keys = sequenceRef.current;
@@ -408,9 +453,17 @@ export function AnimationBlock({
       case "error":
         setError(message.message);
         reportRun(message.message);
+        // A broken stage must not hold the queue.
+        paintRef.current.failed = true;
+        endPaint();
         break;
       case "ready":
         reportRun(null);
+        paintRef.current.ready = true;
+        paintStage();
+        break;
+      case "painted":
+        endPaint();
         break;
     }
   };
@@ -431,6 +484,7 @@ export function AnimationBlock({
       portRef.current = null;
       setSlots([]);
       setError("The animation left its stage.");
+      endPaint();
 
       return;
     }
@@ -462,6 +516,21 @@ export function AnimationBlock({
 
     setSlots([]);
     setError(null);
+
+    // Unseen until painted only while the queue is drawing (or about to draw)
+    // this block. A stage replaced mid-paint starts over.
+    const paint =
+      (motionRef.current === "painting" || motionRef.current === "queued") &&
+      !reducedMotion();
+
+    paintRef.current = {
+      wanted: paint,
+      ready: false,
+      sent: false,
+      failed: false,
+    };
+
+    if (!paint) endPaint();
     target.postMessage(
       { type: STAGE_BOOT, runtime: stageRuntime.toString() },
       "*",
@@ -486,6 +555,7 @@ export function AnimationBlock({
       ...readTheme(figure),
       scale: SCALE,
       reducedMotion: reducedMotion(),
+      paint,
       frame: indexRef.current,
       ...(sequence && { sequence }),
     };
@@ -497,9 +567,20 @@ export function AnimationBlock({
           libraries: [anime],
           fonts,
         } satisfies HostMessage),
-      () => setError("The animation libraries or fonts could not be loaded."),
+      () => {
+        setError("The animation libraries or fonts could not be loaded.");
+        endPaint();
+      },
     );
-  }, [node.html, node.code, node.height, node.scenarios, frames, embeddable]);
+  }, [
+    node.html,
+    node.code,
+    node.height,
+    node.scenarios,
+    frames,
+    embeddable,
+    endPaint,
+  ]);
 
   useEffect(() => () => portRef.current?.close(), []);
 
diff --git a/packages/review/app/src/animation/animation-paint.browser.test.tsx b/packages/review/app/src/animation/animation-paint.browser.test.tsx
new file mode 100644
index 0000000000..65d71380f7
--- /dev/null
+++ b/packages/review/app/src/animation/animation-paint.browser.test.tsx
@@ -0,0 +1,323 @@
+// An animation that arrives from the agent's stream paints its first frame
+// in: its stage stays unseen until the draw queue reaches it, the queue holds
+// on it while it paints, and the stage says when it is done. The stage is a
+// sandboxed frame, so these read what the host draws over its placeholders:
+// a block slot is shown only while its placeholder is.
+
+import { ApiDocument } from "@canvas/api-document";
+import { AuthoringActivityContext } from "@canvas/authoring-activity-context";
+import type { AuthoringCursor } from "@canvas/authoring-cursor";
+import { TestCanvasQuery } from "@canvas/canvas-query-test-utils";
+import { ReviewDebugSettingsProvider } from "@canvas/debug-settings";
+import { documentStyles } from "@canvas/document-styles";
+import {
+  type DrawQueueClock,
+  DrawQueueProvider,
+} from "@canvas/draw-queue-provider";
+import { ReviewSessionProvider } from "@canvas/host/review-session";
+import { documentMarker } from "@canvas/markers.stylex";
+import { ReviewPanelProvider } from "@canvas/review-panel";
+import {
+  type ReviewRoots,
+  ReviewRootsProvider,
+} from "@canvas/review-root-context";
+import {
+  testApiDocumentData,
+  testReviewSession,
+} from "@canvas/review-session-test-utils";
+import { type Block, documentSchema } from "@dev.fast/whiteboard-document";
+import * as stylex from "@stylexjs/stylex";
+import { act, createRef } from "react";
+import { type Root, createRoot } from "react-dom/client";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { cdp } from "vitest/browser";
+
+const note: Block = { id: "note", type: "markdown", markdown: "Lead note.\n" };
+
+const late: Block = { id: "late", type: "markdown", markdown: "Late note.\n" };
+
+const before: Block = { id: "b1", type: "markdown", markdown: "Before.\n" };
+
+const animationBlock = (html: string): Block =>
+  documentSchema.parse([
+    {
+      id: "anim",
+      type: "animation",
+      title: "Paint",
+      frames: [{ key: "a", title: "First" }],
+      html,
+    },
+  ])[0]!;
+
+const nodes = '<div class="wb-row"><div class="wb-node">A</div></div>';
+
+/** A clock the test moves by hand, as in draw-queue.browser.test.tsx: the
+ * cap never ends a paint unless the test advances past it. */
+const createManualClock = () => {
+  let time = 0;
+  let nextId = 0;
+  let scheduled: { id: number; due: number; fn: () => void } | null = null;
+
+  const clock: DrawQueueClock = {
+    now: () => time,
+    setTimeout: (fn, ms) => {
+      const id = ++nextId;
+      scheduled = { id, due: time + ms, fn };
+
+      return id;
+    },
+    clearTimeout: (handle) => {
+      if (scheduled?.id === handle) scheduled = null;
+    },
+  };
+
+  return {
+    clock,
+    advance: async (ms: number) => {
+      time += ms;
+      const due = scheduled;
+
+      if (due && due.due <= time) {
+        scheduled = null;
+        await act(async () => due.fn());
+      }
+    },
+  };
+};
+
+const working = {
+  workingCount: 1,
+  expiresAt: null,
+  activities: [{ activityId: "a", slot: 0 }],
+};
+
+let article: HTMLElement, root: Root;
+
+let manualClock: ReturnType<typeof createManualClock>;
+
+beforeEach(() => {
+  article = document.createElement("article");
+  article.className = `review-document ${stylex.props(documentStyles.article, documentMarker).className}`;
+  article.style.width = "900px";
+  const container = document.createElement("div");
+  article.append(container);
+  document.body.append(article);
+  root = createRoot(container);
+  manualClock = createManualClock();
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  article.remove();
+});
+
+const render = async (cursor: AuthoringCursor | null, blocks: Block[]) => {
+  const roots: ReviewRoots = {
+    appRef: createRef<HTMLDivElement>(),
+    shellRef: createRef<HTMLElement>(),
+    scrollRegionRef: createRef<HTMLElement>(),
+    articleRef: { current: article },
+  };
+
+  await act(async () =>
+    root.render(
+      <TestCanvasQuery>
+        <ReviewSessionProvider session={testReviewSession()}>
+          <ReviewDebugSettingsProvider>
+            <ReviewPanelProvider>
+              <ReviewRootsProvider roots={roots}>
+                <AuthoringActivityContext.Provider value={working}>
+                  <DrawQueueProvider cursor={cursor} clock={manualClock.clock}>
+                    <ApiDocument data={testApiDocumentData(blocks)} />
+                  </DrawQueueProvider>
+                </AuthoringActivityContext.Provider>
+              </ReviewRootsProvider>
+            </ReviewPanelProvider>
+          </ReviewDebugSettingsProvider>
+        </ReviewSessionProvider>
+      </TestCanvasQuery>,
+    ),
+  );
+};
+
+let seq = 0;
+
+const insert = (
+  id: string,
+  kind: "markdown" | "animation",
+): AuthoringCursor => ({
+  targetId: id,
+  blockId: id,
+  source: "edit",
+  edit: { type: "insert", targetId: id, blockId: id, kind },
+  seq: ++seq,
+});
+
+const motion = () =>
+  article.querySelector<HTMLElement>('[data-review-node-id="anim"]')?.dataset
+    .motion;
+
+/** The host's overlay for the block slot showing `text`. */
+const slot = (text: string) =>
+  [
+    ...article.querySelectorAll<HTMLElement>(
+      ".animation-block [data-animation-slot='block']",
+    ),
+  ].find((overlay) => overlay.textContent?.includes(text));
+
+const shown = (text: string) => {
+  const overlay = slot(text);
+
+  return (
+    overlay?.style.visibility === "visible" && overlay.style.opacity === "1"
+  );
+};
+
+const waitFor = (check: () => void, timeout = 8000) =>
+  vi.waitFor(check, { timeout, interval: 20 });
+
+/** Writes `b1` and, behind it in the queue, the animation, so the stage
+ * boots while the animation waits its turn. */
+const arriveBehindBlock = async (blocks: Block[]) => {
+  await render(insert("b1", "markdown"), [before, note, late]);
+  await render(insert("anim", "animation"), [before, ...blocks, note, late]);
+  expect(motion()).toBe("queued");
+};
+
+it("keeps a streamed animation unseen until the queue reaches it, then paints it and moves on", async () => {
+  await arriveBehindBlock([
+    animationBlock(`${nodes}<div data-wb-block="note"></div>`),
+  ]);
+
+  // Booted and laid out, but unseen while it waits.
+  await waitFor(() => expect(slot("Lead note")).toBeTruthy());
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  expect(slot("Lead note")!.style.visibility).toBe("hidden");
+
+  await manualClock.advance(680);
+  expect(motion()).toBe("painting");
+
+  // The stage paints and reports it before the cap.
+  await waitFor(() => expect(shown("Lead note")).toBe(true));
+  await waitFor(() => expect(motion()).toBeUndefined());
+});
+
+it("shows an animation loaded with the board at once, without painting", async () => {
+  await render(null, [
+    animationBlock(`${nodes}<div data-wb-block="note"></div>`),
+    note,
+  ]);
+
+  expect(motion()).toBeUndefined();
+  await waitFor(() => expect(shown("Lead note")).toBe(true));
+});
+
+it("shows a data-wb-paint=none element while the rest is still painting", async () => {
+  const chips = Array.from(
+    { length: 30 },
+    (_, index) => `<span class="wb-chip">job ${index}</span>`,
+  ).join("");
+
+  await arriveBehindBlock([
+    animationBlock(
+      `<div data-wb-block="note" data-wb-paint="none"></div><div class="wb-items">${chips}</div><div data-wb-block="late"></div>`,
+    ),
+  ]);
+  await waitFor(() => expect(slot("Late note")).toBeTruthy());
+
+  await manualClock.advance(680);
+  await waitFor(() => expect(shown("Lead note")).toBe(true));
+  // The last part paints about a second and a half in.
+  expect(shown("Late note")).toBe(false);
+  expect(motion()).toBe("painting");
+
+  await waitFor(() => expect(shown("Late note")).toBe(true));
+  await waitFor(() => expect(motion()).toBeUndefined());
+});
+
+it("hands painting to a paint handler and waits for what it returns", async () => {
+  await arriveBehindBlock([
+    animationBlock(
+      `${nodes}<div id="slot" data-wb-block="note"></div><script>
+        whiteboard.on("paint", ({ instant }) => {
+          document.querySelector("#slot").style.marginLeft = instant ? "0" : "40px";
+          return new Promise((done) => setTimeout(done, 1200));
+        });
+      </script>`,
+    ),
+  ]);
+  await waitFor(() => expect(slot("Lead note")).toBeTruthy());
+  const x = () => new DOMMatrix(slot("Lead note")!.style.transform).m41;
+  const start = x();
+
+  await manualClock.advance(680);
+  // The handler ran with motion, in place of the default painter.
+  await waitFor(() => expect(x()).toBe(start + 40));
+  expect(shown("Lead note")).toBe(true);
+  expect(motion()).toBe("painting");
+
+  await waitFor(() => expect(motion()).toBeUndefined());
+});
+
+const offset = () => {
+  const x = (text: string) =>
+    new DOMMatrix(slot(text)?.style.transform ?? "none").m41;
+
+  return x("Lead note") - x("Late note");
+};
+
+const twoSlots = (script: string) =>
+  animationBlock(
+    `<div id="slot" data-wb-block="note"></div><div data-wb-block="late"></div><script>${script}</script>`,
+  );
+
+it("runs a paint handler instantly on a cold load and lands the paint timeline at its end", async () => {
+  await render(null, [
+    twoSlots(`
+      whiteboard.on("paint", ({ instant }) => {
+        if (instant) document.querySelector("#slot").style.marginLeft = "40px";
+      });
+      whiteboard.timeline("paint").add("#slot", { translateX: [0, 20], duration: 300 });
+    `),
+    note,
+    late,
+  ]);
+
+  await waitFor(() => expect(offset()).toBe(60));
+  expect(motion()).toBeUndefined();
+});
+
+it("plays the paint timeline as a streamed animation paints in, then reports it", async () => {
+  await arriveBehindBlock([
+    twoSlots(`
+      whiteboard.timeline("paint").add("#slot", { translateX: [0, 30], duration: 600 });
+    `),
+  ]);
+  await waitFor(() => expect(slot("Late note")).toBeTruthy());
+
+  await manualClock.advance(680);
+  await waitFor(() => expect(offset()).toBeGreaterThan(0));
+  expect(offset()).toBeLessThan(30);
+  await waitFor(() => expect(motion()).toBeUndefined());
+  expect(offset()).toBe(30);
+});
+
+it("holds nothing under reduced motion", async () => {
+  await cdp().send("Emulation.setEmulatedMedia", {
+    features: [{ name: "prefers-reduced-motion", value: "reduce" }],
+  });
+
+  try {
+    await render(insert("anim", "animation"), [
+      animationBlock(`${nodes}<div data-wb-block="note"></div>`),
+      note,
+    ]);
+
+    // The queue gives the paint no time, and the stage shows at once.
+    await manualClock.advance(0);
+    expect(motion()).toBeUndefined();
+    await waitFor(() => expect(shown("Lead note")).toBe(true));
+  } finally {
+    await cdp().send("Emulation.setEmulatedMedia", { features: [] });
+  }
+});
diff --git a/packages/review/app/src/animation/stage-protocol.ts b/packages/review/app/src/animation/stage-protocol.ts
index 5f0f399ee6..b32d3059b0 100644
--- a/packages/review/app/src/animation/stage-protocol.ts
+++ b/packages/review/app/src/animation/stage-protocol.ts
@@ -42,6 +42,10 @@ export interface StageInit {
    * stage is its own document and may load no font from elsewhere. */
   fonts: string;
   reducedMotion: boolean;
+  /** The block arrived from the agent's stream: build the stage but keep it
+   * unseen until a `paint` message, then paint the first frame in and post
+   * `painted`. False on a cold load, in history and under reduced motion. */
+  paint: boolean;
   frame: number;
   /** The scenario the reader picked: the frame keys the stage starts on. */
   sequence?: string[];
@@ -66,7 +70,9 @@ export type HostMessage =
   /** The height the host's content in a slot takes. */
   | { type: "slot-size"; slot: string; height: number }
   /** The reader picked a scenario: play these frame keys, in order. */
-  | { type: "sequence"; keys: string[] };
+  | { type: "sequence"; keys: string[] }
+  /** The board's turn to draw this block came: paint the first frame in. */
+  | { type: "paint" };
 
 /** The tallest an auto-sized stage may report itself. */
 export const STAGE_MAX_HEIGHT = 4000;
@@ -110,6 +116,8 @@ export const stageMessageSchema = z.discriminatedUnion("type", [
   }),
   /** Every animation the frame started has finished. */
   z.strictObject({ type: z.literal("settled"), index: z.number().int() }),
+  /** The first frame has painted in, after a `paint` message. */
+  z.strictObject({ type: z.literal("painted") }),
   z.strictObject({ type: z.literal("goto"), key: z.string() }),
   z.strictObject({ type: z.literal("step"), delta: z.literal([-1, 1]) }),
   z.strictObject({
diff --git a/packages/review/app/src/animation/stage-reference.ts b/packages/review/app/src/animation/stage-reference.ts
index f67fe58136..5b21b2b171 100644
--- a/packages/review/app/src/animation/stage-reference.ts
+++ b/packages/review/app/src/animation/stage-reference.ts
@@ -8,6 +8,7 @@ import type {
   ArrowOptions,
   FrameChange,
   FrameTimeline,
+  PaintChange,
   Scene,
   SceneCardOptions,
   SceneChange,
@@ -37,6 +38,7 @@ export type StageReferenceChecks = [
   Check<Matches<WhiteboardShim, Reference.Whiteboard>>,
   Check<Matches<FrameChange, Reference.FrameChange>>,
   Check<Matches<FrameTimeline, Reference.FrameTimeline>>,
+  Check<Matches<PaintChange, Reference.PaintChange>>,
   Check<Matches<Scene, Reference.Scene>>,
   Check<Matches<SceneOptions, Reference.SceneOptions>>,
   Check<Matches<SceneCardOptions, Reference.SceneCardOptions>>,
diff --git a/packages/review/app/src/animation/stage-runtime.ts b/packages/review/app/src/animation/stage-runtime.ts
index b8e9931a47..d7821e4792 100644
--- a/packages/review/app/src/animation/stage-runtime.ts
+++ b/packages/review/app/src/animation/stage-runtime.ts
@@ -35,6 +35,17 @@ type FrameResult = void | Animation | readonly Animation[] | Promise<void>;
 
 type FrameHandler = (change: FrameChange) => FrameResult;
 
+/** What a paint handler learns when the block paints its first frame in. */
+export interface PaintChange {
+  /** The first frame, already drawn in its end state. */
+  frame: StageFrame & { index: number };
+  /** Skip motion and leave everything in its end state: the block loaded
+   * without painting, or the reader prefers reduced motion. */
+  instant: boolean;
+}
+
+type PaintHandler = (paint: PaintChange) => FrameResult;
+
 type Tone = "accent" | "added" | "removed" | "modified" | "muted";
 
 /** Where a scene part sits: 1-based column and row, with optional row and
@@ -219,6 +230,9 @@ export interface WhiteboardShim {
   code(name: string): HTMLElement;
   /** A placeholder the host fills with another block of this whiteboard. */
   block(id: string): HTMLElement;
+  /** Run when the block paints its first frame in, replacing the default
+   * painter. */
+  on(key: "paint", handler: PaintHandler): () => void;
   /** Run when a frame shows; "*" runs on every frame. */
   on(key: string, handler: FrameHandler): () => void;
   /** element.animate that holds its end state and honors instant changes. */
@@ -245,7 +259,8 @@ export interface WhiteboardShim {
   /** Removed. Throws, so a stage written for it says how to rebuild. */
   mermaid(...args: unknown[]): never;
   /** The frame's segment of the stage timeline: it plays when the reader
-   * steps into the frame, and lands at its end on a jump. */
+   * steps into the frame, and lands at its end on a jump. "paint" is a
+   * timeline of its own that plays once as the block paints in. */
   timeline(key: string): FrameTimeline;
   /** An SVG arrow between two elements that follows them as they move. */
   arrow(from: CardRef, to: CardRef, options?: ArrowOptions): SVGGElement;
@@ -311,6 +326,7 @@ export function stageRuntime(port: MessagePort): void {
   let instantMode = false;
   let activeSequence: string[] | undefined;
   const handlers = new Map<string, Set<FrameHandler>>();
+  const paintHandlers = new Set<PaintHandler>();
   let theme: Record<string, string> = {};
   let colorScheme: StageColorScheme = "dark";
   let nextSlot = 0;
@@ -618,18 +634,24 @@ export function stageRuntime(port: MessagePort): void {
     | { kind: "call"; callback: () => void; position?: TimelinePosition };
 
   const queued = new Map<string, Entry[]>();
+  const paintQueued: Entry[] = [];
   let built = false;
   let timeline: Timeline | undefined;
+  let paintTimeline: Timeline | undefined;
+
+  // "paint" names the painting-in timeline, unless a frame has that key.
+  const isPaint = (key: string) => key === "paint" && frameIndex(key) < 0;
 
   const frameTimeline = (key: string): FrameTimeline => {
-    if (frameIndex(key) < 0) throw new Error(`Unknown frame "${key}".`);
+    if (!isPaint(key) && frameIndex(key) < 0)
+      throw new Error(`Unknown frame "${key}".`);
 
     if (built)
       throw new Error(
         "Add to frame timelines while the animation's scripts first run.",
       );
 
-    let entries = queued.get(key);
+    let entries = isPaint(key) ? paintQueued : queued.get(key);
 
     if (!entries) queued.set(key, (entries = []));
     const list = entries;
@@ -694,6 +716,59 @@ export function stageRuntime(port: MessagePort): void {
     timeline = next;
   };
 
+  // The paint timeline is its own: numeric positions count from its start.
+  const buildPaintTimeline = () => {
+    if (!paintQueued.length) return;
+
+    const next = lib().createTimeline({
+      autoplay: false,
+      defaults: { duration: 600, ease: "outQuad" },
+    });
+
+    for (const [order, entry] of paintQueued.entries()) {
+      const position = entry.position ?? (order ? undefined : 0);
+
+      if (entry.kind === "call") next.call(entry.callback, position);
+      else if (entry.kind === "add")
+        next.add(entry.targets, entry.params, position);
+      else next.set(entry.targets, entry.params, position);
+    }
+
+    paintTimeline = next;
+  };
+
+  // Land on the paint timeline's end, or play it from its start.
+  const playPaintTimeline = (play: boolean): Promise<void> => {
+    const tl = paintTimeline;
+
+    if (!tl) return Promise.resolve();
+    tl.pause();
+
+    if (!play || tl.duration <= 0) {
+      tl.seek(tl.duration);
+
+      return Promise.resolve();
+    }
+
+    tl.seek(0);
+    tl.resume();
+
+    return new Promise((done) => {
+      const watch = () => {
+        if (tl.currentTime >= tl.duration || tl.completed) {
+          tl.pause();
+          tl.seek(tl.duration);
+
+          return done();
+        }
+
+        requestAnimationFrame(watch);
+      };
+
+      requestAnimationFrame(watch);
+    });
+  };
+
   let segmentToken = 0;
 
   // Land on the end of a frame's segment, or play the segment to its end.
@@ -1523,6 +1598,322 @@ export function stageRuntime(port: MessagePort): void {
     if (current >= 0) show(current, true).catch((error) => fail(String(error)));
   });
 
+  // Painting in: a block that arrived from the agent's stream is built
+  // unseen, then its first frame is drawn in when the host says the board
+  // has reached it. The default painter brings the kit's parts in one after
+  // another, in document order unless data-wb-paint orders them; a paint
+  // handler or timeline replaces it.
+  const PAINTED = [
+    ".wb-card",
+    ".wb-node",
+    ".wb-well",
+    ".wb-chip",
+    ".wb-item",
+    ".wb-badge",
+    ".wb-token",
+    ".wb-table tr",
+    ".wb-lane",
+    ".wb-title",
+    ".wb-caps",
+    ".wb-prose",
+    ".wb-shape",
+    ".wb-shape-text",
+    ".wb-arrow",
+    "[data-wb-slot]",
+    "[data-wb-paint]",
+    "[data-wb-paint-style]",
+  ].join(", ");
+
+  type PaintStyle = "fade" | "draw" | "wipe" | "none";
+
+  const PAINT_STYLES: PaintStyle[] = ["fade", "draw", "wipe", "none"];
+
+  // Every part is in by then, however many there are.
+  const PAINT_TOTAL = 1400;
+
+  // A stage told to paint in that never hears the host's word shows itself.
+  const PAINT_FALLBACK = 20_000;
+
+  // Beyond this many parts, neighbours paint together.
+  const PAINT_BEATS = 40;
+  const PAINT_GAP = 90;
+  const PAINT_EASE = "cubic-bezier(0.2, 0, 0, 1)";
+
+  const PAINT_MS: Record<PaintStyle, number> = {
+    fade: 280,
+    draw: 420,
+    wipe: 360,
+    none: 1,
+  };
+
+  let paintPending = false;
+  let paintAsked = false;
+  let paintDone = false;
+  let paintInstant = false;
+  let firstShown = false;
+  let paintTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const paintOrder = (element: Element) => {
+    const value = element.getAttribute("data-wb-paint");
+
+    if (value === null || value.trim() === "") return Infinity;
+    const order = Number(value);
+
+    if (Number.isFinite(order)) return order;
+    fail(
+      `data-wb-paint="${value}": use a number for the order, or "none" to show the element at once.`,
+    );
+
+    return Infinity;
+  };
+
+  const paintStyle = (element: Element): PaintStyle => {
+    const named = element.getAttribute("data-wb-paint-style");
+
+    if (named !== null) {
+      const style = PAINT_STYLES.find((item) => item === named);
+
+      if (style) return style;
+      fail(`data-wb-paint-style="${named}": use ${PAINT_STYLES.join(", ")}.`);
+    }
+
+    return element.matches(".wb-arrow, path, line, polyline") ? "draw" : "fade";
+  };
+
+  // The parts of the frame showing, each with what its paint holds: a part
+  // inside another painted part goes in with it, unless it is marked.
+  const paintParts = () => {
+    const candidates = [...document.body.querySelectorAll(PAINTED)].filter(
+      (element) =>
+        !element.closest('[data-wb-paint="none"]') &&
+        element.checkVisibility({
+          visibilityProperty: true,
+          opacityProperty: true,
+        }),
+    );
+
+    const painted = new Set(candidates);
+
+    const parts = candidates.filter((element) => {
+      if (
+        element.hasAttribute("data-wb-paint") ||
+        element.hasAttribute("data-wb-paint-style")
+      )
+        return true;
+
+      for (
+        let parent = element.parentElement;
+        parent && parent !== document.body;
+        parent = parent.parentElement
+      )
+        if (painted.has(parent)) return false;
+
+      return true;
+    });
+
+    // A stable sort: numbered parts first, the rest in document order.
+    return parts
+      .map((element) => ({ element, order: paintOrder(element) }))
+      .sort((a, b) => (a.order === b.order ? 0 : a.order < b.order ? -1 : 1))
+      .map(({ element }) => element);
+  };
+
+  const solidStroke = (stroke: SVGGeometryElement, length: number) => {
+    const dashes = getComputedStyle(stroke).strokeDasharray;
+
+    if (dashes === "none") return true;
+
+    return (dashes.match(/[\d.]+/g) ?? []).every(
+      (dash) => Number(dash) >= length * 0.99,
+    );
+  };
+
+  const fadeIn = (element: Element, delay: number) =>
+    element.animate([{ opacity: 0, translate: "0 6px", scale: "0.98" }, {}], {
+      duration: PAINT_MS.fade,
+      delay,
+      easing: PAINT_EASE,
+      fill: "backwards",
+    });
+
+  // A line draws along its path, its arrowhead last; a dashed line, which
+  // cannot draw, fades. Labels come in as the line arrives.
+  const drawIn = (element: Element, delay: number): Animation[] => {
+    const strokes =
+      element instanceof SVGGeometryElement
+        ? [element]
+        : [
+            ...element.querySelectorAll<SVGGeometryElement>(
+              "path, line, polyline, polygon, rect, circle, ellipse",
+            ),
+          ];
+
+    const animations: Animation[] = [];
+
+    for (const stroke of strokes) {
+      const length = stroke.getTotalLength();
+
+      if (!(length > 0) || !solidStroke(stroke, length)) {
+        animations.push(fadeIn(stroke, delay));
+        continue;
+      }
+
+      const dashes = `${length} ${length}`;
+
+      animations.push(
+        stroke.animate(
+          [
+            {
+              offset: 0,
+              strokeDasharray: dashes,
+              strokeDashoffset: `${length}`,
+              markerStart: "none",
+              markerEnd: "none",
+            },
+            { offset: 0.85, markerStart: "none", markerEnd: "none" },
+            { offset: 1, strokeDasharray: dashes, strokeDashoffset: "0" },
+          ],
+          {
+            duration: PAINT_MS.draw,
+            delay,
+            easing: "ease-in-out",
+            fill: "backwards",
+          },
+        ),
+      );
+    }
+
+    if (!strokes.length) animations.push(fadeIn(element, delay));
+
+    for (const text of element.querySelectorAll("text"))
+      animations.push(fadeIn(text, delay + PAINT_MS.draw * 0.6));
+
+    return animations;
+  };
+
+  const paintPart = (
+    element: Element,
+    style: PaintStyle,
+    delay: number,
+  ): Animation[] => {
+    switch (style) {
+      case "none":
+        return [
+          element.animate([{ opacity: 0 }, { opacity: 0 }], {
+            duration: Math.max(delay, PAINT_MS.none),
+          }),
+        ];
+      case "wipe":
+        return [
+          element.animate(
+            [{ clipPath: "inset(0 100% 0 0)" }, { clipPath: "inset(0 0 0 0)" }],
+            {
+              duration: PAINT_MS.wipe,
+              delay,
+              easing: PAINT_EASE,
+              fill: "backwards",
+            },
+          ),
+        ];
+      case "draw":
+        return drawIn(element, delay);
+      case "fade":
+        return [fadeIn(element, delay)];
+    }
+  };
+
+  // Starts every part's paint now, in this task, so nothing shows before its
+  // turn. Each animation fills only backwards: once it ends, the part is in
+  // its own styles.
+  const defaultPaint = (): Animation[] => {
+    const parts = paintParts();
+    const beats = Math.min(parts.length, PAINT_BEATS);
+    const longest = Math.max(...Object.values(PAINT_MS));
+
+    const gap =
+      beats > 1
+        ? Math.min(PAINT_GAP, (PAINT_TOTAL - longest) / (beats - 1))
+        : 0;
+
+    return parts.flatMap((element, index) => {
+      const beat = Math.floor((index * beats) / parts.length);
+
+      try {
+        return paintPart(element, paintStyle(element), beat * gap);
+      } catch {
+        // A part the browser cannot animate this way simply shows.
+        return [];
+      }
+    });
+  };
+
+  const runPaintHandlers = (instant: boolean): Promise<unknown>[] => {
+    const waits: Promise<unknown>[] = [];
+    const paint: PaintChange = { frame: whiteboard.frame, instant };
+    const wasInstant = instantMode;
+    instantMode = instant;
+
+    try {
+      for (const handler of paintHandlers) {
+        try {
+          waits.push(...finished(handler(paint)));
+        } catch (error) {
+          fail(String(error));
+        }
+      }
+    } finally {
+      instantMode = wasInstant;
+    }
+
+    return waits;
+  };
+
+  const paintIn = async () => {
+    paintPending = false;
+    const instant = paintInstant || prefersReducedMotion();
+    const started: Animation[] = [];
+    const waits: Promise<unknown>[] = [];
+
+    try {
+      root.removeAttribute("data-wb-unpainted");
+      const custom = paintHandlers.size > 0 || paintTimeline !== undefined;
+
+      if (!custom && !instant) started.push(...defaultPaint());
+      waits.push(playPaintTimeline(!instant), ...runPaintHandlers(instant));
+
+      if (instant) {
+        for (const animation of document.getAnimations())
+          if (finite(animation)) animation.finish();
+      }
+
+      wake();
+      await Promise.allSettled([
+        ...waits,
+        ...started.map((animation) => animation.finished),
+      ]);
+    } catch (error) {
+      fail(String(error));
+    } finally {
+      for (const animation of started) animation.cancel();
+      paintDone = true;
+      post({ type: "painted" });
+      wake();
+    }
+  };
+
+  // The host's word, or the stage's own timeout: a host that never asks must
+  // not leave the block blank. Long, since a block queued behind many others
+  // waits unseen like any other block would.
+  const askPaint = (instant: boolean) => {
+    if (!paintPending || paintAsked) return;
+    paintAsked = true;
+    paintInstant = instant;
+    clearTimeout(paintTimer);
+
+    if (firstShown) paintIn().catch((error) => fail(String(error)));
+    else if (instant) root.removeAttribute("data-wb-unpainted");
+  };
+
   const makeToken = (label?: string, tone?: Tone) => {
     const element = document.createElement("div");
     element.className = "wb-token";
@@ -2029,15 +2420,25 @@ export function stageRuntime(port: MessagePort): void {
     },
     code: (name) => placeholder("wbCode", name),
     block: (id) => placeholder("wbBlock", id),
-    on(key, handler) {
+    on(key: string, handler: FrameHandler | PaintHandler) {
+      if (isPaint(key)) {
+        // SAFETY: the "paint" overload takes a paint handler.
+        const paint = handler as PaintHandler;
+        paintHandlers.add(paint);
+
+        return () => paintHandlers.delete(paint);
+      }
+
       if (key !== "*" && frameIndex(key) < 0)
         throw new Error(`Unknown frame "${key}".`);
       let set = handlers.get(key);
 
       if (!set) handlers.set(key, (set = new Set()));
-      set.add(handler);
+      // SAFETY: any other key's overload takes a frame handler.
+      const frame = handler as FrameHandler;
+      set.add(frame);
 
-      return () => set.delete(handler);
+      return () => set.delete(frame);
     },
     animate(target, keyframes, options) {
       const element =
@@ -2272,9 +2673,10 @@ export function stageRuntime(port: MessagePort): void {
         // the layers nor those descendants are layout content.
         if (element.closest(".wb-arrows, .wb-tokens")) continue;
 
+        // Unpainted, the body is hidden; size the stage as it will show.
         if (
           !element.checkVisibility({
-            visibilityProperty: true,
+            visibilityProperty: !root.hasAttribute("data-wb-unpainted"),
             opacityProperty: true,
           })
         )
@@ -2348,6 +2750,13 @@ export function stageRuntime(port: MessagePort): void {
     if (message.sequence) activeSequence = [...message.sequence];
 
     root.toggleAttribute("data-wb-auto-size", message.autoSize);
+
+    if (message.paint) {
+      paintPending = true;
+      root.setAttribute("data-wb-unpainted", "");
+      paintTimer = setTimeout(() => askPaint(true), PAINT_FALLBACK);
+    }
+
     setProperties(message.scale);
     applyTheme(message.theme, message.colorScheme);
     style.textContent = message.kit;
@@ -2385,6 +2794,11 @@ export function stageRuntime(port: MessagePort): void {
     await runScripts([...document.body.querySelectorAll("script")]);
     arrows.forEach(route);
     buildTimeline();
+    buildPaintTimeline();
+
+    // Not painting in: the paint timeline lands at its end before the first
+    // frame.
+    if (!paintPending) playPaintTimeline(false);
     post({ type: "ready" });
     watcher.observe(root, {
       subtree: true,
@@ -2403,6 +2817,10 @@ export function stageRuntime(port: MessagePort): void {
         : message.frame;
 
     await show(initial, true);
+    firstShown = true;
+
+    if (!message.paint) runPaintHandlers(true);
+    else if (paintAsked) await paintIn();
   };
 
   port.onmessage = (event: MessageEvent<HostMessage>) => {
@@ -2435,6 +2853,11 @@ export function stageRuntime(port: MessagePort): void {
         break;
       }
 
+      case "paint":
+        // The stage's own timeout may have painted it already.
+        if (paintDone) post({ type: "painted" });
+        else askPaint(false);
+        break;
       case "sequence":
         if (!init) break;
 
diff --git a/packages/review/app/src/api-document.tsx b/packages/review/app/src/api-document.tsx
index 6a141b289c..c1a32f783c 100644
--- a/packages/review/app/src/api-document.tsx
+++ b/packages/review/app/src/api-document.tsx
@@ -619,7 +619,8 @@ export const DocumentNode = memo(function DocumentNode({
           ? drawStyles.blockPulse
           : motion === "erasing"
             ? drawStyles.blockCollapse
-            : motion === "landing" && drawStyles.blockLand,
+            : (motion === "landing" || motion === "painting") &&
+              drawStyles.blockLand,
       )}
       data-review-node-id={node.id}
       data-motion={motion}
diff --git a/packages/review/app/src/draw-queue-provider.tsx b/packages/review/app/src/draw-queue-provider.tsx
index 33f4c811ee..71654b8b67 100644
--- a/packages/review/app/src/draw-queue-provider.tsx
+++ b/packages/review/app/src/draw-queue-provider.tsx
@@ -3,6 +3,7 @@ import {
   type Context,
   type ReactNode,
   createContext,
+  useCallback,
   useContext,
   useEffect,
   useMemo,
@@ -17,6 +18,7 @@ import {
   type MotionPhase,
   arrive,
   nextDue,
+  painted,
   phases,
   standingCursor,
   tick,
@@ -50,6 +52,26 @@ const MotionPhasesContexts: Record<
   lenses: createContext<Map<string, MotionPhase>>(new Map()),
 };
 
+/** What a block may tell its queue about its own drawing. */
+export interface DrawQueueControls {
+  /** The block's stage finished painting it in. */
+  painted: (id: string) => void;
+}
+
+const noControls: DrawQueueControls = { painted: () => {} };
+
+const ControlsContexts: Record<ActivitySurface, Context<DrawQueueControls>> = {
+  document: createContext<DrawQueueControls>(noControls),
+  lenses: createContext<DrawQueueControls>(noControls),
+};
+
+/** The queue's controls; outside a queue (history) they do nothing. */
+export function useDrawQueueControls(
+  scope: ActivitySurface = "document",
+): DrawQueueControls {
+  return useContext(ControlsContexts[scope]);
+}
+
 /** Every element's phase, for a list that must keep an erased block around. */
 export function useMotionPhases(
   scope: ActivitySurface = "document",
@@ -120,14 +142,23 @@ export function DrawQueueProvider({
     return () => clock.clearTimeout(timer);
   }, [state, clock]);
 
+  const onPainted = useCallback(
+    (id: string) => setState((current) => painted(current, id, clock.now())),
+    [clock],
+  );
+
+  const controls = useMemo(() => ({ painted: onPainted }), [onPainted]);
   const standing = standingCursor(state);
   const map = useMemo(() => phases(state), [state]);
   const CursorContext = cursorContext(scope);
   const PhasesContext = MotionPhasesContexts[scope];
+  const ControlsContext = ControlsContexts[scope];
 
   return (
     <CursorContext.Provider value={cursor === undefined ? undefined : standing}>
-      <PhasesContext.Provider value={map}>{children}</PhasesContext.Provider>
+      <ControlsContext.Provider value={controls}>
+        <PhasesContext.Provider value={map}>{children}</PhasesContext.Provider>
+      </ControlsContext.Provider>
     </CursorContext.Provider>
   );
 }
diff --git a/packages/review/app/src/draw-queue.test.ts b/packages/review/app/src/draw-queue.test.ts
index 3306622d68..69314b128d 100644
--- a/packages/review/app/src/draw-queue.test.ts
+++ b/packages/review/app/src/draw-queue.test.ts
@@ -3,10 +3,12 @@ import { describe, expect, it } from "vitest";
 import type { AuthoringCursor } from "./authoring-cursor";
 import {
   EMPTY_QUEUE,
+  PAINT_CAP,
   STROKE_MS,
   WHOLE_THRESHOLD,
   arrive,
   nextDue,
+  painted,
   phases,
   standingCursor,
   tick,
@@ -36,6 +38,14 @@ const block = (id: string): AuthoringCursor => ({
   seq: ++seq,
 });
 
+const animation = (id: string): AuthoringCursor => ({
+  targetId: id,
+  blockId: id,
+  source: "edit",
+  edit: { type: "insert", targetId: id, blockId: id, kind: "animation" },
+  seq: ++seq,
+});
+
 const focus = (id: string): AuthoringCursor => ({
   targetId: id,
   blockId: id,
@@ -347,4 +357,42 @@ describe("draw queue", () => {
     state = tick(state, 780);
     expect(standingCursor(state)?.targetId).toBe("block-2");
   });
+
+  it("holds a new animation while it paints, until its stage is done or the cap", () => {
+    let state = arrive(EMPTY_QUEUE, animation("anim-1"), 0);
+    state = arrive(state, block("block-2"), 10);
+    expect(phases(state)).toEqual(
+      new Map([
+        ["anim-1", "painting"],
+        ["block-2", "queued"],
+      ]),
+    );
+    expect(nextDue(state)).toBe(PAINT_CAP);
+
+    state = painted(state, "anim-1", 900);
+    expect(phases(state)).toEqual(new Map([["block-2", "landing"]]));
+    expect(nextDue(state)).toBe(900 + 680);
+
+    // Left alone, the cap ends it.
+    const capped = tick(arrive(EMPTY_QUEUE, animation("anim-3"), 0), PAINT_CAP);
+    expect(capped.head).toBeNull();
+    expect(standingCursor(capped)?.targetId).toBe("anim-3");
+  });
+
+  it("ignores a painted report for another block, or when the head is not painting", () => {
+    let state = arrive(EMPTY_QUEUE, animation("anim-1"), 0);
+    expect(painted(state, "anim-2", 100)).toBe(state);
+
+    state = arrive(EMPTY_QUEUE, block("block-1"), 0);
+    state = arrive(state, animation("anim-1"), 0);
+    expect(painted(state, "anim-1", 100)).toBe(state);
+    expect(painted(EMPTY_QUEUE, "anim-1", 100)).toBe(EMPTY_QUEUE);
+  });
+
+  it("paints a new animation for no time with reduced motion", () => {
+    let state = arrive(EMPTY_QUEUE, animation("anim-1"), 0, true);
+    expect(nextDue(state)).toBe(0);
+    state = tick(state, 0);
+    expect(state.head).toBeNull();
+  });
 });
diff --git a/packages/review/app/src/draw-queue.ts b/packages/review/app/src/draw-queue.ts
index 1774d56193..e80fefbb42 100644
--- a/packages/review/app/src/draw-queue.ts
+++ b/packages/review/app/src/draw-queue.ts
@@ -9,11 +9,13 @@ import type { AuthoringCursor } from "./authoring-cursor";
  * A diagram written whole is traced in one quick pass, unit by unit in the
  * order a hand would draw it; a burst of units for one diagram larger than
  * WHOLE_THRESHOLD is folded into the same quick pass instead of a strobe of
- * full outlines.
+ * full outlines. A new animation paints itself in: it holds the queue until
+ * its stage reports it is painted, or until PAINT_CAP.
  */
 export type MotionPhase =
   | "queued"
   | "landing"
+  | "painting"
   | "outline"
   | "stroke"
   | "fill"
@@ -59,6 +61,10 @@ export const EMPTY_QUEUE: DrawState = {
 
 const HOLD = Infinity;
 
+/** The longest a new animation holds the queue while its stage paints, should
+ * the stage never say it is done. */
+export const PAINT_CAP = 4000;
+
 /** One quick pass over a whole diagram: a stroke per unit, each as long as
  * its trace, and a large diagram takes several units per stroke so the pass
  * still ends within a few seconds. */
@@ -112,6 +118,10 @@ export function stepsFor(cursor: AuthoringCursor): DrawStep[] {
           { phase: "fill", ms: 250 },
         ];
 
+      // An animation's stage paints its own first frame; painted() ends it.
+      if (edit.kind === "animation")
+        return [{ phase: "painting", ms: PAINT_CAP }];
+
       return [{ phase: "landing", ms: 680 }];
     case "update":
     case "replace":
@@ -297,6 +307,25 @@ export function tick(state: DrawState, now: number): DrawState {
   return changed ? { pending, head, standing } : state;
 }
 
+/** A block's stage finished painting: end its painting step now and move on,
+ * as a tick at that moment would. Anything else is left alone. */
+export function painted(
+  state: DrawState,
+  blockId: string,
+  now: number,
+): DrawState {
+  const head = state.head;
+
+  if (
+    !head ||
+    head.cursor.targetId !== blockId ||
+    head.steps[head.index]?.phase !== "painting"
+  )
+    return state;
+
+  return tick({ ...state, head: { ...head, until: now } }, now);
+}
+
 /** The head moved on to `index`, starting when the step before it was due. */
 const atStep = (head: DrawHead, index: number, from: number): DrawHead => ({
   ...head,
diff --git a/packages/review/app/src/draw-styles.ts b/packages/review/app/src/draw-styles.ts
index 08b7798d45..0eaf9a993d 100644
--- a/packages/review/app/src/draw-styles.ts
+++ b/packages/review/app/src/draw-styles.ts
@@ -11,7 +11,8 @@ import { tokens } from "./tokens.stylex";
 // then fill: a new flow node is traced clockwise from its top-left on its real
 // geometry (pathLength=1 on the rect), pulses once, and its label composes; an
 // edge is one stroke from source to target; a new block gets a slot, then
-// wipes in behind the marker dot; a rewritten block is erased in three
+// wipes in behind the marker dot (an animation gets the slot alone: its stage
+// paints its own content in); a rewritten block is erased in three
 // diagonal passes and rewritten; the top-level block being edited wears the
 // section ring. Queued content waits unseen so nothing lands twice. Reduced
 // motion shows every phase as its finished frame.
diff --git a/packages/review/instructions/animation.md b/packages/review/instructions/animation.md
index 391faf214f..595abb7763 100644
--- a/packages/review/instructions/animation.md
+++ b/packages/review/instructions/animation.md
@@ -83,6 +83,14 @@ Something that moves between frames (a job changing queue slot, a record regroup
 
 `whiteboard.frames` and `frame.index` follow the active scenario, so a frame outside it is not listed. Key your drawing on `frame.data`, not on positions.
 
+## Painting in
+
+When you write an animation, the reader watches it arrive: its first frame paints in, part by part, instead of appearing at once. It paints only then, not when the board loads with it already there, and not under reduced motion. The test harness and a cold load do not paint, so you see it only by watching your own write land on the board.
+
+- By default the kit's parts (cards, nodes, chips, badges, table rows, lanes, labels, peeks, tokens) fade in one after another in document order, and arrows draw along their path, all within about a second and a half. A part inside another goes in with it.
+- `data-wb-paint="1"` orders a part: numbered parts first, the rest in document order. `data-wb-paint="none"` shows an element and everything in it at once. `data-wb-paint-style="fade"`, `"draw"` (an SVG line), `"wipe"` (left to right) or `"none"` picks the effect. Any element with either attribute paints on its own.
+- `whiteboard.on("paint", ({ frame, instant }) => ...)` replaces the default painter: draw the first frame in yourself and return the animations, as a frame handler does. It also runs with `instant: true` when the block does not paint in; leave everything in its end state then. `whiteboard.timeline("paint")` is a timeline that plays once as the block paints in and lands at its end otherwise; it also replaces the default painter. Do not name a frame `paint`.
+
 ## Link the code
 
 Name the ranges the animation explains in `code`, then link the drawing to them:
diff --git a/packages/review/instructions/whiteboard.d.ts b/packages/review/instructions/whiteboard.d.ts
index 1a2418b067..6769e1b598 100644
--- a/packages/review/instructions/whiteboard.d.ts
+++ b/packages/review/instructions/whiteboard.d.ts
@@ -35,6 +35,15 @@ export interface FrameChange {
   instant: boolean;
 }
 
+/** What a paint handler learns as the block paints its first frame in. */
+export interface PaintChange {
+  /** The first frame, already drawn in its end state. */
+  frame: Frame;
+  /** Skip motion and leave everything in its end state: the block loaded
+   * without painting in, or the reader prefers reduced motion. */
+  instant: boolean;
+}
+
 /** Return the animations a handler starts, or a finite promise, so playback
  * waits for them. */
 export type FrameResult =
@@ -58,6 +67,12 @@ export interface Whiteboard {
    * helpers do not manage when it is true. */
   readonly reducedMotion: boolean;
 
+  /** Paint the first frame in yourself, in place of the default painter. Runs
+   * once, after the first frame is drawn: with motion when an agent writes
+   * the block, with `instant: true` on a cold load or under reduced motion,
+   * when it must leave everything in its end state. Painting ends when what
+   * it returns has finished. */
+  on(key: "paint", handler: (paint: PaintChange) => FrameResult): () => void;
   /** Run when a frame shows; "*" runs on every frame, before frame-specific
    * handlers, and again when reduced motion changes. Cancel earlier work when
    * another frame shows. Returns an unsubscribe function. */
@@ -74,7 +89,10 @@ export interface Whiteboard {
   /** The frame's part of one anime.js timeline: it plays when the reader steps
    * into the frame and lands at its end on a jump. A tween starts where the
    * frames before it left the element, so write only where it goes. Add to it
-   * while the script first runs, not from a frame handler. */
+   * while the script first runs, not from a frame handler. "paint" is a
+   * timeline of its own that plays once, after the first frame is drawn, as
+   * the block paints in, in place of the default painter; it lands at its end
+   * otherwise. Numeric positions count from its start. */
   timeline(key: string): FrameTimeline;
   /** anime.js v4, also the global `anime`: easings, stagger, utils. */
   readonly anime: unknown;
diff --git a/packages/review/src/animation-stage-kit.ts b/packages/review/src/animation-stage-kit.ts
index 3345113242..5b797d1d19 100644
--- a/packages/review/src/animation-stage-kit.ts
+++ b/packages/review/src/animation-stage-kit.ts
@@ -178,6 +178,10 @@ const CLASSES: [selector: string, use: string][] = [
     ".wb-shape, .wb-shape-text",
     "An SVG shape drawn like a card, and the text inside it.",
   ],
+  [
+    "[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 +190,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;

From f450fe86f6979bf0d7422ab19b6df5ff87bdc8af Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Sun, 1 Nov 2026 12:31:13 -0500
Subject: [PATCH 5/6] Add the clip block: one timeline the reader plays by its
 markers

An animation is frames the reader steps through. A clip is its sibling:
one continuous timeline the reader plays, pauses, and jumps around by
named markers, for motion where the timing itself is the point. The two
share the sandboxed stage, the runtime, the draft checkout, the host
component, the code tour and the paint-in.

- Schema: clip {title, html, markers: {key, title, caption?, code?}[],
  scenarios?: {key, label}[], code, height, pins}; the Animations
  preference gates it with the animation.
- Runtime: whiteboard.clip(scenario?) builds a timeline with .marker();
  marker handlers, whiteboard.markers and whiteboard.marker; the frame
  API throws in a clip with a pointer to markers. Lifecycle attributes
  follow the marker last reached. Reduced motion steps marker to marker.
- Protocol: mode, markers and scenario in the init; play, pause, seek and
  scenario from the host; clip, time, marker and ended from the stage.
- Host: the block is now a shell over a frame player and a clip player
  with shared controls; a Markers strip, a progress line with a tick per
  marker, Space to play, arrows between markers; the tour's stops are
  the markers; a rebooted stage resumes at its marker.
- Drafts check a clip out as markers.json; a reference clip,
  request-timing, runs in the harness; the authoring guide and typings
  cover clips.

Agent-Session: b315a4f8-1333-461c-9be6-366ceb231b7f
---
 .../app/src/animation/animation-block.tsx     | 602 ++++--------------
 .../animation-paint.browser.test.tsx          |  33 +-
 .../app/src/animation/animation-tour.test.ts  |  17 +
 .../app/src/animation/animation-tour.ts       |  26 +-
 .../src/animation/clip-block.browser.test.tsx | 418 ++++++++++++
 .../review/app/src/animation/clip-player.tsx  | 197 ++++++
 .../review/app/src/animation/frame-player.tsx | 348 ++++++++++
 .../src/animation/references.browser.test.tsx | 113 +++-
 .../app/src/animation/stage-controls.tsx      | 162 +++++
 .../review/app/src/animation/stage-player.ts  |  58 ++
 .../app/src/animation/stage-protocol.ts       |  58 +-
 .../app/src/animation/stage-reference.ts      |   8 +
 .../review/app/src/animation/stage-runtime.ts | 570 ++++++++++++++++-
 .../app/src/block-document-derivations.ts     |   1 +
 .../review/app/src/blocks.browser.test.tsx    |   6 +
 packages/review/app/src/blocks.tsx            |  17 +-
 packages/review/app/src/draw-queue.test.ts    |  16 +-
 packages/review/app/src/draw-queue.ts         |   5 +-
 packages/review/app/src/ui/progress-line.tsx  |  67 ++
 packages/review/instructions/animation.md     |  33 +
 .../animations/request-timing/README.md       |  22 +
 .../animations/request-timing/animation.html  | 120 ++++
 .../animations/request-timing/block.json      |  21 +
 .../animations/request-timing/markers.json    |  32 +
 .../animations/request-timing/scenarios.json  |   4 +
 packages/review/instructions/whiteboard.d.ts  |  67 +-
 packages/review/src/animation-stage-kit.ts    |   3 +-
 packages/review/src/fixtures/blocks/clip.json |  19 +
 .../review-api/animation-authoring.test.ts    |  86 +++
 .../src/review-api/animation-drafts.test.ts   |  94 ++-
 .../review/src/review-api/animation-drafts.ts |  85 ++-
 .../review-api/animation-references.test.ts   |   2 +-
 .../review/src/review-api/authoring-tools.ts  |   6 +-
 .../review/src/review-api/document-text.ts    |  39 +-
 packages/review/src/review-api/http.ts        |   9 +-
 .../review/src/review-api/instructions.ts     |   2 +-
 .../src/blocks/animation.ts                   |   6 +-
 .../src/blocks/clip.test.ts                   |  87 +++
 .../whiteboard-document/src/blocks/clip.ts    | 125 ++++
 .../whiteboard-document/src/blocks/index.ts   |   4 +
 packages/whiteboard-document/src/document.ts  |   6 +-
 41 files changed, 3012 insertions(+), 582 deletions(-)
 create mode 100644 packages/review/app/src/animation/clip-block.browser.test.tsx
 create mode 100644 packages/review/app/src/animation/clip-player.tsx
 create mode 100644 packages/review/app/src/animation/frame-player.tsx
 create mode 100644 packages/review/app/src/animation/stage-controls.tsx
 create mode 100644 packages/review/app/src/animation/stage-player.ts
 create mode 100644 packages/review/app/src/ui/progress-line.tsx
 create mode 100644 packages/review/instructions/animations/request-timing/README.md
 create mode 100644 packages/review/instructions/animations/request-timing/animation.html
 create mode 100644 packages/review/instructions/animations/request-timing/block.json
 create mode 100644 packages/review/instructions/animations/request-timing/markers.json
 create mode 100644 packages/review/instructions/animations/request-timing/scenarios.json
 create mode 100644 packages/review/src/fixtures/blocks/clip.json
 create mode 100644 packages/whiteboard-document/src/blocks/clip.test.ts
 create mode 100644 packages/whiteboard-document/src/blocks/clip.ts

diff --git a/packages/review/app/src/animation/animation-block.tsx b/packages/review/app/src/animation/animation-block.tsx
index dac45005a2..58b0b16654 100644
--- a/packages/review/app/src/animation/animation-block.tsx
+++ b/packages/review/app/src/animation/animation-block.tsx
@@ -25,7 +25,8 @@ import { withClass } from "@canvas/stylex-props";
 import { themeClass, themeStyles } from "@canvas/theme-styles";
 import { tokens } from "@canvas/tokens.stylex";
 import { captureUiEvent } from "@canvas/ui-telemetry";
-import { Button, IconButton } from "@canvas/ui/button";
+import { Button } from "@canvas/ui/button";
+import { focusStyles } from "@canvas/ui/focus";
 import { SegmentedControl } from "@canvas/ui/segmented";
 import { textStyles } from "@canvas/ui/text";
 import { useTooltip } from "@canvas/ui/tooltip";
@@ -40,7 +41,6 @@ import {
 import { STAGE_KIT_CSS, STAGE_THEME } from "@review/animation-stage-kit";
 import * as stylex from "@stylexjs/stylex";
 import {
-  type KeyboardEvent,
   type ReactNode,
   type RefObject,
   useCallback,
@@ -53,8 +53,17 @@ import {
 } from "react";
 import { createPortal } from "react-dom";
 
-import { animationTour, frameAnchorId, frameContent } from "./animation-tour";
+import {
+  animationTour,
+  frameAnchorId,
+  frameContent,
+  markerAnchorId,
+} from "./animation-tour";
+import { useClipPlayer } from "./clip-player";
+import { useFramePlayer } from "./frame-player";
 import { useReportAnimationRun } from "./report-run";
+import { StepStrip } from "./stage-controls";
+import type { StagePlayer } from "./stage-player";
 import {
   type HostMessage,
   STAGE_BOOT,
@@ -69,8 +78,6 @@ import { SCALE } from "./stage-scale";
 // Read on demand: a Worker may lack import.meta.url.
 const stageUrl = () => new URL("./stage.html", import.meta.url).href;
 
-const DEFAULT_DURATION = 3000;
-
 let animeSource: Promise<string> | undefined;
 
 // anime.js's source, for the stage: its own chunk, fetched by the first
@@ -127,13 +134,14 @@ function readTheme(element: Element): Pick<StageInit, "theme" | "colorScheme"> {
 const reducedMotion = () =>
   matchMedia("(prefers-reduced-motion: reduce)").matches;
 
-/** Blocks a stage may show with whiteboard.block(): any but animations,
- * which would nest stages. */
+/** Blocks a stage may show with whiteboard.block(): any but animations and
+ * clips, which would nest stages. */
 function embeddableBlocks(document: Block[]): Map<string, Block> {
   const found = new Map<string, Block>();
 
   const visit = (block: Block) => {
-    if (block.id && block.type !== "animation") found.set(block.id, block);
+    if (block.id && block.type !== "animation" && block.type !== "clip")
+      found.set(block.id, block);
 
     if ("children" in block) block.children.forEach(visit);
   };
@@ -143,30 +151,76 @@ function embeddableBlocks(document: Block[]): Map<string, Block> {
   return found;
 }
 
+type StageBlockProps = BlockProps<"animation" | "clip">;
+
+/** The channel to the stage showing: set when it boots. */
+function useStagePort() {
+  const portRef = useRef<MessagePort | null>(null);
+
+  const send = useCallback((message: HostMessage) => {
+    portRef.current?.postMessage(message);
+  }, []);
+
+  return { portRef, send };
+}
+
+type StagePort = ReturnType<typeof useStagePort>;
+
 /**
- * An agent's HTML animation, run in a sandboxed stage. Whiteboard pieces the
- * stage asks for (code peeks, other blocks) are drawn here, over the
- * placeholders the stage lays out, so they are the real components.
+ * An agent's HTML animation or clip, run in a sandboxed stage. Whiteboard
+ * pieces the stage asks for (code peeks, other blocks) are drawn here, over
+ * the placeholders the stage lays out, so they are the real components. An
+ * animation's reader steps through frames; a clip's plays one timeline.
  */
-export function AnimationBlock({
+export function AnimationBlock(props: StageBlockProps) {
+  return props.node.type === "clip" ? (
+    <ClipStage {...props} node={props.node} />
+  ) : (
+    <FrameStage {...props} node={props.node} />
+  );
+}
+
+function FrameStage(props: BlockProps<"animation">) {
+  const port = useStagePort();
+
+  return (
+    <StageBlock
+      {...props}
+      port={port}
+      player={useFramePlayer(props.node, port.send)}
+    />
+  );
+}
+
+function ClipStage(props: BlockProps<"clip">) {
+  const port = useStagePort();
+
+  return (
+    <StageBlock
+      {...props}
+      port={port}
+      player={useClipPlayer(props.node, port.send)}
+    />
+  );
+}
+
+function StageBlock({
   node,
   data,
   children,
-}: BlockProps<"animation">) {
+  port: { portRef, send },
+  player,
+}: StageBlockProps & { port: StagePort; player: StagePlayer }) {
   const { theme } = useReviewDebugSettings();
   const panelStore = useReviewPanelStore();
   const session = useReviewSession();
   const { diagramFullscreenOnClick } = useWhiteboardSettings();
   const frameRef = useRef<HTMLIFrameElement>(null);
-  const portRef = useRef<MessagePort | null>(null);
-  const [index, setIndex] = useState(0);
-  const [sequenceKeys, setSequenceKeys] = useState<string[] | null>(null);
-  const sequenceRef = useRef<string[] | null>(null);
-  const [playing, setPlaying] = useState(false);
-  const [settled, setSettled] = useState(-1);
   const [contentHeight, setContentHeight] = useState(120);
   const [slots, setSlots] = useState<SlotLayout[]>([]);
   const [error, setError] = useState<string | null>(null);
+  const clip = node.type === "clip";
+  const noun = clip ? "clip" : "animation";
 
   const reportRun = useReportAnimationRun(data.snapshot.reviewId, node.id);
 
@@ -197,49 +251,29 @@ export function AnimationBlock({
   const [held, setHeld] = useState(0);
   const openRef = useRef<HTMLButtonElement>(null);
   const closeRef = useRef<HTMLButtonElement>(null);
-  const indexRef = useRef(index);
-  indexRef.current = index;
 
   const embeddable = useMemo(
     () => embeddableBlocks(data.snapshot.document),
     [data.snapshot.document],
   );
 
-  const frames = node.frames;
-
-  const activeFrames = useMemo(() => {
-    if (!sequenceKeys) return frames;
-    const byKey = new Map(frames.map((item) => [item.key, item]));
-
-    return sequenceKeys.flatMap((key) => {
-      const item = byKey.get(key);
+  const { stops, activeIndex } = player;
+  const stop = stops[activeIndex];
+  const anchorId = clip ? markerAnchorId : frameAnchorId;
 
-      return item ? [item] : [];
-    });
-  }, [frames, sequenceKeys]);
-
-  const last = activeFrames.length - 1;
-  const frame = frames[Math.min(index, frames.length - 1)]!;
-
-  const activeIndex = Math.max(
-    0,
-    activeFrames.findIndex((item) => item.key === frame.key),
-  );
-
-  const steps = activeFrames.every((item) => item.label) ? activeFrames : null;
-
-  // A stop per frame of the path showing, when its frames show code.
+  // A stop per frame of the path showing, or per marker, when they show code.
   const tour = useMemo(
     () =>
       animationTour(
         { id: node.id, title: node.title },
         data.anchors,
-        activeFrames,
+        stops,
+        anchorId,
       ),
-    [node.id, node.title, data.anchors, activeFrames],
+    [node.id, node.title, data.anchors, stops, anchorId],
   );
 
-  const frameAnchor = tour && frameAnchorId(node.id, frame.key);
+  const frameAnchor = tour && stop ? anchorId(node.id, stop.key) : null;
 
   // Unlike a diagram's, the tour stays open on a stop it no longer has: a
   // scenario switch moves it to the frame showing instead.
@@ -261,17 +295,13 @@ export function AnimationBlock({
       JSON.stringify([
         node.html,
         node.height,
-        node.frames,
+        node.type === "clip" ? node.markers : node.frames,
         node.code,
         [...embeddable.keys()],
       ]),
-    [node.html, node.height, node.frames, node.code, embeddable],
+    [node, embeddable],
   );
 
-  const send = useCallback((message: HostMessage) => {
-    portRef.current?.postMessage(message);
-  }, []);
-
   // Paint once the stage is ready and the queue has reached this block, or
   // has given up on it: the content must appear either way.
   const paintStage = () => {
@@ -292,41 +322,6 @@ export function AnimationBlock({
 
   useEffect(() => endPaint, [endPaint]);
 
-  const go = useCallback(
-    (target: number, instant: boolean) => {
-      const keys = sequenceRef.current;
-
-      const path = keys
-        ? keys.flatMap((key) => {
-            const item = frames.find((candidate) => candidate.key === key);
-
-            return item ? [item] : [];
-          })
-        : frames;
-
-      const currentKey = frames[indexRef.current]?.key;
-      const currentPosition = path.findIndex((item) => item.key === currentKey);
-      const position = Math.max(0, Math.min(path.length - 1, target));
-      const next = frames.findIndex((item) => item.key === path[position]?.key);
-
-      if (next < 0 || next === indexRef.current) return;
-      setIndex(next);
-      send({
-        type: "frame",
-        index: next,
-        instant,
-        direction:
-          currentPosition < 0 || position === currentPosition
-            ? "none"
-            : position > currentPosition
-              ? "forward"
-              : "backward",
-        adjacent: currentPosition >= 0 && position === currentPosition + 1,
-      });
-    },
-    [frames, send],
-  );
-
   const openTour = () => {
     if (!tour || !frameAnchor) return;
 
@@ -351,23 +346,23 @@ export function AnimationBlock({
     captureUiEvent(session, "peek_opened", { via: "diagram" });
     const { openPeek, moveOverlayTour, active } = panelStore.getState();
 
-    const stop = tour?.stops.find((item) => item.anchor.id === frameAnchor);
+    const tourStop = tour?.stops.find((item) => item.anchor.id === frameAnchor);
 
-    if (!tour || !stop)
+    if (!tour || !tourStop || !stop)
       return openPeek({
         kind: "peek",
         anchor,
         content: { kind: "source", source: anchor.peek },
       });
 
-    if (tourOpen) return moveOverlayTour(stop.anchor.id, { reveal: true });
+    if (tourOpen) return moveOverlayTour(tourStop.anchor.id, { reveal: true });
 
     if (expanded || diagramFullscreenOnClick) return openTour();
 
     openPeek({
       kind: "peek",
-      anchor: stop.anchor,
-      content: frameContent(node.id, data.anchors, frame, name),
+      anchor: tourStop.anchor,
+      content: frameContent(node.id, data.anchors, stop, name),
       tour: {
         definition: tour,
         revealRequest: (active?.tour?.revealRequest ?? 0) + 1,
@@ -375,45 +370,6 @@ export function AnimationBlock({
     });
   };
 
-  // A stage script's setSequence() and the scenario picker both land here.
-  const selectSequence = (keys: string[]) => {
-    const unique = new Set(keys);
-
-    const valid =
-      unique.size === keys.length &&
-      keys.every((key) => frames.some((frame) => frame.key === key));
-
-    if (!valid) return;
-
-    if (
-      sequenceRef.current?.length === keys.length &&
-      sequenceRef.current.every((key, index) => key === keys[index])
-    )
-      return;
-
-    sequenceRef.current = keys;
-    setSequenceKeys(keys);
-    setPlaying(false);
-    setTimeUp(-1);
-    const currentKey = frames[indexRef.current]?.key;
-
-    const fallback = frames.findIndex((frame) => frame.key === keys[0]);
-
-    const next = keys.includes(currentKey) ? indexRef.current : fallback;
-
-    if (next !== indexRef.current) setIndex(next);
-
-    // Refresh even a preserved key: lifecycle ranges, held scene changes,
-    // and its timeline can differ when active order changes.
-    send({
-      type: "frame",
-      index: next,
-      instant: true,
-      direction: "none",
-      adjacent: false,
-    });
-  };
-
   const onMessage = useRef<(message: StageMessage) => void>(() => {});
 
   onMessage.current = (message) => {
@@ -424,29 +380,6 @@ export function AnimationBlock({
       case "slots":
         setSlots(message.slots);
         break;
-      case "settled":
-        setSettled(message.index);
-        break;
-      case "goto": {
-        const keys = sequenceRef.current;
-        const path = keys ?? frames.map((item) => item.key);
-        const position = path.indexOf(message.key);
-        go(position, true);
-        break;
-      }
-
-      case "step": {
-        const keys = sequenceRef.current;
-        const path = keys ?? frames.map((item) => item.key);
-        const currentKey = frames[indexRef.current]?.key;
-        go(path.indexOf(currentKey) + message.delta, false);
-        break;
-      }
-
-      case "sequence":
-        selectSequence(message.keys);
-        break;
-
       case "reveal":
         reveal(message.name);
         break;
@@ -465,10 +398,13 @@ export function AnimationBlock({
       case "painted":
         endPaint();
         break;
+      default:
+        player.receive(message);
     }
   };
 
   const bootedRef = useRef<HTMLIFrameElement | null>(null);
+  const bootPlayer = useEffectEvent(() => player.boot());
 
   // Hand the stage its runtime and a private port when its page first loads.
   // A later load in the same frame is a page the stage navigated to, which
@@ -483,7 +419,7 @@ export function AnimationBlock({
     if (bootedRef.current === frameRef.current) {
       portRef.current = null;
       setSlots([]);
-      setError("The animation left its stage.");
+      setError(`The ${noun} left its stage.`);
       endPaint();
 
       return;
@@ -498,22 +434,7 @@ export function AnimationBlock({
       if (message.success) onMessage.current(message.data);
     };
 
-    // A new stage starts in the scenario the reader had picked, or the first.
-    const sequence =
-      (
-        node.scenarios?.find((scenario) =>
-          sameKeys(scenario.frames, sequenceRef.current),
-        ) ?? node.scenarios?.[0]
-      )?.frames ?? null;
-
-    sequenceRef.current = sequence;
-    setSequenceKeys(sequence);
-
-    if (sequence && !sequence.includes(frames[indexRef.current]!.key)) {
-      indexRef.current = frames.findIndex((item) => item.key === sequence[0]);
-      setIndex(indexRef.current);
-    }
-
+    const kind = bootPlayer();
     setSlots([]);
     setError(null);
 
@@ -539,16 +460,10 @@ export function AnimationBlock({
 
     const init: Omit<StageInit, "libraries" | "fonts"> = {
       type: "init",
+      ...kind,
       html: node.html,
       kit: STAGE_KIT_CSS,
       autoSize: node.height === "auto",
-      frames: frames.map(({ key, title, caption, data, code }) => ({
-        key,
-        title,
-        caption,
-        data,
-        code,
-      })),
       code: Object.keys(node.code),
       codeTitles: codeTitles(node, data.anchors),
       blocks: [...embeddable.keys()],
@@ -556,8 +471,6 @@ export function AnimationBlock({
       scale: SCALE,
       reducedMotion: reducedMotion(),
       paint,
-      frame: indexRef.current,
-      ...(sequence && { sequence }),
     };
 
     Promise.all([loadAnime(), loadFonts()]).then(
@@ -568,21 +481,13 @@ export function AnimationBlock({
           fonts,
         } satisfies HostMessage),
       () => {
-        setError("The animation libraries or fonts could not be loaded.");
+        setError(`The ${noun} libraries or fonts could not be loaded.`);
         endPaint();
       },
     );
-  }, [
-    node.html,
-    node.code,
-    node.height,
-    node.scenarios,
-    frames,
-    embeddable,
-    endPaint,
-  ]);
-
-  useEffect(() => () => portRef.current?.close(), []);
+  }, [node, noun, embeddable, endPaint, portRef]);
+
+  useEffect(() => () => portRef.current?.close(), [portRef]);
 
   // Read after React commits the matching theme class. Listening to the host
   // event directly can race that commit and export a mixed palette (new neutral
@@ -592,32 +497,6 @@ export function AnimationBlock({
       send({ type: "theme", ...readTheme(figureRef.current) });
   }, [theme, send]);
 
-  // Play: hold each active-sequence frame for its duration and until its motion ends.
-  const [timeUp, setTimeUp] = useState(-1);
-
-  useEffect(() => {
-    if (!playing) return;
-
-    const timer = setTimeout(
-      () => setTimeUp(index),
-      frame.duration ?? DEFAULT_DURATION,
-    );
-
-    return () => clearTimeout(timer);
-  }, [playing, index, frame.duration]);
-
-  useEffect(() => {
-    if (!playing || timeUp !== index || settled !== index) return;
-
-    if (activeIndex >= last) setPlaying(false);
-    else go(activeIndex + 1, false);
-  }, [playing, timeUp, settled, index, activeIndex, last, go]);
-
-  // An edit can drop frames or a sequence selection from under the current one.
-  useEffect(() => {
-    if (!activeFrames.some((item) => item.key === frame.key)) go(0, true);
-  }, [activeFrames, frame.key, go]);
-
   const { closeOverlayTour, moveOverlayTour } = panelStore.getState();
   const collapse = useCallback(() => setExpanded(false), []);
   const close = tourOpen ? closeOverlayTour : collapse;
@@ -643,11 +522,10 @@ export function AnimationBlock({
     const anchor = panelStore.getState().overlayTour?.anchor;
 
     if (!tour || !frameAnchor || !anchor) return;
-    const position = tour.stops.findIndex((stop) => stop.anchor.id === anchor);
+    const position = tour.stops.findIndex((item) => item.anchor.id === anchor);
 
     if (position < 0) moveOverlayTour(frameAnchor, { reveal: true });
-    else if (position !== activeIndex)
-      go(position, Math.abs(position - activeIndex) > 1);
+    else if (position !== activeIndex) player.pick(position, "tour");
   });
 
   const overlayAnchor = overlay?.anchor;
@@ -662,11 +540,11 @@ export function AnimationBlock({
     if (!tour || fullscreen || !inlineAnchor) return;
 
     const position = tour.stops.findIndex(
-      (stop) => stop.anchor.id === inlineAnchor,
+      (item) => item.anchor.id === inlineAnchor,
     );
 
     if (position >= 0 && position !== activeIndex)
-      go(position, Math.abs(position - activeIndex) > 1);
+      player.pick(position, "tour");
   });
 
   useEffect(() => {
@@ -688,19 +566,19 @@ export function AnimationBlock({
       return;
     }
 
-    const stop = tour.stops.find((item) => item.anchor.id === frameAnchor);
+    const tourStop = tour.stops.find((item) => item.anchor.id === frameAnchor);
 
     if (
       !inlineAnchor ||
       fullscreen ||
-      !stop ||
+      !tourStop ||
       (active?.anchor?.id === frameAnchor && active.tour?.definition === tour)
     )
       return;
     openPeek({
       kind: "peek",
-      anchor: stop.anchor,
-      content: stop.content,
+      anchor: tourStop.anchor,
+      content: tourStop.content,
       tour: {
         definition: tour,
         revealRequest: (active?.tour?.revealRequest ?? 0) + 1,
@@ -721,14 +599,6 @@ export function AnimationBlock({
     followFrame();
   }, [frameAnchor, tour]);
 
-  const onKeyDown = (event: KeyboardEvent) => {
-    if (event.key === "ArrowRight") go(activeIndex + 1, false);
-    else if (event.key === "ArrowLeft") go(activeIndex - 1, false);
-    else return;
-
-    event.preventDefault();
-  };
-
   const figure = (
     <figure
       ref={figureRef}
@@ -737,20 +607,23 @@ export function AnimationBlock({
         styles.figure,
         fullscreen && styles.figureFullscreen,
         drawStyles.blockChild,
+        player.onFigureKeyDown !== undefined && focusStyles.ring,
       )}
       aria-label={node.title}
+      tabIndex={player.onFigureKeyDown ? 0 : undefined}
+      onKeyDown={player.onFigureKeyDown}
     >
       <DiagramHeader
-        kind="ANIMATION"
+        kind={clip ? "CLIP" : "ANIMATION"}
         title={node.title}
         titleStyle={styles.headerTitle}
-        meta={`${activeIndex + 1} / ${activeFrames.length}`}
+        meta={`${activeIndex + 1} / ${stops.length}`}
         action={
           fullscreen ? (
             <Button
               ref={closeRef}
               xstyle={diagramStyles.button}
-              aria-label={tourOpen ? "Close tour" : "Close expanded animation"}
+              aria-label={tourOpen ? "Close tour" : `Close expanded ${noun}`}
               onClick={close}
             >
               Close
@@ -765,7 +638,7 @@ export function AnimationBlock({
             <Button
               ref={openRef}
               xstyle={diagramStyles.button}
-              aria-label="Expand animation"
+              aria-label={`Expand ${noun}`}
               onClick={() => {
                 setHeld(figureRef.current?.offsetHeight ?? 0);
                 setExpanded(true);
@@ -786,23 +659,12 @@ export function AnimationBlock({
           </span>
           <SegmentedControl
             label="Scenario"
-            value={
-              node.scenarios.find((scenario) =>
-                sameKeys(scenario.frames, sequenceKeys),
-              )?.key
-            }
+            value={player.scenario}
             options={node.scenarios.map(({ key, label }) => ({
               value: key,
               label,
             }))}
-            onChange={(key) => {
-              const keys = node.scenarios!.find(
-                (scenario) => scenario.key === key,
-              )!.frames;
-
-              send({ type: "sequence", keys });
-              selectSequence(keys);
-            }}
+            onChange={player.selectScenario}
           />
         </div>
       )}
@@ -851,85 +713,22 @@ export function AnimationBlock({
           </div>
         </div>
       </div>
-      {steps && (
-        <div
-          {...stylex.props(styles.steps)}
-          role="group"
-          aria-label="Steps"
-          onKeyDown={onKeyDown}
-        >
-          {steps.map((item, position) => (
-            <button
-              key={item.key}
-              type="button"
-              aria-current={position === activeIndex ? "step" : undefined}
-              onClick={() => go(position, Math.abs(position - activeIndex) > 1)}
-              {...stylex.props(
-                styles.step,
-                position === activeIndex && styles.stepCurrent,
-              )}
-            >
-              <span {...stylex.props(styles.stepIndex)}>{position + 1}</span>
-              <span data-review-copy-prose>{item.label}</span>
-            </button>
-          ))}
-        </div>
+      {player.afterStage}
+      {player.strip && (
+        <StepStrip
+          label={player.strip.label}
+          items={player.strip.items}
+          activeIndex={activeIndex}
+          onPick={(position) => player.pick(position, "controls")}
+          onKeyDown={player.onKeyDown}
+        />
       )}
-      <div {...stylex.props(styles.controls)} onKeyDown={onKeyDown}>
-        <ControlButton
-          label="Previous frame"
-          disabled={activeIndex === 0}
-          onClick={() => go(activeIndex - 1, false)}
-        >
-          <path d="M14.5 6.5 9 12l5.5 5.5" />
-        </ControlButton>
-        <ControlButton
-          label={playing ? "Pause" : activeIndex >= last ? "Replay" : "Play"}
-          onClick={() => {
-            if (playing) return setPlaying(false);
-
-            if (activeIndex >= last) go(0, true);
-
-            setPlaying(true);
-          }}
-        >
-          {playing ? (
-            <path d="M9 6.5v11M15 6.5v11" />
-          ) : (
-            <path d="M8.5 6.5v11l9-5.5z" />
-          )}
-        </ControlButton>
-        <ControlButton
-          label="Next frame"
-          disabled={activeIndex >= last}
-          onClick={() => go(activeIndex + 1, false)}
-        >
-          <path d="M9.5 6.5 15 12l-5.5 5.5" />
-        </ControlButton>
-        <div {...stylex.props(styles.caption)} aria-live="polite">
-          <strong data-review-copy-prose>{frame.title}</strong>
-          {frame.caption && (
-            <span data-review-copy-prose> {frame.caption}</span>
-          )}
-        </div>
-        {!steps && (
-          <div {...stylex.props(styles.dots)} role="group" aria-label="Frames">
-            {activeFrames.map((item, position) => (
-              <FrameDot
-                key={item.key}
-                title={item.title}
-                current={position === activeIndex}
-                onClick={() =>
-                  go(position, Math.abs(position - activeIndex) > 1)
-                }
-              />
-            ))}
-          </div>
-        )}
+      <div {...stylex.props(styles.controls)} onKeyDown={player.onKeyDown}>
+        {player.controls}
       </div>
       {error && (
         <p role="alert" {...stylex.props(styles.error)}>
-          The animation reported an error: {error}
+          The {noun} reported an error: {error}
         </p>
       )}
     </figure>
@@ -974,7 +773,7 @@ export function AnimationBlock({
           )}
           role="dialog"
           aria-modal="true"
-          aria-label={node.title ?? "Animation"}
+          aria-label={node.title ?? (clip ? "Clip" : "Animation")}
         >
           {figure}
         </div>,
@@ -984,9 +783,6 @@ export function AnimationBlock({
   );
 }
 
-const sameKeys = (left: readonly string[], right: readonly string[] | null) =>
-  right?.length === left.length && left.every((key, i) => key === right[i]);
-
 /** A host component drawn where the stage put its placeholder. */
 function SlotOverlay({
   slot,
@@ -1066,43 +862,10 @@ function TourButton({
   );
 }
 
-function ControlButton({
-  label,
-  disabled,
-  onClick,
-  children,
-}: {
-  label: string;
-  disabled?: boolean;
-  onClick(): void;
-  children: ReactNode;
-}) {
-  const tooltip = useTooltip(label, { quick: true });
-
-  return (
-    <IconButton
-      ref={tooltip}
-      aria-label={label}
-      size="small"
-      disabled={disabled}
-      onClick={onClick}
-    >
-      <svg
-        aria-hidden="true"
-        focusable="false"
-        viewBox="0 0 24 24"
-        {...stylex.props(styles.icon)}
-      >
-        {children}
-      </svg>
-    </IconButton>
-  );
-}
-
 /** What hovering a drawn element that opens code says: its label, file and
  * lines. */
 function codeTitles(
-  node: BlockProps<"animation">["node"],
+  node: StageBlockProps["node"],
   anchors: ReadonlyMap<string, SourcePeekAnchor>,
 ): Record<string, string> {
   return Object.fromEntries(
@@ -1121,29 +884,6 @@ function codeTitles(
   );
 }
 
-function FrameDot({
-  title,
-  current,
-  onClick,
-}: {
-  title: string;
-  current: boolean;
-  onClick(): void;
-}) {
-  const tooltip = useTooltip(title, { instant: true });
-
-  return (
-    <button
-      ref={tooltip}
-      type="button"
-      aria-label={title}
-      aria-current={current ? "step" : undefined}
-      onClick={onClick}
-      {...stylex.props(styles.dot, current && styles.dotCurrent)}
-    />
-  );
-}
-
 const narrow = "@media (max-width: 720px)";
 
 const styles = stylex.create({
@@ -1257,90 +997,6 @@ const styles = stylex.create({
     borderTopStyle: "solid",
     borderTopColor: tokens.rule,
   },
-  icon: {
-    width: "16px",
-    height: "16px",
-    fill: "none",
-    stroke: "currentColor",
-    strokeWidth: 1.6,
-    strokeLinecap: "round",
-    strokeLinejoin: "round",
-  },
-  caption: {
-    flex: "1 1 auto",
-    minWidth: 0,
-    marginLeft: space.s6,
-    paddingBlock: space.s8,
-    color: tokens.inkMuted,
-    lineHeight: leading.px18,
-  },
-  dots: {
-    display: "flex",
-    flex: "0 0 auto",
-    gap: space.s6,
-  },
-  dot: {
-    width: "8px",
-    height: "8px",
-    padding: 0,
-    borderWidth: "1px",
-    borderStyle: "solid",
-    borderColor: tokens.inkFaint,
-    borderRadius: radius.round,
-    backgroundColor: tokens.transparent,
-    cursor: "pointer",
-    outline: { default: null, ":focus-visible": `1px solid ${tokens.accent}` },
-    outlineOffset: "2px",
-  },
-  dotCurrent: {
-    borderColor: tokens.accent,
-    backgroundColor: tokens.accent,
-  },
-  // A named step per frame, like a progress strip, instead of plain dots.
-  steps: {
-    display: { default: "flex", [narrow]: "grid" },
-    gridTemplateColumns: {
-      default: null,
-      [narrow]: "repeat(4, minmax(0, 1fr))",
-    },
-    overflowX: { default: "auto", [narrow]: "visible" },
-    borderTopWidth: "1px",
-    borderTopStyle: "solid",
-    borderTopColor: tokens.rule,
-  },
-  step: {
-    display: "flex",
-    flex: "1 1 0",
-    alignItems: "center",
-    justifyContent: "center",
-    gap: space.s4,
-    minWidth: { default: "fit-content", [narrow]: 0 },
-    padding: {
-      default: `${space.s6} ${space.s10}`,
-      [narrow]: `${space.s6} ${space.s4}`,
-    },
-    borderStyle: "none",
-    borderBottomWidth: "2px",
-    borderBottomStyle: "solid",
-    borderBottomColor: tokens.transparent,
-    backgroundColor: tokens.transparent,
-    color: tokens.inkMuted,
-    font: `${fontSize.micro} ${tokens.fontMono}`,
-    letterSpacing: tracking.chrome,
-    textAlign: "center",
-    textTransform: "uppercase",
-    whiteSpace: { default: "nowrap", [narrow]: "normal" },
-    cursor: "pointer",
-    outline: { default: null, ":focus-visible": `1px solid ${tokens.accent}` },
-    outlineOffset: "-2px",
-  },
-  stepCurrent: {
-    borderBottomColor: tokens.accent,
-    color: tokens.ink,
-  },
-  stepIndex: {
-    color: "inherit",
-  },
   error: {
     margin: 0,
     padding: `${space.s8} ${space.s12}`,
diff --git a/packages/review/app/src/animation/animation-paint.browser.test.tsx b/packages/review/app/src/animation/animation-paint.browser.test.tsx
index 65d71380f7..15719c6377 100644
--- a/packages/review/app/src/animation/animation-paint.browser.test.tsx
+++ b/packages/review/app/src/animation/animation-paint.browser.test.tsx
@@ -144,7 +144,7 @@ let seq = 0;
 
 const insert = (
   id: string,
-  kind: "markdown" | "animation",
+  kind: "markdown" | "animation" | "clip",
 ): AuthoringCursor => ({
   targetId: id,
   blockId: id,
@@ -202,6 +202,37 @@ it("keeps a streamed animation unseen until the queue reaches it, then paints it
   await waitFor(() => expect(motion()).toBeUndefined());
 });
 
+it("paints a streamed clip in at time 0, as an animation, and moves on", async () => {
+  const clip = documentSchema.parse([
+    {
+      id: "anim",
+      type: "clip",
+      title: "Paint",
+      markers: [
+        { key: "a", title: "First" },
+        { key: "b", title: "Last" },
+      ],
+      html: `${nodes}<div id="slot" data-wb-block="note"></div><script>
+        whiteboard.clip().marker("a").add("#slot", { translateX: [0, 80], duration: 400 }).marker("b");
+      </script>`,
+    },
+  ])[0]!;
+
+  await render(insert("b1", "markdown"), [before, note, late]);
+  await render(insert("anim", "clip"), [before, clip, note, late]);
+  expect(motion()).toBe("queued");
+  await waitFor(() => expect(slot("Lead note")).toBeTruthy());
+  expect(slot("Lead note")!.style.visibility).toBe("hidden");
+  const start = new DOMMatrix(slot("Lead note")!.style.transform).m41;
+
+  await manualClock.advance(680);
+  expect(motion()).toBe("painting");
+  await waitFor(() => expect(shown("Lead note")).toBe(true));
+  await waitFor(() => expect(motion()).toBeUndefined());
+  // Painted at time 0: nothing has played.
+  expect(new DOMMatrix(slot("Lead note")!.style.transform).m41).toBe(start);
+});
+
 it("shows an animation loaded with the board at once, without painting", async () => {
   await render(null, [
     animationBlock(`${nodes}<div data-wb-block="note"></div>`),
diff --git a/packages/review/app/src/animation/animation-tour.test.ts b/packages/review/app/src/animation/animation-tour.test.ts
index 15dcc65df9..135e9ee685 100644
--- a/packages/review/app/src/animation/animation-tour.test.ts
+++ b/packages/review/app/src/animation/animation-tour.test.ts
@@ -9,6 +9,7 @@ import {
   type AnimationFrame,
   animationTour,
   frameContent,
+  markerAnchorId,
 } from "./animation-tour";
 
 const block = { id: "anim", title: "Order flow" };
@@ -96,6 +97,22 @@ describe("animationTour", () => {
   });
 });
 
+describe("animationTour over a clip's markers", () => {
+  it("has a stop per marker, named for the marker", () => {
+    const markers = [
+      { key: "sent", title: "Sent", code: ["send"] },
+      { key: "saved", title: "Saved", caption: "The row lands." },
+    ];
+
+    const tour = animationTour(block, anchors, markers, markerAnchorId);
+
+    expect(tour?.stops.map((stop) => [stop.anchor.id, stop.content])).toEqual([
+      ["anim:marker:sent", { kind: "source", source: selection(2) }],
+      ["anim:marker:saved", { kind: "explanation", text: "The row lands." }],
+    ]);
+  });
+});
+
 describe("frameContent", () => {
   it("leads with the named code", () => {
     expect(frameContent(block.id, anchors, frames[2]!, "save")).toEqual({
diff --git a/packages/review/app/src/animation/animation-tour.ts b/packages/review/app/src/animation/animation-tour.ts
index bb392df33f..d3789d654c 100644
--- a/packages/review/app/src/animation/animation-tour.ts
+++ b/packages/review/app/src/animation/animation-tour.ts
@@ -4,12 +4,15 @@ import type {
   ReviewPeekContent,
   SourcePeekAnchor,
 } from "@canvas/review-panel-model";
-import { type Block, animationCodeId } from "@dev.fast/whiteboard-document";
+import { animationCodeId } from "@dev.fast/whiteboard-document";
 
-export type AnimationFrame = Extract<
-  Block,
-  { type: "animation" }
->["frames"][number];
+/** What a tour stop is drawn from: an animation's frame or a clip's marker. */
+export interface AnimationFrame {
+  key: string;
+  title: string;
+  caption?: string;
+  code?: string[];
+}
 
 type Anchors = ReadonlyMap<string, SourcePeekAnchor>;
 
@@ -17,6 +20,10 @@ type Anchors = ReadonlyMap<string, SourcePeekAnchor>;
 export const frameAnchorId = (blockId: string, frameKey: string) =>
   `${blockId}:frame:${frameKey}`;
 
+/** The tour stop, and panel anchor, a clip's marker stands for. */
+export const markerAnchorId = (blockId: string, markerKey: string) =>
+  `${blockId}:marker:${markerKey}`;
+
 /** The code a frame lists that resolves, `lead` first when it resolves. */
 function frameSources(
   blockId: string,
@@ -50,13 +57,16 @@ export function frameContent(
 }
 
 /**
- * An animation's tour: a stop per frame of the path being shown, in order.
- * There is none unless some frame of the path shows code that resolves.
+ * An animation's tour: a stop per frame of the path being shown, in order,
+ * or a clip's: a stop per marker. There is none unless some frame or marker
+ * shows code that resolves. `anchorId` names each stop: `frameAnchorId`, or
+ * `markerAnchorId` for a clip.
  */
 export function animationTour(
   block: { id: string; title?: string },
   anchors: Anchors,
   path: readonly AnimationFrame[],
+  anchorId: (blockId: string, key: string) => string = frameAnchorId,
 ): GuidedTour | null {
   if (!path.some((frame) => frameSources(block.id, anchors, frame).length))
     return null;
@@ -69,7 +79,7 @@ export function animationTour(
 
       return {
         anchor: {
-          id: frameAnchorId(block.id, frame.key),
+          id: anchorId(block.id, frame.key),
           title: frame.title,
           ...(frame.caption && { detail: frame.caption }),
           ...(content.kind === "source" && { peek: content.source }),
diff --git a/packages/review/app/src/animation/clip-block.browser.test.tsx b/packages/review/app/src/animation/clip-block.browser.test.tsx
new file mode 100644
index 0000000000..520ff3f14b
--- /dev/null
+++ b/packages/review/app/src/animation/clip-block.browser.test.tsx
@@ -0,0 +1,418 @@
+// A clip runs in the same sandboxed stage as an animation, as one timeline
+// the reader plays and jumps around by markers. The stage is opaque to the
+// test, so these read what the host draws: the meta, the Markers strip, the
+// play button, and the overlay of a block slot the clip's script moves.
+
+import {
+  loadFixture,
+  mountWhiteboard,
+  settled,
+} from "@canvas/whiteboard-fixture";
+import {
+  type Block,
+  documentSchema,
+  selectionKey,
+} from "@dev.fast/whiteboard-document";
+import type { ReviewProgress } from "@review/review-api/review-progress";
+import type { Snapshot } from "@review/review-api/store";
+import { act } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { cdp } from "vitest/browser";
+
+import "@canvas/styles.css";
+
+const note: Block = {
+  id: "note",
+  type: "markdown",
+  markdown: "Moving note.\n",
+};
+
+const markers = [
+  { key: "start", title: "Start", caption: "It sets off." },
+  { key: "middle", title: "Middle", code: ["status"] },
+  { key: "end", title: "End", caption: "It arrives.", code: ["status"] },
+];
+
+// The slot rides the timeline: x 0 at the start, 200 at the middle and 300
+// at the end. The middle's handler drops it 40px, so a jump shows it ran.
+const SCRIPT = `
+  const slot = document.querySelector("#slot");
+  const build = (clip, far) =>
+    clip
+      .marker("start")
+      .add(slot, { translateX: [0, 200], duration: 600, ease: "linear" })
+      .marker("middle")
+      .add(slot, { translateX: far, duration: 600, ease: "linear" })
+      .marker("end");
+  whiteboard.on("middle", () => { slot.style.marginTop = "40px"; });
+  whiteboard.on("start", () => { slot.style.marginTop = "0px"; });
+`;
+
+const clipBlock = (
+  script = `${SCRIPT} build(whiteboard.clip(), 300);`,
+  extra: { scenarios?: { key: string; label: string }[] } = {},
+): Block =>
+  documentSchema.parse([
+    {
+      id: "clip-1",
+      type: "clip",
+      title: "Trip",
+      height: 200,
+      markers,
+      code: { status: "head/order.ts#L1" },
+      html: `<div id="slot" data-wb-block="note" style="width: 160px"></div><script>${script}</script>`,
+      pins: { repositoryId: "repo", base: "base", head: "head" },
+      ...extra,
+    },
+  ])[0]!;
+
+const progress: ReviewProgress = {
+  files: [],
+  lenses: [],
+  resolvedSelections: {
+    [selectionKey({
+      file: "order.ts",
+      start: { side: "head", line: 1 },
+      end: { side: "head", line: 1 },
+    })]: [{ file: "order.ts", side: "head", fromLine: 1, toLine: 1 }],
+  },
+};
+
+let canvas: ReturnType<typeof mountWhiteboard> | undefined;
+
+afterEach(async () => {
+  await act(async () => canvas?.dispose());
+  canvas = undefined;
+  document.body.replaceChildren();
+});
+
+async function mount(block: Block) {
+  const snapshot: Snapshot = {
+    reviewId: "clip-review",
+    version: 0,
+    title: "Clips",
+    pins: { repositoryId: "repo", base: "base", head: "head" },
+    target: {
+      kind: "commits",
+      repositoryId: "repo",
+      base: "base",
+      head: "head",
+    },
+    document: [block, note],
+    createdAt: "2026-11-01T00:00:00.000Z",
+  };
+
+  const container = document.createElement("div");
+  container.style.cssText = "width: 860px; margin: 0 auto;";
+  document.body.append(container);
+
+  await act(async () => {
+    canvas = mountWhiteboard(
+      container,
+      loadFixture({
+        snapshot,
+        progress,
+        commits: [],
+        images: {},
+        traces: {},
+        maps: {},
+      }),
+    );
+  });
+
+  return container;
+}
+
+const figure = () => document.querySelector<HTMLElement>(".animation-block")!;
+
+const meta = () =>
+  document.querySelector(".animation-block figcaption em")?.textContent;
+
+const strip = () => [
+  ...document.querySelectorAll<HTMLButtonElement>(
+    ".animation-block [role='group'][aria-label='Markers'] button",
+  ),
+];
+
+const current = () =>
+  strip()
+    .find((button) => button.getAttribute("aria-current") === "step")
+    ?.textContent?.replace(/^\d+/, "");
+
+const alertText = () =>
+  document.querySelector(".animation-block [role='alert']")?.textContent ??
+  null;
+
+const playButton = () =>
+  document.querySelector<HTMLButtonElement>(
+    ".animation-block button[aria-label='Play'], .animation-block button[aria-label='Pause'], .animation-block button[aria-label='Replay']",
+  )!;
+
+const overlay = () =>
+  document.querySelector<HTMLElement>(
+    ".animation-block [data-animation-slot='block']",
+  );
+
+/** Where the stage put the moving slot, in stage pixels. */
+const position = () => {
+  const matrix = new DOMMatrix(overlay()?.style.transform ?? "none");
+
+  return { x: Math.round(matrix.m41), y: Math.round(matrix.m42) };
+};
+
+const click = (button: HTMLButtonElement) => act(async () => button.click());
+
+const wait = (ms: number) =>
+  act(() => new Promise((resolve) => setTimeout(resolve, ms)));
+
+/** Mounted, with the slot laid out at the clip's start. */
+async function booted(block = clipBlock()) {
+  const container = await mount(block);
+
+  expect(await settled(() => overlay()?.style.visibility === "visible")).toBe(
+    true,
+  );
+  expect(await settled(() => meta() === `1 / ${markers.length}`)).toBe(true);
+
+  return container;
+}
+
+describe("clip", () => {
+  it("boots and lists its markers under the stage", async () => {
+    await booted();
+
+    expect(strip().map((button) => button.textContent)).toEqual([
+      "1Start",
+      "2Middle",
+      "3End",
+    ]);
+    expect(current()).toBe("Start");
+    expect(playButton().getAttribute("aria-label")).toBe("Play");
+    expect(figure().textContent).toContain("It sets off.");
+    expect(
+      document.querySelector(".animation-block figcaption")?.textContent,
+    ).toContain("CLIP");
+    expect(alertText()).toBeNull();
+  });
+
+  it("plays to its end, the active marker following the playhead", async () => {
+    await booted();
+    const start = position();
+
+    await click(playButton());
+    expect(playButton().getAttribute("aria-label")).toBe("Pause");
+    expect(await settled(() => current() === "Middle", 4000)).toBe(true);
+    expect(meta()).toBe("2 / 3");
+
+    expect(
+      await settled(
+        () => playButton().getAttribute("aria-label") === "Replay",
+        4000,
+      ),
+    ).toBe(true);
+    expect(current()).toBe("End");
+    expect(meta()).toBe("3 / 3");
+    expect(figure().textContent).toContain("It arrives.");
+    expect(await settled(() => position().x === start.x + 300)).toBe(true);
+    expect(alertText()).toBeNull();
+
+    // Replay starts over from the start.
+    await click(playButton());
+    expect(await settled(() => current() === "Start")).toBe(true);
+  });
+
+  it("holds the playhead while paused", async () => {
+    await booted();
+    const start = position().x;
+
+    await click(playButton());
+    expect(await settled(() => position().x > start + 20, 4000)).toBe(true);
+    await click(playButton());
+    expect(playButton().getAttribute("aria-label")).toBe("Play");
+    await wait(150);
+    const held = position().x;
+
+    await wait(500);
+    expect(position().x).toBe(held);
+    expect(held).toBeLessThan(start + 300);
+  });
+
+  it("jumps to a marker from the strip and runs its handler", async () => {
+    await booted();
+    const start = position();
+
+    await click(strip()[1]!);
+    expect(await settled(() => meta() === "2 / 3")).toBe(true);
+    // Landed at the middle's time, with its handler's drop.
+    expect(
+      await settled(
+        () => position().x === start.x + 200 && position().y === start.y + 40,
+      ),
+    ).toBe(true);
+    expect(playButton().getAttribute("aria-label")).toBe("Play");
+
+    // Arrow keys on the focused figure step between markers.
+    figure().focus();
+    await act(async () =>
+      figure().dispatchEvent(
+        new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true }),
+      ),
+    );
+    expect(await settled(() => meta() === "3 / 3")).toBe(true);
+    expect(await settled(() => position().x === start.x + 300)).toBe(true);
+
+    await click(strip()[0]!);
+    expect(
+      await settled(() => position().x === start.x && position().y === start.y),
+    ).toBe(true);
+
+    // Space on the figure plays.
+    await act(async () =>
+      figure().dispatchEvent(
+        new KeyboardEvent("keydown", { key: " ", bubbles: true }),
+      ),
+    );
+    expect(playButton().getAttribute("aria-label")).toBe("Pause");
+  });
+
+  it("builds a scenario's own timeline when the reader picks it", async () => {
+    await booted(
+      clipBlock(
+        `${SCRIPT} build(whiteboard.clip("near"), 240); build(whiteboard.clip("far"), 400);`,
+        {
+          scenarios: [
+            { key: "near", label: "Near" },
+            { key: "far", label: "Far" },
+          ],
+        },
+      ),
+    );
+    const start = position().x;
+
+    const end = async () => {
+      await click(strip()[2]!);
+      expect(await settled(() => meta() === "3 / 3")).toBe(true);
+      await wait(150);
+
+      return position().x - start;
+    };
+
+    expect(await end()).toBe(240);
+
+    await click(
+      [
+        ...document.querySelectorAll<HTMLButtonElement>(
+          "[role='group'][aria-label='Scenario'] button",
+        ),
+      ].find((button) => button.textContent === "Far")!,
+    );
+    // Back at the start of the new timeline.
+    expect(await settled(() => meta() === "1 / 3")).toBe(true);
+    expect(await settled(() => position().x === start)).toBe(true);
+    expect(await end()).toBe(400);
+    expect(alertText()).toBeNull();
+  });
+
+  it("reports a declared marker its script never places", async () => {
+    await mount(
+      clipBlock(
+        `whiteboard.clip().marker("start").add("#slot", { translateX: 100 }).marker("middle");`,
+      ),
+    );
+
+    expect(
+      await settled(() => alertText()?.includes('Marker "end" is not placed')),
+    ).toBe(true);
+  });
+
+  it("refuses an animation's frame API in a clip", async () => {
+    await mount(
+      clipBlock(
+        `${SCRIPT} build(whiteboard.clip(), 300); whiteboard.goto("start");`,
+      ),
+    );
+
+    expect(
+      await settled(() => alertText()?.includes("A clip has no frames")),
+    ).toBe(true);
+  });
+
+  it("steps marker to marker without motion under reduced motion", async () => {
+    await cdp().send("Emulation.setEmulatedMedia", {
+      features: [{ name: "prefers-reduced-motion", value: "reduce" }],
+    });
+
+    try {
+      await booted();
+      const start = position().x;
+      const seen = new Set<number>();
+
+      await click(playButton());
+
+      // Every sample is a marker's place: the slot never moves between them.
+      const sample = setInterval(() => seen.add(position().x - start), 20);
+
+      try {
+        expect(await settled(() => meta() === "2 / 3", 5000)).toBe(true);
+        expect(await settled(() => meta() === "3 / 3", 5000)).toBe(true);
+        expect(
+          await settled(
+            () => playButton().getAttribute("aria-label") === "Replay",
+            5000,
+          ),
+        ).toBe(true);
+      } finally {
+        clearInterval(sample);
+      }
+
+      expect([...seen].sort((a, b) => a - b)).toEqual([0, 200, 300]);
+    } finally {
+      await cdp().send("Emulation.setEmulatedMedia", { features: [] });
+    }
+  }, 20_000);
+
+  it("tours its markers, the panel following playback", async () => {
+    await booted();
+
+    const tourOverlay = () => document.querySelector(".diagram-tour-overlay");
+    const pill = () => document.querySelector(".tour-pill-count")?.textContent;
+
+    const tour = await settled(() =>
+      document.querySelector<HTMLButtonElement>(".diagram-tour-button"),
+    );
+
+    await click(tour!);
+    expect(await settled(tourOverlay)).toBeTruthy();
+    // Fullscreen is a new stage: it has laid the slot out again.
+    expect(await settled(() => overlay()?.style.visibility === "visible")).toBe(
+      true,
+    );
+    expect(
+      await settled(
+        () =>
+          tourOverlay()!.querySelectorAll("section[data-review-anchor-id]")
+            .length === 3,
+      ),
+    ).toBe(true);
+    expect(
+      tourOverlay()!.querySelector(
+        "[data-review-anchor-id='clip-1:marker:middle']",
+      ),
+    ).toBeTruthy();
+
+    // The panel's Next seeks to the next marker, paused.
+    await click(
+      tourOverlay()!.querySelector<HTMLButtonElement>(
+        "[data-tour-target='tour-next']",
+      )!,
+    );
+    expect(await settled(() => meta() === "2 / 3")).toBe(true);
+    expect(pill()).toBe("2/3");
+    expect(playButton().getAttribute("aria-label")).toBe("Play");
+
+    // Playing on, the panel follows the markers the playhead passes.
+    await click(playButton());
+    expect(await settled(() => pill() === "3/3", 4000)).toBe(true);
+    expect(meta()).toBe("3 / 3");
+  });
+});
diff --git a/packages/review/app/src/animation/clip-player.tsx b/packages/review/app/src/animation/clip-player.tsx
new file mode 100644
index 0000000000..11f0ae8a65
--- /dev/null
+++ b/packages/review/app/src/animation/clip-player.tsx
@@ -0,0 +1,197 @@
+// A clip's one timeline: the reader plays it, pauses it, and jumps between
+// its markers. The stage owns the playhead and reports it; this follows.
+
+import type { BlockProps } from "@canvas/blocks";
+import { ProgressLine } from "@canvas/ui/progress-line";
+import { type KeyboardEvent, useMemo, useRef, useState } from "react";
+
+import {
+  ControlButton,
+  StopCaption,
+  pauseIcon,
+  playIcon,
+} from "./stage-controls";
+import type { PickedBy, StagePlayer, StageSend } from "./stage-player";
+import type { PlacedMarker, StageMessage } from "./stage-protocol";
+
+export function useClipPlayer(
+  node: BlockProps<"clip">["node"],
+  send: StageSend,
+): StagePlayer {
+  const markers = node.markers;
+  // What the stage last reported: its markers in time order, its length, the
+  // playhead, and the marker the playhead last reached.
+  const [placed, setPlaced] = useState<PlacedMarker[] | null>(null);
+  const [duration, setDuration] = useState(0);
+  const [at, setAt] = useState(0);
+  const [playing, setPlaying] = useState(false);
+  const [markerKey, setMarkerKey] = useState<string>();
+  const [scenario, setScenario] = useState(node.scenarios?.[0]?.key);
+  const scenarioRef = useRef(scenario);
+  // A new stage (going fullscreen, say) picks up at the marker the last one
+  // showed, playing if it was: until it lands there, what it reports from
+  // time 0 is not news. Asks made before it booted went to the last one.
+  const resumeRef = useRef<{ key: string; playing: boolean }>(undefined);
+
+  // In time order once the stage has placed them, as declared until then.
+  const stops = useMemo(() => {
+    if (!placed) return markers;
+    const byKey = new Map(markers.map((marker) => [marker.key, marker]));
+
+    return placed.flatMap(({ key }) => byKey.get(key) ?? []);
+  }, [markers, placed]);
+
+  const activeIndex = Math.max(
+    0,
+    stops.findIndex((stop) => stop.key === markerKey),
+  );
+
+  const ended = !playing && duration > 0 && at >= duration;
+
+  const pick = (position: number, by: PickedBy) => {
+    const stop = stops[position];
+
+    if (!stop) return;
+
+    // The tour reads a stop at rest; the controls keep playing if it was.
+    if (by === "tour" && playing) {
+      send({ type: "pause" });
+      setPlaying(false);
+    }
+
+    resumeRef.current = undefined;
+    setMarkerKey(stop.key);
+    send({ type: "seek", marker: stop.key });
+  };
+
+  const toggle = () => {
+    if (playing) {
+      send({ type: "pause" });
+      setPlaying(false);
+    } else {
+      send({ type: "play" });
+      setPlaying(true);
+    }
+  };
+
+  const receive = (message: StageMessage) => {
+    const resume = resumeRef.current;
+
+    switch (message.type) {
+      case "clip":
+        setPlaced(message.markers);
+        setDuration(message.duration);
+
+        if (resume && message.markers.some(({ key }) => key === resume.key)) {
+          send({ type: "seek", marker: resume.key });
+
+          if (resume.playing) send({ type: "play" });
+        } else {
+          resumeRef.current = undefined;
+          setMarkerKey(undefined);
+          setPlaying(false);
+        }
+
+        break;
+      case "time":
+        if (resume) break;
+        setAt(message.at);
+        setPlaying(message.playing);
+        break;
+      case "marker":
+        if (resume && message.key !== resume.key) break;
+        resumeRef.current = undefined;
+        setMarkerKey(message.key);
+        break;
+      case "ended":
+        setPlaying(false);
+        break;
+    }
+  };
+
+  // A new stage starts on the scenario the reader had picked, or the first.
+  const boot = () => {
+    const kept =
+      node.scenarios?.find((item) => item.key === scenarioRef.current) ??
+      node.scenarios?.[0];
+
+    scenarioRef.current = kept?.key;
+    setScenario(kept?.key);
+    resumeRef.current = markerKey ? { key: markerKey, playing } : undefined;
+
+    return {
+      mode: "clip" as const,
+      frames: [],
+      markers: markers.map(({ key, title, caption, code }) => ({
+        key,
+        title,
+        caption,
+        code,
+      })),
+      scenarios: node.scenarios?.map((item) => item.key) ?? [],
+      frame: 0,
+      ...(kept && { scenario: kept.key }),
+    };
+  };
+
+  const jump = (event: KeyboardEvent) => {
+    if (event.key === "ArrowRight") pick(activeIndex + 1, "controls");
+    else if (event.key === "ArrowLeft") pick(activeIndex - 1, "controls");
+    else return false;
+
+    event.preventDefault();
+
+    return true;
+  };
+
+  return {
+    stops,
+    activeIndex,
+    pick,
+    boot,
+    receive,
+    scenario,
+    selectScenario(key) {
+      if (key === scenarioRef.current) return;
+      scenarioRef.current = key;
+      resumeRef.current = undefined;
+      setScenario(key);
+      setPlaying(false);
+      send({ type: "scenario", key });
+    },
+    strip: {
+      label: "Markers",
+      items: stops.map((stop) => ({ key: stop.key, text: stop.title })),
+    },
+    afterStage: (
+      <ProgressLine
+        value={duration > 0 ? at / duration : 0}
+        ticks={
+          duration > 0 ? (placed ?? []).map((item) => item.at / duration) : []
+        }
+      />
+    ),
+    onKeyDown: jump,
+    // Space plays or pauses when the figure itself has focus; a focused
+    // button keeps Space for itself.
+    onFigureKeyDown(event) {
+      if (event.target !== event.currentTarget) return;
+
+      if (event.key === " ") {
+        event.preventDefault();
+        toggle();
+      } else jump(event);
+    },
+    controls: (
+      <>
+        <ControlButton
+          label={playing ? "Pause" : ended ? "Replay" : "Play"}
+          onClick={toggle}
+        >
+          {playing ? pauseIcon : playIcon}
+        </ControlButton>
+        <StopCaption stop={stops[activeIndex]} />
+      </>
+    ),
+  };
+}
diff --git a/packages/review/app/src/animation/frame-player.tsx b/packages/review/app/src/animation/frame-player.tsx
new file mode 100644
index 0000000000..14a8623c92
--- /dev/null
+++ b/packages/review/app/src/animation/frame-player.tsx
@@ -0,0 +1,348 @@
+// An animation's frames: the reader steps through them, or plays them, each
+// held for its duration and until the stage says its motion settled.
+
+import type { BlockProps } from "@canvas/blocks";
+import { radius, space } from "@canvas/scale.stylex";
+import { tokens } from "@canvas/tokens.stylex";
+import { useTooltip } from "@canvas/ui/tooltip";
+import * as stylex from "@stylexjs/stylex";
+import {
+  type KeyboardEvent,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import {
+  ControlButton,
+  StopCaption,
+  pauseIcon,
+  playIcon,
+} from "./stage-controls";
+import type { StagePlayer, StageSend } from "./stage-player";
+import type { StageMessage } from "./stage-protocol";
+
+const DEFAULT_DURATION = 3000;
+
+const sameKeys = (left: readonly string[], right: readonly string[] | null) =>
+  right?.length === left.length && left.every((key, i) => key === right[i]);
+
+export function useFramePlayer(
+  node: BlockProps<"animation">["node"],
+  send: StageSend,
+): StagePlayer {
+  const frames = node.frames;
+  const [index, setIndex] = useState(0);
+  const [sequenceKeys, setSequenceKeys] = useState<string[] | null>(null);
+  const sequenceRef = useRef<string[] | null>(null);
+  const [playing, setPlaying] = useState(false);
+  const [settled, setSettled] = useState(-1);
+  const [timeUp, setTimeUp] = useState(-1);
+  const indexRef = useRef(index);
+  indexRef.current = index;
+
+  const activeFrames = useMemo(() => {
+    if (!sequenceKeys) return frames;
+    const byKey = new Map(frames.map((item) => [item.key, item]));
+
+    return sequenceKeys.flatMap((key) => {
+      const item = byKey.get(key);
+
+      return item ? [item] : [];
+    });
+  }, [frames, sequenceKeys]);
+
+  const last = activeFrames.length - 1;
+  const frame = frames[Math.min(index, frames.length - 1)]!;
+
+  const activeIndex = Math.max(
+    0,
+    activeFrames.findIndex((item) => item.key === frame.key),
+  );
+
+  const go = useCallback(
+    (target: number, instant: boolean) => {
+      const keys = sequenceRef.current;
+
+      const path = keys
+        ? keys.flatMap((key) => {
+            const item = frames.find((candidate) => candidate.key === key);
+
+            return item ? [item] : [];
+          })
+        : frames;
+
+      const currentKey = frames[indexRef.current]?.key;
+      const currentPosition = path.findIndex((item) => item.key === currentKey);
+      const position = Math.max(0, Math.min(path.length - 1, target));
+      const next = frames.findIndex((item) => item.key === path[position]?.key);
+
+      if (next < 0 || next === indexRef.current) return;
+      setIndex(next);
+      send({
+        type: "frame",
+        index: next,
+        instant,
+        direction:
+          currentPosition < 0 || position === currentPosition
+            ? "none"
+            : position > currentPosition
+              ? "forward"
+              : "backward",
+        adjacent: currentPosition >= 0 && position === currentPosition + 1,
+      });
+    },
+    [frames, send],
+  );
+
+  // A stage script's setSequence() and the scenario picker both land here.
+  const selectSequence = (keys: string[]) => {
+    const unique = new Set(keys);
+
+    const valid =
+      unique.size === keys.length &&
+      keys.every((key) => frames.some((frame) => frame.key === key));
+
+    if (!valid) return;
+
+    if (
+      sequenceRef.current?.length === keys.length &&
+      sequenceRef.current.every((key, index) => key === keys[index])
+    )
+      return;
+
+    sequenceRef.current = keys;
+    setSequenceKeys(keys);
+    setPlaying(false);
+    setTimeUp(-1);
+    const currentKey = frames[indexRef.current]?.key;
+
+    const fallback = frames.findIndex((frame) => frame.key === keys[0]);
+
+    const next = keys.includes(currentKey) ? indexRef.current : fallback;
+
+    if (next !== indexRef.current) setIndex(next);
+
+    // Refresh even a preserved key: lifecycle ranges, held scene changes,
+    // and its timeline can differ when active order changes.
+    send({
+      type: "frame",
+      index: next,
+      instant: true,
+      direction: "none",
+      adjacent: false,
+    });
+  };
+
+  const receive = (message: StageMessage) => {
+    switch (message.type) {
+      case "settled":
+        setSettled(message.index);
+        break;
+      case "goto": {
+        const keys = sequenceRef.current;
+        const path = keys ?? frames.map((item) => item.key);
+        go(path.indexOf(message.key), true);
+        break;
+      }
+
+      case "step": {
+        const keys = sequenceRef.current;
+        const path = keys ?? frames.map((item) => item.key);
+        const currentKey = frames[indexRef.current]?.key;
+        go(path.indexOf(currentKey) + message.delta, false);
+        break;
+      }
+
+      case "sequence":
+        selectSequence(message.keys);
+        break;
+    }
+  };
+
+  // A new stage starts in the scenario the reader had picked, or the first.
+  const boot = () => {
+    const sequence =
+      (
+        node.scenarios?.find((scenario) =>
+          sameKeys(scenario.frames, sequenceRef.current),
+        ) ?? node.scenarios?.[0]
+      )?.frames ?? null;
+
+    sequenceRef.current = sequence;
+    setSequenceKeys(sequence);
+
+    if (sequence && !sequence.includes(frames[indexRef.current]!.key)) {
+      indexRef.current = frames.findIndex((item) => item.key === sequence[0]);
+      setIndex(indexRef.current);
+    }
+
+    return {
+      mode: "frames" as const,
+      frames: frames.map(({ key, title, caption, data, code }) => ({
+        key,
+        title,
+        caption,
+        data,
+        code,
+      })),
+      markers: [],
+      scenarios: [],
+      frame: indexRef.current,
+      ...(sequence && { sequence }),
+    };
+  };
+
+  // Play: hold each active-sequence frame for its duration and until its motion ends.
+  useEffect(() => {
+    if (!playing) return;
+
+    const timer = setTimeout(
+      () => setTimeUp(index),
+      frame.duration ?? DEFAULT_DURATION,
+    );
+
+    return () => clearTimeout(timer);
+  }, [playing, index, frame.duration]);
+
+  useEffect(() => {
+    if (!playing || timeUp !== index || settled !== index) return;
+
+    if (activeIndex >= last) setPlaying(false);
+    else go(activeIndex + 1, false);
+  }, [playing, timeUp, settled, index, activeIndex, last, go]);
+
+  // An edit can drop frames or a sequence selection from under the current one.
+  useEffect(() => {
+    if (!activeFrames.some((item) => item.key === frame.key)) go(0, true);
+  }, [activeFrames, frame.key, go]);
+
+  const pick = (position: number) =>
+    go(position, Math.abs(position - activeIndex) > 1);
+
+  const steps = activeFrames.every((item) => item.label) ? activeFrames : null;
+
+  return {
+    stops: activeFrames,
+    activeIndex,
+    pick,
+    boot,
+    receive,
+    scenario: node.scenarios?.find((scenario) =>
+      sameKeys(scenario.frames, sequenceKeys),
+    )?.key,
+    selectScenario(key) {
+      const keys = node.scenarios?.find(
+        (scenario) => scenario.key === key,
+      )?.frames;
+
+      if (!keys) return;
+      send({ type: "sequence", keys });
+      selectSequence(keys);
+    },
+    strip: steps && {
+      label: "Steps",
+      items: steps.map((item) => ({ key: item.key, text: item.label! })),
+    },
+    onKeyDown(event: KeyboardEvent) {
+      if (event.key === "ArrowRight") go(activeIndex + 1, false);
+      else if (event.key === "ArrowLeft") go(activeIndex - 1, false);
+      else return;
+
+      event.preventDefault();
+    },
+    controls: (
+      <>
+        <ControlButton
+          label="Previous frame"
+          disabled={activeIndex === 0}
+          onClick={() => go(activeIndex - 1, false)}
+        >
+          <path d="M14.5 6.5 9 12l5.5 5.5" />
+        </ControlButton>
+        <ControlButton
+          label={playing ? "Pause" : activeIndex >= last ? "Replay" : "Play"}
+          onClick={() => {
+            if (playing) return setPlaying(false);
+
+            if (activeIndex >= last) go(0, true);
+
+            setPlaying(true);
+          }}
+        >
+          {playing ? pauseIcon : playIcon}
+        </ControlButton>
+        <ControlButton
+          label="Next frame"
+          disabled={activeIndex >= last}
+          onClick={() => go(activeIndex + 1, false)}
+        >
+          <path d="M9.5 6.5 15 12l-5.5 5.5" />
+        </ControlButton>
+        <StopCaption stop={frame} />
+        {!steps && (
+          <div {...stylex.props(styles.dots)} role="group" aria-label="Frames">
+            {activeFrames.map((item, position) => (
+              <FrameDot
+                key={item.key}
+                title={item.title}
+                current={position === activeIndex}
+                onClick={() => pick(position)}
+              />
+            ))}
+          </div>
+        )}
+      </>
+    ),
+  };
+}
+
+function FrameDot({
+  title,
+  current,
+  onClick,
+}: {
+  title: string;
+  current: boolean;
+  onClick(): void;
+}) {
+  const tooltip = useTooltip(title, { instant: true });
+
+  return (
+    <button
+      ref={tooltip}
+      type="button"
+      aria-label={title}
+      aria-current={current ? "step" : undefined}
+      onClick={onClick}
+      {...stylex.props(styles.dot, current && styles.dotCurrent)}
+    />
+  );
+}
+
+const styles = stylex.create({
+  dots: {
+    display: "flex",
+    flex: "0 0 auto",
+    gap: space.s6,
+  },
+  dot: {
+    width: "8px",
+    height: "8px",
+    padding: 0,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: tokens.inkFaint,
+    borderRadius: radius.round,
+    backgroundColor: tokens.transparent,
+    cursor: "pointer",
+    outline: { default: null, ":focus-visible": `1px solid ${tokens.accent}` },
+    outlineOffset: "2px",
+  },
+  dotCurrent: {
+    borderColor: tokens.accent,
+    backgroundColor: tokens.accent,
+  },
+});
diff --git a/packages/review/app/src/animation/references.browser.test.tsx b/packages/review/app/src/animation/references.browser.test.tsx
index ddb6da40c8..36791e4529 100644
--- a/packages/review/app/src/animation/references.browser.test.tsx
+++ b/packages/review/app/src/animation/references.browser.test.tsx
@@ -1,6 +1,7 @@
 // Every reference animation under packages/review/instructions/animations
 // runs here as a reader would see it: mounted on a board, stepped through
-// every frame of every scenario, with no script error. Set
+// every frame of every scenario, with no script error. A reference clip
+// jumps to each marker of every scenario, then plays to its end. Set
 // VITE_ANIMATION_SHOTS=1 to save a screenshot of each frame under
 // __screenshots__/references/<name>/<path>/ beside this file (gitignored),
 // the way an author looks at their work without opening Desktop:
@@ -36,13 +37,24 @@ const ANCHOR = "head/order.ts#L1";
 
 const shots = Boolean(import.meta.env.VITE_ANIMATION_SHOTS);
 
-interface Reference {
+interface AnimationReference {
+  kind: "animation";
   name: string;
   block: JsonObject;
   frames: { key: string; title: string }[];
   scenarios: { key: string; label: string; frames: string[] }[] | undefined;
 }
 
+interface ClipReference {
+  kind: "clip";
+  name: string;
+  block: JsonObject;
+  markers: { key: string; title: string }[];
+  scenarios: { key: string; label: string }[] | undefined;
+}
+
+type Reference = AnimationReference | ClipReference;
+
 function readReferences(): Reference[] {
   const folders = new Map<string, Record<string, string>>();
 
@@ -51,7 +63,7 @@ function readReferences(): Reference[] {
     folders.set(name, { ...folders.get(name), [base]: text });
   }
 
-  return [...folders].flatMap(([name, folder]) => {
+  return [...folders].flatMap(([name, folder]): Reference[] => {
     if (!("animation.html" in folder)) return [];
 
     const block = parseJsonText(folder["block.json"] ?? "{}");
@@ -69,25 +81,40 @@ function readReferences(): Reference[] {
       : {};
 
     const scenariosText = folder["scenarios.json"];
+    const markersText = folder["markers.json"];
 
     const raw: JsonObject = {
       id: `reference-${name}`,
-      type: "animation",
+      type: markersText ? "clip" : "animation",
       ...block,
       code,
       html: folder["animation.html"]!,
-      frames: parseJsonText(folder["frames.json"] ?? "[]"),
+      ...(markersText
+        ? { markers: parseJsonText(markersText) }
+        : { frames: parseJsonText(folder["frames.json"] ?? "[]") }),
       ...(scenariosText && { scenarios: parseJsonText(scenariosText) }),
       pins: { repositoryId: "repo", base: "base", head: "head" },
     };
 
     const [parsed] = documentSchema.parse([raw]);
 
+    if (parsed?.type === "clip")
+      return [
+        {
+          kind: "clip" as const,
+          name,
+          block: raw,
+          markers: parsed.markers,
+          scenarios: parsed.scenarios,
+        },
+      ];
+
     if (parsed?.type !== "animation")
-      throw new Error(`${name}: not an animation`);
+      throw new Error(`${name}: not an animation or clip`);
 
     return [
       {
+        kind: "animation" as const,
         name,
         block: raw,
         frames: parsed.frames,
@@ -198,7 +225,7 @@ async function shoot(
 
 async function stepThrough(
   container: HTMLElement,
-  reference: Reference,
+  reference: AnimationReference,
   path: string,
   keys: string[],
 ) {
@@ -230,6 +257,76 @@ async function stepThrough(
   expect(next().disabled, `${path}: next past the last frame`).toBe(true);
 }
 
+/** Jumps to each marker through the Markers strip, then plays the clip from
+ * its start to its end. */
+async function playThrough(
+  container: HTMLElement,
+  reference: ClipReference,
+  path: string,
+) {
+  const strip = () => [
+    ...container.querySelectorAll<HTMLButtonElement>(
+      "[role='group'][aria-label='Markers'] button",
+    ),
+  ];
+
+  const count = reference.markers.length;
+
+  // The strip lists the markers in time order, so walk it by position.
+  for (let position = 0; position < count; position++) {
+    const button = strip()[position];
+
+    expect(button, `${path}: marker ${position + 1}`).toBeTruthy();
+    await act(async () => button!.click());
+    await shown(container, position, count);
+    await shoot(
+      container,
+      reference,
+      path,
+      `${position + 1}-${button!.textContent?.replace(/^\d+/, "")}`,
+    );
+  }
+
+  await act(async () => strip()[0]!.click());
+  await shown(container, 0, count);
+
+  // Back at the start, the button reads Play once the stage says so.
+  const play = await settled(() =>
+    container.querySelector<HTMLButtonElement>("button[aria-label='Play']"),
+  );
+
+  expect(play, `${path}: play`).toBeTruthy();
+  await act(async () => play!.click());
+  expect(
+    await settled(
+      () =>
+        container.querySelector("button[aria-label='Replay']") ||
+        alertIn(container),
+      30_000,
+    ),
+    `${path}: plays to its end`,
+  ).toBeTruthy();
+  expect(alertIn(container)).toBeNull();
+  expect(text(container)).toContain(`${count} / ${count}`);
+}
+
+/** Plays a clip through, in each of its scenarios. */
+async function playScenarios(container: HTMLElement, reference: ClipReference) {
+  if (!reference.scenarios) return playThrough(container, reference, "all");
+
+  for (const scenario of reference.scenarios) {
+    const option = [
+      ...container.querySelectorAll<HTMLButtonElement>(
+        "[role='group'][aria-label='Scenario'] button",
+      ),
+    ].find((button) => button.textContent === scenario.label);
+
+    expect(option, `scenario ${scenario.label}`).toBeTruthy();
+    await act(async () => option!.click());
+    await playThrough(container, reference, scenario.key);
+  }
+}
+
 describe.skipIf(!references.length)("reference animations", () => {
   it.each(references.map((reference) => [reference.name, reference] as const))(
     "%s runs every frame of every scenario without an error",
@@ -240,6 +337,8 @@ describe.skipIf(!references.length)("reference animations", () => {
         await settled(() => container.querySelector("iframe")),
       ).toBeTruthy();
 
+      if (reference.kind === "clip") return playScenarios(container, reference);
+
       if (!reference.scenarios) {
         await stepThrough(
           container,
diff --git a/packages/review/app/src/animation/stage-controls.tsx b/packages/review/app/src/animation/stage-controls.tsx
new file mode 100644
index 0000000000..95e6f8728f
--- /dev/null
+++ b/packages/review/app/src/animation/stage-controls.tsx
@@ -0,0 +1,162 @@
+// The pieces under an animation's or clip's stage: icon buttons, the caption
+// of the stop showing, and the strip of named stops.
+
+import { fontSize, leading, space, tracking } from "@canvas/scale.stylex";
+import { tokens } from "@canvas/tokens.stylex";
+import { IconButton } from "@canvas/ui/button";
+import { useTooltip } from "@canvas/ui/tooltip";
+import * as stylex from "@stylexjs/stylex";
+import type { KeyboardEvent, ReactNode } from "react";
+
+import type { PlayerStop } from "./stage-player";
+
+export function ControlButton({
+  label,
+  disabled,
+  onClick,
+  children,
+}: {
+  label: string;
+  disabled?: boolean;
+  onClick(): void;
+  children: ReactNode;
+}) {
+  const tooltip = useTooltip(label, { quick: true });
+
+  return (
+    <IconButton
+      ref={tooltip}
+      aria-label={label}
+      size="small"
+      disabled={disabled}
+      onClick={onClick}
+    >
+      <svg
+        aria-hidden="true"
+        focusable="false"
+        viewBox="0 0 24 24"
+        {...stylex.props(styles.icon)}
+      >
+        {children}
+      </svg>
+    </IconButton>
+  );
+}
+
+export const playIcon = <path d="M8.5 6.5v11l9-5.5z" />;
+
+export const pauseIcon = <path d="M9 6.5v11M15 6.5v11" />;
+
+/** The title and caption of the stop showing, read out as it changes. */
+export function StopCaption({ stop }: { stop: PlayerStop | undefined }) {
+  return (
+    <div {...stylex.props(styles.caption)} aria-live="polite">
+      {stop && <strong data-review-copy-prose>{stop.title}</strong>}
+      {stop?.caption && <span data-review-copy-prose> {stop.caption}</span>}
+    </div>
+  );
+}
+
+/** A named step per stop, like a progress strip. */
+export function StepStrip({
+  label,
+  items,
+  activeIndex,
+  onPick,
+  onKeyDown,
+}: {
+  label: string;
+  items: { key: string; text: string }[];
+  activeIndex: number;
+  onPick(position: number): void;
+  onKeyDown(event: KeyboardEvent): void;
+}) {
+  return (
+    <div
+      {...stylex.props(styles.steps)}
+      role="group"
+      aria-label={label}
+      onKeyDown={onKeyDown}
+    >
+      {items.map((item, position) => (
+        <button
+          key={item.key}
+          type="button"
+          aria-current={position === activeIndex ? "step" : undefined}
+          onClick={() => onPick(position)}
+          {...stylex.props(
+            styles.step,
+            position === activeIndex && styles.stepCurrent,
+          )}
+        >
+          <span {...stylex.props(styles.stepIndex)}>{position + 1}</span>
+          <span data-review-copy-prose>{item.text}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
+
+const styles = stylex.create({
+  icon: {
+    width: "16px",
+    height: "16px",
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 1.6,
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+  },
+  caption: {
+    flex: "1 1 auto",
+    minWidth: 0,
+    marginLeft: space.s6,
+    paddingBlock: space.s8,
+    color: tokens.inkMuted,
+    lineHeight: leading.px18,
+  },
+  steps: {
+    display: { default: "flex", [stylex.env.narrow]: "grid" },
+    gridTemplateColumns: {
+      default: null,
+      [stylex.env.narrow]: "repeat(4, minmax(0, 1fr))",
+    },
+    overflowX: { default: "auto", [stylex.env.narrow]: "visible" },
+    borderTopWidth: "1px",
+    borderTopStyle: "solid",
+    borderTopColor: tokens.rule,
+  },
+  step: {
+    display: "flex",
+    flex: "1 1 0",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: space.s4,
+    minWidth: { default: "fit-content", [stylex.env.narrow]: 0 },
+    padding: {
+      default: `${space.s6} ${space.s10}`,
+      [stylex.env.narrow]: `${space.s6} ${space.s4}`,
+    },
+    borderStyle: "none",
+    borderBottomWidth: "2px",
+    borderBottomStyle: "solid",
+    borderBottomColor: tokens.transparent,
+    backgroundColor: tokens.transparent,
+    color: tokens.inkMuted,
+    font: `${fontSize.micro} ${tokens.fontMono}`,
+    letterSpacing: tracking.chrome,
+    textAlign: "center",
+    textTransform: "uppercase",
+    whiteSpace: { default: "nowrap", [stylex.env.narrow]: "normal" },
+    cursor: "pointer",
+    outline: { default: null, ":focus-visible": `1px solid ${tokens.accent}` },
+    outlineOffset: "-2px",
+  },
+  stepCurrent: {
+    borderBottomColor: tokens.accent,
+    color: tokens.ink,
+  },
+  stepIndex: {
+    color: "inherit",
+  },
+});
diff --git a/packages/review/app/src/animation/stage-player.ts b/packages/review/app/src/animation/stage-player.ts
new file mode 100644
index 0000000000..47ed6cc311
--- /dev/null
+++ b/packages/review/app/src/animation/stage-player.ts
@@ -0,0 +1,58 @@
+// What differs between an animation, whose reader steps through frames, and
+// a clip, whose reader plays one timeline and jumps between its markers. The
+// block around either (the stage, its slots, the tour, painting in) is the
+// same; each kind supplies one of these.
+
+import type { KeyboardEvent, ReactNode } from "react";
+
+import type { HostMessage, StageInit, StageMessage } from "./stage-protocol";
+
+/** One stop of the path showing: a frame, or one of a clip's markers. */
+export interface PlayerStop {
+  key: string;
+  title: string;
+  caption?: string;
+  /** The code names the stop lists, for its tour stop. */
+  code?: string[];
+}
+
+/** Who picked a stop: the controls under the stage, or the tour. */
+export type PickedBy = "controls" | "tour";
+
+export type StageSend = (message: HostMessage) => void;
+
+export interface StagePlayer {
+  /** The stops of the path showing, in order. */
+  stops: readonly PlayerStop[];
+  /** The stop showing, in `stops`. */
+  activeIndex: number;
+  /** Show the stop at `position`, as the reader asked through `by`. */
+  pick(position: number, by: PickedBy): void;
+  /** The kind's part of a new stage's first message; resets what the last
+   * stage reported. */
+  boot(): Pick<
+    StageInit,
+    | "mode"
+    | "frames"
+    | "markers"
+    | "scenarios"
+    | "frame"
+    | "sequence"
+    | "scenario"
+  >;
+  /** A message only this kind's stage sends. */
+  receive(message: StageMessage): void;
+  /** The scenario showing, by key. */
+  scenario: string | undefined;
+  selectScenario(key: string): void;
+  /** The strip of named stops under the stage, when there is one. */
+  strip: { label: string; items: { key: string; text: string }[] } | null;
+  /** Drawn right under the stage. */
+  afterStage?: ReactNode;
+  /** The footer's controls and caption. */
+  controls: ReactNode;
+  /** Keys pressed in the strip or the controls. */
+  onKeyDown(event: KeyboardEvent): void;
+  /** Keys pressed on the figure itself, which takes focus when set. */
+  onFigureKeyDown?(event: KeyboardEvent): void;
+}
diff --git a/packages/review/app/src/animation/stage-protocol.ts b/packages/review/app/src/animation/stage-protocol.ts
index b32d3059b0..254f54325f 100644
--- a/packages/review/app/src/animation/stage-protocol.ts
+++ b/packages/review/app/src/animation/stage-protocol.ts
@@ -16,16 +16,39 @@ export interface StageFrame {
   code?: string[];
 }
 
+/** What the stage's script reads about one of a clip's markers. */
+export interface StageMarker {
+  key: string;
+  title: string;
+  caption?: string;
+  /** The code names the marker lists. */
+  code?: string[];
+}
+
+/** A placed marker: where it sits on the active timeline, in milliseconds. */
+export interface PlacedMarker {
+  key: string;
+  at: number;
+}
+
 export type StageColorScheme = "light" | "dark";
 
 /** The first message on the port: everything the stage needs to draw. */
 export interface StageInit {
   type: "init";
+  /** An animation's frames, stepped through, or a clip's one timeline,
+   * played. */
+  mode: "frames" | "clip";
   html: string;
   /** The style kit: the CSS every stage loads before its markup. */
   kit: string;
   autoSize: boolean;
+  /** An animation's frames; empty for a clip. */
   frames: StageFrame[];
+  /** A clip's markers, as declared; empty for an animation. */
+  markers: StageMarker[];
+  /** A clip's scenario keys, which whiteboard.clip() accepts. */
+  scenarios: string[];
   /** The names whiteboard.code() accepts. */
   code: string[];
   /** What hovering an element that opens each code says. */
@@ -49,6 +72,8 @@ export interface StageInit {
   frame: number;
   /** The scenario the reader picked: the frame keys the stage starts on. */
   sequence?: string[];
+  /** The clip scenario the reader picked: the timeline the stage starts on. */
+  scenario?: string;
   /** Library sources the stage runs before its own scripts: anime.js. */
   libraries: string[];
 }
@@ -72,7 +97,14 @@ export type HostMessage =
   /** The reader picked a scenario: play these frame keys, in order. */
   | { type: "sequence"; keys: string[] }
   /** The board's turn to draw this block came: paint the first frame in. */
-  | { type: "paint" };
+  | { type: "paint" }
+  /** A clip: play from the playhead, or from the start at the end. */
+  | { type: "play" }
+  | { type: "pause" }
+  /** A clip: land on a marker, still playing if it was. */
+  | { type: "seek"; marker: string }
+  /** A clip: the reader picked a scenario, a timeline of its own. */
+  | { type: "scenario"; key: string };
 
 /** The tallest an auto-sized stage may report itself. */
 export const STAGE_MAX_HEIGHT = 4000;
@@ -116,6 +148,30 @@ export const stageMessageSchema = z.discriminatedUnion("type", [
   }),
   /** Every animation the frame started has finished. */
   z.strictObject({ type: z.literal("settled"), index: z.number().int() }),
+  /** A clip's timeline is built: its length and every placed marker, by
+   * time. Sent again on a scenario change. */
+  z.strictObject({
+    type: z.literal("clip"),
+    duration: z.number().finite().nonnegative(),
+    markers: z
+      .array(
+        z.strictObject({
+          key: z.string(),
+          at: z.number().finite().nonnegative(),
+        }),
+      )
+      .max(60),
+  }),
+  /** A clip's playhead, while it plays and whenever it stops or jumps. */
+  z.strictObject({
+    type: z.literal("time"),
+    at: z.number().finite().nonnegative(),
+    playing: z.boolean(),
+  }),
+  /** A clip's playhead reached this marker. */
+  z.strictObject({ type: z.literal("marker"), key: z.string() }),
+  /** A clip played to its end and paused there. */
+  z.strictObject({ type: z.literal("ended") }),
   /** The first frame has painted in, after a `paint` message. */
   z.strictObject({ type: z.literal("painted") }),
   z.strictObject({ type: z.literal("goto"), key: z.string() }),
diff --git a/packages/review/app/src/animation/stage-reference.ts b/packages/review/app/src/animation/stage-reference.ts
index 5b21b2b171..9ba9db0d52 100644
--- a/packages/review/app/src/animation/stage-reference.ts
+++ b/packages/review/app/src/animation/stage-reference.ts
@@ -6,9 +6,13 @@
 import type * as Reference from "../../../instructions/whiteboard";
 import type {
   ArrowOptions,
+  ClipMarker,
+  ClipTimeline,
   FrameChange,
   FrameTimeline,
+  MarkerChange,
   PaintChange,
+  ReachedMarker,
   Scene,
   SceneCardOptions,
   SceneChange,
@@ -39,6 +43,10 @@ export type StageReferenceChecks = [
   Check<Matches<FrameChange, Reference.FrameChange>>,
   Check<Matches<FrameTimeline, Reference.FrameTimeline>>,
   Check<Matches<PaintChange, Reference.PaintChange>>,
+  Check<Matches<ClipTimeline, Reference.ClipTimeline>>,
+  Check<Matches<MarkerChange, Reference.MarkerChange>>,
+  Check<Matches<ClipMarker, Reference.Marker>>,
+  Check<Matches<ReachedMarker, Reference.ReachedMarker>>,
   Check<Matches<Scene, Reference.Scene>>,
   Check<Matches<SceneOptions, Reference.SceneOptions>>,
   Check<Matches<SceneCardOptions, Reference.SceneCardOptions>>,
diff --git a/packages/review/app/src/animation/stage-runtime.ts b/packages/review/app/src/animation/stage-runtime.ts
index d7821e4792..0bb1a8d0f7 100644
--- a/packages/review/app/src/animation/stage-runtime.ts
+++ b/packages/review/app/src/animation/stage-runtime.ts
@@ -8,10 +8,12 @@ import type {
 
 import type {
   HostMessage,
+  PlacedMarker,
   SlotLayout,
   StageColorScheme,
   StageFrame,
   StageInit,
+  StageMarker,
   StageMessage,
 } from "./stage-protocol";
 
@@ -35,10 +37,29 @@ type FrameResult = void | Animation | readonly Animation[] | Promise<void>;
 
 type FrameHandler = (change: FrameChange) => FrameResult;
 
+/** A clip's marker as its script reads it: declared, then placed in time. */
+export type ClipMarker = StageMarker & {
+  /** Milliseconds into the active timeline, once the scripts have run. */
+  at?: number;
+};
+
+/** A marker the playhead has reached: placed, with its place in time order. */
+export type ReachedMarker = StageMarker & { at: number; index: number };
+
+/** What a marker handler learns as a clip's playhead reaches its marker. */
+export interface MarkerChange {
+  marker: ReachedMarker;
+  /** A jump, the first draw, or reduced motion: draw the end state at once. */
+  instant: boolean;
+}
+
+type MarkerHandler = (change: MarkerChange) => FrameResult;
+
 /** What a paint handler learns when the block paints its first frame in. */
 export interface PaintChange {
-  /** The first frame, already drawn in its end state. */
-  frame: StageFrame & { index: number };
+  /** The first frame, already drawn in its end state; absent in a clip,
+   * which paints in at time 0. */
+  frame?: StageFrame & { index: number };
   /** Skip motion and leave everything in its end state: the block loaded
    * without painting, or the reader prefers reduced motion. */
   instant: boolean;
@@ -218,6 +239,24 @@ export interface FrameTimeline {
   call(callback: () => void, position?: TimelinePosition): FrameTimeline;
 }
 
+/** A clip's one timeline, or one scenario's. Numeric positions count from
+ * the timeline's start; strings are anime.js positions. */
+export interface ClipTimeline {
+  add(
+    targets: TargetsParam,
+    params: AnimationParams,
+    position?: TimelinePosition,
+  ): ClipTimeline;
+  set(
+    targets: TargetsParam,
+    params: AnimationParams,
+    position?: TimelinePosition,
+  ): ClipTimeline;
+  call(callback: () => void, position?: TimelinePosition): ClipTimeline;
+  /** Place a declared marker at the timeline's end so far, or at `position`. */
+  marker(key: string, position?: TimelinePosition): ClipTimeline;
+}
+
 /** The global `whiteboard` the stage's scripts call. */
 export interface WhiteboardShim {
   readonly frames: readonly (StageFrame & { index: number })[];
@@ -235,6 +274,8 @@ export interface WhiteboardShim {
   on(key: "paint", handler: PaintHandler): () => void;
   /** Run when a frame shows; "*" runs on every frame. */
   on(key: string, handler: FrameHandler): () => void;
+  /** In a clip: run when the playhead reaches the marker; "*" on every one. */
+  on(key: string, handler: MarkerHandler): () => void;
   /** element.animate that holds its end state and honors instant changes. */
   animate(
     target: Element | string,
@@ -262,6 +303,13 @@ export interface WhiteboardShim {
    * steps into the frame, and lands at its end on a jump. "paint" is a
    * timeline of its own that plays once as the block paints in. */
   timeline(key: string): FrameTimeline;
+  /** A clip's timeline, or a scenario's: built while the scripts first run,
+   * once per key. Without a key, the timeline of scenarios with none. */
+  clip(scenario?: string): ClipTimeline;
+  /** A clip's declared markers, each with its time once placed. */
+  readonly markers: readonly ClipMarker[];
+  /** The marker a clip's playhead last reached. */
+  readonly marker: ReachedMarker | undefined;
   /** An SVG arrow between two elements that follows them as they move. */
   arrow(from: CardRef, to: CardRef, options?: ArrowOptions): SVGGElement;
   /** A dot, or a pill with a label, that travel() moves along arrows.
@@ -326,6 +374,8 @@ export function stageRuntime(port: MessagePort): void {
   let instantMode = false;
   let activeSequence: string[] | undefined;
   const handlers = new Map<string, Set<FrameHandler>>();
+  // A clip's handlers, by marker key.
+  const markerHandlers = new Map<string, Set<MarkerHandler>>();
   const paintHandlers = new Set<PaintHandler>();
   let theme: Record<string, string> = {};
   let colorScheme: StageColorScheme = "dark";
@@ -340,11 +390,25 @@ export function stageRuntime(port: MessagePort): void {
   // jump lands on the right one.
   const sceneAppliers: ((key: string) => void)[] = [];
 
+  const clipMode = () => init?.mode === "clip";
+
+  // A clip's active timeline, its placed markers in time order, and the one
+  // its playhead last reached.
+  let clipTimeline: Timeline | undefined;
+  let clipMarkers: PlacedMarker[] = [];
+  let lastMarker = -1;
+
   const declaredFrames = () =>
     (init?.frames ?? []).map((frame, index) => ({ ...frame, index }));
 
-  const frameIndex = (key: string) =>
-    (init?.frames ?? []).findIndex((frame) => frame.key === key);
+  // The keys element states and scene changes name: an animation's frames,
+  // or a clip's markers.
+  const declaredKeys = () =>
+    clipMode()
+      ? (init?.markers ?? []).map((marker) => marker.key)
+      : (init?.frames ?? []).map((frame) => frame.key);
+
+  const frameIndex = (key: string) => declaredKeys().indexOf(key);
 
   const activeFrames = () => {
     const declared = declaredFrames();
@@ -360,8 +424,17 @@ export function stageRuntime(port: MessagePort): void {
     return ordered.map((frame, index) => ({ ...frame, index }));
   };
 
+  // A clip's markers order by time on the active timeline.
   const activeFrameIndex = (key: string) =>
-    activeFrames().findIndex((frame) => frame.key === key);
+    clipMode()
+      ? clipMarkers.findIndex((marker) => marker.key === key)
+      : activeFrames().findIndex((frame) => frame.key === key);
+
+  // The frame showing, or the marker a clip's playhead last reached.
+  const currentKey = () =>
+    clipMode()
+      ? (clipMarkers[lastMarker]?.key ?? "")
+      : (init?.frames[current]?.key ?? "");
 
   const nextFrame = () =>
     new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
@@ -530,7 +603,7 @@ export function stageRuntime(port: MessagePort): void {
   // their exit frame; data-only shows them during the frames it lists. A
   // state, not an event, so a jump lands right.
   const applyStates = () => {
-    const key = init?.frames[current]?.key ?? "";
+    const key = currentKey();
 
     document
       .querySelectorAll<HTMLElement | SVGElement>("[data-highlight]")
@@ -544,11 +617,10 @@ export function stageRuntime(port: MessagePort): void {
     document
       .querySelectorAll<HTMLElement | SVGElement>("[data-enter], [data-exit]")
       .forEach((element) => {
+        // Before a clip's first marker, the position is -1.
         const position = activeFrameIndex(key);
-
-        const enter = element.dataset.enter
-          ? activeFrameIndex(element.dataset.enter)
-          : 0;
+        const enterKey = element.dataset.enter;
+        const enter = enterKey ? activeFrameIndex(enterKey) : -1;
 
         const exit = element.dataset.exit
           ? activeFrameIndex(element.dataset.exit)
@@ -557,7 +629,7 @@ export function stageRuntime(port: MessagePort): void {
         // An enter boundary outside this path never occurs. An exit boundary
         // outside it never ends an element that has already entered.
         element.dataset.wbState =
-          enter < 0 || position < enter
+          (enterKey && enter < 0) || position < enter
             ? "before"
             : exit >= 0 && position >= exit
               ? "after"
@@ -643,6 +715,11 @@ export function stageRuntime(port: MessagePort): void {
   const isPaint = (key: string) => key === "paint" && frameIndex(key) < 0;
 
   const frameTimeline = (key: string): FrameTimeline => {
+    if (clipMode() && !isPaint(key))
+      throw new Error(
+        `A clip has no frames, so timeline("${key}"), travel() and scene.send() do not apply: build the clip's timeline with whiteboard.clip() and place its markers with .marker().`,
+      );
+
     if (!isPaint(key) && frameIndex(key) < 0)
       throw new Error(`Unknown frame "${key}".`);
 
@@ -812,6 +889,358 @@ export function stageRuntime(port: MessagePort): void {
     });
   };
 
+  // A clip is one timeline per scenario, queued while the scripts run as
+  // frame timelines are, with its markers as labels. Only the active one is
+  // built: anime.js lets a later animation take over an earlier one's
+  // properties, so the inactive timelines must not exist side by side.
+  type ClipEntry =
+    | Entry
+    | { kind: "marker"; key: string; position?: TimelinePosition };
+
+  // By scenario key; "" is the timeline built without one.
+  const clipQueued = new Map<string, ClipEntry[]>();
+
+  const clipBuilder = (scenario?: string): ClipTimeline => {
+    if (!clipMode())
+      throw new Error(
+        "whiteboard.clip() builds a clip's timeline, and this block is an animation: use whiteboard.timeline(frameKey) for its frames.",
+      );
+
+    if (built)
+      throw new Error(
+        "Build the clip's timeline while its scripts first run, not from a handler.",
+      );
+
+    const scenarios = init?.scenarios ?? [];
+
+    if (scenario !== undefined && !scenarios.includes(scenario))
+      throw new Error(
+        scenarios.length
+          ? `Unknown scenario "${scenario}": the clip declares ${scenarios.join(", ")}.`
+          : `The clip has no scenarios: call whiteboard.clip() without "${scenario}".`,
+      );
+
+    const slot = scenario ?? "";
+
+    if (clipQueued.has(slot))
+      throw new Error(
+        scenario === undefined
+          ? "whiteboard.clip() was already called: build its timeline once."
+          : `whiteboard.clip("${scenario}") was already called: build each scenario's timeline once.`,
+      );
+
+    const list: ClipEntry[] = [];
+    const placed = new Set<string>();
+    clipQueued.set(slot, list);
+
+    const api: ClipTimeline = {
+      add(targets, params, position) {
+        list.push({ kind: "add", targets, params, position });
+
+        return api;
+      },
+      set(targets, params, position) {
+        list.push({ kind: "set", targets, params, position });
+
+        return api;
+      },
+      call(callback, position) {
+        list.push({ kind: "call", callback, position });
+
+        return api;
+      },
+      marker(key, position) {
+        if (frameIndex(key) < 0)
+          throw new Error(
+            `Unknown marker "${key}": declare it in the clip's markers.`,
+          );
+
+        if (placed.has(key))
+          throw new Error(
+            `Marker "${key}" is already placed on this timeline.`,
+          );
+        placed.add(key);
+        list.push({ kind: "marker", key, position });
+
+        return api;
+      },
+    };
+
+    return api;
+  };
+
+  const buildClip = (entries: ClipEntry[]) => {
+    const next = lib().createTimeline({
+      autoplay: false,
+      defaults: { duration: 600, ease: "outQuad" },
+    });
+
+    for (const entry of entries) {
+      if (entry.kind === "marker")
+        next.label(entry.key, entry.position ?? next.duration);
+      else if (entry.kind === "call") next.call(entry.callback, entry.position);
+      else if (entry.kind === "add")
+        next.add(entry.targets, entry.params, entry.position);
+      else next.set(entry.targets, entry.params, entry.position);
+    }
+
+    return next;
+  };
+
+  // Advances whenever the playhead's owner changes: a pause, a jump, a new
+  // scenario, so a stale watch loop or reduced-motion step stops.
+  let clipToken = 0;
+  let clipPlaying = false;
+  let playAfterPaint = false;
+  let clipTimer: ReturnType<typeof setTimeout> | undefined;
+
+  // Under reduced motion, play holds each marker this long.
+  const CLIP_HOLD = 3000;
+
+  const clipNow = () =>
+    clipTimeline
+      ? Math.max(0, Math.min(clipTimeline.duration, clipTimeline.currentTime))
+      : 0;
+
+  const postTime = () =>
+    post({ type: "time", at: clipNow(), playing: clipPlaying });
+
+  const reachedMarker = (index: number): ReachedMarker | undefined => {
+    const placed = clipMarkers[index];
+    const declared = init?.markers.find((item) => item.key === placed?.key);
+
+    return placed && declared
+      ? { ...declared, at: placed.at, index }
+      : undefined;
+  };
+
+  // The playhead reached a marker: its states, its handlers, and the host.
+  const reach = (index: number, instant: boolean) => {
+    lastMarker = index;
+    const marker = reachedMarker(index);
+
+    if (marker) root.dataset.marker = marker.key;
+    else delete root.dataset.marker;
+
+    applyStates();
+    wake();
+
+    if (!marker) return;
+    const skip = instant || prefersReducedMotion();
+    instantMode = skip;
+
+    if (skip) root.setAttribute("data-wb-instant", "");
+
+    releaseFinished();
+    const change: MarkerChange = { marker, instant: skip };
+
+    try {
+      for (const key of ["*", marker.key])
+        for (const handler of markerHandlers.get(key) ?? []) {
+          try {
+            handler(change);
+          } catch (error) {
+            fail(String(error));
+          }
+        }
+    } finally {
+      instantMode = false;
+    }
+
+    if (skip)
+      nextFrame().then(() => {
+        for (const animation of document.getAnimations())
+          if (finite(animation)) animation.finish();
+
+        root.removeAttribute("data-wb-instant");
+      });
+
+    post({ type: "marker", key: marker.key });
+  };
+
+  // The last marker at or before `at`, for landing on a time.
+  const markerAt = (at: number) =>
+    clipMarkers.findLastIndex((marker) => marker.at <= at);
+
+  const stopClip = () => {
+    clipToken++;
+    clearTimeout(clipTimer);
+    clipTimeline?.pause();
+    clipPlaying = false;
+  };
+
+  const endClip = () => {
+    const tl = clipTimeline;
+
+    if (!tl) return;
+    stopClip();
+    tl.seek(tl.duration);
+
+    for (let index = lastMarker + 1; index < clipMarkers.length; index++)
+      reach(index, true);
+
+    post({ type: "ended" });
+    postTime();
+  };
+
+  // Reduced motion: no motion at all. Hold each marker, then land on the
+  // next one's time, and at the end after the last.
+  const stepClip = (token: number) => {
+    clipTimer = setTimeout(() => {
+      const tl = clipTimeline;
+
+      if (token !== clipToken || !tl) return;
+      const next = lastMarker + 1;
+
+      if (next >= clipMarkers.length) return endClip();
+      tl.seek(clipMarkers[next]!.at);
+      reach(next, true);
+      postTime();
+      stepClip(token);
+    }, CLIP_HOLD);
+  };
+
+  const playClip = () => {
+    const tl = clipTimeline;
+
+    if (clipPlaying) return;
+
+    // Before the scripts have built the timeline, and while the block paints
+    // in at time 0, play waits.
+    if (!tl || (init?.paint && !paintDone)) {
+      playAfterPaint = true;
+
+      return;
+    }
+
+    if (clipNow() >= tl.duration) {
+      tl.seek(0);
+      reach(markerAt(0), true);
+    }
+
+    const token = ++clipToken;
+    clipPlaying = true;
+    wake();
+
+    if (prefersReducedMotion()) {
+      postTime();
+
+      return stepClip(token);
+    }
+
+    if (tl.duration <= 0) return endClip();
+    tl.resume();
+    postTime();
+    let posted = performance.now();
+
+    const watch = () => {
+      if (token !== clipToken) return;
+      const at = clipNow();
+
+      while (
+        lastMarker + 1 < clipMarkers.length &&
+        clipMarkers[lastMarker + 1]!.at <= at
+      )
+        reach(lastMarker + 1, false);
+
+      if (at >= tl.duration || tl.completed) return endClip();
+
+      if (performance.now() - posted >= 100) {
+        posted = performance.now();
+        postTime();
+      }
+
+      requestAnimationFrame(watch);
+    };
+
+    requestAnimationFrame(watch);
+  };
+
+  const pauseClip = () => {
+    playAfterPaint = false;
+
+    if (!clipTimeline) return;
+    stopClip();
+    postTime();
+  };
+
+  const seekClip = (key: string) => {
+    const tl = clipTimeline;
+    const index = clipMarkers.findIndex((marker) => marker.key === key);
+
+    if (!tl || index < 0) return;
+    const playing = clipPlaying;
+    stopClip();
+    tl.seek(clipMarkers[index]!.at);
+    reach(index, true);
+
+    if (playing) playClip();
+    else postTime();
+  };
+
+  // Builds the scenario's timeline in place of the one showing, checks its
+  // markers, and lands it at 0.
+  const activateClip = (scenario: string | undefined) => {
+    stopClip();
+
+    const entries =
+      (scenario === undefined ? undefined : clipQueued.get(scenario)) ??
+      clipQueued.get("");
+
+    if (clipTimeline) {
+      clipTimeline.seek(0);
+      clipTimeline.revert();
+      clipTimeline = undefined;
+    }
+
+    clipMarkers = [];
+    lastMarker = -1;
+
+    if (!entries) {
+      fail(
+        scenario === undefined
+          ? "The clip has no timeline: build it with whiteboard.clip() while its script first runs."
+          : `The clip has no timeline for scenario "${scenario}": build it with whiteboard.clip("${scenario}"), or whiteboard.clip() for every scenario without its own.`,
+      );
+      post({ type: "clip", duration: 0, markers: [] });
+      postTime();
+
+      return;
+    }
+
+    const tl = buildClip(entries);
+    clipTimeline = tl;
+
+    const missing = (init?.markers ?? []).find(
+      (marker) => tl.labels[marker.key] === undefined,
+    );
+
+    if (missing)
+      fail(
+        `Marker "${missing.key}" is not placed on the clip's ${scenario === undefined ? "" : `"${scenario}" `}timeline: call .marker("${missing.key}") on whiteboard.clip(${scenario === undefined ? "" : `"${scenario}"`}).`,
+      );
+
+    clipMarkers = (init?.markers ?? [])
+      .flatMap((marker) => {
+        const at = tl.labels[marker.key];
+
+        return at === undefined
+          ? []
+          : [
+              {
+                key: marker.key,
+                at: Math.max(0, Math.min(tl.duration, at)),
+              },
+            ];
+      })
+      .sort((a, b) => a.at - b.at);
+
+    tl.seek(0);
+    post({ type: "clip", duration: tl.duration, markers: clipMarkers });
+    reach(markerAt(0), true);
+    postTime();
+  };
+
   const svg = "http://www.w3.org/2000/svg";
 
   interface ArrowRecord {
@@ -1497,7 +1926,7 @@ export function stageRuntime(port: MessagePort): void {
     const declared = declaredFrames();
     const declaredFrame = declared[index];
 
-    if (!declaredFrame) return;
+    if (clipMode() || !declaredFrame) return;
     const framePosition = activeFrameIndex(declaredFrame.key);
     const frame = { ...declaredFrame, index: framePosition };
     const previousDeclared = declared[current];
@@ -1595,6 +2024,16 @@ export function stageRuntime(port: MessagePort): void {
   // frame renderers even when the frame key stays the same, so the live
   // whiteboard.reducedMotion getter cannot leave stale semantic content behind.
   motionPreference.addEventListener("change", () => {
+    if (clipMode()) {
+      // Play again in the new mode, from where the playhead is.
+      if (clipPlaying) {
+        stopClip();
+        playClip();
+      } else if (lastMarker >= 0) reach(lastMarker, true);
+
+      return;
+    }
+
     if (current >= 0) show(current, true).catch((error) => fail(String(error)));
   });
 
@@ -1849,7 +2288,12 @@ export function stageRuntime(port: MessagePort): void {
 
   const runPaintHandlers = (instant: boolean): Promise<unknown>[] => {
     const waits: Promise<unknown>[] = [];
-    const paint: PaintChange = { frame: whiteboard.frame, instant };
+
+    const paint: PaintChange = {
+      ...(!clipMode() && { frame: whiteboard.frame }),
+      instant,
+    };
+
     const wasInstant = instantMode;
     instantMode = instant;
 
@@ -1898,6 +2342,11 @@ export function stageRuntime(port: MessagePort): void {
       paintDone = true;
       post({ type: "painted" });
       wake();
+
+      if (playAfterPaint) {
+        playAfterPaint = false;
+        playClip();
+      }
     }
   };
 
@@ -2173,7 +2622,7 @@ export function stageRuntime(port: MessagePort): void {
         let { tone, text } = part.base;
 
         for (const { at, change } of part.changes) {
-          const changeKey = init?.frames[at]?.key;
+          const changeKey = declaredKeys()[at];
           const changePosition = changeKey ? activeFrameIndex(changeKey) : -1;
 
           if (changePosition >= 0 && changePosition <= position) {
@@ -2400,11 +2849,22 @@ export function stageRuntime(port: MessagePort): void {
     };
   };
 
+  // An animation's frame API, called in a clip.
+  const framesOnly = (name: string) => {
+    if (clipMode())
+      throw new Error(
+        `A clip has no frames, so whiteboard.${name} does not apply: its reader jumps between markers. Place them with whiteboard.clip().marker(), and read whiteboard.markers and whiteboard.marker.`,
+      );
+  };
+
   const whiteboard: WhiteboardShim = {
     get frames() {
+      framesOnly("frames");
+
       return activeFrames();
     },
     get frame() {
+      framesOnly("frame");
       const key = init?.frames[Math.max(current, 0)]?.key;
 
       return activeFrames().find((frame) => frame.key === key)!;
@@ -2420,7 +2880,7 @@ export function stageRuntime(port: MessagePort): void {
     },
     code: (name) => placeholder("wbCode", name),
     block: (id) => placeholder("wbBlock", id),
-    on(key: string, handler: FrameHandler | PaintHandler) {
+    on(key: string, handler: FrameHandler | PaintHandler | MarkerHandler) {
       if (isPaint(key)) {
         // SAFETY: the "paint" overload takes a paint handler.
         const paint = handler as PaintHandler;
@@ -2430,7 +2890,21 @@ export function stageRuntime(port: MessagePort): void {
       }
 
       if (key !== "*" && frameIndex(key) < 0)
-        throw new Error(`Unknown frame "${key}".`);
+        throw new Error(
+          clipMode() ? `Unknown marker "${key}".` : `Unknown frame "${key}".`,
+        );
+
+      if (clipMode()) {
+        let markers = markerHandlers.get(key);
+
+        if (!markers) markerHandlers.set(key, (markers = new Set()));
+        // SAFETY: in a clip, any key but "paint" takes a marker handler.
+        const marker = handler as MarkerHandler;
+        markers.add(marker);
+
+        return () => markers.delete(marker);
+      }
+
       let set = handlers.get(key);
 
       if (!set) handlers.set(key, (set = new Set()));
@@ -2464,6 +2938,7 @@ export function stageRuntime(port: MessagePort): void {
       return animation;
     },
     setSequence(keys) {
+      framesOnly("setSequence()");
       const sequence = [...keys];
 
       if (!sequence.length)
@@ -2491,14 +2966,22 @@ export function stageRuntime(port: MessagePort): void {
       post({ type: "sequence", keys: sequence });
     },
     goto(key) {
+      framesOnly("goto()");
+
       if (frameIndex(key) < 0) throw new Error(`Unknown frame "${key}".`);
 
       if (activeSequence && !activeSequence.includes(key))
         throw new Error(`Frame "${key}" is not in the active sequence.`);
       post({ type: "goto", key });
     },
-    next: () => post({ type: "step", delta: 1 }),
-    prev: () => post({ type: "step", delta: -1 }),
+    next() {
+      framesOnly("next()");
+      post({ type: "step", delta: 1 });
+    },
+    prev() {
+      framesOnly("prev()");
+      post({ type: "step", delta: -1 });
+    },
     reveal(name) {
       if (!init?.code.includes(name))
         throw new Error(`Unknown code name "${name}".`);
@@ -2508,6 +2991,17 @@ export function stageRuntime(port: MessagePort): void {
       return lib();
     },
     timeline: frameTimeline,
+    clip: (scenario) => clipBuilder(scenario),
+    get markers() {
+      return (init?.markers ?? []).map((marker) => {
+        const placed = clipMarkers.find((item) => item.key === marker.key);
+
+        return placed ? { ...marker, at: placed.at } : { ...marker };
+      });
+    },
+    get marker() {
+      return reachedMarker(lastMarker);
+    },
     arrow(from, to, options = {}) {
       return createEdge(resolve(from), resolve(to), options).group;
     },
@@ -2601,6 +3095,7 @@ export function stageRuntime(port: MessagePort): void {
   const moving = () =>
     showsInProgress > 0 ||
     (timeline !== undefined && !timeline.paused) ||
+    (clipTimeline !== undefined && !clipTimeline.paused) ||
     document
       .getAnimations()
       .some(
@@ -2793,7 +3288,9 @@ export function stageRuntime(port: MessagePort): void {
     await runSources(message.libraries);
     await runScripts([...document.body.querySelectorAll("script")]);
     arrows.forEach(route);
-    buildTimeline();
+
+    if (message.mode === "clip") built = true;
+    else buildTimeline();
     buildPaintTimeline();
 
     // Not painting in: the paint timeline lands at its end before the first
@@ -2808,6 +3305,23 @@ export function stageRuntime(port: MessagePort): void {
     });
     measuring = true;
     wake();
+
+    if (message.mode === "clip") {
+      activateClip(message.scenario);
+      firstShown = true;
+
+      if (!message.paint) runPaintHandlers(true);
+      else if (paintAsked) await paintIn();
+
+      // A play that came before the timeline was built.
+      if (playAfterPaint && !message.paint) {
+        playAfterPaint = false;
+        playClip();
+      }
+
+      return;
+    }
+
     const requestedKey = message.frames[message.frame]?.key;
     const firstActive = activeSequence?.[0];
 
@@ -2857,6 +3371,24 @@ export function stageRuntime(port: MessagePort): void {
         // The stage's own timeout may have painted it already.
         if (paintDone) post({ type: "painted" });
         else askPaint(false);
+        break;
+      case "play":
+        playClip();
+        break;
+      case "pause":
+        pauseClip();
+        break;
+      case "seek":
+        if (init) seekClip(message.marker);
+        break;
+      case "scenario":
+        if (init?.mode === "clip")
+          try {
+            activateClip(message.key);
+          } catch (error) {
+            fail(String(error));
+          }
+
         break;
       case "sequence":
         if (!init) break;
diff --git a/packages/review/app/src/block-document-derivations.ts b/packages/review/app/src/block-document-derivations.ts
index 8087bc9e11..1ec74ad876 100644
--- a/packages/review/app/src/block-document-derivations.ts
+++ b/packages/review/app/src/block-document-derivations.ts
@@ -22,6 +22,7 @@ export function blockSectionSummary(children: Block[]): ReviewSectionSummary {
       case "flow_diagram":
       case "software_map":
       case "animation":
+      case "clip":
         summary.diagrams += 1;
         break;
       case "code_peek":
diff --git a/packages/review/app/src/blocks.browser.test.tsx b/packages/review/app/src/blocks.browser.test.tsx
index a11fc10f59..36aac2cf81 100644
--- a/packages/review/app/src/blocks.browser.test.tsx
+++ b/packages/review/app/src/blocks.browser.test.tsx
@@ -173,6 +173,12 @@ const rendered: Record<
       c,
       "[data-animation-slot='code'] .fixture-inline-editor[data-path='order.ts']",
     ) && text(c).includes("An order arrives"),
+  // A clip boots the same stage, and lists its markers under it.
+  clip: (c) =>
+    has(
+      c,
+      "[data-animation-slot='code'] .fixture-inline-editor[data-path='order.ts']",
+    ) && text(c).includes("Status queued"),
 };
 
 let canvas: ReturnType<typeof mount> | undefined;
diff --git a/packages/review/app/src/blocks.tsx b/packages/review/app/src/blocks.tsx
index e734e6ab38..f747841781 100644
--- a/packages/review/app/src/blocks.tsx
+++ b/packages/review/app/src/blocks.tsx
@@ -287,19 +287,21 @@ function SoftwareMapBlock({ node, data }: BlockProps<"software_map">) {
   );
 }
 
-function AnimationDiagramBlock(props: BlockProps<"animation">) {
-  const { height, title, html, frames, scenarios, code } = props.node;
+function AnimationDiagramBlock(props: BlockProps<"animation" | "clip">) {
+  const { node } = props;
+  const { height, title, html, scenarios, code } = node;
+  const steps = node.type === "clip" ? node.markers : node.frames;
 
-  // An edit to the animation draws it again from a fresh block, at its first
-  // frame, rather than updating a stage whose frames may have gone.
+  // An edit to the animation or clip draws it again from a fresh block, at
+  // its start, rather than updating a stage whose frames may have gone.
   const revision = useMemo(
-    () => JSON.stringify([html, frames, scenarios, code, height]),
-    [html, frames, scenarios, code, height],
+    () => JSON.stringify([html, steps, scenarios, code, height]),
+    [html, steps, scenarios, code, height],
   );
 
   return (
     <ClientDiagram
-      kind="ANIMATION"
+      kind={node.type === "clip" ? "CLIP" : "ANIMATION"}
       title={title}
       height={height === "auto" ? 120 : height}
     >
@@ -336,6 +338,7 @@ export const blockComponents = {
   flow_diagram: FlowDiagramBlock,
   software_map: SoftwareMapBlock,
   animation: AnimationDiagramBlock,
+  clip: AnimationDiagramBlock,
   section: SectionBlock,
   callout: CalloutBlock,
 } satisfies Components;
diff --git a/packages/review/app/src/draw-queue.test.ts b/packages/review/app/src/draw-queue.test.ts
index 69314b128d..b8891110dc 100644
--- a/packages/review/app/src/draw-queue.test.ts
+++ b/packages/review/app/src/draw-queue.test.ts
@@ -38,11 +38,14 @@ const block = (id: string): AuthoringCursor => ({
   seq: ++seq,
 });
 
-const animation = (id: string): AuthoringCursor => ({
+const animation = (
+  id: string,
+  kind: "animation" | "clip" = "animation",
+): AuthoringCursor => ({
   targetId: id,
   blockId: id,
   source: "edit",
-  edit: { type: "insert", targetId: id, blockId: id, kind: "animation" },
+  edit: { type: "insert", targetId: id, blockId: id, kind },
   seq: ++seq,
 });
 
@@ -379,6 +382,15 @@ describe("draw queue", () => {
     expect(standingCursor(capped)?.targetId).toBe("anim-3");
   });
 
+  it("holds a new clip while it paints, as an animation", () => {
+    let state = arrive(EMPTY_QUEUE, animation("clip-1", "clip"), 0);
+    expect(phases(state)).toEqual(new Map([["clip-1", "painting"]]));
+    expect(nextDue(state)).toBe(PAINT_CAP);
+
+    state = painted(state, "clip-1", 400);
+    expect(state.head).toBeNull();
+  });
+
   it("ignores a painted report for another block, or when the head is not painting", () => {
     let state = arrive(EMPTY_QUEUE, animation("anim-1"), 0);
     expect(painted(state, "anim-2", 100)).toBe(state);
diff --git a/packages/review/app/src/draw-queue.ts b/packages/review/app/src/draw-queue.ts
index e80fefbb42..5803f49eeb 100644
--- a/packages/review/app/src/draw-queue.ts
+++ b/packages/review/app/src/draw-queue.ts
@@ -118,8 +118,9 @@ export function stepsFor(cursor: AuthoringCursor): DrawStep[] {
           { phase: "fill", ms: 250 },
         ];
 
-      // An animation's stage paints its own first frame; painted() ends it.
-      if (edit.kind === "animation")
+      // An animation's or clip's stage paints its own first frame; painted()
+      // ends it.
+      if (edit.kind === "animation" || edit.kind === "clip")
         return [{ phase: "painting", ms: PAINT_CAP }];
 
       return [{ phase: "landing", ms: 680 }];
diff --git a/packages/review/app/src/ui/progress-line.tsx b/packages/review/app/src/ui/progress-line.tsx
new file mode 100644
index 0000000000..0e8a040d38
--- /dev/null
+++ b/packages/review/app/src/ui/progress-line.tsx
@@ -0,0 +1,67 @@
+import { motion, radius } from "@canvas/scale.stylex";
+import { tokens } from "@canvas/tokens.stylex";
+import * as stylex from "@stylexjs/stylex";
+
+/** A thin track filled to `value` (0 to 1), with a tick at each of `ticks`.
+ * It only shows progress: nothing on it is interactive. */
+export function ProgressLine({
+  value,
+  ticks = [],
+}: {
+  value: number;
+  ticks?: readonly number[];
+}) {
+  const clamp = (fraction: number) => Math.max(0, Math.min(1, fraction));
+
+  return (
+    <div aria-hidden="true" {...stylex.props(styles.track)}>
+      <div
+        {...stylex.props(styles.fill)}
+        style={{ transform: `scaleX(${clamp(value)})` }}
+      />
+      {ticks.map((tick, index) => (
+        <span
+          key={index}
+          {...stylex.props(
+            styles.tick,
+            clamp(tick) <= clamp(value) && styles.tickPassed,
+          )}
+          style={{ left: `${clamp(tick) * 100}%` }}
+        />
+      ))}
+    </div>
+  );
+}
+
+const styles = stylex.create({
+  track: {
+    position: "relative",
+    height: "2px",
+    backgroundColor: tokens.rule,
+  },
+  // Updates arrive a few times a second; the transition joins them up.
+  fill: {
+    position: "absolute",
+    inset: 0,
+    backgroundColor: tokens.accent,
+    transformOrigin: "left center",
+    transitionProperty: "transform",
+    transitionDuration: {
+      default: motion.fast,
+      [stylex.env.reducedMotion]: motion.instant,
+    },
+    transitionTimingFunction: "linear",
+  },
+  tick: {
+    position: "absolute",
+    top: "50%",
+    width: "2px",
+    height: "6px",
+    transform: "translate(-50%, -50%)",
+    borderRadius: radius.round,
+    backgroundColor: tokens.inkFaint,
+  },
+  tickPassed: {
+    backgroundColor: tokens.accent,
+  },
+});
diff --git a/packages/review/instructions/animation.md b/packages/review/instructions/animation.md
index 595abb7763..b793ad9108 100644
--- a/packages/review/instructions/animation.md
+++ b/packages/review/instructions/animation.md
@@ -2,6 +2,8 @@ An `animation` component draws HTML you write on the whiteboard, in a sandboxed
 
 For paths a reader can pick, such as a retry that succeeds or one that gives up, use `scenarios`: the whiteboard draws the picker, so do not draw your own buttons.
 
+A `clip` component runs in the same stage with the same API, but it has no frames: it is one timeline the reader plays, pauses and jumps around by named markers. See "Clips: one timeline, played" below.
+
 ## Work in files
 
 1. `session_checkout({ sessionId, targetId })` writes the animation to a folder: `animation.html`, `frames.json`, `scenarios.json` (once it has scenarios) and `block.json` (`title`, and `code` and `pins` when it shows code).
@@ -98,3 +100,34 @@ Name the ranges the animation explains in `code`, then link the drawing to them:
 - `data-wb-open="retry"` (or `code: "retry"` on a scene card) opens the code beside the whiteboard when the reader clicks that element, and names it when they hover. Put it on the part of the drawing the code explains.
 - A frame's `code` lists the ranges that frame shows. Your script reads it as `frame.code`, so one script can mark what to open in every frame.
 - `<div data-wb-code="retry">` (or `scene.peek`) shows a range inside the drawing instead.
+
+## Clips: one timeline, played
+
+Pick a clip when the motion itself is the point and the timing carries the meaning: a token crossing a system, two requests racing, a queue draining, a timeout firing while a reply is on its way. Pick an animation when the reader needs to compare discrete states, one frame against the next.
+
+A clip's folder holds `markers.json` where an animation's holds `frames.json`; `session_checkout` writes whichever the block has, and publishing a folder with `markers.json` makes a clip. A marker is `{ key, title, caption?, code? }`: a named moment the reader jumps to and the tour stops at. The strip under the clip shows each title, so keep titles to a few words. Markers have no `data` or `duration`: the script decides when each one happens.
+
+Build the timeline while the script first runs, and place every marker on it:
+
+```html
+<script>
+  whiteboard
+    .clip()
+    .marker("sent")
+    .add(".packet", { left: ["10%", "50%"], duration: 700 })
+    .marker("accepted")
+    .add(".packet", { left: ["50%", "90%"], duration: 900 })
+    .marker("stored");
+</script>
+```
+
+- `whiteboard.clip()` returns a timeline with `add`, `set` and `call`, as `whiteboard.timeline` does, and `.marker(key)`, which places a declared marker at the timeline's end so far, or at an anime.js position (`.marker("timeout", 1500)`). Numeric positions count from the clip's start. Markers are labels on the timeline, so later calls can start at one: `.add(".retry", { opacity: [0, 1] }, "timeout")`.
+- A marker the script leaves unplaced shows an error under the clip, naming it.
+- With `scenarios` (`[{ key, label }]` in `scenarios.json`), each scenario is a timeline of its own: call `whiteboard.clip("fast")`, `whiteboard.clip("slow")`, once each, and place every marker on each. A `whiteboard.clip()` without a key serves every scenario that has no timeline of its own.
+- Write each tween with its start value (`left: ["10%", "50%"]`, not `left: "50%"`), and make what differs between beats a `set` or a tween on the timeline: jumping back to a marker then undoes everything after it.
+- `whiteboard.on("stored", ({ marker, instant }) => ...)` runs when the playhead crosses that marker playing forward, or lands on it after a jump with `instant: true`; `"*"` runs on every marker. Use it for what a tween cannot draw, such as changing text, and set the whole state for that marker, since the reader can jump straight to it. `whiteboard.markers` lists the markers with their `at` (milliseconds) once placed, and `whiteboard.marker` is the one the playhead last reached.
+- In a clip, `data-enter`, `data-exit`, `data-only`, `data-highlight` and `scene.on` name markers instead of frames, and follow the marker the playhead last reached.
+- `whiteboard.frames`, `frame`, `goto`, `next`, `prev`, `setSequence`, `timeline(key)`, `travel` and `scene.send` belong to frames and throw in a clip. Move tokens with tweens on the clip instead.
+- Under reduced motion the clip never animates: Play steps from marker to marker, holding each for a few seconds and landing on its time at once, and a jump lands at once. Marker handlers get `instant: true`.
+- Painting in and code linking work as for an animation: the clip paints in at time 0, before anything plays, and a marker's `code` gives its tour stop, as a frame's does.
+
diff --git a/packages/review/instructions/animations/request-timing/README.md b/packages/review/instructions/animations/request-timing/README.md
new file mode 100644
index 0000000000..303bcc4141
--- /dev/null
+++ b/packages/review/instructions/animations/request-timing/README.md
@@ -0,0 +1,22 @@
+# One read, with and without the cache
+
+A clip of one request crossing client, API, cache and database as a continuous trip, with an elapsed bar, played once as a cache hit and once as a miss.
+
+## Use when
+
+A change adds, removes or moves a cache, a retry or any hop on a request's path, and the reviewer has to feel what it does to latency: the point is how long each leg takes, not a list of states.
+
+## Shows
+
+A GET token rides from the client to the API and on to the cache. On a hit the cache answers at once; on a miss the read goes on to Postgres, waits there, and comes back through the cache to fill it. A 200 token rides home and the elapsed bar, which fills for the whole trip, stops at that scenario's total. The markers name the same five beats in both, so jumping to Cache lookup in either shows where the paths split.
+
+## Technique
+
+A clip: markers.json declares the beats, and the script builds one timeline per scenario with `whiteboard.clip(key)`, placing each marker with `.marker(key)` where the request reaches it. Tokens move by `left` percentages, so the trip follows the four-column layout at any width. Everything that differs between the scenarios (the result chip, the second token, the total) is a `set` on that scenario's timeline, so a jump back undoes it. The elapsed bar is one tween added at position 0 with the trip's length, scaled by the longest trip so the two scenarios' bars compare.
+
+## Adapt
+
+- Rename the four nodes and their `<small>` lines for your path, and keep the column centers in `client`, `api`, `cache`, `db` in step with the grid.
+- Change the leg lengths in `hop` and `hold` to the proportions that matter, a slow query or a fast cache, and set `LONGEST` to the longest scenario's sum.
+- Add a scenario (a stale entry, a timeout) with an entry in scenarios.json and one more `build` call that places every marker.
+- Point `code` at your client call, handler, cache and query, and list them on the markers that show them.
diff --git a/packages/review/instructions/animations/request-timing/animation.html b/packages/review/instructions/animations/request-timing/animation.html
new file mode 100644
index 0000000000..45f603da41
--- /dev/null
+++ b/packages/review/instructions/animations/request-timing/animation.html
@@ -0,0 +1,120 @@
+<div class="trip">
+  <div class="stops">
+    <div class="wb-node" data-wb-open="client">Client<small>fetchOrder(7)</small></div>
+    <div class="wb-node" data-wb-open="handler">API<small>GET /orders/7</small></div>
+    <div class="wb-node" id="cache" data-wb-open="cache">Cache<small>orders:7</small></div>
+    <div class="wb-node" id="db" data-wb-open="query">Postgres<small>SELECT</small></div>
+  </div>
+  <div class="wb-lane track">
+    <span class="wb-token packet out" data-visible data-labelled>GET</span>
+    <span class="wb-token packet back" data-labelled data-tone="added">200</span>
+  </div>
+  <div class="wb-layers results">
+    <span class="wb-chip result hit" data-tone="added">hit: served from memory</span>
+    <span class="wb-chip result miss" data-tone="modified">miss: read from Postgres, then cached</span>
+  </div>
+  <div class="clock">
+    <span class="wb-caps">elapsed</span>
+    <div class="bar"><div class="fill"></div></div>
+    <span class="wb-layers totals">
+      <span class="wb-mono total hit">38 ms</span>
+      <span class="wb-mono total miss">212 ms</span>
+    </span>
+  </div>
+</div>
+
+<style>
+  .trip {
+    display: grid;
+    gap: var(--wb-space-16);
+    padding: var(--wb-space-20) var(--wb-space-24);
+  }
+  .stops {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    justify-items: center;
+    gap: var(--wb-space-16);
+  }
+  .packet { top: 50%; }
+  .packet.out { left: 12.5%; }
+  .packet.back { left: 62.5%; }
+  .results { justify-items: center; min-height: var(--wb-space-24); }
+  .result, .total { opacity: 0; }
+  .clock {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr) max-content;
+    align-items: center;
+    gap: var(--wb-space-12);
+  }
+  .bar {
+    height: var(--wb-space-6);
+    border-radius: var(--wb-radius-control);
+    background: var(--wb-well);
+    overflow: hidden;
+  }
+  .fill {
+    height: 100%;
+    background: var(--wb-accent);
+    transform: scaleX(0);
+    transform-origin: left;
+  }
+  .totals { justify-items: end; color: var(--wb-ink-muted); }
+</style>
+
+<script>
+  // The centers of the four columns, as the packet's left edge.
+  const [client, api, cache, db] = ["12.5%", "37.5%", "62.5%", "87.5%"];
+  const out = document.querySelector(".packet.out");
+  const back = document.querySelector(".packet.back");
+
+  // One timeline per scenario. Every marker is placed on both, at the moment
+  // the request reaches it, so the strip jumps to the same beat in either.
+  const build = (key, miss) => {
+    const clip = whiteboard.clip(key);
+    let elapsed = 0;
+
+    const hop = (token, from, to, duration) => {
+      clip.add(token, { left: [from, to], duration, ease: "inOutQuad" });
+      elapsed += duration;
+    };
+
+    const hold = (target, duration) => {
+      clip.add(target, { scale: [1, 1.06, 1], duration });
+      elapsed += duration;
+    };
+
+    clip.marker("sent");
+    hop(out, client, api, 700);
+    clip.marker("accepted");
+    hop(out, api, cache, 600);
+    clip.marker("lookup");
+
+    if (miss) {
+      clip.set(".result.miss", { opacity: 1 });
+      hop(out, cache, db, 600);
+      hold("#db", 900);
+      clip.set(out, { opacity: 0 }).set(back, { left: db, opacity: 1 });
+      hop(back, db, cache, 600);
+    } else {
+      clip.set(".result.hit", { opacity: 1 });
+      hold("#cache", 300);
+      clip.set(out, { opacity: 0 }).set(back, { left: cache, opacity: 1 });
+    }
+
+    hop(back, cache, api, 600);
+    clip.marker("reply");
+    hop(back, api, client, 700);
+    clip.set(`.total.${miss ? "miss" : "hit"}`, { opacity: 1 });
+    clip.marker("received");
+
+    // The elapsed bar fills over the whole trip, from the start, on one
+    // scale for both scenarios: the miss's trip fills it.
+    clip.add(".fill", { scaleX: [0, elapsed / LONGEST], duration: elapsed, ease: "linear" }, 0);
+  };
+
+  // The miss's trip, in milliseconds: the sum of its hops and its hold.
+  const LONGEST = 4700;
+
+  build("hit", false);
+  build("miss", true);
+</script>
diff --git a/packages/review/instructions/animations/request-timing/block.json b/packages/review/instructions/animations/request-timing/block.json
new file mode 100644
index 0000000000..07ec019f28
--- /dev/null
+++ b/packages/review/instructions/animations/request-timing/block.json
@@ -0,0 +1,21 @@
+{
+  "title": "One read, with and without the cache",
+  "code": {
+    "client": {
+      "source": "head/web/src/orders/api.ts#L14-L30",
+      "label": "fetchOrder"
+    },
+    "handler": {
+      "source": "head/src/api/orders/get.ts#L8-L36",
+      "label": "getOrder"
+    },
+    "cache": {
+      "source": "head/src/orders/cache.ts#L10-L44",
+      "label": "OrderCache.read"
+    },
+    "query": {
+      "source": "head/src/orders/repository.ts#L52-L70",
+      "label": "selectOrder"
+    }
+  }
+}
diff --git a/packages/review/instructions/animations/request-timing/markers.json b/packages/review/instructions/animations/request-timing/markers.json
new file mode 100644
index 0000000000..460ad03a45
--- /dev/null
+++ b/packages/review/instructions/animations/request-timing/markers.json
@@ -0,0 +1,32 @@
+[
+  {
+    "key": "sent",
+    "title": "Request sent",
+    "caption": "The client asks for order 7.",
+    "code": ["client"]
+  },
+  {
+    "key": "accepted",
+    "title": "API accepts",
+    "caption": "getOrder parses the id and asks the cache first.",
+    "code": ["handler"]
+  },
+  {
+    "key": "lookup",
+    "title": "Cache lookup",
+    "caption": "The cache either holds orders:7 or sends the read on to Postgres.",
+    "code": ["cache", "query"]
+  },
+  {
+    "key": "reply",
+    "title": "API replies",
+    "caption": "The order is back in the API, which answers 200.",
+    "code": ["handler"]
+  },
+  {
+    "key": "received",
+    "title": "Client renders",
+    "caption": "The reply lands. The elapsed bar shows what the cache saved.",
+    "code": ["client"]
+  }
+]
diff --git a/packages/review/instructions/animations/request-timing/scenarios.json b/packages/review/instructions/animations/request-timing/scenarios.json
new file mode 100644
index 0000000000..a8d5e6f92c
--- /dev/null
+++ b/packages/review/instructions/animations/request-timing/scenarios.json
@@ -0,0 +1,4 @@
+[
+  { "key": "hit", "label": "Cache hit" },
+  { "key": "miss", "label": "Cache miss" }
+]
diff --git a/packages/review/instructions/whiteboard.d.ts b/packages/review/instructions/whiteboard.d.ts
index 6769e1b598..358bc8b5cb 100644
--- a/packages/review/instructions/whiteboard.d.ts
+++ b/packages/review/instructions/whiteboard.d.ts
@@ -5,6 +5,9 @@
  *
  * Frames are states, not events: whatever a frame shows must also be right
  * when the reader jumps to it or steps back, not only when it plays.
+ *
+ * A clip has no frames: its script builds one timeline with clip(), places
+ * the block's markers on it, and the reader plays it or jumps to a marker.
  */
 
 /* oxlint-disable anti-slop/no-unknown-parameters, anti-slop/no-object-parameters -- Documents a script API; anime.js parses its own targets and params. */
@@ -35,10 +38,36 @@ export interface FrameChange {
   instant: boolean;
 }
 
+/** One of a clip's markers, as your scripts read it. */
+export interface Marker {
+  key: string;
+  title: string;
+  caption?: string;
+  /** The code names the marker lists, for data-wb-open. */
+  code?: string[];
+  /** Milliseconds into the active timeline, once the scripts have run. */
+  at?: number;
+}
+
+/** A marker the playhead reached: placed, with its place in time order. */
+export interface ReachedMarker extends Marker {
+  at: number;
+  index: number;
+}
+
+/** What a marker handler learns as a clip's playhead reaches its marker. */
+export interface MarkerChange {
+  marker: ReachedMarker;
+  /** A jump to the marker, the first draw, or reduced motion: draw the
+   * marker's state at once. */
+  instant: boolean;
+}
+
 /** What a paint handler learns as the block paints its first frame in. */
 export interface PaintChange {
-  /** The first frame, already drawn in its end state. */
-  frame: Frame;
+  /** The first frame, already drawn in its end state. A clip has none: it
+   * paints in at time 0. */
+  frame?: Frame;
   /** Skip motion and leave everything in its end state: the block loaded
    * without painting in, or the reader prefers reduced motion. */
   instant: boolean;
@@ -77,6 +106,11 @@ export interface Whiteboard {
    * handlers, and again when reduced motion changes. Cancel earlier work when
    * another frame shows. Returns an unsubscribe function. */
   on(key: string, handler: (change: FrameChange) => FrameResult): () => void;
+  /** In a clip: run when the playhead crosses the marker playing forward, or
+   * lands on it after a jump (`instant: true`); "*" runs on every marker.
+   * What a marker sets must also be right when the reader jumps there.
+   * Returns an unsubscribe function. */
+  on(key: string, handler: (change: MarkerChange) => FrameResult): () => void;
   /** element.animate that holds its end state, lands at the end on a jump, and
    * skips motion under reduced motion. Give every keyframe its start value, and
    * measure positions before starting one: a started animation already
@@ -94,6 +128,16 @@ export interface Whiteboard {
    * the block paints in, in place of the default painter; it lands at its end
    * otherwise. Numeric positions count from its start. */
   timeline(key: string): FrameTimeline;
+  /** A clip's one timeline: build it while the script first runs and place
+   * every marker on it. With scenarios, call it once per scenario key, each
+   * a timeline of its own; one built without a key serves every scenario
+   * without its own. Throws in an animation. */
+  clip(scenario?: string): ClipTimeline;
+  /** A clip's markers as declared, each with `at` once placed. Empty in an
+   * animation. */
+  readonly markers: readonly Marker[];
+  /** The marker a clip's playhead last reached, if any. */
+  readonly marker: ReachedMarker | undefined;
   /** anime.js v4, also the global `anime`: easings, stagger, utils. */
   readonly anime: unknown;
 
@@ -156,6 +200,25 @@ export interface FrameTimeline {
   call(callback: () => void, position?: number | string): FrameTimeline;
 }
 
+/** A clip's timeline. Numeric positions count milliseconds from its start;
+ * "<" starts at the previous call's end and "<<" at its beginning. */
+export interface ClipTimeline {
+  add(
+    targets: unknown,
+    params: object,
+    position?: number | string,
+  ): ClipTimeline;
+  set(
+    targets: unknown,
+    params: object,
+    position?: number | string,
+  ): ClipTimeline;
+  call(callback: () => void, position?: number | string): ClipTimeline;
+  /** Place a declared marker at the timeline's end so far, or at an anime.js
+   * position. Every marker must be placed once on each timeline. */
+  marker(key: string, position?: number | string): ClipTimeline;
+}
+
 export interface TravelOptions {
   duration?: number;
   ease?: string;
diff --git a/packages/review/src/animation-stage-kit.ts b/packages/review/src/animation-stage-kit.ts
index 5b797d1d19..02f53d2277 100644
--- a/packages/review/src/animation-stage-kit.ts
+++ b/packages/review/src/animation-stage-kit.ts
@@ -402,7 +402,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}
diff --git a/packages/review/src/fixtures/blocks/clip.json b/packages/review/src/fixtures/blocks/clip.json
new file mode 100644
index 0000000000..9d8ce450df
--- /dev/null
+++ b/packages/review/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>"
+  }
+]
diff --git a/packages/review/src/review-api/animation-authoring.test.ts b/packages/review/src/review-api/animation-authoring.test.ts
index 79da90c77c..2f02eff850 100644
--- a/packages/review/src/review-api/animation-authoring.test.ts
+++ b/packages/review/src/review-api/animation-authoring.test.ts
@@ -141,6 +141,92 @@ it("gates animation authoring live, including stale MCP tools, while keeping sav
   }
 });
 
+it("gates clips with animations", async () => {
+  let enabled = false;
+
+  const store = new ReviewStore(":memory:", {
+    validatePins: async () => {},
+    validateSource: async () => {},
+    validateResource: async () => {},
+  });
+
+  const app = createReviewApi(
+    store,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    () => enabled,
+  );
+
+  const client = new ReviewApiClient(
+    { serverUrl: "http://review.test", token: "test" },
+    async (url, init) => app.request(url.replace("/reviews-api", ""), init),
+  );
+
+  const clip = {
+    type: "clip",
+    title: "Race",
+    html: "<p>Race</p>",
+    markers: [{ key: "go", title: "Go" }],
+  };
+
+  const editTool = async () =>
+    (await client.read<AuthoringTool[]>("/authoring"))
+      .map(publicTool)
+      .find((tool) => tool.name === "session_edit")!;
+
+  try {
+    const { reviewId } = await store.execute({
+      operation: {
+        type: "create",
+        title: "Clips",
+        target: {
+          kind: "commits",
+          repositoryId: "repo",
+          base: "base",
+          head: "head",
+        },
+      },
+    });
+
+    expect(await client.read<string>("/instructions")).not.toContain("- clip ");
+    await expect(
+      callPublicTool(client, await editTool(), {
+        sessionId: reviewId,
+        edit: { type: "insert", content: clip },
+      }),
+    ).rejects.toThrow("Animation authoring is disabled");
+    expect(store.read(reviewId).document).toEqual([]);
+
+    enabled = true;
+    expect(await client.read<string>("/instructions")).toContain("- clip ");
+    await callPublicTool(client, await editTool(), {
+      sessionId: reviewId,
+      edit: { type: "insert", content: clip },
+    });
+    const targetId = store.read(reviewId).document[0]!.id;
+
+    enabled = false;
+    await expect(
+      callPublicTool(client, await editTool(), {
+        sessionId: reviewId,
+        edit: { type: "update", targetId, changes: { title: "Renamed" } },
+      }),
+    ).rejects.toThrow("Animation authoring is disabled");
+    expect(store.read(reviewId).document[0]).toMatchObject({
+      type: "clip",
+      title: "Race",
+    });
+  } finally {
+    store.close();
+  }
+});
+
 it("defaults animation authoring off and persists it", async () => {
   const home = await mkdtemp(path.join(tmpdir(), "animation-preferences-"));
 
diff --git a/packages/review/src/review-api/animation-drafts.test.ts b/packages/review/src/review-api/animation-drafts.test.ts
index c36d8d2440..e18ab5e402 100644
--- a/packages/review/src/review-api/animation-drafts.test.ts
+++ b/packages/review/src/review-api/animation-drafts.test.ts
@@ -1,4 +1,11 @@
-import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
@@ -226,6 +233,89 @@ it("inserts an animation written as files, and later publishes update it", async
   expect(block()).toMatchObject({ title: "Raft again" });
 });
 
+const clip = {
+  type: "clip",
+  title: "Token race",
+  html: "<script>whiteboard.clip().marker('go').marker('won');</script>",
+  markers: [
+    { key: "go", title: "Go", caption: "Both set off." },
+    { key: "won", title: "A wins", caption: "A crosses first." },
+  ],
+};
+
+it("round-trips a clip through its folder: markers.json, not frames.json", async () => {
+  await call("session_edit", { edit: { type: "insert", content: clip } });
+  const targetId = block().id!;
+
+  const checkout = (await call("session_checkout", {
+    targetId,
+    dir: drafts,
+  })) as { files: Record<string, string> };
+
+  expect(Object.keys(checkout.files).sort()).toEqual([
+    "block",
+    "html",
+    "markers",
+  ]);
+  await expect(stat(draftFile("frames.json"))).rejects.toThrow(/ENOENT/);
+  expect(JSON.parse(await readFile(draftFile("markers.json"), "utf8"))).toEqual(
+    clip.markers,
+  );
+
+  await editJson("markers.json", (markers) =>
+    markers.splice(1, 0, { key: "half", title: "Halfway" }),
+  );
+  await call("session_edit", {
+    edit: { type: "update", targetId, fromFiles: drafts },
+  });
+  expect(store.read(sessionId).lastEdit).toMatchObject({
+    fields: ["markers"],
+  });
+  expect(block()).toMatchObject({
+    type: "clip",
+    markers: [
+      expect.objectContaining({ key: "go" }),
+      expect.objectContaining({ key: "half" }),
+      expect.objectContaining({ key: "won" }),
+    ],
+  });
+
+  // A new clip from a folder of its own.
+  const fresh = path.join(drafts, "fresh");
+  await mkdir(fresh);
+  await writeFile(path.join(fresh, "animation.html"), clip.html);
+  await writeFile(
+    path.join(fresh, "markers.json"),
+    JSON.stringify(clip.markers),
+  );
+  await writeFile(
+    path.join(fresh, "block.json"),
+    JSON.stringify({ title: "Second race" }),
+  );
+
+  const inserted = (await call("session_edit", {
+    edit: { type: "insert", fromFiles: fresh },
+  })) as { targetId: string };
+
+  expect(
+    store
+      .read(sessionId)
+      .document.find((item) => item.id === inserted.targetId),
+  ).toMatchObject({ type: "clip", title: "Second race" });
+});
+
+it("refuses a folder holding both frames.json and markers.json", async () => {
+  const targetId = await inserted();
+
+  await call("session_checkout", { targetId, dir: drafts });
+  await writeFile(draftFile("markers.json"), JSON.stringify(clip.markers));
+  await expect(
+    call("session_edit", {
+      edit: { type: "update", targetId, fromFiles: drafts },
+    }),
+  ).rejects.toThrow(/holds both frames\.json and markers\.json/);
+});
+
 it("checks out only animations", async () => {
   await call("session_edit", {
     edit: { type: "insert", content: { type: "markdown", markdown: "Prose" } },
@@ -233,7 +323,7 @@ it("checks out only animations", async () => {
 
   await expect(
     call("session_checkout", { targetId: block().id!, dir: drafts }),
-  ).rejects.toThrow(/is a markdown; only animations check out/);
+  ).rejects.toThrow(/is a markdown; only animations and clips check out/);
 });
 
 it("hands agents whiteboard.css and whiteboard.d.ts, read-only, from checkout and the animation instructions", async () => {
diff --git a/packages/review/src/review-api/animation-drafts.ts b/packages/review/src/review-api/animation-drafts.ts
index 1eab00256e..d5cf2ecec0 100644
--- a/packages/review/src/review-api/animation-drafts.ts
+++ b/packages/review/src/review-api/animation-drafts.ts
@@ -1,6 +1,7 @@
-// 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 {
@@ -40,6 +41,7 @@ import {
 const FILES = {
   html: "animation.html",
   frames: "frames.json",
+  markers: "markers.json",
   scenarios: "scenarios.json",
   block: "block.json",
   checkout: "checkout.json",
@@ -48,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({
@@ -181,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;
@@ -214,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));
@@ -256,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;
@@ -277,17 +287,30 @@ async function readJson(directory: string, name: string, required: boolean) {
   }
 }
 
-/** The animation a folder holds, as a block's fields, checked as a publish would be. */
+/** 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> {
-  const [html, frames, scenarios, block] = await Promise.all([
+): 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),
   ]);
 
+  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.`);
 
@@ -295,10 +318,13 @@ export async function readAnimationFolder(
 
   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;
 
@@ -329,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}`;
@@ -337,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(
@@ -357,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(
@@ -378,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);
@@ -398,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)
diff --git a/packages/review/src/review-api/animation-references.test.ts b/packages/review/src/review-api/animation-references.test.ts
index b67ac087dd..c072932ea9 100644
--- a/packages/review/src/review-api/animation-references.test.ts
+++ b/packages/review/src/review-api/animation-references.test.ts
@@ -96,7 +96,7 @@ describe("the reference animations are what the API accepts", () => {
   it("inserts every reference through the API", async () => {
     for (const reference of await readAnimationReferences()) {
       const fields = await readAnimationFolder(reference.directory);
-      const content: JsonObject = { type: "animation", ...fields };
+      const content: JsonObject = { ...fields };
 
       if (isJsonObject(fields.code))
         content.code = Object.fromEntries(
diff --git a/packages/review/src/review-api/authoring-tools.ts b/packages/review/src/review-api/authoring-tools.ts
index 7132c02697..fde3260a69 100644
--- a/packages/review/src/review-api/authoring-tools.ts
+++ b/packages/review/src/review-api/authoring-tools.ts
@@ -52,7 +52,7 @@ export function authoringTools(
       "While a reader may be watching, write small and often: one paragraph per edit. Insert a new diagram whole. Change one already drawn a unit at a time (a flow_node, flow_edge or step, with parentId naming the diagram), and link each added flow_node to a node already drawn.",
       ...(animationsEnabled
         ? [
-            "An animation is edited as files: review_checkout writes it to a folder, you edit the files with your own file tools, and an edit with fromFiles naming that folder publishes it in place of content or changes. Publish the same folder again after each round of edits.",
+            "An animation or clip is edited as files: review_checkout writes it to a folder, you edit the files with your own file tools, and an edit with fromFiles naming that folder publishes it in place of content or changes. Publish the same folder again after each round of edits.",
           ]
         : []),
     ].join("\n"),
@@ -177,7 +177,7 @@ export function authoringTools(
       ? [
           tool(
             "checkout",
-            "Write an animation to a folder of files to edit with your own file tools: animation.html (its html), frames.json (its frames, each with its data), scenarios.json and block.json (title, code, height, pins). Then publish the folder with review_edit, giving fromFiles instead of content or changes. dir defaults to a folder Whiteboard manages; checking out again overwrites it. A publish is refused if the animation changed after the checkout.",
+            "Write an animation or clip to a folder of files to edit with your own file tools: animation.html (its html), frames.json (an animation's frames, each with its data) or markers.json (a clip's markers), scenarios.json and block.json (title, code, height, pins). Then publish the folder with review_edit, giving fromFiles instead of content or changes. dir defaults to a folder Whiteboard manages; checking out again overwrites it. A publish is refused if the block changed after the checkout.",
             z.strictObject({ ...review, targetId: id, dir: id.optional() }),
             "GET",
             "/:reviewId/inspect",
@@ -244,7 +244,7 @@ function withDraftFiles(edit: ReturnType<typeof publishedEdits>) {
     .string()
     .min(1)
     .describe(
-      "An animation's draft folder, from review_checkout or written yourself: publishes its files as the content (insert, replace) or changes (update).",
+      "An animation's or clip's draft folder, from review_checkout or written yourself: publishes its files as the content (insert, replace) or changes (update). frames.json makes it an animation, markers.json a clip.",
     );
 
   const [insert, replace, update, move, remove] = edit.options;
diff --git a/packages/review/src/review-api/document-text.ts b/packages/review/src/review-api/document-text.ts
index 2cd5d80be3..d8cbcc6bc4 100644
--- a/packages/review/src/review-api/document-text.ts
+++ b/packages/review/src/review-api/document-text.ts
@@ -201,21 +201,36 @@ export function documentText(
           );
         break;
       case "animation":
-        for (const [index, frame] of element.frames.entries()) {
-          detail(
-            `Frame ${index + 1} [${frame.key}]: ${frame.title}${frame.caption ? ` — ${frame.caption}` : ""}`,
-          );
+      case "clip":
+        if (element.type === "animation") {
+          for (const [index, frame] of element.frames.entries()) {
+            detail(
+              `Frame ${index + 1} [${frame.key}]: ${frame.title}${frame.caption ? ` — ${frame.caption}` : ""}`,
+            );
 
-          if (frame.code) write(depth + 2, `Code: ${frame.code.join(", ")}`);
+            if (frame.code) write(depth + 2, `Code: ${frame.code.join(", ")}`);
 
-          if (detailed && frame.data !== undefined)
-            write(depth + 2, `Data: ${JSON.stringify(frame.data)}`);
-        }
+            if (detailed && frame.data !== undefined)
+              write(depth + 2, `Data: ${JSON.stringify(frame.data)}`);
+          }
 
-        for (const scenario of element.scenarios ?? [])
-          detail(
-            `Scenario [${scenario.key}] ${scenario.label}: ${scenario.frames.join(" → ")}`,
-          );
+          for (const scenario of element.scenarios ?? [])
+            detail(
+              `Scenario [${scenario.key}] ${scenario.label}: ${scenario.frames.join(" → ")}`,
+            );
+        } else {
+          for (const [index, marker] of element.markers.entries()) {
+            detail(
+              `Marker ${index + 1} [${marker.key}]: ${marker.title}${marker.caption ? ` — ${marker.caption}` : ""}`,
+            );
+
+            if (marker.code)
+              write(depth + 2, `Code: ${marker.code.join(", ")}`);
+          }
+
+          for (const scenario of element.scenarios ?? [])
+            detail(`Scenario [${scenario.key}] ${scenario.label}`);
+        }
 
         if (runs) {
           const run =
diff --git a/packages/review/src/review-api/http.ts b/packages/review/src/review-api/http.ts
index dd27c812a7..c223314437 100644
--- a/packages/review/src/review-api/http.ts
+++ b/packages/review/src/review-api/http.ts
@@ -2170,12 +2170,15 @@ export function createReviewApi(
             )
           : undefined;
 
+      const animated = (type: string | undefined) =>
+        type === "animation" || type === "clip";
+
       if (
-        incoming.some((element) => element.type === "animation") ||
-        target?.type === "animation"
+        incoming.some((element) => animated(element.type)) ||
+        animated(target?.type)
       )
         throw new ReviewInputError(
-          "Animation authoring is disabled. Enable Animations in Settings under Experimental Features to edit animations. Existing animations can still be viewed.",
+          "Animation authoring is disabled. Enable Animations in Settings under Experimental Features to edit animations and clips. Existing ones can still be viewed.",
           409,
         );
     }
diff --git a/packages/review/src/review-api/instructions.ts b/packages/review/src/review-api/instructions.ts
index d886eddd71..269d1292d1 100644
--- a/packages/review/src/review-api/instructions.ts
+++ b/packages/review/src/review-api/instructions.ts
@@ -30,7 +30,7 @@ export interface InstructionContext {
 /** Keep disabled experimental components out of agent guidance. */
 export const desktopBlockTypes = (animationsEnabled: boolean) =>
   writableBlockTypes.filter(
-    (type) => animationsEnabled || type !== "animation",
+    (type) => animationsEnabled || (type !== "animation" && type !== "clip"),
   );
 
 const COMPONENT_EXAMPLE =
diff --git a/packages/whiteboard-document/src/blocks/animation.ts b/packages/whiteboard-document/src/blocks/animation.ts
index 1439d0e42f..1621693dec 100644
--- a/packages/whiteboard-document/src/blocks/animation.ts
+++ b/packages/whiteboard-document/src/blocks/animation.ts
@@ -11,7 +11,7 @@ import {
 } from "./definition.js";
 
 /** A name the animation's script passes to the `whiteboard` API. */
-const handle = z
+export const handle = z
   .string()
   .regex(
     /^[A-Za-z][\w-]{0,63}$/,
@@ -85,7 +85,9 @@ export const animationScenarioSchema = z.strictObject({
 
 export type AnimationScenario = z.infer<typeof animationScenarioSchema>;
 
-const animationCodeSchema = z.union([
+/** One named source range of an animation or clip: an anchor, or one with
+ * the label it opens under. */
+export const animationCodeSchema = z.union([
   anchorSchema,
   z.strictObject({
     source: anchorSchema,
diff --git a/packages/whiteboard-document/src/blocks/clip.test.ts b/packages/whiteboard-document/src/blocks/clip.test.ts
new file mode 100644
index 0000000000..39a9cd8746
--- /dev/null
+++ b/packages/whiteboard-document/src/blocks/clip.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+
+import { checkReferences, documentSchema } from "../index.js";
+import { ReviewInputError } from "../input-error.js";
+
+const clip = {
+  type: "clip",
+  title: "A request",
+  html: "<script>whiteboard.clip().marker('sent').marker('done');</script>",
+  markers: [
+    { key: "sent", title: "Sent", code: ["send"] },
+    { key: "done", title: "Done", caption: "It lands." },
+  ],
+  scenarios: [
+    { key: "fast", label: "Fast" },
+    { key: "slow", label: "Slow" },
+  ],
+  code: { send: "head/send.ts#L1" },
+};
+
+describe("clip", () => {
+  it("parses with its markers and scenarios, and passes its check", () => {
+    const [block] = documentSchema.parse([clip]);
+
+    expect(block).toMatchObject({
+      type: "clip",
+      markers: clip.markers,
+      scenarios: clip.scenarios,
+      height: "auto",
+    });
+    expect(() => checkReferences([block!])).not.toThrow();
+  });
+
+  it("refuses frame fields on a marker", () => {
+    expect(() =>
+      documentSchema.parse([
+        { ...clip, markers: [{ key: "sent", title: "Sent", duration: 900 }] },
+      ]),
+    ).toThrow(/duration/);
+  });
+
+  it("rejects duplicate marker keys", () => {
+    const [block] = documentSchema.parse([
+      {
+        ...clip,
+        markers: [
+          { key: "sent", title: "Sent" },
+          { key: "sent", title: "Again" },
+        ],
+      },
+    ]);
+
+    expect(() => checkReferences([block!])).toThrow(
+      new ReviewInputError("Clip marker keys must be unique within the clip."),
+    );
+  });
+
+  it("rejects a marker naming code the clip does not", () => {
+    const [block] = documentSchema.parse([
+      { ...clip, markers: [{ key: "sent", title: "Sent", code: ["ghost"] }] },
+    ]);
+
+    expect(() => checkReferences([block!])).toThrow(
+      new ReviewInputError(
+        'Marker "sent" lists code "ghost", which the clip\'s code does not name.',
+      ),
+    );
+  });
+
+  it("rejects duplicate scenario keys", () => {
+    const [block] = documentSchema.parse([
+      {
+        ...clip,
+        scenarios: [
+          { key: "fast", label: "Fast" },
+          { key: "fast", label: "Also fast" },
+        ],
+      },
+    ]);
+
+    expect(() => checkReferences([block!])).toThrow(
+      new ReviewInputError(
+        "Clip scenario keys must be unique within the clip.",
+      ),
+    );
+  });
+});
diff --git a/packages/whiteboard-document/src/blocks/clip.ts b/packages/whiteboard-document/src/blocks/clip.ts
new file mode 100644
index 0000000000..adee77060f
--- /dev/null
+++ b/packages/whiteboard-document/src/blocks/clip.ts
@@ -0,0 +1,125 @@
+import { z } from "zod";
+
+import { ReviewInputError } from "../input-error.js";
+import { animationCodeSchema, handle } from "./animation.js";
+import {
+  type BlockDefinition,
+  defineBlock,
+  elementPins,
+  label,
+  text,
+} from "./definition.js";
+
+export const clipMarkerSchema = z.strictObject({
+  key: handle.describe(
+    "Names the marker for the html: clip.marker(key) places it in time, and whiteboard.on(key, ...) runs as the playhead reaches it.",
+  ),
+  title: label.describe(
+    "What the step strip under the clip shows for this marker, e.g. Lock taken. Keep it to a few words.",
+  ),
+  caption: text
+    .optional()
+    .describe("One or two short sentences shown under the clip."),
+  code: z
+    .array(handle)
+    .min(1)
+    .max(8)
+    .optional()
+    .describe(
+      "The code this moment shows, by name in the block's code. The tour stops here with it.",
+    ),
+});
+
+export type ClipMarker = z.infer<typeof clipMarkerSchema>;
+
+export const clipScenarioSchema = z.strictObject({
+  key: handle.describe(
+    "Names the scenario: whiteboard.clip(key) builds its timeline.",
+  ),
+  label: z
+    .string()
+    .min(1)
+    .max(32)
+    .describe(
+      "What the reader picks above the clip, e.g. Slow replica. Keep it short.",
+    ),
+});
+
+export type ClipScenario = z.infer<typeof clipScenarioSchema>;
+
+export const clipSchema = defineBlock("clip", {
+  title: label,
+  html: text
+    .min(1)
+    .max(200_000)
+    .describe(
+      'The clip\'s body markup: elements, <style> and <script>. Its script builds the timeline with whiteboard.clip() in a sandboxed iframe; see session_get_instructions({topic:"animation"}).',
+    ),
+  markers: z
+    .array(clipMarkerSchema)
+    .min(1)
+    .max(60)
+    .describe(
+      "The named moments the reader jumps between, with unique, stable keys. The script places each one in time.",
+    ),
+  scenarios: z
+    .array(clipScenarioSchema)
+    .min(2)
+    .max(8)
+    .optional()
+    .describe(
+      "Alternate timelines the script builds, one per key. The whiteboard draws a labelled scenario picker above the clip and starts on the first one.",
+    ),
+  code: z
+    .record(handle, animationCodeSchema)
+    .default({})
+    .describe(
+      "Source ranges by name, each an anchor or {source, label}: the label names the range where it opens. Elements with data-wb-open open them; data-wb-code shows one inline.",
+    ),
+  height: z
+    .union([z.literal("auto"), z.number().int().min(120).max(1200)])
+    .default("auto")
+    .describe(
+      "Fit the clip to its content by default, or set a fixed height in CSS pixels.",
+    ),
+  pins: elementPins,
+});
+
+export type ClipBlock = z.infer<typeof clipSchema>;
+
+export const clip = {
+  type: "clip",
+  reference: [
+    '- clip {title, html, markers: {key, title (a few words), caption?, code? ([names in code] this moment shows)}[] (1 to 60), scenarios?: {key, label}[] (2 to 8, each a timeline the script builds), code?: {name: anchor | {source: anchor, label}}, height?: "auto" (default) | number (120 to 1200 CSS px), pins?}; the script places every marker in time',
+    'Use a clip for continuous motion where the timing itself is the point: a token crossing a system, a race, a queue draining. The reader plays it, pauses it and jumps between its markers. Use an animation instead when the reader needs to compare discrete states. Read session_get_instructions({topic:"animation"}) before writing one.',
+  ],
+  schema: clipSchema,
+  check(block: ClipBlock) {
+    if (
+      new Set(block.markers.map((marker) => marker.key)).size !==
+      block.markers.length
+    )
+      throw new ReviewInputError(
+        "Clip marker keys must be unique within the clip.",
+      );
+
+    for (const marker of block.markers) {
+      const unknown = marker.code?.find((name) => !(name in block.code));
+
+      if (unknown)
+        throw new ReviewInputError(
+          `Marker "${marker.key}" lists code "${unknown}", which the clip's code does not name.`,
+        );
+    }
+
+    const scenarios = block.scenarios ?? [];
+
+    if (
+      new Set(scenarios.map((scenario) => scenario.key)).size !==
+      scenarios.length
+    )
+      throw new ReviewInputError(
+        "Clip scenario keys must be unique within the clip.",
+      );
+  },
+} satisfies BlockDefinition<ClipBlock>;
diff --git a/packages/whiteboard-document/src/blocks/index.ts b/packages/whiteboard-document/src/blocks/index.ts
index 756be8f296..09ca77dcc1 100644
--- a/packages/whiteboard-document/src/blocks/index.ts
+++ b/packages/whiteboard-document/src/blocks/index.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
 import { animation } from "./animation.js";
 import { call_stack_diff } from "./call_stack_diff.js";
 import { type CalloutBlock, callout, calloutSchema } from "./callout.js";
+import { clip } from "./clip.js";
 import { code } from "./code.js";
 import { code_peek } from "./code_peek.js";
 import { database_lens } from "./database_lens.js";
@@ -30,6 +31,7 @@ export const leafSchema = z.discriminatedUnion("type", [
   software_map.schema,
   flow_diagram.schema,
   animation.schema,
+  clip.schema,
 ]);
 
 export type LeafBlock = z.infer<typeof leafSchema>;
@@ -56,6 +58,7 @@ export const blocks = {
   software_map,
   flow_diagram,
   animation,
+  clip,
   section,
   callout,
 } satisfies Definitions;
@@ -81,6 +84,7 @@ const referenceOrder: readonly BlockType[] = [
   "call_stack_diff",
   "database_lens",
   "animation",
+  "clip",
 ];
 
 /** The selected blocks' fields, for agent guidance. */
diff --git a/packages/whiteboard-document/src/document.ts b/packages/whiteboard-document/src/document.ts
index 2a43480c0e..30011f67c0 100644
--- a/packages/whiteboard-document/src/document.ts
+++ b/packages/whiteboard-document/src/document.ts
@@ -203,8 +203,8 @@ const unitTypes = new Set(["step", "flow_node", "flow_edge"]);
 export const isUnit = (element: Element): element is Unit =>
   unitTypes.has(element.type);
 
-/** The reference id of a code peek an animation names: the canvas finds the
- * peek's resolved anchor by it. */
+/** The reference id of a code peek an animation or clip names: the canvas
+ * finds the peek's resolved anchor by it. */
 export const animationCodeId = (blockId: string, name: string) =>
   `${blockId}:code:${name}`;
 
@@ -533,7 +533,7 @@ function documentReferences(
         ),
       );
 
-    if (element.type === "animation")
+    if (element.type === "animation" || element.type === "clip")
       return Object.entries(element.code).flatMap(([name, entry]) => {
         const code = animationCode(entry);
 

From 52cf520878b32d19c4fed0a9cc284485f5ec39ba Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Sun, 1 Nov 2026 13:52:15 -0500
Subject: [PATCH 6/6] Keep a streamed clip's paint-in alive, and the live
 queue's head

A clip jumps to its first marker as it activates, without motion, and
that jump finished every animation on the page a frame later, including
the paint-in a streamed clip had just begun: on a live board a new clip
appeared at once. Paint animations now sit out that finish, as they do a
frame shown without motion.

The draw queue lost its head on a live board too. An animation released
the queue when it unmounted, which under StrictMode's simulated unmount
ran at mount; and updaters told the time themselves, so one React ran
again ended a step early. The release on unmount goes (the cap covers a
block that leaves mid-paint), every updater reads the clock before it is
queued, and a control that would change nothing queues nothing.

A stage under the system theme read "light dark" as dark on a light
page; it now follows the reader's preference.

Agent-Session: b315a4f8-1333-461c-9be6-366ceb231b7f
---
 .../animation/animation-block.browser.test.ts | 18 ++++++++++++
 .../app/src/animation/animation-block.tsx     | 18 ++++++++++--
 .../animation-paint.browser.test.tsx          | 26 +++++++++++++++++
 .../review/app/src/animation/stage-runtime.ts | 28 ++++++++++++++-----
 .../review/app/src/draw-queue-provider.tsx    | 25 +++++++++++++++--
 5 files changed, 102 insertions(+), 13 deletions(-)
 create mode 100644 packages/review/app/src/animation/animation-block.browser.test.ts

diff --git a/packages/review/app/src/animation/animation-block.browser.test.ts b/packages/review/app/src/animation/animation-block.browser.test.ts
new file mode 100644
index 0000000000..ce3eb75096
--- /dev/null
+++ b/packages/review/app/src/animation/animation-block.browser.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+
+import { schemeOf } from "./animation-block";
+
+describe("schemeOf", () => {
+  it("takes the host's own light or dark palette", () => {
+    expect(schemeOf("dark")).toBe("dark");
+    expect(schemeOf("light")).toBe("light");
+    expect(schemeOf("normal")).toBe("light");
+  });
+
+  it("follows the reader's preference where the host names both", () => {
+    const dark = matchMedia("(prefers-color-scheme: dark)").matches;
+
+    expect(schemeOf("light dark")).toBe(dark ? "dark" : "light");
+    expect(schemeOf("dark light")).toBe(dark ? "dark" : "light");
+  });
+});
diff --git a/packages/review/app/src/animation/animation-block.tsx b/packages/review/app/src/animation/animation-block.tsx
index 58b0b16654..5b4df5829b 100644
--- a/packages/review/app/src/animation/animation-block.tsx
+++ b/packages/review/app/src/animation/animation-block.tsx
@@ -68,6 +68,7 @@ import {
   type HostMessage,
   STAGE_BOOT,
   type SlotLayout,
+  type StageColorScheme,
   type StageInit,
   type StageMessage,
   stageMessageSchema,
@@ -127,10 +128,23 @@ function readTheme(element: Element): Pick<StageInit, "theme" | "colorScheme"> {
         computed.getPropertyValue(property).trim(),
       ]),
     ),
-    colorScheme: computed.colorScheme.includes("dark") ? "dark" : "light",
+    colorScheme: schemeOf(computed.colorScheme),
   };
 }
 
+// The host's own light or dark palette, or the reader's where it follows the
+// system: "light dark" names both, and would read as dark on a light page.
+export function schemeOf(colorScheme: string): StageColorScheme {
+  const named = colorScheme.split(/\s+/);
+
+  if (named.includes("light") && named.includes("dark"))
+    return matchMedia("(prefers-color-scheme: dark)").matches
+      ? "dark"
+      : "light";
+
+  return named.includes("dark") ? "dark" : "light";
+}
+
 const reducedMotion = () =>
   matchMedia("(prefers-reduced-motion: reduce)").matches;
 
@@ -320,8 +334,6 @@ function StageBlock({
 
   useEffect(() => onPhase(), [motion]);
 
-  useEffect(() => endPaint, [endPaint]);
-
   const openTour = () => {
     if (!tour || !frameAnchor) return;
 
diff --git a/packages/review/app/src/animation/animation-paint.browser.test.tsx b/packages/review/app/src/animation/animation-paint.browser.test.tsx
index 15719c6377..c2a881aec6 100644
--- a/packages/review/app/src/animation/animation-paint.browser.test.tsx
+++ b/packages/review/app/src/animation/animation-paint.browser.test.tsx
@@ -233,6 +233,32 @@ it("paints a streamed clip in at time 0, as an animation, and moves on", async (
   expect(new DOMMatrix(slot("Lead note")!.style.transform).m41).toBe(start);
 });
 
+it("paints a clip that arrives with the queue idle, past its jump to the first marker", async () => {
+  const clip = documentSchema.parse([
+    {
+      id: "anim",
+      type: "clip",
+      title: "Paint",
+      markers: [{ key: "a", title: "First" }],
+      html: `${nodes}<div id="slot" data-wb-block="note"></div><script>
+        whiteboard.clip().marker("a").add("#slot", { translateX: [0, 80], duration: 400 });
+      </script>`,
+    },
+  ])[0]!;
+
+  await render(null, [before, note, late]);
+  await render(insert("anim", "clip"), [before, clip, note, late]);
+  expect(motion()).toBe("painting");
+
+  // Activating the clip jumps to its first marker without motion, which
+  // finishes the page's other animations: the paint still runs its course.
+  await waitFor(() => expect(slot("Lead note")).toBeTruthy());
+  await new Promise((resolve) => setTimeout(resolve, 150));
+  expect(shown("Lead note")).toBe(false);
+  await waitFor(() => expect(shown("Lead note")).toBe(true));
+  await waitFor(() => expect(motion()).toBeUndefined());
+});
+
 it("shows an animation loaded with the board at once, without painting", async () => {
   await render(null, [
     animationBlock(`${nodes}<div data-wb-block="note"></div>`),
diff --git a/packages/review/app/src/animation/stage-runtime.ts b/packages/review/app/src/animation/stage-runtime.ts
index 0bb1a8d0f7..7e49e139be 100644
--- a/packages/review/app/src/animation/stage-runtime.ts
+++ b/packages/review/app/src/animation/stage-runtime.ts
@@ -672,6 +672,18 @@ export function stageRuntime(port: MessagePort): void {
   const finite = (animation: Animation) =>
     Number.isFinite(animation.effect?.getComputedTiming().endTime ?? Infinity);
 
+  // The default painter's animations. A frame or marker reached without
+  // motion finishes every other animation on the page, never these: a clip
+  // jumps to its first marker as it activates, in the same frame its paint
+  // begins.
+  const paintAnimations = new Set<Animation>();
+
+  const finishOthers = () => {
+    for (const animation of document.getAnimations())
+      if (finite(animation) && !paintAnimations.has(animation))
+        animation.finish();
+  };
+
   const lib = (): typeof Anime => {
     const anime = window.anime;
 
@@ -1049,9 +1061,7 @@ export function stageRuntime(port: MessagePort): void {
 
     if (skip)
       nextFrame().then(() => {
-        for (const animation of document.getAnimations())
-          if (finite(animation)) animation.finish();
-
+        finishOthers();
         root.removeAttribute("data-wb-instant");
       });
 
@@ -1993,9 +2003,7 @@ export function stageRuntime(port: MessagePort): void {
       await nextFrame();
 
       if (instantMode) {
-        for (const animation of document.getAnimations())
-          if (finite(animation)) animation.finish();
-
+        finishOthers();
         await nextFrame();
         root.removeAttribute("data-wb-instant");
       } else {
@@ -2323,6 +2331,8 @@ export function stageRuntime(port: MessagePort): void {
       const custom = paintHandlers.size > 0 || paintTimeline !== undefined;
 
       if (!custom && !instant) started.push(...defaultPaint());
+
+      for (const animation of started) paintAnimations.add(animation);
       waits.push(playPaintTimeline(!instant), ...runPaintHandlers(instant));
 
       if (instant) {
@@ -2338,7 +2348,11 @@ export function stageRuntime(port: MessagePort): void {
     } catch (error) {
       fail(String(error));
     } finally {
-      for (const animation of started) animation.cancel();
+      for (const animation of started) {
+        animation.cancel();
+        paintAnimations.delete(animation);
+      }
+
       paintDone = true;
       post({ type: "painted" });
       wake();
diff --git a/packages/review/app/src/draw-queue-provider.tsx b/packages/review/app/src/draw-queue-provider.tsx
index 71654b8b67..1881f0a567 100644
--- a/packages/review/app/src/draw-queue-provider.tsx
+++ b/packages/review/app/src/draw-queue-provider.tsx
@@ -7,6 +7,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
 } from "react";
 
@@ -94,6 +95,10 @@ export function useMotionPhase(
  * the cursor the courier stands on (the head of the queue), and each
  * element's motion phase. Timers advance the queue; the pure model in
  * draw-queue.ts decides what happens. `undefined` is history: no queue.
+ *
+ * Every updater reads the clock before it is queued, never inside: React may
+ * run a queued updater again later, and one that told the time itself would
+ * then end a step early.
  */
 export function DrawQueueProvider({
   cursor,
@@ -110,6 +115,11 @@ export function DrawQueueProvider({
   children: ReactNode;
 }) {
   const [state, setState] = useState<DrawState>(EMPTY_QUEUE);
+  // The state as last rendered, for a control that must not queue an update
+  // it knows changes nothing: a stale no-op update can be replayed over a
+  // later arrival and lose it.
+  const stateRef = useRef(state);
+  stateRef.current = state;
 
   const [seen, setSeen] = useState<AuthoringCursor | null | undefined>(
     undefined,
@@ -123,7 +133,8 @@ export function DrawQueueProvider({
     if (!cursor) setState(EMPTY_QUEUE);
     else {
       const reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
-      setState((current) => arrive(current, cursor, clock.now(), reduced));
+      const now = clock.now();
+      setState((current) => arrive(current, cursor, now, reduced));
     }
   }
 
@@ -135,7 +146,10 @@ export function DrawQueueProvider({
     // A timer can fire a hair before its due time; the step it was set for
     // is due regardless, or the queue would stall with no timer to follow.
     const timer = clock.setTimeout(
-      () => setState((current) => tick(current, Math.max(due, clock.now()))),
+      () => {
+        const now = Math.max(due, clock.now());
+        setState((current) => tick(current, now));
+      },
       Math.max(0, due - clock.now()),
     );
 
@@ -143,7 +157,12 @@ export function DrawQueueProvider({
   }, [state, clock]);
 
   const onPainted = useCallback(
-    (id: string) => setState((current) => painted(current, id, clock.now())),
+    (id: string) => {
+      const now = clock.now();
+
+      if (painted(stateRef.current, id, now) === stateRef.current) return;
+      setState((current) => painted(current, id, now));
+    },
     [clock],
   );