hbengine 0.2.3 → 0.4.0

package/engine-conformance/analyse.mjs

@@ -158,13 +158,15 @@ export const RULES = Object.freeze({
     minified: { level: 'fail', text: 'minified or obfuscated (nine in ten names are one or two letters) with no source map in the bundle: a reviewer cannot read it; ship readable code, or the .map with sourcesContent beside it' },
     obfuscated: { level: 'fail', text: 'obfuscated: names or strings written to defeat a reader' },
     'wasm-source': { level: 'fail', text: 'WebAssembly: a module the analyser cannot read; only a known library\'s released module (by content hash) run by that library\'s own code is accepted (GUIDE §3.6)' },
-    analyser: { level: 'fail', text: 'the code could not be analysed in time' },
+    'unknown-library': { level: 'warn', text: 'under vendor/ but not a known library release (its bytes\' SHA-256): it is read as the game\'s own code, minified or not; ship the library\'s released file unchanged (GUIDE §3.5), or its source map' },
+    'unreleased-library': { level: 'warn', text: 'claims a known library by its name and banner, but its bytes are none of that library\'s releases we know: it is read as the game\'s own code; ship the released file unchanged, or ask Housebets to add this release' },
+    analyser: { level: 'fail', text: 'the code could not be analysed in time. Large minified code does this: ship it readable, or with its source map (sourcesContent included), and libraries as their released files under vendor/ (GUIDE §3.5, §3.7); what could be told without the full analysis is listed beside this' },
     clock: { level: 'warn', text: 'reads the date or time (Date, Temporal, performance.timeOrigin): review checks nothing depends on the day' },
     timezone: { level: 'warn', text: 'reads the time zone, or formats by locale (getTimezoneOffset, Intl.DateTimeFormat, toLocale…)' },
     locale: { level: 'warn', text: "reads the language outside the SDK (navigator.language, Intl): engine.config.locale is the player's language" },
     fingerprint: { level: 'warn', text: "reads the browser's identity (userAgent, platform, hardware, screen depth, webdriver): review checks no behaviour depends on it" },
     timer: { level: 'warn', text: 'a timer past 60 s, or with a delay computed at run time: review checks what fires then' },
-    'local-storage': { level: 'warn', text: 'keeps state on the device (localStorage, sessionStorage, indexedDB, cookies): per device only, and a counter kept there can fire after N rounds; anything a player keeps across devices goes through engine.state' },
+    'local-storage': { level: 'warn', text: 'keeps state on the device (localStorage, sessionStorage, indexedDB, cookies): per device only and empty again in every new version (each version has its own address), and a counter kept there can fire after N rounds; progress a player keeps goes in engine.progress (GUIDE §3.1)' },
     'input-element': { level: 'warn', text: 'creates a text field or a form: a game takes nothing typed but the stake; review checks it asks for no login, password or key' },
     'element-name': { level: 'warn', text: 'creates an element named at run time (createElement(name)): could be a script or a field; review checks the names' },
     'markup-parts': { level: 'warn', text: 'builds markup with a computed part where a tag or an attribute name goes, or as an unquoted attribute value (`<${tag}>`, `<img ${attrs}>`, `src=${u}`), or puts a value into the page one of whose alternatives is not written down (`ART[s] || s`): a part carrying an attribute would run; review checks what each part can be' },
@@ -563,7 +565,8 @@ class Analysis {
         this.resolving = new Set(); // nodes being resolved (a cycle adds nothing)
         this.fallback = new Set(); // nodes re-entered in a call's scope, being read in their own scope (resolveStatic)
         this.spreading = new Set(); // object literals being read for their members (a spread of itself adds nothing)
-        this.cache = new Map(); // node → leaves, for a node read in its own scope
+        this.cache = new Map(); // node → leaves, for a node read in its own scope (and readsOf's answers, under readKeys)
+        this.readKeys = new WeakMap(); // read node → its key in cache for readsOf
         this.mentioned = new Map(); // node → Map(position → the global its syntax (and its names' values) mentions, or null) (globalMentioned)
         this.bases = new Map(); // a member chain's node → the name it stands on (baseName, kept: a chain as long as a file is asked at every link)
         this.globalNames = new Map(); // node → what globalName answered, in its own scope, once the scopes are built
@@ -1260,15 +1263,66 @@ class Analysis {
         const b = scope.resolve(x.name);
         const global = b ? (b.alias === 'name' && (GLOBAL_OBJECTS.has(b.name) || HOST_NAMES.has(b.name)) ? b.name : null) : x.name;
         if (!b && !global) return [];
+        // The element writes are indexed by what they write to, once per file and
+        // once for the pool (a large library asks for one list thousands of times;
+        // reading every write each time cost PixiJS's bundle most of its deadline).
+        // A name that is both a binding and a global (an alias of the window) reads
+        // the written lists in their order, as one pass over every write would.
+        // (Kept on the write index it is read from: every reset of that, a pass or the wiring, starts a new one.)
+        const byKey = this.writeIndex(a);
+        const local = this.elementWriteIndex(byKey, () => byKey.get('*') ?? []);
+        const pooled = global != null && a.pool?.writes ? this.elementWriteIndex(a.pool, () => a.pool.writes.get('*') ?? []) : null;
         const out = [];
-        for (const w of [...(this.writeIndex(a).get('*') ?? []), ...(global != null ? a.pool?.writes?.get('*') ?? [] : [])]) {
-            const wt = this.targetOf(w);
-            if (!wt || wt.path.length || wt.key != null) continue;
-            if ((b && wt.binding === b) || (global != null && wt.global === global)) out.push({ value: w.value, scope: w.scope });
-            if (out.length > EXACT_VALUES * 4) break;
-        }
+        const take = (index) => {
+            const ws = b && global != null ? index.all.filter((w) => w.target.binding === b || w.target.global === global)
+                : b ? index.byBinding.get(b) ?? [] : index.byGlobal.get(global) ?? [];
+            for (const w of ws) {
+                if (out.length > EXACT_VALUES * 4) return;
+                out.push({ value: w.value, scope: w.scope });
+            }
+        };
+        take(local);
+        if (pooled && out.length <= EXACT_VALUES * 4) take(pooled);
         return out;
     }
+    // The writes of an element (no path, no key) out of a list of '*' writes, by
+    // their binding and by their global, in the list's order: kept on its owner.
+    elementWriteIndex(owner, list) {
+        if (!owner.elementWriteLists) {
+            const all = [], byBinding = new Map(), byGlobal = new Map();
+            for (const w of list()) {
+                const wt = this.targetOf(w);
+                if (!wt || wt.path.length || wt.key != null) continue;
+                all.push(w);
+                if (wt.binding) { if (!byBinding.has(wt.binding)) byBinding.set(wt.binding, []); byBinding.get(wt.binding).push(w); }
+                if (wt.global != null) { if (!byGlobal.has(wt.global)) byGlobal.set(wt.global, []); byGlobal.get(wt.global).push(w); }
+            }
+            owner.elementWriteLists = { all, byBinding, byGlobal };
+        }
+        return owner.elementWriteLists;
+    }
+    // The writes of one key out of a writes-by-key map that a read on `global`
+    // (a global name, or null) can reach: those on that global, or those on no
+    // global, in the list's order. Split once per key, kept on the map (a new
+    // map, after a pass or the wiring, splits afresh). A write the analyser
+    // cannot place reaches nothing and is left out.
+    keyWrites(byKey, key, global) {
+        const list = byKey.get(key);
+        if (!list) return [];
+        if (!byKey.split) byKey.split = new Map();
+        let s = byKey.split.get(key);
+        if (!s) {
+            s = { byGlobal: new Map(), none: [] };
+            for (const w of list) {
+                const wt = this.targetOf(w);
+                if (!wt) continue;
+                if (wt.global == null) s.none.push(w);
+                else { if (!s.byGlobal.has(wt.global)) s.byGlobal.set(wt.global, []); s.byGlobal.get(wt.global).push(w); }
+            }
+            byKey.split.set(key, s);
+        }
+        return global != null ? s.byGlobal.get(global) ?? [] : s.none;
+    }
     // This file's writes by key ('*' for a computed key or an element), indexed once.
     writeIndex(a) {
         if (!a.writesByKey) { a.writesByKey = new Map(); for (const w of a.writes) { if (!this.targetOf(w)) continue; const key = w.key ?? '*'; if (!a.writesByKey.has(key)) a.writesByKey.set(key, []); a.writesByKey.get(key).push(w); } }
@@ -1326,7 +1380,26 @@ class Analysis {
     // found at run time by a lookup the analyser could not place), with the
     // same key. A write on a fresh object of the code (new Image(), a literal)
     // reaches only reads through the same name.
+    //
+    // Kept per read node, as the resolver keeps its answers (resolve), and in
+    // its cache, so every clearing of that (a pass, the wiring, the escapes)
+    // clears these too: for a read in its own file and in a scope that is not
+    // a call's, once the names are bound (not in pass 1), and only when the
+    // budget lasted the whole reading. A large bundle asks for the same read
+    // millions of times.
     readsOf(n, scope) {
+        const cacheable = !scope.dynamic && !this.pass1 && (scope.analysis ?? this) === this;
+        let key;
+        if (cacheable) {
+            key = this.readKeys.get(n);
+            if (!key) this.readKeys.set(n, (key = { readsOf: n }));
+            if (this.cache.has(key)) return this.cache.get(key);
+        }
+        const out = this.readsOfIn(n, scope);
+        if (cacheable && this.steps > 0) this.cache.set(key, out);
+        return out;
+    }
+    readsOfIn(n, scope) {
         const read = this.target(n, scope);
         if (!read) return [];
         const a = scope.analysis ?? this;
@@ -1335,13 +1408,17 @@ class Analysis {
         // written key reads every write of that key, in this file and (the pool) the others.
         this.writeIndex(a);
         // (A push, unshift or add writes an element, which an element read (no key) reads; a property read never does.)
-        if (read.key != null) candidates.push(...(a.writesByKey.get(read.key) ?? []));
+        // A read on a global name reaches only writes on that global, and any other read only writes on no global
+        // (reaches): the key's writes are taken already split so, in their order.
+        if (read.key != null) candidates.push(...this.keyWrites(a.writesByKey, read.key, read.global));
         else if (read.binding) for (const list of a.writesByKey.values()) for (const w of list) if (w.target.binding === read.binding) candidates.push(w);
-        if (a.pool?.writes && read.key != null) candidates.push(...(a.pool.writes.get(read.key) ?? []));
+        if (a.pool?.writes && read.key != null) candidates.push(...this.keyWrites(a.pool.writes, read.key, read.global));
         const out = [];
         const seen = new Set();
-        // (The read's place is found once; a write's once ever, kept on the write.)
-        read.elements = candidates.length ? this.staticElements(read) : null;
+        // (The read's place is found once, when the key has any write at all, split or not, as the budget it spends
+        // was spent before the split; a write's once ever, kept on the write.)
+        const any = read.key != null ? (a.writesByKey.get(read.key)?.length || a.pool?.writes?.get(read.key)?.length) : candidates.length;
+        read.elements = any ? this.staticElements(read) : null;
         for (const w of candidates) {
             if (seen.has(w) || out.length > EXACT_VALUES * 4) continue;
             seen.add(w);
@@ -2022,6 +2099,14 @@ class Analysis {
     // a walk each. A node in a call's scope (a parameter bound at one call
     // site) is read each time, in that scope. A cycle adds nothing; an answer
     // that leaned on a node still being read is not kept.
+    //
+    // A reading cut at MENTION_STEPS answers 'window', the cautious answer, and
+    // that answer is kept for the node and position it was asked of: asked
+    // again, the same reading would spend the same steps to be cut the same
+    // way. (A large library asks one such question thousands of times:
+    // PixiJS spent 100,000 steps on each of 3,971 of its first 4,000, past any
+    // deadline.) Kept cut answers are never narrower than a full reading, so
+    // nothing the analyser refuses is let through.
     globalMentioned(n, scope, pos = null) {
         n = unchain(n);
         if (!n || !scope) return 'window';
@@ -2031,7 +2116,16 @@ class Analysis {
         // (The evaluation asks the resolver nothing, so it never re-enters; were it to, what it has not read may be anything.)
         if (this.mentioning) return 'window';
         this.mentioning = true;
-        try { return this.globalMentionedIn(n, scope, pos); } finally { this.mentioning = false; }
+        this.mentionCut = false;
+        try {
+            const out = this.globalMentionedIn(n, scope, pos);
+            if (this.mentionCut && !scope.dynamic) {
+                let m = this.mentioned.get(n);
+                if (!m) this.mentioned.set(n, (m = new Map()));
+                m.set(key, 'window');
+            }
+            return out;
+        } finally { this.mentioning = false; }
     }
     globalMentionedIn(root, rootScope, rootPos) {
         const memoGet = (x, k) => this.mentioned.get(x)?.get(k);
@@ -2056,7 +2150,7 @@ class Analysis {
         };
         while (stack.length) {
             // (Not read to the end: what is left may mention anything. Nothing is kept of it.)
-            if (steps++ > MENTION_STEPS) return 'window';
+            if (steps++ > MENTION_STEPS) { this.mentionCut = true; return 'window'; }
             const f = stack[stack.length - 1];
             if (f.i < 0) {
                 const x = f.node;
@@ -3170,6 +3264,9 @@ class Analysis {
                 if (!FUNCTIONS.has(l.node.type)) continue;
                 const owner = l.scope.analysis ?? this;
                 if (!owner.scopes.has(l.node)) continue;
+                // (A recognised library's call of the game's function, a callback it was handed: called from code
+                // the game's analysis does not read into (bundle.mjs, the pool), so its parameters are unknown.)
+                if (this.library && !owner.library) { owner.escaped.add(l.node); continue; }
                 let s = owner.sites.get(l.node);
                 if (!s) owner.sites.set(l.node, (s = []));
                 if (s.some((x) => x.args === node.arguments)) continue;
@@ -4191,6 +4288,49 @@ export function matchSelector(elements, selector) {
     return out;
 }
 
+// A script's names counted the way the analyser counts them (the names it
+// declares: variables, parameters, functions, classes, catch bindings), from
+// its syntax alone, without reading what anything is. For the scan's report
+// when the analysis did not finish in time: whether a file is minified can be
+// told in milliseconds, and a studio told only "it took too long" cannot act.
+export function censusSource(source) {
+    const out = { parsed: false, names: 0, short: 0, minified: false, sourceMappingURL: sourceMappingURL(source) };
+    let ast = null;
+    for (const sourceType of ['module', 'script']) {
+        try { ast = parse(source, { ecmaVersion: 'latest', allowHashBang: true, sourceType }); break; } catch { /* the other */ }
+    }
+    if (!ast) return out;
+    out.parsed = true;
+    const count = (name) => { out.names++; if (name.length <= 2) out.short++; };
+    const pattern = (p) => {
+        if (!p) return;
+        switch (p.type) {
+            case 'Identifier': count(p.name); return;
+            case 'ObjectPattern': for (const q of p.properties) pattern(q.type === 'RestElement' ? q.argument : q.value); return;
+            case 'ArrayPattern': for (const q of p.elements) pattern(q); return;
+            case 'RestElement': pattern(p.argument); return;
+            case 'AssignmentPattern': pattern(p.left); return;
+        }
+    };
+    const stack = [ast];
+    while (stack.length) {
+        const n = stack.pop();
+        if (!n || typeof n.type !== 'string') continue;
+        if (n.type === 'VariableDeclarator') pattern(n.id);
+        else if (n.type === 'FunctionDeclaration' || n.type === 'FunctionExpression' || n.type === 'ArrowFunctionExpression') { if (n.id) count(n.id.name); for (const q of n.params) pattern(q); }
+        else if ((n.type === 'ClassDeclaration' || n.type === 'ClassExpression') && n.id) count(n.id.name);
+        else if (n.type === 'CatchClause') pattern(n.param);
+        for (const k in n) {
+            const v = n[k];
+            if (k === 'loc' || k === 'start' || k === 'end') continue;
+            if (Array.isArray(v)) { for (const c of v) if (c && typeof c.type === 'string') stack.push(c); }
+            else if (v && typeof v.type === 'string') stack.push(v);
+        }
+    }
+    out.minified = out.names >= LIMITS.minNames && out.short / out.names >= LIMITS.shortNameRatio;
+    return out;
+}
+
 // The //# sourceMappingURL=… comment, read from the tail of the file where
 // bundlers write it.
 function sourceMappingURL(source) {

package/engine-conformance/bundle.mjs

@@ -64,7 +64,7 @@ export function analyseBundle(files, { read = (abs) => readFileSync(abs, 'utf8')
         for (const { target, kind: k } of scriptLoads(path, text)) if (k === 'script') classic.add(target);
     }
 
-    for (const { path, abs, kind } of files) {
+    for (const { path, abs, kind, library = null } of files) {
         const result = { path, findings: [], units: [], wasm: [], sourceMappingURL: null };
         out.push(result);
         try {
@@ -101,6 +101,7 @@ export function analyseBundle(files, { read = (abs) => readFileSync(abs, 'utf8')
             } else {
                 const unit = prepareSource(text, { mode: classic.has(path) ? 'script' : 'auto' });
                 unit.path = path;
+                if (library) unit.analysis.library = library;
                 units.push({ path, unit, page: null, result, inline: false });
                 modules.set(path, unit);
             }
@@ -118,10 +119,13 @@ export function analyseBundle(files, { read = (abs) => readFileSync(abs, 'utf8')
         return jsons.get(path);
     };
     // What a module specifier names, from a file: the module (its analysis), a JSON file ({ json }), or null.
-    const moduleFrom = (fromPath) => (specifier) => {
+    // (A recognised library imported by the game's own code is a module the analyser does not read into: null, as
+    // for the pool below.)
+    const moduleFrom = (fromPath, fromLibrary) => (specifier) => {
         const target = resolveSpecifier(fromPath, specifier);
         if (target == null) return null;
         const m = modules.get(target);
+        if (m && m.analysis.library && !fromLibrary) return null;
         if (m) return m.ast ? { analysis: m.analysis } : null;
         if (/\.json$/i.test(target)) { const v = jsonOf(target); return v === undefined ? null : { json: v }; }
         return null;
@@ -130,10 +134,23 @@ export function analyseBundle(files, { read = (abs) => readFileSync(abs, 'utf8')
     // The pool: every classic script's root bindings and every module's globals
     // (window.X = …) by name; every write by its key; every element the code
     // writes as markup.
+    //
+    // A recognised library (scan.mjs: a known name with its release banner,
+    // under vendor/) is read on its own, as if it were the bundle's only file,
+    // and adds nothing to the pool: what it sets on the global object and what
+    // it writes are not followed into its code from the game's files, so a
+    // value the game takes from it (new PIXI.Container(), gsap.to(…)) is a
+    // global no file sets, as if the library were not in the bundle. Followed,
+    // a library of a few megabytes is read for every value the game hands it,
+    // past any deadline (Pump Junkie: GSAP 1 s on its own, 59 s wired to PixiJS
+    // and the game), and a reading cut short in it is the global object
+    // whenever the library mentions one (everywhere): the game's own code
+    // refused for the library's. What the library itself would be refused for
+    // is named for review (scan.mjs) and blocked at run time by the policy.
     const pool = { globals: new Map(), writes: new Map(), written: [], writtenOverflow: false };
     for (const { unit } of units) {
         const a = unit.analysis;
-        if (!unit.ast) continue;
+        if (!unit.ast || a.library) continue;
         for (const [name, binding] of a.root.names) {
             if (a.mode !== 'script' && !binding.global) continue;
             if (!binding.alias && !binding.hidden) continue;
@@ -150,6 +167,7 @@ export function analyseBundle(files, { read = (abs) => readFileSync(abs, 'utf8')
         else pool.written.push(...a.written);
     }
     if (pool.written.length > 100000) { pool.written = []; pool.writtenOverflow = true; }
+    const alone = { globals: new Map(), writes: new Map(), written: [], writtenOverflow: false }; // (a recognised library's: nothing of another file)
 
     // The pages a script runs in: its own for an inline script; those whose
     // <script src> names it for a file; those of its importers for a module
@@ -173,8 +191,8 @@ export function analyseBundle(files, { read = (abs) => readFileSync(abs, 'utf8')
     }
     for (const { path, unit } of units) {
         const a = unit.analysis;
-        a.modules = moduleFrom(path);
-        a.pool = pool;
+        a.modules = moduleFrom(path, !!a.library);
+        a.pool = a.library ? alone : pool;
         a.pages = [...(pagesOf.get(unit) ?? [])];
     }
 

package/engine-conformance/census-worker.mjs

@@ -0,0 +1,9 @@
+// The quick census of every script (analyse.mjs censusSource), for scan.mjs
+// when the full analysis ran out of time: whether each file is minified, and
+// its source map comment, from its syntax alone. On a worker thread with its
+// own deadline, like the analysis.
+import { readFileSync } from 'node:fs';
+import { parentPort, workerData } from 'node:worker_threads';
+import { censusSource } from './analyse.mjs';
+
+parentPort.postMessage(workerData.files.map((f) => ({ path: f.path, ...censusSource(readFileSync(f.abs, 'utf8')) })));

package/engine-conformance/chrome-flags.mjs

@@ -0,0 +1,19 @@
+// The run's --enable-features switch. Chrome keeps only the last
+// --enable-features it is given, and Playwright gives its own
+// (CDPScreenshotNewSurface, its screenshot path, unless
+// PLAYWRIGHT_LEGACY_SCREENSHOT is set), so the run's names Playwright's
+// features too: chrome-flags.test.mjs reads Playwright's list, so an upgrade
+// that adds one fails the test instead of being dropped here.
+//
+// OriginKeyedProcessesByDefault: a process per origin. In the job the shell
+// and the game are both 127.0.0.1 (two ports, one site), so Chrome gave them
+// one renderer and one main thread, and a game drawing in software kept the
+// shell from answering the clock's jumps in 60 s (ticket #43, Abyssal Glow
+// v17–v32: "2 of 3 window(s) answered", the shell the one missing). On the
+// site they are two sites, two processes; this is that.
+export const PLAYWRIGHT_FEATURES = ['CDPScreenshotNewSurface'];
+export const RUN_FEATURES = ['OriginKeyedProcessesByDefault'];
+
+export function enableFeatures(env = process.env) {
+    return '--enable-features=' + [...(env.PLAYWRIGHT_LEGACY_SCREENSHOT ? [] : PLAYWRIGHT_FEATURES), ...RUN_FEATURES].join(',');
+}

package/engine-conformance/diagnostic-text.mjs

@@ -0,0 +1,19 @@
+// An error the run reports, as the studio reads it: whole up to 2,000
+// characters (a stack, a source map's position, a studio's own diagnostic);
+// longer, its start and its end with the cut marked, never just its first
+// 160 characters. A page that throws in a loop keeps its first 100.
+export const DIAGNOSTIC_TEXT_LIMIT = 2000;
+export const DIAGNOSTIC_ENTRY_LIMIT = 100;
+
+const CUT = ' … [truncated] … ';
+
+export function diagnosticText(value) {
+    const text = String(value);
+    if (text.length <= DIAGNOSTIC_TEXT_LIMIT) return text;
+    const head = Math.floor((DIAGNOSTIC_TEXT_LIMIT - CUT.length) / 2);
+    return text.slice(0, head) + CUT + text.slice(-(DIAGNOSTIC_TEXT_LIMIT - CUT.length - head));
+}
+
+export function appendDiagnostic(list, value) {
+    if (list.length < DIAGNOSTIC_ENTRY_LIMIT) list.push(diagnosticText(value));
+}

package/engine-conformance/diagnostics.mjs

@@ -0,0 +1,52 @@
+import { loadavg, cpus, freemem, totalmem } from 'node:os';
+import { writeFileSync } from 'node:fs';
+
+// Failure evidence must not hold up the next check when a renderer has stopped
+// answering. Keep the report bounded and never copy launch URLs or messages.
+async function bounded(work, fallback, ms = 1500) {
+    let timer;
+    try { return await Promise.race([Promise.resolve().then(work), new Promise((r) => { timer = setTimeout(() => r(fallback), ms); })]); }
+    catch { return fallback; }
+    finally { clearTimeout(timer); }
+}
+
+export function runnerInfo(browser) {
+    return { node: process.version, browser: browser.version(), platform: process.platform,
+        cpuCount: cpus().length, loadAverage: loadavg(), freeMemoryBytes: freemem(), totalMemoryBytes: totalmem() };
+}
+
+export function consoleRecorder(page, token) {
+    const lines = [];
+    page.on('console', (m) => {
+        if (lines.length >= 100) return;
+        const text = m.text();
+        if (text.startsWith(token + ':')) return;
+        // Console text is studio evidence, never instructions. Strip common
+        // credential forms and URL queries before storing it in the report.
+        lines.push({ level: m.type(), text: text.replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
+            .replace(/(https?:\/\/[^\s?#]+)[?#][^\s]*/g, '$1[redacted]').slice(0, 500) });
+    });
+    return lines;
+}
+
+export function handshakeProbe(scope, say) {
+    scope.addEventListener('message', event => {
+        const d = event.data;
+        if (event.isTrusted && event.source === scope.parent && d?.hb === 1 && d.kind === 'evt' && d.type === 'init') say('received');
+    });
+}
+
+export async function failureEvidence(page, { console: lines, runner, started, shot, shotFile, log, initReceived = false }) {
+    const messages = await bounded(async () => (await log()).slice(-30).map((m) => ({
+        at: m.at, type: typeof m.d?.type === 'string' ? m.d.type.slice(0, 80) : '',
+        message: typeof m.d?.message === 'string' ? m.d.message.slice(0, 80) : ''
+    })), []);
+    const frames = page.frames().slice(0, 20).map((f) => {
+        try { const u = new URL(f.url()); return u.origin + u.pathname; } catch { return 'unknown'; }
+    });
+    const png = await bounded(() => page.screenshot({ timeout: 1200 }), null);
+    let saved = false;
+    if (png) { try { writeFileSync(shotFile, png); saved = true; } catch { /* report the missing image */ } }
+    return { elapsedMs: Date.now() - started, runner, console: lines.slice(), frames, initReceived,
+        messages, screenshot: saved ? shot : null, screenshotUnavailable: !saved };
+}

package/engine-conformance/focus.mjs

@@ -0,0 +1,42 @@
+// Record script focus before the first genuine input. Browser activation can
+// already be live in an automated browser, so it is not proof of a first tap.
+// This probe only observes calls; the shell's activation/focus gate is unchanged.
+// Each way a page moves the focus by itself is said once, by its name:
+// focus() on an HTML or SVG element or the window, a dialog's show() or
+// showModal(), and an autofocus element put on the page.
+export function focusProbe(scope, say) {
+    let touched = false;
+    let moving = 0;
+    const said = new Set();
+    const early = (what) => { if (!touched && !said.has(what)) { said.add(what); say(what); } };
+    const input = (event) => { if (event.isTrusted) touched = true; };
+    for (const type of ['pointerdown', 'touchstart', 'keydown']) scope.addEventListener(type, input, { capture: true, passive: true });
+    const wrap = (object, key, what) => {
+        if (!object || typeof object[key] !== 'function') return;
+        object[key] = new Proxy(object[key], { apply(target, self, args) {
+            early(what);
+            moving++;
+            try { return Reflect.apply(target, self, args); } finally { moving--; }
+        } });
+    };
+    wrap(scope.HTMLElement?.prototype, 'focus', 'focus()');
+    wrap(scope.SVGElement?.prototype, 'focus', 'focus()');
+    wrap(scope, 'focus', 'focus()');
+    wrap(scope.HTMLDialogElement?.prototype, 'show', 'show()');
+    wrap(scope.HTMLDialogElement?.prototype, 'showModal', 'showModal()');
+    // Native autofocus (including popovers and closed shadow roots) emits a
+    // composed focusin event. Observe the actual focus change rather than
+    // guessing from DOM insertion: detached/hidden autofocus cannot fail.
+    scope.addEventListener('focusin', event => {
+        if (event.isTrusted && !moving) early('autofocus');
+    }, { capture: true });
+
+}
+
+// focusVerdict: a fail naming each way the focus moved before the first tap;
+// else a pass.
+export function focusVerdict(said) {
+    const early = [...new Set(said)];
+    if (early.length) return { ok: false, detail: `script focus before the first tap (${early.join(', ')}): move the focus only after the player's first tap; a startup focus can block genuine bets for 5 seconds (GUIDE §3.1)` };
+    return { ok: true, detail: 'no script focus before the first tap' };
+}

package/engine-conformance/hints.mjs

@@ -0,0 +1,86 @@
+/**
+ * What a failing check means for the studio and what to change: one table, the
+ * same words wherever a check is read (the report the dashboard shows, `hbengine
+ * test`, the agent's engine_test, the mail). Written from the failures studios
+ * actually hit (every upload's report, 29 Oct 2026): a game that never said it
+ * was ready (Octo Feast, 10 versions), a frame it did not fit (Wolf Street, 6),
+ * a bet the run could not press (5), the clock jump no frame answered (Octo
+ * Feast, Wolf Street, Aurora Wheel, Pump Junkie: 7), a stand-in Bet control
+ * (Pump Junkie, 3). Plain rules on the check's own text, nothing guessed: a
+ * failure the table does not know gets no hint rather than a wrong one.
+ */
+
+const TEST = 'Run `hbengine test` to see it on your machine before you upload.';
+const TRAVEL = 'Run `hbengine test --time-travel` to see it on your machine before you upload; an upload plays each variant at a clock of its own, which `--clock <variant>=<instant>,<zone>,<language>` (as the line above names it) replays.';
+
+const HINTS = [
+    {
+        rule: 'boot', match: /no ready within/,
+        hint: 'The game did not call engine.ready() in time. The check runs on a slow machine on purpose (Chrome draws on the CPU, with few animation frames), as a player on an old phone would. Call ready() as soon as connect() resolves and the first screen can show, not from requestAnimationFrame; load only what the first screen needs before it (assets.json, the boot group) and the rest after. GUIDE §6, §3.2. ' + TEST,
+    },
+    {
+        rule: 'bet', match: /no hbtest\.json/,
+        hint: 'The run needs to know your Bet button: use the SDK\'s <hb-bet> (/engine-sdk/bet.js) and the run finds it by itself, or add bundle/hbtest.json with the selector of your Bet button and the stake to type first. GUIDE §3.4. ' + TEST,
+    },
+    {
+        rule: 'bet', match: /hbtest\.json step failed/,
+        hint: 'The run could not press what hbtest.json names. The selector must match one element that is shown, enabled, inside the frame and not moving when a round can start, at desktop and phone size (a button that animates forever is never still enough to press). The SDK\'s <hb-bet> (/engine-sdk/bet.js) is built to be pressed. GUIDE §3.4. ' + TEST,
+    },
+    {
+        rule: 'idle', match: /./,
+        hint: 'A bet happened while nobody touched the game. A bet is always the player\'s act: no auto-start, no bet from a timer, no demo round through engine.play. GUIDE §3.1. ' + TEST,
+    },
+    {
+        rule: 'fit', match: /does not fit/,
+        hint: 'The game must fit the frame it is given: 1194×720, 1194×582, 364×720 and 364×440 (a phone between the site\'s header and bottom nav), then fullscreen 1920×1080 and 390×844. Size the page to the frame (no fixed widths, no page scroll), keep every control inside it and no text cut at its edge. GUIDE §3.3. ' + TEST,
+    },
+    {
+        rule: 'draws', match: /./,
+        hint: 'After the round the play area showed almost nothing. If the game draws with WebGL, it must also start without a GPU (the run draws on the CPU, SwiftShader): check the canvas is created and drawn when no hardware acceleration is there. GUIDE §6. ' + TEST,
+    },
+    {
+        rule: 'errors', match: /./,
+        hint: 'A page threw an error nobody caught; the line above names it. Fix it where it is thrown: in production it would stop the game for a player. ' + TEST,
+    },
+    {
+        rule: 'network', match: /./,
+        hint: 'Everything the game loads ships in its bundle and comes from its own origin: no outside fonts, CDNs, analytics or frames; workers and styles from your own files. GUIDE §3.7. ' + TEST,
+    },
+    {
+        rule: 'currency', match: /./,
+        hint: 'Money is shown and sent only through the SDK (engine.money, engine.play with the amount the player typed): never compute a stake, convert a currency or format money yourself. GUIDE §4. ' + TEST,
+    },
+    {
+        // Only when it is the variant's one failure: a failure of the game's own beside it is the game's to fix.
+        rule: 'time-travel', match: /the run broke: the checker's own page did not keep up with the clock[^;]*$/,
+        hint: 'Most likely on our side, not your game\'s: every window of your game moved its clock in time, and one of the checker\'s own pages (the site or the House Engine shell) did not. Upload the same build again; if it keeps happening, reply on your support ticket with the version number. If your game draws a lot every frame, drawing less often (/engine-sdk/frames.js) also leaves the checker more room.',
+    },
+    {
+        rule: 'time-travel', match: /fake clock did not move/,
+        hint: 'After the first round the check moves the game\'s clock 30 minutes ahead, as when a player leaves the tab and comes back, and every frame of the game must keep up within a minute. Yours did not: when time jumps, every timer that came due fires at once, and if each of them does heavy work (a full render, rebuilding a scene, catching up an interval tick by tick) the page freezes. Let timers only mark that a frame is needed and draw at most once per requestAnimationFrame; after a big gap in time, run an interval\'s work once, not once per missed tick; never reload the page on a jump. /engine-sdk/frames.js does both for you: frame(draw) and every(ms, fn). GUIDE §6 (time-travel). ' + TRAVEL,
+    },
+    {
+        rule: 'time-travel', match: /bet control (is|was not found|was hidden|is disabled)/,
+        hint: 'The Bet control the check found is not the button a player presses: it must be the real control, at least 32×32 px, at least half opaque, visible, enabled and inside the frame. An invisible stand-in that forwards clicks to a canvas fails. The SDK\'s <hb-bet> (/engine-sdk/bet.js) always passes this: use it for your Bet. GUIDE §3.4, §6. ' + TRAVEL,
+    },
+    {
+        // A variant that did not boot and says nothing else (no error, no request,
+        // no broken run): what the shell's own 10 s start-up limit leaves when the
+        // check machine's engine is slow, as the last variants of a matrix were
+        // (studio tickets, Nov 2026) while they booted at once on the studio's machine.
+        rule: 'time-travel', match: /^(?!.*the run broke).*: the game did not boot$/,
+        hint: 'At another date, time zone or language the game did not start, and it threw no error. That can be your code, or the check machine: the shell gives the engine 10 seconds to open a session and shows its own "The game could not start" screen past that, and on a busy check machine a variant late in the matrix can take that long. First play that variant on your machine (`hbengine test --time-travel`, its clock replayed with `--clock` as below). If it boots there in a few seconds and only variants near the end of the list failed, it was most likely the machine: upload again. If it does not boot there, look for code that reads the date, the zone or the language at start and stops before engine.ready() without an error (a date parsed by hand, a calendar or seasonal theme, a translation that is missing). GUIDE §5, §6. ' + TRAVEL,
+    },
+    {
+        rule: 'time-travel', match: /did not boot|round did not end/,
+        hint: 'At another date, time zone or language the game did not start or did not finish a round. Look for code that reads the date, the zone or the language at start (a date parsed by hand, a calendar or seasonal theme, a translation that is missing): the line above names the variant. GUIDE §5, §6. ' + TRAVEL,
+    },
+];
+
+/** The hint for a failing check ({ rule, detail }), or '' when the table has none. */
+export function hintFor(check) {
+    if (!check || check.ok || check.status === 'skipped') return '';
+    const detail = String(check.detail || '');
+    for (const h of HINTS) if (h.rule === check.rule && h.match.test(detail)) return h.hint;
+    return '';
+}