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

package/dist/vehicle/preview.js

@@ -0,0 +1,854 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewInputError = exports.OCCUPANT_THRESHOLD_TEXT = exports.DEFAULT_PROXY_ITEM_ID = void 0;
+exports.pickGlb = pickGlb;
+exports.locateCandidate = locateCandidate;
+exports.parseCandidatePackage = parseCandidatePackage;
+exports.describeGlb = describeGlb;
+exports.previewVerdict = previewVerdict;
+exports.assertStatus = assertStatus;
+exports.buildPreviewSummary = buildPreviewSummary;
+exports.renderAddOnPreviewText = renderAddOnPreviewText;
+exports.renderPreviewText = renderPreviewText;
+exports.candidateResolved = candidateResolved;
+exports.hostBindPreflight = hostBindPreflight;
+exports.serveLocalAudio = serveLocalAudio;
+exports.runVehiclePreview = runVehiclePreview;
+/**
+ * `helix vehicle preview <dir-or-package.json>` — see and measure a vehicle that is not published yet, in the real HELIX
+ * runtime, BEFORE the first mint locks `physics.chassis.groundToBodyOrigin` for good.
+ *
+ * The candidate (a vehicle package JSON + a GLB, both on disk) is rendered through the same harness `helix item visual-qa`
+ * uses for a published car: the hosted test-grounds world, Try Now, a QA sign-in, boarding with the real E key, and
+ * measurements taken from the DRAWN geometry against the live physics. The one difference is that a published PROXY vehicle
+ * is tried, and the Try Now session response and the model request are replaced with the candidate's package and GLB (the
+ * GLB is served from disk; nothing is uploaded). The engine is the real one, headless, with its own scratch profile.
+ * Nothing is submitted and nothing is recorded on the backend.
+ *
+ * Vehicle Package source layout: `vehicle-package.json`, `model.glb` or the one `*.glb`,
+ * optional `thumbnail.{png,jpg,webp}`.
+ *
+ * `--addon <dir>` (repeatable) previews UNPUBLISHED vehicle add-ons instead (see ./previewAddon.ts): each add-on directory (the layout
+ * `helix vehicle addon check` reads) is fitted to the candidate car, or to a published car (`--item <id>`, no car
+ * directory), by rebuilding the Try Now session's frozen runtime recipe — the engine's own fold and mount do the fitting — and the
+ * DRAWN geometry is measured in world space against its anchor (hubs, mount socket, car bounds, car origin). A tune-only
+ * add-on is judged by reading its ops back out of the live tuning.
+ *
+ * Exit: 0 every blocking check passed, 1 a check failed, 2 the harness could not measure (bad input, sign-in, no world).
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const types_1 = require("../visualQa/types");
+const vehicleStance_1 = require("../visualQa/vehicleStance");
+const vehiclePreview_1 = require("../visualQa/vehiclePreview");
+const previewAddon_1 = require("./previewAddon");
+const previewSeats_1 = require("./previewSeats");
+const validate_1 = require("./validate");
+const hostFrame_1 = require("./hostFrame");
+const vehicleCabinFit_1 = require("../visualQa/vehicleCabinFit");
+const vehicleMath_1 = require("../visualQa/vehicleMath");
+const vehiclePenetration_1 = require("../visualQa/vehiclePenetration");
+const vehiclePosture_1 = require("../visualQa/vehiclePosture");
+const vehicleGrip_1 = require("../visualQa/vehicleGrip");
+const vehiclePoses_1 = require("../visualQa/vehiclePoses");
+const wheelDesign_1 = require("./wheelDesign");
+/** A published, Try-Now-able vehicle the preview rides on. Any published vehicle works; this one is long-lived. */
+exports.DEFAULT_PROXY_ITEM_ID = '280e49b0-39e9-40cd-9d41-4cc4d9ef7ab5';
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const PACKAGE_NAMES = ['vehicle-package.json', 'vehicle.package.json', 'package.vehicle.json'];
+const THUMBNAIL_NAMES = ['thumbnail.png', 'thumbnail.jpg', 'thumbnail.jpeg', 'thumbnail.webp'];
+/** Pick the one `.glb` of a directory: `model.glb`, else the only `*.glb`. Pure over the listing. */
+function pickGlb(files) {
+    const glbs = files.filter((f) => f.toLowerCase().endsWith('.glb'));
+    if (glbs.includes('model.glb'))
+        return { glb: 'model.glb' };
+    if (glbs.length === 1)
+        return { glb: glbs[0] };
+    return { problem: glbs.length === 0 ? 'has no .glb model' : `has ${glbs.length} .glb files; name the drawn one model.glb or pass --glb` };
+}
+/** Resolve `<dir-or-package.json>` (+ `--glb`) to the files to render. Throws a one-line, actionable message. */
+function locateCandidate(target, glbOption) {
+    const abs = node_path_1.default.resolve(target);
+    let st;
+    try {
+        st = node_fs_1.default.statSync(abs);
+    }
+    catch {
+        throw new Error(`${target} does not exist`);
+    }
+    const dir = st.isDirectory() ? abs : node_path_1.default.dirname(abs);
+    let packageFile;
+    if (st.isDirectory()) {
+        packageFile = PACKAGE_NAMES.map((n) => node_path_1.default.join(dir, n)).find((f) => node_fs_1.default.existsSync(f));
+        if (!packageFile)
+            throw new Error(`${dir} has no vehicle-package.json (the helix.vehicle-package/2 JSON)`);
+    }
+    else
+        packageFile = abs;
+    let glbFile;
+    if (glbOption) {
+        glbFile = node_path_1.default.resolve(glbOption);
+        if (!node_fs_1.default.existsSync(glbFile))
+            throw new Error(`--glb ${glbOption} does not exist`);
+    }
+    else {
+        const pick = pickGlb(node_fs_1.default.readdirSync(dir));
+        if (!pick.glb)
+            throw new Error(`${dir} ${pick.problem}`);
+        glbFile = node_path_1.default.join(dir, pick.glb);
+    }
+    const thumbnailFile = THUMBNAIL_NAMES.map((n) => node_path_1.default.join(dir, n)).find((f) => node_fs_1.default.existsSync(f));
+    return { dir, packageFile, glbFile, ...(thumbnailFile ? { thumbnailFile } : {}) };
+}
+/** Parse the package file. Accepts the bare package, `{ vehiclePackage }` (a publish body) and `{ package }` (the runtime's identity wrapper). */
+function parseCandidatePackage(text, file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${file} is not JSON: ${e.message}`);
+    }
+    if (!isRecord(parsed))
+        throw new Error(`${file} must hold a JSON object (the vehicle package)`);
+    if (isRecord(parsed.vehiclePackage))
+        return parsed.vehiclePackage;
+    if (isRecord(parsed.package) && parsed.schemaVersion === undefined && (parsed.format !== undefined || parsed.checksumSha256 !== undefined))
+        return parsed.package;
+    return parsed;
+}
+/** `glTF` magic + version 2 + a sane declared length. Throws when the bytes are not a binary glTF. */
+function describeGlb(bytes, file) {
+    if (bytes.length < 20 || String.fromCharCode(bytes[0], bytes[1], bytes[2], bytes[3]) !== 'glTF')
+        throw new Error(`${file} is not a binary glTF (.glb): bad magic`);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(4, true) !== 2)
+        throw new Error(`${file} is glTF version ${view.getUint32(4, true)}, not 2`);
+    if (view.getUint32(8, true) > bytes.length)
+        throw new Error(`${file} is truncated: its header declares ${view.getUint32(8, true)} bytes, the file has ${bytes.length}`);
+    return { file, sha256: (0, vehiclePreview_1.sha256Hex)(bytes), bytes: bytes.length };
+}
+/** pass: no harness error, every blocking assert passed. fail: a blocking assert failed. error: the harness could not measure. */
+function previewVerdict(asserts, errors, frames) {
+    if (errors.length)
+        return { verdict: 'error', exitCode: 2, reasons: errors.map((e) => `harness: ${e}`) };
+    if (frames === 0)
+        return { verdict: 'error', exitCode: 2, reasons: ['harness: the render produced no frames'] };
+    const failed = asserts.filter((a) => !a.pass && a.severity === 'block');
+    if (failed.length)
+        return { verdict: 'fail', exitCode: 1, reasons: failed.map((a) => `${a.id}: ${a.detail}`) };
+    return { verdict: 'pass', exitCode: 0, reasons: [] };
+}
+const mmT = (m) => `${Math.round(m * 1000)} mm`;
+/** The thresholds behind each occupant assert, in words. Read from the same constants the judges use. */
+exports.OCCUPANT_THRESHOLD_TEXT = {
+    'vehicle.occupants.engine_current': `rendered on engine >= ${vehicleMath_1.OCCUPANT_MIN_ENGINE} (older engines do not seat on the authored H-point)`,
+    'vehicle.occupants.boarded': 'an occupant seated (real E key) and measured in every declared seat',
+    'vehicle.occupants.head_clearance': `crown >= ${mmT(vehicleMath_1.OCCUPANT_QA_THRESHOLDS.headGapMinM)} below the first roof/lining surface above it (open roof passes)`,
+    'vehicle.occupants.hips_on_seat': `lowest buttock vertex <= ${mmT(vehicleMath_1.OCCUPANT_QA_THRESHOLDS.hipFloatMaxM)} above the cushion and no more than ${mmT(vehicleMath_1.OCCUPANT_QA_THRESHOLDS.hipThroughBaseMaxM)} through the seat base`,
+    'vehicle.occupants.hips_sink_depth': `warn: buttocks sunk more than ${mmT(vehicleMath_1.OCCUPANT_QA_THRESHOLDS.hipSinkWarnM)} into the cushion`,
+    'vehicle.occupants.feet_on_floor': `each sole between ${mmT(-vehicleMath_1.OCCUPANT_QA_THRESHOLDS.footSinkMaxM)} (through) and +${mmT(vehicleMath_1.OCCUPANT_QA_THRESHOLDS.footFloatMaxM)} (hovering) of the floor/pedal under it`,
+    'vehicle.occupants.hands_on_wheel': `driver: nearest finger/hand bone of each hand <= ${mmT(vehicleMath_1.OCCUPANT_QA_THRESHOLDS.handToRimMaxM)} from the steering rim`,
+    'vehicle.occupants.penetration': `no skinned surface through the cabin deeper than ${mmT(vehiclePenetration_1.PENETRATION_THRESHOLDS.failDepthM)} over >= ${(vehiclePenetration_1.PENETRATION_THRESHOLDS.failAreaM2 * 1e4).toFixed(1)} cm², or deeper than ${mmT(vehiclePenetration_1.PENETRATION_THRESHOLDS.swallowDepthM)} over >= ${(vehiclePenetration_1.PENETRATION_THRESHOLDS.swallowAreaM2 * 1e4).toFixed(1)} cm² (>= ${vehiclePenetration_1.PENETRATION_THRESHOLDS.failMinPoints} points; hand-on-rim and sole-on-pedal only beyond ${mmT(vehiclePenetration_1.PENETRATION_THRESHOLDS.contactPairDepthM)})`,
+    'vehicle.occupants.near_contact': `warn: any contact deeper than ${mmT(vehiclePenetration_1.PENETRATION_THRESHOLDS.contactMinM)} under the fail threshold`,
+    ...vehiclePosture_1.POSTURE_THRESHOLD_TEXT,
+    ...vehicleGrip_1.GRIP_THRESHOLD_TEXT,
+    'preview.inspection.complete': 'every frame of the fixed inspection set rendered: 8 angles day and night, every wheel, every seat from first person, side glass, over the shoulder and windscreen, the driver steering left/centre/right, the stillness frames',
+    'preview.occupants.cabin_fit': `the runtime's cabin fit moved no seat more than ${mmT(vehicleCabinFit_1.CABIN_FIT_THRESHOLDS.maxMoveM)} from its authored H-point, and refused none`,
+};
+const cm = (m) => (m === null || m === undefined ? null : Math.round(m * 1000) / 10);
+function assertStatus(a) {
+    if (/^not measured/i.test(a.detail))
+        return 'NOT_MEASURED';
+    return a.pass ? 'PASS' : a.severity === 'warn' ? 'WARN' : 'FAIL';
+}
+/** Turn what the route measured into the numbers an author acts on. Pure: everything it reads is in `facts`. */
+function buildPreviewSummary(input) {
+    const { result } = input;
+    const facts = result.facts;
+    const st = facts.stance;
+    const declared = st?.declared ?? (0, vehicleStance_1.declaredStance)(input.pkg);
+    const m = st?.measured;
+    const drawn = m?.drawnGroundToBodyOriginM ?? null;
+    const phys = m?.physicsGroundToBodyOriginM ?? null;
+    const verdict = previewVerdict(result.asserts, result.errors, result.frames.length);
+    const wheels = (m?.wheels ?? []).map((w) => {
+        const row = facts.wheels?.find((r) => r.id === w.id);
+        const roll = facts.rollingRadius?.find((r) => r.id === w.id);
+        return {
+            id: w.id,
+            hub: row?.hub ?? null,
+            drawn: row?.drawnCentre ?? null,
+            deltaCm: row?.delta ? row.delta.map((v) => cm(v)) : null,
+            drawnRadiusM: w.drawnRadiusM,
+            declaredRadiusM: w.physicsRadiusM,
+            originAboveDrawnGroundM: w.drawnGroundBelowOriginM,
+            originAbovePhysicsGroundM: w.physicsGroundBelowOriginM,
+            bodyClearanceM: w.bodyClearanceM,
+            rollingRadiusM: roll?.rollingRadiusM ?? null,
+        };
+    });
+    const dDrawn = drawn !== null && declared.groundToBodyOriginM !== null ? drawn - declared.groundToBodyOriginM : null;
+    const dPhys = phys !== null && declared.groundToBodyOriginM !== null ? phys - declared.groundToBodyOriginM : null;
+    const frames = result.frames.map((f) => node_path_1.default.join(input.out, f.file));
+    const fittedRows = facts.preview?.addOns ?? [];
+    const addOnSummaries = (input.addOns ?? []).map((a, index) => {
+        const row = fittedRows.find((r) => r.itemId === a.itemId);
+        const mine = result.asserts.filter((x) => x.id.startsWith(`preview.addon.${index}.`));
+        const opsAssert = mine.find((x) => x.id.endsWith('.ops_applied'));
+        const m = opsAssert?.measured;
+        return {
+            index, dir: a.dir, title: a.title, itemId: a.itemId, slotType: a.slotType, kind: a.kind,
+            slotId: row?.slotId ?? null, fill: row?.fill ?? null, mountSocket: row?.mountSocket ?? [],
+            glb: a.glb ? { file: a.glb.file, sha256: a.glb.sha256, bytes: a.glb.bytes, servedFromDisk: facts.preview?.addOnGlbServedFromDisk?.[a.itemId] ?? 0 } : null,
+            drawn: (facts.addOn?.probe?.attach ?? []).filter((x) => x.itemId === a.itemId).map((x) => ({ name: x.name, socketNode: x.socketNode, centre: x.centre, min: x.min, max: x.max, triangles: x.triangles })),
+            tuning: m?.ops ? { ops: m.ops.length, applied: m.ops.filter((o) => o.applied).length, changedLeaves: m.changedLeaves ?? 0 } : null,
+            notes: row?.finesse ?? [],
+            pass: mine.length > 0 && mine.every((x) => x.pass || x.severity === 'warn'),
+        };
+    });
+    const carMode = !(input.addOns ?? []).length;
+    const poses = carMode ? vehiclePoses_1.POSE_IDS.map((id) => {
+        const p = facts.poses?.find((x) => x.id === id);
+        return p ? { id, label: p.label, file: p.file ? node_path_1.default.join(input.out, p.file) : null, why: p.file ? null : (p.why ?? 'not made') } : { id, label: id, file: null, why: 'the render never reached the pose phase (see errors)' };
+    }) : [];
+    const occAsserts = result.asserts.filter((a) => a.id.startsWith('vehicle.occupants.') || a.id === 'preview.occupants.cabin_fit');
+    const occupants = occAsserts.length ? occAsserts.map((a) => ({ id: a.id, status: assertStatus(a), threshold: exports.OCCUPANT_THRESHOLD_TEXT[a.id] ?? '', detail: a.detail })) : null;
+    const cfr = facts.cabinFit?.report ?? null;
+    const cabinFit = facts.cabinFit ? {
+        maxMoveM: vehicleCabinFit_1.CABIN_FIT_THRESHOLDS.maxMoveM,
+        rows: facts.cabinFit.rows,
+        steering: cfr?.steering ?? null,
+        pedals: cfr?.pedals ?? [],
+        driverFit: cfr?.driverFit ?? null,
+        warnings: cfr?.warnings ?? [],
+    } : null;
+    const sb = facts.seatBridge;
+    const rep = sb?.report ?? null;
+    const seated = facts.board?.seated ?? null;
+    const boarding = addOnSummaries.length ? null : {
+        boarded: facts.board?.ok === true,
+        seatId: seated?.seatId ?? null,
+        role: seated?.role ?? null,
+        seatKey: seated?.seatId && rep ? rep.table.candidateKeyForCabin[seated.seatId] ?? null : null,
+        candidate: rep ? { keys: rep.candidate.keys, driverKey: rep.candidate.driverKey, cabinSeats: rep.candidate.declaredCabinSeats, glbSeatNodes: rep.candidate.glbSeatNodes, platformDefault: rep.candidate.platformDefault } : null,
+        standIn: rep ? { keys: rep.proxy.keys, driverKey: rep.proxy.driverKey, cabinSeats: rep.proxy.cabinSeats, platformDefault: rep.proxy.platformDefault } : null,
+        vocabulariesIdentical: rep ? rep.table.identical : null,
+        unmappedSeats: rep?.table.unmapped ?? [],
+        bridgeInstalled: sb?.installed ? sb.installed.ok === true : null,
+        sends: sb?.log ?? [],
+        problems: rep?.table.problems ?? [],
+    };
+    return {
+        verdict: verdict.verdict,
+        exitCode: verdict.exitCode,
+        reasons: verdict.reasons,
+        mode: addOnSummaries.length ? 'addon' : 'car',
+        addOns: addOnSummaries,
+        boarding,
+        candidate: {
+            package: input.files.packageFile,
+            glb: input.glb.file,
+            glbSha256: input.glb.sha256,
+            glbBytes: input.glb.bytes,
+            thumbnail: input.files.thumbnailFile ?? null,
+            displayName: typeof input.pkg.displayName === 'string' ? input.pkg.displayName : null,
+            packageChecksumSha256: (result.facts.packageIdentity?.runtimeChecksum) ?? null,
+        },
+        proxyItem: input.proxy,
+        runtime: { renderer: result.renderer, engineVersion: result.engineVersion, world: result.url },
+        stance: {
+            declared,
+            measuredDrawnM: drawn,
+            measuredPhysicsM: phys,
+            deltaDrawnCm: cm(dDrawn),
+            deltaPhysicsCm: cm(dPhys),
+            toleranceCm: vehicleStance_1.STANCE_THRESHOLDS.groundToBodyOriginTolM * 100,
+            pitchDeg: m?.pitchDeg ?? null,
+            rollDeg: m?.rollDeg ?? null,
+            groundClearanceM: m?.lowestBodyPointM ?? null,
+            groundClearanceMesh: m?.lowestBodyMesh ?? null,
+            suggestedGroundToBodyOriginM: drawn,
+        },
+        wheels,
+        poses,
+        cabinFit,
+        occupants,
+        asserts: result.asserts.map((a) => ({ id: a.id, status: assertStatus(a), severity: a.severity, detail: a.detail })),
+        proof: {
+            sessionsRewritten: facts.preview?.sessionsRewritten ?? 0,
+            candidateGlbServedFromDisk: facts.preview?.candidateGlbServedFromDisk ?? 0,
+            candidateAudioServedFromDisk: facts.preview?.candidateAudioServedFromDisk ?? 0,
+            proxyModelFetched: facts.preview?.proxyModelFetched ?? [],
+            packageIdentityMatch: facts.packageIdentity?.match ?? null,
+            renderedBytesFetched: (facts.modelFetchedFrom?.length ?? 0) > 0,
+        },
+        files: {
+            out: input.out,
+            bundle: node_path_1.default.join(input.out, 'bundle.json'),
+            summary: node_path_1.default.join(input.out, 'preview.json'),
+            contactSheet: input.contactSheet,
+            posesSheet: input.posesSheet ?? null,
+            frames,
+        },
+        errors: result.errors,
+        timings: { totalMs: input.totalMs },
+    };
+}
+const m3 = (v) => (v === null || v === undefined ? '?' : v.toFixed(3));
+const signed = (v) => (v === null ? '?' : `${v >= 0 ? '+' : ''}${v.toFixed(1)}`);
+/** The human summary: the stance verdict first, because that is the number that locks at mint. */
+function renderAddOnPreviewText(s) {
+    const mark = s.verdict === 'pass' ? '✔' : '✖';
+    const L = [];
+    const car = s.candidate.glb ? `${s.candidate.displayName ?? node_path_1.default.basename(s.candidate.package)} (candidate car, unpublished)` : `${s.proxyItem.title} (published ${s.proxyItem.id})`;
+    L.push(`${mark} add-on preview ${s.verdict.toUpperCase()} — ${s.addOns.length} unpublished add-on${s.addOns.length === 1 ? '' : 's'} on ${car}`);
+    L.push(`  real runtime: engine ${s.runtime.engineVersion ?? '?'}; renderer ${s.runtime.renderer ?? '?'}; ${s.proof.sessionsRewritten} Try Now session rebuilt (composition fitted with the add-ons); nothing uploaded or recorded`);
+    L.push('');
+    for (const a of s.addOns) {
+        L.push(`${a.pass ? '✔' : '✖'} [${a.index}] ${a.title}  ${a.slotType}  (${a.kind})${a.slotId ? `  slot ${a.slotId}${a.fill === 'all' ? ' (fills every sibling)' : ''}` : ''}`);
+        if (a.glb)
+            L.push(`    model ${node_path_1.default.basename(a.glb.file)} ${(a.glb.bytes / 1024).toFixed(0)} KB, served from disk ${a.glb.servedFromDisk}x; drawn copies ${a.drawn.length}`);
+        for (const d of a.drawn)
+            L.push(`    ${d.name.replace(/^helix-attach:/, '').slice(-34).padEnd(34)} on ${(d.socketNode ?? '?').padEnd(10)} centre ${d.centre ? d.centre.map((v) => v.toFixed(3)).join(', ') : '?'}`);
+        if (a.tuning)
+            L.push(`    tuning: ${a.tuning.applied}/${a.tuning.ops} tune ops read back from the live tuning (${a.tuning.changedLeaves} leaves differ from stock)`);
+        for (const n of a.notes)
+            L.push(`    note: ${n}`);
+    }
+    L.push('');
+    L.push('CHECKS');
+    for (const a of s.asserts)
+        L.push(`  ${a.status.padEnd(12)} ${a.id} — ${a.detail}`);
+    for (const e of s.errors)
+        L.push(`  ERROR        ${e}`);
+    L.push('');
+    if (s.files.contactSheet)
+        L.push(`contact sheet: ${s.files.contactSheet}`);
+    L.push(`frames (${s.files.frames.length}) and bundle.json, preview.json: ${s.files.out}`);
+    L.push(`${(s.timings.totalMs / 1000).toFixed(1)} s`);
+    return L.join('\n');
+}
+function renderPreviewText(s) {
+    if (s.mode === 'addon')
+        return renderAddOnPreviewText(s);
+    const mark = s.verdict === 'pass' ? '✔' : '✖';
+    const L = [];
+    L.push(`${mark} vehicle preview ${s.verdict.toUpperCase()} — ${s.candidate.displayName ?? node_path_1.default.basename(s.candidate.package)}`);
+    L.push(`  rendered ${node_path_1.default.basename(s.candidate.glb)} (${(s.candidate.glbBytes / 1048576).toFixed(2)} MB, sha256 ${s.candidate.glbSha256.slice(0, 12)}…) with ${node_path_1.default.basename(s.candidate.package)} in the real runtime`);
+    L.push(`  via proxy item ${s.proxyItem.id} (${s.proxyItem.title}); engine ${s.runtime.engineVersion ?? '?'}; renderer ${s.runtime.renderer ?? '?'}`);
+    L.push(`  proof: ${s.proof.sessionsRewritten} session rewritten, candidate GLB served from disk ${s.proof.candidateGlbServedFromDisk}x, local audio ${s.proof.candidateAudioServedFromDisk}x, proxy model fetched ${s.proof.proxyModelFetched.length}x, package identity ${s.proof.packageIdentityMatch === null ? '?' : s.proof.packageIdentityMatch ? 'matches' : 'MISMATCH'}`);
+    L.push('');
+    const d = s.stance.declared;
+    L.push('STANCE  (physics.chassis.groundToBodyOrigin cannot change after the first mint)');
+    L.push(`  declared   groundToBodyOrigin ${m3(d.groundToBodyOriginM)} m = wheelRadius ${m3(d.wheelRadiusM)} + staticRideHeight ${m3(d.staticRideHeightM)}${d.impliedGroundToBodyOriginM !== null ? ` (= ${m3(d.impliedGroundToBodyOriginM)})` : ''}`);
+    L.push(`  measured   body origin ${m3(s.stance.measuredDrawnM)} m above the drawn tyre bottoms (${signed(s.stance.deltaDrawnCm)} cm), ${m3(s.stance.measuredPhysicsM)} m above the physics ground (${signed(s.stance.deltaPhysicsCm)} cm); tolerance ±${s.stance.toleranceCm} cm`);
+    L.push(`  attitude   pitch ${s.stance.pitchDeg ?? '?'}°  roll ${s.stance.rollDeg ?? '?'}°   ground clearance ${s.stance.groundClearanceM === null ? '?' : `${(s.stance.groundClearanceM * 100).toFixed(1)} cm`}${s.stance.groundClearanceMesh ? ` (${s.stance.groundClearanceMesh})` : ''}`);
+    const stanceAssert = s.asserts.find((a) => a.id === 'preview.stance.ride_height');
+    if (stanceAssert)
+        L.push(`  ${stanceAssert.status === 'PASS' ? '✔' : '✖'} ${stanceAssert.detail}`);
+    if (s.boarding) {
+        const b = s.boarding;
+        L.push('');
+        L.push('BOARDING  (with the candidate\'s own seat ids)');
+        L.push(`  ${b.boarded ? `seated in ${b.seatId} as ${b.role ?? '?'}${b.seatKey ? ` (candidate manifest key "${b.seatKey}")` : ''}` : 'NOT BOARDED'}`);
+        if (b.candidate)
+            L.push(`  candidate seats ${b.candidate.glbSeatNodes.join(', ') || 'none in the GLB'}; manifest keys ${b.candidate.keys.join(', ') || 'none'}${b.candidate.driverKey ? ` (driver "${b.candidate.driverKey}")` : ''}`);
+        if (b.standIn)
+            L.push(`  stand-in room seats: keys ${b.standIn.keys.join(', ') || 'none'}; ${b.vocabulariesIdentical ? 'the vocabularies agree, nothing was rewritten' : `${b.sends.filter((x) => x.translated).length} of ${b.sends.length} seat send(s) translated into the stand-in's`}`);
+        if (b.unmappedSeats.length) {
+            const granted = b.sends.filter((x) => x.synthetic?.enter && x.synthetic.ok).map((x) => x.synthetic.key);
+            L.push(`  seats the stand-in room has none of (${b.unmappedSeats.join(', ')}): granted in this page's room state, so the avatar sits in the candidate's own seat${granted.length ? ` (${[...new Set(granted)].join(', ')} boarded this way)` : ''}; the room is not told, so this preview is single-client`);
+        }
+        for (const p of b.problems)
+            L.push(`  note: ${p}`);
+    }
+    L.push('');
+    L.push('WHEELS  (body frame, metres; Δ = drawn centre − physics hub, cm)');
+    L.push('  id          origin→drawn ground  origin→physics ground  Δ x/y/z cm           drawn r  declared r  rolling r  body clearance');
+    for (const w of s.wheels) {
+        L.push(`  ${w.id.padEnd(11)} ${m3(w.originAboveDrawnGroundM).padEnd(20)} ${m3(w.originAbovePhysicsGroundM).padEnd(22)} ${(w.deltaCm ? w.deltaCm.map((v) => signed(v)).join(' / ') : '?').padEnd(19)} ${m3(w.drawnRadiusM).padEnd(8)} ${m3(w.declaredRadiusM).padEnd(11)} ${m3(w.rollingRadiusM).padEnd(10)} ${w.bodyClearanceM === null ? '?' : `${(w.bodyClearanceM * 100).toFixed(1)} cm`}`);
+    }
+    if (s.cabinFit) {
+        const cf = s.cabinFit;
+        L.push('');
+        L.push(`CABIN FIT  (where the runtime seats each occupant vs the authored seat H-point; FAIL above ${mmT(cf.maxMoveM)} or a refused seat)`);
+        L.push('  seat           status        authored H-point          runtime H-point           move     aft      lowered  headroom  crown');
+        const v = (x) => (x ? `[${x.map((n) => (Math.abs(n) < 5e-4 ? 0 : n).toFixed(3)).join(', ')}]` : '?');
+        const m = (x) => (x === null ? '?' : mmT(x));
+        for (const r of cf.rows) {
+            L.push(`  ${r.key.padEnd(14)} ${r.status.padEnd(13)} ${v(r.authoredHPoint).padEnd(25)} ${v(r.runtimeHPoint).padEnd(25)} ${m(r.moveM).padEnd(8)} ${m(r.movedAftM).padEnd(8)} ${m(r.loweredM).padEnd(8)} ${(r.headroomM === null ? 'open' : m(r.headroomM)).padEnd(9)} ${m(r.crownClearanceM)}`);
+            if (r.status === 'FAIL')
+                L.push(`    ✖ ${r.detail}`);
+            else if (r.status === 'NOT_MEASURED')
+                L.push(`    ? ${r.detail}`);
+        }
+        if (cf.steering)
+            L.push(`  steering wheel: moved ${mmT(cf.steering.movedAft)} aft, ${mmT(cf.steering.lowered)} down, radius ${mmT(cf.steering.radiusBefore)} -> ${mmT(cf.steering.radiusAfter)}, worst rim-to-skin ${cf.steering.worstClearance === null ? '?' : mmT(cf.steering.worstClearance)}${cf.steering.fullLockReachable === false ? ', full lock NOT reachable' : ''}`);
+        if (cf.pedals.length)
+            L.push(`  pedals raised: ${cf.pedals.map((p) => `${p.id} ${mmT(p.raised)}`).join(', ')}`);
+        if (cf.driverFit)
+            L.push(`  driver fit: ${cf.driverFit.status}${cf.driverFit.reason ? ` (${cf.driverFit.reason})` : ''}`);
+        for (const w of cf.warnings)
+            L.push(`  runtime warning: ${w}`);
+    }
+    if (s.occupants) {
+        L.push('');
+        L.push('OCCUPANTS  (each seat occupied by a real avatar — the platform default avatar unless HELIX_VQA_OWN_AVATAR=1; the threshold each check is judged against)');
+        for (const o of s.occupants) {
+            L.push(`  ${o.status.padEnd(12)} ${o.id} — ${o.detail}`);
+            if (o.threshold)
+                L.push(`               threshold: ${o.threshold}`);
+        }
+    }
+    L.push('');
+    L.push('CHECKS');
+    for (const a of s.asserts)
+        L.push(`  ${a.status.padEnd(12)} ${a.id} — ${a.detail}`);
+    for (const e of s.errors)
+        L.push(`  ERROR        ${e}`);
+    L.push('');
+    if (s.poses.length) {
+        L.push('POSES  (fixed views to put beside the reference photos)');
+        for (const p of s.poses)
+            L.push(`  ${p.id.padEnd(13)} ${p.file ?? `not made: ${p.why}`}`);
+        if (s.files.posesSheet)
+            L.push(`  sheet: ${s.files.posesSheet}`);
+        L.push('');
+    }
+    if (s.inspection) {
+        L.push(`INSPECTION ${s.inspection.verdict.toUpperCase()}  (the gauntlet inspection set: OPEN EVERY SHEET AND LOOK; each line is the question that sheet answers. A defect you can see is a FAIL even when every number passes.)`);
+        for (const sh of s.inspection.sheets)
+            L.push(`  ${sh.file}${sh.missing ? `  [${sh.missing} frame(s) NOT RENDERED]` : ''}\n      LOOK: ${sh.look}`);
+        L.push(`  index: ${s.inspection.index}`);
+        L.push('');
+    }
+    if (s.files.contactSheet)
+        L.push(`contact sheet: ${s.files.contactSheet}`);
+    L.push(`frames (${s.files.frames.length}) and bundle.json, preview.json: ${s.files.out}`);
+    L.push(`${(s.timings.totalMs / 1000).toFixed(1)} s`);
+    return L.join('\n');
+}
+/** The minimal ResolvedItem the vehicle route needs for a candidate that has no published record. */
+function candidateResolved(o) {
+    return {
+        identity: {
+            itemId: o.proxyId,
+            title: typeof o.pkg.displayName === 'string' ? o.pkg.displayName : o.proxyTitle,
+            category: 'vehicle',
+            itemType: 'vehicle',
+            packageVersionId: null,
+            manifestCid: null,
+            packageId: null,
+            packageVersion: 'candidate (unpublished)',
+            vehicleChecksum: null,
+        },
+        item: { id: o.proxyId, title: o.proxyTitle },
+        root: o.pkg,
+        rootRole: 'vehicle-definition',
+        modelCid: `sha256:${o.glb.sha256}`,
+        hostIds: [],
+        meshless: false,
+        candidate: null,
+    };
+}
+async function fetchProxy(apiBase, id) {
+    const res = await fetch(`${apiBase.replace(/\/$/, '')}/api/v1/universal-items/${encodeURIComponent(id)}`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(30_000) });
+    if (!res.ok)
+        throw new Error(`proxy item ${id}: HTTP ${res.status} (pass --proxy-item <a published vehicle id the QA account can try>)`);
+    const body = (await res.json());
+    const item = body.item;
+    if (!item)
+        throw new Error(`proxy item ${id}: no item in the response`);
+    if (item.itemType !== 'vehicle' && item.kind !== 'vehicle')
+        throw new Error(`proxy item ${id} is a ${item.itemType ?? item.kind ?? 'non-vehicle'}, not a vehicle`);
+    return { id, title: String(item.title ?? id) };
+}
+class PreviewInputError extends Error {
+}
+exports.PreviewInputError = PreviewInputError;
+/**
+ * Before any browser: every host-frame add-on's bind (socket, root) must resolve against the car's own nodes. The runtime
+ * throws while composing the car when it does not, the car is never presented, and the page reports no error — so a
+ * preview would sit out its whole presentation timeout. Returns the findings (errors refuse the preview).
+ */
+async function hostBindPreflight(addOns, hostGlb, hostLabel) {
+    const bound = addOns.filter((a) => (0, hostFrame_1.declaredHostBind)({ helixMeshFrame: a.frame }) !== undefined);
+    if (!bound.length)
+        return [];
+    const index = (0, validate_1.hostFrameIndexOfGlb)(hostGlb, await (0, validate_1.loadVehicleValidator)());
+    return bound.flatMap((a) => (0, hostFrame_1.checkBindAgainstHost)((0, hostFrame_1.declaredHostBind)({ helixMeshFrame: a.frame }), index, {
+        label: `add-on "${a.title.replace(/ \(unpublished preview copy\)$/, '')}" (${a.slotType})`, path: `${a.dir}/model.glb:scene.extras.helixMeshFrame.bind`, hostLabel,
+    }));
+}
+/**
+ * Give every audio row backed by a local WAV (`{ name, file }`, the way an unpublished package is authored and the way
+ * the BeamNG importer emits it) a content URL on PREVIEW_AUDIO_ORIGIN plus its checksum/bytes/cid, and return the
+ * files to serve. Rows that already carry a url are left alone. Without this the engine's validator rejects the
+ * package and the car never spawns.
+ */
+function serveLocalAudio(pkg, dir) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { collectAudioRows, localFileFor } = require('./audio');
+    const out = JSON.parse(JSON.stringify(pkg));
+    const served = new Map();
+    // Every slot asset, consumed today or not: the engine's validator requires each closure member's url.
+    for (const r of collectAudioRows(out, { includeUnconsumed: true }).rows) {
+        if (typeof r.row.url === 'string' && r.row.url)
+            continue;
+        const file = localFileFor(r.row, dir);
+        if (!file)
+            continue;
+        const bytes = node_fs_1.default.readFileSync(file);
+        const sha = (0, vehiclePreview_1.sha256Hex)(bytes);
+        served.set(sha, { file, sha256: sha, bytes: bytes.length });
+        Object.assign(r.row, {
+            url: `${vehiclePreview_1.PREVIEW_AUDIO_ORIGIN}/content/sha256/${sha.slice(0, 2)}/${sha}`,
+            checksumSha256: sha, bytes: bytes.length, cid: `cid:sha256:${sha}`, mediaType: 'audio/wav',
+        });
+    }
+    return { pkg: out, audio: [...served.values()] };
+}
+async function runVehiclePreview(opts) {
+    if (opts.referenceWheel) {
+        const w = opts.referenceWheel;
+        if (opts.addOns?.length)
+            throw new PreviewInputError('--reference-wheel judges a candidate car; it does not apply to an --addon preview');
+        if (!node_fs_1.default.existsSync(w.image))
+            throw new PreviewInputError(`--reference-wheel image not found: ${w.image}`);
+        if (w.spokeCount !== undefined && !(Number.isInteger(w.spokeCount) && w.spokeCount >= 3 && w.spokeCount <= 24))
+            throw new PreviewInputError('--reference-wheel-spokes must be a whole number from 3 to 24');
+        if (w.finish !== undefined && !wheelDesign_1.WHEEL_FINISHES.includes(w.finish))
+            throw new PreviewInputError(`--reference-wheel-finish must be one of ${wheelDesign_1.WHEEL_FINISHES.join(', ')}`);
+        if (w.crop && !(w.crop.cx > 0 && w.crop.cx < 1 && w.crop.cy > 0 && w.crop.cy < 1 && w.crop.radius > 0.05 && w.crop.radius <= 0.7))
+            throw new PreviewInputError('--reference-wheel-crop is cx,cy,radius as fractions: centre x of the width, centre y of the height, tyre radius of the shorter side (0.05 to 0.7)');
+    }
+    const t0 = Date.now();
+    const log = (k, v) => { if (!opts.quiet)
+        console.error(`[vehicle-preview] ${k} ${typeof v === 'string' ? v : JSON.stringify(v).slice(0, 300)}`); };
+    let files;
+    let pkg;
+    let glb;
+    let audio = [];
+    let addOns = [];
+    let seatNodes = [];
+    const keepCar = !opts.target;
+    // `--item <id>` alone: inspect a PUBLISHED car exactly as the runtime serves it (re-checking a listed car against the
+    // current gates). Its real package is resolved below and drives the seats, panels and lamps the route exercises.
+    const publishedCar = !opts.target && !opts.addOns?.length && !!opts.item;
+    try {
+        if (opts.addOns?.length)
+            addOns = (0, previewAddon_1.loadPreviewAddOns)(opts.addOns);
+        else if (!opts.target && !opts.item)
+            throw new Error('give a candidate car directory, --item <published vehicle id> to inspect a published car, or one or more --addon <dir>');
+        if (opts.target) {
+            files = locateCandidate(opts.target, opts.glb);
+            pkg = parseCandidatePackage(node_fs_1.default.readFileSync(files.packageFile, 'utf8'), files.packageFile);
+            const glbFileBytes = node_fs_1.default.readFileSync(files.glbFile);
+            glb = describeGlb(glbFileBytes, files.glbFile);
+            ({ pkg, audio } = serveLocalAudio(pkg, node_path_1.default.dirname(files.packageFile)));
+            try {
+                seatNodes = (0, previewSeats_1.glbSeatNodes)((0, validate_1.glbSceneFacts)(glbFileBytes).nodeNames);
+            }
+            catch {
+                seatNodes = [];
+            }
+        }
+        else {
+            // a published car: its package and model are the session's own, so these are placeholders that are never read
+            files = { dir: addOns[0]?.dir ?? process.cwd(), packageFile: '', glbFile: '' };
+            pkg = {};
+            glb = { file: '', sha256: '', bytes: 0 };
+        }
+    }
+    catch (e) {
+        throw new PreviewInputError(String(e?.message ?? e));
+    }
+    // Preflight the host-frame bind contract (no browser yet): a bind the car cannot satisfy fails here, in a second, not after
+    // a 120 s presentation timeout. A candidate car's GLB is on disk; a published car's is its pinned Package model.
+    if (addOns.some((a) => a.kind === 'host')) {
+        let hostGlb;
+        let hostLabel = 'the candidate car';
+        if (opts.target)
+            hostGlb = node_fs_1.default.readFileSync(files.glbFile);
+        else {
+            try {
+                const { getItem, defaultBytesFetch } = await Promise.resolve().then(() => __importStar(require('./platform')));
+                const { hostModel } = await Promise.resolve().then(() => __importStar(require('./addon')));
+                const { publicRequester } = await Promise.resolve().then(() => __importStar(require('./addonPublished')));
+                const api = publicRequester(opts.apiBase);
+                const carId = opts.item ?? opts.proxyItem ?? exports.DEFAULT_PROXY_ITEM_ID;
+                const item = await getItem(api, carId);
+                hostLabel = `the published car "${item.title}"`;
+                hostGlb = (await hostModel(api, item, defaultBytesFetch, opts.apiBase.replace(/\/$/, ''))).glb;
+            }
+            catch (e) {
+                log('warning', `the published car's model could not be read for the host-frame bind preflight (${String(e?.message ?? e).slice(0, 160)})`);
+            }
+        }
+        if (hostGlb) {
+            const found = await hostBindPreflight(addOns, hostGlb, hostLabel);
+            for (const i of found.filter((x) => x.level === 'warn'))
+                log('warning', `${i.code}: ${i.message}`);
+            const errors = found.filter((x) => x.level === 'error');
+            if (errors.length)
+                throw new PreviewInputError(`host-frame bind refused before launching the browser:\n${errors.map((i) => `  ${i.code}: ${i.message}\n    fix: ${i.fix}`).join('\n')}`);
+        }
+    }
+    if (opts.target) {
+        const declared = (0, vehicleStance_1.declaredStance)(pkg);
+        if (declared.groundToBodyOriginM === null)
+            log('warning', 'the package declares no physics.chassis.groundToBodyOrigin; the stance check will report what it measures');
+    }
+    const proxy = await fetchProxy(opts.apiBase, (keepCar ? opts.item : undefined) ?? opts.proxyItem ?? exports.DEFAULT_PROXY_ITEM_ID);
+    const out = node_path_1.default.resolve(opts.out ?? node_path_1.default.join(files.dir, publishedCar ? `.helix-preview-${opts.item.slice(0, 8)}` : '.helix-preview'));
+    node_fs_1.default.rmSync(node_path_1.default.join(out, 'frames'), { recursive: true, force: true });
+    node_fs_1.default.rmSync(node_path_1.default.join(out, 'poses'), { recursive: true, force: true });
+    node_fs_1.default.rmSync(node_path_1.default.join(out, 'poses.jpg'), { force: true });
+    node_fs_1.default.mkdirSync(out, { recursive: true });
+    log('candidate', { package: files.packageFile || `(published car ${proxy.id})`, glb: files.glbFile || undefined, sha256: glb.sha256.slice(0, 16), proxy: proxy.id, addOns: addOns.map((a) => `${a.kind}:${a.slotType}`), out });
+    const { mintStorageState } = await Promise.resolve().then(() => __importStar(require('../visualQa/browser')));
+    const { mintStorageStateOverHttp } = await Promise.resolve().then(() => __importStar(require('../visualQa/signIn')));
+    let storageState = opts.storageState;
+    let minted;
+    if (!storageState) {
+        if (!opts.token)
+            throw new PreviewInputError('no QA sign-in: run `helix login`, or pass --storage-state <file> / set HELIX_VQA_STORAGE_STATE');
+        minted = node_path_1.default.join(node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'helix-preview-')), 'session.json');
+        // Over plain HTTPS first (no browser, so no admission slot on a busy host); a real browser only if the website refuses that.
+        let who;
+        try {
+            who = await mintStorageStateOverHttp(opts.webBase, opts.token, minted);
+        }
+        catch (e) {
+            log('session', `HTTP sign-in refused (${String(e?.message ?? e).slice(0, 120)}); signing in through a browser`);
+            who = await mintStorageState(opts.webBase, opts.token, minted, opts.chrome);
+        }
+        storageState = minted;
+        log('session', `signed in as ${who}`);
+    }
+    // A fresh QA account would sit on the blocking "Claim your name" modal, which swallows every key the harness sends.
+    if (opts.token && !opts.storageState) {
+        try {
+            const { completeEntryFlow } = await Promise.resolve().then(() => __importStar(require('../visualQa/signIn')));
+            const entry = await completeEntryFlow(opts.apiBase, opts.token);
+            if (!entry.alreadyDone)
+                log('session', `completed the account's first-run entry flow (${entry.steps.join(', ') || 'nothing to send'}); done=${entry.done}`);
+        }
+        catch (e) {
+            log('warning', `could not check the account's first-run entry flow (${String(e?.message ?? e).slice(0, 120)}); a fresh account will sit on the Claim-your-name modal and never board`);
+        }
+    }
+    let resolved = candidateResolved({ proxyId: proxy.id, proxyTitle: proxy.title, pkg, glb });
+    if (publishedCar) {
+        const { resolveItem } = await Promise.resolve().then(() => __importStar(require('../visualQa/resolve')));
+        try {
+            resolved = await resolveItem(opts.apiBase, proxy.id, opts.token ?? null);
+        }
+        catch (e) {
+            throw new PreviewInputError(`the published car ${proxy.id} could not be resolved: ${String(e?.message ?? e).slice(0, 300)}`);
+        }
+        pkg = (resolved.root ?? {});
+        log('published', { item: proxy.id, title: resolved.identity.title, version: resolved.identity.packageVersion });
+    }
+    const { renderVehicle } = await Promise.resolve().then(() => __importStar(require('../visualQa/vehicle')));
+    const failed = (msg) => ({ route: 'test-grounds', url: '', frames: [], asserts: [], subjects: [], facts: {}, errors: [msg], renderer: null, engineVersion: null, fetchedAssets: [] });
+    let result;
+    try {
+        // A tune-only add-on is judged against the stock car: read the stock tuning first (a second, frameless load of the same world).
+        let stockTuning = null;
+        if (addOns.some((a) => a.ops.some((o) => o.v === 'tune'))) {
+            log('baseline', 'reading the stock car\'s tuning (a frameless load) to compare the tune ops against');
+            const baseDir = node_path_1.default.join(out, 'baseline');
+            node_fs_1.default.mkdirSync(baseDir, { recursive: true });
+            try {
+                const base = await renderVehicle({
+                    resolved, apiBase: opts.apiBase, webBase: opts.webBase, outDir: baseDir, storageState, executablePath: opts.chrome, log,
+                    preview: { candidate: { pkg, glb, audio, addOns: [], keepCar }, baselineOnly: true },
+                });
+                stockTuning = (base.facts.addOn?.tuning) ?? null;
+                if (!stockTuning || Object.keys(stockTuning).length < 3)
+                    log('warning', `the stock tuning could not be read (${base.errors.join('; ').slice(0, 200)})`);
+                node_fs_1.default.writeFileSync(node_path_1.default.join(baseDir, 'stock-tuning.json'), JSON.stringify(stockTuning, null, 2));
+            }
+            catch (e) {
+                log('warning', `the stock tuning pass failed: ${String(e?.message ?? e).slice(0, 200)}`);
+            }
+        }
+        const ctx = {
+            resolved, apiBase: opts.apiBase, webBase: opts.webBase, outDir: out, storageState, executablePath: opts.chrome, log,
+            preview: {
+                candidate: { pkg, glb, audio, seatNodes, ...(addOns.length ? { addOns } : {}), ...(keepCar ? { keepCar: true } : {}) },
+                ...(addOns.length ? { stockTuning, toleranceCm: opts.toleranceCm } : {}),
+                ...(!addOns.length && opts.referencePaint ? { paint: true } : {}),
+                ...(!addOns.length && opts.referenceWheel ? { wheelFace: true } : {}),
+                // occupants and the inspection set are ON unless explicitly switched off (a quick iteration loop, never a gate result)
+                ...(!addOns.length ? { phases: ['exterior', 'poses', 'articulation', 'steering', 'cabin', 'drive', ...(opts.inspection !== false ? ['inspection'] : []), ...(opts.occupants !== false ? ['occupants'] : [])] } : {}),
+            },
+        };
+        try {
+            result = await renderVehicle(ctx);
+        }
+        catch (e) {
+            result = failed(`render route threw: ${String(e?.stack ?? e).slice(0, 800)}`);
+        }
+    }
+    finally {
+        // the minted session is a live login cookie: never leave it behind
+        if (minted)
+            node_fs_1.default.rmSync(node_path_1.default.dirname(minted), { recursive: true, force: true });
+    }
+    const carName = typeof pkg.displayName === 'string' ? pkg.displayName : (keepCar ? proxy.title : 'candidate');
+    // The route labels everything with the proxy item's id (the runtime's item); to the reader this is the candidate.
+    result = {
+        ...result,
+        asserts: result.asserts.map((a) => ({ ...a, subject: 'candidate' })),
+        frames: result.frames.map((f) => ({ ...f, subject: 'candidate' })),
+        subjects: [{ id: proxy.id, title: keepCar ? proxy.title : `${carName} (via proxy ${proxy.title})`, role: 'host' }],
+    };
+    const bundle = {
+        schema: types_1.VISUAL_QA_BUNDLE_SCHEMA,
+        item: { ...resolved.identity },
+        harness: { version: 'helix-cli vehicle preview', route: result.route, url: result.url, host: node_os_1.default.hostname(), renderer: result.renderer, engineVersion: result.engineVersion, startedAt: new Date(t0).toISOString(), durationMs: Date.now() - t0, fetchedAssets: result.fetchedAssets },
+        frames: result.frames, asserts: result.asserts, facts: result.facts, subjects: result.subjects, errors: result.errors,
+    };
+    node_fs_1.default.writeFileSync(node_path_1.default.join(out, 'bundle.json'), JSON.stringify(bundle, null, 2));
+    let contactSheet = null;
+    const verdict = previewVerdict(result.asserts, result.errors, result.frames.length);
+    if (result.frames.length) {
+        const { renderContactSheet } = await Promise.resolve().then(() => __importStar(require('../visualQa/contactSheet')));
+        const sheet = await renderContactSheet({
+            title: addOns.length ? `PREVIEW — ${addOns.map((a) => a.title.replace(/ \(unpublished preview copy\)$/, '')).join(' + ').slice(0, 90)} on ${carName}` : `PREVIEW — ${typeof pkg.displayName === 'string' ? pkg.displayName : node_path_1.default.basename(files.packageFile)}`,
+            subtitle: addOns.length
+                ? `unpublished add-on${addOns.length > 1 ? 's' : ''} · ${keepCar ? `published car ${proxy.id.slice(0, 8)}` : `candidate car glb ${glb.sha256.slice(0, 12)}… via proxy ${proxy.id.slice(0, 8)}`} · ${result.renderer ?? 'renderer ?'} · engine ${result.engineVersion ?? '?'}`
+                : `unpublished candidate · glb ${glb.sha256.slice(0, 12)}… · via proxy ${proxy.id.slice(0, 8)} · ${result.renderer ?? 'renderer ?'} · engine ${result.engineVersion ?? '?'}`,
+            verdict: verdict.verdict,
+            reasons: [],
+            frames: result.frames.map((f) => ({ label: f.label, bytes: node_fs_1.default.readFileSync(node_path_1.default.join(out, f.file)) })),
+            asserts: result.asserts,
+            critic: null,
+        });
+        contactSheet = node_path_1.default.join(out, 'contact-sheet.jpg');
+        node_fs_1.default.writeFileSync(contactSheet, sheet);
+    }
+    let posesSheet = null;
+    if (!addOns.length) {
+        // the fixed appearance poses, all seven in their fixed order: a pose that could not be made keeps its tile and says why
+        const made = result.facts.poses ?? [];
+        const { renderPoseSheet } = await Promise.resolve().then(() => __importStar(require('../visualQa/contactSheet')));
+        const sheet = await renderPoseSheet({
+            title: `POSES — ${typeof pkg.displayName === 'string' ? pkg.displayName : node_path_1.default.basename(files.packageFile)}`,
+            subtitle: `fixed views, car framed by its own bounds, plain backdrop, sun and environment light only, every lamp off · glb ${glb.sha256.slice(0, 12)}… · engine ${result.engineVersion ?? '?'}`,
+            poses: vehiclePoses_1.POSE_IDS.map((id) => {
+                const p = made.find((x) => x.id === id);
+                const file = p?.file ? node_path_1.default.join(out, p.file) : null;
+                return { id, label: p?.label ?? id, bytes: file && node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file) : null, why: p?.file ? null : (p?.why ?? 'the render never reached the pose phase') };
+            }),
+        });
+        posesSheet = node_path_1.default.join(out, 'poses.jpg');
+        node_fs_1.default.writeFileSync(posesSheet, sheet);
+    }
+    // Body-paint gate: with `--reference-paint`, judge the body paint as the Try Now daylight draws it (vehicle.ts `paint`
+    // phase: paint alone, six cameras, the world's own lights) on hue, saturation, lightness and highlight wash. Rounds 3, 5
+    // and 8 shipped red-authored paint that rendered salmon with a white bonnet hotspot; the old side-pose hue check passed it.
+    if (opts.referencePaint && !addOns.length) {
+        const { judgePaint, paintReference, samplePaintView, PAINT_LIMITS } = await Promise.resolve().then(() => __importStar(require('./paintHue')));
+        const paintFacts = result.facts.paint;
+        let paintAsserts;
+        try {
+            const ref = paintReference(opts.referencePaint);
+            const pairs = (paintFacts?.views ?? []).filter((v) => v.file && v.emptyFile && node_fs_1.default.existsSync(node_path_1.default.join(out, v.file)) && node_fs_1.default.existsSync(node_path_1.default.join(out, v.emptyFile)));
+            if (!pairs.length)
+                throw new Error('the daylight paint views were not rendered (see the run errors)');
+            const stats = [];
+            for (const v of pairs)
+                stats.push(await samplePaintView({ id: v.id, paint: node_fs_1.default.readFileSync(node_path_1.default.join(out, v.file)), empty: node_fs_1.default.readFileSync(node_path_1.default.join(out, v.emptyFile)) }, ref));
+            const judged = judgePaint(opts.referencePaint, stats, (paintFacts?.materials ?? null), opts.paintToleranceDeg ?? PAINT_LIMITS.defaultHueToleranceDeg);
+            paintAsserts = judged.map((a) => ({ id: a.id, pass: a.pass, severity: 'block', detail: a.detail, measured: a.measured }));
+        }
+        catch (error) {
+            paintAsserts = [{ id: 'vehicle.paint.saturation', pass: false, severity: 'block', detail: `paint could not be sampled: ${error.message}`, measured: { referencePaint: opts.referencePaint } }];
+        }
+        result.asserts = [...result.asserts, ...paintAsserts];
+    }
+    // Wheel-design gate: with `--reference-wheel`, judge the candidate's wheel face (front left, square-on, the tyre centred) on spoke
+    // count, finish and centre cap against the reference close-up (vehicle/wheelDesign.ts). Declared values override the photo's.
+    if (opts.referenceWheel && !addOns.length) {
+        const { judgeWheelDesign, measureCandidateWheel, measureReferenceWheel } = await Promise.resolve().then(() => __importStar(require('./wheelDesign')));
+        const wf = result.facts.wheelFace;
+        let wheelAsserts;
+        try {
+            if (!wf?.file || !node_fs_1.default.existsSync(node_path_1.default.join(out, wf.file)))
+                throw new Error('the wheel face was not rendered (see the run errors)');
+            if (!node_fs_1.default.existsSync(opts.referenceWheel.image))
+                throw new PreviewInputError(`--reference-wheel image not found: ${opts.referenceWheel.image}`);
+            const cand = await measureCandidateWheel(node_path_1.default.join(out, wf.file));
+            const ref = await measureReferenceWheel(opts.referenceWheel);
+            result.facts.wheelDesign = { candidate: cand, reference: ref, declared: { spokeCount: opts.referenceWheel.spokeCount ?? null, finish: opts.referenceWheel.finish ?? null, centreCap: opts.referenceWheel.centreCap ?? null }, candidateFrame: wf.file };
+            wheelAsserts = judgeWheelDesign(cand, ref, opts.referenceWheel).map((a) => ({ id: a.id, pass: a.pass, severity: a.severity, detail: a.detail, measured: a.measured }));
+        }
+        catch (error) {
+            if (error instanceof PreviewInputError)
+                throw error;
+            wheelAsserts = [{ id: 'vehicle.wheels.design.spokes', pass: false, severity: 'block', detail: `the wheel design could not be measured: ${error.message}`, measured: { referenceWheel: opts.referenceWheel.image } }];
+        }
+        result.asserts = [...result.asserts, ...wheelAsserts];
+    }
+    // The gauntlet inspection sheets: every frame of the fixed inspection set, one question per sheet (inspectionSheets.ts).
+    // Written whenever the inspection or the occupants ran; an inspection with a hole in it fails preview.inspection.complete.
+    let inspection = null;
+    if (!addOns.length && (opts.inspection !== false || opts.occupants !== false)) {
+        try {
+            const { writeInspectionSheets } = await Promise.resolve().then(() => __importStar(require('./inspectionSheets')));
+            const w = await writeInspectionSheets({ out, carName, engineVersion: result.engineVersion, frames: result.frames, facts: result.facts, asserts: result.asserts });
+            if (opts.inspection !== false && opts.occupants !== false)
+                result.asserts = [...result.asserts, w.complete];
+            inspection = { dir: w.dir, index: node_path_1.default.join(w.dir, 'index.json'), verdict: w.index.verdict, sheets: w.index.sheets.map((s) => ({ id: s.id, file: node_path_1.default.join(w.dir, s.file), look: s.look[0] ?? '', missing: s.missing.length })) };
+        }
+        catch (e) {
+            result.asserts = [...result.asserts, { id: 'preview.inspection.complete', pass: false, severity: 'block', detail: `the inspection sheets could not be written: ${String(e?.message ?? e).slice(0, 200)}` }];
+        }
+    }
+    const summary = buildPreviewSummary({ files, glb, pkg, proxy, result, out, contactSheet, posesSheet, totalMs: Date.now() - t0, addOns });
+    summary.inspection = inspection;
+    node_fs_1.default.writeFileSync(summary.files.summary, JSON.stringify(summary, null, 2));
+    return summary;
+}
+//# sourceMappingURL=preview.js.map