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

package/instructions/animations/cache-fill-evict/animation.html

@@ -0,0 +1,81 @@
+<style>
+  /* Narrow end cards leave the cache its width and the edges room for a
+     message chip to read while it travels. */
+  .wb-scene :is(#caller, #source) { width: var(--wb-space-120); }
+  .wb-scene #caller { justify-self: start; }
+  .wb-scene #source { justify-self: end; }
+</style>
+<script>
+  const s = whiteboard.scene({ columns: 3 });
+  const caller = s.actor({ id: "caller", at: [1, 1], title: "Handler", note: "getUser(id)" });
+  const cache = s.store({
+    id: "cache",
+    at: [2, 1],
+    title: "UserCache",
+    note: "LRU · capacity 3",
+    form: "drum",
+    color: "teal",
+    code: "lookup",
+  });
+  const source = s.actor({
+    id: "source",
+    at: [3, 1],
+    title: "Postgres",
+    note: "~120 ms a read",
+    form: "cylinder",
+    color: "teal",
+  });
+
+  // Items keep their order, so each scenario seeds its own entries, oldest first.
+
+  // Miss, then fill: there is room, so the loaded value joins as the newest.
+  cache.item("user:7", { enter: "request" });
+  cache.item("user:3", { enter: "request" });
+  cache.item("user:42", { enter: "fill", tone: "added" });
+  s.send(caller, cache, "get user:42", "request");
+  s.on("miss", cache, { text: "miss · 2 of 3", tone: "modified" });
+  s.on("miss", caller, { text: "awaiting value" });
+  s.send(cache, source, "load user:42", "miss");
+  s.on("miss", source, { tone: "accent" });
+  s.on("fill", source, { text: "row user:42", tone: "none" });
+  s.send(source, cache, "user:42", "fill");
+  s.on("fill", cache, { text: "stored · 3 of 3", tone: "none" });
+  s.send(cache, caller, "user:42", "serve");
+  s.on("serve", caller, { text: "served · 120 ms" });
+
+  // Hit: served from memory, and the entry moves to the newest end.
+  const hit = cache.item("user:7", { enter: "hit-request", exit: "hit-serve" });
+  cache.item("user:3", { enter: "hit-request" });
+  cache.item("user:42", { enter: "hit-request" });
+  cache.item("user:7", { enter: "hit-serve", tone: "added" });
+  s.send(caller, cache, "get user:7", "hit-request");
+  s.on("hit-request", source, { text: "not called", tone: "muted" });
+  s.on("hit-found", hit, { tone: "modified" });
+  s.on("hit-found", cache, { text: "hit · 3 of 3", tone: "added" });
+  s.send(cache, caller, "user:7", "hit-serve");
+  s.on("hit-serve", cache, { text: "user:3 is now oldest", tone: "none" });
+  s.on("hit-serve", caller, { text: "served · <1 ms" });
+
+  // Eviction: the cache is full, so the oldest entry leaves as the new one enters.
+  const oldest = cache.item("user:7", { enter: "evict-request", exit: "evict-fill" });
+  cache.item("user:3", { enter: "evict-request" });
+  cache.item("user:42", { enter: "evict-request" });
+  cache.item("user:51", { enter: "evict-fill", tone: "added" });
+  s.send(caller, cache, "get user:51", "evict-request");
+  s.on("evict-miss", cache, { text: "miss · 3 of 3, full", tone: "modified" });
+  s.on("evict-miss", oldest, { tone: "removed" });
+  s.on("evict-miss", caller, { text: "awaiting value" });
+  s.send(cache, source, "load user:51", "evict-miss");
+  s.on("evict-miss", source, { tone: "accent" });
+  s.on("evict-fill", source, { text: "row user:51", tone: "none" });
+  s.send(source, cache, "user:51", "evict-fill");
+  s.on("evict-fill", cache, { text: "evicted user:7", tone: "removed" });
+  s.send(cache, caller, "user:51", "evict-serve");
+  s.on("evict-serve", cache, { text: "stored · 3 of 3", tone: "none" });
+  s.on("evict-serve", caller, { text: "served · 120 ms" });
+
+  // Clicking the cache opens the range the current frame is about.
+  whiteboard.on("*", ({ frame }) => {
+    cache.element.dataset.wbOpen = frame.code?.[0] ?? "lookup";
+  });
+</script>

package/instructions/animations/cache-fill-evict/block.json

@@ -0,0 +1,13 @@
+{
+  "title": "Read-through cache with LRU eviction",
+  "code": {
+    "lookup": {
+      "source": "head/src/cache.ts#L20-L48",
+      "label": "UserCache.get"
+    },
+    "evict": {
+      "source": "head/src/cache.ts#L52-L70",
+      "label": "UserCache.evictOldest"
+    }
+  }
+}

package/instructions/animations/cache-fill-evict/frames.json

@@ -0,0 +1,79 @@
+[
+  {
+    "key": "request",
+    "title": "The handler asks the cache",
+    "label": "GET",
+    "caption": "getUser(42) checks UserCache before touching the database.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "miss",
+    "title": "Miss: load from Postgres",
+    "label": "MISS",
+    "caption": "user:42 is not cached, so the cache loads it from the source. The handler waits on this read.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "fill",
+    "title": "The cache stores the row",
+    "label": "FILL",
+    "caption": "Two of three slots were taken, so user:42 joins as the newest entry and nothing is evicted.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "serve",
+    "title": "The handler gets the value",
+    "label": "SERVE",
+    "caption": "The first read paid the database round trip; the next read of user:42 will not.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "hit-request",
+    "title": "The handler asks for user:7",
+    "label": "GET",
+    "caption": "The cache is full and already holds user:7.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "hit-found",
+    "title": "Hit: Postgres is not called",
+    "label": "HIT",
+    "caption": "The value comes from memory. The read also counts as a use, which matters for eviction.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "hit-serve",
+    "title": "Served, and user:7 is the newest",
+    "label": "SERVE",
+    "caption": "user:7 moves to the newest end, so user:3 is now the next to be evicted.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "evict-request",
+    "title": "The handler asks for user:51",
+    "label": "GET",
+    "caption": "All three slots are taken; user:7 is the least recently used.",
+    "code": ["lookup"]
+  },
+  {
+    "key": "evict-miss",
+    "title": "Miss on a full cache",
+    "label": "MISS",
+    "caption": "The cache loads user:51 and picks the oldest entry, user:7, to make room.",
+    "code": ["lookup", "evict"]
+  },
+  {
+    "key": "evict-fill",
+    "title": "user:7 leaves, user:51 enters",
+    "label": "EVICT",
+    "caption": "The cache never grows past its capacity: one entry out for each new one in.",
+    "code": ["evict"]
+  },
+  {
+    "key": "evict-serve",
+    "title": "The handler gets user:51",
+    "label": "SERVE",
+    "caption": "A later read of user:7 is a miss again and pays the database round trip.",
+    "code": ["lookup"]
+  }
+]

package/instructions/animations/cache-fill-evict/scenarios.json

@@ -0,0 +1,17 @@
+[
+  {
+    "key": "miss",
+    "label": "Miss, then fill",
+    "frames": ["request", "miss", "fill", "serve"]
+  },
+  {
+    "key": "hit",
+    "label": "Hit",
+    "frames": ["hit-request", "hit-found", "hit-serve"]
+  },
+  {
+    "key": "evict",
+    "label": "Full: evict oldest",
+    "frames": ["evict-request", "evict-miss", "evict-fill", "evict-serve"]
+  }
+]

package/instructions/animations/log-replay/README.md

@@ -0,0 +1,25 @@
+# Log replay
+
+An append-only event log replays one event per frame into a derived accounts table, and a second scenario redelivers an event that the checkpoint guard skips, so the state visibly stays put.
+
+## Use when
+
+A change adds or alters an event-sourced projection, a consumer of an at-least-once queue, or any handler that folds a log into state. The reviewer needs to see which row each event touches, and that a duplicate or replayed event cannot change the result.
+
+## Shows
+
+- Left, the events seen so far, the current one highlighted; a redelivered event carries a `redelivered` chip.
+- Right, the derived rows: a new row toned `added`, a changed balance `modified`, the touched row underlined, and a checkpoint badge.
+- Under the table, the handler's outcome for the current event; it opens the code that decided it.
+- Clean replay: four events build the state. Redelivered event: #2 arrives again, the row shows `unchanged`, the checkpoint does not move, and the replay ends in the same state as the clean one.
+
+## Technique
+
+Data-driven, with `scenarios` for the two paths; frames the paths share (#1 and #2) are declared once. Each frame's `data` holds the events seen so far, every account row with its tone, the touched row, the checkpoint and the outcome. One `whiteboard.on("*", ...)` handler redraws both tables and returns `whiteboard.animate` fades for what is new since `previous`: the appended event, a new row, a changed balance. Nothing animates on the right when an event is skipped, which is the point. `frame.code[0]` becomes the outcome chip's `data-wb-open`.
+
+## Adapt
+
+- Rewrite `frames.json` with your events and state rows; give each frame the whole log so far and the whole state, never a delta.
+- Change the column headers and `row([...])` cells in `animation.html` if your state has more than two columns.
+- For an out-of-order event instead of a duplicate, keep the same shape: mark the event in `events`, leave the state as it was, and say why in `result`.
+- Name the handler and its guard in `block.json` `code` and list the one each frame exercises.

package/instructions/animations/log-replay/animation.html

@@ -0,0 +1,86 @@
+<style>
+  .replay { --wb-columns: 2; }
+  .seq { width: var(--wb-space-40); }
+  .wb-table tr[data-current] td { color: var(--wb-ink); background: var(--wb-accent-soft); }
+  .wb-table tr[data-touched] td { box-shadow: inset 0 -2px 0 var(--wb-accent); }
+  .aside { margin-left: var(--wb-space-6); }
+  .checkpoint { align-self: flex-start; }
+  .outcome { align-self: flex-start; margin-top: var(--wb-space-4); }
+</style>
+<div class="wb-grid replay">
+  <div class="wb-card">
+    <div class="wb-card-head"><i class="wb-card-dot"></i><span class="wb-card-title">events</span></div>
+    <div class="wb-card-note">append-only log, replayed in order</div>
+    <table class="wb-table">
+      <thead><tr><th class="seq">seq</th><th>event</th></tr></thead>
+      <tbody class="log"></tbody>
+    </table>
+  </div>
+  <div class="wb-card">
+    <div class="wb-card-head"><i class="wb-card-dot"></i><span class="wb-card-title">accounts</span></div>
+    <div class="wb-card-note">derived state, built by apply(event)</div>
+    <span class="wb-badge checkpoint"></span>
+    <table class="wb-table">
+      <thead><tr><th>account</th><th>balance</th></tr></thead>
+      <tbody class="state"></tbody>
+    </table>
+    <span class="wb-chip outcome"></span>
+  </div>
+</div>
+<script>
+  const log = document.querySelector(".log");
+  const state = document.querySelector(".state");
+  const checkpoint = document.querySelector(".checkpoint");
+
+  function row(cells) {
+    const tr = document.createElement("tr");
+    for (const cell of cells) tr.insertCell().append(cell);
+    return tr;
+  }
+
+  function chip(text, tone, className = "aside") {
+    const el = document.createElement("span");
+    el.className = `wb-chip ${className}`;
+    el.dataset.tone = tone;
+    el.textContent = text;
+    return el;
+  }
+
+  const enter = (el) =>
+    whiteboard.animate(el, [{ opacity: 0, transform: "translateY(-4px)" }, { opacity: 1, transform: "none" }], 300);
+
+  whiteboard.on("*", ({ frame, previous }) => {
+    const { events, accounts, touched, applied, result } = frame.data;
+
+    const logRows = events.map((event, index) => {
+      const tr = row([`#${event.seq}`, event.text]);
+      if (event.redelivered) tr.cells[1].append(chip("redelivered", "muted"));
+      tr.toggleAttribute("data-current", index === events.length - 1);
+      return tr;
+    });
+    log.replaceChildren(...logRows);
+
+    const before = new Map((previous?.data.accounts ?? []).map((account) => [account.id, account.balance]));
+    const motion = [];
+    state.replaceChildren(
+      ...accounts.map((account) => {
+        const tr = row([account.id, String(account.balance)]);
+        if (account.tone) tr.dataset.tone = account.tone;
+        if (account.note) tr.cells[1].append(chip(account.note, "muted"));
+        tr.toggleAttribute("data-touched", account.id === touched);
+        if (!before.has(account.id)) motion.push(enter(tr));
+        else if (before.get(account.id) !== account.balance) motion.push(enter(tr.cells[1]));
+        return tr;
+      }),
+    );
+
+    checkpoint.textContent = `checkpoint #${applied}`;
+    // A fresh element per frame, so its code tooltip follows the frame's code name.
+    const outcome = chip(result.text, result.tone, "outcome");
+    if (frame.code) outcome.dataset.wbOpen = frame.code[0];
+    document.querySelector(".outcome").replaceWith(outcome);
+
+    const newEvents = logRows.slice(previous?.data.events.length ?? 0);
+    return [...newEvents.map(enter), enter(outcome), ...motion];
+  });
+</script>

package/instructions/animations/log-replay/block.json

@@ -0,0 +1,10 @@
+{
+  "title": "Replaying the account log",
+  "code": {
+    "apply": { "source": "head/src/ledger/apply.ts#L12-L40", "label": "apply" },
+    "guard": {
+      "source": "head/src/ledger/apply.ts#L13-L17",
+      "label": "checkpoint guard"
+    }
+  }
+}

package/instructions/animations/log-replay/frames.json

@@ -0,0 +1,143 @@
+[
+  {
+    "key": "open-a",
+    "title": "#1 opens account A",
+    "label": "OPEN A",
+    "code": ["apply"],
+    "caption": "apply() inserts A with a zero balance and moves the checkpoint to #1.",
+    "data": {
+      "events": [{ "seq": 1, "text": "AccountOpened A" }],
+      "accounts": [{ "id": "A", "balance": 0, "tone": "added" }],
+      "touched": "A",
+      "applied": 1,
+      "result": { "text": "#1 applied: insert A", "tone": "added" }
+    }
+  },
+  {
+    "key": "deposit-a",
+    "title": "#2 deposits into A",
+    "label": "DEPOSIT 50",
+    "code": ["apply"],
+    "caption": "Each event touches one row. The deposit raises A's balance and the checkpoint follows.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" }
+      ],
+      "accounts": [{ "id": "A", "balance": 50, "tone": "modified" }],
+      "touched": "A",
+      "applied": 2,
+      "result": { "text": "#2 applied: A 0 → 50", "tone": "modified" }
+    }
+  },
+  {
+    "key": "open-b",
+    "title": "#3 opens account B",
+    "label": "OPEN B",
+    "code": ["apply"],
+    "caption": "A second account is a new row; A is untouched.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 3, "text": "AccountOpened B" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 50 },
+        { "id": "B", "balance": 0, "tone": "added" }
+      ],
+      "touched": "B",
+      "applied": 3,
+      "result": { "text": "#3 applied: insert B", "tone": "added" }
+    }
+  },
+  {
+    "key": "withdraw-a",
+    "title": "#4 withdraws from A",
+    "label": "WITHDRAW 20",
+    "code": ["apply"],
+    "caption": "The replay ends at checkpoint #4 with A at 30 and B at 0, the same state the live handler built.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 3, "text": "AccountOpened B" },
+        { "seq": 4, "text": "Withdrew A 20" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 30, "tone": "modified" },
+        { "id": "B", "balance": 0 }
+      ],
+      "touched": "A",
+      "applied": 4,
+      "result": { "text": "#4 applied: A 50 → 30", "tone": "modified" }
+    }
+  },
+  {
+    "key": "redeliver",
+    "title": "#2 arrives again",
+    "label": "REDELIVER #2",
+    "code": ["guard"],
+    "duration": 4500,
+    "caption": "The broker redelivers #2. Its seq is not past the checkpoint, so apply() skips it: A stays at 50 and the checkpoint stays at #2.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 2, "text": "Deposited A 50", "redelivered": true }
+      ],
+      "accounts": [{ "id": "A", "balance": 50, "note": "unchanged" }],
+      "touched": "A",
+      "applied": 2,
+      "result": {
+        "text": "#2 ≤ checkpoint #2: skipped, no change",
+        "tone": "muted"
+      }
+    }
+  },
+  {
+    "key": "dup-open-b",
+    "title": "#3 opens account B",
+    "label": "OPEN B",
+    "code": ["apply"],
+    "caption": "Replay continues from the checkpoint as if the duplicate never arrived.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 2, "text": "Deposited A 50", "redelivered": true },
+        { "seq": 3, "text": "AccountOpened B" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 50 },
+        { "id": "B", "balance": 0, "tone": "added" }
+      ],
+      "touched": "B",
+      "applied": 3,
+      "result": { "text": "#3 applied: insert B", "tone": "added" }
+    }
+  },
+  {
+    "key": "dup-withdraw-a",
+    "title": "#4 withdraws from A",
+    "label": "WITHDRAW 20",
+    "code": ["apply"],
+    "caption": "The replay ends with A at 30, B at 0 and checkpoint #4, the same state as the clean replay. Applying #2 twice would have left A at 80.",
+    "data": {
+      "events": [
+        { "seq": 1, "text": "AccountOpened A" },
+        { "seq": 2, "text": "Deposited A 50" },
+        { "seq": 2, "text": "Deposited A 50", "redelivered": true },
+        { "seq": 3, "text": "AccountOpened B" },
+        { "seq": 4, "text": "Withdrew A 20" }
+      ],
+      "accounts": [
+        { "id": "A", "balance": 30, "tone": "modified" },
+        { "id": "B", "balance": 0 }
+      ],
+      "touched": "A",
+      "applied": 4,
+      "result": { "text": "#4 applied: A 50 → 30", "tone": "modified" }
+    }
+  }
+]

package/instructions/animations/log-replay/scenarios.json

@@ -0,0 +1,18 @@
+[
+  {
+    "key": "clean",
+    "label": "Clean replay",
+    "frames": ["open-a", "deposit-a", "open-b", "withdraw-a"]
+  },
+  {
+    "key": "duplicate",
+    "label": "Redelivered event",
+    "frames": [
+      "open-a",
+      "deposit-a",
+      "redeliver",
+      "dup-open-b",
+      "dup-withdraw-a"
+    ]
+  }
+]

package/instructions/animations/queue-workers/README.md

@@ -0,0 +1,23 @@
+# Bounded queue with two workers
+
+A data-driven drawing of a producer, a bounded queue and two workers that shows jobs moving through it under steady load and under a burst that hits the bound.
+
+## Use when
+
+A change introduces or tunes a job queue, a worker pool or a channel with a capacity, and the reviewer needs to see what happens when producers outrun consumers.
+
+## Shows
+
+- Steady load: jobs are put, taken from the head by idle workers, and completed into Done; the queue stays short.
+- Burst: the queue fills to its bound, `put()` blocks the producer, a completion frees a slot, and the waiting put goes through.
+
+## Technique
+
+Data-driven. Each frame's `data` holds the full state: the producer's next job and state, the queue contents (head first), the bound, each worker's job and the done list. One `whiteboard.on("*", ...)` handler redraws every card from it, then animates only what changed: it records where each job (`data-job`) was drawn before the redraw and glides it from there with `whiteboard.animate`, fading in jobs that are new. `whiteboard.arrow` draws the edges; the put edge takes `data-tone="removed"` while the producer is blocked. The producer and workers are `data-form="bars"`, parts of this codebase, and the queue a violet `data-form="stack"`, so the silhouettes tell them apart before the titles do.
+
+## Adapt
+
+- Edit only frames.json for new steps or scenarios; the script never names a frame key.
+- Change `bound` in the data, or add a worker: a card with id `w3`, its arrow, and a third entry in each frame's `workers`.
+- For a queue that drops or rejects instead of blocking, add a producer state with its own note and send the refused job to a "Dropped" well like Done.
+- Point `code` in block.json at your put and take paths; the cards open them with `data-wb-open`.

package/instructions/animations/queue-workers/animation.html

@@ -0,0 +1,107 @@
+<div class="wb-grid pipeline">
+  <div class="wb-card" id="producer" data-form="bars" data-wb-open="put">
+    <span class="wb-card-title">Producer</span>
+    <span class="wb-card-note"></span>
+    <div class="wb-items"></div>
+  </div>
+  <div class="wb-card" id="queue" data-form="stack" data-color="violet" data-wb-open="put">
+    <span class="wb-card-title">Queue</span>
+    <span class="wb-card-note"></span>
+    <div class="wb-items"></div>
+  </div>
+  <div class="workers">
+    <div class="wb-card" id="w1" data-form="bars" data-wb-open="take">
+      <span class="wb-card-title">Worker 1</span>
+      <span class="wb-card-note"></span>
+      <div class="wb-items"></div>
+    </div>
+    <div class="wb-card" id="w2" data-form="bars" data-wb-open="take">
+      <span class="wb-card-title">Worker 2</span>
+      <span class="wb-card-note"></span>
+      <div class="wb-items"></div>
+    </div>
+    <div class="wb-well done">
+      <span class="wb-caps">Done</span>
+      <div class="wb-items"></div>
+    </div>
+  </div>
+</div>
+
+<style>
+  .pipeline { --wb-columns: 3; column-gap: var(--wb-space-48); align-items: center; }
+  .workers { display: flex; flex-direction: column; gap: var(--wb-space-12); }
+  .done { padding: var(--wb-space-6) var(--wb-space-12); }
+  .done .wb-items { min-height: var(--wb-space-20); }
+  /* Every job and empty slot is the same width, so the queue reads as slots. */
+  .slot { min-width: var(--wb-space-28); text-align: center; }
+  .slot:empty::before { content: "\00a0"; }
+  @media (max-width: 520px) {
+    .pipeline { grid-template-columns: minmax(0, 1fr); row-gap: var(--wb-space-40); }
+  }
+</style>
+
+<script>
+  const put = whiteboard.arrow("#producer", "#queue", { label: "put" });
+  whiteboard.arrow("#queue", "#w1");
+  whiteboard.arrow("#queue", "#w2");
+
+  const slot = (job, tone) => {
+    const el = document.createElement("span");
+    el.className = "wb-chip slot";
+    if (job) el.textContent = el.dataset.job = job;
+    if (tone) el.dataset.tone = tone;
+    return el;
+  };
+
+  const show = (selector, note, chips, tone) => {
+    const card = document.querySelector(selector);
+    card.querySelector(".wb-card-note").textContent = note;
+    card.querySelector(".wb-items").replaceChildren(...chips);
+    if (tone) card.dataset.tone = tone;
+    else delete card.dataset.tone;
+  };
+
+  whiteboard.on("*", ({ frame }) => {
+    const { producer, queue, bound, workers, done } = frame.data;
+
+    // Where every job was drawn, so a job that changed place glides from there.
+    const was = new Map(
+      [...document.querySelectorAll("[data-job]")].map((el) => [el.dataset.job, el.getBoundingClientRect()]),
+    );
+
+    const blocked = producer.state === "blocked";
+    const notes = { ready: "next", blocked: "put() blocks:", woken: "put() resumes:" };
+    show(
+      "#producer",
+      producer.next ? `${notes[producer.state]} ${producer.next}` : "idle",
+      [slot(producer.next, blocked ? "removed" : undefined)],
+      blocked ? "removed" : undefined,
+    );
+    if (blocked) put.dataset.tone = "removed";
+    else delete put.dataset.tone;
+
+    // Tail on the left, head on the right beside the workers.
+    const free = Array.from({ length: bound - queue.length }, () => slot(null, "muted"));
+    const full = queue.length === bound;
+    show(
+      "#queue",
+      `${queue.length} of ${bound}${full ? ", full" : ""}`,
+      [...free, ...queue.toReversed().map((job) => slot(job))],
+      full ? "modified" : undefined,
+    );
+
+    workers.forEach((job, i) =>
+      show(`#w${i + 1}`, job ? `running ${job}` : "idle", [slot(job, job ? undefined : "muted")]),
+    );
+    document.querySelector(".done .wb-items").replaceChildren(...done.map((job) => slot(job, "added")));
+
+    return [...document.querySelectorAll("[data-job]")].flatMap((el) => {
+      const from = was.get(el.dataset.job);
+      if (!from) return whiteboard.animate(el, [{ opacity: 0 }, { opacity: 1 }], 300);
+      const to = el.getBoundingClientRect();
+      const [dx, dy] = [from.left - to.left, from.top - to.top];
+      if (!dx && !dy) return [];
+      return whiteboard.animate(el, [{ transform: `translate(${dx}px, ${dy}px)` }, { transform: "none" }], 600);
+    });
+  });
+</script>

package/instructions/animations/queue-workers/block.json

@@ -0,0 +1,13 @@
+{
+  "title": "Bounded queue with two workers",
+  "code": {
+    "put": {
+      "source": "head/src/jobs/queue.ts#L14-L32",
+      "label": "BoundedQueue.put"
+    },
+    "take": {
+      "source": "head/src/jobs/worker.ts#L8-L26",
+      "label": "Worker.run"
+    }
+  }
+}