cozyclay 3.1.0 → 3.1.2

package/src/shell/preference-pages.jsx

@@ -0,0 +1,72 @@
+import { getAnalyticsOptOut, setAnalyticsOptOut } from "../analytics.js";
+import { loadAutoColor, saveAutoColor } from "../auto-color.js";
+import { readStoredGridView, writeStoredGridView } from "../grid-view.js";
+import { ko } from "../locale.js";
+import ExportFolderPreference from "./ExportFolderPreference.jsx";
+import {
+	LanguageControls,
+	PreferenceRow,
+	PreferenceSection,
+	ReadonlyHotkeys,
+	ThemeControls,
+	ToggleControl,
+} from "./preference-controls.jsx";
+
+export function preferenceSection(section, props) {
+	const { autoColor, setAutoColor, analyticsOptOut, setAnalyticsOptOutState, gridView, setGridView } = props;
+
+	switch (section) {
+		case "Appearance":
+			return (
+				<>
+					<PreferenceSection title={ko("Display", "표시")}>
+						<PreferenceRow title={ko("Language", "언어")} description={ko("Choose the labels used throughout the editor.", "에디터에서 사용할 언어를 선택하세요.")}>
+							<LanguageControls />
+						</PreferenceRow>
+						<PreferenceRow title={ko("Theme", "테마")} description={ko("Dark keeps the studio dim around the stage; Light uses bright glass panels.", "다크는 무대 주변을 어둡게, 라이트는 밝은 유리 패널을 써요.")}>
+							<ThemeControls />
+						</PreferenceRow>
+					</PreferenceSection>
+					<PreferenceSection title={ko("Editor", "에디터")}>
+						<PreferenceRow title={ko("Auto colour", "자동 색")} description={ko("Give scene objects stable display colours.", "씬 오브젝트에 고정된 표시 색을 사용해요.")}>
+							<ToggleControl pressed={autoColor} onChange={(value) => { setAutoColor(value); saveAutoColor(value); }} label={ko("Auto colour", "자동 색")} testid="preferences-auto-color" />
+						</PreferenceRow>
+						<PreferenceRow title={ko("Anonymous analytics", "익명 사용 통계")} description={ko("Help improve CozyClay with anonymous product events.", "익명 제품 이벤트로 CozyClay 개선을 도와요.")}>
+							<ToggleControl
+								pressed={!analyticsOptOut}
+								onChange={async (value) => setAnalyticsOptOutState(await setAnalyticsOptOut(!value))}
+								label={ko("Anonymous analytics", "익명 사용 통계")}
+								testid="settings-analytics"
+							/>
+						</PreferenceRow>
+					</PreferenceSection>
+				</>
+			);
+		case "Viewport":
+			return (
+				<PreferenceSection>
+					<PreferenceRow title={ko("Reference grid", "기준 그리드")} description={ko("Use a dark reference grid instead of the clay deck.", "클레이 데크 대신 어두운 기준 그리드를 사용해요.")}>
+						<ToggleControl pressed={gridView} onChange={(value) => { setGridView(value); writeStoredGridView(globalThis.localStorage, value); }} label={ko("Reference grid", "기준 그리드")} testid="preferences-grid" />
+					</PreferenceRow>
+				</PreferenceSection>
+			);
+		case "Export":
+			return (
+				<PreferenceSection>
+					<ExportFolderPreference />
+				</PreferenceSection>
+			);
+		case "Hotkeys":
+			return (
+				<PreferenceSection>
+					<p className="v2-preferences__section-note">{ko("Shortcuts are read-only here. They stay active whenever focus is outside a text field.", "단축키는 여기서 읽기 전용이에요. 텍스트 입력란 밖에서 항상 사용할 수 있어요.")}</p>
+					<ReadonlyHotkeys />
+				</PreferenceSection>
+			);
+		default:
+			return null;
+	}
+}
+
+// Kept here so the dialog can load a new setting's initial value lazily.
+export { getAnalyticsOptOut, loadAutoColor, readStoredGridView };

package/src/shell/preferences.css

@@ -623,3 +623,49 @@
 		grid-template-columns: 1fr;
 	}
 }
+
+/* Export folder: full-width row because folder names and three controls do not
+   fit the 240px control column used by toggles and language pairs. */
+.v2-preferences .v2-preferences__row--full .v2-preferences__row-copy {
+	margin-bottom: var(--sp-2, 12px);
+}
+
+.v2-preferences .v2-preferences__row--full .v2-preferences__row-control {
+	justify-content: flex-start;
+	flex-wrap: wrap;
+	width: 100%;
+}
+
+.v2-preferences .v2-preferences__export-folder {
+	display: flex;
+	flex-direction: column;
+	align-items: flex-start;
+	gap: var(--sp-1, 8px);
+	min-width: 0;
+	width: 100%;
+}
+
+.v2-preferences .v2-preferences__export-folder .v2-preferences__language-controls {
+	justify-content: flex-start;
+}
+
+.v2-preferences .v2-preferences__export-folder-name {
+	color: var(--text-1, #e4e4e7);
+	font-size: var(--prefs-ui-size, 12px);
+	line-height: 1.35;
+	overflow-wrap: anywhere;
+}
+
+.v2-preferences .v2-preferences__export-folder-status {
+	color: var(--select, #e8a33d);
+	font-size: var(--prefs-secondary-size, 11px);
+	line-height: 1.35;
+}
+
+.v2-preferences .v2-preferences__export-folder-note {
+	display: block;
+	margin-top: var(--sp-1, 8px);
+	color: var(--text-3, #636369);
+	font-size: var(--prefs-secondary-size, 11px);
+	line-height: 1.35;
+}

package/src/shot-prompt.js

@@ -1,20 +1,40 @@
 // Builds the labelled text prompt sent alongside a reference clip when a shot
-// goes to an image or video model. Pure string building: no DOM, no imports.
+// goes to an image or video model. Pure string building: no DOM; the only
+// import is the editor's own lens math, so the prompt and the viewport share
+// one focal <-> fov calibration.
+import { fovToFocalMm, shotAspectRatio } from "./shot.js";
 
 const CAMERA_FOLLOWS_REFERENCE = "follow the reference clip's framing and camera motion exactly";
 const NEUTRAL_LOOK = "clay previs, neutral look";
 const MOTION_LINE = "motion and blocking come from the reference; keep timing";
 
-// FOV degrees -> 35mm-equivalent focal length -> shot-size word.
-// A wide field of view reads as a wide shot; a narrow one as a long shot.
-export function shotSizeFromFov(fovDeg) {
-	if (!Number.isFinite(fovDeg) || fovDeg <= 0) return "normal";
-	const equivalentFocalMm = 18 / Math.tan((fovDeg * Math.PI) / 360);
-	if (equivalentFocalMm <= 20) return "wide";
-	if (equivalentFocalMm <= 40) return "normal";
+// Focal length (on the editor's filmback) -> lens word, in crew terms:
+// under 35 mm reads wide, 35-50 mm normal, longer than 50 mm long.
+export function lensWordFromFocalMm(focalMm) {
+	if (!Number.isFinite(focalMm) || focalMm <= 0) return "normal";
+	if (focalMm < 35) return "wide";
+	if (focalMm <= 50) return "normal";
 	return "long";
 }
 
+// FOV degrees -> focal length through the editor's own calibration
+// (shot.js fovToFocalMm on the given filmback) -> lens word. No second,
+// independently calibrated conversion: the word matches the lens the editor
+// reports for that field of view.
+export function shotSizeFromFov(fovDeg, filmback = {}) {
+	if (!Number.isFinite(fovDeg) || fovDeg <= 0) return "normal";
+	const focalMm = fovToFocalMm((fovDeg * Math.PI) / 180, filmback.sensorId, filmback.aspectRatio);
+	// Round to 0.1 mm so a lens that round-trips through fov keeps its word.
+	return lensWordFromFocalMm(Math.round(focalMm * 10) / 10);
+}
+
+// The editor already reports the focal length it framed with; only a meta
+// without one falls back to converting its fov on the meta's filmback.
+function lensWord(meta) {
+	if (Number.isFinite(meta.focalMm) && meta.focalMm > 0) return lensWordFromFocalMm(meta.focalMm);
+	return shotSizeFromFov(meta.fovDeg, { sensorId: meta.sensorId, aspectRatio: shotAspectRatio(meta.aspect) });
+}
+
 function secondsText(seconds) {
 	return `${Number(seconds.toFixed(2))}s`;
 }
@@ -68,7 +88,7 @@ export function buildShotPrompt(meta, options = {}) {
 
 	const lines = [
 		`SHOT: ${meta.shotTitle || "untitled shot"}, ${secondsText(seconds)}, ${meta.aspect || ""}`.trimEnd(),
-		`LENS: ${meta.focalMm}mm, ${shotSizeFromFov(meta.fovDeg)} shot`,
+		`LENS: ${meta.focalMm}mm, ${lensWord(meta)} shot`,
 		referenceOwnsCamera ? `CAMERA: ${CAMERA_FOLLOWS_REFERENCE}` : `CAMERA: ${cameraWords(meta.cameraMove)}`,
 		`LIGHT: ${lightWords(meta.keyLight)}`,
 		`CAST: ${(meta.cast || []).map((member) => member.name).join(", ") || "none"}`,

package/src/studio-actions.js

@@ -130,7 +130,7 @@ export const STUDIO_ACTIONS = freezeStudioData([
 	{ id: "view.setGhosts", label: "Ghosts", kind: "transient", input: input({ mode: { type: "string", enum: ["off", "step", "keys"] } }, { count: { type: "integer", minimum: 1, maximum: 6 }, step: { type: "integer", minimum: 1, maximum: 24 } }),
 		description: "Onion skin in the editor viewport, like the View menu's Ghosts: translucent poses of the active character's installed take, count (1-6, default 3) before the playhead in blue and as many after it in orange, fading with distance in time; props the take carries (a kit's bat) ghost with the body. mode step spaces them every step frames (1-24, default 4), keys puts them on the spec's key frames, off hides them; e.g. { mode: \"step\", count: 3, step: 4 }. An editor overlay: never in capture_frame, exports or contact sheets (verify_result ghosts: true draws them on a views sheet). A viewer setting: never saved or 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, 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." },
+		description: "Record a shot to an MP4 (camera move and character motion, no editor chrome), like the Export menu's Video (mp4), and hand it to the configured export folder or, when none is usable, the browser download. 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}` },
 	{ id: "scene.duplicate", label: "Duplicate scene", kind: "document", input: input(sceneId),
@@ -152,7 +152,7 @@ export const STUDIO_ACTIONS = freezeStudioData([
 	{ id: "object.duplicate", label: "Duplicate object", kind: "mutation", undoDomain: "objects", input: input({}, { objectId: idSchema }),
 		description: "Copy a scene object (the selected one when objectId is omitted) and place the copy half a metre beside it." },
 	{ id: "ai.prepareShot", label: "Send to AI", kind: "job", input: input({}, { mode: { type: "string", enum: ["image", "video"] }, model: { type: "string", enum: AI_IMAGE_MODELS } }),
-		description: "Prepare the Studio's Send-to-AI package for the shot under the playhead (else the current camera): the prompt for an external image or video model, written from the shot's camera, cast, poses, environment and style, plus reference frames rendered from the shot camera (its first and last camera key when it has keys). No AI service is called. mode \"image\" is a still, \"video\" a shot with its camera move; model is the image model the prompt is written for (image mode only). Each omitted choice keeps the Studio's current one; a given one becomes it. The Studio opens its result panel, where the user copies the prompt and downloads the frames; the frame images stay there and are not in the answer. Answers status \"completed\" with output.prompt, mode, modelLabel, shot (id, name, range), aspectRatio, cameraMode and referenceFrames (how many frames the panel shows). Changes nothing in the scene; not a motion generation." },
+		description: "Prepare the Studio's Send-to-AI package for the shot under the playhead (else the current camera): the prompt for an external image or video model, written from the shot's camera, cast, poses, environment and style, plus reference frames rendered from the shot camera (its first and last camera key when it has keys). No AI service is called. mode \"image\" is a still, \"video\" a shot with its camera move; model is the image model the prompt is written for (image mode only). Each omitted choice keeps the Studio's current one; a given one becomes it. The Studio opens its result panel, where the user copies the prompt and exports the frames to the configured export folder or browser downloads; the frame images stay there and are not in the answer. Answers status \"completed\" with output.prompt, mode, modelLabel, shot (id, name, range), aspectRatio, cameraMode and referenceFrames (how many frames the panel shows). Changes nothing in the scene; not a motion generation." },
 	// The instruction leads the H3 prompt, which the motion API caps at 4000
 	// characters with its camera-lock text (about 225) appended.
 ]);

package/src/studio-agent-motion.js

@@ -12,7 +12,8 @@ import { buildCollisionCapsules, detectPenetrations, supportsCollisionCleanup }
 import { collisionBlockers, blockerSummary } from './motion/collision-blockers.js';
 import { createGroundSampler } from './motion/ground.js';
 import { OBJECT_LIBRARY } from './scene-objects.js';
-import { objectTransformAt } from './object-path.js';
+import { sceneObjectsAt } from './object-travel.js';
+import { objectTracksOf } from './motion3/object-tracks.js';
 import { sampleAt } from './sample-at.js';
 import { isProxyFigure } from './scenes.js';
 
@@ -88,7 +89,7 @@ function stageCast(env, characterId, cast) {
 
 /* One take under evaluation, `t`: {evaluator, motion, env, cast, characterId,
  * character, protectedFrames, range, poseCast?, yieldTask, checkpoint}. */
-function blockersAt(t, frame) {
+function blockersAt(t, frame, objects) {
   t.checkpoint();
   const rigs = {};
   for (const member of t.cast) {
@@ -99,18 +100,19 @@ function blockersAt(t, frame) {
     rigs[member.character.id] = member.evaluator.rig;
   }
   const cast = t.cast.map((member) => member.character).filter(Boolean);
-  return collisionBlockers({ rigs, activeId: t.characterId, characterIds: cast, sceneObjects: t.env.objects, library: OBJECT_LIBRARY, frame, take: { frameCount: t.env.frameCount, fps: 24 } });
+  // `objects` already stand where this frame renders them (routes and take tracks), so no re-sampling here.
+  return collisionBlockers({ rigs, activeId: t.characterId, characterIds: cast, sceneObjects: objects, library: OBJECT_LIBRARY });
 }
 async function samples(t, layer) {
   const rows = [], poses = [], collisions = [], blockers = [];
   const cast = t.cast.map((member) => member.character).filter(Boolean);
   for (let frame = t.range.startFrame; frame < t.range.endFrameExclusive; frame++) {
     t.checkpoint(); poseFrame(t.evaluator, t.motion, layer, frame);
-    const shapes = blockersAt(t, frame);
-    const objects = t.env.objects.map(object => {
-      const at = objectTransformAt(object, frame, { frameCount: t.env.frameCount, fps: 24 });
-      return at ? { ...object, x: at.x, y: at.y, z: at.z, rot: at.rot ?? object.rot } : object;
-    });
+    // Objects as the editor renders them at this frame: travel routes plus the
+    // object tracks the installed takes bake (object-travel.js sceneObjectsAt).
+    const objects = sceneObjectsAt(t.env.objects, frame, t.objectTake);
+    for (const o of objects) if (!o.hidden && (o.rotX || o.rotZ)) t.tilted.add(o.id);
+    const shapes = blockersAt(t, frame, objects);
     rows.push(readSample(t.evaluator, createGroundSampler(objects, { floorY: t.env.floor.y, characters: cast })));
     poses.push(poseValues(t.evaluator.rest));
     const capsules = buildCollisionCapsules(t.evaluator.rig);
@@ -136,7 +138,7 @@ function judge(t, before, after) {
   }
   const supportedCollisionFrames = after.collisions.filter(p => p.length).length;
   const elevatedFrames = after.rows.flatMap((row, f) => Object.values(row.ground).some(y => y !== t.env.floor.y) ? [t.range.startFrame + f] : []);
-  const unsupportedObjects = t.env.objects.filter(o => o.attach || o.rotX || o.rotZ);
+  const unsupportedObjects = t.env.objects.filter(o => o.attach || o.rotX || o.rotZ || t.tilted.has(o.id));
   const missingCast = t.cast.filter(m => !m.evaluator || ((m.character.layer?.waypoints?.length ?? 0) > 0 && !t.poseCast));
   const measuredSupportFrames = after.support.frames.filter(f => f.measured).length;
   const flat = t.env.floor.model === 'flat' && elevatedFrames.length === 0 && Math.abs(t.character.y ?? 0) < 1e-8;
@@ -164,6 +166,13 @@ function receiptVerification(v) {
     limitations: v.limitations, surfaceMeasured: m.surfaceMeasured, maxFloorPenetrationM: m.maxFloorPenetrationM, maxContactSlipM: m.maxContactSlipM, maxContactFloatM: m.maxContactFloatM,
     unsupportedFrames: m.unsupportedFrames, supportedCollisionFrames: m.supportedCollisionFrames, continuityRegressed: m.continuityRegressed, semanticStatus: 'unavailable' };
 }
+/** Object tracks the installed takes bake (this take and the other cast's), keyed by object id. */
+function installedObjectTracks(target, environment) {
+  const takes = new Map((environment.cast ?? []).map(member => [member.character?.id, member.motion]));
+  takes.set(target.character.id, target.motion);
+  const characters = [...takes.keys()].filter(id => typeof id === 'string').map(id => ({ id }));
+  return objectTracksOf({ motionFor: id => takes.get(id) }, characters);
+}
 /** Motion verification of an installed take, on a private rig clone over
  * `range` (default and upper bound: the whole take). target: {character, rig,
  * motion, ikState?, protectedFrames?}; environment has readEnvironment()'s
@@ -177,6 +186,7 @@ export async function verifyInstalledTake({ target, environment, range, poseCast
   const deadline = now() + verificationBudget(endFrameExclusive - startFrame, verificationMs);
   const t = { evaluator: isolatedRig(target.rig), motion, env, cast: [], characterId: target.character.id, character: target.character,
     protectedFrames: target.protectedFrames ?? [], range: { startFrame, endFrameExclusive }, poseCast, yieldTask,
+    objectTake: { frameCount: env.frameCount, fps: 24, objectTracks: installedObjectTracks(target, environment) }, tilted: new Set(),
     checkpoint: () => { if (now() > deadline) fail('VERIFICATION_FAILED', 'Private verification budget exceeded.'); } };
   try {
     stageCast(environment, t.characterId, t.cast);

package/src/studio-agent-protocol.js

@@ -307,7 +307,7 @@ const receiptSchema = union(...Object.values(receiptVariants));
 const failureSchema = object({ ok: literal(false), commandId: id, host: identity, code: choices(STUDIO_ERROR_CODES), phase: choices(["admission", "execution", "prepare", "verify", "repair", "commit", "reconcile", "undo"]),
 	affectedIds: ids(100, 0), expectedTargets: array(guardSchema, 24), currentTargets: array(guardSchema, 24), mutated: union(bool, literal("unknown")),
 	preserved: object({ authoredState: choices(["unchanged", "changed", "unknown"]) }), recovery: object({ action: choices(["none", "inspect", "retry", "new_intent", "reconcile", "sign_in"]) }, { retryAllowed: bool }),
-}, { message: text(500), jobId: id, txId: id, candidates: array(object({ id, kind: choices(["object", "character", "rig"]), position: nullable(vec3) }), 5) });
+}, { message: text(2000), jobId: id, txId: id, candidates: array(object({ id, kind: choices(["object", "character", "rig"]), position: nullable(vec3) }), 5) });
 
 // These are JSON Schema data, not validators with hidden browser dependencies.
 // x-studio-range is the sole relational schema annotation: end > start.

package/src/studio-app-binding.js

@@ -196,9 +196,10 @@ export function createStudioAppBinding(ports) {
 				...(childIds.length ? { childIds: childIds.slice(0, 12), ...(childIds.length > 12 ? { childCount: childIds.length } : {}) } : {}) };
 		};
 		if (patched.length) return { patched, ...extras() };
-		const shot = s.shots.find(row => row.id === id);
+		// A camera key lives inside its shot: still present there means retained, not removed (#863).
+		const shot = s.shots.find(row => row.id === id), key = !shot && !entity && s.shots.flatMap(row => row.cameraKeys?.map(k => ({ shotId: row.id, frame: k.frame, id: k.id })) ?? []).find(k => k.id === id);
 		if (shot) return { name: shot.name || shot.id, range: { startFrame: shot.startFrame, endFrameExclusive: shot.endFrame + 1 } };
-		if (!entity) return { removed: true };
+		if (!entity) return key ? { shotId: key.shotId, frame: key.frame } : { removed: true };
 		const brief = { name: entity.name || entity.subject || entity.id, position: { x: entity.x, y: entity.y ?? 0, z: entity.z } };
 		if (compact) return brief;
 		if (!object) return { ...brief, yawDeg: entity.rot ?? 0, scale: entity.scale ?? 1, ...extras() };

package/src/studio-elements.js

@@ -40,7 +40,11 @@ const entries = [
 	{ path: "object.scale", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: 0.01, y: 0.01, z: 0.01 }, max: { x: 100, y: 100, z: 100 } },
 	{ path: "object.name", type: "string", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
 	{ path: "object.color", type: "color", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
-	{ path: "object.opacity", type: "number", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: 0.05, max: 1, note: "1 is solid; lower is see-through, e.g. 0.3 for clear glass" },
+	{ path: "object.opacity", type: "number", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: 0.05, max: 1, note: "1 is solid; lower is see-through, e.g. 0.4 for a ghost or water; for a glass object use object.material glass" },
+	// The preset names mirror material-presets.js MATERIAL_PRESETS / MATERIAL_FINISHES (test/verify-material-presets.mjs);
+	// sparse: a receipt lists them only on a record that has one.
+	{ path: "object.material", type: "enum", sparse: true, persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", enum: ["clay", "wood", "straw", "stone", "brick", "concrete", "metal", "glass", "ceramic", "plastic", "rubber", "fabric", "paper", "foliage"], note: "cube/sphere/capsule/cylinder/cone/plane only: surface preset with real texture and shine; color stays the tint and a grey (#c2c6c8) object takes the preset's own colour. clay is the default matte look; wood (planks, furniture), straw (thatch, hay, wicker), stone, brick (walls, chimneys), concrete (plaster, pavement), metal (reflects the stage), glass (clear, see-through; tint with color), ceramic (glazed), plastic, rubber (tyres), fabric (cloth, upholstery), paper, foliage (leaves, hedges)" },
+	{ path: "object.finish", type: "enum", sparse: true, persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", enum: ["matte", "satin", "gloss"], note: "with object.material: overrides the preset's shine, e.g. metal + gloss = chrome, glass + matte = frosted, wood + gloss = varnished" },
 	{ path: "object.parent", type: "id", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
 	{ path: "object.attach", type: "id", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", actions: ["object.attach", "object.detach"], note: "carried by a character's root or bone; channels convert so the prop stays put" },
 	{ path: "object.path", type: "array", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },

package/src/workflow/AgentPanel.jsx

@@ -3,12 +3,11 @@ import { FiAlertTriangle, FiArrowUp, FiCamera, FiCheck, FiChevronRight, FiClock,
 import { ATTACHMENT_ACCEPT, ATTACHMENT_FAILED_NOTICE, ATTACHMENT_LIMIT_NOTICE, ATTACHMENT_TYPE_NOTICE, attachmentFilesFromTransfer, attachmentFromFile, transferCarriesFiles } from "./attachment-image.js";
 import { isImeComposing } from "../ime.js";
 import { useStudioShell } from "../shell/studio-shell-context.js";
-import { ko } from "../locale.js";
+import { ko } from "../locale.js"; import { saveExport } from "../export-workspace.js";
 import {
 	AGENT_PANEL_OVERLAY_BREAKPOINT,
 	AGENT_PANEL_RAIL_WIDTH,
-	AGENT_PANEL_WIDTH_MAX,
-	AGENT_PANEL_WIDTH_MIN,
+	AGENT_PANEL_WIDTH_MAX, AGENT_PANEL_WIDTH_MIN,
 	AGENT_STATES,
 	agentServerUnavailable,
 	describeActivity,
@@ -29,8 +28,7 @@ import {
 	formatTurnClock,
 	formatResetIn,
 	readStoredPanelWidth,
-	storeModel,
-	storePanelWidth,
+	storeModel, storePanelWidth,
 	STUDIO_SESSION_STORAGE_KEY,
 	selectedModelRoles,
 	shortModelId,
@@ -43,6 +41,7 @@ const TaskBoard = lazy(() => import("./TaskBoard.jsx"));
 import { AgentProgressCard } from "./AgentProgressCard.jsx";
 import { LoginPanel } from "./LoginPanel.jsx";
 import { TurnSteps } from "./AgentTurnSteps.jsx";
+import { PlanCard } from "./AgentPlanCard.jsx";
 import { ReplyText } from "./AgentReplyText.jsx";
 import { stepLabel, turnLayout } from "./agent-turn.js";
 
@@ -74,7 +73,7 @@ function ImageResultCard({ image, onUse, onUndo, onRegenerate, onOpen }) {
 			? <div className="agent-placed"><StatusDot tone="ok" />Placed<button type="button" className="agent-image-undo" disabled={applying} onClick={() => onUndo(image)}>{applying ? "Removing…" : "Undo"}</button></div>
 			: <div className="agent-image-actions">
 				<button type="button" className="primary agent-image-use" disabled={applying} onClick={() => onUse(image)}><FiImage size={11} /> {applying ? "Applying…" : "Use in scene"}</button>
-				<a className="agent-image-download" role="button" href={image.dataUrl} download={`${image.imageId || "agent-image"}.png`}><FiDownload size={11} /> Download</a>
+				<a className="agent-image-download" role="button" href={image.dataUrl} download={`${image.imageId || "agent-image"}.png`} onClick={(event) => { event.preventDefault(); void saveExport(image.dataUrl, `${image.imageId || "agent-image"}.png`); }}><FiDownload size={11} /> Download</a>
 				<button type="button" className="agent-image-regenerate" onClick={() => onRegenerate(image)}><FiRotateCw size={11} /> Regenerate</button>
 			</div>}
 		{/* The card states what the editor actually did: an unacknowledged or
@@ -908,6 +907,7 @@ export default function AgentPanel({
 				if (item.kind === "receipt") return <div className="agent-row" key={item.id}><ReceiptCard item={item} /></div>;
 				if (item.kind === "failure") return <div className="agent-row" key={item.id}><FailureCard failure={item.failure} onRetry={() => runTurn(chat.lastPrompt)} onFixKey={openProviderKeys} /></div>;
 				if (item.kind === "supervisor") return <div className="agent-row" key={item.id}><SupervisorCard note={item} onSend={(text) => { store.setDraft(text); runTurn(text); }} /></div>;
+				if (item.kind === "plan") return <PlanCard key={item.id} plan={item} live={streaming && !item.outcome} />;
 				return <div className="agent-row" key={item.id}><ImageResultCard image={item} onUse={(image) => store.applyImage(image.id)} onUndo={(image) => store.undoImage(image.id)} onRegenerate={() => runTurn(chat.lastPrompt)} onOpen={setLightbox} /></div>;
 			})}
 

package/src/workflow/AgentPlanCard.jsx

@@ -0,0 +1,41 @@
+// A turn's step checklist in the agent panel (agent-plan.js keeps it): a header that says how far the plan is ("2/5")
+// beside a thin progress bar, and one row per step: done steps checked, the step under way highlighted with a soft
+// pulse, the rest waiting. While the turn runs the card stays pinned to the top of the transcript, so what is happening
+// and what comes next stay in view however long the step list below grows. Once the turn ends nothing pulses, and a
+// step a failed or stopped turn left unfinished reads muted.
+import { FiCheck, FiMinus } from "react-icons/fi";
+import { ko } from "../locale.js";
+import "./agent-plan.css";
+
+const STATUS_WORDS = {
+	done: ko("done", "완료"),
+	active: ko("in progress", "진행 중"),
+	pending: ko("next", "대기"),
+	unfinished: ko("not finished", "미완료"),
+};
+
+function PlanMark({ status }) {
+	if (status === "done") return <FiCheck className="agent-plan-mark done" size={11} aria-hidden="true" />;
+	if (status === "unfinished") return <FiMinus className="agent-plan-mark unfinished" size={11} aria-hidden="true" />;
+	return <span className={`agent-plan-mark ${status}`} aria-hidden="true" />;
+}
+
+export function PlanCard({ plan, live }) {
+	const total = plan.steps.length, done = plan.steps.filter(step => step.status === "done").length;
+	const state = live ? "live" : plan.outcome ?? "done";
+	return <div className="agent-row agent-plan-row" data-plan-live={live ? "true" : "false"}>
+		<section className="agent-card agent-plan" data-agent-card="plan" data-plan-state={state} aria-label={ko(`Plan, ${done} of ${total} done`, `계획, ${total}단계 중 ${done}단계 완료`)}>
+			<div className="agent-plan-head">
+				<span className="agent-plan-title">{ko("Plan", "계획")}</span>
+				<span className="agent-plan-bar" aria-hidden="true"><span className="agent-plan-fill" style={{ "--agent-plan-done": total ? done / total : 0 }} /></span>
+				<span className="agent-plan-count">{done}/{total}</span>
+			</div>
+			<ol className="agent-plan-steps">
+				{plan.steps.map((step, index) => <li key={index} className={`agent-plan-step ${step.status}`} data-plan-status={step.status} aria-current={step.status === "active" ? "step" : undefined} aria-label={`${step.text}: ${STATUS_WORDS[step.status] ?? step.status}`}>
+					<PlanMark status={step.status} />
+					<span className="agent-plan-text">{step.text}</span>
+				</li>)}
+			</ol>
+		</section>
+	</div>;
+}

package/src/workflow/CozySceneNode.jsx

@@ -58,7 +58,7 @@ export default function CozySceneNode({ id = "cozy-scene", data: rawData = {}, s
 			// No shotId: the Scene node tracks a scene, not a shot, so the embed
 			// packs the shot under its own playhead — the one being previewed.
 			const result = await requestKeyframePack(frame, { surface: "workflow" });
-			downloadPack(result);
+			await downloadPack(result);
 			attempt.succeed();
 			track("export:keyframe_pack", { entries: result.entries.length, source: "workflow" });
 			// QA hook, mirroring window.__cozyclay in the Studio: the analytics

package/src/workflow/WorkflowBuilder.jsx

@@ -13,7 +13,7 @@ import { FiActivity, FiBox, FiCode, FiFileText, FiFilm, FiImage, FiLink, FiMusic
 import { Toaster, toast } from "react-hot-toast";
 import { loadWorkflowGraph, normalizeWorkflowGraph, storeWorkflowGraph, WORKFLOW_STORAGE_KEY } from "../project.js";
 import AgentPanel from "./AgentPanel.jsx";
-import CozySceneNode from "./CozySceneNode.jsx";
+import CozySceneNode from "./CozySceneNode.jsx"; import { saveExport } from "../export-workspace.js";
 import { applyCozyScenePatch, normalizeCozySceneData, sceneConnectionAllowed } from "./cozy-scene-node.js";
 import { activeSceneCharacters, characterHandleId, characterIdFromHandle, normalizeMotionInputData, motionInputOutput, parseMotionSpec } from "./motion-input.js";
 import { DEFAULT_NODE_SCHEMAS, defaultFormValues, schemaCategoryForType, schemaModelEntries, schemaProperties } from "./node-schema.js";
@@ -652,7 +652,7 @@ export default function WorkflowBuilder() {
 		},
 	})), [changeModel, nodeSchemas, nodes, runScene, runWorkflow, sceneCharacters, sceneContext, sendSceneToVideo, updateNode, updateScene, uploadFile, useVersionAsReference]);
 
-	const exportGraph = useCallback(() => { const blob = new Blob([JSON.stringify(graph, null, 2)], { type: "application/json" }); const url = URL.createObjectURL(blob); const anchor = document.createElement("a"); anchor.href = url; anchor.download = "cozyclay-workflow.json"; anchor.click(); URL.revokeObjectURL(url); toast.success("Workflow exported"); }, [graph]);
+	const exportGraph = useCallback(async () => { const blob = new Blob([JSON.stringify(graph, null, 2)], { type: "application/json" }); await saveExport(blob, "cozyclay-workflow.json"); toast.success("Workflow exported"); }, [graph]);
 	const onConnect = useCallback((params) => {
 		const target = nodes.find((node) => node.id === params.target);
 		const source = nodes.find((node) => node.id === params.source);

package/src/workflow/agent-client.js

@@ -28,8 +28,9 @@ import { appendAttachments, ATTACHMENT_MAX_COUNT } from "./attachment-image.js";
 import { ko } from "../locale.js";
 import { AGENT_TOOL_CATEGORIES, EXECUTION_TELEMETRY_VALUES } from "../execution-telemetry.js";
 import { STUDIO_VARIANTS, validateReceipt } from "../studio-agent-protocol.js";
-import { requestAgentImage, sidecarRequest, sidecarUrl } from "../agent-image-client.js";
+import { requestAgentImage, sidecarRequest, sidecarUrl } from "../agent-image-client.js"; import { clearSculptSketch, sculptSketchFrame } from "../sculpt-sketch-state.js";
 import { actionLabelsOf, changedLine, scriptNow, stepFields, thinkingLine, withCompose, withThinking, withToolStart, withTurnEnd } from "./agent-turn.js";
+import { isPlanFrame, restoredPlans, withPlanEnd, withPlanFrame } from "./agent-plan.js";
 
 const AGENT_PANEL_WIDTH_KEY = "cozyclay.workflow.agentPanel.width";
 export const AGENT_PANEL_WIDTH_DEFAULT = 360;
@@ -1325,6 +1326,8 @@ export function createAgentChatStore({
 			});
 			return;
 		}
+		// The turn's step checklist (bin/agent/plan-tool.mjs): one card under the prompt; the plan call itself is no step.
+		if (isPlanFrame(event)) { setItems((items) => withPlanFrame(items, event, newId)); return; }
 		if (event?.type === "tool.start") {
 			setItems((items) => withToolStart(items, { kind: "tool", id: event.callId || newId(), callId: event.callId, name: event.name, label: event.label, args: event.args, status: "running", startedAt: clock(), ...stepFields(event.name, event.args, actionLabels) }));
 			return;
@@ -1406,11 +1409,10 @@ export function createAgentChatStore({
 		set({ sessionId: newId(), turnId: null, items: [], pendingAttachments: [], rateLimit: null, lastPrompt: "", turnStartedAt: null, lastTurn: null });
 	};
 	const restore = (transcript, sessionId = state.sessionId) => {
-		abandonSupervisorNotes();
-		seenReceipts.clear();
-		settledActions.clear();
+		abandonSupervisorNotes(); seenReceipts.clear(); settledActions.clear();
 		const restoredReceiptIds = new Set();
-		const restored = (Array.isArray(transcript) ? transcript : []).flatMap((item) => {
+		// Each turn's plan card comes back under its prompt, settled by how the turn ended (agent-plan.js).
+		const restored = restoredPlans((Array.isArray(transcript) ? transcript : []).flatMap((item) => {
 			if (item?.kind === "user" || item?.kind === "assistant") {
 				const attachments = Array.isArray(item.attachments) ? item.attachments.filter((entry) => typeof entry?.dataUrl === "string") : [];
 				return [{ kind: item.kind, id: newId(), text: String(item.text ?? ""), ...(attachments.length ? { attachments } : {}) }];
@@ -1425,8 +1427,8 @@ export function createAgentChatStore({
 				return [{ kind: "receipt", id: `receipt:${item.receiptId || newId()}`, receiptId: item.receiptId, summary: item.summary || "Receipt", receipt: { status: "applied", warnings: [], verification: { status: "verified" } } }];
 			}
 			if (item?.kind === "failure") return [{ kind: "failure", id: newId(), failure: { code: item.code || "upstream", message: String(item.message || "The turn failed."), recovery: { action: "retry", retryAllowed: true } } }];
-			return [];
-		});
+			return item?.kind === "plan" ? [{ kind: "plan", id: newId(), steps: item.steps }] : [];
+		}));
 		const lastPrompt = [...restored].reverse().find((item) => item.kind === "user")?.text || "";
 		set({ sessionId, turnId: null, items: restored, rateLimit: null, lastPrompt, turnStartedAt: null, lastTurn: null, streaming: false });
 		return restored;
@@ -1498,14 +1500,15 @@ export function createAgentChatStore({
 					model: options.model,
 					effort: options.effort ?? undefined,
 					...(typeof options.supervisor === "boolean" ? { supervisor: options.supervisor } : {}), ...(options.tasks ? { tasks: true } : {}),
-				}, applyEvent, signal);
+				}, (event) => { sculptSketchFrame(event); applyEvent(event); }, signal);
 			} catch (error) {
 				if (!signal.aborted) applyEvent({ type: "error", code: "upstream", message: String(error?.message || error) });
 			} finally {
 				if (controller?.signal === signal) controller = null;
-				// A turn the author already replaced owns none of this state.
+				// A turn the author already replaced owns none of this state. Its live sculpt sketch
+				// (the ghost clay of a call still being written) ends with it, whatever ended it.
 				if (activeTurn === turn) {
-					wireTurnId = null;
+					wireTurnId = null; clearSculptSketch();
 					// Ending with nothing on screen is a failure, not a result.
 					if (!turn.produced && !turn.failure && !signal.aborted) {
 						turn.failure = { code: "no_output", message: "The turn ended without a response.", recovery: { action: "retry", retryAllowed: true } };
@@ -1515,7 +1518,7 @@ export function createAgentChatStore({
 					activeTurn = null;
 					// The end state stays in the transcript with the turn's steps (agent-turn.js withTurnEnd).
 					const lastTurn = { status: signal.aborted ? "stopped" : turn.failure ? "failed" : "done", endedAt, durationMs: endedAt - startedAt, failure: turn.failure };
-					set({ streaming: false, turnStartedAt: null, lastTurn, items: withTurnEnd(state.items, lastTurn, newId) });
+					set({ streaming: false, turnStartedAt: null, lastTurn, items: withPlanEnd(withTurnEnd(state.items, lastTurn, newId), lastTurn.status) });
 					if (studio && turn.reviewable && options.supervisor === true && !signal.aborted) requestSupervisorNote(turnId);
 				}
 			}

package/src/workflow/agent-plan.css

@@ -0,0 +1,93 @@
+/* A turn's step checklist (AgentPlanCard.jsx); colours, sizes and motion come from agent-panel.css. */
+.agent-plan-row[data-plan-live="true"] {
+	position: sticky;
+	top: calc(-1 * var(--agent-space-5));
+	z-index: 1;
+	/* the transcript's own colour above the card, so steps scrolling under it never show through the gap */
+	padding-top: var(--agent-space-2);
+	margin-top: calc(-1 * var(--agent-space-2));
+	background: var(--agent-bg);
+}
+
+.agent-plan {
+	--agent-plan-mark: 11px;
+	display: flex;
+	flex-direction: column;
+}
+
+.agent-plan-row[data-plan-live="true"] .agent-plan { box-shadow: 0 6px 14px -8px #000c; }
+
+.agent-plan-head {
+	display: flex;
+	align-items: center;
+	gap: var(--agent-space-3);
+	padding: var(--agent-space-2) var(--agent-space-4);
+	color: var(--agent-text-soft, var(--agent-text));
+	font-size: var(--agent-font-md);
+}
+
+.agent-plan-title { flex: none; font-weight: 600; }
+
+.agent-plan-bar {
+	flex: 1;
+	height: 3px;
+	overflow: hidden;
+	border-radius: var(--agent-radius-pill);
+	background: var(--agent-track);
+}
+
+.agent-plan-fill {
+	display: block;
+	height: 100%;
+	background: var(--agent-ok);
+	transform: scaleX(var(--agent-plan-done, 0));
+	transform-origin: left;
+	transition: transform var(--agent-motion);
+}
+
+.agent-plan-count { flex: none; color: var(--agent-text-dim); font: var(--agent-font-sm) ui-monospace, monospace; font-variant-numeric: tabular-nums; }
+
+.agent-plan-steps {
+	display: flex;
+	flex-direction: column;
+	gap: 2px;
+	margin: 0;
+	padding: var(--agent-space-1) 0 var(--agent-space-2);
+	border-top: 1px solid var(--agent-border);
+	list-style: none;
+}
+
+.agent-plan-step {
+	display: flex;
+	align-items: center;
+	gap: var(--agent-space-3);
+	min-width: 0;
+	padding: 2px var(--agent-space-4);
+	color: var(--agent-text-muted);
+	font-size: var(--agent-font-md);
+	line-height: 1.4;
+}
+
+.agent-plan-text { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.agent-plan-step.done { color: var(--agent-text-dim); }
+.agent-plan-step.active { background: color-mix(in srgb, var(--agent-accent) 12%, transparent); color: var(--agent-text); }
+.agent-plan-step.unfinished { color: var(--agent-text-dim); }
+.agent-plan-step.unfinished .agent-plan-text { font-style: italic; }
+
+.agent-plan-mark { flex: none; width: var(--agent-plan-mark); height: var(--agent-plan-mark); }
+.agent-plan-mark.done { color: var(--agent-ok); }
+.agent-plan-mark.unfinished { color: var(--agent-warn); }
+.agent-plan-mark.pending { border: 1.5px solid var(--agent-border-strong); border-radius: var(--agent-radius-pill); }
+/* the step under way: an accent ring whose centre breathes while the turn runs */
+.agent-plan-mark.active { position: relative; border: 1.5px solid var(--agent-accent); border-radius: var(--agent-radius-pill); }
+.agent-plan-mark.active::after { content: ""; position: absolute; inset: 2px; border-radius: var(--agent-radius-pill); background: var(--agent-accent); }
+.agent-plan[data-plan-state="live"] .agent-plan-mark.active::after { animation: agent-pulse 1.4s ease-in-out infinite; }
+
+/* A finished turn's card is a record: it keeps its rows but no longer pulls the eye. */
+.agent-plan:not([data-plan-state="live"]) .agent-plan-fill { background: var(--agent-text-dim); }
+.agent-plan[data-plan-state="done"] .agent-plan-fill { background: var(--agent-ok); }
+
+@media (prefers-reduced-motion: reduce) {
+	.agent-plan[data-plan-state="live"] .agent-plan-mark.active::after { animation: none; }
+	.agent-plan-fill { transition: none; }
+}