cozyclay 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.8.0
+
+The Studio's chrome gets a research-backed cut: the same capabilities, a third
+fewer controls on screen at once, and one place for each of them. A first-time
+creator can now learn the camera inside the Studio itself, or on cozyclay.org
+before installing, and keep the scene they made. Video mocap gets a quality
+gate, and AI video takes are checked against the scene they were supposed to
+preserve.
+
+### Studio UI simplification
+
+- Simultaneously visible controls drop from 49 / 54 / 65 (Scene / Camera /
+  Motion mode) to 35 / 38 / 51, measured by `tools/qa/studio-control-count.mjs`
+  and recorded with the per-control rationale in `docs/studio-ui-ia.md`.
+- The top bar keeps five actions. One **Export ▾** menu leads with the keyframe
+  pack and folds the mp4, depth/normal passes, storyboard and blocking frame
+  under it; the three Record buttons and the inspector's duplicate FOV/Recenter
+  are gone. **Settings ▾** holds language and analytics.
+- **View ▾** on the viewport bar owns the reference grid, Auto Color and body
+  part colours; Move/Rotate/Scale stay on the transform strip only.
+- The scene switcher sits on the hierarchy's root row; the Projects… button,
+  the root fold caret and the Characters group row are removed and characters
+  sit directly under the scene.
+- Timeline motion tools (IK, Foot, Body, speed, Clear, take bar) render only in
+  Motion mode; Foot snap and Body contact appear only while IK is on.
+- The Scene/PlayView tabs are replaced by the viewport's look-through button:
+  it enters an explicit preview of the shot camera and Esc returns.
+- Selecting the camera switches to Camera mode; the Placement row appears in
+  Motion mode; Generate all waits for at least one prompt block.
+- The `advancedMode` / `beginnerMode` gates that had been hardcoded on are
+  removed.
+
+### Learn the camera
+
+- A seven-step camera tutorial runs inside the Studio: Look, Walk (W A S D
+  Q E), Dolly, Orbit, Shot, Rail, Play. Open it from Settings ▾ → Camera
+  tutorial or `/app/?tutorial=camera`; each step completes only when the
+  gesture actually happens, and the strip never takes the pointer.
+- cozyclay.org embeds a live Studio playground on a preset city block with the
+  same seven steps, a second demo reel, and leaner copy. The tutorial ends by
+  handing over `npx cozyclay --scene city-block`, which opens the local Studio
+  on that starter scene; starter scenes are also offered from the project
+  browser, and the visitor can download the scene they made.
+
+### Agent panel in the Studio
+
+- The Workflow page's Agent chat column is available in the Studio, toggled
+  from View ▾ → Panels → Agent panel or Cmd/Ctrl+B. It boots collapsed so the
+  mode budgets above are unchanged.
+
+### Video mocap and AI video takes
+
+- GVHMR is the only extraction backend; the bridge and the Studio return a
+  named error instead of silently falling back to browser MediaPipe.
+- GVHMR output goes through adaptive position/rotation stabilisation, explicit
+  contact correction, support-surface height (a chair lifts the motion), a
+  mocap quality gate, and scene calibration that survives restore. Palette
+  segmentation diagnostics are exposed for AI-rendered mannequin clips.
+- H3 video takes are checked against the requested scene and camera: the
+  Workflow shows a lock receipt on success and rejects a take whose background
+  or camera drifted, keeping no stale preview.
+
+### Site
+
+- Four search-facing pages (greybox to video, previs software, Seedance camera
+  control, privacy), `robots.txt` with an explicit AI-crawler policy,
+  `llms.txt`, a generated sitemap with real last-modified dates, and IndexNow
+  pings on deploy.
+
 ## 1.7.1
 
 - Open the complete Studio at the development server root; the unfinished

package/README.md

@@ -18,7 +18,9 @@
 </p>
 
 <p align="center">
-  <a href="https://cozyclay.org/">Demo reel</a> ·
+  <a href="https://cozyclay.org/#try">Try it in the browser</a> ·
+  <a href="https://cozyclay.org/greybox-to-video/">Greybox to AI video</a> ·
+  <a href="https://cozyclay.org/previs-software/">Previs software compared</a> ·
   <a href="#quick-start">Quick start</a> ·
   <a href="#what-you-can-do">Features</a> ·
   <a href="#ai-control-mcp">AI control</a> ·
@@ -34,7 +36,13 @@ CozyClay is a browser-based 3D staging studio built with Three.js and React Thre
 npx cozyclay
 ```
 
-That is the whole install. **[cozyclay.org](https://cozyclay.org/)** has the demo reel and a walkthrough of what the studio does; to use it, run it on your own machine. It ships seeded with a pre-generated motion clip, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away — generating *new* motion is optional and uses the Kimodo bridge when configured.
+That is the whole install. Not sure yet? **[Try it in the browser first](https://cozyclay.org/#try)** — a seven-step camera tutorial on a live scene — then keep going on your machine with the same set:
+
+```bash
+npx cozyclay --scene city-block
+```
+
+The studio ships seeded with a pre-generated motion clip, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away — generating *new* motion is optional and uses the Kimodo bridge when configured.
 
 ## Demo
 
@@ -65,7 +73,7 @@ npx cozyclay
 bunx cozyclay
 ```
 
-That downloads the built studio and opens it at `http://127.0.0.1:5180/app/`. Nothing to compile, no dependency tree to install. Useful flags: `--port 5200`, `--no-open`, `--no-motion`.
+That downloads the built studio and opens it at `http://127.0.0.1:5180/app/`. Nothing to compile, no dependency tree to install. Useful flags: `--port 5200`, `--no-open`, `--no-motion`, `--scene city-block` (start on the bundled starter scene instead of an empty room; the first-run dialog offers the same under **Start from a scene**, and a `.cclayproject` downloaded from the browser tutorial opens with **Open a project**).
 
 A global install gives you `cclay`, the same command with less typing. Once a day the launcher checks npm for a newer release and prints a one-line notice after the studio is up; it stays quiet when you're current or offline. `cclay update` installs the latest release, and `--no-update-check` skips the check entirely.
 

package/bin/agent/agent-routes.mjs

@@ -196,8 +196,14 @@ export function createAgentHandler({ auth = defaultAuth, codex, handlers, liveHu
 			if (!adapter || !adapter.configured()) { json(res, 409, { error: "video provider is not configured" }); return true; }
 			try {
 				const result = await adapter.generate({ ...value, durationSeconds: Number(value.durationSeconds) });
-				json(res, 200, { ...(result.mp4Base64 ? { dataUrl: `data:video/mp4;base64,${result.mp4Base64}` } : { url: result.url }), width: result.width, height: result.height, seconds: result.seconds });
-			} catch (error) { json(res, 502, { error: error?.message || "video provider failed" }); }
+				json(res, 200, { ...(result.mp4Base64 ? { dataUrl: `data:video/mp4;base64,${result.mp4Base64}` } : { url: result.url }), width: result.width, height: result.height, seconds: result.seconds, ...(result.preservation ? { preservation: result.preservation } : {}) });
+			} catch (error) {
+				// A generated H3 take that fails the plate check is unsafe to show as
+				// a locked shot. Keep the distinction visible to the client so it can
+				// ask for a retry instead of silently accepting a drifting set.
+				const status = error?.code === "h3-preservation-failed" ? 422 : 502;
+				json(res, status, { error: error?.message || "video provider failed", ...(error?.preservation ? { preservation: error.preservation } : {}) });
+			}
 			return true;
 		}
 		if (req.method !== "POST" || !["/agent/turn", "/agent/stop"].includes(path)) {

package/bin/agent/h3-preservation.mjs

@@ -0,0 +1,218 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+/**
+ * H3 is an image-to-video model: a prompt can request a locked camera, but it
+ * cannot prove that the returned pixels stayed on that camera.  This module
+ * is the output-side guard.  It compares several decoded frames with the
+ * uploaded plate in a border band where the animated performer normally is
+ * absent. A request is accepted only when the output dimensions/aspect and
+ * the measured plate drift are inside the contract.
+ */
+
+export const H3_OUTPUT_LIMITS = Object.freeze({
+	// JPEG/AVC quantisation and the model's first-frame reconstruction create a
+	// small amount of noise. A real camera move changes many edge pixels by much
+	// more than this value.
+	edgeP95Rgb: 14,
+	edgeMeanRgb: 6,
+	// The full-frame 80th percentile catches a camera translation in the
+	// middle of the set even when the border happens to be covered by a subject.
+	globalP80Rgb: 16,
+	// Once the output's first decoded frame has established the model's codec
+	// reconstruction, every later frame must keep the static scene band stable.
+	// This catches a camera move that happens to reconstruct to a similar value
+	// relative to the uploaded plate (and avoids treating subject motion as set
+	// motion).
+	temporalEdgeP95Rgb: 14,
+	temporalEdgeMeanRgb: 6,
+	temporalGlobalP80Rgb: 16,
+	cameraDriftPx: 2,
+	aspectError: 0.01,
+	borderFraction: 0.12,
+});
+
+/** Estimate a rigid camera translation against the plate in the static band. */
+export function estimateH3CameraShift(reference, frame, width, height, { borderFraction = H3_OUTPUT_LIMITS.borderFraction, maxShift = 4 } = {}) {
+	const borderX = Math.max(1, Math.floor(width * borderFraction));
+	const borderY = Math.max(1, Math.floor(height * borderFraction));
+	if (width <= borderX * 2 + 2 || height <= borderY * 2 + 2) return { x: 0, y: 0, errorRgb: 0, distancePx: 0 };
+	let best = { x: 0, y: 0, error: Infinity }; let baseline = Infinity;
+	for (let dy = -maxShift; dy <= maxShift; dy += 1) for (let dx = -maxShift; dx <= maxShift; dx += 1) {
+		let sum = 0; let count = 0;
+		for (let y = 0; y < height; y += 4) for (let x = 0; x < width; x += 4) {
+			// Estimate rigid movement only from the static perimeter. Sampling the
+			// interior lets a moving performer win the alignment search and can
+			// incorrectly call subject motion a camera correction.
+			if (!(x < borderX || x >= width - borderX || y < borderY || y >= height - borderY)) continue;
+			if (x + dx < 0 || x + dx >= width || y + dy < 0 || y + dy >= height) continue;
+			const a = (y * width + x) * 3; const b = ((y + dy) * width + x + dx) * 3;
+			sum += (Math.abs(reference[a] - frame[b]) + Math.abs(reference[a + 1] - frame[b + 1]) + Math.abs(reference[a + 2] - frame[b + 2])) / 3;
+			count += 1;
+		}
+		const error = sum / Math.max(1, count);
+		if (dx === 0 && dy === 0) baseline = error;
+		if (error < best.error) best = { x: dx, y: dy, error };
+	}
+	const improvementRgb = Math.max(0, baseline - best.error);
+	// A flat/softly lit border has many equally good translations. Only treat a
+	// shift as camera evidence when the alignment materially improves error.
+	const distancePx = improvementRgb >= 8 ? Math.hypot(best.x, best.y) : 0;
+	return { x: best.x, y: best.y, errorRgb: best.error, baselineErrorRgb: baseline, improvementRgb, distancePx };
+}
+
+/** Compare two generated frames in the static perimeter and full frame. */
+export function compareH3FrameStability(reference, frame, width, height, { borderFraction = H3_OUTPUT_LIMITS.borderFraction } = {}) {
+	if (!(reference instanceof Uint8Array) || !(frame instanceof Uint8Array) || reference.length < width * height * 3 || frame.length < width * height * 3) throw new TypeError("compareH3FrameStability needs two decoded RGB frames");
+	const borderX = Math.max(1, Math.floor(width * borderFraction));
+	const borderY = Math.max(1, Math.floor(height * borderFraction));
+	const edge = []; const global = [];
+	for (let y = 0; y < height; y += 2) for (let x = 0; x < width; x += 2) {
+		const i = (y * width + x) * 3;
+		const d = (Math.abs(reference[i] - frame[i]) + Math.abs(reference[i + 1] - frame[i + 1]) + Math.abs(reference[i + 2] - frame[i + 2])) / 3;
+		global.push(d);
+		if (x < borderX || x >= width - borderX || y < borderY || y >= height - borderY) edge.push(d);
+	}
+	edge.sort((a, b) => a - b); global.sort((a, b) => a - b);
+	const meanRgb = edge.reduce((sum, value) => sum + value, 0) / Math.max(1, edge.length);
+	const p95Rgb = edge[Math.min(edge.length - 1, Math.floor(edge.length * 0.95))] ?? 255;
+	const globalP80Rgb = global[Math.min(global.length - 1, Math.floor(global.length * 0.8))] ?? 255;
+	const camera = estimateH3CameraShift(reference, frame, width, height, { borderFraction });
+	return { meanRgb, p95Rgb, globalP80Rgb, cameraDriftPx: camera.distancePx, cameraShift: { x: camera.x, y: camera.y }, cameraErrorRgb: camera.errorRgb, cameraImprovementRgb: camera.improvementRgb, samples: edge.length, globalSamples: global.length };
+}
+
+function run(command, args, input = null) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+		const out = []; const err = [];
+		child.stdout.on("data", (chunk) => out.push(chunk));
+		child.stderr.on("data", (chunk) => err.push(chunk));
+		child.once("error", reject);
+		child.once("close", (code) => {
+			if (code === 0) resolve({ stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString("utf8") });
+			else reject(new Error(`${command} exited ${code}: ${Buffer.concat(err).toString("utf8").trim()}`));
+		});
+		if (input) child.stdin.end(input); else child.stdin.end();
+	});
+}
+
+async function decode(path, width, height, seek = null, inputFormat = null) {
+	const args = ["-hide_banner", "-loglevel", "error"];
+	if (inputFormat) args.push("-f", inputFormat);
+	args.push("-i", path);
+	// Place -ss after the input so ffmpeg decodes through the preceding GOP and
+	// returns the requested frame. Fast input seeking would repeatedly return
+	// the first keyframe on long-GOP H3 clips, making temporal camera drift look
+	// stable when it was never inspected.
+	if (seek !== null) args.push("-ss", String(Math.max(0, seek)));
+	args.push("-vf", `scale=${width}:${height}:flags=bicubic`, "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "pipe:1");
+	const { stdout } = await run("ffmpeg", args);
+	const expected = width * height * 3;
+	if (stdout.length < expected) throw new Error(`decoded frame is ${stdout.length} bytes; expected ${expected}`);
+	return stdout.subarray(0, expected);
+}
+
+async function decodeNearest(path, width, height, seek, duration) {
+	// Short test clips and variable frame rate outputs may have no frame at an
+	// arbitrary timestamp near the end. Walk backwards to the nearest decoded
+	// frame instead of treating a valid clip as an inspection failure.
+	for (let offset = 0; offset <= Math.max(1, duration); offset += 1 / 12) {
+		try { return await decode(path, width, height, Math.max(0, seek - offset)); } catch { /* try the preceding frame */ }
+	}
+	throw new Error("H3 output has no decodable video frame.");
+}
+
+async function probe(path) {
+	const { stdout } = await run("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height,duration,nb_frames,r_frame_rate", "-of", "json", path]);
+	const stream = JSON.parse(stdout.toString("utf8"))?.streams?.[0];
+	if (!stream || !Number.isFinite(Number(stream.width)) || !Number.isFinite(Number(stream.height))) throw new Error("H3 output has no video stream metadata.");
+	const [rateNumerator, rateDenominator] = String(stream.r_frame_rate || "").split("/").map(Number);
+	const fps = rateNumerator > 0 && rateDenominator > 0 ? rateNumerator / rateDenominator : null;
+	return { width: Number(stream.width), height: Number(stream.height), seconds: Number.isFinite(Number(stream.duration)) ? Number(stream.duration) : null, frames: Number.isFinite(Number(stream.nb_frames)) ? Number(stream.nb_frames) : null, fps };
+}
+
+/** Compare a decoded RGB frame to the plate. Returns mean and p95 RGB error. */
+export function compareH3Plate(reference, frame, width, height, { borderFraction = H3_OUTPUT_LIMITS.borderFraction } = {}) {
+	if (!(reference instanceof Uint8Array) || !(frame instanceof Uint8Array) || reference.length < width * height * 3 || frame.length < width * height * 3) throw new TypeError("compareH3Plate needs two decoded RGB frames");
+	const borderX = Math.max(1, Math.floor(width * borderFraction));
+	const borderY = Math.max(1, Math.floor(height * borderFraction));
+	const errors = []; const globalErrors = [];
+	for (let y = 0; y < height; y += 2) for (let x = 0; x < width; x += 2) {
+		const i = (y * width + x) * 3;
+		const d = (Math.abs(reference[i] - frame[i]) + Math.abs(reference[i + 1] - frame[i + 1]) + Math.abs(reference[i + 2] - frame[i + 2])) / 3;
+		globalErrors.push(d);
+		if (x < borderX || x >= width - borderX || y < borderY || y >= height - borderY) errors.push(d);
+	}
+	errors.sort((a, b) => a - b);
+	globalErrors.sort((a, b) => a - b);
+	const mean = errors.reduce((sum, value) => sum + value, 0) / Math.max(1, errors.length);
+	const p95 = errors[Math.min(errors.length - 1, Math.floor(errors.length * 0.95))] ?? 255;
+	const globalP80 = globalErrors[Math.min(globalErrors.length - 1, Math.floor(globalErrors.length * 0.8))] ?? 255;
+	const camera = estimateH3CameraShift(reference, frame, width, height, { borderFraction });
+	return { meanRgb: mean, p95Rgb: p95, globalP80Rgb: globalP80, cameraDriftPx: camera.distancePx, cameraShift: { x: camera.x, y: camera.y }, cameraErrorRgb: camera.errorRgb, cameraImprovementRgb: camera.improvementRgb, samples: errors.length, globalSamples: globalErrors.length };
+}
+
+/**
+ * Decode and validate an H3 output against the uploaded first frame. This is
+ * deliberately fail-closed: if ffmpeg/ffprobe cannot inspect the result, the
+ * caller must not present it as a scene-locked take.
+ */
+export async function inspectH3Output({ imageDataUrl, videoBytes, expectedWidth, expectedHeight, limits = H3_OUTPUT_LIMITS, compositorVerified = false }) {
+	if (!imageDataUrl?.startsWith("data:image/")) throw new Error("H3 preservation requires the uploaded first image.");
+	if (!Buffer.isBuffer(videoBytes) || videoBytes.length === 0) throw new Error("H3 preservation requires non-empty video bytes.");
+	const dir = await mkdtemp(join(tmpdir(), "cozyclay-h3-"));
+	const mime = /^data:([^;,]+)/.exec(imageDataUrl)?.[1] || "image/png";
+	const extension = mime.includes("jpeg") || mime.includes("jpg") ? "jpg" : mime.includes("webp") ? "webp" : "png";
+	const imagePath = join(dir, `plate.${extension}`); const videoPath = join(dir, "output.mp4");
+	try {
+		const match = /^data:[^;,]+;base64,(.+)$/.exec(imageDataUrl);
+		if (!match) throw new Error("H3 preservation received an invalid image data URL.");
+		await writeFile(imagePath, Buffer.from(match[1], "base64"));
+		await writeFile(videoPath, videoBytes);
+		const meta = await probe(videoPath);
+		const plateMeta = await probe(imagePath);
+		const width = meta.width; const height = meta.height;
+		// H3 may quantise the canvas to its own 32-pixel grid. The uploaded plate
+		// is the source of truth for a locked camera; accepting a second requested
+		// ratio would allow a crop/reframe to pass the preservation gate.
+		const plateAspect = Number(plateMeta.width) / Number(plateMeta.height);
+		const requestedAspect = Number(expectedWidth) / Number(expectedHeight);
+		const outputAspect = width / height;
+		const targetAspect = Number.isFinite(plateAspect) && plateAspect > 0 ? plateAspect : requestedAspect;
+		const aspectError = Number.isFinite(targetAspect) && targetAspect > 0 ? Math.abs(outputAspect - targetAspect) / targetAspect : 0;
+		if (aspectError > limits.aspectError) throw new Error(`H3 preservation failed: output aspect drift ${(aspectError * 100).toFixed(2)}%.`);
+		const reference = await decode(imagePath, width, height);
+		const duration = Number.isFinite(meta.seconds) && meta.seconds > 0 ? meta.seconds : 1;
+		// Container duration points just past the final decoded frame. Clamp all
+		// seeks to that frame so short clips (and VFR outputs) cannot fail closed
+		// merely because a probe sample landed in the tail gap.
+		const frameStep = Number.isFinite(meta.fps) && meta.fps > 0 ? 1 / meta.fps : 1 / 24;
+		const lastFrameTime = Math.max(0, duration - frameStep);
+		const times = [...new Set([0, lastFrameTime * 0.25, lastFrameTime * 0.5, lastFrameTime * 0.75, lastFrameTime])];
+		const frames = []; const decoded = [];
+		for (const time of times) {
+			const frame = await decodeNearest(videoPath, width, height, time, duration);
+			decoded.push(frame); frames.push(compareH3Plate(reference, frame, width, height, limits));
+		}
+		const temporal = decoded.slice(1).map((frame) => compareH3FrameStability(decoded[0], frame, width, height, limits));
+		const worst = frames.reduce((acc, item) => ({ meanRgb: Math.max(acc.meanRgb, item.meanRgb), p95Rgb: Math.max(acc.p95Rgb, item.p95Rgb), globalP80Rgb: Math.max(acc.globalP80Rgb, item.globalP80Rgb), cameraDriftPx: Math.max(acc.cameraDriftPx, item.cameraDriftPx) }), { meanRgb: 0, p95Rgb: 0, globalP80Rgb: 0, cameraDriftPx: 0 });
+		const temporalWorst = temporal.reduce((acc, item) => ({ meanRgb: Math.max(acc.meanRgb, item.meanRgb), p95Rgb: Math.max(acc.p95Rgb, item.p95Rgb), globalP80Rgb: Math.max(acc.globalP80Rgb, item.globalP80Rgb), cameraDriftPx: Math.max(acc.cameraDriftPx, item.cameraDriftPx) }), { meanRgb: 0, p95Rgb: 0, globalP80Rgb: 0, cameraDriftPx: 0 });
+		// A verified SAM3/ImageCompositeMasked graph owns the foreground mask and
+		// copies the uploaded plate into every non-subject pixel. In that mode a
+		// full-frame percentile would mistake legitimate actor motion for a set
+		// change (especially in close-up shots). Keep the hard perimeter checks for
+		// camera/background drift; retain full-frame checks for unverified callers.
+		const plateGlobalPass = compositorVerified || worst.globalP80Rgb <= limits.globalP80Rgb;
+		const temporalGlobalPass = compositorVerified || temporalWorst.globalP80Rgb <= limits.temporalGlobalP80Rgb;
+		const pass = worst.p95Rgb <= limits.edgeP95Rgb && worst.meanRgb <= limits.edgeMeanRgb && plateGlobalPass && worst.cameraDriftPx <= limits.cameraDriftPx && temporalWorst.p95Rgb <= limits.temporalEdgeP95Rgb && temporalWorst.meanRgb <= limits.temporalEdgeMeanRgb && temporalGlobalPass && temporalWorst.cameraDriftPx <= limits.cameraDriftPx;
+		return { pass, width, height, seconds: meta.seconds, aspectError, frames, temporal, worst, temporalWorst, compositorVerified, limits };
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+export async function inspectH3OutputFromData({ imageDataUrl, videoBytes, expectedWidth, expectedHeight, limits, compositorVerified = false }) {
+	return inspectH3Output({ imageDataUrl, videoBytes, expectedWidth, expectedHeight, limits, compositorVerified });
+}

package/bin/agent/video-adapters.mjs

@@ -1,7 +1,82 @@
+import { inspectH3Output } from "./h3-preservation.mjs";
+
 const COMFY_DEFAULT_WIDTH = 1024;
 const COMFY_DEFAULT_HEIGHT = 576;
 const MAX_INLINE_VIDEO = 24 * 1024 * 1024;
 
+export function comfyDimensionsForAspect(aspect) {
+	if (aspect === "9:16") return { width: 576, height: 1024 };
+	if (aspect === "1:1") return { width: 768, height: 768 };
+	// H3's latent canvas is quantized to 32-pixel axes; 1024x598 is not a
+	// valid canvas and makes MiniMaxH3ImageToVideo reject the graph.  1312x768
+	// is the nearest valid 12:7 canvas under H3's 768-short-edge pixel cap.
+	if (aspect === "12:7") return { width: 1312, height: 768 };
+	// Keep every axis on H3's 32-pixel latent grid. These are the closest
+	// representable canvases to the requested cinematic ratios.
+	if (aspect === "2.39:1") return { width: 1152, height: 480 };
+	if (aspect === "21:9") return { width: 1120, height: 480 };
+	if (aspect === "4:3") return { width: 768, height: 576 };
+	return { width: COMFY_DEFAULT_WIDTH, height: COMFY_DEFAULT_HEIGHT };
+}
+
+// MiniMax H3 is conditioned on the uploaded first frame, but the model is
+// still free to invent a new set or camera unless the contract is repeated in
+// every request. Keep this wording positive and structural: mentioning things
+// such as windows or curtains in a negative prompt has repeatedly caused H3 to
+// hallucinate those objects into the set.
+export const H3_PRESERVATION_CONTRACT =
+	"Treat the provided first image as an immutable scene plate for the entire video. Keep the exact background, floor, set geometry, lighting, horizon, lens, viewpoint, framing, and object positions unchanged from the first frame through the last frame. Animate only the foreground human subject. Use one continuous shot with a locked camera: no pan, tilt, orbit, dolly, zoom, crop, reframing, cut, transition, or time jump. Preserve all non-subject pixels and keep the subject's silhouette edges sharp. Motion priority: honor the requested subject action, including climbing, sitting, hanging, jumping, or any other vertical movement; never flatten that movement or force the subject to remain on the floor. This subject-motion rule changes only the performer, never the scene plate or camera.";
+
+export function isH3Workflow(workflow) {
+	let found = false;
+	const walk = (value) => {
+		if (found || !value || typeof value !== "object") return;
+		if (typeof value.class_type === "string" && /minimax.?h3|h3.*video/i.test(value.class_type)) found = true;
+		for (const [key, child] of Object.entries(value)) {
+			if (key !== "prompt" && typeof child === "string" && /minimax.?h3|h3.*video/i.test(child)) found = true;
+			else if (key !== "prompt") walk(child);
+		}
+	};
+	walk(workflow);
+	return found;
+}
+
+export function buildH3LockedPrompt(prompt) {
+	const source = String(prompt ?? "").trim();
+	if (!source) return H3_PRESERVATION_CONTRACT;
+	if (source.includes("immutable scene plate for the entire video")) return source;
+	return `${source}\n\n${H3_PRESERVATION_CONTRACT}`;
+}
+
+/** A Comfy API link is [node id, output index]. A truthy value in
+ * `first_frame` is not enough: a stale graph can point H3 at an empty latent
+ * or another generated image while a separate LoadImage node sits unused.
+ * Follow the link back to the LoadImage node that the adapter will rewrite to
+ * the uploaded clay frame. This makes the upload and the H3 condition one
+ * connected path, like checking that a film reel is actually threaded through
+ * the projector rather than merely present on the desk. */
+function hasFirstFrameCondition(workflow) {
+	if (!isH3Workflow(workflow)) return true;
+	const nodes = workflow && typeof workflow === "object" ? workflow : {};
+	const refId = (value) => Array.isArray(value) && typeof value[0] === "string" ? value[0] : null;
+	const reachesLoadImage = (id, visiting = new Set()) => {
+		if (!id || visiting.has(id)) return false;
+		const node = nodes[id];
+		if (!node || typeof node !== "object") return false;
+		if (/loadimage/i.test(String(node.class_type || "")) && typeof node.inputs?.image === "string" && node.inputs.image.trim()) return true;
+		// Keep each link traversal independent. A dead branch must not mark a
+		// shared node as visited and hide a later valid path to LoadImage.
+		const nextVisiting = new Set(visiting);
+		nextVisiting.add(id);
+		return Object.values(node.inputs || {}).some((value) => reachesLoadImage(refId(value), nextVisiting));
+	};
+	return Object.values(nodes).some((node) => {
+		if (!node || typeof node !== "object" || !/minimax.?h3|h3.*video/i.test(String(node.class_type || ""))) return false;
+		const value = (node.inputs || {}).first_frame ?? (node.inputs || {}).image;
+		return reachesLoadImage(refId(value));
+	});
+}
+
 const sleep = (ms, signal) => new Promise((resolve, reject) => {
 	if (signal?.aborted) return reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
 	const timer = setTimeout(resolve, ms);
@@ -33,18 +108,131 @@ function findDimensions(value, fallbackWidth, fallbackHeight) {
 	return { width, height, seconds };
 }
 
-function replaceWorkflowInputs(value, prompt, imageName, width, height) {
-	if (Array.isArray(value)) return value.map((item) => replaceWorkflowInputs(item, prompt, imageName, width, height));
+function preferredVideoOutputNodes(workflow) {
+	return new Set(Object.entries(workflow || {})
+		.filter(([, node]) => /savevideo|videocombine|videooutput/i.test(String(node?.class_type || "")))
+		.map(([id]) => id));
+}
+
+const isH3Node = (node) => /minimax.?h3|h3.*video/i.test(String(node?.class_type || ""));
+const isLoadImageNode = (node) => /loadimage/i.test(String(node?.class_type || ""));
+const isCompositeNode = (node) => /imagecomposite|compositeimage|imagemattecomposite/i.test(String(node?.class_type || ""));
+const isMaskNode = (node) => {
+	if (isCompositeNode(node)) return false;
+	// A generic/static mask can hide a broken tracker and would not preserve a
+	// moving performer across frames. Only accept a temporal SAM3/tracked-mask
+	// node on the compositor path.
+	return /sam3[_-]?(videotrack|tracktomask)|tracktomask|videomask/i.test(String(node?.class_type || ""));
+};
+
+function h3GuardError(message, reason) {
+	return Object.assign(new Error(message), {
+		code: "h3-preservation-failed",
+		preservation: { pass: false, reason },
+	});
+}
+
+function linkedNodeIds(value, result = []) {
+	if (Array.isArray(value)) {
+		if (typeof value[0] === "string") result.push(value[0]);
+		else for (const child of value) linkedNodeIds(child, result);
+	} else if (value && typeof value === "object") {
+		for (const child of Object.values(value)) linkedNodeIds(child, result);
+	}
+	return result;
+}
+
+function reachesNode(nodes, startId, predicate, visiting = new Set()) {
+	if (!startId || visiting.has(startId)) return false;
+	const node = nodes?.[startId];
+	if (!node || typeof node !== "object") return false;
+	if (predicate(node)) return true;
+	const nextVisiting = new Set(visiting);
+	nextVisiting.add(startId);
+	return Object.values(node.inputs || {}).some((value) => linkedNodeIds(value).some((id) => reachesNode(nodes, id, predicate, nextVisiting)));
+}
+
+/**
+ * H3 itself is an image-to-video sampler and cannot guarantee that generated
+ * pixels outside the performer stay unchanged. A valid production graph must
+ * therefore composite the generated subject over the uploaded plate before
+ * its final video writer. Keep this structural check alongside the pixel
+ * validator: the pixel check catches a bad run, while this check prevents a
+ * graph with no deterministic preservation stage from running at all.
+ */
+export function hasH3SceneComposite(workflow, outputNodeIds) {
+	const nodes = workflow && typeof workflow === "object" ? workflow : {};
+	const outputIds = [...(outputNodeIds || [])].map(String);
+	if (!outputIds.length) return { pass: false, outputs: [] };
+	const checkOutput = (outputId) => {
+		const compositors = new Set();
+		const collect = (id, visiting = new Set()) => {
+			if (!id || visiting.has(id)) return;
+			const node = nodes[id];
+			if (!node || typeof node !== "object") return;
+			if (isCompositeNode(node)) compositors.add(String(id));
+			const nextVisiting = new Set(visiting);
+			nextVisiting.add(id);
+			for (const value of Object.values(node.inputs || {})) for (const linkedId of linkedNodeIds(value)) collect(linkedId, nextVisiting);
+		};
+		collect(outputId);
+		for (const compositorId of compositors) {
+			const node = nodes[compositorId];
+			const entries = Object.entries(node.inputs || {});
+			const background = entries.filter(([key]) => /destination|background|plate|base/i.test(key));
+			const source = entries.filter(([key]) => /source|foreground|overlay|subject|image2|video/i.test(key));
+			const mask = entries.filter(([key]) => /mask|alpha|matte/i.test(key));
+			const reaches = (entries, predicate) => entries.some(([, value]) => linkedNodeIds(value).some((id) => reachesNode(nodes, id, predicate)));
+			// A TrackToMask node by itself is not proof of a subject mask: a stale
+			// graph can feed it unrelated track data (or a static all-white mask).
+			// Require its SAM3_VideoTrack input to be derived from the H3 frames so
+			// the compositor cannot silently paste an untracked/generated scene.
+			const reachesTrackedMask = (id, visiting = new Set()) => {
+				if (!id || visiting.has(id)) return false;
+				const candidate = nodes[id];
+				if (!candidate || typeof candidate !== "object") return false;
+				const nextVisiting = new Set(visiting);
+				nextVisiting.add(id);
+				if (/sam3[_-]?videotrack/i.test(String(candidate.class_type || ""))) {
+					return linkedNodeIds(candidate.inputs?.images).some((imageId) => reachesNode(nodes, imageId, isH3Node));
+				}
+				if (/sam3[_-]?tracktomask/i.test(String(candidate.class_type || ""))) {
+					return linkedNodeIds(candidate.inputs?.track_data).some((trackId) => reachesTrackedMask(trackId, nextVisiting));
+				}
+				return Object.values(candidate.inputs || {}).some((value) => linkedNodeIds(value).some((linkedId) => reachesTrackedMask(linkedId, nextVisiting)));
+			};
+			const hasTrackedMask = mask.some(([, value]) => linkedNodeIds(value).some((id) => reachesTrackedMask(id)));
+			if (reaches(background, isLoadImageNode) && reaches(source, isH3Node) && hasTrackedMask) {
+				return { pass: true, outputId, compositorId, classType: String(node.class_type || "") };
+			}
+		}
+		return { pass: false, outputId };
+	};
+	const outputs = outputIds.map(checkOutput);
+	return { pass: outputs.every((output) => output.pass), outputs, ...(outputs.length === 1 ? outputs[0] : {}) };
+}
+
+function replaceWorkflowInputs(value, prompt, imageName, width, height, { h3Only = false, h3Context = false } = {}) {
+	if (Array.isArray(value)) return value.map((item) => replaceWorkflowInputs(item, prompt, imageName, width, height, { h3Only, h3Context }));
 	if (!value || typeof value !== "object") {
 		if (typeof value !== "string") return value;
 		if (/PROMPT|paste your/i.test(value)) return prompt;
 		return value;
 	}
 	const output = {};
+	const h3Node = /minimax.?h3|h3.*video/i.test(String(value.class_type || ""));
+	// The prompt lives under the H3 node's `inputs` object in API exports. Carry
+	// a narrow target flag into that child object, while leaving prompts on
+	// unrelated SAM3/tracker nodes untouched.
+	const targetH3Prompt = h3Context || h3Node;
 	for (const [key, item] of Object.entries(value)) {
 		if (key === "image" && typeof item === "string" && /loadimage/i.test(String(value.class_type || ""))) output[key] = imageName;
+		// Workflow exports often contain a real example sentence rather than the
+		// literal PROMPT marker. Replace every node prompt so the H3 preservation
+		// contract cannot be bypassed by a stale saved sentence.
+		else if (key === "prompt" && typeof item === "string" && (!h3Only || targetH3Prompt)) output[key] = prompt;
 		else if ((key === "length" || key === "width" || key === "height") && Number.isInteger(Number(item))) output[key] = key === "length" ? Number(item) : (key === "width" ? width : height);
-		else output[key] = replaceWorkflowInputs(item, prompt, imageName, width, height);
+		else output[key] = replaceWorkflowInputs(item, prompt, imageName, width, height, { h3Only, h3Context: targetH3Prompt });
 	}
 	return output;
 }
@@ -52,21 +240,35 @@ function replaceWorkflowInputs(value, prompt, imageName, width, height) {
 function createComfy(env, fetchImpl) {
 	const base = env.COZYCLAY_COMFY_URL?.replace(/\/$/, "");
 	const workflowPath = env.COZYCLAY_COMFY_WORKFLOW;
-	let workflow;
 	return {
 		id: "comfy", name: "ComfyUI",
 		configured: () => Boolean(base && workflowPath),
 		async generate({ prompt, imageDataUrl, durationSeconds, aspect, fps = 24, signal }) {
-			if (!workflow) workflow = JSON.parse(await (await import("node:fs/promises")).readFile(workflowPath, "utf8"));
+			// Read the graph for every request. Comfy users commonly save a new
+			// H3 graph (for example, after adding the compositor lock) while this
+			// server stays alive; caching would silently keep submitting the old
+			// topology and bypass the current first-frame/output contract.
+			const workflow = JSON.parse(await (await import("node:fs/promises")).readFile(workflowPath, "utf8"));
+			const h3 = isH3Workflow(workflow);
+			const preferredOutputs = h3 ? preferredVideoOutputNodes(workflow) : new Set();
+			if (h3 && !hasFirstFrameCondition(workflow)) {
+				throw h3GuardError("H3 workflow must connect the uploaded image to the first_frame input; refusing an unlocked camera/background run.", "missing-first-frame");
+			}
+			if (h3 && !preferredOutputs.size) {
+				throw h3GuardError("H3 workflow must expose a final SaveVideo/VideoCombine output; refusing an unverified camera/background run.", "missing-final-output");
+			}
+			const sceneComposite = h3 ? hasH3SceneComposite(workflow, preferredOutputs) : { pass: true };
+			if (h3 && !sceneComposite.pass) {
+				throw h3GuardError("H3 workflow must composite the generated subject over the uploaded plate with a tracked mask before final video output; refusing an unlocked camera/background run.", "missing-compositor");
+			}
 			const form = new FormData();
 			form.append("image", dataUrlBlob(imageDataUrl), "cozyclay-frame.png");
 			form.append("overwrite", "true");
 			const uploaded = await fetchImpl(`${base}/upload/image`, { method: "POST", body: form, signal }).then(jsonResponse);
 			const imageName = uploaded.name || uploaded.filename;
 			if (!imageName) throw new Error("ComfyUI did not return an uploaded filename.");
-			const width = aspect === "9:16" ? 576 : aspect === "1:1" ? 768 : 1024;
-			const height = aspect === "9:16" ? 1024 : aspect === "1:1" ? 768 : 576;
-			const promptGraph = replaceWorkflowInputs(workflow, prompt, imageName, width, height);
+			const { width, height } = comfyDimensionsForAspect(aspect);
+			const promptGraph = replaceWorkflowInputs(workflow, h3 ? buildH3LockedPrompt(prompt) : prompt, imageName, width, height, { h3Only: h3, h3Context: false });
 			const queued = await fetchImpl(`${base}/prompt`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ prompt: promptGraph, client_id: `cozyclay-${Date.now()}` }), signal }).then(jsonResponse);
 			if (!queued.prompt_id) throw new Error("ComfyUI did not return a prompt id.");
 			const deadline = Date.now() + 15 * 60 * 1000;
@@ -75,7 +277,9 @@ function createComfy(env, fetchImpl) {
 				history = await fetchImpl(`${base}/history/${encodeURIComponent(queued.prompt_id)}`, { signal }).then(jsonResponse);
 				const entry = history[queued.prompt_id] || history;
 				if (entry?.outputs && Object.keys(entry.outputs).length) {
-					for (const node of Object.values(entry.outputs)) for (const output of Object.values(node || {})) {
+					for (const [nodeId, node] of Object.entries(entry.outputs)) {
+						if (preferredOutputs.size && !preferredOutputs.has(String(nodeId))) continue;
+						for (const output of Object.values(node || {})) {
 						const files = Array.isArray(output) ? output : [output];
 						for (const file of files) if (file?.filename && /\.(mp4|webm|gif|mov)$/i.test(file.filename)) {
 							const query = new URLSearchParams({ filename: file.filename, subfolder: file.subfolder || "", type: file.type || "output" });
@@ -83,7 +287,16 @@ function createComfy(env, fetchImpl) {
 							if (!response.ok) throw new Error(`ComfyUI video fetch failed (${response.status}).`);
 							const bytes = Buffer.from(await response.arrayBuffer());
 							const dimensions = findDimensions(entry, width, height);
-							return { mp4Base64: bytes.length <= MAX_INLINE_VIDEO ? bytes.toString("base64") : undefined, url: bytes.length > MAX_INLINE_VIDEO ? `${base}/view?${query}` : undefined, width: dimensions.width, height: dimensions.height, seconds: dimensions.seconds ?? durationSeconds };
+							let preservation;
+							if (h3) {
+								preservation = await inspectH3Output({ imageDataUrl, videoBytes: bytes, expectedWidth: width, expectedHeight: height, compositorVerified: sceneComposite.pass });
+								if (!preservation.pass) {
+									const { worst } = preservation;
+									throw Object.assign(new Error(`H3 preservation failed: background/camera drift p95=${worst.p95Rgb.toFixed(1)} RGB, mean=${worst.meanRgb.toFixed(1)} RGB.`), { code: "h3-preservation-failed", preservation });
+								}
+							}
+			return { mp4Base64: bytes.length <= MAX_INLINE_VIDEO ? bytes.toString("base64") : undefined, url: bytes.length > MAX_INLINE_VIDEO ? `${base}/view?${query}` : undefined, width: dimensions.width, height: dimensions.height, seconds: dimensions.seconds ?? durationSeconds, ...(preservation ? { preservation: { ...preservation, compositor: sceneComposite } } : {}) };
+						}
 						}
 					}
 				}