cozyclay 3.1.6 → 3.2.1

package/src/analytics-controls.js

@@ -1,5 +1,5 @@
 // The closed list of primary Studio controls that carry `data-fid`, for
-// ui:rage_click and ui:dead_click. A click on any other control reports "other".
+// ui:rage_click and ui:dead_click. A click on any other control reports its area (AREA_IDS) or "other".
 // Ids name a control, never a scene object, a name or any text.
 export const CONTROL_IDS = Object.freeze([
 	"dock_tab_board", "dock_tab_animation", "dock_tab_assets",
@@ -13,5 +13,27 @@ export const CONTROL_IDS = Object.freeze([
 	"board_export", "board_stylize",
 ]);
 
-/** The closed control id of a `data-fid` value, else "other". */
-export const controlOf = (fid) => (CONTROL_IDS.includes(fid) ? fid : "other");
+// A control with no listed `data-fid` reports the Studio area it sits in, by
+// the area's own class; the first match wins, so nested areas come first.
+const AREAS = [
+	["other_guide", ".first-success-guide"],
+	["other_agent", ".agent-panel"],
+	["other_menu", ".menubar, [role='menu']"],
+	["other_sculpt", ".sculpt-panel"],
+	["other_assets", ".content-browser"],
+	["other_board", ".dock-board"],
+	["other_timeline", ".bottom-timeline, .studio-dock-slot"],
+	["other_inspector", ".inspector-pane, .studio-right-column"],
+	["other_viewport", ".studio-left-column"],
+];
+export const AREA_IDS = Object.freeze(AREAS.map(([id]) => id));
+
+/** The closed control id of a `data-fid` value; else the area of `element`, else "other". */
+export function controlOf(fid, element = null) {
+	if (CONTROL_IDS.includes(fid)) return fid;
+	for (const [id, selector] of AREAS) if (element?.closest?.(selector)) return id;
+	return "other";
+}
+
+/** An area id or "other": a control the Studio does not name. */
+export const isUnnamedControl = (control) => control === "other" || AREA_IDS.includes(control);

package/src/analytics-strict.js

@@ -4,7 +4,7 @@
 import { STUDIO_ERROR_CODES } from "./studio-error-codes.js";
 import { ERROR_TYPE_VALUES, sessionEndedPropAllowed } from "./analytics-values.js";
 import { FRICTION_SUMMARY_KEYS, frictionPropAllowed } from "./analytics-friction.js";
-import { CONTROL_IDS } from "./analytics-controls.js";
+import { AREA_IDS, CONTROL_IDS } from "./analytics-controls.js";
 
 const TURN_ID_PATTERN = /^[a-f0-9]{32}$/;
 // The friction count vocabulary (analytics-friction.js bucketFrictionCount).
@@ -18,6 +18,9 @@ const REFUSAL_CODES = new Set([...STUDIO_ERROR_CODES, "other"]);
 export const CONNECT_PROVIDERS = Object.freeze(["openai-codex", "anthropic", "anthropic-subscription", "openai", "google",
 	"minimax", "minimax-cn", "openrouter", "cliproxy", "openai-compatible"]);
 
+/** landing:cta_clicked targets: the landing page's links out and copy buttons. */
+export const LANDING_CTA_TARGETS = Object.freeze(["app", "github", "discord", "npm", "copy_npx", "copy_clone", "copy_mcp", "copy_terminal", "agent_install_doc"]);
+
 /** A Studio refusal code as sent: one of STUDIO_ERROR_CODES, else "other". */
 export const refusalCodeOf = (code) => (STUDIO_ERROR_CODES.includes(code) ? code : "other");
 
@@ -51,6 +54,8 @@ const SCHEMAS = Object.freeze({
 	"studio:refused": {
 		code: inSet(REFUSAL_CODES), origin: oneOf("ui", "agent"), phase: oneOf("admission", "commit"),
 		group: oneOf("object", "shot", "cast", "scene", "motion", "edit", "task", "agent", "other"),
+		// A registered Studio action id (command-bus-telemetry.js sends only those): code-defined, never args (#975).
+		command: (value) => typeof value === "string" && value.length <= 48 && /^[a-z][a-zA-Z0-9]*(?:\.[a-zA-Z0-9]+){1,3}$/.test(value),
 	},
 	// error_type: the app:error label set (analytics.js describeError); never a message or stack.
 	"app:render_crash": { error_type: inSet(ERROR_TYPE_VALUES) },
@@ -69,6 +74,10 @@ const SCHEMAS = Object.freeze({
 	"guide:dismissed": { mode: oneOf("animation", "storyboard"), reached: oneOf("1", "2", "3", "4") },
 	"guide:completed": { mode: oneOf("animation", "storyboard") },
 	"agent:panel_toggled": { open: bool, via: oneOf("key", "button") },
+	// The Export flyout opening (export-menu-telemetry.js); shots is analytics.js bucketCount.
+	"export:menu_opened": {
+		surface: oneOf("studio", "embed"), mode: oneOf("animation", "storyboard"), webcodecs: bool, shots: oneOf("0", "1-3", "4-10", "gte11"),
+	},
 	"object:deleted_soon": { age: inSet(AGE_BUCKETS) },
 	"object:delete_undone": { age: inSet(AGE_BUCKETS) },
 	"edit:undone": {
@@ -94,6 +103,8 @@ const SCHEMAS = Object.freeze({
 	},
 	"shortcut:unbound": { combo: oneOf("copy", "paste", "cut", "select_all", "group", "find", "rename", "help") },
 	"help:shortcuts_opened": {},
+	// The landing page (src/site/landing-analytics.js): which call to action was pressed, never a URL or copied text.
+	"landing:cta_clicked": { target: oneOf(...LANDING_CTA_TARGETS) },
 	"search:no_results": { surface: oneOf("assets", "outliner"), query_len: oneOf("1", "2-3", "4-8", "gte9") },
 	"nav:thrash": { surface: oneOf("dock_tab", "mode", "agent_panel"), switches: oneOf("4-5", "6-10", "gte11"), window_s: oneOf(10) },
 	"camera:thrash": { gestures: oneOf("6-10", "gte11"), kind_mix: oneOf("orbit", "fly", "pan", "mixed"), window_s: oneOf(20) },
@@ -110,11 +121,12 @@ const SCHEMAS = Object.freeze({
 		gap: (value) => value === "first" || long(value), prev_outcome: oneOf("succeeded", "failed", "cancelled", "none"), turn_index: count,
 		attached: bool, task_mode: bool,
 	},
-	"ui:rage_click": { control: oneOf(...CONTROL_IDS, "other"), clicks: oneOf("3", "4-5", "gte6"), changed: bool },
-	"ui:dead_click": { control: oneOf(...CONTROL_IDS, "other"), reason: oneOf("aria_disabled", "refused", "no_effect") },
+	"ui:rage_click": { control: oneOf(...CONTROL_IDS, ...AREA_IDS, "other"), clicks: oneOf("3", "4-5", "gte6"), changed: bool },
+	"ui:dead_click": { control: oneOf(...CONTROL_IDS, ...AREA_IDS, "other"), reason: oneOf("aria_disabled", "refused", "no_effect") },
 	// The update notice (src/update/update-telemetry.js): an install kind and buckets, never a version string or npm output.
 	"update:notice_shown": { kind: oneOf("global", "npx"), behind: oneOf("patch", "minor", "major") },
-	"update:clicked": { action: oneOf("update_now", "copy_command", "later", "dismiss", "release_notes"), kind: oneOf("global", "npx") },
+	"update:clicked": { action: oneOf("update_now", "copy_command", "later", "dismiss", "release_notes", "restart"), kind: oneOf("global", "npx") },
+	"update:restarted": { outcome: oneOf("ok", "timeout") },
 	"update:finished": {
 		outcome: oneOf("ok", "failed"), error_class: oneOf("none", "permission", "network", "node_version", "npm_missing", "other"), duration: long,
 	},

package/src/analytics.js

@@ -1,17 +1,16 @@
+import { appVersion } from "./app-version.js";
 import { FIRST_EDIT_KINDS, FIRST_EDIT_VERSION } from "./semantic-edit.js";
 import { ERROR_TYPE_VALUES, EXPORT_FAILURE_CODES, exportPropAllowed } from "./analytics-values.js";
 import { bump as bumpFriction, observeLongTasks, snapshot as frictionSnapshot } from "./analytics-friction.js";
 import { STRICT_EVENT_KEYS, strictPropValidator } from "./analytics-strict.js";
-export const MCP_TOOL_CATEGORIES = Object.freeze([
-	"read",
-	"camera",
-	"scene_write",
-	"prompt_authoring",
-	"frame_capture",
-	"motion_generate",
-	"motion_apply",
-	"project_io",
-	"other",
+export const MCP_TOOL_CATEGORIES = Object.freeze(["read", "camera", "scene_write", "prompt_authoring", "frame_capture", "motion_generate", "motion_apply", "project_io", "other"]);
+// The live MCP tools (mcp/tool-handlers.mjs liveWorkspaceTools) plus "other".
+// Any other name is sent as "other"; test/verify-analytics.mjs holds the two lists equal.
+export const MCP_TOOL_NAMES = Object.freeze([
+	"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", "other",
 ]);
 export const AGENT_TOOL_CATEGORIES = Object.freeze([
 	"workflow_read",
@@ -52,8 +51,8 @@ export const EXECUTION_TELEMETRY_PROPERTY_KEYS = Object.freeze({
 	"agent:turn_failed": ["turn_id", "duration_bucket", "failure_code"],
 	"agent:turn_cancelled": ["turn_id", "duration_bucket", "failure_code"],
 	"agent:result_applied": ["turn_id"],
-	"mcp:tool_requested": ["tool_category", "request_id"],
-	"mcp:tool_executed": ["tool_category", "outcome", "duration_bucket", "request_id"],
+	"mcp:tool_requested": ["tool_category", "tool_name", "request_id"],
+	"mcp:tool_executed": ["tool_category", "tool_name", "outcome", "duration_bucket", "request_id"],
 	"mcp:result_applied": ["request_id"],
 });
 
@@ -62,6 +61,7 @@ export const EXECUTION_TELEMETRY_VALUES = Object.freeze({
 	node_count_bucket: new Set(["0", "1-3", "4-10", "gte11"]),
 	duration_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
 	tool_category: new Set([...MCP_TOOL_CATEGORIES, ...AGENT_TOOL_CATEGORIES]),
+	tool_name: new Set(MCP_TOOL_NAMES),
 	outcome: new Set(["succeeded", "failed", "uncertain", "cancelled"]),
 });
 
@@ -90,8 +90,8 @@ export const EDIT_GROUPS = Object.freeze({
 export const EDIT_BUCKET_KEYS = Object.freeze(Object.keys(EDIT_GROUPS).map((group) => `${group}_edit_bucket`));
 export const USE_CASE_VALUES = Object.freeze(["animation", "film", "game", "ad_mv", "personal", "other", "skip"]);
 export const TEAM_VALUES = Object.freeze(["team", "solo", "skip"]);
-// Mirrors PREVIS_MODES in project.js; kept local so analytics stays import-light.
-export const PREVIS_MODE_VALUES = new Set(["storyboard", "animation"]);
+// Mirror PREVIS_MODES and CAST_STYLES in project.js; kept local so analytics stays import-light.
+export const PREVIS_MODE_VALUES = new Set(["storyboard", "animation"]), CAST_STYLE_VALUES = new Set(["rig", "capsule", "hybrid"]);
 export const UPDATE_STATUS_VALUES = Object.freeze(["latest", "outdated", "unknown"]);
 const DEFAULT_ALLOWED_ORIGINS = Object.freeze([
 	"https://cozyclay.org",
@@ -112,7 +112,7 @@ const EVENT_PROPERTIES = Object.freeze({
 	"hosted:ticket_created": [],
 	"hosted:result_opened": [],
 	"hosted:opened_in_studio": [],
-	"scene:created": ["scene_source", "previs_mode"],
+	"scene:created": ["scene_source", "previs_mode", "cast_style"],
 	"storyboard:panel_created": ["source"],
 	"storyboard:panel_stylized": ["outcome"],
 	"cast:proxy_added": ["surface"],
@@ -154,7 +154,7 @@ const SCULPT_RUN_MAX_ROUNDS = 10;
 const SCULPT_RUN_MAX_DURATION_MS = 86_400_000;
 const EXECUTION_FAILURE_CODES = Object.freeze({
 	workflow: new Set(["aborted", "capture_failed", "generation_failed", "unknown"]),
-	agent: new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "unknown", "key_refused", "stale_scene", "capability_missing", "busy", "invalid_request"]),
+	agent: new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "network", "unknown", "key_refused", "stale_scene", "capability_missing", "busy", "invalid_request"]),
 });
 // Only a type label and a same-origin script location cross the boundary; the
 // error message, stack text, URLs and anything a user typed never do.
@@ -282,6 +282,8 @@ export function sanitizeProps(event, props) {
 			else if (key === "tool_category") {
 				const categories = event.startsWith("agent:") ? AGENT_TOOL_CATEGORIES : MCP_TOOL_CATEGORIES;
 				if (!categories.includes(props[key])) continue;
+			} else if (key === "tool_name") {
+				if (!event.startsWith("mcp:") || !EXECUTION_TELEMETRY_VALUES.tool_name.has(props[key])) continue;
 			} else if (key === "outcome") {
 				const outcomes = event === "mcp:tool_executed" ? ["succeeded", "failed", "uncertain", "cancelled"] : ["succeeded", "failed", "cancelled"];
 				if (!outcomes.includes(props[key])) continue;
@@ -311,7 +313,7 @@ export function sanitizeProps(event, props) {
 			else if (key === "had_target" && typeof value === "boolean") sanitized[key] = value;
 			continue;
 		}
-		if (key === "previs_mode" && !PREVIS_MODE_VALUES.has(props[key])) continue;
+		if ((key === "previs_mode" && !PREVIS_MODE_VALUES.has(props[key])) || (key === "cast_style" && !CAST_STYLE_VALUES.has(props[key]))) continue;
 		if ((event.startsWith("storyboard:") || event.startsWith("cast:")) && !PREVIS_PROPERTY_VALUES[key]?.has(props[key])) continue;
 		if (event === "survey:use_case") {
 			if (key === "use_case" && !USE_CASE_VALUES.includes(props[key])) continue;
@@ -668,7 +670,10 @@ function runtimeConfig() {
 function isLoopbackOrigin(origin) {
 	try {
 		const parsed = new URL(origin);
-		return parsed.protocol === "http:" && ["127.0.0.1", "localhost"].includes(parsed.hostname);
+		if (parsed.protocol !== "http:") return false;
+		// Loopback and LAN hosts both mean the studio is self-served, not hosted.
+		if (["127.0.0.1", "localhost"].includes(parsed.hostname)) return true;
+		return /^(10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.)/.test(parsed.hostname);
 	} catch {
 		return false;
 	}
@@ -715,7 +720,8 @@ export function resolveAnalyticsRuntime({
 		distribution: "hosted",
 		apiKey: env.VITE_POSTHOG_KEY,
 		apiHost: env.VITE_POSTHOG_HOST || "https://us.i.posthog.com",
-		appVersion: env.VITE_APP_VERSION || null,
+		// The deploy sets no VITE_APP_VERSION, so the bundled package version stands in.
+		appVersion: env.VITE_APP_VERSION || appVersion(),
 		installationId: null,
 		firstLaunch: false,
 		firstLaunchHeardFrom: null,
@@ -743,7 +749,8 @@ function disabledReason(env) {
 	return runtime.kind === "disabled" ? runtime.reason : getAnalyticsOptOut() ? "opted out" : null;
 }
 
-export async function initAnalytics() {
+/** `lite` (the landing page): $pageview and explicit events only; no session, error, long-task or device signals. */
+export async function initAnalytics({ lite = false } = {}) {
 	if (initialized || initPromise) return initPromise;
 	// Explicit hosted opt-in only. This flag never changes consent or build
 	// policy; npm installations use the CLI-owned state instead.
@@ -781,7 +788,9 @@ export async function initAnalytics() {
 				// Hosted visits persist in the browser. Official npm sessions
 				// bootstrap from the CLI-owned installation id instead.
 				persistence: resolved.distribution === "npm" ? "memory" : "localStorage",
-				respect_dnt: true,
+				// Browser DNT is set by extensions and OS defaults, not by a deliberate
+				// per-site choice; the preference toggle remains the explicit signal.
+				respect_dnt: false,
 				disable_session_recording: true,
 				capture_dead_clicks: false,
 				capture_performance: false,
@@ -809,11 +818,8 @@ export async function initAnalytics() {
 			globalThis.__cozyclayAnalytics = { instance: posthog };
 			posthog.capture("$pageview");
 			sessionStartedAt = Date.now();
-			installSessionEndListeners(resolved, globalProperties);
-			installErrorListeners();
-			observeLongTasks();
-			void recordDeviceProfile();
-			if (resolved.distribution === "npm") {
+			if (!lite) { installSessionEndListeners(resolved, globalProperties); installErrorListeners(); observeLongTasks(); void recordDeviceProfile(); }
+			if (resolved.distribution === "npm" && !lite) {
 				track("app:session_started");
 				if (resolved.firstLaunch) {
 					const heardFrom = resolved.firstLaunchHeardFrom;

package/src/app-version.js

@@ -0,0 +1,13 @@
+// The version Help › About names. The npm launcher injects the running
+// package's version as window.__COZYCLAY_RUNTIME__.appVersion; the hosted
+// site and Vite dev have no runtime, so they fall back to package.json the
+// way the start screen does (src/project-browser.jsx).
+import packageInfo from "../package.json" with { type: "json" };
+
+export function appVersion(win = globalThis.window, fallback = packageInfo.version) {
+	try {
+		const runtime = win?.__COZYCLAY_RUNTIME__?.appVersion;
+		if (typeof runtime === "string" && runtime.trim()) return runtime.trim();
+	} catch { /* a throwing getter reads as no runtime */ }
+	return fallback;
+}

package/src/asset-drop.js

@@ -0,0 +1,39 @@
+// Where a Content tile lands: one spawner per payload kind, the same table for
+// the drag onto the stage (App's floor raycast) and the double-click placement
+// at the origin (LibrarySlot). Characters keep their tighter stage clamp (the
+// rig walks, a prop does not); objects, cutouts, meshes and sculpts take the
+// ROOM_LIMIT clamp their creators already apply.
+import { elementByPath } from "./studio-elements.js";
+
+const CHARACTER_BOUNDS = elementByPath("character.position").gizmo;
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+const DROPS = {
+	character: (payload, at, spawn) => spawn.spawnCharacter(payload.id,
+		clamp(at.x, CHARACTER_BOUNDS.min.x, CHARACTER_BOUNDS.max.x),
+		clamp(at.z, CHARACTER_BOUNDS.min.z, CHARACTER_BOUNDS.max.z)),
+	object: (payload, at, spawn) => spawn.addSceneObject(payload.objectKind, at),
+	image: (payload, at, spawn) => spawn.spawnCutoutAt(payload.assetId, at),
+	mesh: (payload, at, spawn) => spawn.spawnMeshAt(payload.assetId, at),
+	// A shelf card carries its recipe: object.sculpt makes it through
+	// createSculptObject as one undo step, and the new sculpt is selected.
+	sculpt: (payload, at, spawn) => {
+		const receipt = spawn.runStudioAction("object.sculpt", { recipe: payload.recipe, ...(payload.name ? { name: payload.name } : {}), placement: at });
+		const id = receipt?.affectedIds?.[0];
+		if (id) spawn.select?.(`object:${id}`);
+		return receipt;
+	},
+};
+
+/**
+ * Spawn `payload` at the floor point `hit` ({ x, z }; y is ignored). `spawn`
+ * names the creators: spawnCharacter, addSceneObject, spawnCutoutAt,
+ * spawnMeshAt, runStudioAction and select. An unknown kind does nothing and
+ * answers false.
+ */
+export function dropAssetAt(payload, hit, spawn) {
+	const drop = DROPS[payload?.kind];
+	if (!drop) return false;
+	drop(payload, { x: hit.x, z: hit.z }, spawn);
+	return true;
+}

package/src/asset-pane.css

@@ -460,3 +460,37 @@
 		scrollbar-color: var(--surface-active, #26262a) transparent;
 	}
 }
+
+@layer regions {
+	/* #740: the Sculpts folder's import / export / delete row above its grid. */
+	.content-browser .sculpt-shelf-actions {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: var(--sp-1, 8px);
+		margin-bottom: var(--sp-1, 8px);
+	}
+
+	.content-browser .sculpt-shelf-actions button {
+		padding: 3px 10px;
+		border: 1px solid var(--line2, #2c2c31);
+		border-radius: var(--r-1, 4px);
+		background: var(--surface-raised, #1e1e21);
+		color: var(--text-row, #c9c9ce);
+		font-size: var(--content-font-secondary);
+		cursor: pointer;
+	}
+
+	.content-browser .sculpt-shelf-actions button:hover {
+		border-color: var(--select, #e8a33d);
+	}
+
+	.content-browser .sculpt-shelf-note {
+		color: var(--text-3, #636369);
+		font-size: var(--content-font-secondary);
+	}
+
+	.content-browser .sculpt-shelf-delete {
+		color: var(--danger, #e5484d);
+	}
+}

package/src/asset-pane.jsx

@@ -7,6 +7,8 @@ import { assetAspect, isImageAssetId, isMeshAssetId, isSupportedMeshType } from
 import { assetKind, formatAssetBytes } from "./asset-shelf.js";
 import { assetRecord } from "./scene-asset-cache.js";
 import ResourceStatus from "./resource-status.jsx";
+import { ContentTile, grabProps } from "./content-tile.jsx";
+import SculptShelf from "./sculpt-shelf-tiles.jsx";
 import { logStore } from "./shell/log-store.js";
 import { SearchEmpty } from "./search-friction.js";
 import "./asset-pane.css";
@@ -130,18 +132,6 @@ function loadThumb(id) {
 	return thumbCache.get(id);
 }
 
-/** The grab wire every card shares: left button only, App owns the rest. */
-function grabProps(onAssetGrab, payload) {
-	return {
-		onPointerDown: (event) => {
-			if (event.button !== 0) return;
-			event.preventDefault();
-			onAssetGrab?.(payload, event);
-		},
-	};
-}
-
-
 function StorageAssetRow({ id, onDelete, deleting, usageCount = 0, graphSignature }) {
 	const [thumb, setThumb] = useState(null);
 	// Capture the graph observed when the explicit confirmation opens. A render
@@ -245,29 +235,6 @@ function StorageManager({ unusedAssetIds, usedAssetIds, usageCounts, graphSignat
 }
 
 
-/** The Content grid's one tile grammar: a square thumbnail, an 11px name and
- * a 10px type line. Click selects (amber ring), a left-button press starts the
- * App-owned drag, double-click places the asset at the origin. */
-function ContentTile({ assetKey, label, type, title, preview, selected, onSelect, grab, onPlace, failed = false }) {
-	return (
-		<button
-			type="button"
-			className={"content-tile" + (failed ? " is-failed" : "")}
-			data-testid="content-asset"
-			data-asset-key={assetKey}
-			aria-pressed={selected}
-			title={title}
-			{...(grab ?? {})}
-			onClick={() => onSelect(assetKey)}
-			onDoubleClick={onPlace ? () => onPlace() : undefined}
-		>
-			<span className="content-tile-thumb">{preview}</span>
-			<span className="content-tile-name">{label}</span>
-			<span className="content-tile-type">{type}</span>
-		</button>
-	);
-}
-
 function useThumb(id) {
 	// null = decoding (skeleton), undefined = record gone, object = ready.
 	const [thumb, setThumb] = useState(null);
@@ -375,6 +342,7 @@ const FOLDERS = [
 	{ id: "cameras", label: () => ko("Cameras", "카메라") },
 	{ id: "motions", label: () => ko("Motions", "모션") },
 	{ id: "poses", label: () => ko("Poses", "포즈") },
+	{ id: "sculpts", label: () => ko("Sculpts", "조형물", "雕塑") },
 ];
 
 function catalogueTile(entry, props) {
@@ -403,6 +371,7 @@ export function FolderGrid({ folder, query, ...props }) {
 	const { imageAssetIds, meshAssetIds, shots = [], takeVersions = [], poses = [], onShotOpen, onTakeOpen, selectedKey, onSelect } = props;
 	let tiles = [];
 	let empty = null;
+	if (folder === "sculpts") return <SculptShelf query={query} {...props} />;
 	if (folder === "basic") {
 		tiles = OBJECT_LIBRARY
 			.filter((entry) => entry.group === "Primitives" && matchesQuery(displayObjectLabel(entry.label), query))

package/src/bus-tasks.js

@@ -167,7 +167,7 @@ export function createBusTasks({ ports, emit }) {
 				task.edits.push({ receiptId: recorded.receiptId, values: point.values, keys: point.keys, mark: point.mark });
 				task.affectedIds = [...new Set([...task.affectedIds, ...recorded.affectedIds])];
 				if (recorded.undo?.historyEntryId) entryTask.set(recorded.undo.historyEntryId, task.taskId);
-				for (const other of open.values()) for (const key of point.keys) if (other !== task && other.reads.has(key)) {
+				for (const other of open.values()) for (const key of point.keys) if (other !== task && [...other.reads].some(read => keysOverlap(read, key))) {
 					other.notices.push({ code: 'DEPENDENCY_CHANGED', message: `${key}, which this task reads, was changed by task ${task.taskId}.` });
 					emit?.({ type: 'task.dependencyChanged', taskId: other.taskId, key, by: task.taskId });
 				}

package/src/character-kind.js

@@ -5,25 +5,27 @@
 import { isProxyFigure } from "./scenes.js";
 import { isKo, isZh } from "./locale.js";
 import { StudioProtocolError } from "./studio-agent-protocol.js";
+import {
+	PROXY_BODY_HEIGHT, PROXY_BODY_RADIUS, PROXY_HEAD_LIFT, PROXY_HEAD_RADIUS, PROXY_SIT_LEG_REACH, PROXY_SIT_TORSO_HEIGHT,
+} from "./proxy-figure-shape.js";
 
 export const CHARACTER_CAPABILITIES = Object.freeze(["rig", "ik", "pose", "motion"]);
-const PROXY_BODY_RADIUS = 0.22;
-const PROXY_BODY_HEIGHT = 1.45;
-const PROXY_HEAD_RADIUS = 0.12;
 
 /** Return a capsule figure's rendered world-space bounds without a rig. */
 export function proxyFigureBounds(character, placement = character) {
 	const posture = character?.posture === "sit" || character?.posture === "lie" ? character.posture : "stand";
-	const bodyHeight = posture === "sit" ? PROXY_BODY_HEIGHT * 0.6 : PROXY_BODY_HEIGHT;
+	const bodyHeight = posture === "sit" ? PROXY_SIT_TORSO_HEIGHT : PROXY_BODY_HEIGHT;
+	const top = bodyHeight + (PROXY_HEAD_LIFT + PROXY_HEAD_RADIUS);
 	const stature = Number.isFinite(placement?.scale) ? placement.scale : Number.isFinite(character?.scale) ? character.scale : 1;
 	const x = Number.isFinite(placement?.x) ? placement.x : character?.x ?? 0;
 	const y = Number.isFinite(placement?.y) ? placement.y : character?.y ?? 0;
 	const z = Number.isFinite(placement?.z) ? placement.z : character?.z ?? 0;
 	const yaw = ((Number.isFinite(placement?.rot) ? placement.rot : character?.rot ?? 0) + (posture === "lie" ? 180 : 0)) * Math.PI / 180;
 	const [minCorner, maxCorner] = posture === "lie"
-		? [[-PROXY_BODY_RADIUS, PROXY_BODY_RADIUS - PROXY_HEAD_RADIUS, -(bodyHeight + 0.25)],
+		? [[-PROXY_BODY_RADIUS, PROXY_BODY_RADIUS - PROXY_HEAD_RADIUS, -top],
 			[PROXY_BODY_RADIUS, PROXY_BODY_RADIUS + PROXY_HEAD_RADIUS, 0]]
-		: [[-PROXY_BODY_RADIUS, 0, -PROXY_BODY_RADIUS], [PROXY_BODY_RADIUS, bodyHeight + 0.25, PROXY_BODY_RADIUS]];
+		// Sit reaches forward (local +z, the facing direction) with its legs.
+		: [[-PROXY_BODY_RADIUS, 0, -PROXY_BODY_RADIUS], [PROXY_BODY_RADIUS, top, posture === "sit" ? PROXY_SIT_LEG_REACH : PROXY_BODY_RADIUS]];
 	const min = { x: Infinity, y: Infinity, z: Infinity }, max = { x: -Infinity, y: -Infinity, z: -Infinity };
 	for (const lx of [minCorner[0], maxCorner[0]]) for (const ly of [minCorner[1], maxCorner[1]]) for (const lz of [minCorner[2], maxCorner[2]]) {
 		const sx = lx * stature, sy = ly * stature, sz = lz * stature;

package/src/click-friction.js

@@ -8,7 +8,8 @@
 // or element ids. Typing targets and IME composition are ignored outright.
 import { track } from "./analytics.js";
 import { admit, bump } from "./analytics-friction.js";
-import { controlOf } from "./analytics-controls.js";
+import { controlOf, isUnnamedControl } from "./analytics-controls.js";
+import { hintDisabledClick } from "./friction-hint.js";
 
 const RAGE_WINDOW_MS = 1000, RAGE_RADIUS_PX = 24, RAGE_MIN = 3, RAGE_COOLDOWN_MS = 10_000, EFFECT_MS = 500;
 const RAGE_PER_CONTROL = 2, DEAD_PER_CONTROL = 2;
@@ -55,7 +56,7 @@ export function notePointerDown({ target, x, y, event, observe = () => () => {}
 	const element = target?.closest?.(CONTROL);
 	if (!element) return;
 	const fid = element.closest("[data-fid]")?.getAttribute("data-fid");
-	const control = controlOf(fid);
+	const control = controlOf(fid, element);
 	const at = now();
 	// A rage burst: the same control, within 1 s of its first click and 24 px of where it began.
 	if (burst && burst.control === control && burst.element === element && at - burst.at <= RAGE_WINDOW_MS && Math.hypot(x - burst.x, y - burst.y) <= RAGE_RADIUS_PX) {
@@ -66,9 +67,9 @@ export function notePointerDown({ target, x, y, event, observe = () => () => {}
 		burst = { control, element, at, x, y, count: 1, changed: () => lastReceiptAt >= since || lastMutationAt >= since };
 		burstTimer = setTimeout(finishBurst, RAGE_WINDOW_MS);
 	}
-	if (disabledOf(element)) { dead(control, "aria_disabled"); return; }
+	if (disabledOf(element)) { dead(control, "aria_disabled"); hintDisabledClick(element, control); return; }
 	// refused / no_effect: watched only on the closed controls, whose clicks are meant to do something.
-	if (control === "other") return;
+	if (isUnnamedControl(control)) return;
 	const stop = observe(() => { lastMutationAt = now(); });
 	setTimeout(() => {
 		try { stop(); } catch { /* the observer is advisory */ }

package/src/command-bus-telemetry.js

@@ -39,10 +39,8 @@ const EDIT_KINDS = [
 	// The take's fields carry its prompt (motion.take.prompt).
 	[/^motion\.set$/, 'prompt_block_edit'],
 ];
-// Built on first use: this module loads inside an import cycle (analytics.js -> semantic-edit.js ->
-// command-bus.js -> here), where EDIT_GROUPS is not initialized yet.
-let groups = null;
-const groupOf = kind => (groups ??= new Map(Object.entries(EDIT_GROUPS).flatMap(([group, kinds]) => kinds.map(entry => [entry, group])))).get(kind);
+const GROUP_BY_KIND = new Map(Object.entries(EDIT_GROUPS).flatMap(([group, kinds]) => kinds.map(entry => [entry, group])));
+const groupOf = kind => GROUP_BY_KIND.get(kind);
 /** A command's closed edit kind, or null. `hint`: asset.import's closed `placeAs`, and `rail` when a
  * shot.setCamera patch names a rail field (key names only; values are never read). */
 export function firstEditKindOf(action, { placeAs, rail = false } = {}) {
@@ -83,15 +81,18 @@ const emit = (event, props) => {
 	try { send(event, props); } catch { /* telemetry is advisory */ }
 };
 
-/** A refusal receipt: the session counter always moves; the event, at most 3 times per (code, group, origin). */
-export function noteRefusal(value, origin, id) {
+/** A refusal receipt: the session counter always moves; the event, at most 3 times per (code, command, origin).
+ * `registered`: `id` is an action the registry declares, so it may ride along as `command`; an id the caller
+ * made up (an unknown action) is reported by its group alone. */
+export function noteRefusal(value, origin, id, registered = false) {
 	// A cancel the caller asked for is not a refusal. A UI one tells a click it was refused (click-friction.js);
 	// an agent's or MCP client's refusal at the same moment is not the user's click.
 	if (value.code === 'CANCELLED') return;
 	if (origin === 'ui') noteBusReceipt(false);
 	const by = origin === 'ui' ? 'ui' : 'agent', code = refusalCodeOf(value.code), group = commandGroup(id);
 	bump(by === 'ui' ? 'refusals_ui' : 'refusals_agent');
-	if (admit(`studio:refused:${code}:${group}:${by}`, REFUSALS_PER_KEY)) emit('studio:refused', { code, origin: by, phase: value.phase, group });
+	const command = registered ? String(id) : undefined;
+	if (admit(`studio:refused:${code}:${command ?? group}:${by}`, REFUSALS_PER_KEY)) emit('studio:refused', { code, origin: by, phase: value.phase, group, ...(command ? { command } : {}) });
 }
 
 // receiptId -> { at, kind }: when a history receipt was recorded and what it did.

package/src/command-bus.js

@@ -12,8 +12,6 @@ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
 const mapResult = (value, success, failure) => value?.then ? value.then(success, failure) : success(value);
 const toastWarnings = toasts => toasts.slice(-12).map(toast => ({ code: 'STUDIO_TOAST', message: [...toast.message].slice(0, 120).join('') }));
-let activeRunDepth = 0;
-export const isBusRunActive = () => activeRunDepth > 0;
 
 export function createCommandBus({ registry, ports }) {
   const pending = new Map(), transactions = new Map(), jobs = new Map(), listeners = new Set();
@@ -211,7 +209,7 @@ export function createCommandBus({ registry, ports }) {
       catch (error) { if (level >= 2 || error?.code !== 'INVALID_RECEIPT' || !/8 KiB/.test(error.message)) throw error; }
     }
   }
-  function executeRun(id, args = {}, options = {}) {
+  function run(id, args = {}, options = {}) {
     const request = { origin: 'ui', commandId: crypto.randomUUID(), ...options };
     if (request.origin === 'ui' && (id === 'edit.undo' || id === 'edit.redo')) ports.finishHistoryGesture?.();
     const before = ports.read(), journal = ports.journal();
@@ -251,7 +249,7 @@ export function createCommandBus({ registry, ports }) {
       if (request.origin === 'ui' && error.uiMessage) ports.showRefusal?.(error.uiMessage);
       const value = refusal(request, before, error, job ? applied : undefined);
       // Session friction and studio:refused, by who asked and what (command-bus-telemetry.js).
-      noteRefusal(value, request.origin, action ?? id);
+      noteRefusal(value, request.origin, action ?? id, registry.ids?.().includes(action ?? id) === true);
       const recorded = begun ? remember(value) : value;
       if (job && !job.completion) { job.outcome = recorded; job.completion = Promise.resolve(recorded); emit({ type: 'job.completed', jobId: job.id, receipt: recorded }); }
       return recorded;
@@ -368,18 +366,6 @@ export function createCommandBus({ registry, ports }) {
       return answer;
     } catch (error) { return rejected(error); }
   }
-  function run(...args) {
-    activeRunDepth++;
-    try {
-      const value = executeRun(...args);
-      if (value?.then) return value.finally(() => { activeRunDepth--; });
-      activeRunDepth--;
-      return value;
-    } catch (error) {
-      activeRunDepth--;
-      throw error;
-    }
-  }
   // noteUndone: edit:undone for the user's own undo (domains/scene-undo.js), which reaches it through the bus.
   return { run, noteUndone,
     // Trusted UI adapter only: wire callers can consume, never mint a token.

package/src/commands/cast.js

@@ -64,7 +64,8 @@ export function register(registry, ports) {
 			if (owner().read().some(entry => entry.id === row.id)) fail('INVALID_ARGUMENT', 'Character id already exists.');
 			owner().write(rows => [...rows, row]);
 		},
-		'character.remove': ({ characterId }) => { character(characterId); if (owner().read().length <= 1) fail('INVALID_ARGUMENT', 'Cannot remove the final character.'); owner().write(rows => rows.filter(row => row.id !== characterId)); },
+		// An empty stage is legal: a new project starts on one.
+		'character.remove': ({ characterId }) => { character(characterId); owner().write(rows => rows.filter(row => row.id !== characterId)); },
 		'character.update': ({ characterId, patch: value }) => {
 			// Rig <-> capsule figure is a different kind of cast member; rig-to-rig model swaps stay.
 			if (Object.hasOwn(value, 'model') && (value.model === PROXY_FIGURE_MODEL) !== isProxyFigure(character(characterId))) fail('INVALID_ARGUMENT', KIND_FIXED_REFUSAL.en);

package/src/commands/index.js

@@ -17,8 +17,9 @@ import * as exporting from "./export.js";
 import * as ai from "./ai.js";
 import * as stage from "./stage.js";
 import * as kits from "./kits.js";
+import * as physics from "./physics.js";
 
-export const COMMAND_MODULES = Object.freeze({ shot, cast, motion, motion3, objects, kits, view, scene, project, export: exporting, ai, stage });
+export const COMMAND_MODULES = Object.freeze({ shot, cast, motion, motion3, physics, objects, kits, view, scene, project, export: exporting, ai, stage });
 
 export function commandDeclarations(modules = COMMAND_MODULES) {
 	return Object.values(modules).flatMap(module => module.declarations.map(declaration => ({

package/src/commands/motion3.js

@@ -26,6 +26,7 @@ import { normalizeCompileArgs } from "../motion3/lenient.js";
 import { createCompileRunner } from "./motion3-compile.js";
 import { createRepairWatch } from "../motion3/repair-watch.js";
 import { peopleOf } from "../motion3/people.js";
+import { hybridCapsuleHint } from "../motion3/hybrid-hint.js";
 
 const TIMELINE_FPS = 24;
 const id = { type: "string", minLength: 1 };
@@ -181,7 +182,8 @@ export function register(registry, ports) {
 			if (best) timing = put(character, best.take, context) ?? timing;
 			const self = best?.specId === own, how = kept ? "; already installed, unchanged" : self ? "; installed as the best take so far"
 				: best ? `; not installed; the best take so far, ${best.specId}, installed` : install === "ifClean" ? (installs ? "; installed" : "; not installed") : "";
-			const output = report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: Boolean(wanted) || self, ...(stuck ? { stuck } : {}), ...adjustedOf(notes) }, { ...delta, ...(r.repair ? { repair: r.repair } : {}), ...(timing ? { timing } : {}) });
+			const hint = hybridCapsuleHint(ports.storeDomain?.("scenes")?.metadata?.().castStyle, { stuck, qa });
+			const output = report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: Boolean(wanted) || self, ...(stuck ? { stuck } : {}), ...(hint ? { hint } : {}), ...adjustedOf(notes) }, { ...delta, ...(r.repair ? { repair: r.repair } : {}), ...(timing ? { timing } : {}) });
 			// agent-progress.js: viewport ghost, timeline beats, agent panel
 			const draft = publishDraft(characterId, { take, installed: installs || kept || self, specId: output.specId, label: r.label, qa, timeline: r.timeline });
 			noteDraftCompiled(draft, r, { installed: installs || kept || self, stuck, repaired: Boolean(r.repair), adjusted: notes.length > 0 });