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.

This run created (already committed with this page)

Post-approval mutations (a later turn, only after final compiled YAML)

No implementation files, no dependencies, and no changes to the unrelated in-flight skillpacks work in the tree.

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.