cozyclay 2.1.0 → 3.0.0

package/src/motion3/lenient.js

@@ -0,0 +1,127 @@
+// Mechanical input mistakes are fixed, not refused, when the fix cannot change what was meant; each
+// fix is one short note the answer carries in output.adjusted (commands/motion3.js). Refused as before:
+// anything that changes timing or meaning (keys past the clip, tol on above, a window wholly past it).
+//   relaxSpec        on the expanded spec before validation (pipeline.js): a goal window partly past the
+//                    clip is cut to it; an object key with only pos takes the turn of the key before it
+//                    (else after it, else its scene pose: rot for a free entry, aim for a carry so the
+//                    arm picks the roll); a rot of length strictly between 0.5 and 2 is normalized
+//   clampProbe       a probe window partly past the take is cut to it (probes.js)
+//   fitEvery         a position probe's every grows to fit its 16 rows (probes.js)
+//   clampFrames      contact-sheet frames past the range are pulled into it (studio-motion-visual.js)
+//   normalizeCompileArgs  install spellings ("always", "if_clean", ...) and repair: { rounds: 0 } / true
+//                    (the registry's normalizeArgs, before the schema check)
+import { quatFromMat } from "./compiler/math.js";
+import { groupsOf } from "./scene.js";
+import { isCarried } from "./carried.js";
+import { isFree } from "./free-motion.js";
+
+const fmtRange = r => `[${r[0]},${r[1]}]`;
+/** Adds note to notes once (search trials expand the same spec again). */
+const note = (notes, text) => { if (notes && !notes.includes(text)) notes.push(text); };
+
+/** [f0, f1] cut to 0..last when it overlaps it; null when nothing is left or it is not a frame range. */
+function clampRange(range, last) {
+	if (!(Array.isArray(range) && range.length === 2 && range.every(Number.isInteger) && range[0] <= range[1])) return null;
+	const lo = Math.max(0, range[0]), hi = Math.min(last, range[1]);
+	return lo <= hi ? [lo, hi] : null;
+}
+
+/** goals[].at partly outside 0..frames-1 is cut to the clip; a window wholly outside is left for validation to refuse. */
+function relaxGoals(spec, notes) {
+	if (!Array.isArray(spec.goals) || !Number.isInteger(spec.frames)) return;
+	const last = spec.frames - 1;
+	spec.goals.forEach((g, i) => {
+		if (!g || typeof g !== "object" || !Array.isArray(g.at)) return;
+		const cut = clampRange(g.at, last);
+		if (!cut || (cut[0] === g.at[0] && cut[1] === g.at[1])) return;
+		note(notes, `goals[${i}]${g.name ? ` "${g.name}"` : ""} at ${fmtRange(g.at)} -> ${fmtRange(cut)}: the clip is 0..${last}`);
+		g.at = cut;
+	});
+}
+
+const turnOf = k => (k.rot !== undefined ? { rot: k.rot } : { aim: k.aim, ...(k.roll !== undefined ? { roll: k.roll } : {}), ...(k.lean !== undefined ? { lean: k.lean } : {}) });
+const hasTurn = k => k && (k.rot !== undefined || k.aim !== undefined);
+const bare = k => k && typeof k === "object" && !Array.isArray(k) && !hasTurn(k) && k.roll === undefined && k.lean === undefined;
+
+/** A key that gives pos only holds the turn it has: the key before it, else after it, else the scene pose. */
+function fillTurns(id, o, scene, notes) {
+	const keys = o.keys.map((k, i) => ({ k, i })).filter(({ k }) => k && Number.isInteger(k.f)).sort((a, b) => a.k.f - b.k.f);
+	const missing = keys.filter(({ k }) => bare(k));
+	if (!missing.length) return;
+	const rest = scene?.objects?.[id] ?? groupsOf(scene ?? {})[id];
+	const fromRest = rest ? (isCarried(o) ? { aim: [rest.R[0][1], rest.R[1][1], rest.R[2][1]].map(v => Math.round(v * 1e4) / 1e4) } : { rot: quatFromMat(rest.R) }) : null;
+	// sources are the keys that gave a turn, so a filled key never passes its fill on
+	const given = keys.filter(e => hasTurn(e.k)), held = [], restIdx = [];
+	for (const { k, i } of missing) {
+		const from = given.filter(e => e.k.f < k.f).at(-1) ?? given.find(e => e.k.f > k.f);
+		if (from) { Object.assign(k, turnOf(from.k)); held.push(i); }
+		else if (fromRest) { Object.assign(k, fromRest); restIdx.push(i); }
+	}
+	if (held.length) note(notes, `objects.${id}.keys[${held.join(",")}] had no rot or aim: each holds the turn of the nearest key before it (else after)`);
+	if (restIdx.length) note(notes, `objects.${id}.keys[${restIdx.join(",")}] had no rot or aim: ${fromRest.aim ? `+Y as in the scene, aim [${fromRest.aim}]` : "turned as in the scene"}`);
+}
+
+/** A rot that is a quaternion off unit length (strictly between 0.5 and 2) is normalized. */
+function normalizeRots(id, o, notes) {
+	o.keys.forEach((k, i) => {
+		if (!Array.isArray(k?.rot) || k.rot.length !== 4 || !k.rot.every(Number.isFinite)) return;
+		const n = Math.hypot(...k.rot);
+		if (Math.abs(n - 1) <= 0.01 || n <= 0.5 || n >= 2) return;
+		k.rot = k.rot.map(v => v / n);
+		note(notes, `objects.${id}.keys[${i}].rot had length ${n.toFixed(3)}: normalized`);
+	});
+}
+
+/**
+ * relaxSpec(spec, scene, notes): the fixes above, in place on the expanded spec (a plain JSON copy the
+ * compile measures; the stored spec stays as sent). notes collects one line per fix.
+ */
+export function relaxSpec(spec, scene, notes) {
+	if (!spec || typeof spec !== "object") return spec;
+	relaxGoals(spec, notes);
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		if (!o || typeof o !== "object" || !Array.isArray(o.keys) || !(isCarried(o) || isFree(o))) continue;
+		fillTurns(id, o, scene, notes);
+		normalizeRots(id, o, notes);
+	}
+	return spec;
+}
+
+/** A probe window cut to the take (frames: one frame or [f0, f1]); null (refused) when nothing is left. */
+export function clampProbe(frames, last, at, notes) {
+	const range = Number.isInteger(frames) ? [frames, frames] : frames, cut = clampRange(range, last);
+	if (cut && (cut[0] !== range[0] || cut[1] !== range[1])) note(notes, `${at}.frames ${fmtRange(range)} -> ${fmtRange(cut)}: the take is 0..${last}`);
+	return cut;
+}
+
+/** The every a position probe needs to answer at most max rows over span frames (the asked one if it fits). */
+export function fitEvery(every, span, max, at, notes) {
+	if (Math.ceil(span / every) <= max) return every;
+	const fit = Math.ceil(span / max);
+	note(notes, `${at}.every ${every} -> ${fit}: a position probe answers at most ${max} rows`);
+	return fit;
+}
+
+/** Contact-sheet frames pulled into lo..hi, in order, each once: { frames, adjusted? }. */
+export function clampFrames(frames, [lo, hi]) {
+	const outside = frames.filter(f => f < lo || f > hi);
+	const kept = [...new Set(frames.map(f => Math.min(hi, Math.max(lo, f))))].sort((a, b) => a - b);
+	return outside.length ? { frames: kept, adjusted: `frames ${outside.join(", ")} lie outside ${lo}..${hi}: drawn at ${kept.filter(f => f === lo || f === hi).join(", ")}` } : { frames: kept };
+}
+
+const INSTALL_WORDS = { always: true, yes: true, true: true, on: true, never: "never", no: "never", false: "never", off: "never", none: "never",
+	ifclean: "ifClean", whenclean: "ifClean", onlyifclean: "ifClean", clean: "ifClean" };
+
+/** motion.compile args with the obvious other spellings turned into the declared ones (meaning unchanged). */
+export function normalizeCompileArgs(args) {
+	if (!args || typeof args !== "object" || Array.isArray(args)) return args;
+	let out = args;
+	if (typeof args.install === "string" && args.install !== "ifClean" && args.install !== "never") {
+		const word = INSTALL_WORDS[args.install.toLowerCase().replace(/[^a-z]/g, "")];
+		if (word !== undefined) out = { ...out, install: word };
+	}
+	if (args.repair === true) out = { ...out, repair: {} };
+	else if (args.repair === false || (args.repair && typeof args.repair === "object" && args.repair.rounds === 0 && Object.keys(args.repair).length === 1))
+		out = Object.fromEntries(Object.entries(out).filter(([k]) => k !== "repair"));
+	return out;
+}

package/src/motion3/object-keys.js

@@ -0,0 +1,236 @@
+// C14. Held-object keys: spec.objects[id].keys = [{ f, pos, rot }] on a carry entry. Each key is
+// the world pose of the object's root (the group root for a group id, else the body: its base
+// pivot, rot a quaternion [x, y, z, w]) at absolute frame f, grab <= f <= release.
+//   between keys    a cubic Hermite on pos and the same in rotation-vector space on rot (squad
+//                   like), Catmull-Rom tangents through inner keys, zero at the first and last key
+//   around the span the hand blends from the plain carry into the keyed span over KEY_BLEND frames
+//                   (inside grab..release; smoothstep), so nothing jumps
+//   the object leads the hand: compile.js asks holdHook for the palm frame the keys put the grip
+//                   at, palm = key o attach^-1, and pose.js solves the hand to it (compiler/hold.js)
+// The object itself is still drawn in the hand (object-pose.js): the residual is what the arm
+// and the wrist could not reach, and QA reports it (qa/key-checks.js).
+import { isCarried, carriedPose, compose, relative } from "./carried.js";
+import { groupsOf } from "./scene.js";
+import { restState } from "./compiler/skeleton.js";
+import { add, scale, sub, apply, T, matFromQuat, quatFromMat } from "./compiler/math.js";
+import { qmul, qconj, qlog, qexp, qrot, qdot, qnorm } from "./compiler/quat.js";
+import { keyRots, leanPos } from "./key-aim.js";
+import { holdCost } from "./compiler/hold.js";
+import { polePlan, smoothPath, smoothed } from "./hold-plan.js";
+import { secondGrip, secondHold, gripGate } from "./second-hand.js";
+import { SIDES } from "./compiler/pose.js";
+import { chooseGrip, between, thinBody } from "./grip-choice.js";
+
+/** Frames over which the hand blends into and out of the keyed span. */
+export const KEY_BLEND = 8;
+// the frames a hand takes to turn into a chosen grip before its grab and out of it after its release (grip-choice.js)
+const GRAB_EASE = 12;
+
+const smooth = x => x * x * (3 - 2 * x);
+/** [grab, release] in absolute frames of `out` (object-pose.js spanOf, kept here to stay out of its import cycle). */
+const spanIn = (out, o) => { const map = f => (out.timeMap ? Math.round(out.timeMap(f)) : f); return [map(o.grab ?? 0), o.release === undefined ? out.frameCount - 1 : map(o.release)]; };
+const invert = p => { const Rt = T(p.R); return { pos: scale(apply(Rt, p.pos), -1), R: Rt }; };
+
+/** The keys of entry o as a curve: times (after a retime), positions, quaternions on one hemisphere (aim keys resolved: key-aim.js), tangents. */
+export function curveOf(o, map, plain, strain, top = 0) {
+	const keys = [...o.keys].sort((a, b) => a.f - b.f), t = keys.map(k => map(k.f)), q = [];
+	const rots = keyRots(keys, i => plain(t[i]), strain && ((i, r) => strain(t[i], leanPos(keys[i], r, top), r, keys[i].lean ? { shoulder: true } : undefined)));
+	const p = keys.map((k, i) => leanPos(k, qnorm(rots[i]), top).slice());
+	for (const r of rots) { const n = qnorm(r); q.push(q.length && qdot(q[q.length - 1], n) < 0 ? n.map(v => -v) : n); }
+	const last = keys.length - 1, rate = i => scale(qlog(qmul(qconj(q[i]), q[i + 1])), 1 / (t[i + 1] - t[i]));
+	const tangent = (i, of) => (i === 0 || i === last ? [0, 0, 0] : scale(add(scale(of(i), t[i] - t[i - 1]), scale(of(i - 1), t[i + 1] - t[i])), 1 / (t[i + 1] - t[i - 1])));
+	const m = p.map((_, i) => tangent(i, j => scale(sub(p[j + 1], p[j]), 1 / (t[j + 1] - t[j])))), w = q.map((_, i) => tangent(i, rate));
+	return { t, p, q, m, w, rots };
+}
+
+const curves = new WeakMap();
+/**
+ * The key curve of spec.objects[id] in `out` (cached per compile result, time map and baked
+ * channels: an aim key turns from the plain carry at its frame, and one without roll takes the
+ * roll the arm holds there most easily).
+ */
+export function curveIn(out, id) {
+	if (!curves.has(out)) curves.set(out, new Map());
+	const cache = curves.get(out), map = out.timeMap, baked = out.baked, had = cache.get(id);
+	if (!had || had.map !== map || had.baked !== baked) {
+		const hold = out.ctx.hold, solved = new Map(), at = t => { const f = Math.round(t); if (!solved.has(f)) solved.set(f, hold.plainFrame(f).s); return solved.get(f); };
+		const plain = t => quatFromMat(hold.carryOn(id, at(t)).R), strain = (t, pos, q, opts) => hold.strainOn(id, at(t), { pos, R: matFromQuat(q) }, opts);
+		cache.set(id, { map, baked, curve: curveOf(out.ctx.spec.objects[id], f => (map ? map(f) : f), plain, strain, 2 * (out.ctx.scene?.objects?.[id]?.half?.[1] ?? 0)) });
+	}
+	return cache.get(id).curve;
+}
+
+/** World pose { pos, R } the keys ask for at absolute frame f (held at the first / last key outside them). */
+export function keyedPose({ t, p, q, m, w }, f) {
+	const n = t.length;
+	if (n === 1 || f <= t[0]) return { pos: p[0].slice(), R: matFromQuat(q[0]) };
+	if (f >= t[n - 1]) return { pos: p[n - 1].slice(), R: matFromQuat(q[n - 1]) };
+	let i = 0;
+	while (f > t[i + 1]) i++;
+	const h = t[i + 1] - t[i], u = (f - t[i]) / h, u2 = u * u, u3 = u2 * u;
+	const h00 = 2 * u3 - 3 * u2 + 1, h10 = u3 - 2 * u2 + u, h01 = -2 * u3 + 3 * u2, h11 = u3 - u2;
+	const pos = add(add(scale(p[i], h00), scale(m[i], h * h10)), add(scale(p[i + 1], h01), scale(m[i + 1], h * h11)));
+	// rotation: q_i exp(v), v a Hermite in q_i's frame from 0 to the step to q_i+1 (the end tangent turned into that frame)
+	const step = qmul(qconj(q[i]), q[i + 1]), d = qlog(step);
+	const v = add(add(scale(d, h01), scale(w[i], h * h10)), scale(qrot(step, w[i + 1]), h * h11));
+	return { pos, R: matFromQuat(qmul(q[i], qexp(v))) };
+}
+
+/**
+ * 0..1: how much the keys lead the hand at absolute frame f (1 from the first to the last key).
+ * After the last key the hand eases out over KEY_BLEND frames even when the release comes sooner:
+ * the rest of the ease runs past the release (holdHook easeOut), so the arm does not snap.
+ */
+function leadWeight(curve, [grab, release], f) {
+	const t0 = curve.t[0], t1 = curve.t[curve.t.length - 1];
+	if (f < grab || f > release) return 0;
+	if (f >= t0 && f <= t1) return 1;
+	const b = f < t0 ? Math.min(KEY_BLEND, t0 - grab) : KEY_BLEND, gap = f < t0 ? t0 - f : f - t1;
+	return b > 0 && gap < b ? smooth(1 - gap / b) : 0;
+}
+
+/** The keyed carry entries: [[id, entry]]. */
+export const keyedEntries = spec => Object.entries(spec.objects ?? {}).filter(([, o]) => isCarried(o) && o.keys?.length);
+
+/**
+ * The hooks a compile needs when some carry has keys (else null): lead(k, f, s, c) -> { w,
+ * palm, measure, pole? } | null for pose.js hooks.hold (the holding hand, or a left hand anchored
+ * to the carry: second-hand.js), and attach(id) -> the object in the palm frame (the
+ * plain carry's offset: at/along, or the grab-frame offset solved without the keys, so the keys
+ * never feed back into it). For aim keys (key-aim.js): plainFrame(f) solves frame f without the
+ * keys (solveLed(f) with them, the second hands left out: what a second hand's roll is planned
+ * on), carryOn(id, s) is where the plain carry holds id on such a pose (where an aim key turns
+ * from) and strainOn(id, s, pose) the arm's cost of holding id at world pose { pos, R } there
+ * (compiler/hold.js holdCost, the roll of an aim key without one).
+ */
+export function holdHook(ctx, out, solvePlain, solveLed) {
+	const { sk, spec, scene } = ctx, held = keyedEntries(spec);
+	if (!held.length) return null;
+	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }), attached = new WeakMap(), attaching = new Set();
+	const restAt = (id, f) => ctx.restingAt?.(id, f) ?? scene?.objects?.[id] ?? groupsOf(scene)[id];
+	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no keyed wrist at
+	// the grab) keeps the grip its keyed path holds most comfortably (grip-choice.js), solved on the plain frames with the
+	// body read at rest; a box keeps the grip grip.js gives it at the grab
+	const choices = new WeakMap(), mapped = f => (out.timeMap ? Math.round(out.timeMap(f)) : f);
+	// chosen once per compile (the first bake): the fixes' rebakes move the body a little, the carry's keys not at all
+	const chosen = id => {
+		if (!choices.has(out)) choices.set(out, new Map());
+		const cache = choices.get(out), o = spec.objects[id], k = spec.props?.[o.prop]?.hand, grab = spanIn(out, o)[0], b = out.baked ?? {};
+		if (cache.has(id)) return cache.get(id);
+		cache.set(id, null);
+		const free = k && o.at === undefined && o.along === undefined && (o.grab !== undefined || !scene?.objects?.[id]) && thinBody(scene, id) && !(spec.fits ?? []).some(fit => fit.side === k && fit.orient === false)
+			&& !["wtwist", "wflex"].some(ch => Math.abs(b[`${ch}_${k}`]?.[grab] ?? 0) > 1e-3)
+			// keys that start after the grab: the body rides the hand from where it rests, which only today's grip meets exactly
+			&& mapped(Math.min(...o.keys.map(key => key.f))) <= grab;
+		if (!free) return null;
+		attaching.add(id);
+		try { cache.set(id, chooseGrip({ sk, o, side: SIDES[k], grab, rest: restAt(id, grab), plain: f => solvePlain(f).s, palmOf: s => palmOf(o, s), map: mapped })); } finally { attaching.delete(id); }
+		return cache.get(id);
+	};
+	const attach = id => {
+		if (!attached.has(out.baked)) attached.set(out.baked, new Map());
+		const cache = attached.get(out.baked), o = spec.objects[id];
+		if (cache.has(id)) return cache.get(id);
+		const picked = chosen(id);
+		if (picked && picked.name !== "today") { cache.set(id, picked.offset); return picked.offset; }
+		const rest = scene?.objects?.[id] ?? groupsOf(scene)[id], group = !scene?.objects?.[id] && !!rest;
+		const keeps = o.at === undefined && o.along === undefined && (group || o.grab !== undefined);
+		// the grab frame solved without the keys: a left hand anchored on id reads it there (object-pose.js), where this offset puts it
+		attaching.add(id);
+		let s;
+		try { s = keeps ? solvePlain(spanIn(out, o)[0]).s : restState(sk); } finally { attaching.delete(id); }
+		const a = relative(palmOf(o, s), keeps ? ctx.restingAt?.(id, spanIn(out, o)[0]) ?? { pos: rest.pos, R: rest.R } : carriedPose(sk, spec, s, o));
+		cache.set(id, a);
+		return a;
+	};
+	const carryOn = (id, s) => compose(palmOf(spec.objects[id], s), attach(id));
+	const strainOn = (id, s, pose, opts) => { const o = spec.objects[id]; return holdCost(sk, s, SIDES[spec.props[o.prop].hand], compose(pose, invert(attach(id))), palmOf(o, s), opts); };
+	const heldAt = (id, o, f) => {
+		const curve = curveIn(out, id), w = leadWeight(curve, spanIn(out, o), f);
+		return w > 0 ? { w, palm: compose(keyedPose(curve, f), invert(attach(id))), measure: s => palmOf(o, s), comfort: o.keys.some(k => k.lean > 0) } : null;
+	};
+	// the elbow's planned path over the frames the keys lead (hold-plan.js), once per baked channels and time map
+	const plans = new WeakMap();
+	const planOf = (id, o) => {
+		if (!plans.has(out.baked)) plans.set(out.baked, new Map());
+		const cache = plans.get(out.baked), had = cache.get(id);
+		if (had && had.map === out.timeMap) return had.plan;
+		const [grab, release] = spanIn(out, o), frames = [];
+		for (let f = Math.max(0, grab); f <= Math.min(out.frameCount - 1, release); f++) if (leadWeight(curveIn(out, id), [grab, release], f) > 0) frames.push(f);
+		const plan = polePlan(sk, SIDES[spec.props[o.prop].hand], frames, f => ({ s: solvePlain(f).s, held: heldAt(id, o, f) }));
+		cache.set(id, { map: out.timeMap, plan });
+		return plan;
+	};
+	// a left hand anchored to a carry the right hand holds grips it too (second-hand.js): its roll about the object, planned over the frames like the elbow
+	let planning = false;
+	const gripAt = (id, s, c) => { const R = carryOn(id, s).R; return secondGrip(sk, spec, id, s, c, [R[0][1], R[1][1], R[2][1]]); };
+	const rollPlans = new WeakMap();
+	const rollsOf = (id, o) => {
+		if (!rollPlans.has(out.baked)) rollPlans.set(out.baked, new Map());
+		const cache = rollPlans.get(out.baked), had = cache.get(id);
+		if (had && had.map === out.timeMap) return had.plan;
+		const [grab, release] = spanIn(out, o), plan = new Map();
+		planning = true;
+		let run = [];
+		const flush = () => {
+			const x = smoothPath((i, r) => run[i].grip.cost(r), (i, r) => run[i].grip.point(r), run.map(g => g.grip.softmin())), gate = smoothed(run.map((g, i) => gripGate(g.grip, x[i])));
+			// then its elbow's path at those rolls, like the holding elbow's (hold-plan.js)
+			const arm = i => run[i].grip.arm(x[i]), th = smoothPath((i, t) => arm(i).at(t).cost, (i, t) => arm(i).at(t).elbow, run.map((_, i) => arm(i).best.th));
+			run.forEach((g, i) => plan.set(g.f, { roll: x[i], gate: gate[i], pole: arm(i).at(th[i]).pv }));
+			run = [];
+		};
+		for (let f = Math.max(0, grab); f <= Math.min(out.frameCount - 1, release); f++) {
+			const solved = leadWeight(curveIn(out, id), [grab, release], f) > 0 ? solveLed(f) : null, grip = solved && gripAt(id, solved.s, solved.c);
+			if (grip) run.push({ f, grip }); else if (run.length) flush();
+		}
+		if (run.length) flush();
+		planning = false;
+		cache.set(id, { map: out.timeMap, plan });
+		return plan;
+	};
+	// around its keys the hand holds a chosen grip: it turns into it over the GRAB_EASE frames before the grab, holds it from the
+	// grab until the keys lead, keeps it on the body where the last key left it, and turns out of it over the GRAB_EASE frames
+	// after the release (by time, not by a fit's weight, which an agent may key on in a frame), so nothing jumps
+	const gripAround = (id, o, f) => {
+		const pick = chosen(id);
+		if (!pick || pick.name === "today") return null;
+		const curve = curveIn(out, id), t0 = curve.t[0], t1 = curve.t[curve.t.length - 1], [grab, release] = spanIn(out, o);
+		if (f >= t0 && f <= t1) return null;
+		// the elbow takes the planned pole of the nearest keyed frame (hold-plan.js), so it does not swing at the span's ends
+		// the grip on the body where the first key puts it (an aim key's roll is picked for this grip), so the reach meets the keys
+		const on = keyedPose(curve, f < t0 ? t0 : t1), grip = compose(on, invert(pick.offset)), measure = s => palmOf(o, s), pole = planOf(id, o).get(Math.round(f < t0 ? t0 : t1));
+		if (f < grab || f > release) { const w = smooth(Math.max(0, 1 - (f < grab ? grab - f : f - release) / GRAB_EASE)); return w > 1e-3 ? { w, palm: grip, measure, pole } : null; }
+		const h = heldAt(id, o, f);
+		return { w: 1, palm: h ? { pos: add(scale(grip.pos, 1 - h.w), scale(h.palm.pos, h.w)), R: between(grip.R, h.palm.R, h.w) } : grip, measure, pole };
+	};
+	// a release within KEY_BLEND frames of the last key: the hands finish easing out of the keys after it (weight from the last
+	// key), the holding hand from the palm they gave it at the release (the object stays where it was let go), each hand with
+	// the elbow pole (and the second hand the roll) planned for the release frame
+	const pastRelease = (id, o, f) => {
+		const curve = curveIn(out, id), t1 = curve.t[curve.t.length - 1], release = spanIn(out, o)[1];
+		return f > release && f - t1 < KEY_BLEND ? { curve, release, w: smooth(1 - (f - t1) / KEY_BLEND) } : null;
+	};
+	const easeOut = (id, o, f) => {
+		const e = pastRelease(id, o, f);
+		return e && { w: e.w, palm: compose(keyedPose(e.curve, e.release), invert(attach(id))), measure: s => palmOf(o, s), pole: planOf(id, o).get(e.release) };
+	};
+	// the hand that holds a keyed carry follows its keys
+	const lead = (k, f, s, c) => {
+		for (const [id, o] of held) {
+			const pre = spec.props?.[o.prop]?.hand === k ? gripAround(id, o, f) ?? easeOut(id, o, f) : null;
+			if (pre) return pre;
+			const h = spec.props?.[o.prop]?.hand === k ? heldAt(id, o, f) : null;
+			if (h) return { ...h, pole: planOf(id, o).get(f) };
+			const after = k === "l" && s && !planning ? pastRelease(id, o, f) : null;
+			const w = k === "l" && s && !planning ? leadWeight(curveIn(out, id), spanIn(out, o), f) || (after?.w ?? 0) : 0, grip = w > 0 ? gripAt(id, s, c) : null;
+			const planned = grip && rollsOf(id, o).get(after ? after.release : f), roll = planned?.roll ?? grip?.softmin();
+			if (grip) return secondHold(grip, w, roll, planned?.gate ?? gripGate(grip, roll), planned?.pole ?? grip.arm(roll).best.pole);
+		}
+		return null;
+	};
+	// the grip (compiler/grip.js) reads where a keyed carry's span and keys begin, after a retime
+	const firstKey = id => { const t = Math.min(...spec.objects[id].keys.map(k => k.f)); return out.timeMap ? Math.round(out.timeMap(t)) : t; };
+	// the grips chosen for keyed carries (observations.wrist reads them): [{ id, hand, name, cost, today }]
+	const grips = () => held.map(([id, o]) => { const p = chosen(id); return p && { id, hand: spec.props[o.prop].hand, name: p.name, cost: p.cost, today: p.today }; }).filter(Boolean);
+	return { lead, attach, attaching: id => attaching.has(id), plainFrame: solvePlain, carryOn, strainOn, span: id => spanIn(out, spec.objects[id]), firstKey, grips };
+}

package/src/motion3/object-pose.js

@@ -0,0 +1,182 @@
+// C3. Where a scene object or a group is at a frame: the one place refs, probes, goals, the
+// timeline, the take and QA read object poses from. See docs/motion-api-v3.1.md (C3, 7.1, 7.2).
+//
+// The group (an Empty) is the unit. spec.objects[id] may name a body or a group:
+//   hinge  { pivot, axis, channel }                        turns the record (a group: the whole group
+//                                                          about the group root) by a keyed angle
+//   carry  { prop, grab?, release?, at?, along?, visible?, level? } the record rides prop `prop`'s hand
+//   switch { visible?, level? }                            moves nothing: shows/hides and dims the record (C15)
+// A carried or hinged group gets ONE track, on the group root (take.objects[groupId]); its parts
+// follow through the parent carry that already exists in src/object-travel.js (ancestorsOf /
+// ownTravelMatrix). There are no per-part tracks. While the group is in hand (grab..release) its
+// track is in world space and the carry from the group's own parent (a table) is cut, so nothing
+// is carried twice (the take's `hold` flags, object-travel.js).
+//   f < grab              the scene pose
+//   grab <= f <= release  follows the prop's hand; without at/along it keeps the transform it had
+//                         against the palm axes at grab (no jump); at/along pin an offset (a group: its root, C15)
+//   f > release           frozen at the release pose
+//   no grab: in hand from frame 0; no release: in hand to the end (PR #14 behaviour)
+//   keys (C14, object-keys.js): the object leads and the hand follows; the object is still drawn
+//                         in the hand, so what the hand cannot reach shows as a residual (QA)
+//   follow { follow, offset?, aim?, visible?, level? }   rides a point of the body every frame (C16, follow.js)
+//   free   { keys?, fall?, visible?, level? }             moves on its own: keys, falls (C17, free-motion.js); a carry's
+//                         fall puts it where it lands before grab (the hand finds it there) or after release
+// Carried objects are OBSTACLES at every frame, at their pose that frame (qa/object-checks.js);
+// a follow entry is none.
+import { isCarried, isFollow, carriedPose, compose, relative, movesRecord } from "./carried.js";
+import { followPose } from "./follow.js";
+import { groupsOf } from "./scene.js";
+import { solveFrame } from "./compiler/compile.js";
+import { channelsAt } from "./compiler/channels.js";
+import { resolveBone } from "./bones.js";
+import { isFree, freePoseAt, beforeGrab, afterRelease } from "./free-motion.js";
+
+/**
+ * Body ids that make up `id` in a motionScene: [id] for a body (plus any bodies parented under
+ * it), every body under it for a group, [] when the scene knows no such id.
+ * @returns {string[]}
+ */
+export function partsOf(scene, id) {
+	const objects = scene?.objects ?? {};
+	return Object.keys(objects).filter(k => k === id || objects[k].ancestors?.includes(id));
+}
+
+/**
+ * True while spec.objects entry `o` holds its record in a hand at absolute frame f
+ * (grab <= f <= release; a missing grab is 0, a missing release the last frame).
+ */
+export function inHandAt(o, f) {
+	return isCarried(o) && f >= (o.grab ?? 0) && (o.release === undefined || f <= o.release);
+}
+
+/** The scene pose { pos, R } of a body or a group root, or null. */
+function restPose(scene, id) {
+	return scene?.objects?.[id] ?? groupsOf(scene)[id] ?? null;
+}
+
+/** The spec.objects key that moves body or group `id`: itself or its nearest group with a carry, follow or hinge entry (a switch moves nothing), or null. */
+function moverOf(spec, scene, id) {
+	return [id, ...(scene?.objects?.[id]?.ancestors ?? groupsOf(scene)[id]?.ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])) ?? null;
+}
+
+/** [grab, release] of a carried entry in absolute frames of `out` (after a retime). */
+export function spanOf(out, o) {
+	const map = f => (out.timeMap ? Math.round(out.timeMap(f)) : f);
+	return [map(o.grab ?? 0), o.release === undefined ? out.frameCount - 1 : map(o.release)];
+}
+
+/** Without at/along a grabbed body, and a group, keeps its grab-frame palm offset; at/along pin one (a kit root, C15). */
+const keepsOffset = (scene, id, o) => o.at === undefined && o.along === undefined && ((!scene?.objects?.[id] && !!groupsOf(scene)[id]) || o.grab !== undefined);
+
+const solved = new WeakMap(), poses = new WeakMap();
+
+/** What free-motion.js reads of a compile result: the spec, the scene and the time map. */
+const freeCtx = out => ({ spec: out.ctx.spec, scene: out.ctx.scene, timeMap: out.timeMap });
+
+/**
+ * Where a carried body or group `id` (or a part of one) rests at absolute f before its grab, and where the hand took
+ * it from after: its scene pose, or where a fall before the grab left it (C17). null when no carry moves it.
+ */
+export function restingAt(out, id, f) {
+	const { spec, scene } = out.ctx, mover = moverOf(spec, scene, id), o = spec.objects?.[mover];
+	if (!isCarried(o)) return null;
+	const root = beforeGrab(freeCtx(out), mover, o, f, spanOf(out, o)[0]);
+	return root && (mover === id ? root : compose(root, relative(restPose(scene, mover), restPose(scene, id))));
+}
+
+/** The solved frame at absolute f: out.frames, or solved once on demand outside a window. */
+function frameAt(out, f) {
+	const own = out.frames[f - (out.f0 ?? 0)];
+	if (own) return own;
+	if (!solved.has(out)) solved.set(out, new Map());
+	const cache = solved.get(out);
+	if (!cache.has(f)) cache.set(f, solveFrame(out.ctx, channelsAt(out.baked, f), f));
+	return cache.get(f);
+}
+
+/** Pose of the record a carried entry moves at in-hand frame f, on that frame's pose s. */
+function carriedOn(out, id, o, f, s) {
+	const { sk, spec, scene } = out.ctx;
+	if (!keepsOffset(scene, id, o)) return carriedPose(sk, spec, s, o);
+	// keyed (object-keys.js): the grab-frame offset solved without the keys, which the hand followed. While that
+	// grab frame is solved (a hand anchored on the object reads it), the object is where the offset puts it: at rest.
+	if (o.keys?.length && out.ctx.hold) return out.ctx.hold.attaching(id) ? restPose(scene, id) : compose(carriedPose(sk, spec, s, { prop: o.prop }), out.ctx.hold.attach(id));
+	const palm = st => carriedPose(sk, spec, st, { prop: o.prop }), grab = spanOf(out, o)[0];
+	return compose(palm(s), relative(palm(grab === f ? s : frameAt(out, grab).s), restingAt(out, id, grab) ?? restPose(scene, id)));
+}
+
+/** Pose of the record a carried entry moves, cached on the solved frame. */
+function carriedAt(out, id, o, f) {
+	const fr = frameAt(out, f);
+	if (!poses.has(fr)) poses.set(fr, new Map());
+	const cache = poses.get(fr);
+	if (!cache.has(id)) cache.set(id, carriedOn(out, id, o, f, fr.s));
+	return cache.get(id);
+}
+
+/**
+ * World pose { pos, R } of the record spec.objects[id] moves (a body or a group root) at
+ * absolute frame f: carried, hinged (out.ctx.objectsAt for a body; the group root turned by
+ * the same hinge) or still. null for an id the scene does not know. `now` ({ s, diag, c }) is
+ * frame f while the compiler solves it (an object anchor): its pose so far stands in for the
+ * solved frame, so the carrying hand must already be solved (compiler/anchors.js).
+ */
+export function rootPoseAt(out, id, f, now = null) {
+	const { spec, scene } = out.ctx, o = movesRecord(spec.objects?.[id]) ? spec.objects[id] : undefined, rest = restPose(scene, id);
+	if (isFollow(o)) return followPose(now ? { ...out, f0: f, frames: [now] } : out, o, f);
+	if (isCarried(o) && (rest || !keepsOffset(scene, id, o))) {
+		const [grab, release] = spanOf(out, o), g = Math.max(grab, Math.min(f, release));
+		if (f < grab && rest) return restingAt(out, id, f);
+		const after = f > release ? afterRelease(freeCtx(out), id, o, f, release, carriedAt(out, id, o, release)) : null;
+		if (after) return after;
+		return now && g === f ? carriedOn(out, id, o, f, now.s) : carriedAt(out, id, o, g);
+	}
+	if (!rest) return null;
+	if (isFree(o)) return freePoseAt(freeCtx(out), id, f);
+	if (o && scene.objects[id]) return out.ctx.objectsAt(f)[id];
+	if (o) { const part = partsOf(scene, id)[0], box = out.ctx.objectsAt(f)[part]; return compose(box, relative(scene.objects[part], rest)); }
+	return { pos: rest.pos, R: rest.R };
+}
+
+/**
+ * The boxes of `id` at absolute frame f of a compile result `out` (out.ctx.scene, out.ctx.spec):
+ * [{ id: partId, pos, R, half }] for a body ([its own box]) or a group (every part box, moved by
+ * the group root's pose at f). null when f is outside the compiled window (out.f0 ..
+ * out.f0 + out.frames.length - 1) or the scene has no such id.
+ * @returns {{ id: string, pos: number[], R: number[][], half: number[] }[] | null}
+ */
+export function objectBoxesAt(out, id, f) {
+	const fr = out.frames?.[f - (out.f0 ?? 0)], scene = out.ctx.scene, parts = partsOf(scene, id);
+	if (!fr || !parts.length) return null;
+	return parts.map(p => { const pose = objectPoseAt(out, p, f); return { id: p, pos: pose.pos, R: pose.R, half: scene.objects[p].half }; });
+}
+
+/**
+ * The hand ("l" | "r") body or group `id` rides at absolute frame f, so a pose of that frame needs that arm solved
+ * first: a carry while in hand (grab..release; after release it is frozen at a frame already solved), a follow on a
+ * joint of that arm or a point of its prop. null otherwise.
+ */
+export function handOf(out, id, f) {
+	const { spec, scene, sk } = out.ctx, entry = spec.objects?.[moverOf(spec, scene, id)];
+	if (isCarried(entry)) { const [grab, release] = spanOf(out, entry); return f >= grab && f <= release ? spec.props?.[entry.prop]?.hand ?? null : null; }
+	if (!isFollow(entry)) return null;
+	const [kind, rest = ""] = String(entry.follow).split(/:(.*)/s);
+	if (kind === "prop") return spec.props?.[rest.split(".")[0]]?.hand ?? null;
+	const arm = (kind === "joint" || kind === "bone") && /^(Left|Right)(Arm|ForeArm|Hand)/.exec(resolveBone(sk, rest).bone ?? "");
+	return arm ? (arm[1] === "Left" ? "l" : "r") : null;
+}
+
+/**
+ * World pose { pos, R } of a body (its base pivot) or a group (its origin) at absolute frame f:
+ * the one pose object refs, probes, goals, QA and object anchors read. A carried or follow record
+ * is where it rides, a hinged one turned, any other at its scene pose. `now` as rootPoseAt.
+ * null for an id the scene does not know.
+ */
+export function objectPoseAt(out, id, f, now = null) {
+	const { spec, scene } = out.ctx, rest = restPose(scene, id), mover = moverOf(spec, scene, id), entry = spec.objects?.[mover];
+	if (!rest) return null;
+	if (isCarried(entry) || isFollow(entry) || isFree(entry)) { const root = rootPoseAt(out, mover, f, now); return root && compose(root, relative(restPose(scene, mover), rest)); }
+	if (!mover) return { pos: rest.pos, R: rest.R };
+	if (scene.objects[id]) return out.ctx.objectsAt(f)[id] ?? rest;
+	return mover === id ? rootPoseAt(out, id, f) : compose(rootPoseAt(out, mover, f), relative(restPose(scene, mover), rest));
+}

package/src/motion3/object-tracks.js

@@ -0,0 +1,12 @@
+// Scene objects the installed takes animate (hinged doors and the like), for object-travel.js:
+// id -> { frameCount, characterId, pos: Float32Array(F*3), quat: Float32Array(F*4), hold?, vis? } across the whole cast
+// (characterId: whose take draws it, for motion.keyObject).
+export function objectTracksOf(motionOwner, characters = []) {
+	const tracks = new Map();
+	for (const character of characters) {
+		const take = motionOwner?.motionFor?.(character.id);
+		if (take?.schema !== "cozyclay.take.v3") continue;
+		for (const [id, track] of Object.entries(take.objects ?? {})) tracks.set(id, { frameCount: take.frameCount, characterId: character.id, ...track });
+	}
+	return tracks;
+}