Skip to content

Add the diagram block to Whiteboard - #1531

Merged
milanb17 merged 3 commits into
mainfrom
mb/whiteboard-block-components-12ca8f
Nov 16, 2026
Merged

milanb17 merged 3 commits into
mainfrom
mb/whiteboard-block-components-12ca8f

Conversation

@milanb17

@milanb17 milanb17 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Three 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.
  3. Render a diagram in a window that is never shown, and render a draft folder — rendering out of sight, in Desktop.

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.
  • A markup kit, which is how most diagrams are now written, with no script:
    • <wb-node>, <wb-group> and <wb-edge> are the parts, owners and wires. Groups take a hue each in turn, or one named with color.
    • <wb-graph direction> places everything inside it and routes the edges, with a vendored copy of Pele's layout (app/vendor/pele-layout). The direction is a wish: a graph too wide for the board turns itself, and one too tall folds into columns.
    • <wb-panel> with <wb-row label value="key"> is a table of state the graph places beside the nodes or under them, filled from each frame's data. side asks for one or the other.
    • The stage draws a legend under a graph when its steps send more than one kind of token (call, reply, failed, lost). <wb-graph token="…"> renames the plain one.
    • Inside a graph the graph owns the layout; outside one, the page's CSS does.
  • How a graph plays:
    • Every token travels to the node it is sent to. A labelled one backs off only as far as it must to clear nodes and other edges, and no further than its edge's label spot.
    • With no scenarios nothing is dimmed; with scenarios, the parts a scenario never touches are.
    • A group's name slides along the top to a spot no edge crosses, and otherwise stays put with the edges passing behind it.
  • 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;
    • chart text colliding with other text, sitting on a line or dot, or cut at the chart's edge, 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. Each code entry is a line range, as in the other blocks, with an optional label.
    • An accepted publish returns quotes of each range's first and last lines, so the agent can check they are the lines it meant.
    • When the board moves to new commits, links whose lines are gone 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, and the play button's tooltip says so. A diagram's step holds for 1.8 seconds (an animation's keeps 3).
  • 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 render also returns notes: what the stage decided for the author, which needs no fix. A graph it turned (with the width keeping the direction would take), a reply that replaced its call on an edge, a panel that did not fit where it was asked.
    • A new diagram instructions topic, a wb.d.ts held to the runtime with satisfies, and six reference diagrams: an architecture with groups, scenarios and a panel (graph-architecture), a state machine (graph-order-states), a sequence, a played request, a latency chart and a rolled die.
  • The setting is now "Diagrams and Animations", and its description and the refusal messages say it covers both. The stored key is still animationsEnabled, so nobody's setting resets.
  • Rendering out of sight (the third commit). session_render sends Desktop the block alone on a copy of its board.
    • Desktop mounts it on a small page (render.html, built beside the canvas) in a window that is never shown, grows the window to the block's height (up to 8,000px), and captures it there. The window is sandboxed, cannot take focus, and closes after 15 seconds idle.
    • The user's window is not scrolled or switched, the board need not be open, and a tall diagram is captured whole.
    • This adds one method to the fork's native host service, renderHiddenPage (hiddenPageRenderer.ts).
    • session_render also takes fromFiles: a draft folder is drawn the same way before it is on the board, through a new POST /:id/render, and nothing is saved. The instructions render a draft first and publish once. Only a render by targetId returns claims.
  • Retirement. With the setting 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 it 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 with hand-placed drawings, which still took several renders each to fit. Later rounds moved the layout into the stage: the markup kit, the graph, the panel, the legend and the render notes. By round 16 a graph with a panel took one render. The rounds also produced the hand-placed routing, the findings with numbers, lost moves and code: false.

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, label? }: a line range like every other block's, without the evidence text 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);
    • 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;
    • the same file covers the kit: a panel's place beside and under a graph, the legend, and the notes for a turned graph and a replaced token;
    • references.browser.test.tsx: every reference runs clean through every scenario, with no findings;
    • a diagram case each in the render, drafts, authoring-gate, 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 and textStyles.truncate.

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.
  • The markup kit was checked in dark only. Light theme, a panel's side, and the replaced-token note outside its test are unchecked.
  • Known rough spots in a graph: a labelled token resting just before a node at the top of a group overlaps the group's name, and an edge label inside a coloured group sits on the board's surface colour instead of the group's fill.
  • The packaged app and an older Desktop were not tried with rendering out of sight. A Desktop without the new method, attached to a newer server, is not handled.
  • Shared boards: the hosted viewer pins published whiteboard-document and canvas versions that predate this block, so a shared board will not show a diagram until those are published and bumped there.

@milanb17
milanb17 force-pushed the mb/whiteboard-block-components-12ca8f branch 30 times, most recently from d84585e to 40d0a5a Compare November 11, 2026 20:55
@milanb17
milanb17 force-pushed the mb/whiteboard-block-components-12ca8f branch 12 times, most recently from d9251e0 to 3601975 Compare November 12, 2026 22:41
A standalone Vite playground for a new whiteboard block: a sandboxed stage
runs an agent's script against a wb SDK with nodes, nested groups, wires,
ELK layout with an overlap check, steps and scenarios with request moves,
code claims verified against the repository, and Observable Plot charts.
PLAN.md lays out moving it into Whiteboard.

Agent-Session: db53cef1-7052-40f4-80b7-97044c16c38b
@milanb17
milanb17 force-pushed the mb/whiteboard-block-components-12ca8f branch 8 times, most recently from 515d171 to c72d8a1 Compare November 16, 2026 02:13
A new `diagram` block draws a system in the existing sandboxed stage. Most
diagrams are markup: `<wb-graph>` places `<wb-node>`, `<wb-group>` and
`<wb-edge>` with a vendored copy of Pele's layout, fits the graph to the
board (turning or folding one that is too wide), and can place a
`<wb-panel>` of values beside it. The stage draws a legend when steps send
more than one kind of token. A script can still draw with the `wb` SDK:
C4 nodes, nested groups and wires laid out by ELK, played timelines, and
Observable Plot charts. ELK, d3 and Plot reach the stage as text over its
port on first use, so the stage keeps its no-network policy.

Steps send tokens along the wires and fill markup from their data;
scenarios give the reader paths to pick between, and parts a scenario
never touches are dimmed. A diagram's steps hold for 1.8 seconds, and the
player's keys are named in the play button's tooltip.

Every node and wire can link to code with evidence: text that must sit in
the linked lines. A publish whose evidence is elsewhere is refused with the
line it moved to, and a board that moves to new commits marks such links
stale. Readers toggle Verify to see each claim's state; stale links show
as changed without hiding the diagram.

Agents author diagrams as files (diagram.html, diagram.js, frames.json,
scenarios.json, block.json) with the existing checkout, publish and render
tools. Renders and session_get report script errors, findings (overlaps,
moves without a wire, unknown code names) and claim counts; a render also
returns notes, what the stage decided for the author, such as a graph it
turned. Instructions, a wb.d.ts held to the runtime, and six reference
diagrams ship with them.

The setting is now Diagrams and Animations. With it on, agents can no
longer insert animation, clip, flow_diagram, sequence or call_stack_diff
blocks; existing ones still render and still take updates. The authoring
guide points design and implementation diagrams at `diagram`.

Agent-Session: db53cef1-7052-40f4-80b7-97044c16c38b
@milanb17
milanb17 force-pushed the mb/whiteboard-block-components-12ca8f branch from c72d8a1 to fdd3de2 Compare November 16, 2026 02:19
…folder

session_render sends Desktop the block alone on its board. Desktop mounts
it on a page in a hidden window as tall as the block needs, captures it
there, and reports what the stage found on each stop. The user's window is
not scrolled or switched, the board need not be open, and a tall diagram is
captured whole.

With that, session_render takes fromFiles: a draft folder is drawn the same
way before it is on the board, and nothing is saved. The diagram
instructions render a draft first and publish once.

Agent-Session: db53cef1-7052-40f4-80b7-97044c16c38b
Agent-Session: cfa09165-90bc-452b-ae64-4d30f1b1b967
@milanb17
milanb17 force-pushed the mb/whiteboard-block-components-12ca8f branch from 3e69a6e to 6ea3595 Compare November 16, 2026 02:34
@milanb17
milanb17 merged commit c3470b7 into main Nov 16, 2026
3 checks passed
@milanb17
milanb17 deleted the mb/whiteboard-block-components-12ca8f branch November 16, 2026 03:07
milanb17 added a commit that referenced this pull request Nov 16, 2026
## What

With the Diagrams and Animations setting on, agents can insert a
`call_stack_diff` again, and the authoring guide names it for the
implementation section.

- `call_stack_diff` is out of `RETIRED_BLOCK_TYPES`, so an insert no
longer gets a 409.
- The setting-on authoring topic keeps the `call_stack_diff` line for
the old vs. new path, in place of "a `diagram` … as two scenarios
(before, after)".
- The Components list includes `call_stack_diff` and `frame` again.

`animation`, `clip`, `flow_diagram` and `sequence` stay retired. Nothing
changes with the setting off.

## Why

#1531 retired `call_stack_diff` on the grounds that a diagram draws what
it did. It does not:

- A call stack marks each frame added, removed or modified from the real
diff. A diagram's before and after scenarios are authored, and nothing
checks them.
- A frame must name a code range. A diagram node's `code` is optional.
- A call stack is a tree with call sites. A diagram has no call depth.

## Testing

`animation-authoring.test.ts`, `authoring-pitfalls.test.ts` and
`animation-drafts.test.ts` pass. Not checked in Desktop.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants