cozyclay 2.0.2 → 2.1.1

package/src/commands/project.js

@@ -1,5 +1,6 @@
 import { studioActionDeclaration } from "../studio-actions.js";
 import { fail } from "./shared.js";
+import { PREVIS_MODES } from "../project.js";
 
 const input = (properties = {}, required = []) => ({ type: "object", properties, required, additionalProperties: false });
 const name = { type: "string", minLength: 1, maxLength: 240 };
@@ -8,12 +9,13 @@ const document = (id, label, properties = {}) => ({ id, label, description: labe
 const rename = { id: "project.rename", label: "Rename project", description: "Rename the project in one retained undo entry.", kind: "mutation", undoDomain: "scenes", input: input({ name }, ["name"]) };
 const save = { ...studioActionDeclaration("project.save"), input: input({ name }) };
 const saveAs = { ...save, id: "project.saveAs", label: "Save project as" };
+const exportAsAnimation = studioActionDeclaration("project.exportAsAnimation");
 const opening = document("project.open", "Open a project file", { serialized: { type: "string", maxLength: 400_000_000 }, handleToken: token, projectToken: token });
-const fresh = document("project.new", "Start a new project", { name });
+const fresh = document("project.new", "Start a new project", { name, previsMode: { type: "string", enum: [...PREVIS_MODES] } });
 const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "tutorial", "launch"] }, name });
 const restore = { ...document("project.restore", "Restore the remembered project", { handleToken: token }), exposure: "ui-only" };
 const browse = { id: "project.browse", label: "Browse projects", description: "Show the project browser.", kind: "transient", exposure: "ui-only", input: input() };
-export const declarations = Object.freeze([rename, save, saveAs, opening, fresh, starter, restore, browse]);
+export const declarations = Object.freeze([rename, save, saveAs, exportAsAnimation, opening, fresh, starter, restore, browse]);
 
 export function register(registry, ports) {
 	const owner = () => ports.storeDomain?.("scenes");
@@ -44,6 +46,17 @@ export function register(registry, ports) {
 				? `This browser has no file access, so the project ${saved.name} was downloaded as ${saved.fileName}.`
 				: `Saved the project ${saved.name} to ${saved.fileName}.` };
 		} });
+	registry.register({ ...exportAsAnimation, available: () => true,
+		run: async (_args, context) => {
+			const saved = await owner().exportAsAnimationProject(context);
+			if (saved?.cancelled) fail("TARGET_NOT_READY", "Not exported: the user closed the file picker.");
+			if (!saved?.saved) fail("TARGET_NOT_READY", saved?.failure === "not-storyboard"
+				? "Export as Animation project is available only for storyboard projects."
+				: "Not exported: writing the animation project file failed.");
+			return { affectedIds: [], output: { fileName: saved.fileName }, summary: saved.downloaded
+				? `This browser has no file access, so the animation project ${saved.name} was downloaded as ${saved.fileName}.`
+				: `Exported the storyboard as ${saved.name} to ${saved.fileName}.` };
+		} });
 	for (const declaration of [opening, fresh, starter, restore, browse]) registry.register({ ...declaration,
 		available, run: async (args, context) => {
 			const result = await owner().projectAction(declaration.id, args, context);

package/src/commands/sculpt-images.js

@@ -0,0 +1,53 @@
+// The image port behind sculpt.compare: a reference ({ assetId } from the asset
+// store, or { dataUrl }) decoded to RGBA, and an RGBA sheet encoded as a PNG data
+// URL. The editor uses the browser one below; a Node test hands in its own as
+// `ports.sculptImages`, so the scoring runs on the same pixels in both.
+import { getAsset, openAssetDb } from "../scene-assets.js";
+
+function canvas(width, height) {
+	if (typeof OffscreenCanvas === "function") return new OffscreenCanvas(width, height);
+	if (globalThis.document?.createElement) return Object.assign(document.createElement("canvas"), { width, height });
+	throw new Error("this browser cannot draw images: no canvas is available");
+}
+
+async function referenceBlob(reference) {
+	if (reference.dataUrl !== undefined) return (await fetch(reference.dataUrl)).blob();
+	const asset = await getAsset(await openAssetDb(), reference.assetId);
+	if (!asset || asset.width === undefined) throw new Error(`no image asset ${reference.assetId} in this project`);
+	return new Blob([asset.bytes], { type: asset.type });
+}
+
+export const browserSculptImages = Object.freeze({
+	async decode(reference) {
+		if (typeof createImageBitmap !== "function") throw new Error("this browser cannot decode images: createImageBitmap is unavailable");
+		const bitmap = await createImageBitmap(await referenceBlob(reference));
+		try {
+			const context = canvas(bitmap.width, bitmap.height).getContext("2d", { willReadFrequently: true });
+			context.drawImage(bitmap, 0, 0);
+			const { width, height, data } = context.getImageData(0, 0, bitmap.width, bitmap.height);
+			return { width, height, data };
+		} finally {
+			bitmap.close?.();
+		}
+	},
+	async encodePng({ width, height, data }) {
+		const surface = canvas(width, height);
+		surface.getContext("2d").putImageData(new ImageData(new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength), width, height), 0, 0);
+		if (!surface.convertToBlob) return surface.toDataURL("image/png");
+		const bytes = new Uint8Array(await (await surface.convertToBlob({ type: "image/png" })).arrayBuffer());
+		let binary = "";
+		for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+		return `data:image/png;base64,${btoa(binary)}`;
+	},
+});
+
+/** Nearest-neighbour shrink of an RGBA image by an integer factor. */
+export function shrinkRgba({ width, height, data }, factor) {
+	const w = Math.max(1, Math.floor(width / factor)), h = Math.max(1, Math.floor(height / factor));
+	const out = new Uint8Array(w * h * 4);
+	for (let y = 0; y < h; y += 1) for (let x = 0; x < w; x += 1) {
+		const s = ((y * factor) * width + x * factor) * 4;
+		out.set(data.subarray(s, s + 4), (y * w + x) * 4);
+	}
+	return { width: w, height: h, data: out };
+}

package/src/commands/shot.js

@@ -1,20 +1,25 @@
 // One semantic entry point for timeline, camera controls and agent framing.
 import { createCameraBlock, updateCameraBlock, removeCameraRail } from '../camera-block.js';
-import { addShotAtFrame, cutAtFrame, duplicateShot, removeShot, reorderShot, resizeShot, renameShot, moveCameraKey, removeCameraKey } from '../cuts.js';
+import { addShotAtFrame, createShot, cutAtFrame, duplicateShot, removeShot, reorderShot, resizeShot, renameShot, moveCameraKey, removeCameraKey } from '../cuts.js';
+import { reflowStillShots, stillFrameCount, STILL_FRAME_COUNT_MAX, STILL_HOLD_DEFAULT } from '../shot-authoring.js';
+import { ko } from '../locale.js';
+import { track } from '../analytics.js';
+import { isImageAssetId } from '../scene-assets.js';
 import { createStableItemId, updateStableItem } from '../stable-items.js';
 import { railFollowForNewGeometry } from '../camera-rail-schedule.js';
-import { studioActionDeclaration } from '../studio-actions.js';
+import { studioActionDeclaration, studioActionRefusal } from '../studio-actions.js';
 import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
 import { elementSetSchema, registerElementSet } from './elements.js';
 import './elements/shot.js';
 import { changedIds, fail, shotLabel } from './shared.js';
 
 const id = StudioSchemas.TargetGuard.properties.targetId;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const number = { type: 'number' };
 const frame = { type: 'integer', minimum: 0 };
 const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
 const mutation = (id, label, schema) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'shot', input: schema });
-const existing = ['shot.create', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.reorder'].map(studioActionDeclaration);
+const existing = ['shot.create', 'shot.createStill', 'shot.setCaption', 'shot.setCastOverride', 'shot.setHold', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.reorder'].map(studioActionDeclaration);
 const extra = [
   mutation('shot.set', 'Set shot fields', elementSetSchema('shot')),
   mutation('shot.rename', 'Rename shot', input({ shotId: id, name: { type: 'string', maxLength: 240 } })),
@@ -28,6 +33,9 @@ const extra = [
   mutation('shot.frame', 'Frame the shot', { ...input({ ...STUDIO_TOOL_SCHEMAS.frame_shot.properties, preset: { type: 'string' } }, []), oneOf: [STUDIO_TOOL_SCHEMAS.frame_shot, input({ preset: { type: 'string' } })] }),
   { ...mutation('shot.replace', 'Replace shot authoring', input({ shots: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } } })), exposure: 'ui-only' },
   { ...mutation('shot.captureCamera', 'Capture camera framing', input({ shotId: id }, [])), exposure: 'ui-only' },
+  // The Board's Stylize result (or null to clear it). UI-only: the picture has
+  // to be in the asset store first, which only the Stylize flow does.
+  { ...mutation('shot.setStylized', 'Set stylized panel image', input({ shotId: id, assetId: { oneOf: [{ type: 'string' }, { type: 'null' }] } })), exposure: 'ui-only' },
   { ...mutation('shot.placeCamera', 'Place camera', input(Object.fromEntries(['x', 'y', 'z', 'lookAtX', 'lookAtY', 'lookAtZ', 'focalMm'].map(key => [key, number])), [])), exposure: 'ui-only' },
 ];
 export const declarations = Object.freeze([extra[0], ...existing, ...extra.slice(1).map(entry => entry.id === 'shot.frame' ? entry : { ...entry, exposure: 'ui-only' })]);
@@ -37,16 +45,75 @@ export function register(registry, ports) {
   const mounted = () => Boolean(ports.storeDomain?.('shot')) || 'The shots document owner is not mounted.';
   const shotOf = shotId => owner().read().find(shot => shot.id === shotId) ?? fail('STALE_TARGET', `Shot ${shotId} is not in this scene.`);
   const patchShot = (shotId, update) => { shotOf(shotId); owner().write(current => updateStableItem(current, shotId, update, 'shots')); };
+  const storyboard = () => ports.storeDomain?.('scenes')?.metadata?.().previsMode === 'storyboard';
+  const stillOf = shotId => {
+    const shot = shotOf(shotId);
+    return shot.kind === 'still' ? shot : fail('INVALID_ARGUMENT', `${shot.name} is a clip shot; only stills have a hold and a place in the still order.`);
+  };
+  // Every still edit is one write: the stills (in their new array order) are
+  // laid end to end and the timeline is sized to them, or nothing changes.
+  function writeStills(shots) {
+    const next = reflowStillShots(shots), frameCount = stillFrameCount(next);
+    if (frameCount > STILL_FRAME_COUNT_MAX) {
+      const en = `Storyboard is full (${STILL_FRAME_COUNT_MAX} frames); shorten a hold or remove a panel.`;
+      throw studioActionRefusal('INVALID_ARGUMENT', en, ko(en, `스토리보드가 가득 찼습니다 (${STILL_FRAME_COUNT_MAX}프레임). 홀드를 줄이거나 패널을 지우세요.`));
+    }
+    const clip = next.find(shot => shot.kind !== 'still' && next.some(still => still.kind === 'still' && still.startFrame <= shot.endFrame && still.endFrame >= shot.startFrame));
+    if (clip) fail('TARGET_NOT_READY', `The stills would overlap the clip shot ${clip.name} (frames ${clip.startFrame}-${clip.endFrame}); move or remove it first.`);
+    owner().writeState(before => ({ ...before, shots: next, frameCount }));
+    return next;
+  }
+  function createStill({ caption = '', hold = STILL_HOLD_DEFAULT } = {}) {
+    const current = owner().read(), framing = owner().capture(), last = current.findLastIndex(shot => shot.kind === 'still');
+    const keys = framing ? [{ id: createStableItemId('camera-key'), frame: 0, framing }] : [];
+    const still = { ...createShot(`Shot ${current.length + 1}`, 0, hold - 1, keys), kind: 'still', caption };
+    const written = writeStills([...current.slice(0, last + 1), still, ...current.slice(last + 1)]);
+    // Land the playhead in the new panel (the timeline.seek path) so the placement
+    // actions that follow write this panel's cast override, not the previous one's.
+    const created = written.find(shot => shot.id === still.id), { selection, view } = ports.readView();
+    ports.publishView({ selection, view: { ...view, frame: created.startFrame }, shotId: created.id });
+  }
+  function duplicate(shotId) {
+    const source = shotOf(shotId), copied = { kind: source.kind, caption: source.caption, cast: structuredClone(source.cast), stylizedAssetId: source.stylizedAssetId };
+    if (source.kind !== 'still') {
+      const before = owner().read(), next = duplicateShot(before, shotId, owner().state().frameCount);
+      return owner().write(next.map(shot => before.includes(shot) ? shot : { ...shot, ...copied }));
+    }
+    const current = owner().read(), index = current.indexOf(source);
+    const copy = { ...createShot(`${source.name} copy`, source.startFrame, source.endFrame,
+      source.cameraKeys.map(key => ({ ...key, id: createStableItemId('camera-key') })), source.camera), ...copied };
+    writeStills([...current.slice(0, index + 1), copy, ...current.slice(index + 1)]);
+  }
+  function reorder({ shotId, startFrame, index }) {
+    if ((startFrame === undefined) === (index === undefined)) fail('INVALID_ARGUMENT', 'shot.reorder takes exactly one of startFrame or index.');
+    const shot = shotOf(shotId);
+    if (shot.kind !== 'still') {
+      if (index !== undefined) stillOf(shotId);
+      return owner().write(current => reorderShot(current, shotId, startFrame, owner().state().frameCount));
+    }
+    const current = owner().read(), others = current.filter(row => row.kind === 'still' && row.id !== shotId);
+    const target = index ?? others.filter(row => row.startFrame < startFrame).length;
+    const order = [...others.slice(0, target), shot, ...others.slice(target)];
+    let next = 0;
+    writeStills(current.map(row => row.kind === 'still' ? order[next++] : row));
+  }
   const methods = {
-    'shot.create': () => owner().write(current => addShotAtFrame(current, ports.state().frame, owner().state().frameCount, owner().capture())),
+    'shot.create': () => storyboard() ? createStill() : owner().write(current => addShotAtFrame(current, ports.state().frame, owner().state().frameCount, owner().capture())),
+    'shot.createStill': args => createStill(args),
+    'shot.setCaption': ({ shotId, caption }) => patchShot(shotId, shot => ({ ...shot, caption })),
+    'shot.setCastOverride': ({ shotId, characterId, override }) => owner().setCastOverride(shotId, characterId, override),
+    'shot.setHold': ({ shotId, hold }) => {
+      const shot = stillOf(shotId), endFrame = shot.startFrame + hold - 1;
+      writeStills(owner().read().map(row => row === shot ? { ...row, endFrame, cameraKeys: row.cameraKeys.filter(key => key.frame <= endFrame) } : row));
+    },
     'shot.split': ({ shotId }) => {
       const shot = shotOf(shotId), { frame } = ports.state();
       if (frame <= shot.startFrame || frame > shot.endFrame) fail('TARGET_NOT_READY', `The playhead (frame ${frame}) is not inside ${shot.name} after its first frame.`);
       owner().write(current => cutAtFrame(current, shotId, frame, owner().capture()));
     },
-    'shot.duplicate': ({ shotId }) => { shotOf(shotId); owner().write(current => duplicateShot(current, shotId, owner().state().frameCount)); },
+    'shot.duplicate': ({ shotId }) => duplicate(shotId),
     'shot.remove': ({ shotId }) => { shotOf(shotId); owner().write(current => removeShot(current, shotId)); },
-    'shot.reorder': ({ shotId, startFrame }) => { shotOf(shotId); owner().write(current => reorderShot(current, shotId, startFrame, owner().state().frameCount)); },
+    'shot.reorder': args => reorder(args),
     'shot.setRange': ({ shotId, range }) => {
       const shot = shotOf(shotId), startFrame = range.startFrame, endFrame = range.endFrameExclusive - 1;
       const edges = startFrame > shot.endFrame ? [['end', endFrame], ['start', startFrame]] : [['start', startFrame], ['end', endFrame]];
@@ -77,24 +144,35 @@ export function register(registry, ports) {
     'shot.setLens': ({ fovDeg }) => owner().setLens(fovDeg),
     'shot.replace': ({ shots }) => owner().write(shots),
     'shot.captureCamera': args => owner().captureCamera(args.shotId),
+    'shot.setStylized': ({ shotId, assetId }) => {
+      if (assetId !== null && !isImageAssetId(assetId)) fail('INVALID_ARGUMENT', `${assetId} is not an image asset id.`);
+      patchShot(shotId, shot => ({ ...shot, stylizedAssetId: assetId }));
+    },
     'shot.placeCamera': args => owner().placeCamera(args),
   };
   const hasShots = state => state.shots.length > 0 || 'There are no shots yet; add one with shot.create.';
   const availability = {
-    'shot.create': state => addShotAtFrame(state.shots, state.frame, state.frameCount, null) !== state.shots || `There is no free room for a new shot at the playhead (frame ${state.frame}); move it with operate_studio { frame } or shorten a shot.`,
+    'shot.createStill': () => true,
+    'shot.create': state => storyboard() || addShotAtFrame(state.shots, state.frame, state.frameCount, null) !== state.shots || `There is no free room for a new shot at the playhead (frame ${state.frame}); move it with operate_studio { frame } or shorten a shot.`,
     'shot.split': state => state.shots.some(shot => state.frame > shot.startFrame && state.frame <= shot.endFrame) || `The playhead (frame ${state.frame}) is not inside a shot after its first frame; move it with operate_studio { frame }.`,
     'shot.clearCameraRail': state => state.shots.some(shot => createCameraBlock(shot.camera).cameraRail) || 'No shot has a camera rail; lay one with shot.setCameraRail.',
   };
   registerElementSet(registry, ports, extra[0]);
   for (const declaration of declarations.filter(row => row.id !== 'shot.set')) registry.register({ ...declaration,
     available: state => mounted() === true ? (availability[declaration.id] ?? (existing.includes(declaration) ? hasShots : () => true))(state) : mounted(),
-    run(args) {
+    run(args, context) {
       if (declaration.id === 'shot.frame') {
         const plan = owner().frame(args);
         return { affectedIds: plan.affectedIds, summary: 'Framed the shot.' };
       }
-      const before = owner().read(); methods[declaration.id](args);
-      const after = owner().read(), changed = changedIds(before, after);
+      const before = owner().read(), newPanel = declaration.id === 'shot.createStill' || (declaration.id === 'shot.create' && storyboard());
+      methods[declaration.id](args);
+      // Only the origin travels: never the caption, name or id of the panel.
+      if (newPanel) track('storyboard:panel_created', { source: context?.origin && context.origin !== 'ui' ? 'agent' : 'manual' });
+      // The owner re-normalizes every shot on write, so compare content, not
+      // identity; a storyboard reflow can still move more shots than a receipt
+      // names (100), and the first 100 stand for the batch.
+      const after = owner().read(), changed = changedIds(before.map(row => after.find(next => next.id === row.id && same(next, row)) ?? row), after).slice(0, 100);
       const affectedIds = changed.length ? changed : [args.shotId ?? ports.state().activeSceneId];
       return { affectedIds, summary: changed.length ? `${declaration.label}: ${changed.map(id => after.find(row => row.id === id)).filter(Boolean).map(shotLabel).join('; ')}.` : `${declaration.label}.` };
     },

package/src/commands/view.js

@@ -1,7 +1,9 @@
 // Viewer preferences: transient, like the View menu they mirror.
-import { studioActionDeclaration } from "../studio-actions.js";
-import { StudioProtocolError, STUDIO_TOOL_SCHEMAS } from '../studio-agent-protocol.js';
+import { studioActionDeclaration, studioActionRefusal } from "../studio-actions.js";
+import { STUDIO_TOOL_SCHEMAS } from '../studio-agent-protocol.js';
+import { ko } from '../locale.js';
 import { shotAtFrame } from '../cuts.js';
+import { fail } from './shared.js';
 
 const fields = STUDIO_TOOL_SCHEMAS.operate_studio.properties;
 const groups = { 'view.select': ['selection', 'shotId'], 'timeline.seek': ['frame'], 'timeline.play': ['playing'], 'view.setMode': ['mode', 'view'] };
@@ -10,16 +12,18 @@ const operations = Object.entries({ ...groups, 'view.update': Object.keys(fields
 	input: { type: 'object', properties: Object.fromEntries(keys.map(key => [key, fields[key]])), required: [], additionalProperties: false },
 }));
 export const declarations = Object.freeze([...operations, ...["view.setPartColours", "view.setGuideMode", "view.setInset"].map(studioActionDeclaration)]);
+// A storyboard project has no Motion department; every door says so the same way.
+export const STORYBOARD_MOTION_REFUSAL = Object.freeze({ en: 'Motion tools are not part of a Storyboard project.', ko: '모션 도구는 스토리보드 프로젝트에 없어요.' });
 export const viewCommand = args => Object.entries(groups).find(([, keys]) => Object.keys(args).every(key => keys.includes(key)))?.[0] ?? 'view.update';
 
 export function register(registry, ports) {
 	registry.registerToolAlias('operate_studio', viewCommand);
 	for (const declaration of operations) registry.register({ ...declaration, available: () => true, run(args) {
-		const fail = (code, message) => { throw new StudioProtocolError(code, message); };
 		if (!Object.keys(args).length || (args.view && !Object.keys(args.view).length)) fail('INVALID_ARGUMENT', 'Specify a view operation.');
 		const state = ports.readView();
 		// Pose mode is IK editing: without a rig to solve there is nothing to pose.
 		if (args.mode === 'pose' && args.mode !== state.view.mode && !ports.canPose()) fail('TARGET_NOT_READY', 'Pose mode needs a loaded character rig to edit with IK.');
+		if (args.mode === 'motion' && state.previsMode === 'storyboard') throw studioActionRefusal('TARGET_NOT_READY', STORYBOARD_MOTION_REFUSAL.en, ko(STORYBOARD_MOTION_REFUSAL.en, STORYBOARD_MOTION_REFUSAL.ko));
 		const selection = args.selection === undefined ? state.selection : args.selection;
 		if (selection) {
 			const found = selection.kind === 'scene' ? selection.id === state.host.sceneId : selection.kind === 'camera' ? selection.id === 'camera'
@@ -31,7 +35,9 @@ export function register(registry, ports) {
 		const frame = args.frame ?? shot?.startFrame ?? state.view.frame;
 		if (frame >= Math.max(1, state.frameCount)) fail('INVALID_RANGE', 'Frame is outside the timeline.');
 		const view = { ...state.view, ...args.view, frame, mode: args.mode ?? state.view.mode, playing: args.playing ?? state.view.playing };
-		ports.publishView({ selection, view, shotId: args.shotId ?? shotAtFrame(state.shots, frame)?.id ?? null });
+		// modeSet: only a command that names a mode moves the editor out of a
+		// UI-only mode (Sculpt, #739), which the published view reads as Stage.
+		ports.publishView({ selection, view, shotId: args.shotId ?? shotAtFrame(state.shots, frame)?.id ?? null, modeSet: args.mode !== undefined });
 		return { affectedIds: [state.host.sceneId], summary: 'Updated editor view.' };
 	} });
 	const viewAction = (id, run) => registry.register({ ...studioActionDeclaration(id), available: () => true,

package/src/coplanar-depth.js

@@ -0,0 +1,216 @@
+import * as THREE from "three";
+
+/**
+ * Depth ranks for coplanar faces of scene-object primitives.
+ *
+ * Agent-built assemblies stack parts whose same-facing faces lie in exactly
+ * one plane (a hood and a grille sharing a top at y=1.05). The depth test
+ * cannot order them, so as the camera moves the winner flips every frame and
+ * the strip sparkles. The ranks computed here let the renderer pull the
+ * later-created part toward the camera by a polygon offset, which holds
+ * whatever the camera does. The records are never edited.
+ */
+
+const DEG = Math.PI / 180;
+/** Planes closer than this are one plane. */
+const PLANE_EPS = 1e-3;
+/** Normals this aligned (cosine) face the same way. */
+const NORMAL_DOT = 0.9999;
+/** Overlap shallower than this is two faces touching along an edge. */
+const OVERLAP_EPS = 1e-4;
+/** Bounds the offset: a deeper chain shares the top rank. */
+export const MAX_DEPTH_RANK = 6;
+
+// Planar faces per kind, in the primitive's local frame BEFORE scale: the axis
+// the face is perpendicular to, which side, and where along that axis it sits
+// (cube/cylinder/cone sit on y in [0, 1] — see Primitive in props.jsx).
+const BOX_FACES = [
+	{ axis: 0, side: 1, at: 0.5 }, { axis: 0, side: -1, at: -0.5 },
+	{ axis: 1, side: 1, at: 1 }, { axis: 1, side: -1, at: 0 },
+	{ axis: 2, side: 1, at: 0.5 }, { axis: 2, side: -1, at: -0.5 },
+];
+const CAP_TOP = { axis: 1, side: 1, at: 1 };
+const CAP_BASE = { axis: 1, side: -1, at: 0 };
+const FACES_BY_KIND = {
+	cube: BOX_FACES,
+	cylinder: [CAP_TOP, CAP_BASE],
+	cone: [CAP_BASE],
+	// 2x2, a hair above the floor, drawn double-sided
+	plane: [{ axis: 1, side: 1, at: 0.004, flat: true }, { axis: 1, side: -1, at: 0.004, flat: true }],
+};
+// Local centre of the box the faces live on, per axis (x/z centred, y from 0).
+const MID = [0, 0.5, 0];
+const HALF = [0.5, 0.5, 0.5];
+const PLANE_HALF = [1, 0, 1];
+
+const rot = new THREE.Matrix4();
+const euler = new THREE.Euler();
+
+/** World-space rectangular faces of one object, or null when it has none. */
+function facesOf(object) {
+	const kind = object.renderer ?? object.kind;
+	const table = FACES_BY_KIND[kind];
+	if (!table || object.attach || object.hidden === true) return null;
+	euler.set((object.rotX ?? 0) * DEG, (object.rot ?? 0) * DEG, (object.rotZ ?? 0) * DEG);
+	rot.makeRotationFromEuler(euler);
+	const e = rot.elements;
+	// column a of the rotation = where local axis a points in the world
+	const axes = [[e[0], e[1], e[2]], [e[4], e[5], e[6]], [e[8], e[9], e[10]]];
+	const scale = [object.scaleX ?? 1, object.scaleY ?? 1, object.scaleZ ?? 1];
+	const pos = [object.x ?? 0, object.y ?? 0, object.z ?? 0];
+	if (![...scale, ...pos, ...axes[0]].every(Number.isFinite)) return null;
+	const faces = [];
+	for (const face of table) {
+		const a = face.axis;
+		const u = (a + 1) % 3;
+		const v = (a + 2) % 3;
+		// a mirrored scale turns the outward normal around with it
+		const flip = face.side * (scale[a] < 0 ? -1 : 1);
+		const half = face.flat ? PLANE_HALF : HALF;
+		const centre = [0, 0, 0];
+		for (let i = 0; i < 3; i += 1) {
+			const local = i === a ? face.at : face.flat ? 0 : MID[i];
+			for (let k = 0; k < 3; k += 1) centre[k] += axes[i][k] * local * scale[i];
+		}
+		faces.push({
+			n: [axes[a][0] * flip, axes[a][1] * flip, axes[a][2] * flip],
+			c: [centre[0] + pos[0], centre[1] + pos[1], centre[2] + pos[2]],
+			u: axes[u],
+			v: axes[v],
+			hu: half[u] * Math.abs(scale[u]),
+			hv: half[v] * Math.abs(scale[v]),
+		});
+	}
+	// world box of the faces, for the pair prefilter
+	const min = [Infinity, Infinity, Infinity];
+	const max = [-Infinity, -Infinity, -Infinity];
+	for (const f of faces) {
+		for (let k = 0; k < 3; k += 1) {
+			const reach = Math.abs(f.u[k]) * f.hu + Math.abs(f.v[k]) * f.hv;
+			min[k] = Math.min(min[k], f.c[k] - reach);
+			max[k] = Math.max(max[k], f.c[k] + reach);
+		}
+	}
+	return { faces, min, max };
+}
+
+const dot = (p, q) => p[0] * q[0] + p[1] * q[1] + p[2] * q[2];
+
+// Overlap of two rectangles lying in one plane, by separating axes in the
+// plane: the rectangles' own edge directions are the only candidates.
+function overlaps(a, b) {
+	const rel = [b.c[0] - a.c[0], b.c[1] - a.c[1], b.c[2] - a.c[2]];
+	for (const axis of [a.u, a.v, b.u, b.v]) {
+		const reachA = Math.abs(dot(axis, a.u)) * a.hu + Math.abs(dot(axis, a.v)) * a.hv;
+		const reachB = Math.abs(dot(axis, b.u)) * b.hu + Math.abs(dot(axis, b.v)) * b.hv;
+		if (Math.abs(dot(axis, rel)) >= reachA + reachB - OVERLAP_EPS) return false;
+	}
+	return true;
+}
+
+/** Every pair of same-facing faces of a and b that share a plane and overlap. */
+function conflictingFaces(a, b) {
+	const found = [];
+	for (const fa of a.faces) {
+		for (const fb of b.faces) {
+			if (dot(fa.n, fb.n) <= NORMAL_DOT) continue;
+			const gap = dot(fa.n, [fb.c[0] - fa.c[0], fb.c[1] - fa.c[1], fb.c[2] - fa.c[2]]);
+			if (Math.abs(gap) > PLANE_EPS) continue;
+			if (overlaps(fa, fb)) found.push(fa);
+		}
+	}
+	return found;
+}
+
+function conflict(a, b) {
+	for (const fa of a.faces) {
+		for (const fb of b.faces) {
+			if (dot(fa.n, fb.n) <= NORMAL_DOT) continue;
+			const gap = dot(fa.n, [fb.c[0] - fa.c[0], fb.c[1] - fa.c[1], fb.c[2] - fa.c[2]]);
+			if (Math.abs(gap) > PLANE_EPS) continue;
+			if (overlaps(fa, fb)) return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Which objects need to win the depth test over an earlier one.
+ *
+ * Two planar faces conflict when they face the same way, share a plane to
+ * within a millimetre and overlap with real area; touching boxes (opposite
+ * facing) never do. The later object in `objects` is the later-made detail, so
+ * each conflict is an edge earlier -> later, and an object's rank is the length
+ * of the longest chain ending at it (capped). Only ranked objects (> 0) get an
+ * entry. Run it on the AUTHORED records: a routed group moves rigidly, so
+ * relative geometry inside it does not change with the frame.
+ *
+ * Skipped: spheres, capsules, models, cutouts, props carried by a character
+ * and hidden props. Cylinder and cone caps are approximated by their bounding
+ * rectangle, which can over-report a conflict near a rim; that costs a
+ * sub-pixel pull on a prop and nothing else.
+ *
+ * @param {Array<object>} objects scene-object records, in creation order
+ * @returns {Map<string, number>} id -> rank
+ */
+export function coplanarDepthRanks(objects) {
+	const ranks = new Map();
+	if (!Array.isArray(objects) || objects.length < 2) return ranks;
+	const shapes = objects.map((object) => (object && typeof object === "object" ? facesOf(object) : null));
+	const rank = new Array(objects.length).fill(0);
+	for (let j = 1; j < objects.length; j += 1) {
+		const b = shapes[j];
+		if (!b) continue;
+		for (let i = 0; i < j; i += 1) {
+			const a = shapes[i];
+			if (!a || rank[i] + 1 <= rank[j]) continue;
+			if (
+				a.min[0] > b.max[0] + PLANE_EPS || b.min[0] > a.max[0] + PLANE_EPS ||
+				a.min[1] > b.max[1] + PLANE_EPS || b.min[1] > a.max[1] + PLANE_EPS ||
+				a.min[2] > b.max[2] + PLANE_EPS || b.min[2] > a.max[2] + PLANE_EPS
+			) continue;
+			if (conflict(a, b)) rank[j] = Math.min(MAX_DEPTH_RANK, rank[i] + 1);
+		}
+		if (rank[j] > 0) ranks.set(objects[j].id, rank[j]);
+	}
+	return ranks;
+}
+
+const AXES = ["x", "y", "z"];
+const FACE_NAMES = { "y+": "tops", "y-": "bottoms" };
+const round = (value) => Number(value.toFixed(4));
+
+/**
+ * The coplanar conflicts coplanarDepthRanks resolves by offset, named: for
+ * each pair of objects with same-facing faces in one plane, the shared planes
+ * ("tops at y=1.05"). Informational for a receipt; it does not decide ranks.
+ *
+ * @param {Array<object>} objects scene-object records
+ * @returns {Array<{a: string, b: string, planes: Array<{face: string, axis: string|null, at: number}>}>}
+ */
+export function coplanarConflicts(objects) {
+	const pairs = [];
+	if (!Array.isArray(objects) || objects.length < 2) return pairs;
+	const shapes = objects.map((object) => (object && typeof object === "object" ? facesOf(object) : null));
+	for (let j = 1; j < objects.length; j += 1) {
+		const b = shapes[j];
+		if (!b) continue;
+		for (let i = 0; i < j; i += 1) {
+			const a = shapes[i];
+			if (!a) continue;
+			if (
+				a.min[0] > b.max[0] + PLANE_EPS || b.min[0] > a.max[0] + PLANE_EPS ||
+				a.min[1] > b.max[1] + PLANE_EPS || b.min[1] > a.max[1] + PLANE_EPS ||
+				a.min[2] > b.max[2] + PLANE_EPS || b.min[2] > a.max[2] + PLANE_EPS
+			) continue;
+			const planes = conflictingFaces(a, b).map((face) => {
+				const axis = [0, 1, 2].find((k) => Math.abs(face.n[k]) > NORMAL_DOT);
+				if (axis === undefined) return { face: "tilted faces", axis: null, at: round(dot(face.n, face.c)) };
+				const sign = face.n[axis] > 0 ? "+" : "-";
+				return { face: FACE_NAMES[`${AXES[axis]}${sign}`] ?? `${sign}${AXES[axis]} faces`, axis: AXES[axis], at: round(face.c[axis]) };
+			});
+			if (planes.length) pairs.push({ a: objects[i].id, b: objects[j].id, planes });
+		}
+	}
+	return pairs;
+}

package/src/cuts.js

@@ -11,7 +11,7 @@ import {
 	updateStableItem,
 } from "./stable-items.js";
 
-export const DEFAULT_SHOT_FRAMES = 40;
+const DEFAULT_SHOT_FRAMES = 40;
 
 const frameNumber = (value, fallback = 0) => Number.isFinite(value) ? Math.round(value) : fallback;
 
@@ -48,6 +48,12 @@ export function createShot(name = "Shot", startFrame = 0, endFrame = startFrame
 		endFrame: end,
 		cameraKeys: uniqueKeys(cameraKeys, start, end),
 		camera: createCameraBlock(camera),
+		// v5 shot-document defaults, so a fresh shot already has the shape the
+		// document normalizer gives it (and an undo restores).
+		kind: "clip",
+		caption: "",
+		cast: {},
+		stylizedAssetId: null,
 	};
 }
 
@@ -133,11 +139,6 @@ export function resizeShot(shots, shotId, edge, rawFrame, frameCount) {
 		.sort((a, b) => a.startFrame - b.startFrame);
 }
 
-/** Compatibility name for callers that move the left edge. */
-export function moveBoundary(shots, shotId, newStartFrame, frameCount) {
-	return resizeShot(shots, shotId, "start", newStartFrame, frameCount);
-}
-
 export function removeShot(shots, shotId) {
 	return removeStableItem(shots, shotId, "shots");
 }