cozyclay 1.0.0 → 1.2.0

package/src/cuts.js

@@ -0,0 +1,184 @@
+// Pure optional Shot-overlay model. Shots are camera ownership cards placed
+// on a timeline: gaps are valid free-camera time, overlaps are rejected.
+
+import { cameraMoveAt } from "./camera-move.js";
+import { cloneCameraBlock, createCameraBlock } from "./camera-block.js";
+
+export const DEFAULT_SHOT_FRAMES = 40;
+
+let nextShotId = 1;
+const id = () => `shot-${Date.now().toString(36)}-${nextShotId++}`;
+const frameNumber = (value, fallback = 0) => Number.isFinite(value) ? Math.round(value) : fallback;
+
+function cloneFraming(framing) {
+	return framing ? { ...framing, pos: framing.pos ? { ...framing.pos } : framing.pos } : framing;
+}
+
+function uniqueKeys(keys, min = -Infinity, max = Infinity) {
+	const byFrame = new Map();
+	for (const key of Array.isArray(keys) ? keys : []) {
+		if (!key || !Number.isFinite(key.frame) || !key.framing) continue;
+		const frame = Math.max(min, Math.min(max, Math.round(key.frame)));
+		byFrame.set(frame, { frame, framing: cloneFraming(key.framing) });
+	}
+	return [...byFrame.values()].sort((a, b) => a.frame - b.frame);
+}
+
+export function createShot(name = "Shot", startFrame = 0, endFrame = startFrame + DEFAULT_SHOT_FRAMES - 1, cameraKeys = [], camera = null) {
+	const start = Math.max(0, frameNumber(startFrame));
+	const end = Math.max(start, frameNumber(endFrame, start));
+	return {
+		id: id(),
+		name: typeof name === "string" && name.trim() ? name.trim() : "Shot",
+		startFrame: start,
+		endFrame: end,
+		cameraKeys: uniqueKeys(cameraKeys, start, end),
+		camera: createCameraBlock(camera),
+	};
+}
+
+/** New documents begin without an implicit camera owner. */
+export function initialShots() {
+	return [];
+}
+
+export function shotIndexAtFrame(shots, frame) {
+	if (!Array.isArray(shots) || !shots.length) return -1;
+	const target = Math.max(0, frameNumber(frame));
+	let low = 0;
+	let high = shots.length - 1;
+	while (low <= high) {
+		const middle = Math.floor((low + high) / 2);
+		const shot = shots[middle];
+		if (target < shot.startFrame) high = middle - 1;
+		else if (target > shot.endFrame) low = middle + 1;
+		else return middle;
+	}
+	return -1;
+}
+
+export function shotAtFrame(shots, frame) {
+	const index = shotIndexAtFrame(shots, frame);
+	return index < 0 ? null : shots[index];
+}
+
+function overlaps(shots, startFrame, endFrame, ignoredIndex = -1) {
+	return shots.some((shot, index) => index !== ignoredIndex && startFrame <= shot.endFrame && endFrame >= shot.startFrame);
+}
+
+/** Split only the Shot that actually covers the cut frame. Gap frames remain gaps. */
+export function cutAtFrame(shots, frame, currentFraming) {
+	if (!Array.isArray(shots) || !currentFraming) return shots;
+	const cutFrame = frameNumber(frame);
+	const index = shotIndexAtFrame(shots, cutFrame);
+	if (index < 0) return shots;
+	const source = shots[index];
+	if (cutFrame <= source.startFrame || cutFrame > source.endFrame) return shots;
+	const upstream = {
+		...source,
+		endFrame: cutFrame - 1,
+		cameraKeys: uniqueKeys(source.cameraKeys, source.startFrame, cutFrame - 1),
+		camera: cloneCameraBlock(source.camera),
+	};
+	const downstream = createShot(`Shot ${shots.length + 1}`, cutFrame, source.endFrame, [
+		...source.cameraKeys.filter((key) => key.frame >= cutFrame),
+		{ frame: cutFrame, framing: currentFraming },
+	], source.camera);
+	return [...shots.slice(0, index), upstream, downstream, ...shots.slice(index + 1)];
+}
+
+/**
+ * Add a 2-second Shot without editing an existing one. If the playhead is
+ * occupied, place the new card in the next full-size free range instead. Add
+ * and Split are separate editorial actions: hanging a new card on the board
+ * must never cut the card already there.
+ */
+export function addShotAtFrame(shots, frame, frameCount, currentFraming, duration = DEFAULT_SHOT_FRAMES) {
+	const list = Array.isArray(shots) ? shots : [];
+	const count = Math.max(1, frameNumber(frameCount, 1));
+	const target = Math.max(0, Math.min(count - 1, frameNumber(frame)));
+	const inside = shotIndexAtFrame(list, target);
+	if (inside >= 0) {
+		const source = list[inside];
+		const length = Math.max(1, frameNumber(duration, DEFAULT_SHOT_FRAMES));
+		const startFrame = freeStart(list, length, count, source.endFrame + 1);
+		if (startFrame === undefined) return list;
+		const keys = currentFraming ? [{ frame: startFrame, framing: currentFraming }] : [];
+		return [...list, createShot(`Shot ${list.length + 1}`, startFrame, startFrame + length - 1, keys)].sort((a, b) => a.startFrame - b.startFrame);
+	}
+	const nextStart = list.find((shot) => shot.startFrame > target)?.startFrame ?? count;
+	const endFrame = Math.min(count - 1, nextStart - 1, target + Math.max(1, frameNumber(duration, DEFAULT_SHOT_FRAMES)) - 1);
+	if (endFrame < target || overlaps(list, target, endFrame)) return list;
+	const keys = currentFraming ? [{ frame: target, framing: currentFraming }] : [];
+	return [...list, createShot(`Shot ${list.length + 1}`, target, endFrame, keys)].sort((a, b) => a.startFrame - b.startFrame);
+}
+
+export function resizeShot(shots, index, edge, rawFrame, frameCount) {
+	if (!Array.isArray(shots) || index < 0 || index >= shots.length || (edge !== "start" && edge !== "end")) return shots;
+	const count = Math.max(1, frameNumber(frameCount, 1));
+	const shot = shots[index];
+	const frame = Math.max(0, Math.min(count - 1, frameNumber(rawFrame, edge === "start" ? shot.startFrame : shot.endFrame)));
+	const startFrame = edge === "start" ? Math.min(frame, shot.endFrame) : shot.startFrame;
+	const endFrame = edge === "end" ? Math.max(frame, shot.startFrame) : shot.endFrame;
+	if ((startFrame === shot.startFrame && endFrame === shot.endFrame) || overlaps(shots, startFrame, endFrame, index)) return shots;
+	const next = shots.slice();
+	next[index] = { ...shot, startFrame, endFrame, cameraKeys: uniqueKeys(shot.cameraKeys, startFrame, endFrame) };
+	return next.sort((a, b) => a.startFrame - b.startFrame);
+}
+
+/** Compatibility name for callers that move the left edge. */
+export function moveBoundary(shots, index, newStartFrame, frameCount) {
+	return resizeShot(shots, index, "start", newStartFrame, frameCount);
+}
+
+export function removeShot(shots, index) {
+	if (!Array.isArray(shots) || index < 0 || index >= shots.length) return shots;
+	return shots.filter((_, shotIndex) => shotIndex !== index);
+}
+
+export function renameShot(shots, index, name) {
+	if (!Array.isArray(shots) || index < 0 || index >= shots.length || typeof name !== "string" || !name.trim()) return shots;
+	return shots.map((shot, shotIndex) => shotIndex === index ? { ...shot, name: name.trim() } : shot);
+}
+
+/** Move a card in absolute time. Duration and local camera instruction travel together. */
+export function reorderShot(shots, fromIndex, rawStartFrame, frameCount) {
+	if (!Array.isArray(shots) || fromIndex < 0 || fromIndex >= shots.length) return shots;
+	const shot = shots[fromIndex];
+	const count = Math.max(1, frameNumber(frameCount, 1));
+	const duration = shot.endFrame - shot.startFrame + 1;
+	const startFrame = Math.max(0, Math.min(count - duration, frameNumber(rawStartFrame, shot.startFrame)));
+	const endFrame = startFrame + duration - 1;
+	if (startFrame === shot.startFrame || overlaps(shots, startFrame, endFrame, fromIndex)) return shots;
+	const delta = startFrame - shot.startFrame;
+	const moved = {
+		...shot,
+		startFrame,
+		endFrame,
+		cameraKeys: uniqueKeys(shot.cameraKeys.map((key) => ({ ...key, frame: key.frame + delta })), startFrame, endFrame),
+	};
+	return shots.map((entry, index) => index === fromIndex ? moved : entry).sort((a, b) => a.startFrame - b.startFrame);
+}
+
+function freeStart(shots, duration, frameCount, preferred) {
+	const candidates = [preferred, 0, ...shots.map((shot) => shot.endFrame + 1)];
+	return candidates.find((start) => start >= 0 && start + duration <= frameCount && !overlaps(shots, start, start + duration - 1));
+}
+
+export function duplicateShot(shots, index, frameCount) {
+	if (!Array.isArray(shots) || index < 0 || index >= shots.length) return shots;
+	const source = shots[index];
+	const duration = source.endFrame - source.startFrame + 1;
+	const startFrame = freeStart(shots, duration, Math.max(1, frameNumber(frameCount, 1)), source.endFrame + 1);
+	if (startFrame === undefined) return shots;
+	const delta = startFrame - source.startFrame;
+	const duplicate = createShot(`${source.name} copy`, startFrame, startFrame + duration - 1,
+		source.cameraKeys.map((key) => ({ ...key, frame: key.frame + delta })), source.camera);
+	return [...shots, duplicate].sort((a, b) => a.startFrame - b.startFrame);
+}
+
+/** Gaps deliberately return null; the caller interprets null as free camera. */
+export function cameraAtFrame(shots, anchor, frame) {
+	const shot = shotAtFrame(shots, frame);
+	return shot ? cameraMoveAt(shot.cameraKeys, anchor, frame) : null;
+}

package/src/generation/client.js

@@ -0,0 +1,56 @@
+const JSON_HEADERS = { "Content-Type": "application/json" };
+const TIMEOUT_MS = 5000;
+const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+
+async function requestJson(path, options = {}, timeoutMs = TIMEOUT_MS, retries = 0) {
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let response;
+    try {
+      response = await fetch(path, { ...options, signal });
+    } catch (error) {
+      if (options.signal?.aborted || attempt === retries) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 250 * (2 ** attempt)));
+      continue;
+    }
+    const payload = await response.json().catch(() => ({}));
+    if (response.ok) return payload;
+    if (!RETRYABLE.has(response.status) || attempt === retries) {
+      throw new Error(payload.reason || payload.errors?.[0] || `generation request failed (HTTP ${response.status})`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250 * (2 ** attempt)));
+  }
+}
+
+export async function checkGenerationBridge() {
+  try {
+    return await requestJson("/generation/health");
+  } catch (error) { return { ok: false, reason: error.message || "generation bridge unreachable" }; }
+}
+
+export async function listGenerationModels() {
+  const payload = await requestJson("/generation/models");
+  return Array.isArray(payload.models) ? payload.models : [];
+}
+
+export async function listGenerationJobs() {
+  const payload = await requestJson("/generation/jobs");
+  return Array.isArray(payload.jobs) ? payload.jobs : [];
+}
+
+export function validateGeneration(spec, { signal } = {}) {
+  return requestJson("/generation/validate", { method: "POST", headers: JSON_HEADERS, body: JSON.stringify(spec), signal });
+}
+
+export function submitGeneration(spec, { signal } = {}) {
+  return requestJson("/generation/jobs", { method: "POST", headers: JSON_HEADERS, body: JSON.stringify(spec), signal }, 30000, 2);
+}
+
+export function getGenerationJob(id, { signal } = {}) {
+  return requestJson(`/generation/jobs/${encodeURIComponent(id)}`, { signal }, 30000, 3);
+}
+
+export function cancelGenerationJob(id) {
+  return requestJson(`/generation/jobs/${encodeURIComponent(id)}`, { method: "DELETE" }, 30000, 1);
+}

package/src/generation/session.js

@@ -0,0 +1,47 @@
+import { cancelGenerationJob, getGenerationJob, submitGeneration, validateGeneration } from "./client.js";
+
+const TERMINAL = new Set(["succeeded", "failed"]);
+
+export async function runGeneration(spec, {
+  signal,
+  timeoutMs = 10 * 60 * 1000,
+  initialDelayMs = 5000,
+  maxDelayMs = 30000,
+  validate = validateGeneration,
+  submit = submitGeneration,
+  poll = getGenerationJob,
+  cancel = cancelGenerationJob,
+  sleep = (ms, waitSignal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    waitSignal?.addEventListener("abort", () => { clearTimeout(timer); reject(waitSignal.reason); }, { once: true });
+  }),
+  onUpdate = () => {},
+} = {}) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  const update = (state) => { onUpdate(state); return state; };
+  let job = null;
+  let validation = null;
+  try {
+    update({ status: "validating", job: null, error: null });
+    validation = await validate(spec, { signal: combined });
+    update({ status: "submitting", job: null, validation, error: null });
+    job = await submit(spec, { signal: combined });
+    update({ status: job.status, job, validation, error: null });
+    let delay = initialDelayMs;
+    while (!TERMINAL.has(job.status)) {
+      await sleep(delay, combined);
+      job = await poll(job.id, { signal: combined });
+      update({ status: job.status, job, validation, error: null });
+      delay = Math.min(maxDelayMs, Math.max(initialDelayMs, delay * 2));
+    }
+    if (job.status === "failed") throw new Error(job.failure || "generation failed");
+    return job;
+  } catch (error) {
+    const timedOut = timeout.aborted && !signal?.aborted;
+    const canceled = signal?.aborted;
+    if (canceled && job?.id) await cancel(job.id).catch(() => {});
+    update({ status: timedOut ? "timed_out" : canceled ? "canceled" : "failed", job, validation, error: error?.message || String(error) });
+    throw error;
+  }
+}

package/src/generation/shot-spec.js

@@ -0,0 +1,40 @@
+export const SHOT_SPEC_VERSION = 1;
+const SUPPORTED_RATIOS = new Set(["16:9", "9:16"]);
+
+export function generationDurationForShot(shot, fps = 20, supportedDurations = [5]) {
+  const rawSeconds = shot
+    ? Math.max(1, (Number(shot.endFrame) - Number(shot.startFrame) + 1) / Math.max(Number(fps) || 1, 1))
+    : 5;
+  const durations = (Array.isArray(supportedDurations) ? supportedDurations : [])
+    .map(Number)
+    .filter((duration) => Number.isInteger(duration) && duration > 0);
+  if (!durations.length) return Math.max(1, Math.min(30, Math.round(rawSeconds)));
+  return durations.reduce((closest, duration) => (
+    Math.abs(duration - rawSeconds) < Math.abs(closest - rawSeconds) ? duration : closest
+  ));
+}
+
+export function compileShotSpec({ provider = "runway", model, prompt, durationSeconds = 5, aspectRatio = "16:9", resolution = "720p", seed = null, startFrame = null, endFrame = null, referenceVideo = null, shot = null, camera = null, subjects = [] }) {
+  const duration = Math.round(Number(durationSeconds));
+  const spec = {
+    version: SHOT_SPEC_VERSION,
+    provider,
+    model,
+    prompt: String(prompt || "").trim(),
+    durationSeconds: duration,
+    aspectRatio: SUPPORTED_RATIOS.has(aspectRatio) ? aspectRatio : "16:9",
+    resolution,
+    seed: seed === "" || seed == null ? null : Number(seed),
+    shot: shot || null,
+    camera: camera || null,
+    subjects: Array.isArray(subjects) ? subjects : [],
+    conditioning: { startFrame, endFrame, referenceVideo },
+  };
+  const errors = [];
+  if (!spec.model) errors.push("model is required");
+  if (!spec.prompt) errors.push("prompt is required");
+  if (!Number.isInteger(spec.durationSeconds) || spec.durationSeconds < 1 || spec.durationSeconds > 30) errors.push("duration must be an integer between 1 and 30 seconds");
+  if (spec.seed !== null && (!Number.isInteger(spec.seed) || spec.seed < 0 || spec.seed > 4294967295)) errors.push("seed must be an integer in 0..4294967295");
+  if (errors.length) throw new Error(errors[0]);
+  return spec;
+}

package/src/generation/use-generation.js

@@ -0,0 +1,55 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { checkGenerationBridge, listGenerationJobs, listGenerationModels } from "./client.js";
+import { runGeneration } from "./session.js";
+import { compileShotSpec, generationDurationForShot } from "./shot-spec.js";
+
+const IDLE = { status: "idle", job: null, validation: null, error: null };
+
+export function useGeneration() {
+  const [models, setModels] = useState([]);
+  const [available, setAvailable] = useState(false);
+  const [state, setState] = useState(IDLE);
+  const [history, setHistory] = useState([]);
+  const abortRef = useRef(null);
+
+  useEffect(() => {
+    let live = true;
+    Promise.all([checkGenerationBridge(), listGenerationModels(), listGenerationJobs()]).then(([health, found, jobs]) => {
+      if (!live) return;
+      setAvailable(Boolean(health.ok && found.some((model) => model.available)));
+      setModels(found.filter((model) => model.available));
+      setHistory(jobs);
+    }).catch(() => { if (live) setAvailable(false); });
+    return () => { live = false; abortRef.current?.abort(); };
+  }, []);
+
+  const start = useCallback(async (input) => {
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    const spec = compileShotSpec(input);
+    try { return await runGeneration(spec, { signal: controller.signal, onUpdate: setState }); }
+    finally {
+      listGenerationJobs().then(setHistory).catch(() => {});
+      if (abortRef.current === controller) abortRef.current = null;
+    }
+  }, []);
+
+  const startResult = useCallback((result, model) => start({
+    provider: model.provider,
+    model: model.id,
+    prompt: result.prompt,
+    durationSeconds: generationDurationForShot(result.shot, result.fps, model.durations),
+    aspectRatio: "16:9",
+    resolution: "720p",
+    startFrame: result.frame,
+    endFrame: model.capabilities?.endFrame ? result.frameB : null,
+    shot: result.shot,
+    camera: result.camera,
+    subjects: result.subjects,
+  }), [start]);
+
+  const cancel = useCallback(() => abortRef.current?.abort(new Error("generation canceled")), []);
+  const reset = useCallback(() => setState(IDLE), []);
+  return { available, models, history, state, start, startResult, cancel, reset };
+}

package/src/hierarchy-model.js

@@ -1,8 +1,15 @@
+// The Hierarchy lists what EXISTS in the 3D scene — camera, characters
+// (with their rig groups, which have viewport handles), environment, props.
+// Workflow surfaces (shot settings, prompt, ARDY motion, prompt blocks,
+// root path, IK keys) are NOT scene entities: they live in the right
+// sidebar's Shot and Motion tabs, keyed by `sidebarTab` in App.jsx.
 export const HIERARCHY_NODES = [
 	{
+		// Keep the legacy selection id until App wiring moves to the document
+		// model; its visible role is a Scene, never an editorial Shot.
 		id: "shot",
-		label: "SHOT 01",
-		kind: "shot",
+		label: "SCENE 01",
+		kind: "scene",
 		children: [
 			{ id: "camera", label: "Camera", kind: "camera" },
 			{
@@ -15,17 +22,6 @@ export const HIERARCHY_NODES = [
 						label: "Character 1",
 						kind: "character",
 						children: [
-							{ id: "characterA.character", label: "Character", kind: "character" },
-							{
-								id: "characterA.motion",
-								label: "Motion",
-								kind: "motion",
-								children: [
-									{ id: "characterA.baseMotion", label: "Base Motion", kind: "clip" },
-									{ id: "characterA.promptBlocks", label: "Prompt Blocks", kind: "prompt" },
-									{ id: "characterA.ik", label: "IK Corrections", kind: "key" },
-								],
-							},
 							{
 								id: "characterA.rig",
 								label: "Rig",
@@ -46,13 +42,9 @@ export const HIERARCHY_NODES = [
 						label: "Character 2",
 						kind: "character",
 						optional: "showB",
-						children: [
-							{ id: "characterB.character", label: "Character", kind: "character" },
-						],
 					},
 				],
 			},
-			{ id: "rootPath", label: "Root Path", kind: "path" },
 			{ id: "environment", label: "Environment", kind: "environment" },
 			{ id: "props", label: "Props", kind: "props" },
 		],