@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/visualQa/browser.js

@@ -0,0 +1,817 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_RUNTIME_URL_RE = exports.RUNTIME_FAULT_RE = void 0;
+exports.defaultExecutable = defaultExecutable;
+exports.useWindowsChrome = useWindowsChrome;
+exports.gpuArgs = gpuArgs;
+exports.installHooks = installHooks;
+exports.resetBrowserAbort = resetBrowserAbort;
+exports.abortAllBrowsers = abortAllBrowsers;
+exports.setCandidate = setCandidate;
+exports.installPlatformRuntimeCors = installPlatformRuntimeCors;
+exports.launchVqaBrowser = launchVqaBrowser;
+exports.browserName = browserName;
+exports.resetBrowserRecords = resetBrowserRecords;
+exports.renderBrowser = renderBrowser;
+exports.distinctBrowserVersions = distinctBrowserVersions;
+exports.preflightVqaBrowser = preflightVqaBrowser;
+exports.fixtureModel = fixtureModel;
+exports.padGlb = padGlb;
+exports.fixtureDigestSpoof = fixtureDigestSpoof;
+exports.rendererInfo = rendererInfo;
+exports.captureJpeg = captureJpeg;
+exports.findFrame = findFrame;
+exports.mintStorageState = mintStorageState;
+// Headless browser for visual QA. Headless ALWAYS (a visible window steals focus from whoever is at the machine),
+// a throwaway profile per run, a mock keychain so macOS never prompts, and a real GPU when one exists.
+//
+// Three hooks are installed in EVERY frame before any page script runs:
+//   1. `window.__vqa.scenes / cams / renderers` — three.js assigns `isScene` / `isPerspectiveCamera` / `isWebGLRenderer`
+//      as own properties in constructors, so an Object.prototype setter sees every instance in any bundle, minified or
+//      not, without the page exposing anything. `render()` is wrapped to learn which scene+camera is the MAIN one.
+//   2. maxTouchPoints = 0 — touch-capable hosts (Windows laptops) make worlds draw the touch HUD.
+//   3. every asset URL fetched is recorded host-side (`fetchedAssets`) as proof of WHAT was rendered.
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const hostSlots_1 = require("../browser/hostSlots");
+const nonSystemChrome_1 = require("../browser/nonSystemChrome");
+const pinnedChrome_1 = require("./pinnedChrome");
+const webgpuSelfTest_1 = require("./webgpuSelfTest");
+const candidate_1 = require("./candidate");
+/** The engine's line when a car cannot be composed (an add-on bind root absent, a vehicle material role with no host material, …). A string match, so it works before and after the engine names it. */
+exports.RUNTIME_FAULT_RE = /^\[helix-vehicle\] composition failed/i;
+/** @deprecated the gate resolves the pinned Chrome for Testing (pinnedChrome.ts); kept for callers of the old export. */
+function defaultExecutable(playwrightDefault) {
+    return (0, nonSystemChrome_1.resolveAutomationChromium)({ playwrightDefault });
+}
+/** True when the harness should drive a Windows-native Chromium over CDP (WSL: the real GPU) instead of a Linux one. */
+function useWindowsChrome() {
+    const v = process.env.HELIX_VQA_WINDOWS_CHROME;
+    if (v === '0' || v === 'false')
+        return false;
+    return v === '1' || v === 'true';
+}
+function gpuArgs(platform = process.platform) {
+    const args = [
+        '--use-mock-keychain',
+        '--password-store=basic',
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-sync',
+        '--ignore-gpu-blocklist',
+        '--enable-gpu',
+        '--autoplay-policy=no-user-gesture-required',
+        '--disable-gpu-watchdog',
+        '--touch-events=disabled',
+    ];
+    // NOT --enable-unsafe-webgpu on macOS/Windows: stable Chrome ships WebGPU on there, and the flag changes what the shader
+    // compiler accepts (measured 2026-10-03: it hides the chromium-1243 swizzle bug that breaks every lit material without
+    // it), so a gate run with it judges a browser no user has. Linux (SwiftShader) still needs it for an adapter at all.
+    if (platform === 'darwin')
+        args.push('--use-angle=metal');
+    if (platform === 'win32')
+        args.push('--use-angle=d3d11', '--force_high_performance_gpu', '--enable-gpu-rasterization', '--enable-features=WebGPU,Vulkan');
+    if (platform === 'linux')
+        args.push('--enable-unsafe-webgpu', ...(process.env.HELIX_VQA_LINUX_GL ?? '--use-angle=swiftshader --enable-unsafe-swiftshader').split(' '));
+    return args;
+}
+/** Page-side hook source. Plain function so Playwright serialises it; runs before any page script in every frame. */
+function installHooks() {
+    const w = window;
+    if (w.__vqa)
+        return;
+    const H = {
+        scenes: [], cams: [], renderers: [], uses: new Map(), main: null, scene: null, frames: 0, draws: new Map(),
+    };
+    w.__vqa = H;
+    try {
+        Object.defineProperty(Navigator.prototype, 'maxTouchPoints', { get: () => 0, configurable: true });
+    }
+    catch { /* best effort */ }
+    const wrapRenderer = (r) => {
+        if (r.__vqaWrapped)
+            return;
+        r.__vqaWrapped = true;
+        for (const fn of ['render', 'renderAsync']) {
+            // Defer: the method is defined on the prototype, so wrap on the instance once construction finishes.
+            queueMicrotask(() => {
+                const orig = r[fn];
+                if (typeof orig !== 'function')
+                    return;
+                r[fn] = function (scene, camera) {
+                    try {
+                        if (scene?.isScene && camera?.isCamera) {
+                            H.uses.set(camera, (H.uses.get(camera) ?? 0) + 1);
+                            H.frames++;
+                            const best = [...H.uses.entries()].sort((a, b) => b[1] - a[1])[0];
+                            if (best && best[0] === camera) {
+                                H.main = camera;
+                                H.scene = scene;
+                            }
+                        }
+                    }
+                    catch { /* never break the page */ }
+                    // Observe only completed draws to this renderer's canvas, never offscreen shadow/environment passes.
+                    let target;
+                    try {
+                        target = typeof r.getRenderTarget === 'function' ? r.getRenderTarget() : undefined;
+                    }
+                    catch { /* leave this draw unproven */ }
+                    const drawFrame = H.frames;
+                    const record = () => {
+                        try {
+                            const c = camera;
+                            if (target !== null || !scene?.isScene || !camera?.isCamera || !r.domElement)
+                                return;
+                            const e = c.matrixWorld.elements;
+                            H.draws.set(r, { renderer: r, canvas: r.domElement, scene, camera, frame: drawFrame,
+                                projection: camera.projectionMatrix.elements.slice(),
+                                worldMatrix: e.slice(), zoom: camera.zoom, view: !!camera.view?.enabled,
+                                pos: c.position.toArray(), matrixWorld: [e[12], e[13], e[14]], direction: [-e[8], -e[9], -e[10]], up: c.up.toArray() });
+                        }
+                        catch { /* never change the surface's render */ }
+                    };
+                    // A later canvas attempt can clear or partially paint before throwing: the previous success is no longer proof.
+                    if (target == null)
+                        H.draws.delete(r);
+                    // eslint-disable-next-line prefer-rest-params
+                    const returned = orig.apply(this, arguments);
+                    // Async completion has no proven drawing boundary: camera state can change while the Promise is pending.
+                    // Keep its exact return value, but never certify that call from mutable state in a later reaction.
+                    if (returned && typeof returned.then === 'function') {
+                        if (target === null)
+                            H.draws.delete(r);
+                    }
+                    else
+                        record();
+                    return returned;
+                };
+            });
+        }
+    };
+    const mk = (name, bucket) => {
+        Object.defineProperty(Object.prototype, name, {
+            configurable: true,
+            enumerable: false,
+            set(v) {
+                try {
+                    Object.defineProperty(this, name, { value: v, writable: true, configurable: true, enumerable: true });
+                    if (v && !H[bucket].includes(this)) {
+                        H[bucket].push(this);
+                        if (bucket === 'renderers')
+                            wrapRenderer(this);
+                    }
+                }
+                catch { /* ignore */ }
+            },
+            get() { return undefined; },
+        });
+    };
+    mk('isScene', 'scenes');
+    mk('isPerspectiveCamera', 'cams');
+    mk('isWebGLRenderer', 'renderers');
+    mk('isWebGPURenderer', 'renderers');
+    // AUDIO: every AudioContext the page makes, and every non-finite value written to an AudioParam. R34 1.0.9's missing
+    // audio mix fields became NaN, `setValueAtTime(NaN)` threw inside the World's frame loop and froze the car; the vehicle
+    // drive check (vehicleDriveAlive.ts) reads these to require the audio graph running and NaN-free. Recorded, then passed
+    // through unchanged: the browser still throws exactly as it would have.
+    const A = { contexts: [], nonFinite: [], nonFiniteCount: 0, writes: 0 };
+    w.__vqaAudio = A;
+    const g = window;
+    const Ctx = g.AudioContext;
+    if (typeof Ctx === 'function') {
+        const Wrapped = function (...args) { const c = Reflect.construct(Ctx, args, new.target ?? Wrapped); A.contexts.push(c); return c; };
+        Wrapped.prototype = Ctx.prototype;
+        Object.setPrototypeOf(Wrapped, Ctx);
+        g.AudioContext = Wrapped;
+    }
+    const AP = g.AudioParam?.prototype;
+    if (AP) {
+        const note = (method, v) => {
+            A.writes++;
+            if (typeof v !== 'number' || Number.isFinite(v))
+                return;
+            A.nonFiniteCount++;
+            if (A.nonFinite.length < 20)
+                A.nonFinite.push({ method, value: String(v) });
+        };
+        for (const m of ['setValueAtTime', 'linearRampToValueAtTime', 'exponentialRampToValueAtTime', 'setTargetAtTime']) {
+            const orig = AP[m];
+            if (typeof orig !== 'function')
+                continue;
+            AP[m] = function (...args) {
+                // HELIX_VQA_FAULT_AUDIO_NAN (debug proof of the drive check): once armed, every write carries NaN, as R34 1.0.9's
+                // missing gain did — the browser then throws exactly where the engine's own write would have.
+                if (A.injectNaN)
+                    args[0] = NaN;
+                note(m, args[0]);
+                return orig.apply(this, args);
+            };
+        }
+        const d = Object.getOwnPropertyDescriptor(AP, 'value');
+        if (d?.set && d.configurable) {
+            Object.defineProperty(AP, 'value', { ...d, set(v) { note('value', v); d.set.call(this, v); } });
+        }
+    }
+}
+const ASSET_RE = /\.(glb|gltf|ktx2|bin|usdz)(\?|$)|\/assets\/|\/continuum\/(public\/)?objects\/|\/content\/sha256\/|\/cas\/|sha256[:/][0-9a-f]{64}/i;
+/** A browser we did not start: `HELIX_VQA_CDP_URL` names a headless Chromium that is already listening (a GPU host). */
+async function connectRemote(cdpUrl, opts, dispose, source) {
+    const { chromium } = await Promise.resolve().then(() => __importStar(require('playwright')));
+    const browser = await chromium.connectOverCDP(cdpUrl);
+    let ctx;
+    try {
+        ctx = await browser.newContext({ viewport: { width: opts.width ?? 1440, height: opts.height ?? 900 }, serviceWorkers: 'block' });
+        const page = await ctx.newPage();
+        const context = ctx;
+        return { ctx: context, page, source, dispose: async () => { try {
+                await context.close();
+            }
+            finally {
+                try {
+                    await browser.close();
+                }
+                finally {
+                    await dispose();
+                }
+            } } };
+    }
+    catch (e) {
+        try {
+            await ctx?.close();
+        }
+        finally {
+            try {
+                await browser.close();
+            }
+            finally {
+                await dispose();
+            }
+        }
+        throw e;
+    }
+}
+async function openSession(opts, signal) {
+    const cdp = process.env.HELIX_VQA_CDP_URL;
+    if (cdp)
+        return connectRemote(cdp, opts, async () => undefined, { executablePath: null, channel: 'remote-cdp' });
+    if (useWindowsChrome()) {
+        const { launchWindowsChrome } = await Promise.resolve().then(() => __importStar(require('./winChrome')));
+        const win = await launchWindowsChrome({ args: gpuArgs('win32') });
+        try {
+            return await connectRemote(win.cdpUrl, opts, () => win.kill(), { executablePath: win.executablePath, channel: win.channel });
+        }
+        catch (e) {
+            await win.kill();
+            throw e;
+        }
+    }
+    const { chromium } = await Promise.resolve().then(() => __importStar(require('playwright')));
+    // Validate/resolve before admission and before allocating the profile.
+    (0, nonSystemChrome_1.assertNotSystemChrome)(opts.executablePath);
+    // The pinned current-stable Chrome for Testing (installed on first use), never Playwright's bundled pre-stable build.
+    const resolved = await (0, pinnedChrome_1.resolveVqaExecutable)({ explicit: opts.executablePath, log: (m) => console.error(`[visual-qa] ${m}`) });
+    (0, nonSystemChrome_1.assertNotSystemChrome)(resolved.executablePath);
+    const executablePath = resolved.executablePath;
+    let profile;
+    let ctx;
+    // Chromium can still be flushing its profile when 'close' fires (ENOTEMPTY on macOS): retry, and never throw from the
+    // close handler — an exception there kills the whole run after the render already finished.
+    const removeProfile = () => {
+        if (!profile)
+            return;
+        try {
+            node_fs_1.default.rmSync(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+        }
+        catch { /* the OS temp reaper owns a leftover */ }
+    };
+    try {
+        profile = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'helix-vqa-'));
+        const profilePath = profile;
+        ctx = await (0, hostSlots_1.launchWithBrowserSlot)(async () => {
+            ctx = await chromium.launchPersistentContext(profilePath, {
+                headless: true,
+                viewport: { width: opts.width ?? 1440, height: opts.height ?? 900 },
+                serviceWorkers: 'block', args: gpuArgs(), ignoreDefaultArgs: ['--disable-gpu'],
+                executablePath, userAgent: undefined,
+            });
+            ctx.once('close', removeProfile);
+            return ctx;
+        }, 'close', { signal, identity: profilePath });
+        const context = ctx;
+        const page = context.pages()[0] ?? (await context.newPage());
+        return { ctx: context, page, source: { executablePath, channel: resolved.channel }, dispose: async () => { await context.close(); removeProfile(); } };
+    }
+    catch (e) {
+        // Close rejection retains its lease and profile while Chromium may still be alive.
+        if (ctx)
+            await ctx.close();
+        removeProfile();
+        throw e;
+    }
+}
+// Each render generation keeps its own signal, including in-flight admission and
+// launches. Resetting for a later render cannot resurrect an earlier aborted one.
+const openSessions = new Set();
+let renderAbort = new AbortController();
+function resetBrowserAbort() { renderAbort = new AbortController(); }
+async function abortAllBrowsers() {
+    renderAbort.abort();
+    await Promise.all([...openSessions].map(async (s) => { try {
+        await s.dispose();
+        openSessions.delete(s);
+    }
+    catch { /* retain for a subsequent close attempt */ } }));
+}
+// Candidate version (`--package-version`): set by command.ts around the render route, so every browser the route opens
+// asks the backend for the candidate instead of the item's current pin. Module-level because the routes own their
+// browsers and must not need to know (see candidate.ts for the two rewrites).
+let candidate = null;
+function setCandidate(config) { candidate = config; }
+/** Response headers for a fulfilled cross-origin API call: the shell calls the API from another origin with credentials,
+ *  so the browser still applies CORS to what we hand back. Keep the API's own answer; fill it in only if absent. */
+function corsSafe(headers, origin) {
+    const out = { ...headers };
+    delete out['content-length'];
+    if (origin && !out['access-control-allow-origin']) {
+        out['access-control-allow-origin'] = origin;
+        out['access-control-allow-credentials'] = 'true';
+    }
+    return out;
+}
+/** The site serves the platform runtime's addons through a cross-origin redirect (`/api/platform-runtime/<pkg>/<file>` -> backend
+ *  -> CDN). A browser with ANY request interception on refuses that redirect chain for lack of an `Access-Control-Allow-Origin`
+ *  header on the first hop (the backend answers `null`), and the page dies with "Something went wrong" before the avatar or
+ *  car is ever presented. Windows Chrome over CDP on the hosted runner hit it for every candidate (version-move) render. */
+exports.PLATFORM_RUNTIME_URL_RE = /\/api\/platform-runtime\/[^/]+\/[^/?]+\.js(\?.*)?$/;
+/** Fetch the platform runtime's scripts in Node (redirects followed there) and hand them back with the header. Install it
+ *  on every context that intercepts requests. */
+async function installPlatformRuntimeCors(ctx) {
+    await ctx.route(exports.PLATFORM_RUNTIME_URL_RE, async (route) => {
+        try {
+            const r = await route.fetch();
+            await route.fulfill({ response: r, headers: { ...r.headers(), 'access-control-allow-origin': '*' } });
+        }
+        catch {
+            await route.continue().catch(() => undefined);
+        }
+    });
+}
+async function installCandidateRoutes(ctx, cand) {
+    await installPlatformRuntimeCors(ctx);
+    if (cand.trial) {
+        await ctx.route(candidate_1.SESSION_URL_RE, async (route) => {
+            const req = route.request();
+            const body = req.method() === 'POST' ? (0, candidate_1.patchSessionBody)(req.postData(), cand) : null;
+            if (body === null) {
+                await route.fallback();
+                return;
+            }
+            // Fetch + fulfil (rather than continue) so `trial.candidate` is bound to the identity BEFORE the page, and so the
+            // runtime, ever sees the session: the vehicle route compares the served checksum against it later.
+            try {
+                const headers = await req.allHeaders();
+                const resp = await route.fetch({ postData: body, headers: { ...headers, 'content-type': 'application/json' } });
+                const text = await resp.text();
+                let json = null;
+                try {
+                    json = JSON.parse(text);
+                }
+                catch { /* not JSON: reported as no candidate */ }
+                cand.onCandidate?.(resp.ok() ? (0, candidate_1.candidateFromSessionResponse)(json) : null, resp.ok() ? json : { status: resp.status(), body: text.slice(0, 400) });
+                await route.fulfill({ status: resp.status(), headers: corsSafe(resp.headers(), headers.origin), body: text });
+            }
+            catch (e) {
+                cand.onCandidate?.(null, { error: String(e?.message ?? e).slice(0, 300) });
+                await route.abort().catch(() => undefined);
+            }
+        });
+    }
+    if (cand.previewAddOns || cand.previewItem) {
+        const preview = (kind, re, rewrite) => ctx.route(re, async (route) => {
+            const req = route.request();
+            if (req.method() !== 'GET') {
+                await route.fallback();
+                return;
+            }
+            const headers = await req.allHeaders();
+            let frameUrl = '';
+            try {
+                frameUrl = req.frame().url();
+            }
+            catch { /* service-worker requests have no trusted frame */ }
+            if (kind === 'item' && !(0, candidate_1.candidateItemOriginAllowed)(req.url(), frameUrl, headers.origin, headers.referer, cand)) {
+                cand.onPreview?.('item', req.url(), false, { error: 'candidate item read used an untrusted API or page origin' });
+                await route.abort();
+                return;
+            }
+            const url = rewrite(req.url());
+            try {
+                const authorized = kind === 'item' && cand.token && !headers.authorization ? { ...headers, authorization: `Bearer ${cand.token}` } : headers;
+                const resp = await route.fetch({ url, headers: authorized, maxRedirects: kind === 'item' && cand.token ? 0 : undefined });
+                const text = await resp.text();
+                let json = null;
+                try {
+                    json = JSON.parse(text);
+                }
+                catch { /* reported by the caller */ }
+                cand.onPreview?.(kind, url, resp.ok(), resp.ok() ? json : { status: resp.status(), body: text.slice(0, 400) });
+                await route.fulfill({ status: resp.status(), headers: corsSafe(resp.headers(), headers.origin), body: text });
+            }
+            catch (e) {
+                cand.onPreview?.(kind, url, false, { error: String(e?.message ?? e).slice(0, 300) });
+                await route.abort().catch(() => undefined);
+            }
+        });
+        if (cand.previewAddOns)
+            await preview('add-ons', candidate_1.ADD_ONS_URL_RE, (u) => (0, candidate_1.addPreviewParams)(u, cand));
+        if (cand.previewItem)
+            await preview('item', (0, candidate_1.itemUrlRe)(cand.itemId), (u) => (0, candidate_1.addItemPreviewParam)(u, cand));
+        // An account that OWNS the add-on (its creator, always) gets the card from its inventory, whose row names the
+        // current pin: swap that pin for the candidate's so the viewport resolves the candidate's bytes.
+        const pin = cand.pin;
+        if (cand.previewAddOns && pin) {
+            await ctx.route(candidate_1.INVENTORY_URL_RE, async (route) => {
+                const req = route.request();
+                if (req.method() !== 'GET') {
+                    await route.fallback();
+                    return;
+                }
+                try {
+                    const headers = await req.allHeaders();
+                    const resp = await route.fetch({ headers });
+                    const text = await resp.text();
+                    let body = text;
+                    if (resp.ok()) {
+                        try {
+                            const json = JSON.parse(text);
+                            const r = (0, candidate_1.rewriteCandidatePins)(json, cand.itemId, pin);
+                            if (r.replaced)
+                                body = JSON.stringify(json);
+                            cand.onPreview?.('inventory', req.url(), true, { replaced: r.replaced, from: r.from });
+                        }
+                        catch { /* not JSON: leave it */ }
+                    }
+                    await route.fulfill({ status: resp.status(), headers: corsSafe(resp.headers(), headers.origin), body });
+                }
+                catch (e) {
+                    cand.onPreview?.('inventory', req.url(), false, { error: String(e?.message ?? e).slice(0, 300) });
+                    await route.abort().catch(() => undefined);
+                }
+            });
+        }
+    }
+}
+async function launchVqaBrowser(opts = {}) {
+    const signal = renderAbort.signal;
+    const checkAbort = () => { if (signal.aborted)
+        throw new Error('visual-qa render was aborted (watchdog)'); };
+    checkAbort();
+    const session = await openSession(opts, signal);
+    const dispose = session.dispose.bind(session);
+    let disposed = false;
+    let disposing;
+    session.dispose = () => {
+        if (disposed)
+            return Promise.resolve();
+        return disposing ??= dispose().then(() => { disposed = true; openSessions.delete(session); }).finally(() => { disposing = undefined; });
+    };
+    try {
+        checkAbort();
+        openSessions.add(session);
+        const { ctx, page } = session;
+        const info = await identifyBrowser(session);
+        if (opts.purpose !== 'session') {
+            const decision = await runSelfTest(page, info);
+            recordBrowser(info, opts.purpose ?? 'render');
+            if (!decision.ok)
+                throw new Error(decision.error);
+        }
+        else {
+            info.webgpu = { status: 'skipped', selfTest: 'skipped' };
+            recordBrowser(info, 'session');
+        }
+        checkAbort();
+        await ctx.addInitScript(installHooks);
+        if (candidate)
+            await installCandidateRoutes(ctx, candidate);
+        const fixture = fixtureModel();
+        if (fixture) {
+            await installPlatformRuntimeCors(ctx);
+            // Gate-proof harness only (see fixtureModel): the pinned model's bytes are answered with a local broken file.
+            // The Marketplace item page (avatar@3 preview) SHA-256-verifies the model against its manifest and checks its byte
+            // count: the fixture is padded to the pinned model's length with a trailing unknown-type GLB chunk (glTF 2.0
+            // loaders ignore unknown chunks), and the page's digest of the fixture bytes reports the pinned hash.
+            const raw = node_fs_1.default.readFileSync(fixture.file);
+            // (the GLB header's total-length field changes with the padding, so the match starts after the 12-byte header)
+            await ctx.addInitScript(fixtureDigestSpoof, { prefix: raw.subarray(12, 268).toString('hex'), hex: fixture.hex });
+            await ctx.route((u) => u.href.includes(fixture.hex), async (route) => {
+                let body = raw;
+                try {
+                    const orig = await route.fetch();
+                    body = padGlb(raw, (await orig.body()).length);
+                }
+                catch { /* serve unpadded */ }
+                await route.fulfill({ status: 200, body, headers: { 'content-type': 'model/gltf-binary', 'access-control-allow-origin': '*' } });
+            });
+        }
+        const fetchedAssets = [];
+        const pageErrors = [];
+        ctx.on('request', (req) => {
+            const u = req.url();
+            if (ASSET_RE.test(u) && !fetchedAssets.includes(u))
+                fetchedAssets.push(u);
+        });
+        page.on('pageerror', (e) => { if (pageErrors.length < 50)
+            pageErrors.push(String(e?.message ?? e).slice(0, 300)); });
+        const runtimeFaults = [];
+        page.on('console', (m) => {
+            if (m.type() !== 'error' || runtimeFaults.length >= 20)
+                return;
+            const text = m.text();
+            if (exports.RUNTIME_FAULT_RE.test(text))
+                runtimeFaults.push(text.slice(0, 600));
+        });
+        if (opts.storageState) {
+            const s = JSON.parse(node_fs_1.default.readFileSync(opts.storageState, 'utf8'));
+            if (s.cookies?.length)
+                await ctx.addCookies(s.cookies);
+            for (const origin of s.origins ?? []) {
+                if (!origin.localStorage?.length)
+                    continue;
+                await page.goto(origin.origin, { waitUntil: 'domcontentloaded' }).catch(() => undefined);
+                await page.evaluate((items) => { for (const it of items)
+                    localStorage.setItem(it.name, it.value); }, origin.localStorage).catch(() => undefined);
+            }
+        }
+        page.setDefaultTimeout(60_000);
+        checkAbort();
+        return { ctx, page, fetchedAssets, pageErrors, runtimeFaults, info, close: () => session.dispose() };
+    }
+    catch (e) {
+        await session.dispose();
+        throw e;
+    }
+}
+/** Display name of a build, from where it lives: Playwright's bundled pre-stable build is named as such so a bundle
+ *  rendered on it can never be mistaken for the pinned stable one. */
+function browserName(executablePath, product) {
+    const p = executablePath ?? '';
+    const pw = /ms-playwright[\\/](chromium(?:_headless_shell)?-\d+)/i.exec(p);
+    if (pw)
+        return `Playwright Chromium (${pw[1]})`;
+    if (/Google Chrome for Testing|[\\/]vqa-chrome[\\/]|chrome-(win64|linux64)[\\/]/i.test(p))
+        return 'Chrome for Testing';
+    return product?.split('/')[0] || 'Chromium';
+}
+async function identifyBrowser(session) {
+    let product = null;
+    let userAgent = null;
+    try {
+        const cdp = await session.ctx.newCDPSession(session.page);
+        const v = (await cdp.send('Browser.getVersion'));
+        product = v.product ?? null;
+        userAgent = v.userAgent ?? null;
+        await cdp.detach().catch(() => undefined);
+    }
+    catch { /* recorded as unknown */ }
+    const version = product ? (/(\d+\.\d+\.\d+\.\d+)/.exec(product)?.[1] ?? null) : null;
+    return { name: browserName(session.source.executablePath, product), version, executablePath: session.source.executablePath, channel: session.source.channel, userAgent };
+}
+/** A secure origin the self-test page is served from (WebGPU is secure-context only; about:blank is not one). */
+const SELFTEST_URL = 'https://vqa-selftest.helix.invalid/';
+async function runSelfTest(page, info) {
+    let result = null;
+    try {
+        await page.route(SELFTEST_URL, (route) => route.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html><title>visual-qa WebGPU self-test</title>' }));
+        try {
+            await page.goto(SELFTEST_URL, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+            result = (await page.evaluate(webgpuSelfTest_1.webGpuSelfTestProbe, webgpuSelfTest_1.SELFTEST_SOURCES));
+        }
+        finally {
+            await page.unroute(SELFTEST_URL).catch(() => undefined);
+        }
+    }
+    catch (e) {
+        result = { webgpu: 'error', reason: `self-test page failed: ${String(e?.message ?? e).slice(0, 200)}` };
+    }
+    const decision = (0, webgpuSelfTest_1.decideSelfTest)(result, info, { requireWebGpu: true });
+    info.webgpu = {
+        status: result?.webgpu ?? 'error',
+        adapter: result?.adapter ?? null,
+        selfTest: decision.ok ? 'pass' : 'fail',
+        ...(decision.ok ? (decision.note ? { detail: decision.note } : {}) : { detail: decision.error.slice(0, 500) }),
+        ...(result?.ms !== undefined ? { ms: result.ms } : {}),
+    };
+    return decision;
+}
+// Every browser a render opened, in order (reset per render by runVisualQa). The bundle records the first render browser.
+const records = [];
+function recordBrowser(info, purpose) { if (records.length < 50)
+    records.push({ ...info, purpose }); }
+function resetBrowserRecords() { records.length = 0; }
+/** The browser that drew this render: the first render launch, else the first launch of any kind, else null. */
+function renderBrowser() {
+    const r = records.find((x) => x.purpose === 'render') ?? records[0];
+    if (!r)
+        return null;
+    const { purpose: _p, ...info } = r;
+    void _p;
+    return info;
+}
+/** Distinct builds this render launched (normally one). */
+function distinctBrowserVersions() { return [...new Set(records.map((r) => `${r.name} ${r.version ?? '?'}`))]; }
+/**
+ * Launch, self-test and close one browser — the hosted worker's preflight, so a host on a broken build refuses to
+ * claim jobs at all instead of burning each job's attempts on harness errors.
+ */
+async function preflightVqaBrowser(opts = {}) {
+    const b = await launchVqaBrowser({ executablePath: opts.executablePath });
+    try {
+        return b.info;
+    }
+    finally {
+        await b.close();
+    }
+}
+/**
+ * `HELIX_VQA_FIXTURE_MODEL=<sha256 hex>=<path to .glb>`: answer every request for that content hash with a local file, so a
+ * deliberately broken fixture (an emissive wash-out, a twisted bone roll, torn skin weights) is drawn by the REAL runtime
+ * through the real route. A run with a fixture always carries a harness error, so its verdict is `error` and it can never
+ * be submitted as a pass (`runVisualQa` adds the error); it exists to prove that each assert fails on what it claims to catch.
+ */
+function fixtureModel(env = process.env) {
+    const v = env.HELIX_VQA_FIXTURE_MODEL;
+    if (!v)
+        return null;
+    const m = /^([0-9a-f]{64})=(.+)$/.exec(v.trim());
+    if (!m)
+        throw new Error('HELIX_VQA_FIXTURE_MODEL must be <sha256 hex>=<path to .glb>');
+    if (!node_fs_1.default.existsSync(m[2]))
+        throw new Error(`HELIX_VQA_FIXTURE_MODEL: ${m[2]} does not exist`);
+    return { hex: m[1], file: m[2] };
+}
+/** Pad a GLB to exactly `length` bytes with a trailing unknown-type chunk; unchanged when it cannot fit. */
+function padGlb(glb, length) {
+    const padLen = length - glb.length - 8;
+    if (padLen < 0 || padLen % 4 || glb.length < 12 || glb.readUInt32LE(0) !== 0x46546c67)
+        return glb;
+    const pad = Buffer.alloc(8 + padLen);
+    pad.writeUInt32LE(padLen, 0);
+    pad.write('PADX', 4, 'latin1');
+    const out = Buffer.concat([glb, pad]);
+    out.writeUInt32LE(out.length, 8);
+    return out;
+}
+/** Page-side (fixture runs only): a digest of bytes that begin like the fixture (after the GLB header) reports the pinned model's hash. */
+function fixtureDigestSpoof(arg) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle || subtle.__vqaFixture)
+        return;
+    const orig = subtle.digest.bind(subtle);
+    subtle.__vqaFixture = true;
+    const want = new Uint8Array(arg.hex.match(/../g).map((h) => parseInt(h, 16)));
+    subtle.digest = async (alg, data) => {
+        const out = await orig(alg, data);
+        try {
+            const u8 = ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+            if (u8.length >= 268) {
+                let hex = '';
+                for (let i = 12; i < 268; i++)
+                    hex += u8[i].toString(16).padStart(2, '0');
+                if (hex === arg.prefix)
+                    return want.buffer.slice(0);
+            }
+        }
+        catch { /* fall through */ }
+        return out;
+    };
+}
+/** The renderer string actually in use (never inferred from flags). */
+async function rendererInfo(page) {
+    return page.evaluate(async () => {
+        const parts = [];
+        try {
+            const c = document.createElement('canvas');
+            const gl = c.getContext('webgl2');
+            const ext = gl?.getExtension('WEBGL_debug_renderer_info');
+            if (gl && ext)
+                parts.push(`webgl2:${String(gl.getParameter(ext.UNMASKED_RENDERER_WEBGL))}`);
+        }
+        catch { /* none */ }
+        try {
+            const gpu = navigator.gpu;
+            const a = gpu ? await gpu.requestAdapter() : null;
+            parts.push(a ? `webgpu:${a.info?.vendor ?? '?'}/${a.info?.architecture ?? '?'}` : 'webgpu:none');
+        }
+        catch {
+            parts.push('webgpu:error');
+        }
+        return parts.join(' | ') || null;
+    }).catch(() => null);
+}
+/** JPEG screenshot of the viewport (or a frame's element) after letting `settleMs` of frames render. */
+async function captureJpeg(page, file, settleMs = 400) {
+    await page.waitForTimeout(settleMs);
+    const buf = await page.screenshot({ type: 'jpeg', quality: 82 });
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    node_fs_1.default.writeFileSync(file, buf);
+    const vp = page.viewportSize() ?? { width: 1440, height: 900 };
+    return { width: vp.width, height: vp.height };
+}
+/** Find the first frame (main or iframe) where `probe` returns truthy. */
+async function findFrame(page, probe, timeoutMs = 90_000) {
+    const t0 = Date.now();
+    while (Date.now() - t0 < timeoutMs) {
+        for (const f of page.frames()) {
+            const ok = await f.evaluate(probe).catch(() => false);
+            if (ok)
+                return f;
+        }
+        await page.waitForTimeout(750);
+    }
+    throw new Error('no frame satisfied the probe');
+}
+/**
+ * Sign a throwaway headless browser in as the CLI's own user and save its storage state, so the harness renders as
+ * the publisher — who owns the item being judged, which the customiser needs for anything not yet listed. Uses the
+ * website's `sso-tokens` provider, which validates the bearer server-side against /users/me (a forged token never
+ * makes a session). Returns the username the session resolved to.
+ */
+async function mintStorageState(webBase, accessToken, file, executablePath) {
+    // The website's sign-in is occasionally refused on the first try (measured ~1 in 5 on a cold Windows Chrome: the callback
+    // answers but /api/auth/session still has no user). A fresh browser and a short pause fixes it, so retry a few times.
+    let last = '';
+    for (let attempt = 1; attempt <= 4; attempt++) {
+        try {
+            return await mintOnce(webBase, accessToken, file, executablePath);
+        }
+        catch (e) {
+            last = String(e?.message ?? e);
+            if (!/could not sign the harness browser in/.test(last))
+                throw e;
+            await new Promise((r) => setTimeout(r, 1500 * attempt));
+        }
+    }
+    throw new Error(last);
+}
+async function mintOnce(webBase, accessToken, file, executablePath) {
+    const b = await launchVqaBrowser({ executablePath, purpose: 'session' });
+    try {
+        const origin = webBase.replace(/\/$/, '');
+        await b.page.goto(`${origin}/`, { waitUntil: 'domcontentloaded' });
+        const result = await b.page.evaluate(async ({ token }) => {
+            const csrf = (await (await fetch('/api/auth/csrf')).json());
+            const body = new URLSearchParams({ csrfToken: csrf.csrfToken, access_token: token, expires_in: String(12 * 3600), json: 'true', callbackUrl: '/' });
+            const res = await fetch('/api/auth/callback/sso-tokens', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body, redirect: 'manual' });
+            const session = (await (await fetch('/api/auth/session')).json());
+            return { status: res.status, user: session?.user?.username ?? session?.user?.name ?? null };
+        }, { token: accessToken });
+        if (!result.user)
+            throw new Error(`could not sign the harness browser in with the CLI login (callback ${result.status}); pass --storage-state instead`);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+        await b.ctx.storageState({ path: file });
+        return result.user;
+    }
+    finally {
+        await b.close();
+    }
+}
+//# sourceMappingURL=browser.js.map