@pokertools/engine 1.0.1 → 1.0.4

package/README.md

@@ -1,607 +1,753 @@
-# @pokertools/engine
+# 🃏 @pokertools/engine
+
+> **Enterprise-grade Texas Hold'em poker game engine**
 
 [![npm version](https://img.shields.io/npm/v/@pokertools/engine.svg)](https://www.npmjs.com/package/@pokertools/engine)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/aaurelions/pokertools/ci.yml?branch=main)](https://github.com/aaurelions/pokertools/actions)
-[![Coverage](https://img.shields.io/codecov/c/github/aaurelions/pokertools)](https://codecov.io/gh/aaurelions/pokertools)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@pokertools/engine)](https://bundlephobia.com/package/@pokertools/engine)
-[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
-
-An enterprise-grade, **deterministic, immutable, and high-performance** Texas Hold'em poker engine.
-
-Built on the **Redux design pattern**, this engine treats the poker game as a finite state machine. It accepts a `GameState` and an `Action`, and returns a new `GameState`. This architecture makes it uniquely suited for:
-
-- **Multiplayer Servers:** Easy synchronization, crash recovery, and concurrency.
-- **AI Training:** Fast simulations for Monte Carlo / Reinforcement Learning (17m hands/sec using `@pokertools/evaluator`).
-- **Real Money Gaming:** Auditable RNG, integer-only arithmetic, and strict invariant checking.
-- **Solvers:** Correct handling of complex side-pots, split-pots, and heads-up positioning.
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [Project Structure](#project-structure)
-- [Advanced Usage](#advanced-usage)
-  - [Provable Fairness (Custom RNG)](#provable-fairness-custom-rng)
-  - [Crash Recovery (Snapshots)](#crash-recovery-snapshots)
-  - [Event Subscription & Middleware](#event-subscription--middleware)
-  - [Hand History Export](#hand-history-export)
-  - [Time Banks & Timeout Logic](#time-banks--timeout-logic)
-  - [Undo & Rollback](#undo--rollback)
-  - [Tournament Blind Schedules](#tournament-blind-schedules)
-  - [Scalability & Worker Threads](#scalability--worker-threads)
-- [Security & Integrity](#security--integrity)
-  - [View Masking (Anti-Cheat)](#view-masking-anti-cheat)
-  - [Invariant Auditing](#invariant-auditing)
-  - [Integer Arithmetic](#integer-arithmetic)
-- [Rule Logic & Edge Cases](#rule-logic--edge-cases)
-- [API Reference](#api-reference)
-- [Error Handling](#error-handling)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Features
-
-- **Pure State Machine:** Zero internal mutation. `f(state, action) => newState`.
-- **Provably Fair:** Inject your own RNG (e.g., CSPRNG or hardware RNG) for completely auditable shuffling.
-- **Crash Resilient:** Export lightweight JSON snapshots and restore game state instantly from a database.
-- **Event Driven:** Subscribe to state changes to trigger UI sounds, animations, or analytics.
-- **Complex Logic Solved:**
-  - **Side Pots:** Handles multi-way all-ins with mathematically correct pot segregation using the iterative subtraction method.
-  - **Split Pots:** Distributes odd chips by position (closest to left of button) or suit automatically.
-  - **Heads-Up Rules:** Automatically switches Button/SB positioning logic when only 2 players remain.
-- **Auto-Runout:** Automatically deals remaining streets and calculates winners when all active players are all-in.
-- **Rake Support:** Configurable rake percentage and cap for cash games (tournaments automatically excluded).
-- **Granular Card Visibility:** Players can selectively show cards at showdown (e.g., show only one card to prove a bluff).
-- **Time Bank Support:** Native support for "Time Bank" resource management and explicit timeout resolutions.
-- **Hand History:** Native export to standard PokerStars/PHH text formats for compatibility with tracking software (PokerTracker 4, HM3).
-- **Strict Typing:** Written in TypeScript with exhaustive definitions for every state transition.
-
-## Installation
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Tests](https://img.shields.io/badge/tests-320%20passed-brightgreen.svg)]()
+
+A **production-ready** poker game engine featuring immutable state management, chip conservation auditing, side pot calculation, rake handling, tournament support, and comprehensive rule enforcement.
+
+---
+
+## ✨ Features
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          ENGINE FEATURES                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  🎰 Complete Texas Hold'em Implementation                                   │
+│  ♻️  Immutable State Machine (Redux-style)                                  │
+│  💰 Chip Conservation Auditing                                              │
+│  🏦 Side Pot Calculation                                                    │
+│  📊 Rake Support (% + cap + noFlopNoDrop)                                   │
+│  🏆 Tournament Mode (blind structure)                                       │
+│  👀 View Masking (anti-cheat)                                               │
+│  💾 Snapshot Serialization                                                  │
+│  ↩️  Undo Support                                                           │
+│  📜 Hand History Export (JSON, PokerStars)                                  │
+│  🌐 Browser Support (Web Crypto RNG)                                        │
+│  🔒 Type-safe Error Handling                                                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📦 Installation
 
 ```bash
-# npm
 npm install @pokertools/engine
+```
 
-# yarn
+```bash
 yarn add @pokertools/engine
+```
 
-# pnpm
+```bash
 pnpm add @pokertools/engine
 ```
 
-## Quick Start
+---
 
-This example demonstrates a simple Pre-flop to Flop sequence.
+## 🚀 Quick Start
 
 ```typescript
 import { PokerEngine, ActionType } from "@pokertools/engine";
 
-// 1. Setup Table
-const engine = new PokerEngine({ smallBlind: 10, bigBlind: 20 });
-
-// 2. Event Listener (Logging)
-// Subscribe before playing to capture all events
-engine.on((action, oldState, newState) => {
-  console.log(`[${action.type}] ${newState.street} - Pot: ${newState.pot}`);
+// Create a cash game table
+const engine = new PokerEngine({
+  smallBlind: 1,
+  bigBlind: 2,
+  maxPlayers: 6,
 });
 
-// 3. Manage Players
-engine.sit(0, "p1", "Alice", 1000);
-engine.sit(1, "p2", "Bob", 1000);
-engine.sit(2, "p3", "Tom", 100);
+// Seat players
+engine.sit(0, "alice", "Alice", 200);
+engine.sit(1, "bob", "Bob", 200);
 
-engine.stand("p3"); // Tom leaves
-engine.sit(2, "p4", "Charlie", 500); // Charlie takes the seat
-
-// 4. Start Hand
-// Button: Alice (Seat 0), SB: Bob (Seat 1), BB: Charlie (Seat 2)
+// Deal a hand
 engine.deal();
 
-// 5. Pre-Flop Action
-// Action starts with Button (Alice) in 3-handed play
-engine.act({ type: ActionType.FOLD, playerId: "p1" }); // Alice folds
-engine.act({ type: ActionType.CALL, playerId: "p2" }); // Bob completes SB to 20 (posts 10 more)
-engine.act({ type: ActionType.CHECK, playerId: "p4" }); // Charlie checks option (already posted BB)
+// Get current state
+console.log(engine.state.street); // "PREFLOP"
+console.log(engine.state.actionTo); // 0 (Alice's turn)
+
+// Execute actions
+engine.act({ type: ActionType.CALL, playerId: "alice" });
+engine.act({ type: ActionType.CHECK, playerId: "bob" });
 
-// 6. Flop Action (Pot: 40)
-// Engine auto-deals Flop. Bob acts first (first active player left of button).
-engine.act({ type: ActionType.CHECK, playerId: "p2" });
-engine.act({ type: ActionType.BET, playerId: "p4", amount: 40 }); // Charlie bets 40
-engine.act({ type: ActionType.CALL, playerId: "p2" }); // Bob calls 40
+// Get player view (masked for opponents)
+const aliceView = engine.view("alice");
+```
 
-// 7. Inspect Data
-// Global state (Admin/Server only - reveals all cards)
-const globalState = engine.state;
+---
 
-// Player view (Safe for Client - masks opponents' cards)
-const bobView = engine.view("p2");
+## 🏗️ Architecture
 
-console.log(`Board: ${globalState.board}`); // e.g., ["As", "Kd", "2c"]
-console.log(`Bob's Hand: ${bobView.players[1].hand}`); // e.g., ["Ah", "Kh"]
-console.log(`Charlie's Hand: ${bobView.players[2].hand ?? "Hidden"}`); // "Hidden" (masked)
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           ARCHITECTURE                                      │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                    ┌──────────────────────────────┐
+                    │        PokerEngine           │
+                    │   (Stateful API Wrapper)     │
+                    └──────────────┬───────────────┘
+                                   │
+                                   ▼
+                    ┌──────────────────────────────┐
+                    │        gameReducer           │
+                    │   f(state, action) => state  │
+                    │     (Pure Function)          │
+                    └──────────────┬───────────────┘
+                                   │
+         ┌─────────────────────────┼─────────────────────────┐
+         │                         │                         │
+         ▼                         ▼                         ▼
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│    Actions      │     │     Rules       │     │    Utilities    │
+├─────────────────┤     ├─────────────────┤     ├─────────────────┤
+│ • betting.ts    │     │ • actionOrder   │     │ • viewMasking   │
+│ • dealing.ts    │     │ • blinds        │     │ • serialization │
+│ • management.ts │     │ • headsUp       │     │ • invariants    │
+│ • showdown.ts   │     │ • showdown      │     │ • rake          │
+│ • special.ts    │     │ • sidePots      │     │ • deck          │
+│ • tournament.ts │     └─────────────────┘     │ • cardUtils     │
+└─────────────────┘                             └─────────────────┘
 ```
 
-### Configuration Examples
+### State Flow
 
-#### Cash Game with Rake
+```
+┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌──────────┐
+│ PREFLOP │ ──▶  │  FLOP   │ ──▶  │  TURN   │ ──▶  │  RIVER  │ ──▶  │ SHOWDOWN │
+└─────────┘      └─────────┘      └─────────┘      └─────────┘      └──────────┘
+     │                                                                    │
+     │                    All but one fold                                │
+     └────────────────────────────────────────────────────────────────────┘
+                              (Award pot)
+```
 
-```typescript
-const cashEngine = new PokerEngine({
-  smallBlind: 5,
-  bigBlind: 10,
-  rakePercent: 5, // 5% rake
-  rakeCap: 10, // Max 10 chips per pot
-});
+---
 
-// After showdown
-console.log(cashEngine.state.rakeThisHand); // e.g., 5 (rake collected)
-// Chip conservation automatically accounts for rake
-```
+## 📖 API Reference
+
+### PokerEngine Class
 
-#### Tournament (No Rake)
+#### Constructor
 
 ```typescript
-const tournamentEngine = new PokerEngine({
-  smallBlind: 25,
-  bigBlind: 50,
-  ante: 5,
-  blindStructure: [
-    { smallBlind: 25, bigBlind: 50, ante: 5 },
-    { smallBlind: 50, bigBlind: 100, ante: 10 },
-    { smallBlind: 100, bigBlind: 200, ante: 25 },
-  ],
-});
+import { PokerEngine } from "@pokertools/engine";
 
-// Rake is automatically disabled for tournaments
-console.log(tournamentEngine.state.rakeThisHand); // Always 0
+const engine = new PokerEngine(config: TableConfig, timeProvider?: () => number);
 ```
 
-## Architecture
+**TableConfig Options:**
 
-Unlike traditional object-oriented poker engines where `player.bet()` mutates the player object in place, `@pokertools/engine` uses a **Reducer Pattern**.
+| Option              | Type           | Default       | Description                  |
+| ------------------- | -------------- | ------------- | ---------------------------- |
+| `smallBlind`        | `number`       | required      | Small blind amount           |
+| `bigBlind`          | `number`       | required      | Big blind amount             |
+| `ante`              | `number`       | `0`           | Ante per player              |
+| `maxPlayers`        | `number`       | `9`           | Maximum seats (2-10)         |
+| `blindStructure`    | `BlindLevel[]` | -             | Tournament blind levels      |
+| `timeBankSeconds`   | `number`       | `30`          | Time bank per player         |
+| `rakePercent`       | `number`       | `0`           | Rake percentage (0-100)      |
+| `rakeCap`           | `number`       | -             | Maximum rake per pot         |
+| `noFlopNoDrop`      | `boolean`      | `true`        | No rake if hand ends preflop |
+| `randomProvider`    | `() => number` | `Math.random` | RNG function                 |
+| `validateIntegrity` | `boolean`      | `true`        | Enable chip auditing         |
+| `isClient`          | `boolean`      | `false`       | Client/optimistic mode       |
+
+---
+
+#### Core Methods
+
+##### `sit(seat, id, name, stack)`
+
+Add a player to the table.
 
 ```typescript
-function gameReducer(state: GameState, action: Action): GameState;
-```
-
-This design enables:
-
-1. **Time Travel:** You can save an array of `Action` objects and replay an entire hand perfectly to debug issues.
-2. **Concurrency:** Since the state is immutable, you can safely read the state in one thread (e.g., sending updates to clients) while calculating the next state in another.
-3. **Testability:** Testing becomes a matter of input vs. output, without complex setup/teardown of class instances.
-
-## Project Structure
-
-The recommended file structure for this library follows separation-of-concerns principles:
-
-```
-@pokertools/engine/
-.
-├── LICENSE
-├── README.md
-├── jest.config.js
-├── package.json
-├── src
-│   ├── actions
-│   │   ├── betting.ts
-│   │   ├── dealing.ts
-│   │   ├── management.ts
-│   │   ├── showdownActions.ts
-│   │   ├── special.ts
-│   │   ├── streetProgression.ts
-│   │   ├── tournament.ts
-│   │   └── validation.ts
-│   ├── engine
-│   │   ├── PokerEngine.ts
-│   │   └── gameReducer.ts
-│   ├── errors
-│   │   ├── ConfigError.ts
-│   │   ├── CriticalStateError.ts
-│   │   ├── ErrorCodes.ts
-│   │   ├── IllegalActionError.ts
-│   │   ├── PokerEngineError.ts
-│   │   └── index.ts
-│   ├── history
-│   │   ├── exporter.ts
-│   │   ├── formats
-│   │   │   ├── json.ts
-│   │   │   └── pokerstars.ts
-│   │   ├── handHistoryBuilder.ts
-│   │   └── types.ts
-│   ├── index.ts
-│   ├── rules
-│   │   ├── actionOrder.ts
-│   │   ├── blinds.ts
-│   │   ├── headsUp.ts
-│   │   ├── showdown.ts
-│   │   └── sidePots.ts
-│   └── utils
-│       ├── cardUtils.ts
-│       ├── constants.ts
-│       ├── deck.ts
-│       ├── invariants.ts
-│       ├── positioning.ts
-│       ├── rake.ts
-│       ├── serialization.ts
-│       ├── validation.ts
-│       └── viewMasking.ts
-├── tests
-│   ├── bugs
-│   ├── debug
-│   ├── integration
-│   ├── property
-│   ├── security
-│   └── unit
-└── tsconfig.json
-```
-
-## Advanced Usage
-
-### Provable Fairness (Custom RNG)
-
-By default, the engine uses `Math.random()`. For real-money gaming, tournaments, or replayable simulations, you **must** inject a seeded or crypto-secure generator. This allows you to prove to players that the deck was shuffled fairly.
+engine.sit(0, "user123", "Alice", 1000);
+```
+
+##### `stand(id)`
+
+Remove a player from the table.
 
 ```typescript
-import seedrandom from "seedrandom";
+engine.stand("user123");
+```
 
-// Create a seeded generator (or use a Crypto API)
-const rng = seedrandom("championship-final-table-seed-12345");
+##### `deal()`
 
-const engine = new PokerEngine({
-  smallBlind: 10,
-  bigBlind: 20,
-  // The engine will use this function for all shuffling and random decisions
-  randomProvider: () => rng.quick(),
-});
+Deal a new hand.
+
+```typescript
+engine.deal();
 ```
 
-### Crash Recovery (Snapshots)
+##### `act(action)`
 
-Because the state is immutable and serializable, you can save the game state to a persistent store (Redis, Postgres, File System) after every move. If your Node.js process crashes, you can restore the table instantly.
+Execute a game action.
 
 ```typescript
-// --- 1. SAVING ---
-// Get a lightweight, serializable JSON object
-const snapshot = engine.snapshot;
-// Save to database (e.g., Redis key "table:101")
-await db.save("table:101", JSON.stringify(snapshot));
+// Fold
+engine.act({ type: ActionType.FOLD, playerId: "user123" });
 
-// ... Server Crashes or Restarts ...
+// Check
+engine.act({ type: ActionType.CHECK, playerId: "user123" });
 
-// --- 2. RESTORING ---
-const savedJson = await db.get("table:101");
-const snapshot = JSON.parse(savedJson);
+// Call
+engine.act({ type: ActionType.CALL, playerId: "user123" });
 
-// Create a new engine instance pre-loaded with the exact previous state
-const engine = PokerEngine.restore(snapshot);
+// Bet (opening bet)
+engine.act({ type: ActionType.BET, playerId: "user123", amount: 100 });
 
-// Resume play immediately - players won't even notice the restart
-console.log(engine.state.actionTo);
-```
+// Raise
+engine.act({ type: ActionType.RAISE, playerId: "user123", amount: 200 });
 
-### Event Subscription & Middleware
+// Show cards at showdown
+engine.act({ type: ActionType.SHOW, playerId: "user123", cardIndices: [0, 1] });
 
-Since the engine is pure, you need a way to know "What just happened?" to trigger side effects like playing sounds, updating the UI, or logging to an analytics server.
+// Muck cards at showdown
+engine.act({ type: ActionType.MUCK, playerId: "user123" });
 
-The engine provides a subscription model that receives the `Action`, the `OldState`, and the `NewState`.
+// Activate time bank
+engine.act({ type: ActionType.TIME_BANK, playerId: "user123" });
+```
 
-```typescript
-engine.on((action, oldState, newState) => {
-  // 1. Detect Phase Changes (e.g., Preflop -> Flop)
-  if (newState.street !== oldState.street) {
-    console.log(`[EVENT] Dealing ${newState.street}: ${newState.board}`);
-    socket.emit("playSound", "deal_cards");
-  }
+---
 
-  // 2. Detect Player Actions
-  if (action.type === ActionType.FOLD) {
-    console.log(`[EVENT] Player ${action.playerId} folded.`);
-    socket.emit("animation", { type: "fold", seat: action.playerId });
-  }
+#### State Access
 
-  // 3. Detect Winners
-  if (newState.winners && !oldState.winners) {
-    console.log(`[EVENT] Winners:`, newState.winners);
-    // Trigger chip gathering animation
-  }
-});
+##### `state` (getter)
+
+Get full unmasked game state.
+
+```typescript
+const state = engine.state;
+console.log(state.street); // "PREFLOP" | "FLOP" | "TURN" | "RIVER" | "SHOWDOWN"
+console.log(state.actionTo); // Seat number of current actor
+console.log(state.board); // Community cards ["As", "Kd", "Qh"]
+console.log(state.pots); // Array of pot objects
+console.log(state.winners); // null or Winner[] after showdown
 ```
 
-### Hand History Export
+##### `view(playerId?, version?)`
 
-Serious players require Hand Histories to analyze their gameplay in tools like **PokerTracker 4**, **Holdem Manager 3**, or **GTO Wizard**. The engine can export the current hand in a standardized text format.
+Get player-specific view with opponent cards masked.
 
 ```typescript
-// Call this at the end of a hand (Street = SHOWDOWN)
-const historyText = engine.history();
-
-console.log(historyText);
-
-/* Output Example:
-PokerStars Hand #23948239048: Hold'em No Limit ($10/$20 USD) - YYYY/MM/DD
-Table 'Alpha' 6-max Seat #1 is the button
-Seat 1: Alice ($1000 in chips) 
-Seat 2: Bob ($1000 in chips) 
-Bob: posts small blind $10
-Alice: posts big blind $20
-*** HOLE CARDS ***
-Dealt to Bob [Ah Kh]
-Bob: raises $40 to $60
-...
-*/
+// Player view (sees own cards)
+const aliceView = engine.view("alice");
+
+// Spectator view (all hole cards hidden)
+const spectatorView = engine.view();
+
+// With version number for sync
+const versioned = engine.view("alice", 42);
 ```
 
-### Time Banks & Timeout Logic
+---
 
-The engine follows a strict separation of concerns:
+#### Validation
 
-- **The Server** manages the clock (Real-time).
-- **The Engine** manages the Time Bank (Resource).
+##### `validate(action)`
 
-The engine does not include a `setTimeout`. Instead, you dispatch explicit actions when the server determines time has expired.
+Check if action is valid without executing.
 
 ```typescript
-// Scenario: Server timer hits 0.0s for Player P1
+const result = engine.validate({
+  type: ActionType.BET,
+  playerId: "alice",
+  amount: 100,
+});
 
-// 1. Check if player has Time Bank remaining
-if (engine.canUseTimeBank("p1")) {
-  // Auto-activate time bank: Deducts time tokens and keeps action on P1
-  engine.act({ type: ActionType.TIME_BANK, playerId: "p1" });
-  console.log("Time Bank activated!");
+if (result.valid) {
+  // Action can be executed
 } else {
-  // 2. No time left: Force a Fold (or Check if allowed)
-  // This action will also mark the player as "Sitting Out"
-  engine.act({ type: ActionType.TIMEOUT, playerId: "p1" });
-  console.log("Player timed out and folded.");
+  console.log(result.error); // "Cannot bet, there's already a bet to call"
+  console.log(result.code); // "CANNOT_BET"
 }
 ```
 
-### Undo & Rollback
+---
 
-Essential for admin tools, friendly games, or correcting misclicks. Since the engine uses a persistent data structure, rolling back to a previous state is computationally cheap and instant.
+#### Serialization
 
-```typescript
-// 1. Player misclicks Fold
-engine.act({ type: ActionType.FOLD, playerId: "p1" });
+##### `snapshot` (getter)
 
-// 2. Admin intervenes
-engine.undo();
+Get serializable snapshot.
 
-// 3. State is now exactly as it was before the fold
-// The actionTo pointer is back on p1
+```typescript
+const snapshot = engine.snapshot;
+localStorage.setItem("game", JSON.stringify(snapshot));
 ```
 
-### Tournament Blind Schedules
+##### `PokerEngine.restore(snapshot)`
 
-For tournaments, you can define a blind structure. The engine does not auto-increment automatically (as that is often time-based), but provides a simple API to advance levels.
+Restore from snapshot.
 
 ```typescript
-const engine = new PokerEngine({
-  initialStack: 1500,
-  blindStructure: [
-    { smallBlind: 10, bigBlind: 20, ante: 0 }, // Level 1
-    { smallBlind: 20, bigBlind: 40, ante: 0 }, // Level 2
-    { smallBlind: 50, bigBlind: 100, ante: 10 }, // Level 3
-  ],
-});
+const saved = JSON.parse(localStorage.getItem("game")!);
+const engine = PokerEngine.restore(saved);
+```
 
-// ... Play some hands ...
+---
 
-// Advance to Level 2
-engine.nextBlindLevel();
-console.log(engine.blinds); // { smallBlind: 20, bigBlind: 40 }
-```
+#### Event Handling
 
-### Scalability & Worker Threads
+##### `on(callback)`
 
-For high-volume applications (e.g., 10,000 concurrent tables), running poker logic on the main Node.js event loop can block I/O. Because the engine is state-in/state-out, it is trivial to offload to **Worker Threads**.
+Subscribe to state changes.
 
 ```typescript
-// worker.ts
-import { parentPort } from "worker_threads";
-import { PokerEngine } from "@pokertools/engine";
-
-parentPort?.on("message", (msg) => {
-  if (msg.type === "PROCESS_ACTION") {
-    // 1. Rehydrate engine from snapshot
-    const engine = PokerEngine.restore(msg.snapshot);
-    // 2. Run logic
-    const newState = engine.act(msg.action);
-    // 3. Send result back to Main Thread
-    parentPort?.postMessage({ status: "success", state: newState });
-  }
+const unsubscribe = engine.on((action, oldState, newState) => {
+  console.log(`Action: ${action.type}`);
+  console.log(`Street: ${oldState.street} -> ${newState.street}`);
 });
+
+// Later: unsubscribe
+unsubscribe();
 ```
 
-## Security & Integrity
+---
 
-### View Masking (Anti-Cheat)
+#### Undo
 
-**Critical:** Never send the full `GameState` result from `state` to a client. It contains the Deck and Opponent Hole Cards.
+##### `undo()`
 
-Use the built-in view generator to create a sanitized version for specific players.
+Undo last action.
 
 ```typescript
-// Server Code
-const globalState = engine.state;
+const success = engine.undo();
+if (success) {
+  console.log("Action undone");
+}
+```
+
+---
+
+#### Tournament
 
-// Send to Alice (Seat 1)
-// - Hides Bob's cards
-// - Hides the Deck
-// - Respects shownCards for granular visibility
-const aliceView = engine.view("p1");
-socket.to("p1").emit("gameState", aliceView);
+##### `nextBlindLevel()`
 
-// Send to Bob (Seat 2)
-const bobView = engine.view("p2");
-socket.to("p2").emit("gameState", bobView);
+Advance to next blind level.
+
+```typescript
+engine.nextBlindLevel();
+console.log(engine.state.blindLevel); // 1
+console.log(engine.state.bigBlind); // Updated
 ```
 
-#### Granular Card Visibility (New Feature)
+---
 
-At showdown, players can control which cards are revealed using the `shownCards` field:
+#### Hand History
+
+##### `history(options?)`
+
+Export hand history in various formats.
 
 ```typescript
-// Player state after showdown
-player.hand = ["As", "Kd"]; // Actual cards (always preserved)
-player.shownCards = [0, 1]; // Both cards shown (winner)
+// JSON format (default)
+const json = engine.history();
 
-// Or for selective showing
-player.shownCards = [0]; // Only left card shown
-player.shownCards = null; // Mucked (no cards shown)
+// PokerStars format
+const ps = engine.history({ format: "pokerstars" });
 
-// Public view respects shownCards and preserves positional context:
-// - shownCards: [0, 1] → hand: ["As", "Kd"]  (both visible)
-// - shownCards: [0]    → hand: ["As", null]  (left visible, right hidden)
-// - shownCards: [1]    → hand: [null, "Kd"]  (left hidden, right visible)
-// - shownCards: null   → hand: null          (completely mucked)
+// Compact JSON
+const compact = engine.history({ format: "compact" });
 ```
 
-**Important:** The view masking preserves positional context by using `null` for hidden cards. This ensures clients know which card is being shown (left vs right).
+##### `getHandHistory()`
+
+Get structured history object.
+
+```typescript
+const history = engine.getHandHistory();
+console.log(history.handId);
+console.log(history.winners);
+console.log(history.streets);
+```
+
+---
+
+#### Optimistic Updates
 
-#### Optional Show Actions
+##### `optimisticAct(action)`
 
-Players can reveal their cards after showdown:
+Preview action result without modifying state.
 
 ```typescript
-// Loser reveals both cards to show a bluff
-engine.act({
-  type: ActionType.SHOW,
-  playerId: "loser123",
-  // cardIndices optional - defaults to all cards [0, 1]
+const preview = engine.optimisticAct({
+  type: ActionType.BET,
+  playerId: "alice",
+  amount: 100,
 });
 
-// Or show only specific cards
-engine.act({
-  type: ActionType.SHOW,
-  playerId: "player456",
-  cardIndices: [0], // Show only left card
-});
+// preview contains new state
+// engine.state is unchanged
+```
 
-// Winner can also explicitly show (already shown by default)
-engine.act({
-  type: ActionType.SHOW,
-  playerId: "winner789",
-});
+##### `reconcile(serverState)`
+
+Merge server state into client engine.
+
+```typescript
+// After receiving state from server
+engine.reconcile(serverState);
 ```
 
-### Invariant Auditing
+---
 
-The engine implements strict accounting logic. After every single action, it runs an internal audit to ensure **Conservation of Chips**.
+## 💰 Money Handling
 
-$$\sum(\text{PlayerStacks}) + \sum(\text{Pots}) + \sum(\text{CurrentBets}) = \text{InitialChips}$$
+### Chip Conservation
 
-If a logic bug ever causes a chip to duplicate or vanish, the engine throws a `CriticalStateError`.
+The engine enforces strict chip conservation:
 
-**Recommendation:** Wrap your `act` calls in a try/catch. If this error occurs, **freeze the table** immediately. It indicates a serious data integrity issue.
+```
+∑(player.stack) + ∑(pot.amount) + ∑(currentBets) + rake = constant
+```
 
-### Integer Arithmetic
+Any violation throws `CriticalStateError`.
 
-To ensure financial accuracy, the engine strictly forbids floating-point numbers.
+### Side Pots
 
-- **Input:** All stacks, bets, and blinds must be Integers (representing cents or the smallest chip unit).
-- **Internal:** Pot divisions use integer division with deterministic remainder distribution (by position).
-- **Safety:** This prevents "Penny Drift" exploits common in JavaScript floating-point math.
+Automatic side pot calculation for all-in scenarios:
 
-## Rule Logic & Edge Cases
+```typescript
+// Example: 3 players with different stacks
+// Alice: 100 (all-in)
+// Bob: 300 (all-in)
+// Charlie: 500 (active)
+
+// Results in:
+// Main Pot: 300 (100 × 3) - Alice, Bob, Charlie eligible
+// Side Pot: 400 (200 × 2) - Bob, Charlie eligible
+// Uncalled: 200 - returned to Charlie
+```
 
-This engine isn't just a loop; it is a strict implementation of standard TDA (Tournament Directors Association) rules.
+### Rake
 
-### 1. Heads-Up Positioning
+```typescript
+const engine = new PokerEngine({
+  smallBlind: 1,
+  bigBlind: 2,
+  rakePercent: 5, // 5% rake
+  rakeCap: 10, // Max $10 per pot
+  noFlopNoDrop: true, // No rake if ends preflop
+});
+```
 
-In a standard game (3+ players), the Small Blind is to the left of the Button.
+---
 
-- **The Trap:** In Heads-Up (2 players), the **Button IS the Small Blind**.
-- **The Rule:** The Button acts **first** Pre-Flop, and acts **last** Post-Flop.
-- **Implementation:** The engine detects when exactly 2 players are active (not folded/busted) and automatically swaps the blind posting order and action order to comply with this rule.
+## 🏆 Tournament Mode
 
-### 2. The "Incomplete Raise"
+```typescript
+const tournament = new PokerEngine({
+  smallBlind: 25,
+  bigBlind: 50,
+  ante: 5,
+  maxPlayers: 9,
+  initialStack: 10000,
+  blindStructure: [
+    { smallBlind: 25, bigBlind: 50, ante: 5 },
+    { smallBlind: 50, bigBlind: 100, ante: 10 },
+    { smallBlind: 75, bigBlind: 150, ante: 15 },
+    { smallBlind: 100, bigBlind: 200, ante: 25 },
+    { smallBlind: 150, bigBlind: 300, ante: 50 },
+  ],
+});
+
+// Advance blinds (e.g., on timer)
+tournament.nextBlindLevel();
+```
 
-- **Scenario:** Player A bets 100. Player B is All-In for 120 (Raise of 20). Min raise is 100.
-- **The Rule:** Since the raise (20) is less than 50% (or 100% depending on ruleset) of the min-raise, the betting is **NOT** re-opened for Player A. Player A can only CALL or FOLD. They cannot re-raise.
-- **Implementation:** The engine tracks `legalActions` and will throw `ILLEGAL_ACTION` if Player A attempts to raise in this spot.
+**Tournament-specific rules:**
 
-### 3. Split Pot "Odd Chip" Resolution
+- Sitting-out players must post blinds/antes
+- Dead button rule for empty seats
+- No rake
 
-In split pots (e.g., High-Low or Tie), chip counts often result in decimals (e.g., 25 chips / 2 players = 12.5).
+---
 
-- **The Rule:** The odd chip goes to the player in the **worst position** (closest to the left of the button). In High-Low games, the odd chip goes to the High hand.
-- **Implementation:** The engine resolves this deterministically using seat indexes relative to the dealer button.
+## 🌐 Browser Usage
 
-### 4. Side Pots (Iterative Subtraction)
+```typescript
+import { createBrowserEngine } from "@pokertools/engine/browser";
 
-The engine handles complex multi-way all-ins.
+// Uses Web Crypto API for secure RNG
+const engine = createBrowserEngine({
+  smallBlind: 1,
+  bigBlind: 2,
+});
+```
 
-- **Scenario:** A (100 chips), B (500 chips), C (1000 chips) all go All-In.
-- **Pot 1 (Main):** 300 chips (100 each from A, B, C). A, B, and C contest this.
-- **Pot 2 (Side):** 800 chips (400 each from B and C). Only B and C contest this.
-- **Remaining:** C's extra 500 chips are returned (no one to match).
-- **Resolution:** The engine evaluates hands for Pot 2 first, awards it, then evaluates Pot 1.
+---
 
-## API Reference
+## ❌ Error Handling
 
-### `PokerEngine` Class
+### Error Types
 
-| Method        | Arguments               | Returns       | Description                                        |
-| ------------- | ----------------------- | ------------- | -------------------------------------------------- |
-| `constructor` | `config`                | `PokerEngine` | Creates a new table instance.                      |
-| `sit`         | `seat, id, name, stack` | `void`        | Adds a player to a specific seat.                  |
-| `stand`       | `id`                    | `void`        | Removes a player.                                  |
-| `deal`        | `none`                  | `void`        | Starts the hand (Shuffles/Posts Blinds).           |
-| `act`         | `action`                | `GameState`   | Executes a move.                                   |
-| `undo`        | `none`                  | `boolean`     | Reverts state to previous step.                    |
-| `state`       | _(Getter)_              | `GameState`   | The full, internal, unmasked state.                |
-| `view`        | `id?`                   | `PublicState` | Masked state for a player (or spectator if no ID). |
-| `snapshot`    | _(Getter)_              | `object`      | Serializable JSON for database storage.            |
-| `restore`     | `snapshot`              | `PokerEngine` | **Static.** Recreates engine from backup.          |
-| `history`     | `none`                  | `string`      | Generates the text log (PHH/PokerStars).           |
-| `on`          | `fn(act, old, new)`     | `unsub`       | Subscribe to state changes.                        |
+| Error                | Description                                     |
+| -------------------- | ----------------------------------------------- |
+| `IllegalActionError` | Invalid game action (send to client)            |
+| `CriticalStateError` | Engine invariant violated (should never happen) |
+| `ConfigError`        | Invalid configuration                           |
 
-### `Action` Types
+### Error Codes
 
 ```typescript
-interface Action {
-  type: ActionType;
-  playerId: string;
-  amount?: number; // Required for BET and RAISE
+import { ErrorCodes } from "@pokertools/engine";
+
+try {
+  engine.act({ type: ActionType.CHECK, playerId: "alice" });
+} catch (err) {
+  if (err instanceof IllegalActionError) {
+    switch (err.code) {
+      case ErrorCodes.NOT_YOUR_TURN:
+        showMessage("Wait for your turn");
+        break;
+      case ErrorCodes.CANNOT_CHECK:
+        showMessage("You must call or fold");
+        break;
+      case ErrorCodes.BET_TOO_SMALL:
+        showMessage(`Minimum bet is ${err.context.minBet}`);
+        break;
+    }
+  }
 }
+```
+
+**Available Error Codes:**
+
+| Category | Codes                                                                 |
+| -------- | --------------------------------------------------------------------- |
+| Player   | `PLAYER_NOT_FOUND`, `NOT_YOUR_TURN`, `NOT_SEATED`, `NO_CHIPS`         |
+| Betting  | `CANNOT_CHECK`, `NOTHING_TO_CALL`, `BET_TOO_SMALL`, `RAISE_TOO_SMALL` |
+| Deal     | `CANNOT_DEAL`, `NOT_ENOUGH_PLAYERS`                                   |
+| Seat     | `INVALID_SEAT`, `SEAT_OCCUPIED`, `INVALID_STACK`                      |
+
+---
+
+## 🎴 Action Types
+
+```typescript
+import { ActionType } from "@pokertools/engine";
 
 enum ActionType {
+  // Management
+  SIT = "SIT",
+  STAND = "STAND",
+  ADD_CHIPS = "ADD_CHIPS",
+  RESERVE_SEAT = "RESERVE_SEAT",
+
+  // Dealing
+  DEAL = "DEAL",
+
+  // Betting
   FOLD = "FOLD",
   CHECK = "CHECK",
   CALL = "CALL",
-  BET = "BET", // Opening a bet
-  RAISE = "RAISE", // Increasing an existing bet
+  BET = "BET",
+  RAISE = "RAISE",
+
+  // Showdown
+  SHOW = "SHOW",
+  MUCK = "MUCK",
+
+  // Special
   TIMEOUT = "TIMEOUT",
-  TIME_BANK = "TIME_BANK", // Extends turn using time bank
+  TIME_BANK = "TIME_BANK",
+
+  // Tournament
+  NEXT_BLIND_LEVEL = "NEXT_BLIND_LEVEL",
+}
+```
+
+---
+
+## 📜 Hand History Export
+
+### JSON Format
+
+```typescript
+const history = engine.history({ format: "json" });
+```
+
+```json
+{
+  "handId": "hand-1734012345678-123456",
+  "timestamp": 1734012345678,
+  "tableName": "Table 1",
+  "gameType": "Cash",
+  "stakes": { "smallBlind": 1, "bigBlind": 2, "ante": 0 },
+  "buttonSeat": 0,
+  "players": [
+    { "seat": 0, "name": "Alice", "startingStack": 200, "endingStack": 220 },
+    { "seat": 1, "name": "Bob", "startingStack": 200, "endingStack": 180 }
+  ],
+  "streets": [
+    {
+      "street": "PREFLOP",
+      "board": [],
+      "actions": [...]
+    }
+  ],
+  "winners": [
+    { "seat": 0, "playerName": "Alice", "amount": 20, "hand": ["As", "Kd"], "handRank": "Two Pair" }
+  ],
+  "totalPot": 40
 }
 ```
 
-## Error Handling
+### PokerStars Format
+
+```typescript
+const history = engine.history({ format: "pokerstars" });
+```
+
+```
+PokerStars Hand #hand-1734012345678: Hold'em No Limit ($1/$2 USD)
+Table 'Table 1' 6-max Seat #1 is the button
+Seat 1: Alice ($200 in chips)
+Seat 2: Bob ($200 in chips)
+Alice: posts small blind $1
+Bob: posts big blind $2
+*** HOLE CARDS ***
+Dealt to Alice [As Kd]
+Alice: calls $1
+Bob: checks
+*** FLOP *** [Qh Jc Ts]
+...
+```
+
+---
+
+## 🔧 Utilities
+
+### View Masking
+
+```typescript
+import { createPublicView } from "@pokertools/engine";
+
+// Create masked view for specific player
+const aliceView = createPublicView(state, "alice");
+
+// Spectator view (all cards hidden)
+const spectatorView = createPublicView(state, null);
+```
 
-The engine throws typed errors. You should wrap `act` calls in a `try/catch` block.
+### Chip Auditing
 
-| Error Code                   | Description                        | Recommended Action                   |
-| ---------------------------- | ---------------------------------- | ------------------------------------ |
-| `CRITICAL_INVARIANT_FAILURE` | Chips disappeared/duplicated.      | **FREEZE GAME**. Contact Support.    |
-| `NOT_YOUR_TURN`              | Player acted out of order.         | Ignore or warn client.               |
-| `INVALID_AMOUNT`             | Bet is below min-raise or > stack. | Reject action, ask for valid amount. |
-| `ILLEGAL_ACTION`             | Tried to Check when facing a bet.  | Reject action.                       |
-| `STALE_STATE`                | Optimistic UI mismatch.            | Send fresh `view()` to client.       |
+```typescript
+import { calculateTotalChips, auditChipConservation } from "@pokertools/engine";
+
+// Get total chips in game
+const total = calculateTotalChips(state);
+
+// Verify chip conservation (throws on failure)
+auditChipConservation(state, expectedTotal);
+```
+
+### Snapshot
+
+```typescript
+import { createSnapshot, restoreFromSnapshot } from "@pokertools/engine";
+
+// Serialize
+const snapshot = createSnapshot(state);
+const json = JSON.stringify(snapshot);
+
+// Deserialize
+const restored = restoreFromSnapshot(JSON.parse(json));
+```
+
+---
+
+## 🧪 Testing
+
+The engine includes 320 tests across multiple categories:
+
+| Category       | Files | Description                  |
+| -------------- | ----- | ---------------------------- |
+| Unit           | 24    | Individual component tests   |
+| Integration    | 4     | Full game flow tests         |
+| Property       | 3     | Randomized invariant testing |
+| Bug Regression | 2     | Fixed bug verification       |
+| Security       | 1     | Anti-cheat/exploit tests     |
+| Debug          | 4     | Detailed trace tests         |
+
+```bash
+npm test -w @pokertools/engine
+```
+
+---
+
+## 📊 State Structure
+
+```typescript
+interface GameState {
+  // Configuration
+  config: TableConfig;
+  players: (Player | null)[];
+  maxPlayers: number;
+
+  // Hand State
+  handNumber: number;
+  buttonSeat: number | null;
+  deck: number[]; // Card codes (server only)
+  board: string[]; // Community cards
+  street: Street;
+
+  // Betting
+  pots: Pot[];
+  currentBets: Map<number, number>;
+  minRaise: number;
+  lastRaiseAmount: number;
+  actionTo: number | null;
+  lastAggressorSeat: number | null;
+
+  // Progress
+  activePlayers: number[];
+  winners: Winner[] | null;
+  rakeThisHand: number;
+
+  // Blinds
+  smallBlind: number;
+  bigBlind: number;
+  ante: number;
+  blindLevel: number;
+
+  // Time Bank
+  timeBanks: Map<number, number>;
+  timeBankActiveSeat: number | null;
+
+  // History
+  actionHistory: ActionRecord[];
+  previousStates: GameState[]; // For undo
+
+  // Metadata
+  timestamp: number;
+  handId: string;
+}
+```
 
-## Contributing
+---
 
-This project is part of the `@pokertools` monorepo.
+## 🔗 Related Packages
 
-1. Clone the repository.
-2. Run `npm install`.
-3. Run `npm test`.
+| Package                               | Description        |
+| ------------------------------------- | ------------------ |
+| [@pokertools/types](../types)         | Type definitions   |
+| [@pokertools/evaluator](../evaluator) | Hand evaluation    |
+| [@pokertools/api](../api)             | REST/WebSocket API |
 
-**Note:** The test suite includes over 500 edge-case scenarios including split pots, kickers, and side-pot math. Please ensure all pass before submitting a PR.
+---
 
-## License
+## 📄 License
 
-MIT
+MIT © A.Aurelius