hbengine 0.2.3

package/engine-shell/core/router.js

@@ -0,0 +1,917 @@
+/**
+ * The shell's switchboard: game requests in, engine calls out, the site's
+ * header kept in step. Pure — the windows, the engine client and the site
+ * bridge are handed in, so every rule here is tested without a browser.
+ *
+ * Money rules, the same as every House Original's:
+ *   - one bet or action at a time;
+ *   - each gets its own generation (the server's idempotency key), minted
+ *     here — the game cannot choose or replay one;
+ *   - a bet is the player's act (below): no click, no bet;
+ *   - the site's header shows the debit when the bet leaves, and the
+ *     server's balance when the game has revealed the outcome (or at
+ *     REVEAL_DEADLINE_MS, whichever is first), so the header never spoils
+ *     a result and never waits on a game that does not say;
+ *   - a refused bet puts the header back; a bet whose outcome is unknown
+ *     ends the site's round with no balance, which makes the site re-read
+ *     the wallet (balance-reconciliation-request), as Coin Flip does.
+ *
+ * The click gate: nothing happens without the player's click. The game is
+ * untrusted code: a bet it sends on its own (a timer, a trigger on a date, a
+ * round count or a language) must not spend the player's money, and a round
+ * it moves on its own (a step, a cash-out) is not the player's play either.
+ * Browsers hand a click inside the game frame to the frame's ancestors as
+ * transient user activation (HTML "activation notification"), so this
+ * window's navigator.userActivation.isActive is true for a few seconds after
+ * the player clicked or pressed a key in the game. A play and every ladder
+ * action — an `advance` (it risks what the player could cash out) and a
+ * `cashout` alike (a round the player left open is theirs to come back to,
+ * never the game's to close for them) — is taken only while that holds, or
+ * inside an autoplay session the player started and on the session's own
+ * round. Activation alone is too wide, though: the same notification reaches
+ * every same-origin frame of the clicked page, and the shell is served from
+ * the site's own origin, so a click in the site's chat or header arms this
+ * window as much as one in the game; and a press on the shell's own controls
+ * (Stop, Cancel, the reality check's Continue, a key typed in the Provably
+ * Fair dialog) is a trusted interaction in this very window. So a play or an
+ * action needs the player's gesture (`gesture`): activation live, the focus
+ * inside the game frame (`focusInGame`: a click in the frame focuses it; one
+ * in the chat does not), that focus the player's own (`frameFocused`, below),
+ * and no input on the shell's own DOM — or, with the shell on the site's
+ * origin, on the site's page: boot.js listens on the site's document as on
+ * its own, and the site may report a press of its own besides (`site-input`
+ * on its bridge) — in the last ACTIVATION_TTL_MS (`shellInput`, the browsers'
+ * transient-activation lifetime, so a shell or site press's activation is
+ * never mistaken for a game click's). What one gesture can buy is bounded
+ * too: one play per CLICK_MIN_GAP_MS and CLICK_BURST_MAX per
+ * CLICK_BURST_WINDOW_MS; one advance per ADVANCE_MIN_GAP_MS and
+ * ADVANCE_BURST_MAX per window (a hidden trigger must not climb a ladder to
+ * its bust on one tile tap), refused as `pacing` beyond that; a cash-out is
+ * not paced (it only returns money, and there is one per round). A browser
+ * without the API cannot confirm a click, so it bets nothing: the refusal
+ * names the browsers that can.
+ *
+ * The focus must be the player's. A game can move the focus into its own
+ * frame by script (`window.focus()` from inside a cross-origin frame works
+ * in current browsers), and the player's next keystrokes — meant for the
+ * site's chat — would then land in the frame, granting it activation. So the
+ * page tells the router whenever the focus enters the game frame
+ * (`frameFocused`): the player's own focusing (a click, a tap) arrives with
+ * the activation it granted already live, no shell or site press within the
+ * activation's lifetime, and not within that lifetime of the focus leaving
+ * the frame (the page watches the exits too: a game sees its own window blur
+ * when the player tabs out of it and can take the focus straight back, with
+ * the activation of that Tab — a key in the game's own document — still live,
+ * and the shell cannot tell such a return from the player's click back; so
+ * for ACTIVATION_TTL_MS after leaving the frame, only a Tab the page saw
+ * brings the player back in) — a Tab into the frame is the player's (the
+ * page says when the entry followed a Tab), though the Tab itself is a shell
+ * or site key; a focus with no activation behind it was scripted, and no
+ * play or action is taken on that focus (`stolenFocus`) until the player
+ * focuses the frame themselves — the page also blurs a stolen focus back out
+ * of the frame at once, so the keystrokes land on the shell's own document
+ * (shell input: the shadow above) rather than in the game.
+ *
+ * Deny by default. Every request the game may make has a kind
+ * (`REQUEST_KIND`): a read (the round receipt, the saved state read) and a
+ * save (the state write: it moves no money, and the game chooses what it
+ * saves whether on a click or later, so a click would protect nothing — and
+ * BAD CAT saves its profile at boot) are always answered; a play, a ladder
+ * action (advance or cash-out) and the start of autoplay (they move the
+ * player's money, or what is on the table) need the player's click or the
+ * session, gated as above; anything else is refused. The kinds are an
+ * explicit list, so a request type added to the protocol later without a
+ * kind is denied, not waved through — a new money path cannot slip past the
+ * gate.
+ *
+ * Autoplay is the shell's, never the game's — and a run of bets is never one
+ * click away. One player click inside the game (on Spin) gives this window
+ * activation, so activation alone must not buy a hundred bets. The game's
+ * `autoplay.start` therefore starts nothing: it is the player's act, so it
+ * needs the same gesture a play does (a scripted ask with no click behind it
+ * is refused `needs-click`), it is refused while paused and once the session
+ * has ended, and it is paced — a request the player cancelled, or that
+ * expired, cannot be repeated for AUTOPLAY_RETRY_GAP_MS (`pacing`), so the
+ * confirmation cannot be reopened the instant the player closes it
+ * (`autoplay` with `retryAfterMs`: the player said no, they did not click too
+ * much, so it is not `pacing`). Then the shell fails closed unless the
+ * player's rules explicitly allow autoplay (`init.rg.autoplay.allowed ===
+ * true`; absent or false is a no), caps the terms — the per-round stake at
+ * the coin's max bet, at the bet's own exposure cap
+ * (`limits.maxStake[mode][bet]`, SPEC §3.1: the request names the bet, so
+ * the shell applies its figure; a bet whose figure is 0 takes nothing right
+ * now, and the ask is refused `unavailable`) and at the balance the shell
+ * last saw, when it saw one (a deposit made in the site's wallet is invisible
+ * here, so an unknown or empty balance caps nothing: the server refuses the
+ * first play and the session ends `refused`); the rounds at
+ * AUTOPLAY_MAX_ROUNDS; a loss limit required, defaulted
+ * (AUTOPLAY_DEFAULT_LOSS_MULT × the stake) when the game names none and never
+ * above the total the session could stake (a limit the run cannot reach
+ * would be a limit in name only) — and shows the player the shell's own
+ * confirmation with exactly those terms, the bet the run is for (`mode`,
+ * `bet`) among them (`site.autoplayConfirm`, shell DOM the game cannot reach,
+ * cover or pre-fill); while it is up, the game's `fairness.open` is dropped,
+ * so nothing of the shell's can be popped over the terms. The session is
+ * created only when the player presses Start on that confirmation
+ * (`confirmAutoplay`, wired to a real click on the shell's own button), never
+ * from the game's message; Cancel or closing refuses (`cancelAutoplay`). The
+ * confirmation lives AUTOPLAY_CONFIRM_MS, well under the SDK's 60 s answer
+ * timeout: unanswered by then it is dismissed (`site.autoplayDismiss`) and the
+ * game refused, so a Start pressed after the game gave up can never start a
+ * session the game knows nothing of; the reality check and the end of the
+ * session dismiss it the same way. To change the bet, the stake or the terms,
+ * the game asks again and the player confirms again. Once a session runs, the
+ * shell shows its control (rounds left, Stop — shell DOM, through
+ * `site.autoplay`), counts each play against it, refuses a play on another
+ * bet or above its stake, and ends it at the count, at a stop, on any refused
+ * play, on Stop (one click on the shell's control), on the reality check, when
+ * the session ends, after AUTOPLAY_IDLE_MS without a play of the session
+ * (`idle`: the granted bets cannot be saved for when the player is not
+ * looking) and when the page is hidden or goes (`hidden`). The game hears
+ * every change as an `autoplay` event. Plays inside the session need no
+ * click; a ladder round the last play opened keeps the session open until it
+ * closes, and its steps and cash-out are the run the player approved — an
+ * action on any other round (one resumed from an earlier page, one the player
+ * opened by hand) is the player's to take, gesture and all, session or not.
+ *
+ * site.roundEnd gets { corr, generation, amount, outcome, balance, payout }:
+ * outcome 'settled' (balance is the server's figure, or null when the
+ * server did not name it), 'rollback' (the stake was never taken) or
+ * 'unknown' (nobody knows yet; the site must re-read the wallet).
+ *
+ * The fairness dialog is the shell's, not the game's: a game's `fairness.open`
+ * is a request to show it on a round, taken at most once per
+ * FAIRNESS_MIN_GAP_MS and never while paused (the game is untrusted code,
+ * and the other side-effecting messages are gated the same way), and the
+ * dialog itself decides what an open from the game may change (page.js: never
+ * the player's work in it). A game's `round` request is answered with the
+ * settled round as the game may see it: no seed, no hash, no revealed seed
+ * (SPEC §2: the receipt is the dialog's).
+ *
+ * Telemetry: a game's error event is counted on the engine (rgs.telemetry
+ * 'error', its text only in the player's console), and a round still open
+ * when the page goes (unload) is counted as abandoned, once per round: the
+ * one the session resumed (init.activeRound) as much as one opened here.
+ * Counts, never text.
+ */
+import { AUTOPLAY_MAX_ROUNDS, ERRORS, GAME_EVENTS, REQUESTS, SHELL_EVENTS, answer, event, maxStakeFor, readGameMessage, refuse } from '../../engine-sdk/protocol.js';
+
+export const REVEAL_DEADLINE_MS = 8_000;
+// A game in an error loop is counted this many times per launch, then only logged:
+// the server caps a player's day anyway, and the browser is spared the requests.
+export const ERROR_REPORTS_PER_LAUNCH = 20;
+// A game may ask for the fairness dialog this often; the rest is dropped
+// (a bundle posting it in a loop would otherwise hammer the seed and receipt
+// routes under the player's session and keep the modal popping).
+export const FAIRNESS_MIN_GAP_MS = 2_000;
+// What one burst of the player's activation can buy without autoplay: a
+// play every CLICK_MIN_GAP_MS at most, and CLICK_BURST_MAX plays in any
+// CLICK_BURST_WINDOW_MS. A person cannot click faster; a game that sends more
+// per click is spending on its own.
+export const CLICK_MIN_GAP_MS = 600;
+export const CLICK_BURST_MAX = 5;
+export const CLICK_BURST_WINDOW_MS = 5_000;
+// What one gesture can buy in ladder advances: a person taps a tile no faster
+// than about ten times a second, and a ladder that climbs by itself (the crash
+// example) steps about six times a second early on, so an honest climb runs
+// through the tap's few seconds; a bundle firing steps at the server's
+// round-trip (fifty to a hundred per click) is cut to a quarter of them and
+// cannot take the ladder to its bust on one tap.
+export const ADVANCE_MIN_GAP_MS = 100;
+export const ADVANCE_BURST_MAX = 25;
+// How long a browser keeps transient activation after an input (Chrome,
+// Firefox and Safari: 5 s). A trusted input on the shell's own DOM arms this
+// window exactly as a game click does, so for this long after one the shell
+// takes no play on activation alone — it cannot tell the two apart.
+export const ACTIVATION_TTL_MS = 5_000;
+// When the game names no loss limit for an autoplay session, the shell
+// applies one so a run always has a floor: this many times the per-round
+// stake. Shown in the confirmation the player approves.
+export const AUTOPLAY_DEFAULT_LOSS_MULT = 100;
+// How long the shell's confirmation waits for the player. The SDK gives up on
+// an unanswered request after 60 s; the confirmation goes well before that,
+// so a late Start cannot start a session the game has already written off.
+export const AUTOPLAY_CONFIRM_MS = 30_000;
+// After the player cancelled a confirmation (or it expired), the game cannot
+// ask again for this long: a Cancel must close the dialog, not reopen it.
+export const AUTOPLAY_RETRY_GAP_MS = 10_000;
+// A session with no play of its own for this long ends (`idle`): a run the
+// player approved is played now, not held for when they have looked away.
+export const AUTOPLAY_IDLE_MS = 30_000;
+export { AUTOPLAY_MAX_ROUNDS };
+// What a game sees of a settled round (REQUESTS.ROUND): the outcome and the
+// money, never the seeds, the hash or the revealed seed. An allow-list, so a
+// field the receipt gains later does not reach the bundle by default. Nor
+// `forced`: a sandbox marks a round whose outcome was chosen rather than drawn
+// (SPEC §2), which tells a bundle it is being tested, so neither a round nor
+// a play or action answer carries it to the game (the studio's sandbox shows
+// it in the shell's own fairness dialog).
+export const ROUND_FIELDS = Object.freeze(['roundId', 'game', 'mathHash', 'mode', 'bet', 'kind', 'nonce', 'draws', 'multBp', 'payoutMultiplier', 'survived', 'busted', 'step', 'currency', 'amount', 'payout', 'state', 'createdAt', 'settledAt']);
+
+/** The receipt cut to ROUND_FIELDS. */
+export function roundForGame(body) {
+    const out = {};
+    for (const k of ROUND_FIELDS) if (Object.hasOwn(body, k)) out[k] = body[k];
+    return out;
+}
+
+/** A play or action answer as the game may see it: the same, its round without `forced`. */
+export function moneyForGame(body) {
+    if (!body || typeof body !== 'object' || !body.round || typeof body.round !== 'object') return body;
+    const { forced, ...round } = body.round;
+    return { ...body, round };
+}
+
+/**
+ * What the gate does with each request type: 'read' (the round receipt, the
+ * state read) and 'save' (the state write — it moves no money) are always
+ * answered; 'money' (a play, a ladder action — advance and cash-out alike)
+ * needs the player's click or the session's own round and is bounded (a
+ * cash-out is not paced); 'autoplay-start' and
+ * 'autoplay-stop' are the session's own. The map is exhaustive over
+ * REQUESTS, so a type not listed here — a future request added to the
+ * protocol, say — classifies as 'deny' and is refused: no new money path
+ * slips past the gate by default.
+ */
+export const REQUEST_KIND = Object.freeze({
+    [REQUESTS.ROUND]: 'read',
+    [REQUESTS.STATE_GET]: 'read',
+    [REQUESTS.STATE_PUT]: 'save',
+    [REQUESTS.PLAY]: 'money',
+    [REQUESTS.ACTION]: 'money',
+    [REQUESTS.AUTOPLAY_START]: 'autoplay-start',
+    [REQUESTS.AUTOPLAY_STOP]: 'autoplay-stop',
+});
+
+/** The gate's kind for a request type; 'deny' for anything not classified. */
+export function requestKind(type) {
+    return Object.hasOwn(REQUEST_KIND, type) ? REQUEST_KIND[type] : 'deny';
+}
+
+/**
+ * Whether the player's activation is live in this window: true, false, or
+ * null when the browser has no navigator.userActivation (then no click can
+ * be confirmed and the shell bets nothing). The default reads the real
+ * window; tests hand in their own.
+ */
+export function browserActivation(nav = globalThis.navigator) {
+    const ua = nav && nav.userActivation;
+    return ua && typeof ua.isActive === 'boolean' ? ua.isActive : null;
+}
+
+/**
+ * Whether the focus is inside the game frame: the shell's document has the
+ * focus (a descendant frame's focus counts as the document's) and its focused
+ * element is the frame whose window `gameWindow()` names. A click or a tap
+ * inside the frame focuses it; a click in the site's chat around the shell,
+ * or on the shell's own dialogs, does not. Outside a browser (no document,
+ * the tests) there is nothing to check.
+ */
+export function browserFocusInGame(gameWindow, doc = globalThis.document) {
+    if (!doc) return true;
+    if (typeof doc.hasFocus === 'function' && !doc.hasFocus()) return false;
+    const el = doc.activeElement;
+    return !!el && !!el.contentWindow && el.contentWindow === gameWindow();
+}
+
+// The words of the refusals the gate and autoplay answer with, in English;
+// boot.js hands the player's language (host/strings.js, the same keys).
+export const GATE_WORDS = Object.freeze({
+    needsClick: 'A bet needs your click.',
+    browserNoClick: 'This browser cannot confirm your click, so it cannot place a bet. Use a current Chrome, Edge, Safari or Firefox.',
+    tooManyBets: 'Too many bets for one click.',
+    autoplayNotAllowed: 'Autoplay is not available on your account.',
+    autoplayRunning: 'Autoplay is already running. Stop it first.',
+    autoplayOverStake: 'This bet is above the stake autoplay was started with.',
+    autoplayOtherBet: 'This bet is not the one autoplay was started with.',
+    autoplayNoRounds: 'The autoplay session has no rounds left.',
+    autoplayCancelled: 'Autoplay was not started.',
+    // The retry gap after a cancelled or expired confirmation: the player closed
+    // autoplay, they did not click too much, so it is not `tooManyBets`.
+    autoplayAskLater: 'Autoplay was just closed. You can ask again in a moment.',
+});
+
+/**
+ * createRouter({ self, gameWindow, rgs, site, init, newGeneration, setTimer, clearTimer, now, activation, focusInGame, words })
+ *   self         the shell's window (receives the game's messages)
+ *   gameWindow   () => the game iframe's contentWindow, the only accepted sender
+ *   rgs          createRgs(...)
+ *   site         the host bridge: roundStart, roundEnd, ready, fairness, error, ended,
+ *                autoplay, autoplayConfirm, autoplayDismiss
+ *   init         the authenticate answer, handed to the game as its config
+ *   now          the clock the fairness pacing and the click bound read (tests hand in their own)
+ *   activation   () => whether the player's activation is live in the shell's window
+ *                (true/false), or null when the browser cannot say (browserActivation)
+ *   focusInGame  () => whether the focus is inside the game frame (browserFocusInGame)
+ *   words        the refusals' words in the player's language (GATE_WORDS's keys)
+ */
+export function createRouter({ self, gameWindow, gameOrigin = '*', rgs, site, init: initialInit, newGeneration = () => crypto.randomUUID(), setTimer = setTimeout, clearTimer = clearTimeout, now = Date.now, activation = browserActivation, focusInGame = () => browserFocusInGame(gameWindow), words = GATE_WORDS }) {
+    let init = initialInit;
+    const observers = new Set();
+    const observe = (listener) => {
+        if (typeof listener !== 'function') return () => {};
+        observers.add(listener);
+        return () => observers.delete(listener);
+    };
+    const report = (observation) => {
+        for (const listener of observers) {
+            try { listener(observation); } catch { /* observers cannot affect routing */ }
+        }
+    };
+    let moneyBusy = false;
+    // While paused (the reality check), no bet and no action leaves the shell:
+    // a game that ignores the notice, or plays on its own, is refused here.
+    let paused = false;
+    // When the game last had the fairness dialog opened for it.
+    let fairnessAt = -Infinity;
+    // When each play, and each advance, bought by the player's gesture alone
+    // left (the burst bounds).
+    let clickPlays = [];
+    let clickAdvances = [];
+    // When the player last pressed or typed on the shell's own DOM, or on the
+    // site's page around it (shellInput): for ACTIVATION_TTL_MS after it,
+    // activation proves nothing about the game.
+    let lastShellInput = -Infinity;
+    // Whether the focus now in the game frame got there by the game's script
+    // (frameFocused): no play or action rides on it until the player focuses
+    // the frame themselves. `stolenAt` is when the game last entered with no
+    // activation behind it: for ACTIVATION_TTL_MS after, a focus with the
+    // activation live is not taken for the player's either (the game steals, a
+    // keystroke lands in it, it steals again on that keystroke's activation).
+    // An entry under a shell or site press's shadow, or within ACTIVATION_TTL_MS
+    // of the focus leaving the frame (the game taking it back on its own blur),
+    // is refused too, but opens no window of its own: the shadow ends with that
+    // press's activation, the exit's window with the exit's.
+    let stolenFocus = false;
+    let stolenAt = -Infinity;
+    // The autoplay session in force, or null:
+    //   { mode, bet, rounds, left, played, stake, stopOnProfit, stopOnLoss, net, openRound, idle }
+    // `mode`/`bet` the one bet the run is for, `net` the session's result so
+    // far (payouts minus stakes), `openRound` a ladder round of the session
+    // still on the table, `idle` the timer that ends a session nothing is
+    // played in.
+    let auto = null;
+    // A session the game asked for and the shell is showing the player, not yet
+    // started: { id, terms, timer }. The session is created only when the player
+    // presses Start on the shell's own confirmation (confirmAutoplay), never
+    // from the game's message or a click inside the game frame; `timer`
+    // dismisses the confirmation at AUTOPLAY_CONFIRM_MS.
+    let pendingAuto = null;
+    // When a confirmation was last cancelled or dismissed: the game may not ask
+    // again before AUTOPLAY_RETRY_GAP_MS has passed.
+    let autoRefusedAt = -Infinity;
+    // The player's balance as last seen from the server (money answers), the
+    // ceiling a session's stake is capped at. Starts from the launch balance.
+    let lastBalance = init && typeof init.balance === 'number' && init.balance >= 0 ? init.balance : null;
+    const round8 = (n) => Math.round((n + Number.EPSILON) * 1e8) / 1e8;
+    // server round id -> { corr, amount, auto } for a round still open; `auto` is
+    // the session object whose play opened it, or null. The object, not a flag:
+    // a round of a session that has ended stays open on the table (the player
+    // may cash it out by hand later), and it must never be taken for a round of
+    // the session running then — its payout would join that session's result,
+    // and the loss limit the player confirmed for it would stop nothing.
+    const opened = new Map();
+    const reveals = new Map(); // server round id -> the roundEnd it is waiting to send
+    const abandoned = new Set(); // open rounds already counted as abandoned (a page hides more than once: bfcache)
+    // The round the player left open last time is open now (the server resumes it with the
+    // session): left again, it counts as abandoned like one opened on this page.
+    const resumed = init && init.activeRound;
+    if (resumed && typeof resumed.id === 'string' && resumed.state === 'open') opened.set(resumed.id, { corr: newGeneration(), amount: 0, auto: null });
+
+    let ended = false;
+    let errorsCounted = 0;
+    // A refusal to the game; the first one that says the session is over
+    // also ends the game (`ended`), and the site hears it once.
+    const refused = (id, e, request) => {
+        sendRefusal(id, e.code, e.message, e.retryAfterMs, e.round, e.maxStake, request);
+        if (e.code === ERRORS.SESSION && !ended) {
+            ended = true;
+            dismissAutoplay(); // a confirmation still on screen cannot start now: closed, the game refused
+            endAutoplay('ended');
+            toGame(event(SHELL_EVENTS.ENDED, {}));
+            report({ type: 'ended' });
+            site.ended();
+        }
+    };
+    const sendRefusal = (id, code, message, retryAfterMs, round, maxStake, request = { id }) => {
+        toGame(refuse(id, code, message, retryAfterMs, round, maxStake));
+        report({ type: 'refused', code, request });
+    };
+    const toGame = (msg) => {
+        const w = gameWindow();
+        // To the game's own origin (the bundle's, named by the descriptor) and only
+        // to the framed window; the shell's frame-src keeps that window on the bundle.
+        // (A stand with no descriptor origin posts to '*', still to that window only.)
+        if (w) w.postMessage(msg, gameOrigin);
+    };
+    const word = (k) => (words && typeof words[k] === 'string' ? words[k] : GATE_WORDS[k]);
+
+    function settleSite(roundId) {
+        const r = reveals.get(roundId);
+        if (!r) return;
+        reveals.delete(roundId);
+        clearTimer(r.timer);
+        site.roundEnd(r.end, r.round); // the round itself is for the shell's own record, not the site
+        if (r.end.outcome === 'settled') report({ type: 'settled', round: r.round, balance: r.end.balance });
+    }
+
+    // ---- autoplay -------------------------------------------------------------------
+    // What the game and the shell's control are told of the session.
+    const autoState = (reason) => {
+        const s = auto ? { active: true, left: auto.left, played: auto.played, stake: auto.stake } : { active: false, left: 0, played: 0 };
+        if (reason) s.reason = reason;
+        return s;
+    };
+    const tellAutoplay = (reason) => {
+        const s = autoState(reason);
+        toGame(event(SHELL_EVENTS.AUTOPLAY, s));
+        if (site.autoplay) site.autoplay(s);
+    };
+    // The session is over (reason: stopped, done, profit, loss, refused, paused, ended, idle, hidden).
+    function endAutoplay(reason) {
+        if (!auto) return;
+        const last = auto;
+        auto = null;
+        clearTimer(last.idle);
+        const s = { active: false, left: last.left, played: last.played, reason };
+        toGame(event(SHELL_EVENTS.AUTOPLAY, s));
+        if (site.autoplay) site.autoplay(s);
+    }
+    // The session was played in just now: it has AUTOPLAY_IDLE_MS more before it
+    // ends as idle. Armed at the start and after every answer of the session's.
+    function touchAutoplay() {
+        if (!auto) return;
+        clearTimer(auto.idle);
+        auto.idle = setTimer(() => endAutoplay('idle'), AUTOPLAY_IDLE_MS);
+    }
+    // After a session play settled (or a session's ladder round closed): the
+    // stops, and the count once nothing of the session is on the table. A
+    // ladder of the session still open has its stake out and its payout
+    // unknown, so the stops wait for it to close (onAction calls back then):
+    // a loss limit at the session's total would otherwise end the run the
+    // moment its last stake left, with the round still on the table.
+    function autoplaySettled() {
+        if (!auto) return;
+        if (auto.openRound) return tellAutoplay();
+        if (auto.stopOnProfit && auto.net >= auto.stopOnProfit) return endAutoplay('profit');
+        if (auto.stopOnLoss && -auto.net >= auto.stopOnLoss) return endAutoplay('loss');
+        if (auto.left === 0) return endAutoplay('done');
+        tellAutoplay();
+    }
+    // Whether the player's responsible-gambling settings allow autoplay. Fail
+    // closed: only an explicit `true` allows it; the backend serialises
+    // rg.AutoplayAllowed as init.rg.autoplay.allowed (engine.go), and anything
+    // else — absent rg, absent autoplay, false, a non-boolean — is a no.
+    const autoplayAllowed = () => init && init.rg && init.rg.autoplay && init.rg.autoplay.allowed === true;
+
+    // The game asks for a session; the shell does NOT start one. It caps the
+    // terms and shows the player the shell's own confirmation. One player
+    // click inside the game (Spin) gives this window activation, so activation
+    // alone must never buy a run of bets: the session is created only from the
+    // player's real click on the shell's Start (confirmAutoplay), a control in
+    // the shell document the game cannot reach, cover or pre-fill. The ask
+    // itself is the player's act too: it needs their gesture, is refused while
+    // paused or ended, and cannot follow a Cancel for AUTOPLAY_RETRY_GAP_MS —
+    // a modal the game could reopen the instant it closes would hold the
+    // player hostage until they press Start.
+    function onAutoplayStart(id, body) {
+        if (ended) return sendRefusal(id, ERRORS.SESSION, 'the session has ended');
+        if (paused) return sendRefusal(id, ERRORS.BUSY, 'the game is paused');
+        if (!autoplayAllowed()) return sendRefusal(id, ERRORS.AUTOPLAY, word('autoplayNotAllowed'));
+        if (auto) return sendRefusal(id, ERRORS.AUTOPLAY, word('autoplayRunning'));
+        // A confirmation already on screen: the game cannot queue another.
+        if (pendingAuto) return sendRefusal(id, ERRORS.AUTOPLAY, word('autoplayRunning'));
+        // Asked again too soon after a Cancel: refused as the cancel was (the
+        // player just said no), with when it may be asked again — not as
+        // `pacing`, which the panel would show as a rate limit.
+        const since = now() - autoRefusedAt;
+        if (since < AUTOPLAY_RETRY_GAP_MS) return sendRefusal(id, ERRORS.AUTOPLAY, word('autoplayAskLater'), AUTOPLAY_RETRY_GAP_MS - since);
+        const g = gesture();
+        if (g) return sendRefusal(id, g.code, g.message);
+        // Cap the per-round stake at the coin's max bet, at the bet's own
+        // exposure cap and at the balance the shell last saw; cap the rounds;
+        // and require a loss limit — the shell applies a default when none is
+        // named, and never lets it exceed the total the session could stake (a
+        // game naming a limit the run cannot reach would show the player a
+        // floor in name only). The bet's cap is limits.maxStake[mode][bet]
+        // (SPEC §3.1, protocol.js maxStakeFor): the request names the bet, so
+        // the shell applies the figure the server wrote for it; a figure of 0
+        // means the bet takes nothing right now (no USD rate to price the cap
+        // in: the server refuses every stake), so the ask is refused rather
+        // than confirmed at a stake of nothing; a bet the session names no
+        // figure for is capped by the coin's max alone, and the server is the
+        // last word on a play above the cap (`limits`, which ends the session
+        // `refused`). The balance is advisory: the shell never hears of a
+        // deposit made in the site's wallet, so an empty or unknown balance
+        // caps nothing, and the server's own refusal of the first play ends a
+        // session the player cannot afford (`refused`, with the server's
+        // words).
+        const limits = (init && init.limits) || {};
+        const betMax = maxStakeFor(limits, body.mode, body.bet);
+        if (betMax === 0) return sendRefusal(id, ERRORS.UNAVAILABLE, 'this bet takes no stake right now');
+        const caps = [body.stake];
+        if (limits.max > 0) caps.push(limits.max);
+        if (betMax > 0) caps.push(betMax);
+        if (lastBalance > 0) caps.push(lastBalance);
+        const stake = round8(Math.min(...caps));
+        const rounds = Math.min(Math.floor(body.rounds), AUTOPLAY_MAX_ROUNDS);
+        const total = round8(stake * rounds);
+        const stopOnProfit = body.stopOnProfit > 0 ? round8(body.stopOnProfit) : 0;
+        const stopOnLoss = round8(Math.min(body.stopOnLoss > 0 ? body.stopOnLoss : stake * AUTOPLAY_DEFAULT_LOSS_MULT, total));
+        // The bet the run is for is part of the terms: the grant is for that
+        // bet and no other (gate), and the player sees it on the confirmation.
+        const terms = { mode: body.mode, bet: body.bet, rounds, stake, total, stopOnProfit, stopOnLoss };
+        // Unanswered by the player in time, the confirmation goes and the game
+        // is refused — before the SDK gives the request up on its own.
+        pendingAuto = { id, terms, timer: setTimer(() => dismissAutoplay(), AUTOPLAY_CONFIRM_MS) };
+        // The shell shows the player exactly what they are approving. No answer
+        // to the game, and no session, until they press Start or cancel.
+        if (site.autoplayConfirm) site.autoplayConfirm({ ...terms });
+    }
+
+    // The player pressed Start on the shell's own confirmation (a real,
+    // trusted click on shell DOM outside the game frame): the session begins
+    // now, on exactly the terms shown.
+    function confirmAutoplay() {
+        if (!pendingAuto) return;
+        const { id, terms, timer } = pendingAuto;
+        pendingAuto = null;
+        clearTimer(timer);
+        auto = { mode: terms.mode, bet: terms.bet, rounds: terms.rounds, left: terms.rounds, played: 0, stake: terms.stake, stopOnProfit: terms.stopOnProfit, stopOnLoss: terms.stopOnLoss, net: 0, openRound: null, idle: null };
+        touchAutoplay();
+        const session = { mode: auto.mode, bet: auto.bet, rounds: auto.rounds, stake: auto.stake };
+        if (auto.stopOnProfit) session.stopOnProfit = auto.stopOnProfit;
+        if (auto.stopOnLoss) session.stopOnLoss = auto.stopOnLoss;
+        toGame(answer(id, { session }));
+        tellAutoplay();
+    }
+
+    // The player cancelled or closed the confirmation without starting: no
+    // session, and the game's request is refused so it can reset. The game
+    // may not ask again before AUTOPLAY_RETRY_GAP_MS.
+    function cancelAutoplay() {
+        if (!pendingAuto) return;
+        const { id, timer } = pendingAuto;
+        pendingAuto = null;
+        clearTimer(timer);
+        autoRefusedAt = now();
+        sendRefusal(id, ERRORS.AUTOPLAY, word('autoplayCancelled'));
+    }
+
+    // The shell takes the confirmation down itself (its deadline passed, the
+    // reality check, the session ended): the game is refused as on a cancel,
+    // and the dialog is closed for the player.
+    function dismissAutoplay() {
+        if (!pendingAuto) return;
+        cancelAutoplay();
+        if (site.autoplayDismiss) site.autoplayDismiss();
+    }
+
+    // ---- the gate ---------------------------------------------------------------------
+    // Whether the player's gesture is behind a request that arrived now: their
+    // activation is live in this window, the focus is inside the game frame
+    // (so the activation is not the site page's) and got there by the
+    // player's own act (frameFocused: not by the game's script), and nothing
+    // was pressed or typed on the shell's own DOM, or on the site's page
+    // around it, within the activation's lifetime (so it is not the shell's
+    // or the site's). Returns null when it is, else the refusal.
+    function gesture() {
+        const live = activation();
+        if (live === null) return { code: ERRORS.CLICK, message: word('browserNoClick') };
+        if (!live) return { code: ERRORS.CLICK, message: word('needsClick') };
+        if (now() - lastShellInput < ACTIVATION_TTL_MS) return { code: ERRORS.CLICK, message: word('needsClick') };
+        if (!focusInGame()) return { code: ERRORS.CLICK, message: word('needsClick') };
+        if (stolenFocus) return { code: ERRORS.CLICK, message: word('needsClick') };
+        return null;
+    }
+
+    // What one gesture may still buy: the request's own kind within its gap and
+    // its burst. Records the request when it may go. Returns null to allow,
+    // else the `pacing` refusal with when to try again.
+    function burst(list, minGap, max) {
+        const t = now();
+        const kept = list.filter((at) => t - at < CLICK_BURST_WINDOW_MS);
+        const last = kept.at(-1);
+        if (last !== undefined && t - last < minGap) return { kept, e: { code: ERRORS.PACING, message: word('tooManyBets'), retryAfterMs: minGap - (t - last) } };
+        if (kept.length >= max) return { kept, e: { code: ERRORS.PACING, message: word('tooManyBets'), retryAfterMs: kept[0] + CLICK_BURST_WINDOW_MS - t } };
+        kept.push(t);
+        return { kept, e: null };
+    }
+
+    // Whether a play or a ladder action may go now: the player's gesture, or
+    // the session — a session play on the granted bet within the stake and
+    // the count, or an action on the session's own open round. Returns null
+    // to allow, else the refusal.
+    function gate(type, body) {
+        if (auto) {
+            if (type === REQUESTS.PLAY) {
+                if (body.mode !== auto.mode || body.bet !== auto.bet) return { code: ERRORS.AUTOPLAY, message: word('autoplayOtherBet') };
+                if (body.amount > auto.stake) return { code: ERRORS.AUTOPLAY, message: word('autoplayOverStake') };
+                if (auto.left === 0) return { code: ERRORS.AUTOPLAY, message: word('autoplayNoRounds') };
+                return null;
+            }
+            // A step or the cash-out of the ladder the session opened: the run
+            // the player approved. Any other round — one resumed from an earlier
+            // page, one the player opened by hand before the session — is the
+            // player's to move, with their gesture, below.
+            if (auto.openRound && body.roundId === auto.openRound) return null;
+        }
+        const g = gesture();
+        if (g) return g;
+        if (type === REQUESTS.PLAY) {
+            const r = burst(clickPlays, CLICK_MIN_GAP_MS, CLICK_BURST_MAX);
+            clickPlays = r.kept;
+            return r.e;
+        }
+        // A cash-out on the player's gesture is not paced: it only returns
+        // money, and a round has one.
+        if (body.action !== 'advance') return null;
+        // An advance moves nothing out of the wallet, but it risks what is on
+        // the table, so one gesture buys a bounded run of steps, not the ladder.
+        const r = burst(clickAdvances, ADVANCE_MIN_GAP_MS, ADVANCE_BURST_MAX);
+        clickAdvances = r.kept;
+        return r.e;
+    }
+
+    // After a money answer: is the round over, and what does the header say?
+    // `playSession` is the session the play was sent in (null for an action,
+    // and for a play outside a session).
+    function afterMoney(corr, generation, amount, body, playSession) {
+        const round = body.round;
+        const known = typeof body.balance === 'number' && body.balance >= 0 ? body.balance : null;
+        if (known !== null) lastBalance = known; // the stake cap of the next session follows the balance
+        if (!round || typeof round.id !== 'string') return;
+        const was = opened.get(round.id);
+        // The round is the running session's when that session's own play
+        // opened it, or when it carries that session's mark from its opening
+        // (a step is not a session play, but the round keeps its mark, or the
+        // ladder's close would never reach the session's result and the session
+        // would never end `done`). The session is matched by identity: a play
+        // whose answer arrives after its session ended, and a round of an
+        // ended session cashed out while a later one runs, belong to no
+        // session — their payout joins no result, and they hold no stop back.
+        const session = auto !== null && (playSession === auto || !!(was && was.auto === auto)) ? auto : null;
+        if (round.state === 'open') {
+            opened.set(round.id, { corr, amount, auto: session });
+            if (session) session.openRound = round.id;
+            report({ type: 'opened', round });
+            return;
+        }
+        opened.delete(round.id);
+        const payout = typeof round.payout === 'number' ? round.payout : 0;
+        // A session's round closed: its payout joins the session's result
+        // (the stake left it when the play went).
+        if (session) {
+            session.net += payout;
+            if (session.openRound === round.id) session.openRound = null;
+        }
+        const end = { corr, generation, amount, outcome: 'settled', balance: known, payout, roundId: round.id };
+        reveals.set(round.id, { end, round, timer: setTimer(() => settleSite(round.id), REVEAL_DEADLINE_MS) });
+    }
+
+    async function onPlay(id, body) {
+        // No free round: a stake of nothing is refused here as the server
+        // refuses it (code 4, `limits`), whatever the server's version. The
+        // protocol gate (readGameMessage) drops such a play before it gets
+        // here; this is the money path's own word on it.
+        if (!(body.amount > 0)) return sendRefusal(id, ERRORS.LIMITS, 'a stake is required: a round is never played for free', undefined, undefined, undefined, { id, type: REQUESTS.PLAY, body });
+        // The session the play goes in, if any. Held by identity: the answer
+        // may arrive after this session ended, or after a later one began, and
+        // then it touches, settles or ends nothing of the session running.
+        const session = auto;
+        if (session) {
+            session.left--;
+            session.played++;
+            session.net -= body.amount;
+        }
+        const generation = newGeneration();
+        const corr = generation;
+        site.roundStart({ corr, generation, amount: body.amount });
+        const r = await rgs.play(generation, body);
+        const inSession = session !== null && auto === session;
+        if (r.ok) {
+            afterMoney(corr, generation, body.amount, r.body, session);
+            if (inSession) touchAutoplay(); // the session was played in: its idle clock starts over
+            toGame(answer(id, moneyForGame(r.body)));
+            // The answer first, then the session's state: a game reads the
+            // round before it learns the session moved on.
+            if (inSession) autoplaySettled();
+            return;
+        }
+        // Refused: nothing was charged, the header goes back. Unknown: the
+        // site re-reads the wallet.
+        site.roundEnd({ corr, generation, amount: body.amount, outcome: r.unknown ? 'unknown' : 'rollback', balance: null, payout: 0 });
+        refused(id, r.error, { id, type: REQUESTS.PLAY, body });
+        // A session does not run through refusals (no balance, limits, an
+        // outage): it stops, as the Originals' autobet stops.
+        if (inSession) endAutoplay('refused');
+    }
+
+    async function onAction(id, body) {
+        const open = opened.get(body.roundId);
+        const generation = newGeneration();
+        const corr = open ? open.corr : generation;
+        const amount = open ? open.amount : 0;
+        const r = await rgs.action(generation, body);
+        if (r.ok) {
+            afterMoney(corr, generation, amount, r.body, null);
+            // The round is the running session's own (marked with that very
+            // session): a step of its ladder is the session being played, and
+            // the ladder's close may end the session. A round of a session that
+            // has ended, moved by the player's hand, is nobody's.
+            const ofSession = auto !== null && !!open && open.auto === auto;
+            if (ofSession) touchAutoplay();
+            toGame(answer(id, moneyForGame(r.body)));
+            if (ofSession && !opened.has(body.roundId)) autoplaySettled();
+            return;
+        }
+        // A refused action leaves the round as it was; only an unknown one
+        // needs the site to look at the wallet.
+        if (r.unknown) site.roundEnd({ corr, generation, amount, outcome: 'unknown', balance: null, payout: 0 });
+        refused(id, r.error, { id, type: REQUESTS.ACTION, body });
+    }
+
+    // A play or a ladder action: serialised (one in flight), refused while
+    // paused, and gated — every one of them needs the player's click or the
+    // session (a cash-out too: a round the player left open is theirs to come
+    // back to — the server holds it with the session — never the game's to
+    // close for them at a moment of its choosing).
+    async function onMoney(id, type, body) {
+        const request = { id, type, body };
+        if (paused) return sendRefusal(id, ERRORS.BUSY, 'the game is paused', undefined, undefined, undefined, request);
+        if (moneyBusy) return sendRefusal(id, ERRORS.BUSY, 'another bet is still with the server', undefined, undefined, undefined, request);
+        const e = gate(type, body);
+        if (e) return sendRefusal(id, e.code, e.message, e.retryAfterMs, undefined, undefined, request);
+        moneyBusy = true;
+        try {
+            await (type === REQUESTS.PLAY ? onPlay(id, body) : onAction(id, body));
+        } finally {
+            moneyBusy = false;
+        }
+    }
+
+    async function onRequest(msg) {
+        const { id, type, body } = msg;
+        switch (requestKind(type)) {
+            case 'autoplay-start':
+                return onAutoplayStart(id, body);
+            case 'autoplay-stop':
+                // Always taken: stopping is never refused, whoever asks.
+                endAutoplay('stopped');
+                return toGame(answer(id, { stopped: true }));
+            case 'money':
+                return onMoney(id, type, body);
+            case 'save': {
+                // A state write moves no money and the game chooses its content
+                // whenever it saves, so a click would protect nothing; an honest
+                // game saves at boot (BAD CAT migrates its profile) and after
+                // the reveal that followed the click, long after it. Answered
+                // without a click; the server paces and sizes it (409 stale,
+                // 413 too large).
+                const r = await rgs.putState(body);
+                return r.ok ? toGame(answer(id, r.body)) : refused(id, r.error, { id, type, body });
+            }
+            case 'read': {
+                // The game never sees seed material (SPEC §2); the receipt is the dialog's.
+                const r = type === REQUESTS.ROUND ? await rgs.round(body.roundId) : await rgs.getState();
+                return r.ok ? toGame(answer(id, type === REQUESTS.ROUND ? roundForGame(r.body) : r.body)) : refused(id, r.error, { id, type, body });
+            }
+            default:
+                // Deny by default: a type that is not a read, a save, a money
+                // path or the session's own is refused. readGameMessage already
+                // drops a type the protocol does not know; this is the shell's
+                // own last word, so a new request type is never run ungated.
+                return sendRefusal(id, ERRORS.INVALID, 'unknown request');
+        }
+    }
+
+    function onEvent(msg) {
+        const b = msg.body;
+        switch (msg.type) {
+            // The game's page asks for its config (again on every page it
+            // loads, and until answered).
+            case GAME_EVENTS.HELLO: return toGame(event(SHELL_EVENTS.INIT, init));
+            case GAME_EVENTS.READY: return site.ready();
+            case GAME_EVENTS.REVEALED: return settleSite(b.roundId);
+            case GAME_EVENTS.FAIRNESS:
+                // Dropped while paused, like a bet; while the autoplay
+                // confirmation is up (nothing of the shell's is popped over the
+                // terms the player is reading); and paced, since the game is
+                // untrusted and the dialog is the player's.
+                if (paused || pendingAuto || now() - fairnessAt < FAIRNESS_MIN_GAP_MS) return;
+                fairnessAt = now();
+                return site.fairness(b.roundId);
+            case GAME_EVENTS.LOADING: return site.loading(b.group, b.loaded, b.total);
+            case GAME_EVENTS.ERROR:
+                if (errorsCounted++ < ERROR_REPORTS_PER_LAUNCH) rgs.telemetry('error');
+                return site.error(b.message);
+        }
+    }
+
+    function onMessage(e) {
+        if (e.source !== gameWindow()) return;
+        if (gameOrigin !== '*' && e.origin !== gameOrigin) return;
+        const msg = readGameMessage(e.data);
+        if (!msg) return;
+        if (msg.kind === 'req') onRequest(msg).catch(() => sendRefusal(msg.id, ERRORS.SERVER, 'the shell failed', undefined, undefined, undefined, { id: msg.id, type: msg.type, body: msg.body }));
+        else onEvent(msg);
+    }
+
+    self.addEventListener('message', onMessage);
+    return {
+        /** Read-only router observations for shell tools such as sandbox scenarios. */
+        observe,
+        /** The current authenticate answer, including refreshed limits and balance. */
+        init: () => init,
+        /** Whether a round is open now (a ladder in play, the one the session resumed,
+         * or a bet still with the server): the fairness dialog holds the seed rotation,
+         * which the server refuses meanwhile, until it ends. */
+        roundOpen: () => moneyBusy || opened.size > 0,
+        /** The autoplay session as the shell's control shows it. */
+        autoplay: () => autoState(),
+        /** The player pressed Start on the shell's confirmation: the session begins now. Wire
+         * this to a real click on the shell's own control, never to a message from the game. */
+        confirmAutoplay: () => confirmAutoplay(),
+        /** The player cancelled or closed the confirmation: no session. */
+        cancelAutoplay: () => cancelAutoplay(),
+        /** The shell's Stop (its own control, outside the game frame): ends the session at once. */
+        autoplayStop: () => endAutoplay('stopped'),
+        /** A trusted input the player made outside the game frame: on the shell's own DOM, or on
+         * the site's page around the shell (page.js listens on both documents when the shell is a
+         * same-origin frame of the site; the site may also report a press of its own as `site-input`
+         * on its bridge, boot.js). For ACTIVATION_TTL_MS the window's activation is that press's,
+         * not the game's, and no play or action is taken on it — so a bundle that stole the focus
+         * back by script rides nothing from a click or a key in the chat or header. */
+        shellInput: () => { lastShellInput = now(); },
+        /** The focus entered the game frame (the page reads it off document.activeElement). The
+         * player's own focusing — a click or a tap in the frame — comes with the activation it
+         * granted already live, no shell or site press within the activation's lifetime, no
+         * scripted focus of the game's within it either, and not within the lifetime of the focus
+         * last leaving the frame (`sinceExitMs`, as the page saw it: a bundle sees its own window
+         * blur and can take the focus straight back with the activation of the player's last key
+         * in the frame — the Tab that took them out — still live, and the shell cannot tell that
+         * from a click back; so a re-entry within ACTIVATION_TTL_MS of leaving is the player's
+         * only via a Tab the page saw). A Tab into the frame (`viaTab`: the page saw the player's
+         * Tab key just before the entry) is the player's though the Tab itself was a key on the
+         * shell's or the site's document, and whatever the time since leaving — it still needs
+         * the activation live and no scripted entry within the lifetime. Anything else is the
+         * game's script (`window.focus()` from inside the frame): no play or action rides on that
+         * focus until the player focuses the frame themselves. An entry with no activation opens
+         * the ACTIVATION_TTL_MS window in which no entry is the player's; one merely shadowed by
+         * a press, or merely quick after an exit, does not (its cost ends with the press's
+         * activation, or ACTIVATION_TTL_MS after the exit). Fail closed on the time: only a number
+         * of milliseconds at or past the lifetime says the exit is long enough ago; anything else
+         * (NaN, a string) is a quick entry. No time at all (the default) is no exit yet: the frame
+         * was never seen focused before. Returns whether the focus was the player's; the page
+         * blurs a stolen one straight back out of the frame. */
+        frameFocused: (viaTab = false, sinceExitMs = Infinity) => {
+            const noActivation = activation() !== true;
+            const shadowed = viaTab !== true && now() - lastShellInput < ACTIVATION_TTL_MS;
+            const quick = viaTab !== true && !(typeof sinceExitMs === 'number' && sinceExitMs >= ACTIVATION_TTL_MS);
+            if (noActivation) stolenAt = now();
+            stolenFocus = noActivation || shadowed || quick || now() - stolenAt < ACTIVATION_TTL_MS;
+            return !stolenFocus;
+        },
+        /** The page is hidden (visibilitychange): a session is for a player who is looking,
+         * so it ends; a confirmation nobody can see is taken down. */
+        hidden: () => {
+            endAutoplay('hidden');
+            dismissAutoplay();
+        },
+        /** Site → game notices (sound, speed, rules, pause, resume, ended). */
+        tell: (type, body) => {
+            if (type === SHELL_EVENTS.PAUSE) {
+                paused = true;
+                // The reality check is the player's moment to stop: autoplay does not
+                // outlive it, and no confirmation stays up over it.
+                endAutoplay('paused');
+                dismissAutoplay();
+            }
+            if (type === SHELL_EVENTS.RESUME) paused = false;
+            toGame(event(type, body));
+        },
+        balanceChanged: (balance) => {
+            if (typeof balance === 'number' && Number.isFinite(balance) && balance >= 0) lastBalance = balance;
+            toGame(event(SHELL_EVENTS.BALANCE, { balance }));
+        },
+        refreshInit: (nextInit) => {
+            init = nextInit;
+            if (typeof nextInit?.balance === 'number' && Number.isFinite(nextInit.balance) && nextInit.balance >= 0) lastBalance = nextInit.balance;
+        },
+        stop: () => {
+            self.removeEventListener('message', onMessage);
+            for (const id of [...reveals.keys()]) settleSite(id);
+        },
+        /** The page is going (pagehide): the session ends as hidden, and a round still open
+         * is counted as abandoned, once. A page that hides, comes back from the cache and
+         * hides again on the same round counts it once; a round opened in between counts. */
+        unload: () => {
+            endAutoplay('hidden');
+            dismissAutoplay();
+            const fresh = [...opened.keys()].filter((id) => !abandoned.has(id));
+            if (fresh.length === 0) return;
+            for (const id of fresh) abandoned.add(id);
+            rgs.telemetry('abandon');
+        },
+    };
+}