cozyclay 3.0.1 → 3.0.2

package/src/motion3/free-motion.js

@@ -29,7 +29,9 @@ import { shapeOf, airPath, settlePath, settledAt, spinOf, spinEnergy, TIP } from
 export const G = 9.8;
 /** The highest a bounce goes, metres. */
 export const BOUNCE_MAX = 0.03;
-const BOUNCE = 0.25, TOUCH = 0.005;
+const BOUNCE = 0.25;
+/** A support's top may sit this far above the lowest point of what rests on it (m). */
+export const TOUCH = 0.005;
 const HELD_OR_HINGED = ["prop", "follow", "pivot", "axis", "channel"];
 
 /** A free entry (C17): no prop, follow or hinge field, and keys or fall. */
@@ -41,14 +43,14 @@ const restOf = (scene, id) => scene?.objects?.[id] ?? groupsOf(scene)[id] ?? nul
 const partsIn = (scene, id) => Object.keys(scene?.objects ?? {}).filter(k => k === id || scene.objects[k].ancestors?.includes(id));
 
 /** The 8 corners of a base-pivot box { pos, R, half }. */
-function corners(box) {
+export function corners(box) {
 	const out = [];
 	for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) out.push(add(box.pos, apply(box.R, [x * box.half[0], y * box.half[1], z * box.half[2]])));
 	return out;
 }
-const topOf = box => Math.max(...corners(box).map(p => p[1]));
+export const topOf = box => Math.max(...corners(box).map(p => p[1]));
 /** True when the vertical through x/z point p crosses the footprint of box. */
-const under = (box, p) => { const q = apply(T(box.R), sub([p[0], box.pos[1] + box.half[1], p[2]], box.pos)); return Math.abs(q[0]) <= box.half[0] && Math.abs(q[2]) <= box.half[2]; };
+export const under = (box, p) => { const q = apply(T(box.R), sub([p[0], box.pos[1] + box.half[1], p[2]], box.pos)); return Math.abs(q[0]) <= box.half[0] && Math.abs(q[2]) <= box.half[2]; };
 
 /** Bodies a spec.objects entry moves (itself or a group above it): they hold nothing up. */
 function moversIn(spec, scene) {
@@ -195,6 +197,12 @@ export function afterRelease(ctx, id, o, f, release, releasePose, beforePose = n
 	return events.length ? walk(events, f, releasePose, plan, false) : null;
 }
 
+/** True when carry entry o falls at or after its release (absolute frame; afterRelease then moves it). */
+export function fallsAfter(ctx, o, release) {
+	const map = ctx.timeMap ?? (f => f);
+	return fallsOf(o).some(fl => map(fl.at) >= release);
+}
+
 /** The falls of entry `id` as planned under the current time map, for readers (timeline, tests): [{ t0, land, end, h, support, top }]. */
 export function fallPlans(ctx, id) {
 	const o = ctx.spec.objects?.[id];

package/src/motion3/object-keys.js

@@ -4,7 +4,8 @@
 //   between keys    a cubic Hermite on pos and the same in rotation-vector space on rot (squad
 //                   like), Catmull-Rom tangents through inner keys, zero at the first and last key
 //   around the span the hand blends from the plain carry into the keyed span over KEY_BLEND frames
-//                   (inside grab..release; smoothstep), so nothing jumps
+//                   (inside grab..release; smoothstep), so nothing jumps; keys that start within KEY_BLEND frames
+//                   of the grab with a grip off where the hand is turn the hand onto it before (holdHook approach)
 //   the object leads the hand: compile.js asks holdHook for the palm frame the keys put the grip
 //                   at, palm = key o attach^-1, and pose.js solves the hand to it (compiler/hold.js)
 // The object itself is still drawn in the hand (object-pose.js): the residual is what the arm
@@ -20,11 +21,14 @@ import { polePlan, smoothPath, smoothed } from "./hold-plan.js";
 import { secondGrip, secondHold, gripGate } from "./second-hand.js";
 import { SIDES } from "./compiler/pose.js";
 import { chooseGrip, between, thinBody } from "./grip-choice.js";
+import { graspedBy } from "./compiler/socket-grip.js";
 
 /** Frames over which the hand blends into and out of the keyed span. */
 export const KEY_BLEND = 8;
 // the frames a hand takes to turn into a chosen grip before its grab and out of it after its release (grip-choice.js)
 const GRAB_EASE = 12;
+// how far (m, deg) the grip keys put the hand on at the grab may be from where the reach brought it before the hand turns onto it first
+const OFF_GRIP = { m: 0.01, deg: 5 };
 
 const smooth = x => x * x * (3 - 2 * x);
 /** [grab, release] in absolute frames of `out` (object-pose.js spanOf, kept here to stay out of its import cycle). */
@@ -108,8 +112,8 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	if (!held.length) return null;
 	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }), attached = new WeakMap(), attaching = new Set();
 	const restAt = (id, f) => ctx.restingAt?.(id, f) ?? scene?.objects?.[id] ?? groupsOf(scene)[id];
-	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no keyed wrist at
-	// the grab) keeps the grip its keyed path holds most comfortably (grip-choice.js), solved on the plain frames with the
+	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no grasp fit, no keyed
+	// wrist at the grab) keeps the grip its keyed path holds most comfortably (grip-choice.js), solved on the plain frames with the
 	// body read at rest; a box keeps the grip grip.js gives it at the grab
 	const choices = new WeakMap(), mapped = f => (out.timeMap ? Math.round(out.timeMap(f)) : f);
 	// chosen once per compile (the first bake): the fixes' rebakes move the body a little, the carry's keys not at all
@@ -118,7 +122,7 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 		const cache = choices.get(out), o = spec.objects[id], k = spec.props?.[o.prop]?.hand, grab = spanIn(out, o)[0], b = out.baked ?? {};
 		if (cache.has(id)) return cache.get(id);
 		cache.set(id, null);
-		const free = k && o.at === undefined && o.along === undefined && (o.grab !== undefined || !scene?.objects?.[id]) && thinBody(scene, id) && !(spec.fits ?? []).some(fit => fit.side === k && fit.orient === false)
+		const free = k && o.at === undefined && o.along === undefined && (o.grab !== undefined || !scene?.objects?.[id]) && thinBody(scene, id) && !(spec.fits ?? []).some(fit => fit.side === k && fit.orient === false) && !graspedBy(spec, scene, id, k)
 			&& !["wtwist", "wflex"].some(ch => Math.abs(b[`${ch}_${k}`]?.[grab] ?? 0) > 1e-3)
 			// keys that start after the grab: the body rides the hand from where it rests, which only today's grip meets exactly
 			&& mapped(Math.min(...o.keys.map(key => key.f))) <= grab;
@@ -203,6 +207,33 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 		const h = heldAt(id, o, f);
 		return { w: 1, palm: h ? { pos: add(scale(grip.pos, 1 - h.w), scale(h.palm.pos, h.w)), R: between(grip.R, h.palm.R, h.w) } : grip, measure, pole };
 	};
+	// keys that lead from the grab frame, or from fewer than KEY_BLEND frames after it, put the hand on their grip at once (or
+	// within those frames: palm = first key o attach^-1). Where that grip is not where the hand would be at the first key (an
+	// at/along offset of the agent's choosing: bench session cb2503b5's cup, 13.6 cm in the grab frame; keys two frames after
+	// the grab: 7146050f's box), the hand turns onto it over the GRAB_EASE frames up to the first key instead, as onto a chosen
+	// grip (gripAround): before the grab with the object at rest, after it carrying the object there. A grip within OFF_GRIP
+	// of where the hand would be changes nothing.
+	const offGrips = new WeakMap();
+	const offGrip = (id, o, grip) => {
+		if (!offGrips.has(out.baked)) offGrips.set(out.baked, new Map());
+		const cache = offGrips.get(out.baked), had = cache.get(id);
+		if (had && had.map === out.timeMap) return had.off;
+		attaching.add(id);
+		let palm;
+		try { palm = palmOf(o, solvePlain(Math.max(spanIn(out, o)[0], Math.round(curveIn(out, id).t[0]))).s); } finally { attaching.delete(id); }
+		const turn = relative(palm, grip).R, deg = Math.acos(Math.min(1, Math.max(-1, (turn[0][0] + turn[1][1] + turn[2][2] - 1) / 2))) * 180 / Math.PI;
+		const off = Math.hypot(...sub(grip.pos, palm.pos)) > OFF_GRIP.m || deg > OFF_GRIP.deg;
+		cache.set(id, { map: out.timeMap, off });
+		return off;
+	};
+	const approach = (id, o, f) => {
+		const curve = curveIn(out, id), [grab, release] = spanIn(out, o), t0 = Math.max(grab, Math.round(curve.t[0]));
+		if (!(f < t0 && f >= t0 - GRAB_EASE) || t0 - grab >= KEY_BLEND || t0 > release) return null;
+		const grip = compose(keyedPose(curve, t0), invert(attach(id)));
+		if (!offGrip(id, o, grip)) return null;
+		const w = smooth(1 - (t0 - f) / GRAB_EASE);
+		return w > 1e-3 ? { w, palm: grip, measure: s => palmOf(o, s), pole: planOf(id, o).get(t0) } : null;
+	};
 	// a release within KEY_BLEND frames of the last key: the hands finish easing out of the keys after it (weight from the last
 	// key), the holding hand from the palm they gave it at the release (the object stays where it was let go), each hand with
 	// the elbow pole (and the second hand the roll) planned for the release frame
@@ -217,7 +248,7 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	// the hand that holds a keyed carry follows its keys
 	const lead = (k, f, s, c) => {
 		for (const [id, o] of held) {
-			const pre = spec.props?.[o.prop]?.hand === k ? gripAround(id, o, f) ?? easeOut(id, o, f) : null;
+			const pre = spec.props?.[o.prop]?.hand === k ? gripAround(id, o, f) ?? approach(id, o, f) ?? easeOut(id, o, f) : null;
 			if (pre) return pre;
 			const h = spec.props?.[o.prop]?.hand === k ? heldAt(id, o, f) : null;
 			if (h) return { ...h, pole: planOf(id, o).get(f) };

package/src/motion3/object-pose.js

@@ -14,7 +14,9 @@
 //   f < grab              the scene pose
 //   grab <= f <= release  follows the prop's hand; without at/along it keeps the transform it had
 //                         against the palm axes at grab (no jump); at/along pin an offset (a group: its root, C15)
-//   f > release           frozen at the release pose
+//   f > release           frozen at the release pose; let go over a body that moves on its own (a seat of a truck the spec
+//                         drives with keys, a hinged lid), it rides that body's mover from the release on, keeping its world
+//                         pose at the release (riderOf): a lighter put down in the cab leaves with the truck
 //   no grab: in hand from frame 0; no release: in hand to the end (PR #14 behaviour)
 //   keys (C14, object-keys.js): the object leads and the hand follows; the object is still drawn
 //                         in the hand, so what the hand cannot reach shows as a residual (QA)
@@ -29,7 +31,8 @@ import { groupsOf } from "./scene.js";
 import { solveFrame } from "./compiler/compile.js";
 import { channelsAt } from "./compiler/channels.js";
 import { resolveBone } from "./bones.js";
-import { isFree, freePoseAt, beforeGrab, afterRelease } from "./free-motion.js";
+import { isFree, freePoseAt, beforeGrab, afterRelease, fallsAfter, corners, topOf, under, TOUCH } from "./free-motion.js";
+import { add } from "./compiler/math.js";
 
 /**
  * Body ids that make up `id` in a motionScene: [id] for a body (plus any bodies parented under
@@ -68,7 +71,7 @@ export function spanOf(out, o) {
 /** Without at/along a grabbed body, and a group, keeps its grab-frame palm offset; at/along pin one (a kit root, C15). */
 const keepsOffset = (scene, id, o) => o.at === undefined && o.along === undefined && ((!scene?.objects?.[id] && !!groupsOf(scene)[id]) || o.grab !== undefined);
 
-const solved = new WeakMap(), poses = new WeakMap();
+const solved = new WeakMap(), poses = new WeakMap(), riders = new WeakMap();
 
 /** What free-motion.js reads of a compile result: the spec, the scene and the time map. */
 const freeCtx = out => ({ spec: out.ctx.spec, scene: out.ctx.scene, timeMap: out.timeMap });
@@ -84,8 +87,36 @@ export function restingAt(out, id, f) {
 	return root && (mover === id ? root : compose(root, relative(restPose(scene, mover), restPose(scene, id))));
 }
 
-/** The solved frame at absolute f: out.frames, or solved once on demand outside a window. */
-function frameAt(out, f) {
+/**
+ * The spec.objects key a carry `id` (entry o) rides after its release: the key that moves the highest body under the
+ * record's centre at the release frame, when that key moves on its own (keys, a fall or a hinge; never a hand or a follow)
+ * and is not the record itself. null when the carry falls after its release, is never let go, or nothing under it moves.
+ */
+export function riderOf(out, id) {
+	if (!riders.has(out)) riders.set(out, new Map());
+	const cache = riders.get(out);
+	if (cache.has(id)) return cache.get(id);
+	const { spec, scene } = out.ctx, o = spec.objects?.[id], rest = restPose(scene, id), parts = partsOf(scene, id);
+	let best = null;
+	if (isCarried(o) && o.release !== undefined && rest && parts.length) {
+		const release = spanOf(out, o)[1];
+		if (release < out.frameCount - 1 && !fallsAfter(freeCtx(out), o, release)) {
+			const at = carriedAt(out, id, o, release), pts = parts.flatMap(p => corners({ ...compose(at, relative(rest, scene.objects[p])), half: scene.objects[p].half }));
+			const low = Math.min(...pts.map(p => p[1])), c = pts.reduce((a, p) => add(a, p), [0, 0, 0]).map(v => v / pts.length);
+			for (const [k, body] of Object.entries(scene.objects)) {
+				const mover = parts.includes(k) ? null : moverOf(spec, scene, k), entry = spec.objects?.[mover];
+				if (!mover || mover === id || isCarried(entry) || isFollow(entry)) continue;
+				const box = { ...objectPoseAt(out, k, release), half: body.half }, top = topOf(box);
+				if (under(box, c) && top <= low + TOUCH && (!best || top > best.top)) best = { mover, top };
+			}
+		}
+	}
+	cache.set(id, best?.mover ?? null);
+	return best?.mover ?? null;
+}
+
+/** The solved frame at absolute f: out.frames, or solved once on demand outside a window (or ahead of the frame being solved). */
+export function frameAt(out, f) {
 	const own = out.frames[f - (out.f0 ?? 0)];
 	if (own) return own;
 	if (!solved.has(out)) solved.set(out, new Map());
@@ -129,6 +160,8 @@ export function rootPoseAt(out, id, f, now = null) {
 		if (f < grab && rest) return restingAt(out, id, f);
 		const after = f > release ? afterRelease(freeCtx(out), id, o, f, release, carriedAt(out, id, o, release), release > 0 ? carriedAt(out, id, o, release - 1) : null) : null;
 		if (after) return after;
+		const by = f > release ? riderOf(out, id) : null;
+		if (by) { const at = carriedAt(out, id, o, release); return compose(rootPoseAt(out, by, f), relative(rootPoseAt(out, by, release), at)); }
 		return now && g === f ? carriedOn(out, id, o, f, now.s) : carriedAt(out, id, o, g);
 	}
 	if (!rest) return null;

package/src/motion3/scene.js

@@ -7,7 +7,8 @@
 // and scene.others (take-source.js), so the groups are rebuilt from the entries: groupsOf.
 // `others` lists the records with no box (an Empty, a light, an effect, a plane) by id with their
 // renderer and ancestors: a switch entry (C15) may name them, and a skill finds a kit's lit parts
-// there. A body that glows (record.glow) says so (`glow: true`).
+// there. A body that glows (record.glow) says so (`glow: true`); a record's grasp sockets (record.grasp,
+// ../object-grasp.js) ride along for the hand (sockets.js).
 import { objectSize } from "../object-size.js";
 import { mul, rx, ry, rz } from "./compiler/math.js";
 
@@ -50,11 +51,11 @@ export function motionScene(objects = []) {
 		if (!o || o.hidden) continue;
 		const size = objectSize(o), up = ancestorsOf(o, byId);
 		if (NO_BODY.has(o.renderer) || !(size.width > 0 && size.height > 0 && size.depth > 0)) {
-			others[o.id] = { renderer: o.renderer, ancestors: up.map(p => p.id) };
+			others[o.id] = { renderer: o.renderer, ancestors: up.map(p => p.id), ...(o.grasp ? { grasp: o.grasp } : {}) };
 			continue;
 		}
 		out[o.id] = { name: o.name, renderer: o.renderer, ...poseOf(o), half: [size.width / 2, size.height / 2, size.depth / 2],
-			ancestors: up.map(p => p.id), ...(up.length ? { ancestorPoses: up.map(poseOf) } : {}), ...(o.glow ? { glow: true } : {}) };
+			ancestors: up.map(p => p.id), ...(up.length ? { ancestorPoses: up.map(poseOf) } : {}), ...(o.glow ? { glow: true } : {}), ...(o.grasp ? { grasp: o.grasp } : {}) };
 	}
 	return { objects: out, groups: groupsOf({ objects: out }), others };
 }

package/src/motion3/schema/fields.js

@@ -11,7 +11,7 @@ export const KEY_FIELDS = ["f", "set", "step", "src"];
 export const USE_FIELDS = ["skill", "args", "f0"];
 /** Anchor fields by anchor kind (besides `kind`). */
 export const ANCHOR_FIELDS = { world: ["p"], body: ["p"], bone: ["bone", "offset"], segment: ["from", "to", "t", "tMin", "offset", "reach"],
-	object: ["object", "local"], landmark: ["name"], prop: ["prop", "point", "offset"], person: ["person", "bone", "offset"] };
+	object: ["object", "local", "socket", "grasp"], landmark: ["name"], prop: ["prop", "point", "offset"], person: ["person", "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. */

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 offset to the palm: no jump.";
+const NO_JUMP = "Without at/along it keeps its grab-frame palm offset: no jump.";
 /** 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 } };
 
@@ -65,13 +65,14 @@ export const NOTES = {
 	anchors: ["An anchor is a named point a hand can go to: key w_<anchor>_l / w_<anchor>_r from 0 to 1 with armw_<side> 1 (the IK arm).",
 		"An anchor name may not end in _l or _r.", "object anchors (a body or a group; local in its own axes) follow the object where it is (hinges, carries): put the other hand on a carried object with one; the carrying hand's own anchor stays where it took it. prop anchors are a point of a prop the other hand holds.",
 		"segment with reach slides from t toward tMin until the arm reaches it.",
+		"An object anchor with grasp (power, pinch, hook, palm) takes the hand by a socket of its object and the compiler turns the hand: power and hook put the knuckle line along the socket's axis with the palm on it, pinch holds at the fingertips, palm presses flat on the nearest face. socket names one (object.grasp sockets the user or you stored, or a thin part by its id: a bar, a grip, a magazine); without it the socket nearest local, or the shoulder. Two hands on one carried object: each hand an object anchor with grasp on its part (a rifle's grip and magazine). reachGrip on such an anchor closes the fingers to the grasp. Never key the wrist for it; a wrist you key (wtwist/wflex) wins.",
 		"person { person: <character id>, bone, offset? } is another character's joint where its installed take has it that frame (a hand on a shoulder, a push on the chest): install that character's take first; reachGrip on it allows the hand to touch that person."],
 	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)."],
 	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 frozen where it was let go.",
+		"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}`,
 		"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 "

package/src/motion3/schema/types.js

@@ -3,7 +3,7 @@
 // looks each field up here, and throws when one is missing, so a new field needs a type here.
 // Shared shapes are $refs into DEFS (describe.js adds the ones an answer uses).
 import { REF_KINDS, OBJECT_KEY_FIELDS } from "./fields.js";
-import { CONVENTIONS } from "../compiler/vocab.js";
+import { CONVENTIONS, GRASPS } from "../compiler/vocab.js";
 import { QA_LIMITS } from "../qa/checks.js";
 import { CAPSULES } from "../qa/geometry.js";
 
@@ -64,7 +64,7 @@ export const ANCHOR_TYPES = {
 	from: str("bone"), to: str("bone"), t: num("0 = from .. 1 = to", { default: 0.5 }), tMin: num("with reach: the lowest t to slide back to", { default: 0.15 }),
 	reach: side("slide toward `from` until this arm reaches"), object: str("scene object id"), local: ref("vec3", "point in the object's frame, m"),
 	name: { const: "mouth" }, prop: str("a prop held by the other hand"), point: str("a point of that prop, or origin"),
-	person: str("a character id"),
+	person: str("a character id"), socket: str("a socket of the object"), grasp: { enum: GRASPS, description: "the hand takes it by a socket" },
 };
 
 const palm = d => ref("vec3", `${d} [d, l, n] on the palm axes (d to the middle finger, l to the thumb side, n = d x l), m`);

package/src/motion3/skills/basic.js

@@ -4,6 +4,10 @@ import { add, apply, ry } from "../compiler/math.js";
 import { walk } from "../compiler/walk.js";
 import { keyBook, skillError } from "./book.js";
 import { walkEnd } from "./info.js";
+import { GRASP_FINGERS, GRASP_POINTS } from "../compiler/vocab.js";
+
+/** The fingers' point a reachGrip fits onto its anchor: the finger middles, or where a grasp holds the thing (the palm is -n on the right hand). */
+const graspPoint = (grasp, k) => (GRASP_POINTS[grasp] ? GRASP_POINTS[grasp].map((v, i) => (i === 2 && k === "r" ? -v : v)) : [0, 0, 0]);
 
 /** standIdle({ at: [x, z], heading = 0, until }): a neutral standing pose, arms down (FK). */
 export function standIdle(ctx) {
@@ -59,7 +63,9 @@ export function reachGrip(ctx) {
 	const { args, state } = ctx, k = args.side, name = args.anchor;
 	if (k !== "l" && k !== "r") skillError(ctx.tag, `args.side must be "l" or "r", got ${JSON.stringify(k)}`);
 	if (typeof name !== "string" || /_[lr]$/.test(name)) skillError(ctx.tag, "args.anchor must name an anchor (not ending in _l/_r)");
-	const reach = args.reach ?? 20, hold = args.hold ?? 22, release = args.release ?? 12, preset = args.fingers ?? "grip";
+	const reach = args.reach ?? 20, hold = args.hold ?? 22, release = args.release ?? 12;
+	// an anchor that takes a grasp closes the hand to that grasp's fingers (../sockets.js)
+	const grasp = (args.define ?? ctx.anchors?.[name])?.grasp, preset = args.fingers ?? GRASP_FINGERS[grasp] ?? "grip";
 	const w = `w_${name}_${k}`, fg = `fingers_${k}`, armw = `armw_${k}`, el = `elbow_${k}`, wasFk = !(state[armw] > 0.5);
 	// a take that ends after the hold but before the hand lets go cuts the release: the grip holds to the last frame
 	const last = ctx.frames - 1, cut = ctx.f0 + reach + hold <= last && ctx.f0 + reach + hold + release > last;
@@ -75,7 +81,7 @@ export function reachGrip(ctx) {
 	const a = args.define ?? ctx.anchors?.[name], obj = a?.kind === "object" ? a.object : a?.kind === "person" ? `person:${a.person}` : null;
 	return {
 		keys: b.keys, end: cut ? last : ctx.f0 + reach + hold + release, ...(cut ? { cut: `release cut at f${last} (hold to the end)` } : {}), anchors: def,
-		props: { [prop]: { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: [0, 0, 0] } } },
+		props: { [prop]: { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: graspPoint(grasp, k) } } },
 		fits: [{ side: k, anchor: name, effector: { prop, point: "fingers" }, ...(args.orient === false ? { orient: false } : {}) }],
 		checks: { contacts: [{ name: `fingers on ${name}`, point: `prop:${prop}.fingers`, target: `anchor:${name}`, tol: 0.04, when: w }],
 			allow: obj ? [{ part: "hand", object: obj, depth: 0.04 }] : [] },

package/src/motion3/skills/info.js

@@ -34,10 +34,10 @@ export const SKILL_INFO = {
 	},
 	reachGrip: {
 		args: { anchor: str("not ending in _l/_r"), side: side("the hand"), reach: int("frames to reach", { default: 20 }), hold: int("frames held", { default: 22 }),
-			release: int("frames to let go", { default: 12 }), elbow: ref("vec3", "elbow pole"), fingers: { enum: FINGER_PRESETS, default: "grip" },
-			define: { type: "object", description: "an anchor (topic anchors) named args.anchor" }, orient: { type: "boolean", description: "false: no grip turn" } },
-		required: ["anchor", "side"], needs: "args.anchor in spec.anchors or args.define", frames: "reach + hold + release (54 by default)",
-		adds: ["props.<anchor>Grip (fingers point)", "fits: fingers onto the anchor", "checks.contacts \"fingers on <anchor>\"", "checks.allow hand on the anchor's object",
+			release: int("frames to let go", { default: 12 }), elbow: ref("vec3", "pole"), fingers: { enum: FINGER_PRESETS, default: "grip" },
+			define: { type: "object", description: "defines anchor args.anchor" }, orient: { type: "boolean", description: "false: no grip turn" } },
+		required: ["anchor", "side"], needs: "args.anchor in anchors or define", frames: "reach + hold + release (54)",
+		adds: ["props.<anchor>Grip (fingers point)", "fits: fingers on the anchor", "checks.contacts \"fingers on <anchor>\"", "checks.allow hand on its object",
 			"keys: w_<anchor>_<side>, fingers_<side>, armw_<side>"],
 		example: { f0: 10, args: { anchor: "bar", side: "r", define: { kind: "world", p: [-0.2, 1.2, 0.33] } } },
 		tune: { reach: 2, release: 2 },

package/src/motion3/sockets.js

@@ -0,0 +1,104 @@
+// Grasp sockets (lane socket): where and how a hand takes hold of an object, so the agent names the part and the
+// grasp and the compiler turns the hand. The grasp is the object's (sessions 02263581, 38322b5d: the agent computed
+// the wrist by hand and held a barbell 90 deg off, the bar through the palm; a rifle's second hand was measured off
+// the first). A socket is, in its record's own axes (metres from the base pivot, as an object anchor's `local`):
+//   at     the point the fingers close on
+//   axis   the line that runs across the palm, the knuckle line along it (a bar, a handle, a grip); none: any
+//   from   the side the hand comes from: the palm faces against it; none: the roll the arm holds most easily
+//          (compiler/socket-grip.js), or on a body with no axis the face nearest the point
+//   thumb  the end of the axis the thumb takes; none: the end-state-comfort end (socketPalm)
+// A record stores named sockets in `grasp` (src/object-grasp.js); every thin body (two half sizes under THIN m: a
+// 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.
+import { add, sub, scale, norm, cross, dot, len, apply, ry, T } from "./compiler/math.js";
+import { partsOf } from "./object-pose.js";
+
+const THIN = 0.045, AXES = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+const flat = (v, n) => sub(v, scale(n, dot(v, n)));
+
+/** The long axis index of a thin body's half sizes, else -1. */
+function thinAxis(half) {
+	if (!half) return -1;
+	const long = [0, 1, 2].reduce((a, i) => (half[i] > half[a] ? i : a), 0);
+	return [0, 1, 2].filter(i => i !== long).every(i => half[i] < THIN) ? long : -1;
+}
+
+/** 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;
+
+/**
+ * Every socket of body or group `id`: [{ name, owner, at, axis?, from?, thumb? }], each in its owner's axes. The record's
+ * own sockets by name; a part's as "<part>.<name>"; a thin part's derived one by the part id.
+ */
+export function socketsOf(scene, id) {
+	const out = [], own = (owner, prefix) => Object.entries(stored(scene, owner) ?? {}).forEach(([name, s]) => out.push({ ...s, name: prefix + name, owner }));
+	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] });
+	}
+	return out;
+}
+
+/** The socket of `id` named `name`, or undefined. */
+export const socketNamed = (scene, id, name) => socketsOf(scene, id).find(s => s.name === name);
+
+/** 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) };
+}
+
+/** The outward normal of the face of the box (of boxes [{ pos, R, half }], base pivots) nearest world point p, or undefined. */
+export function faceFrom(boxes, p) {
+	let best;
+	for (const b of boxes) {
+		const q = apply(T(b.R), sub(p, add(b.pos, apply(b.R, [0, b.half[1], 0])))), out = [0, 1, 2].map(i => Math.abs(q[i]) - b.half[i]);
+		const i = [0, 1, 2].reduce((m, j) => (out[j] > out[m] ? j : m), 0), gap = Math.max(...out);
+		if (!best || gap < best.gap) best = { gap, n: scale([b.R[0][i], b.R[1][i], b.R[2][i]], q[i] < 0 ? -1 : 1) };
+	}
+	return best?.n;
+}
+
+/** How far world point q is from a world socket: from its axis line through p, else from p. */
+export function socketDistance(w, q) {
+	const v = sub(q, w.p);
+	return len(w.axis ? flat(v, w.axis) : v);
+}
+
+/**
+ * The palm frame (columns d, l, n of compiler/limbs.js palmAxes: d to the middle finger, l to the thumb side, n = d x
+ * l; the palm is -n on the right hand, +n on the left) a grasp of `type` takes on world socket w, the forearm along fwd,
+ * the body turned yawDeg. Along an axis (not a flat palm): with `from` the palm faces against it and the knuckle line
+ * runs along the axis; without, the fingers stay on the forearm's line across the axis (a power grip turns the forearm,
+ * not the wrist) and the palm closes on it. The thumb takes `thumb`'s end, else the end-state-comfort end (people take
+ * the grip that ends comfortable, Rosenbaum): up when the forearm is level, toward the midline when it points down or
+ * up. Without an axis the palm faces against `from` (anchorSocket gives a box face's), the fingers on the forearm's line.
+ */
+export function socketPalm(side, w, type, fwd, yawDeg = 0) {
+	const right = side === "Right", sign = v => (right ? v : scale(v, -1));
+	// a side along the axis leaves no knuckle line across it: the palm then just faces against the side (below)
+	if (w.axis && type !== "palm" && !(w.from && len(flat(w.axis, w.from)) < 1e-3)) {
+		if (w.from) {
+			const n = sign(w.from), l0 = norm(flat(w.axis, n)), pick = l => (w.thumb ? dot(l, w.thumb) : dot(cross(l, n), fwd));
+			const l = pick(l0) >= pick(scale(l0, -1)) ? l0 : scale(l0, -1);
+			return cols(cross(l, n), l, n);
+		}
+		const d = across(fwd, w.axis), medial = apply(ry(yawDeg), [right ? 1 : -1, 0, 0]), vy = Math.abs(d[1]);
+		const want = w.thumb ?? flat(add(scale([0, 1, 0], 1 - vy), scale(medial, vy)), d), l0 = norm(flat(w.axis, d));
+		const l = dot(l0, want) >= 0 ? l0 : scale(l0, -1);
+		return cols(d, l, cross(d, l));
+	}
+	const n = sign(w.from ?? scale(fwd, -1)), d = across(fwd, n);
+	return cols(d, cross(n, d), n);
+}
+
+/** fwd made perpendicular to v (unit); any perpendicular when fwd runs along v. */
+function across(fwd, v) {
+	const d = flat(fwd, v);
+	return norm(len(d) > 1e-3 ? d : flat(Math.abs(v[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0], v));
+}
+
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];

package/src/motion3/take-edit.js

@@ -148,7 +148,7 @@ export function renderTakeEdit(take) {
 		if (track.pos) { next.pos = new Float32Array(D * 3); at.forEach(({ i0, i1, t }, f) => lerp(next.pos, f * 3, track.pos, i0 * 3, track.pos, i1 * 3, t, 3)); }
 		if (track.quat) { next.quat = new Float32Array(D * 4); at.forEach(({ i0, i1, t }, f) => nlerp(next.quat, f * 4, track.quat, i0 * 4, track.quat, i1 * 4, t)); }
 		if (track.lvl) { next.lvl = new Float32Array(D); at.forEach(({ i0, i1, t }, f) => lerp(next.lvl, f, track.lvl, i0, track.lvl, i1, t, 1)); }
-		for (const key of ["vis", "hold"]) if (track[key]) { next[key] = new Uint8Array(D); at.forEach(({ near }, f) => { next[key][f] = track[key][near]; }); }
+		for (const key of ["vis", "hold", "world"]) if (track[key]) { next[key] = new Uint8Array(D); at.forEach(({ near }, f) => { next[key][f] = track[key][near]; }); }
 		return [id, next];
 	}));
 	return { ...take, frameCount: D, frames: D, rot, hips, objects, edit, editRendered: true };

package/src/motion3/take.js

@@ -6,12 +6,13 @@
 // world space: one track per spec.objects key (a group: its root only). A switch entry (C15)
 // bakes only vis and lvl, no pos/quat: its record keeps its own place (object-travel.js). A follow
 // entry (C16) bakes pos/quat with hold on every frame: its track is world space throughout. A free entry
-// (C17) bakes pos/quat (and vis/lvl when it names them), world space, no hold.
+// (C17) bakes pos/quat (and vis/lvl when it names them), world space, no hold. A carry that rides a moving body after
+// its release (object-pose.js riderOf) marks those frames `world`: world space too, though no hand holds it.
 import { toLocal } from "./compiler/skeleton.js";
 import { sub, apply, ry, quatFromMat, mul } from "./compiler/math.js";
 import { isCarried, isFollow, isSwitch } from "./carried.js";
 import { isFree } from "./free-motion.js";
-import { rootPoseAt, spanOf } from "./object-pose.js";
+import { rootPoseAt, spanOf, riderOf } from "./object-pose.js";
 
 const TAKE_SCHEMA = "cozyclay.take.v3";
 
@@ -36,7 +37,7 @@ export function bakeTake(sk, out, placement = { position: [0, 0, 0], yaw: 0 }, m
 		const pos = moves ? new Float32Array(F * 3) : null, quat = moves ? new Float32Array(F * 4) : null;
 		const named = rides || !moves || isFree(spec), vis = named && spec.visible ? new Uint8Array(F) : null, hold = rides ? new Uint8Array(F) : null;
 		const lvl = named && spec.level ? new Float32Array(F) : null;
-		const [grab, release] = carried ? spanOf(out, spec) : [0, 0];
+		const [grab, release] = carried ? spanOf(out, spec) : [0, 0], world = carried && riderOf(out, id) ? new Uint8Array(F) : null;
 		for (let f = 0; f < F; f++) {
 			if (vis) vis[f] = (out.baked?.[spec.visible]?.[f + f0] ?? 0) > 0.5 ? 1 : 0;
 			if (lvl) lvl[f] = Math.max(0, Math.min(4, out.baked?.[spec.level]?.[f + f0] ?? 1));
@@ -45,8 +46,9 @@ export function bakeTake(sk, out, placement = { position: [0, 0, 0], yaw: 0 }, m
 			if (!o) continue;
 			pos.set(o.pos, f * 3); quat.set(quatFromMat(o.R), f * 4);
 			if (hold) hold[f] = follows || (f + f0 >= grab && f + f0 <= release) ? 1 : 0;
+			if (world) world[f] = f + f0 > release ? 1 : 0;
 		}
-		objects[id] = { ...(moves ? { pos, quat } : {}), ...(vis ? { vis } : {}), ...(hold ? { hold } : {}), ...(lvl ? { lvl } : {}) };
+		objects[id] = { ...(moves ? { pos, quat } : {}), ...(vis ? { vis } : {}), ...(hold ? { hold } : {}), ...(world ? { world } : {}), ...(lvl ? { lvl } : {}) };
 	}
 	return { schema: TAKE_SCHEMA, fps: out.fps, frameCount: F, rig: sk.model, bones: sk.names.slice(), rot, hips, objects, placement, ...meta };
 }

package/src/object-catalog.jsx

@@ -7,6 +7,7 @@ const GROUP_LABELS_KO = {
 	"Set pieces": "세트 소품",
 	Lights: "조명",
 	Effects: "효과",
+	Text: "텍스트",
 };
 
 const OBJECT_LABELS_KO = {
@@ -24,6 +25,7 @@ const OBJECT_LABELS_KO = {
 	"Spot light": "스포트 조명",
 	Light: "조명",
 	Effect: "효과",
+	Text: "텍스트",
 };
 
 function displayObjectGroupName(name) {
@@ -73,7 +75,7 @@ export function CatalogueEntries({ onPick }) {
 					<span className={`add-object-swatch ${entry.kind}`} style={{ background: entry.color }} aria-hidden="true" />
 					<span>{displayObjectLabel(entry.label)}</span>
 					{/* An empty has no size to quote: say what it is instead of "0 × 0 m". */}
-					<small>{entry.light ? ko("practical light", "실제 조명") : entry.kind === EMPTY_KIND ? ko("node only", "노드 전용") : entry.kind === "effect" ? ko("smoke, fire, rain…", "연기, 불, 비…") : `${entry.footprint.width} × ${entry.footprint.depth} m`}</small>
+					<small>{entry.light ? ko("practical light", "실제 조명") : entry.kind === EMPTY_KIND ? ko("node only", "노드 전용") : entry.kind === "effect" ? ko("smoke, fire, rain…", "연기, 불, 비…") : entry.kind === "text" ? ko("words, signs, logos", "글자, 간판, 로고") : `${entry.footprint.width} × ${entry.footprint.depth} m`}</small>
 				</button>
 			))}
 		</div>

package/src/object-grasp.js

@@ -0,0 +1,38 @@
+/**
+ * Grasp sockets on a record (`grasp`): where and how a hand takes hold of it, in the record's own axes, so they move
+ * with it and save with it. { <name>: { at: [x, y, z] m from the base pivot, axis?: the line across the palm (a bar,
+ * a handle), from?: the side the hand comes from (the palm faces against it), thumb?: the axis end the thumb takes } }.
+ * A motion spec's object anchor with `grasp` takes a hand by one (src/motion3/sockets.js), and a thin body is a socket
+ * of its own without one. At most MAX sockets, names of letters, digits, _ and -.
+ */
+const MAX = 8, NAME = /^[A-Za-z0-9_-]{1,32}$/, REACH = 10;
+
+const vec = (v, limit) => (Array.isArray(v) && v.length === 3 && v.every(Number.isFinite) && v.every(x => Math.abs(x) <= limit) ? v.map(x => Math.round(x * 1e4) / 1e4) : null);
+const dir = v => { const u = vec(v, 1e3), n = u && Math.hypot(...u); return n > 1e-6 ? u.map(x => Math.round((x / n) * 1e4) / 1e4) : null; };
+
+/** The repaired sockets of a record, or null for none (invalid entries are dropped). */
+function normalizeObjectGrasp(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const out = {};
+	for (const [name, s] of Object.entries(value)) {
+		if (Object.keys(out).length >= MAX || !NAME.test(name) || !s || typeof s !== "object") continue;
+		const at = vec(s.at, REACH);
+		if (!at) continue;
+		out[name] = { at };
+		for (const k of ["axis", "from", "thumb"]) { const d = dir(s[k]); if (d) out[name][k] = d; }
+	}
+	return Object.keys(out).length ? out : null;
+}
+
+/** The grasp field of a stored record (normalizeSceneObject): kept when it has a socket. */
+export function objectGraspFields(record) {
+	const grasp = normalizeObjectGrasp(record?.grasp);
+	return grasp ? { grasp } : {};
+}
+
+/** The grasp part of an object.update patch: the sockets replace the record's own; `grasp: null` removes them. Only a change is returned. */
+export function objectGraspPatch(object, patch) {
+	if (patch?.grasp === undefined) return {};
+	const next = patch.grasp === null ? null : normalizeObjectGrasp(patch.grasp);
+	return JSON.stringify(next) === JSON.stringify(object.grasp ?? null) ? {} : { grasp: next };
+}

package/src/object-look.js

@@ -194,3 +194,5 @@ export function withShadowCapWarnings(result, objects) {
 	const warnings = shadowCapWarnings(objects, result?.affectedIds ?? []);
 	return warnings.length ? { ...result, warnings: [...(result.warnings ?? []), ...warnings] } : result;
 }
+// A record's grasp sockets ride the same normalize and patch paths (object-grasp.js).
+export { objectGraspFields, objectGraspPatch } from "./object-grasp.js";

package/src/object-travel.js

@@ -115,12 +115,15 @@ export function trackLevel(id, frame, take) {
 }
 
 /**
- * True while a compiled take holds the record in a hand (a grabbed cup): its track is in world
- * space then, so the carry from its own parents (the table it stood on) is cut, like `attach`.
+ * True while a compiled take holds the record in a hand (a grabbed cup), or the record rides a
+ * moving body after its release (`world`, take.js): its track is in world space then, so the
+ * carry from its own parents (the table it stood on) is cut, like `attach`.
  */
 function held(id, frame, take) {
 	const track = take?.objectTracks?.get?.(id);
-	return !!track?.hold && track.hold[trackFrame(track, frame)] === 1;
+	if (!track) return false;
+	const at = trackFrame(track, frame);
+	return track.hold?.[at] === 1 || track.world?.[at] === 1;
 }
 
 /** The record's own route sample (or compiled track) as a matrix, or null when it does not travel. */