felt/.planning/phases/01-tournament-engine/01-PLAN-L.md

# Plan L: Frontend — Players Tab + Buy-In/Bust-Out Flows

---
wave: 6
depends_on: [01-PLAN-M, 01-PLAN-G, 01-PLAN-I]
files_modified:
  - frontend/src/routes/players/+page.svelte
  - frontend/src/lib/components/PlayerSearch.svelte
  - frontend/src/lib/components/BuyInFlow.svelte
  - frontend/src/lib/components/BustOutFlow.svelte
  - frontend/src/lib/components/PlayerDetail.svelte
autonomous: true
requirements: [PLYR-04, PLYR-05, PLYR-07]
---

## Goal

The Players tab shows all tournament players with search, buy-in flow, bust-out flow, and player detail. All flows are optimized for minimal taps — the TD is under time pressure during a running tournament.

## Context

- **Player management API** — Plan G (search, buy-in, bust-out, undo, rankings)
- **Seating engine API** — Plan H (tables, auto-seat, balancing, break table)
- **Template API** — Plan E (building blocks, templates, wizard)
- **UI shell** — Plan J (layout, data table, FAB, toast)
- **All flows use tap-tap pattern** — no drag-and-drop in Phase 1

## User Decisions (from CONTEXT.md)

- **Buy-in flow:** search/select player → auto-seat suggests optimal seat → TD can override → confirm → receipt
- **Bust-out flow:** tap Bust → pick table → pick seat → verify name → confirm → select hitman → done
- **Bust-out flow must be as few taps as possible**
- **Oval table view (default)** — top-down with numbered seats, switchable to list view
- **Balancing is TD-driven, system-assisted** — 2-tap recording (source seat, destination seat)
- **Break Table is fully automatic**
- **Template building blocks feel like LEGO**
- **No drag-and-drop in Phase 1** — tap-tap for all moves
- **Structure wizard** lives in template management

## Tasks

<task id="L1" title="Implement Players tab with buy-in and bust-out flows">
**1. Player Search** (`frontend/src/lib/components/PlayerSearch.svelte`):
- Typeahead input: as TD types, results appear below (debounced 200ms)
- Results show: name, nickname (if set), last tournament date
- Tap a result to select
- "Add New Player" option at bottom if no match
- 48px result rows for touch targets
- Quick search: when empty, show recently active players

**2. Buy-In Flow** (`frontend/src/lib/components/BuyInFlow.svelte`) — PLYR-04:
- Step-by-step flow (each step is a single screen):
  1. **Search/Select Player**: PlayerSearch component → select player
  2. **Auto-Seat Preview**: system suggests table + seat → TD can accept or tap a different seat
     - Show mini table diagram highlighting suggested seat
     - "Override" button → shows all available seats
  3. **Confirm**: summary card showing player name, table, seat, buy-in amount, chips
     - Big "Confirm Buy-In" button (48px, green)
  4. **Receipt**: brief confirmation toast + receipt data available
- Late registration indicator: if cutoff approaching, show warning
- Late registration override: if past cutoff, show admin override option (logged in audit)
- Bonuses: show if early signup or punctuality bonus applies
- Triggered from: FAB "Buy In" action, or Players tab "+" button

**3. Bust-Out Flow** (`frontend/src/lib/components/BustOutFlow.svelte`) — PLYR-05:
- Optimized for minimum taps:
  1. **Pick Table**: grid of active tables (large tap targets), each showing table name + player count
  2. **Pick Seat**: oval table view of selected table, tap the seat of the busted player
  3. **Verify**: confirmation card: "Bust [Player Name]?" with player photo/avatar
     - Big "Confirm Bust" button (48px, red)
  4. **Select Hitman** (PKO mandatory, otherwise optional):
     - List of active players at the same table (most likely hitman)
     - "Other" option → search all active players
     - "Skip" option (non-PKO only)
  5. **Done**: toast notification "Player Name busted — 12th place"
- Auto-ranking happens in background
- Balance check: if tables become unbalanced, show notification
- Triggered from: FAB "Bust" action

**4. Player Detail** (`frontend/src/lib/components/PlayerDetail.svelte`) — PLYR-07:
- Full player tracking within tournament:
  - Current status (active/busted)
  - Current seat (Table X, Seat Y)
  - Chip count
  - Playing time
  - Buy-in time
  - Rebuys: count and total amount
  - Add-ons: count and total amount
  - Bounties collected (with hitman chain details for PKO)
  - Prize amount
  - Points awarded
  - Net take (prize - total investment)
  - Action history (from audit trail): chronological list of all actions
- Undo buttons on applicable actions (bust, rebuy, addon, buyin)

**5. Players Page** (`frontend/src/routes/players/+page.svelte`):
- Tab layout: "Active" | "Busted" | "All"
- DataTable (from Plan J) showing:
  - Active: Name, Table/Seat, Chips, Rebuys, Status
  - Busted: Name, Position, Bust Time, Hitman, Prize
  - All: Name, Status, Chips/Position, Net
- Search bar at top (filter current list)
- Tap row → Player Detail
- "Buy In" button at top (alternative to FAB)
- Swipe actions: Bust (active players), Undo Bust (busted players)

**6. Rebuy/Add-On Flows:**
- Rebuy: triggered from FAB or player detail
  - Select player (show only eligible — active, under chip threshold, within cutoff)
  - Confirm rebuy amount and chips
  - Quick flow: 2 taps (select + confirm)
- Add-On: similar quick flow
  - Show only during addon window
  - "Add-On All" option for break-time mass add-ons (one-by-one confirmation)

**Verification:**
- Buy-in flow: search → auto-seat → confirm → receipt in minimal taps
- Bust-out flow: table → seat → verify → hitman → done in minimal taps
- Player detail shows all tracking stats
- Player list with tabs (Active/Busted/All) and search
- Undo works from player detail
</task>

## Verification Criteria

1. Buy-in flow completes in minimal taps with auto-seat
2. Bust-out flow completes in minimal taps with hitman selection
3. Player detail shows full per-player tracking stats (PLYR-07)
4. Player list with Active/Busted/All tabs and search
5. Undo works from player detail view
6. Rebuy and add-on quick flows work from FAB and player detail

## Must-Haves (Goal-Backward)

- [ ] Buy-in flow: search → auto-seat → confirm → receipt (minimal taps)
- [ ] Bust-out flow: table → seat → verify → hitman → done (minimal taps, TD under time pressure)
- [ ] Player detail with complete tracking data
- [ ] All flows optimized for touch (48px targets, no drag-and-drop)