waggle-os/docs/ux-refactor/path-exec-phase-D-spec-2026-07-07.md

Path-to-9 execution · PHASE D — the motion system (Pillar 1) + home scroll-reveal

Contract: docs/ux-refactor/path-to-9-2026-07-07.md v3 §Pillar 1 (5/5 endorsed, incl. the

PATH-2 conditions: default route tier + hero morphs, focus/AT spec IN the component,

interruptibility as acceptance criteria, commissioned waggle-settle prototype-first).

The unanimous R19 #1 gap. Highest regression risk → scoped, feature-flagged, staged.

All motion uses lib/motion/tokens.ts. Both themes. Reduced-motion per REDUCED map.

Recon (verified): router = react-router <Routes> in App.tsx; the layout route / = AppShell whose single <Outlet/> (AppShell.tsx:449) renders the active route inside <main class="relative z-10 flex-1 overflow-hidden">. location, useNavigate, AnimatePresence already imported. ChatHost keep-alive portal is SEPARATE from the Outlet (must not be wrapped — it protects in-flight SSE). Phase-0 spring family + --mo-* tokens + REDUCED map exist. Hover tier = the shipped hive-interactive-style classes on cards (Wave T/U/V). AmbientHiveGlow shipped Phase C (home breath).

STAGE 1 (parallel; the two heavy motion lanes are independent)

Lane RT — route-transition system (Pillar 1.1; PATH-2 design blocking)

Files: NEW components/os/RouteTransition.tsx (+ test), components/os/AppShell.tsx (wrap the Outlet only), lib/feature-flags.ts or a local flag (verify the flag pattern), tests.

1. DEFAULT tier — fade-through crossfade + persistent chrome on ALL top-level route changes: wrap <Outlet/> in <AnimatePresence mode="popLayout"> keyed by a ROUTE-GROUP key (NOT the full pathname — a workspace tab change within /workspaces/:id must not crossfade the whole surface; derive the key from the top segment: home/workspaces/ memory/agents/marketplace/settings/…). Enter/exit = opacity fade-through (150–200ms, --mo-base + EASE_OUT); the sidebar + StatusBar are OUTSIDE the animated subtree (persistent chrome — they never fade). NOT a global router rewrite.
2. Interruptibility + input-primacy (PATH-2 design blocking — ACCEPTANCE, tested): a route change mid-transition redirects immediately (AnimatePresence popLayout allows the new child in without waiting for exit); navigation/input NEVER waits on an exit animation. Add a test: fire two navigations in quick succession → the final route wins, no lock. Keep mode="popLayout" (not "wait") precisely so exits don't block enters.
3. Focus + assistive-tech spec IN the component (PATH-2 a11y blocking): on route commit, move focus to the destination surface's primary heading / <main> landmark (focus a tabIndex={-1} ref); set the EXITING subtree inert+aria-hidden for its exit duration (focus/SR cursor can never land in it); announce the route via a polite live region (route label). Ship these INSIDE RouteTransition, not as a follow-up.
4. Reduced-motion: crossfade → instant swap (REDUCED.routeTransition = 'crossfade-only' means: under reduce, no opacity animation — instant), focus + announce still fire.
5. Feature-flag the whole thing (default ON in dev, but a kill switch) so a regression is one flag flip. Verify the ChatHost keep-alive still works (SSE survives a route change — do not wrap ChatHost).

Lane HM — hero shared-element morphs (Pillar 1.1 hero cases)

Files: apps/AllWorkspacesApp.tsx + the workspace route/surface (layoutId on the card→ surface), apps/memory/* (Trust↔Memories tab morph), tests. Depends on Lane RT's RouteTransition existing (Stage 1 both start; HM reads RT's exports — if RT isn't merged yet, HM implements the layoutId pairs and notes the integration point).

1. card→workspace-open: the workspace card's hex avatar + name share a layoutId with the destination workspace header, so opening a card GROWS it into the surface (framer layoutId + LayoutGroup). Scope to this ONE pair; fall back to the default crossfade if the destination header isn't mounted.
2. Trust↔Memories tab morph: the shared hero/container morphs between the two memory tabs (layout animation on the tab panel), not a hard cut.
3. Interruptibility + reduced-motion (instant) as Lane RT item 2/4. Both morphs motion-safe.

STAGE 2 (parallel; after Stage 1)

Lane HV — hover amplitude: "honey responds to touch" (Pillar 1.2; brand HIGH ×3 rounds)

Files: the shared hover-tier class/util (grep where cards define hover — likely inline Tailwind on AllWorkspacesApp/SuggestedAgentCards/ExtensionCard; if there's a shared hive-interactive class in index.css, edit there; else create ONE and adopt), tests.

1. Bump the hover tier amplitude to a felt "honey blooms under the cursor": on hover/ focus-visible → lift (translate-y 2→4px), shadow step, honey border-warm, AND a soft honey glow bloom (box-shadow with --shadow-honey/--honey-glow), 120–160ms --mo-fast + spring feel. ONE implementation adopted by workspace cards, agent cards, marketplace rows, provider tiles. Reduced-motion: keep color/shadow, drop translate.
2. Keep the brand judge's WIN ("respectful, not gratuitous") — bloom is subtle, not neon. Light theme: verify the glow reads on ivory (Phase-A light --honey-glow / deeper honey).

Lane SR — home day-story scroll-reveal (Pillar 1.1 entrance; R20 design HIGH)

Files: apps/HomeCockpit.tsx (+ the home section components), tests.

1. The home "day story" (I REMEMBER → START HERE → memory-review → WHILE YOU SLEPT → pick-up cards) reveals on scroll: each section rises 8px + fades in as it enters the viewport (IntersectionObserver + the card-enter / STAGGER grammar), once per section per visit. So the scripted scroll reads as designed motion, not a static page. Reduced-motion: all visible immediately, no rise/fade. Do not re-trigger on scroll-up.

STAGE 3 (the signature gesture — prototype-first, PATH-2 brand blocking)

Lane WS — the waggle-settle, commissioned + prototyped STANDALONE

Files: NEW components/os/warm/WaggleSettle.tsx (+ test) + a /motion-spec section demonstrating it on exactly ONE moment (memory saved). Do NOT propagate to other moments in this phase — the prototype is judged first (a mini standalone review), THEN rolled out per the Phase-0 SIGNATURE frequency taxonomy in a later step.

1. A recognizably waggle-derived micro-choreography: a brief directional waggle-run (the bee's figure-eight dance DNA — a small side-to-side + forward settle) → settle, ~300–400ms (DUR.settle, SPRING.expressive), honey. Reduced-motion: instant state + color pulse (no path motion). It must read as "the waggle," not a generic scale-pop.
2. Wire it to ONE moment only: the memory-saved confirmation (find the save-memory success path — grep). Render it there behind the SIGNATURE.full taxonomy gate (per-session cooldown). Everything else waits for the standalone judge verdict.

VERIFY STAGE (adversarial)

• V1-motion-system: RouteTransition — is the crossfade interruptible (the double-nav test), is the focus/AT spec implemented (focus moves to heading, exiting tree inert, route announced), does reduced-motion degrade to instant, does ChatHost SSE survive a route change? Hero morphs — do the layoutId pairs animate (code-read + the 12fps capture if available)?
• V2-hover-scroll: hover amplitude felt (inspect the class), light-theme glow reads, reduced-motion drops translate; scroll-reveal fires once per section, reduced-motion off.
• V3-a11y-regression: the highest risk — a keyboard-only pass through 3 route changes (focus lands on the destination heading each time, no focus trapped in an exiting tree, route announced); reduced-motion Playwright pass asserting no route-transition opacity animation under reduce.

Orchestrator after verify

tsc web + full vitest + all ux-gates (contrast/text-guard/warm/runtime) + reduced-motion gate + browser smoke (route changes crossfade, one card→workspace morph, hover bloom) → commit → standalone waggle-settle mini-judge (is it "the waggle"? kitsch check) → if approved, roll out per taxonomy → kit-v7 capture → R22 judge (9-ATTEMPT: min ≥ 9.0). If R22 min < 9 but ≥ 8.5, one convergent-fix round; if it plateaus, stop + re-analyze.