hbengine 0.2.3

package/engine-sdk/sdk.d.ts

@@ -0,0 +1,138 @@
+// Types for @housegames/engine-sdk (sdk.js, ui.js). Editors read them; nothing is built.
+
+export type ErrorCode = 'invalid' | 'busy' | 'insufficient-balance' | 'limits' | 'pacing' | 'pending' | 'unavailable' | 'session-ended' | 'round' | 'conflict' | 'server' | 'needs-click' | 'autoplay';
+export const ERRORS: Readonly<Record<'INVALID' | 'BUSY' | 'INSUFFICIENT' | 'LIMITS' | 'PACING' | 'PENDING' | 'UNAVAILABLE' | 'SESSION' | 'ROUND' | 'CONFLICT' | 'SERVER' | 'CLICK' | 'AUTOPLAY', ErrorCode>>;
+
+/** A refusal from the shell or the server. */
+export class EngineError extends Error {
+    code: ErrorCode;
+    /** For pacing and pending: when to try again. */
+    retryAfterMs?: number;
+    /** For 'round': the round as it stands; redraw it. */
+    round?: Round;
+    /** For a 'limits' refusal over the maximum win per round: the most the bet takes, a decimal
+     * string in the wallet coin as the server wrote it; set the field to it. */
+    maxStake?: string;
+}
+
+export interface Bet { id: string; label?: string; maxMultBp: number }
+export interface Mode {
+    id: string; label?: string; kind: 'table' | 'ladder'; bets: Bet[];
+    steps?: number; ladderBp?: number[]; cashout?: boolean; autoAdvance?: boolean;
+}
+
+export interface Config {
+    game: string;
+    mathHash: string;
+    env: 'sandbox' | 'production';
+    balance?: number;
+    currency: { code: string; symbol: string; decimals: number };
+    /** In the wallet coin. `maxWin` is the most one round pays (the platform's maximum win per round,
+     * or the coin's own, whichever is less); `maxStake[mode][bet]` is the most that bet takes under it
+     * (a decimal string at the coin's precision, rounded down: stake × the bet's top multiplier stays
+     * within `maxWin`), so a high-multiplier bet has a low one. `"0"` for every bet (and `maxWin` 0)
+     * while the coin has no USD rate: nothing can be staked until it is back. Absent on an older server. */
+    limits: { min: number; max: number; maxWin: number; maxStake?: Record<string, Record<string, string>> };
+    modes: Mode[];
+    activeRound?: Round;
+    playerTag: string;
+    state: { revision: number; data: unknown };
+    locale: string;
+    /** The jurisdiction's word on autoplay. */
+    rg?: { autoplay?: { allowed: boolean } };
+}
+
+/** The round as the game replays it. Show it as it comes back: it is the truth. */
+export interface Round {
+    id: string; game: string; mathHash: string; mode: string; bet: string; kind: 'table' | 'ladder';
+    nonce: number; currency: string; amount: string; step: number; state: 'open' | 'closed' | string; createdAt: string;
+    draws: { index: number; raw: string; rejected: number }[];
+    /** The row data of each shown draw (what your math/*.tsv holds). */
+    data: any[];
+    payout?: string; multBp?: number; payoutMultiplier?: number; settledAt?: string;
+    survived?: number; busted?: boolean;
+}
+
+/** Money exactly as the House Originals show it, in the player's coin or fiat. Amounts are wallet units. */
+export interface Money {
+    coin: string; isFiat: boolean; unit: string; sign: string; mark: string;
+    decimals: number; walletDecimals: number;
+    /** The smallest wallet unit (10⁻⁸ for a coin): the precision a stake is cut to. Never a bet button's increment (nor is limits.min): bet up / down walks levels(). */
+    step: number;
+    toView(amount: number): number; toWallet(value: number): number;
+    format(amount: number): string; caption(amount: number): string; parse(text: string): number;
+    payout(amount: number, mult: number): number;
+    /** Round stakes in the display unit between min and max (wallet units, engine.config.limits): offer these, never a converted limit. */
+    levels(min?: number, max?: number): BetLevel[];
+}
+
+/** A bet level: the round number the player sees, the wallet amount engine.play takes, the header's text and the button's label (€2.00, 2 USDT). */
+export interface BetLevel { view: number; amount: number; text: string; label: string; }
+
+export type ShellEvent = 'balance' | 'control' | 'pause' | 'resume' | 'ended' | 'autoplay';
+/** The shell's autoplay session: sent when it starts, after each of its plays and when it ends. */
+export interface AutoplayState {
+    active: boolean;
+    /** Plays left in the session. */
+    left: number;
+    /** Plays made in it. */
+    played: number;
+    /** The most a play in it may stake (while active). */
+    stake?: number;
+    /** Why it ended: stopped, done, profit, loss, refused, paused, ended. */
+    reason?: string;
+}
+export interface EventBody {
+    balance: { balance: number };
+    control: { action: 'sound' | 'settings' };
+    pause: {}; resume: {}; ended: {};
+    autoplay: AutoplayState;
+}
+
+/** What a game asks the shell for on the player's click: at most `rounds` plays (≤ 1000) of one
+ * bet (`mode`, `bet`), none above `stake`. The shell shows the player these terms before any play. */
+export interface AutoplayRequest {
+    mode: string;
+    bet: string;
+    rounds: number;
+    stake: number;
+    /** End the session once its net result reaches this profit / this loss (wallet units). */
+    stopOnProfit?: number;
+    stopOnLoss?: number;
+}
+
+export interface Engine {
+    readonly config: Config;
+    readonly money: Money;
+    /** The balance as the site's header shows it; null while unknown. */
+    readonly balance: number | null;
+    /** The player's saved data; neither call needs a click (a save moves no money). */
+    readonly state: { get(): Promise<{ revision: number; data: unknown }>; put(revision: number, data: unknown): Promise<{ revision: number; data: unknown }> };
+    /** Places a bet; rejects with EngineError. Call it from the player's click (or inside an
+     * autoplay session): the shell refuses a play with no activation behind it (`needs-click`). */
+    play(bet: { mode: string; bet: string; amount: number }): Promise<{ round: Round; balance?: number }>;
+    /** Moves an open ladder round. `advance` and `cashout` both need the player's click as a play does
+     * (nothing moves without the player; a round left open waits for them, never for the game), or the session's own round. */
+    action(round: Round, action: 'advance' | 'cashout'): Promise<{ round: Round; balance?: number }>;
+    /** Autoplay is the shell's: ask for a session from the player's click (`needs-click` otherwise) —
+     * the shell shows the player the capped terms and resolves this on their Start (rejects with
+     * `autoplay` on Cancel, for 10 s after a Cancel, or when their rules forbid it) — play inside it
+     * (no click needed, on the bet granted), follow the `autoplay` event; the shell shows rounds left
+     * and Stop over the game. */
+    readonly autoplay: {
+        start(request: AutoplayRequest): Promise<{ session: AutoplayRequest }>;
+        stop(): Promise<{ stopped: true }>;
+    };
+    /** The settled round as the game may see it, without its seeds; the shell's dialog (openFairness) holds the receipt. */
+    round(roundId: string): Promise<unknown>;
+    on<T extends ShellEvent>(type: T, fn: (body: EventBody[T]) => void): () => void;
+    /** The first frame is on screen. */
+    ready(): void;
+    loading(group: string, loaded: number, total: number): void;
+    /** The round's outcome is on screen: the header balance follows now. */
+    revealed(roundId: string): void;
+    openFairness(roundId: string): void;
+    reportError(message: string): void;
+}
+
+export function connect(options?: { timeoutMs?: number }): Promise<Engine>;

package/engine-sdk/sdk.js

@@ -0,0 +1,330 @@
+/**
+ * @housegames/engine-sdk — what a studio game imports.
+ *
+ *     import { connect } from '@housegames/engine-sdk';
+ *
+ *     const engine = await connect();
+ *     engine.config;                     // game, modes, currency, limits, balance, state…
+ *     engine.money;                      // the player's currency, as the Originals show it
+ *     const field = document.querySelector('hb-bet-amount');   // bet-field.js
+ *     field.connect(engine);
+ *     const { round, balance } = await engine.play({ mode: 'coin', bet: 'heads', amount: field.amount });
+ *     await engine.action(round, 'cashout');
+ *     engine.on('balance', ({ balance }) => …);
+ *     engine.ready();                    // first frame is on screen
+ *
+ * The game never talks to the server. It asks the shell around it, and the
+ * shell answers with what the server decided. Show `round` and `balance` as
+ * they come back: they are the truth, and nothing the game computes is.
+ *
+ * A bet is the player's act: call play(), and a ladder's action (advance
+ * and cashout alike), from the handler of the player's click or key press,
+ * or the shell refuses it with `needs-click`. Autoplay is the shell's: ask
+ * for a session (engine.autoplay.start, below, from the player's click too)
+ * — the shell shows the player the terms and starts it on their Start,
+ * answering you then — play inside it, and follow its `autoplay` events; the
+ * shell shows its own Stop over the game.
+ */
+import {
+    ERRORS,
+    GAME_EVENTS,
+    REQUESTS,
+    SHELL_EVENTS,
+    event,
+    maxStakeFor,
+    readShellMessage,
+    request,
+} from './protocol.js';
+import { moneyFor } from './money.js';
+
+/** A refusal from the shell or the server. `code` is one of ERRORS. */
+export class EngineError extends Error {
+    constructor(code, message, retryAfterMs, round, maxStake) {
+        super(message || code);
+        this.name = 'EngineError';
+        this.code = code;
+        if (retryAfterMs > 0) this.retryAfterMs = retryAfterMs;
+        // A refusal about a round carries it as it stands now.
+        if (round && typeof round === 'object') this.round = round;
+        // A `limits` refusal over the maximum win per round carries the most
+        // the bet takes (a decimal string in the wallet coin, as the server
+        // wrote it): set the field to it.
+        if (typeof maxStake === 'string' && maxStake !== '') this.maxStake = maxStake;
+    }
+}
+
+export { ERRORS };
+
+const CONNECT_TIMEOUT_MS = 15_000;
+const HELLO_EVERY_MS = 400;
+// Windows whose uncaught errors are already reported: a second connect() on the same
+// page (a game that reconnects) must not count each error twice.
+const hooked = new WeakSet();
+// The shell always answers: it has its own deadline on the server and turns
+// a timeout into a refusal. This is only a backstop for a shell that is gone.
+const ANSWER_TIMEOUT_MS = 60_000;
+
+/**
+ * Waits for the shell's `init` and returns the engine handle. Rejects when no
+ * shell answers in time (the game was opened outside the shell).
+ */
+export function connect({ host = globalThis.parent, self = globalThis, timeoutMs = CONNECT_TIMEOUT_MS } = {}) {
+    return new Promise((resolve, reject) => {
+        if (!host || host === self) {
+            reject(new EngineError(ERRORS.SESSION, 'not inside the engine shell'));
+            return;
+        }
+        // The game says it is here and asks for its config, again every
+        // HELLO_EVERY_MS until the shell answers: however long the page took
+        // to load, and whenever the shell started listening.
+        const hello = () => host.postMessage(event(GAME_EVENTS.HELLO, {}), '*');
+        const again = setInterval(hello, HELLO_EVERY_MS);
+        const timer = setTimeout(() => {
+            clearInterval(again);
+            self.removeEventListener('message', onInit);
+            reject(new EngineError(ERRORS.SESSION, 'the engine shell did not answer'));
+        }, timeoutMs);
+        function onInit(e) {
+            if (e.source !== host) return;
+            const msg = readShellMessage(e.data);
+            if (!msg || msg.kind !== 'evt' || msg.type !== SHELL_EVENTS.INIT) return;
+            clearTimeout(timer);
+            clearInterval(again);
+            self.removeEventListener('message', onInit);
+            resolve(new Engine(host, self, msg.body));
+        }
+        self.addEventListener('message', onInit);
+        hello();
+    });
+}
+
+class Engine {
+    #host;
+    #pending = new Map(); // id -> { resolve, reject, timer }
+    #listeners = new Map(); // shell event type -> Set<fn>
+    #seq = 0;
+    #moneyInFlight = false;
+    #balance = null;
+    #reveal = null; // { roundId, balance }: the settled round whose result waits for revealed()
+
+    constructor(host, self, config) {
+        this.#host = host;
+        this.config = Object.freeze(config);
+        // An old shell sends no wallet: the plain coin at its precision.
+        const c = config.currency || {};
+        this.money = moneyFor(config.wallet || { symbol: c.symbol, name: c.symbol, isFiat: false, rate: 1, betPrecision: c.decimals });
+        if (typeof config.balance === 'number') this.#balance = config.balance;
+        self.addEventListener('message', (e) => {
+            if (e.source !== host) return;
+            const msg = readShellMessage(e.data);
+            if (!msg) return;
+            if (msg.kind === 'res') this.#settle(msg);
+            else {
+                // The shell's word on the balance outranks a reveal still waiting.
+                if (msg.type === SHELL_EVENTS.BALANCE && typeof msg.body.balance === 'number') { this.#balance = msg.body.balance; this.#reveal = null; }
+                this.#emit(msg.type, msg.body);
+            }
+        });
+        this.state = Object.freeze({
+            get: () => this.#ask(REQUESTS.STATE_GET, {}),
+            put: (revision, data) => this.#ask(REQUESTS.STATE_PUT, { revision, data }),
+        });
+        // Autoplay is a session the shell grants and runs the count of:
+        //   start({ mode, bet, rounds, stake, stopOnProfit?, stopOnLoss? })  → { session }, on the player's click;
+        //                 rounds ≤ 1000, every play in it on that bet and none above `stake`;
+        //                 a stop ends it at that net result
+        //   stop()        → { stopped: true }, always taken
+        // Plays inside it need no click; the shell's `autoplay` event says
+        // {active, left, played, reason?} on every change. The shell shows
+        // rounds left and Stop over the game itself.
+        this.autoplay = Object.freeze({
+            start: ({ mode, bet, rounds, stake, stopOnProfit, stopOnLoss } = {}) => {
+                const body = { mode, bet, rounds, stake };
+                if (stopOnProfit > 0) body.stopOnProfit = stopOnProfit;
+                if (stopOnLoss > 0) body.stopOnLoss = stopOnLoss;
+                return this.#ask(REQUESTS.AUTOPLAY_START, body);
+            },
+            stop: () => this.#ask(REQUESTS.AUTOPLAY_STOP, {}),
+        });
+        // An error the page never caught (a render loop, a click handler, a promise) is
+        // reported like reportError: the shell logs it, the engine counts one error, and
+        // the studio's Reports show the count. The game's own code sees nothing of this.
+        if (!hooked.has(self)) {
+            hooked.add(self);
+            self.addEventListener('error', (e) => this.reportError(e && e.message ? e.message : 'uncaught error'));
+            self.addEventListener('unhandledrejection', (e) => {
+                const r = e ? e.reason : undefined;
+                this.reportError(r && r.message ? r.message : r === undefined ? 'unhandled rejection' : r);
+            });
+        }
+    }
+
+    /** The player's balance in the wallet currency, as the site's header
+     * shows it: the stake leaves when the bet is placed, the result lands
+     * when the game calls revealed(). null while unknown. */
+    get balance() {
+        return this.#balance;
+    }
+
+    /** Places a bet. Resolves { round, balance? }; rejects with EngineError.
+     * The stake is a positive amount: there is no free round (a round that
+     * costs nothing would still consume a nonce of the player's seed pair),
+     * so 0 is refused here with `limits`, as the server refuses it, before
+     * anything is sent. So is a stake over the most this bet may take under
+     * the maximum win per round (config.limits.maxStake[mode][bet]): the
+     * server would refuse it before the bet, and the refusal names the
+     * highest stake the bet takes. A figure of 0 (the coin has no rate yet)
+     * is refused as `unavailable`, which is what the server would answer. */
+    play({ mode, bet, amount }) {
+        if (!(typeof amount === 'number' && Number.isFinite(amount) && amount > 0)) {
+            return Promise.reject(new EngineError(ERRORS.LIMITS, 'a stake is required: a round is never played for free'));
+        }
+        const most = maxStakeFor(this.config.limits, mode, bet);
+        if (most === 0) {
+            return Promise.reject(new EngineError(ERRORS.UNAVAILABLE, 'nothing can be staked on this bet right now: the coin has no rate to price the maximum win in; try again shortly'));
+        }
+        // Compared at the wallet's precision, so a float's noise past it never
+        // refuses a stake the field shows as exactly the cap.
+        if (most !== null && Number(amount.toFixed(this.money.walletDecimals)) > most) {
+            const named = this.config.limits.maxStake[mode][bet]; // as the server wrote it (a stand may hand a number)
+            return Promise.reject(new EngineError(ERRORS.LIMITS, `the most this bet takes is ${this.money.format(most)} ${this.money.unit}: one round pays no more than the maximum win`, 0, undefined, String(named)));
+        }
+        return this.#money(REQUESTS.PLAY, { mode, bet, amount }).then((answer) => {
+            this.#afterMoney(answer, amount);
+            return answer;
+        });
+    }
+
+    /** Moves an open ladder round: 'advance' or 'cashout' — either from the player's click
+     * (the shell refuses both with `needs-click` otherwise). Pass the round as
+     * you last had it: its step goes with the request, so a stale action
+     * (another tab, a retry) is refused with the round as it stands. */
+    action(round, action) {
+        return this.#money(REQUESTS.ACTION, { roundId: round.id, step: round.step, action }).then((answer) => {
+            this.#afterMoney(answer, 0);
+            return answer;
+        });
+    }
+
+    /** Reads one of the player's settled rounds as the game may see it,
+     * without its seeds; the shell's dialog (openFairness) holds the receipt. */
+    round(roundId) {
+        return this.#ask(REQUESTS.ROUND, { roundId });
+    }
+
+    /** Subscribes to a shell event (balance, control, pause, resume, ended, autoplay). */
+    on(type, fn) {
+        if (!Object.values(SHELL_EVENTS).includes(type) || type === SHELL_EVENTS.INIT) {
+            throw new TypeError(`unknown engine event ${type}`);
+        }
+        if (!this.#listeners.has(type)) this.#listeners.set(type, new Set());
+        this.#listeners.get(type).add(fn);
+        return () => this.#listeners.get(type).delete(fn);
+    }
+
+    /** The first frame is on screen: the shell drops its loader. */
+    ready() {
+        this.#tell(GAME_EVENTS.READY, {});
+    }
+
+    /** Progress of an asset group, for the shell's loader and telemetry. */
+    loading(group, loaded, total) {
+        this.#tell(GAME_EVENTS.LOADING, { group, loaded, total });
+    }
+
+    /** The round's outcome is on screen: the site's header balance follows
+     * now. Call it when your reveal animation lands; if you never do, the
+     * shell moves the header at its own deadline. */
+    revealed(roundId) {
+        if (this.#reveal && this.#reveal.roundId === roundId) {
+            this.#setBalance(this.#reveal.balance);
+            this.#reveal = null;
+        }
+        this.#tell(GAME_EVENTS.REVEALED, { roundId });
+    }
+
+    /** Opens the shell's fairness dialog on a round. */
+    openFairness(roundId) {
+        this.#tell(GAME_EVENTS.FAIRNESS, { roundId });
+    }
+
+    /** Reports a game error: the shell logs it in the player's console and the engine counts
+     * one error for the game's day. The count reaches the studio; the text never does. */
+    reportError(message) {
+        this.#tell(GAME_EVENTS.ERROR, { message: String(message).slice(0, 500) });
+    }
+
+    // The header's two steps: the stake leaves now; a settled round's result
+    // waits for its reveal, an open round's balance is already the truth.
+    #afterMoney(answer, stake) {
+        const known = answer && typeof answer.balance === 'number' && answer.balance >= 0 ? answer.balance : null;
+        const round = answer && answer.round;
+        if (known === null) return;
+        // A reveal the game never reported is overtaken by the next round.
+        if (this.#reveal) this.#setBalance(this.#reveal.balance);
+        this.#reveal = null;
+        if (round && round.state !== 'open' && typeof round.id === 'string') {
+            this.#reveal = { roundId: round.id, balance: known };
+            const dp = this.money.walletDecimals;
+            if (this.#balance !== null && stake > 0) this.#setBalance(Math.max(0, Number((this.#balance - stake).toFixed(dp))));
+        } else {
+            this.#setBalance(known);
+        }
+    }
+
+    #setBalance(balance) {
+        if (balance === this.#balance) return;
+        this.#balance = balance;
+        this.#emit(SHELL_EVENTS.BALANCE, { balance });
+    }
+
+    // One bet or action at a time: the server would refuse the second one
+    // anyway (it holds the player's lock), and saying so here is clearer.
+    #money(type, body) {
+        if (this.#moneyInFlight) {
+            return Promise.reject(new EngineError(ERRORS.BUSY, 'another bet is still with the server'));
+        }
+        this.#moneyInFlight = true;
+        return this.#ask(type, body).finally(() => {
+            this.#moneyInFlight = false;
+        });
+    }
+
+    #ask(type, body) {
+        const id = `r${++this.#seq}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new EngineError(ERRORS.SERVER, 'the engine shell did not answer'));
+            }, ANSWER_TIMEOUT_MS);
+            this.#pending.set(id, { resolve, reject, timer });
+            this.#host.postMessage(request(id, type, body), '*');
+        });
+    }
+
+    #settle(msg) {
+        const p = this.#pending.get(msg.id);
+        if (!p) return;
+        this.#pending.delete(msg.id);
+        clearTimeout(p.timer);
+        if (msg.ok) p.resolve(msg.body);
+        else p.reject(new EngineError(msg.error.code, msg.error.message, msg.error.retryAfterMs, msg.error.round, msg.error.maxStake));
+    }
+
+    #emit(type, body) {
+        for (const fn of this.#listeners.get(type) ?? []) {
+            try {
+                fn(body);
+            } catch (err) {
+                this.reportError(err && err.message ? err.message : err);
+            }
+        }
+    }
+
+    // The shell's window is the only reader. '*' is the target because the
+    // game cannot name the shell's origin from inside an opaque sandbox; the
+    // message carries nothing secret.
+    #tell(type, body) {
+        this.#host.postMessage(event(type, body), '*');
+    }
+}

package/engine-sdk/stake.js

@@ -0,0 +1,68 @@
+/**
+ * Why a stake cannot be played now, as the bet field (bet-field.js) and the
+ * engine panel (ui.js) decide it before anything reaches the shell. One pure
+ * rule, so it is tested without a browser:
+ *
+ *   'balance'  over the balance the shell last reported
+ *   'min'      no stake at all, or under the coin's minimum — an engine round
+ *              is never played for free (SPEC §2 item 5): a round costs a
+ *              nonce of the player's seed pair, so the server refuses a stake
+ *              of 0 and the field never offers one
+ *   'max'      over the coin's maximum
+ *   'maxWin'   over the most this bet may take under the maximum win per
+ *              round (SPEC §3.1): stake × the bet's top multiplier would pass
+ *              the cap, so the server would refuse the bet before it starts.
+ *              A ceiling of 0 (the server names it while the coin has no USD
+ *              rate) refuses every stake, the empty field included: nothing
+ *              can be staked on the bet until the rate is back
+ *   null       playable
+ *
+ * Of the coin's maximum and the bet's own ceiling, the lower is the one named:
+ * the server's `maxStake` never passes the coin's max bet, so a player who
+ * types more than both hears the figure the bet can take, not one it never
+ * could. `limits` is engine.config.limits ({min, max} in wallet units; either
+ * may be missing, as in the sandbox); `balance` is engine.balance (null while
+ * unknown); `maxStake` is the selected bet's own ceiling in wallet units
+ * (protocol.js maxStakeFor), or null when the session names none for it.
+ */
+export function stakeReason(amount, limits, balance, maxStake = null) {
+    const a = Number(amount);
+    const { min, max } = limits || {};
+    const coinMax = typeof max === 'number' && max > 0 ? max : null;
+    const betMax = typeof maxStake === 'number' && maxStake >= 0 ? maxStake : null;
+    if (betMax === 0) return 'maxWin';
+    if (!(a > 0) || !Number.isFinite(a)) return 'min';
+    if (balance !== null && balance !== undefined && a > balance) return 'balance';
+    if (typeof min === 'number' && a < min) return 'min';
+    // The lower ceiling first; a bet's ceiling above the coin's (a stand) is
+    // never reached before the coin's is.
+    if (betMax !== null && (coinMax === null || betMax <= coinMax) && a > betMax) return 'maxWin';
+    if (coinMax !== null && a > coinMax) return 'max';
+    return null;
+}
+
+/**
+ * The most the field offers (its max chip): the coin's maximum, the selected
+ * bet's own ceiling under the maximum win and the balance, whichever is
+ * least; Infinity when none is known. A ceiling of 0 is 0: nothing to offer.
+ */
+export function stakeCeiling(limits, balance, maxStake = null) {
+    const { max } = limits || {};
+    return Math.min(
+        typeof max === 'number' && max > 0 ? max : Infinity,
+        typeof maxStake === 'number' && maxStake >= 0 ? maxStake : Infinity,
+        balance ?? Infinity,
+    );
+}
+
+/**
+ * The least a player can stake: the coin's minimum when the server named
+ * one, else one unit of the wallet's precision — what the "minimum bet"
+ * message says when the field is empty.
+ */
+export function leastStake(limits, walletDecimals) {
+    const { min } = limits || {};
+    if (typeof min === 'number' && min > 0) return min;
+    const dp = Number.isInteger(walletDecimals) && walletDecimals >= 0 ? walletDecimals : 8;
+    return 10 ** -dp;
+}

package/engine-sdk/ui.d.ts

@@ -0,0 +1,36 @@
+import type { Engine, Round } from './sdk.js';
+
+export interface Game {
+    readonly engine: Engine;
+    /** The stake field (<hb-bet-amount>). `reason` says why the stake cannot be played: over the balance,
+     * under the coin's minimum, over its maximum, or over the most the selected bet takes under the
+     * maximum win per round (`maxWin`); the panel keeps `bet` on the selection. */
+    readonly field: HTMLElement & {
+        amount: number;
+        reason: { code: 'balance' | 'min' | 'max' | 'maxWin'; message: string } | null;
+        disabled: boolean;
+        bet: { mode: string; bet: string } | null;
+        /** The most the selected bet takes, in wallet units; null when the session names none;
+         * 0 when nothing can be staked for now (the coin has no rate). */
+        readonly maxStake: number | null;
+    };
+    mode: string;
+    bet: string;
+    /** The ladder round in play, if any. */
+    readonly open: Round | null;
+    /** Climb or cash out the open ladder round, as the panel's buttons do (a zone that drives its own ladder). */
+    advance(): Promise<Round | null>;
+    cashout(): Promise<Round | null>;
+}
+
+/** The engine panel around your zone: modes, bets, stake, Bet, Auto, Next / Cash out. */
+export function mount(el: HTMLElement, hooks: {
+    /** A table round is drawn: show it; resolve when it is on screen. */
+    reveal?: (round: Round, zone: HTMLElement) => Promise<void> | void;
+    /** A ladder round moved (bet, step, cash-out, bust). */
+    step?: (round: Round, zone: HTMLElement) => Promise<void> | void;
+    /** false: no Next button; the zone climbs with game.advance(). */
+    next?: boolean;
+    /** Mode and bet names by language, then id: { es: { base: 'Tirada' } } (else the math's labels). */
+    labels?: Record<string, Record<string, string>>;
+}): Promise<Game>;