Full-codebase commenting pass focused on the tricky, fragile, and
non-obvious spots: animation coordination flags in app.js, AI decision
safety checks in ai.py, scoring evaluation order in game.py, animation
engine magic numbers in card-animations.js, and server infrastructure
coupling in main.py/handlers.py/room.py. No logic changes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Increase post_draw_settle timing (1.1s→1.3s) and swap retry delay
(100ms→350ms) to prevent draw animation from being cut short by the
arriving swap animation. Also make CPU go-out decisions consider
opponent scores and avoid swapping high cards (8+) into hidden slots.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fix dumb AI knocks (e.g. Maya knocking on 13 points) by adding opponent
threat checks and a hard cap of 10 to should_knock_early(). Remove dead
should_go_out_early() call whose return value was never used. Retune knock
chance tiers to be more conservative at higher projected scores.
On the client side, fix round-end reveal sequencing so the last player's
swap/discard animation plays before the reveal sequence starts, and prevent
re-renders from clobbering swap animations during reveals. Also make the
turn-pulse shake configurable via timing-config and target only cards.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Convert CPU turn chain to a cancellable asyncio.Task tracked on Room,
so ending the game or leaving no longer blocks waiting for CPU sleeps.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Tighten should_knock_early() so AI no longer knocks with projected
scores of 12-14. New range: max_acceptable 5-9 (was 8-18), with
scaled knock_chance by score quality and an exception when all
opponents show 25+ visible points.
Fix 5 pre-existing test failures:
- test_event_replay: use game.current_player() instead of hardcoding
"p1", since dealer logic makes p2 go first
- game.py: include current_player_idx in round_started event so state
replay knows the correct starting player
- test_house_rules: rename test_rule_config → run_rule_config so
pytest doesn't collect it as a test fixture
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Break the 666-line choose_swap_or_discard into 8 focused sub-functions,
extract named constants for ~15 magic numbers, add column/pair utility
functions (iter_columns, project_score, count_hidden, hidden_positions),
and extract _log_cpu_action helper to reduce logging boilerplate in
process_cpu_turn. No behavior changes - validated with simulate.py 500.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Prevent CPU players from swapping 8+ value cards (8, 9, 10, J, Q) into
face-down positions, which is statistically bad since expected hidden
card value is ~4.5.
Fixes applied:
- Add value threshold (7) to unpredictability random swap path
- Restrict comeback bonus to cards with value < 8
- Reduce speculative wolfpack Jack bonus from 6x to 2x aggression
- Add safety filter to remove hidden positions for 8+ cards
- Fix endgame logic to discard 8+ instead of forcing swap into hidden
- Skip hidden positions in denial candidate list for 8+ cards
- Add swapped_high_into_unknown tracking to SimulationStats
Reduces "swapped 8+ into unknown" dumb moves from ~85 per 200 games
to ~6 per 500 games (0.054% rate, down from ~2%).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
AI now considers the next player's visible cards before discarding:
- Checks if discarding would give opponent a pair opportunity
- Calculates denial value based on card value and game phase
- May keep a worse card to deny opponent when cost is acceptable
- Denial threshold varies by AI personality (aggression)
Also updates simulation to recognize denial as a valid reason for
swapping good cards, preventing false "swapped good for bad" flags.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Animation fixes:
- Fix held card positioning bug (was appearing at bottom of page)
- Fix discard pile blank/white flash on turn transitions
- Fix blank card at round end by skipping animations during round_over/game_over
- Set card content before triggering flip animation to prevent flash
- Center suit symbol on 10 cards
Timing improvements:
- Reduce post-discard delay from 700ms to 500ms
- Reduce post-swap delay from 1800ms to 1000ms
- Speed up swap flip animation from 1150ms to 550ms
- Reduce CPU initial thinking delay from 150-250ms to 80-150ms
- Pause now happens after swap completes (showing result) instead of before
E2E test suite:
- Add Playwright-based test bot that plays full games
- State parser extracts game state from DOM for validation
- AI brain ports decision logic for automated play
- Freeze detector monitors for UI hangs
- Visual validator checks CSS states
- Full game, stress, and visual test specs
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Early Knock variant: flip all remaining cards (≤2) to go out early
- Update RULES.md with comprehensive documentation for all new variants
- Shorten flip mode dropdown descriptions for cleaner UI
- Add try-catch and optional chaining in startGame() for robustness
- Add WebSocket connection error feedback with reject sound
- AI awareness for Early Knock decisions
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Opponent draw highlight: scale + outline flash animation
- House rules reorganized: Gameplay, Jokers, Card Values, Bonuses & Penalties
- Compact inline rule descriptions with alternating suit separators (♣♦♠♥)
- Wolfpack + Four of a Kind combo note when both selected
- Toast notifications now yellow/green with charcoal text
- Brief pause after AI draw for visual feedback
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add big final results modal at game end with rankings and share button
- Add active rules bar showing enabled variants during gameplay
- Increase spacing between player cards and opponents row
- Add Wolfpack bonus rule (2 pairs of Jacks = -5 pts)
- Change joker options to radio buttons (None/Standard/Lucky Swing/Eagle-Eye)
- Update Eagle-Eye jokers: +2 pts unpaired, -4 pts paired
- Add card flip animation on discard pile
- Redesign waiting room layout with side-by-side columns
- Style card backs with red Bee-style diamond crosshatch pattern
- Compact standings panel to show top 4 per category
- Various CSS polish and responsive improvements
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add constants.py as the single source of truth for card values
- Derive RANK_VALUES from DEFAULT_CARD_VALUES instead of duplicating
- Add centralized get_card_value() function in game.py for Card objects
- Add get_card_value_for_rank() in constants.py for string-based lookups
- Fix bug: AI ten_penny returned 0 instead of 1 per RULES.md
- Update ai.py and game_analyzer.py to use centralized functions
- UI improvements for client
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Features:
- Multiplayer WebSocket game server (FastAPI)
- 8 AI personalities with distinct play styles
- 15+ house rule variants
- SQLite game logging for AI analysis
- Comprehensive test suite (80+ tests)
AI improvements:
- Fixed Maya bug (taking bad cards, discarding good ones)
- Personality traits influence style without overriding competence
- Zero blunders detected in 1000+ game simulations
Testing infrastructure:
- Game rules verification (test_game.py)
- AI decision analysis (game_analyzer.py)
- Score distribution analysis (score_analysis.py)
- House rules testing (test_house_rules.py)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
