cozyclay 2.0.2 → 2.1.0

package/src/stage-labels-ko.js

@@ -0,0 +1,204 @@
+import { ko } from "./locale.js";
+import { CUSTOM_MOVE } from "./shot.js";
+import { CUTOUT_KIND, MESH_KIND } from "./scene-objects.js";
+
+export const RIG_HIERARCHY_FOCUS = {
+	"rig.torso": "spine",
+	"rig.hips": "hips",
+	"rig.spine": "spine",
+	"rig.chest": "chest",
+	"rig.neck": "neck",
+	"rig.head": "head",
+	"rig.leftArm": "leftHand",
+	"rig.leftShoulder": "leftShoulder",
+	"rig.leftElbow": "leftElbow",
+	"rig.leftHand": "leftHand",
+	"rig.rightArm": "rightHand",
+	"rig.rightShoulder": "rightShoulder",
+	"rig.rightElbow": "rightElbow",
+	"rig.rightHand": "rightHand",
+	"rig.leftLeg": "leftFoot",
+	"rig.leftKnee": "leftKnee",
+	"rig.leftFoot": "leftFoot",
+	"rig.rightLeg": "rightFoot",
+	"rig.rightKnee": "rightKnee",
+	"rig.rightFoot": "rightFoot",
+};
+
+export const HIERARCHY_INSPECTOR_TITLES = {
+	shot: ko("Shot settings", "샷 설정"),
+	camera: ko("Camera", "카메라"),
+	light: ko("Light", "조명"),
+	characters: ko("Characters", "인물"),
+	characterA: ko("Character 1", "인물 1"),
+	rig: ko("Rig", "리그"),
+	characterB: ko("Character 2", "인물 2"),
+	environment: ko("Environment", "환경"),
+	props: ko("Props", "소품"),
+	"rig.torso": ko("Torso", "몸통"),
+	"rig.hips": ko("Root / Hips", "루트 / 엉덩이"),
+	"rig.spine": ko("Spine", "척추"),
+	"rig.chest": ko("Chest", "가슴"),
+	"rig.neck": ko("Neck", "목"),
+	"rig.head": ko("Head", "머리"),
+	"rig.leftArm": ko("Left Arm", "왼팔"),
+	"rig.leftShoulder": ko("Left Shoulder", "왼쪽 어깨"),
+	"rig.leftElbow": ko("Left Elbow", "왼쪽 팔꿈치"),
+	"rig.leftHand": ko("Left Hand", "왼손"),
+	"rig.rightArm": ko("Right Arm", "오른팔"),
+	"rig.rightShoulder": ko("Right Shoulder", "오른쪽 어깨"),
+	"rig.rightElbow": ko("Right Elbow", "오른쪽 팔꿈치"),
+	"rig.rightHand": ko("Right Hand", "오른손"),
+	"rig.leftLeg": ko("Left Leg", "왼다리"),
+	"rig.leftKnee": ko("Left Knee", "왼쪽 무릎"),
+	"rig.leftFoot": ko("Left Foot", "왼발"),
+	"rig.rightLeg": ko("Right Leg", "오른다리"),
+	"rig.rightKnee": ko("Right Knee", "오른쪽 무릎"),
+	"rig.rightFoot": ko("Right Foot", "오른발"),
+};
+
+export const CAMERA_MOVE_LABELS_KO = new Map([
+	["Static / locked-off", ko("Static / locked-off", "고정 샷")],
+	["Zoom in", ko("Zoom in", "줌 인")],
+	["Zoom out", ko("Zoom out", "줌 아웃")],
+	["Push-in (dolly in)", ko("Push-in (dolly in)", "푸시인(돌리 인)")],
+	["Pull-out (dolly out)", ko("Pull-out (dolly out)", "풀아웃(돌리 아웃)")],
+	["Pan left", ko("Pan left", "왼쪽 팬")],
+	["Pan right", ko("Pan right", "오른쪽 팬")],
+	["Tilt up", ko("Tilt up", "틸트 업")],
+	["Tilt down", ko("Tilt down", "틸트 다운")],
+	["Tracking / follow", ko("Tracking / follow", "트래킹 / 팔로우")],
+	["Orbit / arc", ko("Orbit / arc", "오빗 / 아크")],
+	["Crane up", ko("Crane up", "크레인 업")],
+	["Crane down", ko("Crane down", "크레인 다운")],
+	["Handheld", ko("Handheld", "핸드헬드")],
+	["Crash zoom in", ko("Crash zoom in", "크래시 줌 인")],
+	["Dolly-zoom (vertigo)", ko("Dolly-zoom (vertigo)", "돌리 줌(버티고)")],
+	["Whip pan", ko("Whip pan", "휩 팬")],
+	["Aerial / drone", ko("Aerial / drone", "공중 / 드론")],
+	[CUSTOM_MOVE, ko(CUSTOM_MOVE, "직접 입력…")],
+]);
+
+export const POSE_LABELS_KO = new Map([
+	["T-pose", ko("T-pose", "T 포즈")],
+	["Relaxed", ko("Relaxed", "편안한 자세")],
+	["Contrapposto", ko("Contrapposto", "콘트라포스토")],
+	["Walking", ko("Walking", "걷는 자세")],
+	["Seated", ko("Seated", "앉은 자세")],
+	["Arms crossed", ko("Arms crossed", "팔짱")],
+	["Pointing", ko("Pointing", "가리키기")],
+	["Hands on hips", ko("Hands on hips", "허리에 손")],
+	["Looking back", ko("Looking back", "뒤돌아보기")],
+	["Hands up", ko("Hands up", "손 올리기")],
+]);
+
+export const SHOT_SIZE_LABELS_KO = new Map([
+	["extreme close-up", ko("extreme close-up", "익스트림 클로즈업")],
+	["close-up", ko("close-up", "클로즈업")],
+	["medium close-up", ko("medium close-up", "미디엄 클로즈업")],
+	["medium shot", ko("medium shot", "미디엄 샷")],
+	["medium-wide shot", ko("medium-wide shot", "미디엄 와이드 샷")],
+	["wide shot", ko("wide shot", "와이드 샷")],
+	["extreme wide shot", ko("extreme wide shot", "익스트림 와이드 샷")],
+]);
+
+export const SHOT_LEVEL_LABELS_KO = new Map([
+	["overhead", ko("overhead", "오버헤드")],
+	["high angle", ko("high angle", "하이 앵글")],
+	["eye level", ko("eye level", "아이 레벨")],
+	["chest level", ko("chest level", "가슴 높이")],
+	["hip level", ko("hip level", "엉덩이 높이")],
+	["knee level", ko("knee level", "무릎 높이")],
+	["ground level", ko("ground level", "바닥 높이")],
+]);
+
+export const SCENE_RENDERER_LABELS_KO = new Map([
+	["cube", ko("cube", "큐브")],
+	["sphere", ko("sphere", "구")],
+	["capsule", ko("capsule", "캡슐")],
+	["cylinder", ko("cylinder", "원기둥")],
+	["cone", ko("cone", "원뿔")],
+	["plane", ko("plane", "평면")],
+	["chair", ko("chair", "의자")],
+	["car", ko("car", "자동차")],
+	["aircraft", ko("aircraft", "비행기")],
+	[CUTOUT_KIND, ko("cutout", "컷아웃")],
+	[MESH_KIND, ko("Mesh", "모델")],
+	["sculpt", ko("Sculpt", "조형")],
+]);
+
+export const SCENE_OBJECT_NAME_LABELS_KO = new Map([
+	["Cube", ko("Cube", "큐브")],
+	["Sphere", ko("Sphere", "구")],
+	["Capsule", ko("Capsule", "캡슐")],
+	["Cylinder", ko("Cylinder", "원기둥")],
+	["Cone", ko("Cone", "원뿔")],
+	["Plane", ko("Plane", "평면")],
+	["Chair", ko("Chair", "의자")],
+	["Car", ko("Car", "자동차")],
+	["Plane (aircraft)", ko("Plane (aircraft)", "비행기")],
+	["Mesh", ko("Mesh", "모델")],
+	["Model", ko("Model", "모델")],
+]);
+
+export function poseLabelKo(pose) {
+	return pose?.custom ? pose.label : POSE_LABELS_KO.get(pose?.label) ?? pose?.label ?? "";
+}
+
+export function cameraMoveLabelKo(move) {
+	return CAMERA_MOVE_LABELS_KO.get(move) ?? move;
+}
+
+export function sceneRendererLabelKo(renderer) {
+	return SCENE_RENDERER_LABELS_KO.get(renderer) ?? renderer;
+}
+
+export function sceneObjectNameDisplayKo(name) {
+	const match = /^(.+?)(?: ([2-9]\d*))?$/.exec(name ?? "");
+	if (!match) return name;
+	const [, base, suffix] = match;
+	const label = SCENE_OBJECT_NAME_LABELS_KO.get(base);
+	return label ? `${label}${suffix ? ` ${suffix}` : ""}` : name;
+}
+
+export function viewShortKo(viewShort) {
+	if (viewShort === "front") return ko("front", "정면");
+	if (viewShort === "back") return ko("back", "후면");
+	if (viewShort?.includes("profile")) return viewShort.startsWith("left") ? ko("left profile", "왼쪽 측면") : ko("right profile", "오른쪽 측면");
+	if (viewShort?.startsWith("front ¾")) return / L$/.test(viewShort) ? ko("front ¾ L", "정면 ¾ 왼쪽") : ko("front ¾ R", "정면 ¾ 오른쪽");
+	if (viewShort?.startsWith("rear ¾")) return / L$/.test(viewShort) ? ko("rear ¾ L", "후면 ¾ 왼쪽") : ko("rear ¾ R", "후면 ¾ 오른쪽");
+	return viewShort;
+}
+
+export function slateLineKo(shot) {
+	return [
+		SHOT_SIZE_LABELS_KO.get(shot.sizeLabel) ?? shot.sizeLabel,
+		viewShortKo(shot.viewShort),
+		SHOT_LEVEL_LABELS_KO.get(shot.levelLabel) ?? shot.levelLabel,
+		`${shot.focalMm}mm`,
+	].filter(Boolean).join(" · ");
+}
+
+export function moveSequenceSlateKo(segments) {
+	if (!segments.length) return "";
+	if (segments.length === 1) {
+		const seg = segments[0];
+		return `${slateLineKo(seg.from)} → ${slateLineKo(seg.to)} · ${cameraMoveLabelKo(seg.label)}`;
+	}
+	const parts = [slateLineKo(segments[0].from)];
+	for (const seg of segments) parts.push(`${cameraMoveLabelKo(seg.label)} → ${slateLineKo(seg.to)}`);
+	return parts.join(" · ");
+}
+
+/** The hierarchy node id an IK focus lights up. Focus maps stay keyed by the
+ * BONE TOKEN; the row id namespaces the result so each cast member's tree
+ * highlights its own bone (#76). */
+export function hierarchyIdForIkFocus(focus, rowId = "characterA") {
+	if (!focus) return null;
+	const exact = Object.entries(RIG_HIERARCHY_FOCUS)
+		.find(([id, mappedFocus]) =>
+			!["rig.torso", "rig.leftArm", "rig.rightArm", "rig.leftLeg", "rig.rightLeg"].includes(id) &&
+			mappedFocus === focus
+		);
+	return `${rowId}.${exact?.[0] ?? "rig"}`;
+}

package/src/stage-startup-defaults.js

@@ -0,0 +1,182 @@
+import * as THREE from "three";
+import { ko, isKo } from "./locale.js";
+import { SHOT_ASPECT_RATIOS } from "./shot.js";
+import {
+	SCENES_QUARANTINE_KEY,
+	createSceneDocument,
+	DEFAULT_SUBJECT_ONE,
+	DEFAULT_SUBJECT_TWO,
+	loadSceneDocumentFromStorage,
+} from "./scenes.js";
+import { POSE_BONES } from "./poses.js";
+import { isPlaygroundEmbed, takePlaygroundProject } from "./playground.js";
+import { DEFAULT_SCENE_OBJECTS } from "./scene-objects.js";
+
+// Stated the way a crew states a setup: how far back, which side, how high the
+// lens rides, and what glass is on it. Order matters — Medium is the setup a
+// director reaches for first, so it leads.
+export const PRESETS = {
+	medium: { label: ko("Medium", "미디엄"), distance: 2.6, azimuth: 22, elevation: 6, fov: 45, targetY: 1.35, two: false },
+	wide: { label: ko("Wide", "와이드"), distance: 7, azimuth: 25, elevation: 4, fov: 38, targetY: 1.2, two: false },
+	closeup: { label: ko("Close-Up", "클로즈업"), distance: 1.3, azimuth: 16, elevation: 2, fov: 45, targetY: 1.55, two: false },
+	low: { label: ko("Low Angle", "로우 앵글"), distance: 3.5, azimuth: 20, elevation: -14, fov: 50, targetY: 1.1, two: false },
+	high: { label: ko("High Angle", "하이 앵글"), distance: 4.5, azimuth: 20, elevation: 16, fov: 45, targetY: 1.1, two: false },
+};
+
+export const SHOT_ASPECT_PRESETS = Object.freeze({
+	"16:9": Object.freeze({ label: "16:9", aspect: SHOT_ASPECT_RATIOS["16:9"], width: 1920, height: 1080 }),
+	"2.39:1": Object.freeze({ label: "2.39:1", aspect: SHOT_ASPECT_RATIOS["2.39:1"], width: 2390, height: 1000 }),
+	"9:16": Object.freeze({ label: "9:16", aspect: SHOT_ASPECT_RATIOS["9:16"], width: 1080, height: 1920 }),
+	"1:1": Object.freeze({ label: "1:1", aspect: SHOT_ASPECT_RATIOS["1:1"], width: 1080, height: 1080 }),
+	"4:3": Object.freeze({ label: "4:3", aspect: SHOT_ASPECT_RATIOS["4:3"], width: 1440, height: 1080 }),
+	"12:7": Object.freeze({ label: "12:7", aspect: SHOT_ASPECT_RATIOS["12:7"], width: 1536, height: 896, title: "12:7 video-inbetweener ratio" }),
+	"fal 480P": Object.freeze({ label: "fal 480P", aspect: SHOT_ASPECT_RATIOS["fal 480P"], width: 1664, height: 960, title: "Fal H3 480P canvas (832x480)" }),
+});
+// Pre-generated clip shipped with the build so a bridge-less session (a hosted
+// static demo, or `npm run dev:ui`) still shows real generated motion.
+// Root-absolute on purpose: the studio is served from "/app/" while these
+// public files stay at the site root, so a page-relative path would resolve
+// to "/app/models/..." and 404. Vite's base is "/" (own apex domain), so a
+// leading slash is now the correct — and only — form that works from both
+// the dev server and the built site.
+// Per-character rig model: the stage entry's `model` is the FBX file stem in
+// public/models AND the wire rig name sent to ARDY, so mesh and export can
+// never drift apart.
+export const characterModelUrl = (model) => `/models/${model}.fbx`;
+
+/** Shipped rig names as the operator says them, not as the files spell them. */
+export const CHARACTER_MODEL_LABELS = { "y-bot-tpose": "Y Bot", "x-bot-tpose": "X Bot" };
+CHARACTER_MODEL_LABELS["proxy-figure"] = ko("Capsule figure", "캡슐 인물");
+
+/** Sequential ids for spawned characters, collision-free against the cast. */
+export function nextCharacterId(list) {
+	const ids = new Set(list.map((entry) => entry.id));
+	let n = list.length + 1;
+	let id = `char-${n}`;
+	while (ids.has(id)) {
+		n += 1;
+		id = `char-${n}`;
+	}
+	return id;
+}
+export const DEMO_MOTION_URL = "/demo/walk-then-stop.npz";
+export const DEMO_MOTION_PROMPT = "A person walks forward.";
+// How long a deletion keeps offering its one-press Undo. Both toasts use the
+// same window so the two deletion paths feel like one rule.
+export const OBJECT_DELETE_UNDO_MS = 7000;
+export const ASSET_DELETE_UNDO_MS = 7000;
+// Neutral grey clay: the set is the grey workbench, so the figures are grey
+// too, light enough to stand off the deck and the sky.
+export const CLAY = "#bdbec3";
+export const CLAY_B = "#a4a5aa";
+// X Bot's shell is smooth (no raised exoskeleton like Y Bot's), so it gets a
+// brighter, whiter clay to keep it readable against the set.
+export const CLAY_X = "#d0d0d4";
+// Model/role default for a cast member; a user-picked entry.tint always wins
+// over this at render time.
+export const defaultCharacterTint = (entry, index) => (entry.model === "x-bot-tpose" ? CLAY_X : index === 0 ? CLAY : CLAY_B);
+
+/**
+ * The first editor view should read like a blocking desk, not a security
+ * camera at the back of the stage. Keep the selected subject large enough to
+ * judge a pose while leaving a little floor around the feet. This is a pure
+ * framing helper so the seed and any future reset action share the same
+ * distance rule.
+ */
+export function editorFrameForSubject(subject) {
+	const scale = Number.isFinite(subject?.scale) && subject.scale > 0 ? subject.scale : 1;
+	const distance = THREE.MathUtils.clamp(3.5 / scale, 2.8, 4.8);
+	const x = subject?.x ?? 0;
+	const z = subject?.z ?? 0;
+	const target = { x, y: 1.05, z };
+	return {
+		target,
+		position: {
+			x: x + distance * 0.62,
+			y: target.y + distance * 0.34,
+			z: z + distance * 0.78,
+		},
+	};
+}
+
+export const DEFAULT_SUBJECT = DEFAULT_SUBJECT_ONE;
+export const DEFAULT_SUBJECT2 = DEFAULT_SUBJECT_TWO;
+export const DEFAULT_ENVIRONMENT = "a sunlit modern living room";
+export const DEFAULT_CAMERA_POSITION = { x: 0.97, y: 1.62, z: 2.39 };
+export const REST_BONES = Object.fromEntries(POSE_BONES.map((b) => [b.id, [0, 0, 0]]));
+
+// Unity's tool keys. They are free because camera movement now lives behind a
+// held right button. (docs/unity-reference.md §9.2)
+export const GIZMO_HOTKEYS = { KeyW: "move", KeyE: "rotate", KeyR: "scale" };
+
+export const WORKSPACE_LAYOUT_KEY = "cozyclay.workspace-layout.v1";
+export const DEFAULT_WORKSPACE_LAYOUT = Object.freeze({
+	hierarchyWidth: 300,
+	sidebarWidth: 380,
+	timelineHeight: 224,
+	insetWidth: 310,
+	insetHeight: 310,
+	insetCollapsed: false,
+	planZoom: 1,
+});
+
+export function loadWorkspaceLayout() {
+	// The landing-page playground is a fixed, chrome-less layout: the plan
+	// inset starts folded and nothing the visitor drags is written back.
+	if (isPlaygroundEmbed(globalThis.location?.search)) return { ...DEFAULT_WORKSPACE_LAYOUT, insetCollapsed: true };
+	try {
+		const saved = JSON.parse(localStorage.getItem(WORKSPACE_LAYOUT_KEY) || "null");
+		return saved ? { ...DEFAULT_WORKSPACE_LAYOUT, ...saved } : { ...DEFAULT_WORKSPACE_LAYOUT };
+	} catch {
+		return { ...DEFAULT_WORKSPACE_LAYOUT };
+	}
+}
+
+/** Load the Scene envelope once. Legacy single-scene objects are migrated by
+ * scenes.js; App only supplies the familiar starter set for a truly new room. */
+export function loadSceneStartup() {
+	const defaults = () => DEFAULT_SCENE_OBJECTS.map((object) => ({ ...object, footprint: { ...object.footprint } }));
+	// The landing-page playground never reads or writes the visitor's saved
+	// scenes: it opens the preset the page fetched (or an empty room if that
+	// fetch failed) and saving stays off for the whole session.
+	if (isPlaygroundEmbed(globalThis.location?.search)) {
+		const preset = takePlaygroundProject();
+		const document = preset?.document ?? createSceneDocument();
+		if (!preset?.document) document.scenes[0].objects = defaults();
+		return { document, saveBlocked: true, error: null, startupCreatedScene: false, toast: null };
+	}
+	try {
+		const result = loadSceneDocumentFromStorage(localStorage);
+		if (result.status === "future") {
+			const document = createSceneDocument();
+			document.scenes[0].objects = defaults();
+			return {
+				document,
+				saveBlocked: true,
+				error: null,
+				toast: ko("Saved scenes were written by a newer CozyClay — they have been left untouched and this session will not save", "저장된 장면은 더 최신 CozyClay에서 만들어졌어요. 이 세션에서는 건드리지 않고 저장도 하지 않습니다."),
+			};
+		}
+		const document = result.document;
+		if ((result.status === "absent" || result.status === "corrupt") && document.scenes[0].objects.length === 0) {
+			document.scenes[0].objects = defaults();
+		}
+		return {
+			document,
+			saveBlocked: false,
+			error: null,
+			// The startup scene is authored silently; without this flag the
+			// funnel's "scene created" step never fires for a brand-new room.
+			startupCreatedScene: result.status === "absent" || result.status === "corrupt",
+			toast: result.status === "corrupt"
+				? ko(`Saved scenes were unreadable — starting fresh; the old data is kept under ${SCENES_QUARANTINE_KEY}`, `저장된 장면을 읽을 수 없어 새로 시작합니다. 기존 데이터는 ${SCENES_QUARANTINE_KEY}에 보관했어요.`)
+				: result.dropped > 0
+					? (isKo ? `저장된 장면 ${result.dropped}개를 복원하지 못했어요` : `${result.dropped} saved scene(s) could not be restored`)
+					: null,
+		};
+	} catch {
+		const document = createSceneDocument();
+		document.scenes[0].objects = defaults();
+		return { document, saveBlocked: false, error: null, startupCreatedScene: true, toast: null };
+	}
+}

package/src/starter-scenes.js

@@ -11,7 +11,7 @@ export const STARTER_SCENES = Object.freeze([
 	}),
 ]);
 
-export function starterSceneById(id) {
+function starterSceneById(id) {
 	return STARTER_SCENES.find((scene) => scene.id === id) ?? null;
 }
 

package/src/storyboard.js

@@ -2,12 +2,24 @@
 // 2d canvas. The canvas factory is injected so both the app (real canvas)
 // and tests (recording stub) can supply it.
 
-export const STORYBOARD_PROMPT_CHARS = 90;
+const STORYBOARD_PROMPT_CHARS = 90;
+/** The greybox inset beside a stylized panel: half the drawn picture's width
+ * and height (a quarter of its area), in its bottom-right corner. */
+export const STORYBOARD_INSET_SCALE = 0.5;
+
+/** The line under a cell: the panel's own caption when it has one, else the
+ * prompt line the cell was given. */
+function storyboardCellText(shot) {
+	const caption = typeof shot.caption === "string" ? shot.caption.trim() : "";
+	return (caption || String(shot.prompt ?? "")).slice(0, STORYBOARD_PROMPT_CHARS);
+}
 
 /**
  * Compose a storyboard grid canvas.
  * @param {object} args
- * @param {Array<{ title: string, durationSeconds: number, prompt: string, image: CanvasImageSource | null }>} args.shots
+ * @param {Array<{ title: string, durationSeconds: number, prompt: string, image: CanvasImageSource | null, stylized?: CanvasImageSource | null, caption?: string }>} args.shots
+ *   `image` is the greybox frame; with `stylized` the cell shows the stylized
+ *   picture and the greybox as an inset. `caption` wins over `prompt`.
  * @param {number} [args.columns] grid columns, default 3
  * @param {{ width: number, height: number }} [args.cell] per-cell size, default 320x180
  * @param {(width: number, height: number) => { width: number, height: number, getContext: (kind: string) => CanvasRenderingContext2D }} args.createCanvas
@@ -30,7 +42,7 @@ export function composeStoryboard({ shots, columns = 3, cell = { width: 320, hei
 	shots.forEach((shot, i) => {
 		const x = (i % cols) * cell.width;
 		const y = Math.floor(i / cols) * cell.height;
-		const image = shot.image;
+		const image = shot.stylized || shot.image;
 		if (image) {
 			const iw = image.width || image.videoWidth || 1;
 			const ih = image.height || image.videoHeight || 1;
@@ -39,7 +51,14 @@ export function composeStoryboard({ shots, columns = 3, cell = { width: 320, hei
 			const scale = Math.min(availW / iw, availH / ih);
 			const dw = iw * scale;
 			const dh = ih * scale;
-			ctx.drawImage(image, x + pad + (availW - dw) / 2, y + pad + (availH - dh) / 2, dw, dh);
+			const dx = x + pad + (availW - dw) / 2;
+			const dy = y + pad + (availH - dh) / 2;
+			ctx.drawImage(image, dx, dy, dw, dh);
+			if (shot.stylized && shot.image) {
+				const iw2 = dw * STORYBOARD_INSET_SCALE;
+				const ih2 = dh * STORYBOARD_INSET_SCALE;
+				ctx.drawImage(shot.image, dx + dw - iw2, dy + dh - ih2, iw2, ih2);
+			}
 		} else {
 			ctx.fillStyle = "#2a2a32";
 			ctx.fillRect(x + pad, y + pad, cell.width - pad * 2, thumbHeight - pad);
@@ -53,7 +72,7 @@ export function composeStoryboard({ shots, columns = 3, cell = { width: 320, hei
 		ctx.fillStyle = "#9a9aa5";
 		ctx.fillText(`${shot.durationSeconds}s`, textX, textY);
 		textY += 14;
-		ctx.fillText(String(shot.prompt ?? "").slice(0, STORYBOARD_PROMPT_CHARS), textX, textY);
+		ctx.fillText(storyboardCellText(shot), textX, textY);
 	});
 
 	return canvas;

package/src/studio-actions.js

@@ -23,6 +23,18 @@ const sceneId = { sceneId: idSchema };
 const NOT_UNDOABLE = "Scenes are outside the undo history: undo_edit and Ctrl+Z cannot revert this.";
 const SCENE_MOVES = "The open scene changes, so later commands in this message are admitted in it; the receipt's host names it.";
 const characterId = { characterId: idSchema };
+const castOverride = {
+	type: "object",
+	properties: {
+		x: { type: "number" },
+		z: { type: "number" },
+		rot: { type: "number" },
+		posture: { type: "string", enum: ["stand", "sit", "lie"] },
+		pose: { type: "object", properties: {}, required: [], additionalProperties: true },
+	},
+	required: [],
+	additionalProperties: false,
+};
 /** A world floor point in metres; y is the floor. */
 const floorPoint = input({ x: { type: "number" }, z: { type: "number" } });
 const waypointFrame = { ...frame, minimum: 1 };
@@ -34,12 +46,14 @@ const num = { type: "number" };
 const perBone = items => ({ type: "array", items, minItems: 1, maxItems: 3 });
 const quaternion = input({ x: num, y: num, z: num, w: num });
 /** One track's key: the IK state's { q, p, baseQ, basePos, chainP,
- * keepTranslations, blend, pin } with quaternions as {x,y,z,w} and positions
+ * keepTranslations, blend, pin, correctionRange } with quaternions as {x,y,z,w} and positions
  * as {x,y,z}; blend is the key's own correction range in frames (src/ardy/ik.js
  * correctionWeight), absent for the editor's default range; pin is the id of
- * the range pin that baked the key (src/ardy/range-pin.js). */
+ * the range pin that baked the key (src/ardy/range-pin.js). correctionRange
+ * pairs the boundary keys of an explicitly selected interval. */
 const ikTrackKey = input({}, { q: perBone(quaternion), p: StudioSchemas.Vec3, baseQ: perBone(quaternion), basePos: StudioSchemas.Vec3,
 	chainP: perBone(StudioSchemas.Vec3), keepTranslations: { type: "boolean" }, blend: { type: "integer", minimum: 1, maximum: 240 },
+	correctionRange: input({ start: frame, end: frame }),
 	pin: { type: "string", minLength: 1, maxLength: 64 } });
 const ikTracks = input({}, Object.fromEntries([...STUDIO_IK_CHAIN_TRACKS, ...STUDIO_IK_JOINT_TRACKS].map(track => [track, ikTrackKey])));
 /** The bones an object can ride (src/scene-objects.js SCENE_ATTACH_BONES). */
@@ -49,25 +63,40 @@ export const STUDIO_ATTACH_BONES = freezeStudioData(["hips", "spine", "chest", "
 const GUIDE_MODES = freezeStudioData(["off", "thirds", "golden", "center", "safe"]);
 /** The image models the Studio writes Send-to-AI prompts for (src/shot.js IMAGE_MODELS). */
 const AI_IMAGE_MODELS = freezeStudioData(["nano_banana_pro", "nano_banana_2", "gpt_image_2", "seedream_5", "flux_2"]);
+const stillHold = { type: "integer", minimum: 1, maximum: 240 };
+const stillIndex = { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER };
+const STORYBOARD_CAP = "Refused when the stills would run past the 28800-frame timeline.";
 const WAYPOINT_RULES = "Pins sit at least 8 frames apart, the walk between two pins must stay within 0.5-3 m/s, and x/z are clamped to +/-11 m; a pin that breaks a rule is refused with the frame or distance that would work.";
 
 export const STUDIO_ACTIONS = freezeStudioData([
 	{ id: "shot.create", label: "Add shot", kind: "mutation", undoDomain: "shot", input: input(),
-		description: "Add a new shot at the playhead, keyed with the current camera framing (the timeline's + Add shot). Move the playhead first with operate_studio { frame }. When the playhead is inside a shot, the new one goes in the next free gap." },
+		description: "Add a new shot at the playhead, keyed with the current camera framing (the timeline's + Add shot). Move the playhead first with operate_studio { frame }. When the playhead is inside a shot, the new one goes in the next free gap. In a storyboard project it adds a still instead, exactly like shot.createStill with no arguments." },
+	{ id: "shot.createStill", label: "Add still", kind: "mutation", undoDomain: "shot", input: input({}, { caption: { type: "string", maxLength: 500 }, hold: stillHold }),
+		description: `Add a still (a storyboard panel: one picture held for hold frames at 24 fps, default 48, 1-240) after the last still, keyed with the current camera framing. Stills sit end to end from frame 0 in order. ${STORYBOARD_CAP}` },
+	{ id: "shot.setCaption", label: "Set shot caption", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, caption: { type: "string", maxLength: 500 } }),
+		description: "Set a shot's caption (the panel's action or dialogue line), trimmed, at most 500 characters; an empty caption clears it." },
+	{ id: "shot.setCastOverride", label: "Set shot cast override", kind: "mutation", undoDomain: "shot",
+		input: input({ ...shotId, ...characterId, override: { oneOf: [castOverride, { type: "null" }] } }),
+		description: "Set or clear one character's placement and pose override for a shot. Overrides apply only when the character has no installed take; a root path still wins." },
+	{ id: "shot.setHold", label: "Set still hold", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, hold: stillHold }),
+		description: `Set how many frames (1-240 at 24 fps) a still holds; the stills after it move so they stay end to end. Stills only. ${STORYBOARD_CAP}` },
 	{ id: "shot.split", label: "Split shot", kind: "mutation", undoDomain: "shot", input: input(shotId),
 		description: "Cut a shot in two at the playhead. The playhead must be inside that shot, after its first frame; the second half starts at the playhead." },
 	{ id: "shot.duplicate", label: "Duplicate shot", kind: "mutation", undoDomain: "shot", input: input(shotId),
-		description: "Copy a shot, its camera and its keys into the next free gap on the timeline." },
+		description: "Copy a shot, its camera, keys, caption, per-shot cast and stylized image. A still's copy goes right after it and the stills after it move along; a clip's copy goes into the next free gap on the timeline." },
 	{ id: "shot.remove", label: "Delete shot", kind: "mutation", undoDomain: "shot", input: input(shotId),
 		description: "Delete a shot and leave its frames as free-camera time." },
 	{ id: "shot.setRange", label: "Set shot range", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, range: StudioSchemas.FrameRange }),
 		description: "Move a shot's start and end to a half-open frame range. Edges are clamped to the timeline and refused where they would overlap another shot; the receipt's delta shows the range that landed." },
-	{ id: "shot.reorder", label: "Move shot", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, startFrame: frame }),
-		description: "Move a shot in time to start at startFrame, keeping its length and camera keys. Refused (a noop) where it would overlap another shot." },
+	{ id: "shot.reorder", label: "Move shot", kind: "mutation", undoDomain: "shot",
+		input: input(shotId, { startFrame: frame, index: stillIndex }),
+		description: "Move a shot; give exactly one of startFrame or index. With startFrame, a clip moves in time to start there, keeping its length and camera keys (a noop where it would overlap another shot), and a still moves to the place in the still order that frame falls in. With index (stills only), the still moves to that position among the stills (0 is first; past the end means last). Stills stay end to end from frame 0." },
 	{ id: "motion.generateAllBlocks", label: "Generate all blocks", kind: "job", generation: "motion", domain: "motion", background: true, input: input(),
 		description: "Generate the active character's motion from all of its prompt blocks, like the top-bar Generate Motion button when prompt blocks have text. It starts a job and returns status \"started\"; the take lands in the editor when the job finishes. Counts as the one motion generation of this message." },
 	{ id: "character.addWaypoint", label: "Add root waypoint", kind: "mutation", undoDomain: "cast", input: input({ ...characterId, position: floorPoint }, { frame: waypointFrame }),
 		description: `Pin a character's root path: at frame, the character's root stands at position (world x/z metres). Frame 0 is the character's own spot, so pins start at frame 1 and each frame holds one pin. Omit frame to pace the pin at a walk (1.4 m/s) from the previous one. ${WAYPOINT_RULES} Read paths with inspect_studio { scope: "motion" }.` },
+	{ id: "character.move", label: "Move character", kind: "mutation", undoDomain: "cast", input: input(characterId, { x: num, z: num, rot: num }),
+		description: "Move a character's stage placement. Inside a still this writes that panel's cast override; outside a still it changes the stage record." },
 	{ id: "character.moveWaypoint", label: "Move root waypoint", kind: "mutation", undoDomain: "cast", input: input({ ...characterId, frame: waypointFrame, position: floorPoint }),
 		description: `Move the character's root waypoint at frame to a new floor position (world x/z metres), keeping its frame. ${WAYPOINT_RULES}` },
 	{ id: "character.removeWaypoint", label: "Remove root waypoint", kind: "mutation", undoDomain: "cast", input: input({ ...characterId, frame: waypointFrame }),
@@ -96,7 +125,7 @@ export const STUDIO_ACTIONS = freezeStudioData([
 		description: "Show a composition guide over the shot frame: rule of thirds, golden ratio, center cross, safe areas, or off. Overlay only, never in exported pixels; a viewer setting that is never undone." },
 	{ id: "view.setInset", label: "Top-View inset", kind: "transient", input: input({ collapsed: { type: "boolean" } }),
 		description: "Fold (collapsed: true) or unfold the Top-View inset pane over the viewport. A viewer setting that is never undone." },
-	{ id: "export.shotVideo", exposure: "confirm", confirmationReason: "Exporting writes a video file outside the Studio.", label: "Export video (mp4)", kind: "job", timeoutMs: 300_000, input: input({}, shotId),
+	{ id: "export.shotVideo", exposure: "confirm", confirmationReason: "Exporting writes a video file outside the Studio.", label: "Export video (mp4)", kind: "job", timeoutMs: 300_000, input: input({}, { ...shotId, scope: { type: "string", enum: ["timeline", "shot"], description: "timeline: the whole timeline, every shot back to back; shot: one shot (shotId, or the one under the playhead)." } }),
 		description: "Record a shot to an MP4 (camera move and character motion, no editor chrome), like the Export menu's Video (mp4), and ask the browser to download it. With shotId it records that shot's own range; without it, what the menu records: the whole take when there is motion, else the shot under the playhead (else the first shot), keyed from the current camera if it has no keys. Waits until the file is encoded (up to 5 minutes) and answers status \"completed\" with output.fileName and output.frameCount. One export at a time; not a motion generation." },
 	{ id: "scene.create", label: "New scene", kind: "document", input: input(),
 		description: `Add an empty scene (named SCENE 01, SCENE 02, ...) after the others and open it, like the scene menu's New scene. ${SCENE_MOVES} ${NOT_UNDOABLE}` },
@@ -110,6 +139,8 @@ export const STUDIO_ACTIONS = freezeStudioData([
 		description: `Open another scene of the project, like the scene pill's menu; the scene being left keeps its state. ${SCENE_MOVES}` },
 	{ id: "project.save", exposure: "confirm", confirmationReason: "Saving may overwrite a file or open a file picker.", label: "Save project", kind: "document", input: input(),
 		description: "Save the whole project to its current file, like the Project menu's Save Project, and answer status \"completed\" with output.fileName. A browser file picker opens only from the user's own click, so it is refused, with the reason, when the project has no file yet this session or the browser must re-grant access to it; ask the user to press Save Project once. An unnamed project opens the Save dialog for the user to name it. Browsers without file access download the project file instead." },
+	{ id: "project.exportAsAnimation", exposure: "confirm", confirmationReason: "Exporting writes an animation project file outside the Studio.", label: "Export as Animation project", kind: "document", input: input(),
+		description: "Export the current storyboard as a new Animation project file, leaving the storyboard open and unchanged. Still shots become clip shots with their ranges, camera keys, captions, cast overrides and stylized asset references preserved. The browser asks where to save the new .cclayproject or downloads it when file access is unavailable." },
 	{ id: "asset.import", label: "Import asset", kind: "mutation", undoDomain: "objects",
 		input: input({ source: { type: "string", minLength: 1, maxLength: 8_000_000, pattern: "^(data:|https?://)" }, name: { type: "string", minLength: 1, maxLength: 120 },
 			placeAs: { type: "string", enum: ["cutout", "backdrop", "mesh"] } }),
@@ -158,7 +189,9 @@ export function createStudioActionRegistry({ readState } = {}) {
 		if (!Array.isArray(result?.affectedIds) || result.affectedIds.some(value => typeof value !== "string") || typeof result.summary !== "string") {
 			throw new Error(`Studio action ${id} must return { affectedIds, summary }.`);
 		}
-		return { affectedIds: [...result.affectedIds], summary: result.summary, ...(result.output === undefined ? {} : { output: structuredClone(result.output) }) };
+		return { affectedIds: [...result.affectedIds], summary: result.summary, ...(result.output === undefined ? {} : { output: structuredClone(result.output) }),
+			// What the command measured and what it found wrong; the bus puts both on the receipt.
+			...(result.checks === undefined ? {} : { checks: structuredClone(result.checks) }), ...(result.warnings?.length ? { warnings: structuredClone(result.warnings) } : {}) };
 	};
 	const registry = {
 		register(entry) {
@@ -183,7 +216,7 @@ export function createStudioActionRegistry({ readState } = {}) {
 		list(state = readState?.()) {
 			return [...entries.values()].map(entry => {
 				const verdict = availability(entry, state);
-				const row = { id: entry.id, label: entry.label, kind: entry.kind, description: entry.description, exposure: entry.exposure,
+				const row = { id: entry.id, label: entry.label, kind: entry.kind, description: entry.description, exposure: entry.exposure, ...(entry.agentHidden ? { agentHidden: true } : {}),
 					...(entry.timeoutMs === undefined ? {} : { timeoutMs: entry.timeoutMs }), ...(entry.generation ? { generation: entry.generation } : {}) };
 				return verdict === true ? { ...row, available: true, input: entry.input } : { ...row, available: false, reason: verdict };
 			});