cozyclay 2.1.0 → 3.0.0

package/src/studio-support-gap.js

@@ -0,0 +1,74 @@
+// How far each placed object stands off what holds it up: the support gap verify_result's
+// placement check reports beside the footprint overlap (studio-agent-commands.js placementChecks),
+// measured on the same world AABB proxies.
+//
+// A group is one unit: the union AABB of its solid parts, judged through its root (a part names
+// its root group). Its support is the floor, or the highest top among the other solid objects
+// whose footprint overlaps the unit's and whose top lies below the unit's middle height.
+// supportGapM is the unit's bottom above that top (0 when it rests on it or sinks into it).
+// These are measurements, not failures: unsupportedIds lists the gaps over 1 cm.
+//
+// Not measured: characters, lights, effects, a group with no solid part, records on a route or
+// riding a character, and records an installed take moves where their scene pose is never drawn
+// (a follow or hinge entry, or a carry in hand from its first frame). A carry grabbed later
+// stands at its scene pose until the grab, so it is measured there.
+import { descendantsOf, isEffectivelyHidden, isEmptyObject } from './scene-objects.js';
+import { EFFECT_KIND } from './effects/effect-record.js';
+import { isCarried, movesRecord } from './motion3/carried.js';
+
+const UNSUPPORTED_M = 0.01, EPS = 1e-6;
+const round = v => Number(v.toFixed(4));
+
+/** Ids the installed takes move (spec.objects keys of each target's take v3), from the binding's targets map. */
+function takeMovedIds(takes) {
+  const moved = new Set();
+  for (const target of takes?.values?.() ?? []) {
+    const take = target?.motion;
+    if (take?.schema !== 'cozyclay.take.v3') continue;
+    for (const [id, entry] of Object.entries(take.spec?.objects ?? {}))
+      if (movesRecord(entry) && !(isCarried(entry) && entry.grab > 0)) moved.add(id);
+  }
+  return moved;
+}
+
+/** [object, parent, ..., root] by id, stopping at a missing parent or a loop. */
+function chainOf(id, byId) {
+  const chain = [];
+  for (let o = byId.get(id); o && !chain.includes(o); o = o.parent ? byId.get(o.parent) : null) chain.push(o);
+  return chain;
+}
+
+const solid = (o, state) => !isEmptyObject(o) && o.renderer !== EFFECT_KIND && !isEffectivelyHidden(o, state.objects, state.characters);
+
+/** Union { min, max } of boxes, or null for none. */
+function union(boxes) {
+  if (!boxes.length) return null;
+  const pick = (end, f) => Object.fromEntries(['x', 'y', 'z'].map(a => [a, f(...boxes.map(b => b[end][a]))]));
+  return { min: pick('min', Math.min), max: pick('max', Math.max) };
+}
+
+const footprintsOverlap = (a, b) => ['x', 'z'].every(a2 => Math.min(a.max[a2], b.max[a2]) - Math.max(a.min[a2], b.min[a2]) > EPS);
+
+/**
+ * { supportGapM: { unitId: metres }, unsupportedIds } for the objects among `ids` (each unit once).
+ * boxOf(entity) answers its world { min, max } or null (studio-agent-commands.js entityWorldBounds);
+ * takes is the binding's targets map (characterId -> { motion }), or undefined.
+ */
+export function supportGaps(ids, state, takes, boxOf) {
+  const byId = new Map(state.objects.map(o => [o.id, o])), moved = takeMovedIds(takes);
+  const rootOf = id => chainOf(id, byId).at(-1)?.id;
+  // A part counts when nothing above it rides a character, a route or a take.
+  const free = o => chainOf(o.id, byId).every(c => !c.attach && !c.path && !moved.has(c.id));
+  const units = [...new Set(ids.filter(id => byId.has(id)).map(rootOf))];
+  const boxes = new Map(state.objects.filter(o => solid(o, state)).map(o => [o.id, boxOf(o)]).filter(([, box]) => box));
+  const supportGapM = {};
+  for (const root of units) {
+    const parts = [byId.get(root), ...descendantsOf(state.objects, root)].filter(o => boxes.has(o.id) && free(o));
+    const own = union(parts.map(o => boxes.get(o.id)));
+    if (!own) continue;
+    const middle = (own.min.y + own.max.y) / 2;
+    const tops = [...boxes].filter(([id, box]) => rootOf(id) !== root && box.max.y <= middle && footprintsOverlap(own, box)).map(([, box]) => box.max.y);
+    supportGapM[root] = round(Math.max(0, own.min.y - Math.max(state.floorY ?? 0, ...tops)));
+  }
+  return { supportGapM, unsupportedIds: Object.keys(supportGapM).filter(id => supportGapM[id] > UNSUPPORTED_M) };
+}

package/src/styles.css

@@ -1543,25 +1543,6 @@ select {
 	font-size: 11px;
 	font-weight: 700;
 }
-/* The photo tile reads as a second, distinct source next to Save pose rather
-   than a variant of it, so its dashed outline carries the accent hue. */
-.pose-tile.add.photo {
-	border-color: color-mix(in srgb, var(--cyan) 42%, var(--line2));
-	color: color-mix(in srgb, var(--cyan) 70%, var(--muted));
-}
-.pose-tile.add.photo .add-plus {
-	font-size: 22px;
-}
-.pose-tile.add.photo.busy {
-	border-style: solid;
-	opacity: 0.75;
-	cursor: progress;
-}
-.pose-tile.add.photo:disabled:hover {
-	border-color: color-mix(in srgb, var(--cyan) 42%, var(--line2));
-	background: transparent;
-}
-
 /* ------------------------------------------------------------ panel ------- */
 
 .panel {
@@ -7296,6 +7277,7 @@ input[type=range] {
 	white-space: nowrap;
 }
 
+/* The panels' native file pickers stay hidden; their own buttons open them. */
 .multimodel-file-input {
 	display: none;
 }

package/src/timeline-defaults.js

@@ -0,0 +1,5 @@
+// The studio timeline's shared numbers: the production clock and the defaults a scene starts from.
+export const TIMELINE_FPS = 24;
+export const DEFAULT_DURATION_S = 15; // pre-motion timeline duration; shown as duration x TIMELINE_FPS frames
+export const DEFAULT_PLAYBACK_SPEED = 1;
+export const MAX_WAYPOINTS = 32; // a root path holds 2..32 distinct waypoint frames

package/src/timeline-extent.js

@@ -2,8 +2,8 @@
  * Return the current content-driven length of the shared production clock.
  *
  * The active character is represented by the editing-buffer motion; inactive
- * characters keep their committed sessionMotion. Prompt block endFrame values
- * are already expressed as an exclusive timeline count, matching motion.frames.
+ * characters keep their committed sessionMotion (motion.frames is an exclusive
+ * timeline count).
  *
  * A zero result is intentional: an empty scene keeps its existing authored
  * duration instead of collapsing the pre-generation clock to one frame.
@@ -11,28 +11,16 @@
 export function timelineContentExtent(
 	characters = [],
 	activeCharacterId = null,
-	activeMotion = null,
-	promptClips = [],
+		activeMotion = null,
 	extraFrames = 0,
 ) {
-	const longestMotion = characters.reduce((max, entry) => {
+	const authoredExtent = characters.reduce((max, entry) => {
 		const clip = entry.id === activeCharacterId ? activeMotion : entry.sessionMotion;
-		const layerPromptEnd = entry.id === activeCharacterId
-			? 0
-			: (entry.layer?.promptClips ?? []).reduce(
-				(layerMax, clip) => Math.max(layerMax, Number.isFinite(clip?.endFrame) ? clip.endFrame : 0),
-				0,
-			);
-		return Math.max(max, Number.isFinite(clip?.frames) ? clip.frames : 0, layerPromptEnd);
+		return Math.max(max, Number.isFinite(clip?.frames) ? clip.frames : 0);
 	}, 0);
-	const promptEnd = promptClips.reduce(
-		(max, clip) => Math.max(max, Number.isFinite(clip?.endFrame) ? clip.endFrame : 0),
-		0,
-	);
-	const authoredExtent = Math.max(longestMotion, promptEnd);
-	// Ingested footage owns the clock only before a cast take or prompt
-	// schedule exists. Once a 136-frame take is installed, an older 192-frame
-	// source video must not recreate the frozen tail this helper prevents.
+	// Ingested footage owns the clock only before a cast take exists. Once a
+	// 136-frame take is installed, an older 192-frame source video must not
+	// recreate the frozen tail this helper prevents.
 	return authoredExtent > 0
 		? authoredExtent
 		: Number.isFinite(extraFrames) ? extraFrames : 0;

package/src/tutorial-walk.js

@@ -0,0 +1,17 @@
+// The camera tutorial's set dressing: a short compiled walk (take v3) for the starter scene's
+// character, so the Shot / Rail / Play steps have somebody moving through the set. Built from
+// the character's own bind skeleton and placement; null for a body motion3 cannot drive.
+import { skeletonFor } from "./motion3/rigs/index.js";
+import { add, apply, ry } from "./motion3/compiler/math.js";
+
+const TUTORIAL_WALK_LABEL = "A person walks forward and stops.";
+
+export function tutorialWalkSpec(character) {
+	const sk = skeletonFor(character?.model);
+	if (!sk) return null;
+	const I = sk.index, P = sk.restWorldPos, ank = P[I.LeftFoot][1], yaw = character.rot ?? 0;
+	const at = (offset, y) => add([character.x ?? 0, character.y ?? 0, character.z ?? 0], apply(ry(yaw), [offset[0], y, offset[1]]));
+	return { schema: "cozyclay.motion-spec.v1", fps: 24, frames: 216, label: TUTORIAL_WALK_LABEL,
+		keys: [{ f: 0, set: { root: at([0, 0], P[I.Hips][1] - 0.01), yaw, foot_l: at([0.09, -0.03], ank), foot_r: at([-0.09, 0.03], ank), fyaw_l: yaw, fyaw_r: yaw } }],
+		generators: [{ type: "walk", f0: 6, steps: 8, heading: [yaw, yaw] }] };
+}

package/src/ui-scrub.js

@@ -7,7 +7,7 @@
  * a pixel buy?". They live here so a Node test can prove them without a DOM.
  *
  * Sensitivity is a RATE over a fixed travel, the same rule the timeline's
- * curve editors follow (src/ardy/timeline.jsx DRAG_TRAVEL_PX): dragging the
+ * curve editors follow (src/motion/timeline.jsx DRAG_TRAVEL_PX): dragging the
  * hand across `SCRUB_TRAVEL_PX` sweeps one meaningful span of the field. The
  * old `pixels * step` mapping tied the feel to the field's precision, so a
  * step 0.05 field needed 100 px to move 5 units while a step 1 field bolted.

package/src/use-shot-camera-tracks.js

@@ -0,0 +1,12 @@
+import { useMemo } from "react";
+import { buildShotCameraTracks, castAimPoint, followSubjectTrack } from "./camera-direction.js";
+
+/** The per-frame follow/rail camera of every shot (camera-direction.js), rebuilt
+ * when the shots, the subject's path or the cast a rail aims at change. */
+export function useShotCameraTracks({ shots, subjectTrack, subjectId, fps, yawDeg, filmback, characters, objects, frameCount, activeId, motion }) {
+	return useMemo(() => {
+		if (!subjectTrack) return null;
+		const cast = { characters, objects, shots, frameCount, fps, clipOf: (entry) => (entry.id === activeId ? motion : entry.sessionMotion) };
+		return buildShotCameraTracks({ shots, subjectTrack: followSubjectTrack(subjectTrack, subjectId, cast), fps, yawDeg, filmback, aimAt: (id, frame) => castAimPoint(id, frame, cast) });
+	}, [shots, subjectTrack, subjectId, fps, yawDeg, filmback, characters, objects, frameCount, activeId, motion]);
+}

package/src/view-ghosts.js

@@ -0,0 +1,97 @@
+// Onion-skin ghosts: translucent poses of the active character's take before and after the
+// playhead, an editor overlay (ghost-set.js draws them on GIZMO_LAYER). This module holds the
+// viewer setting (transient like the View menu: never saved, never undone) and the pure choices:
+// which frames get a ghost and how each one looks.
+import { useSyncExternalStore } from "react";
+import { expandUse } from "./motion3/skills/index.js";
+import { skeletonFor } from "./motion3/rigs/index.js";
+import { motionScene } from "./motion3/scene.js";
+
+/** off; step: every `step` frames; keys: the take spec's key frames nearest the playhead. */
+export const GHOST_MODES = Object.freeze(["off", "step", "keys"]);
+export const GHOST_COUNT = Object.freeze({ min: 1, max: 6 });
+export const GHOST_STEP = Object.freeze({ min: 1, max: 24 });
+const GHOST_DEFAULTS = Object.freeze({ mode: "off", count: 3, step: 4 });
+/** Past poses cool, future poses warm. */
+export const GHOST_COLORS = Object.freeze({ before: "#4d9cff", after: "#ff8a3d" });
+const NEAR_OPACITY = 0.46, FAR_OPACITY = 0.14;
+
+const clampInt = (value, { min, max }, fallback) => (Number.isFinite(value) ? Math.max(min, Math.min(max, Math.round(value))) : fallback);
+
+/** A full, valid setting from a partial one (unknown modes keep the current mode). */
+export function normalizeGhostSettings(patch = {}, base = GHOST_DEFAULTS) {
+	return Object.freeze({
+		mode: GHOST_MODES.includes(patch.mode) ? patch.mode : base.mode,
+		count: clampInt(patch.count, GHOST_COUNT, base.count),
+		step: clampInt(patch.step, GHOST_STEP, base.step),
+	});
+}
+
+let current = GHOST_DEFAULTS;
+const listeners = new Set();
+export const ghostSettings = () => current;
+export function setGhostSettings(patch) {
+	const next = normalizeGhostSettings(patch, current);
+	if (next.mode === current.mode && next.count === current.count && next.step === current.step) return current;
+	current = next;
+	for (const listener of listeners) listener();
+	return current;
+}
+/** What a views contact sheet draws (verify_result ghosts): the viewport's setting while it is on, else 3 each side every 4 frames. */
+export const sheetGhostSettings = () => (current.mode === "off" ? { ...GHOST_DEFAULTS, mode: "step" } : current);
+const subscribe = (listener) => { listeners.add(listener); return () => listeners.delete(listener); };
+export const useGhostSettings = () => useSyncExternalStore(subscribe, ghostSettings, ghostSettings);
+
+/** One sentence for receipts and tooltips. */
+export function describeGhosts({ mode, count, step }) {
+	if (mode === "off") return "Ghosts off.";
+	return `Ghosts: ${count} before and ${count} after the playhead, ${mode === "keys" ? "at the spec's key frames" : `every ${step} frame${step === 1 ? "" : "s"}`}.`;
+}
+
+/**
+ * The frames that get a ghost around `frame` within 0..last: `count` on each side, every `step`
+ * frames, or the nearest of `keyFrames` (mode keys). rank 1 is the nearest; the playhead's own
+ * frame never gets one.
+ */
+export function ghostFrames({ frame, last, mode, count, step, keyFrames = [] }) {
+	if (mode === "off" || !(last >= 0)) return [];
+	const at = Math.max(0, Math.min(last, Math.round(frame) || 0)), out = [];
+	const keys = mode === "keys" ? [...new Set(keyFrames.map(Math.round))].filter((f) => f >= 0 && f <= last).sort((x, y) => x - y) : null;
+	const before = keys ? keys.filter((f) => f < at).reverse() : null, after = keys ? keys.filter((f) => f > at) : null;
+	for (let rank = 1; rank <= count; rank++) {
+		const early = keys ? before[rank - 1] : at - rank * step, late = keys ? after[rank - 1] : at + rank * step;
+		if (early >= 0) out.push({ f: early, side: "before", rank });
+		if (late <= last) out.push({ f: late, side: "after", rank });
+	}
+	return out;
+}
+
+/** Colour and opacity of a ghost: its side's hue, fading with its distance in time. */
+export function ghostLook(side, rank, count) {
+	const t = count > 1 ? (rank - 1) / (count - 1) : 0;
+	return { color: GHOST_COLORS[side], opacity: +(NEAR_OPACITY + (FAR_OPACITY - NEAR_OPACITY) * t).toFixed(3) };
+}
+
+const keyCache = new WeakMap();
+/**
+ * The key frames of an installed take v3: its spec's keys with the skills it uses expanded
+ * (expandUse, lenient), the held-object keys and each generator's start, ascending. A retimed
+ * take (fix.retime) is not remapped: these are the spec's frames. [] for anything else.
+ */
+export function takeKeyFrames(take, objects = []) {
+	if (take?.schema !== "cozyclay.take.v3" || !take.spec) return [];
+	if (keyCache.has(take)) return keyCache.get(take);
+	let spec = take.spec;
+	try {
+		const sk = skeletonFor(take.rig);
+		if (sk && spec.use?.length) spec = expandUse(spec, { sk, scene: motionScene(objects), lenient: true }).spec;
+	} catch { spec = take.spec; }
+	const frames = [
+		...(spec.keys ?? []).map((k) => k?.f),
+		...Object.values(spec.objects ?? {}).flatMap((o) => (Array.isArray(o?.keys) ? o.keys.map((k) => k?.f) : [])),
+		...(spec.generators ?? []).map((g) => g?.f0),
+	].filter(Number.isFinite);
+	const keys = [...new Set(frames.map(Math.round))].sort((a, b) => a - b);
+	keyCache.set(take, keys);
+	return keys;
+}

package/src/view-ghosts.jsx

@@ -0,0 +1,49 @@
+// The viewport's onion-skin ghosts (ghost-set.js) of the active character's take v3. They live on
+// GIZMO_LAYER: the working views draw them, while the shot preview card, PlayView, captures,
+// contact sheets and exports never do. Off by default; view.setGhosts and the View menu's Ghosts
+// group turn them on (view-ghosts.js holds that setting).
+import { useEffect, useMemo } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { GIZMO_LAYER } from "./dualview.jsx";
+import { GhostSet } from "./ghost-set.js";
+import { isTakeV3 } from "./motion3/playback.js";
+import { ghostFrames, takeKeyFrames, useGhostSettings } from "./view-ghosts.js";
+
+// Kit parts mount in the same commit as a take or record change, sometimes a frame later: the
+// carried meshes are collected again on the next frames too.
+const SOURCE_PASSES = 3;
+
+/**
+ * rig: the active character's live rig; take: its installed motion; frame: the playhead;
+ * objects: the authored records; propTake: { frameCount, fps, objectTracks } as SetProps gets it.
+ */
+export function ViewGhosts({ rig, take, frame, objects, propTake }) {
+	const settings = useGhostSettings();
+	const scene = useThree((state) => state.scene), gl = useThree((state) => state.gl), invalidate = useThree((state) => state.invalidate);
+	const set = useMemo(() => new GhostSet({ layer: GIZMO_LAYER }), []);
+	const on = settings.mode !== "off" && !!rig && isTakeV3(take);
+	const keyFrames = useMemo(() => (on && settings.mode === "keys" ? takeKeyFrames(take, objects) : []), [on, settings.mode, take, objects]);
+	const entries = useMemo(() => (on ? ghostFrames({ frame, last: take.frameCount - 1, ...settings, keyFrames }) : []),
+		[on, frame, take, settings, keyFrames]);
+	useEffect(() => {
+		if (!on) return undefined;
+		scene.add(set.object);
+		return () => { scene.remove(set.object); };
+	}, [on, scene, set]);
+	useEffect(() => () => set.dispose(), [set]);
+	// The canvas may render on demand: a new ghost frame set is a reason to draw.
+	useEffect(() => { invalidate(); }, [invalidate, on, entries]);
+	useEffect(() => {
+		// QA hook (test/qa-view-ghosts-browser.mjs): the live set and the renderer it draws with.
+		if (typeof window !== "undefined") window.__cozyclayGhosts = { set, gl, scene, entries };
+	}, [set, gl, scene, entries]);
+	useFrame(() => {
+		// A rig that left the stage (a hidden cast member) keeps no ghosts on it.
+		if (!set.show(on && !!rig.parent)) return;
+		set.setRig(rig);
+		set.syncSources(scene, objects, take, SOURCE_PASSES);
+		rig.parent.updateWorldMatrix(true, false);
+		set.update({ entries, take, placement: rig.parent.matrixWorld, propTake, objects, count: settings.count });
+	});
+	return null;
+}