poker-bitvaljs 1.2.0 → 1.6.0

package/bitval.js

@@ -1,3 +1,16 @@
+// Where bitval-worker.js lives. Resolved against this script's own URL when it
+// is loaded with a <script> tag (so it works from node_modules / a CDN path,
+// not just next to the page); otherwise relative to the page. Override per
+// instance with `bitval.workerUrl = '...'` (e.g. when bundling).
+const _BITVAL_WORKER_URL = (function () {
+  try {
+    if (typeof document !== 'undefined' && document.currentScript && document.currentScript.src) {
+      return new URL('bitval-worker.js', document.currentScript.src).href;
+    }
+  } catch (e) { /* fall through */ }
+  return './bitval-worker.js';
+})();
+
 class XorShift32 {
   constructor(seed = null) {
     this.state = seed !== null ? seed : Math.floor(Math.random() * 2147483647) || 1;
@@ -13,48 +26,10 @@ 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() {
+    this.workerUrl = _BITVAL_WORKER_URL;
+
     // Suit constants
     this._DIAMOND = 3n;
     this._HEART = 2n;
@@ -183,6 +158,64 @@ 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;
+    }
+    // Kicker tables (replace the per-eval "peel the highest bit" loops):
+    // _TOP5V13[m] = top five ranks of m packed as r1*65536+r2*4096+r3*256+r4*16+r5
+    //              (flush / high card value; fewer ranks just sum fewer terms).
+    // _KEEP2_13[m] / _KEEP3_13[m] = m with only its top 2 / top 3 bits kept, so
+    //              _TOP5V13[_KEEP3_13[m]] >> 4 = k1*4096+k2*256+k3*16 (pair kickers).
+    this._TOP5V13 = new Int32Array(8192);
+    this._KEEP2_13 = new Uint16Array(8192);
+    this._KEEP3_13 = new Uint16Array(8192);
+    for (let m = 0; m < 8192; m++) {
+      let v = 0, shift = 65536, n = 0, keep = 0;
+      for (let r = 12; r >= 0 && n < 5; r--) {
+        if (m & (1 << r)) {
+          v += r * shift; shift >>= 4; n++; keep |= 1 << r;
+          if (n === 2) this._KEEP2_13[m] = keep;
+          if (n === 3) this._KEEP3_13[m] = keep;
+        }
+      }
+      if (n < 2) this._KEEP2_13[m] = keep;
+      if (n < 3) this._KEEP3_13[m] = keep;
+      this._TOP5V13[m] = v;
+    }
+
+    // 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 +274,162 @@ 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) return 5 * 1048576 + this._TOP5V13[fm];
+
+    // Straight
+    {
+      const t = STR[all];
+      if (t >= 0) return 4 * 1048576 + t * 65536;
+    }
+
+    // Trips
+    if (trips) {
+      const t = this._high(trips);
+      return 3 * 1048576 + t * 65536 + (this._TOP5V13[this._KEEP2_13[all & ~(1 << t)]] >> 4);
+    }
+
+    // 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);
+      return 1 * 1048576 + p * 65536 + (this._TOP5V13[this._KEEP3_13[all & ~(1 << p)]] >> 4);
+    }
+
+    // High card
+    return this._TOP5V13[all];
+  }
+
   /**
    * Gets the human-readable hand strength from an evaluation mask.
    * @param {BigInt} handMask - Evaluation mask with score bits
@@ -285,28 +474,24 @@ class BitVal {
    * @returns {Object} { win, tie, lose, ...handStrengths } - Results object
    */
   simulate(iterations, numberOfBoardCards = 5, hero = [], villain = [], board = [], deadCards = []) {
-    let numberOfCardsToDeal = (numberOfBoardCards + 2) - (hero.length + board.length);
-    this.xorShift = new XorShift32();
+    const numberOfCardsToDeal = numberOfBoardCards - board.length;
+    const xorShift = this.xorShift = new XorShift32();
 
     const allDeadCards = [...hero, ...villain, ...board, ...deadCards];
-    deadCards = this.getBitMasked(allDeadCards);
-    numberOfCardsToDeal = numberOfBoardCards - board.length;
-    hero = this.getBitMasked(hero);
-    villain = this.getBitMasked(villain);
-    board = this.getBitMasked(board);
+    const deadMask = this.getBitMasked(allDeadCards);
 
     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;
-    let comboArray = null;
-    if (isExhaustive) {
-      const availableMasks = this._getAvailableCardMasksByLookUp(deadCards);
-      comboArray = this._getCombinations(availableMasks, numberOfCardsToDeal);
-    }
+    // 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 result = { 
+    let result = {
       "win": 0,
       "tie": 0,
       "lose": 0,
@@ -321,34 +506,44 @@ class BitVal {
       "Straight Flush": 0
     };
 
-    for (let i = 0; i < iterations; i++) {
-      let _board = isExhaustive && comboArray
-        ? board | comboArray[i]
-        : this.deal(board, deadCards, numberOfCardsToDeal) | board;
-
-      let [hero_eval, hero_tiebreaker] = this.evaluate(hero | _board);
-      let [villain_eval, villain_tiebreaker] = this.evaluate(villain | _board);
+    // BigInt-free hot loop (same engine as compareRange): cards are four 13-bit
+    // suit rank masks and _eval7 orders hands identically to evaluate().
+    const hs = this._suitsOfCards(hero), vs = this._suitsOfCards(villain), bs = this._suitsOfCards(board);
+    const hs0 = hs[0] | bs[0], hs1 = hs[1] | bs[1], hs2 = hs[2] | bs[2], hs3 = hs[3] | bs[3];
+    const vs0 = vs[0] | bs[0], vs1 = vs[1] | bs[1], vs2 = vs[2] | bs[2], vs3 = vs[3] | bs[3];
+    let win = 0, tie = 0, lose = 0;
 
-      if (hero_eval > villain_eval) {
-        result["win"]++;
-        continue;
-      }
-      if (hero_eval < villain_eval) {
-        result["lose"]++;
-        continue;
-      }
-      if (hero_tiebreaker > villain_tiebreaker) {
-        result["win"]++;
-        continue;
+    if (isExhaustive) {
+      const combos = this._buildComboSuits(this._getCombinations(this._getAvailableCardMasksByLookUp(deadMask), numberOfCardsToDeal));
+      const n = Math.min(iterations, combos.length >> 2);
+      for (let i = 0; i < n; i++) {
+        const b = i << 2, d0 = combos[b], d1 = combos[b + 1], d2 = combos[b + 2], d3 = combos[b + 3];
+        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++;
       }
-      if (hero_tiebreaker < villain_tiebreaker) {
-        result["lose"]++;
-        continue;
+    } else {
+      // Partial Fisher-Yates draw from the packed pool of live cards.
+      const pool = this._availableSuitCards(deadMask), poolLen = pool.length;
+      const nDeal = poolLen < numberOfCardsToDeal ? 0 : numberOfCardsToDeal;
+      let st = xorShift.state;
+      for (let i = 0; i < iterations; i++) {
+        let d0 = 0, d1 = 0, d2 = 0, d3 = 0;
+        for (let k = 0; k < nDeal; k++) {
+          st ^= st << 13; st ^= st >> 17; st ^= st << 5;
+          const j = k + Math.abs(st) % (poolLen - k);
+          const card = pool[j]; pool[j] = pool[k]; pool[k] = card;
+          const bit = card & 0xFFFF, suit = card >> 16;
+          if (suit === 0) d0 |= bit; else if (suit === 1) d1 |= bit; else if (suit === 2) d2 |= bit; else d3 |= bit;
+        }
+        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++;
       }
-
-      result["tie"]++
+      xorShift.state = st;
     }
-    
+
+    result.win = win; result.tie = tie; result.lose = lose;
     return result;
   }
 
@@ -368,13 +563,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
   // ============================================
@@ -629,95 +910,103 @@ class BitVal {
   // PRIVATE - Range Comparison Helpers
   // ============================================
 
+  /**
+   * Parses a 2-card hand string into card indices (0..51, rank*4+suit) and a
+   * split 64-bit card bitset (lo = cards 0..31, hi = cards 32..51) so overlap
+   * tests are plain Number ANDs instead of BigInt work.
+   * @private
+   */
+  _parseHand(hand) {
+    const a = this._cardIndex(hand), b = this._cardIndex(hand.substring(2, 4));
+    const lo = (a < 32 ? 1 << a : 0) | (b < 32 ? 1 << b : 0);
+    const hi = (a >= 32 ? 1 << (a - 32) : 0) | (b >= 32 ? 1 << (b - 32) : 0);
+    return { a, b, lo, hi };
+  }
+
+  /**
+   * Card bitset (lo/hi halves) for an array of card strings.
+   * @private
+   */
+  _cardsBitset(cards) {
+    let lo = 0, hi = 0;
+    for (const c of cards) { const i = this._cardIndex(c); if (i < 32) lo |= 1 << i; else hi |= 1 << (i - 32); }
+    return { lo, hi };
+  }
+
   /**
    * Generates all valid matchups between hero and villain hands, excluding overlaps.
+   * Each hand is parsed once; the O(H*V) overlap test runs on Number bitsets.
    * @private
    */
   _generateValidMatchups(heroHands, villainHands, boardCards = []) {
     const valid = [];
-    const boardMask = boardCards.length > 0 ? this.getBitMasked(boardCards) : 0n;
+    const board = this._cardsBitset(boardCards);
+    const nV = villainHands.length;
+    const vLo = new Int32Array(nV), vHi = new Int32Array(nV), vOk = new Uint8Array(nV), vMask = new Array(nV);
+    for (let j = 0; j < nV; j++) {
+      const p = this._parseHand(villainHands[j]);
+      vLo[j] = p.lo; vHi[j] = p.hi;
+      vOk[j] = ((p.lo & board.lo) | (p.hi & board.hi)) === 0 ? 1 : 0;
+      vMask[j] = vOk[j] ? this.getBitMasked(this._handStringToCards(villainHands[j])) : 0n;
+    }
     for (const h of heroHands) {
+      const p = this._parseHand(h);
+      if ((p.lo & board.lo) | (p.hi & board.hi)) continue;
       const hMask = this.getBitMasked(this._handStringToCards(h));
-      if (boardMask && (hMask & boardMask) !== 0n) continue;
-      for (const v of villainHands) {
-        const vMask = this.getBitMasked(this._handStringToCards(v));
-        if ((vMask & boardMask) !== 0n || (hMask & vMask) !== 0n) continue;
-        valid.push({ heroHand: h, villainHand: v, heroMask: hMask, villainMask: vMask });
+      for (let j = 0; j < nV; j++) {
+        if (!vOk[j] || (p.lo & vLo[j]) | (p.hi & vHi[j])) continue;
+        valid.push({ heroHand: h, villainHand: villainHands[j], heroMask: hMask, villainMask: vMask[j] });
       }
     }
     return valid;
   }
 
   /**
-   * Calculates valid matchup counts per canonical key pair.
-   * @private
-   */
-  _calculateValidCounts(validMatchups, hCanon, vCanon, boardCards, numberOfBoardCards) {
-    const counts = new Map();
-    const boardSuitCounts = boardCards.length > 0 ? this._getBoardSuitCounts(boardCards) : null;
-    for (const { heroHand, villainHand } of validMatchups) {
-      const hKey = this._getCanonicalKey(heroHand, boardCards, numberOfBoardCards, boardSuitCounts);
-      const vKey = this._getCanonicalKey(villainHand, boardCards, numberOfBoardCards, boardSuitCounts);
-      const key = `${hKey}:${vKey}`;
-      counts.set(key, (counts.get(key) || 0) + 1);
-    }
-    return counts;
-  }
-
-  /**
-   * Sets up range comparison by generating valid matchups and canonical mappings.
+   * Sets up range comparison. The per-pair matchup list is only materialized
+   * (lazily, via the `validMatchups` getter) by the paths that need it — the
+   * Monte Carlo and unoptimized paths. The exact exhaustive path works straight
+   * from the hand strings (see _buildExhaustiveWork).
    * @private
    */
   _compareRangeSetup(heroHands, villainHands, boardCards, deadCards, numberOfBoardCards, iterations, optimize) {
-    // Generate valid matchups (always needed)
-    const validMatchups = this._generateValidMatchups(heroHands, villainHands, boardCards);
-    
-    // Calculate canonical mappings only if optimization is enabled
-    let hCanon = null;
-    let vCanon = null;
-    let validCounts = null;
-    if (optimize) {
-      hCanon = this._flattenHandsToCanonical(heroHands, boardCards, numberOfBoardCards);
-      vCanon = this._flattenHandsToCanonical(villainHands, boardCards, numberOfBoardCards);
-      validCounts = this._calculateValidCounts(validMatchups, hCanon, vCanon, boardCards, numberOfBoardCards);
-    }
-    
     // Calculate bitmasks
     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;
-    
-    // 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) 
-      : Infinity;
-    iterations = Math.min(iterations, exhaustiveCombinations);
-    const isExhaustive = canBeExhaustive && iterations === exhaustiveCombinations && exhaustiveCombinations < Infinity;
-    
+    const isExhaustive = 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 lower requested count.
+    // Exhaustive is exact and deterministic; the requested iteration count only
+    // matters for larger (>=3 cards to come, e.g. preflop) scenarios.
+    if (isExhaustive) {
+      iterations = this.combinations(52 - this.countBits(deadCardsMask), numberOfCardsToDeal);
+    }
+
     // Generate combo array only if exhaustive
-    const comboArray = isExhaustive 
-      ? this._getCombinations(this._getAvailableCardMasksByLookUp(deadCardsMask), numberOfCardsToDeal) 
+    const comboArray = isExhaustive
+      ? this._getCombinations(this._getAvailableCardMasksByLookUp(deadCardsMask), numberOfCardsToDeal)
       : null;
-    
-    return { 
-      hCanon, 
-      vCanon, 
-      boardMask, 
-      deadCardsMask, 
-      iterations, 
-      isExhaustive, 
-      comboArray, 
-      numberOfCardsToDeal, 
-      validMatchups, 
-      validCounts, 
-      boardCards, 
-      numberOfBoardCards 
+
+    const self = this;
+    return {
+      heroHands,
+      villainHands,
+      boardMask,
+      deadCardsMask,
+      iterations,
+      isExhaustive,
+      comboArray,
+      numberOfCardsToDeal,
+      boardCards,
+      numberOfBoardCards,
+      _validMatchups: null,
+      get validMatchups() {
+        return this._validMatchups || (this._validMatchups = self._generateValidMatchups(heroHands, villainHands, boardCards));
+      }
     };
   }
 
@@ -735,9 +1024,10 @@ class BitVal {
       numberOfBoardCards: setup.numberOfBoardCards,
       iterations: setup.iterations,
       isExhaustive: setup.isExhaustive,
-      numberOfCardsToDeal: setup.numberOfCardsToDeal
-      // Note: hCanon, vCanon, validMatchups, validCounts are not needed in workers
-      // as matchups are pre-serialized and sent separately
+      numberOfCardsToDeal: setup.numberOfCardsToDeal,
+      mcTarget: setup.mcTarget
+      // Note: validMatchups is not needed in workers; matchups are
+      // pre-serialized and sent separately
     };
   }
 
@@ -783,55 +1073,158 @@ 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) {
+  /**
+   * Synchronous single-matchup evaluation (no progress / yielding). Used by the
+   * sequential path when there's no progress callback and by the Web Worker,
+   * so both run the same tight loop with the RNG state held in a local.
+   * @private
+   */
+  _evaluateMatchupSync(heroMask, villainMask, setup) {
+    let win = 0, tie = 0, lose = 0;
+    const hs = this._suitsFromBigMask(heroMask), vs = this._suitsFromBigMask(villainMask);
+    const bb = setup._boardSuits || (setup._boardSuits = this._suitsFromBigMask(setup.boardMask));
+    const hs0 = hs[0], hs1 = hs[1], hs2 = hs[2], hs3 = hs[3];
+    const vs0 = vs[0], vs1 = vs[1], vs2 = vs[2], vs3 = vs[3];
+    const bb0 = bb[0], bb1 = bb[1], bb2 = bb[2], bb3 = bb[3];
+
+    if (setup.isExhaustive) {
+      const comboSuits = setup._comboSuits || (setup._comboSuits = this._buildComboSuits(setup.comboArray));
+      const n = comboSuits.length >> 2;
+      const m0 = hs0 | vs0, m1 = hs1 | vs1, m2 = hs2 | vs2, m3 = hs3 | vs3;
+      for (let i = 0; i < n; i++) {
+        const b = i << 2;
+        const c0 = comboSuits[b], c1 = comboSuits[b + 1], c2 = comboSuits[b + 2], c3 = comboSuits[b + 3];
+        if ((c0 & m0) | (c1 & m1) | (c2 & m2) | (c3 & m3)) continue; // runout uses a hole card
+        const d0 = bb0 | c0, d1 = bb1 | c1, d2 = bb2 | c2, d3 = bb3 | c3;
+        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++;
+      }
+      return { matchupWin: win, matchupTie: tie, matchupLose: lose };
+    }
+
+    const xorShift = this.xorShift = new XorShift32();
+    const pool = this._availableSuitCards(heroMask | villainMask | setup.deadCardsMask), poolLen = pool.length;
+    const nDeal = setup.numberOfCardsToDeal;
+    const iterations = setup.iterations;
+    const mcTarget = setup.mcTarget > 0 ? setup.mcTarget / 100 : 0;
+    let ran = iterations, st = xorShift.state;
+    for (let i = 0; i < iterations; i++) {
+      let d0 = bb0, d1 = bb1, d2 = bb2, d3 = bb3;
+      for (let k = 0; k < nDeal; k++) {
+        st ^= st << 13; st ^= st >> 17; st ^= st << 5;
+        const j = k + Math.abs(st) % (poolLen - k);
+        const card = pool[j]; pool[j] = pool[k]; pool[k] = card;
+        const bit = card & 0xFFFF, suit = card >> 16;
+        if (suit === 0) d0 |= bit; else if (suit === 1) d1 |= bit; else if (suit === 2) d2 |= bit; else d3 |= bit;
+      }
+      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; }
+      }
+    }
+    xorShift.state = st;
+
+    // If early-stopped, scale counts back to the requested iteration count so
+    // every matchup is weighted equally in the aggregate.
+    if (ran < iterations && ran > 0) {
+      const s = iterations / ran;
+      win = Math.round(win * s); tie = Math.round(tie * s); lose = Math.round(lose * s);
+    }
+    return { matchupWin: win, matchupTie: tie, matchupLose: lose };
+  }
+
+  async _evaluateMatchup(heroMask, villainMask, setup, progressCallback = null, matchupIndex = 0, totalMatchups = 1) {
+    // No progress reporting: run the tight synchronous loop (no per-iteration
+    // yield checks, RNG in a local).
+    if (!progressCallback) return this._evaluateMatchupSync(heroMask, villainMask, setup);
     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, live = true;
+      if (comboSuits) {
+        const b = i << 2;
+        const c0 = comboSuits[b], c1 = comboSuits[b + 1], c2 = comboSuits[b + 2], c3 = comboSuits[b + 3];
+        // Skip runouts that use a hole card (impossible deals).
+        live = ((c0 & (hs0 | vs0)) | (c1 & (hs1 | vs1)) | (c2 & (hs2 | vs2)) | (c3 & (hs3 | vs3))) === 0;
+        d0 = bb0 | c0; d1 = bb1 | c1; d2 = bb2 | c2; d3 = bb3 | c3;
       } 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++;
+
+      if (live) {
+        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 +1264,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 +1288,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) {
@@ -926,116 +1327,276 @@ class BitVal {
     return { win, tie, lose };
   }
 
+  /**
+   * Groups the valid (hero, villain) matchups by canonical key pair for the
+   * Monte Carlo path. Canonical keys depend only on the hand (and board), so
+   * they're computed once per hand string, and pairs are enumerated with Number
+   * card bitsets — no per-pair objects or string keys. Each group keeps the
+   * first matchup (hero-major order) as its representative. Cached on `setup`.
+   * @private
+   */
+  _groupMonteCarloMatchups(setup) {
+    if (setup._mcGroups) return setup._mcGroups;
+    const { heroHands, villainHands, boardCards, numberOfBoardCards } = setup;
+    const board = this._cardsBitset(boardCards);
+    const boardSuitCounts = boardCards.length > 0 ? this._getBoardSuitCounts(boardCards) : null;
+    const keyIds = new Map(), keyNames = [];
+    const keyId = (hand) => {
+      const k = this._getCanonicalKey(hand, boardCards, numberOfBoardCards, boardSuitCounts);
+      let id = keyIds.get(k);
+      if (id === undefined) { id = keyNames.length; keyIds.set(k, id); keyNames.push(k); }
+      return id;
+    };
+    const parseSide = (hands) => {
+      const n = hands.length, lo = new Int32Array(n), hi = new Int32Array(n), id = new Int32Array(n), ok = new Uint8Array(n);
+      for (let i = 0; i < n; i++) {
+        const p = this._parseHand(hands[i]);
+        lo[i] = p.lo; hi[i] = p.hi;
+        ok[i] = ((p.lo & board.lo) | (p.hi & board.hi)) === 0 ? 1 : 0;
+        if (ok[i]) id[i] = keyId(hands[i]);
+      }
+      return { lo, hi, id, ok, n };
+    };
+    const H = parseSide(heroHands), V = parseSide(villainHands);
+    const nK = keyNames.length;
+    const groupOf = new Map(), groups = [];
+    for (let h = 0; h < H.n; h++) {
+      if (!H.ok[h]) continue;
+      const hl = H.lo[h], hh = H.hi[h], hk = H.id[h] * nK;
+      for (let v = 0; v < V.n; v++) {
+        if (!V.ok[v] || (hl & V.lo[v]) | (hh & V.hi[v])) continue;
+        const gk = hk + V.id[v];
+        let g = groupOf.get(gk);
+        if (g === undefined) {
+          const heroHand = heroHands[h], villainHand = villainHands[v];
+          const heroKey = keyNames[H.id[h]], villainKey = keyNames[V.id[v]];
+          g = {
+            key: `${heroKey}:${villainKey}`, validCount: 0, heroKey, villainKey, heroHand, villainHand,
+            heroMask: this.getBitMasked(this._handStringToCards(heroHand)),
+            villainMask: this.getBitMasked(this._handStringToCards(villainHand))
+          };
+          groupOf.set(gk, g); groups.push(g);
+        }
+        g.validCount++;
+      }
+    }
+    return (setup._mcGroups = groups);
+  }
+
   /**
    * Compares ranges with canonical key caching optimization (sequential version).
    * @private
    */
   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
     
-    // Pre-calculate board suit counts once (constant for all matchups)
-    const boardSuitCounts = setup.boardCards.length > 0 
-      ? 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 groups = this._groupMonteCarloMatchups(setup);
+      const totalMatchups = groups.length;
+      let matchupIndex = 0;
+      for (const group of groups) {
+        const validCount = group.validCount;
+        const validPair = group;
+        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; }
+          }
+        }
       }
-      matchupGroups.get(key).count++;
+      if (progressCallback) progressCallback(matchupIndex, matchupIndex, 'Complete');
+      return { win, tie, lose };
     }
-    
-    // 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;
+
+    // Exhaustive: EXACT evaluate-once. Build the shared work structure and run
+    // the kernel over all runouts (on the main thread for both the worker and
+    // non-worker paths, so they 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 straight
+   * from the hand strings (no per-pair objects, no BigInt). Hands are
+   * deduplicated into a UNION of hero+villain concrete hands — each evaluated
+   * once per runout even when it appears in both ranges — with per-hand hero
+   * and villain multiplicities, so duplicates count exactly as they do in the
+   * per-pair unoptimized computation. Small fields get an explicit valid-pair
+   * list; large fields are resolved by the counting sweep in _runExhaustive.
+   * Everything is typed arrays so it could be shipped to workers unchanged.
+   * @private
+   */
+  _buildExhaustiveWork(setup) {
+    const board = this._cardsBitset(setup.boardCards);
+    const uIndex = new Int32Array(52 * 52).fill(-1);
+    const uSuitArr = [], uAArr = [], uBArr = [], uLoArr = [], uHiArr = [];
+    const addSide = (hands) => {
+      const u = [];
+      for (const hand of hands) {
+        const p = this._parseHand(hand);
+        if ((p.lo & board.lo) | (p.hi & board.hi)) continue; // conflicts with board
+        const key = p.a < p.b ? p.a * 52 + p.b : p.b * 52 + p.a;
+        let ui = uIndex[key];
+        if (ui < 0) {
+          ui = uIndex[key] = uAArr.length;
+          const s = this._suitsOfCards([hand.substring(0, 2), hand.substring(2, 4)]);
+          uSuitArr.push(s[0], s[1], s[2], s[3]);
+          uAArr.push(p.a); uBArr.push(p.b); uLoArr.push(p.lo); uHiArr.push(p.hi);
+        }
+        u.push(ui);
+      }
+      return u;
+    };
+    const heroU = addSide(setup.heroHands);
+    const villU = addSide(setup.villainHands);
+    const U = uAArr.length;
+    const uSuit = Int32Array.from(uSuitArr), uA = Int32Array.from(uAArr), uB = Int32Array.from(uBArr);
+    const hMult = new Int32Array(U), vMult = new Int32Array(U);
+    for (const u of heroU) hMult[u]++;
+    for (const u of villU) vMult[u]++;
+    const nH = heroU.length, nV = villU.length;
+    const bb = setup._boardSuits || (setup._boardSuits = this._suitsFromBigMask(setup.boardMask));
+
+    // cardU[cardUOff[c]..cardUOff[c+1]) = union hands holding card c, used to
+    // drop hands whose hole cards appear in a runout (that deal is impossible).
+    const cardUOff = new Int32Array(53);
+    for (let u = 0; u < U; u++) { cardUOff[uA[u] + 1]++; cardUOff[uB[u] + 1]++; }
+    for (let c = 0; c < 52; c++) cardUOff[c + 1] += cardUOff[c];
+    const cardU = new Int32Array(U * 2), cfill = cardUOff.slice(0, 52);
+    for (let u = 0; u < U; u++) { cardU[cfill[uA[u]]++] = u; cardU[cfill[uB[u]]++] = u; }
+
+    const useCount = nH >= 16 && nV >= 16;
+    let pHa = null, pVa = null, P = 0, cardTotal = null;
+    if (useCount) {
+      // cardTotal[c] = number of villain entries holding card c.
+      cardTotal = new Int32Array(52);
+      for (let u = 0; u < U; u++) { cardTotal[uA[u]] += vMult[u]; cardTotal[uB[u]] += vMult[u]; }
+    } else {
+      const ph = [], pv = [];
+      for (const h of heroU) {
+        const hl = uLoArr[h], hh = uHiArr[h];
+        for (const v of villU) {
+          if ((hl & uLoArr[v]) | (hh & uHiArr[v])) continue;
+          ph.push(h); pv.push(v);
+        }
+      }
+      pHa = Int32Array.from(ph); pVa = Int32Array.from(pv); P = pHa.length;
+    }
+    return {
+      uSuit, uA, uB, hMult, vMult, U, nH, nV, useCount, pHa, pVa, P, cardTotal, cardUOff, cardU,
+      bb0: bb[0], bb1: bb[1], bb2: bb[2], bb3: bb[3]
+    };
+  }
+
+  /**
+   * Exact exhaustive kernel over runouts [runStart, runEnd). Evaluates each
+   * unique concrete hand once per runout, then resolves matchups by direct
+   * comparison (small fields) or, for large fields, a single sort of the
+   * unique hands followed by a linear sweep over equal-value groups that keeps
+   * running villain counts in total and per hole card (to subtract villains
+   * sharing a card with the hero). Byte-identical to unoptimized.
+   * @private
+   */
+  _runExhaustive(work, comboSuits, runStart, runEnd) {
+    const { uSuit, uA, uB, hMult, vMult, U, nV, useCount, pHa, pVa, P, cardTotal, cardUOff, cardU, bb0, bb1, bb2, bb3 } = work;
+    const uVals = new Int32Array(U);
+    // dead[u] === i  <=>  hand u holds a card dealt in runout i, so it takes no
+    // part in that runout (neither as hero nor as villain).
+    const dead = new Int32Array(U).fill(-1);
+    const cardTot = useCount ? new Int32Array(52) : null;
+    let win = 0, tie = 0, lose = 0;
+
+    // Large-field scratch: sort keys (value*U + u, exact in a double) and
+    // per-card villain counts strictly below / equal to the current value.
+    const keys = useCount ? new Float64Array(U) : null;
+    const order = useCount ? new Int32Array(U) : null;
+    const lessC = useCount ? new Int32Array(52) : null;
+    const eqC = useCount ? new Int32Array(52) : null;
+
+    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 u = 0; u < U; u++) { const q = u << 2; uVals[u] = this._eval7(uSuit[q] | d0, uSuit[q + 1] | d1, uSuit[q + 2] | d2, uSuit[q + 3] | d3); }
+
+      // Mark hands holding a runout card; for counting, also remove those
+      // villains from the field total and the per-card totals.
+      let nVi = nV;
+      if (useCount) cardTot.set(cardTotal);
+      for (let s = 0; s < 4; s++) {
+        let m = comboSuits[b + s];
+        while (m) {
+          const low = m & -m; m ^= low;
+          const c = (31 - Math.clz32(low)) * 4 + s;
+          for (let k = cardUOff[c], e = cardUOff[c + 1]; k < e; k++) {
+            const u = cardU[k];
+            if (dead[u] === i) continue;
+            dead[u] = i;
+            if (useCount) { const vm = vMult[u]; if (vm) { nVi -= vm; cardTot[uA[u]] -= vm; cardTot[uB[u]] -= vm; } }
           }
         }
       }
+
+      if (!useCount) {
+        for (let p = 0; p < P; p++) {
+          const hu = pHa[p], vu = pVa[p];
+          if (dead[hu] === i || dead[vu] === i) continue;
+          const hv = uVals[hu], vv = uVals[vu]; if (hv > vv) win++; else if (vv > hv) lose++; else tie++;
+        }
+        continue;
+      }
+
+      for (let u = 0; u < U; u++) keys[u] = uVals[u] * U + u;
+      keys.sort();
+      for (let k = 0; k < U; k++) { const key = keys[k]; order[k] = key - Math.floor(key / U) * U; }
+      lessC.fill(0);
+
+      let below = 0; // villain entries with value < current group value
+      for (let g = 0; g < U;) {
+        const x = uVals[order[g]];
+        let e = g + 1; while (e < U && uVals[order[e]] === x) e++;
+        // Villain counts at exactly x: total and per card.
+        let eqTotal = 0;
+        for (let k = g; k < e; k++) { const u = order[k]; if (dead[u] === i) continue; const m = vMult[u]; if (m) { eqTotal += m; eqC[uA[u]] += m; eqC[uB[u]] += m; } }
+        const above = nVi - below - eqTotal;
+        // Heroes at x. A villain holding both hero cards (the identical hand)
+        // is subtracted on each card, so add it back once (it ties at x).
+        for (let k = g; k < e; k++) {
+          const u = order[k], m = hMult[u];
+          if (!m || dead[u] === i) continue;
+          const a = uA[u], c = uB[u];
+          const w = below - lessC[a] - lessC[c];
+          const t = eqTotal - eqC[a] - eqC[c] + vMult[u];
+          const l = above - (cardTot[a] - lessC[a] - eqC[a]) - (cardTot[c] - lessC[c] - eqC[c]);
+          win += w * m; tie += t * m; lose += l * m;
+        }
+        // Fold this group into the running "below" counts.
+        for (let k = g; k < e; k++) { const u = order[k]; if (dead[u] === i) continue; const m = vMult[u]; if (m) { lessC[uA[u]] += m; lessC[uB[u]] += m; eqC[uA[u]] = 0; eqC[uB[u]] = 0; } }
+        below += eqTotal;
+        g = e;
+      }
     }
-    
-    if (progressCallback) progressCallback(matchupIndex, matchupIndex, 'Complete');
     return { win, tie, lose };
   }
 
@@ -1045,85 +1606,50 @@ class BitVal {
    * @private
    */
   async _compareRangeOptimized(setup, progressCallback = null, progressInterval = 100, useWorkers = true) {
-    // Pre-calculate board suit counts once (constant for all matchups)
-    const boardSuitCounts = setup.boardCards.length > 0 
-      ? 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
-        });
-      }
-      matchupGroups.get(key).count++;
-    }
-    
-    // Collect all matchups to evaluate (only those that actually exist)
-    const matchupsToEvaluate = [];
-    for (const [key, group] of matchupGroups) {
-      const validPair = group.representative;
-      matchupsToEvaluate.push({
-        key,
-        validCount: group.count,
-        heroKey: group.heroKey,
-        heroHand: validPair.heroHand,
-        heroMask: validPair.heroMask,
-        villainKey: group.villainKey,
-        villainHand: validPair.villainHand,
-        villainMask: validPair.villainMask
-      });
+    // 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);
     }
-    
-    // Calculate total matchups (number of unique canonical key pairs)
+
+    // Group validMatchups by canonical key pair (only matchups that exist).
+    const matchupsToEvaluate = this._groupMonteCarloMatchups(setup);
     const totalMatchups = matchupsToEvaluate.length;
-    
+
     // Check if workers should be used
-    const shouldUseWorkers = useWorkers && 
-                             typeof Worker !== 'undefined' && 
-                             matchupsToEvaluate.length >= 4;
-    
-    if (!shouldUseWorkers) {
-      // Fallback to sequential execution
-      return await this._compareRangeOptimizedSequential(setup, progressCallback, progressInterval);
+    const shouldUseWorkers = useWorkers &&
+                             typeof Worker !== 'undefined' &&
+                             totalMatchups >= 4;
+    let workers = null;
+    if (shouldUseWorkers) {
+      const numWorkers = Math.min((typeof navigator !== 'undefined' && navigator.hardwareConcurrency) || 4, totalMatchups);
+      // Persistent pool (created once, reused across calls). Creation can throw
+      // synchronously (e.g. a cross-origin worker URL); fall back to sequential.
+      try { workers = this._acquireWorkers(numWorkers); } catch (e) { workers = null; }
     }
-    
-    // Use Web Workers for parallelization
-    const numWorkers = Math.min(navigator.hardwareConcurrency || 4, matchupsToEvaluate.length);
-    const batchSize = Math.ceil(matchupsToEvaluate.length / numWorkers);
-    const batches = [];
-    for (let i = 0; i < matchupsToEvaluate.length; i += batchSize) {
-      batches.push(matchupsToEvaluate.slice(i, i + batchSize));
+    if (!workers || workers.length === 0) {
+      return await this._compareRangeOptimizedSequential(setup, progressCallback, progressInterval);
     }
-    
-    // Serialize setup for workers
+    const numWorkers = workers.length;
+
+    // Dynamic dispatch: hand out small chunks to whichever worker is free.
+    // With Monte Carlo early-stop, matchup cost varies a lot (lopsided matchups
+    // converge in ~8k draws, close ones run the full count), so equal static
+    // batches left most workers idle behind the slowest one.
+    const chunkSize = Math.max(1, Math.ceil(totalMatchups / (numWorkers * 8)));
     const serializedSetup = this._serializeSetup(setup);
-    
-    // Create workers and distribute work
-    const workers = [];
-    const promises = [];
-    let completedMatchups = 0;
-    
+    let next = 0, completedMatchups = 0, win = 0, tie = 0, lose = 0, alive = numWorkers;
+    const addResult = (r) => {
+      win += r.matchupWin * r.validCount; tie += r.matchupTie * r.validCount; lose += r.matchupLose * r.validCount;
+      completedMatchups++;
+    };
+
     // Progress tracking
     let lastProgressTime = 0;
     const progressUpdateInterval = 100;
@@ -1134,108 +1660,92 @@ 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 promise = new Promise((resolve, reject) => {
-        worker.onmessage = (e) => {
-          if (e.data.success) {
-            completedMatchups += e.data.results.length;
-            resolve(e.data.results);
-          } else {
-            reject(new Error(e.data.error || 'Worker error'));
+
+    // Each worker loop pulls the next chunk until none are left. A worker that
+    // crashes is dropped from the pool and its in-flight chunk is evaluated on
+    // the main thread, so one bad worker never loses work or fails the call.
+    const runWorker = (worker, workerId) => new Promise((resolve, reject) => {
+      let current = null;
+      const cleanup = () => { worker.onmessage = null; worker.onerror = null; };
+      const dispatch = () => {
+        if (next >= totalMatchups) { cleanup(); resolve(); return; }
+        const start = next; next = Math.min(totalMatchups, next + chunkSize);
+        current = matchupsToEvaluate.slice(start, next);
+        worker.postMessage({ matchups: current.map(m => this._serializeMatchup(m)), setupData: serializedSetup, workerId });
+      };
+      // One handler set per call; cleared on settle so the pooled worker is
+      // clean for the next call. (Assumes compareRange calls don't overlap.)
+      worker.onmessage = (e) => {
+        if (!e.data.success) { cleanup(); reject(new Error(e.data.error || 'Worker error')); return; }
+        for (const r of e.data.results) addResult(r);
+        current = null;
+        dispatch();
+      };
+      worker.onerror = (error) => {
+        if (error && error.preventDefault) error.preventDefault();
+        cleanup();
+        this._discardWorker(worker);
+        try {
+          if (current) for (const m of current) addResult({ validCount: m.validCount, ...this._evaluateMatchupSync(m.heroMask, m.villainMask, setup) });
+          current = null;
+          // Last worker of this call died: finish the remaining chunks here.
+          if (--alive === 0) {
+            while (next < totalMatchups) { const m = matchupsToEvaluate[next++]; addResult({ validCount: m.validCount, ...this._evaluateMatchupSync(m.heroMask, m.villainMask, setup) }); }
           }
-          worker.terminate();
-        };
-        worker.onerror = (error) => {
-          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;
+          resolve();
+        } catch (err) { reject(err); }
+      };
+      dispatch();
+    });
+
     try {
-      const allResults = await Promise.all(promises);
-      
-      for (const batchResults of allResults) {
-        for (const result of batchResults) {
-          win += result.matchupWin * result.validCount;
-          tie += result.matchupTie * result.validCount;
-          lose += result.matchupLose * result.validCount;
-        }
-      }
+      await Promise.all(workers.map((w, i) => runWorker(w, i)));
     } finally {
-      // Clean up progress interval
-      if (progressIntervalId) {
-        clearInterval(progressIntervalId);
-      }
-      
-      // Ensure all workers are terminated
-      workers.forEach(worker => {
-        try {
-          worker.terminate();
-        } catch (e) {
-          // Ignore termination errors
-        }
-      });
-      
-      // Final progress update
-      if (progressCallback) {
-        progressCallback(totalMatchups, totalMatchups, 'Complete');
-      }
+      if (progressIntervalId) clearInterval(progressIntervalId);
+      // Workers are NOT terminated - they stay in the pool for the next call.
+      // Callers can free them explicitly with terminateWorkerPool().
+      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(this.workerUrl));
+    }
+    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;
   }
 
   /**
@@ -1302,26 +1812,6 @@ class BitVal {
     }
   }
 
-  /**
-   * Flattens hands to canonical keys for caching optimization.
-   * @private
-   */
-  _flattenHandsToCanonical(hands, boardCards = [], numberOfBoardCards = 5) {
-    const canonicalMap = new Map();
-    const canonicalToHand = new Map();
-    const boardSuitCounts = boardCards.length > 0 ? this._getBoardSuitCounts(boardCards) : null;
-    
-    for (const hand of hands) {
-      const key = this._getCanonicalKey(hand, boardCards, numberOfBoardCards, boardSuitCounts);
-      canonicalMap.set(key, (canonicalMap.get(key) || 0) + 1);
-      if (!canonicalToHand.has(key)) {
-        canonicalToHand.set(key, hand);
-      }
-    }
-    
-    return { canonicalMap, canonicalToHand };
-  }
-
   /**
    * Gets board suit counts for flush potential calculation.
    * @private
@@ -1386,6 +1876,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 = [];