cozyclay 3.0.2 → 3.1.0

package/src/motion3/skills/index.js

@@ -7,13 +7,16 @@ import { stateAt } from "../compiler/walk.js";
 import { didYouMean, suggestField } from "../compiler/vocab.js";
 import { USE_FIELDS } from "../schema/fields.js";
 import { SKILL_INFO } from "./info.js";
+import { fixOptions } from "../fix/index.js";
 import { standIdle, walkTo, reachGrip } from "./basic.js";
 import { sitInSeat, exitCar } from "./car.js";
 import { smokeCigarette } from "./smoke.js";
 import { flip } from "./flip.js";
 import { hitReaction } from "./impact.js";
+import { throwObject } from "./throw.js";
+import { catchObject } from "./catch.js";
 
-const SKILLS = { standIdle, sitInSeat, exitCar, walkTo, reachGrip, smokeCigarette, flip, hitReaction };
+const SKILLS = { standIdle, sitInSeat, exitCar, walkTo, reachGrip, smokeCigarette, flip, hitReaction, throwObject, catchObject };
 export const SKILL_NAMES = Object.keys(SKILLS);
 const bad = msg => { throw new Error(`MOTION_SPEC_INVALID: ${msg}`); };
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
@@ -52,7 +55,7 @@ export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
 	if (!spec.use?.length) return { spec, used: [] };
 	if (!Array.isArray(spec.use)) bad("spec.use must be an array of { skill, args, f0 }");
 	const own = (spec.keys ?? []).map((k, i) => ({ ...k, src: `keys[${i}]` }));
-	const merged = { anchors: {}, props: {}, objects: {}, fits: [], checks: {}, channels: [] }, skillKeys = [], used = [];
+	const merged = { anchors: {}, props: {}, objects: {}, fits: [], checks: {}, channels: [], fills: {}, goals: [] }, skillKeys = [], used = [];
 	spec.use.forEach((u, i) => {
 		const tag = `use[${i}] ${u?.skill}`;
 		if (!SKILLS[u?.skill]) bad(`use[${i}].skill "${u?.skill}" is not a skill${didYouMean(String(u?.skill), SKILL_NAMES)} (skills: ${SKILL_NAMES.join(", ")})`);
@@ -60,7 +63,8 @@ export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
 		argsOk(u, i, lenient);
 		if (!Number.isInteger(u.f0) || u.f0 < 0 || u.f0 > spec.frames - 1) bad(`use[${i}].f0 must be an integer frame within 0..${spec.frames - 1}, got ${JSON.stringify(u.f0)}`);
 		const keys = [...skillKeys, ...own];
-		const ctx = { sk, scene, frames: spec.frames, auto, self: spec.fix !== false && spec.fix?.self !== false, f0: u.f0, args: structuredClone(u.args ?? {}), tag, keys, state: structuredClone(stateAt(keys, u.f0)), anchors: { ...merged.anchors, ...spec.anchors } };
+		const ctx = { sk, scene, frames: spec.frames, fps: spec.fps ?? 24, auto, props: { ...merged.props, ...spec.props }, self: spec.fix !== false && spec.fix?.self !== false, f0: u.f0, args: structuredClone(u.args ?? {}), tag, keys,
+			use: spec.use, index: i, place: fixOptions(spec.fix).stance, state: structuredClone(stateAt(keys, u.f0)), anchors: { ...merged.anchors, ...spec.anchors }, objects: { ...merged.objects, ...spec.objects } };
 		const part = SKILLS[u.skill](ctx), last = Math.max(part.end ?? u.f0, ...part.keys.map(k => k.f));
 		if (last > spec.frames - 1) bad(`${tag} needs ${last - u.f0} frames from f${u.f0} (to f${last}), past the last frame f${spec.frames - 1}; set frames >= ${last + 1} or frames: "auto"`);
 		skillKeys.push(...part.keys.map(k => ({ ...k, src: k.src ?? tag })));
@@ -70,7 +74,10 @@ export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
 		for (const fit of part.fits ?? []) if (!merged.fits.some(x => same(x, fit))) merged.fits.push(fit);
 		for (const ch of part.channels ?? []) if (!merged.channels.includes(ch)) merged.channels.push(ch);
 		mergeChecks(merged.checks, part.checks);
-		used.push({ skill: u.skill, f0: u.f0, end: part.end, ...(part.paced ? { paced: part.paced } : {}), ...(part.cut ? { cut: part.cut } : {}) });
+		// fields a skill fills into an entry when it leaves them out (throwObject: a carry's release and fall)
+		for (const [id, f] of Object.entries(part.fills ?? {})) merged.fills[id] = { ...merged.fills[id], ...f };
+		merged.goals.push(...(part.goals ?? []));
+		used.push({ skill: u.skill, f0: u.f0, end: part.end, ...(part.paced ? { paced: part.paced } : {}), ...(part.cut ? { cut: part.cut } : {}), ...(part.placed ? { placed: part.placed } : {}) });
 	});
 	const out = { ...spec, keys: [...skillKeys, ...own], anchors: { ...merged.anchors, ...spec.anchors }, props: { ...merged.props, ...spec.props },
 		objects: { ...merged.objects, ...spec.objects } };
@@ -80,6 +87,8 @@ export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
 	out.fits = [...merged.fits.filter(f => !mine.some(m => m.side === f.side && m.anchor === f.anchor)), ...mine];
 	mergeChecks(merged.checks, spec.checks);
 	out.checks = merged.checks;
+	for (const [id, f] of Object.entries(merged.fills)) if (out.objects[id]) out.objects[id] = { ...f, ...out.objects[id] };
+	if (merged.goals.length) out.goals = [...merged.goals, ...(spec.goals ?? [])];
 	delete out.use;
 	return { spec: out, used };
 }

package/src/motion3/skills/info.js

@@ -19,7 +19,7 @@ const walkArgs = Object.fromEntries(WALK_FIELDS.filter(f => f !== "type" && f !=
 
 export const SKILL_INFO = {
 	standIdle: {
-		args: { at: xz("[x, z] world m; default the root keyed before f0"), heading: num("degrees (yaw); default the keyed yaw"), until: int("hold the pose to this frame") },
+		args: { at: xz("[x, z] world m; default the root keyed before f0, else within reach of the next reachGrip's anchor (output.observations.placed); a stance in a body slides out of it"), heading: num("degrees (yaw); default the keyed yaw"), until: int("hold the pose to this frame") },
 		needs: "args.at, or a root keyed before f0", frames: "1 (to args.until when given)",
 		adds: ["keys: a standing pose, FK arms down"], example: { f0: 0, args: { at: [0, 0], heading: 0 } },
 		place: { at: 0.03 },
@@ -77,4 +77,17 @@ export const SKILL_INFO = {
 			speed: num("launch speed, m/s (a shove 2, a car at 30 km/h about 8)", { default: 4, exclusiveMinimum: 0 }), land: { enum: ["back", "front"], description: "default: back when hit from the front" } },
 		needs: "a pose; dir or from", frames: "~40", adds: ["keys: thrown to rest"], example: { f0: 10, args: { dir: [0, -1], speed: 3 } },
 	},
+	throwObject: {
+		args: { object: str("the carried object's id (objects.<id>.prop on the hand's prop)"), side: side("the throwing hand (default r)"), to: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3, description: "[x, y, z] world m: where it lands" },
+			arc: { enum: ["low", "high"], description: "launch angle: low 20 deg, high 50 deg (default low)" } },
+		required: ["object", "to"], needs: "the object in that hand (its objects entry on the hand's prop)", frames: "24 (wind-up, swing, release at f0+18, follow-through)",
+		adds: ["keys: wind-up, swing, follow-through", "objects.<id>: release and fall { v: \"hand\" } when the entry leaves them out", "goals: <id> lands at the target"],
+		example: { f0: 40, args: { object: "ball", to: [0, 0, 5] } },
+	},
+	catchObject: {
+		args: { object: str("the flying object's id (objects.<id>.fall { at, v })"), side: { enum: ["r", "both"], description: "the right hand, or both (a thing over 1 kg takes both)" } },
+		required: ["object"], needs: "the object flying: objects.<id>.fall { at, v }", frames: "to the catch (the first frame in reach, at least 10 from f0) + 14",
+		adds: ["keys: reach, close, give with it", "objects.<id>: prop, grab, grasp when the entry leaves them out", "props.<id>Catch"],
+		example: { f0: 0, args: { object: "ball" } },
+	},
 };

package/src/motion3/skills/reach-human.js

@@ -0,0 +1,139 @@
+// How a person's reach to grasp unfolds in time (reachGrip's keys), from the prehension literature:
+//   transport  the wrist's speed is a single bell whose peak comes early, at about a third of the movement, and the
+//              longer deceleration (about two thirds) is the slow approach onto the object (time to peak velocity 33 %
+//              of movement time: Paulignan et al., Exp Brain Res 1991, doi:10.1007/BF00231858). A minimum-jerk bell
+//              (Flash & Hogan 1985) on time warped by t^WARP puts the peak at 0.5^(1/WARP) of the reach.
+//   grasp      the hand stays open wider than the object through the transport and closes onto it in the slow
+//              approach: the maximum grip aperture comes at about two thirds to three quarters of the movement (Jeannerod,
+//              J Mot Behav 1984; Hu et al., Exp Brain Res 2005), and it scales with the object's size (Marteniuk et al.,
+//              Hum Mov Sci 1990), a couple of centimetres wider than the object (MARGIN). These rigs' relaxed hands are
+//              already open (thumb tip to index tip: Y Bot 11.5 cm, X Bot 9.7 cm) and there is no wider preset: a thing
+//              that fits that opening with the margin (a can, a cup) is reached with the hand held open to CLOSE of the
+//              reach, then closed on it; a wider one closes along the reach as before, or the open fingers would sweep
+//              into it on the way (a 10 cm box: 6 cm deep). So does a thing that sits more than OVER m in from the near
+//              edge of what it stands on: the open fingertips hang below the hand and dragged across the table top on the
+//              way (a cup 12 cm in, bench S8). CLOSE is 0.4, earlier than a person's: the hand comes straight in, and the
+//              open fingertips (about 8 cm past the finger middles) went into a cup wrapped from the side when they
+//              stayed open later (1.5 cm at 0.7); a hand that plans an arc around the thing is the next step.
+//   gaze       the eyes go to the grasp point before the hand gets there and stay on it until the hand has it
+//              (Johansson et al., J Neurosci 2001;21:6917). The rigs have no eyes: the head turns HEAD_SHARE of the
+//              way, done by GAZE of the reach, held through the hold, back by the end of the release.
+import { add, apply, len, sub } from "../compiler/math.js";
+import { restState } from "../compiler/skeleton.js";
+import { fingers } from "../compiler/limbs.js";
+import { sdBox } from "../qa/geometry.js";
+
+const WARP = 0.65, ARM_WARP = 0.75, HEAD_SHARE = 0.75, MARGIN = 0.025, KNEE = 0.1, OVER = 0.08, BELOW = 0.12;
+export const CLOSE = 0.4, GAZE = 0.3;
+const TRANSPORT = [0.15, 0.3, 0.45, 0.6, 0.7, 0.8, 0.9];
+const minJerk = t => t * t * t * (10 - 15 * t + 6 * t * t);
+/** The share of the way the hand has come at fraction t of the reach. */
+// two phases: the fast transport covers NEAR of the way by SLOW of the time, the low-velocity approach the rest while the
+// fingers close (about half the movement time is that slow approach after peak deceleration, Paulignan et al. 1991)
+const NEAR = 0.9, SLOW = 0.7;
+const transport = (t, warp) => {
+	const u = Math.min(1, Math.max(0, t));
+	return u < SLOW ? NEAR * minJerk(Math.pow(u / SLOW, warp)) : NEAR + (1 - NEAR) * minJerk((u - SLOW) / (1 - SLOW));
+};
+/**
+ * Inner keys of the transport for a reach of n frames: [frame from f0, the target's share, the arm's IK share]. The arm's
+ * IK weight follows a milder bell (ARM_WARP): the hand is the blend of the two, and the target's bell alone on an arm
+ * blending in at its plain ease peaked at mid-reach, while both at WARP pushed a cup reach past the QA's one-frame pop.
+ */
+export const transportKeys = n => [...new Map(TRANSPORT.map(t => Math.round(t * n)).filter(f => f > 0 && f < n).map(f => [f, [transport(f / n, WARP), transport(f / n, ARM_WARP)]])).entries()].map(([f, [t, a]]) => [f, t, a]);
+
+const DEG = 180 / Math.PI, clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+/**
+ * True when the reach to anchor a takes the early-peaked transport: a thing at rest (a world point or a scene object's;
+ * a reach to a body, a bone or a prop chases a moving point) above the knees (KNEE m over the rest knee). A person
+ * reaching lower bends or crouches, which these keys do not plan: the arm alone, sped up early, swept the thigh and
+ * shin on the way to a vending tray (QA 5 -> 7), so a low reach keeps the plain ease.
+ */
+export function earlyTransport(ctx, a) {
+	const p = restPoint(ctx, a), I = ctx.sk.index;
+	return !!p && p[1] >= ctx.sk.restWorldPos[I.LeftLeg][1] + KNEE;
+}
+
+/** The world point an anchor rests at before the grab (world, or a scene object's point), or null for one that moves with a body. */
+function restPoint(ctx, a) {
+	if (a?.kind === "world" && Array.isArray(a.p)) return a.p.map(Number); // a copy, as in bodyOf
+	const o = a?.kind === "object" ? ctx.scene?.objects?.[a.object] : null;
+	if (!o || [a.object, ...(o.ancestors ?? [])].some(id => movesBy(ctx, id))) return null;
+	return add(o.pos, apply(o.R, a.local ?? [0, o.half?.[1] ?? 0, 0]));
+}
+
+/**
+ * True when spec.objects moves record `id` before the reach is done (ctx.until): a follow or a hinge, or keys or a fall
+ * from before that frame (a carry whose keys start at a grab after the hand arrives rests until then).
+ */
+function movesBy(ctx, id) {
+	const o = ctx.objects?.[id];
+	if (!o || typeof o !== "object") return false;
+	if (o.follow !== undefined || o.hinge !== undefined) return true;
+	const from = Math.min(...(o.keys ?? []).map(k => k.f).filter(Number.isFinite), o.fall?.at ?? Infinity);
+	return from < (ctx.until ?? Infinity);
+}
+
+const opened = new WeakMap();
+/** The rig's relaxed hand opening, thumb tip to index tip (m). */
+function openHand(sk) {
+	if (!opened.has(sk)) {
+		const s = restState(sk), I = sk.index;
+		fingers(sk, s, "Right", {});
+		opened.set(sk, len(sub(s.P[I.RightHandThumb4], s.P[I.RightHandIndex4])));
+	}
+	return opened.get(sk);
+}
+
+/** The scene body anchor a reaches for (its object, or the body its world point lies in), or null. */
+function bodyOf(ctx, a) {
+	const objects = ctx.scene?.objects ?? {};
+	if (a?.kind === "object") return objects[a.object]?.half ? objects[a.object] : null;
+	if (a?.kind !== "world" || !Array.isArray(a.p)) return null;
+	// a copy: the spec's own (frozen) array passed into the shared vector math deoptimised it for the whole compile (2x)
+	const p = a.p.map(Number);
+	return Object.values(objects).filter(o => o.half && sdBox(p, o) <= 0.01).sort((x, y) => sdBox(p, x) - sdBox(p, y))[0] ?? null;
+}
+
+/** True when, OVER m short of point p toward the character (root r), the hand is still above a surface within BELOW m under p. */
+function overSupport(ctx, p, r, skip) {
+	const dx = r[0] - p[0], dz = r[2] - p[2], d = Math.hypot(dx, dz);
+	if (d < 1e-6) return false;
+	const q = [p[0] + (dx / d) * OVER, p[1], p[2] + (dz / d) * OVER];
+	return Object.entries(ctx.scene?.objects ?? {}).some(([id, o]) => {
+		if (!o.half || skip.has(id) || skip.has(o.parent)) return false;
+		const top = sub(q, [0, BELOW, 0]);
+		return sdBox(q, o) > 0 && sdBox(top, o) <= 0;
+	});
+}
+
+/**
+ * True when the hand stays open on the way to the thing anchor a reaches for, from the pose at f0 (state): it fits the
+ * rig's open hand with MARGIN, and the hand's last OVER m to it are not over the surface it rests on.
+ */
+export function holdsOpen(ctx, a, state) {
+	const o = bodyOf(ctx, a), p = restPoint(ctx, a) ?? (o && add(o.pos, apply(o.R, [0, o.half[1], 0])));
+	if (!o || !p || 2 * Math.min(...o.half) + MARGIN > openHand(ctx.sk)) return false;
+	const skip = new Set(Object.entries(ctx.scene.objects).filter(([, x]) => x === o).map(([id]) => id));
+	return !(Array.isArray(state.root) && overSupport(ctx, p, state.root, skip));
+}
+
+/**
+ * The head's yaw and pitch (deg, the head's own channels) that turn the gaze HEAD_SHARE of the way onto anchor a from the
+ * pose at f0 (state), or null when the anchor moves with a body or the pose has no root.
+ */
+export function gazeAt(ctx, a, state) {
+	const p = restPoint(ctx, a), r = state.root;
+	if (!p || !Array.isArray(r)) return null;
+	const P = ctx.sk.restWorldPos, I = ctx.sk.index, eye = [r[0], r[1] + P[I.Head][1] - P[I.Hips][1], r[2]];
+	const d = [p[0] - eye[0], p[1] - eye[1], p[2] - eye[2]], flat = Math.hypot(d[0], d[2]);
+	if (flat < 0.05) return null;
+	let yaw = Math.atan2(d[0], d[2]) * DEG - (state.yaw ?? 0) - (state.spine_yaw ?? 0);
+	while (yaw > 180) yaw -= 360;
+	while (yaw < -180) yaw += 360;
+	const down = Math.atan2(-d[1], flat) * DEG - (state.pitch ?? 0) - (state.spine_pitch ?? 0);
+	return { head_yaw: clamp(HEAD_SHARE * yaw, -60, 60), head_pitch: clamp(HEAD_SHARE * down, -30, 50) };
+}
+
+/** True when keys before this skill already move the head within [a, b]: a keyed look wins. */
+export const headKeyed = (keys, a, b) => keys.some(k => k.f >= a && k.f <= b && (k.set?.head_yaw !== undefined || k.set?.head_pitch !== undefined));

package/src/motion3/skills/stance.js

@@ -0,0 +1,92 @@
+// Where a standing body stands (standIdle): clear of the scene's bodies, and within reach of what it reaches for.
+// Session 7f15b4ae: every cup and ball attempt stood with a foot in the table (COLLIDE foot_r x cube over the whole
+// take) and the arm at full reach, while QA's hint already said how far to move the body; the agent kept guessing
+// `at` by hand. Two rules:
+//   clear   a stance whose legs, feet or hips are inside a body (a table, a box on the floor) slides out of it, the
+//           least distance that clears it by MARGIN: straight back first, then sideways, then the diagonals
+//   reach   standIdle with no `at` (and no root keyed) before a reachGrip in the same spec keeps its heading and steps
+//           up to the anchor: the reaching shoulder in line with it, as near as COMFORT of the arm's length allows,
+//           then back out of whatever is in the way (it stands at a table's edge)
+// The body is the rest pose's legs, feet and hips as capsules (qa/geometry.js radii); a body whose top is under
+// SUPPORT m (a floor, a mat, a low step) is stood on, not stood clear of.
+import { add, sub, len, apply, ry } from "../compiler/math.js";
+import { sdBox } from "../qa/geometry.js";
+import { partsOf } from "../object-pose.js";
+
+const MARGIN = 0.01, SUPPORT = 0.12, COMFORT = 0.8, SLIDE = 0.6, STEP = 0.01, NEAREST = 0.15, HANG = 0.62;
+// [from, to, radius] of the standing body, as in qa/geometry.js CAPSULES (the foot: ankle to the toe tip)
+const PARTS = ["Left", "Right"].flatMap(S => [[`${S}UpLeg`, `${S}Leg`, 0.07], [`${S}Leg`, `${S}Foot`, 0.05], [`${S}Foot`, `${S}ToeBase`, 0.045], [`${S}ToeBase`, `${S}Toe_End`, 0.04]])
+	.concat([["LeftUpLeg", "RightUpLeg", 0.095], ["Hips", "Spine2", 0.12]]);
+const DIRS = [[0, -1], [1, 0], [-1, 0], [Math.SQRT1_2, -Math.SQRT1_2], [-Math.SQRT1_2, -Math.SQRT1_2]];
+
+/** The standing body's sample points [p, r] at ground point c = [x, z] facing heading h (deg): legs, feet, hips and the arms hanging at the sides (standIdle's FK arms down). */
+function bodyPoints(sk, c, h) {
+	const I = sk.index, P = sk.restWorldPos, hip = P[I.Hips], R = ry(h), at = p => add([c[0], 0, c[1]], apply(R, [p[0] - hip[0], p[1], p[2] - hip[2]]));
+	const seg = (A, B, r) => [0, 0.25, 0.5, 0.75, 1].map(t => [add(A, sub(B, A).map(v => v * t)), r]);
+	const arms = ["Left", "Right"].flatMap(S => { const sh = P[I[`${S}Arm`]], side = Math.sign(sh[0] - hip[0]) * 0.04; return seg(at(sh), at([sh[0] + side, sh[1] - HANG, sh[2]]), 0.045); });
+	return PARTS.filter(([a, b]) => I[a] !== undefined && I[b] !== undefined).flatMap(([a, b, r]) => seg(at(P[I[a]]), at(P[I[b]]), r)).concat(arms);
+}
+
+/** The bodies a stance must stay clear of: every scene body whose top is above SUPPORT m. */
+const obstacles = scene => Object.values(scene?.objects ?? {}).filter(o => o.half && o.pos && o.R && o.pos[1] + 2 * o.half[1] * o.R[1][1] > SUPPORT);
+
+/** How far the body at c, h is clear of the obstacles (m; negative: inside one by that much, past MARGIN). */
+function clearance(sk, boxes, c, h) {
+	let worst = Infinity;
+	for (const [p, r] of bodyPoints(sk, c, h)) for (const b of boxes) worst = Math.min(worst, sdBox(p, b) - r - MARGIN);
+	return worst;
+}
+
+/** A stance at c ([x, z]) facing h moved the least distance out of the scene's bodies: { at, moved } or null when it is clear. */
+export function clearStance(sk, scene, c, h) {
+	const boxes = obstacles(scene);
+	if (!boxes.length || clearance(sk, boxes, c, h) >= 0) return null;
+	const R = ry(h);
+	for (let d = STEP; d <= SLIDE + 1e-9; d += STEP) {
+		for (const [x, z] of DIRS) {
+			const v = apply(R, [x * d, 0, z * d]), at = [c[0] + v[0], c[1] + v[2]];
+			if (clearance(sk, boxes, at, h) >= 0) return { at: at.map(n => +n.toFixed(4)), moved: +d.toFixed(2) };
+		}
+	}
+	return null;
+}
+
+/**
+ * The world point an anchor definition names on the still scene, as anchors.js resolves it: world p; an object's (or a
+ * group's) `local` point, its base pivot without one; with `grasp` and no `local`, the centre of its parts (where a
+ * thin part's socket sits). Null for any other kind.
+ */
+function anchorPoint(scene, a) {
+	if (a?.kind === "world" && Array.isArray(a.p)) return a.p;
+	if (a?.kind !== "object" || !scene) return null;
+	const o = scene.objects?.[a.object] ?? scene.groups?.[a.object];
+	if (!o) return null;
+	if (!a.grasp || a.local) return add(o.pos, apply(o.R, a.local ?? [0, 0, 0]));
+	const parts = partsOf(scene, a.object).map(id => scene.objects[id]).filter(p => p?.half);
+	const centres = parts.map(p => add(p.pos, apply(p.R, [0, p.half[1], 0])));
+	return centres.reduce((m, p) => add(m, p.map(v => v / centres.length)), [0, 0, 0]);
+}
+
+/**
+ * The stance for a standIdle with no `at`: the first reachGrip after it in `use` (index i) and its anchor. The body
+ * keeps its facing (args.heading, else the keyed yaw, else 0: the agent turns it by heading) and steps up to the
+ * anchor: the reaching shoulder lined up with it, COMFORT of the arm's length from it (at least NEAREST m ahead), then
+ * straight back out of any body in the way (a table: the body stands at its edge). { at, heading, anchor, moved } or
+ * null when no reachGrip follows or its anchor has no still point.
+ */
+export function reachStance(ctx) {
+	const { sk, scene, use = [], index = -1 } = ctx, next = use.slice(index + 1).find(u => u?.skill === "reachGrip");
+	const a = next && (next.args?.define ?? ctx.anchors?.[next.args?.anchor]), T = anchorPoint(scene, a);
+	if (!T) return null;
+	const I = sk.index, P = sk.restWorldPos, S = next.args.side === "l" ? "Left" : "Right", hip = P[I.Hips], sh = P[I[`${S}Arm`]];
+	const arm = len(sub(P[I[`${S}ForeArm`]], sh)) + len(sub(P[I[`${S}Hand`]], P[I[`${S}ForeArm`]])) + len(sub(P[I[`${S}HandMiddle2`]], P[I[`${S}Hand`]]));
+	const dy = sh[1] - T[1], ahead = Math.max(NEAREST, Math.sqrt(Math.max(0, (COMFORT * arm) ** 2 - dy * dy)));
+	const h = ctx.args.heading ?? ctx.state?.yaw ?? 0, R = ry(h), boxes = obstacles(scene);
+	const off = apply(R, [sh[0] - hip[0], 0, sh[2] - hip[2] + ahead]), c0 = [T[0] - off[0], T[2] - off[2]];
+	let moved = 0, c = c0;
+	for (; moved <= SLIDE + 1e-9 && clearance(sk, boxes, c, h) < 0; moved += STEP) {
+		const back = apply(R, [0, 0, -(moved + STEP)]);
+		c = [c0[0] + back[0], c0[1] + back[2]];
+	}
+	return { at: c.map(n => +n.toFixed(4)), heading: h, anchor: next.args.anchor, moved: +moved.toFixed(2) };
+}

package/src/motion3/skills/throw.js

@@ -0,0 +1,72 @@
+// throwObject: the hand throws what it carries at a point (#816). From the pose at f0 the arm winds up behind the shoulder,
+// swings forward and lets go, then follows through. The launch is closed form: the arc's launch angle (low LOW deg, high
+// HIGH deg) and the speed that carries the object from where the hand lets it go to args.to under G (free-motion.js). The
+// last frame before the release and the release frame put the wrist one frame's travel apart along that velocity, so the
+// wrist moves at the launch velocity there; the fall the skill writes leaves at that velocity, { at: release, v } (flight.js).
+// Not v: "hand": the hand's turn as the elbow opens adds a whip to the object (about 2 m/s at the release, so the throw
+// carried 2 m long), which only the solved frames know; "hand" stays for an agent's own release. It writes the carry's release and fall (fills: fields the agent's own entry leaves out) and a goal: the
+// object near args.to at its landing. A release with no fall stays where the hand let it go (C3), so the skill writes one.
+import { add, sub, scale, apply, ry, len } from "../compiler/math.js";
+import { G } from "../free-motion.js";
+import { skillError } from "./book.js";
+import { GRASP_FINGERS } from "../compiler/vocab.js";
+
+const LOW = 20, HIGH = 50, WIND = 10, SWING = 8, FOLLOW = 10, SETTLE_FRAMES = 8, TOL = 0.25;
+// the wrist at the release: ahead of the shoulder along the throw and up; the thing held rides PALM m ahead of the wrist
+const AHEAD = 0.42, UP = 0.22, PALM = 0.09, BACK = 0.12, SIDE = 0.25, LOWER = 0.4;
+const r3 = v => v.map(x => Math.round(x * 1000) / 1000);
+
+/** How far the root of scene body or group `id` sits above its lowest point at rest (m). */
+function liftOf(scene, id) {
+	const parts = Object.entries(scene?.objects ?? {}).filter(([k, e]) => k === id || e.ancestors?.includes(id)).map(([, e]) => e);
+	const root = scene?.objects?.[id]?.pos ?? parts[0]?.ancestorPoses?.[0]?.pos;
+	if (!root || !parts.length) return 0;
+	return root[1] - Math.min(...parts.map(e => e.pos[1]));
+}
+
+export function throwObject(ctx) {
+	const { args, state, sk, scene, tag } = ctx, id = args.object, k = args.side ?? "r", o = ctx.objects?.[id];
+	if (k !== "l" && k !== "r") skillError(tag, `args.side must be "l" or "r", got ${JSON.stringify(k)}`);
+	if (!o?.prop || ctx.props?.[o.prop]?.hand !== k) skillError(tag, `args.object "${id}" must be carried by the ${k === "r" ? "right" : "left"} hand (objects.${id}.prop on a prop with hand "${k}")`);
+	if (!Array.isArray(args.to) || args.to.length !== 3) skillError(tag, "args.to must be [x, y, z] world m (where it lands)");
+	const theta = ((args.arc === "high" ? HIGH : LOW) * Math.PI) / 180, fps = ctx.fps ?? 24, S = k === "l" ? "Left" : "Right";
+	// the shoulder where the body stands at f0: the bind pose's offset from the hips, turned by the yaw, on the keyed root
+	const P = sk.restWorldPos, hips = state.root ?? P[sk.index.Hips], R = ry(state.yaw ?? 0);
+	const shoulder = add(hips, apply(R, sub(P[sk.index[`${S}Arm`]], P[sk.index.Hips])));
+	const flat = [args.to[0] - shoulder[0], 0, args.to[2] - shoulder[2]], dist = len(flat);
+	if (dist < 0.5) skillError(tag, `args.to is ${dist.toFixed(2)} m from the shoulder; throw it at least 0.5 m`);
+	const dir = scale(flat, 1 / dist), wrist = add(shoulder, add(scale(dir, AHEAD), [0, UP, 0])), from = add(wrist, scale(dir, PALM));
+	const land = args.to[1] + liftOf(scene, id), d = len([args.to[0] - from[0], 0, args.to[2] - from[2]]), dy = land - from[1];
+	const den = 2 * Math.cos(theta) ** 2 * (d * Math.tan(theta) - dy);
+	if (!(den > 0)) skillError(tag, `args.to is too high for a ${args.arc ?? "low"} arc from the hand; use arc "high" or a lower point`);
+	const speed = Math.sqrt((G * d * d) / den), v = add(scale(dir, speed * Math.cos(theta)), [0, speed * Math.sin(theta), 0]);
+	const flight = (v[1] + Math.sqrt(v[1] ** 2 + 2 * G * Math.max(0, from[1] - land))) / G;
+	const release = ctx.f0 + WIND + SWING, landed = Math.min(ctx.frames - 1, release + Math.ceil(flight * fps) + SETTLE_FRAMES);
+	// the wind-up goes back out on the hand's side (not behind the back), the follow-through on down across the body
+	const out = scale([dir[2], 0, -dir[0]], k === "r" ? -1 : 1), hand = `hand_${k}`, armw = `armw_${k}`;
+	const wind = add(shoulder, add(add(scale(dir, -BACK), scale(out, SIDE)), [0, -0.05, 0]));
+	// mid-swing the wrist stays out from the shoulder (a target near it folds the elbow past its stop); after the release it
+	// slows over three frames, going on and down, then crosses low in front
+	const mid = add(shoulder, add(add(scale(out, 0.32), scale(dir, 0.12)), [0, 0.08, 0]));
+	const on = add(wrist, scale(v, 0.45 / fps)), through = add(shoulder, add(scale(dir, 0.46), [0, -0.1, 0])), follow = add(shoulder, add(add(scale(dir, 0.3), scale(out, -0.15)), [0, -LOWER, 0]));
+	// the hand keeps its grip on the thing through the swing and opens as it lets go
+	const fg = `fingers_${k}`, preset = GRASP_FINGERS[o.grasp] ?? "grip", grip = { ...state[fg], [preset]: 1 }, open = { ...state[fg], [preset]: 0 };
+	const keys = [
+		{ f: ctx.f0, set: { [armw]: state[armw] ?? 0, [fg]: grip, ...(state[hand] ? { [hand]: state[hand] } : {}) } },
+		{ f: release, set: { [fg]: grip } }, { f: release + 3, set: { [fg]: open } },
+		{ f: ctx.f0 + WIND, set: { [armw]: 1, [hand]: r3(wind) } },
+		{ f: ctx.f0 + WIND + Math.round(SWING / 2), set: { [armw]: 1, [hand]: r3(mid) } },
+		{ f: release - 1, set: { [armw]: 1, [hand]: r3(sub(wrist, scale(v, 1 / fps))) } },
+		{ f: release, set: { [armw]: 1, [hand]: r3(wrist) } },
+		{ f: release + 1, set: { [armw]: 1, [hand]: r3(on) } },
+		{ f: release + 3, set: { [armw]: 1, [hand]: r3(through) } },
+		{ f: release + FOLLOW, set: { [armw]: 1, [hand]: r3(follow) } },
+	];
+	const target = `${id}Target`;
+	return {
+		keys, end: release + FOLLOW, anchors: { [target]: { kind: "world", p: r3([args.to[0], land, args.to[2]]) } },
+		fills: { [id]: { release, fall: { at: release, v: r3(v) } } },
+		goals: [{ name: `${id} lands at the target`, near: [`object:${id}`, `anchor:${target}`], at: landed, tol: TOL }],
+		throw: { release, speed: Math.round(speed * 100) / 100, v: r3(v), flight: Math.round(flight * 100) / 100 },
+	};
+}

package/src/motion3/sockets.js

@@ -11,6 +11,10 @@
 // bar, a can, a handle) is one too, named by its id, through its centre along its long axis. An object anchor with
 // `grasp` (power, pinch, hook, palm) takes the hand by a socket of its object: `socket` names it, else the one
 // nearest the anchor's `local` point or, without one, nearest the shoulder of the hand, picked once per compile.
+// A disc (a cylinder whose height is under THIN m and whose two sides are wider: a steering wheel) is a rim socket
+// instead: `rim` its radius, `normal` its axis; the hand takes the rim where it is nearest the anchor's `local` point
+// or the hand's shoulder, the knuckle line along the rim (session 2ad2760a: the wheel was held by points in the
+// driver's frame, 15 cm off the rim, and they did not follow the truck). anchorSocket fixes that point once per hand.
 import { add, sub, scale, norm, cross, dot, len, apply, ry, T } from "./compiler/math.js";
 import { partsOf } from "./object-pose.js";
 
@@ -24,6 +28,9 @@ function thinAxis(half) {
 	return [0, 1, 2].filter(i => i !== long).every(i => half[i] < THIN) ? long : -1;
 }
 
+/** A cylinder flat along its axis (its height under THIN m) and round across it, both sides over THIN m. */
+const isDisc = (renderer, half) => renderer === "cylinder" && !!half && half[1] < THIN && Math.min(half[0], half[2]) >= THIN && Math.abs(half[0] - half[2]) < 0.1 * half[0];
+
 /** The record's stored sockets: a body's in scene.objects, a group's (an Empty) in scene.others. */
 const stored = (scene, id) => scene?.objects?.[id]?.grasp ?? scene?.others?.[id]?.grasp ?? null;
 
@@ -36,8 +43,10 @@ export function socketsOf(scene, id) {
 	own(id, "");
 	for (const part of partsOf(scene, id)) {
 		if (part !== id) own(part, `${part}.`);
-		const half = scene.objects[part].half, long = thinAxis(half);
-		if (long >= 0) out.push({ name: part, owner: part, at: [0, half[1], 0], axis: AXES[long] });
+		const { half, renderer } = scene.objects[part], long = thinAxis(half);
+		// a thin body's radius: the thinner of the two half sizes across the axis (how far the palm sits off the axis)
+		if (long >= 0) out.push({ name: part, owner: part, at: [0, half[1], 0], axis: AXES[long], radius: Math.min(...half.filter((_, i) => i !== long)) });
+		else if (isDisc(renderer, half)) out.push({ name: part, owner: part, at: [0, half[1], 0], rim: half[0], normal: AXES[1] });
 	}
 	return out;
 }
@@ -48,7 +57,14 @@ export const socketNamed = (scene, id, name) => socketsOf(scene, id).find(s => s
 /** A socket in world space on its owner's pose { pos, R }: { p, axis?, from?, thumb? }. */
 export function socketWorld(socket, pose) {
 	const dir = v => (v ? norm(apply(pose.R, v)) : undefined);
-	return { p: add(pose.pos, apply(pose.R, socket.at ?? [0, 0, 0])), axis: dir(socket.axis), from: dir(socket.from), thumb: dir(socket.thumb) };
+	return { p: add(pose.pos, apply(pose.R, socket.at ?? [0, 0, 0])), axis: dir(socket.axis), from: dir(socket.from), thumb: dir(socket.thumb), radius: socket.radius,
+		...(socket.rim ? { rim: socket.rim, normal: dir(socket.normal) } : {}) };
+}
+
+/** The point of world rim socket w nearest world point q, and the rim's direction there: { p, axis }. */
+export function rimPoint(w, q) {
+	const v = flat(sub(q, w.p), w.normal), r = len(v) > 1e-6 ? norm(v) : norm(flat(Math.abs(w.normal[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0], w.normal));
+	return { p: add(w.p, scale(r, w.rim)), axis: norm(cross(w.normal, r)) };
 }
 
 /** The outward normal of the face of the box (of boxes [{ pos, R, half }], base pivots) nearest world point p, or undefined. */
@@ -62,9 +78,10 @@ export function faceFrom(boxes, p) {
 	return best?.n;
 }
 
-/** How far world point q is from a world socket: from its axis line through p, else from p. */
+/** How far world point q is from a world socket: from its rim, else its axis line through p, else from p. */
 export function socketDistance(w, q) {
 	const v = sub(q, w.p);
+	if (w.rim) return Math.hypot(dot(v, w.normal), len(flat(v, w.normal)) - w.rim);
 	return len(w.axis ? flat(v, w.axis) : v);
 }
 

package/src/motion3/views.js

@@ -1,6 +1,7 @@
 // C11 own views: the cameras of a verify_result contact_sheet with `views`. They are the
 // agent's own cameras around the subject, never the user's shot camera. A view stays at one
-// place for every frame of the sheet and frames what matters over those frames (the focus
+// place for every frame of the sheet (or rides with the focus when it travels farther than its
+// size) and frames what matters over those frames (the focus
 // refs, else the whole character, plus any trail), so a small action fills the tile and
 // motion reads as change inside one still frame. Pure over a compile result (compileSpec .out).
 //   front          in front of the character, 10 degrees up
@@ -78,7 +79,8 @@ function fit(name, points, back, upHint, aspect) {
  * Deterministic: the same compile, frames and arguments give the same cameras.
  */
 export function viewCameras(out, { views, frames, focus = [], trails = [], aspect = 1 }) {
-	let points = frames.flatMap(f => focus.flatMap(ref => refPoints(out, f, ref)));
+	const ride = rideOf(out, frames, focus);
+	let points = frames.flatMap(f => focus.flatMap(ref => refPoints(out, f, ref)).map(p => (ride ? sub(p, ride[f]) : p)));
 	const body = frames.flatMap(f => jointsAt(out, f));
 	if (!points.length) points = body;
 	points = [...points, ...trails.flatMap(t => t.points.map(q => q.p))];
@@ -86,12 +88,33 @@ export function viewCameras(out, { views, frames, focus = [], trails = [], aspec
 	const { left, forward } = facingOf(out, frames), hips = mean(frames.map(f => jointsAt(out, f)[out.ctx.sk.index.Hips]).filter(Boolean));
 	const side = focus.length && dot(sub(mean(points), hips), left) > 0.02 ? left : scale(left, -1);
 	return views.map(name => {
-		if (name === "top") return fit(name, points, UP, forward, aspect);
-		const e = rad(ELEVATION[name]), level = name === "front" ? forward : name === "side" ? side : norm(add(forward, side));
-		return fit(name, points, add(scale(level, Math.cos(e)), scale(UP, Math.sin(e))), UP, aspect);
+		const cam = name === "top" ? fit(name, points, UP, forward, aspect)
+			: (e => fit(name, points, add(scale(name === "front" ? forward : name === "side" ? side : norm(add(forward, side)), Math.cos(e)), scale(UP, Math.sin(e))), UP, aspect))(rad(ELEVATION[name]));
+		return ride ? { ...cam, ride } : cam;
 	});
 }
 
+/**
+ * The focus's travel over the frames: { [frame]: its centre there less its mean centre } when it moves farther than its
+ * own size (a wheel in a driving truck, session 2ad2760a: one camera for the whole drive framed the road and showed the
+ * hands too small to read), else null. A riding view keeps its place relative to the focus (cameraAt).
+ */
+function rideOf(out, frames, focus) {
+	if (!focus.length) return null;
+	const at = frames.map(f => ({ f, points: focus.flatMap(ref => refPoints(out, f, ref)) })).filter(x => x.points.length);
+	if (at.length < 2) return null;
+	const centres = at.map(x => mean(x.points)), mid = mean(centres);
+	const size = Math.max(MIN_HALF, ...at.map((x, i) => Math.max(...x.points.map(p => Math.hypot(...sub(p, centres[i]))))));
+	if (Math.max(...centres.map(c => Math.hypot(...sub(c, mid)))) <= size) return null;
+	return Object.fromEntries(at.map((x, i) => [x.f, sub(centres[i], mid)]));
+}
+
+/** View camera `cam` at `frame`: a riding view moved by the focus's travel there (rideOf), else cam itself. */
+export function cameraAt(cam, frame) {
+	const d = cam.ride?.[frame];
+	return d ? { ...cam, eye: add(cam.eye, d), target: add(cam.target, d) } : cam;
+}
+
 // A picture hides distance along its own line of sight, so a sheet holds two views at least APART
 // degrees apart. Front and three-quarter (45 degrees apart) look along nearly one line: the
 // guitarist's right hand 20 cm in front of the guitar (session df388a9b) showed in neither.

package/src/object-catalog.jsx

@@ -4,7 +4,6 @@ import { EMPTY_KIND, OBJECT_MENU_ENTRIES } from "./scene-objects.js";
 
 const GROUP_LABELS_KO = {
 	Primitives: "기본 도형",
-	"Set pieces": "세트 소품",
 	Lights: "조명",
 	Effects: "효과",
 	Text: "텍스트",
@@ -18,9 +17,6 @@ const OBJECT_LABELS_KO = {
 	Cylinder: "원기둥",
 	Cone: "원뿔",
 	Plane: "평면",
-	Chair: "의자",
-	Car: "자동차",
-	"Plane (aircraft)": "비행기",
 	"Point light": "점 조명",
 	"Spot light": "스포트 조명",
 	Light: "조명",

package/src/object-gizmo.jsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
-import { GIZMO_LAYER, SHOT_ASPECT, fitAspect } from "./dualview.jsx";
+import { GIZMO_LAYER, SHOT_ASPECT } from "./dualview.jsx";
+import { fitAspect } from "./shot-frame.js";
 import { HANDLE_PROXY_FLAG, claimsPress } from "./gizmo-claim.js";
 import { CUTOUT_KIND, rotatePatch, scalePatch, screenRotatePatch, translatePatch, wrapAngle } from "./scene-objects.js";
 import { dragTravel, dragTurn } from "./held-object-pose.js";

package/src/object-path.js

@@ -464,4 +464,4 @@ export function strokeToPathPoints(stroke, simplify, { maxPoints = STROKE_MAX_PO
 	return points.map((point) => ({ x: point.x, y: 0, z: point.z }));
 }
 
-export { MAX_PATH_POINTS, MAX_PATH_MARKS, MARK_GAP, MAX_LEAN as MAX_PATH_LEAN, MAX_HEIGHT as MAX_PATH_HEIGHT, STROKE_MAX_POINTS };
+export { MAX_PATH_POINTS, MAX_PATH_MARKS, MARK_GAP, MAX_LEAN as MAX_PATH_LEAN, STROKE_MAX_POINTS };

package/src/panels/ProjectPanel.jsx

@@ -1,4 +1,7 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import { ko } from "../locale.js";
+import { usePopover } from "../popover.js";
 import ResourceStatus from "../resource-status.jsx";
 import { useBus } from "../app-context.js";
 import "./details.css";
@@ -7,27 +10,45 @@ export default function ProjectPanel({
 	projectMenuOpen, setProjectMenuOpen, projectDirty, projectName, projectStartupOpen, projectManifest,
 }) {
 	const { run } = useBus();
+	const triggerRef = useRef(null);
+	const [menuBox, setMenuBox] = useState(null);
+	usePopover(projectMenuOpen, () => setProjectMenuOpen(false));
+	// The menu is portaled and fixed under the trigger: the glass column clips
+	// and blurs its children, so an in-place menu was cut at the column edge
+	// and read the column's transparent panel fill. App.jsx closes it on an
+	// outside pointerdown via `.closest(".project-menu-wrap")`, so the portal
+	// layer carries that class (display:contents, no box of its own).
+	useLayoutEffect(() => {
+		const rect = projectMenuOpen ? triggerRef.current?.getBoundingClientRect() : null;
+		setMenuBox(rect ? { left: rect.left, top: rect.bottom + 6 } : null);
+	}, [projectMenuOpen]);
+	// Hidden until the layout effect has placed it, so it never paints at the
+	// wrong spot; without a document (server render) it stays in place.
+	const menu = projectMenuOpen && (
+		<div className="project-menu-wrap v2-project-menu project-menu-layer">
+			<div className="project-menu" role="menu" style={menuBox ?? { visibility: "hidden" }} onClick={() => setProjectMenuOpen(false)}>
+				<button type="button" role="menuitem" onClick={() => run("project.new")}>{ko("New Project", "새 프로젝트")}</button>
+				<button type="button" role="menuitem" onClick={() => run("project.browse")}>{ko("Open Project…", "프로젝트 열기…")}</button>
+				<button type="button" role="menuitem" onClick={() => run("project.save")}>{ko("Save Project", "프로젝트 저장")}</button>
+				<button type="button" role="menuitem" onClick={() => run("project.saveAs")}>{ko("Save Project As…", "다른 이름으로 저장…")}</button>
+				<ResourceStatus manifest={projectManifest} compact />
+			</div>
+		</div>
+	);
 	return (
-<div className="project-menu-wrap v2-project-menu">
-					<button
-						type="button"
-						className="project-menu-trigger"
-						aria-expanded={projectMenuOpen}
-						onClick={() => setProjectMenuOpen((open) => !open)}
-					>
-						{projectDirty && <i className="project-dirty-dot" aria-label={ko("Unsaved changes", "저장되지 않은 변경사항")} />}
-						{projectName ?? (projectStartupOpen ? ko("Choose Project", "프로젝트 선택") : ko("Untitled Project", "제목 없는 프로젝트"))}
-						<span className="caret">▾</span>
-					</button>
-					{projectMenuOpen && (
-						<div className="project-menu" role="menu" onClick={() => setProjectMenuOpen(false)}>
-							<button type="button" role="menuitem" onClick={() => run("project.new")}>{ko("New Project", "새 프로젝트")}</button>
-							<button type="button" role="menuitem" onClick={() => run("project.browse")}>{ko("Open Project…", "프로젝트 열기…")}</button>
-							<button type="button" role="menuitem" onClick={() => run("project.save")}>{ko("Save Project", "프로젝트 저장")}</button>
-							<button type="button" role="menuitem" onClick={() => run("project.saveAs")}>{ko("Save Project As…", "다른 이름으로 저장…")}</button>
-							<ResourceStatus manifest={projectManifest} compact />
-						</div>
-					)}
-				</div>
+		<div className="project-menu-wrap v2-project-menu">
+			<button
+				type="button"
+				className="project-menu-trigger"
+				ref={triggerRef}
+				aria-expanded={projectMenuOpen}
+				onClick={() => setProjectMenuOpen((open) => !open)}
+			>
+				{projectDirty && <i className="project-dirty-dot" aria-label={ko("Unsaved changes", "저장되지 않은 변경사항")} />}
+				{projectName ?? (projectStartupOpen ? ko("Choose Project", "프로젝트 선택") : ko("Untitled Project", "제목 없는 프로젝트"))}
+				<span className="caret">▾</span>
+			</button>
+			{menu && (globalThis.document ? createPortal(menu, globalThis.document.body) : menu)}
+		</div>
 	);
 }