hbengine 0.2.3

package/engine-sdk/ui.js

@@ -0,0 +1,340 @@
+/**
+ * The frontend engine: the House Originals' panel around a studio's zone.
+ * A studio that does not want to build a panel draws only its game and
+ * gets the rest — modes and bets from its math, the stake in the player's
+ * currency, Bet, Auto, Next / Cash out on a ladder, refusals in the
+ * player's language — looking and behaving like Dice or Mines.
+ *
+ *     <hb-game><canvas slot="zone"></canvas></hb-game>
+ *
+ *     import { mount } from './engine-sdk/ui.js';
+ *     const game = await mount(document.querySelector('hb-game'), {
+ *         // A table round is drawn: show it, resolve when it is on screen.
+ *         reveal: (round, zone) => animate(round.data[0]),
+ *         // A ladder round moved (bet, step, cash-out, bust); optional.
+ *         step: (round, zone) => animateStep(round),
+ *         // false: no Next button; the zone climbs a ladder with game.advance() (a crash).
+ *         next: true,
+ *         // Mode and bet names by language (else the math's labels); optional.
+ *         labels: { es: { base: 'Tirada', buy: 'Comprar giros gratis' }, … },
+ *     });
+ *     game.engine;            // the SDK handle (config, money, on, state…)
+ *     game.field;             // the stake field (amount, reason, 'change')
+ *     game.mode / game.bet;   // the selection; a zone may set them
+ *     el.addEventListener('select', (e) => e.detail);   // {mode, bet} whenever it changes
+ *
+ * The panel is the Originals' layout: a 300px column beside the zone on
+ * desktop, the frame's full height (720px, or the screen in fullscreen),
+ * under the zone on a phone. The balance is the site's header. A mode with more than
+ * twelve bets (a dice target) is picked in the zone: it sets game.bet.
+ */
+import { connect, ERRORS } from './sdk.js';
+import { wordsFor } from './bet-field.js';
+import { autoplayRequest, autoplayStop, nextStake } from './autoplay.js';
+
+const CSS = `
+:host { display: block; font-family: var(--hb-font, 'Figtree', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif); color: #F9F9FB; background: #08141a; }
+.card { display: grid; grid-template-columns: 300px minmax(0, 1fr); min-height: 100vh; }
+.panel { display: flex; flex-direction: column; gap: 16px; padding: 20px; padding-inline: max(20px, env(safe-area-inset-left)) max(20px, env(safe-area-inset-right)); background: #0b1f28; border-inline-end: 1px solid #0D2A38; }
+.zone { position: relative; display: grid; place-items: center; min-height: 360px; overflow: hidden; }
+::slotted(*) { max-width: 100%; }
+@media (max-width: 699px) { .card { grid-template-columns: minmax(0, 1fr); min-height: 0; } .zone { order: -1; } .panel { border-inline-end: 0; border-top: 1px solid #0D2A38; padding-bottom: max(20px, env(safe-area-inset-bottom)); } }
+@media (prefers-reduced-motion: reduce) { button { transition: none; } }
+.tabs { display: flex; padding: 3px; gap: 3px; background: rgba(9, 102, 125, 0.15); border-radius: 8px; }
+.tabs button { flex: 1; height: 38px; }
+select.modes { height: 40px; padding: 0 12px; background: #0b1f28; border: 1px solid #0D2A38; border-radius: 8px; color: #F9F9FB; font: inherit; font-size: 14px; font-weight: 600; }
+.picks { display: grid; grid-template-columns: repeat(auto-fit, minmax(88px, 1fr)); gap: 8px; }
+.picks button { height: 48px; flex-direction: column; gap: 0; line-height: 18px; }
+.picks small { font-size: 12px; color: #8F96A8; }
+.counts { display: flex; gap: 4px; }
+.auto { display: grid; gap: 8px; }
+.rule { display: grid; grid-template-columns: 1fr auto; gap: 8px; align-items: center; }
+.rule .tabs { padding: 2px; gap: 2px; }
+.rule .tabs button { height: 28px; padding: 0 8px; font-size: 12px; }
+.rule input { width: 72px; height: 32px; padding: 0 8px; background: #0b1f28; border: 1px solid #0D2A38; border-radius: 8px; color: #F9F9FB; font: inherit; font-size: 14px; text-align: right; }
+.pct { display: inline-flex; align-items: center; gap: 4px; color: #8F96A8; font-size: 12px; }
+.pct input { width: 48px; }
+.counts button { flex: 1; height: 32px; font-size: 12px; }
+button { display: inline-flex; align-items: center; justify-content: center; padding: 0 12px; border: 0; border-radius: 8px; background: rgba(9, 102, 125, 0.15); color: #8F96A8; font: inherit; font-size: 14px; font-weight: 600; cursor: pointer; transition: background 120ms ease, transform 120ms ease; }
+button:hover { background: rgba(9, 102, 125, 0.2); color: #F9F9FB; }
+button:active { transform: scale(0.98); }
+button:disabled { opacity: 0.45; cursor: not-allowed; transform: none; }
+button[aria-pressed="true"] { background: #0D2A38; color: #F9F9FB; }
+.picks button[aria-pressed="true"] { box-shadow: inset 0 0 0 1px #28F3F3; }
+.label { font-size: 14px; line-height: 20px; font-weight: 600; }
+.main { height: 48px; background: #28F3F3; color: #041015; font-size: 16px; }
+.main:hover { background: #5cf6f6; color: #041015; }
+.ladder { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; }
+.ladder [hidden] + .main, .ladder .main:only-child { grid-column: 1 / -1; }
+[hidden] { display: none !important; }
+`;
+
+const COUNTS = [10, 25, 50, 100, 0];
+const mult = (bp) => (bp / 10000).toLocaleString('en-US', { maximumFractionDigits: 2 }) + '×';
+
+class GameElement extends HTMLElement {
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = CSS;
+        root.append(style);
+        const tpl = document.createElement('template');
+        tpl.innerHTML = `<div class="card"><div class="panel" part="panel">
+<div class="tabs" data-tabs></div>
+<div class="tabs" data-modes></div>
+<select class="modes" data-mode-select hidden aria-label="Mode"></select>
+<div class="picks" data-bets></div>
+<hb-bet-amount max-button></hb-bet-amount>
+<div data-auto hidden class="auto">
+<span class="label" data-w="numberOfBets"></span><div class="counts" data-counts></div>
+<div class="rule"><span class="label" data-w="onWin"></span><div class="tabs" data-onwin></div><span class="pct"><input data-onwin-pct inputmode="decimal" placeholder="0">%</span></div>
+<div class="rule"><span class="label" data-w="onLoss"></span><div class="tabs" data-onloss></div><span class="pct"><input data-onloss-pct inputmode="decimal" placeholder="0">%</span></div>
+<div class="rule"><span class="label" data-w="stopOnProfit"></span><input data-stop-profit inputmode="decimal"></div>
+<div class="rule"><span class="label" data-w="stopOnLoss"></span><input data-stop-loss inputmode="decimal"></div>
+</div>
+<button class="main" data-main></button>
+<div class="ladder" data-ladder hidden><button class="main" data-next></button><button class="main" data-cashout></button></div>
+</div><div class="zone" part="zone"><slot name="zone"></slot></div></div>`;
+        root.append(tpl.content);
+    }
+}
+
+if (globalThis.customElements && !customElements.get('hb-game')) customElements.define('hb-game', GameElement);
+
+/** Connects the panel to the engine and the zone's hooks. */
+export async function mount(el, { reveal = async () => {}, step = async () => {}, labels = {}, next = true } = {}) {
+    const [engine] = await Promise.all([connect(), customElements.whenDefined('hb-bet-amount')]);
+    const names = labels[(engine.config.locale || 'en').slice(0, 2)] || labels.en || {};
+    const $ = (sel) => el.shadowRoot.querySelector(sel);
+    const words = wordsFor(engine.config.locale || navigator.language);
+    const field = $('hb-bet-amount').connect(engine);
+    // The stake decides whether Bet can be pressed: the button follows the field.
+    field.addEventListener('change', () => render());
+    const zone = el.querySelector('[slot="zone"]');
+    const modes = engine.config.modes;
+    const sel = { mode: modes[0].id, bet: modes[0].bets[0].id };
+    const modeOf = () => modes.find((m) => m.id === sel.mode);
+    let auto = false, count = 10, left = 0, busy = false, paused = false;
+    // Whether a shell autoplay session of this panel's is running (the shell
+    // counts it and may end it first: its Stop, a stop rule, a refusal).
+    let running = false;
+    const rule = { win: 'reset', loss: 'reset' }; // after a win / a loss: reset the stake, or increase it by the percent
+    let open = engine.config.activeRound || null; // a ladder round in play
+    // The refusal the last money call met, null after one that went: a zone
+    // that drives a ladder reads why its step was refused (`pacing` says when
+    // to go on; `needs-click` says to wait for the player).
+    let lastRefusal = null;
+    const game = {
+        engine, zone, field,
+        get refusal() { return lastRefusal; },
+        get mode() { return sel.mode; },
+        // During a run the selection is the session's (the shell holds every
+        // play to the bet the player approved): a zone's pick waits for it to end.
+        set mode(v) { if (!running && modes.some((m) => m.id === v)) { sel.mode = v; sel.bet = modeOf().bets[0].id; select(); } },
+        get bet() { return sel.bet; },
+        set bet(v) { if (!running && modeOf().bets.some((b) => b.id === v)) { sel.bet = v; select(); } },
+        // A ladder the zone drives itself (a crash climbs on a timer): the
+        // same calls as the panel's buttons, so the panel stays in step.
+        get open() { return open; },
+        advance: () => (open && !busy && !queued ? money(() => engine.action(open, 'advance')) : Promise.resolve(null)),
+        cashout: () => cashout(),
+    };
+    // A cash-out asked for while a step is with the server runs as soon as it answers.
+    let queued = false;
+    function cashout() {
+        if (busy) { queued = true; return Promise.resolve(null); }
+        return open ? money(() => engine.action(open, 'cashout')) : Promise.resolve(null);
+    }
+    // The selection changed (the panel or the zone): the field holds the stake
+    // to the bet's own highest stake under the maximum win, and the zone redraws.
+    const select = () => { field.bet = { mode: sel.mode, bet: sel.bet }; render(); el.dispatchEvent(new CustomEvent('select', { detail: { mode: sel.mode, bet: sel.bet } })); };
+
+    const picker = (box, items, onPick) => {
+        box.hidden = items.length < 2;
+        box.replaceChildren(...items.map((it) => {
+            const b = document.createElement('button');
+            b.type = 'button';
+            b.dataset.id = it.id;
+            b.append(names[it.id] || it.label || it.id);
+            if (it.maxMultBp) b.insertAdjacentHTML('beforeend', `<small>${mult(it.maxMultBp)}</small>`);
+            b.onclick = () => onPick(it.id);
+            return b;
+        }));
+    };
+    const mark = (box, id, lock) => box.querySelectorAll('button').forEach((b) => {
+        b.setAttribute('aria-pressed', b.dataset.id === id);
+        b.disabled = lock;
+    });
+
+    function render() {
+        const m = modeOf();
+        const ladder = open && open.state === 'open';
+        const lock = busy || paused || ladder || left > 0;
+        if ($('[data-bets]').dataset.mode !== m.id) {
+            picker($('[data-bets]'), m.bets.length <= 12 ? m.bets : [], (id) => { game.bet = id; });
+            $('[data-bets]').dataset.mode = m.id;
+        }
+        mark($('[data-modes]'), sel.mode, lock);
+        Object.assign($('[data-mode-select]'), { value: sel.mode, disabled: lock });
+        mark($('[data-bets]'), sel.bet, lock);
+        field.disabled = lock;
+        // Auto is for one-draw modes, where the player's rules allow it
+        // (engine.config.rg.autoplay, the jurisdiction's word): a ladder is
+        // played by hand.
+        const noAuto = m.kind === 'ladder' || (engine.config.rg && engine.config.rg.autoplay && engine.config.rg.autoplay.allowed === false);
+        if (noAuto && auto) { auto = false; mark($('[data-tabs]'), 'manual', false); }
+        $('[data-tabs]').hidden = noAuto;
+        $('[data-auto]').hidden = !auto;
+        const main = $('[data-main]');
+        main.hidden = ladder;
+        main.textContent = left > 0 ? words.stopAutobet : auto ? words.startAutobet : words.bet;
+        // Bet needs a playable stake (never 0: there is no free round); Stop autobet never does.
+        const playable = left > 0 || (field.amount > 0 && !field.reason);
+        main.disabled = paused || (busy && left === 0) || !playable;
+        $('[data-ladder]').hidden = !ladder;
+        if (ladder) {
+            const k = open.step;
+            $('[data-next]').hidden = !next;
+            $('[data-next]').textContent = k < m.steps ? mult(m.ladderBp[k]) : '';
+            $('[data-next]').disabled = paused || busy || k >= m.steps;
+            $('[data-cashout]').hidden = !m.cashout;
+            $('[data-cashout]').textContent = `${words.cashOut} ${k > 0 ? mult(m.ladderBp[k - 1]) : ''}`;
+            $('[data-cashout]').disabled = paused || (busy && next) || k === 0 || queued;
+        }
+    }
+
+    // A refusal under the stake field, in the player's language where the
+    // code has one; a money refusal's message is the server's own.
+    function refused(e) {
+        field.note(e.code === ERRORS.PACING || e.code === ERRORS.BUSY ? words.apiRateLimited
+            : e.code === ERRORS.PENDING ? words.apiRoundUnresolved
+            : e.code === ERRORS.SERVER || e.code === ERRORS.UNAVAILABLE ? words.apiInternalError
+            : e.message);
+        if (e.round) open = e.round;
+        left = 0;
+    }
+
+    async function money(call) {
+        busy = true;
+        render();
+        let round = null;
+        lastRefusal = null;
+        try {
+            ({ round } = await call());
+            open = round.state === 'open' ? round : null;
+        } catch (e) {
+            lastRefusal = e;
+            refused(e);
+        }
+        busy = false;
+        render();
+        if (!round) { queued = false; return null; }
+        await (round.kind === 'ladder' ? step : reveal)(round, zone);
+        if (round.state !== 'open') engine.revealed(round.id);
+        if (queued) { queued = false; if (open) return money(() => engine.action(open, 'cashout')); }
+        return round;
+    }
+
+    function play() {
+        // Never a stake of 0: the field's reason says `min` on an empty
+        // field, and the engine refuses it anyway (there is no free round).
+        if (field.reason || !(field.amount > 0)) { if (field.reason) field.note(field.reason.message); return null; }
+        return money(() => engine.play({ mode: sel.mode, bet: sel.bet, amount: field.amount }));
+    }
+
+    // A run: the Originals' rules — on win / on loss the stake resets or
+    // grows by a percent; it stops at a profit or a loss the player named,
+    // on any refusal, or when the player says so. The run is a shell
+    // autoplay session (autoplay.js): asked for on the Start press, which is
+    // the player's click; the shell counts its rounds, caps its stake, shows
+    // its own Stop over the game and ends it first when a stop or a refusal
+    // comes — the panel follows (`autoplay` event). Its own Stop asks the shell.
+    async function run() {
+        if (left > 0) return stopRun();
+        if (!auto) return play();
+        if (field.reason || !(field.amount > 0)) { if (field.reason) field.note(field.reason.message); return null; }
+        const base = field.amount;
+        const pct = (sel) => Math.max(0, Number($(sel).value) || 0);
+        const winPct = pct('[data-onwin-pct]'), lossPct = pct('[data-onloss-pct]');
+        const stopProfit = engine.money.parse($('[data-stop-profit]').value), stopLoss = engine.money.parse($('[data-stop-loss]').value);
+        // A growing run asks for the most it could stake: the coin's max, the
+        // selected bet's own ceiling under the maximum win (field.maxStake; the
+        // shell caps the grant at it too, since the request names the bet) and
+        // the balance.
+        const req = autoplayRequest({ mode: sel.mode, bet: sel.bet, amount: base, count, rule, winPct, lossPct, stopProfit, stopLoss, limits: engine.config.limits, balance: engine.balance, maxStake: field.maxStake });
+        // The shell shows the player the terms and answers on their Start (or
+        // Cancel): the panel waits, its buttons held, so a second press cannot
+        // ask twice.
+        busy = true;
+        render();
+        let session;
+        try {
+            ({ session } = await engine.autoplay.start(req));
+        } catch (e) {
+            busy = false;
+            refused(e);
+            return null;
+        }
+        busy = false;
+        // The shell may have capped the terms (the coin's max, the balance, a
+        // loss limit of its own when none was set): the run keeps to the grant
+        // — the stops are the session's, so the panel never sends a play the
+        // shell would refuse because the session ended on its loss limit.
+        req.rounds = session.rounds;
+        req.stake = session.stake;
+        const stops = { stopProfit: session.stopOnProfit > 0 ? session.stopOnProfit : stopProfit, stopLoss: session.stopOnLoss > 0 ? session.stopOnLoss : stopLoss };
+        running = true;
+        let profit = 0;
+        for (left = req.rounds; left > 0 && running && !paused; left--) {
+            render();
+            const round = await play();
+            if (!round || !running || paused) break;
+            profit += round.payout - round.amount;
+            if (autoplayStop({ profit, ...stops })) break;
+            field.amount = nextStake({ amount: field.amount, base, won: round.payout > round.amount, rule, winPct, lossPct, cap: req.stake, decimals: engine.money.walletDecimals });
+        }
+        stopRun();
+    }
+    // The run is over, by the panel or by the shell: the session is released
+    // (a stop asked twice is harmless) and the panel is a bet panel again.
+    function stopRun() {
+        const was = running;
+        running = false;
+        left = 0;
+        render();
+        if (was) engine.autoplay.stop().catch(() => {});
+    }
+
+    // Up to four modes are tabs; more (plinko's rows × risks) are one select, as the Originals do.
+    if (modes.length > 4) {
+        const s = $('[data-mode-select]');
+        s.replaceChildren(...modes.map((m) => new Option(names[m.id] || m.label || m.id, m.id)));
+        s.hidden = false;
+        $('[data-modes]').hidden = true;
+        s.onchange = () => { game.mode = s.value; };
+    } else picker($('[data-modes]'), modes, (id) => { game.mode = id; });
+    picker($('[data-tabs]'), [{ id: 'manual', label: words.manual }, { id: 'auto', label: words.auto }], (id) => { auto = id === 'auto'; left = 0; mark($('[data-tabs]'), id, false); render(); });
+    mark($('[data-tabs]'), 'manual', false);
+    for (const w of el.shadowRoot.querySelectorAll('[data-w]')) w.textContent = words[w.dataset.w];
+    picker($('[data-counts]'), COUNTS.map((n) => ({ id: String(n), label: n ? String(n) : '∞' })), (id) => { count = Number(id); mark($('[data-counts]'), id, false); });
+    mark($('[data-counts]'), '10', false);
+    for (const [key, box] of [['win', '[data-onwin]'], ['loss', '[data-onloss]']]) {
+        picker($(box), [{ id: 'reset', label: words.reset }, { id: 'increase', label: words.increase }], (id) => { rule[key] = id; mark($(box), id, false); });
+        mark($(box), 'reset', false);
+    }
+    $('[data-main]').onclick = run;
+    $('[data-next]').onclick = () => money(() => engine.action(open, 'advance'));
+    $('[data-cashout]').onclick = () => { cashout(); render(); };
+    engine.on('pause', () => { paused = true; render(); });
+    engine.on('resume', () => { paused = false; render(); });
+    engine.on('ended', () => { busy = true; left = 0; render(); });
+    // The first selection's own ceiling: a 5,000× bet takes less than a 2× one.
+    field.bet = { mode: sel.mode, bet: sel.bet };
+    // The shell ended the session (its Stop, a stop rule, a refusal, the reality check).
+    engine.on('autoplay', (s) => { if (!s.active && running) { running = false; left = 0; render(); } });
+    render();
+    if (open) await step(open, zone);
+    engine.ready();
+    return game;
+}

package/engine-shell/core/faults.js

@@ -0,0 +1,127 @@
+/**
+ * Sandbox faults for ADR 0006.
+ *
+ * The wrapper sits around the fetch passed to createRgs so refusal() and the
+ * lost-answer retries run unchanged, just as they do for a real response.
+ * Every request passes through untouched until the sandbox panel arms a fault.
+ */
+
+const BODY = Object.freeze({
+    session: { code: 'session-expired', error: 'session expired (sandbox test)' },
+    server: { error: 'server error (sandbox test)' },
+    unavailable: { error: 'unavailable (sandbox test)' },
+});
+
+function response(status, body) {
+    const text = body === undefined ? '' : JSON.stringify(body);
+    if (typeof Response === 'function') {
+        return new Response(text, { status, headers: { 'Content-Type': 'application/json' } });
+    }
+    return { status, ok: status < 400, json: async () => body };
+}
+
+function requestUrl(input) {
+    if (typeof input === 'string') return input;
+    return input && input.url;
+}
+
+function affectedPath(input, init) {
+    try {
+        const pathname = new URL(requestUrl(input), globalThis.location?.href).pathname;
+        const marker = pathname.indexOf('/engine/v1/');
+        if (marker < 0) return null;
+        const method = String(init?.method || input?.method || 'GET').toUpperCase();
+        const path = pathname.slice(marker + '/engine/v1/'.length);
+        if (method !== 'POST' || !['play', 'action', 'end-round', 'balance'].includes(path)) return null;
+        return path;
+    } catch {
+        return null;
+    }
+}
+
+function abortError() {
+    return new DOMException('The operation was aborted.', 'AbortError');
+}
+
+function timeout(signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        signal?.addEventListener('abort', () => reject(abortError()), { once: true });
+    });
+}
+
+function slow(realFetch, input, init, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => realFetch(input, init).then(resolve, reject), ms);
+        init?.signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(abortError());
+        }, { once: true });
+    });
+}
+
+function syntheticFault(fault, realFetch, input, init) {
+    if (fault.kind === 'session') return Promise.resolve(response(401, BODY.session));
+    if (fault.kind === 'server') return Promise.resolve(response(500, BODY.server));
+    if (fault.kind === 'unavailable') return Promise.resolve(response(503, BODY.unavailable));
+    if (fault.kind === 'timeout') return timeout(init?.signal);
+    if (fault.kind === 'slow') return slow(realFetch, input, init, fault.ms);
+    return realFetch(input, init);
+}
+
+/** Creates the inert fetch wrapper controlled by the sandbox test panel. */
+export function createFaults(realFetch) {
+    let armed = null;
+    const listeners = new Set();
+
+    function notify() {
+        const snapshot = armed ? { ...armed } : null;
+        for (const listener of listeners) {
+            try {
+                listener(snapshot);
+            } catch {
+                // Status observers cannot affect fault injection.
+            }
+        }
+    }
+
+    function fetch(input, init = {}) {
+        const path = affectedPath(input, init);
+        if (!armed || !path || (armed.only && armed.only !== path)) return realFetch(input, init);
+        const fault = armed;
+        fault.times -= 1;
+        if (fault.times <= 0) armed = null;
+        notify();
+        return syntheticFault(fault, realFetch, input, init);
+    }
+
+    function arm(kind, opts = {}) {
+        armed = {
+            kind,
+            times: Number.isInteger(opts.times) && opts.times > 0 ? opts.times : 1,
+            ms: Number.isFinite(opts.ms) ? opts.ms : 3000,
+            ...(typeof opts.only === 'string' ? { only: opts.only } : {}),
+        };
+        notify();
+    }
+
+    function clear() {
+        armed = null;
+        notify();
+    }
+
+    function state() {
+        return armed ? { ...armed } : null;
+    }
+
+    function onChange(listener) {
+        if (typeof listener !== 'function') return () => {};
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    }
+
+    return { fetch, arm, clear, state, onChange };
+}

package/engine-shell/core/rgs.js

@@ -0,0 +1,193 @@
+/**
+ * The shell's client of the engine API (/engine/v1). The only code that
+ * holds the session id; the game never sees it.
+ *
+ * Every refusal comes back as { code, message, retryAfterMs? } with `code`
+ * one of the protocol's ERRORS, so the game reads one scheme whatever the
+ * server said. A play or an action whose answer was lost (the network, a
+ * timeout, a 5xx) is asked again with the SAME generation: the server
+ * answers a generation it has seen with the round it stored, so asking
+ * twice can never bet twice. A seed rotation is retried the same way under
+ * its generation, so asking twice can never rotate twice.
+ */
+import { ERRORS } from '../../engine-sdk/protocol.js';
+
+const DEADLINE_MS = 10_000;
+const LOST_ANSWER_RETRIES = 2;
+const LOST_ANSWER_BACKOFF_MS = 600;
+
+// Over the maximum win per round (SPEC §3.1, internal/constants/error.go
+// MaxPayoutErrCode): the body names the most the bet takes (`maxStake`).
+const MAX_PAYOUT_CODE = 21;
+
+// The backend's numeric bet codes (internal/constants/error.go).
+const BET_CODES = new Map([
+    [1, ERRORS.LIMITS], // max win at start
+    [3, ERRORS.LIMITS], // above max bet
+    [4, ERRORS.LIMITS], // below min bet
+    [6, ERRORS.INVALID], // bet parameters
+    [7, ERRORS.PACING], // duplicate inside the dedup window
+    [8, ERRORS.PACING], // previous bet still settling
+    [9, ERRORS.PENDING], // wallet answer ambiguous; the reconciler resolves it
+    [10, ERRORS.INVALID], // more decimals than the currency has
+    [11, ERRORS.INVALID], // stake rounds to zero
+    [12, ERRORS.INVALID], // negative stake
+    [13, ERRORS.PACING],
+    [15, ERRORS.UNAVAILABLE], // rate unavailable
+    [16, ERRORS.PACING], // throttled
+    [17, ERRORS.ROUND], // a round is in progress
+    [18, ERRORS.UNAVAILABLE], // idempotency guard unavailable
+    [19, ERRORS.ROUND], // round moved
+    [20, ERRORS.ROUND], // round open in another currency
+    [MAX_PAYOUT_CODE, ERRORS.LIMITS], // over the maximum win per round: the body names the most the bet takes
+]);
+
+// The most a bet takes, as a refusal over the maximum win names it: a plain
+// decimal string in the coin, as the server wrote it.
+const DECIMAL_RE = /^\d+(\.\d+)?$/;
+
+/** Turns a refused HTTP answer into a protocol refusal. */
+export function refusal(status, body) {
+    const message = body && typeof body.error === 'string' ? body.error : '';
+    const retryAfterMs = body && Number.isSafeInteger(body.retryAfterMs) ? body.retryAfterMs : 0;
+    // A refusal about a round carries it as it stands: `round` (codes 17 and
+    // 19) or `game` (code 20, a round in another currency).
+    const round = body && typeof body === 'object' ? (body.round ?? body.game) : undefined;
+    // A refusal over the maximum win per round carries the most the bet
+    // takes, so the game can set its field to the figure; no other does.
+    const maxStake = body && body.code === MAX_PAYOUT_CODE && typeof body.maxStake === 'string' && DECIMAL_RE.test(body.maxStake) ? body.maxStake : undefined;
+    const out = (code) => {
+        const e = { code, message };
+        if (retryAfterMs > 0) e.retryAfterMs = retryAfterMs;
+        if (round && typeof round === 'object') e.round = round;
+        if (maxStake !== undefined) e.maxStake = maxStake;
+        return e;
+    };
+    const code = body ? body.code : undefined;
+    if (typeof code === 'number' && BET_CODES.has(code)) return out(BET_CODES.get(code));
+    if (status === 401 || status === 403 || (typeof code === 'string' && code.startsWith('session-'))) return out(ERRORS.SESSION);
+    if (status === 409) return out(ERRORS.CONFLICT);
+    if (status === 404) return out(ERRORS.ROUND);
+    if (status === 429) return out(ERRORS.PACING);
+    if (status === 503) return out(ERRORS.UNAVAILABLE);
+    if (status === 400 && /insufficient/i.test(message)) return out(ERRORS.INSUFFICIENT);
+    if (status >= 400 && status < 500) return out(ERRORS.INVALID);
+    return out(ERRORS.SERVER);
+}
+
+/**
+ * createRgs({ base, sessionId, fetch, sleep }) — base is the engine API's
+ * origin + path prefix, e.g. "https://games.housebets.com/engine/v1".
+ */
+export function createRgs({ base, sessionId, fetch: doFetch = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+    async function call(method, path, body, { includeStatus = false } = {}) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), DEADLINE_MS);
+        try {
+            const res = await doFetch(base + path, {
+                method,
+                headers: { Authorization: `Bearer ${sessionId}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: ctrl.signal,
+                credentials: 'omit',
+                cache: 'no-store',
+            });
+            let json = null;
+            try {
+                json = await res.json();
+            } catch {
+                json = null;
+            }
+            if (res.ok && res.status === 204) return { ok: true, body: {}, ...(includeStatus ? { status: res.status } : {}) };
+            if (res.ok && json && typeof json === 'object') return { ok: true, body: json, ...(includeStatus ? { status: res.status } : {}) };
+            // A 2xx whose body did not arrive whole is an answer lost on the
+            // way, not a refusal: the server may have settled, so it is asked
+            // again under the same generation.
+            if (res.ok) return { ok: false, lost: true, error: { code: ERRORS.SERVER, message: 'the answer did not arrive whole' }, ...(includeStatus ? { status: res.status } : {}) };
+            return { ok: false, lost: res.status >= 500 && res.status !== 503, error: refusal(res.status, json), ...(includeStatus ? { status: res.status } : {}) };
+        } catch {
+            return { ok: false, lost: true, error: { code: ERRORS.SERVER, message: 'no answer from the server' } };
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    // A call that is safe to repeat only under its own generation: the
+    // server stores the answer by it and replays it, so a lost answer is
+    // asked for again; a refusal is final and asked once.
+    async function retried(method, path, body) {
+        let r = await call(method, path, body);
+        let retried = false;
+        for (let i = 0; i < LOST_ANSWER_RETRIES && !r.ok && r.lost; i++) {
+            await sleep(LOST_ANSWER_BACKOFF_MS * (i + 1));
+            r = await call(method, path, body);
+            retried = true;
+        }
+        return { r, retried };
+    }
+
+    // A money call is safe to repeat only under its own generation.
+    async function money(path, body) {
+        let { r, retried: again } = await retried('POST', path, body);
+        // A retry that meets the first attempt still in flight (or already
+        // claimed) learns nothing about the outcome either; and "pending" is
+        // the server saying the wallet's answer was ambiguous — the
+        // reconciler decides, so nobody may treat the stake as returned.
+        const stillOpen = again && !r.ok && r.error.code === ERRORS.PACING;
+        if (!r.ok && (r.lost || stillOpen || r.error.code === ERRORS.PENDING)) {
+            // Still no answer: the round may or may not exist. The wallet
+            // and the reconciler settle it; the game must not guess.
+            return { ok: false, unknown: true, error: { code: ERRORS.PENDING, message: 'the bet is being checked' } };
+        }
+        return r;
+    }
+
+    // A seed rotation under its generation: a lost answer is asked for again
+    // (the server replays the stored answer, never rotating twice); when it is
+    // still lost the dialog is told so (`lost`) and keeps the generation for
+    // the player's next press, which the server will answer as the first.
+    async function rotation(method, path, body) {
+        const { r } = await retried(method, path, body);
+        return r;
+    }
+
+    return {
+        authenticate: (lang) => call('POST', '/authenticate', lang ? { lang } : {}),
+        balance: () => call('POST', '/balance', {}),
+        play: (generation, { mode, bet, amount }) => money('/play', { generation, mode, bet, amount }),
+        action: (generation, { roundId, step, action }) => money('/action', { generation, roundId, step, action }),
+        round: (roundId) => call('GET', `/fairness/${encodeURIComponent(roundId)}`),
+        // The player's seed pair for this game, under the session: the shell's
+        // provably-fair dialog alone calls these (the game has no request for
+        // them), so the player's site token never has to come back to the page.
+        //   seeds          {serverSeedHash, nextServerSeedHash, clientSeed, nonce, totalBets,
+        //                   previous: {serverSeed, serverSeedHash, clientSeed, nonce, retiredAt} | null}
+        //   setClientSeed  retires the pair (revealed as `previous`) and starts a fresh one,
+        //                  at nonce 0, under the new client seed — a rotation
+        //   rotateSeeds    the same, keeping the client seed
+        // Both take a generation (the dialog mints one per attempt): the server
+        // answers a generation it has seen with the answer it stored.
+        seeds: () => call('GET', '/seeds'),
+        setClientSeed: (generation, clientSeed) => rotation('PUT', '/seeds/client', { generation, clientSeed }),
+        rotateSeeds: (generation) => rotation('POST', '/seeds/rotate', { generation }),
+        getState: () => call('GET', '/state'),
+        putState: ({ revision, data }) => call('PUT', '/state', { revision, data }),
+        // Sandbox only (the server refuses it anywhere else): the next round resolves to these rows.
+        force: (indices, mode) => call('POST', '/sandbox/force', { indices, ...(mode ? { mode } : {}) }),
+        clearForce: () => call('DELETE', '/sandbox/force', undefined, { includeStatus: true }),
+        sandboxBalance: (amount) => call('POST', '/sandbox/balance', { amount: String(amount) }),
+        // A signal about the game (boot, error, abandon, slow), counted on the server per
+        // game and day and never kept as text: the kind is all that leaves. Fire and forget,
+        // with keepalive so the one sent as the page closes still goes. Resolves either way.
+        telemetry: (kind) => Promise.resolve()
+            .then(() => doFetch(base + '/telemetry', {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${sessionId}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ kind }),
+                keepalive: true,
+                credentials: 'omit',
+                cache: 'no-store',
+            }))
+            .then(() => undefined, () => undefined),
+    };
+}