@block52/poker-vm-sdk 1.12.0 → 1.12.1

package/dist/index.d.ts

@@ -46220,7 +46220,11 @@ declare class PokerSolver {
     /**
      * Evaluate a 5-card poker hand
      */
-    private static evaluateHand;
+    /**
+     * Evaluate exactly 5 cards (a winner's best hand, WinnerDTO.cards). Use
+     * findBestHand for 7.
+     */
+    static evaluateHand(cards: Card[]): HandEvaluation;
     /**
      * Check if cards form a straight (excluding low straight A-2-3-4-5)
      */
@@ -46490,11 +46494,47 @@ declare class PokerGameIntegration {
         hand2Evaluation: HandEvaluation;
     };
     /**
-     * Create a formatted hand description for UI display
+     * The winning hand in words, from the winner's best five cards
+     * (WinnerDTO.cards) and the board (communityCards): "Full House, Eights
+     * over Sevens", "Diamond Flush, Six high", "Set of Sevens". The board tells
+     * a set (pocket pair plus one on the board) from trips (one hole card plus a
+     * board pair, or all three on the board), which the five cards alone can't.
+     * @param cards The winner's five card mnemonics ("6D")
+     * @param board The community cards
+     * @returns The hand in words, or "" for an uncontested pot (no cards)
+     */
+    static describeWinningHand(cards: string[] | undefined, board: string[]): string;
+    /**
+     * Fill in each winner's name and description from its cards and the board.
+     * The engine no longer writes the hand's wording into chain state
+     * (poker-vm#2721), so callers run game state through this as it arrives and
+     * keep reading winner.name / winner.description as before.
+     *
+     * A winner with five cards gets "Full House, Eights over Sevens" in both
+     * fields. A winner without five cards (an uncontested pot, or an older state
+     * that recorded hole cards) is returned unchanged.
+     *
+     * Returns a new state object; the input is not modified.
+     * @param state Any game state with winners and community cards
+     */
+    static withWinnerDescriptions<T extends {
+        winners: WinnerDTO[];
+        communityCards: string[];
+    }>(state: T): T;
+    /**
+     * The hand description in words: "Full House, Eights over Sevens", "Quad
+     * Fours", "Diamond Flush, Six high", "Ace high". A flush names its suit from
+     * the best hand. The rank and suit words mirror @block52/deck's rankName /
+     * suitName.
      * @param evaluation Hand evaluation result
      * @returns Human-readable hand description
      */
     static formatHandDescription(evaluation: HandEvaluation): string;
+    private static readonly RANK_WORDS;
+    /** A high-ace rank spelled out ("Ace", "Ten"); plural gives "Aces", "Sixes". */
+    private static rankWord;
+    /** The suit word every card of a flush shares ("Diamond"), or "" when the hand is empty or mixed. */
+    private static flushSuitWord;
     /**
      * Example usage with string cards (for testing/debugging)
      * @param playerCardStrings Array of player hands as mnemonic strings

package/dist/index.esm.js

@@ -57114,6 +57114,10 @@ class PokerSolver {
     /**
      * Evaluate a 5-card poker hand
      */
+    /**
+     * Evaluate exactly 5 cards (a winner's best hand, WinnerDTO.cards). Use
+     * findBestHand for 7.
+     */
     static evaluateHand(cards) {
         if (cards.length !== 5) {
             throw new Error("Hand evaluation requires exactly 5 cards");
@@ -58191,37 +58195,116 @@ class PokerGameIntegration {
         };
     }
     /**
-     * Create a formatted hand description for UI display
+     * The winning hand in words, from the winner's best five cards
+     * (WinnerDTO.cards) and the board (communityCards): "Full House, Eights
+     * over Sevens", "Diamond Flush, Six high", "Set of Sevens". The board tells
+     * a set (pocket pair plus one on the board) from trips (one hole card plus a
+     * board pair, or all three on the board), which the five cards alone can't.
+     * @param cards The winner's five card mnemonics ("6D")
+     * @param board The community cards
+     * @returns The hand in words, or "" for an uncontested pot (no cards)
+     */
+    static describeWinningHand(cards, board) {
+        if (!cards || cards.length === 0)
+            return "";
+        if (cards.length !== 5) {
+            throw new Error(`describeWinningHand expects the winning five cards, got ${cards.length}`);
+        }
+        const evaluation = PokerSolver.evaluateHand(cards.map(c => Deck.fromString(c)));
+        if (evaluation.handType === HandType.THREE_OF_A_KIND) {
+            const tripRank = evaluation.rankValues[0];
+            const onBoard = board.map(c => Deck.fromString(c)).filter(c => (c.rank === 1 ? 14 : c.rank) === tripRank).length;
+            if (onBoard === 1)
+                return `Set of ${this.rankWord(tripRank, true)}`;
+        }
+        return this.formatHandDescription(evaluation);
+    }
+    /**
+     * Fill in each winner's name and description from its cards and the board.
+     * The engine no longer writes the hand's wording into chain state
+     * (poker-vm#2721), so callers run game state through this as it arrives and
+     * keep reading winner.name / winner.description as before.
+     *
+     * A winner with five cards gets "Full House, Eights over Sevens" in both
+     * fields. A winner without five cards (an uncontested pot, or an older state
+     * that recorded hole cards) is returned unchanged.
+     *
+     * Returns a new state object; the input is not modified.
+     * @param state Any game state with winners and community cards
+     */
+    static withWinnerDescriptions(state) {
+        const winners = state.winners.map(winner => {
+            if (!winner.cards || winner.cards.length !== 5)
+                return winner;
+            const description = this.describeWinningHand(winner.cards, state.communityCards);
+            return { ...winner, name: description, description };
+        });
+        return { ...state, winners };
+    }
+    /**
+     * The hand description in words: "Full House, Eights over Sevens", "Quad
+     * Fours", "Diamond Flush, Six high", "Ace high". A flush names its suit from
+     * the best hand. The rank and suit words mirror @block52/deck's rankName /
+     * suitName.
      * @param evaluation Hand evaluation result
      * @returns Human-readable hand description
      */
     static formatHandDescription(evaluation) {
-        const { handType, rankValues, description } = evaluation;
+        const { handType, rankValues, description, bestHand } = evaluation;
+        const suit = this.flushSuitWord(bestHand);
+        const suited = (hand) => (suit ? `${suit} ${hand}` : hand);
         switch (handType) {
             case HandType.ROYAL_FLUSH:
-                return "Royal Flush";
+                return suit ? `Royal Flush in ${suit}s` : "Royal Flush";
             case HandType.STRAIGHT_FLUSH:
-                return `Straight Flush, ${PokerSolver.formatRank(rankValues[0])} high`;
+                return `${suited("Straight Flush")}, ${this.rankWord(rankValues[0])} high`;
             case HandType.FOUR_OF_A_KIND:
-                return `Four ${PokerSolver.formatRank(rankValues[0])}s`;
+                return `Quad ${this.rankWord(rankValues[0], true)}`;
             case HandType.FULL_HOUSE:
-                return `Full House, ${PokerSolver.formatRank(rankValues[0])}s over ${PokerSolver.formatRank(rankValues[1])}s`;
+                return `Full House, ${this.rankWord(rankValues[0], true)} over ${this.rankWord(rankValues[1], true)}`;
             case HandType.FLUSH:
-                return `Flush, ${PokerSolver.formatRank(rankValues[0])} high`;
+                return `${suited("Flush")}, ${this.rankWord(rankValues[0])} high`;
             case HandType.STRAIGHT:
-                return `Straight, ${PokerSolver.formatRank(rankValues[0])} high`;
+                return `Straight, ${this.rankWord(rankValues[0])} high`;
             case HandType.THREE_OF_A_KIND:
-                return `Three ${PokerSolver.formatRank(rankValues[0])}s`;
+                return `Trip ${this.rankWord(rankValues[0], true)}`;
             case HandType.TWO_PAIR:
-                return `Two Pair, ${PokerSolver.formatRank(rankValues[0])}s and ${PokerSolver.formatRank(rankValues[1])}s`;
+                return `Two Pair, ${this.rankWord(rankValues[0], true)} and ${this.rankWord(rankValues[1], true)}`;
             case HandType.PAIR:
-                return `Pair of ${PokerSolver.formatRank(rankValues[0])}s`;
+                return `Pair of ${this.rankWord(rankValues[0], true)}`;
             case HandType.HIGH_CARD:
-                return `${PokerSolver.formatRank(rankValues[0])} high`;
+                return `${this.rankWord(rankValues[0])} high`;
             default:
                 return description;
         }
     }
+    /** A high-ace rank spelled out ("Ace", "Ten"); plural gives "Aces", "Sixes". */
+    static rankWord(rank, plural = false) {
+        const words = this.RANK_WORDS[rank === 1 ? 14 : rank];
+        if (!words)
+            return plural ? `${PokerSolver.formatRank(rank)}s` : PokerSolver.formatRank(rank);
+        return plural ? words[1] : words[0];
+    }
+    /** The suit word every card of a flush shares ("Diamond"), or "" when the hand is empty or mixed. */
+    static flushSuitWord(cards) {
+        if (!cards || cards.length === 0)
+            return "";
+        const suit = cards[0].suit;
+        if (cards.some(c => c.suit !== suit))
+            return "";
+        switch (suit) {
+            case SUIT.CLUBS:
+                return "Club";
+            case SUIT.DIAMONDS:
+                return "Diamond";
+            case SUIT.HEARTS:
+                return "Heart";
+            case SUIT.SPADES:
+                return "Spade";
+            default:
+                return "";
+        }
+    }
     /**
      * Example usage with string cards (for testing/debugging)
      * @param playerCardStrings Array of player hands as mnemonic strings
@@ -58242,6 +58325,21 @@ class PokerGameIntegration {
         return { winners, results };
     }
 }
+PokerGameIntegration.RANK_WORDS = {
+    14: ["Ace", "Aces"],
+    13: ["King", "Kings"],
+    12: ["Queen", "Queens"],
+    11: ["Jack", "Jacks"],
+    10: ["Ten", "Tens"],
+    9: ["Nine", "Nines"],
+    8: ["Eight", "Eights"],
+    7: ["Seven", "Sevens"],
+    6: ["Six", "Sixes"],
+    5: ["Five", "Fives"],
+    4: ["Four", "Fours"],
+    3: ["Three", "Threes"],
+    2: ["Two", "Twos"]
+};
 // Example usage:
 /*
 const example = PokerGameIntegration.exampleShowdown([