The bar, the panel and sharing

Everything a reader does with a scenario happens on a bar along the bottom of the diagram, like the controls of a video: which scenario to watch, what its step is saying, and the buttons and slider that move it. A panel over the left of the picture holds the outline and the views.

Everything in one picture. Letters on the edges match the interfaces table underneath.

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

The bar

The bar is as wide as the picture and attached to its bottom edge. It is there whenever the view has a scenario, and with nothing chosen it only offers them.

Part	What it does
Scenario menu	Names the scenario in play and opens a list of the others upward over the picture, each with its length, its phases and the first lines of its summary. Overview shows the diagram on its own. The arrow keys move through it, `Enter` chooses and `Esc` puts it away.
The words	The title of the step in progress, its phase, who talks to whom, and the note you wrote for it, described below.
Play, Pause, Resume, Replay	Runs the scenario. The button’s label says what it will do next.
Previous step, Next step	Moves one step at a time. If a step is half played, Next finishes it first.
The slider	A segment for each step, grouped by phase. Click or drag to any moment, described below.
Steps	Opens the list of every step, described below.
Speed	0.5×, 1× or 2×.
CC	Shows or hides the words.
Flow, Sequence, Story	Switches how the scenario is drawn. See story and sequence.

The bar also says where you are: step 3/9 · 0:04. In a narrow widget it wraps into rows, with the slider on a row of its own. It keeps its height from one step to the next, so nothing below it jumps while a scenario plays.

The slider

The slider has a segment for every step, and every segment is the same width, however long its packet takes to fly: a quick self-step is as easy to hit as a long journey. Steps that start together in a par block share one segment. The segments are grouped by phase, with a wider gap between groups, like the chapters of a video, and a scenario written as plain steps is one group.

Pointing at a place says which step is there: its phase, its number and its title.
Clicking or dragging goes to that moment. Playback pauses while you scrub, so you can look.
From the keyboard, ← and → step back and on, Home and End go to the ends. A screen reader hears “Step 3 of 9” and the title.

The steps

Steps opens the whole scenario as a list above the bar, with the story in a few words at the top and every step grouped by phase. It scrolls by itself to keep the step in progress in view, and never scrolls the page to do it. The step in progress is highlighted, finished steps are marked, and notes appear under their step. A multi-hop step names the nodes it passes through (“via CDN, API gateway”). Esc, a press anywhere else, or the button again puts it away.

Phases fold. Click the header of a phase to fold its steps away and again to show them; the two buttons above the steps fold every phase or show them all. A folded phase still says how many steps it holds, and while the scenario plays through it, how far it has got and what is happening: now: charge the card, 2/3. Folding changes what is listed, never what plays. The sequence and the story fold the same phases, so what you put away stays away whichever way the scenario is drawn. Another scenario starts with every phase shown.

Click a step to play it. The path already travelled stays lit, so a reader can jump to the middle of a story and still see how it got there. The list is also keyboard-friendly: Tab to a step and press Enter or Space.

The words

Beside the controls, the bar writes out what is happening. Before a scenario starts it says how long it is and gives its summary. While it plays it gives the step: a chip with the phase, the title, who talks to whom, and under them the note you wrote for it, up to two lines. A longer note ends with more, which opens the list of steps where it is shown whole.

The words are on by default, and CC turns them off. A page can start without them with subtitles={false}. They are the same over the picture, the sequence and the story.

The panel

The panel sits over the left of the picture, inside the viewport. While it is open the diagram is fitted to the room it leaves, so nothing starts underneath it.

Tab	What is in it
Outline	The diagram as a tree: its groups, the nodes in them, and the connections of each node. See the outline.
Views	A card for each view, with how many nodes and scenarios it has. Appears when the diagram has more than one.

The arrow at the top folds the panel away to a single button in the corner, so the picture can have the whole viewport. The viewer keeps its height when the panel folds, so the page does not jump.

The panel starts open when there is another view to choose, and folded when there is not. A page can decide with sidebar={true} or sidebar={false}, and the diagram file with defaults.sidebar. When the widget is narrower than about 640 px it starts folded, and an open panel becomes a sheet over the lower part of the picture rather than a column beside it.

The outline

The Outline tab is the diagram as a hierarchy, in the order you wrote it:

Groups hold their nodes and the groups nested in them, with a count. Click a group, or press ←, to fold it away.
Nodes list their connections underneath, → for what the node sends, ← for what it receives and ↔ for both ways, with the label of the edge. A node that holds another diagram has icons to show it in place or open it; once it is shown in place, the nodes inside it appear under it as rows of their own.
Clicking a node selects it: its details open and the picture glides to it, keeping the zoom you have. Clicking a connection goes to the node at its other end.
Pointing at a node or a connection lights it up in the picture, and pointing at a node in the picture lights up its row.

The two buttons at the top fold everything away and unfold it again. Everything starts unfolded. The tree is a real tree for the keyboard: ↑ and ↓ move, → and ← unfold and fold, Enter selects.

Follow

On a large diagram the whole picture is small, so the camera can follow the action. A Follow button appears while a scenario is selected. Following starts on automatically when the diagram is wider than 1500 px or taller than 950 px, and stops as soon as the reader pans or zooms. Press it again to bring it back.

Links to a moment

The address bar follows the scenario and step, so readers can share exactly what they are looking at:

https://example.com/examples/checkout/#checkout=place-order.4

The format is #<diagram>=<scenario>[.<step>], where the step is the number shown in the timeline. A page with several diagrams joins them with &:

#checkout=place-order.4&payments=pay.2

Opening such a link selects the scenario, switches to its view, and shows the step already played, paused, so the reader decides when to continue.

A link can also open nested diagrams: #shop~=orders/stock opens the orders node, then the stock node inside it. The scenario of the diagram at that level is keyed by the diagram names that lead to it, joined with /: #shop/orders/stock=reserve.3.

Autoplay and reduced motion

A scenario a reader clicks starts playing. One that a page selects with scenario="..." waits, unless the page also passes autoplay:

<Diagram name="checkout" scenario="place-order" autoplay />

Readers who ask their system for reduced motion are never autoplayed, and clicking a scenario selects it without playing. They can still press Play, step through, or scrub.

How it works

A scenario compiles to a timeline: for every step, when it starts and ends, and for every hop, when the packet is on which edge. frameAt(t) is a pure function that turns a time into a picture: which packets are where, which nodes are lit. The player is only a clock that advances t. That is why scrubbing, stepping, deep links and the tests are all exact. See how it works inside.