cozyclay 2.1.1 → 3.0.1

package/src/motion3/search.js

@@ -0,0 +1,117 @@
+// Open parameters: any number in a spec (generator params, key channel values or vector
+// components, anchor offsets, skill args) may be written as { range: [lo, hi] } (or
+// { search: [lo, hi] }, + int: true). motion.compile then searches the values deterministically:
+// the midpoint first, a grid (one parameter) or a Halton set (several), then a shrinking pattern
+// search around the best, at most spec.search.budget (default 32, max 64) compiles, stopping at
+// the first value with QA 0. Each trial compiles only the frames the parameters can change.
+import { compileMotion } from "./compiler/compile.js";
+import { bakeChannels, flowOptions } from "./compiler/channels.js";
+import { expandGenerators } from "./compiler/walk.js";
+import { runMotionQa } from "./qa/index.js";
+import { weightOf } from "./qa/severity.js";
+
+const INT_FIELDS = new Set(["f", "f0", "steps", "period", "swing", "until", "reach", "hold", "release"]);
+const isOpen = v => v && typeof v === "object" && !Array.isArray(v) && (v.range ?? v.search) !== undefined && Object.keys(v).every(k => ["range", "search", "int"].includes(k));
+const pathText = path => path.reduce((s, p) => (typeof p === "number" ? `${s}[${p}]` : s ? `${s}.${p}` : p), "");
+
+/** Every { range } in the spec: [{ path, lo, hi, int }]. */
+export function findParams(spec) {
+	const out = [];
+	const walk = (v, path) => {
+		if (isOpen(v)) {
+			const r = v.range ?? v.search;
+			if (!(Array.isArray(r) && r.length === 2 && r.every(Number.isFinite) && r[0] < r[1])) throw new Error(`MOTION_SPEC_INVALID: ${pathText(path)} range must be [lo, hi] with lo < hi, got ${JSON.stringify(r)}`);
+			out.push({ path, lo: r[0], hi: r[1], int: v.int ?? INT_FIELDS.has(path[path.length - 1]) });
+			return;
+		}
+		if (Array.isArray(v)) v.forEach((x, i) => walk(x, [...path, i]));
+		else if (v && typeof v === "object") for (const [k, x] of Object.entries(v)) walk(x, [...path, k]);
+	};
+	for (const [k, v] of Object.entries(spec ?? {})) if (!["schema", "fps", "frames", "search"].includes(k)) walk(v, [k]);
+	return out;
+}
+
+const snap = (p, x) => { const v = Math.min(p.hi, Math.max(p.lo, x)); return p.int ? Math.round(v) : Math.round(v * 1e4) / 1e4; };
+
+function resolveParams(spec, params, values) {
+	const s = structuredClone(spec);
+	params.forEach((p, i) => { let o = s; for (const k of p.path.slice(0, -1)) o = o[k]; o[p.path[p.path.length - 1]] = values[i]; });
+	return s;
+}
+
+/** QA groups -> one number: the sum of their severities (qa/severity.js, unrounded). */
+const costOf = qa => qa.groups.reduce((c, g) => c + weightOf(g), 0);
+
+/** Frames a parameter can change (baked channels differ between its ends), or null for all. */
+function dirtyWindow(spec, params, mid, prepare, sk) {
+	const expand = values => prepare(resolveParams(spec, params, values));
+	const base = expand(mid), parts = s => JSON.stringify({ ...s, keys: undefined, generators: undefined });
+	const bake = s => bakeChannels(expandGenerators(s, sk), s.frames, flowOptions(s.flow));
+	const b0 = bake(base);
+	let a = Infinity, b = -Infinity;
+	for (let i = 0; i < params.length; i++) for (const end of [params[i].lo, params[i].hi]) {
+		const s = expand(mid.map((v, j) => (j === i ? snap(params[i], end) : v)));
+		if (parts(s) !== parts(base)) return null;
+		const b1 = bake(s);
+		for (const ch of new Set([...Object.keys(b0), ...Object.keys(b1)])) {
+			const x = b0[ch], y = b1[ch];
+			for (let f = 0; f < spec.frames; f++) if (JSON.stringify(x?.[f]) !== JSON.stringify(y?.[f])) { a = Math.min(a, f); b = Math.max(b, f); }
+		}
+	}
+	return a > b ? null : [Math.max(0, a - 8), Math.min(spec.frames - 1, b + 8)];
+}
+
+/** Halton point i (1-based) in [0, 1]^k. */
+const PRIMES = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29];
+const halton = (i, k) => Array.from({ length: k }, (_, d) => { let f = 1, r = 0, n = i; const p = PRIMES[d % PRIMES.length]; while (n > 0) { f /= p; r += f * (n % p); n = Math.floor(n / p); } return r; });
+
+/**
+ * prepare(spec) -> expanded + validated plain spec (pipeline.js). Returns the spec with the
+ * chosen values and a report { values: { path: value }, evals, cost (0 = clean), window, ms }.
+ */
+export function searchParams(spec, params, { sk, scene }, prepare) {
+	const t0 = performance.now(), budget = Math.max(1, Math.min(64, Math.round(spec.search?.budget ?? 32)));
+	const mid = params.map(p => snap(p, (p.lo + p.hi) / 2));
+	const window = dirtyWindow(spec, params, mid, prepare, sk);
+	const cache = new Map();
+	let evals = 0, best = null;
+	const evaluate = values => {
+		const key = values.join(",");
+		if (cache.has(key)) return cache.get(key);
+		if (evals >= budget) return Infinity;
+		evals++;
+		let cost;
+		try {
+			const exp = prepare(resolveParams(spec, params, values));
+			cost = costOf(runMotionQa(sk, compileMotion({ fps: 24, ...exp }, { sk, scene }, { window }), exp, { explain: false }));
+		} catch (error) {
+			if (!/MOTION_SPEC_INVALID/.test(error.message)) throw error;
+			cost = 1e9;
+		}
+		cache.set(key, cost);
+		if (!best || cost < best.cost) best = { values, cost };
+		return cost;
+	};
+	const done = () => best?.cost === 0 || evals >= budget;
+	const at = u => params.map((p, d) => snap(p, p.lo + (p.hi - p.lo) * u[d]));
+	evaluate(mid);
+	// coarse pass: a 9-point grid from the middle outward (one parameter) or Halton points
+	const coarse = params.length === 1 ? [4, 3, 5, 2, 6, 1, 7, 0, 8].map(i => [i / 8]) : Array.from({ length: Math.min(budget >> 1, 8 * params.length) }, (_, i) => halton(i + 1, params.length));
+	for (const u of coarse) { if (done()) break; evaluate(at(u)); }
+	// pattern search around the best, halving the step
+	let step = params.map(p => (p.hi - p.lo) / 8);
+	while (!done() && step.some((s, d) => s > (params[d].int ? 0.5 : (params[d].hi - params[d].lo) * 1e-3))) {
+		let moved = false;
+		for (let d = 0; d < params.length && !done(); d++) for (const sg of [-1, 1]) {
+			const v = best.values.slice(); v[d] = snap(params[d], v[d] + sg * step[d]);
+			const before = best.cost;
+			evaluate(v);
+			if (best.cost < before) moved = true;
+		}
+		if (!moved) step = step.map(s => s / 2);
+	}
+	return {
+		spec: resolveParams(spec, params, best.values),
+		search: { values: Object.fromEntries(params.map((p, i) => [pathText(p.path), best.values[i]])), evals, cost: Math.round(best.cost * 100) / 100, window, ms: Math.round(performance.now() - t0) },
+	};
+}

package/src/motion3/second-hand.js

@@ -0,0 +1,112 @@
+// The second hand on a held object (C14, lane K8). While keys lead a carry the right hand holds
+// (object-keys.js), a left hand anchored to that prop (w_<anchor>_l on a kind "prop" anchor of
+// the same prop, with or without a fit) turns with the object too. The wrist stays where the
+// anchor puts it (with a fit, the palm stays where the fit puts it). The hand takes the holding
+// hand's grip mirrored across the plane of the object's axis and the holding fingers (the object's
+// +Y runs through the left palm frame as through the right one, knuckles in line), turned about
+// the axis to the roll its arm holds most easily (planned over the frames, object-keys.js and
+// hold-plan.js). The arm follows as for the holding hand (compiler/hold.js): the elbow swivels
+// about the shoulder-wrist axis (lane N1; it stayed in the plane the anchor's IK gave it, and the
+// default pole, down and back, bent a left arm reaching across the chest into the torso), the
+// forearm and the wrist turn. Each roll is scored by the wrist's strain at the best of POLES poles,
+// plus CLEAR per squared centimetre the upper arm, the forearm or the hand goes into the torso
+// capsules (the BODY check's), and DEEP per squared centimetre the hand goes past what QA allows a
+// hand: into the torso past the BODY allowance, into the holding hand past the SELF one (lane Q1:
+// at CLEAR alone, session 4db5d447 put the hand 0.9 cm into torso_lo at f35 to save 1 of strain,
+// QA BODY). The elbow's path is planned like the holding elbow's. The hold
+// eases in with the keys' weight times the anchor weight, and a grip the arm cannot hold fades out.
+// Only a hand solved after the holding hand can follow it (pose.js solves the right arm first), so
+// the second hand is the left.
+import { palmAxes } from "./compiler/limbs.js";
+import { SIDES } from "./compiler/pose.js";
+import { add, sub, scale, norm, dot, cross, mul, T, apply, axisRot, len, clamp } from "./compiler/math.js";
+import { landscape, ELBOW_REST } from "./compiler/arm-orient.js";
+import { bendPlane } from "./compiler/hold.js";
+import { CAPSULES } from "./qa/geometry.js";
+import { QA_LIMITS } from "./qa/checks.js";
+import { bodyFor, segmentDepth } from "./body.js";
+
+const ROLLS = 36, TEMP = 0.05, PULL = 0.3, EASY = 3, SLACK = 10, POLES = 36, CLEAR = 1, DEEP = 100;
+const TORSO = CAPSULES.filter(c => c[0].startsWith("torso")), RADIUS = Object.fromEntries(CAPSULES.map(c => [c[0], c[3]]));
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];
+const col = (R, i) => [R[0][i], R[1][i], R[2][i]];
+
+/** The distance between segments p1-q1 and p2-q2 (closest points, clamped to both). */
+function segSeg(p1, q1, p2, q2) {
+	const d1 = sub(q1, p1), d2 = sub(q2, p2), r = sub(p1, p2), a = dot(d1, d1), e = dot(d2, d2), f = dot(d2, r);
+	if (a < 1e-12 || e < 1e-12) return len(r);
+	const c = dot(d1, r), b = dot(d1, d2), den = a * e - b * b;
+	let t = den > 1e-12 ? clamp((b * f - c * e) / den, 0, 1) : 0, u = (b * t + f) / e;
+	if (u < 0) { u = 0; t = clamp(-c / a, 0, 1); } else if (u > 1) { u = 1; t = clamp((b - c) / a, 0, 1); }
+	return len(sub(add(p1, scale(d1, t)), add(p2, scale(d2, u))));
+}
+
+/** The palm frame of `side` on pose s: the finger middles, axes d, l, n as columns. */
+function palmFrame(sk, s, side) {
+	const I = sk.index, ax = palmAxes(sk, s, side);
+	return { pos: scale(add(s.P[I[`${side}HandIndex2`]], s.P[I[`${side}HandMiddle2`]]), 0.5), R: cols(ax.d, ax.l, ax.n) };
+}
+
+/**
+ * The left hand's grip on carry `id` at this frame, or null when the left hand is not anchored to
+ * its prop: s is the pose with the holding hand done and the left arm on its plain target, c the
+ * frame's channels, axis the object's +Y as drawn. The grip is the holding hand's mirrored (knuckles
+ * in line), turned `roll` radians about the axis; arm(roll) is the left arm holding it: at(th) ->
+ * { pv, elbow, cost } for the elbow th radians about the shoulder-wrist axis from its plane (the
+ * swivel landscape plus the torso price) and best { th, pole, cost }; cost(roll) is best's cost
+ * (pulled lightly toward the mirror), point(roll) the end of the hand that moves (the palm with the
+ * wrist pinned, the wrist with the palm pinned), softmin() the easiest roll.
+ */
+export function secondGrip(sk, spec, id, s, c, axis) {
+	const o = spec.objects[id];
+	if (spec.props[o.prop].hand !== "r") return null;
+	const weight = Object.entries(spec.anchors ?? {}).reduce((sum, [name, a]) => sum + (a.kind === "prop" && a.prop === o.prop ? Math.max(0, c[`w_${name}_l`] ?? 0) : 0), 0);
+	if (!(weight > 1e-4)) return null;
+	// the mirror of the holding palm frame across the plane of the axis and the holding fingers
+	const R = palmFrame(sk, s, SIDES.r).R, d = col(R, 0), p = norm(cross(axis, sub(d, scale(axis, dot(d, axis))))), mirror = v => sub(v, scale(p, 2 * dot(v, p)));
+	const base = cols(mirror(d), mirror(col(R, 1)), scale(mirror(col(R, 2)), -1));
+	const left = palmFrame(sk, s, SIDES.l), I = sk.index, h = I.LeftHand, wrist = s.P[h], local = mul(T(s.R[h]), left.R), localP = apply(T(s.R[h]), sub(left.pos, wrist));
+	// with a fit the palm (its effector) stays where the fit put it, else the wrist stays on the anchor
+	const pin = (spec.fits ?? []).some(x => x.side === "l" && spec.anchors?.[x.anchor]?.kind === "prop" && spec.anchors[x.anchor].prop === o.prop && c[`w_${x.anchor}_l`] > 1e-4) ? "palm" : "wrist";
+	const rolled = r => mul(axisRot(axis, r * 180 / Math.PI), base), hand = r => mul(rolled(r), T(local));
+	const point = r => (pin === "wrist" ? add(wrist, apply(hand(r), localP)) : sub(left.pos, apply(hand(r), localP)));
+	// the wrist for a roll, the knuckles off it, and how deep a segment goes into the torso (m)
+	const wristAt = r => (pin === "wrist" ? wrist : point(r)), knuckle = apply(T(s.R[h]), sub(s.P[I.LeftHandMiddle3], wrist)), S = s.P[I.LeftArm], plane = bendPlane(sk, s, SIDES.l);
+	// on the fitted skin when the rig has one and spec.fix.self is on (body.js, as QA's BODY measures it), else on the torso capsules
+	const skin = spec.fix === false || spec.fix?.self === false ? null : bodyFor(sk), BONE = { uarm_l: I.LeftArm, farm_l: I.LeftForeArm, hand_l: I.LeftHand };
+	const into = (a, b, part) => (skin ? segmentDepth(skin, sk, s, BONE[part], a, b) : Math.max(0, ...TORSO.map(([, ta, tb, rt]) => RADIUS[part] + rt - segSeg(a, b, s.P[I[ta]], s.P[I[tb]]))));
+	const arms = new Map();
+	const arm = r => {
+		if (arms.has(r)) return arms.get(r);
+		const W = wristAt(r), land = landscape(sk, s, SIDES.l, hand(r), W, plane, ELBOW_REST);
+		const at = th => { const q = land.at(th); return { pv: q.pv, elbow: q.elbow, cost: q.cost + CLEAR * ((100 * into(S, q.elbow, "uarm_l")) ** 2 + (100 * into(q.elbow, W, "farm_l")) ** 2) }; };
+		let best = { th: 0, cost: Infinity };
+		for (let i = 0; i < POLES; i++) { const th = (2 * Math.PI * i) / POLES - Math.PI, v = at(th).cost; if (v < best.cost) best = { th, cost: v }; }
+		const K = add(W, apply(hand(r), knuckle)), deep = into(W, K, "hand_l"), past = Math.max(0, deep - QA_LIMITS.body);
+		// the holding hand is done: how far this hand's capsule goes into it (QA SELF "hands overlap")
+		const touch = 2 * RADIUS.hand_l - segSeg(W, K, s.P[I.RightHand], s.P[I.RightHandMiddle3]), over = Math.max(0, touch - QA_LIMITS.hands);
+		const fixed = CLEAR * ((100 * deep) ** 2 + (100 * land.miss) ** 2) + (past > 0 ? DEEP * (100 * past) ** 2 : 0) + (over > 0 ? DEEP * (100 * over) ** 2 : 0);
+		const a = { at, best: { th: best.th, pole: at(best.th).pv, cost: best.cost + fixed } };
+		arms.set(r, a);
+		return a;
+	};
+	const cost = r => arm(r).best.cost + PULL * (1 - Math.cos(r));
+	const softmin = () => {
+		const all = Array.from({ length: ROLLS }, (_, i) => { const r = (2 * Math.PI * i) / ROLLS - Math.PI; return [r, cost(r)]; }), low = Math.min(...all.map(x => x[1]));
+		const m = all.reduce((acc, [r, v]) => { const e = Math.exp(-(v - low) / TEMP); return [acc[0] + e * Math.cos(r), acc[1] + e * Math.sin(r)]; }, [0, 0]);
+		return Math.atan2(m[1], m[0]);
+	};
+	return { id, weight, pin, at: left.pos, rolled, arm, cost, point, softmin, measure: s2 => palmFrame(sk, s2, SIDES.l) };
+}
+
+/** How much of a grip at `roll` the arm can take: 1 while its cost is under EASY, fading by SLACK past it. */
+export const gripGate = (grip, roll) => Math.exp(-Math.max(0, grip.cost(roll) - EASY) / SLACK);
+
+/**
+ * The hold ({ w, palm, measure, pole, pin, second } for compiler/hold.js) of a grip at `roll`
+ * radians with the elbow toward `pole` (a world direction), w the keys' lead weight, gate the
+ * planned gripGate: a grip the arm cannot hold fades out, so the hand stays nearer where the plain
+ * arm put it instead of turning to a limit and flipping there.
+ */
+export const secondHold = (grip, w, roll, gate, pole) => ({ w: w * Math.min(1, grip.weight) * gate, second: grip.id, pin: grip.pin,
+	pole, palm: { pos: grip.at, R: grip.rolled(roll) }, measure: grip.measure });

package/src/motion3/settle.js

@@ -0,0 +1,136 @@
+// How a falling object (C17, free-motion.js) comes to rest. It falls with its centre on a parabola, turning at the spin it
+// was let go with, and lands on its lowest point. Then it rolls about what touches the support. Landing on an edge or a
+// corner it rocks back onto the face nearest down, or falls over onto the face it leans to when it leans past that edge.
+// Then it goes over an edge onto a lower face while the landing has the energy (a share TIP of the drop; only one that hit
+// tilted or spinning, since a flat landing has nothing to tip it), or at once from a precarious face (one it can tilt less
+// than PRECARIOUS before its centre passes the edge). So a phone on its edge falls flat, a tilted box comes down on a face,
+// a can let go at a slant lies down, and a can or cup dropped upright stays upright. It only rolls onto a face that lowers
+// its centre by at least LOWER of its height, so a near cube stays the way it lands. The shape is the box around the
+// object's parts in its own frame, and its centre is the parts' volume-weighted centre. Every step is a rotation about a
+// pivot on the support, paced by gravity: closed form and deterministic.
+import { add, sub, scale, dot, cross, len, norm, mul, apply, axisRot, clamp } from "./compiler/math.js";
+import { G } from "./free-motion.js";
+
+/** The share of the drop height a landing spends tipping the object over an edge. */
+export const TIP = 0.3;
+const LOWER = 0.2, FLAT = 0.5, PRECARIOUS = 15, MIN_SPIN = 1, MAX_SPIN = 6 * Math.PI, MAX_STEPS = 3;
+const DOWN = [0, -1, 0];
+const AXES = [[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]];
+const deg = r => (r * 180) / Math.PI;
+
+/** The shape of part boxes { pos, R, half } given in the root frame: { com, lo, hi } (box around the corners); null without volume. */
+export function shapeOf(boxes) {
+	const solid = boxes.filter(b => b.half[0] * b.half[1] * b.half[2] > 1e-12);
+	if (!solid.length) return null;
+	let vol = 0, c = [0, 0, 0];
+	const corners = [];
+	for (const b of solid) {
+		const v = b.half[0] * b.half[1] * b.half[2];
+		vol += v;
+		c = add(c, scale(add(b.pos, apply(b.R, [0, b.half[1], 0])), v));
+		for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) corners.push(add(b.pos, apply(b.R, [x * b.half[0], y * b.half[1], z * b.half[2]])));
+	}
+	return { com: scale(c, 1 / vol), lo: [0, 1, 2].map(i => Math.min(...corners.map(p => p[i]))), hi: [0, 1, 2].map(i => Math.max(...corners.map(p => p[i]))) };
+}
+
+const boxCorners = s => [0, 1, 2, 3, 4, 5, 6, 7].map(i => [i & 1 ? s.hi[0] : s.lo[0], i & 2 ? s.hi[1] : s.lo[1], i & 4 ? s.hi[2] : s.lo[2]]);
+const world = (pose, p) => add(pose.pos, apply(pose.R, p));
+const lowest = (s, pose) => Math.min(...boxCorners(s).map(p => world(pose, p)[1]));
+/** The pose moved up or down so its lowest corner sits on the support top. */
+const snap = (s, pose, top) => ({ pos: [pose.pos[0], pose.pos[1] + top - lowest(s, pose), pose.pos[2]], R: pose.R });
+const about = (pose, pivot, Q) => ({ pos: add(pivot, apply(Q, sub(pose.pos, pivot))), R: mul(Q, pose.R) });
+/** The face whose outward normal points most nearly down. */
+const downFace = R => AXES.reduce((best, n, k) => (dot(apply(R, n), DOWN) > dot(apply(R, AXES[best]), DOWN) ? k : best), 0);
+/** Where the plane of face k lies along its axis, and the centre's distance to it (its height when it rests on k). */
+const facePlane = (s, k) => { const a = k >> 1; return AXES[k][a] > 0 ? s.hi[a] : s.lo[a]; };
+const heightOn = (s, k) => Math.abs(facePlane(s, k) - s.com[k >> 1]);
+
+/** The spin (rad/s, world axis times rate) that takes rotation Ra to Rb in one frame at fps; capped at MAX_SPIN, none under MIN_SPIN (a hand's jitter). */
+export function spinOf(Ra, Rb, fps) {
+	const D = mul(Rb, [[Ra[0][0], Ra[1][0], Ra[2][0]], [Ra[0][1], Ra[1][1], Ra[2][1]], [Ra[0][2], Ra[1][2], Ra[2][2]]]);
+	const a = Math.acos(clamp((D[0][0] + D[1][1] + D[2][2] - 1) / 2, -1, 1));
+	if (a * fps < MIN_SPIN) return [0, 0, 0];
+	const axis = norm([D[2][1] - D[1][2], D[0][2] - D[2][0], D[1][0] - D[0][1]]), rate = Math.min(MAX_SPIN, a * fps);
+	return len(axis) > 0 ? scale(axis, rate) : [0, 0, 0];
+}
+
+/** The fall through the air from `start` onto the support top: { tl (s), at(t) } with the centre on a parabola, turning at `spin`. */
+export function airPath(s, start, spin, top, fps) {
+	const rate = len(spin), com0 = world(start, s.com);
+	const at = t => {
+		const R = rate > 0 ? mul(axisRot(spin, deg(rate * t)), start.R) : start.R;
+		return { pos: sub(add(com0, [0, -0.5 * G * t * t, 0]), apply(R, s.com)), R };
+	};
+	const h = Math.max(0, lowest(s, start) - top);
+	if (rate === 0) return { tl: Math.sqrt((2 * h) / G), at };
+	// spinning: the first sub-frame step whose lowest corner reaches the top, then halved down to the touch
+	const dt = 1 / (fps * 8), cap = Math.sqrt((2 * (h + len(sub(s.hi, s.lo)))) / G) + dt;
+	let a = 0, b = dt;
+	while (b < cap && lowest(s, at(b)) > top) { a = b; b += dt; }
+	for (let i = 0; i < 24 && b - a > 1e-7; i++) { const m = (a + b) / 2; if (lowest(s, at(m)) > top) a = m; else b = m; }
+	return { tl: b, at };
+}
+
+/** A step's duration (s): gravity-paced by the centre's height and the angle it rolls through. */
+const stepTime = (height, angle) => 0.12 + 0.9 * Math.sqrt(Math.max(height, 1e-4) / G) * Math.sqrt(angle / 90);
+
+/**
+ * From the pose it lands in, how it rolls to rest on the support top with `energy` (m of drop) to tip over edges:
+ * { steps: [{ from, pivot, axis, angle, time }], rest, time }. `lean` (horizontal) is the way a spin tips it: it gives a flat
+ * landing the energy and breaks a tie between edges.
+ */
+export function settlePath(s, impact, top, energy, lean = [0, 0, 0]) {
+	const steps = [];
+	let pose = snap(s, impact, top), time = 0;
+	const push = (pivot, axis, angle) => {
+		const height = world(pose, s.com)[1] - top, t = stepTime(height, angle);
+		steps.push({ from: pose, pivot, axis, angle, time: t });
+		pose = snap(s, about(pose, pivot, axisRot(axis, angle)), top);
+		time += t;
+	};
+	// landed on an edge or a corner: back onto the face nearest down, or over onto the face it leans to when it leans past
+	// that edge (more than the angle its centre needs to pass it), rolling about the corners on the support
+	let k = downFace(pose.R);
+	const tiltOf = j => deg(Math.acos(clamp(dot(apply(pose.R, AXES[j]), DOWN), -1, 1))), tilt = tiltOf(k);
+	if (tilt > FLAT) {
+		const side = [0, 1, 2, 3, 4, 5].filter(j => j >> 1 !== k >> 1).reduce((a, j) => (tiltOf(j) < tiltOf(a) ? j : a), k === 0 || k === 1 ? 2 : 0);
+		if (tilt > deg(Math.atan2(heightOn(s, side), heightOn(s, k)))) k = side;
+		const touching = boxCorners(s).map(p => world(pose, p)).filter(p => p[1] <= top + 1e-4);
+		const n = apply(pose.R, AXES[k]);
+		push(scale(touching.reduce(add, [0, 0, 0]), 1 / touching.length), norm(cross(n, DOWN)), tiltOf(k));
+	}
+	// over an edge onto a lower face while the landing has the energy, at once from a precarious face (or a centre past the
+	// edge); a flat landing with no spin has none
+	let left = tilt > FLAT || len(lean) > 0 ? energy : 0;
+	for (let i = 0; i < MAX_STEPS; i++) {
+		const com = world(pose, s.com), cK = com[1] - top;
+		let best = null;
+		for (let j = 0; j < 6; j++) {
+			if (j >> 1 === k >> 1) continue;
+			const out = apply(pose.R, AXES[j]), edge = world(pose, AXES[j].map((v, a) => (v ? facePlane(s, j) : a === k >> 1 ? facePlane(s, k) : s.com[a])));
+			const w = -dot(sub(com, edge), out), cJ = heightOn(s, j);
+			if (!(w < 0 || cJ < cK * (1 - LOWER))) continue;
+			const cost = w < 0 || deg(Math.atan2(w, cK)) < PRECARIOUS ? 0 : Math.hypot(cK, w) - cK, side = dot(out, lean);
+			if (!best || cost < best.cost - 1e-9 || (Math.abs(cost - best.cost) <= 1e-9 && side > best.side)) best = { j, out, edge, cost, side };
+		}
+		if (!best || best.cost > left) break;
+		left -= best.cost;
+		const touching = boxCorners(s).map(p => world(pose, p)).filter(p => p[1] <= top + 1e-4 && dot(sub(p, best.edge), best.out) >= -1e-4);
+		push(touching.length ? scale(touching.reduce(add, [0, 0, 0]), 1 / touching.length) : [best.edge[0], top, best.edge[2]], norm(cross(best.out, DOWN)), 90);
+		k = best.j;
+	}
+	return { steps, rest: pose, time };
+}
+
+/** The pose `u` seconds after it landed, along the settle path: each step rolls about its pivot, accelerating like a fall. */
+export function settledAt(path, u) {
+	let t = u;
+	for (const st of path.steps) {
+		if (t < st.time) { const s = t / st.time; return about(st.from, st.pivot, axisRot(st.axis, st.angle * s * s)); }
+		t -= st.time;
+	}
+	return path.rest;
+}
+
+/** The energy (m of drop) a spin adds: its kinetic energy over m g, for the box's radius of gyration about its centre. */
+export const spinEnergy = (s, spin) => (len(spin) ** 2 * ((s.hi[0] - s.lo[0]) ** 2 + (s.hi[1] - s.lo[1]) ** 2 + (s.hi[2] - s.lo[2]) ** 2)) / (24 * G);

package/src/motion3/skills/basic.js

@@ -0,0 +1,83 @@
+// Basic skills: stand, walk, reach-and-grip. Each reads the channel state the earlier keys
+// leave at its f0 and returns keys plus whatever anchors, props, fits and checks it needs.
+import { add, apply, ry } from "../compiler/math.js";
+import { walk } from "../compiler/walk.js";
+import { keyBook, skillError } from "./book.js";
+import { walkEnd } from "./info.js";
+
+/** standIdle({ at: [x, z], heading = 0, until }): a neutral standing pose, arms down (FK). */
+export function standIdle(ctx) {
+	const { sk, args, state } = ctx, I = sk.index, P = sk.restWorldPos, ank = P[I.LeftFoot][1];
+	const h = args.heading ?? state.yaw ?? 0, base = args.at ?? (state.root ? [state.root[0], state.root[2]] : null);
+	if (!base) skillError(ctx.tag, "needs args.at: [x, z] (no root is keyed before f0)");
+	const c = [base[0], 0, base[base.length - 1]], R = ry(h), foot = v => { const p = add(c, apply(R, v)); p[1] = ank; return p; };
+	const set = { root: [c[0], P[I.Hips][1] - 0.01, c[2]], yaw: h, pitch: 0, roll: 0, spine_yaw: 0, spine_pitch: 0, spine_roll: 0, head_yaw: 0, head_pitch: 0,
+		foot_l: foot([0.09, 0, -0.03]), foot_r: foot([-0.09, 0, 0.03]), fyaw_l: h, fyaw_r: h, fpitch_l: 0, fpitch_r: 0, knee_l: [0.05, 0, 1], knee_r: [-0.05, 0, 1],
+		armw_l: 0, armw_r: 0, aswing_l: 0, aswing_r: 0, abend_l: 0, abend_r: 0, arm_hang: 1 };
+	const keys = [{ f: ctx.f0, set }];
+	if (args.until !== undefined) keys.push({ f: args.until, set: structuredClone(set) });
+	return { keys, end: args.until ?? ctx.f0 };
+}
+
+/**
+ * walkTo({ to: [x, z] } | { heading: h | [h0, h1] }, steps, step = 0.5, turnDistance, ...): the
+ * walk generator from the pose at f0. With `to` the heading turns toward the point and the step
+ * count covers the distance. Ends 16 + steps * period + 18 frames after f0, feet together; a
+ * take that ends after the last step holds that pose to its end. The steps keep a natural rhythm
+ * (compiler/gait-rhythm.js); vary: 0 makes every step the same.
+ */
+export function walkTo(ctx) {
+	const { args, state } = ctx;
+	if (!state.foot_l || !state.foot_r || !state.root) skillError(ctx.tag, "needs a standing pose keyed before f0 (use standIdle or another skill first)");
+	const gen = { type: "walk", f0: ctx.f0, ...args };
+	delete gen.to; delete gen.arrive;
+	const h0 = state.yaw ?? 0, step = args.step ?? 0.5, first = args.firstStep ?? 0.4;
+	if (args.to) {
+		const c0 = [(state.foot_l[0] + state.foot_r[0]) / 2, (state.foot_l[2] + state.foot_r[2]) / 2];
+		const dx = args.to[0] - c0[0], dz = args.to[args.to.length - 1] - c0[1], d = Math.hypot(dx, dz);
+		let h1 = Math.atan2(dx, dz) * 180 / Math.PI;
+		while (h1 - h0 > 180) h1 -= 360;
+		while (h1 - h0 < -180) h1 += 360;
+		gen.heading = args.heading ?? [h0, h1];
+		gen.steps = args.steps ?? Math.max(2, 2 + Math.round((d - first) / step));
+	}
+	if (typeof gen.heading === "number") gen.heading = [h0, gen.heading];
+	const keys = walk(gen, ctx.keys, ctx.sk, ctx.tag), end = walkEnd(gen), last = ctx.frames - 1;
+	// the settle after the last step only holds the pose: a take that ends in it ends the walk there
+	if (end > last && Math.max(...keys.filter(k => k.f < end).map(k => k.f)) <= last) return { keys: keys.filter(k => k.f <= last), end: last, cut: `settle cut at f${last} (hold to the end)` };
+	return { keys, end };
+}
+
+/**
+ * reachGrip({ anchor, side, reach = 20, hold = 22, release = 12, elbow, fingers = "grip",
+ * define, orient = true }): the hand goes to the anchor (defined elsewhere, or by `define`) over
+ * `reach` frames with the fingers closing, holds, and lets go. Adds a fit of the fingertips on the
+ * anchor (on a body it also turns the hand into a grip, compiler/grip.js; orient: false leaves the
+ * hand's turn alone) and a contact check. A take that ends during the release holds the grip to its end.
+ */
+export function reachGrip(ctx) {
+	const { args, state } = ctx, k = args.side, name = args.anchor;
+	if (k !== "l" && k !== "r") skillError(ctx.tag, `args.side must be "l" or "r", got ${JSON.stringify(k)}`);
+	if (typeof name !== "string" || /_[lr]$/.test(name)) skillError(ctx.tag, "args.anchor must name an anchor (not ending in _l/_r)");
+	const reach = args.reach ?? 20, hold = args.hold ?? 22, release = args.release ?? 12, preset = args.fingers ?? "grip";
+	const w = `w_${name}_${k}`, fg = `fingers_${k}`, armw = `armw_${k}`, el = `elbow_${k}`, wasFk = !(state[armw] > 0.5);
+	// a take that ends after the hold but before the hand lets go cuts the release: the grip holds to the last frame
+	const last = ctx.frames - 1, cut = ctx.f0 + reach + hold <= last && ctx.f0 + reach + hold + release > last;
+	for (const [c, v] of [[w, 0], [fg, { [preset]: 0 }], [armw, 0]]) if (state[c] === undefined) state[c] = v;
+	const b = keyBook(state, ctx.f0);
+	b.hold(0, w, fg, armw, el);
+	b.at(reach, { [w]: 1, [fg]: { ...state[fg], [preset]: 1 }, [armw]: 1, ...(args.elbow ? { [el]: args.elbow } : {}) });
+	b.hold(reach + hold, w, fg, armw, el);
+	if (!cut) b.at(reach + hold + release, { [w]: 0, [fg]: { ...state[fg], [preset]: 0 }, ...(wasFk ? { [armw]: 0 } : {}) });
+	const S = k === "l" ? "Left" : "Right", prop = `${name}Grip`;
+	const def = args.define ? { [name]: args.define } : {};
+	// the hand may touch what it grips: an object, or the other person (people.js) whose joint the anchor is on
+	const a = args.define ?? ctx.anchors?.[name], obj = a?.kind === "object" ? a.object : a?.kind === "person" ? `person:${a.person}` : null;
+	return {
+		keys: b.keys, end: cut ? last : ctx.f0 + reach + hold + release, ...(cut ? { cut: `release cut at f${last} (hold to the end)` } : {}), anchors: def,
+		props: { [prop]: { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: [0, 0, 0] } } },
+		fits: [{ side: k, anchor: name, effector: { prop, point: "fingers" }, ...(args.orient === false ? { orient: false } : {}) }],
+		checks: { contacts: [{ name: `fingers on ${name}`, point: `prop:${prop}.fingers`, target: `anchor:${name}`, tol: 0.04, when: w }],
+			allow: obj ? [{ part: "hand", object: obj, depth: 0.04 }] : [] },
+	};
+}

package/src/motion3/skills/book.js

@@ -0,0 +1,76 @@
+// Skill plumbing: a key book that tracks the channel state while a skill writes keys, and the
+// placement of choreography written in a template frame (e.g. a car's own frame, driver side
+// on +X) into the scene: translate, turn by a yaw, and mirror left/right for the other side.
+import { add, apply, ry } from "../compiler/math.js";
+
+const SIDE_SWAP = { _l: "_r", _r: "_l" };
+const NEGATE_ON_MIRROR = /^(yaw|roll|spine_yaw|spine_roll|head_yaw|head_roll|fyaw_[lr]|wtwist_[lr]|wflex_[lr])$/;
+const POINT = /^(root|foot_[lr]|hand_[lr])$/, POLE = /^(knee|elbow)_[lr]$/, YAW = /^(yaw|fyaw_[lr])$/;
+
+const clone = v => (v && typeof v === "object" ? structuredClone(v) : v);
+export const swapSide = name => name.replace(/_(l|r)$/, m => SIDE_SWAP[m]).replace(/^(Left|Right)/, m => (m === "Left" ? "Right" : "Left"));
+
+/**
+ * A frame: { origin: [x,y,z], yaw (deg), mirror (bool), negate: Set of extra channels (hinge
+ * angles) to negate, names: { anchor: mirroredAnchor } }. Template points p map to
+ * origin + ry(yaw)(mirror ? [-x, y, z] : p).
+ */
+export const identityFrame = () => ({ origin: [0, 0, 0], yaw: 0, mirror: false, negate: new Set(), names: {} });
+
+const placePoint = (fr, p) => add(fr.origin, apply(ry(fr.yaw), fr.mirror ? [-p[0], p[1], p[2]] : p));
+export const placeDir = (fr, v) => (fr.mirror ? [-v[0], v[1], v[2]] : v.slice());
+
+/** A channel name in the placed frame (sides swap and anchor names rename when mirrored). */
+export function placeChannel(fr, ch) {
+	if (!fr.mirror) return ch;
+	const w = /^w_(.+)_([lr])$/.exec(ch);
+	if (w) return `w_${fr.names[w[1]] ?? w[1]}_${w[2] === "l" ? "r" : "l"}`;
+	return /_[lr]$/.test(ch) ? swapSide(ch) : ch;
+}
+
+function placeSet(fr, set) {
+	const out = {};
+	for (const [ch, v0] of Object.entries(set)) {
+		let v = clone(v0);
+		if (POINT.test(ch)) v = placePoint(fr, v);
+		else if (POLE.test(ch)) v = placeDir(fr, v);
+		else if (typeof v === "number") {
+			if (fr.mirror && (NEGATE_ON_MIRROR.test(ch) || fr.negate.has(ch))) v = -v;
+			if (YAW.test(ch)) v += fr.yaw;
+		}
+		out[placeChannel(fr, ch)] = v;
+	}
+	return out;
+}
+
+/**
+ * Keys relative to f0 (book.at(12, ...) writes frame f0 + 12). `at` and `step` take template
+ * values and place them; `hold` re-keys the current (already placed) values.
+ */
+export function keyBook(state, f0 = 0, fr = identityFrame()) {
+	const keys = [], name = ch => placeChannel(fr, ch);
+	return {
+		state, keys, frame: fr,
+		at(f, set) { const placed = placeSet(fr, set); Object.assign(state, clone(placed)); keys.push({ f: f0 + f, set: placed }); },
+		hold(f, ...names) { keys.push({ f: f0 + f, set: Object.fromEntries(names.filter(n => state[name(n)] !== undefined).map(n => [name(n), clone(state[name(n)])])) }); },
+		step(f, ch, value) {
+			const n = name(ch);
+			keys.push({ f: f0 + f - 1, set: { [n]: state[n] } });
+			state[n] = value;
+			keys.push({ f: f0 + f, set: { [n]: value }, step: [n] });
+		},
+	};
+}
+
+/** Throws the skill's own MOTION_SPEC_INVALID message. */
+export const skillError = (tag, msg) => { throw new Error(`MOTION_SPEC_INVALID: ${tag}: ${msg}`); };
+
+/** Scene box by id or a skill error naming the arg. */
+export function sceneBox(ctx, arg, id) {
+	const box = ctx.scene?.objects?.[id];
+	if (!box) skillError(ctx.tag, `args.${arg} "${id}" is not a scene object`);
+	return box;
+}
+
+/** Yaw (deg) of a box's rotation matrix about +Y. */
+export const yawOf = R => Math.atan2(R[0][2], R[2][2]) * 180 / Math.PI;