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

package/instructions/animation.md

@@ -2,12 +2,15 @@ An `animation` component draws HTML you write on the whiteboard, in a sandboxed
 
 For paths a reader can pick, such as a retry that succeeds or one that gives up, use `scenarios`: the whiteboard draws the picker, so do not draw your own buttons.
 
+A `clip` component runs in the same stage with the same API, but it has no frames: it is one timeline the reader plays, pauses and jumps around by named markers. See "Clips: one timeline, played" below.
+
 ## Work in files
 
 1. `session_checkout({ sessionId, targetId })` writes the animation to a folder: `animation.html`, `frames.json`, `scenarios.json` (once it has scenarios) and `block.json` (`title`, and `code` and `pins` when it shows code).
 2. Edit those files with your file tools.
 3. Publish the folder: `session_edit({ sessionId, edit: { type: "update", targetId, fromFiles: "<folder>" } })`. Only the files you changed are saved. Keep editing and publishing the same folder; it records what it last published in `checkout.json`.
 4. Read it back with `session_get({ sessionId, targetId })`. Its script runs only where the whiteboard is open, a moment after you publish, so the read says whether it ran there without an error, threw (with the error), or has not run yet. Fix an error and publish again.
+5. Look at it: `session_render({ sessionId, targetId, frame })` shows that frame (or a clip at that marker; omitted, the first) on the whiteboard open in Desktop, as the reader sees it, and returns it as a PNG image, with the error the script threw, if any. It also writes the PNG to the path the result names. Render each frame you changed and check the drawing is what you meant: cards where you placed them, arrows between the right parts, nothing clipped or overlapping. Do not take screenshots of the screen. The whiteboard must be open in Desktop: `session_create` opens it, and `session_open` opens an existing one.
 
 For a new animation, write the same files into a folder of your own and publish with `{ type: "insert", fromFiles: "<folder>", parentId, afterId }`. If someone else changed the animation after your checkout, the publish is refused: check it out again.
 
@@ -15,7 +18,11 @@ For a new animation, write the same files into a folder of your own and publish
 
 Before you write HTML, read the two files whose paths `session_checkout` and these instructions give: `whiteboard.css`, the classes and `--wb-*` variables every animation loads, and `whiteboard.d.ts`, the `whiteboard` API. Use the classes and variables rather than your own colors, sizes or fonts, so the animation matches the board in light and dark.
 
-There are two ways to draw.
+Draw for a stage 720px wide: the width of the board's reading column, and the narrowest the stage gets. Fit that width with nothing past its right edge, so the reader never scrolls sideways on a full-size board: a scene fits three columns of cards, with room for link labels between them. A wider board or fullscreen gives the stage more room, and a narrower window keeps it at 720px and scrolls it sideways, so do not shrink the drawing for small widths. A scene keeps its columns at any width.
+
+Start from the reference closest to what you are drawing, listed under References at the end of these instructions: copy its folder into your draft, then change the data, the prose and the code links.
+
+There are three ways to draw.
 
 ### A scene: cards and messages
 
@@ -24,8 +31,8 @@ For a few services, processes or stores with messages moving between them, use `
 ```html
 <script>
   const s = whiteboard.scene({ columns: 2 });
-  const client = s.actor({ id: "client", at: [1, 1], title: "Client" });
-  const api = s.actor({ id: "api", at: [2, 1], title: "API" });
+  const client = s.actor({ id: "client", at: [1, 1], title: "Client", form: "window" });
+  const api = s.actor({ id: "api", at: [2, 1], title: "API", form: "bars" });
 
   s.send(client, api, "GET", "send");
   s.on("send", api, { note: "timed out", tone: "removed" });
@@ -34,7 +41,21 @@ For a few services, processes or stores with messages moving between them, use `
 </script>
 ```
 
-A scene names frame keys, so a new scenario means new frames and a few new lines like these.
+A scene names frame keys, so a new scenario means new frames and a few new lines like these. While a frame shows, each message it sends is the label of its edge and the edge takes the marker colour, however the reader reached the frame; stepping into the frame rides a chip from the sender that settles into the label. A card's `id` is its element's id, so your own CSS can address it as `#api`.
+
+Give each card the silhouette of what it stands for, so a reader tells the parts apart before reading a title: `form: "window"` for a client, `"bars"` for a service or worker of this codebase, `"cylinder"` for a database, `"drum"` for a cache, `"stack"` for a queue or topic, `"pill"` for a start or end, `"cut"` for a branch. A third-party service or API gets `outline: "dashed"`. `color` sets a border colour at rest (`teal` for stores, `violet` for queues, `accent` for the part under discussion); a frame's `tone` takes over while set. The same `data-form`, `data-outline` and `data-color` work on a `wb-node` in a hand-made layout.
+
+Draw a boundary around cards that belong together with `s.group({ id, at: [column, row, rowSpan, colSpan], title: "SEARCH SERVICE", color })`: a washed box behind the cards in those cells, titled in its corner. On a board that reviews a change, mark what it did to a part with `change: "added" | "modified" | "removed"` on the card: its dot and left edge take the change colour at rest, and a removed part's title is struck. When the cards carry marks a reader must decode, add `s.legend([{ form: "cylinder", label: "Database" }, { change: "modified", label: "Changed here" }])`, one row under the scene; name only what matters.
+
+### A hand-made layout: lanes, axes, graphs
+
+When the drawing is not a grid of cards (attempts on a time axis, two lanes interleaving, a state graph), lay out your own elements with the kit (`wb-node`, `wb-lane`, `wb-table`) and connect them:
+
+- `whiteboard.arrow("#caller", "#service", { enter: "a1" })` draws an SVG arrow that follows the two elements. A string here is a CSS selector; in a scene's methods it is a card id.
+- `whiteboard.token({ label: "GET" })` and `whiteboard.travel(token, arrow, "a1")` ride a chip along the arrow during that frame.
+- `whiteboard.timeline("a1").add(".wait", { scaleX: [0, 1], duration: 600 })` adds tweens that play when the reader steps into the frame and land at their end on a jump.
+
+Declare arrows, tokens, travels and timelines while the script first runs, naming the frames they play in; they cannot be added from a frame handler. `data-enter="a1"`, `data-exit="a3"`, `data-only="a1 a3"` and `data-highlight="a1 a3"` on any element show, hide or ring it in those frames with no script.
 
 ### Your own HTML: draw each frame from its data
 
@@ -65,7 +86,19 @@ Draw the frame in full, then animate what is new since the previous frame:
 </script>
 ```
 
-Write each frame's data in full, not as a change from the one before: a reader can jump straight to any frame. `whiteboard.animate` skips the motion on a jump and under reduced motion, and returning its animations makes playback wait for them.
+Write each frame's data in full, not as a change from the one before: a reader can jump straight to any frame. `whiteboard.animate` skips the motion on a jump and under reduced motion, and returning its animations makes playback wait for them. Give every keyframe its start value (`[{ opacity: 0 }, { opacity: 1 }]`, not `[{ opacity: 1 }]`): a jump finishes the animation, and a missing start lands wrong.
+
+Something that moves between frames (a job changing queue slot, a record regrouped under a new parent) is drawn the same way: measure every element's position, redraw, then animate each moved element from its old position to `transform: none`. Measure everything before starting any animation; one that has started already reports its transform.
+
+`whiteboard.frames` and `frame.index` follow the active scenario, so a frame outside it is not listed. Key your drawing on `frame.data`, not on positions.
+
+## Painting in
+
+When you write an animation, the reader watches it arrive: its first frame paints in, part by part, instead of appearing at once. It paints only then, not when the board loads with it already there, and not under reduced motion. The test harness and a cold load do not paint, so you see it only by watching your own write land on the board.
+
+- By default the kit's parts (cards, nodes, chips, badges, table rows, lanes, labels, peeks, tokens) fade in one after another in document order, and arrows draw along their path, all within about a second and a half. A part inside another goes in with it.
+- `data-wb-paint="1"` orders a part: numbered parts first, the rest in document order. `data-wb-paint="none"` shows an element and everything in it at once. `data-wb-paint-style="fade"`, `"draw"` (an SVG line), `"wipe"` (left to right) or `"none"` picks the effect. Any element with either attribute paints on its own.
+- `whiteboard.on("paint", ({ frame, instant }) => ...)` replaces the default painter: draw the first frame in yourself and return the animations, as a frame handler does. It also runs with `instant: true` when the block does not paint in; leave everything in its end state then. `whiteboard.timeline("paint")` is a timeline that plays once as the block paints in and lands at its end otherwise; it also replaces the default painter. Do not name a frame `paint`.
 
 ## Link the code
 
@@ -74,3 +107,34 @@ Name the ranges the animation explains in `code`, then link the drawing to them:
 - `data-wb-open="retry"` (or `code: "retry"` on a scene card) opens the code beside the whiteboard when the reader clicks that element, and names it when they hover. Put it on the part of the drawing the code explains.
 - A frame's `code` lists the ranges that frame shows. Your script reads it as `frame.code`, so one script can mark what to open in every frame.
 - `<div data-wb-code="retry">` (or `scene.peek`) shows a range inside the drawing instead.
+
+## Clips: one timeline, played
+
+Pick a clip when the motion itself is the point and the timing carries the meaning: a token crossing a system, two requests racing, a queue draining, a timeout firing while a reply is on its way. Pick an animation when the reader needs to compare discrete states, one frame against the next.
+
+A clip's folder holds `markers.json` where an animation's holds `frames.json`; `session_checkout` writes whichever the block has, and publishing a folder with `markers.json` makes a clip. A marker is `{ key, title, caption?, code? }`: a named moment the reader jumps to and the tour stops at. The strip under the clip shows each title, so keep titles to a few words. Markers have no `data` or `duration`: the script decides when each one happens.
+
+Build the timeline while the script first runs, and place every marker on it:
+
+```html
+<script>
+  whiteboard
+    .clip()
+    .marker("sent")
+    .add(".packet", { left: ["10%", "50%"], duration: 700 })
+    .marker("accepted")
+    .add(".packet", { left: ["50%", "90%"], duration: 900 })
+    .marker("stored");
+</script>
+```
+
+- `whiteboard.clip()` returns a timeline with `add`, `set` and `call`, as `whiteboard.timeline` does, and `.marker(key)`, which places a declared marker at the timeline's end so far, or at an anime.js position (`.marker("timeout", 1500)`). Numeric positions count from the clip's start. Markers are labels on the timeline, so later calls can start at one: `.add(".retry", { opacity: [0, 1] }, "timeout")`.
+- A marker the script leaves unplaced shows an error under the clip, naming it.
+- With `scenarios` (`[{ key, label }]` in `scenarios.json`), each scenario is a timeline of its own: call `whiteboard.clip("fast")`, `whiteboard.clip("slow")`, once each, and place every marker on each. A `whiteboard.clip()` without a key serves every scenario that has no timeline of its own.
+- Write each tween with its start value (`left: ["10%", "50%"]`, not `left: "50%"`), and make what differs between beats a `set` or a tween on the timeline: jumping back to a marker then undoes everything after it.
+- `whiteboard.on("stored", ({ marker, instant }) => ...)` runs when the playhead crosses that marker playing forward, or lands on it after a jump with `instant: true`; `"*"` runs on every marker. Use it for what a tween cannot draw, such as changing text, and set the whole state for that marker, since the reader can jump straight to it. `whiteboard.markers` lists the markers with their `at` (milliseconds) once placed, and `whiteboard.marker` is the one the playhead last reached.
+- In a clip, `data-enter`, `data-exit`, `data-only`, `data-highlight` and `scene.on` name markers instead of frames, and follow the marker the playhead last reached.
+- `whiteboard.frames`, `frame`, `goto`, `next`, `prev`, `setSequence`, `timeline(key)`, `travel` and `scene.send` belong to frames and throw in a clip. Move tokens with tweens on the clip instead.
+- Under reduced motion the clip never animates: Play steps from marker to marker, holding each for a few seconds and landing on its time at once, and a jump lands at once. Marker handlers get `instant: true`.
+- Painting in and code linking work as for an animation: the clip paints in at time 0, before anything plays, and a marker's `code` gives its tour stop, as a frame's does.
+

package/instructions/animations/before-after-structure/README.md

@@ -0,0 +1,27 @@
+# Before/after structure
+
+A flat list of orders regroups into a map keyed by customer: the same records slide from the old shape into the new one, and tones mark the key, the new containers and the field that goes away.
+
+## Use when
+
+A change reshapes data rather than behavior: a list becomes a map or tree, fields move into a nested object, a type gains or drops a level. The reviewer needs to see where each existing value lands, not just the new type.
+
+## Shows
+
+1. The before shape, as nested cards.
+2. The field that drives the change (here the grouping key), toned `modified`.
+3. The records moving into their new containers, which appear toned `added`.
+4. The field the new shape makes redundant, toned `removed`.
+5. The after shape, plain.
+
+## Technique
+
+Data-driven. Each frame's `data.root` is the whole structure as a tree of nodes `{id, title, note?, tone?, open?, layout?, fields?, children?}`. One `whiteboard.on("*", ...)` handler redraws the tree, then animates the difference with FLIP: it measures every `[data-id]` before and after the redraw and slides kept elements from their old box with `whiteboard.animate` (a child subtracts its parent's slide). New elements fade in; a new container that receives moved elements fades only its own chrome. `whiteboard.animate` lands the end state on a jump and under reduced motion. A node's `open` becomes `data-wb-open` only in frames whose `code` lists it.
+
+## Adapt
+
+- Rewrite `frames.json`: keep each node's `id` stable across frames, since the id is what makes an element travel instead of reappearing.
+- Set `layout: "row"` on a node whose children should sit side by side; the default stacks them.
+- Put tones on what changed in that frame only, and leave the last frame plain.
+- Name your ranges in `block.json` `code`, list them in the frames that show the transformation, and set `open` on the node the code builds.
+- `animation.html` should not need changes.

package/instructions/animations/before-after-structure/animation.html

@@ -0,0 +1,89 @@
+<style>
+  .structure { padding: var(--wb-space-16) var(--wb-space-24); }
+  .node { width: max-content; max-width: 100%; min-width: var(--wb-space-120); }
+  .structure > .node { width: auto; }
+  .children { display: flex; flex-direction: column; align-items: flex-start; gap: var(--wb-space-8); margin-top: var(--wb-space-6); }
+  .children[data-layout="row"] { flex-direction: row; flex-wrap: wrap; gap: var(--wb-space-12); }
+  .fields { flex-direction: column; align-items: flex-start; }
+</style>
+<div class="structure"></div>
+<script>
+  const stage = document.querySelector(".structure");
+
+  function element(tag, className, text) {
+    const el = document.createElement(tag);
+    el.className = className;
+    if (text !== undefined) el.textContent = text;
+    return el;
+  }
+
+  // One card per node: a title, an optional type note, fields as chips, and nested children.
+  function draw(node, code) {
+    const card = element("div", "wb-card node");
+    card.dataset.id = node.id;
+    if (node.tone) card.dataset.tone = node.tone;
+    if (node.open && code.includes(node.open)) card.dataset.wbOpen = node.open;
+
+    const head = element("div", "wb-card-head");
+    head.append(element("i", "wb-card-dot"), element("span", "wb-card-title", node.title));
+    card.append(head);
+    if (node.note) card.append(element("div", "wb-card-note", node.note));
+
+    if (node.fields) {
+      const fields = element("div", "wb-items fields");
+      for (const field of node.fields) {
+        const chip = element("span", "wb-chip", `${field.name}: ${field.value}`);
+        chip.dataset.id = `${node.id}.${field.name}`;
+        if (field.tone) chip.dataset.tone = field.tone;
+        fields.append(chip);
+      }
+      card.append(fields);
+    }
+
+    if (node.children) {
+      const children = element("div", "children");
+      children.dataset.layout = node.layout ?? "column";
+      children.append(...node.children.map((child) => draw(child, code)));
+      card.append(children);
+    }
+    return card;
+  }
+
+  const rects = () =>
+    new Map([...stage.querySelectorAll("[data-id]")].map((el) => [el, el.getBoundingClientRect()]));
+
+  whiteboard.on("*", ({ frame }) => {
+    const was = new Map([...rects()].map(([el, rect]) => [el.dataset.id, rect]));
+    stage.replaceChildren(draw(frame.data.root, frame.code ?? []));
+    const now = rects();
+
+    // Slide each kept element from where it was (FLIP). A child rides its parent's
+    // slide, so it moves only by the part of its offset the parent does not cover.
+    const offsets = new Map();
+    return [...now].flatMap(([el, to]) => {
+      const inherited = offsets.get(el.parentElement.closest("[data-id]")) ?? [0, 0];
+      const from = was.get(el.dataset.id);
+      if (!from) {
+        offsets.set(el, inherited);
+        // A new container keeps the moved elements it now holds visible: fade only its own chrome.
+        const holds = [...el.querySelectorAll("[data-id]")].some((child) => was.has(child.dataset.id));
+        if (!holds) return [whiteboard.animate(el, [{ opacity: 0 }, { opacity: 1 }], 300)];
+        const chrome = [...el.children].filter((part) => !part.classList.contains("children"));
+        return [
+          whiteboard.animate(el, [{ borderColor: "transparent", backgroundColor: "transparent" }, {}], 300),
+          ...chrome.map((part) => whiteboard.animate(part, [{ opacity: 0 }, { opacity: 1 }], 300)),
+        ];
+      }
+      const offset = [from.left - to.left, from.top - to.top];
+      offsets.set(el, offset);
+      const [x, y] = [offset[0] - inherited[0], offset[1] - inherited[1]];
+      if (Math.abs(x) < 1 && Math.abs(y) < 1) return [];
+      return [
+        whiteboard.animate(el, [{ transform: `translate(${x}px, ${y}px)` }, { transform: "none" }], {
+          duration: 550,
+          easing: whiteboard.theme["motion-settle"],
+        }),
+      ];
+    });
+  });
+</script>

package/instructions/animations/before-after-structure/block.json

@@ -0,0 +1,10 @@
+{
+  "title": "Orders grouped by customer",
+  "code": {
+    "group": {
+      "source": "head/src/orders/group-by-customer.ts#L8-L31",
+      "label": "groupByCustomer"
+    },
+    "order": { "source": "head/src/orders/order.ts#L3-L12", "label": "Order" }
+  }
+}

package/instructions/animations/before-after-structure/frames.json

@@ -0,0 +1,313 @@
+[
+  {
+    "key": "before",
+    "title": "A flat list of orders",
+    "label": "BEFORE",
+    "caption": "Before the change, orders is one array, and every reader that needs a customer's orders filters it.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "orders",
+        "note": "Order[]",
+        "layout": "row",
+        "children": [
+          {
+            "id": "o1",
+            "title": "o1",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme" },
+              { "name": "total", "value": 40 }
+            ]
+          },
+          {
+            "id": "o2",
+            "title": "o2",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex" },
+              { "name": "total", "value": 15 }
+            ]
+          },
+          {
+            "id": "o3",
+            "title": "o3",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme" },
+              { "name": "total", "value": 70 }
+            ]
+          },
+          {
+            "id": "o4",
+            "title": "o4",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex" },
+              { "name": "total", "value": 30 }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "key",
+    "title": "customer becomes the key",
+    "label": "KEY",
+    "code": ["group"],
+    "caption": "groupByCustomer reads each order's customer field and uses it as the map key.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "orders",
+        "note": "Order[]",
+        "layout": "row",
+        "children": [
+          {
+            "id": "o1",
+            "title": "o1",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme", "tone": "modified" },
+              { "name": "total", "value": 40 }
+            ]
+          },
+          {
+            "id": "o2",
+            "title": "o2",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex", "tone": "modified" },
+              { "name": "total", "value": 15 }
+            ]
+          },
+          {
+            "id": "o3",
+            "title": "o3",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "acme", "tone": "modified" },
+              { "name": "total", "value": 70 }
+            ]
+          },
+          {
+            "id": "o4",
+            "title": "o4",
+            "open": "order",
+            "fields": [
+              { "name": "customer", "value": "globex", "tone": "modified" },
+              { "name": "total", "value": 30 }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "move",
+    "title": "Orders move under their customer",
+    "label": "GROUP",
+    "code": ["group"],
+    "caption": "One entry per customer, in first-seen order; each order keeps its place within its customer.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "ordersByCustomer",
+        "note": "Map<CustomerId, Order[]>",
+        "open": "group",
+        "tone": "modified",
+        "layout": "row",
+        "children": [
+          {
+            "id": "g-acme",
+            "title": "acme",
+            "note": "Order[]",
+            "open": "group",
+            "tone": "added",
+            "children": [
+              {
+                "id": "o1",
+                "title": "o1",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "acme" },
+                  { "name": "total", "value": 40 }
+                ]
+              },
+              {
+                "id": "o3",
+                "title": "o3",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "acme" },
+                  { "name": "total", "value": 70 }
+                ]
+              }
+            ]
+          },
+          {
+            "id": "g-globex",
+            "title": "globex",
+            "note": "Order[]",
+            "open": "group",
+            "tone": "added",
+            "children": [
+              {
+                "id": "o2",
+                "title": "o2",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "globex" },
+                  { "name": "total", "value": 15 }
+                ]
+              },
+              {
+                "id": "o4",
+                "title": "o4",
+                "open": "order",
+                "fields": [
+                  { "name": "customer", "value": "globex" },
+                  { "name": "total", "value": 30 }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "trim",
+    "title": "Order drops its customer field",
+    "label": "TRIM",
+    "code": ["order"],
+    "caption": "The key already names the customer, so Order no longer carries it.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "ordersByCustomer",
+        "note": "Map<CustomerId, Order[]>",
+        "open": "group",
+        "tone": "modified",
+        "layout": "row",
+        "children": [
+          {
+            "id": "g-acme",
+            "title": "acme",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o1",
+                "title": "o1",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "acme", "tone": "removed" },
+                  { "name": "total", "value": 40 }
+                ]
+              },
+              {
+                "id": "o3",
+                "title": "o3",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "acme", "tone": "removed" },
+                  { "name": "total", "value": 70 }
+                ]
+              }
+            ]
+          },
+          {
+            "id": "g-globex",
+            "title": "globex",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o2",
+                "title": "o2",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "globex", "tone": "removed" },
+                  { "name": "total", "value": 15 }
+                ]
+              },
+              {
+                "id": "o4",
+                "title": "o4",
+                "open": "order",
+                "tone": "modified",
+                "fields": [
+                  { "name": "customer", "value": "globex", "tone": "removed" },
+                  { "name": "total", "value": 30 }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  {
+    "key": "after",
+    "title": "After: orders keyed by customer",
+    "label": "AFTER",
+    "code": ["group", "order"],
+    "caption": "A customer's orders are one lookup away, and no order can disagree with the customer it sits under.",
+    "data": {
+      "root": {
+        "id": "root",
+        "title": "ordersByCustomer",
+        "note": "Map<CustomerId, Order[]>",
+        "open": "group",
+        "layout": "row",
+        "children": [
+          {
+            "id": "g-acme",
+            "title": "acme",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o1",
+                "title": "o1",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 40 }]
+              },
+              {
+                "id": "o3",
+                "title": "o3",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 70 }]
+              }
+            ]
+          },
+          {
+            "id": "g-globex",
+            "title": "globex",
+            "note": "Order[]",
+            "open": "group",
+            "children": [
+              {
+                "id": "o2",
+                "title": "o2",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 15 }]
+              },
+              {
+                "id": "o4",
+                "title": "o4",
+                "open": "order",
+                "fields": [{ "name": "total", "value": 30 }]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }
+]

package/instructions/animations/cache-fill-evict/README.md

@@ -0,0 +1,24 @@
+# Read-through cache with LRU eviction
+
+A scene with a caller, a bounded cache and a slow source that walks a miss and fill, a hit, and an eviction when the cache is full.
+
+## Use when
+
+A change adds or alters a cache in front of a slower dependency: its read-through path, its capacity, or what it evicts and when.
+
+## Shows
+
+- Miss: the request falls through to the source, the row is stored as the newest entry, then returned.
+- Hit: the value comes from memory, the source is marked not called, and the entry moves to the newest end.
+- Full: the oldest entry is marked, then leaves as the loaded one enters; the cache stays at capacity.
+
+## Technique
+
+Scene-based. `whiteboard.scene` places three cards; `scene.store` holds the entries as `cache.item(label, { enter, exit, tone })`. `scene.send` moves each request and reply, and `scene.on(frame, part, { text, tone })` changes notes and tones from a frame on. Items keep their order, so each scenario seeds its own entries, and a moved entry is one item exiting while another enters. The cache card opens code with `code:`; a `whiteboard.on("*")` handler points it at the first name in `frame.code`, so clicking it during an eviction opens the eviction range. The cache is a `drum` and Postgres a `cylinder`, both in `teal`, so the two stores read as stores beside the handler's plain box.
+
+## Adapt
+
+- Rename the cards and keys to your caller, cache and source; keep labels short (chips about 12 characters).
+- Change the capacity by seeding more items, and the policy by which item exits (oldest for LRU or FIFO, least used for LFU).
+- Add a scenario such as a stale entry or a failed load with new frame keys and a few `send` and `on` lines.
+- Point `code` in block.json at your real ranges and list them in each frame's `code`.