cozyclay 3.1.4 → 3.1.5

package/src/semantic-edit.js

@@ -1,7 +1,9 @@
 import { createCameraBlock } from "./camera-block.js";
 import { isBusRunActive } from "./command-bus.js";
 
-export const FIRST_EDIT_VERSION = 1;
+// 2: counted from the user's own command-bus receipts (#922); 1 diffed domain values and
+// missed shot, camera and object edits in the real Studio.
+export const FIRST_EDIT_VERSION = 2;
 export const FIRST_EDIT_KINDS = Object.freeze([
 	"pose_edit", "object_insert", "cutout_insert", "object_transform",
 	"shot_add", "shot_edit", "camera_key_record", "rail_edit",
@@ -64,18 +66,29 @@ export function semanticEditKind(domain, before, after) {
 	return null;
 }
 
-export function createFirstEditTracker(emit) {
+/** (surface, kind) -> the surface's first edit, once: `${surface}:first_edit` with a closed kind. */
+export function createFirstEditRecorder(emit) {
 	// Dedupe once per editor App mount, independently for Studio and Playground.
 	// Scene/project switches and history do not reset it; no install persistence.
 	const seen = new Set();
-	return (surface, domain, before, after) => {
-		if (!["craft", "playground"].includes(surface) || seen.has(surface)) return false;
-		const kind = semanticEditKind(domain, before, after);
-		if (!kind) return false;
+	const record = (surface, kind) => {
+		if (!["craft", "playground"].includes(surface) || seen.has(surface) || !FIRST_EDIT_KINDS.includes(kind)) return false;
 		seen.add(surface);
 		emit(`${surface}:first_edit`, { edit_kind: kind, definition_version: FIRST_EDIT_VERSION });
 		return true;
 	};
+	record.seen = surface => seen.has(surface);
+	return record;
+}
+
+/** The same dedupe over a domain diff (semanticEditKind), for callers that hold before/after values. */
+export function createFirstEditTracker(emit) {
+	const record = createFirstEditRecorder(emit);
+	return (surface, domain, before, after) => {
+		if (record.seen(surface)) return false;
+		const kind = semanticEditKind(domain, before, after);
+		return kind ? record(surface, kind) : false;
+	};
 }
 
 // Synchronous mutation owner shared by UI and live commands. Keeping the before

package/src/shell/BoardSlot.jsx

@@ -4,7 +4,7 @@ import { ko } from "../locale.js";
 import { assetRecord, rememberAsset } from "../scene-asset-cache.js";
 import { ASSET_MAX_SOURCE_BYTES, importImageFile } from "../scene-assets.js";
 import { STILL_HOLD_MAX } from "../shot-authoring.js";
-import { startExportAttempt, track } from "../analytics.js";
+import { track } from "../analytics.js"; import { startExportAttempt } from "../export-attempt.js";
 import { bytesToDataUrl, panelVideoPrompt, sendPanelToWorkflow } from "../workflow-send.js";
 import { panelStylizeRequest, requestAgentImage, stylizedPngBytes, stylizeErrorMessage } from "../agent-image-client.js";
 
@@ -266,7 +266,7 @@ function PanelCard({ shot, index, fps, thumb, stylizing, onStylize, onUnstylize,
 			<div className="dock-board-actions">
 				<button type="button" data-action="duplicate" title={ko("Duplicate this panel after itself", "이 패널을 바로 뒤에 복제")} onClick={(event) => { stop(event); onDuplicate(); }}>{ko("Duplicate", "복제")}</button>
 				<button type="button" data-action="delete" className="danger" title={ko("Delete this panel (Delete)", "이 패널 삭제 (Delete)")} onClick={(event) => { stop(event); onRemove(); }}>{ko("Delete", "삭제")}</button>
-				<button type="button" data-action="stylize" disabled={stylizing}
+				<button type="button" data-action="stylize" data-fid="board_stylize" disabled={stylizing}
 					title={shot.stylizedAssetId
 						? ko("Generate a new stylized picture from this panel's frame and caption (replaces the current one)", "이 패널의 프레임과 캡션으로 스타일화 그림을 새로 생성 (지금 그림을 바꿔요)")
 						: ko("Generate a stylized picture from this panel's frame and caption", "이 패널의 프레임과 캡션으로 스타일화 그림 생성")}
@@ -295,7 +295,7 @@ function PanelCard({ shot, index, fps, thumb, stylizing, onStylize, onUnstylize,
 						<button type="button" role="menuitem" data-send-source="greybox" onClick={(event) => { stop(event); setSendMenu(false); onSendToWorkflow("greybox"); }}>{ko("Greybox", "그레이박스")}</button>
 					</div>
 				)}
-				<button type="button" data-action="export" disabled={exporting} title={exporting ? ko("Export — another export is running", "내보내기 — 다른 내보내기가 진행 중입니다") : ko("Export this panel as a pack (zip)", "이 패널을 팩(zip)으로 내보내기")} data-disabled-reason={exporting ? "export-running" : undefined} onClick={(event) => { stop(event); onExport(); }}>{ko("Export", "내보내기")}</button>
+				<button type="button" data-action="export" data-fid="board_export" disabled={exporting} title={exporting ? ko("Export — another export is running", "내보내기 — 다른 내보내기가 진행 중입니다") : ko("Export this panel as a pack (zip)", "이 패널을 팩(zip)으로 내보내기")} data-disabled-reason={exporting ? "export-running" : undefined} onClick={(event) => { stop(event); onExport(); }}>{ko("Export", "내보내기")}</button>
 			</div>
 			<div className="dock-board-thumb" data-stylized={stylized ? "true" : undefined}>
 				{stylized ? <img className="dock-board-image" src={stylized} alt="" draggable={false} /> : thumb && <img className="dock-board-image" src={thumb} alt="" draggable={false} />}

package/src/shell/BottomDock.jsx

@@ -194,7 +194,7 @@ export default function BottomDock({ tab: requestedTab = "animation", onTabChang
 						type="button"
 						role="tab"
 						key={entry.key}
-						data-testid={`dock-tab-${entry.key}`}
+						data-testid={`dock-tab-${entry.key}`} data-fid={`dock_tab_${entry.key}`}
 						aria-selected={tab === entry.key}
 						onClick={() => onTabChange?.(entry.key)}
 					>

package/src/shell/DetailsSlot.jsx

@@ -271,7 +271,7 @@ export default function DetailsSlot() {
 				<button
 					type="button"
 					className="studio-agent-bar"
-					data-testid="studio-agent-bar"
+					data-testid="studio-agent-bar" data-fid="agent_panel"
 					aria-expanded="false"
 					title={ko("Open Agent (Cmd/Ctrl+B)", "에이전트 열기 (Cmd/Ctrl+B)")}
 					onClick={() => setStudioAgentMode(true)}

package/src/shell/MenuBar.jsx

@@ -3,6 +3,7 @@ import { createPortal } from "react-dom";
 import { useStudioShell } from "./studio-shell-context.js";
 import SourceOffer from "../source-offer.jsx";
 import { ko } from "../locale.js";
+import { noteShortcutsOpened } from "../shortcut-friction.js";
 
 const MAC = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform ?? "");
 const MOD = MAC ? "⌘" : "Ctrl+";
@@ -351,7 +352,7 @@ export default function MenuBar({ preferences }) {
 						type="button"
 						role="menuitem"
 						className="menubar-item"
-						data-testid="export-animation-project"
+						data-testid="export-animation-project" data-fid="export_animation_project"
 						onClick={item(() => runStudioAction("project.exportAsAnimation"))}
 					>
 						<span className="menubar-item-label">{ko("Export as Animation project…", "애니메이션 프로젝트로 내보내기…")}</span>
@@ -389,7 +390,7 @@ export default function MenuBar({ preferences }) {
 								type="button"
 								role="menuitem"
 								className="menubar-item export-menu-primary"
-								data-testid="export-keyframe-pack"
+								data-testid="export-keyframe-pack" data-fid="export_keyframe_pack"
 								disabled={!shots.length || recording}
 								data-disabled-reason={shots.length ? undefined : "no-shots"}
 								title={shots.length
@@ -410,7 +411,7 @@ export default function MenuBar({ preferences }) {
 									type="button"
 									role="menuitem"
 									className="menubar-item"
-									data-testid="export-video"
+									data-testid="export-video" data-fid="export_video"
 									disabled={recording}
 									title={ko("Render the whole timeline to one MP4 — every shot back to back, camera and motion, no editor chrome", "타임라인 전체를 MP4 하나로 — 모든 샷을 이어서, 카메라·모션만, 편집 UI 제외")}
 									onClick={() => {
@@ -426,7 +427,7 @@ export default function MenuBar({ preferences }) {
 									type="button"
 									role="menuitem"
 									className="menubar-item"
-									data-testid="export-video-shot"
+									data-testid="export-video-shot" data-fid="export_video_shot"
 									disabled={recording}
 									title={ko("Render one shot to its own MP4 — the shot you opened the menu from, or the one under the playhead", "샷 하나만 MP4로 — 메뉴를 연 샷, 아니면 재생 위치의 샷")}
 									onClick={() => {
@@ -442,7 +443,7 @@ export default function MenuBar({ preferences }) {
 								type="button"
 								role="menuitem"
 								className="menubar-item"
-								data-testid="export-render-passes"
+								data-testid="export-render-passes" data-fid="export_render_passes"
 								disabled={recording}
 								title={ko("Depth and normal conditioning plates of the current framing", "현재 프레이밍의 뎁스·노멀 컨디션 플레이트")}
 								onClick={item(exportRenderPasses)}
@@ -453,7 +454,7 @@ export default function MenuBar({ preferences }) {
 								type="button"
 								role="menuitem"
 								className="menubar-item"
-								data-testid="export-depth-video"
+								data-testid="export-depth-video" data-fid="export_depth_video"
 								disabled={!shots.length || recording}
 								data-disabled-reason={shots.length ? undefined : "no-shots"}
 								title={ko("Depth pass of the whole shot as an mp4 for video-model conditioning", "샷 전체의 뎁스 패스를 mp4로 — 영상 모델 컨디셔닝용")}
@@ -469,7 +470,7 @@ export default function MenuBar({ preferences }) {
 								type="button"
 								role="menuitem"
 								className="menubar-item"
-								data-testid="export-storyboard"
+								data-testid="export-storyboard" data-fid="export_storyboard"
 								disabled={!shots.length || recording}
 								data-disabled-reason={shots.length ? undefined : "no-shots"}
 								title={shots.length
@@ -484,7 +485,7 @@ export default function MenuBar({ preferences }) {
 									type="button"
 									role="menuitem"
 									className="menubar-item"
-									data-testid="export-otio"
+									data-testid="export-otio" data-fid="export_otio"
 									title={ko("Download OTIO cut list", "OTIO 컷 목록 다운로드")}
 									onClick={item(downloadOtioCutList)}
 								>
@@ -506,11 +507,11 @@ export default function MenuBar({ preferences }) {
 		),
 		edit: (
 			<>
-				<button type="button" role="menuitem" className="menubar-item" onClick={item(() => castDomain.undoScene())}>
+				<button type="button" role="menuitem" className="menubar-item" data-fid="menu_undo" onClick={item(() => castDomain.undoScene("menu"))}>
 					<span className="menubar-item-label">{ko("Undo", "실행 취소")}</span>
 					<Shortcut keys={`${MOD}Z`} />
 				</button>
-				<button type="button" role="menuitem" className="menubar-item" onClick={item(() => castDomain.redoScene())}>
+				<button type="button" role="menuitem" className="menubar-item" data-fid="menu_redo" onClick={item(() => castDomain.redoScene())}>
 					<span className="menubar-item-label">{ko("Redo", "다시 실행")}</span>
 					<Shortcut keys={`${SHIFT}${MOD}Z`} />
 				</button>
@@ -534,9 +535,8 @@ export default function MenuBar({ preferences }) {
 		),
 		help: (
 			<>
-				<button type="button" role="menuitem" className="menubar-item" onClick={item(() => setDialog("shortcuts"))}>
-					<span className="menubar-item-label">{ko("Keyboard shortcuts", "단축키")}</span>
-				</button>
+				<button type="button" role="menuitem" className="menubar-item" onClick={item(() => { setDialog("shortcuts"); noteShortcutsOpened(); })}>
+					<span className="menubar-item-label">{ko("Keyboard shortcuts", "단축키")}</span></button>
 				<button type="button" role="menuitem" className="menubar-item" onClick={item(() => setDialog("about"))}>
 					<span className="menubar-item-label">{ko("About Cozy Clay", "Cozy Clay 정보")}</span>
 				</button>

package/src/shell/StudioShell.jsx

@@ -1,5 +1,7 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
+import { installClickFriction } from "../click-friction.js";
 import { ko } from "../locale.js";
+import { noteNavSwitch } from "../thrash-friction.js";
 import { useStudioShell } from "./studio-shell-context.js";
 import TopBar, { ProjectHead } from "./TopBar.jsx";
 import OutlinerSlot from "./OutlinerSlot.jsx";
@@ -32,7 +34,11 @@ export default function StudioShell({ viewport, children, ...props }) {
 	// Embeds (playview, playground) keep the Sequencer-only dock.
 	const embedded = Boolean(props["data-embed-mode"]);
 	const shownTab = embedded ? "animation" : dockTab;
+	// Rage and dead clicks on the primary controls (data-fid): one capture-phase listener for the whole shell.
+	useEffect(() => installClickFriction(), []);
 	function changeDockTab(next) {
+		// A user's tab flip toward nav:thrash (thrash-friction.js).
+		if (next !== dockTab) noteNavSwitch("dock_tab");
 		setDockTab(next);
 		try {
 			globalThis.localStorage?.setItem(DOCK_TAB_KEY, next);

package/src/shell/TopBar.jsx

@@ -3,6 +3,7 @@ import ProjectPanel from "../panels/ProjectPanel.jsx";
 import MenuBar from "./MenuBar.jsx";
 import { SaveState } from "./StatusBar.jsx";
 import { ko } from "../locale.js";
+import UpdateChip from "../update/UpdateChip.jsx";
 import "./topbar.css";
 
 // 2a top bar: File/Edit/Window/Help, then the MCP state. Motion is authored by the
@@ -15,6 +16,7 @@ export default function TopBar({ preferences }) {
 		<header className="topbar v2-topbar" data-rec-state={recState}>
 			<MenuBar preferences={preferences} />
 			<div className="topbar-spacer" />
+			<UpdateChip />
 			<span
 				className={"topbar-mcp" + (liveWorkspaceHandle ? " live-workspace-handle" : "")}
 				data-state={connected ? "connected" : "disconnected"}

package/src/shell/ViewportToolbar.jsx

@@ -309,7 +309,7 @@ export default function ViewportToolbar() {
 							type="button"
 							key={tool.key}
 							data-tool-key={tool.key}
-							data-tool={tool.id}
+							data-tool={tool.id} data-fid={`tool_${tool.id}`}
 							className={"vp-tool-key" + (tool.active ? " active" : "")}
 							aria-pressed={tool.active}
 							aria-disabled={tool.refused ? true : undefined}
@@ -341,7 +341,7 @@ export default function ViewportToolbar() {
 								role="tab"
 								key={mode.id}
 								data-mode-key={mode.key}
-								data-mode={mode.id}
+								data-mode={mode.id} data-fid={`mode_${mode.id}`}
 								className={"vp-mode-key" + (active ? " active" : "")}
 								aria-selected={active}
 								aria-disabled={refused ? true : undefined}

package/src/shortcut-friction.js

@@ -0,0 +1,122 @@
+// Shortcut friction: shortcut:ignored (a bound Studio key that did nothing),
+// shortcut:unbound (a common combo the Studio has no binding for) and
+// help:shortcuts_opened. Only a closed key class, reason or combo name leaves,
+// never the key character. Keys typed into an input, textarea, select or
+// contenteditable element, and keys of an IME composition, are never looked at.
+import { track } from "./analytics.js";
+import { admit, bump } from "./analytics-friction.js";
+import { isImeComposing } from "./ime.js";
+
+const IGNORED_PER_CLASS = 5, UNBOUND_PER_COMBO = 3, HELP_PER_SESSION = 3;
+let send = track, defer = (run) => setTimeout(run, 0), listening = false;
+
+const emit = (event, props) => {
+	try { send(event, props); } catch { /* telemetry is advisory */ }
+};
+
+/** A target the user types into: its keys are text, never shortcuts. */
+function isTypingTarget(target) {
+	return Boolean(target && (target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(String(target.tagName ?? ""))));
+}
+
+/**
+ * A bound shortcut that did nothing. `keyClass` is one of undo, redo, mode,
+ * transform, frame, duplicate, delete; `reason` one of no_selection, wrong_mode,
+ * workflow_mode, busy, empty_history (analytics-strict.js). The friction
+ * counter moves every time; the event goes out 5 times per class per session.
+ */
+export function noteShortcutIgnored(keyClass, reason) {
+	try {
+		bump("shortcut_ignored");
+		if (admit(`shortcut:ignored:${keyClass}`, IGNORED_PER_CLASS)) emit("shortcut:ignored", { key_class: keyClass, reason });
+	} catch { /* telemetry is advisory */ }
+}
+
+/** Ctrl/Cmd+Z (undo) or Ctrl/Cmd+Shift+Z (redo) from the keyboard: its bus receipt says whether anything moved. */
+export function noteHistoryKey(keyClass, receipt) {
+	// A refused undo names a running task that owns the last edit (scene-undo.js).
+	if (receipt?.ok === false) noteShortcutIgnored(keyClass, "busy");
+	else if (receipt?.status === "noop") noteShortcutIgnored(keyClass, "empty_history");
+}
+
+/**
+ * A key that reached the global handler's "nothing selected" exit (App.jsx):
+ * F, Ctrl/Cmd+D and Delete/Backspace need a selection there. Another handler
+ * (a path point, a cut, a board panel) may own the key, so only a press no
+ * handler claimed (defaultPrevented false after dispatch) counts.
+ */
+export function noteUnselectedKey(event) {
+	if (!event || event.repeat || isImeComposing(event)) return;
+	const mod = event.ctrlKey || event.metaKey;
+	const keyClass = event.code === "KeyF" && !mod && !event.altKey ? "frame"
+		: event.code === "KeyD" && mod && !event.altKey && !event.shiftKey ? "duplicate"
+			: (event.key === "Delete" || event.key === "Backspace") && !mod ? "delete" : null;
+	if (!keyClass) return;
+	defer(() => { if (!event.defaultPrevented) noteShortcutIgnored(keyClass, "no_selection"); });
+}
+
+const modOnly = (event) => (event.ctrlKey || event.metaKey) && !event.altKey && !event.shiftKey;
+const bare = (event) => !event.ctrlKey && !event.metaKey && !event.altKey && !event.shiftKey;
+// The closed combo list, by physical key code (a keyboard layout or an IME never
+// changes it). F2 (rename) is the one bare key; every other combo is modifier + key.
+// Save, zoom-to-fit, focus-selected and deselect are left out: Ctrl/Cmd+S is bound
+// (MenuBar.jsx), and the others have no modifier combo common enough to name.
+const COMBOS = [
+	["copy", (event) => modOnly(event) && event.code === "KeyC"],
+	["paste", (event) => modOnly(event) && event.code === "KeyV"],
+	["cut", (event) => modOnly(event) && event.code === "KeyX"],
+	["select_all", (event) => modOnly(event) && event.code === "KeyA"],
+	["group", (event) => modOnly(event) && event.code === "KeyG"],
+	["find", (event) => modOnly(event) && event.code === "KeyF"],
+	["rename", (event) => bare(event) && event.code === "F2"],
+	["help", (event) => event.code === "Slash" && !event.altKey && (event.shiftKey || event.ctrlKey || event.metaKey)],
+];
+export const UNBOUND_COMBOS = Object.freeze(COMBOS.map(([name]) => name));
+
+/** The closed combo name of a keydown, or null. */
+export function comboOf(event) {
+	return COMBOS.find(([, matches]) => matches(event))?.[0] ?? null;
+}
+
+// Copying or cutting page text the user selected is the browser's own job.
+const hasTextSelection = () => {
+	try { return globalThis.getSelection?.()?.isCollapsed === false; } catch { return false; }
+};
+
+/**
+ * A keydown on the window, in the bubble phase. It is judged after dispatch
+ * (deferred), so every Studio handler has run: a combo none of them claimed
+ * (defaultPrevented false) is unbound. Capture-phase handlers that stop the
+ * event (controls.jsx onEscapeCapture, object-gizmo.jsx's drag Escape) are
+ * invisible here; none of them handles a combo on the list.
+ */
+export function noteUnboundKey(event) {
+	if (!event || event.repeat || isImeComposing(event) || isTypingTarget(event.target)) return null;
+	const combo = comboOf(event);
+	if (!combo || ((combo === "copy" || combo === "cut") && hasTextSelection())) return null;
+	defer(() => {
+		if (event.defaultPrevented) return;
+		if (admit(`shortcut:unbound:${combo}`, UNBOUND_PER_COMBO)) emit("shortcut:unbound", { combo });
+	});
+	return combo;
+}
+
+/** Install the unbound-combo listener once (main.jsx). */
+export function listenForUnboundShortcuts(target = globalThis.window) {
+	if (listening || typeof target?.addEventListener !== "function") return false;
+	target.addEventListener("keydown", noteUnboundKey);
+	listening = true;
+	return true;
+}
+
+/** Help > Keyboard shortcuts opened: 3 per session. */
+export function noteShortcutsOpened() {
+	if (admit("help:shortcuts_opened", HELP_PER_SESSION)) emit("help:shortcuts_opened", {});
+}
+
+/** Tests only: capture what is sent and run deferred checks by hand; returns the restore. */
+export function shortcutFrictionSeam({ track: capture = track, defer: later = defer } = {}) {
+	const previous = [send, defer];
+	send = capture; defer = later;
+	return () => { [send, defer] = previous; };
+}

package/src/stage-canvas-rigs.jsx

@@ -7,6 +7,7 @@ import { shotAtFrame } from "./cuts.js";
 import { sampleAt } from "./sample-at.js";
 import { playbackProbe, probeVisibility } from "./motion/playback-probe.js";
 import { RENDER_ACTIVITY_EVENT } from "./use-render-activity.js";
+import { reportGlLost } from "./crash-telemetry.js";
 import { PRESETS, editorFrameForSubject } from "./stage-startup-defaults.js";
 
 /** Selection marker for the picked cast member: a Unity-style XYZ tripod
@@ -371,11 +372,9 @@ export function ContextLossGuard({ onLostChange }) {
 		const onLost = (event) => {
 			event.preventDefault();
 			onLostChange(true);
+			reportGlLost("context_lost");
 		};
-		const onRestored = () => {
-			onLostChange(false);
-			invalidate();
-		};
+		const onRestored = () => { onLostChange(false); invalidate(); };
 		canvas.addEventListener("webglcontextlost", onLost);
 		canvas.addEventListener("webglcontextrestored", onRestored);
 		return () => {

package/src/studio-telemetry.js

@@ -0,0 +1,97 @@
+// Studio-shell signals with closed values only:
+// - studio:ready, once per session: navigation start to the first frame after the
+//   first React commit (StudioReadyMark in main.jsx). It never delays the render.
+// - agent:panel_toggled, at most 10 per session: Cmd/Ctrl+B or the toolbar control.
+// - object:deleted_soon and object:delete_undone, at most 10 each per session.
+//   Object ids are slugs a re-created object of the same kind can reuse, so only an
+//   id this session created counts, and the age is an ESTIMATE.
+// Never object ids, names, kinds or anything the user typed.
+import { useEffect } from "react";
+import { initAnalytics, track } from "./analytics.js";
+import { admit } from "./analytics-friction.js";
+import { bucketAge } from "./analytics-strict.js";
+
+// Mirrors OBJECT_DELETE_UNDO_MS (stage-startup-defaults.js); test/verify-analytics.mjs checks both.
+export const DELETE_UNDO_WINDOW_MS = 7000;
+const PANEL_TOGGLES_PER_SESSION = 10, DELETES_PER_SESSION = 10;
+
+let send = track, clock = () => Date.now();
+// studio:ready lands before the SDK has loaded; initAnalytics() is idempotent (main.jsx started it).
+let sendWhenReady = (event, props) => { initAnalytics().then(() => send(event, props), () => {}); };
+const created = new Map(), deleted = new Map();
+const guarded = (run) => { try { run(); } catch { /* Telemetry must never affect the studio. */ } };
+
+/** lt2s, 2-5s, 5-15s, gte15s from navigation start. */
+export function bucketBoot(ms) {
+	if (!Number.isFinite(ms) || ms < 2000) return "lt2s";
+	if (ms < 5000) return "2-5s";
+	if (ms < 15_000) return "5-15s";
+	return "gte15s";
+}
+
+/** The first frame after the first render; `ms` is performance.now() (navigation start origin). */
+export function noteStudioReady(ms) {
+	guarded(() => {
+		if (Number.isFinite(ms) && ms >= 0 && admit("studio:ready", 1)) sendWhenReady("studio:ready", { boot: bucketBoot(ms) });
+	});
+}
+
+/** Renders nothing; after the first commit it waits one frame and reports studio:ready. */
+export function StudioReadyMark() {
+	useEffect(() => {
+		const raf = globalThis.requestAnimationFrame;
+		if (typeof raf !== "function") return undefined;
+		const id = raf(() => noteStudioReady(performance.now()));
+		return () => globalThis.cancelAnimationFrame?.(id);
+	}, []);
+	return null;
+}
+
+/** The agent panel is about to flip; `wasCollapsed` is its state before the toggle. */
+export function notePanelToggled(wasCollapsed, via) {
+	guarded(() => {
+		if (typeof wasCollapsed !== "boolean" || !["key", "button"].includes(via)) return;
+		if (admit("agent:panel_toggled", PANEL_TOGGLES_PER_SESSION)) send("agent:panel_toggled", { open: wasCollapsed, via });
+	});
+}
+
+/** The user added object `id` (Add menu, Assets shelf). */
+export function noteObjectCreated(id) {
+	guarded(() => { if (id) created.set(id, clock()); });
+}
+
+/** The user deleted object `id`; object:deleted_soon only when this session created that id. */
+export function noteObjectDeleted(id) {
+	guarded(() => {
+		if (!id) return;
+		const now = clock(), bornAt = created.get(id);
+		deleted.set(id, now);
+		if (bornAt === undefined) return;
+		created.delete(id);
+		if (admit("object:deleted_soon", DELETES_PER_SESSION)) send("object:deleted_soon", { age: bucketAge(now - bornAt) });
+	});
+}
+
+/** The deletion of `id` was undone; counts only inside the delete-undo window. */
+export function noteDeleteUndone(id) {
+	guarded(() => {
+		const deletedAt = deleted.get(id);
+		if (deletedAt === undefined) return;
+		deleted.delete(id);
+		const age = clock() - deletedAt;
+		if (age >= 0 && age <= DELETE_UNDO_WINDOW_MS && admit("object:delete_undone", DELETES_PER_SESSION)) {
+			send("object:delete_undone", { age: bucketAge(age) });
+		}
+	});
+}
+
+/** Tests only: capture what is sent (studio:ready too) and drive the clock; returns the restore. */
+export function studioTelemetrySeam(capture, now) {
+	const previous = [send, clock, sendWhenReady];
+	send = capture;
+	sendWhenReady = capture;
+	if (now) clock = now;
+	created.clear();
+	deleted.clear();
+	return () => { [send, clock, sendWhenReady] = previous; created.clear(); deleted.clear(); };
+}

package/src/thrash-friction.js

@@ -0,0 +1,90 @@
+// nav:thrash and camera:thrash: flipping between panels or modes, or moving the
+// camera again and again, with no edit in between. "No edit" is the command
+// bus's user-edit path (command-bus-telemetry.js lastUserEditAt): agent, MCP,
+// undo and redo receipts never count as an edit. Only closed values leave: a
+// surface, a count bucket, a gesture-kind mix and the fixed window.
+import { track } from "./analytics.js";
+import { bucketFrictionCount, bump } from "./analytics-friction.js";
+import { lastUserEditAt } from "./command-bus-telemetry.js";
+
+const COOLDOWN_MS = 30_000;
+let send = track, clock = () => Date.now(), lastEdit = lastUserEditAt;
+let timers = { set: (run, ms) => setTimeout(run, ms), clear: (id) => clearTimeout(id) };
+
+/** 4-5, 6-10, gte11: how many switches a thrash window held (4 is the threshold). */
+const bucketSwitches = (count) => (count <= 5 ? "4-5" : count <= 10 ? "6-10" : "gte11");
+const kindMix = (kinds) => (new Set(kinds).size === 1 ? kinds[0] : "mixed");
+
+/**
+ * `threshold` events inside `windowMs`, all after the last user edit, open a
+ * window that closes `windowMs` after its first event; at the close the event
+ * goes out with everything that window held, and a 30 s cooldown starts. A
+ * window that opens during the cooldown only moves the counter. A user edit after
+ * a window opened cancels it: the next event starts over from the events after
+ * that edit, so a fresh run of switches is judged on its own window.
+ */
+function createDetector({ event, counter, threshold, windowMs, props }) {
+	let stamps = [], open = null, cooledUntil = -Infinity;
+	const fresh = (now) => {
+		const edit = lastEdit();
+		return stamps.filter(({ at }) => at > edit && at > now - windowMs);
+	};
+	const close = (start) => {
+		open = null;
+		const edit = lastEdit();
+		const held = stamps.filter(({ at }) => at > edit && at >= start && at <= start + windowMs);
+		stamps = [];
+		if (held.length < threshold) return;
+		bump(counter);
+		cooledUntil = clock() + COOLDOWN_MS;
+		try { send(event, props(held)); } catch { /* telemetry is advisory */ }
+	};
+	return {
+		note(kind) {
+			if (open && lastEdit() >= open.start) { timers.clear(open.id); open = null; }
+			if (open) { stamps.push({ at: clock(), kind }); return; }
+			const now = clock();
+			stamps = [...fresh(now), { at: now, kind }];
+			if (stamps.length < threshold) return;
+			if (now < cooledUntil) { bump(counter); stamps = []; return; }
+			const start = stamps[0].at;
+			open = { start, id: timers.set(() => close(start), Math.max(0, start + windowMs - now)) };
+		},
+		reset() { if (open) timers.clear(open.id); stamps = []; open = null; cooledUntil = -Infinity; },
+	};
+}
+
+const NAV_SURFACES = ["dock_tab", "mode", "agent_panel"];
+const nav = Object.fromEntries(NAV_SURFACES.map((surface) => [surface, createDetector({
+	event: "nav:thrash", counter: "nav_thrash", threshold: 4, windowMs: 10_000,
+	props: (held) => ({ surface, switches: bucketSwitches(held.length), window_s: 10 }),
+})]));
+const camera = createDetector({
+	event: "camera:thrash", counter: "camera_thrash", threshold: 6, windowMs: 20_000,
+	props: (held) => ({ gestures: bucketFrictionCount(held.length), kind_mix: kindMix(held.map(({ kind }) => kind)), window_s: 20 }),
+});
+
+/**
+ * One user switch on `surface`: dock_tab (StudioShell.jsx), mode (App.jsx
+ * selectWorkflowMode) or agent_panel (App.jsx, the agent panel toggle). 4 or
+ * more in 10 s with no edit is a thrash; 30 s cooldown per surface.
+ */
+export function noteNavSwitch(surface) {
+	try { nav[surface]?.note(surface); } catch { /* telemetry is advisory */ }
+}
+
+/** One finished camera gesture that moved the view (controls.jsx): orbit, fly or pan. 6 or more in 20 s with no edit. */
+export function noteCameraGesture(kind) {
+	try { if (kind === "orbit" || kind === "fly" || kind === "pan") camera.note(kind); } catch { /* telemetry is advisory */ }
+}
+
+/** Tests only: capture what is sent, drive the clock, timers and last edit; returns the restore. */
+export function thrashSeam({ track: capture = track, now = clock, set = timers.set, clear = timers.clear, lastEditAt = lastEdit } = {}) {
+	const previous = [send, clock, timers, lastEdit];
+	send = capture; clock = now; timers = { set, clear }; lastEdit = lastEditAt;
+	for (const detector of [...Object.values(nav), camera]) detector.reset();
+	return () => {
+		for (const detector of [...Object.values(nav), camera]) detector.reset();
+		[send, clock, timers, lastEdit] = previous;
+	};
+}