cozyclay 2.1.0 → 3.0.0

package/src/motion3/compiler/math.js

@@ -0,0 +1,72 @@
+// Small dependency-free vector / 3x3 / quaternion helpers for the motion3 compiler.
+// Vectors are [x, y, z]; matrices are row-major [[...],[...],[...]] acting on column
+// vectors (R v); quaternions are three.js order [x, y, z, w].
+
+export const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+export const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+export const len = a => Math.hypot(a[0], a[1], a[2]);
+export const dist = (a, b) => len(sub(a, b));
+export function norm(a) {
+	const l = len(a);
+	return l > 1e-12 ? [a[0] / l, a[1] / l, a[2] / l] : [0, 0, 0];
+}
+export const clamp = (x, lo, hi) => Math.min(hi, Math.max(lo, x));
+const rad = d => d * Math.PI / 180;
+const deg = r => r * 180 / Math.PI;
+
+export const I3 = () => [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+export function mul(A, B) {
+	const C = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+	for (let i = 0; i < 3; i++) for (let j = 0; j < 3; j++) C[i][j] = A[i][0] * B[0][j] + A[i][1] * B[1][j] + A[i][2] * B[2][j];
+	return C;
+}
+export const apply = (R, v) => [R[0][0] * v[0] + R[0][1] * v[1] + R[0][2] * v[2], R[1][0] * v[0] + R[1][1] * v[1] + R[1][2] * v[2], R[2][0] * v[0] + R[2][1] * v[1] + R[2][2] * v[2]];
+export const T = R => [[R[0][0], R[1][0], R[2][0]], [R[0][1], R[1][1], R[2][1]], [R[0][2], R[1][2], R[2][2]]];
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];
+
+export function rx(d) { const t = rad(d), c = Math.cos(t), s = Math.sin(t); return [[1, 0, 0], [0, c, -s], [0, s, c]]; }
+export function ry(d) { const t = rad(d), c = Math.cos(t), s = Math.sin(t); return [[c, 0, s], [0, 1, 0], [-s, 0, c]]; }
+export function rz(d) { const t = rad(d), c = Math.cos(t), s = Math.sin(t); return [[c, -s, 0], [s, c, 0], [0, 0, 1]]; }
+
+/** Rotation by `d` degrees about unit-normalised axis `ax` (Rodrigues). */
+export function axisRot(ax, d) {
+	const [x, y, z] = norm(ax), t = rad(d), c = Math.cos(t), s = Math.sin(t), k = 1 - c;
+	return [[c + x * x * k, x * y * k - z * s, x * z * k + y * s], [y * x * k + z * s, c + y * y * k, y * z * k - x * s], [z * x * k - y * s, z * y * k + x * s, c + z * z * k]];
+}
+
+/** Orthonormal frame whose first column is d and second lies toward p. */
+function frame(d, p) {
+	const a = norm(d);
+	let b = sub(p, scale(a, dot(p, a)));
+	if (len(b) < 1e-9) b = sub([0, 1, 0], scale(a, a[1])), len(b) < 1e-9 && (b = sub([1, 0, 0], scale(a, a[0])));
+	b = norm(b);
+	return cols(a, b, cross(a, b));
+}
+
+/** Rotation taking frame (d0, p0) onto frame (d1, p1). */
+export const align = (d0, p0, d1, p1) => mul(frame(d1, p1), T(frame(d0, p0)));
+
+export function quatFromMat(R) {
+	const m00 = R[0][0], m11 = R[1][1], m22 = R[2][2], tr = m00 + m11 + m22;
+	let x, y, z, w;
+	if (tr > 0) { const s = 0.5 / Math.sqrt(tr + 1); w = 0.25 / s; x = (R[2][1] - R[1][2]) * s; y = (R[0][2] - R[2][0]) * s; z = (R[1][0] - R[0][1]) * s; }
+	else if (m00 > m11 && m00 > m22) { const s = 2 * Math.sqrt(1 + m00 - m11 - m22); w = (R[2][1] - R[1][2]) / s; x = 0.25 * s; y = (R[0][1] + R[1][0]) / s; z = (R[0][2] + R[2][0]) / s; }
+	else if (m11 > m22) { const s = 2 * Math.sqrt(1 + m11 - m00 - m22); w = (R[0][2] - R[2][0]) / s; x = (R[0][1] + R[1][0]) / s; y = 0.25 * s; z = (R[1][2] + R[2][1]) / s; }
+	else { const s = 2 * Math.sqrt(1 + m22 - m00 - m11); w = (R[1][0] - R[0][1]) / s; x = (R[0][2] + R[2][0]) / s; y = (R[1][2] + R[2][1]) / s; z = 0.25 * s; }
+	const l = Math.hypot(x, y, z, w);
+	return [x / l, y / l, z / l, w / l];
+}
+
+export function matFromQuat([x, y, z, w]) {
+	return [
+		[1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+		[2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+		[2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+	];
+}
+
+/** Angle in degrees between two directions. */
+export const angle = (a, b) => deg(Math.acos(clamp(dot(norm(a), norm(b)), -1, 1)));

package/src/motion3/compiler/pose.js

@@ -0,0 +1,162 @@
+// One frame of the body: channel values -> world-space bone state.
+// Conventions (CozyClay): metres, +Y up, yaw 0 faces +Z, positive yaw turns toward +X,
+// the character's left is +X at yaw 0. Body-frame vectors (poles, body-local targets) are
+// rotated by the root yaw only.
+import { add, sub, scale, norm, len, apply, mul, rx, ry, rz } from "./math.js";
+import { restState, rotateSubtree } from "./skeleton.js";
+import { twoBone, orientFoot, wrist, fingers, limitFold, askedFold, swivelElbow, ELBOW_FOLD, KNEE_FOLD } from "./limbs.js";
+import { holdHand } from "./hold.js";
+import { clampWrist } from "./wrist-clamp.js";
+import { ELBOW_REST } from "./arm-orient.js";
+import { wristBody, bodyDistance } from "../body.js";
+
+export const SIDES = { l: "Left", r: "Right" };
+/** How much of an auto-fix elbow turn an arm at IK weight w takes (fix/self.js plans with the same). */
+export const turnWeight = w => { const x = Math.min(1, Math.max(0, w)); return x * x * (3 - 2 * x); };
+const KNEE_REST = [0, 0, 1], LEG = ["UpLeg", "Leg", "Foot"];
+
+const v3 = (x, d = [0, 0, 0]) => (Array.isArray(x) || ArrayBuffer.isView(x) ? [x[0], x[1], x[2]] : d);
+const num = (x, d = 0) => (typeof x === "number" && Number.isFinite(x) ? x : d);
+
+/** Split a body-frame rotation over a chain of bones, each turning about its own joint. */
+function spread(sk, s, bones, yaw, pitch, roll) {
+	const k = bones.length;
+	for (const name of bones) {
+		const b = sk.index[name];
+		rotateSubtree(sk, s, b, s.P[b].slice(), mul(ry(yaw / k), mul(rx(pitch / k), rz(roll / k))));
+	}
+}
+
+// Soft reach (spec.fix.reach): a wrist target up to 5 cm beyond the arm's reach is pulled onto
+// the reach sphere through a C1 soft knee, so the arm never snaps straight; the overshoot is
+// recorded. Farther targets are staging errors and stay for QA (REACH).
+const SOFT_KNEE = 0.99, SOFT_MAX = 0.9995;
+export const REACH_FIX_MAX = 0.05;
+function softReach(sk, s, a, fa, h, target, diag, k) {
+	const R = len(sub(s.P[fa], s.P[a])) + len(sub(s.P[h], s.P[fa])), v = sub(target, s.P[a]), d = len(v);
+	const k0 = SOFT_KNEE * R, w = (SOFT_MAX - SOFT_KNEE) * R;
+	if (d <= k0 || d - SOFT_MAX * R > REACH_FIX_MAX) return target;
+	const dc = k0 + w * (1 - Math.exp(-(d - k0) / w));
+	diag[`reach_over_${k}`] = Math.max(0, d - SOFT_MAX * R);
+	return add(s.P[a], scale(v, dc / d));
+}
+
+/**
+ * hooks.handTarget(side, s) -> { target:[x,y,z] } world wrist target before the FK/IK blend
+ * hooks.afterArm(side, s, diag) lets the caller measure props carried by that hand.
+ * hooks.push(side) -> [x,y,z] | undefined, a world offset added to the IK target (auto-fix); hooks.skinPush(side) the same
+ * for the self fix (fix/self.js), taken as far as the arm is on its IK.
+ * hooks.softReach clamps unreachable wrist targets smoothly (auto-fix).
+ * hooks.foldFree lets the arm IK fold past the elbow's stop (a fit's measuring passes, compile.js).
+ * hooks.hold(side, s) -> { w, palm, measure, pole?, second? } | null: a held object's keys lead the hand (hold.js).
+ * hooks.keepOut(side, s, target) -> target: the blended wrist target kept out of the body (auto-fix, compile.js).
+ * hooks.swivel(side) -> deg | undefined, an elbow turn about the shoulder-wrist line, the hand kept (auto-fix, fix/self.js).
+ * diag.arm_fold_<k>: the flexion (deg) the wrist target asked when past ELBOW_FOLD (arm_miss_<k> is then how far inside).
+ * diag.leg_fold_<k>: the knee flexion (deg) the ankle target asked when past KNEE_FOLD (leg_miss_<k> is then how far inside).
+ */
+// arm_hang (keyed by standIdle and the walk): a free FK forearm hangs plumb from the elbow, as a person's does,
+// instead of carrying on the upper arm's slant out from the body (the hands sat about 9 cm wider than a person's);
+// a working arm (on IK, or a hand that holds something: compile.js hangoff, idle.js busyHands) takes none of it. A rig whose thigh comes near (the X Bot) stops HANG_BACK
+// degrees short of the first angle that brings its forearm or hand within HANG_CLEAR of the skin standing, so the
+// walk's sway does not carry it into the thigh. Faded out as arm_rest raises the arms (none at 45); once per rig and rest.
+const HANG_CLEAR = 0.095, HANG_BACK = 2, hangs = new Map();
+function hangOf(sk, down) {
+	const key = `${sk.model}|${down}`;
+	if (hangs.has(key)) return hangs.get(key);
+	const full = (90 - down) * Math.min(1, Math.max(0, (down - 45) / 27)), wb = wristBody(sk);
+	const clearAt = h => {
+		const s = restState(sk);
+		return [["Left", -1], ["Right", 1]].every(([side, sg]) => {
+			const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], hd = sk.index[`${side}Hand`], tip = sk.index[`${side}HandMiddle1`];
+			rotateSubtree(sk, s, a, s.P[a].slice(), rz(sg * down));
+			rotateSubtree(sk, s, fa, s.P[fa].slice(), rz(sg * h));
+			const pts = [0.5, 0.75, 1].map(t => add(s.P[fa], scale(sub(s.P[hd], s.P[fa]), t))).concat([s.P[tip]]);
+			return pts.every(p => bodyDistance(wb.body, s, p, wb.skip).d >= HANG_CLEAR);
+		});
+	};
+	let hang = full;
+	if (wb && full > 0) {
+		for (let h = 0; h <= full; h += 0.5) if (!clearAt(h)) { hang = Math.max(0, h - HANG_BACK); break; }
+	}
+	hangs.set(key, hang);
+	return hang;
+}
+
+export function pose(sk, c, hooks = {}) {
+	const s = restState(sk);
+	const diag = {};
+	// Base: arms down from the bind T-pose (body frame, before everything else).
+	const down = num(c.arm_rest, 72), hang = num(c.arm_hang) && num(c.arm_hang) * hangOf(sk, down);
+	for (const [side, sg, k] of [["Left", -1, "l"], ["Right", 1, "r"]]) {
+		const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], h = hang * (1 - Math.min(1, Math.max(0, num(c[`armw_${k}`]) + num(c[`hangoff_${k}`]))));
+		rotateSubtree(sk, s, a, s.P[a].slice(), rz(sg * down));
+		if (h) rotateSubtree(sk, s, fa, s.P[fa].slice(), rz(sg * h));
+	}
+	// FK arm swing (forward +) and elbow bend, body frame.
+	for (const [k, side] of Object.entries(SIDES)) {
+		const bd = num(c[`abend_${k}`]), sw = num(c[`aswing_${k}`]);
+		const fa = sk.index[`${side}ForeArm`], a = sk.index[`${side}Arm`];
+		// an FK bend past the fold eases to its stop like the IK (limbs.js elbowFold)
+		if (bd) { rotateSubtree(sk, s, fa, s.P[fa].slice(), rx(-bd)); limitFold(sk, s, side); }
+		if (sw) rotateSubtree(sk, s, a, s.P[a].slice(), rx(-sw));
+	}
+	spread(sk, s, ["Neck", "Head"], num(c.head_yaw), num(c.head_pitch), num(c.head_roll));
+	spread(sk, s, ["Spine", "Spine1", "Spine2"], num(c.spine_yaw), num(c.spine_pitch), num(c.spine_roll));
+	// Root: turn about the hips joint, then put the hips at `root`.
+	const hips = sk.index.Hips, yaw = num(c.yaw);
+	rotateSubtree(sk, s, hips, s.P[hips].slice(), mul(ry(yaw), mul(rx(num(c.pitch)), rz(num(c.roll)))));
+	const shift = sub(v3(c.root, s.P[hips]), s.P[hips]);
+	for (let j = 0; j < s.P.length; j++) s.P[j] = add(s.P[j], shift);
+	const body = ry(yaw);
+	// Legs: two-bone IK to the ankle targets, the knee no further folded than its stop (limbs.js KNEE_STOP), then aim the feet.
+	for (const [k, side] of Object.entries(SIDES)) {
+		if (!c[`foot_${k}`]) continue;
+		const target = v3(c[`foot_${k}`]);
+		diag[`leg_miss_${k}`] = twoBone(sk, s, sk.index[`${side}UpLeg`], sk.index[`${side}Leg`], sk.index[`${side}Foot`],
+			target, apply(body, v3(c[`knee_${k}`], KNEE_REST)), KNEE_REST, "knee");
+		// a target nearer the hip than the knee folds leaves a residual (leg_miss); leg_fold says what it asked
+		const fold = askedFold(sk, s, side, target, LEG);
+		if (fold > KNEE_FOLD) diag[`leg_fold_${k}`] = fold;
+		orientFoot(sk, s, side, num(c[`fyaw_${k}`], yaw), num(c[`fpitch_${k}`]));
+	}
+	// Arms: blend the FK hand toward the hook's target, poles blended the same way.
+	for (const k of hooks.armOrder ?? ["r", "l"]) {
+		const side = SIDES[k], w = num(c[`armw_${k}`]);
+		const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], h = sk.index[`${side}Hand`];
+		const poleIk = norm(apply(body, v3(c[`elbow_${k}`], [0, -1, -0.3])));
+		diag[`arm_miss_${k}`] = 0;
+		if (w > 1e-4 && hooks.handTarget) {
+			const fkHand = s.P[h].slice();
+			const goal = hooks.handTarget(k, s, diag) ?? fkHand;
+			let target = add(fkHand, scale(sub(goal, fkHand), w));
+			if (hooks.keepOut) target = hooks.keepOut(k, s, target);
+			const push = hooks.push?.(k);
+			if (push) target = add(target, push);
+			// the self fix's push rides the IK as far as the arm is on it (an arm coming in from FK would jump)
+			const skinPush = hooks.skinPush?.(k);
+			if (skinPush) target = add(target, scale(skinPush, turnWeight(w)));
+			if (hooks.softReach) target = softReach(sk, s, a, fa, h, target, diag, k);
+			const poleFk = norm(sub(s.P[fa], scale(add(s.P[a], fkHand), 0.5)));
+			const pole = add(scale(poleFk, 1 - w), scale(poleIk, w));
+			// a target nearer the shoulder than the elbow folds leaves a residual too; arm_fold says what it asked
+			diag[`arm_miss_${k}`] = twoBone(sk, s, a, fa, h, target, pole, ELBOW_REST, hooks.foldFree ? null : "elbow");
+			const fold = askedFold(sk, s, side, target);
+			if (fold > ELBOW_FOLD && !hooks.foldFree) diag[`arm_fold_${k}`] = fold;
+		}
+		wrist(sk, s, side, num(c[`wtwist_${k}`]), num(c[`wflex_${k}`]));
+		fingers(sk, s, side, c[`fingers_${k}`]);
+		const held = hooks.hold?.(k, s);
+		// a keyed carry's hand follows its object; else a fit's hand takes a grip on the body under its anchor (grip.js),
+		// and while the keys only ease in (before the first key) the arm they ease from takes it too
+		if (!held || held.w < 1) hooks.grip?.(k, s, diag);
+		if (held) holdHand(sk, s, side, held, ELBOW_REST, diag, k);
+		// after a held object's grip, so its hand keeps the grip the hold solved; an arm coming in from FK turns
+		// no more than its IK weight (the IK elbow already lands somewhere else than the FK one)
+		const turn = hooks.swivel?.(k);
+		// the turn keeps the hand's world turn; a wrist it takes past its limits stops there and the hand turns with the elbow
+		// (wrist-clamp.js), unless keys lead what the hand holds: that hand keeps the object's grip (hold.js limits its wrist)
+		if (turn) { swivelElbow(sk, s, side, turn * turnWeight(w)); if (!held) clampWrist(sk, s, side); }
+		hooks.afterArm?.(k, s, diag);
+	}
+	return { s, diag };
+}

package/src/motion3/compiler/quat.js

@@ -0,0 +1,49 @@
+// Quaternion helpers for the held-object keys (../object-keys.js) and the hand-from-object solve
+// (hold.js). Quaternions are three.js order [x, y, z, w], as math.js quatFromMat / matFromQuat;
+// a rotation vector is axis * radians.
+
+export const qmul = (a, b) => [
+	a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+	a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+	a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+	a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+];
+export const qconj = q => [-q[0], -q[1], -q[2], q[3]];
+export const qdot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+export function qnorm(q) {
+	const l = Math.hypot(q[0], q[1], q[2], q[3]);
+	return l > 1e-12 ? [q[0] / l, q[1] / l, q[2] / l, q[3] / l] : [0, 0, 0, 1];
+}
+
+/** Rotation vector of unit q, the short way round (|v| <= pi). */
+export function qlog(q) {
+	const sg = q[3] < 0 ? -1 : 1, x = q[0] * sg, y = q[1] * sg, z = q[2] * sg, w = q[3] * sg, s = Math.hypot(x, y, z);
+	if (s < 1e-12) return [2 * x, 2 * y, 2 * z];
+	const a = 2 * Math.atan2(s, w) / s;
+	return [x * a, y * a, z * a];
+}
+
+/** Unit quaternion of rotation vector v. */
+export function qexp(v) {
+	const a = Math.hypot(v[0], v[1], v[2]);
+	if (a < 1e-12) return qnorm([v[0] / 2, v[1] / 2, v[2] / 2, 1]);
+	const s = Math.sin(a / 2) / a;
+	return [v[0] * s, v[1] * s, v[2] * s, Math.cos(a / 2)];
+}
+
+/** Rotate vector v by unit q. */
+export const qrot = (q, v) => qmul(qmul(q, [v[0], v[1], v[2], 0]), qconj(q)).slice(0, 3);
+
+/** The shortest turn taking unit direction a onto unit direction b (half a turn about a normal of a when they are opposite). */
+export function arcQuat(a, b) {
+	const w = 1 + a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+	if (w > 1e-9) return qnorm([a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0], w]);
+	const n = Math.abs(a[0]) < 0.9 ? [0, a[2], -a[1]] : [-a[2], 0, a[0]], l = Math.hypot(...n);
+	return [n[0] / l, n[1] / l, n[2] / l, 0];
+}
+
+/** The turn by `deg` degrees about unit axis `u` (right-handed). */
+export const axisQuat = (u, deg) => { const h = deg * Math.PI / 360, s = Math.sin(h); return [u[0] * s, u[1] * s, u[2] * s, Math.cos(h)]; };
+
+/** a -> b by t along the short arc (t = 0: a, t = 1: b). */
+export const slerp = (a, b, t) => qmul(a, qexp(qlog(qmul(qconj(a), b)).map(c => c * t)));

package/src/motion3/compiler/skeleton.js

@@ -0,0 +1,74 @@
+// Rig skeleton for the motion3 compiler: bind data from src/motion3/rigs/<model>.json
+// (extracted by tools/motion3/extract-rig.mjs), in METRES, rig root at the origin
+// facing +Z with +X on the character's left.
+import { apply, add, sub, mul, T, matFromQuat, quatFromMat } from "./math.js";
+
+const CM = 0.01;
+
+export function createSkeleton(rigJson) {
+	const bones = rigJson.bones;
+	const names = bones.map(b => b.name);
+	const index = Object.fromEntries(names.map((n, i) => [n, i]));
+	const parent = bones.map(b => b.parent);
+	const children = names.map(() => []);
+	parent.forEach((p, i) => { if (p >= 0) children[p].push(i); });
+	// subtree[i] = i and every descendant, parents before children
+	const subtree = names.map((_, i) => {
+		const out = [], stack = [i];
+		while (stack.length) { const j = stack.shift(); out.push(j); stack.unshift(...children[j]); }
+		return out;
+	});
+	const restLocalPos = bones.map(b => b.localPos.map(v => v * CM));
+	const restLocalRot = bones.map(b => matFromQuat(b.localQuat));
+	const restWorldPos = bones.map(b => b.worldPos.map(v => v * CM));
+	const restWorldRot = bones.map(b => matFromQuat(b.worldQuat));
+	const L = rigJson.landmarks;
+	const head = index.Head;
+	// Landmarks re-expressed in the Head bone's rest frame, so they ride the head.
+	const toHead = p => apply(T(restWorldRot[head]), sub(p.map(v => v * CM), restWorldPos[head]));
+	const landmarks = {
+		mouth: toHead(L.mouth),
+		headCentre: toHead(L.headEllipsoid.centre),
+		headRadii: L.headEllipsoid.radii.map(v => v * CM),
+		// how far the skin's sole lies below the ToeBase / Toe_End joints at bind (m; qa/geometry.js solePoints)
+		sole: { ball: (L.sole?.ball ?? 0) * CM, tip: (L.sole?.tip ?? 0) * CM },
+	};
+	return { model: rigJson.model, names, index, parent, children, subtree, restLocalPos, restLocalRot, restWorldPos, restWorldRot, landmarks };
+}
+
+/** Rest pose as a mutable world-space state { P, R }. */
+export function restState(sk) {
+	return { P: sk.restWorldPos.map(p => p.slice()), R: sk.restWorldRot.map(r => r.map(row => row.slice())) };
+}
+
+/** Rigidly rotate bone `b`'s subtree by world rotation R about world point `pivot`. */
+export function rotateSubtree(sk, s, b, pivot, R) {
+	for (const j of sk.subtree[b]) {
+		s.P[j] = add(pivot, apply(R, sub(s.P[j], pivot)));
+		s.R[j] = mul(R, s.R[j]);
+	}
+}
+
+/** World state -> per-bone LOCAL quaternions [x,y,z,w] plus the hips local position (m). */
+export function toLocal(sk, s) {
+	const quats = sk.names.map((_, j) => {
+		const p = sk.parent[j];
+		return quatFromMat(p < 0 ? s.R[j] : mul(T(s.R[p]), s.R[j]));
+	});
+	return { quats, hips: s.P[sk.index.Hips].slice() };
+}
+
+/** Forward kinematics from local quaternions + hips position back to a world state. */
+export function fk(sk, quats, hips) {
+	const P = [], R = [];
+	for (const j of sk.subtree[sk.index.Hips]) {
+		const p = sk.parent[j], Lr = matFromQuat(quats[j]);
+		if (p < 0) { R[j] = Lr; P[j] = hips.slice(); continue; }
+		R[j] = mul(R[p], Lr);
+		P[j] = add(P[p], apply(R[p], sk.restLocalPos[j]));
+	}
+	return { P, R };
+}
+
+/** Point fixed to a bone, given in that bone's own frame (e.g. a landmark). */
+export const bonePoint = (s, b, local) => add(s.P[b], apply(s.R[b], local));

package/src/motion3/compiler/validate-common.js

@@ -0,0 +1,32 @@
+// The checks every part of the validator shares: a bone, a scene object, a check point.
+// Messages are exact (the agent fixes them in one edit). See validate.js.
+import { didYouMean } from "./vocab.js";
+import { partsOf } from "../object-pose.js";
+
+export function boneOk(err, sk, at, bone) {
+	if (!sk || sk.index[bone] !== undefined) return true;
+	err(`${at} names unknown bone "${bone}"${didYouMean(String(bone), sk.names)}`);
+	return false;
+}
+
+/**
+ * A scene object id. A group (an Empty: no box of its own) passes only with { groups: true }
+ * (carry, hinge, object: refs and object anchors take groups, see C3); elsewhere the message lists its parts.
+ */
+export function objectOk(err, scene, at, id, { groups = false } = {}) {
+	const ids = Object.keys(scene?.objects ?? {});
+	if (!ids.length || ids.includes(id)) return true;
+	const parts = partsOf(scene, id);
+	if (parts.length && groups) return true;
+	if (parts.length) err(`${at} names "${id}", a group (Empty) with no body of its own; its parts are ${parts.join(", ")}. Name one part`);
+	else err(`${at} names object "${id}", which is not in the scene${didYouMean(String(id), [...new Set([...ids, ...ids.flatMap(k => scene.objects[k].ancestors ?? []), ...Object.keys(scene.others ?? {})])])}`);
+	return false;
+}
+
+export function refOk(spec, err, sk, at, ref) {
+	const [kind, rest] = String(ref).split(/:(.*)/s);
+	if (kind === "joint") return boneOk(err, sk, at, rest);
+	if (kind === "anchor") return spec.anchors?.[rest] ? true : err(`${at} "${ref}" names no anchor`);
+	if (kind === "prop") { const [p, pt] = (rest ?? "").split("."); return spec.props?.[p]?.points?.[pt] || pt === "origin" ? true : err(`${at} "${ref}" names no prop point`); }
+	err(`${at} "${ref}" must be joint:<Bone>, prop:<prop>.<point> or anchor:<name>`);
+}

package/src/motion3/compiler/validate-goals.js

@@ -0,0 +1,118 @@
+// Validation of spec.goals (C8), exact messages through err(...):
+//   - each goal names exactly one predicate of near | above | moved | still | speed
+//     (schema/fields.js GOAL_FIELDS)
+//   - near/above take two refs, moved/still/speed one ref (refs.js checkRef, the full ref grammar);
+//     a bare "<id>[.center|.top|.base]" in moved, still or speed is taken as object:<id>
+//     (canonicalGoals, before validation; the spec a specId names holds the object: form); moved
+//     and still on any other point measure from at[0], so they need at: [f0, f1] with f0 < f1
+//   - tol (near, still) and by (above, moved, speed) are numbers; speed needs by (m/s, > 0);
+//     mode "all" | "any", at an absolute frame or [f0, f1] within 0..frames-1; goal names differ
+//   - after / before name another goal (its name, or goals[i] for an unnamed one); a goal that
+//     waits on itself through after/before is refused, listing the loop
+//   - unknown fields go through opts.unknown (ignored when lenient)
+import { GOAL_FIELDS } from "../schema/fields.js";
+import { checkRef } from "../refs.js";
+import { GOAL_KINDS, ONE_REF, goalKinds, goalName } from "../qa/goals.js";
+import { didYouMean, fmt } from "./vocab.js";
+
+const SHAPE = "{ name?, near | above | moved | still | speed, tol?, by?, at, mode?, after?, before? }";
+const TOL = new Set(["near", "still"]), BY = new Set(["above", "moved", "speed"]);
+// tol on above/moved is refused, not mapped: a tolerance reads as by: -tol (slack) or by: tol (clearance),
+// and agents meant both, so the message names each by that could be meant with the number sent.
+function tolOnBy(kind, tol) {
+	const v = Number.isFinite(tol) && tol !== 0 ? Math.abs(tol) : 0.05;
+	if (kind === "speed") return `speed takes by (the point reaches by m/s): use by: ${v} (m/s), not tol`;
+	return kind === "above" ? `above takes by (a.y - b.y >= by, default 0): use by: ${v} for a at least ${v} m above b, or by: -${v} to let a sit up to ${v} m below b, not tol`
+		: `moved takes by (the object moves >= by, default 0.05): use by: ${v} (metres), not tol`;
+}
+const bareRef = v => typeof v === "string" && v !== "" && !/^[a-z]+:/.test(v);
+const bareOf = g => ["moved", "still", "speed"].find(k => bareRef(g?.[k]));
+
+/** goals with every bare moved, still or speed id written as "object:<id>"; goals itself when none is bare. */
+export function canonicalGoals(goals) {
+	return Array.isArray(goals) && goals.some(bareOf) ? goals.map(g => { const k = bareOf(g); return k ? { ...g, [k]: `object:${g[k]}` } : g; }) : goals;
+}
+
+function validateAt(err, at, v, frames, past = "") {
+	const ok = f => Number.isInteger(f);
+	if (v === undefined) return err(`${at} needs at: a frame or [f0, f1] (absolute frames within 0..${frames - 1})`);
+	const range = Array.isArray(v) ? v : [v, v];
+	if (!(range.length === 2 && range.every(ok) && range[0] <= range[1])) return err(`${at}.at must be an integer frame or [f0, f1] with f0 <= f1, got ${fmt(v)}`);
+	if (range[0] < 0 || range[1] > frames - 1) err(`${at}.at = ${fmt(v)} is outside 0..${frames - 1} (spec.frames ${frames})${range[1] > frames - 1 ? past : ""}`);
+}
+
+/** The one-ref predicates: an object id or a point ref; moved and still on a point need a span. */
+function validateOneRef(spec, err, ctx, at, g, kind) {
+	const ref = g[kind];
+	if (typeof ref !== "string") return err(`${at}.${kind} must be an object id or a point ref (object:<id>[.center|.top|.base], prop:<prop>.<point>, joint:<Bone>, landmark:mouth, anchor:<name>), got ${fmt(ref)}`);
+	if (checkRef(spec, err, ctx, `${at}.${kind}`, ref) && kind !== "speed" && !ref.startsWith("object:") && (Number.isInteger(g.at) || (Array.isArray(g.at) && g.at[0] === g.at[1])))
+		err(`${at}.${kind} "${ref}" measures ${kind === "moved" ? "how far the point gets" : "how far the point strays"} from where it is at at[0], so at must be [f0, f1] with f0 < f1, got ${fmt(g.at)}`);
+}
+
+function validateGoal(spec, err, opts, g, i, names) {
+	const at = `goals[${i}]`, ctx = { sk: opts.sk, scene: opts.scene }, unknown = opts.unknown ?? err;
+	if (!g || typeof g !== "object" || Array.isArray(g)) return err(`${at} must be ${SHAPE}, got ${fmt(g)}`);
+	for (const f of Object.keys(g)) if (!GOAL_FIELDS.includes(f)) unknown(`${at} has unknown field "${f}"${didYouMean(f, GOAL_FIELDS)} (fields: ${GOAL_FIELDS.join(", ")})`);
+	if (g.name !== undefined) {
+		if (typeof g.name !== "string" || !g.name.trim()) err(`${at}.name must be a non-empty string, got ${fmt(g.name)}`);
+		else if (names.has(g.name)) err(`${at}.name "${g.name}" is already used by goals[${names.get(g.name)}]; goal names must differ`);
+		else names.set(g.name, i);
+	}
+	const kinds = goalKinds(g), kind = kinds[0];
+	if (!kinds.length) err(`${at} needs one predicate: ${GOAL_KINDS.join(", ")}`);
+	if (kinds.length > 1) err(`${at} names ${kinds.join(" and ")}; a goal takes exactly one of ${GOAL_KINDS.join(", ")} (split it into ${kinds.length} goals)`);
+	if (kinds.length === 1 && ONE_REF.has(kind)) validateOneRef(spec, err, ctx, at, g, kind);
+	else if (kinds.length === 1) {
+		const pair = g[kind];
+		if (!(Array.isArray(pair) && pair.length === 2 && pair.every(r => typeof r === "string"))) err(`${at}.${kind} must be [ref, ref] (two point refs), got ${fmt(pair)}`);
+		else pair.forEach((ref, j) => checkRef(spec, err, ctx, `${at}.${kind}[${j}]`, ref));
+	}
+	if (g.tol !== undefined) {
+		if (kinds.length === 1 && !TOL.has(kind)) err(`${at}.tol applies to near and still; ${tolOnBy(kind, g.tol)}`);
+		else if (!(Number.isFinite(g.tol) && g.tol >= 0)) err(`${at}.tol must be a number >= 0 (metres), got ${fmt(g.tol)}`);
+	}
+	if (g.by !== undefined) {
+		if (kinds.length === 1 && !BY.has(kind)) err(`${at}.by applies to above, moved and speed; ${kind} takes tol`);
+		else if (!Number.isFinite(g.by) || (kind === "moved" && g.by < 0) || (kind === "speed" && g.by <= 0)) err(`${at}.by must be a ${kind === "moved" ? "number >= 0 (metres)" : kind === "speed" ? "number > 0 (m/s)" : "finite number (metres)"}, got ${fmt(g.by)}`);
+	} else if (kind === "speed" && kinds.length === 1) err(`${at}.speed needs by: the speed the point must reach, in m/s (e.g. by: 2)`);
+	if (g.mode !== undefined && g.mode !== "all" && g.mode !== "any") err(`${at}.mode must be "all" or "any", got ${fmt(g.mode)}`);
+	validateAt(err, at, g.at, opts.frames, opts.past);
+}
+
+/** after/before: each names another goal, and no goal waits on itself; one message per loop. */
+function validateOrder(goals, err) {
+	const names = new Map(goals.map((g, i) => [g && typeof g === "object" ? goalName(g, i) : `goals[${i}]`, i]));
+	const waits = goals.map((g, i) => ["after", "before"].flatMap(side => {
+		if (!g || typeof g !== "object" || g[side] === undefined) return [];
+		const j = names.get(g[side]);
+		if (typeof g[side] !== "string" || j === undefined) { err(`goals[${i}].${side} must name another goal (its name, or goals[<i>] when it has none), got ${fmt(g[side])}${typeof g[side] === "string" ? didYouMean(g[side], [...names.keys()]) : ""}`); return []; }
+		if (j === i) { err(`goals[${i}].${side} names the goal itself; name the goal whose first met frame this one waits for`); return []; }
+		return [j];
+	}));
+	const state = goals.map(() => 0), path = [];
+	const visit = i => {
+		if (state[i] === 2) return;
+		if (state[i] === 1) {
+			const loop = path.slice(path.indexOf(i)).map(j => `"${goalName(goals[j], j)}"`);
+			return err(`goals wait on each other through after/before: ${[...loop, loop[0]].join(" -> ")}; one of them must not wait`);
+		}
+		state[i] = 1; path.push(i);
+		for (const j of waits[i]) visit(j);
+		path.pop(); state[i] = 2;
+	};
+	goals.forEach((_, i) => visit(i));
+}
+
+/**
+ * validateGoals(spec, err, opts)
+ * @param {object} spec  the expanded spec
+ * @param {(msg: string) => void} err  collects one problem (validate.js)
+ * @param {{ sk?: object, scene?: object, frames: number, lenient?: boolean, unknown?: (msg: string) => void, past?: string }} opts
+ */
+export function validateGoals(spec, err, opts) {
+	if (spec.goals === undefined) return;
+	if (!Array.isArray(spec.goals)) return err(`spec.goals must be an array of goals ${SHAPE}, got ${fmt(spec.goals)}`);
+	const names = new Map();
+	spec.goals.forEach((g, i) => validateGoal(spec, err, opts, g, i, names));
+	validateOrder(spec.goals, err);
+}