@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/gesture/inspect.js

@@ -0,0 +1,678 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BONES = void 0;
+exports.compass = compass;
+exports.resolveAttachSpec = resolveAttachSpec;
+exports.unitVerdictFor = unitVerdictFor;
+exports.gripFrameReads = gripFrameReads;
+exports.describePose = describePose;
+exports.inspectGesture = inspectGesture;
+exports.formatInspect = formatInspect;
+exports.relevantAxisRows = relevantAxisRows;
+// PORTED from helix-web-engine-new/systems/humanoid-character/scripts/pose.mjs — the source of truth for
+// pose observability. SYNC OBLIGATION: fix bugs there first, then mirror the change here; do not diverge.
+/**
+ * Headless pose observability — answers "where does this clip actually put the body, and what is it
+ * actually doing" without a browser.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The bone axis table describes what each axis does FROM REST. Those meanings stop being true the moment
+ * a parent rotates: rotations chain, so a child's "raises the arm" axis is carried wherever the parent
+ * twist put it. Authoring a large multi-joint pose therefore cannot be reasoned out from the table alone
+ * — the only ground truth is where the bones land once the whole chain is posed.
+ *
+ * Runs the world's OWN compileGesture + GesturePlayer, so it cannot drift from what the world renders.
+ */
+const node_fs_1 = require("node:fs");
+const rig_1 = require("./rig");
+const worldRuntime_1 = require("./worldRuntime");
+const axisReference_1 = require("./axisReference");
+exports.DEFAULT_BONES = ['clavicle_r', 'upperarm_r', 'lowerarm_r', 'hand_r', 'head', 'spine_03'];
+const MOTION_SAMPLES = 64;
+const AXIS_PROBE_DEG = 10;
+const round = (v, n = 3) => Math.round(v * 10 ** n) / 10 ** n;
+const vec = (v) => [round(v.x), round(v.y), round(v.z)];
+const AXIS_NAMES = ['x', 'y', 'z'];
+/** Exported for tests: these two produce the human-facing readback, and are duck-typed on .x/.y/.z so
+ *  they need no three. A sign error here silently misleads every measurement an agent takes. */
+/** Coarse compass for a unit vector — never a precise angle, because conformed rigs differ by ~20° at the extremities. */
+function compass(v) {
+    const opts = [
+        ['up', v.y], ['down', -v.y], ['forward', v.z], ['backward', -v.z],
+        ['character-left', v.x], ['character-right', -v.x],
+    ].sort((a, b) => b[1] - a[1]);
+    return opts[0][1] < 0.8 ? `${opts[0][0]} and ${opts[1][0]}` : opts[0][0];
+}
+const worldOf = (three, bone) => { const p = new three.Vector3(); bone.getWorldPosition(p); return p; };
+const childBone = (bone) => bone.children.find((c) => c.isBone === true);
+/** The bone's TIP (its child joint). Rotating a bone does not move its own origin — only the tip moves,
+ *  which is why wrist rotation is invisible to a hand_r position probe. */
+const tipOf = (three, bone) => { const c = childBone(bone); return c !== undefined ? worldOf(three, c) : worldOf(three, bone); };
+function poseAt(ctx, gesture, seconds) {
+    for (const [bone, q] of ctx.rig.bind)
+        bone.quaternion.copy(q);
+    ctx.player.pose(gesture, seconds);
+    ctx.rig.root.updateMatrixWorld(true);
+}
+// ---- Self-calibrating hand frame ---------------------------------------------------------------------
+// Conform rebinds every character to the canonical skeleton but AIMS each mapped bone at that character's
+// own child joint (shortestArc4) — so hand frames differ by up to ~20° between rigs. Deriving the palm
+// from THIS rig's own bind pose absorbs that arc by construction; a canonical constant would not.
+function handFrame(ctx, handName) {
+    const { three, rig } = ctx;
+    const hand = rig.find(handName);
+    if (hand === null)
+        return null;
+    const side = handName.endsWith('_l') ? '_l' : '_r';
+    const fingerBone = rig.find(`middle_01${side}`) ?? rig.find(`index_01${side}`);
+    const thumbBone = rig.find(`thumb_01${side}`);
+    if (fingerBone === null || thumbBone === null)
+        return { unavailable: 'rig lacks finger bones' };
+    for (const [bone, q] of rig.bind)
+        bone.quaternion.copy(q);
+    rig.root.updateMatrixWorld(true);
+    const origin = worldOf(three, hand);
+    const fingers = worldOf(three, fingerBone).sub(origin).normalize();
+    const thumb = worldOf(three, thumbBone).sub(origin).normalize();
+    const palm = new three.Vector3().crossVectors(fingers, thumb).normalize();
+    // Cross-product handedness is a convention, not a measurement — fix it per side rather than sniffing a
+    // component. Verified on body-m / body-f / web-viking: right-hand cross(fingers,thumb) points INTO the
+    // palm on all three, and the left hand mirrors it exactly (Y/Z negated, X equal).
+    if (side === '_r')
+        palm.negate();
+    const bindQ = new three.Quaternion();
+    hand.getWorldQuaternion(bindQ);
+    const inv = bindQ.clone().invert();
+    return { hand, fingersLocal: fingers.applyQuaternion(inv), palmLocal: palm.applyQuaternion(inv) };
+}
+function facingNow(ctx, frame) {
+    if (frame === null)
+        return null;
+    if ('unavailable' in frame)
+        return { unavailable: frame.unavailable };
+    const q = new ctx.three.Quaternion();
+    frame.hand.getWorldQuaternion(q);
+    const palm = frame.palmLocal.clone().applyQuaternion(q);
+    const fingers = frame.fingersLocal.clone().applyQuaternion(q);
+    return { palm: vec(palm), fingers: vec(fingers), reads: `palm faces ${compass(palm)}, fingers point ${compass(fingers)}` };
+}
+// ---- Attachment measurement --------------------------------------------------------------------------
+// Mirrors AttachmentService.attach: explicit offsets override the preset's, the socket falls back to the
+// preset's own, and the span gate is the runtime's DEFAULT_MAX_PROP_SPAN_M rejection — keep them equal.
+const MAX_PROP_SPAN_M = 2;
+/** Exported for tests: resolves the attach spec exactly as AttachmentService.attach would. */
+function resolveAttachSpec(spec, presets) {
+    let preset = null;
+    if (spec.preset != null) {
+        if (presets === null) {
+            throw new Error('the installed humanoid-character does not export HELD_ITEM_PRESETS — it predates attachments (added in 0.2.14).\n'
+                + '  Any existing ^0.2 pin already allows it — no helix.json edit needed, just rerun the install and rebuild:\n'
+                + '  MCP: install_world_packages · CLI: helix install (via npx: `npx @hypersoniclabs/helix-cli install` — bare `helix` is an unrelated npm package).');
+        }
+        preset = presets[spec.preset] ?? null;
+        if (preset === null)
+            throw new Error(`--preset: unknown preset '${spec.preset}' (known: ${Object.keys(presets).join(', ')})`);
+    }
+    const socket = spec.socket ?? preset?.socket ?? 'hand_r.grip';
+    let position = spec.position ?? preset?.position ?? [0, 0, 0];
+    let rotationEulerDeg = spec.rotationEulerDeg ?? preset?.rotationEulerDeg ?? [0, 0, 0];
+    // AttachmentService's auto-mirror (SYNC: the MIRRORED_SOCKET rule in AttachmentService.attach): preset
+    // offsets are authored for the preset's default socket and flip on its sagittal mirror (position
+    // x → −x, euler [a,b,c] → [a,−b,−c]). Explicit offsets are never mirrored. Without this the tools
+    // measure a left-hand pose the runtime will not render.
+    let mirrored = false;
+    if (preset !== null && MIRRORED_SOCKET[preset.socket] === socket) {
+        if (spec.position == null && preset.position !== undefined) {
+            position = [neg(position[0]), position[1], position[2]];
+            mirrored = true;
+        }
+        if (spec.rotationEulerDeg == null && preset.rotationEulerDeg !== undefined) {
+            rotationEulerDeg = [rotationEulerDeg[0], neg(rotationEulerDeg[1]), neg(rotationEulerDeg[2])];
+            mirrored = true;
+        }
+    }
+    return { socket, position, rotationEulerDeg, mirrored };
+}
+/** Sagittal socket pairs — SYNC: AttachmentService's MIRRORED_SOCKET. */
+const MIRRORED_SOCKET = { 'hand_r.grip': 'hand_l.grip', 'hand_l.grip': 'hand_r.grip' };
+const neg = (v) => (v === 0 ? 0 : -v);
+/** Exported for tests. The runtime rejection wording creators actually hit, plus the too-small suspicion. */
+function unitVerdictFor(span) {
+    if (span > MAX_PROP_SPAN_M) {
+        return `runtime REJECTS this prop: spans ${round(span, 2)} m (limit ${MAX_PROP_SPAN_M} m) — almost always a cm/mm unit slip; author props in meters`;
+    }
+    return span < 0.01 ? `suspiciously small: ${round(span, 3)} m max span — double unit conversion?` : `meters OK (${round(span, 2)} m max span)`;
+}
+/** Exported for tests — duck-typed on .x/.y/.z like compass. English for the socket-frame bbox; the grip
+ *  frame IS the semantic held-item frame (+z out, +y up). */
+function gripFrameReads(sMin, sMax) {
+    const parts = [];
+    if (sMax.z > 0.005)
+        parts.push(`extends ${round(sMax.z, 2)}m out along +z`);
+    if (sMin.z < -0.005)
+        parts.push(`${round(-sMin.z, 2)}m behind the grip point`);
+    if (sMax.y > 0.005)
+        parts.push(`${round(sMax.y, 2)}m above it`);
+    if (sMin.y < -0.005)
+        parts.push(`${round(-sMin.y, 2)}m below`);
+    const inside = sMin.x <= 0 && sMax.x >= 0 && sMin.y <= 0 && sMax.y >= 0 && sMin.z <= 0 && sMax.z >= 0;
+    if (inside)
+        parts.push('grip origin is inside the prop volume');
+    else {
+        const clamp = (v, lo, hi) => Math.min(Math.max(v, lo), hi);
+        const dist = Math.hypot(clamp(0, sMin.x, sMax.x), clamp(0, sMin.y, sMax.y), clamp(0, sMin.z, sMax.z));
+        parts.push(`grip origin is OUTSIDE the prop volume (nearest point ${round(dist, 3)}m away — is the grip modeled at the origin?)`);
+    }
+    return parts.join(', ');
+}
+/** Node-side GLB reads carry no geometry objects, so the bbox comes from POSITION accessor min/max per
+ *  primitive — the same conservative corner-transform bound Box3.setFromObject computes in the browser. */
+async function propCorners(three, glbPath) {
+    const { NodeIO } = await Promise.resolve().then(() => __importStar(require('@gltf-transform/core')));
+    const { ALL_EXTENSIONS } = await Promise.resolve().then(() => __importStar(require('@gltf-transform/extensions')));
+    let doc;
+    try {
+        doc = await new NodeIO().registerExtensions(ALL_EXTENSIONS).read(glbPath);
+    }
+    catch (err) {
+        throw new Error(`--attach: ${glbPath} is not a readable .glb/.gltf — ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const scene = doc.getRoot().listScenes()[0];
+    if (scene === undefined)
+        throw new Error(`--attach: prop GLB has no scenes: ${glbPath}`);
+    const corners = [];
+    const visit = (node, parent) => {
+        const local = new three.Matrix4().compose(new three.Vector3().fromArray(node.getTranslation()), new three.Quaternion().fromArray(node.getRotation()), new three.Vector3().fromArray(node.getScale()));
+        const world = new three.Matrix4().multiplyMatrices(parent, local);
+        const mesh = node.getMesh();
+        if (mesh !== null) {
+            for (const prim of mesh.listPrimitives()) {
+                const pos = prim.getAttribute('POSITION');
+                const pMin = pos?.getMin([]);
+                const pMax = pos?.getMax([]);
+                if (pMin == null || pMax == null)
+                    continue;
+                for (let i = 0; i < 8; i++) {
+                    corners.push(new three.Vector3((i & 1) === 0 ? pMin[0] : pMax[0], (i & 2) === 0 ? pMin[1] : pMax[1], (i & 4) === 0 ? pMin[2] : pMax[2]).applyMatrix4(world));
+                }
+            }
+        }
+        for (const child of node.listChildren())
+            visit(child, world);
+    };
+    for (const node of scene.listChildren())
+        visit(node, new three.Matrix4());
+    if (corners.length === 0)
+        throw new Error(`--attach: prop GLB has no mesh geometry: ${glbPath}`);
+    return corners;
+}
+function boxOf(three, points) {
+    const min = new three.Vector3(Infinity, Infinity, Infinity);
+    const max = new three.Vector3(-Infinity, -Infinity, -Infinity);
+    for (const p of points) {
+        min.min(p);
+        max.max(p);
+    }
+    return { min, max };
+}
+async function measureAttachment(runtime, ctx, spec) {
+    if (runtime.SocketService === null || runtime.defaultSockets === null) {
+        throw new Error('the installed humanoid-character does not export SocketService/DEFAULT_SOCKETS — it predates attachment tooling.\n'
+            + '  Rerun the install and rebuild: MCP: install_world_packages · CLI: helix install.');
+    }
+    const resolved = resolveAttachSpec(spec, runtime.heldItemPresets);
+    const { three } = ctx;
+    let sockets;
+    try {
+        sockets = new runtime.SocketService(ctx.rig.root, runtime.defaultSockets); // bind pose — the same construction-time constraint as Character
+    }
+    catch (err) {
+        throw new Error(`--attach: socket construction failed on this rig: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (sockets.has(resolved.socket) !== true) {
+        throw new Error(`--socket: '${resolved.socket}' is not defined (defined: ${sockets.list().join(', ')})`);
+    }
+    const corners = await propCorners(three, spec.prop);
+    const local = boxOf(three, corners);
+    const size = local.max.clone().sub(local.min);
+    const span = Math.max(size.x, size.y, size.z);
+    const offsetQ = new three.Quaternion().setFromEuler(new three.Euler(...resolved.rotationEulerDeg.map((d) => (d * Math.PI) / 180), 'XYZ'));
+    const offsetP = new three.Vector3().fromArray(resolved.position);
+    const inSocket = boxOf(three, corners.map((c) => c.clone().applyQuaternion(offsetQ).add(offsetP)));
+    return {
+        report: {
+            prop: spec.prop, socket: resolved.socket, preset: spec.preset ?? null,
+            position: resolved.position, rotationEulerDeg: resolved.rotationEulerDeg, mirrored: resolved.mirrored,
+            bbox: { min: vec(local.min), max: vec(local.max) }, span: round(span, 3), unitVerdict: unitVerdictFor(span),
+            gripFrame: { min: vec(inSocket.min), max: vec(inSocket.max), reads: gripFrameReads(inSocket.min, inSocket.max) },
+        },
+        socket: resolved.socket, sockets, offsetQ, center: inSocket.min.clone().add(inSocket.max).multiplyScalar(0.5),
+    };
+}
+/** Posed placement of the prop: where its volume center lands, where its +z points, and its item-up. */
+function attachmentPlacement(three, attach, ref) {
+    const pose = { position: new three.Vector3(), quaternion: new three.Quaternion() };
+    attach.sockets.getWorldTransform(attach.socket, pose);
+    const center = attach.center.clone().applyQuaternion(pose.quaternion).add(pose.position);
+    const frameQ = pose.quaternion.clone().multiply(attach.offsetQ);
+    const dir = new three.Vector3(0, 0, 1).applyQuaternion(frameQ);
+    const up = new three.Vector3(0, 1, 0).applyQuaternion(frameQ);
+    return { center: vec(center), dir: vec(dir), up: vec(up), reads: describePose(`prop@${attach.socket}`, center, dir, ref) };
+}
+/** Plain-English readback so an agent with no eyes can still tell a good pose from a broken one. */
+function describePose(name, pos, dir, ref) {
+    const parts = [];
+    if (ref.head !== null) {
+        const d = pos.y - ref.head;
+        if (d > 0.08)
+            parts.push(`${round(d, 2)}m above head`);
+        else if (d > -0.08)
+            parts.push('at head height');
+        else if (pos.y > ref.shoulder - 0.08)
+            parts.push('between shoulder and head');
+        else if (pos.y > ref.hip)
+            parts.push('between hip and shoulder');
+        else
+            parts.push('below hip');
+    }
+    const side = pos.x - ref.centerX;
+    if (Math.abs(side) > 0.12)
+        parts.push(`${round(Math.abs(side), 2)}m to the ${side > 0 ? 'character-left' : 'character-right'}`);
+    else
+        parts.push('near the midline');
+    const fwd = pos.z - ref.centerZ;
+    if (Math.abs(fwd) > 0.12)
+        parts.push(fwd > 0 ? `${round(fwd, 2)}m in front` : `${round(-fwd, 2)}m behind`);
+    if (dir !== null)
+        parts.push(`points ${compass(dir)}`);
+    return `${name}: ${parts.join(', ')}`;
+}
+function refsNow(ctx) {
+    const at = (n) => { const b = ctx.rig.find(n); return b !== null ? worldOf(ctx.three, b) : null; };
+    const head = at('head'), clav = at('clavicle_r'), pelvis = at('pelvis'), spine = at('spine_03');
+    return {
+        head: head !== null ? head.y : null,
+        shoulder: clav !== null ? clav.y : 0,
+        hip: pelvis !== null ? pelvis.y : 0,
+        centerX: spine !== null ? spine.x : 0,
+        centerZ: spine !== null ? spine.z : 0,
+    };
+}
+async function inspectGesture(opts) {
+    let raw;
+    try {
+        raw = opts.clip === '-' ? (0, node_fs_1.readFileSync)(0, 'utf8') : (0, node_fs_1.readFileSync)(opts.clip, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`cannot read the gesture clip ${opts.clip}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let source;
+    try {
+        source = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${opts.clip} is not valid JSON: ${err.message}`);
+    }
+    const runtime = await (0, worldRuntime_1.loadGestureRuntime)(opts.worldDir);
+    // The gate MUST fire before compiling: a pre-0.2.15 system silently ignores an `ik` field (or fails
+    // blaming keys[].bones), so the clip would inspect WRONG rather than error.
+    if ((0, worldRuntime_1.clipUsesIk)(source) && runtime.describePose === null)
+        throw new Error(worldRuntime_1.IK_UNSUPPORTED_MESSAGE);
+    if ((0, worldRuntime_1.clipUsesItem)(source) && !runtime.ikItemIntents)
+        throw new Error(worldRuntime_1.ITEM_UNSUPPORTED_MESSAGE);
+    const { three } = runtime;
+    const compiled = runtime.compileGesture(source);
+    const rig = opts.rig ? await (0, rig_1.glbRig)(three, opts.rig) : (0, rig_1.canonicalRig)(three);
+    // The player captures the bind pose at construction — must happen before anything poses the rig.
+    const ctx = { three, rig, player: new runtime.GesturePlayer(rig.root) };
+    // Sockets are built in bind pose too, so the attachment must be measured before anything poses the rig.
+    const attach = opts.attach != null ? await measureAttachment(runtime, ctx, opts.attach) : null;
+    const bones = opts.bones ?? exports.DEFAULT_BONES;
+    const times = (opts.times ?? []).length > 0 || opts.motion === true || opts.axes === true ? (opts.times ?? []) : ['0'];
+    const handFrames = new Map();
+    for (const name of bones)
+        if (/^hand_(l|r)$/.test(name))
+            handFrames.set(name, handFrame(ctx, name));
+    // ---- ik report: goal → resolved eulers → canonical landing → this-rig landing ----------------------
+    // Two skeletons can be in play: describePose runs on the system's EMBEDDED canonical snapshot; poseAt runs
+    // the requested rig. With --rig their disagreement is conform drift, not a solver bug — show both.
+    const eulerDegAt = (bone, t) => {
+        const track = compiled.gesture.tracks.find((tr) => tr.bone === bone);
+        if (track === undefined)
+            return null;
+        const i = track.times.findIndex((time) => Math.abs(time - t) < 1e-6);
+        if (i === -1)
+            return null;
+        const e = new three.Euler().setFromQuaternion(track.quats[i], 'ZYX');
+        // ZYX decomposition can land on the gimbal-alternate branch for deep hinges (a pure Ry(-104) reads
+        // [180,-76,180]) — report the equivalent smallest-reading branch, as the compiler emits it.
+        const wrapDeg = (d) => (Math.atan2(Math.sin((d * Math.PI) / 180), Math.cos((d * Math.PI) / 180)) * 180) / Math.PI;
+        let deg = [e.x, e.y, e.z].map((r) => (r * 180) / Math.PI);
+        const alt = [wrapDeg(deg[0] + 180), wrapDeg(180 - deg[1]), wrapDeg(deg[2] + 180)];
+        if (Math.abs(alt[0]) + Math.abs(alt[1]) + Math.abs(alt[2]) < Math.abs(deg[0]) + Math.abs(deg[1]) + Math.abs(deg[2]) - 1e-9)
+            deg = alt;
+        return deg.map((d) => round(d, 1));
+    };
+    let ik = null;
+    if (runtime.describePose !== null) {
+        const keys = Array.isArray(source.keys) ? source.keys : [];
+        const goals = [];
+        const clipWarnings = compiled.warnings ?? [];
+        for (let ki = 0; ki < keys.length; ki++) {
+            const ikGoals = keys[ki]?.ik;
+            if (typeof ikGoals !== 'object' || ikGoals === null)
+                continue;
+            const t = keys[ki].t ?? 0;
+            const described = runtime.describePose(compiled.gesture, t);
+            poseAt(ctx, compiled.gesture, t);
+            for (const side of ['l', 'r']) {
+                const goal = ikGoals[`hand_${side}`];
+                if (goal === undefined || !Array.isArray(goal.position))
+                    continue;
+                const hand = side === 'l' ? described.leftHand : described.rightHand;
+                const bone = rig.find(`hand_${side}`);
+                const rigPos = bone !== null ? worldOf(three, bone) : null;
+                const dist = (p) => round(Math.hypot(p[0] - goal.position[0], p[1] - goal.position[1], p[2] - goal.position[2]), 3);
+                const canonicalErr = hand !== null ? dist(hand.position) : null;
+                const rigErr = rigPos !== null ? dist([rigPos.x, rigPos.y, rigPos.z]) : null;
+                const resolved = {};
+                for (const emitted of [`upperarm_${side}`, `lowerarm_${side}`, ...(goal.palm !== undefined ? [`hand_${side}`] : [])]) {
+                    const e = eulerDegAt(emitted, t);
+                    if (e !== null)
+                        resolved[emitted] = e;
+                }
+                const bucket = clipWarnings.filter((w) => w.startsWith(`keys[${ki}].ik`));
+                goals.push({
+                    key: ki, t, hand: `hand_${side}`,
+                    goal: { position: goal.position, palm: goal.palm ?? null, elbow: goal.elbow ?? null },
+                    resolved,
+                    canonical: hand !== null && canonicalErr !== null ? { position: hand.position, palm: hand.palm, errM: canonicalErr, reads: hand.text } : null,
+                    rig: rigPos !== null && rigErr !== null ? { position: vec(rigPos), errM: rigErr } : null,
+                    warnings: bucket,
+                    reads: `keys[${ki}] ${side === 'l' ? 'left' : 'right'} hand → [${goal.position.join(', ')}]`
+                        + `${goal.palm !== undefined ? ` palm ${goal.palm}` : ''}${goal.elbow !== undefined ? ` elbow ${goal.elbow}` : ''}`
+                        + `${canonicalErr !== null ? ` — canonical lands ${round(canonicalErr * 100, 1)} cm off` : ''}`
+                        + `${rigErr !== null && canonicalErr !== null ? `, this rig ${round(rigErr * 100, 1)} cm off (Δ = conform drift)` : ''}`
+                        + `${bucket.length > 0 ? ` — ${bucket.length} warning(s)` : ''}`,
+                });
+            }
+        }
+        if (goals.length > 0) {
+            ik = { goals };
+            // describePose measures against REST — an additive clip layers over live locomotion instead.
+            if (source.compose === 'additive')
+                ik.note = 'additive clip: landings are measured against rest, not the locomotion it will layer onto';
+        }
+    }
+    // ---- static frames --------------------------------------------------------------------------------
+    const frames = [];
+    for (const spec of times) {
+        const seconds = spec.endsWith('%') ? (parseFloat(spec) / 100) * compiled.gesture.duration : parseFloat(spec);
+        if (Number.isNaN(seconds))
+            throw new Error(`--t: '${spec}' is not a number of seconds or a percentage`);
+        poseAt(ctx, compiled.gesture, seconds);
+        const ref = refsNow(ctx);
+        const out = {};
+        for (const name of bones) {
+            const bone = rig.find(name);
+            if (bone === null) {
+                out[name] = { reads: `${name}: no such bone`, error: 'no such bone' };
+                continue;
+            }
+            const pos = worldOf(three, bone);
+            const child = childBone(bone);
+            const dir = child !== undefined ? worldOf(three, child).sub(pos).normalize() : null;
+            const entry = { pos: vec(pos), dir: dir !== null ? vec(dir) : null, reads: describePose(name, pos, dir, ref) };
+            if (handFrames.has(name))
+                entry.facing = facingNow(ctx, handFrames.get(name));
+            out[name] = entry;
+        }
+        const frame = { t: seconds, bones: out };
+        if (attach !== null)
+            frame.attachment = attachmentPlacement(three, attach, ref);
+        // Canonical-skeleton landmark inverse (0.2.15+) — null per hand when the clip never keys that arm.
+        if (runtime.describePose !== null) {
+            const described = runtime.describePose(compiled.gesture, seconds);
+            if (described.rightHand !== null || described.leftHand !== null)
+                frame.hands = described;
+        }
+        frames.push(frame);
+    }
+    // ---- --motion: what the clip DOES over time -------------------------------------------------------
+    // A static frame cannot show this. Tracks each bone's TIP, so wrist/finger rotation is visible.
+    let motion = null;
+    if (opts.motion === true) {
+        motion = {};
+        const paths = new Map(bones.map((n) => [n, []]));
+        const [w0, w1] = opts.motionWindow ?? [0, compiled.gesture.duration];
+        for (let i = 0; i < MOTION_SAMPLES; i++) {
+            poseAt(ctx, compiled.gesture, w0 + (i / (MOTION_SAMPLES - 1)) * (w1 - w0));
+            for (const name of bones) {
+                const bone = rig.find(name);
+                if (bone !== null)
+                    paths.get(name).push(tipOf(three, bone));
+            }
+        }
+        for (const [name, path] of paths) {
+            if (path.length === 0) {
+                motion[name] = { reads: `${name}: no such bone`, error: 'no such bone' };
+                continue;
+            }
+            const ext = ['x', 'y', 'z'].map((k) => {
+                const vals = path.map((p) => p[k]);
+                return Math.max(...vals) - Math.min(...vals);
+            });
+            const [lateral, vertical, depth] = ext;
+            let length = 0;
+            for (let i = 1; i < path.length; i++)
+                length += path[i].distanceTo(path[i - 1]);
+            const dominant = ext.indexOf(Math.max(...ext));
+            const total = Math.hypot(lateral, vertical, depth) || 1;
+            // Reversals along the dominant axis: a wave has several, a one-way reach has none.
+            const key = ['x', 'y', 'z'][dominant];
+            let reversals = 0, sign = 0;
+            for (let i = 1; i < path.length; i++) {
+                const d = path[i][key] - path[i - 1][key];
+                if (Math.abs(d) < 1e-4)
+                    continue;
+                const s = Math.sign(d);
+                if (sign !== 0 && s !== sign)
+                    reversals++;
+                sign = s;
+            }
+            const label = ['side-to-side', 'up-and-down', 'front-to-back'][dominant];
+            const purity = round(ext[dominant] / total, 2);
+            motion[name] = {
+                lateral: round(lateral), vertical: round(vertical), depth: round(depth),
+                pathLength: round(length), dominant: label, purity, reversals,
+                reads: `${name}: moves ${round(ext[dominant], 2)}m ${label} (purity ${purity}), `
+                    + `lateral ${round(lateral, 2)} / vertical ${round(vertical, 2)} / depth ${round(depth, 2)}, ${reversals} reversal(s)`,
+            };
+        }
+    }
+    // ---- --axes: what each keyed axis actually does AT the posed chain ---------------------------------
+    // The rest-frame table cannot answer this once parents have rotated. Perturbs the SOURCE key value (what
+    // an author would edit) and recompiles, so the reported effect is exactly what changing that number does.
+    let axes = null;
+    if (opts.axes === true) {
+        const keys = Array.isArray(source.keys) ? source.keys : [];
+        const probeName = opts.probe ?? [...bones].reverse().find((n) => rig.find(n) !== null) ?? 'hand_r';
+        axes = { probe: probeName, keys: [] };
+        for (let ki = 0; ki < keys.length; ki++) {
+            const key = keys[ki];
+            const bonesAtKey = key.bones ?? {};
+            const t = key.t ?? 0;
+            poseAt(ctx, compiled.gesture, t);
+            const probeBone = rig.find(probeName);
+            if (probeBone === null)
+                break;
+            const base = tipOf(three, probeBone);
+            const rows = [];
+            for (const boneName of Object.keys(bonesAtKey)) {
+                for (let ai = 0; ai < 3; ai++) {
+                    const probeSource = JSON.parse(JSON.stringify(source));
+                    probeSource.keys[ki].bones[boneName][ai] += AXIS_PROBE_DEG;
+                    let probeGesture;
+                    try {
+                        probeGesture = runtime.compileGesture(probeSource).gesture;
+                    }
+                    catch {
+                        continue;
+                    }
+                    poseAt(ctx, probeGesture, t);
+                    const moved = tipOf(three, rig.find(probeName)).sub(base);
+                    const mag = moved.length();
+                    if (mag < 1e-4) {
+                        rows.push({ axis: `${boneName}.${AXIS_NAMES[ai]}`, magnitude: 0, reads: `${boneName}.${AXIS_NAMES[ai]}: no effect on ${probeName}` });
+                        continue;
+                    }
+                    const unit = moved.clone().normalize();
+                    rows.push({
+                        axis: `${boneName}.${AXIS_NAMES[ai]}`, magnitude: round(mag), delta: vec(moved),
+                        reads: `${boneName}.${AXIS_NAMES[ai]}: +${AXIS_PROBE_DEG}° moves ${probeName} ${round(mag, 3)}m ${compass(unit)}`,
+                    });
+                    poseAt(ctx, compiled.gesture, t);
+                }
+            }
+            rows.sort((a, b) => b.magnitude - a.magnitude);
+            axes.keys.push({ t, rows });
+        }
+    }
+    return {
+        clip: compiled.gesture.name,
+        duration: compiled.gesture.duration,
+        rig: rig.source,
+        system: runtime.systemPath,
+        warnings: compiled.warnings ?? [],
+        frames,
+        motion,
+        axes,
+        ik,
+        keyedAxisRows: relevantAxisRows(runtime.axisTable, source),
+        attachment: attach !== null ? attach.report : null,
+    };
+}
+/** Human-readable report. `--json` returns the InspectResult instead. */
+function formatInspect(r, opts = {}) {
+    const out = [`${r.clip} (${r.duration}s) — rig ${r.rig}`];
+    // ik-attributed warnings print bucketed under their goal below — keep the top block for the rest.
+    const topWarnings = r.ik !== null ? r.warnings.filter((w) => !/^keys\[\d+\]\.ik/.test(w)) : r.warnings;
+    if (topWarnings.length > 0)
+        out.push(`warnings:\n  ${topWarnings.join('\n  ')}`);
+    if (r.ik !== null) {
+        out.push(`\nik goals${r.ik.note !== undefined ? ` (${r.ik.note})` : ''}:`);
+        for (const g of r.ik.goals) {
+            out.push(`  ${g.reads}`);
+            if (g.canonical !== null)
+                out.push(`      canonical: ${g.canonical.reads}`);
+            for (const [bone, e] of Object.entries(g.resolved))
+                out.push(`      resolved ${bone}: [${e.join(', ')}]°`);
+            for (const w of g.warnings)
+                out.push(`      ! ${w}`);
+        }
+    }
+    if (r.attachment != null) {
+        const a = r.attachment;
+        const range = (min, max) => AXIS_NAMES.map((k, i) => `${k} ${min[i]}…${max[i]}`).join(' · ');
+        out.push(`\nattachment: ${a.prop.split(/[\\/]/).pop()} → ${a.socket}${a.preset !== null ? ` (preset ${a.preset})` : ''}`);
+        out.push(`  offsets: position ${JSON.stringify(a.position)} m · rotation ${JSON.stringify(a.rotationEulerDeg)} deg${a.mirrored ? ' (preset auto-mirrored for this socket)' : ''}`);
+        out.push(`  prop bbox (m): ${range(a.bbox.min, a.bbox.max)} — ${a.unitVerdict}`);
+        out.push(`  grip frame (m): ${range(a.gripFrame.min, a.gripFrame.max)}`);
+        out.push(`  ${a.gripFrame.reads}`);
+    }
+    for (const f of r.frames) {
+        out.push(`\nt=${f.t}s`);
+        for (const [name, b] of Object.entries(f.bones)) {
+            out.push(`  ${b.reads}`);
+            if (b.pos !== undefined)
+                out.push(`      pos=${JSON.stringify(b.pos)} dir=${JSON.stringify(b.dir)}`);
+            if (b.facing != null)
+                out.push(`      ${b.facing.unavailable !== undefined ? `facing unavailable — ${b.facing.unavailable}` : b.facing.reads}`);
+        }
+        if (f.hands !== undefined) {
+            for (const h of [f.hands.rightHand, f.hands.leftHand])
+                if (h !== null && h !== undefined)
+                    out.push(`  hands: ${h.text}`);
+        }
+        if (f.attachment !== undefined) {
+            out.push(`  ${f.attachment.reads}`);
+            out.push(`      center=${JSON.stringify(f.attachment.center)} dir=${JSON.stringify(f.attachment.dir)} up=${JSON.stringify(f.attachment.up)}`);
+        }
+    }
+    if (r.motion !== null) {
+        out.push(`\nmotion over ${opts.motionWindow ? `t=${opts.motionWindow[0]}..${opts.motionWindow[1]}` : 'the whole clip'}`);
+        for (const m of Object.values(r.motion))
+            out.push(`  ${m.reads}`);
+    }
+    if (r.axes !== null) {
+        out.push(`\naxis effects at the posed chain (probe: ${r.axes.probe}, +${AXIS_PROBE_DEG}° each)`);
+        for (const k of r.axes.keys) {
+            if (k.rows.length === 0)
+                continue;
+            out.push(`  t=${k.t}s`);
+            for (const row of k.rows.slice(0, 8))
+                out.push(`    ${row.reads}`);
+        }
+    }
+    if (r.warnings.length > 0 && r.keyedAxisRows.length > 0) {
+        out.push('\nnatural ranges for the bones this clip keys (outside them warns, it does not fail)');
+        for (const row of r.keyedAxisRows) {
+            out.push(`  ${row.bones}  x ${row.natural.x.join('…')}  y ${row.natural.y.join('…')}  z ${row.natural.z.join('…')}`);
+        }
+    }
+    return out.join('\n');
+}
+/** Natural-range context for the bones a clip actually keys — the table rows that matter, not all 15. */
+function relevantAxisRows(table, clipJson) {
+    if (table === null)
+        return [];
+    const keyed = new Set();
+    for (const key of Array.isArray(clipJson?.keys) ? clipJson.keys : [])
+        for (const b of Object.keys(key.bones ?? {}))
+            keyed.add(b);
+    const seen = new Set();
+    const hits = [];
+    for (const bone of keyed) {
+        const ref = (0, axisReference_1.axisReferenceFor)(table, bone);
+        if (ref === undefined || seen.has(ref))
+            continue;
+        seen.add(ref);
+        hits.push({ bones: ref.bones.source, axes: ref.axes, natural: ref.natural });
+    }
+    return hits;
+}
+//# sourceMappingURL=inspect.js.map