cozyclay 2.1.1 → 3.0.1

package/src/motion3/qa/style.js

@@ -0,0 +1,228 @@
+// Style quantities: how fast a joint moves, how hard it speeds up, how far the centre of mass
+// leaves the feet and how deep a knee or elbow bends. They depend on what the motion is for (a
+// bat swing moves the wrists at 9 m/s), so QA measures them (output.observations) and does not
+// judge them. A spec that names a style limit in checks.limits asks for that quantity to be a
+// check again: speedCore/speedLimb -> SPEED, accCore/accLimb -> ACC, knee -> KNEE (bend),
+// balance -> BALANCE. A pop is not style: one frame whose acceleration stands out from the
+// frames around it is an artifact (a step key, a pole flip, a snapped anchor), so POP stays a
+// QA error, and so is a FLOAT: the body off the ground without falling (floatChecks). A pop is a
+// spike, not a large value: a hard but continuous acceleration (a swing's launch) is style.
+// See docs/motion-api-v3.1.md C13.
+import { add, sub, scale, len, dot, angle } from "../compiler/math.js";
+import { CAPSULES, segPoints, sdBox } from "./geometry.js";
+import { groundSole, groundY } from "./ground.js";
+
+const SPEED_JOINTS = ["Hips", "Head", "LeftHand", "RightHand", "LeftFoot", "RightFoot", "LeftLeg", "RightLeg", "LeftForeArm", "RightForeArm"];
+const CORE = new Set(["Hips", "Head"]);
+const BENDS = [["knee_l", "LeftUpLeg", "LeftLeg", "LeftFoot"], ["knee_r", "RightUpLeg", "RightLeg", "RightFoot"],
+	["elbow_l", "LeftArm", "LeftForeArm", "LeftHand"], ["elbow_r", "RightArm", "RightForeArm", "RightHand"]];
+/** A pop's acceleration is more than this many times the level around it (popLevel). */
+const POP_RATIO = 2;
+/** FLOAT: the share of gravity an airborne run may miss (0.75: the hips fall at a quarter of g). */
+const FLOAT_LIMIT = 0.75;
+/** Peak speed (m/s) under which a joint counts as still and peaks leaves it out. */
+const STILL = 0.05;
+const r2 = x => Math.round(x * 100) / 100;
+
+/**
+ * Per SPEED_JOINT: speed v[f] (m/frame, from f-1), acceleration a[f] (m/frame^2, from f-2) and
+ * its vector A[f]; 0 where undefined.
+ */
+function kinematics(sk, out) {
+	const F = out.frames, n = F.length;
+	return SPEED_JOINTS.map(j => {
+		const X = F.map(fr => fr.s.P[sk.index[j]]), v = new Float64Array(n), a = new Float64Array(n), A = X.map(() => [0, 0, 0]);
+		for (let f = 1; f < n; f++) v[f] = len(sub(X[f], X[f - 1]));
+		for (let f = 2; f < n; f++) { A[f] = sub(sub(X[f], X[f - 1]), sub(X[f - 1], X[f - 2])); a[f] = len(A[f]); }
+		return { j, core: CORE.has(j), v, a, A };
+	});
+}
+
+/**
+ * The acceleration level around frame f that a pop is measured against (m/frame^2), the larger of
+ *   far    the largest acceleration 2 and 3 frames away. A one-frame event shows in up to three
+ *          neighbouring frames (a step key in f and f+1, a one-frame glitch in f-1..f+1), so the
+ *          frames next to f are not read here;
+ *   burst  what the frames next to f carry in f's own direction, less what the other one turns
+ *          back. At 24 fps a hard move gathers its acceleration into 2 or 3 frames that all push
+ *          the same way (a swing's launch, the hips turning round): a burst, not a pop, however
+ *          hard. A glitch pushes back on both sides (+1, -2, +1), a step on one (+1, -1), and a
+ *          jitter turns back on one side as the other follows (+, -, -, +): those carry none.
+ * k = { a, A } (kinematics).
+ */
+function popLevel({ a, A }, f) {
+	let far = 0;
+	for (const q of [f - 3, f - 2, f + 2, f + 3]) if (q >= 2 && q < a.length) far = Math.max(far, a[q]);
+	const along = a[f] > 0 ? [f - 1, f + 1].filter(q => q >= 2 && q < a.length).map(q => dot(A[q], A[f]) / a[f]) : [];
+	return along.length ? Math.max(far, Math.max(...along) + Math.min(0, ...along)) : far;
+}
+
+/** True when k.a[f] (m/frame^2) is a pop: above floor and POP_RATIO times popLevel(k, f); k = { a, A } (kinematics). */
+export const isPop = (k, f, floor) => k.a[f] > floor && k.a[f] > POP_RATIO * popLevel(k, f);
+
+/** Hard POP issues (limits L: accCore, accLimb are the floor); push(kind, msg, f, value, limit). */
+export function popChecks(sk, out, L, push) {
+	for (const k of kinematics(sk, out)) {
+		const floor = k.core ? L.accCore : L.accLimb;
+		for (let f = 2; f < k.a.length; f++) if (isPop(k, f, floor)) push("POP", `${k.j} accel ${(k.a[f] * 100).toFixed(2)} cm/f^2 in one frame`, f, k.a[f], floor);
+	}
+}
+
+/** Trunk capsules that rest a body on the floor (lying, sitting on it): within this of the floor, the floor carries it. */
+const FLOOR_REST = ["hips", "torso_lo", "torso_hi"], FLOOR_TOL = 0.04;
+/** True when the floor under the trunk or a declared support (checks.supports) carries the body at frame f. */
+function supported(out, f, supports) {
+	const { P } = out.frames[f].s, I = out.ctx.sk.index;
+	if (CAPSULES.some(([part, a, b, r]) => FLOOR_REST.includes(part) && Math.min(P[I[a]][1], P[I[b]][1]) - r < FLOOR_TOL)) return true;
+	return supports.some(sp => {
+		const box = out.objectsAt(f)[sp.object], cap = CAPSULES.find(c => c[0] === (sp.part ?? "hips"));
+		return box && cap && Math.min(...segPoints(P[I[cap[1]]], P[I[cap[2]]]).map(p => sdBox(p, box))) - cap[3] < (sp.tol ?? 0.04);
+	});
+}
+
+/**
+ * Per frame: null where a declared support carries the body, "air" with no foot on the ground,
+ * else the balance margin in metres: how far the centre of mass (hips, spine, head) sits inside
+ * the box of the feet on the ground, the floor or an object's top (ground.js; < 0: outside it).
+ * While the hips travel every foot counts.
+ */
+function balanceMargins(out, supports = []) {
+	const sk = out.ctx.sk, I = sk.index, F = out.frames;
+	return F.map(({ s }, f) => {
+		if (supported(out, f, supports)) return null;
+		const { P } = s;
+		const moving = f > 0 && f < F.length - 1 && Math.hypot(F[f + 1].s.P[I.Hips][0] - F[f - 1].s.P[I.Hips][0], F[f + 1].s.P[I.Hips][2] - F[f - 1].s.P[I.Hips][2]) / 2 > 0.006;
+		const feet = [];
+		for (const S of ["Left", "Right"]) {
+			const sp = groundSole(out, f, S);
+			if (moving || Math.min(sp.heel[1], sp.ball[1]) < 0.02) feet.push(sp.heel, sp.ball, sp.tip);
+		}
+		if (!feet.length) return "air";
+		const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, P[I[j]]), [0, 0, 0]), 0.25);
+		const xs = feet.map(p => p[0]), zs = feet.map(p => p[2]);
+		return Math.min(com[0] - Math.min(...xs), Math.max(...xs) - com[0], com[2] - Math.min(...zs), Math.max(...zs) - com[2]);
+	});
+}
+
+/** True when a hand rests on the ground at frame f: its wrist or knuckles within HAND_DOWN of the ground under them. */
+const HAND_DOWN = 0.06;
+function handDown(out, f) {
+	const { P } = out.frames[f].s, I = out.ctx.sk.index;
+	return ["Left", "Right"].some(S => [`${S}Hand`, `${S}HandMiddle1`].some(j => I[j] !== undefined && P[I[j]][1] - groundY(out, f, P[I[j]]) < HAND_DOWN));
+}
+
+/** Runs [a, b] (indexes of out.frames) with both soles 2 cm or more above the ground (ground.js), no hand on it and no declared support. */
+function airRuns(out, supports = []) {
+	const n = out.frames.length, runs = [];
+	const air = out.frames.map((_, f) => !supported(out, f, supports)
+		&& ["Left", "Right"].every(S => { const sp = groundSole(out, f, S); return Math.min(sp.heel[1], sp.ball[1]) >= 0.02; }) && !handDown(out, f));
+	for (let a = 0; a < n; a++) {
+		if (!air[a]) continue;
+		let b = a;
+		while (b + 1 < n && air[b + 1]) b++;
+		runs.push([a, b]);
+		a = b;
+	}
+	return runs;
+}
+
+/**
+ * Hard FLOAT issues: 4 or more frames off the ground (airRuns) in which the hips do not fall.
+ * A jump or a drop is ballistic: over the run the hips' vertical speed drops by gravity (the
+ * speed into the run minus the speed out of it, per frame, is g). A body held up by nothing
+ * keeps it; under a quarter of g is a float. value = the share of g missing (1 = no fall).
+ */
+export function floatChecks(out, checks = {}) {
+	const F = out.frames, n = F.length, I = out.ctx.sk.index, g = 9.81 / (out.fps ?? 24) ** 2, f0 = out.f0 ?? 0, issues = [];
+	const y = f => F[Math.max(0, Math.min(n - 1, f))].s.P[I.Hips][1];
+	for (const [a, b] of airRuns(out, checks.supports)) {
+		const frames = b - a + 1;
+		if (frames < 4) continue;
+		const vin = a > 0 ? y(a) - y(a - 1) : y(a + 1) - y(a), vout = b < n - 1 ? y(b + 1) - y(b) : y(b) - y(b - 1);
+		const missing = 1 - (vin - vout) / frames / g;
+		if (missing <= FLOAT_LIMIT) continue;
+		for (let f = a; f <= b; f++) issues.push({ kind: "FLOAT", msg: `no foot on the ground f${a + f0}-f${b + f0}, hips fall at ${Math.round(Math.max(0, 1 - missing) * 100)}% of g`, frame: f, value: +missing.toFixed(4), limit: FLOAT_LIMIT });
+	}
+	return issues;
+}
+
+const bendAt = (sk, s, [, a, b, c]) => angle(sub(s.P[sk.index[b]], s.P[sk.index[a]]), sub(s.P[sk.index[c]], s.P[sk.index[b]]));
+
+/**
+ * The style checks the spec opted into by naming their limit in checks.limits (own keys only);
+ * L is QA_LIMITS merged with them. Issues as generalChecks makes them (f indexes out.frames).
+ */
+export function styleChecks(sk, out, checks, L) {
+	const own = checks?.limits ?? {}, on = k => Object.hasOwn(own, k), issues = [];
+	const push = (kind, msg, f, value, limit) => issues.push({ kind, msg, frame: f, value: +value.toFixed(4), limit });
+	for (const k of kinematics(sk, out)) {
+		const { j, core, v, a } = k, vk = core ? "speedCore" : "speedLimb", ak = core ? "accCore" : "accLimb";
+		for (let f = 1; f < v.length; f++) {
+			if (on(vk) && v[f] > L[vk]) push("SPEED", `${j} ${(v[f] * 100).toFixed(1)} cm/frame`, f, v[f], L[vk]);
+			// a pop is already a POP group
+			if (on(ak) && f > 1 && a[f] > L[ak] && !isPop(k, f, L[ak])) push("ACC", `${j} accel ${(a[f] * 100).toFixed(2)} cm/f^2`, f, a[f], L[ak]);
+		}
+	}
+	if (on("knee")) out.frames.forEach(({ s }, f) => {
+		for (const bend of BENDS.slice(0, 2)) {
+			const deg = bendAt(sk, s, bend);
+			if (deg > L.knee) push("KNEE", `${bend[0] === "knee_l" ? "Left" : "Right"} knee bent ${deg.toFixed(0)}deg`, f, deg, L.knee);
+		}
+	});
+	if (on("balance")) balanceMargins(out, checks.supports).forEach((m, f) => {
+		if (m === "air") push("BALANCE", "no foot on the ground", f, 0, 0);
+		else if (m !== null && -m > L.balance) {
+			const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, out.frames[f].s.P[sk.index[j]]), [0, 0, 0]), 0.25);
+			push("BALANCE", `centre of mass ${com[0].toFixed(2)},${com[2].toFixed(2)} outside the feet`, f, -m, L.balance);
+		}
+	});
+	return issues;
+}
+
+/**
+ * output.observations: measurements, not verdicts. Frames are absolute (out.f0 added).
+ * { units, peaks: { <joint>: { speed: [m/s, f], accel: [m/s^2, f] } } (joints that move: STILL),
+ *   balance: { min: [m, f], outside?: [f0, f1], air?: [[f0, f1], ...] (at most 4 runs with both
+ *   feet off the ground: the floor or an object's top) }, bend: { knee_l: [deg, f], ... } }
+ */
+export function observeMotion(sk, out, checks = {}) {
+	const f0 = out.f0 ?? 0, fps = out.fps ?? 24, peak = (arr, k) => {
+		let at = 0;
+		for (let f = 1; f < arr.length; f++) if (arr[f] > arr[at]) at = f;
+		return [Math.round(arr[at] * k * 100) / 100, at + f0];
+	};
+	const peaks = Object.fromEntries(kinematics(sk, out).map(({ j, v, a }) => [j, { speed: peak(v, fps), accel: peak(a, fps * fps) }]).filter(([, p]) => p.speed[0] >= STILL));
+	const margins = balanceMargins(out, checks.supports), span = test => {
+		const fs = margins.map((m, f) => (test(m) ? f + f0 : -1)).filter(f => f >= 0);
+		return fs.length ? [fs[0], fs[fs.length - 1]] : null;
+	}, air = airRuns(out, checks.supports).slice(0, 4).map(([a, b]) => [a + f0, b + f0]);
+	let min = null;
+	margins.forEach((m, f) => { if (typeof m === "number" && (!min || m < min[0])) min = [r2(m), f + f0]; });
+	const outside = span(m => typeof m === "number" && m < 0);
+	const bend = Object.fromEntries(BENDS.map(b => {
+		let best = [0, f0];
+		out.frames.forEach(({ s }, f) => { const d = bendAt(sk, s, b); if (d > best[0]) best = [d, f + f0]; });
+		return [b[0], [Math.round(best[0]), best[1]]];
+	}));
+	return { units: "[value, frame]; speed m/s, accel m/s^2, balance m inside the feet (< 0 outside), bend deg (0 straight)",
+		peaks, balance: { min, ...(outside ? { outside } : {}), ...(air.length ? { air } : {}) }, bend };
+}
+
+/**
+ * Per frame, how many times too fast the motion is by what QA reports (fix/retime.js): a pop
+ * against its surroundings (square root: acceleration falls with the square of the stretch) and
+ * the speed or acceleration limits the spec opted into. L = QA_LIMITS merged with own.
+ */
+export function speedExcess(sk, out, own, L) {
+	const on = k => Object.hasOwn(own ?? {}, k), e = new Float64Array(out.frames.length);
+	for (const k of kinematics(sk, out)) {
+		const { core, v, a } = k, vk = core ? "speedCore" : "speedLimb", ak = core ? "accCore" : "accLimb";
+		for (let f = 1; f < v.length; f++) {
+			if (on(vk)) e[f] = Math.max(e[f], v[f] / L[vk]);
+			if (f < 2) continue;
+			if (isPop(k, f, L[ak])) e[f] = Math.max(e[f], Math.sqrt(a[f] / Math.max(L[ak], POP_RATIO * popLevel(k, f))));
+			if (on(ak)) e[f] = Math.max(e[f], Math.sqrt(a[f] / L[ak]));
+		}
+	}
+	return e;
+}

package/src/motion3/qa/wrist-checks.js

@@ -0,0 +1,69 @@
+// QA WRIST (lane wristqa): a holding wrist at its anatomical limit is broken whatever the motion is for
+// (C13 keeps style measured, not judged; a wrist the arm had to clamp is neither). On the frames a hand
+// holds (wrist-obs.js holding: a fit, a keyed carry, a grip or a carry), the wrist's turn on its forearm
+// is read where the arm asked for it: a keyed carry's need before hold.js clamped it (diag.hold_<k>),
+// else the turn the solved pose shows at the joint, against the whole limits: the wtwist channel turns the
+// hand alone (limbs.js wrist, the forearm bone takes no share), and a grip stays inside the comfortable twist.
+// An axis more than AT deg past its limit (arm-orient.js WRIST_LIMITS: the clamp engaged, or a turn no wrist makes) is an issue:
+//   WRIST  "hand_r flex 72deg (limit 70)", value the degrees asked, limit the limit
+// Past the comfortable range only is not judged: output.observations.wrist counts it.
+// The hint moves the body, not the wrist. Which move frees it depends on the elbow's path the hold plans
+// over the whole carry (hold-plan.js), so no single frame predicts it (a 10 cm hip drop computed to free
+// the wrist at f90 of bench S6 kept it at its limit once compiled; a 20 deg lean freed 3 of its 4
+// frames): repair compiles the leans instead (repair-tune.js WRIST) and keeps the one that lowers the summed
+// severity with every goal held.
+import { WRIST_LIMITS, wristNeed } from "../compiler/arm-orient.js";
+import { palmAxes } from "../compiler/limbs.js";
+import { apply, len, mul, scale, sub, T } from "../compiler/math.js";
+import { holding } from "./wrist-obs.js";
+
+const AT = 0.5, HELD = 0.5, AXES = ["flex", "dev", "twist"], SIDES = { l: "Left", r: "Right" };
+const WORDS = { flex: v => (v >= 0 ? "flex" : "extension"), dev: v => (v >= 0 ? "radial deviation" : "ulnar deviation"), twist: () => "twist" };
+
+/** The worst axis of a wrist need against its limits: { axis, value, edge, past } (past > AT is an issue). */
+function worstAxis(need) {
+	let best = null;
+	for (const n of AXES) {
+		const [lo, hi] = WRIST_LIMITS[n], v = need[n], edge = v >= 0 ? hi : lo, past = v >= 0 ? v - hi : lo - v;
+		if (!best || past > best.past) best = { axis: n, value: v, edge, past };
+	}
+	return best;
+}
+
+/** The wrist need of hand k on frame i: the hold's (before its clamp) when a keyed carry leads it, else the joint's on the solved pose. */
+function needAt(sk, out, k, i) {
+	const { s, diag } = out.frames[i], h = diag[`hold_${k}`];
+	if ((h?.w ?? 0) > HELD) return h;
+	const S = SIDES[k], I = sk.index, hb = I[`${S}Hand`], fa = I[`${S}ForeArm`], rw = sk.restWorldRot;
+	const axT = scale(sub(s.P[hb], s.P[fa]), 1 / Math.max(1e-9, len(sub(s.P[hb], s.P[fa])))), neutral = mul(s.R[fa], mul(T(rw[fa]), rw[hb]));
+	return wristNeed(neutral, s.R[hb], axT, apply(mul(neutral, T(s.R[hb])), palmAxes(sk, s, S).l));
+}
+
+/** WRIST issues of every holding hand ({ kind, msg, frame, value, limit }, frame an out.frames index). */
+export function wristIssues(sk, out) {
+	const issues = [], f0 = out.f0 ?? 0;
+	for (const k of ["l", "r"]) out.frames.forEach((_, i) => {
+		if (!holding(out, k, i, i + f0)) return;
+		const w = worstAxis(needAt(sk, out, k, i));
+		if (w.past <= AT) return;
+		const lim = Math.abs(w.edge);
+		issues.push({ kind: "WRIST", msg: `hand_${k} ${WORDS[w.axis](w.value)} ${Math.round(Math.abs(w.value))}deg (limit ${Math.round(lim)})`, frame: i, value: +Math.abs(w.value).toFixed(2), limit: lim });
+	});
+	return issues;
+}
+
+/** WRIST group -> { cause, hint }: what bends the wrist (fix.self's elbow turn, or where the body stands), and the body moves repair tries (repair-tune.js WRIST). */
+function wristHint(X, g) {
+	const m = /^hand_([lr]) /.exec(g.subject), k = m?.[1];
+	if (!k) return null;
+	const f = g.worstFrame, where = `at f${f}${g.count > 1 ? ` (f${g.first}-f${g.last}, ${g.count} frames)` : ""}`;
+	// fix.self turned the elbow about the shoulder-wrist line and the hand kept its turn: the wrist took the turn
+	const turn = Math.round(X.out.ctx?.swivel?.[k]?.get(f) ?? 0);
+	if (Math.abs(turn) >= 1) return { cause: `fix.self elbow turn ${turn}deg at f${f}`, hint: `${g.subject} ${where}: fix.self turned the elbow ${turn} deg to keep the arm out of the body and the hand kept its turn, so the wrist took it; key elbow_${k} (the elbow pole) or the hand's target so the arm clears the body without the turn` };
+	const held = (X.out.frames[X.rel(f)]?.diag[`hold_${k}`]?.w ?? 0) > HELD && Object.keys(X.spec.objects ?? {}).find(id => X.spec.props?.[X.spec.objects[id]?.prop]?.hand === k);
+	const lean = X.fr(f).c.spine_pitch ?? 0;
+	return { cause: held ? `objects.${held}.keys near f${f}` : X.cause(`armw_${k}`, f),
+		hint: `${g.subject} ${where}: the arm cannot turn the hand that far from where the body stands; lean the upper body over the hand (spine_pitch ${Math.round(lean)} at f${f}: try ${Math.round(lean + 20)}) or bring the body to it (root), ${held ? `or key ${held} so the hand need not bend that far (its aim or pos)` : "or move what the hand reaches"}; repair: { rounds } tries leans of 10-30 deg here and keeps one that helps` };
+}
+
+export const wristHints = { WRIST: wristHint };

package/src/motion3/qa/wrist-obs.js

@@ -0,0 +1,60 @@
+// Measured, not judged (output.observations.wrist, lane wrist): how far each wrist bends while its hand
+// holds something. A hand holds on the frames a fit's weight is on (reachGrip, any fit), a keyed carry
+// leads it (diag.hold_<k>), a grip turns it (diag.grip_<k>) or it carries a body. On those frames the
+// hand's turn relative to its forearm is read the way compiler/hold.js turns it (arm-orient.js
+// wristNeed): flex (+ toward the palm), deviation (+ toward the thumb, radial; - ulnar) and the twist the
+// wrist joint shows (the forearm bone takes FOREARM_SHARE of a turn, so the joint's comfortable twist
+// is that share of the forearm's). Frames past the comfortable ranges (arm-orient.js WRIST_COMFORT) and
+// at the anatomical limits (WRIST_LIMITS) are counted.
+// Why: a hand drawn by keys bent 70 deg (the limit) with 33 deg of ulnar deviation for frames while QA
+// stayed clean (bench S6), and no answer said so. The shoulder too (lane elbow): a cup held at the mouth with
+// the upper arm 130-160 deg up, the elbow 20 cm over the shoulder, in most bench cup takes.
+import { wristNeed, WRIST_LIMITS, WRIST_COMFORT, FOREARM_SHARE } from "../compiler/arm-orient.js";
+import { palmAxes } from "../compiler/limbs.js";
+import { apply, len, mul, scale, sub, T } from "../compiler/math.js";
+import { handOf } from "../object-pose.js";
+
+const HOLD = 0.5, AT = 1, LEVEL = 90;
+const JOINT = { twist: 1 - FOREARM_SHARE, flex: 1, dev: 1 };
+const range = (k, table) => table[k].map(v => v * JOINT[k]);
+
+export const WRIST_UNITS = "wrist: deg on the frames a hand holds (a fit, a carry or a grip on); flex + toward the palm, dev + radial / - ulnar, twist at the wrist joint; [min, f, max, f], frames past the comfortable range and at the limit; grip: the grip a keyed carry of a thin body keeps (grip-choice.js), cost [it, today's] (comfort-priced wrist, reach and body over the keys); elevation [max deg, f] of the upper arm (90 level), raised: frames the elbow is over the shoulder";
+
+/** True when the hand of side k holds something on frame i of out (absolute frame f); qa/wrist-checks.js reads it too. */
+export function holding(out, k, i, f) {
+	const { diag } = out.frames[i], baked = out.baked ?? {};
+	if ((diag[`hold_${k}`]?.w ?? 0) > HOLD || (diag[`grip_${k}`]?.w ?? 0) > HOLD) return true;
+	for (const fit of out.ctx.spec.fits ?? []) if (fit.side === k && (baked[`w_${fit.anchor}_${k}`]?.[f] ?? 0) > HOLD) return true;
+	return Object.keys(out.ctx.spec.objects ?? {}).some(id => out.ctx.spec.objects[id]?.prop && handOf(out, id, f) === k);
+}
+
+/** observeWrist(sk, out) -> { hand_l?, hand_r? } or null when no hand holds anything. Frames are absolute. */
+export function observeWrist(sk, out) {
+	const I = sk.index, rw = sk.restWorldRot, f0 = out.f0 ?? 0, res = {};
+	for (const [S, k] of [["Left", "l"], ["Right", "r"]]) {
+		const h = I[`${S}Hand`], fa = I[`${S}ForeArm`], a = I[`${S}Arm`], row = { frames: 0, past: 0, limit: 0, raised: 0 };
+		out.frames.forEach(({ s }, i) => {
+			const f = i + f0;
+			if (!holding(out, k, i, f)) return;
+			const axT = scale(sub(s.P[h], s.P[fa]), 1 / Math.max(1e-9, len(sub(s.P[h], s.P[fa])))), neutral = mul(s.R[fa], mul(T(rw[fa]), rw[h]));
+			const need = wristNeed(neutral, s.R[h], axT, apply(mul(neutral, T(s.R[h])), palmAxes(sk, s, S).l));
+			row.frames++;
+			for (const n of ["flex", "dev", "twist"]) {
+				const v = Math.round(need[n]), cur = row[n];
+				row[n] = cur ? [Math.min(cur[0], v), v < cur[0] ? f : cur[1], Math.max(cur[2], v), v > cur[2] ? f : cur[3]] : [v, f, v, f];
+			}
+			// past the comfortable range by more than a degree; at a limit within a degree of it
+			const outside = (table, by) => ["flex", "dev", "twist"].some(n => { const [lo, hi] = range(n, table); return need[n] < lo + by || need[n] > hi - by; });
+			if (outside(WRIST_COMFORT, -AT)) row.past++;
+			if (outside(WRIST_LIMITS, AT)) row.limit++;
+			// the shoulder (lane elbow): the upper arm's elevation from hanging down, and the frames the elbow is over the shoulder's level
+			const up = sub(s.P[fa], s.P[a]), el = Math.round((Math.acos(Math.max(-1, Math.min(1, -up[1] / Math.max(1e-9, len(up))))) * 180) / Math.PI);
+			if (!row.elevation || el > row.elevation[0]) row.elevation = [el, f];
+			if (el > LEVEL) row.raised++;
+		});
+		if (row.frames) res[`hand_${k}`] = row;
+	}
+	// the grip a keyed carry chose for where it goes (grip-choice.js): what the hand of that carry holds
+	for (const g of out.ctx.hold?.grips?.() ?? []) if (res[`hand_${g.hand}`]) res[`hand_${g.hand}`].grip = { object: g.id, chose: g.name, cost: [g.cost, g.today] };
+	return Object.keys(res).length ? res : null;
+}

package/src/motion3/refs.js

@@ -0,0 +1,129 @@
+// C2. Point references, the one grammar goals, probes and the timeline use (spec.checks keep
+// their older joint/prop/anchor subset, validate-common.js refOk):
+//   joint:<Bone> | bone:<Bone>          the bone's joint (the two are the same; names go through bones.js)
+//   prop:<prop>.<point>                 a point of a held prop (spec.props; "origin" always exists)
+//   anchor:<name>                       a spec anchor, resolved as the compiler resolves it
+//   landmark:mouth                      the measured face landmark
+//   person:<id>.<Bone>                  another character's joint where its installed take has it (people.js)
+//   object:<id>[.center|.top|.base]     a body or a group (object-pose.js objectBoxesAt): the centre,
+//                                       top-face centre or bottom-face centre of the AABB of its
+//                                       part boxes' corners (default center)
+// Frames are absolute; a frame outside the compiled window (out.f0 ..) answers null.
+import { REF_KINDS } from "./schema/fields.js";
+import { resolveBone } from "./bones.js";
+import { objectBoxesAt, partsOf } from "./object-pose.js";
+import { objectOk } from "./compiler/validate-common.js";
+import { resolveAnchor } from "./compiler/anchors.js";
+import { bonePoint } from "./compiler/skeleton.js";
+import { didYouMean } from "./compiler/vocab.js";
+import { add, apply, sub, len } from "./compiler/math.js";
+import { sdBox } from "./qa/geometry.js";
+import { personJoint, peopleList } from "./people.js";
+
+const SYNTAX = { joint: "joint:<Bone>", bone: "bone:<Bone>", prop: "prop:<prop>.<point>", anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base]", person: "person:<id>.<Bone>" };
+
+function parse(ref) {
+	const m = /^([a-z]+):(.+)$/s.exec(String(ref));
+	if (!m) return null;
+	const [, kind, rest] = m;
+	if (kind === "prop") { const [name, point] = rest.split("."); return { kind, name, point: point ?? "" }; }
+	if (kind === "object") { const o = /^(.+)\.(center|top|base)$/s.exec(rest); return { kind, name: o ? o[1] : rest, point: o ? o[2] : null }; }
+	if (kind === "person") { const dot = rest.lastIndexOf("."); return { kind, name: dot > 0 ? rest.slice(0, dot) : rest, point: dot > 0 ? rest.slice(dot + 1) : "" }; }
+	return { kind, name: rest, point: null };
+}
+
+function boxesPoint(boxes, which) {
+	const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+	for (const b of boxes) for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) {
+		const p = add(b.pos, apply(b.R, [x * b.half[0], y * b.half[1], z * b.half[2]]));
+		for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i], p[i]); hi[i] = Math.max(hi[i], p[i]); }
+	}
+	const c = [(lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, (lo[2] + hi[2]) / 2];
+	return which === "top" ? [c[0], hi[1], c[2]] : which === "base" ? [c[0], lo[1], c[2]] : c;
+}
+
+/** World point [x, y, z] of `ref` at absolute frame f of compile result out, or null. */
+export function refPoint(out, f, ref) {
+	const fr = out.frames?.[f - (out.f0 ?? 0)], r = parse(ref);
+	if (!fr || !r) return null;
+	const { s, diag, c } = fr, sk = out.ctx.sk;
+	switch (r.kind) {
+		case "joint": case "bone": { const { bone } = resolveBone(sk, r.name); return bone ? s.P[sk.index[bone]].slice() : null; }
+		case "prop": { const p = diag.props?.[r.name]?.[r.point]; return Array.isArray(p) ? p.slice() : null; }
+		case "anchor": return out.ctx.spec.anchors?.[r.name] ? resolveAnchor(out.ctx, r.name, s, { ...diag, frame: f }, c) : null;
+		case "landmark": return sk.landmarks?.[r.name] ? bonePoint(s, sk.index.Head, sk.landmarks[r.name]) : null;
+		case "object": { const boxes = objectBoxesAt(out, r.name, f); return boxes ? boxesPoint(boxes, r.point) : null; }
+		case "person": return personJoint(out.ctx.scene, r.name, r.point, f);
+		default: return null;
+	}
+}
+
+/**
+ * Metres between refs a and b at absolute frame f, or null when either is unknown there. A bare
+ * object:<id> (no .center/.top/.base) means "to the object's surface": the distance from the
+ * other point to the nearest part box (sdBox, 0 inside); two bare objects measure a's centre to
+ * b's surface. Any other pair is the distance between the two points.
+ */
+export function refDistance(out, f, a, b) {
+	const bare = ref => { const r = parse(ref); return r?.kind === "object" && r.point === null ? r : null; };
+	const surf = bare(b) ? [a, bare(b)] : bare(a) ? [b, bare(a)] : null;
+	if (surf) {
+		const p = refPoint(out, f, surf[0]), boxes = objectBoxesAt(out, surf[1].name, f);
+		return p && boxes ? Math.max(0, Math.min(...boxes.map(box => sdBox(p, box)))) : null;
+	}
+	const p = refPoint(out, f, a), q = refPoint(out, f, b);
+	return p && q ? len(sub(p, q)) : null;
+}
+
+/**
+ * The prefixed refs a bare name could mean in this spec, rig and scene (`; did you mean
+ * "object:empty-2"?`), or "". A field that takes more than one ref kind stays strict.
+ */
+function bareHint(spec, { sk, scene }, ref, kinds) {
+	if (typeof ref !== "string" || !ref) return "";
+	const id = ref.replace(/\.(center|top|base)$/, ""), [prop, point] = ref.split(".");
+	const bone = sk && (kinds.includes("joint") || kinds.includes("bone")) ? resolveBone(sk, ref).bone : null;
+	const known = [
+		kinds.includes("object") && (scene?.objects?.[id] || partsOf(scene, id).length) && `object:${ref}`,
+		bone && `${kinds.includes("joint") ? "joint" : "bone"}:${bone}`,
+		kinds.includes("anchor") && spec.anchors?.[ref] && `anchor:${ref}`,
+		kinds.includes("prop") && spec.props?.[prop] && (point === "origin" || spec.props[prop].points?.[point]) && `prop:${ref}`,
+		kinds.includes("landmark") && ref === "mouth" && "landmark:mouth",
+	].filter(Boolean);
+	return known.length ? `; did you mean ${known.map(k => `"${k}"`).join(" or ")}?` : "";
+}
+
+/**
+ * Validates ref against the spec (props, anchors), the rig (bones) and the scene (objects and
+ * groups). Reports one exact message through err, prefixed `${at} "${ref}"`, and answers whether
+ * the ref is good. kinds limits the grammar (default all of REF_KINDS). A bare name (no kind:)
+ * is refused with the forms it could mean (bareHint).
+ */
+export function checkRef(spec, err, { sk, scene }, at, ref, kinds = REF_KINDS) {
+	const r = parse(ref), tag = `${at} "${ref}"`;
+	if (!r || !kinds.includes(r.kind)) { err(`${tag} must be ${kinds.map(k => SYNTAX[k]).join(", ")}${r ? "" : bareHint(spec, { sk, scene }, ref, kinds)}`); return false; }
+	if (r.kind === "joint" || r.kind === "bone") {
+		const { bone, hint } = sk ? resolveBone(sk, r.name) : { bone: r.name };
+		if (!bone) err(`${tag}: unknown bone${hint}`);
+		return Boolean(bone);
+	}
+	if (r.kind === "prop") {
+		const ok = Boolean(spec.props?.[r.name] && (r.point === "origin" || spec.props[r.name].points?.[r.point]));
+		if (!ok) err(`${tag}: spec.props has no point ${r.name}.${r.point}`);
+		return ok;
+	}
+	if (r.kind === "anchor") {
+		if (!spec.anchors?.[r.name]) err(`${tag}: no anchor "${r.name}" in spec.anchors${didYouMean(r.name, Object.keys(spec.anchors ?? {}))}`);
+		return Boolean(spec.anchors?.[r.name]);
+	}
+	if (r.kind === "landmark") {
+		if (r.name !== "mouth") err(`${tag}: the only landmark is "mouth"`);
+		return r.name === "mouth";
+	}
+	if (r.kind === "person") {
+		const ok = Boolean(personJoint(scene, r.name, r.point, 0));
+		if (!ok) err(`${tag}: no person "${r.name}" with joint "${r.point}" (people with an installed take: ${peopleList(scene)})`);
+		return ok;
+	}
+	return objectOk(err, scene, tag, r.name, { groups: true });
+}

package/src/motion3/repair-tune.js

@@ -0,0 +1,121 @@
+// C6. Repair's second move: a QA group just past its limit that carries no patch. Its cause names
+// what made it, and a skill arg or a key time maps to the geometry too indirectly for a hint to
+// predict (in the cup take, firstStep -1 cm cleared a thigh hit but a 5.04 cm/f^2 pop appeared;
+// step did nothing). A compile is cheap, so repair tries a few small changes instead and keeps
+// the best (repair.js), like an automatic { range } that stays near the agent's value:
+//   cause "... use[i] <skill> ..."          each arg in SKILL_INFO[skill].tune, 1 then 2 steps
+//                                             either way, from the arg as sent or its default
+//   SPEED/ACC/POP "between keys[a] fA and keys[b] fB" (the agent's keys)
+//                                             key a 1 or 2 frames earlier, key b later
+//   GOAL up to 10 cm short (with or without a patch): where the body stands at the worst frame,
+//                                             1 then 2 steps either way: the agent's root keys
+//                                             there (x, z), else the last standIdle/walkTo before
+//                                             it (SKILL_INFO[skill].place); then the lean, the
+//                                             spine_pitch of the agent's keys around it (5 deg)
+//   WRIST (qa/wrist-checks.js) at the worst frame: a lean there (a spine_pitch key 10, 20 or 30 deg
+//                                             forward of the lean before it, or 10 back, eased back to it 12
+//                                             frames either side when no lean key is nearer), then the lean
+//                                             keys around it 5 or 10 deg either way; which move frees
+//                                             a held wrist depends on the elbow path the hold plans, so it is
+//                                             compiled (on bench S6 the body's floor steps only made it worse)
+//                                             ; none when fix.self's elbow turn bent it (cause "fix.self ..."): a lean
+//                                             does not undo the turn (car exit: 21 compiles, 20 s, 57 -> 51 deg)
+// Every candidate is a JSON Patch on the agent's spec; the order is fixed, so the search is
+// deterministic. Least-change candidates come first, so a tie keeps the smaller edit.
+import { excessOf } from "./qa/severity.js";
+import { SKILL_INFO } from "./skills/info.js";
+
+const NEAR = 0.5, STEPS = [-1, 1, -2, 2], PLACE_MAX = 0.1, LEAN = 5;
+const isNum = x => typeof x === "number" && Number.isFinite(x);
+
+/** A group no more than half its limit (or 5 mm, for small limits) past it. */
+const nearLimit = g => excessOf(g) <= NEAR * Math.max(Math.abs(g.limit), 0.01);
+
+/** use[i] <skill>: one patch per tune arg and step, smallest steps first. */
+function skillCandidates(cause, spec) {
+	const m = /\buse\[(\d+)\] (\w+)/.exec(cause), i = Number(m?.[1]), u = m && spec.use?.[i];
+	const info = m && u?.skill === m[2] ? SKILL_INFO[u.skill] : null;
+	if (!info?.tune) return [];
+	const out = [];
+	for (const n of [1, 2]) for (const [arg, step] of Object.entries(info.tune)) {
+		const schema = info.args[arg] ?? {}, now = u.args?.[arg] ?? schema.default;
+		if (!isNum(now)) continue;
+		for (const sg of STEPS.filter(s => Math.abs(s) === n)) {
+			const raw = now + sg * step, value = schema.type === "integer" ? Math.round(raw) : Math.round(raw * 1e4) / 1e4;
+			if (!(value > 0) || value === now) continue;
+			out.push(u.args ? [{ op: u.args[arg] === undefined ? "add" : "replace", path: `/use/${i}/args/${arg}`, value }]
+				: [{ op: "add", path: `/use/${i}/args`, value: { [arg]: value } }]);
+		}
+	}
+	return out;
+}
+
+/** SPEED/ACC/POP between two of the agent's keys: more frames between them, 1 then 2. */
+function keyCandidates(g, cause, spec) {
+	if (!["SPEED", "ACC", "POP"].includes(g.kind)) return [];
+	const m = /between keys\[(\d+)\] f(\d+) and keys\[(\d+)\] f(\d+)/.exec(cause);
+	if (!m) return [];
+	const [a, fa, b, fb] = m.slice(1).map(Number), keys = spec.keys ?? [];
+	if (keys[a]?.f !== fa || keys[b]?.f !== fb) return [];
+	const last = Number.isInteger(spec.frames) ? spec.frames - 1 : Infinity, out = [];
+	for (const n of [1, 2]) {
+		if (fa - n >= 0) out.push([{ op: "replace", path: `/keys/${a}/f`, value: fa - n }]);
+		if (fb + n <= last) out.push([{ op: "replace", path: `/keys/${b}/f`, value: fb + n }]);
+	}
+	return out;
+}
+
+const round4 = v => Math.round(v * 1e4) / 1e4;
+
+/** One step (n = 1 or 2, either way) of what places the body at frame f, then of the lean. */
+function placeSteps(spec, f, n) {
+	const keys = spec.keys ?? [], out = [];
+	const skill = (spec.use ?? []).map((u, i) => ({ u, i })).filter(({ u }) => (u?.skill === "standIdle" || u?.skill === "walkTo") && u.f0 <= f).sort((a, b) => a.u.f0 - b.u.f0).at(-1);
+	const roots = keys.map((k, j) => ({ k, j })).filter(({ k }) => Array.isArray(k?.set?.root) && k.set.root.length === 3 && isNum(k.f) && k.f > (skill?.u.f0 ?? -1));
+	if (roots.some(({ k }) => k.f <= f)) {
+		for (const axis of [0, 2]) for (const sg of [-n, n]) out.push(roots.map(({ k, j }) => ({ op: "replace", path: `/keys/${j}/set/root`, value: k.set.root.map((v, a) => (a === axis ? round4(v + sg * 0.03) : v)) })));
+	} else if (skill) {
+		const { u, i } = skill, place = SKILL_INFO[u.skill].place ?? {}, steps = u.args?.steps ?? 8;
+		for (const [arg, step] of Object.entries(place)) {
+			if (arg === "step" && steps <= 2) continue;
+			const now = u.args?.[arg] ?? SKILL_INFO[u.skill].args[arg]?.default;
+			const set = value => [u.args ? { op: u.args[arg] === undefined ? "add" : "replace", path: `/use/${i}/args/${arg}`, value } : { op: "add", path: `/use/${i}/args`, value: { [arg]: value } }];
+			if (Array.isArray(now)) for (const axis of [0, now.length - 1]) for (const sg of [-n, n]) out.push(set(now.map((v, a) => (a === axis ? round4(v + sg * step) : v))));
+			else if (isNum(now)) for (const sg of [-n, n]) if (now + sg * step > 0.05) out.push(set(round4(now + sg * step)));
+		}
+	}
+	const pitched = keys.map((k, j) => ({ f: k?.f, j })).filter(({ j }) => isNum(keys[j]?.set?.spine_pitch) && isNum(keys[j].f)).sort((a, b) => a.f - b.f);
+	const lean = [pitched.filter(p => p.f <= f).at(-1), pitched.find(p => p.f > f)].filter(Boolean).map(p => p.j);
+	for (const sg of lean.length ? [n, -n] : []) out.push(lean.map(j => ({ op: "replace", path: `/keys/${j}/set/spine_pitch`, value: keys[j].set.spine_pitch + sg * LEAN })));
+	return out;
+}
+
+const LEANS = [10, 20, 30, -10], EASE = 12;
+
+/** WRIST: a spine_pitch key at f that leans the upper body by d from the lean before it, eased back over EASE frames where no lean key is nearer. */
+function leanSteps(spec, f) {
+	const keys = spec.keys ?? [], at = Math.round(f), last = Number.isInteger(spec.frames) ? spec.frames - 1 : Infinity;
+	const pitched = keys.filter(k => isNum(k?.f) && isNum(k?.set?.spine_pitch)).sort((a, b) => a.f - b.f);
+	const prev = pitched.filter(k => k.f < at).at(-1), next = pitched.find(k => k.f > at), base = prev?.set.spine_pitch ?? 0;
+	const same = keys.findIndex(k => k?.f === at && k.set && typeof k.set === "object");
+	return LEANS.map(d => {
+		const value = base + d, ops = [same >= 0 ? { op: keys[same].set.spine_pitch === undefined ? "add" : "replace", path: `/keys/${same}/set/spine_pitch`, value } : { op: "add", path: "/keys/-", value: { f: at, set: { spine_pitch: value } } }];
+		if ((!prev || at - prev.f > EASE) && at - EASE >= 0) ops.push({ op: "add", path: "/keys/-", value: { f: at - EASE, set: { spine_pitch: base } } });
+		if ((!next || next.f - at > EASE) && at + EASE <= last) ops.push({ op: "add", path: "/keys/-", value: { f: at + EASE, set: { spine_pitch: next?.set.spine_pitch ?? base } } });
+		return ops;
+	});
+}
+
+/**
+ * tuneCandidates(g, spec) -> patch[] (each a JSON Patch on spec; [] when the group is not near its
+ * limit, already carries a patch, or its cause names nothing tunable; a GOAL group up to 10 cm
+ * short also gets the body placement steps)
+ */
+export function tuneCandidates(g, spec) {
+	if (typeof g.cause !== "string") return [];
+	if (g.kind === "WRIST" && g.cause.startsWith("fix.self")) return [];
+	if (g.kind === "WRIST" && isNum(g.worstFrame)) return [...leanSteps(spec, g.worstFrame), ...[1, 2].flatMap(n => placeSteps(spec, g.worstFrame, n)).filter(p => p.every(op => op.path.endsWith("/spine_pitch")))];
+	const near = !g.patch && nearLimit(g) ? [...skillCandidates(g.cause, spec), ...keyCandidates(g, g.cause, spec)] : [];
+	if (g.kind !== "GOAL" || !isNum(g.worstFrame) || excessOf(g) > PLACE_MAX) return near;
+	return [...near, ...placeSteps(spec, g.worstFrame, 1), ...placeSteps(spec, g.worstFrame, 2)];
+}