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

package/dist/visualQa/viewer.js

@@ -0,0 +1,750 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderViewer = void 0;
+exports.capturePoseMatches = capturePoseMatches;
+exports.hostIsGone = hostIsGone;
+// THE CUSTOMISER / ITEM-VIEWER ROUTE — renders an add-on, wearable or prop where a BUYER sees it, and measures it.
+//
+// Why this exists: a Porsche 993's wheel add-ons were listed while every static composition path (customiser, item
+// preview, thumbnail, AR) drew all four replicas stacked as ONE wheel at the car's centre — the 993's `rim_*` nodes
+// sit at the origin with geometry baked at the hubs, so the socket anchor resolved to (0,0,0). In the live world the
+// rims are adopted into wheel holders and look fine, so the in-world proof passed. Nothing judged the customiser.
+//
+//   vehicle-addon            /customize/item/<hostId>  (signed in) — fit ONLY this part through the page's own card,
+//                            per declared host; frames fit.3q.front / fit.3q.rear / fit.side / fit.close / fit.xray / fit.part (+ wheel.<corner>)
+//   character-addon/wearable /customize/item/<baseId>  (signed in) — same surface on a character base, per declared
+//                            base; frames base.<id>.front / .back / .side / .close
+//   prop                     /items/<id>               (public)    — frames front / 3q / side / top
+//
+// The item is fitted by the page's own code (a catalogue click stages it locally; nothing is saved or bought), the
+// part is identified by diffing the scene's mesh set before/after the click, and its identity is proven by the
+// pinned model CID appearing in the page's own requests.
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const sharp_1 = __importDefault(require("sharp"));
+const browser_1 = require("./browser");
+const commonAsserts_1 = require("./commonAsserts");
+const resolve_1 = require("./resolve");
+const viewerPage_1 = require("./viewerPage");
+const worldWalk_1 = require("./worldWalk");
+const worldWalkMath_1 = require("./worldWalkMath");
+const viewerGeometry_1 = require("./viewerGeometry");
+const FIT_TIMEOUT_MS = 25_000;
+const LOAD_TIMEOUT_MS = 45_000;
+const ASSET_URL = /\.(glb|gltf|ktx2|bin|usdz)(\?|$)|\/content\/sha256\/|\/continuum\/(public\/)?objects\/|\/cas\//i;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The backend rate-limits bursts (429) — a customiser load alone makes ~40 API calls. Back off and retry. */
+async function withRetry(fn, tries = 5) {
+    for (let i = 0;; i++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (i >= tries - 1 || !/\b429\b/.test(String(e?.message ?? e)))
+                throw e;
+            await sleep(3000 * 2 ** i);
+        }
+    }
+}
+const renderViewer = async (ctx) => {
+    const started = Date.now();
+    const category = ctx.resolved.identity.category;
+    const route = category === 'prop' ? 'item-viewer' : 'customizer';
+    const result = {
+        route, url: '', frames: [], asserts: [], facts: { category, timings: {} }, subjects: [], errors: [],
+        renderer: null, engineVersion: null, fetchedAssets: [],
+    };
+    const timings = result.facts.timings;
+    if (category === 'vehicle' || category === 'avatar') {
+        result.errors.push(`the customiser/item-viewer route does not render a whole ${category}; command.ts routes it to its own test-grounds route`);
+        return result;
+    }
+    if (ctx.resolved.meshless) {
+        // A tune-only part (a blow-off valve is a sound) has nothing to draw: say so as a fact, not a failure.
+        result.facts.renderable = false;
+        result.facts.notRenderableReason = `${ctx.resolved.identity.title} is a meshless ${String(ctx.resolved.item.slotType ?? 'add-on')} (no model variant in its pinned package): nothing to render or place`;
+        result.subjects = ctx.resolved.hostIds.map((id) => ({ id, title: id, role: category === 'vehicle-addon' ? 'host' : 'base' }));
+        return result;
+    }
+    const modelHex = (0, resolve_1.hexOf)(ctx.resolved.modelCid);
+    if (!modelHex)
+        result.errors.push('the pinned package names no model CID, so the rendered bytes cannot be proven to be the pinned model');
+    if (route === 'customizer' && !ctx.storageState) {
+        result.errors.push('the customiser needs a signed-in storageState (ctx.storageState); none was given');
+        return result;
+    }
+    const b = await (0, browser_1.launchVqaBrowser)({ storageState: route === 'customizer' ? ctx.storageState : undefined, executablePath: ctx.executablePath });
+    await b.ctx.addInitScript({ content: viewerPage_1.CONTROLS_HOOK });
+    const requests = [];
+    b.ctx.on('request', (req) => { const u = req.url(); if (ASSET_URL.test(u) && !requests.includes(u))
+        requests.push(u); });
+    let walkHosts = [];
+    try {
+        if (route === 'item-viewer')
+            await runProp(ctx, b, result);
+        else {
+            const declared = (ctx.hostIds?.length ? ctx.hostIds : ctx.resolved.hostIds).filter(Boolean);
+            // A base/host the catalogue no longer has (archived or deleted after the add-on declared it) cannot be rendered by
+            // anyone: skip it as a recorded fact instead of failing the whole run on the page's "Universal item not found". Only
+            // when the hosts were not named explicitly, and only on a definite 404 (any other status still surfaces as an error).
+            const hosts = [];
+            const gone = [];
+            for (const id of declared) {
+                if (!ctx.hostIds?.length && await hostIsGone(ctx.apiBase, id))
+                    gone.push(id);
+                else
+                    hosts.push(id);
+            }
+            if (gone.length)
+                result.facts.skippedHosts = gone.map((id) => ({ id, reason: `GET /universal-items/${id} answers 404: the ${category === 'vehicle-addon' ? 'host' : 'base'} no longer exists` }));
+            if (!hosts.length && gone.length)
+                result.errors.push(`every declared ${category === 'vehicle-addon' ? 'host' : 'base'} no longer exists (${gone.join(', ')}) — nothing to fit it to`);
+            else if (!hosts.length)
+                result.errors.push(`${category} declares no ${category === 'vehicle-addon' ? 'host' : 'base'} item ids (addOn.baseItemIds is empty) — nothing to fit it to`);
+            for (const hostId of hosts) {
+                const t = Date.now();
+                try {
+                    if (category === 'vehicle-addon')
+                        await runVehicleHost(ctx, b, result, hostId);
+                    else
+                        await runCharacterBase(ctx, b, result, hostId);
+                }
+                catch (e) {
+                    result.errors.push(`${hostId}: ${String(e?.message ?? e).split('\n')[0]}`);
+                }
+                timings[`subject.${hostId}`] = Date.now() - t;
+                ctx.log(`viewer.${hostId}`, { ms: timings[`subject.${hostId}`], asserts: result.asserts.filter((a) => a.subject === hostId).map((a) => `${a.id}:${a.pass ? 'pass' : 'FAIL'}`) });
+            }
+            walkHosts = category === 'vehicle-addon' ? [] : hosts;
+        }
+        result.renderer = await (0, browser_1.rendererInfo)(b.page);
+    }
+    finally {
+        result.fetchedAssets = [...new Set([...b.fetchedAssets, ...requests])];
+        if (b.pageErrors.length)
+            result.facts.pageErrors = b.pageErrors.slice(0, 20);
+        await b.close();
+    }
+    // World walk (wearables, character add-ons): the item worn on each base in the test grounds and walked, after the
+    // customiser browser is closed so a run never holds two browsers.
+    const walk = (0, worldWalkMath_1.worldWalkEnabled)(category, ctx.worldWalk);
+    if (walkHosts.length && !walk.enabled)
+        result.facts.worldWalk = { skipped: walk.reason };
+    else if (walkHosts.length) {
+        const walkFacts = {};
+        result.facts.worldWalk = walkFacts;
+        for (const hostId of walkHosts) {
+            // a part drawn by no surface on this base by design (a tuning-only opening) has nothing to wear
+            if ((result.facts.bases?.[hostId])?.renderable === false) {
+                walkFacts[hostId] = { skipped: 'not renderable on this base' };
+                continue;
+            }
+            const t = Date.now();
+            const title = result.subjects.find((s) => s.id === hostId)?.title ?? hostId;
+            const w = await (0, worldWalk_1.runWearWalk)(ctx, hostId, title);
+            result.frames.push(...w.frames);
+            result.asserts.push(...w.asserts);
+            result.errors.push(...w.errors);
+            result.fetchedAssets.push(...w.fetchedAssets.filter((u) => !result.fetchedAssets.includes(u)));
+            walkFacts[hostId] = w.facts;
+            timings[`walk.${hostId}`] = Date.now() - t;
+        }
+    }
+    const subjectsFacts = Object.values({ ...(result.facts.hosts ?? {}), ...(result.facts.bases ?? {}) });
+    if (subjectsFacts.length && subjectsFacts.every((f) => f.renderable === false) && !result.frames.length) {
+        // Nothing is drawn on any host BY DESIGN (tuning-only openings): no bytes to prove, nothing to judge.
+        result.facts.renderable = false;
+        result.facts.notRenderableReason = subjectsFacts.map((f) => f.notRenderableReason).join(' ');
+    }
+    else if (modelHex) {
+        const proof = requests.filter((u) => u.includes(modelHex));
+        result.facts.modelIdentity = { modelCid: ctx.resolved.modelCid, fetched: proof };
+        if (!proof.length)
+            result.errors.push(`rendered bytes are not the pinned model: no request the page made carried ${modelHex}`);
+    }
+    timings.total = Date.now() - started;
+    return result;
+};
+exports.renderViewer = renderViewer;
+// ── Shared page plumbing ─────────────────────────────────────────────────────────────────────────────────────────
+async function sceneFrame(page) {
+    const f = await (0, browser_1.findFrame)(page, () => { const s = window.__vqa?.scene; if (!s)
+        return false; let n = 0; s.traverse((o) => { if (o.isMesh)
+        n++; }); return n > 0; }, LOAD_TIMEOUT_MS);
+    await f.evaluate(commonAsserts_1.INSTALL_SCENE_STATS);
+    await f.evaluate(viewerPage_1.INSTALL_VIEWER_PAGE);
+    return f;
+}
+/** Wait until `probe` returns the same number `stable` polls in a row (and it satisfies `ok`). */
+async function settle(frame, probe, ok, timeoutMs, stable = 3, everyMs = 300) {
+    const t0 = Date.now();
+    let last = -1;
+    let same = 0;
+    while (Date.now() - t0 < timeoutMs) {
+        const n = (await frame.evaluate(probe).catch(() => -1));
+        if (n === last && ok(n)) {
+            if (++same >= stable)
+                return n;
+        }
+        else {
+            same = 0;
+            last = n;
+        }
+        await sleep(everyMs);
+    }
+    return last;
+}
+async function viewportAttrs(page) {
+    return page.evaluate(() => {
+        const out = {};
+        for (const sel of ['[data-equip-state]', '[data-equip-viewport]']) {
+            const el = document.querySelector(sel);
+            if (el)
+                for (const a of el.attributes)
+                    if (a.name.startsWith('data-'))
+                        out[a.name] = a.value;
+        }
+        return out;
+    });
+}
+const parseVec = (s, fallback) => {
+    const v = (s ?? '').split(',').map(Number);
+    return v.length === 3 && v.every(Number.isFinite) ? v : fallback;
+};
+/** A screenshot is admissible only when a completed draw to its own canvas used the requested pose. */
+function capturePoseMatches(aim, actual) {
+    const draw = actual?.draw;
+    const vec = (v) => Array.isArray(v) && v.length === 3 && v.every(Number.isFinite);
+    if (!aim?.ok || !draw || !vec(aim.camera) || !vec(aim.centre) || !vec(actual.pos) || !vec(actual.matrixWorld)
+        || !vec(draw.pos) || !vec(draw.matrixWorld) || !vec(draw.direction))
+        return false;
+    if (![aim.cameraId, aim.rendererId, aim.canvasId].every((n) => Number.isInteger(n) && n > 0))
+        return false;
+    if (['cameraId', 'rendererId', 'canvasId'].some((k) => actual[k] !== aim[k] || draw[k] !== aim[k]))
+        return false;
+    if (!Number.isFinite(draw.frame) || draw.frame <= aim.beforeDrawFrame || actual.view
+        || actual.fov !== aim.fov || actual.aspect !== aim.aspect)
+        return false;
+    const near = (a, b) => a.every((n, i) => Math.abs(n - b[i]) <= 0.001);
+    const matrix = (v) => Array.isArray(v) && v.length === 16 && v.every(Number.isFinite);
+    const matricesNear = (a, b, tolerance) => a.every((n, i) => Math.abs(n - b[i]) <= tolerance);
+    if (![aim.worldMatrix, aim.projection, actual.worldMatrix, actual.projection, draw.worldMatrix, draw.projection].every(matrix)
+        || !Number.isFinite(aim.zoom) || actual.zoom !== aim.zoom || draw.zoom !== aim.zoom || draw.view
+        || ![actual.worldMatrix, draw.worldMatrix].every((v) => matricesNear(v, aim.worldMatrix, 0.001))
+        || ![actual.projection, draw.projection].every((v) => matricesNear(v, aim.projection, 1e-8)))
+        return false;
+    if (![actual.pos, actual.matrixWorld, draw.pos, draw.matrixWorld].every((v) => near(v, aim.camera)))
+        return false;
+    const expected = aim.centre.map((n, i) => n - aim.camera[i]);
+    const el = Math.hypot(...expected), dl = Math.hypot(...draw.direction);
+    return el > 0 && dl > 0 && expected.reduce((n, v, i) => n + v * draw.direction[i], 0) / (el * dl) >= 0.9999;
+}
+/** Aim the page's own camera at each shot's box and screenshot the canvas. Returns frames + image stats. */
+async function shoot(frame, outDir, subject, shots, result) {
+    if (!await frame.evaluate(() => __vqv.isolateCanvas())) {
+        result.errors.push('no unique captured subject canvas');
+        return [];
+    }
+    await frame.evaluate(() => document.querySelector('[data-vqv-canvas]')?.scrollIntoView({ block: 'center' }));
+    const images = [];
+    const rig = await frame.evaluate(() => __vqv.rig());
+    if (!rig.controls)
+        result.facts.cameraControlsHooked = false;
+    try {
+        for (const s of shots) {
+            const aim = await frame.evaluate(([min, max, dir, margin, fit]) => __vqv.aim(min, max, dir, margin, fit), [s.box.min, s.box.max, s.dir, s.margin ?? 1.1, s.fit ?? 'box']);
+            if (!aim.ok) {
+                result.errors.push(`${s.id}: camera could not be aimed (${aim.why})`);
+                continue;
+            }
+            const rendered = await frame.evaluate(() => __vqv.frames(4));
+            await sleep(120);
+            const beforeCapture = await frame.evaluate(() => globalThis.__vqv.renderCam());
+            if (!capturePoseMatches(aim, beforeCapture)) {
+                result.errors.push(`${s.id}: completed canvas draw does not match requested camera pose`);
+                continue;
+            }
+            const file = node_path_1.default.join('frames', `${s.id.replace(/[^A-Za-z0-9._-]/g, '_')}.jpg`);
+            const abs = node_path_1.default.join(outDir, file);
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(abs), { recursive: true });
+            const loc = frame.locator('[data-vqv-canvas]').first();
+            const buf = await loc.screenshot({ type: 'jpeg', quality: 84 });
+            const afterCapture = await frame.evaluate(() => globalThis.__vqv.renderCam());
+            if (!capturePoseMatches(aim, afterCapture) || afterCapture.draw.frame < beforeCapture.draw.frame) {
+                result.errors.push(`${s.id}: captured canvas camera changed during screenshot`);
+                continue;
+            }
+            node_fs_1.default.writeFileSync(abs, buf);
+            const box = await loc.boundingBox();
+            const f = { id: s.id, label: s.label, group: s.group, file, width: Math.round(box?.width ?? 0), height: Math.round(box?.height ?? 0), ...(subject ? { subject } : {}) };
+            result.frames.push(f);
+            const st = await (0, commonAsserts_1.imageStats)(abs);
+            images.push({ ...st, file });
+            (result.facts.cameras ??= {})[s.id] = { ...aim, renders: rendered,
+                beforeCapture, after: afterCapture };
+        }
+    }
+    finally {
+        // Hand the surface its own camera back once the fitted frames are grabbed.
+        await frame.evaluate(() => __vqv.releaseCam()).catch(() => undefined);
+    }
+    return images;
+}
+/** SceneStats where bounds are the LARGEST single instance (an instance is the item; four wheels are not one 2 m item). */
+function perInstanceStats(stats, instances) {
+    const biggest = instances.filter((i) => i.bounds).sort((a, b) => Math.max(...(b.bounds.size ?? [0])) - Math.max(...(a.bounds.size ?? [0])))[0];
+    return biggest?.bounds ? { ...stats, bounds: { min: biggest.bounds.min, max: biggest.bounds.max, size: biggest.bounds.size ?? [0, 0, 0] } } : stats;
+}
+/** Fit the item through the customiser's own catalogue card. Returns which tile was used. */
+async function fitThroughCatalogue(page, itemId, title) {
+    // Browse everything compatible, not only owned copies.
+    const allTab = page.locator('button', { hasText: /^\s*All compatible\s*$/i }).first();
+    if (await allTab.isVisible().catch(() => false))
+        await allTab.click().catch(() => undefined);
+    const search = page.locator('[data-addon-catalogue-panel] input, input[placeholder*="Search"]').first();
+    const tryFind = async (needle) => {
+        await search.fill(needle);
+        await sleep(350);
+        const tiles = await page.evaluate(() => [...document.querySelectorAll('[data-addon-tile]')].map((e) => ({
+            key: e.getAttribute('data-addon-tile'), state: e.getAttribute('data-tile-state'), text: String(e.textContent ?? ''),
+        })));
+        const exact = tiles.find((t) => t.key === itemId || t.key === `try:${itemId}`);
+        if (exact)
+            return exact;
+        const lc = title.toLowerCase();
+        const byTitle = tiles.filter((t) => t.text.toLowerCase().includes(lc) && t.state !== 'blocked');
+        return byTitle.find((t) => t.state === 'owned') ?? byTitle.find((t) => t.state === 'equipped-elsewhere') ?? byTitle.find((t) => t.state === 'equipped') ?? null;
+    };
+    let tile = await tryFind(title);
+    if (!tile)
+        tile = await tryFind(title.split(/\s+/).slice(0, 3).join(' '));
+    if (!tile)
+        throw new Error(`the customiser lists no card for "${title}" (${itemId}) — not compatible, not listed and not owned by the QA account`);
+    if (tile.state === 'equipped')
+        return { key: tile.key, state: tile.state, via: 'already-equipped' };
+    await page.click(`[data-addon-tile="${tile.key}"]`);
+    await sleep(300);
+    const move = page.locator('[data-addon-move-confirm-accept]');
+    if (await move.isVisible().catch(() => false))
+        await move.click();
+    return { key: tile.key, state: tile.state, via: tile.key === itemId ? 'catalogue' : 'owned-copy' };
+}
+async function openCustomiser(ctx, b, hostId, result) {
+    const t0 = Date.now();
+    const url = `${ctx.webBase.replace(/\/$/, '')}/customize/item/${hostId}`;
+    if (!result.url)
+        result.url = url;
+    // One retry: a burst of 429s from the API leaves the surface on "Opening the customizer…" or an error notice.
+    for (let attempt = 0;; attempt++) {
+        await b.page.goto(url, { waitUntil: 'domcontentloaded' });
+        const ready = await b.page.waitForSelector('[data-equip-state="ready"]', { timeout: LOAD_TIMEOUT_MS / 2 }).then(() => true).catch(() => false);
+        const loaded = ready && await b.page.waitForSelector('[data-subject-loaded="true"]', { timeout: LOAD_TIMEOUT_MS / 2 }).then(() => true).catch(() => false);
+        if (loaded)
+            break;
+        const a = await viewportAttrs(b.page);
+        const notice = await b.page.evaluate(() => String(document.querySelector('[data-equip-state]')?.textContent ?? document.body?.innerText ?? '').replace(/\s+/g, ' ').slice(0, 160)).catch(() => '');
+        const why = `the customiser did not load the subject (data-equip-state=${a['data-equip-state'] ?? 'absent'}, data-subject-loaded=${a['data-subject-loaded'] ?? 'absent'}; page says: "${notice}")`;
+        if (attempt >= 1)
+            throw new Error(why);
+        (result.facts.retries ??= []).push(`${hostId}: ${why}`);
+        await sleep(8000);
+    }
+    const frame = await sceneFrame(b.page);
+    await settle(frame, () => { let n = 0; window.__vqa.scene.traverse((o) => { if (o.isMesh)
+        n++; }); return n; }, (n) => n > 0, 10_000);
+    return { frame, attrs: await viewportAttrs(b.page), loadMs: Date.now() - t0 };
+}
+async function waitForFit(page, frame) {
+    const t0 = Date.now();
+    await page.waitForFunction(() => Number(document.querySelector('[data-equip-state]')?.getAttribute('data-equip-addons') ?? '0') >= 1, null, { timeout: FIT_TIMEOUT_MS }).catch(() => undefined);
+    // Settle on the new-mesh count; stop early when the viewport reports the part as failed (refused or unloadable).
+    let last = -1;
+    let same = 0;
+    let failed = 0;
+    while (Date.now() - t0 < FIT_TIMEOUT_MS) {
+        const probe = (await frame.evaluate(() => ({ n: __vqv.newMeshCount(), failed: Number(document.querySelector('[data-equip-viewport]')?.getAttribute('data-parts-failed') ?? '0') })).catch(() => ({ n: -1, failed: 0 })));
+        failed = probe.failed;
+        if (failed > 0 && probe.n <= 0)
+            break;
+        if (probe.n === last && probe.n > 0) {
+            if (++same >= 4)
+                break;
+        }
+        else {
+            same = 0;
+            last = probe.n;
+        }
+        await sleep(250);
+    }
+    return { meshes: Math.max(0, last), ms: Date.now() - t0, failed };
+}
+// ── vehicle-addon ────────────────────────────────────────────────────────────────────────────────────────────────
+async function runVehicleHost(ctx, b, result, hostId) {
+    const item = ctx.resolved;
+    const host = await withRetry(() => (0, resolve_1.resolveItem)(ctx.apiBase, hostId));
+    result.subjects.push({ id: hostId, title: host.identity.title, role: 'host' });
+    const facts = { title: host.identity.title, hostModelCid: host.modelCid };
+    (result.facts.hosts ??= {});
+    result.facts.hosts[hostId] = facts;
+    const slotTypeOfItem = String(item.item.slotType ?? item.root?.mount?.slotType ?? '');
+    const opening = await hostOpening(ctx.apiBase, hostId, slotTypeOfItem);
+    facts.opening = opening;
+    if (opening?.tuningOnly) {
+        // The board gives this slot no attachment point: the world strips the model and the customiser mirrors it
+        // (helixgame.com lib/addons/tuning-only-slots.ts). Nothing is drawn BY DESIGN — a fact, not a failure.
+        facts.renderable = false;
+        facts.notRenderableReason = `${host.identity.title}'s ${opening.instanceId} opening is tuning-only (socket.prefer and socket.accepts are empty), so neither the world nor the customiser draws a model for ${item.identity.title}; only its tune ops apply`;
+        return;
+    }
+    const { frame, attrs, loadMs } = await openCustomiser(ctx, b, hostId, result);
+    facts.loadMs = loadMs;
+    facts.prefittedAddOns = Number(attrs['data-equip-addons'] ?? 0);
+    const forward = parseVec(attrs['data-subject-forward'], [0, 0, 1]);
+    facts.forward = { vector: forward, from: attrs['data-subject-forward-from'] ?? null };
+    const snap = await frame.evaluate(() => __vqv.snapshot());
+    const hostStats = (await frame.evaluate(() => __vqv.hostStats()));
+    const hostFrame = await frame.evaluate(() => __vqv.hostFrame());
+    const drawnWheels = await frame.evaluate(() => __vqv.hostWheels());
+    facts.snapshot = snap;
+    facts.hostBounds = hostStats?.bounds ?? null;
+    facts.hostFrame = hostFrame;
+    facts.hostDrawnWheels = drawnWheels;
+    const hostOrigin = hostFrame?.origin ?? [0, 0, 0];
+    const tile = await fitThroughCatalogue(b.page, item.identity.itemId, item.identity.title);
+    facts.tile = tile;
+    const fit = await waitForFit(b.page, frame);
+    facts.fitMs = fit.ms;
+    facts.viewport = Object.fromEntries(Object.entries(await viewportAttrs(b.page)).filter(([k]) => k.startsWith('data-parts') || k === 'data-equip-addons'));
+    if (fit.meshes === 0) {
+        result.errors.push(fit.failed
+            ? `${hostId}: the customiser refused or failed to load "${item.identity.title}" (data-parts-failed=${fit.failed}); nothing was drawn`
+            : `${hostId}: fitting "${item.identity.title}" drew no new mesh within ${FIT_TIMEOUT_MS / 1000}s`);
+        return;
+    }
+    const instances = (await frame.evaluate(() => __vqv.instances()));
+    const partStats = (await frame.evaluate(() => __vqv.partStats()));
+    facts.instances = instances.map((i) => ({ ...i, centre: i.bounds ? (0, viewerGeometry_1.centreOf)(i.bounds) : null }));
+    facts.partBounds = partStats.bounds;
+    const rootDoc = item.root ?? {};
+    const mount = (rootDoc.mount ?? {});
+    const slotType = String(item.item.slotType ?? mount.slotType ?? '');
+    const isWheel = /^vehicle\.wheels?@/.test(slotType) || (mount.sockets ?? []).some((s) => /^wheel_/.test(s));
+    let socketAssert;
+    let hubs = [];
+    if (isWheel) {
+        const physics = (0, viewerGeometry_1.chassisPhysics)(host.root);
+        const derived = (0, viewerGeometry_1.deriveHubs)(drawnWheels, physics, { bounds: hostStats?.bounds ?? null, forward, groundY: hostStats?.bounds?.min[1] ?? null });
+        hubs = derived.hubs;
+        facts.hubs = { source: derived.source, hubs: derived.hubs, physics, crossCheck: derived.crossCheck, crossCheckOk: derived.crossCheckOk };
+        socketAssert = (0, viewerGeometry_1.wheelAtSocketAssert)(hostId, instances, derived.hubs, { count: Number(mount.count ?? 4), sockets: mount.sockets ?? [] }, hostOrigin);
+        if (derived.crossCheckOk === false) {
+            socketAssert.detail += `; note: the host's drawn wheels disagree with its physics (${derived.crossCheck.disagreements.join(', ')})`;
+        }
+    }
+    else {
+        const socketNames = [...new Set(instances.map((i) => i.socket).filter((s) => !!s))];
+        const nodes = socketNames.length ? await frame.evaluate((names) => __vqv.nodePositions(names), socketNames) : {};
+        const sock = socketNames[0] ? nodes[socketNames[0]] : null;
+        socketAssert = (0, viewerGeometry_1.vehiclePartAtSocketAssert)(hostId, partStats.bounds, hostStats?.bounds, {
+            slotType, forward, hostOrigin,
+            socket: sock ? { name: socketNames[0], at: sock.drawn ? (0, viewerGeometry_1.centreOf)(sock.drawn) : sock.origin } : null,
+        });
+        facts.sockets = nodes;
+    }
+    result.asserts.push(socketAssert);
+    // ── Frames ──
+    const part = partStats.bounds;
+    const whole = (0, viewerGeometry_1.unionBox)([hostStats?.bounds, part]) ?? part;
+    const dirs = (0, viewerGeometry_1.viewDirs)(forward);
+    const shots = [
+        { id: `addon.${hostId}.fit.3q.front`, label: `${item.identity.title} fitted to ${host.identity.title} — front three-quarter`, group: 'fit', box: whole, dir: dirs.q3front, margin: 1.06, fit: 'scene' },
+        { id: `addon.${hostId}.fit.3q.rear`, label: `${item.identity.title} fitted to ${host.identity.title} — rear three-quarter`, group: 'fit', box: whole, dir: dirs.q3rear, margin: 1.06, fit: 'scene' },
+        { id: `addon.${hostId}.fit.side`, label: `${item.identity.title} fitted to ${host.identity.title} — side`, group: 'fit', box: whole, dir: dirs.side, margin: 1.06, fit: 'scene' },
+    ];
+    // The close-up must SHOW the part. An engine framed on its own bounds from outside shows a quarter panel, so measure
+    // how much of the part the host hides from each candidate angle and take the least occluded; when the part is
+    // enclosed from every side, the close-up becomes the x-ray.
+    const defaultClose = isWheel ? dirs.side : /exhaust/.test(slotType) ? dirs.back : /spoiler|wing/.test(slotType) ? dirs.q3rear : dirs.q3front;
+    let xrayClose = false;
+    if (part) {
+        const closeBox = padBox(part, 0.05);
+        const occl = await chooseCloseUp(frame, closeBox, defaultClose, [dirs.q3front, dirs.q3rear, dirs.side, mirror(dirs.side), dirs.top, flipSide(dirs.q3front, forward), flipSide(dirs.q3rear, forward)]);
+        facts.closeUp = occl;
+        if (occl.best.occluded < OCCLUDED_MAX) {
+            const moved = occl.best.index !== 0;
+            shots.push({ id: `addon.${hostId}.fit.close`, label: moved
+                    ? `${item.identity.title} close-up from its least-occluded side (${pct(occl.best.occluded)} hidden by the host here; ${pct(occl.tried[0].occluded)} from the default angle)`
+                    : `${item.identity.title} close-up (framed on the part's drawn bounds)`, group: 'detail', box: closeBox, dir: occl.best.dir, margin: 1.3, fit: 'part' });
+        }
+        else {
+            xrayClose = true;
+        }
+    }
+    if (isWheel && hostStats?.bounds) {
+        const hc = (0, viewerGeometry_1.centreOf)(hostStats.bounds);
+        const radius = (0, viewerGeometry_1.chassisPhysics)(host.root).wheelRadius ?? 0.33;
+        for (const h of hubs) {
+            // Framed on the HUB — where the wheel must be — from outboard, so an empty arch is visible as empty.
+            const lateral = [h.centre[0] - hc[0], 0, h.centre[2] - hc[2]];
+            const f = forward;
+            const along = lateral[0] * f[0] + lateral[2] * f[2];
+            const out = [lateral[0] - along * f[0], 0, lateral[2] - along * f[2]];
+            const n = Math.hypot(out[0], out[2]) || 1;
+            const dir = [out[0] / n + f[0] * 0.35 * Math.sign(along || 1), 0.25, out[2] / n + f[2] * 0.35 * Math.sign(along || 1)];
+            const r = radius * 1.2;
+            shots.push({ id: `addon.${hostId}.wheel.${h.socket.replace(/^wheel_/, '')}`, label: `${h.socket} hub of ${host.identity.title} with ${item.identity.title} fitted`, group: 'wheels',
+                box: { min: [h.centre[0] - r, h.centre[1] - r, h.centre[2] - r], max: [h.centre[0] + r, h.centre[1] + r, h.centre[2] + r] }, dir, margin: 1.0 });
+        }
+    }
+    const images = await shoot(frame, ctx.outDir, hostId, shots, result);
+    if (part) {
+        // X-RAY: the host drawn translucent, the part opaque, framed on the part with enough of the car around it to judge
+        // placement, from above on the part's own end of the car.
+        const pc = (0, viewerGeometry_1.centreOf)(part);
+        const hc = hostStats?.bounds ? (0, viewerGeometry_1.centreOf)(hostStats.bounds) : pc;
+        const rearward = (pc[0] - hc[0]) * forward[0] + (pc[2] - hc[2]) * forward[2] < 0;
+        const above = norm(rearward ? [dirs.q3rear[0], 1.1, dirs.q3rear[2]] : [dirs.q3front[0], 1.1, dirs.q3front[2]]);
+        const largest = Math.max(...(part.size ?? [0.3, 0.3, 0.3]));
+        const xrayLabel = `X-RAY of ${host.identity.title}: the host body is drawn translucent (about 18% opacity) so ${item.identity.title} — drawn opaque — can be judged where it sits inside the car; not how a buyer sees it`;
+        await frame.evaluate(() => __vqv.xray(true, 0.18));
+        try {
+            const xs = [{ id: `addon.${hostId}.fit.xray`, label: xrayLabel, group: 'detail', box: padBox(part, Math.max(0.2, largest * 0.3)), dir: above, margin: 1.0 }];
+            if (xrayClose) {
+                xs.unshift({ id: `addon.${hostId}.fit.close`, label: `${item.identity.title} close-up as an X-RAY — the part is at least ${pct(OCCLUDED_MAX)} enclosed by ${host.identity.title} from every angle, so the host is drawn translucent here`, group: 'detail', box: padBox(part, 0.05), dir: facts.closeUp ? facts.closeUp.best.dir : defaultClose, margin: 1.3, fit: 'part' });
+            }
+            images.push(...await shoot(frame, ctx.outDir, hostId, xs, result));
+        }
+        finally {
+            await frame.evaluate(() => __vqv.xray(false));
+        }
+        // The same part with the host hidden: an engine or turbo sits behind body panels in every buyer-facing shot. Framed
+        // from the part's own outboard side — the least-occluded direction the close-up search already found — so a rear- or
+        // side-mounted part (an exhaust at the tail) reads head-on instead of showing its blank inboard face.
+        const partDir = facts.closeUp?.best.dir ?? defaultClose;
+        await frame.evaluate(() => __vqv.hideHost(true));
+        images.push(...await shoot(frame, ctx.outDir, hostId, [{ id: `addon.${hostId}.fit.part`, label: `${item.identity.title} as fitted, host body hidden (detail; inboard/back faces a player never sees may be culled here and are not a defect)`, group: 'detail', box: padBox(part, 0.05), dir: partDir, margin: 1.15, fit: 'part' }], result));
+        await frame.evaluate(() => __vqv.hideHost(false));
+    }
+    result.asserts.push(...(0, commonAsserts_1.commonAsserts)('vehicle-addon', perInstanceStats(partStats, instances), images, { subject: hostId }));
+}
+// ── Close-up occlusion ───────────────────────────────────────────────────────────────────────────────────────────
+/** A close-up that shows less than (1 - this) of the part moves to another angle or becomes the x-ray. */
+const OCCLUDED_MAX = 0.7;
+const pct = (v) => `${Math.round(v * 100)}%`;
+const mirror = (d) => [-d[0], d[1], -d[2]];
+/** Reflect a view direction to the subject's other side (across the forward/up plane). */
+const flipSide = (d, f) => { const l = [f[2], 0, -f[0]]; const k = 2 * (d[0] * l[0] + d[2] * l[2]); return [d[0] - k * l[0], d[1], d[2] - k * l[2]]; };
+const norm = (v) => { const n = Math.hypot(...v) || 1; return [v[0] / n, v[1] / n, v[2] / n]; };
+/** Greyscale raw grab of the canvas, downscaled (occlusion maths only; never saved). */
+async function grab(frame) {
+    await frame.evaluate(() => __vqv.frames(3));
+    const png = await frame.locator('[data-vqv-canvas]').first().screenshot({ type: 'png' });
+    return (0, sharp_1.default)(png).greyscale().resize(320, 200, { fit: 'fill' }).raw().toBuffer();
+}
+/**
+ * Share of the part's pixels the host covers from `dir`: part-only render vs background gives the part's mask; the
+ * full render differing from the part-only render inside that mask is occlusion.
+ */
+async function occlusionFrom(frame, box, dir) {
+    await frame.evaluate(() => __vqv.isolateCanvas());
+    await frame.evaluate(([min, max, d]) => __vqv.aim(min, max, d, 1.3, 'part'), [box.min, box.max, dir]);
+    const full = await grab(frame);
+    await frame.evaluate(() => __vqv.hideHost(true));
+    let partOnly;
+    let bg;
+    try {
+        partOnly = await grab(frame);
+        await frame.evaluate(() => __vqv.hidePart(true));
+        try {
+            bg = await grab(frame);
+        }
+        finally {
+            await frame.evaluate(() => __vqv.hidePart(false));
+        }
+    }
+    finally {
+        await frame.evaluate(() => __vqv.hideHost(false));
+    }
+    let mask = 0;
+    let hidden = 0;
+    for (let i = 0; i < partOnly.length; i++) {
+        if (Math.abs(partOnly[i] - bg[i]) <= 10)
+            continue;
+        mask++;
+        if (Math.abs(full[i] - partOnly[i]) > 28)
+            hidden++;
+    }
+    return { occluded: mask ? hidden / mask : 1, partPixels: mask };
+}
+async function chooseCloseUp(frame, box, first, others) {
+    const tried = [];
+    const firstO = await occlusionFrom(frame, box, first);
+    tried.push({ dir: first, ...firstO });
+    if (firstO.occluded >= OCCLUDED_MAX) {
+        for (const d of others) {
+            if (Math.hypot(d[0] - first[0], d[1] - first[1], d[2] - first[2]) < 1e-3)
+                continue;
+            const o = await occlusionFrom(frame, box, d);
+            tried.push({ dir: d, ...o });
+            if (o.occluded < 0.3)
+                break; // good enough; stop searching
+        }
+    }
+    let bi = 0;
+    tried.forEach((t, i) => { if (t.occluded < tried[bi].occluded - 0.05)
+        bi = i; });
+    const r = (v) => Math.round(v * 1000) / 1000;
+    return { tried: tried.map((t) => ({ ...t, occluded: r(t.occluded) })), best: { index: bi, dir: tried[bi].dir, occluded: r(tried[bi].occluded) } };
+}
+/** True only when the public catalogue answers 404 for this item: it was archived or deleted. Anything else (network, 5xx) is "not known to be gone". */
+async function hostIsGone(apiBase, hostId, fetchImpl = fetch) {
+    try {
+        const res = await withRetry(async () => {
+            const r = await fetchImpl(`${apiBase.replace(/\/$/, '')}/api/v1/universal-items/${hostId}`, { headers: { accept: 'application/json' } });
+            if (r.status === 429 || r.status >= 500)
+                throw new Error(`item → ${r.status}`);
+            return r;
+        });
+        return res.status === 404;
+    }
+    catch {
+        return false;
+    }
+}
+/** The host board's opening for a slot type (public `GET /universal-items/:id/slots`), and whether it is tuning-only. */
+async function hostOpening(apiBase, hostId, slotType) {
+    try {
+        const res = await withRetry(async () => {
+            const r = await fetch(`${apiBase.replace(/\/$/, '')}/api/v1/universal-items/${hostId}/slots`, { headers: { accept: 'application/json' } });
+            if (r.status === 429)
+                throw new Error('slots → 429');
+            return r;
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        const slot = (body.slots ?? []).find((s) => s.slotType === slotType);
+        if (!slot)
+            return null;
+        const sock = slot.socket;
+        const tuningOnly = !!sock && Array.isArray(sock.prefer) && Array.isArray(sock.accepts) && sock.prefer.length === 0 && sock.accepts.length === 0;
+        return { instanceId: String(slot.instanceId ?? slotType), socket: sock ?? null, tuningOnly };
+    }
+    catch {
+        return null;
+    }
+}
+/** Bounds in the frame of a uniformly scaled node at `origin` (undo a viewer's presentation scale). */
+function unscale(b, scale, origin) {
+    if (!scale || Math.abs(scale - 1) < 1e-4)
+        return { ...b, size: b.size ?? [b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2]] };
+    const f = (v) => [0, 1, 2].map((i) => Math.round(((v[i] - origin[i]) / scale) * 10000) / 10000);
+    const min = f(b.min);
+    const max = f(b.max);
+    return { min, max, size: [0, 1, 2].map((i) => Math.round((max[i] - min[i]) * 10000) / 10000) };
+}
+const padBox = (b, p) => ({ min: [b.min[0] - p, b.min[1] - p, b.min[2] - p], max: [b.max[0] + p, b.max[1] + p, b.max[2] + p] });
+// ── character-addon / wearable ───────────────────────────────────────────────────────────────────────────────────
+async function runCharacterBase(ctx, b, result, baseId) {
+    const item = ctx.resolved;
+    const category = item.identity.category;
+    const base = await withRetry(() => (0, resolve_1.resolveItem)(ctx.apiBase, baseId)).catch(() => null);
+    const baseTitle = base?.identity.title ?? baseId;
+    result.subjects.push({ id: baseId, title: baseTitle, role: 'base' });
+    const facts = { title: baseTitle };
+    (result.facts.bases ??= {});
+    result.facts.bases[baseId] = facts;
+    const { frame, attrs, loadMs } = await openCustomiser(ctx, b, baseId, result);
+    facts.loadMs = loadMs;
+    facts.prefittedAddOns = Number(attrs['data-equip-addons'] ?? 0);
+    facts.pose = attrs['data-character-preview-pose'] ?? null;
+    const forward = parseVec(attrs['data-subject-forward'], [0, 0, 1]);
+    facts.snapshot = await frame.evaluate(() => __vqv.snapshot());
+    const bodyStats = (await frame.evaluate(() => __vqv.hostStats()));
+    const bones = (await frame.evaluate(() => __vqv.bones()));
+    const baseFrame = await frame.evaluate(() => __vqv.hostFrame());
+    const bodyPoints = (await frame.evaluate(() => __vqv.sampleBody(12000)));
+    facts.bodyBounds = bodyStats?.bounds ?? null;
+    facts.bones = Object.keys(bones).length;
+    facts.keyBones = Object.fromEntries(['head', 'neck', 'pelvis', 'spine', 'foot_l', 'foot_r', 'calf_l', 'calf_r', 'hand_l', 'hand_r'].map((k) => [k, (0, viewerGeometry_1.findBone)(bones, k)]));
+    facts.baseOrigin = baseFrame?.origin ?? null;
+    const tile = await fitThroughCatalogue(b.page, item.identity.itemId, item.identity.title);
+    facts.tile = tile;
+    const fit = await waitForFit(b.page, frame);
+    facts.fitMs = fit.ms;
+    facts.viewport = Object.fromEntries(Object.entries(await viewportAttrs(b.page)).filter(([k]) => k.startsWith('data-parts') || k.startsWith('data-character') || k === 'data-equip-addons'));
+    if (fit.meshes === 0) {
+        result.errors.push(fit.failed
+            ? `${baseId}: the customiser refused or failed to load "${item.identity.title}" (data-parts-failed=${fit.failed}); nothing was drawn`
+            : `${baseId}: fitting "${item.identity.title}" drew no new mesh within ${FIT_TIMEOUT_MS / 1000}s`);
+        return;
+    }
+    const instances = (await frame.evaluate(() => __vqv.instances()));
+    const partStats = (await frame.evaluate(() => __vqv.partStats()));
+    const itemPoints = (await frame.evaluate(() => __vqv.samplePart(5000)));
+    facts.instances = instances.map((i) => ({ key: i.key, attachedTo: i.attachedTo, meshes: i.meshes, bounds: i.bounds, centre: i.bounds ? (0, viewerGeometry_1.centreOf)(i.bounds) : null }));
+    facts.partBounds = partStats.bounds;
+    const slot = String(item.item.slotType ?? '');
+    const body = (bodyStats?.bounds ?? null);
+    const baseOrigin = baseFrame?.origin ?? [0, 0, 0];
+    if (category === 'character-addon') {
+        result.asserts.push((0, viewerGeometry_1.characterAtSocketAssert)(baseId, slot, partStats.bounds, bones, body, baseOrigin, instances.length));
+    }
+    const onBody = (0, viewerGeometry_1.onBodyAssert)(baseId, slot, itemPoints, bones, body);
+    const floating = (0, viewerGeometry_1.notFloatingAssert)(baseId, itemPoints, bodyPoints);
+    result.asserts.push(onBody, floating);
+    facts.regionOverlap = onBody.measured;
+    facts.bodyDistance = floating.measured;
+    const dirs = (0, viewerGeometry_1.viewDirs)(forward);
+    const part = partStats.bounds;
+    const whole = (0, viewerGeometry_1.unionBox)([body, part]) ?? part;
+    const shots = [
+        { id: `base.${baseId}.front`, label: `${item.identity.title} on ${baseTitle} — front`, group: 'fit', box: whole, dir: dirs.front, margin: 1.06, fit: 'scene' },
+        { id: `base.${baseId}.back`, label: `${item.identity.title} on ${baseTitle} — back`, group: 'fit', box: whole, dir: dirs.back, margin: 1.06, fit: 'scene' },
+        { id: `base.${baseId}.side`, label: `${item.identity.title} on ${baseTitle} — side`, group: 'fit', box: whole, dir: dirs.side, margin: 1.06, fit: 'scene' },
+    ];
+    if (part)
+        shots.push({ id: `base.${baseId}.close`, label: `${item.identity.title} on ${baseTitle} — close-up on the item`, group: 'detail', box: padBox(part, 0.04), dir: dirs.q3front, margin: 1.35, fit: 'part' });
+    const images = await shoot(frame, ctx.outDir, baseId, shots, result);
+    result.asserts.push(...(0, commonAsserts_1.commonAsserts)(category, partStats, images, { subject: baseId, slot: category === 'wearable' ? slot : null, bodyHeight: body ? body.max[1] - body.min[1] : null }));
+}
+// ── prop ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+async function runProp(ctx, b, result) {
+    const item = ctx.resolved;
+    const t0 = Date.now();
+    const url = `${ctx.webBase.replace(/\/$/, '')}/items/${item.identity.itemId}`;
+    result.url = url;
+    await b.page.goto(url, { waitUntil: 'domcontentloaded' });
+    const frame = await sceneFrame(b.page);
+    await frame.evaluate(() => document.querySelector('canvas')?.scrollIntoView({ block: 'center' }));
+    // Settle on the drawn triangle count, not on time: KTX2 and LODs arrive after the first mesh.
+    await settle(frame, () => { const s = __vqv.subjectStats(); return s ? s.triangles : 0; }, (n) => n > 0, LOAD_TIMEOUT_MS, 4, 400);
+    result.facts.timings.load = Date.now() - t0;
+    const stats = (await frame.evaluate(() => __vqv.subjectStats()));
+    if (!stats || !stats.bounds) {
+        result.errors.push('the public item viewer drew no item geometry');
+        return;
+    }
+    // The public viewer fits every model to a ~2.15 m stage (helixgame.com item-viewer.tsx fitModelToStage). Judge
+    // the item's AUTHORED size: divide the drawn bounds by that presentation scale.
+    const pres = (await frame.evaluate(() => __vqv.presentationScale()));
+    const box = stats.bounds;
+    const authored = unscale(box, pres.scale, pres.origin);
+    result.facts.presentation = pres;
+    result.facts.drawnBounds = box;
+    result.facts.bounds = authored;
+    result.facts.triangles = stats.triangles;
+    const dirs = (0, viewerGeometry_1.viewDirs)([0, 0, 1]);
+    const shots = [
+        { id: 'prop.front', label: `${item.identity.title} — front`, group: 'exterior', box, dir: dirs.front, margin: 1.08, fit: 'scene' },
+        { id: 'prop.3q', label: `${item.identity.title} — three-quarter`, group: 'exterior', box, dir: dirs.q3front, margin: 1.08, fit: 'scene' },
+        { id: 'prop.side', label: `${item.identity.title} — side`, group: 'exterior', box, dir: dirs.side, margin: 1.08, fit: 'scene' },
+        { id: 'prop.top', label: `${item.identity.title} — top`, group: 'exterior', box, dir: dirs.top, margin: 1.08, fit: 'scene' },
+    ];
+    const images = await shoot(frame, ctx.outDir, undefined, shots, result);
+    result.asserts.push(...(0, commonAsserts_1.commonAsserts)('prop', { ...stats, bounds: authored }, images));
+}
+//# sourceMappingURL=viewer.js.map