cozyclay 2.1.0 → 3.0.0

package/src/motion3/qa/hints-goal.js

@@ -0,0 +1,160 @@
+// Hints for GOAL groups (C8, C6). The hint moves whatever drives the goal's moving side at the
+// worst frame by the shortfall (+3 mm): a hand (a hand joint, a prop point, an object in hand),
+// else a foot or the root, through moveHint (hints-contact.js, read only). The fix is
+// { channel: "hand_l", f, delta } when the hand target drives that hand (qa/patch.js turns it into
+// a patch), { path: "/anchors/<a>/p", delta } when a world anchor does, and none for an FK arm.
+// still moves the point back toward where it should stay; speed and a goal that waits on another
+// (after/before) get a hint without a fix. Two causes come first, because moving the hand target
+// cannot cure them:
+//   - another anchor weight of that hand is above 0 at the frame (it ramps between two keys
+//     across the goal), so the hand goes part of the way to that anchor: key it 0 there;
+//   - the arm is at full reach (the wrist target is clamped or missed): move the body (bodyMove).
+import { resolveBone } from "../bones.js";
+import { inHandAt } from "../object-pose.js";
+import { refPoint } from "../refs.js";
+import { scale, norm, sub, len } from "../compiler/math.js";
+import { moveHint } from "./hints-contact.js";
+import { goalKinds, goalName, goalNeed, goalWindow, movedHome, movedRef } from "./goals.js";
+import { m3, vec } from "./fmt.js";
+
+const MARGIN = 0.003, LEAK = 0.02, BODY_MAX = 0.2;
+
+/**
+ * The body move that brings shoulder k `need` m nearer its hand at f (the arm points at its
+ * target when at full reach): { delta, hint, fix } with fix { channel: "root", f, delta, hold:
+ * true } (qa/patch.js moves what places the body: a standIdle at, a walkTo's steps or the agent's
+ * root keys). null when the arm points mostly up or down, where walking closer does not help.
+ */
+export function bodyMove(X, k, f, need, why = "") {
+	const S = k === "l" ? "Left" : "Right", { s } = X.fr(f), v = sub(s.P[X.I[`${S}Hand`]], s.P[X.I[`${S}Arm`]]);
+	const flat = Math.hypot(v[0], v[2]) / Math.max(len(v), 1e-9);
+	if (flat < 0.5) return null;
+	const delta = scale(norm([v[0], 0, v[2]]), Math.min(BODY_MAX, need / flat));
+	return { delta, hint: `body: move ${vec(delta)} m toward the target at f${f}, ${X.cause("root", f)} (arm ${k} is at full reach)${why}`, fix: { channel: "root", f, delta, hold: true } };
+}
+
+/** Arm k cannot reach its wrist target at f (soft reach clamped it, or the IK missed; not a target inside the elbow's fold, arm_fold). */
+const atReach = (X, k, f) => (X.fr(f).diag[`reach_over_${k}`] ?? 0) > 1e-3 || ((X.fr(f).diag[`arm_miss_${k}`] ?? 0) > 2e-3 && !X.fr(f).diag[`arm_fold_${k}`]);
+
+/** The largest other anchor weight of hand k above LEAK at f while `drive` leads it, or null. */
+function leakOf(X, k, f, drive) {
+	let best = null;
+	for (const [ch, w] of Object.entries(X.fr(f).c)) {
+		if (ch === drive || !new RegExp(`^w_.+_${k}$`).test(ch) || !(w > LEAK) || (best && w <= best.w)) continue;
+		best = { ch, w };
+	}
+	return best;
+}
+
+/** Leak hint: key the stray weight 0 at the goal's last frame when it rises from 0 there, else at f. */
+function leakHint(X, goal, part, f, why) {
+	const k = part.slice(-1), d = X.hand(k, f), leak = d.anchor ? leakOf(X, k, f, d.ch) : null;
+	if (!leak) return null;
+	const end = Array.isArray(goal.at) ? goal.at[1] : goal.at, prev = X.bracket(leak.ch, f).prev;
+	const at = prev && Math.abs(X.out.baked[leak.ch]?.[Math.round(prev.f)] ?? 1) <= LEAK && end >= f && !(X.bracket(leak.ch, f).next?.f <= end) ? end : f;
+	const share = leak.w / Math.max(1, (X.fr(f).c[d.ch] ?? 1) + leak.w), other = leak.ch.replace(/^w_/, "").replace(/_[lr]$/, "");
+	return { cause: X.cause(leak.ch, f), hint: `${leak.ch} is ${m3(leak.w)} at f${f}, so anchor ${other} takes ${Math.round(share * 100)}% of the hand target from ${d.label}: key ${leak.ch} 0 at f${at}${why}`,
+		fix: { channel: leak.ch, f: at, value: 0 } };
+}
+
+/** The goal a GOAL group reports: the longest name its subject starts with. */
+function goalOf(X, g) {
+	let best = null;
+	(X.spec?.goals ?? []).forEach((goal, i) => {
+		const name = goalName(goal, i);
+		if (g.subject.startsWith(`${name}:`) && (!best || name.length > best.name.length)) best = { goal, name, i };
+	});
+	return best;
+}
+
+/** The record that carries object `id` at frame f (the id itself or a group above it), or null. */
+function carrierOf(X, id, f) {
+	const ids = [id, ...(X.out.ctx.scene?.objects?.[id]?.ancestors ?? [])];
+	const key = ids.find(k => inHandAt(X.spec.objects?.[k], f));
+	return key ? X.spec.objects[key] : null;
+}
+
+/** The body part (moveHint name) that moves ref at frame f: hand_<k>, foot_<k>, root, or null for a still point. */
+function partOf(X, ref, f) {
+	const [, kind, rest] = /^([a-z]+):(.+)$/s.exec(ref) ?? [];
+	if (kind === "prop") return X.spec.props?.[rest.split(".")[0]]?.hand ? `hand_${X.spec.props[rest.split(".")[0]].hand}` : null;
+	if (kind === "object") {
+		const o = carrierOf(X, rest.replace(/\.(center|top|base)$/, ""), f), k = o && X.spec.props?.[o.prop]?.hand;
+		return k ? `hand_${k}` : null;
+	}
+	if (kind === "landmark") return "root";
+	if (kind !== "joint" && kind !== "bone") return null;
+	const bone = resolveBone(X.sk, rest).bone ?? "", side = /^Left/.test(bone) ? "l" : /^Right/.test(bone) ? "r" : null;
+	if (side && /^(Left|Right)(Hand|ForeArm)/.test(bone)) return `hand_${side}`;
+	if (side && /^(Left|Right)(Foot|Toe|Leg)/.test(bone)) return `foot_${side}`;
+	return "root";
+}
+
+/** fix for moving `part` by delta at f, when it applies to a channel or a world anchor. */
+function fixFor(X, part, f, delta) {
+	const k = part.slice(-1);
+	if (!part.startsWith("hand_")) return { channel: part, f, delta };
+	const d = X.hand(k, f);
+	if (d.ch === `hand_${k}`) return { channel: d.ch, f, delta };
+	if (d.anchor && X.spec.anchors?.[d.anchor]?.kind === "world") return { path: `/anchors/${d.anchor}/p`, delta };
+	return null;
+}
+
+/** The side to move and its delta: [part, delta], hands first, then a body part, a to b (still: back toward its home, from `from`). */
+function plan(X, goal, kind, f, amount, from) {
+	if (kind === "moved" || kind === "still") {
+		const ref = goal[kind], part = partOf(X, ref, f), home = movedHome(X.out, goal, from), p = refPoint(X.out, f, movedRef(ref));
+		const away = p && home && len(sub(p, home)) > 1e-3 ? norm(sub(p, home)) : [0, 1, 0];
+		return part ? [part, scale(away, kind === "still" ? -amount : amount)] : null;
+	}
+	const [a, b] = goal[kind], pa = partOf(X, a, f), pb = partOf(X, b, f);
+	const rank = p => (p?.startsWith("hand_") ? 2 : p ? 1 : 0), moveA = rank(pa) >= rank(pb);
+	const part = moveA ? pa : pb, sign = moveA ? 1 : -1;
+	if (!part) return null;
+	if (kind === "above") return [part, [0, sign * amount, 0]];
+	const qa = refPoint(X.out, f, a), qb = refPoint(X.out, f, b);
+	return qa && qb ? [part, scale(norm(sub(qb, qa)), sign * amount)] : null;
+}
+
+export const goalHints = {
+	/** GOAL(X, g) -> { cause, hint, fix? } | null */
+	GOAL(X, g) {
+		const found = X.spec && goalOf(X, g), f = g.worstFrame;
+		if (!found) return { cause: `goal ${g.subject.split(":")[0]}`, hint: `change the keys around f${f} until the goal holds` };
+		const { goal, name, i } = found, kind = goalKinds(goal)[0], amount = g.worst + MARGIN, w = goalWindow(X.out, X.spec.goals, i);
+		if (w.wait) {
+			const other = goal.after ?? goal.before;
+			return { cause: `goal ${name}`, hint: `${name} ${w.wait}: make goal "${other}" hold${goal.after !== undefined && goal.before !== undefined ? ` and "${goal.before}"` : ""} where this one needs it, or move at` };
+		}
+		const unit = kind === "speed" ? "m/s" : "m", at = kind === "near" || kind === "still" ? "<=" : ">=";
+		const why = ` (goal "${name}" is ${m3(g.worst)} ${unit} ${kind === "still" ? "off" : "short"}; needs ${at} ${goalNeed(goal, kind)})`;
+		if (kind === "speed") {
+			const part = partOf(X, goal.speed, f);
+			return { cause: part ? X.cause(part, f) : `goal ${name}`,
+				hint: `${goal.speed} is too slow at f${f}: put its keys around f${f} closer in time, or farther apart in space${why}` };
+		}
+		const move = plan(X, goal, kind, f, amount, w.a);
+		if (!move) {
+			if (kind === "still" && goal.still.startsWith("object:")) {
+				const id = goal.still.slice(7).replace(/\.(center|top|base)$/, "");
+				return { cause: `objects.${id}`, hint: `${id} moves at f${f}, where it should stay: hold its hinge channel or keys until then, or start them later${why}` };
+			}
+			if (kind === "still") return { cause: `goal ${name}`, hint: `${goal.still} moves at f${f} and nothing that follows the body moves it; name a joint, prop point or held object${why}` };
+			if (kind === "moved" && !goal.moved.startsWith("object:")) return { cause: `goal ${name}`, hint: `${goal.moved} does not move with the body at f${f}; name a joint, prop point or held object` };
+			if (kind === "moved") {
+				const id = goal.moved.slice(7).replace(/\.(center|top|base)$/, "");
+				return { cause: `objects.${id}`, hint: `${id} is not in a hand at f${f}, so nothing moves it: carry it (objects.${id} = { prop, grab }) or hinge it` };
+			}
+			return { cause: `goal ${name}`, hint: `neither ${goal[kind][0]} nor ${goal[kind][1]} moves with the body at f${f}; name a joint, prop point or held object` };
+		}
+		const [part, delta] = move;
+		if (part.startsWith("hand_")) {
+			const leak = leakHint(X, goal, part, f, why);
+			if (leak) return leak;
+			const body = atReach(X, part.slice(-1), f) && bodyMove(X, part.slice(-1), f, amount, why);
+			if (body) return { cause: X.cause("root", f), hint: body.hint, fix: body.fix };
+		}
+		const r = moveHint(X, part, f, delta, why), fix = fixFor(X, part, f, delta);
+		return { cause: r.cause, hint: r.hint, ...(fix ? { fix } : {}) };
+	},
+};

package/src/motion3/qa/hints-knee.js

@@ -0,0 +1,24 @@
+// The knee's stop in QA hints (compiler/limbs.js KNEE_FOLD, KNEE_STOP). An ankle target nearer the hip
+// than the knee folds leaves the ankle farther out: under the hip in a squat, down into the floor. So
+// REACH leg_miss, GROUND on that foot and KNEE (folds past the stop) say the same thing: the hips are
+// lower than the legs fold, bring the root up off the feet (a target above the hip: the foot out from it).
+import { sub, scale, norm, len, dist, dot } from "../compiler/math.js";
+import { reachAt, KNEE_FOLD, KNEE_STOP } from "../compiler/limbs.js";
+import { vec, m3 } from "./fmt.js";
+
+/** What the solver says of a knee on its stop: ` (the knee would fold 168deg; it bends to 150deg and stops at 160deg)`. */
+export const kneeWhy = (lead, asked) => ` (${lead}the knee would fold ${Math.round(asked)}deg; it bends to ${KNEE_FOLD}deg and stops at ${KNEE_STOP}deg)`;
+
+/**
+ * Hint for leg k at frame f whose ankle point T (the foot_k target, or the drawn ankle) is nearer the
+ * hip than the knee folds KNEE_FOLD: the root up by what puts T at that fold's reach when T is under the
+ * hip, else foot_k out from the hip by that much. `why` says why (kneeWhy).
+ */
+export function kneeFoldHint(X, k, f, why, T) {
+	const S = k === "l" ? "Left" : "Right", P = X.fr(f).s.P, H = P[X.I[`${S}UpLeg`]], K = P[X.I[`${S}Leg`]], A = P[X.I[`${S}Foot`]];
+	const v = sub(T, H), R = reachAt(dist(H, K), dist(K, A), KNEE_FOLD) + 0.002, out = scale(norm(v), Math.max(0, R - len(v)));
+	// the hips up by d leave the target R from the hip: |v - d up| = R, the root above the target
+	const d = v[1] + Math.sqrt(Math.max(0, v[1] * v[1] - dot(v, v) + R * R));
+	if (v[1] < 0) return { cause: X.cause("root", f), hint: `root: raise ${m3(d)} m at f${f}${why}, or key foot_${k} farther from the hip (wider or more forward)`, fix: { channel: "root", f, delta: [0, d, 0] } };
+	return { cause: X.cause(`foot_${k}`, f), hint: `foot_${k}: move ${vec(out)} m out from the hip at f${f}${why}, or raise root ${m3(d)} m`, fix: { channel: `foot_${k}`, f, delta: out } };
+}

package/src/motion3/qa/hints-motion.js

@@ -0,0 +1,209 @@
+// Hints for motion-type issues (reach, knees and elbows past their stop, pole flips, sliding, pops,
+// floating, opted-in speed and acceleration) and for the spec's own checks (contacts, orient,
+// below, appear). Orient and below try small changes of the wrist or elbow channels on the worst
+// frame and scale the best one to the needed amount.
+import { add, sub, scale, norm, len, dist, angle, apply, ry, clamp, dot } from "../compiler/math.js";
+import { solveFrame } from "../compiler/compile.js";
+import { channelsAt } from "../compiler/channels.js";
+import { resolveAnchor } from "../compiler/anchors.js";
+import { carried, reachAt, ELBOW_FOLD, ELBOW_STOP, KNEE_FOLD } from "../compiler/limbs.js";
+import { pointOf } from "./spec-checks.js";
+import { solePoints, ankleY } from "./geometry.js";
+import { vec, m3 } from "./fmt.js";
+import { moveHint } from "./hints-contact.js";
+import { kneeFoldHint, kneeWhy } from "./hints-knee.js";
+import { bodyMove } from "./hints-goal.js";
+
+const LIMB = { Leg: ["UpLeg", "Leg", "Foot", "knee"], ForeArm: ["Arm", "ForeArm", "Hand", "elbow"] };
+const sideOf = s => (s.startsWith("Left") ? "l" : "r");
+const weightOf = ch => (/^(w_|armw)/.test(ch) ? 0.5 : /^(root|foot|hand)/.test(ch) ? 1 : /^(knee|elbow)/.test(ch) ? 0.2 : 0.01);
+
+/** Channels that move joint j, ranked by how much each changed into frame f (metres-equivalent). */
+function movers(X, j, f) {
+	const k = sideOf(j), b = X.out.baked;
+	let list = ["root", "yaw", "pitch"];
+	if (j === "Head") list = ["head_yaw", "head_pitch", "spine_pitch", "spine_yaw", "root", "yaw"];
+	else if (/Hand|ForeArm/.test(j)) list = [`hand_${k}`, `armw_${k}`, `elbow_${k}`, `aswing_${k}`, `abend_${k}`, ...Object.keys(b).filter(ch => new RegExp(`^w_.+_${k}$`).test(ch)), "spine_yaw", "spine_pitch", "root", "yaw"];
+	else if (/Foot|Leg/.test(j)) list = [`foot_${k}`, `knee_${k}`, `fpitch_${k}`, "root"];
+	const change = ch => {
+		const a = b[ch]?.[f - 1], c = b[ch]?.[f];
+		if (a === undefined || c === undefined || typeof a === "object" && !Array.isArray(a)) return 0;
+		return (Array.isArray(a) ? dist(a, c) : Math.abs(c - a)) * weightOf(ch);
+	};
+	return list.filter(ch => b[ch]).sort((p, q) => change(q) - change(p));
+}
+
+function speedHint(X, g, power) {
+	const j = g.subject.split(" ")[0], f = g.worstFrame, ch = movers(X, j, f)[0] ?? "root";
+	const { prev, next } = X.bracket(ch, f), stepped = X.keys(ch).find(k => k.step && Math.abs(k.f - f) <= 1);
+	if (stepped) return { cause: X.cause(ch, f), hint: `${ch}: a step key jumps at f${Math.round(stepped.f)}; ease it over 4+ frames (key the old value 4 frames earlier, drop the step)` };
+	const factor = Math.ceil(Math.pow(g.worst / g.limit, power) * 1.1 * 10) / 10;
+	const a = Math.round(prev?.f ?? f - 4), b = Math.round(next?.f ?? f + 4), extra = Math.ceil((b - a) * (factor - 1));
+	const anchor = /^w_(.+)_[lr]$/.exec(ch);
+	return { cause: X.cause(ch, f), hint: `retime: stretch f${a}-f${b} by ${factor}x (+${extra} frames, move the keys from f${b} on later)${anchor ? ` - the hand switches to anchor ${anchor[1]} too fast` : ""}; or fix.retime: true`,
+		fix: X.spec.fix === false ? undefined : { path: "/fix/retime", value: true } };
+}
+
+/** A check point (joint:/prop:/anchor:) on a freshly solved frame. */
+function pointOn(X, fr, ref) {
+	const [kind, rest] = ref.split(/:(.*)/s);
+	if (kind === "joint") return fr.s.P[X.I[rest]];
+	if (kind === "prop") { const [p, pt] = rest.split("."); return fr.diag.props?.[p]?.[pt]; }
+	return resolveAnchor(X.out.ctx, rest, fr.s, fr.diag, fr.c);
+}
+
+/** Try channel changes on frame f; returns the best { ch, value, gain } for measure() (higher is better). */
+function probe(X, f, tries, measure) {
+	const c0 = channelsAt(X.out.baked, f), base = measure(X.fr(f));
+	let best = null;
+	for (const [ch, value, unit] of tries) {
+		const gain = measure(solveFrame(X.out.ctx, { ...c0, [ch]: value }, f)) - base;
+		if (gain > 1e-6 && (!best || gain / unit > best.gain / best.unit)) best = { ch, value, gain, unit };
+	}
+	return { best, base, c0 };
+}
+
+const hipOrShoulder = (X, k, f, limb) => X.fr(f).s.P[X.I[`${k === "l" ? "Left" : "Right"}${LIMB[limb][0]}`]];
+
+export const motionHints = {
+	REACH(X, g) {
+		const [, limb, k] = /^(leg|arm)_miss_([lr])$/.exec(g.subject) ?? [], f = g.worstFrame, need = g.worst + 0.002;
+		if (limb === "leg") {
+			// an ankle target nearer the hip than the knee folds (compiler/limbs.js): the hips up off it
+			const fold = X.fr(f).diag[`leg_fold_${k}`];
+			if (fold) return kneeFoldHint(X, k, f, kneeWhy(`the ankle target is ${m3(g.worst)} m inside the shin's reach: `, fold), X.fr(f).c[`foot_${k}`]);
+			const T = X.fr(f).c[`foot_${k}`] ?? [0, 0, 0], H = hipOrShoulder(X, k, f, "Leg"), v = sub(T, H), R = dist(H, T) - g.worst;
+			const disc = v[1] * v[1] - dot(v, v) + R * R, side = [v[0], 0, v[2]];
+			const alt = disc >= 0 ? `or root down ${m3(-v[1] - Math.sqrt(disc) + 0.002)} m${g.worst <= 0.05 ? " (fix.reach does this when on)" : ""}`
+				: `or root ${vec(scale(norm(side), len(side) - R * 0.95))} m toward the foot (the foot is ${m3(len(side))} m sideways of the hip: the root and foot keys disagree)`;
+			return { cause: X.cause(`foot_${k}`, f), hint: `foot_${k}: move ${vec(scale(norm(sub(H, T)), need))} m toward the hip at f${f}, ${alt}`, fix: { channel: `foot_${k}`, f, delta: scale(norm(sub(H, T)), need) } };
+		}
+		const S = k === "l" ? "Left" : "Right", { s, diag } = X.fr(f), dir = norm(sub(s.P[X.I[`${S}Hand`]], s.P[X.I[`${S}Arm`]]));
+		// a target nearer the shoulder than the elbow folds (compiler/limbs.js): out from the shoulder, or the body back from it
+		const fold = diag[`arm_fold_${k}`];
+		if (fold) {
+			const r = moveHint(X, `hand_${k}`, f, scale(dir, need), ` (the hand target is ${m3(g.worst)} m inside the forearm's reach: the elbow would fold ${Math.round(fold)}deg; it bends to ${ELBOW_FOLD}deg and stops at ${ELBOW_STOP}deg)`);
+			return { cause: r.cause, hint: `${r.hint}, or bring root ${vec(scale([-dir[0], 0, -dir[2]], need))} m back from it`, fix: r.fix };
+		}
+		const r = moveHint(X, `hand_${k}`, f, scale(dir, -need), "");
+		// a hand on a point the scene or the spec pins (an object anchor, one a goal or contact check names) stays: the body comes closer
+		const a = X.hand(k, f).anchor, refs = JSON.stringify([X.spec.goals ?? [], X.spec.checks?.contacts ?? []]);
+		const pinned = a && (X.spec.anchors?.[a]?.kind === "object" || refs.includes(`"anchor:${a}"`)), fit = X.spec.fits?.[X.hand(k, f).fit ?? -1];
+		// a fit pushes the wrist target far past reach; the body comes as far as the effector is short
+		const eff = fit?.effector?.prop && X.fr(f).diag.props?.[fit.effector.prop]?.[fit.effector.point];
+		const gap = eff ? dist(eff, add(pointOn(X, X.fr(f), `anchor:${a}`), fit.offset ?? [0, 0, 0])) + 0.01 : need;
+		const body = pinned && bodyMove(X, k, f, Math.min(need, gap));
+		if (body) return { cause: r.cause, hint: `${body.hint} (out of reach by ${m3(g.worst)} m), or ${r.hint}`, fix: body.fix };
+		return { cause: r.cause, hint: `${r.hint} (out of reach by ${m3(g.worst)} m), or bring root ${vec(scale([dir[0], 0, dir[2]], need))} m closer`, fix: r.fix };
+	},
+	KNEE(X, g) {
+		const k = sideOf(g.subject), S = k === "l" ? "Left" : "Right", f = g.worstFrame, { s, c } = X.fr(f), P = s.P, I = X.I;
+		if (/backward/.test(g.subject)) {
+			const toe = sub(P[I[`${S}ToeBase`]], P[I[`${S}Foot`]]); toe[1] = 0;
+			const pole = add(norm(apply(ry(-(c.yaw ?? 0)), toe)), [0, 0.3, 0]);
+			return { cause: X.cause(`knee_${k}`, f), hint: `knee_${k}: key ${vec(norm(pole))} (body frame, along the foot) at f${f}; a knee pole is +z forward, +x the character's left`, fix: { channel: `knee_${k}`, f, value: norm(pole) } };
+		}
+		// past the stop (the solver stops every knee at KNEE_STOP, so this pose came from outside it): the hips up off the foot
+		if (/ folds /.test(g.subject)) return kneeFoldHint(X, k, f, ` (the knee folds ${m3(g.worst)}deg, past its ${g.limit}deg stop; it bends freely to ${KNEE_FOLD}deg)`, P[I[`${S}Foot`]]);
+		const H = P[I[`${S}UpLeg`]], K = P[I[`${S}Leg`]], A = P[I[`${S}Foot`]], a = dist(H, K), b = dist(K, A);
+		const inner = (180 - (g.limit - 5)) * Math.PI / 180, want = Math.sqrt(a * a + b * b - 2 * a * b * Math.cos(inner));
+		return { cause: X.cause(`foot_${k}`, f), hint: `foot_${k}: move ${vec(scale(norm(sub(A, H)), want - dist(H, A)))} m away from the hip at f${f} (the knee folds ${m3(g.worst)} deg, limit ${g.limit})`,
+			fix: { channel: `foot_${k}`, f, delta: scale(norm(sub(A, H)), want - dist(H, A)) } };
+	},
+	// the solver stops every elbow at ELBOW_STOP, so a fold past it comes from outside the solver: the hand out from the shoulder
+	ELBOW(X, g) {
+		const k = sideOf(g.subject), S = k === "l" ? "Left" : "Right", f = g.worstFrame, P = X.fr(f).s.P, I = X.I;
+		const A = P[I[`${S}Arm`]], E = P[I[`${S}ForeArm`]], W = P[I[`${S}Hand`]], delta = scale(norm(sub(W, A)), reachAt(dist(A, E), dist(E, W), ELBOW_FOLD) - dist(A, W));
+		return moveHint(X, `hand_${k}`, f, delta, ` (the elbow folds ${m3(g.worst)}deg, past its ${g.limit}deg stop; it bends freely to ${ELBOW_FOLD}deg)`);
+	},
+	FLIP(X, g) {
+		const [, S, limb] = /^(Left|Right)(Leg|ForeArm) /.exec(g.subject) ?? [], f = g.worstFrame;
+		if (!limb) return null;
+		const k = sideOf(S), [r, m, e, pole] = LIMB[limb], I = X.I, gap = +(/ over (\d+) frames$/.exec(g.subject)?.[1] ?? 1);
+		// an elbow on its stop: the target passes near the shoulder and the stopped hand swings round it, whatever the pole
+		const fd = X.fr(f).diag, asked = limb === "ForeArm" && (fd[`arm_fold_${k}`] ?? fd[`hold_${k}`]?.fold);
+		if (asked) {
+			const held = fd[`hold_${k}`]?.fold && Object.entries(X.spec.objects ?? {}).find(([, o]) => o.keys?.length && X.spec.props?.[o.prop]?.hand === k)?.[0];
+			return { cause: held ? `objects.${held}.keys` : X.cause(X.hand(k, f).ch, f), hint: `the ${held ? `keys of ${held} ask` : "hand target asks"} the elbow to fold ${Math.round(asked)}deg at f${f}, past its ${ELBOW_STOP}deg stop, so the hand swings round the shoulder on the stop: move ${held ? "the keyed pose" : "the target"} out from the shoulder (REACH says how far)` };
+		}
+		const bendAt = q => { const P = X.fr(q).s.P; return angle(sub(P[I[`${S}${m}`]], P[I[`${S}${r}`]]), sub(P[I[`${S}${e}`]], P[I[`${S}${m}`]])); };
+		// a flip over several frames passed through the straight (or folded) frames between: the straightest names it
+		const fb = Array.from({ length: Math.max(1, gap - 1) }, (_, i) => (gap > 1 ? f - 1 - i : f)).reduce((p, q) => (bendAt(q) < bendAt(p) ? q : p)), bend = bendAt(fb);
+		const ch = `${pole}_${k}`, prevPole = X.out.baked[ch]?.[Math.max(0, f - 1)];
+		if (prevPole && len(prevPole) < 0.5) return { cause: X.cause(ch, f), hint: `${ch}: the pole passes near zero (length ${m3(len(prevPole))}) at f${f} while it turns between opposite keys; add an in-between pole key (e.g. the average direction, normalised) so it turns, not shrinks` };
+		const straight = bend < 12 ? `the limb is almost straight at f${fb} (bend ${m3(bend)} deg), so the pole cannot hold it: bring the ${limb === "Leg" ? "foot" : "hand"} target ~0.02 m toward the ${limb === "Leg" ? "hip" : "shoulder"}, or ` : "";
+		return { cause: X.cause(ch, f), hint: `${ch}: ${straight}keep the pole on one side through f${f}${prevPole ? ` (key ${vec(prevPole)} there)` : ""}`, fix: prevPole && { channel: ch, f, value: prevPole } };
+	},
+	SLIDE(X, g) {
+		const k = sideOf(g.subject), S = k === "l" ? "Left" : "Right", key = g.subject.includes("heel") ? "heel" : "ball";
+		const f0 = Math.max(0, g.first - 1), at = f => solePoints(X.sk, X.fr(f).s, S)[key];
+		const slid = Math.hypot(at(g.last)[0] - at(f0)[0], at(g.last)[2] - at(f0)[2]), hold = X.out.baked[`foot_${k}`]?.[f0];
+		// the ankle stays and the foot turns flat on the floor (fyaw): the turn is the slide
+		const turn = X.out.baked[`fyaw_${k}`], end = X.out.baked[`foot_${k}`]?.[g.last];
+		if (turn && hold && end && Math.hypot(end[0] - hold[0], end[2] - hold[2]) < slid / 2 && Math.abs(turn[g.last] - turn[f0]) > 1) return { cause: X.cause(`fyaw_${k}`, g.worstFrame),
+			hint: `fyaw_${k}: the flat foot turns ${m3(turn[f0])} -> ${m3(turn[g.last])} deg over f${f0}-f${g.last} and the ${key} slides ${m3(slid)} m; key fyaw_${k} ${m3(turn[f0])} at f${g.last} so it turns once the foot is up, or lift the heel first (fpitch_${k} +) so it pivots on the ball`,
+			fix: { channel: `fyaw_${k}`, f: g.last, value: turn[f0] } };
+		return { cause: X.cause(`foot_${k}`, g.worstFrame), hint: `foot_${k}: hold it still over f${f0}-f${g.last}${hold ? ` (key ${vec(hold)} at both ends)` : ""}; the ${key} slides ${m3(slid)} m${slid < 0.01 ? "; fix.slide locks this when on" : ""}`,
+			fix: hold && { channel: `foot_${k}`, f: g.last, value: hold } };
+	},
+	SPEED: (X, g) => speedHint(X, g, 1),
+	POP: (X, g) => speedHint(X, g, 0.5),
+	ACC: (X, g) => speedHint(X, g, 0.5),
+	FLOAT: (X, g) => ({ cause: X.cause("root", g.worstFrame), hint: `over f${g.first}-f${g.last} lower the root or key foot_l/foot_r back onto the ground, the floor or the top of an object under the foot (the ankle stands ${ankleY(X.sk)} m above it); a jump needs the hips to rise and fall; a seat or ledge the hips rest on goes in checks.supports (a foot on an object's top needs none)` }),
+	LENGTH: () => ({ cause: "compiler", hint: "a bone changed length: report the spec, this is a compiler fault" }),
+	CONTACT(X, g) {
+		const ck = (X.spec.checks?.contacts ?? []).find(c => g.subject.startsWith(`${c.name}:`)), f = g.worstFrame, i = X.rel(f);
+		if (!ck) return null;
+		const a = pointOf(X.out, i, ck.point), b = pointOf(X.out, i, ck.target), delta = sub(b, a);
+		const prop = /^prop:([^.]+)/.exec(ck.point), k = prop ? X.spec.props?.[prop[1]]?.hand : sideOf(ck.point.slice(6));
+		const { diag } = X.fr(f), over = Math.max(diag[`reach_over_${k}`] ?? 0, diag[`arm_miss_${k}`] ?? 0);
+		const anchor = /^anchor:(.+)$/.exec(ck.target)?.[1], fit = (X.spec.fits ?? []).findIndex(ft => ft.side === k && ft.anchor === anchor);
+		const cause = fit >= 0 ? `fits[${fit}] (${k} -> anchor ${anchor})` : moveHint(X, `hand_${k}`, f, delta).cause;
+		const toRoot = scale(norm([delta[0], 0, delta[2]]), over + 0.01), fold = diag[`arm_fold_${k}`];
+		if (over > 0.002 && fold) {
+			const S = X.fr(f).s.P[X.I[`${k === "l" ? "Left" : "Right"}Arm`]], back = scale(norm([S[0] - b[0], 0, S[2] - b[2]]), over + 0.01);
+			return { cause, hint: `inside the forearm's reach by ${m3(over)} m at f${f} (the elbow would fold ${Math.round(fold)}deg; it stops at ${ELBOW_STOP}deg): bring root ${vec(back)} m back from ${anchor ?? "the target"}, or move the target out from the shoulder`, fix: { channel: "root", f, delta: back } };
+		}
+		if (over > 0.002) return { cause, hint: `out of reach by ${m3(over)} m at f${f}: bring root ${vec(toRoot)} m toward ${anchor ?? "the target"}, or move the target`, fix: { channel: "root", f, delta: toRoot } };
+		const r = moveHint(X, `hand_${k}`, f, delta);
+		return { cause, hint: `${r.hint}${fit < 0 && anchor ? `; or add fits: [{ side: "${k}", anchor: "${anchor}", effector: ${prop ? `{ prop: "${prop[1]}", point: "${ck.point.split(".")[1]}" }` : "{ joints: [...] }"} }]` : ""}`, fix: r.fix };
+	},
+	ORIENT(X, g) {
+		const ck = (X.spec.checks?.orient ?? []).find(c => g.subject.startsWith(`${c.name}:`)), f = g.worstFrame;
+		if (!ck) return null;
+		const prop = /^prop:([^.]+)/.exec(ck.from), k = prop ? X.spec.props?.[prop[1]]?.hand : sideOf(ck.from.slice(6)), minCos = ck.minCos ?? 0.64;
+		const along = fr => (ck.along === "up" ? [0, 1, 0] : ck.along === "face" ? carried(X.sk, fr.s, X.I.Head, [0, 0, 1]) : norm(ck.along));
+		const cos = fr => dot(norm(sub(pointOn(X, fr, ck.to), pointOn(X, fr, ck.from))), along(fr));
+		const c = channelsAt(X.out.baked, f), tw = c[`wtwist_${k}`] ?? 0, fx = c[`wflex_${k}`] ?? 0;
+		const { best, base } = probe(X, f, [[`wtwist_${k}`, clamp(tw + 15, -85, 85), 15], [`wtwist_${k}`, clamp(tw - 15, -85, 85), 15], [`wflex_${k}`, clamp(fx + 15, -70, 70), 15], [`wflex_${k}`, clamp(fx - 15, -70, 70), 15]], cos);
+		if (!best) return { cause: X.cause(`wtwist_${k}`, f), hint: `turn the prop another way: wrist twist/flex do not help at f${f} (cos ${m3(base)}, needs ${minCos}); change elbow_${k} or the prop points` };
+		const from = best.ch.startsWith("wtwist") ? tw : fx, lim = best.ch.startsWith("wtwist") ? 85 : 70;
+		const want = clamp(from + (best.value - from) * Math.min(4, (minCos - base + 0.03) / best.gain), -lim, lim);
+		return { cause: X.cause(best.ch, f), hint: `${best.ch}: key ${m3(want)} deg at f${f} (now ${m3(from)}; cos ${m3(base)}, needs ${minCos})`, fix: { channel: best.ch, f, value: want } };
+	},
+	BELOW(X, g) {
+		const ck = (X.spec.checks?.below ?? []).find(c => g.subject.startsWith(`${c.name}:`)), f = g.worstFrame;
+		if (!ck) return null;
+		const k = sideOf(ck.joint), ch = `${/Leg/.test(ck.joint) ? "knee" : "elbow"}_${k}`, pole = channelsAt(X.out.baked, f)[ch] ?? [0, -1, -0.3];
+		const drop = fr => fr.s.P[X.I[ck.ref]][1] - fr.s.P[X.I[ck.joint]][1];
+		// candidate poles (body frame), nearest to the current one first among those that are enough
+		const need = (ck.min ?? 0.08) + 0.01, c0 = channelsAt(X.out.baked, f), base = drop(X.fr(f));
+		const tries = [[0, -1, 0], [0.5, -1, 0], [-0.5, -1, 0], [0, -1, -0.4], [0, -1, 0.4], [0.5, -1, 0.5], [-0.5, -1, 0.5], [0.5, -1, -0.4], [-0.5, -1, -0.4]]
+			.map(p => ({ p, d: drop(solveFrame(X.out.ctx, { ...c0, [ch]: p }, f)), turn: angle(p, pole) }));
+		const ok = tries.filter(t => t.d >= need).sort((p, q) => p.turn - q.turn)[0], best = ok ?? tries.sort((p, q) => q.d - p.d)[0];
+		if (!(best.d > base)) return { cause: X.cause(ch, f), hint: `${ch}: no pole change lowers ${ck.joint} at f${f}; lower the hand target instead` };
+		return { cause: X.cause(ch, f), hint: `${ch}: key ${vec(best.p)} (body frame: +y up, +z forward) at f${f} (${ck.joint} ${m3(base)} m below ${ck.ref} -> ${m3(best.d)}, needs ${ck.min ?? 0.08})`, fix: { channel: ch, f, value: best.p } };
+	},
+	APPEAR(X, g) {
+		const ck = (X.spec.checks?.appear ?? []).find(c => g.subject.startsWith(`${c.name}:`)), f = g.worstFrame;
+		if (!ck) return null;
+		let best = null;
+		for (let q = Math.max(X.out.f0 ?? 0, f - 24); q <= Math.min((X.out.f0 ?? 0) + X.out.frames.length - 1, f + 24); q++) {
+			const d = len(sub(pointOf(X.out, X.rel(q), `joint:${ck.joint}`), pointOf(X.out, X.rel(q), `anchor:${ck.anchor}`)));
+			if (!best || d < best.d) best = { q, d };
+		}
+		const tol = ck.tol ?? 0.035;
+		return { cause: X.cause(ck.channel, f), hint: best.d <= tol ? `${ck.channel}: move the step from f${f} to f${best.q} (${ck.joint} ${m3(best.d)} m from ${ck.anchor} there)`
+			: `${ck.joint} never gets within ${tol} m of ${ck.anchor} near f${f} (closest ${m3(best.d)} m at f${best.q}): hold its weight w_${ck.anchor}_${sideOf(ck.joint)} at 1 around the switch` };
+	},
+};

package/src/motion3/qa/hints-object.js

@@ -0,0 +1,91 @@
+// Hints for object issues (C3, C6, 7.1). A hint function takes the explain context X
+// (qa/explain.js) and the group g and returns { cause, hint, fix? } (fix: see qa/patch.js).
+//   GRAB     looks within +-24 frames for the frame nearest the grab where the hand is within the
+//            limit and proposes fix { path: "/objects/<id>/grab", value: f }; failing that it
+//            moves the hand to the object (moveHint) with a fix on what drives the hand
+//   COLLIDE  for a carried object ("<part> x <id>", "<id> x <other>") moves the holding hand,
+//            so the object comes out; the other hand's arm in it while that hand is on an object
+//            anchor on it moves the anchor's local point out instead; any other COLLIDE is the body hint (hints-contact.js)
+//   REACH    for a keyed object ("<id>: 6.2 cm off its keys", key-checks.js); else the arm and leg hint (hints-motion.js)
+import { contactHints, moveHint } from "./hints-contact.js";
+import { motionHints } from "./hints-motion.js";
+import { keyHint } from "./key-checks.js";
+import { CAPSULES, segPoints, sdBox, boxNormal } from "./geometry.js";
+import { grabGap, boxOverlap } from "./object-checks.js";
+import { isCarried, propOrigin } from "../carried.js";
+import { objectBoxesAt, partsOf, spanOf } from "../object-pose.js";
+import { groupsOf } from "../scene.js";
+import { sub, scale, len, apply, T, add, clamp } from "../compiler/math.js";
+
+const MARGIN = 0.003, SEARCH = 24;
+
+/** A fix that moves hand k by delta at f, on whatever drives it there (hand channel, fit or world anchor). */
+function handFix(X, k, f, delta) {
+	const d = X.hand(k, f);
+	if (d.ch === `hand_${k}`) return { channel: d.ch, f, delta };
+	if (d.fit !== null && d.fit !== undefined) return X.spec.fits[d.fit].offset ? { path: `/fits/${d.fit}/offset`, delta } : { path: `/fits/${d.fit}/offset`, value: delta };
+	if (d.anchor && X.spec.anchors?.[d.anchor]?.kind === "world") return { path: `/anchors/${d.anchor}/p`, delta };
+	return undefined;
+}
+
+function moveHand(X, k, f, delta, why) {
+	const r = moveHint(X, `hand_${k}`, f, delta, why), fix = handFix(X, k, f, delta);
+	return fix ? { ...r, fix } : r;
+}
+
+/** True when hand k is on an object anchor (weight > 0.5) on record `id` or a body or group under it at f. */
+function anchoredOn(X, k, f, id) {
+	const a = X.spec.anchors?.[X.hand(k, f).anchor], scene = X.out.ctx.scene;
+	return a?.kind === "object" && [scene.objects?.[a.object]?.ancestors, groupsOf(scene)[a.object]?.ancestors, [a.object]].some(ids => ids?.includes(id));
+}
+
+/** Closest point of a box (base pivot) to p. */
+function closest(box, p) {
+	const q = apply(T(box.R), sub(p, box.pos)), c = [0, box.half[1], 0];
+	return add(box.pos, apply(box.R, q.map((v, i) => clamp(v, c[i] - box.half[i], c[i] + box.half[i]))));
+}
+
+export const objectHints = {
+	REACH: (X, g) => keyHint(X, g) ?? motionHints.REACH(X, g),
+	/** GRAB(X, g) -> { cause, hint, fix? } */
+	GRAB(X, g) {
+		const id = g.subject.split(":")[0], grab = g.worstFrame, o = X.spec?.objects?.[id];
+		const plain = { cause: `objects.${id}.grab`, hint: `${id}: move the hand to it by f${grab}, or set objects.${id}.grab to the frame the hand arrives` };
+		if (!X.out || !isCarried(o)) return plain;
+		let best = null;
+		for (let f = grab - SEARCH; f <= grab + SEARCH; f++) {
+			const gap = grabGap(X.out, id, f);
+			if (gap !== null && gap <= g.limit && (!best || Math.abs(f - grab) < Math.abs(best[0] - grab))) best = [f, gap];
+		}
+		if (best) return { cause: plain.cause, hint: `${id}: set objects.${id}.grab to ${best[0]} (the hand is ${(best[1] * 100).toFixed(1)} cm from it there, ${(g.worst * 100).toFixed(1)} cm at f${grab})`, fix: { path: `/objects/${id}/grab`, value: best[0] } };
+		const { sk, spec, scene } = X.out.ctx, p = propOrigin(sk, spec, X.fr(grab).s, o);
+		const target = partsOf(scene, id).map(part => closest(scene.objects[part], p)).reduce((a, b) => (len(sub(b, p)) < len(sub(a, p)) ? b : a));
+		const gap = len(sub(target, p)), delta = scale(sub(target, p), gap > 1e-9 ? (gap - g.limit / 2) / gap : 0);
+		const r = moveHand(X, spec.props[o.prop].hand, grab, delta, ` (to ${id} at grab)`);
+		return { ...r, hint: `${r.hint}; or set objects.${id}.grab to the frame the hand arrives` };
+	},
+	/** COLLIDE(X, g) for a carried object, else the body hint. */
+	COLLIDE(X, g) {
+		const [, a, b] = /^(\S+) x (.+)$/.exec(g.subject) ?? [], objects = X.spec?.objects ?? {};
+		const id = isCarried(objects[b]) ? b : isCarried(objects[a]) ? a : null;
+		if (!id || !X.out) return contactHints.COLLIDE(X, g);
+		const o = objects[id], k = X.spec.props[o.prop].hand, [grab, release] = spanOf(X.out, o), need = g.worst - g.limit + MARGIN;
+		const f = g.worstFrame, held = f >= grab && f <= release, at = Math.min(f, release), boxes = objectBoxesAt(X.out, id, f) ?? [];
+		if (id === b) {
+			const cap = CAPSULES.find(c => c[0] === a), { s } = X.fr(f);
+			if (!cap || !boxes.length) return null;
+			const pts = segPoints(s.P[X.I[cap[1]]], s.P[X.I[cap[2]]]);
+			const [box, p] = boxes.flatMap(bx => pts.map(q => [bx, q])).reduce((m, x) => (sdBox(x[1], x[0]) < sdBox(m[1], m[0]) ? x : m));
+			const n = boxNormal(p, box), j = /^(hand|farm|uarm)_([lr])$/.exec(a)?.[2];
+			// the other hand on an object anchor on what hand k carries rides with it: moving the carry cannot part them, its point moves out
+			if (held && j && j !== k && anchoredOn(X, j, f, id)) return moveHint(X, `hand_${j}`, f, scale(n, need), ` (out of ${id})`);
+			return held ? moveHand(X, k, f, scale(n, -need), ` (${id} off ${a})`) : moveHint(X, a, f, scale(n, need), ` (out of ${id})`);
+		}
+		const ob = X.out.objectsAt(X.rel(f))[b];
+		if (!ob || !boxes.length) return null;
+		// out on the side it came from: where it was the frame before the hit (or at grab)
+		const was = objectBoxesAt(X.out, id, Math.max(grab, g.first - 1)) ?? boxes;
+		const hit = boxes.map((bx, i) => boxOverlap(bx, ob, sub(was[i].pos, ob.pos))).reduce((m, x) => (x.depth > m.depth ? x : m));
+		return moveHand(X, k, at, scale(hit.axis, hit.depth - g.limit + MARGIN), held ? ` (${id} out of ${b})` : ` (${id} is put down in ${b}; it stays where the hand lets go at f${release})`);
+	},
+};

package/src/motion3/qa/index.js

@@ -0,0 +1,42 @@
+// Motion QA entry: general checks on every take, the checks the spec declares, the objects it
+// moves (object-checks.js), its goals (goals.js) and the style checks it opted into by naming
+// their limit (style.js; otherwise style is measured, not judged: observeMotion). Groups are
+// ranked by severity.js.
+import { generalChecks, QA_LIMITS } from "./checks.js";
+import { styleChecks, floatChecks } from "./style.js";
+import { specChecks } from "./spec-checks.js";
+import { objectChecks } from "./object-checks.js";
+import { goalChecks } from "./goals.js";
+import { wristIssues } from "./wrist-checks.js";
+import { explainGroups } from "./explain.js";
+import { LOW_IS_BAD, groupKey, rankGroups } from "./severity.js";
+
+/** Group issues by kind + subject (severity.js groupKey); each group reports count, worst value and frame range. */
+function summarizeIssues(issues) {
+	const groups = new Map();
+	for (const i of issues) {
+		const key = groupKey({ kind: i.kind, subject: i.msg });
+		const g = groups.get(key) ?? { kind: i.kind, subject: i.msg, count: 0, worst: i.value, worstFrame: i.frame, first: i.frame, last: i.frame, limit: i.limit };
+		g.count++; g.first = Math.min(g.first, i.frame); g.last = Math.max(g.last, i.frame);
+		const worse = LOW_IS_BAD.has(i.kind) ? i.value < g.worst : i.value > g.worst;
+		if (worse) { g.worst = i.value; g.worstFrame = i.frame; g.subject = i.msg; }
+		groups.set(key, g);
+	}
+	return rankGroups([...groups.values()]);
+}
+
+/**
+ * opts.explain (default true) adds cause + hint (and patch, qa/patch.js) to the top groups
+ * (explain.js); opts.userSpec is the spec as the agent sent it, which patches address. Frames
+ * are absolute even when the compile was windowed (out.f0). qa.goals is there when spec.goals is.
+ */
+export function runMotionQa(sk, out, spec, opts = {}) {
+	const checks = spec.checks ?? {}, goals = goalChecks(out, spec.goals ?? []);
+	const issues = [...generalChecks(sk, out, { allow: checks.allow, limits: checks.limits, mouthPoints: checks.mouthPoints }), ...specChecks(out, checks),
+		...objectChecks(sk, out, spec), ...floatChecks(out, checks),
+		...styleChecks(sk, out, checks, { ...QA_LIMITS, ...checks.limits }), ...wristIssues(sk, out), ...goals.issues];
+	if (out.f0) for (const i of issues) i.frame += out.f0;
+	const groups = summarizeIssues(issues);
+	if (opts.explain !== false) explainGroups(sk, out, spec, groups, { userSpec: opts.userSpec });
+	return { ok: issues.length === 0, total: issues.length, ...(spec.goals ? { goals: goals.results } : {}), groups };
+}

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

@@ -0,0 +1,82 @@
+// QA of held-object keys (C14, ../object-keys.js). From the first to the last key the object
+// leads the hand; the object is drawn in the hand, so what the arm or the wrist could not reach
+// leaves the object off the pose its keys ask for. That residual is measured on the object, as the
+// farthest corner of its part boxes from where the keys put it:
+//   REACH  "<id>: 6.2 cm off its keys", value metres, limit checks.limits.reach (default 0.01)
+// The hint names the key and why the hand fell short (diag.hold_<side>, compiler/hold.js): the
+// arm out of reach, the grip nearer the shoulder than the elbow folds (compiler/limbs.js), or a
+// wrist turn past its limit after the elbow swung and the forearm turned (lane K8: the whole arm
+// follows the object, compiler/arm-orient.js).
+// Measured, not judged (C16, output.observations.held): every key as drawn, so the agent sees how
+// far each one is from what the hand can hold without a probe.
+import { keyedEntries, curveIn, keyedPose } from "../object-keys.js";
+import { rootPoseAt, partsOf } from "../object-pose.js";
+import { relative } from "../carried.js";
+import { groupsOf } from "../scene.js";
+import { WRIST_LIMITS } from "../compiler/arm-orient.js";
+import { ELBOW_FOLD, ELBOW_STOP } from "../compiler/limbs.js";
+import { add, apply, dist, norm, angle, matFromQuat } from "../compiler/math.js";
+
+const SUBJECT = /^(.+): [\d.]+ cm off its keys$/;
+const WRIST_WORDS = { twist: "twist about the forearm", flex: "flex", dev: "deviation (+ toward the thumb)" };
+
+/** The corners of id's part boxes in its root frame (the box spans y 0..2 half on its base pivot). */
+function cornersOf(scene, id) {
+	const root = scene.objects[id] ?? groupsOf(scene)[id];
+	return partsOf(scene, id).flatMap(p => {
+		const box = scene.objects[p], rel = relative(root, box), [x, y, z] = box.half;
+		return [-x, x].flatMap(a => [0, 2 * y].flatMap(b => [-z, z].map(c => add(rel.pos, apply(rel.R, [a, b, c])))));
+	});
+}
+
+/** REACH issues of every keyed carry, frames as out.frames indexes. */
+export function keyIssues(out, L, push) {
+	const { scene } = out.ctx, f0 = out.f0 ?? 0;
+	for (const [id] of keyedEntries(out.ctx.spec)) {
+		const curve = curveIn(out, id), corners = cornersOf(scene, id);
+		if (!corners.length) continue;
+		for (let f = Math.max(f0, Math.ceil(curve.t[0])); f <= Math.min(f0 + out.frames.length - 1, Math.floor(curve.t[curve.t.length - 1])); f++) {
+			const want = keyedPose(curve, f), got = rootPoseAt(out, id, f);
+			const off = Math.max(...corners.map(c => dist(add(want.pos, apply(want.R, c)), add(got.pos, apply(got.R, c)))));
+			if (off > L.reach) push("REACH", `${id}: ${(off * 100).toFixed(1)} cm off its keys`, f - f0, off, L.reach);
+		}
+	}
+}
+
+/** REACH for a keyed object ("<id>: 6.2 cm off its keys") -> { cause, hint }, else null. */
+export function keyHint(X, g) {
+	const id = SUBJECT.exec(g.subject)?.[1], o = X.spec?.objects?.[id];
+	if (!o?.keys?.length) return null;
+	const f = g.worstFrame, k = X.spec.props?.[o.prop]?.hand, h = X.fr(f).diag[`hold_${k}`] ?? {};
+	const near = o.keys.reduce((best, key, i) => (Math.abs(key.f - f) < Math.abs(o.keys[best].f - f) ? i : best), 0);
+	const wrist = Object.entries(WRIST_LIMITS).filter(([n, [lo, hi]]) => h[n] < lo || h[n] > hi).map(([n, [lo, hi]]) => `the wrist ${WRIST_WORDS[n]} needs ${Math.round(h[n])}deg (limit ${lo}..${hi})`);
+	// the arm already swung the elbow and turned the forearm (compiler/arm-orient.js): say so with what the wrist still needs
+	if (wrist.length) wrist[wrist.length - 1] += ` after the elbow swung ${Math.round(h.swivel ?? 0)}deg and the forearm turned`;
+	// the grip nearer the shoulder than the elbow folds (h.fold, the flexion it asked): out from the shoulder, not nearer the hand
+	const fold = h.miss > 0.005 && h.fold, short = fold ? `the grip is ${(h.miss * 100).toFixed(1)} cm inside the forearm's reach (the elbow would fold ${Math.round(h.fold)}deg; it bends to ${ELBOW_FOLD}deg and stops at ${ELBOW_STOP}deg)` : `the arm is ${(h.miss * 100).toFixed(1)} cm short`;
+	const why = [...(h.miss > 0.005 ? [short] : []), ...wrist];
+	const roll = o.keys[near].aim && o.keys[near].roll === undefined ? "" : "; an aim key without roll takes the roll the arm holds most easily";
+	return { cause: `objects.${id}.keys[${near}] f${o.keys[near].f}`,
+		hint: `${id} at f${f}: ${why.length ? why.join(", ") : "the hand cannot hold it there"}; ${fold ? "key a pose farther from the shoulder, or turn or move the body away from it" : "key a pose nearer the hand, or bring the body to it"} (root, yaw, spine_yaw)${roll}` };
+}
+
+const r1 = v => Math.round(v * 10) / 10, r2 = v => Math.round(v * 100) / 100;
+/** observations.held units: what a row of a keyed object says. */
+export const HELD_UNITS = "held: per key, deg = the drawn +Y off the asked one (aim, or rot's +Y), cm = the drawn base off pos, got = the drawn +Y (when 1 deg off or more), rot = what an aim key used";
+
+/**
+ * Every key of every keyed carry as drawn: { <id>: [{ f, deg, cm, got?, rot? }] } in key order
+ * (frames as the spec writes them), or null when nothing is keyed.
+ */
+export function heldReadings(out) {
+	const held = keyedEntries(out.ctx.spec);
+	if (!held.length) return null;
+	return Object.fromEntries(held.map(([id, o]) => {
+		const curve = curveIn(out, id), keys = [...o.keys].sort((a, b) => a.f - b.f);
+		return [id, keys.map((k, i) => {
+			const got = rootPoseAt(out, id, Math.round(curve.t[i])), y = [got.R[0][1], got.R[1][1], got.R[2][1]];
+			const want = k.aim ? norm(k.aim) : apply(matFromQuat(curve.q[i]), [0, 1, 0]), deg = r1(angle(want, y));
+			return { f: k.f, deg, cm: r1(dist(k.pos, got.pos) * 100), ...(deg >= 1 ? { got: y.map(r2) } : {}), ...(k.aim ? { rot: curve.rots[i] } : {}) };
+		})];
+	}));
+}