cozyclay 3.0.2 → 3.0.3

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/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/studio-app-binding.js

@@ -1,6 +1,7 @@
 // The Studio's agent binding: inspection, admission and the agent's commands
 // over the editor's native state. App.jsx supplies the ports (reads, commits,
 // history, the action registry); this module owns no React or renderer state.
+import { taskTargetPorts } from "./bus-task-targets.js";
 import { createCommandBus } from "./command-bus.js";
 import { readElementDocument, elementReadback, elementPatchArgs, elementTarget, elementPatchReceipt } from "./commands/elements.js";
 import { physicsKeyStamp } from "./motion/physics-review.js";
@@ -220,8 +221,7 @@ export function createStudioAppBinding(ports) {
 			}, recordAction: (...args) => ports.recordAction(...args), beginAction: (...args) => ports.beginAction(...args),
 			readback: actionReadback, remember, receipt: id => receipts.get(id), isRetained: receipt => ports.isRetained(receipt),
 			canUndo: receipt => ports.canUndo(receipt), undo: () => ports.undo(), redo: () => ports.redo(),
-			history: redo => ports.history?.(redo), finishHistoryGesture: () => ports.finishHistoryGesture?.(),
-			readTarget: id => { refresh(); return tokens.get(id)?.token; },
+			history: redo => ports.history?.(redo), finishHistoryGesture: () => ports.finishHistoryGesture?.(), readTarget: id => { refresh(); return tokens.get(id)?.token; }, ...taskTargetPorts(ports),
 			captureToasts: listener => ports.captureToasts?.(listener), showRefusal: message => ports.showRefusal?.(message), emit: event => ports.emitCommandEvent?.(event),
 		} });
 		return actionBus;

package/src/studio-error-codes.js

@@ -4,7 +4,7 @@ export const STUDIO_ERROR_CODES = Object.freeze([
 	"INVALID_ARGUMENT", "INVALID_CONTEXT", "INVALID_IDENTITY", "INVALID_TURN_ID", "INVALID_SESSION_ID", "INVALID_RECEIPT", "INVALID_RANGE", "INVALID_REQUEST",
 	"UNKNOWN_TOOL", "UNKNOWN_VARIANT", "DUPLICATE_NAME", "CONTEXT_LIMIT", "CONTEXT_TOO_LARGE", "AMBIGUOUS_TARGET", "AMBIGUOUS_BASIS", "TARGET_NOT_READY", "TARGET_BUSY",
 	"STALE_TARGET", "STALE_SCENE", "STALE_ENVIRONMENT", "STALE_CURSOR", "CAPABILITY_MISSING", "LIVE_HUB_UNAVAILABLE", "AUTH_REQUIRED", "GENERATION_LIMIT", "RATE_LIMITED", "BACKEND_UNAVAILABLE",
-	"VERIFICATION_FAILED", "REPAIR_REGRESSED", "CANCELLED", "UNCERTAIN_APPLY", "UNDO_CONFLICT", "CONFIRMATION_REQUIRED", "TIMEOUT", "UNDO_EXPIRED", "INTERNAL_ERROR",
+	"VERIFICATION_FAILED", "REPAIR_REGRESSED", "CANCELLED", "UNCERTAIN_APPLY", "UNDO_CONFLICT", "CONFIRMATION_REQUIRED", "TIMEOUT", "UNDO_EXPIRED", "INTERNAL_ERROR", "SCOPE_DENIED", "SCOPE_BUSY",
 ]);
 /**
  * A refusal's code. A protocol error carries its own; a JavaScript runtime error (TypeError, ReferenceError, RangeError,

package/src/studio-motion-visual.js

@@ -9,7 +9,7 @@ import { compileSpec } from "./motion3/pipeline.js";
 import { motionScene } from "./motion3/scene.js";
 import { skeletonFor } from "./motion3/rigs/index.js";
 import { beatFrames, grabReleases, traceSeries, TRACE_COLORS } from "./motion3/beats.js";
-import { depthViews, projectPoint, trailPoints, viewCameras } from "./motion3/views.js";
+import { cameraAt, depthViews, projectPoint, trailPoints, viewCameras } from "./motion3/views.js";
 import { checkRef } from "./motion3/refs.js";
 import { renderWithGhosts } from "./ghost-set.js";
 import { GHOST_COLORS, sheetGhostSettings } from "./view-ghosts.js";
@@ -92,14 +92,14 @@ function viewSheet(args, r, { s, frames, span, grid, picks, ports, added }) {
 	if (!cameras.length) throw new StudioProtocolError("TARGET_NOT_READY", "views found no compiled frame of the take in the range.");
 	const cells = cameras.flatMap(cam => frames.map(frame => ({ cam, frame }))), target = args.ghosts ? s.targets.get(r.characterId) : null;
 	if (args.ghosts && !target?.rig) throw new StudioProtocolError("TARGET_NOT_READY", "ghosts pose a copy of the character's rig; it has not loaded in the editor yet.");
-	const sheet = buildContactSheet(cells, ({ cam, frame }) => {
-		const render = () => ports.renderFrameBuffer(frame, { eye: cam.eye, quaternion: cam.quaternion, fovDeg: cam.fovDeg, output: { width: side, height: side } });
+	const sheet = buildContactSheet(cells, ({ cam: view, frame }) => {
+		const cam = cameraAt(view, frame), render = () => ports.renderFrameBuffer(frame, { eye: cam.eye, quaternion: cam.quaternion, fovDeg: cam.fovDeg, output: { width: side, height: side } });
 		const tile = target ? renderWithGhosts({ rig: target.rig, take: target.motion, objects: s.objects }, frame, render) : render();
 		const dots = trails.flatMap(t => t.points.map(({ f, p }) => [f, projectPoint(cam, p, tile.width, tile.height), rgb(t.color)])
 			.filter(([, q]) => q).map(([f, [x, y], color]) => ({ x, y, color, r: f === frame ? 4 : 1.5, alpha: f <= frame ? 1 : 0.35, ring: f === frame })));
 		return { ...tile, data: paintDots(tile.data, tile.width, tile.height, dots) };
 	}, grid);
-	const views = cameras.map(cam => ({ name: cam.name, eye: round2(cam.eye), target: round2(cam.target) }));
+	const views = cameras.map(cam => ({ name: cam.name, eye: round2(cam.eye), target: round2(cam.target), ...(cam.ride ? { rides: "focus" } : {}) }));
 	const ref = { frames, layout: grid.layout, views, ...(added ? { addedView: added } : {}), focus: focus.length ? focus : "character", ...(trails.length ? { trails: trails.map(({ ref: of, color }) => ({ ref: of, color })) } : {}), ...(picks ? { picks } : {}),
 		...(target ? { ghosts: { ...sheetGhostSettings(), ...GHOST_COLORS } } : {}) };
 	return [{ dataUrl: ports.encodePng(sheet.data, sheet), width: sheet.width, height: sheet.height, frames, layout: grid.layout, views: views.map(v => v.name) }, ref];

package/tools/run-tests.mjs

@@ -14,7 +14,7 @@ if (!process.env.COZYCLAY_AGENT_SESSIONS_DIR) {
 }
 
 const NODE_FILES = [
-	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
+	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-reach-human.mjs", "test/motion3/verify-motion3-stance-grasp.mjs", "test/motion3/verify-motion3-grasp-friction.mjs", "test/motion3/verify-motion3-grasp-measure.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
 	"test/verify-proxy-figure-bounds.mjs",
 	"test/verify-character-capabilities.mjs",
 	"test/verify-root-path.mjs",