hbengine 0.2.3

package/engine-conformance/bundle.mjs

@@ -0,0 +1,208 @@
+// The code analysis of a whole bundle, for the worker thread (analyse-worker)
+// and for anything that wants it in-process (tests, a trace): every script
+// and page parsed and scoped first, the files then wired to one another — a
+// module's imports to the exports of the file they name, a classic script's
+// globals to every other script's, a page's elements to the scripts it loads
+// (and to the modules they import), every write to a property or an attribute
+// to a pool the reads consult, every call to the function it reaches in
+// whatever file — and each file judged with all of that in reach, so a value
+// put into the page is followed to where it is written.
+import { readFileSync } from 'node:fs';
+import { analyseData, analyseHtml, analyseXml, judgeSource, prepareSource, resolveSpecifier, scriptKind, RULES } from './analyse.mjs';
+
+// Every <script …> tag of a page, its attributes read for src and type (scriptKind).
+const SCRIPT_TAG = /<script\b([^>]*)>/gi;
+const SRC_ATTR = /\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+const TYPE_ATTR = /\stype\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+// The scripts a page loads by src: [{ target, kind }], kind 'script' (a classic
+// script: its top-level declarations are the page's globals), 'module', or
+// null for a data block the browser never runs.
+function scriptLoads(path, text) {
+    const out = [];
+    for (const m of text.matchAll(SCRIPT_TAG)) {
+        const attrs = m[1];
+        const src = SRC_ATTR.exec(attrs);
+        if (!src) continue;
+        const target = resolveSpecifier(path, (src[1] ?? src[2] ?? src[3] ?? '').trim());
+        if (target == null) continue;
+        const type = TYPE_ATTR.exec(attrs);
+        const kind = scriptKind(type ? (type[1] ?? type[2] ?? type[3] ?? '') : '');
+        if (kind === 'importmap') continue;
+        out.push({ target, kind });
+    }
+    return out;
+}
+
+/**
+ * `files`: [{ path, abs, kind }] with kind 'xml', 'html', 'data' or 'script'
+ * (scan.mjs decides). Returns one result per file: { path, findings, units,
+ * wasm, sourceMappingURL }. `hook(unit)` is called with each prepared unit
+ * before judging (a trace instruments the analysis there).
+ */
+export function analyseBundle(files, { read = (abs) => readFileSync(abs, 'utf8'), hook = null } = {}) {
+    const out = [];
+    const units = []; // { path, unit, page, result, inline }
+    const pages = new Map(); // path → { path, elements, overflow, loads: [paths], units }
+    const modules = new Map(); // path → unit (a .js/.mjs file), for imports
+    const jsons = new Map(); // path → parsed JSON (or undefined), for JSON imports
+    const texts = new Map(); // path → text of a .json data file
+    const fail = (result, e) => result.findings.push({ level: 'fail', rule: 'analyser', line: 1, what: `the analyser stopped on this file: ${e.message}` });
+
+    // The files every page loads by a plain <script src> (no type, or a
+    // JavaScript MIME type) are classic scripts: parsed as the browser parses
+    // them (a module-only construct is a syntax error there, as in the
+    // browser), with their top-level declarations the page's globals, which
+    // every other script reads. A file loaded both ways is read as a classic
+    // script (the over-approximation: more is global, nothing less).
+    const classic = new Set();
+    const texts0 = new Map();
+    for (const { path, abs, kind } of files) {
+        if (kind !== 'html') continue;
+        let text;
+        try { text = read(abs); } catch { continue; }
+        texts0.set(abs, text);
+        for (const { target, kind: k } of scriptLoads(path, text)) if (k === 'script') classic.add(target);
+    }
+
+    for (const { path, abs, kind } of files) {
+        const result = { path, findings: [], units: [], wasm: [], sourceMappingURL: null };
+        out.push(result);
+        try {
+            const text = texts0.has(abs) ? texts0.get(abs) : read(abs);
+            if (kind === 'xml') {
+                // An SVG or XML document runs its scripts and handler attributes
+                // when framed or embedded, not when drawn: read as the browser
+                // renders it (prefixes dropped; a DTD subset refused), any
+                // <script> refused outright (a game's scripts are .js files).
+                result.findings.push(...analyseXml(text).findings);
+            } else if (kind === 'data') {
+                // A text file that is not code or markup (.json, .txt, .csv, a
+                // template of any extension): markup the game may put into the
+                // page is walked as code's strings are. A .json the analyser
+                // cannot parse is refused: the page would read it as JSON, and
+                // what the analyser cannot read the same way it does not pass.
+                const r = analyseData(text);
+                result.findings.push(...r.findings);
+                if (/\.json$/i.test(path) && !r.parsed) result.findings.push({ level: RULES['data-file'].level, rule: 'data-file', line: 1, what: 'not valid JSON' });
+                if (/\.json$/i.test(path) && r.parsed) texts.set(path, text);
+            } else if (kind === 'html') {
+                const page = analyseHtml(text);
+                result.findings.push(...page.findings);
+                const info = { path, elements: page.elements, overflow: page.overflow, loads: [], units: [] };
+                pages.set(path, info);
+                for (const script of page.scripts) {
+                    const unit = prepareSource(script.code, { mode: script.mode, lineOffset: script.line - 1 });
+                    unit.path = path;
+                    units.push({ path, unit, page: info, result, inline: true });
+                    info.units.push(unit);
+                }
+                // The scripts the page loads by src (a <script src> has no body for the walk to return).
+                for (const { target } of scriptLoads(path, text)) if (!info.loads.includes(target)) info.loads.push(target);
+            } else {
+                const unit = prepareSource(text, { mode: classic.has(path) ? 'script' : 'auto' });
+                unit.path = path;
+                units.push({ path, unit, page: null, result, inline: false });
+                modules.set(path, unit);
+            }
+        } catch (e) {
+            // A shape of syntax the analyser did not expect fails the file, never passes it.
+            fail(result, e);
+        }
+    }
+
+    // ---- wiring -----------------------------------------------------------------
+
+    // A JSON module: its parsed value, read once.
+    const jsonOf = (path) => {
+        if (!jsons.has(path)) { const t = texts.get(path); let v; try { v = t == null ? undefined : JSON.parse(t.charCodeAt(0) === 0xfeff ? t.slice(1) : t); } catch { v = undefined; } jsons.set(path, v); }
+        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) => {
+        const target = resolveSpecifier(fromPath, specifier);
+        if (target == null) return null;
+        const m = modules.get(target);
+        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;
+    };
+
+    // 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.
+    const pool = { globals: new Map(), writes: new Map(), written: [], writtenOverflow: false };
+    for (const { unit } of units) {
+        const a = unit.analysis;
+        if (!unit.ast) continue;
+        for (const [name, binding] of a.root.names) {
+            if (a.mode !== 'script' && !binding.global) continue;
+            if (!binding.alias && !binding.hidden) continue;
+            if (!pool.globals.has(name)) pool.globals.set(name, []);
+            pool.globals.get(name).push({ binding, scope: a.root });
+        }
+        for (const w of a.writes) {
+            if (!a.targetOf(w)) continue;
+            const key = w.key ?? '*';
+            if (!pool.writes.has(key)) pool.writes.set(key, []);
+            pool.writes.get(key).push(w);
+        }
+        if (a.writtenOverflow) pool.writtenOverflow = true;
+        else pool.written.push(...a.written);
+    }
+    if (pool.written.length > 100000) { pool.written = []; pool.writtenOverflow = true; }
+
+    // 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
+    // imported by another (to a fixpoint, since imports chain).
+    const pagesOf = new Map();
+    for (const u of units) pagesOf.set(u.unit, new Set(u.page ? [u.page] : []));
+    for (const info of pages.values()) for (const target of info.loads) { const m = modules.get(target); if (m) pagesOf.get(m)?.add(info); }
+    for (let changed = true, rounds = 0; changed && rounds < 50; rounds++) {
+        changed = false;
+        for (const { path, unit } of units) {
+            if (!unit.ast) continue;
+            const mine = pagesOf.get(unit);
+            for (const specifier of unit.analysis.imports) {
+                const target = resolveSpecifier(path, specifier);
+                const m = target != null ? modules.get(target) : null;
+                if (!m) continue;
+                const theirs = pagesOf.get(m);
+                for (const p of mine) if (!theirs.has(p)) { theirs.add(p); changed = true; }
+            }
+        }
+    }
+    for (const { path, unit } of units) {
+        const a = unit.analysis;
+        a.modules = moduleFrom(path);
+        a.pool = pool;
+        a.pages = [...(pagesOf.get(unit) ?? [])];
+    }
+
+    // Every reference, in every file, to a function of another file (or a method
+    // of a written object) otherwise than as a callee — handed to forEach, a
+    // timer, a listener, kept in a name — escapes it: called from where the
+    // analyser does not see, its parameters stay unknown. Then every call, in
+    // every file, to a function the resolver reaches (a method of an object
+    // another file set on the global object, an export called by its importer,
+    // a method of a written object): a call site of that function, so its
+    // parameters are the arguments written there.
+    for (const { unit } of units) if (unit.ast) { unit.analysis.cache.clear(); unit.analysis.mentioned.clear(); unit.analysis.globalNames.clear(); unit.analysis.writesByKey = null; unit.analysis.writesBySyntax = null; } // (pass 1 resolved before the wiring)
+    for (const { unit } of units) if (unit.ast) unit.analysis.collectEscapes();
+    for (const { unit } of units) if (unit.ast) unit.analysis.collectSites();
+
+    // ---- judging -----------------------------------------------------------------
+
+    for (const { unit, result, inline } of units) {
+        try {
+            if (hook) hook(unit);
+            const r = judgeSource(unit);
+            result.findings.push(...r.findings);
+            result.wasm.push(...r.wasm);
+            if (inline) result.units.push({ kind: 'inline', line: unit.analysis.lineOffset + 1, minified: r.minified, names: r.names, short: r.short });
+            else { result.sourceMappingURL = r.sourceMappingURL; result.units.push({ kind: 'file', line: 1, minified: r.minified, names: r.names, short: r.short }); }
+        } catch (e) {
+            fail(result, e);
+        }
+    }
+    return out;
+}

package/engine-conformance/clock.mjs

@@ -0,0 +1,294 @@
+/**
+ * The fake clock a time-travel page runs under, and how the run drives it.
+ *
+ * The implementation is Playwright's own (the clock its context.clock
+ * installs: fake Date, timers, animation frames, idle callbacks, performance
+ * and Intl, flowing at real pace and jumped by runFor/fastForward), read from
+ * the installed playwright-core. Playwright installs it under a global the
+ * game could find (`globalThis.__pwClock`) and drives it by evaluating against
+ * that name in every frame; the run installs the same code from its own init
+ * script with no global at all, and drives it through the message channel
+ * travel.mjs clockTrap listens on under the run's token: the site page (the
+ * run's own) posts `token:clock:<op>:<id>:<ms>` into every frame and waits for
+ * each frame's `token:clockdone:<id>:<now>`. Nothing of it is reachable from a
+ * page's script, and a frame that did not answer is a frame whose clock did
+ * not move, which the run treats as the variant breaking rather than judging
+ * a game on clocks that disagree.
+ *
+ * Three pieces of Playwright's code are changed (patchClockSource): a timer's
+ * callback is called from a native timer task instead of from the clock's own
+ * loop, so a stack trace taken inside it holds the callback alone, as in
+ * production, and never the clock's frames (_callFirstTimer, _runTo); an
+ * exception it throws reaches the window as an uncaught error, as in
+ * production, where the run records it. An animation frame's callback is
+ * given the document's animation timeline reading (the embedder's
+ * `frameTime`, set by startClock: the native frame time plus the clock's
+ * lead, which is what the shimmed `document.timeline.currentTime` reads) in
+ * place of the clock's ticks, so inside the callback the two are equal as in
+ * production. And a read of the clock while it is paused from its real-time
+ * flow (inside a jump: runFor and fastForward pause it) asks the embedder to
+ * let the real time since the clock last moved flow into it (`flowInJump`,
+ * set by startClock), so inside a callback the jump fires performance.now()
+ * and Date.now() move across the callback's own work as they do in any
+ * browser, instead of standing still until the callback returns. The patch is
+ * applied to the exact text it expects and refused otherwise: a clock the run
+ * does not know is not a clock to travel on.
+ *
+ * A frame the game makes while the run is on (a nested page) installs its own
+ * clock at creation and reads the instant from its parent, same-origin, so it
+ * agrees with the frames that jumped before it existed; a frame with no
+ * same-origin parent (the top frames at launch) starts from the instant the
+ * run set, plus the real time since.
+ */
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+let cached = null;
+
+// What the patch replaces, and with what (clockSource's `_callFirstTimer` and
+// the embedder it dispatches through).
+const DISPATCH_FROM = `      let error;
+      try {
+        timer.func.apply(null, args);
+      } catch (e) {
+        error = e;
+      }
+      await new Promise((f) => this._embedder.setTimeout(f));
+      return { timerFound: true, error };`;
+const DISPATCH_TO = `      await new Promise((f) => { this._embedder.callTimer(timer.func, args); this._embedder.setTimeout(f); });
+      return { timerFound: true, error: void 0 };`;
+const EMBEDDER_FROM = `    setTimeout: (task, timeout) => {
+      const timerId = originals.bound.setTimeout(task, timeout);`;
+const EMBEDDER_TO = `    callTimer: (func, args) => void originals.bound.setTimeout(func, 0, ...args),
+    setTimeout: (task, timeout) => {
+      const timerId = originals.bound.setTimeout(task, timeout);`;
+const FRAME_FROM = `      if (timer.type === "AnimationFrame" /* AnimationFrame */)
+        args = [this._now.ticks];`;
+const FRAME_TO = `      if (timer.type === "AnimationFrame" /* AnimationFrame */)
+        args = [typeof this._embedder.frameTime === "function" ? this._embedder.frameTime(this._now.ticks) : this._now.ticks];`;
+// A read of the clock while it is paused from its real-time flow (inside a
+// jump): the embedder may let the real time since flow into it.
+const SYNC_FROM = `  _syncRealTime() {
+    if (!this._realTime)
+      return;`;
+const SYNC_TO = `  _syncRealTime() {
+    if (!this._realTime) {
+      if (typeof this._embedder.flowInJump === "function")
+        this._embedder.flowInJump();
+      return;
+    }`;
+
+/**
+ * Playwright's clock source with a timer's callback dispatched from a native
+ * timer task (see above): the callback goes to the native setTimeout as it is,
+ * with the timer's arguments, and the clock's loop waits for a task of its own
+ * queued right after it, so callbacks still run one per task and in order; an
+ * animation frame's callback given the embedder's frame time when it has one;
+ * and a read of the paused clock (inside a jump) handed to the embedder's
+ * `flowInJump` when it has one, so the clock can flow with the real time the
+ * jump's callbacks spend. All four pieces of text must be there exactly once,
+ * or the source is refused.
+ */
+export function patchClockSource(src) {
+    if (typeof src !== 'string') throw new Error('the clock source is not text');
+    for (const [from, what] of [[DISPATCH_FROM, 'timer dispatch'], [EMBEDDER_FROM, 'embedder'], [FRAME_FROM, 'animation frame argument'], [SYNC_FROM, 'real-time sync']]) {
+        const n = src.split(from).length - 1;
+        if (n !== 1) throw new Error(`playwright-core's clock source is not what the run expects: its ${what} appears ${n} time(s), not once`);
+    }
+    return src.replace(DISPATCH_FROM, DISPATCH_TO).replace(EMBEDDER_FROM, EMBEDDER_TO).replace(FRAME_FROM, FRAME_TO).replace(SYNC_FROM, SYNC_TO);
+}
+
+/**
+ * Playwright's clock implementation, as its own context.clock injects it: a
+ * script that leaves `inject` and `install` on `module.exports`. Read from the
+ * installed playwright-core, patched (patchClockSource), and refused when it
+ * is not what the run expects: a matrix on a clock the run does not know is
+ * not a matrix.
+ */
+export function clockSource() {
+    if (cached) return cached;
+    const require = createRequire(import.meta.url);
+    let file;
+    try { file = join(dirname(require.resolve('playwright-core')), 'lib', 'generated', 'clockSource.js'); } catch (e) { throw new Error(`playwright-core is not installed: ${e.message}`); }
+    let src;
+    try { src = require(file).source; } catch (e) { throw new Error(`playwright-core's clock source could not be read (${file}): ${e.message}`); }
+    if (typeof src !== 'string' || !src.includes('ClockController') || !src.includes('inject: () => inject') || !src.includes('module.exports')) throw new Error(`playwright-core's clock source is not what the run expects (${file})`);
+    cached = patchClockSource(src);
+    return cached;
+}
+
+/**
+ * Starts the fake clock in a scope (stringified into the page's init script,
+ * after the natives are captured and before anything else): Playwright's
+ * `inject` installs the fakes and lets them flow; `install(at)` sets the
+ * instant. `at` is the parent frame's now when the parent is the game's own
+ * (same-origin: a frame made mid-run agrees with the frames that jumped), else
+ * `o.at` plus the real time since `o.wall`, when the run wrote the script.
+ *
+ * The fake's monotonic clock is started where the native one stands (Playwright
+ * starts it at zero), so performance.now() and every native timestamp agree
+ * at boot and differ afterwards by the jumps alone. Those are kept: a history
+ * of what the fake clock was ahead of the native one after each move, read
+ * back by `leadAt` (the lead at a native instant: a timestamp taken before a
+ * jump keeps its time) and `toNative` (a fake instant as the native clock
+ * knows it). Inside a jump the clock flows: Playwright pauses its real-time
+ * flow for the jump, so the clock would stand still inside every callback the
+ * jump fires until the callback returned (a game measuring its own work
+ * against performance.now() in a timer would read zero, which no browser
+ * shows); here the real time since the clock last moved is let into it at
+ * every read inside the jump (the patched `_syncRealTime` asks
+ * `flowInJump`) and before every move (a timer's dispatch, the jump's end),
+ * so a callback that spends 3 ms sees 3 ms pass, the timer due next fires in
+ * order and late by what the callback took, as natively, and the jump still
+ * ends at its target with the callbacks' time inside it. And the jumps reach
+ * what the clock does not drive: every running animation (Web Animations,
+ * CSS) is moved on by what the clock moved, at its own rate, as the clock
+ * moves (before any timer due in the jump runs); the real time the jump
+ * itself took moves the animations on its own (the compositor's), and what
+ * of it the clock did not count is taken back at the end, so a transition
+ * finishes in game time, and what is on screen agrees with the clock. An
+ * animation frame's callback is handed the timeline's reading (the native
+ * frame time plus the lead), the same number `document.timeline.currentTime`
+ * gives inside it. The same in a worker (workerShim): no document, no
+ * animations, no parent; a timer global the scope never had (Playwright
+ * installs `requestIdleCallback` wherever it installs) is removed again, so
+ * the scope keeps its own shape. Returns what clockShim and clockTrap need of
+ * it: the fake to read, and the jump to drive (and the controller and the
+ * history, for the tests).
+ */
+export function startClock(scope, o, exportsOf, natives) {
+    // Playwright's bundle exports thunks (`inject: () => inject`): the function is one call in.
+    const inject = exportsOf.inject();
+    if (typeof inject !== 'function') throw new Error('the clock source exports no inject');
+    // The clock reads real time through the `performance` it finds at injection
+    // and calls `now` on it by name; clockShim will route that name to the fake,
+    // so the clock is given a stand-in holding the native `now` bound, and the
+    // native object is put back by the shim. Nothing the game sees of it.
+    const nativeNow = natives.perfNow.d.value.bind(natives.performance);
+    const standIn = { now: nativeNow, timeOrigin: natives.originValue };
+    Object.defineProperty(scope, 'performance', { value: standIn, writable: true, enumerable: true, configurable: true });
+    const pw = inject(scope);
+    if (!pw || !pw.controller || typeof pw.controller.install !== 'function') throw new Error('the clock source gave no controller');
+    // A timer the scope never had (a worker has no requestIdleCallback) is not given to it.
+    for (const k of ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'requestAnimationFrame', 'cancelAnimationFrame', 'requestIdleCallback', 'cancelIdleCallback']) {
+        if (typeof natives[k] !== 'function' && Object.getOwnPropertyDescriptor(scope, k)) { try { delete scope[k]; } catch { /* left as it is */ } }
+    }
+    // Playwright's fake performance, read here before clockShim puts the native object back: its now and
+    // timeOrigin are the fake clock's (the shimmed getters read them from here, never from themselves).
+    const fakePerf = scope.performance;
+    let at = null;
+    try { if (scope.parent && scope.parent !== scope && typeof scope.parent.Date === 'function') at = scope.parent.Date.now(); } catch { at = null; }
+    if (typeof at !== 'number' || !Number.isFinite(at)) at = o.at + (natives.Date.now() - o.wall);
+    const C = pw.controller;
+    C.install(at);
+    if (!C._now || typeof C._now.ticks !== 'number' || typeof C._now.time !== 'number' || typeof C._advanceNow !== 'function' || typeof C._innerPause !== 'function' || typeof C._innerResume !== 'function') throw new Error('the clock source is not the controller the run expects');
+    // The monotonic clock starts where the native one stands; the origin is the wall time at its zero.
+    C._now.ticks = Math.ceil(nativeNow());
+    C._now.origin = C._now.time - C._now.ticks;
+    // The jumps: (native instant, lead) after each move of the clock.
+    const history = [{ at: nativeNow(), lead: C._now.ticks - nativeNow() }];
+    const note = () => {
+        const t = nativeNow(), lead = C._now.ticks - t, last = history[history.length - 1];
+        if (t <= last.at) last.lead = lead;
+        else if (Math.abs(last.lead - lead) >= 1) history.push({ at: t, lead });
+    };
+    const leadAt = (t) => {
+        if (!(t > history[0].at)) return history[0].lead;
+        let lo = 0, hi = history.length - 1;
+        while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (history[mid].at <= t) lo = mid; else hi = mid - 1; }
+        return history[lo].lead;
+    };
+    // (The fake's ticks are whole milliseconds: an instant within one of a
+    // move's own is the move's, never the move before.)
+    const toNative = (f) => {
+        for (let i = history.length - 1; i >= 0; i--) { const t = f - history[i].lead; if (t >= history[i].at - 1) return Math.max(t, history[i].at); }
+        return f - history[0].lead;
+    };
+    // Every running animation of the document moved by `ms` of its own time.
+    const advance = (ms) => {
+        if (!ms || !scope.document || !natives.getAnimations || !natives.animCurrent || !natives.animState) return;
+        let list;
+        try { list = natives.getAnimations.call(scope.document); } catch { return; }
+        for (const a of list) {
+            try {
+                if (natives.animState.d.get.call(a) !== 'running') continue;
+                const cur = natives.animCurrent.d.get.call(a);
+                if (typeof cur !== 'number') continue;
+                const rate = natives.animRate ? natives.animRate.d.get.call(a) : 1;
+                natives.animCurrent.d.set.call(a, cur + ms * (typeof rate === 'number' ? rate : 1));
+            } catch { /* an animation that cannot be moved stays where it is */ }
+        }
+    };
+    // What an animation frame's callback is handed: the document's native frame
+    // time plus the clock's lead now, which is what the shimmed
+    // document.timeline.currentTime reads inside the callback; the ticks where
+    // there is no timeline (a worker).
+    C._embedder.frameTime = (ticks) => {
+        try {
+            const tl = scope.document && scope.document.timeline;
+            const v = tl && natives.timeline && typeof natives.timeline.d.get === 'function' ? natives.timeline.d.get.call(tl) : null;
+            return typeof v === 'number' ? v + (C._now.ticks - nativeNow()) : ticks;
+        } catch { return ticks; }
+    };
+    const origAdvance = C._advanceNow, origPause = C._innerPause, origResume = C._innerResume;
+    // The real time of a jump flows into the clock (see above). `stamp` is the
+    // native instant the clock last counted up to while paused (whole
+    // milliseconds, as the embedder reads the clock; null while the clock flows
+    // in real time by itself), `counted` how much real time the flow put into
+    // the clock during this pause. The flow moves the clock alone, never the
+    // animations: the compositor moves those by the same real time itself.
+    const embNow = () => C._embedder.performanceNow();
+    let lostFrom = null, stamp = null, counted = 0;
+    const flow = () => {
+        if (stamp === null) return;
+        const t = embNow(), since = t - stamp;
+        if (since > 0) { stamp = t; counted += since; origAdvance.call(C, C._now.ticks + since); note(); }
+    };
+    C._embedder.flowInJump = flow;
+    // A move of the clock (not its real-time flow, which _realTime marks): the real time since the last flows first, then the animations by the rest, then the clock, then the history.
+    C._advanceNow = function (to) { if (!this._realTime) { flow(); if (to > this._now.ticks) advance(to - this._now.ticks); } const r = origAdvance.call(this, to); if (!this._realTime) note(); return r; };
+    // A jump pauses the real-time flow and resumes it after: the real time between is the clock's only as far as the flow counted it, so the rest is taken back from the animations.
+    C._innerPause = function (...a) { if (lostFrom === null) { lostFrom = nativeNow(); counted = 0; stamp = embNow(); } return origPause.apply(this, a); };
+    C._innerResume = function (...a) { stamp = null; if (lostFrom !== null) { advance(lostFrom + counted - nativeNow()); lostFrom = null; counted = 0; } const r = origResume.apply(this, a); note(); return r; };
+    return {
+        fake: { now: () => C.now(), perfNow: () => fakePerf.now(), origin: () => fakePerf.timeOrigin, leadAt, toNative },
+        jump: (op, ms) => C[op](ms),
+        controller: C,
+        history,
+    };
+}
+
+/**
+ * The site page's side of the channel (evaluated in the run's own page): posts
+ * the command into every window below it, itself included, and resolves with
+ * each window's clock and location once all have answered; the caller bounds
+ * the wait and reads `window.__clock` (the site page's own, out of the game's
+ * reach) for who did not answer.
+ */
+export function siteJump([token, op, ms]) {
+    return new Promise((resolve) => {
+        const id = Math.random().toString(36).slice(2, 12);
+        const posted = [];
+        const walk = (w) => {
+            try { w.postMessage(`${token}:clock:${op}:${id}:${ms}`, '*'); posted.push(w); } catch { /* a window that cannot be reached has no clock to move */ }
+            let n = 0;
+            try { n = w.frames.length; } catch { n = 0; }
+            for (let i = 0; i < n; i++) { try { walk(w.frames[i]); } catch { /* gone */ } }
+        };
+        const nows = [], from = [];
+        const prefix = `${token}:clockdone:${id}:`;
+        // The tally, for the run to read when a window did not answer in time.
+        const tally = { id, op, ms, posted: 0, from };
+        window.__clock = tally;
+        const done = (e) => {
+            if (typeof e.data !== 'string' || !e.data.startsWith(prefix)) return;
+            const [now, ...href] = e.data.slice(prefix.length).split(':');
+            nows.push(Number(now));
+            from.push(href.join(':'));
+            if (nows.length >= posted.length) { removeEventListener('message', done); resolve({ of: posted.length, nows, from }); }
+        };
+        addEventListener('message', done);
+        walk(window);
+        tally.posted = posted.length;
+    });
+}

package/engine-conformance/csp.go

@@ -0,0 +1,56 @@
+// Package conformance holds what the conformance run and the production servers
+// share: the engine's Content-Security-Policy headers, rendered from csp.json
+// (the one source; run.mjs renders the same file), and the endpoint browsers
+// send the policy's violation reports to.
+package conformance
+
+import (
+	_ "embed"
+	"encoding/json"
+	"strings"
+)
+
+//go:embed csp.json
+var cspJSON []byte
+
+var templates struct {
+	Bundle    string `json:"bundle"`
+	Shell     string `json:"shell"`
+	Endpoints string `json:"endpoints"`
+}
+
+func init() {
+	// The file is part of the build: a template that does not parse is a defect
+	// of the build, found by the first test, never by a player.
+	if err := json.Unmarshal(cspJSON, &templates); err != nil {
+		panic("csp.json: " + err.Error())
+	}
+}
+
+func render(template string, pairs ...string) string {
+	out := strings.NewReplacer(pairs...).Replace(template)
+	if strings.Contains(out, "{") {
+		panic("csp.json: a placeholder has no value in " + out)
+	}
+	return out
+}
+
+// BundleCSP is the policy a studio bundle is served under: origin is the
+// bundle's own ('self'), ancestors who may frame it, report where its
+// browser sends violation reports (a path on the bundle's origin).
+func BundleCSP(origin, ancestors, report string) string {
+	return render(templates.Bundle, "{origin}", origin, "{ancestors}", ancestors, "{report}", report)
+}
+
+// ShellCSP is the shell's policy: frames are the origins it may frame (the
+// bundles), ancestors who may frame it, report where its violation reports go.
+func ShellCSP(frames, ancestors, report string) string {
+	return render(templates.Shell, "{frames}", frames, "{ancestors}", ancestors, "{report}", report)
+}
+
+// ReportingEndpoints is the Reporting-Endpoints header a policy's `report-to
+// csp` names: browsers with the Reporting API deliver there, the others to
+// report-uri. Both point at the same path.
+func ReportingEndpoints(report string) string {
+	return render(templates.Endpoints, "{report}", report)
+}

package/engine-conformance/csp.json

@@ -0,0 +1,6 @@
+{
+    "about": "The two Content-Security-Policy headers of the House Engine, rendered by bundles.go, shell.go and run.mjs from this one file: {origin} is the bundle's own origin ('self' in production), {frames} the origins the shell may frame, {ancestors} who may frame the page, {report} the path browsers send violation reports to (report-to names the endpoint of the Reporting-Endpoints header, csp.go and csp.mjs render both). SPEC.md §4 explains each directive.",
+    "bundle": "sandbox allow-scripts allow-same-origin; default-src 'none'; script-src {origin} 'unsafe-inline' 'wasm-unsafe-eval'; worker-src {origin} blob:; style-src {origin} 'unsafe-inline'; img-src {origin} data: blob:; media-src {origin} data: blob:; font-src {origin} data:; connect-src {origin}; frame-src {origin}; frame-ancestors {ancestors}; base-uri 'none'; form-action 'none'; webrtc 'block'; report-uri {report}; report-to csp",
+    "shell": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; frame-src {frames}; img-src 'self' data:; frame-ancestors {ancestors}; base-uri 'none'; form-action 'none'; report-uri {report}; report-to csp",
+    "endpoints": "csp=\"{report}\""
+}

package/engine-conformance/csp.mjs

@@ -0,0 +1,20 @@
+// The engine's Content-Security-Policy headers, rendered from csp.json: the
+// one source the production servers (csp.go) render the same way, so the run
+// plays a bundle under the policy players get.
+import { readFileSync } from 'node:fs';
+
+const templates = JSON.parse(readFileSync(new URL('./csp.json', import.meta.url), 'utf8'));
+
+function render(template, values) {
+    return template.replace(/\{(\w+)\}/g, (_, key) => {
+        if (values[key] === undefined) throw new Error(`csp.json: no value for {${key}}`);
+        return values[key];
+    });
+}
+
+/** The bundle origin's policy: its own origin, who may frame it, where reports go. */
+export const bundleCSP = ({ origin, ancestors, report }) => render(templates.bundle, { origin, ancestors, report });
+/** The shell's policy: which origins it frames, who may frame it, where reports go. */
+export const shellCSP = ({ frames, ancestors, report }) => render(templates.shell, { frames, ancestors, report });
+/** The Reporting-Endpoints header that `report-to csp` names. */
+export const reportingEndpoints = (report) => render(templates.endpoints, { report });

package/engine-conformance/gzip-sizes.mjs

@@ -0,0 +1,9 @@
+// The gzip size of each file named in workerData, for scan.mjs: measured on a
+// worker thread, so a bundle at the budget's edge (seconds of compression) never
+// holds the event loop of the process that asked — the pipeline keeps answering
+// its health checks and the studio while an upload is measured.
+import { parentPort, workerData } from 'node:worker_threads';
+import { readFileSync } from 'node:fs';
+import { gzipSync } from 'node:zlib';
+
+parentPort.postMessage(workerData.map((path) => gzipSync(readFileSync(path)).length));

package/engine-conformance/package.json

@@ -0,0 +1 @@
+{ "type": "module" }