cozyclay 2.1.0 → 3.0.0

package/src/effects/state.js

@@ -0,0 +1,59 @@
+/**
+ * What the agent can measure about an effect: `effectStateAt(objectId, frame)`
+ * answers { frame, alive, emitter: [x,y,z], bounds: { min, max } | null } in
+ * metres, rounded to the millimetre, plus `clamped` when the scene-wide
+ * particle cap thinned this emitter.
+ *
+ * The answer is computed, not read back from the GPU, by the same simulation
+ * call the renderer draws with. EffectsLayer publishes the take it draws
+ * against; the records come from the caller when it has fresher ones.
+ */
+import { isEffectivelyHidden } from "../object-hidden.js";
+import { evaluateEffects } from "./simulate.js";
+import { EFFECT_KIND } from "./effect-record.js";
+
+let readLive = () => null;
+
+/** The renderer's current { take, live } (a reader, so it is always the last render's). */
+export function publishEffectScene(read) {
+	readLive = typeof read === "function" ? read : () => null;
+}
+
+/** The simulation scene for a list of AUTHORED records: effect records, lookup and the authored-hidden set. */
+export function effectSceneOf(objects) {
+	const records = objects.filter((object) => object?.renderer === EFFECT_KIND);
+	return { records, lookup: new Map(objects.map((object) => [object.id, object])),
+		hidden: new Set(records.filter((record) => isEffectivelyHidden(record, objects, [])).map((record) => record.id)) };
+}
+
+const mm = (value) => {
+	const rounded = Math.round(value * 1000) / 1000;
+	return rounded === 0 ? 0 : rounded;
+};
+
+/** The effect state for one emitter in `scene` (see the module note), or null when it is no effect. */
+export function effectStateIn(scene, objectId, frame) {
+	const records = scene?.records ?? [];
+	if (!records.some((record) => record.id === objectId)) return null;
+	const at = Math.max(0, Math.round(Number(frame) || 0));
+	const st = evaluateEffects(records, scene, at, { only: objectId }).get(objectId);
+	return {
+		frame: at, alive: st.alive, emitter: st.emitter.map(mm),
+		bounds: st.alive ? { min: st.min.map(mm), max: st.max.map(mm) } : null,
+		...(st.clamped ? { clamped: st.clamped } : {}),
+	};
+}
+
+/** `objects` (authored records) default to the ones the renderer last drew. */
+export function effectStateAt(objectId, frame, objects = null) {
+	const live = readLive() ?? {};
+	const scene = objects ? { ...effectSceneOf(objects), take: live.take ?? {}, live: live.live ?? null } : live;
+	return effectStateIn(scene, objectId, frame);
+}
+
+/** An inspect_studio entity row with `effect` (the state at `frame`) added for an effect record. */
+export function withEffectState(row, frame, objects) {
+	if (row?.renderer !== EFFECT_KIND) return row;
+	const effect = effectStateAt(row.id, frame, objects);
+	return effect ? { ...row, effect } : row;
+}

package/src/execution-telemetry.js

@@ -42,11 +42,10 @@ function executionFailureCode(error, channel, fallbackCode = "unknown") {
 }
 
 export function mcpToolCategory(name) {
-	if (name === "generate_motion") return "motion_generate";
-	if (name === "load_motion") return "motion_apply";
+	
 	if (name === "capture_frame") return "frame_capture";
 	if (name === "set_camera" || name === "frame_shot" || name === "mark_camera_move" || name === "describe_camera_move") return "camera";
-	if (name === "set_prompt_blocks") return "prompt_authoring";
+	
 	if (name === "save_project" || name === "open_project") return "project_io";
 	if (name === "describe_scene" || name === "describe_shot" || name === "render_prompt" || name === "live_status" || name === "compare_sculpt") return "read";
 	if (name === "add_character" || name === "place_character" || name === "remove_character" || name === "focus_character" || name === "place_object" || name === "import_mesh" || name === "sculpt_object" || name === "group_objects" || name === "update_object" || name === "remove_object" || name === "apply_batch" || name === "add_scene" || name === "switch_scene") return "scene_write";

package/src/first-success-guide.jsx

@@ -15,10 +15,10 @@ const ANIMATION_STEPS = [
 		hintKo: "바닥의 캐릭터 마커를 드래그해 배치하세요.",
 	},
 	{
-		en: "Press K to set a key at the current frame.",
-		ko: "현재 프레임에서 K를 눌러 키를 설정하세요.",
-		hintEn: "The key appears on the timeline as your first pose checkpoint.",
-		hintKo: "첫 포즈 체크포인트가 타임라인에 표시됩니다.",
+		en: "Ask the Agent for a motion.",
+		ko: "에이전트에게 동작을 요청하세요.",
+		hintEn: "Open it with Cmd/Ctrl+B and say what the character does; the take lands on the Body lane.",
+		hintKo: "Cmd/Ctrl+B로 열고 캐릭터가 할 동작을 말하면 테이크가 바디 레인에 올라갑니다.",
 	},
 	{
 		en: "Scrub the timeline or press Space to play.",
@@ -81,7 +81,7 @@ export default function FirstSuccessGuide({ open, onDismiss, previsMode = "anima
 				<div className="v2-first-success-guide-complete first-success-guide-complete" id="first-success-guide-description" role="status">
 					<div className="v2-first-success-guide-check first-success-guide-check">✓</div>
 					<strong>{storyboard ? ko("You made your first panel.", "첫 패널을 만들었어요.") : ko("You made your first shot.", "첫 샷을 만들었어요.")}</strong>
-					<p>{storyboard ? ko("Describe, review on the Board, then stylize or export. You can close this guide and keep adding panels.", "설명하고, 보드에서 확인한 뒤 스타일을 입히거나 내보내세요. 가이드를 닫고 패널을 계속 추가하세요.") : ko("Select, move, key, and play are the core CozyClay loop. You can close this guide and keep blocking.", "선택하고, 움직이고, 키를 찍고, 재생하는 것이 CozyClay의 핵심 흐름입니다. 가이드를 닫고 계속 블로킹하세요.")}</p>
+					<p>{storyboard ? ko("Describe, review on the Board, then stylize or export. You can close this guide and keep adding panels.", "설명하고, 보드에서 확인한 뒤 스타일을 입히거나 내보내세요. 가이드를 닫고 패널을 계속 추가하세요.") : ko("Select, move, ask, and play are the core CozyClay loop. You can close this guide and keep blocking.", "선택하고, 움직이고, 요청하고, 재생하는 것이 CozyClay의 핵심 흐름입니다. 가이드를 닫고 계속 블로킹하세요.")}</p>
 					<button type="button" className="v2-first-success-guide-next first-success-guide-next btn primary" onClick={onDismiss}>{ko("Continue editing", "편집 계속하기")}</button>
 				</div>
 			) : (

package/src/ghost-set.js

@@ -0,0 +1,257 @@
+// The onion-skin ghosts as three.js objects (view-ghosts.js chooses the frames and the look). A
+// ghost is a slot: one clone of the live rig, posed from the take (playback.js) only when its
+// frame changes, plus copies of the meshes of the records that take carries (a kit's parts),
+// placed where the take has them at that frame (object-travel.js). Clones share the live
+// geometry; each slot owns one material. Every node sits on one layer (GIZMO_LAYER in the
+// viewport, so no capture renders it) and takes no ray, so a ghost never wins a pick. Each mesh
+// has a depth-only twin drawn just before it, so a ghost shows only its front surface: one
+// translucent silhouette, not a stack of overlapping shells.
+import * as THREE from "three";
+import { clone as cloneSkeleton } from "three/examples/jsm/utils/SkeletonUtils.js";
+import { applyTakeFrame } from "./motion3/playback.js";
+import { sceneObjectTravelMatrixAt, trackShown } from "./object-travel.js";
+import { ghostFrames, ghostLook, sheetGhostSettings, takeKeyFrames } from "./view-ghosts.js";
+
+const noRay = () => {};
+// Ghosts draw after the other see-through things, nearest in time first: a ghost behind a nearer
+// one (in depth) hides there, one in front of it tints it.
+const GHOST_ORDER = 40;
+
+function claim(node, layer) {
+	node.layers.set(layer);
+	node.raycast = noRay;
+	node.castShadow = false;
+	node.receiveShadow = false;
+}
+
+/** The depth-only twin of a ghost mesh, a child at its place (a skinned one bound to the same skeleton). */
+function addDepthTwin(mesh, material) {
+	const twin = mesh.isSkinnedMesh ? new THREE.SkinnedMesh(mesh.geometry, material) : new THREE.Mesh(mesh.geometry, material);
+	if (mesh.isSkinnedMesh) { twin.bindMode = mesh.bindMode; twin.bind(mesh.skeleton, mesh.bindMatrix); }
+	twin.userData.depthTwin = true;
+	twin.frustumCulled = false;
+	mesh.add(twin);
+	return twin;
+}
+
+/** A copy of a rig whose bind-pose map points at the copy's bones (Object3D.copy JSON-clones userData, losing the Map). */
+function cloneRig(rig) {
+	const copy = cloneSkeleton(rig), originals = [], copies = [];
+	rig.traverse((node) => originals.push(node));
+	copy.traverse((node) => copies.push(node));
+	const binds = rig.userData?.poseBind;
+	copy.userData = binds instanceof Map ? { poseBind: new Map(originals.flatMap((node, i) => (binds.has(node) ? [[copies[i], binds.get(node)]] : []))) } : {};
+	return copy;
+}
+
+/** Ids of the records a character's take moves (its spec.objects that travel) and everything grouped under them. */
+export function rideIds(objects = [], take) {
+	const moved = new Set(Object.entries(take?.objects ?? {}).filter(([, track]) => track?.pos).map(([id]) => id));
+	if (!moved.size) return [];
+	const byId = new Map(objects.map((o) => [o.id, o]));
+	const rides = (o, seen = new Set()) => !!o && !seen.has(o.id) && (moved.has(o.id) || rides(byId.get(o.parent), seen.add(o.id)));
+	return objects.filter((o) => !o.hidden && rides(o)).map((o) => o.id);
+}
+
+/** The take's own object tracks as object-travel.js reads them (objectTracksOf for one character). */
+export const takeTracks = (take) => new Map(Object.entries(take?.objects ?? {}).map(([id, track]) => [id, { frameCount: take.frameCount, ...track }]));
+
+/**
+ * What a record draws, from its mounted group (props.jsx tags it userData.sceneObjectId): every
+ * visible mesh on layer 0 (no editor markers, halos or particles), with its matrix relative to
+ * the record's own frame. Records not mounted yet are left out.
+ */
+export function propSources(scene, ids) {
+	const wanted = new Set(ids), sources = [];
+	if (!wanted.size) return sources;
+	scene.traverse((group) => {
+		const id = group.userData?.sceneObjectId;
+		if (!wanted.has(id) || group.userData.ghost) return;
+		group.updateWorldMatrix(true, true);
+		const inverse = group.matrixWorld.clone().invert(), meshes = [];
+		const walk = (node) => {
+			if (!node.visible || node.userData?.beautyOnly) return;
+			if (node.isMesh && !node.isInstancedMesh && node.layers.isEnabled(0) && node.geometry?.attributes?.position) {
+				meshes.push({ geometry: node.geometry, matrix: inverse.clone().multiply(node.matrixWorld) });
+			}
+			for (const child of node.children) if (!child.userData?.sceneObjectId) walk(child);
+		};
+		for (const child of group.children) walk(child);
+		if (meshes.length) sources.push({ id, meshes });
+	});
+	return sources;
+}
+
+const material = () => new THREE.MeshMatcapMaterial({ transparent: true, depthWrite: false, toneMapped: false, fog: false });
+// Pushed back a hair so the colour pass of the same surface passes the depth test.
+const depthOnly = () => new THREE.MeshBasicMaterial({ colorWrite: false, transparent: true, polygonOffset: true, polygonOffsetFactor: 1, polygonOffsetUnits: 1 });
+
+export class GhostSet {
+	constructor({ layer }) {
+		this.layer = layer;
+		this.object = new THREE.Group();
+		this.object.name = "ghosts";
+		this.object.userData.ghost = true;
+		// The body ghosts ride the character's placement; the props are already in world space.
+		this.body = new THREE.Group();
+		this.body.matrixAutoUpdate = false;
+		this.props = new THREE.Group();
+		this.object.add(this.body, this.props);
+		this.slots = [];
+		this.rig = null;
+		this.sources = [];
+		this.sourceTake = this.sourceObjects = null;
+		this.sourcePasses = 0;
+		this.depthMaterial = depthOnly();
+		this.stats = { poses: 0, poseMs: 0 };
+	}
+
+	/** Show or hide the whole set; answers `shown`. */
+	show(shown) {
+		this.object.visible = shown;
+		return shown;
+	}
+
+	/** Rebuild the slots for another rig (a new model, part colours): the old clones go. */
+	setRig(rig) {
+		if (rig === this.rig) return;
+		this.clear();
+		this.rig = rig;
+	}
+
+	/**
+	 * Collect the carried records' meshes (propSources) when the take or the records changed, and
+	 * again on the next `passes - 1` calls: kit parts can mount a frame after the change.
+	 */
+	syncSources(scene, objects, take, passes = 1) {
+		if (this.sourceTake !== take || this.sourceObjects !== objects) Object.assign(this, { sourceTake: take, sourceObjects: objects, sourcePasses: passes });
+		if (this.sourcePasses <= 0) return;
+		this.sourcePasses -= 1;
+		this.setSources(propSources(scene, rideIds(objects, take)));
+	}
+
+	/** Records whose meshes ride along (propSources); every slot rebuilds its prop copies. */
+	setSources(sources) {
+		this.sources = sources;
+		for (const slot of this.slots) this.fillProps(slot);
+	}
+
+	fillProps(slot) {
+		slot.props.clear();
+		slot.records = this.sources.map(({ id, meshes }) => {
+			const group = new THREE.Group();
+			group.matrixAutoUpdate = false;
+			claim(group, this.layer);
+			for (const { geometry, matrix } of meshes) {
+				const mesh = new THREE.Mesh(geometry, slot.material);
+				mesh.matrixAutoUpdate = false;
+				mesh.matrix.copy(matrix);
+				mesh.frustumCulled = false;
+				group.add(mesh);
+				addDepthTwin(mesh, this.depthMaterial);
+				mesh.traverse((node) => claim(node, this.layer));
+			}
+			slot.props.add(group);
+			return { id, group };
+		});
+		slot.f = null;
+		if (slot.order !== null) this.setOrder(slot, slot.order, true);
+	}
+
+	addSlot() {
+		const slot = { material: material(), rig: cloneRig(this.rig), props: new THREE.Group(), records: [], f: null, take: null, order: null };
+		const meshes = [];
+		slot.rig.traverse((node) => { if (node.isMesh) meshes.push(node); });
+		for (const mesh of meshes) { mesh.material = slot.material; mesh.frustumCulled = false; addDepthTwin(mesh, this.depthMaterial); }
+		slot.rig.traverse((node) => claim(node, this.layer));
+		claim(slot.props, this.layer);
+		this.body.add(slot.rig);
+		this.props.add(slot.props);
+		this.fillProps(slot);
+		this.slots.push(slot);
+		return slot;
+	}
+
+	/** The twin at `order`, the colour right after it. */
+	setOrder(slot, order, force = false) {
+		if (slot.order === order && !force) return;
+		slot.order = order;
+		const at = (node) => { node.renderOrder = node.userData.depthTwin ? order : order + 1; };
+		slot.rig.traverse(at);
+		slot.props.traverse(at);
+	}
+
+	/**
+	 * Show `entries` (ghostFrames) of `take`: body poses under `placement` (the rig's parent world
+	 * matrix), carried records at their tracked pose in `propTake` ({ frameCount, fps, objectTracks })
+	 * over the authored `objects`. A slot re-poses only when its frame or take changed.
+	 */
+	update({ entries, take, placement, propTake, objects, count }) {
+		if (placement) { this.body.matrix.copy(placement); this.body.matrixWorldNeedsUpdate = true; }
+		if (!this.rig || !take) entries = [];
+		while (this.slots.length < entries.length) this.addSlot();
+		const t0 = performance.now();
+		let posed = 0, lookup = null;
+		this.slots.forEach((slot, i) => {
+			const entry = entries[i];
+			slot.rig.visible = slot.props.visible = !!entry;
+			if (!entry) return;
+			const look = ghostLook(entry.side, entry.rank, count);
+			slot.material.color.set(look.color).multiplyScalar(1.3);
+			slot.material.opacity = look.opacity;
+			this.setOrder(slot, GHOST_ORDER + 2 * i);
+			if (slot.f === entry.f && slot.take === take && slot.tracks === propTake?.objectTracks) return;
+			Object.assign(slot, { f: entry.f, take, tracks: propTake?.objectTracks });
+			applyTakeFrame(slot.rig, take, entry.f);
+			if (slot.records.length) lookup ??= new Map(objects.map((o) => [o.id, o]));
+			for (const record of slot.records) {
+				const world = trackShown(record.id, entry.f, propTake, lookup) ? sceneObjectTravelMatrixAt(lookup, record.id, entry.f, propTake, record.group.matrix) : null;
+				// A record that does not travel stands where the real one is: no ghost.
+				record.group.visible = !!world;
+				record.group.matrixWorldNeedsUpdate = true;
+			}
+			posed += 1;
+		});
+		if (posed) { this.stats.poses += posed; this.stats.poseMs = +(performance.now() - t0).toFixed(3); }
+	}
+
+	clear() {
+		for (const slot of this.slots) {
+			slot.material.dispose();
+			slot.rig.traverse((node) => { if (node.isSkinnedMesh) node.skeleton.dispose(); });
+			this.body.remove(slot.rig);
+			this.props.remove(slot.props);
+		}
+		this.slots = [];
+	}
+
+	dispose() {
+		this.clear();
+		this.depthMaterial.dispose();
+		this.rig = null;
+		this.sources = [];
+		this.sourceTake = this.sourceObjects = null;
+	}
+}
+
+const captureSets = new WeakMap();
+const sceneOf = (node) => { while (node?.parent) node = node.parent; return node; };
+
+/**
+ * Draw ghosts into one capture (verify_result contact_sheet ghosts: true): the poses
+ * sheetGhostSettings asks for around `frame`, on layer 0 for the duration of `render()` only.
+ * Answers render()'s value; without a rig in a scene or a take v3 it just renders.
+ */
+export function renderWithGhosts({ rig, take, objects = [] }, frame, render) {
+	const scene = sceneOf(rig);
+	if (take?.schema !== "cozyclay.take.v3" || !scene?.isScene) return render();
+	const settings = sheetGhostSettings();
+	let set = captureSets.get(rig);
+	if (!set) { set = new GhostSet({ layer: 0 }); set.setRig(rig); captureSets.set(rig, set); }
+	set.syncSources(scene, objects, take);
+	rig.parent?.updateWorldMatrix(true, false);
+	const entries = ghostFrames({ frame, last: take.frameCount - 1, ...settings, keyFrames: settings.mode === "keys" ? takeKeyFrames(take, objects) : [] });
+	set.update({ entries, take, placement: rig.parent?.matrixWorld, propTake: { frameCount: take.frameCount, fps: take.fps, objectTracks: takeTracks(take) }, objects, count: settings.count });
+	scene.add(set.object);
+	try { return render(); } finally { scene.remove(set.object); }
+}

package/src/held-object-edit.jsx

@@ -0,0 +1,113 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import * as THREE from "three";
+import { GIZMO_LAYER } from "./dualview.jsx";
+import { drawnPose, editKindAt, hingedRootPose, keyObjectArgs, movedRootPose, rootTrackPose, tipTrail, trackedMoverOf, withPreview } from "./held-object-pose.js";
+
+/**
+ * Editing an object a compiled take draws, from the viewport gizmo.
+ *
+ * - The gizmo stands on the drawn pose (held-object-pose.js drawnPose): the
+ *   world centre and rotation the take gives the selection at this frame.
+ * - While a hand holds the object, a move or rotate drag moves the track's
+ *   root (the body, or its carried group root). The object follows the
+ *   pointer through a one-frame preview of the track. On release the pose is
+ *   sent as `motion.keyObject`, which keys it, recompiles the take and makes
+ *   the hand follow (docs/motion-api-v3.1.md C14).
+ * - A hinged object: a ring drag turns it about its hinge and keys that
+ *   angle through the same action (the engine keeps the turn about the axis).
+ * - Anything else (not in hand at this frame, a move on a hinge, or no take)
+ *   keeps the plain placement drag on the authored record.
+ *
+ * Returns the tracks to draw with (the preview applied) and the controller the
+ * ObjectGizmo `held` prop takes, with the tip trail of a carried object.
+ */
+export function useHeldObjectEdit({ selected, objects, tracks, frame, frameCount, fps, motion, run }) {
+	const [preview, setPreview] = useState(null);
+	const dragRef = useRef(null);
+	const lookup = useMemo(() => new Map(objects.map((object) => [object.id, object])), [objects]);
+	const shown = withPreview(tracks, preview);
+	const id = selected?.id ?? null;
+	const mover = id ? trackedMoverOf(lookup, shown, id) : null;
+	const pose = mover ? drawnPose(lookup, id, frame, { frameCount, fps, objectTracks: shown }) : null;
+	const track = mover ? tracks.get(mover.id) : null;
+	const characterId = track?.characterId ?? null;
+	const kind = mover ? editKindAt(mover.track, frame) : null;
+	// The take's own spec entry: a carry's keys, a hinge's pivot and axis.
+	const entry = characterId ? motion?.motionFor?.(characterId)?.spec?.objects?.[mover.id] ?? null : null;
+	const keys = entry?.keys;
+	const keyList = Array.isArray(keys) ? keys.map((key) => key?.f).filter(Number.isFinite).join(",") : "";
+	// The trail walks every frame, so it is rebuilt only when what it reads
+	// changes. Held frames are drawn by the mover's own track alone (the hold
+	// cuts the carry from above), so that track is the whole take it needs.
+	const moverId = mover?.id ?? null, pos = track?.pos, quat = track?.quat, hold = track?.hold, count = track?.frameCount;
+	const trail = useMemo(() => {
+		if (!moverId || !hold) return null;
+		const only = { frameCount: count, pos, quat, hold };
+		const keyFrames = keyList ? keyList.split(",").map(Number) : [];
+		return tipTrail(lookup, id, { track: only }, { frameCount, fps, objectTracks: new Map([[moverId, only]]) }, keyFrames);
+	}, [lookup, id, moverId, pos, quat, hold, count, frameCount, fps, keyList]);
+	useEffect(() => {
+		// QA hook: what the gizmo stands on, read by the browser checks.
+		window.__heldGizmo = pose ? { id, mover: moverId, kind, characterId, pose } : null;
+	});
+	const show = (build) => {
+		const drag = dragRef.current;
+		if (!drag) return;
+		drag.last = build(drag);
+		setPreview({ id: drag.id, frame: drag.frame, ...drag.last });
+	};
+	const gizmo = pose && {
+		pose,
+		trail,
+		// In hand: move and rotate key the pose. A hinge: the rings key its
+		// angle (the turn about the hinge axis); a move stays the plain drag.
+		editable: (kind === "held" || kind === "hinge") && Boolean(characterId),
+		hinge: kind === "hinge",
+		begin() {
+			dragRef.current = { id: moverId, frame: Math.round(frame), root: rootTrackPose(track, frame), pivot: pose.centre, characterId, hinge: kind === "hinge" ? entry ?? {} : null, last: null };
+			return true;
+		},
+		move: (travel) => show((drag) => movedRootPose(drag.root, drag.pivot, { travel })),
+		rotate: (axis, degrees) => show((drag) => (drag.hinge ? hingedRootPose(drag.root, drag.pivot, drag.hinge, axis, degrees) : movedRootPose(drag.root, drag.pivot, { axis, degrees }))),
+		end(commit) {
+			const drag = dragRef.current;
+			dragRef.current = null;
+			if (!commit || !drag?.last) return setPreview(null);
+			let answer = null;
+			try {
+				answer = run("motion.keyObject", keyObjectArgs(drag.characterId, drag.id, drag.frame, drag.last, { hinge: Boolean(drag.hinge) }));
+			} catch (error) {
+				console.warn("motion.keyObject failed", error);
+			}
+			// The preview stays until the recompiled take is installed, so the object does not jump back first.
+			Promise.resolve(answer).finally(() => setPreview(null));
+		},
+	};
+	return { tracks: shown, gizmo };
+}
+
+const TRAIL_COLOR = "#ffd23d";
+
+/** The held object's tip arc and its key markers: editor furniture on GIZMO_LAYER, never recorded. */
+export function HeldTrail({ trail }) {
+	const geometry = useMemo(() => (trail ? new THREE.BufferGeometry().setFromPoints(trail.points.map((point) => new THREE.Vector3(...point))) : null), [trail]);
+	useEffect(() => () => geometry?.dispose(), [geometry]);
+	const groupRef = useRef(null);
+	useEffect(() => {
+		groupRef.current?.traverse((node) => node.layers.set(GIZMO_LAYER));
+	});
+	if (!trail) return null;
+	return (
+		<group ref={groupRef}>
+			<line geometry={geometry} renderOrder={997} frustumCulled={false}>
+				<lineBasicMaterial color={TRAIL_COLOR} transparent opacity={0.8} depthTest={false} depthWrite={false} />
+			</line>
+			{trail.keys.map((point, index) => (
+				<mesh key={index} position={point} renderOrder={997}>
+					<sphereGeometry args={[0.025, 10, 8]} />
+					<meshBasicMaterial color={TRAIL_COLOR} depthTest={false} depthWrite={false} transparent />
+				</mesh>
+			))}
+		</group>
+	);
+}

package/src/held-object-pose.js

@@ -0,0 +1,175 @@
+import { Matrix4, Quaternion, Vector3 } from "three";
+import { sceneObjectTravelMatrixAt } from "./object-travel.js";
+import { EMPTY_KIND } from "./scene-objects.js";
+
+/**
+ * Pose and placement math for editing an object a compiled take draws (a bat
+ * in a hand, a hinged door, the parts of a carried group).
+ *
+ * The take's track sets the pose such an object is drawn at, every frame. Its
+ * authored record is not that pose, so a gizmo on the record stands in the
+ * wrong place and a drag on the record changes nothing on screen. The gizmo
+ * stands on the drawn pose instead, and a drag moves the root of the track
+ * (the body, or the group root that carries it). The new root pose becomes a
+ * held-object key (motion.keyObject, docs/motion-api-v3.1.md C14).
+ *
+ * Track poses are the record's base pivot (bottom centre) in world space, as
+ * object-travel.js composes them.
+ */
+
+const frameIndex = (track, frame) => Math.max(0, Math.min(track.frameCount - 1, Math.round(frame) || 0));
+const parentOf = (lookup, record) => (typeof record.parent === "string" ? lookup.get(record.parent) : null);
+
+/**
+ * The take track that draws record `id`: its own, else the nearest tracked
+ * ancestor's (a carried group root moves its parts). Null when no take draws it
+ * or the chain reaches a record that rides a character bone (`attach`).
+ * @returns {{ id: string, track: object } | null}
+ */
+export function trackedMoverOf(lookup, tracks, id) {
+	const seen = new Set();
+	for (let record = lookup.get(id); record && !seen.has(record.id); record = parentOf(lookup, record)) {
+		seen.add(record.id);
+		if (record.attach) return null;
+		const track = tracks?.get?.(record.id);
+		if (track) return { id: record.id, track };
+	}
+	return null;
+}
+
+/**
+ * What a drag on the mover writes at `frame`: "held" while a hand holds it (a
+ * carried track with its hold flag up), "hinge" for a track with no hold flags,
+ * null when it is carried but not in hand (before the grab, after the release).
+ */
+export function editKindAt(track, frame) {
+	if (!track?.hold) return track ? "hinge" : null;
+	return track.hold[frameIndex(track, frame)] === 1 ? "held" : null;
+}
+
+/** The record's own centre in its local frame: half its height up from the base, or the origin of an Empty. */
+function localCentre(record, out) {
+	return out.set(0, record.renderer === EMPTY_KIND ? 0 : (record.height ?? 1) / 2, 0);
+}
+
+/**
+ * Where record `id` is drawn at `frame`: its world centre and world rotation,
+ * as plain arrays. Null when nothing moves it (the authored record is the pose).
+ * @returns {{ centre: number[], quat: number[] } | null}
+ */
+export function drawnPose(lookup, id, frame, take) {
+	const record = lookup.get(id);
+	const matrix = record ? sceneObjectTravelMatrixAt(lookup, id, frame, take, new Matrix4()) : null;
+	if (!matrix) return null;
+	const quat = new Quaternion();
+	matrix.decompose(new Vector3(), quat, new Vector3());
+	return { centre: localCentre(record, new Vector3()).applyMatrix4(matrix).toArray(), quat: quat.toArray() };
+}
+
+/** The mover's root pose at `frame` from its track: { pos, quat } as three.js values. */
+export function rootTrackPose(track, frame) {
+	const f = frameIndex(track, frame);
+	return {
+		pos: new Vector3().fromArray(track.pos, f * 3),
+		quat: new Quaternion().fromArray(track.quat, f * 4),
+	};
+}
+
+/**
+ * The root pose after a rigid drag about `pivot` (the gizmo's centre): first a
+ * turn of `degrees` about the world `axis` through the pivot, then a world
+ * `travel`. Either part may be absent.
+ */
+export function movedRootPose(root, pivot, { travel = null, axis = null, degrees = 0 } = {}) {
+	const pos = root.pos.clone();
+	const quat = root.quat.clone();
+	if (axis && degrees) {
+		const turn = new Quaternion().setFromAxisAngle(axis.clone().normalize(), (degrees * Math.PI) / 180);
+		const centre = new Vector3().fromArray(pivot);
+		pos.sub(centre).applyQuaternion(turn).add(centre);
+		quat.premultiply(turn).normalize();
+	}
+	if (travel) pos.add(travel);
+	return { pos, quat };
+}
+
+/**
+ * A ring drag on a hinged object: only the turn about the hinge axis is kept
+ * (the engine keeps the same, C14), about the hinge pivot. `hinge` is its
+ * spec.objects entry ({ pivot, axis }, world space); without a pivot the
+ * gizmo centre stands in.
+ */
+export function hingedRootPose(root, centre, hinge, axis, degrees) {
+	const hingeAxis = new Vector3().fromArray(hinge?.axis ?? [0, 1, 0]).normalize();
+	return movedRootPose(root, hinge?.pivot ?? centre, { axis: hingeAxis, degrees: degrees * axis.clone().normalize().dot(hingeAxis) });
+}
+
+const snapTo = (value, step) => (step ? Math.round(value / step) * step : value);
+
+/**
+ * A move drag's world travel: the pointer's world delta read along each free
+ * axis (one for an arrow, two for a plane square), each snapped to `step` m.
+ */
+export function dragTravel(delta, axes, step = 0) {
+	const travel = new Vector3();
+	for (const axis of axes) travel.addScaledVector(axis, snapTo(delta.dot(axis), step));
+	return travel;
+}
+
+/** A ring drag's turn in degrees, snapped to `step`. */
+export const dragTurn = (degrees, step = 0) => snapTo(degrees, step);
+
+/**
+ * The tracks with one frame of one mover replaced by a preview pose, so the
+ * object follows the pointer while a drag is open. The source tracks are not
+ * changed.
+ */
+export function withPreview(tracks, preview) {
+	const track = preview && tracks?.get?.(preview.id);
+	if (!track) return tracks;
+	const f = frameIndex(track, preview.frame);
+	const pos = Float32Array.from(track.pos);
+	const quat = Float32Array.from(track.quat);
+	pos.set(preview.pos.toArray(), f * 3);
+	quat.set(preview.quat.toArray(), f * 4);
+	return new Map(tracks).set(preview.id, { ...track, pos, quat });
+}
+
+const round = (value) => Math.round(value * 1e4) / 1e4;
+
+/**
+ * The motion.keyObject arguments for a root pose at `frame` (world metres, quaternion [x, y, z, w]).
+ * A hinge sends the rotation alone: the engine keeps its turn about the hinge axis.
+ */
+export function keyObjectArgs(characterId, objectId, frame, pose, { hinge = false } = {}) {
+	return {
+		characterId,
+		objectId,
+		frame: Math.max(0, Math.round(frame)),
+		...(hinge ? {} : { pos: pose.pos.toArray().map(round) }),
+		rot: pose.quat.clone().normalize().toArray().map(round),
+	};
+}
+
+/**
+ * The arc the held object draws: the tip of record `id` (its top along its own
+ * +Y, or the origin of an Empty) at every frame its mover is in hand, and the
+ * tip at each key frame. Null when the mover has no hold flags.
+ * @returns {{ points: number[][], keys: number[][] } | null}
+ */
+export function tipTrail(lookup, id, mover, take, keyFrames = []) {
+	const record = lookup.get(id);
+	const hold = mover?.track?.hold;
+	if (!record || !hold) return null;
+	const tipLocal = new Vector3(0, record.renderer === EMPTY_KIND ? 0 : (record.height ?? 1), 0);
+	const matrix = new Matrix4();
+	const tipAt = (frame) => (sceneObjectTravelMatrixAt(lookup, id, frame, take, matrix) ? tipLocal.clone().applyMatrix4(matrix).toArray() : null);
+	const points = [];
+	for (let frame = 0; frame < mover.track.frameCount; frame += 1) {
+		if (hold[frame] !== 1) continue;
+		const tip = tipAt(frame);
+		if (tip) points.push(tip);
+	}
+	const keys = keyFrames.filter((frame) => hold[frameIndex(mover.track, frame)] === 1).map(tipAt).filter(Boolean);
+	return points.length > 1 ? { points, keys } : null;
+}

package/src/hierarchy-model.js

@@ -121,7 +121,7 @@ function objectRow(object, label) {
 		kind: "object",
 		hidden: object.hidden === true,
 		// The record's kind, so a row can say it is a node with nothing to draw.
-		...(object.renderer === "empty" ? { renderer: "empty" } : {}),
+		...(object.renderer === "empty" || object.renderer === "light" ? { renderer: object.renderer } : {}),
 	};
 }
 

package/src/hierarchy-panel.jsx

@@ -123,7 +123,7 @@ const OUTLINER_TYPES = {
 
 function outlinerTypeFor(node) {
 	const key = node.kind === "object"
-		? node.renderer === "empty" ? "empty" : "mesh"
+		? node.renderer === "empty" ? "empty" : node.renderer === "light" ? "light" : "mesh"
 		: node.kind === "character" || node.kind === "bone"
 			? "cast"
 			: node.kind === "camera"