Animation Design Plan — Deck-Builder blueprint-morph + card-flight

The deck-builder UX design (apps/skills-showcase/docs/deck-builder-ux.md, committed 6e2e6aec) introduces two new framer-motion transitions that don't exist in the /prototype flow:

• blueprint-morph — deck blueprint card on the table ⇄ builder overlay at /deck/[slug].
• card-flight — fan card flies into a deck slot on tap, plus an add-all stagger variant.

/animation-design-planner was invoked to plan these before building — naming the visible motion contracts, lifecycle owner, state phases, and proof method so implementation doesn't start with local timing tweaks. Framework detected: framer-motion 12.40 (imported as "framer-motion") → motion-framer subskill guardrails apply.

Evidence behind the load-bearing decisions

Never list

• Never: double-vision — blueprint and panel both visible at full opacity.
• Never: flash at morph-back.
• Never: builder content popping before the morph completes.
• Never: table scroll jump.
• Never: focus loss — focus moves to the builder heading on open, returns to the originating blueprint on close.
• Never: URL/visual desync.

Interruption rules

• Blueprint taps ignored unless phase is table.
• Dismiss legal only from builder-open — plus dismiss-during-blueprint-morphing, which retargets the layout morph from its current projected position.
• Hard load of /deck/[slug] skips the open morph (no origin) but still morphs back on close, because the table renders underneath.

Never list

• Never: double-vision — full-opacity fan card while the clone flies.
• Never: clone clipped by the sheet's overflow or painted under the scrim/slot strip.
• Never: slot filling before the clone lands (reduced motion excepted).
• Never: counter desync after interruptions.
• Never: accidental collect from an inspect tap — flip and fly remain separate affordances.

Interruption rules

• Re-tap of an in-flight or collected card is a no-op.
• Concurrent flights of different cards are allowed.
• Drawer close or builder dismiss mid-flight snaps all flights to end (no cancel/rollback) before proceeding.
• Deck-complete sequence defers until all flights land.

⚠ These are ephemeral previews, not production code. The demos show directional motion; the scrubbers show the phase timing data. All timings are design targets that pass through dbg.scaleT at implementation time. No state persists.

Hierarchical composition; the existing PackFlowPhase machine is nested unchanged:

DeckTableShell (client; rendered by both app/page.tsx and app/deck/[slug]/page.tsx)
├── owns DeckFlowPhase: table → blueprint-morphing → builder-open → builder-dismissing → table
├── owns activeDeck + collectedCardIds (localStorage-backed, per slug)
├── one <LayoutGroup> wrapping table + builder
├── TableSurface (always mounted)
├── BuilderPanel (AnimatePresence; mounted while activeDeck != null)
│   └── BuilderPackFlow — PackFlowPhase owner extracted from PrototypeInner
│       (sealed → opening-apex → drawer-open → closing-* chain, verbatim)
│       └── owns flights Map<cardId, FlightRecord> (parallel records, NOT a scalar phase:
│           queued → measuring → in-flight → settling → done per record)
└── FlightLayer (fixed inset-0, pointer-events-none, z-[70]) — flight clones

Identity rules

• Fan cards keyed by skill.id, never filtered/reordered on collect (preserves PackOpener's fan/collapse math).
• Flight clones keyed flight-${skill.id}, max one per card.
• Slots keyed ${deckSlug}:${slotId}.
• Exactly one mounted owner of deck-blueprint-${slug} at a time — source stays mounted at opacity 0, the SealedPack pattern.

Commit timing

Optimistic — collectedCardIds + localStorage commit at tap time; animation is pure presentation; a presentation-level displayedCount ticks on flight-land and reconciles on any interrupt. No rollback paths exist.

Interruption rule

finishAllFlightsImmediately() (snap-to-end: stop controls, remove clones, force slots filled, reconcile counter) runs before any drawer close or builder dismiss. Back/dismiss with the drawer open uses a fast drawer teardown (BottomSheet's existing 0.01s fadeExit path, skip the collapse ritual) so leaving feels immediate.

⚠ This is an ephemeral preview, not production code. Click a state node to highlight its legal transitions and guards. The DeckFlowPhase chain is the new shell machine; the FlightRecord chain is per-card (a Map of parallel records, not a scalar phase). No state persists.

All timings pass through dbg.scaleT and are debug-speed scalable.

blueprint-morph open

1. Tap → pushState + blueprint claims opacity 0 / panel claims layoutId.
2. Layout spring morph (~450 ms, framer layout spring).
3. onLayoutAnimationComplete (one-shot ref) → builder-open.
4. Content stagger-in (slot columns then shelf, ~200 ms, 40 ms stagger).

blueprint-morph close

1. Content near-instant fade-out (0.01 s, so the morph reads).
2. AnimatePresence onExitComplete → blueprint reclaims id.
3. Morph-back (~350 ms) → onLayoutAnimationComplete → table, focus restored.

Morph-back completion frame is the flash-risk apex. It gets a dedicated gate step in the debug harness and a named manual slow-motion check in the proof gate.

card-flight

1. Tap → optimistic commit + fan card dims (same frame).
2. Measure source rect; if the target slot is off-screen, scrollIntoView({behavior:"instant"}) then re-measure next rAF.
3. Clone mounts in FlightLayer at source rect.
4. Imperative animate() x/y/scale to slot rect, spring {stiffness: 260, damping: 26} (~400 ms).
5. .then(): clone removed, slot ghost→filled, declarative pulse scale [1, 1.08, 1] ~250 ms, counter ticks.

Add-all: filtered queue, 70 ms stagger per flight (13-card worst case ≈ 0.84 s launch tail), batch-complete via decrement ref; single tap is a batch of 1.

• Transform/opacity only; the morph animates the panel chrome rectangle, never the slot grid layout; no filter/shadow animation.
• BuilderPanel's layoutId container takes no declarative animate on transforms; content motion lives on child wrappers.
• AnimatePresence placement: BuilderPanel's presence is owned by DeckTableShell (the component that decides mounting), mode sync; BottomSheet keeps its existing presence handling.
• Reduced motion (useReducedMotion(), read once in the shell): same state chain and callbacks fire in the same order (debug/test parity), durations degrade — blueprint-morph becomes a 120 ms opacity crossfade with layoutId omitted; card-flight mounts no clone, launch/land marks fire back-to-back, slot fills with a 120 ms fade, no pulse, add-all has no stagger. Retrofitting the existing pack flow is a named follow-up, out of scope.
• Pointer events: FlightLayer pointer-events-none; scrim/dismiss disabled during blueprint-morphing and builder-dismissing; focus management per contract A.

New step arrays in steps.ts (+ nodes/lanes deck-shell, builder, flight-layer and runtime slices in animationMachine.ts):

New debug drivers: openDeck, dismissDeck, flyCard, flyAll, extended reset. All new transitions pass through dbg.scaleT.

User direction during planning: add Playwright at implementation time.

Vitest sequence tests (existing pattern — mocked debug report() channel, mocked getBoundingClientRect)

• Morph open/close phase order.
• Flight optimistic-commit + interrupt reconciliation (close-mid-flight leaves counter == collected size).
• Re-tap no-op.
• Hard-load /deck/[slug] enters builder-open without morph.

Playwright (devDependency added in the deck-builder implementation phase, local runs only — no GitHub Actions)

• Screenshots at each phase boundary.
• Video of morph open/close and a 3-card add-all.
• Assert no frame shows double-vision or a clipped clone.
• A prefers-reduced-motion project run asserting crossfade/instant-fill behavior.

Manual slow-motion review (at --debug-speed 0.25)

• Morph-back apex frame (flash risk).
• Clone z-order over scrim/sheet/slot strip.
• Perceived continuity of the chrome rectangle.
• Interruption feel (back-during-flight).

Acceptance: every "never" item in contracts A/B has a corresponding automated or named-manual check; onExitComplete-dependent cleanup verified to run after exit, not during.

Review run created

Confirmation mutations

The first implementation spike runs after this confirmation, scoped to Next 16.2.6 shallow pushState behavior.

After approval, the natural next step is the deck-builder implementation handoff: the canonical plan plus deck-builder-ux.md become the spec inputs, with the Next 16.2.6 pushState spike as the first implementation task.