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

package/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"
+      }
+    }
+  }
+]

package/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"]
+  }
+]

package/instructions/animations/video-platform-architecture/README.md

@@ -0,0 +1,24 @@
+# How a video gets from upload to playback
+
+An architecture scene: the client, the edge, our services and our storage as four groups, with an upload walking down through them and a playback walking back out through the CDN.
+
+## Use when
+
+A change moves work between layers of a system: a new service, a queue between two steps, a cache in front of storage, a third party taking over a step. The reviewer needs to see which layer owns each step and where a request leaves our code.
+
+## Shows
+
+- Upload: the gateway routes to the upload service, the original lands in blob storage, a transcode job waits in a queue, a worker renders renditions and the catalog marks the video ready.
+- Playback: the catalog resolves a manifest, the app fetches segments from the CDN, and the first fetch in a region misses to blob storage; later ones never touch our services.
+- Each layer is a `group`; each card wears its kind as a `form`; the storage cards share `teal`; the queue is `violet`; the CDN, which we do not run, is dashed. A `legend` decodes them.
+
+## Technique
+
+A scene of six half-step columns, every card two wide so the two edge cards sit centred under the one client, and four rows, one row per layer, placed so that every hop is between neighbouring cells: the app over the gateway, the services under the gateway's row, each store under the service that uses it. `s.group` draws the four layers behind their cells: the client in `accent`, the edge plain, services plain, storage in `teal`. Cards take `form`: `window` for the app, `bars` for our services, `drum` with `outline: "dashed"` for the CDN, `cylinder` for the stores and `stack` for the queue. One `send` per frame carries the request or the data between layers; `on` changes notes and tones as a layer takes over; `highlight` rings the card doing the work. `s.legend` lists the six marks once, under the scene.
+
+## Adapt
+
+- Rename the layers and cards to your system; keep three card columns (six half-step ones when a row must centre under another) so the groups stay one row each, and give each layer its own row. Place a card under the one that calls it: an edge between neighbouring cells reads, one that crosses a card bows. Twelve nodes in four columns tangle; nine in three read.
+- Put each real step's range in `code` and name it on the frames that show it.
+- A layer with one card still deserves its group when the boundary is the point.
+- Keep one `send` per frame; a step that fans out is two frames.

package/instructions/animations/video-platform-architecture/animation.html

@@ -0,0 +1,76 @@
+<script>
+  // Six half-step columns, every card two wide, so a row of two can sit
+  // centred under a row of one.
+  const s = whiteboard.scene({ columns: 6 });
+
+  // Four layers, one row each, each a group behind its cells. Every hop in
+  // the story is between neighbouring cells, so no edge crosses a card.
+  s.group({ id: "clients", at: [3, 1, 1, 2], title: "Client", color: "accent" });
+  s.group({ id: "edge", at: [2, 2, 1, 4], title: "Edge" });
+  s.group({ id: "services", at: [1, 3, 1, 6], title: "Our services" });
+  s.group({ id: "storage", at: [1, 4, 1, 6], title: "Storage", color: "teal" });
+
+  // Each card wears its kind: a window for the app, bars for our services,
+  // a drum for the CDN's cache, dashed because we do not run it, cylinders
+  // for the stores and a stack for the queue.
+  const app = s.actor({ id: "app", at: [3, 1, 1, 2], title: "Video app", form: "window", highlight: ["post", "watch", "play"] });
+  const gateway = s.actor({ id: "gateway", at: [2, 2, 1, 2], title: "API gateway", form: "bars", highlight: ["receive", "deliver"] });
+  const cdn = s.store({ id: "cdn", at: [4, 2, 1, 2], title: "CDN", note: "edge cache · third party", form: "drum", outline: "dashed", highlight: ["segment", "edge-miss"] });
+
+  const upload = s.actor({ id: "upload", at: [1, 3, 1, 2], title: "Upload service", form: "bars", code: "upload", highlight: ["store", "enqueue"] });
+  const transcoder = s.actor({ id: "transcoder", at: [3, 3, 1, 2], title: "Transcoder", note: "worker pool", form: "bars", code: "transcode", highlight: ["transcode", "renditions"] });
+  const catalog = s.actor({ id: "catalog", at: [5, 3, 1, 2], title: "Catalog service", form: "bars", code: "watch", highlight: ["ready", "lookup", "resolve"] });
+
+  const queue = s.store({ id: "queue", at: [1, 4, 1, 2], title: "Transcode queue", form: "stack", color: "violet" });
+  const blob = s.store({ id: "blob", at: [3, 4, 1, 2], title: "Blob store", note: "originals · renditions", form: "cylinder", color: "teal" });
+  const db = s.store({ id: "db", at: [5, 4, 1, 2], title: "Catalog DB", note: "videos · renditions", form: "cylinder", color: "teal" });
+
+  s.legend([
+    { form: "window", label: "Client" },
+    { form: "bars", label: "Our service" },
+    { form: "cylinder", color: "teal", label: "Store" },
+    { form: "stack", color: "violet", label: "Queue" },
+    { form: "drum", label: "Cache" },
+    { outline: "dashed", label: "Third party" },
+  ]);
+
+  // The catalog always reads its database; the other edges arrive with sends.
+  s.link(catalog, db);
+
+  // Upload: down through the layers, then ready.
+  s.send(app, gateway, "POST /videos", "post");
+  s.send(gateway, upload, "video.mp4", "receive");
+  s.on("receive", upload, { text: "receiving 1.2 GB" });
+  s.send(upload, blob, "original", "store");
+  s.on("store", blob, { text: "v1/original.mp4", tone: "added" });
+  s.on("enqueue", upload, { text: "202 Accepted", tone: "added" });
+  queue.item("v1", { enter: "enqueue", exit: "transcode", tone: "added" });
+  s.send(upload, queue, "transcode v1", "enqueue");
+  s.send(queue, transcoder, "job v1", "transcode");
+  s.on("transcode", transcoder, { text: "rendering 360p · 720p · 1080p", tone: "accent" });
+  s.on("transcode", upload, { tone: "none" });
+  s.send(transcoder, blob, "renditions", "renditions");
+  s.on("renditions", blob, { text: "v1/{360,720,1080}p" });
+  s.send(transcoder, catalog, "v1 ready", "ready");
+  s.on("ready", transcoder, { text: "idle", tone: "none" });
+  s.on("ready", catalog, { text: "v1: ready", tone: "added" });
+  s.on("ready", db, { text: "videos.v1 = ready", tone: "added" });
+
+  // Playback: resolved by our services once, then served from the edge.
+  s.on("watch", catalog, { tone: "none" });
+  s.on("watch", db, { tone: "none" });
+  s.send(app, gateway, "GET /watch/v1", "watch");
+  s.send(gateway, catalog, "watch v1", "lookup");
+  s.on("lookup", db, { text: "read videos.v1" });
+  s.send(catalog, gateway, "manifest", "resolve");
+  s.on("resolve", catalog, { text: "manifest → CDN URLs" });
+  s.send(gateway, app, "manifest", "deliver");
+  s.on("deliver", app, { text: "playing v1", tone: "accent" });
+  s.send(app, cdn, "GET seg-0001", "segment");
+  s.on("segment", cdn, { text: "miss", tone: "modified" });
+  s.send(cdn, blob, "fetch seg-0001", "edge-miss");
+  s.on("edge-miss", blob, { text: "v1/720p/seg-0001" });
+  cdn.item("seg-0001", { enter: "edge-miss", tone: "added" });
+  s.send(cdn, app, "seg-0001", "play");
+  s.on("play", cdn, { text: "cached at the edge", tone: "none" });
+</script>

package/instructions/animations/video-platform-architecture/block.json

@@ -0,0 +1,17 @@
+{
+  "title": "How a video gets from upload to playback",
+  "code": {
+    "upload": {
+      "source": "head/services/upload/src/handler.ts#L18-L64",
+      "label": "handleUpload"
+    },
+    "transcode": {
+      "source": "head/services/transcoder/src/worker.ts#L30-L92",
+      "label": "TranscodeWorker.run"
+    },
+    "watch": {
+      "source": "head/services/catalog/src/watch.ts#L12-L58",
+      "label": "resolveWatch"
+    }
+  }
+}

package/instructions/animations/video-platform-architecture/frames.json

@@ -0,0 +1,97 @@
+[
+  {
+    "key": "post",
+    "title": "A creator uploads a video",
+    "label": "POST",
+    "caption": "The app posts the file to the API gateway, which fronts every service.",
+    "code": ["upload"]
+  },
+  {
+    "key": "receive",
+    "title": "The gateway hands it to the upload service",
+    "label": "RECEIVE",
+    "caption": "Routing by path: /videos belongs to the upload service.",
+    "code": ["upload"]
+  },
+  {
+    "key": "store",
+    "title": "The original goes to blob storage",
+    "label": "STORE",
+    "caption": "handleUpload streams the original into the blob store before anything else happens.",
+    "code": ["upload"]
+  },
+  {
+    "key": "enqueue",
+    "title": "A transcode job is queued",
+    "label": "ENQUEUE",
+    "caption": "The upload service answers the creator now; the heavy work waits in the queue.",
+    "code": ["upload"]
+  },
+  {
+    "key": "transcode",
+    "title": "A transcoder takes the job",
+    "label": "TRANSCODE",
+    "caption": "A worker takes the job and renders the renditions clients can stream.",
+    "code": ["transcode"]
+  },
+  {
+    "key": "renditions",
+    "title": "Renditions go back to the blob store",
+    "label": "RENDITIONS",
+    "caption": "Each rendition is written beside the original, keyed by video and quality.",
+    "code": ["transcode"]
+  },
+  {
+    "key": "ready",
+    "title": "The catalog marks the video ready",
+    "label": "READY",
+    "caption": "The transcoder tells the catalog service, which updates the catalog database; the video is now playable.",
+    "code": ["transcode"]
+  },
+  {
+    "key": "watch",
+    "title": "A viewer opens a video",
+    "label": "WATCH",
+    "caption": "The app asks the gateway for /watch/v1.",
+    "code": ["watch"]
+  },
+  {
+    "key": "lookup",
+    "title": "The catalog service resolves it",
+    "label": "LOOKUP",
+    "caption": "resolveWatch reads the video's row: its renditions and where they live.",
+    "code": ["watch"]
+  },
+  {
+    "key": "resolve",
+    "title": "A manifest comes back",
+    "label": "RESOLVE",
+    "caption": "The manifest lists segment URLs on the CDN, not the blob store.",
+    "code": ["watch"]
+  },
+  {
+    "key": "deliver",
+    "title": "The gateway returns the manifest",
+    "label": "DELIVER",
+    "caption": "The app can now fetch segments without touching our services again.",
+    "code": ["watch"]
+  },
+  {
+    "key": "segment",
+    "title": "The app fetches a segment from the CDN",
+    "label": "SEGMENT",
+    "caption": "Segments are plain files: the edge serves them, not the catalog."
+  },
+  {
+    "key": "edge-miss",
+    "title": "The edge misses and fetches from blob storage",
+    "label": "EDGE MISS",
+    "caption": "The first viewer in a region pays the fetch from our blob store; the CDN keeps the segment."
+  },
+  {
+    "key": "play",
+    "title": "Segments stream from the edge",
+    "label": "PLAY",
+    "caption": "Later viewers near this edge are served from the CDN's cache, without touching our services."
+  }
+]

package/instructions/animations/video-platform-architecture/scenarios.json

@@ -0,0 +1,28 @@
+[
+  {
+    "key": "upload",
+    "label": "Upload",
+    "frames": [
+      "post",
+      "receive",
+      "store",
+      "enqueue",
+      "transcode",
+      "renditions",
+      "ready"
+    ]
+  },
+  {
+    "key": "playback",
+    "label": "Playback",
+    "frames": [
+      "watch",
+      "lookup",
+      "resolve",
+      "deliver",
+      "segment",
+      "edge-miss",
+      "play"
+    ]
+  }
+]

package/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. */
@@ -12,6 +15,37 @@
 /** Colors any scene part, arrow, token, or kit element (as data-tone). */
 export type Tone = "accent" | "added" | "removed" | "modified" | "muted";
 
+/** A card's silhouette, so a reader tells kinds apart before reading a
+ * title. Pick by what the card stands for: `cylinder` for a database,
+ * `drum` for a cache, `stack` for a queue or topic, `window` for a client
+ * (a browser, an app), `bars` for a service or worker of this codebase,
+ * `pill` for a start or end, `cut` for a branch. Any kit element takes it as
+ * data-form. */
+export type Form =
+  | "box"
+  | "pill"
+  | "cut"
+  | "cylinder"
+  | "drum"
+  | "stack"
+  | "window"
+  | "bars";
+
+/** A border's line. `dashed` reads as outside the system: a third-party
+ * service or API. As data-outline on a kit element. */
+export type Outline = "solid" | "dashed" | "dotted";
+
+/** A border's colour at rest, for grouping cards of a kind: `teal` suits
+ * stores, `violet` queues, `accent` the part under discussion. A tone from
+ * on() takes over while set. As data-color on a kit element. */
+export type Color = "ink" | "accent" | "teal" | "violet";
+
+/** What the change under review did to the part a card stands for. A
+ * resting mark in the change colours, its dot and a stripe down its left
+ * edge, that a frame's `tone` does not replace; a removed part's title is
+ * struck through. As data-change on a kit element. */
+export type Change = "added" | "modified" | "removed";
+
 /** One frame, as your scripts read it. */
 export interface Frame {
   key: string;
@@ -35,6 +69,41 @@ 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. 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;
+}
+
 /** Return the animations a handler starts, or a finite promise, so playback
  * waits for them. */
 export type FrameResult =
@@ -44,7 +113,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;
@@ -57,12 +127,25 @@ 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. */
   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. */
+   * 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,8 +153,22 @@ 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. "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;
+  /** 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;
 
@@ -104,9 +201,10 @@ export interface Whiteboard {
   /** A dot, or a pill with a label, that travel() moves along arrows. */
   token(options?: TokenOptions): HTMLElement;
   /** 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
+   * It waits at the head until the next frame unless `stay` is false. 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,
@@ -133,6 +231,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;
@@ -140,7 +257,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
@@ -154,12 +273,11 @@ export type Cell = [
 
 export interface SceneOptions {
   /** Declared columns; default 3. Three cards with short labels fit a row at
-   * the document's width; past four, use a second row. */
+   * the document's width; past four, use a second row. The scene keeps its
+   * columns at any width: a narrower block scrolls it sideways. */
   columns?: number;
   /** Where the scene goes; defaults to the animation's body. */
   container?: string | HTMLElement;
-  /** Fold into fewer columns when narrow, then one. Default true. */
-  responsive?: boolean;
 }
 
 export interface Scene {
@@ -177,14 +295,25 @@ export interface Scene {
   ): HTMLElement;
   /** A pill above the scene, e.g. a version; on() changes its text. */
   badge(options: { text?: string; tone?: Tone }): HTMLElement;
+  /** A washed box behind the cards in its cells, titled in its corner: a
+   * boundary such as a service, a process or a layer. Declare it before or
+   * after its cards. */
+  group(options: SceneGroupOptions): HTMLElement;
+  /** A row under the scene saying what the cards' marks mean: one glyph,
+   * drawn like a card with the entry's marks, and a label each. Name only
+   * what the reader must decode. */
+  legend(entries: SceneLegendEntry[]): HTMLElement;
   /** Change a card's note, or an item's or badge's text, or a tone, from this
    * frame on, until a later frame changes it. Follows the active path. */
   on(frame: string, part: CardRef, change: SceneChange): void;
   /** A straight edge between two cards that follows them. It bows around
    * cards in the way; keep the cells between linked cards empty. */
   link(from: CardRef, to: CardRef, options?: SceneLinkOptions): SVGGElement;
-  /** A chip that rides the edge during a frame at one fixed speed, drawing the
-   * edge if there is none. Keep labels to about 12 characters. */
+  /** A message from one card to another in a frame, drawing the edge if there
+   * is none. While the frame shows, the message is the edge's label and the
+   * edge takes the marker colour, however the frame was reached; stepping
+   * into the frame rides a chip from the sender that settles into the label.
+   * Keep labels to about 12 characters. */
   send(
     from: CardRef,
     to: CardRef,
@@ -227,12 +356,39 @@ export interface SceneCardOptions extends Lifecycle {
   /** The second line; on() changes it per frame. */
   note?: string;
   tone?: Tone;
+  /** What the card is, by silhouette; see Form. Default box. */
+  form?: Form;
+  /** The border's line; see Outline. Default solid. */
+  outline?: Outline;
+  /** The border's colour at rest; see Color. */
+  color?: Color;
+  /** What the change under review did to this part; see Change. */
+  change?: Change;
   /** Frames during which the card is ringed. */
   highlight?: string[];
   /** The code the card opens when clicked: a name in the block's code. */
   code?: string;
 }
 
+export interface SceneGroupOptions extends Lifecycle {
+  id: string;
+  /** The cells the group covers; its cards sit on its wash. */
+  at: Cell;
+  /** A caps title in its top-left corner, e.g. SEARCH SERVICE. */
+  title?: string;
+  /** The wash and title colour; see Color. Default a neutral well. */
+  color?: Color;
+}
+
+export interface SceneLegendEntry {
+  label: string;
+  form?: Form;
+  outline?: Outline;
+  color?: Color;
+  tone?: Tone;
+  change?: Change;
+}
+
 export interface SceneItemOptions extends Lifecycle {
   tone?: Tone;
 }
@@ -254,10 +410,8 @@ export interface SceneLinkOptions extends Lifecycle {
 }
 
 export interface SceneSendOptions extends Lifecycle {
+  /** Colours the chip, and the edge and its label while the frame shows. */
   tone?: Tone;
-  /** Keep the chip at its target instead of fading it out; scope when it shows
-   * with enter, exit or only. */
-  stay?: boolean;
 }
 
 export interface ArrowOptions extends Lifecycle {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.fast/whiteboard",
-  "version": "0.5.1",
+  "version": "0.5.2-preview.20261104.146",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -77,10 +77,10 @@
     "typescript": "6.0.3",
     "vitest": "4.1.12",
     "@dev.fast/json": "0.0.0",
-    "@dev.fast/trace-core": "0.0.0",
-    "@dev.fast/review-share-protocol": "0.3.1",
+    "@dev.fast/review-share-protocol": "0.6.0",
     "@dev.fast/review-protocol": "0.0.0",
     "@dev.fast/trace-protocol": "0.5.0",
+    "@dev.fast/trace-core": "0.0.0",
     "@dev.fast/whiteboard-document": "0.2.1"
   },
   "engines": {
@@ -91,7 +91,7 @@
     "repo": "devdotfast/review",
     "docs": "packages/review/instructions/authoring.md"
   },
-  "gitHead": "8c348e988bf5f91c45a9ad8b0a2748680ac0985f",
+  "gitHead": "20f4d6dcfaa9f7a40ff77fd6e6b2467fc89e64fa",
   "scripts": {
     "prebuild": "pnpm run build:workspace-deps",
     "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",