@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/visualQa/vehicleMath.js

@@ -0,0 +1,967 @@
+"use strict";
+// Pure geometry + verdict functions for the vehicle render route (`vehicle.ts`). No browser, no I/O: everything here
+// takes numbers pulled out of the live scene graph and returns numbers and verdicts, so the thresholds can be
+// calibrated against real cars in `vehicle.spec.ts` (must-fail / must-pass fixtures) without a GPU.
+//
+// Frame convention: every point is in the vehicle BODY frame (the presented entity's `object3d` local space):
+// +Y up, +Z forward, +X towards the left-hand side of the car. Units are metres and radians unless named `Deg`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HIP_WINDOW_ABOVE_PELVIS_M = exports.OCCUPANT_QA_THRESHOLDS = exports.OCCUPANT_MIN_ENGINE = exports.qAngleDeg = exports.qInv = exports.qMul = exports.r3v = exports.r4 = exports.norm = exports.len = exports.cross = exports.scale = exports.add = exports.sub = exports.dot = exports.VEHICLE_QA_THRESHOLDS = void 0;
+exports.axleBasis = axleBasis;
+exports.smallestEigenvector = smallestEigenvector;
+exports.wheelGeometry = wheelGeometry;
+exports.archAnalysis = archAnalysis;
+exports.contactPlane = contactPlane;
+exports.rideHeight = rideHeight;
+exports.judgeAtHubs = judgeAtHubs;
+exports.judgeArchClearance = judgeArchClearance;
+exports.judgeRadius = judgeRadius;
+exports.spinAnalysis = spinAnalysis;
+exports.signedAngleAboutDeg = signedAngleAboutDeg;
+exports.axleYawDeg = axleYawDeg;
+exports.judgePanel = judgePanel;
+exports.camFit = camFit;
+exports.sampleTriangles = sampleTriangles;
+exports.wheelNeighbourhood = wheelNeighbourhood;
+exports.resolveDeclaredSeats = resolveDeclaredSeats;
+exports.engineAtLeast = engineAtLeast;
+exports.rayFirst = rayFirst;
+exports.rayHits = rayHits;
+exports.measureOccupant = measureOccupant;
+exports.judgeOccupants = judgeOccupants;
+const vehiclePenetration_1 = require("./vehiclePenetration");
+/** Thresholds. Calibrated on live cars — see the calibration table in `vehicle.spec.ts`. */
+exports.VEHICLE_QA_THRESHOLDS = {
+    /** Drawn wheel centre vs physics hub, lateral (x) and longitudinal (z). */
+    hubPlanarTolM: 0.03,
+    /** Drawn wheel centre vs physics hub, vertical (y). */
+    hubVerticalTolM: 0.03,
+    /** Drawn axle vs the wheel node's spin axis. Geometry that is not square to its spin axis wobbles. */
+    axleAgreementMaxDeg: 10,
+    /** Drawn tyre radius vs physics radius (warn-level: a big mismatch sinks or floats the tyre). */
+    radiusTolM: 0.03,
+    /** A body vertex this far inside the tyre volume is poke-through. */
+    penetrationDepthM: 0.01,
+    /** Body points inside this fraction of the tyre radius are inside the rim barrel (brakes, hub, knuckle — often baked
+     *  into a single body mesh): never judged. Road-car rims sit at 0.62–0.72 of the tyre radius. */
+    hubZoneFraction: 0.72,
+    /** Body vertices this many points inside the tyre (deeper than `penetrationDepthM`) fail the wheel. */
+    penetrationMaxCount: 0,
+    /** Arch window: body over the tyre within this angle of vertical. */
+    archWindowDeg: 60,
+    /** Fender skin outboard of the tyre's outer face that still counts as the arch lip. */
+    archOutboardBandM: 0.12,
+    /** The lip band starts this far inboard of the tyre's outer face (sidewall bulge, lip curl). */
+    archLipInsetM: 0.02,
+    /** Lip points are judged down to this fraction of the tyre radius (there is no hardware outboard of the tyre). */
+    lipFloorFraction: 0.3,
+    /** The side-view cutout measure looks down to this fraction of the radius (below it: brake discs, hub). */
+    cutoutFloorFraction: 0.45,
+    /** Minimum radial gap from the tyre's top arc to the body. */
+    archGapMinM: 0,
+    /** Lowest body point above the contact plane, road cars. */
+    rideHeightMinM: 0.05,
+    /** Duplicate wheel geometry within this distance of a hub is a second drawn wheel on that hub. */
+    duplicateHubM: 0.25,
+    /** Spin: drawn rotation / (distance / radius). */
+    spinRatioMin: 0.8,
+    spinRatioMax: 1.25,
+    /** Spin needs at least this much sampled time and this much rolled angle to judge. */
+    spinMinSeconds: 1,
+    spinMinExpectedRad: 3,
+    /** Largest per-sample expected step before the samples alias (can't unwrap beyond π). */
+    spinMaxStepRad: 2.6,
+    /** Steering at full lock: front wheels must yaw at least this much, and the steering wheel at least this much. */
+    steerWheelMinDeg: 10,
+    steeringWheelMinDeg: 30,
+    /** Steered wheels vs the physics steer angle at full lock. */
+    steerAgreementTolDeg: 4,
+    /** Articulation: open angle within this of the declared hinge travel; closed again within this of closed. */
+    panelTolDeg: 5,
+    panelReturnTolDeg: 2,
+    /** Attached nodes (glass, door card, mirror) must stay rigid to the panel's main node. */
+    rigidPosTolM: 0.005,
+    rigidQuatDotMin: 0.9999,
+};
+// ---------------------------------------------------------------------------------------------------------------
+// vector helpers
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+exports.dot = dot;
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+exports.sub = sub;
+const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+exports.add = add;
+const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+exports.scale = scale;
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+exports.cross = cross;
+const len = (a) => Math.hypot(a[0], a[1], a[2]);
+exports.len = len;
+const norm = (a) => { const l = (0, exports.len)(a) || 1; return [a[0] / l, a[1] / l, a[2] / l]; };
+exports.norm = norm;
+const r4 = (v) => Math.round(v * 10000) / 10000;
+exports.r4 = r4;
+const r3v = (v) => [(0, exports.r4)(v[0]), (0, exports.r4)(v[1]), (0, exports.r4)(v[2])];
+exports.r3v = r3v;
+const DEG = 180 / Math.PI;
+/** Orthonormal basis around an axle: `a` the axle, `u` body-up projected off the axle, `v = a × u` (forward-ish). */
+function axleBasis(axle) {
+    const a = (0, exports.norm)(axle);
+    let u = (0, exports.sub)([0, 1, 0], (0, exports.scale)(a, a[1]));
+    if ((0, exports.len)(u) < 1e-6)
+        u = (0, exports.sub)([0, 0, 1], (0, exports.scale)(a, a[2]));
+    u = (0, exports.norm)(u);
+    return { a, u, v: (0, exports.cross)(a, u) };
+}
+/** Eigenvector of the smallest eigenvalue of a symmetric 3×3 matrix (Jacobi). */
+function smallestEigenvector(m) {
+    const A = m.map((r) => r.slice());
+    const V = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+    for (let sweep = 0; sweep < 50; sweep++) {
+        let off = 0;
+        for (let p = 0; p < 3; p++)
+            for (let q = p + 1; q < 3; q++)
+                off += A[p][q] * A[p][q];
+        if (off < 1e-18)
+            break;
+        for (let p = 0; p < 3; p++) {
+            for (let q = p + 1; q < 3; q++) {
+                if (Math.abs(A[p][q]) < 1e-18)
+                    continue;
+                const theta = (A[q][q] - A[p][p]) / (2 * A[p][q]);
+                const t = Math.sign(theta || 1) / (Math.abs(theta) + Math.sqrt(theta * theta + 1));
+                const c = 1 / Math.sqrt(t * t + 1);
+                const s = t * c;
+                for (let k = 0; k < 3; k++) {
+                    const akp = A[k][p];
+                    const akq = A[k][q];
+                    A[k][p] = c * akp - s * akq;
+                    A[k][q] = s * akp + c * akq;
+                }
+                for (let k = 0; k < 3; k++) {
+                    const apk = A[p][k];
+                    const aqk = A[q][k];
+                    A[p][k] = c * apk - s * aqk;
+                    A[q][k] = s * apk + c * aqk;
+                }
+                for (let k = 0; k < 3; k++) {
+                    const vkp = V[k][p];
+                    const vkq = V[k][q];
+                    V[k][p] = c * vkp - s * vkq;
+                    V[k][q] = s * vkp + c * vkq;
+                }
+            }
+        }
+    }
+    let best = 0;
+    for (let i = 1; i < 3; i++)
+        if (A[i][i] < A[best][best])
+            best = i;
+    return (0, exports.norm)([V[0][best], V[1][best], V[2][best]]);
+}
+/**
+ * Measure a drawn wheel from its vertices (flat xyz, body frame). `axleHint` is the wheel node's spin axis; the centre
+ * is the centre of the tyre circle in the plane perpendicular to it and the midpoint of the tread along it. Node
+ * origins are never used — a rim node can sit at the car's origin with its geometry baked at the hub.
+ */
+function wheelGeometry(points, axleHint) {
+    const n = Math.floor(points.length / 3);
+    if (n < 24)
+        return null;
+    const { a, u, v } = axleBasis(axleHint);
+    let umin = Infinity, umax = -Infinity, vmin = Infinity, vmax = -Infinity;
+    const mean = [0, 0, 0];
+    for (let i = 0; i < n; i++) {
+        const p = [points[3 * i], points[3 * i + 1], points[3 * i + 2]];
+        const pu = (0, exports.dot)(p, u), pv = (0, exports.dot)(p, v);
+        if (pu < umin)
+            umin = pu;
+        if (pu > umax)
+            umax = pu;
+        if (pv < vmin)
+            vmin = pv;
+        if (pv > vmax)
+            vmax = pv;
+        mean[0] += p[0];
+        mean[1] += p[1];
+        mean[2] += p[2];
+    }
+    mean[0] /= n;
+    mean[1] /= n;
+    mean[2] /= n;
+    const cu = (umin + umax) / 2, cv = (vmin + vmax) / 2;
+    let radius = 0;
+    const rho = new Float64Array(n), sAx = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        const p = [points[3 * i], points[3 * i + 1], points[3 * i + 2]];
+        rho[i] = Math.hypot((0, exports.dot)(p, u) - cu, (0, exports.dot)(p, v) - cv);
+        sAx[i] = (0, exports.dot)(p, a);
+        if (rho[i] > radius)
+            radius = rho[i];
+    }
+    let smin = Infinity, smax = -Infinity;
+    for (let i = 0; i < n; i++) {
+        if (rho[i] < 0.9 * radius)
+            continue;
+        if (sAx[i] < smin)
+            smin = sAx[i];
+        if (sAx[i] > smax)
+            smax = sAx[i];
+    }
+    const sc = (smin + smax) / 2;
+    const centre = (0, exports.add)((0, exports.add)((0, exports.scale)(a, sc), (0, exports.scale)(u, cu)), (0, exports.scale)(v, cv));
+    // covariance → smallest-variance axis
+    const C = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+    for (let i = 0; i < n; i++) {
+        const d = [points[3 * i] - mean[0], points[3 * i + 1] - mean[1], points[3 * i + 2] - mean[2]];
+        for (let r = 0; r < 3; r++)
+            for (let c = 0; c < 3; c++)
+                C[r][c] += d[r] * d[c];
+    }
+    let pca = smallestEigenvector(C);
+    if ((0, exports.dot)(pca, a) < 0)
+        pca = (0, exports.scale)(pca, -1);
+    const agree = Math.acos(Math.min(1, Math.abs((0, exports.dot)(pca, a)))) * DEG;
+    return { centre: (0, exports.r3v)(centre), axle: (0, exports.r3v)(a), pcaAxle: (0, exports.r3v)(pca), axleAgreementDeg: +agree.toFixed(2), radius: (0, exports.r4)(radius), width: (0, exports.r4)(smax - smin), points: n };
+}
+/**
+ * Body vs one tyre. `outward` is +1 when the axle direction points away from the car's centreline at this wheel.
+ * The tyre is the cylinder (centre, axle, radius r, width w).
+ */
+function archAnalysis(body, w, outward, t = exports.VEHICLE_QA_THRESHOLDS) {
+    const { a, u, v } = axleBasis(w.axle);
+    const r = w.radius, hw = w.width / 2;
+    const win = (t.archWindowDeg * Math.PI) / 180;
+    const top = (15 * Math.PI) / 180;
+    const n = Math.floor(body.points.length / 3);
+    let pc = 0, pmax = 0;
+    const pMeshes = new Set();
+    let gap = null, gapTop = null, cutTop = null, gapAt = null, gapMesh = null, archPts = 0;
+    for (let i = 0; i < n; i++) {
+        const d = (0, exports.sub)([body.points[3 * i], body.points[3 * i + 1], body.points[3 * i + 2]], w.centre);
+        const s = (0, exports.dot)(d, a);
+        const du = (0, exports.dot)(d, u), dv = (0, exports.dot)(d, v);
+        const rho = Math.hypot(du, dv);
+        if (rho > r + 0.6 || Math.abs(s) > hw + 0.4)
+            continue;
+        const so = s * outward;
+        // Outboard of the tyre's outer face there is no brake/hub hardware, so the fender lip is judged down to 0.3 r —
+        // a deep tuck must read as deep, not saturate. Inside the tyre's width, the rim barrel (≤ hubZoneFraction·r)
+        // holds brakes and knuckles that are often baked into the body mesh, so it is never judged.
+        const lip = so >= hw - t.archLipInsetM;
+        // side-view cutout over the tyre top: body in the tyre's OUTER half (and beyond), within ±15° of vertical
+        const ang0 = Math.atan2(dv, du);
+        if (so >= 0 && so <= hw + t.archOutboardBandM && Math.abs(ang0) <= top && rho >= t.cutoutFloorFraction * r) {
+            const g = rho - r;
+            if (cutTop === null || g < cutTop)
+                cutTop = g;
+        }
+        if (rho < (lip ? t.lipFloorFraction : t.hubZoneFraction) * r)
+            continue;
+        if (Math.abs(s) < hw && rho < r && rho >= t.hubZoneFraction * r) {
+            const depth = Math.min(r - rho, hw - Math.abs(s));
+            if (depth > t.penetrationDepthM) {
+                pc++;
+                if (depth > pmax)
+                    pmax = depth;
+                if (pMeshes.size < 8)
+                    pMeshes.add(body.names[body.mesh[i]] ?? '?');
+            }
+        }
+        if (so < -hw || so > hw + t.archOutboardBandM)
+            continue;
+        const ang = Math.atan2(dv, du); // 0 = straight up, + = towards +v (forward for a left-pointing axle)
+        if (Math.abs(ang) > win)
+            continue;
+        archPts++;
+        const g = rho - r;
+        if (gap === null || g < gap) {
+            gap = g;
+            gapAt = ang;
+            gapMesh = body.names[body.mesh[i]] ?? '?';
+        }
+        if (Math.abs(ang) <= top && (gapTop === null || g < gapTop))
+            gapTop = g;
+    }
+    return {
+        penetrationCount: pc,
+        maxPenetrationM: (0, exports.r4)(pmax),
+        penetrationMeshes: [...pMeshes],
+        archGapM: gap === null ? null : (0, exports.r4)(gap),
+        archGapTopM: gapTop === null ? null : (0, exports.r4)(gapTop),
+        archCutoutTopM: cutTop === null ? null : (0, exports.r4)(cutTop),
+        archGapAtDeg: gapAt === null ? null : +(gapAt * DEG).toFixed(1),
+        archGapMesh: gapMesh,
+        archPoints: archPts,
+    };
+}
+/** Least-squares plane y = c0 + c1·x + c2·z through the tyre contact points (centre − r·up for each wheel). */
+function contactPlane(wheels) {
+    const pts = wheels.map((w) => { const { u } = axleBasis(w.axle); return (0, exports.sub)(w.centre, (0, exports.scale)(u, w.radius)); });
+    if (pts.length < 3) {
+        const y = pts.reduce((s, p) => s + p[1], 0) / Math.max(1, pts.length);
+        return [y, 0, 0];
+    }
+    // normal equations for [1 x z]
+    const M = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+    const b = [0, 0, 0];
+    for (const p of pts) {
+        const row = [1, p[0], p[2]];
+        for (let i = 0; i < 3; i++) {
+            b[i] += row[i] * p[1];
+            for (let j = 0; j < 3; j++)
+                M[i][j] += row[i] * row[j];
+        }
+    }
+    const sol = solve3(M, b);
+    return sol ?? [pts.reduce((s, p) => s + p[1], 0) / pts.length, 0, 0];
+}
+function solve3(M, b) {
+    const det = (m) => m[0][0] * (m[1][1] * m[2][2] - m[1][2] * m[2][1]) - m[0][1] * (m[1][0] * m[2][2] - m[1][2] * m[2][0]) + m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0]);
+    const D = det(M);
+    if (Math.abs(D) < 1e-12)
+        return null;
+    const out = [];
+    for (let c = 0; c < 3; c++) {
+        const Mc = M.map((row, i) => row.map((v, j) => (j === c ? b[i] : v)));
+        out.push(det(Mc) / D);
+    }
+    return out;
+}
+function rideHeight(body, plane, filter) {
+    const n = Math.floor(body.points.length / 3);
+    let best = null, mesh = null, at = null;
+    for (let i = 0; i < n; i++) {
+        const p = [body.points[3 * i], body.points[3 * i + 1], body.points[3 * i + 2]];
+        if (filter && !filter(p))
+            continue;
+        const h = p[1] - (plane[0] + plane[1] * p[0] + plane[2] * p[2]);
+        if (best === null || h < best) {
+            best = h;
+            mesh = body.names[body.mesh[i]] ?? '?';
+            at = p;
+        }
+    }
+    return { minM: best === null ? null : (0, exports.r4)(best), mesh, at: at ? (0, exports.r3v)(at) : null };
+}
+function judgeAtHubs(rows, physicsWheelCount, duplicates, t = exports.VEHICLE_QA_THRESHOLDS) {
+    const drawn = rows.filter((r) => r.drawnCentre);
+    const off = rows.filter((r) => !r.delta || Math.abs(r.delta[0]) > t.hubPlanarTolM || Math.abs(r.delta[2]) > t.hubPlanarTolM || Math.abs(r.delta[1]) > t.hubVerticalTolM);
+    const wobble = rows.filter((r) => r.axleAgreementDeg !== null && r.axleAgreementDeg > t.axleAgreementMaxDeg);
+    // two drawn wheels on one hub: either a duplicate mesh near a hub, or two drawn centres closer than a tyre radius
+    const shared = [];
+    for (let i = 0; i < drawn.length; i++)
+        for (let j = i + 1; j < drawn.length; j++) {
+            const d = (0, exports.len)((0, exports.sub)(drawn[i].drawnCentre, drawn[j].drawnCentre));
+            if (d < Math.max(0.2, (drawn[i].radius ?? 0.3)))
+                shared.push(`${drawn[i].id}+${drawn[j].id} ${d.toFixed(3)} m apart`);
+        }
+    for (const d of duplicates)
+        shared.push(`${d.mesh} drawn ${d.distM.toFixed(3)} m from ${d.nearWheel}`);
+    const countOk = drawn.length === physicsWheelCount && physicsWheelCount > 0;
+    const pass = countOk && off.length === 0 && shared.length === 0 && wobble.length === 0;
+    const worst = rows.filter((r) => r.delta).map((r) => ({ id: r.id, d: Math.max(Math.abs(r.delta[0]), Math.abs(r.delta[1]), Math.abs(r.delta[2])) })).sort((x, y) => y.d - x.d)[0];
+    const detail = !countOk
+        ? `${drawn.length} drawn wheels for ${physicsWheelCount} physics wheels`
+        : off.length
+            ? `${off.map((r) => `${r.id} drawn ${r.delta ? `${(r.delta[0] * 100).toFixed(1)}/${(r.delta[1] * 100).toFixed(1)}/${(r.delta[2] * 100).toFixed(1)} cm (x/y/z)` : 'nowhere'}`).join(', ')} off its physics hub (tolerance ${t.hubPlanarTolM * 100} cm)`
+            : shared.length
+                ? `two drawn wheels share a hub: ${shared.join('; ')}`
+                : wobble.length
+                    ? `${wobble.map((r) => `${r.id} ${r.axleAgreementDeg}°`).join(', ')} drawn geometry not square to its spin axis`
+                    : `${drawn.length}/${physicsWheelCount} drawn wheels on their physics hubs; worst offset ${worst ? (worst.d * 100).toFixed(1) : '?'} cm (${worst?.id})`;
+    return {
+        pass,
+        detail,
+        measured: {
+            physicsWheels: physicsWheelCount,
+            drawnWheels: drawn.length,
+            tolerance: { planarM: t.hubPlanarTolM, verticalM: t.hubVerticalTolM, axleDeg: t.axleAgreementMaxDeg },
+            wheels: rows.map((r) => ({ id: r.id, hub: r.hub, drawn: r.drawnCentre, delta: r.delta, axleAgreementDeg: r.axleAgreementDeg })),
+            sharedHubs: shared,
+        },
+    };
+}
+function judgeArchClearance(rows, ride, t = exports.VEHICLE_QA_THRESHOLDS) {
+    const poke = rows.filter((r) => (r.penetrationCount ?? 0) > t.penetrationMaxCount);
+    const tight = rows.filter((r) => r.archGapM !== null && r.archGapM < t.archGapMinM);
+    const unmeasured = rows.filter((r) => r.drawnCentre === null);
+    const lowRide = ride.minM === null || ride.minM < t.rideHeightMinM;
+    const pass = poke.length === 0 && tight.length === 0 && unmeasured.length === 0 && !lowRide;
+    const parts = [];
+    if (unmeasured.length)
+        parts.push(`${unmeasured.map((r) => r.id).join(', ')} not measurable`);
+    if (tight.length)
+        parts.push(`tyre inside the arch: ${tight.map((r) => `${r.id} gap ${(r.archGapM * 100).toFixed(1)} cm${r.archCutoutTopM !== null && r.archCutoutTopM !== undefined && r.archCutoutTopM < 0 ? ` (tyre top ${(-r.archCutoutTopM * 100).toFixed(1)} cm above the cutout)` : ''}`).join(', ')}`);
+    if (poke.length)
+        parts.push(`body surface inside the tyre: ${poke.map((r) => `${r.id} ${r.penetrationCount} samples up to ${((r.maxPenetrationM ?? 0) * 100).toFixed(1)} cm deep`).join(', ')}`);
+    if (lowRide)
+        parts.push(`ride height ${ride.minM === null ? 'unmeasured' : `${(ride.minM * 100).toFixed(1)} cm (${ride.mesh})`} < ${t.rideHeightMinM * 100} cm`);
+    const gaps = rows.map((r) => r.archGapM).filter((g) => g !== null);
+    const cuts = rows.map((r) => r.archCutoutTopM).filter((g) => g !== null && g !== undefined);
+    const detail = pass
+        ? `every tyre clears its arch (min gap ${gaps.length ? (Math.min(...gaps) * 100).toFixed(1) : '—'} cm${cuts.length ? `, tyre top to cutout ${(Math.min(...cuts) * 100).toFixed(1)}–${(Math.max(...cuts) * 100).toFixed(1)} cm` : ''}), no body inside a tyre, ride height ${((ride.minM ?? 0) * 100).toFixed(1)} cm`
+        : parts.join('; ');
+    return {
+        pass,
+        detail,
+        measured: {
+            thresholds: { penetrationDepthM: t.penetrationDepthM, archGapMinM: t.archGapMinM, archWindowDeg: t.archWindowDeg, rideHeightMinM: t.rideHeightMinM },
+            rideHeight: ride,
+            wheels: rows.map((r) => ({ id: r.id, radius: r.radius, width: r.width, penetrationCount: r.penetrationCount, maxPenetrationM: r.maxPenetrationM, penetrationMeshes: r.penetrationMeshes, archGapM: r.archGapM, archGapTopM: r.archGapTopM, archCutoutTopM: r.archCutoutTopM ?? null, archGapAtDeg: r.archGapAtDeg, archGapMesh: r.archGapMesh, rideHeightLocalM: r.rideHeightLocalM })),
+        },
+    };
+}
+function judgeRadius(rows, t = exports.VEHICLE_QA_THRESHOLDS) {
+    // each wheel against ITS OWN rolling radius (a staggered car's rear tyre is bigger than its front, by design)
+    const phys = (r) => r.rollRadius ?? r.physicsRadius;
+    const bad = rows.filter((r) => r.radius === null || Math.abs(r.radius - phys(r)) > t.radiusTolM);
+    return {
+        pass: bad.length === 0,
+        detail: bad.length
+            ? `drawn tyre radius differs from physics: ${bad.map((r) => `${r.id} ${r.radius === null ? '?' : (r.radius * 100).toFixed(1)} vs ${(phys(r) * 100).toFixed(1)} cm`).join(', ')}`
+            : `drawn tyre radii match physics within ${t.radiusTolM * 100} cm (${rows.map((r) => `${r.id} ${((r.radius ?? 0) * 100).toFixed(1)}/${(phys(r) * 100).toFixed(1)}`).join(', ')})`,
+        measured: { wheels: rows.map((r) => ({ id: r.id, axle: r.axle ?? null, drawn: r.radius, physics: phys(r), contact: r.physicsRadius })) },
+    };
+}
+const wrapPi = (x) => { let y = x; while (y > Math.PI)
+    y -= 2 * Math.PI; while (y < -Math.PI)
+    y += 2 * Math.PI; return y; };
+function spinAnalysis(samples, ids, radii, t = exports.VEHICLE_QA_THRESHOLDS) {
+    const res = { pass: false, seconds: 0, distanceM: 0, fps: 0, wheels: [], reason: null };
+    if (samples.length < 3) {
+        res.reason = `only ${samples.length} samples`;
+        return res;
+    }
+    res.seconds = (samples[samples.length - 1].t - samples[0].t) / 1000;
+    res.fps = +((samples.length - 1) / Math.max(1e-6, res.seconds)).toFixed(1);
+    let dist = 0;
+    for (let i = 1; i < samples.length; i++)
+        dist += Math.hypot(samples[i].x - samples[i - 1].x, samples[i].z - samples[i - 1].z);
+    res.distanceM = (0, exports.r4)(dist);
+    const dir = Math.sign(samples.reduce((s, x) => s + x.forwardSpeed, 0)) || 1;
+    let ok = true;
+    const reasons = [];
+    ids.forEach((id, w) => {
+        let total = 0, maxStep = 0;
+        for (let i = 1; i < samples.length; i++) {
+            const step = wrapPi(samples[i].ang[w] - samples[i - 1].ang[w]);
+            total += step;
+            const stepDist = Math.hypot(samples[i].x - samples[i - 1].x, samples[i].z - samples[i - 1].z);
+            maxStep = Math.max(maxStep, stepDist / radii[w]);
+        }
+        const expected = (dist / radii[w]) * dir;
+        const ratio = Math.abs(expected) > 1e-6 ? total / expected : null;
+        res.wheels.push({ id, drawnRad: (0, exports.r4)(total), expectedRad: (0, exports.r4)(expected), ratio: ratio === null ? null : +ratio.toFixed(3), maxStepRad: (0, exports.r4)(maxStep) });
+        if (maxStep > t.spinMaxStepRad) {
+            ok = false;
+            reasons.push(`${id} sampled too sparsely (${maxStep.toFixed(2)} rad/sample)`);
+        }
+        else if (ratio === null || ratio < t.spinRatioMin || ratio > t.spinRatioMax) {
+            ok = false;
+            reasons.push(`${id} turned ${total.toFixed(2)} rad for ${expected.toFixed(2)} expected (ratio ${ratio === null ? '?' : ratio.toFixed(2)})`);
+        }
+    });
+    if (res.seconds < t.spinMinSeconds) {
+        ok = false;
+        reasons.push(`sampled ${res.seconds.toFixed(2)} s < ${t.spinMinSeconds} s`);
+    }
+    const minExpected = Math.min(...res.wheels.map((w) => Math.abs(w.expectedRad)));
+    if (!(minExpected >= t.spinMinExpectedRad)) {
+        ok = false;
+        reasons.push(`only ${dist.toFixed(2)} m travelled (${minExpected.toFixed(2)} rad expected)`);
+    }
+    res.pass = ok;
+    res.reason = reasons.length ? reasons.join('; ') : null;
+    return res;
+}
+const qMul = (a, b) => [
+    a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+    a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+    a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+    a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+];
+exports.qMul = qMul;
+const qInv = (q) => [-q[0], -q[1], -q[2], q[3]];
+exports.qInv = qInv;
+const qAngleDeg = (q) => 2 * Math.acos(Math.min(1, Math.abs(q[3]))) * DEG;
+exports.qAngleDeg = qAngleDeg;
+/** Signed angle (deg) of the rotation taking `from` to `to`, measured about `axis` (both quats in the same frame). */
+function signedAngleAboutDeg(from, to, axis) {
+    const rel = (0, exports.qMul)(to, (0, exports.qInv)(from));
+    const a = (0, exports.norm)(axis);
+    const proj = rel[0] * a[0] + rel[1] * a[1] + rel[2] * a[2];
+    let ang = 2 * Math.atan2(proj, rel[3]) * DEG;
+    if (ang > 180)
+        ang -= 360;
+    if (ang < -180)
+        ang += 360;
+    return ang;
+}
+/** Yaw (deg) of an axle direction about body +Y, 0 = square across the car. */
+function axleYawDeg(axle) {
+    let a = (0, exports.norm)(axle);
+    if (a[0] < 0)
+        a = (0, exports.scale)(a, -1);
+    return Math.atan2(-a[2], a[0]) * DEG;
+}
+const travelWhy = (st, verb) => st === 'toggle-not-accepted' ? `the runtime never accepted the ${verb} toggle (state unchanged after re-issuing it)`
+    : st === 'state-flipped-but-panel-did-not-move' ? `the runtime reported it ${verb === 'open' ? 'open' : 'closed'} but the panel did not move`
+        : st === 'stopped-short' ? `the runtime reported it ${verb === 'open' ? 'open' : 'closed'} but the panel stopped short`
+            : '';
+function judgePanel(p, t = exports.VEHICLE_QA_THRESHOLDS) {
+    if (p.openDeg === null)
+        return { pass: false, why: `${p.id} never measured open` };
+    const err = Math.abs(p.openDeg - p.expectedDeg);
+    if (err > t.panelTolDeg) {
+        const w = travelWhy(p.opening?.status, 'open');
+        return { pass: false, why: `${p.id} opened ${p.openDeg.toFixed(1)}° for ${p.expectedDeg}° declared${w ? ` — ${w}` : ''}` };
+    }
+    if (p.closedAgainDeg === null || Math.abs(p.closedAgainDeg) > t.panelReturnTolDeg) {
+        const w = travelWhy(p.closing?.status, 'close');
+        return { pass: false, why: `${p.id} did not return closed (${p.closedAgainDeg === null ? '?' : p.closedAgainDeg.toFixed(1)}° after ${p.closing?.seconds ?? '?'} s${p.closing?.reissued ? `, toggle re-issued ${p.closing.reissued}×` : ''})${w ? ` — ${w}` : ''}` };
+    }
+    const loose = p.attached.filter((a) => 'missing' in a || a.maxPosDeltaM > t.rigidPosTolM || a.quatDot < t.rigidQuatDotMin);
+    if (loose.length)
+        return { pass: false, why: `${p.id}: ${loose.map((a) => ('missing' in a ? `${a.node} missing` : `${a.node} drifted ${(a.maxPosDeltaM * 1000).toFixed(1)} mm`)).join(', ')} instead of moving with the panel` };
+    return { pass: true, why: `${p.id} ${p.openDeg.toFixed(1)}°/${p.expectedDeg}°` };
+}
+/**
+ * Camera (body frame) looking at the centre of a box from direction `dir`, far enough that the box fills ~`fill` of
+ * the frame. `fov` is vertical, `aspect` = width / height.
+ */
+function camFit(min, max, dir, fov = 30, aspect = 1.6, fill = 0.86) {
+    const d = (0, exports.norm)(dir);
+    const centre = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+    // camera basis: forward f = −d, right = f × up, up' = right × f
+    const f = (0, exports.scale)(d, -1);
+    let right = (0, exports.cross)(f, [0, 1, 0]);
+    if ((0, exports.len)(right) < 1e-6)
+        right = [1, 0, 0];
+    right = (0, exports.norm)(right);
+    const up = (0, exports.norm)((0, exports.cross)(right, f));
+    let hx = 0, hy = 0, hz = 0;
+    for (let i = 0; i < 8; i++) {
+        const c = [i & 1 ? max[0] : min[0], i & 2 ? max[1] : min[1], i & 4 ? max[2] : min[2]];
+        const o = (0, exports.sub)(c, centre);
+        hx = Math.max(hx, Math.abs((0, exports.dot)(o, right)));
+        hy = Math.max(hy, Math.abs((0, exports.dot)(o, up)));
+        hz = Math.max(hz, Math.abs((0, exports.dot)(o, f)));
+    }
+    const vt = Math.tan((fov * Math.PI) / 360);
+    const ht = vt * aspect;
+    const dist = Math.max(hx / (ht * fill), hy / (vt * fill)) + hz;
+    return { pos: (0, exports.r3v)((0, exports.add)(centre, (0, exports.scale)(d, dist))), target: (0, exports.r3v)(centre), fov, near: 0.05 };
+}
+/**
+ * Points on the body SURFACE (not just its vertices) inside `box`, on a barycentric grid of about `spacing` metres.
+ * Vertices alone miss the case that matters most: a fender skin whose large triangles have every vertex outside the
+ * tyre while the face itself cuts through it — the 993's arches are exactly that.
+ */
+function sampleTriangles(body, box, spacing = 0.008, maxPoints = 400_000) {
+    const pts = [];
+    const mesh = [];
+    const n = Math.floor(body.tris.length / 9);
+    for (let i = 0; i < n && pts.length / 3 < maxPoints; i++) {
+        const o = 9 * i;
+        const A = [body.tris[o], body.tris[o + 1], body.tris[o + 2]];
+        const B = [body.tris[o + 3], body.tris[o + 4], body.tris[o + 5]];
+        const C = [body.tris[o + 6], body.tris[o + 7], body.tris[o + 8]];
+        let out = false;
+        for (let a = 0; a < 3 && !out; a++) {
+            const lo = Math.min(A[a], B[a], C[a]), hi = Math.max(A[a], B[a], C[a]);
+            if (hi < box.min[a] || lo > box.max[a])
+                out = true;
+        }
+        if (out)
+            continue;
+        const edge = Math.max((0, exports.len)((0, exports.sub)(B, A)), (0, exports.len)((0, exports.sub)(C, B)), (0, exports.len)((0, exports.sub)(A, C)));
+        const k = Math.max(1, Math.min(200, Math.ceil(edge / spacing)));
+        for (let u = 0; u <= k; u++) {
+            for (let v = 0; v <= k - u; v++) {
+                const a = u / k, b = v / k, c = 1 - a - b;
+                const p = [A[0] * c + B[0] * a + C[0] * b, A[1] * c + B[1] * a + C[1] * b, A[2] * c + B[2] * a + C[2] * b];
+                if (p[0] < box.min[0] || p[0] > box.max[0] || p[1] < box.min[1] || p[1] > box.max[1] || p[2] < box.min[2] || p[2] > box.max[2])
+                    continue;
+                pts.push(p[0], p[1], p[2]);
+                mesh.push(body.mesh[i]);
+            }
+        }
+    }
+    return { points: pts, mesh, names: body.names };
+}
+/** The region around a wheel whose body surface can touch or overhang the tyre. */
+function wheelNeighbourhood(w, t = exports.VEHICLE_QA_THRESHOLDS) {
+    const r = w.radius + 0.12;
+    const lat = w.width / 2 + t.archOutboardBandM + 0.05;
+    const ax = Math.abs(w.axle[0]) > 0.7;
+    const ex = ax ? [lat, r, r] : [r, r, lat];
+    return { min: (0, exports.sub)(w.centre, ex), max: (0, exports.add)(w.centre, ex) };
+}
+// ── seats ─────────────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Match a package's declared `module.seatVars` keys to the seats the world actually produced.
+ *
+ * The engine does not compare raw strings: `core/vehicle/seatIdResolution.ts` (`cabinSeatIdFor`) accepts a key
+ * that is EITHER a cabin seat id (`seat_dside_f`, …) OR the legacy driver role key (`module.driverSeat`, default
+ * `'driver'`), which means the driver's cabin seat. A legacy single-driver package that declares `driver` is a
+ * valid manifest and boards correctly, so requiring the key itself to be an evidence seat id failed it.
+ * Everything else must still be a real seat id: a passenger key the cabin does not have is exactly the defect
+ * this assert exists to catch (the engine itself warns that such a seat "can never replicate").
+ */
+function resolveDeclaredSeats(declared, evidence) {
+    const ids = new Set(evidence.map((s) => s.id));
+    const driverCabinId = evidence.find((s) => s.role === 'driver')?.id ?? null;
+    const resolved = {};
+    const absent = [];
+    for (const key of declared.seats) {
+        if (ids.has(key))
+            resolved[key] = key;
+        else if (declared.driver !== null && key === declared.driver && driverCabinId !== null)
+            resolved[key] = driverCabinId;
+        else
+            absent.push(key);
+    }
+    return { absent, resolved, driverId: declared.driver !== null ? (resolved[declared.driver] ?? null) : null };
+}
+// ---------------------------------------------------------------------------------------------------------------
+// seated occupants (engine 0.3.168+: an authored seat H-point sets where the occupant sits, and the cabin is moved into
+// the frame the model is DRAWN in). A seat that is right on paper puts a skull through a roof lining or a pelvis through a
+// cushion, so everything below is measured on the DRAWN occupant (skinned vertices) against the DRAWN car (triangles),
+// never on a socket or a node origin.
+/** The first engine whose cabin fit honours authored seat-socket heights. Anything older makes the occupant numbers meaningless. */
+exports.OCCUPANT_MIN_ENGINE = '0.3.169';
+exports.OCCUPANT_QA_THRESHOLDS = {
+    /** Crown (highest skinned vertex of the head) to the first car surface above it. Below this the head touches or is through the lining. */
+    headGapMinM: 0.01,
+    /** The occupant must not hover above the cushion: lowest buttock vertex above the cushion top by more than this. */
+    hipFloatMaxM: 0.12,
+    /** ...nor go through the seat's base: lowest buttock vertex below the first up-facing surface under the seat by more than this. */
+    hipThroughBaseMaxM: 0.02,
+    /** Warn-level: how deep the buttocks sit INTO the cushion volume. A bucket seat swallows some of a body; this much is a lot. */
+    hipSinkWarnM: 0.1,
+    /** Sole vs the first car surface below the foot (floor mat, sill, pedal pad). A sole this far under it is through the floor. */
+    footSinkMaxM: 0.05,
+    /** A sole this far above it hovers in mid air. */
+    footFloatMaxM: 0.3,
+    /** Driver: the nearest finger-or-hand bone to the steering wheel, per hand. */
+    handToRimMaxM: 0.07,
+    /** The pelvis must sit on the seat node the engine says it is on. */
+    seatResidualMaxM: 0.03,
+};
+/** `0.3.169` vs `0.3.170-beta` etc. Compares the numeric dotted prefix; an unreadable version is NOT at least anything. */
+function engineAtLeast(version, min) {
+    const parse = (s) => {
+        const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(s.trim());
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const a = version ? parse(version) : null;
+    const b = parse(min);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return true;
+}
+/**
+ * Nearest TWO-SIDED hit of a ray against a triangle soup (Möller–Trumbore, no back-face culling: a headliner or a seat
+ * cushion is usually modelled as a single-sided shell that faces away from the occupant).
+ */
+function rayFirst(soup, origin, dir, opts = {}) {
+    const hits = rayHits(soup, origin, dir, opts);
+    return hits.length ? hits[0] : null;
+}
+/** Every hit of the ray, nearest first. See `rayFirst` for `cull`. */
+function rayHits(soup, origin, dir, opts = {}) {
+    const minT = opts.minT ?? 1e-4, maxT = opts.maxT ?? 10;
+    const { tris, mesh, names } = soup;
+    const [ox, oy, oz] = origin, [dx, dy, dz] = dir;
+    const out = [];
+    for (let i = 0, n = tris.length / 9; i < n; i++) {
+        const k = i * 9;
+        const e1x = tris[k + 3] - tris[k], e1y = tris[k + 4] - tris[k + 1], e1z = tris[k + 5] - tris[k + 2];
+        const e2x = tris[k + 6] - tris[k], e2y = tris[k + 7] - tris[k + 1], e2z = tris[k + 8] - tris[k + 2];
+        const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x;
+        const det = e1x * px + e1y * py + e1z * pz;
+        if (opts.cull ? det < 1e-12 : Math.abs(det) < 1e-12)
+            continue; // cull: only surfaces FACING the ray (an up-facing floor/cushion seen from above)
+        const inv = 1 / det;
+        const tx = ox - tris[k], ty = oy - tris[k + 1], tz = oz - tris[k + 2];
+        const u = (tx * px + ty * py + tz * pz) * inv;
+        if (u < 0 || u > 1)
+            continue;
+        const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x;
+        const v = (dx * qx + dy * qy + dz * qz) * inv;
+        if (v < 0 || u + v > 1)
+            continue;
+        const t = (e2x * qx + e2y * qy + e2z * qz) * inv;
+        if (t > minT && t <= maxT) {
+            const p = [ox + dx * t, oy + dy * t, oz + dz * t];
+            out.push({ t, y: p[1], point: p, mesh: names[mesh[i]] ?? '?' });
+        }
+    }
+    return out.sort((x, y) => x.t - y.t);
+}
+const find = (bones, re) => {
+    for (const [name, p] of Object.entries(bones))
+        if (re.test(name))
+            return { name, p };
+    return null;
+};
+const median = (xs) => {
+    if (!xs.length)
+        return null;
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.floor(s.length / 2)];
+};
+/** Everything the occupant asserts judge, from one pull. Pure. */
+/** How far ABOVE the pelvis bone the buttock search reaches (see measureOccupant). */
+exports.HIP_WINDOW_ABOVE_PELVIS_M = 0.15;
+function measureOccupant(pull) {
+    const P = pull.points;
+    const n = P.length / 3;
+    const head = find(pull.bones, /^head$/i) ?? find(pull.bones, /head/i);
+    const pelvis = find(pull.bones, /^(pelvis|hips)$/i) ?? find(pull.bones, /pelvis|hips/i);
+    // ---- head: crown vs the first surface above the skull
+    let crownY = null, ceilingY = null, ceilingMesh = null, gapM = null, openRoof = false;
+    if (head) {
+        for (let i = 0; i < n; i++) {
+            const x = P[i * 3], y = P[i * 3 + 1], z = P[i * 3 + 2];
+            if (y < head.p[1] - 0.03 || Math.hypot(x - head.p[0], z - head.p[2]) > 0.28)
+                continue;
+            if (crownY === null || y > crownY)
+                crownY = y;
+        }
+        if (crownY !== null) {
+            // ── THE CEILING IS OVER THE CROWN, NOT OVER THE BONE ────────────────────────────────────────────────
+            // Casting up from the head BONE (as this did) starts inside the skull AND, on a one-piece race seat,
+            // inside the seat's own integrated headrest. Its TOP then becomes the first hit and is reported as the
+            // roof — MEASURED on the F40: the engine's `cabinFit` reports +112 mm crown clearance while this assert
+            // reported −156 mm to the headrest (the headrest top sits 15 mm over the bone, 156 mm under the crown).
+            // So cast from the CROWN. Only when the crown is ALREADY through the roof is there no surface above it,
+            // and then the surface over the bone IS the roof the head has passed through — negative, still a fail.
+            // A surface at or below the crown can never be the ceiling when the head clears the roof.
+            const lowestOver = (fromY) => {
+                let low = null;
+                for (const dx of [-0.08, 0, 0.08])
+                    for (const dz of [-0.08, 0, 0.08]) {
+                        const h = rayFirst(pull.cabin, [head.p[0] + dx, fromY, head.p[2] + dz], [0, 1, 0]);
+                        if (h && (low === null || h.y < low.y))
+                            low = h;
+                    }
+                return low;
+            };
+            const over = lowestOver(crownY) ?? lowestOver(head.p[1]);
+            if (over) {
+                ceilingY = over.y;
+                ceilingMesh = over.mesh;
+                gapM = (0, exports.r4)(over.y - crownY);
+            }
+            else
+                openRoof = true;
+        }
+    }
+    // ---- hips: lowest buttock vertex vs the first surface below the pelvis
+    let buttockY = null, seatY = null, seatMesh = null, hipGap = null;
+    let baseY = null, baseGap = null;
+    if (pelvis) {
+        for (let i = 0; i < n; i++) {
+            const x = P[i * 3], y = P[i * 3 + 1], z = P[i * 3 + 2];
+            // The column under (and just above) the pelvis bone. The upper bound is NOT the pelvis bone itself: avatars rig
+            // the pelvis joint at different heights relative to their buttocks (Unitree G1's lowest buttock vertex sits 27 mm
+            // ABOVE its pelvis bone), and a window capped at pelvis+20 mm then held no buttock at all and failed a seated G1
+            // as "no seat surface". Taking the lowest vertex, a higher cap can only ever add the buttocks back.
+            if (Math.abs(x - pelvis.p[0]) > 0.17 || Math.abs(z - pelvis.p[2]) > 0.2 || y > pelvis.p[1] + exports.HIP_WINDOW_ABOVE_PELVIS_M || y < pelvis.p[1] - 0.3)
+                continue;
+            if (buttockY === null || y < buttockY)
+                buttockY = y;
+        }
+        const hits = [];
+        for (const dx of [-0.1, 0, 0.1])
+            for (const dz of [-0.1, 0, 0.1]) {
+                const h = rayFirst(pull.cabin, [pelvis.p[0] + dx, pelvis.p[1] + 0.3, pelvis.p[2] + dz], [0, -1, 0], { cull: true });
+                if (h)
+                    hits.push(h);
+            }
+        const my = median(hits.map((h) => h.y));
+        if (my !== null) {
+            seatY = my;
+            seatMesh = hits.reduce((a, b) => (Math.abs(b.y - my) < Math.abs(a.y - my) ? b : a)).mesh;
+        }
+        if (buttockY !== null && seatY !== null)
+            hipGap = (0, exports.r4)(buttockY - seatY);
+        {
+            // the floor pan under the seat: the LOWEST up-facing surface below the pelvis (a seat is a volume sitting on it)
+            const lows = [];
+            for (const dx of [-0.1, 0, 0.1])
+                for (const dz of [-0.1, 0, 0.1]) {
+                    const all = rayHits(pull.cabin, [pelvis.p[0] + dx, pelvis.p[1] + 0.3, pelvis.p[2] + dz], [0, -1, 0], { cull: true });
+                    if (all.length)
+                        lows.push(all[all.length - 1].y);
+                }
+            const by = median(lows);
+            if (by !== null && buttockY !== null) {
+                baseY = by;
+                baseGap = (0, exports.r4)(buttockY - by);
+            }
+        }
+    }
+    // ---- feet: lowest sole vertex vs the first surface below the foot
+    const feet = [];
+    for (const side of ['l', 'r']) {
+        const foot = find(pull.bones, new RegExp(`^foot[_.]?${side}$`, 'i')) ?? find(pull.bones, new RegExp(`foot.*${side}$|${side}.*foot`, 'i'));
+        if (!foot) {
+            feet.push({ side, soleY: null, floorY: null, floorMesh: null, gapM: null });
+            continue;
+        }
+        let soleY = null;
+        for (let i = 0; i < n; i++) {
+            const x = P[i * 3], y = P[i * 3 + 1], z = P[i * 3 + 2];
+            if (Math.hypot(x - foot.p[0], z - foot.p[2]) > 0.14 || y > foot.p[1] + 0.06)
+                continue;
+            if (soleY === null || y < soleY)
+                soleY = y;
+        }
+        const hits = [];
+        for (const dx of [-0.05, 0, 0.05])
+            for (const dz of [-0.05, 0, 0.05]) {
+                const h = rayFirst(pull.cabin, [foot.p[0] + dx, foot.p[1] + 0.1, foot.p[2] + dz], [0, -1, 0], { cull: true });
+                if (h)
+                    hits.push(h);
+            }
+        const fy = median(hits.map((h) => h.y));
+        const mesh = fy === null ? null : hits.reduce((a, b) => (Math.abs(b.y - fy) < Math.abs(a.y - fy) ? b : a)).mesh;
+        feet.push({ side, soleY: soleY === null ? null : (0, exports.r4)(soleY), floorY: fy === null ? null : (0, exports.r4)(fy), floorMesh: mesh, gapM: soleY !== null && fy !== null ? (0, exports.r4)(soleY - fy) : null });
+    }
+    // ---- hands: nearest finger/hand bone to the steering wheel (driver only)
+    let hands = null;
+    if (pull.role === 'driver' && pull.rim && pull.rim.length >= 9) {
+        hands = ['l', 'r'].map((side) => {
+            let best = Infinity, bone = null;
+            for (const [name, p] of Object.entries(pull.bones)) {
+                // `hand_l`, `index_02_r`, `thumb_01_l` ... the arm's last bones on this side
+                if (!new RegExp(`^(hand|thumb|index|middle|ring|pinky|pink)(_\\d+)?[_.]${side}$`, 'i').test(name))
+                    continue;
+                for (let i = 0; i < pull.rim.length; i += 3) {
+                    const d = Math.hypot(p[0] - pull.rim[i], p[1] - pull.rim[i + 1], p[2] - pull.rim[i + 2]);
+                    if (d < best) {
+                        best = d;
+                        bone = name;
+                    }
+                }
+            }
+            return { side, nearestBone: bone, distM: Number.isFinite(best) ? (0, exports.r4)(best) : null };
+        });
+    }
+    return {
+        seatKey: pull.seatKey, seatId: pull.seatId, role: pull.role, occupantPoints: n, cabinTriangles: pull.cabin.tris.length / 9,
+        head: { boneY: head ? (0, exports.r4)(head.p[1]) : null, crownY: crownY === null ? null : (0, exports.r4)(crownY), ceilingY: ceilingY === null ? null : (0, exports.r4)(ceilingY), gapM, ceilingMesh, openRoof },
+        hips: { pelvisY: pelvis ? (0, exports.r4)(pelvis.p[1]) : null, buttockY: buttockY === null ? null : (0, exports.r4)(buttockY), seatSurfaceY: seatY === null ? null : (0, exports.r4)(seatY), seatMesh, gapM: hipGap, baseY: baseY === null ? null : (0, exports.r4)(baseY), baseGapM: baseGap },
+        feet, hands, seatResidualM: pull.seatResidualM,
+    };
+}
+const mm = (v) => (v === null ? '?' : `${v >= 0 ? '+' : ''}${(v * 1000).toFixed(0)} mm`);
+/**
+ * The occupant asserts, one per question the critic also answers visually. `boarded` lists the declared seats the harness
+ * could NOT sit in (with why): a declared seat nobody can use is itself a defect.
+ */
+function judgeOccupants(measures, failedSeats, declaredSeats, engineVersion, T = exports.OCCUPANT_QA_THRESHOLDS) {
+    const out = [];
+    const seated = new Set(measures.map((m) => m.seatKey));
+    const missing = declaredSeats.filter((s) => !seated.has(s));
+    out.push({
+        id: 'vehicle.occupants.engine_current',
+        pass: engineAtLeast(engineVersion, exports.OCCUPANT_MIN_ENGINE),
+        detail: engineAtLeast(engineVersion, exports.OCCUPANT_MIN_ENGINE)
+            ? `rendered on engine ${engineVersion} (>= ${exports.OCCUPANT_MIN_ENGINE}, which seats occupants on the authored H-point in the drawn frame)`
+            : `rendered on engine ${engineVersion ?? 'unknown'}; occupant fit is only meaningful on >= ${exports.OCCUPANT_MIN_ENGINE}`,
+        measured: { engineVersion, min: exports.OCCUPANT_MIN_ENGINE },
+    });
+    out.push({
+        id: 'vehicle.occupants.boarded',
+        pass: missing.length === 0 && measures.length > 0,
+        detail: missing.length === 0 && measures.length > 0
+            ? `an occupant was seated and measured in every declared seat (${measures.map((m) => m.seatKey).join(', ')})`
+            : `declared seats not seated/measured: ${(missing.length ? missing : declaredSeats).map((s) => `${s}${failedSeats.find((f) => f.seatKey === s) ? ` (${failedSeats.find((f) => f.seatKey === s).why})` : ''}`).join('; ')}`,
+        measured: { declared: declaredSeats, measured: [...seated], failed: failedSeats },
+    });
+    const rows = (f) => measures.map((m) => `${m.seatKey}: ${f(m)}`).join('; ');
+    // head
+    const headBad = measures.filter((m) => m.head.gapM === null ? m.head.crownY === null : m.head.gapM < T.headGapMinM);
+    out.push({
+        id: 'vehicle.occupants.head_clearance',
+        pass: measures.length > 0 && headBad.length === 0,
+        detail: !measures.length ? 'no occupant measured'
+            : headBad.length ? `crown not clear of the roof lining: ${headBad.map((m) => `${m.seatKey} ${m.head.gapM === null ? 'crown not measured' : `${mm(m.head.gapM)} to ${m.head.ceilingMesh}`}`).join('; ')} (need >= ${T.headGapMinM * 1000} mm)`
+                : `crown to roof lining: ${rows((m) => (m.head.openRoof ? 'open roof' : mm(m.head.gapM)))}`,
+        measured: { seats: measures.map((m) => ({ seat: m.seatKey, ...m.head })), minM: T.headGapMinM },
+    });
+    // hips
+    const hipBad = measures.filter((m) => m.hips.gapM === null || m.hips.gapM > T.hipFloatMaxM || (m.hips.baseGapM !== null && m.hips.baseGapM < -T.hipThroughBaseMaxM));
+    out.push({
+        id: 'vehicle.occupants.hips_on_seat',
+        pass: measures.length > 0 && hipBad.length === 0,
+        detail: !measures.length ? 'no occupant measured'
+            : hipBad.length ? `pelvis not seated: ${hipBad.map((m) => (m.hips.gapM === null ? `${m.seatKey} no seat surface under the pelvis`
+                : m.hips.gapM > T.hipFloatMaxM ? `${m.seatKey} hovers ${mm(m.hips.gapM)} above ${m.hips.seatMesh}`
+                    : `${m.seatKey} buttocks ${mm(m.hips.baseGapM)} below the seat base (through the floor under ${m.hips.seatMesh})`)).join('; ')}`
+                : `buttocks vs cushion top ${rows((m) => mm(m.hips.gapM))}; above the seat base by ${rows((m) => mm(m.hips.baseGapM))}`,
+        measured: { seats: measures.map((m) => ({ seat: m.seatKey, ...m.hips })), floatMaxM: T.hipFloatMaxM, throughBaseMaxM: T.hipThroughBaseMaxM },
+    });
+    const deep = measures.filter((m) => m.hips.gapM !== null && -m.hips.gapM > T.hipSinkWarnM);
+    out.push({
+        id: 'vehicle.occupants.hips_sink_depth',
+        pass: deep.length === 0,
+        severity: 'warn',
+        detail: deep.length ? `buttocks sit deep in the cushion: ${deep.map((m) => `${m.seatKey} ${mm(-m.hips.gapM).replace('+', '')} below ${m.hips.seatMesh}'s top`).join('; ')} (warn above ${T.hipSinkWarnM * 1000} mm: the seat's H-point is at the cushion surface rather than at a hip height)`
+            : `buttocks sink into the cushion by ${rows((m) => (m.hips.gapM === null ? '?' : mm(-m.hips.gapM).replace('+', '')))}`,
+        measured: { seats: measures.map((m) => ({ seat: m.seatKey, sinkM: m.hips.gapM === null ? null : (0, exports.r4)(-m.hips.gapM) })), warnM: T.hipSinkWarnM },
+    });
+    // feet
+    const footBad = [];
+    for (const m of measures)
+        for (const f of m.feet) {
+            if (f.gapM === null)
+                footBad.push(`${m.seatKey} foot_${f.side} not measured`);
+            else if (f.gapM < -T.footSinkMaxM)
+                footBad.push(`${m.seatKey} foot_${f.side} ${mm(f.gapM)} (through ${f.floorMesh})`);
+            else if (f.gapM > T.footFloatMaxM)
+                footBad.push(`${m.seatKey} foot_${f.side} ${mm(f.gapM)} (hovering over ${f.floorMesh})`);
+        }
+    out.push({
+        id: 'vehicle.occupants.feet_on_floor',
+        pass: measures.length > 0 && footBad.length === 0,
+        detail: !measures.length ? 'no occupant measured'
+            : footBad.length ? `feet: ${footBad.join('; ')} (allowed ${-T.footSinkMaxM * 1000}..+${T.footFloatMaxM * 1000} mm)`
+                : `sole vs floor/pedal below: ${rows((m) => m.feet.map((f) => `${f.side.toUpperCase()} ${mm(f.gapM)}`).join(' '))}`,
+        measured: { seats: measures.map((m) => ({ seat: m.seatKey, feet: m.feet })), sinkMaxM: T.footSinkMaxM, floatMaxM: T.footFloatMaxM },
+    });
+    // hands (driver)
+    const drivers = measures.filter((m) => m.role === 'driver');
+    const handBad = [];
+    for (const m of drivers) {
+        if (!m.hands)
+            handBad.push(`${m.seatKey} no steering wheel / hands to measure`);
+        else
+            for (const h of m.hands) {
+                if (h.distM === null)
+                    handBad.push(`${m.seatKey} ${h.side} hand not measured`);
+                else if (h.distM > T.handToRimMaxM)
+                    handBad.push(`${m.seatKey} ${h.side} hand ${mm(h.distM).replace('+', '')} from the wheel (${h.nearestBone})`);
+            }
+    }
+    out.push({
+        id: 'vehicle.occupants.hands_on_wheel',
+        pass: drivers.length > 0 && handBad.length === 0,
+        detail: !drivers.length ? 'no driver measured'
+            : handBad.length ? `driver's hands: ${handBad.join('; ')} (need <= ${T.handToRimMaxM * 1000} mm)`
+                : `driver's nearest finger/hand bone to the wheel: ${drivers.map((m) => (m.hands ?? []).map((h) => `${h.side.toUpperCase()} ${mm(h.distM).replace('+', '')}`).join(' ')).join('; ')}`,
+        measured: { drivers: drivers.map((m) => ({ seat: m.seatKey, hands: m.hands })), maxM: T.handToRimMaxM },
+    });
+    // measured clipping into the cabin (block) and the contacts under its threshold (warn)
+    out.push(...(0, vehiclePenetration_1.judgePenetration)(measures.map((m) => m.penetration), measures.map((m) => m.seatKey)));
+    return out;
+}
+//# sourceMappingURL=vehicleMath.js.map