hbengine 0.2.3

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

@@ -0,0 +1,681 @@
+/**
+ * The sandbox-only test controls. boot.js imports this module only after the
+ * round server reports env === 'sandbox', so the casino never creates this UI.
+ * Maths and money still come from the shell's existing owners; this module only
+ * presents controls and sends their domain inputs to those owners.
+ */
+import { rowLabel, times } from './fair.js';
+import { loadPack } from './engine-v1.js';
+import { applicableScenarios, createScenarioContext, createScenarioRunner, SCENARIO_TIMEOUT } from './sandbox-scenarios.js';
+
+function text(tag, value) {
+    const element = document.createElement(tag);
+    element.textContent = value;
+    return element;
+}
+
+function labelOf(value, fallback) {
+    return value && typeof value.label === 'string' && value.label ? value.label : fallback;
+}
+
+function rangesContain(ranges, index) {
+    return ranges.some((range) => Array.isArray(range) && index >= range[0] && index <= range[1]);
+}
+
+function firstRowInRange(ranges, rows) {
+    for (const range of Array.isArray(ranges) ? ranges : []) {
+        if (!Array.isArray(range) || !Number.isInteger(range[0])) continue;
+        if (range[0] >= 0 && range[0] < rows.length) return range[0];
+    }
+    return null;
+}
+
+function firstBustRow(ranges, rows) {
+    for (let index = 0; index < rows.length; index += 1) {
+        if (!rangesContain(ranges, index)) return index;
+    }
+    return null;
+}
+
+function uniqueLabel(label, used) {
+    if (!used.has(label)) {
+        used.add(label);
+        return label;
+    }
+    let suffix = 2;
+    let candidate = `${label} · ${suffix}`;
+    while (used.has(candidate)) {
+        suffix += 1;
+        candidate = `${label} · ${suffix}`;
+    }
+    used.add(candidate);
+    return candidate;
+}
+
+function subjectLabel(mode, bet, modes, bets) {
+    const parts = [];
+    if (modes > 1) parts.push(labelOf(mode, mode.id));
+    if (bets > 1) parts.push(labelOf(bet, bet.id));
+    return parts.join(' · ');
+}
+
+function entryLabel(mode, bet, modes, bets, suffix) {
+    const subject = subjectLabel(mode, bet, modes, bets);
+    return subject ? `${subject} · ${suffix}` : suffix;
+}
+
+/** Returns the forceable rows represented by a parsed maths pack. */
+export function tierEntries(pack) {
+    const modes = Array.isArray(pack?.manifest?.modes) ? pack.manifest.modes : [];
+    const entries = [];
+    const used = new Set();
+    for (const mode of modes) {
+        const bets = Array.isArray(mode.bets) ? mode.bets : [];
+        for (const bet of bets) {
+            if (mode.kind === 'table') {
+                const seen = new Set();
+                const tiers = Array.isArray(bet.tiers) ? bet.tiers : [];
+                for (const tier of tiers) {
+                    if (!Number.isSafeInteger(tier.multBp) || seen.has(tier.multBp)) continue;
+                    const rowIndex = firstRowInRange(tier.outcomes, pack.tables[mode.table]?.rows || []);
+                    if (rowIndex === null) continue;
+                    seen.add(tier.multBp);
+                    const suffix = times(tier.multBp);
+                    entries.push({
+                        indices: [rowIndex],
+                        mode: mode.id,
+                        bet: bet.id,
+                        modeLabel: labelOf(mode, mode.id),
+                        betLabel: labelOf(bet, bet.id),
+                        autoAdvance: false,
+                        multiplier: tier.multBp,
+                        subject: subjectLabel(mode, bet, modes.length, bets.length),
+                        label: uniqueLabel(entryLabel(mode, bet, modes.length, bets.length, suffix), used),
+                        detail: rowLabel(pack, { table: mode.table, index: rowIndex }),
+                    });
+                }
+                continue;
+            }
+            if (mode.kind !== 'ladder') continue;
+            const steps = Array.isArray(mode.steps) ? mode.steps : [];
+            const survive = [];
+            let canSurvive = true;
+            for (let step = 0; step < steps.length; step += 1) {
+                const table = pack.tables[steps[step].table];
+                const row = firstRowInRange([bet.survive?.[step]], table?.rows || []);
+                if (row === null) canSurvive = false;
+                survive.push(row);
+            }
+            if (canSurvive && survive.length === steps.length && survive.length > 0) {
+                entries.push({
+                    indices: survive,
+                    mode: mode.id,
+                    bet: bet.id,
+                    modeLabel: labelOf(mode, mode.id),
+                    betLabel: labelOf(bet, bet.id),
+                    autoAdvance: mode.autoAdvance === true,
+                    multiplier: null,
+                    subject: subjectLabel(mode, bet, modes.length, bets.length),
+                    label: uniqueLabel(entryLabel(mode, bet, modes.length, bets.length, 'Survive every step'), used),
+                    detail: survive.map((row, step) => rowLabel(pack, { table: steps[step].table, index: row })).join(' · '),
+                });
+            }
+            const firstTable = pack.tables[steps[0]?.table];
+            const firstRanges = bet.survive?.[0] || [];
+            const bust = firstBustRow(firstRanges, firstTable?.rows || []);
+            const bustIndices = [bust];
+            for (let step = 1; bust !== null && step < steps.length; step += 1) {
+                const table = pack.tables[steps[step].table];
+                if (!table?.rows?.length) bustIndices.length = 0;
+                else bustIndices.push(0);
+            }
+            if (bust !== null && bustIndices.length === steps.length) {
+                entries.push({
+                    indices: bustIndices,
+                    mode: mode.id,
+                    bet: bet.id,
+                    modeLabel: labelOf(mode, mode.id),
+                    betLabel: labelOf(bet, bet.id),
+                    autoAdvance: mode.autoAdvance === true,
+                    multiplier: null,
+                    subject: subjectLabel(mode, bet, modes.length, bets.length),
+                    label: uniqueLabel(entryLabel(mode, bet, modes.length, bets.length, 'Bust at step 1'), used),
+                    detail: bustIndices.map((row, step) => rowLabel(pack, { table: steps[step].table, index: row })).join(' · '),
+                });
+            }
+        }
+    }
+    return entries;
+}
+
+/** Returns no controls when the document is not the requested committed pack. */
+export function entriesForVersion(pack, version) {
+    if (!pack || pack.recomputed !== version) return [];
+    const entries = tierEntries(pack);
+    const used = new Set(entries.map((entry) => entry.label));
+    const modes = Array.isArray(pack.manifest?.modes) ? pack.manifest.modes : [];
+    for (const mode of modes) {
+        if (mode.kind !== 'table') continue;
+        const rows = pack.tables?.[mode.table]?.rows || [];
+        for (const bet of Array.isArray(mode.bets) ? mode.bets : []) {
+            const covered = (Array.isArray(bet.tiers) ? bet.tiers : []).flatMap((tier) => Array.isArray(tier.outcomes) ? tier.outcomes : []);
+            const losing = firstBustRow(covered, rows);
+            if (losing === null) continue;
+            const subject = subjectLabel(mode, bet, modes.length, mode.bets.length);
+            entries.push({
+                indices: [losing],
+                mode: mode.id,
+                bet: bet.id,
+                modeLabel: labelOf(mode, mode.id),
+                betLabel: labelOf(bet, bet.id),
+                autoAdvance: false,
+                multiplier: 0,
+                loss: true,
+                subject,
+                label: uniqueLabel(entryLabel(mode, bet, modes.length, mode.bets.length, 'Losing row'), used),
+                detail: rowLabel(pack, { table: mode.table, index: losing }),
+            });
+        }
+    }
+    return entries;
+}
+
+/** Converts a displayed amount to the server's plain decimal wallet string. */
+export function balanceValue(value, money) {
+    if (!/^\d+(\.\d+)?$/.test(value)) return null;
+    const display = money.parse(value);
+    const amount = display;
+    if (!Number.isFinite(amount) || amount < 0 || amount > 1e9) return null;
+    const decimals = Math.min(8, Number.isInteger(money.walletDecimals) ? money.walletDecimals : 8);
+    const decimal = amount.toFixed(decimals).replace(/(\.\d*?)0+$/, '$1').replace(/\.$/, '');
+    if (!/^\d{1,10}(\.\d{1,8})?$/.test(decimal)) return null;
+    return { amount, decimal };
+}
+
+function addTierButtons(box, entries, rgs, status, register) {
+    for (const tier of entries) {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'sandbox-test-tier';
+        button.textContent = tier.label;
+        button.title = tier.detail;
+        button.addEventListener('click', async () => {
+            button.disabled = true;
+            try {
+                const result = await rgs.force(tier.indices, tier.mode);
+                const label = tier.multiplier === null ? tier.label : times(tier.multiplier);
+                const subject = tier.subject ? `Next ${tier.subject} round: ` : 'Next round forced: ';
+                status.textContent = result.ok ? subject + label : (result.error?.message || 'The next round was refused.');
+            } finally {
+                button.disabled = runActive;
+            }
+        });
+        box.append(button);
+        register?.(button);
+    }
+}
+
+/** Creates the panel over the game frame for a sandbox session. */
+export function createSandboxPanel({ rgs, router, faults, api, slug, mathHash, frame, money, refresh }) {
+    if (typeof document === 'undefined' || !rgs || !router || !faults) return null;
+    const stage = document.getElementById('stage');
+    if (!stage) return null;
+
+    const root = document.createElement('div');
+    root.className = 'sandbox-test';
+    const toggle = document.createElement('button');
+    toggle.type = 'button';
+    toggle.className = 'sandbox-test-toggle';
+    toggle.textContent = 'Test';
+    toggle.setAttribute('aria-expanded', 'false');
+    toggle.setAttribute('aria-controls', 'sandbox-test-panel');
+    const panel = document.createElement('section');
+    panel.id = 'sandbox-test-panel';
+    panel.className = 'sandbox-test-panel';
+    panel.hidden = true;
+    panel.setAttribute('aria-label', 'Sandbox test controls');
+    const status = text('p', '');
+    status.className = 'sandbox-test-status';
+    status.setAttribute('role', 'status');
+    status.setAttribute('aria-live', 'polite');
+    const instruction = text('p', '');
+    instruction.className = 'sandbox-test-instruction';
+    instruction.hidden = true;
+    instruction.setAttribute('role', 'status');
+    const observations = [];
+    const maxObservations = 64;
+    const waiters = new Set();
+    let observationSequence = 0;
+    let scenarioStartSequence = 0;
+    let scenarioStartAt = 0;
+    if (typeof router.observe === 'function') router.observe((observation) => {
+        const observed = { ...observation, observedAt: Date.now(), observationSequence: ++observationSequence };
+        if (!runActive) return;
+        observations.push(observed);
+        if (observations.length > maxObservations) observations.splice(0, observations.length - maxObservations);
+        for (const waiter of [...waiters]) {
+            if (waiter.skip) continue;
+            let matched = false;
+            try {
+                matched = observed.observationSequence > waiter.startSequence && observed.observedAt >= waiter.startAt && waiter.predicate(observed);
+            } catch {
+                matched = false;
+            }
+            if (matched) {
+                waiters.delete(waiter);
+                clearTimeout(waiter.timer);
+                const index = observations.indexOf(observed);
+                if (index >= 0) observations.splice(index, 1);
+                waiter.resolve(observed);
+            }
+        }
+    });
+    const waitFor = (predicate, ms = 90_000, registerCancel) => {
+        const startSequence = scenarioStartSequence;
+        const startAt = scenarioStartAt;
+        for (let index = 0; index < observations.length; index += 1) {
+            const observation = observations[index];
+            let matched = false;
+            try {
+                matched = observation.observationSequence > startSequence && observation.observedAt >= startAt && predicate(observation);
+            } catch {
+                matched = false;
+            }
+            if (matched) {
+                observations.splice(index, 1);
+                return Promise.resolve(observation);
+            }
+        }
+        return new Promise((resolve) => {
+            const waiter = {
+                predicate,
+                resolve,
+                skip: false,
+                startSequence,
+                startAt,
+                timer: setTimeout(() => {
+                    waiters.delete(waiter);
+                    resolve(SCENARIO_TIMEOUT);
+                }, ms),
+            };
+            registerCancel?.(() => {
+                waiters.delete(waiter);
+                clearTimeout(waiter.timer);
+                waiter.skip = true;
+                resolve(null);
+            });
+            waiters.add(waiter);
+        });
+    };
+    let loaded = false;
+    toggle.addEventListener('click', () => {
+        panel.hidden = !panel.hidden;
+        toggle.setAttribute('aria-expanded', String(!panel.hidden));
+        if (!panel.hidden && !loaded) {
+            loaded = true;
+            loadPack(api, slug, mathHash).then((pack) => {
+                if (pack.recomputed !== mathHash) {
+                    status.textContent = 'The maths pack does not match this version.';
+                    return;
+                }
+                scenarioEntries = entriesForVersion(pack, mathHash);
+                addTierButtons(tierBox, scenarioEntries, rgs, status, (button) => manualControls.push(button));
+                addScenarioControls(scenariosBox);
+            }, (error) => {
+                status.textContent = error.message || 'Maths could not be loaded.';
+            });
+        }
+        if (!panel.hidden) panel.querySelector('button, input')?.focus();
+    });
+    root.append(toggle, panel);
+    stage.append(root);
+
+    panel.append(text('h2', 'Sandbox tests'), instruction);
+    const rounds = document.createElement('div');
+    rounds.className = 'sandbox-test-section';
+    rounds.append(text('h3', 'Next round'));
+    const tierBox = document.createElement('div');
+    tierBox.className = 'sandbox-test-tiers';
+    rounds.append(tierBox);
+    panel.append(rounds);
+    const scenariosSection = document.createElement('div');
+    scenariosSection.className = 'sandbox-test-section sandbox-test-scenarios-section';
+    scenariosSection.append(text('h3', 'Scenarios'));
+    const scenariosBox = document.createElement('div');
+    scenariosBox.className = 'sandbox-test-scenarios';
+    const runAll = document.createElement('button');
+    runAll.type = 'button';
+    runAll.textContent = 'Run all';
+    const skip = document.createElement('button');
+    skip.type = 'button';
+    skip.textContent = 'Skip';
+    skip.hidden = true;
+    const stop = document.createElement('button');
+    stop.type = 'button';
+    stop.textContent = 'Stop';
+    stop.hidden = true;
+    const summary = document.createElement('ul');
+    summary.className = 'sandbox-test-summary';
+    scenariosSection.append(scenariosBox, runAll, skip, stop, summary);
+    panel.append(scenariosSection);
+    let scenarioEntries = [];
+    let scenarioButtons = [];
+    const manualControls = [];
+    let runActive = false;
+    let activeRunner = null;
+    const setRunningControls = (disabled) => {
+        for (const control of [...manualControls, ...scenarioButtons]) control.disabled = disabled;
+        runAll.disabled = disabled || scenarioButtons.length === 0;
+    };
+    let summaryItems = [];
+    let verdictResolve = null;
+    const renderSummary = (items) => {
+        summary.replaceChildren();
+        for (const { scenario, outcome } of items) {
+            const line = document.createElement('li');
+            const label = outcome.status === 'expected'
+                ? 'as expected'
+                : outcome.status === 'needs-verdict'
+                    ? `needs verdict (${outcome.detail})`
+                    : outcome.status === 'skipped'
+                        ? 'skipped'
+                        : outcome.status === 'stopped'
+                            ? 'stopped'
+                            : `different (${outcome.detail})`;
+            const warnings = outcome.warnings?.length ? ` · warnings: ${outcome.warnings.join('; ')}` : '';
+            line.textContent = `${scenario.title}: ${label}${outcome.verdict ? ` · ${outcome.verdict}` : ''}${warnings}`;
+            if (outcome.status === 'needs-verdict' && !outcome.verdict) {
+                const right = document.createElement('button');
+                right.type = 'button';
+                right.textContent = 'Looks right';
+                const wrong = document.createElement('button');
+                wrong.type = 'button';
+                wrong.textContent = 'Looks wrong';
+                const skipVerdict = document.createElement('button');
+                skipVerdict.type = 'button';
+                skipVerdict.textContent = 'Skip verdict';
+                right.addEventListener('click', () => finishReview('looks right'));
+                wrong.addEventListener('click', () => finishReview('looks wrong'));
+                skipVerdict.addEventListener('click', () => finishReview('skip verdict'));
+                line.append(' ', right, ' ', wrong, ' ', skipVerdict);
+            }
+            summary.append(line);
+        }
+    };
+    const scenarioContext = () => createScenarioContext({
+        entries: scenarioEntries,
+        limits: router.init?.()?.limits || {},
+        walletDecimals: money.walletDecimals,
+        setBalance: (value) => setWalletBalance(Number(value)),
+        force: (indices, mode) => rgs.force(indices, mode),
+        clearForce: () => rgs.clearForce(),
+        armFault: (kind, options = {}) => faults.arm(kind, options),
+        clearFaults: () => faults.clear(),
+        reload: async () => {
+            const result = await refresh();
+            if (result.ok) frame.src = frame.src;
+            return result;
+        },
+        currentBalance: async () => {
+            const response = await rgs.balance();
+            const value = response?.ok && typeof response.body?.balance === 'number' ? response.body.balance : undefined;
+            return value;
+        },
+        startingBalance: typeof router.init?.()?.balance === 'number' ? router.init().balance : undefined,
+        say: (message) => { status.textContent = message; if (runActive) { instruction.hidden = false; instruction.textContent = message; } },
+        waitFor: (predicate, ms, registerCancel) => waitFor(predicate, ms, registerCancel),
+        beforeScenario: () => {
+            observations.length = 0;
+            scenarioStartSequence = observationSequence;
+            scenarioStartAt = Date.now();
+        },
+        beforeWait: () => {
+            observations.length = 0;
+            scenarioStartSequence = observationSequence;
+            scenarioStartAt = Date.now();
+        },
+        awaitVerdict: (item) => new Promise((resolve) => {
+            reviewOutcome = item;
+            verdictResolve = resolve;
+            looksRight.hidden = false;
+            looksWrong.hidden = false;
+            renderSummary(summaryItems);
+        }),
+        cancelVerdict: () => {
+            verdictResolve?.();
+            verdictResolve = null;
+        },
+    });
+    let reviewOutcome = null;
+    let looksRight;
+    let looksWrong;
+    const finishReview = (verdict) => {
+        if (!reviewOutcome) return;
+        reviewOutcome.outcome.verdict = verdict;
+        reviewOutcome.outcome.status = verdict === 'looks right' ? 'expected' : verdict === 'looks wrong' ? 'different' : 'skipped';
+        looksRight.hidden = true;
+        looksWrong.hidden = true;
+        status.textContent = `${reviewOutcome.scenario.title}: ${reviewOutcome.outcome.detail} · ${verdict}`;
+        renderSummary(summaryItems);
+        verdictResolve?.();
+        verdictResolve = null;
+    };
+    const runOne = async (scenario) => {
+        runActive = true;
+        root.classList.add('sandbox-test-running');
+        setRunningControls(true);
+        skip.hidden = false;
+        stop.hidden = false;
+        looksRight?.setAttribute('hidden', '');
+        looksWrong?.setAttribute('hidden', '');
+        instruction.hidden = false;
+        instruction.textContent = scenario.todo;
+        status.textContent = `${scenario.title} — ${scenario.todo}`;
+        activeRunner = createScenarioRunner({ scenarios: [scenario], ctx: scenarioContext() });
+        try {
+            const outcome = await activeRunner.run(scenario);
+            const stoppedAt = activeRunner.wasStopped();
+            status.textContent = stoppedAt ? `Stopped at ${stoppedAt}/1` : `${scenario.title}: ${outcome.detail}`;
+            reviewOutcome = { scenario, outcome };
+            summaryItems = [reviewOutcome];
+            renderSummary(summaryItems);
+            looksRight.hidden = !outcome.review;
+            looksWrong.hidden = !outcome.review;
+            return outcome;
+        } finally {
+            runActive = false;
+            root.classList.remove('sandbox-test-running');
+            setRunningControls(false);
+            skip.hidden = true;
+            stop.hidden = true;
+            instruction.hidden = true;
+            activeRunner = null;
+        }
+    };
+    function addScenarioControls(box) {
+        box.replaceChildren();
+        scenarioButtons = [];
+        const ctx = scenarioContext();
+        const applicable = applicableScenarios(ctx);
+        const groups = new Map();
+        for (const scenario of applicable) {
+            if (!groups.has(scenario.group)) {
+                const group = document.createElement('div');
+                group.className = 'sandbox-test-scenario-group';
+                group.append(text('strong', scenario.group));
+                box.append(group);
+                groups.set(scenario.group, group);
+            }
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.textContent = scenario.title;
+            button.title = scenario.look;
+            button.addEventListener('click', () => { if (!runActive) runOne(scenario); });
+            groups.get(scenario.group).append(button);
+            scenarioButtons.push(button);
+        manualControls.push(button);
+        }
+        runAll.disabled = applicable.length === 0;
+        runAll.onclick = async () => {
+            if (runActive) return;
+            runActive = true;
+            root.classList.add('sandbox-test-running');
+            setRunningControls(true);
+            skip.hidden = false;
+            stop.hidden = false;
+            looksRight?.setAttribute('hidden', '');
+            looksWrong?.setAttribute('hidden', '');
+            summaryItems = [];
+            summary.replaceChildren();
+            activeRunner = createScenarioRunner({
+                scenarios: applicable,
+                ctx: scenarioContext(),
+                onScenario: (item) => {
+                    summaryItems.push({ scenario: item.scenario, outcome: item.outcome });
+                    renderSummary(summaryItems);
+                },
+            });
+            instruction.hidden = false;
+            try {
+                const results = await activeRunner.runAll();
+                renderSummary(results);
+                const stoppedAt = activeRunner.wasStopped();
+                const warning = results.at(-1)?.outcome?.warnings?.join('; ');
+                status.textContent = warning ? `Stopped at ${stoppedAt}/${applicable.length}: ${warning}` : stoppedAt ? `Stopped at ${stoppedAt}/${applicable.length}` : `Finished ${results.length} / ${applicable.length}`;
+            } finally {
+                runActive = false;
+                root.classList.remove('sandbox-test-running');
+                setRunningControls(false);
+                skip.hidden = true;
+                stop.hidden = true;
+                instruction.hidden = true;
+                activeRunner = null;
+            }
+        };
+    }
+    skip.addEventListener('click', () => activeRunner?.skip());
+    stop.addEventListener('click', () => activeRunner?.stop());
+    const balance = document.createElement('div');
+    balance.className = 'sandbox-test-section';
+    balance.append(text('h3', 'Balance'));
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.inputMode = 'decimal';
+    input.setAttribute('aria-label', 'Balance amount');
+    input.placeholder = money?.unit ? `Amount (${money.unit})` : 'Amount';
+    const set = document.createElement('button');
+    set.type = 'button';
+    set.textContent = 'Set';
+    const empty = document.createElement('button');
+    empty.type = 'button';
+    empty.textContent = 'Empty';
+    const setBalanceValue = async (value) => {
+        const parsed = balanceValue(value, money);
+        if (!parsed) {
+            status.textContent = /^\d+(\.\d+)?$/.test(value) && Number(value) > 1e9 ? 'At most 1,000,000,000' : 'Enter a valid non-negative amount.';
+            return;
+        }
+        set.disabled = true;
+        empty.disabled = true;
+        try {
+            const result = await rgs.sandboxBalance(parsed.decimal);
+            if (!result.ok) {
+                status.textContent = result.error?.message || 'Balance refused.';
+                return;
+            }
+            const balance = result.body && result.body.balance;
+            if (typeof balance !== 'number' || !Number.isFinite(balance) || balance < 0) {
+                status.textContent = 'Balance response was invalid.';
+                return;
+            }
+            router.balanceChanged(balance);
+            status.textContent = `Balance set: ${money.format(balance)}`;
+        } finally {
+            set.disabled = runActive;
+            empty.disabled = runActive;
+        }
+    };
+    const setWalletBalance = async (value) => {
+        if (!Number.isFinite(value) || value < 0) return { ok: false, error: { message: 'Balance is invalid.' } };
+        const decimals = Math.min(8, Number.isInteger(money?.walletDecimals) ? money.walletDecimals : 8);
+        const decimal = value.toFixed(decimals).replace(/(\.\d*?)0+$/, '$1').replace(/\.$/, '') || '0';
+        const result = await rgs.sandboxBalance(decimal);
+        if (result.ok) {
+            const balance = result.body && result.body.balance;
+            if (typeof balance === 'number' && Number.isFinite(balance) && balance >= 0) {
+                router.balanceChanged(balance);
+            }
+        }
+        return result;
+    };
+    set.addEventListener('click', () => setBalanceValue(input.value.trim()));
+    empty.addEventListener('click', () => {
+        input.value = '0';
+        setBalanceValue('0');
+    });
+    balance.append(input, set, empty);
+    manualControls.push(input, set, empty);
+    panel.append(balance);
+
+    const faultsSection = document.createElement('div');
+    faultsSection.className = 'sandbox-test-section';
+    faultsSection.append(text('h3', 'Faults'));
+    const showFaultState = () => {
+        const state = faults.state();
+        status.textContent = state ? `${state.kind} armed for ${state.times} call${state.times === 1 ? '' : 's'}` : 'No fault armed';
+    };
+    faults.onChange?.(showFaultState);
+    for (const kind of ['session', 'server', 'unavailable', 'timeout', 'slow']) {
+        const row = document.createElement('div');
+        row.className = 'sandbox-test-fault';
+        const name = text('span', kind);
+        const note = kind === 'session' ? text('small', 'the game is told its session expired; reopen from House Studio to play on') : null;
+        const one = document.createElement('button');
+        one.type = 'button';
+        one.textContent = 'Next call';
+        const three = document.createElement('button');
+        three.type = 'button';
+        three.textContent = 'Next 3 calls';
+        one.addEventListener('click', () => {
+            faults.arm(kind, { times: 1 });
+        });
+        three.addEventListener('click', () => {
+            faults.arm(kind, { times: 3 });
+        });
+        row.append(name);
+        if (note) row.append(note);
+        row.append(one, three);
+        faultsSection.append(row);
+        manualControls.push(one, three);
+    }
+    const clear = document.createElement('button');
+    clear.type = 'button';
+    clear.textContent = 'Clear';
+    clear.addEventListener('click', () => {
+        faults.clear();
+    });
+    faultsSection.append(clear);
+    manualControls.push(clear);
+    panel.append(faultsSection);
+
+    const reload = document.createElement('button');
+    reload.type = 'button';
+    reload.className = 'sandbox-test-reload';
+    reload.textContent = 'Reload game';
+    reload.addEventListener('click', async () => {
+        reload.disabled = true;
+        const result = await refresh();
+        reload.disabled = runActive;
+        if (result.ok) frame.src = frame.src;
+        else status.textContent = result.error?.message || 'Session refresh refused.';
+    });
+    manualControls.push(reload);
+    looksRight = document.createElement('button');
+    looksRight.type = 'button'; looksRight.textContent = 'Looks right'; looksRight.hidden = true;
+    looksWrong = document.createElement('button');
+    looksWrong.type = 'button'; looksWrong.textContent = 'Looks wrong'; looksWrong.hidden = true;
+    looksRight.addEventListener('click', () => finishReview('looks right'));
+    looksWrong.addEventListener('click', () => finishReview('looks wrong'));
+    panel.append(reload, looksRight, looksWrong, status);
+    return root;
+}