cozyclay 2.1.1 → 3.0.1

package/src/motion3/qa/geometry.js

@@ -0,0 +1,77 @@
+// Collision proxies for motion QA: body capsules on Mixamo joints, scene objects as oriented
+// boxes (base pivot = bottom centre, CozyClay convention), the head as the measured ellipsoid.
+import { add, sub, scale, dot, len, apply, T, clamp } from "../compiler/math.js";
+import { bonePoint } from "../compiler/skeleton.js";
+
+// [part, from joint, to joint, radius m]. Radii are fitted to the X/Y Bot skin.
+export const CAPSULES = [
+	["torso_lo", "Spine", "Spine2", 0.12], ["torso_hi", "Spine2", "Neck", 0.105], ["hips", "LeftUpLeg", "RightUpLeg", 0.095],
+	["neck", "Neck", "Head", 0.055],
+	...["Left", "Right"].flatMap(S => {
+		const k = S === "Left" ? "l" : "r";
+		return [[`thigh_${k}`, `${S}UpLeg`, `${S}Leg`, 0.07], [`shin_${k}`, `${S}Leg`, `${S}Foot`, 0.05],
+			[`uarm_${k}`, `${S}Arm`, `${S}ForeArm`, 0.042], [`farm_${k}`, `${S}ForeArm`, `${S}Hand`, 0.033],
+			[`hand_${k}`, `${S}Hand`, `${S}HandMiddle3`, 0.022]];
+	}),
+];
+
+export const segPoints = (a, b, n = 9) => Array.from({ length: n }, (_, i) => add(a, scale(sub(b, a), i / (n - 1))));
+
+/** Signed distance from p to a box (negative inside). */
+export function sdBox(p, box) {
+	const q = apply(T(box.R), sub(p, box.pos));
+	const c = [0, box.half[1], 0];
+	const d = [Math.abs(q[0] - c[0]) - box.half[0], Math.abs(q[1] - c[1]) - box.half[1], Math.abs(q[2] - c[2]) - box.half[2]];
+	const outside = len([Math.max(d[0], 0), Math.max(d[1], 0), Math.max(d[2], 0)]);
+	return outside + Math.min(Math.max(d[0], d[1], d[2]), 0);
+}
+
+export function segDist(p1, q1, p2, q2) {
+	let best = Infinity;
+	const d2 = sub(q2, p2), dd = dot(d2, d2);
+	for (const a of segPoints(p1, q1)) {
+		const u = dd < 1e-12 ? 0 : clamp(dot(sub(a, p2), d2) / dd, 0, 1);
+		best = Math.min(best, len(sub(a, add(p2, scale(d2, u)))));
+	}
+	return best;
+}
+
+/** Depth (m) of point p inside the head ellipsoid, negative when outside. */
+export function headDepth(sk, s, p) {
+	const c = bonePoint(s, sk.index.Head, sk.landmarks.headCentre), R = s.R[sk.index.Head];
+	const q = apply(T(R), sub(p, c)), r = sk.landmarks.headRadii;
+	const v = len([q[0] / r[0], q[1] / r[1], q[2] / r[2]]);
+	return (1 - v) * Math.min(...r);
+}
+
+/** The rig's standing ankle height (m): where foot_* stands a flat foot on the floor (X Bot 0.087, Y Bot 0.105). */
+export const ankleY = sk => Math.round(sk.restWorldPos[sk.index.LeftFoot][1] * 1000) / 1000;
+
+/** A point `drop` m straight below bone b's joint at bind, carried by b (the joint itself when 0). */
+const below = (sk, s, b, drop) => (drop ? bonePoint(s, b, apply(T(sk.restWorldRot[b]), [0, -drop, 0])) : s.P[b]);
+
+/**
+ * Sole points carried by a foot, on the skin's sole (the surface verify_result's floor measure
+ * reads): heel 4.5 cm behind and 0.5 cm above the bottom of the ankle at bind; ball under the
+ * ToeBase joint at the toe pad; tip at the front edge. The rig's sole landmark says how far the
+ * skin lies below the joints (X Bot: on the ball joint; Y Bot: 3.3 cm under it).
+ */
+export function solePoints(sk, s, side) {
+	const I = sk.index, P = sk.restWorldPos, drop = sk.landmarks.sole ?? {};
+	const foot = I[`${side}Foot`], toe = I[`${side}ToeBase`], toeEnd = I[`${side}Toe_End`] ?? toe;
+	const heelRest = [P[foot][0], 0.005, P[foot][2] - 0.045];
+	const heelLocal = apply(T(sk.restWorldRot[foot]), sub(heelRest, P[foot]));
+	return { heel: bonePoint(s, foot, heelLocal), ball: below(sk, s, toe, drop.ball), tip: below(sk, s, toeEnd, drop.tip) };
+}
+
+/** Outward unit normal of a box at p (the nearest face from inside, the closest direction from outside). */
+export function boxNormal(p, box) {
+	const q = apply(T(box.R), sub(p, box.pos));
+	q[1] -= box.half[1];
+	const d = q.map((v, i) => Math.abs(v) - box.half[i]);
+	let n;
+	if (Math.max(...d) < 0) { const i = d.indexOf(Math.max(...d)); n = [0, 0, 0]; n[i] = Math.sign(q[i]) || 1; }
+	else n = q.map((v, i) => (d[i] > 0 ? Math.sign(v) * d[i] : 0));
+	const l = len(n);
+	return apply(box.R, l > 1e-12 ? scale(n, 1 / l) : [0, 1, 0]);
+}

package/src/motion3/qa/goals.js

@@ -0,0 +1,191 @@
+// Goals (C8): what the motion must achieve, measured on the compiled frames. A goal names one
+// predicate and the frames it must hold on (at: an absolute frame or [f0, f1]):
+//   near:  [a, b]  refDistance(a, b) <= tol (default 0.05 m)
+//   above: [a, b]  a.y - b.y >= by (default 0 m)
+//   moved: ref     an object's point (default its base) is at least by (default 0.05 m) from
+//                  where the scene put it; any other point ref (prop:, joint:, landmark:, anchor:)
+//                  gets at least by from where it was at at[0]: one value, its farthest frame
+//   still: ref     the point stays within tol (default 0.01 m) of the same home moved measures
+//                  from (an object: where the scene put it; any other point: where it is at at[0])
+//   speed: ref     the point's speed (central difference, m/s) is at least by (no default)
+// mode "all" (every frame of at; the default, except speed) or "any" (one frame; speed's default).
+// after / before: "<goal name>" cut at to the frames after (before) the first frame the named goal
+// holds, so an event the agent did not place on a frame can still order two goals ("the can moves
+// after the kick"). A named goal that never holds, or holds too late, leaves no frames: the goal
+// fails with value and at null and one GOAL issue (value 0.01) at at[0]; the named goal's own GOAL
+// group carries the measure. Each goal answers one result { name, kind, ok, value, at, need }: for
+// "all" the frame closest to failing (or the worst failure), for "any" the best frame. A failed goal
+// adds GOAL issues (value = the shortfall, limit 0): "all" one per failing frame, so the group's
+// count and first..last show how much of at fails and the search (search.js) sees progress; "any"
+// one, at the best frame. Issue frames index out.frames (out.f0 + i); goals[].at and every frame in
+// a message are absolute.
+import { refPoint, refDistance } from "../refs.js";
+import { partsOf } from "../object-pose.js";
+import { add, apply, len, sub } from "../compiler/math.js";
+import { m3 } from "./fmt.js";
+
+/** The goal predicates, one per goal. */
+export const GOAL_KINDS = ["near", "above", "moved", "still", "speed"];
+const DEFAULT_NEED = { near: 0.05, above: 0, moved: 0.05, still: 0.01 };
+/** Predicates met at value <= need (tol); the others are met at value >= need (by). */
+const AT_MOST = new Set(["near", "still"]);
+/** Predicates on one point ref (the others take [ref, ref]). */
+export const ONE_REF = new Set(["moved", "still", "speed"]);
+
+/** The predicates goal g names (validation wants exactly one). */
+export const goalKinds = g => GOAL_KINDS.filter(k => g?.[k] !== undefined);
+/** A goal's name: its own, else its place in spec.goals ("goals[1]", which groupKey keeps apart). */
+export const goalName = (g, i) => g.name ?? `goals[${i}]`;
+/** The bound: tol for near and still, by for above, moved and speed. */
+export const goalNeed = (g, kind) => (AT_MOST.has(kind) ? g.tol : g.by) ?? DEFAULT_NEED[kind];
+/** "all" or "any": the goal's own, else any for speed (a speed is reached) and all for the rest. */
+const goalMode = (g, kind) => g.mode ?? (kind === "speed" ? "any" : "all");
+
+/** moved and still measure the named point of an object ref (its base when none is named), any other ref as it is. */
+export const movedRef = ref => (!ref.startsWith("object:") || /\.(center|top|base)$/.test(ref) ? ref : `${ref}.base`);
+
+/** Where the scene put the point of a moved object ref: the same AABB point refs.js answers, from the scene boxes. */
+function scenePoint(scene, ref) {
+	const [, id, which] = /^object:(.+)\.(center|top|base)$/s.exec(movedRef(ref)) ?? [];
+	const boxes = partsOf(scene, id).map(p => scene.objects[p]);
+	if (!boxes.length) return null;
+	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;
+}
+
+/** The point ref of a moved or still goal. */
+const homeRef = g => g.moved ?? g.still;
+
+/** Where a moved or still goal measures from: an object's point where the scene put it, any other point where it is at `from` (default at[0]). */
+export const movedHome = (out, g, from = Array.isArray(g.at) ? g.at[0] : g.at) => (homeRef(g).startsWith("object:") ? scenePoint(out.ctx.scene, homeRef(g)) : refPoint(out, from, homeRef(g)));
+
+/** The speed of point ref at absolute frame f (m/s): central difference, one-sided at the window's edges; null when unknown. */
+function speedAt(out, ref, f) {
+	const p = refPoint(out, f, ref), fps = out.fps ?? 24;
+	if (!p) return null;
+	const a = refPoint(out, f - 1, ref), b = refPoint(out, f + 1, ref);
+	if (a && b) return (len(sub(b, a)) * fps) / 2;
+	const q = a ?? b;
+	return q ? len(sub(p, q)) * fps : null;
+}
+
+/** The measured value of goal g at absolute frame f (metres, m/s for speed), or null when a ref is unknown there. */
+function measure(out, g, kind, f, home) {
+	if (kind === "near") return refDistance(out, f, g.near[0], g.near[1]);
+	if (kind === "above") {
+		const a = refPoint(out, f, g.above[0]), b = refPoint(out, f, g.above[1]);
+		return a && b ? a[1] - b[1] : null;
+	}
+	if (kind === "speed") return speedAt(out, g.speed, f);
+	const p = home && refPoint(out, f, movedRef(homeRef(g)));
+	return p ? len(sub(p, home)) : null;
+}
+
+/** How far value v is from meeting the bound (> 0 fails). */
+const shortOf = (kind, v, need) => (AT_MOST.has(kind) ? v - need : need - v);
+const round4 = x => Math.max(1e-4, Math.round(x * 1e4) / 1e4);
+
+/** The measured frames of goal g over [a, b]: [{ f, v, short }], and the frame its point is measured from (a point's moved or still). */
+function rowsOf(X, g, kind, a, b) {
+	const need = goalNeed(g, kind), point = (kind === "moved" || kind === "still") && !homeRef(g).startsWith("object:");
+	// a point is measured from where it is at the window's first frame (outside a windowed trial compile: unknown, so nothing is measured)
+	const home = kind === "moved" || kind === "still" ? movedHome(X.out, g, a) : null, rows = [];
+	for (let f = Math.max(a, X.f0); f <= Math.min(b, X.last); f++) {
+		const v = measure(X.out, g, kind, f, home);
+		if (v !== null) rows.push({ f, v, short: shortOf(kind, v, need) });
+	}
+	return { rows, from: point ? a : undefined };
+}
+
+/**
+ * The first frame goal j holds (its own window, cut by its own after/before): a frame, null when
+ * it never holds there (or sits in an after/before loop), undefined when no frame of it is measured
+ * (a windowed trial compile that does not reach it).
+ */
+function eventOf(X, j) {
+	if (X.events.has(j)) return X.events.get(j);
+	if (X.visiting.has(j)) return null;
+	X.visiting.add(j);
+	const g = X.goals[j], kind = goalKinds(g)[0], w = kind && windowOf(X, j);
+	let e;
+	if (w && !w.wait) {
+		const { rows } = rowsOf(X, g, kind, w.a, w.b);
+		e = rows.length ? (rows.find(r => r.short <= 0)?.f ?? null) : undefined;
+	} else e = w?.wait ? null : undefined;
+	X.visiting.delete(j);
+	X.events.set(j, e);
+	return e;
+}
+
+/** The frames goal i measures: at cut by after and before ({ a, b }), or { wait } when that leaves none, or { skip } when unknown here. */
+function windowOf(X, i) {
+	const g = X.goals[i];
+	let [a, b] = Array.isArray(g.at) ? g.at : [g.at, g.at];
+	for (const side of ["after", "before"]) {
+		if (g[side] === undefined) continue;
+		const j = X.names.get(g[side]);
+		if (j === undefined || j === i) return { wait: `${side} "${g[side]}" names no other goal` };
+		const e = eventOf(X, j);
+		if (e === undefined) return { skip: true };
+		if (e === null) return { wait: `waits for "${g[side]}" (${side}), which never holds` };
+		if (side === "after") a = Math.max(a, e + 1); else b = Math.min(b, e - 1);
+		if (a > b) return { wait: `no frames left ${side} "${g[side]}" (it holds first at f${e}; at is f${Array.isArray(g.at) ? `${g.at[0]}-f${g.at[1]}` : g.at})` };
+	}
+	return { a, b };
+}
+
+function message(name, kind, row, need, any, from) {
+	const where = any ? `f${row.f}, the best of f${any[0]}-f${any[1]}` : `f${row.f}`;
+	if (kind === "near") return `${name}: ${m3(row.v)} m at ${where} (needs <= ${need})`;
+	if (kind === "above") return `${name}: ${m3(row.v)} m above at ${where} (needs >= ${need})`;
+	if (kind === "speed") return `${name}: ${m3(row.v)} m/s at ${where} (needs >= ${need})`;
+	if (kind === "still") return `${name}: ${m3(row.v)} m from ${from === undefined ? "its scene pose" : `f${from}`} at ${where} (needs <= ${need})`;
+	return `${name}: moved ${m3(row.v)} m${from === undefined ? "" : ` from f${from}`} at ${where} (needs >= ${need})`;
+}
+
+/** The frames goal i measures in compile result out (after/before applied): { a, b } | { wait } | { skip } (hints-goal.js). */
+export function goalWindow(out, goals, i) {
+	const f0 = out.f0 ?? 0, names = new Map(goals.map((g, j) => [goalName(g, j), j]));
+	return windowOf({ out, goals, names, f0, last: f0 + (out.frames?.length ?? 0) - 1, events: new Map(), visiting: new Set() }, i);
+}
+
+/**
+ * goalChecks(out, goals) -> { issues, results }
+ * @param {object} out  compileMotion result (refs.js reads it)
+ * @param {object[]} goals  spec.goals
+ * @returns {{ issues: object[], results: { name: string, kind: string, ok: boolean, value: number|null, at: number|null, need: number }[] }}
+ */
+export function goalChecks(out, goals) {
+	const issues = [], results = [], f0 = out.f0 ?? 0;
+	const X = { out, goals, names: new Map(goals.map((g, j) => [goalName(g, j), j])), f0, last: f0 + (out.frames?.length ?? 0) - 1, events: new Map(), visiting: new Set() };
+	goals.forEach((g, i) => {
+		const kind = goalKinds(g)[0];
+		if (!kind) return;
+		const name = goalName(g, i), need = goalNeed(g, kind), w = windowOf(X, i), at0 = Array.isArray(g.at) ? g.at[0] : g.at;
+		if (w.skip) return;
+		if (w.wait) {
+			results.push({ name, kind, ok: false, value: null, at: null, need });
+			if (at0 >= f0 && at0 <= X.last) issues.push({ kind: "GOAL", msg: `${name}: ${w.wait}`, frame: at0 - f0, value: 0.01, limit: 0 });
+			return;
+		}
+		let { rows, from } = rowsOf(X, g, kind, w.a, w.b);
+		// a windowed trial compile (search.js) may not reach at; those frames cannot change there
+		if (!rows.length) return;
+		// a point's moved is one value: the farthest it gets from where it was at at[0]
+		if (kind === "moved" && from !== undefined) rows = [rows.reduce((p, r) => (r.v > p.v ? r : p))];
+		const any = goalMode(g, kind) === "any", cut = Array.isArray(g.at) ? w.a !== w.b : false;
+		const pick = rows.reduce((p, r) => ((any ? r.short < p.short : r.short > p.short) ? r : p));
+		const ok = pick.short <= 0;
+		results.push({ name, kind, ok, value: m3(pick.v), at: pick.f, need });
+		if (ok) return;
+		for (const r of any ? [pick] : rows.filter(r => r.short > 0)) {
+			issues.push({ kind: "GOAL", msg: message(name, kind, r, need, any && cut ? [w.a, w.b] : null, from), frame: r.f - f0, value: round4(r.short), limit: 0 });
+		}
+	});
+	return { issues, results };
+}

package/src/motion3/qa/ground.js

@@ -0,0 +1,60 @@
+// The ground under a foot: the floor (y 0) or the top of a scene obstacle the sole stands on.
+// Every ground measurement reads sole heights from here: QA's air runs, FLOAT and balance
+// (style.js), SLIDE (checks.js), the timeline's planted runs, and the fixes that keep to QA's
+// planted definition (fix/slide.js, fix/turn.js). A foot on a box top is then on the ground as one
+// on the floor is. Session 68d305dc: a foot on a 0.7 m cube read as "no foot on the ground"
+// (FLOAT n57), and naming the cube in checks.supports did not clear it (a support rests the hips).
+// The obstacles are out.objectsAt(i): carried and follow objects are not ground, a hinge is at its
+// turned pose. GROUND (a sole under the floor) and fix.ground stay on the floor.
+import { T, apply, sub, len } from "../compiler/math.js";
+import { solePoints } from "./geometry.js";
+
+/** A top up to this far (m) above a sole point is still the ground under it: a sole sunk into a top stands on it. */
+const SINK = 0.05;
+
+const prepared = new WeakMap();
+
+/** The obstacle boxes of one frame's map, with what the vertical-line test needs. */
+function boxesOf(objs) {
+	let list = prepared.get(objs);
+	if (!list) {
+		list = Object.values(objs).filter(box => box.half && !box.ignore).map(box => {
+			const RT = T(box.R), c = [box.pos[0] + box.R[0][1] * box.half[1], box.pos[1] + box.R[1][1] * box.half[1], box.pos[2] + box.R[2][1] * box.half[1]];
+			return { RT, c, half: box.half, up: [box.R[1][0], box.R[1][1], box.R[1][2]], r: len(box.half) };
+		});
+		prepared.set(objs, list);
+	}
+	return list;
+}
+
+/** Height of the box's top on the vertical line through p (any rotation), or null when the line misses it. */
+function topOver(b, p) {
+	if (Math.hypot(p[0] - b.c[0], p[2] - b.c[2]) > b.r) return null;
+	const q = apply(b.RT, sub(p, b.c));
+	let lo = -Infinity, hi = Infinity;
+	for (let k = 0; k < 3; k++) {
+		const d = b.up[k], h = b.half[k];
+		if (Math.abs(d) < 1e-9) { if (Math.abs(q[k]) > h) return null; continue; }
+		const t1 = (-h - q[k]) / d, t2 = (h - q[k]) / d;
+		lo = Math.max(lo, Math.min(t1, t2));
+		hi = Math.min(hi, Math.max(t1, t2));
+	}
+	return lo <= hi ? p[1] + hi : null;
+}
+
+/** World height of the ground under point p at frame index i of out (out.frames[i]). */
+export function groundY(out, i, p) {
+	let g = 0;
+	for (const b of boxesOf(out.objectsAt(i))) {
+		const top = topOver(b, p);
+		if (top !== null && top <= p[1] + SINK && top > g) g = top;
+	}
+	return g;
+}
+
+/** solePoints of frame index i with y the height above the ground under each point (x, z are world). */
+export function groundSole(out, i, side) {
+	const sp = solePoints(out.ctx.sk, out.frames[i].s, side);
+	for (const key of ["heel", "ball", "tip"]) sp[key] = [sp[key][0], sp[key][1] - groundY(out, i, sp[key]), sp[key][2]];
+	return sp;
+}

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

@@ -0,0 +1,195 @@
+// Hints for contact-type issues: a body part inside a box, the floor, the head, the torso or the
+// other limb. Each answers a world move (direction x amount) for whatever drives that part.
+import { add, sub, scale, norm, dot, len, clamp, apply, ry, T } from "../compiler/math.js";
+import { bonePoint } from "../compiler/skeleton.js";
+import { CAPSULES, segPoints, sdBox, boxNormal, headDepth, segDist, solePoints, ankleY } from "./geometry.js";
+import { vec, m3 } from "./fmt.js";
+import { kneeFoldHint, kneeWhy } from "./hints-knee.js";
+import { objectFrame } from "../compiler/anchors.js";
+import { bodyFor, bodyNormal, limbDepth } from "../body.js";
+import { footProbes, footDepths } from "./foot-checks.js";
+import { personCapsules } from "./people-checks.js";
+
+const MARGIN = 0.003;
+/** The most a foot hint lifts a foot over a body it went into through a side (a stair riser); higher, it backs out. */
+const LIFT_MAX = 0.25;
+const sideOf = name => (/(^|_)l$|^Left/.test(name) ? "l" : /(^|_)r$|^Right/.test(name) ? "r" : null);
+
+/** fix (qa/patch.js) moving anchor `name` of hand k by a world delta at f: its own point, in the frame that point is written in. */
+function anchorFix(X, name, f, delta, k) {
+	const a = X.spec.anchors?.[name], path = field => `/anchors/${name}/${field}`;
+	if (a?.kind === "world") return { path: path("p"), delta };
+	if (a?.kind === "body") return { path: path("p"), delta: apply(ry(-(X.fr(f).c.yaw ?? 0)), delta) };
+	if (["bone", "segment", "prop", "person"].includes(a?.kind)) return { path: path("offset"), delta };
+	if (a?.kind !== "object") return undefined;
+	// local is in the object's axes where that hand's target read it (anchors.js objectFrame)
+	const fr = X.fr(f), o = objectFrame(X.out.ctx, a, name, { ...fr, diag: { ...fr.diag, frame: f } }, k);
+	return { path: path("local"), delta: apply(T(o.R), delta) };
+}
+
+/** cause + hint (+ fix, qa/patch.js) for moving a body part (capsule name, prop_<name>, hand_<k>) by `delta` at frame f. */
+export function moveHint(X, part, f, delta, why = "") {
+	const prop = /^prop_(.+)$/.exec(part);
+	const k = prop ? X.spec.props?.[prop[1]]?.hand : sideOf(part);
+	let label, cause, fix, shown = delta;
+	if (/^(hand|farm|uarm)_/.test(part) || prop) {
+		const d = X.hand(k, f);
+		label = d.label;
+		fix = d.anchor ? anchorFix(X, d.anchor, f, delta, k) : d.ch === `hand_${k}` ? { channel: d.ch, f, delta } : undefined;
+		// an object anchor moves its point on the object (local, in the object's axes), never the object
+		const on = d.anchor && X.spec.anchors[d.anchor]?.kind === "object" ? X.spec.anchors[d.anchor].object : null;
+		if (on && fix) { label = `anchors.${d.anchor}.local (a point on ${on}, in ${on}'s axes; ${on} stays)`; shown = fix.delta; }
+		cause = d.anchor ? `anchor ${d.anchor}${d.fit !== null ? ` (fits[${d.fit}])` : ""} via ${X.cause(d.ch, f)}` : X.cause(d.ch, f);
+	} else if (/^(shin|foot|sole)_/.test(part)) { label = `foot_${k}`; cause = X.cause(label, f); fix = { channel: label, f, delta }; }
+	// a body held since its key (it breathes and sways there, compiler/idle.js): move what placed it (patch.js hold)
+	else { label = "root"; cause = X.cause("root", f); fix = { channel: "root", f, delta, ...(/^root held since /.test(cause) ? { hold: true } : {}) }; }
+	// a key the walk generator wrote: the agent changes the walk, not the key
+	const walk = / (walk|walkTo) /.test(` ${cause}`) && /step|start|end/.test(cause);
+	if (walk && !/^anchor/.test(label)) return { cause, hint: `walk path: ${label} needs ${vec(delta)} m at f${f}${why}; change that walk's heading/turnDistance/step (or give one a { range: [lo, hi] })` };
+	return { cause, hint: `${label}: move ${vec(shown)} m at f${f}${why}`, fix };
+}
+
+const capsule = name => CAPSULES.find(c => c[0] === name);
+
+/** Deepest point of a capsule in a box at frame f and the box's outward normal there. */
+function deepest(X, f, part, box) {
+	const [, a, b] = capsule(part), { s } = X.fr(f);
+	const pts = segPoints(s.P[X.I[a]], s.P[X.I[b]]), ds = pts.map(p => sdBox(p, box)), m = Math.min(...ds);
+	return { p: pts[ds.indexOf(m)], n: boxNormal(pts[ds.indexOf(m)], box), d: m };
+}
+
+function boxHint(X, g, part, id, need) {
+	const f = g.worstFrame, box = X.out.objectsAt(X.rel(f))[id];
+	if (!box || !capsule(part)) return null;
+	const { n } = deepest(X, f, part, box);
+	return moveHint(X, part, f, scale(n, need), ` (out of ${id})`);
+}
+
+/**
+ * A foot in a box (foot-checks.js): through a side face (a toe swung into a stair's riser) the foot rises over the
+ * box's top by what its deepest probe lacks, with the way straight out of that side as the other choice; through
+ * the top face (a sole sunk in a step) it comes out along that face.
+ */
+function footHint(X, g, part, id) {
+	const f = g.worstFrame, box = X.out.objectsAt(X.rel(f))[id];
+	if (!box) return null;
+	const probes = footProbes(X.sk, X.fr(f).s, part.endsWith("_l") ? "Left" : "Right"), d = footDepths(probes, box), need = g.worst - g.limit + MARGIN;
+	if (!(d.side > 0)) return d.topAt ? moveHint(X, part, f, scale(boxNormal(d.topAt, box), need), ` (out of ${id}'s top)`) : null;
+	const under = p => 2 * box.half[1] - apply(T(box.R), sub(p, box.pos))[1];
+	const rise = Math.max(...probes.filter(p => sdBox(p, box) < 0).map(under)) + MARGIN, out = scale(boxNormal(d.sideAt, box), need);
+	// a step's riser is cleared by lifting the swing; a panel the foot kicks or a wall is left the way the foot came
+	if (rise > LIFT_MAX) return moveHint(X, part, f, out, ` (out of ${id}'s side)`);
+	const r = moveHint(X, part, f, apply(box.R, [0, rise, 0]), ` (over ${id}'s top; its ${g.worst.toFixed(3)} m is through a side)`);
+	r.hint += /^walk path/.test(r.hint) ? "; a higher lift raises the swing" : `; or move ${vec(out)} m out of that side`;
+	return r;
+}
+
+function towardFrom(X, g, part, from, need, what) {
+	return moveHint(X, part, g.worstFrame, scale(norm(from), need), ` (away from the ${what})`);
+}
+
+/** Probe points of a hand or prop at frame f (as the FACE/BODY checks probe them). */
+function probes(X, f, nm) {
+	const { s, diag } = X.fr(f), I = X.I;
+	if (nm.startsWith("hand_")) { const S = nm.endsWith("l") ? "Left" : "Right"; return segPoints(s.P[I[`${S}Hand`]], s.P[I[`${S}HandMiddle3`]], 5); }
+	return Object.entries(diag.props?.[nm.slice(5)] ?? {}).filter(([k, p]) => Array.isArray(p) && k !== "origin").map(([, p]) => p);
+}
+
+export const contactHints = {
+	COLLIDE(X, g) {
+		const [, part, id] = /^(\S+) x (.+)$/.exec(g.subject) ?? [];
+		if (/^foot_[lr]$/.test(part ?? "")) return footHint(X, g, part, id);
+		const r = boxHint(X, g, part, id, g.worst - g.limit + MARGIN);
+		if (r && /^(hand|farm)_/.test(part) && !X.spec.fix?.penetration && g.worst - g.limit <= 0.05) {
+			r.hint += "; or fix.penetration: 0.02 pushes shallow hand hits out";
+			if (X.spec.fix !== false) r.fix = { path: "/fix/penetration", value: 0.02 };
+		}
+		return r;
+	},
+	/** PERSON "<part> x person:<id>": the part moves out of the other person's deepest capsule, along the line between their nearest points. */
+	PERSON(X, g) {
+		const [, part, id] = /^(\S+) x person:(.+)$/.exec(g.subject) ?? [], mine = capsule(part), p0 = X.out?.ctx?.scene?.people?.[id];
+		if (!mine || !p0) return null;
+		const f = g.worstFrame, { s } = X.fr(f), pts = segPoints(s.P[X.I[mine[1]]], s.P[X.I[mine[2]]]);
+		const near = ([other, C, D, q]) => {
+			const cd = sub(D, C), dd = Math.max(dot(cd, cd), 1e-12);
+			return pts.map(p => { const at = add(C, scale(cd, clamp(dot(sub(p, C), cd) / dd, 0, 1))); return { other, p, q: at, depth: mine[3] + q - len(sub(p, at)) }; })
+				.reduce((m, x) => (x.depth > m.depth ? x : m));
+		};
+		const hit = personCapsules(p0, f).map(near).reduce((m, x) => (x.depth > m.depth ? x : m));
+		const away = len(sub(hit.p, hit.q)) > 1e-6 ? norm(sub(hit.p, hit.q)) : norm([hit.p[0] - hit.q[0] || 1, 0, hit.p[2] - hit.q[2]]);
+		const r = moveHint(X, part, f, scale(away, g.worst - g.limit + MARGIN), ` (out of ${p0.name}'s ${hit.other})`);
+		return { ...r, hint: `${r.hint}; or, for a touch you mean, checks.allow [{ part: "${part}", object: "person:${id}", depth: ${m3(g.worst + MARGIN)} }]` };
+	},
+	CLEARANCE(X, g) {
+		const k = (X.spec.checks?.clearance ?? []).find(c => g.subject.startsWith(`${c.name}:`));
+		return k && boxHint(X, g, k.part, k.object, k.min - g.worst + MARGIN);
+	},
+	GROUND(X, g) {
+		const k = g.subject.startsWith("Left") ? "l" : "r", f = g.worstFrame, c = X.fr(f).c, fold = X.fr(f).diag[`leg_fold_${k}`];
+		// the knee on its stop left the ankle under its target (compiler/limbs.js): raising the foot folds it further, the root comes up
+		if (fold) return kneeFoldHint(X, k, f, kneeWhy("the sole is in the floor because the knee is on its stop: ", fold), c[`foot_${k}`]);
+		const pitch = c[`fpitch_${k}`] ? `, or less fpitch_${k} (now ${m3(c[`fpitch_${k}`])} deg; + lifts the heel)` : "";
+		return { cause: X.cause(`foot_${k}`, f), hint: `foot_${k}: raise ${m3(g.worst + 0.001)} m at f${f} (foot_* is the ankle; it stands ${ankleY(X.sk)} m above the floor)${pitch}`,
+			fix: { channel: `foot_${k}`, f, delta: [0, g.worst + 0.001, 0] } };
+	},
+	FACE(X, g) {
+		const nm = g.subject.replace(/ into head$/, ""), f = g.worstFrame, { s } = X.fr(f);
+		const c = bonePoint(s, X.I.Head, X.sk.landmarks.headCentre);
+		const p = probes(X, f, nm).reduce((best, q) => (headDepth(X.sk, s, q) > headDepth(X.sk, s, best) ? q : best));
+		return towardFrom(X, g, nm, sub(p, c), g.worst - g.limit + MARGIN, "head");
+	},
+	BODY(X, g) {
+		const [, nm, part] = /^(\S+) into (\S+)$/.exec(g.subject) ?? [];
+		const cap = capsule(part), f = g.worstFrame, { s } = X.fr(f);
+		// an arm on the fitted skin (body-checks.js): the hand target moves out along the skin where it goes deepest;
+		// an upper arm or forearm says so, since turning its elbow (elbow_<k>) away from the body may do instead
+		const limb = /^(hand|farm|uarm)_([lr])$/.exec(nm ?? ""), body = limb && bodyFor(X.sk);
+		if (body) {
+			const bone = X.I[`${limb[2] === "l" ? "Left" : "Right"}${{ hand: "Hand", farm: "ForeArm", uarm: "Arm" }[limb[1]]}`], hit = limbDepth(body, X.sk, s, bone);
+			const out = hit.p && bodyNormal(body, s, hit.p, body.skip.get(bone));
+			if (out) {
+				const r = moveHint(X, nm, f, scale(out, g.worst - g.limit + MARGIN), ` (out of the ${part})`);
+				if (limb[1] !== "hand") r.hint += `; or turn elbow_${limb[2]} away from the ${part}`;
+				return r;
+			}
+		}
+		if (!cap) return null;
+		const A = s.P[X.I[cap[1]]], B = s.P[X.I[cap[2]]], ab = sub(B, A);
+		const axis = p => add(A, scale(ab, clamp(dot(sub(p, A), ab) / dot(ab, ab), 0, 1)));
+		const p = probes(X, f, nm).reduce((best, q) => (len(sub(q, axis(q))) < len(sub(best, axis(best))) ? q : best));
+		return towardFrom(X, g, nm, sub(p, axis(p)), g.worst - g.limit + MARGIN, "torso");
+	},
+	SELF(X, g) {
+		const f = g.worstFrame, { s } = X.fr(f), P = s.P, I = X.I;
+		if (g.subject === "hands overlap") {
+			const d = norm(sub(P[I.LeftHand], P[I.RightHand])), need = (g.worst - g.limit + MARGIN) / 2;
+			const r = moveHint(X, "hand_l", f, scale(d, need));
+			return { cause: r.cause, hint: `${r.hint}; and ${moveHint(X, "hand_r", f, scale(d, -need)).hint}`, fix: moveHint(X, "hand_l", f, scale(d, 2 * need)).fix };
+		}
+		const shins = g.subject === "shins touch", min = shins ? 0.1 : 0.135;
+		const [a, b] = shins ? ["Leg", "Foot"] : ["UpLeg", "Leg"];
+		const gap = segDist(P[I[`Left${a}`]], P[I[`Left${b}`]], P[I[`Right${a}`]], P[I[`Right${b}`]]);
+		const d = sub(P[I[`Left${b}`]], P[I[`Right${b}`]]); d[1] = 0;
+		const need = (min - gap + MARGIN) / 2, dir = norm(d);
+		return { cause: X.cause("foot_l", f), hint: `foot_l: move ${vec(scale(dir, need))} m and foot_r ${vec(scale(dir, -need))} m at f${f} (${shins ? "shins" : "thighs"} ${m3(gap)} m apart, need ${min}); or spread knee_l/knee_r`,
+			fix: { channel: "foot_l", f, delta: scale(dir, 2 * need) } };
+	},
+	OBJECT(X, g) {
+		const [, id, oid] = /^(\S+) into (.+)$/.exec(g.subject) ?? [];
+		const ch = X.spec.objects?.[id]?.channel;
+		if (!ch) return null;
+		const at = f => X.out.baked[ch]?.[f] ?? 0, clean = g.first > 0 ? at(g.first - 1) : at(0);
+		return { cause: X.cause(ch, g.worstFrame), hint: `${ch}: keep it within ${m3(clean)} deg (it reaches ${m3(at(g.worstFrame))} at f${g.worstFrame}, ${m3(g.worst)} m into ${oid}), or move ${oid}`,
+			fix: { channel: ch, f: g.worstFrame, value: clean } };
+	},
+	BALANCE(X, g) {
+		const f = g.worstFrame, { s } = X.fr(f), P = s.P, I = X.I;
+		if (g.subject === "no foot on the ground") return { cause: X.cause("root", f), hint: `at f${f} lower foot_l or foot_r onto the ground, the floor or the top of an object under it (the ankle stands ${ankleY(X.sk)} m above it), or declare checks.supports for the seat the hips rest on` };
+		const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, P[I[j]]), [0, 0, 0]), 0.25);
+		const feet = ["Left", "Right"].flatMap(S => Object.values(solePoints(X.sk, s, S)));
+		const xs = feet.map(p => p[0]), zs = feet.map(p => p[2]), mg = 0.08 - 0.01;
+		const to = [clamp(com[0], Math.min(...xs) - mg, Math.max(...xs) + mg), com[1], clamp(com[2], Math.min(...zs) - mg, Math.max(...zs) + mg)];
+		return { cause: X.cause("root", f), hint: `root: move ${vec(sub(to, com))} m at f${f} (centre of mass over the feet), or step a foot under it`, fix: { channel: "root", f, delta: sub(to, com) } };
+	},
+};