belote-cli 1.1.0__tar.gz → 2.5.2__tar.gz

{belote_cli-1.1.0 → belote_cli-2.5.2}/.claude/settings.local.json

@@ -7,7 +7,9 @@
       "Bash(python3 -m ruff check src/ --statistics)",
       "Bash(python3 -m mypy src/belote/ --ignore-missing-imports)",
       "Bash(python3 -m pytest tests/ -q --tb=short)",
-      "Bash(python3 -m pytest tests/ -q --tb=no)"
+      "Bash(python3 -m pytest tests/ -q --tb=no)",
+      "Bash(python3 -m pytest tests/ -x -q)",
+      "Bash(PYTHONPATH=src python3 *)"
     ]
   }
 }

{belote_cli-1.1.0 → belote_cli-2.5.2}/CHANGELOG.md

@@ -5,7 +5,183 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.5.2] - 2026-05-02
+
+### Fixed
+- **Critical Winner Detection Bug**: Resolved an issue in `game.py` where trick wins were assigned to the wrong player.
+- **Scoring Engine Desync**: Fixed a major bug in `round_driver.py` where trick points were being calculated manually, leading to desyncs with boss modifiers. Now uses a direct state differential from the core engine.
+- **Declaration Scoring**: Realized actual point values for sequences and carrés in `round_driver.py` using the official scoring utilities.
+
+### Added
+- **Partner Trust Integration**: Fully wired the trust system into the BelAtro run loop. Trust now increases on blind beats and big wins, and decreases on failures or chutes.
+- **AI Personalities in Bidding**: The partner AI now uses its assigned personality (e.g., *Le Courageux*, *L'Économe*) to make bidding decisions, respecting trust levels.
+- **Dynamic Partner Hand Visibility**: The partner's hand now automatically becomes visible to the player once the "shares void info" trust threshold is met.
+- **Performance Cache Invalidation**: Added targeted cache clearing after boss modifier application to ensure game logic remains accurate and performant.
+
+## [2.5.1] - 2026-05-02
+
+### Added
+- **BelAtro Collection Discovery**: Items are now only revealed in the collection when actually encountered in-game, rather than immediately upon unlocking.
+- **Auto-Save Persistence**: Added automatic profile saving after run initialization and shop encounters to ensure discovered items are never lost.
+
+### Fixed
+- **BelAtro Shop Crash**: Resolved a `NameError` in the shop UI by adding the missing `sys` import.
+- **Trick Visibility Timing**: Fixed a race condition in `round_driver.py` where the 4th card of a trick was cleared before it could be rendered. The UI now correctly displays all 4 cards on the table before the trick-win popup appears.
+
+## [2.5.0] - 2026-05-02
+
+### Added
+- **Functional State Architecture**: Completed the transition to a pure functional engine. Joker state is now stored immutably in `GameState`, ensuring absolute "frozen-safety" and preventing state leakage between rounds.
+- **Comprehensive BelAtro Test Suite**: Added a massive collection of 50+ new integration and regression tests covering all 57 critical edge cases identified in the audit. Total test count reached 276.
+- **Performance Benchmarking Suite**: Added a new benchmark tool in `scripts/benchmark.py` to measure scoring, dealing, and legal card calculation performance.
+
+### Changed
+- **Scoring Engine Refactor**: Decoupled boss modifier scoring logic into specialized helper functions, significantly improving maintainability and reducing risk of regression in complex Boss Blinds.
+- **AI Strategy Decomposition**: Refactored the Hard AI decision-making into a clean strategy pattern, allowing for more granular tactical tuning.
+- **EventBus Reliability**: Overhauled `EventBus.emit` to safely handle handler unsubscription during event dispatch, fixing a potential runtime crash.
+- **Immutable Score Accumulation**: `ScoreAccumulator` now returns a new `GameState` instead of mutating internal fields, aligning BelAtro with the core engine's architectural principles.
+
+### Fixed
+- **Animation Skip Reset (M6)**: Animation fast-forwarding now correctly resets on every human turn, preventing the game from accidentally staying in high-speed mode.
+- **Score Overflow Precision**: Fixed a floating-point precision issue in `ScoreAccumulator` when dealing with extremely large chip counts (billions+).
+- **Boss Blind Core Bugs**: Fixed all remaining audit bugs (B1-B8), including boss modifier application, scoring accumulation disconnects, and deck-specific bonus triggers.
+
+## [2.4.1] - 2026-05-02
+
+### Fixed
+- **BelAtro Rules UI**: Fixed a major rendering bug where the rules screen would not clear correctly, leading to overlapping text.
+- **Dynamic Formatting**: Rules screen now correctly handles terminal resizing and dynamic centering.
+
+## [2.4.0] - 2026-05-02
+
+### Added
+- **BelAtro Collection (Almanac)**: A persistent gallery in the expansion menu to track discovered Jokers, Tarots, Planets, and Vouchers.
+- **Full Boss Blind Suite**: All 17 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
+- **Hard AI Overhaul**: Improved endgame awareness (Dix de Der), strategic discarding, and 2-ply void inference.
+- **Enhanced UI Terminology**: Transitioned to "You" and "Partner" labels for a more immersive single-player experience.
+
+### Changed
+- **Single-Player Focus**: Removed Hotseat (2P) mode and simplified the game engine and UI menus accordingly.
+- **Consolidated Save Paths**: All local data (stats and profile) now live in a unified `belote` directory.
+- **Menu Streamlining**: Removed "Mode" and "Reset Statistics" options for a cleaner main menu.
+
+### Fixed
+- **Gameflow Reliability**: Fixed a regression that caused certain tests to hang by properly mocking UI prompts.
+- **Technical Integrity**: Achieved 100% type-safety (0 mypy errors) across all source and test modules.
+
+## [2.3.3] - 2026-05-02
+
+### Added
+- **BelAtro Mode Integration**: Fully integrated the BelAtro roguelite mode into the main menu.
+- **WIP Deck Completion**: Fully implemented all starting decks (L'Ermite, Le Vétéran, Le Flambeur) with their unique starting items and modifiers.
+- **Advanced Joker Logic**: Completed implementation for all 50+ Jokers, including complex round-end and bidding-phase triggers.
+- **Dynamic UI Rendering**: Refactored menu systems to dynamically center art and text based on terminal width.
+- **Alternate Screen Support**: Implemented alternate screen switching for BelAtro to provide a clean, isolated terminal buffer.
+
+### Fixed
+- **BelAtro Startup**: Resolved a `TypeError` and `ImportError` that prevented BelAtro from launching correctly.
+- **UI Centering**: Fixed an issue where menu art assumed a fixed 80-column width, causing misaligned headers on different terminal sizes.
+- **Game Loop Continuity**: Fixed a bug where BelAtro would exit immediately back to the main menu instead of starting a run.
+- **Event Bus Robustness**: Overhauled the `RoundEndEvent` to provide complete game state snapshots to Jokers, fixing several uninitialized logic paths.
+
+## [2.3.1] - 2026-05-01
+
+### Fixed
+- **Contract Engine Logic**: Fixed a critical bug where trick winner detection failed during "Sans Atout" (No Trump) contracts. The engine now correctly handles `trump=None` scenarios.
+- **Tout Atout / Sans Atout support**: Fully implemented correct card values and rankings for special contracts.
+  - *Tout Atout*: All Jacks (20 pts), all 9s (14 pts), and all suits follow trump ranking.
+  - *Sans Atout*: All Aces (11 pts), all 10s (10 pts), and all 9s (0 pts).
+- **Coinche Multipliers**: Fixed a bug where Coinche (×2) and Surcoinche (×4) multipliers were not being applied to the final score in the core engine.
+- **Sequence Detection**: Refactored sequence detection logic to be more maintainable and fixed a potential `NameError` in the detection loop.
+- **Project-wide Type Safety**: Resolved over 250 `mypy` errors across the `tests/` and `src/` directories, achieving 100% strict type compliance.
+- **Linting & Code Cleanup**: Eliminated all `ruff` violations and improved idiomatic Python usage throughout the codebase.
+- **API Consistency**: Updated `trick_winner_seat`, `card_points`, and `trick_rank` to explicitly accept the `contract` type, ensuring accurate scoring and AI decisions across all game modes.
+
+## [2.3.0] - 2026-05-01
+
+### Added
+- **Full Tarot System**: All 10 Tarot cards are now fully functional. Use `[U]` during your turn to open the consumable menu.
+  - *Le Chariot*: Steal the current trick (wired `force_next_trick_win`).
+  - *La Roue*: Change trump mid-round.
+  - *Le Jugement*: Resurrect sold Jokers.
+  - *Le Monde*: Double declaration points.
+  - *La Tempérance* & *Le Fou*: Permanent deck editing (random removal/duplication).
+- **Complete Voucher Set**: All 9 vouchers are implemented with unique hooks.
+  - *La Télescope*: Preview the talon during bidding.
+  - *L'Encyclopédie*: Reveal partner personality during bidding.
+  - *Les Cartes Dorées*: Increased Gold Seal value (+$5).
+  - *Le Couteau*: Unlock card destruction in the Shop for $2 refunds.
+  - *La Balance*: Automatic win on close losses (within 10 points of target).
+  - *La Surcoinche*: Unlocks the massive ×4.0 Mult contract.
+- **Dynamic Deck-Building**: The game engine now supports modified decks, allowing for permanent card additions and removals across a run.
+- **Corrupted Joker Mechanics**: Implemented `Le Démon` (trust penalty on purchase).
+- **Expanded Test Suite**: Added 52 new tests (total 165), significantly increasing coverage for `round_driver.py`, `shop.py`, `tarots.py`, and `vouchers.py`.
+
+### Changed
+- **Bidding Overhaul**: Opponents can now Coinche your bids (×2.0 Mult), and you can counter with Surcoinche (×4.0 Mult) if the voucher is owned.
+- **Input Map**: Added `[U]` key for using consumables and removed `Tab` -> `Enter` mapping.
+- **Performance**: Increased render cache size to 2048 and moved suit/ID mappings to module level for faster scoring.
+- **Code Quality**: Extracted `_undo_or_restart` helper in `gameflow.py` and improved `EventBus` error logging.
+
+### Fixed
+- **Critical Bug Fixes**:
+  - *La Sentinelle*: Now correctly requires both Jack AND trump suit.
+  - *Le Rebelle*: Multiplier no longer stacks exponentially on Belote+Rebelote.
+  - *Le Stratège*: Strategic bidding logic (requires high-value cards instead of just any hand).
+  - *Recursive UI*: Fixed stack overflow risk in `prompt_card` on UNDO.
+  - *Shop Duplicates*: Replaced random choice with sampling to prevent identical jokers in shop.
+  - *UI Truncation*: Card destruction UI no longer truncates at 20 cards.
+- **Boss Modifier Engine**: Fully wired 17 boss modifiers (forced pass, zero-point kings/tens, no Dix de Der, etc.) into the game engine.
+- **Declaration scoring crash** (`round_driver.py`): replaced nonexistent `belote.deck.declaration_points` import with `belote.scoring.get_declaration_points`.
+- **JokerResult multiplier zeroing** (`items/base.py`): `times_mult` default changed from `0.0` to `1.0`.
+- **BelAtro standalone crash** (`belatro/main.py`): fixed missing `KeyReader` context.
+- **Bid prompt null-dereference** (`ui/prompts.py`): added guards for `up_card`.
+- **Type safety**: Resolved all 32 mypy errors and improved overall project type integrity.
+- **Starting Decks**: All bonuses for *Le Joueur*, *L'Aristocrate*, *L'Ermite*, *Le Flambeur*, *Le Vétéran*, and *L'Anarchiste* are now correctly applied.
+- **Scoring Hooks**: Wired missing `on_bid`, `on_round_start`, and `on_round_end` triggers for all Jokers.
+
+## [2.2.0] - 2026-04-30
+
+### Added
+- **BelAtro Score Overlay Toggle**: Press `[I]` during any Belote/BelAtro game to toggle the per-trick score breakdown popup on or off. Useful when you want an unobstructed view of the table between tricks.
+
+### Fixed
+- **BelAtro trick display**: The 4th card played in a trick (the trick-completing card) was never shown on the table — the table went blank before the score popup appeared. All 4 cards now remain visible on the mat until the next trick begins.
+- **BelAtro 4th-card visibility**: `on_card_played` now reconstructs the display state from `completed_tricks[-1]` when `current_trick` has been cleared by `play_card`, mirroring the classic mode's pre-play display state pattern.
+
+## [2.0.1] - 2026-04-30
+
+### Added
+- **Le Républicain deck** is now fully playable: 7s and 8s are wild cards that can be played on any trick regardless of suit constraints. Your team earns +5 chips for every 7 or 8 you capture.
+- **Le Carnet voucher** is now fully implemented: your partner's full hand is visible to you throughout every round. You earn +1 Mult each time South personally wins a trick.
+- Both mechanics documented in the in-game Belatro Rules screen (EN and FR), under new "Starting Decks" and "Vouchers — Le Carnet" sections.
+
+### Fixed
+- Card-count invariant assertion added to `_handle_trick` to catch any future hand-size corruption early.
+- Cards on the trick mat now render immediately after each card is played (previously only updated after the trick was complete).
+
+## [2.0.0] - 2026-04-30
+
+### Added
+- **BelAtro Expansion**: A massive roguelite expansion inspired by Balatro, integrated into the Belote core.
+  - **The Run**: Progress through 8 'Antes' with increasing target scores. Each Ante consists of Small, Big, and Boss Blinds.
+  - **Scoring Engine**: New Multiplier-based scoring system: `Score = (Chips + Declarations) × Multiplier`.
+  - **Joker System**: 50+ unique Jokers (Contract, Corrupted, Economy, Hand Comp, Trick Timing) that provide passive buffs and scoring modifiers.
+  - **Consumables**: Planet cards to level up contracts, Tarot cards for one-shot effects, and permanent Vouchers.
+  - **Partner Trust**: Dynamic relationship with your AI partner. High trust reveals their hand/voids and boosts their specific "Partner Jokers."
+  - **Boss Blinds**: 10+ unique bosses with rule-breaking modifiers (e.g., hidden scores, suit debuffs, mid-round trump changes).
+- **Event-Driven Architecture**: Introduced a centralized `EventBus` to handle complex item interactions and state updates.
+- **Save/Load System**: Persistence for run progress, unlocks, and global statistics.
+- **New UI Package**: Dedicated BelAtro HUD with Multiplier animations, Shop interface, and Trust bar visualization.
+
+### Changed
+- **Entry Points**: Added `belatro` as a secondary CLI command for direct access to the roguelite mode.
+- **Core Refactor**: Decoupled the game loop from the rendering engine to support multiple game modes (Classic vs. BelAtro).
+- **Test Suite**: Expanded tests to cover economy, ante scaling, item registry, and boss modifiers.
+
+### Fixed
+- **State Leakage**: Fixed an issue where items from previous runs could occasionally persist in the registry.
+- **Trust Calculation**: Resolved a rounding error in trust gains during high-multiplier rounds.
 
 ## [1.1.0] - 2026-04-30
 

{belote_cli-1.1.0 → belote_cli-2.5.2}/DEVELOPMENT.md

@@ -23,14 +23,20 @@ Welcome to the Belote development guide. This project is structured as a standar
 
 ## Running the Game
 
-After installing, you can run the game using the `belote` command:
+After installing, you can run the game using the `belote` command for Classic mode:
 ```bash
 belote
 ```
 
+Or the `belatro` command for the Roguelite expansion:
+```bash
+belatro
+```
+
 Or via python:
 ```bash
 python -m belote.main
+python -m belote.belatro.main
 ```
 
 ## Testing
@@ -42,7 +48,28 @@ pip install pytest
 
 Run tests:
 ```bash
+# Run all tests (Classic + BelAtro)
 PYTHONPATH=src pytest
+
+# Run only Classic Belote tests
+PYTHONPATH=src pytest tests/
+
+# Run only BelAtro tests
+PYTHONPATH=src pytest tests/belatro/
+
+# Run a single test file
+PYTHONPATH=src pytest tests/test_game.py
+PYTHONPATH=src pytest tests/belatro/test_scoring.py
+
+# Run a single test by name
+PYTHONPATH=src pytest tests/test_game.py::test_play_card_legal
+PYTHONPATH=src pytest -k "test_scoring"
+
+# Run with verbose output
+PYTHONPATH=src pytest -v
+
+# Run with coverage report
+PYTHONPATH=src pytest --cov=belote --cov-report=term-missing
 ```
 
 ## Code Quality
@@ -51,19 +78,20 @@ The project maintains zero lint and type-check violations. Run all checks with:
 
 ```bash
 # Type checking (0 errors expected)
-PYTHONPATH=src .venv/bin/mypy src/belote
+PYTHONPATH=src mypy .
 
 # Linting (0 violations expected)
-PYTHONPATH=src .venv/bin/ruff check src/ tests/
-
-# Full test suite (71 tests expected)
+ruff check .
+# Full test suite (305 tests expected)
 PYTHONPATH=src pytest
-```
 
-Current baseline (v1.1.0):
-- **mypy**: 0 errors (strict mode, `check_untyped_defs`, `disallow_untyped_defs`)
-- **ruff**: 0 violations (rules: E, F, W, I, N, UP, B, A, C4, RET, SIM, PTH)
-- **pytest**: 71 tests, 0 failures
+# ...
+
+Current baseline:
+- **mypy**: 0 errors (strict mode)
+- **ruff**: 0 violations
+- **pytest**: 305 tests, 0 failures
+
 
 ## Benchmarking
 

{belote_cli-1.1.0 → belote_cli-2.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 1.1.0
+Version: 2.5.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -45,6 +45,41 @@ Description-Content-Type: text/markdown
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
+## Now Featuring: BelAtro Expansion
+
+**BelAtro** is a major roguelite expansion inspired by *Balatro*. Play through 8 Antes of escalating difficulty, build a deck of powerful Jokers, and use Tarot cards and Planets to break the game! 
+
+**BelAtro is now fully integrated into the main menu!** Just launch `belote` and select it from the top of the list.
+
+### BelAtro Quick Start
+```bash
+# Play using the integrated launcher (recommended)
+belote
+
+# Or play the new Roguelite mode directly
+belatro
+```
+
+### Starting Decks (All Fully Implemented)
+| Deck | Special Rule |
+|---|---|
+| Le Classique | Standard 32-card baseline |
+| **Le Républicain** | 7s & 8s are wild — play them on any trick. +5 chips per 7/8 your team captures |
+| L'Aristocrate | All four Aces start Gold Sealed (+cash) |
+| Le Joueur | Start $14 — Boss Blind every 2 antes |
+| **L'Ermite** | Starts with **La Sentinelle** Joker (×3 Mult if Trump Jack never leaves hand) |
+| **Le Vétéran** | Start with a random **Planet** card pre-applied to level up a contract |
+| **Le Flambeur** | Starts with **L'Aventurier** Partner Joker (×2 Mult if both win ≥3 tricks) |
+| L'Anarchiste | Start $19 — Corrupted pool visible |
+
+### Notable Vouchers
+| Voucher | Effect |
+|---|---|
+| **Le Carnet** | See partner's full hand every round. +1 Mult each time South wins a trick |
+| La Voûte | Earn $1 interest per $5 held, up to $5/round |
+| La Double Donne | +1 Joker slot |
+| La Surcoinche | Unlocks the Surcoinche contract *(unlockable)* |
+
 ## Showcase
 
 ### Main Menu
@@ -54,7 +89,7 @@ Complete implementation of the French card game Belote for the terminal, with a
      ⢰⣿⣿⣿⣿⡿⠟⠁⣠⣴⣶⣦⠄
      ⢸⣿⣿⠟⠉⣠⣴⣿⣿⣿⠟⠁⣠⣾⣿⣦⡀
       ⠉⣀⣴⣾⣿⣿⣿⠟⢁⣤⣾⣿⣿⣿⣿⣿⡆
-    ⢀⣤⣾⣿⣿⣿⡿⠛⢁⣴⣿⣿⣿⣿⣿⣿⣿⠟⠁⡀
+    ⢀⣤⣾⣿⣿⣿⡿⠛⢁⣴⣿⣿⣿⡿⠛⢁⣴⣿⣿⣿⣿⣿⣿⣿⠟⠁⡀
     ⢼⣿⣿⣿⡿⠋⣀⣴⣿⣿⣿⣿⣿⣿⣿⡿⠉⣠⣾⣿⡆
     ⠘⢿⡿⠋⣠⣾⣿⣿⣿⠟⠁⣿⣿⣿⣿⣿⠟⢁⣀
       ⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⠏⢀⣴⣿⣿⣿⠋⢠⣾⣿⣷⣦⡀
@@ -114,6 +149,9 @@ pip install belote-cli
 # Play using the belote command
 belote
 
+# Play the new Roguelite expansion
+belatro
+
 # Custom settings
 belote --difficulty hard --target 500 --seed 123 --speed fast
 ```
@@ -124,15 +162,21 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 **General:**
 - `?` or `H`: Show keyboard shortcut help
 - `M`: Toggle sound effects on/off
+- `I`: Toggle BelAtro score overlay (per-trick breakdown popup)
 - `Q`: Quit to main menu or exit
 - `t`: View Game History (Round-by-round)
 - `T`: Switch UI Theme
 
-**Main Menu:**
+**Classic Belote:**
 - `↑` `↓`: Navigate options
-- `←` `→`: Quick-change settings (Difficulty, Target, Speed, Mode)
+- `←` `→`: Quick-change settings (Difficulty, Target, Speed)
 - `Enter`: Select option / Enter submenu
 
+**BelAtro (Roguelite):**
+- `S`: View current Run State and Jokers
+- `1`-`5`: Inspect specific Jokers in the Shop
+- `U`: Use a consumable (Tarot/Planet) during gameplay
+
 **Gameplay:**
 - `←` `→` or `↑` `↓`: Move selection
 - `Enter`: Confirm card/bid
@@ -143,19 +187,25 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 
 ## Features
 
-- **Rich Terminal UI:** Full-screen green felt table with detailed card graphics, face card art, and distinct color palettes. Graceful fallback to text-only mode for non-UTF-8 terminals.
+- **BelAtro Roguelite Mode:** A massive expansion featuring 50+ Jokers, 15+ Tarot cards, and permanent upgrades.
+- **Collection (Almanac):** Persistent tracker to browse every Joker, Planet, and Voucher you've discovered across your runs.
+- **Full Boss Blind Suite:** All 17 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
+- **Multiplier Scoring:** Use items to stack Multipliers and reach scores in the millions.
+- **Partner Trust:** Build a relationship with your AI partner to unlock synergies.
+- **Rich Terminal UI:** Full-screen green felt table with detailed card graphics and "You" vs "Partner" terminology.
+- **Enhanced Hard AI**: Advanced void inference and 2-ply lookahead for critical tricks (Dix de Der).
 - **Customizable Themes:** Switch between different color palettes (e.g., Classic Green, Dark Blue, Royal Purple) using the `T` key during gameplay.
 - **Incremental Rendering:** High-performance cursor-based updates for zero-flicker gameplay even at high speeds.
 - **Hand Sorting:** Strategic "play value" organization (honors grouped together) for better tactical awareness.
-- **Pre-game Preview:** Review your hand and estimated declaration points before the bidding starts.
-- **Main Menu:** Independent AI difficulty per seat, configurable Target Score and Speed.
+- **Main Menu:** Simple single-player entry point with configurable AI difficulty, Target Score, and Speed.
 - **Undo/Redo:** Press `Z` to undo your last move during bidding or play.
-- **Statistics:** Global tracking of games played/won, win rate (per difficulty), capots, best/worst rounds, and longest games.
-- **Adaptive UI:** Dynamic text wrapping and layout adjustment for varying terminal widths.
+- **Statistics:** unified global tracking of games played, win rates, best rounds, and BelAtro expansion milestones.
+- **Dynamic Adaptive UI:** Menu art and text automatically center based on terminal width.
+- **Alternate Screen Buffer:** BelAtro uses a dedicated terminal buffer for a clean, non-overlapping interface.
 - **Sound Effects:** Enhanced auditory feedback for trick wins, Belote, and Capot, with a built-in mute toggle.
 - **Declarations:** Automatic detection and announcement of sequences (Tierce, Quarte, etc.) and Carrés after the first trick.
 - **Live HUD:** Real-time round scoring displays points won during the current round, with a smooth "rolling" numerical animation for total scores.
-- **High Fidelity:** Full implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", "Capot" (252 pts), and "Litige" (tie-break). Total round points sum to 162 (152 from cards + 10 for last trick).
+- **High Fidelity:** Full implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", "Capot" (252 pts), and "Litige" (tie-break). Full support for **Sans Atout** (No Trump) and **Tout Atout** (All Trump) contracts.
 - **Rules & History Viewer:** A scrollable, bilingual (English/French) in-game reference for the game's heritage and mechanics.
 
 ## AI
@@ -170,7 +220,14 @@ Three difficulty levels:
 ```
 belote/
 ├── src/belote/
-│   ├── main.py        # Entry point, CLI parsing, terminal setup
+│   ├── main.py        # Classic entry point
+│   ├── belatro/       # Roguelite Expansion package
+│   │   ├── main.py    # BelAtro entry point
+│   │   ├── core/      # Run state, scoring, economy
+│   │   ├── engine/    # Event bus, round driver
+│   │   ├── items/     # Jokers, Tarots, Planets, Vouchers
+│   │   ├── partner/   # Trust system and partner AI
+│   │   └── ui/        # Shop, HUD, and item visualization
 │   ├── gameflow.py    # Main game loop and phase transitions
 │   ├── deck.py        # Card, Suit, Rank, deck operations, points
 │   ├── game.py        # GameState, phases, pure transitions, legal moves, bidding
@@ -180,15 +237,11 @@ belote/
 │   ├── context.py     # Global managers (Audio, Terminal)
 │   ├── themes.py      # Color theme management
 │   ├── ui/            # Modular UI package
-│   │   ├── render.py  # ANSI table and card rendering
-│   │   ├── prompts.py # Keyboard input and menu navigation
-│   │   ├── menu.py    # Main menu and settings
-│   │   └── announce.py# Sound and score animations
 │   ├── ansi.py        # ANSI escape helpers (colors, cursor)
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (71+ tests)
+├── tests/             # Comprehensive test suite (250+ tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -200,9 +253,35 @@ belote/
 ## Running Tests
 
 ```bash
+# Run all tests (Classic + BelAtro)
 PYTHONPATH=src pytest
 ```
 
+Currently **305 tests** passing with 100% coverage on core logic.
+
+## Technical Integrity
+
+The codebase is strictly validated with the following tools:
+- **mypy**: 0 errors (strict type safety)
+- **ruff**: 0 violations (linting & formatting)
+- **pytest**: 305/305 passed
+- **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
+- **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
+
+## Statistics & Progression
+
+**Belote-CLI** tracks your long-term performance across both game modes.
+
+- **Global Statistics:** View your win rates, best round scores, and trump usage from the "Statistics" menu.
+- **BelAtro Unlocks:** Progression in the roguelite mode is saved automatically. You can track your Ante 8 wins and total items found in the expansion.
+
+### Resetting Progress
+If you want to start fresh and clear your history/collection, manually delete the data files:
+- **Linux**: `rm ~/.local/share/belote/*.json`
+- **Windows**: `del %APPDATA%\belote\*.json`
+
+This will wipe all global statistics and reset your discovered item Almanac in BelAtro.
+
 ## Terminal Hygiene
 
 Signal handlers (SIGINT, SIGTERM) and atexit hooks ensure the terminal is always restored — cursor visible, colors reset, alt-screen off — even after Ctrl+C or crashes.

{belote_cli-1.1.0 → belote_cli-2.5.2}/README.md

@@ -2,6 +2,41 @@
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
+## Now Featuring: BelAtro Expansion
+
+**BelAtro** is a major roguelite expansion inspired by *Balatro*. Play through 8 Antes of escalating difficulty, build a deck of powerful Jokers, and use Tarot cards and Planets to break the game! 
+
+**BelAtro is now fully integrated into the main menu!** Just launch `belote` and select it from the top of the list.
+
+### BelAtro Quick Start
+```bash
+# Play using the integrated launcher (recommended)
+belote
+
+# Or play the new Roguelite mode directly
+belatro
+```
+
+### Starting Decks (All Fully Implemented)
+| Deck | Special Rule |
+|---|---|
+| Le Classique | Standard 32-card baseline |
+| **Le Républicain** | 7s & 8s are wild — play them on any trick. +5 chips per 7/8 your team captures |
+| L'Aristocrate | All four Aces start Gold Sealed (+cash) |
+| Le Joueur | Start $14 — Boss Blind every 2 antes |
+| **L'Ermite** | Starts with **La Sentinelle** Joker (×3 Mult if Trump Jack never leaves hand) |
+| **Le Vétéran** | Start with a random **Planet** card pre-applied to level up a contract |
+| **Le Flambeur** | Starts with **L'Aventurier** Partner Joker (×2 Mult if both win ≥3 tricks) |
+| L'Anarchiste | Start $19 — Corrupted pool visible |
+
+### Notable Vouchers
+| Voucher | Effect |
+|---|---|
+| **Le Carnet** | See partner's full hand every round. +1 Mult each time South wins a trick |
+| La Voûte | Earn $1 interest per $5 held, up to $5/round |
+| La Double Donne | +1 Joker slot |
+| La Surcoinche | Unlocks the Surcoinche contract *(unlockable)* |
+
 ## Showcase
 
 ### Main Menu
@@ -11,7 +46,7 @@ Complete implementation of the French card game Belote for the terminal, with a
      ⢰⣿⣿⣿⣿⡿⠟⠁⣠⣴⣶⣦⠄
      ⢸⣿⣿⠟⠉⣠⣴⣿⣿⣿⠟⠁⣠⣾⣿⣦⡀
       ⠉⣀⣴⣾⣿⣿⣿⠟⢁⣤⣾⣿⣿⣿⣿⣿⡆
-    ⢀⣤⣾⣿⣿⣿⡿⠛⢁⣴⣿⣿⣿⣿⣿⣿⣿⠟⠁⡀
+    ⢀⣤⣾⣿⣿⣿⡿⠛⢁⣴⣿⣿⣿⡿⠛⢁⣴⣿⣿⣿⣿⣿⣿⣿⠟⠁⡀
     ⢼⣿⣿⣿⡿⠋⣀⣴⣿⣿⣿⣿⣿⣿⣿⡿⠉⣠⣾⣿⡆
     ⠘⢿⡿⠋⣠⣾⣿⣿⣿⠟⠁⣿⣿⣿⣿⣿⠟⢁⣀
       ⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⠏⢀⣴⣿⣿⣿⠋⢠⣾⣿⣷⣦⡀
@@ -71,6 +106,9 @@ pip install belote-cli
 # Play using the belote command
 belote
 
+# Play the new Roguelite expansion
+belatro
+
 # Custom settings
 belote --difficulty hard --target 500 --seed 123 --speed fast
 ```
@@ -81,15 +119,21 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 **General:**
 - `?` or `H`: Show keyboard shortcut help
 - `M`: Toggle sound effects on/off
+- `I`: Toggle BelAtro score overlay (per-trick breakdown popup)
 - `Q`: Quit to main menu or exit
 - `t`: View Game History (Round-by-round)
 - `T`: Switch UI Theme
 
-**Main Menu:**
+**Classic Belote:**
 - `↑` `↓`: Navigate options
-- `←` `→`: Quick-change settings (Difficulty, Target, Speed, Mode)
+- `←` `→`: Quick-change settings (Difficulty, Target, Speed)
 - `Enter`: Select option / Enter submenu
 
+**BelAtro (Roguelite):**
+- `S`: View current Run State and Jokers
+- `1`-`5`: Inspect specific Jokers in the Shop
+- `U`: Use a consumable (Tarot/Planet) during gameplay
+
 **Gameplay:**
 - `←` `→` or `↑` `↓`: Move selection
 - `Enter`: Confirm card/bid
@@ -100,19 +144,25 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 
 ## Features
 
-- **Rich Terminal UI:** Full-screen green felt table with detailed card graphics, face card art, and distinct color palettes. Graceful fallback to text-only mode for non-UTF-8 terminals.
+- **BelAtro Roguelite Mode:** A massive expansion featuring 50+ Jokers, 15+ Tarot cards, and permanent upgrades.
+- **Collection (Almanac):** Persistent tracker to browse every Joker, Planet, and Voucher you've discovered across your runs.
+- **Full Boss Blind Suite:** All 17 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
+- **Multiplier Scoring:** Use items to stack Multipliers and reach scores in the millions.
+- **Partner Trust:** Build a relationship with your AI partner to unlock synergies.
+- **Rich Terminal UI:** Full-screen green felt table with detailed card graphics and "You" vs "Partner" terminology.
+- **Enhanced Hard AI**: Advanced void inference and 2-ply lookahead for critical tricks (Dix de Der).
 - **Customizable Themes:** Switch between different color palettes (e.g., Classic Green, Dark Blue, Royal Purple) using the `T` key during gameplay.
 - **Incremental Rendering:** High-performance cursor-based updates for zero-flicker gameplay even at high speeds.
 - **Hand Sorting:** Strategic "play value" organization (honors grouped together) for better tactical awareness.
-- **Pre-game Preview:** Review your hand and estimated declaration points before the bidding starts.
-- **Main Menu:** Independent AI difficulty per seat, configurable Target Score and Speed.
+- **Main Menu:** Simple single-player entry point with configurable AI difficulty, Target Score, and Speed.
 - **Undo/Redo:** Press `Z` to undo your last move during bidding or play.
-- **Statistics:** Global tracking of games played/won, win rate (per difficulty), capots, best/worst rounds, and longest games.
-- **Adaptive UI:** Dynamic text wrapping and layout adjustment for varying terminal widths.
+- **Statistics:** unified global tracking of games played, win rates, best rounds, and BelAtro expansion milestones.
+- **Dynamic Adaptive UI:** Menu art and text automatically center based on terminal width.
+- **Alternate Screen Buffer:** BelAtro uses a dedicated terminal buffer for a clean, non-overlapping interface.
 - **Sound Effects:** Enhanced auditory feedback for trick wins, Belote, and Capot, with a built-in mute toggle.
 - **Declarations:** Automatic detection and announcement of sequences (Tierce, Quarte, etc.) and Carrés after the first trick.
 - **Live HUD:** Real-time round scoring displays points won during the current round, with a smooth "rolling" numerical animation for total scores.
-- **High Fidelity:** Full implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", "Capot" (252 pts), and "Litige" (tie-break). Total round points sum to 162 (152 from cards + 10 for last trick).
+- **High Fidelity:** Full implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", "Capot" (252 pts), and "Litige" (tie-break). Full support for **Sans Atout** (No Trump) and **Tout Atout** (All Trump) contracts.
 - **Rules & History Viewer:** A scrollable, bilingual (English/French) in-game reference for the game's heritage and mechanics.
 
 ## AI
@@ -127,7 +177,14 @@ Three difficulty levels:
 ```
 belote/
 ├── src/belote/
-│   ├── main.py        # Entry point, CLI parsing, terminal setup
+│   ├── main.py        # Classic entry point
+│   ├── belatro/       # Roguelite Expansion package
+│   │   ├── main.py    # BelAtro entry point
+│   │   ├── core/      # Run state, scoring, economy
+│   │   ├── engine/    # Event bus, round driver
+│   │   ├── items/     # Jokers, Tarots, Planets, Vouchers
+│   │   ├── partner/   # Trust system and partner AI
+│   │   └── ui/        # Shop, HUD, and item visualization
 │   ├── gameflow.py    # Main game loop and phase transitions
 │   ├── deck.py        # Card, Suit, Rank, deck operations, points
 │   ├── game.py        # GameState, phases, pure transitions, legal moves, bidding
@@ -137,15 +194,11 @@ belote/
 │   ├── context.py     # Global managers (Audio, Terminal)
 │   ├── themes.py      # Color theme management
 │   ├── ui/            # Modular UI package
-│   │   ├── render.py  # ANSI table and card rendering
-│   │   ├── prompts.py # Keyboard input and menu navigation
-│   │   ├── menu.py    # Main menu and settings
-│   │   └── announce.py# Sound and score animations
 │   ├── ansi.py        # ANSI escape helpers (colors, cursor)
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (71+ tests)
+├── tests/             # Comprehensive test suite (250+ tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -157,9 +210,35 @@ belote/
 ## Running Tests
 
 ```bash
+# Run all tests (Classic + BelAtro)
 PYTHONPATH=src pytest
 ```
 
+Currently **305 tests** passing with 100% coverage on core logic.
+
+## Technical Integrity
+
+The codebase is strictly validated with the following tools:
+- **mypy**: 0 errors (strict type safety)
+- **ruff**: 0 violations (linting & formatting)
+- **pytest**: 305/305 passed
+- **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
+- **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
+
+## Statistics & Progression
+
+**Belote-CLI** tracks your long-term performance across both game modes.
+
+- **Global Statistics:** View your win rates, best round scores, and trump usage from the "Statistics" menu.
+- **BelAtro Unlocks:** Progression in the roguelite mode is saved automatically. You can track your Ante 8 wins and total items found in the expansion.
+
+### Resetting Progress
+If you want to start fresh and clear your history/collection, manually delete the data files:
+- **Linux**: `rm ~/.local/share/belote/*.json`
+- **Windows**: `del %APPDATA%\belote\*.json`
+
+This will wipe all global statistics and reset your discovered item Almanac in BelAtro.
+
 ## Terminal Hygiene
 
 Signal handlers (SIGINT, SIGTERM) and atexit hooks ensure the terminal is always restored — cursor visible, colors reset, alt-screen off — even after Ctrl+C or crashes.