cozyclay 3.0.3 → 3.1.1

package/src/motion3/shapes.js

@@ -0,0 +1,70 @@
+// The shape of a motion-scene entry to a hand (#816): a sphere and a cylinder are round, not the box they sit in. A
+// 7.4 cm ball in its box is off by up to 30% of its radius at the corners, so fingers closing on the box would stop in
+// the air. The shape is derived from what every entry already carries (renderer, half: scene.js), so no field is added
+// to an entry and a saved take source, which keeps whole entries, reads the same shapes. DOM-free: the compile worker
+// runs it. Everything else (GRAB, COLLIDE, landing) keeps the oriented box.
+//   sphere    renderer "sphere" whose three halves agree within EVEN: r = their mean (an uneven one is an ellipsoid:
+//             its box)
+//   cylinder  renderer "cylinder": its axis along the entry's local +Y, r the smaller cross half, h = 2 half[1]
+//   box       anything else: the oriented box on the base pivot (qa/geometry.js sdBox)
+// An entry's pos is its base pivot (the bottom centre); its centre is pos + R [0, half[1], 0].
+import { add, sub, scale, len, apply, T } from "./compiler/math.js";
+import { sdBox, boxNormal, segPoints } from "./qa/geometry.js";
+
+const EVEN = 0.05;
+
+/** { kind: "sphere", r } | { kind: "cylinder", r, h } | { kind: "box" } of a motion-scene entry. */
+export function shapeOf(entry) {
+	const h = entry?.half;
+	if (!h) return { kind: "box" };
+	if (entry.renderer === "sphere") {
+		const r = (h[0] + h[1] + h[2]) / 3;
+		return Math.max(...h) - Math.min(...h) <= EVEN * r ? { kind: "sphere", r } : { kind: "box" };
+	}
+	if (entry.renderer === "cylinder") return { kind: "cylinder", r: Math.min(h[0], h[2]), h: 2 * h[1] };
+	return { kind: "box" };
+}
+
+const local = (entry, p) => { const q = apply(T(entry.R), sub(p, entry.pos)); q[1] -= entry.half[1]; return q; };
+const centre = entry => add(entry.pos, apply(entry.R, [0, entry.half[1], 0]));
+
+/** Signed distance (m) from p to the entry's shape: negative inside. */
+export function signedDistance(entry, p) {
+	const s = shapeOf(entry);
+	if (s.kind === "sphere") return len(sub(p, centre(entry))) - s.r;
+	if (s.kind === "cylinder") {
+		const q = local(entry, p), radial = Math.hypot(q[0], q[2]) - s.r, axial = Math.abs(q[1]) - s.h / 2;
+		return Math.hypot(Math.max(radial, 0), Math.max(axial, 0)) + Math.min(Math.max(radial, axial), 0);
+	}
+	return sdBox(p, entry);
+}
+
+/** Outward unit normal of the entry's shape at p (the nearest surface's from inside). */
+export function normalAt(entry, p) {
+	const s = shapeOf(entry);
+	if (s.kind === "sphere") { const d = sub(p, centre(entry)), l = len(d); return l > 1e-12 ? scale(d, 1 / l) : apply(entry.R, [0, 1, 0]); }
+	if (s.kind === "cylinder") {
+		const q = local(entry, p), rq = Math.hypot(q[0], q[2]), radial = rq - s.r, axial = Math.abs(q[1]) - s.h / 2;
+		const out = rq > 1e-12 ? [q[0] / rq, 0, q[2] / rq] : [1, 0, 0], cap = [0, Math.sign(q[1]) || 1, 0];
+		let n;
+		if (radial <= 0 && axial <= 0) n = radial > axial ? out : cap;
+		else n = add(scale(out, Math.max(radial, 0)), scale(cap, Math.max(axial, 0)));
+		const l = len(n);
+		return apply(entry.R, l > 1e-12 ? scale(n, 1 / l) : out);
+	}
+	return boxNormal(p, entry);
+}
+
+export function closestPoint(entry, p) {
+	return sub(p, scale(normalAt(entry, p), signedDistance(entry, p)));
+}
+
+/**
+ * How far a capsule (segment a-b, `radius` m) goes into the entry's shape, m: positive is the depth of its skin inside,
+ * negative the gap between its skin and the surface. Sampled on the segment as the QA capsules are (segPoints).
+ */
+export function capsuleDepth(entry, a, b, radius) {
+	let depth = -Infinity;
+	for (const p of segPoints(a, b)) depth = Math.max(depth, radius - signedDistance(entry, p));
+	return depth;
+}

package/src/motion3/skills/catch.js

@@ -0,0 +1,71 @@
+// catchObject: a hand meets a flying thing where it can reach and gives with it (#816). The thing flies as a free entry
+// does, objects.<id>.fall { at, v } from its pose at `at` (flight.js); the skill samples that flight and picks the first
+// frame its point is in front of the chest (FRONT m ahead, between the hips and the head) and SHELL m from the catching
+// shoulder, no earlier than the hand can get there from f0 (REACH frames). The open hand arrives ARRIVE frames before it,
+// the finger middles on the point (a fit on a world anchor there); the fingers close and the carry takes it at
+// that frame (fills: prop, grab, grasp), so it rests in the hand (seat.js) and the fingers close on it (finger-close.js).
+// Then the hand gives with it: along the incoming velocity by clamp(0.08 + 0.02 x mass x speed, 0.08, 0.15) m over ABSORB
+// frames, slowing to a stop, and eases back. side "both", or a thing over HEAVY kg, adds the left hand on its left side
+// along the same path (world anchors: the right hand holds the carry, the left meets it). A flight that never comes within
+// reach is refused, naming its nearest frame and point; a hand that comes too late (f0 past the reach) misses: QA CATCH.
+import { add, sub, scale, apply, ry, len, norm, dot } from "../compiler/math.js";
+import { freePoseAt } from "../free-motion.js";
+import { massOf } from "../mass.js";
+import { skillError } from "./book.js";
+import { transportKeys } from "./reach-human.js";
+
+const SHELL = [0.35, 0.65], FRONT = 0.15, REACH = 10, LONG = 20, ARRIVE = 2, ABSORB = 6, BACK = 8, HEAVY = 1;
+const r3 = v => v.map(x => Math.round(x * 1000) / 1000);
+const clamp = (x, a, b) => Math.min(b, Math.max(a, x));
+
+/** The shoulder of side S and the body's forward on the keyed root and yaw of state. */
+function bodyAt(sk, state, S) {
+	const P = sk.restWorldPos, hips = state.root ?? P[sk.index.Hips], R = ry(state.yaw ?? 0);
+	return { hips, shoulder: add(hips, apply(R, sub(P[sk.index[`${S}Arm`]], P[sk.index.Hips]))), head: add(hips, apply(R, sub(P[sk.index.Head], P[sk.index.Hips]))), fwd: apply(R, [0, 0, 1]) };
+}
+
+export function catchObject(ctx) {
+	const { args, state, sk, scene, tag } = ctx, id = args.object, side = args.side ?? "r", o = ctx.objects?.[id], fps = ctx.fps ?? 24;
+	if (side !== "r" && side !== "both") skillError(tag, `args.side must be "r" or "both", got ${JSON.stringify(side)}`);
+	const fall = Array.isArray(o?.fall) ? o.fall[0] : o?.fall;
+	if (!Array.isArray(fall?.v)) skillError(tag, `args.object "${id}" must fly: objects.${id}.fall { at, v: [vx, vy, vz] }`);
+	const body = bodyAt(sk, state, "Right"), flight = { spec: { objects: { [id]: { fall: o.fall } }, fps }, scene, timeMap: null };
+	const at = f => freePoseAt(flight, id, f)?.pos;
+	// the first frame of the flight in front of the chest within the shell around the shoulder; else the nearest one
+	let pick = null, near = null;
+	for (let f = fall.at + 1; f < ctx.frames; f++) {
+		const p = at(f), d = len(sub(p, body.shoulder)), ahead = dot(sub(p, body.hips), body.fwd), off = Math.max(0, SHELL[0] - d, d - SHELL[1], FRONT - ahead, body.hips[1] - 0.1 - p[1], p[1] - body.head[1]);
+		if (!near || off < near.off) near = { f, p, off };
+		if (off === 0) { pick = { f, p }; break; }
+	}
+	if (!pick) skillError(tag, `${id} never comes within reach of the right hand (in front of the chest, ${SHELL[0]}-${SHELL[1]} m from the shoulder): nearest at f${near.f}, [${r3(near.p).join(", ")}], ${near.off.toFixed(2)} m out; move the body (standIdle at) or the throw`);
+	// the hand needs REACH frames from f0: a later pick it would get to in time; else it comes late to where the thing was
+	const contact = Math.max(pick.f, ctx.f0 + REACH + ARRIVE), p = pick.p;
+	const incoming = scale(sub(at(pick.f), at(pick.f - 1)), fps), speed = len(incoming), mass = massOf({ objects: ctx.objects }, scene, id);
+	const give = clamp(0.08 + 0.02 * mass * speed, 0.08, 0.15), u = norm(incoming), ease = t => 1 - (1 - t) ** 3;
+	const path = [p, ...Array.from({ length: ABSORB }, (_, i) => add(p, scale(u, give * ease((i + 1) / ABSORB)))), add(p, scale(u, give * 0.4))];
+	const start = Math.max(ctx.f0, contact - ARRIVE - LONG), both = side === "both" || mass > HEAVY;
+	// the left hand (both hands, or a heavy thing) on its left side, its finger middles across the thing from the right's
+	const radius = Math.max(0, ...Object.values(scene.objects).filter(e => e === scene.objects[id] || e.ancestors?.includes(id)).map(e => Math.max(...e.half)));
+	const left = apply(ry(state.yaw ?? 0), [1, 0, 0]), part = { keys: [], end: contact + ABSORB + BACK, props: {}, anchors: {}, fits: [], channels: [],
+		fills: { [id]: { prop: `${id}Catch`, grab: contact, grasp: "spherical" } }, catch: { contact, point: r3(p), speed: Math.round(speed * 100) / 100, give: Math.round(give * 1000) / 1000, hands: both ? 2 : 1 } };
+	for (const k of both ? ["r", "l"] : ["r"]) {
+		const S = k === "l" ? "Left" : "Right", prop = k === "r" ? `${id}Catch` : `${id}CatchL`, off = k === "r" ? [0, 0, 0] : scale(left, 2 * radius + 0.04);
+		const armw = `armw_${k}`, fg = `fingers_${k}`, open = { ...state[fg], spherical: 0 }, shut = { ...state[fg], spherical: 1 };
+		// the finger middles (the prop's origin) on the point at the catch, then on each point of the give: world anchors
+		// with a fit each, the weight handed from one to the next frame by frame (the fits solve the hand onto them exactly)
+		const names = path.map((_, i) => `${prop}${i}`), w = i => `w_${names[i]}_${k}`;
+		part.keys.push(
+			// the elbow down and out (body axes), so it swings out round the side, not in across the body
+			{ f: start, set: { [armw]: state[armw] ?? 0, [w(0)]: 0, [fg]: open, [`elbow_${k}`]: k === "r" ? [-1, -0.5, -0.5] : [1, -0.5, -0.5] } },
+			// the reach's early-peaked transport, the arm's weight ahead of the aim's (reach-human.js; as reachGrip)
+			...transportKeys(contact - ARRIVE - start).map(([f, t, ta]) => ({ f: start + f, set: { [w(0)]: t, [armw]: (state[armw] ?? 0) + (1 - (state[armw] ?? 0)) * ta } })),
+			{ f: contact - ARRIVE, set: { [armw]: 1, [w(0)]: 1, [fg]: open } },
+			{ f: contact, set: { [w(0)]: 1, [fg]: shut } },
+			...path.slice(1).flatMap((_, j) => { const i = j + 1, f = i <= ABSORB ? contact + i : contact + ABSORB + BACK; return [{ f: i <= ABSORB ? f - 1 : contact + ABSORB, set: { [w(i - 1)]: 1, [w(i)]: 0 } }, { f, set: { [w(i - 1)]: 0, [w(i)]: 1 } }]; }),
+		);
+		part.props[prop] = { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: [0, 0, 0] } };
+		names.forEach((n, i) => { part.anchors[n] = { kind: "world", p: r3(add(path[i], off)) }; part.fits.push({ side: k, anchor: n, effector: { prop, point: "fingers" } }); part.channels.push(w(i)); });
+	}
+	return part;
+}

package/src/motion3/skills/index.js

@@ -13,8 +13,10 @@ 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);
@@ -53,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(", ")})`);
@@ -61,7 +63,7 @@ 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, props: { ...merged.props, ...spec.props }, self: spec.fix !== false && spec.fix?.self !== false, f0: u.f0, args: structuredClone(u.args ?? {}), tag, keys,
+		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"`);
@@ -72,6 +74,9 @@ 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);
+		// 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 },
@@ -82,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

@@ -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/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/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-look.js

@@ -16,6 +16,7 @@
  */
 
 import { normalizeObjectColor } from "./object-colors.js";
+import { objectMaterialFields, objectMaterialPatch } from "./material-presets.js";
 
 export const LIGHT_KIND = "light";
 
@@ -94,8 +95,8 @@ export function normalizeObjectGlow(value) {
 }
 
 /** The light/glow fields a normalized record carries. A light renderer always
- * has a light; any record keeps a glow only when it has one, so records written
- * before glow existed come back byte-for-byte unchanged. */
+ * has a light; any record keeps a glow (and a primitive its surface preset)
+ * only when it has one, so records written before come back unchanged. */
 export function objectLookFields(record, entry) {
 	const out = {};
 	if ((entry.renderer ?? entry.kind) === LIGHT_KIND) out.light = normalizeObjectLight(record.light, record.light?.type ?? entry.light?.type);
@@ -103,12 +104,14 @@ export function objectLookFields(record, entry) {
 	if (glow) out.glow = glow;
 	// A kit part a take switches on (a muzzle flash and its light) stays hidden without one (object-travel.js trackShown).
 	if (record.showOnlyInTake === true) out.showOnlyInTake = true;
-	return out;
+	// A primitive's surface preset (material-presets.js).
+	return Object.assign(out, objectMaterialFields(record, entry.renderer ?? entry.kind));
 }
 
 /** The light/glow part of an object.update patch: each field merges over the
  * record's own and is repaired; `glow: null` removes the glow. Only changes are
- * returned. A light on a record that is not a light is ignored. */
+ * returned. A light on a record that is not a light is ignored. A primitive's
+ * material and finish ride along (material-presets.js). */
 export function objectLookPatch(object, patch) {
 	const update = {};
 	if (patch?.light && typeof patch.light === "object" && object.renderer === LIGHT_KIND) {
@@ -119,7 +122,7 @@ export function objectLookPatch(object, patch) {
 		const next = patch.glow === null ? null : normalizeObjectGlow({ ...(object.glow ?? {}), ...patch.glow });
 		if (JSON.stringify(next) !== JSON.stringify(object.glow ?? null)) update.glow = next;
 	}
-	return update;
+	return Object.assign(update, objectMaterialPatch(object, patch));
 }
 
 /** 32-bit FNV-1a of the record id: the flicker's seed. */
@@ -196,3 +199,4 @@ export function withShadowCapWarnings(result, objects) {
 }
 // A record's grasp sockets ride the same normalize and patch paths (object-grasp.js).
 export { objectGraspFields, objectGraspPatch } from "./object-grasp.js";
+export { objectMaterialKeys } from "./material-presets.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>
 	);
 }

package/src/panels/details.css

@@ -1032,14 +1032,25 @@
 	background: var(--select, #e8a33d);
 }
 
+/* The menu is portaled to <body> (ProjectPanel.jsx); the layer that carries
+   the wrap classes there has no box of its own. Surface and layer are the
+   shared popover tokens (themes.css). */
+.v2-project-menu.project-menu-layer {
+	display: contents;
+}
+
 .v2-project-menu.v2-project-menu .project-menu {
+	position: fixed;
+	z-index: var(--z-popover, 90);
 	box-sizing: border-box;
 	min-width: var(--details-menu-width, 200px);
 	padding: var(--details-gap, 4px);
-	border: var(--details-border-width, 1px) solid var(--row-divider, #1d1d20);
-	border-radius: var(--r-2, 6px);
-	background: var(--surface-panel, #151517);
-	box-shadow: none;
+	border: var(--details-border-width, 1px) solid var(--popover-border, var(--row-divider, #1d1d20));
+	border-radius: var(--popover-radius, 6px);
+	background: var(--popover-surface, var(--surface-raised, #1e1e21));
+	-webkit-backdrop-filter: var(--popover-blur, none);
+	backdrop-filter: var(--popover-blur, none);
+	box-shadow: var(--popover-shadow, 0 8px 24px rgba(0, 0, 0, .45));
 }
 
 .v2-project-menu.v2-project-menu .project-menu button {

package/src/popover.js

@@ -0,0 +1,37 @@
+import { useEffect, useRef } from "react";
+
+// Shell popovers (the project menu, dropdowns, the Outliner context menu) are
+// exclusive: opening one announces itself and every other open one closes, so
+// two menus never stack over each other. Their surface and layer are the
+// --popover-* / --z-popover tokens in src/styles/themes.css.
+const POPOVER_OPEN_EVENT = "cozyclay:popover-open";
+
+/**
+ * Join the exclusive popover group while `open` is truthy. A new truthy
+ * `open` value (a context menu re-opened at another row) announces again.
+ * With `insideRefs`, a mousedown outside every ref also closes the popover.
+ */
+export function usePopover(open, close, insideRefs = null) {
+	const live = useRef({ close, insideRefs });
+	useEffect(() => {
+		live.current = { close, insideRefs };
+	});
+	useEffect(() => {
+		if (!open) return undefined;
+		const token = {};
+		window.dispatchEvent(new CustomEvent(POPOVER_OPEN_EVENT, { detail: token }));
+		const onOtherOpen = (event) => {
+			if (event.detail !== token) live.current.close();
+		};
+		const onDocMouseDown = (event) => {
+			const refs = live.current.insideRefs;
+			if (refs && !refs.some((ref) => ref.current?.contains(event.target))) live.current.close();
+		};
+		window.addEventListener(POPOVER_OPEN_EVENT, onOtherOpen);
+		document.addEventListener("mousedown", onDocMouseDown);
+		return () => {
+			window.removeEventListener(POPOVER_OPEN_EVENT, onOtherOpen);
+			document.removeEventListener("mousedown", onDocMouseDown);
+		};
+	}, [open]);
+}

package/src/posestudio.jsx

@@ -423,13 +423,10 @@ export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus,
 			// not-yet-focused sphere just took focus (nothing to bake). An
 			// empty-canvas click releases focus too.
 			if (!d.moved) {
-				if (d.kind === "empty") {
-					if (focusIdRef.current) focusRef.current?.(null);
-					return;
-				}
-				if (d.wasFocused && !d.axisDir) {
-					focusRef.current?.(null); // toggle off
-				}
+				// (An empty press is always wasFocused: it only begins while focused.)
+				// A gizmo volume can win the raycast over the sphere centre, so a
+				// no-move press on the centre (d.centerClick) toggles off too.
+				if (d.wasFocused && (!d.axisDir || d.centerClick)) focusRef.current?.(null); // toggle off
 				// axis-arrow clicks and fresh-sphere clicks: nothing to bake
 				return;
 			}
@@ -842,7 +839,7 @@ const CLICK_PX = 4;
 		if (kind === "empty") {
 			// An empty-canvas press: no drag, just a click candidate that
 			// releases focus on pointerup (see onUp).
-			dragRef.current = { kind: "empty", trackId: "empty", downXY, moved: false };
+			dragRef.current = { kind: "empty", trackId: "empty", downXY, moved: false, wasFocused: true };
 			window.addEventListener("pointermove", handlersRef.current.onMove);
 			window.addEventListener("pointerup", handlersRef.current.onUp);
 			window.addEventListener("pointercancel", handlersRef.current.onUp);
@@ -860,6 +857,7 @@ const CLICK_PX = 4;
 		}
 		raycaster.setFromCamera(ndc, camera);
 		let plane;
+		const rect = gl.domElement.getBoundingClientRect(), c = origin.clone().project(camera);
 		const ringDrag = !!axisDir && (kind === "fk" || kind === "swing");
 		if (ringDrag) {
 			// A ring turns about its axis: the pointer is read on the ring's own plane.
@@ -892,6 +890,8 @@ const CLICK_PX = 4;
 			// a no-move click toggles focus OFF only then; a click on a fresh
 			// (unfocused) handle must keep the focus it just took.
 			wasFocused: focusIdRef.current === track.id,
+			// Press landed within CLICK_PX of the sphere's projected centre.
+			centerClick: Math.hypot(downXY[0] - (rect.left + (c.x + 1) / 2 * rect.width), downXY[1] - (rect.top + (1 - c.y) / 2 * rect.height)) <= CLICK_PX,
 		};
 		if (kind === "fk" || kind === "swing" || kind === "body") {
 			// Swing/translate start state, frozen at drag start so moves stay
@@ -944,8 +944,7 @@ const CLICK_PX = 4;
 				handleRefs.current[p.track.id]?.userData.ikExposed !== false
 			);
 			if (focused && !selectionOnly) picks = picks.filter((p) => p.track.id === focused);
-		else picks = picks.filter((p) => !p.axisDir); // spheres only
-			if (selectionOnly) picks = picks.filter((p) => !p.axisDir);
+			else picks = picks.filter((p) => !p.axisDir); // spheres only
 			if (!picks.length) {
 				if (focused) beginDrag("empty", { id: "empty" }, null, null, downXY);
 				return;
@@ -985,10 +984,16 @@ const CLICK_PX = 4;
 			}
 			setHoverAxis((current) => (current === axis ? current : axis));
 		};
+		// Esc releases the focused handle (same path as the toggle-off click).
+		const onKey = (ev) => {
+			if (ev.key === "Escape" && focusIdRef.current && !/^(INPUT|TEXTAREA|SELECT)$/.test(ev.target?.tagName)) focusRef.current?.(null);
+		};
 		raycaster.layers.enable(POSER_LAYER);
 		el.addEventListener("pointerdown", onDown, true);
 		el.addEventListener("pointermove", onHover);
+		window.addEventListener("keydown", onKey);
 		return () => {
+			window.removeEventListener("keydown", onKey);
 			el.removeEventListener("pointerdown", onDown, true);
 			el.removeEventListener("pointermove", onHover);
 			raycaster.layers.disable(POSER_LAYER);

package/src/primitive-look.js

@@ -0,0 +1,38 @@
+/**
+ * A primitive's surface preset (object.material / object.finish) as the
+ * material props.jsx hangs on its mesh, and the polygon offset every prop
+ * material takes for its depth rank.
+ */
+
+import { useEffect, useMemo } from "react";
+import { lookMaterial } from "./material-look.js";
+
+// Parts of an assembly can share a plane with an earlier part (hood top and
+// grille top). The depth test can't order them and the winner flips as the
+// camera moves, so a ranked part is pulled toward the camera by `rank` steps
+// (negative = nearer). Rank 0 gets nothing: those materials stay untouched.
+export function depthRankProps(rank) {
+	return rank > 0 ? { polygonOffset: true, polygonOffsetFactor: -rank, polygonOffsetUnits: -rank } : null;
+}
+
+/** Each primitive's extent in its mesh frame at scale 1 (props.jsx builds
+ * them); the rest are unit sized. The shader multiplies the record's scale in. */
+const PRIMITIVE_SIZE = { capsule: [0.7, 1.4, 0.7], plane: [2, 2, 0.01] };
+
+/**
+ * The preset material for a primitive record, or null when the record keeps
+ * the plain clay look (no material and no finish) or auto-colour paints it
+ * flat: the caller then draws exactly what it drew before presets. Rebuilt
+ * when the look, the colour or the rank changes; the program and the pattern
+ * textures are shared, so a rebuild is cheap.
+ */
+export function usePrimitiveLook(object, kind, side, depthRank) {
+	const { material, finish, color, autoColor } = object;
+	const active = !autoColor && Boolean(material || finish);
+	const look = useMemo(
+		() => (active ? lookMaterial({ material, finish, color, side, size: PRIMITIVE_SIZE[kind] }, depthRankProps(depthRank)) : null),
+		[active, material, finish, color, side, kind, depthRank],
+	);
+	useEffect(() => () => look?.dispose(), [look]);
+	return look;
+}