cozyclay 3.0.0 → 3.0.1

package/src/motion3/settle.js

@@ -0,0 +1,136 @@
+// How a falling object (C17, free-motion.js) comes to rest. It falls with its centre on a parabola, turning at the spin it
+// was let go with, and lands on its lowest point. Then it rolls about what touches the support. Landing on an edge or a
+// corner it rocks back onto the face nearest down, or falls over onto the face it leans to when it leans past that edge.
+// Then it goes over an edge onto a lower face while the landing has the energy (a share TIP of the drop; only one that hit
+// tilted or spinning, since a flat landing has nothing to tip it), or at once from a precarious face (one it can tilt less
+// than PRECARIOUS before its centre passes the edge). So a phone on its edge falls flat, a tilted box comes down on a face,
+// a can let go at a slant lies down, and a can or cup dropped upright stays upright. It only rolls onto a face that lowers
+// its centre by at least LOWER of its height, so a near cube stays the way it lands. The shape is the box around the
+// object's parts in its own frame, and its centre is the parts' volume-weighted centre. Every step is a rotation about a
+// pivot on the support, paced by gravity: closed form and deterministic.
+import { add, sub, scale, dot, cross, len, norm, mul, apply, axisRot, clamp } from "./compiler/math.js";
+import { G } from "./free-motion.js";
+
+/** The share of the drop height a landing spends tipping the object over an edge. */
+export const TIP = 0.3;
+const LOWER = 0.2, FLAT = 0.5, PRECARIOUS = 15, MIN_SPIN = 1, MAX_SPIN = 6 * Math.PI, MAX_STEPS = 3;
+const DOWN = [0, -1, 0];
+const AXES = [[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]];
+const deg = r => (r * 180) / Math.PI;
+
+/** The shape of part boxes { pos, R, half } given in the root frame: { com, lo, hi } (box around the corners); null without volume. */
+export function shapeOf(boxes) {
+	const solid = boxes.filter(b => b.half[0] * b.half[1] * b.half[2] > 1e-12);
+	if (!solid.length) return null;
+	let vol = 0, c = [0, 0, 0];
+	const corners = [];
+	for (const b of solid) {
+		const v = b.half[0] * b.half[1] * b.half[2];
+		vol += v;
+		c = add(c, scale(add(b.pos, apply(b.R, [0, b.half[1], 0])), v));
+		for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) corners.push(add(b.pos, apply(b.R, [x * b.half[0], y * b.half[1], z * b.half[2]])));
+	}
+	return { com: scale(c, 1 / vol), lo: [0, 1, 2].map(i => Math.min(...corners.map(p => p[i]))), hi: [0, 1, 2].map(i => Math.max(...corners.map(p => p[i]))) };
+}
+
+const boxCorners = s => [0, 1, 2, 3, 4, 5, 6, 7].map(i => [i & 1 ? s.hi[0] : s.lo[0], i & 2 ? s.hi[1] : s.lo[1], i & 4 ? s.hi[2] : s.lo[2]]);
+const world = (pose, p) => add(pose.pos, apply(pose.R, p));
+const lowest = (s, pose) => Math.min(...boxCorners(s).map(p => world(pose, p)[1]));
+/** The pose moved up or down so its lowest corner sits on the support top. */
+const snap = (s, pose, top) => ({ pos: [pose.pos[0], pose.pos[1] + top - lowest(s, pose), pose.pos[2]], R: pose.R });
+const about = (pose, pivot, Q) => ({ pos: add(pivot, apply(Q, sub(pose.pos, pivot))), R: mul(Q, pose.R) });
+/** The face whose outward normal points most nearly down. */
+const downFace = R => AXES.reduce((best, n, k) => (dot(apply(R, n), DOWN) > dot(apply(R, AXES[best]), DOWN) ? k : best), 0);
+/** Where the plane of face k lies along its axis, and the centre's distance to it (its height when it rests on k). */
+const facePlane = (s, k) => { const a = k >> 1; return AXES[k][a] > 0 ? s.hi[a] : s.lo[a]; };
+const heightOn = (s, k) => Math.abs(facePlane(s, k) - s.com[k >> 1]);
+
+/** The spin (rad/s, world axis times rate) that takes rotation Ra to Rb in one frame at fps; capped at MAX_SPIN, none under MIN_SPIN (a hand's jitter). */
+export function spinOf(Ra, Rb, fps) {
+	const D = mul(Rb, [[Ra[0][0], Ra[1][0], Ra[2][0]], [Ra[0][1], Ra[1][1], Ra[2][1]], [Ra[0][2], Ra[1][2], Ra[2][2]]]);
+	const a = Math.acos(clamp((D[0][0] + D[1][1] + D[2][2] - 1) / 2, -1, 1));
+	if (a * fps < MIN_SPIN) return [0, 0, 0];
+	const axis = norm([D[2][1] - D[1][2], D[0][2] - D[2][0], D[1][0] - D[0][1]]), rate = Math.min(MAX_SPIN, a * fps);
+	return len(axis) > 0 ? scale(axis, rate) : [0, 0, 0];
+}
+
+/** The fall through the air from `start` onto the support top: { tl (s), at(t) } with the centre on a parabola, turning at `spin`. */
+export function airPath(s, start, spin, top, fps) {
+	const rate = len(spin), com0 = world(start, s.com);
+	const at = t => {
+		const R = rate > 0 ? mul(axisRot(spin, deg(rate * t)), start.R) : start.R;
+		return { pos: sub(add(com0, [0, -0.5 * G * t * t, 0]), apply(R, s.com)), R };
+	};
+	const h = Math.max(0, lowest(s, start) - top);
+	if (rate === 0) return { tl: Math.sqrt((2 * h) / G), at };
+	// spinning: the first sub-frame step whose lowest corner reaches the top, then halved down to the touch
+	const dt = 1 / (fps * 8), cap = Math.sqrt((2 * (h + len(sub(s.hi, s.lo)))) / G) + dt;
+	let a = 0, b = dt;
+	while (b < cap && lowest(s, at(b)) > top) { a = b; b += dt; }
+	for (let i = 0; i < 24 && b - a > 1e-7; i++) { const m = (a + b) / 2; if (lowest(s, at(m)) > top) a = m; else b = m; }
+	return { tl: b, at };
+}
+
+/** A step's duration (s): gravity-paced by the centre's height and the angle it rolls through. */
+const stepTime = (height, angle) => 0.12 + 0.9 * Math.sqrt(Math.max(height, 1e-4) / G) * Math.sqrt(angle / 90);
+
+/**
+ * From the pose it lands in, how it rolls to rest on the support top with `energy` (m of drop) to tip over edges:
+ * { steps: [{ from, pivot, axis, angle, time }], rest, time }. `lean` (horizontal) is the way a spin tips it: it gives a flat
+ * landing the energy and breaks a tie between edges.
+ */
+export function settlePath(s, impact, top, energy, lean = [0, 0, 0]) {
+	const steps = [];
+	let pose = snap(s, impact, top), time = 0;
+	const push = (pivot, axis, angle) => {
+		const height = world(pose, s.com)[1] - top, t = stepTime(height, angle);
+		steps.push({ from: pose, pivot, axis, angle, time: t });
+		pose = snap(s, about(pose, pivot, axisRot(axis, angle)), top);
+		time += t;
+	};
+	// landed on an edge or a corner: back onto the face nearest down, or over onto the face it leans to when it leans past
+	// that edge (more than the angle its centre needs to pass it), rolling about the corners on the support
+	let k = downFace(pose.R);
+	const tiltOf = j => deg(Math.acos(clamp(dot(apply(pose.R, AXES[j]), DOWN), -1, 1))), tilt = tiltOf(k);
+	if (tilt > FLAT) {
+		const side = [0, 1, 2, 3, 4, 5].filter(j => j >> 1 !== k >> 1).reduce((a, j) => (tiltOf(j) < tiltOf(a) ? j : a), k === 0 || k === 1 ? 2 : 0);
+		if (tilt > deg(Math.atan2(heightOn(s, side), heightOn(s, k)))) k = side;
+		const touching = boxCorners(s).map(p => world(pose, p)).filter(p => p[1] <= top + 1e-4);
+		const n = apply(pose.R, AXES[k]);
+		push(scale(touching.reduce(add, [0, 0, 0]), 1 / touching.length), norm(cross(n, DOWN)), tiltOf(k));
+	}
+	// over an edge onto a lower face while the landing has the energy, at once from a precarious face (or a centre past the
+	// edge); a flat landing with no spin has none
+	let left = tilt > FLAT || len(lean) > 0 ? energy : 0;
+	for (let i = 0; i < MAX_STEPS; i++) {
+		const com = world(pose, s.com), cK = com[1] - top;
+		let best = null;
+		for (let j = 0; j < 6; j++) {
+			if (j >> 1 === k >> 1) continue;
+			const out = apply(pose.R, AXES[j]), edge = world(pose, AXES[j].map((v, a) => (v ? facePlane(s, j) : a === k >> 1 ? facePlane(s, k) : s.com[a])));
+			const w = -dot(sub(com, edge), out), cJ = heightOn(s, j);
+			if (!(w < 0 || cJ < cK * (1 - LOWER))) continue;
+			const cost = w < 0 || deg(Math.atan2(w, cK)) < PRECARIOUS ? 0 : Math.hypot(cK, w) - cK, side = dot(out, lean);
+			if (!best || cost < best.cost - 1e-9 || (Math.abs(cost - best.cost) <= 1e-9 && side > best.side)) best = { j, out, edge, cost, side };
+		}
+		if (!best || best.cost > left) break;
+		left -= best.cost;
+		const touching = boxCorners(s).map(p => world(pose, p)).filter(p => p[1] <= top + 1e-4 && dot(sub(p, best.edge), best.out) >= -1e-4);
+		push(touching.length ? scale(touching.reduce(add, [0, 0, 0]), 1 / touching.length) : [best.edge[0], top, best.edge[2]], norm(cross(best.out, DOWN)), 90);
+		k = best.j;
+	}
+	return { steps, rest: pose, time };
+}
+
+/** The pose `u` seconds after it landed, along the settle path: each step rolls about its pivot, accelerating like a fall. */
+export function settledAt(path, u) {
+	let t = u;
+	for (const st of path.steps) {
+		if (t < st.time) { const s = t / st.time; return about(st.from, st.pivot, axisRot(st.axis, st.angle * s * s)); }
+		t -= st.time;
+	}
+	return path.rest;
+}
+
+/** The energy (m of drop) a spin adds: its kinetic energy over m g, for the box's radius of gyration about its centre. */
+export const spinEnergy = (s, spin) => (len(spin) ** 2 * ((s.hi[0] - s.lo[0]) ** 2 + (s.hi[1] - s.lo[1]) ** 2 + (s.hi[2] - s.lo[2]) ** 2)) / (24 * G);

package/src/motion3/skills/basic.js

@@ -71,7 +71,8 @@ export function reachGrip(ctx) {
 	if (!cut) b.at(reach + hold + release, { [w]: 0, [fg]: { ...state[fg], [preset]: 0 }, ...(wasFk ? { [armw]: 0 } : {}) });
 	const S = k === "l" ? "Left" : "Right", prop = `${name}Grip`;
 	const def = args.define ? { [name]: args.define } : {};
-	const obj = args.define?.kind === "object" ? args.define.object : ctx.anchors?.[name]?.kind === "object" ? ctx.anchors[name].object : null;
+	// the hand may touch what it grips: an object, or the other person (people.js) whose joint the anchor is on
+	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] } } },

package/src/motion3/skills/flip.js

@@ -0,0 +1,200 @@
+// flip: a standing back or front tuck, or a cartwheel, from the standing pose keyed before f0. The root and the feet (and
+// the cartwheel's hands) are keyed every frame from closed-form curves whose speeds join without a kink (no POP); the
+// arms, spine and head are keyed at the phase edges and the channels' own interpolation carries them between.
+// - back/front: crouch, push-off (the heels roll up over the balls), a ballistic flight (the hips on a parabola under
+//   gravity, so QA reads a jump, not a float) with the knees tucked to the chest while the whole body turns 360 deg a turn
+//   (pitch, - backward), a landing that absorbs the fall, and the stand.
+// - cartwheel: the lead foot steps out, then the body rolls 360 deg toward args.side like a wheel whose spokes are the
+//   straddled legs and the arms overhead: each frame the hips sit as high as the lowest spoke touching the floor allows,
+//   and a hand or foot whose spoke is down stays planted where it touched.
+// Both end with the turn's full angle and then 0 on the last two frames (the same pose), so a later key at 0 does not
+// unwind it. Poles are given so the knees and elbows bend toward the turning body's front (pose.js tiltFrame).
+import { add, sub, scale, apply, mul, rx, ry, rz, dist, T } from "../compiler/math.js";
+import { pivot } from "../compiler/walk-pelvis.js";
+import { tiltFrame } from "../compiler/pose.js";
+import { skillError } from "./book.js";
+
+const G = 9.81 / (24 * 24); // m per frame^2 at the timeline's 24 fps
+const CROUCH = 10, PUSH = 5, LAND = 6, RISE = 14, TOE_OFF = 50;
+const clamp01 = u => Math.min(1, Math.max(0, u));
+const ease = u => { const t = clamp01(u); return t * t * (3 - 2 * t); };
+const mix = (a, b, t) => a + (b - a) * t;
+const mix3 = (a, b, t) => a.map((v, i) => v + (b[i] - v) * t);
+const window = (u, a, b, c, d) => ease((u - a) / (b - a)) - ease((u - c) / (d - c));
+const SIDE = { l: 1, r: -1 };
+const bodyFrame = (h, pitch, roll) => mul(ry(h), mul(rx(pitch), rz(roll)));
+/** A pole the turning body (B) holds as `local`, written as the channel pose.js turns by its own frame. */
+const poleFor = (h, pitch, roll, B, local) => apply(T(tiltFrame(h, pitch, roll)?.R ?? ry(h)), apply(B, local));
+
+/**
+ * fyaw/fpitch that make pose.js aim the foot (orientFoot, in its tilt frame) where the turning body B holds it at fpitch
+ * `fp` in its own frame: the toe direction solved back through the frame pose.js reads the channels in (clamped to fpitch's
+ * range). Nearer upright pose.js reads them on the level, as for any foot, and they pass as they are.
+ */
+function footAim(b, k, pitch, roll, B, fp) {
+	const tilt = tiltFrame(b.h, pitch, roll);
+	if (!tilt) return { fyaw: b.h, fpitch: fp };
+	const rest = b.toe[k], want = apply(B, apply(rx(fp), rest)), d = apply(T(tilt.R), want);
+	const phi = Math.atan2(-rest[1], rest[2]), deg = 180 / Math.PI;
+	const p = Math.asin(Math.max(-1, Math.min(1, -d[1] / Math.hypot(...d)))) - phi;
+	return { fyaw: b.h + Math.atan2(d[0], d[2]) * deg, fpitch: Math.max(-60, Math.min(90, p * deg)) };
+}
+
+function base(ctx) {
+	const { sk, args, state } = ctx, I = sk.index, P = sk.restWorldPos;
+	if (!state.foot_l || !state.foot_r || !state.root) skillError(ctx.tag, "needs a standing pose keyed before f0 (use standIdle or another skill first)");
+	const h = args.heading ?? state.yaw ?? 0, R = ry(h), hips = P[I.Hips];
+	const leg = dist(P[I.LeftUpLeg], P[I.LeftLeg]) + dist(P[I.LeftLeg], P[I.LeftFoot]), arm = dist(P[I.LeftArm], P[I.LeftForeArm]) + dist(P[I.LeftForeArm], P[I.LeftHand]);
+	return { h, R, F: apply(R, [0, 0, 1]), L: apply(R, [1, 0, 0]), ank: P[I.LeftFoot][1], y0: hips[1] - 0.01, leg, arm,
+		feet: { l: state.foot_l.slice(), r: state.foot_r.slice() }, root: state.root.slice(),
+		hipOff: { l: sub(P[I.LeftUpLeg], hips), r: sub(P[I.RightUpLeg], hips) }, shoulder: { l: sub(P[I.LeftArm], hips), r: sub(P[I.RightArm], hips) },
+		toe: { l: sub(P[I.LeftToeBase], P[I.LeftFoot]), r: sub(P[I.RightToeBase], P[I.RightFoot]) } };
+}
+
+function tuck(ctx, b, kind) {
+	// one turn from a standing jump whose hips rise H at the top: the curves below are measured clean for that flip (a
+	// higher jump or more turns would need its own tuck timing, so the skill takes neither)
+	const { args } = ctx, s = kind === "back" ? -1 : 1, turn = s * 360, H = 0.5;
+	const travel = args.travel ?? (kind === "back" ? -0.25 : 0.4);
+	const yT = b.y0 + 0.05, yL = b.y0 - 0.02;                // the hips at take-off (toes pointed) and at touch-down
+	const Tf = Math.max(10, Math.round(Math.sqrt(2 * (H - 0.05) / G) + Math.sqrt(2 * (yT + H - 0.05 - yL) / G)));
+	const v0 = (yL - yT + (G * Tf * Tf) / 2) / Tf, vL = v0 - G * Tf, yc = yT - (v0 * PUSH) / 2, bottom = yL + (vL * LAND) / 2;
+	const vx = travel / (PUSH / 2 + Tf + LAND / 2);
+	const t0 = ctx.f0, tP = t0 + CROUCH, tA = tP + PUSH, tD = tA + Tf, tL = tD + LAND, tE = tL + RISE;
+	const land = k => add(b.feet[k], scale(b.F, travel)), ball = k => add(b.feet[k], apply(b.R, b.toe[k]));
+	const hipsAt = f => {
+		let y, x;
+		if (f <= tP) { y = mix(b.root[1], yc, ease((f - t0) / CROUCH)); x = 0; }
+		else if (f <= tA) { const t = f - tP; y = yc + (v0 / PUSH) * t * t / 2; x = (vx / PUSH) * t * t / 2; }
+		else if (f <= tD) { const t = f - tA; y = yT + v0 * t - (G * t * t) / 2; x = (vx * PUSH) / 2 + vx * t; }
+		else if (f <= tL) { const t = f - tD; y = yL + vL * t - (vL / LAND) * t * t / 2; x = (vx * PUSH) / 2 + vx * Tf + vx * t - (vx / LAND) * t * t / 2; }
+		else { y = mix(bottom, b.y0, ease((f - tL) / RISE)); x = travel; }
+		return add([b.root[0], y, b.root[2]], scale(b.F, x));
+	};
+	// the turn starts 2 frames before take-off and ends 3 after touch-down
+	const pitchAt = f => turn * ease((f - tA + 2) / (Tf + 5)), frameAt = f => bodyFrame(b.h, pitchAt(f), 0);
+	// in the air the feet ride the body: from where they left the floor, through the tuck, to where they land, all in its frame
+	const local = (f, p) => apply(T(frameAt(f)), sub(p, hipsAt(f)));
+	const offL = { l: local(tA, pivot(ball("l"), b.h, TOE_OFF, b.feet.l)), r: local(tA, pivot(ball("r"), b.h, TOE_OFF, b.feet.r)) };
+	const onL = { l: local(tD, land("l")), r: local(tD, land("r")) };
+	const keys = [];
+	for (let f = t0; f <= tE + 1; f++) {
+		const pitch = f > tE ? 0 : pitchAt(f), B = bodyFrame(b.h, pitch, 0), hips = hipsAt(f), u = (f - tA) / Tf;
+		const tk = f > tA && f < tD ? window(u, 0.12, 0.34, 0.6, 0.82) : 0;
+		const set = { root: hips, yaw: b.h, pitch, roll: 0, armw_l: 0, armw_r: 0, fyaw_l: b.h, fyaw_r: b.h };
+		for (const k of ["l", "r"]) {
+			let foot, fp;
+			if (f <= tP) { foot = b.feet[k]; fp = 0; }
+			else if (f <= tA) { fp = TOE_OFF * ease((f - tP) / PUSH); foot = pivot(ball(k), b.h, fp, b.feet[k]); }
+			else if (f < tD) {
+				const a = 1 - ease(u / 0.2), c = ease((u - 0.72) / 0.28);
+				const mid = add(b.hipOff[k], mix3([0, -b.leg * 0.97, 0], [SIDE[k] * 0.02, -0.24, 0.16], tk));
+				foot = add(hips, apply(B, add(add(scale(offL[k], a), scale(onL[k], c)), scale(mid, 1 - a - c))));
+				fp = mix(mix(TOE_OFF, 30, ease(u / 0.2)), 0, ease((u - 0.7) / 0.3));
+			} else { foot = land(k); fp = 0; }
+			const aim = f > tA && f < tD ? footAim(b, k, pitch, 0, B, fp) : { fyaw: b.h, fpitch: fp };
+			Object.assign(set, { [`foot_${k}`]: foot, [`fpitch_${k}`]: aim.fpitch, [`fyaw_${k}`]: aim.fyaw, [`knee_${k}`]: poleFor(b.h, pitch, 0, B, [SIDE[k] * 0.05, 0.5 * tk, 1]) });
+		}
+		keys.push({ f, set });
+	}
+	// the arms, spine and head at the phase edges: back in the crouch, overhead at take-off, to the shins in the tuck,
+	// forward for the landing, then down
+	const head = kind === "back" ? [-12, 18] : [10, 25];
+	for (const [f, sw, bd, sp, hd] of [[t0, 0, 0, 0, 0], [tP, -45, 15, 20, 0], [tA, 160, 5, -8, head[0]], [Math.round(tA + 0.3 * Tf), 55, 85, 32, head[1]],
+		[Math.round(tA + 0.62 * Tf), 55, 85, 32, head[1]], [tD, 75, 25, 22, 0], [tL, 70, 25, 28, 0], [tE, 0, 0, 0, 0]]) {
+		keys.push({ f, set: { aswing_l: sw, aswing_r: sw, abend_l: bd, abend_r: bd, spine_pitch: sp, head_pitch: hd } });
+	}
+	return { keys, end: tE + 1 };
+}
+
+function cartwheel(ctx, b) {
+	const { args } = ctx, dir = args.side === "r" ? -1 : 1, rs = -dir;   // toward the character's left the head goes to +x: roll -
+	const W = 12, ROT = 34, REC = 14, t0 = ctx.f0, tR = t0 + W, tC = tR + ROT, tE = tC + REC;
+	const lead = dir > 0 ? "l" : "r", trail = lead === "l" ? "r" : "l";
+	// spokes from the hips in the body's frame (x the body's left): the legs straddled, the arms overhead and apart
+	const spoke = { foot: k => add(b.hipOff[k], [SIDE[k] * 0.3, -b.leg * 0.93, 0]), hand: k => add(b.shoulder[k], [SIDE[k] * 0.32, b.arm * 0.88, 0]) };
+	const floor = { foot: b.ank, hand: 0.1 };
+	// the order the ends touch down rolling toward the lead side; the body pivots on each in turn like a wheel on its spokes
+	const order = [["foot", lead], ["hand", lead], ["hand", trail], ["foot", trail], ["foot", lead]];
+	const rollAt = f => f <= tR ? 0 : f <= tC ? rs * 360 * ease((f - tR) / ROT) : rs * 360;
+	const end = (f, hips, part, k) => add(hips, apply(bodyFrame(b.h, 0, rollAt(f)), spoke[part](k)));
+	// start: the trail foot stays, the lead foot steps out so both stand on their spokes; the hips over them
+	const B0 = bodyFrame(b.h, 0, 0), hips0 = sub(b.feet[trail], apply(B0, spoke.foot(trail))), stepTo = end(tR, hips0, "foot", lead);
+	stepTo[1] = b.ank;
+	const raw = [], plants = { foot: { l: [], r: [] }, hand: { l: [], r: [] } };
+	let at = 0, pivot = b.feet[lead].slice(), from = tR;
+	plants.foot[trail].push({ a: t0, b: tR, p: b.feet[trail] });
+	for (let f = t0; f <= tE + 1; f++) {
+		if (f <= tR) { raw.push(mix3(b.root, hips0, ease((f - t0) / W))); continue; }
+		if (f === tR + 1) pivot = stepTo.slice();
+		let hips = sub(pivot, apply(bodyFrame(b.h, 0, rollAt(f)), spoke[order[at][0]](order[at][1])));
+		const next = order[at + 1];
+		if (next && f <= tC) {
+			const e = end(f, hips, ...next);
+			if (e[1] <= floor[next[0]]) {
+				// the end touched between the frames: pivot where it crossed the floor, so the hips do not jump
+				const ep = end(f - 1, raw.at(-1), ...next), h1 = ep[1] - floor[next[0]], h2 = e[1] - floor[next[0]];
+				const cross = mix3(ep, e, h1 > 0 ? h1 / (h1 - h2) : 1);
+				plants[order[at][0]][order[at][1]].push({ a: from, b: f, p: pivot });
+				at++; from = f; pivot = [cross[0], floor[next[0]], cross[2]];
+				hips = sub(pivot, apply(bodyFrame(b.h, 0, rollAt(f)), spoke[next[0]](next[1])));
+			}
+		}
+		raw.push(hips);
+	}
+	plants[order[at][0]][order[at][1]].push({ a: from, b: tE + 1, p: pivot });
+	// the trail foot that landed stays down to the end too
+	const last = order[order.length - 2];
+	if (at >= order.length - 1) plants[last[0]][last[1]].at(-1).b = tE + 1;
+	// the pivot path turns at each touch-down: blurred over a few frames (the planted ends absorb it), then the stand
+	const blur = raw.map((p, i) => { let s = [0, 0, 0], w = 0; for (let d = -3; d <= 3; d++) { const j = Math.min(raw.length - 1, Math.max(0, i + d)), g = Math.exp(-(d * d) / 4); s = add(s, scale(raw[j], g)); w += g; } return scale(s, 1 / w); });
+	const hipsAt = f => f <= tC ? blur[f - t0] : add(blur[tC - t0], [0, (b.y0 - blur[tC - t0][1]) * ease((f - tC) / REC), 0]);
+	// a planted end the turning body has rolled away from is drawn toward its hip or shoulder until the limb reaches it
+	const reach = (p, from, n) => { const v = sub(p, from), d = Math.hypot(...v); return d > n ? add(from, scale(v, n / d)) : p; };
+	// a hand or foot near its plant: easing onto it over the 6 frames before, held, then let go by following the body from
+	// where it left the floor (its place in the body's frame then) toward its spoke, so it lifts without a jolt
+	const touch = (part, k, f, free) => {
+		for (const r of plants[part][k]) {
+			if (f >= r.a - 6 && f <= r.b) return mix3(free, r.p, ease((f - r.a + 6) / 6));
+			if (f > r.b && f <= r.b + 10) {
+				const at = bodyFrame(b.h, 0, rollAt(r.b)), left = apply(T(at), sub(r.p, hipsAt(r.b)));
+				const follow = add(hipsAt(f), apply(bodyFrame(b.h, 0, rollAt(f)), mix3(left, spoke[part](k), ease((f - r.b - 1) / 9))));
+				return mix3(r.p, follow, ease((f - r.b) / 8));
+			}
+		}
+		return free;
+	};
+	const planted = (part, k, f) => plants[part][k].some(r => f >= r.a && f <= r.b);
+	// where the feet stand after the roll: a planted one where it is, else under its spoke at the roll's end
+	const landed = Object.fromEntries(["l", "r"].map(k => { const p = planted("foot", k, tC) ? plants.foot[k].at(-1).p.slice() : end(tC, hipsAt(tC), "foot", k); p[1] = b.ank; return [k, p]; }));
+	const keys = [];
+	for (let f = t0; f <= tE + 1; f++) {
+		const roll = f === tE + 1 ? 0 : rollAt(f), B = bodyFrame(b.h, 0, rollAt(f)), hips = hipsAt(f);
+		const set = { root: hips, yaw: b.h, pitch: 0, roll };
+		for (const k of ["l", "r"]) {
+			let foot;
+			if (f <= tR && k === lead) { const w = ease((f - t0 - 1) / (W - 4)); foot = add(mix3(b.feet[k], stepTo, w), [0, 0.07 * Math.sin(Math.PI * w), 0]); }
+			else if (f > tC) foot = landed[k];
+			else {
+				const down = ease((f - tC + 4) / 4);
+				foot = reach(mix3(touch("foot", k, f, end(f, hips, "foot", k)), landed[k], down), add(hips, apply(B, b.hipOff[k])), b.leg * 0.995);
+			}
+			const aim = f > tR && f <= tC ? footAim(b, k, 0, rollAt(f), B, 0) : { fyaw: b.h, fpitch: 0 };
+			Object.assign(set, { [`foot_${k}`]: foot, [`fyaw_${k}`]: aim.fyaw, [`fpitch_${k}`]: aim.fpitch, [`knee_${k}`]: poleFor(b.h, 0, roll, B, [SIDE[k] * 0.05, 0, 1]),
+				[`hand_${k}`]: reach(f > tR && f <= tC ? touch("hand", k, f, end(f, hips, "hand", k)) : end(f, hips, "hand", k), add(hips, apply(B, b.shoulder[k])), b.arm * 0.995), [`elbow_${k}`]: poleFor(b.h, 0, roll, B, [SIDE[k] * 0.4, 0, -1]),
+				[`armw_${k}`]: f <= tR ? 0 : f <= tC ? ease((f - tR) / 6) : 1 - ease((f - tC) / 8) });
+		}
+		// the FK arms overhead along the hand spokes, so the hand eases onto its IK target without a jump
+		set.arm_rest = f <= tR ? mix(72, -56, ease((f - t0) / W)) : f <= tC ? -56 : mix(-56, 72, ease((f - tC) / REC));
+		keys.push({ f, set });
+	}
+	return { keys, end: tE + 1 };
+}
+
+/** flip({ kind: "back" | "front" | "cartwheel", travel, side, heading }) */
+export function flip(ctx) {
+	const kind = ctx.args.kind ?? "back";
+	if (!["back", "front", "cartwheel"].includes(kind)) skillError(ctx.tag, `kind must be "back", "front" or "cartwheel", got ${JSON.stringify(kind)}`);
+	const b = base(ctx);
+	return kind === "cartwheel" ? cartwheel(ctx, b) : tuck(ctx, b, kind);
+}

package/src/motion3/skills/impact.js

@@ -0,0 +1,109 @@
+// hitReaction: a body thrown by a hit (a car, a shove, a blow) and coming to rest on the floor, from the pose at f0.
+// Deterministic physics on the root: launched along the push at `speed` (m/s) and up (from the speed), it flies under gravity, lands
+// when the hips reach lying height, then slides to a stop on floor friction. The body turns to fall along the push
+// (on its back when pushed from the front, "land"), the trunk and head whip on a damped spring against the shove,
+// the arms flail and trail, the legs follow the hips (feet held off the floor) and the whole body lies still at the end.
+import { add, apply, ry, rx } from "../compiler/math.js";
+import { tiltFrame } from "../compiler/pose.js";
+import { personJoint } from "../people.js";
+import { skillError } from "./book.js";
+
+// LIE: the root's height lying on the back or face down, the trunk's skin just on the floor (X/Y Bot)
+const G = 9.81, FPS = 24, MU = 0.75, LIE = { back: 0.16, front: 0.11 }, TURN = 0.25, ONSET = 0.12, LIFT_OFF = 0.25;
+/** Distance covered by a speed that builds up over ONSET s (a hit pushes for about a tenth of a second, not one frame). */
+const ramp = t => t - ONSET * (1 - Math.exp(-t / ONSET));
+/** A foot held off the floor eases onto it (softplus over w m) instead of being cut at it. */
+const softFloor = (y, lie, w) => lie + w * Math.log1p(Math.exp((y - lie) / w));
+/** The landing: the fall stops over CUSHION s at one deceleration (spread over frames, not one), the trunk sinking SINK m
+ * into its own give past lying height, and springs back to it over SETTLE s. */
+const CUSHION = 3 / FPS, SINK = 0.03, SETTLE = 0.25;
+const smooth = x => { const t = Math.min(1, Math.max(0, x)); return t * t * t * (t * (6 * t - 15) + 10); };
+const wrap = d => ((d + 540) % 360) - 180;
+const r3 = v => v.map(x => Math.round(x * 1000) / 1000);
+const r1 = x => Math.round(x * 10) / 10;
+
+/** Where the earlier keys have a vec3 channel at frame f, read straight between the keys around it (state holds the last key). */
+function track(keys, ch, f) {
+	let a = null, b = null;
+	for (const k of keys) {
+		const v = k.set?.[ch];
+		if (!Array.isArray(v)) continue;
+		if (k.f <= f && (!a || k.f >= a.f)) a = { f: k.f, v };
+		if (k.f > f && (!b || k.f < b.f)) b = { f: k.f, v };
+	}
+	if (!a || !b) return a?.v;
+	const w = (f - a.f) / (b.f - a.f);
+	return a.v.map((x, i) => x + (b.v[i] - x) * w);
+}
+
+/** The push direction [x, z] (unit) from args.dir, or from args.from (object:<id> | person:<id>) toward the hips. */
+function pushOf(ctx, root) {
+	const { args, scene } = ctx;
+	let d = args.dir;
+	if (!d && typeof args.from === "string") {
+		const [kind, id] = args.from.split(/:(.*)/s);
+		const at = kind === "object" ? scene?.objects?.[id]?.pos : kind === "person" ? personJoint(scene, id, "Hips", ctx.f0) : null;
+		if (!at) skillError(ctx.tag, `args.from "${args.from}" must be object:<id> of a scene body or person:<id> of a character with an installed take`);
+		d = [root[0] - at[0], root[2] - at[2]];
+	}
+	if (!Array.isArray(d) || d.length !== 2 || !(Math.hypot(d[0], d[1]) > 1e-6)) skillError(ctx.tag, "needs args.dir: [x, z] (the way the body is thrown) or args.from: object:<id> | person:<id> (what hits it)");
+	const n = Math.hypot(d[0], d[1]);
+	return [d[0] / n, d[1] / n];
+}
+
+export function hitReaction(ctx) {
+	const { sk, args, state } = ctx, I = sk.index, P = sk.restWorldPos;
+	if (!state.root) skillError(ctx.tag, "needs a pose keyed before f0 (standIdle, a walk, ...)");
+	// the hit takes the body where the earlier motion has it at f0, a foot in the air going on at its speed
+	const root0 = track(ctx.keys, "root", ctx.f0) ?? state.root.slice(), from = {};
+	for (const k of ["l", "r"]) {
+		const at = track(ctx.keys, `foot_${k}`, ctx.f0), was = track(ctx.keys, `foot_${k}`, ctx.f0 - 1);
+		if (at) from[k] = { at, v: was ? at.map((x, i) => x - was[i]) : [0, 0, 0] };
+	}
+	const yaw0 = state.yaw ?? 0, [dx, dz] = pushOf(ctx, root0);
+	const speed = args.speed ?? 4;
+	if (!(Number.isFinite(speed) && speed > 0)) skillError(ctx.tag, `args.speed must be a launch speed above 0 m/s, got ${JSON.stringify(args.speed)}`);
+	const up = Math.min(2.5, Math.max(0.8, 0.3 * speed));
+	// pushed against the way it faces (a hit from the front) it lands on its back; "land" overrides
+	const facing = apply(ry(yaw0), [0, 0, 1]), back = (args.land ?? (dx * facing[0] + dz * facing[2] <= 0 ? "back" : "front")) === "back";
+	const head = Math.atan2(dx, dz) * 180 / Math.PI, yawT = back ? head + 180 : head, turn = wrap(yawT - yaw0), pitchT = back ? -90 : 90;
+	const lie = back ? LIE.back : LIE.front, y0 = root0[1], fall = t => y0 + up * ramp(t) - 0.5 * G * t * t, vel = t => up * (1 - Math.exp(-t / ONSET)) - G * t;
+	// the cushion starts at t1 where the fall, slowed evenly to rest over CUSHION, ends just at lying height
+	let lo = 0, hi = (up + Math.sqrt(up * up + 2 * G * Math.max(0, y0 - lie))) / G + 1;
+	for (let i = 0; i < 60; i++) { const m = (lo + hi) / 2; if (fall(m) + vel(m) * CUSHION / 2 > lie - SINK || vel(m) > 0) lo = m; else hi = m; }
+	const t1 = lo, v1 = Math.min(0, vel(t1)), y1 = fall(t1), T = t1 + CUSHION, tSlide = speed / (MU * G), tRest = T + tSlide;
+	const height = t => t < t1 ? fall(t) : t < T ? y1 + v1 * (t - t1) - v1 / (2 * CUSHION) * (t - t1) ** 2 : lie - SINK * (1 - smooth((t - T) / SETTLE));
+	const ankle = P[I.LeftFoot][1], hipsY = P[I.Hips][1], sign = back ? 1 : -1, LEG = 0.9 * Math.hypot(...[0, 1, 2].map(i => P[I.LeftFoot][i] - P[I.Hips][i]));
+	const end = ctx.f0 + Math.ceil((tRest + 0.6) * FPS), keys = [];
+	for (let f = ctx.f0; f <= end; f++) {
+		const t = (f - ctx.f0) / FPS, flying = t < T, ts = Math.min(Math.max(0, t - T), tSlide);
+		const run = flying ? speed * ramp(t) : speed * ramp(T) + speed * ts - 0.5 * MU * G * ts * ts;
+		const y = height(t);
+		const root = [root0[0] + dx * run, y, root0[2] + dz * run];
+		const tilt = Math.max(0.35, 0.9 * T), yaw = yaw0 + turn * smooth(t / Math.max(TURN, tilt)), pitch = pitchT * smooth(t / tilt), R = (v => apply(ry(yaw), apply(rx(pitch), v)));
+		// the trunk and head whip against the shove (a damped spring), the arms flail and trail, all settling by the rest
+		const ease = smooth(t / ONSET), whip = ease * Math.exp(-t / 0.18) * Math.sin(2 * Math.PI * t / 0.55), flail = smooth(t / 0.3) * Math.exp(-t / 0.45) * Math.sin(2 * Math.PI * t / 0.6);
+		const lying = smooth((t - T) / 0.3);
+		// legs bend in the air and lie out: on the back a little bent, knees up, toes up; face down straight, toes down
+		const legY = -(hipsY - ankle) + 0.06 * (1 - lying) + (back ? 0.03 : 0.01) * lying, off = smooth(t / LIFT_OFF);
+		// face down the feet ride a little off the floor while the body slides, so they are not taken for planted feet
+		const floor = ankle + 0.01 + (!back && !flying && ts < tSlide ? 0.04 : 0);
+		// on the back the heels stay below the hips (a soft cap), so the legs slope down to the feet and the knees bend up
+		const foot = (k, x, z) => { const p = add(root, R([x, legY, z])), cap = root[1] - 0.05; if (back) p[1] = cap - 0.05 * Math.log1p(Math.exp((cap - p[1]) / 0.05)); p[1] = softFloor(p[1], floor, 0.03); const o = from[k]; if (!o) return p; const q = o.at.map((x, i) => x + o.v[i] * (f - ctx.f0) * (1 - off)); q[1] = Math.max(o.at[1], q[1]); return reach(p.map((v, i) => q[i] + (v - q[i]) * off)); };
+		// a foot left behind is drawn in within the leg's reach of the hips (a soft cap, in as the foot lifts), so the leg is pulled, not torn
+		const reach = p => { const d = p.map((v, i) => v - root[i]), n = Math.hypot(...d), m = LEG - 0.02 * Math.log1p(Math.exp((LEG - n) / 0.02)); return n > 1e-9 ? root.map((v, i) => v + d[i] * (1 + (m / n - 1) * off)) : p; };
+		// the knee points along the body's forward pitched with it, square to the leg (no flip lying down); a pole is read
+		// in the yaw frame, tilted past 60 degrees of pitch (pose.js tiltFrame), so that tilt (lean) is taken back out of
+		// the knee poles (and half of it, face down, out of the foot pitch: the toes rest on the floor, not in it)
+		const tf = tiltFrame(0, pitch, 0), back0 = tf ? apply(tf.R, [0, 1, 0]) : [0, 1, 0], lean = Math.atan2(back0[2], back0[1]) * 180 / Math.PI;
+		const knee = apply(rx(-lean), [0, -Math.sin(pitch * Math.PI / 180), Math.max(0.05, Math.cos(pitch * Math.PI / 180))]);
+		const set = { root: r3(root), yaw: r1(yaw), pitch: r1(pitch), roll: 0,
+			foot_l: r3(foot("l", 0.11, 0.04 + 0.1 * flail * off - (back ? 0.1 : 0) * lying)), foot_r: r3(foot("r", -0.11, 0.04 - 0.1 * flail * off - (back ? 0.1 : 0) * lying)), fyaw_l: r1(yaw), fyaw_r: r1(yaw), fpitch_l: r1(back ? -50 * lying : -0.5 * lean), fpitch_r: r1(back ? -50 * lying : -0.5 * lean),
+			knee_l: r3([0.05, knee[1], knee[2]]), knee_r: r3([-0.05, knee[1], knee[2]]),
+			spine_pitch: r1(sign * 22 * whip * Math.min(1, speed / 4)), spine_yaw: 0, spine_roll: r1(10 * flail * (1 - lying)), head_pitch: r1(sign * 30 * whip * Math.min(1, speed / 4) + (back ? -8 : 8) * lying), head_roll: r1(12 * lying),
+			arm_rest: r1(72 - 22 * lying), aswing_l: r1(sign * 45 * flail + 8 * lying), aswing_r: r1(-sign * 35 * flail - 8 * lying), abend_l: r1(25 + 30 * flail * flail), abend_r: r1(30 + 25 * flail * flail) };
+		if (f === ctx.f0) Object.assign(set, { armw_l: 0, armw_r: 0, fingers_l: { relaxed: 1 }, fingers_r: { relaxed: 1 } });
+		keys.push({ f, set });
+	}
+	return { keys, end };
+}

package/src/motion3/skills/index.js

@@ -10,8 +10,10 @@ import { SKILL_INFO } from "./info.js";
 import { standIdle, walkTo, reachGrip } from "./basic.js";
 import { sitInSeat, exitCar } from "./car.js";
 import { smokeCigarette } from "./smoke.js";
+import { flip } from "./flip.js";
+import { hitReaction } from "./impact.js";
 
-const SKILLS = { standIdle, sitInSeat, exitCar, walkTo, reachGrip, smokeCigarette };
+const SKILLS = { standIdle, sitInSeat, exitCar, walkTo, reachGrip, smokeCigarette, flip, hitReaction };
 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);

package/src/motion3/skills/info.js

@@ -53,6 +53,16 @@ export const SKILL_INFO = {
 		adds: ["objects: door and handle hinges", "anchors handle, lthigh, rthigh", "props.grip", "fits, checks.contacts, checks.allow"],
 		example: { f0: 0, args: { car: "Car" } },
 	},
+	flip: {
+		args: { kind: { enum: ["back", "front", "cartwheel"], default: "back", description: "a standing back or front tuck, or a cartwheel" },
+			travel: num("back/front: m along the heading at landing (default back -0.25, front 0.4)"),
+			side: side("cartwheel: toward the character's l (default) or r"), heading: num("degrees (yaw); default the keyed yaw") },
+		needs: "a standing pose keyed before f0", frames: "back/front 58 (one turn, the hips 0.5 m up); cartwheel 68",
+		adds: ["keys every frame: back/front crouch, push-off, a ballistic tucked flight turning the whole body (pitch to -360 back, +360 front) and a landing that stands up",
+			"cartwheel: a side step, then the whole body rolls 360 like a wheel on the straddled legs and the arms overhead, the hands planted in turn",
+			"whole-body pitch and roll take full turns in any key (no range); past 60 deg the knee and elbow poles and the feet turn with the body"],
+		example: { f0: 10, args: { kind: "back" } },
+	},
 	smokeCigarette: {
 		args: { until: int("hold to this frame; default the last frame; under f0+264 the beats are paced to fit"),
 			kit: { type: "object", properties: { cig: str("the cigarette kit's rootId (object.createKit)"), lighter: str("the lighter kit's rootId"), exhale: str("the exhale kit's rootId (or an effect): it follows the mouth") },
@@ -62,4 +72,9 @@ export const SKILL_INFO = {
 			"checks contacts, orient, below, appear, mouthPoints"],
 		example: { f0: 0, args: {} },
 	},
+	hitReaction: {
+		args: { dir: xz("[x, z] the way the body is thrown"), from: str("or what hits it: object:<id> | person:<id> (thrown away from it)"),
+			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 } },
+	},
 };

package/src/qa-label.js

@@ -0,0 +1,25 @@
+// How a QA result reads to a person. QA records one issue per frame and groups them by kind and subject (qa/index.js),
+// so one goal missed on 321 frames is 321 issues but one problem: the user saw "QA 549" for two long groups. People read
+// problems (the groups); qa.total stays the frame-level count the agent, repair and search work with.
+import { ko } from "./locale.js";
+
+/** Problems in a QA result: its groups (qa.problems from runMotionQa; an older result counts its groups). A failed result
+ * with neither, or with no groups, falls back to its frame-level count, so it never reads as clean. */
+export function qaProblems(qa) {
+	const n = qa?.problems ?? (Array.isArray(qa?.groups) ? qa.groups.length : 0);
+	return n || (qa?.ok ? 0 : (qa?.total ?? 0));
+}
+
+/** "QA clean" | "2 problems" ("QA 통과" | "문제 2개"). */
+export function qaLabel(qa) {
+	const n = qaProblems(qa);
+	if (qa?.ok || !n) return ko("QA clean", "QA 통과");
+	return ko(`${n} problem${n === 1 ? "" : "s"}`, `문제 ${n}개`);
+}
+
+/** A receipt's QA phrase: "clean" | "2 problems (321 frame issues)". */
+export function qaSay(qa) {
+	if (qa?.ok) return "clean";
+	const n = qaProblems(qa), total = qa?.total ?? 0;
+	return `${n} problem${n === 1 ? "" : "s"} (${total} frame issue${total === 1 ? "" : "s"})`;
+}

package/src/studio-actions.js

@@ -112,6 +112,10 @@ export const STUDIO_ACTIONS = freezeStudioData([
 		description: "Lay a shot's dolly rail through points (world floor x/z metres, in travel order) and put the shot's camera on it, like drawing the rail in the Top-View: the camera runs the rail at an even speed over the whole shot (or its authored rail-follow range), so a push-in, pull-out, orbit, track or crane is one call with 2-6 points (a line, or an arc through a few points; the rail is a smooth curve through them). height is the lens height in metres, one number or crane marks [{ t: 0..1 along the rail, height }] (default the follow height, 1.6). aim is what the camera holds: up to 4 character or object ids (their middle, frame by frame: a character's chest, an object's middle) or a world point { x, y, z }; without an aim it follows the scene's first character. aimHeight puts a cast aim at that world height instead of the chest, e.g. 0.9 to hold a whole standing body, 1.6 for faces. focalMm is the shot's lens (default the scene lens). It replaces any rail the shot had and keeps any height, aim or lens you leave out (null clears aim and lens), and it removes the camera keys the rail covers. Answers the rail's length, speed, height, aim and lens; check the framing with verify_result { targets, checks: [\"framing\"], range: the shot's frames } and a contact sheet. Read rails with inspect_studio { scope: \"shot\" }." },
 	{ id: "shot.clearCameraRail", label: "Delete camera rail", kind: "mutation", undoDomain: "shot", input: input(shotId),
 		description: "Delete a shot's camera rail; the shot's camera goes back to following its subject at the current distance." },
+	{ id: "shot.setCameraMode", label: "Set shot camera mode", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, mode: { type: "string", enum: ["keys", "follow", "rail"] } }),
+		description: "Set how a shot's camera moves: keys plays the shot's camera keys (frame_shot frames them; one framing holds the whole shot), follow keeps the captured distance from the subject, rail rides the shot's rail (lay one first with shot.setCameraRail). Deleting a rail leaves follow; set keys to hold a framed camera instead." },
+	{ id: "shot.rename", label: "Rename shot", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, name: { type: "string", maxLength: 240 } }),
+		description: "Rename a shot: its label on the timeline and in shot lists." },
 	{ id: "object.attach", label: "Attach to character", kind: "mutation", undoDomain: "objects",
 		input: input({ objectId: idSchema, ...characterId }, { bone: { type: "string", enum: STUDIO_ATTACH_BONES } }),
 		description: "Make a scene object ride a character, like dropping it on the character's Hierarchy row: on one bone (a cup in the right hand: bone \"rightHand\") or, with bone omitted, on the character's animated root so it travels with the body. The object keeps its place on screen: its position, rotation and scale are rewritten into the new frame (local to that bone while attached), and it leaves any group. Needs the character's rig on stage." },

package/src/studio-agent-protocol.js

@@ -1,6 +1,6 @@
 // Shared by the browser and sidecar. No Node, React, renderer or provider imports.
 import { STUDIO_ELEMENTS, isSettableElement } from "./studio-elements.js";
-import { STUDIO_ERROR_CODES } from "./studio-error-codes.js";
+import { STUDIO_ERROR_CODES, refusalCode } from "./studio-error-codes.js";
 import { EFFECT_VALUE_SCHEMA } from "./effects/effect-record.js";
 import { wrongType, unknownField, missingField, arrayRefusal, duplicateItem, stringRefusal, enumRefusal, numberRefusal, unionRefusal } from "./studio-schema-errors.js";
 // Mirrors PREVIS_MODES (project.js) and POSTURES (scenes.js). Neither is imported:
@@ -30,7 +30,7 @@ export const STUDIO_TOOLS = Object.freeze(Object.keys(STUDIO_TOOL_LABELS));
  * object→objects, shot→shot, stage→stage. */
 export const STUDIO_PATCH_KINDS = Object.freeze(["character", "object", "shot", "stage"]);
 export const STUDIO_PATCH_DOMAINS = Object.freeze({ character: "cast", object: "objects", shot: "shot", stage: "stage" });
-export { STUDIO_ERROR_CODES };
+export { STUDIO_ERROR_CODES, refusalCode };
 export const STUDIO_VARIANTS = freezeStudioData({
 	selectionKinds: ["scene", "object", "character", "rig", "camera"], modes: ["scene", "pose", "camera", "motion"], shotModes: ["keys", "follow", "rail"],
 	framingSizes: ["extreme close-up", "close-up", "medium close-up", "medium shot", "medium-wide shot", "wide shot", "extreme wide shot"],
@@ -146,9 +146,9 @@ export function patchValueSchema(element) {
 	if (element.type === "color") return { ...text(32), pattern: "^#[0-9a-fA-F]{6}$" };
 	if (element.type === "image") return nullable(dataImage);
 	if (element.type === "vec3") {
-		const bounds = element.gizmo ?? element;
-		if (bounds.min && typeof bounds.min === "object" && bounds.max && typeof bounds.max === "object") {
-			return object({ x: number(bounds.min.x, bounds.max.x), y: number(bounds.min.y, bounds.max.y), z: number(bounds.min.z, bounds.max.z) });
+		const { min, max } = element; // the element's own range; a gizmo envelope only limits the UI drag
+		if (min && typeof min === "object" && max && typeof max === "object") {
+			return object({ x: number(min.x, max.x), y: number(min.y, max.y), z: number(min.z, max.z) });
 		}
 		return vec3;
 	}
@@ -160,10 +160,10 @@ export function patchValueSchema(element) {
  * derived from the same declaration table as `patchValueSchema` so the two
  * can never drift apart. */
 export function buildPatchDescriptors(elements) {
-	return elements.filter(isSettableElement).map(({ path, type, min, max, enum: enumValues, gizmo, note }) => ({
+	return elements.filter(isSettableElement).map(({ path, type, min, max, enum: enumValues, note }) => ({
 		path, type,
-		...(gizmo?.min !== undefined ? { min: { ...gizmo.min } } : min !== undefined ? { min: min && typeof min === "object" ? { ...min } : min } : {}),
-		...(gizmo?.max !== undefined ? { max: { ...gizmo.max } } : max !== undefined ? { max: max && typeof max === "object" ? { ...max } : max } : {}),
+		...(min !== undefined ? { min: min && typeof min === "object" ? { ...min } : min } : {}),
+		...(max !== undefined ? { max: max && typeof max === "object" ? { ...max } : max } : {}),
 		...(enumValues ? { enum: [...enumValues] } : {}),
 		...(note ? { note } : {}),
 	}));

package/src/studio-app-binding.js

@@ -12,7 +12,7 @@ import { buildStudioContext, physicsFingerprintInput, studioEntityCursor, valida
 import { createStudioCommandJournal, framingChecks, localTransformReadback, placementChecks, sampledFramingResult, studioObjectCatalogue } from "./studio-agent-commands.js";
 import { verifyInstalledTake } from "./studio-agent-motion.js"; import { objectRowBounds } from "./studio-entity-bounds.js"; import { exportFramingInto } from "./studio-export-framing.js";
 import { shotGeometryFacts } from "./studio-geometry-facts.js"; import { KIT_CATALOGUE } from "./kits/index.js";
-import { STUDIO_TOOL_FAMILIES, StudioProtocolError, validateReceipt, validateStudioCommand, validateStudioIdentity } from "./studio-agent-protocol.js";
+import { STUDIO_TOOL_FAMILIES, StudioProtocolError, validateReceipt, validateStudioCommand, validateStudioIdentity, refusalCode } from "./studio-agent-protocol.js";
 import { studioVisual, verifyLighting } from "./studio-motion-visual.js";
 import { withEffectState } from "./effects/state.js"; import { hdrEnvironmentCatalogue } from "./stage-hdr-library.js";
 
@@ -165,7 +165,7 @@ export function createStudioAppBinding(ports) {
 		// the first 120 characters the protocol carries.
 		const words = [...String(error?.message ?? "").trim()];
 		return validateReceipt({ ok: false, commandId: request.commandId, host: request.host ?? request.binding?.host,
-			code: error.code ?? "INVALID_ARGUMENT", phase, affectedIds: [], expectedTargets: [], currentTargets: [], mutated: false,
+			code: refusalCode(error), phase, affectedIds: [], expectedTargets: [], currentTargets: [], mutated: false,
 			preserved: { authoredState: "unchanged" }, recovery: { action: "inspect", retryAllowed: false },
 			...(words.length ? { message: words.length > 120 ? `${words.slice(0, 119).join("")}…` : words.join("") } : {}) });
 	}

package/src/studio-error-codes.js

@@ -4,5 +4,12 @@ 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",
+	"VERIFICATION_FAILED", "REPAIR_REGRESSED", "CANCELLED", "UNCERTAIN_APPLY", "UNDO_CONFLICT", "CONFIRMATION_REQUIRED", "TIMEOUT", "UNDO_EXPIRED", "INTERNAL_ERROR",
 ]);
+/**
+ * A refusal's code. A protocol error carries its own; a JavaScript runtime error (TypeError, ReferenceError, RangeError,
+ * SyntaxError) is a fault in the editor, never the caller's input, so it reads INTERNAL_ERROR; any other plain Error is
+ * the validation message of a command and stays INVALID_ARGUMENT.
+ */
+export const refusalCode = error => error?.code
+	?? (["TypeError", "ReferenceError", "RangeError", "SyntaxError"].includes(error?.name) ? "INTERNAL_ERROR" : "INVALID_ARGUMENT");