feat(family): mouse parallax + neighbor hover-lift (4a)

[ffllyygod]

Task 4a — Mouse parallax + neighbor hover-lift

Brief: .karimo/prds/002_the-family-r3f-cinema/briefs/4a_the-family-r3f-cinema.md
Wave 7 · Complexity 4/10 · Model opus
Spec ref: docs/superpowers/specs/2026-05-18-the-family-r3f-cinema-design.md §7.2

Summary

Desktop-only cinematic affordances on the §05 The Family ring.

• Cursor parallax: ±0.18 rad additive ring offset, eased via existing maath damp.
• Neighbour hover-lift: non-active packs bump scale 0.72→0.78 and z +0.1 on pointerenter.
• Both gate on (hover:hover) and (pointer:fine) + !reducedMotion — touch / coarse-pointer / reduced-motion users see none of it.
• snapTo / nudge open a 150ms pause window during which getParallax() returns {0,0} so the cursor doesn't fight click-to-snap easing.

Files

• components/about/TheFamily/use-family-controls.ts — parallaxRef, pausedUntilRef, setParallax, getParallax, needsParallax, PARALLAX_PAUSE_MS (= 150ms). Reduced-motion zeros + ignores writes; needsTick extended.
• components/about/TheFamily/use-family-controls.test.ts (new) — 3 vitest cases: setParallax write, post-snap pause window, reduced-motion no-op.
• components/about/TheFamily/CanvasScene.tsx — Ring useFrame adds clamped parallax offset; per-pack hoveredIndex state lifts non-active packs; enableHover prop gates hover handler attachment. Frameloop "always" while hover is active.
• components/about/TheFamily/TheFamilyClient.tsx — matchMedia('(hover: hover) and (pointer: fine)') probe; onPointerMove chained (drag + parallax); onPointerLeave resets to {0,0}.

Evidence

$ npm run typecheck
[clean]

$ npx vitest --run
Test Files  15 passed (15)
Tests       126 passed (126)

3 new cases under useFamilyControls — parallax (PRD 002 task 4a):

• setParallax writes (x, y) into parallaxRef.current
• snapTo opens a 150ms pause window during which getParallax returns {0,0}
• reducedMotion=true: setParallax is a no-op (ref stays at {0,0})

Downstream

• 4b consumes the same hook return — needsParallax + parallaxRef exports are stable. No API removals.

Closes karimo task 4a

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pilato	Ready	Preview, Comment	May 18, 2026 10:54am