cozyclay 2.0.2 → 2.1.0

package/src/object-travel.js

@@ -0,0 +1,224 @@
+import { Euler, Matrix4, Quaternion, Vector3 } from "three";
+import { objectTransformAt } from "./object-path.js";
+import { routeOwnerFor } from "./route-owner.js";
+import { EMPTY_KIND } from "./scene-objects.js";
+
+/**
+ * Travel through the grouping hierarchy.
+ *
+ * A route belongs to one record, but a group is one body: a car built from a
+ * chassis with its cabin, fenders and wheels parented under it has to drive as
+ * a whole when the chassis gets the route. Records stay flat and world-space
+ * (a parent only carries its children while authoring), so the carry happens
+ * here at sample time: every routed ancestor's motion — where its route puts
+ * it, relative to where it was authored — is applied rigidly to everything
+ * under it. Scale never rides along: the motion is the routed record's own
+ * route sample against its own authored pose, both at its own scale.
+ *
+ * The inverse holds for an Empty, which is a pure group node: when it has no
+ * route of its own but a routed descendant owns the group's travel (a car
+ * Empty over its Chassis), it is drawn carried by that descendant's motion, so
+ * its marker and gizmo stay on the car. Ordinary meshes keep their authored
+ * place — only ancestors carry what is below them.
+ *
+ * Carried props are left to the attach frame that already places them: a
+ * record that rides a character is not walked, and neither is an ancestor
+ * that does.
+ */
+
+const DEG = Math.PI / 180;
+
+const scratchPos = new Vector3();
+const scratchQuat = new Quaternion();
+const scratchScale = new Vector3();
+const scratchEuler = new Euler();
+const scratchAuthored = new Matrix4();
+const scratchOwn = new Matrix4();
+const scratchMotion = new Matrix4();
+
+function compose(out, x, y, z, rotX, rot, rotZ, object, order = "XYZ") {
+	scratchPos.set(x, y, z);
+	scratchQuat.setFromEuler(scratchEuler.set(rotX * DEG, rot * DEG, rotZ * DEG, order));
+	scratchScale.set(object.scaleX ?? 1, object.scaleY ?? 1, object.scaleZ ?? 1);
+	return out.compose(scratchPos, scratchQuat, scratchScale);
+}
+
+function authoredMatrix(object, out) {
+	return compose(out, object.x ?? 0, object.y ?? 0, object.z ?? 0, object.rotX ?? 0, object.rot ?? 0, object.rotZ ?? 0, object);
+}
+
+/**
+ * The pose a route sample gives a record, as the Euler triple of
+ * R = Ry(yaw) · Rx(pitch) · Rz(bank), applied as three.js's "YXZ" order: the
+ * yaw turns the body in the world, the pitch tilts it about its own lateral
+ * axis, the bank rolls it about its own forward axis. An authored rotX/rotZ is
+ * the body's own pitch and roll, so it stays about the body's axes however the
+ * heading turns (in the plain XYZ order rotX stayed about world X, and a pitch
+ * became a roll once the route turned). The route's lean rides on top:
+ * `bank` positive = right side down, `pitch` positive = nose up, which is
+ * the opposite sign to rotX (positive rotX tips the nose down).
+ */
+export function travelPose(object, at) {
+	return {
+		rotX: (object.rotX ?? 0) - (at.pitch ?? 0),
+		rot: at.rot ?? object.rot ?? 0,
+		rotZ: (object.rotZ ?? 0) + (at.bank ?? 0),
+	};
+}
+
+/** The record's own route sample as a matrix, or null when it does not travel. */
+function ownTravelMatrix(object, frame, take, out) {
+	if (!object.path) return null;
+	const at = objectTransformAt(object, frame, take);
+	if (!at) return null;
+	const pose = travelPose(object, at);
+	return compose(out, at.x, at.y, at.z, pose.rotX, pose.rot, pose.rotZ, object, "YXZ");
+}
+
+const asLookup = (objects) => {
+	if (objects instanceof Map) return objects;
+	const lookup = new Map();
+	for (const object of objects ?? []) if (object && typeof object.id === "string") lookup.set(object.id, object);
+	return lookup;
+};
+
+/**
+ * The world matrix a record is drawn with at `frame`, or null when neither it
+ * nor any ancestor travels (its authored transform is then the answer).
+ *
+ * @param {Map<string, object>|object[]} objects authored records, by id or as the list
+ */
+/** Parent first, up to the root; stops at a cycle, a missing record or a carried one. */
+function ancestorsOf(lookup, object) {
+	const chain = [];
+	const seen = new Set([object.id]);
+	let parentId = typeof object.parent === "string" ? object.parent : null;
+	while (parentId && !seen.has(parentId)) {
+		seen.add(parentId);
+		const parent = lookup.get(parentId);
+		if (!parent || parent.attach) break;
+		chain.push(parent);
+		parentId = typeof parent.parent === "string" ? parent.parent : null;
+	}
+	return chain;
+}
+
+const scratchRide = new Matrix4();
+
+/** The routed descendant an Empty rides, or null for anything else. */
+function ridden(lookup, object) {
+	if (object.path || object.attach || object.renderer !== EMPTY_KIND) return null;
+	const owner = routeOwnerFor(lookup, object.id);
+	return owner && owner !== object ? owner : null;
+}
+
+export function sceneObjectTravelMatrixAt(objects, id, frame, take = {}, out = new Matrix4()) {
+	const lookup = asLookup(objects);
+	const object = lookup.get(id);
+	if (!object || object.attach) return null;
+	const owner = ridden(lookup, object);
+	// The descendant's whole carry (its own ancestors' motion included, which
+	// the Empty shares), applied to where the Empty was authored. Its own scale
+	// never enters: the carry is rigid.
+	if (owner && sceneObjectCarryMatrixAt(lookup, owner.id, frame, take, scratchRide)) {
+		return out.multiplyMatrices(scratchRide, authoredMatrix(object, scratchAuthored));
+	}
+	const chain = ancestorsOf(lookup, object);
+	let moved = false;
+	scratchMotion.identity();
+	for (let index = chain.length - 1; index >= 0; index -= 1) {
+		const ancestor = chain[index];
+		if (!ownTravelMatrix(ancestor, frame, take, scratchOwn)) continue;
+		scratchMotion.multiply(scratchOwn).multiply(authoredMatrix(ancestor, scratchAuthored).invert());
+		moved = true;
+	}
+	const own = ownTravelMatrix(object, frame, take, scratchOwn);
+	if (!moved && !own) return null;
+	return out.multiplyMatrices(scratchMotion, own ?? authoredMatrix(object, scratchAuthored));
+}
+
+const scratchCarry = new Matrix4();
+
+/**
+ * The rigid motion a record's travel hands to whatever rides it at `frame`:
+ * where it is drawn against where it was authored. Its own scale cancels out,
+ * so a rider keeps its size under a scaled chassis. Null when the record does
+ * not travel (nor anything above it), is missing, or is carried by a character.
+ */
+export function sceneObjectCarryMatrixAt(objects, id, frame, take = {}, out = new Matrix4()) {
+	const lookup = asLookup(objects);
+	const object = lookup.get(id);
+	if (!object || object.attach) return null;
+	if (!sceneObjectTravelMatrixAt(lookup, id, frame, take, out)) return null;
+	return out.multiply(authoredMatrix(object, scratchCarry).invert());
+}
+
+const scratchCarried = new Matrix4();
+const scratchPoint = new Vector3();
+
+/**
+ * Where a point riding `objectId` stands at `frame`: the point (a grouped
+ * character's played root) through the object's carry. The point comes back
+ * unchanged when there is no object or it does not travel; `y` is used for
+ * the carry and returned only when the point had one.
+ */
+export function carriedPointAt(objects, objectId, point, frame, take = {}) {
+	if (!point || !objectId) return point;
+	const carry = sceneObjectCarryMatrixAt(objects, objectId, frame, take, scratchCarried);
+	if (!carry) return point;
+	scratchPoint.set(point.x, point.y ?? 0, point.z).applyMatrix4(carry);
+	return point.y === undefined ? { x: scratchPoint.x, z: scratchPoint.z } : { x: scratchPoint.x, y: scratchPoint.y, z: scratchPoint.z };
+}
+
+const wrapDegrees = (value) => {
+	const wrapped = ((((value + 180) % 360) + 360) % 360) - 180;
+	return wrapped === -180 ? 180 : wrapped;
+};
+
+/**
+ * The records as they stand at `frame`: x/y/z and rotation replaced for every
+ * record that travels on its own route or under a routed ancestor. Untouched
+ * records are returned as-is, and so is the list when nothing moves.
+ */
+export function sceneObjectsAt(objects, frame, take = {}) {
+	if (!objects.some((object) => object.path)) return objects;
+	const lookup = asLookup(objects);
+	const matrix = new Matrix4();
+	const position = new Vector3();
+	const quaternion = new Quaternion();
+	const scale = new Vector3();
+	const euler = new Euler();
+	/** The record for a pose given as a matrix: x/y/z plus the XYZ Euler the records speak. */
+	const recordAt = (object, pose) => {
+		pose.decompose(position, quaternion, scale);
+		const next = { ...object, x: position.x, y: position.y, z: position.z };
+		// A pure turn about the vertical keeps the authored zero pitch/roll and
+		// reads back as one yaw, instead of the 180/x/180 Euler a decompose of a
+		// large yaw gives.
+		if (!(object.rotX ?? 0) && !(object.rotZ ?? 0) && Math.abs(quaternion.x) < 1e-9 && Math.abs(quaternion.z) < 1e-9) {
+			next.rot = wrapDegrees((2 * Math.atan2(quaternion.y, quaternion.w)) / DEG);
+		} else {
+			euler.setFromQuaternion(quaternion, "XYZ");
+			next.rotX = euler.x / DEG;
+			next.rot = euler.y / DEG;
+			next.rotZ = euler.z / DEG;
+		}
+		return next;
+	};
+	return objects.map((object) => {
+		if (object.attach || (!ancestorsOf(lookup, object).some((ancestor) => ancestor.path) && !ridden(lookup, object))) {
+			// Nothing above it travels (and nothing below carries it): the route
+			// sample alone, exactly as before the hierarchy carry — for a carried
+			// prop, in the frame its numbers already live in.
+			const at = objectTransformAt(object, frame, take);
+			if (!at) return object;
+			// A level, upright route is a yaw and a place. One that leans, or a
+			// body with its own pitch/roll, is an orientation (travelPose).
+			if (!at.bank && !at.pitch && !(object.rotX ?? 0) && !(object.rotZ ?? 0)) return { ...object, x: at.x, y: at.y, z: at.z, rot: at.rot ?? object.rot };
+			const pose = travelPose(object, at);
+			return recordAt(object, compose(matrix, at.x, at.y, at.z, pose.rotX, pose.rot, pose.rotZ, object, "YXZ"));
+		}
+		if (!sceneObjectTravelMatrixAt(lookup, object.id, frame, take, matrix)) return object;
+		return recordAt(object, matrix);
+	});
+}

package/src/otio.js

@@ -5,9 +5,10 @@ import { isEffectivelyHidden } from "./scene-objects.js";
 import { sampleAt } from "./sample-at.js";
 import { TIMELINE_FRAME_FPS } from "./scenes.js";
 import { usedSensorHeightMm } from "./shot.js";
+import { shotHold } from "./shot-authoring.js";
 
-export const OTIO_TIMELINE_FPS = TIMELINE_FRAME_FPS;
-export const OTIO_START_TIMECODE = "00:00:00:00";
+const OTIO_TIMELINE_FPS = TIMELINE_FRAME_FPS;
+const OTIO_START_TIMECODE = "00:00:00:00";
 
 const finiteOr = (value, fallback = 0) => Number.isFinite(value) ? value : fallback;
 
@@ -143,6 +144,10 @@ function gap(startFrame, durationFrames) {
 
 function clip(scene, shot) {
 	const metadata = shotMetadata(scene, shot);
+	// A still (storyboard panel) is one picture held for its hold: the clip
+	// runs exactly that many frames and says so.
+	const still = shot.kind === "still";
+	if (still) Object.assign(metadata, { kind: "still", hold: shotHold(shot), caption: typeof shot.caption === "string" ? shot.caption : "" });
 	return {
 		OTIO_SCHEMA: "Clip.1",
 		effects: [],
@@ -156,7 +161,7 @@ function clip(scene, shot) {
 		},
 		metadata: { cozyclay: metadata },
 		name: typeof shot.name === "string" && shot.name.trim() ? shot.name.trim() : "Shot",
-		source_range: timeRange(0, shot.endFrame - shot.startFrame + 1),
+		source_range: timeRange(0, still ? shotHold(shot) : shot.endFrame - shot.startFrame + 1),
 	};
 }
 

package/src/panels/CharacterTransformPanel.jsx

@@ -2,9 +2,17 @@ import Foldout from "./Foldout.jsx";
 import { ko } from "../locale.js";
 import { Vector3Row, Slider } from "../ui.jsx";
 import { useCastTransaction } from '../domains/cast.js';
+import { useContext } from "react";
+import { AppContext } from "../app-context.js";
+import { shotAtFrame } from "../cuts.js";
 
 export default function CharacterTransformPanel({ workflowMode, isCharacterSelection, activeChar }) {
 	const { run, begin, commit } = useCastTransaction();
+	const app = useContext(AppContext);
+	const live = app?.ports.read?.();
+	const still = live ? shotAtFrame(live.shots, live.view.frame) : null;
+	const shown = live?.targets?.get?.(activeChar.id)?.motion || activeChar.layer?.waypoints?.length
+		? activeChar : { ...activeChar, ...(still?.cast?.[activeChar.id] ?? {}) };
 	return (
 <Foldout
 					key={workflowMode === "motion" ? "placement" : "transform"}
@@ -20,11 +28,16 @@ export default function CharacterTransformPanel({ workflowMode, isCharacterSelec
 							<Vector3Row
 								label={ko("Position", "위치")}
 								fields={[
-									{ axis: "X", value: activeChar.x, step: 0.05, precision: 2, scrubRange: 5, onChange: (x) => run('character.update', { characterId: activeChar.id, patch: { x } }), onScrubStart: begin, onScrubEnd: commit },
-									{ axis: "Z", value: activeChar.z, step: 0.05, precision: 2, scrubRange: 5, onChange: (z) => run('character.update', { characterId: activeChar.id, patch: { z } }), onScrubStart: begin, onScrubEnd: commit },
+									{ axis: "X", value: shown.x, step: 0.05, precision: 2, scrubRange: 5, onChange: (x) => run('character.update', { characterId: activeChar.id, patch: { x } }), onScrubStart: begin, onScrubEnd: commit },
+									{ axis: "Z", value: shown.z, step: 0.05, precision: 2, scrubRange: 5, onChange: (z) => run('character.update', { characterId: activeChar.id, patch: { z } }), onScrubStart: begin, onScrubEnd: commit },
 								]}
 							/>
-							<Slider compact label={ko("Rotation", "회전")} min={-180} max={180} step={1} value={activeChar.rot ?? 0} unit="°" onChange={(rot) => run('character.update', { characterId: activeChar.id, patch: { rot } })} />
+							<Slider compact label={ko("Rotation", "회전")} min={-180} max={180} step={1} value={shown.rot ?? 0} unit="°" onChange={(rot) => run('character.update', { characterId: activeChar.id, patch: { rot } })} />
+							{still?.kind === "still" && (
+								<button type="button" className="secondary-button" onClick={() => run("shot.setCastOverride", { shotId: still.id, characterId: activeChar.id, override: null })}>
+									{ko("Use stage placement", "무대 배치 사용")}
+								</button>
+							)}
 						</div>
 					) : (
 						<>
@@ -34,13 +47,18 @@ export default function CharacterTransformPanel({ workflowMode, isCharacterSelec
 							<Vector3Row
 								label={ko("Position", "위치")}
 								fields={[
-									{ axis: "X", value: activeChar.x, step: 0.05, precision: 2, scrubRange: 5, onChange: (x) => run('character.update', { characterId: activeChar.id, patch: { x } }), onScrubStart: begin, onScrubEnd: commit },
+									{ axis: "X", value: shown.x, step: 0.05, precision: 2, scrubRange: 5, onChange: (x) => run('character.update', { characterId: activeChar.id, patch: { x } }), onScrubStart: begin, onScrubEnd: commit },
 									{ axis: "Y", value: activeChar.y ?? 0, step: 0.05, precision: 2, scrubRange: 5, onChange: (y) => run('character.update', { characterId: activeChar.id, patch: { y } }), onScrubStart: begin, onScrubEnd: commit },
-									{ axis: "Z", value: activeChar.z, step: 0.05, precision: 2, scrubRange: 5, onChange: (z) => run('character.update', { characterId: activeChar.id, patch: { z } }), onScrubStart: begin, onScrubEnd: commit },
+									{ axis: "Z", value: shown.z, step: 0.05, precision: 2, scrubRange: 5, onChange: (z) => run('character.update', { characterId: activeChar.id, patch: { z } }), onScrubStart: begin, onScrubEnd: commit },
 								]}
 							/>
-							<Slider compact label={ko("Rotation", "회전")} min={-180} max={180} step={1} value={activeChar.rot ?? 0} unit="°" onChange={(rot) => run('character.update', { characterId: activeChar.id, patch: { rot } })} />
+							<Slider compact label={ko("Rotation", "회전")} min={-180} max={180} step={1} value={shown.rot ?? 0} unit="°" onChange={(rot) => run('character.update', { characterId: activeChar.id, patch: { rot } })} />
 							<Slider compact label={ko("Scale", "크기")} min={0.2} max={3} step={0.05} value={activeChar.scale ?? 1} unit="×" onChange={(scale) => run('character.update', { characterId: activeChar.id, patch: { scale } })} />
+							{still?.kind === "still" && (
+								<button type="button" className="secondary-button" onClick={() => run("shot.setCastOverride", { shotId: still.id, characterId: activeChar.id, override: null })}>
+									{ko("Use stage placement", "무대 배치 사용")}
+								</button>
+							)}
 						</>
 					)}
 				</Foldout>

package/src/panels/ObjectTransformPanel.jsx

@@ -4,9 +4,10 @@ import Foldout from "./Foldout.jsx";
 import { ko, isKo } from "../locale.js";
 import { Field, Vector3Row } from "../ui.jsx";
 import { sceneObjectNameDisplayKo } from "../app-stage.jsx";
-import { MESH_KIND, CUTOUT_KIND, CUTOUT_DEFAULT_HEIGHT, OBJECT_COLORS, normalizeObjectColor } from "../scene-objects.js";
+import { MESH_KIND, CUTOUT_KIND, EMPTY_KIND, SCULPT_KIND, CUTOUT_DEFAULT_HEIGHT, OBJECT_COLORS, normalizeObjectColor } from "../scene-objects.js";
 import { MESH_HEIGHT_MIN } from "../scene-mesh.js";
 import { autoColorHex } from "../auto-color.js";
+import { isImeComposing } from "../ime.js";
 
 export default function ObjectTransformPanel({
 	selectedSceneObject, snapEnabled, setSnapEnabled, attachTargetLabel,
@@ -39,7 +40,7 @@ export default function ObjectTransformPanel({
 		? ['run.update', { txId, args: { id: selectedSceneObject.id, patch } }]
 		: ['object.update', { id: selectedSceneObject.id, patch }];
 	const endKey = event => {
-		if (event.key === 'Enter' || event.key === 'Escape') {
+		if ((event.key === 'Enter' && !isImeComposing(event)) || event.key === 'Escape') {
 			event.stopPropagation(); finish(event.key === 'Enter'); setObjectColorDraft(null);
 		}
 	};
@@ -452,7 +453,7 @@ export default function ObjectTransformPanel({
 										</p>
 									</>
 								)}
-								{selectedSceneObject.renderer !== CUTOUT_KIND && (selectedSceneObject.renderer !== MESH_KIND || selectedSceneObject.clay) && (
+								{selectedSceneObject.renderer !== CUTOUT_KIND && selectedSceneObject.renderer !== EMPTY_KIND && selectedSceneObject.renderer !== SCULPT_KIND && (selectedSceneObject.renderer !== MESH_KIND || selectedSceneObject.clay) && (
 									// One swatch shows the colour; the row opens only when you want
 									// to change it, instead of six chips sitting there all day.
 									<details className="object-colors-pop">

package/src/panels/PoseImagePanel.jsx

@@ -0,0 +1,205 @@
+import { useEffect, useReducer, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import Foldout from "./Foldout.jsx";
+import { ko, isKo } from "../locale.js";
+import { readReferenceImage } from "./ReferenceImageField.jsx";
+import { createHttpTransport } from "../workflow/agent-client.js";
+import "./pose-image.css";
+
+// The sidecar accepts at most 6 references per request, shared with the scene's identity and
+// environment sheets.
+const REFERENCES_MAX = 6;
+const USER_REFERENCES_MAX = 4;
+const RESULTS_KEPT = 8;
+
+// Module-level so leaving Pose mode (which unmounts the Details pane) keeps the references, the
+// prompt, the results and an in-flight generation.
+// `shot` is the pinned capture ({ dataUrl, references }): Generate sends exactly what the panel shows.
+const store = { source: "view", refs: [], prompt: "", shot: null, results: [], selected: 0, busySince: null, error: "", listeners: new Set() };
+function setPoseImageState(patch) {
+	Object.assign(store, patch);
+	for (const listener of store.listeners) listener();
+}
+
+function poseImageErrorMessage(error) {
+	if (error?.status === 401 || error?.code === "auth") return ko("Sign in with ChatGPT in the Agent panel first.", "먼저 Agent 패널에서 ChatGPT로 로그인하세요.");
+	return isKo ? `생성 실패 — ${error?.message || "알 수 없는 오류"}` : `Generation failed — ${error?.message || "unknown error"}`;
+}
+
+async function generatePoseImage(capturePoseImage) {
+	const prompt = store.prompt.trim();
+	if (!prompt || store.busySince) return;
+	const shot = store.shot ?? capturePoseImage?.(store.source);
+	if (!shot) { setPoseImageState({ error: ko("The shot renderer is not ready yet.", "샷 렌더러가 아직 준비되지 않았어요.") }); return; }
+	const references = [
+		...shot.references,
+		...store.refs.map((dataUrl, index) => ({ role: "reference", name: String(index + 1), dataUrl })),
+	];
+	if (references.length > REFERENCES_MAX) {
+		setPoseImageState({ shot, error: isKo
+			? `참조 이미지는 최대 ${REFERENCES_MAX}장이에요 (인물·환경 참조 ${shot.references.length}장 포함).`
+			: `At most ${REFERENCES_MAX} reference images (${shot.references.length} identity/environment included).` });
+		return;
+	}
+	setPoseImageState({ shot, busySince: Date.now(), error: "" });
+	try {
+		const output = await createHttpTransport().image({ prompt, imageDataUrl: shot.dataUrl, references, composition: "frame", quality: "auto" });
+		setPoseImageState({ results: [{ dataUrl: output.dataUrl, prompt, at: Date.now() }, ...store.results].slice(0, RESULTS_KEPT), selected: 0 });
+	} catch (error) {
+		setPoseImageState({ error: poseImageErrorMessage(error) });
+	} finally {
+		setPoseImageState({ busySince: null });
+	}
+}
+
+export default function PoseImagePanel({ hidden, capturePoseImage }) {
+	const [, rerender] = useReducer((tick) => tick + 1, 0);
+	const [viewing, setViewing] = useState(false);
+	const fileRef = useRef(null);
+	useEffect(() => {
+		store.listeners.add(rerender);
+		return () => { store.listeners.delete(rerender); };
+	}, []);
+	useEffect(() => {
+		if (!store.busySince) return undefined;
+		const timer = setInterval(rerender, 1000);
+		return () => clearInterval(timer);
+	}, [store.busySince]);
+
+	const { source, refs, prompt, shot, results, selected, busySince, error } = store;
+	const capture = (next = source) => setPoseImageState({ source: next, shot: capturePoseImage?.(next) ?? null });
+	const result = results[selected] ?? null;
+	const elapsed = busySince ? Math.max(0, Math.round((Date.now() - busySince) / 1000)) : 0;
+	const addFiles = async (files) => {
+		const room = USER_REFERENCES_MAX - store.refs.length;
+		const picked = [...files].filter((file) => file.type.startsWith("image/")).slice(0, room);
+		try {
+			const read = await Promise.all(picked.map((file) => readReferenceImage(file)));
+			setPoseImageState({ refs: [...store.refs, ...read].slice(0, USER_REFERENCES_MAX), error: "" });
+		} catch (failure) {
+			setPoseImageState({ error: isKo ? `이미지를 불러오지 못했어요 — ${failure.message}` : `Could not load that image — ${failure.message}` });
+		}
+	};
+
+	return (
+		<Foldout hidden={hidden} title={ko("Image from pose", "포즈로 이미지 생성")}>
+			<div className="pose-image" data-testid="pose-image">
+				<div className="pose-image-frame">
+					<div className="pose-image-source" role="radiogroup" aria-label={ko("Frame source", "프레임 시점")}>
+						{[["view", ko("Current view", "지금 보는 화면")], ["shot", ko("Shot camera", "샷 카메라")]].map(([id, label]) => (
+							<button key={id} type="button" role="radio" aria-checked={source === id} data-active={source === id ? "true" : undefined}
+								data-testid={`pose-image-source-${id}`} onClick={() => capture(id)}>{label}</button>
+						))}
+					</div>
+					<div className="pose-image-label">
+						<span>{shot ? ko("This frame is sent", "이 프레임으로 생성해요") : source === "view" ? ko("Frame the viewport, then capture", "뷰포트를 맞춘 뒤 캡처") : ko("The shot camera's view", "샷 카메라 시점")}</span>
+						<button type="button" className="btn ghost small" data-testid="pose-image-capture" onClick={() => capture()}>
+							{shot ? ko("Recapture", "다시 캡처") : ko("Capture", "캡처")}
+						</button>
+					</div>
+					{shot
+						? <img className="pose-image-shot" src={shot.dataUrl} alt={ko("The frame sent to the image model", "이미지 모델에 보낼 프레임")} />
+						: <p className="inspector-hint">{ko("Not captured yet — Generate captures this view.", "아직 캡처 전 — 생성하면 지금 화면을 캡처해요.")}</p>}
+				</div>
+
+				<div className="pose-image-label"><span>{ko("References", "참조 이미지")}</span><small>{refs.length}/{USER_REFERENCES_MAX}</small></div>
+				<div className="pose-image-refs"
+					onDragOver={(event) => { if (event.dataTransfer?.types?.includes("Files")) event.preventDefault(); }}
+					onDrop={(event) => { event.preventDefault(); addFiles(event.dataTransfer?.files ?? []); }}>
+					{refs.map((dataUrl, index) => (
+						<div key={index} className="pose-image-ref">
+							<img src={dataUrl} alt={isKo ? `참조 ${index + 1}` : `Reference ${index + 1}`} />
+							<button type="button" className="pose-image-ref-remove" aria-label={ko("Remove reference", "참조 삭제")}
+								onClick={() => setPoseImageState({ refs: store.refs.filter((_, at) => at !== index) })}>×</button>
+						</div>
+					))}
+					{refs.length < USER_REFERENCES_MAX && (
+						<button type="button" className="pose-image-ref pose-image-ref-add" data-testid="pose-image-add-ref"
+							title={ko("Add a reference picture (or drop one here)", "참조 이미지 추가 (여기로 끌어놓아도 돼요)")}
+							onClick={() => fileRef.current?.click()}>＋</button>
+					)}
+				</div>
+				<input ref={fileRef} type="file" accept="image/*" multiple className="multimodel-file-input" data-testid="pose-image-ref-input"
+					onChange={(event) => { const files = [...(event.target.files ?? [])]; event.target.value = ""; addFiles(files); }} />
+
+				<textarea
+					className="pose-image-prompt"
+					data-testid="pose-image-prompt"
+					rows={3}
+					value={prompt}
+					placeholder={ko("Describe the image — e.g. a knight in silver armour, dusk light, cinematic", "어떤 이미지인지 적어 주세요 — 예: 은빛 갑옷의 기사, 해질녘 빛, 영화 같은 톤")}
+					onChange={(event) => setPoseImageState({ prompt: event.target.value })}
+					onKeyDown={(event) => { if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) { event.preventDefault(); generatePoseImage(capturePoseImage); } }}
+				/>
+				<button type="button" className="btn primary full" data-testid="pose-image-generate"
+					disabled={!prompt.trim() || Boolean(busySince)}
+					onClick={() => generatePoseImage(capturePoseImage)}>
+					{busySince ? (isKo ? `생성 중… ${elapsed}초` : `Generating… ${elapsed}s`) : ko("Generate image", "이미지 생성")}
+				</button>
+				{error && <p className="inspector-hint pose-image-error" role="status" data-testid="pose-image-error">{error}</p>}
+
+				{result && (
+					<div className="pose-image-result" data-testid="pose-image-result">
+						<button type="button" className="pose-image-result-open" data-testid="pose-image-open"
+							title={ko("View larger", "크게 보기")} onClick={() => setViewing(true)}>
+							<img src={result.dataUrl} alt={result.prompt} />
+						</button>
+						<div className="pose-image-result-actions">
+							<a className="btn ghost small" href={result.dataUrl} download={`cozyclay-pose-${result.at}.png`}>{ko("Download", "다운로드")}</a>
+							<button type="button" className="btn ghost small" disabled={refs.length >= USER_REFERENCES_MAX}
+								onClick={() => setPoseImageState({ refs: [...store.refs, result.dataUrl].slice(0, USER_REFERENCES_MAX) })}>
+								{ko("Use as reference", "참조로 쓰기")}
+							</button>
+						</div>
+						{results.length > 1 && (
+							<div className="pose-image-history">
+								{results.map((entry, index) => (
+									<button key={entry.at} type="button" data-active={index === selected ? "true" : undefined}
+										title={entry.prompt} onClick={() => setPoseImageState({ selected: index })}>
+										<img src={entry.dataUrl} alt="" />
+									</button>
+								))}
+							</div>
+						)}
+					</div>
+				)}
+			</div>
+			{viewing && result && createPortal(
+				<PoseImageViewer results={results} selected={selected} onSelect={(index) => setPoseImageState({ selected: index })} onClose={() => setViewing(false)} />,
+				document.body,
+			)}
+		</Foldout>
+	);
+}
+
+function PoseImageViewer({ results, selected, onSelect, onClose }) {
+	const entry = results[selected];
+	useEffect(() => {
+		const onKey = (event) => {
+			if (event.key === "Escape") onClose();
+			else if (event.key === "ArrowLeft" && selected < results.length - 1) onSelect(selected + 1);
+			else if (event.key === "ArrowRight" && selected > 0) onSelect(selected - 1);
+			else return;
+			event.preventDefault();
+			event.stopPropagation();
+		};
+		window.addEventListener("keydown", onKey, true);
+		return () => window.removeEventListener("keydown", onKey, true);
+	}, [results.length, selected, onSelect, onClose]);
+	return (
+		<div className="pose-image-viewer" role="dialog" aria-modal="true" aria-label={ko("Generated image", "생성된 이미지")} data-testid="pose-image-viewer"
+			onClick={(event) => { if (event.target === event.currentTarget) onClose(); }}>
+			<figure className="pose-image-viewer-body">
+				<img src={entry.dataUrl} alt={entry.prompt} />
+				<figcaption>
+					<span className="pose-image-viewer-prompt">{entry.prompt}</span>
+					{results.length > 1 && <span className="pose-image-viewer-count">{results.length - selected}/{results.length}</span>}
+					<a className="btn ghost small" href={entry.dataUrl} download={`cozyclay-pose-${entry.at}.png`}>{ko("Download", "다운로드")}</a>
+					<button type="button" className="btn ghost small" data-testid="pose-image-viewer-close" onClick={onClose}>{ko("Close", "닫기")}</button>
+				</figcaption>
+			</figure>
+			{selected < results.length - 1 && <button type="button" className="pose-image-viewer-nav prev" aria-label={ko("Older", "이전")} onClick={() => onSelect(selected + 1)}>‹</button>}
+			{selected > 0 && <button type="button" className="pose-image-viewer-nav next" aria-label={ko("Newer", "다음")} onClick={() => onSelect(selected - 1)}>›</button>}
+		</div>
+	);
+}

package/src/panels/PromptBlocksPanel.jsx

@@ -21,9 +21,11 @@ export default function PromptBlocksPanel({
 	readinessState, ardyRunning, cancelArdy, ardyStatus, ardyOutcome,
 }) {
 	const { run, begin, commit, characterId } = useCastTransaction();
-	const { refineDisabledReason, workflowMode } = useStudioShell();
+	const { refineDisabledReason, workflowMode, previsMode } = useStudioShell();
 	const selectedClip = promptClips.find((clip) => clip.id === selectedPromptId) ?? null;
 	const refineReason = refineDisabledReason();
+	// A storyboard has no prompt blocks to author or edit.
+	if (previsMode === "storyboard") return null;
 	// Generate, Start over, Take it again and Add block live in the top bar's
 	// Generate Motion button and its caret menu, their one home (R1).
 	return (

package/src/panels/ProxyFigurePanel.jsx

@@ -0,0 +1,56 @@
+import Foldout from "./Foldout.jsx";
+import { ko } from "../locale.js";
+import { POSTURES, isProxyFigure } from "../scenes.js";
+import { useBus, AppContext } from "../app-context.js";
+import { useContext } from "react";
+import { shotAtFrame } from "../cuts.js";
+
+const POSTURE_LABELS = {
+	stand: () => ko("Stand", "서기"),
+	sit: () => ko("Sit", "앉기"),
+	lie: () => ko("Lie", "눕기"),
+};
+
+// Side-on silhouettes on a 24 grid, the stroke family of the shell's icons.
+const POSTURE_GLYPHS = {
+	stand: "M12 3.5a2 2 0 1 1 0 4 2 2 0 1 1 0-4z M12 9.5v11",
+	sit: "M10 4a2 2 0 1 1 0 4 2 2 0 1 1 0-4z M10 10v6h6v4.5",
+	lie: "M4 13a2 2 0 1 1 0 4 2 2 0 1 1 0-4z M8 15h12.5",
+};
+
+/** Details for a capsule figure: it has no rig and no bones, so the one body
+ * choice is its posture. Rig figures never see this panel. */
+export default function ProxyFigurePanel({ isCharacterSelection, activeChar }) {
+	const { run } = useBus();
+	const app = useContext(AppContext);
+	const live = app?.ports.read?.();
+	const shot = live ? shotAtFrame(live.shots, live.view.frame) : null;
+	const selectedPosture = live?.targets?.get?.(activeChar.id)?.motion || activeChar.layer?.waypoints?.length
+		? activeChar.posture : shot?.cast?.[activeChar.id]?.posture ?? activeChar.posture;
+	if (!isProxyFigure(activeChar)) return null;
+	return (
+		<Foldout hidden={!isCharacterSelection} title={ko("Capsule figure", "캡슐 인물")}>
+			<div className="rig-picker" role="radiogroup" aria-label={ko("Posture", "자세")} data-testid="proxy-posture" style={{ gridTemplateColumns: "repeat(3, minmax(0, 1fr))" }}>
+				{POSTURES.map((posture) => (
+					<button
+						type="button"
+						key={posture}
+						role="radio"
+						aria-checked={selectedPosture === posture}
+						className={"rig-option" + (selectedPosture === posture ? " active" : "")}
+						data-posture={posture}
+						onClick={() => {
+							if (selectedPosture === posture) return;
+							run("character.update", { characterId: activeChar.id, patch: { posture } });
+						}}
+					>
+						<svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round">
+							<path d={POSTURE_GLYPHS[posture]} />
+						</svg>
+						<span>{POSTURE_LABELS[posture]()}</span>
+					</button>
+				))}
+			</div>
+		</Foldout>
+	);
+}

package/src/panels/ReferenceImageField.jsx

@@ -4,7 +4,7 @@ import { ASSET_IMAGE_TYPES, downscaleTarget } from "../scene-assets.js";
 
 const REFERENCE_IMAGE_MAX_DIMENSION = 1024;
 
-async function readReferenceImage(file, { maxDimension = REFERENCE_IMAGE_MAX_DIMENSION } = {}) {
+export async function readReferenceImage(file, { maxDimension = REFERENCE_IMAGE_MAX_DIMENSION } = {}) {
 	if (!file) throw new Error("No file");
 	if (!ASSET_IMAGE_TYPES.includes(String(file.type).toLowerCase())) {
 		throw new Error("unsupported image type");