#Magic Vault 5×3 — Prioritized Frontend Backlog

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this backlog task-by-task. Each task is an independent review gate; do not combine tickets into one large change.

Goal: Implement the approved Magic Vault base-spin, win-presentation and Hold & Win flows as small, testable frontend increments.

Architecture: One presentation orchestrator owns phase order and delegates to independent reel, win, feature, HUD, audio, background and camera tracks. Backend responses remain authoritative; speed and Skip change presentation duration only. Work is delivered as vertical slices so every merged ticket leaves a playable, recoverable game.

Source: magic-vault-5x3-presentation-flow.md

#Global constraints

• Game ID is magic-vault-5x3; grid is 5 reels × 3 rows.
• Backend grid, wins, payout, balance and feature state are authoritative.
• One new paid spin uses one new Idempotency-Key; replay uses the same frozen request and key.
• Hold & Win steps have no additional wager and use the expected-step replay contract.
• Normal, Fast and Turbo share the same state transitions.
• Skip completes only the active presentation phase.
• Full Grid awards exactly Grand 500×, replacing the coin-prize sum.
• Line Win presentation exists only in the base game.
• No frontend payout, prize or wallet calculation is permitted.
• Existing reconnect behavior must remain functional after every ticket.
• Draft is DEV/demo only; no ticket enables stage, production or real-wallet play.

#Delivery order

P0 Foundation
  FE-MV-001 → FE-MV-002 → FE-MV-003 → FE-MV-004

P1 Base and Win
  FE-MV-005 → FE-MV-006 → FE-MV-007
  FE-MV-008 → FE-MV-009

P1 Hold & Win
  FE-MV-010 → FE-MV-011 → FE-MV-012 → FE-MV-013

P2 Polish and Operations
  FE-MV-014 → FE-MV-015 → FE-MV-016 → FE-MV-017

P3 Release Gate
  FE-MV-018

#P0 — Required foundation

#FE-MV-001: Presentation phase orchestrator

Priority: P0 Depends on: none

Outcome: A typed phase machine controls presentation order independently of backend request state and visual components.

Required states:

BOOT → RECOVERY_CHECK → IDLE → SPIN_REQUEST → REELS_SPINNING
→ ANTICIPATION? → REELS_STOPPING → RESULT_REVEAL
→ WIN_FLOW? → FEATURE_FLOW? → BALANCE_SETTLEMENT → IDLE

Scope:

• Define phase identifiers and allowed transitions.
• Separate authoritative round data from presentation-only state.
• Expose one phase-completion event consumed by the orchestrator.
• Reject invalid transitions in DEV with sanitized diagnostics.
• Preserve current session bootstrap and reconnect entry points.

Acceptance criteria:

• Every approved happy-path transition is executable in order.
• A feature cannot transition directly to a new paid spin.
• An invalid transition produces no request or wallet mutation.
• Reload can enter recovery without passing through paid-spin request.
• Unit tests cover the complete transition table.

Verification: phase-machine unit suite, invalid-transition tests, existing reconnect tests, typecheck, lint and production build.

#FE-MV-002: Parallel presentation track coordinator

Priority: P0 Depends on: FE-MV-001

Outcome: Reels, symbols, feature overlay, HUD, audio, background and camera can animate in parallel while one phase remains the sole ordering authority.

Scope:

• Define a cancellable phase context with completion and fast-forward signals.
• Register named tracks without letting tracks transition the machine directly.
• Wait for required tracks; allow decorative tracks to finish or be cancelled safely.
• Dispose timers, tick callbacks, particles and sounds when a phase exits.

Acceptance criteria:

• Required parallel tracks complete before the next phase.
• Decorative tracks cannot block progression indefinitely.
• Exiting a phase leaves no active timers or duplicate listeners.
• Re-entering a phase after recovery does not replay disposed effects.
• Track failures fail closed into the existing interrupted presentation state.

Verification: fake-clock tests, cancellation tests, listener/timer leak assertions and repeated phase-entry tests.

#FE-MV-003: Normal, Fast and Turbo timing profiles

Priority: P0 Depends on: FE-MV-002

Outcome: All presentation timings come from one immutable profile selected at phase start.

Required profiles:

Acceptance criteria:

• Changing speed affects the next phase, not one already in progress.
• State order is byte-for-byte/logically identical across all modes.
• Turbo retains reel stops, anticipation, landed prizes, respin changes and settlement.
• Timing tests use fake time and contain no wall-clock flakiness.

Verification: parameterized phase tests for all three profiles and full frontend suite.

#FE-MV-004: Global Skip and input-lock contract

Priority: P0 Depends on: FE-MV-002, FE-MV-003

Outcome: One input fast-forwards the active presentation without cancelling requests or advancing backend state.

Scope:

• Spin label becomes Stop during reel/feature motion and Skip during result presentation.
• Skip completes count-ups, reveals required symbols/prizes and retains minimum title holds.
• Bet and new-wager controls remain locked while a request or feature is unresolved.
• No whole-feature Skip is provided in Draft v0.1.

Acceptance criteria:

• Double click creates at most one paid request.
• Skip before response does not invent stop positions.
• Skip during feature intro still displays all initial prizes.
• Skip during a step still displays every newly_landed cell and new respin count.
• Skip during settlement shows the authoritative final award.

Verification: input-spam tests, pending-request tests and per-phase fast-forward tests.

#P1 — Base spin vertical slices

#FE-MV-005: Server-authoritative reel spin and stop

Priority: P1 Depends on: FE-MV-001 through FE-MV-004

Outcome: A paid response drives the visible 5×3 reel result through acceleration, loop and ordered stops.

Scope:

• Start reel motion with the paid request.
• Keep a neutral loop while waiting for the response.
• Stop left to right using only the returned grid.
• Add blur removal, overshoot, bounce, landing squash and reel-stop accents.
• Give COIN and WILD additional local accents.

Acceptance criteria:

• Final visible grid exactly equals the backend response.
• A delayed response extends the loop without fake stops.
• Reel stops remain ordered in every speed mode.
• Stop/Skip cannot create another request.
• Response validation failure never reveals a fabricated result.

Verification: deterministic grid fixture, delayed-response fixture, stop-order tests and visual snapshot/screenshot checks.

#FE-MV-006: Hold & Win anticipation on the base reels

Priority: P1 Depends on: FE-MV-005

Outcome: Five visible COIN before the final reel creates a readable but fast anticipation.

Scope:

• Detect the presentation condition from the already-known authoritative grid and stop order.
• Slow the last reel, pulse visible COIN, dim other symbols, illuminate the frame and run a riser.
• Resolve softly on a miss and into the feature sting on a trigger.

Acceptance criteria:

• Anticipation runs only when the sixth COIN remains possible on the final reel.
• A miss has no punitive failure effect.
• Turbo retains a 250–350 ms anticipation cue.
• Skip resolves directly to the authoritative final reel.
• Anticipation never changes trigger evaluation.

Verification: 5-COIN miss, 5-to-6 trigger and non-anticipation fixtures in all speed profiles.

#FE-MV-007: Base no-win and result routing

Priority: P1 Depends on: FE-MV-005, FE-MV-006

Outcome: Every stopped base result routes exactly once to no-win, line-win or feature flow.

Routing:

no payout + no feature → NO_WIN → IDLE
line payout only       → LINE_WIN
feature only           → FEATURE_TRIGGER
line payout + feature  → SHORT_LINE_WIN → FEATURE_TRIGGER

Acceptance criteria:

• No-win uses a short neutral hold and never displays LOSE.
• Line win and feature are not presented in the wrong order.
• Controls unlock only after the selected flow completes.
• One response produces one routing decision.
• Autoplay cannot begin the next paid spin while feature routing is pending.

Verification: table-driven routing tests for all four outcomes.

#P1 — Win flow

#FE-MV-008: Base Line Win presentation

Priority: P1 Depends on: FE-MV-007

Outcome: Base wins show all paylines together, then a short individual cycle.

Scope:

• Keep winning symbols bright and dim non-winning symbols.
• Trace every winning line together.
• Count the authoritative round payout.
• Cycle individual lines in Normal/Fast; Turbo may omit the cycle.
• Use round-level payout for Total Win; never sum wins[].payout.

Acceptance criteria:

• Line presentation is never used for feature settlement.
• All-line presentation precedes the individual cycle.
• The cycle never changes Total Win or Balance.
• Skip completes count-up and retains a 300–400 ms final hold.
• A simultaneous feature trigger uses the shortened base-win presentation.

Verification: single-line, multi-line, Turbo and line-plus-feature fixtures.

#FE-MV-009: Big, Mega, Ultra, Epic and Max Win

Priority: P1 Depends on: FE-MV-008

Outcome: Total-bet multiplier selects one consistent celebration shared by base and feature settlements.

Thresholds:

Acceptance criteria:

• Threshold boundaries are unit-tested exactly.
• Tier selection uses total bet, not line bet.
• Base and feature payouts use the same tier selector.
• Skip resolves to final title/amount with the approved minimum hold.
• Max/Grand cannot be visually skipped completely.
• Reduced-motion removes shake while preserving tier readability.

Verification: exact boundary fixtures at 9.99×, 10×, 25×, 50×, 100× and 500×.

#P1 — Hold & Win flow

#FE-MV-010: Trigger transition and initial locked grid

Priority: P1 Depends on: FE-MV-007, FE-MV-004

Outcome: A backend Hold & Win next_state transitions from the base reels to an authoritative 15-cell feature board.

Scope:

• Dim non-COIN symbols and flash triggering cells.
• Crossfade to the bonus background and feature HUD.
• Build cells in canonical column*3 + row order.
• Lift triggering COIN and reveal backend-provided prizes with speed-specific stagger.
• Store/retain the existing feature recovery checkpoint.

Acceptance criteria:

• Exactly 15 cells render in canonical order.
• Locked positions and prizes match next_state exactly.
• Frontend does not infer trigger or assign prizes.
• RESPINS 3 appears from the authoritative state.
• Skip reveals the complete initial board and every prize.
• No new paid request can start while the feature is open.

Verification: recorded 6-COIN and 7-COIN trigger fixtures plus serialized response drift tests.

#FE-MV-011: Hold & Win step animation

Priority: P1 Depends on: FE-MV-010

Outcome: Empty cells spin while locked cells remain fixed; miss and landing responses update the board once.

Scope:

• Send the expected feature-step index with no new wager.
• Animate only empty cells.
• Use newly_landed for one-time landing effects.
• Animate miss decrement and landing reset to three.
• Handle one, two and three-or-more simultaneous landings.

Acceptance criteria:

• Feature-step wallet bet is zero.
• Locked cells never spin or lose prizes.
• Miss decrements by one without negative failure effects.
• Any landing resets the visible counter to three.
• Duplicate/replayed step does not reanimate an already-consumed landing.
• Skip leaves the complete authoritative snapshot visible.

Verification: miss, single landing, multi-landing, reset and duplicate-step fixtures.

#FE-MV-012: Fixed prizes and last-respin presentation

Priority: P1 Depends on: FE-MV-011

Outcome: Mini, Minor, Major and last-respin events are distinct without delaying the fast loop.

Scope:

• Mini 10×: turquoise local ring.
• Minor 25×: violet burst and short cell focus.
• Major 100×: gold impact, short zoom and unique sting.
• Last respin: counter, frame and empty-cell tension pulse.
• Keep regular 10× visually distinct from prize kind Mini 10×.

Acceptance criteria:

• Presentation selects by backend prize kind, not value alone.
• Regular 10× never receives Mini presentation.
• Major can be skipped only to its final locked state and minimum hold.
• Last-respin presentation does not alter duration or outcome.
• Turbo retains a compressed cue for each event.

Verification: one fixture for regular 10×, Mini, Minor, Major and last-respin state.

#FE-MV-013: Settlement, Grand and return to base

Priority: P1 Depends on: FE-MV-009, FE-MV-011, FE-MV-012

Outcome: Ordinary and Full Grid endings reconcile one authoritative award and return cleanly to the base game.

Scope:

• Collect locked prizes in grouped visual waves.
• Count to the backend feature award.
• Route through shared win tiers.
• Full Grid pulses all 15 cells, closes the vault and shows Grand/Max Win.
• Clear feature recovery only after settlement.
• Restore base background, HUD, reels and controls.

Acceptance criteria:

• Ordinary award equals backend settlement payout.
• Full Grid displays exactly Grand 500×.
• UI never adds individual prize sum to Grand.
• Settlement animation does not credit Balance locally.
• Recovery checkpoint is cleared only after authoritative settlement.
• Autoplay resumes only after return-to-base completion.

Verification: ordinary, capped ordinary, Full Grid, skipped settlement and autoplay-resume fixtures.

#P2 — Polish and operational behavior

#FE-MV-014: Audio event system

Priority: P2 Depends on: FE-MV-005, FE-MV-009, FE-MV-013

Outcome: Phase events drive layered, cancellable audio without duplicated or abruptly cut samples.

Acceptance criteria:

• Reel-stop pitch progresses from reel 1 through reel 5.
• COIN and WILD accents layer over mechanical stops.
• Anticipation resolves cleanly for miss and trigger.
• Simultaneous coin landings use one group impact plus light accents.
• Important stings duck ambience by 25–40%.
• Turbo selects short assets/envelopes rather than truncating long samples.

Verification: event-routing unit tests and manual audio QA matrix for all speed modes.

#FE-MV-015: Particles, camera and backgrounds

Priority: P2 Depends on: FE-MV-005 through FE-MV-013

Outcome: Visual polish follows the approved hierarchy and never hides state or controls.

Acceptance criteria:

• Particles render in behind-board, board-local and foreground layers.
• No effect covers prizes, respin counter, Win, controls or errors.
• Camera effects are event-based and never continuous.
• Base/bonus background transition survives Skip and reconnect.
• Disposing a phase removes its particles and camera offset.

Verification: screenshot matrix, layer-order assertions and repeated-transition leak test.

#FE-MV-016: Autoplay and error orchestration

Priority: P2 Depends on: FE-MV-004, FE-MV-007, FE-MV-013

Outcome: Autoplay respects paid-operation, feature, recovery and settlement boundaries.

Acceptance criteria:

• Paid autoplay pauses while a feature is open.
• Feature steps may progress automatically but are never skipped server-side.
• Autoplay stops on insufficient balance, unresolved recovery, conflict, unsupported feature, state mismatch, Max Win or player stop.
• A delayed request shows WAITING FOR SERVER without fabricated state.
• Player-facing errors contain no raw backend internals or credentials.

Verification: autoplay stop-condition table, delayed-response tests and sanitized-error tests.

#FE-MV-017: Reduced motion and adaptive performance

Priority: P2 Depends on: FE-MV-014, FE-MV-015

Outcome: Reduced-motion and low-performance modes preserve every essential state cue.

Degradation order: foreground particles, ambient particles, blur, complex glow.

Acceptance criteria:

• Reduced motion removes shake and strong zoom.
• Reel stops, triggers, landed cells, prizes, counters and settlement remain readable.
• Adaptive quality never changes the phase machine or backend request timing.
• Resize/background-tab transitions preserve logical cells and active recovery state.

Verification: reduced-motion snapshots, forced-low-FPS profile and resize/visibility tests.

#P3 — Final integration gate

#FE-MV-018: End-to-end presentation verification

Priority: P3 Depends on: FE-MV-001 through FE-MV-017

Outcome: One evidence pack proves the approved flow on DEV/demo without changing math or production state.

Required scenarios:

1. Base no win.
2. Single and multiple line wins.
3. Five-COIN anticipation miss.
4. Six-COIN Hold & Win trigger.
5. Trigger with simultaneous base line win.
6. Hold & Win miss, one landing and multiple landing.
7. Mini, Minor, Major and regular 10× distinction.
8. Last respin and ordinary settlement.
9. Full Grid Grand 500×.
10. Skip in every phase.
11. Normal, Fast and Turbo.
12. Reload/reconnect mid-feature.
13. Ambiguous paid-spin replay.
14. Reduced-motion and low-performance modes.

Acceptance criteria:

• Displayed grid, payout, balance and feature snapshot match captured backend responses.
• No duplicate wager, feature step, landing animation or payout occurs.
• Wallet arithmetic reconciles for every wagered scenario.
• Feature steps show zero additional wager.
• Lint, typecheck, unit/integration tests and production build pass.
• No protected math config, RNG or parity vector changes.
• Stage/prod flags and real wallets remain untouched.

Verification artifacts: sanitized request/response fixtures, screenshots or short captures for each speed mode, test logs, build result and a checklist mapped to the presentation-flow sections.

#Shared definition of done

Every ticket must satisfy all applicable items before merge:

• RED test or failing fixture observed before implementation.
• Focused tests pass.
• Full affected frontend suite passes.
• Typecheck, lint and production build pass.
• git diff --check is clean.
• Only ticket-scoped files are staged.
• Existing reconnect tests remain green.
• No frontend payout or wallet calculation is introduced.
• No stage/prod, backend flag or canonical math change is included.
• Commit and review evidence reference the ticket ID.