poker-extval 3.3.3 → 3.4.0

package/README.md

@@ -126,6 +126,9 @@ const result = evaluateHand(['As', 'Ah', 'Kd', 'Kc', 'Qs'], false);
 - Descriptive labels (isTopPair, etc.) are only true if they match the strongest hand
 - Made flush or stronger cannot have straight draws (flush > straight)
 - Draws can coexist when no made hand exists (flush draw + straight draw is valid)
+- With 6 or more cards, draws are collected from **every** 5-card combination, not just the best one, so a draw using a card outside the best five is still reported. Straight draws are dropped once a straight or better is made, and flush draws once a flush or better is made. `isComboDraw` is true when the whole hand has both a flush draw and a straight draw.
+
+**Draws by street**: the number of cards sets the street. With 5 cards (the flop) every draw is possible; with 6 (the turn) there is no `isBackdoorFlushDraw`, since one card to come cannot complete it; with 7 (the river) there are no draws at all. This applies in both modes.
 
 ### Evaluating Multiple Card Hands
 
@@ -191,6 +194,8 @@ The `evaluateHand()` function returns an object where:
 - `isMiddleThreeOfAKind` - Three of a kind is neither highest nor lowest
 - `isBottomThreeOfAKind` - Three of a kind is the lowest rank
 
+**Note**: With `holeCards`, pair and three of a kind positions are judged against the **whole board**, including board cards left out of the 5-card combination: top means at or above the highest board card (so a pocket pair above the board is top pair), bottom means at or below the lowest, middle is anything between. A pair or three of a kind made only of board cards gets no position. Without `holeCards` the board is unknown, so positions are judged within the 5-card combination. Two pair positions are always judged within the 5-card combination.
+
 #### Overcard Categorization (requires `holeCards`; not filtered by strict mode)
 - `isOvercard` - At least one hole card ranks above every board card
 - `isTwoOvercards` - Both hole cards rank above every board card
@@ -446,7 +451,7 @@ The test suite includes 700+ tests covering:
 
 ## API Reference
 
-### `evaluateHand(cards, strict, holeCards)`
+### `evaluateHand(cards, strict, holeCards, villainRange)`
 
 Main function to evaluate poker hands.
 
@@ -454,6 +459,7 @@ Main function to evaluate poker hands.
 - `cards` (string[]): Array of 5 or more card strings
 - `strict` (boolean, optional): If `true`, only the strongest made hand and stronger draws are marked. If `false`, all applicable hand types are marked (default: `true`).
 - `holeCards` (string[] | null, optional): Exactly 2 cards identifying the player's hole cards, both of which must appear in `cards`. Required for the overcard categorizations; without it those properties are always `false` (default: `null`).
+- `villainRange` (string[] | null, optional): Villain hands as exact combos (`'AhKd'`) or shorthand (`'QQ'`, `'AKs'`, `'AKo'`, `'AK'`, `'TT+'`, `'ATs+'`, `'ATo+'`, `'AT+'`). When supplied, each evaluation gets a `villainRange` property; see [Villain Range Blockers](#villain-range-blockers) (default: `null`).
 
 **Returns:**
 - Object mapping sorted hand strings to evaluation objects
@@ -466,7 +472,7 @@ Main function to evaluate poker hands.
 #### Constructor
 
 ```javascript
-new HandEvaluator(cards, strict, holeCards)
+new HandEvaluator(cards, strict, holeCards, villainRange)
 ```
 
 Creates a new HandEvaluator instance.
@@ -475,6 +481,7 @@ Creates a new HandEvaluator instance.
 - `cards` (string[]): Array of 5 or more card strings
 - `strict` (boolean, optional): If `true`, only the strongest made hand and stronger draws are marked. If `false`, all applicable hand types are marked (default: `true`).
 - `holeCards` (string[] | null, optional): Exactly 2 cards identifying the player's hole cards, both of which must appear in `cards`. Required for the overcard categorizations (default: `null`).
+- `villainRange` (string[] | null, optional): Villain hands as exact combos (`'AhKd'`) or shorthand (`'QQ'`, `'AKs'`, `'AKo'`, `'AK'`, `'TT+'`, `'ATs+'`, `'ATo+'`, `'AT+'`). When supplied, each evaluation gets a `villainRange` property; see [Villain Range Blockers](#villain-range-blockers) (default: `null`).
 
 **Properties:**
 - `evaluation` - Object mapping sorted hand strings to evaluation objects (same format as `evaluateHand()` return value)
@@ -482,6 +489,29 @@ Creates a new HandEvaluator instance.
 - `strict` - Boolean indicating whether strict mode is enabled
 - `holeCards` - Array of the 2 hole cards, or `null` if none were supplied
 
+### Villain Range Blockers
+
+Pass a villain range as the fourth argument to see which of its combos the known cards rule out:
+
+```javascript
+const board = ['Kh', '8d', '4c'];
+const holeCards = ['Ah', 'Js'];
+const result = evaluateHand([...board, ...holeCards], true, holeCards, ['AKs', 'QQ', 'JsTs']);
+const { villainRange } = Object.values(result)[0];
+
+villainRange.allBlocks;
+// { unblocked: ['AsKs', 'AdKd', 'AcKc', 'QsQh', 'QsQd', 'QsQc', 'QhQd', 'QhQc', 'QdQc'],
+//   blocked:   ['AhKh', 'JsTs'] }
+```
+
+The result has three views, each `{ unblocked: [], blocked: [] }` of exact combos:
+
+- `boardBlocks` - blocked by a board card (every card in `cards` that is not a hole card)
+- `heroBlocks` - blocked by one of the hole cards
+- `allBlocks` - blocked by any known card; `unblocked` here is what villain can actually hold
+
+Shorthand is expanded to combos, so a partly blocked entry such as `AKs` is split across both lists. Combos are written high rank first (`'AhKd'`, and `'QsQh'` for pairs with suits ordered s, h, d, c), duplicates are removed, and input order is kept. Without `holeCards`, every card is treated as board, so `heroBlocks` blocks nothing. In non-strict mode every combination carries the same `villainRange`. The property is omitted when no range is supplied, and an invalid entry throws.
+
 **Note**: All internal methods are private. Use the `evaluation` property to access evaluation results.
 
 ## Releasing

package/evaluator.js

@@ -36,6 +36,31 @@ const HOLE_CARD_CATEGORIES = new Set([
   'isTwoUndercards'
 ]);
 
+/**
+ * Draw properties. On 6+ cards they describe the whole hand rather than one 5-card combination,
+ * so strict mode collects them from every combination (see #mergeDraws).
+ *
+ * @constant {string[]}
+ */
+const DRAW_PROPERTIES = [
+  'isFlushDraw',
+  'isBackdoorFlushDraw',
+  'isOpenEndedStraightDraw',
+  'isInsideStraightDraw',
+  'isStraightDraw',
+  'isOpenEndedStraightDrawWheel',
+  'isInsideStraightDrawWheel',
+  'isComboDraw'
+];
+
+const STRAIGHT_DRAW_PROPERTIES = [
+  'isOpenEndedStraightDraw',
+  'isInsideStraightDraw',
+  'isStraightDraw',
+  'isOpenEndedStraightDrawWheel',
+  'isInsideStraightDrawWheel'
+];
+
 class HandEvaluator {
   /**
    * Creates an instance of HandEvaluator.
@@ -48,9 +73,14 @@ class HandEvaluator {
    * @param {string[]|null} [holeCards=null] - Optional array of exactly 2 cards identifying the player's
    *   hole cards. Required for the overcard categorizations (isOvercard, isTwoOvercards, etc.); without it
    *   those properties are always false. Both cards must be present in `cards`.
+   * @param {string[]|null} [villainRange=null] - Optional array of villain hands, as exact combos ('AhKd') or
+   *   shorthand ('QQ', 'AKs', 'AKo', 'AK', 'TT+', 'ATs+', 'ATo+', 'AT+'). When supplied, every evaluation
+   *   gets a `villainRange` property listing which combos the known cards block (see #classifyVillainRange).
+   * @param {string[]|null} [originalCards=null] - Internal: the full hand when evaluating one 5-card combination
    * @throws {Error} If cards is not an array, has fewer than 5 cards, contains invalid format,
    *   invalid rank, invalid suit, or duplicate cards
    * @throws {Error} If holeCards is provided but is not an array of exactly 2 distinct cards drawn from `cards`
+   * @throws {Error} If villainRange is provided but is not an array of valid combos or shorthand
    * @example
    * const evaluator = new HandEvaluator(['As', 'Ks', 'Qs', 'Js', 'Ts']);
    * @example
@@ -63,7 +93,7 @@ class HandEvaluator {
    * // With hole cards - enables overcard categorization
    * const withHoleCards = new HandEvaluator(['Ks', 'Qh', '8d', '3c', 'Ad', 'Jh'], true, ['Ad', 'Jh']);
    */
-  constructor(cards, strict = true, holeCards = null, originalCards = null) {
+  constructor(cards, strict = true, holeCards = null, villainRange = null, originalCards = null) {
     this.#validateCards(cards);
     // Copy so that in-place sorting during evaluation never reorders the caller's array
     this.cards = [...cards];
@@ -75,7 +105,117 @@ class HandEvaluator {
       this.#validateHoleCards(holeCards, this.originalCards || cards);
       this.holeCards = holeCards;
     }
+    const villainCombos = villainRange === null || villainRange === undefined ? null : this.#parseVillainRange(villainRange);
     this.evaluation = this.#evaluateAllCombinations();
+    if (villainCombos) {
+      const classification = this.#classifyVillainRange(villainCombos);
+      for (const evaluation of Object.values(this.evaluation)) evaluation.villainRange = classification;
+    }
+  }
+
+  // ==================== VILLAIN RANGE ====================
+
+  /**
+   * Expands a villain range into exact two-card combos, in input order and without duplicates.
+   * Each combo is written high rank first, with suits ordered s, h, d, c for pairs (e.g. 'AhKd', 'QsQh').
+   *
+   * Accepted entries:
+   * - Exact combo: 'AhKd' (either card order)
+   * - Pair: 'QQ' (6 combos); 'TT+' adds every higher pair
+   * - Suited: 'AKs' (4 combos); offsuit: 'AKo' (12 combos); either: 'AK' (16 combos)
+   * - Plus forms keep the first rank and raise the second up to one below it: 'ATs+' is ATs, AJs, AQs, AKs
+   *
+   * @private
+   * @param {string[]} villainRange - Range entries to expand
+   * @returns {string[]} Exact combos
+   * @throws {Error} If villainRange is not an array or an entry is not a valid combo or shorthand
+   */
+  #parseVillainRange(villainRange) {
+    if (!Array.isArray(villainRange)) {
+      throw new Error('Villain range must be an array');
+    }
+    const ranks = 'AKQJT98765432';
+    const suits = 'shdc';
+    const combos = [];
+    const seen = new Set();
+    const add = (first, second) => {
+      // High rank first; for equal ranks, order suits s, h, d, c
+      const order = c => ranks.indexOf(c[0]) * 4 + suits.indexOf(c[1]);
+      const [a, b] = order(first) <= order(second) ? [first, second] : [second, first];
+      if (!seen.has(a + b)) {
+        seen.add(a + b);
+        combos.push(a + b);
+      }
+    };
+    const addRanks = (high, low, type) => {
+      for (const s1 of suits) {
+        for (const s2 of suits) {
+          if (high === low ? suits.indexOf(s2) <= suits.indexOf(s1) : (type === 's' && s1 !== s2) || (type === 'o' && s1 === s2)) continue;
+          add(high + s1, low + s2);
+        }
+      }
+    };
+
+    villainRange.forEach((entry, i) => {
+      const invalid = () => new Error(`Invalid villain range entry at index ${i}: "${entry}"`);
+      if (typeof entry !== 'string') throw invalid();
+
+      const exact = entry.match(/^([AKQJT2-9])([shdc])([AKQJT2-9])([shdc])$/);
+      if (exact) {
+        const [first, second] = [exact[1] + exact[2], exact[3] + exact[4]];
+        if (first === second) throw invalid();
+        add(first, second);
+        return;
+      }
+
+      const shorthand = entry.match(/^([AKQJT2-9])([AKQJT2-9])([so]?)(\+?)$/);
+      if (!shorthand) throw invalid();
+      const [, r1, r2, type, plus] = shorthand;
+      const [high, low] = ranks.indexOf(r1) <= ranks.indexOf(r2) ? [r1, r2] : [r2, r1];
+      if (high === low) {
+        if (type) throw invalid();
+        const lows = plus ? ranks.slice(0, ranks.indexOf(high) + 1) : high;
+        for (const rank of lows) addRanks(rank, rank);
+        return;
+      }
+      const lows = plus ? ranks.slice(ranks.indexOf(high) + 1, ranks.indexOf(low) + 1) : low;
+      for (const rank of lows) addRanks(high, rank, type);
+    });
+    return combos;
+  }
+
+  /**
+   * Splits villain combos by which known cards block them. A combo is blocked when it shares a
+   * card with the blockers, so villain cannot hold it.
+   *
+   * - boardBlocks: blocked by the board (every card that is not a hole card)
+   * - heroBlocks: blocked by the hole cards (always unblocked without hole cards)
+   * - allBlocks: blocked by any known card
+   *
+   * Without hole cards every card passed is treated as board.
+   *
+   * @private
+   * @param {string[]} combos - Exact combos from #parseVillainRange
+   * @returns {{boardBlocks: Object, heroBlocks: Object, allBlocks: Object}} Each with `unblocked` and `blocked` arrays
+   */
+  #classifyVillainRange(combos) {
+    const fullHand = this.originalCards || this.cards;
+    const heroCards = new Set(this.holeCards || []);
+    const boardCards = new Set(fullHand.filter(c => !heroCards.has(c)));
+    const allCards = new Set(fullHand);
+    const split = blockers => {
+      const result = { unblocked: [], blocked: [] };
+      for (const combo of combos) {
+        const isBlocked = blockers.has(combo.slice(0, 2)) || blockers.has(combo.slice(2));
+        result[isBlocked ? 'blocked' : 'unblocked'].push(combo);
+      }
+      return result;
+    };
+    return {
+      boardBlocks: split(boardCards),
+      heroBlocks: split(heroCards),
+      allBlocks: split(allCards)
+    };
   }
 
   /**
@@ -271,7 +411,11 @@ class HandEvaluator {
     this.#isOpenEndedStraightDraw();
     this.#isInsideStraightDraw();
     this.#isStraightDraw();
+    // Always set the wheel flags; the standard draw checks above only evaluate them as a fallback
+    this.#isOpenEndedStraightDrawWheel();
+    this.#isInsideStraightDrawWheel();
     this.#isComboDraw();
+    this.#clearDrawsForStreet();
     this.#isUnderPair();
     this.#isOvercards();
     this.#isHighCard();
@@ -345,9 +489,7 @@ class HandEvaluator {
     
     // Filter draws: made flush or stronger cannot have straight draws
     if (strongest >= 6) {
-      evaluation.isStraightDraw = false;
-      evaluation.isOpenEndedStraightDraw = false;
-      evaluation.isInsideStraightDraw = false;
+      for (const draw of STRAIGHT_DRAW_PROPERTIES) evaluation[draw] = false;
     }
   }
 
@@ -496,12 +638,75 @@ class HandEvaluator {
     const result = {};
     for (const combination of combinations) {
       const key = this.#formatHandKey(combination);
-      const tempEvaluator = new HandEvaluator(combination, this.strict, this.holeCards, this.originalCards);
+      const tempEvaluator = new HandEvaluator(combination, this.strict, this.holeCards, null, this.originalCards);
       const evaluationKey = Object.keys(tempEvaluator.evaluation)[0];
       result[key] = tempEvaluator.evaluation[evaluationKey];
     }
     
-    return this.strict ? this.#findBestCombination(result) : result;
+    if (!this.strict) return result;
+    const best = this.#findBestCombination(result);
+    this.#mergeDraws(Object.values(best)[0], result);
+    return best;
+  }
+
+  /**
+   * Removes draws that can no longer complete, based on how many cards the full hand holds:
+   * 5 cards is the flop (two cards to come), 6 is the turn (one card to come, so a backdoor
+   * draw cannot complete) and 7 or more is the river (no cards to come, so there are no draws).
+   *
+   * @private
+   */
+  #clearDrawsForStreet() {
+    const cardCount = (this.originalCards || this.cards).length;
+    if (cardCount >= 7) {
+      for (const draw of DRAW_PROPERTIES) this.evaluation[draw] = false;
+    } else if (cardCount === 6) {
+      this.evaluation.isBackdoorFlushDraw = false;
+    }
+  }
+
+  /**
+   * In strict mode with 6+ cards only the best 5-card combination is returned, but a draw can
+   * use cards outside it (e.g. the hole card that makes four to a flush). Copies onto the best
+   * evaluation every draw found in any combination, with that combination's key and kicker
+   * cards, then drops draws the made hand already beats and recomputes the combo draw for the
+   * whole hand.
+   *
+   * @private
+   * @param {Object} best - The evaluation of the best combination (modified in place)
+   * @param {Object<string, Object>} result - Evaluations of every combination
+   */
+  #mergeDraws(best, result) {
+    const clear = draw => {
+      best[draw] = false;
+      best.keyCards[draw] = [];
+      best.kickerCards[draw] = [];
+    };
+    for (const draw of DRAW_PROPERTIES) {
+      if (draw === 'isComboDraw' || best[draw]) continue;
+      const source = Object.values(result).find(evaluation => evaluation[draw]);
+      if (!source) continue;
+      best[draw] = true;
+      best.keyCards[draw] = source.keyCards[draw];
+      best.kickerCards[draw] = source.kickerCards[draw];
+    }
+
+    // A made straight or better needs no straight draw; a made flush or better needs no flush draw
+    const strongest = this.#getHandStrength(best);
+    if (strongest >= 5) STRAIGHT_DRAW_PROPERTIES.forEach(clear);
+    if (strongest >= 6) ['isFlushDraw', 'isBackdoorFlushDraw'].forEach(clear);
+
+    if (best.isComboDraw || !(best.isFlushDraw && best.isStraightDraw)) {
+      if (!(best.isFlushDraw && best.isStraightDraw)) clear('isComboDraw');
+      return;
+    }
+    best.isComboDraw = true;
+    const keyCards = [...new Set([...best.keyCards.isFlushDraw, ...best.keyCards.isStraightDraw])]
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+    best.keyCards.isComboDraw = keyCards;
+    best.kickerCards.isComboDraw = this.cards
+      .filter(c => !keyCards.includes(c))
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
   }
 
   /**
@@ -797,6 +1002,8 @@ class HandEvaluator {
     if (this.evaluation.isTopPair !== undefined) return this.evaluation.isTopPair;
     if (this.evaluation.isPair === undefined) this.#isPair();
     if (!this.evaluation.isPair) return this.evaluation.isTopPair = false;
+    const position = this.#getBoardPosition(this.#getPairRank());
+    if (position !== null) return this.evaluation.isTopPair = position === 'top';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isTopPair = rankCounts[this.cards[0].slice(0, -1)] === 2;
   }
@@ -815,6 +1022,8 @@ class HandEvaluator {
     if (this.evaluation.isPair === undefined) this.#isPair();
     if (this.evaluation.isTwoPair === undefined) this.#isTwoPair();
     if (!this.evaluation.isPair || this.evaluation.isTwoPair) return this.evaluation.isMiddlePair = false;
+    const position = this.#getBoardPosition(this.#getPairRank());
+    if (position !== null) return this.evaluation.isMiddlePair = position === 'middle';
     const ranks = this.#getRankCountsSorted();
     return this.evaluation.isMiddlePair = ranks.length === 4 && (ranks[1].count === 2 || ranks[2].count === 2);
   }
@@ -832,6 +1041,8 @@ class HandEvaluator {
     if (this.evaluation.isBottomPair !== undefined) return this.evaluation.isBottomPair;
     if (this.evaluation.isPair === undefined) this.#isPair();
     if (!this.evaluation.isPair) return this.evaluation.isBottomPair = false;
+    const position = this.#getBoardPosition(this.#getPairRank());
+    if (position !== null) return this.evaluation.isBottomPair = position === 'bottom';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isBottomPair = rankCounts[this.cards[this.cards.length - 1].slice(0, -1)] === 2;
   }
@@ -904,6 +1115,8 @@ class HandEvaluator {
     if (this.evaluation.isTopThreeOfAKind !== undefined) return this.evaluation.isTopThreeOfAKind;
     if (this.evaluation.isThreeOfAKind === undefined) this.#isThreeOfAKind();
     if (!this.evaluation.isThreeOfAKind) return this.evaluation.isTopThreeOfAKind = false;
+    const position = this.#getBoardPosition(this.#getTripsRank());
+    if (position !== null) return this.evaluation.isTopThreeOfAKind = position === 'top';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isTopThreeOfAKind = rankCounts[this.cards[0].slice(0, -1)] === 3;
   }
@@ -921,6 +1134,8 @@ class HandEvaluator {
     if (this.evaluation.isMiddleThreeOfAKind !== undefined) return this.evaluation.isMiddleThreeOfAKind;
     if (this.evaluation.isThreeOfAKind === undefined) this.#isThreeOfAKind();
     if (!this.evaluation.isThreeOfAKind) return this.evaluation.isMiddleThreeOfAKind = false;
+    const position = this.#getBoardPosition(this.#getTripsRank());
+    if (position !== null) return this.evaluation.isMiddleThreeOfAKind = position === 'middle';
     const ranks = this.#getRankCountsSorted();
     return this.evaluation.isMiddleThreeOfAKind = ranks.length === 3 && ranks[1].count === 3;
   }
@@ -938,6 +1153,8 @@ class HandEvaluator {
     if (this.evaluation.isBottomThreeOfAKind !== undefined) return this.evaluation.isBottomThreeOfAKind;
     if (this.evaluation.isThreeOfAKind === undefined) this.#isThreeOfAKind();
     if (!this.evaluation.isThreeOfAKind) return this.evaluation.isBottomThreeOfAKind = false;
+    const position = this.#getBoardPosition(this.#getTripsRank());
+    if (position !== null) return this.evaluation.isBottomThreeOfAKind = position === 'bottom';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isBottomThreeOfAKind = rankCounts[this.cards[this.cards.length - 1].slice(0, -1)] === 3;
   }
@@ -1851,6 +2068,42 @@ class HandEvaluator {
     }
     return null;
   }
+
+  /**
+   * Gets the rank of the three of a kind in the current hand.
+   *
+   * @private
+   * @returns {string|null} The rank of the three of a kind, or null if none exists
+   */
+  #getTripsRank() {
+    const rankCounts = this.#getRankCounts();
+    return Object.keys(rankCounts).find(rank => rankCounts[rank] === 3) || null;
+  }
+
+  /**
+   * Classifies a paired (or tripled) rank against the whole board, including board cards outside
+   * the current 5-card combination. Requires hole cards: without them the board is unknown and
+   * positions fall back to the 5-card combination.
+   *
+   * - 'top': the rank is at or above the highest board card (top pair, or a pocket pair above the board)
+   * - 'bottom': the rank is at or below the lowest board card
+   * - 'middle': anything in between
+   * - 'none': no hole card has this rank, so the pair or trips belongs to the board
+   *
+   * @private
+   * @param {string|null} rank - The rank to classify
+   * @returns {string|null} The position, or null if no hole cards were supplied
+   */
+  #getBoardPosition(rank) {
+    if (!this.holeCards) return null;
+    if (!rank || !this.holeCards.some(c => c.slice(0, -1) === rank)) return 'none';
+    const fullHand = this.originalCards || this.cards;
+    const boardValues = fullHand.filter(c => !this.holeCards.includes(c)).map(c => this.#getRankValue(c));
+    const value = this.#getRankValue(rank + 's');
+    if (value >= Math.max(...boardValues)) return 'top';
+    if (value <= Math.min(...boardValues)) return 'bottom';
+    return 'middle';
+  }
   
   // ==================== OVERCARDS ====================
 
@@ -1974,10 +2227,13 @@ class HandEvaluator {
  *   Required for the overcard categorizations (isOvercard, isTwoOvercards, isOvercardAndMiddleCard,
  *   isOvercardAndUndercard, isTwoMiddleCards, isMiddleAndUndercard, isTwoUndercards); without it those
  *   properties are always false. Both cards must be present in `cards`.
+ * @param {string[]|null} [villainRange=null] - Optional villain hands as exact combos ('AhKd') or shorthand
+ *   ('QQ', 'AKs', 'AKo', 'AK', 'TT+', 'ATs+'). When supplied, each evaluation includes
+ *   `villainRange: { boardBlocks, heroBlocks, allBlocks }`, each `{ unblocked: [], blocked: [] }` of exact combos.
  * @returns {Object} Object mapping sorted hand strings (e.g., "As, Ks, Qs, Js, Ts") to evaluation objects with boolean fields for all hand types and draws
  */
-function evaluateHand(cards, strict = true, holeCards = null) {
-  const evaluator = new HandEvaluator(cards, strict, holeCards);
+function evaluateHand(cards, strict = true, holeCards = null, villainRange = null) {
+  const evaluator = new HandEvaluator(cards, strict, holeCards, villainRange);
   return evaluator.evaluation;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poker-extval",
-  "version": "3.3.3",
+  "version": "3.4.0",
   "description": "Poker hand evaluator with comprehensive test suite",
   "main": "evaluator.js",
   "files": [