@hyperframes/studio 0.7.75 → 0.7.77

package/src/hooks/useDomSelection.ts

@@ -24,6 +24,7 @@ import {
   type DomEditSelection,
 } from "../components/editor/domEditing";
 import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits";
+import { useStudioTestHooks } from "./useStudioTestHooks";
 
 // ── Types ──
 
@@ -506,6 +507,9 @@ export function useDomSelection({
     applyDomSelection(null, { revealPanel: false });
   }, [applyDomSelection, captionEditMode]);
 
+  // Dev-only headless-QA shortcut (window.__studioTest.selectByDomId). No-op in prod.
+  useStudioTestHooks({ previewIframeRef, buildDomSelectionFromTarget, applyDomSelection });
+
   const applyMarqueeSelection = useCallback(
     // fallow-ignore-next-line complexity
     (selections: DomEditSelection[], additive: boolean) => {

package/src/hooks/useEnableKeyframes.test.ts

@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
+  applyArcKeyframeAtPlayhead,
   animatedProps,
   buildExtendedKeyframes,
   isPlayheadWithinTween,
@@ -107,6 +108,19 @@ describe("isPlayheadWithinTween", () => {
   it("does not block when the start can't be resolved", () => {
     expect(isPlayheadWithinTween(anim({ position: "+=1" }), 99)).toBe(true);
   });
+
+  // The toolbar's "extends animation" tooltip has to agree with what the edit
+  // paths do. Those span a duration-less tween across its clip, so answering
+  // from GSAP's 0.5s default reported the playhead outside a window the click
+  // then treated as clip-wide.
+  it("spans the clip for a duration-less tween when given the selection", () => {
+    const durationless = anim({ position: 0 });
+    const selection = { dataAttributes: { duration: "16" } } as unknown as DomEditSelection;
+
+    expect(isPlayheadWithinTween(durationless, 5)).toBe(false);
+    expect(isPlayheadWithinTween(durationless, 5, selection)).toBe(true);
+    expect(isPlayheadWithinTween(durationless, 20, selection)).toBe(false);
+  });
 });
 
 describe("buildExtendedKeyframes", () => {
@@ -219,6 +233,114 @@ describe("promoteSetToKeyframes — auto endpoint", () => {
   });
 });
 
+describe("applyArcKeyframeAtPlayhead", () => {
+  const arcAnim = anim({
+    id: "#el-to-0-position",
+    position: 0,
+    duration: 10,
+    keyframes: {
+      format: "object-array",
+      keyframes: [
+        { percentage: 0, properties: { x: 0, y: 0 } },
+        { percentage: 50, properties: { x: 50, y: 50 } },
+        { percentage: 100, properties: { x: 100, y: 0 } },
+      ],
+    },
+    arcPath: {
+      enabled: true,
+      autoRotate: false,
+      segments: [{ curviness: 1 }, { curviness: 1 }],
+    },
+  });
+
+  function arcFixture(x: number, y: number) {
+    const commitMutation = vi.fn(async () => undefined);
+    const session = { commitMutation } as unknown as EnableKeyframesSession;
+    const sel = {
+      id: "el",
+      selector: "#el",
+      element: { isConnected: true } as HTMLElement,
+      dataAttributes: { duration: "10" },
+    } as DomEditSelection;
+    const iframe = {
+      contentWindow: {
+        gsap: { getProperty: (_element: Element, property: string) => (property === "x" ? x : y) },
+      },
+    } as unknown as HTMLIFrameElement;
+    return { commitMutation, iframe, sel, session };
+  }
+
+  it("removes an existing interior stop without redistributing the remaining times", async () => {
+    const fixture = arcFixture(50, 50);
+    await applyArcKeyframeAtPlayhead(fixture.session, fixture.sel, arcAnim, 5, fixture.iframe);
+    expect(fixture.commitMutation).toHaveBeenCalledWith(
+      {
+        type: "replace-with-keyframes",
+        animationId: arcAnim.id,
+        targetSelector: "#el",
+        position: 0,
+        duration: 10,
+        keyframes: [
+          { percentage: 0, properties: { x: 0, y: 0 } },
+          { percentage: 100, properties: { x: 100, y: 0 } },
+        ],
+        ease: "none",
+      },
+      { label: "Remove keyframe", softReload: true },
+    );
+  });
+
+  it("preserves the path endpoints", async () => {
+    const fixture = arcFixture(0, 0);
+    await applyArcKeyframeAtPlayhead(fixture.session, fixture.sel, arcAnim, 0, fixture.iframe);
+    expect(fixture.commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("adds a temporal keyframe at the exact playhead while preserving authored times", async () => {
+    const fixture = arcFixture(25, 25);
+    await applyArcKeyframeAtPlayhead(fixture.session, fixture.sel, arcAnim, 2.5, fixture.iframe);
+    expect(fixture.commitMutation).toHaveBeenCalledWith(
+      {
+        type: "replace-with-keyframes",
+        animationId: arcAnim.id,
+        targetSelector: "#el",
+        position: 0,
+        duration: 10,
+        keyframes: [
+          { percentage: 0, properties: { x: 0, y: 0 } },
+          { percentage: 25, properties: { x: 25, y: 25 } },
+          { percentage: 50, properties: { x: 50, y: 50 } },
+          { percentage: 100, properties: { x: 100, y: 0 } },
+        ],
+        ease: "none",
+      },
+      { label: "Add keyframe", softReload: true },
+    );
+  });
+
+  it("uses the owning clip duration when an arc omits its outer duration", async () => {
+    const fixture = arcFixture(25, 25);
+    const durationlessArc = { ...arcAnim, duration: undefined };
+
+    await applyArcKeyframeAtPlayhead(
+      fixture.session,
+      fixture.sel,
+      durationlessArc,
+      2.5,
+      fixture.iframe,
+    );
+
+    expect(fixture.commitMutation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "replace-with-keyframes",
+        duration: 10,
+        keyframes: expect.arrayContaining([{ percentage: 25, properties: { x: 25, y: 25 } }]),
+      }),
+      { label: "Add keyframe", softReload: true },
+    );
+  });
+});
+
 function renderEnableKeyframes(session: EnableKeyframesSession): () => Promise<void> {
   let enable: (() => Promise<void>) | null = null;
   function Probe() {

package/src/hooks/useEnableKeyframes.ts

@@ -12,16 +12,23 @@ import type { GsapAnimation, GsapPercentageKeyframe } from "@hyperframes/core/gs
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
-import { selectorFromSelection, computeElementPercentage, isInstantHold } from "./gsapShared";
 import {
+  selectorFromSelection,
+  computeElementPercentage,
+  KEYFRAME_PCT_MATCH,
+  isInstantHold,
+  resolveEditableTweenDuration,
+} from "./gsapShared";
+import {
+  absoluteToPercentage,
   resolveTweenStart,
   resolveTweenDuration,
   isTimeWithinTween,
 } from "../utils/globalTimeCompiler";
 import { POSITION_PROPS } from "./gsapRuntimeReaders";
 import { roundTo3 } from "../utils/rounding";
-import { nearestPointOnPath } from "../components/editor/motionPathGeometry";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+import { buildTemporalArcKeyframes } from "./gsapDragPositionCommit";
 
 let enableKeyframesTransactionCounter = 0;
 
@@ -71,11 +78,22 @@ export function animatedProps(anim: GsapAnimation | null): string[] {
  * Whether the playhead sits inside an animation's tween range. When the tween's
  * start can't be resolved we don't block (the percentage falls back to clip range,
  * preserving prior behavior for elements without explicit timing).
+ *
+ * Pass the selection whenever the caller has one: a duration-less tween spans
+ * its clip, and answering from GSAP's 0.5s default reports the playhead outside
+ * a window the edit paths treat as clip-wide.
  */
-export function isPlayheadWithinTween(anim: GsapAnimation, currentTime: number): boolean {
+export function isPlayheadWithinTween(
+  anim: GsapAnimation,
+  currentTime: number,
+  selection?: DomEditSelection | null,
+): boolean {
   const start = resolveTweenStart(anim);
   if (start === null) return true;
-  return isTimeWithinTween(currentTime, start, resolveTweenDuration(anim));
+  const duration = selection
+    ? resolveEditableTweenDuration(anim, selection)
+    : resolveTweenDuration(anim);
+  return isTimeWithinTween(currentTime, start, duration);
 }
 
 /**
@@ -89,9 +107,10 @@ export function buildExtendedKeyframes(
   anim: GsapAnimation,
   currentTime: number,
   position: Record<string, number>,
+  sourceDuration = resolveTweenDuration(anim),
 ): { position: number; duration: number; keyframes: GsapPercentageKeyframe[] } {
   const oldStart = resolveTweenStart(anim) ?? 0;
-  const oldDuration = resolveTweenDuration(anim);
+  const oldDuration = sourceDuration;
   const newStart = Math.min(oldStart, currentTime);
   const newEnd = Math.max(oldStart + oldDuration, currentTime);
   const newDuration = roundTo3(newEnd - newStart);
@@ -222,6 +241,37 @@ async function fetchAnimationsForElement(sel: DomEditSelection): Promise<GsapAni
   return (await tryFetchAnimationsForElement(sel)) ?? [];
 }
 
+async function extendKeyframedTweenToPlayhead(
+  session: EnableKeyframesSession,
+  sel: DomEditSelection,
+  anim: GsapAnimation,
+  currentTime: number,
+  duration: number,
+  iframe: HTMLIFrameElement | null,
+  commitOverrides?: Partial<CommitMutationOptions>,
+): Promise<void> {
+  const selector = selectorFromSelection(sel);
+  const position = readElementPosition(iframe, sel, anim);
+  if (!selector || Object.keys(position).length === 0 || !session.commitMutation) return;
+  const extended = buildExtendedKeyframes(anim, currentTime, position, duration);
+  await session.commitMutation(
+    {
+      type: "replace-with-keyframes",
+      animationId: anim.id,
+      targetSelector: selector,
+      position: extended.position,
+      duration: extended.duration,
+      keyframes: extended.keyframes,
+      ease: anim.ease,
+    },
+    {
+      label: "Add keyframe",
+      softReload: true,
+      ...commitOverrides,
+    },
+  );
+}
+
 /**
  * Apply "add keyframe at playhead" to a tween that already has x/y keyframes:
  * toggle off an existing stop, add one at the playhead's tween-relative %, or —
@@ -237,32 +287,25 @@ async function applyKeyframeAtPlayhead(
   iframe: HTMLIFrameElement | null,
   commitOverrides?: Partial<CommitMutationOptions>,
 ): Promise<void> {
-  if (!isPlayheadWithinTween(kfAnim, t)) {
-    const position = readElementPosition(iframe, sel, kfAnim);
-    const selector = selectorFromSelection(sel);
-    if (selector && Object.keys(position).length > 0 && session.commitMutation) {
-      const extended = buildExtendedKeyframes(kfAnim, t, position);
-      await session.commitMutation(
-        {
-          type: "replace-with-keyframes",
-          animationId: kfAnim.id,
-          targetSelector: selector,
-          position: extended.position,
-          duration: extended.duration,
-          keyframes: extended.keyframes,
-          ease: kfAnim.ease,
-        },
-        {
-          label: "Add keyframe",
-          softReload: true,
-          ...commitOverrides,
-        },
-      );
-    }
+  const duration = resolveEditableTweenDuration(kfAnim, sel);
+  const start = resolveTweenStart(kfAnim);
+  if (start !== null && !isTimeWithinTween(t, start, duration)) {
+    await extendKeyframedTweenToPlayhead(
+      session,
+      sel,
+      kfAnim,
+      t,
+      duration,
+      iframe,
+      commitOverrides,
+    );
     return;
   }
-  const pct = computeElementPercentage(t, sel, kfAnim);
-  const existing = kfAnim.keyframes?.keyframes.find((k) => Math.abs(k.percentage - pct) <= 1);
+  const pct =
+    start === null ? computeElementPercentage(t, sel) : absoluteToPercentage(t, start, duration);
+  const existing = kfAnim.keyframes?.keyframes.find(
+    (k) => Math.abs(k.percentage - pct) <= KEYFRAME_PCT_MATCH,
+  );
   if (existing) {
     session.handleGsapRemoveKeyframe(kfAnim.id, existing.percentage);
     return;
@@ -332,14 +375,13 @@ export async function promoteSetToKeyframes(
 }
 
 /**
- * An arc (motionPath) tween — its waypoints are reconstructed onto `keyframes`, so
- * it must be edited as waypoints (not x/y keyframes, which would break the curve).
- * "Add keyframe at playhead" drops a waypoint where the element currently sits on
- * the path, inserted at the matching segment so the curve is preserved. Outside the
- * range, extend the duration so the motion reaches the playhead.
+ * Convert an arc (motionPath) tween to temporal x/y keyframes before toggling the
+ * playhead stop. A toolbar command named "Add keyframe at playhead" must preserve
+ * every authored stop's time; inserting a spatial waypoint instead redistributes
+ * the path and can silently compress the animation.
  */
 // fallow-ignore-next-line complexity
-async function applyArcWaypointAtPlayhead(
+export async function applyArcKeyframeAtPlayhead(
   session: EnableKeyframesSession,
   sel: DomEditSelection,
   arcAnim: GsapAnimation,
@@ -347,8 +389,11 @@ async function applyArcWaypointAtPlayhead(
   iframe: HTMLIFrameElement | null,
 ): Promise<void> {
   if (!session.commitMutation) return;
-  if (!isPlayheadWithinTween(arcAnim, t)) {
-    const start = resolveTweenStart(arcAnim) ?? 0;
+  const targetSelector = selectorFromSelection(sel);
+  if (!targetSelector) return;
+  const start = resolveTweenStart(arcAnim) ?? 0;
+  const duration = resolveEditableTweenDuration(arcAnim, sel);
+  if (!isTimeWithinTween(t, start, duration)) {
     if (t > start) {
       await session.commitMutation(
         {
@@ -361,30 +406,45 @@ async function applyArcWaypointAtPlayhead(
     }
     return;
   }
+  const nodes = arcAnim.keyframes?.keyframes ?? [];
+  const playheadPercentage = absoluteToPercentage(t, start, duration);
+  const timedNodeIndex = nodes.findIndex(
+    (node) => Math.abs(node.percentage - playheadPercentage) <= KEYFRAME_PCT_MATCH,
+  );
+  if (timedNodeIndex !== -1) {
+    if (timedNodeIndex > 0 && timedNodeIndex < nodes.length - 1) {
+      await session.commitMutation(
+        {
+          type: "replace-with-keyframes",
+          animationId: arcAnim.id,
+          targetSelector,
+          position: roundTo3(start),
+          duration: roundTo3(duration),
+          keyframes: nodes.filter((_, index) => index !== timedNodeIndex),
+          ease: "none",
+        },
+        { label: "Remove keyframe", softReload: true },
+      );
+    }
+    return;
+  }
+
   const live = readElementPosition(iframe, sel, arcAnim);
   if (typeof live.x !== "number" || typeof live.y !== "number") return;
-  const liveX = live.x;
-  const liveY = live.y;
-  const nodes = (arcAnim.keyframes?.keyframes ?? [])
-    .map((k) => ({ x: k.properties.x, y: k.properties.y }))
-    .filter(
-      (p): p is { x: number; y: number } => typeof p.x === "number" && typeof p.y === "number",
-    );
-  // Don't duplicate a waypoint that already sits where the element is (e.g. at the
-  // path endpoints).
-  const WAYPOINT_MERGE_PX = 6;
-  if (nodes.some((n) => Math.hypot(n.x - liveX, n.y - liveY) <= WAYPOINT_MERGE_PX)) return;
-  const proj = nearestPointOnPath(liveX, liveY, nodes);
-  if (!proj) return;
   await session.commitMutation(
     {
-      type: "add-motion-path-point",
+      type: "replace-with-keyframes",
       animationId: arcAnim.id,
-      index: proj.segIndex + 1,
-      x: liveX,
-      y: liveY,
+      targetSelector,
+      position: roundTo3(start),
+      duration: roundTo3(duration),
+      keyframes: buildTemporalArcKeyframes(arcAnim, playheadPercentage, {
+        x: live.x,
+        y: live.y,
+      }),
+      ease: "none",
     },
-    { label: "Add waypoint", softReload: true },
+    { label: "Add keyframe", softReload: true },
   );
 }
 
@@ -420,7 +480,7 @@ export function useEnableKeyframes(
     const flatAnim = anims.find((a) => !a.keyframes && !a.arcPath && !isInstantHold(a));
 
     if (arcAnim) {
-      await applyArcWaypointAtPlayhead(session, sel, arcAnim, t, iframe);
+      await applyArcKeyframeAtPlayhead(session, sel, arcAnim, t, iframe);
     } else if (kfAnim) {
       await applyKeyframeAtPlayhead(session, sel, kfAnim, t, iframe);
     } else if (setAnim) {

package/src/hooks/useGestureCommit.ts

@@ -13,7 +13,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
 import { roundTo3 } from "../utils/rounding";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
-import { isInstantHold } from "./gsapShared";
+import { isInstantHold, idSelector } from "./gsapShared";
 
 type RecordedKeyframe = {
   percentage: number;
@@ -168,7 +168,7 @@ export function useGestureCommit({
         if (!sortedPcts.includes(0)) sortedPcts.unshift(0);
       }
 
-      const selector = sel.id ? `#${sel.id}` : sel.selector;
+      const selector = sel.id ? idSelector(sel.id) : sel.selector;
       if (!selector) {
         showToast("Cannot save — element has no selector", "error");
         return;

package/src/hooks/useGsapAnimationFetchFallback.ts

@@ -36,7 +36,7 @@ export type ElementAnimationsOutcome =
  * so the caller can apply the right retry budget to each.
  */
 export function selectElementAnimationsOrRetry(
-  parsed: ParsedGsap | null,
+  parsed: Pick<ParsedGsap, "animations"> | null,
   target: { id: string | null; selector: string | null },
 ): ElementAnimationsOutcome {
   if (!parsed) return { kind: "fetch-error" };

package/src/hooks/useGsapKeyframeOps.test.tsx

@@ -19,11 +19,21 @@ afterEach(() => {
 
 const selection: DomEditSelection = { id: "box", selector: "#box" } as DomEditSelection;
 
+function successfulCommitMutation() {
+  return vi.fn<(...args: unknown[]) => Promise<unknown>>(async (...args) => {
+    const options = args[2] as {
+      onResult?: (result: { ok: boolean; changed: boolean }) => void;
+    };
+    options.onResult?.({ ok: true, changed: true });
+  });
+}
+
 function renderKeyframeOps(over: {
   commitMutation: (...args: unknown[]) => Promise<unknown>;
   trackGsapSaveFailure: (...args: unknown[]) => void;
 }) {
   const captured: { api: HookApi | null } = { api: null };
+  // This hook harness intentionally mirrors the separate script-commit harness.
   function Probe() {
     // fallow-ignore-next-line code-duplication
     captured.api = useGsapKeyframeOps({
@@ -49,11 +59,21 @@ function renderKeyframeOps(over: {
   return captured.api;
 }
 
+async function moveKeyframeWith(
+  commitMutation: (...args: unknown[]) => Promise<unknown>,
+): Promise<{ committed: boolean; trackGsapSaveFailure: ReturnType<typeof vi.fn> }> {
+  const trackGsapSaveFailure = vi.fn();
+  const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure });
+  let committed = true;
+  await act(async () => {
+    committed = await api.moveKeyframe(selection, "box-to-0-position", 50, 75);
+  });
+  return { committed, trackGsapSaveFailure };
+}
+
 describe("useGsapKeyframeOps — resizeKeyframedTween", () => {
   it("issues a resize-keyframed-tween mutation with the remap + window", async () => {
-    const commitMutation = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => ({
-      ok: true,
-    }));
+    const commitMutation = successfulCommitMutation();
     const trackGsapSaveFailure = vi.fn<(...args: unknown[]) => void>();
     const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure });
 
@@ -61,8 +81,9 @@ describe("useGsapKeyframeOps — resizeKeyframedTween", () => {
       { from: 0, to: 0 },
       { from: 100, to: 100 },
     ];
+    let committed = false;
     await act(async () => {
-      api.resizeKeyframedTween(selection, "box-to-0-opacity", 0.2, 2, pctRemap);
+      committed = await api.resizeKeyframedTween(selection, "box-to-0-opacity", 0.2, 2, pctRemap);
     });
 
     expect(commitMutation).toHaveBeenCalledTimes(1);
@@ -76,6 +97,7 @@ describe("useGsapKeyframeOps — resizeKeyframedTween", () => {
       pctRemap,
     });
     expect(trackGsapSaveFailure).not.toHaveBeenCalled();
+    expect(committed).toBe(true);
   });
 
   it("routes a rejected commit to trackGsapSaveFailure (no unhandled rejection)", async () => {
@@ -86,10 +108,11 @@ describe("useGsapKeyframeOps — resizeKeyframedTween", () => {
     const trackGsapSaveFailure = vi.fn<(...args: unknown[]) => void>();
     const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure });
 
+    let committed = true;
     await act(async () => {
-      api.resizeKeyframedTween(selection, "box-to-0-opacity", 0.2, 2, [{ from: 100, to: 100 }]);
-      // let the rejected commit promise settle inside act
-      await Promise.resolve();
+      committed = await api.resizeKeyframedTween(selection, "box-to-0-opacity", 0.2, 2, [
+        { from: 100, to: 100 },
+      ]);
     });
 
     expect(trackGsapSaveFailure).toHaveBeenCalledTimes(1);
@@ -98,14 +121,72 @@ describe("useGsapKeyframeOps — resizeKeyframedTween", () => {
     expect(selArg).toBe(selection);
     expect((mutationArg as { type: string }).type).toBe("resize-keyframed-tween");
     expect(labelArg).toBe("Retime keyframe (resize tween)");
+    expect(committed).toBe(false);
+  });
+});
+
+describe("useGsapKeyframeOps — moveKeyframe settlement", () => {
+  it("returns false when the commit settles without a durable writer result", async () => {
+    const { committed, trackGsapSaveFailure } = await moveKeyframeWith(vi.fn(async () => {}));
+
+    expect(committed).toBe(false);
+    expect(trackGsapSaveFailure).not.toHaveBeenCalled();
+  });
+
+  it("returns false when the writer accepts but does not change the keyframe", async () => {
+    const commitMutation = vi.fn(async (...args: unknown[]) => {
+      const options = args[2] as { onResult?: (result: { ok: boolean; changed: boolean }) => void };
+      options.onResult?.({ ok: true, changed: false });
+    });
+    const { committed, trackGsapSaveFailure } = await moveKeyframeWith(commitMutation);
+
+    expect(committed).toBe(false);
+    expect(trackGsapSaveFailure).not.toHaveBeenCalled();
+  });
+
+  it("returns false and tracks a rejected move", async () => {
+    const error = new Error("write failed");
+    const commitMutation = vi.fn().mockRejectedValue(error);
+    const { committed, trackGsapSaveFailure } = await moveKeyframeWith(commitMutation);
+
+    expect(committed).toBe(false);
+    expect(trackGsapSaveFailure).toHaveBeenCalledExactlyOnceWith(
+      error,
+      selection,
+      {
+        type: "move-keyframe",
+        animationId: "box-to-0-position",
+        fromPercentage: 50,
+        toPercentage: 75,
+      },
+      "Move keyframe to 75%",
+    );
   });
 });
 
 describe("useGsapKeyframeOps — keyframe transaction options", () => {
+  it("routes a flat-lane add through the add-keyframe writer mutation", async () => {
+    const commitMutation = successfulCommitMutation();
+    const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure: vi.fn() });
+
+    await act(async () => {
+      await api.addKeyframeBatch(selection, "box-to-0-position", 50, { x: 210 });
+    });
+
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      {
+        type: "add-keyframe",
+        animationId: "box-to-0-position",
+        percentage: 50,
+        properties: { x: 210 },
+      },
+      { label: "Add keyframe at 50%", softReload: true },
+    );
+  });
+
   it("soft-reloads a standalone convert when the SDK path is unavailable", async () => {
-    const commitMutation = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => ({
-      ok: true,
-    }));
+    const commitMutation = successfulCommitMutation();
     const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure: vi.fn() });
 
     await act(async () => {
@@ -123,9 +204,7 @@ describe("useGsapKeyframeOps — keyframe transaction options", () => {
   });
 
   it("threads one coalesce key through skipped convert reload and terminal batch edit", async () => {
-    const commitMutation = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => ({
-      ok: true,
-    }));
+    const commitMutation = successfulCommitMutation();
     const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure: vi.fn() });
     const coalesceKey = "enable-keyframes:box-to-0-opacity:1";