Flow & animation

A diagram's animation is a flow — an ordered list of steps the engine compiles into a timeline and plays when the diagram scrolls into view. When no flow is authored, Beck derives one from the edges. For a task-oriented walkthrough, see Animate the flow.

Animation is skipped entirely — Beck emits the static frame — when meta.animate is false or the reader prefers reduced motion. See reduced motion.

The flow block

flow:
  repeat: -1
  repeatDelay: 1.5
  steps:
    - packet: { from: client, to: api, label: GET /item }
    - working: { node: db }
    - packet: { from: api, to: db, color: info }
    - idle: { node: db }
    - packet: { from: db, to: api, color: success }
    - wait: 1

Derived flow

With no flow block, Beck derives one for the three types that have a sequence of events to play — a bare document already animates. What it derives depends on the diagram type:

• architecture and state — a topological walk from roots to leaves: a phase label the first time each node (or state) sends, a packet along every edge (or transition) in order, then a wait and a reset, looping forever.
• sequence — the authored message order is the story: one packet per message, in order, with each - section: band emitted as a seekable phase. Packets ride their message's colour (replies with a decelerating ease), and the scenery starts dimmed — each row, bar, and band lights up as the story reaches it, then everything fades back down before the loop.
• class — nothing. A class diagram is structural reference material, not a narrative, so it has no derived flow: with no flow block it renders a still frame and never loads the animation runtime. Script a flow: yourself if you want a guided tour.

A note: on a connector (an architecture edge, a sequence message, or a state transition) is folded into the derived flow as a narrate caption, emitted just before that hop's packet. Notes are ignored once you author an explicit flow: — narrate the story with narrate steps there instead.

Steps

Each step is a mapping with a single key naming its type. from/to/node values must reference a declared node id (or, for edge endpoints, a group id).

burst clamps count to 1–24 (default 3) and defaults stagger to 0.12 seconds. status, working, stream, and activate persist until a later step or reset clears them; everything else is a one-shot beat.

- status: { node: scan, text: FAILED, color: danger }
- fail: { node: scan, text: vulnerable }
- parallel:
    - burst: { from: alert, to: [oncall, slack, email], count: 4 }
    - pulse: { node: alert }
- phase: notified
- wait: 1
- reset:

Packet knobs

packet and burst share these. Each unset knob falls back to the traversed edge kind's default (see per-edge-kind motion), then to an engine constant.

A travelling packet draws a colour trail in lockstep with its easing and pulses the target node on arrival.

Packet shapes

Each shape travels below so you can read it in motion. An explicit size always overrides a shape's baseline radius.

Eases

An ease only reveals itself in motion, so each one runs live — same edge, same speed, different curve.

Per-edge-kind motion

When a packet's knobs are unset, it inherits the motion of the edge kind it travels — so data, control, async, and dependency packets read differently with zero authoring. Explicit knobs always win. Each card below sends a default packet along an edge of that kind, so the difference in size, speed, glow, and easing is something you watch rather than read off a table.

Narration

A narrate step (or a connector note: folded into a derived flow) writes a line to a caption bar rendered under the diagram body and holds it long enough to read. Captions cross-fade as the flow advances and clear on each loop. The bar only appears when the flow actually carries caption text and narration is enabled; because it is part of the animation, a diagram rendered as a static frame (see reduced motion) shows no caption bar.

The narrate step

With no hold, a caption's on-screen time is derived from its length so a longer line lingers longer: max(min, pad + (words / wpm) × 60) seconds, using the meta.narrate knobs.

meta.narrate

Tunes narration for the whole diagram. A bare boolean toggles the caption bar; a mapping tunes the reading-time pace. Absent means enabled with the defaults below (captions still only appear once a narrate step or a connector note: supplies text).

meta:
  narrate: { wpm: 200, min: 2 }   # or `narrate: false` to turn captions off
flow:
  steps:
    - narrate: The request enters the gateway.
    - packet: { from: client, to: gw }
    - narrate: { text: Auth rejected the token., hold: 3, color: danger }

Reduced motion

If meta.animate is false, or the reader's system requests reduced motion, Beck emits the static frame instead. The persistent CSS-driven effects (working, stream, status and icon tints) consume theme variables directly, so they survive a theme change and keep running even while the timeline is paused.