cozyclay 1.9.0 → 2.0.0

package/src/motion-trail.js

@@ -9,9 +9,23 @@
  * objects with cloned arrays and never touch the caller's take.
  */
 
-import { CSKEL27_JOINTS } from "./ardy/cskel27.js";
+import { CSKEL27_JOINTS, CSKEL27_PARENTS } from "./ardy/cskel27.js";
+import { motionJointPositions, motionJointPositionsAt } from "./ardy/playback.js";
+import { renderMotionEdit } from "./ardy/motion-edit.js";
+
+/** Metres per rig unit: Character scales the Mixamo centimetre rig by 0.01 * stature. */
+const RIG_UNIT_METRES = 0.01;
 
 const JOINTS = CSKEL27_JOINTS.length;
+const jointIndex = (name) => CSKEL27_JOINTS.indexOf(name);
+
+/** Limb trail track -> two-bone chain [root, mid, effector] its drag bends. */
+const LIMB_CHAINS = {
+	leftHand: ["LeftArm", "LeftForeArm", "LeftHand"],
+	rightHand: ["RightArm", "RightForeArm", "RightHand"],
+	leftFoot: ["LeftUpLeg", "LeftLeg", "LeftFoot"],
+	rightFoot: ["RightUpLeg", "RightLeg", "RightFoot"],
+};
 
 /**
  * The always-drawn trail tracks: root plus every IK chain endpoint and the
@@ -74,17 +88,42 @@ function toWorldXZ(basis, x, z) {
 	];
 }
 
+/** Rendered rig-space samples of one joint, or null when the rig drives no bone for it. */
+function renderedSamples(motion, joint, rig) {
+	if (!rig) return null;
+	const samples = motionJointPositions(rig, motion);
+	return samples && Number.isFinite(samples.positions[joint * 3]) ? samples : null;
+}
+
 /**
- * World-space polyline of one cskel27 joint's posed position across the take.
+ * World-space polyline of one cskel27 joint across the take.
  * Returns a flat [x0,y0,z0, x1,y1,z1, ...] array of length frames*3.
  * `baseY` is the character entry's stage height (roof scenes ride above 0).
+ * With `rig`, the points are where playback RENDERS that joint's bone on this
+ * rig (rig proportions, prep scale, bind offsets); without it, the clip's
+ * own posedJoints (the space pins and the wire use).
  */
-export function jointTrailPoints(motion, jointName = "Hips", { baseY = 0, scale = 1 } = {}) {
+export function jointTrailPoints(motion, jointName = "Hips", { baseY = 0, scale = 1, rig = null } = {}) {
 	if (!motion?.posedJoints || !(motion.frames > 0)) return null;
 	const joint = CSKEL27_JOINTS.indexOf(jointName);
 	if (joint < 0) return null;
 	const basis = anchorBasis(motion);
 	const out = new Float32Array(motion.frames * 3);
+	const rendered = renderedSamples(motion, joint, rig);
+	if (rendered) {
+		// The Character group: anchor position, clip yaw, 0.01 * stature scale.
+		// Rig space is already anchor-relative (applyMotionFrame rebases).
+		const unit = RIG_UNIT_METRES * scale;
+		for (let f = 0; f < motion.frames; f += 1) {
+			const po = (f * JOINTS + joint) * 3;
+			const x = rendered.positions[po] * unit;
+			const z = rendered.positions[po + 2] * unit;
+			out[f * 3] = basis.anchorX + x * basis.cos + z * basis.sin;
+			out[f * 3 + 1] = baseY + rendered.positions[po + 1] * unit;
+			out[f * 3 + 2] = basis.anchorZ - x * basis.sin + z * basis.cos;
+		}
+		return out;
+	}
 	for (let f = 0; f < motion.frames; f += 1) {
 		const po = (f * JOINTS + joint) * 3;
 		const [wx, wz] = toWorldXZ(basis, motion.posedJoints[po], motion.posedJoints[po + 2]);
@@ -152,6 +191,63 @@ export function worldDeltaToClip(motion, delta) {
 	};
 }
 
+/**
+ * World drag delta on a drawn (rendered) trail -> the clip delta
+ * applyTrailFalloffDelta takes, so the RENDERED effector follows the pointer.
+ *
+ * Playback turns the rig's own bones by the clip's rotations and adds rotated
+ * bind offsets, so a clip move is not a rendered move (the y-bot forearm is
+ * 27.6 cm against the clip's 23.3; the Mixamo head bone sits near the neck
+ * pivot). Rather than model that, keep the clip delta along the pointer (as
+ * before) and solve its LENGTH through real playback: the gain that brings
+ * the rendered effector closest to the pointer (least squares, so it never
+ * overshoots). A full 3D inverse was rejected: limb reach makes some
+ * directions unreachable and chasing them sends the clip delta far off.
+ * The gain is capped at 1.5: rig/clip limb ratios sit well inside it, and a
+ * bone that needs more (the Mixamo head bone rides ~11 cm from the neck
+ * pivot, 17 degrees per rendered cm) is a lever the edit cannot drive 1:1
+ * without spinning the part. Without a rig: yaw + stature only.
+ */
+export function worldDeltaToTrailClip(motion, delta, { track = "hips", grabFrame = 0, radiusFrames = 0, rig = null, scale = 1 } = {}) {
+	const stature = Number.isFinite(scale) && scale > 1e-9 ? scale : 1;
+	const plain = worldDeltaToClip(motion, { x: delta.x / stature, y: delta.y / stature, z: delta.z / stature });
+	const distance = Math.hypot(delta.x, delta.y, delta.z);
+	const joint = jointIndex(TRAIL_TRACKS.find((item) => item.id === track)?.joint ?? "");
+	const samples = rig && joint >= 0 && motion?.rotMats && distance > 1e-6 ? motionJointPositions(rig, motion) : null;
+	const frame = Math.max(0, Math.min((motion?.frames ?? 1) - 1, Math.round(grabFrame) || 0));
+	const base = samples?.positions.subarray((frame * JOINTS + joint) * 3, (frame * JOINTS + joint) * 3 + 3);
+	if (!base || !Number.isFinite(base[0])) return plain;
+	const basis = anchorBasis(motion);
+	const unit = RIG_UNIT_METRES * stature;
+	const target = [delta.x, delta.y, delta.z];
+	const scaled = (gain) => ({ x: plain.x * gain, y: plain.y * gain, z: plain.z * gain });
+	// Rendered world displacement of the effector at the grab for a gain.
+	const reached = (gain) => {
+		const edited = applyTrailFalloffDelta(motion, { track, grabFrame: frame, radiusFrames, clipDelta: scaled(gain) });
+		const p = motionJointPositionsAt(rig, edited, frame).subarray(joint * 3, joint * 3 + 3);
+		const x = (p[0] - base[0]) * unit;
+		const z = (p[2] - base[2]) * unit;
+		return [x * basis.cos + z * basis.sin, (p[1] - base[1]) * unit, -x * basis.sin + z * basis.cos];
+	};
+	const MIN_GAIN = 0.1;
+	const MAX_GAIN = 1.5;
+	// Locally reached ~ gain * v, so the best gain is gain * (D.r)/(r.r);
+	// iterate that (the reach limit bends the curve) and keep the closest.
+	let gain = 1;
+	let best = { gain: 1, miss: Infinity };
+	for (let i = 0; i < 4; i += 1) {
+		const r = reached(gain);
+		const miss = len(sub(target, r));
+		if (miss < best.miss) best = { gain, miss };
+		const rr = dot(r, r);
+		if (!(rr > 1e-12) || miss < 1e-4) break;
+		const next = Math.max(MIN_GAIN, Math.min(MAX_GAIN, (gain * dot(target, r)) / rr));
+		if (Math.abs(next - gain) < 1e-4) break;
+		gain = next;
+	}
+	return scaled(best.gain);
+}
+
 /** Smoothstep falloff: 1 at the grab frame, 0 at/beyond the radius. */
 export function falloffWeight(distanceFrames, radiusFrames) {
 	if (!(radiusFrames > 0)) return distanceFrames === 0 ? 1 : 0;
@@ -172,17 +268,278 @@ export function trailEditRange(frameCount, grabFrame, radiusFrames) {
 	};
 }
 
+/* --- small vector / row-major 3x3 helpers for the limb and head solves --- */
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+const scale3 = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const len = (a) => Math.hypot(a[0], a[1], a[2]);
+function unit(a) {
+	const l = len(a);
+	return l > 1e-9 ? scale3(a, 1 / l) : null;
+}
+function matMul(a, b) {
+	const out = new Array(9);
+	for (let r = 0; r < 3; r += 1) {
+		for (let c = 0; c < 3; c += 1) {
+			out[r * 3 + c] = a[r * 3] * b[c] + a[r * 3 + 1] * b[3 + c] + a[r * 3 + 2] * b[6 + c];
+		}
+	}
+	return out;
+}
+const matT = (m) => [m[0], m[3], m[6], m[1], m[4], m[7], m[2], m[5], m[8]];
+const matVec = (m, v) => [
+	m[0] * v[0] + m[1] * v[1] + m[2] * v[2],
+	m[3] * v[0] + m[4] * v[1] + m[5] * v[2],
+	m[6] * v[0] + m[7] * v[1] + m[8] * v[2],
+];
+/** Inverse of a row-major 3x3 (callers keep it well conditioned). */
+function inverse3(m) {
+	const [a, b, c, d, e, f, g, h, i] = m;
+	const A = e * i - f * h, B = f * g - d * i, C = d * h - e * g;
+	const det = a * A + b * B + c * C;
+	return [A, c * h - b * i, b * f - c * e, B, a * i - c * g, c * d - a * f, C, b * g - a * h, a * e - b * d].map((v) => v / det);
+}
+/** Shortest-arc rotation taking unit `a` onto unit `b` (Rodrigues). */
+function arcRotation(a, b) {
+	const c = dot(a, b);
+	if (c < -1 + 1e-9) {
+		const axis = unit(cross(a, Math.abs(a[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0]));
+		const [x, y, z] = axis;
+		return [2 * x * x - 1, 2 * x * y, 2 * x * z, 2 * x * y, 2 * y * y - 1, 2 * y * z, 2 * x * z, 2 * y * z, 2 * z * z - 1];
+	}
+	const [x, y, z] = cross(a, b);
+	const k = 1 / (1 + c);
+	return [
+		1 - k * (y * y + z * z), -z + k * x * y, y + k * x * z,
+		z + k * x * y, 1 - k * (x * x + z * z), -x + k * y * z,
+		-y + k * x * z, x + k * y * z, 1 - k * (x * x + y * y),
+	];
+}
+
+/** Joint `root` and everything below it in the cskel27 tree. */
+function subtreeOf(root) {
+	return CSKEL27_JOINTS.map((_, j) => j).filter((j) => {
+		for (let k = j; k !== null; k = CSKEL27_PARENTS[k]) if (k === root) return true;
+		return false;
+	});
+}
+
+/** Per-frame accessors over a take's flat posedJoints / rotMats (locals). */
+function frameAccess(posedJoints, rotMats, f) {
+	const globals = new Map();
+	const local = (j) => Array.from(rotMats.subarray((f * JOINTS + j) * 9, (f * JOINTS + j) * 9 + 9));
+	const global = (j) => {
+		if (!globals.has(j)) {
+			const parent = CSKEL27_PARENTS[j];
+			globals.set(j, parent === null ? local(j) : matMul(global(parent), local(j)));
+		}
+		return globals.get(j);
+	};
+	return {
+		pos: (j) => {
+			const po = (f * JOINTS + j) * 3;
+			return [posedJoints[po], posedJoints[po + 1], posedJoints[po + 2]];
+		},
+		setPos: (j, p) => posedJoints.set(p, (f * JOINTS + j) * 3),
+		global,
+		/** Write joint j's LOCAL rotation so its global becomes `g` (parent untouched). */
+		setGlobal: (j, g, parentGlobal = CSKEL27_PARENTS[j] === null ? null : global(CSKEL27_PARENTS[j])) => {
+			rotMats.set(parentGlobal ? matMul(matT(parentGlobal), g) : g, (f * JOINTS + j) * 9);
+		},
+	};
+}
+
+/** One bend-side guide from the source window, never from the dragged target. */
+function limbWindowNormal(motion, [a, b, c], startFrame, endFrame, grabFrame, radiusFrames) {
+	let sum = [0, 0, 0];
+	for (let f = startFrame; f < endFrame; f += 1) {
+		const access = frameAccess(motion.posedJoints, null, f);
+		const normal = cross(sub(access.pos(b), access.pos(a)), sub(access.pos(c), access.pos(a)));
+		// Area weighting gives nearly straight (ill-conditioned) frames no vote.
+		sum = add(sum, scale3(normal, falloffWeight(f - grabFrame, radiusFrames)));
+	}
+	return unit(sum);
+}
+
+/** Beyond reach, the bend plane turns at most this far from the source frame's plane. */
+const OVERREACH_PLANE_LIMIT = Math.PI / 6;
+/** Excess distance, as a fraction of reach, over which that limit eases in. */
+const OVERREACH_EASE = 0.25;
+
+/** Rotate unit `from` toward unit `to` by at most `radians`. */
+function limitNormal(from, to, radians) {
+	const angle = Math.acos(Math.max(-1, Math.min(1, dot(from, to))));
+	if (angle <= radians) return to;
+	const tangent = unit(sub(to, scale3(from, dot(from, to))));
+	return tangent ? add(scale3(from, Math.cos(radians)), scale3(tangent, Math.sin(radians))) : from;
+}
+
+/**
+ * Two-bone solve: follow a reachable target exactly, using one window guide.
+ * An unreachable target cannot be met anyway, so there the bend plane is
+ * held within OVERREACH_PLANE_LIMIT of its pre-drag plane, easing in from the
+ * reach boundary so crossing it does not pop.
+ */
+function bendLimbFrame(access, [a, b, c], descendants, offset, guide) {
+	const A = access.pos(a);
+	const B = access.pos(b);
+	const C = access.pos(c);
+	const l1 = len(sub(B, A));
+	const l2 = len(sub(C, B));
+	if (len(offset) < 1e-9) return;
+	const AB = sub(B, A);
+	const AC = sub(C, A);
+	const oldNormal = unit(cross(AB, AC));
+	let toTarget = sub(add(C, offset), A);
+	let dir = unit(toTarget) ?? unit(AC);
+	if (!dir) return;
+	const reference = guide ?? oldNormal ?? unit(cross(dir, Math.abs(dir[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0]));
+	let normal = unit(sub(reference, scale3(dir, dot(reference, dir))))
+		?? unit(cross(dir, Math.abs(dir[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0]));
+	const excess = (len(toTarget) - (l1 + l2)) / ((l1 + l2) * OVERREACH_EASE);
+	const turn = oldNormal ? Math.acos(Math.max(-1, Math.min(1, dot(oldNormal, normal)))) : 0;
+	if (excess > 0 && turn > OVERREACH_PLANE_LIMIT) {
+		const t = Math.min(1, excess);
+		const capped = limitNormal(oldNormal, normal, turn - (turn - OVERREACH_PLANE_LIMIT) * t * t * (3 - 2 * t));
+		// Aim the straightened limb at the target's projection into that plane.
+		const projected = sub(toTarget, scale3(capped, dot(toTarget, capped)));
+		if (unit(projected)) {
+			normal = capped;
+			toTarget = projected;
+			dir = unit(projected);
+		}
+	}
+	// Leave a sub-millimetre bend at full reach so its side stays defined.
+	const d = Math.min(l1 + l2 - 1e-6, Math.max(Math.abs(l1 - l2) + 1e-6, len(toTarget)));
+	if (!(d > 1e-9)) return;
+	const along = (l1 * l1 - l2 * l2 + d * d) / (2 * d);
+	const h = Math.sqrt(Math.max(0, l1 * l1 - along * along));
+	const pole = unit(cross(dir, normal));
+	const B2 = add(A, add(scale3(dir, along), scale3(pole, h)));
+	const C2 = add(A, scale3(dir, d));
+	const move = sub(C2, C);
+	for (const j of descendants) access.setPos(j, add(access.pos(j), move));
+	access.setPos(b, B2);
+	if (!access.rotMats) return;
+	// Transport each segment by its shortest arc, not by the bend frame:
+	// rotating the frame added axial twist even when the elbow hardly moved.
+	const swing = (from, to) => arcRotation(unit(from), unit(to));
+	const ga = matMul(swing(AB, sub(B2, A)), access.global(a));
+	const gb = matMul(swing(sub(C, B), sub(C2, B2)), access.global(b));
+	const gc = access.global(c);
+	access.setGlobal(a, ga);
+	access.setGlobal(b, gb, ga);
+	access.setGlobal(c, gc, gb);
+}
+
+/** Head drag for one frame: swing Neck->Head about the neck toward the target. */
+function swingHeadFrame(access, neck, head, subtree, offset) {
+	const N = access.pos(neck);
+	const H = access.pos(head);
+	const from = unit(sub(H, N));
+	const to = unit(sub(add(H, offset), N));
+	if (!from || !to) return;
+	const q = arcRotation(from, to);
+	for (const j of subtree) access.setPos(j, add(N, matVec(q, sub(access.pos(j), N))));
+	if (access.rotMats) access.setGlobal(neck, matMul(q, access.global(neck)));
+}
+
+/** Validate and own the small JSON recipe stored beside the source motion ID. */
+export function normalizeTrailEdits(value) {
+	if (value == null) return null;
+	const fail = () => { throw new TypeError("Invalid motion trail edit recipe"); };
+	if (value.version !== 1 || !Number.isInteger(value.frames) || value.frames < 1
+		|| !(value.fps > 0) || !Number.isFinite(value.fps)
+		|| !Array.isArray(value.edits) || value.edits.length > 4096) fail();
+	const edits = value.edits.map((edit) => {
+		if (!TRAIL_TRACKS.some(({ id }) => id === edit?.track)
+			|| !Number.isInteger(edit.grabFrame) || edit.grabFrame < 0 || edit.grabFrame >= value.frames
+			|| !Number.isInteger(edit.radiusFrames) || edit.radiusFrames < 0
+			|| !["x", "y", "z"].every((axis) => Number.isFinite(edit.clipDelta?.[axis]))) fail();
+		return { track: edit.track, grabFrame: edit.grabFrame, radiusFrames: edit.radiusFrames,
+			clipDelta: { x: edit.clipDelta.x, y: edit.clipDelta.y, z: edit.clipDelta.z } };
+	});
+	let segments = null;
+	if (value.segments != null) {
+		if (!Array.isArray(value.segments) || !value.segments.length || value.segments.length > 4096) fail();
+		segments = value.segments.map((segment) => {
+			if (typeof segment?.id !== "string" || !Number.isInteger(segment.sourceStart) || segment.sourceStart < 0
+				|| !Number.isInteger(segment.sourceEnd) || segment.sourceEnd < segment.sourceStart
+				|| !Number.isFinite(segment.speed) || segment.speed < 0.1 || segment.speed > 4) fail();
+			return { id: segment.id, sourceStart: segment.sourceStart, sourceEnd: segment.sourceEnd, speed: segment.speed };
+		});
+	}
+	return { version: 1, frames: value.frames, fps: value.fps, segments, edits };
+}
+
+function rememberTrailEdit(source, edited, edit) {
+	const previous = source.trailEdits;
+	return { ...edited, trailEdits: {
+		version: 1, frames: source.frames, fps: source.fps,
+		segments: previous?.segments ?? source.editSegments?.map((segment) => ({ ...segment })) ?? null,
+		edits: [...(previous?.edits ?? []), { ...edit, clipDelta: { ...edit.clipDelta } }],
+	} };
+}
+
+/** Rebuild the arrays AND the retarget reference after project/cache decoding. */
+export function restoreTrailEdits(motion, stored) {
+	const recipe = normalizeTrailEdits(stored);
+	if (!recipe) return motion;
+	if (recipe.segments?.some((segment) => segment.sourceEnd >= motion.frames)) {
+		throw new RangeError("Motion trail source segment exceeds the take");
+	}
+	let restored = recipe.segments ? renderMotionEdit(motion, recipe.segments) : motion;
+	if (restored.frames !== recipe.frames || restored.fps !== recipe.fps) {
+		throw new RangeError("Motion trail recipe does not match the take clock");
+	}
+	for (const edit of recipe.edits) restored = applyTrailFalloffDelta(restored, edit);
+	return restored;
+}
+
 /**
- * Deform a take by a clip-space delta centred on `grabFrame`: every frame in
- * the falloff window shifts by weight(f) * delta on rootPos AND posedJoints
- * (applyMotionFrame skins from posedJoints; rootPos feeds camera/subject
- * sampling — both must agree or the preview tears). Returns a new motion.
+ * Deform a take by a clip-space delta centred on `grabFrame`, weighted per
+ * frame by the smoothstep falloff. `track` is the dragged TRAIL_TRACKS id:
+ *   - "hips" (default): the whole body shifts by weight(f) * delta on rootPos
+ *     AND posedJoints (applyMotionFrame skins from posedJoints; rootPos feeds
+ *     camera/subject sampling — both must agree or the preview tears).
+ *   - a hand/foot: only that limb bends (bendLimbFrame).
+ *   - "head": only the head swings about the neck (swingHeadFrame).
+ * Limb and head edits rewrite rotMats too, since playback reads rotations.
+ * Returns a new motion; the caller's arrays are never written.
  */
-export function applyTrailFalloffDelta(motion, { grabFrame, radiusFrames, clipDelta }) {
+export function applyTrailFalloffDelta(motion, { track = "hips", grabFrame, radiusFrames, clipDelta }) {
 	if (!motion?.posedJoints || !motion?.rootPos || !(motion.frames > 0)) return motion;
 	const { startFrame, endFrame } = trailEditRange(motion.frames, grabFrame, radiusFrames);
 	const rootPos = motion.rootPos.slice();
 	const posedJoints = motion.posedJoints.slice();
+	const chain = LIMB_CHAINS[track]?.map(jointIndex);
+	if (chain || track === "head") {
+		const rotMats = motion.rotMats ? motion.rotMats.slice() : null;
+		const neck = jointIndex("Neck");
+		const head = jointIndex("Head");
+		const moved = subtreeOf(chain ? chain[2] : head).filter((j) => !chain || j !== chain[2]);
+		const guide = chain ? limbWindowNormal(motion, chain, startFrame, endFrame, grabFrame, radiusFrames) : null;
+		for (let f = startFrame; f < endFrame; f += 1) {
+			const w = falloffWeight(f - grabFrame, radiusFrames);
+			if (w <= 0) continue;
+			const access = { ...frameAccess(posedJoints, rotMats, f), rotMats };
+			const offset = [clipDelta.x * w, clipDelta.y * w, clipDelta.z * w];
+			if (chain) bendLimbFrame(access, chain, [chain[2], ...moved], offset, guide);
+			else swingHeadFrame(access, neck, head, moved, offset);
+		}
+		const edited = rotMats ? { ...motion, rootPos, posedJoints, rotMats } : { ...motion, rootPos, posedJoints };
+		if (chain && rotMats) {
+			// One immutable reference, not a chain of preview/drag snapshots.
+			edited.trailRetarget = {
+				base: motion.trailRetarget?.base ?? motion,
+				chains: [...new Set([...(motion.trailRetarget?.chains ?? []), track])],
+			};
+		}
+		return rememberTrailEdit(motion, edited, { track, grabFrame, radiusFrames, clipDelta });
+	}
 	for (let f = startFrame; f < endFrame; f += 1) {
 		const w = falloffWeight(f - grabFrame, radiusFrames);
 		if (w <= 0) continue;
@@ -199,7 +556,7 @@ export function applyTrailFalloffDelta(motion, { grabFrame, radiusFrames, clipDe
 			posedJoints[po + 2] += dz;
 		}
 	}
-	return { ...motion, rootPos, posedJoints };
+	return rememberTrailEdit(motion, { ...motion, rootPos, posedJoints }, { track, grabFrame, radiusFrames, clipDelta });
 }
 
 /**

package/src/object-gizmo.jsx

@@ -461,7 +461,13 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 		 * Escape-clears-selection handler; with no drag open it returns without
 		 * touching the event, so App still gets its deselect (§7). */
 		const onKeyDown = (event) => {
-			if ((event.code !== "Escape" && event.key !== "Escape") || !dragRef.current) return;
+			if (!dragRef.current) return;
+			// Settle before App chooses between owned and native undo histories.
+			if ((event.ctrlKey || event.metaKey) && (event.code === "KeyZ" || event.code === "KeyY")) {
+				endDrag(true);
+				return;
+			}
+			if (event.code !== "Escape" && event.key !== "Escape") return;
 			endDrag(false);
 			event.preventDefault();
 			event.stopPropagation();

package/src/otio.js

@@ -1,6 +1,7 @@
 // OpenTimelineIO cut-list export. OTIO is JSON, so this module deliberately
 // has no OTIO dependency: the schema names below are the wire contract.
 
+import { isEffectivelyHidden } from "./scene-objects.js";
 import { sampleAt } from "./sample-at.js";
 import { TIMELINE_FRAME_FPS } from "./scenes.js";
 import { usedSensorHeightMm } from "./shot.js";
@@ -71,7 +72,7 @@ function blockingAt(scene, frame) {
 		...(Array.isArray(characters) ? characters : [])
 			.filter((character) => character && character.hidden !== true)
 			.map((character, index) => characterBlocking(scene, character, index, frame)),
-		...objects.filter(Boolean).map(objectBlocking),
+		...objects.filter((object) => object && !isEffectivelyHidden(object, objects, Array.isArray(characters) ? characters : [])).map(objectBlocking),
 	];
 }
 

package/src/panels/CameraPanel.jsx

@@ -0,0 +1,60 @@
+import Foldout from "./Foldout.jsx";
+import { ko, isKo } from "../locale.js";
+import { Field } from "../ui.jsx";
+import { VIDEO_MODEL_PRESETS } from "../model-presets.js";
+import { useBus } from "../app-context.js";
+
+export default function CameraPanel({ isCameraSelection, shot, moveSequence, cameraKeys, activeShot }) {
+	const { run } = useBus();
+	return (
+<Foldout hidden={!isCameraSelection} title={ko("Camera", "카메라")}>
+						<div className="readout v2-details-readout">
+						<span title={ko("camera to subject", "카메라와 피사체 거리")}>{shot.distance.toFixed(2)} m</span>
+						<span title={ko("nearest prime on the cropped filmback", "크롭된 필름백 기준 가장 가까운 단렌즈")}>{shot.focalMm} mm</span>
+						<span title={ko("angle relative to the subject's eyes", "피사체 눈높이 기준 각도")}>{shot.elevationDeg.toFixed(0)}°</span>
+						</div>
+						<h3 className="move-head v2-details-subsection-title">{ko("Move keys", "움직임 키")}</h3>
+						{moveSequence ? (
+							<div className="move-slate v2-details-value-box" title={ko("derived from the keyframings, not chosen from a list", "목록에서 고른 값이 아니라 키프레임에서 계산된 움직임입니다")}>
+								{moveSequence.displaySlate} · {moveSequence.spanS}{ko("s", "초")}
+							</div>
+						) : (
+							<div className="move-slate v2-details-value-box">
+								{cameraKeys.length === 1
+									? (isKo ? `프레임 ${cameraKeys[0].frame}부터 고정 샷 — 샷 블록 아래 빈 줄을 클릭해 움직임을 추가하세요` : `locked-off hold from frame ${cameraKeys[0].frame} — click the empty lower strip in a Shot block to add a move`)
+									: ko("click a Shot block's lower strip to key the current framing at that frame", "샷 블록 아래 빈 줄을 클릭하면 해당 프레임에 현재 프레이밍을 저장합니다")}
+							</div>
+						)}
+
+						<h3 className="move-head v2-details-subsection-title">{ko("Follow cam", "팔로우 카메라")}</h3>
+						<p className="camera-editor-pointer">
+							{activeShot
+								? ko(`Editing ${activeShot.name} in the timeline camera bar below.`, `아래 타임라인 카메라 바에서 ${activeShot.name}을 편집합니다.`)
+								: ko("Select a Shot block below to edit its camera.", "아래에서 샷 블록을 선택하면 카메라를 편집할 수 있습니다.")}
+						</p>
+
+						{/* Which generator this cut is being made FOR. Nothing here
+						    re-times or re-crops the shot — the timeline simply warns
+						    when the cut runs past the target's clip length or leaves
+						    its delivery aspects. */}
+						<h3 className="move-head v2-details-subsection-title">{ko("Target model", "타깃 모델")}</h3>
+						<p className="inspector-hint v2-details-hint">
+							{ko("The timeline flags this shot when the cut runs past the model's clip length or leaves its delivery ratios. Nothing is re-timed or re-cropped.", "컷 길이나 화면 비율이 모델 한계를 벗어나면 타임라인이 표시해줘요. 자동으로 재조정하지는 않습니다.")}
+						</p>
+						<Field label={ko("Cut for", "맞출 모델")}>
+							<select
+								data-shot-target-model
+								aria-label={ko("Target video model", "타깃 영상 모델")}
+								disabled={!activeShot}
+								value={activeShot?.targetModel ?? ""}
+								onChange={(event) => run('shot.set', { id: activeShot.id, set: { targetModel: event.target.value || null } })}
+							>
+								<option value="">{ko("None", "없음")}</option>
+								{VIDEO_MODEL_PRESETS.map((entry) => (
+									<option key={entry.id} value={entry.id}>{entry.name}</option>
+								))}
+							</select>
+						</Field>
+					</Foldout>
+	);
+}

package/src/panels/CharacterTransformPanel.jsx

@@ -0,0 +1,48 @@
+import Foldout from "./Foldout.jsx";
+import { ko } from "../locale.js";
+import { Vector3Row, Slider } from "../ui.jsx";
+import { useCastTransaction } from '../domains/cast.js';
+
+export default function CharacterTransformPanel({ workflowMode, isCharacterSelection, activeChar }) {
+	const { run, begin, commit } = useCastTransaction();
+	return (
+<Foldout
+					key={workflowMode === "motion" ? "placement" : "transform"}
+					hidden={!isCharacterSelection}
+					defaultOpen={workflowMode === "motion"}
+					title={workflowMode === "motion" ? ko("Placement", "배치") : ko("Transform", "변환")}
+				>
+					{workflowMode === "motion" ? (
+						<div className="placement-fields v2-details-panel">
+							<p className="inspector-hint">
+								{ko("Stage position — does not change the take", "무대 위치 — 테이크는 바꾸지 않습니다")}
+							</p>
+							<Vector3Row
+								label={ko("Position", "위치")}
+								fields={[
+									{ axis: "X", value: activeChar.x, step: 0.05, precision: 2, scrubRange: 5, onChange: (x) => run('character.update', { characterId: activeChar.id, patch: { x } }), onScrubStart: begin, onScrubEnd: commit },
+									{ axis: "Z", value: activeChar.z, step: 0.05, precision: 2, scrubRange: 5, onChange: (z) => run('character.update', { characterId: activeChar.id, patch: { z } }), onScrubStart: begin, onScrubEnd: commit },
+								]}
+							/>
+							<Slider compact label={ko("Rotation", "회전")} min={-180} max={180} step={1} value={activeChar.rot ?? 0} unit="°" onChange={(rot) => run('character.update', { characterId: activeChar.id, patch: { rot } })} />
+						</div>
+					) : (
+						<>
+							<p className="inspector-hint">
+								{ko("Edit the selected subject's placement, turn and size. Drag the Transform tool in the viewport for direct manipulation.", "선택한 인물의 위치·회전·크기를 편집합니다. 뷰포트의 변환 도구를 드래그해 바로 조작할 수도 있어요.")}
+							</p>
+							<Vector3Row
+								label={ko("Position", "위치")}
+								fields={[
+									{ axis: "X", value: activeChar.x, step: 0.05, precision: 2, scrubRange: 5, onChange: (x) => run('character.update', { characterId: activeChar.id, patch: { x } }), onScrubStart: begin, onScrubEnd: commit },
+									{ axis: "Y", value: activeChar.y ?? 0, step: 0.05, precision: 2, scrubRange: 5, onChange: (y) => run('character.update', { characterId: activeChar.id, patch: { y } }), onScrubStart: begin, onScrubEnd: commit },
+									{ axis: "Z", value: activeChar.z, step: 0.05, precision: 2, scrubRange: 5, onChange: (z) => run('character.update', { characterId: activeChar.id, patch: { z } }), onScrubStart: begin, onScrubEnd: commit },
+								]}
+							/>
+							<Slider compact label={ko("Rotation", "회전")} min={-180} max={180} step={1} value={activeChar.rot ?? 0} unit="°" onChange={(rot) => run('character.update', { characterId: activeChar.id, patch: { rot } })} />
+							<Slider compact label={ko("Scale", "크기")} min={0.2} max={3} step={0.05} value={activeChar.scale ?? 1} unit="×" onChange={(scale) => run('character.update', { characterId: activeChar.id, patch: { scale } })} />
+						</>
+					)}
+				</Foldout>
+	);
+}

package/src/panels/EnvironmentPanel.jsx

@@ -0,0 +1,40 @@
+import { ko } from "../locale.js";
+import { useStageTransaction } from "../domains/stage.js";
+import Foldout from "./Foldout.jsx";
+import { Field } from "../ui.jsx";
+import ReferenceImageField from "./ReferenceImageField.jsx";
+
+export default function EnvironmentPanel(props) {
+	const { run, begin, commit } = useStageTransaction();
+	return (
+<Foldout hidden={props.selectedHierarchyId !== "environment"} title={ko("Environment", "환경")}>
+						<label className="check details-toggle-row">
+							<span>{ko("I have an environment sheet", "환경 시트가 있어요")}</span>
+							<input type="checkbox" checked={props.hasEnvSheet} onChange={(event) => run("stage.setEnvironment", { hasEnvSheet: event.target.checked })} />
+						</label>
+						{!props.hasEnvSheet && (
+						<Field label={ko("Environment description", "환경 설명")}>
+								<input type="text" value={props.environment} onChange={(event) => run("run.update", { txId: begin("stage.setEnvironment"), args: { environment: event.target.value } })} onBlur={commit} />
+							</Field>
+						)}
+					<Field label={ko("Look / style", "룩 / 스타일")}>
+							<input type="text" value={props.style} onChange={(event) => run("run.update", { txId: begin("stage.setStyle"), args: { style: event.target.value } })} onBlur={commit} />
+						</Field>
+						<ReferenceImageField
+							label={ko("Environment reference", "환경 참고 이미지")}
+							hint={ko(
+								"A picture of this location. It travels with every framing capture so a render takes its materials, palette and lighting from the real place.",
+								"이 장소의 사진입니다. 모든 프레이밍 캐프처에 함께 실려 재질·색감·조명을 실제 장소에서 가져옵니다.",
+							)}
+							value={props.environmentImage}
+							alt={ko("Environment reference", "환경 참고 이미지")}
+							inputProps={{ "data-environment-image-input": "" }}
+							onPick={(dataUrl) => {
+								run("stage.setEnvironment", { environmentImage: dataUrl });
+								props.setToast(ko("Environment reference set", "환경 참고 이미지를 설정했어요"));
+							}}
+							onClear={() => run("stage.setEnvironment", { environmentImage: null })}
+						/>
+					</Foldout>
+	);
+}

package/src/panels/Foldout.jsx

@@ -0,0 +1,32 @@
+import { useState, useRef, useEffect } from "react";
+import "./details.css";
+
+export default function Foldout({ title, hidden, defaultOpen = true, openSignal = 0, children }) {
+	const [open, setOpen] = useState(defaultOpen);
+	const cardRef = useRef(null);
+	// A collapsed panel must still be reachable from elsewhere: selecting a
+	// prompt block on the timeline has to reveal the panel that edits it, or
+	// the click looks like it did nothing. Opening alone is not enough — the
+	// panel can sit below the fold of a long Inspector — so it is scrolled into
+	// view as well. The signal only ever opens; it never closes a panel.
+	useEffect(() => {
+		if (openSignal <= 0) return undefined;
+		setOpen(true);
+		// One frame later: the body has to exist before it can be scrolled to.
+		const raf = requestAnimationFrame(() => {
+			cardRef.current?.scrollIntoView({ block: "nearest" });
+		});
+		return () => cancelAnimationFrame(raf);
+	}, [openSignal]);
+	return (
+		<section ref={cardRef} className={"card foldout v2-details-section" + (open ? " open" : "")} hidden={hidden}>
+			<h3>
+				<button type="button" className="foldout-head v2-details-foldout-head" aria-expanded={open} onClick={() => setOpen((v) => !v)}>
+					<span className="foldout-arrow v2-details-foldout-arrow" data-open={open ? "true" : "false"} aria-hidden="true" />
+					<span className="foldout-title v2-details-foldout-title">{title}</span>
+				</button>
+			</h3>
+			{open && <div className="foldout-body v2-details-foldout-body">{children}</div>}
+		</section>
+	);
+}