cozyclay 3.0.3 → 3.1.0

package/src/motion3/load.js

@@ -0,0 +1,125 @@
+// What a hand holds weighs on its arm (#816). The load on a hand is the held object's mass (mass.js) x G x the
+// horizontal distance from its shoulder to its wrist (N m), read on the solved frames:
+//   sag      a carry whose load can reach LIGHT N m (its mass at the arm's full reach) lowers the wrist target of a
+//            plain IK hand (a hand_k target: not a fit, whose passes re-solve it, nor a keyed carry, whose keys lead
+//            it) by min(SAG_MAX, SAG_PER_KG x mass) and draws it as far in toward the shoulder, so the elbow bends
+//            more; eased in over the settle from the grab and out the same before the release (seat.js SETTLE)
+//   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)
+// 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";
+import { armReach } from "./compiler/anchors.js";
+import { isCarried } from "./carried.js";
+import { massOf } from "./mass.js";
+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;
+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;
+const ease = t => { const u = Math.min(1, Math.max(0, t)); return u * u * (3 - 2 * u); };
+
+/** The carries of spec, [id, entry, hand] (hand "l" | "r"). */
+const carries = spec => Object.entries(spec.objects ?? {}).filter(([, o]) => isCarried(o) && spec.props?.[o.prop]).map(([id, o]) => [id, o, spec.props[o.prop].hand]);
+
+/**
+ * The world offset (m) the wrist target of hand k takes at frame f for what it carries, or null: ctx is the compile
+ * context (its spec, scene, sk, carrySpan), s the frame's pose so far, target the wrist target, free the share of the
+ * arm on a plain target.
+ */
+export function sagOf(ctx, k, f, s, target, free) {
+	const { spec, scene, sk } = ctx;
+	if (!graspOn(spec) || !(free > 1e-3)) return null;
+	for (const [id, o, hand] of carries(spec)) {
+		if (hand !== k || o.keys?.length) continue;
+		const mass = massOf(spec, scene, id), [grab, release] = ctx.carrySpan(o);
+		if (f < grab || f > release || mass * G * armReach(sk, k) < LIGHT) continue;
+		const w = ease((f - grab) / SETTLE) * ease((release - f) / SETTLE) * free, drop = Math.min(SAG_MAX, SAG_PER_KG * mass) * w;
+		if (!(drop > 0)) return null;
+		const toShoulder = sub(s.P[sk.index[`${SIDES[k]}Arm`]], target);
+		const across = len([toShoulder[0], 0, toShoulder[2]]) > 1e-6 ? norm([toShoulder[0], 0, toShoulder[2]]) : [0, 0, 0];
+		return add([0, -drop, 0], scale(across, drop));
+	}
+	return null;
+}
+
+/** N m on hand k on pose s holding `mass` kg. */
+const nm = (sk, s, k, mass) => { const d = sub(s.P[sk.index[`${SIDES[k]}Hand`]], s.P[sk.index[`${SIDES[k]}Arm`]]); return mass * G * Math.hypot(d[0], d[2]); };
+
+/** fn({ id, o, k, mass, f, Nm }) for each carry on each frame of out its hand holds it (grasp physics on). */
+function eachHeld(sk, out, fn) {
+	const { spec, scene } = out.ctx, f0 = out.f0 ?? 0;
+	if (!graspOn(spec)) return;
+	const list = carries(spec).map(([id, o, k]) => ({ id, o, k, mass: massOf(spec, scene, id) }));
+	if (!list.length) return;
+	out.frames.forEach(({ s }, i) => {
+		const f = i + f0;
+		for (const c of list) if (handOf(out, c.id, f) === c.k) fn({ ...c, f, Nm: nm(sk, s, c.k, c.mass) });
+	});
+}
+
+/** observeLoad(sk, out) -> { hand_l?, hand_r? } (each { object, mass, maxNm, at, frames: [first, last] }) or null. */
+export function observeLoad(sk, out) {
+	const res = {};
+	eachHeld(sk, out, ({ id, k, mass, f, Nm }) => {
+		const row = res[`hand_${k}`] ??= { object: id, mass: Math.round(mass * 1000) / 1000, maxNm: 0, at: f, frames: [f, f] };
+		if (Nm > row.maxNm) { row.maxNm = Nm; row.at = f; }
+		row.frames[1] = f;
+	});
+	for (const row of Object.values(res)) row.maxNm = Math.round(row.maxNm * 10) / 10;
+	return Object.keys(res).length ? res : null;
+}
+
+/** True when the hand other than k is on carry id (an object anchor on it or a prop anchor on its prop) at f. */
+function secondOn(out, id, o, k, f) {
+	const j = k === "r" ? "l" : "r", { spec, scene } = out.ctx, parts = new Set([id, ...partsOf(scene, id)]);
+	return Object.entries(spec.anchors ?? {}).some(([name, a]) => (out.baked?.[`w_${name}_${j}`]?.[f] ?? 0) > SECOND
+		&& ((a.kind === "object" && parts.has(a.object)) || (a.kind === "prop" && a.prop === o.prop)));
+}
+
+/** QA LOAD issues: a hand carrying past ONE_HAND N m with no second hand on the object. */
+export function loadChecks(sk, out) {
+	const issues = [];
+	eachHeld(sk, out, ({ id, o, k, f, Nm }) => {
+		if (Nm > ONE_HAND && !secondOn(out, id, o, k, f)) issues.push({ kind: "LOAD", msg: `${SIDES[k].toLowerCase()} holds ${id} at ${Nm.toFixed(0)} N m`, frame: f, value: Math.round(Nm * 10) / 10, limit: ONE_HAND });
+	});
+	return issues;
+}
+
+/**
+ * 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).
+ */
+function otherFace(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;
+	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);
+}
+
+export const loadHints = {
+	/** LOAD(X, g) -> { cause, hint, fix? }: the other hand on it; a patch when the right hand holds. */
+	LOAD(X, g) {
+		const [, side, id] = /^(left|right) holds (\S+) at/.exec(g.subject) ?? [], o = X.spec?.objects?.[id];
+		if (!o || !X.out) return null;
+		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 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 } } }] } };
+	},
+};

package/src/motion3/mass.js

@@ -0,0 +1,23 @@
+// What a scene object weighs, kg, for the arm that holds it (#816). The spec says it (spec.objects[id].mass), else a
+// small sphere is a ball (BALL kg: a baseball is 0.145), else its parts' volumes at DENSITY (wood, a filled box). A
+// group weighs what its bodies do. Never a scene record field: motion-scene entries are saved with a take (shapes.js).
+import { partsOf } from "./object-pose.js";
+import { shapeOf } from "./shapes.js";
+
+const BALL = 0.15, BALL_SIZE = 0.12, DENSITY = 400, MIN = 0.02, MAX = 60;
+
+function volumeOf(entry) {
+	const s = shapeOf(entry), h = entry.half;
+	if (s.kind === "sphere") return (4 / 3) * Math.PI * s.r ** 3;
+	if (s.kind === "cylinder") return Math.PI * s.r * s.r * s.h;
+	return 8 * h[0] * h[1] * h[2];
+}
+
+export function massOf(spec, scene, id) {
+	const given = spec?.objects?.[id]?.mass;
+	if (Number.isFinite(given)) return given;
+	const parts = partsOf(scene, id).map(k => scene.objects[k]);
+	if (parts.length === 1 && shapeOf(parts[0]).kind === "sphere" && 2 * shapeOf(parts[0]).r < BALL_SIZE) return BALL;
+	const kg = parts.reduce((sum, e) => sum + volumeOf(e) * DENSITY, 0);
+	return Math.min(MAX, Math.max(MIN, kg));
+}

package/src/motion3/object-keys.js

@@ -11,6 +11,7 @@
 // The object itself is still drawn in the hand (object-pose.js): the residual is what the arm
 // and the wrist could not reach, and QA reports it (qa/key-checks.js).
 import { isCarried, carriedPose, compose, relative } from "./carried.js";
+import { seatsInHand, seatOffset, settleAt, between as slide } from "./seat.js";
 import { groupsOf } from "./scene.js";
 import { restState } from "./compiler/skeleton.js";
 import { add, scale, sub, apply, T, matFromQuat, quatFromMat } from "./compiler/math.js";
@@ -110,7 +111,8 @@ export const keyedEntries = spec => Object.entries(spec.objects ?? {}).filter(([
 export function holdHook(ctx, out, solvePlain, solveLed) {
 	const { sk, spec, scene } = ctx, held = keyedEntries(spec);
 	if (!held.length) return null;
-	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }), attached = new WeakMap(), attaching = new Set();
+	const seated = new Set(held.map(([id]) => id).filter(id => seatsInHand(spec, spec.objects[id], scene, id)).map(id => spec.objects[id]));
+	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }, seated.has(o)), attached = new WeakMap(), attaching = new Set();
 	const restAt = (id, f) => ctx.restingAt?.(id, f) ?? scene?.objects?.[id] ?? groupsOf(scene)[id];
 	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no grasp fit, no keyed
 	// wrist at the grab) keeps the grip its keyed path holds most comfortably (grip-choice.js), solved on the plain frames with the
@@ -136,22 +138,25 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 		const cache = attached.get(out.baked), o = spec.objects[id];
 		if (cache.has(id)) return cache.get(id);
 		const picked = chosen(id);
-		if (picked && picked.name !== "today") { cache.set(id, picked.offset); return picked.offset; }
+		if (picked && picked.name !== "today") { const a = seated.has(o) ? seatOffset(sk, spec, scene, id, o, picked.offset) : picked.offset; cache.set(id, a); cache.set(`${id}|taken`, picked.offset); return a; }
 		const rest = scene?.objects?.[id] ?? groupsOf(scene)[id], group = !scene?.objects?.[id] && !!rest;
 		const keeps = o.at === undefined && o.along === undefined && (group || o.grab !== undefined);
 		// the grab frame solved without the keys: a left hand anchored on id reads it there (object-pose.js), where this offset puts it
 		attaching.add(id);
 		let s;
 		try { s = keeps ? solvePlain(spanIn(out, o)[0]).s : restState(sk); } finally { attaching.delete(id); }
-		const a = relative(palmOf(o, s), keeps ? ctx.restingAt?.(id, spanIn(out, o)[0]) ?? { pos: rest.pos, R: rest.R } : carriedPose(sk, spec, s, o));
-		cache.set(id, a);
+		const taken = relative(palmOf(o, s), keeps ? ctx.restingAt?.(id, spanIn(out, o)[0]) ?? { pos: rest.pos, R: rest.R } : carriedPose(sk, spec, s, o));
+		const a = keeps && seated.has(o) ? seatOffset(sk, spec, scene, id, o, taken) : taken;
+		cache.set(id, a); cache.set(`${id}|taken`, taken);
 		return a;
 	};
+	// on the grasp path a keyed carry's hand slides from where it took the object into its seat over the settle (seat.js)
+	const attachAt = (id, f) => { const a = attach(id), t = attached.get(out.baked)?.get(`${id}|taken`); return t && t !== a && f !== undefined ? slide(t, a, settleAt(spanIn(out, spec.objects[id])[0], f)) : a; };
 	const carryOn = (id, s) => compose(palmOf(spec.objects[id], s), attach(id));
 	const strainOn = (id, s, pose, opts) => { const o = spec.objects[id]; return holdCost(sk, s, SIDES[spec.props[o.prop].hand], compose(pose, invert(attach(id))), palmOf(o, s), opts); };
 	const heldAt = (id, o, f) => {
 		const curve = curveIn(out, id), w = leadWeight(curve, spanIn(out, o), f);
-		return w > 0 ? { w, palm: compose(keyedPose(curve, f), invert(attach(id))), measure: s => palmOf(o, s), comfort: o.keys.some(k => k.lean > 0) } : null;
+		return w > 0 ? { w, palm: compose(keyedPose(curve, f), invert(attachAt(id, f))), measure: s => palmOf(o, s), comfort: o.keys.some(k => k.lean > 0) } : null;
 	};
 	// the elbow's planned path over the frames the keys lead (hold-plan.js), once per baked channels and time map
 	const plans = new WeakMap();
@@ -263,5 +268,5 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	const firstKey = id => { const t = Math.min(...spec.objects[id].keys.map(k => k.f)); return out.timeMap ? Math.round(out.timeMap(t)) : t; };
 	// the grips chosen for keyed carries (observations.wrist reads them): [{ id, hand, name, cost, today }]
 	const grips = () => held.map(([id, o]) => { const p = chosen(id); return p && { id, hand: spec.props[o.prop].hand, name: p.name, cost: p.cost, today: p.today }; }).filter(Boolean);
-	return { lead, attach, attaching: id => attaching.has(id), plainFrame: solvePlain, carryOn, strainOn, span: id => spanIn(out, spec.objects[id]), firstKey, grips };
+	return { lead, attach, attachAt, attaching: id => attaching.has(id), plainFrame: solvePlain, carryOn, strainOn, span: id => spanIn(out, spec.objects[id]), firstKey, grips };
 }

package/src/motion3/object-pose.js

@@ -26,6 +26,7 @@
 // Carried objects are OBSTACLES at every frame, at their pose that frame (qa/object-checks.js);
 // a follow entry is none.
 import { isCarried, isFollow, carriedPose, compose, relative, movesRecord } from "./carried.js";
+import { seatsInHand, seatOffset, settleAt, between } from "./seat.js";
 import { followPose } from "./follow.js";
 import { groupsOf } from "./scene.js";
 import { solveFrame } from "./compiler/compile.js";
@@ -131,9 +132,16 @@ function carriedOn(out, id, o, f, s) {
 	if (!keepsOffset(scene, id, o)) return carriedPose(sk, spec, s, o);
 	// keyed (object-keys.js): the grab-frame offset solved without the keys, which the hand followed. While that
 	// grab frame is solved (a hand anchored on the object reads it), the object is where the offset puts it: at rest.
-	if (o.keys?.length && out.ctx.hold) return out.ctx.hold.attaching(id) ? restPose(scene, id) : compose(carriedPose(sk, spec, s, { prop: o.prop }), out.ctx.hold.attach(id));
-	const palm = st => carriedPose(sk, spec, st, { prop: o.prop }), grab = spanOf(out, o)[0];
-	return compose(palm(s), relative(palm(grab === f ? s : frameAt(out, grab).s), restingAt(out, id, grab) ?? restPose(scene, id)));
+	const seat = seatsInHand(spec, o, scene, id);
+	if (o.keys?.length && out.ctx.hold) {
+		if (out.ctx.hold.attaching(id)) return restPose(scene, id);
+		const held = compose(carriedPose(sk, spec, s, { prop: o.prop }, seat), out.ctx.hold.attachAt(id, f)), grab = spanOf(out, o)[0];
+		return seat ? between(restingAt(out, id, grab) ?? restPose(scene, id), held, settleAt(grab, f)) : held;
+	}
+	const palm = st => carriedPose(sk, spec, st, { prop: o.prop }, seat), grab = spanOf(out, o)[0];
+	const taken = relative(palm(grab === f ? s : frameAt(out, grab).s), restingAt(out, id, grab) ?? restPose(scene, id));
+	// on the grasp path the object eases into its seat against the palm (seat.js)
+	return seat ? between(compose(palm(s), taken), compose(palm(s), seatOffset(sk, spec, scene, id, o, taken)), settleAt(grab, f)) : compose(palm(s), taken);
 }
 
 /** Pose of the record a carried entry moves, cached on the solved frame. */

package/src/motion3/pipeline.js

@@ -27,6 +27,7 @@ import { canonicalGoals } from "./compiler/validate-goals.js";
 import { heldReadings, HELD_UNITS } from "./qa/key-checks.js";
 import { observeNear, NEAR_UNITS } from "./qa/near.js";
 import { observeWrist, WRIST_UNITS } from "./qa/wrist-obs.js";
+import { observeLoad, LOAD_UNITS } from "./load.js";
 import { planWalks, applyWalkPlans } from "./walk-plan.js";
 import { relaxSpec } from "./lenient.js";
 
@@ -90,6 +91,8 @@ export function compileSpec(sent, { sk, scene }, opts = {}) {
 	const near = observeNear(sk, out), wrist = observeWrist(sk, out);
 	if (near) Object.assign(observations, { units: `${observations.units}; ${NEAR_UNITS}`, near });
 	if (wrist) Object.assign(observations, { units: `${observations.units}; ${WRIST_UNITS}`, wrist });
+	const load = observeLoad(sk, out);
+	if (load) Object.assign(observations, { units: `${observations.units}; ${LOAD_UNITS}`, load });
 	// a skill that paced its beats to fit a short span says so where every answer keeps it (C7 tier 1)
 	const paced = used.filter(u => u.paced).map(u => `${u.skill} paced ${u.paced.toFixed(2)} to fit f${u.f0}..f${u.end}`);
 	if (paced.length) observations.paced = paced;

package/src/motion3/qa/explain.js

@@ -8,9 +8,11 @@ import { motionHints } from "./hints-motion.js";
 import { objectHints } from "./hints-object.js";
 import { goalHints } from "./hints-goal.js";
 import { wristHints } from "./wrist-checks.js";
+import { loadHints } from "../load.js";
+import { graspHints } from "./hints-grasp.js";
 import { attachPatches } from "./patch.js";
 
-const HINTS = { ...contactHints, ...motionHints, ...objectHints, ...goalHints, ...wristHints };
+const HINTS = { ...contactHints, ...motionHints, ...objectHints, ...goalHints, ...wristHints, ...loadHints, ...graspHints };
 
 function keyTable(out) {
 	const byCh = new Map();

package/src/motion3/qa/grasp-checks.js

@@ -0,0 +1,123 @@
+// Does the hand hold what it carries (#816)? The COLLIDE check excuses the holding hand and forearm (object-checks.js)
+// and nothing judged the fingers, so a ball riding the finger middles, through them, scored QA 0 (session 7f15b4ae).
+// On the physical-grasp path: a carry with no at/along (it rests in the hand) or naming a carry grasp, on grab..release,
+// and a fit on an object anchor with grasp while it holds (its weight and its fingers' grip at least HELD: the reach has
+// arrived and the skill has the hand closed; the object
+// still rests where it stands, so SUPPORT does not judge it). A carry pinned with at/along and no
+// grasp type (a cigarette, a lighter) keeps its preset grip and is not judged here. With fix.grasp false the carries it
+// would seat are judged as they are held (the preset grip; qa/hints-grasp.js turns grasp back on); fix: false judges none.
+// The fingers are phalanx capsules
+// (PHALANX m) against the held object's shapes (shapes.js: a ball is round, not its box):
+//   FINGER_PEN  "<Bone> into <id>": a phalanx's skin deeper than PEN in it
+//   FINGER_GAP  "<side> fingers off <id>": fewer than 3 of the 4 fingertips within GAP of its surface (pinch: the thumb
+//               and the index); the thumb and two fingers hold too (a tripod: a small ball the ring and little fingers do
+//               not reach)
+//   SUPPORT     "<id> not supported": nothing touching it from below holds its centre over its contacts (within
+//               SUPPORT_TOL across), no thumb presses against the fingers (OPPOSE deg between their contact normals)
+//               and the contacts do not enclose it (their normals no more than ENCLOSE deg apart)
+import { add, scale, dot, norm, apply } from "../compiler/math.js";
+import { isCarried } from "../carried.js";
+import { spanOf, partsOf, objectPoseAt } from "../object-pose.js";
+import { SETTLE, seatsInHand } from "../seat.js";
+import { shapeOf, normalAt, closestPoint, capsuleDepth } from "../shapes.js";
+
+const PHALANX = 0.009, PALM = 0.022, PEN = 0.004, GAP = 0.008, HELD = 0.995, SUPPORT_TOL = 0.01, OPPOSE = 120, ENCLOSE = 150, BELOW = -0.3, ARRIVED = 0.03;
+const FINGERS = ["Index", "Middle", "Ring", "Pinky"], SIDE = { l: "Left", r: "Right" };
+
+/** The grasp a held object takes when the spec names none: a sphere's hand cups it, a cylinder's wraps it. */
+function defaultGrasp(scene, id) {
+	const parts = partsOf(scene, id), kind = parts.length === 1 ? shapeOf(scene.objects[parts[0]]).kind : "box";
+	return kind === "sphere" ? "spherical" : kind === "cylinder" ? "power" : null;
+}
+
+/** The held carries and grasp fits, each { id, k (hand), grasp, from, to } in absolute frames, with the frames a fit weighs in. */
+export function heldSpans(out) {
+	const { spec: asked, scene } = out.ctx, spans = [], spec = asked.fix?.grasp === false ? { ...asked, fix: { ...asked.fix, grasp: true } } : asked;
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		// the carries grasp physics seats (with fix.grasp false: the ones it would)
+		if (!isCarried(o) || !seatsInHand(spec, o, scene, id)) continue;
+		const k = spec.props?.[o.prop]?.hand, [from, to] = spanOf(out, o);
+		// judged once the object has settled into the hand (seat.js): the grab itself is the transition
+		if (k) spans.push({ id, k, grasp: o.grasp ?? defaultGrasp(scene, id), from: from + SETTLE + 1, to });
+	}
+	for (const fit of spec.fits ?? []) {
+		const a = spec.anchors?.[fit.anchor];
+		// a rim socket (a steering wheel) keeps its rim grip: the fingers do not close on the disc the scene draws (finger-close.js)
+		if (a?.kind !== "object" || !a.grasp || out.ctx.sockets?.get(fit.anchor)?.rim) continue;
+		const ch = `w_${fit.anchor}_${fit.side}`, f0 = out.f0 ?? 0, fingers = out.baked?.[`fingers_${fit.side}`];
+		const grip = f => Object.entries(fingers?.[f] ?? {}).reduce((acc, [p, v]) => acc + (p === "relaxed" ? 0 : v || 0), 0);
+		const held = f => (out.baked?.[ch]?.[f] ?? 0) >= HELD && grip(f) >= HELD;
+		spans.push({ id: a.object, k: fit.side, grasp: a.grasp, from: f0, to: f0 + out.frames.length - 1, held, rests: true });
+	}
+	return spans;
+}
+
+const entriesAt = (out, id, f) => partsOf(out.ctx.scene, id).map(p => ({ ...out.ctx.scene.objects[p], ...objectPoseAt(out, p, f) }));
+
+function handCapsules(sk, s, k) {
+	const S = SIDE[k], P = j => s.P[sk.index[`${S}Hand${j}`]], out = [{ bone: `${S}Hand`, finger: "palm", a: s.P[sk.index[`${S}Hand`]], b: P("Middle1"), r: PALM }];
+	for (const f of [...FINGERS, "Thumb"]) for (let i = 1; i <= 3; i++) out.push({ bone: `${S}Hand${f}${i}`, finger: f, tip: i === 3, a: P(`${f}${i}`), b: P(`${f}${i + 1}`), r: PHALANX });
+	return out;
+}
+
+function contacts(capsules, entries) {
+	return capsules.map(c => {
+		let best = { depth: -Infinity };
+		for (const e of entries) { const d = capsuleDepth(e, c.a, c.b, c.r); if (d > best.depth) best = { depth: d, entry: e }; }
+		const mid = scale(add(c.a, c.b), 0.5), at = best.entry && closestPoint(best.entry, mid);
+		return { ...c, depth: best.depth, at, normal: best.entry && normalAt(best.entry, mid) };
+	});
+}
+
+function hullDistance(p, pts) {
+	if (!pts.length) return Infinity;
+	const q = [p[0], p[2]], xs = pts.map(v => [v[0], v[2]]);
+	const segDist = (a, b) => { const ab = [b[0] - a[0], b[1] - a[1]], t = Math.max(0, Math.min(1, ((q[0] - a[0]) * ab[0] + (q[1] - a[1]) * ab[1]) / ((ab[0] ** 2 + ab[1] ** 2) || 1))); return Math.hypot(q[0] - a[0] - t * ab[0], q[1] - a[1] - t * ab[1]); };
+	const hull = monotoneHull(xs);
+	if (hull.length >= 3 && hull.every((a, i) => { const b = hull[(i + 1) % hull.length]; return (b[0] - a[0]) * (q[1] - a[1]) - (b[1] - a[1]) * (q[0] - a[0]) >= 0; })) return 0;
+	return Math.min(...hull.map((a, i) => segDist(a, hull[(i + 1) % hull.length])));
+}
+function monotoneHull(points) {
+	const p = [...points].sort((a, b) => a[0] - b[0] || a[1] - b[1]), cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+	if (p.length < 3) return p;
+	const lower = [], upper = [];
+	for (const v of p) { while (lower.length >= 2 && cross(lower.at(-2), lower.at(-1), v) <= 0) lower.pop(); lower.push(v); }
+	for (const v of p.reverse()) { while (upper.length >= 2 && cross(upper.at(-2), upper.at(-1), v) <= 0) upper.pop(); upper.push(v); }
+	return [...lower.slice(0, -1), ...upper.slice(0, -1)];
+}
+
+function frameIssues(sk, s, h, entries, push, f) {
+	const touch = contacts(handCapsules(sk, s, h.k), entries), side = SIDE[h.k].toLowerCase();
+	// a reach whose hand never got there is REACH's and CONTACT's to report, not the fingers'
+	if (h.rests && touch[0].depth < -ARRIVED) return;
+	for (const c of touch) if (c.finger !== "palm" && c.depth > PEN) push("FINGER_PEN", `${c.bone} into ${h.id}`, f, c.depth, PEN);
+	const tipOn = finger => touch.some(c => c.finger === finger && c.tip && c.depth >= -GAP);
+	const fingersOn = FINGERS.filter(tipOn).length, thumb = tipOn("Thumb");
+	// a pinch holds between the thumb and the index; a small ball in a tripod (the thumb and two fingers); else three fingers
+	const gripped = h.grasp === "pinch" ? thumb && tipOn("Index") : fingersOn >= 3 || (thumb && fingersOn >= 2);
+	if (!gripped) push("FINGER_GAP", `${side} fingers off ${h.id}`, f, fingersOn + (thumb ? 1 : 0), h.grasp === "pinch" ? 2 : 3);
+	const on = touch.filter(c => c.depth >= -GAP && c.normal);
+	const c0 = scale(entries.reduce((acc, e) => add(acc, add(e.pos, apply(e.R, [0, e.half[1], 0]))), [0, 0, 0]), 1 / entries.length);
+	const under = on.filter(c => c.normal[1] <= BELOW).map(c => c.at);
+	const thumbN = on.filter(c => c.finger === "Thumb").map(c => c.normal), fingerN = on.filter(c => FINGERS.includes(c.finger)).map(c => c.normal);
+	const mean = v => (v.length ? norm(v.reduce(add, [0, 0, 0])) : null), tn = mean(thumbN), fn = mean(fingerN);
+	const opposed = tn && fn && (Math.acos(Math.max(-1, Math.min(1, dot(tn, fn)))) * 180) / Math.PI >= OPPOSE;
+	const angle = (a, b) => (Math.acos(Math.max(-1, Math.min(1, dot(a, b)))) * 180) / Math.PI;
+	const enclosed = on.some((a, i) => on.slice(i + 1).some(b => angle(a.normal, b.normal) >= ENCLOSE));
+	if (!h.rests && !opposed && !enclosed && hullDistance(c0, under) > SUPPORT_TOL) push("SUPPORT", `${h.id} not supported`, f, Math.min(1, hullDistance(c0, under)), SUPPORT_TOL);
+}
+
+/** FINGER_PEN, FINGER_GAP and SUPPORT issues of every held span (frames index out.frames, as every check's). */
+export function graspChecks(sk, out) {
+	// fix.grasp false is judged too: the hand that keeps its preset grip is what its hint turns grasp back on for
+	if (out.ctx.spec.fix === false) return [];
+	const issues = [], f0 = out.f0 ?? 0, push = (kind, msg, i, value, limit) => issues.push({ kind, msg, frame: i, value: +value.toFixed(4), limit });
+	for (const h of heldSpans(out)) {
+		for (let f = Math.max(h.from, f0); f <= Math.min(h.to, f0 + out.frames.length - 1); f++) {
+			if (h.held && !h.held(f)) continue;
+			const entries = entriesAt(out, h.id, f);
+			if (entries.length) frameIssues(sk, out.frames[f - f0].s, h, entries, push, f - f0);
+		}
+	}
+	return issues;
+}

package/src/motion3/qa/hints-grasp.js

@@ -0,0 +1,71 @@
+// Hints for the grasp kinds (#816, qa/grasp-checks.js, skills/catch.js): { cause, hint, fix? } as the other hints-*.js.
+//   FINGER_GAP  fix.grasp false: the fingers stopped at the preset; fix /fix/grasp true. Else the hand toward the object
+//   FINGER_PEN  fix.grasp false: the same fix. Else the hand out of it along its surface normal at the phalanx
+//   SUPPORT     the carry names the grasp its shape takes (sphere: spherical, cylinder: power, else palm); with
+//               fix.grasp false, grasp back on first
+//   CATCH       catchObject's f0 earlier by the frames the hand came late (the ball passed the catch point that much
+//               before the grab)
+// LOAD's hint is load.js's (the second hand).
+import { moveHint } from "./hints-contact.js";
+import { add, scale, sub, len } from "../compiler/math.js";
+import { shapeOf, normalAt, signedDistance } from "../shapes.js";
+import { partsOf, restingAt } from "../object-pose.js";
+
+const MARGIN = 0.005;
+const graspOff = X => X.spec?.fix?.grasp === false;
+const turnOn = { cause: "spec.fix.grasp false: the fingers stopped at the preset curl", hint: "turn grasp physics on (fix.grasp true): the fingers close until they touch and the thing rests in the hand", fix: { path: "/fix/grasp", value: true } };
+
+/** The held object's part entries at frame f, as drawn. */
+function heldAt(X, id, f) {
+	const { scene } = X.out.ctx, at = X.out.objectsAt?.(X.rel(f)) ?? {};
+	return partsOf(scene, id).map(p => ({ ...scene.objects[p], ...(X.out.ctx.objectPose?.(p, f) ?? at[p] ?? {}) }));
+}
+
+export const graspHints = {
+	FINGER_GAP(X, g) {
+		if (graspOff(X)) return turnOn;
+		const [, side, id] = /^(left|right) fingers off (\S+)$/.exec(g.subject) ?? [];
+		if (!id || !X.out) return null;
+		const k = side === "left" ? "l" : "r", S = side === "left" ? "Left" : "Right", f = g.worstFrame, { s } = X.fr(f);
+		const palm = scale(add(s.P[X.I[`${S}Hand`]], s.P[X.I[`${S}HandMiddle1`]]), 0.5), parts = heldAt(X, id, f);
+		if (!parts.length) return null;
+		const near = parts.reduce((m, e) => (signedDistance(e, palm) < signedDistance(m, palm) ? e : m)), gap = signedDistance(near, palm);
+		return moveHint(X, `hand_${k}`, f, scale(normalAt(near, palm), -Math.max(0, gap - 0.03)), ` (onto ${id}: the fingers reach it from nearer)`);
+	},
+	FINGER_PEN(X, g) {
+		if (graspOff(X)) return turnOn;
+		const [, bone, id] = /^(\S+) into (\S+)$/.exec(g.subject) ?? [];
+		if (!id || !X.out || X.I[bone] === undefined) return null;
+		const k = bone.startsWith("Left") ? "l" : "r", f = g.worstFrame, p = X.fr(f).s.P[X.I[bone]], parts = heldAt(X, id, f);
+		if (!parts.length) return null;
+		const into = parts.reduce((m, e) => (signedDistance(e, p) < signedDistance(m, p) ? e : m));
+		return moveHint(X, `hand_${k}`, f, scale(normalAt(into, p), g.worst - g.limit + MARGIN), ` (out of ${id})`);
+	},
+	SUPPORT(X, g) {
+		if (graspOff(X)) return turnOn;
+		const id = /^(\S+) not supported$/.exec(g.subject)?.[1], o = X.spec?.objects?.[id];
+		if (!o || !X.out) return null;
+		const part = X.out.ctx.scene.objects[partsOf(X.out.ctx.scene, id)[0]], kind = part ? shapeOf(part).kind : "box";
+		const grasp = kind === "sphere" ? "spherical" : kind === "cylinder" ? "power" : "palm";
+		if (o.grasp === grasp) return { cause: `objects.${id}.grasp ${grasp}`, hint: `${id} rests on the fingers only: hold it nearer the palm (the hand lower under it) or with both hands` };
+		return { cause: `objects.${id} (no grasp for a ${kind})`, hint: `${id}: set objects.${id}.grasp to "${grasp}" (how a ${kind} is held)`, fix: { path: `/objects/${id}/grasp`, value: grasp } };
+	},
+	CATCH(X, g) {
+		const [, id] = /^(\S+) missed by/.exec(g.subject) ?? [], o = X.spec?.objects?.[id];
+		if (!o || !X.out) return null;
+		const grab = g.worstFrame, target = X.spec.anchors?.[`${id}Catch0`]?.p;
+		if (!target) return { cause: `objects.${id}.grab`, hint: `${id}: the hand is ${(g.worst * 100).toFixed(1)} cm from it at f${grab}; reach it earlier` };
+		// the frame the flight was at the catch point: the hand came that many frames after it
+		let best = null;
+		for (let f = Math.max(0, grab - 30); f < grab; f++) {
+			const at = restingAt(X.out, id, f)?.pos;
+			if (at && (!best || len(sub(at, target)) < best.d)) best = { f, d: len(sub(at, target)) };
+		}
+		const lead = best ? grab - best.f : 0, hint = `${id}: the hand gets there ${lead} frame(s) after it passed (${(g.worst * 100).toFixed(1)} cm off at f${grab}); start catchObject ${lead} frame(s) earlier`;
+		if (!(lead > 0)) return { cause: `use catchObject ${id}`, hint };
+		return { cause: `use catchObject ${id} f0`, hint, fix: { ops: user => {
+			const i = (user.use ?? []).findIndex(u => u.skill === "catchObject" && u.args?.object === id);
+			return i < 0 ? null : [{ op: "replace", path: `/use/${i}/f0`, value: Math.max(0, user.use[i].f0 - lead) }];
+		} } };
+	},
+};

package/src/motion3/qa/index.js

@@ -7,6 +7,8 @@ import { generalChecks, QA_LIMITS } from "./checks.js";
 import { styleChecks, floatChecks } from "./style.js";
 import { specChecks } from "./spec-checks.js";
 import { objectChecks } from "./object-checks.js";
+import { graspChecks } from "./grasp-checks.js";
+import { loadChecks } from "../load.js";
 import { goalChecks } from "./goals.js";
 import { wristIssues } from "./wrist-checks.js";
 import { peopleChecks } from "./people-checks.js";
@@ -35,7 +37,7 @@ function summarizeIssues(issues) {
 export function runMotionQa(sk, out, spec, opts = {}) {
 	const checks = spec.checks ?? {}, goals = goalChecks(out, spec.goals ?? []);
 	const issues = [...generalChecks(sk, out, { allow: checks.allow, limits: checks.limits, mouthPoints: checks.mouthPoints }), ...specChecks(out, checks),
-		...objectChecks(sk, out, spec), ...floatChecks(out, checks),
+		...objectChecks(sk, out, spec), ...graspChecks(sk, out), ...loadChecks(sk, out), ...floatChecks(out, checks),
 		...styleChecks(sk, out, checks, { ...QA_LIMITS, ...checks.limits }), ...wristIssues(sk, out), ...peopleChecks(sk, out, checks), ...goals.issues];
 	if (out.f0) for (const i of issues) i.frame += out.f0;
 	const groups = summarizeIssues(issues);

package/src/motion3/qa/object-checks.js

@@ -1,6 +1,8 @@
 // QA of scene objects the spec carries (C3 and 7.1), as plain issues { kind, msg, frame, value,
 // limit } (frame indexes out.frames):
 //   GRAB     "<id>: hand 12.0 cm from it at grab", frame = grab, limit = checks.limits.grab
+//   CATCH    "<id> missed by 4.2 cm": a carry that takes it out of the air (a fall with v before the grab) is more than
+//            CATCH_GAP m from it at the grab (#816, catchObject)
 //            (default 0.03 m); the distance runs from the prop origin to the part boxes' surface
 //            at their scene pose (where the hand finds them). An object its visible channel shows
 //            only from grab on appears in the hand (a cigarette out of a pocket), and one grabbed
@@ -23,7 +25,7 @@ import { isCarried, propOrigin } from "../carried.js";
 import { objectBoxesAt, partsOf, spanOf, restingAt } from "../object-pose.js";
 import { add, sub, apply, dot, cross, len, dist, scale, norm } from "../compiler/math.js";
 
-const NEAR_SUPPORT = 3;
+const NEAR_SUPPORT = 3, CATCH_GAP = 0.03;
 
 const centre = b => add(b.pos, apply(b.R, [0, b.half[1], 0]));
 const col = (R, i) => [R[0][i], R[1][i], R[2][i]];
@@ -100,7 +102,10 @@ export function objectChecks(sk, out, spec) {
 		const [grab, release] = spanOf(out, o), k = spec.props?.[o.prop]?.hand, excused = new Set([`hand_${k}`, `farm_${k}`]);
 		if (o.grab !== undefined && grab > 0 && out.frames[grab - f0] && shownAt(out, o, grab - 1)) {
 			const gap = grabGap(out, id, grab);
-			if (gap > L.grab) push("GRAB", `${id}: hand ${(gap * 100).toFixed(1)} cm from it at grab`, grab - f0, gap, L.grab);
+			// a carry that takes a thing out of the air (a fall with v before its grab: catchObject) misses it: CATCH
+			const flying = [o.fall ?? []].flat().some(fl => Array.isArray(fl.v) && fl.at < grab);
+			if (flying && gap > CATCH_GAP) push("CATCH", `${id} missed by ${(gap * 100).toFixed(1)} cm`, grab - f0, gap, CATCH_GAP);
+			else if (!flying && gap > L.grab) push("GRAB", `${id}: hand ${(gap * 100).toFixed(1)} cm from it at grab`, grab - f0, gap, L.grab);
 		}
 		const support = o.grab !== undefined ? supportOf(out, id, grab) : null;
 		const nearSupport = f => Math.abs(f - grab) <= NEAR_SUPPORT || (o.release !== undefined && Math.abs(f - release) <= NEAR_SUPPORT);

package/src/motion3/qa/patch.js

@@ -6,6 +6,7 @@
 //   { path: "/fix/retime", value: true }                      set a spec path
 //   { path: "/anchors/cupHandle/p", delta: [dx, dy, dz] }     move a spec value by delta
 //   { channel: "root", f, delta, hold: true }                  move the body that stands at f
+//   { ops: userSpec => [{ op, path, value }] }                 the operations for the agent's spec (a second hand: load.js)
 // Each becomes g.patch = [{ op, path, value }] against opts.userSpec (the spec as the agent sent
 // it, use[] not expanded): a user key that sets the channel within f +-2 -> replace
 // /keys/<i>/set/<ch>; a standIdle stance moved sideways -> /use/<i>/args/at; otherwise add
@@ -131,7 +132,7 @@ function pathPatch(userSpec, fix) {
 
 /** The patch for one fix, or null when it does not apply mechanically or changes nothing. */
 function patchOf(fix, X, userSpec) {
-	const patch = fix.channel !== undefined ? channelPatch(X, userSpec, fix) : fix.path !== undefined ? pathPatch(userSpec, fix) : null;
+	const patch = fix.ops ? fix.ops(userSpec) : (fix.channel !== undefined ? channelPatch(X, userSpec, fix) : fix.path !== undefined ? pathPatch(userSpec, fix) : null);
 	if (!patch) return null;
 	try {
 		return JSON.stringify(applyPatch(userSpec, patch)) === JSON.stringify(userSpec) ? null : patch;

package/src/motion3/qa/spec-checks.js

@@ -12,6 +12,8 @@ import { carried } from "../compiler/limbs.js";
 import { resolveAnchor } from "../compiler/anchors.js";
 import { CAPSULES, segPoints, sdBox } from "./geometry.js";
 import { refDistance } from "../refs.js";
+import { seatsInHand } from "../seat.js";
+import { handOf } from "../object-pose.js";
 
 export function pointOf(out, f, ref) {
 	const { s, diag, c } = out.frames[f], [kind, rest] = ref.split(/:(.*)/s);
@@ -22,6 +24,12 @@ export function pointOf(out, f, ref) {
 }
 
 /** The part a contact target "anchor:<name>" holds by when that anchor takes a grasp (its socket's owner, else its object), else null. */
+/** The carry on the grasp path (seat.js) the hand of prop point `ref` holds at absolute frame f, or null (#816). */
+function seatedIn(out, ref, f) {
+	const prop = /^prop:([^.]+)\./.exec(ref)?.[1], k = out.ctx.spec.props?.[prop]?.hand, { spec, scene } = out.ctx;
+	return k ? Object.keys(spec.objects ?? {}).find(id => seatsInHand(spec, spec.objects[id], scene, id) && handOf(out, id, f) === k) ?? null : null;
+}
+
 function graspPart(out, ref) {
 	const [kind, name] = ref.split(/:(.*)/s), a = kind === "anchor" ? out.ctx.spec.anchors?.[name] : null;
 	if (a?.kind !== "object" || !a.grasp) return null;
@@ -46,7 +54,8 @@ export function specChecks(out, checks = {}) {
 			// on a grasp's anchor the fingers close on the held part wherever the grasp turned them round it: they are on it
 			// when they are on its surface (as goals' near on an object), not on one point of it (session 7f15b4ae: 0.4 cm
 			// on the cup, read as 5.3 cm from the anchor)
-			const held = graspPart(out, k.target), e = held ? refDistance(out, f, k.point, `object:${held}`) ?? len(sub(a, b)) : len(sub(a, b));
+			// and a hand that holds a thing resting in its palm (seat.js) has its fingers on that thing's surface
+			const held = graspPart(out, k.target) ?? seatedIn(out, k.point, f + (out.f0 ?? 0)), e = held ? refDistance(out, f, k.point, `object:${held}`) ?? len(sub(a, b)) : len(sub(a, b));
 			if (e > (k.tol ?? 0.01)) push("CONTACT", `${k.name}: ${(e * 100).toFixed(1)} cm apart`, f, e, k.tol ?? 0.01);
 		}
 		for (const k of checks.orient ?? []) if (active(out, f, k.when)) {

package/src/motion3/schema/fields.js

@@ -15,10 +15,10 @@ export const ANCHOR_FIELDS = { world: ["p"], body: ["p"], bone: ["bone", "offset
 export const PROP_FIELDS = ["hand", "origin", "points"];
 export const FIT_FIELDS = ["side", "anchor", "effector", "offset", "orient"];
 /** spec.objects[id]: a hinge or a carry (a body or a group id), see C3; carry keys: C14; a switch (any record, C15) moves nothing; a follow (any record, C16) rides a point of the body; a free entry (C17) moves by keys and falls. */
-export const OBJECT_FIELDS = { hinge: ["pivot", "axis", "channel"], carry: ["prop", "at", "along", "visible", "level", "grab", "release", "keys", "fall"], switch: ["visible", "level"],
+export const OBJECT_FIELDS = { hinge: ["pivot", "axis", "channel"], carry: ["prop", "at", "along", "visible", "level", "grab", "release", "keys", "fall", "grasp", "mass"], switch: ["visible", "level"],
 	follow: ["follow", "offset", "aim", "visible", "level"], free: ["keys", "fall", "visible", "level"] };
-/** One spec.objects[id].fall entry (C17): the frame it starts to fall, what it lands on, how much it bounces, whether it rolls to rest. */
-export const FALL_FIELDS = ["at", "onto", "bounce", "tumble"];
+/** One spec.objects[id].fall entry (C17): the frame it starts to fall, what it lands on, how much it bounces, whether it rolls to rest, the velocity it leaves with. */
+export const FALL_FIELDS = ["at", "onto", "bounce", "tumble", "v"];
 /** One spec.objects[id].keys entry (C14): the held object's world pose at frame f; aim (+ roll) in place of rot (C16). */
 export const OBJECT_KEY_FIELDS = ["f", "pos", "rot", "aim", "roll", "lean"];
 export const WALK_FIELDS = ["type", "f0", "steps", "step", "period", "swing", "halfWidth", "lift", "heading", "turnDistance", "pelvisHigh", "pelvisLow", "firstStep", "armSwing", "vary"];