@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/visualQa/viewerPage.js

@@ -0,0 +1,414 @@
+"use strict";
+// Page-side helpers for the customiser / item-viewer route. Plain JS strings (the CLI compiles without the DOM lib),
+// evaluated in the frame whose three.js scene `browser.ts` already exposes as `window.__vqa.scene`.
+//
+// Nothing here changes what the page draws except the camera and which DOM panels are visible: the item is fitted
+// through the page's own UI, by the page's own code, so the frames show exactly what a buyer sees.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTALL_VIEWER_PAGE = exports.CONTROLS_HOOK = void 0;
+/**
+ * Captures every OrbitControls-like instance (anything that assigns `enableDamping` in its constructor) so the
+ * harness can move the page's own camera without the controls snapping it back. Same Object.prototype-setter trick
+ * as the scene hook in browser.ts; installed as an extra init script by the viewer route only.
+ */
+exports.CONTROLS_HOOK = `(() => {
+  if (globalThis.__vqvControls) return;
+  const list = []; globalThis.__vqvControls = list;
+  try {
+    Object.defineProperty(Object.prototype, 'enableDamping', {
+      configurable: true, enumerable: false,
+      set(v) {
+        try { Object.defineProperty(this, 'enableDamping', { value: v, writable: true, configurable: true, enumerable: true }); } catch (e) {}
+        if (this && !list.includes(this)) list.push(this);
+      },
+      get() { return undefined; },
+    });
+  } catch (e) {}
+})();`;
+/**
+ * Installs `globalThis.__vqv` in the frame. Requires INSTALL_SCENE_STATS (commonAsserts.ts) to be installed first.
+ * Every position it returns is WORLD space, rounded to 0.1 mm.
+ */
+exports.INSTALL_VIEWER_PAGE = `globalThis.__vqv = (function () {
+  const r4 = (v) => Math.round(v * 10000) / 10000;
+  const S = { before: null, beforeMeshes: null, host: null, controls: null, pinned: null };
+  const scene = () => { const draw = activeDraw(); return (draw && draw.scene) || (globalThis.__vqa && globalThis.__vqa.scene) || null; };
+
+  /**
+   * HOLD THE AIMED POSE. A single camera.position/lookAt write is not enough: the surface's own render loop drives its
+   * OrbitControls every frame (controls.update() recomputes position from ITS target and spherical), and a re-fit on a
+   * layout edge writes camera.position outright, so the aimed pose is gone before the screenshot and every fitted frame
+   * renders the surface's default view — a rear-mounted part is then never in frame. Re-apply the pose from a wrapper
+   * around camera.updateMatrixWorld, which three.js calls during every render (after the surface's own writes), so the
+   * drawn frame is the aimed one. The same pin the whole-vehicle route uses (vehicleProbe \`setCam\`).
+   *
+   * Each camera retains only its own current pose. Update the entry before aim's matrix update, or that update
+   * would restore the previous shot. Never lend one camera's pose to another captured camera.
+   */
+  function pinCam(cam, pose) {
+    if (!S.pinned) S.pinned = new Map();
+    const existing = S.pinned.get(cam);
+    if (existing) { existing.pose = pose; return; }
+    const entry = { orig: cam.updateMatrixWorld, pose };
+    S.pinned.set(cam, entry);
+    cam.updateMatrixWorld = function (force) {
+      const p = entry.pose;
+      cam.position.set(p.pos[0], p.pos[1], p.pos[2]);
+      cam.up.set(p.up[0], p.up[1], p.up[2]);
+      cam.lookAt(p.target[0], p.target[1], p.target[2]);
+      return entry.orig.call(cam, force);
+    };
+  }
+  /** Restore exactly the method each camera had before capture. */
+  function releaseCam() {
+    if (S.pinned) { for (const [cam, entry] of S.pinned) cam.updateMatrixWorld = entry.orig; S.pinned = null; }
+    return true;
+  }
+  const meshesOf = (root) => { const out = []; if (root) root.traverse((o) => { if (o.isMesh && !o.isBatchedMesh && o.geometry) out.push(o); }); return out; };
+  const chainVisible = (o) => { for (let p = o; p; p = p.parent) if (p.visible === false) return false; return true; };
+  const fakeRoot = (list) => ({ updateMatrixWorld() {}, traverse(cb) { for (const m of list) cb(m); } });
+  const statsOf = (list) => { const s = scene(); if (s) s.updateMatrixWorld(true); return globalThis.__vqaStats(fakeRoot(list)); };
+  const worldPos = (o) => { const e = o.matrixWorld.elements; return [r4(e[12]), r4(e[13]), r4(e[14])]; };
+
+  /**
+   * The viewer owns a scene-level Group containing its loaded model; the customiser adds the GLTF Group directly.
+   * Studio lights and the contact-shadow/floor meshes are siblings of that container, never its descendants.
+   * Select that ownership boundary by object identity/type, not authored names: a studio lamp, floor rug, or
+   * model named "studio-contact-shadow" is still the subject. Missing containers fail closed.
+   */
+  function hostRoot() {
+    const s = scene(); if (!s) return null;
+    let host = null;
+    for (const c of s.children) {
+      if (!c.isGroup && !c.isScene) continue;
+      if (!meshesOf(c).length) continue;
+      // A different viewer layout needs an explicit root contract; never guess among multiple model containers.
+      if (host) return null;
+      host = c;
+    }
+    return host;
+  }
+
+  /** Remember every object in the scene now (before the part is fitted). */
+  function snapshot() {
+    const s = scene(); if (!s) return null;
+    s.updateMatrixWorld(true);
+    S.before = new Set(); S.beforeMeshes = [];
+    s.traverse((o) => { S.before.add(o); if (o.isMesh && o.geometry) S.beforeMeshes.push(o); });
+    S.host = hostRoot();
+    return { objects: S.before.size, meshes: S.beforeMeshes.length, host: S.host ? (S.host.name || S.host.type) : null };
+  }
+
+  /** Meshes that did not exist at snapshot time and are drawn (visible chain). */
+  function newMeshes() {
+    const s = scene(); if (!s || !S.before) return [];
+    const out = [];
+    // A \`helix:vehicle-batch:*\` BatchedMesh (re)built after the fit packs every part in its LOCAL frame: it is never
+    // the part. The parts it draws stay in the graph as proxies with their real transforms, and those are measured.
+    if (S.host) S.host.traverse((o) => { if (o.isMesh && !o.isBatchedMesh && o.geometry && !S.before.has(o) && chainVisible(o)) out.push(o); });
+    return out;
+  }
+  function newMeshCount() { return newMeshes().length; }
+
+  /** Group new meshes into fitted instances: one group per top-most newly-added ancestor. */
+  function instances() {
+    const groups = new Map();
+    for (const m of newMeshes()) {
+      let top = m;
+      while (top.parent && !S.before.has(top.parent)) top = top.parent;
+      if (!groups.has(top)) groups.set(top, []);
+      groups.get(top).push(m);
+    }
+    const out = [];
+    for (const [top, list] of groups) {
+      let socket = null; const chain = [];
+      for (let p = list[0]; p; p = p.parent) { chain.push(p.name || p.type); if (!socket && /^socket:/.test(p.name || '')) socket = p.name.slice(7); }
+      const st = statsOf(list);
+      out.push({ key: top.name || top.type, socket, attachedTo: top.parent ? (top.parent.name || top.parent.type) : null,
+        chain: chain.slice(0, 7).join(' < '), meshes: list.length, triangles: st.triangles, bounds: st.bounds, origin: worldPos(top) });
+    }
+    return out;
+  }
+
+  /** SceneStats over every new mesh (the fitted part as drawn). */
+  function partStats() { return statsOf(newMeshes()); }
+  /** SceneStats of the subject (host / base) as drawn at snapshot time. */
+  function hostStats() { return S.host ? statsOf(meshesOf(S.host).filter(chainVisible)) : null; }
+  /** SceneStats over the drawn meshes owned by the model container (prop route: the item is the whole subject). */
+  function subjectStats() { const h = hostRoot(); return h ? statsOf(meshesOf(h).filter(chainVisible)) : null; }
+
+  /** Per-corner drawn wheel geometry of the host (rim/tyre/wheel nodes), measured at snapshot time. */
+  function hostWheels() {
+    const h = S.host; if (!h) return [];
+    const corners = new Map(); const norm = { fl: 'lf', fr: 'rf', rl: 'lr', bl: 'lr', br: 'rr' };
+    h.traverse((o) => {
+      const m = /^(rim|rims|tyre|tire|tyres|tires|wheel|whl|hub)[_\\-. ]?(lf|rf|lr|rr|fl|fr|rl|bl|br)(?![a-z])/i.exec(o.name || '');
+      if (!m) return;
+      const c = norm[m[2].toLowerCase()] || m[2].toLowerCase();
+      if (!corners.has(c)) corners.set(c, { nodes: new Set(), meshes: new Set() });
+      corners.get(c).nodes.add(o.name);
+      for (const mm of meshesOf(o)) if (chainVisible(mm)) corners.get(c).meshes.add(mm);
+    });
+    const out = [];
+    for (const [corner, v] of corners) {
+      const st = statsOf([...v.meshes]);
+      out.push({ corner, nodes: [...v.nodes].sort(), meshes: v.meshes.size, bounds: st.bounds });
+    }
+    return out;
+  }
+
+  /** Host frame facts: origin (vehicle_root if present, else the subject root), scale, quaternion. */
+  function hostFrame() {
+    const h = S.host || hostRoot(); if (!h) return null;
+    h.updateMatrixWorld(true);
+    let vr = null; h.traverse((o) => { if (!vr && /^vehicle_root$/i.test(o.name || '')) vr = o; });
+    const e = (vr || h).matrixWorld.elements;
+    const sc = Math.hypot(e[0], e[1], e[2]);
+    return { node: (vr || h).name || (vr || h).type, origin: [r4(e[12]), r4(e[13]), r4(e[14])], scale: r4(sc),
+      xAxis: [r4(e[0] / sc), r4(e[1] / sc), r4(e[2] / sc)], zAxis: [r4(e[8] / sc), r4(e[9] / sc), r4(e[10] / sc)] };
+  }
+
+  /**
+   * The presentation transform a viewer put on the model: walking down from the subject root through single-child
+   * groups, the first node carrying a non-unit uniform scale (the item viewer's fitModelToStage scales the model to a
+   * 2.15 m stage). Bounds divided by it are the item's authored size.
+   */
+  function presentationScale() {
+    let n = hostRoot(); if (!n) return { scale: 1, origin: [0, 0, 0], node: null };
+    n.updateMatrixWorld(true);
+    for (let depth = 0; n && depth < 6; depth++) {
+      const sc = n.scale;
+      if (Math.abs(sc.x - 1) > 1e-4 && Math.abs(sc.x - sc.y) < 1e-6 && Math.abs(sc.x - sc.z) < 1e-6) {
+        const e = n.matrixWorld.elements;
+        return { scale: r4(Math.hypot(e[0], e[1], e[2])), origin: [r4(e[12]), r4(e[13]), r4(e[14])], node: n.name || n.type, depth };
+      }
+      const kids = n.children.filter((c) => !c.isLight);
+      if (kids.length !== 1 || n.isMesh) break;
+      n = kids[0];
+    }
+    return { scale: 1, origin: [0, 0, 0], node: null };
+  }
+
+  /** World position of named host nodes (first match per name). */
+  function nodePositions(names) {
+    const s = scene(); const out = {}; if (!s) return out;
+    s.updateMatrixWorld(true);
+    s.traverse((o) => { if (names.includes(o.name) && !out[o.name]) { const st = statsOf(meshesOf(o).filter(chainVisible)); out[o.name] = { origin: worldPos(o), drawn: st.bounds }; } });
+    return out;
+  }
+
+  /** Bones of the base (any skinned mesh in the snapshot subject), world positions. */
+  function bones() {
+    const out = {}; const s = scene(); if (!s) return out;
+    s.updateMatrixWorld(true);
+    const root = S.host || hostRoot(); if (!root) return out;
+    root.traverse((o) => { if (o.isBone && !(o.name in out)) out[o.name] = worldPos(o); });
+    return out;
+  }
+
+  /**
+   * Evenly sampled WORLD vertices of a mesh list (skinning applied), flat [x,y,z,...], at most maxPoints. Only
+   * index-referenced vertices inside the draw range count: a POSITION buffer can carry vertices nothing draws.
+   */
+  function sample(list, maxPoints) {
+    const s = scene(); if (s) s.updateMatrixWorld(true);
+    const refs = list.map((m) => {
+      const g = m.geometry; const pos = g.attributes.position; if (!pos) return null;
+      const idx = g.index ? g.index.array : null; const n = idx ? idx.length : pos.count;
+      const start = (g.drawRange && g.drawRange.start) || 0;
+      const count = Math.min(n - start, (g.drawRange && Number.isFinite(g.drawRange.count)) ? g.drawRange.count : n);
+      let used;
+      if (idx) { used = new Set(); for (let k = start; k < start + count; k++) used.add(idx[k]); used = [...used]; }
+      else { used = []; for (let k = start; k < start + count; k++) used.push(k); }
+      return { m, pos, used };
+    }).filter(Boolean);
+    let total = 0; for (const r of refs) total += r.used.length;
+    const step = Math.max(1, Math.ceil(total / maxPoints));
+    const out = [];
+    for (const { m, pos, used } of refs) {
+      const e = m.matrixWorld.elements;
+      const skinned = m.isSkinnedMesh && typeof m.getVertexPosition === 'function';
+      const tmp = skinned ? new (m.position.constructor)() : null;
+      for (let j = 0; j < used.length; j += step) {
+        const i = used[j];
+        let x, y, z;
+        if (skinned) { m.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) || !Number.isFinite(y) || !Number.isFinite(z)) continue;
+        out.push(r4(e[0] * x + e[4] * y + e[8] * z + e[12]), r4(e[1] * x + e[5] * y + e[9] * z + e[13]), r4(e[2] * x + e[6] * y + e[10] * z + e[14]));
+      }
+    }
+    return out;
+  }
+  function samplePart(maxPoints) { return sample(newMeshes(), maxPoints); }
+  function sampleBody(maxPoints) { return sample((S.beforeMeshes || []).filter((m) => S.host && isUnder(m, S.host)), maxPoints); }
+  function isUnder(o, root) { for (let p = o; p; p = p.parent) if (p === root) return true; return false; }
+
+  /**
+   * The camera the surface ACTUALLY draws the visible canvas with, and its controls.
+   *
+   * \`__vqa.main\` is the most-used camera across every \`render(scene, camera)\` call, which is NOT the buyer-facing
+   * camera once an add-on is fitted: the surface then runs an internal orthographic pass (the environment/shadow
+   * render), and main flips to that ortho camera. Aiming it moves a camera that never draws the canvas, so every
+   * fitted frame renders the surface's default view. The surface's own OrbitControls are constructed with the visible
+   * camera. The completed default-framebuffer receipt binds that camera to the canvas; ambiguous canvases fail.
+   */
+  const ids = new WeakMap(); let nextId = 0;
+  const idOf = (object) => { if (!object) return null; if (!ids.has(object)) ids.set(object, ++nextId); return ids.get(object); };
+  function activeDraw() {
+    const H = globalThis.__vqa || {};
+    const marked = typeof document !== 'undefined' ? document.querySelector('[data-vqv-canvas]') : null;
+    const matches = [...(H.draws || new Map()).values()].filter((d) => d.scene?.isScene && d.camera.isPerspectiveCamera
+      && d.canvas === d.renderer.domElement && (!marked || d.canvas === marked));
+    return matches.length === 1 ? matches[0] : null;
+  }
+  function rig() {
+    const draw = activeDraw(); const cam = draw && draw.camera;
+    const ctl = (globalThis.__vqvControls || []).find((c) => c && c.object === cam && c.target) || null;
+    return { cam, ctl, draw };
+  }
+  function renderCam() {
+    const { cam, draw } = rig(); if (!cam || !draw) return null;
+    const e = cam.matrixWorld.elements;
+    return { cameraId: idOf(cam), rendererId: idOf(draw.renderer), canvasId: idOf(draw.canvas),
+      pos: cam.position.toArray(), matrixWorld: [e[12], e[13], e[14]], worldMatrix: e.slice(), projection: cam.projectionMatrix.elements.slice(), zoom: cam.zoom, fov: cam.fov, aspect: cam.aspect, view: !!cam.view?.enabled,
+      draw: { cameraId: idOf(draw.camera), rendererId: idOf(draw.renderer), canvasId: idOf(draw.canvas),
+        frame: draw.frame, worldMatrix: draw.worldMatrix, projection: draw.projection, zoom: draw.zoom, view: draw.view, pos: draw.pos, matrixWorld: draw.matrixWorld, direction: draw.direction, up: draw.up } };
+  }
+  /** Select only the canvas actually drawn by the subject's perspective camera. */
+  function isolateCanvas() {
+    const draw = activeDraw(); const canvas = draw && draw.canvas;
+    if (!canvas) return false;
+    canvas.setAttribute('data-vqv-canvas', '1');
+    for (let node = canvas; node && node !== document.body && node.parentElement; node = node.parentElement) {
+      for (const sib of node.parentElement.children) if (sib !== node && sib.style) { sib.style.setProperty('visibility', 'hidden', 'important'); sib.style.setProperty('opacity', '0', 'important'); }
+    }
+    return true;
+  }
+
+  /** Point the page's camera at box [min,max] from direction dir (unit, target→camera). */
+  /**
+   * Point the page's camera from direction dir (unit, target→camera). \`fit\` chooses what must fill the frame:
+   * 'box' = the 8 corners of [min,max]; 'scene' = sampled drawn vertices of the subject + the fitted part;
+   * 'part' = sampled drawn vertices of the fitted part only. Vertex fits are tight and re-centred on the silhouette.
+   */
+  function aim(min, max, dir, margin, fit) {
+    const { cam, ctl, draw } = rig(); if (!cam) return { ok: false, why: 'no unique subject canvas/camera draw' };
+    const V = cam.position.constructor;
+    const c = new V((min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2);
+    if (cam.clearViewOffset) cam.clearViewOffset();
+    const vfov = (cam.fov || 40) * Math.PI / 180; const aspect = cam.aspect || 1.6;
+    const tv = Math.tan(vfov / 2), th = Math.tan(vfov / 2) * aspect;
+    const d = new V(dir[0], dir[1], dir[2]).normalize();
+    const upRef = Math.abs(d.y) > 0.98 ? new V(0, 0, -1) : new V(0, 1, 0);
+    const right = new V().crossVectors(upRef, d).normalize(); const up = new V().crossVectors(d, right).normalize();
+    let pts = [];
+    if (fit === 'scene' || fit === 'part') {
+      const list = fit === 'part' ? newMeshes() : newMeshes().concat(meshesOf(S.host || hostRoot()).filter(chainVisible));
+      const flat = sample(list, 6000);
+      for (let i = 0; i + 2 < flat.length; i += 3) pts.push(new V(flat[i], flat[i + 1], flat[i + 2]));
+    }
+    if (!pts.length) for (let i = 0; i < 8; i++) pts.push(new V(i & 1 ? max[0] : min[0], i & 2 ? max[1] : min[1], i & 4 ? max[2] : min[2]));
+    // Re-centre on the silhouette in the image plane, then take the distance at which every point just fits.
+    let x0 = Infinity, x1 = -Infinity, y0 = Infinity, y1 = -Infinity;
+    for (const p of pts) { const q = p.clone().sub(c); const x = q.dot(right), y = q.dot(up); if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y; }
+    c.addScaledVector(right, (x0 + x1) / 2).addScaledVector(up, (y0 + y1) / 2);
+    let dist = 0.05;
+    for (const p of pts) {
+      const q = p.clone().sub(c);
+      const along = q.dot(d); const x = Math.abs(q.dot(right)); const y = Math.abs(q.dot(up));
+      dist = Math.max(dist, along + x / th, along + y / tv);
+    }
+    dist *= (margin || 1.08);
+    const upv = Math.abs(d.y) > 0.98 ? [0, 0, -1] : [0, 1, 0];
+    const px = c.x + d.x * dist, py = c.y + d.y * dist, pz = c.z + d.z * dist;
+    // PIN THIS SHOT'S POSE FIRST. If an earlier shot already installed the updateMatrixWorld wrapper, the call below
+    // would re-apply the PREVIOUS pose (overwriting cam.position) and every fitted frame would render the first shot's
+    // camera. Setting this camera's pose first makes that call re-apply the NEW pose; the return uses the
+    // computed numbers so it can never report a stale position.
+    pinCam(cam, { pos: [px, py, pz], target: [c.x, c.y, c.z], up: upv });
+    cam.position.set(px, py, pz);
+    cam.near = Math.max(0.005, dist / 200); cam.far = Math.max(cam.far || 100, dist * 20);
+    cam.up.set(upv[0], upv[1], upv[2]);
+    cam.lookAt(c); cam.updateProjectionMatrix(); cam.updateMatrixWorld(true);
+    if (ctl) {
+      try {
+        ctl.autoRotate = false; ctl.minDistance = 0; ctl.maxDistance = Infinity; ctl.minPolarAngle = 0; ctl.maxPolarAngle = Math.PI;
+        ctl.minAzimuthAngle = -Infinity; ctl.maxAzimuthAngle = Infinity; if ('maxTargetRadius' in ctl) ctl.maxTargetRadius = Infinity;
+        if ('minZoom' in ctl) ctl.minZoom = 0;
+        ctl.target.copy(c); ctl.update(); ctl.dispatchEvent && ctl.dispatchEvent({ type: 'change' });
+      } catch (e) {}
+    }
+    cam.updateMatrixWorld(true);
+    return { worldMatrix: cam.matrixWorld.elements.slice(), projection: cam.projectionMatrix.elements.slice(), zoom: cam.zoom, ok: true, controls: !!ctl, pinned: true, centre: [r4(c.x), r4(c.y), r4(c.z)], distance: r4(dist), camera: [r4(px), r4(py), r4(pz)], cameraId: idOf(cam), rendererId: idOf(draw.renderer), canvasId: idOf(draw.canvas), beforeDrawFrame: draw.frame, fov: cam.fov, aspect: cam.aspect };
+  }
+
+  /** Temporarily hide (true) / restore (false) the snapshot subject's own meshes, leaving the fitted part drawn. */
+  function hideHost(on) {
+    if (on) { S.hidden = (S.beforeMeshes || []).filter((m) => m.visible && S.host && isUnder(m, S.host)); for (const m of S.hidden) m.visible = false; }
+    else { for (const m of S.hidden || []) m.visible = true; S.hidden = null; }
+    return (S.hidden || []).length;
+  }
+
+  /** Temporarily hide (true) / restore (false) the fitted part's meshes. */
+  function hidePart(on) {
+    if (on) { S.hiddenPart = newMeshes(); for (const m of S.hiddenPart) m.visible = false; }
+    else { for (const m of S.hiddenPart || []) m.visible = true; S.hiddenPart = null; }
+    return (S.hiddenPart || []).length;
+  }
+
+  /**
+   * X-ray: draw the subject's own meshes translucent (opacity, no depth write) so an enclosed part reads through the
+   * body; the fitted part stays opaque. Materials are swapped for clones and restored exactly on xray(false).
+   */
+  function xray(on, opacity) {
+    if (on) {
+      S.xray = [];
+      const clones = new Map();
+      for (const m of (S.beforeMeshes || []).filter((x) => x.visible && S.host && isUnder(x, S.host))) {
+        const orig = m.material;
+        const swap = (mat) => {
+          if (!mat) return mat;
+          if (!clones.has(mat)) {
+            const c = mat.clone();
+            c.transparent = true; c.opacity = opacity == null ? 0.18 : opacity; c.depthWrite = false;
+            if ('transmission' in c) c.transmission = 0;
+            c.needsUpdate = true;
+            clones.set(mat, c);
+          }
+          return clones.get(mat);
+        };
+        m.material = Array.isArray(orig) ? orig.map(swap) : swap(orig);
+        S.xray.push([m, orig, m.renderOrder]);
+        m.renderOrder = 10;
+      }
+      // The part goes LAST in the transparent pass, fully opaque and depth-writing: the translucent host (which
+      // writes no depth) is blended first, so the part is drawn crisp on top instead of veiled by every body layer.
+      const onTop = new Map();
+      for (const m of newMeshes()) {
+        const orig = m.material;
+        const lift = (mat) => {
+          if (!mat) return mat;
+          if (!onTop.has(mat)) { const c = mat.clone(); c.transparent = true; c.opacity = 1; c.depthWrite = true; c.depthTest = true; c.needsUpdate = true; onTop.set(mat, c); }
+          return onTop.get(mat);
+        };
+        m.material = Array.isArray(orig) ? orig.map(lift) : lift(orig);
+        S.xray.push([m, orig, m.renderOrder]);
+        m.renderOrder = 999;
+      }
+      return S.xray.length;
+    }
+    for (const [m, orig, ro] of S.xray || []) { m.material = orig; m.renderOrder = ro; }
+    const n = (S.xray || []).length; S.xray = null;
+    return n;
+  }
+
+  /** Resolve after n animation frames (and report how many renders happened meanwhile). */
+  function frames(n) {
+    const H = globalThis.__vqa || {}; const f0 = H.frames || 0;
+    return new Promise((res) => { let k = 0; const tick = () => { if (++k >= n) res((H.frames || 0) - f0); else requestAnimationFrame(tick); }; requestAnimationFrame(tick); });
+  }
+
+  return { snapshot, newMeshCount, instances, partStats, hostStats, subjectStats, hostWheels, hostFrame, nodePositions, bones,
+    samplePart, sampleBody, isolateCanvas, aim, releaseCam, renderCam, frames, hideHost, hidePart, xray, presentationScale, rig: () => { const r = rig(); return { camera: !!r.cam, controls: !!r.ctl, fov: r.cam ? r.cam.fov : null, aspect: r.cam ? r.cam.aspect : null }; } };
+})();`;
+//# sourceMappingURL=viewerPage.js.map

package/dist/visualQa/viewerPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewerPage.js","sourceRoot":"","sources":["../../src/visualQa/viewerPage.ts"],"names":[],"mappings":";AAAA,qHAAqH;AACrH,oGAAoG;AACpG,EAAE;AACF,kHAAkH;AAClH,mGAAmG;;;AAEnG;;;;GAIG;AACU,QAAA,aAAa,GAAG;;;;;;;;;;;;;MAavB,CAAC;AAEP;;;GAGG;AACU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA6X7B,CAAC"}

package/dist/visualQa/webgpuSelfTest.d.ts

@@ -0,0 +1,52 @@
+export declare const SELFTEST_VS = "@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> { return vec4<f32>(f32(i) - 1.0, 0.0, 0.0, 1.0); }";
+/** Control: a plain component read. */
+export declare const SELFTEST_FS_CONTROL = "struct O { @location(0) c: vec4<f32> };\nvar<private> v : vec4<f32>;\n@fragment fn main() -> O { var o: O; o.c = vec4<f32>(v.x); return o; }";
+/** Repro: a component read off a swizzle — what three r185 emits for every lit node material. */
+export declare const SELFTEST_FS_SWIZZLE = "struct O { @location(0) c: vec4<f32> };\nvar<private> v : vec4<f32>;\n@fragment fn main() -> O { var o: O; o.c = vec4<f32>(v.xy.x); return o; }";
+export interface ShaderCompileResult {
+    ok: boolean;
+    messages: string[];
+}
+export interface WebGpuSelfTest {
+    /** `available` = an adapter and a device; `none` = no navigator.gpu or no adapter; `error` = the probe itself threw. */
+    webgpu: 'available' | 'none' | 'error';
+    adapter?: string | null;
+    reason?: string;
+    control?: ShaderCompileResult;
+    swizzle?: ShaderCompileResult;
+    ms?: number;
+}
+/** Page-side probe. A plain function (serialised by Playwright); takes the shader sources as its argument. */
+export declare function webGpuSelfTestProbe(src: {
+    vs: string;
+    control: string;
+    swizzle: string;
+}): Promise<WebGpuSelfTest>;
+export declare const SELFTEST_SOURCES: {
+    vs: string;
+    control: string;
+    swizzle: string;
+};
+export interface SelfTestBrowserLabel {
+    name: string;
+    version: string | null;
+    executablePath?: string | null;
+}
+export type SelfTestDecision = {
+    ok: true;
+    note?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Message prefix the hosted worker / reviewers can match on. */
+export declare const BROKEN_COMPILER_PREFIX = "broken WebGPU shader compiler in";
+/**
+ * Decide whether a browser may render. Pure, so the policy is unit-tested:
+ *   - repro fails while the control compiles → the known Tint swizzle bug: refuse.
+ *   - control fails too → WebGPU cannot compile a trivial shader: refuse.
+ *   - no adapter / probe threw → refuse when the route needs WebGPU, else allow (and the caller records it).
+ */
+export declare function decideSelfTest(r: WebGpuSelfTest | null | undefined, browser: SelfTestBrowserLabel, opts: {
+    requireWebGpu: boolean;
+}): SelfTestDecision;

package/dist/visualQa/webgpuSelfTest.js

@@ -0,0 +1,113 @@
+"use strict";
+// Startup self-test: before a visual-QA browser renders anything, prove its WebGPU shader compiler can build what three
+// r185 emits. Measured 2026-10-03: Playwright's bundled Chromium 153.0.8010.12 (chromium-1243) refuses any WGSL that
+// reads a component off a swizzle (`v.xy.x`) on Metal — the shader MODULE compiles, the render PIPELINE fails with
+// "swizzle view instruction still has usages after lowering" — and three emits that for every lit node material, so the
+// whole render goes black or bodyless while stable Chrome draws it. A run on such a build judges the browser, not the
+// item, so the harness refuses to render on it (a harness error: the run fails closed and is retried elsewhere).
+//
+// The probe compiles a CONTROL shader (`v.x`) and the REPRO (`v.xy.x`) through module + render-pipeline creation and
+// reads getCompilationInfo, the async pipeline rejection and the validation/internal error scopes. A control failure
+// means WebGPU is broken outright; a repro-only failure is exactly this compiler bug.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROKEN_COMPILER_PREFIX = exports.SELFTEST_SOURCES = exports.SELFTEST_FS_SWIZZLE = exports.SELFTEST_FS_CONTROL = exports.SELFTEST_VS = void 0;
+exports.webGpuSelfTestProbe = webGpuSelfTestProbe;
+exports.decideSelfTest = decideSelfTest;
+exports.SELFTEST_VS = '@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> { return vec4<f32>(f32(i) - 1.0, 0.0, 0.0, 1.0); }';
+/** Control: a plain component read. */
+exports.SELFTEST_FS_CONTROL = 'struct O { @location(0) c: vec4<f32> };\nvar<private> v : vec4<f32>;\n@fragment fn main() -> O { var o: O; o.c = vec4<f32>(v.x); return o; }';
+/** Repro: a component read off a swizzle — what three r185 emits for every lit node material. */
+exports.SELFTEST_FS_SWIZZLE = 'struct O { @location(0) c: vec4<f32> };\nvar<private> v : vec4<f32>;\n@fragment fn main() -> O { var o: O; o.c = vec4<f32>(v.xy.x); return o; }';
+/** Page-side probe. A plain function (serialised by Playwright); takes the shader sources as its argument. */
+async function webGpuSelfTestProbe(src) {
+    const t0 = Date.now();
+    try {
+        const gpu = navigator.gpu;
+        if (!gpu)
+            return { webgpu: 'none', reason: 'navigator.gpu is undefined', ms: Date.now() - t0 };
+        const adapter = await gpu.requestAdapter();
+        if (!adapter)
+            return { webgpu: 'none', reason: 'requestAdapter() returned null', ms: Date.now() - t0 };
+        const info = adapter.info ?? {};
+        const adapterName = [info.vendor, info.architecture, info.device, info.description].filter(Boolean).join('/') || null;
+        const device = await adapter.requestDevice();
+        const compile = async (code) => {
+            const messages = [];
+            device.pushErrorScope('validation');
+            device.pushErrorScope('internal');
+            try {
+                const vs = device.createShaderModule({ code: src.vs });
+                const fs = device.createShaderModule({ code });
+                const ci = await fs.getCompilationInfo();
+                for (const m of ci.messages ?? [])
+                    if (m.type === 'error')
+                        messages.push(`compile: ${String(m.message).slice(0, 300)}`);
+                try {
+                    await device.createRenderPipelineAsync({
+                        layout: 'auto',
+                        vertex: { module: vs, entryPoint: 'vs' },
+                        fragment: { module: fs, entryPoint: 'main', targets: [{ format: 'rgba8unorm' }] },
+                        primitive: { topology: 'triangle-list' },
+                    });
+                }
+                catch (e) {
+                    messages.push(`pipeline: ${String(e?.message ?? e).slice(0, 400)}`);
+                }
+            }
+            finally {
+                const internal = await device.popErrorScope();
+                const validation = await device.popErrorScope();
+                if (internal)
+                    messages.push(`internal: ${String(internal.message).slice(0, 300)}`);
+                if (validation)
+                    messages.push(`validation: ${String(validation.message).slice(0, 300)}`);
+            }
+            return { ok: messages.length === 0, messages };
+        };
+        const control = await compile(src.control);
+        const swizzle = await compile(src.swizzle);
+        try {
+            device.destroy();
+        }
+        catch { /* best effort */ }
+        return { webgpu: 'available', adapter: adapterName, control, swizzle, ms: Date.now() - t0 };
+    }
+    catch (e) {
+        return { webgpu: 'error', reason: String(e?.message ?? e).slice(0, 300), ms: Date.now() - t0 };
+    }
+}
+exports.SELFTEST_SOURCES = { vs: exports.SELFTEST_VS, control: exports.SELFTEST_FS_CONTROL, swizzle: exports.SELFTEST_FS_SWIZZLE };
+/** Message prefix the hosted worker / reviewers can match on. */
+exports.BROKEN_COMPILER_PREFIX = 'broken WebGPU shader compiler in';
+/**
+ * Decide whether a browser may render. Pure, so the policy is unit-tested:
+ *   - repro fails while the control compiles → the known Tint swizzle bug: refuse.
+ *   - control fails too → WebGPU cannot compile a trivial shader: refuse.
+ *   - no adapter / probe threw → refuse when the route needs WebGPU, else allow (and the caller records it).
+ */
+function decideSelfTest(r, browser, opts) {
+    const label = `${browser.name} ${browser.version ?? '(unknown version)'}${browser.executablePath ? ` (${browser.executablePath})` : ''}`;
+    if (!r || typeof r !== 'object' || !r.webgpu) {
+        return opts.requireWebGpu
+            ? { ok: false, error: `WebGPU self-test returned nothing in ${label}; refusing to render a WebGPU route unverified` }
+            : { ok: true, note: 'WebGPU self-test returned nothing' };
+    }
+    if (r.webgpu === 'available') {
+        if (r.control && !r.control.ok) {
+            return { ok: false, error: `WebGPU cannot compile a trivial shader in ${label}: ${r.control.messages.join(' | ').slice(0, 400)}` };
+        }
+        if (!r.swizzle || !r.swizzle.ok) {
+            return {
+                ok: false,
+                error: `${exports.BROKEN_COMPILER_PREFIX} ${label}: a component read off a swizzle (v.xy.x, emitted by three r185 for every lit material) fails to compile` +
+                    `${r.swizzle?.messages?.length ? ` (${r.swizzle.messages.join(' | ').slice(0, 300)})` : ''}; use a Chrome-for-Testing build matching stable`,
+            };
+        }
+        return { ok: true };
+    }
+    const why = r.reason ?? r.webgpu;
+    if (opts.requireWebGpu)
+        return { ok: false, error: `no WebGPU adapter in ${label} (${why}); this route renders with WebGPU, refusing to judge a WebGL fallback no user sees` };
+    return { ok: true, note: `no WebGPU adapter (${why})` };
+}
+//# sourceMappingURL=webgpuSelfTest.js.map

package/dist/visualQa/webgpuSelfTest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgpuSelfTest.js","sourceRoot":"","sources":["../../src/visualQa/webgpuSelfTest.ts"],"names":[],"mappings":"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"}