[milanb17]

Two commits:

1. Add a lab for the diagram block — the standalone packages/animation-lab playground and PLAN.md.
2. Add the diagram block to Whiteboard — the product integration.

What it adds

• A diagram block (whiteboard-document/src/blocks/diagram.ts). An agent's markup (html), JavaScript module (script) or both draw in the existing sandboxed stage, the script with a global wb:
  • nodes in the C4 kinds, nested groups and wires, laid out by ELK or placed by hand;
  • steps whose moves send tokens along the wires: failed draws one red, and lost stops it halfway for a message that never arrives;
  • scenarios, played timelines, Observable Plot charts and three.js scenes;
  • diagram.html as the page, laid out as any web page is: <div data-wb-drawing> marks where wb draws and takes the drawing's size, so panels, tables and logs sit around it with flow, flex or grid. Without markup the page is that element alone. The page's styles are scoped to it with @scope, so they never reach what wb draws. data-wb-from, data-wb-until and data-wb-only show an element by frame with no script.
• The stage runtime (app/src/diagram/wb-runtime.ts), ported from the lab onto the stage's MessagePort.
  • ELK, d3, Plot and three.js reach the stage as text when a script first uses them, so the stage keeps its no-network CSP. No new Trusted Types policy is needed.
  • The board pushes the theme, so a forced light or dark theme wins over the OS.
• What the stage does for an author placing by hand:
  • A wire leaves the side facing the other node, and runs straight when one node's side spans the other's.
  • Wires sharing a side spread 12px apart and cross over on lanes of their own.
  • Labels sit by the quieter end, clear of nodes and of group edges and names.
  • Nodes and groups grow about their middle to show their name and tag whole.
  • A group's name moves along its header clear of the wires.
  • A token rests back around a bend when a wire's last stretch is too short for it.
• Findings that say what is wrong and by how much, including:
  • overlaps, a wire through a node, a label on a group's edge;
  • text cut off, with the width it needs, and a hand-placed node grown past its width;
  • a move with no wire, listing the wires that do join its nodes;
  • text colliding inside a chart, and Plot's own warnings;
  • a drawing or page wider than the column, naming what reaches furthest and how far to move it;
  • a script that draws while diagram.html has no data-wb-drawing (an error), and page styles that name body, :root or wb's own elements.
• Code links with evidence. Each code entry names text that must appear inside its linked lines.
  • A publish whose evidence is elsewhere is refused with a 409 naming the line it moved to; an accepted publish returns quotes of each range's first and last lines.
  • When the board moves to new commits, links whose evidence moved are marked changed.
  • Linked nodes and wires open the side peek on click or Enter, and Tour walks the steps alongside their code.
  • code: false marks a node or wire that is not code, such as a repository drawn as a database.
• The player under a diagram (animation/timeline-controls.tsx): a round play button, a track of steps or chapters with their names, and the current caption. Space plays and pauses; the arrow keys step.
• Authoring. Agents use the existing tools:
  • session_checkout and fromFiles work with a folder holding diagram.html, diagram.js or both.
  • session_render (frame: "all" renders every frame of every scenario) and session_get report script errors, findings and claim counts (matches, changed, unlinked).
  • A new diagram instructions topic, a wb.d.ts held to the runtime with satisfies, and ten reference diagrams: layered architecture, request fan-out, fan-out, shared lock, sequence, call path, request with state, played request, latency chart and rolled die.
• Retirement. With Animations on, agents get a 409 when they insert animation, clip, flow_diagram, sequence or call_stack_diff.
  • Existing ones still render and still take updates.
  • The authoring guide points design and implementation diagrams at diagram.
  • With Animations off, nothing changes.

How the authoring experience was tuned

An agent (Fable) drew three new diagrams a round on a test board, using only what the whiteboard serves an author, and logged every point of friction. Each round's fixes went into the stage first, then the references, then the instructions. Round 10 came back satisfied. The rounds produced the hand-placed routing, the findings with numbers, lost moves, code: false, and the fan-out and shared-lock references.

Where it differs from PLAN.md

• Frames and scenarios: the schema keeps the animation block's shape (a frame list plus scenarios naming frame keys) instead of scenarios with nested frames. This reuses the frame player and the tour unchanged.
• Code entries are { source, evidence, label? }, as the plan's D6 suggested.
• No reader-facing Verify toggle. Claim counts go to agents in render results; readers see the code through the side peek and Tour.
• session_render has no verify input. A render returns the claim counts and findings from the canvas's run report instead, so the Desktop render verb and the protocol are unchanged.
• Reader selection (phase 6) is not ported. The runtime keeps wb.selectable for ids and labels only.
• Group hues and chart series keep the lab's validated colours, which don't map to canvas tokens. This is the token gap D6 flagged.

Tests

• New tests:
  • diagram.test.ts (schema rules);
  • code-evidence.test.ts;
  • diagram-block.browser.test.tsx: layout and size, routing and labels, findings, claim counts, stale links, code: false, script and syntax errors, steps, timeline, markup without a script, the drawing placed where data-wb-drawing sits, page styles kept off the drawing, and a missing mount;
  • references.browser.test.tsx: every reference runs clean through every scenario, with no findings;
  • a diagram case each in the render, drafts, authoring-gate, local-data (stale evidence), attached-Desktop and headless-host tests.
• Updated tests: those that set up animations, clips, sequences and flows now insert them as a person, since agents can no longer add them.
• store-upgrade.test.ts now pins its clock: a fixture board put in Trash on 2026-10-13 reached the 30-day purge, which failed it on main too.
• Typecheck, pnpm lint and pnpm format:check are clean; the deslop-ui pass has run. It moved the players' glyphs into ui/icons.tsx and put the player on IconButton, useTooltip, textStyles.truncate and Kbd.

Checked in Desktop

The player in dark and light: play, pause and replay, Space and the arrow keys, Tab through the track and step names, and the captions on hover and focus. That check found step names cut off and running together at mid widths. Names under stops now show only when every one fits whole, as below the narrow breakpoint.

Not done

• Reduced motion and zoom were not checked by hand.