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

package/instructions/animations/request-across-layers/frames.json

@@ -0,0 +1,58 @@
+[
+  {
+    "key": "request",
+    "title": "The client posts a JSON body",
+    "label": "REQUEST",
+    "caption": "The body is untyped JSON: qty arrives as the string \"2\".",
+    "code": ["validate"]
+  },
+  {
+    "key": "validate",
+    "title": "The API validates it into a DTO",
+    "label": "VALIDATE",
+    "caption": "validateCreateOrder parses the body; qty becomes a number and the service only ever sees a CreateOrderDto.",
+    "code": ["validate"]
+  },
+  {
+    "key": "persist",
+    "title": "The service builds an Order and inserts it",
+    "label": "PERSIST",
+    "caption": "OrderService builds a domain Order, which has no id until the database assigns one.",
+    "code": ["service", "repository"]
+  },
+  {
+    "key": "stored",
+    "title": "The database returns the row",
+    "label": "STORED",
+    "caption": "The insert returns the row with the id Postgres assigned.",
+    "code": ["repository"]
+  },
+  {
+    "key": "map",
+    "title": "The row maps back to an Order",
+    "label": "MAP",
+    "caption": "The service returns a domain Order, not the row: the API never sees column names.",
+    "code": ["service"]
+  },
+  {
+    "key": "respond",
+    "title": "The API answers 201 with a response body",
+    "label": "RESPOND",
+    "caption": "The API serializes the Order for the wire, exposing the id as a public string.",
+    "code": ["validate"]
+  },
+  {
+    "key": "bad-request",
+    "title": "The client posts an invalid body",
+    "label": "BAD REQUEST",
+    "caption": "Same endpoint, but qty is \"-1\".",
+    "code": ["validate"]
+  },
+  {
+    "key": "rejected",
+    "title": "Validation rejects it at the API",
+    "label": "REJECTED",
+    "caption": "The API answers 422 naming the field. The service and the database are never called.",
+    "code": ["validate"]
+  }
+]

package/instructions/animations/request-across-layers/scenarios.json

@@ -0,0 +1,12 @@
+[
+  {
+    "key": "success",
+    "label": "Valid order",
+    "frames": ["request", "validate", "persist", "stored", "map", "respond"]
+  },
+  {
+    "key": "invalid",
+    "label": "Validation fails",
+    "frames": ["bad-request", "rejected"]
+  }
+]

package/instructions/animations/request-timing/README.md

@@ -0,0 +1,22 @@
+# One read, with and without the cache
+
+A clip of one request crossing client, API, cache and database as a continuous trip, with an elapsed bar, played once as a cache hit and once as a miss.
+
+## Use when
+
+A change adds, removes or moves a cache, a retry or any hop on a request's path, and the reviewer has to feel what it does to latency: the point is how long each leg takes, not a list of states.
+
+## Shows
+
+A GET token rides from the client to the API and on to the cache. On a hit the cache answers at once; on a miss the read goes on to Postgres, waits there, and comes back through the cache to fill it. A 200 token rides home and the elapsed bar, which fills for the whole trip, stops at that scenario's total. The markers name the same five beats in both, so jumping to Cache lookup in either shows where the paths split.
+
+## Technique
+
+A clip: markers.json declares the beats, and the script builds one timeline per scenario with `whiteboard.clip(key)`, placing each marker with `.marker(key)` where the request reaches it. Tokens move by `left` percentages, so the trip follows the four-column layout at any width. Everything that differs between the scenarios (the result chip, the second token, the total) is a `set` on that scenario's timeline, so a jump back undoes it. The elapsed bar is one tween added at position 0 with the trip's length, scaled by the longest trip so the two scenarios' bars compare.
+
+## Adapt
+
+- Rename the four nodes and their `<small>` lines for your path, keeping each node's `data-form` to what it stands for (a window, bars, a drum, a cylinder), and keep the column centers in `client`, `api`, `cache`, `db` in step with the grid.
+- Change the leg lengths in `hop` and `hold` to the proportions that matter, a slow query or a fast cache, and set `LONGEST` to the longest scenario's sum.
+- Add a scenario (a stale entry, a timeout) with an entry in scenarios.json and one more `build` call that places every marker.
+- Point `code` at your client call, handler, cache and query, and list them on the markers that show them.

package/instructions/animations/request-timing/animation.html

@@ -0,0 +1,120 @@
+<div class="trip">
+  <div class="stops">
+    <div class="wb-node" data-form="window" data-wb-open="client">Client<small>fetchOrder(7)</small></div>
+    <div class="wb-node" data-form="bars" data-wb-open="handler">API<small>GET /orders/7</small></div>
+    <div class="wb-node" id="cache" data-form="drum" data-wb-open="cache">Cache<small>orders:7</small></div>
+    <div class="wb-node" id="db" data-form="cylinder" data-color="teal" data-wb-open="query">Postgres<small>SELECT</small></div>
+  </div>
+  <div class="wb-lane track">
+    <span class="wb-token packet out" data-visible data-labelled>GET</span>
+    <span class="wb-token packet back" data-labelled data-tone="added">200</span>
+  </div>
+  <div class="wb-layers results">
+    <span class="wb-chip result hit" data-tone="added">hit: served from memory</span>
+    <span class="wb-chip result miss" data-tone="modified">miss: read from Postgres, then cached</span>
+  </div>
+  <div class="clock">
+    <span class="wb-caps">elapsed</span>
+    <div class="bar"><div class="fill"></div></div>
+    <span class="wb-layers totals">
+      <span class="wb-mono total hit">38 ms</span>
+      <span class="wb-mono total miss">212 ms</span>
+    </span>
+  </div>
+</div>
+
+<style>
+  .trip {
+    display: grid;
+    gap: var(--wb-space-16);
+    padding: var(--wb-space-20) var(--wb-space-24);
+  }
+  .stops {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    justify-items: center;
+    gap: var(--wb-space-16);
+  }
+  .packet { top: 50%; }
+  .packet.out { left: 12.5%; }
+  .packet.back { left: 62.5%; }
+  .results { justify-items: center; min-height: var(--wb-space-24); }
+  .result, .total { opacity: 0; }
+  .clock {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr) max-content;
+    align-items: center;
+    gap: var(--wb-space-12);
+  }
+  .bar {
+    height: var(--wb-space-6);
+    border-radius: var(--wb-radius-control);
+    background: var(--wb-well);
+    overflow: hidden;
+  }
+  .fill {
+    height: 100%;
+    background: var(--wb-accent);
+    transform: scaleX(0);
+    transform-origin: left;
+  }
+  .totals { justify-items: end; color: var(--wb-ink-muted); }
+</style>
+
+<script>
+  // The centers of the four columns, as the packet's left edge.
+  const [client, api, cache, db] = ["12.5%", "37.5%", "62.5%", "87.5%"];
+  const out = document.querySelector(".packet.out");
+  const back = document.querySelector(".packet.back");
+
+  // One timeline per scenario. Every marker is placed on both, at the moment
+  // the request reaches it, so the strip jumps to the same beat in either.
+  const build = (key, miss) => {
+    const clip = whiteboard.clip(key);
+    let elapsed = 0;
+
+    const hop = (token, from, to, duration) => {
+      clip.add(token, { left: [from, to], duration, ease: "inOutQuad" });
+      elapsed += duration;
+    };
+
+    const hold = (target, duration) => {
+      clip.add(target, { scale: [1, 1.06, 1], duration });
+      elapsed += duration;
+    };
+
+    clip.marker("sent");
+    hop(out, client, api, 700);
+    clip.marker("accepted");
+    hop(out, api, cache, 600);
+    clip.marker("lookup");
+
+    if (miss) {
+      clip.set(".result.miss", { opacity: 1 });
+      hop(out, cache, db, 600);
+      hold("#db", 900);
+      clip.set(out, { opacity: 0 }).set(back, { left: db, opacity: 1 });
+      hop(back, db, cache, 600);
+    } else {
+      clip.set(".result.hit", { opacity: 1 });
+      hold("#cache", 300);
+      clip.set(out, { opacity: 0 }).set(back, { left: cache, opacity: 1 });
+    }
+
+    hop(back, cache, api, 600);
+    clip.marker("reply");
+    hop(back, api, client, 700);
+    clip.set(`.total.${miss ? "miss" : "hit"}`, { opacity: 1 });
+    clip.marker("received");
+
+    // The elapsed bar fills over the whole trip, from the start, on one
+    // scale for both scenarios: the miss's trip fills it.
+    clip.add(".fill", { scaleX: [0, elapsed / LONGEST], duration: elapsed, ease: "linear" }, 0);
+  };
+
+  // The miss's trip, in milliseconds: the sum of its hops and its hold.
+  const LONGEST = 4700;
+
+  build("hit", false);
+  build("miss", true);
+</script>

package/instructions/animations/request-timing/block.json

@@ -0,0 +1,21 @@
+{
+  "title": "One read, with and without the cache",
+  "code": {
+    "client": {
+      "source": "head/web/src/orders/api.ts#L14-L30",
+      "label": "fetchOrder"
+    },
+    "handler": {
+      "source": "head/src/api/orders/get.ts#L8-L36",
+      "label": "getOrder"
+    },
+    "cache": {
+      "source": "head/src/orders/cache.ts#L10-L44",
+      "label": "OrderCache.read"
+    },
+    "query": {
+      "source": "head/src/orders/repository.ts#L52-L70",
+      "label": "selectOrder"
+    }
+  }
+}

package/instructions/animations/request-timing/markers.json

@@ -0,0 +1,32 @@
+[
+  {
+    "key": "sent",
+    "title": "Request sent",
+    "caption": "The client asks for order 7.",
+    "code": ["client"]
+  },
+  {
+    "key": "accepted",
+    "title": "API accepts",
+    "caption": "getOrder parses the id and asks the cache first.",
+    "code": ["handler"]
+  },
+  {
+    "key": "lookup",
+    "title": "Cache lookup",
+    "caption": "The cache either holds orders:7 or sends the read on to Postgres.",
+    "code": ["cache", "query"]
+  },
+  {
+    "key": "reply",
+    "title": "API replies",
+    "caption": "The order is back in the API, which answers 200.",
+    "code": ["handler"]
+  },
+  {
+    "key": "received",
+    "title": "Client renders",
+    "caption": "The reply lands. The elapsed bar shows what the cache saved.",
+    "code": ["client"]
+  }
+]

package/instructions/animations/request-timing/scenarios.json

@@ -0,0 +1,4 @@
+[
+  { "key": "hit", "label": "Cache hit" },
+  { "key": "miss", "label": "Cache miss" }
+]

package/instructions/animations/retry-backoff/README.md

@@ -0,0 +1,22 @@
+# Retry with exponential backoff
+
+Attempts from a caller to a service on a time axis in seconds, with waits that double between them, in one path that succeeds on the third attempt and one that gives up after the maximum.
+
+## Use when
+
+A change adds or tunes a retry loop: the base delay, the multiplier, the attempt cap, or which errors count as retryable, and the reviewer needs to see when each attempt actually lands and how long the caller can be held.
+
+## Shows
+
+Each attempt drops a request from the caller lane to the service lane and lands a status chip. Between attempts, a wait line grows along the caller lane, its length proportional to the delay, against an axis ticked in seconds. One scenario ends with a 200 at 3s; the other runs four attempts and throws at 7s.
+
+## Technique
+
+A scene in hand-made HTML: the script lays attempts and waits out from two small arrays, positioning each by its time in seconds (`--t`). Each is tied to its frame with `data-enter`; `whiteboard.arrow` links an attempt's caller marker to its result, `whiteboard.travel` moves one `GET` token along it, and `whiteboard.timeline(frame)` reveals the result and grows the wait line, so a jump or reduced motion lands on the end state. Attempt markers carry `data-wb-open="retry"` and waits `data-wb-open="backoff"`; each frame's `code` lists the range it explains.
+
+## Adapt
+
+- Edit `attempts` and `waits` to your schedule: a different base, factor or cap, or jitter (give each wait its real `span`). Keep the axis domain (`8` in the CSS and the tick loop) just past the last attempt.
+- Rename the status chips and the token label to your protocol, such as a gRPC code or a queue redelivery.
+- Add a scenario for another branch, such as a non-retryable 400 that fails at once, as new frames and one new entry in `attempts`.
+- Point `code` in block.json at your loop and delay function.

package/instructions/animations/retry-backoff/animation.html

@@ -0,0 +1,122 @@
+<div class="retry">
+  <div class="top">
+    <span class="wb-badge" data-wb-open="backoff">base 1s · ×2 · max 4 attempts</span>
+    <span class="wb-layers">
+      <span class="wb-badge" data-tone="added" data-enter="a3ok">returned 200 at 3s</span>
+      <span class="wb-badge" data-tone="removed" data-enter="giveup">threw 503 at 7s</span>
+    </span>
+  </div>
+  <span class="wb-caps">caller</span>
+  <div class="wb-lane track caller"></div>
+  <span class="wb-caps service-name">service</span>
+  <div class="wb-lane track service"></div>
+  <span></span>
+  <div class="track axis"></div>
+</div>
+
+<style>
+  .retry {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    align-items: center;
+    gap: var(--wb-space-12) var(--wb-space-16);
+    padding: var(--wb-space-20) var(--wb-space-24);
+  }
+  .top {
+    grid-column: 1 / -1;
+    display: flex;
+    justify-content: space-between;
+    margin-bottom: var(--wb-space-24);
+  }
+  .top .wb-layers { justify-items: end; }
+  .service-name, .service { margin-top: var(--wb-space-56); }
+  .track { position: relative; margin-inline: var(--wb-space-16); }
+  /* Seconds become a share of the track: the axis spans 0 to 8s. */
+  .at, .wait, .tick { position: absolute; left: calc(var(--t) * 100% / 8); }
+  .at { top: 50%; translate: -50% -50%; }
+  .wait { top: 50%; width: calc(var(--span) * 100% / 8); }
+  .wait-line {
+    height: var(--wb-space-2);
+    margin-top: calc(var(--wb-space-2) / -2);
+    background: var(--wb-accent);
+    transform-origin: left;
+  }
+  .wait-label {
+    position: absolute;
+    left: 50%;
+    bottom: var(--wb-space-6);
+    translate: -50% 0;
+    color: var(--wb-accent);
+    font: var(--wb-text-micro) var(--wb-font-mono);
+    white-space: nowrap;
+  }
+  .caller .wb-chip { background: var(--wb-surface); }
+  .axis { height: var(--wb-space-20); border-top: 1px solid var(--wb-rule); }
+  .tick {
+    top: 0;
+    translate: -50% 0;
+    padding-top: var(--wb-space-4);
+    color: var(--wb-ink-faint);
+    font: var(--wb-text-micro) var(--wb-font-mono);
+  }
+  .tick::before {
+    content: "";
+    position: absolute;
+    top: 0;
+    left: 50%;
+    height: var(--wb-space-4);
+    border-left: 1px solid var(--wb-rule);
+  }
+</style>
+
+<script>
+  // Attempt n starts after waiting base × 2^(n−1) seconds: at 0, 1, 3 and 7s.
+  const attempts = [
+    { frame: "a1", n: 1, t: 0, status: "503" },
+    { frame: "a2", n: 2, t: 1, status: "503" },
+    { frame: "a3ok", n: 3, t: 3, status: "200", tone: "added" },
+    { frame: "a3fail", n: 3, t: 3, status: "503" },
+    { frame: "a4", n: 4, t: 7, status: "503" },
+  ];
+  const waits = [
+    { frame: "w1", t: 0, span: 1 },
+    { frame: "w2", t: 1, span: 2 },
+    { frame: "w3", t: 3, span: 4 },
+  ];
+
+  const caller = document.querySelector(".caller");
+  const service = document.querySelector(".service");
+  const axis = document.querySelector(".axis");
+  const request = whiteboard.token({ label: "GET" });
+
+  const place = (parent, className, vars, html) => {
+    const element = document.createElement("div");
+    element.className = className;
+    for (const [name, value] of Object.entries(vars)) element.style.setProperty(`--${name}`, value);
+    element.innerHTML = html;
+    parent.append(element);
+    return element;
+  };
+
+  for (let t = 0; t <= 8; t++) place(axis, "tick", { t }, `${t}s`);
+
+  for (const { frame, t, span } of waits) {
+    const wait = place(caller, "wait", { t, span }, `<div class="wait-line"></div><span class="wait-label">wait ${span}s</span>`);
+    wait.dataset.enter = frame;
+    wait.dataset.wbOpen = "backoff";
+    // The line grows at 0.5s per second of delay, so a longer wait reads as longer.
+    whiteboard.timeline(frame).add(wait.firstChild, { scaleX: [0, 1], duration: span * 500, ease: "linear" });
+  }
+
+  for (const { frame, n, t, status, tone = "removed" } of attempts) {
+    const marker = place(caller, "at", { t }, `<span class="wb-chip">#${n}</span>`);
+    marker.dataset.enter = frame;
+    marker.dataset.wbOpen = "retry";
+    const result = place(service, "at", { t }, `<span class="wb-chip" data-tone="${tone}">${status}</span>`);
+    result.dataset.enter = frame;
+
+    const arrow = whiteboard.arrow(marker, result, { enter: frame });
+    whiteboard.travel(request, arrow, frame);
+    whiteboard.timeline(frame).add(result.firstChild, { opacity: [0, 1], duration: 250 }, 900);
+  }
+</script>

package/instructions/animations/retry-backoff/block.json

@@ -0,0 +1,10 @@
+{
+  "title": "Retry with exponential backoff",
+  "code": {
+    "retry": { "source": "head/src/retry.ts#L10-L36", "label": "retry loop" },
+    "backoff": {
+      "source": "head/src/retry.ts#L38-L44",
+      "label": "backoffDelay"
+    }
+  }
+}

package/instructions/animations/retry-backoff/frames.json

@@ -0,0 +1,65 @@
+[
+  {
+    "key": "a1",
+    "title": "First attempt fails",
+    "label": "ATTEMPT 1",
+    "caption": "At 0s the caller sends the request and the service answers 503. The loop treats it as retryable instead of returning it.",
+    "code": ["retry"]
+  },
+  {
+    "key": "w1",
+    "title": "Wait 1s",
+    "label": "WAIT 1S",
+    "caption": "The delay is base × 2^(attempt − 1), so 1s after the first failure. The caller sleeps and sends nothing.",
+    "code": ["backoff"]
+  },
+  {
+    "key": "a2",
+    "title": "Second attempt fails",
+    "label": "ATTEMPT 2",
+    "caption": "At 1s the caller tries again and gets another 503.",
+    "code": ["retry"]
+  },
+  {
+    "key": "w2",
+    "title": "Wait 2s",
+    "label": "WAIT 2S",
+    "caption": "The delay doubles to 2s, so the next attempt lands at 3s. Each failure gives the service longer to recover.",
+    "code": ["backoff"]
+  },
+  {
+    "key": "a3ok",
+    "title": "Third attempt succeeds",
+    "label": "ATTEMPT 3",
+    "caption": "At 3s the service answers 200. The loop returns that response, after 3s spent waiting.",
+    "code": ["retry"]
+  },
+  {
+    "key": "a3fail",
+    "title": "Third attempt fails",
+    "label": "ATTEMPT 3",
+    "caption": "At 3s the service still answers 503.",
+    "code": ["retry"]
+  },
+  {
+    "key": "w3",
+    "title": "Wait 4s",
+    "label": "WAIT 4S",
+    "caption": "The delay doubles again to 4s. Attempts thin out as failures pile up, so a struggling service is not hammered.",
+    "code": ["backoff"]
+  },
+  {
+    "key": "a4",
+    "title": "Last attempt fails",
+    "label": "ATTEMPT 4",
+    "caption": "At 7s the fourth attempt, the maximum, gets a 503 too.",
+    "code": ["retry"]
+  },
+  {
+    "key": "giveup",
+    "title": "Give up",
+    "label": "GIVE UP",
+    "caption": "With no attempts left, the loop stops and throws the last 503 to the caller instead of waiting 8s more.",
+    "code": ["retry"]
+  }
+]

package/instructions/animations/retry-backoff/scenarios.json

@@ -0,0 +1,12 @@
+[
+  {
+    "key": "succeeds",
+    "label": "Succeeds on attempt 3",
+    "frames": ["a1", "w1", "a2", "w2", "a3ok"]
+  },
+  {
+    "key": "gives-up",
+    "label": "Gives up after 4 attempts",
+    "frames": ["a1", "w1", "a2", "w2", "a3fail", "w3", "a4", "giveup"]
+  }
+]

package/instructions/animations/state-machine/README.md

@@ -0,0 +1,24 @@
+# State machine
+
+An entity's states drawn as nodes with their legal transitions as arrows, where each frame names the current state and the transition tried, a token rides the arrow taken, and an illegal transition is refused without a state change.
+
+## Use when
+
+A change adds, removes or guards a transition, such as an order status, a job lifecycle or a subscription, and the reviewer needs to see which moves are legal from where and what happens to one that is not.
+
+## Shows
+
+- Happy path: draft, submit to queued, pay to paid, ship to shipped, then a cancel refused because the order has shipped.
+- Cancellation: draft, queued, cancel to cancelled, then a late payment refused.
+- The current state is ringed and the persisted `status` value sits below; a refused move draws a dashed red arrow, its token stops partway, and a 409 chip names the reason.
+
+## Technique
+
+Data-driven: each frame's `data` is `{ state, transition?: { event, from, to, refused? } }`, complete per frame, and one `whiteboard.on("*", ...)` draws any frame from it. Nodes are `.wb-node` elements in a CSS grid, the start and the final states as `data-form="pill"`; `whiteboard.arrow` draws the edges and one `whiteboard.token` rides them. The ride is a `whiteboard.animate` over points sampled from the arrow's path, so it skips itself on a jump and under reduced motion; it plays only when stepping forward.
+
+## Adapt
+
+- Replace the nodes and the `arrow(...)` calls with your states and legal transitions; place nodes with the grid, at most four columns.
+- Write one frame per step in `frames.json`; a new scenario needs no script change.
+- Set `refused` to the error your code returns for an illegal move.
+- Point `code` at your transition table.

package/instructions/animations/state-machine/animation.html

@@ -0,0 +1,95 @@
+<style>
+  .machine {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    justify-items: center;
+    row-gap: var(--wb-space-72);
+    padding: var(--wb-space-24);
+  }
+  .machine [data-state="cancelled"] { grid-column: 2 / span 2; }
+  .wb-node[data-current] { box-shadow: 0 0 0 var(--wb-space-4) var(--wb-accent-soft); }
+  .status { padding-top: 0; justify-content: center; gap: var(--wb-space-8); }
+</style>
+
+<div class="machine">
+  <div class="wb-node" data-state="draft" data-form="pill">draft<small>editable</small></div>
+  <div class="wb-node" data-state="queued">queued<small>awaiting payment</small></div>
+  <div class="wb-node" data-state="paid">paid<small>awaiting shipment</small></div>
+  <div class="wb-node" data-state="shipped" data-form="pill">shipped<small>final</small></div>
+  <div class="wb-node" data-state="cancelled" data-form="pill">cancelled<small>final</small></div>
+</div>
+<div class="wb-row status">
+  <span class="wb-badge" data-wb-open="transitions"></span>
+  <span class="wb-chip" data-tone="removed"></span>
+</div>
+
+<script>
+  const nodes = Object.fromEntries(
+    [...document.querySelectorAll(".wb-node")].map((node) => [node.dataset.state, node]),
+  );
+  const [badge, refusal] = document.querySelectorAll(".status > *");
+  const token = whiteboard.token();
+  const arrows = new Map();
+
+  const arrow = (from, to, options) => {
+    const made = whiteboard.arrow(nodes[from], nodes[to], options);
+    arrows.set(`${from}>${to}`, made);
+    return made;
+  };
+
+  // The legal transitions. A refused one gets its arrow when a frame tries it.
+  arrow("draft", "queued", { label: "submit" });
+  arrow("queued", "paid", { label: "pay" });
+  arrow("paid", "shipped", { label: "ship" });
+  arrow("queued", "cancelled", { label: "cancel" });
+  arrow("paid", "cancelled", { label: "cancel" });
+
+  const mark = (state) => {
+    for (const [name, node] of Object.entries(nodes)) {
+      node.toggleAttribute("data-current", name === state);
+      if (name === state) node.dataset.tone = "accent";
+      else delete node.dataset.tone;
+    }
+    badge.textContent = `status = ${state}`;
+  };
+
+  let ride;
+
+  whiteboard.on("*", ({ frame, direction, instant }) => {
+    const { state, transition: move } = frame.data;
+    const key = move && `${move.from}>${move.to}`;
+
+    if (move?.refused && !arrows.has(key))
+      arrow(move.from, move.to, { label: move.event, tone: "removed", dashed: true, bend: -36 }).dataset.refused = "";
+
+    for (const [name, line] of arrows) {
+      if ("refused" in line.dataset) line.style.display = name === key ? "" : "none";
+      else if (name === key) line.dataset.tone = "accent";
+      else delete line.dataset.tone;
+    }
+
+    refusal.style.display = move?.refused ? "" : "none";
+    refusal.textContent = move?.refused ? `${move.event}: 409 ${move.refused}` : "";
+
+    ride?.cancel();
+    const plays = move && direction === "forward" && !instant;
+    mark(plays && !move.refused ? move.from : state);
+    if (!plays) return;
+
+    // Sample the routed line: a refused move stops partway and fades.
+    const line = arrows.get(key).querySelector(".wb-line");
+    const reach = line.getTotalLength() * (move.refused ? 0.3 : 1);
+    const steps = Array.from({ length: 13 }, (_, i) => line.getPointAtLength((reach * i) / 12));
+    token.dataset.tone = move.refused ? "removed" : "accent";
+    ride = whiteboard.animate(
+      token,
+      steps.map(({ x, y }, i) => ({ transform: `translate(${x}px, ${y}px)`, opacity: i === 12 ? 0 : 1 })),
+      { duration: 900, easing: "ease-in-out" },
+    );
+    ride.finished.then(
+      () => whiteboard.frame.key === frame.key && mark(state),
+      () => {},
+    );
+    return ride;
+  });
+</script>

package/instructions/animations/state-machine/block.json

@@ -0,0 +1,9 @@
+{
+  "title": "Order status transitions",
+  "code": {
+    "transitions": {
+      "source": "head/src/orders/transitions.ts#L8-L34",
+      "label": "ORDER_TRANSITIONS"
+    }
+  }
+}