hbengine 0.2.3

package/engine-examples/keno/math-kit/pack.mjs

@@ -0,0 +1,165 @@
+/**
+ * The maths kit: a game's outcomes as weighted rows, its RTP exactly, and the
+ * pack the engine verifies (SPEC §1). A row is { weight, data, pay } where
+ * pay is { betId: multBp } (10000 = 1×, the total stake back) and data is
+ * what the bundle receives to show the round.
+ *
+ *   import { writePack, fit } from './pack.mjs';
+ *   const rows = fit(simulated, 9600);            // exact 96.00% (balance() when no row pays nothing)
+ *   writePack('math', { game: 'my-slot', rtpBp: 9600, modes: [{ id: 'base', rows, bets: ['spin'] }] });
+ *
+ * Every number here is an integer: weights are BigInt, RTP is a fraction.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MAX_SUM = 1n << 63n;
+
+// A small seeded generator for building tables (never for play: the engine draws).
+export function rng(seed) {
+    let a = seed >>> 0;
+    const next = () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    next.int = (n) => Math.floor(next() * n);
+    return next;
+}
+
+export function binomial(n, k) {
+    let r = 1n;
+    for (let i = 1n; i <= BigInt(k); i++) r = (r * BigInt(n - k) + r * i) / i;
+    return r;
+}
+
+const gcd = (a, b) => { while (b) [a, b] = [b, a % b]; return a < 0n ? -a : a; };
+
+/** RTP of one bet over rows, exactly: { num, den } in basis points, and a 4-decimal string. */
+export function rtp(rows, bet) {
+    let num = 0n, den = 0n;
+    for (const r of rows) { den += r.weight; num += r.weight * BigInt(r.pay[bet] || 0); }
+    return { num, den, bp: bp4(num, den) };
+}
+
+export const bp4 = (num, den) => {
+    const x = (num * 10000n) / den; // bp × 10^4, truncated as the verifier reports it
+    return `${x / 10000n}.${String(x % 10000n).padStart(4, '0')}`;
+};
+
+/**
+ * Weights so that one bet's RTP is exactly targetBp: the paying rows keep
+ * their proportions (all multiplied by one integer), the rows that pay
+ * nothing share what is left in their own proportions. Needs rows that pay
+ * nothing, and paying rows that alone return more than the target.
+ */
+export function fit(rows, targetBp, bet = Object.keys(rows[0].pay)[0]) {
+    const T = BigInt(targetBp);
+    const wins = rows.filter((r) => r.pay[bet] > 0), zeros = rows.filter((r) => !(r.pay[bet] > 0));
+    if (!zeros.length) throw new Error('fit: no row pays nothing');
+    const S = wins.reduce((s, r) => s + r.weight * (BigInt(r.pay[bet]) - T), 0n); // what the wins return above T
+    if (S <= 0n) throw new Error(`fit: the paying rows alone return less than ${targetBp / 100}%`);
+    const k = T / gcd(S, T);     // so that k·S is a multiple of T
+    const Z = (k * S) / T;       // the weight the zero rows share
+    const zw = zeros.reduce((s, r) => s + r.weight, 0n);
+    let given = 0n;
+    const out = rows.map((r) => {
+        if (r.pay[bet] > 0) return { ...r, weight: r.weight * k };
+        const w = (Z * r.weight) / zw;
+        given += w;
+        return { ...r, weight: w };
+    });
+    // The rounding remainder goes to the first zero row; a zero weight is dropped.
+    const first = out.find((r) => !(r.pay[bet] > 0));
+    first.weight += Z - given;
+    const kept = out.filter((r) => r.weight > 0n);
+    const check = rtp(kept, bet);
+    if (check.num !== T * check.den) throw new Error('fit: not exact (a bug)');
+    return kept;
+}
+
+/**
+ * Weights so that one bet's RTP is exactly targetBp when every row pays
+ * something (a bonus buy, plinko): rows paying more than the target are
+ * all multiplied by one integer, rows paying less by another, so each
+ * group keeps its own proportions and the two balance at the target.
+ */
+export function balance(rows, targetBp, bet = Object.keys(rows[0].pay)[0]) {
+    const T = BigInt(targetBp);
+    const over = rows.reduce((s, r) => s + (BigInt(r.pay[bet] || 0) > T ? r.weight * (BigInt(r.pay[bet]) - T) : 0n), 0n);
+    const under = rows.reduce((s, r) => s + (BigInt(r.pay[bet] || 0) < T ? r.weight * (T - BigInt(r.pay[bet] || 0)) : 0n), 0n);
+    if (!over || !under) throw new Error('balance: needs rows on both sides of the target');
+    const g = gcd(over, under);
+    const out = rows.map((r) => ({ ...r, weight: r.weight * (BigInt(r.pay[bet] || 0) > T ? under / g : BigInt(r.pay[bet] || 0) < T ? over / g : 1n) }));
+    const check = rtp(out, bet);
+    if (check.num !== T * check.den) throw new Error('balance: not exact (a bug)');
+    return out;
+}
+
+/** Rows with the same data are one row with the sum of their weights. */
+export function merge(rows) {
+    const by = new Map();
+    for (const r of rows) {
+        const key = JSON.stringify(r.data);
+        const x = by.get(key);
+        if (x) x.weight += r.weight;
+        else by.set(key, { ...r, weight: r.weight });
+    }
+    return [...by.values()];
+}
+
+// Inclusive [lo, hi] ranges of sorted indexes.
+function ranges(ids) {
+    const out = [];
+    for (const i of ids) {
+        const last = out.at(-1);
+        if (last && last[1] === i - 1) last[1] = i;
+        else out.push([i, i]);
+    }
+    return out;
+}
+
+/**
+ * Writes manifest.json and one table per mode. A mode is { id, label?, rows,
+ * bets: [id | {id, label}] }; its rows are sorted by what the first bet pays,
+ * so each pay tier is one range. Prints every bet's exact RTP, hit rate and
+ * largest multiplier; returns them.
+ */
+export function writePack(dir, { game, rtpBp, modes }) {
+    mkdirSync(dir, { recursive: true });
+    const manifest = { format: 'house-engine-math/1', game, rtpBp, modes: [] };
+    const report = [];
+    for (const mode of modes) {
+        const bets = mode.bets.map((b) => (typeof b === 'string' ? { id: b } : b));
+        const first = bets[0].id;
+        const rows = [...mode.rows].sort((a, b) => (a.pay[first] || 0) - (b.pay[first] || 0));
+        if (rows.length < 2 || rows.length > 1_000_000) throw new Error(`${mode.id}: 2 to 1,000,000 rows, not ${rows.length}`);
+        const sum = rows.reduce((s, r) => s + r.weight, 0n);
+        if (sum > MAX_SUM) throw new Error(`${mode.id}: weights sum to more than 2^63`);
+        const lines = rows.map((r) => {
+            if (r.weight <= 0n) throw new Error(`${mode.id}: a weight is not positive`);
+            const json = r.data === undefined ? '' : JSON.stringify(r.data);
+            if (json.length > 4096) throw new Error(`${mode.id}: a row's data is over 4096 bytes`);
+            return json ? `${r.weight}\t${json}` : String(r.weight);
+        });
+        const table = `${game}-${mode.id}.tsv`;
+        writeFileSync(join(dir, table), lines.join('\n') + '\n');
+        manifest.modes.push({
+            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table,
+            bets: bets.map((b) => {
+                const tiers = new Map();
+                rows.forEach((r, i) => { const m = r.pay[b.id] || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
+                const { num, den, bp } = rtp(rows, b.id);
+                const hit = rows.reduce((s, r) => s + (r.pay[b.id] > 0 ? r.weight : 0n), 0n);
+                const max = Math.max(...tiers.keys());
+                report.push({ mode: mode.id, bet: b.id, rtp: bp, hit: bp4(hit * 10000n, den), max: max / 10000, rows: rows.length, exact: num % den === 0n });
+                return { id: b.id, ...(b.label ? { label: b.label } : {}), tiers: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) };
+            }),
+        });
+    }
+    writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest) + '\n');
+    for (const r of report) console.log(`${r.mode}/${r.bet}: RTP ${r.rtp} bp  hit ${r.hit} bp  max ${r.max}×  rows ${r.rows}`);
+    return report;
+}

package/engine-examples/keno/math-kit/package.json

@@ -0,0 +1,8 @@
+{
+    "name": "@housegames/engine-math",
+    "private": true,
+    "version": "0.1.0",
+    "type": "module",
+    "description": "The maths kit: outcomes as weighted rows, exact RTP, an exact fit to a target, the pack the engine verifies; a video slot model (reels, lines, wilds, scatters, free spins) and a tumble model (scatter pays, tumbles, multipliers).",
+    "exports": { "./pack.mjs": "./pack.mjs", "./slot.mjs": "./slot.mjs", "./tumble.mjs": "./tumble.mjs" }
+}

package/engine-examples/keno/math-kit/slot.mjs

@@ -0,0 +1,94 @@
+/**
+ * A video slot for the maths kit: reels, paylines, a wild, a scatter that
+ * starts free spins (with a multiplier, retriggers), and a win cap. It plays
+ * rounds with a seeded generator to make the table's rows ("books"): every
+ * row is a whole round, base spin and free spins, with what it pays. fit()
+ * then makes the table's RTP exact; the table is the game.
+ *
+ * Pays are in basis points of the total stake (10000 = 1×) for 3, 4, 5 of a
+ * kind on a line, left to right; scatters pay anywhere, times the stake.
+ *
+ * A row's data, for the bundle: { b: spin, f: [spin…], x: free multiplier }
+ * where a spin is [stop0…stopN, winBp, lineMask, scatterCount].
+ */
+export function slot(cfg) {
+    const { reels, freeReels = reels, rows, lines, pays, wild, scatter, maxWinBp } = cfg;
+    const n = reels.length;
+
+    const grid = (strips, stops) => stops.map((s, r) => Array.from({ length: rows }, (_, y) => strips[r][(s + y) % strips[r].length]));
+
+    // One spin's wins: each line pays its best run from the left (wilds stand in).
+    function evaluate(strips, stops) {
+        const g = grid(strips, stops);
+        let win = 0, mask = 0;
+        lines.forEach((line, li) => {
+            const cells = line.map((y, r) => g[r][y]);
+            const sym = cells.find((c) => c !== wild) ?? wild;
+            if (sym === scatter.symbol) return;
+            let count = 0;
+            while (count < n && (cells[count] === sym || cells[count] === wild)) count++;
+            const pay = (pays[sym] || {})[count] || 0;
+            // A run of wilds alone pays as wilds when that is more.
+            let wc = 0;
+            while (wc < n && cells[wc] === wild) wc++;
+            const best = Math.max(pay, (pays[wild] || {})[wc] || 0);
+            if (best > 0) { win += best; mask |= 1 << li; }
+        });
+        const scatters = g.flat().filter((c) => c === scatter.symbol).length;
+        win += (scatter.pays[scatters] || 0);
+        return { win, mask, scatters };
+    }
+
+    const spin = (strips, next) => strips.map((s) => next.int(s.length));
+
+    /** One whole round: the row's data and what it pays (bp of the stake).
+     * A bought round is the free spins alone, as three scatters start them. */
+    function round(next, buy = false) {
+        const stops = buy ? null : spin(reels, next);
+        const base = buy ? { win: 0, scatters: 3 } : evaluate(reels, stops);
+        const data = buy ? { buy: 1 } : { b: [...stops, base.win, base.mask, base.scatters] };
+        let total = base.win;
+        let left = scatter.spins[base.scatters] || 0;
+        if (left) {
+            data.f = [];
+            data.x = scatter.multiplier;
+            while (left > 0 && data.f.length < scatter.cap) {
+                left--;
+                const s = spin(freeReels, next);
+                const e = evaluate(freeReels, s);
+                data.f.push([...s, e.win * scatter.multiplier, e.mask, e.scatters]);
+                total += e.win * scatter.multiplier;
+                left += scatter.retrigger[e.scatters] || 0;
+            }
+        }
+        if (total > maxWinBp) { total = maxWinBp; data.cap = 1; }
+        return { data, pay: total };
+    }
+
+    return { evaluate, round, grid };
+}
+
+/**
+ * Plays `count` rounds (bought ones with `buy`) and keeps them as rows: every paying round, and up to
+ * `losing` different losing rounds that share the weight of every losing
+ * round played (so the rows keep the played RTP and hit rate before fit).
+ */
+export function books(game, next, count, losing = 4000, buy = false) {
+    const wins = new Map(), lose = new Map();
+    let lost = 0n;
+    for (let i = 0; i < count; i++) {
+        const { data, pay } = game.round(next, buy);
+        if (pay <= 0) {
+            lost++;
+            if (lose.size < losing) lose.set(JSON.stringify(data), { weight: 0n, data, pay: { spin: 0 } });
+            continue;
+        }
+        const key = JSON.stringify(data);
+        const r = wins.get(key);
+        if (r) r.weight += 1n;
+        else wins.set(key, { weight: 1n, data, pay: { spin: pay } });
+    }
+    const zeros = [...lose.values()];
+    zeros.forEach((r, i) => { r.weight = lost / BigInt(zeros.length) + (BigInt(i) < lost % BigInt(zeros.length) ? 1n : 0n); });
+    return [...zeros.filter((r) => r.weight > 0n), ...wins.values()];
+}

package/engine-examples/keno/math-kit/tumble.mjs

@@ -0,0 +1,94 @@
+/**
+ * A tumbling, scatter-pays slot for the maths kit: a cols × rows grid, every
+ * cell drawn by symbol weight; a symbol pays when enough of it is anywhere
+ * on the grid; winners vanish, the rest fall, new symbols drop in, until
+ * nothing pays. Scatters start free spins, where multiplier symbols land
+ * and multiply the spin's win. Like slot.mjs, it plays whole rounds into
+ * rows; fit() then makes the RTP exact.
+ *
+ * Symbols are single characters. Pays are basis points of the stake by
+ * count: { A: [[8, 2000], [10, 5000], [12, 10000]] } pays the highest band
+ * the count reaches.
+ *
+ * A row's data, for the page:
+ *   { b: spin, f: [spin…] }   spin = [grid, [tumble…], multipliers?]
+ *   grid    the first grid, column by column, top to bottom ("ABCDE…")
+ *   tumble  [winners, winBp, fill0, fill1, …]: the symbols that paid, what
+ *           they paid, and per column the new symbols that drop in (top first)
+ *   multipliers  free spins only: the values of the multiplier symbols on the
+ *           last grid, summed onto the spin's win when it won
+ */
+export function tumble(cfg) {
+    const { cols, rows, weights, freeWeights = weights, pays, scatter, bomb, maxWinBp } = cfg;
+    const pick = (w, next) => {
+        const total = w.reduce((s, [, n]) => s + n, 0);
+        let x = next() * total;
+        for (const [s, n] of w) if ((x -= n) < 0) return s;
+        return w[w.length - 1][0];
+    };
+    const table = (o) => Object.entries(o);
+    const base = table(weights), free = table(freeWeights);
+    const counts = Object.keys(scatter.spins).map(Number), least = Math.min(...counts), most = Math.max(...counts);
+
+    // One spin: the grid, its tumbles, and (free spins) its multipliers.
+    function spin(next, inFree) {
+        const w = inFree ? free : base;
+        const draw = () => {
+            const s = pick(w, next);
+            return s === bomb?.symbol && !inFree ? pick(base.filter(([x]) => x !== bomb.symbol), next) : s;
+        };
+        let grid = Array.from({ length: cols }, () => Array.from({ length: rows }, draw));
+        const first = grid.map((c) => c.join('')).join('');
+        const tumbles = [];
+        let win = 0;
+        for (;;) {
+            const counts = {};
+            for (const c of grid) for (const s of c) counts[s] = (counts[s] || 0) + 1;
+            let paid = '', bp = 0;
+            for (const [s, bands] of Object.entries(pays)) {
+                const band = bands.filter(([n]) => counts[s] >= n).at(-1);
+                if (band) { paid += s; bp += band[1]; }
+            }
+            if (!paid) break;
+            win += bp;
+            const fills = grid.map((c) => {
+                const kept = c.filter((s) => !paid.includes(s));
+                const add = Array.from({ length: rows - kept.length }, draw);
+                c.splice(0, rows, ...add, ...kept); // new symbols on top
+                return add.join('');
+            });
+            tumbles.push([paid, bp, ...fills]);
+        }
+        const out = [first, tumbles];
+        const scatters = grid.flat().filter((s) => s === scatter.symbol).length; // on the last grid
+        let total = win;
+        if (inFree && bomb) {
+            const bombs = grid.flat().filter((s) => s === bomb.symbol).map(() => pick(bomb.values, next));
+            if (bombs.length) out.push(bombs);
+            if (win && bombs.length) total = win * bombs.reduce((a, b) => a + b, 0);
+        }
+        return { out, total, scatters };
+    }
+
+    /** One whole round: the row's data and what it pays (bp of the stake). */
+    function round(next) {
+        const b = spin(next, false);
+        const data = { b: b.out };
+        let total = b.total + (scatter.pays[Math.min(b.scatters, most)] || 0);
+        let left = b.scatters >= least ? scatter.spins[Math.min(b.scatters, most)] : 0;
+        if (left) {
+            data.f = [];
+            while (left > 0 && data.f.length < scatter.cap) {
+                left--;
+                const f = spin(next, true);
+                data.f.push(f.out);
+                total += f.total;
+                if (f.scatters >= scatter.retrigger.count) left += scatter.retrigger.spins;
+            }
+        }
+        if (total > maxWinBp) { total = maxWinBp; data.cap = 1; }
+        return { data, pay: total };
+    }
+
+    return { round };
+}

package/engine-examples/lines/AGENTS.md

@@ -0,0 +1,3 @@
+# For agents
+
+This is a House Engine game (Housebets). Read the guide first: `engine_guide` (MCP) or `engine-sdk/GUIDE.md`. Then `hbengine verify`, `hbengine dev`, `hbengine upload` (or the `engine_*` tools). The math is `math/`, the frontend `bundle/`; never compute money or outcomes in the frontend.

package/engine-examples/lines/README.md

@@ -0,0 +1,20 @@
+# Lines — a video slot from the maths kit
+
+Five reels, three rows, ten lines, a wild, a scatter that pays anywhere and
+starts 10–15 free spins with wins ×2 (three scatters in free spins add five
+more, up to 60), a 5,000× cap. RTP exactly 96.00%, hit rate 31.4%.
+**Bonus buy**: a second mode plays the free spins alone; its price is what
+they return on average (27 spins, the stake is the price), balanced to
+exactly 96.00%.
+
+| path | what |
+|---|---|
+| `math/gen.mjs` | the model (reels, lines, pays, free spins), 400,000 rounds played into rows, `fit` to exactly 96%; 50,000 bought rounds `balance`d to 96%; also writes `bundle/model.json` |
+| `math-kit/` | the maths kit (`packages/engine-math`): `pack.mjs` (rows, exact RTP, fit, the pack), `slot.mjs` (reels, lines, wilds, scatters, free spins) |
+| `bundle/game.js` | spins to the drawn stops, draws the paying lines, plays the free spins the row holds |
+
+A row is a whole round: `{"b":[5 stops, win, lineMask, scatters], "f":[[…] per free spin], "x":2}`.
+The engine pays the row's tier; the page shows what the row says.
+
+    node math/gen.mjs my-slot        # change the model, play it into a new table
+    npx hbengine verify .            # the engine's exact RTP, hit rate, max win

package/engine-examples/lines/bundle/assets.json

@@ -0,0 +1 @@
+{"groups": {"boot": {"files": ["index.html", "game.js", "game.css", "model.json", "i18n.json"]}}}

package/engine-examples/lines/bundle/game.css

@@ -0,0 +1,16 @@
+body { margin: 0; background: #08141a; }
+.slot { container-type: inline-size; display: flex; flex-direction: column; align-items: center; gap: 14px; width: 100%; padding: 16px 12px; box-sizing: border-box; }
+.banner, .win { height: 24px; font: 700 16px/24px 'Red Hat Display', 'Figtree', system-ui, sans-serif; color: #F9F9FB; font-variant-numeric: tabular-nums; }
+.banner { color: #8F96A8; font-size: 14px; }
+.win { color: #FDDC73; }
+.board { --c: min(112px, (100cqi - 64px) / 5); position: relative; padding: 8px; border-radius: 14px; background: #061218; box-shadow: inset 0 0 0 1px #0D2A38; }
+.reels { display: grid; grid-template-columns: repeat(5, var(--c)); gap: 6px; }
+.reel { position: relative; height: calc(var(--c) * 3); overflow: hidden; border-radius: 8px; background: #0b1f28; }
+.strip { position: absolute; inset: 0 0 auto 0; will-change: transform; }
+.cell { height: var(--c); display: grid; place-items: center; }
+.cell svg { width: 62%; height: 62%; }
+.cell b { font: 800 calc(var(--c) * .42)/1 'Red Hat Display', 'Figtree', system-ui, sans-serif; color: #8F96A8; }
+.cell.hit { background: rgba(253, 220, 115, .1); }
+.lines { position: absolute; inset: 8px; width: calc(100% - 16px); height: calc(100% - 16px); pointer-events: none; overflow: visible; }
+.lines polyline { fill: none; stroke: #FDDC73; stroke-width: 3; stroke-linejoin: round; opacity: .85; }
+@media (prefers-reduced-motion: reduce) { .strip { transition: none !important; } }

package/engine-examples/lines/bundle/game.js

@@ -0,0 +1,125 @@
+// Lines: five reels, ten lines, free spins. The panel is the engine's
+// (engine-sdk/ui.js); this file spins the reels to the stops the server drew
+// and draws what paid. Every amount comes from the row (math/gen.mjs wrote
+// model.json from the same model that made the rows).
+import { mount } from '/engine-sdk/ui.js';
+
+const model = await (await fetch('./model.json')).json();
+// The page's own words in the player's language (bundle/i18n.json, English otherwise).
+const I18N = await (await fetch('./i18n.json')).json();
+let W = I18N.en;
+const t = (k, v = {}) => W[k].replace(/\{(\w+)\}/g, (_, x) => v[x]);
+const reelsEl = document.getElementById('reels'), linesEl = document.getElementById('lines');
+const banner = document.getElementById('banner'), winEl = document.getElementById('win');
+const N = model.reels.length, ROWS = model.rows;
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const SVG = (inner, fill, stroke) => `<svg viewBox="0 0 40 40"><g fill="${fill}" stroke="${stroke}" stroke-width="2" stroke-linejoin="round">${inner}</g></svg>`;
+// Deep fills, bright strokes (big shapes stay desaturated).
+const ART = {
+    seven: SVG('<path d="M9 8h22l-11 25h-6l9-19H9z"/>', '#7e1f3a', '#ff6b81'),
+    gem: SVG('<path d="M8 15l6-7h12l6 7-12 17z"/>', '#0d5f6e', '#5cf6f6'),
+    star: SVG('<path d="M20 5l4.5 9.5 10.5 1.5-7.6 7.3 1.8 10.4L20 28.8l-9.2 4.9 1.8-10.4L5 16l10.5-1.5z"/>', '#7d5410', '#FDDC73'),
+    bell: SVG('<path d="M20 6c6 0 10 5 10 11v7l4 5H6l4-5v-7c0-6 4-11 10-11zM16 31h8a4 4 0 01-8 0z"/>', '#2b2f6b', '#a6adff'),
+    W: '<b class="wild">W</b>', S: SVG('<circle cx="20" cy="20" r="13"/><circle cx="20" cy="20" r="6" fill="none"/>', '#1f5a3a', '#7cf2b0'),
+};
+const art = (s) => ART[s] || `<b>${s}</b>`;
+
+let c = 96; // the cell size: CSS sets it from the zone's width, read before each spin
+const reels = [];
+for (let r = 0; r < N; r++) {
+    const reel = document.createElement('div');
+    reel.className = 'reel';
+    const strip = document.createElement('div');
+    strip.className = 'strip';
+    reel.append(strip);
+    reelsEl.append(reel);
+    reels.push(strip);
+}
+const cellsOf = (strip) => [...strip.children];
+
+function show(strips, stops) { // the resting grid
+    reels.forEach((strip, r) => {
+        strip.style.transition = 'none';
+        strip.style.transform = 'translateY(0)';
+        strip.innerHTML = Array.from({ length: ROWS }, (_, y) => `<div class="cell">${art(strips[r][(stops[r] + y) % strips[r].length])}</div>`).join('');
+    });
+}
+
+// Spins every reel to its stops: a strip of passing symbols ending on the result.
+function spin(strips, stops, ms) {
+    return Promise.all(reels.map((strip, r) => {
+        const s = strips[r], pass = 8 + r * 3, from = cellsOf(strip).slice(0, ROWS).map((e) => e.innerHTML);
+        const passing = Array.from({ length: pass }, (_, i) => art(s[(stops[r] + ROWS + i * 7) % s.length]));
+        const end = Array.from({ length: ROWS }, (_, y) => art(s[(stops[r] + y) % s.length]));
+        strip.innerHTML = [...end, ...passing, ...from].map((h) => `<div class="cell">${h}</div>`).join('');
+        strip.style.transition = 'none';
+        strip.style.transform = `translateY(-${(pass + ROWS) * c}px)`;
+        void strip.offsetWidth;
+        strip.style.transition = `transform ${ms + r * 120}ms cubic-bezier(.15, .7, .2, 1)`;
+        strip.style.transform = 'translateY(0)';
+        return wait(ms + r * 120);
+    })).then(() => reels.forEach((strip) => cellsOf(strip).slice(ROWS).forEach((e) => e.remove())));
+}
+
+function paint([mask, scatters], strips, stops) {
+    linesEl.innerHTML = '';
+    const step = c + 6;
+    model.lines.forEach((line, i) => {
+        if (!(mask & (1 << i))) return;
+        const pts = line.map((y, r) => `${r * step + c / 2},${y * c + c / 2}`).join(' ');
+        linesEl.insertAdjacentHTML('beforeend', `<polyline points="${pts}"/>`);
+        line.forEach((y, r) => cellsOf(reels[r])[y]?.classList.add('hit'));
+    });
+    if (scatters >= 3) reels.forEach((strip, r) => cellsOf(strip).forEach((e, y) => { if (strips[r][(stops[r] + y) % strips[r].length] === model.scatter.symbol) e.classList.add('hit'); }));
+}
+
+const times = (bp) => (bp / 10000).toFixed(2) + '×';
+
+const measure = () => { c = reelsEl.firstElementChild.getBoundingClientRect().height / ROWS || c; };
+show(model.reels, [0, 0, 0, 0, 0]);
+
+const game = await mount(document.getElementById('game'), {
+    labels: Object.fromEntries(Object.entries(I18N).map(([l, w]) => [l, w.modes])),
+    async reveal(round) {
+        const d = round.data[0];
+        // A bought round is the free spins alone; its stake was their price.
+        const [stops, [win, mask, scatters]] = d.buy ? [null, [0, 0, 0]] : [d.b.slice(0, N), d.b.slice(N)];
+        linesEl.innerHTML = ''; winEl.textContent = ''; banner.textContent = '';
+        measure();
+        if (stops) {
+            await spin(model.reels, stops, 700);
+            paint([mask, scatters], model.reels, stops);
+        }
+        let total = win;
+        // Shown per stake: a bought round's stake was the price of model.price spins.
+        const per = (bp) => times(Math.floor(bp / (d.buy ? model.price : 1)));
+        if (win) winEl.textContent = times(total);
+        if (d.f) {
+            // A tap on the reels skips to the end of the free spins.
+            let skip = false;
+            const tap = () => { skip = true; };
+            reelsEl.addEventListener('pointerdown', tap);
+            await wait(700);
+            for (let i = 0; i < d.f.length; i++) {
+                const s = d.f[i];
+                total += s[N];
+                if (skip && i < d.f.length - 1) continue;
+                banner.textContent = `${t('freeSpins', { i: i + 1, n: d.f.length })} · ${t('winsTimes', { x: d.x })}` + (skip ? '' : ` · ${t('tapToSkip')}`);
+                linesEl.innerHTML = '';
+                await spin(model.freeReels, s.slice(0, N), skip ? 120 : 380);
+                paint(s.slice(N + 1), model.freeReels, s.slice(0, N));
+                if (total) winEl.textContent = per(total);
+                if (!skip) await wait(s[N] ? 420 : 120);
+            }
+            reelsEl.removeEventListener('pointerdown', tap);
+            if (stops) show(model.reels, stops);
+            banner.textContent = t('freePaid', { w: per(total - win) });
+        }
+        if (d.cap) winEl.textContent = `${per(total)} · ${t('maxWin')}`;
+    },
+});
+W = I18N[(game.engine.config.locale || 'en').slice(0, 2)] || I18N.en;
+let hinted = false;
+document.getElementById('game').addEventListener('select', (e) => {
+    if (e.detail.mode === 'buy') { banner.textContent = t('buyHint', { n: model.price }); hinted = true; } else if (hinted) { banner.textContent = ''; hinted = false; }
+});

package/engine-examples/lines/bundle/hbtest.json

@@ -0,0 +1,4 @@
+{
+  "stake": { "page": "index.html", "selector": "hb-game hb-bet-amount input", "value": "1.00" },
+  "bet": { "page": "index.html", "selector": "hb-game [data-main]" }
+}