cozyclay 3.1.6 → 3.2.1

package/src/motion3/fix/person.js

@@ -0,0 +1,110 @@
+// Person push-out (spec.fix.person, on by default): an arm capsule (upper arm, forearm, hand) inside another character
+// (scene.people, their installed take; qa/people-checks.js PERSON) moves its wrist IK target out by the depth plus a margin,
+// eased over neighbouring frames, the same way push.js takes a hand out of a box. No depth limit: a hand keyed deep into
+// someone comes out too. The escape keeps the side the hand came from: a normal that points the opposite way from the
+// previous frame's (the first frame of a pass: from their hips to mine, level), or away from my side of them (that level
+// line), is replaced by the previous one, so a hand past their axis is pulled back the way it came instead of out through
+// their back (the previous frame alone lets the normal turn a little each frame until it points through them). Fixed passes and fixed order (people by id, their
+// capsules in CAPSULES order), no time or random cut-off: the same spec gives the same take. Frames where that arm is FK
+// (armw 0) cannot be pushed and are counted as skipped. An intended touch (checks.allow { part, object: "person:<id>",
+// depth }) may go that deep.
+import { add, sub, scale, dot, len, clamp } from "../compiler/math.js";
+import { QA_LIMITS, allowance } from "../qa/checks.js";
+import { CAPSULES, segPoints } from "../qa/geometry.js";
+import { personCapsules } from "../qa/people-checks.js";
+import { round4 } from "./ease.js";
+
+const EASE = 4, MARGIN = 0.004, PASSES = 6, APART = 2.2;
+const ARM_PARTS = { l: CAPSULES.filter(c => /^(uarm|farm|hand)_l$/.test(c[0])), r: CAPSULES.filter(c => /^(uarm|farm|hand)_r$/.test(c[0])) };
+
+/** The closest points of segment PQ (sampled as qa/geometry.js segDist does, so the depth is QA's) and segment CD. */
+function closest(P, Q, C, D) {
+	const d2 = sub(D, C), dd = dot(d2, d2);
+	let best = null;
+	for (const a of segPoints(P, Q)) {
+		const u = dd < 1e-12 ? 0 : clamp(dot(sub(a, C), d2) / dd, 0, 1), b = add(C, scale(d2, u)), d = len(sub(a, b));
+		if (!best || d < best.d) best = { a, b, d };
+	}
+	return best;
+}
+
+/** Level unit vector from a to b (their hips to mine), or null when they are on top of each other. */
+function level(a, b) {
+	const v = [b[0] - a[0], 0, b[2] - a[2]], l = len(v);
+	return l > 1e-6 ? scale(v, 1 / l) : null;
+}
+
+/** The bodies to keep out of: [id, person] sorted by id, only those whose take has every capsule joint. */
+function bodies(out) {
+	return Object.entries(out.ctx?.scene?.people ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+		.filter(([, p]) => CAPSULES.every(([, a, b]) => p.names.includes(a) && p.names.includes(b)));
+}
+
+/** Per-frame push vectors for side k: the escape (side-kept normal * (depth past what is allowed + margin)) summed over people. */
+function needs(out, k, people, lim, allow, stats) {
+	const { sk } = out.ctx, I = sk.index, n = out.frames.length, f0 = out.f0 ?? 0, v = Array.from({ length: n }, () => null);
+	const prev = new Map();
+	for (let i = 0; i < n; i++) {
+		const { s, c } = out.frames[i];
+		let sum = null;
+		for (const [id, p] of people) {
+			const theirs = personCapsules(p, i + f0), hips = theirs.find(t => t[0] === "hips")[1];
+			if (len(sub(s.P[I.Hips], hips)) > APART) continue;
+			let best = null;
+			for (const [part, a, b, r] of ARM_PARTS[k]) {
+				const meant = allowance(allow, part, `person:${id}`), limit = meant ?? lim, A = s.P[I[a]], B = s.P[I[b]];
+				for (const [, C, D, q] of theirs) {
+					const hit = closest(A, B, C, D), depth = r + q - hit.d;
+					if (depth > limit && (!best || depth - (meant ?? 0) > best.need)) best = { need: depth - (meant ?? 0), hit };
+				}
+			}
+			if (!best) continue;
+			const side = level(hips, s.P[I.Hips]) ?? [0, 0, 0], ref = prev.get(id) ?? side;
+			let nrm = best.hit.d > 1e-6 ? scale(sub(best.hit.a, best.hit.b), 1 / best.hit.d) : ref;
+			if (dot(nrm, ref) < 0 || dot(nrm, side) < 0) nrm = ref;
+			prev.set(id, nrm);
+			sum = add(sum ?? [0, 0, 0], scale(nrm, best.need + MARGIN));
+		}
+		if (!sum) continue;
+		if (!(c[`armw_${k}`] > 1e-4)) { stats.skipped++; continue; }
+		v[i] = sum;
+	}
+	return v;
+}
+
+export function personOut(out, engine) {
+	const people = bodies(out);
+	if (!people.length) return null;
+	const { checks = {} } = out.ctx.spec, lim = { ...QA_LIMITS, ...checks.limits }.allow, n = out.frames.length, stats = { skipped: 0 };
+	const hit = new Set();
+	let max = 0, passes = 0;
+	for (let pass = 0; pass < PASSES; pass++) {
+		stats.skipped = 0;
+		const touched = new Set();
+		for (const k of ["l", "r"]) {
+			const v = needs(out, k, people, lim, checks.allow, stats), push = out.ctx.push[k];
+			// eased dilation of the vectors: neighbours get the strongest nearby push, scaled down (push.js)
+			const eased = Array.from({ length: n }, () => null);
+			for (let i = 0; i < n; i++) {
+				if (!v[i]) continue;
+				hit.add(`${k}${i}`);
+				for (let j = Math.max(0, i - EASE - 1); j <= Math.min(n - 1, i + EASE + 1); j++) {
+					const t = 1 - Math.abs(i - j) / (EASE + 1), w = scale(v[i], t * t * (3 - 2 * t));
+					if (!eased[j] || len(w) > len(eased[j])) eased[j] = w;
+				}
+			}
+			for (let i = 0; i < n; i++) {
+				if (!eased[i]) continue;
+				const f = out.f0 + i, next = add(push.get(f) ?? [0, 0, 0], eased[i]);
+				push.set(f, next);
+				max = Math.max(max, len(next));
+				touched.add(f);
+			}
+		}
+		if (!touched.size) break;
+		passes++;
+		engine.solve([...touched]);
+	}
+	if (!hit.size && !stats.skipped) return null;
+	return { frames: hit.size, max: round4(max), passes, skipped: stats.skipped, how: "hand pushed out of the other person, back the way it came" };
+}

package/src/motion3/free-motion.js

@@ -25,6 +25,7 @@ import { curveOf, keyedPose } from "./object-keys.js";
 import { add, apply, sub, T, quatFromMat, I3 } from "./compiler/math.js";
 import { shapeOf, airPath, settlePath, settledAt, spinOf, spinEnergy, TIP } from "./settle.js";
 import { fallVelocity, moves, flightTime, drift, landingWith } from "./flight.js";
+import { springRest, springStep, swingOf, swungPose, springLength, springOpts } from "./compiler/spring.js";
 
 /** Gravity, m/s^2. */
 export const G = 9.8;
@@ -138,24 +139,28 @@ function eventsOf(o, map, from = -Infinity, to = Infinity) {
 	return events;
 }
 
-/** The pose events give at mapped frame f, starting from pose `start`; `keep` caches each fall's plan on its event. */
-function walk(events, f, start, plan, keep = true) {
-	let pose = start;
+/**
+ * The pose events give at mapped frame f, starting from pose `start`, and whether f is on or past a fall's landing with no
+ * key lifting it since (landed: it rests and hangs from nothing): { pose, landed }. `keep` caches each fall's plan on its event.
+ */
+function walkLanded(events, f, start, plan, keep = true) {
+	let pose = start, landed = false;
 	for (const e of events) {
 		if (e.run) {
 			const { t } = e.curve;
-			if (f < t[0]) return pose;
-			if (f <= t[t.length - 1]) return keyedPose(e.curve, f);
-			pose = keyedPose(e.curve, t[t.length - 1]);
+			if (f < t[0]) return { pose, landed };
+			if (f <= t[t.length - 1]) return { pose: keyedPose(e.curve, f), landed: false };
+			pose = keyedPose(e.curve, t[t.length - 1]); landed = false;
 		} else {
-			if (f < e.fall.t) return pose;
+			if (f < e.fall.t) return { pose, landed };
 			const p = keep ? (e.plan ??= plan(pose, e.fall)) : plan(pose, e.fall);
-			if (f < p.end) return p.at(f);
-			pose = p.rest;
+			if (f < p.end) return { pose: p.at(f), landed: f >= p.land };
+			pose = p.rest; landed = true;
 		}
 	}
-	return pose;
+	return { pose, landed };
 }
+const walk = (events, f, start, plan, keep = true) => walkLanded(events, f, start, plan, keep).pose;
 
 const timelines = new WeakMap();
 /** The events of entry o under time map `map`, cached per scene, entry and span (key curves built once). */
@@ -182,6 +187,34 @@ export function freePoseAt(ctx, id, f) {
 	return walk(timelineOf(ctx, id, o, ctx.timeMap, "all"), f, { pos: rest.pos, R: rest.R }, planner(ctx, id));
 }
 
+const swings = new WeakMap();
+/**
+ * freePoseAt turned by the entry's spring (spec.objects[id].spring, compiler/spring.js), else freePoseAt: the pendulum
+ * walks frames 0..f of the unswung pose and stops dead on a fall's landing (landedAt), cached per spec, entry and time map. The one swing of a free entry: the take and
+ * refs (object-pose.js rootPoseAt) and the obstacle boxes QA and fixes read (compiler/compile.js objectTracks).
+ */
+export function freeSwungAt(ctx, id, f) {
+	const pose = freePoseAt(ctx, id, f), o = ctx.spec.objects?.[id];
+	if (!pose || !o?.spring) return pose;
+	if (!swings.has(ctx.spec)) swings.set(ctx.spec, new Map());
+	const cache = swings.get(ctx.spec);
+	let c = cache.get(id);
+	if (!c || c.map !== ctx.timeMap || c.o !== o) cache.set(id, c = { map: ctx.timeMap, o, states: [], length: springLength(partsIn(ctx.scene, id).flatMap(p => corners(ctx.scene.objects[p]))) });
+	const opts = springOpts(o.spring, ctx.spec.fps ?? 30, c.length);
+	for (let k = c.states.length; k <= f; k++) {
+		const s = springStep(k ? c.states[k - 1] : springRest(), (k === f ? pose : freePoseAt(ctx, id, k)).pos, opts);
+		// landed, it rests on its face and hangs from nothing: no swing, and none carried on (its corners stay on the surface)
+		c.states[k] = landedAt(ctx, id, k) ? { ...s, th: [0, 0], w: [0, 0] } : s;
+	}
+	return swungPose(pose, swingOf(c.states[f]));
+}
+
+/** True when free entry `id` at absolute f is on or past a fall's landing and no key has lifted it since (walkLanded). */
+function landedAt(ctx, id, f) {
+	const rest = restOf(ctx.scene, id);
+	return walkLanded(timelineOf(ctx, id, ctx.spec.objects[id], ctx.timeMap, "all"), f, { pos: rest.pos, R: rest.R }, planner(ctx, id)).landed;
+}
+
 /** Where carry `id` (entry o) is before its grab at absolute f: its scene pose, or where a fall before grab left it. */
 export function beforeGrab(ctx, id, o, f, grab) {
 	const rest = restOf(ctx.scene, id);
@@ -194,10 +227,15 @@ export function beforeGrab(ctx, id, o, f, grab) {
  * `beforePose` (a frame before the release) gives the spin it is let go with to a fall that starts right at the release.
  */
 export function afterRelease(ctx, id, o, f, release, releasePose, beforePose = null) {
+	return releaseFall(ctx, id, o, f, release, releasePose, beforePose)?.pose ?? null;
+}
+
+/** afterRelease and whether f is on or past a landing of those falls (walkLanded): { pose, landed }, or null as afterRelease. */
+export function releaseFall(ctx, id, o, f, release, releasePose, beforePose = null) {
 	const events = fallsOf(o).length ? timelineOf({ ...ctx, release }, id, o, ctx.timeMap, "after") : [];
 	// the release pose comes from the solved body, which a rebake changes: plan these falls afresh
 	const plan = (start, fall) => fallPlan(ctx.spec, ctx.scene, id, start, fall.t, fall, ctx.spec.fps ?? 30, fall.t <= release + 1 ? beforePose : null);
-	return events.length ? walk(events, f, releasePose, plan, false) : null;
+	return events.length ? walkLanded(events, f, releasePose, plan, false) : null;
 }
 
 /** True when carry entry o falls at or after its release (absolute frame; afterRelease then moves it). */

package/src/motion3/hybrid-hint.js

@@ -0,0 +1,19 @@
+// A hybrid project's rig take that stopped paying: the compile result says so in one line, so the
+// agent proposes capsule figures before more repairs instead of reading output.stuck as advisory
+// (bin/agent/studio-prompt.mjs, the hybrid cast gate).
+
+/** QA group kinds that a rig rarely repairs by more compiles: contact, collision, balance, body. */
+export const HYBRID_HARD_KINDS = Object.freeze(["LOAD", "COLLIDE", "BODY", "SELF", "PERSON"]);
+export const HYBRID_CAPSULE_HINT = "hybrid project: propose capsule figures to the user before more repairs";
+
+/**
+ * The hint for a compile in a project with this castStyle, or null. It fires in a hybrid project
+ * only on a failing take (qa.ok false), when the repair watch said stuck or cap, or when the worst
+ * non-GOAL group (qa.groups is ranked) is hard. A stuck note on a passing take (the watch's
+ * "already passed QA" polish) is no reason to leave the rig.
+ */
+export function hybridCapsuleHint(castStyle, { stuck, qa } = {}) {
+	if (castStyle !== "hybrid" || qa?.ok !== false) return null;
+	const top = (qa?.groups ?? []).find(group => group.kind !== "GOAL");
+	return stuck || HYBRID_HARD_KINDS.includes(top?.kind) ? HYBRID_CAPSULE_HINT : null;
+}

package/src/motion3/load.js

@@ -7,7 +7,8 @@
 //   observe  output.observations.load: each hand that carries something, { object, mass, maxNm, at, frames }
 //   LOAD     "<side> holds <id> at <x> N m": past QA_LIMITS-style ONE_HAND N m with no second hand on the object; its
 //            hint asks for the other hand, and when the right hand holds, a patch adds a left reachGrip that arrives at
-//            the grab on the object's face nearest the left shoulder (second-hand.js holds only a right-hand carry)
+//            the grab on the object's face nearest the left shoulder, with the other faces as candidates repair compiles
+//            and picks from (repair.js; second-hand.js holds only a right-hand carry)
 // fix.grasp false turns all three off: the take of before.
 import { add, sub, scale, norm, apply, T, len } from "./compiler/math.js";
 import { SIDES } from "./compiler/pose.js";
@@ -18,6 +19,9 @@ import { handOf, spanOf, partsOf, objectPoseAt } from "./object-pose.js";
 import { SETTLE, restOf } from "./seat.js";
 
 const REACH = 10, G = 9.81, LIGHT = 2, SAG_MAX = 0.06, SAG_PER_KG = 0.006, ONE_HAND = 25, SECOND = 0.5;
+// the left palm's axis sits a palm radius (qa/grasp-checks.js PALM) out of the face, so its skin is on it, not its bone;
+// on the 12 kg box at 0 the forearm grazed the edge (+X face: QA 42), at 0.022 none (QA 0); at most FACES candidates
+const STANDOFF = 0.022, FACES = 4;
 export const LOAD_UNITS = "load: what each hand carries, kg, and its most N m (mass x 9.81 x the shoulder-to-wrist distance across) at f; frames [first, last] held";
 
 const graspOn = spec => spec?.fix !== false && spec?.fix?.grasp !== false;
@@ -91,19 +95,21 @@ export function loadChecks(sk, out) {
 }
 
 /**
- * The anchor point (object local) for the left hand on carry id at frame f: the centre of the face nearest the left
- * shoulder, of the faces other than the bottom and the one the right palm is on (the box's other side, as two hands hold it).
+ * The anchor points (object local) for the left hand on carry id at frame f, nearest the left shoulder first: the
+ * centres of the faces other than the bottom and the one the right palm is on (the box's other side, as two hands hold
+ * it), each STANDOFF out of its face. Which face is cheapest the distance does not tell (on the 12 kg box the top won
+ * by 0.3 mm and sent the hand through the edge: QA 121, the +X face 42), so repair compiles them all (repair.js).
  */
-function otherFace(out, id, f) {
+function otherFaces(out, id, f) {
 	const { sk, scene } = out.ctx, s = out.frames[f - (out.f0 ?? 0)]?.s, pose = objectPoseAt(out, id, f), rest = restOf(scene, id);
 	const part = scene.objects[partsOf(scene, id)[0]] ?? scene.objects[id];
-	if (!s || !pose || !part?.half) return null;
+	if (!s || !pose || !part?.half) return [];
 	const toLocal = p => apply(T(pose.R), sub(p, pose.pos)), c = apply(T(rest.R), sub(add(part.pos, apply(part.R, [0, part.half[1], 0])), rest.pos));
 	const palm = toLocal(scale(add(s.P[sk.index.RightHand], s.P[sk.index.RightHandMiddle1]), 0.5)), shoulder = toLocal(s.P[sk.index.LeftArm]);
 	const faces = [0, 1, 2].flatMap(i => [-1, 1].map(sg => { const p = c.slice(); p[i] += sg * part.half[i]; return { p, i, sg }; })).filter(x => !(x.i === 1 && x.sg < 0));
 	const palmFace = faces.reduce((m, x) => (Math.abs(palm[x.i] - x.p[x.i]) < Math.abs(palm[m.i] - m.p[m.i]) ? x : m));
-	const best = faces.filter(x => x !== palmFace).reduce((m, x) => (len(sub(x.p, shoulder)) < len(sub(m.p, shoulder)) ? x : m));
-	return best.p.map(x => Math.round(x * 1000) / 1000);
+	const off = x => x.p.map((v, i) => Math.round((i === x.i ? v + x.sg * STANDOFF : v) * 1000) / 1000);
+	return faces.filter(x => x !== palmFace).map(x => ({ x, d: len(sub(x.p, shoulder)) })).sort((a, b) => a.d - b.d).slice(0, FACES).map(({ x }) => off(x));
 }
 
 export const loadHints = {
@@ -114,12 +120,13 @@ export const loadHints = {
 		const k = side === "left" ? "l" : "r", other = k === "r" ? "left" : "right", [grab] = spanOf(X.out, o), kg = massOf(X.spec, X.out.ctx.scene, id);
 		const plain = { cause: `objects.${id} (${kg.toFixed(1)} kg)`, hint: `${id} weighs ${kg.toFixed(1)} kg: ${g.worst.toFixed(0)} N m on the ${side} arm at f${g.worstFrame} (one hand holds ${ONE_HAND}); put the ${other} hand on it too (a reachGrip on an object anchor on ${id} from f${grab}), or carry it closer to the body` };
 		if (k !== "r") return plain;
-		const local = otherFace(X.out, id, Math.max(grab, Math.min(g.worstFrame, spanOf(X.out, o)[1])));
-		if (!local) return plain;
+		const faces = otherFaces(X.out, id, Math.max(grab, Math.min(g.worstFrame, spanOf(X.out, o)[1])));
+		if (!faces.length) return plain;
 		const name = `${id}Other`;
 		// a big face takes the flat palm against it (a power grip's thumb would go into the box)
-		const anchor = { kind: "object", object: id, local, grasp: "palm" };
-		return { ...plain, fix: { ops: user => [user.anchors ? { op: "add", path: `/anchors/${name}`, value: anchor } : { op: "add", path: "/anchors", value: { [name]: anchor } },
-			{ op: "add", path: "/use/-", value: { skill: "reachGrip", f0: Math.max(0, grab - REACH), args: { anchor: name, side: "l", reach: Math.min(REACH, grab) || 1, hold: Math.max(1, spanOf(X.out, o)[1] - grab), release: 1 } } }] } };
+		const ops = local => user => { const anchor = { kind: "object", object: id, local, grasp: "palm" };
+			return [user.anchors ? { op: "add", path: `/anchors/${name}`, value: anchor } : { op: "add", path: "/anchors", value: { [name]: anchor } },
+				{ op: "add", path: "/use/-", value: { skill: "reachGrip", f0: Math.max(0, grab - REACH), args: { anchor: name, side: "l", reach: Math.min(REACH, grab) || 1, hold: Math.max(1, spanOf(X.out, o)[1] - grab), release: 1 } } }]; };
+		return { ...plain, fix: { ops: ops(faces[0]), candidates: faces.map(ops) } };
 	},
 };

package/src/motion3/object-pose.js

@@ -32,8 +32,9 @@ 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, fallsAfter, corners, topOf, under, TOUCH } from "./free-motion.js";
+import { isFree, freePoseAt, freeSwungAt, beforeGrab, afterRelease, releaseFall, fallsAfter, corners, topOf, under, TOUCH } from "./free-motion.js";
 import { add } from "./compiler/math.js";
+import { springRest, springStep, swingOf, swungPose, springLength, springOpts } from "./compiler/spring.js";
 
 /**
  * Body ids that make up `id` in a motionScene: [id] for a body (plus any bodies parented under
@@ -161,12 +162,53 @@ function carriedAt(out, id, o, f) {
  * solved frame, so the carrying hand must already be solved (compiler/anchors.js).
  */
 export function rootPoseAt(out, id, f, now = null) {
+	const o = out.ctx.spec.objects?.[id];
+	if (o?.spring && isFree(o)) return freeSwungAt(freeCtx(out), id, f);
+	const pose = basePoseAt(out, id, f, now);
+	return o?.spring && pose && isCarried(o) ? swungPose(pose, springAt(out, id, o, f, now ? pose : null)) : pose;
+}
+
+const springs = new WeakMap();
+
+/**
+ * The swing [tx, tz] of spring carry `id` at absolute f (compiler/spring.js): the solver walks frames 0..f of the
+ * record's unswung pose (its anchor). Each frame's state is cached with the solved frame it was read on, and reused
+ * while frames 0..k are still those frames (a fix that re-solves a frame starts the walk again there). `nowPose`: the
+ * unswung pose of frame f while it is being solved (not cached).
+ */
+function springAt(out, id, o, f, nowPose) {
+	if (!springs.has(out)) springs.set(out, new Map());
+	const cache = springs.get(out), f0 = out.f0 ?? 0, fps = out.fps ?? out.ctx.spec.fps ?? 30, { scene } = out.ctx;
+	if (!cache.has(id)) cache.set(id, { states: [], keys: [], length: springLength(partsOf(scene, id).flatMap(p => corners(scene.objects[p]))) });
+	const c = cache.get(id), opts = springOpts(o.spring, fps, c.length), release = spanOf(out, o)[1];
+	const end = nowPose ? f - 1 : f;
+	let k = 0;
+	while (k <= end && k < c.states.length && c.keys[k] === (out.frames[k - f0] ?? null)) k += 1;
+	c.states.length = k; c.keys.length = k;
+	// let go and fallen (free-motion.js releaseFall): from its landing it rests and hangs from nothing, no swing carried on
+	const step = (prev, j, pose) => {
+		const fell = j > release ? releaseFall(...releaseArgs(out, id, o, j, release)) : null, s = springStep(prev, (pose ?? fell?.pose ?? basePoseAt(out, id, j)).pos, opts);
+		return fell?.landed ? { ...s, th: [0, 0], w: [0, 0] } : s;
+	};
+	for (; k <= end; k++) {
+		c.states[k] = step(k ? c.states[k - 1] : springRest(), k, null);
+		c.keys[k] = out.frames[k - f0] ?? null;
+	}
+	const last = end >= 0 ? c.states[end] : springRest();
+	return swingOf(nowPose ? step(last, f, nowPose) : last);
+}
+
+/** The arguments of free-motion.js afterRelease / releaseFall for carry `id` (entry o) at f past its release frame. */
+const releaseArgs = (out, id, o, f, release) => [freeCtx(out), id, o, f, release, carriedAt(out, id, o, release), release > 0 ? carriedAt(out, id, o, release - 1) : null];
+
+/** rootPoseAt before a spring swings it: where the keys and the hand put it (qa/key-checks.js measures the keys on it). */
+export function basePoseAt(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), release > 0 ? carriedAt(out, id, o, release - 1) : null) : null;
+		const after = f > release ? afterRelease(...releaseArgs(out, id, o, f, release)) : null;
 		if (after) return after;
 		const by = f > release ? riderOf(out, id) : null;
 		if (by) { const at = carriedAt(out, id, o, release); return compose(rootPoseAt(out, by, f), relative(rootPoseAt(out, by, release), at)); }

package/src/motion3/people.js

@@ -8,6 +8,8 @@ import { skeletonFor } from "./rigs/index.js";
 import { fk } from "./compiler/skeleton.js";
 import { add, apply, ry } from "./compiler/math.js";
 import { resolveBone } from "./bones.js";
+import { CAPSULES } from "./qa/geometry.js";
+import { APART } from "./qa/people-checks.js";
 
 const sampled = new WeakMap();
 // joints are kept to 1e-5 m: what a saved take keeps of them (keptPeople) is then exactly what its compile read
@@ -61,8 +63,10 @@ export const peopleList = scene => Object.entries(scene?.people ?? {}).map(([id,
  * What a take keeps of the people so that its saved source compiles the same again without the others' takes
  * (take-source.js): only the joints its person anchors and refs name (anywhere in the spec: anchors, a skill's
  * define, goals, probes; a bare person:<id> in a skill's from is that person's Hips), as plain arrays (a saved project is JSON), or null.
+ * When fix.person moved an arm (out.fixed.person.frames), every capsule joint (qa/geometry.js CAPSULES) of each person whose
+ * hips came within APART of mine is kept too, so the saved source pushes the same arm out again (fix/person.js).
  */
-export function keptPeople(scene, spec) {
+export function keptPeople(scene, spec, out) {
 	const want = new Map(), keep = (id, b) => {
 		const p = scene?.people?.[id], bone = p && resolveBone(skeletonFor(p.rig), b).bone;
 		if (bone) want.set(id, new Set([...(want.get(id) ?? []), bone]));
@@ -73,6 +77,17 @@ export function keptPeople(scene, spec) {
 		else if (v && typeof v === "object") { if (v.kind === "person") keep(v.person, v.bone); for (const [k, x] of Object.entries(v)) walk(x, k); }
 	};
 	walk(spec);
+	if (out?.fixed?.person?.frames > 0) {
+		const H = out.ctx.sk.index.Hips, f0 = out.f0 ?? 0, joints = CAPSULES.flatMap(([, a, b]) => [a, b]);
+		for (const [id, p] of Object.entries(scene?.people ?? {})) {
+			const j = p.names.indexOf(CAPSULES.find(c => c[0] === "hips")[1]), J = p.names.length;
+			const near = j >= 0 && out.frames.some(({ s }, i) => {
+				const at = (Math.max(0, Math.min(p.frames - 1, i + f0)) * J + j) * 3, h = s.P[H];
+				return Math.hypot(h[0] - p.P[at], h[1] - p.P[at + 1], h[2] - p.P[at + 2]) <= APART;
+			});
+			if (near) for (const b of joints) if (p.names.includes(b)) keep(id, b);
+		}
+	}
 	if (!want.size) return null;
 	return Object.fromEntries([...want].map(([id, bones]) => {
 		const p = scene.people[id], names = [...bones], J = p.names.length, P = [];

package/src/motion3/physics-frames.js

@@ -0,0 +1,72 @@
+// The frames QA measured, rebuilt from an installed take v3 (take.js bakeTake), for the physics overlay
+// (physics-view.js). A take keeps local bone turns and the hips in the character's placement frame, plus world
+// tracks of the objects it moves; QA read the compiler's `out`: world joint positions per frame, the skeleton and
+// the obstacle boxes per frame. takeOut gives that shape back, so the overlay calls QA's own functions (qa/com.js,
+// qa/ground.js, qa/style.js) on the pose the viewport plays, and its verdicts are QA's.
+//   frames[f].s   { P, R }: fk of the take's frame f, turned by the placement yaw and moved to its position
+//   objectsAt(f)  the authored records as motion boxes (scene.js), the way compile.js objectTracks lays them out:
+//                 a record a carry or a follow moves is not an obstacle; one a free or hinge entry moves stands
+//                 where the take's track puts its mover
+// Pure: the take and the records in, numbers out; cached per take and records.
+import { skeletonFor } from "./rigs/index.js";
+import { fk } from "./compiler/skeleton.js";
+import { add, apply, mul, ry, matFromQuat } from "./compiler/math.js";
+import { motionScene, groupsOf } from "./scene.js";
+import { isCarried, isFollow, movesRecord, compose, relative } from "./carried.js";
+import { expandUse } from "./skills/index.js";
+
+const cache = new WeakMap();
+
+/** The take's spec with its skills expanded (the checks and objects QA read), or the spec as stored when it cannot expand. */
+function expandedSpec(take, sk, scene) {
+	try { return expandUse(take.spec ?? {}, { sk, scene, lenient: true }).spec; } catch { return take.spec ?? {}; }
+}
+
+/** World pose { pos, R } of track `track` at frame f, or null when it has none there. */
+export function trackPose(track, f) {
+	if (!track?.pos || !track.quat || f < 0 || (f + 1) * 3 > track.pos.length) return null;
+	const p = track.pos, q = track.quat;
+	return { pos: [p[f * 3], p[f * 3 + 1], p[f * 3 + 2]], R: matFromQuat([q[f * 4], q[f * 4 + 1], q[f * 4 + 2], q[f * 4 + 3]]) };
+}
+
+/** The obstacle boxes of frame f (compile.js objectTracks obstacles, the movers read from the take's tracks). */
+function obstaclesAt(take, spec, scene, f) {
+	const out = {}, groups = groupsOf(scene);
+	for (const [id, o] of Object.entries(scene.objects)) {
+		const mover = [id, ...(o.ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])), entry = spec.objects?.[mover];
+		if (!entry) { out[id] = o; continue; }
+		if (isCarried(entry) || isFollow(entry)) continue;
+		const pose = trackPose(take.objects?.[mover], f), rest = scene.objects[mover] ?? groups[mover];
+		out[id] = pose && rest ? { ...o, ...compose(pose, relative(rest, o)) } : o;
+	}
+	return out;
+}
+
+/**
+ * takeOut(take, objects) -> { frames, ctx: { sk, spec, scene }, objectsAt, fps, f0, frameCount } | null: the `out`
+ * QA reads, from take v3 `take` over the authored records `objects`. null for another take or a body motion3 cannot
+ * drive. spec is the take's spec with its skills expanded.
+ */
+export function takeOut(take, objects = []) {
+	if (take?.schema !== "cozyclay.take.v3" || !(take.frameCount > 0)) return null;
+	const kept = cache.get(take);
+	if (kept && kept.objects === objects) return kept.out;
+	const sk = skeletonFor(take.rig);
+	if (!sk) return null;
+	const B = take.bones.length, slot = take.bones.map(name => sk.index[name]), yaw = ry(take.placement?.yaw ?? 0), at = take.placement?.position ?? [0, 0, 0];
+	const frames = [];
+	for (let f = 0; f < take.frameCount; f++) {
+		const quats = sk.names.map(() => [0, 0, 0, 1]);
+		for (let b = 0; b < B; b++) if (slot[b] !== undefined) quats[slot[b]] = Array.from(take.rot.subarray((f * B + b) * 4, (f * B + b) * 4 + 4));
+		const local = fk(sk, quats, Array.from(take.hips.subarray(f * 3, f * 3 + 3)));
+		frames.push({ s: { P: local.P.map(p => p && add(at, apply(yaw, p))), R: local.R.map(R => R && mul(yaw, R)) } });
+	}
+	const scene = motionScene(objects), spec = expandedSpec(take, sk, scene), boxes = new Map();
+	const objectsAt = f => {
+		if (!boxes.has(f)) boxes.set(f, obstaclesAt(take, spec, scene, Math.max(0, Math.min(take.frameCount - 1, f))));
+		return boxes.get(f);
+	};
+	const out = { frames, ctx: { sk, spec, scene }, objectsAt, fps: take.fps ?? 24, f0: 0, frameCount: take.frameCount };
+	cache.set(take, { objects, out });
+	return out;
+}

package/src/motion3/physics-trail.js

@@ -0,0 +1,45 @@
+// The physics overlay's motion trail of spring objects (spec.objects[id].spring, compiler/spring.js): the path of
+// each one's tip over the last TRAIL_FRAMES frames, read from the take's own track (what playback draws). The tip
+// is the corner of the record's boxes (its parts, for a group) farthest from its anchor, the pose's origin the
+// spring swings it about (compiler/spring.js swungPose). An object without a spring has no trail.
+// Pure and cached per view (physics-view.js).
+import { add, apply, sub, len, T } from "./compiler/math.js";
+import { trackPose } from "./physics-frames.js";
+import { groupsOf } from "./scene.js";
+import { corners } from "./free-motion.js";
+import { partsOf } from "./object-pose.js";
+
+/** How many frames back a trail reaches (the playhead's frame included). */
+export const TRAIL_FRAMES = 24;
+const tips = new WeakMap();
+
+/** [{ id, local }]: each spring object the take tracks, with its tip in its own frame. */
+function springTips(view) {
+	if (tips.has(view)) return tips.get(view);
+	const { scene, spec } = view.out.ctx, groups = groupsOf(scene), list = [];
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		const rest = scene.objects[id] ?? groups[id];
+		if (!o?.spring || !rest || !view.take.objects?.[id]?.pos) continue;
+		let local = null;
+		for (const c of partsOf(scene, id).flatMap(part => corners(scene.objects[part]))) {
+			const q = apply(T(rest.R), sub(c, rest.pos));
+			if (!local || len(q) > len(local) + 1e-9) local = q;
+		}
+		if (local) list.push({ id, local });
+	}
+	tips.set(view, list);
+	return list;
+}
+
+/** [{ id, points: [[x, y, z], ...] }]: each spring object's tip from `length` - 1 frames before `frame` up to it, oldest first. */
+export function tipTrails(view, frame, length = TRAIL_FRAMES) {
+	const last = Math.max(0, Math.min(view.out.frames.length - 1, Math.round(frame) || 0));
+	return springTips(view).map(({ id, local }) => {
+		const points = [];
+		for (let f = Math.max(0, last - length + 1); f <= last; f++) {
+			const pose = trackPose(view.take.objects[id], f);
+			if (pose) points.push(add(pose.pos, apply(pose.R, local)));
+		}
+		return { id, points };
+	});
+}

package/src/motion3/physics-view.js

@@ -0,0 +1,79 @@
+// What the physics overlay draws (src/physics-overlay.js), frame by frame, measured by QA's own functions on the
+// installed take (physics-frames.js takeOut), so the overlay's colours are QA's verdicts:
+//   comAt      the mass-weighted centre of mass (qa/com.js) and its state: "outside" when it sits farther outside
+//              the support polygon than the balance limit (checks.limits.balance, else QA_LIMITS.balance: what
+//              BALANCE reports), "inside" otherwise, "air" with no foot on the ground, "supported" where a declared
+//              support carries the body (qa/style.js balanceFrames)
+//   supportAt  the convex hull of the sole points on the ground (qa/com.js balanceAt feet), each corner on
+//              the ground QA measured that sole point from (balanceAt ground)
+//   airArcs    per air run of 4 frames or more (qa/style.js airRuns, the runs floatChecks judges): the hips path
+//              from the frame before takeoff to the frame after landing, and the gravity parabola through the same
+//              two anchors (qa/ballistic.js); float marks the runs QA calls FLOAT
+// Positions are world metres where the take was compiled (take.placement). Pure and cached per take.
+import { takeOut } from "./physics-frames.js";
+import { balanceFrames, airRuns, floatChecks } from "./qa/style.js";
+import { balanceAt, bodyCentre, convexHull } from "./qa/com.js";
+import { groundY } from "./qa/ground.js";
+import { ballisticArc } from "./qa/ballistic.js";
+import { QA_LIMITS } from "./qa/checks.js";
+
+/** floatChecks judges runs of this many frames or more. */
+const MIN_RUN = 4;
+const views = new WeakMap();
+
+/** The overlay's view of take v3 `take` over the authored records `objects`, or null when it has none. */
+export function physicsView(take, objects = []) {
+	const out = takeOut(take, objects);
+	if (!out) return null;
+	if (!views.has(out)) {
+		const checks = out.ctx.spec.checks ?? {};
+		views.set(out, { take, out, checks, limit: checks.limits?.balance ?? QA_LIMITS.balance, balance: null, arcs: null });
+	}
+	return views.get(out);
+}
+
+/** The take frame shown at timeline frame `frame` (clamped to the take). */
+const viewFrame = (view, frame) => Math.max(0, Math.min(view.out.frames.length - 1, Math.round(frame) || 0));
+
+const balanceOf = view => (view.balance ??= balanceFrames(view.out, view.checks.supports));
+
+/** { frame, p: [x, y, z], ground: the ground height under p, state, margin (m, null off the ground) } at `frame`. */
+export function comAt(view, frame) {
+	const f = viewFrame(view, frame), b = balanceOf(view)[f], measured = b && b !== "air";
+	const p = measured ? b.com : bodyCentre(view.out.ctx.sk, view.out.frames[f].s);
+	const state = b === null ? "supported" : b === "air" ? "air" : -b.margin > view.limit ? "outside" : "inside";
+	return { frame: f, p, ground: groundY(view.out, f, p), state, margin: measured ? b.margin : null };
+}
+
+/**
+ * The support polygon at `frame`: its corners [x, y, z] counter-clockwise in (x, z), y the ground QA measured that
+ * sole point from (balanceAt ground); [] with no foot down. convexHull keeps the feet's own points, so each corner
+ * finds its ground by identity.
+ */
+export function supportAt(view, frame) {
+	const f = viewFrame(view, frame), b = balanceOf(view)[f] ?? balanceAt(view.out, f);
+	if (b === "air") return [];
+	return convexHull(b.feet).map(p => [p[0], b.ground[b.feet.indexOf(p)], p[1]]);
+}
+
+/**
+ * [{ a, b, from, to, float, path, fit, worst }]: per air run [a, b], the hips path from anchor `from` (a - 1) to `to`
+ * (b + 1) and the parabola `fit` over the same frames (the hips' x and z, the arc's height); worst = the largest
+ * fit - actual height (m). A run that touches either end of the take has no anchor and no arc.
+ */
+export function airArcs(view) {
+	if (view.arcs) return view.arcs;
+	const { out, checks } = view, I = out.ctx.sk.index, hips = out.frames.map(fr => fr.s.P[I.Hips]), y = hips.map(p => p[1]);
+	const floats = new Set(floatChecks(out, checks).map(issue => issue.frame)), g = 9.81 / out.fps ** 2;
+	view.arcs = [];
+	for (const [a, b] of airRuns(out, checks.supports)) {
+		const arc = b - a + 1 >= MIN_RUN ? ballisticArc(y, a, b, g, Infinity) : null;
+		if (!arc) continue;
+		const path = hips.slice(arc.from, arc.to + 1).map(p => [...p]);
+		const fit = path.map((p, i) => (i === 0 || i === path.length - 1 ? [...p] : [p[0], p[1] + arc.delta[i - 1], p[2]]));
+		let float = true;
+		for (let f = a; f <= b; f++) float &&= floats.has(f);
+		view.arcs.push({ a, b, from: arc.from, to: arc.to, float, path, fit, worst: arc.delta[arc.worst - a] });
+	}
+	return view.arcs;
+}

package/src/motion3/pipeline.js

@@ -7,7 +7,8 @@
 // heldReadings; each hand and foot against the nearest object, qa/near.js observeNear; each holding
 // wrist's bend, qa/wrist-obs.js observeWrist; how mechanical it reads against the agent's own
 // keys, qa/motion-life.js observeLife; a skill
-// paced to fit a short span: observations.paced; a skill whose release or
+// paced to fit a short span: observations.paced; a carried spring whose base is far from the hand:
+// qa/spring-pivot.js observations.spring; a skill whose release or
 // settle the last frame cut: observations.cut; what the spec asked against what it got, per skill,
 // contact and goal: qa/asked.js observeAsked), and the timeline and the
 // requested probes read the result.
@@ -33,6 +34,7 @@ import { observeWrist, WRIST_UNITS } from "./qa/wrist-obs.js";
 import { observeLoad, LOAD_UNITS } from "./load.js";
 import { observeLife, LIFE_UNITS } from "./qa/motion-life.js";
 import { observeGait, GAIT_UNITS } from "./qa/gait-observe.js";
+import { springPivots } from "./qa/spring-pivot.js";
 import { planWalks, applyWalkPlans } from "./walk-plan.js";
 import { relaxSpec } from "./lenient.js";
 import { observeAsked } from "./qa/asked.js";
@@ -140,6 +142,8 @@ function compilePrepared(prepared, { sk, scene }, opts, notes, refusals) {
 	const placed = used.filter(u => u.placed).map(u => `${u.skill} f${u.f0}: ${u.placed.why}: at [${u.placed.at.join(", ")}], heading ${u.placed.heading}`);
 	if (placed.length) observations.placed = placed;
 	if (plans.length) observations.planned = plans.map(p => p.note);
+	const pivots = springPivots(out);
+	if (pivots) observations.spring = pivots;
 	const got = observeAsked(out, { used, use: resolved?.use, checks: measured.checks, goals: measured.goals, results: qa.goals });
 	if (got) observations.asked = got;
 	const timeline = timelineOf(out, { used, spec: expanded }), probes = asked && runProbes(out, asked, { spec: expanded, sk, scene, notes });