hbengine 0.2.3

package/engine-conformance/scan.mjs

@@ -0,0 +1,476 @@
+#!/usr/bin/env node
+/**
+ * The upload's static scan: what a studio bundle must be before anything
+ * runs it. The same code runs in `hbengine lint` on the studio's machine and
+ * in our upload pipeline, so a studio never learns at upload what it could
+ * not have learned locally.
+ *
+ *   node scan.mjs <bundle-dir> [--json]
+ *
+ * Every finding is { level: 'fail' | 'warn', rule, file?, detail }. Any fail
+ * rejects the upload, with the report sent back to the studio.
+ *
+ * The code is read by a parser (analyse.mjs, on a worker thread with a
+ * deadline), not matched by patterns: what a script reaches is decided from
+ * its syntax, with names resolved through scopes. Markup keeps a few regex
+ * rules (CSP, base, refresh, object/embed, srcdoc, outside URLs) that a tag
+ * walk serves as well as a parser would.
+ */
+import { closeSync, lstatSync, openSync, readdirSync, readFileSync, readSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { Worker } from 'node:worker_threads';
+import { join, relative, extname, posix } from 'node:path';
+import { checkAssetManifest } from '../engine-sdk/assets.js';
+import { RULES } from './analyse.mjs';
+
+// The WebAssembly modules accepted, by the SHA-256 of their bytes: files of
+// library releases as published (wasm-releases.json says how a row is added).
+// A module is a program the analyser cannot read; a name or a banner is not
+// a tie to anything, the bytes are.
+export const KNOWN_WASM = new Map(Object.entries(JSON.parse(readFileSync(new URL('./wasm-releases.json', import.meta.url), 'utf8')).modules));
+const WASM_MAGIC = Buffer.from([0x00, 0x61, 0x73, 0x6d]);
+
+// totalBytes is the figure a studio is told (SPEC §3, the FAQ): a game is at
+// most this big, and so is its upload on the wire (pipeline/sync/server.mjs
+// MAX_UPLOAD takes it from here; internal/archive MaxBytes is the same number
+// on the Go side, held to it by TestBoundsAgreeWithThePipeline).
+export const BUDGETS = Object.freeze({
+    totalBytes: 300 * 1024 * 1024,
+    files: 2500,
+    fileBytes: 8 * 1024 * 1024,
+    codeBytes: 4 * 1024 * 1024,
+    bootGzipBytes: 2 * 1024 * 1024,
+    bootJsGzipBytes: 250 * 1024,
+    groupGzipBytes: 25 * 1024 * 1024,
+});
+
+// Measuring a bundle's gzip sizes gets this long; a bundle within budget takes
+// seconds, and one that keeps a thread busy past this is refused as over budget.
+const GZIP_TIMEOUT = 120 * 1000;
+// Parsing, wiring and walking every script gets this long: Bad Cat (43 scripts,
+// 900 KB, 8 pages) takes about two seconds with every value followed across its
+// files, Kraken half a second. A bundle whose code is still being read at the
+// deadline is refused unread.
+const ANALYSE_TIMEOUT = 120 * 1000;
+
+const TEXT = new Set(['.html', '.htm', '.js', '.mjs', '.css', '.json', '.svg', '.xml', '.xhtml', '.xsl', '.xslt', '.txt']);
+// The languages the site ships (arbitrium-frontend apps/web/messages).
+const SITE_LOCALES = ['ar', 'da', 'de', 'en', 'es', 'fi', 'fr', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'pl', 'pt', 'ru', 'th', 'tr', 'vi', 'zh'];
+const CODE = new Set(['.html', '.htm', '.js', '.mjs']);
+// Text data files: what a game fetches and may put into its page is walked
+// for markup as the code's own strings are (a handler in a .json string). A
+// data file is any file that is UTF-8 text from its first byte to its last
+// and is not code or markup — .json, .txt, .csv, .atlas, a shader, a template
+// of any extension or none: the content decides, not the name (a name is not
+// trust). A binary file (an image, a sound, a font, a model) is not read; what
+// the code fetches as text is refused at the sink (hidden-markup). Source maps
+// are for the reviewer, never fetched by the page, and are not read as data.
+const REVIEW_ONLY = new Set(['.map']);
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+function isText(f) {
+    try { UTF8.decode(readFileSync(f.abs)); return true; } catch { return false; }
+}
+// Documents that run their <script> and handler attributes when the page frames
+// them (the bundle's policy allows frames of its own origin): the analyser
+// reads their markup as the browser renders it (entities expanded, namespace
+// prefixes dropped), and any script in them is refused (svg-script). A
+// stylesheet (.xsl) is read the same: a transform's output is a page too.
+const XML_PAGES = new Set(['.svg', '.xml', '.xhtml', '.xsl', '.xslt']);
+const MARKUP = new Set(['.html', '.htm', ...XML_PAGES]);
+// Attributes of markup whose value is a URL the browser never fetches: a
+// namespace name, a schema's location, an RDF subject or object (Inkscape's
+// <metadata> names its licence that way). Stripped before the outside-url rule
+// reads a markup file; an <image href>, a <script src>, a <use href> stay.
+const MARKUP_IDENTIFIERS = /\b(?:xmlns(?::[\w.-]+)?|xsi:(?:noNamespace)?schemaLocation|rdf:(?:about|resource|datatype))\s*=\s*(?:"[^"]*"|'[^']*')/gi;
+// Extensions are compared in lower case throughout: the CDN serves main.JS as
+// JavaScript (bundles.go lower-cases too), so the scan reads it as such.
+const ext = (f) => extname(f.path).toLowerCase();
+
+// Markup a game's pages must never contain: each is a way out of the
+// sandbox's promises. The code rules of the same kind (eval, sockets, imports
+// of URLs, the report path in a string …) are the analyser's.
+// A tag is read under any namespace prefix (an XHTML document's <h:base>).
+const FORBIDDEN_MARKUP = [
+    { rule: 'report-path', re: /\/csp-report\b/ },
+    { rule: 'meta-csp', re: /<(?:[\w.-]+:)?meta[^>]+http-equiv\s*=\s*["']?content-security-policy/i },
+    { rule: 'navigation', re: /<(?:[\w.-]+:)?base\b|<(?:[\w.-]+:)?meta[^>]+http-equiv\s*=\s*["']?refresh|<(?:[\w.-]+:)?(?:object|embed)\b|\bsrcdoc\s*=/i },
+];
+// The scan is the early word; the browser's policy on the studio origin
+// (no eval, connect-src self, base-uri none, no plugins) is the law, and the
+// run proves the bets reach the engine.
+
+// Libraries a studio ships under vendor/ that we know by name. A file named
+// like one, carrying the banner its releases carry in the first 4 KB, is read
+// as that library: what the analyser would refuse in it is named for the
+// reviewer instead (the browser's policy blocks it at run time, and the run
+// proves the game works without it), and its being minified is expected.
+// Anything else under vendor/ is the game's own code to the scan. A studio
+// with another library asks us to add it here.
+export const KNOWN_LIBRARIES = [
+    { name: 'PixiJS', file: /^(?:pixi|unsafe-eval|pixi-[\w.-]+)(?:[.-][\w.-]*)?\.m?js$/i, banner: /pixi\.?js/i },
+    { name: 'howler.js', file: /^howler(?:[.-][\w.-]*)?\.m?js$/i, banner: /howler/i },
+    { name: 'GSAP', file: /^(?:gsap|[A-Za-z]+Plugin)(?:[.-][\w.-]*)?\.m?js$/i, banner: /gsap|greensock/i },
+    { name: 'three.js', file: /^three(?:[.-][\w.-]*)?\.m?js$/i, banner: /three\.?js/i },
+    { name: 'Phaser', file: /^phaser(?:[.-][\w.-]*)?\.m?js$/i, banner: /phaser/i },
+    { name: 'Babylon.js', file: /^babylon(?:[.-][\w.-]*)?\.m?js$/i, banner: /babylon/i },
+    { name: 'Matter.js', file: /^matter(?:[.-][\w.-]*)?\.m?js$/i, banner: /matter/i },
+    { name: 'Planck.js', file: /^planck(?:[.-][\w.-]*)?\.m?js$/i, banner: /planck/i },
+    { name: 'anime.js', file: /^anime(?:[.-][\w.-]*)?\.m?js$/i, banner: /anime/i },
+    { name: 'jQuery', file: /^jquery(?:[.-][\w.-]*)?\.m?js$/i, banner: /jquery/i },
+    { name: 'lodash', file: /^lodash(?:[.-][\w.-]*)?\.m?js$/i, banner: /lodash/i },
+    { name: 'Spine', file: /^(?:spine|pixi-spine)(?:[.-][\w.-]*)?\.m?js$/i, banner: /spine/i },
+    { name: 'Tone.js', file: /^tone(?:[.-][\w.-]*)?\.m?js$/i, banner: /tone\.?js/i },
+    { name: 'Hammer.js', file: /^hammer(?:[.-][\w.-]*)?\.m?js$/i, banner: /hammer/i },
+    { name: 'Tween.js', file: /^tween(?:[.-][\w.-]*)?\.m?js$/i, banner: /tween/i },
+    { name: 'p5.js', file: /^p5(?:[.-][\w.-]*)?\.m?js$/i, banner: /p5\.?js/i },
+    { name: 'CreateJS', file: /^(?:createjs|easeljs|soundjs|preloadjs|tweenjs)(?:[.-][\w.-]*)?\.m?js$/i, banner: /createjs/i },
+    { name: 'PlayCanvas', file: /^playcanvas(?:[.-][\w.-]*)?\.m?js$/i, banner: /playcanvas/i },
+    { name: 'cannon.js', file: /^cannon(?:[.-][\w.-]*)?\.m?js$/i, banner: /cannon/i },
+    { name: 'Box2D', file: /^box2d(?:[._-][\w.-]*)?\.m?js$/i, banner: /box2d/i },
+    { name: 'Rapier', file: /^rapier(?:[._-][\w.-]*)?\.m?js$/i, banner: /rapier/i },
+    // three.js's loaders' glue (examples/jsm/libs): Emscripten builds that run their module.
+    { name: 'Basis Universal (three.js)', file: /^basis_transcoder(?:[._-][\w.-]*)?\.m?js$/i, banner: /\bBASIS\b/ },
+    { name: 'Draco (three.js)', file: /^draco_(?:decoder|encoder|wasm_wrapper)(?:[._-][\w.-]*)?\.m?js$/i, banner: /draco/i },
+];
+const BANNER_BYTES = 4096;
+
+// A scheme is a word of its own: `--turn:180deg` (a CSS custom property) and
+// `.turn:hover` (a class) are not TURN server addresses, so a scheme preceded
+// by a word character, `-`, `.` or `#` is not one.
+const URL_RE = /(?<![\w.#-])(?:https?|wss?|stuns?|turns?):\/?\/?[^\s"'`)<>]+/g;
+// Hosts that appear in markup as identifiers, not as network destinations.
+const URL_IGNORE = /^https?:\/\/(www\.w3\.org|schema\.org|xmlns\.com)\//;
+
+// Comments describe code but do not execute it (the engine-use checks below
+// read the code without them; the analyser has its own parser).
+function withoutComments(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/(^|[^\\])\/\/.*$/gm, '$1');
+}
+
+// Plain files only: a link could point outside the bundle, or loop.
+function walk(dir, root = dir, out = []) {
+    for (const name of readdirSync(dir)) {
+        const p = join(dir, name);
+        const st = lstatSync(p);
+        if (st.isDirectory()) walk(p, root, out);
+        else out.push({ path: relative(root, p), abs: p, bytes: st.size, link: st.isSymbolicLink() });
+    }
+    return out;
+}
+
+// A worker thread's one answer, by its deadline: compressing and parsing are
+// CPU time the asking process's event loop must not spend, since the pipeline
+// serves an API while it scans. A thread past its deadline is stopped, and the
+// scan fails rather than waits.
+function onWorker(script, workerData, timeout, what, resourceLimits) {
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(new URL(script, import.meta.url), { workerData, resourceLimits });
+        const timer = setTimeout(() => { worker.terminate(); reject(new Error(`${what} took over ${timeout / 1000} s`)); }, timeout);
+        worker.once('message', (m) => { clearTimeout(timer); resolve(m); });
+        worker.once('error', (e) => { clearTimeout(timer); reject(new Error(`${what} stopped: ${e.message}`)); });
+        worker.once('exit', (code) => { clearTimeout(timer); if (code !== 0) reject(new Error(`${what} stopped with ${code}`)); });
+    });
+}
+
+// The gzip size of each file, by index (gzip-sizes.mjs).
+const gzipSizes = (paths, timeout) => onWorker('./gzip-sizes.mjs', paths, timeout, 'measuring the gzip sizes');
+// The analyser's findings per code file (analyse-worker.mjs). The thread's heap
+// is bounded: a 4 MB file's syntax tree is tens of megabytes, not a gigabyte.
+const analyseFiles = (files, timeout) => onWorker('./analyse-worker.mjs', { files }, timeout, 'analysing the code', { maxOldGenerationSizeMb: 1024 });
+
+// Does this HTML frame another page of the bundle (an <iframe>, <frame>,
+// <embed> or <object> whose src/data is a relative .html address)? A tag walk,
+// not one regex over the file: the file is a studio's, and a pattern with
+// overlapping quantifiers could be made to backtrack for minutes.
+const FRAME_TAG = /<(?:[\w.-]+:)?(?:iframe|frame|embed|object)\b/gi;
+const FRAME_ADDRESS = /\b(?:src|data)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi;
+const OWN_PAGE = /^(?!(?:[a-z][a-z0-9+.-]*:)?\/\/)(?![a-z][a-z0-9+.-]*:)[^?#]*\.(?:html?|xhtml|xml|svg)(?:[?#]|$)/i;
+export function framesOwnPage(html) {
+    FRAME_TAG.lastIndex = 0;
+    for (let m; (m = FRAME_TAG.exec(html)); ) {
+        const start = m.index;
+        const end = html.indexOf('>', start);
+        // A tag is short; one that runs on for kilobytes is not one a browser
+        // would read as this tag: that window is read as it is and the walk
+        // goes on after it, never back over it.
+        const capped = end < 0 || end - start > 4096;
+        const tagEnd = capped ? Math.min(start + 4096, html.length) : end;
+        const tag = html.slice(start, tagEnd);
+        FRAME_ADDRESS.lastIndex = 0;
+        for (let a; (a = FRAME_ADDRESS.exec(tag)); ) {
+            const value = (a[1] ?? a[2] ?? a[3] ?? '').trim();
+            if (OWN_PAGE.test(value)) return true;
+        }
+        FRAME_TAG.lastIndex = capped ? tagEnd : end + 1;
+    }
+    return false;
+}
+
+// The first 4 KB of a file, where a library's banner is.
+function head(abs) {
+    const fd = openSync(abs, 'r');
+    try {
+        const buf = Buffer.alloc(BANNER_BYTES);
+        const n = readSync(fd, buf, 0, BANNER_BYTES, 0);
+        return buf.toString('utf8', 0, n);
+    } finally { closeSync(fd); }
+}
+
+// Which known library a vendor/ file is, by its name and the banner in its
+// head; null for anything else.
+export function recognisedLibrary(path, head) {
+    if (!path.startsWith('vendor/')) return null;
+    const base = posix.basename(path);
+    const lib = KNOWN_LIBRARIES.find((l) => l.file.test(base));
+    return lib && lib.banner.test(head.slice(0, BANNER_BYTES)) ? lib.name : null;
+}
+
+// A source map a reviewer can read from: version 3, with every source's text
+// in it. Returns the problem, or null when the map will do.
+export function sourceMapProblem(json) {
+    let map;
+    try { map = JSON.parse(json); } catch { return 'its source map is not valid JSON'; }
+    if (!map || map.version !== 3) return 'its source map is not version 3';
+    if (!Array.isArray(map.sources) || map.sources.length === 0) return 'its source map names no sources';
+    if (!Array.isArray(map.sourcesContent) || map.sourcesContent.length !== map.sources.length || !map.sourcesContent.every((s) => typeof s === 'string')) return 'its source map has no sourcesContent: the original code is not in the bundle';
+    return null;
+}
+
+// The source map of a minified file, found by its sourceMappingURL comment
+// (a path in the bundle, or a data: URL with the map inline) or as the .map
+// beside it. Returns null when a readable map is there, else why not.
+function minifiedProblem(file, sourceMappingURL, byPath) {
+    const url = sourceMappingURL;
+    if (url && /^data:/i.test(url)) {
+        const m = /^data:[^,]*?(;base64)?,(.*)$/is.exec(url);
+        if (!m) return 'its inline source map cannot be read';
+        const json = m[1] ? Buffer.from(m[2], 'base64').toString('utf8') : decodeURIComponent(m[2]);
+        return sourceMapProblem(json);
+    }
+    const candidates = [];
+    if (url && !/^[a-z][a-z0-9+.-]*:/i.test(url)) candidates.push(posix.normalize(posix.join(posix.dirname(file), url.split(/[?#]/)[0])));
+    candidates.push(file + '.map');
+    for (const c of candidates) {
+        const f = byPath.get(c);
+        if (f && !f.link) return sourceMapProblem(readFileSync(f.abs, 'utf8'));
+    }
+    return url ? `its source map ${url.slice(0, 60)} is not in the bundle` : 'no source map in the bundle';
+}
+
+// Is this file a WebAssembly module, whatever it is called? Its first four
+// bytes say (`\0asm`); a .wasm by extension is one too.
+function isWasm(f) {
+    if (ext(f) === '.wasm') return true;
+    if (f.bytes < 4 || f.bytes > BUDGETS.fileBytes) return false;
+    const fd = openSync(f.abs, 'r');
+    try { const buf = Buffer.alloc(4); readSync(fd, buf, 0, 4, 0); return buf.equals(WASM_MAGIC); } finally { closeSync(fd); }
+}
+const sha256 = (abs) => createHash('sha256').update(readFileSync(abs)).digest('hex');
+
+// What the analyser found, as the report's findings. A refusal is one finding
+// per rule and file, with its lines; a warning is one finding per rule across
+// the bundle, with its places, so the reviewer reads each rule once. A rule
+// the analyser refuses in a known library is a warning kept with its file.
+const LOCATIONS = 8;
+function aggregate(found) {
+    const groups = new Map();
+    const place = (level, rule, file, loc) => {
+        const perFile = level === 'fail' || loc.library;
+        const key = `${level}\0${rule}\0${perFile ? file : ''}`;
+        let g = groups.get(key);
+        if (!g) groups.set(key, (g = { level, rule, file: perFile ? file : null, library: loc.library || null, locs: [], seen: new Set() }));
+        const id = `${file}\0${loc.line}\0${loc.what}`;
+        if (g.seen.has(id)) return;
+        g.seen.add(id);
+        g.locs.push({ file, line: loc.line, what: loc.what });
+    };
+    for (const { file, library, findings } of found) {
+        for (const f of findings) {
+            const demoted = library && f.level === 'fail' && f.rule !== 'syntax' && f.rule !== 'analyser';
+            place(demoted ? 'warn' : f.level, f.rule, file, { ...f, library: demoted ? library : null });
+        }
+    }
+    const out = [];
+    for (const g of groups.values()) {
+        g.locs.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+        const shown = g.locs.slice(0, LOCATIONS).map((l) => (g.file ? `line ${l.line} ${l.what}` : `${l.file}:${l.line} ${l.what}`));
+        const more = g.locs.length > LOCATIONS ? ` (+${g.locs.length - LOCATIONS} more)` : '';
+        const text = (RULES[g.rule]?.text ?? g.rule) + (g.library ? (g.rule === 'wasm-source' ? ` (library ${g.library}: runs its own released module)` : ` (library ${g.library}: blocked at run time)`) : '');
+        out.push({ level: g.level, rule: g.rule, detail: `${text}: ${shown.join(', ')}${more}`, ...(g.file ? { file: g.file } : {}) });
+    }
+    return out;
+}
+
+export async function scan(dir, { gzipTimeout = GZIP_TIMEOUT, analyseTimeout = ANALYSE_TIMEOUT } = {}) {
+    const findings = [];
+    const add = (level, rule, detail, file) => findings.push({ level, rule, detail, ...(file ? { file } : {}) });
+    const files = walk(dir);
+    const total = files.reduce((a, f) => a + f.bytes, 0);
+    const byPath = new Map(files.map((f) => [f.path, f]));
+
+    if (!files.some((f) => f.path === 'index.html')) add('fail', 'entry', 'no index.html at the bundle root');
+    if (total > BUDGETS.totalBytes) add('fail', 'budget-total', `${mb(total)} MB, limit ${mb(BUDGETS.totalBytes)} MB`);
+    if (files.length > BUDGETS.files) add('fail', 'budget-files', `${files.length} files, limit ${BUDGETS.files}`);
+    for (const f of files) {
+        if (f.link) add('fail', 'symlink', 'a link, not a file', f.path);
+        else if (f.bytes > BUDGETS.fileBytes) add('fail', 'budget-file', `${mb(f.bytes)} MB, limit ${mb(BUDGETS.fileBytes)} MB`, f.path);
+        else if (f.bytes > BUDGETS.codeBytes && (CODE.has(ext(f)) || ext(f) === '.css')) add('fail', 'budget-code', `${mb(f.bytes)} MB of code, limit ${mb(BUDGETS.codeBytes)} MB`, f.path);
+    }
+    // engine-sdk/ is ours, served on the studio origin: a copy in the bundle
+    // would be a changed SDK.
+    if (files.some((f) => f.path.startsWith('engine-sdk/'))) add('fail', 'sdk-shipped', 'engine-sdk/ is served by the platform; the bundle must not carry its own');
+
+    // Staged loading: assets.json groups, the boot group within budget.
+    const manifest = files.find((f) => f.path === 'assets.json');
+    if (!manifest) {
+        add('fail', 'assets-manifest', `no assets.json: nothing says what loads first, so the first frame waits for all ${mb(total)} MB`);
+    } else {
+        let groups = null;
+        try {
+            const m = JSON.parse(readFileSync(manifest.abs, 'utf8'));
+            for (const problem of checkAssetManifest(m)) add('fail', 'assets-manifest', problem);
+            groups = m.groups;
+        } catch { add('fail', 'assets-manifest', 'assets.json is not valid JSON'); }
+        const staged = new Set(Object.values(groups || {}).flatMap((g) => g.files || []));
+        // Source maps are for the reviewer, never fetched by the page.
+        const unstaged = files.filter((f) => !staged.has(f.path) && !['assets.json', 'hbtest.json', 'i18n.json'].includes(f.path) && !f.path.endsWith('.map'));
+        if (unstaged.length) add('warn', 'assets-unstaged', `${unstaged.length} file(s) in no group, e.g. ${unstaged[0].path}: shipped, never prefetched`);
+        // Every group's members measured in one go, off this thread; a link is
+        // already a failure above and is not read.
+        const members = (g) => (g.files || []).map((p) => byPath.get(p)).filter((f) => f && !f.link);
+        const measured = [...new Set(Object.values(groups || {}).flatMap(members))];
+        const gzip = new Map();
+        try {
+            const sizes = await gzipSizes(measured.map((f) => f.abs), gzipTimeout);
+            measured.forEach((f, i) => gzip.set(f.path, sizes[i]));
+        } catch (e) { add('fail', 'budget-group', e.message); }
+        const gzipped = (files) => files.reduce((a, f) => a + (gzip.get(f.path) || 0), 0);
+        for (const [name, g] of Object.entries(groups || {})) {
+            const missing = (g.files || []).filter((p) => !byPath.has(p));
+            if (missing.length) add('fail', 'assets-missing', `group ${name} lists ${missing.length} file(s) not in the bundle, e.g. ${missing[0]}`);
+            const gz = gzipped(members(g));
+            const limit = name === 'boot' ? BUDGETS.bootGzipBytes : BUDGETS.groupGzipBytes;
+            if (gz > limit) add('fail', 'budget-group', `group ${name}: ${mb(gz)} MB gzip, limit ${mb(limit)} MB`);
+            if (name === 'boot') {
+                const js = gzipped(members(g).filter((f) => CODE.has(ext(f)) && !MARKUP.has(ext(f))));
+                if (js > BUDGETS.bootJsGzipBytes) add('fail', 'budget-boot-js', `boot JS ${kb(js)} KB gzip, limit ${kb(BUDGETS.bootJsGzipBytes)} KB`);
+            }
+        }
+    }
+
+    // Languages: a bundle that ships i18n.json ({en: {...}, ru: {...}}) is told
+    // which of the site's languages it lacks; English is the floor.
+    const i18n = files.find((f) => f.path === 'i18n.json');
+    if (i18n) {
+        let dict = null;
+        try { dict = JSON.parse(readFileSync(i18n.abs, 'utf8')); } catch { add('fail', 'i18n', 'i18n.json is not valid JSON'); }
+        if (dict && typeof dict === 'object') {
+            if (!dict.en) add('fail', 'i18n', 'i18n.json has no "en": English is the fallback for every player');
+            const missing = SITE_LOCALES.filter((l) => !dict[l]);
+            if (missing.length) add('warn', 'i18n', `no ${missing.join(' ')}: those players see English`);
+        }
+    }
+
+    // The code, read by the analyser on its thread: every .js/.mjs file and
+    // every script inside a page, within the code budget (a file over it has
+    // failed above and is not read); every SVG or XML document's markup and
+    // every text data file's text (within the file budget; they are not code,
+    // so the code budget does not bound them, and the walk is linear).
+    const isData = (f) => !CODE.has(ext(f)) && !XML_PAGES.has(ext(f)) && !REVIEW_ONLY.has(ext(f)) && f.bytes <= BUDGETS.fileBytes && isText(f);
+    const code = files.filter((f) => !f.link && ((CODE.has(ext(f)) && f.bytes <= BUDGETS.codeBytes) || (XML_PAGES.has(ext(f)) && f.bytes <= BUDGETS.fileBytes) || isData(f)));
+    const kind = (f) => (XML_PAGES.has(ext(f)) ? 'xml' : MARKUP.has(ext(f)) ? 'html' : CODE.has(ext(f)) ? 'script' : 'data');
+    let analysed = [];
+    try { analysed = await analyseFiles(code.map((f) => ({ path: f.path, abs: f.abs, kind: kind(f) })), analyseTimeout); }
+    catch (e) { add('fail', 'analyser', `${RULES.analyser.text}: ${e.message}`); }
+    const library = new Map(code.map((f) => [f.path, recognisedLibrary(f.path, f.path.startsWith('vendor/') ? head(f.abs) : '')]));
+    // A WebAssembly module is a program the analyser cannot read. One whose
+    // bytes are a known library's release (KNOWN_WASM, by SHA-256) is named for
+    // the reviewer, like the rest of what that library would be refused for;
+    // any other, whatever it is named and wherever it sits, is refused. Code
+    // that reaches WebAssembly is refused unless it is a recognised library's
+    // (demoted below with its other refusals): a game's own code runs none.
+    for (const f of files) {
+        if (f.link || !isWasm(f)) continue;
+        const hash = sha256(f.abs);
+        const known = KNOWN_WASM.get(hash);
+        if (known) add('warn', 'wasm-source', `a WebAssembly module of ${known.library} (${known.package} ${known.versions.join(', ')}, ${known.file}), shipped as released: named for review`, f.path);
+        else add('fail', 'wasm-source', `${RULES['wasm-source'].text}: not a known library release (sha256 ${hash})`, f.path);
+    }
+    const found = [];
+    for (const r of analysed) {
+        const lib = library.get(r.path);
+        const own = [...r.findings];
+        // Minified code is read through its source map; a known library is
+        // read as that library; an inline script has no map to be read through.
+        for (const u of r.units) {
+            if (!u.minified || lib) continue;
+            const problem = u.kind === 'inline' ? 'an inline script has no source map; put built code in a .js file with its .map' : minifiedProblem(r.path, r.sourceMappingURL, byPath);
+            if (problem) own.push({ level: 'fail', rule: 'minified', line: u.line, what: `${u.short} of ${u.names} names are one or two letters; ${problem}` });
+        }
+        // WebAssembly reached by the code: refused (a recognised library's is demoted to a warning by aggregate()).
+        for (const w of r.wasm) own.push({ level: 'fail', rule: 'wasm-source', line: w.line, what: w.what });
+        found.push({ file: r.path, library: lib, findings: own });
+    }
+    const fromCode = aggregate(found);
+    findings.push(...fromCode);
+    // A rule the analyser already named in a page (the report path in a
+    // script's string) is not named again by the markup regex.
+    const named = new Set(fromCode.filter((f) => f.file).map((f) => `${f.rule}\0${f.file}`));
+
+    let usesSdk = false, usesPlay = false, usesRevealed = false, nested = [];
+    for (const f of files) {
+        const e = ext(f);
+        if (!TEXT.has(e) || f.link) continue;
+        if (f.bytes > BUDGETS.codeBytes && (CODE.has(e) || e === '.css')) continue; // failed the code budget above, not read
+        const text = readFileSync(f.abs, 'utf8');
+        if (CODE.has(e)) {
+            const code = withoutComments(text);
+            if (/engine-sdk|connect\s*\(\s*\{[^}]*host/.test(code)) usesSdk = true;
+            // The engine panel (ui.js) plays and reveals for the game.
+            if (/\.play\s*\(\s*\{|engine-sdk\/ui\.js/.test(code)) usesPlay = true;
+            if (/\.revealed\s*\(|engine-sdk\/ui\.js/.test(code)) usesRevealed = true;
+        }
+        if (MARKUP.has(e)) {
+            for (const r of FORBIDDEN_MARKUP) if (!named.has(`${r.rule}\0${f.path}`) && r.re.test(text)) add('fail', r.rule, RULES[r.rule].text, f.path);
+            // A page that frames another page of the bundle: on a version's own origin
+            // that is allowed ('self'); on a shared origin only by its switch (bundles.SelfFrames).
+            if (framesOwnPage(text)) nested.push(f.path);
+        }
+        // (An SVG or XML document's scripts and handlers are the analyser's: svg-script, inline-handler.)
+        if (!CODE.has(e) && e !== '.css' && !XML_PAGES.has(e)) continue; // a URL in a text file is not a request
+        // A namespace or schema name in markup is an identifier, never fetched.
+        const addresses = MARKUP.has(e) ? text.replace(MARKUP_IDENTIFIERS, '') : text;
+        for (const u of addresses.match(URL_RE) || []) {
+            if (URL_IGNORE.test(u)) continue;
+            add(f.path.startsWith('vendor/') ? 'warn' : 'fail', 'outside-url', `references ${u.slice(0, 80)}: everything a game loads ships in its bundle`, f.path);
+            break;
+        }
+    }
+    if (!usesSdk) add('fail', 'no-engine', 'never connects to the engine (@housegames/engine-sdk): outcomes and money would not come from our server');
+    else {
+        if (!usesPlay) add('fail', 'no-play', 'connects but never calls engine.play: bets do not reach the server');
+        if (!usesRevealed) add('fail', 'no-revealed', 'never calls engine.revealed: the site header cannot follow the reveal');
+    }
+    if (nested.length) add('warn', 'nested-pages', `${nested.length} page(s) frame another page of the bundle, e.g. ${nested[0]}: build the game as one page with views inside it (GUIDE §1)`);
+
+    // Fails first, then warnings, each in the order found.
+    findings.sort((a, b) => (a.level === b.level ? 0 : a.level === 'fail' ? -1 : 1));
+    return { files: files.length, bytes: total, findings, ok: !findings.some((f) => f.level === 'fail') };
+}
+
+const mb = (b) => (b / 1024 / 1024).toFixed(1);
+const kb = (b) => Math.round(b / 1024);
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const dir = process.argv[2];
+    if (!dir) { console.error('usage: scan.mjs <bundle-dir> [--json]'); process.exit(2); }
+    const r = await scan(dir);
+    if (process.argv.includes('--json')) console.log(JSON.stringify(r, null, 1));
+    else {
+        console.log(`${r.ok ? 'PASS' : 'FAIL'}  ${r.files} files, ${mb(r.bytes)} MB`);
+        for (const f of r.findings) console.log(`  ${f.level.toUpperCase().padEnd(4)} ${f.rule.padEnd(16)} ${f.file ? f.file + ': ' : ''}${f.detail}`);
+    }
+    process.exit(r.ok ? 0 : 1);
+}

package/engine-conformance/testdata/clock-overlay/bundle/assets.json

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

package/engine-conformance/testdata/clock-overlay/bundle/game.css

@@ -0,0 +1,17 @@
+body { margin: 0; background: #08141a; color: #F9F9FB; font: 500 14px/1.4 'Figtree', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+.dice { width: 100%; max-width: 560px; box-sizing: border-box; padding: 20px; display: grid; gap: 20px; }
+.facts { display: flex; flex-wrap: wrap; gap: 16px; justify-content: space-between; font-size: 13px; color: #8F96A8; font-variant-numeric: tabular-nums; }
+.facts b { color: #F9F9FB; font-weight: 700; font-size: 15px; }
+.track { position: relative; height: 48px; background: #0b1f28; border: 1px solid #0D2A38; border-radius: 24px; }
+.win { position: absolute; top: 0; bottom: 0; background: rgba(40, 243, 243, 0.22); border-left: 1px solid #28F3F3; border-right: 1px solid #28F3F3; border-radius: inherit; }
+.scale { position: absolute; inset: 100% 12px auto 12px; padding-top: 6px; display: flex; justify-content: space-between; color: #8F96A8; font-size: 11px; font-variant-numeric: tabular-nums; }
+.marker { position: absolute; top: 50%; left: 22px; transform: translate(-50%, -50%); min-width: 44px; height: 36px; padding: 0 10px; display: grid; place-items: center; border-radius: 18px; background: #28F3F3; color: #041015; font-weight: 700; font-size: 15px; font-variant-numeric: tabular-nums; box-shadow: 0 6px 20px rgba(0,0,0,.4); transition: left 620ms cubic-bezier(.2,.8,.2,1); }
+.marker.win { background: #58e879; }
+.marker.lose { background: #FA2E5D; color: #F9F9FB; }
+.pick { display: grid; gap: 12px; }
+.side { display: inline-flex; padding: 3px; gap: 3px; background: rgba(9,102,125,0.15); border-radius: 8px; justify-self: start; }
+.side button { height: 32px; padding: 0 14px; border: 0; border-radius: 6px; background: transparent; color: #8F96A8; font: inherit; font-weight: 600; cursor: pointer; }
+.side button[aria-pressed="true"] { background: #0D2A38; color: #F9F9FB; }
+.target { display: grid; grid-template-columns: 1fr auto; gap: 12px; align-items: center; }
+.target input[type="range"] { width: 100%; accent-color: #28F3F3; }
+.target output { color: #F9F9FB; font-weight: 700; font-variant-numeric: tabular-nums; min-width: 28px; text-align: right; }

package/engine-conformance/testdata/clock-overlay/bundle/game.js

@@ -0,0 +1,83 @@
+// A test bundle (travel.browser.test.mjs): dice as the other test bundles play
+// it, with a hidden behaviour keyed on the clock and on what it kept in
+// storage. The first time it boots it remembers the instant; from twelve hours
+// after that instant, the first stake typed puts a full-screen "session
+// expired" sign-in over the bet button — a password field and the words of a
+// credential prompt, which also take the run's click (the click never lands,
+// so the harness breaks on it). The run must still see what was on screen
+// when it broke and fail the variant on it, not file the break alone.
+import { mount } from '/engine-sdk/ui.js';
+
+const el = document.getElementById('game');
+const marker = document.getElementById('marker');
+const winBand = document.getElementById('win');
+const mult = document.getElementById('mult');
+const chance = document.getElementById('chance');
+const maxwin = document.getElementById('maxwin');
+const target = document.getElementById('target');
+const val = document.getElementById('val');
+const sides = el.querySelectorAll('[data-side]');
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const pct = (x) => (x / 99 * 100) + '%';
+
+let side = 'under';
+let n = 50;
+
+// The trigger: the first boot is remembered; half a day on, the sign-in appears on the first stake.
+const KEY = 'overlay-first-seen';
+let first = Number(localStorage.getItem(KEY) || 0);
+if (!first) { first = Date.now(); localStorage.setItem(KEY, String(first)); }
+const armed = Date.now() - first > 12 * 60 * 60 * 1000;
+let shown = false;
+const overlay = () => {
+    if (!armed || shown) return;
+    shown = true;
+    const box = document.createElement('div');
+    box.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,.85);z-index:9999;display:grid;place-items:center;color:#fff;font:16px sans-serif';
+    box.innerHTML = '<form><h2>Session expired</h2><p>Enter your password to continue</p><label>Password <input type="password" name="pw"></label><br><button type="button">Log in</button></form>';
+    document.body.append(box);
+};
+
+const game = await mount(el, {
+    async reveal(round) {
+        const roll = round.data[0].roll;
+        marker.classList.remove('win', 'lose');
+        marker.textContent = '?';
+        marker.style.transition = 'none';
+        marker.style.left = '22px';
+        void marker.offsetWidth;
+        marker.style.transition = '';
+        await wait(40);
+        marker.style.left = `clamp(22px, ${pct(roll)}, calc(100% - 22px))`; // the marker stays on the track at 0 and 99
+        await wait(620);
+        marker.textContent = String(roll);
+        marker.classList.add(round.payout > 0 ? 'win' : 'lose');
+    },
+});
+const { engine, field } = game;
+const money = engine.money;
+const bets = new Map(engine.config.modes[0].bets.map((b) => [b.id, b]));
+const range = () => (side === 'under' ? [0, n - 1] : [n + 1, 99]);
+
+function paint() {
+    val.textContent = String(n);
+    const [lo, hi] = range();
+    winBand.style.left = pct(lo);
+    winBand.style.width = pct(hi - lo);
+    chance.textContent = String(hi - lo + 1);
+    const bet = bets.get(`${side}-${n}`);
+    const m = bet.maxMultBp / 10000;
+    mult.textContent = m.toFixed(2) + '×';
+    maxwin.textContent = money.sign + money.format(money.payout(field.amount, m)) + (money.sign ? '' : ' ' + money.unit);
+    game.bet = bet.id;
+}
+
+for (const s of sides) s.addEventListener('click', () => {
+    side = s.dataset.side;
+    for (const o of sides) o.setAttribute('aria-pressed', String(o === s));
+    paint();
+});
+target.addEventListener('input', () => { n = +target.value; paint(); });
+field.addEventListener('change', () => { paint(); overlay(); });
+field.addEventListener('input', overlay);
+paint();

package/engine-conformance/testdata/clock-overlay/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]" }
+}

package/engine-conformance/testdata/clock-overlay/bundle/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>Clock overlay</title>
+<link rel="stylesheet" href="./game.css">
+<script type="module" src="/engine-sdk/bet-field.js"></script>
+<script type="module" src="./game.js"></script>
+</head>
+<body>
+<hb-game id="game">
+  <div slot="zone" class="dice" aria-live="polite">
+    <div class="facts">
+      <span>Payout <b id="mult">2.00×</b></span>
+      <span>Chance <b id="chance">50</b>%</span>
+      <span>Max win <b id="maxwin">—</b></span>
+    </div>
+    <div class="track" id="track">
+      <div class="win" id="win"></div>
+      <div class="scale"><span>0</span><span>25</span><span>50</span><span>75</span><span>99</span></div>
+      <div class="marker" id="marker">?</div>
+    </div>
+    <div class="pick">
+      <div class="side" role="tablist">
+        <button type="button" data-side="under" aria-pressed="true">Under</button>
+        <button type="button" data-side="over">Over</button>
+      </div>
+      <label class="target"><input id="target" type="range" min="2" max="98" step="1" value="50" aria-label="target"><output id="val">50</output></label>
+    </div>
+  </div>
+</hb-game>
+</body>
+</html>

package/engine-conformance/testdata/clock-probe/bundle/assets.json

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