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

package/dist/visualQa/vehicleGrip.d.ts

@@ -0,0 +1,156 @@
+import type { Quat, Vec3 } from './vehicleMath';
+export declare const GRIP_THRESHOLDS: {
+    /** Nearest hand/finger bone to the wheel's RIM (its outer ring, not the spokes or hub), per hand, median over a window.
+     *  A gripping hand's finger joints sit inside the fingers wrapped round the tube: measured 2-4 mm on the F40 driver.
+     *  The single-frame assert's 70 mm let a hand resting on the thigh next to the bottom of the rim pass (F40, 52-58 mm). */
+    readonly handToRimMaxM: 0.03;
+    /** The hand's grip point (mean of its hand and finger bones) to the rim's tube centreline: a hand ON the rim, not beside it. */
+    readonly gripToRingMaxM: 0.09;
+    /** Peak-to-peak travel of any finger joint in its own hand's frame within one held window. A static grip moves < 1 mm. */
+    readonly fingerStillMaxM: 0.004;
+    /** ...and the largest change of any finger joint's LOCAL rotation from the window's first frame (the seated-hands
+     *  proof's own measure: pinned fingers read ~0 deg, the idle clip's curl/uncurl several degrees). */
+    readonly fingerDriftMaxDeg: 3;
+    /** Peak-to-peak travel of a hand bone in the car's frame within one held window (wheel held still, car at rest). */
+    readonly handStillMaxM: 0.012;
+    /** At each lock the STEERING hand (the one that travels furthest with the wheel) must cover at least this fraction of the
+     *  wheel's turn: the wheel is visibly turned by a hand. The other hand may hold its place and let the rim slide through
+     *  it (push-pull steering, as driving schools teach it and as the seat rig does once an arm runs out of reach), but it
+     *  must stay ON the rim (hands_on_wheel_steering) and must not travel against the wheel. Measured on humanoid-character
+     *  0.3.212 (lock to lock, sliding past reach): the steering hand rides 31-38 % of a 110 deg turn on the R34, 993 and
+     *  F40; a hand that does not ride at all reads 0-10 %. */
+    readonly followMinFraction: 0.25;
+    /** A hand that travels round the rim AGAINST the wheel's turn by more than this is fighting it. */
+    readonly againstMaxDeg: 15;
+    /** ...judged only when the wheel turned at least this much between centre and lock. */
+    readonly followMinRimDeg: 20;
+    /** Centred wheel: clock hour band per hand ("about 9 and 3"; 10-and-2 passes, a hand at the top or bottom does not). */
+    readonly leftHourMin: 7.5;
+    readonly leftHourMax: 11.5;
+    readonly rightHourMin: 0.5;
+    readonly rightHourMax: 4.5;
+    /** A window with fewer frames than this measured nothing. */
+    readonly minFrames: 12;
+};
+export type GripThresholds = typeof GRIP_THRESHOLDS;
+/** Samples per held window, one every GRIP_WINDOW_STRIDE animation frames: ~2.4 s at 60 fps, long enough to catch an
+ *  idle clip's finger cycle (a 0.4 s window read the F40 passenger's fingers at 3 mm, under the threshold). */
+export declare const GRIP_WINDOW_FRAMES = 48;
+export declare const GRIP_WINDOW_STRIDE = 3;
+export type GripState = 'rest' | 'centre' | 'left' | 'right';
+export interface GripFrame {
+    t: number;
+    body: Record<string, Vec3>;
+    inHand: Record<string, Vec3>;
+    localQ?: Record<string, Quat>;
+}
+/** One held window as `__vqaVeh.occupantFrames` returns it, tagged with the seat and the steering state. */
+export interface GripWindow {
+    seatKey: string;
+    role: string;
+    state: GripState;
+    frames: GripFrame[];
+    /** Steering wheel vertices at the end of the window (body frame, flat xyz), and its rotation (body frame). */
+    rim: number[] | null;
+    rimQ: Quat | null;
+    steer: number | null;
+}
+export interface RimGeometry {
+    centre: Vec3;
+    normal: Vec3;
+    up: Vec3;
+    left: Vec3;
+    radius: number;
+}
+/** Rotate v by unit quaternion q (x y z w). */
+export declare function qRotate(q: Quat, v: Vec3): Vec3;
+/**
+ * The wheel's plane and centre from its vertices (rim, spokes, hub): the plane normal is the covariance's smallest
+ * eigenvector, turned to face the driver (−z); the centre is the mean of the outer ring (the points at >= 80 % of the
+ * largest in-plane radius), which spokes and a hub offset cannot drag.
+ */
+export declare function rimGeometry(points: ArrayLike<number> | null): RimGeometry | null;
+/** Clock angle of a point about the rim, degrees clockwise from 12 as the driver sees it, in (−180, 180]. */
+export declare function clockDeg(p: Vec3, g: RimGeometry): number;
+export declare const hourOf: (deg: number) => number;
+/** Signed rotation of the wheel between two of its body-frame rotations, in the same clockwise-positive convention. */
+export declare function rimTurnDeg(from: Quat, to: Quat, g: RimGeometry): number;
+/** The rim's outer ring: the wheel vertices at >= 80 % of its largest radius (the tube a hand holds), flat xyz. */
+export declare function ringPoints(points: ArrayLike<number> | null, g: RimGeometry | null): number[] | null;
+/** A point's distance to the rim's tube CENTRELINE (the circle through the ring's middle). */
+export declare function toRingCentreline(p: Vec3, g: RimGeometry): number;
+export interface WindowStillness {
+    seatKey: string;
+    state: GripState;
+    frames: number;
+    seconds: number;
+    /** Worst finger joint: its name and peak-to-peak travel in its hand's frame (m). */
+    fingerSpanM: number | null;
+    fingerBone: string | null;
+    fingerJoints: number;
+    /** Worst finger joint by LOCAL rotation: degrees from the window's first frame. */
+    fingerDriftDeg: number | null;
+    fingerDriftBone: string | null;
+    /** Worst hand: its peak-to-peak travel in the car's frame (m). */
+    handSpanM: number | null;
+    handBone: string | null;
+}
+export declare function windowStillness(w: GripWindow): WindowStillness;
+export interface HandAtState {
+    side: 'l' | 'r';
+    distM: number | null;
+    bone: string | null;
+    gripToRingM: number | null;
+    clockDeg: number | null;
+    hour: number | null;
+}
+export interface DriverGrip {
+    seatKey: string;
+    rim: {
+        radiusM: number;
+        centre: Vec3;
+    } | null;
+    states: Array<{
+        state: GripState;
+        steer: number | null;
+        rimTurnDeg: number | null;
+        hands: HandAtState[];
+    }>;
+    /** Per hand and lock: hand travel round the rim vs the wheel's turn (both clockwise-positive degrees). */
+    follow: Array<{
+        side: 'l' | 'r';
+        lock: 'left' | 'right';
+        rimDeg: number | null;
+        handDeg: number | null;
+        fraction: number | null;
+    }>;
+}
+/** The driver's grip across the centre/left/right windows. The rim geometry is fixed by the CENTRE window. */
+export declare function measureDriverGrip(windows: GripWindow[]): DriverGrip | null;
+export interface GripVerdict {
+    id: string;
+    pass: boolean;
+    severity: 'block' | 'warn';
+    detail: string;
+    measured: Record<string, unknown>;
+}
+/**
+ * Judge the windows of every occupant. `driverSeats` names the seats that hold the steering wheel; `seats` every seat that
+ * was occupied (a seat with no window measured fails, it is not skipped).
+ */
+export declare function judgeGrip(windows: GripWindow[], seats: Array<{
+    seatKey: string;
+    role: string;
+}>, T?: GripThresholds): GripVerdict[];
+/**
+ * The seat rig's own complaints, as it logs them (`[vehicle-seat] steering rim out of reach for the left hand in …`, from
+ * humanoid-character 0.3.212; the same lines fill its describe().warnings): a hand the rig had to park on the thigh, a seat
+ * it could not fit. Any such line while an occupant sat is a car defect.
+ */
+export declare function judgeSeatRigWarnings(lines: Array<{
+    seatKey: string;
+    text: string;
+}>, seated: number): GripVerdict;
+/** Assert ids this module emits (each blocking). */
+export declare const GRIP_ASSERT_IDS: readonly ["vehicle.occupants.hands_on_wheel_steering", "vehicle.occupants.hands_follow_wheel", "vehicle.occupants.hands_at_nine_and_three", "vehicle.occupants.fingers_still", "vehicle.occupants.hands_still", "vehicle.occupants.seat_rig_warnings"];
+export declare const GRIP_THRESHOLD_TEXT: Record<string, string>;

package/dist/visualQa/vehicleGrip.js

@@ -0,0 +1,439 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRIP_THRESHOLD_TEXT = exports.GRIP_ASSERT_IDS = exports.hourOf = exports.GRIP_WINDOW_STRIDE = exports.GRIP_WINDOW_FRAMES = exports.GRIP_THRESHOLDS = void 0;
+exports.qRotate = qRotate;
+exports.rimGeometry = rimGeometry;
+exports.clockDeg = clockDeg;
+exports.rimTurnDeg = rimTurnDeg;
+exports.ringPoints = ringPoints;
+exports.toRingCentreline = toRingCentreline;
+exports.windowStillness = windowStillness;
+exports.measureDriverGrip = measureDriverGrip;
+exports.judgeGrip = judgeGrip;
+exports.judgeSeatRigWarnings = judgeSeatRigWarnings;
+const vehicleMath_1 = require("./vehicleMath");
+exports.GRIP_THRESHOLDS = {
+    /** Nearest hand/finger bone to the wheel's RIM (its outer ring, not the spokes or hub), per hand, median over a window.
+     *  A gripping hand's finger joints sit inside the fingers wrapped round the tube: measured 2-4 mm on the F40 driver.
+     *  The single-frame assert's 70 mm let a hand resting on the thigh next to the bottom of the rim pass (F40, 52-58 mm). */
+    handToRimMaxM: 0.03,
+    /** The hand's grip point (mean of its hand and finger bones) to the rim's tube centreline: a hand ON the rim, not beside it. */
+    gripToRingMaxM: 0.09,
+    /** Peak-to-peak travel of any finger joint in its own hand's frame within one held window. A static grip moves < 1 mm. */
+    fingerStillMaxM: 0.004,
+    /** ...and the largest change of any finger joint's LOCAL rotation from the window's first frame (the seated-hands
+     *  proof's own measure: pinned fingers read ~0 deg, the idle clip's curl/uncurl several degrees). */
+    fingerDriftMaxDeg: 3,
+    /** Peak-to-peak travel of a hand bone in the car's frame within one held window (wheel held still, car at rest). */
+    handStillMaxM: 0.012,
+    /** At each lock the STEERING hand (the one that travels furthest with the wheel) must cover at least this fraction of the
+     *  wheel's turn: the wheel is visibly turned by a hand. The other hand may hold its place and let the rim slide through
+     *  it (push-pull steering, as driving schools teach it and as the seat rig does once an arm runs out of reach), but it
+     *  must stay ON the rim (hands_on_wheel_steering) and must not travel against the wheel. Measured on humanoid-character
+     *  0.3.212 (lock to lock, sliding past reach): the steering hand rides 31-38 % of a 110 deg turn on the R34, 993 and
+     *  F40; a hand that does not ride at all reads 0-10 %. */
+    followMinFraction: 0.25,
+    /** A hand that travels round the rim AGAINST the wheel's turn by more than this is fighting it. */
+    againstMaxDeg: 15,
+    /** ...judged only when the wheel turned at least this much between centre and lock. */
+    followMinRimDeg: 20,
+    /** Centred wheel: clock hour band per hand ("about 9 and 3"; 10-and-2 passes, a hand at the top or bottom does not). */
+    leftHourMin: 7.5,
+    leftHourMax: 11.5,
+    rightHourMin: 0.5,
+    rightHourMax: 4.5,
+    /** A window with fewer frames than this measured nothing. */
+    minFrames: 12,
+};
+/** Samples per held window, one every GRIP_WINDOW_STRIDE animation frames: ~2.4 s at 60 fps, long enough to catch an
+ *  idle clip's finger cycle (a 0.4 s window read the F40 passenger's fingers at 3 mm, under the threshold). */
+exports.GRIP_WINDOW_FRAMES = 48;
+exports.GRIP_WINDOW_STRIDE = 3;
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const len = (a) => Math.hypot(a[0], a[1], a[2]);
+const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+const norm = (a) => { const l = len(a) || 1; return [a[0] / l, a[1] / l, a[2] / l]; };
+const inPlane = (v, n) => norm(sub(v, scale(n, dot(v, n))));
+const r1 = (v) => Math.round(v * 10) / 10;
+const r4 = (v) => Math.round(v * 10000) / 10000;
+const mm = (m) => (m === null ? '?' : `${(m * 1000).toFixed(0)} mm`);
+/** Rotate v by unit quaternion q (x y z w). */
+function qRotate(q, v) {
+    const [x, y, z, w] = q;
+    const ix = w * v[0] + y * v[2] - z * v[1];
+    const iy = w * v[1] + z * v[0] - x * v[2];
+    const iz = w * v[2] + x * v[1] - y * v[0];
+    const iw = -x * v[0] - y * v[1] - z * v[2];
+    return [ix * w + iw * -x + iy * -z - iz * -y, iy * w + iw * -y + iz * -x - ix * -z, iz * w + iw * -z + ix * -y - iy * -x];
+}
+const qInv = (q) => [-q[0], -q[1], -q[2], q[3]];
+/**
+ * The wheel's plane and centre from its vertices (rim, spokes, hub): the plane normal is the covariance's smallest
+ * eigenvector, turned to face the driver (−z); the centre is the mean of the outer ring (the points at >= 80 % of the
+ * largest in-plane radius), which spokes and a hub offset cannot drag.
+ */
+function rimGeometry(points) {
+    if (!points || points.length < 30)
+        return null;
+    const n = Math.floor(points.length / 3);
+    let c = [0, 0, 0];
+    for (let i = 0; i < n; i++) {
+        c[0] += points[3 * i];
+        c[1] += points[3 * i + 1];
+        c[2] += points[3 * i + 2];
+    }
+    c = scale(c, 1 / n);
+    const cov = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+    for (let i = 0; i < n; i++) {
+        const d = [points[3 * i] - c[0], points[3 * i + 1] - c[1], points[3 * i + 2] - c[2]];
+        for (let a = 0; a < 3; a++)
+            for (let b = 0; b < 3; b++)
+                cov[a][b] += d[a] * d[b];
+    }
+    let normal = norm((0, vehicleMath_1.smallestEigenvector)(cov));
+    if (normal[2] > 0)
+        normal = scale(normal, -1);
+    const radial = (p) => { const d = sub(p, c); return len(sub(d, scale(normal, dot(d, normal)))); };
+    const pts = [];
+    for (let i = 0; i < n; i++)
+        pts.push([points[3 * i], points[3 * i + 1], points[3 * i + 2]]);
+    const rMax = Math.max(...pts.map(radial));
+    const ring = pts.filter((p) => radial(p) >= 0.8 * rMax);
+    let centre = [0, 0, 0];
+    for (const p of ring)
+        centre = [centre[0] + p[0], centre[1] + p[1], centre[2] + p[2]];
+    centre = scale(centre, 1 / Math.max(1, ring.length));
+    const radii = ring.map((p) => { const d = sub(p, centre); return len(sub(d, scale(normal, dot(d, normal)))); }).sort((a, b) => a - b);
+    return { centre, normal, up: inPlane([0, 1, 0], normal), left: inPlane([1, 0, 0], normal), radius: radii[Math.floor(radii.length / 2)] ?? rMax };
+}
+/** Clock angle of a point about the rim, degrees clockwise from 12 as the driver sees it, in (−180, 180]. */
+function clockDeg(p, g) {
+    const d = sub(p, g.centre);
+    return (Math.atan2(-dot(d, g.left), dot(d, g.up)) * 180) / Math.PI;
+}
+const hourOf = (deg) => ((((deg / 30) % 12) + 12) % 12);
+exports.hourOf = hourOf;
+const wrap = (d) => { let x = ((d + 180) % 360 + 360) % 360 - 180; if (x === -180)
+    x = 180; return x; };
+/** Signed rotation of the wheel between two of its body-frame rotations, in the same clockwise-positive convention. */
+function rimTurnDeg(from, to, g) {
+    // the wheel's own "12 o'clock" direction at `from`, carried to `to`, read as a clock angle
+    const moved = qRotate(to, qRotate(qInv(from), g.up));
+    return wrap((Math.atan2(-dot(moved, g.left), dot(moved, g.up)) * 180) / Math.PI);
+}
+const HAND_BONE = (side) => new RegExp(`^(hand|thumb|index|middle|ring|pinky|pink)(_\\d+)?[_.]${side}$`, 'i');
+const FINGER_BONE = /^(thumb|index|middle|ring|pinky|pink)(_\d+)?[_.](l|r)$/i;
+/** The rim's outer ring: the wheel vertices at >= 80 % of its largest radius (the tube a hand holds), flat xyz. */
+function ringPoints(points, g) {
+    if (!points || !g)
+        return null;
+    const out = [];
+    for (let i = 0; i + 2 < points.length; i += 3) {
+        const d = [points[i] - g.centre[0], points[i + 1] - g.centre[1], points[i + 2] - g.centre[2]];
+        const r = len(sub(d, scale(g.normal, dot(d, g.normal))));
+        if (r >= 0.75 * g.radius)
+            out.push(points[i], points[i + 1], points[i + 2]);
+    }
+    return out.length ? out : null;
+}
+/** A point's distance to the rim's tube CENTRELINE (the circle through the ring's middle). */
+function toRingCentreline(p, g) {
+    const d = sub(p, g.centre);
+    const h = dot(d, g.normal);
+    const r = len(sub(d, scale(g.normal, h)));
+    return Math.hypot(r - g.radius, h);
+}
+/** One hand in one frame: its nearest hand/finger bone to the ring, and its grip point (mean of its hand+finger bones). */
+function handAt(f, side, ring) {
+    const re = HAND_BONE(side);
+    let best = Infinity, bone = null;
+    const gp = [0, 0, 0];
+    let k = 0;
+    for (const [name, p] of Object.entries(f.body)) {
+        if (!re.test(name))
+            continue;
+        gp[0] += p[0];
+        gp[1] += p[1];
+        gp[2] += p[2];
+        k++;
+        if (ring)
+            for (let i = 0; i + 2 < ring.length; i += 3) {
+                const d = Math.hypot(p[0] - ring[i], p[1] - ring[i + 1], p[2] - ring[i + 2]);
+                if (d < best) {
+                    best = d;
+                    bone = name;
+                }
+            }
+    }
+    return { dist: Number.isFinite(best) ? best : null, bone, grip: k ? scale(gp, 1 / k) : null };
+}
+const median = (xs) => { if (!xs.length)
+    return null; const s = [...xs].sort((a, b) => a - b); return s[Math.floor(s.length / 2)]; };
+const spanOf = (ps) => {
+    if (ps.length < 2)
+        return 0;
+    const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+    for (const p of ps)
+        for (let a = 0; a < 3; a++) {
+            lo[a] = Math.min(lo[a], p[a]);
+            hi[a] = Math.max(hi[a], p[a]);
+        }
+    return len(sub(hi, lo));
+};
+function windowStillness(w) {
+    const joints = new Map();
+    const hands = new Map();
+    for (const f of w.frames) {
+        for (const [name, p] of Object.entries(f.inHand))
+            if (FINGER_BONE.test(name)) {
+                const a = joints.get(name) ?? [];
+                a.push(p);
+                joints.set(name, a);
+            }
+        for (const [name, p] of Object.entries(f.body))
+            if (/^hand[_.](l|r)$/i.test(name)) {
+                const a = hands.get(name) ?? [];
+                a.push(p);
+                hands.set(name, a);
+            }
+    }
+    let fs = -1, fb = null;
+    for (const [n, ps] of joints) {
+        const s = spanOf(ps);
+        if (s > fs) {
+            fs = s;
+            fb = n;
+        }
+    }
+    let hs = -1, hb = null;
+    for (const [n, ps] of hands) {
+        const s = spanOf(ps);
+        if (s > hs) {
+            hs = s;
+            hb = n;
+        }
+    }
+    // local-rotation drift from the first frame, per finger joint (the angle between two unit quaternions)
+    let dd = -1, db = null;
+    const q0 = w.frames[0]?.localQ ?? {};
+    for (const f of w.frames)
+        for (const [n, q] of Object.entries(f.localQ ?? {})) {
+            const a = q0[n];
+            if (!a)
+                continue;
+            const dotq = Math.min(1, Math.abs(a[0] * q[0] + a[1] * q[1] + a[2] * q[2] + a[3] * q[3]));
+            const deg = (2 * Math.acos(dotq) * 180) / Math.PI;
+            if (deg > dd) {
+                dd = deg;
+                db = n;
+            }
+        }
+    const t = w.frames.length ? (w.frames[w.frames.length - 1].t - w.frames[0].t) / 1000 : 0;
+    return { seatKey: w.seatKey, state: w.state, frames: w.frames.length, seconds: Math.round(t * 100) / 100, fingerSpanM: fs < 0 ? null : r4(fs), fingerBone: fb, fingerJoints: joints.size, fingerDriftDeg: dd < 0 ? null : r1(dd), fingerDriftBone: db, handSpanM: hs < 0 ? null : r4(hs), handBone: hb };
+}
+/** The driver's grip across the centre/left/right windows. The rim geometry is fixed by the CENTRE window. */
+function measureDriverGrip(windows) {
+    const centre = windows.find((w) => w.state === 'centre');
+    if (!centre)
+        return null;
+    const g = rimGeometry(centre.rim);
+    const out = { seatKey: centre.seatKey, rim: g ? { radiusM: r4(g.radius), centre: g.centre.map(r4) } : null, states: [], follow: [] };
+    const handsOf = (w) => ['l', 'r'].map((side) => {
+        const wg = rimGeometry(w.rim) ?? g;
+        const ring = ringPoints(w.rim, wg);
+        const per = w.frames.map((f) => handAt(f, side, ring));
+        const d = median(per.map((x) => x.dist).filter((x) => x !== null));
+        const grips = per.map((x) => x.grip).filter((x) => x !== null);
+        const gm = grips.length ? scale(grips.reduce((a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]], [0, 0, 0]), 1 / grips.length) : null;
+        const cd = g && gm ? clockDeg(gm, g) : null;
+        const bones = per.map((x) => x.bone).filter(Boolean);
+        const gr = wg && gm ? toRingCentreline(gm, wg) : null;
+        return { side, distM: d === null ? null : r4(d), bone: bones[0] ?? null, gripToRingM: gr === null ? null : r4(gr), clockDeg: cd === null ? null : r1(cd), hour: cd === null ? null : r1((0, exports.hourOf)(cd)) };
+    });
+    for (const w of windows.filter((x) => x.state !== 'rest')) {
+        const turn = g && centre.rimQ && w.rimQ ? r1(rimTurnDeg(centre.rimQ, w.rimQ, g)) : null;
+        out.states.push({ state: w.state, steer: w.steer, rimTurnDeg: w.state === 'centre' ? 0 : turn, hands: handsOf(w) });
+    }
+    const c = out.states.find((s) => s.state === 'centre');
+    for (const lock of ['left', 'right']) {
+        const s = out.states.find((x) => x.state === lock);
+        for (const side of ['l', 'r']) {
+            const h0 = c?.hands.find((h) => h.side === side)?.clockDeg ?? null;
+            const h1 = s?.hands.find((h) => h.side === side)?.clockDeg ?? null;
+            const rimDeg = s?.rimTurnDeg ?? null;
+            const handDeg = h0 !== null && h1 !== null ? r1(wrap(h1 - h0)) : null;
+            out.follow.push({ side, lock, rimDeg, handDeg, fraction: rimDeg !== null && handDeg !== null && Math.abs(rimDeg) > 1e-6 ? Math.round((handDeg / rimDeg) * 100) / 100 : null });
+        }
+    }
+    return out;
+}
+/**
+ * Judge the windows of every occupant. `driverSeats` names the seats that hold the steering wheel; `seats` every seat that
+ * was occupied (a seat with no window measured fails, it is not skipped).
+ */
+function judgeGrip(windows, seats, T = exports.GRIP_THRESHOLDS) {
+    const out = [];
+    const drivers = seats.filter((s) => s.role === 'driver');
+    const grips = drivers.map((d) => ({ seat: d.seatKey, grip: measureDriverGrip(windows.filter((w) => w.seatKey === d.seatKey)) }));
+    // ---- hands on the rim at centre, left lock, right lock
+    const onBad = [];
+    const onRows = [];
+    for (const { seat, grip } of grips) {
+        if (!grip) {
+            onBad.push(`${seat}: the steering windows were not captured`);
+            continue;
+        }
+        if (!grip.rim) {
+            onBad.push(`${seat}: no steering wheel geometry to hold`);
+            continue;
+        }
+        for (const want of ['centre', 'left', 'right']) {
+            const s = grip.states.find((x) => x.state === want);
+            if (!s) {
+                onBad.push(`${seat} ${want}: not captured`);
+                continue;
+            }
+            for (const h of s.hands) {
+                if (h.distM === null)
+                    onBad.push(`${seat} ${want} ${h.side.toUpperCase()} hand: not measured`);
+                else if (h.distM > T.handToRimMaxM || (h.gripToRingM !== null && h.gripToRingM > T.gripToRingMaxM))
+                    onBad.push(`${seat} ${want} ${h.side.toUpperCase()} hand off the rim (nearest finger ${mm(h.distM)} from it, grip ${mm(h.gripToRingM)} from the tube)`);
+            }
+            onRows.push(`${want} L ${mm(s.hands[0]?.distM ?? null)}/${mm(s.hands[0]?.gripToRingM ?? null)} R ${mm(s.hands[1]?.distM ?? null)}/${mm(s.hands[1]?.gripToRingM ?? null)}`);
+        }
+    }
+    out.push({
+        id: 'vehicle.occupants.hands_on_wheel_steering', severity: 'block',
+        pass: grips.length > 0 && onBad.length === 0,
+        detail: !grips.length ? 'no driver seat was occupied'
+            : onBad.length ? `driver's hands leave the wheel while steering: ${onBad.join('; ')} (need the nearest finger <= ${mm(T.handToRimMaxM)} from the rim and the grip <= ${mm(T.gripToRingMaxM)} from the tube, at centre, left lock and right lock)`
+                : `driver's hands on the rim (nearest finger / grip to tube): ${onRows.join('; ')}`,
+        measured: { drivers: grips.map((x) => ({ seat: x.seat, rim: x.grip?.rim ?? null, states: x.grip?.states ?? null })), maxM: T.handToRimMaxM, gripToRingMaxM: T.gripToRingMaxM },
+    });
+    // ---- hands travel with the wheel: at each lock one hand turns it, and no hand moves against it
+    const fBad = [];
+    const fRows = [];
+    for (const { seat, grip } of grips) {
+        if (!grip?.rim) {
+            fBad.push(`${seat}: not measured`);
+            continue;
+        }
+        for (const lock of ['left', 'right']) {
+            const rows = grip.follow.filter((f) => f.lock === lock);
+            const tag = `${seat} at ${lock} lock`;
+            if (rows.length < 2 || rows.some((f) => f.rimDeg === null || f.handDeg === null)) {
+                fBad.push(`${tag}: not measured`);
+                continue;
+            }
+            const rim = rows[0].rimDeg;
+            if (Math.abs(rim) < T.followMinRimDeg) {
+                fBad.push(`${tag}: the steering wheel turned only ${rim} deg, so no hand can be seen turning it`);
+                continue;
+            }
+            const fr = rows.map((f) => ({ side: f.side.toUpperCase(), deg: f.handDeg, frac: f.handDeg / rim }));
+            const best = fr.reduce((a, b) => (b.frac > a.frac ? b : a));
+            const desc = fr.map((h) => `${h.side} ${h.deg}/${rim} deg (${Math.round(h.frac * 100)} %)`).join(', ');
+            if (best.frac < T.followMinFraction)
+                fBad.push(`${tag}: no hand turns the wheel — ${desc}; the steering hand must travel >= ${Math.round(T.followMinFraction * 100)} % of the turn with it`);
+            for (const h of fr)
+                if (h.frac < 0 && Math.abs(h.deg) > T.againstMaxDeg)
+                    fBad.push(`${tag}: the ${h.side} hand travels ${Math.abs(h.deg)} deg AGAINST the wheel`);
+            fRows.push(`${lock}: ${desc}${fr.some((h) => h !== best && h.frac < T.followMinFraction) ? ' (push-pull: the other hand holds and lets the rim slide)' : ''}`);
+        }
+    }
+    out.push({
+        id: 'vehicle.occupants.hands_follow_wheel', severity: 'block',
+        pass: grips.length > 0 && fBad.length === 0,
+        detail: !grips.length ? 'no driver seat was occupied'
+            : fBad.length ? `the driver's hands do not turn the wheel: ${fBad.join('; ')}`
+                : `hand travel / wheel turn: ${fRows.join('; ')}`,
+        measured: { follow: grips.map((x) => ({ seat: x.seat, follow: x.grip?.follow ?? null })), minFraction: T.followMinFraction, minRimDeg: T.followMinRimDeg, againstMaxDeg: T.againstMaxDeg },
+    });
+    // ---- 9 and 3 with the wheel centred
+    const nBad = [];
+    const nRows = [];
+    for (const { seat, grip } of grips) {
+        const c = grip?.states.find((s) => s.state === 'centre');
+        if (!c || !grip?.rim) {
+            nBad.push(`${seat}: not measured`);
+            continue;
+        }
+        for (const h of c.hands) {
+            const [lo, hi] = h.side === 'l' ? [T.leftHourMin, T.leftHourMax] : [T.rightHourMin, T.rightHourMax];
+            if (h.hour === null)
+                nBad.push(`${seat} ${h.side.toUpperCase()} hand: not measured`);
+            else if (h.hour < lo || h.hour > hi)
+                nBad.push(`${seat} ${h.side.toUpperCase()} hand at ${h.hour.toFixed(1)} o'clock (want ${lo}-${hi})`);
+            nRows.push(`${h.side.toUpperCase()} ${h.hour === null ? '?' : h.hour.toFixed(1)} o'clock`);
+        }
+    }
+    out.push({
+        id: 'vehicle.occupants.hands_at_nine_and_three', severity: 'block',
+        pass: grips.length > 0 && nBad.length === 0,
+        detail: !grips.length ? 'no driver seat was occupied'
+            : nBad.length ? `wheel centred, the hands are not at about 9 and 3: ${nBad.join('; ')}`
+                : `wheel centred: ${nRows.join(', ')}`,
+        measured: { centre: grips.map((x) => ({ seat: x.seat, hands: x.grip?.states.find((s) => s.state === 'centre')?.hands ?? null })), bands: { left: [T.leftHourMin, T.leftHourMax], right: [T.rightHourMin, T.rightHourMax] } },
+    });
+    // ---- still fingers and hands, every occupant, every held window
+    const still = windows.map(windowStillness);
+    const missing = seats.filter((s) => !still.some((w) => w.seatKey === s.seatKey && w.frames >= T.minFrames));
+    const fingerBad = still.filter((w) => w.frames >= T.minFrames && (w.fingerSpanM === null || w.fingerSpanM > T.fingerStillMaxM || (w.fingerDriftDeg !== null && w.fingerDriftDeg > T.fingerDriftMaxDeg)));
+    const handBad = still.filter((w) => w.frames >= T.minFrames && (w.handSpanM === null || w.handSpanM > T.handStillMaxM));
+    const row = (w, v) => `${w.seatKey}/${w.state} ${v === 'f' ? `${w.fingerBone ?? 'no finger joints'} ${mm(w.fingerSpanM)}${w.fingerDriftDeg !== null ? `, ${w.fingerDriftBone} ${w.fingerDriftDeg} deg` : ''}` : `${w.handBone ?? 'no hand'} ${mm(w.handSpanM)}`}`;
+    const worst = (v) => still.filter((w) => w.frames >= T.minFrames).map((w) => row(w, v)).join('; ');
+    out.push({
+        id: 'vehicle.occupants.fingers_still', severity: 'block',
+        pass: seats.length > 0 && missing.length === 0 && fingerBad.length === 0,
+        detail: !seats.length ? 'no occupant seated'
+            : missing.length ? `fingers not measured for ${missing.map((s) => s.seatKey).join(', ')} (no held window of >= ${T.minFrames} frames)`
+                : fingerBad.length ? `fingers move while the hands are held (twitching / grasping): ${fingerBad.map((w) => row(w, 'f')).join('; ')} (need <= ${mm(T.fingerStillMaxM)} peak-to-peak per joint in the hand's frame and <= ${T.fingerDriftMaxDeg} deg of local rotation)`
+                    : `worst finger joint travel per window: ${worst('f')}`,
+        measured: { windows: still, maxM: T.fingerStillMaxM, maxDriftDeg: T.fingerDriftMaxDeg },
+    });
+    out.push({
+        id: 'vehicle.occupants.hands_still', severity: 'block',
+        pass: seats.length > 0 && missing.length === 0 && handBad.length === 0,
+        detail: !seats.length ? 'no occupant seated'
+            : missing.length ? `hands not measured for ${missing.map((s) => s.seatKey).join(', ')}`
+                : handBad.length ? `hands move while nothing moves them: ${handBad.map((w) => row(w, 'h')).join('; ')} (need <= ${mm(T.handStillMaxM)} peak-to-peak in the car's frame)`
+                    : `worst hand travel per window: ${worst('h')}`,
+        measured: { windows: still.map((w) => ({ seatKey: w.seatKey, state: w.state, frames: w.frames, handSpanM: w.handSpanM, handBone: w.handBone })), maxM: T.handStillMaxM },
+    });
+    return out;
+}
+/**
+ * The seat rig's own complaints, as it logs them (`[vehicle-seat] steering rim out of reach for the left hand in …`, from
+ * humanoid-character 0.3.212; the same lines fill its describe().warnings): a hand the rig had to park on the thigh, a seat
+ * it could not fit. Any such line while an occupant sat is a car defect.
+ */
+function judgeSeatRigWarnings(lines, seated) {
+    const uniq = [...new Map(lines.map((l) => [`${l.seatKey}|${l.text}`, l])).values()];
+    return {
+        id: 'vehicle.occupants.seat_rig_warnings', severity: 'block',
+        pass: seated > 0 && uniq.length === 0,
+        detail: !seated ? 'no occupant seated'
+            : uniq.length ? `the seat rig gave up on something while seated: ${uniq.slice(0, 6).map((l) => `${l.seatKey}: ${l.text.replace(/^\[vehicle-seat\]\s*/, '').slice(0, 160)}`).join('; ')}`
+                : 'the seat rig logged no warning for any occupied seat (no rim out of reach, no hand parked in the lap)',
+        measured: { warnings: uniq },
+    };
+}
+/** Assert ids this module emits (each blocking). */
+exports.GRIP_ASSERT_IDS = [
+    'vehicle.occupants.hands_on_wheel_steering',
+    'vehicle.occupants.hands_follow_wheel',
+    'vehicle.occupants.hands_at_nine_and_three',
+    'vehicle.occupants.fingers_still',
+    'vehicle.occupants.hands_still',
+    'vehicle.occupants.seat_rig_warnings',
+];
+exports.GRIP_THRESHOLD_TEXT = {
+    'vehicle.occupants.hands_on_wheel_steering': `driver: each hand ON the rim with the wheel centred, at left lock and at right lock: nearest hand/finger bone <= ${mm(exports.GRIP_THRESHOLDS.handToRimMaxM)} from the rim's ring and the grip point <= ${mm(exports.GRIP_THRESHOLDS.gripToRingMaxM)} from the tube centreline`,
+    'vehicle.occupants.hands_follow_wheel': `driver, at each lock: the steering hand travels round the rim with the wheel by >= ${Math.round(exports.GRIP_THRESHOLDS.followMinFraction * 100)} % of its turn, and no hand travels against it by more than ${exports.GRIP_THRESHOLDS.againstMaxDeg} deg (the other hand may hold and let the rim slide: push-pull)`,
+    'vehicle.occupants.hands_at_nine_and_three': `driver, wheel centred: left hand ${exports.GRIP_THRESHOLDS.leftHourMin}-${exports.GRIP_THRESHOLDS.leftHourMax} o'clock, right hand ${exports.GRIP_THRESHOLDS.rightHourMin}-${exports.GRIP_THRESHOLDS.rightHourMax} o'clock`,
+    'vehicle.occupants.fingers_still': `every occupant: each finger joint moves <= ${mm(exports.GRIP_THRESHOLDS.fingerStillMaxM)} (in its hand's frame) and turns <= ${exports.GRIP_THRESHOLDS.fingerDriftMaxDeg} deg (local rotation) over a held window of ${exports.GRIP_WINDOW_FRAMES} samples (~2.4 s)`,
+    'vehicle.occupants.seat_rig_warnings': 'the seat rig logs no `[vehicle-seat]` warning while any seat is occupied (a steering rim out of reach parks the hand in the lap)',
+    'vehicle.occupants.hands_still': `every occupant: each hand moves <= ${mm(exports.GRIP_THRESHOLDS.handStillMaxM)} (in the car's frame) over a held window`,
+};
+//# sourceMappingURL=vehicleGrip.js.map