cozyclay 2.0.0 → 2.1.0

package/src/matte-editor.js

@@ -43,10 +43,10 @@ const OVERLAY_ALPHA = 0.62;
 const STAGE_GROUND = "#141819";
 /** Interaction runs on a preview this wide at most — the paint underneath it
  * stays at the picture's own resolution. */
-export const EDIT_PREVIEW_MAX = 512;
+const EDIT_PREVIEW_MAX = 512;
 /** Zoom range. 1 is the whole picture — there is no reason to look at less of
  * it than that — and 16 puts a preview pixel under a fingertip. */
-export const MIN_ZOOM = 1;
+const MIN_ZOOM = 1;
 export const MAX_ZOOM = 16;
 /** How many edits back you can walk. Each step is a full-resolution copy of
  * the selection, so this is a memory budget as much as a usability one: seven
@@ -251,8 +251,6 @@ export function createMatteEditor(canvas, {
 		report();
 	}
 
-	/* --------------------------------------------------------- pointer --- */
-
 	/** Where a pointer is, in FULL-resolution picture pixels: stage → picture,
 	 * through the same placement the paint is drawn with. */
 	function at(event) {
@@ -370,8 +368,6 @@ export function createMatteEditor(canvas, {
 		growFromStroke();
 		if (canvas.hasPointerCapture?.(event.pointerId)) canvas.releasePointerCapture(event.pointerId);
 	};
-	/* ------------------------------------------------------------ view --- */
-
 	/** Zoom about a point on screen, so what is under the cursor stays under
 	 * the cursor — the only zoom that lets you keep working on the thing you
 	 * were looking at. */
@@ -416,8 +412,6 @@ export function createMatteEditor(canvas, {
 	canvas.addEventListener("keydown", onKeyDown);
 	canvas.addEventListener("keyup", onKeyUp);
 
-	/* ------------------------------------------------------------- api --- */
-
 	return {
 		/**
 		 * Decode an asset and show it AS IT IS. Nothing is marked until someone

package/src/matte.js

@@ -109,15 +109,6 @@ export function borderSeeds({ data, width, height }, points = null) {
 	return { seeds: Float64Array.from(seeds), starts };
 }
 
-/**
- * Drop the background, in place on a copy.
- *
- * `tolerance` (0–1) is the one control a person should ever need: it scales
- * both the bound against the seed colours and the local step. `shrink` eats
- * the fringe of background-coloured pixels that survives any threshold, and
- * `feather` softens what is left so the card's edge does not read as a
- * cut-out-with-scissors line against the set.
- */
 /**
  * `within`, when given, fences the growth: a pixel can only be entered if it is
  * marked there. That is what lets the eraser be the same tool as the brush —
@@ -177,8 +168,6 @@ export function backgroundMask(pixels, { points = null, tolerance = 0.18, within
 	return background;
 }
 
-/* -------------------------------------------------------------- brush ---- */
-
 /**
  * A round stroke into the paint layer: `value` 1 means "this is background
  * after all", -1 means "put that back". The paint layer is kept SEPARATE from
@@ -235,8 +224,6 @@ export function combineMask(auto, paint, { width, height, paintWidth = width, pa
 	return out;
 }
 
-/* -------------------------------------------------------------- apply ---- */
-
 /**
  * Turn a mask into transparency: erode the fringe, soften the boundary, write
  * the alpha. Split from the growth above so the editor can show a mask, let
@@ -257,7 +244,6 @@ function dropEdgeLines(data, width, height) {
 	let changed = 0;
 	for (let i = 0; i < total; i += 1) {
 		if (data[i * 4 + 3] < 8 || visited[i]) continue;
-		// flood this kept component
 		stack.length = 0;
 		stack.push(i);
 		visited[i] = 1;
@@ -336,7 +322,6 @@ export function applyMask(pixels, mask, { shrink = 1, feather = 1 } = {}) {
 		grown = next;
 	}
 
-	/* -- alpha, then a soft edge that only touches the boundary ------------- */
 	const alpha = new Float32Array(total);
 	let removed = 0;
 	for (let pixel = 0; pixel < total; pixel++) {
@@ -387,8 +372,6 @@ export function removeBackground(pixels, { points = null, tolerance = 0.18, shri
 	return applyMask(pixels, grown, { shrink, feather });
 }
 
-/* --------------------------------------------------------------- trim ---- */
-
 /** The box the picture still occupies, or null when nothing survived. */
 export function opaqueBounds({ data, width, height }, threshold = 8) {
 	let minX = width;
@@ -422,8 +405,6 @@ export function cropPixels({ data, width, height }, box) {
 	return { data: out, width: box.width, height: box.height };
 }
 
-/* ------------------------------------------------------------- browser ---- */
-
 function defaultCanvas(width, height) {
 	if (typeof OffscreenCanvas === "function") return new OffscreenCanvas(width, height);
 	throw new Error("this browser cannot edit images — OffscreenCanvas is unavailable");

package/src/mesh-graph-clone.js

@@ -5,6 +5,10 @@
  * a Mixamo-as-statue (or any skinned GLB) can bind to the wrong bones. Graphs
  * that actually contain a SkinnedMesh go through SkeletonUtils; everything
  * else keeps the cheap deep clone.
+ *
+ * Both clones share materials with the cache, so each instance gets its own
+ * copies (marked `instanceOwned`, disposed with the instance): a per-object
+ * write such as `object.opacity` must not leak into other copies.
  */
 import { clone as cloneSkeleton } from "three/examples/jsm/utils/SkeletonUtils.js";
 
@@ -18,6 +22,16 @@ export function graphHasSkinnedMesh(root) {
 
 export function cloneMeshGraph(source) {
 	if (!source) return source;
-	if (graphHasSkinnedMesh(source)) return cloneSkeleton(source);
-	return source.clone(true);
+	const root = graphHasSkinnedMesh(source) ? cloneSkeleton(source) : source.clone(true);
+	const copies = new Map();
+	const own = (material) => {
+		if (!copies.has(material)) copies.set(material, material.clone());
+		return copies.get(material);
+	};
+	root.traverse((node) => {
+		if (!node.isMesh || !node.material) return;
+		node.material = Array.isArray(node.material) ? node.material.map(own) : own(node.material);
+		node.userData.instanceOwned = true;
+	});
+	return root;
 }

package/src/mesh-sniff.js

@@ -61,7 +61,6 @@ export function looksLikeObj(bytes) {
 		const line = raw.trim();
 		if (!/^v\s+/.test(line)) continue;
 		const parts = line.split(/\s+/);
-		if (parts[0] !== "v") continue;
 		if ([parts[1], parts[2], parts[3]].every((part) => Number.isFinite(Number(part)))) return true;
 	}
 	return false;

package/src/monotone-cubic.js

@@ -0,0 +1,40 @@
+/**
+ * A monotone piecewise cubic through authored knots (harmonic-mean tangents,
+ * Fritsch–Carlson family): it hits every knot exactly, never overshoots between
+ * two of them, runs flat across a local extremum and degrades to the exact
+ * straight lerp for two knots. The camera crane's height profile and a route's
+ * lean (bank / pitch) marks share it, so a dot means the same thing on both rails.
+ *
+ * @param {object[]} knots ascending by `t`; at least one
+ * @param {number} x position along the profile (clamped to the knots' span)
+ * @param {(knot: object) => number} read the knot's value; defaults to `knot.v`
+ */
+export function monotoneCubicAt(knots, x, read = (knot) => knot.v) {
+	const last = knots.length - 1;
+	const clamped = Math.max(knots[0].t, Math.min(knots[last].t, x));
+	if (clamped <= knots[0].t) return read(knots[0]);
+	if (clamped >= knots[last].t) return read(knots[last]);
+	let i = 0;
+	while (i < knots.length - 2 && clamped > knots[i + 1].t) i += 1;
+	const p0 = knots[i];
+	const p1 = knots[i + 1];
+	const h = p1.t - p0.t;
+	if (h < 1e-9) return read(p1);
+	const v0 = read(p0);
+	const v1 = read(p1);
+	const secant = (a, b) => (read(b) - read(a)) / Math.max(b.t - a.t, 1e-9);
+	const d = secant(p0, p1);
+	// harmonic mean of neighbouring secants; zero across a local extremum
+	const mono = (sa, sb) => (sa * sb <= 0 ? 0 : (2 * sa * sb) / (sa + sb));
+	const m0 = i > 0 ? mono(secant(knots[i - 1], p0), d) : d;
+	const m1 = i < knots.length - 2 ? mono(d, secant(p1, knots[i + 2])) : d;
+	const u = (clamped - p0.t) / h;
+	const u2 = u * u;
+	const u3 = u2 * u;
+	return (
+		(2 * u3 - 3 * u2 + 1) * v0 +
+		(u3 - 2 * u2 + u) * h * m0 +
+		(-2 * u3 + 3 * u2) * v1 +
+		(u3 - u2) * h * m1
+	);
+}

package/src/motion/generation.js

@@ -1,7 +1,7 @@
 // Pure request construction. The caller supplies one rolled seed and sampled
 // poses; no rig, store, random source, notification or network is touched here.
 import { StudioProtocolError, compileStudioBeats } from '../studio-agent-protocol.js';
-import { TIMELINE_FRAME_FPS as FPS } from '../scenes.js';
+import { TIMELINE_FRAME_FPS as FPS } from '../timeline-fps.js';
 import { judgeAuthoredPath, alignArdyPath } from '../ardy/waypoints.js';
 import { planPosePin, PIN_BLOCKED } from '../ardy/pose-pin.js';
 import { blocksFromRequest, replayPayload, replayTruncated } from '../take-recipe.js';

package/src/motion-store.js

@@ -1,10 +1,10 @@
-export const MOTION_DB_NAME = "cozyclay.motions";
-export const MOTION_DB_VERSION = 1;
-export const MOTION_STORE_NAME = "motions";
+const MOTION_DB_NAME = "cozyclay.motions";
+const MOTION_DB_VERSION = 1;
+const MOTION_STORE_NAME = "motions";
 
 const validId = (id) => typeof id === "string" && /^[0-9a-f]{64}$/i.test(id);
 
-export function normalizeMotion(record) {
+function normalizeMotion(record) {
 	if (!record || typeof record !== "object" || !validId(record.motionId)) return null;
 	if (record.encoding !== "base64" || typeof record.data !== "string") return null;
 	return { ...record, motionId: record.motionId.toLowerCase(), stored: true };

package/src/motion-trail.js

@@ -28,10 +28,11 @@ const LIMB_CHAINS = {
 };
 
 /**
- * The always-drawn trail tracks: root plus every IK chain endpoint and the
- * head, coloured exactly like their viewport IK/FK handles (posestudio.jsx
- * coding: arms orange, legs blue, torso yellow, head purple). Pick order is
- * limbs-first so an overlapping grab prefers the finer target; hips last.
+ * The available trail tracks: root plus every IK chain endpoint and the head,
+ * coloured exactly like their viewport IK/FK handles (posestudio.jsx coding:
+ * arms orange, legs blue, torso yellow, head purple). The viewport can focus
+ * one track after selection; pick order is limbs-first so an overlapping grab
+ * prefers the finer target; hips last.
  */
 export const TRAIL_TRACKS = [
 	{ id: "leftHand", joint: "LeftHand", color: "#ff8a3d" },
@@ -295,13 +296,6 @@ const matVec = (m, v) => [
 	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);

package/src/multimodel-ingest.js

@@ -8,8 +8,6 @@
 // and a silent fallback to a plausible-looking default is how footage that was
 // never read ends up looking ingested.
 
-export const INGEST_STAGES = Object.freeze(["idle", "fetching", "probing", "ready", "error"]);
-
 /** A successful extraction is not proof that vertical recovery was applied. */
 export function trajectoryReceipt(report, korean = false) {
 	if (!report) return "";
@@ -242,7 +240,7 @@ export function fpsFromFrameTimes(times, fallback = 30) {
 	return { fps: Math.round(1 / median), measured: true };
 }
 
-export function formatBytes(bytes) {
+function formatBytes(bytes) {
 	if (!Number.isFinite(bytes) || bytes < 0) return "";
 	if (bytes < 1024) return `${bytes} B`;
 	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;

package/src/object-catalog.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState } from "react";
 import { ko, isKo } from "./locale.js";
-import { OBJECT_LIBRARY } from "./scene-objects.js";
+import { EMPTY_KIND, OBJECT_MENU_ENTRIES } from "./scene-objects.js";
 
 const GROUP_LABELS_KO = {
 	Primitives: "기본 도형",
@@ -8,6 +8,7 @@ const GROUP_LABELS_KO = {
 };
 
 const OBJECT_LABELS_KO = {
+	Empty: "빈 오브젝트",
 	Cube: "큐브",
 	Sphere: "구",
 	Capsule: "캡슐",
@@ -19,7 +20,7 @@ const OBJECT_LABELS_KO = {
 	"Plane (aircraft)": "비행기",
 };
 
-export function displayObjectGroupName(name) {
+function displayObjectGroupName(name) {
 	return isKo ? (GROUP_LABELS_KO[name] ?? name) : name;
 }
 
@@ -39,9 +40,9 @@ export function displayObjectLabel(label) {
 /** The catalogue grouped by section. Shared with the hierarchy's right-click
  * create menu so both entry points list the same objects
  * (docs/unity-reference.md §9.7). */
-export function buildObjectMenuGroups() {
+function buildObjectMenuGroups() {
 	const groups = [];
-	for (const entry of OBJECT_LIBRARY) {
+	for (const entry of OBJECT_MENU_ENTRIES) {
 		const group = groups.find((item) => item.name === entry.group);
 		if (group) group.entries.push(entry);
 		else groups.push({ name: entry.group, entries: [entry] });
@@ -65,7 +66,8 @@ export function CatalogueEntries({ onPick }) {
 				>
 					<span className={`add-object-swatch ${entry.kind}`} style={{ background: entry.color }} aria-hidden="true" />
 					<span>{displayObjectLabel(entry.label)}</span>
-					<small>{entry.footprint.width} × {entry.footprint.depth} m</small>
+					{/* An empty has no size to quote: say what it is instead of "0 × 0 m". */}
+					<small>{entry.kind === EMPTY_KIND ? ko("node only", "노드 전용") : `${entry.footprint.width} × ${entry.footprint.depth} m`}</small>
 				</button>
 			))}
 		</div>

package/src/object-gizmo.jsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
 import { GIZMO_LAYER, SHOT_ASPECT, fitAspect } from "./dualview.jsx";
@@ -228,21 +228,6 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 		rootRef.current?.traverse((node) => node.layers?.set(GIZMO_LAYER));
 	});
 
-	/** pointer -> NDC inside the rect the shot camera actually rendered into */
-	const pointerRay = (event) => {
-		const pane = paneRef.current;
-		const camera = camRef.current;
-		if (!pane || !camera) return null;
-		const bounds = pane.getBoundingClientRect();
-		if (bounds.width < 2 || bounds.height < 2) return null;
-		const rect = imageRect(bounds);
-		tools.ndc.set(
-			((event.clientX - rect.x) / rect.w) * 2 - 1,
-			-((event.clientY - rect.y) / rect.h) * 2 + 1,
-		);
-		return Math.abs(tools.ndc.x) <= 1 && Math.abs(tools.ndc.y) <= 1 ? tools.ndc : null;
-	};
-
 	/** the scene object under the pointer, if any (meshes carry the id on an
 	 * ancestor group, so the hit walks up to find it) */
 	const pickObject = () => {
@@ -256,9 +241,18 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 		// whichever surface is nearer.
 		tools.raycaster.layers.set(GIZMO_LAYER);
 		let ghostId = null;
+		let ghostIsEmpty = false;
 		const ghostHit = tools.raycaster.intersectObjects(scene.children, true).find((entry) => {
 			if (!entry.object.isMesh) return false;
 			for (let node = entry.object; node; node = node.parent) {
+				// An Empty's marker: its pick volume is a gizmo-layer mesh under
+				// the object's own group, so the owning record is the first
+				// ancestor carrying a sceneObjectId.
+				if (entry.object.userData?.emptyPick && node.userData?.sceneObjectId) {
+					ghostId = node.userData.sceneObjectId;
+					ghostIsEmpty = true;
+					return true;
+				}
 				if (node.userData?.shotCameraPick) {
 					ghostId = "__shotcam__";
 					return true;
@@ -271,7 +265,9 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 			return false;
 		});
 		tools.raycaster.layers.set(0);
-		if (ghostHit && (!hit || ghostHit.distance < hit.distance)) return { id: ghostId, point: ghostHit.point.clone() };
+		// The Empty's marker is drawn over the set (no depth test), so what you
+		// see is what you click: it wins over whatever surface is behind it.
+		if (ghostHit && (ghostIsEmpty || !hit || ghostHit.distance < hit.distance)) return { id: ghostId, point: ghostHit.point.clone() };
 		if (!hit) return null;
 		for (let node = hit.object; node; node = node.parent) {
 			if (node.userData?.sceneObjectId) return { id: node.userData.sceneObjectId, point: hit.point.clone() };
@@ -478,9 +474,15 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 		 * null for the uniform-scale knob and for plane handles, which carry
 		 * their own `plane` axes instead. */
 		const beginDrag = (kind, axis, dir, camera) => {
-			const live = stateRef.current.object;
-			if (!live) return false;
-			tools.origin.set(live.x, gizmoHeight(live), live.z);
+			const shown = stateRef.current.object;
+			if (!shown) return false;
+			// The gizmo can be SHOWN on the pose a routed record is drawn at, while
+			// every channel a drag writes starts from the AUTHORED record: a start
+			// taken from the drawn numbers would land them in the authored ones
+			// (a jump of however far the car has driven). The pivot, and the yaw
+			// the card's corners are seen at, are the shown ones.
+			const live = stateRef.current.objects.find((entry) => entry.id === shown.id) ?? shown;
+			tools.origin.set(shown.x, gizmoHeight(shown), shown.z);
 			camera.getWorldDirection(tools.eye);
 			let plane;
 			let drag;
@@ -525,7 +527,7 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 				// The card's own plane, so the grab tracks the picture rather than a
 				// world axis: a standee that has been turned is still resized by the
 				// corner the eye sees.
-				const yaw = ((live.rot ?? 0) * Math.PI) / 180;
+				const yaw = ((shown.rot ?? 0) * Math.PI) / 180;
 				const right = new THREE.Vector3(Math.cos(yaw), 0, -Math.sin(yaw));
 				const up = new THREE.Vector3(0, 1, 0);
 				const normal = new THREE.Vector3().crossVectors(right, up).normalize();
@@ -631,17 +633,22 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 			// side-effect free: it only answers "would you grab here?".
 			if (stateRef.current.claimPointer?.(event)) return;
 			const grabbed = pickHandle(event);
-			// A press ON the key-light sun outranks any handle overlapping it:
-			// the puck's own body-drag is the primary interaction there, and the
-			// centre plane-square would otherwise silently claim the grab.
+			// A press ON the key-light sun, or on a route or crane dot, outranks
+			// any handle overlapping it: the puck's own body-drag and the dot's
+			// own grab are the primary interaction there, and the centre
+			// plane-square would otherwise silently claim the grab. (A routed
+			// object drawn at frame 0 sits exactly on its route's start dot.)
 			if (grabbed && rayFrom(event)) {
 				tools.raycaster.layers.set(GIZMO_LAYER);
-				const sunClaims = tools.raycaster.intersectObjects(scene.children, true).some((entry) => {
-					for (let node = entry.object; node; node = node.parent) if (node.userData?.keyLightPick) return true;
+				const dotClaims = tools.raycaster.intersectObjects(scene.children, true).some((entry) => {
+					for (let node = entry.object; node; node = node.parent) {
+						const data = node.userData;
+						if (data?.keyLightPick || data?.pathIndex !== undefined || data?.pathRing || data?.craneIndex !== undefined) return true;
+					}
 					return false;
 				});
 				tools.raycaster.layers.set(0);
-				if (sunClaims) return;
+				if (dotClaims) return;
 			}
 			if (
 				grabbed &&
@@ -769,9 +776,9 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 
 	// QA hook: where each handle sits on screen, through the exact rect the
 	// picker builds its ray from. Headless checks drive real pointer events
-	// with it (harmless in normal use).
-	if (typeof window !== "undefined") {
-		if (!pickOnly) window.__gizmoHandles = () => {
+	// with it (harmless in normal use). The character gizmo is a separate
+	// pick-only instance, so it needs its own mirror hook.
+	const getHandles = useCallback(() => {
 			const camera = camRef?.current;
 			const pane = paneRef?.current;
 			if (!camera || !pane) return [];
@@ -799,8 +806,15 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 						y: rect.y + ((1 - point.y) / 2) * rect.h,
 					};
 				});
+		}, [camRef, paneRef, shotAspect]);
+	if (typeof window !== "undefined" && !pickOnly) window.__gizmoHandles = getHandles;
+	useEffect(() => {
+		if (typeof window === "undefined" || !pickOnly) return undefined;
+		window.__characterGizmoHandles = getHandles;
+		return () => {
+			if (window.__characterGizmoHandles === getHandles) delete window.__characterGizmoHandles;
 		};
-	}
+	}, [getHandles, pickOnly]);
 
 	if (!enabled || !object) {
 		handlesRef.current.clear();