cozyclay 2.1.0 → 3.0.0

package/src/motion3/pipeline.js

@@ -0,0 +1,102 @@
+// One compile as motion.compile runs it: frames "auto" resolves (skills/frames-auto.js), open
+// parameters are searched (search.js), unnamed checks get their index as a name (on a copy,
+// qa/check-names.js), skills expand (skills/), the spec is validated strictly (leniently for a
+// saved take compiled again), the compiler bakes and auto-fixes the frames, QA measures them with
+// a cause and a hint per issue group against the agent's own spec, the style quantities are
+// measured (qa/style.js observeMotion; keyed objects: every key as drawn, qa/key-checks.js
+// heldReadings; each hand and foot against the nearest object, qa/near.js observeNear; each holding
+// wrist's bend, qa/wrist-obs.js observeWrist; a skill
+// paced to fit a short span: observations.paced; a skill whose release or
+// settle the last frame cut: observations.cut), and the timeline and the
+// requested probes read the result.
+// liftRequest first takes what the agent obviously meant: spec.probes are request probes, and a
+// bare goals[].moved id is object:<id>; relaxSpec (lenient.js) fixes mechanical slips in the expanded
+// spec before validation and the answer lists each fix in notes.
+import { compileMotion } from "./compiler/compile.js";
+import { validateSpec } from "./compiler/validate.js";
+import { runMotionQa } from "./qa/index.js";
+import { observeMotion } from "./qa/style.js";
+import { nameChecks } from "./qa/check-names.js";
+import { expandUse } from "./skills/index.js";
+import { resolveFrames } from "./skills/frames-auto.js";
+import { markFramesAuto } from "./spec-store.js";
+import { findParams, searchParams } from "./search.js";
+import { timelineOf } from "./timeline.js";
+import { runProbes } from "./probes.js";
+import { canonicalGoals } from "./compiler/validate-goals.js";
+import { heldReadings, HELD_UNITS } from "./qa/key-checks.js";
+import { observeNear, NEAR_UNITS } from "./qa/near.js";
+import { observeWrist, WRIST_UNITS } from "./qa/wrist-obs.js";
+import { planWalks, applyWalkPlans } from "./walk-plan.js";
+import { relaxSpec } from "./lenient.js";
+
+const ms = t => Math.round(performance.now() - t);
+
+/** A spec after retime: frame-range checks follow the keys they were written against. */
+function warpChecks(spec, map) {
+	const c = structuredClone(spec.checks ?? {}), w = r => (Array.isArray(r) ? [Math.round(map(r[0])), Math.round(map(r[1]))] : r);
+	for (const name of ["contacts", "orient", "below"]) for (const k of c[name] ?? []) k.when = w(k.when);
+	for (const k of c.clearance ?? []) k.frames = w(k.frames);
+	return { ...spec, checks: c };
+}
+
+/**
+ * liftRequest(spec, probes) -> { spec, probes }. spec.probes (sent inside the spec, or added by
+ * a patch) join the request's probes after them and leave the spec, so they are never stored and
+ * never change its specId; bare goals[].moved ids get their object: prefix (validate-goals.js).
+ * The spec comes back as the same object when nothing changes.
+ */
+export function liftRequest(spec, probes) {
+	if (!spec || typeof spec !== "object" || Array.isArray(spec)) return { spec, probes };
+	const goals = canonicalGoals(spec.goals);
+	if (spec.probes === undefined && goals === spec.goals) return { spec, probes };
+	const { probes: inSpec, ...rest } = spec;
+	const lifted = inSpec === undefined ? probes : probes ? [...probes, ...(Array.isArray(inSpec) ? inSpec : [inSpec])] : inSpec;
+	return { spec: goals === spec.goals ? rest : { ...rest, goals }, probes: lifted };
+}
+
+/**
+ * spec -> { out, qa, observations, spec (frames and open values filled in), expanded, used,
+ * fixed, search, timeline, probes?, notes?, ms }. opts.checks replaces every check (the spec's and its skills') for a
+ * re-measure; opts.lenient ignores unknown fields (take-source.js); opts.probes are measured
+ * (with spec.probes, liftRequest).
+ */
+export function compileSpec(sent, { sk, scene }, opts = {}) {
+	const { spec, probes: asked } = liftRequest(sent, opts.probes);
+	const t0 = performance.now(), ctx = { sk, scene, lenient: opts.lenient === true }, notes = [];
+	const checks = opts.checks && nameChecks({ checks: opts.checks }).checks;
+	let plans = [];
+	const expand = s => {
+		const { spec: exp, used } = expandUse(nameChecks(applyWalkPlans(s, plans)), ctx);
+		// plain JSON objects compile about twice as fast as structuredClone'd ones (V8 shapes)
+		const full = relaxSpec(JSON.parse(JSON.stringify(checks ? { ...exp, checks } : exp)), scene, notes);
+		validateSpec(full, ctx);
+		return { full, used };
+	};
+	// a walkTo with arrive gets its cadence planned on probe compiles of the walk alone (walk-plan.js); the spec keeps arrive
+	plans = planWalks(spec, { sk, scene, trial: s => { const full = expand(s).full; return runMotionQa(sk, compileMotion({ fps: 24, ...full }, ctx), full, { explain: false }); } });
+	const framed = spec?.frames === "auto" && plans.length ? { ...spec, frames: resolveFrames(applyWalkPlans(spec, plans), ctx).frames } : resolveFrames(spec, ctx), params = findParams(framed);
+	let resolved = framed, search = null;
+	if (params.length) ({ spec: resolved, search } = searchParams(framed, params, ctx, s => expand(s).full));
+	// the store keeps the "auto" intent beside the resolved number (spec-store.js)
+	if (spec?.frames === "auto") markFramesAuto(resolved);
+	const t1 = performance.now();
+	const { full: expanded, used } = expand(resolved);
+	const out = compileMotion({ fps: 24, ...expanded }, ctx);
+	const compileMs = ms(t1), t2 = performance.now();
+	const measured = out.timeMap ? warpChecks(expanded, out.timeMap) : expanded;
+	const qa = runMotionQa(sk, out, measured, { userSpec: resolved }), observations = observeMotion(sk, out, measured.checks), held = heldReadings(out);
+	if (held) Object.assign(observations, { units: `${observations.units}; ${HELD_UNITS}`, held });
+	const near = observeNear(sk, out), wrist = observeWrist(sk, out);
+	if (near) Object.assign(observations, { units: `${observations.units}; ${NEAR_UNITS}`, near });
+	if (wrist) Object.assign(observations, { units: `${observations.units}; ${WRIST_UNITS}`, wrist });
+	// a skill that paced its beats to fit a short span says so where every answer keeps it (C7 tier 1)
+	const paced = used.filter(u => u.paced).map(u => `${u.skill} paced ${u.paced.toFixed(2)} to fit f${u.f0}..f${u.end}`);
+	if (paced.length) observations.paced = paced;
+	const cut = used.filter(u => u.cut).map(u => `${u.skill}: ${u.cut}`);
+	if (cut.length) observations.cut = cut;
+	if (plans.length) observations.planned = plans.map(p => p.note);
+	const timeline = timelineOf(out, { used, spec: expanded }), probes = asked && runProbes(out, asked, { spec: expanded, sk, scene, notes });
+	return { out, qa, observations, spec: resolved, expanded, used, fixed: out.fixed, search, timeline, ...(probes ? { probes } : {}), ...(notes.length ? { notes } : {}),
+		ms: { compile: compileMs, qa: ms(t2), total: ms(t0) } };
+}

package/src/motion3/playback.js

@@ -0,0 +1,51 @@
+// Play a take v3 on a live rig: local quaternions straight onto the Mixamo control bones
+// (first depth-first bone of each name; the nested identity "skinned" copies are never
+// written) and the hips position in rig space. The rig root carries the character's
+// placement and the 0.01 centimetre scale, so metres become centimetres here.
+import { normalizeBoneName } from "../poses.js";
+
+const CM_PER_M = 100;
+const resolved = new WeakMap();
+
+function controlBones(rig, names) {
+	let entry = resolved.get(rig);
+	if (entry && entry.key === names.join()) return entry;
+	const first = new Map();
+	rig.traverse(o => {
+		if (!o.isBone) return;
+		const n = normalizeBoneName(o.name);
+		if (!first.has(n)) first.set(n, o);
+	});
+	const bones = names.map(name => {
+		const target = normalizeBoneName(name);
+		for (const [n, bone] of first) if (n === target || n.endsWith(target)) return bone;
+		return null;
+	});
+	// Bind translations: a take never moves a bone except the hips, so every other bone goes
+	// back to its bind position (another player may have stretched it).
+	const binds = rig.userData?.poseBind;
+	const bindPos = bones.map(b => {
+		const p = b && binds?.get(b)?.position;
+		return b ? (p ? [p.x, p.y, p.z] : b.position.toArray()) : null;
+	});
+	entry = { key: names.join(), bones, bindPos, hips: names.indexOf("Hips") };
+	resolved.set(rig, entry);
+	return entry;
+}
+
+export const isTakeV3 = motion => motion?.schema === "cozyclay.take.v3";
+
+export function applyTakeFrame(rig, take, frame) {
+	if (!rig || !take) return;
+	const { bones, bindPos, hips } = controlBones(rig, take.bones);
+	const f = Math.max(0, Math.min(take.frameCount - 1, Math.round(frame) || 0)), B = take.bones.length;
+	for (let b = 0; b < B; b++) {
+		const bone = bones[b];
+		if (!bone) continue;
+		const i = (f * B + b) * 4;
+		bone.quaternion.set(take.rot[i], take.rot[i + 1], take.rot[i + 2], take.rot[i + 3]);
+		if (b === hips) bone.position.set(take.hips[f * 3] * CM_PER_M, take.hips[f * 3 + 1] * CM_PER_M, take.hips[f * 3 + 2] * CM_PER_M);
+		else bone.position.set(bindPos[b][0], bindPos[b][1], bindPos[b][2]);
+	}
+	rig.updateMatrixWorld(true);
+}

package/src/motion3/probes.js

@@ -0,0 +1,91 @@
+// C5. Probes: measurements the agent asks for on this compile (motion.compile { probes }),
+// whether or not it installs. At most 16 probes; each is checked first (schema/fields.js
+// PROBE_FIELDS, refs.js checkRef with the full grammar) and every problem is thrown at once as
+// MOTION_SPEC_INVALID, one per line, e.g.
+//   probes[0].distance[0] "joint:LeftHnad": unknown bone; did you mean "LeftHand"?
+// Bone names may be loose ("hips", "hand_l", bones.js resolveBone); they are turned into the
+// rig's names before measuring. Answers per name (a probe without a name is "probes[i]"):
+//   distance [a, b]  { min, minAt, max, maxAt, mean, first, last }   (refs.js refDistance; metres
+//                    to 6 decimals; every `every` frames, default 1; null when no frame has a value)
+//   position ref     { at: [{ f, p: [x,y,z] }] }                      (metres to 4 decimals; at most 16
+//                    rows; every defaults to the step that fits the range in 16 rows, a smaller one grows to it)
+// frames: [f0, f1] absolute and inclusive, or one frame (default the whole take); a window partly past
+// the take is cut to it. Both fixes leave a note in ctx.notes (lenient.js; output.adjusted).
+import { PROBE_FIELDS } from "./schema/fields.js";
+import { checkRef, refPoint, refDistance } from "./refs.js";
+import { resolveBone } from "./bones.js";
+import { didYouMean, fmt } from "./compiler/vocab.js";
+import { clampProbe, fitEvery } from "./lenient.js";
+
+const MAX_PROBES = 16, MAX_ROWS = 16, MAX_ERRORS = 12, SHAPE = "{ name, distance: [refA, refB] | position: ref, frames: [f0, f1], every }";
+const r6 = v => Math.round(v * 1e6) / 1e6, r4 = v => Math.round(v * 1e4) / 1e4;
+
+/** joint:/bone: refs with the rig's own bone name ("joint:hips" -> "joint:Hips"). */
+function exactRef(sk, ref) {
+	const m = /^(joint|bone):(.+)$/s.exec(ref);
+	return m ? `${m[1]}:${resolveBone(sk, m[2]).bone ?? m[2]}` : ref;
+}
+
+function rangeOf(p, at, last, err, notes) {
+	const fr = p.frames === undefined ? [0, last] : clampProbe(p.frames, last, at, notes);
+	if (!fr) err(`${at}.frames must be [f0, f1], integer frames within 0..${last} with f0 <= f1, got ${fmt(p.frames)}`);
+	return fr;
+}
+
+/** Checked probes [{ name, refs, kind, range, every }]; throws MOTION_SPEC_INVALID listing every problem. */
+function checkProbes(out, probes, { spec, sk, scene, notes }) {
+	const errors = [], err = m => { if (errors.length < MAX_ERRORS) errors.push(m); }, last = out.frameCount - 1, list = [], names = new Map();
+	if (!Array.isArray(probes)) err(`probes must be an array of ${SHAPE}`);
+	else if (probes.length > MAX_PROBES) err(`probes has ${probes.length} entries; at most ${MAX_PROBES} per compile`);
+	else probes.forEach((p, i) => {
+		const at = `probes[${i}]`;
+		if (!p || typeof p !== "object" || Array.isArray(p)) return err(`${at} must be ${SHAPE}`);
+		for (const k of Object.keys(p)) if (!PROBE_FIELDS.includes(k)) err(`${at} has unknown field "${k}"${didYouMean(k, PROBE_FIELDS)}; a probe is ${SHAPE}`);
+		const name = p.name ?? at;
+		if (typeof name !== "string" || !name) err(`${at}.name must be a non-empty string, got ${fmt(p.name)}`);
+		else if (names.has(name)) err(`${at}.name "${name}" is already used by ${names.get(name)}; probe names must differ`);
+		else names.set(name, at);
+		if ((p.distance === undefined) === (p.position === undefined)) return err(`${at} needs exactly one of distance: [refA, refB] or position: ref`);
+		const kind = p.distance !== undefined ? "distance" : "position";
+		const refs = kind === "distance" ? p.distance : [p.position];
+		if (kind === "distance" && !(Array.isArray(refs) && refs.length === 2 && refs.every(r => typeof r === "string"))) return err(`${at}.distance must be [refA, refB], two point refs, got ${fmt(p.distance)}`);
+		if (kind === "position" && typeof p.position !== "string") return err(`${at}.position must be a point ref, got ${fmt(p.position)}`);
+		const good = refs.map((r, j) => checkRef(spec, err, { sk, scene }, kind === "distance" ? `${at}.distance[${j}]` : `${at}.position`, r)).every(Boolean);
+		const range = rangeOf(p, at, last, err, notes);
+		if (p.every !== undefined && !(Number.isInteger(p.every) && p.every >= 1)) return err(`${at}.every must be a positive integer, got ${fmt(p.every)}`);
+		if (!good || !range) return;
+		const span = range[1] - range[0] + 1, asked = p.every ?? (kind === "position" ? Math.ceil(span / MAX_ROWS) : 1);
+		const every = kind === "position" ? fitEvery(asked, span, MAX_ROWS, at, notes) : asked;
+		list.push({ name, kind, refs: refs.map(r => exactRef(sk, r)), range, every });
+	});
+	if (errors.length) throw new Error(`MOTION_SPEC_INVALID: ${errors.join("\n")}${errors.length >= MAX_ERRORS ? "\n(more problems not listed)" : ""}`);
+	return list;
+}
+
+function frameList([f0, f1], every) {
+	const out = [];
+	for (let f = f0; f <= f1; f += every) out.push(f);
+	return out;
+}
+
+function distanceOf(out, p) {
+	const vals = frameList(p.range, p.every).map(f => [f, refDistance(out, f, p.refs[0], p.refs[1])]).filter(([, v]) => Number.isFinite(v));
+	if (!vals.length) return { min: null, minAt: null, max: null, maxAt: null, mean: null, first: null, last: null };
+	let lo = vals[0], hi = vals[0], sum = 0;
+	for (const fv of vals) { if (fv[1] < lo[1]) lo = fv; if (fv[1] > hi[1]) hi = fv; sum += fv[1]; }
+	return { min: r6(lo[1]), minAt: lo[0], max: r6(hi[1]), maxAt: hi[0], mean: r6(sum / vals.length), first: r6(vals[0][1]), last: r6(vals[vals.length - 1][1]) };
+}
+
+function positionOf(out, p) {
+	return { at: frameList(p.range, p.every).map(f => { const q = refPoint(out, f, p.refs[0]); return { f, p: q ? q.map(r4) : null }; }) };
+}
+
+/**
+ * runProbes(out, probes, { spec, sk, scene }) -> { [name]: result }
+ * @param {object} out  compileMotion result
+ * @param {object[]} probes  the request's probes
+ * @param {{ spec: object, sk: object, scene: object, notes?: string[] }} ctx  spec = the expanded spec; notes gets the windows cut and every grown
+ */
+export function runProbes(out, probes, ctx) {
+	return Object.fromEntries(checkProbes(out, probes, ctx).map(p => [p.name, p.kind === "distance" ? distanceOf(out, p) : positionOf(out, p)]));
+}

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

@@ -0,0 +1,34 @@
+// BODY on the fitted skin (src/motion3/body.js): an upper arm, forearm or hand going into any other
+// part of the body (torso, hips, head, legs, the other arm) more than L.skin. Each limb probes as
+// spheres on its bone; the body answers from its signed distance grids. The parts are named as the
+// capsules were (qa/geometry.js CAPSULES), so "hand_r into torso_hi" reads the same as before; a
+// spec's checks.allow { part, object: <part>, depth } lets a declared contact touch deeper.
+import { bodyFor, limbDepth } from "../body.js";
+
+const REGIONS = [
+	[/^Hips$/, "hips"], [/^(Spine|Spine1)$/, "torso_lo"], [/^Spine2$/, "torso_hi"], [/^Neck$/, "neck"], [/^Head/, "head"],
+	[/Shoulder$/, "shoulder"], [/UpLeg$/, "thigh"], [/Leg$/, "shin"], [/(Foot|Toe)/, "foot"], [/ForeArm$/, "farm"], [/Arm$/, "uarm"], [/Hand$/, "hand"],
+];
+/** The QA part name of bone b ("thigh_l", "torso_hi", ...). */
+export function regionOf(sk, b) {
+	const name = sk.names[b] ?? "", side = /^Left/.test(name) ? "_l" : /^Right/.test(name) ? "_r" : "";
+	const hit = REGIONS.find(([re]) => re.test(name));
+	return hit ? `${hit[1]}${side}` : name;
+}
+
+export const ARM_BONES = ["Arm", "ForeArm", "Hand"].flatMap(n => [`Left${n}`, `Right${n}`]);
+
+/** L: limits { skin } (m); push(kind, msg, frame, value, limit); allowed(part, into): a declared depth or null. */
+export function bodyChecks(sk, out, L, push, allowed) {
+	const body = bodyFor(sk);
+	if (!body) return;
+	const limbs = ARM_BONES.map(n => sk.index[n]);
+	out.frames.forEach(({ s }, f) => {
+		for (const b of limbs) {
+			const hit = limbDepth(body, sk, s, b);
+			if (hit.into < 0) continue;
+			const part = regionOf(sk, b), into = regionOf(sk, hit.into), lim = Math.max(allowed(part, into) ?? 0, L.skin);
+			if (hit.depth > lim) push("BODY", `${part} into ${into}`, f, hit.depth, lim);
+		}
+	});
+}

package/src/motion3/qa/check-names.js

@@ -0,0 +1,14 @@
+// Unnamed checks get a name from their place in the agent's own spec ("contacts[0]"), so their
+// QA groups say which check failed and two unnamed checks stay two groups (severity.js groupKey
+// keeps a bracketed index). Runs on a copy before the skills expand, so skill checks keep theirs.
+
+const NAMED = ["contacts", "orient", "below", "clearance", "appear"];
+
+/** spec -> a copy whose unnamed spec.checks entries are named "<list>[<index>]" (spec when none are). */
+export function nameChecks(spec) {
+	const c = spec?.checks;
+	if (!c || typeof c !== "object" || !NAMED.some(k => Array.isArray(c[k]) && c[k].some(e => e && typeof e === "object" && e.name === undefined))) return spec;
+	const checks = { ...c };
+	for (const k of NAMED) if (Array.isArray(c[k])) checks[k] = c[k].map((e, i) => (e && typeof e === "object" && e.name === undefined ? { ...e, name: `${k}[${i}]` } : e));
+	return { ...spec, checks };
+}

package/src/motion3/qa/checks.js

@@ -0,0 +1,121 @@
+// General motion checks (every take): scene collisions, ground, IK reach, planted-foot slide,
+// bone length, one-frame pops (style.js), knee and elbow flips, knees bending backward, knees and
+// elbows folded past their stop (KNEE: the shin in the thigh; ELBOW: the forearm in the upper arm,
+// compiler/limbs.js), self contact, hands and held props entering the head (and the torso,
+// contact-checks.js; arms into any other body part on the fitted skin, body-checks.js). Speed, acceleration, knee bend and balance are style: style.js measures them
+// and checks them only when the spec names their limit (checks.limits).
+import { add, sub, scale, apply, len, dist, cross, norm, dot, angle } from "../compiler/math.js";
+import { CAPSULES, segPoints, sdBox, segDist, headDepth, solePoints } from "./geometry.js";
+import { contactChecks } from "./contact-checks.js";
+import { bodyChecks } from "./body-checks.js";
+import { popChecks } from "./style.js";
+import { groundSole } from "./ground.js";
+import { footChecks } from "./foot-checks.js";
+import { ELBOW_STOP, KNEE_STOP } from "../compiler/limbs.js";
+
+export const QA_LIMITS = { allow: 0.005, groundAllow: 0.01, reach: 0.01, slide: 0.0015, plantH: 0.012,
+	speedCore: 0.04, speedLimb: 0.16, accCore: 0.015, accLimb: 0.05, flip: 60, knee: 150, headAllow: 0.003, self: 0,
+	body: 0.005, skin: 0.015, hands: 0.01, object: 0.005, grab: 0.03, balance: 0.08 };
+/** FLIP reads a bend plane only where the limb is bent this far (deg) from straight and from folded flat. */
+const FLIP_BEND = 20;
+/** KNEE (folds) and ELBOW: degrees past KNEE_STOP or ELBOW_STOP that count (the IK sits on the stop to rounding). */
+const STOP_TOL = 0.01;
+
+export const allowance = (allow, part, obj) => {
+	for (const a of allow ?? []) if (part.startsWith(a.part) && (a.object === obj || (a.object.endsWith("*") && obj.startsWith(a.object.slice(0, -1))))) return a.depth;
+	return null;
+};
+
+export function generalChecks(sk, out, opts = {}) {
+	const L = { ...QA_LIMITS, ...opts.limits }, issues = [], I = sk.index, F = out.frames, n = F.length;
+	const push = (kind, msg, f, value, limit) => issues.push({ kind, msg, frame: f, value: +value.toFixed(4), limit });
+	for (let f = 0; f < n; f++) {
+		const { s, diag } = F[f], objs = out.objectsAt(f);
+		// bounding spheres of the boxes: a capsule farther away than its own reach cannot touch one
+		const spheres = Object.entries(objs).filter(([, box]) => box.half && !box.ignore)
+			.map(([id, box]) => [id, box, add(box.pos, apply(box.R, [0, box.half[1], 0])), len(box.half)]);
+		for (const [part, a, b, r] of CAPSULES) {
+			const A = s.P[I[a]], B = s.P[I[b]], mid = scale(add(A, B), 0.5), reach = r + dist(A, B) / 2;
+			let pts = null;
+			for (const [id, box, c, rb] of spheres) {
+				const lim = allowance(opts.allow, part, id) ?? L.allow;
+				if (reach - (dist(mid, c) - rb) <= lim) continue;
+				pts ??= segPoints(A, B);
+				const pen = r - Math.min(...pts.map(p => sdBox(p, box)));
+				if (pen > lim) push("COLLIDE", `${part} x ${id}`, f, pen, lim);
+			}
+		}
+		footChecks(sk, s, f, spheres, L, (part, id) => allowance(opts.allow, part, id), push);
+		for (const side of ["Left", "Right"]) {
+			const sp = solePoints(sk, s, side), low = Math.min(sp.heel[1], sp.ball[1], sp.tip[1]);
+			if (low < -L.groundAllow) push("GROUND", `${side} sole below floor`, f, -low, L.groundAllow);
+		}
+		for (const [k, v] of Object.entries(diag)) if (/miss_[lr]$/.test(k) && v > L.reach) push("REACH", k, f, v, L.reach);
+		// hands, forearms and held props must stay out of the head
+		const probes = [];
+		for (const S of ["Left", "Right"]) probes.push(...segPoints(s.P[I[`${S}Hand`]], s.P[I[`${S}HandMiddle3`]], 5).map(p => [`hand_${S[0].toLowerCase()}`, p, 0.022]));
+		for (const [pn, pts] of Object.entries(diag.props ?? {})) for (const [k, p] of Object.entries(pts)) if (Array.isArray(p) && k !== "origin" && !(opts.mouthPoints ?? []).includes(`${pn}.${k}`)) probes.push([`prop_${pn}`, p, 0.004]);
+		for (const [nm, p, r] of probes) { const d = headDepth(sk, s, p) + r; if (d > L.headAllow) push("FACE", `${nm} into head`, f, d, L.headAllow); }
+		if (segDist(s.P[I.LeftLeg], s.P[I.LeftFoot], s.P[I.RightLeg], s.P[I.RightFoot]) < 0.1 + L.self) push("SELF", "shins touch", f, 0.1, 0.1);
+		if (segDist(s.P[I.LeftUpLeg], s.P[I.LeftLeg], s.P[I.RightUpLeg], s.P[I.RightLeg]) < 0.135 + L.self) push("SELF", "thighs overlap", f, 0.135, 0.135);
+		for (const S of ["Left", "Right"]) {
+			const th = s.P[I[`${S}UpLeg`]], kn = s.P[I[`${S}Leg`]], an = s.P[I[`${S}Foot`]];
+			const bend = angle(sub(kn, th), sub(an, kn));
+			// the foot's heading on the ground; the toe sits below the ankle, which must not count
+			const toeDir = sub(s.P[I[`${S}ToeBase`]], an); toeDir[1] = 0;
+			const mid = sub(kn, [(th[0] + an[0]) / 2, (th[1] + an[1]) / 2, (th[2] + an[2]) / 2]);
+			if (bend > 3 && dot(mid, toeDir) < -0.002) push("KNEE", `${S} knee bends backward`, f, bend, 0);
+			// a knee folded past its stop puts the shin in the thigh (the solver stops at KNEE_STOP)
+			if (bend > KNEE_STOP + STOP_TOL) push("KNEE", `${S} knee folds ${bend.toFixed(0)}deg`, f, bend, KNEE_STOP);
+			// an elbow folded past its stop puts the forearm in the upper arm (the solver stops at ELBOW_STOP)
+			const fold = angle(sub(s.P[I[`${S}ForeArm`]], s.P[I[`${S}Arm`]]), sub(s.P[I[`${S}Hand`]], s.P[I[`${S}ForeArm`]]));
+			if (fold > ELBOW_STOP + STOP_TOL) push("ELBOW", `${S} elbow folds ${fold.toFixed(0)}deg`, f, fold, ELBOW_STOP);
+		}
+	}
+	const allowed = (part, into) => allowance(opts.allow, part, into);
+	contactChecks(sk, out, L, push, allowed);
+	bodyChecks(sk, out, L, push, allowed);
+	// temporal checks; a planted heel or ball is low over the ground under it, the floor or an object's top (ground.js)
+	for (const S of ["Left", "Right"]) {
+		const sole = F.map((_, f) => groundSole(out, f, S));
+		for (let f = 1; f < n; f++) {
+			const a = sole[f - 1], b = sole[f];
+			for (const key of ["heel", "ball"]) {
+				const planted = b[key][1] < L.plantH && a[key][1] < L.plantH && Math.abs(b[key][1] - a[key][1]) < 0.0005;
+				const hv = Math.hypot(b[key][0] - a[key][0], b[key][2] - a[key][2]);
+				if (planted && hv > L.slide) push("SLIDE", `${S} ${key} slides`, f, hv, L.slide);
+			}
+		}
+	}
+	for (let j = 0; j < sk.names.length; j++) {
+		const p = sk.parent[j]; if (p < 0) continue;
+		const L0 = dist(sk.restWorldPos[j], sk.restWorldPos[p]);
+		const drift = Math.max(...F.map(fr => Math.abs(dist(fr.s.P[j], fr.s.P[p]) - L0)));
+		if (drift > 0.001) push("LENGTH", `${sk.names[p]}-${sk.names[j]}`, 0, drift, 0.001);
+	}
+	popChecks(sk, out, L, push);
+	flipChecks(sk, F, L, push);
+	return issues;
+}
+
+/**
+ * FLIP: a knee's or elbow's bend plane turns more than L.flip degrees a frame. The plane is read
+ * only on frames the limb is bent FLIP_BEND or more from straight and from folded flat: near
+ * either end a few millimetres set it, so the hand or foot moving a few centimetres turns it any
+ * way (session df6acdcc: the right elbow folded to 171 deg as the wrist passed the shoulder, and
+ * its plane turned 71 deg in a frame while the elbow moved 3 cm). Across the frames between, the
+ * turn is shared out per frame, so a pole that flips while the limb is straight still shows.
+ */
+function flipChecks(sk, F, L, push) {
+	const I = sk.index, bent = Math.sin(FLIP_BEND * Math.PI / 180);
+	for (const S of ["Left", "Right"]) for (const [a, b, c] of [[`${S}UpLeg`, `${S}Leg`, `${S}Foot`], [`${S}Arm`, `${S}ForeArm`, `${S}Hand`]]) {
+		let prev = null, at = 0;
+		for (let f = 0; f < F.length; f++) {
+			const P = F[f].s.P, up = sub(P[I[b]], P[I[a]]), down = sub(P[I[c]], P[I[b]]), nv = cross(up, down);
+			if (len(nv) < bent * len(up) * len(down)) continue;
+			const u = norm(nv), turn = prev ? angle(u, prev) : 0, gap = f - at;
+			if (turn / gap > L.flip) push("FLIP", `${b} bend plane jumps ${turn.toFixed(0)}deg${gap > 1 ? ` over ${gap} frames` : ""}`, f, turn / gap, L.flip);
+			prev = u; at = f;
+		}
+	}
+}

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

@@ -0,0 +1,51 @@
+// Contact checks on top of the general set (ported from the car-exit prototype QA): hands and
+// held prop points entering the torso, the two hands overlapping, and hinged scene objects
+// (spec.objects, e.g. a door) passing through the rest of the scene. Corners only for objects.
+import { add, sub, scale, dot, len, apply, clamp } from "../compiler/math.js";
+import { CAPSULES, sdBox, segDist } from "./geometry.js";
+import { movesRecord } from "../carried.js";
+
+const TORSO = CAPSULES.filter(c => c[0].startsWith("torso"));
+const HAND_R = CAPSULES.find(c => c[0] === "hand_l")[3];
+const PROP_R = 0.004;
+
+function pointSegDist(p, a, b) {
+	const ab = sub(b, a), t = clamp(dot(sub(p, a), ab) / Math.max(dot(ab, ab), 1e-12), 0, 1);
+	return len(sub(p, add(a, scale(ab, t))));
+}
+
+function corners(o) {
+	const out = [];
+	for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) out.push(add(o.pos, apply(o.R, [x * o.half[0], y * o.half[1], z * o.half[2]])));
+	return out;
+}
+
+/** L: limits { body, hands, object } (m); push(kind, msg, frame, value, limit); allowed(part, into): a declared depth or null. */
+export function contactChecks(sk, out, L, push, allowed = () => null) {
+	const I = sk.index, hinged = Object.entries(out.ctx.spec.objects ?? {}).filter(([, o]) => movesRecord(o)).map(([id]) => id);
+	for (let f = 0; f < out.frames.length; f++) {
+		const { s, diag } = out.frames[f], P = s.P;
+		// hands into the torso: body-checks.js, on the fitted skin; held prop points stay on the capsules
+		const probes = [];
+		for (const [pn, pts] of Object.entries(diag.props ?? {})) for (const [k, p] of Object.entries(pts)) if (Array.isArray(p) && k !== "origin") probes.push([`prop_${pn}`, p, PROP_R]);
+		for (const [part, a, b, r] of TORSO) {
+			const worst = new Map();
+			for (const [nm, p, pr] of probes) worst.set(nm, Math.max(worst.get(nm) ?? -Infinity, r + pr - pointSegDist(p, P[I[a]], P[I[b]])));
+			for (const [nm, d] of worst) if (d > L.body) push("BODY", `${nm} into ${part}`, f, d, L.body);
+		}
+		const overlap = 2 * HAND_R - segDist(P[I.LeftHand], P[I.LeftHandMiddle3], P[I.RightHand], P[I.RightHandMiddle3]);
+		const handsLim = Math.max(allowed("hand_l", "hand_r") ?? 0, L.hands);
+		if (overlap > handsLim) push("SELF", "hands overlap", f, overlap, handsLim);
+		if (!hinged.length) continue;
+		const objs = out.objectsAt(f);
+		for (const id of hinged) {
+			if (!objs[id]?.half) continue;
+			const cs = corners(objs[id]);
+			for (const [oid, box] of Object.entries(objs)) {
+				if (hinged.includes(oid) || !box.half || box.ignore) continue;
+				const depth = -Math.min(...cs.map(p => sdBox(p, box)));
+				if (depth > L.object) push("OBJECT", `${id} into ${oid}`, f, depth, L.object);
+			}
+		}
+	}
+}

package/src/motion3/qa/explain.js

@@ -0,0 +1,80 @@
+// Actionable QA: every issue group gets a `cause` (the spec element most responsible: a key and
+// channel, an anchor, a fit, a generator step, a skill) and a `hint` (what to change, with a
+// direction and an amount in world metres or degrees, at a frame). Hints are derived from the
+// geometry of the worst frame and from the keys that bracket it. A hint function returns
+// { cause, hint, fix? }; fix rides on the group unseen (non-enumerable) for qa/patch.js.
+import { contactHints } from "./hints-contact.js";
+import { motionHints } from "./hints-motion.js";
+import { objectHints } from "./hints-object.js";
+import { goalHints } from "./hints-goal.js";
+import { wristHints } from "./wrist-checks.js";
+import { attachPatches } from "./patch.js";
+
+const HINTS = { ...contactHints, ...motionHints, ...objectHints, ...goalHints, ...wristHints };
+
+function keyTable(out) {
+	const byCh = new Map();
+	for (const k of out.keys ?? []) for (const ch of Object.keys(k.set ?? {})) {
+		if (!byCh.has(ch)) byCh.set(ch, []);
+		byCh.get(ch).push({ f: k.f, src: k.src ?? "keys", step: k.step?.includes(ch) });
+	}
+	for (const list of byCh.values()) list.sort((a, b) => a.f - b.f);
+	return byCh;
+}
+
+/** The context every hint function reads: frames by absolute index, keys, drivers. */
+function context(sk, out, spec) {
+	const table = keyTable(out);
+	const X = {
+		sk, out, spec, I: sk.index,
+		fr: f => out.frames[Math.max(0, Math.min(out.frames.length - 1, f - (out.f0 ?? 0)))],
+		rel: f => Math.max(0, Math.min(out.frames.length - 1, f - (out.f0 ?? 0))),
+		keys: ch => table.get(ch) ?? [],
+		bracket(ch, f) {
+			const list = X.keys(ch);
+			let prev = null, next = null;
+			for (const k of list) { if (k.f <= f) prev = k; else { next = k; break; } }
+			return { prev, next };
+		},
+		/** "keys[12] f200 hand_r" when a key sits within 2 frames, else the two keys around f. */
+		cause(ch, f) {
+			const { prev, next } = X.bracket(ch, f);
+			if (!prev && !next) return `${ch} (not keyed)`;
+			const near = prev && f - prev.f <= 2 ? prev : next && next.f - f <= 2 ? next : null;
+			if (near) return `${near.src} f${Math.round(near.f)} ${ch}`;
+			if (!next) return `${ch} held since ${prev.src} f${Math.round(prev.f)}`;
+			if (!prev) return `${ch} before ${next.src} f${Math.round(next.f)}`;
+			return `${ch} between ${prev.src} f${Math.round(prev.f)} and ${next.src === prev.src ? "" : `${next.src} `}f${Math.round(next.f)}`;
+		},
+		/** What drives hand k at frame f: an anchor weight, the hand target, or the FK arm. */
+		hand(k, f) {
+			const c = X.fr(f).c;
+			if (!(c[`armw_${k}`] > 0.5)) return { label: `arm ${k} (FK: aswing_${k}/abend_${k}, or armw_${k} 1 and hand_${k})`, ch: `aswing_${k}` };
+			let best = null;
+			for (const [ch, w] of Object.entries(c)) {
+				const mm = /^w_(.+)_([lr])$/.exec(ch);
+				if (mm && mm[2] === k && w > 0.5 && (!best || w > best.w)) best = { w, anchor: mm[1], ch };
+			}
+			if (!best) return { label: `hand_${k}`, ch: `hand_${k}` };
+			const fit = (spec.fits ?? []).findIndex(ft => ft.anchor === best.anchor && ft.side === k);
+			return { label: `anchor ${best.anchor}`, ch: best.ch, anchor: best.anchor, fit: fit >= 0 ? fit : null };
+		},
+	};
+	return X;
+}
+
+/** Adds cause + hint (+ patch) to the first `limit` groups (mutates and returns them); userSpec is what patches address. */
+export function explainGroups(sk, out, spec, groups, { limit = 16, userSpec } = {}) {
+	if (!groups.length) return groups;
+	const X = context(sk, out, spec);
+	for (const g of groups.slice(0, limit)) {
+		try {
+			const r = HINTS[g.kind]?.(X, g);
+			if (r) { g.cause = r.cause; g.hint = r.hint; }
+			if (r?.fix) Object.defineProperty(g, "fix", { value: r.fix, enumerable: false, configurable: true });
+		} catch (error) {
+			g.cause = "unknown"; g.hint = `no hint (${error.message})`;
+		}
+	}
+	return attachPatches(groups, { X, userSpec });
+}

package/src/motion3/qa/fmt.js

@@ -0,0 +1,5 @@
+// Compact number formatting for QA hints (millimetre precision).
+export const m3 = x => { const r = Math.round(x * 1000) / 1000; return Object.is(r, -0) ? 0 : r; };
+
+/** Compact vector: [+0.021, 0, -0.004]. */
+export const vec = v => `[${v.map(x => { const r = m3(x); return r > 0 ? `+${r}` : `${r}`; }).join(", ")}]`;

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

@@ -0,0 +1,72 @@
+// COLLIDE for the feet: the foot's skin against the scene bodies, as "foot_<k> x <id>". The shin capsule ends at
+// the ankle and GROUND reads the floor only, so a swinging toe went 9.6 cm into a stair riser with QA clean
+// (session e7edb718). The probes are points on the fitted skin of the foot and toe bones (body.js grids: the
+// cells within half a step of the skin, one per SPACING m cube, carried by their bone); a rig without a fitted
+// body uses the sole points. A foot on a body's top is a step, not a collision: a probe the top face is nearest
+// to may sit up to the ground's allowance in it (QA_LIMITS.groundAllow, as GROUND gives the floor); through a
+// side face the usual allowance holds. A part-wise allow entry ({ part: "foot", object }) sets both.
+import { add, apply, dist, dot, scale } from "../compiler/math.js";
+import { bodyFor } from "../body.js";
+import { sdBox, boxNormal, solePoints } from "./geometry.js";
+
+const UP = [0, 1, 0], TOP = 0.7, SPACING = 0.025;
+const skins = new Map();
+
+/** Skin points of a foot in its bones' bind frames: [[bone index, local point], ...] (null for a rig without a fitted body). */
+function footSkin(sk, side) {
+	const key = `${sk.model}:${side}`;
+	if (skins.has(key)) return skins.get(key);
+	const body = bodyFor(sk), out = body ? [] : null;
+	for (const g of body?.grids ?? []) {
+		if (g.b !== sk.index[`${side}Foot`] && g.b !== sk.index[`${side}ToeBase`]) continue;
+		const [nx, ny, nz] = g.dims, seen = new Set();
+		for (let i = 0; i < nx; i++) for (let j = 0; j < ny; j++) for (let k = 0; k < nz; k++) {
+			if (Math.abs(g.data[(i * ny + j) * nz + k] / 1000) > body.step / 2) continue;
+			const q = [g.min[0] + i * body.step, g.min[1] + j * body.step, g.min[2] + k * body.step], cell = q.map(v => Math.floor(v / SPACING)).join();
+			if (!seen.has(cell)) { seen.add(cell); out.push([g.b, q]); }
+		}
+	}
+	skins.set(key, out);
+	return out;
+}
+
+/** The foot's collision probes at state s: world points on its skin (the sole points without a fitted body). */
+export function footProbes(sk, s, side) {
+	const skin = footSkin(sk, side);
+	if (!skin?.length) {
+		const sp = solePoints(sk, s, side), mid = (a, b) => scale(add(a, b), 0.5);
+		return [sp.heel, mid(sp.heel, sp.ball), sp.ball, mid(sp.ball, sp.tip), sp.tip];
+	}
+	return skin.map(([b, q]) => add(s.P[b], apply(s.R[b], q)));
+}
+
+/**
+ * How deep a foot's probes go into a box, through its top and through its sides: { top, side } in metres
+ * (-Infinity: not in), each with the probe that goes deepest that way ({ topAt, sideAt }).
+ */
+export function footDepths(probes, box) {
+	const out = { top: -Infinity, side: -Infinity, topAt: null, sideAt: null };
+	for (const p of probes) {
+		const d = -sdBox(p, box);
+		if (d <= 0) continue;
+		const way = dot(boxNormal(p, box), UP) > TOP ? "top" : "side";
+		if (d > out[way]) { out[way] = d; out[`${way}At`] = p; }
+	}
+	return out;
+}
+
+/**
+ * Push COLLIDE "foot_<k> x <id>" for each foot in each body at frame f. spheres: [id, box, centre, radius] of
+ * the bodies (checks.js); allowed(part, id) the spec's allow depth or null.
+ */
+export function footChecks(sk, s, f, spheres, L, allowed, push) {
+	for (const [side, k] of [["Left", "l"], ["Right", "r"]]) {
+		const probes = footProbes(sk, s, side), part = `foot_${k}`;
+		for (const [id, box, c, rb] of spheres) {
+			if (probes.every(p => dist(p, c) > rb)) continue;
+			const d = footDepths(probes, box), own = allowed(part, id), sideLim = own ?? L.allow, topLim = own ?? L.groundAllow;
+			if (d.side > sideLim) push("COLLIDE", `${part} x ${id}`, f, d.side, sideLim);
+			else if (d.top > topLim) push("COLLIDE", `${part} x ${id}`, f, d.top, topLim);
+		}
+	}
+}