hbengine 0.2.3 → 0.4.0

package/engine-shell/host/index.html

@@ -15,17 +15,40 @@
   @font-face { font-family: 'Red Hat Display'; font-style: normal; font-weight: 700; font-display: swap; src: url(./fonts/red-hat-display-700.woff2) format('woff2'); }
   :root { color-scheme: dark; --bg:#041015; --s1:#0B1920; --s3:#0D2A38; --b:#0D2531; --b2:#113A4C; --t1:#F9F9FB; --t2:#8F96A8; --brand:#02F8F8; --brand6:#0AD4D4; --primary:#C4F4F1; --ok:#47D496; --err:#F41F50; }
   * { box-sizing: border-box; }
-  html, body { margin: 0; height: 100%; background: var(--bg); color: var(--t1); font: 400 14px/20px Figtree, system-ui, sans-serif; touch-action: pan-x pan-y; overscroll-behavior: none; }
-  #stage { position: relative; height: 100%; min-height: 560px; }
+  html, body { margin: 0; height: 100%; overflow: hidden; background: var(--bg); color: var(--t1); font: 400 14px/20px Figtree, system-ui, sans-serif; touch-action: pan-x pan-y; overscroll-behavior: none; }
+  /* The stage is exactly the frame the site gives the shell, at any size, and never
+     scrolls: the game gets that room and lays itself out in it (docs/GAME-GUIDE.md). */
+  #stage { position: relative; height: 100%; overflow: hidden; }
   #game { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; background: var(--bg); }
   .over { position: absolute; inset: 0; display: grid; place-items: center; background: var(--bg); }
   .over[hidden] { display: none; }
-  .loader { display: grid; gap: 14px; justify-items: center; width: min(320px, 80vw); }
-  .h { width: 44px; height: 44px; border-radius: 10px; background: var(--s1); border: 1px solid var(--b2); display: grid; place-items: center; font: 700 26px/1 'Red Hat Display', system-ui, sans-serif; color: var(--brand); animation: pulse 1.4s ease-in-out infinite; }
-  @keyframes pulse { 50% { opacity: .55; } }
-  @media (prefers-reduced-motion: reduce) { .h { animation: none; } }
-  .bar { width: 100%; height: 4px; border-radius: 999px; background: var(--s1); overflow: hidden; }
-  .bar i { display: block; height: 100%; width: 0; background: var(--brand6); transition: width .2s; }
+  /* The loader (intro.js), Dion's entry screen: House Studio's six white squares snap
+     together from scattered, the cyan centre pops in last, the wordmark comes up.
+     A square takes 450 ms from its --d and is in place at 40% of it (intro.js LANDS);
+     the centre takes 400 ms from 420 ms and is in place at 28% (CENTRE_LANDS). */
+  .intro { display: grid; justify-items: center; gap: 18px; }
+  .intro svg { width: 76px; height: 76px; overflow: visible; }
+  .intro .t { fill: var(--t1); opacity: 0; transform-box: fill-box; transform-origin: center; }
+  .intro .c { fill: var(--brand); opacity: 0; transform-box: fill-box; transform-origin: center; }
+  .intro-go .t { animation: tile-in 450ms cubic-bezier(.2,.9,.3,1.15) var(--d) both; }
+  .intro-go .c { animation: centre-in 400ms cubic-bezier(.3,1.6,.5,1) 420ms both, breathe 2.2s ease-in-out 1.4s infinite; }
+  @keyframes tile-in { from { opacity: 0; transform: translate(var(--x), var(--y)) rotate(var(--r)) scale(.5); } to { opacity: 1; transform: none; } }
+  @keyframes centre-in { from { opacity: 0; transform: scale(0); } to { opacity: 1; transform: none; } }
+  @keyframes breathe { 0%, 100% { opacity: 1; } 50% { opacity: .62; } }
+  .intro .word { font: 700 12px/16px 'Red Hat Display', system-ui, sans-serif; letter-spacing: .34em; margin-right: -.34em; color: var(--t2); opacity: 0; }
+  .intro-go .word { animation: fade 350ms ease 550ms both; }
+  @keyframes fade { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
+  .intro .bar { width: 132px; height: 2px; border-radius: 999px; background: var(--s3); overflow: hidden; opacity: 0; }
+  .intro-go .bar { animation: fade 300ms ease-out 700ms both; }
+  .intro .bar i { display: block; height: 100%; background: var(--brand6); transform: scaleX(0); transform-origin: left; transition: transform .25s ease-out; }
+  .intro-out { transition: opacity 280ms ease-in; opacity: 0; }
+  .intro-out svg { transition: transform 280ms ease-in; transform: scale(1.06); }
+  .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+  @media (max-width: 480px) { .intro svg { width: 60px; height: 60px; } }
+  @media (prefers-reduced-motion: reduce) {
+    .intro-go .t, .intro-go .c, .intro-go .word, .intro-go .bar { animation: none; opacity: 1; transform: none; }
+    .intro-out, .intro-out svg { transition: none; }
+  }
   .muted { color: var(--t2); font-size: 12px; line-height: 18px; }
   .panel { background: var(--s1); border: 1px solid var(--b); border-radius: 12px; padding: 20px; max-width: 420px; display: grid; gap: 10px; }
   .panel h2 { margin: 0; font: 700 18px/24px 'Red Hat Display', system-ui, sans-serif; }
@@ -167,7 +190,19 @@
 <body>
 <div id="stage">
   <iframe id="game" title="game" sandbox="allow-scripts allow-same-origin" allow="autoplay" referrerpolicy="no-referrer" hidden></iframe>
-  <div class="over" id="loading"><div class="loader"><div class="h">H</div><div class="bar"><i id="progress"></i></div><div class="muted" id="loading-text">Starting</div></div></div>
+  <div class="over" id="loading"><div class="intro">
+    <svg viewBox="0 0 32 32" aria-hidden="true">
+      <rect class="t" style="--d:0ms;--x:-26px;--y:-34px;--r:-50deg" x="3" y="3" width="8" height="8" rx="1.5"/>
+      <rect class="t" style="--d:30ms;--x:30px;--y:-38px;--r:40deg" x="21" y="3" width="8" height="8" rx="1.5"/>
+      <rect class="t" style="--d:60ms;--x:-46px;--y:4px;--r:35deg" x="3" y="12" width="8" height="8" rx="1.5"/>
+      <rect class="t" style="--d:90ms;--x:48px;--y:-2px;--r:-35deg" x="21" y="12" width="8" height="8" rx="1.5"/>
+      <rect class="t" style="--d:120ms;--x:-22px;--y:40px;--r:-25deg" x="3" y="21" width="8" height="8" rx="1.5"/>
+      <rect class="t" style="--d:150ms;--x:24px;--y:36px;--r:55deg" x="21" y="21" width="8" height="8" rx="1.5"/>
+      <rect class="c" x="12" y="12" width="8" height="8" rx="1.5"/>
+    </svg>
+    <div class="word" aria-hidden="true">HOUSE STUDIO</div>
+    <div class="bar" role="progressbar" aria-label="Loading" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"><i data-intro-bar></i></div>
+  </div></div>
   <div class="over" id="failed" hidden><div class="panel"><h2>Game unavailable</h2><p id="failed-text"></p></div></div>
   <div class="auto" id="auto" hidden><span id="auto-text" role="status" aria-live="polite"></span><button type="button" class="auto-stop" id="auto-stop">Stop</button></div>
 </div>

package/engine-shell/host/intro.js

@@ -0,0 +1,99 @@
+/**
+ * The loader every engine game opens with, Dion's entry screen: House Studio's
+ * six white squares snap together from scattered, the cyan centre pops in
+ * last, the wordmark comes up, and a hairline follows the game's asset groups.
+ * It comes to rest; only the centre tile breathes while a slow game loads.
+ * No words: the progress is announced to screen readers only.
+ *
+ * Sound: a low marimba note as each square lands and a warm bowl chord on the
+ * centre (C3–A3, a quiet octave above for phone speakers), synthesised here,
+ * no files. Each note peaks on the frame its tile lands. It plays only when
+ * the browser lets audio start without asking (the site's press carries into
+ * the frame through allow="autoplay") and the player has not turned the
+ * site's speaker off (the shell counts the bar's sound presses).
+ */
+
+// When each square lands, in ms from the start: index.html's CSS (--d apart by
+// STEP, a 450 ms snap whose easing puts it in place at 40%) and these must agree.
+const STEP = 30, FALL = 450, IMPACT = 0.4;
+const ORDER = ['tl', 'tr', 'ml', 'mr', 'bl', 'br'];
+export const LANDS = ORDER.map((_, i) => i * STEP + FALL * IMPACT);
+// The centre's pop overshoots: its easing reaches full size at 28% of 400 ms.
+export const CENTRE_DELAY = 420, CENTRE_FALL = 400, CENTRE_IMPACT = 0.28;
+export const CENTRE_LANDS = CENTRE_DELAY + CENTRE_FALL * CENTRE_IMPACT;
+// The game is never held back longer than this for the mark to finish.
+export const MIN_SHOWN = 1100;
+export const EXIT = 280;
+
+const NOTES = [130.81, 146.83, 164.81, 174.61, 196.0, 220.0]; // C3 D3 E3 F3 G3 A3
+const CHORD = [130.81, 196.0, 329.63]; // C3 G3 E4
+
+const SOUND_KEY = 'hb-shell-sound';
+export const soundOn = (store) => { try { return !store || store.getItem(SOUND_KEY) !== 'off'; } catch { return true; } };
+/** The site's bar sent `sound`: it flips the speaker, the games and this loader with it. */
+export const toggleSound = (store = storage()) => { if (!store) return; try { store.setItem(SOUND_KEY, soundOn(store) ? 'off' : 'on'); } catch { /* no storage: stays on */ } };
+
+/** A struck note: a sine with a fast attack and an exponential tail, plus a quiet octave. */
+function strike(ctx, out, at, freq, { gain = 0.05, tail = 0.35, octave = 0.35 } = {}) {
+    for (const [f, g] of [[freq, gain], [freq * 2, gain * octave], [freq * 4, gain * 0.08]]) {
+        const o = ctx.createOscillator(), v = ctx.createGain();
+        o.type = 'sine';
+        o.frequency.value = f;
+        v.gain.setValueAtTime(0.0001, at - 0.006);
+        v.gain.exponentialRampToValueAtTime(g, at); // the peak, on the landing frame
+        v.gain.exponentialRampToValueAtTime(0.0001, at + tail * (f === freq ? 1 : 0.6));
+        o.connect(v).connect(out);
+        o.start(at - 0.006);
+        o.stop(at + tail + 0.05);
+    }
+}
+
+/** The intro's sound, scheduled against the moment the animation started. */
+export function playIntro(ctx, startedAt) {
+    const out = ctx.createGain();
+    out.gain.value = 0.9;
+    out.connect(ctx.destination);
+    // The animation's start on the audio clock; a note whose tile already landed is left out.
+    const t0 = ctx.currentTime - (performance.now() - startedAt) / 1000;
+    const due = (ms) => t0 + ms / 1000 > ctx.currentTime + 0.012;
+    LANDS.forEach((ms, i) => { if (due(ms)) strike(ctx, out, t0 + ms / 1000, NOTES[i], { gain: 0.028 + i * 0.002, tail: 0.32 }); });
+    if (due(CENTRE_LANDS)) CHORD.forEach((f, i) => strike(ctx, out, t0 + CENTRE_LANDS / 1000, f, { gain: [0.07, 0.05, 0.022][i], tail: 1.9, octave: 0.3 }));
+}
+
+const storage = () => { try { return globalThis.localStorage || null; } catch { return null; } }; // a sandboxed frame may refuse it
+
+export function intro(root, { store = storage(), now = () => performance.now(), Audio = globalThis.AudioContext || globalThis.webkitAudioContext } = {}) {
+    const started = now();
+    const bar = root.querySelector?.('[data-intro-bar]');
+    const meter = root.querySelector?.('[role="progressbar"]');
+    let done = null;
+    if (Audio && soundOn(store)) {
+        try {
+            const ctx = new Audio();
+            // Never a prompt: if the browser holds audio back, the loader is silent.
+            Promise.resolve(ctx.resume && ctx.resume()).then(() => {
+                if (ctx.state === 'running') playIntro(ctx, started);
+                setTimeout(() => ctx.close && ctx.close(), CENTRE_LANDS + 2500);
+            }, () => {});
+        } catch { /* no audio here */ }
+    }
+    root.classList?.add('intro-go');
+    return {
+        progress(p) {
+            const pct = Math.max(0, Math.min(100, Math.round(p)));
+            if (bar) bar.style.transform = `scaleX(${pct / 100})`;
+            if (meter) meter.setAttribute('aria-valuenow', String(pct));
+        },
+        /** The game is ready: the mark finishes (at most MIN_SHOWN from the start), then the loader fades. */
+        finish() {
+            if (done) return done;
+            if (bar) bar.style.transform = 'scaleX(1)';
+            const wait = Math.max(0, MIN_SHOWN - (now() - started));
+            done = new Promise((resolve) => setTimeout(() => {
+                root.classList?.add('intro-out');
+                setTimeout(() => { root.hidden = true; resolve(); }, EXIT);
+            }, wait));
+            return done;
+        },
+    };
+}

package/engine-shell/host/page.js

@@ -5,9 +5,24 @@ import { API, boot } from './boot.js';
 import { CLIENT_SEED_MAX, betFor, chars, compare, drawLines, expectation, outcome, rotationDifferences, roundLine, withRevealed } from './fair.js';
 import { loadPack, play, sha256Hex } from './engine-v1.js';
 import { STRINGS, fill, wordsFor } from './strings.js';
+import { createAudioSession } from './audio-session.js';
+import { intro, toggleSound, soundOn } from './intro.js';
 const $ = (id) => document.getElementById(id);
 const frame = $('game');
 const groups = new Map();
+// The loader starts with the page: the mark builds while the game's first assets come in.
+const loader = intro($('loading'));
+const audioSession = createAudioSession();
+let soundEnabled = true;
+try { soundEnabled = soundOn(globalThis.localStorage); } catch { /* storage may be blocked */ }
+// Release the page-wide override on departure or backgrounding. A bfcache
+// return may restore only an explicit sound-on choice from this page.
+window.addEventListener?.('pagehide', () => audioSession.suspend());
+window.addEventListener?.('pageshow', () => audioSession.resume());
+document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') audioSession.suspend();
+    else audioSession.resume();
+});
 // How long after the autoplay confirmation opens its Start stays dead. The
 // game chose the moment the dialog appeared and knows where Start renders, so
 // a player already tapping Spin where Start will be must not land the next tap
@@ -521,7 +536,7 @@ const fair = {
             const modeId = this.modeId(pack);
             const bet = betFor(pack, modeId, receipt);
             if (!bet.id) throw new Error('bet');
-            const got = await play(pack, modeId, bet.id, server, client, nonce);
+            const got = await play(pack, modeId, bet.id, server, client, nonce, { award: !!(receipt && receipt.mode === modeId && receipt.meter && receipt.meter.award) });
             if (check !== this.check) return;
             const round = receipt && receipt.mode === modeId ? receipt : null;
             let text = w.computedResult + ': ' + outcome(pack, got, round, bet.known, w);
@@ -589,13 +604,18 @@ const ui = {
     loading(group, loaded, total) {
         groups.set(group, [loaded, total]);
         let l = 0, t = 0; for (const [a, b] of groups.values()) { l += a; t += b; }
-        $('progress').style.width = (t ? Math.round(l / t * 100) : 0) + '%';
-        $('loading-text').textContent = 'Loading ' + group;
+        loader.progress(t ? l / t * 100 : 0);
+    },
+    ready() { loader.finish(); },
+    /** The site's speaker was pressed: the loader stays silent next time if it is now off. */
+    soundPressed() {
+        soundEnabled = !soundEnabled;
+        toggleSound();
+        audioSession.setEnabled(soundEnabled);
     },
-    ready() { $('loading').hidden = true; },
     started(info) { window.__engine = info; },
     round(r) { window.__rounds = (window.__rounds || []).concat(r); },
-    fail(message, err) { if (err) console.warn(err); $('loading').hidden = true; $('failed-text').textContent = message; $('failed').hidden = false; },
+    fail(message, err) { audioSession.release(); if (err) console.warn(err); $('loading').hidden = true; $('failed-text').textContent = message; $('failed').hidden = false; },
     /** The player's language: the dialog's words. */
     locale(lang) { fair.setLocale(lang); },
     // The player has played this long: the game is paused until they say

package/engine-shell/host/sandbox-panel.js

@@ -248,7 +248,8 @@ export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, f
     let observationSequence = 0;
     let scenarioStartSequence = 0;
     let scenarioStartAt = 0;
-    if (typeof router.observe === 'function') router.observe((observation) => {
+    let gameRefusalWaitActive = false;
+    const dispatchObservation = (observation) => {
         const observed = { ...observation, observedAt: Date.now(), observationSequence: ++observationSequence };
         if (!runActive) return;
         observations.push(observed);
@@ -269,7 +270,8 @@ export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, f
                 waiter.resolve(observed);
             }
         }
-    });
+    };
+    if (typeof router.observe === 'function') router.observe(dispatchObservation);
     const waitFor = (predicate, ms = 90_000, registerCancel) => {
         const startSequence = scenarioStartSequence;
         const startAt = scenarioStartAt;
@@ -354,9 +356,13 @@ export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, f
     stop.type = 'button';
     stop.textContent = 'Stop';
     stop.hidden = true;
+    const gameRefusal = document.createElement('button');
+    gameRefusal.type = 'button';
+    gameRefusal.textContent = 'The game refused it';
+    gameRefusal.hidden = true;
     const summary = document.createElement('ul');
     summary.className = 'sandbox-test-summary';
-    scenariosSection.append(scenariosBox, runAll, skip, stop, summary);
+    scenariosSection.append(scenariosBox, runAll, skip, stop, gameRefusal, summary);
     panel.append(scenariosSection);
     let scenarioEntries = [];
     let scenarioButtons = [];
@@ -434,6 +440,10 @@ export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, f
             scenarioStartSequence = observationSequence;
             scenarioStartAt = Date.now();
         },
+        offerGameRefusal: (on) => {
+            gameRefusalWaitActive = on === true && runActive;
+            gameRefusal.hidden = !gameRefusalWaitActive;
+        },
         awaitVerdict: (item) => new Promise((resolve) => {
             reviewOutcome = item;
             verdictResolve = resolve;
@@ -484,6 +494,8 @@ export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, f
             return outcome;
         } finally {
             runActive = false;
+            gameRefusalWaitActive = false;
+            gameRefusal.hidden = true;
             root.classList.remove('sandbox-test-running');
             setRunningControls(false);
             skip.hidden = true;
@@ -544,6 +556,8 @@ export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, f
                 status.textContent = warning ? `Stopped at ${stoppedAt}/${applicable.length}: ${warning}` : stoppedAt ? `Stopped at ${stoppedAt}/${applicable.length}` : `Finished ${results.length} / ${applicable.length}`;
             } finally {
                 runActive = false;
+                gameRefusalWaitActive = false;
+                gameRefusal.hidden = true;
                 root.classList.remove('sandbox-test-running');
                 setRunningControls(false);
                 skip.hidden = true;
@@ -555,6 +569,12 @@ export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, f
     }
     skip.addEventListener('click', () => activeRunner?.skip());
     stop.addEventListener('click', () => activeRunner?.stop());
+    gameRefusal.addEventListener('click', () => {
+        if (!gameRefusalWaitActive) return;
+        gameRefusalWaitActive = false;
+        gameRefusal.hidden = true;
+        dispatchObservation({ type: 'game-refused' });
+    });
     const balance = document.createElement('div');
     balance.className = 'sandbox-test-section';
     balance.append(text('h3', 'Balance'));

package/engine-shell/host/sandbox-scenarios.js

@@ -117,10 +117,11 @@ function checkRound(observation, entry, check = {}) {
     return expected(check.detail || 'The runner observed the expected round.', observation, check.review ? { review: true } : {});
 }
 
-async function wait(ctx, predicate, instruction) {
+async function wait(ctx, predicate, instruction, { gameRefusal = false } = {}) {
     try {
         ctx.beforeWait?.();
-        const observation = await ctx.waitFor(predicate, SCENARIO_TIMEOUT_MS);
+        ctx.offerGameRefusal?.(gameRefusal);
+        const observation = await ctx.waitFor((event) => (gameRefusal && event?.type === 'game-refused') || predicate(event), SCENARIO_TIMEOUT_MS);
         if (observation === SCENARIO_TIMEOUT) return result('skipped', `Skipped after 90 seconds: ${instruction}`);
         if (observation) return { observation };
         const status = ctx.stopRequested?.() ? 'stopped' : ctx.skipRequested?.() ? 'skipped' : 'needs-verdict';
@@ -130,9 +131,15 @@ async function wait(ctx, predicate, instruction) {
     } catch (error) {
         if (error?.code === 'timeout' || error?.name === 'TimeoutError') return result('skipped', `Skipped after 90 seconds: ${instruction}`);
         throw error;
+    } finally {
+        if (gameRefusal) ctx.offerGameRefusal?.(false);
     }
 }
 
+function gameRefusalResult(observation) {
+    return expected('The game refused the stake itself.', observation, { verdict: 'game refused it' });
+}
+
 async function setupBalance(ctx, amount) {
     const response = await ctx.setBalance(amount);
     return response?.ok === false ? result('different', `Different: setup refused (${response.error?.message || 'balance refused'}).`) : null;
@@ -151,13 +158,14 @@ function ladderInstruction(ctx, entry, suffix) {
 
 const definitions = [
     {
-        id: 'cant-afford-minimum', group: 'Balance', title: "Can't afford the minimum stake", todo: 'Press Bet once', look: 'An insufficient-balance refusal', applies: (ctx) => !!playEntry(ctx),
+        id: 'cant-afford-minimum', group: 'Balance', title: "Can't afford the minimum stake", todo: 'Press Bet once', look: 'An insufficient-balance refusal, or the game refusing it itself', applies: (ctx) => !!playEntry(ctx),
         async run(ctx) {
             const setup = await setupBalance(ctx, Math.max(0, minimumStake(ctx) - walletUnit(ctx)));
             if (setup) return setup;
             ctx.say?.(betInstruction(ctx, playEntry(ctx)));
-            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo);
+            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo, { gameRefusal: true });
             if (!waited.observation) return waited;
+            if (waited.observation.type === 'game-refused') return gameRefusalResult(waited.observation);
             if (waited.observation.type === 'settled') return result('different', 'Different: a settled round occurred.', waited.observation);
             return waited.observation.code === 'insufficient-balance'
                 ? expected('Refused with insufficient-balance', waited.observation, { review: true })
@@ -165,7 +173,7 @@ const definitions = [
         },
     },
     {
-        id: 'exactly-one-bet', group: 'Balance', title: 'Exactly one bet', todo: 'Bet the minimum stake', look: 'One losing round, then insufficient-balance', applies: (ctx) => !!playEntry(ctx, (entry) => !!losingEntry(ctx, entry)),
+        id: 'exactly-one-bet', group: 'Balance', title: 'Exactly one bet', todo: 'Bet the minimum stake', look: 'One losing round, then insufficient-balance or the game refusing it itself', applies: (ctx) => !!playEntry(ctx, (entry) => !!losingEntry(ctx, entry)),
         async run(ctx) {
             const entry = playEntry(ctx, (candidate) => !!losingEntry(ctx, candidate));
             let setup = await setupBalance(ctx, minimumStake(ctx));
@@ -178,22 +186,24 @@ const definitions = [
             if (!first.observation) return first;
             const firstCheck = checkRound(first.observation, losingEntry(ctx, entry), { loss: true });
             if (firstCheck.status !== 'expected') return firstCheck;
-            const second = await wait(ctx, (event) => refusalFor(event), this.todo);
+            const second = await wait(ctx, (event) => refusalFor(event), this.todo, { gameRefusal: true });
             if (!second.observation) return second;
+            if (second.observation.type === 'game-refused') return gameRefusalResult(second.observation);
             return second.observation.code === 'insufficient-balance'
                 ? expected('Exactly one losing bet, then insufficient-balance', second.observation, { review: true })
                 : result('different', `Different: second bet refused with ${second.observation.code}.`, second.observation);
         },
     },
     {
-        id: 'stake-above-balance', group: 'Balance', title: 'Stake above the balance', todo: 'Press Bet with a stake above the balance', look: 'An insufficient-balance refusal or the game explanation', applies: (ctx) => !!playEntry(ctx),
+        id: 'stake-above-balance', group: 'Balance', title: 'Stake above the balance', todo: 'Press Bet with a stake above the balance', look: 'An insufficient-balance refusal, or the game refusing it itself', applies: (ctx) => !!playEntry(ctx),
         async run(ctx) {
             const entry = playEntry(ctx);
             const setup = await setupBalance(ctx, minimumStake(ctx));
             if (setup) return setup;
             ctx.say?.(`Bet more than the balance (${minimumStake(ctx)}) on ${entry.modeLabel || entry.mode} / ${entry.betLabel || entry.bet}`);
-            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo);
+            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo, { gameRefusal: true });
             if (!waited.observation) return waited;
+            if (waited.observation.type === 'game-refused') return gameRefusalResult(waited.observation);
             if (waited.observation.type === 'settled') return result('different', 'Different: a settled round occurred.', waited.observation);
             return waited.observation.code === 'insufficient-balance'
                 ? expected('Refused with insufficient-balance', waited.observation, { review: true })
@@ -201,13 +211,14 @@ const definitions = [
         },
     },
     {
-        id: 'empty-wallet', group: 'Balance', title: 'Empty wallet', todo: 'Press Bet once', look: 'A refusal for insufficient balance', applies: (ctx) => !!playEntry(ctx),
+        id: 'empty-wallet', group: 'Balance', title: 'Empty wallet', todo: 'Press Bet once', look: 'An insufficient-balance refusal, or the game refusing it itself', applies: (ctx) => !!playEntry(ctx),
         async run(ctx) {
             const setup = await setupBalance(ctx, 0);
             if (setup) return setup;
             ctx.say?.(`Empty wallet — ${betInstruction(ctx, playEntry(ctx))}`);
-            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo);
+            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo, { gameRefusal: true });
             if (!waited.observation) return waited;
+            if (waited.observation.type === 'game-refused') return gameRefusalResult(waited.observation);
             if (waited.observation.type === 'settled') return result('different', 'Different: a settled round occurred.', waited.observation);
             return waited.observation.code === 'insufficient-balance'
                 ? expected('Refused with insufficient-balance', waited.observation, { review: true })
@@ -380,7 +391,7 @@ export function applicableScenarios(ctx) {
     });
 }
 
-export function createScenarioContext({ entries: scenarioEntries = [], limits = {}, walletDecimals = 8, setBalance, force, clearForce, armFault, clearFaults, reload, currentBalance, startingBalance, say, waitFor, skip, beforeScenario, beforeWait, awaitVerdict, cancelVerdict, resolveVerdict } = {}) {
+export function createScenarioContext({ entries: scenarioEntries = [], limits = {}, walletDecimals = 8, setBalance, force, clearForce, armFault, clearFaults, reload, currentBalance, startingBalance, say, waitFor, skip, beforeScenario, beforeWait, offerGameRefusal, awaitVerdict, cancelVerdict, resolveVerdict } = {}) {
     const context = {
         entries: scenarioEntries,
         limits,
@@ -398,6 +409,7 @@ export function createScenarioContext({ entries: scenarioEntries = [], limits =
         skip,
         beforeScenario,
         beforeWait,
+        offerGameRefusal,
         awaitVerdict,
         cancelVerdict,
         resolveVerdict,

package/engine-shell/host/site-bridge.js

@@ -61,8 +61,10 @@ export function createSiteBridge({ parent, parentOrigin, gameId, currencyId }) {
                     flat(EV.reconcile, ids(r));
             }
         },
-        ready: () => {
-            post({ message: 'gameLoaded', data: { progress: 100 } });
+        // category: the studio's word for the game ("slots", "plinko", …), from its
+        // descriptor; the site shows "In game" in its header for a slot.
+        ready: (category) => {
+            post({ message: 'gameLoaded', data: { progress: 100, ...(typeof category === 'string' && /^[a-z]{1,16}$/.test(category) ? { category } : {}) } });
             post({ type: 'housebets-game-controls-ready' });
         },
         /**

package/engine-shell/verifiers/engine-verify.js

@@ -250,8 +250,9 @@ function loadPack(dir) {
   const manifestText = readManifestText(path.join(dir, 'manifest.json'));
   const manifest = JSON.parse(manifestText);
   const tables = {};
-  for (const m of manifest.modes) {
-    const names = m.kind === 'table' ? [m.table] : m.steps.map((s) => s.table);
+  const lists = manifest.modes.map((m) => (m.kind === 'table' ? [m.table] : m.steps.map((s) => s.table)));
+  for (const mt of manifest.meters || []) lists.push([mt.table]); // the meters' award tables are in the hash too
+  for (const names of lists) {
     for (const n of names) if (!tables[n]) tables[n] = parseTable(n, readText(path.join(dir, n)));
   }
   return { manifest, manifestText, tables };
@@ -307,7 +308,15 @@ function play(pack, modeId, betId, serverSeed, clientSeed, nonce) {
   if (mode.kind === 'table') {
     const d = pick(pack.tables[mode.table], s);
     const tier = bet.tiers.find((t) => inRanges(t.outcomes, d.index));
-    return { mode: modeId, bet: betId, draws: [d], multBp: tier ? tier.multBp : 0 };
+    const out = { mode: modeId, bet: betId, draws: [d], multBp: tier ? tier.multBp : 0 };
+    // The meter's award (a round that filled it): the stream's next draw.
+    const meter = mode.meter && (pack.manifest.meters || []).find((m) => m.id === mode.meter);
+    if (meter) {
+      const a = 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 };
+    }
+    return out;
   }
   const draws = []; let survived = 0, busted = false;
   for (const step of mode.steps) {

package/package.json

@@ -1,10 +1,11 @@
 {
     "name": "hbengine",
-    "version": "0.2.3",
+    "version": "0.4.0",
     "description": "Build, verify and ship House Engine games to House Studio, from the terminal or from an AI agent (MCP).",
     "type": "module",
     "bin": { "hbengine": "engine-cli/hbengine.mjs" },
     "engines": { "node": ">=20" },
+    "dependencies": { "playwright-core": "1.58.2" },
     "homepage": "https://housestudio.io",
     "license": "UNLICENSED"
 }