feat(playback): the Gate path, a +N badge beside every token, the own-label rule and 24 pairs a step (v0.22.0)

[MerciHanrim]

Summary

Part of #330: the first of its three playback pull requests (v0.22.0). Playback now shows what moved where: the path a Gate took, every amount as a +N badge beside its round token, the connection's own label rule, the 24-pair cap, and Focus mode winning on connections, with their reduced-motion and forced-colours forms. A presentation layer only: the engine, the RNG, files, share links, digests and simulation results are unchanged; Monte Carlo draws no tokens, as before.

What changes

• The Gate path. For every Gate, deterministic or probabilistic, each outgoing connection that carried a move this step is highlighted (.pb-path--gate) under its round token, from its onset to settle; several can be at once. A branch with no move keeps its usual look.
• +N beside the round token. The round token still travels wherever it did. The step's summed amount always rides beside it as a badge, from +1; before, a bare number sat above the dot only when the amount was above 1. The badge lives in the label layer, above every connection label, pinned ltr; at L0 it is left out with the dot, as the dot already was.
• The connection's own label never moves. It dims only while its real box overlaps the token or the badge; no other connection's label is tested, and the label's size is read once per text, never per frame.
• 24 token-and-badge pairs per step replace the 60 travelling-cue budget, chosen by the same stable key. Past them, every resource connection that moved keeps the path highlight (.pb-path--over-cap) and its arrival cue.
• Focus mode wins on connections. Outside the focus set the path highlight, the token and badge, the depart / arrive cues, the L0 pulse and the reduced-motion forms are drawn at the connection's 0.26 (filter: opacity(), so it multiplies with their own animation); cues inside a node keep full strength.
• Reduced motion: nothing travels; the moved paths, the arrival tells and the +N badges (at the target end, off the target node) stay, static, for the committed step, within the same 24 pairs.
• Forced colours: the path highlight is told by width (4 px CanvasText), the badge is a Canvas pill with a CanvasText border, a covered label gives way while covered, and outside the focus set the highlight takes the 1 5 dash, the token turns hollow and the badge's border is dashed.

Contract changes

• docs/simulation-playback.md: §PB4.5 (24 pairs; past the cap, highlight and arrival cue) and the new §PB4.6 (Gate path, +N badge, label rule, Focus, reduced motion, forced colours).
• docs/large-graph-readability.md §LGR2.3: playback cues on a dimmed connection follow its dimming.
• docs/visual-language.md §VL9: the new motion and its reduced-motion form.
• examples/README.md: the playback fixture's cap and checklist.

Tests

• New e2e/playback-gate-path.spec.ts (8 tests): the taken branch of a deterministic and of a probabilistic Gate is highlighted and carries its token and +N, the untaken one keeps its computed look; a split moving on every branch highlights each; the own label dims only while covered and never moves; Focus dims the cues of an out-of-focus connection and not of an in-focus one; the forced-colours forms; the reduced-motion static form, held through a pause and cleared on Reset; the committed values and the document digest equal a run without the cues.
• src/components/edges/playbackBadge.test.ts (8 tests): the badge text from +1, its place beside the token, the own-label overlap rule, the cap of 24.
• Nine existing tests pinned the old contract (the 60 budget, the bare number above the dot); they now check the new one. Four titles changed, nothing was removed:

Spec	Old title	New title
playback-caps-perf	MAX_PLAYBACK_TOKENS_TOTAL — ≤ 60 travelling tokens; the overflow edges still commit	MAX_PLAYBACK_TOKENS_TOTAL — 24 token-and-badge pairs; the overflow edges keep a path highlight and still commit
playback-caps-perf	mixed 40 resource + 20 trigger + 20 label ⇒ ≤ 60 travelling elements total	mixed 40 resource + 20 trigger + 20 label ⇒ 24 travelling elements total
playback-caps-perf	the chosen 60 are independent of node / edge input order	the chosen 24 are independent of node / edge input order
playback-fixture	every travelling cue kind renders, and the global 60-token budget bites	every travelling cue kind renders, and the global 24-pair budget bites

• The other five keep their titles: canvas-refresh-edges "one token per edge per step…" and playback-choreography "several transfers on one edge…" read the badge instead of the old number; playback-caps-perf "MAX_PLAYBACK_TOKENS — a selected edge caps…" reads the badge; playback-fixture "the token walks the real d…" picks a Bézier edge among the 24 that carry a token (its old zf40 is now past the cap); large-graph-readability "VISUAL — a committed step…" has an updated baseline. The reduced-motion test in canvas-refresh-edges also checks the static +2.
• Test list: chromium 1,901 → 1,909 (+8), mobile 117 unchanged.

Baselines

Seven replaced, approved after an off (main 707fcc8) / on (this branch) capture of all 76, compared on every channel, each side also captured twice to separate noise: large-graph-readability run-distinction-states-chromium (the step's badges, a covered label dimmed) and playback-visual play-depart-{light,dark,forced-colors}-L2 on chromium and on mobile (the +3 badge beside the departing token, where a bare 3 sat above it). Two that differed were left as they are as noise: frames-activity-chromium (it differs between two captures of the same tree on both sides) and ko-desktop-app-chromium (3 px at the spot that varies between runs). The other 69 are byte-identical.

Checks run locally

• npx tsc -b, unit tests 3,279 passed, every source check:*, oxlint at its 39-warning baseline.
• Every spec that owns baselines, 1 worker, twice in a row: chromium 243 passed and mobile 88 passed in both runs, 0 failed, 0 retried.
• The full e2e, 2 workers: chromium 1,906 passed and 3 skipped, mobile 113 passed and 4 skipped; 0 failed, 0 retried.

Release

v0.22.0: package.json, the release-note entry (five lines in 18 languages, 16 without native review; the Portuguese lines are identical in pt-BR and pt-PT), .changes/playback-gate-path.json, CHANGELOG.md, README.md. The release date is set to the Seoul day of the merge right before it.

[cloudflare-workers-and-pages]

Deploying cozy-loop-studio with    Cloudflare Pages

Latest commit:	3d310d1
Status:	✅  Deploy successful!
Preview URL:	https://75898517.cozy-loop-studio.pages.dev
Branch Preview URL:	https://feat-play-gate-path.cozy-loop-studio.pages.dev

View logs