cozyclay 2.1.1 → 3.0.0

package/src/motion3/grip-choice.js

@@ -0,0 +1,130 @@
+// The grip a keyed carry keeps (C18, lane pathgrip). Without at/along a carry keeps the palm-object transform of
+// its grab frame (object-keys.js attach), and nothing chose that grip: the hand met the object at whatever turn the
+// reach left it, and the keys then took the cup to the mouth with the wrist past its comfortable range on 9-47
+// frames in 6 of 8 bench S8 takes (50-58 deg of flex and 70 deg of forearm twist at the mouth). A person picks the
+// grip for where the object is going (end-state comfort, Rosenbaum), so for a keyed carry whose grip is free the
+// grab offset is chosen here over the carry's keyed path:
+//   cost      at the grab (the hand takes the grip on the body at rest) and along the keys, the arm's wrist need at
+//             the elbow the hold solve takes (arm-orient.js landscape) priced against the comfortable ranges
+//             (WRIST_COMFORT: z^2 inside, STEEP to the anatomical limits, OVER past them), plus REACH per squared
+//             centimetre the arm is short or folded (a residual QA reports) and BODY per squared centimetre the arm
+//             or the hand goes into the body (body.js)
+//   faithful  the keys as the compile resolves them (key-aim.js: an aim key without roll at the roll the arm's
+//             strain picks), priced every STEP frames; today's grip that keeps every frame comfortable stays
+//   search    from today's grip, turns of STEPS degrees about the palm axes (the fingers' line, the palm normal,
+//             the knuckle line) while the rough cost (the grab and KEYS keys, an aim key at the best of ROLLS rolls
+//             by the strain) drops; the fingers' point stays where the fit put it
+//   pick      the found grip only when its faithful cost beats today's by MARGIN or SHARE of it (no flip for less)
+// Deterministic. The hand comes into the grip on its reach and leaves it on its release (object-keys.js).
+import { sub, scale, norm, len, apply, mul, T, axisRot, matFromQuat, quatFromMat } from "./compiler/math.js";
+import { qmul, qrot, qdot, axisQuat, arcQuat, qlog, slerp } from "./compiler/quat.js";
+import { aimArm, holdCost } from "./compiler/hold.js";
+import { curveOf, keyedPose } from "./object-keys.js";
+import { landscape, ELBOW_REST, WRIST_COMFORT, WRIST_LIMITS } from "./compiler/arm-orient.js";
+import { bodyFor, segmentDepth } from "./body.js";
+import { reachAt, ELBOW_FOLD } from "./compiler/limbs.js";
+import { compose, relative } from "./carried.js";
+
+const THIN = 0.045, ROLLS = 4, KEYS = 8, STEPS = [30, 10], TRIES = 2, STEP = 4, MARGIN = 2, SHARE = 0.1, COMFORTABLE = 1.5, REACH = 20, BODY = 4, STEEP = 8, OVER = 400;
+// the palm frame's columns (carried.js carriedPose): the fingers' line, the palm normal, the knuckle line (reversed)
+const AXES = ["the fingers' line", "the palm normal", "the knuckle line"];
+const col = (R, i) => [R[0][i], R[1][i], R[2][i]];
+const invert = p => { const Rt = T(p.R); return { pos: scale(apply(Rt, p.pos), -1), R: Rt }; };
+const r2 = v => Math.round(v * 100) / 100;
+
+/** The rotation a fraction t of the way from A to B. */
+export function between(A, B, t) {
+	const a = quatFromMat(A);
+	let b = quatFromMat(B);
+	if (qdot(a, b) < 0) b = b.map(v => -v);
+	return matFromQuat(slerp(a, b, t));
+}
+
+/** Price of one wrist turn v (deg) against its comfortable range and anatomical limits. */
+function price(v, [clo, chi], [llo, lhi]) {
+	const c = v >= 0 ? chi : -clo, L = v >= 0 ? lhi : -llo, a = Math.abs(v);
+	if (a <= c) return (a / c) ** 2;
+	const e = (Math.min(a, L) - c) / Math.max(1e-6, L - c);
+	return 1 + STEEP * e * e + (a > L ? OVER * ((a - L) / L) ** 2 : 0);
+}
+
+/** The arm's comfort-priced cost of holding palm frame `palm` on pose s (the plain arm of `side`, `now` its palm frame there). */
+function comfortCost(sk, s, side, palm, now) {
+	const { goal, plane, wristAt } = aimArm(sk, s, side, palm, now, 1), W = wristAt(goal), land = landscape(sk, s, side, goal, W, plane, ELBOW_REST);
+	const arm = land.at(land.softmin()), I = sk.index, S = s.P[I[`${side}Arm`]];
+	const A = len(sub(s.P[I[`${side}ForeArm`]], S)), B = len(sub(s.P[I[`${side}Hand`]], s.P[I[`${side}ForeArm`]]));
+	const fold = Math.max(0, reachAt(A, B, ELBOW_FOLD) - len(sub(W, S))), body = bodyFor(sk);
+	const into = body ? Math.max(segmentDepth(body, sk, s, I[`${side}Arm`], S, arm.elbow), segmentDepth(body, sk, s, I[`${side}ForeArm`], arm.elbow, W), segmentDepth(body, sk, s, I[`${side}Hand`], W, palm.pos)) : 0;
+	return ["twist", "flex", "dev"].reduce((c, k) => c + price(arm.need[k], WRIST_COMFORT[k], WRIST_LIMITS[k]), 0) + REACH * ((land.miss * 100) ** 2 + (fold * 100) ** 2) + BODY * (into * 100) ** 2;
+}
+
+/** The rough cost of key `key` with offset A: a rot key at its rot; an aim key turned from where the carry holds it (key-aim.js), at its roll or at the best of ROLLS rolls by the arm's strain (hold.js holdCost, as the compile picks it), priced by priceOf. */
+function keyCost(sk, s, side, key, now, A, priceOf) {
+	if (key.aim === undefined) return priceOf({ pos: key.pos, R: matFromQuat(key.rot) });
+	const from = quatFromMat(compose(now, A).R), d = norm(key.aim), q0 = qmul(arcQuat(norm(qrot(from, [0, 1, 0])), d), from);
+	const pose = r => ({ pos: key.pos, R: matFromQuat(qmul(axisQuat(d, r), q0)) });
+	if (key.roll !== undefined) return priceOf(pose(key.roll));
+	let best = null;
+	for (let j = 0; j < ROLLS; j++) {
+		const p = pose(j * (360 / ROLLS) - 180), strain = holdCost(sk, s, side, compose(p, invert(A)), now);
+		if (!best || strain < best.strain) best = { p, strain };
+	}
+	return priceOf(best.p);
+}
+
+/**
+ * True when body or group `id` is thin (two half sizes under THIN m: a cup, a can, a bar, a handle); a group by its
+ * largest part (a cup with a handle is held by its cup). A box keeps the grip grip.js gives it at the grab.
+ */
+export function thinBody(scene, id) {
+	const parts = Object.entries(scene?.objects ?? {}).filter(([k, o]) => (k === id || o.ancestors?.includes(id)) && o.half);
+	if (!parts.length) return false;
+	const half = parts.map(([, o]) => o.half).reduce((m, h) => (h[0] * h[1] * h[2] > m[0] * m[1] * m[2] ? h : m));
+	const long = [0, 1, 2].reduce((a, i) => (half[i] > half[a] ? i : a), 0);
+	return [0, 1, 2].filter(i => i !== long).every(i => half[i] < THIN);
+}
+
+/** At most n of the keys, spread over them (the first and the last kept). */
+const spread = (keys, n) => (keys.length <= n ? keys : Array.from({ length: n }, (_, i) => keys[Math.round((i * (keys.length - 1)) / (n - 1))]));
+
+/** How the found rotation R differs from today's R0, in words: "today's grip turned 40 deg about the palm normal". */
+function named(R0, R) {
+	const v = qlog(quatFromMat(mul(T(R0), R))), deg = Math.round((2 * len(v) * 180) / Math.PI), i = [0, 1, 2].reduce((m, j) => (Math.abs(v[j]) > Math.abs(v[m]) ? j : m), 0);
+	return `today's grip turned ${deg} deg, mostly about ${AXES[i]}`;
+}
+
+/**
+ * chooseGrip({ sk, o, side, grab, rest, plain, palmOf, map }) -> { offset, name, cost, today }: the grab offset a
+ * keyed carry with a free grip keeps (see above). plain(f) solves frame f without keys, palmOf(s) is the carry's palm
+ * frame on a pose, rest the body's pose at the grab, map a key frame to its timeline frame.
+ */
+export function chooseGrip({ sk, o, side, grab, rest, plain, palmOf, map = f => f }) {
+	const solved = new Map(), at = f => { const g = Math.round(f); if (!solved.has(g)) { const s = plain(g); solved.set(g, { s, now: palmOf(s) }); } return solved.get(g); };
+	const { s: s0, now: now0 } = at(grab), keys = [...o.keys].sort((a, b) => a.f - b.f), some = spread(keys, KEYS);
+	const offsetOf = R => relative({ pos: now0.pos, R }, rest), held = (A, f, pose) => { const { s, now } = at(f); return comfortCost(sk, s, side, compose(pose, invert(A)), now); };
+	const grabCost = A => comfortCost(sk, s0, side, compose(rest, invert(A)), now0);
+	const rough = R => { const A = offsetOf(R); return grabCost(A) + some.reduce((sum, key) => { const { s, now } = at(map(key.f)); return sum + keyCost(sk, s, side, key, now, A, pose => held(A, map(key.f), pose)); }, 0); };
+	const faithful = R => {
+		const A = offsetOf(R), t0 = Math.round(map(keys[0].f)), t1 = Math.round(map(keys[keys.length - 1].f));
+		const curve = curveOf(o, map, t => quatFromMat(compose(at(t).now, A).R), (t, pos, q, opts) => { const { s, now } = at(t); return holdCost(sk, s, side, compose({ pos, R: matFromQuat(q) }, invert(A)), now, opts); }, 2 * (rest?.half?.[1] ?? 0));
+		let cost = grabCost(A), worst = cost;
+		for (let f = t0; f <= t1; f += STEP) { const c = held(A, f, keyedPose(curve, f)); cost += c; worst = Math.max(worst, c); }
+		return { A, cost, worst };
+	};
+	// today's grip that keeps every frame comfortable (each turn inside its range) stays as it is
+	const today = { name: "today", R: now0.R, ...faithful(now0.R) };
+	if (today.worst <= COMFORTABLE) return { offset: today.A, name: "today", cost: r2(today.cost), today: r2(today.cost) };
+	let cur = { R: now0.R, rough: rough(now0.R) };
+	for (const step of STEPS) {
+		for (let tries = 0, better = true; better && tries < TRIES; tries++) {
+			better = false;
+			for (const i of [0, 1, 2]) for (const sign of [1, -1]) {
+				const R = mul(axisRot(col(cur.R, i), sign * step), cur.R), c = rough(R);
+				if (c < cur.rough - 1e-6) { cur = { R, rough: c }; better = true; }
+			}
+		}
+	}
+	const found = cur.R === now0.R ? today : { name: named(now0.R, cur.R), ...faithful(cur.R) };
+	const pick = found.cost < today.cost - Math.max(MARGIN, SHARE * today.cost) ? found : today;
+	return { offset: pick.A, name: pick.name, cost: r2(pick.cost), today: r2(today.cost) };
+}

package/src/motion3/hold-plan.js

@@ -0,0 +1,157 @@
+// The arms' paths over a keyed span (C14, lane K8). What the arm does on a frame the keys lead
+// (the holding elbow's swivel, compiler/arm-orient.js; the second hand's roll about the object,
+// second-hand.js) is read as a cost per frame on the pose that frame starts from, and the path
+// minimises, over all those frames at once, the cost of each frame plus SMOOTH times the squared
+// acceleration of the point that choice moves (the elbow; the free end of the second hand): where
+// the cost barely cares the arm glides, where it does the arm goes where the wrist needs it. The
+// best choice alone can move 20 deg from one frame to the next while a bat whips through the
+// zone, and an arm that followed it would jerk (QA POP). Solved by NEWTON Gauss-Newton steps from
+// each frame's soft minimum, each a banded (5-diagonal) linear solve. Every frame reads the same
+// plan, so a frame still solves on its own (a windowed compile, a frame solved on demand) and the
+// same spec gives the same take.
+// The holding elbow's path never jumps (lane Q1, steadyPath). Where the cheap poles of two frames
+// in a row lie on either side of a ridge, smoothPath from each frame's soft minimum stays in a
+// local optimum that jumps across it (session 4db5d447, the follow-through: the elbow could hold
+// the bat down-forward to f43 and up-forward from f44, and the planned elbow went 22 cm in one
+// frame, QA POP and FLIP 78 deg). A path that jumps (jumpsIn) is solved again from the cheapest
+// path that never turns more than JUMP a frame (continuousPath, dynamic programming over the
+// poles), and if the cost pulls that back into a jump, with the smoothing BOOST times stronger
+// around it: the elbow goes over the ridge in a few frames (QA-17 run: at most 10 cm a frame,
+// the plane 26 deg a frame) and pays its strain there. A path that does not jump, and one these
+// do not free of its jump (the keys jerk the hand there), is the plan as before, bit for bit.
+import { holdLandscape } from "./compiler/hold.js";
+import { add, sub, scale, dot, angle, len } from "./compiler/math.js";
+
+const SMOOTH = 1000, NEWTON = 4, STEP = 0.03, MAX_STEP = 0.6, MIN_CURVE = 0.05, SIGMA = 2;
+// A jump: the pole turns more than JUMP deg in a frame while the elbow moves more than SPIKE times
+// as far as in the frames around and more than FLOOR m (QA POP's floor, accLimb). The continuous
+// path prices each turn TURN per squared radian and OVER_TURN past JUMP; BOOST, AROUND as above.
+const JUMP = 45, SPIKE = 2, FLOOR = 0.05, TURN = 10, OVER_TURN = 400, BOOST = 16, AROUND = 4;
+/** The poles continuousPath reads (radians from the landscape's th 0), 5 deg apart. */
+const POLE_GRID = Array.from({ length: 72 }, (_, i) => (2 * Math.PI * i) / 72 - Math.PI);
+
+/** Solve the symmetric 5-diagonal system A x = b; A[i][k] is the entry (i, i + k - 2). */
+function solveBand(A, b) {
+	const n = b.length, x = Array.from(b);
+	for (let i = 0; i < n; i++) {
+		for (let j = i + 1; j <= Math.min(i + 2, n - 1); j++) {
+			const m = A[j][i - j + 2] / A[i][2];
+			for (let k = i; k <= Math.min(i + 2, n - 1); k++) A[j][k - j + 2] -= m * A[i][k - i + 2];
+			x[j] -= m * x[i];
+		}
+	}
+	for (let i = n - 1; i >= 0; i--) {
+		for (let k = i + 1; k <= Math.min(i + 2, n - 1); k++) x[i] -= A[i][k - i + 2] * x[k];
+		x[i] /= A[i][2];
+	}
+	return x;
+}
+
+/**
+ * The angle per frame (radians, frames in a row) that minimises sum cost(i, x_i) + SMOOTH *
+ * sum weight_r |P(r) - 2 P(r+1) + P(r+2)|^2 with P(i) = point(i, x_i) (metres), from x0 (each
+ * frame's own best, unwrapped here so neighbours differ by less than half a turn); weight 1 when
+ * not given.
+ */
+export function smoothPath(cost, point, x0, weight = null) {
+	const n = x0.length, x = x0.slice();
+	for (let i = 1; i < n; i++) x[i] = x[i - 1] + Math.atan2(Math.sin(x[i] - x[i - 1]), Math.cos(x[i] - x[i - 1]));
+	for (let it = 0; it < NEWTON && n > 2; it++) {
+		const A = x.map(() => new Float64Array(5)), b = new Float64Array(n);
+		x.forEach((t, i) => {
+			const c0 = cost(i, t), cp = cost(i, t + STEP), cm = cost(i, t - STEP);
+			A[i][2] = Math.max(MIN_CURVE, (cp + cm - 2 * c0) / (STEP * STEP));
+			b[i] = -(cp - cm) / (2 * STEP);
+		});
+		// linearised: the point moves along tan = dP/dx
+		const P = x.map((t, i) => point(i, t)), tan = x.map((t, i) => scale(sub(point(i, t + STEP), point(i, t - STEP)), 1 / (2 * STEP)));
+		for (let r = 0; r + 2 < n; r++) {
+			const c = [1, -2, 1], acc = add(sub(P[r], scale(P[r + 1], 2)), P[r + 2]), k = weight ? 2 * SMOOTH * weight[r] : 2 * SMOOTH;
+			for (let p = 0; p < 3; p++) {
+				b[r + p] -= k * c[p] * dot(acc, tan[r + p]);
+				for (let q = 0; q < 3; q++) A[r + p][q - p + 2] += k * c[p] * c[q] * dot(tan[r + p], tan[r + q]);
+			}
+		}
+		const step = solveBand(A, b);
+		x.forEach((t, i) => { x[i] = t + Math.max(-MAX_STEP, Math.min(MAX_STEP, step[i])); });
+	}
+	return x;
+}
+
+/**
+ * The frames i where the path x jumps from frame i to i + 1: dir (a unit vector, the elbow's pole)
+ * turns more than JUMP degrees and the point (the elbow) moves more than SPIKE times as far as in
+ * the frame before or after, and more than FLOOR metres. A pole that turns while the arm is
+ * straight barely moves the elbow, and a swing moves it fast for several frames: neither is a jump.
+ */
+function jumpsIn(x, dir, point) {
+	const P = x.map((t, i) => point(i, t)), step = i => (i >= 0 && i + 1 < P.length ? len(sub(P[i + 1], P[i])) : 0);
+	return x.slice(1).map((t, i) => i).filter(i => step(i) > FLOOR && step(i) > SPIKE * Math.max(step(i - 1), step(i + 1)) && angle(dir(i, x[i]), dir(i + 1, x[i + 1])) > JUMP);
+}
+
+/**
+ * The path over the candidate angles `grid` that minimises sum cost(i, x_i) + TURN * sum a_i^2
+ * plus OVER_TURN * (a_i - JUMP)^2 past JUMP, a_i the turn (radians) of dir from frame i to i + 1
+ * (dynamic programming): the cheapest way through that never jumps, whichever valley it starts in.
+ */
+function continuousPath(cost, dir, n, grid) {
+	const K = grid.length, lim = JUMP * Math.PI / 180, C = [], U = [];
+	for (let i = 0; i < n; i++) { C.push(grid.map(t => cost(i, t))); U.push(grid.map(t => dir(i, t))); }
+	let total = C[0].slice();
+	const back = [];
+	for (let i = 1; i < n; i++) {
+		const next = new Array(K), from = new Int32Array(K);
+		for (let k = 0; k < K; k++) {
+			let best = Infinity;
+			for (let j = 0; j < K; j++) {
+				const a = Math.acos(Math.max(-1, Math.min(1, dot(U[i - 1][j], U[i][k])))), t = total[j] + TURN * a * a + (a > lim ? OVER_TURN * (a - lim) ** 2 : 0);
+				if (t < best) { best = t; from[k] = j; }
+			}
+			next[k] = best + C[i][k];
+		}
+		back.push(from);
+		total = next;
+	}
+	const pick = new Array(n);
+	pick[n - 1] = total.indexOf(Math.min(...total));
+	for (let i = n - 1; i > 0; i--) pick[i - 1] = back[i - 1][pick[i]];
+	return pick.map(k => grid[k]);
+}
+
+/**
+ * smoothPath that never jumps (jumpsIn): dir(i, x) is the world direction choice x gives frame i
+ * (the elbow's pole), grid the candidate angles. When the path smoothPath finds from x0 jumps, it
+ * starts again from the continuous path (continuousPath); if the cost pulls that back into a jump,
+ * the acceleration terms within AROUND frames of it weigh BOOST times more. A path that does not
+ * jump is smoothPath's, bit for bit, and so is one these do not free of jumps (the keys themselves
+ * jerk the hand there).
+ */
+export function steadyPath(cost, point, x0, dir, grid = POLE_GRID) {
+	const x = smoothPath(cost, point, x0);
+	if (!jumpsIn(x, dir, point).length) return x;
+	const y0 = continuousPath(cost, dir, x.length, grid), y = smoothPath(cost, point, y0), jumps = jumpsIn(y, dir, point);
+	if (!jumps.length) return y;
+	const weight = new Float64Array(Math.max(0, y.length - 2)).map((_, r) => (jumps.some(j => j >= r - AROUND && j <= r + 1 + AROUND) ? BOOST : 1));
+	const z = smoothPath(cost, point, y0, weight);
+	return jumpsIn(z, dir, point).length ? x : z;
+}
+
+/** Values over frames in a row, smoothed by a Gaussian of SIGMA frames (the weights renormalised at the ends). */
+export function smoothed(v) {
+	return v.map((_, i) => {
+		let sum = 0, wsum = 0;
+		for (let j = Math.max(0, i - 3 * SIGMA); j <= Math.min(v.length - 1, i + 3 * SIGMA); j++) { const g = Math.exp(-((j - i) ** 2) / (2 * SIGMA * SIGMA)); sum += g * v[j]; wsum += g; }
+		return sum / wsum;
+	});
+}
+
+/**
+ * The holding elbow's planned pole per frame, Map f -> world direction, over `frames` (ascending
+ * and contiguous, the frames the keys lead). frameAt(f) -> { s, held }: the plain pose of frame f
+ * and what the hand holds there (object-keys.js lead).
+ */
+export function polePlan(sk, side, frames, frameAt) {
+	const lands = frames.map(f => { const { s, held } = frameAt(f); return holdLandscape(sk, s, side, held); });
+	const th = steadyPath((i, t) => lands[i].at(t).cost, (i, t) => lands[i].at(t).elbow, lands.map(l => l.softmin()), (i, t) => lands[i].at(t).pv);
+	return new Map(frames.map((f, i) => [f, lands[i].at(th[i]).pv]));
+}

package/src/motion3/json-patch.js

@@ -0,0 +1,77 @@
+// JSON Patch (RFC 6902) on a motion spec: add, remove, replace and test, with "-" to append to
+// an array in add. Used for motion.compile { base, patch } (C7) and by repair (C6). Errors are
+// MOTION_SPEC_INVALID (INVALID_ARGUMENT to the agent) and name the op and what is there:
+//   patch[1] (replace /keys/12/f): /keys/12 does not exist (keys has 9 entries)
+// With a notes list (motion.compile, lenient.js), replace on a member an existing object lacks adds it
+// and says so; repair (no notes) stays strict.
+
+const OPS = ["add", "remove", "replace", "test"];
+const bad = msg => { throw new Error(`MOTION_SPEC_INVALID: ${msg}`); };
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** "/keys/0/set" -> ["keys", "0", "set"] (~1 is "/", ~0 is "~"). */
+const tokens = path => path.split("/").slice(1).map(t => t.replaceAll("~1", "/").replaceAll("~0", "~"));
+const pointer = parts => parts.map(t => `/${String(t).replaceAll("~", "~0").replaceAll("/", "~1")}`).join("");
+
+function what(container, name) {
+	if (Array.isArray(container)) return `${name} has ${container.length} entries`;
+	const keys = Object.keys(container);
+	return keys.length ? `${name} has ${keys.slice(0, 8).join(", ")}${keys.length > 8 ? ", ..." : ""}` : `${name} is empty`;
+}
+
+/** The container holding the last token, walking every token before it. */
+function parentOf(doc, parts, tag) {
+	let node = doc;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const t = parts[i], name = i ? parts[i - 1] : "the spec";
+		if (node === null || typeof node !== "object" || !Object.hasOwn(node, Array.isArray(node) ? Number(t) : t) || (Array.isArray(node) && !/^\d+$/.test(t)))
+			bad(`${tag}: ${pointer(parts.slice(0, i + 1))} does not exist${node && typeof node === "object" ? ` (${what(node, name)})` : ""}`);
+		node = node[Array.isArray(node) ? Number(t) : t];
+	}
+	if (node === null || typeof node !== "object") bad(`${tag}: ${pointer(parts.slice(0, -1))} is not an object or array`);
+	return node;
+}
+
+function applyOne(doc, op, i, notes) {
+	if (!op || typeof op !== "object" || !OPS.includes(op.op)) bad(`patch[${i}]: op must be ${OPS.join(", ")}, got ${JSON.stringify(op?.op)}`);
+	const tag = `patch[${i}] (${op.op} ${op.path})`;
+	if (typeof op.path !== "string" || (op.path !== "" && !op.path.startsWith("/"))) bad(`${tag}: path must be a JSON Pointer such as "/keys/0/f"`);
+	if (op.op !== "remove" && !Object.hasOwn(op, "value")) bad(`${tag}: needs a value`);
+	if (op.path === "") {
+		if (op.op === "replace") return structuredClone(op.value);
+		if (op.op === "test") { if (!same(doc, op.value)) bad(`${tag}: the spec differs from the test value`); return doc; }
+		bad(`${tag}: ${op.op} needs a path below the spec`);
+	}
+	const parts = tokens(op.path), last = parts[parts.length - 1], node = parentOf(doc, parts, tag);
+	const name = parts.length > 1 ? parts[parts.length - 2] : "the spec";
+	if (Array.isArray(node)) {
+		if (last === "-") { if (op.op !== "add") bad(`${tag}: "-" (append) works with add only`); node.push(structuredClone(op.value)); return doc; }
+		const k = /^\d+$/.test(last) ? Number(last) : NaN;
+		const max = op.op === "add" ? node.length : node.length - 1;
+		if (!(k >= 0 && k <= max)) bad(`${tag}: ${op.path} does not exist (${what(node, name)})`);
+		if (op.op === "add") node.splice(k, 0, structuredClone(op.value));
+		else if (op.op === "remove") node.splice(k, 1);
+		else if (op.op === "replace") node[k] = structuredClone(op.value);
+		else if (!same(node[k], op.value)) bad(`${tag}: value is ${JSON.stringify(node[k])?.slice(0, 60)}, not ${JSON.stringify(op.value)?.slice(0, 60)}`);
+		return doc;
+	}
+	if (op.op === "replace" && notes && !Object.hasOwn(node, last)) notes.push(`${tag}: ${op.path} did not exist (${what(node, name)}); added`);
+	else if (op.op !== "add" && !Object.hasOwn(node, last)) bad(`${tag}: ${op.path} does not exist (${what(node, name)})`);
+	if (op.op === "remove") delete node[last];
+	else if (op.op === "test") { if (!same(node[last], op.value)) bad(`${tag}: value is ${JSON.stringify(node[last])?.slice(0, 60)}, not ${JSON.stringify(op.value)?.slice(0, 60)}`); }
+	else node[last] = structuredClone(op.value);
+	return doc;
+}
+
+/**
+ * Applies ops in order to a copy of doc (doc is never changed) and returns the copy; the first
+ * failing op throws MOTION_SPEC_INVALID and nothing is applied. notes (optional) turns a replace on a
+ * missing object member into an add and collects a line for it.
+ * @param {object} doc
+ * @param {{ op: "add" | "remove" | "replace" | "test", path: string, value?: any }[]} ops
+ * @param {string[]} [notes]
+ */
+export function applyPatch(doc, ops, notes) {
+	if (!Array.isArray(ops)) bad("patch must be an array of { op, path, value }");
+	return ops.reduce((d, op, i) => applyOne(d, op, i, notes), structuredClone(doc));
+}

package/src/motion3/key-aim.js

@@ -0,0 +1,105 @@
+// C16. Aim keys: a held-object key (C14) may give aim [x, y, z], the world direction the object's
+// +Y points (a bat: knob to barrel), with an optional roll (degrees about that direction,
+// right-handed), in place of the quaternion rot. An aim key turns the object the shortest way
+// from where the plain carry (no keys) holds it at that key's frame onto aim, then by roll.
+// (Turning from the key before instead piles the roll up over a swing: the bat fixture's keys as
+// aims, so chained, missed by 45.5 cm.)
+// Without roll (lane K8) the key takes the roll the arm holds most easily: ROLLS candidate rolls
+// about aim are scored by the strain of the arm that holds them (compiler/hold.js holdCost), a
+// pass over the keys in order picks one per key with a light price on how far the object turns
+// from the key before (so equally easy rolls do not alternate), and a golden-section search
+// settles each pick within its step. roll given (0 included) and rot keys are used exactly.
+// The quaternion is rounded to 1e-5 (the grid motion.keyObject writes) and kept on the hemisphere
+// of the key before it.
+// lean (degrees, lane elbow) lets the compiler lean aim itself up to that far: a cup brought to the mouth
+// is tipped toward the face AND a little toward the hand's side, which lets the elbow stay down (a cup at
+// the mouth aimed only at the face can be held with a comfortable wrist only with the elbow over the
+// shoulder). The aim, and AZIMUTHS directions leaned lean/2 and lean, each at every roll (or at the
+// given roll), are scored by the arm's strain plus the shoulder's price (hold.js holdCost opts.shoulder);
+// the chain and the roll refinement run as above on the picked direction.
+import { qmul, qrot, qdot, qnorm, arcQuat, axisQuat } from "./compiler/quat.js";
+import { add, cross, norm, scale, sub } from "./compiler/math.js";
+
+const ROLLS = 24, STEP = 360 / ROLLS, TURN = 0.2, GOLDEN = 12, AZIMUTHS = 8;
+const round5 = v => Math.round(v * 1e5) / 1e5;
+/** The turn between two unit quaternions, radians. */
+const turn = (a, b) => 2 * Math.acos(Math.min(1, Math.abs(qdot(a, b))));
+
+/**
+ * Where a leaning key puts the object: a lean pivots about the object's top (its +Y end, `top` m above its
+ * base pivot), so a cup's rim stays where aim put it (at the lips) and its foot swings; any other key's pos.
+ */
+export const leanPos = (key, q, top) => (key.lean > 0 && key.aim && top > 0 ? add(key.pos, scale(sub(norm(key.aim), qrot(q, [0, 1, 0])), top)) : key.pos);
+
+/** aim d and the directions leaned lean/2 and lean deg from it toward AZIMUTHS sides. */
+function leanedAims(d, lean) {
+	const side = norm(cross(d, Math.abs(d[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0])), up = cross(d, side), out = [d];
+	for (const deg of [lean / 2, lean]) for (let j = 0; j < AZIMUTHS; j++) {
+		const a = (2 * Math.PI * j) / AZIMUTHS, t = (Math.min(deg, 45) * Math.PI) / 180, w = add(scale(side, Math.cos(a)), scale(up, Math.sin(a)));
+		out.push(norm(add(scale(d, Math.cos(t)), scale(w, Math.sin(t)))));
+	}
+	return out;
+}
+
+/** The pick per key: DP over candidates [{ q, cost }] per key, a TURN price on the squared turn between neighbours. */
+function chain(cands) {
+	let best = cands[0].map(c => ({ total: c.cost, from: -1 }));
+	const back = [best];
+	for (let i = 1; i < cands.length; i++) {
+		best = cands[i].map(c => {
+			let pick = { total: Infinity, from: -1 };
+			cands[i - 1].forEach((p, j) => { const t = back[i - 1][j].total + TURN * turn(p.q, c.q) ** 2; if (t < pick.total) pick = { total: t, from: j }; });
+			return { total: pick.total + c.cost, from: pick.from };
+		});
+		back.push(best);
+	}
+	const picks = [];
+	for (let i = cands.length - 1, j = best.reduce((m, b, k) => (b.total < best[m].total ? k : m), 0); i >= 0; j = back[i][j].from, i--) picks[i] = j;
+	return picks;
+}
+
+/** Golden-section search of f on [lo, hi]. */
+function golden(f, lo, hi) {
+	const g = (Math.sqrt(5) - 1) / 2;
+	let a = lo, b = hi, c = b - g * (b - a), d = a + g * (b - a), fc = f(c), fd = f(d);
+	for (let i = 0; i < GOLDEN; i++) {
+		if (fc < fd) { b = d; d = c; fd = fc; c = b - g * (b - a); fc = f(c); } else { a = c; c = d; fc = fd; d = a + g * (b - a); fd = f(d); }
+	}
+	return (a + b) / 2;
+}
+
+/**
+ * The rot of each key (keys sorted by f): a rot key's own, an aim key's resolved quaternion
+ * [x, y, z, w]. plain(i) is the rotation (a quaternion) the plain carry gives the object at key
+ * i's frame; it is asked for aim keys only. strain(i, q), when given, is the arm's cost of
+ * holding key i at rotation q; it picks the roll of aim keys that give none.
+ */
+export function keyRots(keys, plain, strain) {
+	const at = keys.map((k, i) => {
+		if (k.aim === undefined) return { fixed: qnorm(k.rot) };
+		const from = qnorm(plain(i)), aimed = d => { const q0 = qmul(arcQuat(norm(qrot(from, [0, 1, 0])), d), from); return r => qmul(axisQuat(d, r), q0); };
+		if (k.lean > 0 && strain) return { leans: leanedAims(norm(k.aim), k.lean).map(aimed), roll: k.roll };
+		const rolled = aimed(norm(k.aim));
+		return k.roll !== undefined || !strain ? { fixed: k.roll ? rolled(k.roll) : rolled(0) } : { rolled };
+	});
+	const rollsOf = a => (a.roll !== undefined ? [a.roll] : Array.from({ length: ROLLS }, (_, j) => j * STEP - 180));
+	const cands = at.map((a, i) => (a.fixed ? [{ q: a.fixed, cost: 0, r: 0 }]
+		: a.leans ? a.leans.flatMap(rolled => rollsOf(a).map(r => { const q = rolled(r); return { q, cost: strain(i, q), r, rolled, fixedRoll: a.roll !== undefined }; }))
+		: Array.from({ length: ROLLS }, (_, j) => { const r = j * STEP - 180, q = a.rolled(r); return { q, cost: strain(i, q), r }; })));
+	const picks = chain(cands), chosen = cands.map((c, i) => c[picks[i]]);
+	// a leaning key keeps the direction it picked; its roll is refined below like any other (unless given)
+	for (const [i, a] of at.entries()) if (a.leans) at[i] = chosen[i].fixedRoll ? { fixed: chosen[i].q } : { rolled: chosen[i].rolled };
+	const rots = [];
+	let prev = null;
+	for (const [i, a] of at.entries()) {
+		if (keys[i].aim === undefined) { rots.push(keys[i].rot); prev = a.fixed; continue; }
+		let q = (a.fixed ?? a.rolled(golden(r => {
+			const qr = a.rolled(r), near = [chosen[i - 1], chosen[i + 1]].filter(Boolean);
+			return strain(i, qr) + near.reduce((sum, n) => sum + TURN * turn(n.q, qr) ** 2, 0);
+		}, chosen[i].r - STEP / 2, chosen[i].r + STEP / 2))).map(round5);
+		if (prev && qdot(q, prev) < 0) q = q.map(v => -v);
+		rots.push(q);
+		prev = qnorm(q);
+	}
+	return rots;
+}

package/src/motion3/key-edit.js

@@ -0,0 +1,82 @@
+// motion.keyObject (C14): one key of an object the take moves, upserted into (or removed from) a
+// copy of the take's spec. The caller compiles and installs the copy.
+//   carry  objects.<id>.keys[{ f, pos, rot }] or [{ f, pos, aim, roll? }] (C16): the world pose of its
+//          base (a group: its root), only while it is in hand (grab..release); kept sorted by f; the
+//          last one removed drops `keys`
+//   hinge  spec.keys[{ f, set: { <channel>: degrees } }]: `angle`, or the turn of `rot` (the drawn
+//          world rotation) about the hinge axis from the scene pose; a key at f is reused
+// An object a skill moves (exitCar's door hinge) is keyed the same way: a hinge through its channel,
+// a carry by copying the skill's entry into spec.objects with the keys (the spec's own entry wins).
+// Frames are the spec's (absolute). Errors carry the MOTION_SPEC_INVALID: prefix (INVALID_ARGUMENT).
+import { isCarried, isFollow, movesRecord } from "./carried.js";
+import { groupsOf } from "./scene.js";
+import { mul, T, norm, quatFromMat, matFromQuat } from "./compiler/math.js";
+
+const bad = msg => { throw new Error(`MOTION_SPEC_INVALID: ${msg}`); };
+const round = (v, d) => Math.round(v * d) / d;
+const framesOf = list => (list.length ? list.map(f => `f${f}`).join(", ") : "none");
+
+/** The spec.objects key that moves scene body `id` (itself or its nearest group; a switch moves nothing), or null. */
+function moverOf(spec, scene, id) {
+	return [id, ...(scene?.objects?.[id]?.ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])) ?? null;
+}
+
+/** Degrees the world rotation `rot` turns about `axis` from the rest rotation (the twist, -180..180). */
+function hingeAngle(rot, rest, axis) {
+	const q = quatFromMat(mul(matFromQuat(rot), T(rest.R))), a = norm(axis), sg = q[3] < 0 ? -1 : 1;
+	const deg = 2 * Math.atan2(sg * (q[0] * a[0] + q[1] * a[1] + q[2] * a[2]), sg * q[3]) * 180 / Math.PI;
+	return round(deg > 180 ? deg - 360 : deg, 100);
+}
+
+function carryKey(spec, id, o, { frame, pos, rot, aim, roll, remove }) {
+	const lo = o.grab ?? 0, hi = o.release ?? spec.frames - 1, keys = [...(o.keys ?? [])].filter(k => k.f !== frame);
+	if (frame < lo || frame > hi) bad(`"${id}" is in hand only f${lo}..f${hi} (grab..release); at f${frame} the take does not hold it, so drag it as a scene object, or change objects.${id}.grab/release first`);
+	if (remove) {
+		if (keys.length === (o.keys ?? []).length) bad(`"${id}" has no key at f${frame}; its keys: ${framesOf((o.keys ?? []).map(k => k.f))}`);
+	} else {
+		if (!Array.isArray(pos) || Array.isArray(rot) === Array.isArray(aim)) {
+			bad(`keying "${id}" (carried) needs pos [x, y, z] and rot [x, y, z, w] or aim [x, y, z] (+ roll), one of the two: the world pose of its base (a group: its root)`);
+		}
+		const turn = rot ? { rot: rot.map(v => round(v, 1e5)) } : { aim: aim.map(v => round(v, 1e5)), ...(Number.isFinite(roll) && roll ? { roll: round(roll, 100) } : {}) };
+		keys.push({ f: frame, pos: pos.map(v => round(v, 1e4)), ...turn });
+	}
+	const { keys: _old, ...rest } = o;
+	spec.objects[id] = keys.length ? { ...rest, keys: keys.sort((a, b) => a.f - b.f) } : rest;
+	return { kind: "carry", f: frame, ...(remove ? { removed: true } : {}), keys: keys.map(k => k.f) };
+}
+
+function hingeKey(spec, scene, id, o, { frame, rot, angle, remove }) {
+	const ch = o.channel, i = (spec.keys ?? []).findIndex(k => k?.f === frame && !k.src && k.set && ch in k.set);
+	if (remove) {
+		if (i < 0) bad(`"${id}" (hinge, channel "${ch}") has no key at f${frame}; ${ch} is keyed at ${framesOf((spec.keys ?? []).filter(k => k?.set && ch in k.set).map(k => k.f))}`);
+		const { [ch]: _gone, ...set } = spec.keys[i].set;
+		spec.keys = Object.keys(set).length ? spec.keys.map((k, j) => (j === i ? { ...k, set, ...(k.step ? { step: k.step.filter(c => c !== ch) } : {}) } : k)) : spec.keys.filter((_, j) => j !== i);
+		return { kind: "hinge", channel: ch, f: frame, removed: true };
+	}
+	const rest = scene?.objects?.[id] ?? groupsOf(scene)[id];
+	const value = Number.isFinite(angle) ? round(angle, 100) : Array.isArray(rot) && rest ? hingeAngle(rot, rest, o.axis ?? [0, 1, 0])
+		: bad(`keying "${id}" (a hinge on channel "${ch}") needs angle (degrees) or rot [x, y, z, w] (its drawn world rotation; the turn about the hinge axis is kept)`);
+	const at = (spec.keys ?? []).findIndex(k => k?.f === frame && !k.src);
+	spec.keys = at < 0 ? [...(spec.keys ?? []), { f: frame, set: { [ch]: value } }] : spec.keys.map((k, j) => (j === at ? { ...k, set: { ...k.set, [ch]: value } } : k));
+	return { kind: "hinge", channel: ch, f: frame, angle: value };
+}
+
+/**
+ * keyObject(spec, scene, { objectId, frame, pos?, rot?, aim?, roll?, angle?, remove? }, skillObjects?) -> { spec, keyed }:
+ * a copy of the spec with the key written, and what was written ({ objectId, kind, f, ... }).
+ * skillObjects are the spec.objects entries its skills add (skills/index.js expandUse).
+ */
+export function keyObject(stored, scene, args, skillObjects = {}) {
+	const spec = structuredClone(stored), { objectId: id, frame } = args, moves = x => (movesRecord(x) ? x : undefined);
+	const o = moves(spec.objects?.[id]) ?? structuredClone(moves(skillObjects[id]));
+	if (!o) {
+		const mover = moverOf({ objects: { ...skillObjects, ...spec.objects } }, scene, id);
+		bad(mover ? `"${id}" moves with "${mover}" (spec.objects.${mover}); key "${mover}" with its root pose`
+			: `"${id}" is not in this take's spec.objects (${Object.keys({ ...skillObjects, ...spec.objects }).join(", ") || "none"}): the take neither carries nor hinges it, so drag it as a scene object`);
+	}
+	if (!(Number.isInteger(frame) && frame >= 0 && frame < spec.frames)) bad(`frame ${frame} is outside the take (0..${spec.frames - 1})`);
+	if (isFollow(o)) bad(`"${id}" follows ${o.follow} (spec.objects.${id}); it has no keys: change its follow, offset or aim`);
+	if (isCarried(o)) spec.objects = { ...spec.objects, [id]: o };
+	const keyed = isCarried(o) ? carryKey(spec, id, o, args) : hingeKey(spec, scene, id, o, args);
+	return { spec, keyed: { objectId: id, ...keyed } };
+}