@hyperframes/studio 0.8.114 → 0.8.115

package/src/components/sidebar/AssetContextMenu.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { filename } from "./assetHelpers";
+import { menuClasses } from "../ui/menuStyle";
 
 /** Reject names that would escape the asset directory or break paths. */
 function isValidAssetName(name: string): boolean {
@@ -94,8 +95,7 @@ export function ContextMenu({
     onClose();
   }, [renameDraft, asset, onRename, onClose]);
 
-  const itemCls =
-    "w-full text-left px-3 py-1.5 text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 outline-hidden active:bg-neutral-700/70 transition-colors";
+  const itemCls = `${menuClasses.row} ${menuClasses.rowEnabled} active:bg-neutral-700/70 transition-colors`;
 
   return (
     <div
@@ -110,7 +110,7 @@ export function ContextMenu({
         ref={menuRef}
         role="menu"
         aria-label={`Actions for ${filename(asset)}`}
-        className="absolute bg-neutral-900 border border-neutral-700 rounded-lg shadow-xl py-1 min-w-[160px] text-xs"
+        className={`${menuClasses.panel} absolute min-w-[160px] text-xs`}
         style={{ left: pos.x, top: pos.y }}
         onClick={(e) => e.stopPropagation()}
       >
@@ -147,7 +147,7 @@ export function ContextMenu({
               <button
                 role="menuitem"
                 onClick={() => setMode("confirm-delete")}
-                className={`${itemCls} text-danger-ink`}
+                className={`${menuClasses.row} ${menuClasses.rowDanger} active:bg-neutral-700/70 transition-colors`}
               >
                 Delete
               </button>

package/src/components/ui/menuStyle.test.ts

@@ -0,0 +1,61 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { describe, expect, it } from "vitest";
+import { menuClasses } from "./menuStyle";
+
+const spacing = /(^| )-?(p|py|pt|pb|m|my|mt|mb)-\d/;
+const root = join(__dirname, "../..");
+
+/** Panels that are not a column of rows: a dialog, a crop toolbar, a preset card and a bare speed list. */
+const NOT_ROW_MENUS = new Set([
+  "player/components/AudioGainDialog.tsx",
+  "components/editor/CropPresetBar.tsx",
+  "components/editor/EaseCurveSection.tsx",
+  "player/components/SpeedMenu.tsx",
+]);
+
+function sources(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) return sources(path);
+    return /\.tsx$/.test(name) && !/\.test\./.test(name) ? [path] : [];
+  });
+}
+
+const files = sources(root).map((path) => ({
+  name: relative(root, path).replaceAll("\\", "/"),
+  text: readFileSync(path, "utf8"),
+}));
+
+describe("menu style", () => {
+  it("adds no padding or margin around a menu's rows", () => {
+    for (const key of ["panel", "group", "divider"] as const)
+      expect(menuClasses[key], key).not.toMatch(spacing);
+  });
+
+  it("clips the panel to its own rounded corners, so a highlight never pokes out of them", () => {
+    expect(menuClasses.panel).toContain("overflow-hidden");
+    expect(menuClasses.panel).toMatch(/(^| )rounded-/);
+  });
+
+  it("is the only place a menu panel's fill, border and shadow are written", () => {
+    const handBuilt = files
+      .filter(({ name }) => !NOT_ROW_MENUS.has(name))
+      .filter(({ text }) =>
+        [...text.matchAll(/["'`]([^"'`]*)["'`]/g)].some(
+          ([, literal]) =>
+            /shadow-(lg|xl)/.test(literal!) && /bg-(neutral-900|panel-bg-2)\b/.test(literal!),
+        ),
+      )
+      .map(({ name }) => name);
+    expect(handBuilt).toEqual([]);
+  });
+
+  it("is the panel of every role=menu, wherever its element is written", () => {
+    const unowned = files
+      .filter(({ text }) => text.includes('role="menu"'))
+      .filter(({ name, text }) => !NOT_ROW_MENUS.has(name) && !text.includes("menuClasses.panel"))
+      .map(({ name }) => name);
+    expect(unowned).toEqual([]);
+  });
+});

package/src/components/ui/menuStyle.ts

@@ -0,0 +1,10 @@
+/** The one owner of context menu spacing: rows touch the panel, which clips to its rounded corners. */
+export const menuClasses = {
+  panel: "overflow-hidden rounded-md border border-neutral-700 bg-neutral-900 shadow-lg",
+  group: "empty:hidden border-b border-neutral-700/60",
+  divider: "border-t border-neutral-700/60",
+  row: "w-full px-3 py-1.5 text-left text-xs outline-hidden",
+  rowEnabled: "text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 cursor-pointer",
+  rowDanger: "text-danger-ink hover:bg-danger/25 focus-visible:bg-danger/25 cursor-pointer",
+  rowDisabled: "text-neutral-600 cursor-not-allowed",
+} as const;

package/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),
     [],
   );
 

package/src/contexts/TimelineEditContext.tsx

@@ -46,6 +46,7 @@ const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {
   onRazorSplit: true,
   onRazorSplitAll: true,
   onFreezeFrame: true,
+  clipMenuTools: true,
   onNotice: true,
   onDeleteKeyframe: true,
   onDeleteAllKeyframes: true,

package/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";

package/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 {

package/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);

package/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[]>;
 }
 

package/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}`;

package/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();
+});

package/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 };
+    },
+  };
+}

package/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 },
       );
     }
 

package/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();
+});

package/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() };

package/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;

package/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" });
+});