@block52/poker-vm-sdk 1.10.0 → 1.12.1

package/dist/index.esm.js

@@ -2847,6 +2847,7 @@ function createBaseMsgCreateGame() {
         name: "",
         bettingLimit: "",
         startTime: Long.ZERO,
+        blindStructure: "",
     };
 }
 const MsgCreateGame = {
@@ -2911,6 +2912,9 @@ const MsgCreateGame = {
         if (!message.startTime.equals(Long.ZERO)) {
             writer.uint32(168).int64(message.startTime.toString());
         }
+        if (message.blindStructure !== "") {
+            writer.uint32(178).string(message.blindStructure);
+        }
         return writer;
     },
     decode(input, length) {
@@ -3060,6 +3064,13 @@ const MsgCreateGame = {
                     message.startTime = Long.fromString(reader.int64().toString());
                     continue;
                 }
+                case 22: {
+                    if (tag !== 178) {
+                        break;
+                    }
+                    message.blindStructure = reader.string();
+                    continue;
+                }
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -3090,6 +3101,7 @@ const MsgCreateGame = {
             name: isSet$2b(object.name) ? globalThis.String(object.name) : "",
             bettingLimit: isSet$2b(object.bettingLimit) ? globalThis.String(object.bettingLimit) : "",
             startTime: isSet$2b(object.startTime) ? Long.fromValue(object.startTime) : Long.ZERO,
+            blindStructure: isSet$2b(object.blindStructure) ? globalThis.String(object.blindStructure) : "",
         };
     },
     toJSON(message) {
@@ -3154,6 +3166,9 @@ const MsgCreateGame = {
         if (!message.startTime.equals(Long.ZERO)) {
             obj.startTime = (message.startTime || Long.ZERO).toString();
         }
+        if (message.blindStructure !== "") {
+            obj.blindStructure = message.blindStructure;
+        }
         return obj;
     },
     create(base) {
@@ -3202,6 +3217,7 @@ const MsgCreateGame = {
         message.startTime = (object.startTime !== undefined && object.startTime !== null)
             ? Long.fromValue(object.startTime)
             : Long.ZERO;
+        message.blindStructure = object.blindStructure ?? "";
         message.entryFee = (object.entryFee !== undefined && object.entryFee !== null)
             ? Long.fromValue(object.entryFee)
             : Long.UZERO;
@@ -56601,6 +56617,451 @@ const isValidPlayerAddress = (address) => {
     return !isEmptyAddress(address);
 };
 
+/**
+ * The text form of blind structures (poker-vm#1734's "SPL", decided on #2613 /
+ * #2713): a human-readable notation over the typed `BlindStructureDTO`, which
+ * stays canonical in the engine and on chain. These two functions are the only
+ * conversion (Commandment 12); no parser runs inside consensus code.
+ *
+ *   BLINDS turbo                                  a preset, no block
+ *
+ *   BLINDS custom {                               algorithmic
+ *     start: 25/50
+ *     duration: 5m
+ *     progression: double | linear 25 | percentage 1.5
+ *     round: 25                                   percentage only (the engine's roundTo)
+ *     ante: bb | bb * 0.1 | level >= 4 ? bb * 0.1 : 0
+ *     cap: 15
+ *   }
+ *
+ *   BLINDS wsop_main {                            table
+ *     duration: 120m                              default for rows without their own
+ *     ante: bb                                    rule applied per row unless the row gives an amount
+ *     levels {
+ *       0: 100/200
+ *       1: 200/300 ante 300 duration 90m
+ *       2: break 20m
+ *     }
+ *   }
+ *
+ * Fields may share a line, separated by spaces. `#` starts a comment. Level
+ * numbers are the engine's 0-based levels everywhere (`levels` rows, `cap`,
+ * `level >=`): a table row's position is its level in the engine, so rows run
+ * 0, 1, 2… without gaps. Amounts are chip-unit integers; `ante` multipliers
+ * and `percentage` factors have at most four decimals (basis points).
+ * `parseBlindStructure(formatBlindStructure(x))` deep-equals `x`.
+ */
+const BPS = 10000n;
+const IDENT = /^[A-Za-z_][\w-]*$/;
+const FIELD_KEY = /^([A-Za-z_]\w*):$/;
+const ROW_KEY = /^(\d+):$/;
+function fail(message) {
+    throw new Error(`blind structure: ${message}`);
+}
+function tokenize(text) {
+    const noComments = text
+        .split("\n")
+        .map(line => line.replace(/#.*$/, ""))
+        .join("\n");
+    return noComments
+        .replace(/\{/g, " { ")
+        .replace(/\}/g, " } ")
+        .split(/\s+/)
+        .filter(t => t.length > 0);
+}
+function parseAmount(what, s) {
+    if (!/^\d+$/.test(s))
+        fail(`${what} must be a whole number of chips, got "${s}"`);
+    return BigInt(s).toString();
+}
+function parseMinutes(what, s) {
+    const m = /^(\d+)(m|h)$/.exec(s);
+    if (!m)
+        fail(`${what} must be a duration like 5m or 2h, got "${s}"`);
+    const n = Number(m[1]) * (m[2] === "h" ? 60 : 1);
+    if (n <= 0)
+        fail(`${what} must be positive`);
+    return n;
+}
+function parseInteger(what, s) {
+    if (!/^\d+$/.test(s) || !Number.isSafeInteger(Number(s)))
+        fail(`${what} must be a whole number, got "${s}"`);
+    return Number(s);
+}
+/** "1.5" → 15000, "0.125" → 1250 (exact; at most four decimals). */
+function parseBps(what, s) {
+    const m = /^(\d+)(?:\.(\d{1,4}))?$/.exec(s);
+    if (!m)
+        fail(`${what} must be a decimal with at most four places, got "${s}"`);
+    return Number(m[1]) * 10000 + Number((m[2] ?? "").padEnd(4, "0"));
+}
+function formatBps(bps) {
+    const whole = Math.floor(bps / 10000);
+    const frac = String(bps % 10000).padStart(4, "0").replace(/0+$/, "");
+    return frac === "" ? String(whole) : `${whole}.${frac}`;
+}
+function parseAnteRule(expr) {
+    const text = expr.replace(/\s+/g, " ").trim();
+    if (text === "0")
+        return undefined;
+    const conditional = /^level >= (\d+) \? (.+) : 0$/.exec(text);
+    const startLevel = conditional ? parseInteger("ante start level", conditional[1]) : 0;
+    const multiplier = (conditional ? conditional[2] : text).replace(/\s+/g, "");
+    if (multiplier === "bb")
+        return { startLevel, bps: 10000 };
+    const m = /^bb\*(\d+(?:\.\d+)?)$/.exec(multiplier);
+    if (!m)
+        fail(`ante must be "bb", "bb * <fraction>" or "level >= N ? bb * <fraction> : 0", got "${expr}"`);
+    const bps = parseBps("ante fraction", m[1]);
+    if (bps <= 0 || bps > 10000)
+        fail(`ante fraction must be within 0..1, got "${m[1]}"`);
+    return { startLevel, bps };
+}
+function formatAnteRule(rule) {
+    const multiplier = rule.bps === 10000 ? "bb" : `bb * ${formatBps(rule.bps)}`;
+    return rule.startLevel > 0 ? `level >= ${rule.startLevel} ? ${multiplier} : 0` : multiplier;
+}
+function anteFor(bigBlind, rule, level) {
+    if (!rule || level < rule.startLevel)
+        return "0";
+    return ((BigInt(bigBlind) * BigInt(rule.bps)) / BPS).toString();
+}
+/** Splits the block body into `key:` fields (value = the tokens up to the next key) and the `levels { … }` rows. */
+function readBody(toks) {
+    const fields = new Map();
+    let rows;
+    let i = 0;
+    while (i < toks.length) {
+        const tok = toks[i];
+        if (tok === "levels") {
+            if (toks[i + 1] !== "{")
+                fail("levels must be followed by { … }");
+            if (rows)
+                fail("levels given twice");
+            rows = new Map();
+            i += 2;
+            let current;
+            for (; i < toks.length && toks[i] !== "}"; i++) {
+                const row = ROW_KEY.exec(toks[i]);
+                if (row) {
+                    current = Number(row[1]);
+                    if (rows.has(current))
+                        fail(`level ${current} given twice`);
+                    rows.set(current, []);
+                }
+                else if (current === undefined) {
+                    fail(`expected a level number like "0:" before "${toks[i]}"`);
+                }
+                else {
+                    rows.get(current).push(toks[i]);
+                }
+            }
+            if (i >= toks.length)
+                fail("levels block is not closed");
+            i++;
+            continue;
+        }
+        const key = FIELD_KEY.exec(tok);
+        if (!key)
+            fail(`expected a field like "start:" but found "${tok}"`);
+        if (fields.has(key[1]))
+            fail(`${key[1]} given twice`);
+        const value = [];
+        for (i++; i < toks.length && !FIELD_KEY.test(toks[i]) && toks[i] !== "levels"; i++)
+            value.push(toks[i]);
+        if (value.length === 0)
+            fail(`${key[1]} has no value`);
+        fields.set(key[1], value);
+    }
+    return { fields, rows };
+}
+const ALGORITHMIC_FIELDS = new Set(["start", "duration", "progression", "round", "ante", "cap"]);
+const TABLE_FIELDS = new Set(["duration", "ante", "cap"]);
+function parseRow(level, toks, defaults) {
+    if (toks[0] === "break") {
+        if (toks.length !== 2)
+            fail(`level ${level}: a break is "break <duration>"`);
+        return { level, smallBlind: "", bigBlind: "", ante: "", durationMinutes: parseMinutes(`level ${level} break`, toks[1]), isBreak: true };
+    }
+    const blinds = /^(\d+)\/(\d+)$/.exec(toks[0] ?? "");
+    if (!blinds)
+        fail(`level ${level}: expected "<sb>/<bb>" or "break <duration>", got "${toks.join(" ")}"`);
+    const smallBlind = parseAmount(`level ${level} small blind`, blinds[1]);
+    const bigBlind = parseAmount(`level ${level} big blind`, blinds[2]);
+    if (BigInt(smallBlind) <= 0n || BigInt(bigBlind) < BigInt(smallBlind)) {
+        fail(`level ${level}: blinds must be positive with the big blind at least the small blind`);
+    }
+    let ante;
+    let durationMinutes;
+    for (let i = 1; i < toks.length; i += 2) {
+        const value = toks[i + 1];
+        if (value === undefined)
+            fail(`level ${level}: "${toks[i]}" needs a value`);
+        if (toks[i] === "ante") {
+            if (ante !== undefined)
+                fail(`level ${level}: ante given twice`);
+            ante = parseAmount(`level ${level} ante`, value);
+        }
+        else if (toks[i] === "duration") {
+            if (durationMinutes !== undefined)
+                fail(`level ${level}: duration given twice`);
+            durationMinutes = parseMinutes(`level ${level} duration`, value);
+        }
+        else {
+            fail(`level ${level}: unknown row option "${toks[i]}" (ante or duration)`);
+        }
+    }
+    if (durationMinutes === undefined)
+        durationMinutes = defaults.duration;
+    if (durationMinutes === undefined)
+        fail(`level ${level} has no duration and the structure sets no default "duration:"`);
+    return { level, smallBlind, bigBlind, ante: ante ?? anteFor(bigBlind, defaults.ante, level), durationMinutes, isBreak: false };
+}
+function parseTable(body) {
+    for (const key of body.fields.keys()) {
+        if (!TABLE_FIELDS.has(key))
+            fail(`"${key}" is not a table-mode field (a table takes its blinds from levels)`);
+    }
+    const defaults = {
+        duration: body.fields.has("duration") ? parseMinutes("duration", body.fields.get("duration").join(" ")) : undefined,
+        ante: body.fields.has("ante") ? parseAnteRule(body.fields.get("ante").join(" ")) : undefined
+    };
+    const rows = body.rows;
+    if (rows.size === 0)
+        fail("levels has no rows");
+    const levels = [];
+    const numbers = [...rows.keys()];
+    numbers.forEach((n, i) => {
+        if (n !== i)
+            fail(`levels must run 0, 1, 2… in order (0-based, as the engine numbers them); found level ${n} at position ${i}`);
+        levels.push(parseRow(n, rows.get(n), defaults));
+    });
+    if (levels[0].isBreak)
+        fail("the first level must not be a break");
+    if (levels[levels.length - 1].isBreak)
+        fail("the last level must not be a break (it repeats once the schedule runs out)");
+    const out = { progression: "table", levels };
+    if (body.fields.has("cap"))
+        out.maxLevel = parseInteger("cap", body.fields.get("cap").join(" "));
+    return out;
+}
+function parseAlgorithmic(body) {
+    const f = body.fields;
+    for (const key of f.keys()) {
+        if (!ALGORITHMIC_FIELDS.has(key))
+            fail(`unknown field "${key}" (start, duration, progression, round, ante, cap, levels)`);
+    }
+    for (const required of ["start", "duration", "progression"]) {
+        if (!f.has(required))
+            fail(`${required} is required (or give levels { … } for a table)`);
+    }
+    const start = /^(\d+)\/(\d+)$/.exec(f.get("start").join(""));
+    if (!start)
+        fail(`start must be "<sb>/<bb>", got "${f.get("start").join(" ")}"`);
+    const startSmallBlind = parseAmount("start small blind", start[1]);
+    const startBigBlind = parseAmount("start big blind", start[2]);
+    if (BigInt(startSmallBlind) <= 0n || BigInt(startBigBlind) !== 2n * BigInt(startSmallBlind)) {
+        fail(`opening blinds ${startSmallBlind}/${startBigBlind}: the algorithmic progressions need a positive small blind and big blind = 2 × small blind`);
+    }
+    const base = {
+        startSmallBlind,
+        startBigBlind,
+        durationMinutes: parseMinutes("duration", f.get("duration").join(" ")),
+        ...(f.has("cap") ? { maxLevel: parseInteger("cap", f.get("cap").join(" ")) } : {}),
+        ...(f.has("ante") ? (() => { const ante = parseAnteRule(f.get("ante").join(" ")); return ante ? { ante } : {}; })() : {})
+    };
+    const [kind, ...rest] = f.get("progression");
+    switch (kind) {
+        case "double":
+            if (rest.length !== 0 || f.has("round"))
+                fail("double takes no argument and no round");
+            return { progression: "double", ...base };
+        case "linear": {
+            if (rest.length !== 1 || f.has("round"))
+                fail('linear needs one step, e.g. "linear 25", and no round');
+            const step = parseAmount("linear step", rest[0]);
+            if (BigInt(step) <= 0n)
+                fail("linear step must be positive");
+            return { progression: "linear", ...base, step };
+        }
+        case "percentage": {
+            if (rest.length !== 1)
+                fail('percentage needs one factor, e.g. "percentage 1.5"');
+            const factorBps = parseBps("percentage factor", rest[0]);
+            if (factorBps <= 10000)
+                fail(`percentage factor must exceed 1, got "${rest[0]}"`);
+            if (!f.has("round"))
+                fail('percentage needs "round: <chips>" (the engine rounds each level to a multiple of it)');
+            const roundTo = parseAmount("round", f.get("round").join(" "));
+            if (BigInt(roundTo) <= 0n)
+                fail("round must be positive");
+            return { progression: "percentage", ...base, factorBps, roundTo };
+        }
+        default:
+            fail(`progression must be double, "linear <step>" or "percentage <factor>", got "${[kind, ...rest].join(" ")}"`);
+    }
+}
+/**
+ * Parses the text form into the typed structure. Throws on anything the
+ * engine would refuse that can be seen without expanding levels; the engine
+ * validates the result again on load.
+ */
+function parseBlindStructure(text) {
+    const toks = tokenize(text);
+    if (toks[0] !== "BLINDS")
+        fail('must start with "BLINDS <name>"');
+    const name = toks[1];
+    if (name === undefined || !IDENT.test(name))
+        fail(`"BLINDS" needs a name, got "${name ?? ""}"`);
+    if (toks.length === 2) {
+        if (!BLIND_PRESETS.includes(name)) {
+            fail(`"${name}" is not a preset (${BLIND_PRESETS.join(", ")}); a custom structure needs a { … } block`);
+        }
+        return { preset: name };
+    }
+    if (toks[2] !== "{" || toks[toks.length - 1] !== "}")
+        fail("the structure must be a { … } block after the name");
+    if (BLIND_PRESETS.includes(name))
+        fail(`"${name}" is a preset and takes no block`);
+    const body = readBody(toks.slice(3, -1));
+    return body.rows ? parseTable(body) : parseAlgorithmic(body);
+}
+/**
+ * The inverse of parseBlindStructure. A preset formats as `BLINDS <preset>`;
+ * anything else as a block under `name` (default "custom").
+ */
+function formatBlindStructure(structure, name = "custom") {
+    if ("preset" in structure)
+        return `BLINDS ${structure.preset}`;
+    if (!IDENT.test(name) || BLIND_PRESETS.includes(name))
+        fail(`"${name}" is not a usable structure name`);
+    const lines = [];
+    if (structure.progression === "table") {
+        lines.push("  levels {");
+        for (const l of structure.levels) {
+            if (l.isBreak) {
+                lines.push(`    ${l.level}: break ${l.durationMinutes}m`);
+            }
+            else {
+                const ante = l.ante !== "0" ? ` ante ${l.ante}` : "";
+                lines.push(`    ${l.level}: ${l.smallBlind}/${l.bigBlind}${ante} duration ${l.durationMinutes}m`);
+            }
+        }
+        lines.push("  }");
+    }
+    else {
+        lines.push(`  start: ${structure.startSmallBlind}/${structure.startBigBlind}`);
+        lines.push(`  duration: ${structure.durationMinutes}m`);
+        switch (structure.progression) {
+            case "double":
+                lines.push("  progression: double");
+                break;
+            case "linear":
+                lines.push(`  progression: linear ${structure.step}`);
+                break;
+            case "percentage":
+                lines.push(`  progression: percentage ${formatBps(structure.factorBps)}`);
+                lines.push(`  round: ${structure.roundTo}`);
+                break;
+        }
+        if (structure.ante)
+            lines.push(`  ante: ${formatAnteRule(structure.ante)}`);
+    }
+    if (structure.maxLevel !== undefined)
+        lines.push(`  cap: ${structure.maxLevel}`);
+    return [`BLINDS ${name} {`, ...lines, "}"].join("\n");
+}
+// --- Level expansion (poker-vm#2718) --------------------------------------
+//
+// A TypeScript port of the engine's ExpandLevel (pvm/go/engine/tournament_blinds.go),
+// integer-exact with BigInt, so a create-form preview or a table's "Blinds"
+// panel shows exactly the levels the engine will play. Pinned against the
+// engine's own expansions in blindStructure.test.ts.
+/**
+ * #1734's preset library, as the engine resolves it (pvm/go/engine
+ * tournament_blinds.go blindPresets). The engine resolves a preset on the
+ * table's first action; `resolveBlindPreset` does the same client-side so the
+ * levels can be previewed before the table exists.
+ */
+const BLIND_PRESET_STRUCTURES = {
+    turbo: { progression: "double", startSmallBlind: "25", startBigBlind: "50", durationMinutes: 5, ante: { startLevel: 4, bps: 1000 } },
+    standard: { progression: "double", startSmallBlind: "25", startBigBlind: "50", durationMinutes: 10, ante: { startLevel: 5, bps: 1000 } },
+    deep_stack: {
+        progression: "percentage",
+        startSmallBlind: "25",
+        startBigBlind: "50",
+        factorBps: 15000,
+        roundTo: "25",
+        durationMinutes: 15,
+        ante: { startLevel: 6, bps: 1250 }
+    },
+    hyper_turbo: { progression: "double", startSmallBlind: "50", startBigBlind: "100", durationMinutes: 3, ante: { startLevel: 3, bps: 1000 } }
+};
+/** Replaces a preset with its concrete structure (a deep copy); anything else is returned as is. */
+function resolveBlindPreset(structure) {
+    if (!("preset" in structure))
+        return structure;
+    const preset = BLIND_PRESET_STRUCTURES[structure.preset];
+    if (!preset)
+        fail(`"${structure.preset}" is not a preset (${BLIND_PRESETS.join(", ")})`);
+    return JSON.parse(JSON.stringify(preset));
+}
+function algorithmicSmallBlind(structure, n) {
+    const sb0 = BigInt(structure.startSmallBlind);
+    switch (structure.progression) {
+        case "double":
+            return sb0 << BigInt(n);
+        case "linear":
+            return sb0 + BigInt(structure.step) * BigInt(n);
+        case "percentage": {
+            const roundTo = BigInt(structure.roundTo);
+            const factor = BigInt(structure.factorBps);
+            let sb = sb0;
+            for (let i = 0; i < n; i++) {
+                const raw = (sb * factor) / BPS;
+                let q = raw / roundTo;
+                const r = raw % roundTo;
+                if (r * 2n >= roundTo)
+                    q += 1n;
+                let rounded = q * roundTo;
+                const floor = sb + roundTo;
+                if (rounded < floor)
+                    rounded = floor;
+                sb = rounded;
+            }
+            return sb;
+        }
+    }
+}
+/**
+ * Level n (0-based) of a structure, exactly as the engine expands it: the cap
+ * (`maxLevel`) freezes the blinds while the level number keeps counting; a
+ * table schedule repeats its last row once it runs out; the ante rule applies
+ * from its start level. A preset must be resolved first (`resolveBlindPreset`).
+ */
+function expandBlindLevel(structure, n) {
+    if (!Number.isInteger(n) || n < 0)
+        fail(`blind level ${n} must be a non-negative integer`);
+    if ("preset" in structure)
+        fail(`resolve the "${structure.preset}" preset before expanding it (resolveBlindPreset)`);
+    const m = structure.maxLevel !== undefined && n > structure.maxLevel ? structure.maxLevel : n;
+    if (structure.progression === "table") {
+        const rows = structure.levels;
+        if (rows.length === 0)
+            fail("a table structure needs at least one level");
+        const row = { ...rows[Math.min(m, rows.length - 1)] };
+        row.level = n;
+        row.durationMinutes = n >= rows.length ? rows[rows.length - 1].durationMinutes : rows[n].durationMinutes;
+        return row;
+    }
+    const sb = algorithmicSmallBlind(structure, m);
+    const bb = sb * 2n;
+    let ante = 0n;
+    if (structure.ante && n >= structure.ante.startLevel)
+        ante = (bb * BigInt(structure.ante.bps)) / BPS;
+    return { level: n, smallBlind: sb.toString(), bigBlind: bb.toString(), ante: ante.toString(), durationMinutes: structure.durationMinutes, isBreak: false };
+}
+
 /**
  * Poker hand types in order of strength (weakest to strongest)
  */
@@ -56653,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");
@@ -57730,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
@@ -57781,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([
@@ -71184,8 +71743,8 @@ class SigningCosmosClient extends CosmosClient {
             if (sngConfig.startingStack <= 0n) {
                 throw new Error(`${gameFormat} games require a positive startingStack; got ${sngConfig.startingStack}.`);
             }
-            if (!sngConfig.blindLevelDuration || sngConfig.blindLevelDuration <= 0) {
-                throw new Error(`${gameFormat} games require a positive blindLevelDuration; got ${sngConfig.blindLevelDuration}.`);
+            if (!sngConfig.blindStructure && (!sngConfig.blindLevelDuration || sngConfig.blindLevelDuration <= 0)) {
+                throw new Error(`${gameFormat} games require a positive blindLevelDuration (or a blindStructure); got ${sngConfig.blindLevelDuration}.`);
             }
             assertCreatableSngField(minPlayers, maxPlayers, sngConfig);
         }
@@ -71228,6 +71787,9 @@ class SigningCosmosClient extends CosmosClient {
             // Scheduled start (poker-vm#2680), unix seconds. 0 = unscheduled, and
             // a zero proto3 int64 is not encoded at all.
             startTime: sngConfig?.startTime ? Long.fromNumber(sngConfig.startTime) : Long.ZERO,
+            // Blind structure (block52/pokerchain#434) as JSON; "" = doubling, and
+            // an empty proto3 string is not encoded at all.
+            blindStructure: sngConfig?.blindStructure ? JSON.stringify(sngConfig.blindStructure) : "",
         });
         // Create the transaction message
         const msg = {
@@ -71257,7 +71819,8 @@ class SigningCosmosClient extends CosmosClient {
             ...(sngConfig && {
                 startingStack: sngConfig.startingStack.toString(),
                 blindLevelDuration: sngConfig.blindLevelDuration,
-                entryFee: sngConfig.entryFee?.toString() ?? "0"
+                entryFee: sngConfig.entryFee?.toString() ?? "0",
+                ...(sngConfig.blindStructure && { blindStructure: sngConfig.blindStructure })
             })
         });
         try {
@@ -72178,5 +72741,5 @@ const registry = new Registry([
     ...msgTypes,
 ]);
 
-export { AllPlayerActions, BLIND_PRESETS, BLIND_PROGRESSIONS, BLOCK52_HD_PATH, BettingLimit, Board, COSMOS_CONSTANTS, Client, CosmosClient, Deck, GAME_NAME_MICRO_PER_CHAR, GameFormat, GameStatus, GameVariant, HandType, KEYS, MAX_GAME_NAME_LENGTH, MSG_CREATE_VALIDATOR_TYPE_URL, MissingWalletError, NonPlayerActionType, Params$c as Params, PlayerActionType, PlayerStatus, PokerGameIntegration, PokerSolver, RPCMethods, SIT_IN_METHOD_NEXT_BB, SIT_IN_METHOD_POST_NOW, SIT_OUT_METHOD_NEXT_BB, SIT_OUT_METHOD_NEXT_HAND, SUIT, SigningCosmosClient, TexasHoldemRound, TxExecutionError, ValidatorBond, WithdrawalRequest, assertCreatableBettingLimit, assertExecuted, buildMsgCreateValidator, computeGameNameFee, createSigningClientFromMnemonic, createWalletFromMnemonic, decToAtomics, formatGameFormatDisplay, formatGameVariantDisplay, generateWallet, getActionByType, getAddressFromMnemonic, getBettingLimit, getDefaultCosmosConfig, getGameFormat, getGameFormatForCosmos, getGameFormatFromObject, getGameVariant, hasAction, holeCardsPerPlayer, isCashFormat, isEmptyAddress, isPotLimit, isSitAndGoFormat, isTournamentFormat, isValidMnemonic, isValidPlayerAddress, parseGameFormat, parseGameVariant, registry, toValoperAddress, txFailureHash, txFailurePhase };
+export { AllPlayerActions, BLIND_PRESETS, BLIND_PRESET_STRUCTURES, BLIND_PROGRESSIONS, BLOCK52_HD_PATH, BettingLimit, Board, COSMOS_CONSTANTS, Client, CosmosClient, Deck, GAME_NAME_MICRO_PER_CHAR, GameFormat, GameStatus, GameVariant, HandType, KEYS, MAX_GAME_NAME_LENGTH, MSG_CREATE_VALIDATOR_TYPE_URL, MissingWalletError, NonPlayerActionType, Params$c as Params, PlayerActionType, PlayerStatus, PokerGameIntegration, PokerSolver, RPCMethods, SIT_IN_METHOD_NEXT_BB, SIT_IN_METHOD_POST_NOW, SIT_OUT_METHOD_NEXT_BB, SIT_OUT_METHOD_NEXT_HAND, SUIT, SigningCosmosClient, TexasHoldemRound, TxExecutionError, ValidatorBond, WithdrawalRequest, assertCreatableBettingLimit, assertExecuted, buildMsgCreateValidator, computeGameNameFee, createSigningClientFromMnemonic, createWalletFromMnemonic, decToAtomics, expandBlindLevel, formatBlindStructure, formatGameFormatDisplay, formatGameVariantDisplay, generateWallet, getActionByType, getAddressFromMnemonic, getBettingLimit, getDefaultCosmosConfig, getGameFormat, getGameFormatForCosmos, getGameFormatFromObject, getGameVariant, hasAction, holeCardsPerPlayer, isCashFormat, isEmptyAddress, isPotLimit, isSitAndGoFormat, isTournamentFormat, isValidMnemonic, isValidPlayerAddress, parseBlindStructure, parseGameFormat, parseGameVariant, registry, resolveBlindPreset, toValoperAddress, txFailureHash, txFailurePhase };
 //# sourceMappingURL=index.esm.js.map