hbengine 0.2.3

package/engine-sdk/GUIDE.md

@@ -0,0 +1,855 @@
+# Build a House Engine game
+
+A House Engine game is two things: a **math pack** (what can happen and
+what it pays, as data) and a **bundle** (static files that draw it). The
+engine draws every outcome on our server with our provably-fair stream,
+moves the money on the player's Housebets wallet, and your bundle shows what
+the server decided. You never compute money, randomness or balances.
+
+```
+my-game/
+  hbengine.json        {slug, portal, rgs}
+  math/manifest.json   modes, bets, payouts (§2)
+  math/<table>.tsv     weighted outcomes, one per line
+  bundle/index.html    your game (§3)
+  bundle/assets.json   what loads first (§3.2)
+  bundle/hbtest.json   how the pipeline plays one bet (§3.3)
+```
+
+```
+npx hbengine templates  # coin dice slot lines tumble keno crash mines plinko tower wheel
+npx hbengine init my-game --template lines --slug my-game
+cd my-game
+npx hbengine connect                              # a key from House Studio, one click (or hbengine login <portal> with a key)
+npx hbengine verify     # the engine's own verifier: exact RTP per bet, the mathHash
+npx hbengine dev        # play your bundle inside the real shell, against the sandbox (after a first upload)
+npx hbengine upload     # verify + lint + upload; the sandbox plays it; the dashboard has the checks
+npx hbengine store      # store.json (+ tile.png) → the store page
+npx hbengine submit     # the newest version that passed, to review
+npx hbengine stats      # rounds, GGR and RTP by coin once it is played
+```
+
+The dashboard (sign up at the same address) does the rest: upload by
+dragging the folder in, the store page and tile, the sandbox in any coin
+and language with a forced first round, submit for review, go live,
+reports, statements and payouts.
+
+`hbengine connect` opens the approve page in your browser; an owner or
+developer approves there, and the terminal shows which studio did and asks
+`Connect to <studio> (<slug>)? [y/N]` before it keeps the key (a no revokes
+it; so does closing the terminal at the question). An agent, or a script with
+no terminal, passes `--studio <slug>` instead (Organisation → Profile shows
+the slug): the portal then lets only that studio approve; without it and
+without a terminal, `hbengine connect` stops before asking for a code. A
+gateway hiccup while waiting is retried a few times.
+
+With an agent: `npx hbengine connect` adds the MCP server (`npx hbengine mcp`)
+to Claude Code, Cursor and Codex, and the same steps are tools (`engine_guide`,
+`engine_templates`, `engine_init`, `engine_verify`, `engine_lint`,
+`engine_upload`, `engine_store`, `engine_submit`, `engine_live`,
+`engine_status`, `engine_stats`): an agent takes a game from a template to
+review and, once Housebets approves it, live.
+
+Keep hbengine current: after any command it says when npm has a newer
+version (restart your agent to take it, or `npm i -g hbengine@latest` if you
+installed it; `hbengine version` says which you have), and the dashboard shows
+a notice while your studio's tools are behind.
+
+Stuck on something of House Engine itself (a bug in the engine, the SDK or
+these tools, a question this guide does not answer), or have an idea? Tell
+us: `hbengine feedback --kind bug --message "…"`, the dashboard's Support
+page, or ask your agent to send Housebets feedback (`engine_feedback`). Say
+what you did, what happened and the exact error; hbengine adds its version,
+node, the OS and the game. We answer by email and in `hbengine tickets`
+(`engine_tickets`).
+
+## 1. How it runs
+
+```
+housebets.com page ─ frame ─▶ our shell (same origin as the site)
+                               · mints the player's session, talks to the engine
+                               · header balance, round lifecycle, fairness dialog
+                               └─ frame ─▶ your bundle, on its own origin
+                                           sandboxed: no network but its own files,
+                                           talks only to the shell (postMessage)
+```
+
+Your page imports the SDK from its own origin — the platform serves it
+there, your bundle must not carry a copy:
+
+```html
+<script type="module" src="/engine-sdk/bet-field.js"></script>
+<script type="module" src="./game.js"></script>
+```
+
+Two ways to build the frontend; both ship through the same pipeline:
+
+- **The engine panel** (`/engine-sdk/ui.js`): you draw only the game; the
+  Originals' panel (stake in the player's currency, Bet, Auto with the
+  Originals' rules — count, on win / on loss reset or increase by a
+  percent, stop on profit / loss — mode and bet pickers from your math,
+  Next / Cash out on a ladder, refusals in the player's language) is ours,
+  and its Auto runs as a shell autoplay session (§3.1).
+  `engine-examples/coin` is 30 lines.
+- **Your own frontend**: any static web tech (plain, Pixi, Phaser, your
+  framework's build output). You use the SDK's `connect()` and show the
+  rounds it returns, and the money fields (`<hb-bet-amount>`) so currencies
+  are right. BAD CAT (four games, a lobby, skins, music) is the reference.
+  Build it as one page with views inside it, not as pages that frame other
+  pages of the bundle (the upload's scan names such pages, `nested-pages`).
+
+## 2. The math pack
+
+`math/manifest.json`:
+
+```json
+{ "format": "house-engine-math/1", "game": "coin", "rtpBp": 9900,
+  "modes": [ { "id": "coin", "label": "Coin", "kind": "table", "table": "coin.tsv",
+      "bets": [ { "id": "heads", "label": "Heads", "tiers": [ { "outcomes": [[0, 0]], "multBp": 19800 } ] },
+                { "id": "tails", "label": "Tails", "tiers": [ { "outcomes": [[1, 1]], "multBp": 19800 } ] } ] } ] }
+```
+
+`math/coin.tsv` — one outcome per line, `weight<TAB>json`; the JSON is
+what your frontend gets back as `round.data[i]` (the dice faces, the reel
+stops, the trap tile), the server never reads it:
+
+```
+1	{"side":"heads"}
+1	{"side":"tails"}
+```
+
+- **table** mode: one draw settles the bet. Each bet names payout tiers
+  over outcome index ranges; `multBp` is basis points of the stake,
+  stake included (19800 = 1.98×). A dice with 97 targets is 97 bets on one
+  100-row table; a 3-reel slot with 48-stop reels is a 110,592-row table whose tiers group the
+  paying combinations. **100,000 different rounds in every mode is
+  recommended for a slot** (each bonus buy too): under it pre-flight warns
+  and the reviewer decides (fine for a classic 3-reel, not for a video
+  slot). Rows count once when another has the same data and pays the same;
+  the verifier reports `rounds` per mode. Originals have no recommendation.
+- **ladder** mode (`"kind": "ladder"`): every step is drawn at bet from its
+  table; `bets[].survive` are the rows that let the player go on;
+  `ladderBp[k-1]` is the cumulative payout after `k` survived steps;
+  `cashout: true` lets the player stop after any step; `autoAdvance: true`
+  plays all steps at once (all or nothing). Tower, chicken road, mines-like
+  games are ladders.
+- Slug `^[a-z0-9][a-z0-9-]{1,23}$`; ids `^[a-z0-9][a-z0-9-]{0,31}$`;
+  weights are integers, Σ ≤ 2⁶³, ≤ 1,000,000 rows, row JSON ≤ 4 KB;
+  ≤ 64 steps. Unknown fields are refused.
+- **RTP** is computed exactly (integer arithmetic) for every bet:
+  `9000 ≤ RTP ≤ rtpBp ≤ 9900`, every bet must be able to pay. A ladder's
+  RTP is its best stop. An outcome no bet pays on (a push, a tie, a zero
+  segment) is fine — the verifier only names it. `hbengine verify` prints RTP, hit rate, max
+  multiplier and (ladders) the RTP at every stop; what it accepts the upload
+  accepts, because it is the same code (`POST /engine/v1/verify`).
+- A ladder round's **outcome** is `round.state`: `open`, `cashed_out` or
+  `busted` (`settled` for a table). `round.busted` and `round.survived`
+  describe the drawn path and arrive when the round closes — after a
+  cash-out too, when the path would have busted later. Show the player's
+  result from `round.state` and `round.step`.
+- The pack's **mathHash** names the version. A session is pinned to one
+  hash; a new upload is a new version; players on an open ladder finish on
+  the version they started.
+
+### 2.1 The maths kit — slots, plinko, anything with features
+
+`packages/engine-math` (copied into a project as `math-kit/` by the
+`lines`, `tumble` and `plinko` templates) writes the pack from rows you
+describe — `slot.mjs` for reels and lines, `tumble.mjs` for scatter pays
+with tumbles:
+
+```js
+import { fit, rng, writePack } from '../math-kit/pack.mjs';
+import { books, slot } from '../math-kit/slot.mjs';
+const game = slot({ reels, rows: 3, lines, pays, wild: 'W', scatter: { symbol: 'S', pays, spins, retrigger, multiplier: 2, cap: 60 }, maxWinBp });
+const rows = fit(books(game, rng(SEED), 400_000), 9600);   // every row a whole round, RTP exactly 96.00%
+writePack('math', { game: 'my-slot', rtpBp: 9600, modes: [{ id: 'base', rows, bets: ['spin'] }] });
+```
+
+- A **row is a whole round** (a "book"): the base spin and every free spin
+  it starts, with what it pays in total. Features, cascades, multipliers,
+  pick bonuses — anything you can play in code — become rows the same way;
+  the page plays back what the row holds.
+- **`fit(rows, targetBp)`** makes the RTP exactly the target: the paying
+  rows keep their proportions, the losing rows share the weight left.
+  Integer arithmetic throughout; the engine's verifier then agrees to the
+  fourth decimal.
+- **`balance(rows, targetBp)`** does the same for a table where every row
+  pays (a bonus buy, plinko): the rows above and below the target are each
+  scaled by one integer. The `lines` template's **bonus buy** mode is the
+  free spins alone, priced at what they return on average (27 spins),
+  balanced to exactly 96%.
+- **`writePack`** sorts rows so each pay tier is one range, checks the
+  limits (rows, Σ weights, row size) and prints RTP, hit rate and max win.
+- Tune the model until RTP *before* the fit is near the target (the gen
+  prints it): the fit should nudge, not reshape, the hit rate.
+- Exact games (plinko, wheels, dice) need no fit: weights are exact
+  (`binomial(n, k)`), and you solve one multiplier for the RTP — round it
+  to what the page shows, so the board shows exactly what pays.
+- Write the model the page needs (reels, lines, pays) to `bundle/` from
+  the same script, so the page and the table can never disagree.
+
+The studio dashboard shows every bet's RTP, hit rate, largest win and
+volatility (σ of one round's multiplier: low < 2, medium < 5, high < 15,
+very high above) from the verified pack; players see the same on the
+game's page.
+
+## 3. The bundle
+
+`bundle/index.html` at the root, everything relative. Budgets: boot group
+≤ 2 MB gzip (its JavaScript ≤ 250 KB gzip), any other group ≤ 25 MB gzip,
+≤ 300 MB and ≤ 2,500 files in all, one file ≤ 8 MB (code ≤ 4 MB), plain
+files only.
+
+### 3.1 The SDK
+
+```js
+import { connect } from '/engine-sdk/sdk.js';
+const engine = await connect();            // waits for the shell's init
+engine.config                              // game, mathHash, env, currency, limits, modes, balance, locale, wallet, state, activeRound?
+const { round, balance } = await engine.play({ mode: 'coin', bet: 'heads', amount: field.amount });
+round.data[0]                              // the row JSON you wrote in the table
+engine.revealed(round.id);                 // the outcome is on screen: the header balance moves now
+// round: { id, mode, bet, kind, amount (wallet units), state 'open'|'settled'|'cashed_out'|'busted',
+//          step, payout, multBp, data: [row JSON per draw], draws: [{index, raw, rejected}], nonce, mathHash }
+// engine.config.limits: { min, max, maxWin, maxStake: { <mode>: { <bet>: "12.50" } } } in the wallet coin
+//                       (may be empty in the sandbox); maxStake is the most each bet takes, §4.1
+// a ladder draws every step at the bet; while it is open you see only the steps played,
+// once it ends (bust, cash-out, autoAdvance) `data` has every step — show up to the first miss
+// a push (a tier paying 1.00×) is `payout === amount`; a loss is `payout === 0`
+await engine.action(round, 'advance' | 'cashout');   // ladders; pass the round as you last had it; both from the player's click
+engine.on('balance' | 'control' | 'pause' | 'resume' | 'ended' | 'autoplay', fn)
+// pause/resume: the shell's reality check (engine.config.rg.realityCheckSec); ended: the session is over
+// engine.config.rg: { autoplay: { allowed }, realityCheckSec } — the jurisdiction's rules; the panel obeys them
+// autoplay { active, left, played, stake?, reason? }: the shell's session changed (started, a play, or ended)
+await engine.autoplay.start({ mode, bet, rounds, stake, stopOnProfit?, stopOnLoss? })  // the player's grant for one bet: the shell shows the terms, they press Start
+engine.autoplay.stop()                     // end it; the shell also shows its own Stop over your game
+engine.state.get() / engine.state.put(revision, data)   // the player's own saved data, ≤ 256 KB, any device
+                                           // both resolve { revision, data }; put with the revision you read
+                                           // (0 the first time); a stale revision rejects with `conflict`
+                                           // save when the player changes something, not per frame: over 10 writes
+                                           // at once and then one a second rejects with `pacing` (retryAfterMs)
+                                           // keep a `version` field in it: a new release of your game reads old data
+engine.money                               // §4
+engine.openFairness(round.id); engine.reportError(msg);
+```
+
+One `play`/`action` at a time; a second is refused with `busy`. Every
+refusal is an `EngineError` with a `code` (`invalid busy
+insufficient-balance limits pacing pending unavailable session-ended round
+conflict server needs-click autoplay`), a message to show, and for `round`
+the round as it now stands (redraw it). `pending` means the wallet has not
+answered: the shell and the server settle it; show the message, do not retry
+on your own.
+
+**Nothing happens without the player's click.** A `play` and every ladder
+`action` — an `advance` and a `cashout` alike — are taken only when the
+player has just clicked or pressed a key in your page — the shell reads the
+real browser activation a click gives it, which lasts a few seconds, and
+checks that the focus is inside your frame and got there by the player's own
+act (a click in your page puts it there; a click elsewhere on the site page
+does not, and a `focus()` your script calls is undone and buys nothing) — or
+inside an autoplay session the player started (its plays, and the steps and
+cash-out of the ladder it opened). Call them from the handler of the
+player's gesture, not from a timer, a load, a date or a round count, or the
+shell refuses them with `needs-click` ("A bet needs your click", in the
+player's language). An auto cash-out target is such a timer: the shell
+refuses the cash-out the moment the click lapses, so put a target in your
+maths (its own stop) rather than in your page; a round the player leaves open
+stays open for them to come back to (the server resumes it with the session),
+and is never your page's to close. One click
+buys one bet: a second `play` within 600 ms, or a sixth within 5 s, is
+refused with `pacing` and `retryAfterMs`; one tap buys at most one `advance`
+per 100 ms and 25 per 5 s, refused the same way; a cash-out is not paced. For
+5 s after the player pressed one of the shell's own controls (Stop on the
+autoplay pill, Cancel on its confirmation, Continue on the reality check, a
+key in the Provably Fair dialog) — or, in production, anything on the site's
+page around your game (the chat, the header: the shell is a frame of that
+page and a press there arms it as a click in your page does) — the shell
+takes no bet on activation alone either, so a bet pressed within those 5 s
+is refused with `needs-click` — every one of them, until 5 s have passed
+since the last press outside your frame; show the message and let the player
+press again. The same 5 s follow the player tabbing out of your page by
+keyboard: a click back into it within them is refused `needs-click` and the
+focus is put back outside (the shell cannot tell that click from a
+`focus()` your script might call on its own `blur`, so neither gets in); a
+Tab back into your page is let in, and so is a click 5 s after they left.
+The read-only `round` and `state.get`, and `state.put` (a save
+moves no money: save at boot or after a reveal as you always did) need no
+click. A browser without `navigator.userActivation` cannot confirm a click,
+so the shell bets nothing there and the refusal names the browsers that can
+(current Chrome, Edge, Safari and Firefox all have it). The upload's
+conformance run presses your Bet with a real click, so a game that bets from
+the click handler passes as before.
+
+A ladder your page climbs itself (a crash) advances on the Bet click's
+activation for those few seconds and within the tap's run of steps, then the
+shell refuses the next step: on `pacing` wait `retryAfterMs` and climb on;
+on anything else (`null` from `game.advance()` — read `game.refusal` for why
+— or `needs-click` from `engine.action`) stop climbing, keep the round and
+Cash out on screen, and climb on at the player's next tap. Take that tap on
+`click` (or `pointerup`), not `pointerdown`: a touch grants the shell its
+activation only when the finger lifts, so a step sent from `pointerdown`
+can be refused again on a phone. Cash out is the player's press, never the
+page's (no auto cash-out on a timer). `engine-examples/crash` does exactly
+this. A tile or a Next button pressed per step (mines, tower) is a click per
+step and needs nothing more.
+
+**Autoplay is the player's grant through the shell:**
+
+```js
+const { session } = await engine.autoplay.start({ mode: game.mode, bet: game.bet, rounds: 50, stake: field.amount, stopOnProfit: 20, stopOnLoss: 10 });
+// Call it from the player's click on your Auto button (a start with no click behind it is refused
+// `needs-click`, like a bet). The run is for one bet (`mode`, `bet`: the player approves that bet, and
+// a play on another is refused `autoplay`); rounds ≤ 1000; no play in the session may stake more than
+// `stake`; the stops are optional, in wallet units, on the session's net result (a loss limit is
+// always applied: yours, or 100× the stake, and never above the total the run could stake). The shell
+// shows the player the terms — the bet, capped at the coin's max bet, the bet's own ceiling
+// (engine.config.limits.maxStake[mode][bet], §4.1: the request names the bet, so the shell applies it;
+// a bet whose figure is 0 takes nothing right now, and the start rejects `unavailable`) and the
+// balance it last saw — in its own dialog over your frame and resolves this only when they press
+// Start there (its Start is dead for the dialog's first second); rejects with `autoplay` on Cancel,
+// after 30 s unanswered, on the reality check, when the player's rules forbid autoplay
+// (engine.config.rg.autoplay.allowed), while one is already running, and (with `retryAfterMs`;
+// "Autoplay was just closed. You can ask again in a moment.", in the player's language) for 10 s
+// after a Cancel — a cancelled request cannot be repeated at once, so do not retry it from your
+// rejection handler; with `busy` while paused. `session` carries the terms as granted: keep your run
+// to them.
+engine.on('autoplay', ({ active, left, played, reason }) => …);   // on start, after each play, at the end
+await engine.autoplay.stop();                                      // always taken
+```
+
+The shell counts the rounds, refuses a play on another bet, above the stake
+or past the count, ends the session at the count (once a ladder round it
+opened has closed; the stops wait for it too), at a stop, on any refused play, on `stop()`, on the reality check,
+after 30 s without a play of the session (`idle`: play the granted rounds
+now, not later), when the page is hidden (`hidden`: another tab, the phone
+locked) and when the player presses **Stop** on the shell's own control — a
+small pill over your frame showing the rounds left, which your page cannot
+cover or press — and tells you of every change through the `autoplay` event
+(`reason`: `stopped done profit loss refused paused ended idle hidden`).
+Plays you send while a session is live need no further click. Build no
+autoplay engine of your own that bets without the player: a click carries
+only the first few seconds, so the shell refuses such a loop's bets with
+`needs-click` once the player's activation lapses, and with `pacing` beyond
+five plays in 5 s — a three-spin loop passing your test proves nothing. The
+engine panel's Auto (`ui.js`) already runs through the shell; a custom front
+end starts the session from its own Auto button (the player then confirms in
+the shell's dialog) and calls `stop()` from its own Stop. A bundle already
+live with an autoplay loop of its own (Kraken's autopick run, BAD CAT's
+auto-bets) is cut off the same way from the day this shell deploys — its
+Auto plays a few rounds after the click and then stops with `needs-click` —
+until it is republished on `engine.autoplay`; the shell goes first, by
+decision, because a game betting on its own is exactly what it exists to
+stop.
+
+`engine.reportError(msg)`, and an uncaught error or unhandled promise
+rejection in your page (the SDK listens for both on `window`), is logged in
+the player's console and counted on the engine as one error for the game's
+day; the shell also counts a launch per open and a round left open when the
+page closes on one. Your Reports page and `hbengine stats` show the counts
+per day — counts only, never the text: nothing a game sends reaches the
+studio as text.
+
+With the engine panel instead:
+
+```js
+import { mount } from '/engine-sdk/ui.js';
+const game = await mount(document.querySelector('hb-game'), {
+    reveal: async (round, zone) => { /* animate round.data[0]; resolve when on screen */ },
+    step:   async (round, zone) => { /* a ladder round moved */ },
+});
+game.mode = 'hard'; game.bet = 'over-50';  // when your zone picks (a mode with > 12 bets)
+el.addEventListener('select', (e) => draw(e.detail.mode));   // the panel's pick reached your zone
+// engine.config.modes carries ids, labels, kinds and each bet's maxMultBp — never the
+// tables: what your zone draws (a wheel's segments, a paytable) is a constant of yours.
+```
+
+### 3.2 Loading in stages — `assets.json`
+
+```json
+{ "groups": { "boot": { "files": ["index.html", "game.js", "game.css"] },
+              "music": { "files": ["music/a.mp3"], "load": "idle" },
+              "skins": { "files": ["skins/tabby.webp"], "load": "demand" } } }
+```
+
+`boot` is what the first frame needs; `idle` groups load after
+`engine.ready()`; `demand` groups when you ask (`createAssetLoader` in
+`/engine-sdk/assets.js`, or your own loader — the manifest is the contract).
+Every file in exactly one group.
+
+### 3.3 Fit — the frame, and what the site's bar does
+
+The game is the frame, as a House Original is: the site gives it the
+column's width × **720 px** (phone: ~364 × 720), wider in theatre mode and
+the whole screen in fullscreen (the site's buttons). Lay the game out for
+the box it is given — `height: 100%`, the board taking what is left — and
+re-fit when it changes. The frame never grows to the page and never
+scrolls: the pipeline plays your game at 1194×720 and 364×720, then
+fullscreen at 1920×1080 and 390×844, and every control must be on screen
+at each — and no text, image or canvas may be cut by the frame's edge (a
+reel that runs off a phone fails). Decoration meant to bleed off the edge
+is marked `aria-hidden="true"`; a clip inside the frame (a reel window, a
+ticker) is yours and fine.
+
+The site already shows the title, the balance and a bar under the frame —
+draw none of them. Showing the balance in the game is allowed (slots do),
+from `engine.balance` through `engine.money`. The bar's buttons reach the
+game as `engine.on('control', ({ action }) => …)`: `sound` (toggle your
+sound), `settings`; **Provably Fair** opens the shell's own dialog, the
+House Originals' modal in the game window: a Seeds tab (the player's client
+seed, the server seed hash before play, the next hash, the nonce, Rotate
+seed pair, the revealed pairs) and a Verify tab (server seed, client seed,
+nonce and mode in, the recomputed result out, matched against the round when
+opened on one). It is the same for every engine game and it is the shell's,
+so build no fairness UI of your own — no seeds view, no rotate button, no
+verifier; `engine.openFairness(round.id)` opens the shell's dialog on a
+round from inside your game, filled and verified, when you want a button
+there (call it on the player's click: the shell takes it at most once every
+two seconds, not while paused, and never over what the player has typed in
+the dialog). `engine.round(id)` gives you the settled round without its
+seeds. Every round is a bet: send `engine.play` a stake of at least
+`engine.config.limits.min` and never offer a free or zero-stake spin — the
+server refuses a stake under the minimum and a stake of 0 (a round that
+costs nothing would still consume a nonce of the player's seed pair), demo
+or otherwise.
+
+### 3.4 `hbtest.json` — how the pipeline plays one bet
+
+```json
+{ "open":  [{ "page": "index.html", "selector": "a[href='./coin.html']" }],
+  "stake": { "page": "index.html", "selector": "hb-game hb-bet-amount input", "value": "1.00" },
+  "bet":   { "page": "index.html", "selector": "hb-game [data-main]" } }
+```
+
+Selectors reach into shadow roots; `page` is the page's file name. The run
+types the stake, presses the bet, and expects `engine.play` and then
+`revealed`. A ladder's bet opens a round: add `"then": [{ "page": "index.html", "selector":
+"hb-game [data-next]" }, { "page": "index.html", "selector": "hb-game [data-cashout]" }]`
+so the run closes it. Each `then` step is pressed only if its control is
+visible and enabled — a bust can end the round before Cash out exists.
+`"shows": { "page": "index.html", "selector": "#face", "path": "data.0.side" }`
+makes the run check that the element shows the value the server drew
+(`path` walks the round: `data.0.side` = `round.data[0].side`).
+A game with several screens (a lobby of games) lists the others in
+`"visit"`: clicks made before `open`, each screen and back, e.g.
+`[{ "page": "index.html", "selector": "[data-card='dice']" }, { "page": "index.html", "selector": "#back" }]`.
+An error or a scroll on any of them fails the run like one on the bet's screen.
+A custom frontend names its own elements: any selector works
+(`#play`, `.stake input`); give the Bet button and the stake input stable
+ids and use those.
+The engine panel's selectors are a contract: `hb-game hb-bet-amount input`
+(stake), `hb-game [data-main]` (Bet), `[data-next]`, `[data-cashout]`,
+`[data-modes] button[data-id="<mode>"]`, `[data-bets] button[data-id="<bet>"]`.
+The typed stake is parsed in every currency of the run (a fiat at 2
+decimals, the coin at 8): keep it representable in both, `1.00` is.
+
+### 3.5 Libraries (Pixi, Howler, GSAP …)
+
+Ship them in the bundle under `bundle/vendor/` — nothing loads from a CDN at
+run time. Libraries often contain code paths the player's browser will
+refuse here (`new Function`, default CDN URLs). The scan reads a file under
+`vendor/` as a library when its file name and the banner comment in its
+head match a library we know (PixiJS and its `unsafe-eval` module, howler.js,
+GSAP, three.js, Phaser, Babylon.js, Matter.js, Planck.js, anime.js, jQuery,
+lodash, Spine, Tone.js, Hammer.js, Tween.js, p5.js, CreateJS, PlayCanvas,
+cannon.js, Box2D, Rapier — `KNOWN_LIBRARIES` in `engine-conformance/scan.mjs`;
+ask us to add one): what it would refuse in your own code it only names for
+the reviewer, and the library may be minified as released. Anything else
+under `vendor/` is read as your code (§3.7 applies, a source map and all).
+The conformance run fails a game that trips the policy even once — configure
+the library not to take those paths. Ship the release file as it is: never
+edit a library file to get past the scan.
+
+**PixiJS v8**: load its no-eval module right after it — the policy has no
+`unsafe-eval`, and without this Pixi's renderer cannot start:
+
+```html
+<script src="./vendor/pixi.min.js"></script>          <!-- pixi.js@8 dist/pixi.min.js -->
+<script src="./vendor/unsafe-eval.min.js"></script>   <!-- pixi.js@8 dist/packages/unsafe-eval.min.js -->
+```
+
+`ticker.add(fn)` returns the ticker, not `fn`: keep `fn` to remove it when a
+screen closes, or it runs on destroyed sprites (an error the run catches).
+
+Pixi is ~185 KB gzip and fits the boot budget; put your textures in
+staged groups.
+
+### 3.6 Compressed textures and WebAssembly (KTX2 / Basis)
+
+The policy allows WebAssembly (`'wasm-unsafe-eval'`) and workers started
+from `blob:` (`worker-src 'self' blob:`), so a KTX2/Basis transcoder runs —
+GPU-compressed textures keep phone memory down. But a `.wasm` is a program
+nobody at Housebets can read, so the scan accepts WebAssembly on one footing
+only: **a known library's released module, run by that library's own code.**
+
+- The module's bytes must be a release we know: the scan hashes every
+  WebAssembly module in the bundle (by its first bytes, whatever the file is
+  called) and looks the SHA-256 up in
+  `packages/engine-conformance/wasm-releases.json` — three.js's
+  `basis_transcoder.wasm` and `draco_decoder.wasm`, Rapier's
+  `rapier_wasm2d_bg.wasm`/`rapier_wasm3d_bg.wasm`, Box2D's `Box2D.wasm`,
+  at the versions listed. Ship the file exactly as the package publishes it.
+  A module whose hash is not there is refused, whatever its name and
+  wherever it sits; a name like `rapier_bg.wasm` is no tie to anything.
+  Need another library or version? Ask us to add its hash (we take it from
+  the published tarball, never from a file in an upload).
+- Only the library's own glue may reach `WebAssembly`: its `.js` under
+  `vendor/`, named and bannered as released (§3.5: `basis_transcoder.js`,
+  `draco_decoder.js`, `rapier*.js`, `Box2D*.js` are known). Your own code
+  reaching `WebAssembly` in any way — `WebAssembly.instantiate(…)`, a name
+  bound to it, `this.wa = WebAssembly`, a module embedded as base64 — is
+  refused. `typeof WebAssembly === 'object'` is a feature check, not a use.
+- Its JS glue must not call `new Function`/`eval`. Emscripten's embind does
+  by default; the published three.js builds do not. The conformance run
+  fails a game whose transcoder trips the policy, so `hbengine test` tells
+  you at once.
+- three.js: `new KTX2Loader().setTranscoderPath('./vendor/basis/')
+  .detectSupport(renderer)`. In Pixi or another engine, point its KTX2
+  transcoder path at the same `./vendor/` folder.
+- Put `.ktx2` textures in staged `assets.json` groups like any other art;
+  keep a PNG/WebP fallback only if a target device lacks every supported
+  GPU format.
+- A transcoder or physics engine you built yourself cannot ship as
+  WebAssembly: there is no source we could tie to the bytes. Ship it as
+  JavaScript (readable, or with its source map, §3.7).
+
+### 3.7 What a bundle must not do — and why the scan reads your code
+
+The upload's scan parses every script of the bundle (every `.js`, every
+inline `<script>`) and reads what it reaches from the syntax, with names
+resolved through scopes — not by matching patterns. A rule is refused in
+every spelling: `window['ev' + 'al']` is `eval`, `(0, eval)` is `eval`,
+`fn.constructor('…')` is the Function constructor. Write plainly; a reader
+at Housebets has to see what your game does before a player does.
+
+**Refused** (the upload fails, naming file and line):
+
+- `eval` and the Function constructor in any form: `Function(…)`,
+  `new Function`, `x.constructor(…)` on anything (a function's
+  `.constructor` *is* `Function`, and the scan cannot tell a function from
+  a class instance). Reading a property off it is fine — `.constructor.name`,
+  `this.constructor.DEFAULTS`, `this.constructor.create(opts)`,
+  `new this.constructor()` with no arguments, `x.constructor === Array` —
+  but calling it, `new o.constructor(a, b)` with arguments, keeping it in a
+  name (`const C = o.constructor`, `const { constructor } = o`) or reaching
+  `.call`/`.apply`/`.bind` on it is refused: name the class instead.
+- The global object by a computed name — `window[name]`, `globalThis[k]`,
+  `self[k]`, `top[k]`, `parent[k]`, `frames[i]`, `document[k]`,
+  `Reflect.get(window, k)`, `Object.keys(window)`, `for (k in window)`,
+  `{ ...window }`, `const { ...rest } = window`, `new Proxy(window, …)` —
+  also through a name bound to it: `const w = window`, `let w; w = window`,
+  `const { self: w } = window`, a `(function (root) { … })(window)` wrapper.
+  `window.name`, `window['name']` and `const { name } = window` are fine:
+  they say what they reach, and are judged as that name (`const { eval } =
+  window` is `eval`).
+- A property name built at run time that spells an API: `obj['ev' + 'al']`,
+  `obj[atob('…')]`, `obj[String.fromCharCode(…)]`, `obj['\x65val']`,
+  `'lave'.split('').reverse().join('')`. Ordinary dynamic keys
+  (`sounds['win_' + level]`, `obj[key]`, `dict[lang.toLowerCase()]`) are fine.
+- A string handed to `setTimeout`/`setInterval`; `with`; `document.write`
+  (on any document: `frame.contentDocument.write`, `node.ownerDocument.write`);
+  `createElement('script')` or a `<script>` tag in a string (its text would
+  run as code nobody read — load scripts with `<script src>` or `import()` of
+  a path); code in attributes (`onclick="…"`, `href="javascript:…"`,
+  `setAttribute('onclick', …)` however the name is spelled — `'on' + 'click'`,
+  reversed, decoded, each name of a list a loop runs over — `setAttributeNS`,
+  `toggleAttribute` and `createAttribute` too, and a handler inside markup you
+  build from a string: `innerHTML = '<img onerror=…>'`, `insertAdjacentHTML`,
+  `outerHTML`, `createContextualFragment`, `setHTMLUnsafe`,
+  `DOMParser.parseFromString`, also when the markup is split across pieces,
+  `'<img on' + 'error=…>'`) — use `addEventListener`.
+- An attribute name the scan cannot read: `setAttribute(name, …)`,
+  `toggleAttribute(name)`, `createAttribute(name)` with `name` computed.
+  Write the name down. A `for (const key of ['title', 'alt'])` or
+  `['title', 'alt'].forEach((key) => …)` over written names is read, and so
+  is a written prefix: `'data-' + key` and `` `aria-${name}` `` are fine,
+  `'on' + type` is a handler, `prefix + '-id'` is not readable.
+  `createElement(name)` with a computed tag stays a review warning (a
+  helper's `el(tag, …)` is the common case).
+- Markup built from text the scan cannot read exactly: `innerHTML =
+  atob(…)`, `innerHTML = decodeURIComponent(…)`, `new TextDecoder().decode(…)`,
+  a written markup string rewritten by a pattern (`TPL.replace(/{{x}}/g,
+  …)`, `.sort`, `.map` over its characters); text from outside the code at
+  a markup or URL sink: a response body (`.text()`, `.json()`), storage, a
+  cookie, a field's value, a message's data (`addEventListener('message',
+  …)` in any spelling, `onmessage`), typed text, `window.name`, the address
+  (`location.hash`, `location.search`, `document.URL`, `URLSearchParams`:
+  the game can write the address and read it back decoded) — through any
+  name, list, `.map`, `.then`, destructuring or property the text passes.
+- Markup or a URL of which nothing is written down: `innerHTML = x`,
+  `el.href = url`, `img.src = asset(id)` with nothing the scan can read
+  behind `x`. The scan follows a value to where it is written: through the
+  names it was bound to, objects and lists you wrote (`ART[sym]`, `P[0] +
+  P[1]`), your own functions (what they return, their parameters from where
+  you call them, in any file), properties and `dataset` attributes you wrote
+  and read back, `Map.set`/`get`, imports (`import * as ART from './art.js'`,
+  a JSON module), globals another script set on `window`, and the page's own
+  elements (`document.getElementById('f').dataset.src` is the attribute as
+  written in the page). What it cannot place anywhere is refused; one
+  alternative written beside one it cannot place (`ART[sym] || sym`) is
+  named for review. As a URL, the written start fixes the scheme: `'./x/' +
+  id` and `location.origin + path` are fine, `base + '/a.png'` with `base`
+  unknown, `'java' + x`, `'data:' + x` are refused; an `Image` or an
+  `<img>` you create loads a resource and may take any address. A computed
+  part inside written markup (`` `<div class="${c}">${text}</div>` ``,
+  `'<b>' + name + '</b>'`) stands in as a word; where a tag or an attribute
+  name would go, or as an unquoted attribute value (`` `<${tag}>` ``, ``
+  `<img ${attrs}>` ``, `` `<img src=${u}>` ``), it is named for review —
+  quote values, write tags and attributes down.
+- A constant spelled across pieces anywhere in the code (`'java' +
+  'script:x'`, `['<img o', 'nerror=x>'].join('')`, `atob('PGltZy…')` in a
+  helper) is judged where it stands, as a literal is.
+- A method that sets attributes or builds markup or elements kept in a name,
+  bound or passed on instead of called: `const set = el.setAttribute`,
+  `el.setAttribute.bind(el)`, `document.createElement.bind(document)`,
+  `fn(el.insertAdjacentHTML)`, and its property descriptor taken
+  (`Object.getOwnPropertyDescriptor(Element.prototype, 'innerHTML')` kept, or
+  of a name not written down). Call it where you use it (`.call`, `.apply`,
+  `Reflect.apply`, `Function.prototype.call.call` and `desc.set.call(el, v)`
+  / `desc.value.call(el, …)` are read through to the call; `if
+  (el.setAttribute)` and `typeof el.setAttribute` are checks, not references).
+  `a.protocol = 'javascript'` turns a link into a `javascript:` URL and is
+  refused like one; `navigator[k]`, `location[k]`, `screen[k]`, `crypto[k]`,
+  `performance[k]`, `Reflect.get(navigator, k)` with `k` computed are refused
+  (write the name, or a list of names a loop runs over).
+- A `Blob`, `File` or `Response` of JavaScript or of a document whose text
+  is not written down (`new Blob([code], { type: 'text/javascript' })` with
+  `code` computed, `new Response(t, { headers: { 'content-type': 'text/html'
+  } })`, headers not written down): put a worker in a `.js` file. One written
+  down is read as code (its rules apply), as a page (`text/html`) or as XML
+  (`application/xhtml+xml`, `image/svg+xml`, any `+xml` type: prefixes
+  dropped, a DTD subset refused, as a framed document is).
+- A `data:` URL that is a page (`data:text/html,…`), an SVG `data:` URL that
+  holds a script or a handler, a `data:` script, or a `data:` body the scan
+  cannot decode. Inline SVG icons as `data:image/svg+xml` are fine.
+- A handler attribute, a `<script>`, a `javascript:` URL or a `data:` page in
+  a `.json` or `.txt` file's text, or in a page's data block (`<script
+  type="application/json">`, `<xmp>`, `<textarea>`): what the game fetches
+  or reads back may reach the page as markup, so data files and data blocks
+  are read as the code's strings are (`<b>` in a translation is fine). A
+  `.json` that does not parse, or a data file of more than a million values,
+  is refused: the scan reads nothing it cannot read to the end.
+- `import()` of a URL (`https:`, `data:`, `blob:`) or of a computed address
+  (`import('./views/' + name + '.js')` — import each path literally); a `<script
+  type="importmap">`; a `<script src="data:…">`; an SVG or XML document
+  (`.svg`, `.xml`, `.xhtml`, `.xsl`) with a `<script>` (under any namespace
+  prefix: `<svg:script>` is one) or a handler attribute — a frame runs them as
+  a page. The scan reads such a document as the browser renders it, prefixes
+  dropped (`svg:onload` is `onload`), and refuses outright what it would have
+  to emulate the parser to read: an internal DTD subset (`<!DOCTYPE svg [ …
+  ]>`), any `<!ENTITY>` or `<!ATTLIST>` declaration (an entity becomes markup
+  where it is referenced, an attribute default — an `onload` among them — is
+  added to every such element), and an `<?xml-stylesheet?>`. Export art as
+  plain SVG without a DTD (Illustrator: *Export As → SVG*, not the SVG 1.1
+  DTD profile; an external `<!DOCTYPE svg PUBLIC …>` with no `[ … ]` is
+  fine, browsers do not fetch it).
+- `WebSocket`, WebRTC (`RTCPeerConnection`), `navigator.serviceWorker`,
+  `fetch('/api/…')` of a server of your own (saved data goes through
+  `engine.state`), the string `/csp-report`, any URL outside the bundle.
+- Own CSP, `<base>`, meta refresh, `<object>`/`<embed>`, `srcdoc`, a copy of
+  `engine-sdk/`.
+- No bet of its own: a play with no click of the player's behind it is
+  refused, and an autoplay loop that is not a shell session runs only for the
+  click's few seconds, then is refused (§3.1).
+- WebAssembly reached by your own code, and any WebAssembly module whose
+  bytes are not a known library release (§3.6).
+- **Minified or obfuscated code without a source map.** The measure: a file
+  with twenty names or more, nine in ten of them one or two letters, is
+  minified (every minifier's output is at 98–100%; the densest hand-written
+  game we have is at 72%). Names of the form `_0x1a2b` or ASCII text written
+  in `\x`/`\u` escapes are an obfuscator's and refused outright. Ship readable
+  code, or ship the build with its source map in the bundle — the `.map`
+  beside the file or named by its `//# sourceMappingURL=` comment (an inline
+  `data:` map works too), version 3, with `sourcesContent` (Vite: `build:
+  { sourcemap: true }`; esbuild: `--sourcemap`). A minified inline script
+  has nowhere for a map: put built code in a `.js` file. The reviewer reads
+  the sources; the play-tests play the real bytes.
+- A file that does not parse as JavaScript (as a module or as a classic
+  script): a browser would refuse it too.
+
+**Named for the reviewer** (the upload passes; each is listed with file and
+line, so the reviewer knows where to look — keep them to what the game
+needs): reading the date or time (`Date`, `Temporal`,
+`performance.timeOrigin`); the time zone or locale formatting
+(`getTimezoneOffset`, `Intl.DateTimeFormat`, `toLocale…`); the language
+outside the SDK (`navigator.language`, `Intl` — `engine.config.locale` is the
+player's language); the browser's identity (`userAgent`, `platform`,
+`hardwareConcurrency`, `deviceMemory`, `screen.colorDepth`,
+`navigator.webdriver`); a timer past 60 s or with a computed delay; state
+kept on the device (`localStorage`, `sessionStorage`, `indexedDB`, cookies —
+per device only, and anything a player keeps across devices goes through
+`engine.state`); a text field or form (`<input>`, `<textarea>`, `<form>`,
+`createElement('input')`: a game takes nothing typed but the stake) and
+words like "password" or "sign in" in its text; browser randomness
+(`Math.random`, `crypto.getRandomValues` — for visuals only, every outcome
+is the server's); a `fetch` of a computed address, `XMLHttpRequest`,
+`sendBeacon`; a Worker on a built URL or `URL.createObjectURL`; reaching the
+parent or top frame; `location` changes and `window.open`.
+
+## 4. Currencies — never compute money
+
+The player plays in any Housebets coin and may see it as a fiat (EUR, JPY,
+…) at the platform's rate. `engine.money` is the Originals' own money code
+bound to the session:
+
+```js
+const m = engine.money;
+m.unit, m.sign, m.decimals     // 'EUR', '€', 2   — or 'BTC', '', 8
+m.format(amount)               // a wallet amount, as the header shows it
+m.caption(amount)              // '0.00019230 BTC' under a fiat field
+m.parse(text)                  // what the player typed → wallet amount, truncated down
+m.mark                         // our picture of the currency (data: URI)
+```
+
+Stakes go to `engine.play` in **wallet units** at the wallet's precision;
+`<hb-bet-amount>` does all of it (mark, sign, precision, ½ 2× max, limits,
+remembered stake):
+
+```html
+<hb-bet-amount id="stake" max-button></hb-bet-amount>
+<script type="module">
+  const field = document.getElementById('stake').connect(engine);
+  field.bet = { mode: 'coin', bet: 'heads' };   // the bet the stake is for: its own ceiling (§4.1)
+  field.amount        // wallet units for engine.play
+  field.reason        // {code, message} when the stake cannot be played, else null
+</script>
+```
+
+Balances and payouts come from the server; show them with `m.format`.
+
+**Bet levels, as a slot shows them.** A game with its own bet buttons (a
+bet up/down, a bet menu) offers `m.levels(limits.min, limits.max)`: round
+stakes in the player's display unit — €0.10, €0.20, €0.50, €1 … or 0.1, 1,
+10 USDT — each with the wallet `amount` to send, the header's `text` and a
+`label` for the button (`€2.00`, `2 USDT`). Never show a raw wallet amount
+or a limit converted from dollars ("2,000.62019200 USDT"): the limits are
+set in dollars and converted to the coin at the live rate, so only the
+levels are round. Decimals never change the maths: a payout is the stake ×
+the multiplier, cut to the wallet's precision (10⁻⁸ for a coin).
+Bet up / down moves one level — never by a fixed amount such as the
+minimum bet or `m.step` (the wallet's smallest unit, 0.00000001): a button
+that adds the minimum takes a thousand clicks to go from 0.10 to 100. A
+stake is never below `engine.config.limits.min` and never 0: there is no
+free spin (§3.3), so a play button stays disabled until the field holds a
+playable stake (`field.reason === null` and `field.amount > 0`; an empty
+field's `reason` is `min`, and `engine.play` itself refuses a stake of 0
+with `limits` before anything is sent). The engine panel (`ui.js`) does
+exactly this.
+
+### 4.1 Maximum win per round
+
+No single round of any engine game pays more than the platform's **maximum
+win per round** (1,000,000 USD unless Housebets sets another figure; the
+same for every game), or the player's coin's own maximum win when that is
+less. The cap is enforced **before the bet**, never by cutting a win: a win
+reduced after the draw would change your RTP and break the round's
+provably-fair receipt. So the server refuses a stake whose largest possible
+win — the stake times the bet's top multiplier (`maxMultBp` of a table bet,
+the last `ladderBp` of a ladder) — would pass the cap, with a `limits`
+refusal that names the most the bet takes.
+
+What this means for your game: **a high-multiplier bet has a low maximum
+stake.** A bet that can pay 5,000× takes at most 1,000,000 / 5,000 = 200
+USD a round; one that can pay 1,000,000× takes at most a dollar. Your Maths
+card in House Studio (the game's page, once the maths are verified) shows
+the figure per bet (`Max stake`) and marks one under a dollar `under $1`.
+Choose your multipliers with that in mind: a 2× coin flip is held by the
+coin's max bet alone.
+
+The session says it per bet, in the wallet coin at its precision, rounded
+down:
+
+```js
+engine.config.limits.maxWin                    // the most one round pays, in the wallet coin
+engine.config.limits.maxStake.coin.heads       // "12.50": the most this bet takes
+```
+
+Nothing to compute: tell the field which bet the stake is for
+(`field.bet = { mode, bet }`; the engine panel does it on every
+selection) and it holds the stake to that bet's figure, turns red and says
+the most the bet takes when the player types more (`field.reason.code ===
+'maxWin'`; of the coin's max bet and the bet's own figure, the lower is the
+one named), and its max chip stops there. `engine.play` refuses a stake over
+the figure before anything is sent, with `limits` and the same message; a
+`limits` refusal from the server over the cap carries the figure too
+(`err.maxStake`, a decimal string in the wallet coin), so you can set the
+field to it (`field.value = err.maxStake`).
+
+A session that names `"0"` for a bet (and `maxWin` 0) means nothing can be
+staked on it until the coin's USD rate is back: the field says so (the
+Originals' "Something went wrong" line) and hides its max chip, a play
+button on `field.reason` stays disabled, and `engine.play` refuses with
+`unavailable`, as the server would. A session from an older server names no
+`maxStake` at all: then the coin's max bet alone holds in the SDK, and the
+server is the last word anyway.
+
+## 5. Languages
+
+`engine.config.locale` is the player's language (the site's). The panel,
+the field and every refusal are already in it (13 languages). Your own
+strings: ship them as `bundle/i18n.json` — `{ "en": {…}, "ru": {…} }` —
+and pick by `engine.config.locale`, falling back to `en` (required). The
+engine panel names modes and bets from your math's labels; give it names
+by language with `mount(el, { labels: { de: { base: 'Drehen' } } })`
+(the lines and keno templates do). The
+upload tells you which of the site's languages (`ar da de en es fi fr hi hu
+id it ja ko pl pt ru th tr vi zh`) you lack. Numbers and money: always
+through `engine.money`.
+
+## 6. What the upload checks — the whole list
+
+`hbengine upload` = `verify` + `lint` + the portal's conformance run (about
+two minutes on real desktop and phone frames; `hbengine status` shows the
+state meanwhile). A version is `sandbox` only when every line is `ok`:
+
+| check | what passes |
+|---|---|
+| math | the pack verifies (§2): format, RTP band, every bet pays |
+| budgets | §3 sizes; `assets.json` well formed, `boot` present, every file in one group |
+| code | every script parsed: nothing of §3.7's refused list, in any spelling (libraries under `vendor/` we know: named, §3.5); what is named for review is listed with file and line |
+| readable | no minified or obfuscated code without its source map; WebAssembly only as a known library's released module, run by the library (§3.6, §3.7) |
+| engine use | the code connects, calls `play`, calls `revealed` |
+| boot (desktop, phone) | `hello` answered and `ready()` within 25 s |
+| idle | left untouched for 15 s, the game places no bet: a bet is always the player's act (and the shell refuses one with no click behind it, §3.1) |
+| bet | one bet through your UI (`hbtest.json`), pressed with a real click, reaches `engine.play`, then `revealed` |
+| shows | with `shows` in `hbtest.json`: the element shows the value of the round the server drew |
+| draws | after the round, the play area shows something: its visible content covers at least 2% of the frame (a board with no size fails) |
+| picture | the screenshot of the frame is not one flat colour (a warning for the reviewer for now): a canvas that drew nothing, or WebGL that could not start, shows a black frame. The run draws WebGL on the CPU (SwiftShader), so a WebGL game must start without a GPU |
+| currency | under a fiat display (desktop) and a bare coin (phone): the stake sent equals what the Originals send for the typed amount; the screen shows that currency |
+| outage | the next bet meets an ambiguous wallet answer: the game keeps running, the site is asked to re-read the wallet |
+| fit | the game fits the frame it is given — 1194×720 and 364×720, then fullscreen 1920×1080 and 390×844: no page scrolls, every visible control is inside the frame, no text (or more than a tenth of a picture) is cut by its edge |
+| errors | no uncaught error in any page |
+| network | no request leaves the bundle's origin, and the policy refuses nothing (a blocked worker, script or style fails the run) |
+
+Then a reviewer plays it (`sandbox → review → live`), with a kill switch at
+every level. Money, seeds, limits and refunds are the platform's and the
+same as for every House Original: you never handle them.
+
+## 7. Examples
+
+`engine-examples/`: **coin** (table, engine panel, 30 lines), **dice**
+(97 bets, the zone picks), **slot** (110,592-row table, reels from
+`round.data`), **lines** (a video slot from the maths kit: 5×3, ten lines,
+wild, scatter, free spins ×2 with retriggers, 96.00% exactly), **tumble**
+(a 6 × 5 scatter-pays grid with tumbles and free-spin multipliers, 96.00%
+exactly), **keno** (40 numbers, 1–10 picks, hypergeometric weights; the
+picks choose the mode), **crash** (a 64-level ladder with cash-out that
+the page climbs itself with `game.advance()`; 99% at every level), **mines** (a ladder of reveals, 1–24 mines, exact
+weights per reveal), **plinko**
+(8/12/16 rows × three risks, binomial weights), **tower** (8-step ladder
+with cash-out), **wheel** (three modes). BAD CAT (`badcat-engine/`) is a full custom frontend ported as a
+studio would.
+
+## 8. Review
+
+Every version a player can see is reviewed by a person at Housebets first. Review works like a pull request.
+
+1. Run `npx hbengine preflight` (or `engine_preflight`) first: on the newest version that passed every check (the one submit sends), it checks what a machine can of the review checklist — the RTP and max win your rules quote against the verified maths, rules in every language, the store page, phone and desktop fit, errors, load and network — and prints the facts the rules must quote. A pre-flight fail is pre-ticked on the reviewer's checklist; a pass is a note to them, not a tick, since each item asks more than a machine sees. Then `npx hbengine submit` (or `engine_submit`, or the Review tab) sends the newest version that passed every check.
+2. The reviewer plays it on desktop and phone and goes through the **review checklist** (the game's Review tab, and `checklist` in `engine_review`): the maths against the rules and the screen, the rules in every language, phone and desktop play, sound, recovery from errors, content you own, nothing aimed at children, no outcome logic or outside servers in the bundle, an honest store page. Go through it yourself before you submit.
+3. Anything to change is a **thread** on the version: a **must fix** blocks going live, a **suggestion** does not. Each thread names its area and says what, where and why.
+4. Fix every must-fix thread in the project, upload the new version and submit it. Submitting marks the open must-fix threads as fixed in that version (on the Review tab you can untick any it does not fix). To ask the reviewer something instead, reply on the thread (`npx hbengine reply --thread 12 --message "…"`, `engine_reply`, or the Review tab), in at most 4,000 characters.
+5. The reviewer checks each fix and resolves the thread, or reopens it with a reply.
+6. With no must-fix left, the version is approved: the studio's owners and its uploaders get an email. An owner puts it live: **Make live** on the Versions tab, `npx hbengine live` in the project, or `engine_live` (with a key an owner made). The round server and the front end switch within seconds, and everyone gets an email that it is live. The first time, players find the game on Housebets once Housebets switches its catalogue page on; we email you when it is. Players keep the live version until then.
+
+With an agent: "fix the review" is `engine_review` → change the project → `engine_upload` → `engine_preflight` → `engine_submit`; "put it live" is `engine_status` (is it approved?) → `engine_live`.