hbengine 0.2.3 → 0.4.0

package/engine-sdk/progress.js

@@ -0,0 +1,128 @@
+/**
+ * engine.progress: the player's saved progress (skins, settings, a
+ * collection, achievements), kept on the server through engine.state so it is
+ * there on every device and in every version of the game. Browser storage is
+ * not: each version is served from its own origin, so localStorage starts
+ * empty on every new version (GUIDE §3.1, "Saving player progress").
+ *
+ *   await engine.progress.ready;                 // loaded; nothing is saved before
+ *   engine.progress.get('skins', []);            // a value, or the fallback
+ *   engine.progress.set('skin', 'tabby');        // saved within ~2 s, and when the page goes
+ *   engine.progress.update('wins', (n = 0) => n + 1);
+ *   await engine.progress.flush();               // save now (before leaving a screen, say)
+ *   await engine.progress.migrate(['my-game-v1']); // once: localStorage keys moved to the server
+ *
+ * What it does for you: never saves before the server's copy is loaded (an
+ * empty page never overwrites a player's progress); batches writes; on a
+ * stale revision (another tab saved) reloads, puts your pending changes on
+ * top and saves again; refuses a value that would take the whole above the
+ * server's limit before the server does. Progress lives under `progress` in
+ * the state document; anything else a game keeps there is left as it is.
+ *
+ * Progress never changes what a round pays: it is cosmetic. Progress that
+ * pays is a meter (GUIDE §2.2), kept by the engine with the round.
+ */
+import { STATE_MAX_BYTES } from './protocol.js';
+
+const utf8 = (s) => new TextEncoder().encode(s).length;
+
+/**
+ * createProgress(state, { delay, setTimer, clearTimer, storage, onError })
+ *   state      engine.state ({ get, put })
+ *   delay      ms between a change and its save (2000)
+ */
+export function createProgress(state, { delay = 2000, setTimer = setTimeout, clearTimer = clearTimeout, storage = globalThis.localStorage, onError = () => {} } = {}) {
+    let revision = 0, doc = {}, values = {};
+    const pending = new Map(); // key → value (undefined: delete)
+    let timer = null, saving = null, loaded = false;
+
+    const read = (s) => {
+        revision = s.revision || 0;
+        doc = s.data && typeof s.data === 'object' && !Array.isArray(s.data) ? s.data : {};
+        values = doc.progress && typeof doc.progress === 'object' && !Array.isArray(doc.progress) ? { ...doc.progress } : {};
+    };
+    const withPending = () => {
+        const out = { ...values };
+        for (const [k, v] of pending) if (v === undefined) delete out[k]; else out[k] = v;
+        return out;
+    };
+    const ready = state.get().then((s) => { read(s); loaded = true; });
+
+    function schedule() {
+        if (timer !== null) return;
+        timer = setTimer(() => { timer = null; flush().catch(onError); }, delay);
+    }
+
+    async function save() {
+        await ready;
+        for (let attempt = 0; pending.size && attempt < 5; attempt++) {
+            const sent = new Map(pending);
+            const next = withPending();
+            try {
+                const r = await state.put(revision, { ...doc, progress: next });
+                read(r);
+                for (const [k, v] of sent) if (pending.get(k) === v) pending.delete(k);
+            } catch (e) {
+                if (!e || e.code !== 'conflict') throw e;
+                // Another tab or device saved first: theirs, then ours on top.
+                read(await state.get());
+            }
+        }
+    }
+
+    function flush() {
+        if (timer !== null) { clearTimer(timer); timer = null; }
+        if (saving) return saving.then(() => (pending.size ? flush() : undefined));
+        if (!pending.size) return ready;
+        saving = save().finally(() => { saving = null; });
+        return saving;
+    }
+
+    function set(key, value) {
+        if (typeof key !== 'string' || !key) throw new TypeError('progress: a key is a non-empty string');
+        if (value !== undefined) JSON.stringify(value); // throws on what cannot be saved
+        const trial = { ...withPending() };
+        if (value === undefined) delete trial[key]; else trial[key] = value;
+        if (utf8(JSON.stringify({ ...doc, progress: trial })) > STATE_MAX_BYTES) throw new RangeError(`progress: saving "${key}" would pass the ${STATE_MAX_BYTES / 1024} KB a player's saved data may take`);
+        pending.set(key, value);
+        if (loaded) schedule(); else ready.then(schedule);
+    }
+
+    if (typeof addEventListener === 'function') {
+        addEventListener('pagehide', () => { if (pending.size) flush().catch(() => {}); });
+    }
+
+    return Object.freeze({
+        ready,
+        get: (key, fallback) => { const v = withPending()[key]; return v === undefined ? fallback : v; },
+        set,
+        update: (key, fn) => { const v = withPending()[key]; set(key, fn(v)); },
+        remove: (key) => set(key, undefined),
+        keys: () => Object.keys(withPending()),
+        flush,
+        /**
+         * Moves values a game kept in localStorage to the server, once: a key
+         * the server already has is left as the server has it. The keys are
+         * removed from localStorage once saved.
+         */
+        async migrate(keys) {
+            await ready;
+            if (!storage) return [];
+            const moved = [];
+            for (const k of keys) {
+                let raw = null;
+                try { raw = storage.getItem(k); } catch { raw = null; }
+                if (raw === null || withPending()[k] !== undefined) continue;
+                let value = raw;
+                try { value = JSON.parse(raw); } catch { /* kept as text */ }
+                set(k, value);
+                moved.push(k);
+            }
+            if (moved.length) {
+                await flush();
+                for (const k of moved) { try { storage.removeItem(k); } catch { /* gone already */ } }
+            }
+            return moved;
+        },
+    });
+}

package/engine-sdk/protocol.js

@@ -33,6 +33,8 @@ export const REQUESTS = Object.freeze({
     ROUND: 'round',
     STATE_GET: 'state.get',
     STATE_PUT: 'state.put',
+    // The player's meters of this game in the session's coin (GUIDE: Meters).
+    METERS_GET: 'meters.get',
     // 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
@@ -154,6 +156,7 @@ const REQUEST_BODY = {
         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.METERS_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';

package/engine-sdk/sdk.d.ts

@@ -51,8 +51,23 @@ export interface Round {
     data: any[];
     payout?: string; multBp?: number; payoutMultiplier?: number; settledAt?: string;
     survived?: number; busted?: boolean;
+    /** A round of a mode with a meter: the meter before and after it, and the award when this round filled it. */
+    meter?: RoundMeter;
 }
 
+/** A meter's state, in the coin, as decimal strings. */
+export interface MeterValue { filled: string; target: string; reference: string }
+
+/** What a round did to its meter (GUIDE: Meters). */
+export interface RoundMeter {
+    id: string; label?: string; fill?: number; before: MeterValue; after: MeterValue;
+    /** The award this round paid (already in `payout`): `multBp` of `reference`, its draw and its row's data. */
+    award?: { reference: string; multBp: number; payout: number; draw: { index: number; raw: string; rejected: number; draw: number }; data: any };
+}
+
+/** One meter as engine.meters() reads it. `anchorCap`: the largest reference a new meter starts at in this coin. */
+export interface Meter extends MeterValue { id: string; label?: string; fill: number; anchorCap: string }
+
 /** Money exactly as the House Originals show it, in the player's coin or fiat. Amounts are wallet units. */
 export interface Money {
     coin: string; isFiat: boolean; unit: string; sign: string; mark: string;
@@ -108,6 +123,10 @@ export interface Engine {
     readonly balance: number | null;
     /** The player's saved data; neither call needs a click (a save moves no money). */
     readonly state: { get(): Promise<{ revision: number; data: unknown }>; put(revision: number, data: unknown): Promise<{ revision: number; data: unknown }> };
+    /** The player's meters of this game in the session's coin (empty when the pack has none). */
+    meters(): Promise<Meter[]>;
+    /** The player's saved progress (cosmetic), on the server: every device, every version (GUIDE §3.1). */
+    readonly progress: Progress;
     /** Places a bet; rejects with EngineError. Call it from the player's click (or inside an
      * autoplay session): the shell refuses a play with no activation behind it (`needs-click`). */
     play(bet: { mode: string; bet: string; amount: number }): Promise<{ round: Round; balance?: number }>;
@@ -136,3 +155,19 @@ export interface Engine {
 }
 
 export function connect(options?: { timeoutMs?: number }): Promise<Engine>;
+
+/** engine.progress: saved progress over engine.state, safe by default. */
+export interface Progress {
+    /** Resolves once the server's copy is loaded; nothing is saved before. */
+    readonly ready: Promise<void>;
+    get<T = unknown>(key: string, fallback?: T): T;
+    /** Saved within ~2 s and when the page goes; throws past the 256 KB limit. */
+    set(key: string, value: unknown): void;
+    update<T = unknown>(key: string, fn: (value: T | undefined) => T): void;
+    remove(key: string): void;
+    keys(): string[];
+    /** Saves now. */
+    flush(): Promise<void>;
+    /** Moves these localStorage keys to the server once (a key the server has wins); returns the keys moved. */
+    migrate(keys: string[]): Promise<string[]>;
+}

package/engine-sdk/sdk.js

@@ -25,6 +25,7 @@
  * answering you then — play inside it, and follow its `autoplay` events; the
  * shell shows its own Stop over the game.
  */
+import { createProgress } from './progress.js';
 import {
     ERRORS,
     GAME_EVENTS,
@@ -129,6 +130,14 @@ class Engine {
             get: () => this.#ask(REQUESTS.STATE_GET, {}),
             put: (revision, data) => this.#ask(REQUESTS.STATE_PUT, { revision, data }),
         });
+        // The player's meters (the pack's `meters`): what is in each, in the
+        // session's coin. Every round of a mode with a meter also carries
+        // `round.meter` (before, after, and the award when it filled).
+        this.meters = () => this.#ask(REQUESTS.METERS_GET, {}).then((b) => b.meters);
+        // Saved progress over engine.state (progress.js): made on first use,
+        // so a game that does not use it reads nothing at boot.
+        let progress = null;
+        Object.defineProperty(this, 'progress', { enumerable: true, get: () => (progress ||= createProgress(this.state)) });
         // Autoplay is a session the shell grants and runs the count of:
         //   start({ mode, bet, rounds, stake, stopOnProfit?, stopOnLoss? })  → { session }, on the player's click;
         //                 rounds ≤ 1000, every play in it on that bet and none above `stake`;

package/engine-sdk/ui.js

@@ -272,8 +272,11 @@ export async function mount(el, { reveal = async () => {}, step = async () => {}
         try {
             ({ session } = await engine.autoplay.start(req));
         } catch (e) {
+            // Cancelled or refused: the panel repaints, or the controls the
+            // wait disabled stay disabled with no run going.
             busy = false;
             refused(e);
+            render();
             return null;
         }
         busy = false;

package/engine-shell/core/rgs.js

@@ -171,6 +171,7 @@ export function createRgs({ base, sessionId, fetch: doFetch = globalThis.fetch,
         setClientSeed: (generation, clientSeed) => rotation('PUT', '/seeds/client', { generation, clientSeed }),
         rotateSeeds: (generation) => rotation('POST', '/seeds/rotate', { generation }),
         getState: () => call('GET', '/state'),
+        getMeters: () => call('GET', '/meters'),
         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 } : {}) }),

package/engine-shell/core/router.js

@@ -40,9 +40,10 @@
  * 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
+ * on its bridge) — since the focus last entered the game frame, within
+ * ACTIVATION_TTL_MS (`shellInput`: a press out there that left the focus in
+ * the frame is that press's activation, not a game click's; the player's
+ * click back into the game ends it at once). 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
@@ -56,21 +57,18 @@
  * 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.
+ * (`frameFocused`): the player's own focusing (a click, a tap, a Tab) arrives
+ * with the activation it granted already live; 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. A focus the game takes back while a press of the
+ * player's out there still has the activation live is not told from the
+ * player's click back. Telling them apart took refusing every play for 5 s
+ * after any click on the site or the shell (Rewards, chat, Provably Fair,
+ * then Spin: refused). Such a steal buys one play per press, within the
+ * bet's cap, and is left to review and monitoring.
  *
  * 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
@@ -206,7 +204,7 @@ export { AUTOPLAY_MAX_ROUNDS };
 // (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']);
+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', 'meter']);
 
 /** The receipt cut to ROUND_FIELDS. */
 export function roundForGame(body) {
@@ -236,6 +234,7 @@ export function moneyForGame(body) {
 export const REQUEST_KIND = Object.freeze({
     [REQUESTS.ROUND]: 'read',
     [REQUESTS.STATE_GET]: 'read',
+    [REQUESTS.METERS_GET]: 'read',
     [REQUESTS.STATE_PUT]: 'save',
     [REQUESTS.PLAY]: 'money',
     [REQUESTS.ACTION]: 'money',
@@ -329,19 +328,24 @@ export function createRouter({ self, gameWindow, gameOrigin = '*', rgs, site, in
     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.
+    // site's page around it (shellInput), and when the focus last entered the
+    // game frame as the player's (frameFocused). A press out there that left
+    // the focus in the frame (a control that keeps it, a key) shadows the
+    // activation for ACTIVATION_TTL_MS: it is that press's, not the game's.
+    // The player's way back to the game (a click or a tap in it) is an entry
+    // after the press, and ends the shadow at once: Rewards, then Spin, plays.
     let lastShellInput = -Infinity;
+    let lastEntryAt = -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.
+    // A focus the game takes back with a site press's activation still live
+    // is not told from the player's click back (one play per press, within
+    // the bet's cap; the 5-second refusal it took to tell them apart broke
+    // every Spin after Rewards, chat or Provably Fair).
     let stolenFocus = false;
     let stolenAt = -Infinity;
     // The autoplay session in force, or null:
@@ -579,7 +583,7 @@ export function createRouter({ self, gameWindow, gameOrigin = '*', rgs, site, in
         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 (now() - lastShellInput < ACTIVATION_TTL_MS && lastEntryAt <= lastShellInput) 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;
@@ -773,7 +777,7 @@ export function createRouter({ self, gameWindow, gameOrigin = '*', rgs, site, in
             }
             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();
+                const r = type === REQUESTS.ROUND ? await rgs.round(body.roundId) : type === REQUESTS.METERS_GET ? await rgs.getMeters() : 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:
@@ -839,37 +843,25 @@ export function createRouter({ self, gameWindow, gameOrigin = '*', rgs, site, in
         /** 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. */
+         * on its bridge, boot.js). The window's activation is then that press's, not the game's:
+         * until the focus next enters the game frame as the player's (frameFocused), or for
+         * ACTIVATION_TTL_MS, no play or action is taken on it. */
         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) => {
+         * player's own focusing — a click or a tap in the frame, a Tab into it — comes with the
+         * activation it granted already live, and no scripted focus of the game's within the
+         * activation's 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, and an entry with no activation opens the ACTIVATION_TTL_MS window in which
+         * no entry is the player's. An entry taken as the player's ends the shadow of an earlier
+         * shell or site press (shellInput). The page's arguments (whether a Tab came first, the time
+         * since the focus left) are no longer read. Returns whether the focus was the player's; the
+         * page blurs a stolen one straight back out of the frame. */
+        frameFocused: () => {
             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;
+            stolenFocus = noActivation || now() - stolenAt < ACTIVATION_TTL_MS;
+            if (!stolenFocus) lastEntryAt = now();
             return !stolenFocus;
         },
         /** The page is hidden (visibilitychange): a session is for a player who is looking,

package/engine-shell/host/audio-session.js

@@ -0,0 +1,24 @@
+// Only the trusted shell requests playback mode. No media/microphone access,
+// AudioContext, or playback is started here. A fresh page does not opt in.
+export function createAudioSession(navigator = globalThis.navigator) {
+    let wanted = false, suspended = false, owned = false;
+    const apply = () => {
+        try {
+            const session = navigator?.audioSession;
+            if (!session) return;
+            if (wanted && !suspended) {
+                if (session.type !== 'playback') session.type = 'playback';
+                owned = session.type === 'playback';
+            } else if (owned) {
+                if (session.type === 'playback') session.type = 'auto';
+                owned = false;
+            }
+        } catch { /* Unsupported, denied or interrupted: ordinary audio still works. */ }
+    };
+    return {
+        setEnabled(on) { wanted = !!on; apply(); },
+        suspend() { suspended = true; apply(); },
+        resume() { suspended = false; apply(); },
+        release() { wanted = false; apply(); },
+    };
+}

package/engine-shell/host/boot.js

@@ -306,7 +306,7 @@ export async function boot({ ui }) {
             },
             ready: () => {
                 ui.ready();
-                bridge.ready();
+                bridge.ready(descriptor.category);
             },
             loading: ui.loading,
             fairness: fairness.game,
@@ -331,7 +331,10 @@ export async function boot({ ui }) {
         if (!cmd) return;
         if (cmd.cancel) ui.fairnessCancel(cmd.cancel);
         else if (cmd.input) router.shellInput();
-        else if (cmd.control) router.tell('control', { action: cmd.control });
+        else if (cmd.control) {
+            if (cmd.control === 'sound') ui.soundPressed?.();
+            router.tell('control', { action: cmd.control });
+        }
         else fairness.player(cmd.fairness, cmd.requestId);
     });
     // No site around the shell (opened directly, or a stand): the shell

package/engine-shell/host/engine-v1.js

@@ -308,8 +308,11 @@ export function packFromDocument(source) {
     if (!doc.tables || typeof doc.tables !== 'object') throw new Error('the document has no tables');
     const manifestCanonical = canonicalJSON(manifestText);
     const tables = {};
-    for (const m of doc.manifest.modes) {
-        const names = m.kind === 'table' ? [m.table] : (m.steps || []).map((s) => s.table);
+    // Every table the manifest names, the meters' awards' too: the hash is
+    // over all of them.
+    const lists = doc.manifest.modes.map((m) => (m.kind === 'table' ? [m.table] : (m.steps || []).map((s) => s.table)));
+    for (const mt of Array.isArray(doc.manifest.meters) ? doc.manifest.meters : []) lists.push([mt.table]);
+    for (const names of lists) {
         for (const n of names) {
             if (tables[n]) continue;
             if (typeof doc.tables[n] !== 'string') throw new Error(`the document lacks table ${n}`);
@@ -401,7 +404,7 @@ const inRanges = (rs, i) => rs.some(([lo, hi]) => i >= lo && i <= hi);
  * is drawn every step at the bet; a cash-out after k steps pays ladderBp[k-1],
  * which the receipt's `multBp` names.
  */
-export async function play(pack, modeId, betId, serverSeed, clientSeed, nonce) {
+export async function play(pack, modeId, betId, serverSeed, clientSeed, nonce, { award = false } = {}) {
     const mode = pack.manifest.modes.find((m) => m.id === modeId);
     if (!mode) throw new Error(`no mode ${modeId}`);
     const bet = mode.bets.find((b) => b.id === betId);
@@ -410,7 +413,17 @@ export async function play(pack, modeId, betId, serverSeed, clientSeed, nonce) {
     if (mode.kind === 'table') {
         const d = await pick(pack.tables[mode.table], s);
         const tier = bet.tiers.find((t) => inRanges(t.outcomes, d.index));
-        return { mode: modeId, bet: betId, kind: 'table', draws: [d], multBp: tier ? tier.multBp : 0, blocks: s.blocks };
+        const out = { mode: modeId, bet: betId, kind: 'table', draws: [d], multBp: tier ? tier.multBp : 0, blocks: s.blocks };
+        // A round that filled its meter: the award is the stream's next draw,
+        // from the meter's table, paying its tier's multBp of the reference.
+        const meter = award && mode.meter && (pack.manifest.meters || []).find((m) => m.id === mode.meter);
+        if (meter) {
+            const a = await pick(pack.tables[meter.table], s);
+            const t = meter.award.find((x) => inRanges(x.outcomes, a.index));
+            out.award = { draw: a, multBp: t ? t.multBp : 0 };
+            out.blocks = s.blocks;
+        }
+        return out;
     }
     const draws = []; let survived = 0, busted = false;
     for (const step of mode.steps) {

package/engine-shell/host/fair.js

@@ -60,9 +60,22 @@ export function expectation(r) {
         state: typeof r.state === 'string' && STATE.test(r.state) ? r.state : null,
         step: Number.isInteger(r.step) && r.step >= 0 ? r.step : null,
         serverSeedHash: typeof r.serverSeedHash === 'string' && HEX64.test(r.serverSeedHash) ? r.serverSeedHash : null,
+        ...(meterAward(r) ? { award: meterAward(r) } : {}),
     };
 }
 
+// The receipt's meter award (a round that filled its meter): its draw and
+// multiplier; null when the round paid none; `unreadable` when it names one
+// that cannot be read.
+function meterAward(r) {
+    const a = r && r.meter && r.meter.award;
+    if (!a) return null;
+    const d = a.draw || {};
+    const raw = typeof d.raw === 'string' && RAW.test(d.raw) ? d.raw : null;
+    if (raw === null || !Number.isInteger(d.index) || d.index < 0 || !Number.isInteger(a.multBp) || a.multBp < 0) return { unreadable: true };
+    return { raw, index: d.index, rejected: Number.isInteger(d.rejected) && d.rejected > 0 ? d.rejected : 0, multBp: a.multBp };
+}
+
 /**
  * The bet a recomputation pays by: the receipt's when the receipt is this
  * mode's, the mode's only bet, else its first — and then the multiplier is
@@ -274,6 +287,20 @@ export function compare(expect, got, pack, seedHash) {
         if (g.index !== w.index) differences.push(`draw ${k + 1}: row ${g.index} here, ${w.index} on the receipt`);
         if ((g.rejected || 0) !== w.rejected) differences.push(`draw ${k + 1}: ${g.rejected || 0} rejected here, ${w.rejected} on the receipt`);
     });
+    if (expect.award) {
+        const a = expect.award, g = got.award;
+        if (a.unreadable) {
+            differences.push("the receipt's meter award could not be read");
+            unreadable = true;
+        } else if (!g) {
+            differences.push('the receipt pays a meter award this mode cannot draw');
+        } else {
+            if (g.draw.raw.toString() !== a.raw) differences.push(`meter award: raw ${g.draw.raw} here, ${a.raw} on the receipt`);
+            if (g.draw.index !== a.index) differences.push(`meter award: row ${g.draw.index} here, ${a.index} on the receipt`);
+            if ((g.draw.rejected || 0) !== a.rejected) differences.push(`meter award: ${g.draw.rejected || 0} rejected here, ${a.rejected} on the receipt`);
+            if (g.multBp !== a.multBp) differences.push(`meter award: ${times(g.multBp)} the reference here, ${times(a.multBp)} on the receipt`);
+        }
+    }
     if (expect.multBp === null) {
         differences.push('the receipt names no multiplier');
         unreadable = true;