poker-bitvaljs 1.5.2 → 1.7.0

package/README.md

@@ -175,7 +175,7 @@ Compares two ranges of hands.
 - `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 the Monte Carlo path (default: `true`). The exact flop/turn path runs on the main thread.
+- `useWorkers` (Boolean): Use Web Workers (default: `true`) for Monte Carlo and for large exact flop/turn queries; small exact queries stay 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:**
@@ -185,20 +185,55 @@ Compares two ranges of hands.
 
 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`.
+(browser) or Node `Buffer`. The table (~1 MB) ships with the npm package at
+`poker-bitvaljs/bench/preflop-table.bin`; regenerate it with `npm run gen:preflop`.
 
 ```javascript
-// Browser
-const buf = await (await fetch('./bench/preflop-table.bin')).arrayBuffer();
+// Browser (serve the file from wherever you host the package)
+const buf = await (await fetch('./node_modules/poker-bitvaljs/bench/preflop-table.bin')).arrayBuffer();
 bitval.loadPreflopTable(buf);
 
 // Node
 const fs = require('fs');
-bitval.loadPreflopTable(fs.readFileSync('bench/preflop-table.bin'));
+bitval.loadPreflopTable(fs.readFileSync(require.resolve('poker-bitvaljs/bench/preflop-table.bin')));
 ```
 
 Without a table loaded, preflop falls back to Monte Carlo — nothing else changes.
 
+### Shared-board Monte Carlo (opt-in)
+
+Monte Carlo is only used when the preflop table can't be (preflop with dead
+cards, or no table loaded). By default each matchup samples its own boards.
+Setting `mcSharedBoards` samples boards once and evaluates every hand on each
+board, counting all valid pairs at once — typically 25–100× faster for
+range-vs-range, with no canonical-grouping approximation:
+
+```javascript
+const bitval = new BitVal();
+bitval.mcSharedBoards = true;
+const r = await bitval.compareRange(heroRange, villainRange, [], ['2c'], 5, 100000);
+```
+
+In this mode `iterations` is the maximum number of **boards** sampled (shared by
+all matchups), `mcTargetPct` applies to the aggregate equity, and the returned
+`win`/`tie`/`lose` are summed over valid pairs × boards. Equity percentages are
+directly comparable to the default mode; raw counts are not.
+
+## Changes in 1.7.0
+
+- Opt-in shared-board Monte Carlo (`mcSharedBoards`, above).
+- Large exact flop/turn queries are split across Web Workers.
+- Faster exact flop/turn kernel (radix sort), faster preflop table load and
+  lookup (~4.5× for full range vs full range). Results are unchanged.
+
+## Changes in 1.6.0
+
+- **Flop/turn correctness fix:** exhaustive `compareRange` no longer counts
+  runouts that deal a player's own hole card. Flop/turn equities from earlier
+  versions were slightly off (typically 0–3 percentage points) and will change.
+- Large range-vs-range flop/turn is ~10–100× faster; `simulate()` is ~45×
+  faster; the preflop table ships with the package.
+
 ## Performance
 
 - **No BigInt in the hot path** — cards are four 13-bit suit lanes evaluated with
@@ -222,6 +257,11 @@ correctness with `npm test` (and `npm run test:full` for the exhaustive proofs).
 - 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.
+- For preflop with dead cards, set `bitval.mcSharedBoards = true` (see above).
+- Web Workers load `bitval-worker.js` from next to `bitval.js` (resolved from
+  the `<script>` tag's URL). If you bundle or relocate the files, set
+  `bitval.workerUrl = '/path/to/bitval-worker.js'`. If workers can't start,
+  `compareRange` falls back to the main thread.
 
 ## Testing Locally
 

package/bitval-worker.js

@@ -32,101 +32,29 @@ function deserializeMatchup(matchupData) {
   };
 }
 
-/**
- * Evaluates a single matchup in the worker context
- * Similar to _evaluateMatchup but without progress callbacks
- */
-async function evaluateMatchupInWorker(heroMask, villainMask, setup, bitval) {
-  let win = 0, tie = 0, lose = 0;
-  const deadMask = heroMask | villainMask | setup.deadCardsMask;
-
-  // Initialize random number generator for Monte Carlo (not needed for exhaustive)
-  if (!setup.isExhaustive) {
-    bitval.xorShift = new XorShift32();
-  }
-  
-  // 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.
-    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++) {
-    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 {
-      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;
-      }
-    }
-    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 };
-}
-
 // 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).
+// Worker message handler: per-matchup Monte Carlo batches, or exact-kernel
+// batches (type: 'kernel').
 self.onmessage = async function(e) {
   try {
+    // Exact kernel over a batch of runouts / sampled boards
+    // (BitVal._runKernelBatches): exact flop/turn and shared-board Monte Carlo.
+    if (e.data.type === 'kernel') {
+      const { work, boards } = e.data;
+      self.postMessage({ success: true, result: _bitval._runExhaustive(work, boards, 0, boards.length >> 2) });
+      return;
+    }
+
     const { matchups, setupData, workerId } = e.data;
     const setup = deserializeSetup(setupData);
     const results = [];
 
     for (const matchupData of matchups) {
       const matchup = deserializeMatchup(matchupData);
-      const result = await evaluateMatchupInWorker(matchup.heroMask, matchup.villainMask, setup, _bitval);
+      // Same synchronous loop as the main thread (BitVal._evaluateMatchupSync).
+      const result = _bitval._evaluateMatchupSync(matchup.heroMask, matchup.villainMask, setup);
       results.push({ key: matchup.key, validCount: matchup.validCount, ...result });
     }