cozyclay 3.1.3 → 3.1.5

package/src/analytics-values.js

@@ -0,0 +1,49 @@
+// Closed property values for the export lifecycle and the session-end beacon.
+// Kept out of analytics.js so these vocabularies can grow without growing the
+// core sanitizer; nothing here imports, so analytics.js can depend on it.
+
+export const EXPORT_FAILURE_CODES = new Set(["unsupported_codec", "encode_failed", "render_failed", "aborted", "unknown"]);
+const COUNT_BUCKETS = new Set(["0", "1-3", "4-10", "gte11"]);
+const EXPORT_PROPERTY_VALUES = Object.freeze({
+	export_kind: new Set(["video", "depth_video", "frame", "keyframe_pack", "workflow_send", "animation_project", "contact_sheet", "panel_pack", "animatic", "storyboard", "render_pass", "otio"]),
+	format: new Set(["mp4", "png", "zip", "cclayproject", "otio"]),
+	surface: new Set(["studio", "workflow", "embed"]),
+	duration_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
+	failure_code: EXPORT_FAILURE_CODES,
+	objects: COUNT_BUCKETS,
+	// Where a failed or cancelled export stood: the step and its frame share.
+	stage: new Set(["preparing", "encoding", "finalizing", "handoff"]),
+	progress: new Set(["0", "1-25", "26-50", "51-75", "76-99"]),
+	// export:saved: where the file went, and why it fell back to a download.
+	method: new Set(["workspace", "download"]),
+	reason: new Set(["none", "unsupported", "no_workspace", "permission", "write_failed"]),
+});
+const ATTEMPT_ID_PATTERN = /^[a-f0-9]{32}$/;
+
+/** One export:attempt_* or export:saved property, checked against its closed set. */
+export function exportPropAllowed(key, value) {
+	if (key === "attempt_id" || key === "retry_of") return typeof value === "string" && ATTEMPT_ID_PATTERN.test(value);
+	if (key === "is_retry") return typeof value === "boolean";
+	return EXPORT_PROPERTY_VALUES[key]?.has(value) ?? false;
+}
+
+// The thrown-value type labels app:error and app:render_crash share (analytics.js
+// errorType): built-in Error and DOMException names, else "non_error" or "other".
+export const ERROR_TYPE_VALUES = new Set([
+	"Error", "TypeError", "RangeError", "ReferenceError", "SyntaxError", "EvalError", "URIError",
+	"AggregateError", "AbortError", "TimeoutError", "NotAllowedError", "NotSupportedError", "NotFoundError",
+	"NotReadableError", "InvalidStateError", "QuotaExceededError", "SecurityError", "NetworkError",
+	"DataCloneError", "OperationError", "EncodingError", "UnknownError", "DOMException", "non_error", "other",
+]);
+export const SESSION_DURATION_BUCKETS = new Set(["lt1m", "1-5m", "5-15m", "15-30m", "gte30m"]);
+// The SDK's session id is a random UUID; nothing else may ride in that slot.
+const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SCENES_TOUCHED_MAX = 20;
+
+/** One app:session_ended property: code-made buckets, a capped count, the SDK session id. */
+export function sessionEndedPropAllowed(key, value) {
+	if (key === "duration_bucket") return SESSION_DURATION_BUCKETS.has(value);
+	if (key === "scenes_touched") return Number.isInteger(value) && value >= 0 && value <= SCENES_TOUCHED_MAX;
+	if (key === "session_id") return typeof value === "string" && SESSION_ID_PATTERN.test(value);
+	return key.endsWith("_bucket") && COUNT_BUCKETS.has(value);
+}

package/src/analytics.js

@@ -1,4 +1,7 @@
 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",
@@ -94,10 +97,12 @@ const DEFAULT_ALLOWED_ORIGINS = Object.freeze([
 	"https://cozyclay.org",
 	"https://www.cozyclay.org",
 ]);
+const EXPORT_ATTEMPT_KEYS = ["attempt_id", "export_kind", "format", "surface", "is_retry", "retry_of", "objects"];
 const EVENT_PROPERTIES = Object.freeze({
 	"install:first_launch": ["heard_from"],
 	"app:session_started": [],
-	"app:session_ended": ["duration_bucket", "action_count_bucket", "scenes_touched", ...EDIT_BUCKET_KEYS],
+	"app:session_ended": ["duration_bucket", "action_count_bucket", "scenes_touched", ...EDIT_BUCKET_KEYS, "session_id"],
+	...STRICT_EVENT_KEYS,
 	"app:error": ["error_kind", "error_type", "error_source", "error_file", "error_line", "error_col"],
 	"device:profile": ["gpu_vendor", "gpu_class", "webgl", "cpu_bucket", "memory_bucket", "frame_rate_bucket"],
 	"survey:use_case": ["use_case", "team"],
@@ -116,21 +121,14 @@ const EVENT_PROPERTIES = Object.freeze({
 	"project:opened": ["age_bucket"],
 	"craft:first_action": ["action_kind"],
 	"craft:first_edit": ["edit_kind", "definition_version"],
-	"motion:generate_requested": ["surface", "input_mode", "request_id"],
-	"motion:preflight_blocked": ["reason", "surface", "request_id"],
-	"motion:preflight_passed": ["backend", "surface", "request_id"],
-	"motion:job_started": ["backend", "input_mode", "request_id"],
-	"motion:job_succeeded": ["backend", "duration_bucket", "input_mode", "request_id"],
-	"motion:job_failed": ["backend", "duration_bucket", "input_mode", "error_code", "request_id"],
-	"motion:result_applied": ["request_id", "backend"],
 	"export:blocking_frame_succeeded": ["format"],
 	"export:video_succeeded": ["format"],
 	"export:keyframe_pack": ["entries", "source"],
-	"export:attempt_started": ["attempt_id", "export_kind", "format", "surface"],
-	"export:attempt_succeeded": ["attempt_id", "export_kind", "format", "surface", "duration_bucket"],
-	"export:attempt_failed": ["attempt_id", "export_kind", "format", "surface", "duration_bucket", "failure_code"],
-	"export:attempt_cancelled": ["attempt_id", "export_kind", "format", "surface", "duration_bucket", "failure_code"],
-	"sample:played": ["from"],
+	"export:attempt_started": EXPORT_ATTEMPT_KEYS,
+	"export:attempt_succeeded": [...EXPORT_ATTEMPT_KEYS, "duration_bucket"],
+	"export:attempt_failed": [...EXPORT_ATTEMPT_KEYS, "duration_bucket", "failure_code", "stage", "progress"],
+	"export:attempt_cancelled": [...EXPORT_ATTEMPT_KEYS, "duration_bucket", "failure_code", "stage", "progress"],
+	"export:saved": ["method", "reason"],
 	"playground:opened": [],
 	"playground:first_action": ["action_kind"],
 	"playground:first_edit": ["edit_kind", "definition_version"],
@@ -140,35 +138,15 @@ const EVENT_PROPERTIES = Object.freeze({
 });
 const FEATURE_NAMES = new Set([
 	"pose_edit", "pose_save", "camera_fly", "orbit", "dolly_rail", "crane_graph", "timeline_scrub",
-	"prompt_block_add", "shot_add", "shot_cut", "export_pose", "export_frame", "export_video",
-	"export_depth_video", "export_keyframe_pack",
-	"mcp_connected", "auto_color", "plan_view",
+	"export_frame", "export_video",
+	"export_depth_video", "export_keyframe_pack", "export_render_pass", "export_storyboard",
+	"auto_color",
 ]);
 // `site` and `playground` arrive through `npx cozyclay --via <source>` from the
 // landing page's copy commands; the others are the first-launch prompt answers.
 export const HEARD_FROM_SOURCES = Object.freeze(["x", "hn", "reddit", "github", "friend", "other", "site", "playground"]);
 const HEARD_FROM_VALUES = new Set(HEARD_FROM_SOURCES);
 const DENIED_PROPERTY_KEYS = new Set(["prompt", "text", "url", "path", "file"]);
-const MOTION_ERROR_CODES = new Set(["aborted", "unsupported_route", "generation_failed", "quota", "unknown"]);
-const MOTION_PROPERTY_VALUES = Object.freeze({
-	// `fal` is the Studio's AI video route (H3 Max Turbo through api.cozyclay.org).
-	backend: new Set(["none", "local_kimodo", "hosted", "fal"]),
-	surface: new Set(["timeline", "line_edit", "trail", "mcp", "fal_card", "agent"]),
-	input_mode: new Set(["prompt", "pose", "edit", "a_to_b", "still"]),
-	// `locked`: the AI video route is not enabled for this account yet.
-	// `missing_input`: A/B stills, segmentation or a shared camera are missing.
-	reason: new Set(["unconfigured", "unreachable", "unsupported_route", "locked", "missing_input"]),
-	error_code: MOTION_ERROR_CODES,
-	duration_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
-});
-const EXPORT_FAILURE_CODES = new Set(["unsupported_codec", "encode_failed", "render_failed", "aborted", "unknown"]);
-const EXPORT_PROPERTY_VALUES = Object.freeze({
-	export_kind: new Set(["video", "depth_video", "frame", "keyframe_pack", "workflow_send", "animation_project", "contact_sheet", "panel_pack", "animatic"]),
-	format: new Set(["mp4", "png", "zip", "cclayproject"]),
-	surface: new Set(["studio", "workflow", "embed"]),
-	duration_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
-	failure_code: EXPORT_FAILURE_CODES,
-});
 // Sculpt mode (#739): one sculpt_run per finished run. Numbers only: no
 // reference image, recipe, part name or sculpt id ever rides along.
 export const SCULPT_RUN_OUTCOMES = Object.freeze(["done", "cancelled", "failed"]);
@@ -176,18 +154,13 @@ 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"]),
+	agent: new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "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.
 const ERROR_PROPERTY_VALUES = Object.freeze({
 	error_kind: new Set(["error", "unhandled_rejection"]),
-	error_type: new Set([
-		"Error", "TypeError", "RangeError", "ReferenceError", "SyntaxError", "EvalError", "URIError",
-		"AggregateError", "AbortError", "TimeoutError", "NotAllowedError", "NotSupportedError", "NotFoundError",
-		"NotReadableError", "InvalidStateError", "QuotaExceededError", "SecurityError", "NetworkError",
-		"DataCloneError", "OperationError", "EncodingError", "UnknownError", "DOMException", "non_error", "other",
-	]),
+	error_type: ERROR_TYPE_VALUES,
 	error_source: new Set(["app", "extension", "external", "unknown"]),
 });
 const ERROR_FILE_PATTERN = /^[A-Za-z0-9_.-]{1,80}\.(?:m?js|jsx|ts|tsx)$/;
@@ -227,8 +200,8 @@ let deviceProfileStarted = false;
 // Passive signals describe the session; they are not user actions and never
 // move action_count_bucket.
 const PASSIVE_EVENTS = new Set([
-	"app:session_started", "app:session_ended", "install:first_launch",
-	"app:error", "device:profile",
+	"app:session_started", "app:session_ended", "install:first_launch", ...Object.keys(STRICT_EVENT_KEYS),
+	"app:error", "device:profile", "app:render_crash", "app:gl_lost",
 ]);
 
 function storage() {
@@ -283,16 +256,13 @@ const isSafePropertyValue = (value) => {
 export function sanitizeProps(event, props) {
 	const allowedKeys = EVENT_PROPERTIES[event] ?? [];
 	if (!props || typeof props !== "object" || Array.isArray(props)) return {};
-	const sanitized = {};
+	const sanitized = {}, strict = strictPropValidator(event);
 	for (const key of allowedKeys) {
 		if (DENIED_PROPERTY_KEYS.has(key) || !Object.hasOwn(props, key)) continue;
 		if (event === "feature:used" && (key !== "name" || !FEATURE_NAMES.has(props[key]))) continue;
 		if (event === "install:first_launch" && (key !== "heard_from" || !HEARD_FROM_VALUES.has(props[key]))) continue;
-		if (event.startsWith("export:attempt_")) {
-			if (key === "attempt_id") {
-				if (typeof props[key] !== "string" || !/^[a-f0-9]{32}$/.test(props[key])) continue;
-			} else if (!EXPORT_PROPERTY_VALUES[key]?.has(props[key])) continue;
-		}
+		if ((event.startsWith("export:attempt_") || event === "export:saved") && !exportPropAllowed(key, props[key])) continue;
+		if (strict) { if (strict(key, props[key])) sanitized[key] = props[key]; continue; }
 		if (event === "export:keyframe_pack") {
 			if (key === "source" && props[key] !== "workflow") continue;
 			if (key === "entries" && (!Number.isFinite(props[key]) || props[key] < 0)) continue;
@@ -301,11 +271,6 @@ export function sanitizeProps(event, props) {
 			if (key === "edit_kind" && !FIRST_EDIT_KINDS.includes(props[key])) continue;
 			if (key === "definition_version" && props[key] !== FIRST_EDIT_VERSION) continue;
 		}
-		if (event.startsWith("motion:")) {
-			if (key === "request_id") {
-				if (typeof props[key] !== "string" || !/^[a-f0-9]{32}$/.test(props[key])) continue;
-			} else if (!MOTION_PROPERTY_VALUES[key]?.has(props[key])) continue;
-		}
 		if (event.startsWith("workflow:") || event.startsWith("agent:") || event.startsWith("mcp:")) {
 			if (key === "run_id" || key === "turn_id" || key === "request_id") {
 				if (typeof props[key] !== "string" || !/^[a-f0-9]{32}$/.test(props[key])) continue;
@@ -547,63 +512,6 @@ export function exportFailureCode(error, fallbackCode = "unknown") {
 	return EXPORT_FAILURE_CODES.has(fallbackCode) ? fallbackCode : "unknown";
 }
 
-/**
- * One user-initiated export, ending at pipeline completion/download handoff.
- * Optional { now, capture } dependencies keep fixtures deterministic. Telemetry
- * failures (including unavailable randomness) must not change export behavior.
- */
-export function startExportAttempt(metadata, dependencies = {}) {
-	let terminal = false;
-	let props = null;
-	let startedAt = NaN;
-	let now = () => performance.now();
-	let capture = track;
-	const readClock = () => {
-		try { return now(); } catch { return NaN; }
-	};
-	const emit = (event, payload) => {
-		try {
-			Promise.resolve(capture(event, sanitizeProps(event, payload))).catch(() => {
-				// A rejected transport is as non-fatal as a synchronous failure.
-			});
-		} catch {
-			// Analytics must never affect the export or its error handling.
-		}
-	};
-	try {
-		now = dependencies.now ?? now;
-		capture = dependencies.capture ?? capture;
-		const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
-		const attempt_id = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-		props = { ...sanitizeProps("export:attempt_started", metadata), attempt_id };
-		startedAt = readClock();
-		emit("export:attempt_started", props);
-	} catch {
-		// Without a secure random ID, omit the attempt rather than inventing
-		// a persistent/content-derived identifier or blocking the export.
-		props = null;
-	}
-	const finish = (result, error, fallbackCode) => {
-		if (terminal) return;
-		terminal = true;
-		if (!props) return;
-		try {
-			const payload = { ...props, duration_bucket: bucketMs(readClock() - startedAt) };
-			if (result === "failed") {
-				payload.failure_code = exportFailureCode(error, fallbackCode);
-				if (payload.failure_code === "aborted") result = "cancelled";
-			}
-			emit(`export:attempt_${result}`, payload);
-		} catch {
-			// Clock/payload failures are isolated from the actual export too.
-		}
-	};
-	return {
-		succeed() { finish("succeeded"); },
-		fail(error, fallbackCode = "unknown") { finish("failed", error, fallbackCode); },
-	};
-}
-
 const URL_PROPERTY_KEYS = [
 	"$current_url",
 	"$initial_current_url",
@@ -903,6 +811,7 @@ export async function initAnalytics() {
 			sessionStartedAt = Date.now();
 			installSessionEndListeners(resolved, globalProperties);
 			installErrorListeners();
+			observeLongTasks();
 			void recordDeviceProfile();
 			if (resolved.distribution === "npm") {
 				track("app:session_started");
@@ -919,7 +828,8 @@ export async function initAnalytics() {
 }
 
 export function track(event, props = {}) {
-	if (!initialized || !enabled || !posthog) return;
+	// The allowlist is the gate: an event it does not name is never sent.
+	if (!initialized || !enabled || !posthog || !Object.hasOwn(EVENT_PROPERTIES, event)) return;
 	try {
 		if (getAnalyticsOptOut()) return;
 		const sanitized = sanitizeProps(event, props);
@@ -983,7 +893,7 @@ function installErrorListeners() {
 	errorListenersInstalled = true;
 	const report = (payload) => {
 		try {
-			const props = describeError(payload);
+			const props = describeError(payload); bumpFriction("errors");
 			const signature = [props.error_kind, props.error_type, props.error_source, props.error_file, props.error_line, props.error_col].join("|");
 			if (errorSignaturesSeen.has(signature) || errorSignaturesSeen.size >= ERROR_SIGNATURE_LIMIT) return;
 			errorSignaturesSeen.add(signature);
@@ -1113,25 +1023,19 @@ function installSessionEndListeners(resolved, globalProperties) {
 			// This transport bypasses the SDK, so explicitly apply the same
 			// current opt-out and browser DNT policy before serializing an ID.
 			if (!enabled || !posthog || getAnalyticsOptOut() || posthog.has_opted_out_capturing()) return;
-			const payload = {
-				api_key: resolved.apiKey,
-				event: "app:session_ended",
-				properties: {
-					...globalProperties,
-					distinct_id: posthog.get_distinct_id(),
-					duration_bucket: bucketSessionDuration(Date.now() - sessionStartedAt),
-					action_count_bucket: bucketCount(sessionActionCount),
-					scenes_touched: Math.min(20, sessionScenesTouched),
-					...sessionEditBuckets(),
-				},
-			};
-			const body = JSON.stringify(payload);
 			const endpoint = `${resolved.apiHost.replace(/\/$/, "")}/e/`;
-			if (typeof globalThis.navigator?.sendBeacon === "function") {
-				globalThis.navigator.sendBeacon(endpoint, new Blob([body], { type: "application/json" }));
-			} else {
-				void fetch(endpoint, { method: "POST", body, keepalive: true, headers: { "content-type": "application/json" } });
-			}
+			const identity = { ...globalProperties, distinct_id: posthog.get_distinct_id() };
+			// The same validator as every SDK event, one request per event.
+			const send = (event, props) => {
+				const body = JSON.stringify({ api_key: resolved.apiKey, event, properties: { ...identity, ...sanitizeProps(event, props) } });
+				if (typeof globalThis.navigator?.sendBeacon === "function") globalThis.navigator.sendBeacon(endpoint, new Blob([body], { type: "application/json" }));
+				else void fetch(endpoint, { method: "POST", body, keepalive: true, headers: { "content-type": "application/json" } });
+			};
+			const duration = bucketSessionDuration(Date.now() - sessionStartedAt);
+			// session_id joins the last events of the session.
+			send("app:session_ended", { session_id: posthog.get_session_id?.(), duration_bucket: duration, action_count_bucket: bucketCount(sessionActionCount),
+				scenes_touched: Math.min(20, sessionScenesTouched), ...sessionEditBuckets() });
+			send("app:friction_summary", { active_time: duration, ...frictionSnapshot() });
 		} catch {
 			// Unload telemetry is best effort.
 		}

package/src/asset-pane.jsx

@@ -8,6 +8,7 @@ import { assetKind, formatAssetBytes } from "./asset-shelf.js";
 import { assetRecord } from "./scene-asset-cache.js";
 import ResourceStatus from "./resource-status.jsx";
 import { logStore } from "./shell/log-store.js";
+import { SearchEmpty } from "./search-friction.js";
 import "./asset-pane.css";
 
 /** Casting assets offered in the Content browser's Characters folder. A rig's `id` doubles as
@@ -396,9 +397,7 @@ function catalogueTile(entry, props) {
 	);
 }
 
-function EmptyNote({ children }) {
-	return <p className="content-empty">{children}</p>;
-}
+const EmptyNote = ({ children }) => <p className="content-empty">{children}</p>;
 
 export function FolderGrid({ folder, query, ...props }) {
 	const { imageAssetIds, meshAssetIds, shots = [], takeVersions = [], poses = [], onShotOpen, onTakeOpen, selectedKey, onSelect } = props;
@@ -504,7 +503,7 @@ export function FolderGrid({ folder, query, ...props }) {
 		if (!poses.length) empty = ko("No saved poses yet. Save one from the pose studio.", "저장된 포즈가 아직 없어요. 포즈 스튜디오에서 저장하세요.");
 	}
 	if (empty) return <EmptyNote>{empty}</EmptyNote>;
-	if (query && folder !== "props" && !tiles.length) return <EmptyNote>{ko("Nothing matches this search.", "검색 결과가 없어요.")}</EmptyNote>;
+	if (query && folder !== "props" && !tiles.length) return <SearchEmpty surface="assets" query={query}><EmptyNote>{ko("Nothing matches this search.", "검색 결과가 없어요.")}</EmptyNote></SearchEmpty>;
 	return <div className="content-grid" role="list">{tiles}</div>;
 }
 
@@ -531,7 +530,7 @@ function LogView({ query }) {
 		if (list) list.scrollTop = list.scrollHeight;
 	}, [visible.length, visible[visible.length - 1]?.text]);
 	if (!entries.length) return <EmptyNote>{ko("No events yet this session. Notices, generation jobs and exports appear here.", "이번 세션의 기록이 아직 없어요. 알림, 생성 작업, 내보내기가 여기에 표시됩니다.")}</EmptyNote>;
-	if (!visible.length) return <EmptyNote>{ko("Nothing matches this search.", "검색 결과가 없어요.")}</EmptyNote>;
+	if (!visible.length) return <SearchEmpty surface="assets" query={query}><EmptyNote>{ko("Nothing matches this search.", "검색 결과가 없어요.")}</EmptyNote></SearchEmpty>;
 	return (
 		<ol className="content-log" ref={listRef} data-testid="content-log" aria-live="polite">
 			{visible.map((entry) => (

package/src/click-friction.js

@@ -0,0 +1,101 @@
+// ui:rage_click and ui:dead_click from one capture-phase pointerdown listener the
+// Studio shell installs (StudioShell.jsx). Real pointer input on a natively disabled
+// button still dispatches pointerdown to a document capture listener (Chrome 155,
+// measured; mousedown and click do not), so no control needs the aria-disabled
+// pattern for its dead clicks to be seen.
+//
+// Only a closed control id leaves (analytics-controls.js), never coordinates, text
+// 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";
+
+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;
+const CONTROL = "[data-fid], button, [role='button'], [role='tab'], [role='menuitem'], a[href]";
+
+let send = track, now = () => performance.now();
+let burst = null, burstTimer = null;
+const lastRage = new Map();
+let lastReceiptAt = -Infinity, lastRefusalAt = -Infinity, lastMutationAt = -Infinity;
+
+/** The command bus recorded a receipt for a UI-origin command (command-bus-telemetry.js); `ok: false` is a refusal. */
+export function noteBusReceipt(ok) {
+	const at = now();
+	lastReceiptAt = at;
+	if (!ok) lastRefusalAt = at;
+}
+
+const typing = (target, event) => event?.isComposing || Boolean(target?.closest?.("input, textarea, select, [contenteditable=''], [contenteditable='true']"));
+const disabledOf = (control) => Boolean(control?.closest?.("[aria-disabled='true'], :disabled"));
+const bucketClicks = (n) => (n >= 6 ? "gte6" : n >= 4 ? "4-5" : "3");
+const emit = (event, props) => { try { send(event, props); } catch { /* telemetry is advisory */ } };
+
+function finishBurst() {
+	clearTimeout(burstTimer);
+	const ended = burst;
+	burst = null;
+	if (!ended || ended.count < RAGE_MIN) return;
+	bump("rage_clicks");
+	const at = now(), last = lastRage.get(ended.control) ?? -Infinity;
+	if (at - last < RAGE_COOLDOWN_MS) return;
+	lastRage.set(ended.control, at);
+	if (admit(`ui:rage_click:${ended.control}`, RAGE_PER_CONTROL)) emit("ui:rage_click", { control: ended.control, clicks: bucketClicks(ended.count), changed: ended.changed() });
+}
+
+function dead(control, reason) {
+	bump("dead_clicks");
+	if (admit(`ui:dead_click:${control}`, DEAD_PER_CONTROL)) emit("ui:dead_click", { control, reason });
+}
+
+/** One pointerdown, as the shell's capture listener sees it. `x`, `y` stay local (the rage radius). */
+export function notePointerDown({ target, x, y, event, observe = () => () => {} }) {
+	// A right or middle click runs no control's action: only the primary button (mouse, pen, touch: 0) counts.
+	if ((event?.button ?? 0) !== 0 || typing(target, event)) return;
+	const element = target?.closest?.(CONTROL);
+	if (!element) return;
+	const fid = element.closest("[data-fid]")?.getAttribute("data-fid");
+	const control = controlOf(fid);
+	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) {
+		burst.count += 1;
+	} else {
+		finishBurst();
+		const since = at;
+		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; }
+	// refused / no_effect: watched only on the closed controls, whose clicks are meant to do something.
+	if (control === "other") return;
+	const stop = observe(() => { lastMutationAt = now(); });
+	setTimeout(() => {
+		try { stop(); } catch { /* the observer is advisory */ }
+		if (lastRefusalAt >= at) dead(control, "refused");
+		else if (lastReceiptAt < at && lastMutationAt < at) dead(control, "no_effect");
+	}, EFFECT_MS);
+}
+
+/** The shell's listener: one capture-phase pointerdown on `root`. Returns its removal. */
+export function installClickFriction(root = globalThis.document) {
+	if (!root?.addEventListener) return () => {};
+	const observe = (onChange) => {
+		if (typeof MutationObserver !== "function") return () => {};
+		const observer = new MutationObserver(onChange);
+		observer.observe(root.body ?? root, { subtree: true, childList: true, attributes: true, characterData: true });
+		return () => observer.disconnect();
+	};
+	const listener = (event) => { try { notePointerDown({ target: event.target, x: event.clientX, y: event.clientY, event, observe }); } catch { /* never affect a click */ } };
+	root.addEventListener("pointerdown", listener, true);
+	return () => root.removeEventListener("pointerdown", listener, true);
+}
+
+/** Tests only: capture what is sent and drive the clock; returns the restore. */
+export function clickFrictionSeam({ capture = track, clock = () => performance.now() } = {}) {
+	const previous = [send, now];
+	send = capture; now = clock;
+	const reset = () => { clearTimeout(burstTimer); burst = null; lastRage.clear(); lastReceiptAt = lastRefusalAt = lastMutationAt = -Infinity; };
+	reset();
+	return () => { [send, now] = previous; reset(); };
+}

package/src/command-bus-telemetry.js

@@ -0,0 +1,155 @@
+// The command bus's friction signals: studio:refused (one per refusal, capped per
+// key), the history receipts an undo can name, and edit:undone for the user's own
+// undos (domains/scene-undo.js). Only closed values leave: a refusal code, a
+// command group, an edit kind, an age bucket. Never ids, args or messages.
+import { EDIT_GROUPS, recordSemanticEdit, track } from './analytics.js';
+import { createFirstEditRecorder } from './semantic-edit.js';
+import { admit, bump } from './analytics-friction.js';
+import { bucketAge, refusalCodeOf } from './analytics-strict.js';
+import { noteEditGesture } from './post-turn-edits.js';
+import { noteBusReceipt } from './click-friction.js';
+
+let send = track, clock = () => Date.now();
+const REFUSALS_PER_KEY = 3, UNDOS_PER_SESSION = 20, STAMPS_KEPT = 500;
+
+// Command id prefix to studio:refused group; anything else is "other".
+const GROUPS = [
+	[/^objects?\./, 'object'], [/^shot\./, 'shot'], [/^(characters?|cast)\./, 'cast'], [/^scene\./, 'scene'],
+	[/^(?:motion|ik)\./, 'motion'], [/^edit\./, 'edit'], [/^task\./, 'task'], [/^agent\./, 'agent'],
+];
+export const commandGroup = id => GROUPS.find(([pattern]) => pattern.test(String(id)))?.[1] ?? 'other';
+
+// The one table from a committed command to its closed edit kind (FIRST_EDIT_KINDS,
+// semantic-edit.js); its group (EDIT_GROUPS, analytics.js) follows from the kind.
+// Recording a camera key is camera_key_record; drawing or clearing a rail (or a
+// setCamera patch naming a rail field) is rail_edit; retiming or removing keys and
+// other camera-block changes are shot_edit, as they were in version 1. Capturing the
+// viewing camera into the shot (after an orbit or fly) is navigation, not an edit.
+// Bone and IK keys are pose; placing or adding a character counts as an object, as it
+// does for object_insert. Everything else is no edit kind.
+const EDIT_KINDS = [
+	[/^shot\.captureCamera$/, null],
+	[/^shot\.(create|createStill|duplicate|split)$/, 'shot_add'],
+	[/^shot\.(setCameraRail|clearCameraRail)$/, 'rail_edit'],
+	[/^shot\.addKey$/, 'camera_key_record'],
+	[/^shot\./, 'shot_edit'],
+	[/^(character\.(setPose|setIkKey|removeIkKey|clearIkKeys)|ik\.|motion\.rangePin\.)/, 'pose_edit'],
+	[/^(object\.(add|duplicate|sculpt|createKit)|character\.add)$/, 'object_insert'],
+	[/^(objects?\.|character\.(set|remove|update|move)$|characters\.arrange$|cast\.replace$)/, 'object_transform'],
+	// 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);
+/** 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 } = {}) {
+	if (action === 'asset.import') return placeAs === 'cutout' ? 'cutout_insert' : 'object_insert';
+	if (action === 'shot.setCamera' && rail) return 'rail_edit';
+	return EDIT_KINDS.find(([pattern]) => pattern.test(String(action)))?.[1] ?? null;
+}
+// The camera block's rail fields (semantic-edit.js rail_edit): a setCamera patch naming one edits the rail.
+const RAIL_FIELDS = ['cameraRail', 'craneHeight', 'railFollow', 'dollyTiming'];
+const railPatch = args => Object.keys(args?.patch ?? {}).some(key => RAIL_FIELDS.includes(key));
+// A drag's begin/update patches, remembered by txId until its commit names the edit.
+const railTransactions = new Set();
+function hintOf(id, args, recorded) {
+	if (id === 'run.begin' || id === 'run.update') {
+		if (recorded.txId && railPatch(args?.args)) railTransactions.add(recorded.txId);
+		while (railTransactions.size > 50) railTransactions.delete(railTransactions.values().next().value);
+		return {};
+	}
+	return { placeAs: args?.placeAs, rail: id === 'run.commit' ? railTransactions.delete(recorded.txId) : railPatch(args) };
+}
+const AGENT_WORK = new Set(['agent.turn.finish', 'task.finish']);
+/** The edit:undone / post-turn group of a command: pose, camera, object, shot, prompt, agent_turn or other. */
+export function editKind(action, origin = 'ui', hint) {
+	// What the agent made (its turn, a task, or an edit it ran on its own) is undone as agent work.
+	if (AGENT_WORK.has(action) || origin !== 'ui') return 'agent_turn';
+	return groupOf(firstEditKindOf(action, hint)) ?? 'other';
+}
+
+// The user's own edits feed the session edit buckets and the surface's first edit
+// (definition_version 2). App starts a new mount boundary with startUserEdits.
+let editSurface = 'craft', firstEdit = createFirstEditRecorder((event, props) => send(event, props));
+export function startUserEdits(surface) {
+	editSurface = surface;
+	firstEdit = createFirstEditRecorder((event, props) => send(event, props));
+}
+
+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 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 });
+}
+
+// receiptId -> { at, kind }: when a history receipt was recorded and what it did.
+const stamps = new Map();
+
+/**
+ * The bus's history receipts by history entry id (what edit.undo restores), each
+ * stamped when it was recorded. Gesture rule: a drag is one transaction whose
+ * receipt is recorded at run.commit, and any later receipt naming the same entry
+ * replaces the earlier one, so an entry's age runs from its LAST receipt: the
+ * time since the user finished that edit, not since they started it.
+ */
+export function createHistoryReceipts(ports) {
+	const receipts = new Map();
+	return {
+		get: historyEntryId => receipts.get(historyEntryId),
+		/** `id` the command, `action` the command a transaction ran (run.commit of a drag). */
+		remember(recorded, { id, origin, action, args }) {
+			const hint = hintOf(id, args, recorded);
+			if (origin === 'ui' && recorded.ok !== false) noteBusReceipt(true);
+			// Session friction: an undo the user made (agent undos are the agent's own correction).
+			if (id === 'edit.undo' && origin === 'ui' && recorded.status === 'undone') bump('undos');
+			// The user's edit that changed the scene, once per receipt (a drag commits once): the session edit
+			// buckets, the first edit and agent:post_turn_edit. Agent, MCP and undo/redo receipts never count.
+			if (origin === 'ui' && recorded.authored === true && !id.startsWith('edit.')) noteUserEdit(firstEditKindOf(action ?? id, hint));
+			if (recorded.undo?.canUndoDirect && !id.startsWith('edit.')) {
+				receipts.set(recorded.undo.historyEntryId, recorded);
+				stamps.set(recorded.receiptId, { at: clock(), kind: editKind(action ?? id, origin, hint) });
+				while (stamps.size > STAMPS_KEPT) stamps.delete(stamps.keys().next().value);
+			}
+			for (const [key, receipt] of receipts) if (ports.isRetained?.(receipt) === false) { receipts.delete(key); stamps.delete(receipt.receiptId); }
+		},
+	};
+}
+
+let userEditAt = -Infinity;
+/** When the user's own last edit receipt was recorded (bus clock), or -Infinity: the thrash detectors' "no edit in between". */
+export const lastUserEditAt = () => userEditAt;
+function noteUserEdit(kind) {
+	if (!kind) return;
+	userEditAt = clock();
+	try { recordSemanticEdit(kind); firstEdit(editSurface, kind); } catch { /* telemetry is advisory */ }
+	noteEditGesture(groupOf(kind));
+}
+
+const RESULTS = { undone: 'done', noop: 'noop' };
+/** The user's undo (`via` key, menu or button): its receipt, or null for an IK drag preview backed out. */
+export function noteUndone(via, receipt) {
+	const result = !receipt ? 'done' : receipt.ok === false ? 'refused' : RESULTS[receipt.status];
+	if (!result || !admit('edit:undone', UNDOS_PER_SESSION)) return;
+	// A native history entry no receipt names (or nothing undone at all) is "other", with no age.
+	const stamp = result === 'done' && receipt ? stamps.get(receipt.undoneReceiptId) : null;
+	emit('edit:undone', { kind: receipt ? stamp?.kind ?? 'other' : 'ik_preview', via, result, ...(stamp ? { age: bucketAge(clock() - stamp.at) } : {}) });
+}
+
+/** Tests only: capture what is sent and drive the clock; returns the restore. */
+export function telemetrySeam({ track: capture = track, now = () => Date.now() } = {}) {
+	const previous = [send, clock];
+	send = capture; clock = now;
+	return () => { [send, clock] = previous; stamps.clear(); };
+}