Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
fix(ui): rebuild onboarding to the approved design and suspend its motion off screen (#2028)
Max78db7eae5c9d
diff --git a/docs/plans/2026-09-17-onboarding-design-fidelity.md b/docs/plans/2026-09-17-onboarding-design-fidelity.mdnew file mode 100644index 000000000..b90d94f16--- /dev/null+++ b/docs/plans/2026-09-17-onboarding-design-fidelity.md@@ -0,0 +1,384 @@+# Onboarding design fidelity repair — issue #2017++PR #2015 merged successfully but did not faithfully reproduce the approved Welcome and assistant-setup design. The owner rejected the visual fidelity on 2026-09-17 and explicitly identified the existing animated Show Page as the implementation reference. At 16:55 the owner additionally required the designed widths and adaptation to different screens.++## Authority and scope++- Static appearance, copy, dimensions, and state presentation: `avibe-docs/design_desktop.pen`, read only through Pencil. The latest design wins if the older prototype differs.+- Welcome animation reference: https://max-app.avibe.bot/p/SM2vv4wGlM4/ (existing source is available locally; reuse its authored sequence and visual details rather than approximating it).+- Fix forward from current `master` after #2015. This is the visual correction of #2010. Keep existing logo assets, shared React Web/Desktop ownership, and existing setup/auth/config behavior.+- The separate #2011 authentication/readiness and #2012 Workbench/General issues retain their behavior scope. #2013 native desktop integration remains later. No new auth model, fabricated connected state, native window controls in Web, service restart, or production-state testing.++## Confirmed gaps in the merged source++- Document and code content were flattened into generic bars; document paragraphs/footer and code indentation/multiple segments are missing. Reveal, completion, and check-mark timing differ from the reference.+- The return wire loses its rounded route, ports, glow, and traveling pulse treatment. Return caption does not change with the cycle. PM content is reset at the summary phase.+- Theme fills/borders/shadows and internal spacing were approximated. A 240x228 outer card alone does not establish design fidelity.+- Narrow screens switch the collaborative diagram into a long vertical stack and hide the electric feedback loop, unlike the provided responsive prototype.+- Page/container widths, header composition, access-tile geometry, and setup-row alignment require an explicit measured comparison, including their interaction states.++## Acceptance contract++1. Every shared surface delivered by #2010 is compared to its corresponding final design state at the same effective content viewport. Record native-titlebar exclusion explicitly, retaining the designed Web content geometry. No arbitrary max-width, global zoom, or screenshot-only CSS may stand in for the designed layout.+2. At the desktop reference, collaboration is 880x272, each card 240x228, access area 640 wide, primary Welcome action 144x44, and assistant rows 880x88. **Superseded on 2026-09-17 by the owner's accepted 1104 cap — see "Accepted width" below; the frames' 880 numbers remain the source proportion.** Read precise text, spacing, radii, borders, fills and effects from Pencil, including Light values. Larger viewports preserve designed component widths and center the content. Smaller/shorter screens adapt without clipping, horizontal overflow, overlapping labels, disconnected wires, or unreachable controls; keep the collaborative sequence legible.+3. Welcome reproduces the authored 8.9-second loop: PM 0–1.5s; first handoff 1.5–2.25s; Codex 2.25–3.75s; second handoff 3.75–4.5s; tests 4.5–6s; return 6–7s; summary 7–8.9s. Source remains active in transit; destination activates on arrival. Document/code reveal, sequential test ticks, 850ms progress circle, 300ms hinge check, 250ms caption fade, wire ports/glow, and return caption follow the design/reference. Completed PM work stays complete during summary.+4. ~~Pause/replay synchronize all animated layers~~ — **superseded on 2026-09-17 18:26 by the owner: the design has no playback controls, so none ship.** Hidden/offscreen content suspends nonessential work; reduced motion gives a complete static narrative. Access-tile interaction and emphasis follow the reference and preserve keyboard use. See "Playback controls removed" below.+5. Dark/Light and Chinese/English use the same faithful component geometry. There is no separate Light English frame: combine the approved English copy and Light visual specification. Existing logos remain unchanged. Existing configuration, detection, installation, synchronization, navigation, and recovery invariants stay intact.+6. Evidence includes design exports, actual product screenshots, a same-size side-by-side or overlay comparison, measured geometry, and captured motion phases. Inspect desktop, intermediate, wide, narrow and short viewports; the representative matrix includes 1200x800, 1440x900, 1024x768, 768x1024, 390x844 and 320x568. A test count or a no-overflow assertion alone is not visual acceptance.+7. Before PR delivery, PM independently checks rendered fidelity and one consuming regression test. Run focused behavior/motion/i18n tests, UI build/lint, theme/catalog checks and the scoped Impeccable detector. Changes stay hermetic with mocked APIs; never claim live OAuth or real installation coverage from mocks.++## Reference frames++Welcome: `bi8Au`, `J0qaZ`, `P8iLm0`.+Setup: `i3vw9`, `lm7mN`, `ktRgC`; hover `mK2JX`, `ZaXoW`, `X7N2Z`; awaiting connection `ICidc`, `S3mLYc`, `HR3ps`; upgrade `I9Q8VD`, `pHiuw`, `QPdWU`; connected `F8RLgR`, `r1IQ0B`, `xNmhX`.++Installed/connection controls that depend on #2011 must be explicitly recorded as that issue's outstanding behavior, never presented as visually accepted by this correction. This issue restores the reachable #2010 surface and existing presentation props without inventing readiness.++## Delivery++One isolated task worktree and a non-draft PR to `master`; owner visual acceptance is required before declaring design fidelity complete. Exact-head Codex pass, all required CI green, zero unresolved threads, and review-loop circuit breaker remain mandatory. **Do not manually post `@codex review`: cyhhao triggers automatically; report any verified automation gap.** No automatic merge; the prior authorization applied to #2015 only.+++## Execution contract++Owner session: `sestqz5wvu5ty`. Branch: `fix/onboarding-design-fidelity`.+Baseline: `0d3e44de245e109b3e5e2dd98ce85c9b5e9a21f4` (latest origin/master at dispatch).+This plan supersedes the visual acceptance claim for merged #2010, not the deferred behavior boundaries of #2011–#2013. Implementation is authorized by the owner's correction; no repeat permission request is needed.++Source evidence (read-only):+- `/Users/max/workspace/ai/avibe/avibe-docs/design_desktop.pen`+- `/Users/max/.avibe/show/ses36vg559de2/src/pages/index.tsx`+- `/Users/max/.avibe/show/ses36vg559de2/src/welcome.css`+- `/tmp/onboarding-visual-repair/frames.json` and `design/` — freshly exported by Pencil on 2026-09-17 around 17:00. Check live source if a conflicting change is observed.+- `/tmp/issue2010-pencil.py` — working read-only stdio helper; initialize, notification, then 2s client registration delay. `execute` may use only Get/Print/Export/TakeScreenshot for this task. Do not parse or save the .pen raw file.++The prototype is an animation reference, not authority for stale product layout: the latest Pencil Welcome has no centered extra brand row, and its access area differs from the prototype's horizontal padding. Preserve existing logo assets wherever used; do not introduce the prototype Radio placeholder as a new Avibe logo. Shared Web omits simulated macOS window controls; compare the shared content rectangle explicitly instead of shifting all measurements silently.++### Animation origin session and precedence++On 2026-09-17 17:10 the owner named Session `ses36vg559de2` as the animation origin+("引导页动画实现在 ... 这个会话,你去参照"). Its local source at+`/Users/max/.avibe/show/ses36vg559de2/src/` is that Session's implementation and is+already the animation reference in this plan. Precedence, highest first:++1. Latest `design_desktop.pen` frames — static geometry, copy, fills, borders, radii, state presentation.+2. Session `ses36vg559de2` source — motion sequence, skeleton shapes, glyph and pulse behavior, calibrated glow.+3. Older prototype layout — superseded wherever 1 or 2 disagree.++Owner decisions carried from that Session's history (`/tmp/onboarding-visual-repair/reference-owner-decisions.json`,+96 messages; motion refinements in `reference-session.json`):++- Horizontal three-card PM/developer/tester story with authored document and code skeletons,+ progressive line reveal, and ordered test checks.+- Final durations: each work step <=1.5s, horizontal pulse 0.75s, return 1s, whole loop 8.9s.+ Earlier 12s / 2s / uniform-1s versions are superseded.+- Each handoff pulse travels once and disappears on arrival; no static arrows. The destination+ highlights and begins internal work only after the pulse lands; the source stays active in transit.+- The working glyph is a drawn green ring, not the earlier solid dot with a bubbling halo. The same+ ring stays mounted through completion, closes, then the check grows elastically from its hinge+ toward both ends. The ring is about 12px inside a 14px glyph. The status caption fades over 250ms+ without interrupting the ring.+- The active card carries a visible exterior green glow; an inward or too-subtle shadow was rejected.+ Use the browser-calibrated glow, not a naive transfer of Pencil's shadow spread. The Light pulse+ stays light mint rather than turning dark.+- Six access tiles use the actual product icons with Avibe App first. Hover scales the icon to 1.18+ and fills the tile at about half the border's opacity; idle randomized emphasis pauses on pointer+ entry and keyboard use stays intact. No outer wrapper border. The CTA itself stays still and only+ its arrow moves 4px right.+- The 2026-09-17 design removes the header and centered brand logos from the guidance screens+ ("这些引导页的logo都去掉") and widens the six access tiles so their outer edges align with the+ left and right vertical legs of the return wire ("左右侧和左右的这2条线对齐"). Existing product+ logo assets stay wherever a logo still belongs.+- The setup heading matches the Welcome heading in size, style, and position; setup content matches+ Welcome's width; row hover uses the Welcome glow.+- In Light, green-button text and icons are both white.++Unrelated logo exploration, desktop-shell implementation, and historical manual review triggers from+that Session are out of scope. The owner's no-manual-`@codex` rule still applies.++### Width and screen adaptation++Owner on 2026-09-17 17:14: "你要考虑不同大小屏幕的适配,是固定宽度还是?". The answer is a+capped fluid layout with a responsive internal arrangement — not a globally fixed 1200px page and+not a transform/zoom scale-down.++- 1200x800 is the design reference viewport, not a forced window size. Wider monitors gain+ surrounding whitespace; the cards never stretch to fill them.+- Below the cap, containers are `width:100%` with that max-width plus explicit page+ gutters (40px desktop, 24px tablet, 16px phone: 390 -> 358 usable, 320 -> 288 usable). No+ page-level min-width, so there is no horizontal overflow. The card grid uses percentage tracks+ (27.272727% with space-between), so card width, handoff gaps, and the stretched wire viewBox stay+ proportional at every container width without a separate rule per size.+- Intermediate widths adjust gaps and spacing before shrinking content. At phone widths the+ collaboration keeps its compact horizontal narrative, with wires and ports still attached to real+ card geometry. Card-internal labels wrap or stack and the diagram grows taller rather than+ shrinking text to an unreadable size; the caption stays at or above 11px instead of the+ prototype's 7px.+- Access tiles drop from three columns to two on narrow screens with comfortable targets. Assistant+ setup rows reflow status and actions onto another line, and the desktop 88px row height becomes+ content-driven on small screens.+- Short windows scroll naturally and keep the primary action reachable; no `overflow:hidden`+ clipping and no global scale-down. Content taller than the viewport is never cut off above the+ fold. **Corrected 2026-09-17 18:36: the welcome is vertically centred and the setup is+ top-anchored, because the frames anchor them differently — see "Vertical rhythm" below.**++If a full label cannot stay readable at the minimum width, report the concrete constraint and the+smallest layout adaptation rather than hiding information or treating no-overflow as a pass.++### Accepted width: 1104++Owner on 2026-09-17 17:38: "用1104". This accepts PM's recommendation and supersedes both the+frames' 880 and the unaccepted 1240 candidate. The frames stay the source of proportion; 1104 is+the cap the whole composition is drawn at.++- One shared `--ob-content-w: 1104px` caps the header, the Welcome story and the assistant rows,+ so header and body can never drift apart.+- Everything else is that cap times its authored ratio to 880, never a re-typed number: access area+ `640/880` -> 802.9, cards `27.272727%` -> 301.1 with 100.4 of handoff space, diagram+ `880:272` -> 1104x341.2, cards `228/272` of the diagram -> 286.0.+- The diagram is sized from its own width (`aspect-ratio`), not from the cap, so the proportion+ holds at every width between the gutters and the cap and the stretched `880x272` viewBox keeps+ every port on its card edge. Widening the cap alone would have detached the wires.+- Card interiors are drawn in design units (`--ob-u: 100cqw / 880`): padding, skeleton rhythm, bar+ and check sizes grow with the card, while text, icons and controls keep their authored sizes. A+ card a quarter taller must not read as a zoomed screenshot, and must not leave a hole under its+ skeleton either.+- Assistant rows widen to 1104; their 88 height stays because the row's contents fit it, and it is+ a `min-height` on the row itself (border included), not a multiplication. Everything inside the+ row keeps its authored size and offset, so the extra width lands in the identity column only.+- Below 960 the bands keep their hand-chosen diagram height and the authored interior rhythm.++### Vertical rhythm++The design's 1200x800 frames include the native 44px titlebar, so the web content box they describe+is 1200x756.++**Corrected 2026-09-17 18:24 (PM, from the live file).** Both frames show the heading block 65px+below the content edge, but only one of them *specifies* it. `JuwcG` and `KIxnF` centre the welcome+inside their frame, so its 65 is a RESULT of that frame's height; `IWQi6` tops the setup out at its+own 64.5 padding, so that 65 is the position itself. The product reproduces the setup's number as+20px shell padding plus the 45px language bar, and centres the welcome in what is left. A test that+pinned the welcome's y to 65 was asserting the one window height where the two happen to agree, and+has been replaced by a centring assertion plus the setup's own fixed top.++Centring is `align-self: center` inside a `flex: 1 0 auto` content box, which is what keeps a+composition taller than the window from being pushed off the top: the box grows to its content, the+slack to share becomes zero, and the shell scrolls from the content edge.++Measured from the frames rather than the exports, both screens run one rhythm from that edge:++- Welcome (`bi8Au`): heading 79, 24, collaboration 880x272, 24, access 640x160, 24, action 144x44,+ then 64 of slack. The heading is a 34/1.35 title, a 10 gap and a 14/1.57 subtitle; a browser+ stacks the same type to 77.9 because the design rounds each text box up on its own.+- Setup (`i3vw9`): the same heading block, 24, a 29 tall section bar, 12, then 88 tall rows on a+ 100 pitch, 24, and a footer that spaces action, hint and Back by 10. Inside a row: a 44 well 20+ from the outer edge, identity 16 further in, status and action against the opposite 20.+- The setup frame's OUTER container starts at x=48 of the 1200 frame and is 1104 wide, but the+ rows and content inside it are drawn at 880 like the welcome's. 1104 is therefore the design's+ own outer container, not its content width; the content reaches it only by the owner's amendment,+ and 48 is the gutter at which that cap is met.++The amendment changes exactly one term of that rhythm: the collaboration is 341.2 rather than 272,+so the welcome needs 781 of content height where the design needed 692. A 1200x800 desktop window+has a 756 content box, so something has to give.++**Corrected 2026-09-17 18:36 (PM).** It is not the spacing. There used to be a `max-height: 760px`+band that took the 24 gaps to 16 and halved the access block's padding; it bought about 30px and+spent the design's own composition to do it, at the reference's own frame size, where nothing was+wrong. That band is deleted. Whitespace IS the composition, so a short window scrolls: the type,+the icons, the buttons, the 24px gaps, the 88px assistant rows and their 12px spacing are identical+at every height, and only width adapts.++### 2026-09-17 18:23-18:36 repair disposition++PM held the first repair before push and issued a bounded correction list; the owner overruled one+part of it directly. This section is the source-backed disposition and replaces any earlier claim in+this plan that contradicts it.++#### Playback controls removed (owner, 18:26)++"不需要暂停和播放按钮,设计图里都没有呀". Every user-facing pause / play / resume / replay control+is gone, together with its reserved layout space, its state and handlers, and its copy and styles.+No substitute control replaces it. The loop starts with the screen and owns itself.++What stays is lifecycle only, because the browser — not the user — asks for it:++- `useOnboardingMotion()` returns `running` from a reduced-motion preference, document visibility+ and whether the composition is on screen. It has no setter and no UI.+- A hidden tab stops both halves of the motion together: the React clock the cards are read from,+ and the CSS animations the shimmer and the test ticks run on. Stopping only the first would leave+ the second playing on unseen and reappearing mid-sweep.+- Being scrolled out of sight stops the same two halves, because a visible document is only half+ the question: on a short window the diagram sits entirely above the viewport while the user reads+ the button below it. The hook observes the element each consumer attaches its ref to, so the story+ and the access tiles suspend independently: both are normally on screen together at desktop sizes,+ while a short or narrow window can give them different intersection. `threshold: 0` is the+ reading the incumbent observer in `vault-chat-requests` takes, so any intersecting pixel counts+ and a composition at the seam stays live instead of stuttering.+- No restart machinery was built for the removed button. Resuming continues the same sweep.++Manual pause/replay UI tests are deleted; the suite now asserts the *absence* of playback controls+on both steps, and captures deterministic phases through test-owned time control rather than any+shipped UI.++**Defect found by the rendered-state assertion.** The `data-motion="paused"` rule lost on+specificity to `.onboarding-collaboration-card[data-state="working"] .onboarding-skeleton::after`,+whose `animation` shorthand resets play state to running — so the longest-running effect on the+screen was the one the suspension never reached. Asserting the attribute would have passed. The rule+now carries `!important`, for the same reason the reduced-motion block does: no authored rule should+be able to out-specify "the tab is not being presented".++#### The access block follows the actual diagram width++The six tiles are drawn 640 wide on the diagram's own 880 box, so their outer edges land on the+vertical legs of the return wire (the ports at x=120 and x=760). `.onboarding-access` is therefore+`calc(100% * 640 / 880)` of the same box the diagram is sized from, not a number that happens to+agree at the cap. It is asserted at 1440 / 1200 / 1100 / 1024 / 900 / 768 against the rendered port+centres, because only a width derived from the real diagram holds at all of them.++Documented exception, below 600: two columns of 640/880 of a phone would be about 200px of tiles+inside a 360px screen, so the block takes the full content width and the tiles stay a readable+target. This deliberately leaves the wire relation rather than following it into an unusable size.++#### The active-card halo is one managed semantic token, themed through variables++The reference's dark halo is a spread-less 28px mint at `#5BFFA060`; Light has its own tighter+16/-4 at `#10B98170` over a `#10B98160` border. Both are now carried by one managed token,+`--shadow-glow-onboarding-mint`, instead of approximated by stacking two rungs of the sized scale.++Its per-theme parts are named runtime variables (`--onboarding-glow-blur`, `-spread`, `-alpha`)+re-anchored beside the rest of each light palette. That shape is not decoration: `src/index.css`+declares the token inside `@theme inline`, so Tailwind substitutes its VALUE into the utilities at+build time and a later re-declaration of the token name would compile to nothing while looking+correct in the file. `--brand-glow-blur` already uses this shape, and `assertInlineThemeTokensAreNotRedeclared`+exists precisely to fail the other one. The hue needs no variable: `color-mix(in srgb, var(--mint) …)`+already follows whichever mint the theme declares.++The auditor was strengthened rather than widened. `glowScale.test.mjs` now resolves each rung+through its own theme's declared numbers before asserting, so a themed blur is a number by+assertion time — which let the CTA move from "themed blur, therefore unasserted" to pinned at 16+(dark) and 20 (light), and let the new onboarding role be pinned in both themes. Four red probes+confirm it bites: light CTA blur, light onboarding blur, light onboarding alpha, dark onboarding+spread. No idle card or assistant row gained a drop shadow; the suite asserts idle cards carry+`box-shadow: none` in both themes.++#### Type, mobile identity, and button chrome++- The live design's headline is 34/1.35/600 at **-1.6** tracking (`XKQOx`, `Igagh`, `hv9DA` agree),+ shared by both steps and asserted from computed style.+- Narrow adaptations are deliberate and recorded in the stylesheet where they are made: 30/-1.4 at+ 960 (the same -0.047em ratio), and 25/-0.8 at 600 — phones loosen rather than follow the ratio,+ because tight tracking is exactly what costs legibility at that size.+- Below 600 the three card footers use one explicit grid (logo, name, role, each on its own row)+ with the name's box holding the two lines the longest of them needs. Free flex wrapping produced+ a different arrangement per name length and left the three separators up to 21px apart. Nothing is+ truncated, scaled globally, or dropped to the prototype's 7px; both lines of a wrapped name show.+ Asserted at 320 and 390 in EN and ZH and in the 768 band, from real bounding boxes: equal status+ y/height, equal identity y/height, no clipped or ellipsised label, role type at or above 10px.+- Re-scan is outlined (`n4ATm` / `H8gj7`); install and configure keep a visible themed border and+ surface; primary actions rest flat on the designed theme fill with its designed text colour. No+ global button recipe was rewritten and no darker global primary palette was adopted.++#### Skeletons are audited against native coordinates++All three are written from their own nodes and the numbers are recorded beside the rules:+`h5qtNn` (17 above the heading, then 12 / 8 / 14 / 7 / 7 between six lines, 14 below the last),+`u3bGM` (six 11-tall rows on a 16 pitch, 14 below the box top), `xyNG1` (four 12-tall rows on a 23+pitch, 17 below the box top — fewer rows, so this skeleton ends higher; the design's own asymmetry,+not slack). The extra card height the 1104 cap creates is allocated by reserving each end's authored+share in design units (17.56 status + 149.3 skeleton + 18.8 + 55.2 identity = 240.9 of content), so+the three separators align by construction and the surplus cannot pool under the last bar.+Typography and icons keep their authored sizes. No document footer or test-result strip was added.++#### Source-approved, left alone++The dark browser shadow stays as drawn (the native -17 spread is not copied), the return height is+correct, the 2s access emphasis is authored interaction and is not erased to match a static still,+existing logo assets and `PlatformIcon` are untouched, an idle Codex card is authored, the shimmer+is authored, and dual-card glow in a settled still is a comparison artefact of holding every effect+at one time rather than leakage.++Two observations from the 21:40 read-only visual pass are recorded as non-blocking rather than+fixed: the English testing caption takes three lines at 320 — the footer and card baselines stay+aligned and every word is readable, so wrapping is preferred to shrinking it — and the optical+top/bottom difference at 768 is explained by the native header's own space, so no redesign follows.++#### Evidence claims++- Settled stills (every CSS effect held past its end) are the only images compared against a static+ frame; they are labelled as such. The normal-speed evidence is a separate recorded run with no+ clock control at all, sampling what the page actually draws across a full loop and across a+ hide/show.+- `ThemeProvider` is checked for real: System mode sets no `data-theme` and follows an emulated OS+ switch live, and a stored explicit preference survives the OS moving in either direction and a+ reload.+- The fixture stays hermetic: a deny-by-default route records every non-GET or off-origin request+ and each test asserts that list is empty. No local service, no Incus runner, and no OAuth or+ install was ever performed — the assistants render an installed, permitted runtime because the+ fixture answers those reads, which is a rendering claim and not a working-integration one.++**Capture clock ownership, corrected 2026-09-17 21:52.** `page.clock.install()` replaces the timer+functions but leaves the clock advancing with real time — measured directly: 38 ticks of a 16ms+interval in 600ms of wall time. Only `pauseAt` holds it. Every "settled" still therefore landed+wherever wall-clock time had carried the story, which is how a dark and a light capture of the same+size ended up drawing different cards. `openOnboarding` now pauses at a fixed instant, after which+only `freezeAt` moves it; each still names its phase in its filename and the capture asserts the+rendered states are that phase's. This was found because the new offscreen test failed on it, not to+improve a claim.++Two limitations stand in the batch as it exists:++- `welcome-design-frame-1200x756-codex-working.png` is a VIEWPORT CROP, not a whole composition: at+ 756 the primary action is below the fold. It proves matching in-view geometry only. Scrolling is+ the accepted outcome and the button is reachable; the companion `…-cta-…` still shows it scrolled+ to, and a second companion at 390x300 comes from the offscreen test.+- Images produced before the clock fix are not an exact-phase cross-theme pair, whatever their+ filename said. No deterministic same-phase A/B may be claimed for that batch. The batch shipped+ with this change is regenerated under the paused clock, where the phase is exact by construction.++#### The 360 slot is the assistant block (PM, 21:38)++Item 3's "minimum 360px slot" is `.onboarding-assistants`, the region native `sNs1V` names, and it+already carries `min-height: 360px`. An earlier note in this plan added up 252 and 348 from the+blocks *around* it and concluded the number did not resolve; those sums never measured the slot's+own minimum and are withdrawn. No implementation change followed — the geometry case now asserts the+slot directly (computed `min-height` 360, rendered height at least 360), together with the 24 below+it and the 52 from the last row to the button. Measuring both gaps is what shows the 52 comes from+the slot's spare height plus the 24, rather than from a margin tuned to match it.++### Follow-on boundary (not this patch)++The owner's 17:49 desktop request (no top navigation, System-default theme switching) belongs to+issues #2012 and #2013. This patch preserves the existing `ThemeProvider` semantics (System default,+stored manual preference, shared setter) and the Web language entry in the onboarding header, and+adds no desktop detection.++### Ownership++Single UI implementation lane owns `ui/src/components/onboarding/*`, `ui/src/components/steps/Welcome.tsx`, presentation-only edits in `steps/AgentDetection.tsx` and `Wizard.tsx`, directly related tests, only relevant `onboarding.*` keys in `ui/src/i18n/en.json` and `zh.json`, and this plan plus a short status correction to the existing shared plan. Keep detection/install/provider reconciliation, Back/Continue completion flow, and auth semantics intact. Reuse existing primitives/icons; component-scoped theme variables may encode exact approved design values without changing the global theme. Broader tokens/primitive or behavior changes require PM scope diagnosis before editing.++No-touch: primary checkout, old shared-onboarding worktree, other task branches/worktrees, design file, existing Show Page, native desktop, Python/API/persistent schema, credentials, runtime service, unrelated i18n, and global Workbench/Settings. PM may edit this plan before dispatch; after dispatch the lane is the sole writer until hand-back.++### Implementation and evidence++- Audit incumbent at this baseline against complete exported state set. Record residual #2011 controls accurately. Fix all in-scope visual drift, not only the obvious animation.+- Port the authored sequence and skeleton/line/check shapes into the existing React components. Adapt imports/i18n/semantic theme ownership; avoid importing the Show runtime or introducing parallel controllers/dependencies.+- Desktop width is constrained by design, not by available monitor width. On narrow screens preserve the pulse's source/destination connections through actual component sizing; do not solve overflow by discarding the narrative.+- Build a hermetic browser fixture for the actual product entry with mocked network and isolated browser state. Explicitly deny unmatched write-capable requests. Never connect to the running local service or call the Incus runner. No real auth/install claim.+- Capture design, before and after at the same content viewport and freeze the same timeline phase (reference is PM complete, Codex working, tests waiting); record crop/native-titlebar rules. Capture each phase and a representative full loop, plus hidden/reduced motion — ~~pause/replay~~ superseded 18:26, there are no playback controls to capture. Automated bounding rectangles supplement screenshots, not replace them.+- Test responsive invariants over wide/intermediate/narrow/short sizes; test Chinese/English and light/dark, preserve System mode. At 1200x800 do not inherit the prototype's preview-stage breakpoint that shrinks the cards merely because height <=850; the actual design has 240x228 cards there.+- Before opening a PR, deliver a concrete diff, local verification and screenshot/motion evidence for PM spot-check. No new product-direction approval is required. PM checks fidelity and consumer regressions before the first push.+- After the reviewed patch is ready, create PR with `Closes #2017`, base master, include scenario IDs and evidence/residual checks. Immediately notify PM with PR/head so an independent PM Watch can be armed; keep one durable lane combined PR/CI Watch. Never manually trigger Codex. Review/CI follow-up uses the normal circuit breaker.++### Tasks++- [x] Issue created and title/body read back.+- [x] Read existing Show Page source and latest Pencil frames.+- [x] Isolated worktree created from latest master.+- [x] Complete source-to-render difference table and fix shared visuals.+- [x] Complete same-viewport screenshot, motion and responsive evidence.+- [x] Bounded repair of the 18:23-18:36 disposition, recorded above.+- [x] Offscreen suspension, the 360 slot assertion, and the capture clock fix (PM 21:38/21:40).+- [ ] PM independent pre-push spot-check.+- [ ] PR, exact-head review, zero unresolved threads, all required CI green.+- [ ] Owner visual acceptance; merge requires a fresh explicit instruction.diff --git a/ui/e2e/onboarding-fidelity/fixture.html b/ui/e2e/onboarding-fidelity/fixture.htmlnew file mode 100644index 000000000..dfdaac5cc--- /dev/null+++ b/ui/e2e/onboarding-fidelity/fixture.html@@ -0,0 +1,2 @@+<!doctype html>+<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Onboarding fidelity fixture</title></head><body><div id="root"></div><script type="module" src="./fixture.tsx"></script></body></html>diff --git a/ui/e2e/onboarding-fidelity/fixture.tsx b/ui/e2e/onboarding-fidelity/fixture.tsxnew file mode 100644index 000000000..ee169c8a5--- /dev/null+++ b/ui/e2e/onboarding-fidelity/fixture.tsx@@ -0,0 +1,39 @@+// Mounts the product's own Wizard — the real component that renders the Welcome+// and assistant-setup screens — inside the real providers. Nothing here restates+// onboarding layout or behaviour: the whole point is that the browser measures+// the shipped component tree. Every request is answered by the spec's routes, so+// the fixture never reaches a running service and never writes anything.+import { createRoot } from 'react-dom/client';+import { createInstance } from 'i18next';+import { I18nextProvider } from 'react-i18next';+import en from '../../src/i18n/en.json';+import zh from '../../src/i18n/zh.json';+import '../../src/index.css';+import { ApiProvider } from '../../src/context/ApiContext';+import { ThemeProvider } from '../../src/context/ThemeProvider';+import { ToastProvider } from '../../src/context/ToastProvider';+import { Wizard } from '../../src/components/Wizard';++// The product's own ThemeProvider, reading the same `?theme=` it reads in the app:+// `dark` and `light` are explicit preferences, `system` follows the OS. Writing+// `data-theme` here instead would have been the fixture theming itself, which cannot+// show whether System-mode follow and preference preservation still work.+const params = new URLSearchParams(location.search);+const language = createInstance();+await language.init({+ lng: params.get('lang') ?? 'en',+ resources: { en: { translation: en }, zh: { translation: zh } },+ interpolation: { escapeValue: false },+});++createRoot(document.getElementById('root')!).render(+ <I18nextProvider i18n={language}>+ <ThemeProvider>+ <ToastProvider>+ <ApiProvider>+ <Wizard />+ </ApiProvider>+ </ToastProvider>+ </ThemeProvider>+ </I18nextProvider>,+);diff --git a/ui/e2e/onboarding-fidelity/geometry.spec.ts b/ui/e2e/onboarding-fidelity/geometry.spec.tsnew file mode 100644index 000000000..1ca914796--- /dev/null+++ b/ui/e2e/onboarding-fidelity/geometry.spec.ts@@ -0,0 +1,681 @@+import { expect, test, type Page } from '@playwright/test';+import {+ PHASES, VIEWPORTS, cssEffects, freezeAt, openOnboarding, openSetup, renderedPhase,+ serveProduct, setDocumentHidden, settleEffects, size, storeThemePreference,+} from './support';++/**+ * The 2026-09-17 design is a set of exact numbers, so this suite measures the shipped+ * component in a browser instead of asserting that nothing overflows. Screenshots are+ * written as artifacts from the same runs that make the assertions, so the evidence and+ * the guard can never describe two different builds.+ *+ * Sizes: a Playwright viewport IS the web content box, so nothing is subtracted for+ * chrome. The design's own 1200x800 frames include the native 44px titlebar above the+ * web view, which makes the design's content box 1200x756 — that is the size to overlay+ * a frame against (DESIGN_FRAME below). The dispatch's 1200x800 of effective content is+ * the larger window that same content box needs, and is what the matrix captures.+ *+ * The owner accepted 1104 as the desktop content cap on 2026-09-17, superseding the+ * frames' authored 880. Every number below is that decision applied to the frame's+ * proportion (1104/880 = 1.2545...), not a re-measured design.+ */+const DESIGN_FRAME = { width: 1200, height: 756 };+/**+ * The one moment every still is taken at, carried into the filename so an artifact says+ * which phase it is rather than leaving a reader to infer it. Since `openOnboarding`+ * pauses the clock before the page loads, this is exact and not merely settled: the same+ * phase draws the same cards across themes, languages and sizes, which is what makes a+ * dark/light pair of one size a content A/B rather than two unrelated frames.+ */+const CAPTURE_PHASE = 'codex-working';+const CAPTURE_STATES = ['complete', 'working', 'waiting'];+/** 20px of shell padding plus the 45px language bar: the setup's authored top (IWQi6). */+const SETUP_TOP = 65;++const box = async (page: Page, selector: string, index = 0) => {+ const rect = await page.locator(selector).nth(index).boundingBox();+ if (!rect) throw new Error(`${selector} is not rendered`);+ return rect;+};++/** Every match's real rect in one round trip — what "aligned" has to be measured from. */+const boxes = (page: Page, selector: string) =>+ page.locator(selector).evaluateAll((nodes) => nodes.map((node) => {+ const rect = node.getBoundingClientRect();+ return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };+ }));++const round = (value: number) => Math.round(value * 100) / 100;+const spread = (values: number[]) => Math.max(...values) - Math.min(...values);++test.describe('desktop reference geometry', () => {+ test.use({ viewport: { width: 1200, height: 800 } });++ test('welcome matches the accepted 1104 collaboration and 802.9 access spans', async ({ page }, info) => {+ const denied = await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES['codex-working']);++ const collaboration = await box(page, '.onboarding-collaboration');+ expect(round(collaboration.width)).toBe(1104);+ expect(collaboration.height).toBeCloseTo(341.24, 1);+ // Card size comes from a percentage track and the diagram's own width, so the+ // proportion holds at every width; those ratios are not representable on the+ // engine's 1/64px grid, so the numbers are met to within a sixty-fourth of a pixel.+ for (let index = 0; index < 3; index += 1) {+ const card = await box(page, '.onboarding-collaboration-card', index);+ expect(card.width).toBeCloseTo(301.09, 1);+ expect(card.height).toBeCloseTo(286.04, 1);+ }+ const [first, second, third] = await Promise.all([0, 1, 2].map((index) => box(page, '.onboarding-collaboration-card', index)));+ expect(second.x - (first.x + first.width)).toBeCloseTo(100.36, 1);+ expect(third.x - (second.x + second.width)).toBeCloseTo(100.36, 1);+ // What has to be exact is that the wire endpoints sit on the card edges: both are+ // driven by the same percentage basis, so a port can never drift off its card.+ const port = await box(page, '.onboarding-port', 0);+ expect(port.x + port.width / 2).toBeCloseTo(first.x + first.width, 1);++ const access = await box(page, '.onboarding-access');+ expect(access.width).toBeCloseTo(802.91, 1);+ expect(access.x - collaboration.x).toBeCloseTo(150.55, 1);++ const action = await box(page, '.onboarding-primary-action');+ expect(round(action.height)).toBe(44);+ expect(action.width).toBeGreaterThanOrEqual(144);++ await settleEffects(page);+ await page.screenshot({ path: info.outputPath('welcome-1200x800-dark-en.png') });+ expect(denied).toEqual([]);+ });++ // The design stacks the welcome with one rhythm: a 79 tall message block, then 24+ // between every block (frame bi8Au, whose blocks sit at y=65/168/464/648 of its 756+ // content box). The 1104 amendment makes the collaboration taller, so the blocks below+ // it move down by that much and no other number changes.+ test('welcome keeps the design vertical rhythm between its blocks', async ({ page }) => {+ const denied = await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES['codex-working']);++ const heading = await box(page, '.onboarding-heading');+ // The same type the design specifies: a 34/1.35 title, a 10 gap and a 14/1.57+ // subtitle. The design reports 79 because it rounds each text box up on its own+ // (46 + 10 + 23); the browser stacks the unrounded boxes to 77.9.+ expect(heading.height).toBeCloseTo(77.89, 1);++ const story = await box(page, '.onboarding-story');+ const access = await box(page, '.onboarding-access');+ const action = await box(page, '.onboarding-primary-action');+ expect(story.y - (heading.y + heading.height)).toBeCloseTo(24, 0);+ expect(access.y - (story.y + story.height)).toBeCloseTo(24, 0);+ expect(action.y - (access.y + access.height)).toBeCloseTo(24, 0);+ // The access block's own height is content, not cap: two 42 rows, an 8 gap, the+ // caption and 17 of padding — the design's 160 at any width.+ expect(round(access.height)).toBe(160);+ expect(denied).toEqual([]);+ });++ /**+ * The two steps are anchored differently because the design anchors them differently:+ * JuwcG and KIxnF centre the welcome inside their frame, IWQi6 tops the setup out at+ * its own 64.5 padding. So the welcome's y is a RESULT of the window height and the+ * setup's is a position — and a test that pinned the welcome to 65 was asserting the+ * one window height where those two happen to agree.+ */+ test('the welcome is centred by the window, and the setup is not', async ({ page }) => {+ await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES['codex-working']);++ const centring = async () => {+ const content = await box(page, '.onboarding-shell-content');+ const welcome = await box(page, '.onboarding-welcome');+ return {+ above: welcome.y - content.y,+ below: (content.y + content.height) - (welcome.y + welcome.height),+ headingY: (await box(page, '.onboarding-heading')).y,+ };+ };++ await page.setViewportSize({ width: 1200, height: 1200 });+ const tall = await centring();+ expect(Math.abs(tall.above - tall.below)).toBeLessThanOrEqual(1);+ // Centred means it moved: a tall window puts the heading far below the setup's 65.+ expect(tall.headingY).toBeGreaterThan(SETUP_TOP + 100);++ // At the design's own content box the composition is taller than the window, so+ // there is no slack to share and the same rule lands it on the content edge — where+ // the frame draws it. The shell scrolls from there instead of clipping the top.+ await page.setViewportSize(DESIGN_FRAME);+ const short = await centring();+ expect(short.above).toBeLessThanOrEqual(1);+ expect(round(short.headingY)).toBe(SETUP_TOP);++ await openSetup(page, 'en');+ // The setup's top is the position itself, so it holds at both window heights.+ expect(round((await box(page, '.onboarding-heading')).y)).toBe(SETUP_TOP);+ await page.setViewportSize({ width: 1200, height: 1200 });+ expect(round((await box(page, '.onboarding-heading')).y)).toBe(SETUP_TOP);+ });++ /**+ * A short window used to buy about 30px by taking the step gaps from 24 to 16 and+ * squeezing the access block — spending the design's own spacing at 1200x800, the+ * reference's own frame size, where nothing was wrong. Whitespace IS the composition,+ * so the shell scrolls instead and nothing about the type or the controls changes.+ */+ test('a short window scrolls rather than compressing the composition', async ({ page }) => {+ await serveProduct(page);+ await openOnboarding(page);+ const metrics = () => page.evaluate(() => {+ const read = (selector: string) => {+ const node = document.querySelector(selector);+ const style = node ? getComputedStyle(node) : null;+ return style ? `${style.fontSize}/${style.lineHeight}` : 'missing';+ };+ const rect = (selector: string) => {+ const found = document.querySelector(selector)?.getBoundingClientRect();+ return found ? `${Math.round(found.width)}x${Math.round(found.height)}` : 'missing';+ };+ return {+ type: [read('.onboarding-heading :is(h1, h2)'), read('.onboarding-heading p'), read('.onboarding-access-tile span')],+ action: [rect('.onboarding-primary-action'), read('.onboarding-primary-action')],+ access: rect('.onboarding-access'),+ };+ });+ const tall = await metrics();++ await page.setViewportSize(DESIGN_FRAME);+ await freezeAt(page, PHASES['codex-working']);+ expect(await metrics()).toEqual(tall);++ const heading = await box(page, '.onboarding-heading');+ const story = await box(page, '.onboarding-story');+ const access = await box(page, '.onboarding-access');+ const action = await box(page, '.onboarding-primary-action');+ for (const gap of [story.y - (heading.y + heading.height), access.y - (story.y + story.height), action.y - (access.y + access.height)]) {+ expect(gap).toBeCloseTo(24, 0);+ }+ // Scrolling is the accepted outcome, and it has to actually be reachable.+ expect(await page.evaluate(() => document.documentElement.scrollHeight > window.innerHeight+ || (document.querySelector('.onboarding-shell') as HTMLElement).scrollHeight > window.innerHeight)).toBe(true);+ await page.locator('.onboarding-primary-action').scrollIntoViewIfNeeded();+ await expect(page.locator('.onboarding-primary-action')).toBeInViewport();+ });++ test('assistant setup keeps the shared width, 88px rows and 12px spacing', async ({ page }, info) => {+ const denied = await serveProduct(page);+ await openOnboarding(page);+ const welcomeTitle = await box(page, '.onboarding-heading :is(h1, h2)');+ await openSetup(page, 'en');++ const setupTitle = await box(page, '.onboarding-heading :is(h1, h2)');+ // The title's box is shared between the steps; only its y differs, because only the+ // welcome is centred. Asserting the height keeps the two from drifting apart.+ expect(round(setupTitle.height)).toBe(round(welcomeTitle.height));++ const assistants = await box(page, '.onboarding-assistants');+ expect(round(assistants.width)).toBe(1104);+ // The block keeps native sNs1V's 360 slot as a reserved minimum: small content growth+ // — a detection error, an install chip — is absorbed by the slack already there+ // instead of moving the button, and anything larger grows the block naturally.+ expect(await page.locator('.onboarding-assistants').evaluate((node) => getComputedStyle(node).minHeight)).toBe('360px');+ expect(assistants.height).toBeGreaterThanOrEqual(360);+ await expect(page.locator('.onboarding-assistant')).toHaveCount(3);+ for (let index = 0; index < 3; index += 1) {+ const row = await box(page, '.onboarding-assistant', index);+ // Width follows the shared cap; height stays the design's 88 because the row's+ // content fits it, not because a fixed height forces it.+ expect([round(row.width), round(row.height)]).toEqual([1104, 88]);+ // Inside the row nothing was rescaled: a 44 well 20 from the edge, then identity+ // 16 further in, exactly as frame i3vw9 lays every backend row out.+ const logo = await box(page, '.onboarding-assistant-logo', index);+ expect([round(logo.width), round(logo.height)]).toEqual([44, 44]);+ expect(round(logo.x - row.x)).toBe(20);+ expect(round(logo.y - row.y)).toBe(22);+ const identity = await box(page, '.onboarding-assistant-identity', index);+ expect(round(identity.x - row.x)).toBe(80);+ }+ // 12 between the section bar and the first row, and between rows (design pitch 100).+ const header = await box(page, '.onboarding-assistants-header');+ const [firstRow, secondRow] = await Promise.all([0, 1].map((index) => box(page, '.onboarding-assistant', index)));+ expect(firstRow.y - (header.y + header.height)).toBeCloseTo(12, 0);+ expect(round(secondRow.y - firstRow.y)).toBe(100);+ // The setup heading keeps the welcome's 24 to the block below it.+ const setupHeading = await box(page, '.onboarding-heading');+ expect(header.y - (setupHeading.y + setupHeading.height)).toBeCloseTo(24, 0);+ // And the same 24 below the slot, which puts the button 52 under the last row: the+ // slot's own spare height plus that gap. Measuring both is what proves the 52 comes+ // from the 360 slot rather than from a margin someone tuned to match it.+ const footer = await box(page, '.onboarding-setup-footer');+ const lastRow = await box(page, '.onboarding-assistant', 2);+ const cta = await box(page, '.onboarding-primary-action');+ expect(footer.y - (assistants.y + assistants.height)).toBeCloseTo(24, 0);+ expect(cta.y - (lastRow.y + lastRow.height)).toBeCloseTo(52, 0);++ await settleEffects(page);+ await page.screenshot({ path: info.outputPath('setup-1200x800-dark-en.png') });+ expect(denied).toEqual([]);+ });++ // The live design sets one headline everywhere: 34/1.35/600 at -1.6 tracking (XKQOx,+ // Igagh and hv9DA all agree), which is tighter than the browser default this shipped+ // with. Both steps read it from the same rule, so both are checked.+ test('both steps use the live design headline tracking', async ({ page }) => {+ await serveProduct(page);+ await openOnboarding(page);+ const type = () => page.evaluate(() => {+ const node = document.querySelector('.onboarding-heading :is(h1, h2)');+ const style = node ? getComputedStyle(node) : null;+ return style ? { size: style.fontSize, tracking: style.letterSpacing, weight: style.fontWeight } : null;+ });+ const expected = { size: '34px', tracking: '-1.6px', weight: '600' };+ expect(await type()).toEqual(expected);+ await openSetup(page, 'en');+ expect(await type()).toEqual(expected);+ });++ test('every handoff pulse rides the wire that connects its two cards', async ({ page }, info) => {+ const denied = await serveProduct(page);+ await openOnboarding(page);+ let clock = 0;+ for (const [name, elapsed] of Object.entries(PHASES)) {+ await freezeAt(page, elapsed - clock);+ clock = elapsed;+ const travelling = name.startsWith('handoff') || name === 'return-to-pm';+ await expect(page.getByTestId('handoff-pulse')).toHaveCount(travelling ? 1 : 0);+ await settleEffects(page);+ await page.locator('.onboarding-collaboration').screenshot({ path: info.outputPath(`phase-${name}.png`) });+ }+ expect(denied).toEqual([]);+ });+});++test.describe('capped fluid width', () => {+ for (const viewport of VIEWPORTS) {+ test(`fits ${size(viewport)} without horizontal overflow or clipping`, async ({ page }) => {+ await page.setViewportSize(viewport);+ const denied = await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES['codex-working']);++ expect(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true);+ const collaboration = await box(page, '.onboarding-collaboration');+ // Capped fluid: never wider than the accepted cap, never wider than the viewport.+ expect(collaboration.width).toBeLessThanOrEqual(1104);+ expect(collaboration.width).toBeLessThanOrEqual(viewport.width);+ const wires = await box(page, '.onboarding-wires');+ // The stretched wire box always covers the cards, so no pulse can detach.+ expect(round(wires.width)).toBe(round(collaboration.width));++ // The primary action stays reachable: short viewports scroll rather than clip.+ const action = page.locator('.onboarding-primary-action');+ await action.scrollIntoViewIfNeeded();+ await expect(action).toBeInViewport();+ const clipped = await page.evaluate(() => {+ const shell = document.querySelector('.onboarding-shell');+ return shell ? getComputedStyle(shell).overflowY === 'hidden' : true;+ });+ expect(clipped).toBe(false);+ expect(denied).toEqual([]);+ });+ }++ /**+ * The access block is drawn 640 wide on the diagram's own 880 box, so its edges land+ * on the vertical legs of the return wire — the ports at x=120 and x=760. Checking+ * that at the cap alone would pass on a block sized from a fixed number that happens+ * to agree there, so it is checked at every width in between: only a width derived+ * from the diagram's ACTUAL width can hold the relation at all of them.+ */+ for (const width of [1440, 1200, 1100, 1024, 900, 768]) {+ test(`the access block spans the return wire legs at ${width}`, async ({ page }) => {+ await page.setViewportSize({ width, height: 900 });+ await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES['codex-working']);++ const access = await box(page, '.onboarding-access');+ // PORTS index 5 is the x=120 leg and index 4 the x=760 one; `preserveAspectRatio`+ // is none, so each maps to that share of the rendered width.+ const left = await box(page, '.onboarding-port', 5);+ const right = await box(page, '.onboarding-port', 4);+ expect(access.x).toBeCloseTo(left.x + left.width / 2, 0);+ expect(access.x + access.width).toBeCloseTo(right.x + right.width / 2, 0);+ });+ }++ /**+ * The one documented exception. Two columns of 640/880 of a phone would be about+ * 200px of tiles inside a 360px screen, so below 600 the block takes the full content+ * width and the tiles stay a readable target — deliberately leaving the wire relation+ * rather than following it into an unusable size.+ */+ test('phones take the full content width instead, on purpose', async ({ page }) => {+ await page.setViewportSize({ width: 390, height: 844 });+ await serveProduct(page);+ await openOnboarding(page);+ const access = await box(page, '.onboarding-access');+ const welcome = await box(page, '.onboarding-welcome');+ expect(round(access.width)).toBe(round(welcome.width));+ });++ test('access tiles drop to two columns on phones and keep full labels', async ({ page }) => {+ await page.setViewportSize({ width: 390, height: 844 });+ await serveProduct(page);+ await openOnboarding(page);+ const tiles = page.locator('.onboarding-access-tile');+ await expect(tiles).toHaveCount(6);+ const rects = await tiles.evaluateAll((nodes) => nodes.map((node) => node.getBoundingClientRect().top));+ expect(new Set(rects.map((top) => Math.round(top))).size).toBe(3);+ const labels = await tiles.evaluateAll((nodes) => nodes.map((node) => node.scrollWidth <= node.clientWidth + 1));+ expect(labels).toEqual([true, true, true, true, true, true]);+ });+});++/**+ * Narrow widths are where a card stops being a scaled copy of the design and becomes an+ * adaptation, so the thing to check is that the adaptation is ONE arrangement rather+ * than whichever one each label's length happens to produce. Every assertion here reads+ * real bounding boxes: three status rows that start and end together, three identities+ * that do, and no label clipped or truncated to make that true.+ */+test.describe('narrow identity alignment', () => {+ for (const viewport of [{ width: 320, height: 568 }, { width: 390, height: 844 }, { width: 768, height: 1024 }]) {+ for (const lang of ['en', 'zh'] as const) {+ test(`${size(viewport)} ${lang} keeps the three cards on one grid`, async ({ page }, info) => {+ await page.setViewportSize(viewport);+ const denied = await serveProduct(page);+ await openOnboarding(page, { lang });+ await freezeAt(page, PHASES['codex-working']);++ const statuses = await boxes(page, '.onboarding-story-status');+ const identities = await boxes(page, '.onboarding-story-identity');+ expect([statuses.length, identities.length]).toEqual([3, 3]);+ // The header row and the separator above the footer are the two lines the eye+ // reads across the three cards, so both have to be one line, not three.+ expect(spread(statuses.map((one) => one.y))).toBeLessThanOrEqual(1);+ expect(spread(statuses.map((one) => one.height))).toBeLessThanOrEqual(1);+ expect(spread(identities.map((one) => one.y))).toBeLessThanOrEqual(1);+ expect(spread(identities.map((one) => one.height))).toBeLessThanOrEqual(1);++ // Alignment must not have been bought by cutting the labels: every name, role+ // and caption is fully inside its own box, with no ellipsis doing the fitting.+ const clipped = await page.locator(+ '.onboarding-story-identity strong, .onboarding-story-identity > span:last-child, .onboarding-status-text',+ ).evaluateAll((nodes) => nodes+ .filter((node) => {+ const style = getComputedStyle(node);+ return node.scrollWidth > node.clientWidth + 1+ || node.scrollHeight > node.clientHeight + 1+ || style.textOverflow === 'ellipsis';+ })+ .map((node) => node.textContent?.trim() ?? ''));+ expect(clipped).toEqual([]);+ // …and the labels are still the product's own words at a readable size.+ const names = await page.locator('.onboarding-story-identity strong').allInnerTexts();+ expect(names.map((name) => name.replace(/\s+/g, ' ').trim())).toEqual(['Claude Code', 'Codex', 'OpenCode']);+ const smallest = await page.locator('.onboarding-story-identity > span:last-child')+ .evaluateAll((nodes) => Math.min(...nodes.map((node) => parseFloat(getComputedStyle(node).fontSize))));+ expect(smallest).toBeGreaterThanOrEqual(10);++ await settleEffects(page);+ await page.locator('.onboarding-collaboration').screenshot({+ path: info.outputPath(`identity-${size(viewport)}-${lang}.png`),+ });+ expect(denied).toEqual([]);+ });+ }+ }+});++/**+ * The approved design has no playback toolbar, so the story owns its own lifecycle:+ * it starts with the screen, loops, and stops only for the two things the browser tells+ * it about — a reduced-motion preference and a tab that is not being presented.+ */+test.describe('motion lifecycle', () => {+ test.use({ viewport: { width: 1200, height: 800 } });++ const PLAYBACK = /pause|play|resume|replay|restart|暂停|播放|重播|重新播放/i;++ test('ships no playback control on either step', async ({ page }) => {+ await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES['tests-running']);++ // Nothing inside the diagram is operable at all — not a button, not a control that+ // merely looks like text, and not a reserved slot waiting for one.+ await expect(page.locator('.onboarding-story button, .onboarding-story [role="button"], .onboarding-story input')).toHaveCount(0);+ const named = async () => (await page.locator('button, [role="button"], input, a').evaluateAll((nodes) => nodes+ .map((node) => `${node.getAttribute('aria-label') ?? ''} ${node.textContent ?? ''} ${node.getAttribute('title') ?? ''}`)))+ .filter((label) => PLAYBACK.test(label));+ expect(await named()).toEqual([]);+ await openSetup(page, 'en');+ expect(await named()).toEqual([]);+ });++ /**+ * `page.clock` controls the timers the cards are read from; it does not control the+ * document timeline the shimmer and the test ticks run on. So a suspension that only+ * stopped the React clock would leave those playing on unseen and reappearing+ * mid-sweep — which is why this asserts the RENDERED animation state, not the+ * attribute that requests it.+ */+ test('a hidden tab freezes what is drawn, and resuming does not skip', async ({ page }) => {+ await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES['codex-working']);+ const before = await renderedPhase(page);+ expect(await cssEffects(page)).not.toEqual([]);++ await setDocumentHidden(page, true);+ await expect(page.locator('.onboarding-collaboration')).toHaveAttribute('data-motion', 'paused');+ const stopped = await cssEffects(page);+ expect(stopped.every((effect) => effect.state === 'paused')).toBe(true);++ // Time passes while the tab is in the background, and nothing moves.+ await page.clock.runFor(3000);+ await page.waitForTimeout(250);+ expect(await cssEffects(page)).toEqual(stopped);+ expect(await renderedPhase(page)).toEqual(before);++ await setDocumentHidden(page, false);+ await expect(page.locator('.onboarding-collaboration')).toHaveAttribute('data-motion', 'running');+ // Resuming continues the same sweep: the phase is where it was left, not where+ // wall-clock time had carried it, and the CSS effects pick up their own timelines.+ expect(await renderedPhase(page)).toEqual(before);+ const resumed = await cssEffects(page);+ expect(resumed.some((effect) => effect.state === 'running')).toBe(true);++ // And it is genuinely running again, rather than merely unpaused.+ await freezeAt(page, PHASES['pm-summary'] - PHASES['codex-working']);+ expect(await renderedPhase(page)).not.toEqual(before);+ });++ /**+ * The other half of the same lifecycle. A hidden tab is not the only way a story goes+ * unwatched: at 390x300 the diagram and the button below it cannot share the screen, so+ * reading the button puts the whole composition above the viewport while the document+ * stays perfectly visible. Element visibility is what closes that, and `threshold: 0`+ * is what keeps a partly scrolled composition alive instead of stuttering at the seam.+ */+ test('a story scrolled out of sight suspends, and partial visibility does not', async ({ page }, info) => {+ const denied = await serveProduct(page);+ await page.setViewportSize({ width: 390, height: 300 });+ await openOnboarding(page);+ await freezeAt(page, PHASES['codex-working']);+ const diagram = page.locator('.onboarding-collaboration');+ const rect = () => diagram.evaluate((node) => {+ const found = node.getBoundingClientRect();+ return { top: Math.round(found.top), bottom: Math.round(found.bottom) };+ });+ // Whichever element actually scrolls here, the page or the shell inside it.+ const scrollBy = (delta: number) => page.evaluate((amount) => {+ const shell = document.querySelector('.onboarding-shell') as HTMLElement | null;+ const scroller = shell && shell.scrollHeight > shell.clientHeight ? shell : document.scrollingElement!;+ scroller.scrollTop += amount;+ }, delta);++ await page.locator('.onboarding-primary-action').scrollIntoViewIfNeeded();+ expect((await rect()).bottom).toBeLessThanOrEqual(0);+ expect(await page.evaluate(() => document.hidden)).toBe(false);+ await expect(diagram).toHaveAttribute('data-motion', 'paused');++ const before = await renderedPhase(page);+ const stopped = await cssEffects(page);+ expect(stopped.every((effect) => effect.state === 'paused')).toBe(true);+ await page.clock.runFor(3000);+ await page.waitForTimeout(250);+ expect(await renderedPhase(page)).toEqual(before);+ expect(await cssEffects(page)).toEqual(stopped);+ // The companion still for the design-frame crop: the CTA, reached by scrolling.+ await page.screenshot({ path: info.outputPath('scrolled-cta-390x300.png') });++ // Partly back: any intersecting pixel counts, so the story is live again at the seam.+ await scrollBy(-100);+ await page.waitForTimeout(150);+ const seam = await rect();+ expect(seam.top).toBeLessThan(0);+ expect(seam.bottom).toBeGreaterThan(0);+ await expect(diagram).toHaveAttribute('data-motion', 'running');++ // And it resumed rather than restarted or skipped: the phase is the one it was+ // holding, and it moves on from there once the clock runs again.+ expect(await renderedPhase(page)).toEqual(before);+ await freezeAt(page, PHASES['pm-summary'] - PHASES['codex-working']);+ expect(await renderedPhase(page)).not.toEqual(before);+ expect(denied).toEqual([]);+ });++ test('a reduced-motion preference draws the settled story and no pulse', async ({ page }, info) => {+ await serveProduct(page);+ await page.emulateMedia({ reducedMotion: 'reduce' });+ await openOnboarding(page);+ await expect(page.getByTestId('handoff-pulse')).toHaveCount(0);+ expect(await cssEffects(page)).toEqual([]);+ await page.screenshot({ path: info.outputPath('reduced-motion.png') });+ });+});++/**+ * The onboarding is the first screen a new install shows, so it is also the first place+ * the theme has to behave: follow the system when nothing was chosen, and keep an+ * explicit choice when the system disagrees with it.+ */+test.describe('theme', () => {+ test.use({ viewport: { width: 1200, height: 800 } });++ const themeState = (page: Page) => page.evaluate(() => ({+ attribute: document.documentElement.getAttribute('data-theme'),+ background: getComputedStyle(document.documentElement).getPropertyValue('--background').trim(),+ }));++ test('follows the system when no preference has been made', async ({ page }) => {+ await serveProduct(page);+ await page.emulateMedia({ colorScheme: 'dark' });+ await openOnboarding(page, { theme: null });+ const dark = await themeState(page);+ // A fresh install starts in system mode, which sets no attribute at all: the+ // stylesheet's own media query answers, and that is what lets the OS switch through+ // without a reload.+ expect(dark.attribute).toBeNull();++ await page.emulateMedia({ colorScheme: 'light' });+ const light = await themeState(page);+ expect(light.attribute).toBeNull();+ expect(light.background).not.toBe(dark.background);+ });++ test('keeps a stored preference when the system disagrees', async ({ page }) => {+ await serveProduct(page);+ await storeThemePreference(page, 'light');+ await page.emulateMedia({ colorScheme: 'dark' });+ await openOnboarding(page, { theme: null });+ const chosen = await themeState(page);+ expect(chosen.attribute).toBe('light');++ // The OS moving underneath a made choice must not take it away, in either direction.+ await page.emulateMedia({ colorScheme: 'light' });+ expect(await themeState(page)).toEqual(chosen);+ await page.emulateMedia({ colorScheme: 'dark' });+ expect(await themeState(page)).toEqual(chosen);+ await page.reload();+ await page.locator('.onboarding-collaboration').waitFor();+ expect((await themeState(page)).attribute).toBe('light');+ });++ /**+ * The active card's halo is the one effect the reference specifies per theme: a+ * spread-less 28px mint in dark, and light's own tighter 16/-4. It is asserted on the+ * rendered `box-shadow` because the token behind it is substituted into its utilities+ * at build time — reading the custom property would pass on a theme override that+ * compiles to nothing.+ */+ for (const [theme, geometry] of [['dark', '0px 0px 28px 0px'], ['light', '0px 0px 16px -4px']] as const) {+ test(`${theme} draws its own active-card halo, and idle cards none`, async ({ page }) => {+ await serveProduct(page);+ await openOnboarding(page, { theme });+ await freezeAt(page, PHASES['codex-working']);+ // The card fades its halo in over 650ms, so reading mid-transition measures the+ // interpolation rather than the design's value. Settling first asks for the value+ // the card actually arrives at.+ await settleEffects(page);++ const shadows = await page.locator('.onboarding-collaboration-card').evaluateAll((nodes) => nodes+ .map((node) => ({ active: node.getAttribute('data-active'), shadow: getComputedStyle(node).boxShadow })));+ const active = shadows.filter((card) => card.active === 'true');+ expect(active).toHaveLength(1);+ expect(active[0].shadow).toContain(geometry);+ // The glow is what says which card is working, so it cannot also be on the others.+ for (const card of shadows.filter((one) => one.active !== 'true')) expect(card.shadow).toBe('none');+ });+ }+});++test.describe('capture', () => {+ for (const viewport of VIEWPORTS) {+ for (const theme of ['dark', 'light'] as const) {+ for (const lang of ['en', 'zh'] as const) {+ // Settled stills: the clock is held at one named phase and every CSS effect is+ // held past its end, so two runs — or two themes — produce the same drawing and+ // it can be compared against a static frame. The phase is in the filename because+ // a still that does not say which moment it is cannot be compared with anything.+ test(`${size(viewport)} ${theme} ${lang}`, async ({ page }, info) => {+ await page.setViewportSize(viewport);+ await serveProduct(page);+ await openOnboarding(page, { lang, theme });+ await freezeAt(page, PHASES[CAPTURE_PHASE]);+ expect((await renderedPhase(page)).states).toEqual(CAPTURE_STATES);+ await settleEffects(page);+ await page.screenshot({ path: info.outputPath(`welcome-${size(viewport)}-${theme}-${lang}-${CAPTURE_PHASE}.png`), fullPage: true });+ await openSetup(page, lang);+ await settleEffects(page);+ await page.screenshot({ path: info.outputPath(`setup-${size(viewport)}-${theme}-${lang}.png`), fullPage: true });+ });+ }+ }+ }++ // The design's own content box, for overlaying an exported frame at 1:1. This still is+ // a VIEWPORT CROP, not the whole composition: at 756 the primary action sits below the+ // fold, which is the accepted outcome rather than a layout the product should shrink to+ // fit. The companion below shows it scrolled to, so the pair covers what one cannot.+ test('design frame content box', async ({ page }, info) => {+ await page.setViewportSize(DESIGN_FRAME);+ await serveProduct(page);+ await openOnboarding(page);+ await freezeAt(page, PHASES[CAPTURE_PHASE]);+ expect((await renderedPhase(page)).states).toEqual(CAPTURE_STATES);+ await settleEffects(page);+ await page.screenshot({ path: info.outputPath(`welcome-design-frame-1200x756-${CAPTURE_PHASE}.png`) });+ await page.locator('.onboarding-primary-action').scrollIntoViewIfNeeded();+ await expect(page.locator('.onboarding-primary-action')).toBeInViewport();+ await settleEffects(page);+ await page.screenshot({ path: info.outputPath(`welcome-design-frame-1200x756-cta-${CAPTURE_PHASE}.png`) });+ await openSetup(page, 'en');+ await settleEffects(page);+ await page.screenshot({ path: info.outputPath('setup-design-frame-1200x756.png') });+ });+});diff --git a/ui/e2e/onboarding-fidelity/loop.spec.ts b/ui/e2e/onboarding-fidelity/loop.spec.tsnew file mode 100644index 000000000..ae453cce3--- /dev/null+++ b/ui/e2e/onboarding-fidelity/loop.spec.ts@@ -0,0 +1,44 @@+import { writeFile } from 'node:fs/promises';+import { expect, test } from '@playwright/test';+import { openOnboarding, renderedPhase, serveProduct, setDocumentHidden } from './support';++/**+ * The loop at the speed it was authored at, with no clock control anywhere: a video of+ * one full 8.9s cycle plus a hide/show in the middle of it, and a sampled log of what+ * the page was actually drawing at each step. This is the moving evidence — every+ * capture in `geometry.spec.ts` is a settled still, and the two answer different+ * questions. It lives in its own file because recording video is a per-file option.+ */+test.use({ viewport: { width: 1200, height: 800 }, video: 'on' });++test('the story runs, suspends with the tab and resumes', async ({ page }, info) => {+ const denied = await serveProduct(page);+ await openOnboarding(page, { realTime: true });++ const samples: { at: number; hidden: boolean; phase: Awaited<ReturnType<typeof renderedPhase>> }[] = [];+ const started = Date.now();+ for (let step = 0; step < 14; step += 1) {+ if (step === 6) await setDocumentHidden(page, true);+ if (step === 9) await setDocumentHidden(page, false);+ const hidden = step >= 6 && step < 9;+ samples.push({ at: Date.now() - started, hidden, phase: await renderedPhase(page) });+ await page.waitForTimeout(800);+ }++ // The hidden samples are all the same frame: a background tab advances nothing.+ const dark = samples.filter((sample) => sample.hidden);+ for (const sample of dark) expect(sample.phase).toEqual(dark[0].phase);+ // Over a full loop every card is seen working and every card is seen complete, so the+ // recording really is of the whole cycle rather than one long phase.+ const states = samples.map((sample) => sample.phase.states);+ for (let card = 0; card < 3; card += 1) {+ expect(states.some((state) => state[card] === 'working')).toBe(true);+ expect(states.some((state) => state[card] === 'complete')).toBe(true);+ }+ // Written to the output directory rather than attached inline, so the log lands beside+ // the video as a file a reviewer can open without a Playwright HTML report.+ const log = info.outputPath('normal-speed-phases.json');+ await writeFile(log, `${JSON.stringify(samples, null, 2)}\n`);+ await info.attach('normal-speed-phases.json', { path: log, contentType: 'application/json' });+ expect(denied).toEqual([]);+});diff --git a/ui/e2e/onboarding-fidelity/support.ts b/ui/e2e/onboarding-fidelity/support.tsnew file mode 100644index 000000000..0d3c45cf9--- /dev/null+++ b/ui/e2e/onboarding-fidelity/support.ts@@ -0,0 +1,201 @@+import type { Page, Route } from '@playwright/test';++export const ORIGIN = 'http://127.0.0.1:5212';++/** Every phase of the authored 8.9s loop, addressed by the elapsed time it freezes at. */+export const PHASES = {+ 'pm-working': 600,+ 'handoff-to-codex': 1875,+ 'codex-working': 3000,+ 'handoff-to-opencode': 4125,+ 'tests-running': 5200,+ 'return-to-pm': 6500,+ 'pm-summary': 8000,+} as const;++export const VIEWPORTS = [+ { width: 1200, height: 800 },+ { width: 1440, height: 900 },+ { width: 1024, height: 768 },+ { width: 768, height: 1024 },+ { width: 390, height: 844 },+ { width: 320, height: 568 },+] as const;++export const size = ({ width, height }: { width: number; height: number }) => `${width}x${height}`;++const CONFIG = {+ platforms: { enabled: [] },+ agents: {+ claude: { enabled: true, cli_path: 'claude' },+ codex: { enabled: true, cli_path: 'codex' },+ opencode: { enabled: true, cli_path: 'opencode' },+ },+ agent: { default_cwd: '/fixture/work' },+ show_duration: false,+};++const CATALOG = {+ platforms: ['slack', 'discord', 'telegram', 'lark', 'wechat'].map((id) => ({ id, enabled: false })),+};++/**+ * Answers the product's reads locally and refuses everything else. Any request that+ * is not a same-origin GET — every write verb, and anything addressed off this+ * fixture's origin — is aborted and recorded, so a capture can prove it never+ * touched a running service or real user state.+ */+export async function serveProduct(page: Page) {+ const denied: string[] = [];+ await page.route('**/*', async (route: Route) => {+ const request = route.request();+ const method = request.method();+ if (request.url().startsWith(ORIGIN) && (method === 'GET' || method === 'HEAD')) return route.fallback();+ denied.push(`${method} ${request.url()}`);+ return route.abort();+ });+ await page.route('**/api/config', (route) => route.fulfill({ json: CONFIG }));+ await page.route('**/api/platforms', (route) => route.fulfill({ json: CATALOG }));+ await page.route('**/api/settings**', (route) => route.fulfill({ json: { channels: {} } }));+ await page.route('**/api/cli/detect**', (route) => {+ const binary = new URL(route.request().url()).searchParams.get('binary') ?? '';+ return route.fulfill({ json: { found: true, path: `/fixture/bin/${binary.split('/').pop()}` } });+ });+ // The setup step reads each assistant's runtime and OpenCode's permission flag. They+ // are answered as an installed, permitted runtime so the screen renders the state the+ // design describes rather than the error state a missing backend would produce.+ await page.route('**/api/backend/*/runtime', (route) => {+ const name = new URL(route.request().url()).pathname.split('/').at(-2);+ return route.fulfill({+ json: {+ ok: true,+ name,+ enabled: true,+ cli_path: name,+ resolved_path: `/fixture/bin/${name}`,+ installed: true,+ current_version: '1.0.0',+ latest_version: '1.0.0',+ has_update: false,+ supports_restart: true,+ process_status: 'running',+ },+ });+ });+ await page.route('**/api/opencode/permission-status', (route) =>+ route.fulfill({ json: { ok: true, permission_allowed: true } }),+ );+ return denied;+}++/**+ * Loads the fixture with a frozen clock so a phase can be held still for comparison.+ *+ * `realTime` leaves the clock alone, which is what a recording of the loop needs: the+ * story is meant to be watched at the speed it was authored at, and a frozen clock can+ * only ever show it one still at a time.+ */+/** Any fixed instant; the story reads elapsed time, so only determinism matters. */+const FIXED_TIME = new Date('2026-09-17T09:00:00Z');++export async function openOnboarding(+ page: Page,+ options: { lang?: string; theme?: string | null; realTime?: boolean } = {},+) {+ if (!options.realTime) {+ // `install` alone replaces the timers but leaves the clock ticking with real time,+ // so the story still lands wherever wall-clock time carried it between two runs —+ // which is how a dark and a light capture of "the same phase" end up different.+ // `pauseAt` is what actually holds it: afterwards only `freezeAt` moves it.+ await page.clock.install({ time: FIXED_TIME });+ await page.clock.pauseAt(FIXED_TIME);+ }+ const query = new URLSearchParams({ lang: options.lang ?? 'en' });+ // `theme: null` omits the parameter, which is the only way to watch the provider+ // choose for itself — the query overrides the stored preference by design.+ const theme = options.theme === undefined ? 'dark' : options.theme;+ if (theme !== null) query.set('theme', theme);+ await page.goto(`/e2e/onboarding-fidelity/fixture.html?${query}`);+ await page.locator('.onboarding-collaboration').waitFor();+}++/** Seeds the Web UI's own theme key, the way a user who once picked one leaves it. */+export function storeThemePreference(page: Page, mode: 'system' | 'light' | 'dark') {+ return page.addInitScript((value) => {+ window.localStorage.setItem('vibe-remote-theme', value);+ }, mode);+}++/** Which card the story is drawing, and what it says — the phase, as the page shows it. */+export function renderedPhase(page: Page) {+ return page.evaluate(() => {+ const cards = [...document.querySelectorAll('.onboarding-collaboration-card')];+ return {+ states: cards.map((card) => card.getAttribute('data-state') ?? ''),+ captions: cards.map((card) => card.querySelector('.onboarding-status-text')?.textContent?.trim() ?? ''),+ written: cards.map((card) => card.querySelectorAll('.onboarding-write-visible').length),+ pulse: document.querySelectorAll('[data-testid="handoff-pulse"]').length,+ };+ });+}++/** Advances the frozen clock to an exact elapsed time inside the loop. */+export async function freezeAt(page: Page, elapsed: number) {+ await page.clock.runFor(elapsed);+ await page.locator('.onboarding-collaboration-card[data-state]').first().waitFor();+}++/**+ * Holds every CSS animation at one point of its OWN timeline. `page.clock` controls+ * timers, which is what the story's clock is built from; it does not control the+ * document timeline the shimmer and the test ticks run on. A screenshot taken after+ * `freezeAt` alone therefore catches those wherever wall-clock time had carried them,+ * and two runs of the same phase differ. Seeking past a `both`-filled animation's+ * duration holds its end state, which is what a settled phase looks like — 1000ms+ * clears the longest of them (750ms shimmer, 340ms ticks at a 480ms last delay).+ */+export async function settleEffects(page: Page, at = 1000) {+ await page.evaluate((time) => {+ for (const animation of document.getAnimations()) {+ animation.currentTime = time;+ animation.pause();+ }+ }, at);+}++/**+ * What the CSS ANIMATIONS are actually doing, which is the state a DOM diff cannot see.+ * Transitions are deliberately left out: `document.getAnimations()` returns those too,+ * but a transition is finite and settles by itself, while an animation loops — so it is+ * the animations that would otherwise play on unseen in a background tab, and only they+ * that `animation-play-state` can hold.+ */+export function cssEffects(page: Page) {+ return page.evaluate(() => document.getAnimations()+ .filter((animation) => {+ if (!('animationName' in animation)) return false;+ // The onboarding's own motion, which is the whole of what its lifecycle owns.+ const target = (animation.effect as KeyframeEffect | null)?.target ?? null;+ return !!target?.closest('.onboarding-shell');+ })+ .map((animation) => ({+ name: String((animation as unknown as { animationName: string }).animationName),+ state: animation.playState,+ at: Math.round(Number(animation.currentTime ?? 0)),+ }))+ .sort((left, right) => `${left.name}${left.at}`.localeCompare(`${right.name}${right.at}`)));+}++/** Simulates the tab going to the background, which no Playwright API does directly. */+export async function setDocumentHidden(page: Page, hidden: boolean) {+ await page.evaluate((value) => {+ Object.defineProperty(document, 'hidden', { configurable: true, get: () => value });+ Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => (value ? 'hidden' : 'visible') });+ document.dispatchEvent(new Event('visibilitychange'));+ }, hidden);+}++export async function openSetup(page: Page, lang: string) {+ await page.getByRole('button', { name: lang === 'zh' ? '开始使用' : 'Get started' }).click();+ await page.locator('.onboarding-assistants').waitFor();+}diff --git a/ui/e2e/onboarding-fidelity/tsconfig.json b/ui/e2e/onboarding-fidelity/tsconfig.jsonnew file mode 100644index 000000000..a7b270eff--- /dev/null+++ b/ui/e2e/onboarding-fidelity/tsconfig.json@@ -0,0 +1,6 @@+{+ "extends": "../../tsconfig.app.json",+ "compilerOptions": { "types": ["vite/client", "node"] },+ "include": ["*.ts", "*.tsx", "../../playwright.onboarding-fidelity.config.ts", "../../agentation.d.ts"],+ "exclude": []+}diff --git a/ui/package.json b/ui/package.jsonindex d8a5cb2ca..43f65be41 100644--- a/ui/package.json+++ b/ui/package.json@@ -25,6 +25,7 @@"test:project-order": "tsc -p e2e/project-order/tsconfig.json --noEmit && playwright test --config playwright.project-order.config.ts","test:model-catalog": "tsc -p e2e/model-catalog/tsconfig.json --noEmit && playwright test --config playwright.model-catalog.config.ts","test:model-provider": "tsc -p e2e/model-provider/tsconfig.json --noEmit && playwright test --config playwright.model-provider.config.ts",+ "test:onboarding-fidelity": "tsc -p e2e/onboarding-fidelity/tsconfig.json --noEmit && playwright test --config playwright.onboarding-fidelity.config.ts","validate:catalog": "node scripts/validate-scenario-catalog.mjs","validate:theme": "node scripts/validate-theme.mjs"},diff --git a/ui/playwright.onboarding-fidelity.config.ts b/ui/playwright.onboarding-fidelity.config.tsnew file mode 100644index 000000000..493d98919--- /dev/null+++ b/ui/playwright.onboarding-fidelity.config.ts@@ -0,0 +1,18 @@+import { defineConfig, devices } from '@playwright/test';++// Hermetic: the dev server is bound to loopback and points at a dead backend port,+// and every request the page makes is answered or refused by the spec's own routes,+// so nothing here reaches a running Avibe service or writes to user state.+export default defineConfig({+ testDir: './e2e/onboarding-fidelity',+ outputDir: './e2e/.artifacts/onboarding-fidelity',+ workers: 1,+ retries: 0,+ use: { baseURL: 'http://127.0.0.1:5212', trace: 'retain-on-failure' },+ webServer: {+ command: 'npm run dev -- --host 127.0.0.1 --port 5212 --strictPort',+ env: { VIBE_UI_BACKEND: 'http://127.0.0.1:9' },+ url: 'http://127.0.0.1:5212/e2e/onboarding-fidelity/fixture.html',+ },+ projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],+});diff --git a/ui/scripts/glowScale.test.mjs b/ui/scripts/glowScale.test.mjsindex d641f346f..c92f8e87a 100644--- a/ui/scripts/glowScale.test.mjs+++ b/ui/scripts/glowScale.test.mjs@@ -68,7 +68,26 @@ const OFF_RULE = {},cta: {why: 'owner-set: themed blur (2026-08-14) and 0.6 alpha, not from design.pen',- holds: /^0 0 var\(--brand-glow-blur\) -4px rgba\(\d+, \d+, \d+, 0\.6\)$/,+ holds: /^0 0 \d+px -4px rgba\(\d+, \d+, \d+, 0\.6\)$/,+ },+ // The approved onboarding reference draws its active card with no spread at all+ // and at #5BFFA060, so the two fields the general rule fixes -- spread = -blur/4+ // and alpha 0.44 -- are the two this role is excused from, and `holds` pins both+ // at the reference's own numbers. Its blur is not excused: it is asserted from+ // ROLE_BLUR like every other role's, because a role is still a name for a size.+ //+ // Two patterns, because the two frames drew this card separately: Light's own+ // (waUhu) is 16/-4 at #10B98170, so the fields excused here are the ones that+ // differ. An exception that named one theme would have left the other+ // unasserted, which is this file's recurring failure shape -- so a themed+ // exception states BOTH themes, and a theme it says nothing about fails rather+ // than passing by default.+ onboarding: {+ why: 'the owner-approved active-card halo: spreadless #5BFFA060 in dark, and the light frame\'s own 16/-4 #10B98170',+ holds: {+ dark: /^0 0 \d+px 0px color-mix\(in srgb, var\(--[a-z]+\) 37\.6%, transparent\)$/,+ light: /^0 0 \d+px -4px color-mix\(in srgb, var\(--[a-z]+\) 44%, transparent\)$/,+ },},};@@ -77,8 +96,77 @@ const OFF_RULE = {// about which is 24 and which is 32, so swapping two rungs' blurs left every// assertion here green and every converted call site one rung off its frame.// A role is a name for a size; the mapping is the thing being asserted.+// A role whose size is themed names one size per theme instead of one size. That is+// not a softening: a single number still means "this blur in every theme", and a+// themed role must state every theme or `blurOf` returns undefined and the assertion+// fails. What it is NOT is an escape -- `onboarding` is pinned to 28 and 16, not+// excused from having a blur, and `cta` is pinned to 16 and 20 where it used to be+// excused entirely: "themed" was being read as "unasserted", so the owner's two+// numbers were the only blurs in this file that nothing checked.const ROLE_BLUR = {dot: 8, wire: 4, xs: 12, sm: 16, md: 24, lg: 32, xl: 48,+ cta: { dark: 16, light: 20 },+ onboarding: { dark: 28, light: 16 },+};++const blurOf = (role, theme) => {+ const blur = ROLE_BLUR[role];+ return typeof blur === 'number' ? blur : blur?.[theme];+};++// Every rung is read under both palettes, not under the block it is written in.+// That block is always `@theme`: the token layer is `@theme inline`, so Tailwind+// substitutes each value into its utilities at build time and `validate:theme`+// fails a later re-declaration of the same name as dead. Asking which theme a+// DECLARATION belongs to therefore has one answer for every glow in the tree, and+// the question worth asking is what the declaration draws once each palette has+// supplied its own numbers.+const THEMES = ['dark', 'light'];++// Which is how a glow is themed at all, since a value cannot be. A hue follows the+// palette on its own -- `color-mix(in srgb, var(--mint) …)` is whichever mint the+// theme declares -- but a blur is a number, and a number that has to change per+// theme has to be named and re-anchored where the palette is. `--brand-glow-blur`+// is that shape and `--onboarding-glow-*` follows it.+//+// So a rung is resolved through the numbers its theme declares before anything is+// asserted about it. Only the numbers: a colour name is left as written, because+// "this token's colour is that accent" is an assertion below and resolving it away+// would delete it. The whole-selector matching is the one `DARK_ACCENTS` explains+// -- a substring test reads `:root:not([data-theme="dark"])`, the light block whose+// entire job is to say it is not the dark one, as a dark declaration.+const NUMBER = /^-?[\d.]+(px|%)?$/;++const THEME_NUMBERS = (() => {+ const numbers = { dark: new Map(), light: new Map() };+ postcss.parse(CSS).walkRules((rule) => {+ let light = rule.selectors.some((one) => one.trim() === '[data-theme="light"]');+ for (let at = rule.parent; at && !light; at = at.parent) {+ light = at.type === 'atrule' && at.name === 'media' && /prefers-color-scheme:\s*light/.test(at.params);+ }+ const dark = !light && rule.selectors.some((one) => [':root', '[data-theme="dark"]'].includes(one.trim()));+ if (!light && !dark) return;++ for (const node of rule.nodes ?? []) {+ if (node.type !== 'decl' || !node.prop.startsWith('--') || !NUMBER.test(node.value.trim())) continue;+ numbers[light ? 'light' : 'dark'].set(node.prop, node.value.trim());+ }+ });++ // Light declares only what it changes, so it reads through dark for the rest --+ // the cascade, which is what the browser does with these two blocks.+ return { dark: numbers.dark, light: new Map([...numbers.dark, ...numbers.light]) };+})();++const resolveNumbers = (value, theme) => {+ let resolved = value.replace(/\s+/g, ' ').trim();+ for (let hop = 0; hop < 4; hop += 1) {+ const next = resolved.replace(/var\((--[\w-]+)\)/g, (written, name) =>+ THEME_NUMBERS[theme].get(name) ?? written);+ if (next === resolved) break;+ resolved = next;+ }+ return resolved;};const SPREAD_CAP = 12;@@ -102,7 +190,15 @@ const rungs = SHEETS.flatMap(([, sheet]) => {const found = [];sheet.walkDecls((decl) => {const match = RUNG_NAME.exec(decl.prop);- if (match) found.push({ ...match.groups, token: decl.prop, value: decl.value });+ // Every DECLARATION under every theme, not every name: reading one per name+ // would leave whichever came second unchecked -- the same "collected, marked+ // managed and discarded unread" hole the validator's own token layer had -- and+ // reading one theme per declaration leaves the other palette's numbers+ // unasserted, which is the same hole one level along.+ if (!match) return;+ for (const theme of THEMES) {+ found.push({ ...match.groups, theme, token: decl.prop, value: resolveNumbers(decl.value, theme) });+ }});return found;});@@ -184,12 +280,9 @@ describe('the accent glow scale', () => {expect(MANAGED.filter((token) => !rungs.some((rung) => rung.token === token))).toEqual([]);});- // And the role a name parses into has to be one the scale defines. `role in- // ROLE_BLUR` already decides which blur is asserted, but its else-branch --- // "then it must carry a themed blur" -- describes `cta`, so an invented role- // spelled with `var(--…)` would satisfy it. A role is a name for a size; a- // name for no size is not a role.- it.each(rungs)('$token names a role the scale defines', ({ role }) => {+ // And the role a name parses into has to be one the scale defines. A role is a+ // name for a size; a name for no size is not a role.+ it.each(rungs)('$token in $theme names a role the scale defines', ({ role }) => {expect(role in ROLE_BLUR || role in OFF_RULE, `${role} is on neither the blur scale nor the off-rule list`).toBe(true);});@@ -212,7 +305,7 @@ describe('the accent glow scale', () => {// status dot was unasserted in every theme. A token named for an accent that// draws a different one is the same defect as a blur off its frame, and it is// the harder one to see by eye.- it.each(rungs)('$token is its accent, as the dark theme declares it', ({ accent, value }) => {+ it.each(rungs)('$token in $theme is its accent, as the dark theme declares it', ({ accent, value }) => {const declared = DARK_ACCENTS.get(`--${accent}`);expect(declared, `--${accent} is declared in no [data-theme="dark"] block`).toBeDefined();expect([...declared], `--${accent} is declared more than once in dark`).toHaveLength(1);@@ -233,12 +326,16 @@ describe('the accent glow scale', () => {// A role is a name for a size, so the size is the assertion. Membership in a// set of blurs cannot see two roles trading values.- it.each(rungs)('$token has its role\'s blur', ({ role, value }) => {- if (!(role in ROLE_BLUR)) {- expect(value, `${role} has no fixed blur, so it must carry a themed one`).toMatch(/^0 0 var\(--[a-z-]+\) /);- return;- }- expect(Number(value.match(/^0 0 (\d+)px/)?.[1])).toBe(ROLE_BLUR[role]);+ //+ // Every role, with no branch for a themed one. That branch read "then it must+ // carry a themed blur", which described `cta` exactly -- and so accepted any+ // number at all behind the variable, including a role invented that morning.+ // Resolving a rung through its theme's own numbers is what removes the need for+ // it: a themed blur is a number by the time it gets here.+ it.each(rungs)('$token has its role\'s blur in $theme', ({ role, theme, value }) => {+ const blur = blurOf(role, theme);+ expect(blur, `${role} names no blur for the ${theme} theme it is declared in`).toBeDefined();+ expect(Number(value.match(/^0 0 (\d+)px/)?.[1])).toBe(blur);});it.each(Object.entries(OFF_RULE))('states why %s is off the rule', (role, { why }) => {@@ -248,8 +345,11 @@ describe('the accent glow scale', () => {// Every accent's token of an off-rule role, so a role is covered across the// palette rather than at whichever accent happens to be first.- it.each(rungs.filter((rung) => rung.role in OFF_RULE))('$token holds its documented exception', ({ role, value }) => {- expect(value.trim(), OFF_RULE[role].why).toMatch(OFF_RULE[role].holds);+ it.each(rungs.filter((rung) => rung.role in OFF_RULE))('$token holds its documented exception in $theme', ({ role, theme, value }) => {+ const { holds, why } = OFF_RULE[role];+ const pattern = holds instanceof RegExp ? holds : holds[theme];+ expect(pattern, `${role} states no exception for the ${theme} theme it is declared in`).toBeDefined();+ expect(value.trim(), why).toMatch(pattern);});// Which comments count as design glow annotations, and what each one measures.@@ -316,7 +416,8 @@ describe('the accent glow scale', () => {// scale the test pins and not whatever index.css currently happens to say.// Taking it from the file made the two agree by construction: a rung nudged// to 40px became "spellable" in the same edit that broke its frame.- const spellable = new Set(Object.values(ROLE_BLUR));+ const spellable = new Set(Object.values(ROLE_BLUR)+ .flatMap((blur) => (typeof blur === 'number' ? [blur] : Object.values(blur))));expect([...annotated].filter((blur) => !spellable.has(blur)).sort((a, b) => a - b)).toEqual([]);}, WHOLE_TREE_SCAN);diff --git a/ui/src/components/Wizard.tsx b/ui/src/components/Wizard.tsxindex a5c1c6ea6..b5fbb4bee 100644--- a/ui/src/components/Wizard.tsx+++ b/ui/src/components/Wizard.tsx@@ -22,7 +22,7 @@ import {collectWizardEnabledPlatformDelta,type WizardEnabledPlatformDelta,} from '../lib/wizardConfigMutations';-import { BrandLogo, WizardChrome } from './visual';+import { WizardChrome } from './visual';import { LanguageSwitcher } from './LanguageSwitcher';export const Wizard: React.FC = () => {@@ -245,8 +245,9 @@ export const Wizard: React.FC = () => {if (isWelcome || stepId === 'agents') {return (<div className="onboarding-shell">+ {/* The 2026-09-17 design drops the brand mark from the guidance screens+ ("这些引导页的logo都去掉"); the language switcher keeps the bar. */}<header>- <div className="flex items-center gap-2.5"><BrandLogo size={32} /><span className="text-sm font-semibold">Avibe</span></div><LanguageSwitcher /></header><main className="onboarding-shell-content">diff --git a/ui/src/components/onboarding/AccessTiles.tsx b/ui/src/components/onboarding/AccessTiles.tsxindex bc791bcec..b37b7a317 100644--- a/ui/src/components/onboarding/AccessTiles.tsx+++ b/ui/src/components/onboarding/AccessTiles.tsx@@ -1,17 +1,20 @@import { useEffect, useState } from 'react';-import { useReducedMotion } from 'framer-motion';import { useTranslation } from 'react-i18next';import { PlatformIcon } from '../visual';+import { useOnboardingMotion } from './motion';const PLATFORMS = ['avibe', 'slack', 'discord', 'telegram', 'lark', 'wechat'];-export function AccessTiles({ paused }: { paused: boolean }) {+export function AccessTiles() {const { t } = useTranslation();- const reducedMotion = useReducedMotion() === true;+ const { ref, running } = useOnboardingMotion();const [pointerInside, setPointerInside] = useState(false);const [focusInside, setFocusInside] = useState(false);const [emphasis, setEmphasis] = useState<number | null>(null);- const automatic = !paused && !reducedMotion && !pointerInside && !focusInside;+ // Same lifecycle as the story: a hidden tab, a reduced-motion preference, or these+ // tiles being scrolled out of sight stops the rotation; pointer and keyboard+ // interaction still yield the emphasis to the user.+ const automatic = running && !pointerInside && !focusInside;useEffect(() => {if (!automatic) return;const timer = window.setInterval(() => {@@ -22,7 +25,7 @@ export function AccessTiles({ paused }: { paused: boolean }) {}, [automatic]);return (- <section className="onboarding-access" aria-label={t('onboarding.access.label')}>+ <section ref={ref} className="onboarding-access" aria-label={t('onboarding.access.label')}><p>{t('onboarding.access.description')}</p><ul className="onboarding-access-grid" onPointerEnter={() => setPointerInside(true)} onPointerLeave={() => setPointerInside(false)}onFocus={() => setFocusInside(true)} onBlur={(event) => { if (!event.currentTarget.contains(event.relatedTarget)) setFocusInside(false); }}>diff --git a/ui/src/components/onboarding/CollaborationStory.tsx b/ui/src/components/onboarding/CollaborationStory.tsxindex f81e99693..e297170d9 100644--- a/ui/src/components/onboarding/CollaborationStory.tsx+++ b/ui/src/components/onboarding/CollaborationStory.tsx@@ -1,81 +1,178 @@-import { useEffect, useState } from 'react';-import { CodeXml, FileText, ListChecks, Pause, Play, RotateCcw } from 'lucide-react';+import { useEffect, useId, useState } from 'react';+import { Check, CodeXml, FileText, ListChecks } from 'lucide-react';import { useTranslation } from 'react-i18next';-import { useReducedMotion } from 'framer-motion';import { BackendIcon } from '../visual';-import { Button } from '../ui/button';import { Card } from '../ui/card';-import { ASSISTANT_ORDER, collaborationFrame } from './collaborationTimeline';+import { ASSISTANT_ORDER, WORK_LINES, collaborationFrame } from './collaborationTimeline';+import { useOnboardingMotion } from './motion';-export function CollaborationStory({ paused, onPausedChange }: {- paused: boolean;- onPausedChange: (paused: boolean) => void;-}) {+/** Wire geometry in the 880x272 collaboration box: two handoffs and the rounded return loop. */+const WIRES = [+ 'M240 118H320',+ 'M560 118H640',+ 'M760 228V246Q760 262 744 262H136Q120 262 120 246V228',+];+const PORTS: [number, number][] = [[240, 118], [320, 118], [560, 118], [640, 118], [760, 228], [120, 228]];+const ICONS = [FileText, CodeXml, ListChecks];+// Every skeleton line as its share of the block it is measured in, so the three cards+// draw the widths design_desktop.pen draws at any scale. The card's content box is 198+// wide; a document line is a share of that, a test line too (the checkbox and its gap+// are laid beside it, not out of it), and a code line is a share of the bar column that+// starts after the line number — which is why those two sets have different bases.+const DOCUMENT_BARS = [55.1, 94.9, 79.3, 36.9, 89.4, 65.7];+const CODE_INDENT = [0, 10, 20, 20, 10, 0];+const CODE_BARS: [number, number][] = [[24.3, 30.4], [18.1, 43.3], [29.2, 23], [21.7, 33.5], [31.6, 14.6], [14.4, 0]];+const TEST_BARS = [73.2, 61.6, 82.3, 54.5];++function Bar({ width, tone, revealed }: { width: number; tone?: string; revealed?: boolean }) {+ const reveal = revealed === undefined ? ''+ : `onboarding-write-line ${revealed ? 'onboarding-write-visible' : ''}`;+ return <span className={`onboarding-bar ${tone ?? ''} ${reveal}`} style={{ width: `${width}%` }} />;+}++/**+ * One ring stays mounted from the first frame of work through completion: it draws itself as the+ * work progresses, closes, and the check then grows from its hinge toward both ends.+ */+function WorkStatus({ active, done, progress }: { active: boolean; done: boolean; progress: number }) {+ return (+ <span className="onboarding-status-glyph" aria-hidden="true">+ {active || done ? (+ <svg className="onboarding-status-mark" viewBox="0 0 20 20" fill="none">+ <circle className="onboarding-status-ring" cx="10" cy="10" r="8" pathLength="1"+ transform="rotate(-90 10 10)" style={{ strokeDashoffset: done ? 0 : 1 - progress }} />+ {done && (+ <g className="onboarding-status-check">+ <path d="M8.5 12.5 5.5 9.5" />+ <path d="M8.5 12.5 14.5 6.5" />+ </g>+ )}+ </svg>+ ) : <span className="onboarding-status-dot" />}+ </span>+ );+}++function Skeleton({ backend, done, written }: { backend: string; done: boolean; written: number }) {+ if (backend === 'claude') {+ return (+ <div className="onboarding-skeleton onboarding-skeleton-document">+ <Bar width={DOCUMENT_BARS[0]} tone="onboarding-bar-heading" revealed={written > 0} />+ <Bar width={DOCUMENT_BARS[1]} revealed={written > 1} />+ <Bar width={DOCUMENT_BARS[2]} revealed={written > 2} />+ <div className="onboarding-skeleton-paragraph">+ <Bar width={DOCUMENT_BARS[3]} tone="onboarding-bar-subheading" revealed={written > 3} />+ <Bar width={DOCUMENT_BARS[4]} revealed={written > 4} />+ <Bar width={DOCUMENT_BARS[5]} revealed={written > 5} />+ </div>+ </div>+ );+ }+ if (backend === 'codex') {+ return (+ <div className="onboarding-skeleton onboarding-skeleton-code">+ {CODE_BARS.map(([first, second], line) => (+ <div key={line} className={`onboarding-code-row onboarding-write-line ${written > line ? 'onboarding-write-visible' : ''}`}>+ <span className="onboarding-code-number">{line + 1}</span>+ {/* The indent is geometry, not type, so it scales with the diagram. */}+ <div className="onboarding-code-bars" style={{ paddingLeft: `calc(${CODE_INDENT[line]} * var(--ob-u))` }}>+ <Bar width={first} tone={line % 2 ? 'onboarding-bar-violet' : 'onboarding-bar-cyan'} />+ <Bar width={second} />+ </div>+ </div>+ ))}+ </div>+ );+ }+ return (+ <div className={`onboarding-skeleton onboarding-skeleton-tests ${done ? 'onboarding-tests-done' : ''}`}>+ {TEST_BARS.map((width, line) => (+ <div key={line} className="onboarding-test-row" style={{ '--test-index': line } as React.CSSProperties}>+ <span className="onboarding-test-check"><Check size={10} strokeWidth={3} /></span>+ <Bar width={width} />+ </div>+ ))}+ </div>+ );+}++/** The wires are stretched to the card grid, so every coordinate stays proportional. */+function Circuit({ handoff }: { handoff: { wire: number; progress: number } | null }) {+ const glowId = useId();+ const pulse = handoff && {+ strokeDashoffset: 16 - 100 * handoff.progress,+ opacity: Math.max(0, Math.min(1, handoff.progress / 0.08, (1 - handoff.progress) / 0.06)),+ };+ return (+ <svg className="onboarding-wires" viewBox="0 0 880 272" fill="none" preserveAspectRatio="none" aria-hidden="true">+ <defs>+ <filter id={glowId} x="-100%" y="-500%" width="300%" height="1100%"><feGaussianBlur stdDeviation="3" /></filter>+ </defs>+ {WIRES.map((d, index) => (+ <g key={d}>+ <path className="onboarding-wire" d={d} />+ {handoff?.wire === index && (+ <g data-testid="handoff-pulse">+ <path className="onboarding-pulse-halo" d={d} pathLength={100} style={{ ...pulse, filter: `url(#${glowId})` }} />+ <path className="onboarding-pulse-core" d={d} pathLength={100} style={pulse ?? undefined} />+ </g>+ )}+ </g>+ ))}+ {PORTS.map(([x, y]) => <circle key={`${x}-${y}`} className="onboarding-port" cx={x} cy={y} r={3} />)}+ </svg>+ );+}++/** The design has no playback controls, so the loop starts with the screen and owns itself. */+export function CollaborationStory() {const { t } = useTranslation();- const reducedMotion = useReducedMotion() === true;+ const { ref, reducedMotion, running } = useOnboardingMotion();const [elapsed, setElapsed] = useState(0);useEffect(() => {- if (paused || reducedMotion) return;+ if (!running) return;let previous = performance.now();const timer = window.setInterval(() => {const now = performance.now();const delta = now - previous;previous = now;setElapsed((value) => value + delta);- }, 50);+ }, 16);return () => window.clearInterval(timer);- }, [paused, reducedMotion]);+ }, [running]);const frame = collaborationFrame(elapsed, reducedMotion);- const paths = ['M240 112 H320', 'M560 112 H640', 'M760 228 V260 H120 V228'];- const icons = [FileText, CodeXml, ListChecks];return (<section className="onboarding-story" aria-label={t('onboarding.story.label')}><p className="sr-only">{t('onboarding.story.description')}</p>- <div className="onboarding-collaboration" data-reduced-motion={reducedMotion}>- <svg className="onboarding-wires" viewBox="0 0 880 272" aria-hidden="true">- {paths.map((path) => <path key={path} d={path} fill="none" stroke="var(--border-strong)" />)}- {frame.handoff && !reducedMotion && (- <path data-testid="handoff-pulse" d={paths[frame.handoff.path]} fill="none"- stroke="var(--mint)" strokeWidth="2" pathLength="1" strokeDasharray="0.06 1"- strokeDashoffset={-frame.handoff.progress * 0.94} />- )}- </svg>+ {/* `data-motion` hands the same running state to the stylesheet: when the diagram+ is not being presented — the tab is hidden, or it has been scrolled out of+ sight — it holds every CSS animation inside at its current frame instead of+ letting it play on unseen against a stopped clock. The ref is what makes the+ second of those readable: it is this element's own visibility that decides. */}+ <div ref={ref} className="onboarding-collaboration" data-reduced-motion={reducedMotion}+ data-motion={running ? 'running' : 'paused'}>+ <Circuit handoff={frame.handoff} /><div className="onboarding-collaboration-cards">{ASSISTANT_ORDER.map((backend, index) => {- const progress = frame.progress[index];- const state = progress >= 1 ? 'complete' : progress > 0 ? 'working' : 'waiting';- const Icon = icons[index];- const phase = index === 0 && frame.summary ? 'summary' : state;+ const done = frame.done[index];+ const active = frame.active === index;+ const state = done ? 'complete' : active ? 'working' : 'waiting';+ const summary = index === 0 && frame.summary;+ const caption = summary ? t('onboarding.story.claude.summary')+ : t(`onboarding.story.${backend}.${done ? 'complete' : 'working'}`);+ const Icon = ICONS[index];return (- <Card key={backend} className="onboarding-collaboration-card" data-active={frame.active === index}+ <Card key={backend} className="onboarding-collaboration-card" data-active={active}data-state={state} aria-label={t(`onboarding.story.${backend}.name`)}><div className="onboarding-story-status" aria-hidden="true">- <Icon size={13} />- <span key={phase} className={paused ? '' : 'onboarding-status-copy'}>- {phase === 'summary' ? t('onboarding.story.claude.summary') : t(`onboarding.story.${backend}.${state}`)}+ <Icon size={13} strokeWidth={1.7} className="onboarding-status-icon" />+ <span key={caption} className="onboarding-status-text onboarding-status-enter">+ {caption}</span>- <svg viewBox="0 0 14 14" className="onboarding-status-glyph">- <circle cx="7" cy="7" r="2.5" fill="currentColor" opacity={state === 'waiting' ? 0.5 : 0} />- <circle cx="7" cy="7" r="5.5" fill="none" stroke="var(--mint)" strokeWidth="1.2"- pathLength="1" strokeDasharray="1" strokeDashoffset={1 - Math.min(1, progress * 1500 / 850)}- transform="rotate(-90 7 7)" />- <path d="m4.4 7 1.7 1.8 3.7-3.6" fill="none" stroke="var(--mint)" strokeWidth="1.3"- pathLength="1" strokeDasharray="1" strokeDashoffset={1 - Math.max(0, Math.min(1, (progress * 1500 - 850) / 300))} />- </svg>- </div>- <div className={`onboarding-skeleton onboarding-skeleton-${backend}`} aria-hidden="true">- {Array.from({ length: index === 2 ? 4 : 6 }, (_, line) => {- const revealed = progress >= (line + 1) / (index === 2 ? 4 : 6);- return (- <div key={line} className="onboarding-skeleton-row" style={{ opacity: revealed ? 1 : 0.2 }}>- {index === 1 && <span className="onboarding-code-number">{line + 1}</span>}- {index === 2 && <span className="onboarding-test-check">{revealed ? '✓' : ''}</span>}- <span className="onboarding-skeleton-line" style={{ width: `${[90, 75, 84, 62, 80, 68][line]}%` }} />- </div>- );- })}+ <WorkStatus active={active} done={done} progress={frame.progress[index]} /></div>+ <Skeleton backend={backend} done={done} written={reducedMotion ? WORK_LINES : frame.written[index]} /><div className="onboarding-story-identity"><BackendIcon backend={backend} size={28} variant="glyph" aria-hidden="true" /><strong>{t(`onboarding.story.${backend}.name`)}</strong>@@ -85,18 +182,10 @@ export function CollaborationStory({ paused, onPausedChange }: {);})}</div>- <p className="onboarding-story-caption">{t('onboarding.story.caption')}</p>+ <p className="onboarding-story-caption" data-returning={frame.returning}>+ {t(frame.returning ? 'onboarding.story.returnCaption' : 'onboarding.story.caption')}+ </p></div>- {!reducedMotion && (- <div className="onboarding-motion-controls">- <Button variant="ghost" size="icon" className="size-7" onClick={() => onPausedChange(!paused)}- aria-label={t(paused ? 'onboarding.story.play' : 'onboarding.story.pause')}>- {paused ? <Play size={12} /> : <Pause size={12} />}- </Button>- <Button variant="ghost" size="icon" className="size-7" onClick={() => { setElapsed(0); onPausedChange(false); }}- aria-label={t('onboarding.story.replay')}><RotateCcw size={12} /></Button>- </div>- )}</section>);}diff --git a/ui/src/components/onboarding/Welcome.test.tsx b/ui/src/components/onboarding/Welcome.test.tsxindex 62c473e2d..78e83a616 100644--- a/ui/src/components/onboarding/Welcome.test.tsx+++ b/ui/src/components/onboarding/Welcome.test.tsx@@ -15,8 +15,44 @@ vi.mock('../../context/ApiContext', () => ({ useApi: () => mocks.api }));const i18n = createInstance();await i18n.init({ lng: 'en', resources: { en: { translation: en }, zh: { translation: zh } }, interpolation: { escapeValue: false } });const wrap = (element: React.ReactNode) => <I18nextProvider i18n={i18n}>{element}</I18nextProvider>;++/** The tab going to the background, which jsdom exposes no other way. */+const setHidden = (hidden: boolean) => act(() => {+ Object.defineProperty(document, 'hidden', { configurable: true, get: () => hidden });+ Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => (hidden ? 'hidden' : 'visible') });+ document.dispatchEvent(new Event('visibilitychange'));+});++/**+ * The composition scrolling out of sight, which jsdom exposes no other way either: it+ * ships no IntersectionObserver at all. The stub keeps the real contract — observe an+ * element, report whether it intersects — and hands back a switch the test can flip.+ */+function stubIntersectionObserver() {+ const report: ((onScreen: boolean) => void)[] = [];+ class Stub {+ constructor(callback: IntersectionObserverCallback) {+ report.push((onScreen) => callback(+ [{ isIntersecting: onScreen } as IntersectionObserverEntry],+ this as unknown as IntersectionObserver,+ ));+ }+ observe() {}+ unobserve() {}+ disconnect() {}+ }+ vi.stubGlobal('IntersectionObserver', Stub);+ return (onScreen: boolean) => act(() => { for (const notify of report) notify(onScreen); });+}+beforeEach(() => { mocks.reduced = false; vi.clearAllMocks(); void i18n.changeLanguage('en'); });-afterEach(() => { cleanup(); vi.useRealTimers(); });+afterEach(() => {+ cleanup();+ vi.useRealTimers();+ vi.unstubAllGlobals();+ delete (document as Partial<Document>).hidden;+ delete (document as Partial<Document>).visibilityState;+});describe('Welcome', () => {it('checks saved paths before advancing without persisting configuration', async () => {@@ -47,40 +83,86 @@ describe('Welcome', () => {});});-describe('collaboration playback and access interaction', () => {- it('advances the pulse and freezes the entire state on pause', () => {+describe('collaboration lifecycle and access interaction', () => {+ it('starts on its own and offers no playback control', () => {vi.useFakeTimers();- const { container, rerender } = render(wrap(<CollaborationStory paused={false} onPausedChange={vi.fn()} />));+ const { container } = render(wrap(<CollaborationStory />));act(() => vi.advanceTimersByTime(1800));expect(screen.getByTestId('handoff-pulse')).toBeTruthy();expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(1);- rerender(wrap(<CollaborationStory paused onPausedChange={vi.fn()} />));- const before = container.innerHTML;+ // The approved design has no playback toolbar, so the story ships no control at all —+ // not a renamed one, not a hidden one, not a keyboard-only one.+ expect(container.querySelectorAll('button, [role="button"], input')).toHaveLength(0);+ });+ it('holds the story still while the tab is hidden and resumes in the same phase', () => {+ vi.useFakeTimers();+ const { container } = render(wrap(<CollaborationStory />));+ const diagram = () => container.querySelector('.onboarding-collaboration') as HTMLElement;+ act(() => vi.advanceTimersByTime(5000));+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);+ expect(diagram().dataset.motion).toBe('running');++ setHidden(true);+ // `data-motion` is what holds the rendered CSS animations; the cleared timer is what+ // holds the React frame. Both have to stop, or the diagram plays on against a clock+ // nobody is watching and jumps when the tab comes back.+ expect(diagram().dataset.motion).toBe('paused');+ expect(vi.getTimerCount()).toBe(0);+ const frozen = container.innerHTML;act(() => vi.advanceTimersByTime(3000));- expect(container.innerHTML).toBe(before);+ expect(container.innerHTML).toBe(frozen);++ setHidden(false);+ expect(diagram().dataset.motion).toBe('running');+ expect(vi.getTimerCount()).toBe(1);+ // Continuity, not restart: the 3000ms spent hidden would have carried the third card+ // past its completion, and a restart would have emptied all three.+ act(() => vi.advanceTimersByTime(100));+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);+ act(() => vi.advanceTimersByTime(400));+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(3);});- it('replays every card and pulse from the same beginning', () => {+ it('holds the story still while it is scrolled out of sight, with the tab still visible', () => {vi.useFakeTimers();- const resume = vi.fn();- const { container } = render(wrap(<CollaborationStory paused={false} onPausedChange={resume} />));+ const scroll = stubIntersectionObserver();+ const { container } = render(wrap(<CollaborationStory />));+ const diagram = () => container.querySelector('.onboarding-collaboration') as HTMLElement;act(() => vi.advanceTimersByTime(5000));expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);- fireEvent.click(screen.getByRole('button', { name: 'Replay animation' }));- expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(0);- expect(screen.queryByTestId('handoff-pulse')).toBeNull();- expect(resume).toHaveBeenCalledWith(false);+ expect(diagram().dataset.motion).toBe('running');++ // A hidden tab is only half the lifecycle. Here the document is perfectly visible+ // and it is the diagram that has left the screen — on a short window it can sit+ // entirely above the viewport while the user reads the button below it.+ scroll(false);+ expect(document.hidden).toBeFalsy();+ expect(diagram().dataset.motion).toBe('paused');+ expect(vi.getTimerCount()).toBe(0);+ const frozen = container.innerHTML;+ act(() => vi.advanceTimersByTime(3000));+ expect(container.innerHTML).toBe(frozen);++ scroll(true);+ expect(diagram().dataset.motion).toBe('running');+ expect(vi.getTimerCount()).toBe(1);+ // Continuity, not restart, exactly as for the hidden tab above.+ act(() => vi.advanceTimersByTime(100));+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);+ act(() => vi.advanceTimersByTime(400));+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(3);});it('shows completed work and stops all timers for reduced motion', () => {vi.useFakeTimers(); mocks.reduced = true;const { container } = render(wrap(<Welcome onNext={vi.fn()} />));expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(3);expect(screen.queryByTestId('handoff-pulse')).toBeNull();- expect(screen.queryByRole('button', { name: 'Pause animation' })).toBeNull();+ // Get started is the only button on the screen.+ expect(screen.getAllByRole('button').map((node) => node.textContent?.trim())).toEqual(['Get started']);expect(vi.getTimerCount()).toBe(0);});it('pauses idle emphasis throughout pointer and keyboard interaction', () => {vi.useFakeTimers();- const { container } = render(wrap(<AccessTiles paused={false} />));+ const { container } = render(wrap(<AccessTiles />));act(() => vi.advanceTimersByTime(2000));expect(container.querySelectorAll('[data-emphasis="true"]')).toHaveLength(1);fireEvent.pointerEnter(screen.getByRole('list'));@@ -92,4 +174,28 @@ describe('collaboration playback and access interaction', () => {fireEvent.blur(screen.getAllByRole('listitem')[0], { relatedTarget: null });expect(vi.getTimerCount()).toBe(1);});+ it('stops the access rotation with the tab and keeps it stopped for reduced motion', () => {+ vi.useFakeTimers();+ const { container } = render(wrap(<AccessTiles />));+ act(() => vi.advanceTimersByTime(2000));+ expect(container.querySelectorAll('[data-emphasis="true"]')).toHaveLength(1);+ setHidden(true);+ expect(vi.getTimerCount()).toBe(0);+ expect(container.querySelectorAll('[data-emphasis="true"]')).toHaveLength(0);+ setHidden(false);+ expect(vi.getTimerCount()).toBe(1);+ });+ it('stops the access rotation when the tiles themselves scroll out of sight', () => {+ vi.useFakeTimers();+ const scroll = stubIntersectionObserver();+ const { container } = render(wrap(<AccessTiles />));+ act(() => vi.advanceTimersByTime(2000));+ expect(vi.getTimerCount()).toBe(1);+ scroll(false);+ expect(vi.getTimerCount()).toBe(0);+ scroll(true);+ expect(vi.getTimerCount()).toBe(1);+ // The rotation is what suspends; the six tiles it rotates through are always there.+ expect(container.querySelectorAll('.onboarding-access-tile')).toHaveLength(6);+ });});diff --git a/ui/src/components/onboarding/collaborationTimeline.test.ts b/ui/src/components/onboarding/collaborationTimeline.test.tsindex b53b161af..c73fb5c42 100644--- a/ui/src/components/onboarding/collaborationTimeline.test.ts+++ b/ui/src/components/onboarding/collaborationTimeline.test.ts@@ -1,25 +1,49 @@import { describe, expect, it } from 'vitest';-import { collaborationFrame } from './collaborationTimeline';+import { COLLABORATION_DURATION, WORK_LINES, collaborationFrame } from './collaborationTimeline';describe('one collaboration clock', () => {it('keeps the source active until each pulse arrives', () => {- for (const [start, end, source, destination, path] of [[1500, 2250, 0, 1, 0], [3750, 4500, 1, 2, 1], [6000, 7000, 2, 0, 2]]) {- expect(collaborationFrame(start)).toMatchObject({ active: source, handoff: { path, progress: 0 } });+ for (const [start, end, source, destination, wire] of [[1500, 2250, 0, 1, 0], [3750, 4500, 1, 2, 1]]) {+ expect(collaborationFrame(start)).toMatchObject({ active: source, handoff: { wire, progress: 0 } });expect(collaborationFrame(end - 1).active).toBe(source);expect(collaborationFrame(end)).toMatchObject({ active: destination, handoff: null });expect(collaborationFrame(end).progress[destination]).toBe(0);}});- it('finishes each card in 1.5 seconds and repeats the entire story together', () => {+ it('travels one wire at a time and shows no pulse while a card works', () => {+ expect(collaborationFrame(2600).handoff).toBeNull();+ expect(collaborationFrame(1875).handoff).toEqual({ wire: 0, progress: 0.5 });+ expect(collaborationFrame(6500).handoff).toEqual({ wire: 2, progress: 0.5 });+ });+ it('writes the skeleton line by line before the card reports complete', () => {+ expect(collaborationFrame(2250).written[1]).toBe(0);+ expect(collaborationFrame(2400).written[1]).toBe(2);+ expect(collaborationFrame(2900).written[1]).toBe(WORK_LINES);+ expect(collaborationFrame(2900).done[1]).toBe(false);+ expect(collaborationFrame(3100)).toMatchObject({ active: 1, done: [true, true, false] });+ });+ it('keeps finished work on screen while the result returns to the PM', () => {+ expect(collaborationFrame(6500)).toMatchObject({ done: [true, true, true], written: [WORK_LINES, WORK_LINES, WORK_LINES], returning: true, summary: false });+ expect(collaborationFrame(8500)).toMatchObject({ active: 0, progress: [1, 1, 1], written: [WORK_LINES, WORK_LINES, WORK_LINES], summary: true, returning: true });+ });+ it('finishes each card inside its own step and repeats the entire story together', () => {expect(collaborationFrame(1500).progress[0]).toBe(1);expect(collaborationFrame(3750).progress[1]).toBe(1);expect(collaborationFrame(6000).progress).toEqual([1, 1, 1]);- expect(collaborationFrame(8500)).toMatchObject({ progress: [1, 1, 1], summary: true });+ expect(COLLABORATION_DURATION).toBe(8900);expect(collaborationFrame(8900)).toEqual(collaborationFrame(0));});- it('shows a completed collaboration with no pulse or active card in reduced motion', () => {+ it('shows the completed collaboration with no pulse in reduced motion', () => {for (const elapsed of [0, 1750, 4000, 6500, 8900]) {- expect(collaborationFrame(elapsed, true)).toEqual({ active: null, handoff: null, progress: [1, 1, 1], summary: true });+ expect(collaborationFrame(elapsed, true)).toEqual({+ active: 0,+ handoff: null,+ progress: [1, 1, 1],+ done: [true, true, true],+ written: [WORK_LINES, WORK_LINES, WORK_LINES],+ summary: true,+ returning: true,+ });}});});diff --git a/ui/src/components/onboarding/collaborationTimeline.ts b/ui/src/components/onboarding/collaborationTimeline.tsindex d80b5c3c8..9e05446fd 100644--- a/ui/src/components/onboarding/collaborationTimeline.ts+++ b/ui/src/components/onboarding/collaborationTimeline.ts@@ -1,16 +1,71 @@-export const COLLABORATION_DURATION = 8900;export const ASSISTANT_ORDER = ['claude', 'codex', 'opencode'] as const;export type AssistantId = typeof ASSISTANT_ORDER[number];+/**+ * The authored relay from the approved Welcome design: each assistant works for+ * 1500ms, each handoff travels its wire, and the closing summary returns to the PM.+ * A step keeps its SOURCE active while the pulse is in transit; the destination+ * only activates once the pulse lands.+ */+const RELAY = [+ { id: 'claude', active: 0, duration: 1500 },+ { id: 'to-codex', active: 0, duration: 750, wire: 0 },+ { id: 'codex', active: 1, duration: 1500 },+ { id: 'to-opencode', active: 1, duration: 750, wire: 1 },+ { id: 'opencode', active: 2, duration: 1500 },+ { id: 'to-claude', active: 2, duration: 1000, wire: 2 },+ { id: 'summary', active: 0, duration: 1900 },+] as const;++export const COLLABORATION_STEPS = RELAY.map((step, index) => {+ const start = RELAY.slice(0, index).reduce((total, previous) => total + previous.duration, 0);+ return { ...step, start, end: start + step.duration };+});+export const COLLABORATION_DURATION = COLLABORATION_STEPS[COLLABORATION_STEPS.length - 1].end;++/** Each card fills its skeleton in 850ms; the rest of its turn holds the completed state. */+export const WORK_CONTENT_DURATION = 850;+/** Both the document and the code skeleton reveal six lines, 110ms apart. */+export const WORK_LINES = 6;+const WORK_STARTS = ASSISTANT_ORDER.map((_, index) => COLLABORATION_STEPS[index * 2].start);++const clamp = (value: number) => Math.max(0, Math.min(1, value));++export interface CollaborationFrame {+ /** Index of the card that currently owns the work, or null when nothing is running. */+ active: number | null;+ /** Wire index the pulse is travelling, with its 0..1 position along that wire. */+ handoff: { wire: number; progress: number } | null;+ /** Skeleton fill 0..1 per card. */+ progress: number[];+ /** Completed work stays complete for the rest of the cycle, including the summary. */+ done: boolean[];+ /** Revealed skeleton lines per card. */+ written: number[];+ /** The closing phase, where the PM summarizes instead of restating its own work. */+ summary: boolean;+ /** True while the result is travelling back to, or being summarized by, the PM. */+ returning: boolean;+}+/** All cards and traveling pulses are projections of this one clock. */-export function collaborationFrame(elapsed: number, reducedMotion = false) {- const time = reducedMotion ? COLLABORATION_DURATION : elapsed % COLLABORATION_DURATION;- const starts = [time >= 7000 ? 7000 : 0, 2250, 4500];- const progress = starts.map((start) => Math.min(1, Math.max(0, (time - start) / 1500)));- const active = reducedMotion ? null : time < 2250 ? 0 : time < 4500 ? 1 : time < 7000 ? 2 : 0;- const handoff = time >= 1500 && time < 2250 ? { path: 0, progress: (time - 1500) / 750 }- : time >= 3750 && time < 4500 ? { path: 1, progress: (time - 3750) / 750 }- : time >= 6000 && time < 7000 ? { path: 2, progress: (time - 6000) / 1000 }- : null;- return { active, progress, handoff, summary: time >= 7000 };+export function collaborationFrame(elapsed: number, reducedMotion = false): CollaborationFrame {+ const time = reducedMotion ? COLLABORATION_DURATION - 1 : elapsed % COLLABORATION_DURATION;+ const step = COLLABORATION_STEPS.find((candidate) => time < candidate.end)+ ?? COLLABORATION_STEPS[COLLABORATION_STEPS.length - 1];+ const worked = WORK_STARTS.map((start) => time - start);+ const done = worked.map((value) => reducedMotion || value >= WORK_CONTENT_DURATION);+ return {+ active: step.active,+ handoff: 'wire' in step && !reducedMotion+ ? { wire: step.wire, progress: clamp((time - step.start) / step.duration) }+ : null,+ progress: worked.map((value, index) => (done[index] ? 1 : clamp(value / WORK_CONTENT_DURATION))),+ done,+ written: worked.map((value, index) => (done[index] ? WORK_LINES+ : step.active === index ? Math.max(0, Math.min(WORK_LINES, Math.floor((value - 40) / 110) + 1))+ : 0)),+ summary: step.id === 'summary',+ returning: step.id === 'to-claude' || step.id === 'summary',+ };}diff --git a/ui/src/components/onboarding/motion.ts b/ui/src/components/onboarding/motion.tsnew file mode 100644index 000000000..37a6186fa--- /dev/null+++ b/ui/src/components/onboarding/motion.ts@@ -0,0 +1,68 @@+import { useEffect, useState } from 'react';+import { useReducedMotion } from 'framer-motion';++/**+ * Whether the document is being presented at all. An interval keeps firing in a+ * background tab — throttled, so its deltas arrive in one lump — and a CSS+ * animation keeps its own timeline running there too. Reading visibility here is+ * what lets both stop together.+ */+function useDocumentVisible() {+ const [visible, setVisible] = useState(() => typeof document === 'undefined' || !document.hidden);+ useEffect(() => {+ const read = () => setVisible(!document.hidden);+ read();+ document.addEventListener('visibilitychange', read);+ return () => document.removeEventListener('visibilitychange', read);+ }, []);+ return visible;+}++/**+ * Whether this particular composition is on screen. A hidden tab is only half the+ * question: on a short window the diagram can sit entirely above the viewport while+ * the document is perfectly visible, and its clock and CSS effects would keep running+ * for nobody. `threshold: 0` is the same reading the incumbent observer in+ * `vault-chat-requests` takes — any intersecting pixel counts — so a composition that+ * is only partly scrolled in stays live rather than stuttering at the edge.+ *+ * Without an element or without the API (jsdom) this answers "on screen", so a+ * consumer that never attaches the ref keeps the behaviour it had before. Nothing+ * resets it when the effect cannot observe: an observer reports the element's current+ * intersection as soon as it starts watching, so the only unobserved state that+ * outlives the initial one is the element going away, and that is the unmount.+ */+function useElementOnScreen() {+ const [element, setElement] = useState<HTMLElement | null>(null);+ const [onScreen, setOnScreen] = useState(true);+ useEffect(() => {+ if (!element || typeof IntersectionObserver === 'undefined') return;+ const observer = new IntersectionObserver(+ ([entry]) => setOnScreen(entry.isIntersecting),+ { threshold: 0 },+ );+ observer.observe(element);+ return () => observer.disconnect();+ }, [element]);+ return [setElement, onScreen] as const;+}++/**+ * The one answer to "is this onboarding animation running", used by the story and the+ * access tiles so a reduced-motion preference, a hidden tab and being scrolled out of+ * sight all stop it the same way. Each consumer attaches the returned `ref` to the+ * element it draws in, so the two suspend independently: at desktop sizes both are+ * normally on screen together, but on a short or narrow window they can have different+ * viewport intersection, and each should answer for its own. There is no user-facing+ * control here on purpose: the+ * approved design has no playback toolbar, so this is lifecycle only. `running` also+ * drives the diagram's `data-motion` attribute, which is how the CSS-owned effects (the+ * skeleton shimmer and the test ticks) are held at their current frame rather than left+ * to play on against a stopped clock.+ */+export function useOnboardingMotion() {+ const reducedMotion = useReducedMotion() === true;+ const documentVisible = useDocumentVisible();+ const [ref, onScreen] = useElementOnScreen();+ return { ref, reducedMotion, running: !reducedMotion && documentVisible && onScreen };+}diff --git a/ui/src/components/onboarding/onboarding.css b/ui/src/components/onboarding/onboarding.cssindex d5971f80c..388b221bd 100644--- a/ui/src/components/onboarding/onboarding.css+++ b/ui/src/components/onboarding/onboarding.css@@ -1,118 +1,641 @@+/* Onboarding surface — Welcome and assistant setup.+ *+ * Geometry, fills and motion follow `avibe-docs/design_desktop.pen` and the authored+ * animation in Show session `ses36vg559de2`. The values below are component-scoped on+ * purpose: they encode exact approved design numbers without moving any global token.+ *+ * Widths are capped fluid, never fixed: the card grid uses percentage tracks and the+ * diagram is sized from its own width, so card width, handoff gaps, diagram height and+ * the stretched wire viewBox stay proportional at every container width. The owner+ * accepted 1104 as the desktop cap; only the narrow bands choose a height directly.+ */.onboarding-shell {+ --ob-card: linear-gradient(150deg, #151521, #101019);+ --ob-card-border: #ffffff1c;+ --ob-active-border: #5bffa059;+ /* The reference's own exterior glow — a 28px, spread-less mint at #5BFFA060 — now+ carried by one managed token instead of approximated by stacking two rungs of the+ sized scale. The inset line is only the top highlight, not the glow. */+ --ob-active-shadow: var(--shadow-glow-onboarding-mint), inset 0 1px 0 #5bffa012;+ --ob-idle-dot: #4c5060;+ --ob-skeleton: #ffffff12;+ --ob-skeleton-strong: #ffffff28;+ --ob-shimmer-soft: #ffffff08;+ --ob-shimmer: #ffffff16;+ --ob-line-number: #585c71;+ --ob-code-violet: #a496e15c;+ --ob-code-cyan: #67c2b75c;+ --ob-check-bg: #ffffff05;+ --ob-check-border: #5bffa044;+ --ob-check-done: #5bffa012;+ --ob-identity-line: #ffffff0e;+ --ob-wire: #5bffa031;+ --ob-port: #15281f;+ --ob-port-border: #5bffa066;+ --ob-pulse: #b5ffd4;+ --ob-pulse-glow: #5bffa0;+ --ob-caption: #697087;+ --ob-tile-bg: #ffffff03;+ --ob-tile-hover: #ffffff0a;+ --ob-well: #ffffff04;+ --ob-tile-label: #d3d7e2;++ /* One content width for the header, the story and the assistant rows. 1104 is the+ setup frame's own container (i3vw9 lays it out at x=48 of a 1200 frame); the owner+ accepted it for the welcome too, whose blocks are authored at 880. Every dependent+ number is therefore expressed as its ratio to 880 rather than re-typed: the cap+ alone moves the whole composition and nothing can drift out of proportion.+ At 1104 that yields 301.1 cards, a 1104x341.2 diagram and an 802.9 access span. */+ --ob-content-w: 1104px;+ /* 20px shell padding plus this bar is the setup's authored 64.5 top offset (IWQi6),+ which it holds at every window height. The welcome is centred instead and reaches+ the same 65 only at the design's own 756 content box. */+ --ob-header-h: 45px;+ /* The design's own side padding, so the cap is reached at exactly its 1200 frame. */+ --ob-gutter: 48px;+background: var(--background);color: var(--foreground);height: var(--app-shell-h);overflow-y: auto;- padding: 20px 24px;+ display: flex;+ flex-direction: column;+ padding: 20px var(--ob-gutter);+}+@media (prefers-color-scheme: light) {+ :root:not([data-theme="dark"]) .onboarding-shell { --ob-theme: light; }+}+[data-theme="light"] .onboarding-shell { --ob-theme: light; }+/* Both light blocks must stay value-identical, like the global theme's own pair. */+@media (prefers-color-scheme: light) {+ :root:not([data-theme="dark"]) .onboarding-shell {+ --ob-card: #ffffff;+ --ob-card-border: #08081212;+ /* The light frame's own active card (waUhu): a #10B98160 edge over a 16/-4+ #10B98170 halo, and no inset highlight — that top line is the dark card's+ lit rim, and on white it reads as a seam. The halo is the same managed+ token as dark; the token itself is what carries light's geometry. */+ --ob-active-border: #10b98160;+ --ob-active-shadow: var(--shadow-glow-onboarding-mint);+ --ob-idle-dot: #5c6079;+ --ob-skeleton: #08081214;+ --ob-skeleton-strong: #08081224;+ --ob-shimmer-soft: #08081204;+ --ob-shimmer: #08081208;+ --ob-line-number: #5c6079;+ --ob-code-violet: #7c3aed24;+ --ob-code-cyan: #0891b224;+ --ob-check-bg: #eef1f7;+ --ob-check-border: #aae6d2;+ --ob-check-done: #10b98114;+ --ob-identity-line: #08081214;+ --ob-wire: #10b98124;+ --ob-port: #10b98124;+ --ob-port-border: #aae6d2;+ /* Light keeps a light mint pulse; a darker green read as a smear on white. */+ --ob-pulse: #6ee7b7;+ --ob-pulse-glow: #5bffa080;+ --ob-caption: #5c6079;+ --ob-tile-bg: #ffffff;+ --ob-tile-hover: #0808120a;+ --ob-well: #eef1f780;+ --ob-tile-label: #0a0a14;+ }}+[data-theme="light"] .onboarding-shell {+ --ob-card: #ffffff;+ --ob-card-border: #08081212;+ /* waUhu's edge and halo — see the prefers-color-scheme block above. */+ --ob-active-border: #10b98160;+ --ob-active-shadow: var(--shadow-glow-onboarding-mint);+ --ob-idle-dot: #5c6079;+ --ob-skeleton: #08081214;+ --ob-skeleton-strong: #08081224;+ --ob-shimmer-soft: #08081204;+ --ob-shimmer: #08081208;+ --ob-line-number: #5c6079;+ --ob-code-violet: #7c3aed24;+ --ob-code-cyan: #0891b224;+ --ob-check-bg: #eef1f7;+ --ob-check-border: #aae6d2;+ --ob-check-done: #10b98114;+ --ob-identity-line: #08081214;+ --ob-wire: #10b98124;+ --ob-port: #10b98124;+ --ob-port-border: #aae6d2;+ --ob-pulse: #6ee7b7;+ --ob-pulse-glow: #5bffa080;+ --ob-caption: #5c6079;+ --ob-tile-bg: #ffffff;+ --ob-tile-hover: #0808120a;+ --ob-well: #eef1f780;+ --ob-tile-label: #0a0a14;+}+.onboarding-shell > header {display: flex;align-items: center;- justify-content: space-between;- max-width: 1104px;+ justify-content: flex-end;+ flex-shrink: 0;+ height: var(--ob-header-h);+ max-width: var(--ob-content-w);+ width: 100%;margin: 0 auto;}+/* `1 0 auto`: this box is never shorter than what it holds, so a composition taller+ than the window pushes the shell into its own scroll rather than being clipped above+ the fold — and centring a child inside it can never push that child off the top. */.onboarding-shell-content {+ flex: 1 0 auto;display: flex;- align-items: center;- min-height: calc(100% - 44px);- padding: 28px 0;+ align-items: flex-start;+ justify-content: center;}+/* The two steps are anchored differently because the design anchors them differently.+ JuwcG and KIxnF centre the welcome in their frame; IWQi6 tops the setup out at its+ own 64.5 padding. So the welcome's y is a RESULT of the window height — it is 65 at+ the design's own 756 content box and lower in a taller one — while the setup's is the+ position itself. Whichever is taller than the window scrolls from its top edge. */+.onboarding-welcome { align-self: center; }.onboarding-welcome, .onboarding-setup {display: flex;flex-direction: column;align-items: center;width: 100%;- max-width: 880px;+ max-width: var(--ob-content-w);margin: 0 auto;gap: 24px;}.onboarding-heading { text-align: center; width: 100%; }+/* The live design's headline: 34/1.35/600 at -1.6 tracking (nodes XKQOx, Igagh and+ hv9DA all agree), shared by the welcome and the setup title. */.onboarding-heading h1, .onboarding-heading h2 {font-size: 34px;+ line-height: 1.35;font-weight: 600;- line-height: 1.2;- letter-spacing: -0.5px;+ letter-spacing: -1.6px;+}+.onboarding-heading p { margin-top: 10px; font-size: 14px; line-height: 22px; color: var(--muted); }++/* ---- Collaboration story ------------------------------------------------ */++.onboarding-story { position: relative; width: 100%; display: flex; align-items: flex-start; justify-content: center; }+.onboarding-collaboration {+ position: relative;+ width: 100%;+ max-width: var(--ob-content-w);+ /* The diagram is sized from its own width, so the authored 880x272 proportion holds+ at every width up to the cap, where it is the approved 1104x341.2. Narrow bands+ set an explicit height instead: wrapped labels need more room than the proportion. */+ aspect-ratio: 880 / 272;+ height: var(--ob-diagram-h, auto);+ container-type: inline-size;+}+.onboarding-collaboration-cards {+ display: grid;+ grid-template-columns: repeat(3, minmax(0, 27.272727%));+ justify-content: space-between;+ /* The cards occupy 228 of the 272 rows; the rest is the return wire's band. */+ height: calc(100% * 228 / 272);+ position: relative;+ z-index: 1;+ /* One design unit: the frames are drawn on an 880 box, so everything the card draws+ is written as its authored number times this unit and stays proportional as the+ diagram grows to the cap. Text and icons keep their own sizes on purpose — a card+ that is a quarter taller should not read as a zoomed screenshot. */+ --ob-u: calc(100cqw / 880);}-.onboarding-heading p { margin-top: 10px; font-size: 14px; color: var(--muted); }-.onboarding-story { position: relative; width: 100%; }-.onboarding-collaboration { position: relative; padding-bottom: 44px; }-.onboarding-collaboration-cards { display: flex; justify-content: space-between; gap: 24px; }.onboarding-collaboration-card {- flex: 0 1 240px;+ display: flex;+ flex-direction: column;+ height: 100%;min-width: 0;- height: 228px;- border-radius: 16px;- padding: 18px 20px;- background: linear-gradient(150deg, var(--surface-2), var(--surface));- transition: border-color 180ms, box-shadow 180ms;-}-.onboarding-collaboration-card[data-active="true"], .onboarding-assistant:hover, .onboarding-assistant:focus-within {- border-color: color-mix(in srgb, var(--mint) 34%, transparent);- box-shadow: var(--shadow-glow-lg-mint);-}-.onboarding-wires { position: absolute; inset: 0; width: 100%; height: 272px; pointer-events: none; }-.onboarding-story-status { display: flex; align-items: center; gap: 7px; font-size: 10px; height: 14px; color: var(--muted); }-.onboarding-story-status > span { flex: 1; white-space: nowrap; }-.onboarding-status-glyph { width: 14px; height: 14px; flex-shrink: 0; }-.onboarding-status-copy { animation: onboarding-status-in 250ms ease-out; }-@keyframes onboarding-status-in { from { opacity: 0; } to { opacity: 1; } }-.onboarding-skeleton { height: 134px; padding-top: 22px; display: flex; flex-direction: column; gap: 10px; }-.onboarding-skeleton-row { display: flex; align-items: center; gap: 10px; height: 7px; }-.onboarding-skeleton-line { display: block; height: 6px; border-radius: 3px; background: color-mix(in srgb, var(--foreground) 12%, transparent); }-.onboarding-skeleton-claude .onboarding-skeleton-row:first-child .onboarding-skeleton-line { height: 9px; width: 55% !important; background: color-mix(in srgb, var(--foreground) 25%, transparent); }-.onboarding-skeleton-codex .onboarding-skeleton-line { background: color-mix(in srgb, var(--cyan) 36%, transparent); }-.onboarding-skeleton-codex .onboarding-skeleton-row:nth-child(even) .onboarding-skeleton-line { background: color-mix(in srgb, var(--violet) 36%, transparent); }-.onboarding-code-number { font: 8px monospace; color: var(--muted); }-.onboarding-skeleton-opencode { gap: 18px; }-.onboarding-test-check { display: flex; width: 12px; height: 12px; border: 1px solid var(--border-strong); border-radius: 3px; color: var(--mint-ink); font-size: 10px; align-items: center; justify-content: center; flex-shrink: 0; }-.onboarding-story-identity { display: flex; align-items: center; gap: 11px; padding-top: 16px; border-top: 1px solid var(--border); }-.onboarding-story-identity strong { font-size: 14px; font-weight: 600; }-.onboarding-story-identity > span:last-child { margin-left: auto; font-size: 11px; color: var(--muted); }-.onboarding-story-caption { position: absolute; bottom: 0; left: 50%; transform: translateX(-50%); padding: 0 14px; background: var(--background); color: var(--muted); font-size: 10px; white-space: nowrap; }-.onboarding-motion-controls { position: absolute; right: 0; bottom: -6px; display: flex; color: var(--muted); }-.onboarding-access { max-width: 640px; width: 100%; padding: 16px 0; }-.onboarding-access > p { text-align: center; font-size: 12px; color: var(--muted); margin-bottom: 14px; }+ border-radius: calc(16 * var(--ob-u));+ border: 1px solid var(--ob-card-border);+ background: var(--ob-card);+ padding: calc(18 * var(--ob-u)) calc(20 * var(--ob-u));+ overflow: hidden;+ transition: border-color 650ms, box-shadow 650ms;+}+.onboarding-collaboration-card[data-active="true"],+.onboarding-assistant:hover, .onboarding-assistant:focus-within {+ border-color: var(--ob-active-border);+ box-shadow: var(--ob-active-shadow);+}+/* The card's 192 of content is authored as 14 status + 119 skeleton + 15 + 44 identity.+ The skeleton is the flexible one, so anything the other three fail to claim pools+ below the last bar — which is exactly what an unscaled 16px glyph and 28px logo did+ at the cap. Both ends therefore reserve their authored share in design units, and the+ skeleton keeps the 119 it was drawn at. Reserving rather than fixing also aligns the+ three separators, since the rows above them are now the same height by construction. */+.onboarding-story-status {+ display: flex;+ align-items: center;+ gap: 7px;+ flex-shrink: 0;+ min-height: calc(14 * var(--ob-u));+ color: var(--muted);+ font-size: 10px;+}+.onboarding-status-icon { flex-shrink: 0; }+.onboarding-status-text { white-space: nowrap; }+.onboarding-status-enter { animation: onboarding-caption-enter 250ms ease-out both; }+@keyframes onboarding-caption-enter { from { opacity: 0; } to { opacity: 1; } }+/* 14, so the glyph fits the status row it sits in at the design's own scale instead+ of forcing that row two pixels taller than the 14 it is drawn at. */+.onboarding-status-glyph {+ margin-left: auto;+ width: 14px;+ height: 14px;+ flex-shrink: 0;+ display: grid;+ place-items: center;+ color: var(--mint-ink);+}+.onboarding-status-dot { width: 5px; height: 5px; border-radius: 50%; background: var(--ob-idle-dot); }+/* One ring, mounted from the first working frame through completion. */+.onboarding-status-mark {+ display: block;+ width: 14px;+ height: 14px;+ overflow: visible;+ stroke: currentColor;+ stroke-linecap: round;+ stroke-linejoin: round;+}+.onboarding-status-ring { stroke-width: 1.4; stroke-dasharray: 1; }+.onboarding-status-check {+ stroke-width: 1.8;+ transform-box: view-box;+ transform-origin: 8.5px 12.5px;+ animation: onboarding-check-grow 300ms both;+}+@keyframes onboarding-check-grow {+ 0% { opacity: 0; transform: scale(0); }+ 10% { opacity: 1; }+ 65% { transform: scale(1.16); }+ 85% { transform: scale(0.96); }+ 100% { opacity: 1; transform: scale(1); }+}++.onboarding-write-line {+ opacity: 0;+ clip-path: inset(0 100% 0 0);+ transition: clip-path 100ms ease-out, opacity 80ms ease-out;+}+.onboarding-write-visible { opacity: 1; clip-path: inset(0 0 0 0); }+.onboarding-skeleton { flex: 1; min-height: 0; padding-top: calc(17 * var(--ob-u)); position: relative; overflow: hidden; }+.onboarding-bar {+ display: block;+ height: calc(6 * var(--ob-u));+ border-radius: calc(3 * var(--ob-u));+ background: var(--ob-skeleton);+ flex-shrink: 0;+}+/* h5qtNn's own rhythm inside its 119 box: 17 above the heading, then 12 / 8 / 14 / 7 / 7+ between the six lines, leaving 14 below the last one. The heading is excluded here+ rather than left to lose: a class selector cannot outrank a child selector, so the+ generic 8 silently ate the 12 this rule is the reason for. 14 is written as the+ paragraph's own margin because it collapses with the 8 above it — the larger wins,+ which is the gap the design draws between the two blocks. */+.onboarding-skeleton-document > .onboarding-bar:not(.onboarding-bar-heading) { margin-bottom: calc(8 * var(--ob-u)); }+.onboarding-bar-heading { height: calc(9 * var(--ob-u)); margin-bottom: calc(12 * var(--ob-u)); background: var(--ob-skeleton-strong); }+.onboarding-skeleton-paragraph { display: flex; flex-direction: column; gap: calc(7 * var(--ob-u)); margin-top: calc(14 * var(--ob-u)); }+.onboarding-bar-subheading { height: calc(7 * var(--ob-u)); background: var(--ob-card-border); }+.onboarding-collaboration-card[data-state="working"] .onboarding-skeleton::after {+ content: "";+ position: absolute;+ inset: 0;+ transform: translateX(-110%);+ background: linear-gradient(110deg, transparent 20%, var(--ob-shimmer-soft) 45%,+ var(--ob-shimmer) 50%, var(--ob-shimmer-soft) 55%, transparent 80%);+ animation: onboarding-shimmer 750ms ease-in-out both;+ pointer-events: none;+}+@keyframes onboarding-shimmer { to { transform: translateX(110%); } }++/* u3bGM: six 11-tall rows on a 16 pitch, 14 below the box top — and, like the document,+ 14 left under the last one. The row is 11 because that is what its line number+ occupies; the bars inside it are 6 and centre against that. */+.onboarding-skeleton-code { display: flex; flex-direction: column; gap: calc(5 * var(--ob-u)); padding-top: calc(14 * var(--ob-u)); }+.onboarding-code-row { display: flex; align-items: center; gap: calc(10 * var(--ob-u)); height: calc(11 * var(--ob-u)); }+.onboarding-code-number { font-family: ui-monospace, monospace; font-size: 8px; line-height: 1; width: 7px; color: var(--ob-line-number); }+.onboarding-code-bars { display: flex; align-items: center; gap: calc(6 * var(--ob-u)); flex: 1; min-width: 0; }+.onboarding-bar-cyan { background: var(--ob-code-cyan); }+.onboarding-bar-violet { background: var(--ob-code-violet); }++/* xyNG1: four 12-tall rows on a 23 pitch, 17 below the box top. Fewer rows than the+ other two, so this skeleton ends higher — the design's own asymmetry, not slack. */+.onboarding-skeleton-tests { display: flex; flex-direction: column; gap: calc(11 * var(--ob-u)); padding-top: calc(17 * var(--ob-u)); }+.onboarding-test-row { display: flex; align-items: center; gap: calc(9 * var(--ob-u)); }+.onboarding-test-check {+ height: calc(12 * var(--ob-u));+ width: calc(12 * var(--ob-u));+ flex-shrink: 0;+ display: grid;+ place-items: center;+ border: 1px solid var(--ob-skeleton-strong);+ border-radius: calc(3 * var(--ob-u));+ background: var(--ob-check-bg);+ color: transparent;+}+/* The four checks tick in order while the tests card is working. */+.onboarding-collaboration-card[data-state="working"] .onboarding-test-check {+ animation: onboarding-test-pass 340ms both;+ animation-delay: calc(var(--test-index) * 160ms);+}+.onboarding-tests-done .onboarding-test-check {+ color: var(--mint-ink);+ border-color: var(--ob-check-border);+ background: var(--ob-check-done);+}+@keyframes onboarding-test-pass {+ 0%, 50% { color: transparent; border-color: var(--ob-skeleton-strong); background: var(--ob-check-bg); }+ 100% { color: var(--mint-ink); border-color: var(--ob-check-border); background: var(--ob-check-done); }+}++/* 44 from the separator to the card's inner edge, 15 of clear space above it. The+ 28px logo does not scale, so without the reserved height this block shrank as the+ diagram grew and handed the difference to the skeleton above it. */+.onboarding-story-identity {+ display: flex;+ align-items: center;+ gap: 11px;+ flex-shrink: 0;+ min-height: calc(44 * var(--ob-u));+ border-top: 1px solid var(--ob-identity-line);+ padding-top: calc(16 * var(--ob-u));+ margin-top: calc(15 * var(--ob-u));+}+.onboarding-story-identity > svg { flex-shrink: 0; }+.onboarding-story-identity strong { font-size: 14px; font-weight: 550; letter-spacing: -0.3px; white-space: nowrap; }+.onboarding-story-identity > span:last-child { margin-left: auto; font-size: 11px; color: var(--muted); white-space: nowrap; }++.onboarding-wires { position: absolute; inset: 0; width: 100%; height: 100%; overflow: visible; pointer-events: none; }+.onboarding-wire { stroke: var(--ob-wire); stroke-width: 1; }+.onboarding-port { fill: var(--ob-port); stroke: var(--ob-port-border); stroke-width: 1; }+/* A single 16-unit segment of a 100-unit path: the pulse crosses once and leaves. */+.onboarding-pulse-core, .onboarding-pulse-halo {+ stroke-dasharray: 16 116;+ stroke-dashoffset: 16;+ stroke-linecap: round;+ opacity: 0;+}+.onboarding-pulse-core { stroke: var(--ob-pulse); stroke-width: 1.6; }+.onboarding-pulse-halo { stroke: var(--ob-pulse-glow); stroke-width: 4; }++.onboarding-story-caption {+ position: absolute;+ bottom: -1px;+ left: 50%;+ transform: translateX(-50%);+ padding: 0 12px;+ background: var(--background);+ color: var(--ob-caption);+ font-size: 10px;+ line-height: 18px;+ white-space: nowrap;+ transition: color 300ms;+}+.onboarding-story-caption[data-returning="true"] { color: var(--mint-ink); }++/* ---- Access tiles -------------------------------------------------------- */++/* The outer tile edges land on the two vertical legs of the return wire (x=120 and+ x=760 of the 880 viewBox), so this block is 640/880 of the diagram — and of the+ diagram as it currently is, not of the cap. Both are laid out in the same column, so+ one percentage keeps the edges on the legs at every width: 802.9 at the 1104 cap,+ 674.9 at a 928 content box, and so on down to the phone band. */+.onboarding-access { width: calc(100% * 640 / 880); text-align: center; padding: 17px 0; }+.onboarding-access > p { font-size: 12px; line-height: 20px; color: var(--muted); margin-bottom: 14px; }.onboarding-access-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px 10px; list-style: none; }-.onboarding-access-tile { display: flex; align-items: center; gap: 9px; min-height: 42px; padding: 0 10px; border-radius: 10px; border: 1px solid var(--border-strong); background: var(--surface); font-size: 12px; }-.onboarding-access-icon { display: flex; align-items: center; justify-content: center; width: 28px; height: 28px; flex-shrink: 0; transition: transform 180ms; }-.onboarding-access-tile:hover, .onboarding-access-tile:focus, .onboarding-access-tile[data-emphasis="true"] { background: color-mix(in srgb, var(--border) 50%, var(--surface)); }-.onboarding-access-tile:hover .onboarding-access-icon, .onboarding-access-tile:focus .onboarding-access-icon, .onboarding-access-tile[data-emphasis="true"] .onboarding-access-icon { transform: scale(1.18); }-.onboarding-access-tile:focus-visible { outline: 2px solid var(--ring); outline-offset: 3px; }-.onboarding-setup { align-self: flex-start; padding-top: 24px; }-.onboarding-assistants { width: 100%; display: flex; flex-direction: column; gap: 12px; }-.onboarding-assistants-header { display: flex; justify-content: space-between; align-items: center; color: var(--muted); font-size: 13px; }-.onboarding-assistant { transition: border-color 180ms, box-shadow 180ms; }-.onboarding-assistant-main { display: flex; align-items: center; gap: 16px; min-height: 86px; padding: 16px 20px; }-.onboarding-assistant-logo { width: 44px; height: 44px; display: flex; align-items: center; justify-content: center; background: var(--background); border-radius: 10px; flex-shrink: 0; }+.onboarding-access-tile {+ min-width: 0;+ min-height: 42px;+ padding: 0 10px;+ display: flex;+ align-items: center;+ gap: 9px;+ border: 1px solid var(--border);+ border-radius: 10px;+ background: var(--ob-tile-bg);+ color: var(--ob-tile-label);+ font-size: 12px;+ line-height: 18px;+ text-align: left;+ outline: none;+ transition: background-color 180ms ease;+}+.onboarding-access-tile:hover, .onboarding-access-tile:focus-visible, .onboarding-access-tile[data-emphasis="true"] {+ background: var(--ob-tile-hover);+}+.onboarding-access-tile:focus-visible { outline: 1px solid var(--mint); outline-offset: 2px; }+.onboarding-access-icon {+ height: 28px;+ width: 28px;+ flex-shrink: 0;+ border-radius: 7px;+ background: var(--ob-well);+ display: grid;+ place-items: center;+ transition: transform 180ms ease;+}+.onboarding-access-tile:hover .onboarding-access-icon,+.onboarding-access-tile:focus-visible .onboarding-access-icon,+.onboarding-access-tile[data-emphasis="true"] .onboarding-access-icon { transform: scale(1.18); }++/* ---- Primary action ------------------------------------------------------ */++/* The reference draws this CTA as a flat mint fill — design.pen has no glow on any+ button, and `brand` carries one at rest. The fill, the label pairing and the hover+ stay the variant's; only the halo goes, which is presentation and nothing else. */+.onboarding-primary-action {+ box-shadow: none;+ border-radius: 10px;+ font-size: 13px;+ font-weight: 600;+ min-width: 144px;+ height: 44px;+ padding: 0 22px;+ gap: 10px;+}++/* ---- Assistant setup ----------------------------------------------------- */++/* The design spaces the section bar and every row by 12 (frame i3vw9: rows at 41, 141+ and 241 below a 29 tall bar), so one gap owns both.+ sNs1V draws this as a 360 slot holding a 329 bar-and-list, and the 24 below it is the+ step's own gap. That 31 of remainder is the breathing space before the footer, so it+ is reserved here rather than left over: a row that grows for an error or a wrapped+ label takes it back, and the slot grows past 360 only once it is used up. */+.onboarding-assistants { width: 100%; display: flex; flex-direction: column; gap: 12px; min-height: 360px; }+.onboarding-assistants-header { display: flex; justify-content: space-between; align-items: center; }+.onboarding-assistants-header h3 { font-size: 14px; font-weight: 600; color: var(--foreground); }+/* The design's 88 is the row's own height, border included, so it lives here rather+ than on the inner block; the row still grows when an error is shown. */+.onboarding-assistant {+ display: flex;+ flex-direction: column;+ min-height: 88px;+ border-radius: 12px;+ background: var(--surface-2);+ transition: border-color 650ms, box-shadow 650ms;+}+/* The design's 20 is measured from the row's outer edge and the row carries a 1px+ border, so the padding inside it is 19. */+.onboarding-assistant-main { flex: 1; display: flex; align-items: center; gap: 16px; padding: 16px 19px; }+.onboarding-assistant-logo {+ width: 44px;+ height: 44px;+ flex-shrink: 0;+ display: grid;+ place-items: center;+ border: 1px solid var(--border);+ border-radius: 10px;+ background: var(--ob-well);+}.onboarding-assistant-identity { flex: 1; min-width: 0; }.onboarding-assistant-identity h3 { font-size: 15px; font-weight: 600; }.onboarding-assistant-identity p { font-size: 12px; margin-top: 4px; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }.onboarding-assistant-status, .onboarding-assistant-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }-.onboarding-assistant-error { padding: 0 20px 16px; font-size: 12px; color: var(--destructive-ink); overflow-wrap: anywhere; }+.onboarding-assistant-error { padding: 0 19px 16px; font-size: 12px; color: var(--destructive-ink); overflow-wrap: anywhere; }.onboarding-assistant-error pre { margin-top: 8px; max-height: 160px; overflow: auto; white-space: pre-wrap; }.onboarding-assistant-error summary { margin-top: 8px; cursor: pointer; }.onboarding-setup-footer { display: flex; flex-direction: column; align-items: center; gap: 10px; }-@media (max-width: 900px) {++/* ---- Bands --------------------------------------------------------------- */++/* Below the design width the collaboration keeps its proportions and only loses+ height; the grid percentages carry the rest. A band's `--ob-diagram-h` is the whole+ 272-row box, of which the cards keep 228 — so 250px is a 210px card. */+@media (max-width: 1023px) {+ .onboarding-shell { --ob-gutter: 24px; }+}+@media (max-width: 959px) {+ .onboarding-shell { --ob-diagram-h: 250px; }+ /* Below the proportional bands the card is sized by hand, so the interior returns to+ its authored rhythm instead of following the diagram's width. */+ .onboarding-collaboration-cards { --ob-u: 1px; }+ /* A deliberate narrow-screen adaptation, not the design's number: the title drops to+ 30 here, and its tracking follows it proportionally (-1.6 at 34 is -0.047em). */+ .onboarding-heading h1, .onboarding-heading h2 { font-size: 30px; letter-spacing: -1.4px; }+ .onboarding-collaboration-card { padding: 16px; }+ .onboarding-story-identity { gap: 8px; padding-top: 12px; margin-top: 10px; }+ .onboarding-story-identity strong { font-size: 13px; }+ .onboarding-story-identity > span:last-child { font-size: 10px; }+ .onboarding-story-identity > svg { width: 25px; height: 25px; }+}+/* Tablet portrait and below: the caption moves under the icon row so a full label+ wraps instead of shrinking to an unreadable size. */+@media (max-width: 767px) {+ .onboarding-story-status { flex-wrap: wrap; row-gap: 4px; min-height: 32px; align-content: flex-start; }+ .onboarding-status-text { order: 3; width: 100%; white-space: normal; font-size: 11px; line-height: 13px; }+ .onboarding-story-identity { flex-wrap: wrap; gap: 6px; }+ .onboarding-story-identity > span:last-child { margin-left: 0; width: 100%; }.onboarding-assistant-main { flex-wrap: wrap; }- .onboarding-assistant-identity p { white-space: normal; }.onboarding-assistant-identity { flex-basis: calc(100% - 60px); }.onboarding-assistant-actions { margin-left: auto; flex-wrap: wrap; }}-@media (max-width: 767px) {- .onboarding-shell { padding: 16px; }- .onboarding-heading h1, .onboarding-heading h2 { font-size: 28px; }- .onboarding-collaboration-cards { flex-direction: column; align-items: center; gap: 24px; }- .onboarding-collaboration-card { width: min(100%, 320px); flex: none; }- .onboarding-wires { display: none; }- .onboarding-collaboration-card { position: relative; }- .onboarding-collaboration-card + .onboarding-collaboration-card::before { content: ''; position: absolute; height: 24px; width: 1px; background: var(--border-strong); top: -25px; left: 50%; }- .onboarding-access-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }- .onboarding-assistant-main { gap: 12px; padding: 16px; }- .onboarding-assistant-actions { margin-left: 0; }- .onboarding-motion-controls { bottom: -28px; }+@media (max-width: 599px) {+ .onboarding-shell { --ob-gutter: 16px; --ob-diagram-h: 300px; }+ /* Phones loosen rather than follow the proportion: -1.2 would be the 34/-1.6 ratio at+ this size, and tight tracking is exactly what costs legibility on a small screen. */+ .onboarding-heading h1, .onboarding-heading h2 { font-size: 25px; line-height: 1.4; letter-spacing: -0.8px; }+ .onboarding-heading p { font-size: 12px; line-height: 20px; }+ .onboarding-welcome, .onboarding-setup { gap: 20px; }+ .onboarding-collaboration-card { padding: 10px 8px; border-radius: 10px; }+ /* The kind glyph stays: it is the one mark that says which of the three kinds of work+ a card is doing, and at 13px it costs a third of a row it already reserves. */+ .onboarding-story-status { min-height: 46px; }+ .onboarding-skeleton { padding-top: 12px; }+ .onboarding-bar { height: 4px; }+ .onboarding-bar-heading { height: 6px; margin-bottom: 8px; }+ .onboarding-skeleton-document > .onboarding-bar:not(.onboarding-bar-heading) { margin-bottom: 5px; }+ .onboarding-skeleton-paragraph { gap: 5px; margin-top: 8px; }+ .onboarding-bar-subheading { height: 5px; }+ .onboarding-skeleton-code { gap: 6px; padding-top: 12px; }+ .onboarding-code-row { gap: 4px; height: 6px; }+ .onboarding-code-number { font-size: 6px; }+ .onboarding-code-bars { gap: 3px; padding-left: 0 !important; }+ .onboarding-skeleton-tests { gap: 7px; padding-top: 12px; }+ .onboarding-test-row { gap: 5px; }+ .onboarding-test-check { width: 10px; height: 10px; border-radius: 2px; }+ .onboarding-test-check svg { width: 8px; height: 8px; }+ /* One arrangement for all three cards, rather than whichever one each name's length+ produces. A card is ~62px wide here, so "Claude Code" wraps and "Codex" does not:+ free flex wrapping therefore put two logos above their names and the third beside+ one, and left the three separators as much as 21px apart. An explicit stack — logo,+ name, role, each on its own row — with the name's box holding the two lines the+ longest of them needs makes the three identities the same height by construction,+ and the skeleton above absorbs the difference, so the separators line up. Nothing+ is truncated or scaled to fit: both lines of a wrapped name are shown. */+ .onboarding-story-identity {+ display: grid;+ grid-template-columns: minmax(0, 1fr);+ justify-items: start;+ padding-top: 9px;+ margin-top: 8px;+ gap: 4px;+ }+ .onboarding-story-identity > svg { width: 20px; height: 20px; }+ .onboarding-story-identity strong {+ font-size: 11px;+ line-height: 14px;+ letter-spacing: -0.4px;+ white-space: normal;+ min-height: 28px;+ }+ .onboarding-story-identity > span:last-child { font-size: 10px; line-height: 13px; min-height: 13px; }+ /* The one width that deliberately leaves the wire relation: two columns of 640/880 of+ a phone would be ~200px of tiles inside a 360px screen, so below this band the+ block takes the full width and the tiles stay a readable target. */+ .onboarding-access { width: 100%; padding: 10px 0; }+ .onboarding-access-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; }+ .onboarding-access-tile { min-height: 44px; padding: 0 9px; gap: 8px; }+ /* Small screens let the row follow its wrapped contents instead of the design's 88. */+ .onboarding-assistant { min-height: 0; }+ .onboarding-assistant-main { gap: 12px; padding: 14px 16px; }+ .onboarding-assistant-logo { width: 36px; height: 36px; }+ .onboarding-assistant-identity { flex-basis: calc(100% - 48px); }+ .onboarding-assistant-identity p { white-space: normal; }+ .onboarding-assistant-status, .onboarding-assistant-actions { margin-left: 0; flex-wrap: wrap; }+}+/* The narrowest supported width still shows every label; English needs a third line. */+@media (max-width: 374px) {+ .onboarding-shell { --ob-diagram-h: 320px; }+ .onboarding-story-status { min-height: 62px; }+}+/* A short window scrolls. There used to be a `max-height: 760px` rule here that took+ the step gaps from 24 to 16 and squeezed the access block, which bought roughly 30px+ and spent the design's own spacing to do it — at 1200x800, the reference's own frame+ size, where nothing was wrong. Whitespace is the composition; scrolling is an+ accepted outcome. Only the narrow bands adapt, and they adapt by width. */++/* ---- Stopping ------------------------------------------------------------ */++/* Pausing has to stop what is being drawn, not only the clock the cards are read from.+ The skeleton shimmer and the four test ticks are CSS animations on their own+ timeline, which `page.clock`-style time control and a frozen React tree both leave+ running; the same is true of a hidden tab, where they would play on unseen and+ reappear mid-sweep. `paused` holds each of them at its current frame, so resuming+ continues the same sweep instead of jumping to wherever wall-clock time had got to. */+/* `!important` for the same reason the reduced-motion block below uses it: this is a+ lifecycle override, and no authored rule should be able to out-specify "the tab is not+ being presented". Without it the shimmer kept running — its own rule carries a class+ more than this one, and the `animation` shorthand it uses resets play state to+ running, so the longest effect on the screen was the one this never reached. */+.onboarding-collaboration[data-motion="paused"],+.onboarding-collaboration[data-motion="paused"] *,+.onboarding-collaboration[data-motion="paused"] *::before,+.onboarding-collaboration[data-motion="paused"] *::after {+ animation-play-state: paused !important;}+@media (prefers-reduced-motion: reduce) {- .onboarding-shell *, .onboarding-shell *::before { animation: none !important; transition: none !important; }+ .onboarding-shell *, .onboarding-shell *::before, .onboarding-shell *::after {+ animation: none !important;+ transition: none !important;+ }.onboarding-access-icon { transform: none !important; }+ .onboarding-pulse-core, .onboarding-pulse-halo { stroke-dasharray: none; }}diff --git a/ui/src/components/steps/AgentDetection.tsx b/ui/src/components/steps/AgentDetection.tsxindex a6a2ff885..ab868325b 100644--- a/ui/src/components/steps/AgentDetection.tsx+++ b/ui/src/components/steps/AgentDetection.tsx@@ -478,7 +478,9 @@ export const AgentDetection: React.FC<AgentDetectionProps> = ({ data, onNext, on<div className="onboarding-assistants"><div className="onboarding-assistants-header"><h3>{t('onboarding.setup.assistants')}</h3>- <Button type="button" variant="ghost" size="sm" onClick={() => void detectAll()}+ {/* n4ATm draws this as an outlined control on its own surface, not a bare+ text button: `secondary` is that pair, and `xs` its 12px/12px metrics. */}+ <Button type="button" variant="secondary" size="xs" onClick={() => void detectAll()}disabled={isAnyInstalling || Object.values(detectingAgents).some(Boolean)}><RefreshCw size={14} />{t('agentDetection.rescan')}</Button>@@ -513,9 +515,10 @@ export const AgentDetection: React.FC<AgentDetectionProps> = ({ data, onNext, ononSetup={() => void permission.setupPermission()} className="w-full" />{providerDialog}<div className="onboarding-setup-footer">- <Button type="button" variant="brand" className="h-11 min-w-36" onClick={() => void handlePrimaryAction()}+ <Button type="button" variant="brand" className="group onboarding-primary-action" onClick={() => void handlePrimaryAction()}disabled={!canContinue || syncing}>- {t('common.continue')}<ArrowRight size={16} />+ {t('common.continue')}+ <ArrowRight size={16} className="motion-safe:transition-transform motion-safe:duration-180 motion-safe:group-hover:translate-x-1" /></Button>{opencodeNeedsPermission && <p className="text-center text-xs text-gold-ink">{t('agentDetection.permissionGateHint')}</p>}{onBack && <Button type="button" variant="ghost" size="sm" disabled={syncing} onClick={() => onBack({ agents })}><ArrowLeft size={14} />{t('common.back')}</Button>}diff --git a/ui/src/components/steps/Welcome.tsx b/ui/src/components/steps/Welcome.tsxindex 741478317..7a1b91980 100644--- a/ui/src/components/steps/Welcome.tsx+++ b/ui/src/components/steps/Welcome.tsx@@ -17,7 +17,6 @@ interface WelcomeProps {export function Welcome({ data, onNext }: WelcomeProps) {const { t } = useTranslation();const api = useApi();- const [paused, setPaused] = useState(false);const [pending, setPending] = useState(false);const [error, setError] = useState<string | null>(null);const busy = useRef(false);@@ -46,9 +45,9 @@ export function Welcome({ data, onNext }: WelcomeProps) {<h1>{t('onboarding.welcome.title')}</h1><p>{t('onboarding.welcome.subtitle')}</p></header>- <CollaborationStory paused={paused} onPausedChange={setPaused} />- <AccessTiles paused={paused} />- <Button type="button" variant="brand" className="group h-11 min-w-36" onClick={() => void start()} disabled={pending}>+ <CollaborationStory />+ <AccessTiles />+ <Button type="button" variant="brand" className="group onboarding-primary-action" onClick={() => void start()} disabled={pending}>{t(pending ? 'onboarding.welcome.detecting' : error ? 'common.retry' : 'onboarding.welcome.getStarted')}{pending ? <RefreshCw size={16} className="motion-safe:animate-spin" /> : <ArrowRight size={16} className="motion-safe:transition-transform motion-safe:duration-180 motion-safe:group-hover:translate-x-1" />}</Button>diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.jsonindex 60f871536..2e418baea 100644--- a/ui/src/i18n/en.json+++ b/ui/src/i18n/en.json@@ -5215,13 +5215,10 @@"label": "Assistants working together","description": "Claude Code plans the work, Codex builds it, OpenCode tests it, and Claude Code summarizes the result.","caption": "Plan · Build · Test · Deliver",- "pause": "Pause animation",- "play": "Play animation",- "replay": "Replay animation",+ "returnCaption": "Tests passed · back to the PM","claude": {"name": "Claude Code","role": "PM",- "waiting": "Planning the work","working": "Writing the project brief","complete": "Project brief ready","summary": "Summarizing the delivery"@@ -5229,14 +5226,12 @@"codex": {"name": "Codex","role": "Developer",- "waiting": "Waiting for the brief","working": "Writing code","complete": "Implementation ready"},"opencode": {"name": "OpenCode","role": "Tester",- "waiting": "Waiting for the code","working": "Writing and running tests","complete": "All tests passed"}diff --git a/ui/src/i18n/zh.json b/ui/src/i18n/zh.jsonindex bfe13ad46..5f4926048 100644--- a/ui/src/i18n/zh.json+++ b/ui/src/i18n/zh.json@@ -5215,28 +5215,23 @@"label": "助手接力协作","description": "Claude Code 规划任务,Codex 编写代码,OpenCode 执行测试,最后由 Claude Code 汇总交付。","caption": "规划 · 开发 · 测试 · 交付",- "pause": "暂停动画",- "play": "播放动画",- "replay": "重新播放动画",+ "returnCaption": "测试通过,回传 PM","claude": {"name": "Claude Code","role": "PM",- "waiting": "规划任务","working": "编写需求文档","complete": "需求文档已就绪",- "summary": "汇总交付结果"+ "summary": "汇总结果,完成交付"},"codex": {"name": "Codex","role": "开发",- "waiting": "等待需求文档","working": "编写功能代码","complete": "功能代码已就绪"},"opencode": {"name": "OpenCode","role": "测试",- "waiting": "等待功能代码","working": "编写并执行用例","complete": "测试全部通过"}diff --git a/ui/src/index.css b/ui/src/index.cssindex 24d1b8272..96b2461e9 100644--- a/ui/src/index.css+++ b/ui/src/index.css@@ -188,6 +188,27 @@--shadow-glow-xl-mint: 0 0 48px -12px rgba(91, 255, 160, 0.44);+ /* `onboarding` is the active-card halo of the approved onboarding reference, the+ one the owner pointed at: a centred 28px mint at #5BFFA060, with no spread and+ brighter than the sized rungs carry. It is a role rather than a rung because+ both of those departures are the reference's, not the scale's -- reaching it by+ stacking `xl` and `lg` was an approximation of an explicit value.+ `37.6%` is that hex's own alpha: 0x60 is 96/255.++ It is the one role the design draws at two sizes, because the two frames drew+ it separately: Light's active card (node waUhu) is 16/-4 at #10B98170, which is+ the sized scale's own `sm` geometry and alpha. The hue needs nothing for that+ -- `var(--mint)` already follows whichever mint the theme declares, the way+ `wire` does -- but blur, spread and alpha are numbers, and a number cannot+ follow a palette. They are named here and re-anchored beside the rest of the+ light palette, which is the shape `--brand-glow-blur` already uses and the only+ one that renders: this block is `@theme inline`, so Tailwind substitutes the+ value below into the utilities at build time and a later override of THIS name+ would compile to nothing while looking correct in the file. */+ --shadow-glow-onboarding-mint:+ 0 0 var(--onboarding-glow-blur) var(--onboarding-glow-spread)+ color-mix(in srgb, var(--mint) var(--onboarding-glow-alpha), transparent);+--shadow-glow-cta-mint: 0 0 var(--brand-glow-blur) -4px rgba(91, 255, 160, 0.6);--shadow-glow-cta-cyan: 0 0 var(--brand-glow-blur) -4px rgba(63, 224, 229, 0.6);--shadow-glow-cta-violet: 0 0 var(--brand-glow-blur) -4px rgba(124, 91, 255, 0.6);@@ -279,6 +300,13 @@because it is the one part of that glow that differs per theme. */--brand-glow-blur: 16px;+ /* Geometry and alpha of the onboarding active-card halo, for the same reason the+ CTA blur is here: they are the parts of that glow that differ per theme, and+ the token itself is inlined into its utilities and so cannot be re-declared. */+ --onboarding-glow-blur: 28px;+ --onboarding-glow-spread: 0px;+ --onboarding-glow-alpha: 37.6%;+/* Colour of the card wash shadows (`--shadow-mint-card*`). design.pen writes itas the frame's own brand mint at 0.078, which is why it is the one part ofthose shadows that moves between themes. */@@ -437,6 +465,14 @@/* Wider CTA glow than dark: the same neon spreads far less over a white card,so 16px read as almost nothing here (owner decision 2026-08-14). */--brand-glow-blur: 20px;++ /* The Light frame's own active card (waUhu) draws 16px at -4px spread and+ #10B98170 -- the sized scale's `sm` geometry and its 0.44 alpha, not dark's+ spreadless 28. Only these numbers are re-anchored; the hue stays `var(--mint)`,+ which this block has already swapped to the light brand. */+ --onboarding-glow-blur: 16px;+ --onboarding-glow-spread: -4px;+ --onboarding-glow-alpha: 44%;}}@@ -542,6 +578,12 @@/* Wider CTA glow than dark: the same neon spreads far less over a white card,so 16px read as almost nothing here (owner decision 2026-08-14). */--brand-glow-blur: 20px;++ /* Light's own active-card geometry - see the prefers-color-scheme block above.+ Both light blocks must stay value-identical. */+ --onboarding-glow-blur: 16px;+ --onboarding-glow-spread: -4px;+ --onboarding-glow-alpha: 44%;}html,