poker-bitvaljs 1.2.0 → 1.5.2

package/README.md

@@ -6,11 +6,15 @@ High-performance poker hand evaluator optimized for browser environments, using
 
 ## Features
 
-- **Fast hand evaluation** using bitwise operations
-- **Range vs range equity calculations** with canonical key caching optimization
-- **Web Workers support** for parallel processing across multiple CPU cores (3-7x speedup)
-- **Monte Carlo simulation** for preflop and postflop scenarios
-- **Exhaustive enumeration** for flop/turn scenarios (2 or fewer cards to come)
+- **Fast hand evaluation** using four 13-bit suit lanes and plain 32-bit integers
+  (no BigInt in the hot path) — ~28–70× faster than the previous BigInt engine
+- **Exact range vs range equity** on the flop and turn via evaluate-once with
+  counting (byte-identical to brute force, no approximation)
+- **Exact, instant preflop** via an optional precomputed equity table
+  (`loadPreflopTable`) — replaces Monte Carlo entirely for preflop
+- **Monte Carlo** with confidence-interval early-stop for the remaining sampled
+  case (preflop with dead cards)
+- **Web Workers** for the Monte Carlo path
 - **Progress callbacks** with configurable update intervals
 - **Browser and Node.js compatible**
 
@@ -157,9 +161,9 @@ Simulates a single hand vs hand matchup.
 **Returns:**
 - `{ win, tie, lose }`: Results object
 
-### `compareRange(heroHands, villainHands, boardCards, deadCards, numberOfBoardCards, iterations, optimize, progressCallback, progressInterval, useWorkers)`
+### `compareRange(heroHands, villainHands, boardCards, deadCards, numberOfBoardCards, iterations, optimize, progressCallback, progressInterval, useWorkers, mcTargetPct)`
 
-Compares two ranges of hands with optional optimization and Web Workers parallelization.
+Compares two ranges of hands.
 
 **Parameters:**
 - `heroHands` (Array): Array of hero hand strings (e.g., `['AsAh', 'AsAd']`)
@@ -167,40 +171,57 @@ Compares two ranges of hands with optional optimization and Web Workers parallel
 - `boardCards` (Array): Board cards as strings (default: `[]`)
 - `deadCards` (Array): Dead cards as strings (default: `[]`)
 - `numberOfBoardCards` (Number): Total board cards (default: `5`)
-- `iterations` (Number): Number of simulations per matchup (default: `10000`)
-- `optimize` (Boolean): Use canonical key caching for performance (default: `true`). **Note:** Optimizations may result in a ±0.5% margin of error compared to unoptimized calculations.
+- `iterations` (Number): Monte Carlo samples per matchup (default: `10000`). Ignored on the flop/turn (exhaustive) and preflop-table paths, which are exact.
+- `optimize` (Boolean): Use the optimized path (default: `true`). On the flop/turn this is **exact** (byte-identical to `optimize: false`), just much faster.
 - `progressCallback` (Function): Optional callback `(current, total, message) => {}` (default: `null`)
 - `progressInterval` (Number): Update progress callback every N matchups (default: `100`)
-- `useWorkers` (Boolean): Use Web Workers for parallelization across CPU cores (default: `true`). Automatically falls back to sequential execution if workers are unavailable or workload is too small (< 4 matchups).
+- `useWorkers` (Boolean): Use Web Workers for the Monte Carlo path (default: `true`). The exact flop/turn path runs on the main thread.
+- `mcTargetPct` (Number): Monte Carlo early-stop target — stop sampling a matchup once its 95% confidence-interval half-width is within this many equity percentage points (default: `0.3`). Pass `0` to force the full `iterations`. Only affects the Monte Carlo (preflop) path.
 
 **Returns:**
 - `Promise<{ win, tie, lose }>`: Results object
 
-**Web Workers Notes:**
-- Web Workers provide 3-7x speedup on multi-core systems by parallelizing matchup evaluations
-- Workers are automatically disabled when:
-  - `useWorkers` is `false`
-  - Workers are not supported by the browser
-  - There are fewer than 4 matchups (overhead not worth it)
-- For local testing with `file://` protocol, use a local web server (see [Testing Locally](#testing-locally))
+### `loadPreflopTable(buffer)`
+
+Loads the precomputed exact preflop equity table and enables the preflop fast
+path in `compareRange` (empty board, no dead cards). Accepts an `ArrayBuffer`
+(browser) or Node `Buffer`. Generate the table with `npm run gen:preflop`.
+
+```javascript
+// Browser
+const buf = await (await fetch('./bench/preflop-table.bin')).arrayBuffer();
+bitval.loadPreflopTable(buf);
+
+// Node
+const fs = require('fs');
+bitval.loadPreflopTable(fs.readFileSync('bench/preflop-table.bin'));
+```
+
+Without a table loaded, preflop falls back to Monte Carlo — nothing else changes.
 
 ## Performance
 
-- **Optimized for browser environments** with efficient bitwise operations
-- **Web Workers parallelization** provides 3-7x speedup on multi-core systems
-- Canonical key caching reduces redundant evaluations (may introduce ±0.5% margin of error)
-- Exhaustive enumeration for flop/turn (2 or fewer cards to come)
-- Monte Carlo simulation for preflop and river scenarios
-- Adaptive progress reporting to minimize UI blocking
+- **No BigInt in the hot path** — cards are four 13-bit suit lanes evaluated with
+  plain 32-bit integer ops. ~28–70× faster than the previous BigInt engine.
+- **Flop/turn: exact and fast.** Each unique concrete hand is evaluated once per
+  runout; wide range-vs-range is resolved by counting. No ±0.5% approximation.
+- **Preflop: exact table lookup** (with `loadPreflopTable`) instead of Monte
+  Carlo — effectively instant.
+- **Monte Carlo** (only preflop with dead cards) uses confidence-interval
+  early-stop and Web Workers.
+
+Reproduce the benchmarks with `node bench/pre-vs-post.js` and `npm run bench`;
+correctness with `npm test` (and `npm run test:full` for the exhaustive proofs).
 
 **Test performance and benchmark online:** [https://darraghgeo.github.io/poker-bitvaljs/](https://darraghgeo.github.io/poker-bitvaljs/)
 
 ### Performance Tips
 
-- Enable Web Workers (default) for best performance on multi-core systems
-- Use canonical caching (`optimize: true`) for large range comparisons
-- Adjust `progressInterval` to balance UI responsiveness vs. performance
-- For very small workloads (< 4 matchups), workers are automatically disabled to avoid overhead
+- Call `loadPreflopTable` once at startup for exact, instant preflop equity.
+- Keep `optimize: true` (default) — on the flop/turn it is exact and much faster.
+- Lower `mcTargetPct` (or set `0`) for higher-precision Monte Carlo; raise it for
+  faster, looser preflop-with-dead-cards estimates.
+- Adjust `progressInterval` to balance UI responsiveness vs. performance.
 
 ## Testing Locally
 

package/bitval-worker.js

@@ -36,103 +36,98 @@ function deserializeMatchup(matchupData) {
  * Evaluates a single matchup in the worker context
  * Similar to _evaluateMatchup but without progress callbacks
  */
-async function evaluateMatchupInWorker(heroMask, villainMask, setup, evalCache, cacheInfo, bitval) {
+async function evaluateMatchupInWorker(heroMask, villainMask, setup, bitval) {
   let win = 0, tie = 0, lose = 0;
   const deadMask = heroMask | villainMask | setup.deadCardsMask;
-  const matchupDeadMask = heroMask | villainMask; // Only matchup-level dead cards (excludes setup.deadCardsMask)
-  
+
   // Initialize random number generator for Monte Carlo (not needed for exhaustive)
   if (!setup.isExhaustive) {
     bitval.xorShift = new XorShift32();
   }
   
-  // Prepare for exhaustive enumeration if applicable
-  let comboArray = null;
+  // BigInt-free (Number) hot loop, mirroring BitVal._evaluateMatchup. Cards are
+  // four 13-bit suit rank masks; bitval._eval7 does the evaluation with no BigInt.
   let iterations = setup.iterations;
+  const heroSuits = bitval._suitsFromBigMask(heroMask);
+  const villainSuits = bitval._suitsFromBigMask(villainMask);
+  const boardBaseSuits = bitval._suitsFromBigMask(setup.boardMask);
+  const hs0 = heroSuits[0], hs1 = heroSuits[1], hs2 = heroSuits[2], hs3 = heroSuits[3];
+  const vs0 = villainSuits[0], vs1 = villainSuits[1], vs2 = villainSuits[2], vs3 = villainSuits[3];
+  const bb0 = boardBaseSuits[0], bb1 = boardBaseSuits[1], bb2 = boardBaseSuits[2], bb3 = boardBaseSuits[3];
+
+  let comboSuits = null;              // flat Int32Array, 4 entries per combo
+  let pool = null, poolLen = 0;       // packed Int32Array of available cards
+  const nDeal = setup.numberOfCardsToDeal;
   if (setup.isExhaustive) {
-    // Use comboArray from setup if available, otherwise compute it
-    if (setup.comboArray && setup.comboArray.length > 0) {
-      comboArray = setup.comboArray;
-      iterations = comboArray.length;
-    } else {
-      // Compute comboArray if not provided
-      const availableMasks = bitval._getAvailableCardMasksByLookUp(deadMask);
-      comboArray = bitval._getCombinations(availableMasks, setup.numberOfCardsToDeal);
-      iterations = comboArray.length;
-    }
+    // Use comboArray from setup if available, otherwise compute it.
+    let comboArray = (setup.comboArray && setup.comboArray.length > 0)
+      ? setup.comboArray
+      : bitval._getCombinations(bitval._getAvailableCardMasksByLookUp(deadMask), nDeal);
+    comboSuits = bitval._buildComboSuits(comboArray);
+    iterations = comboSuits.length >> 2;
+  } else {
+    pool = bitval._availableSuitCards(deadMask);
+    poolLen = pool.length;
   }
-  
+
+  // Monte Carlo early-stop (mirrors BitVal._evaluateMatchup).
+  const mcTarget = setup.isExhaustive ? 0 : (setup.mcTarget > 0 ? setup.mcTarget / 100 : 0);
+  const reqIters = iterations;
+  let ran = iterations;
+
   // Main evaluation loop
   for (let i = 0; i < iterations; i++) {
-    // Generate board: use pre-computed combo for exhaustive, or deal randomly
-    const board = setup.isExhaustive 
-      ? setup.boardMask | comboArray[i]
-      : bitval.deal(setup.boardMask, deadMask, setup.numberOfCardsToDeal) | setup.boardMask;
-    
-    // Evaluate both hands
-    let hEval, hKick, vEval, vKick;
-    if (cacheInfo && evalCache) {
-      [hEval, hKick] = bitval._getCachedEvaluation(cacheInfo.heroKey, cacheInfo.heroHand, board, evalCache, matchupDeadMask);
-      [vEval, vKick] = bitval._getCachedEvaluation(cacheInfo.villainKey, cacheInfo.villainHand, board, evalCache, matchupDeadMask);
+    let d0, d1, d2, d3;
+    if (comboSuits) {
+      const b = i << 2;
+      d0 = bb0 | comboSuits[b]; d1 = bb1 | comboSuits[b + 1]; d2 = bb2 | comboSuits[b + 2]; d3 = bb3 | comboSuits[b + 3];
     } else {
-      [hEval, hKick] = bitval.evaluate(heroMask | board);
-      [vEval, vKick] = bitval.evaluate(villainMask | board);
+      d0 = bb0; d1 = bb1; d2 = bb2; d3 = bb3;
+      for (let kk = 0; kk < nDeal; kk++) {
+        const j = kk + bitval.xorShift.next(poolLen - kk);
+        const tmp = pool[kk]; pool[kk] = pool[j]; pool[j] = tmp;
+        const p = pool[kk], bit = p & 0xFFFF, suit = p >> 16;
+        if (suit === 0) d0 |= bit;
+        else if (suit === 1) d1 |= bit;
+        else if (suit === 2) d2 |= bit;
+        else d3 |= bit;
+      }
     }
-    
-    // Compare and accumulate results
-    if (hEval > vEval || (hEval === vEval && hKick > vKick)) {
-      win++;
-    } else if (vEval > hEval || (vEval === hEval && vKick > hKick)) {
-      lose++;
-    } else {
-      tie++;
+    const hE = bitval._eval7(hs0 | d0, hs1 | d1, hs2 | d2, hs3 | d3);
+    const vE = bitval._eval7(vs0 | d0, vs1 | d1, vs2 | d2, vs3 | d3);
+    if (hE > vE) win++;
+    else if (vE > hE) lose++;
+    else tie++;
+
+    if (mcTarget && (i & 4095) === 4095 && i >= 8191) {
+      const n = i + 1, p = (win + tie * 0.5) / n;
+      if (1.96 * Math.sqrt(p * (1 - p) / n) < mcTarget) { ran = n; break; }
     }
   }
-  
+
+  if (ran < reqIters && ran > 0) {
+    const s = reqIters / ran;
+    win = Math.round(win * s); tie = Math.round(tie * s); lose = Math.round(lose * s);
+  }
+
   return { matchupWin: win, matchupTie: tie, matchupLose: lose };
 }
 
-// Worker message handler
+// Reused BitVal instance (holds the lookup tables; cheap to keep around).
+const _bitval = new BitVal();
+
+// Worker message handler. Workers handle the Monte Carlo path only; the
+// exhaustive exact path runs on the main thread (see BitVal._compareRangeOptimized).
 self.onmessage = async function(e) {
   try {
     const { matchups, setupData, workerId } = e.data;
-    
-    // Deserialize setup
     const setup = deserializeSetup(setupData);
-    
-    // Create BitVal instance and cache for this worker (reused for all matchups)
-    const bitval = new BitVal();
-    const evalCache = new FastestAutoClearingCache(16000000);
-    
     const results = [];
-    
-    // Evaluate each matchup in the batch
+
     for (const matchupData of matchups) {
       const matchup = deserializeMatchup(matchupData);
-      
-      // Prepare cache info if available
-      const cacheInfo = matchup.heroKey ? {
-        heroKey: matchup.heroKey,
-        heroHand: matchup.heroHand,
-        villainKey: matchup.villainKey,
-        villainHand: matchup.villainHand
-      } : null;
-      
-      // Evaluate matchup
-      const result = await evaluateMatchupInWorker(
-        matchup.heroMask,
-        matchup.villainMask,
-        setup,
-        evalCache,
-        cacheInfo,
-        bitval
-      );
-      
-      results.push({
-        key: matchup.key,
-        validCount: matchup.validCount,
-        ...result
-      });
+      const result = await evaluateMatchupInWorker(matchup.heroMask, matchup.villainMask, setup, _bitval);
+      results.push({ key: matchup.key, validCount: matchup.validCount, ...result });
     }
     
     // Send results back to main thread

package/bitval.js

@@ -13,46 +13,6 @@ class XorShift32 {
   }
 }
 
-/**
- * Fastest auto-clearing cache with minimal overhead.
- * Uses bitwise counter check to avoid expensive modulo operations.
- */
-class FastestAutoClearingCache {
-  constructor(maxSize = 16000000) {
-    this.maxSize = maxSize;
-    this.clearThreshold = Math.floor(maxSize * 0.95); // Clear at 95% capacity
-    this.cache = new Map();
-    this.counter = 0;
-  }
-  
-  has(key) {
-    return this.cache.has(key); // No overhead on hot path
-  }
-  
-  get(key) {
-    return this.cache.get(key); // No overhead on hot path
-  }
-  
-  set(key, value) {
-    // Bitwise check is faster than modulo - check every ~1 million operations
-    // 0xFFFFF = 1,048,576 (2^20)
-    if ((++this.counter & 0xFFFFF) === 0) {
-      if (this.cache.size >= this.clearThreshold) {
-        this.cache.clear();
-      }
-    }
-    this.cache.set(key, value);
-  }
-  
-  clear() {
-    this.cache.clear();
-  }
-  
-  get size() {
-    return this.cache.size;
-  }
-}
-
 class BitVal {
   constructor() {
     // Suit constants
@@ -183,6 +143,43 @@ class BitVal {
       4503599627370496n: 67553994410557455n,
       1n: 67553994410557455n
     };
+
+    // ---- BigInt-free fast path (Number evaluator) lookups ----
+    // Rank index 0..12 = 2..A; suit index 0..3. A card set is four 13-bit rank
+    // masks (one per suit); evaluation and set-union run entirely on Numbers.
+    this._N_RANK = { '2': 0, '3': 1, '4': 2, '5': 3, '6': 4, '7': 5, '8': 6, '9': 7, 'T': 8, 'J': 9, 'Q': 10, 'K': 11, 'A': 12 };
+    this._N_SUIT = { s: 0, h: 1, d: 2, c: 3 };
+    this.CARD_SUITS = {};                 // 'As' -> { suit, bit }
+    this._MASK_TO_SUIT = new Map();       // single-card BigInt mask -> { suit, bit }
+    for (const card in this.CARD_MASKS) {
+      const sr = { suit: this._N_SUIT[card[1]], bit: 1 << this._N_RANK[card[0]] };
+      this.CARD_SUITS[card] = sr;
+      this._MASK_TO_SUIT.set(this.CARD_MASKS[card], sr);
+    }
+
+    // 13-bit rank-mask lookup tables for the fast evaluator. Each is 8192
+    // entries (~8-16 KB total), built once here, cache-resident at runtime.
+    // _POPC13[m]     = number of set bits (suit length / rank count).
+    // _STRAIGHT13[m] = top rank (4..12) of the best straight, 3 for the wheel,
+    //                  or -1 for none. Replaces the per-eval straight scan loop.
+    this._POPC13 = new Uint8Array(8192);
+    this._STRAIGHT13 = new Int8Array(8192);
+    for (let m = 0; m < 8192; m++) {
+      let c = 0, x = m;
+      while (x) { x &= x - 1; c++; }
+      this._POPC13[m] = c;
+      let run = 0, top = -1;
+      for (let r = 12; r >= 0; r--) {
+        if (m & (1 << r)) { if (++run >= 5) { top = r + 4; break; } } else run = 0;
+      }
+      if (top < 0 && (m & (1 << 12)) && (m & 0b1111) === 0b1111) top = 3; // wheel
+      this._STRAIGHT13[m] = top;
+    }
+
+    // Preflop exact-equity table (loaded on demand via loadPreflopTable). The 24
+    // suit permutations canonicalize a matchup for lookup (card index = rank*4+suit).
+    this._pfMap = null; this._pfWin = null; this._pfTie = null; this._pfTotal = 0;
+    this._S4 = (function () { const p = a => a.length <= 1 ? [a] : a.flatMap((x, i) => p(a.slice(0, i).concat(a.slice(i + 1))).map(r => [x, ...r])); return p([0, 1, 2, 3]); })();
   }
 
   // ============================================
@@ -241,6 +238,177 @@ class BitVal {
     return [this.stripBits(this.normalize(hand), 5), null];
   }
 
+  // ============================================
+  // FAST PATH - BigInt-free (Number) evaluator
+  // ============================================
+
+  /**
+   * Population count of a 13-bit rank mask.
+   * @private
+   */
+  _popc(m) { return this._POPC13[m]; }
+
+  /**
+   * Index (0..12) of the highest set bit of a non-zero 13-bit rank mask.
+   * @private
+   */
+  _high(m) { return 31 - Math.clz32(m); }
+
+  /**
+   * Top rank (4..12) of the best 5-card straight in a 13-bit rank mask, or -1.
+   * Handles the A-2-3-4-5 wheel (returns 3, i.e. a five-high straight).
+   * @private
+   */
+  _straightTop(m) { return this._STRAIGHT13[m]; }
+
+  /**
+   * Builds the four 13-bit suit rank masks for an array of card strings.
+   * @private
+   */
+  _suitsOfCards(cards) {
+    const suits = [0, 0, 0, 0];
+    for (let i = 0; i < cards.length; i++) {
+      const sr = this.CARD_SUITS[cards[i]];
+      suits[sr.suit] |= sr.bit;
+    }
+    return suits;
+  }
+
+  /**
+   * Decomposes a BigInt card-set mask into four 13-bit suit rank masks.
+   * Used once per matchup / combo, never in the innermost loop.
+   * @private
+   */
+  _suitsFromBigMask(bigMask) {
+    const suits = [0, 0, 0, 0];
+    for (const [mask, sr] of this._MASK_TO_SUIT) {
+      if ((bigMask & mask) === mask) suits[sr.suit] |= sr.bit;
+    }
+    return suits;
+  }
+
+  /**
+   * Available cards (as {suit, bit}) not present in the given BigInt dead mask.
+   * Built once per matchup for the Monte Carlo dealing loop.
+   * @private
+   */
+  _availableSuitCards(deadMask) {
+    const out = [];
+    for (const [mask, sr] of this._MASK_TO_SUIT) {
+      if ((deadMask & mask) === 0n) out.push((sr.suit << 16) | sr.bit);
+    }
+    return Int32Array.from(out); // packed: suit in bits 16-17, rank bit in low 13
+  }
+
+  /**
+   * Flattens a BigInt combo array into a single Int32Array of suit rank masks
+   * (4 entries per combo: s, h, d, c). One contiguous buffer instead of N small
+   * arrays — better cache locality, no per-combo GC. Cached on `setup`.
+   * @private
+   */
+  _buildComboSuits(comboArray) {
+    const out = new Int32Array(comboArray.length * 4);
+    for (let i = 0; i < comboArray.length; i++) {
+      const s = this._suitsFromBigMask(comboArray[i]);
+      const b = i * 4;
+      out[b] = s[0]; out[b + 1] = s[1]; out[b + 2] = s[2]; out[b + 3] = s[3];
+    }
+    return out;
+  }
+
+  /**
+   * Evaluates a 5-7 card hand given its four 13-bit suit rank masks and returns
+   * a single Number whose ordering is identical to `evaluate()` (score+kickers).
+   * Higher = stronger. No BigInt, no allocation.
+   * @private
+   */
+  _eval7(s, h, d, c) {
+    const all = s | h | d | c;
+    const POPC = this._POPC13, STR = this._STRAIGHT13;
+
+    // Flush suit (>=5 of one suit), reused for straight-flush and flush.
+    let fm = 0;
+    if (POPC[s] >= 5) fm = s;
+    else if (POPC[h] >= 5) fm = h;
+    else if (POPC[d] >= 5) fm = d;
+    else if (POPC[c] >= 5) fm = c;
+
+    // Straight flush
+    if (fm) {
+      const t = STR[fm];
+      if (t >= 0) return 8 * 1048576 + t * 65536;
+    }
+
+    // Per-rank suit-count masks (exact via boolean suit combinations)
+    const four = s & h & d & c;
+    const threePlus = (s & h & d) | (s & h & c) | (s & d & c) | (h & d & c);
+    const twoPlus = (s & h) | (s & d) | (s & c) | (h & d) | (h & c) | (d & c);
+    const trips = threePlus & ~four;   // exactly three
+    const pairs = twoPlus & ~threePlus; // exactly two
+
+    // Quads
+    if (four) {
+      const q = this._high(four);
+      const k = this._high(all & ~(1 << q));
+      return 7 * 1048576 + q * 65536 + k * 4096;
+    }
+
+    // Full house (a trip plus another trip or a pair)
+    if (trips) {
+      const t1 = this._high(trips);
+      const restTrips = trips & ~(1 << t1);
+      const p = restTrips ? this._high(restTrips) : (pairs ? this._high(pairs) : -1);
+      if (p >= 0) return 6 * 1048576 + t1 * 65536 + p * 4096;
+    }
+
+    // Flush
+    if (fm) {
+      let m = fm, v = 5 * 1048576, shift = 65536;
+      for (let n = 0; n < 5; n++) { const r = this._high(m); v += r * shift; m &= ~(1 << r); shift >>= 4; }
+      return v;
+    }
+
+    // Straight
+    {
+      const t = STR[all];
+      if (t >= 0) return 4 * 1048576 + t * 65536;
+    }
+
+    // Trips
+    if (trips) {
+      const t = this._high(trips);
+      let rest = all & ~(1 << t);
+      const k1 = this._high(rest); rest &= ~(1 << k1);
+      const k2 = this._high(rest);
+      return 3 * 1048576 + t * 65536 + k1 * 4096 + k2 * 256;
+    }
+
+    // Two pair
+    if (pairs && (pairs & (pairs - 1))) {
+      const p1 = this._high(pairs);
+      const p2 = this._high(pairs & ~(1 << p1));
+      const k = this._high(all & ~(1 << p1) & ~(1 << p2));
+      return 2 * 1048576 + p1 * 65536 + p2 * 4096 + k * 256;
+    }
+
+    // One pair
+    if (pairs) {
+      const p = this._high(pairs);
+      let rest = all & ~(1 << p);
+      const k1 = this._high(rest); rest &= ~(1 << k1);
+      const k2 = this._high(rest); rest &= ~(1 << k2);
+      const k3 = this._high(rest);
+      return 1 * 1048576 + p * 65536 + k1 * 4096 + k2 * 256 + k3 * 16;
+    }
+
+    // High card
+    {
+      let m = all, v = 0, shift = 65536;
+      for (let n = 0; n < 5; n++) { const r = this._high(m); v += r * shift; m &= ~(1 << r); shift >>= 4; }
+      return v;
+    }
+  }
+
   /**
    * Gets the human-readable hand strength from an evaluation mask.
    * @param {BigInt} handMask - Evaluation mask with score bits
@@ -297,9 +465,14 @@ class BitVal {
 
     const availableCards = 52 - new Set(allDeadCards).size;
     const exhaustiveCombinations = this.combinations(availableCards, numberOfCardsToDeal);
-    iterations = Math.min(iterations, exhaustiveCombinations);
 
-    const isExhaustive = iterations === exhaustiveCombinations && numberOfCardsToDeal > 0 && numberOfCardsToDeal <= 2;
+    // For <=2 cards to come the full runout space is tiny (<=1326), so always
+    // enumerate it exactly instead of Monte-Carloing a low iteration count.
+    // 0 cards to come (a complete board) is also exhaustive: exactly one runout.
+    // Exhaustive is exact and deterministic; the iteration count only matters
+    // for larger (>=3 cards to come) scenarios.
+    const isExhaustive = numberOfCardsToDeal >= 0 && numberOfCardsToDeal <= 2;
+    iterations = isExhaustive ? exhaustiveCombinations : Math.min(iterations, exhaustiveCombinations);
     let comboArray = null;
     if (isExhaustive) {
       const availableMasks = this._getAvailableCardMasksByLookUp(deadCards);
@@ -368,13 +541,99 @@ class BitVal {
    * @param {Function} progressCallback - Optional progress callback (current, total, message)
    * @param {Number} progressInterval - Update progress every N matchups (default: 100)
    * @param {Boolean} useWorkers - Use Web Workers for parallelization (default: true)
+   * @param {Number} mcTargetPct - Monte Carlo early-stop target: stop sampling a
+   *   matchup once its 95% CI half-width is within this many equity percentage
+   *   points (default: 0.3). Pass 0 to force the full `iterations`. Only affects
+   *   Monte Carlo (preflop); the exact flop/turn and preflop-table paths ignore it.
    * @returns {Promise<Object>} { win, tie, lose } - Results object
    */
-  async compareRange(heroHands, villainHands, boardCards = [], deadCards = [], numberOfBoardCards = 5, iterations = 10000, optimize = true, progressCallback = null, progressInterval = 100, useWorkers = true) {
+  async compareRange(heroHands, villainHands, boardCards = [], deadCards = [], numberOfBoardCards = 5, iterations = 10000, optimize = true, progressCallback = null, progressInterval = 100, useWorkers = true, mcTargetPct = 0.3) {
+    // Preflop exact fast path: if the preflop equity table is loaded and this is
+    // a full-board preflop query with no dead cards, look up every matchup's
+    // exact equity instead of Monte Carlo. Instant and exact.
+    if (this._pfMap && boardCards.length === 0 && deadCards.length === 0 && numberOfBoardCards === 5) {
+      const r = this._compareRangePreflopExact(heroHands, villainHands);
+      if (progressCallback) progressCallback(1, 1, 'Complete');
+      return r;
+    }
     const setup = this._compareRangeSetup(heroHands, villainHands, boardCards, deadCards, numberOfBoardCards, iterations, optimize);
+    // Monte Carlo early-stop target (95% CI half-width, in equity percentage
+    // points). Default on; pass 0 to force full `iterations`. Ignored by the
+    // exact (exhaustive) path. Only affects the remaining MC case (preflop with
+    // dead cards, or preflop with no table loaded).
+    setup.mcTarget = mcTargetPct;
     return optimize ? await this._compareRangeOptimized(setup, progressCallback, progressInterval, useWorkers) : await this._compareRangeUnoptimized(heroHands, villainHands, setup, progressCallback, progressInterval);
   }
 
+  /**
+   * Loads the exact preflop equity table (produced by bench/gen-preflop-table.js).
+   * Accepts an ArrayBuffer (browser fetch) or Node Buffer. Enables the preflop
+   * fast path in compareRange.
+   * @param {ArrayBuffer|Uint8Array|Buffer} buffer
+   * @returns {Number} number of canonical matchups loaded
+   */
+  loadPreflopTable(buffer) {
+    const ab = buffer instanceof ArrayBuffer ? buffer : buffer.buffer;
+    const off = buffer instanceof ArrayBuffer ? 0 : (buffer.byteOffset || 0);
+    const view = new DataView(ab, off, buffer.byteLength !== undefined ? buffer.byteLength : ab.byteLength);
+    if (view.getUint32(0, true) !== 0x50464551) throw new Error('invalid preflop table (bad magic)');
+    const count = view.getUint32(4, true);
+    this._pfTotal = view.getUint32(8, true);
+    this._pfWin = new Uint32Array(count);
+    this._pfTie = new Uint32Array(count);
+    this._pfMap = new Map();
+    for (let i = 0; i < count; i++) {
+      const o = 12 + i * 12;
+      this._pfMap.set(view.getUint32(o, true), i);
+      this._pfWin[i] = view.getUint32(o + 4, true);
+      this._pfTie[i] = view.getUint32(o + 8, true);
+    }
+    return count;
+  }
+
+  /** Card index (0..51) = rankIndex*4 + suitIndex, for a 2-char card string. @private */
+  _cardIndex(card) { return this._N_RANK[card[0]] * 4 + this._N_SUIT[card[1]]; }
+
+  /** Suit-isomorphic canonical key of a hero-vs-villain matchup (card indices). @private */
+  _preflopCanonKey(h1, h2, v1, v2) {
+    let best = Infinity;
+    const S4 = this._S4;
+    for (let pi = 0; pi < 24; pi++) {
+      const p = S4[pi];
+      const mh1 = (h1 & ~3) | p[h1 & 3], mh2 = (h2 & ~3) | p[h2 & 3];
+      const mv1 = (v1 & ~3) | p[v1 & 3], mv2 = (v2 & ~3) | p[v2 & 3];
+      const a = mh1 < mh2 ? mh1 : mh2, b = mh1 < mh2 ? mh2 : mh1;
+      const c = mv1 < mv2 ? mv1 : mv2, d = mv1 < mv2 ? mv2 : mv1;
+      const key = ((a * 52 + b) * 52 + c) * 52 + d;
+      if (key < best) best = key;
+    }
+    return best;
+  }
+
+  /**
+   * Exact preflop range-vs-range via the loaded table: sum each valid (hero,
+   * villain) matchup's exact win/tie/lose over all C(48,5) boards.
+   * @private
+   */
+  _compareRangePreflopExact(heroHands, villainHands) {
+    const total = this._pfTotal;
+    const heroC = [], villC = [];
+    for (const h of heroHands) heroC.push(this._cardIndex(h.slice(0, 2)), this._cardIndex(h.slice(2, 4)));
+    for (const v of villainHands) villC.push(this._cardIndex(v.slice(0, 2)), this._cardIndex(v.slice(2, 4)));
+    let win = 0, tie = 0, lose = 0;
+    for (let hi = 0; hi < heroC.length; hi += 2) {
+      const h1 = heroC[hi], h2 = heroC[hi + 1];
+      for (let vi = 0; vi < villC.length; vi += 2) {
+        const v1 = villC[vi], v2 = villC[vi + 1];
+        if (h1 === v1 || h1 === v2 || h2 === v1 || h2 === v2) continue; // conflicting hole cards
+        const idx = this._pfMap.get(this._preflopCanonKey(h1, h2, v1, v2));
+        const w = this._pfWin[idx], t = this._pfTie[idx];
+        win += w; tie += t; lose += total - w - t;
+      }
+    }
+    return { win, tie, lose };
+  }
+
   // ============================================
   // PUBLIC API - Utility Methods
   // ============================================
@@ -686,19 +945,24 @@ class BitVal {
     const boardMask = this.getBitMasked(boardCards);
     const deadCardsMask = this.getBitMasked([...boardCards, ...deadCards]);
     
-    // Calculate cards to deal and determine if exhaustive enumeration is possible
+    // Calculate cards to deal and determine if exhaustive enumeration is possible.
+    // 0 cards to come (a complete board) is exhaustive too: exactly one runout.
     const numberOfCardsToDeal = numberOfBoardCards - boardCards.length;
-    const canBeExhaustive = numberOfCardsToDeal > 0 && numberOfCardsToDeal <= 2;
+    const canBeExhaustive = numberOfCardsToDeal >= 0 && numberOfCardsToDeal <= 2;
     
     // Calculate available cards using bitmask (more efficient than Set)
     const availableCards = 52 - this.countBits(deadCardsMask);
     
     // Determine if we should use exhaustive enumeration
-    const exhaustiveCombinations = canBeExhaustive 
-      ? this.combinations(availableCards, numberOfCardsToDeal) 
+    const exhaustiveCombinations = canBeExhaustive
+      ? this.combinations(availableCards, numberOfCardsToDeal)
       : Infinity;
-    iterations = Math.min(iterations, exhaustiveCombinations);
-    const isExhaustive = canBeExhaustive && iterations === exhaustiveCombinations && exhaustiveCombinations < Infinity;
+    // For <=2 cards to come the full runout space is tiny (<=1326), so always
+    // enumerate it exactly instead of Monte-Carloing a lower requested count.
+    // Exhaustive is exact and deterministic; the requested iteration count only
+    // matters for larger (>=3 cards to come, e.g. preflop) scenarios.
+    const isExhaustive = canBeExhaustive && exhaustiveCombinations < Infinity;
+    iterations = isExhaustive ? exhaustiveCombinations : Math.min(iterations, exhaustiveCombinations);
     
     // Generate combo array only if exhaustive
     const comboArray = isExhaustive 
@@ -735,7 +999,8 @@ class BitVal {
       numberOfBoardCards: setup.numberOfBoardCards,
       iterations: setup.iterations,
       isExhaustive: setup.isExhaustive,
-      numberOfCardsToDeal: setup.numberOfCardsToDeal
+      numberOfCardsToDeal: setup.numberOfCardsToDeal,
+      mcTarget: setup.mcTarget
       // Note: hCanon, vCanon, validMatchups, validCounts are not needed in workers
       // as matchups are pre-serialized and sent separately
     };
@@ -783,55 +1048,84 @@ class BitVal {
    * Optimized for browser performance with adaptive yielding and inlined hot loop.
    * @private
    */
-  async _evaluateMatchup(heroMask, villainMask, setup, evalCache = null, progressCallback = null, matchupIndex = 0, totalMatchups = 1) {
+  async _evaluateMatchup(heroMask, villainMask, setup, progressCallback = null, matchupIndex = 0, totalMatchups = 1) {
     let win = 0, tie = 0, lose = 0;
     const deadMask = heroMask | villainMask | setup.deadCardsMask;
-    const matchupDeadMask = heroMask | villainMask; // Only matchup-level dead cards (excludes setup.deadCardsMask)
-    
+
     // Initialize random number generator for Monte Carlo (not needed for exhaustive)
     if (!setup.isExhaustive) {
       this.xorShift = new XorShift32();
     }
     
-    // Prepare for exhaustive enumeration if applicable
-    let comboArray = null;
+    // Prepare BigInt-free (Number) representations for the hot loop. The old
+    // path built a BigInt board and called the BigInt evaluate() twice per
+    // iteration; here cards are four 13-bit suit rank masks and _eval7 does the
+    // work with no BigInt and no allocation. The board suit-masks and the combo
+    // suit-masks are constant across matchups, so they're computed once and
+    // cached on `setup`.
     let iterations = setup.iterations;
+    const heroSuits = this._suitsFromBigMask(heroMask);
+    const villainSuits = this._suitsFromBigMask(villainMask);
+    const boardBaseSuits = setup._boardSuits || (setup._boardSuits = this._suitsFromBigMask(setup.boardMask));
+    const hs0 = heroSuits[0], hs1 = heroSuits[1], hs2 = heroSuits[2], hs3 = heroSuits[3];
+    const vs0 = villainSuits[0], vs1 = villainSuits[1], vs2 = villainSuits[2], vs3 = villainSuits[3];
+    const bb0 = boardBaseSuits[0], bb1 = boardBaseSuits[1], bb2 = boardBaseSuits[2], bb3 = boardBaseSuits[3];
+
+    let comboSuits = null;              // flat Int32Array, 4 entries per combo
+    let pool = null, poolLen = 0;       // packed Int32Array of available cards
+    const nDeal = setup.numberOfCardsToDeal;
     if (setup.isExhaustive) {
-      // Reuse pre-computed comboArray from setup (already computed in _compareRangeSetup)
-      comboArray = setup.comboArray;
-      iterations = comboArray.length;
+      comboSuits = setup._comboSuits || (setup._comboSuits = this._buildComboSuits(setup.comboArray));
+      iterations = comboSuits.length >> 2;
+    } else {
+      pool = this._availableSuitCards(deadMask);
+      poolLen = pool.length;
     }
-    
-    // Main evaluation loop - optimized with inlined functions and adaptive yielding
-    const yieldInterval = 5000; // Increased from 1000 - reduces async overhead while maintaining responsiveness
+
+    // Main evaluation loop - adaptive yielding for UI responsiveness
+    const yieldInterval = 5000;
     let lastProgressTime = 0;
     const progressUpdateInterval = 100; // Update progress at most every 100ms
-    
+
+    // Monte Carlo early-stop: stop once this matchup's 95% CI half-width is
+    // within the target (lopsided matchups converge fast). Never exceeds the
+    // requested iterations; disabled for exact enumeration and when mcTarget<=0.
+    const mcTarget = setup.isExhaustive ? 0 : (setup.mcTarget > 0 ? setup.mcTarget / 100 : 0);
+    const reqIters = iterations;
+    let ran = iterations;
+
     for (let i = 0; i < iterations; i++) {
-      // Generate board: use pre-computed combo for exhaustive, or deal randomly
-      const board = setup.isExhaustive 
-        ? setup.boardMask | comboArray[i]
-        : this.deal(setup.boardMask, deadMask, setup.numberOfCardsToDeal) | setup.boardMask;
-      
-      // Evaluate both hands - inlined for performance (no function call overhead)
-      let hEval, hKick, vEval, vKick;
-      if (evalCache) {
-        [hEval, hKick] = this._getCachedEvaluation(evalCache.heroKey, evalCache.heroHand, board, evalCache.cache, matchupDeadMask);
-        [vEval, vKick] = this._getCachedEvaluation(evalCache.villainKey, evalCache.villainHand, board, evalCache.cache, matchupDeadMask);
+      // Build the runout as suit rank-masks: precomputed combo (exhaustive) or
+      // a Fisher-Yates draw from the available pool (Monte Carlo).
+      let d0, d1, d2, d3;
+      if (comboSuits) {
+        const b = i << 2;
+        d0 = bb0 | comboSuits[b]; d1 = bb1 | comboSuits[b + 1]; d2 = bb2 | comboSuits[b + 2]; d3 = bb3 | comboSuits[b + 3];
       } else {
-        [hEval, hKick] = this.evaluate(heroMask | board);
-        [vEval, vKick] = this.evaluate(villainMask | board);
+        d0 = bb0; d1 = bb1; d2 = bb2; d3 = bb3;
+        for (let k = 0; k < nDeal; k++) {
+          const j = k + this.xorShift.next(poolLen - k);
+          const tmp = pool[k]; pool[k] = pool[j]; pool[j] = tmp;
+          const p = pool[k], bit = p & 0xFFFF, suit = p >> 16;
+          if (suit === 0) d0 |= bit;
+          else if (suit === 1) d1 |= bit;
+          else if (suit === 2) d2 |= bit;
+          else d3 |= bit;
+        }
       }
-      
-      // Compare and accumulate results - inlined for performance
-      if (hEval > vEval || (hEval === vEval && hKick > vKick)) {
-        win++;
-      } else if (vEval > hEval || (vEval === hEval && vKick > hKick)) {
-        lose++;
-      } else {
-        tie++;
+
+      const hE = this._eval7(hs0 | d0, hs1 | d1, hs2 | d2, hs3 | d3);
+      const vE = this._eval7(vs0 | d0, vs1 | d1, vs2 | d2, vs3 | d3);
+      if (hE > vE) win++;
+      else if (vE > hE) lose++;
+      else tie++;
+
+      // Monte Carlo early-stop check (every 4096 draws, past a warm-up).
+      if (mcTarget && (i & 4095) === 4095 && i >= 8191) {
+        const n = i + 1, p = (win + tie * 0.5) / n;
+        if (1.96 * Math.sqrt(p * (1 - p) / n) < mcTarget) { ran = n; break; }
       }
-      
+
       // Adaptive yielding: less frequent but still maintains UI responsiveness
       if (progressCallback && i > 0 && i % yieldInterval === 0) {
         const now = Date.now();
@@ -871,7 +1165,15 @@ class BitVal {
         }
       }
     }
-    
+
+    // If early-stopped, scale counts back to the requested iteration count so
+    // the aggregate (which sums raw counts across matchups) weights every
+    // matchup equally regardless of how early it converged.
+    if (ran < reqIters && ran > 0) {
+      const s = reqIters / ran;
+      win = Math.round(win * s); tie = Math.round(tie * s); lose = Math.round(lose * s);
+    }
+
     return { matchupWin: win, matchupTie: tie, matchupLose: lose };
   }
 
@@ -887,7 +1189,7 @@ class BitVal {
     
     for (let i = 0; i < total; i++) {
       const { heroMask, villainMask } = setup.validMatchups[i];
-      const { matchupWin, matchupTie, matchupLose } = await this._evaluateMatchup(heroMask, villainMask, setup, null, progressCallback, i, total);
+      const { matchupWin, matchupTie, matchupLose } = await this._evaluateMatchup(heroMask, villainMask, setup, progressCallback, i, total);
       win += matchupWin; tie += matchupTie; lose += matchupLose;
       
       if (progressCallback && i % progressInterval === 0) {
@@ -932,7 +1234,6 @@ class BitVal {
    */
   async _compareRangeOptimizedSequential(setup, progressCallback = null, progressInterval = 100) {
     let win = 0, tie = 0, lose = 0;
-    const evalCache = new FastestAutoClearingCache(16000000);
     let lastProgressTime = 0;
     const progressUpdateInterval = 100; // Update progress at most every 100ms
     
@@ -941,101 +1242,129 @@ class BitVal {
       ? this._getBoardSuitCounts(setup.boardCards) 
       : null;
     
-    // Group validMatchups by canonical key pair
-    // This ensures we only process matchups that actually exist, avoiding Cartesian product issues
-    const matchupGroups = new Map();
-    for (const matchup of setup.validMatchups) {
-      const mHKey = this._getCanonicalKey(
-        matchup.heroHand, 
-        setup.boardCards, 
-        setup.numberOfBoardCards, 
-        boardSuitCounts
-      );
-      const mVKey = this._getCanonicalKey(
-        matchup.villainHand, 
-        setup.boardCards, 
-        setup.numberOfBoardCards, 
-        boardSuitCounts
-      );
-      const key = `${mHKey}:${mVKey}`;
-      
-      if (!matchupGroups.has(key)) {
-        matchupGroups.set(key, {
-          heroKey: mHKey,
-          villainKey: mVKey,
-          representative: matchup,
-          count: 0
-        });
+    // Monte Carlo (>=3 cards to come): canonical grouping + independent
+    // per-matchup sampling (each matchup deals its own boards, so runouts can't
+    // be shared). Grouping only pays off here, where a matchup is expensive.
+    if (!setup.isExhaustive) {
+      const matchupGroups = new Map();
+      for (const matchup of setup.validMatchups) {
+        const mHKey = this._getCanonicalKey(matchup.heroHand, setup.boardCards, setup.numberOfBoardCards, boardSuitCounts);
+        const mVKey = this._getCanonicalKey(matchup.villainHand, setup.boardCards, setup.numberOfBoardCards, boardSuitCounts);
+        const key = `${mHKey}:${mVKey}`;
+        let g = matchupGroups.get(key);
+        if (!g) { g = { heroKey: mHKey, villainKey: mVKey, representative: matchup, count: 0 }; matchupGroups.set(key, g); }
+        g.count++;
       }
-      matchupGroups.get(key).count++;
-    }
-    
-    // Calculate accurate total matchups (number of unique canonical key pairs)
-    const totalMatchups = matchupGroups.size;
-    
-    let matchupIndex = 0;
-    // Iterate over actual matchup groups (not Cartesian product)
-    for (const [key, group] of matchupGroups) {
-      const validCount = group.count;
-      const validPair = group.representative;
-      
-      const cache = { 
-        heroKey: group.heroKey, 
-        heroHand: validPair.heroHand, 
-        villainKey: group.villainKey, 
-        villainHand: validPair.villainHand, 
-        cache: evalCache 
-      };
-      
-      const { matchupWin, matchupTie, matchupLose } = await this._evaluateMatchup(
-        validPair.heroMask, 
-        validPair.villainMask, 
-        setup, 
-        cache, 
-        progressCallback, 
-        matchupIndex, 
-        totalMatchups
-      );
-      
-      win += matchupWin * validCount;
-      tie += matchupTie * validCount;
-      lose += matchupLose * validCount;
-      
-      matchupIndex++;
-      if (progressCallback && matchupIndex % progressInterval === 0) {
-        const now = Date.now();
-        const shouldUpdateProgress = now - lastProgressTime >= progressUpdateInterval;
-        
-        // Use modern browser APIs for better scheduling when available
-        if (typeof scheduler !== 'undefined' && scheduler.postTask) {
-          await scheduler.postTask(() => {
-            if (shouldUpdateProgress) {
-              progressCallback(matchupIndex, totalMatchups, `Evaluating ${matchupIndex}`);
-              lastProgressTime = now;
-            }
-          }, { priority: 'user-blocking' });
-        } else if (typeof requestIdleCallback !== 'undefined') {
-          await new Promise(resolve => {
-            requestIdleCallback(() => {
-              if (shouldUpdateProgress) {
-                progressCallback(matchupIndex, totalMatchups, `Evaluating ${matchupIndex}`);
-                lastProgressTime = now;
-              }
-              resolve();
-            }, { timeout: 1 });
-          });
-        } else {
-          // Fallback to setTimeout
-          await new Promise(resolve => setTimeout(resolve, 0));
-          if (shouldUpdateProgress) {
-            progressCallback(matchupIndex, totalMatchups, `Evaluating ${matchupIndex}`);
-            lastProgressTime = now;
+      const totalMatchups = matchupGroups.size;
+      let matchupIndex = 0;
+      for (const [key, group] of matchupGroups) {
+        const validCount = group.count;
+        const validPair = group.representative;
+        const { matchupWin, matchupTie, matchupLose } = await this._evaluateMatchup(
+          validPair.heroMask, validPair.villainMask, setup, progressCallback, matchupIndex, totalMatchups
+        );
+        win += matchupWin * validCount;
+        tie += matchupTie * validCount;
+        lose += matchupLose * validCount;
+        matchupIndex++;
+        if (progressCallback && matchupIndex % progressInterval === 0) {
+          const now = Date.now();
+          const shouldUpdateProgress = now - lastProgressTime >= progressUpdateInterval;
+          if (typeof scheduler !== 'undefined' && scheduler.postTask) {
+            await scheduler.postTask(() => { if (shouldUpdateProgress) { progressCallback(matchupIndex, totalMatchups, `Evaluating ${matchupIndex}`); lastProgressTime = now; } }, { priority: 'user-blocking' });
+          } else if (typeof requestIdleCallback !== 'undefined') {
+            await new Promise(resolve => { requestIdleCallback(() => { if (shouldUpdateProgress) { progressCallback(matchupIndex, totalMatchups, `Evaluating ${matchupIndex}`); lastProgressTime = now; } resolve(); }, { timeout: 1 }); });
+          } else {
+            await new Promise(resolve => setTimeout(resolve, 0));
+            if (shouldUpdateProgress) { progressCallback(matchupIndex, totalMatchups, `Evaluating ${matchupIndex}`); lastProgressTime = now; }
           }
         }
       }
+      if (progressCallback) progressCallback(matchupIndex, matchupIndex, 'Complete');
+      return { win, tie, lose };
+    }
+
+    // Exhaustive: EXACT evaluate-once. Build the shared work structure and run
+    // the kernel over all runouts. The Web Worker path (_compareRangeOptimized)
+    // runs the SAME kernel over runout slices, so workers and sequential agree
+    // byte-for-byte.
+    const work = this._buildExhaustiveWork(setup);
+    const comboSuits = setup._comboSuits || (setup._comboSuits = this._buildComboSuits(setup.comboArray));
+    const nRun = comboSuits.length >> 2;
+    const r = this._runExhaustive(work, comboSuits, 0, nRun);
+    if (progressCallback) progressCallback(nRun, nRun, 'Complete');
+    return r;
+  }
+
+  /**
+   * Builds the reusable per-run work for the exact exhaustive kernel: unique
+   * concrete hero/villain suit masks, the valid-pair list, and (for large
+   * fields) the card-conflict CSR. Everything is transferable typed arrays so
+   * it can be serialized to workers unchanged.
+   * @private
+   */
+  _buildExhaustiveWork(setup) {
+    const heroIdx = new Map(), villIdx = new Map();
+    const heroSuit = [], villSuit = [], pairH = [], pairV = [];
+    for (const m of setup.validMatchups) {
+      let hi = heroIdx.get(m.heroMask);
+      if (hi === undefined) { hi = heroSuit.length >> 2; heroIdx.set(m.heroMask, hi); const s = this._suitsFromBigMask(m.heroMask); heroSuit.push(s[0], s[1], s[2], s[3]); }
+      let vi = villIdx.get(m.villainMask);
+      if (vi === undefined) { vi = villSuit.length >> 2; villIdx.set(m.villainMask, vi); const s = this._suitsFromBigMask(m.villainMask); villSuit.push(s[0], s[1], s[2], s[3]); }
+      pairH.push(hi); pairV.push(vi);
+    }
+    const H = heroSuit.length >> 2, V = villSuit.length >> 2, P = pairH.length;
+    const hSuit = Int32Array.from(heroSuit), vSuit = Int32Array.from(villSuit);
+    const pHa = Int32Array.from(pairH), pVa = Int32Array.from(pairV);
+    const bb = setup._boardSuits || (setup._boardSuits = this._suitsFromBigMask(setup.boardMask));
+
+    const useCount = H >= 16 && V >= 16;
+    let confList = null, confOff = null;
+    if (useCount) {
+      const confListArr = [];
+      confOff = new Int32Array(H + 1);
+      for (let h = 0; h < H; h++) {
+        const q = h << 2, a0 = hSuit[q], a1 = hSuit[q + 1], a2 = hSuit[q + 2], a3 = hSuit[q + 3];
+        for (let v = 0; v < V; v++) { const r = v << 2; if ((a0 & vSuit[r]) | (a1 & vSuit[r + 1]) | (a2 & vSuit[r + 2]) | (a3 & vSuit[r + 3])) confListArr.push(v); }
+        confOff[h + 1] = confListArr.length;
+      }
+      confList = Int32Array.from(confListArr);
+    }
+    return { hSuit, vSuit, pHa, pVa, confList, confOff, useCount, bb0: bb[0], bb1: bb[1], bb2: bb[2], bb3: bb[3], H, V, P };
+  }
+
+  /**
+   * Exact exhaustive kernel over runouts [runStart, runEnd). Evaluates each
+   * unique concrete hand once per runout, then resolves matchups by direct
+   * comparison (small fields) or sorted-villain binary-search counting with
+   * card-conflict correction (large fields). Byte-identical to unoptimized.
+   * @private
+   */
+  _runExhaustive(work, comboSuits, runStart, runEnd) {
+    const { hSuit, vSuit, pHa, pVa, confList, confOff, useCount, bb0, bb1, bb2, bb3, H, V, P } = work;
+    const heroVals = new Int32Array(H), villVals = new Int32Array(V);
+    const sortedV = useCount ? new Int32Array(V) : null;
+    let win = 0, tie = 0, lose = 0;
+    for (let i = runStart; i < runEnd; i++) {
+      const b = i << 2;
+      const d0 = bb0 | comboSuits[b], d1 = bb1 | comboSuits[b + 1], d2 = bb2 | comboSuits[b + 2], d3 = bb3 | comboSuits[b + 3];
+      for (let h = 0; h < H; h++) { const q = h << 2; heroVals[h] = this._eval7(hSuit[q] | d0, hSuit[q + 1] | d1, hSuit[q + 2] | d2, hSuit[q + 3] | d3); }
+      for (let v = 0; v < V; v++) { const q = v << 2; villVals[v] = this._eval7(vSuit[q] | d0, vSuit[q + 1] | d1, vSuit[q + 2] | d2, vSuit[q + 3] | d3); }
+      if (useCount) {
+        sortedV.set(villVals);
+        sortedV.sort();
+        for (let h = 0; h < H; h++) {
+          const x = heroVals[h];
+          let lo = 0, hb = V; while (lo < hb) { const mid = (lo + hb) >> 1; if (sortedV[mid] < x) lo = mid + 1; else hb = mid; }
+          let up = lo; hb = V; while (up < hb) { const mid = (up + hb) >> 1; if (sortedV[mid] <= x) up = mid + 1; else hb = mid; }
+          let wH = lo, tH = up - lo, lH = V - up;
+          for (let ci = confOff[h], end = confOff[h + 1]; ci < end; ci++) { const cv = villVals[confList[ci]]; if (cv < x) wH--; else if (cv === x) tH--; else lH--; }
+          win += wH; tie += tH; lose += lH;
+        }
+      } else {
+        for (let p = 0; p < P; p++) { const hv = heroVals[pHa[p]], vv = villVals[pVa[p]]; if (hv > vv) win++; else if (vv > hv) lose++; else tie++; }
+      }
     }
-    
-    if (progressCallback) progressCallback(matchupIndex, matchupIndex, 'Complete');
     return { win, tie, lose };
   }
 
@@ -1045,9 +1374,21 @@ class BitVal {
    * @private
    */
   async _compareRangeOptimized(setup, progressCallback = null, progressInterval = 100, useWorkers = true) {
+    // Exhaustive (flop/turn): run the EXACT kernel on the main thread. It's now
+    // fast enough (~tens of ms) that this is the right choice, and it makes the
+    // worker and non-worker paths agree byte-for-byte (fixes the exact-vs-
+    // approximate split that per-canonical-group workers had). Splitting runouts
+    // across workers was a net loss here (structured-cloning the pair/conflict
+    // work to every worker dwarfs the compute) — true off-thread parallelism of
+    // this path needs SharedArrayBuffer (COOP/COEP), left as a follow-up. The
+    // reusable _runExhaustive / _buildExhaustiveWork are kept for that.
+    if (setup.isExhaustive) {
+      return await this._compareRangeOptimizedSequential(setup, progressCallback, progressInterval);
+    }
+
     // Pre-calculate board suit counts once (constant for all matchups)
-    const boardSuitCounts = setup.boardCards.length > 0 
-      ? this._getBoardSuitCounts(setup.boardCards) 
+    const boardSuitCounts = setup.boardCards.length > 0
+      ? this._getBoardSuitCounts(setup.boardCards)
       : null;
     
     // Group validMatchups by canonical key pair
@@ -1115,15 +1456,17 @@ class BitVal {
     for (let i = 0; i < matchupsToEvaluate.length; i += batchSize) {
       batches.push(matchupsToEvaluate.slice(i, i + batchSize));
     }
-    
+
     // Serialize setup for workers
     const serializedSetup = this._serializeSetup(setup);
-    
-    // Create workers and distribute work
-    const workers = [];
+
+    // Acquire persistent workers from the pool (created once, reused across calls).
+    // Previously a fresh Worker was spawned and terminated per compareRange call,
+    // paying thread-spawn + importScripts('./bitval.js') parse on every query.
+    const workers = this._acquireWorkers(batches.length);
     const promises = [];
     let completedMatchups = 0;
-    
+
     // Progress tracking
     let lastProgressTime = 0;
     const progressUpdateInterval = 100;
@@ -1134,44 +1477,48 @@ class BitVal {
         lastProgressTime = now;
       }
     }, progressUpdateInterval) : null;
-    
+
     for (let i = 0; i < batches.length; i++) {
-      const worker = new Worker('./bitval-worker.js');
-      workers.push(worker);
-      
+      const worker = workers[i];
+
       const promise = new Promise((resolve, reject) => {
+        // One-shot handlers per dispatch; cleared on settle so the pooled worker
+        // is clean for the next call. (Assumes compareRange calls don't overlap.)
+        const cleanup = () => { worker.onmessage = null; worker.onerror = null; };
         worker.onmessage = (e) => {
+          cleanup();
           if (e.data.success) {
             completedMatchups += e.data.results.length;
             resolve(e.data.results);
           } else {
             reject(new Error(e.data.error || 'Worker error'));
           }
-          worker.terminate();
         };
         worker.onerror = (error) => {
+          cleanup();
+          // A crashed worker can't be reused - drop it from the pool.
+          this._discardWorker(worker);
           reject(error);
-          worker.terminate();
         };
-        
+
         // Serialize matchups for this batch
         const serializedBatch = batches[i].map(m => this._serializeMatchup(m));
-        
+
         worker.postMessage({
           matchups: serializedBatch,
           setupData: serializedSetup,
           workerId: i
         });
       });
-      
+
       promises.push(promise);
     }
-    
+
     // Wait for all workers and aggregate results
     let win = 0, tie = 0, lose = 0;
     try {
       const allResults = await Promise.all(promises);
-      
+
       for (const batchResults of allResults) {
         for (const result of batchResults) {
           win += result.matchupWin * result.validCount;
@@ -1184,58 +1531,55 @@ class BitVal {
       if (progressIntervalId) {
         clearInterval(progressIntervalId);
       }
-      
-      // Ensure all workers are terminated
-      workers.forEach(worker => {
-        try {
-          worker.terminate();
-        } catch (e) {
-          // Ignore termination errors
-        }
-      });
-      
+
+      // Workers are NOT terminated - they stay in the pool for the next call.
+      // Callers can free them explicitly with terminateWorkerPool().
+
       // Final progress update
       if (progressCallback) {
         progressCallback(totalMatchups, totalMatchups, 'Complete');
       }
     }
-    
+
     return { win, tie, lose };
   }
 
   /**
-   * Generates a numeric hash key from canonical key and board for faster cache lookups.
+   * Returns `count` persistent workers, lazily growing the pool as needed.
+   * Reused across compareRange calls so thread-spawn + importScripts parse is
+   * paid once rather than per query.
    * @private
    */
-  _getCacheKeyHash(canonicalKey, board, matchupDeadMask = 0n) {
-    // Hash the canonical key string
-    let hash = 0;
-    for (let i = 0; i < canonicalKey.length; i++) {
-      hash = ((hash << 5) - hash) + canonicalKey.charCodeAt(i);
-      hash = hash & hash; // Convert to 32-bit integer
-    }
-    // Combine with board bits (use lower 32 bits of BigInt for fast XOR)
-    const boardBits = Number(board & 0xFFFFFFFFn);
-    hash = hash ^ boardBits;
-    
-    // Include matchup dead mask to prevent cross-matchup cache collisions
-    // This ensures different matchups (with different dead cards) don't share cache entries
-    const deadBits = Number(matchupDeadMask & 0xFFFFFFFFn);
-    return hash ^ deadBits;
+  _acquireWorkers(count) {
+    if (!this._workerPool) this._workerPool = [];
+    while (this._workerPool.length < count) {
+      this._workerPool.push(new Worker('./bitval-worker.js'));
+    }
+    return this._workerPool.slice(0, count);
   }
 
   /**
-   * Gets cached evaluation or evaluates and caches the result.
-   * Uses numeric hash keys for faster cache lookups.
+   * Removes a (typically crashed) worker from the pool and terminates it.
    * @private
    */
-  _getCachedEvaluation(canonicalKey, originalHand, completeBoard, evalCache, matchupDeadMask = 0n) {
-    const cacheKey = this._getCacheKeyHash(canonicalKey, completeBoard, matchupDeadMask);
-    if (evalCache.has(cacheKey)) return evalCache.get(cacheKey);
-    const handMask = this.getBitMasked(this._handStringToCards(originalHand));
-    const evaluation = this.evaluate(handMask | completeBoard);
-    evalCache.set(cacheKey, evaluation);
-    return evaluation;
+  _discardWorker(worker) {
+    if (this._workerPool) {
+      const idx = this._workerPool.indexOf(worker);
+      if (idx !== -1) this._workerPool.splice(idx, 1);
+    }
+    try { worker.terminate(); } catch (e) { /* ignore */ }
+  }
+
+  /**
+   * Terminates and clears the persistent worker pool. Call when done with an
+   * instance (e.g. on teardown) to free the worker threads.
+   */
+  terminateWorkerPool() {
+    if (!this._workerPool) return;
+    for (const worker of this._workerPool) {
+      try { worker.terminate(); } catch (e) { /* ignore */ }
+    }
+    this._workerPool = null;
   }
 
   /**
@@ -1386,6 +1730,7 @@ class BitVal {
    * @private
    */
   _getCombinations(availableMasks, k) {
+    if (k === 0) return [0n]; // complete board: exactly one runout (the empty draw)
     if (k === 1) return availableMasks;
     if (k === 2) {
       let combos = [];

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "poker-bitvaljs",
-  "version": "1.2.0",
+  "version": "1.5.2",
   "description": "High-performance poker hand evaluator optimized for browser environments, using bitwise operations for rapid poker hand analysis and equity calculations.",
   "main": "bitval.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node bench/correctness.js && node bench/determinism.js && node bench/exact-optimize.js 300 && node bench/eval-equivalence.js 1000000",
+    "test:full": "node bench/eval-equivalence.js --full && node bench/engine-differential.js && node bench/exact-optimize.js 2000",
+    "test:equiv": "node bench/eval-equivalence.js",
+    "test:exact": "node bench/exact-optimize.js",
+    "test:differential": "node bench/engine-differential.js",
+    "test:preflop": "node bench/preflop-validate.js",
+    "gen:preflop": "node bench/gen-preflop-table.js --out bench/preflop-table.bin",
+    "bench": "node bench/bench.js",
+    "bench:correct": "node bench/correctness.js",
+    "bench:determinism": "node bench/determinism.js"
   },
   "keywords": [
     "poker",