Skip to content

Write HTML. Render video. Built for agents.

feat(studio): track completed preview editing gestures (#4916)

Miguel Ángel852782bbb0e1
diff --git a/packages/studio-server/src/routes/files.test.ts b/packages/studio-server/src/routes/files.test.ts
index bb60b5b7cc..de2deb0c7c 100644
--- a/packages/studio-server/src/routes/files.test.ts
+++ b/packages/studio-server/src/routes/files.test.ts
@@ -1496,6 +1496,44 @@ tl.fromTo("#box", { opacity: 0, x: -50 }, { opacity: 1, x: 0, duration: 1.5, eas
expect(result.parsed.animations[0].fromProperties).toMatchObject({ opacity: 0.2, x: -25 });
});
+ it("reports a no-op keyframe member separately from a changed batch member", async () => {
+ const projectDir = createProjectDir();
+ writeHtml(
+ projectDir,
+ "comp.html",
+ `<script>const tl = gsap.timeline();tl.to("#box", {keyframes: {"0%": {x: 0}, "100%": {x: 100}}, duration: 2}, 0);</script>`,
+ );
+ const app = new Hono();
+ registerFileRoutes(app, createAdapter(projectDir));
+ const anim = await getFirstAnimation(app, "comp.html");
+ const add = {
+ type: "add-keyframe",
+ animationId: anim.id,
+ percentage: 50,
+ properties: { x: 50 },
+ };
+ const seed = await postGsapMutationBatch(app, "comp.html", { mutations: [add] });
+ expect(seed.status).toBe(200);
+ const seeded = await getFirstAnimation(app, "comp.html");
+ const response = await postGsapMutationBatch(app, "comp.html", {
+ mutations: [
+ { ...add, animationId: seeded.id },
+ { type: "update-meta", animationId: seeded.id, updates: { duration: 3 } },
+ ],
+ });
+ expect(response.status).toBe(200);
+ const result = (await response.json()) as {
+ changed: boolean;
+ mutationChanges: boolean[];
+ after: string;
+ };
+ expect(result).toMatchObject({ changed: true, mutationChanges: [false, true] });
+ expect(result.after).toBe(readFileSync(join(projectDir, "comp.html"), "utf-8"));
+ expect(result).toMatchObject({
+ parsed: { animations: [expect.objectContaining({ duration: 3 })] },
+ });
+ });
+
it("conditionally restores the exact GSAP mutation output", async () => {
const projectDir = createProjectDir();
writeHtml(projectDir, "comp.html", "MUTATED");
diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts
index 3e78a854de..6dcafa22db 100644
--- a/packages/studio-server/src/routes/files.ts
+++ b/packages/studio-server/src/routes/files.ts
@@ -1467,7 +1467,9 @@ async function applyGsapMutations(
return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
}
+ const mutationChanges: boolean[] = [];
for (const mutation of mutations) {
+ const previousScript = block.scriptText;
const result = await executeGsapMutation(mutation, block, respond, writer);
if (result instanceof Response) return result;
let newScript = typeof result === "string" ? result : result.script;
@@ -1480,6 +1482,7 @@ async function applyGsapMutations(
? syncPositionHoldsBeforeKeyframes(newScript)
: (await loadGsapParser()).syncPositionHoldsBeforeKeyframes(newScript);
}
+ mutationChanges.push(newScript !== previousScript);
block.scriptText = newScript;
}
@@ -1509,6 +1512,7 @@ async function applyGsapMutations(
ok: true,
changed,
mutated: changed,
+ mutationChanges,
parsed: parseGsapScriptAcorn(block.scriptText),
before: beforeHtml,
after: newHtml,
diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsx
index 810506c6c1..147b3c299c 100644
--- a/packages/studio/src/App.tsx
+++ b/packages/studio/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({
diff --git a/packages/studio/src/components/editor/DomEditCropHandles.test.tsx b/packages/studio/src/components/editor/DomEditCropHandles.test.tsx
index 0357a5b5b1..f574f821ef 100644
--- a/packages/studio/src/components/editor/DomEditCropHandles.test.tsx
+++ b/packages/studio/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());
+ },
+ );
+});
diff --git a/packages/studio/src/components/editor/DomEditCropHandles.tsx b/packages/studio/src/components/editor/DomEditCropHandles.tsx
index 6ec3d5a322..3a7f07456e 100644
--- a/packages/studio/src/components/editor/DomEditCropHandles.tsx
+++ b/packages/studio/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>) => {
diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
index 4a1976d4bf..95636a4fec 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.tsx
+++ b/packages/studio/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 —
diff --git a/packages/studio/src/components/editor/MotionPathOverlay.tsx b/packages/studio/src/components/editor/MotionPathOverlay.tsx
index eeaa18824b..b66c1361ba 100644
--- a/packages/studio/src/components/editor/MotionPathOverlay.tsx
+++ b/packages/studio/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);
}
diff --git a/packages/studio/src/components/editor/PropertyPanelEmptyState.tsx b/packages/studio/src/components/editor/PropertyPanelEmptyState.tsx
index 4890b7deb6..dbbb45f864 100644
--- a/packages/studio/src/components/editor/PropertyPanelEmptyState.tsx
+++ b/packages/studio/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} />
diff --git a/packages/studio/src/components/editor/SnapToolbar.test.tsx b/packages/studio/src/components/editor/SnapToolbar.test.tsx
index 00e9c01f1f..461fa94eef 100644
--- a/packages/studio/src/components/editor/SnapToolbar.test.tsx
+++ b/packages/studio/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());
+});
diff --git a/packages/studio/src/components/editor/SnapToolbar.tsx b/packages/studio/src/components/editor/SnapToolbar.tsx
index a92d025059..a91995d3e9 100644
--- a/packages/studio/src/components/editor/SnapToolbar.tsx
+++ b/packages/studio/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>
diff --git a/packages/studio/src/components/editor/anchoredResizeCommitFeedsOffset.test.ts b/packages/studio/src/components/editor/anchoredResizeCommitFeedsOffset.test.ts
index 1e065adc33..908275e01c 100644
--- a/packages/studio/src/components/editor/anchoredResizeCommitFeedsOffset.test.ts
+++ b/packages/studio/src/components/editor/anchoredResizeCommitFeedsOffset.test.ts
@@ -1,6 +1,8 @@
// @vitest-environment happy-dom
import { afterEach, describe, expect, it, vi } from "vitest";
+import { trackStudioEvent } from "../../utils/studioTelemetry";
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
import type { DomEditSelection } from "./domEditing";
import type { GestureState, UseDomEditOverlayGesturesOptions } from "./domEditOverlayGestures";
@@ -178,7 +180,7 @@ function buildHarness(
};
const handlers = createDomEditOverlayGestureHandlers(opts);
- return { handlers, commits, selection };
+ return { handlers, commits, selection, opts };
}
type OverlayRectLike = {
@@ -287,3 +289,48 @@ describe("anchored corner resize — the release commit feeds the center-pin off
expect(consoleError).toHaveBeenCalledWith("resize commit failed", failure);
});
});
+
+describe("resize usage at pointer release", () => {
+ it("counts one completed resize despite multiple pointer moves", async () => {
+ vi.mocked(trackStudioEvent).mockClear();
+ const h = buildHarness(async () => ({ ok: true, changed: true }));
+ await finishResize(h.handlers);
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+ feature: "resize",
+ surface: "preview",
+ method: "drag",
+ });
+ });
+ it.each([undefined, { ok: true as const, changed: false }])(
+ "does not count an unchanged or unconfirmed resize",
+ async (result) => {
+ vi.mocked(trackStudioEvent).mockClear();
+ const h = buildHarness(async () => result);
+ await finishResize(h.handlers);
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ },
+ );
+});
+
+describe("move and rotation usage", () => {
+ it.each(["drag", "rotate"] as const)("counts %s once after pointer release", async (kind) => {
+ vi.mocked(trackStudioEvent).mockClear();
+ const h = buildHarness();
+ h.selection.capabilities.canApplyManualRotation = true;
+ const saved = vi.fn(async () => ({ ok: true as const, changed: true }));
+ h.opts.onPathOffsetCommitRef.current = saved;
+ h.opts.onRotationCommitRef.current = saved;
+ h.handlers.startGesture(kind, evt(200, 50));
+ h.handlers.onPointerMove(evt(150, 120));
+ h.handlers.onPointerMove(evt(100, 150));
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ h.handlers.onPointerUp(evt(100, 150));
+ await Promise.resolve();
+ expect(saved).toHaveBeenCalledTimes(1);
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+ feature: kind === "drag" ? "move" : "rotate",
+ surface: "preview",
+ method: "drag",
+ });
+ });
+});
diff --git a/packages/studio/src/components/editor/audioFxTelemetry.ts b/packages/studio/src/components/editor/audioFxTelemetry.ts
index 2ec5b9a16d..ec2a9175f5 100644
--- a/packages/studio/src/components/editor/audioFxTelemetry.ts
+++ b/packages/studio/src/components/editor/audioFxTelemetry.ts
@@ -10,9 +10,8 @@
* filenames, not composition paths, not chain JSON. Every property below is
* either a fixed identifier from our own catalogue (a preset id, an effect
* type, a parameter key), a number, or a boolean. `studioTelemetry.ts` already
- * strips the query string off `url_hash` for exactly this reason — the ids in
- * it are the author's own. The rack sees the same class of data and must hold
- * the same line.
+ * sends only a route kind in `url_hash` for the same reason. The rack sees
+ * the same class of data and must hold the same line.
*
* The second rule is about volume: **commit, not preview.** Every control in
* the rack has a preview path that fires continuously while a slider moves and
diff --git a/packages/studio/src/components/editor/commitPreflightHandles.test.tsx b/packages/studio/src/components/editor/commitPreflightHandles.test.tsx
index 6e680f66f8..c772626c9a 100644
--- a/packages/studio/src/components/editor/commitPreflightHandles.test.tsx
+++ b/packages/studio/src/components/editor/commitPreflightHandles.test.tsx
@@ -287,7 +287,7 @@ describe("handles follow what Studio would commit", () => {
{ x: 0, y: 0 },
commitList,
preview,
- vi.fn(),
+ vi.fn(async () => undefined),
undefined,
preflightOnly,
);
@@ -401,7 +401,7 @@ describe("handles follow what Studio would commit", () => {
{ x: 0, y: 0 },
[stagger],
preview,
- vi.fn(),
+ vi.fn(async () => undefined),
undefined,
groupPreflight,
);
diff --git a/packages/studio/src/components/editor/cropResize.ts b/packages/studio/src/components/editor/cropResize.ts
index 306e984b07..72b350f0db 100644
--- a/packages/studio/src/components/editor/cropResize.ts
+++ b/packages/studio/src/components/editor/cropResize.ts
@@ -1,3 +1,4 @@
+import type { DomEditPersistOutcome } from "../../hooks/domEditCommitTypes";
import type { PatchOperation } from "../../utils/sourcePatcher";
import type { CommitMutation } from "../../hooks/gsapScriptCommitTypes";
import type { DomEditSelection } from "./domEditingTypes";
@@ -94,7 +95,7 @@ type PatchCommit = (
selection: DomEditSelection,
patches: PatchOperation[],
options: { label: string; coalesceKey: string; coalesceMs?: number },
-) => Promise<void>;
+) => Promise<DomEditPersistOutcome | undefined>;
/** Stage the crop and save it under the resize's undo key, taking it back off the element if that fails. */
export async function saveCropResize(
@@ -102,11 +103,11 @@ export async function saveCropResize(
selection: DomEditSelection,
commit: PatchCommit,
coalesceKey: string,
-): Promise<void> {
+): Promise<DomEditPersistOutcome | undefined> {
const crop = stage();
if (!crop) return;
try {
- await commit(selection, [crop.patch], {
+ return await commit(selection, [crop.patch], {
label: "Resize layer",
coalesceKey,
coalesceMs: Number.POSITIVE_INFINITY,
diff --git a/packages/studio/src/components/editor/marqueeCommit.test.tsx b/packages/studio/src/components/editor/marqueeCommit.test.tsx
index 8586f15e0a..e7a9a81477 100644
--- a/packages/studio/src/components/editor/marqueeCommit.test.tsx
+++ b/packages/studio/src/components/editor/marqueeCommit.test.tsx
@@ -1,10 +1,14 @@
// @vitest-environment happy-dom
-import { act, useRef } from "react";
+import { act, useRef, type RefObject } from "react";
import type { Root } from "react-dom/client";
import { afterEach, beforeEach, expect, it, vi } from "vitest";
import { installReactActEnvironment, mountReactHarness } from "../../hooks/domSelectionTestHarness";
+import { trackStudioEvent } from "../../utils/studioTelemetry";
+import type { DomSelectionResult } from "../../hooks/useDomSelectionTypes";
import { useMarqueeGestures } from "./marqueeCommit";
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
// Layout stands in for a real preview: every element is visible and sits at the band's start.
vi.mock("./domEditingElement", async (importOriginal) => ({
...(await importOriginal<typeof import("./domEditingElement")>()),
@@ -40,9 +44,53 @@ function Overlay() {
);
}
-const pointer = (type: string, clientX: number, clientY: number) =>
+function MarqueeSurface({
+ overlayRef,
+ marquee,
+}: {
+ overlayRef: RefObject<HTMLDivElement | null>;
+ marquee: ReturnType<typeof useMarqueeGestures>;
+}) {
+ return (
+ <div
+ ref={overlayRef}
+ data-band-overlay
+ onPointerDown={marquee.begin}
+ onPointerMove={marquee.onPointerMove}
+ onPointerUp={marquee.onPointerUp}
+ />
+ );
+}
+
+function TestMarquee({
+ iframeRef,
+ onSelect,
+ resolveHits,
+}: {
+ iframeRef: RefObject<HTMLIFrameElement | null>;
+ onSelect: (selections: HTMLElement[], additive: boolean) => DomSelectionResult | void;
+ resolveHits: (elements: HTMLElement[]) => HTMLElement[] | Promise<HTMLElement[]>;
+}) {
+ const overlayRef = useRef<HTMLDivElement>(null);
+ const marquee = useMarqueeGestures({
+ iframeRef,
+ overlayRef,
+ activeCompositionPathRef: useRef<string | null>("index.html"),
+ onMarqueeSelectRef: { current: onSelect },
+ resolveHits,
+ });
+ return <MarqueeSurface overlayRef={overlayRef} marquee={marquee} />;
+}
+
+const pointer = (
+ type: string,
+ clientX: number,
+ clientY: number,
+ selector = "[data-overlay]",
+ shiftKey = false,
+) =>
act(() => {
- document.querySelector("[data-overlay]")!.dispatchEvent(
+ document.querySelector(selector)!.dispatchEvent(
new PointerEvent(type, {
bubbles: true,
buttons: type === "pointerup" ? 0 : 1,
@@ -50,6 +98,7 @@ const pointer = (type: string, clientX: number, clientY: number) =>
pointerId: 1,
clientX,
clientY,
+ shiftKey,
}),
);
});
@@ -68,6 +117,7 @@ const hostListener = (e: KeyboardEvent) => {
};
beforeEach(() => {
+ vi.clearAllMocks();
hostEscapes = [];
window.addEventListener("keydown", hostListener);
root = mountReactHarness(<Overlay />);
@@ -128,42 +178,17 @@ it("a reload promoted mid-band selects from the preview on screen, not the retir
const [retired, live] = [preview(), preview()];
const picked: HTMLElement[][] = [];
const iframeRef = { current: retired as HTMLIFrameElement | null };
- function Band() {
- const overlayRef = useRef<HTMLDivElement>(null);
- const marquee = useMarqueeGestures({
- iframeRef,
- overlayRef,
- activeCompositionPathRef: useRef<string | null>("index.html"),
- onMarqueeSelectRef: useRef(() => undefined),
- resolveHits: async (elements: HTMLElement[]) => {
+ const band = mountReactHarness(
+ <TestMarquee
+ iframeRef={iframeRef}
+ onSelect={() => undefined}
+ resolveHits={async (elements) => {
picked.push(elements);
return [];
- },
- });
- return (
- <div
- ref={overlayRef}
- data-band-overlay
- onPointerDown={marquee.begin}
- onPointerMove={marquee.onPointerMove}
- onPointerUp={marquee.onPointerUp}
- />
- );
- }
- const band = mountReactHarness(<Band />);
- const fire = (type: string, x: number, y: number) =>
- act(() => {
- document.querySelector("[data-band-overlay]")!.dispatchEvent(
- new PointerEvent(type, {
- bubbles: true,
- button: 0,
- buttons: type === "pointerup" ? 0 : 1,
- pointerId: 1,
- clientX: x,
- clientY: y,
- }),
- );
- });
+ }}
+ />,
+ );
+ const fire = (type: string, x: number, y: number) => pointer(type, x, y, "[data-band-overlay]");
try {
fire("pointerdown", 0, 0);
fire("pointermove", 120, 90);
@@ -175,3 +200,47 @@ it("a reload promoted mid-band selects from the preview on screen, not the retir
act(() => band.unmount());
}
});
+
+it.each([
+ [2, false, 2, 0],
+ [1, true, 2, 1],
+ [2, true, 2, 1],
+ [1, true, 1, 0],
+])(
+ "counts marquee receipt: %s hits, changed=%s, group=%s",
+ async (hits, changed, count, events) => {
+ const iframe = document.createElement("iframe");
+ const doc = document.implementation.createHTMLDocument("preview");
+ doc.body.innerHTML =
+ '<div data-composition-id="main"><h1 id="title">Title</h1><p id="subtitle">Subtitle</p></div>';
+ Object.defineProperty(iframe, "contentDocument", { value: doc });
+ const apply = vi.fn((_selections: HTMLElement[], _additive: boolean) => ({ changed, count }));
+ const band = mountReactHarness(
+ <TestMarquee
+ iframeRef={{ current: iframe }}
+ onSelect={apply}
+ resolveHits={(elements) => elements.slice(0, hits)}
+ />,
+ );
+ const fire = (type: string, x: number, y: number) =>
+ pointer(type, x, y, "[data-band-overlay]", true);
+ try {
+ fire("pointerdown", 0, 0);
+ fire("pointermove", 120, 90);
+ await act(async () => {
+ fire("pointerup", 120, 90);
+ });
+ expect(apply).toHaveBeenCalledTimes(1);
+ expect(apply.mock.calls[0]![0]).toHaveLength(hits);
+ expect(trackStudioEvent).toHaveBeenCalledTimes(events);
+ if (events)
+ expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+ feature: "multi_select",
+ surface: "preview",
+ method: "drag",
+ });
+ } finally {
+ act(() => band.unmount());
+ }
+ },
+);
diff --git a/packages/studio/src/components/editor/marqueeCommit.ts b/packages/studio/src/components/editor/marqueeCommit.ts
index d00194dd63..44f74a4d22 100644
--- a/packages/studio/src/components/editor/marqueeCommit.ts
+++ b/packages/studio/src/components/editor/marqueeCommit.ts
@@ -1,3 +1,5 @@
+import type { DomSelectionResult } from "../../hooks/useDomSelectionTypes";
+import { trackPreviewFeatureUsed } from "../../utils/previewFeatureUsage";
// fallow-ignore-file code-duplication
import { useCallback, useEffect, useRef, useState } from "react";
import type { DomEditSelection } from "./domEditing";
@@ -18,6 +20,16 @@ interface MarqueeState {
target: Element;
}
+function currentMarqueeCandidates(
+ cached: MarqueeHit[] | null,
+ iframe: HTMLIFrameElement,
+ overlay: HTMLDivElement,
+ path: string,
+): MarqueeHit[] {
+ if (cached?.every((hit) => hit.element.ownerDocument === iframe.contentDocument)) return cached;
+ return collectMarqueeCandidates(iframe, overlay, path);
+}
+
const MARQUEE_THRESHOLD_PX = 4;
interface MarqueeHit {
@@ -103,7 +115,9 @@ export interface MarqueeGesturesDeps<T = DomEditSelection> {
iframeRef: React.RefObject<HTMLIFrameElement | null>;
overlayRef: React.RefObject<HTMLDivElement | null>;
activeCompositionPathRef: React.RefObject<string | null>;
- onMarqueeSelectRef: React.RefObject<((selections: T[], additive: boolean) => void) | undefined>;
+ onMarqueeSelectRef: React.RefObject<
+ ((selections: T[], additive: boolean) => DomSelectionResult | void) | undefined
+ >;
/** Turns the elements a drag touched into picks; without it, Studio's edit selections. */
resolveHits?: (elements: HTMLElement[]) => T[] | Promise<T[]>;
selectionRef?: React.RefObject<DomEditSelection | null>;
@@ -127,6 +141,10 @@ export interface MarqueeGestures {
onPointerCancel: () => void;
}
+function trackMarqueeSelection(result: DomSelectionResult | void): void {
+ if (result?.changed && result.count > 1) trackPreviewFeatureUsed("multi_select", "drag");
+}
+
function releaseCapture(m: MarqueeState): void {
try {
m.target.releasePointerCapture(m.pointerId);
@@ -160,18 +178,16 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
const overlay = deps.overlayRef.current;
if (!iframe || !overlay || !deps.onMarqueeSelectRef.current) return;
const acp = deps.activeCompositionPathRef.current ?? "index.html";
- const cached = candidatesRef.current;
- const measuredOnScreen = cached?.every(
- (hit) => hit.element.ownerDocument === iframe.contentDocument,
- );
- const candidates =
- cached && measuredOnScreen ? cached : collectMarqueeCandidates(iframe, overlay, acp);
+ const candidates = currentMarqueeCandidates(candidatesRef.current, iframe, overlay, acp);
const elements = hitsWithin(rect, candidates).map((hit) => hit.element);
const resolveHits = deps.resolveHits;
const picks = resolveHits
? await resolveHits(elements)
: ((await resolveDomEditSelections(elements, acp)) as T[]);
- deps.onMarqueeSelectRef.current?.(picks, additive);
+ const applySelection = deps.onMarqueeSelectRef.current;
+ if (!applySelection) return;
+ const result = applySelection(picks, additive);
+ trackMarqueeSelection(result);
},
[
deps.iframeRef,
diff --git a/packages/studio/src/components/editor/motionPathCommit.test.ts b/packages/studio/src/components/editor/motionPathCommit.test.ts
index 1b91c20c21..8c4cfab108 100644
--- a/packages/studio/src/components/editor/motionPathCommit.test.ts
+++ b/packages/studio/src/components/editor/motionPathCommit.test.ts
@@ -1,5 +1,5 @@
// @vitest-environment jsdom
-import { describe, it, expect, vi } from "vitest";
+import { beforeEach, describe, it, expect, vi } from "vitest";
import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
import { editableAnimationId } from "./motionPathSelection";
import {
@@ -148,3 +148,31 @@ describe("commitCreatePath", () => {
);
});
});
+
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../../utils/studioTelemetry";
+import type { CommitFn } from "./motionPathCommit";
+beforeEach(() => vi.clearAllMocks());
+describe("motion path usage at the writer", () => {
+ it("counts a changed drag once without coordinates or target ids", async () => {
+ const commit: CommitFn = async (_mutation, options) => {
+ options.onResult?.({ ok: true, changed: true });
+ };
+ await commitNode({ type: "keyframe", pct: 50 }, 120, 30, "private-target", commit);
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+ feature: "motion_path",
+ surface: "preview",
+ method: "drag",
+ });
+ });
+ it.each([undefined, { ok: true }, { ok: true, changed: false }, { ok: false, changed: true }])(
+ "does not count absent or unsuccessful results (%j)",
+ async (result) => {
+ const commit: CommitFn = async (_mutation, options) => {
+ if (result) options.onResult?.(result);
+ };
+ await commitAddWaypoint("private-target", 1, 20, 40, commit);
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ },
+ );
+});
diff --git a/packages/studio/src/components/editor/motionPathCommit.ts b/packages/studio/src/components/editor/motionPathCommit.ts
index 53a7c0fcf9..3b1b6a7eab 100644
--- a/packages/studio/src/components/editor/motionPathCommit.ts
+++ b/packages/studio/src/components/editor/motionPathCommit.ts
@@ -1,3 +1,5 @@
+import type { CommitMutationOptions } from "../../hooks/gsapScriptCommitTypes";
+import { trackPreviewFeatureUsed, type PreviewMethod } from "../../utils/previewFeatureUsage";
/**
* Commit helpers for the motion-path overlay. Each maps a canvas gesture to a
* GSAP source mutation routed through the (selection-bound) commit facade, which
@@ -7,11 +9,21 @@ import type { MotionNodeRef } from "./motionPathGeometry";
export type CommitFn = (
mutation: Record<string, unknown>,
- options: { label: string; softReload?: boolean },
+ options: CommitMutationOptions,
) => Promise<void>;
const NEW_PATH_DURATION = 1.5;
+function motionPathCommitOptions(label: string, method: PreviewMethod): CommitMutationOptions {
+ return {
+ label,
+ softReload: true,
+ onResult: (result) => {
+ if (result.ok && result.changed === true) trackPreviewFeatureUsed("motion_path", method);
+ },
+ };
+}
+
export function commitNode(
ref: MotionNodeRef,
x: number,
@@ -23,10 +35,10 @@ export function commitNode(
ref.type === "keyframe"
? { type: "update-keyframe", animationId, percentage: ref.pct, properties: { x, y } }
: { type: "update-motion-path-point", animationId, pointIndex: ref.index, x, y };
- return commit(mutation, {
- label: ref.type === "keyframe" ? "Move keyframe" : "Move waypoint",
- softReload: true,
- });
+ return commit(
+ mutation,
+ motionPathCommitOptions(ref.type === "keyframe" ? "Move keyframe" : "Move waypoint", "drag"),
+ );
}
export function commitAddWaypoint(
@@ -38,7 +50,7 @@ export function commitAddWaypoint(
): Promise<void> {
return commit(
{ type: "add-motion-path-point", animationId, index, x, y },
- { label: "Add waypoint", softReload: true },
+ motionPathCommitOptions("Add waypoint", "button"),
);
}
@@ -54,7 +66,7 @@ export function commitAddKeyframe(
// at that pct) and converts a flat tween to keyframes form when needed.
return commit(
{ type: "add-keyframe", animationId, percentage, properties: { x, y } },
- { label: "Add keyframe", softReload: true },
+ motionPathCommitOptions("Add keyframe", "button"),
);
}
@@ -65,7 +77,7 @@ export function commitRemoveWaypoint(
): Promise<void> {
return commit(
{ type: "remove-motion-path-point", animationId, index },
- { label: "Remove waypoint", softReload: true },
+ motionPathCommitOptions("Remove waypoint", "button"),
);
}
@@ -78,6 +90,6 @@ export function commitCreatePath(
): Promise<void> {
return commit(
{ type: "add-motion-path", targetSelector, position, duration: NEW_PATH_DURATION, x, y },
- { label: "Create motion path", softReload: true },
+ motionPathCommitOptions("Create motion path", "button"),
);
}
diff --git a/packages/studio/src/components/editor/propertyPanelFlatTextSection.tsx b/packages/studio/src/components/editor/propertyPanelFlatTextSection.tsx
index 3731734485..ea8d6838d2 100644
--- a/packages/studio/src/components/editor/propertyPanelFlatTextSection.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFlatTextSection.tsx
@@ -1,3 +1,4 @@
+import type { PropertyPanelProps } from "./propertyPanelTypes";
import { useEffect, useState } from "react";
import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
import { Plus, X } from "../../icons/SystemIcons";
@@ -246,13 +247,15 @@ export function FlatTextSection({
element: DomEditSelection;
styles: Record<string, string>;
fontAssets: ImportedFontAsset[];
- onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
- onSetText: (value: string, fieldKey?: string) => void;
- onSetTextFieldStyle: (fieldKey: string, property: string, value: string) => void;
- onPreviewTextFieldStyle?: (fieldKey: string, property: string, value: string) => void;
- onAddTextField: (afterFieldKey?: string) => string | Promise<string | null> | null;
- onRemoveTextField: (fieldKey: string) => void;
-}) {
+} & Pick<
+ PropertyPanelProps,
+ | "onImportFonts"
+ | "onSetText"
+ | "onSetTextFieldStyle"
+ | "onPreviewTextFieldStyle"
+ | "onAddTextField"
+ | "onRemoveTextField"
+>) {
const track = useTrackDesignInput();
const [activeFieldKey, setActiveFieldKey] = useState<string | null>(
element.textFields[0]?.key ?? null,
diff --git a/packages/studio/src/components/editor/propertyPanelFxAddMenu.tsx b/packages/studio/src/components/editor/propertyPanelFxAddMenu.tsx
index 44536055f7..e345252771 100644
--- a/packages/studio/src/components/editor/propertyPanelFxAddMenu.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxAddMenu.tsx
@@ -1,3 +1,4 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
* The add-effect shelf: Tone, the composite jobs, and the raw registry.
*
@@ -81,6 +82,7 @@ export function FxAddMenu({
withJob,
withEffect,
}: FxAddMenuProps) {
+ const trackInput = useTrackDesignInput();
return (
<div
className="hf-fx-add-menu space-y-1.5 rounded-[4px] border border-panel-border-input p-1.5"
@@ -108,8 +110,15 @@ export function FxAddMenu({
title="Listen to this track and even out its loud and quiet parts."
disabled={disabled || analysing}
onClick={() => {
- if (levelled) onRemoveLevel?.();
- else onLevel();
+ if (levelled) {
+ if (onRemoveLevel) {
+ onRemoveLevel();
+ trackInput("button", "remove-levelling");
+ }
+ } else {
+ onLevel();
+ trackInput("button", "add-levelling");
+ }
onClose();
}}
// The one module here that cannot answer instantly: it has to
diff --git a/packages/studio/src/components/editor/propertyPanelFxCarveModule.tsx b/packages/studio/src/components/editor/propertyPanelFxCarveModule.tsx
index 1357e6e32c..94536b9caa 100644
--- a/packages/studio/src/components/editor/propertyPanelFxCarveModule.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxCarveModule.tsx
@@ -1,3 +1,4 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
* The voiceover carve, as one module in the FX rack.
*
@@ -165,6 +166,7 @@ export function FxCarveModule({
onCarvePreview(carve: HfCarveSettings): void;
}) {
const on = carve.enabled;
+ const trackInput = useTrackDesignInput();
const soleVoice = soleCarveVoice(sourceOptions, carve.sources);
const summary = carveSummary({ nodes, carve, analysing });
// The carve's own colour, used three ways: the module's left edge, the title,
@@ -215,7 +217,10 @@ export function FxCarveModule({
aria-pressed={on}
title={on ? "Switch the carve off" : "Switch the carve on"}
disabled={disabled}
- onClick={() => onCarveChange({ ...carve, enabled: !on })}
+ onClick={() => {
+ onCarveChange({ ...carve, enabled: !on });
+ trackInput("toggle", "carve-enabled");
+ }}
>
{on ? "On" : "Off"}
</button>
@@ -250,7 +255,10 @@ export function FxCarveModule({
value={carve.strength}
disabled={disabled || carve.sources.length === 0}
onChange={(_k, v) => onCarvePreview({ ...carve, strength: Number(v) })}
- onCommit={(_k, v) => onCarveChange({ ...carve, strength: Number(v) })}
+ onCommit={(_k, v) => {
+ onCarveChange({ ...carve, strength: Number(v) });
+ trackInput("slider", "carve-strength");
+ }}
/>
</div>
{/* What the analysis made of all that. Divided rather than boxed: these
@@ -334,6 +342,7 @@ function CarveSourceRow({
disabled?: boolean;
onCarveChange(carve: HfCarveSettings): void;
}) {
+ const trackInput = useTrackDesignInput();
return (
<div className="hf-fx-row flex min-h-6 items-center gap-2">
{/* Wraps like every other name in this column (see FxParamRow) — one
@@ -366,14 +375,15 @@ function CarveSourceRow({
data-carve-source={o.id}
checked={carve.sources.includes(o.id)}
disabled={disabled}
- onChange={(e) =>
+ onChange={(e) => {
onCarveChange({
...carve,
sources: e.target.checked
? [...carve.sources, o.id]
: carve.sources.filter((id) => id !== o.id),
- })
- }
+ });
+ trackInput("toggle", "carve-source");
+ }}
/>
<span className="truncate">{o.label}</span>
</label>
diff --git a/packages/studio/src/components/editor/propertyPanelFxNodeOpenBody.tsx b/packages/studio/src/components/editor/propertyPanelFxNodeOpenBody.tsx
index 6a5183212c..c35189af45 100644
--- a/packages/studio/src/components/editor/propertyPanelFxNodeOpenBody.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxNodeOpenBody.tsx
@@ -1,3 +1,4 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
* An effect row's open face: the derived or primary one-knob control, and
* Details underneath it.
@@ -54,6 +55,7 @@ function FxNodeDerivedKnob({
onUpdate(index: number, patch: Partial<HfAudioFxNode>): void;
trackKind?: string;
}) {
+ const trackInput = useTrackDesignInput();
if (!derived) return null;
return (
<>
@@ -66,6 +68,7 @@ function FxNodeDerivedKnob({
onCommit={(_k, v) => {
trackProfileCommitted(node.type, Number(v), { trackKind });
onUpdate(index, { params: applyAudioFxProfile(node.type, Number(v), params) });
+ trackInput("slider", "profile-strength");
}}
/>
</div>
diff --git a/packages/studio/src/components/editor/propertyPanelFxNodeParams.tsx b/packages/studio/src/components/editor/propertyPanelFxNodeParams.tsx
index 4e73130e3f..014257718e 100644
--- a/packages/studio/src/components/editor/propertyPanelFxNodeParams.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxNodeParams.tsx
@@ -1,3 +1,4 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
* An open effect's knobs, with whatever automation surface applies to them.
*
@@ -69,6 +70,7 @@ export function FxNodeParams({
index: number;
disabled: boolean;
}) {
+ const trackInput = useTrackDesignInput();
const nodeId = node.id;
// Lanes address a node by id; the controls know their own parameter keys. This
// is the one place that translation belongs.
@@ -97,14 +99,25 @@ export function FxNodeParams({
if (before[key] === value) continue;
if (typeof value !== "number" && typeof value !== "string") continue;
trackParamCommitted(node.type, key, value, "details", { trackKind });
+ trackInput(typeof value === "number" ? "slider" : "select", key);
}
onUpdate(index, { params: next });
}}
automatedKeys={automatedKeysOf(node, def.params, automatedTargets)}
- onAutomate={nodeId && onAutomateParam ? (key) => onAutomateParam(nodeId, key) : undefined}
+ onAutomate={
+ nodeId && onAutomateParam
+ ? (key) => {
+ onAutomateParam(nodeId, key);
+ trackInput("button", "automate-param");
+ }
+ : undefined
+ }
onRemoveAutomation={
nodeId && onRemoveParamAutomation
- ? (key) => onRemoveParamAutomation(nodeId, key)
+ ? (key) => {
+ onRemoveParamAutomation(nodeId, key);
+ trackInput("button", "remove-param-automation");
+ }
: undefined
}
/>
diff --git a/packages/studio/src/components/editor/propertyPanelFxNodeRow.tsx b/packages/studio/src/components/editor/propertyPanelFxNodeRow.tsx
index 567b71f23d..7d5a960dd2 100644
--- a/packages/studio/src/components/editor/propertyPanelFxNodeRow.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxNodeRow.tsx
@@ -1,3 +1,4 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
* One effect in the FX rack: its header controls, and its knobs when open.
*
@@ -246,6 +247,7 @@ export function FxNodeRow({
onPreview,
trackKind,
}: FxNodeRowProps) {
+ const trackInput = useTrackDesignInput();
const registryDef = getAudioFxDef(node.type);
const def = useMemo(() => (registryDef ? plainDef(registryDef) : null), [registryDef]);
const primary = registryDef ? primaryParamOf(registryDef) : null;
@@ -306,6 +308,7 @@ export function FxNodeRow({
onToggleBypass={() => {
trackNodeBypassed(node.type, !bypassed, { trackKind });
onUpdate(index, { enabled: bypassed });
+ trackInput("toggle", "effect-bypass");
}}
onMove={(delta) => onMove(index, delta)}
onRemove={() => onRemove(index)}
diff --git a/packages/studio/src/components/editor/propertyPanelFxPresetRun.tsx b/packages/studio/src/components/editor/propertyPanelFxPresetRun.tsx
index eb92a90455..deddff5b2a 100644
--- a/packages/studio/src/components/editor/propertyPanelFxPresetRun.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxPresetRun.tsx
@@ -1,3 +1,4 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
* One preset's bracket in the rack: its own header, on/off switch, amount lane
* and the rows it wraps — or, for a run with no preset, just the rows.
@@ -93,6 +94,7 @@ export function FxPresetRun({
onAutomate,
onRemoveAutomation,
}: FxPresetRunProps) {
+ const trackInput = useTrackDesignInput();
const rows = run.items.map(({ node, i }) => (
<FxNodeRow
// Keyed by id, as the carve module's list above already is. On
@@ -183,7 +185,10 @@ export function FxPresetRun({
aria-pressed={runOn}
title={runOn ? `Switch ${preset.label} off` : `Switch ${preset.label} back on`}
disabled={disabled}
- onClick={() => onSetAmount(runOn ? 0 : 1)}
+ onClick={() => {
+ onSetAmount(runOn ? 0 : 1);
+ trackInput("toggle", "preset-amount");
+ }}
>
{runOn ? "On" : "Off"}
</button>
@@ -205,7 +210,10 @@ export function FxPresetRun({
disabled={disabled || automated}
automated={automated}
onChange={(_k, v) => onSetAmount(Number(v), false)}
- onCommit={(_k, v) => onSetAmount(Number(v))}
+ onCommit={(_k, v) => {
+ onSetAmount(Number(v));
+ trackInput("slider", "preset-amount");
+ }}
onAutomate={onAutomate}
onRemoveAutomation={onRemoveAutomation}
/>
diff --git a/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx b/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx
index ee27e3b699..ee2452d431 100644
--- a/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx
@@ -1787,3 +1787,59 @@ describe("voiceover carve visibility", () => {
expect(carveBlock(host)).toBeTruthy();
});
});
+
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../../utils/studioTelemetry";
+import { __resetDesignInputThrottle } from "../../utils/designInputTracking";
+import { DesignPanelInputProvider } from "../../contexts/DesignPanelInputContext";
+function renderTrackedFx(props: Partial<Parameters<typeof FxSection>[0]> = {}) {
+ vi.mocked(trackStudioEvent).mockClear();
+ __resetDesignInputThrottle();
+ return renderInto(
+ <DesignPanelInputProvider ui="flat" section="media">
+ <FxSection
+ chain={chainOf("lowpass", "gain")}
+ onChainChange={vi.fn()}
+ carve={null}
+ onCarveChange={vi.fn()}
+ sourceOptions={[]}
+ {...props}
+ />
+ </DesignPanelInputProvider>,
+ );
+}
+
+describe("custom FX inspector input usage", () => {
+ it.each([
+ [".hf-fx-bypass", "toggle", "effect-bypass"],
+ ['.hf-fx-move[title="Move down"]', "button", "move-effect"],
+ [".hf-fx-remove", "button", "remove-effect"],
+ ])("tracks %s through design_input once", (selector, control, name) => {
+ const onChainChange = vi.fn();
+ const { host, root } = renderTrackedFx({ onChainChange });
+ click(host.querySelector(selector));
+ expect(onChainChange).toHaveBeenCalledTimes(1);
+ expect(
+ vi.mocked(trackStudioEvent).mock.calls.filter(([event]) => event === "design_input"),
+ ).toEqual([["design_input", { ui: "flat", section: "media", control, name }]]);
+ expect(vi.mocked(trackStudioEvent).mock.calls.some(([event]) => event === "feature_used")).toBe(
+ false,
+ );
+ act(() => root.unmount());
+ });
+ it.each([false, true])("tracks a levelling button once (already levelled: %s)", (levelled) => {
+ const action = vi.fn();
+ const { host, root } = renderTrackedFx({ levelled, onLevel: action, onRemoveLevel: action });
+ click(byText(host, "button", "+ effect"));
+ vi.mocked(trackStudioEvent).mockClear();
+ click(byText(host, "button", levelled ? "Remove levelling" : "Even Out Levels"));
+ expect(action).toHaveBeenCalledTimes(1);
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("design_input", {
+ ui: "flat",
+ section: "media",
+ control: "button",
+ name: levelled ? "remove-levelling" : "add-levelling",
+ });
+ act(() => root.unmount());
+ });
+});
diff --git a/packages/studio/src/components/editor/propertyPanelFxSection.tsx b/packages/studio/src/components/editor/propertyPanelFxSection.tsx
index 90312e700a..94412b210e 100644
--- a/packages/studio/src/components/editor/propertyPanelFxSection.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFxSection.tsx
@@ -1,3 +1,4 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
* The FX section for an audio element: the chain, plus the voiceover carve.
*
@@ -120,13 +121,17 @@ export function FxSection({
// could only name a source it must not.
const showCarve = !carvedAgainstBy && (sourceOptions.length > 0 || carve !== null);
+ const trackInput = useTrackDesignInput();
const [adding, setAdding] = useState(false);
const [picking, setPicking] = useState(false);
const [openNode, setOpenNode] = useState<number | null>(0);
const mutate = useCallback(
- (nodes: HfAudioFxNode[]) => onChainChange({ ...chain, nodes }),
- [chain, onChainChange],
+ (nodes: HfAudioFxNode[], input?: string, control = "button") => {
+ onChainChange({ ...chain, nodes });
+ if (input) trackInput(control, input);
+ },
+ [chain, onChainChange, trackInput],
);
// Dragging a knob previews without persisting; releasing it commits once.
@@ -156,7 +161,7 @@ export function FxSection({
// old chain back over the write that just landed is a race the author
// hears as the preset arriving and then leaving again.
clearAudition();
- mutate(next.nodes);
+ mutate(next.nodes, "apply-preset");
// Land on the first node the preset wrote, so the author can hear what
// arrived and immediately see what it is made of.
setOpenNode(next.nodes.findIndex((n) => n.fromPreset === id));
@@ -169,7 +174,7 @@ export function FxSection({
(job: HfAudioFxJob) => {
clearAudition();
trackNodeAdded(job.type, "job", job.id, { trackKind });
- mutate(withJob(chain, job).nodes);
+ mutate(withJob(chain, job).nodes, "add-job");
setOpenNode(chain.nodes.length);
setAdding(false);
},
@@ -180,7 +185,7 @@ export function FxSection({
(type: string) => {
clearAudition();
trackNodeAdded(type, "effect", null, { trackKind });
- mutate(withEffect(chain, type).nodes);
+ mutate(withEffect(chain, type).nodes, "add-effect");
setOpenNode(chain.nodes.length);
setAdding(false);
},
@@ -218,26 +223,18 @@ export function FxSection({
[chain, mutate, onChainPreview],
);
- /**
- * Take a preset back out whole, lanes and all.
- *
- * Same contract as removing one node — an orphaned lane keeps driving a
- * parameter that is no longer in the graph, and with ids minted lowest-free
- * the next effect added inherits it.
- */
+ // Remove the run and its lanes together so new nodes cannot inherit orphaned automation.
const removeRun = useCallback(
(items: { node: HfAudioFxNode; i: number }[], presetId?: string) => {
- // One call, not a loop: every write is computed from the same snapshot and
- // replaces the whole attribute, so a loop kept only its last write and left
- // the other nodes' lanes behind as orphans. The preset id goes with it —
- // the `fx.preset.<id>` amount lane belongs to the preset, not to any node,
- // so nothing else would ever collect it, and re-applying the preset later
- // resurrected the old ramp.
+ // Remove node and preset automation together before replacing the chain.
const ids = items.map(({ node }) => node.id).filter((id): id is string => Boolean(id));
if (ids.length > 0 || presetId) onRemoveNodesAutomation?.(ids, presetId);
if (presetId) trackPresetRemoved(presetId, { trackKind });
const slots = new Set(items.map((item) => item.i));
- mutate(chain.nodes.filter((_, i) => !slots.has(i)));
+ mutate(
+ chain.nodes.filter((_, i) => !slots.has(i)),
+ "remove-preset",
+ );
setOpenNode(null);
},
[chain.nodes, mutate, onRemoveNodesAutomation, trackKind],
@@ -254,7 +251,10 @@ export function FxSection({
const removedId = removed?.id;
if (removedId) onRemoveNodeAutomation?.(removedId);
if (removed) trackNodeRemoved(removed.type, nodeOrigin(removed), { trackKind });
- mutate(chain.nodes.filter((_, i) => i !== index));
+ mutate(
+ chain.nodes.filter((_, i) => i !== index),
+ "remove-effect",
+ );
setOpenNode(null);
},
[chain.nodes, mutate, onRemoveNodeAutomation, trackKind],
@@ -372,7 +372,7 @@ export function FxSection({
clearAudition();
const { chain: next, eqId } = addAudioEq(chain);
trackNodeAdded("eq", "eq", null, { trackKind });
- mutate(next.nodes);
+ mutate(next.nodes, "add-eq");
setOpenEq(eqId);
setAdding(false);
}, [chain, mutate, clearAudition, trackKind]);
@@ -386,20 +386,18 @@ export function FxSection({
);
const commitEqBand = useCallback(
(eqId: string, band: string, gain: number) =>
- mutate(setAudioEqBandGain(chain, eqId, band, gain).nodes),
+ mutate(setAudioEqBandGain(chain, eqId, band, gain).nodes, "eq-gain", "slider"),
[chain, mutate],
);
const removeEq = useCallback(
(eqId: string) => {
- // Batched for the same reason as `removeRun` — this loop had the identical
- // last-write-wins bug and was only unreachable because an EQ band row
- // offers no automation toggle today.
+ // Remove the EQ automation in one write.
const ids = chain.nodes
.filter((node) => node.fromEq === eqId)
.map((node) => node.id)
.filter((id): id is string => Boolean(id));
if (ids.length > 0) onRemoveNodesAutomation?.(ids);
- mutate(removeAudioEq(chain, eqId).nodes);
+ mutate(removeAudioEq(chain, eqId).nodes, "remove-eq");
},
[chain, mutate, onRemoveNodesAutomation],
);
@@ -412,7 +410,7 @@ export function FxSection({
const [moved] = next.splice(index, 1);
next.splice(target, 0, moved!);
if (moved) trackNodeMoved(moved.type, delta < 0 ? "up" : "down", { trackKind });
- mutate(next);
+ mutate(next, "move-effect");
setOpenNode(target);
},
[chain.nodes, mutate, trackKind],
@@ -448,6 +446,7 @@ export function FxSection({
return () => {
trackPresetAutomated(presetId, true, { trackKind });
onAutomatePreset(presetId, amount);
+ trackInput("button", "automate-preset");
};
};
@@ -456,7 +455,10 @@ export function FxSection({
presetId: string | undefined,
): (() => void) | undefined => {
if (!presetId || !onRemovePresetAutomation || !presetAutomated.has(presetId)) return undefined;
- return () => onRemovePresetAutomation(presetId);
+ return () => {
+ onRemovePresetAutomation(presetId);
+ trackInput("button", "remove-preset-automation");
+ };
};
return (
diff --git a/packages/studio/src/components/editor/propertyPanelTypes.ts b/packages/studio/src/components/editor/propertyPanelTypes.ts
index 3b58a02ebc..7dab3a8180 100644
--- a/packages/studio/src/components/editor/propertyPanelTypes.ts
+++ b/packages/studio/src/components/editor/propertyPanelTypes.ts
@@ -82,12 +82,15 @@ export interface PropertyPanelProps {
element: DomEditSelection,
next: { x: number; y: number },
route?: { plainTranslate: boolean },
- ) => void | Promise<void>;
+ ) => void | Promise<void | import("../../utils/previewFeatureUsage").GeometryCommitResult>;
onSetManualSize: (
element: DomEditSelection,
next: { width: number; height: number },
- ) => void | Promise<void>;
- onSetManualRotation: (element: DomEditSelection, next: { angle: number }) => void | Promise<void>;
+ ) => void | Promise<void | import("../../utils/previewFeatureUsage").GeometryCommitResult>;
+ onSetManualRotation: (
+ element: DomEditSelection,
+ next: { angle: number },
+ ) => void | Promise<void | import("../../utils/previewFeatureUsage").GeometryCommitResult>;
onSetText: (value: string, fieldKey?: string) => void;
onSetTextFieldStyle: (fieldKey: string, property: string, value: string) => void;
onPreviewTextFieldStyle?: (fieldKey: string, property: string, value: string) => void;
diff --git a/packages/studio/src/components/editor/useDomEditNudge.test.tsx b/packages/studio/src/components/editor/useDomEditNudge.test.tsx
index 01dc955732..af77cdcbfd 100644
--- a/packages/studio/src/components/editor/useDomEditNudge.test.tsx
+++ b/packages/studio/src/components/editor/useDomEditNudge.test.tsx
@@ -1,3 +1,4 @@
+import { trackStudioEvent } from "../../utils/studioTelemetry";
// @vitest-environment happy-dom
import React, { act } from "react";
import { createRoot } from "react-dom/client";
@@ -423,3 +424,39 @@ describe("useDomEditNudge — a commit that throws", () => {
act(() => root.unmount());
});
});
+
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+describe("nudge usage", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.useFakeTimers();
+ __resetForTests();
+ });
+ afterEach(() => vi.useRealTimers());
+ it.each([true, false])(
+ "counts a whole key burst only when the writer changed source (%s)",
+ async (changed) => {
+ const root = createRoot(document.body.appendChild(document.createElement("div")));
+ const element = document.body.appendChild(document.createElement("div"));
+ const commit = vi.fn().mockResolvedValue({ ok: true, changed });
+ act(() =>
+ root.render(
+ <Harness selection={makeSelection("Dot", element)} onPathOffsetCommit={commit} />,
+ ),
+ );
+ act(() => {
+ dispatchArrowRight();
+ dispatchArrowRight();
+ });
+ await act(async () => vi.advanceTimersByTimeAsync(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10));
+ expect(commit).toHaveBeenCalledTimes(1);
+ expect(vi.mocked(trackStudioEvent).mock.calls).toEqual(
+ changed
+ ? [["feature_used", { feature: "nudge", surface: "preview", method: "keyboard" }]]
+ : [],
+ );
+ act(() => root.unmount());
+ element.remove();
+ },
+ );
+});
diff --git a/packages/studio/src/components/editor/useDomEditNudge.ts b/packages/studio/src/components/editor/useDomEditNudge.ts
index 49129d5fc5..b1dae8ffb1 100644
--- a/packages/studio/src/components/editor/useDomEditNudge.ts
+++ b/packages/studio/src/components/editor/useDomEditNudge.ts
@@ -1,3 +1,4 @@
+import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
/**
* Canvas arrow-key nudge for DomEditOverlay: arrows move the selected
* element(s) 1 composition px, Shift = 10. Each keypress previews through the
@@ -173,6 +174,7 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
for (const member of session.members)
restoreStudioPathOffset(member.element, member.initialPathOffset);
saved = Promise.resolve(commit)
+ .then((result) => trackPreviewEditResult("nudge", "keyboard", result))
.catch(() => {
for (const member of session.members) {
if (isStudioManualEditGestureCurrent(member.element, member.gestureToken)) {
diff --git a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
index 4cc806e9ae..bd792ae38a 100644
--- a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
@@ -1,3 +1,4 @@
+import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
// fallow-ignore-file code-duplication
/**
* Gesture handling for DomEditOverlay.
@@ -353,6 +354,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
const groupSaved = Promise.resolve(
groupEdit.adopt(() => opts.onGroupPathOffsetCommitRef.current(updates)),
)
+ .then((result) => trackPreviewEditResult("move", "drag", result))
.catch(() => {
for (const member of groupG.members) {
if (
@@ -442,6 +444,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
applyRotationDraft(sel.element, finalRotation.angle, g.plainRotation);
const commit = g.plainRotation ? { ...finalRotation, plain: g.plainRotation } : finalRotation;
void Promise.resolve(opts.onRotationCommitRef.current(sel, commit))
+ .then((result) => trackPreviewEditResult("rotate", "drag", result))
.catch((error) => {
logGestureCommitFailure("rotate commit failed", error);
if (
@@ -488,6 +491,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
}),
),
)
+ .then((result) => trackPreviewEditResult("move", "drag", result))
.catch(() => {
if (
g.pathOffsetMember?.gestureToken &&
@@ -534,6 +538,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
void Promise.resolve(
opts.onBoxSizeCommitRef.current(sel, finalSize, finalOffset ?? undefined, restore),
)
+ .then((result) => trackPreviewEditResult("resize", "drag", result))
.catch((error) => {
logGestureCommitFailure("resize commit failed", error);
})
diff --git a/packages/studio/src/components/editor/useDomEditZOrder.ts b/packages/studio/src/components/editor/useDomEditZOrder.ts
index e504327741..037777abeb 100644
--- a/packages/studio/src/components/editor/useDomEditZOrder.ts
+++ b/packages/studio/src/components/editor/useDomEditZOrder.ts
@@ -1,3 +1,4 @@
+import { trackPreviewFeatureUsed } from "../../utils/previewFeatureUsage";
import { useCallback, useMemo } from "react";
import { useDomEditActionsContext } from "../../contexts/DomEditContext";
import { readHfId, type DomEditSelection } from "./domEditing";
@@ -156,8 +157,13 @@ export function useDomEditZOrder(): DomEditZOrder {
// One serialized z→lane transaction: the mirror runs only AFTER a durable z commit and
// no second gesture interleaves (see runZLaneGesture). A failed z commit has already
// toasted and rolled back, so the catch only keeps its rejection from going unhandled.
+ let changed = false;
runZLaneGesture({
- commitZ: () => handleDomZIndexReorderCommit(entries, coalesceKey, action),
+ commitZ: async () => {
+ const result = await handleDomZIndexReorderCommit(entries, coalesceKey, action);
+ changed = result?.durable === true && result.changed;
+ return result;
+ },
mirror: () =>
mirrorZOrderToTimeline({
selectionKey: entries.find((e) => e.element === sel.element)?.key,
@@ -166,7 +172,11 @@ export function useDomEditZOrder(): DomEditZOrder {
sourceFile: sel.sourceFile,
coalesceKey,
}),
- }).catch(() => undefined);
+ })
+ .then(() => {
+ if (changed) trackPreviewFeatureUsed("z_order", "button");
+ })
+ .catch(() => undefined);
return true;
},
[activeCompPath, handleDomZIndexReorderCommit, mirrorZOrderToTimeline, readOnly],
diff --git a/packages/studio/src/components/nle/useTimelineEditCallbacks.test.tsx b/packages/studio/src/components/nle/useTimelineEditCallbacks.test.tsx
index 06e599ea0c..53a6a64270 100644
--- a/packages/studio/src/components/nle/useTimelineEditCallbacks.test.tsx
+++ b/packages/studio/src/components/nle/useTimelineEditCallbacks.test.tsx
@@ -409,6 +409,7 @@ describe("useTimelineEditCallbacks — flat tween keyframe lanes", () => {
expect(mocks.actions.handleGsapRemoveAllKeyframes).toHaveBeenCalledWith(
scaleAnimation.id,
circleSelection,
+ false,
);
view.unmount();
});
diff --git a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts b/packages/studio/src/components/nle/useTimelineEditCallbacks.ts
index 8f66485f15..a1adfe2b2d 100644
--- a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts
+++ b/packages/studio/src/components/nle/useTimelineEditCallbacks.ts
@@ -1,4 +1,5 @@
import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
+import { trackKeyframeUsage } from "../../utils/keyframeUsage";
import { useCallback, useMemo } from "react";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import type { TimelineElement } from "../../player";
@@ -259,7 +260,12 @@ export function useTimelineEditCallbacks({
if (!selection) return;
// Serial: each removal rewrites the same source file, so dispatching
// them together would have the later writes read a pre-edit document.
- for (const anim of anims) await handleGsapRemoveAllKeyframes(anim.id, selection);
+ let changed = false;
+ for (const anim of anims) {
+ const result = await handleGsapRemoveAllKeyframes(anim.id, selection, false);
+ changed = result || changed;
+ }
+ if (changed) trackKeyframeUsage("remove_all");
});
},
onDeleteKeyframe: (elId, keyframe) => {
diff --git a/packages/studio/src/contexts/DomEditContext.tsx b/packages/studio/src/contexts/DomEditContext.tsx
index d84f19ca54..87282b5baa 100644
--- a/packages/studio/src/contexts/DomEditContext.tsx
+++ b/packages/studio/src/contexts/DomEditContext.tsx
@@ -251,7 +251,7 @@ export function DomEditProvider({
commitMutationRef.current = commitMutation;
const stableCommitMutation = useCallback<DomEditActionsValue["commitMutation"]>(
- (mutation, options) => commitMutationRef.current(mutation, options),
+ (mutation, options, selection) => commitMutationRef.current(mutation, options, selection),
[],
);
diff --git a/packages/studio/src/domEditExports.test.tsx b/packages/studio/src/domEditExports.test.tsx
index f67a900730..a9bb7d2184 100644
--- a/packages/studio/src/domEditExports.test.tsx
+++ b/packages/studio/src/domEditExports.test.tsx
@@ -79,7 +79,7 @@ describe("DOM editing package exports", () => {
front.id = "front";
parent.append(back, front);
document.body.append(parent);
- const commitZ = vi.fn(() => Promise.resolve());
+ const commitZ = vi.fn(async () => ({ durable: true, changed: true }));
const session = {
handleDomZIndexReorderCommit: commitZ,
} as unknown as Parameters<typeof DomEditProvider>[0]["value"];
@@ -107,6 +107,11 @@ describe("DOM editing package exports", () => {
await act(async () => {
expect(zOrder?.apply(sel, toFront)).toBe(true);
});
+ expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+ feature: "z_order",
+ surface: "preview",
+ method: "button",
+ });
expect(commitZ).toHaveBeenCalledTimes(1);
expect(commitZ).toHaveBeenCalledWith(
expect.arrayContaining([expect.objectContaining({ element: back, id: "back" })]),
@@ -159,3 +164,6 @@ describe("DOM editing package exports", () => {
await act(async () => root.unmount());
});
});
+
+vi.mock("./utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "./utils/studioTelemetry";
diff --git a/packages/studio/src/hooks/domEditCommitRunner.ts b/packages/studio/src/hooks/domEditCommitRunner.ts
index 623e25d079..e16f26def4 100644
--- a/packages/studio/src/hooks/domEditCommitRunner.ts
+++ b/packages/studio/src/hooks/domEditCommitRunner.ts
@@ -94,7 +94,7 @@ export type DomEditCommitDeclineReason =
| "persist-failed";
export type DomEditCommitOutcome =
- | { ok: true; persistence?: DomEditPersistOutcome }
+ | { ok: true; persistence?: DomEditPersistOutcome; changed?: boolean }
| { ok: false; reason: DomEditCommitDeclineReason };
export function domEditCommitDeclined(reason: DomEditCommitDeclineReason): DomEditCommitOutcome {
diff --git a/packages/studio/src/hooks/elementOffsetStager.ts b/packages/studio/src/hooks/elementOffsetStager.ts
index f87db4f919..9ea191ce45 100644
--- a/packages/studio/src/hooks/elementOffsetStager.ts
+++ b/packages/studio/src/hooks/elementOffsetStager.ts
@@ -1,3 +1,4 @@
+import type { DomEditPersistOutcome } from "./domEditCommitTypes";
import { getDomEditTargetKey, type DomEditSelection } from "../components/editor/domEditing";
import {
applyElementPositionOffset,
@@ -23,7 +24,7 @@ export interface ElementOffsetStagerDeps {
selection: DomEditSelection,
patches: PatchOperation[],
options: { label: string; coalesceKey: string; coalesceMs?: number },
- ) => Promise<void>;
+ ) => Promise<DomEditPersistOutcome | undefined>;
showToast: (message: string, tone?: "error" | "info") => void;
readOnlyPreview?: boolean;
}
@@ -59,7 +60,7 @@ function stagePlainTranslate(
selection: DomEditSelection,
next: { x: number; y: number },
coalesceKey?: string,
-): { save: () => Promise<void>; rollback: () => void } {
+): { save: () => Promise<DomEditPersistOutcome | undefined>; rollback: () => void } {
const el = selection.element;
const before = captureStudioPathOffset(el);
const patches = writePlainMove(el, next);
@@ -85,9 +86,9 @@ export function stageElementOffset(
next: { x: number; y: number },
plainTranslate: boolean,
coalesceKey?: string,
-): { save: () => Promise<void>; rollback: () => void } {
+): { save: () => Promise<DomEditPersistOutcome | undefined>; rollback: () => void } {
const el = selection.element;
- if (readOnlyPreview) return { save: () => Promise.resolve(), rollback: () => undefined };
+ if (readOnlyPreview) return { save: () => Promise.resolve(undefined), rollback: () => undefined };
if (plainTranslate) {
refuseGsapTakeover(el, showToast);
return stagePlainTranslate(commitPositionPatchToHtml, selection, next, coalesceKey);
diff --git a/packages/studio/src/hooks/gsapDragCommit.ts b/packages/studio/src/hooks/gsapDragCommit.ts
index 264f2a6903..44d459ec1e 100644
--- a/packages/studio/src/hooks/gsapDragCommit.ts
+++ b/packages/studio/src/hooks/gsapDragCommit.ts
@@ -13,7 +13,7 @@ import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeComp
import { roundTo3, roundToLayoutPx } from "../utils/rounding";
import { computeElementPercentage, writeTargetSelector } from "./gsapShared";
import { computeDraggedGsapPosition } from "./draggedGsapPosition";
-import type { RuntimeTweenChange } from "./gsapRuntimePatch";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
import { isGestureTransactionCommit, runGestureTransaction } from "./gestureTransaction";
import { setPatchFromUpdateProperty } from "./gsapDragStaticSetHelpers";
import { GsapEditBlockedError } from "./gsapEditOutcome";
@@ -23,25 +23,7 @@ export {
findSizeSetAnimation,
} from "./gsapDragStaticSetHelpers";
export interface GsapDragCommitCallbacks {
- commitMutation: (
- selection: DomEditSelection,
- mutation: Record<string, unknown>,
- options: {
- label: string;
- coalesceKey?: string;
- coalesceMs?: number;
- softReload?: boolean;
- skipReload?: boolean;
- beforeReload?: () => void;
- /**
- * Value-only fast path: when set, `runCommit` patches the changed tween in
- * the preview runtime in place (instant, no re-run) and only falls back to
- * the soft reload if the patch can't be safely applied. Attached only to
- * value-only `set` commits; structural/keyframe commits omit it.
- */
- instantPatch?: { selector: string; change: RuntimeTweenChange };
- },
- ) => Promise<void>;
+ commitMutation: CommitMutation;
fetchAnimations?: () => Promise<GsapAnimation[]>;
}
diff --git a/packages/studio/src/hooks/gsapDragPositionCommit.ts b/packages/studio/src/hooks/gsapDragPositionCommit.ts
index 7610e7e124..3447615232 100644
--- a/packages/studio/src/hooks/gsapDragPositionCommit.ts
+++ b/packages/studio/src/hooks/gsapDragPositionCommit.ts
@@ -81,7 +81,12 @@ async function extendTweenAndAddKeyframe(
duration: roundTo3(newDuration),
keyframes: remappedKfs,
},
- { label: `Move layer (extended keyframe)`, softReload: true, beforeReload },
+ {
+ label: `Move layer (extended keyframe)`,
+ keyframeAction: "add",
+ softReload: true,
+ beforeReload,
+ },
);
}
@@ -339,7 +344,12 @@ export async function commitGsapPositionFromDrag(
keyframes: temporalKeyframes,
ease: "none",
},
- { label: "Move layer (new keyframe)", softReload: true, beforeReload: restoreOffset },
+ {
+ label: "Move layer (new keyframe)",
+ keyframeAction: "add",
+ softReload: true,
+ beforeReload: restoreOffset,
+ },
);
return;
}
@@ -449,7 +459,12 @@ export async function commitGsapPositionFromDrag(
existingPosAnim
? { type: "replace-with-keyframes", animationId: existingPosAnim.id, ...baseKf }
: { type: "add-with-keyframes", ...baseKf },
- { label: "Move layer (from extended)", softReload: true, beforeReload: restoreOffset },
+ {
+ label: "Move layer (from extended)",
+ keyframeAction: "add",
+ softReload: true,
+ beforeReload: restoreOffset,
+ },
);
} else {
const coalesceKey = `gsap:convert-drag:${anim.id}`;
diff --git a/packages/studio/src/hooks/gsapGestureOutcome.test.ts b/packages/studio/src/hooks/gsapGestureOutcome.test.ts
new file mode 100644
index 0000000000..7440eae90c
--- /dev/null
+++ b/packages/studio/src/hooks/gsapGestureOutcome.test.ts
@@ -0,0 +1,161 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
+import { observeGsapGesture } from "./gsapGestureOutcome";
+import type { CommitMutation, MutationResult } from "./gsapScriptCommitTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+beforeEach(() => vi.clearAllMocks());
+const selection = {} as Parameters<CommitMutation>[0];
+const mutation = {
+ type: "add-keyframe",
+ animationId: "private-target",
+ properties: { text: "private-content" },
+};
+function writer(result?: MutationResult): CommitMutation {
+ const commit: CommitMutation = async (_selection, _mutation, options) => {
+ if (result) options.onResult?.(result);
+ };
+ commit.batch = async (_calls, options) => {
+ if (result) options.onResult?.(result);
+ };
+ return commit;
+}
+
+describe("GSAP gesture usage", () => {
+ it("counts a multi-write add gesture once from successful writer results", async () => {
+ const observed = observeGsapGesture(
+ writer({ ok: true, changed: true, mutationChanges: [true] }),
+ );
+ const onResult = vi.fn();
+ await observed.commit!(
+ selection,
+ { type: "convert-to-keyframes" },
+ { label: "Convert", onResult },
+ );
+ await observed.commit!(selection, mutation, { label: "Add" });
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ expect(observed.finish()).toEqual({ ok: true, changed: true });
+ expect(onResult).toHaveBeenCalledWith({ ok: true, changed: true, mutationChanges: [true] });
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+ });
+
+ it("counts a batched insertion once", async () => {
+ const observed = observeGsapGesture(
+ writer({ ok: true, changed: true, mutationChanges: [true, true] }),
+ );
+ await observed.commit!.batch!(
+ [
+ { selection, mutation, options: { label: "Add" } },
+ { selection, mutation, options: { label: "Add" } },
+ ],
+ { label: "Add together" },
+ );
+ expect(observed.finish().changed).toBe(true);
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+ });
+
+ it("retains insertion metadata from an earlier member of a mixed batch", async () => {
+ const observed = observeGsapGesture(
+ writer({ ok: true, changed: true, mutationChanges: [true, true] }),
+ );
+ await observed.commit!.batch!(
+ [
+ {
+ selection,
+ mutation: { type: "replace-with-keyframes" },
+ options: { label: "Extend", keyframeAction: "add" },
+ },
+ { selection, mutation: { type: "update-keyframe" }, options: { label: "Update" } },
+ ],
+ { label: "Update" },
+ );
+ observed.finish();
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+ });
+
+ it("uses semantic insertion metadata for a replacement", async () => {
+ const observed = observeGsapGesture(
+ writer({ ok: true, changed: true, mutationChanges: [true] }),
+ );
+ await observed.commit!(
+ selection,
+ { type: "replace-with-keyframes" },
+ { label: "Replace", keyframeAction: "add" },
+ );
+ observed.finish();
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+ });
+
+ it.each([undefined, { ok: true }, { ok: true, changed: false }, { ok: false, changed: true }])(
+ "does not count resolution without a changed successful write (%j)",
+ async (result) => {
+ const observed = observeGsapGesture(writer(result));
+ await observed.commit!(selection, mutation, { label: "Add" });
+ expect(observed.finish()).toEqual({ ok: true, changed: false });
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ },
+ );
+
+ it("does not count missing writers or an unfinished group", async () => {
+ expect(observeGsapGesture(null).finish()).toEqual({ ok: true, changed: false });
+ const observed = observeGsapGesture(writer());
+ await observed.commit!(selection, mutation, { label: "Add" });
+ expect(observed.finish(true).changed).toBe(false);
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ });
+
+ it("reports a successful plain DOM gesture without inventing keyframes", () => {
+ expect(observeGsapGesture(null).finish(true).changed).toBe(true);
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ });
+});
+
+it.each([
+ [[false, true], 0],
+ [[true, false], 1],
+ [undefined, 0],
+] as const)(
+ "attributes mixed batches only to changed members (%j)",
+ async (mutationChanges, count) => {
+ const result = {
+ ok: true,
+ changed: true,
+ mutationChanges: mutationChanges && [...mutationChanges],
+ };
+ const observed = observeGsapGesture(writer(result));
+ const mutations = [mutation, { type: "update-property" }];
+ await observed.commit!.batch!(
+ mutations.map((mutation) => ({ selection, mutation, options: { label: "Edit" } })),
+ { label: "Edit" },
+ );
+ expect(observed.finish()).toEqual({ ok: true, changed: true });
+ expect(trackStudioEvent).toHaveBeenCalledTimes(count);
+ if (count) expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+ vi.mocked(trackStudioEvent).mockClear();
+ trackKeyframeCommit(mutations, result, { label: "Edit" });
+ expect(trackStudioEvent).toHaveBeenCalledTimes(count);
+ },
+);
+
+it("excludes a suppressed preparation from mixed-batch attribution", async () => {
+ const result = { ok: true, changed: true, mutationChanges: [true, false] };
+ const calls = [
+ {
+ selection,
+ mutation: { type: "convert-to-keyframes" },
+ options: { label: "Prepare", keyframeTelemetry: false },
+ },
+ { selection, mutation, options: { label: "Add" } },
+ ];
+ const observed = observeGsapGesture(writer(result));
+ await observed.commit!.batch!(calls, { label: "Add" });
+ expect(observed.finish()).toEqual({ ok: true, changed: true });
+ trackKeyframeCommit(
+ calls.map((call) => call.mutation),
+ result,
+ { label: "Add" },
+ calls.map((call) => call.options),
+ );
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+});
diff --git a/packages/studio/src/hooks/gsapGestureOutcome.ts b/packages/studio/src/hooks/gsapGestureOutcome.ts
new file mode 100644
index 0000000000..9016e10434
--- /dev/null
+++ b/packages/studio/src/hooks/gsapGestureOutcome.ts
@@ -0,0 +1,64 @@
+import type {
+ CommitMutationCall,
+ CommitMutation,
+ CommitMutationOptions,
+ MutationResult,
+} from "./gsapScriptCommitTypes";
+import {
+ keyframeUsageActions,
+ changedMutationIndices,
+ primaryKeyframeAction,
+ trackKeyframeUsage,
+ type KeyframeUsageAction,
+} from "../utils/keyframeUsage";
+import type { GeometryCommitResult } from "../utils/previewFeatureUsage";
+
+export function observeGsapGesture(writer: CommitMutation | null) {
+ let changed = false;
+ let pendingResults = 0;
+ const actions = new Set<KeyframeUsageAction>();
+ const observe = (calls: CommitMutationCall[], options: CommitMutationOptions) => {
+ pendingResults += 1;
+ return {
+ ...options,
+ keyframeTelemetry: false,
+ onResult: (result: MutationResult) => {
+ pendingResults -= 1;
+ options.onResult?.(result);
+ if (!result.ok || result.changed !== true) return;
+ changed = true;
+ const members = changedMutationIndices(
+ result,
+ calls.length,
+ calls.map((call) => call.options),
+ ).map((index) => calls[index]!);
+ for (const action of keyframeUsageActions(
+ members.map((call) => call.mutation),
+ members.map((call) => call.options.keyframeAction),
+ ))
+ actions.add(action);
+ },
+ };
+ };
+ let commit: CommitMutation | null = null;
+ if (writer) {
+ commit = (selection, mutation, options) =>
+ writer(selection, mutation, observe([{ selection, mutation, options }], options));
+ if (writer.batch) {
+ const batch = writer.batch;
+ commit.batch = (calls, options) => batch(calls, observe(calls, options));
+ }
+ }
+ return {
+ commit,
+ recordDomResult: (result: { changed: boolean } | undefined) => {
+ changed ||= result?.changed === true;
+ },
+ finish: (domChanged = false): GeometryCommitResult => {
+ if (pendingResults !== 0) return { ok: true, changed: false };
+ const action = primaryKeyframeAction(actions);
+ if (action) trackKeyframeUsage(action);
+ return { ok: true, changed: changed || domChanged };
+ },
+ };
+}
diff --git a/packages/studio/src/hooks/gsapKeyframeCommit.ts b/packages/studio/src/hooks/gsapKeyframeCommit.ts
index ed3ecc498e..974368c435 100644
--- a/packages/studio/src/hooks/gsapKeyframeCommit.ts
+++ b/packages/studio/src/hooks/gsapKeyframeCommit.ts
@@ -4,23 +4,14 @@ import { absoluteToPercentageForAnimation, findTweenAtTime } from "../utils/glob
import { PROPERTY_DEFAULTS, selectorFromSelection, writeTargetSelector } from "./gsapShared";
import { roundToCenti } from "../utils/rounding";
-type CommitFn = (
- selection: DomEditSelection,
- mutation: Record<string, unknown>,
- options: {
- label: string;
- coalesceKey?: string;
- softReload?: boolean;
- skipReload?: boolean;
- },
-) => Promise<void>;
+import type { CommitMutation } from "./gsapScriptCommitTypes";
export async function commitKeyframeAtTimeImpl(
selection: DomEditSelection,
absoluteTime: number,
animations: GsapAnimation[],
properties: Record<string, number | string>,
- commitMutation: CommitFn,
+ commitMutation: CommitMutation,
): Promise<void> {
// Matching an authored tween is a string compare against what the author
// wrote, so it keeps using the selection's own selector; the NEW tween below
@@ -38,7 +29,7 @@ export async function commitKeyframeAtTimeImpl(
await commitMutation(
selection,
{ type: "convert-to-keyframes", animationId: tween.id },
- { label: "Convert to keyframes", skipReload: true },
+ { label: "Convert to keyframes", keyframeTelemetry: false, skipReload: true },
);
}
diff --git a/packages/studio/src/hooks/gsapResizeIntercept.test.ts b/packages/studio/src/hooks/gsapResizeIntercept.test.ts
index 15c7a428b4..72e8b33a2f 100644
--- a/packages/studio/src/hooks/gsapResizeIntercept.test.ts
+++ b/packages/studio/src/hooks/gsapResizeIntercept.test.ts
@@ -3,10 +3,16 @@ import { afterEach, expect, it, vi } from "vitest";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { usePlayerStore } from "../player/store/playerStore";
+import { observeGsapGesture } from "./gsapGestureOutcome";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
import { computeCurrentPercentage } from "./gsapDragCommit";
import { tryGsapResizeIntercept } from "./gsapResizeIntercept";
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
afterEach(() => {
+ vi.clearAllMocks();
vi.restoreAllMocks();
usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null });
});
@@ -553,3 +559,30 @@ it("hands the size to the element's CSS when its only tween is a fade", async ()
expect(handled).toEqual({ status: "element-size" });
expect(commitMutation).not.toHaveBeenCalled();
});
+
+it.each([
+ [5, 1],
+ [0.5, 1],
+ [0.2, 0],
+])("counts scale resize insertion at %ss", async (time, count) => {
+ const el = makeGradedElement();
+ const iframe = fakeIframe(el, { scale: 1, scaleX: 1, scaleY: 1 });
+ usePlayerStore.setState({ currentTime: time, activeKeyframePct: null });
+ const writer: CommitMutation = async (_selection, _mutation, options) => {
+ options.onResult?.({ ok: true, changed: true });
+ };
+ const outcome = observeGsapGesture(writer);
+ const result = await tryGsapResizeIntercept(
+ { id: "clip", selector: "#clip", element: el } as DomEditSelection,
+ { width: 700, height: 400 },
+ [keyframedScaleFixture()],
+ iframe,
+ outcome.commit!,
+ );
+ expect(result.status).toBe("persisted");
+ outcome.finish();
+ expect(trackStudioEvent).toHaveBeenCalledTimes(count);
+ if (count) expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+ el.remove();
+ document.querySelector("#__hf_color_grading_clip")?.remove();
+});
diff --git a/packages/studio/src/hooks/gsapResizeIntercept.ts b/packages/studio/src/hooks/gsapResizeIntercept.ts
index e4adbc5348..5cc3c93e59 100644
--- a/packages/studio/src/hooks/gsapResizeIntercept.ts
+++ b/packages/studio/src/hooks/gsapResizeIntercept.ts
@@ -541,6 +541,7 @@ export async function tryGsapResizeIntercept(
? `Resize (extended to ${ct.toFixed(2)}s)`
: `Resize (keyframe ${Math.round(((ct - newStart) / newDuration) * 1000) / 10}%)`,
softReload: true,
+ ...(!collidingKf ? { keyframeAction: "add" as const } : {}),
},
);
return { status: "persisted", ownsDragOffset: await finalizeScaleResizeCommit() };
diff --git a/packages/studio/src/hooks/gsapScriptCommitTypes.ts b/packages/studio/src/hooks/gsapScriptCommitTypes.ts
index ed292c649f..5682587ad5 100644
--- a/packages/studio/src/hooks/gsapScriptCommitTypes.ts
+++ b/packages/studio/src/hooks/gsapScriptCommitTypes.ts
@@ -3,10 +3,12 @@ import type { Composition } from "@hyperframes/sdk";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import type { PublishSdkSession } from "../utils/sdkCutover";
import type { RuntimeTweenChange } from "./gsapRuntimePatch";
+import type { KeyframeUsageAction } from "../utils/keyframeUsage";
export interface MutationResult {
ok: boolean;
changed?: boolean;
+ mutationChanges?: boolean[];
parsed?: ParsedGsap;
before?: string;
after?: string;
@@ -15,6 +17,9 @@ export interface MutationResult {
export interface CommitMutationOptions {
label: string;
+ keyframeTelemetry?: boolean;
+ keyframeAction?: KeyframeUsageAction;
+ keyframeProperty?: string;
/** Observe the durable writer result without duplicating the request path. */
onResult?: (result: MutationResult) => void;
coalesceKey?: string;
diff --git a/packages/studio/src/hooks/gsapShared.writeTarget.test.ts b/packages/studio/src/hooks/gsapShared.writeTarget.test.ts
index 1be27acf50..5d9af24411 100644
--- a/packages/studio/src/hooks/gsapShared.writeTarget.test.ts
+++ b/packages/studio/src/hooks/gsapShared.writeTarget.test.ts
@@ -6,6 +6,10 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { buildStableSelector, getSelectorIndex } from "../components/editor/domEditingDom";
import { resolveSelectorElementIds, tweenTargetsElement, writeTargetSelector } from "./gsapShared";
import { commitKeyframeAtTimeImpl } from "./gsapKeyframeCommit";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
import { promoteSetToKeyframes } from "./useEnableKeyframes";
afterEach(() => {
@@ -287,3 +291,19 @@ describe("commitKeyframeAtTimeImpl — no one-element target", () => {
expect(commitMutation).not.toHaveBeenCalled();
});
});
+
+it("counts a keyframe-at-time conversion and insertion as one add gesture", async () => {
+ vi.clearAllMocks();
+ const el = document.createElement("div");
+ el.id = "target";
+ document.body.append(el);
+ const selection = selectionFor(el);
+ const animations = parseGsapScript(
+ 'const tl = gsap.timeline(); tl.to("#target", {x:100,duration:4},0);',
+ ).animations;
+ const commit: CommitMutation = async (_selection, mutation, options) => {
+ trackKeyframeCommit([mutation], { ok: true, changed: true }, options);
+ };
+ await commitKeyframeAtTimeImpl(selection, 1, animations, { x: 25 }, commit);
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+});
diff --git a/packages/studio/src/hooks/plainRotation.ts b/packages/studio/src/hooks/plainRotation.ts
index b1f163abc6..f96cb0f7de 100644
--- a/packages/studio/src/hooks/plainRotation.ts
+++ b/packages/studio/src/hooks/plainRotation.ts
@@ -1,3 +1,4 @@
+import type { DomEditPersistOutcome } from "./domEditCommitTypes";
import type { DomEditSelection } from "../components/editor/domEditing";
import { captureStudioRotation, clearStudioRotation } from "../components/editor/manualEdits";
import { buildClearRotationPatches } from "../components/editor/manualEditsDomPatches";
@@ -17,8 +18,8 @@ export function savePlainRotation(
{ commitPositionPatchToHtml, readOnlyPreview }: Omit<ElementOffsetStagerDeps, "showToast">,
selection: DomEditSelection,
next: RotationCommit,
-): Promise<void> {
- if (readOnlyPreview) return Promise.resolve();
+): Promise<DomEditPersistOutcome | undefined> {
+ if (readOnlyPreview) return Promise.resolve(undefined);
const { element } = selection;
const before = captureStudioRotation(element);
// Legacy marks go in the same write, or a seek puts their angle back; clearing them voids the press read.
diff --git a/packages/studio/src/hooks/previewPromotionSelection.test.tsx b/packages/studio/src/hooks/previewPromotionSelection.test.tsx
index 06fd90b5d2..a60a4b4e0c 100644
--- a/packages/studio/src/hooks/previewPromotionSelection.test.tsx
+++ b/packages/studio/src/hooks/previewPromotionSelection.test.tsx
@@ -101,7 +101,7 @@ describe("a shadow reload promoted without a host re-render", () => {
});
expect(overlayNode).toBe(selection.element);
- const commitPositionPatchToHtml = vi.fn(async () => {});
+ const commitPositionPatchToHtml = vi.fn(async () => undefined);
await savePlainRotation({ commitPositionPatchToHtml }, selection, { angle: 30 });
await stageElementOffset(
{ commitPositionPatchToHtml, showToast: vi.fn() },
diff --git a/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx b/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx
index 74c9217dc0..0c28f3fa47 100644
--- a/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx
+++ b/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx
@@ -2,17 +2,22 @@
import React, { act } from "react";
import { afterEach, describe, expect, it, vi } from "vitest";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { parseGsapScript, type GsapAnimation } from "@hyperframes/core/gsap-parser";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { usePlayerStore } from "../player/store/playerStore";
import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
import { mountReactHarness, withInlineLayoutBox } from "./domSelectionTestHarness";
import { writeSizeWithCrop } from "../components/editor/cropResize";
-import type { CommitMutation } from "./gsapScriptCommitTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
+import type { CommitMutationOptions, CommitMutation } from "./gsapScriptCommitTypes";
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
afterEach(() => {
+ vi.clearAllMocks();
document.body.innerHTML = "";
usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 0 });
});
@@ -43,7 +48,11 @@ type Commit = (
/** Renders the hook and hands its commit function to the caller via a ref callback. */
function renderHookWith(
animations: GsapAnimation[],
- onMutation: (mutation: Record<string, unknown>, label: string) => unknown | Promise<unknown>,
+ onMutation: (
+ mutation: Record<string, unknown>,
+ label: string,
+ options: CommitMutationOptions,
+ ) => unknown | Promise<unknown>,
onReady: (commit: Commit) => void,
bumpGsapCache = vi.fn(),
onBatch?: (
@@ -56,9 +65,9 @@ function renderHookWith(
async (
_sel: DomEditSelection,
mutation: Record<string, unknown>,
- options: { label: string },
+ options: CommitMutationOptions,
) => {
- await onMutation(mutation, options.label);
+ await onMutation(mutation, options.label, options);
},
onBatch
? {
@@ -401,3 +410,35 @@ describe("useAnimatedPropertyCommit — a size write and its crop are one undo s
act(() => root.unmount());
});
});
+
+it("counts one add when an inspector edit first converts a flat animation", async () => {
+ usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 1 });
+ const flat = parseGsapScript(
+ 'const tl = gsap.timeline(); tl.to("#box", { rotationX: 0, duration: 2 }, 0);',
+ ).animations[0]!;
+ const mutations: Record<string, unknown>[] = [];
+ let commit!: Commit;
+ const root = renderHookWith(
+ [flat, keyframedAnim],
+ (mutation, _label, options) => {
+ mutations.push(mutation);
+ trackKeyframeCommit([mutation], { ok: true, changed: true }, options);
+ },
+ (value) => {
+ commit = value;
+ },
+ );
+ try {
+ await act(async () => {
+ await commit(selection, { rotationX: 20 });
+ });
+ expect(mutations.map((mutation) => mutation.type)).toEqual([
+ "convert-to-keyframes",
+ "add-keyframe",
+ ]);
+ expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+ expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+ } finally {
+ act(() => root.unmount());
+ }
+});
diff --git a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
index 254474be6f..a415ad46f1 100644
--- a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
+++ b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
@@ -333,7 +333,7 @@ async function commitKeyframeProps(
await commit(
selection,
{ type: "convert-to-keyframes", animationId: anim.id },
- { label: "Convert to keyframes", skipReload: true },
+ { label: "Convert to keyframes", keyframeTelemetry: false, skipReload: true },
);
}
const ct = usePlayerStore.getState().currentTime;
@@ -389,7 +389,7 @@ async function commitKeyframeProps(
duration: roundTo3(newDuration),
keyframes: remapped,
},
- { label: `Edit ${primaryProp} (extended keyframe)`, softReload: true },
+ { label: `Edit ${primaryProp} (extended keyframe)`, keyframeAction: "add", softReload: true },
);
return;
}
diff --git a/packages/studio/src/hooks/useDomEditPositionPatchCommit.ts b/packages/studio/src/hooks/useDomEditPositionPatchCommit.ts
index 173ba4e2e3..101038cae4 100644
--- a/packages/studio/src/hooks/useDomEditPositionPatchCommit.ts
+++ b/packages/studio/src/hooks/useDomEditPositionPatchCommit.ts
@@ -33,30 +33,25 @@ export function useDomEditPositionPatchCommit({
coalesceMs: options.coalesceMs,
skipRefresh: options.skipRefresh ?? true,
deferRender: options.deferRender,
- })
- .then(() => undefined)
- .catch((error) => {
- // A paused save queue is not worth a toast: the paused-save banner is
- // already on screen, and one toast per blocked edit is what this branch
- // exists to prevent. It still has to REJECT, though. Swallowing it
- // resolved the commit, which skipped the caller's revert, so the element
- // stayed where the drag put it while nothing reached the file.
- if (error instanceof DomEditSaveQueueOpenError) throw error;
- if (!wasAlreadyToasted(error)) {
- showToast(error instanceof Error ? error.message : "Failed to save position");
- }
- trackStudioSaveFailure({
- source: "dom_edit",
- error,
- filePath: selection.sourceFile ?? activeCompPath ?? "index.html",
- mutationType: "position",
- label: options.label,
- targetId: selection.id,
- targetSelector: selection.selector,
- targetSourceFile: selection.sourceFile,
- });
- throw error;
+ }).catch((error) => {
+ // The paused-save banner already explains this refusal. Rethrow so the
+ // caller reverts the preview instead of treating an unsaved edit as committed.
+ if (error instanceof DomEditSaveQueueOpenError) throw error;
+ if (!wasAlreadyToasted(error)) {
+ showToast(error instanceof Error ? error.message : "Failed to save position");
+ }
+ trackStudioSaveFailure({
+ source: "dom_edit",
+ error,
+ filePath: selection.sourceFile ?? activeCompPath ?? "index.html",
+ mutationType: "position",
+ label: options.label,
+ targetId: selection.id,
+ targetSelector: selection.selector,
+ targetSourceFile: selection.sourceFile,
});
+ throw error;
+ });
},
[activeCompPath, persistDomEditOperations, showToast],
);
diff --git a/packages/studio/src/hooks/useDomEditTextCommits.test.tsx b/packages/studio/src/hooks/useDomEditTextCommits.test.tsx
index 3057120c54..85124e5487 100644
--- a/packages/studio/src/hooks/useDomEditTextCommits.test.tsx
+++ b/packages/studio/src/hooks/useDomEditTextCommits.test.tsx
@@ -160,6 +160,21 @@ describe("useDomEditTextCommits", () => {
};
}
+ it.each([true, false])(
+ "counts in-place text only after a changed write (%s)",
+ async (changed) => {
+ vi.mocked(trackStudioEvent).mockClear();
+ const { persist, save } = richTextProbe();
+ persist.mockResolvedValue({ changed, sourceFile: "private.html", version: "v2" });
+ await save();
+ expect(vi.mocked(trackStudioEvent).mock.calls).toEqual(
+ changed
+ ? [["feature_used", { feature: "text_edit", surface: "preview", method: "field" }]]
+ : [],
+ );
+ },
+ );
+
it("saves in-place text while the preview is editable, and refreshes the selection it edited", async () => {
const applyDomSelection = vi.fn();
const { persist, element, save } = richTextProbe(undefined, () => ({ applyDomSelection }));
@@ -464,3 +479,6 @@ describe("useDomEditTextCommits", () => {
expect(agentElement.textContent).toBe("Edited");
});
});
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../utils/studioTelemetry";
diff --git a/packages/studio/src/hooks/useDomEditTextCommits.ts b/packages/studio/src/hooks/useDomEditTextCommits.ts
index 21e26c3ca2..19110e843e 100644
--- a/packages/studio/src/hooks/useDomEditTextCommits.ts
+++ b/packages/studio/src/hooks/useDomEditTextCommits.ts
@@ -1,3 +1,4 @@
+import { trackPreviewFeatureUsed } from "../utils/previewFeatureUsage";
import { useCallback, useRef } from "react";
import { normalizeDomEditStyleValue } from "../utils/studioHelpers";
import { injectPreviewGoogleFont, injectPreviewImportedFont } from "../utils/studioFontHelpers";
@@ -272,11 +273,12 @@ export function useDomEditTextCommits({
appliedHtml = element.innerHTML;
},
persist: async () => {
- await persistDomEditOperations(selection, operations, {
+ const result = await persistDomEditOperations(selection, operations, {
label: "Edit text",
skipRefresh: true,
shouldSave: isLatestTextCommit,
});
+ if (result?.changed) trackPreviewFeatureUsed("text_edit", "field");
},
shouldRevert: () => isLatestTextCommit(),
revert: () => {
diff --git a/packages/studio/src/hooks/useDomEditWiring.ts b/packages/studio/src/hooks/useDomEditWiring.ts
index 19178b24d3..106eef1bce 100644
--- a/packages/studio/src/hooks/useDomEditWiring.ts
+++ b/packages/studio/src/hooks/useDomEditWiring.ts
@@ -104,8 +104,10 @@ export interface UseDomEditWiringParams {
animId: string,
resolvedFromValues?: Record<string, number | string>,
) => Promise<void>;
- removeAllKeyframes: (sel: DomEditSelection, animId: string) => Promise<void>;
- handleDomManualEditsReset: (sel: DomEditSelection) => Promise<void>;
+ removeAllKeyframes: Parameters<typeof useGsapSelectionHandlers>[0]["removeAllKeyframes"];
+ handleDomManualEditsReset: (
+ sel: DomEditSelection,
+ ) => Promise<void | import("./domEditCommitTypes").DomEditPersistOutcome>;
}
// fallow-ignore-next-line complexity
diff --git a/packages/studio/src/hooks/useDomGeometryCommit.test.tsx b/packages/studio/src/hooks/useDomGeometryCommit.test.tsx
index 1c3006e053..c31af2e0c9 100644
--- a/packages/studio/src/hooks/useDomGeometryCommit.test.tsx
+++ b/packages/studio/src/hooks/useDomGeometryCommit.test.tsx
@@ -127,7 +127,7 @@ describe("useDomGeometryCommit, from the package entry", () => {
y: 20,
});
- expect(outcome).toEqual({ ok: true });
+ expect(outcome).toEqual({ ok: true, changed: true });
expect(mutations).toEqual([
expect.objectContaining({ type: "add", targetSelector: "#card", method: "set" }),
]);
@@ -146,7 +146,14 @@ describe("useDomGeometryCommit, from the package entry", () => {
const url = String(input instanceof Request ? input.url : input);
calls.urls.push(url);
if (url.includes("/patch-element/")) calls.patches.push(JSON.parse(String(init?.body)));
- const saved = { ok: true, changed: true, matched: true, content: "AFTER", version: "v2" };
+ const saved = {
+ ok: true,
+ changed: true,
+ matched: true,
+ path: "index.html",
+ content: "AFTER",
+ version: "v2",
+ };
const body = url.includes("/files/") ? { content: SOURCE } : saved;
const status = url.includes("/patch-element/") ? patchStatus : 200;
return new Response(JSON.stringify(body), {
@@ -163,7 +170,10 @@ describe("useDomGeometryCommit, from the package entry", () => {
const { element, recordEdit, hook, unmount } = renderHost();
const card = makeSelection("card", element);
- await expect(hook().commitPathOffset(card, { x: 130.5, y: 90 })).resolves.toEqual({ ok: true });
+ await expect(hook().commitPathOffset(card, { x: 130.5, y: 90 })).resolves.toEqual({
+ ok: true,
+ changed: true,
+ });
expect(element.style.getPropertyValue("translate")).toBe("130.5px 90px");
expect(calls.patches).toEqual([
@@ -185,7 +195,7 @@ describe("useDomGeometryCommit, from the package entry", () => {
await expect(
hook().commitBoxSize(makeSelection("card", element), { width: 300, height: 90 }),
- ).resolves.toEqual({ ok: true });
+ ).resolves.toEqual({ ok: true, changed: true });
expect(element.style.getPropertyValue("width")).toBe("300px");
expect(calls.patches).toEqual([
@@ -247,7 +257,7 @@ describe("useDomGeometryCommit, from the package entry", () => {
{ x: 1, y: 2 },
{ plainTranslate: true },
),
- ).resolves.toEqual({ ok: true });
+ ).resolves.toEqual({ ok: true, changed: true });
expect(calls.patches).toHaveLength(1);
unmount();
});
@@ -396,7 +406,14 @@ describe("useDomGeometryCommit, one word of a staggered phrase", () => {
headers: { "content-type": "application/json" },
});
}
- return json({ ok: true, changed: true, matched: true, content: "AFTER", version: "v2" });
+ return json({
+ ok: true,
+ changed: true,
+ matched: true,
+ path: "index.html",
+ content: "AFTER",
+ version: "v2",
+ });
}
if (url.includes("/api/projects/p1/gsap-mutations/")) {
calls.gsapMutations.push(JSON.parse(String(init?.body)));
@@ -426,6 +443,7 @@ describe("useDomGeometryCommit, one word of a staggered phrase", () => {
await expect(hook().commitPathOffset(selection, { x: 40, y: 20 })).resolves.toEqual({
ok: true,
+ changed: true,
});
expect(calls.gsapMutations).toHaveLength(0);
@@ -455,6 +473,7 @@ describe("useDomGeometryCommit, one word of a staggered phrase", () => {
]);
await expect(hook().commitPathOffset(selection, { x: 40, y: 20 })).resolves.toEqual({
ok: true,
+ changed: true,
});
expect(calls.patches).toHaveLength(2);
diff --git a/packages/studio/src/hooks/useDomGeometryCommit.ts b/packages/studio/src/hooks/useDomGeometryCommit.ts
index c730430e7e..234736ae20 100644
--- a/packages/studio/src/hooks/useDomGeometryCommit.ts
+++ b/packages/studio/src/hooks/useDomGeometryCommit.ts
@@ -1,3 +1,4 @@
+import type { GeometryCommitResult } from "../utils/previewFeatureUsage";
import type { RotationCommit } from "../components/editor/rotationDraft";
import { useCallback, useMemo, useRef, useState } from "react";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
@@ -67,7 +68,7 @@ export function useDomGeometryCommit({
}: UseDomGeometryCommitOptions): DomGeometryCommits {
const projectIdRef = useRef(projectId);
projectIdRef.current = projectId;
- const pending = useRef(new Set<Promise<void>>()).current;
+ const pending = useRef(new Set<Promise<GeometryCommitResult | undefined>>()).current;
const editHistory = useMemo(() => ({ recordEdit }), [recordEdit]);
const reload = useCallback(
() => (reloadPreview ? reloadPreview() : iframeRef.current?.contentWindow?.location.reload()),
@@ -142,7 +143,10 @@ export function useDomGeometryCommit({
updateArcSegment: gsap.updateArcSegment,
});
const saved = useCallback(
- async (commit: () => Promise<void>, restore = noop): Promise<DomEditCommitOutcome> => {
+ async (
+ commit: () => Promise<GeometryCommitResult | undefined>,
+ restore = noop,
+ ): Promise<DomEditCommitOutcome> => {
const refusal = !projectIdRef.current
? "No project is open"
: !isPreviewBooted(projectIdRef.current)
@@ -156,11 +160,10 @@ export function useDomGeometryCommit({
const run = commit();
pending.add(run);
try {
- await run;
+ return { ok: true, changed: (await run)?.changed === true };
} finally {
pending.delete(run);
}
- return { ok: true };
},
[pending, showToast],
);
diff --git a/packages/studio/src/hooks/useDomGeometryCommits.test.tsx b/packages/studio/src/hooks/useDomGeometryCommits.test.tsx
index e6d81df47f..4e0af6d849 100644
--- a/packages/studio/src/hooks/useDomGeometryCommits.test.tsx
+++ b/packages/studio/src/hooks/useDomGeometryCommits.test.tsx
@@ -305,6 +305,7 @@ describe("Reset after a plain move puts the author's translate back", () => {
async (_selection, patches) => {
project.history.push(project.file);
project.file = patches.reduce((html, op) => applyPatch(html, "layer", op), project.file);
+ return undefined;
},
);
const selection = { id: "layer", selector: "#layer", element } as unknown as DomEditSelection;
diff --git a/packages/studio/src/hooks/useDomGeometryCommits.ts b/packages/studio/src/hooks/useDomGeometryCommits.ts
index 25b4ce8a19..8c133fb3f0 100644
--- a/packages/studio/src/hooks/useDomGeometryCommits.ts
+++ b/packages/studio/src/hooks/useDomGeometryCommits.ts
@@ -1,3 +1,4 @@
+import type { DomEditPersistOutcome } from "./domEditCommitTypes";
import type { RotationCommit } from "../components/editor/rotationDraft";
import { useCallback } from "react";
import { getDomEditTargetKey, type DomEditSelection } from "../components/editor/domEditing";
@@ -39,7 +40,7 @@ export interface UseDomGeometryCommitsParams {
skipRefresh?: boolean;
deferRender?: boolean;
},
- ) => Promise<void>;
+ ) => Promise<DomEditPersistOutcome | undefined>;
readOnlyPreview: boolean;
}
@@ -73,7 +74,7 @@ export function useDomGeometryCommits({
restore?: () => void,
undoKey?: string,
) => {
- if (readOnlyPreview) return Promise.resolve();
+ if (readOnlyPreview) return Promise.resolve(undefined);
const element = selection.element;
const beforeSize = captureStudioBoxSize(element);
const beforeOffset = captureStudioPathOffset(element);
diff --git a/packages/studio/src/hooks/useDomSelection.test.ts b/packages/studio/src/hooks/useDomSelection.test.ts
index 43047c25f6..fe24abb79e 100644
--- a/packages/studio/src/hooks/useDomSelection.test.ts
+++ b/packages/studio/src/hooks/useDomSelection.test.ts
@@ -334,3 +334,29 @@ describe("useDomSelection", () => {
harness.cleanup();
});
});
+
+it("reports unchanged marquee membership and one new additive member", () => {
+ const { harness, card, chip } = renderCardAndChip();
+ try {
+ act(() => harness.current().applyDomSelection(card));
+ let receipt!: ReturnType<ReturnType<typeof useDomSelection>["applyMarqueeSelection"]>;
+ act(() => {
+ receipt = harness.current().applyMarqueeSelection([chip], true);
+ });
+ expect(receipt).toEqual({ changed: true, count: 2 });
+ act(() => {
+ receipt = harness.current().applyMarqueeSelection([card, chip], true);
+ });
+ expect(receipt).toEqual({ changed: false, count: 2 });
+ act(() => {
+ receipt = harness.current().applyMarqueeSelection([], true);
+ });
+ expect(receipt).toEqual({ changed: false, count: 2 });
+ act(() => {
+ receipt = harness.current().applyMarqueeSelection([], false);
+ });
+ expect(receipt).toEqual({ changed: true, count: 0 });
+ } finally {
+ harness.cleanup();
+ }
+});
diff --git a/packages/studio/src/hooks/useDomSelection.ts b/packages/studio/src/hooks/useDomSelection.ts
index 4802a6937e..f64c04e044 100644
--- a/packages/studio/src/hooks/useDomSelection.ts
+++ b/packages/studio/src/hooks/useDomSelection.ts
@@ -487,12 +487,13 @@ export function useDomSelection({
// fallow-ignore-next-line complexity
(selections: DomEditSelection[], additive: boolean) => {
logSelect("marquee", { hits: selections.length, additive });
+ const current = domEditSelectionRef.current;
+ const currentGroup = domEditGroupSelectionsRef.current;
if (selections.length === 0) {
+ const count = seedDomEditGroupWithSelection(currentGroup, current).length;
if (!additive) applyDomSelection(null, { revealPanel: false });
- return;
+ return { changed: !additive && count > 0, count: additive ? count : 0 };
}
- const current = domEditSelectionRef.current;
- const currentGroup = domEditGroupSelectionsRef.current;
let nextGroup: DomEditSelection[];
if (additive) {
nextGroup = seedDomEditGroupWithSelection(currentGroup, current);
@@ -507,11 +508,17 @@ export function useDomSelection({
}
}
const nextSelection = additive && current ? current : selections[0];
+ const previous = seedDomEditGroupWithSelection(currentGroup, current);
+ const changed =
+ previous.length !== nextGroup.length ||
+ nextGroup.some((selection) => !domEditSelectionInGroup(previous, selection)) ||
+ !domEditSelectionsTargetSame(current, nextSelection);
domEditSelectionRef.current = nextSelection;
domEditGroupSelectionsRef.current = nextGroup;
setDomEditSelection(nextSelection);
setDomEditGroupSelections(nextGroup);
announceTimelineSelection(nextGroup, nextSelection, true);
+ return { changed, count: nextGroup.length };
},
[applyDomSelection, announceTimelineSelection],
);
diff --git a/packages/studio/src/hooks/useDomSelectionTypes.ts b/packages/studio/src/hooks/useDomSelectionTypes.ts
index 85f21f8d86..b118cd4ae1 100644
--- a/packages/studio/src/hooks/useDomSelectionTypes.ts
+++ b/packages/studio/src/hooks/useDomSelectionTypes.ts
@@ -3,6 +3,11 @@ import type { DomEditSelection } from "../components/editor/domEditing";
import type { SelectElementOptions, TimelineElement } from "../player";
import type { RightPanelTab } from "../utils/studioHelpers";
+export interface DomSelectionResult {
+ changed: boolean;
+ count: number;
+}
+
export interface ApplyDomSelectionOptions {
revealPanel?: boolean;
additive?: boolean;
@@ -85,5 +90,5 @@ export interface UseDomSelectionReturn {
handleTimelineElementSelect: (element: TimelineElement | null) => Promise<void>;
refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => Promise<void>;
refreshDomEditGroupSelectionsFromPreview: (selections: DomEditSelection[]) => Promise<void>;
- applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => void;
+ applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => DomSelectionResult;
}
diff --git a/packages/studio/src/hooks/useEnableKeyframes.test.ts b/packages/studio/src/hooks/useEnableKeyframes.test.ts
index 07bf9e2353..4334e7e6cd 100644
--- a/packages/studio/src/hooks/useEnableKeyframes.test.ts
+++ b/packages/studio/src/hooks/useEnableKeyframes.test.ts
@@ -314,7 +314,7 @@ describe("applyArcKeyframeAtPlayhead", () => {
],
ease: "none",
},
- { label: "Add keyframe", softReload: true },
+ { label: "Add keyframe", softReload: true, keyframeAction: "add" },
);
});
@@ -336,7 +336,7 @@ describe("applyArcKeyframeAtPlayhead", () => {
duration: 10,
keyframes: expect.arrayContaining([{ percentage: 25, properties: { x: 25, y: 25 } }]),
}),
- { label: "Add keyframe", softReload: true },
+ { label: "Add keyframe", softReload: true, keyframeAction: "add" },
);
});
});
diff --git a/packages/studio/src/hooks/useEnableKeyframes.ts b/packages/studio/src/hooks/useEnableKeyframes.ts
index c886ca58b8..71b7e0f95d 100644
--- a/packages/studio/src/hooks/useEnableKeyframes.ts
+++ b/packages/studio/src/hooks/useEnableKeyframes.ts
@@ -159,7 +159,7 @@ async function replaceSetWithSingleKeyframe(
keyframes: [{ percentage: 0, properties: position }],
ease: setAnim.ease,
},
- { label: "Enable keyframes", softReload: true },
+ { label: "Enable keyframes", keyframeAction: "add", softReload: true },
);
}
@@ -270,6 +270,7 @@ async function extendKeyframedTweenToPlayhead(
},
{
label: "Add keyframe",
+ keyframeAction: "add",
softReload: true,
...commitOverrides,
},
@@ -377,7 +378,7 @@ export async function promoteSetToKeyframes(
],
ease: setAnim.ease,
},
- { label: "Add keyframe", softReload: true },
+ { label: "Add keyframe", keyframeAction: "add", softReload: true },
);
}
@@ -454,7 +455,7 @@ export async function applyArcKeyframeAtPlayhead(
}),
ease: "none",
},
- { label: "Add keyframe", softReload: true },
+ { label: "Add keyframe", keyframeAction: "add", softReload: true },
);
}
@@ -503,6 +504,7 @@ export function useEnableKeyframes(
enableKeyframesTransactionCounter += 1;
const coalesceKey = `enable-keyframes:${flatAnim.id}:${enableKeyframesTransactionCounter}`;
const convertCommitOverrides: Partial<CommitMutationOptions> = {
+ keyframeTelemetry: false,
skipReload: true,
coalesceKey,
coalesceMs: Number.POSITIVE_INFINITY,
diff --git a/packages/studio/src/hooks/useGestureCommit.test.tsx b/packages/studio/src/hooks/useGestureCommit.test.tsx
index a2077c5e87..5166e049e4 100644
--- a/packages/studio/src/hooks/useGestureCommit.test.tsx
+++ b/packages/studio/src/hooks/useGestureCommit.test.tsx
@@ -1,12 +1,18 @@
// @vitest-environment jsdom
-import { act } from "react";
+import { act, useLayoutEffect } from "react";
import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
import type { DomEditSelection } from "../components/editor/domEditing";
import { usePlayerStore } from "../player";
import { mountReactHarness } from "./domSelectionTestHarness";
import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
import { useGestureCommit } from "./useGestureCommit";
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
const gestureRecording = vi.hoisted(() => ({
startRecording: vi.fn(),
stopRecording: vi.fn(() => [
@@ -84,44 +90,88 @@ function makeSelection(element: HTMLElement): DomEditSelection {
};
}
+function mountRecording(
+ writer: (
+ mutation: Record<string, unknown>,
+ options: CommitMutationOptions,
+ selection?: DomEditSelection,
+ ) => Promise<void>,
+ animations: GsapAnimation[] = [],
+ readOnlyPreview = false,
+) {
+ const iframe = document.createElement("iframe");
+ document.body.append(iframe);
+ const element = document.createElement("div");
+ element.id = "card";
+ const session = {
+ current: {
+ domEditSelection: makeSelection(element),
+ selectedGsapAnimations: animations,
+ commitMutation: writer,
+ },
+ };
+ let hook: ReturnType<typeof useGestureCommit> | null = null;
+ function Probe() {
+ const editing = useGsapAwareEditing({
+ domEditSelection: session.current.domEditSelection,
+ selectedGsapAnimations: session.current.selectedGsapAnimations,
+ gsapCommitMutation: (selection, mutation, options) => writer(mutation, options, selection),
+ previewIframeRef: { current: iframe },
+ showToast: vi.fn(),
+ bumpGsapCache: vi.fn(),
+ makeFetchFallback: () => vi.fn(),
+ trackGsapInteractionFailure: vi.fn(),
+ stageElementPositionOffset: vi.fn(),
+ handleDomBoxSizeCommit: vi.fn(),
+ handleDomRotationCommit: vi.fn(),
+ commitPositionPatchToHtml: vi.fn(),
+ addGsapAnimation: vi.fn(),
+ convertToKeyframes: vi.fn(),
+ setArcPath: vi.fn(),
+ updateArcSegment: vi.fn(),
+ });
+ const currentHook = useGestureCommit({
+ domEditSessionRef: session,
+ previewIframeRef: { current: iframe },
+ showToast: vi.fn(),
+ isGestureRecordingRef: { current: false },
+ readOnlyPreview,
+ });
+ useLayoutEffect(() => {
+ session.current.commitMutation = editing.commitMutation;
+ hook = currentHook;
+ });
+ return null;
+ }
+ const root = mountReactHarness(<Probe />);
+ cleanup = () => act(() => root.unmount());
+ return Object.assign(
+ () => {
+ if (!hook) throw new Error("hook did not initialize");
+ return hook;
+ },
+ {
+ select: (selection: DomEditSelection, nextAnimations: GsapAnimation[]) => {
+ session.current.domEditSelection = selection;
+ session.current.selectedGsapAnimations = nextAnimations;
+ act(() => root.render(<Probe />));
+ },
+ },
+ );
+}
+
describe("useGestureCommit", () => {
it("coalesces property-group commits and reloads only the terminal group", async () => {
- const iframe = document.createElement("iframe");
- document.body.append(iframe);
- const element = document.createElement("div");
- element.id = "card";
- const commitMutation = vi.fn<
+ const writer = vi.fn<
(mutation: Record<string, unknown>, options: CommitMutationOptions) => Promise<void>
>(async () => {});
- const sessionRef = {
- current: {
- domEditSelection: makeSelection(element),
- selectedGsapAnimations: [],
- commitMutation,
- },
- };
- const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
- function Probe() {
- captured.hook = useGestureCommit({
- domEditSessionRef: sessionRef,
- previewIframeRef: { current: iframe },
- showToast: vi.fn(),
- isGestureRecordingRef: { current: false },
- readOnlyPreview: false,
- });
- return null;
- }
- const root = mountReactHarness(<Probe />);
- cleanup = () => act(() => root.unmount());
- if (!captured.hook) throw new Error("hook did not initialize");
-
- act(() => captured.hook?.handleToggleRecording());
- act(() => captured.hook?.handleToggleRecording());
+ const hook = mountRecording(writer);
+ act(() => hook().handleToggleRecording());
+ act(() => hook().handleToggleRecording());
await act(async () => {
- await vi.waitFor(() => expect(commitMutation).toHaveBeenCalledTimes(2));
+ await vi.waitFor(() => expect(writer).toHaveBeenCalledTimes(2));
});
-
- const options = commitMutation.mock.calls.map((call) => call[1]);
+ const options = writer.mock.calls.map((call) => call[1]);
expect(new Set(options.map((entry) => entry.coalesceKey)).size).toBe(1);
expect(options[0]).toEqual(expect.objectContaining({ coalesceMs: Infinity, skipReload: true }));
expect(options[0]).not.toHaveProperty("softReload");
@@ -130,30 +180,150 @@ describe("useGestureCommit", () => {
});
it("does not start a recording while the preview is read-only", () => {
- const element = document.createElement("div");
- const commitMutation = vi.fn(async () => {});
- const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
- function Probe() {
- captured.hook = useGestureCommit({
- domEditSessionRef: {
- current: {
- domEditSelection: makeSelection(element),
- selectedGsapAnimations: [],
- commitMutation,
- },
- },
- previewIframeRef: { current: document.createElement("iframe") },
- showToast: vi.fn(),
- isGestureRecordingRef: { current: false },
- readOnlyPreview: true,
+ const writer = vi.fn(async () => {});
+ const hook = mountRecording(writer, [], true);
+ act(() => hook().handleToggleRecording());
+ expect(gestureRecording.startRecording).not.toHaveBeenCalled();
+ expect(writer).not.toHaveBeenCalled();
+ });
+});
+
+it.each([
+ ["new mixed-property recording", undefined, true, true, 1, "button"],
+ ["keyboard recording", undefined, true, true, 1, "keyboard"],
+ ["static hold replacement", "set", true, true, 1, "button"],
+ ["overlapping tween replacement", "to", true, true, 1, "button"],
+ ["unchanged recording", undefined, true, false, 0, "button"],
+ ["refused recording", undefined, false, true, 0, "button"],
+] as const)(
+ "counts writer receipts once for %s",
+ async (_name, method, ok, changed, count, inputMethod) => {
+ const animations = method
+ ? [
+ {
+ id: "card-position",
+ targetSelector: "#card",
+ propertyGroup: "position",
+ method,
+ properties: { x: 0, y: 0 },
+ resolvedStart: 0,
+ position: 0,
+ duration: method === "set" ? 0 : 2,
+ keyframes: {
+ keyframes: [
+ { percentage: 0, properties: { x: 0 } },
+ { percentage: 100, properties: { x: 100 } },
+ ],
+ },
+ } as unknown as GsapAnimation,
+ ]
+ : [];
+ const writer = vi.fn(
+ async (mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+ const result = { ok, changed };
+ trackKeyframeCommit([mutation], result, options);
+ options.onResult?.(result);
+ },
+ );
+ const hook = mountRecording(writer, animations);
+ act(() => hook().handleToggleRecording(inputMethod));
+ await act(async () => {
+ hook().handleToggleRecording();
+ await vi.waitFor(() => expect(writer).toHaveBeenCalled());
+ });
+ expect(trackStudioEvent).toHaveBeenCalledTimes(count * 2);
+ if (count) {
+ expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+ expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+ feature: "gesture_recording",
+ surface: "preview",
+ method: inputMethod,
});
- return null;
}
- const root = mountReactHarness(<Probe />);
- cleanup = () => act(() => root.unmount());
+ },
+);
- act(() => captured.hook?.handleToggleRecording());
- expect(gestureRecording.startRecording).not.toHaveBeenCalled();
- expect(commitMutation).not.toHaveBeenCalled();
+it("keeps a pending recording isolated until its writer settles", async () => {
+ let release!: () => void;
+ const pending = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ const writer = vi.fn(
+ async (_mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+ await pending;
+ options.onResult?.({ ok: true, changed: true });
+ },
+ );
+ const hook = mountRecording(writer);
+ act(() => hook().handleToggleRecording("keyboard"));
+ act(() => hook().handleToggleRecording());
+ await vi.waitFor(() => expect(writer).toHaveBeenCalledTimes(1));
+ act(() => hook().handleToggleRecording("button"));
+ expect(gestureRecording.startRecording).toHaveBeenCalledTimes(1);
+ await act(async () => {
+ release();
+ await vi.waitFor(() =>
+ expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+ feature: "gesture_recording",
+ surface: "preview",
+ method: "keyboard",
+ }),
+ );
+ });
+ expect(gestureRecording.clearSamples).toHaveBeenCalledTimes(1);
+ act(() => hook().handleToggleRecording("button"));
+ expect(gestureRecording.startRecording).toHaveBeenCalledTimes(2);
+});
+
+it("writes one recording to its original selection after selecting another source", async () => {
+ const original = {
+ id: "original-position",
+ targetSelector: "#card",
+ propertyGroup: "position",
+ method: "set",
+ properties: { x: 0, y: 0 },
+ resolvedStart: 0,
+ position: 0,
+ duration: 0,
+ } as GsapAnimation;
+ const writer = vi.fn(
+ async (
+ _mutation: Record<string, unknown>,
+ options: CommitMutationOptions,
+ _selection?: DomEditSelection,
+ ) => {
+ options.onResult?.({ ok: true, changed: true });
+ },
+ );
+ const hook = mountRecording(writer, [original]);
+ act(() => hook().handleToggleRecording("keyboard"));
+ const other = document.createElement("div");
+ other.id = "other";
+ hook.select(
+ { ...makeSelection(other), sourceFile: "other.html", compositionPath: "other.html" },
+ [],
+ );
+ await act(async () => {
+ hook().handleToggleRecording();
+ await vi.waitFor(() => expect(trackStudioEvent).toHaveBeenCalledTimes(2));
+ });
+ expect(writer).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ type: "replace-with-keyframes",
+ animationId: "original-position",
+ targetSelector: "#card",
+ }),
+ expect.objectContaining({ keyframeAction: "add" }),
+ expect.objectContaining({
+ id: "card",
+ sourceFile: "index.html",
+ compositionPath: "index.html",
+ }),
+ );
+ expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+ expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+ feature: "gesture_recording",
+ surface: "preview",
+ method: "keyboard",
});
});
diff --git a/packages/studio/src/hooks/useGestureCommit.ts b/packages/studio/src/hooks/useGestureCommit.ts
index 78b48c631f..86de46e75a 100644
--- a/packages/studio/src/hooks/useGestureCommit.ts
+++ b/packages/studio/src/hooks/useGestureCommit.ts
@@ -11,6 +11,8 @@ import { usePlayerStore } from "../player";
import type { DomEditSelection } from "../components/editor/domEditing";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+import { trackPreviewEditResult } from "../utils/previewFeatureUsage";
+import { observeGsapGesture } from "./gsapGestureOutcome";
import { roundTo3 } from "../utils/rounding";
import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
import { isInstantHold, idSelector, writeTargetSelector, tweenTargetsElement } from "./gsapShared";
@@ -72,6 +74,7 @@ interface GestureSessionRef {
commitMutation?: (
mutation: Record<string, unknown>,
options: CommitMutationOptions,
+ selection?: DomEditSelection,
) => Promise<void>;
}
@@ -81,6 +84,12 @@ function reloadOnlyLast(index: number, count: number): Partial<CommitMutationOpt
return index === count - 1 ? { softReload: true } : { skipReload: true };
}
+function recordingEnd(selection: DomEditSelection): number | undefined {
+ const start = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
+ const duration = Number.parseFloat(selection.dataAttributes?.duration ?? "0") || 0;
+ return duration > 0 ? start + duration : undefined;
+}
+
let gestureRecordingCommitCounter = 0;
interface UseGestureCommitParams {
@@ -95,7 +104,7 @@ interface UseGestureCommitParams {
export interface UseGestureCommitResult {
gestureState: "idle" | "recording";
gestureRecording: ReturnType<typeof useGestureRecording>;
- handleToggleRecording: () => void;
+ handleToggleRecording: (method?: "button" | "keyboard") => void;
}
// fallow-ignore-next-line complexity
@@ -111,11 +120,13 @@ export function useGestureCommit({
const [gestureState, setGestureState] = useState<"idle" | "recording">("idle");
const gestureStateRef = useRef<"idle" | "recording">("idle");
const recordingAutoStopRef = useRef<ReturnType<typeof setInterval>>(undefined);
+ const recordingMethodRef = useRef<"button" | "keyboard">("button");
const recordingStartTimeRef = useRef(0);
const commitInFlightRef = useRef(false);
// Capture selection at recording start so commit always targets the recorded element,
// even if the user's selection changes mid-recording.
const capturedSelectionRef = useRef<DomEditSelection | null>(null);
+ const capturedAnimationsRef = useRef<GsapAnimation[]>([]);
// Unmount: clear auto-stop interval
useEffect(() => () => clearInterval(recordingAutoStopRef.current), []);
@@ -206,6 +217,12 @@ export function useGestureCommit({
return;
}
if (liveSession.commitMutation) {
+ const writer = liveSession.commitMutation;
+ const outcome = observeGsapGesture((_selection, mutation, options) =>
+ writer(mutation, options, sel),
+ );
+ const commit = (mutation: Record<string, unknown>, options: CommitMutationOptions) =>
+ outcome.commit!(sel, mutation, options);
const recStart = recordingStartTimeRef.current;
const rawKeyframes = sortedPcts.map((pct) => ({
percentage: pct,
@@ -216,7 +233,7 @@ export function useGestureCommit({
const hasPositionProps = keyframes.some((kf) =>
Object.keys(kf.properties).some((k) => classifyPropertyGroup(k) === "position"),
);
- const allAnims = liveSession.selectedGsapAnimations ?? [];
+ const allAnims = capturedAnimationsRef.current;
const existingPositionTween = hasPositionProps
? allAnims.find(
(a) =>
@@ -228,7 +245,7 @@ export function useGestureCommit({
if (isInstantHold(existingPositionTween)) {
// An instant hold is not a tween to merge into — replace it with the
// recorded motion (which already starts from the held position).
- await liveSession.commitMutation(
+ await commit(
{
type: "replace-with-keyframes",
animationId: existingPositionTween.id,
@@ -237,7 +254,7 @@ export function useGestureCommit({
duration: roundTo3(duration),
keyframes,
},
- { label: "Gesture recording (replace set)", softReload: true },
+ { label: "Gesture recording (replace set)", softReload: true, keyframeAction: "add" },
);
} else {
const tweenStart = existingPositionTween.resolvedStart ?? 0;
@@ -274,7 +291,7 @@ export function useGestureCommit({
const merged = [...preserved, ...mapped].sort((a, b) => a.percentage - b.percentage);
- await liveSession.commitMutation(
+ await commit(
{
type: "replace-with-keyframes",
animationId: existingPositionTween.id,
@@ -286,7 +303,7 @@ export function useGestureCommit({
duration: tweenDur,
keyframes: merged,
},
- { label: "Gesture recording (merge)", softReload: true },
+ { label: "Gesture recording (merge)", softReload: true, keyframeAction: "add" },
);
} else {
// Emit one tween per property group so a mixed-prop gesture (e.g.
@@ -294,7 +311,7 @@ export function useGestureCommit({
// tween that the position-only drag intercept can't edit.
const keyframeGroups = partitionKeyframesByGroup(keyframes);
for (const [index, groupKfs] of keyframeGroups.entries()) {
- await liveSession.commitMutation(
+ await commit(
{
type: "add-with-keyframes",
targetSelector: writeSelector,
@@ -320,7 +337,7 @@ export function useGestureCommit({
// No existing tween — same per-group split as the new-range branch above.
const keyframeGroups = partitionKeyframesByGroup(keyframes);
for (const [index, groupKfs] of keyframeGroups.entries()) {
- await liveSession.commitMutation(
+ await commit(
{
type: "add-with-keyframes",
targetSelector: writeSelector,
@@ -338,6 +355,7 @@ export function useGestureCommit({
);
}
}
+ trackPreviewEditResult("gesture_recording", recordingMethodRef.current, outcome.finish());
}
showToast(`Recorded ${sortedPcts.length} keyframes`, "info");
} catch (err) {
@@ -351,58 +369,71 @@ export function useGestureCommit({
}
}, [gestureRecording, showToast, isGestureRecordingRef, domEditSessionRef]);
- // fallow-ignore-next-line complexity
- const handleToggleRecording = useCallback(() => {
- if (gestureStateRef.current === "recording") {
- if (readOnlyPreview) {
- cancelRecording();
+ const armAutoStop = useCallback(
+ (elementEnd: number | undefined) => {
+ clearInterval(recordingAutoStopRef.current);
+ const autoStopAt = elementEnd ?? Infinity;
+ recordingAutoStopRef.current = setInterval(() => {
+ const { currentTime: t, duration: d } = usePlayerStore.getState();
+ const limit = Math.min(autoStopAt, d);
+ if (limit > 0 && t >= limit - 0.05) {
+ void stopAndCommitRecording();
+ }
+ }, 100);
+ },
+ [stopAndCommitRecording],
+ );
+
+ const startRecording = useCallback(
+ (method: "button" | "keyboard") => {
+ if (readOnlyPreview) return;
+ const sel = domEditSessionRef.current.domEditSelection;
+ if (!sel) {
+ showToast("Select an element first", "error");
+ return;
+ }
+ const iframe = previewIframeRef.current;
+ if (!iframe) {
+ showToast("Preview not ready — try again", "error");
return;
}
- void stopAndCommitRecording();
- return;
- }
- if (readOnlyPreview) return;
- const sel = domEditSessionRef.current.domEditSelection;
- if (!sel) {
- showToast("Select an element first", "error");
- return;
- }
- const iframe = previewIframeRef.current;
- if (!iframe) {
- showToast("Preview not ready — try again", "error");
- return;
- }
- const store = usePlayerStore.getState();
- recordingStartTimeRef.current = store.currentTime;
- const elStart = Number.parseFloat(sel.dataAttributes?.start ?? "0") || 0;
- const elDur = Number.parseFloat(sel.dataAttributes?.duration ?? "0") || 0;
- const elementEnd = elDur > 0 ? elStart + elDur : undefined;
- capturedSelectionRef.current = sel;
- gestureRecording.startRecording(sel.element, iframe, elementEnd);
- gestureStateRef.current = "recording";
- isGestureRecordingRef.current = true;
- setGestureState("recording");
+ const store = usePlayerStore.getState();
+ recordingMethodRef.current = method;
+ recordingStartTimeRef.current = store.currentTime;
+ const elementEnd = recordingEnd(sel);
+ capturedSelectionRef.current = sel;
+ capturedAnimationsRef.current = domEditSessionRef.current.selectedGsapAnimations ?? [];
+ gestureRecording.startRecording(sel.element, iframe, elementEnd);
+ gestureStateRef.current = "recording";
+ isGestureRecordingRef.current = true;
+ setGestureState("recording");
- clearInterval(recordingAutoStopRef.current);
- const autoStopAt = elementEnd ?? Infinity;
- recordingAutoStopRef.current = setInterval(() => {
- const { currentTime: t, duration: d } = usePlayerStore.getState();
- const limit = Math.min(autoStopAt, d);
- if (limit > 0 && t >= limit - 0.05) {
- void stopAndCommitRecording();
+ armAutoStop(elementEnd);
+ },
+ [
+ gestureRecording,
+ showToast,
+ previewIframeRef,
+ domEditSessionRef,
+ isGestureRecordingRef,
+ readOnlyPreview,
+ armAutoStop,
+ ],
+ );
+
+ const handleToggleRecording = useCallback(
+ (method: "button" | "keyboard" = "button") => {
+ if (commitInFlightRef.current) return;
+ if (gestureStateRef.current === "recording") {
+ if (readOnlyPreview) cancelRecording();
+ else void stopAndCommitRecording();
+ return;
}
- }, 100);
- }, [
- gestureRecording,
- showToast,
- stopAndCommitRecording,
- cancelRecording,
- previewIframeRef,
- domEditSessionRef,
- isGestureRecordingRef,
- readOnlyPreview,
- ]);
+ startRecording(method);
+ },
+ [cancelRecording, readOnlyPreview, startRecording, stopAndCommitRecording],
+ );
return useStableHandlers({ gestureState, gestureRecording, handleToggleRecording }, projectId);
}
diff --git a/packages/studio/src/hooks/useGsapAwareEditing.test.tsx b/packages/studio/src/hooks/useGsapAwareEditing.test.tsx
index d86f6686fd..22818afe7c 100644
--- a/packages/studio/src/hooks/useGsapAwareEditing.test.tsx
+++ b/packages/studio/src/hooks/useGsapAwareEditing.test.tsx
@@ -74,7 +74,7 @@ function mountResizeHandler(
size: { width: number; height: number },
offset?: { x: number; y: number },
restore?: () => void,
- ) => Promise<void>)
+ ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>)
| null = null;
let property: ReturnType<typeof useGsapAwareEditing>["commitAnimatedProperty"] | null = null;
function Harness() {
@@ -131,13 +131,18 @@ function mountGroupHandler({
"trackGsapInteractionFailure" | "stageElementPositionOffset" | "handleDomRotationCommit"
>
>) {
- let groupCommit!: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
+ let groupCommit!: (
+ updates: DomEditGroupPathOffsetCommit[],
+ ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
let pathOffsetCommit!: (
selection: DomEditSelection,
next: { x: number; y: number },
route?: { plainTranslate?: boolean },
- ) => Promise<void>;
- let rotationCommit!: (selection: DomEditSelection, next: RotationCommit) => Promise<void>;
+ ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
+ let rotationCommit!: (
+ selection: DomEditSelection,
+ next: RotationCommit,
+ ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
function Harness() {
const editing = useGsapAwareEditing({
domEditSelection: null,
@@ -589,7 +594,7 @@ describe("useGsapAwareEditing anchored resize", () => {
h.selection.element.setAttribute("data-hf-drag-initial-offset-x", "0");
h.selection.element.setAttribute("data-hf-drag-initial-offset-y", "0");
- let commit!: Promise<void>;
+ let commit!: Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
act(() => {
commit = h.resize(h.selection, { width: 300, height: 200 }, { x: -50.2, y: -25.6 });
});
@@ -636,7 +641,7 @@ describe("useGsapAwareEditing anchored resize", () => {
s: DomEditSelection,
m: unknown,
o: { coalesceKey?: string; label?: string; softReload?: boolean },
- ) => Promise<void>,
+ ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>,
_fetch: unknown,
options?: { preflightOnly?: boolean },
) => {
diff --git a/packages/studio/src/hooks/useGsapAwareEditing.ts b/packages/studio/src/hooks/useGsapAwareEditing.ts
index 008b599c19..824b882aeb 100644
--- a/packages/studio/src/hooks/useGsapAwareEditing.ts
+++ b/packages/studio/src/hooks/useGsapAwareEditing.ts
@@ -1,3 +1,6 @@
+import { useGsapAwareGroupMove } from "./useGsapAwareGroupMove";
+import { observeGsapGesture } from "./gsapGestureOutcome";
+import type { DomEditPersistOutcome } from "./domEditCommitTypes";
/**
* GSAP-aware move/resize/rotation wrappers that intercept geometry commits
* for animated elements and route them through script mutation instead of
@@ -21,14 +24,9 @@ import {
useGsapSaveFailureTelemetry,
useSafeGsapCommitMutation,
} from "./useSafeGsapCommitMutation";
-import type {
- CommitMutation,
- CommitMutationCall,
- CommitMutationOptions,
-} from "./gsapScriptCommitTypes";
+import type { CommitMutation, CommitMutationOptions } from "./gsapScriptCommitTypes";
import { setElementGsapPosition } from "../utils/elementGsap";
import { logResize, logResizeSettle } from "../utils/resizeDebug";
-import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
import type { MoveCommitOptions } from "../components/editor/domEditOverlayGestures";
import { runGestureTransaction } from "./gestureTransaction";
import {
@@ -40,29 +38,13 @@ import {
} from "./gsapRuntimeKeyframes";
import { assertGsapEditPersisted, saveMove } from "./gsapEditOutcome";
import type { GsapAnimationFetchOptions } from "./useGsapAnimationFetchFallback";
-import { refuseGsapTakeover, type ElementOffsetStagerDeps } from "./elementOffsetStager";
+import { type ElementOffsetStagerDeps } from "./elementOffsetStager";
import {
prepareCropResize,
saveCropResize,
writeSizeWithCrop,
} from "../components/editor/cropResize";
-// Distinct coalesceKey per group drag so consecutive group drags don't fold
-// into one another's undo entry (module-local counter, not Date.now()).
-let groupDragCommitCounter = 0;
-
-function firstPreflightFailure(
- results: PromiseSettledResult<void>[],
- updates: DomEditGroupPathOffsetCommit[],
-): { error: unknown; selection: DomEditSelection } | null {
- for (const [index, result] of results.entries()) {
- if (result.status !== "rejected") continue;
- const selection = updates[index]?.selection;
- if (selection) return { error: result.reason, selection };
- }
- return null;
-}
-
export interface UseGsapAwareEditingParams {
domEditSelection: DomEditSelection | null;
selectedGsapAnimations: GsapAnimation[];
@@ -86,15 +68,18 @@ export interface UseGsapAwareEditingParams {
next: { x: number; y: number },
plainTranslate: boolean,
coalesceKey?: string,
- ) => { save: () => Promise<void>; rollback: () => void };
- handleDomRotationCommit: (selection: DomEditSelection, next: RotationCommit) => Promise<void>;
+ ) => { save: () => Promise<DomEditPersistOutcome | undefined>; rollback: () => void };
+ handleDomRotationCommit: (
+ selection: DomEditSelection,
+ next: RotationCommit,
+ ) => Promise<DomEditPersistOutcome | undefined>;
handleDomBoxSizeCommit: (
selection: DomEditSelection,
next: { width: number; height: number },
offset?: { x: number; y: number },
restore?: () => void,
undoKey?: string,
- ) => Promise<void>;
+ ) => Promise<DomEditPersistOutcome | undefined>;
commitPositionPatchToHtml: ElementOffsetStagerDeps["commitPositionPatchToHtml"];
// GSAP script commit ops (from useGsapScriptCommits)
addGsapAnimation: (
@@ -162,10 +147,12 @@ export function useGsapAwareEditing({
next: { x: number; y: number },
modifiers?: MoveCommitOptions,
) => {
- // A gesture and the panel carry their route; webmcp's moveTo decides here.
- if (modifiers?.plainTranslate ?? !gsapWritesPosition(selection.element))
- return stageElementPositionOffset(selection, next, true).save();
- if (gsapCommitMutation) {
+ const writes = observeGsapGesture(gsapCommitMutation);
+ if (modifiers?.plainTranslate ?? !gsapWritesPosition(selection.element)) {
+ const result = await stageElementPositionOffset(selection, next, true).save();
+ return writes.finish(result?.changed === true);
+ }
+ if (writes.commit) {
try {
const ownedAnimations = getGsapAnimationsForSelection(selection);
const targetAnimations = Array.isArray(ownedAnimations)
@@ -176,11 +163,15 @@ export function useGsapAwareEditing({
next,
targetAnimations,
previewIframeRef.current,
- gsapCommitMutation,
+ writes.commit,
makeFetchFallback(selection),
modifiers,
);
- await saveMove(outcome, () => stageElementPositionOffset(selection, next, false).save());
+ await saveMove(outcome, async () => {
+ const result = await stageElementPositionOffset(selection, next, false).save();
+ writes.recordDomResult(result);
+ });
+ return writes.finish();
} catch (error) {
trackGsapInteractionFailure(error, selection, "drag", "Move animated layer");
throw error;
@@ -197,137 +188,14 @@ export function useGsapAwareEditing({
],
);
- // Multi-select (group) drag: each member takes the single drag's writer, so a member GSAP
- // does not position is saved on itself and the rest go through the GSAP intercept.
- const handleGsapAwareGroupPathOffsetCommit = useCallback(
- async (updates: DomEditGroupPathOffsetCommit[]) => {
- if (!gsapCommitMutation || updates.length === 0) return;
- // A group drag is ONE user action: fold every member's position write into
- // a single undo entry by forcing a shared coalesceKey (infinite window, so
- // it survives the N sequential server round-trips) onto each commit —
- // otherwise each member records its own entry and it takes N presses to undo.
- const coalesceKey = `group-drag:${++groupDragCommitCounter}`;
- // Members are written one at a time, and a re-render re-runs the script with the OLD
- // position of every member not yet written, so they snap back until their own write
- // lands. The drafts are already on screen: hold the render until the last member.
- let renderOnCommit = false;
- const previewFallbackLatch = { pending: false };
- const withGroupOptions = (options: CommitMutationOptions): CommitMutationOptions => ({
- ...options,
- coalesceKey,
- coalesceMs: Number.POSITIVE_INFINITY,
- deferPreviewSync: !renderOnCommit,
- previewFallbackLatch,
- });
- // Every member writes the same file. Queue their mutations and send them as
- // ONE request instead of one round trip per member: the server reads, parses
- // and writes the composition once, and the preview patches once.
- const queued: CommitMutationCall[] = [];
- const flushQueued = async () => {
- if (queued.length === 0) return;
- const calls = queued.splice(0, queued.length);
- if (!gsapCommitMutation.batch) {
- for (const call of calls) {
- await gsapCommitMutation(call.selection, call.mutation, call.options);
- }
- return;
- }
- await gsapCommitMutation.batch(calls, {
- ...(calls.at(-1)?.options ?? { label: "Move animated layer (group)" }),
- label: "Move animated layer (group)",
- });
- };
- const coalescedCommit: typeof gsapCommitMutation = (selection, mutation, options) => {
- queued.push({ selection, mutation, options: withGroupOptions(options) });
- return Promise.resolve();
- };
- const preflightAnimations = new Map<DomEditSelection, GsapAnimation[]>();
- // Members saved on themselves, each with its route: true for its CSS translate.
- const offsetMembers = new Map<DomEditSelection, boolean>();
- // Editability is user-atomic: prove every member can be written before the first source
- // mutation, so a blocked member never leaves earlier siblings partially moved. Preflights
- // write nothing and share one in-flight parse per file, so they run together.
- const preflightResults = await Promise.allSettled(
- updates.map(async ({ selection, plainTranslate }) => {
- if (plainTranslate ?? !gsapWritesPosition(selection.element)) {
- refuseGsapTakeover(selection.element, showToast);
- return void offsetMembers.set(selection, true);
- }
- const animations = await makeFetchFallback(selection, { failOnFetchError: true })();
- preflightAnimations.set(selection, animations);
- const outcome = await tryGsapDragIntercept(
- selection,
- { x: 0, y: 0 },
- animations,
- previewIframeRef.current,
- coalescedCommit,
- undefined,
- { preflightOnly: true, group: true },
- );
- if (outcome.status === "element-offset") offsetMembers.set(selection, false);
- assertGsapEditPersisted(outcome);
- }),
- );
- const preflightFailure = firstPreflightFailure(preflightResults, updates);
- if (preflightFailure) {
- trackGsapInteractionFailure(
- preflightFailure.error,
- preflightFailure.selection,
- "drag",
- "Move animated layer (group)",
- );
- throw preflightFailure.error;
- }
- const lastScriptWrite = updates.findLastIndex(
- ({ selection }) => !offsetMembers.has(selection),
- );
- for (const [index, { selection, next }] of updates.entries()) {
- renderOnCommit = index === lastScriptWrite;
- const plain = offsetMembers.get(selection);
- if (plain !== undefined) {
- await stageElementPositionOffset(selection, next, plain, coalesceKey).save();
- continue;
- }
- try {
- const outcome = await tryGsapDragIntercept(
- selection,
- next,
- preflightAnimations.get(selection) ?? [],
- previewIframeRef.current,
- coalescedCommit,
- // The intercept re-reads the file to resolve a stale or shared tween.
- // Anything already queued has to be on disk before that read, or it
- // resolves against a file missing writes it is about to build on.
- async () => {
- await flushQueued();
- return makeFetchFallback(selection, { fresh: true })();
- },
- { preflightPassed: true },
- );
- assertGsapEditPersisted(outcome);
- } catch (error) {
- trackGsapInteractionFailure(error, selection, "drag", "Move animated layer (group)");
- throw error;
- }
- }
- try {
- await flushQueued();
- } catch (error) {
- // The aggregate write has no uniquely failing member; do not misattribute
- // its telemetry to whichever member happened to be last in the array.
- trackGsapInteractionFailure(error, null, "drag", "Move animated layer (group)");
- throw error;
- }
- },
- [
- gsapCommitMutation,
- previewIframeRef,
- makeFetchFallback,
- trackGsapInteractionFailure,
- stageElementPositionOffset,
- showToast,
- ],
- );
+ const handleGsapAwareGroupPathOffsetCommit = useGsapAwareGroupMove({
+ gsapCommitMutation,
+ previewIframeRef,
+ makeFetchFallback,
+ trackGsapInteractionFailure,
+ stageElementPositionOffset,
+ showToast,
+ });
const handleGsapAwareBoxSizeCommit = useCallback(
async (
@@ -336,8 +204,11 @@ export function useGsapAwareEditing({
offset?: { x: number; y: number },
restore: () => void = () => undefined,
) => {
- if (!gsapWritesBox(selection.element))
- return handleDomBoxSizeCommit(selection, next, offset, restore);
+ const writes = observeGsapGesture(gsapCommitMutation);
+ if (!gsapWritesBox(selection.element)) {
+ const result = await handleDomBoxSizeCommit(selection, next, offset, restore);
+ return writes.finish(result?.changed === true);
+ }
let targetAnimations: GsapAnimation[];
try {
const ownedAnimations = getGsapAnimationsForSelection(selection);
@@ -367,7 +238,28 @@ export function useGsapAwareEditing({
let anchorMove: ReturnType<typeof stageElementPositionOffset> | null = null;
const stageCrop = prepareCropResize(selection.element);
let cropUndoKey: string | null = null;
- return runGestureTransaction({
+ const saveResizeAnchor = async (
+ ownsDragOffset: boolean,
+ commitMutation: CommitMutation,
+ coalesceKey: string,
+ ) => {
+ if (offset && !ownsDragOffset) {
+ const dragOutcome = await tryGsapDragIntercept(
+ selection,
+ offset,
+ targetAnimations,
+ previewIframeRef.current,
+ commitMutation,
+ makeFetchFallback(selection),
+ );
+ // Saved after the size, under its undo key, so the two are one step.
+ await saveMove(dragOutcome, async () => {
+ const plain = !gsapWritesPosition(selection.element);
+ anchorMove = stageElementPositionOffset(selection, offset, plain, coalesceKey);
+ });
+ }
+ };
+ await runGestureTransaction({
element: selection.element,
label: "Resize layer",
settle: () => {
@@ -383,8 +275,8 @@ export function useGsapAwareEditing({
setElementGsapPosition(selection.element, newX, newY);
},
persist: async (commit, coalesceKey) => {
- if (gsapCommitMutation) {
- const commitMutation = commit(gsapCommitMutation);
+ if (writes.commit) {
+ const commitMutation = commit(writes.commit);
try {
const outcome = await tryGsapResizeIntercept(
selection,
@@ -396,9 +288,16 @@ export function useGsapAwareEditing({
);
assertGsapEditPersisted(outcome);
// Saved before the buffered GSAP writes, so their reload stays the gesture's last render.
- if (outcome.status === "element-size")
- await handleDomBoxSizeCommit(selection, next, undefined, undefined, coalesceKey);
- else cropUndoKey = coalesceKey;
+ if (outcome.status === "element-size") {
+ const result = await handleDomBoxSizeCommit(
+ selection,
+ next,
+ undefined,
+ undefined,
+ coalesceKey,
+ );
+ writes.recordDomResult(result);
+ } else cropUndoKey = coalesceKey;
// What the resize did, not what its tweens suggest: a scale hold still commits a size.
const ownsDragOffset =
outcome.status === "persisted" && outcome.ownsDragOffset === true;
@@ -409,21 +308,7 @@ export function useGsapAwareEditing({
});
// A resize that moved the element itself has already written
// where it landed. Everything else leaves the anchor to the drag.
- if (offset && !ownsDragOffset) {
- const dragOutcome = await tryGsapDragIntercept(
- selection,
- offset,
- targetAnimations,
- previewIframeRef.current,
- commitMutation,
- makeFetchFallback(selection),
- );
- // Saved after the size, under its undo key, so the two are one step.
- await saveMove(dragOutcome, async () => {
- const plain = !gsapWritesPosition(selection.element);
- anchorMove = stageElementPositionOffset(selection, offset, plain, coalesceKey);
- });
- }
+ await saveResizeAnchor(ownsDragOffset, commitMutation, coalesceKey);
logResizeSettle(selection.element, ownsDragOffset ? "gsap-scale" : "gsap-size");
return;
} catch (error) {
@@ -434,10 +319,17 @@ export function useGsapAwareEditing({
throw new Error("Resize of a GSAP-owned box has no GSAP writer");
},
afterBufferedCommitsSaved: async () => {
- await anchorMove?.save();
+ const anchorResult = await anchorMove?.save();
+ writes.recordDomResult(anchorResult);
// Only now is the size live for every caller, drag or not.
if (cropUndoKey) {
- await saveCropResize(stageCrop, selection, commitPositionPatchToHtml, cropUndoKey);
+ const cropResult = await saveCropResize(
+ stageCrop,
+ selection,
+ commitPositionPatchToHtml,
+ cropUndoKey,
+ );
+ writes.recordDomResult(cropResult);
}
},
restore: () => {
@@ -446,6 +338,7 @@ export function useGsapAwareEditing({
},
skipPixelAssert: hasLivePositionTween,
});
+ return writes.finish();
},
[
handleDomBoxSizeCommit,
@@ -461,9 +354,12 @@ export function useGsapAwareEditing({
const handleGsapAwareRotationCommit = useCallback(
async (selection: DomEditSelection, next: RotationCommit) => {
- if (next.plain || !gsapWritesRotation(selection.element))
- return handleDomRotationCommit(selection, next);
- if (gsapCommitMutation) {
+ const writes = observeGsapGesture(gsapCommitMutation);
+ if (next.plain || !gsapWritesRotation(selection.element)) {
+ const result = await handleDomRotationCommit(selection, next);
+ return writes.finish(result?.changed === true);
+ }
+ if (writes.commit) {
try {
const targetAnimations = await getGsapAnimationsForSelection(selection);
// A keyframe or a tl.set; a computed source rejects, so the gesture restores its draft.
@@ -472,10 +368,11 @@ export function useGsapAwareEditing({
next.angle,
targetAnimations,
previewIframeRef.current,
- gsapCommitMutation,
+ writes.commit,
makeFetchFallback(selection),
);
assertGsapEditPersisted(outcome);
+ return writes.finish();
} catch (error) {
trackGsapInteractionFailure(error, selection, "rotation", "Rotate animated layer");
throw error;
@@ -564,12 +461,16 @@ export function useGsapAwareEditing({
);
const commitMutation = useCallback(
- async (mutation: Record<string, unknown>, options: { label: string; softReload?: boolean }) => {
- if (!domEditSelection) return;
+ async (
+ mutation: Record<string, unknown>,
+ options: CommitMutationOptions,
+ selection = domEditSelection,
+ ) => {
+ if (!selection) return;
// Return (await) the safe-commit chain so consumers that `await
// session.commitMutation(...)` (gesture recording, enable-keyframes) run
// their post-actions only after the server save has settled.
- await safeGsapCommit(domEditSelection, mutation, options);
+ await safeGsapCommit(selection, mutation, options);
},
[domEditSelection, safeGsapCommit],
);
diff --git a/packages/studio/src/hooks/useGsapAwareGroupMove.ts b/packages/studio/src/hooks/useGsapAwareGroupMove.ts
new file mode 100644
index 0000000000..7b2154ffd5
--- /dev/null
+++ b/packages/studio/src/hooks/useGsapAwareGroupMove.ts
@@ -0,0 +1,179 @@
+import { useCallback } from "react";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { CommitMutationCall, CommitMutationOptions } from "./gsapScriptCommitTypes";
+import type { UseGsapAwareEditingParams } from "./useGsapAwareEditing";
+import { observeGsapGesture } from "./gsapGestureOutcome";
+import { gsapWritesPosition } from "./gsapRuntimeKeyframes";
+import { refuseGsapTakeover } from "./elementOffsetStager";
+import { tryGsapDragIntercept } from "./gsapRuntimeBridge";
+import { assertGsapEditPersisted } from "./gsapEditOutcome";
+
+// A distinct key keeps consecutive group drags in separate undo entries.
+let groupDragCommitCounter = 0;
+
+function firstPreflightFailure(
+ results: PromiseSettledResult<void>[],
+ updates: DomEditGroupPathOffsetCommit[],
+): { error: unknown; selection: DomEditSelection } | null {
+ for (const [index, result] of results.entries()) {
+ if (result.status !== "rejected") continue;
+ const selection = updates[index]?.selection;
+ if (selection) return { error: result.reason, selection };
+ }
+ return null;
+}
+
+export function useGsapAwareGroupMove({
+ gsapCommitMutation,
+ previewIframeRef,
+ makeFetchFallback,
+ trackGsapInteractionFailure,
+ stageElementPositionOffset,
+ showToast,
+}: Pick<
+ UseGsapAwareEditingParams,
+ | "gsapCommitMutation"
+ | "previewIframeRef"
+ | "makeFetchFallback"
+ | "trackGsapInteractionFailure"
+ | "stageElementPositionOffset"
+ | "showToast"
+>) {
+ const handleGsapAwareGroupPathOffsetCommit = useCallback(
+ async (
+ updates: DomEditGroupPathOffsetCommit[],
+ ): Promise<import("../utils/previewFeatureUsage").GeometryCommitResult> => {
+ const writes = observeGsapGesture(gsapCommitMutation);
+ const writer = writes.commit;
+ if (!writer) return { ok: true, changed: false };
+ // One coalesce key across slow writes keeps the group drag in one undo entry.
+ const coalesceKey = `group-drag:${++groupDragCommitCounter}`;
+ // Hold the render until every member is saved, or unwritten members snap back.
+ let renderOnCommit = false;
+ const previewFallbackLatch = { pending: false };
+ const withGroupOptions = (options: CommitMutationOptions): CommitMutationOptions => ({
+ ...options,
+ coalesceKey,
+ coalesceMs: Number.POSITIVE_INFINITY,
+ deferPreviewSync: !renderOnCommit,
+ previewFallbackLatch,
+ });
+ // Batch members in the same file to avoid repeating its read, parse, write and preview patch.
+ const queued: CommitMutationCall[] = [];
+ const flushQueued = async () => {
+ if (queued.length === 0) return;
+ const calls = queued.splice(0, queued.length);
+ if (!writer.batch) {
+ for (const call of calls) {
+ await writer(call.selection, call.mutation, call.options);
+ }
+ return;
+ }
+ await writer.batch(calls, {
+ ...(calls.at(-1)?.options ?? { label: "Move animated layer (group)" }),
+ label: "Move animated layer (group)",
+ });
+ };
+ const coalescedCommit: typeof gsapCommitMutation = (selection, mutation, options) => {
+ queued.push({ selection, mutation, options: withGroupOptions(options) });
+ return Promise.resolve();
+ };
+ const preflightAnimations = new Map<DomEditSelection, GsapAnimation[]>();
+ // Members saved on themselves, each with its route: true for its CSS translate.
+ const offsetMembers = new Map<DomEditSelection, boolean>();
+ // Editability is user-atomic: prove every member can be written before the first source
+ // mutation, so a blocked member never leaves earlier siblings partially moved. Preflights
+ // write nothing and share one in-flight parse per file, so they run together.
+ const preflightResults = await Promise.allSettled(
+ updates.map(async ({ selection, plainTranslate }) => {
+ if (plainTranslate ?? !gsapWritesPosition(selection.element)) {
+ refuseGsapTakeover(selection.element, showToast);
+ return void offsetMembers.set(selection, true);
+ }
+ const animations = await makeFetchFallback(selection, { failOnFetchError: true })();
+ preflightAnimations.set(selection, animations);
+ const outcome = await tryGsapDragIntercept(
+ selection,
+ { x: 0, y: 0 },
+ animations,
+ previewIframeRef.current,
+ coalescedCommit,
+ undefined,
+ { preflightOnly: true, group: true },
+ );
+ if (outcome.status === "element-offset") offsetMembers.set(selection, false);
+ assertGsapEditPersisted(outcome);
+ }),
+ );
+ const preflightFailure = firstPreflightFailure(preflightResults, updates);
+ if (preflightFailure) {
+ trackGsapInteractionFailure(
+ preflightFailure.error,
+ preflightFailure.selection,
+ "drag",
+ "Move animated layer (group)",
+ );
+ throw preflightFailure.error;
+ }
+ const lastScriptWrite = updates.findLastIndex(
+ ({ selection }) => !offsetMembers.has(selection),
+ );
+ for (const [index, { selection, next }] of updates.entries()) {
+ renderOnCommit = index === lastScriptWrite;
+ const plain = offsetMembers.get(selection);
+ if (plain !== undefined) {
+ const result = await stageElementPositionOffset(
+ selection,
+ next,
+ plain,
+ coalesceKey,
+ ).save();
+ writes.recordDomResult(result);
+ continue;
+ }
+ try {
+ const outcome = await tryGsapDragIntercept(
+ selection,
+ next,
+ preflightAnimations.get(selection) ?? [],
+ previewIframeRef.current,
+ coalescedCommit,
+ // The intercept re-reads the file to resolve a stale or shared tween.
+ // Anything already queued has to be on disk before that read, or it
+ // resolves against a file missing writes it is about to build on.
+ async () => {
+ await flushQueued();
+ return makeFetchFallback(selection, { fresh: true })();
+ },
+ { preflightPassed: true },
+ );
+ assertGsapEditPersisted(outcome);
+ } catch (error) {
+ trackGsapInteractionFailure(error, selection, "drag", "Move animated layer (group)");
+ throw error;
+ }
+ }
+ try {
+ await flushQueued();
+ return writes.finish();
+ } catch (error) {
+ // The aggregate write has no uniquely failing member; do not misattribute
+ // its telemetry to whichever member happened to be last in the array.
+ trackGsapInteractionFailure(error, null, "drag", "Move animated layer (group)");
+ throw error;
+ }
+ },
+ [
+ gsapCommitMutation,
+ previewIframeRef,
+ makeFetchFallback,
+ trackGsapInteractionFailure,
+ stageElementPositionOffset,
+ showToast,
+ ],
+ );
+
+ return handleGsapAwareGroupPathOffsetCommit;
+}
diff --git a/packages/studio/src/hooks/useGsapKeyframeOps.sdkUsage.test.tsx b/packages/studio/src/hooks/useGsapKeyframeOps.sdkUsage.test.tsx
new file mode 100644
index 0000000000..8f0a56d961
--- /dev/null
+++ b/packages/studio/src/hooks/useGsapKeyframeOps.sdkUsage.test.tsx
@@ -0,0 +1,114 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useGsapKeyframeOps } from "./useGsapKeyframeOps";
+import type { CutoverResult } from "../utils/sdkCutover";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+const sdkWrite = vi.hoisted(() => vi.fn<(...args: unknown[]) => Promise<CutoverResult>>());
+vi.mock("../utils/sdkCutover", async (original) => ({
+ ...(await original<typeof import("../utils/sdkCutover")>()),
+ sdkGsapKeyframePersist: sdkWrite,
+ sdkGsapConvertToKeyframesPersist: sdkWrite,
+ sdkGsapRemoveAllKeyframesPersist: sdkWrite,
+}));
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+type Params = Parameters<typeof useGsapKeyframeOps>[0];
+let root: Root;
+function mount() {
+ let api: ReturnType<typeof useGsapKeyframeOps> | undefined;
+ const legacy = vi.fn(async () => undefined);
+ function Probe() {
+ api = useGsapKeyframeOps({
+ activeCompPath: "index.html",
+ commitMutation: legacy,
+ commitMutationSafely: legacy,
+ trackGsapSaveFailure: vi.fn(),
+ sdkSession: {} as NonNullable<Params["sdkSession"]>,
+ sdkDeps: {
+ editHistory: { recordEdit: vi.fn(async () => undefined) },
+ writeProjectFile: vi.fn(async () => undefined),
+ reloadPreview: vi.fn(),
+ },
+ });
+ return null;
+ }
+ root = createRoot(document.createElement("div"));
+ act(() => root.render(<Probe />));
+ if (!api) throw new Error("hook did not mount");
+ return { api, legacy };
+}
+const selection = { id: "private-target", sourceFile: "private.html" } as DomEditSelection;
+beforeEach(() => {
+ vi.clearAllMocks();
+ sdkWrite.mockResolvedValue({
+ status: "committed",
+ version: "v2",
+ before: "before",
+ after: "after",
+ });
+});
+afterEach(() => act(() => root.unmount()));
+describe("SDK keyframe usage", () => {
+ it.each(["add", "convert", "remove_all", "reset"] as const)(
+ "counts a changed committed %s operation once",
+ async (action) => {
+ const { api, legacy } = mount();
+ await act(async () => {
+ if (action === "add")
+ await api.addKeyframeBatch(selection, "private-animation", 50, { x: 12, y: 4 });
+ else if (action === "convert") await api.convertToKeyframes(selection, "private-animation");
+ else await api.removeAllKeyframes(selection, "private-animation", action);
+ });
+ expect(legacy).not.toHaveBeenCalled();
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action });
+ },
+ );
+ it("preserves property metadata on a single-property SDK add", async () => {
+ const { api } = mount();
+ await act(async () => api.addKeyframe(selection, "private-animation", 50, "x", 12));
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", {
+ action: "add",
+ property: "x",
+ });
+ });
+ it("does not count unchanged SDK source", async () => {
+ sdkWrite.mockResolvedValue({
+ status: "committed",
+ version: "v2",
+ before: "same",
+ after: "same",
+ });
+ const { api } = mount();
+ await api.addKeyframeBatch(selection, "private-animation", 50, { x: 12 });
+ expect(await api.removeAllKeyframes(selection, "private-animation")).toBe(false);
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ });
+ it("honors intermediate-write suppression in SDK paths", async () => {
+ const { api } = mount();
+ await api.convertToKeyframes(selection, "private-animation", undefined, undefined, {
+ keyframeTelemetry: false,
+ });
+ await api.addKeyframeBatch(
+ selection,
+ "private-animation",
+ 50,
+ { x: 12 },
+ { keyframeTelemetry: false },
+ );
+ await api.removeAllKeyframes(selection, "private-animation", "remove_all", false);
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ });
+ it("does not fall back or count after a failed SDK write", async () => {
+ sdkWrite.mockResolvedValue({ status: "failed", error: new Error("refused") });
+ const { api, legacy } = mount();
+ await expect(
+ api.addKeyframeBatch(selection, "private-animation", 50, { x: 12 }),
+ ).rejects.toThrow("refused");
+ expect(legacy).not.toHaveBeenCalled();
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/studio/src/hooks/useGsapKeyframeOps.ts b/packages/studio/src/hooks/useGsapKeyframeOps.ts
index ca77fe0c0c..16b4b88d15 100644
--- a/packages/studio/src/hooks/useGsapKeyframeOps.ts
+++ b/packages/studio/src/hooks/useGsapKeyframeOps.ts
@@ -1,3 +1,4 @@
+import { trackKeyframeUsage } from "../utils/keyframeUsage";
// fallow-ignore-file code-duplication
// Add/remove operation-family transaction shapes stay parallel until SDK graduation.
import { useCallback } from "react";
@@ -139,10 +140,14 @@ export function useGsapKeyframeOps({
coalesceKey: `gsap:${animationId}:kf:${percentage}`,
},
);
- if (cutoverCommittedOrThrow(handled)) return;
+ if (cutoverCommittedOrThrow(handled)) {
+ if (handled.before !== handled.after) trackKeyframeUsage("add", property);
+ return;
+ }
}
await commitMutation(selection, mutation, {
label: `Add keyframe at ${percentage}%`,
+ keyframeProperty: property,
softReload: true,
});
},
@@ -172,7 +177,11 @@ export function useGsapKeyframeOps({
sdkDeps,
toSdkPersistOptions(`Add keyframe at ${percentage}%`, commitOverrides),
);
- if (cutoverCommittedOrThrow(handled)) return;
+ if (cutoverCommittedOrThrow(handled)) {
+ if (handled.before !== handled.after && commitOverrides?.keyframeTelemetry !== false)
+ trackKeyframeUsage("add");
+ return;
+ }
}
return commitMutation(
selection,
@@ -319,7 +328,11 @@ export function useGsapKeyframeOps({
sdkDeps,
toSdkPersistOptions("Convert to keyframes", commitOverrides),
);
- if (cutoverCommittedOrThrow(handled)) return;
+ if (cutoverCommittedOrThrow(handled)) {
+ if (handled.before !== handled.after && commitOverrides.keyframeTelemetry !== false)
+ trackKeyframeUsage("convert");
+ return;
+ }
}
return commitMutation(
selection,
@@ -333,11 +346,19 @@ export function useGsapKeyframeOps({
);
const removeAllKeyframes = useCallback(
- async (selection: DomEditSelection, animationId: string) => {
+ async (
+ selection: DomEditSelection,
+ animationId: string,
+ action: "remove_all" | "reset" = "remove_all",
+ telemetry = true,
+ ): Promise<boolean> => {
const targetPath = selection.sourceFile || activeCompPath || "index.html";
// A class/descendant selector can resolve a live element whose selection
// deliberately has no id. The cache is still keyed by that DOM id.
- const cacheElementId = selection.id || selection.element?.id;
+ const clearCache = () => {
+ const cacheElementId = selection.id || selection.element?.id;
+ if (cacheElementId) clearKeyframeCacheForElement(targetPath, cacheElementId);
+ };
if (sdkSession && sdkDeps) {
const handled = await sdkGsapRemoveAllKeyframesPersist(
targetPath,
@@ -347,26 +368,31 @@ export function useGsapKeyframeOps({
{ label: "Remove all keyframes" },
);
if (cutoverCommittedOrThrow(handled)) {
- if (cacheElementId) clearKeyframeCacheForElement(targetPath, cacheElementId);
- return;
+ clearCache();
+ const changed = handled.before !== handled.after;
+ if (changed && telemetry) trackKeyframeUsage(action);
+ return changed;
}
}
+ let changed = false;
await commitMutationSafely(
selection,
{ type: "remove-all-keyframes", animationId },
{
label: "Remove all keyframes",
+ keyframeAction: action,
+ keyframeTelemetry: telemetry,
softReload: true,
// The committed result is the single success boundary: clearing
// before it makes failed saves lie, while waiting for the reload leaves
// stale diamonds visible during the source round-trip.
onResult: (result) => {
- if (result.changed !== false && cacheElementId) {
- clearKeyframeCacheForElement(targetPath, cacheElementId);
- }
+ changed = result.ok && result.changed === true;
+ if (changed) clearCache();
},
},
);
+ return changed;
},
[commitMutationSafely, activeCompPath, sdkSession, sdkDeps],
);
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
index c136204e19..3207a25cd0 100644
--- a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
+++ b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
@@ -590,6 +590,63 @@ describe("runCommit — instantPatch wiring", () => {
vi.unstubAllGlobals();
});
+ it.each([
+ ["add-keyframe", "add"],
+ ["add-with-keyframes", "add"],
+ ["convert-to-keyframes", "convert"],
+ ["remove-all-keyframes", "remove_all"],
+ ])("counts %s only after a changed durable write", async (type, action) => {
+ mockFetchResult();
+ const deps = renderCommitHook();
+ await deps.api.commitMutation(
+ selection,
+ { type, properties: { text: "private-content" } },
+ { label: "Edit" },
+ );
+ expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([
+ ["keyframe", { action }],
+ ]);
+ });
+
+ it("counts reset with its explicit action and suppresses intermediate writes", async () => {
+ mockFetchResult();
+ const deps = renderCommitHook();
+ await deps.api.commitMutation(
+ selection,
+ { type: "convert-to-keyframes" },
+ { label: "Convert", keyframeTelemetry: false },
+ );
+ await deps.api.commitMutation(
+ selection,
+ { type: "remove-all-keyframes" },
+ { label: "Reset", keyframeAction: "reset" },
+ );
+ expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([
+ ["keyframe", { action: "reset" }],
+ ]);
+ });
+
+ it("does not count a successful unchanged keyframe write", async () => {
+ mockFetchResult({ changed: false });
+ const deps = renderCommitHook();
+ await deps.api.commitMutation(selection, { type: "add-keyframe" }, { label: "Add" });
+ expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([]);
+ });
+
+ it("does not count a failed write that skipReload suppresses", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async () => ({ ok: false, status: 500 })),
+ );
+ const deps = renderCommitHook();
+ await deps.api.commitMutation(
+ selection,
+ { type: "add-keyframe" },
+ { label: "Add", skipReload: true },
+ );
+ expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([]);
+ });
+
const NESTED_SCRIPT = 'window.__timelines["root"] = tl;';
const SUB = `<template><div data-composition-id="sub"><div id="nwid" style="left: 40px"></div></div></template>`;
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.ts b/packages/studio/src/hooks/useGsapScriptCommits.ts
index a4d78d0d04..eebfb66854 100644
--- a/packages/studio/src/hooks/useGsapScriptCommits.ts
+++ b/packages/studio/src/hooks/useGsapScriptCommits.ts
@@ -11,6 +11,7 @@ import {
} from "../utils/gsapSoftReload";
import type { SoftReloadResult } from "../utils/gsapSoftReload";
import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordinator";
import { trackedStudioEdit } from "../utils/studioPendingEdits";
import {
@@ -391,6 +392,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
mutateGsapScript(pid, targetPath, mutation),
);
if (!result) return;
+ trackKeyframeCommit([mutation], result, options);
options.onResult?.(result);
await finalizeSuccessfulMutation(pid, compositionPath, selection, mutation, targetPath, result, options);
}, [showToast, finalizeSuccessfulMutation]);
@@ -404,6 +406,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
mutateGsapScriptBatch(pid, targetPath, mutations),
);
if (!result) return;
+ trackKeyframeCommit(mutations, result, options, calls.map((call) => call.options));
options.onResult?.(result);
// Each call brings its own fast-path patch; the batch wrote them all, so the
// preview sync applies them all rather than just the last call's.
diff --git a/packages/studio/src/hooks/useGsapSelectionHandlers.test.tsx b/packages/studio/src/hooks/useGsapSelectionHandlers.test.tsx
index 6317c2b249..47b00f805f 100644
--- a/packages/studio/src/hooks/useGsapSelectionHandlers.test.tsx
+++ b/packages/studio/src/hooks/useGsapSelectionHandlers.test.tsx
@@ -42,7 +42,7 @@ function makeParams(overrides: Partial<Params> = {}): Params {
moveKeyframe: vi.fn().mockResolvedValue(true),
resizeKeyframedTween: vi.fn().mockResolvedValue(true),
convertToKeyframes: resolved(),
- removeAllKeyframes: resolved(),
+ removeAllKeyframes: vi.fn().mockResolvedValue(true),
handleDomManualEditsReset: vi.fn(),
selectedGsapAnimations: [],
showToast: vi.fn(),
diff --git a/packages/studio/src/hooks/useGsapSelectionHandlers.ts b/packages/studio/src/hooks/useGsapSelectionHandlers.ts
index 6479061cd5..e7101ffca5 100644
--- a/packages/studio/src/hooks/useGsapSelectionHandlers.ts
+++ b/packages/studio/src/hooks/useGsapSelectionHandlers.ts
@@ -109,9 +109,16 @@ export function useGsapSelectionHandlers({
duration?: number,
commitOverrides?: Partial<CommitMutationOptions>,
) => Promise<void>;
- removeAllKeyframes: (sel: DomEditSelection, animId: string) => Promise<void>;
+ removeAllKeyframes: (
+ sel: DomEditSelection,
+ animId: string,
+ action?: "remove_all" | "reset",
+ telemetry?: boolean,
+ ) => Promise<boolean>;
- handleDomManualEditsReset: (sel: DomEditSelection) => Promise<void>;
+ handleDomManualEditsReset: (
+ sel: DomEditSelection,
+ ) => Promise<void | import("./domEditCommitTypes").DomEditPersistOutcome>;
selectedGsapAnimations: GsapAnimation[];
showToast: (message: string, tone?: "error" | "info") => void;
}) {
@@ -323,7 +330,6 @@ export function useGsapSelectionHandlers({
) => {
const sel = resolveWriteSelection(selectionOverride);
if (!sel) return;
- trackStudioEvent("keyframe", { action: "add", property });
addKeyframe(sel, animId, percentage, property, value);
},
[resolveWriteSelection, addKeyframe],
@@ -441,31 +447,31 @@ export function useGsapSelectionHandlers({
);
const handleGsapRemoveAllKeyframes = useCallback(
- (animId: string, selectionOverride?: DomEditSelection | null) => {
+ (animId: string, selectionOverride?: DomEditSelection | null, telemetry = true) => {
const selection = resolveWriteSelection(selectionOverride);
if (!selection) return Promise.resolve(false);
- return observeGsapMutation(
- removeAllKeyframes(selection, animId),
- selection,
- "remove-all-keyframes",
- "Remove all keyframes",
- );
+ return removeAllKeyframes(selection, animId, "remove_all", telemetry).catch((error) => {
+ trackGsapHandlerFailure(error, selection, "remove-all-keyframes", "Remove all keyframes");
+ return false;
+ });
},
- [resolveWriteSelection, observeGsapMutation, removeAllKeyframes],
+ [resolveWriteSelection, trackGsapHandlerFailure, removeAllKeyframes],
);
const handleResetSelectedElementKeyframes = useCallback((): boolean => {
if (!domEditSelection) return false;
const withKeyframes = selectedGsapAnimations.find((a) => a.keyframes);
if (!withKeyframes) return false;
- observeGsapMutation(
- removeAllKeyframes(domEditSelection, withKeyframes.id),
- domEditSelection,
- "remove-all-keyframes",
- "Remove all keyframes",
- );
+ void removeAllKeyframes(domEditSelection, withKeyframes.id, "reset").catch((error) => {
+ trackGsapHandlerFailure(
+ error,
+ domEditSelection,
+ "remove-all-keyframes",
+ "Remove all keyframes",
+ );
+ });
return true;
- }, [domEditSelection, observeGsapMutation, removeAllKeyframes, selectedGsapAnimations]);
+ }, [domEditSelection, trackGsapHandlerFailure, removeAllKeyframes, selectedGsapAnimations]);
return {
handleGsapUpdateProperty,
diff --git a/packages/studio/src/hooks/usePreviewInteraction.test.ts b/packages/studio/src/hooks/usePreviewInteraction.test.ts
index 7a7013dfb1..6bc79817fa 100644
--- a/packages/studio/src/hooks/usePreviewInteraction.test.ts
+++ b/packages/studio/src/hooks/usePreviewInteraction.test.ts
@@ -299,3 +299,24 @@ describe("a refused move's toast", () => {
]);
});
});
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../utils/studioTelemetry";
+it("counts additive preview selection only after resolving a hit", async () => {
+ vi.mocked(trackStudioEvent).mockClear();
+ const selection = makeSelection("Card", document.createElement("div"));
+ const applyDomSelection = vi.fn();
+ const { canvas, cleanup } = renderHarness({
+ previewIframe: createPreviewIframe(vi.fn()),
+ resolveDomSelectionFromPreviewPoint: vi.fn(async () => selection),
+ applyDomSelection,
+ });
+ await dispatchMouseDown(canvas, { shiftKey: true });
+ expect(applyDomSelection).toHaveBeenCalledWith(selection, { additive: true });
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+ feature: "multi_select",
+ surface: "preview",
+ method: "button",
+ });
+ cleanup();
+});
diff --git a/packages/studio/src/hooks/usePreviewInteraction.ts b/packages/studio/src/hooks/usePreviewInteraction.ts
index 563cc816d8..9b5395307e 100644
--- a/packages/studio/src/hooks/usePreviewInteraction.ts
+++ b/packages/studio/src/hooks/usePreviewInteraction.ts
@@ -1,3 +1,4 @@
+import { trackPreviewFeatureUsed } from "../utils/previewFeatureUsage";
import { useCallback, useRef } from "react";
import { liveTime, usePlayerStore } from "../player";
import { pauseStudioPreviewPlayback } from "../utils/studioPreviewHelpers";
@@ -169,6 +170,7 @@ export function usePreviewInteraction({
e.preventDefault();
e.stopPropagation();
applyDomSelection(nextSelection, { additive: true });
+ trackPreviewFeatureUsed("multi_select", "button");
return;
}
diff --git a/packages/studio/src/utils/keyframeUsage.ts b/packages/studio/src/utils/keyframeUsage.ts
new file mode 100644
index 0000000000..f3a5214471
--- /dev/null
+++ b/packages/studio/src/utils/keyframeUsage.ts
@@ -0,0 +1,79 @@
+import type { CommitMutationOptions, MutationResult } from "../hooks/gsapScriptCommitTypes";
+import { trackStudioEvent } from "./studioTelemetry";
+
+export type KeyframeUsageAction = "add" | "convert" | "remove_all" | "reset";
+
+export function keyframeUsageActions(
+ mutations: ReadonlyArray<Record<string, unknown>>,
+ semanticActions?: ReadonlyArray<KeyframeUsageAction | undefined>,
+): Set<KeyframeUsageAction> {
+ const actions = new Set<KeyframeUsageAction>();
+ for (const [index, mutation] of mutations.entries()) {
+ const semanticAction = semanticActions?.[index];
+ if (semanticAction) {
+ actions.add(semanticAction);
+ continue;
+ }
+ switch (mutation.type) {
+ case "add-keyframe":
+ case "add-with-keyframes":
+ actions.add("add");
+ break;
+ case "convert-to-keyframes":
+ actions.add("convert");
+ break;
+ case "remove-all-keyframes":
+ actions.add("remove_all");
+ break;
+ }
+ }
+ return actions;
+}
+
+export function trackKeyframeUsage(action: KeyframeUsageAction, property?: string): void {
+ trackStudioEvent("keyframe", property === undefined ? { action } : { action, property });
+}
+
+export function primaryKeyframeAction(
+ actions: ReadonlySet<KeyframeUsageAction>,
+): KeyframeUsageAction | undefined {
+ return (["add", "convert", "remove_all", "reset"] as const).find((action) => actions.has(action));
+}
+
+export function changedMutationIndices(
+ result: MutationResult,
+ count: number,
+ options?: ReadonlyArray<Pick<CommitMutationOptions, "keyframeTelemetry">>,
+): number[] {
+ if (!result.ok || result.changed !== true) return [];
+ const changes = count === 1 ? [true] : result.mutationChanges;
+ if (
+ !Array.isArray(changes) ||
+ changes.length !== count ||
+ changes.some((value) => typeof value !== "boolean")
+ )
+ return [];
+ return changes.flatMap((changed, index) =>
+ changed && options?.[index]?.keyframeTelemetry !== false ? [index] : [],
+ );
+}
+
+export function trackKeyframeCommit(
+ mutations: ReadonlyArray<Record<string, unknown>>,
+ result: MutationResult,
+ options: CommitMutationOptions,
+ memberOptions?: ReadonlyArray<CommitMutationOptions>,
+): void {
+ if (!result.ok || result.changed !== true || options.keyframeTelemetry === false) return;
+ const indices = changedMutationIndices(result, mutations.length, memberOptions);
+ const actions = keyframeUsageActions(
+ indices.map((index) => mutations[index]!),
+ indices.map(
+ (index) =>
+ memberOptions?.[index]?.keyframeAction ??
+ (mutations.length === 1 ? options.keyframeAction : undefined),
+ ),
+ );
+ const action = primaryKeyframeAction(actions);
+ if (action) trackKeyframeUsage(action, action === "add" ? options.keyframeProperty : undefined);
+}
diff --git a/packages/studio/src/utils/previewFeatureUsage.test.ts b/packages/studio/src/utils/previewFeatureUsage.test.ts
new file mode 100644
index 0000000000..c6188b9430
--- /dev/null
+++ b/packages/studio/src/utils/previewFeatureUsage.test.ts
@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { trackPreviewEditResult } from "./previewFeatureUsage";
+import { trackStudioEvent } from "./studioTelemetry";
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+beforeEach(() => vi.clearAllMocks());
+describe("preview write usage", () => {
+ it.each([
+ { ok: true, changed: true },
+ {
+ ok: true,
+ persistence: { changed: true, sourceFile: "private.html", content: "private text" },
+ },
+ ])("sends only gesture metadata after a changed result", (result) => {
+ trackPreviewEditResult("resize", "drag", result);
+ expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+ feature: "resize",
+ surface: "preview",
+ method: "drag",
+ });
+ });
+ it.each([
+ undefined,
+ null,
+ {},
+ { ok: false, changed: true },
+ { changed: false },
+ { persistence: { changed: false } },
+ ])("does not count unavailable, failed or unchanged results (%j)", (result) => {
+ trackPreviewEditResult("move", "drag", result);
+ expect(trackStudioEvent).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/studio/src/utils/previewFeatureUsage.ts b/packages/studio/src/utils/previewFeatureUsage.ts
new file mode 100644
index 0000000000..5e06fcd17c
--- /dev/null
+++ b/packages/studio/src/utils/previewFeatureUsage.ts
@@ -0,0 +1,46 @@
+import { trackStudioEvent } from "./studioTelemetry";
+
+export type PreviewFeature =
+ | "move"
+ | "resize"
+ | "rotate"
+ | "crop"
+ | "nudge"
+ | "multi_select"
+ | "z_order"
+ | "text_edit"
+ | "motion_path"
+ | "gesture_recording"
+ | "snapping"
+ | "grid"
+ | "grid_spacing"
+ | "snap_to_grid"
+ | "ruler"
+ | "safe_margins";
+
+export type PreviewMethod = "drag" | "button" | "keyboard" | "field";
+
+export interface GeometryCommitResult {
+ ok: true;
+ changed: boolean;
+}
+
+export function trackPreviewFeatureUsed(feature: PreviewFeature, method: PreviewMethod): void {
+ trackStudioEvent("feature_used", { feature, surface: "preview", method });
+}
+
+export function trackPreviewEditResult(
+ feature: PreviewFeature,
+ method: PreviewMethod,
+ result: unknown,
+): void {
+ if (typeof result !== "object" || result === null) return;
+ if (Reflect.get(result, "ok") === false) return;
+ const persistence = Reflect.get(result, "persistence");
+ const changed =
+ Reflect.get(result, "changed") === true ||
+ (typeof persistence === "object" &&
+ persistence !== null &&
+ Reflect.get(persistence, "changed") === true);
+ if (changed) trackPreviewFeatureUsed(feature, method);
+}
diff --git a/packages/studio/src/utils/studioTelemetry.test.ts b/packages/studio/src/utils/studioTelemetry.test.ts
index 59cffef5b6..f30d45ff1b 100644
--- a/packages/studio/src/utils/studioTelemetry.test.ts
+++ b/packages/studio/src/utils/studioTelemetry.test.ts
@@ -1,5 +1,6 @@
// @vitest-environment happy-dom
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildProjectHash } from "./projectRouting";
// The `studio:*` path predates telemetry/config.ts and shipped its own
// opt-out key and its own send loop, so it sat outside both contracts the
@@ -25,6 +26,8 @@ describe("studioTelemetry — shared opt-out and canary properties", () => {
beforeEach(async () => {
policyState.allowed = true;
localStorage.clear();
+ sessionStorage.clear();
+ window.location.hash = "";
vi.resetModules();
vi.useFakeTimers();
fetchMock = vi.fn(() => Promise.resolve({ ok: true } as Response));
@@ -33,8 +36,10 @@ describe("studioTelemetry — shared opt-out and canary properties", () => {
});
afterEach(() => {
+ window.location.hash = "";
vi.useRealTimers();
vi.unstubAllGlobals();
+ vi.restoreAllMocks();
});
/** Drain the queue and return the events the batch would have sent. */
@@ -87,4 +92,106 @@ describe("studioTelemetry — shared opt-out and canary properties", () => {
"$feature/canary-test-one": "false",
});
});
+
+ it.each(["fetch", "beacon"] as const)(
+ "excludes project names from the complete serialized %s batch",
+ async (transport) => {
+ const projectName = "Launch #1? v2";
+ window.location.hash = buildProjectHash(projectName, { selSelector: "#private-element" });
+ const beacon = vi.fn((_url: string, _body: string) => true);
+ vi.stubGlobal("navigator", { userAgent: "test", sendBeacon: beacon });
+ for (const event of ["feature_used", "keyframe", "design_input", "toolbar_action"]) {
+ trackStudioEvent(event);
+ }
+ if (transport === "beacon") {
+ const { flushViaBeacon } = await import("./studioTelemetry");
+ flushViaBeacon();
+ } else {
+ await vi.runOnlyPendingTimersAsync();
+ }
+ const serialized =
+ transport === "beacon"
+ ? beacon.mock.calls[0]?.[1]
+ : (fetchMock.mock.calls[0]?.[1] as RequestInit)?.body;
+ expect(typeof serialized).toBe("string");
+ const body = serialized as string;
+ expect(body).not.toContain(projectName);
+ expect(body).not.toContain(encodeURIComponent(projectName));
+ expect(body).not.toContain("private-element");
+ expect(body).not.toContain("7aef12cc");
+ const payload = JSON.parse(body);
+ expect(payload.batch).toHaveLength(4);
+ for (const event of payload.batch) {
+ expect(event.properties.url_hash).toBe("project");
+ expect(event.properties.url_route_id).toMatch(/^[0-9a-f]{8}$/);
+ }
+ },
+ );
+
+ it.each([
+ ["", "home"],
+ ["#", "home"],
+ ["#unknown/Launch%20%231%3F%20v2?selection=secret", "other"],
+ ])("sends a finite route kind for %s", async (hash, routeKind) => {
+ window.location.hash = hash;
+ trackStudioEvent("thing_happened");
+ const events = await sentEvents();
+ expect(events[0]?.["properties"]).toMatchObject({ url_hash: routeKind });
+ });
+
+ it("keeps route identity stable across query changes and distinct across projects", async () => {
+ window.location.hash = buildProjectHash("Launch #1? v2");
+ trackStudioEvent("session_start");
+ window.location.hash = buildProjectHash("Launch #1? v2", { selSelector: "#another-element" });
+ trackStudioEvent("feature_used");
+ window.location.hash = buildProjectHash("Another launch");
+ trackStudioEvent("feature_used");
+ const events = await sentEvents();
+ const ids = events.map(
+ (event) => (event["properties"] as Record<string, unknown>)["url_route_id"],
+ );
+ expect(ids[0]).toMatch(/^[0-9a-f]{8}$/);
+ expect(ids[1]).toBe(ids[0]);
+ expect(ids[2]).not.toBe(ids[0]);
+ expect(ids[2]).toMatch(/^[0-9a-f]{8}$/);
+ });
+ it("reuses a route ID after reloading the same tab", async () => {
+ window.location.hash = buildProjectHash("Launch #1? v2");
+ trackStudioEvent("session_start");
+ const first = (await sentEvents())[0]?.properties as Record<string, unknown>;
+ vi.clearAllTimers();
+ vi.resetModules();
+ fetchMock.mockClear();
+ ({ trackStudioEvent } = await import("./studioTelemetry"));
+ trackStudioEvent("session_start");
+ const second = (await sentEvents())[0]?.properties as Record<string, unknown>;
+ expect(second.url_route_id).toBe(first.url_route_id);
+ });
+
+ it("assigns different random IDs to the same route in two tabs", async () => {
+ const random = vi.spyOn(crypto, "getRandomValues");
+ random.mockImplementationOnce((bytes) => {
+ (bytes as Uint8Array).set([1, 2, 3, 4]);
+ return bytes;
+ });
+ window.location.hash = buildProjectHash("Launch #1? v2");
+ trackStudioEvent("session_start");
+ const first = (await sentEvents())[0]?.properties as Record<string, unknown>;
+ // A second independent tab has its own sessionStorage and module instance.
+ sessionStorage.clear();
+ vi.clearAllTimers();
+ vi.resetModules();
+ fetchMock.mockClear();
+ random.mockImplementationOnce((bytes) => {
+ (bytes as Uint8Array).set([5, 6, 7, 8]);
+ return bytes;
+ });
+ ({ trackStudioEvent } = await import("./studioTelemetry"));
+ trackStudioEvent("session_start");
+ const second = (await sentEvents())[0]?.properties as Record<string, unknown>;
+ expect(first.url_route_id).toBe("01020304");
+ expect(second.url_route_id).toBe("05060708");
+ expect(second.url_route_id).not.toBe(first.url_route_id);
+ expect(random).toHaveBeenCalledTimes(2);
+ });
});
diff --git a/packages/studio/src/utils/studioTelemetry.ts b/packages/studio/src/utils/studioTelemetry.ts
index 9edff6cddd..aa59b0184c 100644
--- a/packages/studio/src/utils/studioTelemetry.ts
+++ b/packages/studio/src/utils/studioTelemetry.ts
@@ -1,3 +1,4 @@
+import { parseProjectHashRoute } from "./projectRouting";
import { resolveStudioDistinctId } from "../telemetry/distinctId";
import { browserTelemetryAllowed } from "../telemetry/policy";
import { canaryEventProperties } from "../telemetry/canary";
@@ -41,6 +42,51 @@ function isEnabled(): boolean {
return browserTelemetryAllowed();
}
+function studioRouteKind(hash: string): "project" | "home" | "other" {
+ if (parseProjectHashRoute(hash)) return "project";
+ if (hash === "" || hash === "#") return "home";
+ return "other";
+}
+
+const ROUTE_IDS_KEY = "hyperframes-studio:routeIds";
+let routeIds: Map<string, string> | undefined;
+
+function isRouteIdEntry(entry: unknown): entry is [string, string] {
+ return (
+ Array.isArray(entry) &&
+ entry.length === 2 &&
+ typeof entry[0] === "string" &&
+ typeof entry[1] === "string" &&
+ /^[0-9a-f]{8}$/.test(entry[1])
+ );
+}
+
+function readRouteIds(): Map<string, string> {
+ try {
+ const stored: unknown = JSON.parse(sessionStorage.getItem(ROUTE_IDS_KEY) ?? "[]");
+ return new Map(Array.isArray(stored) ? stored.filter(isRouteIdEntry) : []);
+ } catch {
+ // Storage may be blocked or corrupt. Keep random IDs in memory instead.
+ return new Map();
+ }
+}
+
+function studioRouteId(hash: string): string {
+ routeIds ??= readRouteIds();
+ const route = hash.split("?")[0];
+ const existing = routeIds.get(route);
+ if (existing !== undefined) return existing;
+ const bytes = crypto.getRandomValues(new Uint8Array(4));
+ const id = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+ routeIds.set(route, id);
+ try {
+ sessionStorage.setItem(ROUTE_IDS_KEY, JSON.stringify([...routeIds]));
+ } catch {
+ // The in-memory map still preserves equality when storage is unavailable.
+ }
+ return id;
+}
+
function getSessionProperties(): EventProperties {
return {
studio_version: typeof __STUDIO_VERSION__ !== "undefined" ? __STUDIO_VERSION__ : "dev",
@@ -57,10 +103,9 @@ function getSessionProperties(): EventProperties {
viewport_width: window.innerWidth,
viewport_height: window.innerHeight,
user_agent: navigator.userAgent,
- // Route slug only — drop the query string, which carries the current
- // selection (selId / selSelector are the user's own element ids/CSS
- // selectors) and other view state we must not send to analytics.
- url_hash: location.hash.replace(/#project\//, "").split("?")[0],
+ // Route names and query parameters are user content. Send only the route kind.
+ url_hash: studioRouteKind(location.hash),
+ url_route_id: studioRouteId(location.hash),
};
}
diff --git a/packages/studio/src/webmcp/StudioAgentTools.tsx b/packages/studio/src/webmcp/StudioAgentTools.tsx
index 0b20cb0696..808e332e71 100644
--- a/packages/studio/src/webmcp/StudioAgentTools.tsx
+++ b/packages/studio/src/webmcp/StudioAgentTools.tsx
@@ -31,13 +31,13 @@ type ResizeCommit = (
next: { width: number; height: number },
offset?: { x: number; y: number },
restore?: () => void,
-) => Promise<void>;
+) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
export function resizeSelectionFromAgent(
selection: DomEditSelection,
next: { width: number; height: number },
commit: ResizeCommit,
-): Promise<void> {
+): Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult> {
const previous = captureStudioBoxSize(selection.element);
applyStudioBoxSizeDraft(selection.element, next);
return commit(selection, next, undefined, () => {