@pokertools/engine 1.0.0 → 1.0.4

package/dist/actions/dealing.js

@@ -15,23 +15,93 @@ const positioning_1 = require("../utils/positioning");
  */
 function handleDeal(state, action) {
     // Move button (Dead Button logic: moves to next seat index regardless of occupancy)
-    const newButtonSeat = moveButton(state);
+    let newButtonSeat = moveButton(state);
     // Determine if this is a tournament
     const isTournament = !!state.config.blindStructure;
-    // Create and shuffle deck
+    const isClient = !!state.config.isClient;
+    // Create and shuffle deck (server only)
+    // In client mode, we use an empty deck and deal masked cards
     const rng = state.config.randomProvider ?? Math.random;
-    const deck = (0, deck_1.shuffle)((0, deck_1.createDeck)(), rng);
+    const deck = isClient ? [] : (0, deck_1.shuffle)((0, deck_1.createDeck)(), rng);
+    // Create a copy of timeBanks to modify
+    const newTimeBanks = new Map(state.timeBanks);
+    // First, merge pendingAddOn into stack for all players
+    const newPlayers = state.players.map((player) => {
+        if (!player)
+            return null;
+        // Skip reserved players (they haven't confirmed yet)
+        if (player.status === "RESERVED" /* PlayerStatus.RESERVED */) {
+            // Check if reservation has expired
+            if (player.reservationExpiry && action.timestamp >= player.reservationExpiry) {
+                // Reservation expired, remove player
+                newTimeBanks.delete(player.seat);
+                return null;
+            }
+            // Keep reserved player as-is
+            return player;
+        }
+        // Merge pendingAddOn into stack
+        const newStack = player.stack + player.pendingAddOn;
+        return {
+            ...player,
+            stack: newStack,
+            pendingAddOn: 0, // Clear pending add-on
+        };
+    });
+    newButtonSeat = moveHeadsUpButtonToOccupiedSeat(newButtonSeat, {
+        ...state,
+        players: newPlayers,
+    });
+    // Get blind positions for this hand
+    const blindPositions = (0, blinds_1.getBlindPositions)({
+        ...state,
+        buttonSeat: newButtonSeat,
+        players: newPlayers,
+    });
     // Get players who will be dealt in
     const playersToReceive = [];
-    for (let seat = 0; seat < state.players.length; seat++) {
-        const player = state.players[seat];
-        if (player && player.stack > 0 && !player.isSittingOut) {
+    for (let seat = 0; seat < newPlayers.length; seat++) {
+        const player = newPlayers[seat];
+        // Basic eligibility checks
+        if (!player || player.stack <= 0 || player.status === "RESERVED" /* PlayerStatus.RESERVED */) {
+            continue;
+        }
+        // We check WAIT_FOR_BB *before* checking isSittingOut.
+        // This allows us to "unsit" a player if they hit the Big Blind.
+        let shouldPlay = true;
+        if (!isTournament && player.sitInOption === "WAIT_FOR_BB" /* SitInOption.WAIT_FOR_BB */) {
+            const isInBigBlind = blindPositions?.bigBlindSeat === seat;
+            if (isInBigBlind) {
+                // PLAYER RE-ENTRY: They are in the Big Blind. Force them active.
+                // We must update the player object in newPlayers to reflect they are back.
+                newPlayers[seat] = {
+                    ...player,
+                    isSittingOut: false,
+                };
+                shouldPlay = true;
+            }
+            else {
+                // Not in BB yet. Force them to sit out.
+                // Only update if not already sitting out to avoid object churn
+                if (!player.isSittingOut) {
+                    newPlayers[seat] = {
+                        ...player,
+                        isSittingOut: true,
+                    };
+                }
+                shouldPlay = false;
+            }
+        }
+        else if (player.isSittingOut) {
+            // Standard sitting out check
+            shouldPlay = false;
+        }
+        if (shouldPlay) {
             playersToReceive.push(seat);
         }
     }
     // Deal 2 cards to each player
     let remainingDeck = deck;
-    const newPlayers = [...state.players];
     // Initialize hands for receiving players (active, not sitting out)
     for (const seat of playersToReceive) {
         newPlayers[seat] = {
@@ -62,10 +132,17 @@ function handleDeal(state, action) {
     // Deal 2 cards, one by one, in circle (standard poker procedure)
     for (let round = 0; round < 2; round++) {
         for (const seat of playersToReceive) {
-            // Deal 1 card
-            const [cards, nextDeck] = (0, deck_1.dealCards)(remainingDeck, 1);
-            remainingDeck = nextDeck;
-            const cardStrings = (0, cardUtils_1.cardCodesToStrings)(cards);
+            let cardStrings;
+            if (isClient) {
+                // Client mode: Deal masked cards
+                cardStrings = [null];
+            }
+            else {
+                // Server mode: Deal from deck
+                const [cards, nextDeck] = (0, deck_1.dealCards)(remainingDeck, 1);
+                remainingDeck = nextDeck;
+                cardStrings = (0, cardUtils_1.cardCodesToStrings)(cards);
+            }
             // Append to existing hand
             const currentPlayer = newPlayers[seat];
             const currentHand = currentPlayer.hand ?? []; // Should be [] from initialization
@@ -76,14 +153,15 @@ function handleDeal(state, action) {
         }
     }
     // Post blinds and antes
-    const blindPositions = (0, blinds_1.getBlindPositions)({
+    // Recalculate blind positions with the new button seat
+    const finalBlindPositions = (0, blinds_1.getBlindPositions)({
         ...state,
         buttonSeat: newButtonSeat,
         players: newPlayers,
     });
     const currentBets = new Map();
-    if (blindPositions) {
-        const { smallBlindSeat, bigBlindSeat } = blindPositions;
+    if (finalBlindPositions) {
+        const { smallBlindSeat, bigBlindSeat } = finalBlindPositions;
         // Post small blind
         // In tournaments: sitting-out players MUST post to prevent "blinding off" exploit
         // In cash games: sitting-out SB is treated as "Dead Small Blind" (no post)
@@ -110,19 +188,24 @@ function handleDeal(state, action) {
         // Post big blind (Must exist for hand to start)
         const bbPlayer = newPlayers[bigBlindSeat];
         if (bbPlayer) {
-            const bbAmount = Math.min(bbPlayer.stack, state.bigBlind);
-            currentBets.set(bigBlindSeat, bbAmount);
-            newPlayers[bigBlindSeat] = {
-                ...bbPlayer,
-                stack: bbPlayer.stack - bbAmount,
-                betThisStreet: bbAmount,
-                totalInvestedThisHand: bbAmount,
-                status: bbAmount === bbPlayer.stack
-                    ? "ALL_IN" /* PlayerStatus.ALL_IN */
-                    : bbPlayer.isSittingOut
-                        ? "FOLDED" /* PlayerStatus.FOLDED */
-                        : "ACTIVE" /* PlayerStatus.ACTIVE */,
-            };
+            // In Cash Games: sitting-out players should NEVER post blinds (they are skipped by getBlindPositions)
+            // In Tournaments: sitting-out players MUST post blinds to prevent "blinding off" exploit
+            const shouldPostBB = isTournament || !bbPlayer.isSittingOut;
+            if (shouldPostBB) {
+                const bbAmount = Math.min(bbPlayer.stack, state.bigBlind);
+                currentBets.set(bigBlindSeat, bbAmount);
+                newPlayers[bigBlindSeat] = {
+                    ...bbPlayer,
+                    stack: bbPlayer.stack - bbAmount,
+                    betThisStreet: bbAmount,
+                    totalInvestedThisHand: bbAmount,
+                    status: bbAmount === bbPlayer.stack
+                        ? "ALL_IN" /* PlayerStatus.ALL_IN */
+                        : bbPlayer.isSittingOut
+                            ? "FOLDED" /* PlayerStatus.FOLDED */
+                            : "ACTIVE" /* PlayerStatus.ACTIVE */,
+                };
+            }
         }
     }
     // Post antes if configured
@@ -204,3 +287,11 @@ function moveButton(state) {
     // We do not skip empty seats here.
     return (0, positioning_1.getNextSeat)(state.buttonSeat, state.maxPlayers);
 }
+function moveHeadsUpButtonToOccupiedSeat(buttonSeat, state) {
+    const occupiedSeats = state.players.filter((player) => player !== null && player.stack > 0);
+    const buttonPlayer = state.players[buttonSeat];
+    if (occupiedSeats.length !== 2 || (buttonPlayer !== null && buttonPlayer.stack > 0)) {
+        return buttonSeat;
+    }
+    return (0, positioning_1.getNextOccupiedSeat)(buttonSeat, state.players, state.maxPlayers) ?? buttonSeat;
+}

package/dist/actions/management.d.ts

@@ -1,4 +1,4 @@
-import { GameState, SitAction, StandAction } from "@pokertools/types";
+import { GameState, SitAction, StandAction, AddChipsAction, ReserveSeatAction } from "@pokertools/types";
 /**
  * Handle SIT action - add player to table
  */
@@ -7,3 +7,14 @@ export declare function handleSit(state: GameState, action: SitAction): GameStat
  * Handle STAND action - remove player from table
  */
 export declare function handleStand(state: GameState, action: StandAction): GameState;
+/**
+ * Handle ADD_CHIPS action - add chips to player's pending stack
+ * Chips are held in pendingAddOn and will be merged into stack at start of next hand
+ */
+export declare function handleAddChips(state: GameState, action: AddChipsAction): GameState;
+/**
+ * Handle RESERVE_SEAT action - reserve a seat for a player
+ * Marks the seat as RESERVED with an expiration timestamp
+ * API can use this to lock a seat while processing payment
+ */
+export declare function handleReserveSeat(state: GameState, action: ReserveSeatAction): GameState;

package/dist/actions/management.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleSit = handleSit;
 exports.handleStand = handleStand;
+exports.handleAddChips = handleAddChips;
+exports.handleReserveSeat = handleReserveSeat;
 const positioning_1 = require("../utils/positioning");
+const betting_1 = require("./betting");
 /**
  * Handle SIT action - add player to table
  */
@@ -19,6 +22,9 @@ function handleSit(state, action) {
         totalInvestedThisHand: 0,
         isSittingOut: false,
         timeBank: state.config.timeBankSeconds ?? 30,
+        pendingAddOn: 0,
+        sitInOption: action.sitInOption ?? "IMMEDIATE" /* SitInOption.IMMEDIATE */,
+        reservationExpiry: null,
     };
     const newPlayers = [...state.players];
     newPlayers[action.seat] = newPlayer;
@@ -40,19 +46,94 @@ function handleStand(state, action) {
     if (!result) {
         return state;
     }
-    const { seat } = result;
-    const newPlayers = [...state.players];
+    let currentState = state;
+    const { player, seat } = result;
+    // 1. BEST PRACTICE: If the player is in a live hand, they must FOLD first.
+    // This resolves the "ActionTo" pointer, potential winners, and pot eligibility
+    // using the standard game rules defined in handleFold.
+    const isLiveHand = currentState.handNumber > 0 &&
+        currentState.street !== "SHOWDOWN" && // Not needed if hand is over
+        (player.status === "ACTIVE" || player.status === "ALL_IN");
+    if (isLiveHand) {
+        // Execute a "Virtual Fold" to gracefully exit the hand
+        currentState = (0, betting_1.handleFold)(currentState, {
+            type: "FOLD" /* ActionType.FOLD */,
+            playerId: player.id,
+            timestamp: action.timestamp,
+        });
+        // NOTE: handleFold returns a new state where actionTo has already been
+        // advanced to the next player. The invariant check will now pass.
+    }
+    // 2. Remove player from table (Standard Stand Logic)
+    const newPlayers = [...currentState.players];
     newPlayers[seat] = null;
     // Remove from time banks
-    const newTimeBanks = new Map(state.timeBanks);
+    const newTimeBanks = new Map(currentState.timeBanks);
     newTimeBanks.delete(seat);
     // Remove from active players if present
-    const newActivePlayers = state.activePlayers.filter((s) => s !== seat);
+    // (Note: handleFold might have already moved them to FOLDED status,
+    // but we ensure they are fully removed from tracking here)
+    const newActivePlayers = currentState.activePlayers.filter((s) => s !== seat);
     return {
-        ...state,
+        ...currentState,
         players: newPlayers,
         activePlayers: newActivePlayers,
         timeBanks: newTimeBanks,
         timestamp: action.timestamp,
     };
 }
+/**
+ * Handle ADD_CHIPS action - add chips to player's pending stack
+ * Chips are held in pendingAddOn and will be merged into stack at start of next hand
+ */
+function handleAddChips(state, action) {
+    const result = (0, positioning_1.getPlayerById)(state, action.playerId);
+    if (!result) {
+        return state;
+    }
+    const { player, seat } = result;
+    const newPlayers = [...state.players];
+    newPlayers[seat] = {
+        ...player,
+        pendingAddOn: player.pendingAddOn + action.amount,
+    };
+    return {
+        ...state,
+        players: newPlayers,
+        timestamp: action.timestamp,
+    };
+}
+/**
+ * Handle RESERVE_SEAT action - reserve a seat for a player
+ * Marks the seat as RESERVED with an expiration timestamp
+ * API can use this to lock a seat while processing payment
+ */
+function handleReserveSeat(state, action) {
+    // Check if seat is already occupied
+    if (state.players[action.seat] !== null) {
+        return state;
+    }
+    const reservedPlayer = {
+        id: action.playerId,
+        name: action.playerName,
+        seat: action.seat,
+        stack: 0,
+        hand: null,
+        shownCards: null,
+        status: "RESERVED" /* PlayerStatus.RESERVED */,
+        betThisStreet: 0,
+        totalInvestedThisHand: 0,
+        isSittingOut: false,
+        timeBank: state.config.timeBankSeconds ?? 30,
+        pendingAddOn: 0,
+        sitInOption: "IMMEDIATE" /* SitInOption.IMMEDIATE */,
+        reservationExpiry: action.expiryTimestamp,
+    };
+    const newPlayers = [...state.players];
+    newPlayers[action.seat] = reservedPlayer;
+    return {
+        ...state,
+        players: newPlayers,
+        timestamp: action.timestamp,
+    };
+}

package/dist/actions/special.d.ts

@@ -10,5 +10,23 @@ export declare function handleTimeout(state: GameState, action: TimeoutAction):
  * Handle TIME_BANK action
  * - Deducts time from player's time bank
  * - Keeps action on same player
+ *
+ * TIME BANK DEDUCTION POLICY:
+ * This implementation uses a "pay-per-activation" model where:
+ * - Each time bank activation deducts a fixed amount (default: 10 seconds)
+ * - Player receives the full deduction amount as additional time
+ * - If remaining time bank is less than the deduction, it is fully consumed
+ * - This prevents players from getting "free" time when they have < 10s remaining
+ *
+ * Example scenarios:
+ * - Player has 30s, activates time bank → 20s remaining, gets 10s additional time
+ * - Player has 5s, activates time bank → 0s remaining, gets 10s additional time
+ * - Player has 0s, cannot activate time bank → forced timeout/fold
+ *
+ * Alternative design consideration:
+ * If you want "time-as-resource" (only deduct what you use), you would need:
+ * - Track time used per activation in the UI layer
+ * - Deduct actual time consumed rather than fixed amount
+ * - Return unused time if action is made before deduction expires
  */
 export declare function handleTimeBank(state: GameState, action: TimeBankAction): GameState;

package/dist/actions/special.js

@@ -56,6 +56,24 @@ function handleTimeout(state, action) {
  * Handle TIME_BANK action
  * - Deducts time from player's time bank
  * - Keeps action on same player
+ *
+ * TIME BANK DEDUCTION POLICY:
+ * This implementation uses a "pay-per-activation" model where:
+ * - Each time bank activation deducts a fixed amount (default: 10 seconds)
+ * - Player receives the full deduction amount as additional time
+ * - If remaining time bank is less than the deduction, it is fully consumed
+ * - This prevents players from getting "free" time when they have < 10s remaining
+ *
+ * Example scenarios:
+ * - Player has 30s, activates time bank → 20s remaining, gets 10s additional time
+ * - Player has 5s, activates time bank → 0s remaining, gets 10s additional time
+ * - Player has 0s, cannot activate time bank → forced timeout/fold
+ *
+ * Alternative design consideration:
+ * If you want "time-as-resource" (only deduct what you use), you would need:
+ * - Track time used per activation in the UI layer
+ * - Deduct actual time consumed rather than fixed amount
+ * - Return unused time if action is made before deduction expires
  */
 function handleTimeBank(state, action) {
     const result = (0, positioning_1.getPlayerById)(state, action.playerId);
@@ -73,6 +91,7 @@ function handleTimeBank(state, action) {
         });
     }
     // Deduct time from player's time bank (configurable, default 10 seconds)
+    // Uses pay-per-activation model: deduct full amount even if less is available
     const deduction = state.config.timeBankDeductionSeconds ?? 10;
     const newTimeBank = Math.max(0, currentTimeBank - deduction);
     const newTimeBanks = new Map(state.timeBanks);
@@ -80,6 +99,7 @@ function handleTimeBank(state, action) {
     return {
         ...state,
         timeBanks: newTimeBanks,
+        timeBankActiveSeat: seat, // Mark time bank as active for this player
         timestamp: action.timestamp,
         // Keep actionTo the same (extends player's turn)
     };

package/dist/actions/validation.js

@@ -31,6 +31,12 @@ function validateAction(state, action) {
         case "TIME_BANK" /* ActionType.TIME_BANK */:
             validateTimeAction(state, action);
             break;
+        case "ADD_CHIPS" /* ActionType.ADD_CHIPS */:
+            validateAddChipsAction(state, action);
+            break;
+        case "RESERVE_SEAT" /* ActionType.RESERVE_SEAT */:
+            validateReserveSeatAction(state, action);
+            break;
         default:
             // Other actions don't need validation
             break;
@@ -145,8 +151,13 @@ function validateSitAction(state, action) {
     if (action.seat < 0 || action.seat >= state.maxPlayers) {
         throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_SEAT, `Seat ${action.seat} is invalid (max: ${state.maxPlayers - 1})`, { seat: action.seat, maxPlayers: state.maxPlayers });
     }
-    if (state.players[action.seat] !== null) {
-        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.SEAT_OCCUPIED, `Seat ${action.seat} is already occupied`, { seat: action.seat });
+    const existingPlayer = state.players[action.seat];
+    if (existingPlayer !== null) {
+        // Allow claiming the seat if it is RESERVED by THIS player
+        const isMyReservation = existingPlayer.status === "RESERVED" /* PlayerStatus.RESERVED */ && existingPlayer.id === action.playerId;
+        if (!isMyReservation) {
+            throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.SEAT_OCCUPIED, `Seat ${action.seat} is already occupied`, { seat: action.seat });
+        }
     }
     if (action.stack <= 0) {
         throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_STACK, `Stack must be positive, got ${action.stack}`, { stack: action.stack });
@@ -168,6 +179,20 @@ function validateTimeAction(state, action) {
         throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.NOT_YOUR_TURN, `Player ${action.playerId} cannot use time action when it's not their turn`, { playerId: action.playerId, actionTo: state.actionTo });
     }
 }
+function validateAddChipsAction(state, action) {
+    const result = (0, positioning_1.getPlayerById)(state, action.playerId);
+    if (!result) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.PLAYER_NOT_FOUND, `Player ${action.playerId} not found`, { playerId: action.playerId });
+    }
+}
+function validateReserveSeatAction(state, action) {
+    if (action.seat < 0 || action.seat >= state.maxPlayers) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_SEAT, `Seat ${action.seat} is invalid (max: ${state.maxPlayers - 1})`, { seat: action.seat, maxPlayers: state.maxPlayers });
+    }
+    if (state.players[action.seat] !== null) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.SEAT_OCCUPIED, `Seat ${action.seat} is already occupied`, { seat: action.seat });
+    }
+}
 /**
  * Get current highest bet this street
  */

package/dist/browser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser-compatible entry point for PokerEngine
+ *
+ * This file provides a browser-safe RNG using Web Crypto API
+ * and re-exports all engine functionality for use in web applications.
+ */
+import { PokerEngine } from "./engine/PokerEngine";
+import type { TableConfig } from "@pokertools/types";
+/**
+ * Browser-compatible RNG using Web Crypto API
+ * Falls back to Math.random() only in environments without crypto
+ */
+export declare function getBrowserRNG(): () => number;
+/**
+ * Create a PokerEngine instance with browser-compatible RNG
+ */
+export declare function createBrowserEngine(config: TableConfig): PokerEngine;
+export * from "./engine/PokerEngine";
+export * from "./actions/betting";
+export * from "./actions/dealing";
+export * from "./actions/management";
+export * from "./actions/showdownActions";
+export * from "./actions/special";
+export * from "./utils/viewMasking";
+export * from "./utils/serialization";
+export * from "./utils/cardUtils";
+export * from "./history/exporter";

package/dist/browser.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Browser-compatible entry point for PokerEngine
+ *
+ * This file provides a browser-safe RNG using Web Crypto API
+ * and re-exports all engine functionality for use in web applications.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBrowserRNG = getBrowserRNG;
+exports.createBrowserEngine = createBrowserEngine;
+const PokerEngine_1 = require("./engine/PokerEngine");
+/**
+ * Browser-compatible RNG using Web Crypto API
+ * Falls back to Math.random() only in environments without crypto
+ */
+function getBrowserRNG() {
+    // Check for Web Crypto API
+    if (typeof window !== "undefined" && window.crypto?.getRandomValues) {
+        return () => {
+            const buffer = new Uint32Array(1);
+            window.crypto.getRandomValues(buffer);
+            return buffer[0] / 0x100000000;
+        };
+    }
+    // Check for Node.js crypto (for SSR/testing)
+    if (typeof globalThis !== "undefined" && globalThis.crypto?.getRandomValues) {
+        return () => {
+            const buffer = new Uint32Array(1);
+            globalThis.crypto.getRandomValues(buffer);
+            return buffer[0] / 0x100000000;
+        };
+    }
+    // Fallback (warn in development)
+    if (process.env.NODE_ENV !== "production") {
+        console.warn("[PokerEngine Browser] Web Crypto API not available, using Math.random(). " +
+            "This is NOT cryptographically secure.");
+    }
+    return Math.random;
+}
+/**
+ * Create a PokerEngine instance with browser-compatible RNG
+ */
+function createBrowserEngine(config) {
+    return new PokerEngine_1.PokerEngine({
+        ...config,
+        randomProvider: getBrowserRNG(),
+    });
+}
+// Re-export everything from main engine
+__exportStar(require("./engine/PokerEngine"), exports);
+__exportStar(require("./actions/betting"), exports);
+__exportStar(require("./actions/dealing"), exports);
+__exportStar(require("./actions/management"), exports);
+__exportStar(require("./actions/showdownActions"), exports);
+__exportStar(require("./actions/special"), exports);
+__exportStar(require("./utils/viewMasking"), exports);
+__exportStar(require("./utils/serialization"), exports);
+__exportStar(require("./utils/cardUtils"), exports);
+__exportStar(require("./history/exporter"), exports);

package/dist/engine/PokerEngine.d.ts

@@ -1,6 +1,6 @@
 import { GameState, TableConfig, Action, PublicState } from "@pokertools/types";
 import { Snapshot } from "../utils/serialization";
-import { HandHistory, ExportOptions } from "../history/types";
+import { HandHistory, ExportOptions } from "@pokertools/types";
 /**
  * Event listener callback type
  */
@@ -35,6 +35,27 @@ export declare class PokerEngine {
      * If action.timestamp is not provided, the engine will automatically set it
      */
     act(action: Action): GameState;
+    /**
+     * Validate an action without executing it
+     * Useful for UI state (enabling/disabling buttons)
+     */
+    validate(action: Action): {
+        valid: true;
+    } | {
+        valid: false;
+        error: string;
+        code?: string;
+    };
+    /**
+     * Reconcile local state with server state
+     * Smoothly merges server updates into client engine
+     */
+    reconcile(serverState: PublicState | GameState): void;
+    /**
+     * Optimistically execute an action and return the provisional state
+     * Does not modify the engine's actual state
+     */
+    optimisticAct(action: Action): GameState;
     /**
      * Undo last action
      */
@@ -46,7 +67,7 @@ export declare class PokerEngine {
     /**
      * Get player view (masked)
      */
-    view(playerId?: string): PublicState;
+    view(playerId?: string, version?: number): PublicState;
     /**
      * Get snapshot for serialization
      */

package/dist/engine/PokerEngine.js

@@ -80,6 +80,57 @@ class PokerEngine {
         this.dispatch(actionWithTimestamp);
         return this.currentState;
     }
+    /**
+     * Validate an action without executing it
+     * Useful for UI state (enabling/disabling buttons)
+     */
+    validate(action) {
+        try {
+            // Dry-run the reducer
+            // We don't need to deep clone state because reducer is immutable
+            // and pure, and we discard the result.
+            (0, gameReducer_1.gameReducer)(this.currentState, action);
+            return { valid: true };
+        }
+        catch (err) {
+            const message = err?.message ?? "Invalid action";
+            const code = err?.code;
+            return {
+                valid: false,
+                error: message,
+                code,
+            };
+        }
+    }
+    /**
+     * Reconcile local state with server state
+     * Smoothly merges server updates into client engine
+     */
+    reconcile(serverState) {
+        // Hydrate PublicState into GameState if needed
+        const newState = {
+            ...serverState,
+            // Ensure deck exists (empty for client/public state)
+            deck: "deck" in serverState ? serverState.deck : [],
+            // Ensure players map correctly (PublicPlayer.hand is compatible with Player.hand)
+            players: serverState.players, // Type assertion needed due to deep readonly/mutable mismatch potential
+            // Ensure config carries isClient flag if set locally
+            config: {
+                ...serverState.config,
+                isClient: this.currentState.config.isClient,
+            },
+        };
+        this.currentState = newState;
+    }
+    /**
+     * Optimistically execute an action and return the provisional state
+     * Does not modify the engine's actual state
+     */
+    optimisticAct(action) {
+        const timestamp = action.timestamp ?? this.timeProvider();
+        const actionWithTimestamp = { ...action, timestamp };
+        return (0, gameReducer_1.gameReducer)(this.currentState, actionWithTimestamp);
+    }
     /**
      * Undo last action
      */
@@ -100,8 +151,8 @@ class PokerEngine {
     /**
      * Get player view (masked)
      */
-    view(playerId) {
-        return (0, viewMasking_1.createPublicView)(this.currentState, playerId ?? null);
+    view(playerId, version) {
+        return (0, viewMasking_1.createPublicView)(this.currentState, playerId ?? null, version ?? 0);
     }
     /**
      * Get snapshot for serialization
@@ -236,6 +287,7 @@ class PokerEngine {
             ante: initialBlinds?.ante ?? config.ante ?? 0,
             blindLevel: 0,
             timeBanks: new Map(),
+            timeBankActiveSeat: null,
             actionHistory: [],
             previousStates: [],
             timestamp: Date.now(),