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

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

@@ -0,0 +1,119 @@
+[
+  {
+    "key": "steady-put",
+    "title": "The producer enqueues two jobs",
+    "label": "PUT",
+    "caption": "j1 and j2 wait in the queue; both workers are idle.",
+    "data": {
+      "producer": { "next": "j3", "state": "ready" },
+      "queue": ["j1", "j2"],
+      "bound": 4,
+      "workers": [null, null],
+      "done": []
+    }
+  },
+  {
+    "key": "steady-take",
+    "title": "Each worker takes one",
+    "label": "TAKE",
+    "caption": "Workers take from the head of the queue, oldest first, one job each.",
+    "data": {
+      "producer": { "next": "j3", "state": "ready" },
+      "queue": [],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "steady-refill",
+    "title": "More jobs arrive",
+    "label": "PUT",
+    "caption": "The producer keeps putting while the workers run. Two of four slots are used.",
+    "data": {
+      "producer": { "next": "j5", "state": "ready" },
+      "queue": ["j3", "j4"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "steady-done",
+    "title": "A worker finishes and takes the next",
+    "label": "DONE",
+    "caption": "Worker 1 completes j1 and takes j3. Under steady load the queue stays short and never reaches its bound.",
+    "data": {
+      "producer": { "next": "j5", "state": "ready" },
+      "queue": ["j4"],
+      "bound": 4,
+      "workers": ["j3", "j2"],
+      "done": ["j1"]
+    }
+  },
+  {
+    "key": "burst-busy",
+    "title": "Both workers are busy",
+    "label": "BUSY",
+    "caption": "j1 and j2 are running and j3 waits. The producer is about to send a burst.",
+    "data": {
+      "producer": { "next": "j4", "state": "ready" },
+      "queue": ["j3"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "burst-fill",
+    "title": "The burst fills the queue",
+    "label": "FILL",
+    "caption": "j4 to j6 arrive faster than the workers finish. The queue holds four jobs: its bound.",
+    "data": {
+      "producer": { "next": "j7", "state": "ready" },
+      "queue": ["j3", "j4", "j5", "j6"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "burst-wait",
+    "title": "put() blocks the producer",
+    "label": "BACKPRESSURE",
+    "caption": "The queue is full, so put(j7) waits instead of growing the queue. The producer slows to the workers' pace.",
+    "data": {
+      "producer": { "next": "j7", "state": "blocked" },
+      "queue": ["j3", "j4", "j5", "j6"],
+      "bound": 4,
+      "workers": ["j1", "j2"],
+      "done": []
+    }
+  },
+  {
+    "key": "burst-drain",
+    "title": "A worker frees a slot",
+    "label": "TAKE",
+    "caption": "Worker 1 completes j1 and takes j3. That frees a slot and wakes the blocked put.",
+    "data": {
+      "producer": { "next": "j7", "state": "woken" },
+      "queue": ["j4", "j5", "j6"],
+      "bound": 4,
+      "workers": ["j3", "j2"],
+      "done": ["j1"]
+    }
+  },
+  {
+    "key": "burst-resume",
+    "title": "The waiting put goes through",
+    "label": "RESUME",
+    "caption": "j7 takes the free slot and the queue is full again, so put(j8) blocks until the next completion.",
+    "data": {
+      "producer": { "next": "j8", "state": "blocked" },
+      "queue": ["j4", "j5", "j6", "j7"],
+      "bound": 4,
+      "workers": ["j3", "j2"],
+      "done": ["j1"]
+    }
+  }
+]

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

@@ -0,0 +1,18 @@
+[
+  {
+    "key": "steady",
+    "label": "Steady load",
+    "frames": ["steady-put", "steady-take", "steady-refill", "steady-done"]
+  },
+  {
+    "key": "burst",
+    "label": "Burst hits the bound",
+    "frames": [
+      "burst-busy",
+      "burst-fill",
+      "burst-wait",
+      "burst-drain",
+      "burst-resume"
+    ]
+  }
+]

package/instructions/animations/race-two-lanes/README.md

@@ -0,0 +1,22 @@
+# Lost update between two writers
+
+Two actors read, modify and write one shared row in interleaved steps on two lanes, losing an update without a lock and serializing behind it with one.
+
+## Use when
+
+A change touches a read-modify-write on shared state, such as a balance, a counter or a JSON blob saved back whole, or adds or removes a lock, a transaction or a version check around it, and the reviewer has to judge whether two concurrent callers can clobber each other.
+
+## Shows
+
+Each actor's steps appear on its own lane in time columns, so the interleaving reads left to right, and its card shows the value it holds locally. The row below changes as writes land. Without a lock, both read 100 and B's write of 120 erases A's 150. With a lock, B's blocked bar grows until A writes and releases, then B reads 150 and writes 170.
+
+## Technique
+
+Data-driven: each frame's `data` holds the full state (the column count, every step so far with its lane, column, span and tone, each actor's local value, and the row), and one `whiteboard.on("*", ...)` handler redraws it all. It compares with `previous.data` to animate only what changed: a new step slides in, a wait that lasted another step grows from its old width, a step whose tone changed fades up, and a changed cell slides in, all through `whiteboard.animate`, so jumps and reduced motion draw the end state.
+
+## Adapt
+
+- Rename the actors in the two cards and rewrite the step `text` for your operation: an increment, a cache refill, a config file saved back.
+- Change the row: its columns are the keys of `record.row`, so add a `version` column to show optimistic concurrency, and add a scenario where B's write is rejected and retried.
+- Keep `columns` the same across a scenario's frames so the lanes do not reflow as steps arrive.
+- A new frame or scenario is only new entries in frames.json and scenarios.json; animation.html stays as it is.

package/instructions/animations/race-two-lanes/animation.html

@@ -0,0 +1,97 @@
+<div class="race">
+  <div class="wb-card" data-actor="A">
+    <span class="wb-card-title">A · deposit +50</span>
+    <span class="wb-card-note"></span>
+  </div>
+  <div class="wb-lane steps" data-actor="A"></div>
+  <div class="wb-card" data-actor="B">
+    <span class="wb-card-title">B · deposit +20</span>
+    <span class="wb-card-note"></span>
+  </div>
+  <div class="wb-lane steps" data-actor="B"></div>
+  <div class="record">
+    <span class="wb-caps">accounts</span>
+    <table class="wb-table"><thead><tr></tr></thead><tbody><tr></tr></tbody></table>
+  </div>
+</div>
+
+<style>
+  .race {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    align-items: center;
+    gap: var(--wb-space-16);
+    padding: var(--wb-space-20) var(--wb-space-24);
+  }
+  .steps {
+    display: grid;
+    grid-template-columns: repeat(var(--columns), minmax(0, 1fr));
+    align-items: center;
+    gap: var(--wb-space-4);
+  }
+  .steps .wb-chip { position: relative; justify-self: center; max-width: 100%; text-align: center; }
+  .steps .wait { justify-self: stretch; transform-origin: left; }
+  .record {
+    grid-column: 1 / -1;
+    justify-self: center;
+    width: min(100%, calc(var(--wb-space-160) * 2));
+    margin-top: var(--wb-space-12);
+  }
+</style>
+
+<script>
+  const lanes = document.querySelectorAll(".steps");
+  const head = document.querySelector(".record thead tr");
+  const row = document.querySelector(".record tbody tr");
+
+  const cell = (tag, text) => {
+    const element = document.createElement(tag);
+    element.textContent = text;
+    return element;
+  };
+
+  const slideIn = (element) =>
+    whiteboard.animate(element, [{ opacity: 0, transform: "translateY(-4px)" }, { opacity: 1, transform: "none" }], 300);
+
+  whiteboard.on("*", ({ frame, previous }) => {
+    const { columns, steps, local, record } = frame.data;
+    const before = previous?.data ?? { steps: [], record: { row: {} } };
+    const animations = [];
+
+    for (const lane of lanes) {
+      lane.style.setProperty("--columns", columns);
+      lane.replaceChildren();
+    }
+
+    steps.forEach((step, index) => {
+      const chip = cell("span", step.text);
+      chip.className = step.wait ? "wb-chip wait" : "wb-chip";
+      chip.style.gridColumn = `${step.at} / span ${step.span ?? 1}`;
+      if (step.tone) chip.dataset.tone = step.tone;
+      document.querySelector(`.steps[data-actor="${step.actor}"]`).append(chip);
+
+      const old = before.steps[index];
+      if (!old) animations.push(slideIn(chip));
+      // A wait that lasts into this frame grows from where it ended.
+      else if ((old.span ?? 1) < (step.span ?? 1))
+        animations.push(whiteboard.animate(chip, [{ transform: `scaleX(${(old.span ?? 1) / step.span})` }, { transform: "none" }], 400));
+      else if (old.tone !== step.tone) animations.push(whiteboard.animate(chip, [{ opacity: 0.3 }, { opacity: 1 }], 400));
+    });
+
+    for (const [actor, value] of Object.entries(local))
+      document.querySelector(`.wb-card[data-actor="${actor}"] .wb-card-note`).textContent = `local ${value}`;
+
+    head.replaceChildren(...Object.keys(record.row).map((key) => cell("th", key)));
+    row.replaceChildren(
+      ...Object.entries(record.row).map(([key, value]) => {
+        const td = cell("td", value);
+        if (before.record.row[key] !== undefined && before.record.row[key] !== value) animations.push(slideIn(td));
+        return td;
+      }),
+    );
+    if (record.tone) row.dataset.tone = record.tone;
+    else delete row.dataset.tone;
+
+    return animations;
+  });
+</script>

package/instructions/animations/race-two-lanes/block.json

@@ -0,0 +1 @@
+{ "title": "Lost update between two writers" }

package/instructions/animations/race-two-lanes/frames.json

@@ -0,0 +1,234 @@
+[
+  {
+    "key": "n-start",
+    "title": "Two deposits, one row",
+    "label": "START",
+    "caption": "Account 7 holds 100. A deposits 50 and B deposits 20, each by reading the balance, adding, and writing it back, with no lock.",
+    "data": {
+      "columns": 6,
+      "steps": [],
+      "local": { "A": "—", "B": "—" },
+      "record": { "row": { "id": "acct 7", "balance": "100" } }
+    }
+  },
+  {
+    "key": "n-read",
+    "title": "Both read 100",
+    "label": "BOTH READ",
+    "caption": "A reads 100, then B reads 100 before A has written. Each now holds its own copy.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" }
+      ],
+      "local": { "A": "100", "B": "100" },
+      "record": { "row": { "id": "acct 7", "balance": "100" } }
+    }
+  },
+  {
+    "key": "n-modify",
+    "title": "Both add locally",
+    "label": "BOTH ADD",
+    "caption": "A computes 150 and B computes 120, each from the 100 it read. The row has not changed yet.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "B", "at": 4, "text": "+20 → 120" }
+      ],
+      "local": { "A": "150", "B": "120" },
+      "record": { "row": { "id": "acct 7", "balance": "100" } }
+    }
+  },
+  {
+    "key": "n-write-a",
+    "title": "A writes 150",
+    "label": "A WRITES",
+    "caption": "The row now holds 150, A's deposit included.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "B", "at": 4, "text": "+20 → 120" },
+        { "actor": "A", "at": 5, "text": "write 150", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "120" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "150" },
+        "tone": "modified"
+      }
+    }
+  },
+  {
+    "key": "n-write-b",
+    "title": "B overwrites with 120",
+    "label": "LOST UPDATE",
+    "caption": "B writes the 120 it computed from a stale read and clobbers A's write. The row should hold 170; A's 50 is lost.",
+    "data": {
+      "columns": 6,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        { "actor": "B", "at": 2, "text": "read 100" },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "B", "at": 4, "text": "+20 → 120" },
+        { "actor": "A", "at": 5, "text": "write 150", "tone": "removed" },
+        { "actor": "B", "at": 6, "text": "write 120", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "120" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "120" },
+        "tone": "removed"
+      }
+    }
+  },
+  {
+    "key": "l-start",
+    "title": "Two deposits, one locked row",
+    "label": "START",
+    "caption": "Account 7 holds 100. This time each actor locks the row before it reads, and releases the lock when it writes.",
+    "data": {
+      "columns": 7,
+      "steps": [],
+      "local": { "A": "—", "B": "—" },
+      "record": { "row": { "id": "acct 7", "balance": "100", "lock": "free" } }
+    }
+  },
+  {
+    "key": "l-lock",
+    "title": "A locks and reads 100",
+    "label": "A LOCKS",
+    "caption": "A takes the row lock and reads 100. B asks for the same lock and blocks.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 1,
+          "wait": true,
+          "tone": "muted"
+        }
+      ],
+      "local": { "A": "100", "B": "—" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "100", "lock": "held by A" }
+      }
+    }
+  },
+  {
+    "key": "l-modify",
+    "title": "A adds while B waits",
+    "label": "A ADDS",
+    "caption": "A computes 150. B is still blocked, so it cannot read the old balance.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 2,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" }
+      ],
+      "local": { "A": "150", "B": "—" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "100", "lock": "held by A" }
+      }
+    }
+  },
+  {
+    "key": "l-write-a",
+    "title": "A writes and unlocks",
+    "label": "A WRITES",
+    "caption": "A writes 150 and releases the lock, which wakes B.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 3,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "A", "at": 4, "text": "write 150", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "—" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "150", "lock": "free" },
+        "tone": "modified"
+      }
+    }
+  },
+  {
+    "key": "l-read-b",
+    "title": "B reads A's write",
+    "label": "B READS",
+    "caption": "B takes the lock and reads 150: it sees A's deposit because it had to wait for it.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 3,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "A", "at": 4, "text": "write 150" },
+        { "actor": "B", "at": 5, "text": "read 150" }
+      ],
+      "local": { "A": "150", "B": "150" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "150", "lock": "held by B" }
+      }
+    }
+  },
+  {
+    "key": "l-write-b",
+    "title": "B writes 170",
+    "label": "B WRITES",
+    "caption": "B writes 170 and releases the lock. Both deposits are in the row: the lock turned the race into a queue.",
+    "data": {
+      "columns": 7,
+      "steps": [
+        { "actor": "A", "at": 1, "text": "read 100" },
+        {
+          "actor": "B",
+          "at": 2,
+          "text": "blocked",
+          "span": 3,
+          "wait": true,
+          "tone": "muted"
+        },
+        { "actor": "A", "at": 3, "text": "+50 → 150" },
+        { "actor": "A", "at": 4, "text": "write 150" },
+        { "actor": "B", "at": 5, "text": "read 150" },
+        { "actor": "B", "at": 6, "text": "+20 → 170" },
+        { "actor": "B", "at": 7, "text": "write 170", "tone": "modified" }
+      ],
+      "local": { "A": "150", "B": "170" },
+      "record": {
+        "row": { "id": "acct 7", "balance": "170", "lock": "free" },
+        "tone": "modified"
+      }
+    }
+  }
+]

package/instructions/animations/race-two-lanes/scenarios.json

@@ -0,0 +1,19 @@
+[
+  {
+    "key": "no-lock",
+    "label": "Without a lock",
+    "frames": ["n-start", "n-read", "n-modify", "n-write-a", "n-write-b"]
+  },
+  {
+    "key": "lock",
+    "label": "With a row lock",
+    "frames": [
+      "l-start",
+      "l-lock",
+      "l-modify",
+      "l-write-a",
+      "l-read-b",
+      "l-write-b"
+    ]
+  }
+]

package/instructions/animations/request-across-layers/README.md

@@ -0,0 +1,24 @@
+# Request across layers
+
+One request crosses client, API, service and database and back, and each card shows the payload in the shape that layer holds, with a branch where validation stops it at the API.
+
+## Use when
+
+A change touches how a request is parsed, validated, mapped or persisted, and the reviewer needs to see which layer owns which shape and where a bad input is turned away.
+
+## Shows
+
+- Valid order: a JSON body with a string `qty` becomes a typed DTO, a domain Order without an id, a row with one, an Order again, and a 201 body.
+- Validation fails: the API answers 422 naming the field; the service and the database are marked not called.
+- The card doing the work is ringed in each frame; its note keeps the shape it produced, so earlier shapes stay readable.
+
+## Technique
+
+A scene: `whiteboard.scene({ columns: 4 })` with four `actor`s, solid `link`s for requests and dashed ones for replies, one `send` per hop per frame, and `on(frame, card, { text, tone })` for the payload shape. Each card wears its layer's `form`: a `window` for the client, `bars` for the API and the service, a `cylinder` in `teal` for the database. A `group` boxes the API and the service as the one server, `change: "modified"` marks the API as what the review touched, and a `legend` decodes the three marks. `highlight` rings the active card; `code` on a card and each frame's `code` link the ranges.
+
+## Adapt
+
+- Rename the actors and code ranges to your layers; keep four or fewer in a row. A third-party API in the chain gets `outline: "dashed"`.
+- Write each note as the payload's real type at that layer, short enough for two lines.
+- Keep one `send` per frame: sends on different edges in one frame start together.
+- Branch with new frame keys (a different body) and a scenario, not by drawing buttons.

package/instructions/animations/request-across-layers/animation.html

@@ -0,0 +1,85 @@
+<script>
+  const s = whiteboard.scene({ columns: 4 });
+
+  // Ring the card that reshapes the payload in each frame.
+  // Each card wears the shape of its layer: a window for the client, bars
+  // for the services this codebase runs, a cylinder for the database.
+  const client = s.actor({
+    id: "client",
+    at: [1, 1],
+    title: "Client",
+    form: "window",
+    highlight: ["request", "respond", "bad-request"],
+  });
+  const api = s.actor({
+    id: "api",
+    at: [2, 1],
+    title: "API",
+    form: "bars",
+    change: "modified",
+    code: "validate",
+    highlight: ["validate", "rejected"],
+  });
+  const service = s.actor({
+    id: "service",
+    at: [3, 1],
+    title: "OrderService",
+    form: "bars",
+    code: "service",
+    highlight: ["persist", "map"],
+  });
+  const db = s.actor({
+    id: "db",
+    at: [4, 1],
+    title: "Postgres",
+    form: "cylinder",
+    color: "teal",
+    code: "repository",
+    highlight: ["stored"],
+  });
+
+  // The API and the service are the one codebase; the review changed the API.
+  s.group({ id: "server", at: [2, 1, 1, 2], title: "Order server" });
+  s.legend([
+    { form: "bars", label: "This codebase" },
+    { form: "cylinder", color: "teal", label: "Database" },
+    { change: "modified", label: "Changed in this review" },
+  ]);
+
+  // Requests travel solid edges; replies ride dashed ones beside them.
+  s.link(client, api);
+  s.link(api, service);
+  s.link(service, db);
+  s.link(db, service, { dashed: true });
+  s.link(service, api, { dashed: true });
+  s.link(api, client, { dashed: true });
+
+  // Success: each layer holds the payload in its own shape.
+  s.on("request", client, { text: '{ sku, qty: "2" }' });
+  s.send(client, api, "POST /orders", "request");
+
+  s.on("validate", api, { text: "CreateOrderDto { sku, qty: 2 }" });
+  s.send(api, service, "dto", "validate");
+
+  s.on("persist", service, { text: "Order { id: null }" });
+  s.send(service, db, "INSERT", "persist");
+
+  s.on("stored", db, { text: "orders row id=812" });
+  s.send(db, service, "row 812", "stored");
+
+  s.on("map", service, { text: "Order { id: 812 }" });
+  s.send(service, api, "Order", "map");
+
+  s.on("respond", client, { text: '201 { id: "ord_812" }', tone: "added" });
+  s.send(api, client, "201", "respond");
+
+  // Validation failure: the API answers and the request stops there.
+  s.on("bad-request", client, { text: '{ sku, qty: "-1" }' });
+  s.send(client, api, "POST /orders", "bad-request");
+
+  s.on("rejected", api, { text: "qty: must be ≥ 1", tone: "removed" });
+  s.on("rejected", client, { text: "422 { field: qty }", tone: "removed" });
+  s.on("rejected", service, { text: "not called", tone: "muted" });
+  s.on("rejected", db, { text: "not called", tone: "muted" });
+  s.send(api, client, "422", "rejected", { tone: "removed" });
+</script>

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

@@ -0,0 +1,17 @@
+{
+  "title": "An order request across the layers",
+  "code": {
+    "validate": {
+      "source": "head/src/api/orders/validate.ts#L12-L40",
+      "label": "validateCreateOrder"
+    },
+    "service": {
+      "source": "head/src/orders/service.ts#L20-L58",
+      "label": "OrderService.create"
+    },
+    "repository": {
+      "source": "head/src/orders/repository.ts#L8-L31",
+      "label": "insertOrder"
+    }
+  }
+}