PokeR/openspec/changes/archive/2025-05-17-foundational-pokertable/tasks.md

1. Project Structure & Types

• 1.1 Create directory structure: src/lib/types/, src/lib/game/, src/lib/components/, src/lib/utils/
• 1.2 Define TypeScript types: Card (suit, rank), Suit, Rank enums in src/lib/types/card.ts
• 1.3 Define PlayerSeat interface with ID, name, chips, currentBet, status, holeCards, position in src/lib/types/player.ts
• 1.4 Define GameState interface with deck, players, communityCards, pot, dealerPosition, currentTurn, bettingRound, actionHistory in src/lib/types/game-state.ts
• 1.5 Define Action type (Check, Call, Raise, Fold, AllIn) in src/lib/types/action.ts

2. Game Engine Foundation

• 2.1 Implement createDeck() function that generates a 52-card deck in src/lib/game/deck.ts
• 2.2 Implement shuffleDeck(deck) function using Fisher-Yates algorithm in src/lib/game/deck.ts
• 2.3 Implement dealHoleCards(deck, players) pure function that deals 2 cards per active player in src/lib/game/dealing.ts
• 2.4 Implement dealCommunityCards(deck, count) for flop (3), turn (1), river (1) in src/lib/game/dealing.ts
• 2.5 Implement postBlinds(state) pure function that deducts small/big blind from correct players in src/lib/game/blinds.ts

3. Betting Logic

• 3.1 Implement getNextActivePlayer(state) helper for clockwise turn advancement in src/lib/game/turn.ts
• 3.2 Implement validateAction(playerId, action, state) function with fold/call/raise rules in src/lib/game/validation.ts
• 3.3 Implement applyCheck(state, playerId) pure function returning new state in src/lib/game/actions.ts
• 3.4 Implement applyCall(state, playerId) pure function returning new state in src/lib/game/actions.ts
• 3.5 Implement applyRaise(state, playerId, amount) pure function with min-raise validation in src/lib/game/actions.ts
• 3.6 Implement applyFold(state, playerId) pure function that marks player as folded in src/lib/game/actions.ts
• 3.7 Implement applyAllIn(state, playerId) pure function that posts remaining chips in src/lib/game/actions.ts
• 3.8 Implement completeBettingRound(state) to detect when all active players have matched bets and advance to next street in src/lib/game/betting-round.ts

4. Hand Evaluation

• 4.1 Implement suit/rank constants and comparison utilities in src/lib/utils/ranks.ts
• 4.2 Implement evaluateHand(7 cards) function that returns hand rank (high card through royal flush) in src/lib/utils/hand-evaluator.ts
• 4.3 Implement tiebreaker logic for same-rank hands using kicker comparison in src/lib/utils/hand-evaluator.ts
• 4.4 Implement determineWinner(state) function that evaluates all active players and awards pot in src/lib/game/showdown.ts

5. Game State Management

• 5.1 Implement createInitialState(numPlayers, startingStack) factory function in src/lib/game/state.ts
• 5.2 Implement startNewHand(state) pure function: shuffle deck, post blinds, deal hole cards, reset bets in src/lib/game/hand.ts
• 5.3 Implement rotateDealer(state) to advance dealer button clockwise in src/lib/game/state.ts
• 5.4 Implement recordAction(state, playerId, action) to append to action history in src/lib/game/state.ts

6. Card Component

• 6.1 Create Card.svelte component with props: card (Card), flipped (boolean), animateDeal (boolean) in src/lib/components/Card.svelte
• 6.2 Implement card face rendering with suit symbols and rank display, colored red/black by suit in Card.svelte
• 6.3 Implement card back pattern styling in Card.svelte scoped CSS
• 6.4 Add CSS 3D flip animation using transform: rotateY(180deg) and backface-visibility: hidden in Card.svelte
• 6.5 Add Svelte flip() spring animation for deal transitions in Card.svelte
• 6.6 Add hover elevation effect via CSS transition on scoped styles in Card.svelte
• 6.7 Define shared card dimension CSS custom properties (--card-width, --card-height, --card-radius) in a global style file

7. Player Seat Component

• 7.1 Create PlayerSeat.svelte component with props: player (PlayerSeat), isCurrentTurn, isHuman in src/lib/components/PlayerSeat.svelte
• 7.2 Render player name, chip count, and current bet amount in PlayerSeat.svelte
• 7.3 Render hole cards using Card component with flip state based on visibility rules in PlayerSeat.svelte
• 7.4 Add visual indicator for current turn (highlight/glow) in PlayerSeat.svelte
• 7.5 Add folded player styling (dimmed, semi-transparent) in PlayerSeat.svelte

8. Poker Table UI

• 8.1 Create PokerTable.svelte component with CSS Grid oval layout for up to 9 seats in src/lib/components/PokerTable.svelte
• 8.2 Implement seat positioning using CSS Grid areas arranged in oval pattern in PokerTable.svelte
• 8.3 Render community card area in table center with dynamic card display in PokerTable.svelte
• 8.4 Add pot display component in table center showing current pot value in PokerTable.svelte
• 8.5 Implement dealer button indicator positioned at current dealer seat in PokerTable.svelte

9. Action Controls

• 9.1 Create BetControls.svelte component with Check, Call, Raise, Fold, All-In buttons in src/lib/components/BetControls.svelte
• 9.2 Implement conditional button visibility based on current game state (check vs call logic) in BetControls.svelte
• 9.3 Add raise amount input with min/max validation in BetControls.svelte
• 9.4 Wire button clicks to dispatch action events to parent component in BetControls.svelte

10. Integration & Page Assembly

• 10.1 Replace src/routes/+page.svelte with poker game page that composes PokerTable, PlayerSeat, and BetControls
• 10.2 Initialize game state using Svelte 5 $state rune in the page component
• 10.3 Wire human player actions from BetControls to game engine pure functions, updating reactive state
• 10.4 Implement basic AI opponent logic: random valid action selection with small delay between turns
• 10.5 Add "New Hand" button to start next hand after showdown completion
• 10.6 Update src/routes/+layout.svelte with dark background suitable for poker table aesthetic
• 10.7 Manual playtest: verify full hand flow from deal through showdown with all betting rounds