docs(01-12): complete Players Tab + Buy-In/Bust-Out Flows plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/STATE.md

@@ -8,7 +8,7 @@ progress:
   total_phases: 1
   completed_phases: 0
   total_plans: 14
-  completed_plans: 11
+  completed_plans: 12
 ---
 
 # Project State
@@ -23,27 +23,27 @@ See: .planning/PROJECT.md (updated 2026-02-28)
 ## Current Position
 
 Phase: 1 of 7 (Tournament Engine)
-Plan: 12 of 14 in current phase
+Plan: 13 of 14 in current phase
 Status: Executing Phase 1
-Last activity: 2026-03-01 — Completed Plan 09 (Tournament Lifecycle + Multi-Tournament + Chop/Deal)
+Last activity: 2026-03-01 — Completed Plan 12 (Frontend Players Tab + Buy-In/Bust-Out Flows)
 
-Progress: [████████░░] 79%
+Progress: [████████▓░] 86%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 11
+- Total plans completed: 12
 - Average duration: 10min
-- Total execution time: 1.75 hours
+- Total execution time: 1.88 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
-| 01-tournament-engine | 11 | 105min | 10min |
+| 01-tournament-engine | 12 | 113min | 9min |
 
 **Recent Trend:**
-- Last 5 plans: 01-13 (5min), 01-06 (9min), 01-08 (6min), 01-07 (7min), 01-09 (25min)
+- Last 5 plans: 01-12 (8min), 01-13 (5min), 01-06 (9min), 01-08 (6min), 01-07 (7min)
 - Trend: steady
 
 *Updated after each plan completion*
@@ -105,6 +105,10 @@ Recent decisions affecting current work:
 - [01-09]: Full chop sets all players to 'deal' status and completes tournament; partial chop continues play
 - [01-09]: Tournament auto-close: 1 remaining = EndTournament, 0 remaining = CancelTournament
 - [01-09]: Integration tests use file-based DB with WAL mode for clock ticker goroutine compatibility
+- [01-12]: Flow overlays use fixed full-screen z-index 100 positioning (modal-like, not route-based)
+- [01-12]: BustOutFlow uses grid table picker then seat tap for minimal taps under time pressure
+- [01-12]: RebuyFlow/AddOnFlow preselectedPlayer prop skips search step for direct launch from PlayerDetail
+- [01-12]: FAB actions in layout wired to actual flow overlays (replacing placeholder toasts)
 
 ### Pending Todos
 
@@ -122,5 +126,5 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-03-01
-Stopped at: Completed 01-09-PLAN.md (Tournament Lifecycle + Multi-Tournament + Chop/Deal)
+Stopped at: Completed 01-12-PLAN.md (Frontend Players Tab + Buy-In/Bust-Out Flows)
 Resume file: None

.planning/phases/01-tournament-engine/01-12-SUMMARY.md

@@ -0,0 +1,149 @@
+---
+phase: 01-tournament-engine
+plan: 12
+subsystem: ui
+tags: [svelte, sveltekit, player-management, buy-in, bust-out, rebuy, addon, touch-ui]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine
+    provides: Player management API (Plan G), seating engine API (Plan H), UI shell (Plan J/K)
+provides:
+  - PlayerSearch typeahead component
+  - BuyInFlow step-by-step wizard
+  - BustOutFlow minimal-tap flow
+  - PlayerDetail per-player tracking panel
+  - RebuyFlow quick 2-tap flow
+  - AddOnFlow with mass add-on option
+  - Players page with Active/Busted/All tabs
+  - FAB actions wired to actual tournament flows
+affects: [frontend, tournament-operations, player-experience]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [flow-overlay-pattern, step-wizard-pattern, tap-tap-interaction]
+
+key-files:
+  created:
+    - frontend/src/lib/components/PlayerSearch.svelte
+    - frontend/src/lib/components/BuyInFlow.svelte
+    - frontend/src/lib/components/BustOutFlow.svelte
+    - frontend/src/lib/components/PlayerDetail.svelte
+    - frontend/src/lib/components/RebuyFlow.svelte
+    - frontend/src/lib/components/AddOnFlow.svelte
+  modified:
+    - frontend/src/routes/players/+page.svelte
+    - frontend/src/routes/+layout.svelte
+
+key-decisions:
+  - "Flow overlays use fixed full-screen positioning (z-index 100) for modal-like behavior"
+  - "BuyInFlow uses 3-step wizard with mini table diagram for seat visualization"
+  - "BustOutFlow uses grid table picker then seat tap for minimal taps under time pressure"
+  - "RebuyFlow and AddOnFlow support preselectedPlayer prop for direct launch from PlayerDetail"
+  - "FAB actions in layout now trigger actual flow overlays instead of placeholder toasts"
+  - "DataTable receives Player[] cast as Record<string,unknown>[] for type compatibility"
+
+patterns-established:
+  - "Flow overlay pattern: full-screen fixed overlay with header (back/close) + step content"
+  - "Step wizard pattern: step indicator + content per step, goBack() method for navigation"
+  - "Preselected entity pattern: optional prop to skip search step in quick flows"
+
+requirements-completed: [PLYR-04, PLYR-05, PLYR-07]
+
+# Metrics
+duration: 8min
+completed: 2026-03-01
+---
+
+# Plan 12: Frontend Players Tab + Buy-In/Bust-Out Flows Summary
+
+**Touch-optimized Players tab with step-by-step buy-in wizard, minimal-tap bust-out flow, full player detail tracking, and quick rebuy/add-on flows via FAB and player detail**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-03-01T07:15:08Z
+- **Completed:** 2026-03-01T07:23:17Z
+- **Tasks:** 1 (with 6 sub-components)
+- **Files modified:** 8
+
+## Accomplishments
+- PlayerSearch with debounced typeahead, 48px touch rows, "Add New Player" option, recently active when empty
+- BuyInFlow 3-step wizard: search player, auto-seat with mini table diagram + override, confirm with green button
+- BustOutFlow minimal-tap flow: table grid, oval seat picker, verify with avatar, hitman selection (same table + search all)
+- PlayerDetail with status/location/chips, financial stats, action history, undo buttons for bust/buyin/rebuy
+- RebuyFlow and AddOnFlow with 2-tap quick flow, preselected player support, mass add-on all option
+- Players page with Active/Busted/All segmented tabs, DataTable with search and swipe actions
+- Layout FAB now launches actual flow overlays with clock pause/resume via API
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task L1: Players tab with buy-in and bust-out flows** - `44b555d` (feat)
+
+**Plan metadata:** [pending] (docs: complete plan)
+
+## Files Created/Modified
+- `frontend/src/lib/components/PlayerSearch.svelte` - Typeahead player search with debounce, touch targets, recent players
+- `frontend/src/lib/components/BuyInFlow.svelte` - 3-step buy-in wizard with auto-seat and mini table diagram
+- `frontend/src/lib/components/BustOutFlow.svelte` - Minimal-tap bust-out flow with table grid and seat picker
+- `frontend/src/lib/components/PlayerDetail.svelte` - Full per-player tracking panel with undo actions
+- `frontend/src/lib/components/RebuyFlow.svelte` - Quick rebuy flow with preselected player support
+- `frontend/src/lib/components/AddOnFlow.svelte` - Quick add-on flow with mass add-on all option
+- `frontend/src/routes/players/+page.svelte` - Players page with Active/Busted/All tabs and overlay flows
+- `frontend/src/routes/+layout.svelte` - FAB actions wired to actual flows, clock pause/resume
+
+## Decisions Made
+- Flow overlays use fixed full-screen positioning (z-index 100) for modal-like behavior rather than routes
+- BuyInFlow uses 3-step wizard with mini table diagram for seat visualization (auto-seat preview)
+- BustOutFlow uses grid table picker then seat tap for minimal taps under time pressure
+- RebuyFlow and AddOnFlow support preselectedPlayer prop for direct launch from PlayerDetail
+- FAB actions in layout now trigger actual flow overlays instead of placeholder toasts
+- DataTable receives Player[] cast as Record<string,unknown>[] for type compatibility
+- Svelte 5 $effect used for preselectedPlayer initialization to avoid state_referenced_locally warnings
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed Svelte 5 {@const} placement in BuyInFlow**
+- **Found during:** Task L1 (BuyInFlow component)
+- **Issue:** {@const} tag placed inside HTML div element instead of Svelte block
+- **Fix:** Wrapped in additional {#if} block so {@const} is direct child of Svelte control flow
+- **Files modified:** frontend/src/lib/components/BuyInFlow.svelte
+- **Verification:** svelte-check passes with zero errors in our files
+- **Committed in:** 44b555d (Task L1 commit)
+
+**2. [Rule 1 - Bug] Fixed state_referenced_locally warnings in RebuyFlow/AddOnFlow**
+- **Found during:** Task L1 (RebuyFlow, AddOnFlow components)
+- **Issue:** Initializing $state from prop value captures initial value only
+- **Fix:** Used $effect to set state from prop, initializing state to defaults
+- **Files modified:** frontend/src/lib/components/RebuyFlow.svelte, frontend/src/lib/components/AddOnFlow.svelte
+- **Verification:** svelte-check shows no warnings for these files
+- **Committed in:** 44b555d (Task L1 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 bugs)
+**Impact on plan:** Both auto-fixes necessary for correct Svelte 5 compilation. No scope creep.
+
+## Issues Encountered
+None beyond the auto-fixed items above.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Players tab with all flows is complete and ready for integration testing
+- FAB actions are now wired to real flows throughout the app
+- Pre-existing errors in BubblePrize.svelte and DealFlow.svelte are not affected by this plan
+
+## Self-Check: PASSED
+
+All 9 files verified present. Commit 44b555d verified in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*