cozyclay 3.1.6 → 3.2.1

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.1.6\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"d7b44cfa152ddb449c4e1445adeb8e3ae0a176e8eab6d431c7d9103ee12c25fc\"}","signature":"ruWnt+cS82Ajp7uv+w9ZiHLcqY5lCSNKER2sVtiLV+jnhGAzpPw1/KuZazg9lwFucoycs99uTwY8s+e5A3WQDw=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.2.1\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"e718aecfd151dda276e5d63c11a57f1e47b52a54d35fc07dbea34a0b209de6c5\"}","signature":"57sTKSSWpbM4IS3uUaKX1UpUWwfo6aH0+GzQvkJP41AwzK9jGMCAwzatT6oDobQ86JFHBpXnpT2+kSSATwLpCg=="}

package/dist/index.html

@@ -46,7 +46,7 @@
         "applicationCategory": "DesignApplication",
         "applicationSubCategory": "3D previsualization",
         "operatingSystem": "Any (Chromium-based browser)",
-        "softwareVersion": "3.1.6",
+        "softwareVersion": "3.2.1",
         "description": "CozyClay is an open-source, browser-based 3D staging studio. Block a scene, pose characters, sequence motion prompts on a timeline, and preview generated motion in one local workspace that handles like the Unity Editor.",
         "image": "https://cozyclay.org/media/cozyclay-truck-demo-poster.jpg",
         "screenshot": "https://cozyclay.org/media/cozyclay-truck-demo-poster.jpg",
@@ -380,6 +380,9 @@
         .btn, a.card, .seg button, details summary::after { transition: none; }
       }
     </style>
+    <script type="module" crossorigin src="/assets/landing-2Fy7DU41.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-P2Xu9kJm.js">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-CaTUuLPM.js">
   </head>
   <body>
     <header class="site">

package/dist/privacy/index.html

@@ -133,7 +133,7 @@ cclay telemetry on</code></pre>
             <tbody>
               <tr><td>install:first_launch, app:session_started, app:session_ended</td><td>Counting installs and sessions; duration and action counts are bucketed. install:first_launch may carry heard_from (x, hn, reddit, github, friend, other, site or playground), from the first-launch prompt or a copied <code>npx cozyclay --via</code> command. app:session_ended also carries scenes_touched (how many scenes were created or loaded in the session, an exact count capped at 20, not bucketed), session_id (the opaque random session id the PostHog SDK generates, used only to join a session's last events, such as an error just before it ended) and per-session edit gesture counts in five groups, pose_edit_bucket, camera_edit_bucket, object_edit_bucket, shot_edit_bucket and prompt_edit_bucket, each bucketed (0, 1-3, 4-10 or gte11); never what was edited</td></tr>
               <tr><td>app:friction_summary</td><td>Once per session, next to app:session_ended: how much friction the session had, as closed buckets only. active_time (the session duration bucket); counts of refusals the Studio gave the user (refusals_ui) and the agent (refusals_agent), user undos (undos), errors (errors), browser long tasks (long_tasks) and motion compiles (compiles), each as 0, 1, 2, 3, 4-5, 6-10 or gte11; the longest long task (long_task_max: lt50, 50-150, 150-500, 500-2000 or gte2000 ms); the share of late playback ticks (late_tick_ratio: 0, lt5, 5-20, 20-50 or gte50 %). rage_clicks and dead_clicks count every ui:rage_click and ui:dead_click, shortcut_ignored every shortcut:ignored, search_empty every search:no_results, and nav_thrash and camera_thrash every nav:thrash and camera:thrash, including those past their event's cap. Never which command, control, key or text was involved.</td></tr>
-              <tr><td>studio:refused</td><td>A command the Studio refused, as closed values only: code (one of the Studio's fixed error codes, such as INVALID_ARGUMENT, STALE_SCENE or TARGET_BUSY, else other), origin (ui for the user's own control, agent for the agent or an MCP client), phase (admission, refused before any change, or commit, refused after it started changing) and group (the command's family: object, shot, cast, scene, motion, edit, task, agent or other). At most 3 per code, group and origin per session; the rest are only counted in app:friction_summary. A cancel the caller asked for is not a refusal. Never the command's arguments, target or message.</td></tr>
+              <tr><td>studio:refused</td><td>A command the Studio refused, as closed values only: code (one of the Studio's fixed error codes, such as INVALID_ARGUMENT, STALE_SCENE or TARGET_BUSY, else other), origin (ui for the user's own control, agent for the agent or an MCP client), phase (admission, refused before any change, or commit, refused after it started changing) group (the command's family: object, shot, cast, scene, motion, edit, task, agent or other) and command (the refused action's id, such as object.set or shot.setCameraRail, only when it is one of the actions the Studio itself declares; a name the caller made up is left out). At most 3 per code, command (or group, without one) and origin per session; the rest are only counted in app:friction_summary. A cancel the caller asked for is not a refusal. Never the command's arguments, target or message.</td></tr>
               <tr><td>edit:undone</td><td>A user undo (agent undos are not counted): age (lt2s, 2-10s, 10-60s or gte60s since the undone edit was made, only when the undo was done and its age is known), kind (pose, camera, object, shot, prompt, agent_turn for the agent's whole turn, ik_preview for an un-applied IK drag, or other), via (key, menu or button) and result (done, noop when there was nothing to undo, or refused). At most 20 per session. Never what was undone.</td></tr>
               <tr><td>agent:turn_summary</td><td>One per agent turn: turn_id (the same random id as agent:turn_*); outcome (succeeded, failed or cancelled); wall (the turn's length) and first_tool (time to the first tool call, absent without tools), each lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m; counts of tool calls (tool_calls), failed tool calls (tool_failed), tool calls the Studio refused (refused), commands re-sent once after a stale revision or a busy gesture (stale_retry) and motion compiles (drafts), each as 0, 1, 2, 3, 4-5, 6-10 or gte11; refusal_top (the most frequent refusal code, or none); authored (true or false: the turn changed the scene); qa_first and qa_last (clean or problems, absent without drafts); qa_trend (improved, flat, worse, or na with fewer than 2 drafts); stuck (true or false: the motion compiler's stop rule fired); cancel_phase (before_tool, during_tool, after_tool or na). No prompt text, tool names, messages or responses.</td></tr>
               <tr><td>agent:post_turn_edit</td><td>One per agent turn: turn_id (the same random id) and the user's own edit gestures in the 120 seconds after the turn ended, closed early when the next turn starts or the page closes. edited (true or false); counts per group (pose, camera, object, shot, and prompt_block, which counts edits to a take's prompt and take fields), each as 0, 1, 2, 3, 4-5, 6-10 or gte11, where one continuous drag is one gesture; first_delay (time to the first edit: lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m), only when edited is true. Never which object or what changed.</td></tr>
@@ -149,7 +149,7 @@ cclay telemetry on</code></pre>
               <tr><td>agent:connect_finished</td><td>That attempt ended: provider, method, outcome (ok, failed, cancelled with the Cancel button, abandoned when closed or left unfinished), step it had reached (list, prompt, waiting or done) and duration (lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m). Never the key, token, account, email or error text.</td></tr>
               <tr><td>agent:model_changed</td><td>A model picked in the agent's model list: its provider (as above, or other) and after_failure (whether the last agent turn had failed). At most 10 per session.</td></tr>
               <tr><td>agent:prompt_sent</td><td>One per prompt sent to the agent: turn_id (the same random id as agent:turn_*); provider (as for agent:connect_started, or other); via (typed, retry_button, regenerate, chip or supervisor); prompt_len (1-20, 21-80, 81-240 or gte241 characters); compose_ms (first keystroke to send, typed prompts only) and gap (since the previous turn ended, or first) as lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m; similarity (first, same, near or different, computed in the browser against the previous prompt's words); prev_outcome (succeeded, failed, cancelled or none); turn_index (1, 2, 3, 4-5, 6-10 or gte11); attached and task_mode (true or false). Never the prompt text or its words.</td></tr>
-              <tr><td>ui:rage_click</td><td>Three or more fast clicks (within 1 second and 24 pixels) on one primary control: control (a control id from a fixed list, such as tl_play or export_video, or other), clicks (3, 4-5 or gte6) and changed (whether the Studio responded within half a second). At most 2 per control per session. No coordinates, no text, no element or object ids.</td></tr>
+              <tr><td>ui:rage_click</td><td>Three or more fast clicks (within 1 second and 24 pixels) on one primary control: control (a control id from a fixed list, such as tl_play or export_video; for a control not on that list, the Studio area it sits in: other_guide, other_agent, other_menu, other_sculpt, other_assets, other_board, other_timeline, other_inspector or other_viewport; else other), clicks (3, 4-5 or gte6) and changed (whether the Studio responded within half a second). At most 2 per control per session. No coordinates, no text, no element or object ids.</td></tr>
               <tr><td>ui:dead_click</td><td>A click on a primary control that did nothing: control (as above) and reason (aria_disabled when the control was disabled, refused when the Studio refused the command, no_effect when nothing changed within half a second). At most 2 per control per session. Clicks into text fields are never observed.</td></tr>
               <tr><td>feature:used</td><td>One signal per feature per session: a fixed feature name such as pose_edit (a real bone or pose change), pose_save (saving a pose to the library), camera_fly, export_video, export_storyboard or export_render_pass</td></tr>
               <tr><td>$pageview, scene:created, scene:loaded, craft:first_action, activation:completed</td><td>Funnel and drop-off analysis</td></tr>
@@ -161,14 +161,15 @@ cclay telemetry on</code></pre>
               <tr><td>workflow:result_applied</td><td>Captured or generated image/video output was written to the Workflow canvas: run_id only, at most once per run, independently of a later failure. No image bytes or output contents.</td></tr>
               <tr><td>agent:turn_requested</td><td>Explicit Agent turn requests from surface (studio or workflow), paired by ephemeral turn_id. No prompts, responses or model identifiers.</td></tr>
               <tr><td>agent:tool_executed</td><td>Agent tool observations: turn_id, tool_category (workflow_read, workflow_write, workflow_run, frame_capture, image_generate, scene_write or other), outcome (succeeded, failed or cancelled) and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s). Tool names, arguments and results are excluded.</td></tr>
-              <tr><td>agent:turn_succeeded, agent:turn_failed, agent:turn_cancelled</td><td>Agent turn outcomes: turn_id and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s); failures and actual cancellations also include failure_code (aborted, auth, rate_limited, tool_failed, upstream, key_refused, stale_scene, capability_missing, busy, invalid_request or unknown). auth means CozyClay's local agent has no sign-in or refused the session; key_refused means the model provider rejected the key or credentials; stale_scene means the turn was refused because the scene changed underneath it; capability_missing means a required capability was unavailable, for example the live hub port was already in use; busy means another turn or target was busy; invalid_request means the request itself was rejected. Missing terminal delivery is not success.</td></tr>
+              <tr><td>agent:turn_succeeded, agent:turn_failed, agent:turn_cancelled</td><td>Agent turn outcomes: turn_id and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s); failures and actual cancellations also include failure_code (aborted, auth, rate_limited, tool_failed, upstream, network, key_refused, stale_scene, capability_missing, busy, invalid_request or unknown). upstream means the model provider failed (an HTTP 5xx, overload or a cut-off stream); network means the request never got an HTTP answer (offline, connection reset or DNS); unknown is any other failure. auth means CozyClay's local agent has no sign-in or refused the session; key_refused means the model provider rejected the key or credentials; stale_scene means the turn was refused because the scene changed underneath it; capability_missing means a required capability was unavailable, for example the live hub port was already in use; busy means another turn or target was busy; invalid_request means the request itself was rejected. Missing terminal delivery is not success.</td></tr>
               <tr><td>agent:result_applied</td><td>An Agent turn produced an acknowledged editor change: turn_id only, at most once per turn. Successful reads and focus/navigation do not prove applied output.</td></tr>
-              <tr><td>mcp:tool_requested</td><td>Connected-editor MCP execution requests: ephemeral request_id and tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other).</td></tr>
-              <tr><td>mcp:tool_executed</td><td>Connected-editor MCP outcomes: request_id, tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other), outcome (succeeded, failed, uncertain or cancelled) and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s). Control-plane success does not prove a mutation applied.</td></tr>
+              <tr><td>mcp:tool_requested</td><td>Connected-editor MCP execution requests: ephemeral request_id, tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other) and tool_name, the CozyClay tool that ran (describe_scene, describe_shot, render_prompt, mark_camera_move, describe_camera_move, save_project, set_camera, frame_shot, add_character, place_character, remove_character, focus_character, place_object, import_mesh, sculpt_object, compare_sculpt, group_objects, update_object, remove_object, apply_batch, add_scene, switch_scene, open_project, capture_frame, studio_commands, studio_run or other; never its arguments).</td></tr>
+              <tr><td>mcp:tool_executed</td><td>Connected-editor MCP outcomes: request_id, tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other), tool_name (describe_scene, describe_shot, render_prompt, mark_camera_move, describe_camera_move, save_project, set_camera, frame_shot, add_character, place_character, remove_character, focus_character, place_object, import_mesh, sculpt_object, compare_sculpt, group_objects, update_object, remove_object, apply_batch, add_scene, switch_scene, open_project, capture_frame, studio_commands, studio_run or other), outcome (succeeded, failed, uncertain or cancelled) and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s). Control-plane success does not prove a mutation applied.</td></tr>
               <tr><td>mcp:result_applied</td><td>A connected editor acknowledged an MCP mutation, paired by request_id. Detached or disconnected MCP sessions remain unobserved.</td></tr>
               <tr><td>export:blocking_frame_succeeded, export:video_succeeded</td><td>Export reliability</td></tr>
               <tr><td>export:attempt_started, export:attempt_succeeded, export:attempt_failed, export:attempt_cancelled</td><td>Export attempts and outcomes, paired by an ephemeral random attempt_id; export_kind (video, depth_video, frame, keyframe_pack, contact_sheet, panel_pack, animatic, animation_project, workflow_send, storyboard, render_pass or otio), format (mp4, png, zip, cclayproject or otio), initiating surface (studio, workflow or embed), is_retry (whether the attempt retries an earlier one), retry_of (the retried attempt's attempt_id, only when is_retry is true) and objects (the scene's object count, bucketed 0, 1-3, 4-10 or gte11). Terminal events include a bucketed duration_bucket; failures and real cancellations include a normalized failure_code (unsupported_codec, encode_failed, render_failed, aborted or unknown), the stage where the export stopped (preparing, encoding, finalizing or handoff) and a progress bucket (0, 1-25, 26-50, 51-75 or 76-99 percent), never raw error messages, filenames, URLs, paths, prompts or scene content. Success means pipeline completion or download handoff, not confirmation that the OS saved a file.</td></tr>
               <tr><td>export:saved</td><td>How each exported file was saved, one event per file: method (workspace, written into the export folder you chose, or download, a browser download) and reason (none; unsupported, the browser has no folder access; no_workspace, no export folder is chosen; permission, folder access was denied; or write_failed, the folder write failed and the file fell back to a download). Never the file name or path.</td></tr>
+              <tr><td>export:menu_opened</td><td>The Export menu opened, once per open: surface (studio or embed), mode (animation or storyboard), webcodecs (whether this browser has the video encoder an MP4 export needs; a yes/no check, not a codec test) and shots (shot count bucket, panels in a storyboard: 0, 1-3, 4-10, gte11). Never shot names or what you exported.</td></tr>
               <tr><td>export:keyframe_pack</td><td>Legacy Workflow pack handoffs, with numeric entries count and source=workflow; not an additional export attempt</td></tr>
               <tr><td>sculpt_run</td><td>One event per finished Sculpt mode run: outcome (done, cancelled or failed), rounds (0 to 10), final_iou (how closely the final sculpt matched the reference image, 0 to 1 rounded to two decimals; omitted when the run was never scored), duration_ms (elapsed run time in milliseconds) and had_target (whether the run reworked an existing sculpt instead of creating one). Numbers only: never the reference image, recipe, part names or sculpt id.</td></tr>
               <tr><td>playground:opened, playground:first_action</td><td>Whether the home-page playground gets used</td></tr>
@@ -177,6 +178,7 @@ cclay telemetry on</code></pre>
               <tr><td>app:gl_lost</td><td>The 3D view's graphics failed, at most once per kind per session: kind (unavailable when WebGL is off at startup, context_lost when the GPU context drops later). Never the GPU renderer string.</td></tr>
               <tr><td>studio:ready</td><td>Once per session: how long the studio took to show its first frame, from page navigation to the first frame after the first render: boot (lt2s, 2-5s, 5-15s or gte15s). Never what was loaded.</td></tr>
               <tr><td>playback:summary</td><td>One per playback run (play until stop, or until the frame rate or speed changes), at most 10 per session: duration (lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m); late_ticks, an estimate of dropped frames, not a measured one: the share of playback timer ticks that had to catch up more than one frame (0, lt5, 5-20, 20-50 or gte50 %); max_catchup (the most frames one tick caught up: 1, 2, 3-5 or gte6); fps (12, 24, 30, 60 or other); speed (0.5, 1, 2 or other); measured_fps (the browser's frame rate during playback, the device:profile frame-rate buckets). Every run also feeds app:friction_summary.late_tick_ratio. Never the scene, the take or the frame range.</td></tr>
+              <tr><td>landing:cta_clicked</td><td>The landing page (cozyclay.org/) sends one $pageview and, when a call to action is pressed, which one: target (app, github, discord, npm, copy_npx, copy_clone, copy_mcp, copy_terminal or agent_install_doc). Never the URL or the copied text. The landing page sends no session, error, device or performance events.</td></tr>
               <tr><td>guide:opened</td><td>The first-60-seconds guide opened, at most once per session: mode (animation or storyboard). Never step text or what you did.</td></tr>
               <tr><td>guide:step</td><td>A guide step marked done, each step at most once per session: mode (animation or storyboard), step (1 to 4) and step_ms (time on that step: lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m).</td></tr>
               <tr><td>guide:dismissed</td><td>The guide closed before its last step, at most once per session: mode (animation or storyboard) and reached (1 to 4, the step it was showing).</td></tr>
@@ -185,8 +187,9 @@ cclay telemetry on</code></pre>
               <tr><td>object:deleted_soon</td><td>You deleted an object you added in this session, at most 10 per session: age (how long after adding it: lt2s, 2-10s, 10-60s or gte60s). Object ids are reused names, so this is an estimate. Never the object's id, name or kind.</td></tr>
               <tr><td>object:delete_undone</td><td>You undid an object deletion within its 7-second undo window, at most 10 per session: age (time from the deletion to the undo: lt2s or 2-10s). Never the object's id, name or kind.</td></tr>
               <tr><td>update:notice_shown</td><td>The update notice appeared in the top bar of an npm studio, once per session: kind (global or npx) and behind (patch, minor or major: how far the running version is behind the newest release). Never a path or a command</td></tr>
-              <tr><td>update:clicked</td><td>A button on the update notice, at most 10 per session: action (update_now, copy_command, later, dismiss or release_notes) and kind (global or npx)</td></tr>
+              <tr><td>update:clicked</td><td>A button on the update notice, at most 10 per session: action (update_now, copy_command, later, dismiss, release_notes or restart) and kind (global or npx)</td></tr>
               <tr><td>update:finished</td><td>A one-click update ended, at most 3 per session: outcome (ok or failed), error_class (none, permission, network, node_version, npm_missing or other) and duration (lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m). Never npm's output, a path or the command line</td></tr>
+              <tr><td>update:restarted</td><td>Restart now ended in the tab that pressed it, once per session: outcome (ok: the updated launcher answered; timeout: it did not within 30 seconds). Never a version string, a path or the command line</td></tr>
               <tr><td>device:profile</td><td>Once per session, whether the studio can run smoothly: gpu_vendor (nvidia, amd, intel, apple, qualcomm, arm, software, other or unknown), gpu_class (discrete, integrated, software or unknown), webgl (webgl2, webgl1 or none), cpu_bucket (1-4, 5-8, 9-16, gte17 or unknown), memory_bucket (lt4, 4-7, gte8 or unknown) and frame_rate_bucket (lt20, 20-40, 40-55, gte55 or unknown) from one three-second sample. The GPU renderer string and exact hardware values never leave the browser.</td></tr>
               <tr><td>survey:use_case</td><td>An optional question shown at most once after a successful export, only while telemetry is on: use_case (animation, film, game, ad_mv, personal, other or skip) and team (team, solo or skip). Closed choices only; no free text.</td></tr>
               <tr><td>hosted:composer_viewed, hosted:login_started, hosted:ticket_created, hosted:result_opened, hosted:opened_in_studio</td><td>Hosted demo funnel</td></tr>

package/dist/sitemap.xml

@@ -2,7 +2,7 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://cozyclay.org/</loc>
-    <lastmod>2026-10-24</lastmod>
+    <lastmod>2026-10-27</lastmod>
   </url>
   <url>
     <loc>https://cozyclay.org/greybox-to-video/</loc>
@@ -22,6 +22,6 @@
   </url>
   <url>
     <loc>https://cozyclay.org/privacy/</loc>
-    <lastmod>2026-10-25</lastmod>
+    <lastmod>2026-10-27</lastmod>
   </url>
 </urlset>

package/dist/workflow/index.html

@@ -8,11 +8,12 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-DJwOUzqJ.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/task-board-CkLZGPkv.js">
+    <script type="module" crossorigin src="/assets/workflow-CSiBlX1s.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/analytics-CaTUuLPM.js">
+    <link rel="modulepreload" crossorigin href="/assets/task-board-UVGTZLRF.js">
+    <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-P2Xu9kJm.js">
     <link rel="modulepreload" crossorigin href="/assets/fflate.module-KbGj5-H6.js">
-    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-t45pWCyq.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-CLGNbEBq.js">
     <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-BEjjhNEo.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>

package/mcp/README.md

@@ -73,7 +73,7 @@ generated frame matches the blocking instead of drifting off into a generic shot
 | `place_object` / `update_object` / `remove_object` | the set — `place_object` also accepts `name` and `parent`, so multi-part assets like "Building A" land as one named assembly |
 | `import_mesh` | load a local GLB, OBJ or FBX from a filesystem path as a mesh prop (live editor required); optional floor position, yaw, standing height, clay |
 | `sculpt_object` | build a clay prop from a recipe of soft parts (blob, box, cylinder, torus, frame), usually from a reference image; pass `id` with `recipe` to re-sculpt or with `edits` to patch parts; `capture: true` returns the frame too. Works without an editor. Contract: `docs/sculpt-from-image.md` |
-| `compare_sculpt` | score a sculpt's silhouette against its reference image (PNG/JPEG path): IoU, proportion delta, missing area by height band, parts that stick out, and a reference \| overlay sheet; `candidates` ranks up to 12 edit sets without applying any. Works without an editor |
+| `compare_sculpt` | score a sculpt's silhouette against its reference image (PNG/JPEG path): IoU, proportion delta, missing area by height band, parts that stick out, and a reference \| overlay sheet; `views` [{ yaw, reference, weight? }] scores several views (front 0.6, side 0.25, back 0.15 by default) in place of `reference`; `candidates` ranks up to 12 edit sets without applying any. Works without an editor |
 | `group_objects` | attach children to a parent so they move as one; pass `parent: null` to detach |
 | `apply_batch` | execute up to 100 object mutations as one user-visible undo transaction |
 | `render_prompt` | the shot as an AI image or video prompt |

package/mcp/live-hub.mjs

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { bucketMs, sanitizeProps } from "../src/analytics.js";
-import { mcpToolCategory } from "../src/execution-telemetry.js";
+import { mcpToolCategory, mcpToolName } from "../src/execution-telemetry.js";
 
 import { WebSocket, WebSocketServer } from "ws";
 
@@ -192,7 +192,7 @@ export class LiveHub {
 		const startedAt = safely(now);
 		if (typeof requestId !== "string" || !/^[a-f0-9]{32}$/.test(requestId) || !Number.isFinite(startedAt)) return work();
 		const workspaceId = this.workspaceId(handle);
-		const category = mcpToolCategory(name);
+		const category = mcpToolCategory(name), toolName = mcpToolName(name);
 		const emit = (event, props) => safely(() => {
 			// Do not reconstruct this lifecycle on a replacement connection.
 			if (this.editors.get(handle) !== socket || socket.readyState !== WebSocket.OPEN) return;
@@ -266,14 +266,14 @@ export class LiveHub {
 			if (value?.isError === true && !failure) failure = acknowledgedMutation ? "uncertain" : "failed";
 			terminal = true;
 			const endedAt = safely(now);
-			if (Number.isFinite(endedAt)) emit("mcp:tool_executed", { request_id: requestId, tool_category: category, outcome: failure ?? "succeeded", duration_bucket: bucketMs(endedAt - startedAt) });
+			if (Number.isFinite(endedAt)) emit("mcp:tool_executed", { request_id: requestId, tool_category: category, tool_name: toolName, outcome: failure ?? "succeeded", duration_bucket: bucketMs(endedAt - startedAt) });
 			emitApplied();
 			// Never retain scene data with an asynchronous motion job.
 			description = undefined;
 			studioContext = undefined;
 			mutation = null;
 		});
-		emit("mcp:tool_requested", { request_id: requestId, tool_category: category });
+		emit("mcp:tool_requested", { request_id: requestId, tool_category: category, tool_name: toolName });
 		return executionObserver.run(observer, async () => {
 			try {
 				const value = await work();

package/mcp/tool-handlers.mjs

@@ -32,6 +32,7 @@ import { MAX_COMMAND_TIMEOUT_MS } from "./live-hub.mjs";
 import { readMeshFromPath } from "./mesh-file.mjs";
 import { encodePng, readImageFromPath } from "./image-file.mjs";
 import { rankingRow, scoreSculptAgainstReference } from "../src/sculpt-compare.js";
+import { scoreSculptAgainstViews } from "../src/sculpt-views.js";
 import { DEFAULT_POSE } from "../src/poses.js";
 
 import {
@@ -75,7 +76,9 @@ import { documentWithCamera, splitSavedCamera } from "./project-camera.mjs";
 
 /** The authoring state. One scene document, one camera, one project name. */
 export const state = {
-	doc: createSceneDocument(),
+	// Memory mode keeps the one-character stage it always opened with; the
+	// studio's new project starts empty, and a connected editor reports its own.
+	doc: createSceneDocument({ seedCharacter: true }),
 	name: "Untitled",
 	/** the project's previs mode ("storyboard" | "animation"); the live editor reports it with every describe */
 	previsMode: DEFAULT_PREVIS_MODE,
@@ -1009,7 +1012,6 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				const st = stage();
 				const target = findCharacter(character);
 				if (!target) return text(`No character "${character}". ${castHint()}`);
-				if (st.characters.length === 1) return text("The scene needs at least one character.");
 				const letter = letterFor(target);
 				st.characters = st.characters.filter((c) => c !== target);
 				if (state.focus && !findCharacter(state.focus)) {
@@ -1231,17 +1233,18 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 					"Unlike capture_frame and sculpt_object, compare_sculpt scores a sculpt's shape against a reference image instead of rendering the shot or changing the sculpt. " +
 					"Give the sculpt's id and the path of the reference (PNG or JPEG on this machine; a flat background or transparency). It reads the reference's subject as a mask, draws the sculpt's silhouette from a view (yaw: the camera's azimuth, 0 in front, positive toward the subject's own left; elevation: degrees above), " +
 					"fits it to the subject's height and position, and returns IoU, the width-to-height delta, which height band is missing area (top, middle, bottom) and which parts stick out, plus a sheet: reference | overlay (grey both, red missing, blue extra). " +
-					"Omit yaw to try -45..45 and keep the best. Pass candidates (up to 12 labelled edit sets) to score several fixes in one call without applying any; the answer ranks them against the current sculpt. Shape only: colour is not scored. Works without an editor.",
+					"Omit yaw to try -45..45 and keep the best. Instead of reference, views [{ yaw, reference, weight? }] scores several views of the subject (a blueprint's front 0, side 90, back 180) and blends their IoUs by weight (default front 0.6, side 0.25, back 0.15; a view whose height:width differs from the front's by more than 35% gets 0), with one row per view. Pass candidates (up to 12 labelled edit sets) to score several fixes in one call without applying any; the answer ranks them against the current sculpt. Shape only: colour is not scored. Works without an editor.",
 				inputSchema: {
 					id: z.string().min(1).describe("the sculpt's object id"),
-					reference: z.string().min(1).describe("filesystem path to the reference PNG or JPEG"),
+					reference: z.string().min(1).optional().describe("filesystem path to the reference PNG or JPEG; give this or views"),
+					views: z.array(z.object({ yaw: z.number().min(-180).max(180), reference: z.string().min(1), weight: z.number().min(0).max(1).optional() })).min(1).max(4).optional().describe("several views of the subject (path + camera yaw each), scored together by weight; give this or reference"),
 					yaw: z.number().min(-180).max(180).optional().describe("reference camera azimuth in degrees; omitted tries -45..45"),
 					elevation: z.number().min(-60).max(60).optional().describe("reference camera elevation in degrees; default 0"),
 					candidates: z.array(z.object({ label: z.string().min(1).max(60), edits: z.array(z.object({}).passthrough()).min(1).max(48) })).min(1).max(12).optional()
 						.describe("alternative edit sets to score side by side without applying any; returns them ranked by IoU with the winner's sheet"),
 				},
 			},
-			async ({ id, reference, yaw, elevation = 0, candidates }) => {
+			async ({ id, reference, views, yaw, elevation = 0, candidates }) => {
 				const workspaceHandle = liveWorkspace.getStore();
 				if (liveHub?.connected) {
 					try { await refreshLiveDescription(workspaceHandle); } catch (error) { return liveError(error); }
@@ -1249,11 +1252,11 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				const target = scene().objects.find((o) => o.id === id);
 				if (!target) return text(`No object "${id}". Call describe_scene for the current ids.`);
 				if (target.renderer !== SCULPT_KIND || !target.recipe) return { content: [{ type: "text", text: `${id} is a ${target.renderer}, not a sculpt.` }], isError: true };
-				let image;
-				try { image = await readImageFromPath(reference); } catch (error) { return { content: [{ type: "text", text: error.message }], isError: true }; }
-				let result;
+				if ((reference === undefined) === (views === undefined)) return { content: [{ type: "text", text: "Give exactly one of reference (one view) or views (several weighted views)." }], isError: true };
+				let image, result;
+				try { image = views ? await Promise.all(views.map(async (view) => ({ ...view, image: await readImageFromPath(view.reference) }))) : await readImageFromPath(reference); } catch (error) { return { content: [{ type: "text", text: error.message }], isError: true }; }
 				try {
-					const scored = scoreSculptAgainstReference(target.recipe, image, { yaw, elevation, candidates });
+					const scored = views ? scoreSculptAgainstViews(target.recipe, image, { elevation, candidates }) : scoreSculptAgainstReference(target.recipe, image, { yaw, elevation, candidates });
 					result = scored.result;
 					if (candidates) {
 						const { ranked, refused } = scored;
@@ -1267,12 +1270,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 					return { content: [{ type: "text", text: error.message }], isError: true };
 				}
 				const png = encodePng(result.sheet.width, result.sheet.height, result.sheet.data);
-				return {
-					content: [
-						{ type: "text", text: JSON.stringify({ id, ...result.report }) },
-						{ type: "image", data: png.toString("base64"), mimeType: "image/png" },
-					],
-				};
+				return { content: [{ type: "text", text: JSON.stringify({ id, ...result.report }) }, { type: "image", data: png.toString("base64"), mimeType: "image/png" }] };
 			},
 		),
 
@@ -1527,7 +1525,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 					mode,
 					model: modelById(model) ?? undefined,
 					shot: currentShot(),
-					subject: framed.subject,
+					subject: framed?.subject ?? "",
 					subject2: other?.subject ?? null,
 					posePhrase: pose_phrase,
 					pose2Phrase: other ? pose2_phrase : "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozyclay",
-  "version": "3.1.6",
+  "version": "3.2.1",
   "description": "Open source previs software in the browser: block a scene, pose characters, author camera moves and cuts, then take the same shots to an AI video model.",
   "scripts": {
     "dev": "node tools/dev-full.mjs --host 127.0.0.1 --port 5180",
@@ -41,6 +41,7 @@
     "demo:api": "npm --prefix workers/api run dev",
     "demo:api:install": "npm --prefix workers/api ci",
     "qa:browser": "node tools/qa-browser.mjs --",
+    "tutorial:record": "node tools/tutorial/launch.mjs",
     "test:shot-authoring": "node test/verify-shot-authoring.mjs",
     "test:camera-follow": "node test/verify-camera-follow.mjs",
     "test:sample-at": "node test/verify-sample-at.mjs",
@@ -75,6 +76,7 @@
     "eslint": "^10.12.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "globals": "^17.13.0",
+    "jpeg-js": "0.4.4",
     "knip": "^6.41.0",
     "mediabunny": "^1.55.2",
     "posthog-js": "^1.418.12",

package/src/App.jsx

@@ -36,10 +36,12 @@ import { noteNavSwitch } from "./thrash-friction.js";
 
 import AgentPanel from "./workflow/AgentPanel.jsx";
 import SculptPanel from "./panels/SculptPanel.jsx";
+import { dropAssetAt } from "./asset-drop.js";
+import { saveSculptToShelf } from "./sculpt-shelf.js";
 import { createAgentPort, createSculptRun } from "./sculpt-run.js";
 import { SculptTurntable } from "./sculpt-stage.jsx";
 import { measureReferenceOutline } from "./sculpt-compare.js";
-import { BLUEPRINT_LAYOUT, buildBlueprintPrompt } from "./sculpt-blueprint.js";
+import { BLUEPRINT_LAYOUT, blueprintRunViews, buildBlueprintPrompt } from "./sculpt-blueprint.js";
 import { browserSculptImages } from "./commands/sculpt-images.js";
 import { sculptAgentClient, sculptModelLabel } from "./sculpt-mode.js";
 import { useSculptMode } from "./use-sculpt-mode.js";
@@ -140,7 +142,7 @@ import {
 	pathMetrics,
 	strokeToPathPoints,
 } from "./object-path.js";
-import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx"; import { SculptSketch } from "./sculpt-sketch.jsx";
+import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx"; import { SculptSketch } from "./sculpt-sketch.jsx"; import { PhysicsOverlayLayer } from "./physics-overlay.jsx"; import { syncPhysicsOverlays } from "./physics-overlay.js";
 import { routeOwnerFor } from "./route-owner.js";
 import {
 	exportFailureCode,
@@ -168,6 +170,8 @@ import {
 	RangePinMarker,
 	warmPoseThumbnails,
 } from "./posestudio.jsx";
+import { FingerHandles, useFingerEdit } from "./finger-handles.jsx";
+import { STORYBOARD_FONT, storyboardCaption, storyboardLine } from "./shell/storyboard-caption.js";
 
 import {
 	createIkState,
@@ -297,28 +301,6 @@ const CHARACTER_SCALE_BOUNDS = elementByPath("character.scale");
 // fades the same highlight out over the same two seconds.
 const AGENT_RECEIPT_HIGHLIGHT_MS = 2000;
 
-// The storyboard contact sheet is drawn on a bare 2d canvas, which has no
-// stylesheet to inherit from: it gets the studio's own type stack explicitly
-// so the sheet reads like the app it came out of.
-const STORYBOARD_FONT = '12px Inter, "Pretendard", "Noto Sans KR", system-ui, -apple-system, "Segoe UI", Helvetica, Arial, sans-serif';
-// One unwrapped caption line at 12px inside a 480px cell holds about 64
-// characters before it runs into the next column.
-const STORYBOARD_CAPTION_CHARS = 64;
-
-/** Cut a caption to what one unwrapped cell line holds. */
-function storyboardLine(text) {
-	return text.length > STORYBOARD_CAPTION_CHARS ? `${text.slice(0, STORYBOARD_CAPTION_CHARS - 1)}\u2026` : text;
-}
-
-/** Fold a labelled shot prompt into the one line a board cell can hold. */
-function storyboardCaption(prompt) {
-	return storyboardLine(prompt
-		.split("\n")
-		.filter((line) => line.startsWith("SHOT:") || line.startsWith("LENS:"))
-		.map((line) => line.slice(line.indexOf(":") + 1).trim())
-		.join(" · "));
-}
-
 /**
  * Pose ONE cast member's rig at an absolute timeline frame: its own clip first,
  * then its own IK correction layer on top. This is the single description of
@@ -1012,21 +994,8 @@ export default function App() {
 			raycaster.setFromCamera(pointer, cam);
 			const hit = new THREE.Vector3();
 			if (!raycaster.ray.intersectPlane(new THREE.Plane(new THREE.Vector3(0, 1, 0), 0), hit)) return;
-			// Dispatch on the payload kind: same ray, four spawners. Characters
-			// keep their tighter stage clamp (the rig walks, a prop does not);
-			// objects, cutouts and meshes take the same ROOM_LIMIT clamp their
-			// creators already apply.
-			if (payload.kind === "character") {
-				spawnCharacter(payload.id,
-					THREE.MathUtils.clamp(hit.x, CHARACTER_POSITION_BOUNDS.min.x, CHARACTER_POSITION_BOUNDS.max.x),
-					THREE.MathUtils.clamp(hit.z, CHARACTER_POSITION_BOUNDS.min.z, CHARACTER_POSITION_BOUNDS.max.z));
-			} else if (payload.kind === "object") {
-				addSceneObject(payload.objectKind, { x: hit.x, z: hit.z });
-			} else if (payload.kind === "image") {
-				spawnCutoutAt(payload.assetId, { x: hit.x, z: hit.z });
-			} else if (payload.kind === "mesh") {
-				spawnMeshAt(payload.assetId, { x: hit.x, z: hit.z });
-			}
+			// Dispatch on the payload kind (asset-drop.js): same ray, one spawner per kind.
+			dropAssetAt(payload, hit, { spawnCharacter, addSceneObject, spawnCutoutAt, spawnMeshAt, runStudioAction, select: setSelectedHierarchyId });
 		};
 		window.addEventListener("pointermove", onMove);
 		window.addEventListener("pointerup", onUp);
@@ -1121,6 +1090,7 @@ export default function App() {
 		ikDragEnd, ikAddKeyframe,
 		ikDeleteKeyframe, ikApplyPoseAsKey,
 	} = motionDomain;
+	const { handFingers, fingerEditing, setFingerEdit, exposureProbeRef: fingerExposureRef } = useFingerEdit(ikFocus, ikFkJoints);
 	const [partColoursEnabled, setPartColoursEnabled] = useState(false);
 	const [partColoursMode, setPartColoursMode] = useState("shaded");
 
@@ -1239,7 +1209,7 @@ export default function App() {
 		attachTargetForRow, attachTargetLabel, attachSceneObject,
 	} = objectsDomain;
 
-	const { sculptMode, sculptCamRef, sculptView, sculptReference, setSculptReference, sculptRun, setSculptRun, sculptRunRef, sculptAgentStatus, sculptModels, sculptModelPick, chooseSculptModel, sculptTransport, sculptTap, sculptTarget, setSculptTargetId, requestSculptView, sculptBlueprint, setSculptBlueprint, generateSculptBlueprint, cancelSculptBlueprint } = useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectId });
+	const { sculptMode, sculptCamRef, sculptView, sculptReference, setSculptReference, sculptRun, setSculptRun, sculptRunRef, sculptAgentStatus, sculptChatgpt, sculptModels, sculptModelPick, chooseSculptModel, sculptTransport, sculptTap, sculptTarget, setSculptTargetId, requestSculptView, sculptBlueprint, setSculptBlueprint, generateSculptBlueprint, cancelSculptBlueprint, sculptParts } = useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectId, appContext });
 	async function chooseSculptReference(file) {
 		try {
 			// A new reference makes the old sheet a drawing of something else.
@@ -1257,6 +1227,8 @@ export default function App() {
 			bus: { subscribe: (listener) => sculptTap.subscribe(listener, studioBindingRef.current?.bus) },
 			agent: createAgentPort(sculptAgentClient(sculptTransport, () => buildStudioAgentContext())),
 			reference: sculptReference,
+			// The blueprint's side and back crops, when a sheet was drawn (#970).
+			views: blueprintRunViews(sculptBlueprint.sheet),
 			sculptId: sculptTarget?.id ?? null,
 			score: (args) => appContext.bus.run("sculpt.compare", args, { origin: "ui" }),
 			measure: async (reference) => measureReferenceOutline(await browserSculptImages.decode(reference)),
@@ -1629,10 +1601,10 @@ export default function App() {
 				if (modeKey !== workflowMode && selectWorkflowMode(modeKey) === false) noteShortcutIgnored("mode", "workflow_mode");
 				return;
 			}
-			// Sculpt mode's W/E/R swing the turntable to front, side and back.
+			// Sculpt mode's W/E/R swing the turntable to front, side and back, or drive a selected part's gizmo.
 			if (workflowMode === "sculpt" && GIZMO_HOTKEYS[event.code]) {
 				event.preventDefault();
-				requestSculptView({ KeyW: "front", KeyE: "side", KeyR: "back" }[event.code]);
+				sculptParts.onKey(event.code);
 				return;
 			}
 			// Pose mode's W/R are the IK tools, gated like their Rig Control
@@ -1683,7 +1655,7 @@ export default function App() {
 				runStudioAction("object.duplicate");
 				return;
 			}
-			if (event.key === "Escape" && selectedSceneObjectId) {
+			if (event.key === "Escape" && selectedSceneObjectId && !event.defaultPrevented) {
 				setSelectedHierarchyId("props");
 				return;
 			}
@@ -2343,7 +2315,7 @@ export default function App() {
 		// patchable state, so every reader sees the body the save path writes.
 		stage: { shotAspect: shotAspectKey, cameraPresetId, sensorId, hasCharSheet, environmentImage, environment, style, hasEnvSheet, keyLight, lighting },
 		timeline: { currentFrame: tlFrame, frameCount: tlFrameCount, fps: tlFps },
-		activeCharacterId,
+		activeCharacterId: characters.length ? activeCharacterId : null,
 		partColours: partColoursEnabled ? PART_COLOURS : null,
 		waypoints,
 		characters,
@@ -2874,7 +2846,7 @@ export default function App() {
 		// pass is the recorder's stand-in for the useFrame the preview gets.
 		// Riding characters move with their object first, then the props.
 		syncCarriers();
-		propSyncRef.current?.();
+		propSyncRef.current?.(); syncPhysicsOverlays(frame);
 		const sampled = sampleAt(context?.playbackScene ?? playbackScene, shotAtFrame(context?.shots ?? shots, frame), frame);
 		const framing = sampled.camera ?? context?.framing;
 		const cam = shotCamRef.current;
@@ -2959,7 +2931,7 @@ export default function App() {
 			look.current.pitch = cameraSnapshot.pitch;
 			propFrameRef.current = propFrame;
 			syncCarriers();
-			propSyncRef.current?.();
+			propSyncRef.current?.(); syncPhysicsOverlays();
 		}
 	}
 
@@ -3657,7 +3629,7 @@ export default function App() {
 				const point = new THREE.Vector3(); bone.getWorldPosition(point);
 				return point.toArray();
 			},
-			committedIkEdits, waypoints,
+			committedIkEdits, waypoints, rigs, characters, // rigs/characters: every cast member (QA reads a second rig)
 			// Scene props as the stage sees them, for QA that places a box and
 			// waits for its transform to land before fitting to it.
 			objects: sceneObjects,
@@ -3702,22 +3674,14 @@ export default function App() {
 			// instead of driving a file dialog. Same liveStateRef reasoning as
 			// captureMeta — the effect does not depend on the shot list.
 			exportKeyframePack: async (shotId) => {
-				const attempt = startExportAttempt({ export_kind: "keyframe_pack", format: "zip", surface: embedMode ? "embed" : "studio" });
-				try {
-					const live = appContext.live.state;
-					const index = live.shotIndexForPack(shotId ?? null);
-					const pack = await live.buildShotKeyframePack(live.shots[index], index);
-					// base64: a pack holds an MP4, and a megabyte-scale JS number array
-					// is not something to hand a CDP evaluate.
-					let binary = "";
-					for (const byte of pack.bytes) binary += String.fromCharCode(byte);
-					const result = { name: pack.name, entries: pack.entries.map((entry) => entry.name), byteLength: pack.bytes.byteLength, bytes: btoa(binary) };
-					attempt.succeed();
-					return result;
-				} catch (error) {
-					attempt.fail(error);
-					throw error;
-				}
+				const live = appContext.live.state;
+				const index = live.shotIndexForPack(shotId ?? null);
+				const pack = await live.buildShotKeyframePack(live.shots[index], index);
+				// base64: a pack holds an MP4, and a megabyte-scale JS number array
+				// is not something to hand a CDP evaluate.
+				let binary = "";
+				for (const byte of pack.bytes) binary += String.fromCharCode(byte);
+				return { name: pack.name, entries: pack.entries.map((entry) => entry.name), byteLength: pack.bytes.byteLength, bytes: btoa(binary) };
 			},
 			renderPass: (kind) => appContext.live.state.renderPassDataUrls([kind])[kind],
 			// QA-only video export (#193): the Export menu's Video item without the
@@ -4205,7 +4169,7 @@ export default function App() {
 			preserveAuthoredMotion: Boolean(c.layer?.waypoints?.length) }]));
 		return { host: { workspaceId: liveWorkspaceIdRef.current, documentEpoch: studioDocumentEpochRef.current,
 				sceneId: activeSceneIdRef.current, sceneEpoch: studioSceneEpochRef.current }, workspaceHandle: liveWorkspaceHandleRef.current,
-			sceneName: live.scenes.find(s => s.id === activeSceneIdRef.current)?.name ?? "Untitled Scene", previsMode: scenesDomain.previsMode, aspect: live.stage.shotAspect, stage: live.stage,
+			sceneName: live.scenes.find(s => s.id === activeSceneIdRef.current)?.name ?? "Untitled Scene", previsMode: scenesDomain.previsMode, castStyle: scenesDomain.castStyle, aspect: live.stage.shotAspect, stage: live.stage,
 			objects: storeRef.current.objects, characters: list, targets, shots: live.shots, frameCount: live.timeline.frameCount,
 			selection: live.studioSelection, activeCharacterId: live.activeCharacterId, selectedShotId: live.studioShotId,
 			view: live.studioView, camera: live.studioCamera ?? readStudioCamera(), filmback: live.filmback, manual: manualCameraOverrideRef.current,
@@ -4400,7 +4364,7 @@ export default function App() {
 		// an action sees its own edit before React renders it.
 		state: () => ({
 			shots: appContext.live.state.shots, objects: storeRef.current.objects, characters: appContext.live.characters, frame: tlFrame, frameCount: tlFrameCount,
-			selectedObjectId: selectedSceneObjectId, activeCharacterId: activeChar?.id ?? null,
+			selectedObjectId: selectedSceneObjectId, activeCharacterId: characters.length ? activeChar.id : null,
 			
 			generating: false,
 			motionReady: false,
@@ -4476,19 +4440,20 @@ export default function App() {
 	// Sculpt mode's panel heads the Details column (DetailsSlot mounts it).
 	const sculptPanel = sculptMode && !embedMode ? (
 		<SculptPanel
-			run={sculptRun}
+			run={sculptRun} parts={sculptParts}
 			reference={sculptReference}
 			onReference={(file) => void chooseSculptReference(file)}
 			onStart={startSculptRun}
 			onCancel={() => sculptRunRef.current?.cancel()}
 			onPlaceInScene={placeSculptInScene}
+			onSaveToShelf={() => void saveSculptToShelf(sculptTarget).then(setToast)}
 			canStart={Boolean(sculptReference) && sculptAgentStatus === "ready" && Boolean(liveWorkspaceHandle) && Boolean(sculptModelPick.model)}
 			blueprint={{
 				...sculptBlueprint,
 				prompt: buildBlueprintPrompt({ pose: sculptBlueprint.pose, notes: sculptBlueprint.notes }),
 				layout: BLUEPRINT_LAYOUT,
-				// The image model is ChatGPT-only (the sidecar refuses others with a reason).
-				refusal: sculptAgentStatus === "signed-out" ? ko("Sign in with ChatGPT in the Agent panel to generate a blueprint.", "도면을 생성하려면 에이전트 패널에서 ChatGPT로 로그인하세요.") : null,
+				// The image model is ChatGPT-only: without a ChatGPT token the button is hidden and this says why (#970).
+				refusal: !sculptChatgpt ? ko("Sign in with ChatGPT in the Agent panel to generate a blueprint.", "도면을 생성하려면 에이전트 패널에서 ChatGPT로 로그인하세요.") : null,
 				onPose: (pose) => setSculptBlueprint((current) => ({ ...current, pose })),
 				onNotes: (notes) => setSculptBlueprint((current) => ({ ...current, notes })),
 				onGenerate: () => void generateSculptBlueprint(),
@@ -4515,7 +4480,7 @@ export default function App() {
 	// The single shell snapshot keeps subsequent region work out of App.
 	const shellContext = {
 		sculptPanel,
-		projectMenuOpen, setProjectMenuOpen, projectDirty, projectName, previsMode, projectStartupOpen,
+		projectMenuOpen, setProjectMenuOpen, projectDirty, projectName, previsMode, castStyle: scenesDomain.castStyle, projectStartupOpen,
 		requestNewProject, setProjectStartupOpen, setProjectBrowserOpen, runStudioAction, saveProject,
 		projectManifest, projectSaveState, recState, exportMenuTriggerRef, exportMenuOpen,
 		exportShotIdRef, setExportMenuAnchor, setExportMenuOpen, exportPhaseLabel,
@@ -4529,7 +4494,7 @@ export default function App() {
 		activeSceneId, selectSceneDocument, createSceneDocumentFromUi, duplicateSceneDocumentFromUi, renameSceneDocumentFromUi,
 		deleteSceneDocumentFromUi, addSceneObject, renameSceneObject, deleteSceneObject, frameSelection, groupObjectUnderNewEmpty, renameRequest,
 		toggleHierarchyHidden, propsDrop, hierarchyReparent, agentTouchedRows, workflowMode,
-		selectWorkflowMode, gizmoMode, setGizmoMode, snapEnabled, setSnapEnabled, sculptView, requestSculptView,
+		selectWorkflowMode, gizmoMode, setGizmoMode, snapEnabled, setSnapEnabled, sculptView, requestSculptView, sculptParts,
 		preset, applyPreset, cameraPresetId, shotAspectKey,
 		fovDeg, shotsDomain, shot, setNonce, workspaceLayout,
 		viewMenuTriggerRef, viewMenuOpen, setViewMenuAnchor, setViewMenuOpen, viewLooksActive,
@@ -4546,7 +4511,7 @@ export default function App() {
 		setStudioPick, appContext, removePose, activeRig, saveCurrentPose,
 		setTlFrame, tlFrameCount,
 		tlFrame, isRigSelection, ikChains, ikFocus, footSnap, poseObjectOpacity, setPoseObjectOpacity, capturePoseImage,
-		ikEditTool, setIkEditTool,
+		ikEditTool, setIkEditTool, ikSolve, ikDragEnd, ikTick, handFingers, fingerEditing, setFingerEdit,
 		pendingIkEdit, applyPendingIkEdit, cancelPendingIkEdit,
 		rangePins, rangePinResiduals, rangePinSelection, rangePinPartPick,
 		rangePinPreview, setRangePinSelection, setRangePinPartPick, previewRangePinDraft, applyRangePinDraft,
@@ -4724,7 +4689,7 @@ export default function App() {
 							{sculptMode && (
 								<SculptTurntable
 									camRef={sculptCamRef}
-									objects={sceneObjects}
+									objects={sceneObjects} parts={sculptParts}
 									target={sculptTarget}
 									size={sculptTarget ? objectSize(sculptTarget) : null}
 									view={sculptView}
@@ -4762,7 +4727,7 @@ export default function App() {
 									/>
 								</ObjectCarrier>
 							))}
-							<ViewGhosts rig={rigs[activeChar.id]} take={motion} frame={tlFrame} objects={sceneObjects} propTake={{ frameCount: tlFrameCount, fps: tlFps, objectTracks }} /><DraftGhost rigs={rigs} objects={sceneObjects} /><SculptSketch objects={sceneObjects} />
+							<ViewGhosts rig={rigs[activeChar.id]} take={motion} frame={tlFrame} objects={sceneObjects} propTake={{ frameCount: tlFrameCount, fps: tlFps, objectTracks }} /><DraftGhost rigs={rigs} objects={sceneObjects} /><SculptSketch objects={sceneObjects} /><PhysicsOverlayLayer rig={rigs[activeChar.id]} take={motion} objects={sceneObjects} />
 
 							{/* Selection marker: XYZ tripod + ring on the picked cast
 							    member; the X/Z arrows drag it across the deck. */}
@@ -4882,7 +4847,9 @@ export default function App() {
 								onFocus={focusIkHandle}
 								onSolve={ikSolve}
 								onDragEnd={ikDragEnd}
+								focusToolsHidden={fingerEditing} exposureProbeRef={fingerExposureRef}
 							/>
+							<FingerHandles fingers={handFingers} enabled={fingerEditing && ikMode && ikEditTool === "ik" && !posing && !playMode} onSolve={ikSolve} onDragEnd={ikDragEnd} exposureProbeRef={fingerExposureRef} />
 							<RangePinMarker
 								chains={ikChains}
 								track={rangePinPreview?.track}
@@ -5268,9 +5235,9 @@ export default function App() {
 						openProject();
 					}}
 					starters={STARTER_SCENES}
-					onStarter={(id, name) => {
+					onStarter={(id, name, options) => {
 						setProjectBrowserOpen(false);
-						void openStarterScene(id, "starter", name);
+						void openStarterScene(id, "starter", name, options?.castStyle);
 					}}
 					onNew={(name, options) => {
 						setProjectBrowserOpen(false);