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

package/dist/visualQa/avatarProbe.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTALL_AVATAR_PROBE = void 0;
+// Page-side probe for the avatar render route. Installed into the test-grounds world frame as `globalThis.__vqaAv`.
+// Plain JavaScript in a string so nothing the TypeScript compiler emits can leak into the page.
+//
+// The local player of a Try Now trial IS the item: `__assetGym.mp.local.model` is the avatar's drawn Group (LOD scenes,
+// skinned meshes, skeleton), standing on the test grounds' floor with its origin at the character's ground plane.
+// Everything is read in the BODY frame — origin at the model's ground point, +Z where the engine says the character
+// faces, +Y up, +X the character's left — so a camera pose means the same thing whatever the heading.
+exports.INSTALL_AVATAR_PROBE = `(() => {
+  const G = globalThis;
+  if (G.__vqaAv) return true;
+  const A = {};
+  A.mp = () => G.__assetGym.mp;
+  A.model = () => A.mp().local.model;
+  A.V = () => A.model().position.constructor;
+  A.Q = () => A.model().quaternion.constructor;
+  A.camera = () => A.mp().local.services.camera.camera;
+  A.visible = (o, root) => { for (let p = o; p; p = p.parent) { if (p.visible === false) return false; if (p === root) break; } return true; };
+  A.bone = (name) => { let r = null; A.model().traverse((o) => { if (!r && o.isBone && o.name === name) r = o; }); return r; };
+  /** Body frame: engine forward = the model's local +Z, flattened to the ground. */
+  A.basis = () => {
+    const m = A.model(); m.updateMatrixWorld(true);
+    const V = A.V(), Q = A.Q();
+    const q = m.getWorldQuaternion(new Q());
+    const f = new V(0, 0, 1).applyQuaternion(q); f.y = 0;
+    if (f.length() < 1e-6) f.set(0, 0, 1);
+    f.normalize();
+    const up = new V(0, 1, 0);
+    const l = new V().crossVectors(up, f).normalize();
+    const o = m.getWorldPosition(new V());
+    return { o, f, l, up };
+  };
+  A.toBody = (w, B) => { B = B || A.basis(); const V = A.V(); const d = new V(w.x - B.o.x, w.y - B.o.y, w.z - B.o.z); return [d.dot(B.l), d.y, d.dot(B.f)]; };
+  A.toWorld = (p, B) => { B = B || A.basis(); const V = A.V(); return new V(B.o.x + B.l.x * p[0] + B.f.x * p[2], B.o.y + p[1], B.o.z + B.l.z * p[0] + B.f.z * p[2]); };
+  A.bonesBody = (names) => {
+    const out = {}; const B = A.basis(); const V = A.V();
+    for (const n of names) { const b = A.bone(n); if (b) out[n] = A.toBody(b.getWorldPosition(new V()), B).map((v) => Math.round(v * 10000) / 10000); }
+    return out;
+  };
+  /** Drawn vertices of the model in BODY frame (skinned vertices are posed), at most ~maxN, flat. */
+  A.points = (maxN) => {
+    const m = A.model(); m.updateMatrixWorld(true);
+    const B = A.basis(); const V = A.V(); const tmp = new V();
+    const meshes = [];
+    let total = 0;
+    m.traverse((o) => {
+      if (!o.isMesh || !o.geometry || !o.geometry.attributes || !o.geometry.attributes.position) return;
+      if (!A.visible(o, m)) return;
+      const ms = Array.isArray(o.material) ? o.material : [o.material];
+      if (ms.every((x) => !x || x.visible === false || (x.transparent && (x.opacity ?? 1) < 0.02) || x.colorWrite === false)) return;
+      meshes.push(o); total += o.geometry.attributes.position.count;
+    });
+    const step = Math.max(1, Math.floor(total / (maxN || 60000)));
+    const out = [];
+    for (const o of meshes) {
+      if (o.isSkinnedMesh && o.skeleton) o.skeleton.update();
+      const pos = o.geometry.attributes.position; const e = o.matrixWorld.elements;
+      const skinned = o.isSkinnedMesh && typeof o.getVertexPosition === 'function';
+      for (let i = 0; i < pos.count; i += step) {
+        let x, y, z;
+        if (skinned) { o.getVertexPosition(i, tmp); x = tmp.x; y = tmp.y; z = tmp.z; } else { x = pos.getX(i); y = pos.getY(i); z = pos.getZ(i); }
+        if (!Number.isFinite(x + y + z)) continue;
+        const wx = e[0] * x + e[4] * y + e[8] * z + e[12], wy = e[1] * x + e[5] * y + e[9] * z + e[13], wz = e[2] * x + e[6] * y + e[10] * z + e[14];
+        const dx = wx - B.o.x, dy = wy - B.o.y, dz = wz - B.o.z;
+        out.push(dx * B.l.x + dz * B.l.z, dy, dx * B.f.x + dz * B.f.z);
+      }
+    }
+    return out;
+  };
+  /** What the avatar is made of, for the facts block: meshes by LOD, skeleton size, materials. */
+  A.describe = () => {
+    const m = A.model(); const out = { root: m.name, skinned: [], bones: 0, lod: null, helixBodyHeight: m.userData && m.userData.helixBodyHeight || null, helixFace: !!(m.userData && m.userData.helixFace) };
+    m.traverse((o) => {
+      if (o.isBone) out.bones++;
+      if (o.isSkinnedMesh) {
+        const ms = Array.isArray(o.material) ? o.material : [o.material]; const mt = ms[0] || {};
+        out.skinned.push({ name: o.name, verts: o.geometry.attributes.position.count, visible: A.visible(o, m), bones: o.skeleton ? o.skeleton.bones.length : 0,
+          material: { type: mt.type, name: mt.name, map: !!mt.map, normalMap: !!mt.normalMap, emissiveMap: !!mt.emissiveMap, color: mt.color && mt.color.getHexString && mt.color.getHexString() } });
+      }
+    });
+    const lod = m.getObjectByName('character-lod'); if (lod && lod.getCurrentLevel) out.lod = lod.getCurrentLevel();
+    return out;
+  };
+  /** Pin the render camera to a body-frame pose, re-applied every frame so the follow cam cannot fight it. */
+  A.setCam = (c) => {
+    const cam = A.camera(); if (!cam) return false;
+    if (!cam.__vqaPinned) {
+      const orig = cam.updateMatrixWorld.bind(cam);
+      cam.updateMatrixWorld = function (force) {
+        // A frozen stride (A.freeze) is re-applied here, after the engine's mixer has posed the bones for this frame and
+        // before the renderer skins the meshes, so the pinned camera sees the held pose while the engine keeps running.
+        if (G.__vqaFrozen) { try { A.applyFrozen(); } catch (e) { /* never break the render */ } }
+        const o = G.__vqaCam;
+        if (o) {
+          const B = A.basis();
+          this.position.copy(A.toWorld(o.pos, B));
+          this.up.set(0, 1, 0);
+          this.lookAt(A.toWorld(o.target, B));
+          if (o.fov && this.fov !== o.fov) { this.fov = o.fov; this.updateProjectionMatrix(); }
+          if (o.near && this.near !== o.near) { this.near = o.near; this.updateProjectionMatrix(); }
+        }
+        return orig(force);
+      };
+      cam.__vqaPinned = { fov: cam.fov, near: cam.near };
+    }
+    G.__vqaCam = c; return true;
+  };
+  A.clearCam = () => { G.__vqaCam = null; const cam = A.camera(); if (cam && cam.__vqaPinned) { cam.fov = cam.__vqaPinned.fov; cam.near = cam.__vqaPinned.near; cam.updateProjectionMatrix(); } return true; };
+  A.stats = () => G.__vqaStats(A.model());
+  A.materialsOf = () => {
+    const m = A.model(); const mats = new Set();
+    m.traverse((o) => { if (o.isMesh) for (const mt of (Array.isArray(o.material) ? o.material : [o.material])) if (mt) mats.add(mt); });
+    return mats;
+  };
+  /** Every drawn primitive's material: does it exist, which maps it samples and whether each decoded, how much it emits
+   *  without an emissive map, and how many triangles it covers. The ground truth for the material asserts. */
+  A.materials = () => {
+    const m = A.model(); const rows = []; let tris = 0;
+    const SLOTS = ['map', 'normalMap', 'emissiveMap', 'roughnessMap', 'metalnessMap', 'aoMap', 'alphaMap'];
+    const decoded = (t) => {
+      if (!t) return null;
+      const img = t.image; const mips = t.mipmaps;
+      if (t.isCompressedTexture || (mips && mips.length && mips[0] && mips[0].data)) return !!(mips && mips.length && mips[0] && mips[0].data && mips[0].data.length) || !!(img && img.width > 0);
+      if (img && (img.width > 0 || img.videoWidth > 0 || (img.data && img.data.length))) return true;
+      return false;
+    };
+    m.traverse((o) => {
+      if (!o.isMesh || !o.geometry || !A.visible(o, m)) return;
+      const g = o.geometry; const pos = g.attributes && g.attributes.position; if (!pos) return;
+      const n = Math.floor((g.index ? g.index.count : pos.count) / 3);
+      const groups = Array.isArray(o.material) && g.groups && g.groups.length ? g.groups : null;
+      const ms = Array.isArray(o.material) ? o.material : [o.material];
+      ms.forEach((mt, i) => {
+        const t = groups ? Math.floor((groups.filter((gr) => gr.materialIndex === i).reduce((s, gr) => s + Math.min(gr.count, (g.index ? g.index.count : pos.count)), 0)) / 3) : (i === 0 ? n : 0);
+        tris += t;
+        if (!mt) { rows.push({ mesh: o.name || o.uuid.slice(0, 8), material: null, tris: t, missing: true }); return; }
+        if (mt.visible === false || mt.colorWrite === false || (mt.transparent && (mt.opacity ?? 1) < 0.02)) { tris -= t; return; }
+        const maps = {}; for (const k of SLOTS) { const d = decoded(mt[k]); if (d !== null) maps[k] = d; }
+        const e = mt.emissive ? Math.max(mt.emissive.r, mt.emissive.g, mt.emissive.b) * (mt.emissiveIntensity ?? 1) : 0;
+        rows.push({ mesh: o.name || o.uuid.slice(0, 8), material: mt.name || mt.type, type: mt.type, tris: t, maps, emissive: Math.round(e * 1000) / 1000,
+          color: mt.color && mt.color.getHexString ? mt.color.getHexString() : null, metalness: mt.metalness ?? null, unlit: mt.type === 'MeshBasicMaterial' });
+      });
+    });
+    return { tris, rows };
+  };
+  /** Re-shade the avatar for one diagnostic frame, then restore it exactly. 'albedo': unlit base colour (base colour x map
+   *  routed through emission, no lighting); 'mask': flat magenta, to find the avatar's pixels; 'restore': the original. */
+  A.shade = (mode) => {
+    let n = 0;
+    for (const mt of A.materialsOf()) {
+      if (mode === 'restore') {
+        const S = mt.__vqaSaved; if (!S) continue;
+        for (const k of Object.keys(S.props)) mt[k] = S.props[k];
+        if (mt.color && S.color) mt.color.copy(S.color); if (mt.emissive && S.emissive) mt.emissive.copy(S.emissive);
+        delete mt.__vqaSaved; mt.needsUpdate = true; n++; continue;
+      }
+      if (!mt.emissive || !mt.color) continue; // not a lit standard material (unlit/basic): leave it as drawn
+      if (!mt.__vqaSaved) mt.__vqaSaved = { props: { map: mt.map, emissiveMap: mt.emissiveMap, emissiveIntensity: mt.emissiveIntensity, metalness: mt.metalness, roughness: mt.roughness, envMapIntensity: mt.envMapIntensity, toneMapped: mt.toneMapped }, color: mt.color.clone(), emissive: mt.emissive.clone() };
+      const S = mt.__vqaSaved;
+      mt.color.setRGB(0, 0, 0); mt.metalness = 0; mt.roughness = 1; mt.envMapIntensity = 0; mt.emissiveIntensity = 1; mt.toneMapped = false;
+      if (mode === 'albedo') { mt.emissive.copy(S.color); mt.emissiveMap = S.props.map || null; }
+      else { mt.emissive.setRGB(1, 0, 1); mt.emissiveMap = null; }
+      mt.needsUpdate = true; n++;
+    }
+    return n;
+  };
+  // ------------------------------------------------------------------------------------------------ rig (walk) probes
+  const LIMBS = [['thigh_l', 'calf_l'], ['calf_l', 'foot_l'], ['foot_l', 'ball_l'], ['thigh_r', 'calf_r'], ['calf_r', 'foot_r'], ['foot_r', 'ball_r'],
+    ['upperarm_l', 'lowerarm_l'], ['lowerarm_l', 'hand_l'], ['upperarm_r', 'lowerarm_r'], ['lowerarm_r', 'hand_r']];
+  /** Per limb bone: its BIND-pose local rotation (from the skin's inverse bind matrices, i.e. the pose the mesh was
+   *  weighted in) and its own axis (towards its child, in its bind frame). */
+  A.rigInit = () => {
+    const m = A.model(); const V = A.V(), Q = A.Q();
+    let skel = null; m.traverse((o) => { if (!skel && o.isSkinnedMesh && o.skeleton && A.visible(o, m)) skel = o.skeleton; });
+    if (!skel) { A.__rig = []; return { limbs: 0, names: [], bones: 0 }; }
+    const M4 = m.matrixWorld.constructor;
+    const bindWorld = new Map(); skel.bones.forEach((b, i) => bindWorld.set(b, new M4().copy(skel.boneInverses[i]).invert()));
+    const rig = [];
+    for (const [bn, cn] of LIMBS) {
+      const b = skel.bones.find((x) => x.name === bn); const c = skel.bones.find((x) => x.name === cn);
+      if (!b || !c) continue;
+      const bw = bindWorld.get(b); const pw = b.parent && bindWorld.get(b.parent);
+      const local = pw ? new M4().copy(pw).invert().multiply(bw) : bw.clone();
+      const q = new Q(); local.decompose(new V(), q, new V());
+      const cp = new V(); new M4().copy(bw).invert().multiply(bindWorld.get(c)).decompose(cp, new Q(), new V());
+      if (cp.length() < 1e-6) continue;
+      rig.push({ name: bn, bone: b, bindQ: q, axis: cp.normalize() });
+    }
+    A.__rig = rig;
+    return { limbs: rig.length, names: rig.map((r) => r.name), bones: skel.bones.length };
+  };
+  /** Each limb bone's twist about its own axis away from its bind pose (deg, 0..180), and the direction each knee bends
+   *  (deg from the body's forward, measured only when the leg is bent by more than 3 cm). */
+  A.rigSample = () => {
+    const out = { twist: {}, knee: {} }; const V = A.V();
+    for (const r of A.__rig || []) {
+      const qr = r.bindQ.clone().invert().multiply(r.bone.quaternion);
+      const d = qr.x * r.axis.x + qr.y * r.axis.y + qr.z * r.axis.z;
+      out.twist[r.name] = Math.round(2 * Math.atan2(Math.abs(d), Math.abs(qr.w)) * 1800 / Math.PI) / 10;
+    }
+    const B = A.basis(); const at = (n) => { const b = A.bone(n); return b ? A.toBody(b.getWorldPosition(new V()), B) : null; };
+    for (const s of ['l', 'r']) {
+      const h = at('thigh_' + s), k = at('calf_' + s), a = at('foot_' + s);
+      if (!h || !k || !a) continue;
+      const ha = [a[0] - h[0], a[1] - h[1], a[2] - h[2]]; const L2 = ha[0] ** 2 + ha[1] ** 2 + ha[2] ** 2 || 1;
+      const t = ((k[0] - h[0]) * ha[0] + (k[1] - h[1]) * ha[1] + (k[2] - h[2]) * ha[2]) / L2;
+      const bend = [k[0] - (h[0] + ha[0] * t), k[1] - (h[1] + ha[1] * t), k[2] - (h[2] + ha[2] * t)];
+      const horiz = Math.hypot(bend[0], bend[2]);
+      out.knee[s] = { bendCm: Math.round(Math.hypot(bend[0], bend[1], bend[2]) * 1000) / 10, deg: horiz > 1e-4 ? Math.round(Math.acos(Math.max(-1, Math.min(1, bend[2] / horiz))) * 1800 / Math.PI) / 10 : null };
+    }
+    return out;
+  };
+  /** Sample up to maxTris triangles of every visible skinned mesh and remember their BIND (rest) areas and edge lengths. */
+  A.skinInit = (maxTris) => {
+    const m = A.model(); const meshes = [];
+    m.traverse((o) => { if (o.isSkinnedMesh && typeof o.getVertexPosition === 'function' && A.visible(o, m) && o.geometry && o.geometry.attributes && o.geometry.attributes.position) meshes.push(o); });
+    let total = 0; for (const o of meshes) total += Math.floor((o.geometry.index ? o.geometry.index.count : o.geometry.attributes.position.count) / 3);
+    const step = Math.max(1, Math.floor(total / (maxTris || 20000)));
+    const V = A.V(); const tris = [];
+    for (const o of meshes) {
+      const g = o.geometry; const pos = g.attributes.position; const idx = g.index ? g.index.array : null; const n = Math.floor((idx ? idx.length : pos.count) / 3);
+      for (let t = 0; t < n; t += step) {
+        const a = idx ? idx[t * 3] : t * 3, b = idx ? idx[t * 3 + 1] : t * 3 + 1, c = idx ? idx[t * 3 + 2] : t * 3 + 2;
+        const pa = new V().fromBufferAttribute(pos, a), pb = new V().fromBufferAttribute(pos, b), pc = new V().fromBufferAttribute(pos, c);
+        const area = new V().subVectors(pb, pa).cross(new V().subVectors(pc, pa)).length() / 2;
+        if (!(area > 1e-10)) continue;
+        tris.push({ o, a, b, c, area, e: [pa.distanceTo(pb), pb.distanceTo(pc), pc.distanceTo(pa)] });
+      }
+    }
+    A.__tris = tris;
+    return { meshes: meshes.length, sampled: tris.length, step };
+  };
+  /** Posed vs bind triangles: area-weighted shares of collapsed (< 15 % of rest area), stretched (> 4x) and
+   *  edge-stretched (an edge > 3x its rest length) triangles, normalised by the median so a uniform scale cancels. */
+  A.skinSample = () => {
+    const tris = A.__tris || []; if (!tris.length) return null;
+    const V = A.V(); const cache = new Map(); const m = A.model(); m.updateMatrixWorld(true);
+    const seen = new Set(); for (const t of tris) if (!seen.has(t.o)) { seen.add(t.o); if (t.o.skeleton) t.o.skeleton.update(); }
+    const P = (o, i) => { let mm = cache.get(o); if (!mm) { mm = new Map(); cache.set(o, mm); } let v = mm.get(i); if (!v) { v = new V(); o.getVertexPosition(i, v); mm.set(i, v); } return v; };
+    const rows = []; let total = 0; let bad = 0;
+    for (const t of tris) {
+      const pa = P(t.o, t.a), pb = P(t.o, t.b), pc = P(t.o, t.c);
+      const area = new V().subVectors(pb, pa).cross(new V().subVectors(pc, pa)).length() / 2;
+      if (!Number.isFinite(area)) { bad += t.area; total += t.area; continue; }
+      const es = Math.max(pa.distanceTo(pb) / (t.e[0] || 1e-9), pb.distanceTo(pc) / (t.e[1] || 1e-9), pc.distanceTo(pa) / (t.e[2] || 1e-9));
+      rows.push([area / t.area, es, t.area]); total += t.area;
+    }
+    const sorted = rows.map((r) => r[0]).sort((x, y) => x - y); const med = sorted[Math.floor(sorted.length / 2)] || 1; const sm = Math.sqrt(med);
+    let collapsed = 0, stretched = 0, edge = 0;
+    for (const [ar, es, w] of rows) { const r = ar / med; if (r < 0.15) collapsed += w; if (r > 4) stretched += w; if (es / sm > 3) edge += w; }
+    const f = (v) => Math.round((v / (total || 1)) * 100000) / 100000;
+    return { median: Math.round(med * 10000) / 10000, collapsed: f(collapsed + bad), stretched: f(stretched), edgeStretched: f(edge) };
+  };
+  /** Hold the current pose for rendering while the engine keeps animating underneath (re-applied before every render). */
+  A.freeze = () => { const snap = []; A.model().traverse((o) => { if (o.isBone) snap.push([o, o.position.clone(), o.quaternion.clone(), o.scale.clone()]); }); G.__vqaFrozen = snap; return snap.length; };
+  A.unfreeze = () => { G.__vqaFrozen = null; return true; };
+  A.applyFrozen = () => { const s = G.__vqaFrozen; if (!s) return; for (const [b, p, q, sc] of s) { b.position.copy(p); b.quaternion.copy(q); b.scale.copy(sc); } A.model().updateMatrixWorld(true); };
+  A.position = () => A.model().position.toArray();
+  G.__vqaAv = A;
+  return true;
+})()`;
+//# sourceMappingURL=avatarProbe.js.map

package/dist/visualQa/avatarProbe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatarProbe.js","sourceRoot":"","sources":["../../src/visualQa/avatarProbe.ts"],"names":[],"mappings":";;;AAAA,oHAAoH;AACpH,gGAAgG;AAChG,EAAE;AACF,wHAAwH;AACxH,kHAAkH;AAClH,oHAAoH;AACpH,sGAAsG;AACzF,QAAA,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4P/B,CAAC"}

package/dist/visualQa/browser.d.ts

@@ -0,0 +1,116 @@
+import { type BrowserChannel } from './pinnedChrome';
+import { type WebGpuSelfTest } from './webgpuSelfTest';
+import type { BrowserContext, Frame, Page } from 'playwright';
+import { type CandidateConfig } from './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. */
+export declare const RUNTIME_FAULT_RE: RegExp;
+export interface VqaBrowser {
+    ctx: BrowserContext;
+    page: Page;
+    fetchedAssets: string[];
+    pageErrors: string[];
+    /**
+     * Console errors that say the runtime refused to compose the car (`[helix-vehicle] composition failed: …`). The throw
+     * happens while the car is being composed, so it is never presented and the page raises no error of its own.
+     */
+    runtimeFaults: string[];
+    /** The browser this session runs on, as recorded in the bundle (`harness.browser`). */
+    info: VqaBrowserInfo;
+    close(): Promise<void>;
+}
+/** `harness.browser` in every bundle: which exact build drew the frames, where it came from, and its WebGPU self-test. */
+export interface VqaBrowserInfo {
+    /** `Chrome for Testing`, `Playwright Chromium (chromium-1243)`, … */
+    name: string;
+    /** Full four-part version from CDP `Browser.getVersion` (the UA string reduces it to `153.0.0.0`). */
+    version: string | null;
+    executablePath: string | null;
+    /** `pinned-cft` (the gate's own current-stable pin), `env-override` (HELIX_VQA_CHROME / HELIX_VQA_WIN_CHROME),
+     *  `explicit` (--chrome), `remote-cdp` (HELIX_VQA_CDP_URL: a browser this process did not start). */
+    channel: BrowserChannel;
+    userAgent: string | null;
+    webgpu?: {
+        status: WebGpuSelfTest['webgpu'] | 'skipped';
+        adapter?: string | null;
+        selfTest: 'pass' | 'fail' | 'skipped';
+        detail?: string;
+        ms?: number;
+    };
+}
+export interface VqaLaunchOptions {
+    /** Playwright storageState JSON (cookies + localStorage) of a signed-in QA account. */
+    storageState?: string;
+    width?: number;
+    height?: number;
+    /** Explicit Chromium executable. Defaults to the pinned current-stable Chrome for Testing; the macOS system Chrome is refused. */
+    executablePath?: string;
+    /** `session` = only mints a sign-in cookie (no WebGPU self-test). Default `render`. */
+    purpose?: 'render' | 'session';
+}
+/** @deprecated the gate resolves the pinned Chrome for Testing (pinnedChrome.ts); kept for callers of the old export. */
+export declare function defaultExecutable(playwrightDefault?: string): string | undefined;
+/** True when the harness should drive a Windows-native Chromium over CDP (WSL: the real GPU) instead of a Linux one. */
+export declare function useWindowsChrome(): boolean;
+export declare function gpuArgs(platform?: NodeJS.Platform): string[];
+/** Page-side hook source. Plain function so Playwright serialises it; runs before any page script in every frame. */
+export declare function installHooks(): void;
+export declare function resetBrowserAbort(): void;
+export declare function abortAllBrowsers(): Promise<void>;
+export declare function setCandidate(config: CandidateConfig | null): void;
+/** 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. */
+export declare const PLATFORM_RUNTIME_URL_RE: RegExp;
+/** 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. */
+export declare function installPlatformRuntimeCors(ctx: Pick<BrowserContext, 'route'>): Promise<void>;
+export declare function launchVqaBrowser(opts?: VqaLaunchOptions): Promise<VqaBrowser>;
+/** 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. */
+export declare function browserName(executablePath: string | null, product: string | null): string;
+export declare function resetBrowserRecords(): void;
+/** The browser that drew this render: the first render launch, else the first launch of any kind, else null. */
+export declare function renderBrowser(): VqaBrowserInfo | null;
+/** Distinct builds this render launched (normally one). */
+export declare function distinctBrowserVersions(): string[];
+/**
+ * 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.
+ */
+export declare function preflightVqaBrowser(opts?: {
+    executablePath?: string;
+}): Promise<VqaBrowserInfo>;
+/**
+ * `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.
+ */
+export declare function fixtureModel(env?: NodeJS.ProcessEnv): {
+    hex: string;
+    file: string;
+} | null;
+/** Pad a GLB to exactly `length` bytes with a trailing unknown-type chunk; unchanged when it cannot fit. */
+export declare function padGlb(glb: Buffer, length: number): Buffer;
+/** Page-side (fixture runs only): a digest of bytes that begin like the fixture (after the GLB header) reports the pinned model's hash. */
+export declare function fixtureDigestSpoof(arg: {
+    prefix: string;
+    hex: string;
+}): void;
+/** The renderer string actually in use (never inferred from flags). */
+export declare function rendererInfo(page: Page): Promise<string | null>;
+/** JPEG screenshot of the viewport (or a frame's element) after letting `settleMs` of frames render. */
+export declare function captureJpeg(page: Page, file: string, settleMs?: number): Promise<{
+    width: number;
+    height: number;
+}>;
+/** Find the first frame (main or iframe) where `probe` returns truthy. */
+export declare function findFrame(page: Page, probe: () => unknown, timeoutMs?: number): Promise<Frame>;
+/**
+ * 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.
+ */
+export declare function mintStorageState(webBase: string, accessToken: string, file: string, executablePath?: string): Promise<string>;