From 46411d2eec86237c8281a3e2a7f3b3a3221ca2cd Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Tue, 27 Oct 2026 15:35:02 -0400
Subject: [PATCH 1/6] Pad animations and let them expand fullscreen

Give the animation stage 16px of padding so a drawing no longer runs into
the card's edges. The stage and its slot overlays sit in an inner box, so
host code peeks still line up.

Add an Expand button to the animation header. It portals the figure into a
fullscreen overlay over the canvas (themed, Escape closes, canvas scroll
locked), centres the drawing, and keeps a placeholder inline so the
document holds its place. Focus moves to Close on open and back to Expand
on close.

The stage iframe now inherits the page's color-scheme instead of "normal".
In dark themes the mismatch made Chromium paint an opaque backdrop behind
the frame, which the new padding exposed.

Agent-Session: 9433c530-a019-433a-95a7-428a25de521d
---
 .../app/src/animation/animation-block.tsx     | 192 ++++++++++++++----
 1 file changed, 155 insertions(+), 37 deletions(-)

diff --git a/packages/review/app/src/animation/animation-block.tsx b/packages/review/app/src/animation/animation-block.tsx
index fd22ad0e0..27251ad5d 100644
--- a/packages/review/app/src/animation/animation-block.tsx
+++ b/packages/review/app/src/animation/animation-block.tsx
@@ -2,6 +2,8 @@ import type { BlockProps } from "@canvas/blocks";
 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 { drawStyles } from "@canvas/draw-styles";
 import { useOptionalReviewPanel } from "@canvas/review-panel";
 import {
@@ -13,9 +15,11 @@ import {
   space,
   tracking,
 } from "@canvas/scale.stylex";
+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 { IconButton } from "@canvas/ui/button";
+import { Button, IconButton } from "@canvas/ui/button";
 import { useTooltip } from "@canvas/ui/tooltip";
 import { anchorSelection } from "@review/lens-selection";
 import { type Block, animationCodeId } from "@review/review-api/document";
@@ -30,6 +34,7 @@ import {
   useRef,
   useState,
 } from "react";
+import { createPortal } from "react-dom";
 
 import {
   type HostMessage,
@@ -195,6 +200,11 @@ export function AnimationBlock({
   const [contentHeight, setContentHeight] = useState(120);
   const [slots, setSlots] = useState<SlotLayout[]>([]);
   const [error, setError] = useState<string | null>(null);
+  // 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);
+  const closeRef = useRef<HTMLButtonElement>(null);
   const indexRef = useRef(index);
   indexRef.current = index;
 
@@ -471,6 +481,22 @@ export function AnimationBlock({
     if (!activeFrames.some((item) => item.key === frame.key)) go(0, true);
   }, [activeFrames, frame.key, go]);
 
+  const collapse = useCallback(() => setExpanded(null), []);
+
+  const { portalTarget } = useDiagramTourShell(expanded !== null, collapse);
+
+  // Focus follows the figure in and back out to the control that opened it.
+  const wasExpanded = useRef(false);
+
+  useEffect(() => {
+    if (expanded !== null) closeRef.current?.focus();
+    else if (wasExpanded.current) expandRef.current?.focus();
+
+    wasExpanded.current = expanded !== null;
+  }, [expanded]);
+
+  const fullscreen = expanded !== null && portalTarget !== null;
+
   const onKeyDown = (event: KeyboardEvent) => {
     if (event.key === "ArrowRight") go(activeIndex + 1, false);
     else if (event.key === "ArrowLeft") go(activeIndex - 1, false);
@@ -479,10 +505,15 @@ export function AnimationBlock({
     event.preventDefault();
   };
 
-  return (
+  const figure = (
     <figure
       ref={figureRef}
-      {...withClass("animation-block", styles.figure, drawStyles.blockChild)}
+      {...withClass(
+        "animation-block",
+        styles.figure,
+        fullscreen && styles.figureFullscreen,
+        drawStyles.blockChild,
+      )}
       aria-label={node.title}
     >
       <DiagramHeader
@@ -490,41 +521,66 @@ export function AnimationBlock({
         title={node.title}
         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>
+        }
       />
       <div
-        {...stylex.props(styles.stage)}
-        style={{ height: node.height === "auto" ? contentHeight : node.height }}
+        {...stylex.props(styles.stage, fullscreen && styles.stageFullscreen)}
       >
-        <iframe
-          key={stageKey}
-          ref={frameRef}
-          src={stageUrl}
-          title={node.title}
-          sandbox="allow-scripts"
-          onLoad={boot}
-          {...stylex.props(styles.frame)}
-        />
-        <div {...stylex.props(styles.overlays)}>
-          {slots.map((slot) => (
-            <SlotOverlay
-              key={slot.slot}
-              slot={slot}
-              onHeight={(height) =>
-                send({ type: "slot-size", slot: slot.slot, height })
-              }
-            >
-              {slot.kind === "code"
-                ? node.code[slot.ref] && (
-                    <CodePeekCard
-                      source={anchorSelection(node.code[slot.ref]!, node.pins)}
-                      heightMode="capped"
-                      xstyle={styles.peek}
-                    />
-                  )
-                : embeddable.get(slot.ref) &&
-                  children([embeddable.get(slot.ref)!])}
-            </SlotOverlay>
-          ))}
+        <div
+          {...stylex.props(styles.canvas)}
+          style={{
+            height: node.height === "auto" ? contentHeight : node.height,
+          }}
+        >
+          <iframe
+            key={stageKey}
+            ref={frameRef}
+            src={stageUrl}
+            title={node.title}
+            sandbox="allow-scripts"
+            onLoad={boot}
+            {...stylex.props(styles.frame)}
+          />
+          <div {...stylex.props(styles.overlays)}>
+            {slots.map((slot) => (
+              <SlotOverlay
+                key={slot.slot}
+                slot={slot}
+                onHeight={(height) =>
+                  send({ type: "slot-size", slot: slot.slot, height })
+                }
+              >
+                {slot.kind === "code"
+                  ? node.code[slot.ref] && (
+                      <CodePeekCard
+                        source={anchorSelection(
+                          node.code[slot.ref]!,
+                          node.pins,
+                        )}
+                        heightMode="capped"
+                        xstyle={styles.peek}
+                      />
+                    )
+                  : embeddable.get(slot.ref) &&
+                    children([embeddable.get(slot.ref)!])}
+              </SlotOverlay>
+            ))}
+          </div>
         </div>
       </div>
       {steps && (
@@ -610,6 +666,33 @@ export function AnimationBlock({
       )}
     </figure>
   );
+
+  if (!fullscreen) return figure;
+
+  // Portaled outside .review-app, so it carries the theme itself, as the
+  // diagram tour overlay does.
+  return (
+    <>
+      <div aria-hidden="true" style={{ height: expanded }} />
+      {createPortal(
+        <div
+          {...withClass(
+            `review-app--theme-${theme}`,
+            themeStyles.vars,
+            themeClass(theme),
+            styles.overlay,
+            shellStyles.clearsWindowControls,
+          )}
+          role="dialog"
+          aria-modal="true"
+          aria-label={node.title ?? "Animation"}
+        >
+          {figure}
+        </div>,
+        portalTarget,
+      )}
+    </>
+  );
 }
 
 /** A host component drawn where the stage put its placeholder. */
@@ -732,10 +815,43 @@ const styles = stylex.create({
     textOverflow: { default: null, [narrow]: "clip" },
     whiteSpace: { default: null, [narrow]: "normal" },
   },
+  figureFullscreen: {
+    display: "flex",
+    flex: "1 1 auto",
+    flexDirection: "column",
+    minHeight: 0,
+    margin: 0,
+  },
+  // Room around the stage so its drawing does not run into the card's edges.
   stage: {
+    padding: space.s16,
+    backgroundColor: tokens.surface,
+  },
+  // Fullscreen, the stage takes the room the controls leave and centers the
+  // drawing in it, scrolling when the drawing is taller.
+  stageFullscreen: {
+    display: "flex",
+    flex: "1 1 auto",
+    flexDirection: "column",
+    justifyContent: "safe center",
+    minHeight: 0,
+    overflowY: "auto",
+    padding: { default: space.s32, [narrow]: space.s16 },
+  },
+  canvas: {
     position: "relative",
+    flex: "0 0 auto",
     overflow: "hidden",
-    backgroundColor: tokens.surface,
+  },
+  overlay: {
+    position: "fixed",
+    inset: 0,
+    zIndex: tokens.reviewDebugLayer,
+    boxSizing: "border-box",
+    display: "flex",
+    flexDirection: "column",
+    padding: { default: space.s24, [narrow]: space.s8 },
+    backgroundColor: tokens.bg,
   },
   frame: {
     display: "block",
@@ -743,7 +859,9 @@ const styles = stylex.create({
     height: "100%",
     borderWidth: 0,
     borderStyle: "none",
-    colorScheme: "normal",
+    // The page's own scheme, which is the one the stage is told to use. A
+    // frame whose scheme differs from its page gets an opaque backdrop.
+    colorScheme: "inherit",
     backgroundColor: tokens.transparent,
   },
   // Over the stage but out of the pointer's way; each slot takes it back.

From cb4dae65195f575a3628dc57ad4481ffbb052f3b Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Tue, 27 Oct 2026 15:35:05 -0400
Subject: [PATCH 2/6] Remove Mermaid (Pele) from animations

whiteboard.mermaid laid out large graphs, but it could not change labels
between frames, move chips along edges, or link to code, and it shrank wide
graphs until their labels were unreadable. Animations now have two modes:
the scene, and the toolkit with raw HTML. The guide sends a large graph to
a flow_diagram beside a scene that animates only the part that changes.

Drop the stage's Mermaid code and styles, the Pele loader, the pele
dependency and its test config, and the two Mermaid tests.

A stage that still calls whiteboard.mermaid() gets an error saying to
rebuild it as a scene or a flow_diagram, shown inline under the animation.
Animations are experimental and unreleased, so few boards have one.

Agent-Session: 9433c530-a019-433a-95a7-428a25de521d
---
 packages/review/app/package.json              |   1 -
 .../app/src/animation/animation-block.tsx     |  20 +-
 .../app/src/animation/stage-protocol.ts       |   3 +-
 .../review/app/src/animation/stage-runtime.ts | 264 +-----------------
 .../review/app/src/blocks.browser.test.tsx    |  86 ------
 packages/review/app/vitest.config.ts          |   6 +-
 packages/review/instructions/animation.md     |  56 +---
 pnpm-lock.yaml                                |   9 -
 8 files changed, 18 insertions(+), 427 deletions(-)

diff --git a/packages/review/app/package.json b/packages/review/app/package.json
index 12cf30139..896aa5b79 100644
--- a/packages/review/app/package.json
+++ b/packages/review/app/package.json
@@ -30,7 +30,6 @@
     "mdast-util-gfm": "3.1.0",
     "mdast-util-math": "3.0.0",
     "mdast-util-to-markdown": "2.1.2",
-    "pele": "1.6.0",
     "react": "19.2.5",
     "react-dom": "19.2.5",
     "zod": "catalog:",
diff --git a/packages/review/app/src/animation/animation-block.tsx b/packages/review/app/src/animation/animation-block.tsx
index 27251ad5d..1e4723138 100644
--- a/packages/review/app/src/animation/animation-block.tsx
+++ b/packages/review/app/src/animation/animation-block.tsx
@@ -59,16 +59,6 @@ const loadAnime = () =>
     (module) => module.default,
   ));
 
-let peleSource: Promise<string> | undefined;
-
-// Pele's source, for a stage whose scripts draw Mermaid: fetched by the first
-// one that does, as anime.js is by the first animation.
-const loadPele = () =>
-  (peleSource ??= import("pele/global?raw").then((module) => module.default));
-
-/** Whether a stage's html draws Mermaid, which is all that needs Pele. */
-const drawsMermaid = (html: string) => /\.mermaid\s*\(/.test(html);
-
 let fontRules: Promise<string> | undefined;
 
 const fontFiles = import.meta.glob<string>("../fonts/*.woff2", {
@@ -430,15 +420,11 @@ export function AnimationBlock({
       frame: indexRef.current,
     };
 
-    Promise.all([
-      loadAnime(),
-      drawsMermaid(node.html) ? loadPele() : undefined,
-      loadFonts(),
-    ]).then(
-      ([anime, pele, fonts]) =>
+    Promise.all([loadAnime(), loadFonts()]).then(
+      ([anime, fonts]) =>
         channel.port1.postMessage({
           ...init,
-          libraries: pele ? [anime, pele] : [anime],
+          libraries: [anime],
           fonts,
         } satisfies HostMessage),
       () => setError("The animation libraries or fonts could not be loaded."),
diff --git a/packages/review/app/src/animation/stage-protocol.ts b/packages/review/app/src/animation/stage-protocol.ts
index 2948adcf9..efe4f8368 100644
--- a/packages/review/app/src/animation/stage-protocol.ts
+++ b/packages/review/app/src/animation/stage-protocol.ts
@@ -34,8 +34,7 @@ export interface StageInit {
   fonts: string;
   reducedMotion: boolean;
   frame: number;
-  /** Library sources the stage runs before its own scripts: anime.js, and
-   * Pele when the stage draws Mermaid. */
+  /** Library sources the stage runs before its own scripts: anime.js. */
   libraries: string[];
 }
 
diff --git a/packages/review/app/src/animation/stage-runtime.ts b/packages/review/app/src/animation/stage-runtime.ts
index 9e7ab2b47..6c158849a 100644
--- a/packages/review/app/src/animation/stage-runtime.ts
+++ b/packages/review/app/src/animation/stage-runtime.ts
@@ -5,7 +5,6 @@ import type {
   Timeline,
   TimelinePosition,
 } from "animejs";
-import type * as Pele from "pele";
 
 import type {
   HostMessage,
@@ -20,8 +19,6 @@ declare global {
   interface Window {
     /** anime.js, in the animation stage only: its UMD build sets it. */
     anime?: typeof Anime;
-    /** Pele, in a stage whose scripts draw Mermaid: its global build sets it. */
-    pele?: typeof Pele;
   }
 }
 
@@ -192,40 +189,6 @@ export interface TokenOptions {
   only?: string[];
 }
 
-export interface MermaidOptions {
-  /** A selector or element to draw into; defaults to a new element at the
-   * end of document.body. */
-  container?: string | HTMLElement;
-}
-
-/** A Mermaid diagram from whiteboard.mermaid(). Its parts are named by their
- * Mermaid ids: a node's id, a named edge's (`a e1@--> b`), `L_<from>_<to>_<n>`
- * for an unnamed flowchart edge, and a sequence diagram's participants by name
- * and its messages i0, i1, … in order. Each method returns the diagram. */
-export interface MermaidDiagram {
-  readonly element: HTMLElement;
-  /** Every part id in the drawing. */
-  readonly ids: readonly string[];
-  /** Show the parts from this frame on; an edge draws in. */
-  enter(frame: string, ...ids: string[]): MermaidDiagram;
-  /** Hide the parts from this frame on. */
-  exit(frame: string, ...ids: string[]): MermaidDiagram;
-  /** Show the parts only in these frames. */
-  only(frames: string | readonly string[], ...ids: string[]): MermaidDiagram;
-  /** Ring the parts in these frames. */
-  highlight(
-    frames: string | readonly string[],
-    ...ids: string[]
-  ): MermaidDiagram;
-  /** Give the parts a tone from this frame on, until a later frame changes
-   * it; "none" clears it. */
-  on(
-    frame: string,
-    ids: string | readonly string[],
-    change: { tone: Tone | "none" },
-  ): MermaidDiagram;
-}
-
 /** One frame's part of the stage timeline. Numeric positions count from the
  * frame's start; strings are anime.js positions. */
 export interface FrameTimeline {
@@ -277,9 +240,8 @@ export interface WhiteboardShim {
   /** A grid of cards, edges and chips with consistent spacing and routing.
    * Prefer it to arrow/token for request-flow and state diagrams. */
   scene(options?: SceneOptions): Scene;
-  /** A Mermaid diagram, laid out for you and drawn in the stage's theme,
-   * whose parts enter, leave, light up and take tones by frame. */
-  mermaid(text: string, options?: MermaidOptions): MermaidDiagram;
+  /** 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. */
   timeline(key: string): FrameTimeline;
@@ -317,9 +279,8 @@ export function stageRuntime(port: MessagePort): void {
     post({ type: "error", message: message.slice(0, 2000) });
 
   addEventListener("error", (event) => {
-    // A ResizeObserver whose callback resizes what it watches, as Pele's
-    // does when it draws a diagram again, gets the rest next frame. Chromium
-    // reports that as an error, but nothing failed.
+    // A ResizeObserver whose callback resizes what it watches gets the rest
+    // next frame. Chromium reports that as an error, but nothing failed.
     if (event.message.startsWith("ResizeObserver loop")) return;
     fail(event.message);
   });
@@ -571,48 +532,6 @@ body {
 .wb-items > [data-wb-state="before"], .wb-items > [data-wb-state="after"],
 .wb-table tr[data-wb-state="before"], .wb-table tr[data-wb-state="after"] { display: none; }
 .wb-scene-top { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--wb-space-8); margin-bottom: var(--wb-space-4); }
-/* Mermaid, drawn by Pele in the stage's theme. A shape is a node's own
-   outline; an edge's line is drawn in by its dash offset, as an arrow is. */
-.wb-mermaid {
-  display: block;
-  padding: var(--wb-space-20) var(--wb-space-24);
-  --pele-bg: var(--wb-surface);
-  --pele-fg: var(--wb-ink);
-  --pele-muted: var(--wb-ink-muted);
-  --pele-line: var(--wb-ink-faint);
-  --pele-surface: var(--wb-surface);
-  --pele-surface-alt: var(--wb-well);
-  --pele-border: var(--wb-rule);
-  --pele-accent: var(--wb-accent);
-  --pele-font: var(--wb-font-mono);
-  --pele-font-mono: var(--wb-font-code);
-  --pele-radius: var(--wb-radius-surface);
-  --pele-series-1: var(--wb-accent);
-  --pele-series-2: var(--wb-added);
-  --pele-series-3: var(--wb-modified);
-  --pele-series-4: var(--wb-removed);
-}
-.wb-mermaid .pele-node > :is(rect, path, polygon, circle, ellipse) { transition: fill var(--wb-duration) ease, stroke var(--wb-duration) ease; }
-.wb-mermaid .pele-edge > path { transition: stroke var(--wb-duration) ease, fill var(--wb-duration) ease, stroke-dashoffset var(--wb-duration) ease; }
-.wb-mermaid .wb-draw { stroke-dasharray: var(--wb-length) var(--wb-length); }
-.wb-mermaid .pele-edge[data-wb-state="before"] > .wb-draw { stroke-dashoffset: var(--wb-length); }
-.wb-mermaid .pele-node[data-tone="accent"] > :is(rect, path, polygon, circle, ellipse) { stroke: var(--wb-accent); }
-.wb-mermaid .pele-node[data-tone="added"] > :is(rect, path, polygon, circle, ellipse) { fill: var(--wb-added-bg); stroke: var(--wb-added); }
-.wb-mermaid .pele-node[data-tone="removed"] > :is(rect, path, polygon, circle, ellipse) { fill: var(--wb-removed-bg); stroke: var(--wb-removed); }
-.wb-mermaid .pele-node[data-tone="modified"] > :is(rect, path, polygon, circle, ellipse) { fill: var(--wb-modified-bg); stroke: var(--wb-modified); }
-.wb-mermaid .pele-node[data-tone="muted"] { color: var(--wb-ink-muted); }
-.wb-mermaid .pele-node[data-tone="muted"] > :is(rect, path, polygon, circle, ellipse) { stroke-dasharray: 4 3; }
-.wb-mermaid .pele-node[data-wb-highlit] > :is(rect, path, polygon, circle, ellipse) { stroke: var(--wb-accent); stroke-width: 2; }
-.wb-mermaid .pele-edge[data-tone="accent"] > path:not(.pele-marker), .wb-mermaid .pele-edge[data-wb-highlit] > path:not(.pele-marker) { stroke: var(--wb-accent); }
-.wb-mermaid .pele-edge[data-tone="accent"] > .pele-marker, .wb-mermaid .pele-edge[data-wb-highlit] > .pele-marker { fill: var(--wb-accent); }
-.wb-mermaid .pele-edge[data-wb-highlit] > path:not(.pele-marker) { stroke-width: 2.5; }
-.wb-mermaid .pele-edge[data-tone="added"] > path:not(.pele-marker) { stroke: var(--wb-added); }
-.wb-mermaid .pele-edge[data-tone="added"] > .pele-marker { fill: var(--wb-added); }
-.wb-mermaid .pele-edge[data-tone="removed"] > path:not(.pele-marker) { stroke: var(--wb-removed); }
-.wb-mermaid .pele-edge[data-tone="removed"] > .pele-marker { fill: var(--wb-removed); }
-.wb-mermaid .pele-edge[data-tone="modified"] > path:not(.pele-marker) { stroke: var(--wb-modified); }
-.wb-mermaid .pele-edge[data-tone="modified"] > .pele-marker { fill: var(--wb-modified); }
-.wb-mermaid .pele-edge[data-tone="muted"] > path:not(.pele-marker) { stroke-dasharray: 4 3; }
 :root[data-wb-instant] *, :root[data-wb-instant] *::before, :root[data-wb-instant] *::after {
   transition: none !important;
   animation-duration: 0s !important;
@@ -2124,175 +2043,6 @@ body {
     };
   };
 
-  // Pele lays the diagram out and draws it again when its width or fonts
-  // change, so the frame attributes go back on after every drawing.
-  const mermaid = (text: string, options: MermaidOptions): MermaidDiagram => {
-    const pele = window.pele;
-
-    if (!pele)
-      throw new Error(
-        "whiteboard.mermaid(): Pele did not load. The stage loads it when the block's html calls .mermaid(.",
-      );
-
-    const element = document.createElement("div");
-    element.className = "wb-mermaid";
-    (options.container ? resolve(options.container) : document.body).append(
-      element,
-    );
-
-    type Mark = "enter" | "exit" | "only" | "highlight";
-
-    const marks = new Map<string, Map<Mark, string>>();
-    const tones = new Map<string, { at: number; tone: Tone | "none" }[]>();
-
-    const parts = (id: string) =>
-      element.querySelectorAll<SVGElement>(`svg [data-id="${CSS.escape(id)}"]`);
-
-    const ids = () => [
-      ...new Set(
-        [...element.querySelectorAll<SVGElement>("svg [data-id]")].map(
-          (part) => part.dataset.id!,
-        ),
-      ),
-    ];
-
-    const decorate = () => {
-      for (const [id, set] of marks)
-        for (const part of parts(id))
-          for (const [name, value] of set) part.dataset[name] = value;
-
-      // A solid edge that enters draws in along its length; a dashed one
-      // keeps its dashes and fades.
-      element
-        .querySelectorAll<SVGPathElement>(
-          ":is(.pele-edge[data-enter], .pele-edge[data-only]) > path:not(.pele-marker):not([stroke-dasharray])",
-        )
-        .forEach((path) => {
-          path.classList.add("wb-draw");
-          path.style.setProperty("--wb-length", String(path.getTotalLength()));
-        });
-    };
-
-    sceneAppliers.push((key) => {
-      const position = activeFrameIndex(key);
-
-      for (const [id, changes] of tones) {
-        let tone: Tone | "none" = "none";
-
-        for (const change of changes) {
-          const changeKey = init?.frames[change.at]?.key;
-          const changePosition = changeKey ? activeFrameIndex(changeKey) : -1;
-
-          if (changePosition >= 0 && changePosition <= position)
-            tone = change.tone;
-        }
-
-        for (const part of parts(id))
-          if (tone === "none") delete part.dataset.tone;
-          else part.dataset.tone = tone;
-      }
-    });
-
-    pele.mount(element, text, {
-      fontSize:
-        parseFloat(getComputedStyle(root).getPropertyValue("--wb-text-body")) ||
-        undefined,
-      links: false,
-      zoom: false,
-      onRender: () => {
-        decorate();
-
-        if (current >= 0) applyStates();
-      },
-      onError: (error) =>
-        fail(
-          `whiteboard.mermaid(): ${error instanceof Error ? error.message : String(error)}`,
-        ),
-    });
-
-    const check = (
-      method: string,
-      frames: readonly string[],
-      list: readonly string[],
-    ) => {
-      for (const frame of frames)
-        if (frameIndex(frame) < 0) throw new Error(`Unknown frame "${frame}".`);
-
-      if (!list.length)
-        throw new Error(`mermaid.${method}() needs at least one part id.`);
-
-      // Text that failed to draw has no parts; onError has said why.
-      if (!element.querySelector("svg")) return;
-      const known = ids();
-
-      for (const id of list)
-        if (!known.includes(id))
-          throw new Error(
-            `The diagram has no part "${id}". Its parts: ${known.join(", ")}.`,
-          );
-    };
-
-    const framesOf = (frames: string | readonly string[]) => [frames].flat();
-
-    const mark = (name: Mark, frames: string[], list: string[]) => {
-      check(name, frames, list);
-
-      for (const id of list) {
-        let set = marks.get(id);
-
-        if (!set) marks.set(id, (set = new Map()));
-
-        const value =
-          name === "highlight"
-            ? [...new Set([...(set.get(name)?.split(" ") ?? []), ...frames])]
-            : frames;
-
-        set.set(name, value.join(" "));
-      }
-
-      decorate();
-
-      if (current >= 0) applyStates();
-
-      return diagram;
-    };
-
-    const diagram: MermaidDiagram = {
-      element,
-      get ids() {
-        return ids();
-      },
-      enter: (frame, ...list) => mark("enter", [frame], list),
-      exit: (frame, ...list) => mark("exit", [frame], list),
-      only: (frames, ...list) => mark("only", framesOf(frames), list),
-      highlight: (frames, ...list) => mark("highlight", framesOf(frames), list),
-      on(frame, list, change) {
-        for (const key of Object.keys(change))
-          if (key !== "tone")
-            throw new Error(
-              `mermaid.on(): no change field "${key}" — use { tone }.`,
-            );
-
-        const targets = framesOf(list);
-        check("on", [frame], targets);
-
-        for (const id of targets) {
-          let changes = tones.get(id);
-
-          if (!changes) tones.set(id, (changes = []));
-          changes.push({ at: frameIndex(frame), tone: change.tone });
-          changes.sort((a, b) => a.at - b.at);
-        }
-
-        if (current >= 0) applyStates();
-
-        return diagram;
-      },
-    };
-
-    return diagram;
-  };
-
   const whiteboard: WhiteboardShim = {
     get frames() {
       return activeFrames();
@@ -2408,7 +2158,11 @@ body {
       travelAlong(resolve(token), record, frame, options);
     },
     scene: (options = {}) => scene(options),
-    mermaid: (text, options = {}) => mermaid(text, options),
+    mermaid: () => {
+      throw new Error(
+        "whiteboard.mermaid() was removed from animations. Rebuild the diagram as a whiteboard.scene, or show the whole graph in a flow_diagram block.",
+      );
+    },
   };
 
   Object.defineProperty(window, "whiteboard", { value: whiteboard });
diff --git a/packages/review/app/src/blocks.browser.test.tsx b/packages/review/app/src/blocks.browser.test.tsx
index 6e75222a4..01ff73e27 100644
--- a/packages/review/app/src/blocks.browser.test.tsx
+++ b/packages/review/app/src/blocks.browser.test.tsx
@@ -889,70 +889,6 @@ describe("block components", () => {
     ).toBe("200px");
   });
 
-  it("draws Mermaid in the stage's theme, revealing and lighting its parts by frame", async () => {
-    const { container } = await mountFixture("animation", {
-      document: [
-        {
-          id: "block-1",
-          type: "animation",
-          title: "Mermaid",
-          height: "auto",
-          pins: { repositoryId: "repo", base: "base", head: "head" },
-          frames: [
-            { key: "call", title: "Call" },
-            { key: "write", title: "Write" },
-          ],
-          code: { proof: "head/order.ts#L1" },
-          html: [
-            "<script>",
-            'const d=whiteboard.mermaid("flowchart LR\\n  api[API] e1@--> store[(Store)]");',
-            'd.highlight("call","api").enter("write","store","e1").on("write","store",{tone:"added"});',
-            'const proof=whiteboard.code("proof");proof.style.width="10px";document.body.append(proof);',
-            'const part=(id)=>d.element.querySelector(`.pele-node[data-id="${id}"], .pele-edge[data-id="${id}"]`);',
-            'const probe=document.createElement("span");probe.style.color="var(--wb-surface)";document.body.append(probe);',
-            'whiteboard.on("*",({frame})=>{setTimeout(()=>{const api=part("api"),store=part("store"),edge=part("e1");const shown=(el)=>getComputedStyle(el).visibility==="visible";const themed=getComputedStyle(api.querySelector("rect")).fill===getComputedStyle(probe).color;',
-            'const ok=frame.key==="call"?api.hasAttribute("data-wb-highlit")&&!shown(store)&&!shown(edge)&&store.dataset.tone===undefined:!api.hasAttribute("data-wb-highlit")&&shown(store)&&shown(edge)&&store.dataset.tone==="added";',
-            'proof.style.width=themed&&ok?(frame.key==="call"?"200px":"240px"):"100px"},600)});',
-            "</script>",
-          ].join(""),
-        },
-      ],
-    });
-
-    const width = () =>
-      container.querySelector<HTMLElement>("[data-animation-slot='code']")
-        ?.style.width;
-
-    const step = (label: string) =>
-      act(async () =>
-        container
-          .querySelector<HTMLButtonElement>(`button[aria-label='${label}']`)!
-          .click(),
-      );
-
-    const landed = () =>
-      settled(() =>
-        width() === "100px" || width() === "200px" || width() === "240px"
-          ? width()
-          : undefined,
-      );
-
-    expect(await landed()).toBe("200px");
-    await step("Next frame");
-    expect(
-      await settled(() =>
-        width() === "100px" || width() === "240px" ? width() : undefined,
-      ),
-    ).toBe("240px");
-    await step("Previous frame");
-    expect(
-      await settled(() =>
-        width() === "100px" || width() === "200px" ? width() : undefined,
-      ),
-    ).toBe("200px");
-    expect(container.querySelector("[role='alert']")).toBeNull();
-  });
-
   it("does not report a ResizeObserver that resizes its own target", async () => {
     const { container } = await mountFixture("animation", {
       document: [
@@ -984,28 +920,6 @@ describe("block components", () => {
     expect(container.querySelector("[role='alert']")).toBeNull();
   });
 
-  it("names a Mermaid part the diagram does not have", async () => {
-    const { container } = await mountFixture("animation", {
-      document: [
-        {
-          id: "block-1",
-          type: "animation",
-          title: "Mermaid typo",
-          height: "auto",
-          frames: [{ key: "only", title: "Only" }],
-          code: {},
-          html: '<script>whiteboard.mermaid("flowchart LR\\n  api --> store").enter("only","stor");</script>',
-        },
-      ],
-    });
-
-    expect(
-      await settled(
-        () => container.querySelector("[role='alert']")?.textContent,
-      ),
-    ).toMatch(/The diagram has no part "stor"\. Its parts: .*\bstore\b/);
-  });
-
   it("mounts a scene in its container and keeps narrow tables readable", async () => {
     const { container } = await mountFixture("animation", {
       document: [
diff --git a/packages/review/app/vitest.config.ts b/packages/review/app/vitest.config.ts
index f3c588e9b..56b229cfa 100644
--- a/packages/review/app/vitest.config.ts
+++ b/packages/review/app/vitest.config.ts
@@ -83,10 +83,10 @@ export default defineConfig({
       {
         plugins: [stylexDevCss(), react()],
         resolve: { alias, dedupe: ["react", "react-dom"] },
-        // The stage needs anime.js's and Pele's files as text; prebundling
-        // would make them modules.
+        // The stage needs anime.js's file as text; prebundling would make it
+        // a module.
         optimizeDeps: {
-          exclude: ["@animejs-bundles/anime.umd.min.js?raw", "pele/global?raw"],
+          exclude: ["@animejs-bundles/anime.umd.min.js?raw"],
         },
         test: {
           name: "browser",
diff --git a/packages/review/instructions/animation.md b/packages/review/instructions/animation.md
index 66cd8bd63..7b2f55efb 100644
--- a/packages/review/instructions/animation.md
+++ b/packages/review/instructions/animation.md
@@ -7,10 +7,9 @@ Choose where to start by what changes between the frames:
 | Build with | When the frames show |
 | --- | --- |
 | The scene (`whiteboard.scene`) | Up to about 8 cards whose notes, text and tones change, with chips moving along their edges. This is the default. |
-| Mermaid (`whiteboard.mermaid`) | A larger diagram, or one with branches or subgroups, whose nodes and edges appear, leave or light up. Its labels stay fixed: use the scene if they must change. |
 | The toolkit, style kit and raw HTML | Anything else: a chart, a timeline, a queue, a custom shape, or motion the scene cannot express (`arrow`, `token`, `travel`, `timeline`). |
 
-If no part of the drawing changes between frames, it is not an animation: use a `sequence` or `flow_diagram` block, whose steps and nodes link to code. The three mix: a stage can hold a scene, a Mermaid diagram and your own HTML together.
+If no part of the drawing changes between frames, it is not an animation: use a `sequence` or `flow_diagram` block, whose steps and nodes link to code. For a larger graph, animate only the part that changes as a scene, and put the whole graph in a `flow_diagram` beside it. The two mix: a stage can hold a scene and your own HTML together.
 
 ## The component
 
@@ -156,57 +155,6 @@ table.row(cells: string[], { enter?; exit?; only?; tone? }): HTMLTableRowElement
 
 The stage sets `data-frame="<key>"` on `<html>`, and `enter` / `exit` / `only` on any scene part decide the frames it shows in. They are states, not events, so they land right when the reader jumps to a frame or steps back. With `setSequence`, `enter` / `exit` and held `scene.on` changes follow active-sequence order, not declaration order: a change whose key is outside the active path does not apply, an inactive `enter` never occurs, and an inactive `exit` does not end an already-entered part. `only` and highlight lists always match exact stable keys. Visible cards keep their declared wide-grid cells. Hidden cards, store items and table rows collapse from layout; put replacing cards in the same cell. For an intentionally stable footprint, give the container a min-height or choose a fixed stage height with an appropriate scrolling plan.
 
-## Draw with Mermaid
-
-`whiteboard.mermaid(text)` draws a Mermaid diagram in the stage's theme, lays it out for you, and shows its parts frame by frame. Use it when the frames change a diagram too large to place card by card: a pipeline whose stages light up in turn, a state machine stepping through its states, a graph that grows as a request spreads. Use the scene when a few cards carry chips along their edges; Mermaid has no `send`.
-
-Mermaid nodes do not link to code. A diagram that stays the same in every frame belongs in a `flow_diagram` or `sequence` block, not in an animation.
-
-```html
-<script>
-  const d = whiteboard.mermaid(`flowchart LR
-    agent[Agent] e1@-->|call| api(Review API)
-    api e2@-->|edit op| store[(Store)]
-    store e3@-.->|snapshot| canvas[Canvas]`);
-
-  d.highlight("call", "agent", "e1")
-    .enter("write", "store", "e2")
-    .on("write", "store", { tone: "modified" })
-    .enter("watch", "canvas", "e3")
-    .on("watch", "canvas", { tone: "added" });
-</script>
-```
-
-Name a part by its Mermaid id:
-
-- A node by its id: `api` above.
-- An edge by the id you give it with `@`: `a e1@--> b`. Name every edge you will reveal or light up. An unnamed flowchart edge is `L_<from>_<to>_<n>`, counting from 0.
-- In a sequence diagram, a participant by its name, and a message as `i0`, `i1`, … in the order they appear.
-
-`d.ids` lists every part in the drawing, and a call naming a part the drawing lacks throws with that list.
-
-```ts
-whiteboard.mermaid(text: string, options?: { container?: string | Element }): MermaidDiagram;
-
-interface MermaidDiagram {
-  readonly element: HTMLElement;     // the diagram's box
-  readonly ids: readonly string[];
-  enter(frame: string, ...ids: string[]): MermaidDiagram;   // show from this frame on
-  exit(frame: string, ...ids: string[]): MermaidDiagram;    // hide from this frame on
-  only(frames: string | string[], ...ids: string[]): MermaidDiagram;
-  highlight(frames: string | string[], ...ids: string[]): MermaidDiagram;   // ring during these frames
-  on(frame: string, ids: string | string[], change: { tone: Tone | "none" }): MermaidDiagram;
-}
-```
-
-- The whole diagram is laid out once, from its full text, and parts that have not entered keep their place. Nothing moves as parts appear, so write the text for the last frame and reveal it frame by frame.
-- `enter`, `exit`, `only` and `highlight` follow the same rules as on scene parts, active sequences included. A solid edge draws in along its line as it enters; a dashed one fades in. An edge's label shows and hides with it.
-- `on` gives nodes and edges a tone from that frame on, as `scene.on` does; `"none"` clears it.
-- The diagram follows the stage's colors, faces and theme. Leave out Mermaid's `style`, `classDef` and `%%{init}%%` theming: they fix colors that do not follow light and dark. Use tones instead. Links and `click` actions do nothing in the stage.
-- The diagram fits its box's width and draws again when that width changes. A diagram that runs across and does not fit a narrow box is drawn running down instead of shrunk, so a `flowchart LR` may show top to bottom in the document column. Your frame changes carry over to the new drawing, but an element you hold from `d.element` does not: look parts up again inside a frame handler.
-- Any Mermaid diagram type draws. Highlights and tones color nodes and edges. Flowchart and sequence diagrams name their parts as above. State, class and ER diagrams name nodes by their ids too, but make up their own edge ids, such as `edge0`; read them from `d.ids`.
-- Text Mermaid cannot parse shows its error under the stage.
-
 ## Going further: the toolkit
 
 When the scene cannot express a layout, drop to the toolkit. It is the same drawing underneath, so it mixes with a scene: pass the card returned by `scene.actor`, `scene.store`, or `scene.table` directly to `arrow`, or use its public `id` or `element` fields where another API needs one.
@@ -340,6 +288,6 @@ Custom CSS should use the whiteboard's variables, never literal colors, sizes or
 - Each frame shows one idea; its title says what changed. 3 to 8 frames is usual.
 - Omit `height` unless the animation intentionally needs a fixed viewport; verify any numeric height in every frame and narrow layout.
 - Every frame reads correctly when reached by a jump, not only by playing.
-- Build as "Choose how to build it" says: a scene by default, Mermaid for a larger or branching diagram, and the toolkit or raw HTML for anything else.
+- Build as "Choose how to build it" says: a scene by default, and the toolkit or raw HTML for anything else.
 - In raw HTML, build from the style kit and the `--wb-*` variables; write no literal color, size or font name.
 - Script errors show under the stage. After writing, read the whiteboard back and fix any.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 744356d5a..71b7b4e08 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -477,9 +477,6 @@ importers:
       mdast-util-to-markdown:
         specifier: 2.1.2
         version: 2.1.2
-      pele:
-        specifier: 1.6.0
-        version: 1.6.0
       react:
         specifier: 19.2.5
         version: 19.2.5
@@ -3018,10 +3015,6 @@ packages:
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
-  pele@1.6.0:
-    resolution: {integrity: sha512-VfAiVItsOGlGhvnBfphdT28VCG7mXMZxQNOwAGsCtxI2ztbUsT39MraEOYjsapLxVETkdUZscm0DdotYDQMLdw==}
-    engines: {node: '>=20'}
-
   pend@1.2.0:
     resolution: {integrity: sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==}
 
@@ -5983,8 +5976,6 @@ snapshots:
 
   pathe@2.0.3: {}
 
-  pele@1.6.0: {}
-
   pend@1.2.0: {}
 
   pi-acp@0.0.34:

From d0532ab2ea74dd20bb0c9f32f2c532cafeabbc0f Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Tue, 27 Oct 2026 16:11:33 -0400
Subject: [PATCH 3/6] Wait for the stage to boot before stepping frames in the
 held-animations test

The frame count shows before the stage boots, so on a slow runner the test could step past frame a before its animation ran (CI: "a at 0"). Wait for the stage's ready message instead.

Agent-Session: a38a1758-2248-4cad-903d-6e0c59fef9ed
---
 packages/review/app/src/blocks.browser.test.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/review/app/src/blocks.browser.test.tsx b/packages/review/app/src/blocks.browser.test.tsx
index 0c7d3550b..00d13393b 100644
--- a/packages/review/app/src/blocks.browser.test.tsx
+++ b/packages/review/app/src/blocks.browser.test.tsx
@@ -1059,6 +1059,8 @@ describe("block components", () => {
   });
 
   it("lets go of a frame's finished animations on the next frame and keeps their end state", async () => {
+    using stages = tapStages();
+
     const { container } = await mountFixture("animation", {
       document: [
         {
@@ -1091,7 +1093,9 @@ describe("block components", () => {
       await new Promise((resolve) => setTimeout(resolve, 200));
     };
 
-    expect(await settled(() => text(container).includes("1 / 4"))).toBe(true);
+    // The count shows before the stage boots: wait for the stage itself, so
+    // frame a's animation has run before stepping on.
+    expect(await settled(() => stages.count("ready") === 1)).toBe(true);
     await new Promise((resolve) => setTimeout(resolve, 200));
     await next("2 / 4");
     await next("3 / 4");

From fc7fc123b588db95485a0c9e26853ebc4c04e482 Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Tue, 27 Oct 2026 16:20:01 -0400
Subject: [PATCH 4/6] Keep the selected block's hint on it as the block resizes

Agent-Session: a38a1758-2248-4cad-903d-6e0c59fef9ed
---
 .../review/app/src/board-editor/views.tsx     | 28 +++++++++++++------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/packages/review/app/src/board-editor/views.tsx b/packages/review/app/src/board-editor/views.tsx
index b8d6fe370..138e76e76 100644
--- a/packages/review/app/src/board-editor/views.tsx
+++ b/packages/review/app/src/board-editor/views.tsx
@@ -350,21 +350,33 @@ function RichBlock({
   const [hint, setHint] = useState<{ top: number; right: number }>();
 
   // The hint sits under the block's own card, which may be narrower than
-  // the page.
+  // the page, and follows it when the card resizes: an animation grows as
+  // its frames add code peeks.
   useLayoutEffect(() => {
-    const card = ref.current?.querySelector(
-      ":scope > [data-review-node-id] > *",
-    );
+    const container = ref.current;
+
+    const card = container?.querySelector(":scope > [data-review-node-id] > *");
 
-    if (!selected || !card || !ref.current) {
+    if (!selected || !card || !container) {
       setHint(undefined);
 
       return;
     }
 
-    const box = ref.current.getBoundingClientRect();
-    const rect = card.getBoundingClientRect();
-    setHint({ top: rect.bottom - box.top + 7, right: box.right - rect.right });
+    const measure = () => {
+      const box = container.getBoundingClientRect();
+      const rect = card.getBoundingClientRect();
+      setHint({
+        top: rect.bottom - box.top + 7,
+        right: box.right - rect.right,
+      });
+    };
+
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(card);
+
+    return () => observer.disconnect();
   }, [selected]);
 
   if (!renderer) return null;

From 3c2bc688fffce74c18bbef3fc2635d93b8325abd Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Tue, 27 Oct 2026 16:20:23 -0400
Subject: [PATCH 5/6] Fold wide scenes into fewer columns and open columns for
 link labels

Agent-Session: a38a1758-2248-4cad-903d-6e0c59fef9ed
---
 .../review/app/src/animation/stage-runtime.ts | 108 ++++++++++++++----
 .../review/app/src/blocks.browser.test.tsx    |  42 +++++++
 packages/review/instructions/animation.md     |   4 +-
 3 files changed, 128 insertions(+), 26 deletions(-)

diff --git a/packages/review/app/src/animation/stage-runtime.ts b/packages/review/app/src/animation/stage-runtime.ts
index c9d92da51..189606f58 100644
--- a/packages/review/app/src/animation/stage-runtime.ts
+++ b/packages/review/app/src/animation/stage-runtime.ts
@@ -532,6 +532,9 @@ body {
 .wb-scene { display: grid; gap: var(--wb-space-28) var(--wb-space-48); padding: var(--wb-space-24); align-items: start; justify-items: stretch; min-width: 0; }
 .wb-scene-compact { grid-template-columns: minmax(0, 1fr) !important; row-gap: var(--wb-space-48); }
 .wb-scene-compact > * { grid-column: 1 / -1 !important; grid-row: auto !important; }
+.wb-scene-fold { grid-template-columns: repeat(var(--wb-fold), minmax(0, 1fr)) !important; }
+.wb-scene-fold > * { grid-column: auto !important; grid-row: auto !important; }
+.wb-scene-fold > [data-wb-wide] { grid-column: 1 / -1 !important; }
 .wb-scene > [data-wb-state="before"], .wb-scene > [data-wb-state="after"],
 .wb-items > [data-wb-state="before"], .wb-items > [data-wb-state="after"],
 .wb-table tr[data-wb-state="before"], .wb-table tr[data-wb-state="after"] { display: none; }
@@ -1807,34 +1810,81 @@ body {
       grid,
     );
 
-    if (options.responsive !== false && columns > 1) {
-      // Preserve declared cells on wider layouts. In a narrow container, use
-      // reading order rather than shrinking cards, tables and labels to fit.
-      const reflow = () => {
-        const style = getComputedStyle(grid);
+    // Labels of links between cards in one row: the columns open up to fit
+    // the widest, so it sits between its cards rather than off its line.
+    const rowLabels = new Set<string>();
+
+    const sizeGap = () => {
+      if (!rowLabels.size) return;
+      const probe = document.createElement("span");
+      probe.className = "wb-label";
+      probe.style.cssText =
+        "position: absolute; visibility: hidden; white-space: nowrap";
+      grid.append(probe);
+      let widest = 0;
+
+      for (const label of rowLabels) {
+        probe.textContent = label;
+        widest = Math.max(widest, probe.getBoundingClientRect().width);
+      }
 
-        const padding =
-          parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
+      probe.remove();
+      grid.style.columnGap = `${Math.min(160, Math.max(48, Math.ceil(widest) + 16))}px`;
+    };
 
-        const gap = parseFloat(style.columnGap);
-        grid.classList.toggle(
-          "wb-scene-compact",
-          grid.clientWidth < columns * 140 + (columns - 1) * gap + padding,
-        );
-      };
+    const responsive = options.responsive !== false && columns > 1;
 
-      let layoutFrame: number | undefined;
-      new ResizeObserver(() => {
-        wake();
+    // Preserve declared cells on wider layouts. In a narrower container, fold
+    // into fewer columns in reading order, and below that into one, rather
+    // than shrinking cards, tables and labels to fit.
+    const reflow = () => {
+      sizeGap();
 
-        if (layoutFrame !== undefined) return;
-        layoutFrame = requestAnimationFrame(() => {
-          layoutFrame = undefined;
-          reflow();
-        });
-      }).observe(grid);
-      reflow();
-    }
+      if (!responsive) return;
+      const style = getComputedStyle(grid);
+
+      const padding =
+        parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
+
+      const gap = parseFloat(style.columnGap);
+
+      const fits = (count: number) =>
+        grid.clientWidth >= count * 140 + (count - 1) * gap + padding;
+
+      let shown = columns;
+
+      if (!fits(columns)) {
+        shown = 1;
+
+        // An even fold, or two columns: four cards fold to two rows of two,
+        // not three and one.
+        for (let count = columns - 1; count >= 2; count--)
+          if ((columns % count === 0 || count === 2) && fits(count)) {
+            shown = count;
+            break;
+          }
+      }
+
+      grid.classList.toggle("wb-scene-compact", shown === 1);
+      grid.classList.toggle("wb-scene-fold", shown > 1 && shown < columns);
+      grid.style.setProperty("--wb-fold", String(shown));
+    };
+
+    let layoutFrame: number | undefined;
+
+    const scheduleLayout = () => {
+      if (layoutFrame !== undefined) return;
+      layoutFrame = requestAnimationFrame(() => {
+        layoutFrame = undefined;
+        reflow();
+      });
+    };
+
+    new ResizeObserver(() => {
+      wake();
+      scheduleLayout();
+    }).observe(grid);
+    reflow();
 
     const nodes = new Map<string, HTMLElement>();
     const links = new Map<string, ArrowRecord>();
@@ -1886,10 +1936,15 @@ body {
       }
     });
 
+    const rows = new Map<HTMLElement, number>();
+
     const place = (el: HTMLElement, [column, row, rowSpan, colSpan]: Cell) => {
       el.style.gridColumn = colSpan
         ? `${column} / span ${colSpan}`
         : String(column);
+      // Folded into fewer columns, a cell that spans columns takes the row.
+      el.toggleAttribute("data-wb-wide", (colSpan ?? 1) > 1);
+      rows.set(el, row);
       el.style.gridRow = rowSpan ? `${row} / span ${rowSpan}` : String(row);
       el.style.order = String((row - 1) * columns + column);
     };
@@ -1957,6 +2012,11 @@ body {
       const record = createEdge(a, b, { ...options, offset });
       links.set(`${ak}>${bk}`, record);
 
+      if (options.label && rows.has(a) && rows.get(a) === rows.get(b)) {
+        rowLabels.add(options.label);
+        scheduleLayout();
+      }
+
       return record;
     };
 
diff --git a/packages/review/app/src/blocks.browser.test.tsx b/packages/review/app/src/blocks.browser.test.tsx
index 00d13393b..e0060f3f4 100644
--- a/packages/review/app/src/blocks.browser.test.tsx
+++ b/packages/review/app/src/blocks.browser.test.tsx
@@ -1139,6 +1139,48 @@ describe("block components", () => {
     expect(stages.count("ready")).toBe(1);
   });
 
+  it("folds a scene into fewer columns before one, and opens columns to fit a row's link labels", async () => {
+    const scene = (box: string) =>
+      `const ${box} = whiteboard.scene({ columns: 4, container: "#${box}" });` +
+      ["a", "b", "c", "d"]
+        .map(
+          (id, i) =>
+            `${box}.actor({ id: "${box}-${id}", at: [${i + 1}, 1], title: "${id}" });`,
+        )
+        .join("") +
+      `${box}.link("${box}-a", "${box}-b", { label: "init + port to the stage" });` +
+      `${box}.peek("status", { at: [1, 2, 1, 4] });`;
+
+    const { container } = await mountFixture("animation", {
+      document: [
+        {
+          id: "block-1",
+          type: "animation",
+          title: "Folds",
+          height: "auto",
+          frames: [{ key: "only", title: "Only" }],
+          code: { status: "head/order.ts#L1" },
+          // Each scene reports its column count and gap through the error line.
+          html:
+            '<div id="narrow" style="width: 760px"></div><div id="wide" style="width: 1400px"></div><script>' +
+            scene("narrow") +
+            scene("wide") +
+            'const report = (id) => { const s = getComputedStyle(document.querySelector(`#${id} .wb-scene`)); return `${id} ${s.gridTemplateColumns.split(" ").length} gap ${parseFloat(s.columnGap) > 48}`; };' +
+            'setTimeout(() => { throw new Error(`${report("narrow")}, ${report("wide")}`); }, 600);' +
+            "</script>",
+          pins: { repositoryId: "repo", base: "base", head: "head" },
+        },
+      ],
+    });
+
+    expect(await settled(() => alertText(container).includes("narrow"))).toBe(
+      true,
+    );
+    expect(alertText(container)).toContain(
+      "narrow 2 gap true, wide 4 gap true",
+    );
+  });
+
   it("boots the stage again each time it goes fullscreen and back", async () => {
     using stages = tapStages();
 
diff --git a/packages/review/instructions/animation.md b/packages/review/instructions/animation.md
index 7b2f55efb..d3ad72ce6 100644
--- a/packages/review/instructions/animation.md
+++ b/packages/review/instructions/animation.md
@@ -103,11 +103,11 @@ If no part of the drawing changes between frames, it is not an animation: use a
 
 A scene appends to the stage body by default. To compose it with your own headings, text or controls, pass a container selector or element: `whiteboard.scene({ columns: 3, container: "#diagram" })`. Badges stay with that container too.
 
-When the container is too narrow for readable cards, the scene stacks its cells in row/column order. Widening restores the declared grid. Tables wrap their content. Hidden cards, store items and table rows take no space, so auto height follows visible content. Use `responsive: false` for an intentional fixed grid with your own responsive or scrolling plan.
+When the container is too narrow for the declared columns, the scene folds into fewer, in row/column order: four columns become two rows of two, and a cell spanning columns takes a whole row. Narrower still, it stacks into one column. Widening restores the declared grid. Tables wrap their content. Hidden cards, store items and table rows take no space, so auto height follows visible content. Use `responsive: false` for an intentional fixed grid with your own responsive or scrolling plan.
 
 The scene keeps three things consistent for you:
 
-- **Spacing.** Cards sit in grid cells with a fixed gap. You choose the cell; the scene sets the gap and the padding. Four cards fit a sufficiently wide row; narrower containers stack them. Past four, prefer a second row.
+- **Spacing.** Cards sit in grid cells. You choose the cell; the scene sets the padding and the gap, widening the gap between columns to fit the longest label on a link within a row. At the default document width, three cards with short link labels fit a row; a fourth folds the row in two until the reader widens the document or goes fullscreen. Past four, prefer a second row.
 - **Edges.** `link` draws one straight line from the center of one card's nearest side to the other's, with one weight and one arrowhead. `dashed: true` means async (a reply, a stream, a background send). A second edge between the same two cards offsets beside the first.
 - **Moving blocks.** `send` is the only way to move a block along an edge. The chip rides the edge's line at one fixed speed, so a longer edge takes longer, and every chip moves at the same pace. It fades out on arrival unless you pass `stay: true`.
 

From af626ef65004e69d8d4e4cfe94f4cf54e5fabf92 Mon Sep 17 00:00:00 2001
From: Milan Bhandari <milanb@gmail.com>
Date: Tue, 27 Oct 2026 16:20:23 -0400
Subject: [PATCH 6/6] Add scenarios to animations, with a labelled picker

Agent-Session: a38a1758-2248-4cad-903d-6e0c59fef9ed
---
 .../app/src/animation/animation-block.tsx     | 156 ++++++++++++------
 .../app/src/animation/stage-protocol.ts       |   6 +-
 .../review/app/src/animation/stage-runtime.ts |  16 ++
 .../review/app/src/blocks.browser.test.tsx    |  52 ++++++
 packages/review/instructions/animation.md     |  26 +--
 .../review/src/review-api/blocks/animation.ts |  50 ++++++
 .../src/review-api/blocks/blocks.test.ts      |  16 ++
 7 files changed, 262 insertions(+), 60 deletions(-)

diff --git a/packages/review/app/src/animation/animation-block.tsx b/packages/review/app/src/animation/animation-block.tsx
index d3559ac8f..bf1e0a327 100644
--- a/packages/review/app/src/animation/animation-block.tsx
+++ b/packages/review/app/src/animation/animation-block.tsx
@@ -20,6 +20,8 @@ import { withClass } from "@canvas/stylex-props";
 import { themeClass, themeStyles } from "@canvas/theme-styles";
 import { tokens } from "@canvas/tokens.stylex";
 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 { anchorSelection } from "@review/lens-selection";
 import { type Block, animationCodeId } from "@review/review-api/document";
@@ -293,6 +295,45 @@ export function AnimationBlock({
     [data.anchors, node.id, openPeek],
   );
 
+  // 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) => {
@@ -322,51 +363,9 @@ export function AnimationBlock({
         break;
       }
 
-      case "sequence": {
-        const unique = new Set(message.keys);
-
-        const valid =
-          unique.size === message.keys.length &&
-          message.keys.every((key) =>
-            frames.some((frame) => frame.key === key),
-          );
-
-        if (!valid) break;
-
-        if (
-          sequenceRef.current?.length === message.keys.length &&
-          sequenceRef.current.every((key, index) => key === message.keys[index])
-        )
-          break;
-
-        sequenceRef.current = message.keys;
-        setSequenceKeys(message.keys);
-        setPlaying(false);
-        setTimeUp(-1);
-        const currentKey = frames[indexRef.current]?.key;
-
-        const fallback = frames.findIndex(
-          (frame) => frame.key === message.keys[0],
-        );
-
-        const next = message.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,
-        });
-
+      case "sequence":
+        selectSequence(message.keys);
         break;
-      }
 
       case "reveal":
         reveal(message.name);
@@ -408,8 +407,22 @@ export function AnimationBlock({
       if (message.success) onMessage.current(message.data);
     };
 
-    sequenceRef.current = null;
-    setSequenceKeys(null);
+    // 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);
+    }
+
     setSlots([]);
     setError(null);
     target.postMessage(
@@ -433,6 +446,7 @@ export function AnimationBlock({
       scale: SCALE,
       reducedMotion: reducedMotion(),
       frame: indexRef.current,
+      ...(sequence && { sequence }),
     };
 
     Promise.all([loadAnime(), loadFonts()]).then(
@@ -444,7 +458,7 @@ export function AnimationBlock({
         } satisfies HostMessage),
       () => setError("The animation libraries or fonts could not be loaded."),
     );
-  }, [node.html, node.code, node.height, frames, embeddable]);
+  }, [node.html, node.code, node.height, node.scenarios, frames, embeddable]);
 
   useEffect(() => () => portRef.current?.close(), []);
 
@@ -539,6 +553,36 @@ export function AnimationBlock({
           </Button>
         }
       />
+      {node.scenarios && (
+        <div {...stylex.props(styles.scenarios)}>
+          <span
+            aria-hidden="true"
+            {...stylex.props(textStyles.eyebrow, styles.scenarioLabel)}
+          >
+            Scenario
+          </span>
+          <SegmentedControl
+            label="Scenario"
+            value={
+              node.scenarios.find((scenario) =>
+                sameKeys(scenario.frames, sequenceKeys),
+              )?.key
+            }
+            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);
+            }}
+          />
+        </div>
+      )}
       <div
         {...stylex.props(styles.stage, fullscreen && styles.stageFullscreen)}
       >
@@ -696,6 +740,9 @@ 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,
@@ -823,6 +870,21 @@ const styles = stylex.create({
     minHeight: 0,
     margin: 0,
   },
+  // The scenario picker, a strip between the header and the stage that
+  // scrolls sideways when its scenarios outrun the width.
+  scenarios: {
+    display: "flex",
+    alignItems: "center",
+    gap: space.s8,
+    overflowX: "auto",
+    padding: `${space.s6} ${space.s12}`,
+    borderBottomWidth: "1px",
+    borderBottomStyle: "solid",
+    borderBottomColor: tokens.rule,
+  },
+  scenarioLabel: {
+    flex: "0 0 auto",
+  },
   // Room around the stage so its drawing does not run into the card's edges.
   stage: {
     padding: space.s16,
diff --git a/packages/review/app/src/animation/stage-protocol.ts b/packages/review/app/src/animation/stage-protocol.ts
index 6a220b531..84fb77639 100644
--- a/packages/review/app/src/animation/stage-protocol.ts
+++ b/packages/review/app/src/animation/stage-protocol.ts
@@ -34,6 +34,8 @@ export interface StageInit {
   fonts: string;
   reducedMotion: boolean;
   frame: number;
+  /** The scenario the reader picked: the frame keys the stage starts on. */
+  sequence?: string[];
   /** Library sources the stage runs before its own scripts: anime.js. */
   libraries: string[];
 }
@@ -53,7 +55,9 @@ export type HostMessage =
       colorScheme: StageColorScheme;
     }
   /** The height the host's content in a slot takes. */
-  | { type: "slot-size"; slot: string; height: number };
+  | { type: "slot-size"; slot: string; height: number }
+  /** The reader picked a scenario: play these frame keys, in order. */
+  | { type: "sequence"; keys: string[] };
 
 /** The tallest an auto-sized stage may report itself. */
 export const STAGE_MAX_HEIGHT = 4000;
diff --git a/packages/review/app/src/animation/stage-runtime.ts b/packages/review/app/src/animation/stage-runtime.ts
index 189606f58..02b616b2b 100644
--- a/packages/review/app/src/animation/stage-runtime.ts
+++ b/packages/review/app/src/animation/stage-runtime.ts
@@ -2476,6 +2476,11 @@ body {
 
   const start = async (message: StageInit) => {
     init = message;
+
+    // The scenario the reader picked, before the stage's scripts run; a
+    // script's own setSequence() still replaces it.
+    if (message.sequence) activeSequence = [...message.sequence];
+
     root.toggleAttribute("data-wb-auto-size", message.autoSize);
     setProperties(message.scale);
     applyTheme(message.theme, message.colorScheme);
@@ -2548,6 +2553,17 @@ body {
         wake();
         break;
       }
+
+      case "sequence":
+        if (!init) break;
+
+        try {
+          whiteboard.setSequence(message.keys);
+        } catch (error) {
+          fail(String(error));
+        }
+
+        break;
     }
   };
 }
diff --git a/packages/review/app/src/blocks.browser.test.tsx b/packages/review/app/src/blocks.browser.test.tsx
index e0060f3f4..375d728f1 100644
--- a/packages/review/app/src/blocks.browser.test.tsx
+++ b/packages/review/app/src/blocks.browser.test.tsx
@@ -1181,6 +1181,58 @@ describe("block components", () => {
     );
   });
 
+  it("starts on the first scenario and switches the stage's path from the picker", async () => {
+    const { container } = await mountFixture("animation", {
+      document: [
+        {
+          id: "block-1",
+          type: "animation",
+          title: "Branches",
+          height: "auto",
+          frames: [
+            { key: "a", title: "Start", label: "START" },
+            { key: "b", title: "Delivered", label: "DELIVER" },
+            { key: "c", title: "Dropped", label: "DROP" },
+          ],
+          scenarios: [
+            { key: "ok", label: "Delivered", frames: ["a", "b"] },
+            { key: "lost", label: "Dropped packet", frames: ["a", "c"] },
+          ],
+          code: {},
+          // The stage reports the path it was given through its error line.
+          html: '<script>whiteboard.on("*", () => { if (whiteboard.frames.some((f) => f.key === "c")) throw new Error("stage on dropped"); });</script>',
+          pins: { repositoryId: "repo", base: "base", head: "head" },
+        },
+      ],
+    });
+
+    const steps = () =>
+      [...container.querySelectorAll("[aria-label='Steps'] button")].map(
+        (step) => step.textContent,
+      );
+
+    const picker = (name: string) =>
+      [
+        ...container.querySelectorAll<HTMLButtonElement>(
+          "[role='group'][aria-label='Scenario'] button",
+        ),
+      ].find((button) => button.textContent === name)!;
+
+    expect(text(container)).toContain("Scenario");
+    expect(await settled(() => steps().join() === "1START,2DELIVER")).toBe(
+      true,
+    );
+    expect(picker("Delivered").getAttribute("aria-pressed")).toBe("true");
+
+    await act(async () => picker("Dropped packet").click());
+
+    expect(await settled(() => steps().join() === "1START,2DROP")).toBe(true);
+    expect(picker("Dropped packet").getAttribute("aria-pressed")).toBe("true");
+    expect(
+      await settled(() => alertText(container).includes("stage on dropped")),
+    ).toBe(true);
+  });
+
   it("boots the stage again each time it goes fullscreen and back", async () => {
     using stages = tapStages();
 
diff --git a/packages/review/instructions/animation.md b/packages/review/instructions/animation.md
index d3ad72ce6..bee01b910 100644
--- a/packages/review/instructions/animation.md
+++ b/packages/review/instructions/animation.md
@@ -38,7 +38,8 @@ If no part of the drawing changes between frames, it is not an animation: use a
 }
 ```
 
-- `frames`: every possible step. `key` names the frame for your markup and scripts; `title` and `caption` show under the stage. `label` is a short step name (e.g. `SEND`); give every frame one, or none, and the reader gets a named step strip instead of dots. `duration` (ms, default 3000) is how long the frame holds while playing. For a flow with alternate branches, declare every stable frame here and select the active ordered path with `whiteboard.setSequence(...)`.
+- `frames`: every possible step. `key` names the frame for your markup and scripts; `title` and `caption` show under the stage. `label` is a short step name (e.g. `SEND`); give every frame one, or none, and the reader gets a named step strip instead of dots. `duration` (ms, default 3000) is how long the frame holds while playing. For a flow with alternate paths, declare every frame here and list the paths in `scenarios`.
+- `scenarios`: alternate paths through the frames, 2 to 8, each `{ "key", "label", "frames": [frame keys in order] }`. The whiteboard draws a picker labelled Scenario above the stage and starts on the first. `label` is what the reader picks, e.g. `Retried request`. Omit it for an animation with one path.
 - `code`: the source ranges the stage shows, by name. The server checks each anchor like any other reference, so verify paths and lines. Use `head/` for the new code and `base/` for the old.
 - `pins`: as on any block that quotes code. A review with a target lends its own; a board without one needs them on the block.
 - `html`: the stage's body. It runs in a sandboxed frame with no network: inline `<style>` and `<script>` only, no external URLs. Images must be `data:` URLs.
@@ -153,7 +154,7 @@ table.row(cells: string[], { enter?; exit?; only?; tone? }): HTMLTableRowElement
 
 ### Frames
 
-The stage sets `data-frame="<key>"` on `<html>`, and `enter` / `exit` / `only` on any scene part decide the frames it shows in. They are states, not events, so they land right when the reader jumps to a frame or steps back. With `setSequence`, `enter` / `exit` and held `scene.on` changes follow active-sequence order, not declaration order: a change whose key is outside the active path does not apply, an inactive `enter` never occurs, and an inactive `exit` does not end an already-entered part. `only` and highlight lists always match exact stable keys. Visible cards keep their declared wide-grid cells. Hidden cards, store items and table rows collapse from layout; put replacing cards in the same cell. For an intentionally stable footprint, give the container a min-height or choose a fixed stage height with an appropriate scrolling plan.
+The stage sets `data-frame="<key>"` on `<html>`, and `enter` / `exit` / `only` on any scene part decide the frames it shows in. They are states, not events, so they land right when the reader jumps to a frame or steps back. With an active path (a scenario, or `setSequence`), `enter` / `exit` and held `scene.on` changes follow active-path order, not declaration order: a change whose key is outside the active path does not apply, an inactive `enter` never occurs, and an inactive `exit` does not end an already-entered part. `only` and highlight lists always match exact stable keys. Visible cards keep their declared wide-grid cells. Hidden cards, store items and table rows collapse from layout; put replacing cards in the same cell. For an intentionally stable footprint, give the container a min-height or choose a fixed stage height with an appropriate scrolling plan.
 
 ## Going further: the toolkit
 
@@ -248,19 +249,19 @@ readonly theme; readonly colorScheme: "light" | "dark"; readonly reducedMotion;
 
 `whiteboard.frame` is the current frame object, not its key. For keyed state, read `whiteboard.frame.key` or use the handler argument: `whiteboard.on("*", ({ frame }) => render(frame.key))`.
 
-For alternate paths, call `whiteboard.setSequence(["start", "branch-a", "done"])`. Every key must be a unique frame declared in the component. Repeating the same sequence is a no-op, so it is safe to call from a render path. The selected order controls the host step labels, titles, count, Previous/Next, keyboard navigation, Play/Replay, and `whiteboard.next()` / `prev()`; changing it stops current playback and clears its hold timer. Changing the sequence preserves the current frame when it remains in the new path; otherwise it lands instantly on the new path's first frame. `whiteboard.frames` contains the active ordered path and its `index` values, and `whiteboard.frame.index` is the current active-path position; keys remain the stable identity. `goto(key)` accepts only a frame in the active sequence and is a direct jump, while adjacent forward steps still play the destination frame's motion even when declaration indexes move backward. Call `setSequence` before `goto` when a control switches branches:
+For alternate paths, declare `scenarios` on the component rather than drawing your own buttons in the stage: the reader gets a labelled picker that works the same on every whiteboard.
 
-```js
-const delivered = ["push", "gossip", "replicate", "serve"];
-const dropped = ["push", "gossip-dropped", "catch-up", "serve-recovered"];
-
-function selectPath(drop) {
-  const path = drop ? dropped : delivered;
-  whiteboard.setSequence(path);
-  whiteboard.goto(path[1]);
-}
+```json
+"scenarios": [
+  { "key": "delivered", "label": "Delivered", "frames": ["push", "gossip", "replicate", "serve"] },
+  { "key": "dropped", "label": "Dropped packet", "frames": ["push", "gossip-dropped", "catch-up", "serve-recovered"] }
+]
 ```
 
+Picking a scenario selects its frames as the active path. The active path controls the host step labels, titles, count, Previous/Next, keyboard navigation, Play/Replay, and `whiteboard.next()` / `prev()`; changing it stops current playback and clears its hold timer. It preserves the current frame when that frame is in the new path; otherwise it lands instantly on the new path's first frame. `whiteboard.frames` contains the active ordered path and its `index` values, and `whiteboard.frame.index` is the current active-path position; keys remain the stable identity. `goto(key)` accepts only a frame in the active path and is a direct jump, while adjacent forward steps still play the destination frame's motion even when declaration indexes move backward.
+
+`whiteboard.setSequence(keys)` selects a path from a script, for a branch the drawing itself decides. Every key must be a unique declared frame, and repeating the same sequence is a no-op, so it is safe to call from a render path. When the path matches a scenario, the picker shows that scenario.
+
 - `scene.peek(name, ...)`, `whiteboard.code(name)` and `<div data-wb-code="name">` all draw the real code peek over a placeholder. Give `scene.peek` a cell, and span columns (the cell's `colSpan`) when the code needs width — a one-column peek clips long lines; a raw `data-wb-code` div takes a CSS width instead. Its height follows the code, up to about 18 lines. A peek is always on top of your drawing, so do not draw or travel over it.
 - A code peek is about 40px of header plus 18px per line, up to about 400px. Rows of cards take about 90px each. With the default `height: "auto"`, the stage grows to fit them. If you intentionally use a numeric fixed height, leave enough room because overflow clips at that height.
 
@@ -288,6 +289,7 @@ Custom CSS should use the whiteboard's variables, never literal colors, sizes or
 - Each frame shows one idea; its title says what changed. 3 to 8 frames is usual.
 - Omit `height` unless the animation intentionally needs a fixed viewport; verify any numeric height in every frame and narrow layout.
 - Every frame reads correctly when reached by a jump, not only by playing.
+- Alternate paths are `scenarios` on the component, not buttons drawn in the stage.
 - Build as "Choose how to build it" says: a scene by default, and the toolkit or raw HTML for anything else.
 - In raw HTML, build from the style kit and the `--wb-*` variables; write no literal color, size or font name.
 - Script errors show under the stage. After writing, read the whiteboard back and fix any.
diff --git a/packages/review/src/review-api/blocks/animation.ts b/packages/review/src/review-api/blocks/animation.ts
index 5e6796a44..7e2f247bc 100644
--- a/packages/review/src/review-api/blocks/animation.ts
+++ b/packages/review/src/review-api/blocks/animation.ts
@@ -45,6 +45,24 @@ export const animationFrameSchema = z.strictObject({
 
 export type AnimationFrame = z.infer<typeof animationFrameSchema>;
 
+export const animationScenarioSchema = z.strictObject({
+  key: handle.describe("Names the scenario."),
+  label: z
+    .string()
+    .min(1)
+    .max(32)
+    .describe(
+      "What the reader picks above the stage, e.g. Retried request. Keep it short.",
+    ),
+  frames: z
+    .array(handle)
+    .min(1)
+    .max(60)
+    .describe("The frame keys this scenario plays, in order."),
+});
+
+export type AnimationScenario = z.infer<typeof animationScenarioSchema>;
+
 export const animationSchema = defineBlock("animation", {
   title: label,
   html: text
@@ -60,6 +78,14 @@ export const animationSchema = defineBlock("animation", {
     .describe(
       "Every possible frame. Stage scripts may select an ordered branch with whiteboard.setSequence(keys); keys stay unique and stable.",
     ),
+  scenarios: z
+    .array(animationScenarioSchema)
+    .min(2)
+    .max(8)
+    .optional()
+    .describe(
+      "Alternate paths through the frames. The whiteboard draws a labelled scenario picker above the stage and starts on the first one.",
+    ),
   code: z
     .record(handle, anchorSchema)
     .default({})
@@ -94,5 +120,29 @@ export const animation = {
       throw new ReviewInputError(
         "Give every animation frame a label, or none: the step strip needs one per frame.",
       );
+
+    const scenarios = block.scenarios ?? [];
+
+    if (
+      new Set(scenarios.map((scenario) => scenario.key)).size !==
+      scenarios.length
+    )
+      throw new ReviewInputError(
+        "Animation scenario keys must be unique within the animation.",
+      );
+
+    for (const scenario of scenarios) {
+      if (new Set(scenario.frames).size !== scenario.frames.length)
+        throw new ReviewInputError(
+          `Scenario "${scenario.key}" lists a frame twice.`,
+        );
+
+      const unknown = scenario.frames.find((key) => !keys.has(key));
+
+      if (unknown)
+        throw new ReviewInputError(
+          `Scenario "${scenario.key}" names frame "${unknown}", which the animation does not declare.`,
+        );
+    }
   },
 } satisfies BlockDefinition<AnimationBlock>;
diff --git a/packages/review/src/review-api/blocks/blocks.test.ts b/packages/review/src/review-api/blocks/blocks.test.ts
index c32fd47d9..fe3eddd9e 100644
--- a/packages/review/src/review-api/blocks/blocks.test.ts
+++ b/packages/review/src/review-api/blocks/blocks.test.ts
@@ -112,6 +112,22 @@ describe("block definitions", () => {
         ),
       );
     });
+    it("animation: scenarios name declared frames", async () => {
+      const [animation] = await fixture("animation");
+
+      const scenarios = (missing: string) => ({
+        ...animation!,
+        scenarios: [
+          { key: "short", label: "Short", frames: ["before"] },
+          { key: "long", label: "Long", frames: ["before", missing] },
+        ],
+      });
+
+      expect(() => checkReferences([scenarios("change")])).not.toThrow();
+      expect(() => checkReferences([scenarios("chnage")])).toThrow(
+        /names frame "chnage"/,
+      );
+    });
     it("animation: frame labels are all or none", async () => {
       const [animation] = await fixture("animation");