cozyclay 3.0.3 → 3.1.1

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"];

package/src/motion3/schema/topics.js

@@ -48,7 +48,7 @@ export const EXAMPLES = {
 };
 
 const UNITS = `World metres, +Y up; ${CONVENTIONS.yaw}; the character's left is +X at yaw 0. Angles in degrees.`;
-const NO_JUMP = "Without at/along it keeps its grab-frame palm offset: no jump.";
+const NO_JUMP = "No at/along: it rests in the palm, fingers closed on it. Throw/catch: throwObject, catchObject.";
 /** The objects example's carry: a grip prop and the object it holds. */
 const CARRY = { props: EXAMPLES.objects.props, objects: { cup: EXAMPLES.objects.objects.cup } };
 
@@ -70,19 +70,20 @@ export const NOTES = {
 	props: ["A prop is a set of points fixed to one hand, [d, l, n] along the palm axes; prop:<prop>.origin is the mean of its origin bones.",
 		"fits: the hand target moves so the effector (a prop point or the mean of joints), not the wrist, lands on the anchor.",
 		"A fit on a scene body also turns the hand about the forearm into a grip: a thin body (a can, a bar, a handle, a neck) across the palm, else thumb up; never past a comfortable forearm turn. A wrist you turn (wtwist/wflex) wins; fit.orient: false (reachGrip args.orient: false) turns it off.",
-		"reachGrip adds props.<anchor>Grip and its fit. Carry a scene object with objects.<id>.prop (topic objects)."],
+		"reachGrip adds props.<anchor>Grip and its fit. Carry a scene object with objects.<id>.prop (topic objects).",
+		"Do not pin a carried thing on a knuckle point: without at/along it rests in the palm and the fingers close on it (fix.grasp). objects.<id>.grasp names how: power, pinch, hook, palm, spherical (a ball). objects.<id>.mass (kg) weighs on the arm; past one hand QA says LOAD and patches in the other hand."],
 	objects: ["A hinge turns the object (a body or a group) about pivot/axis by the angle channel your keys set (degrees).",
 		"A carry follows the prop's hand: before grab the scene pose, grab..release in the hand, after release where it was let go, riding a body under it that keys or a hinge move.",
-		`No grab: in hand from frame 0; no release: to the end. ${NO_JUMP}`,
+		"No grab: in hand from frame 0; no release: to the end. No at/along: it rests in the palm, fingers closed on it.",
 		"A group (Empty) id moves all its parts; at/along pin a group's root to the palm too (an object.createKit kit). A carried object is an obstacle for the body and the scene.",
 		"A switch { visible?, level? } (no prop, no hinge field) moves nothing: it shows or hides any record (a part, a light, an effect) and sets its level, 0..4 light, glow and effect strength "
 			+ "(an unkeyed level reads 1). Hiding a group hides its parts. A carry takes level too.",
-		"keys pose a carried object in the world while it is in hand (grab <= f <= release): pos is its base (a group: its root), rot a quaternion [x, y, z, w], "
-			+ "or aim [x, y, z] the direction its +Y points (a bat's barrel), turned from how the hand holds it there, plus roll degrees about aim; no roll: the roll the arm holds most easily. "
-			+ `The object leads and the whole arm follows (the elbow swings, the forearm turns, the wrist adds the rest within ${Object.entries(WRIST_LIMITS).map(([k, [lo, hi]]) => `${k} ${lo}..${hi}`).join(", ")} deg; dev + toward the thumb); `
+		"keys pose a carried object in the world while in hand: pos its base (a group: its root), rot a quaternion [x, y, z, w], "
+			+ "or aim [x, y, z] where its +Y points (a bat's barrel) plus roll degrees about it (none: the roll the arm holds most easily). "
+			+ `The object leads and the arm follows (elbow, forearm, then the wrist within ${Object.entries(WRIST_LIMITS).map(([k, [lo, hi]]) => `${k} ${lo}..${hi}`).join(", ")} deg; dev + toward the thumb); `
 			+ "a left hand on a prop anchor of it turns with it; "
-			+ `the hand eases in and out over ${KEY_BLEND} frames. A REACH group "<id>: n cm off its keys" is what the hand could not reach; `
-			+ "output.observations.held measures every key as drawn (deg off the asked +Y, cm off pos, the drawn +Y, the rot an aim key used).",
+			+ `the hand eases in and out over ${KEY_BLEND} frames. REACH "<id>: n cm off its keys" is what the hand could not reach; `
+			+ "observations.held measures each key as drawn.",
 		"free { keys?, fall? } moves what nobody holds: keys at any frame; fall drops it at frame at onto the still top below (onto: that one; else the floor) "
 			+ "to rest on a stable face, one small bounce (0: none). A carry falls before grab or after release.",
 		"A follow { follow: <ref>, offset?, aim?, visible?, level? } puts any record (an effect, a light, a part) on a body point every frame: "

package/src/motion3/schema/types.js

@@ -86,7 +86,8 @@ export const FIT_TYPES = {
 const OBJECT_KEY_TYPES = { f: int(), pos: ref("vec3"), rot: { type: "array", items: { type: "number" }, minItems: 4, maxItems: 4, description: "quat x, y, z, w" },
 	aim: ref("vec3", "or rot: +Y dir"), roll: num("deg about aim"), lean: num("aim tilt", { minimum: 0, maximum: 45 }) };
 
-const FALL = { type: "object", properties: { at: int(), onto: str(), bounce: num(null, { default: 0.25, minimum: 0, maximum: 0.6 }), tumble: { type: "boolean" } }, required: ["at"], additionalProperties: false };
+const FALL = { type: "object", properties: { at: int(), onto: str(), bounce: num(null, { default: 0.25, minimum: 0, maximum: 0.6 }), tumble: { type: "boolean" },
+	v: { oneOf: [{ $ref: "#/$defs/vec3" }, { const: "hand" }], description: "m/s" } }, required: ["at"], additionalProperties: false };
 /** A free entry's keys and fall (C17) are a carry's, at any frame: said once, not twice. */
 const AS_CARRY = { description: "as carry; keys at any frame" };
 export const FREE_TYPES = { keys: AS_CARRY, fall: AS_CARRY };
@@ -98,6 +99,7 @@ export const OBJECT_TYPES = {
 	keys: { type: "array", items: { type: "object", properties: Object.fromEntries(OBJECT_KEY_FIELDS.map(f => [f, OBJECT_KEY_TYPES[f]])), required: ["f", "pos"], additionalProperties: false },
 		description: "world pose at f; hand follows" },
 	fall: { ...FALL, description: "or a list; topic objects" },
+	grasp: { enum: GRASPS }, mass: num("kg", { minimum: 0.01, maximum: 60 }),
 	follow: ref("ref"), offset: ref("vec3"), aim: { oneOf: [{ enum: ["face", "up"] }, { $ref: "#/$defs/vec3" }, { $ref: "#/$defs/ref" }], default: "up" },
 };
 
@@ -141,6 +143,7 @@ export const FIX_TYPES = {
 	self: bool("arms kept out of the body's skin (wrists, elbows)", { default: true }),
 	retime: bool("speed spikes borrow frames from the neighbouring keys", { default: false }),
 	stance: bool("a standIdle stance in a scene body slides out of it (observations.placed)", { default: true }),
+	grasp: bool("fingers close on what the hand holds; it rests in the hand", { default: true }),
 };
 
 export const REF_DOCS = {

package/src/motion3/seat.js

@@ -0,0 +1,84 @@
+// A carried object rests in the hand that holds it (#816). Without at/along it kept the transform it had against the
+// prop origin, the finger middles, at the grab frame: session 7f15b4ae's ball rode 2.4 cm off them, the index and middle
+// 3 cm inside it, and closing the fingers would move that origin with them. On the grasp path (a carry with no at/along,
+// or naming a carry grasp) with fix.grasp on:
+//   frame  the palm frame stands on the Hand bone: the prop origin where the bind pose has it against the hand, so
+//          closing fingers move nothing they hold (carried.js carriedPose `fixed`)
+//   seat   the grab-frame offset slides along the palm normal until the palm and the knuckles just touch the object
+//          (their skin TOUCH m off it): found once per offset by bisection on the bind hand, no frame is solved for it
+//   settle over SETTLE frames from the grab the object eases from where it rests into its seat (smoothstep)
+import { add, sub, scale, apply, T } from "./compiler/math.js";
+import { restState } from "./compiler/skeleton.js";
+import { SIDES } from "./compiler/pose.js";
+import { carriedPose, compose, relative } from "./carried.js";
+import { capsuleDepth, shapeOf } from "./shapes.js";
+
+const TOUCH = 0.002, PALM = 0.022, KNUCKLE = 0.012, NEAR = 0.04, FAR = 0.15, STEPS = 12;
+export const SETTLE = 4;
+
+/**
+ * True when carry entry o of body or group `id` rests in its hand: grasp physics on, and a carry grasp named, or no pinned
+ * at/along on one round body (a ball, a can: shapes.js). A box or a kit carried without a grasp keeps its grab-frame offset
+ * (a lantern hangs from its handle; sliding it onto the palm would push it off the fingers).
+ */
+export const seatsInHand = (spec, o, scene, id) => spec?.fix !== false && spec?.fix?.grasp !== false && !!o?.prop
+	&& (o.grasp !== undefined || (o.at === undefined && o.along === undefined && roundBody(scene, id)));
+function roundBody(scene, id) {
+	const parts = Object.entries(scene?.objects ?? {}).filter(([k, e]) => k === id || e.ancestors?.includes(id));
+	return parts.length === 1 && shapeOf(parts[0][1]).kind !== "box";
+}
+
+const seats = new WeakMap();
+
+/**
+ * The offset (in the palm frame of carry o's prop) that seats body or group `id` against the palm: `offset` moved along
+ * the palm normal until the palm (Hand to Middle1) and the knuckles (Index1 to Pinky1) touch it from outside.
+ */
+export function seatOffset(sk, spec, scene, id, o, offset) {
+	if (!seats.has(scene)) seats.set(scene, new Map());
+	const cache = seats.get(scene), key = `${id}|${o.prop}|${offset.pos.map(v => v.toFixed(6)).join(",")}`;
+	if (cache.has(key)) return cache.get(key);
+	const prop = spec.props[o.prop], side = SIDES[prop.hand], s0 = restState(sk), frame = carriedPose(sk, spec, s0, { prop: o.prop }, true);
+	const local = p => apply(T(frame.R), sub(p, frame.pos)), J = n => local(s0.P[sk.index[`${side}${n}`]]);
+	const hand = [[J("Hand"), J("HandMiddle1"), PALM], [J("HandIndex1"), J("HandPinky1"), KNUCKLE]];
+	const root = restOf(scene, id), parts = Object.entries(scene.objects).filter(([k, e]) => k === id || e.ancestors?.includes(id));
+	// slide along the palm normal (the frame's y column): out of the hand when the object is in it, in toward it when it
+	// floats off it, whichever way the depth falls; stop where the skin is TOUCH off it
+	const y = [0, 1, 0], depthAt = u => {
+		const at = { pos: add(offset.pos, scale(y, u)), R: offset.R };
+		let d = -Infinity;
+		for (const [, e] of parts) {
+			const entry = { ...e, ...compose(at, relative(root, e)) };
+			for (const [a, b, r] of hand) d = Math.max(d, capsuleDepth(entry, a, b, r));
+		}
+		return d;
+	};
+	// out of the hand is the palm's side: -n on the right hand, +n on the left (limbs.js palmAxes), the frame's y column n
+	const d0 = depthAt(0), outward = prop.hand === "l" ? 1 : -1, inside = d0 > -TOUCH;
+	// inside: the answer lies outward within FAR; floating: inward within NEAR (never past the touch)
+	let lo = 0, hi = inside ? FAR : NEAR;
+	const sign = inside ? outward : -outward;
+	if (inside || depthAt(sign * hi) > -TOUCH) {
+		for (let i = 0; i < STEPS; i++) { const mid = (lo + hi) / 2; if ((depthAt(sign * mid) > -TOUCH) === inside) lo = mid; else hi = mid; }
+	} else lo = 0;
+	const seated = { pos: add(offset.pos, scale(y, sign * (inside ? hi : lo))), R: offset.R };
+	cache.set(key, seated);
+	return seated;
+}
+
+/** The rest pose { pos, R } of a body or a group root (a group: its parts' ancestor pose). */
+export function restOf(scene, id) {
+	const e = scene.objects[id];
+	if (e) return { pos: e.pos, R: e.R };
+	const g = Object.values(scene.objects).find(x => x.ancestors?.[0] === id);
+	return g?.ancestorPoses?.[0] ?? { pos: [0, 0, 0], R: [[1, 0, 0], [0, 1, 0], [0, 0, 1]] };
+}
+
+/** How far into its seat a carried object is at absolute frame f (0 at the grab, 1 from SETTLE frames on). */
+export function settleAt(grab, f) {
+	const t = Math.min(1, Math.max(0, (f - grab) / SETTLE));
+	return t * t * (3 - 2 * t);
+}
+
+/** The world pose between `from` and `to` (same turn: the seat only slides), t of the way. */
+export const between = (from, to, t) => ({ pos: add(from.pos, scale(sub(to.pos, from.pos), t)), R: to.R });

package/src/motion3/settle.js

@@ -10,6 +10,7 @@
 // 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";
+import { flightTime } from "./flight.js";
 
 /** The share of the drop height a landing spends tipping the object over an edge. */
 export const TIP = 0.3;
@@ -54,17 +55,21 @@ export function spinOf(Ra, Rb, 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);
+/**
+ * The fall through the air from `start` onto the support top: { tl (s), at(t) } with the centre on a parabola, turning at
+ * `spin`, leaving at v0 m/s (a throw, flight.js; zero: straight down, as before).
+ */
+export function airPath(s, start, spin, top, fps, v0 = [0, 0, 0]) {
+	const rate = len(spin), com0 = world(start, s.com), still = !v0.some(v => v !== 0);
 	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 fall = still ? [0, -0.5 * G * t * t, 0] : [v0[0] * t, v0[1] * t - 0.5 * G * t * t, v0[2] * t];
+		return { pos: sub(add(com0, fall), 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 };
+	if (rate === 0) return { tl: still ? Math.sqrt((2 * h) / G) : flightTime(h, v0[1], 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;
+	const dt = 1 / (fps * 8), cap = (still ? Math.sqrt((2 * (h + len(sub(s.hi, s.lo)))) / G) : flightTime(h + len(sub(s.hi, s.lo)), v0[1], 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; }