feat(playback): play execution visualization — taken paths, +N badges, arrival and conversion cues #330

Summary

Playback already animates one round token per connection per step along the connection's real path, in the engine's own order (docs/simulation-playback.md, docs/simulation-playback-ordering.md). This issue keeps that token and adds to it, so a step reads as "what moved where": every path that carried a move, its amount as a +N badge beside the token, a pulse inside the Pool when the token arrives, a mark inside the Converter, and a rule per way of running. It is a presentation layer only. The playback docs are living documents; the engine, the RNG and the PB-INV and PBO-INV invariants are kept.

Current state

Measured read-only on main 6de1852 (dev server) and on production v0.21.0 · build 6de1852 (real UI, throwaway Chrome contexts); both agree.

• Token: one round dot (r 3.6, the run colour) per connection per step, carrying the step's summed amount; the amount shows as a bare number 8 px above the dot only when it is above 1, and it can sit on top of the connection's own label. It follows the real Bézier or orthogonal path.
• Order: connections start in up to 6 buckets within the first 30 % of the step; a router's pull-in and push-out share one onset.
• Gate: no taken-path tell; a branch with no move just has no token.
• Pool: the arrival disc plays at settle, after the token is gone, for 120 ms.
• Converter: no conversion cue; inputs and output move together with the generic fired wave.
• Speed: 120 to 2400 ms per step (default 600, not persisted); every speed draws the same choreography, and at 120 ms the cue keyframes (120 to 500 ms) are cut off at settle.
• Budget: at most 60 travelling cues per step; the widest bundled step measured (early MMO, 10 steps) peaks at 35.
• Monte Carlo: nothing on the canvas. Reduced motion: no travel, held static cues. L0: no token, a path pulse.
• Phone: no speed control (docs/mobile.md §MV4), always 600 ms; a fitted template sits at about 0.45 zoom, on the L0 line.
• Priority: tokens always use the run colour (FC-4.2); on a connection outside the Focus set they play at full strength, and the connection itself is not dimmed either (a separate bug, fix(canvas): Focus mode does not dim the connections outside the focus set #329).

The round token stays

The round token that travels a connection today is kept wherever it travels today; the one exception is the very fast tier, where it still appears, at the end of the flashed path. +N is a badge that adds the amount to it; it never replaces it.

The desktop slider is continuous (120 to 2400 ms), so the tiers have exact boundaries: 400 ms and above is the full tier (the token and its +N badge travel together), 200 to 399 ms is fast (the token travels, +N shows on arrival), below 200 ms is very fast (the path flashes, then the token and +N appear at the end). Step always draws the full tier, whatever the slider says. The tier is read once when a step starts; a speed change during a step applies from the next step. The phone's 1000, 600, 300 and 120 ms each fall in exactly one tier.

Decisions

1. Token unit: one summed round token per connection per step, as today. No token per engine transfer.
2. Amount: always shown as +N, from +1, as a badge beside the token; the pair is drawn on top. The connection's own label never moves; it dims only while its real bounding box overlaps the token or its badge. Only the connection's own label is checked; no other connection's label is tested on any frame.
3. Gate: for every gate kind, every outgoing path with a move event this step is highlighted and carries its round token; several can be at once. A branch with no event gets no playback cue.
4. Converter (option A): inputs and output keep the engine's order and their tokens move together; a conversion mark is shown inside the Converter. No consume-then-produce sequence.
5. Per mode: the table above. Monte Carlo draws no per-move choreography.
6. Focus mode wins on connections: the path highlight, round token and badge on a connection outside the focus set are drawn at the same low strength as the connection. Inside the nodes, the fired wave, the evaluated mark, the Pool arrival pulse and the conversion mark keep full strength, as §LGR2.3 intends.
7. Phone (§MV4 reopened narrowly), in the last pull request: a four-step choice under ⋯ → Playback speed: Slow 1000 ms, Normal 600 ms, Fast 300 ms, Very fast 120 ms. No run seed in the bar; the Monte Carlo dialog keeps its base seed. Each step follows the same tier as on the desktop, with fewer moving elements and simpler effects.
8. Cap: at most 24 token-and-badge pairs per step, the dot and its badge counted together. This replaces the 60 travelling-cue budget. Past 24, every path that moved keeps its highlight and every arrival keeps its cue.
9. Reduced motion and forced colours: every pull request implements and tests the reduced-motion and forced-colours forms of the cues it adds, in the same pull request.

Visual priority

• Invalid, selection and keyboard-focus rings stay on top, unchanged.
• The structure line and flow colours stay.
• The arrival pulse and the conversion mark are drawn inside the node only.
• The playback path is drawn on the connection and follows Focus dimming.
• No animation reaches a file, a digest or an engine result.

Contract changes, in the documents they belong to

Pull requests

• Prerequisite (v0.21.1): Focus mode dims the connections outside the focus set (fix(canvas): Focus mode does not dim the connections outside the focus set #329). Done in fix(canvas): Focus mode dims the connections outside the focus set (v0.21.1) #331, merged as 7e66da2 (v0.21.1, 2026-10-07); PR and main CI green, production checked, Release v0.21.1.

Work scheduled before PR 1

These are not part of the playback work; they are fixes scheduled to ship before PR 1.

• v0.21.2: value and detail rows sit inside Pool, Parameter and Register nodes (fix(canvas): Pool, Register and Parameter value rows sit too close to node silhouettes #332). Done in fix(canvas): Pool, Register and Parameter value rows sit inside the node (v0.21.2) #333, merged as c5e7d8f (2026-10-07); production checked, Release v0.21.2.
• v0.21.3: the edit lock's behaviour and its state display (fix(canvas): a new document starts unlocked, and the edit lock blocks every user edit (v0.21.3) #334 and fix(canvas): the edit-lock control shows locked and unlocked at a glance, without colour (v0.21.3) #335, in one pull request). Done in fix(canvas): the edit lock resets at document boundaries and shows its state (v0.21.3) #336, merged as 70a9c37 (2026-10-08); production checked, Release v0.21.3.
• v0.21.4: the Controls rail keeps its frame buttons, disabled, while the canvas is locked (fix(canvas): the Controls rail keeps its frame buttons, disabled, while the canvas is locked (v0.21.4) #338), and focusing the phone’s language search no longer zooms the page in on iPhone (fix(mobile): focusing the language search no longer zooms the page in on iPhone (v0.21.4) #340), in one pull request. Done in fix: the Controls rail keeps its frame buttons while the canvas is locked, and the phone's text fields no longer zoom the page (v0.21.4) #339, merged as 707fcc8 (2026-10-08); production checked, Release v0.21.4.
• Deferred after v0.24.0, no longer before PR 1: text containment for the Pool, Source, Drain, Converter and Gate (fix(canvas): text stays inside the Pool, Source, Drain, Converter and Gate outlines at every width #337). The investigation found that the current node and connection structure cannot keep text inside the outline, keep each node's geometry and leave the connections where they are all at once; it moves into a Diagram Readability design after v0.24.0 (see fix(canvas): text stays inside the Pool, Source, Drain, Converter and Gate outlines at every width #337).

Playback pull requests

• PR 1 (v0.22.0): the gate path highlight, +N badges, the label overlap rule, the 24-pair cap, with their reduced-motion and forced-colours forms. Done in feat(playback): the Gate path, a +N badge beside every token, the own-label rule and 24 pairs a step (v0.22.0) #341, merged as c4640bc (2026-10-09); production checked, Release v0.22.0.
• PR 2 (v0.23.0): the Pool arrival pulse and the Converter mark (option A), with their reduced-motion and forced-colours forms. Done in feat(playback): a Pool lights up as its first marker arrives, and a Converter shows a conversion mark (v0.23.0) #342, merged as 1a1ce1b (2026-10-09); production checked, Release v0.23.0.
• PR 3 (v0.24.0): the speed tiers, the phone's four speeds and its simpler drawing, large-graph checks. Done in feat(playback): speed tiers, a full Step, and the phone's Playback speed with 12 pairs a step (v0.24.0) #343, merged as 10098d6 (2026-10-09); production checked, Release v0.24.0.

Each pull request can be reverted on its own, keeps every existing playback test green, and changes a visual baseline only where it draws something new, each reviewed before it is updated.

Out of scope

• Any engine, RNG, state-semantics, file format, digest or simulation change; Monte Carlo and Predict stay without per-move choreography.
• Camera moves or auto-pan to the action; recording or exporting the animation; scrub with choreography.
• feat(graph): color-coded flows and compact nodes #325 and its milestone stay closed.
• No manual screen-reader check; automated accessibility-tree, focus and live-region tests are the bar.

Done when

• Every decision above is shipped, with its contract change in the document it belongs to.
• Wherever a round token travels in v0.21.0, it still travels, except at the very fast tier, where it appears at the end of the flashed path.
• The committed simulation, the run CSV, files and digests are byte-identical with and without the new cues, at every speed and under reduced motion.
• Every new cue has a reduced-motion and a forced-colours form, and a test that pins it.