cozyclay 3.1.3 → 3.1.5

package/src/App.jsx

@@ -30,7 +30,9 @@ import { applyTakeFrame } from "./motion3/playback.js";
 
 import { FlyControls, aimAt, forwardFrom } from "./controls.jsx";
 import { createLiveControl, loadLiveWorkspaceId, mintLiveWorkspaceId } from "./live-control.js";
-import { createFirstEditTracker, semanticEditKind } from "./semantic-edit.js";
+import { startUserEdits } from "./command-bus-telemetry.js";
+import { noteHistoryKey, noteShortcutIgnored, noteUnselectedKey } from "./shortcut-friction.js";
+import { noteNavSwitch } from "./thrash-friction.js";
 
 import AgentPanel from "./workflow/AgentPanel.jsx";
 import SculptPanel from "./panels/SculptPanel.jsx";
@@ -118,6 +120,7 @@ import {
 } from "./project.js";
 import ProjectBrowser, { ProjectNameDialog } from "./project-browser.jsx";
 import FirstSuccessGuide from "./first-success-guide.jsx";
+import { noteDeleteUndone, notePanelToggled } from "./studio-telemetry.js";
 import UseCaseQuestion from "./use-case-question.jsx";
 import ObjectGizmo from "./object-gizmo.jsx";
 import { useHeldObjectEdit } from "./held-object-edit.jsx";
@@ -140,19 +143,17 @@ import {
 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 { routeOwnerFor } from "./route-owner.js";
 import {
-	analyticsActive,
 	exportFailureCode,
-	recordSemanticEdit,
 	recordUseCase,
 	sculptRunTelemetry,
 	shouldAskUseCase,
-	startExportAttempt,
 	track,
 	trackActivation,
 	trackFeature,
 } from "./analytics.js";
 import { ko, isKo, isZh } from "./locale.js";
 import { saveExport } from "./export-workspace.js";
+import { startExportAttempt } from "./export-attempt.js";
 import { characterCapabilities, kindRefusal, proxyFigureBounds } from "./character-kind.js";
 import { STARTER_SCENES, resolveSceneParam } from "./starter-scenes.js";
 import { PART_COLOURS } from "./part-colours.js";
@@ -181,6 +182,7 @@ import {
 	Toast,
 } from "./ui.jsx";
 import { useRenderActivity } from "./use-render-activity.js";
+import { useWebGlAvailable } from "./use-webgl-available.js";
 
 import {
 	CUSTOM_MOVE,
@@ -442,33 +444,20 @@ export default function App() {
 	if (typeof window !== "undefined") window.__cozyclayRenders = (window.__cozyclayRenders || 0) + 1;
 	const sceneRevisionRef = useRef(0);
 	const studioBindingRef = useRef(null);
-	const firstEditRef = useRef(null);
-	if (!firstEditRef.current) {
-		const firstEdit = createFirstEditTracker(track);
-		// Observe the existing semantic boundary once, even after its telemetry
-		// gate is satisfied. The semantic hook itself stays unchanged.
-		firstEditRef.current = (surface, domain, before, after) => {
+	const semanticEditRef = useRef(null);
+	if (!semanticEditRef.current) {
+		// A new mount boundary for the first edit. User edits are counted from the
+		// command bus's own receipts (command-bus-telemetry.js), not from here.
+		startUserEdits(playgroundMode ? "playground" : "craft");
+		semanticEditRef.current = (domain, before, after) => {
 			if (before !== after) sceneRevisionRef.current += 1;
 			studioBindingRef.current?.invalidate(domain, before, after);
 			studioBindingRef.current?.publishSemantic(domain, after);
-			// Every authored edit is counted by its closed kind for the session
-			// summary (#466); classification only runs while telemetry is on.
-			if (before !== after && analyticsActive()) {
-				try {
-					const kind = semanticEditKind(domain, before, after);
-					if (kind) recordSemanticEdit(kind);
-				} catch {
-					// Telemetry classification must never affect editing.
-				}
-			}
-			return firstEdit(surface, domain, before, after);
 		};
 	}
 	// One semantic hook for authored UI and programmatic mutations. Passive
 	// setters intentionally bypass it (navigation, load, seed, restore, history).
-	const markSemanticEdit = (domain, before, after) => {
-		return firstEditRef.current(playgroundMode ? "playground" : "craft", domain, before, after);
-	};
+	const markSemanticEdit = (domain, before, after) => semanticEditRef.current(domain, before, after);
 	const craftActionTrackedRef = useRef(false);
 	const markCraftAction = (actionKind) => {
 		if (craftActionTrackedRef.current) return;
@@ -1148,29 +1137,29 @@ export default function App() {
 	// the "load a character" one, which would read as a loading problem.
 	const activeCapabilities = characterCapabilities(activeChar);
 	const poseRefusal = !activeCapabilities.pose ? kindRefusal("pose", isKo, isZh) : ikChains ? null : ko("Load a character to pose it — Pose mode edits its rig with IK", "캐릭터를 불러와야 포즈를 잡을 수 있어요 — 포즈 모드는 IK로 리그를 편집합니다", "加载角色后才能摆姿势 — 姿势模式用 IK 编辑其骨骼");
+	// False when the mode refuses (its reason shows as a toast): the 1-5 keys report that as shortcut:ignored.
 	function selectWorkflowMode(next) {
 		if (next === "pose" && poseRefusal) {
 			setToast(poseRefusal);
-			return;
+			return false;
 		}
 		// A storyboard is stills: there is no Motion department to open.
 		if (next === "motion" && storyboardProject) {
 			setToast(ko(STORYBOARD_MOTION_REFUSAL.en, STORYBOARD_MOTION_REFUSAL.ko, STORYBOARD_MOTION_REFUSAL.zh));
-			return;
+			return false;
 		}
 		setWorkflowMode(next);
+		// A user's switch (tab, key, a shot or camera pick) toward nav:thrash; the agent's view.setMode does not come here.
+		if (next !== workflowMode) noteNavSwitch("mode");
 		// Picking a department leaves the chrome-free player. Shot-look is
 		// camera work, so it only yields when the operator leaves Camera.
 		if (preview) exitPreview();
 		else if (lookThroughShot && next !== "camera") exitPreview();
 		if (next === "camera") setSelectedHierarchyId("camera");
-		else if (next === "motion") {
-			// The active character's ROW, not the group: the placement gizmo only
-			// renders for a specific cast member, so selecting the group used to
-			// drop the operator into Motion with nothing to drag.
-			setSelectedHierarchyId(rowIdForCharIndex(activeCharIndex));
-			
-		}
+		// The active character's ROW, not the group: the placement gizmo only
+		// renders for a specific cast member, so selecting the group used to
+		// drop the operator into Motion with nothing to drag.
+		else if (next === "motion") setSelectedHierarchyId(rowIdForCharIndex(activeCharIndex));
 		// Pose lands on the active character's rig: its Rig Control panel holds
 		// the IK tools that W/E/R switch between.
 		else if (next === "pose") setSelectedHierarchyId(`${rowIdForCharIndex(activeCharIndex)}.rig`);
@@ -1605,7 +1594,7 @@ export default function App() {
 			setToast(ko("A newer edit comes after this deletion. Use Undo history instead.", "삭제 이후의 편집이 있어요. 실행 취소 기록을 사용해 주세요."));
 			return;
 		}
-		undoScene();
+		undoScene("button");
 	}
 
 	useEffect(() => {
@@ -1626,8 +1615,8 @@ export default function App() {
 			// selected, and mid-drag the store's settle commits then steps.
 			if (event.code === "KeyZ" && (event.ctrlKey || event.metaKey)) {
 				event.preventDefault();
-				if (event.shiftKey) redoScene();
-				else undoScene();
+				// Nothing to undo or redo, or a refused undo, is shortcut:ignored: the bus receipt says which.
+				if (event.shiftKey) noteHistoryKey("redo", redoScene()); else noteHistoryKey("undo", undoScene("key"));
 				return;
 			}
 			// 1-4 pick the workflow mode; pose is refused (with its reason) when
@@ -1637,7 +1626,7 @@ export default function App() {
 				// A storyboard has no key 4: it does nothing, not even a refusal.
 				if (modeKey === "motion" && storyboardProject) return;
 				event.preventDefault();
-				if (modeKey !== workflowMode) selectWorkflowMode(modeKey);
+				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.
@@ -1650,9 +1639,9 @@ export default function App() {
 			// buttons: the range pin needs a take.
 			if (workflowMode === "pose" && GIZMO_HOTKEYS[event.code]) {
 				event.preventDefault();
+				// E has no IK tool: a pose-mode E does nothing (shortcut:ignored).
 				if (event.code === "KeyW") setIkEditTool("ik");
-				
-				else if (event.code === "KeyR" && motion) { setIkEditTool("pin"); setRangePinPartPick(null); }
+				else if (event.code === "KeyR" && motion) { setIkEditTool("pin"); setRangePinPartPick(null); } else if (event.code === "KeyE") noteShortcutIgnored("transform", "wrong_mode");
 				return;
 			}
 			if (GIZMO_HOTKEYS[event.code]) {
@@ -1703,7 +1692,8 @@ export default function App() {
 				dropSelectedSceneObject();
 				return;
 			}
-			if (!selectedSceneObjectId) return;
+			// F, Ctrl/Cmd+D and Delete with nothing to act on reach here: shortcut:ignored, no_selection.
+			if (!selectedSceneObjectId) return noteUnselectedKey(event);
 			if (event.key !== "Delete" && event.key !== "Backspace") return;
 			// A selected path point owns Delete: the route's handles are the
 			// finer target, and deleting the whole prop out from under a point
@@ -1809,6 +1799,7 @@ export default function App() {
 		return () => window.removeEventListener(PWA_UPDATE_EVENT, onUpdate);
 	}, []);
 	const [glContextLost, setGlContextLost] = useState(false);
+	const webGlAvailable = useWebGlAvailable();
 
 
 
@@ -2245,14 +2236,14 @@ export default function App() {
 		try { const value = studioBindingRef.current.context(); setStudioAgentError(null); return value; }
 		catch (error) { setStudioAgentError(`${error.code ?? "INVALID_CONTEXT"}: ${error.message}`); return null; }
 	};
+	const agentCollapsedRef = useRef(agentCollapsed);
+	useEffect(() => { agentCollapsedRef.current = agentCollapsed; }, [agentCollapsed]);
 	useEffect(() => {
 		if (embedMode) return;
-		const toggle = () => setAgentCollapsed(value => !value);
-		const key = event => {
-			if ((event.metaKey || event.ctrlKey) && event.code === "KeyB") { event.preventDefault(); toggle(); }
-		};
-		window.addEventListener("cozyclay:agent-panel-toggle", toggle);
-		window.addEventListener("keydown", key);
+		// The toolbar control and Workflow's button dispatch the event; Cmd/Ctrl+B calls toggle with the keydown.
+		const toggle = (event) => { notePanelToggled(agentCollapsedRef.current, event?.type === "keydown" ? "key" : "button"); noteNavSwitch("agent_panel"); setAgentCollapsed(value => !value); };
+		const key = event => { if ((event.metaKey || event.ctrlKey) && event.code === "KeyB") { event.preventDefault(); toggle(event); } };
+		window.addEventListener("cozyclay:agent-panel-toggle", toggle); window.addEventListener("keydown", key);
 		return () => { window.removeEventListener("cozyclay:agent-panel-toggle", toggle); window.removeEventListener("keydown", key); };
 	}, [embedMode]);
 	const projectHandleRef = useRef(null);
@@ -2783,7 +2774,7 @@ export default function App() {
 
 	function updateExportStatus(job, phase, details = {}) {
 		if (recRef.current !== job) return;
-		job.cancellable = details.cancellable ?? false;
+		job.cancellable = details.cancellable ?? false; if (!job.controller.signal.aborted) job.attempt?.note(phase, details);
 		setExportStatus({ kind: job.request.kind, phase, label: job.label, ...details });
 	}
 
@@ -2805,11 +2796,10 @@ export default function App() {
 			if (request.external) throw new Error(ko("An export is already running", "이미 내보내기 중입니다"));
 			return null;
 		}
-		const job = { request, controller: new AbortController(), capture: null, cancellable: false };
+		const job = { request, controller: new AbortController(), capture: null, cancellable: false, attempt: request.external ? null : startExportAttempt({ export_kind: request.kind, format: request.format, surface: embedMode ? "embed" : "studio", objects: sceneObjects.length, request }) };
 		recRef.current = job;
 		retryExportRef.current = request;
 		setRecState("recording");
-		const attempt = request.external ? null : startExportAttempt({ export_kind: request.kind, format: request.format, surface: embedMode ? "embed" : "studio" });
 		updateExportStatus(job, "preparing", { cancellable: request.kind !== "frame" });
 		try {
 			await exportBoundary(job);
@@ -2819,7 +2809,7 @@ export default function App() {
 			}
 			const output = await request.run(job);
 			job.controller.signal.throwIfAborted();
-			attempt?.succeed();
+			job.attempt?.succeed();
 			updateExportStatus(job, "completed", { message: request.download
 				? ko("Export completed. Check your export folder or browser downloads; the OS save is not confirmed.", "내보내기를 완료했어요. 내보내기 폴더나 브라우저 다운로드를 확인하세요. OS 저장 완료는 확인할 수 없어요.")
 				: ko("Export pipeline completed. The requesting tool handles the file handoff.", "내보내기 처리를 완료했어요. 요청한 도구에서 파일 전달을 처리합니다.") });
@@ -2842,7 +2832,7 @@ export default function App() {
 			return output;
 		} catch (error) {
 			const code = exportFailureCode(error, request.kind === "depth_video" ? "render_failed" : "unknown");
-			attempt?.fail(error, code);
+			job.attempt?.fail(error, code, request.handedOff.size);
 			const message = exportRecovery(code);
 			updateExportStatus(job, code === "aborted" ? "cancelled" : "failed", {
 				code, message, retryable: !request.external, handedOff: request.handedOff.size,
@@ -3097,6 +3087,7 @@ export default function App() {
 			setToast(ko("Add at least one Shot before exporting OTIO", "OTIO를 내보내려면 샷을 하나 이상 추가하세요"));
 			return;
 		}
+		const attempt = startExportAttempt({ export_kind: "otio", format: "otio", surface: embedMode ? "embed" : "studio", objects: sceneObjects.length });
 		try {
 			const activeScene = scenes.find((scene) => scene.id === activeSceneId);
 			const exportScene = {
@@ -3111,17 +3102,14 @@ export default function App() {
 			};
 			const serialized = serializeOtio(exportScene, shots);
 			const blob = new Blob([serialized], { type: "application/json" });
-			const slug = (activeScene?.name ?? "cut-list")
-				.toLowerCase()
-				.replace(/[^a-z0-9]+/g, "-")
-				.replace(/^-+|-+$/g, "") || "cut-list";
-			await saveExport(blob, `cozyclay-${slug}.otio`);
+			const slug = (activeScene?.name ?? "cut-list").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "cut-list";
+			await saveExport(blob, `cozyclay-${slug}.otio`); attempt.succeed();
 			const frameCount = shots.reduce((total, shot) => total + shot.endFrame - shot.startFrame + 1, 0);
 			setToast(ko(`OTIO saved · ${shots.length} shots · ${frameCount} frames`,
 				`OTIO 저장됨 · ${shots.length}샷 · ${frameCount}프레임`,
 				`OTIO 已保存 · ${shots.length} 个镜头 · ${frameCount} 帧`));
 		} catch (error) {
-			setToast(error?.message || String(error));
+			attempt.fail(error); setToast(error?.message || String(error));
 		}
 	}
 
@@ -3273,13 +3261,15 @@ export default function App() {
 
 	/** Depth and normal conditioning passes of the framing on screen now. */
 	async function exportRenderPasses() {
+		const attempt = startExportAttempt({ export_kind: "render_pass", format: "png", surface: embedMode ? "embed" : "studio", objects: sceneObjects.length });
+		let handedOff = 0;
 		try {
 			const dataUrls = renderPassDataUrls();
-			for (const kind of ["depth", "normal"]) await saveExport(dataUrls[kind], passFileName(kind));
+			for (const kind of ["depth", "normal"]) { await saveExport(dataUrls[kind], passFileName(kind)); handedOff += 1; }
 			setToast(ko("Depth and normal passes exported", "뎁스·노멀 패스를 내보냈어요"));
-			trackFeature("export_render_pass");
+			attempt.succeed(); trackFeature("export_render_pass");
 		} catch (error) {
-			setToast(error?.message || String(error));
+			attempt.fail(error, "render_failed", handedOff); setToast(error?.message || String(error));
 		}
 	}
 
@@ -3308,6 +3298,7 @@ export default function App() {
 
 	/** Contact sheet of the whole cut: one thumbnail and prompt per shot. */
 	async function exportStoryboard() {
+		const attempt = startExportAttempt({ export_kind: "storyboard", format: "png", surface: embedMode ? "embed" : "studio", objects: sceneObjects.length });
 		try {
 			if (!shots.length) throw new Error(ko("Add at least one Shot before exporting a storyboard", "스토리보드를 내보내려면 샷을 하나 이상 추가하세요"));
 			setToast(ko("Composing the storyboard…", "스토리보드 구성 중…"));
@@ -3337,9 +3328,9 @@ export default function App() {
 			});
 			await saveExport(canvas.toDataURL("image/png"), "cozyclay-storyboard.png");
 			setToast(ko(`Storyboard saved · ${cells.length} shots`, `스토리보드 저장됨 · ${cells.length}샷`, `故事板已保存 · ${cells.length} 个镜头`));
-			trackFeature("export_storyboard");
+			attempt.succeed(); trackFeature("export_storyboard");
 		} catch (error) {
-			setToast(error?.message || String(error));
+			attempt.fail(error); setToast(error?.message || String(error));
 		}
 	}
 
@@ -3625,7 +3616,9 @@ export default function App() {
 	// nothing to apply — pure FK posing / pure motion playback stays
 	// untouched.
 	useEffect(() => {
-		if (!ikChains || !activeRig || posing) return;
+		// On a selection switch this runs once before the resolve effect's
+		// setIkChains lands: the chains still pose the previous character.
+		if (!ikChains || !activeRig || posing || ikChains.values().next().value?.rig !== activeRig) return;
 		// Preview changes may re-run this effect without a playhead change.
 		// Always re-establish the motion base before adding a correction.
 		if (motion) poseMemberAtFrame(activeRig, motion, null, tlFrame);
@@ -3645,7 +3638,7 @@ export default function App() {
 	useEffect(() => {
 		const frameChanged = ikPrevFrameRef.current !== tlFrame;
 		ikPrevFrameRef.current = tlFrame;
-		if (!ikMode || !ikChains || !activeRig || posing) return;
+		if (!ikMode || !ikChains || !activeRig || posing || ikChains.values().next().value?.rig !== activeRig) return;
 		if (!frameChanged) return; // pure toggle-on: evaluate already ran
 		ikSeedTargets(ikChains, ikStateRef.current);
 	}, [ikMode, ikChains, activeRig, motion, posing, tlFrame, ikTick, ikFkJoints]);
@@ -4271,7 +4264,7 @@ export default function App() {
 		const restored = storeRef.current.objects;
 		if (before !== restored) {
 			if (!redo && objectDeleteUndo?.id && restored.some(object => object.id === objectDeleteUndo.id)) {
-				setSelectedHierarchyId(`object:${objectDeleteUndo.id}`); setObjectDeleteUndo(null);
+				setSelectedHierarchyId(`object:${objectDeleteUndo.id}`); setObjectDeleteUndo(null); noteDeleteUndone(objectDeleteUndo.id);
 			} else if (selectedSceneObjectId && !restored.some(object => object.id === selectedSceneObjectId)) setSelectedHierarchyId("props");
 		}
 		setToast(redo ? ko("Redone", "다시 실행됨") : ko("Undone", "실행 취소됨"));
@@ -5121,11 +5114,7 @@ export default function App() {
 						    — orbit, pan, click-to-select — reaches the WebGL canvas
 						    untouched while the mode is on. */}
 
-						{!(globalThis.__cozyclayWebGLAvailable ??= (() => {
-							if (typeof document === "undefined") return true;
-							const canvas = document.createElement("canvas");
-							return Boolean(canvas.getContext("webgl") || canvas.getContext("experimental-webgl"));
-						})()) && (
+						{!webGlAvailable && (
 							<div className="gl-lost-overlay" role="alert" data-testid="webgl-unavailable">
 								<div className="gl-lost-card">
 									<strong>{ko("3D graphics (WebGL) is turned off in this browser", "이 브라우저에서 3D 그래픽(WebGL)이 꺼져 있어요")}</strong>

package/src/analytics-controls.js

@@ -0,0 +1,17 @@
+// 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".
+// 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",
+	"mode_scene", "mode_pose", "mode_camera", "mode_motion", "mode_sculpt",
+	"tool_move", "tool_rotate", "tool_scale", "tool_ik", "tool_pin", "tool_front", "tool_side", "tool_back",
+	"tl_play", "shot_add", "shot_delete", "camera_key_add",
+	"export_animation_project", "export_keyframe_pack", "export_video", "export_video_shot",
+	"export_render_passes", "export_depth_video", "export_storyboard", "export_otio",
+	"menu_undo", "menu_redo",
+	"agent_send", "agent_stop", "agent_steer", "agent_retry", "agent_connect", "agent_panel",
+	"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");

package/src/analytics-friction.js

@@ -0,0 +1,124 @@
+// Session friction counters for app:friction_summary, sent once at session end.
+// Detectors bump a counter on every occurrence; a detector that also has its
+// own event asks admit() first, so past its per-session cap only the counter
+// here moves. Counts leave only as closed buckets. Nothing here reads input
+// elements or text: callers pass counts and durations, never content.
+import { SESSION_DURATION_BUCKETS } from "./analytics-values.js";
+
+// Counter sources: refusals_ui/refusals_agent and undos (command bus), errors
+// (app:error listener, ErrorBoundary), long_tasks (longtask observer), compiles
+// (every motion.compile draft, motion-draft-telemetry.js), rage_clicks/dead_clicks
+// (click-friction.js), shortcut_ignored (shortcut-friction.js), search_empty
+// (search-friction.js), nav_thrash/camera_thrash (thrash-friction.js).
+const COUNTERS = Object.freeze([
+	"refusals_ui", "refusals_agent", "undos", "errors", "rage_clicks", "dead_clicks",
+	"shortcut_ignored", "search_empty", "nav_thrash", "camera_thrash", "long_tasks", "compiles",
+]);
+export const FRICTION_SUMMARY_KEYS = Object.freeze(["active_time", ...COUNTERS, "long_task_max", "late_tick_ratio"]);
+const COUNT_BUCKETS = new Set(["0", "1", "2", "3", "4-5", "6-10", "gte11"]);
+const LONG_TASK_BUCKETS = new Set(["lt50", "50-150", "150-500", "500-2000", "gte2000"]);
+const LATE_TICK_BUCKETS = new Set(["0", "lt5", "5-20", "20-50", "gte50"]);
+
+const counts = new Map(COUNTERS.map((name) => [name, 0]));
+const admitted = new Map();
+let longTaskMax = 0;
+let lateTicks = 0;
+let totalTicks = 0;
+let observing = false;
+
+/** 0, 1, 2, 3, 4-5, 6-10, gte11: small counts stay distinguishable. */
+export function bucketFrictionCount(value) {
+	const count = Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+	if (count <= 3) return String(count);
+	if (count <= 5) return "4-5";
+	if (count <= 10) return "6-10";
+	return "gte11";
+}
+
+/** lt50, 50-150, 150-500, 500-2000, gte2000 ms: long tasks and compile times. */
+export function bucketShortMs(ms) {
+	if (!(ms >= 50)) return "lt50";
+	if (ms < 150) return "50-150";
+	if (ms < 500) return "150-500";
+	if (ms < 2000) return "500-2000";
+	return "gte2000";
+}
+
+/** Share of playback ticks that ran late, as a closed percent bucket. */
+export function bucketLateTicks(late, total) {
+	if (!(total > 0) || !(late > 0)) return "0";
+	const percent = (late / total) * 100;
+	if (percent < 5) return "lt5";
+	if (percent < 20) return "5-20";
+	if (percent < 50) return "20-50";
+	return "gte50";
+}
+
+/** Count n occurrences of a known counter. Unknown names are ignored. */
+export function bump(name, n = 1) {
+	if (!counts.has(name) || !Number.isFinite(n) || n < 1) return false;
+	counts.set(name, counts.get(name) + Math.floor(n));
+	return true;
+}
+
+/** True while `event` has been admitted fewer than `cap` times this session. */
+export function admit(event, cap) {
+	const seen = admitted.get(event) ?? 0;
+	if (!(seen < cap)) return false;
+	admitted.set(event, seen + 1);
+	return true;
+}
+
+export function noteLongTask(ms) {
+	if (!Number.isFinite(ms) || ms < 0) return;
+	bump("long_tasks");
+	longTaskMax = Math.max(longTaskMax, ms);
+}
+
+/** One playback run's ticks: how many ran late out of how many. */
+export function noteTick(late, total) {
+	if (!Number.isInteger(late) || !Number.isInteger(total) || late < 0 || total < late) return;
+	lateTicks += late;
+	totalTicks += total;
+}
+
+/** Feed long tasks into the counters where the browser reports them; a no-op elsewhere. */
+export function observeLongTasks(Observer = globalThis.PerformanceObserver) {
+	if (observing) return true;
+	try {
+		if (typeof Observer !== "function" || !Observer.supportedEntryTypes?.includes("longtask")) return false;
+		new Observer((list) => {
+			for (const entry of list.getEntries()) noteLongTask(entry.duration);
+		}).observe({ type: "longtask" });
+		observing = true;
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** The session's counters as closed buckets, without active_time. */
+export function snapshot() {
+	return {
+		...Object.fromEntries([...counts].map(([name, count]) => [name, bucketFrictionCount(count)])),
+		long_task_max: bucketShortMs(longTaskMax),
+		late_tick_ratio: bucketLateTicks(lateTicks, totalTicks),
+	};
+}
+
+/** One app:friction_summary property, checked against its closed set. */
+export function frictionPropAllowed(key, value) {
+	if (key === "active_time") return SESSION_DURATION_BUCKETS.has(value);
+	if (key === "long_task_max") return LONG_TASK_BUCKETS.has(value);
+	if (key === "late_tick_ratio") return LATE_TICK_BUCKETS.has(value);
+	return counts.has(key) && COUNT_BUCKETS.has(value);
+}
+
+/** Tests only: a fresh session. The long-task observer stays installed. */
+export function reset() {
+	for (const name of counts.keys()) counts.set(name, 0);
+	admitted.clear();
+	longTaskMax = 0;
+	lateTicks = 0;
+	totalTicks = 0;
+}

package/src/analytics-strict.js

@@ -0,0 +1,139 @@
+// Events whose every property is checked against its own closed set, never the
+// generic "short string" rule. analytics.js asks strictPropValidator(event) once
+// per event; a property its validator refuses is dropped.
+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";
+
+const TURN_ID_PATTERN = /^[a-f0-9]{32}$/;
+// The friction count vocabulary (analytics-friction.js bucketFrictionCount).
+const COUNT_BUCKETS = new Set(["0", "1", "2", "3", "4-5", "6-10", "gte11"]);
+const LONG_BUCKETS = new Set(["lt10s", "10-30s", "30-60s", "1-2m", "2-5m", "gte5m"]);
+const AGE_BUCKETS = new Set(["lt2s", "2-10s", "10-60s", "gte60s"]);
+const SHORT_MS_BUCKETS = new Set(["lt50", "50-150", "150-500", "500-2000", "gte2000"]);
+const REFUSAL_CODES = new Set([...STUDIO_ERROR_CODES, "other"]);
+// The providers CozyClay configures itself (bin/agent/providers.mjs PROVIDERS); the
+// connect funnel reports any other id the login list offers as "other".
+export const CONNECT_PROVIDERS = Object.freeze(["openai-codex", "anthropic", "anthropic-subscription", "openai", "google",
+	"minimax", "minimax-cn", "openrouter", "cliproxy", "openai-compatible"]);
+
+/** A Studio refusal code as sent: one of STUDIO_ERROR_CODES, else "other". */
+export const refusalCodeOf = (code) => (STUDIO_ERROR_CODES.includes(code) ? code : "other");
+
+/** lt10s, 10-30s, 30-60s, 1-2m, 2-5m, gte5m: agent turns and edit windows outlast bucketMs. */
+export function bucketLong(ms) {
+	if (!Number.isFinite(ms) || ms < 10_000) return "lt10s";
+	if (ms < 30_000) return "10-30s";
+	if (ms < 60_000) return "30-60s";
+	if (ms < 120_000) return "1-2m";
+	if (ms < 300_000) return "2-5m";
+	return "gte5m";
+}
+
+/** lt2s, 2-10s, 10-60s, gte60s: how old an edit was when it was undone. */
+export function bucketAge(ms) {
+	if (!Number.isFinite(ms) || ms < 2000) return "lt2s";
+	if (ms < 10_000) return "2-10s";
+	if (ms < 60_000) return "10-60s";
+	return "gte60s";
+}
+
+const oneOf = (...values) => (value) => values.includes(value);
+const inSet = (set) => (value) => set.has(value);
+const turnId = (value) => typeof value === "string" && TURN_ID_PATTERN.test(value);
+const bool = (value) => typeof value === "boolean";
+const count = inSet(COUNT_BUCKETS);
+const long = inSet(LONG_BUCKETS);
+
+// One closed check per property. The keys are the allowlist (EVENT_PROPERTIES).
+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"),
+	},
+	// error_type: the app:error label set (analytics.js describeError); never a message or stack.
+	"app:render_crash": { error_type: inSet(ERROR_TYPE_VALUES) },
+	"app:gl_lost": { kind: oneOf("unavailable", "context_lost") },
+	"studio:ready": { boot: oneOf("lt2s", "2-5s", "5-15s", "gte15s") },
+	// late_ticks (the late_tick_ratio set) is an estimate: timer ticks that caught up more than one frame,
+	// not measured render drops. measured_fps is device:profile's frame_rate_bucket set (bucketFrameRate).
+	"playback:summary": {
+		duration: long, late_ticks: oneOf("0", "lt5", "5-20", "20-50", "gte50"), max_catchup: oneOf("1", "2", "3-5", "gte6"),
+		fps: oneOf("12", "24", "30", "60", "other"), speed: oneOf("0.5", "1", "2", "other"),
+		measured_fps: oneOf("lt20", "20-40", "40-55", "gte55", "unknown"),
+	},
+	// mode and step: first-success-guide.jsx's STEPS_BY_MODE keys and its 4 steps per mode.
+	"guide:opened": { mode: oneOf("animation", "storyboard") },
+	"guide:step": { mode: oneOf("animation", "storyboard"), step: oneOf("1", "2", "3", "4"), step_ms: long },
+	"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") },
+	"object:deleted_soon": { age: inSet(AGE_BUCKETS) },
+	"object:delete_undone": { age: inSet(AGE_BUCKETS) },
+	"edit:undone": {
+		age: inSet(AGE_BUCKETS), kind: oneOf("pose", "camera", "object", "shot", "prompt", "agent_turn", "ik_preview", "other"),
+		via: oneOf("key", "menu", "button"), result: oneOf("done", "noop", "refused"),
+	},
+	"agent:turn_summary": {
+		turn_id: turnId, outcome: oneOf("succeeded", "failed", "cancelled"), wall: long, first_tool: long,
+		tool_calls: count, tool_failed: count, refused: count, refusal_top: (value) => value === "none" || REFUSAL_CODES.has(value),
+		stale_retry: count, authored: bool, drafts: count, qa_first: oneOf("clean", "problems"), qa_last: oneOf("clean", "problems"),
+		qa_trend: oneOf("improved", "flat", "worse", "na"), stuck: bool, cancel_phase: oneOf("before_tool", "during_tool", "after_tool", "na"),
+	},
+	"motion:draft_compiled": {
+		draft_index: count, qa_clean: bool, qa_problems: count, qa_frames: oneOf("0", "1-10", "11-50", "51-200", "gte201"),
+		compile: inSet(SHORT_MS_BUCKETS), installed: bool, stuck: bool, repaired: bool, searched: bool, adjusted: bool,
+		frames: oneOf("lt30", "30-120", "121-480", "gte481"),
+	},
+	// Shortcut, search and thrash friction (shortcut-friction.js, search-friction.js, thrash-friction.js).
+	// A key class or combo name, never the key character; a query length bucket, never the query.
+	"shortcut:ignored": {
+		key_class: oneOf("undo", "redo", "mode", "transform", "frame", "duplicate", "delete"),
+		reason: oneOf("no_selection", "wrong_mode", "workflow_mode", "busy", "empty_history"),
+	},
+	"shortcut:unbound": { combo: oneOf("copy", "paste", "cut", "select_all", "group", "find", "rename", "help") },
+	"help:shortcuts_opened": {},
+	"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) },
+	"agent:connect_opened": { entry: oneOf("first_run", "failure_card", "signed_out", "menu", "other") },
+	"agent:connect_started": { provider: oneOf(...CONNECT_PROVIDERS, "other"), method: oneOf("oauth", "api_key", "chatgpt") },
+	"agent:connect_finished": {
+		provider: oneOf(...CONNECT_PROVIDERS, "other"), method: oneOf("oauth", "api_key", "chatgpt"),
+		outcome: oneOf("ok", "failed", "cancelled", "abandoned"), step: oneOf("list", "prompt", "waiting", "done"), duration: long,
+	},
+	"agent:model_changed": { provider: oneOf(...CONNECT_PROVIDERS, "other"), after_failure: bool },
+	"agent:prompt_sent": {
+		turn_id: turnId, provider: oneOf(...CONNECT_PROVIDERS, "other"), via: oneOf("typed", "retry_button", "regenerate", "chip", "supervisor"),
+		prompt_len: oneOf("1-20", "21-80", "81-240", "gte241"), compose_ms: long, similarity: oneOf("first", "same", "near", "different"),
+		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") },
+	// 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:finished": {
+		outcome: oneOf("ok", "failed"), error_class: oneOf("none", "permission", "network", "node_version", "npm_missing", "other"), duration: long,
+	},
+	"agent:post_turn_edit": {
+		// prompt_block, not prompt: "prompt" is a denied property key (analytics.js), whatever its value.
+		turn_id: turnId, edited: bool, pose: count, camera: count, object: count, shot: count, prompt_block: count, first_delay: long,
+	},
+});
+
+/** EVENT_PROPERTIES rows for the strict events defined here (app:session_ended keeps its own row). */
+export const STRICT_EVENT_KEYS = Object.freeze({
+	"app:friction_summary": FRICTION_SUMMARY_KEYS,
+	...Object.fromEntries(Object.entries(SCHEMAS).map(([event, schema]) => [event, Object.keys(schema)])),
+});
+
+/** (key, value) => allowed, for an event with a closed schema; null for every other event. */
+export function strictPropValidator(event) {
+	if (event === "app:session_ended") return sessionEndedPropAllowed;
+	if (event === "app:friction_summary") return frictionPropAllowed;
+	const schema = SCHEMAS[event];
+	return schema ? (key, value) => Object.hasOwn(schema, key) && schema[key](value) : null;
+}