@hyperframes/studio 0.8.114 → 0.8.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.114",
+  "version": "0.8.115",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/player": "0.8.114",
-    "@hyperframes/parsers": "0.8.114",
-    "@hyperframes/sdk": "0.8.114",
-    "@hyperframes/shader-transitions": "0.8.114",
-    "@hyperframes/studio-server": "0.8.114",
-    "@hyperframes/core": "0.8.114"
+    "@hyperframes/core": "0.8.115",
+    "@hyperframes/player": "0.8.115",
+    "@hyperframes/studio-server": "0.8.115",
+    "@hyperframes/sdk": "0.8.115",
+    "@hyperframes/shader-transitions": "0.8.115",
+    "@hyperframes/parsers": "0.8.115"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.114"
+    "@hyperframes/producer": "0.8.115"
   },
   "peerDependencies": {
     "react": "19",
@@ -97,6 +97,7 @@
     "test:filmstrip-controls": "node tests/e2e/filmstrip-controls.mjs",
     "test:webmcp-edit-loop": "node tests/e2e/webmcp-edit-loop.mjs",
     "test:thumbnail-save": "node tests/e2e/thumbnail-save.mjs",
+    "bench:timeline-bulk-actions": "node tests/e2e/timeline-bulk-actions.mjs",
     "test:timeline-virtualization": "TIMELINE_ROW_VIRTUALIZATION=on TIMELINE_ELEMENT_COUNT=50000 node tests/e2e/timeline-virtualization.mjs",
     "test:watch": "vitest",
     "test:colors:browser": "node tests/e2e/native-css-colors.mjs",

package/src/App.tsx

@@ -272,7 +272,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     onUngroupSelection: () => domEditSessionRef.current.handleUngroupSelection(),
     activeCompPath,
     forceReloadSdkSession: sdkHandle.forceReload,
-    onToggleRecording: () => handleToggleRecordingRef.current(),
+    onToggleRecording: () => handleToggleRecordingRef.current("keyboard"),
     readOnlyPreview,
   });
   const domEditSessionResult = useDomEditSession({
@@ -363,7 +363,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     resetErrors: resetConsoleErrors,
   } = useConsoleErrorCapture(previewIframe);
   const fileDrop = useGlobalFileDrop(timelineEditing.handleTimelineFileDrop);
-  const handleToggleRecordingRef = useRef<() => void>(() => {});
+  const handleToggleRecordingRef = useRef<(method?: "button" | "keyboard") => void>(() => {});
   const domEditSessionRef = useRef(domEditSession);
   domEditSessionRef.current = domEditSession;
   const { gestureState, gestureRecording, handleToggleRecording } = useGestureCommit({

package/src/components/LinkedSelectionToggle.tsx

@@ -6,6 +6,7 @@ import { useMenuKeyboardNav } from "../player/components/menuKeyboardNav";
 import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";
 import { Tooltip } from "./ui";
 import { flatActive, flatIdle } from "./timelineToolbarStyles";
+import { menuClasses } from "./ui/menuStyle";
 
 function SyncIndicatorMenu({ x, y, onClose }: { x: number; y: number; onClose: () => void }) {
   const menuRef = useContextMenuDismiss(onClose);
@@ -17,14 +18,14 @@ function SyncIndicatorMenu({ x, y, onClose }: { x: number; y: number; onClose: (
       ref={menuRef}
       role="menu"
       aria-label="Linked clips"
-      className="fixed z-200 min-w-[200px] rounded-sm border border-neutral-700 bg-neutral-900 py-1 shadow-lg"
+      className={`${menuClasses.panel} fixed z-200 min-w-[200px]`}
       style={{ left: x, top: y }}
     >
       <button
         type="button"
         role="menuitemcheckbox"
         aria-checked={visible}
-        className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs text-neutral-300 outline-hidden hover:bg-neutral-800 focus-visible:bg-neutral-800"
+        className={`${menuClasses.row} ${menuClasses.rowEnabled} flex items-center gap-2`}
         onClick={() => {
           setVisible(!visible);
           onClose();

package/src/components/dock/Dock.tsx

@@ -31,6 +31,7 @@ import {
   type PanelId,
 } from "./panelRegistry";
 import "./dock.css";
+import { menuClasses } from "../ui/menuStyle";
 
 const PERSIST_DEBOUNCE_MS = 250;
 
@@ -288,10 +289,7 @@ function WindowMenu() {
         Window
       </button>
       {open && (
-        <div
-          role="menu"
-          className="absolute right-0 top-8 z-50 w-44 rounded-md border border-neutral-800 bg-neutral-900 py-1 shadow-lg"
-        >
+        <div role="menu" className={`${menuClasses.panel} absolute right-0 top-8 z-50 w-44`}>
           {panels.map((id) => (
             <button
               key={id}
@@ -299,13 +297,13 @@ function WindowMenu() {
               role="menuitemcheckbox"
               aria-checked={openPanels.has(id)}
               onClick={() => togglePanel(id)}
-              className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-neutral-300 hover:bg-neutral-800"
+              className={`${menuClasses.row} ${menuClasses.rowEnabled} flex items-center gap-2`}
             >
               <span className="w-3 text-accent-ink">{openPanels.has(id) ? "✓" : ""}</span>
               {PANEL_DEFINITIONS[id].title}
             </button>
           ))}
-          <div className="my-1 border-t border-neutral-800" />
+          <div className={menuClasses.divider} />
           <button
             type="button"
             role="menuitem"
@@ -313,7 +311,7 @@ function WindowMenu() {
               resetLayout();
               setOpen(false);
             }}
-            className="w-full px-3 py-1.5 text-left text-[11px] text-neutral-300 hover:bg-neutral-800"
+            className={`${menuClasses.row} ${menuClasses.rowEnabled}`}
           >
             Reset layout
           </button>

package/src/components/editor/CanvasContextMenu.tsx

@@ -33,6 +33,7 @@ import {
   type ZOrderAction,
   type ZOrderPatch,
 } from "./canvasContextMenuZOrder";
+import { menuClasses } from "../ui/menuStyle";
 
 interface CanvasContextMenuProps {
   /** Viewport x of the right-click event. */
@@ -209,7 +210,7 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
   return createPortal(
     <div
       ref={menuRef}
-      className="fixed z-200 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
+      className={`${menuClasses.panel} fixed z-200 min-w-[180px]`}
       style={{ left: adjustedX, top: adjustedY }}
       onPointerDown={stopBubble}
       onMouseDown={stopBubble}
@@ -252,7 +253,7 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
           );
         })}
 
-      {hasDivider && <div className="my-1 border-t border-neutral-700/60" />}
+      {hasDivider && <div className={menuClasses.divider} />}
 
       {hasDelete && (
         <button

package/src/components/editor/DomEditCropHandles.test.tsx

@@ -345,3 +345,30 @@ describe("DomEditCropHandles preset bar", () => {
     expect(useCropPresetBarStore.getState().openFor).toBeNull();
   });
 });
+
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../../utils/studioTelemetry";
+describe("crop usage", () => {
+  it.each([true, false])(
+    "counts a crop drag only after a changed writer result (%s)",
+    async (changed) => {
+      vi.mocked(trackStudioEvent).mockClear();
+      const saved = vi.fn(async () => ({ ok: true, changed }));
+      const { root } = render(makeEl("private-target", "inset(10px)"), saved);
+      const handle = document.querySelector<HTMLElement>('[aria-label="Crop right"]')!;
+      dragCropRight(handle, 1, [
+        [200, 1],
+        [180, 1],
+        [160, 1],
+      ]);
+      await act(async () => {
+        await Promise.resolve();
+      });
+      expect(saved).toHaveBeenCalledTimes(1);
+      expect(vi.mocked(trackStudioEvent).mock.calls).toEqual(
+        changed ? [["feature_used", { feature: "crop", surface: "preview", method: "drag" }]] : [],
+      );
+      act(() => root.unmount());
+    },
+  );
+});

package/src/components/editor/DomEditCropHandles.tsx

@@ -1,3 +1,4 @@
+import { trackPreviewEditResult, type PreviewMethod } from "../../utils/previewFeatureUsage";
 import { useEffect, useRef, useState, type PointerEvent as ReactPointerEvent } from "react";
 import type { DomEditSelection } from "./domEditing";
 import { type OverlayRect, RESIZE_HANDLE_HIT_PX } from "./domEditOverlayGeometry";
@@ -229,19 +230,21 @@ export function DomEditCropHandles({
     // the lift keeps it hidden while selected. A drag that ends where it started saves nothing.
     const value = buildInsetClipPathSides(gesture.insets, gesture.radius);
     if (value === buildInsetClipPathSides(gesture.startInsets, gesture.radius)) return;
-    commitClipPath(value);
+    commitClipPath(value, "drag");
   };
 
-  const commitClipPath = (value: string) => {
+  const commitClipPath = (value: string, method: PreviewMethod) => {
     const commit = onStyleCommit?.("clip-path", value);
-    void Promise.resolve(commit).catch(() => undefined);
+    void Promise.resolve(commit)
+      .then((result) => trackPreviewEditResult("crop", method, result))
+      .catch(() => undefined);
   };
 
   const applyPresetInsets = (insets: ClipPathInsetSides | null) => {
     const next = insets ?? { top: 0, right: 0, bottom: 0, left: 0 };
     setState((prev) => ({ ...prev, insets: next }));
     const radius = readCropFollowingResize(selection.element)?.radius ?? 0;
-    commitClipPath(insets === null ? "" : buildInsetClipPathSides(next, radius));
+    commitClipPath(insets === null ? "" : buildInsetClipPathSides(next, radius), "button");
   };
 
   const cancelCropGesture = (event: ReactPointerEvent<HTMLElement>) => {

package/src/components/editor/DomEditOverlay.tsx

@@ -1,3 +1,4 @@
+import type { DomSelectionResult } from "../../hooks/useDomSelectionTypes";
 import type { RotationCommit } from "./rotationDraft";
 import { memo, useEffect, useMemo, useRef, type RefObject } from "react";
 import { type DomEditSelection } from "./domEditing";
@@ -98,7 +99,10 @@ export interface DomEditOverlayProps {
   onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
   recordingState?: GestureRecordingState;
   onToggleRecording?: () => void;
-  onMarqueeSelect?: (selections: DomEditSelection[], additive: boolean) => void;
+  onMarqueeSelect?: (
+    selections: DomEditSelection[],
+    additive: boolean,
+  ) => DomSelectionResult | void;
   /**
    * Delete the selected canvas element.
    * Wire to handleDomEditElementDelete from useDomEditActionsContext —

package/src/components/editor/FileTreeNodes.tsx

@@ -18,11 +18,14 @@ import {
   type InlineInputState,
   DIM,
 } from "./FileTreeIcons";
+import { menuClasses } from "../ui/menuStyle";
 
 export type { ContextMenuState, InlineInputState };
 export { buildTree, sortChildren, isActiveInSubtree } from "./FileTreeIcons";
 
 const SZ_ICON = 14;
+const ROW = `${menuClasses.row} ${menuClasses.rowEnabled} flex items-center gap-2 active:bg-neutral-700`;
+const DANGER_ROW = `${menuClasses.row} ${menuClasses.rowDanger} flex items-center gap-2 active:bg-danger/25`;
 
 // ── Context Menu Component ──
 
@@ -101,14 +104,14 @@ export function ContextMenu({
       ref={menuRef}
       role="menu"
       onKeyDown={handleMenuKeyDown}
-      className="fixed z-50 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[160px]"
+      className={`${menuClasses.panel} fixed z-50 min-w-[160px]`}
       style={{ left: adjustedX, top: adjustedY }}
     >
       {state.targetIsFolder && (
         <>
           <button
             role="menuitem"
-            className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 active:bg-neutral-700 outline-hidden cursor-pointer text-left"
+            className={ROW}
             onClick={() => {
               onNewFile(state.targetPath);
               onClose();
@@ -119,7 +122,7 @@ export function ContextMenu({
           </button>
           <button
             role="menuitem"
-            className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 active:bg-neutral-700 outline-hidden cursor-pointer text-left"
+            className={ROW}
             onClick={() => {
               onNewFolder(state.targetPath);
               onClose();
@@ -128,14 +131,14 @@ export function ContextMenu({
             <FolderSimplePlus size={12} weight="duotone" className="text-neutral-500" />
             New Folder
           </button>
-          <div className="border-t border-neutral-700 my-1" />
+          <div className={menuClasses.divider} />
         </>
       )}
       {!state.targetIsFolder && (
         <>
           <button
             role="menuitem"
-            className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 active:bg-neutral-700 outline-hidden cursor-pointer text-left"
+            className={ROW}
             onClick={() => {
               onNewFile(parentPath);
               onClose();
@@ -144,12 +147,12 @@ export function ContextMenu({
             <FilePlus size={12} weight="duotone" className="text-neutral-500" />
             New File
           </button>
-          <div className="border-t border-neutral-700 my-1" />
+          <div className={menuClasses.divider} />
         </>
       )}
       <button
         role="menuitem"
-        className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 active:bg-neutral-700 outline-hidden cursor-pointer text-left"
+        className={ROW}
         onClick={() => {
           onRename(state.targetPath);
           onClose();
@@ -161,7 +164,7 @@ export function ContextMenu({
       {!state.targetIsFolder && (
         <button
           role="menuitem"
-          className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 active:bg-neutral-700 outline-hidden cursor-pointer text-left"
+          className={ROW}
           onClick={() => {
             onDuplicate(state.targetPath);
             onClose();
@@ -171,10 +174,10 @@ export function ContextMenu({
           Duplicate
         </button>
       )}
-      <div className="border-t border-neutral-700 my-1" />
+      <div className={menuClasses.divider} />
       <button
         role="menuitem"
-        className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-danger-ink hover:bg-danger/25 focus-visible:bg-danger/25 active:bg-danger/25 outline-hidden cursor-pointer text-left"
+        className={DANGER_ROW}
         onClick={() => {
           onDelete(state.targetPath);
           onClose();

package/src/components/editor/MotionPathOverlay.tsx

@@ -1,3 +1,5 @@
+import { observeGsapGesture } from "../../hooks/gsapGestureOutcome";
+import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
 import { scopedElementKey } from "../../hooks/gsapKeyframeCacheHelpers";
 import { memo, useEffect, useRef, useState, type RefObject } from "react";
 import type { DomEditSelection } from "./domEditing";
@@ -382,15 +384,18 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
       selection &&
       !usePlayerStore.getState().autoKeyframeEnabled
     ) {
+      const writes = observeGsapGesture((_sel, mutation, options) =>
+        commitMutation(mutation, options),
+      );
       void commitWholePropertyOffset(
         selection,
         anim,
         { x, y },
         d.ref.pct,
         iframeRef.current,
-        { commitMutation: (_sel, mutation, options) => commitMutation(mutation, options) },
+        { commitMutation: writes.commit! },
         "Move animation path",
-      );
+      ).then(() => trackPreviewEditResult("motion_path", "drag", writes.finish()));
     } else {
       void commitNode(d.ref, x, y, animId, commitMutation);
     }

package/src/components/editor/PropertyPanelEmptyState.tsx

@@ -1,6 +1,7 @@
 import { Eye, Layers } from "../../icons/SystemIcons";
 import type { DomEditSelection } from "./domEditingTypes";
 import { canHideSelections } from "../../utils/timelineInspector";
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
 
 function FlatEmptyState() {
   return (
@@ -71,6 +72,7 @@ function FlatMultiSelectState({
   // One predicate for both actions and for the handler's own refusal, so the
   // button and the refusal cannot disagree about what audio is.
   const hasAudio = !canHideSelections(multiSelectedElements);
+  const trackInput = useTrackDesignInput();
   return (
     <div className="flex flex-col gap-3 px-4 py-3">
       <div className="flex items-center gap-3 rounded-xl border border-panel-border bg-panel-surface p-3">
@@ -141,7 +143,11 @@ function FlatMultiSelectState({
           <button
             type="button"
             data-flat-multiselect-group="true"
-            onClick={onGroupSelection}
+            onClick={() => {
+              if (!onGroupSelection) return;
+              onGroupSelection();
+              trackInput("button", "group-selection");
+            }}
             className="flex h-[34px] flex-1 items-center justify-center gap-2 rounded-lg bg-panel-hover text-[11px] font-semibold text-panel-text-0"
           >
             <Layers size={13} />
@@ -150,7 +156,11 @@ function FlatMultiSelectState({
           <button
             type="button"
             data-flat-multiselect-hide-all="true"
-            onClick={onHideAllSelected}
+            onClick={() => {
+              if (!onHideAllSelected) return;
+              onHideAllSelected();
+              trackInput("button", "hide-all");
+            }}
             className="flex h-[34px] items-center gap-1.5 rounded-lg border border-panel-border-input bg-panel-input px-3 text-[11px] font-medium text-panel-text-2"
           >
             <Eye size={13} />

package/src/components/editor/SnapToolbar.test.tsx

@@ -1,8 +1,9 @@
+import { trackStudioEvent } from "../../utils/studioTelemetry";
 // @vitest-environment happy-dom
 
 import React, { act, useRef } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useAppHotkeys } from "../../hooks/useAppHotkeys";
 import { usePlayerStore } from "../../player/store/playerStore";
 import type { DomEditSelection } from "./domEditing";
@@ -182,3 +183,101 @@ describe("SnapToolbar ruler and safe-margin toggles", () => {
     act(() => root.unmount());
   });
 });
+
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+beforeEach(() => vi.clearAllMocks());
+describe("preview setting usage", () => {
+  it.each([
+    ["Toggle snap", "snapping"],
+    ["Toggle grid", "grid"],
+    ["Toggle ruler", "ruler"],
+    ["Toggle safe margins", "safe_margins"],
+  ])("counts the %s button without setting values", (label, feature) => {
+    const { root } = renderToolbar();
+    const button = document.querySelector<HTMLButtonElement>(`[aria-label="${label}"]`)!;
+    act(() => button.click());
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature,
+      surface: "preview",
+      method: "button",
+    });
+    act(() => root.unmount());
+  });
+  it("counts keyboard grid toggling once", () => {
+    const { root } = renderToolbar();
+    act(() => document.dispatchEvent(new KeyboardEvent("keydown", { key: "g", bubbles: true })));
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: "grid",
+      surface: "preview",
+      method: "keyboard",
+    });
+    act(() => root.unmount());
+  });
+});
+
+describe("preview field and key gesture counting", () => {
+  it("counts a grid spacing edit once when the field settles", () => {
+    const { root } = renderToolbar();
+    act(() => document.querySelector<HTMLButtonElement>('[aria-label="Grid options"]')!.click());
+    const input = document.querySelector<HTMLInputElement>('input[type="number"]')!;
+    const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!;
+    act(() => input.focus());
+    for (const value of ["20", "200"]) {
+      act(() => {
+        setter.call(input, value);
+        input.dispatchEvent(new Event("input", { bubbles: true }));
+      });
+    }
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+    act(() => input.blur());
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: "grid_spacing",
+      surface: "preview",
+      method: "field",
+    });
+    act(() => root.unmount());
+  });
+  it("counts snap-to-grid through its committed checkbox", () => {
+    const { root } = renderToolbar();
+    act(() => document.querySelector<HTMLButtonElement>('[aria-label="Grid options"]')!.click());
+    act(() => document.querySelector<HTMLInputElement>('input[type="checkbox"]')!.click());
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: "snap_to_grid",
+      surface: "preview",
+      method: "button",
+    });
+    act(() => root.unmount());
+  });
+  it.each(["s", "g"])("does not count auto-repeat as another %s key gesture", (key) => {
+    const { root } = renderToolbar();
+    act(() => document.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true })));
+    act(() =>
+      document.dispatchEvent(new KeyboardEvent("keydown", { key, repeat: true, bubbles: true })),
+    );
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: key === "s" ? "snapping" : "grid",
+      surface: "preview",
+      method: "keyboard",
+    });
+    act(() => root.unmount());
+  });
+});
+
+it("counts a changed field when click-away dismisses it before blur", () => {
+  const { root } = renderToolbar();
+  act(() => document.querySelector<HTMLButtonElement>('[aria-label="Grid options"]')!.click());
+  const input = document.querySelector<HTMLInputElement>('input[type="number"]')!;
+  act(() => input.focus());
+  act(() => {
+    Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(input, "230");
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+  });
+  act(() => document.body.dispatchEvent(new MouseEvent("mousedown", { bubbles: true })));
+  expect(document.querySelector('input[type="number"]')).toBeNull();
+  expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+    feature: "grid_spacing",
+    surface: "preview",
+    method: "field",
+  });
+  act(() => root.unmount());
+});

package/src/components/editor/SnapToolbar.tsx

@@ -1,3 +1,4 @@
+import { trackPreviewFeatureUsed } from "../../utils/previewFeatureUsage";
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { MagnetStraight, GridFour, Path, Ruler, FrameCorners } from "@phosphor-icons/react";
 import { usePlayerStore } from "../../player/store/playerStore";
@@ -16,6 +17,16 @@ export const SnapToolbar = memo(function SnapToolbar() {
   const setMotionPathArmed = usePlayerStore((s) => s.setMotionPathArmed);
   const popoverRef = useRef<HTMLDivElement>(null);
   const gridButtonRef = useRef<HTMLButtonElement>(null);
+  const gridSpacingAtFocus = useRef<number | null>(null);
+  const currentGridSpacing = useRef(prefs.gridSpacing);
+  currentGridSpacing.current = prefs.gridSpacing;
+  const settleGridSpacing = useCallback(() => {
+    const previous = gridSpacingAtFocus.current;
+    gridSpacingAtFocus.current = null;
+    if (previous !== null && previous !== currentGridSpacing.current)
+      trackPreviewFeatureUsed("grid_spacing", "field");
+  }, []);
+  useEffect(() => settleGridSpacing, [settleGridSpacing]);
 
   const updatePrefs = useCallback(
     (patch: Partial<typeof prefs>) => {
@@ -26,10 +37,12 @@ export const SnapToolbar = memo(function SnapToolbar() {
 
   const toggleSnap = useCallback(() => {
     updatePrefs({ snapEnabled: !prefs.snapEnabled });
+    trackPreviewFeatureUsed("snapping", "button");
   }, [prefs.snapEnabled, updatePrefs]);
 
   const toggleGrid = useCallback(() => {
     updatePrefs({ gridVisible: !prefs.gridVisible });
+    trackPreviewFeatureUsed("grid", "button");
   }, [prefs.gridVisible, updatePrefs]);
 
   useEffect(() => {
@@ -41,10 +54,12 @@ export const SnapToolbar = memo(function SnapToolbar() {
       if (e.key === "s" && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
         updatePrefs({ snapEnabled: !prefs.snapEnabled });
+        if (!e.repeat) trackPreviewFeatureUsed("snapping", "keyboard");
       }
       if (e.key === "g" && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
         updatePrefs({ gridVisible: !prefs.gridVisible });
+        if (!e.repeat) trackPreviewFeatureUsed("grid", "keyboard");
       }
     };
     document.addEventListener("keydown", handleKeyDown);
@@ -56,11 +71,12 @@ export const SnapToolbar = memo(function SnapToolbar() {
     const handleClickOutside = (e: MouseEvent) => {
       const target = e.target as Node;
       if (popoverRef.current?.contains(target) || gridButtonRef.current?.contains(target)) return;
+      settleGridSpacing();
       setGridPopoverOpen(false);
     };
     document.addEventListener("mousedown", handleClickOutside);
     return () => document.removeEventListener("mousedown", handleClickOutside);
-  }, [gridPopoverOpen]);
+  }, [gridPopoverOpen, settleGridSpacing]);
 
   return (
     <div
@@ -101,7 +117,10 @@ export const SnapToolbar = memo(function SnapToolbar() {
                 ? "bg-studio-accent/20 text-accent-ink"
                 : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
             }`}
-            onClick={toggle}
+            onClick={() => {
+              toggle();
+              trackPreviewFeatureUsed(key === "rulerVisible" ? "ruler" : "safe_margins", "button");
+            }}
             title={`${label} ${visible ? "on" : "off"}`}
             aria-label={`Toggle ${label.toLowerCase()}`}
             aria-pressed={visible}
@@ -136,6 +155,7 @@ export const SnapToolbar = memo(function SnapToolbar() {
           onClick={toggleGrid}
           onContextMenu={(e) => {
             e.preventDefault();
+            if (gridPopoverOpen) settleGridSpacing();
             setGridPopoverOpen((v) => !v);
           }}
           title={
@@ -150,7 +170,10 @@ export const SnapToolbar = memo(function SnapToolbar() {
         <button
           type="button"
           className="absolute -right-0.5 -bottom-0.5 rounded-sm p-0.5 text-white/50 hover:text-white/90 bg-black/50"
-          onClick={() => setGridPopoverOpen((v) => !v)}
+          onClick={() => {
+            if (gridPopoverOpen) settleGridSpacing();
+            setGridPopoverOpen((v) => !v);
+          }}
           title="Grid options"
           aria-label="Grid options"
           aria-expanded={gridPopoverOpen}
@@ -173,9 +196,21 @@ export const SnapToolbar = memo(function SnapToolbar() {
                 max={500}
                 step={10}
                 value={prefs.gridSpacing}
+                onFocus={() => {
+                  gridSpacingAtFocus.current = prefs.gridSpacing;
+                }}
+                onBlur={settleGridSpacing}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") e.currentTarget.blur();
+                }}
                 onChange={(e) => {
                   const val = Number.parseInt(e.target.value, 10);
-                  if (Number.isFinite(val) && val >= 10 && val <= 500) {
+                  if (
+                    Number.isFinite(val) &&
+                    val >= 10 &&
+                    val <= 500 &&
+                    val !== prefs.gridSpacing
+                  ) {
                     updatePrefs({ gridSpacing: val });
                   }
                 }}
@@ -186,7 +221,10 @@ export const SnapToolbar = memo(function SnapToolbar() {
               <input
                 type="checkbox"
                 checked={prefs.snapToGrid}
-                onChange={() => updatePrefs({ snapToGrid: !prefs.snapToGrid })}
+                onChange={() => {
+                  updatePrefs({ snapToGrid: !prefs.snapToGrid });
+                  trackPreviewFeatureUsed("snap_to_grid", "button");
+                }}
                 className="accent-studio-accent"
               />
               <span>Snap to grid</span>