hbengine 0.2.3

package/engine-sdk/messages.js

@@ -0,0 +1,289 @@
+/* GENERATED by tools/sync-kit.mjs from the Originals' dictionaries: do not edit. */
+export const MESSAGES = {
+    "en": {
+        "betAmount": "Bet Amount",
+        "blockOverBalance": "Bet exceeds balance",
+        "blockOverMax": "Exceeds maximum bet amount of {amount} {currency}",
+        "blockUnderMin": "Minimum bet amount is {amount} {currency}",
+        "bet": "Bet",
+        "manual": "Manual",
+        "auto": "Auto",
+        "startAutobet": "Start Autobet",
+        "stopAutobet": "Stop Autobet",
+        "numberOfBets": "Number of bets (0 = infinite)",
+        "onWin": "On Win",
+        "onLoss": "On Loss",
+        "reset": "Reset",
+        "increase": "Increase",
+        "stopOnProfit": "Stop on Profit",
+        "stopOnLoss": "Stop on Loss",
+        "apiRateLimited": "Slow down and try again.",
+        "apiRoundUnresolved": "The round did not settle in time. Your balance will update on its own.",
+        "apiInternalError": "Something went wrong. Please try again.",
+        "cashOut": "Cash out"
+    },
+    "es": {
+        "betAmount": "Importe de la apuesta",
+        "blockOverBalance": "La apuesta supera el saldo",
+        "blockOverMax": "Supera la apuesta máxima de {amount} {currency}",
+        "blockUnderMin": "La apuesta mínima es de {amount} {currency}",
+        "bet": "Apostar",
+        "manual": "Manual",
+        "auto": "Auto",
+        "startAutobet": "Iniciar autoapuesta",
+        "stopAutobet": "Detener autoapuesta",
+        "numberOfBets": "Número de apuestas (0 = ilimitado)",
+        "onWin": "Al ganar",
+        "onLoss": "Al perder",
+        "reset": "Reset",
+        "increase": "Subir",
+        "stopOnProfit": "Parar en ganancia",
+        "stopOnLoss": "Parar en pérdida",
+        "apiRateLimited": "Más despacio, inténtalo de nuevo.",
+        "apiRoundUnresolved": "La ronda no se resolvió a tiempo. Tu saldo se actualizará por sí solo.",
+        "apiInternalError": "Algo salió mal. Inténtalo de nuevo.",
+        "cashOut": "Retirar"
+    },
+    "hu": {
+        "betAmount": "Tét összege",
+        "blockOverBalance": "A tét meghaladja az egyenleget",
+        "blockOverMax": "Meghaladja a maximális tétet: {amount} {currency}",
+        "blockUnderMin": "A minimális tét {amount} {currency}",
+        "bet": "Fogadás",
+        "manual": "Kézi",
+        "auto": "Auto",
+        "startAutobet": "Autofogadás indítása",
+        "stopAutobet": "Autofogadás leállítása",
+        "numberOfBets": "Fogadások száma (0 = végtelen)",
+        "onWin": "Nyerésnél",
+        "onLoss": "Vesztésnél",
+        "reset": "Reset",
+        "increase": "Növelés",
+        "stopOnProfit": "Leállítás nyereségnél",
+        "stopOnLoss": "Leállítás veszteségnél",
+        "apiRateLimited": "Lassabban, próbáld újra.",
+        "apiRoundUnresolved": "A kör nem zárult le időben. Az egyenleg magától frissül.",
+        "apiInternalError": "Valami hiba történt. Próbáld újra.",
+        "cashOut": "Kiszállás"
+    },
+    "fr": {
+        "betAmount": "Montant du pari",
+        "blockOverBalance": "La mise dépasse le solde",
+        "blockOverMax": "Dépasse la mise maximale de {amount} {currency}",
+        "blockUnderMin": "La mise minimale est de {amount} {currency}",
+        "bet": "Parier",
+        "manual": "Manuel",
+        "auto": "Auto",
+        "startAutobet": "Lancer l'autobet",
+        "stopAutobet": "Arrêter l'autobet",
+        "numberOfBets": "Nombre de paris (0 = illimité)",
+        "onWin": "En cas de gain",
+        "onLoss": "En cas de perte",
+        "reset": "Réinit.",
+        "increase": "Hausse",
+        "stopOnProfit": "Arrêt sur gain",
+        "stopOnLoss": "Arrêt sur perte",
+        "apiRateLimited": "Doucement, réessayez.",
+        "apiRoundUnresolved": "La partie ne s'est pas dénouée à temps. Votre solde se mettra à jour de lui-même.",
+        "apiInternalError": "Une erreur est survenue. Réessayez.",
+        "cashOut": "Encaisser"
+    },
+    "ru": {
+        "betAmount": "Сумма ставки",
+        "blockOverBalance": "Ставка больше баланса",
+        "blockOverMax": "Больше максимальной ставки {amount} {currency}",
+        "blockUnderMin": "Минимальная сумма ставки — {amount} {currency}",
+        "bet": "Ставка",
+        "manual": "Вручную",
+        "auto": "Авто",
+        "startAutobet": "Запустить автобет",
+        "stopAutobet": "Остановить автобет",
+        "numberOfBets": "Число ставок (0 — без ограничения)",
+        "onWin": "При выигрыше",
+        "onLoss": "При проигрыше",
+        "reset": "Сброс",
+        "increase": "Рост",
+        "stopOnProfit": "Стоп при прибыли",
+        "stopOnLoss": "Стоп при убытке",
+        "apiRateLimited": "Помедленнее, попробуйте ещё раз.",
+        "apiRoundUnresolved": "Раунд не разрешился в срок. Баланс обновится сам.",
+        "apiInternalError": "Что-то пошло не так. Попробуйте ещё раз.",
+        "cashOut": "Забрать"
+    },
+    "pt": {
+        "betAmount": "Valor da aposta",
+        "blockOverBalance": "A aposta excede o saldo",
+        "blockOverMax": "Excede a aposta máxima de {amount} {currency}",
+        "blockUnderMin": "A aposta mínima é de {amount} {currency}",
+        "bet": "Apostar",
+        "manual": "Manual",
+        "auto": "Auto",
+        "startAutobet": "Iniciar aposta automática",
+        "stopAutobet": "Parar aposta automática",
+        "numberOfBets": "Número de apostas (0 = ilimitado)",
+        "onWin": "Ao ganhar",
+        "onLoss": "Ao perder",
+        "reset": "Redefinir",
+        "increase": "Subir",
+        "stopOnProfit": "Parar no lucro",
+        "stopOnLoss": "Parar na perda",
+        "apiRateLimited": "Mais devagar, tente novamente.",
+        "apiRoundUnresolved": "A rodada não foi liquidada em tempo. Seu saldo será atualizado sozinho.",
+        "apiInternalError": "Algo deu errado. Tente novamente.",
+        "cashOut": "Sacar"
+    },
+    "id": {
+        "betAmount": "Jumlah taruhan",
+        "blockOverBalance": "Taruhan melebihi saldo",
+        "blockOverMax": "Melebihi taruhan maksimum {amount} {currency}",
+        "blockUnderMin": "Taruhan minimum adalah {amount} {currency}",
+        "bet": "Bertaruh",
+        "manual": "Manual",
+        "auto": "Otomatis",
+        "startAutobet": "Mulai taruhan otomatis",
+        "stopAutobet": "Hentikan taruhan otomatis",
+        "numberOfBets": "Jumlah taruhan (0 = tanpa batas)",
+        "onWin": "Saat menang",
+        "onLoss": "Saat kalah",
+        "reset": "Reset",
+        "increase": "Naikkan",
+        "stopOnProfit": "Berhenti saat profit",
+        "stopOnLoss": "Berhenti saat rugi",
+        "apiRateLimited": "Pelan-pelan, coba lagi.",
+        "apiRoundUnresolved": "Putaran tidak selesai tepat waktu. Saldo Anda akan diperbarui sendiri.",
+        "apiInternalError": "Terjadi kesalahan. Coba lagi.",
+        "cashOut": "Cash out"
+    },
+    "de": {
+        "betAmount": "Einsatz",
+        "blockOverBalance": "Einsatz übersteigt das Guthaben",
+        "blockOverMax": "Übersteigt den Höchsteinsatz von {amount} {currency}",
+        "blockUnderMin": "Der Mindesteinsatz beträgt {amount} {currency}",
+        "bet": "Wetten",
+        "manual": "Manuell",
+        "auto": "Auto",
+        "startAutobet": "Autobet starten",
+        "stopAutobet": "Autobet stoppen",
+        "numberOfBets": "Anzahl Wetten (0 = unbegrenzt)",
+        "onWin": "Bei Gewinn",
+        "onLoss": "Bei Verlust",
+        "reset": "Reset",
+        "increase": "Erhöhen",
+        "stopOnProfit": "Stop bei Gewinn",
+        "stopOnLoss": "Stop bei Verlust",
+        "apiRateLimited": "Langsamer, bitte erneut versuchen.",
+        "apiRoundUnresolved": "Die Runde wurde nicht rechtzeitig abgerechnet. Ihr Guthaben aktualisiert sich von selbst.",
+        "apiInternalError": "Etwas ist schiefgelaufen. Bitte erneut versuchen.",
+        "cashOut": "Auszahlen"
+    },
+    "ko": {
+        "betAmount": "베팅 금액",
+        "blockOverBalance": "베팅이 잔액을 초과합니다",
+        "blockOverMax": "최대 베팅 금액 {amount} {currency}을(를) 초과합니다",
+        "blockUnderMin": "최소 베팅 금액은 {amount} {currency}입니다",
+        "bet": "베팅",
+        "manual": "수동",
+        "auto": "자동",
+        "startAutobet": "자동 베팅 시작",
+        "stopAutobet": "자동 베팅 중지",
+        "numberOfBets": "베팅 횟수 (0 = 무제한)",
+        "onWin": "승리 시",
+        "onLoss": "패배 시",
+        "reset": "초기화",
+        "increase": "증가",
+        "stopOnProfit": "수익 도달 시 중지",
+        "stopOnLoss": "손실 도달 시 중지",
+        "apiRateLimited": "조금 천천히, 다시 시도해 주세요.",
+        "apiRoundUnresolved": "라운드가 제때 정산되지 않았습니다. 잔액은 자동으로 업데이트됩니다.",
+        "apiInternalError": "문제가 발생했습니다. 다시 시도해 주세요.",
+        "cashOut": "캐시아웃"
+    },
+    "tr": {
+        "betAmount": "Bahis tutarı",
+        "blockOverBalance": "Bahis bakiyeyi aşıyor",
+        "blockOverMax": "Maksimum bahis tutarı {amount} {currency} değerini aşıyor",
+        "blockUnderMin": "Minimum bahis tutarı {amount} {currency}",
+        "bet": "Bahis yap",
+        "manual": "Manuel",
+        "auto": "Oto",
+        "startAutobet": "Otomatik bahsi başlat",
+        "stopAutobet": "Otomatik bahsi durdur",
+        "numberOfBets": "Bahis sayısı (0 = sınırsız)",
+        "onWin": "Kazanınca",
+        "onLoss": "Kaybedince",
+        "reset": "Sıfırla",
+        "increase": "Artır",
+        "stopOnProfit": "Kârda durdur",
+        "stopOnLoss": "Zararda durdur",
+        "apiRateLimited": "Biraz yavaş, tekrar deneyin.",
+        "apiRoundUnresolved": "Tur zamanında sonuçlanmadı. Bakiyeniz kendiliğinden güncellenecek.",
+        "apiInternalError": "Bir şeyler ters gitti. Tekrar deneyin.",
+        "cashOut": "Nakit al"
+    },
+    "zh": {
+        "betAmount": "投注金额",
+        "blockOverBalance": "投注超出余额",
+        "blockOverMax": "超出最高投注额 {amount} {currency}",
+        "blockUnderMin": "最低投注金额为 {amount} {currency}",
+        "bet": "投注",
+        "manual": "手动",
+        "auto": "自动",
+        "startAutobet": "开始自动投注",
+        "stopAutobet": "停止自动投注",
+        "numberOfBets": "投注次数（0 = 无限）",
+        "onWin": "获胜时",
+        "onLoss": "失败时",
+        "reset": "重置",
+        "increase": "增加",
+        "stopOnProfit": "达到利润时停止",
+        "stopOnLoss": "达到亏损时停止",
+        "apiRateLimited": "请慢一点，稍后重试。",
+        "apiRoundUnresolved": "本轮未能及时结算。您的余额将自动更新。",
+        "apiInternalError": "出现问题，请重试。",
+        "cashOut": "提现"
+    },
+    "vi": {
+        "betAmount": "Số tiền cược",
+        "blockOverBalance": "Tiền cược vượt quá số dư",
+        "blockOverMax": "Vượt quá mức cược tối đa {amount} {currency}",
+        "blockUnderMin": "Số tiền cược tối thiểu là {amount} {currency}",
+        "bet": "Cược",
+        "manual": "Thủ công",
+        "auto": "Tự động",
+        "startAutobet": "Bắt đầu tự cược",
+        "stopAutobet": "Dừng tự cược",
+        "numberOfBets": "Số lượt cược (0 = không giới hạn)",
+        "onWin": "Khi thắng",
+        "onLoss": "Khi thua",
+        "reset": "Đặt lại",
+        "increase": "Tăng",
+        "stopOnProfit": "Dừng khi đạt lợi nhuận",
+        "stopOnLoss": "Dừng khi thua lỗ",
+        "apiRateLimited": "Chậm lại, hãy thử lại.",
+        "apiRoundUnresolved": "Vòng chơi chưa được quyết toán kịp thời. Số dư của bạn sẽ tự cập nhật.",
+        "apiInternalError": "Đã xảy ra lỗi. Hãy thử lại.",
+        "cashOut": "Rút tiền"
+    },
+    "ja": {
+        "betAmount": "ベット額",
+        "blockOverBalance": "ベット額が残高を超えています",
+        "blockOverMax": "最大ベット額 {amount} {currency} を超えています",
+        "blockUnderMin": "最低ベット額は {amount} {currency} です",
+        "bet": "ベット",
+        "manual": "手動",
+        "auto": "オート",
+        "startAutobet": "オートベット開始",
+        "stopAutobet": "オートベット停止",
+        "numberOfBets": "ベット回数（0 = 無制限）",
+        "onWin": "勝利時",
+        "onLoss": "敗北時",
+        "reset": "リセット",
+        "increase": "増やす",
+        "stopOnProfit": "利益で停止",
+        "stopOnLoss": "損失で停止",
+        "apiRateLimited": "少しゆっくり、もう一度お試しください。",
+        "apiRoundUnresolved": "ラウンドが時間内に精算されませんでした。残高は自動的に更新されます。",
+        "apiInternalError": "問題が発生しました。もう一度お試しください。",
+        "cashOut": "キャッシュアウト"
+    }
+};

package/engine-sdk/money.js

@@ -0,0 +1,89 @@
+/**
+ * Money on screen, exactly as the House Originals show it: the Originals' own
+ * code (@housegames/game-kit core/wallet-format.js and numeric-input.js,
+ * carried unchanged in kit/ and held to the source by kit.test.js), so a
+ * studio game and Dice can never disagree about a currency.
+ *
+ * The wallet is the platform's currency for the session (what our own games
+ * receive as currentlycurrency): any Housebets coin, shown in the coin or in
+ * the player's fiat at the platform's rate. What a player types is in the
+ * field's unit (euros in a EUR display); toWallet turns it into the wallet
+ * amount, truncated to the wallet's precision, and that is what engine.play
+ * takes. Balances and payouts come from the server and are only formatted.
+ *
+ * Every picture is ours and travels inside the SDK: the site's coin marks
+ * (marks.js) and the Originals' fiat coins (kit/fiat-coins.js).
+ */
+import * as kit from './kit/wallet-format.js';
+import { fiatCoinSrc } from './kit/fiat-coins.js';
+import { sanitizeDecimal, filterNumericInput } from './kit/numeric-input.js';
+import { COIN_MARKS, LOGO_MARK } from './marks.js';
+
+export { sanitizeDecimal, filterNumericInput };
+
+/** The mark of a currency code: our coin for a fiat, the site's for a coin,
+ * the logo for a coin it has no picture of. */
+export function markOf(code) {
+    const c = String(code || '').trim().toUpperCase();
+    return fiatCoinSrc(c) || COIN_MARKS[c] || LOGO_MARK;
+}
+
+/** The money helpers bound to one session's wallet. */
+export function moneyFor(w) {
+    const fiatView = kit.isFiatView(w);
+    // The wallet's own currency: in a fiat display the platform renames
+    // `symbol` to the fiat and keeps the coin in `name` (wallet-format.js).
+    const coin = (w && (w.name || w.symbol)) || '';
+    return Object.freeze({
+        wallet: w,
+        coin,
+        isFiat: fiatView,
+        unit: kit.viewUnit(w),
+        sign: kit.fieldSign(w),
+        decimals: kit.viewPrecision(w),
+        walletDecimals: kit.walletPrecision(w),
+        mark: markOf(fiatView ? kit.viewUnit(w) : coin),
+        /** One smallest wallet unit (10⁻⁸ for a coin): the precision a stake is cut to, never a
+         *  bet button's increment, and neither is the minimum bet — bet up / down walks levels()
+         *  (a slot's €0.10, €0.20, €0.50 …). */
+        step: 10 ** -kit.walletPrecision(w),
+        toView: (amount) => kit.viewFromWallet(amount, w),
+        toWallet: (value) => kit.walletFromView(value, w),
+        format: (amount) => kit.fmtView(amount, w),
+        caption: (amount) => kit.counterText(amount, w),
+        parse: (text) => kit.parseView(text, w),
+        payout: (amount, mult) => kit.payoutAtWalletPrecision(amount, mult, w),
+        filter: (input) => filterNumericInput(input, 'decimal'),
+        levels: (min, max) => betLevels(w, min, max),
+    });
+}
+
+/**
+ * Bet levels as a slot shows them: round stakes in the player's display unit
+ * (1, 2, 5 × a power of ten: €0.10, €0.20, €0.50, €1, €2 … or 0.0001 BTC …),
+ * each with the wallet amount engine.play takes, its text as the header
+ * formats it, and its label as a bet button says it. Only the levels
+ * between min and max (wallet units, engine.config.limits) whose wallet amount
+ * shows back as the same round number: a stake the player sees is the stake
+ * that is sent, and no converted limit ("2,000.62019200 USDT") is ever offered.
+ * At most 24, from the smallest up.
+ */
+export function betLevels(w, min = 0, max = Infinity) {
+    const dp = kit.viewPrecision(w);
+    const out = [];
+    for (let e = -dp; e <= 9 && out.length < 24; e++) {
+        for (const k of [1, 2, 5]) {
+            const view = Number((k * 10 ** e).toFixed(Math.max(0, -e)));
+            const amount = kit.walletFromView(view, w);
+            if (!(amount > 0) || amount < min || amount > max) continue;
+            if (Math.abs(kit.viewFromWallet(amount, w) - view) > 10 ** -dp / 2) continue; // would not show as the round number
+            const text = kit.fmtView(amount, w);
+            // The level as a button says it: €2.00 in a fiat display, 2 USDT / 0.0005 BTC in a coin
+            // (a round level needs none of the wallet's trailing zeros).
+            const label = kit.isFiatView(w) ? kit.fieldSign(w) + text : `${text.includes('.') ? text.replace(/\.?0+$/, '') : text} ${kit.viewUnit(w)}`;
+            out.push({ view, amount, text, label });
+            if (out.length === 24) break;
+        }
+    }
+    return out;
+}

package/engine-sdk/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/engine-sdk/protocol.js

@@ -0,0 +1,263 @@
+/**
+ * The message contract between the engine shell (our code) and a studio game
+ * (theirs), which runs in a sandboxed iframe with no network of its own.
+ *
+ * The shell is the only client of the engine API. The game asks it for
+ * everything — a bet, an action, its saved state — and the shell answers with
+ * what the server said. Nothing the game sends can move money by itself: a
+ * request is a wish the server decides on, and the balance and outcome the
+ * game shows are the ones the shell hands back. A bet is also the player's
+ * act: the shell takes a play only on the player's click (the browser's user
+ * activation, which a click inside the game frame hands the shell) or inside
+ * an autoplay session the player started, so a game cannot bet on its own.
+ *
+ * Every message is one envelope:
+ *
+ *     { hb: 1, kind: 'req', id, type, body }        game  -> shell, answered
+ *     { hb: 1, kind: 'res', id, ok: true, body }    shell -> game, the answer
+ *     { hb: 1, kind: 'res', id, ok: false, error }  shell -> game, a refusal
+ *     { hb: 1, kind: 'evt', type, body }            either way, not answered
+ *
+ * Both sides drop anything that does not validate here, without answering:
+ * a malformed message is never a reason to act. The sender is checked by
+ * window, not by origin — a sandboxed frame's origin is the string "null",
+ * which any other sandboxed frame shares.
+ */
+
+export const PROTOCOL = 1;
+
+/** Requests the game may make; each is answered exactly once. */
+export const REQUESTS = Object.freeze({
+    PLAY: 'play',
+    ACTION: 'action',
+    ROUND: 'round',
+    STATE_GET: 'state.get',
+    STATE_PUT: 'state.put',
+    // Autoplay is the shell's: the game asks for a session (on the player's
+    // click; the shell confirms it with the player in its own dialog) and
+    // plays inside it; the shell counts the rounds, holds the plays to the
+    // bet and the stake granted, shows its own Stop and ends it. The game
+    // cannot run bets on its own.
+    AUTOPLAY_START: 'autoplay.start',
+    AUTOPLAY_STOP: 'autoplay.stop',
+});
+
+/** The most rounds one autoplay session may hold. */
+export const AUTOPLAY_MAX_ROUNDS = 1000;
+
+/** Events the game may send; none is answered and none is trusted for money. */
+export const GAME_EVENTS = Object.freeze({
+    HELLO: 'hello',
+    READY: 'ready',
+    LOADING: 'loading',
+    REVEALED: 'revealed',
+    FAIRNESS: 'fairness.open',
+    ERROR: 'error',
+});
+
+/** Events the shell sends the game. */
+export const SHELL_EVENTS = Object.freeze({
+    INIT: 'init',
+    BALANCE: 'balance',
+    CONTROL: 'control',
+    PAUSE: 'pause',
+    RESUME: 'resume',
+    ENDED: 'ended',
+    // The autoplay session changed: {active, left, played, stake?, reason?}.
+    // Sent when one starts, after each of its plays, and when it ends
+    // (reason: stopped, done, profit, loss, refused, paused, ended).
+    AUTOPLAY: 'autoplay',
+});
+
+/** Refusal codes the shell answers with. The game shows the message; the
+ * code tells it whether trying again can help. */
+export const ERRORS = Object.freeze({
+    INVALID: 'invalid',             // the request does not validate; never retry
+    BUSY: 'busy',                   // another play/action is still with the server
+    INSUFFICIENT: 'insufficient-balance',
+    LIMITS: 'limits',               // below min, above max, or over the max win
+    PACING: 'pacing',               // too fast; retry after retryAfterMs
+    PENDING: 'pending',             // the wallet has not answered yet; retry after retryAfterMs
+    UNAVAILABLE: 'unavailable',     // the game is paused or the server is down
+    SESSION: 'session-ended',       // the session is over; the shell will say so
+    ROUND: 'round',                 // no such round, it moved on or closed, or one is already open
+                                    // (the refusal carries the round as it stands: redraw it)
+    CONFLICT: 'conflict',           // state.put with a stale revision
+    SERVER: 'server',
+    CLICK: 'needs-click',           // no click of the player's behind the bet, the step, the cash-out
+                                    // or the autoplay request (or a browser that cannot confirm one,
+                                    // or the click was on the shell's own controls); ask again from
+                                    // the player's click handler, after retryAfterMs when given
+    AUTOPLAY: 'autoplay',           // autoplay refused: not allowed for the player, one already
+                                    // running or asked for, cancelled a moment ago (retryAfterMs), or
+                                    // a play outside the session's bet, stake or count
+});
+
+/** The most a saved state may weigh, as the server counts it. */
+export const STATE_MAX_BYTES = 256 * 1024;
+
+/**
+ * The most a player may stake on one bet under the maximum win per round, as
+ * the session's `limits.maxStake[mode][bet]` names it (SPEC §3.1): a decimal
+ * string in the wallet coin at its precision, rounded down by the server so
+ * that stake × the bet's top multiplier stays within the cap. A high
+ * multiplier means a low figure. A figure of 0 is a figure: the server names
+ * it for every bet while the coin has no USD rate to price the cap in, and
+ * refuses every stake meanwhile (503, `unavailable`), so nothing can be
+ * staked until the rate is back. null only when the session names none for
+ * the bet (an older server, a sandbox without limits, a malformed value):
+ * then the coin's `limits.max` alone holds here, and the server is the last
+ * word anyway.
+ */
+export function maxStakeFor(limits, mode, bet) {
+    if (!isObject(limits) || !isObject(limits.maxStake) || !Object.hasOwn(limits.maxStake, mode)) return null;
+    const byMode = limits.maxStake[mode];
+    if (!isObject(byMode) || !Object.hasOwn(byMode, bet)) return null;
+    const v = byMode[bet];
+    const n = typeof v === 'number' ? v : typeof v === 'string' && /^\d+(\.\d+)?$/.test(v) ? Number(v) : NaN;
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+const ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const GROUP_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
+const keysWithin = (o, allowed) => Object.keys(o).every((k) => allowed.includes(k));
+
+/** Body validators: each returns null when the body is acceptable, else why not. */
+const REQUEST_BODY = {
+    [REQUESTS.PLAY]: (b) => {
+        if (!keysWithin(b, ['mode', 'bet', 'amount'])) return 'unknown key';
+        if (typeof b.mode !== 'string' || !SLUG_RE.test(b.mode)) return 'mode';
+        if (typeof b.bet !== 'string' || !SLUG_RE.test(b.bet)) return 'bet';
+        // A 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 a play of 0 is not a play and never reaches the shell's
+        // money path. The SDK refuses it with a reason before it is sent.
+        if (typeof b.amount !== 'number' || !Number.isFinite(b.amount) || b.amount <= 0) return 'amount';
+        return null;
+    },
+    // `step` is the step the game saw the round at (the round's own `step`):
+    // an action decided on an older view is refused, never applied late.
+    [REQUESTS.ACTION]: (b) => {
+        if (!keysWithin(b, ['roundId', 'step', 'action'])) return 'unknown key';
+        if (typeof b.roundId !== 'string' || !UUID_RE.test(b.roundId)) return 'roundId';
+        if (!isCount(b.step)) return 'step';
+        if (b.action !== 'advance' && b.action !== 'cashout') return 'action';
+        return null;
+    },
+    [REQUESTS.ROUND]: (b) => {
+        if (!keysWithin(b, ['roundId'])) return 'unknown key';
+        return typeof b.roundId === 'string' && UUID_RE.test(b.roundId) ? null : 'roundId';
+    },
+    [REQUESTS.STATE_GET]: (b) => (Object.keys(b).length === 0 ? null : 'unknown key'),
+    [REQUESTS.STATE_PUT]: (b) => {
+        if (!keysWithin(b, ['revision', 'data'])) return 'unknown key';
+        if (!isCount(b.revision)) return 'revision';
+        if (!isObject(b.data)) return 'data';
+        if (utf8Length(JSON.stringify(b.data)) > STATE_MAX_BYTES) return 'data too large';
+        return null;
+    },
+    // A session of at most `rounds` plays of one bet (`mode`, `bet`: the run
+    // is for that bet and no other), none above `stake`; the two stops end it
+    // when the session's net result reaches the figure (profit up, loss
+    // down). Every figure is in wallet units.
+    [REQUESTS.AUTOPLAY_START]: (b) => {
+        if (!keysWithin(b, ['mode', 'bet', 'rounds', 'stake', 'stopOnProfit', 'stopOnLoss'])) return 'unknown key';
+        if (typeof b.mode !== 'string' || !SLUG_RE.test(b.mode)) return 'mode';
+        if (typeof b.bet !== 'string' || !SLUG_RE.test(b.bet)) return 'bet';
+        if (!Number.isSafeInteger(b.rounds) || b.rounds < 1 || b.rounds > AUTOPLAY_MAX_ROUNDS) return 'rounds';
+        if (!isMoney(b.stake)) return 'stake';
+        if (b.stopOnProfit !== undefined && !isMoney(b.stopOnProfit)) return 'stopOnProfit';
+        if (b.stopOnLoss !== undefined && !isMoney(b.stopOnLoss)) return 'stopOnLoss';
+        return null;
+    },
+    [REQUESTS.AUTOPLAY_STOP]: (b) => (Object.keys(b).length === 0 ? null : 'unknown key'),
+};
+
+const isMoney = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+
+const GAME_EVENT_BODY = {
+    // The game's page is up and asks for its config; repeated until answered.
+    [GAME_EVENTS.HELLO]: (b) => (Object.keys(b).length === 0 ? null : 'unknown key'),
+    [GAME_EVENTS.READY]: (b) => (Object.keys(b).length === 0 ? null : 'unknown key'),
+    [GAME_EVENTS.LOADING]: (b) => {
+        if (!keysWithin(b, ['group', 'loaded', 'total'])) return 'unknown key';
+        if (typeof b.group !== 'string' || !GROUP_RE.test(b.group)) return 'group';
+        if (!isCount(b.loaded) || !isCount(b.total) || b.loaded > b.total) return 'progress';
+        return null;
+    },
+    // The outcome of a round is on screen; the shell moves the site's header
+    // balance now (or at its own deadline, whichever is first).
+    [GAME_EVENTS.REVEALED]: (b) => {
+        if (!keysWithin(b, ['roundId'])) return 'unknown key';
+        return typeof b.roundId === 'string' && UUID_RE.test(b.roundId) ? null : 'roundId';
+    },
+    [GAME_EVENTS.FAIRNESS]: (b) => {
+        if (!keysWithin(b, ['roundId'])) return 'unknown key';
+        return typeof b.roundId === 'string' && UUID_RE.test(b.roundId) ? null : 'roundId';
+    },
+    [GAME_EVENTS.ERROR]: (b) => {
+        if (!keysWithin(b, ['message'])) return 'unknown key';
+        return typeof b.message === 'string' && b.message.length <= 500 ? null : 'message';
+    },
+};
+
+function utf8Length(s) {
+    return new TextEncoder().encode(s).length;
+}
+
+/**
+ * Validates a message a game sent. Returns the message when the shell may act
+ * on it, else null.
+ */
+export function readGameMessage(data) {
+    if (!isObject(data) || data.hb !== PROTOCOL || !isObject(data.body)) return null;
+    if (data.kind === 'req') {
+        if (!keysWithin(data, ['hb', 'kind', 'id', 'type', 'body'])) return null;
+        if (typeof data.id !== 'string' || !ID_RE.test(data.id)) return null;
+        const check = Object.hasOwn(REQUEST_BODY, data.type) ? REQUEST_BODY[data.type] : null;
+        return check && check(data.body) === null ? data : null;
+    }
+    if (data.kind === 'evt') {
+        if (!keysWithin(data, ['hb', 'kind', 'type', 'body'])) return null;
+        const check = Object.hasOwn(GAME_EVENT_BODY, data.type) ? GAME_EVENT_BODY[data.type] : null;
+        return check && check(data.body) === null ? data : null;
+    }
+    return null;
+}
+
+/**
+ * Validates a message the shell sent. Returns it when the game may act on
+ * it, else null. The game trusts the shell (it is the page that framed it),
+ * so this only guards against foreign or broken messages.
+ */
+export function readShellMessage(data) {
+    if (!isObject(data) || data.hb !== PROTOCOL) return null;
+    if (data.kind === 'res') {
+        if (typeof data.id !== 'string' || !ID_RE.test(data.id) || typeof data.ok !== 'boolean') return null;
+        if (data.ok) return isObject(data.body) ? data : null;
+        return isObject(data.error) && typeof data.error.code === 'string' ? data : null;
+    }
+    if (data.kind === 'evt') {
+        return Object.values(SHELL_EVENTS).includes(data.type) && isObject(data.body) ? data : null;
+    }
+    return null;
+}
+
+export const request = (id, type, body) => ({ hb: PROTOCOL, kind: 'req', id, type, body });
+export const answer = (id, body) => ({ hb: PROTOCOL, kind: 'res', id, ok: true, body });
+// `maxStake` rides on a `limits` refusal over the maximum win per round (SPEC
+// §3.1): the most the bet takes, as the server wrote it (a decimal string at
+// the coin's precision), so the game can set its field to the figure.
+export const refuse = (id, code, message, retryAfterMs, round, maxStake) => {
+    const error = { code, message };
+    if (retryAfterMs > 0) error.retryAfterMs = retryAfterMs;
+    if (round) error.round = round;
+    if (typeof maxStake === 'string' && maxStake !== '') error.maxStake = maxStake;
+    return { hb: PROTOCOL, kind: 'res', id, ok: false, error };
+};
+export const event = (type, body = {}) => ({ hb: PROTOCOL, kind: 'evt', type, body });