hbengine 0.2.3 → 0.4.0

package/engine-sdk/GUIDE.md

@@ -23,16 +23,18 @@ 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 upload     # verify + lint + direct-to-storage upload; the sandbox plays it; the dashboard has the checks
+npx hbengine store      # store.json → the store page (Housebets makes the tile)
 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
+dragging the folder in, the store page, the sandbox in any coin
 and language with a forced first round, submit for review, go live,
-reports, statements and payouts.
+reports, statements and payouts. The tile on Housebets is ours: we make it
+from your game's own art when a version goes live, in the style of every
+tile on the site.
 
 `hbengine connect` opens the approve page in your browser; an owner or
 developer approves there, and the terminal shows which studio did and asks
@@ -141,7 +143,7 @@ stops, the trap tile), the server never reads it:
   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`).
+  accepts, because it is the same code (the engine's own verifier).
 - 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
@@ -180,7 +182,23 @@ writePack('math', { game: 'my-slot', rtpBp: 9600, modes: [{ id: 'base', rows, be
   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.
+  limits and prints RTP, hit rate and max win. The limits, the same the
+  upload enforces: 2 to 1,000,000 rows per mode, Σ weights under 2^63, a
+  row's data at most 4096 UTF-8 bytes, at most **16,384 distinct payouts (tiers)
+  per bet** (round multipliers to fewer values when a bonus-buy mode has
+  more), and at most 64 modes and 256 bets per mode.
+- **Pack size.** The maths in a pack (the files in `math/` together, as
+  they are on disk) may be at most **200 MB**. `writePack` refuses more, so
+  does `hbengine` before it sends anything (`verify`, `pack`, `upload`), and
+  so does the upload's own check.
+- With a studio key, `hbengine verify` (and the check `upload` and `pack`
+  run first) sends the maths to House Studio's hosted pre-check, which may
+  not take the larger packs within that limit: it takes about **32 MiB**
+  of request, and the maths sent as JSON are somewhat bigger than on disk
+  (each tab and line break counts twice). That is not a verdict on the
+  maths: `upload` and `pack` say the pre-check could not take the pack and
+  carry on, and the upload's own check verifies it. `verify` alone says the
+  same and exits with an error, as it could not check the maths.
 - 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
@@ -194,6 +212,78 @@ 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.
 
+### 2.2 Meters — progress that pays
+
+A **meter** is progress a player builds across rounds that changes what a
+round pays: a potion that fills and pours a giant crystal, a jackpot bar, a
+"collect to bonus" counter. It is kept by the House Engine (never by your
+page or by `engine.state`), in the same transaction as each round, and it is
+part of the verified maths. Your page shows it; it cannot change it.
+
+**The rule.** A meter fills with the **money staked** in its modes, not with
+a count of rounds. Its award comes after `fill × reference` has been staked,
+where the *reference* is the stake of the round that started the meter
+(capped, below). The round that fills it also draws once from the meter's
+**award table**, which pays multiples of the reference — added to that
+round's payout, in its one credit. Then the meter starts again (whatever
+the filling round had left over starts the next one).
+
+```json
+"meters": [{ "id": "potion", "label": "Potion", "fill": 250, "table": "potion.tsv",
+             "award": [{ "outcomes": [[0, 59]], "multBp": 20000 }, { "outcomes": [[60, 84]], "multBp": 30000 }] }],
+"modes":  [{ "id": "8-low", "kind": "table", "table": "8-low.tsv", "meter": "potion", "bets": [ … ] }]
+```
+
+- `fill`: 2 to 1,000,000. `award` tiers pay `multBp` **of the reference**
+  (10000 = the reference once); rows no tier lists pay nothing.
+- One meter per mode (`"meter": id`, table modes only); several modes may
+  share one meter. A meter is kept per player, game, meter id and coin, and
+  carries over to your new versions while its `id` stays the same — give a
+  meter a **new id** whenever you change its `fill` or its award.
+- With the maths kit: `writePack(dir, { …, modes: [{ …, meter: 'potion' }],
+  meters: [{ id: 'potion', fill: 250, rows: [{ weight, pay, data }] }] })` —
+  `pay` in bp of the reference; it prints each bet as base + meter.
+
+**Why it is safe, for you and for the player.** Every unit staked buys
+exactly `1/fill` of an award worth `E[award] × reference`, so what a meter
+adds to the RTP is exact and the same whatever the player does — small
+stakes then a big one, stopping and coming back, any order:
+
+    RTP of a bet = its base RTP + E[award] ÷ fill
+
+The verifier computes it exactly and refuses a pack whose total passes the
+declared `rtpBp`; the **base alone must also be at least 90%**, so a player
+who leaves before a meter fills has still played a fair game.
+`hbengine verify` shows both (`rtp` and `baseRtp`) and each meter's
+`awardEv`, `awardMax` and what it adds.
+
+**Maximum win.** A round's base win may use at most half the round's
+maximum win and a meter's award the other half: the stake limits of a mode
+with a meter are set for that (`limits.maxStake` is lower than without the
+meter), and a meter's reference is capped at the largest stake whose top
+award fits its half (`anchorCap`) — a very large stake fills a meter of a
+smaller reference, more often. A stake that would fill a meter while its
+award no longer fits is refused, never reduced (code 21).
+
+**In the page.**
+
+```js
+const meters = await engine.meters();   // [{ id, label, fill, filled, target, reference, anchorCap }] in the coin
+const { round } = await engine.play({ mode, bet, amount });
+round.meter;   // { id, before, after, award? }: award = { reference, multBp, payout, draw, data }
+```
+
+`round.payout` already includes the award; `award.data` is the award row's
+data (what your page draws), `award.payout` its part of the payout. The
+round's receipt carries the meter, and the Provably Fair dialog verifies the
+award's draw: it is the round stream's next draw after the round's own.
+
+**Review.** The meter is visible at all times while its mode is played, and
+the rules say how it fills, what the award pays (on the reference, not the
+last stake), the RTP as base + meter, and that an unfinished meter is kept
+for the player. The `plinko-jar` template (`hbengine init --template
+plinko-jar`) is a complete one: maths, jar and page.
+
 ## 3. The bundle
 
 `bundle/index.html` at the root, everything relative. Budgets: boot group
@@ -211,7 +301,8 @@ const { round, balance } = await engine.play({ mode: 'coin', bet: 'heads', amoun
 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 }
+//          step, payout, multBp, data: [row JSON per draw], draws: [{index, raw, rejected}], nonce, mathHash,
+//          meter?: { id, before, after, award? } — a mode with a meter, §2.2 }
 // 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,
@@ -225,6 +316,7 @@ engine.on('balance' | 'control' | 'pause' | 'resume' | 'ended' | 'autoplay', fn)
 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
+engine.meters()                            // the player's meters in this coin (§2.2); round.meter on every round of a meter mode
                                            // 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
@@ -248,7 +340,9 @@ 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
+does not; a `focus()` your script calls does not count either, and before
+the player's first tap it makes the shell refuse every play for 5 s, see
+below) — 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
@@ -282,6 +376,16 @@ so the shell bets nothing there and the refusal names the browsers that can
 conformance run presses your Bet with a real click, so a game that bets from
 the click handler passes as before.
 
+**Never call `focus()` before the player's first tap.** A script that moves
+the focus into its frame (an intro's Continue button focused when it
+appears, say) is taken as focus not given by the player: the shell undoes it
+and refuses every play with `needs-click` for the next 5 s, the player's own
+taps included. An `autofocus` attribute and a dialog's `show()` or
+`showModal()` move the focus too, so the same applies to them. On a phone
+the first taps on Spin then do nothing. Desktop browsers do not show it
+(they already have the player's activation), so you only see it on a real
+phone; the conformance run's `focus` check catches it before then.
+
 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;
@@ -365,6 +469,30 @@ el.addEventListener('select', (e) => draw(e.detail.mode));   // the panel's pick
 // tables: what your zone draws (a wheel's segments, a paytable) is a constant of yours.
 ```
 
+#### Saving player progress — `engine.progress`
+
+Anything a player builds up for show — skins, a collection, achievements,
+settings, a streak shown for fun — goes in **`engine.progress`**. It is kept
+on the server for the player and the game: the same on every device and in
+every version you upload. **Browser storage is not**: each version is served
+from its own address, so `localStorage` and IndexedDB start empty on every
+new version and on every other device — progress kept only there "resets".
+
+```js
+await engine.progress.ready;                       // loaded: nothing is saved before this
+const skins = engine.progress.get('skins', []);    // a value, or your fallback
+engine.progress.set('skin', 'tabby');              // saved within ~2 s, and when the page goes
+engine.progress.update('drops', (n = 0) => n + 1);
+await engine.progress.migrate(['my-game-skins']);  // once: values you kept in localStorage move over
+```
+
+It saves at most every two seconds, merges with another tab's save instead
+of overwriting it, and refuses a value that would take the player's saved
+data past 256 KB when you set it (`engine.state` is the same store,
+underneath; use one or the other for a key). Saved progress never changes a
+payout: progress that pays is a meter (§2.2). Keep in the browser only what
+may be lost (a panel left open, the last tab).
+
 ### 3.2 Loading in stages — `assets.json`
 
 ```json
@@ -381,13 +509,17 @@ 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
+column's width × **up to 720 px**, wider in theatre mode and the whole
+screen in fullscreen (the site's buttons). On a phone or tablet the frame
+is the room between the site's header and its bottom nav, so its height is
+the phone's: about 440 px on a 375×667 iPhone, 700 on a tall Android; on a
+laptop the window can make it shorter than 720 too. 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
+re-fit when it changes (a portrait layout that needs 600 px loses its Spin
+row on most phones). The frame never grows to the page and never scrolls:
+the pipeline plays your game at 1194×720, 1194×582, 364×720 and 364×440,
+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.
@@ -416,6 +548,25 @@ or otherwise.
 
 ### 3.4 `hbtest.json` — how the pipeline plays one bet
 
+**A game that draws its own interface: use the SDK's Bet button.** It is the
+easiest way through this section and the time-travel control check (§6):
+
+```html
+<script type="module" src="/engine-sdk/bet.js"></script>
+<hb-bet></hb-bet>   <!-- or <hb-bet><img slot="icon" src="spin.png" alt=""> Spin</hb-bet> -->
+```
+```js
+bet.addEventListener('bet', () => spin());   // only the player's press fires it
+bet.busy = true;                             // during a round
+```
+
+Style it with `--hb-bet-bg`, `--hb-bet-color`, `--hb-bet-radius`,
+`--hb-bet-font` and `hb-bet::part(button)`. Its size (at least 48×48), opacity,
+visibility and pointer are the SDK's and cannot be styled away, so it always
+passes the control check. The run finds it by itself: a game that loads
+`/engine-sdk/bet.js` needs no `hbtest.json` (keep one only to type a stake or
+open a screen before the 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" },
@@ -444,19 +595,40 @@ The engine panel's selectors are a contract: `hb-game hb-bet-amount input`
 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.
 
+**The Bet control is the player's own button.** The run presses what a
+player presses, and the time-travel runs (§6) measure the element `bet`
+names once the stake is typed. It must be:
+
+- at least **32×32** CSS pixels;
+- at least **half opaque**, counting its parents' opacity;
+- visible (`visibility: visible`), taking the pointer (no
+  `pointer-events: none`), enabled, and inside the frame.
+
+A stand-in the player never sees or presses is refused, even when the real
+button is drawn on a canvas: a transparent, tiny or off-screen element
+wired to `engine.play` would let the run pass while the button players
+use goes untested. A game drawn on a canvas gives its Bet button as a real
+DOM element the player clicks: a `<button>` over the canvas, styled or
+drawn as the button itself (the canvas draws nothing beneath it), or the
+engine panel's Bet (`hb-game [data-main]`).
+
 ### 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).
+`vendor/` as a library when its bytes are exactly a release's file as the
+package publishes it on npm (the same bytes a CDN serves): its SHA-256 is in
+`engine-conformance/js-releases.json` (today PixiJS 8.16.0, 8.22.0 and 7.4.3
+with its `unsafe-eval` module, GSAP 3.14.2 and 3.15.0, and the glue of the
+WebAssembly releases below; ask us to add a library or a version, we take
+the hash from the published tarball, never from a file in an upload). What
+it would refuse in your own code it then only names for the reviewer, the
+library may be minified as released, and the scan does not follow your
+values into it. Anything else under `vendor/` — a custom or rebuilt
+library, a bundler chunk, a file named and bannered like a library but not
+byte for byte its release — is read as your code (§3.7 applies, a source
+map and all), and the scan says which library it looked like.
 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.
@@ -495,8 +667,8 @@ only: **a known library's released module, run by that library's own code.**
   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
+  `vendor/`, byte for byte as released (§3.5: the glue of every release
+  above is in `js-releases.json`). 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.
@@ -734,8 +906,9 @@ 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.
+with `limits` before anything is sent). The field's `change` event also fires
+when a balance update changes `reason`, so the engine panel (`ui.js`) follows
+the balance as well as edits and bet selection.
 
 ### 4.1 Maximum win per round
 
@@ -799,9 +972,36 @@ 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`:
+**Run it first on your machine:** `hbengine test` plays the desktop and phone
+checks, and `hbengine test --time-travel` the fake-clock matrix too (your
+agent: `engine_test` with `timeTravel`). A failing line says what to change
+under it, here and on the dashboard.
+
+`hbengine upload` = `verify` + `lint` + the portal's conformance run: real
+desktop and phone frames, then the fake-clock matrix below (two to ten
+minutes; `hbengine status` shows the state meanwhile — upload the next
+version once it says the run is over). A version can reach `sandbox` with warnings or skipped coverage. Read each
+line: a skipped check or an endurance run that ended early is not a pass.
+The report marks incomplete coverage explicitly; Housebets can review the
+submission with those gaps visible and decide what still needs checking.
+
+**The run's machine is slow on purpose.** Chrome draws on the CPU
+(SwiftShader), with few animation frames, and the desktop and phone frames run
+one after the other in the same browser. So: call `ready()` from `connect()`'s
+resolution, not from `requestAnimationFrame` (a starved frame may not fire it
+in 25 s); keep idle CSS and canvas animations cheap (a button that never stops
+moving is never "stable" enough to click); load what the first screen needs
+first.
+
+Each frame-size context is closed before the next starts, including when a
+check fails. A boot or scripted-click failure keeps a screenshot when the
+renderer can answer, bounded console output, elapsed time, frame paths and
+the names of observed shell messages. The JSON report puts this evidence in
+`diagnostics.desktop` / `diagnostics.phone`, or in a failed time-travel
+variant's `diagnostics`. Runner Node/Chrome versions, CPU count, load and memory
+are included so a local result can be compared with the hosted machine.
+A missing screenshot is reported explicitly; diagnostic capture has a time
+limit so a stuck renderer cannot keep the rest of the run waiting.
 
 | check | what passes |
 |---|---|
@@ -812,15 +1012,17 @@ state meanwhile). A version is `sandbox` only when every line is `ok`:
 | 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) |
+| focus | until the run's first click (so through the idle wait too), nothing moves the focus: no `focus()` on an element or the window, no `autofocus` element on the page, no dialog `show()` or `showModal()`; a startup focus can make the shell refuse genuine bets for five seconds (§3.1). A warning for now, not a fail |
 | 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 |
+| outage | the next bet meets an ambiguous wallet answer: the game keeps running, the site is asked to re-read the wallet. **Not run yet** on the hosted upload, nor by `hbengine test` on an engine-dev with no wallet fault stub: both show it as skipped. Check it yourself: a refused or lost bet (`pending`, `server`, `unavailable`, §3.1) shows its message and gives the Bet control back, never a stuck game |
+| fit | the game fits the frame it is given — 1194×720, 1194×582, 364×720 and 364×440, 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) |
+| time-travel | the fake-clock matrix: the game boots and plays a round with the clock moved and the player elsewhere — `base` (now, UTC, en), a day on, a week on, a month on, a year on, a weekend, a holiday, the first of a month, and `long` (300 rounds). `hbengine test --time-travel` plays each at fixed clocks; an upload plays each kind at an instant, a time zone and one of the SDK's languages drawn for that upload, so make the game right for any date, zone and language, not for a list. Each variant also measures the Bet control (§3.4: at least 32×32 px, at least half opaque, visible, enabled, in the frame): a stand-in fails as "the bet control is …". After the first round the clock jumps 30 minutes ahead (a player who left the tab and came back), and every frame must keep up within 60 seconds: every timer that came due fires at once, so a game whose timers each do heavy work (a full render, rebuilding a scene, an interval catching up tick by tick) freezes and fails "the fake clock did not move". Let timers only mark that a frame is needed and draw at most once per `requestAnimationFrame`; after a gap, run an interval's work once. `/engine-sdk/frames.js` does both: `frame(draw)` (any number of requests before the next frame is one draw) and `every(ms, fn)` (after a gap it runs once, told how many periods it missed). The matrix has 510 s; a variant that does not fit in what is left is **skipped** and shown as skipped — not run, not passed — so read the report's time-travel lines, not only the verdict |
 
 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
@@ -845,7 +1047,7 @@ studio would.
 
 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.
+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 (a max win is in multiples of the stake of the bet that pays it: for a buy mode, its buy price, not the base bet), 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.

package/engine-sdk/bet-field.js

@@ -13,7 +13,7 @@
  *     field.bet = { mode, bet };                           // the bet the stake is for (its own ceiling)
  *     engine.play({ mode, bet, amount: field.amount });    // wallet units
  *     field.disabled = true;                               // while a round runs
- *     field.addEventListener('change', (e) => e.detail);   // { amount, reason }
+ *     field.addEventListener('change', (e) => e.detail);   // { amount, reason }; also on a balance update when reason changes
  *     field.value;                                         // the same as text, like an <input>
  *
  * The rule is the Originals' (bet field: coinflip-frontend BetAmount.svelte,
@@ -101,6 +101,7 @@ export class BetAmountField extends HTMLElement {
     #typing = false;
     #hintTimer = 0;
     #note = '';
+    #reasonCode = null;
     #els;
 
     constructor() {
@@ -128,7 +129,11 @@ export class BetAmountField extends HTMLElement {
     connect(engine) {
         this.#engine = engine;
         this.#money = engine.money;
-        engine.on('balance', () => this.#render());
+        engine.on('balance', () => {
+            const before = this.#reasonCode;
+            this.#render();
+            this.#announceReasonChange(before);
+        });
         const kept = this.#recall();
         if (kept > 0) this.#amount = kept;
         this.#render();
@@ -166,10 +171,11 @@ export class BetAmountField extends HTMLElement {
     set bet(v) {
         const next = v && typeof v.mode === 'string' && typeof v.bet === 'string' ? { mode: v.mode, bet: v.bet } : null;
         if ((next && this.#bet && next.mode === this.#bet.mode && next.bet === this.#bet.bet) || (!next && !this.#bet)) return;
+        const before = this.#reasonCode;
         this.#bet = next;
         this.#render();
         // Another bet may take less: whoever follows `reason` hears it changed.
-        this.dispatchEvent(new CustomEvent('change', { detail: { amount: this.#amount, reason: this.reason } }));
+        this.#announceReasonChange(before, true);
     }
 
     /** The most the selected bet takes, in wallet units, or null when the
@@ -278,6 +284,12 @@ export class BetAmountField extends HTMLElement {
         this.dispatchEvent(new CustomEvent('change', { detail: { amount: next, reason } }));
     }
 
+    #announceReasonChange(before, always = false) {
+        const reason = this.reason;
+        if (!always && before === (reason ? reason.code : null)) return;
+        this.dispatchEvent(new CustomEvent('change', { detail: { amount: this.#amount, reason } }));
+    }
+
     /** A note under the field for a few seconds (a refusal's message). */
     note(text) {
         this.#hint(String(text));
@@ -322,6 +334,7 @@ export class BetAmountField extends HTMLElement {
         e.sign.classList.toggle('empty', e.input.value === '');
         e.cap.textContent = m.caption(this.#amount) || '';
         const reason = this.reason;
+        this.#reasonCode = reason ? reason.code : null;
         // Red is for a stake the server would refuse; an empty field just
         // says what the least stake is.
         const wrong = !!reason && this.#amount > 0;

package/engine-sdk/bet.js

@@ -0,0 +1,88 @@
+/**
+ * The Bet button, for a game that draws its own interface.
+ *
+ *     import '/engine-sdk/bet.js';
+ *
+ *     <hb-bet></hb-bet>                         anywhere: over the canvas, in a bar
+ *     <hb-bet><img slot="icon" src="spin.png" alt=""> Spin</hb-bet>   the game's own art and words
+ *
+ *     bet.addEventListener('bet', () => spin());   // the player's press, and nothing else
+ *     bet.busy = true;                             // during a round: shown, not pressable
+ *
+ * The button a player presses is the one the upload's check presses and
+ * measures (GUIDE §3.4): a real button, at least 48×48 px, fully opaque,
+ * taking the pointer. Those few things are fixed here (`!important` inside
+ * the element outranks the game's styles); everything else is the game's:
+ * `--hb-bet-bg`, `--hb-bet-color`, `--hb-bet-radius`, `--hb-bet-font`, and
+ * `hb-bet::part(button)` for the rest. A game with this button needs no
+ * hbtest.json: the check finds `hb-bet` on the game's first page and presses it.
+ *
+ * `bet` fires on a press by the player only, never on a click made by code:
+ * a bet is the player's act, and the shell refuses one without it anyway.
+ */
+
+const CSS = `
+:host { display: inline-block; vertical-align: middle; }
+:host([hidden]) { display: none; }
+button {
+  min-width: 48px !important; min-height: 48px !important;
+  opacity: 1 !important; visibility: visible !important; pointer-events: auto !important;
+  display: inline-flex; align-items: center; justify-content: center; gap: 8px;
+  box-sizing: border-box; width: 100%; height: 100%; padding: 0 20px; border: 0; cursor: pointer;
+  border-radius: var(--hb-bet-radius, 8px);
+  background: var(--hb-bet-bg, #28F3F3); color: var(--hb-bet-color, #041015);
+  font: 600 16px/1 var(--hb-bet-font, var(--hb-font, 'Figtree', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif));
+  transition: transform 120ms ease, filter 120ms ease;
+}
+button:hover { filter: brightness(1.08); }
+button:active { transform: scale(0.98); }
+button:disabled { cursor: progress; filter: saturate(0.6) brightness(0.85); transform: none; }
+::slotted([slot="icon"]) { max-height: 100%; }
+@media (prefers-reduced-motion: reduce) { button { transition: none; } }
+`;
+
+export class BetButton extends HTMLElement {
+    static observedAttributes = ['busy', 'label'];
+    #button;
+    #label;
+
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = CSS;
+        root.append(style);
+        this.#button = document.createElement('button');
+        this.#button.type = 'button';
+        this.#button.setAttribute('part', 'button');
+        const icon = document.createElement('slot');
+        icon.name = 'icon';
+        this.#label = document.createElement('slot');
+        this.#label.textContent = 'Bet';
+        this.#button.append(icon, this.#label);
+        root.append(this.#button);
+        this.#button.addEventListener('click', (e) => {
+            if (!e.isTrusted || this.busy) return;
+            this.dispatchEvent(new CustomEvent('bet', { bubbles: true, composed: true }));
+        });
+    }
+
+    /** True while a round runs: the button stays on screen and takes no press. */
+    get busy() { return this.hasAttribute('busy'); }
+    set busy(on) { this.toggleAttribute('busy', !!on); }
+
+    attributeChangedCallback(name, _old, value) {
+        if (name === 'busy') {
+            this.#button.disabled = value !== null;
+            if (value !== null) this.setAttribute('aria-busy', 'true');
+            else this.removeAttribute('aria-busy');
+        }
+        if (name === 'label') this.#label.textContent = value || 'Bet';
+    }
+
+    /** The real button (focus, measuring). */
+    get button() { return this.#button; }
+    focus(options) { this.#button.focus(options); }
+}
+
+if (globalThis.customElements && !customElements.get('hb-bet')) customElements.define('hb-bet', BetButton);

package/engine-sdk/frames.js

@@ -0,0 +1,75 @@
+/**
+ * Drawing and repeating that never pile up.
+ *
+ *     import { frame, every } from '/engine-sdk/frames.js';
+ *     frame(draw);                                  // draw at the next animation frame
+ *     const t = every(1000, (missed) => tick(missed));
+ *     t.stop();
+ *
+ * When time jumps (a player comes back to a tab after half an hour; the
+ * upload's check moves the clock 30 minutes on purpose) every timer that came
+ * due fires at once. A game whose timers each draw the whole scene, or whose
+ * interval catches up tick by tick, freezes: the check fails it "the fake
+ * clock did not move" (GUIDE §6). These two cannot:
+ *
+ * - `frame(draw)`: every request before the next animation frame is one call
+ *   of `draw` (each different function once), so a burst of timers asking to
+ *   draw costs one draw.
+ * - `every(ms, fn)`: once per period; after a gap it runs once, told how many
+ *   periods it missed (`fn(missed)`), never once per missed period. One timer
+ *   is pending at a time, so a jump can only fire it once.
+ */
+
+const browser = () => ({
+    now: () => globalThis.performance.now(),
+    setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimer: (t) => globalThis.clearTimeout(t),
+    raf: (fn) => (globalThis.requestAnimationFrame ? globalThis.requestAnimationFrame(fn) : globalThis.setTimeout(fn, 16)),
+});
+
+/** The helpers on a given clock (the tests'), or the page's. */
+export function createFrames(clock = browser()) {
+    const { now, setTimer, clearTimer, raf } = clock;
+    const asked = new Set();
+    let pending = false;
+
+    function frame(draw) {
+        if (typeof draw !== 'function') throw new TypeError('frame(draw): draw is a function');
+        asked.add(draw);
+        if (pending) return;
+        pending = true;
+        raf(() => {
+            pending = false;
+            const draws = [...asked];
+            asked.clear();
+            for (const d of draws) {
+                try { d(); } catch (e) { setTimer(() => { throw e; }, 0); }
+            }
+        });
+    }
+
+    function every(ms, fn) {
+        if (!(ms > 0) || typeof fn !== 'function') throw new TypeError('every(ms, fn): a period above 0 and a function');
+        let last = now();
+        let timer = null;
+        let stopped = false;
+        const run = () => {
+            timer = null;
+            if (stopped) return;
+            const t = now();
+            const periods = Math.max(1, Math.floor((t - last) / ms));
+            // The next run keeps the rhythm from the last period that ended, not from this late call.
+            last += periods * ms;
+            try { fn(periods - 1); } catch (e) { setTimer(() => { throw e; }, 0); }
+            if (!stopped) timer = setTimer(run, Math.max(0, last + ms - now()));
+        };
+        timer = setTimer(run, ms);
+        return { stop() { stopped = true; if (timer !== null) clearTimer(timer); timer = null; } };
+    }
+
+    return { frame, every };
+}
+
+const page = createFrames();
+export const frame = page.frame;
+export const every = page.every;