@hyperframes/studio 0.7.76 → 0.7.78

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

package/src/hooks/useGsapKeyframeOps.ts

@@ -15,6 +15,7 @@ import {
 } from "../utils/sdkCutover";
 import type { KeyframeCacheEntry } from "../player/store/playerStore";
 import { commitKeyframeAtTimeImpl } from "./gsapKeyframeCommit";
+import { idFromSelector } from "./gsapShared";
 import {
   clearKeyframeCacheForElement,
   readKeyframeSnapshot,
@@ -236,7 +237,7 @@ export function useGsapKeyframeOps({
   );
 
   const moveKeyframe = useCallback(
-    (
+    async (
       selection: DomEditSelection,
       animationId: string,
       fromPercentage: number,
@@ -247,18 +248,26 @@ export function useGsapKeyframeOps({
       // updateKeyframeCacheFromParsed re-keys the diamond from the fresh parse, so no
       // optimistic cache write is needed (mapping the tween-% to clip-% here would
       // duplicate that math). softReload mirrors remove-keyframe.
-      void commitMutation(selection, mutation, {
-        label: `Move keyframe to ${toPercentage}%`,
-        softReload: true,
-      }).catch((error) => {
+      try {
+        let changed = false;
+        await commitMutation(selection, mutation, {
+          label: `Move keyframe to ${toPercentage}%`,
+          softReload: true,
+          onResult: (result) => {
+            changed = result.changed !== false;
+          },
+        });
+        return changed;
+      } catch (error) {
         trackGsapSaveFailure(error, selection, mutation, `Move keyframe to ${toPercentage}%`);
-      });
+        return false;
+      }
     },
     [commitMutation, trackGsapSaveFailure],
   );
 
   const resizeKeyframedTween = useCallback(
-    (
+    async (
       selection: DomEditSelection,
       animationId: string,
       position: number,
@@ -275,12 +284,20 @@ export function useGsapKeyframeOps({
       // Boundary drag-to-retime: the server re-keys keyframes in place + grows the
       // tween window, preserving _auto / per-keyframe ease / easeEach / outer ease.
       // softReload re-keys the diamonds from the fresh parse (mirrors moveKeyframe).
-      void commitMutation(selection, mutation, {
-        label: "Retime keyframe (resize tween)",
-        softReload: true,
-      }).catch((error) => {
+      try {
+        let changed = false;
+        await commitMutation(selection, mutation, {
+          label: "Retime keyframe (resize tween)",
+          softReload: true,
+          onResult: (result) => {
+            changed = result.changed !== false;
+          },
+        });
+        return changed;
+      } catch (error) {
         trackGsapSaveFailure(error, selection, mutation, "Retime keyframe (resize tween)");
-      });
+        return false;
+      }
     },
     [commitMutation, trackGsapSaveFailure],
   );
@@ -322,7 +339,7 @@ export function useGsapKeyframeOps({
       // remove-all-keyframes collapses the tween to a static hold and the commit
       // path doesn't return parsed animations, so the keyframe cache is never
       // refreshed — clear it here so the timeline diamonds disappear immediately.
-      const elementId = selection.id ?? selection.selector?.match(/^#([\w-]+)/)?.[1] ?? null;
+      const elementId = selection.id ?? idFromSelector(selection.selector);
       if (elementId) clearKeyframeCacheForElement(targetPath, elementId);
       if (sdkSession && sdkDeps) {
         const handled = await sdkGsapRemoveAllKeyframesPersist(

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -298,6 +298,27 @@ describe("runCommit — instantPatch wiring", () => {
     expect(deps.showToast).toHaveBeenCalledWith("A keyframe already exists at that time", "info");
   });
 
+  it("publishes the server mutation outcome to callers", async () => {
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+    let commitResult: MutationResult | undefined;
+
+    await act(async () => {
+      await deps.api.commitMutation(
+        selection,
+        { type: "move-keyframe", fromPercentage: 50, toPercentage: 75 },
+        {
+          label: "Move keyframe",
+          onResult: (result) => {
+            commitResult = result;
+          },
+        },
+      );
+    });
+
+    expect(commitResult).toEqual(expect.objectContaining({ ok: true, changed: false }));
+  });
+
   it("no-op commit with an instantPatch still patches the runtime (paired x/y commits)", async () => {
     patchRuntimeTweenInPlace.mockReturnValue(true);
     mockFetchResult({ changed: false });

package/src/hooks/useGsapScriptCommits.ts

@@ -338,6 +338,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       mutateGsapScript(pid, targetPath, mutation),
     );
     if (!result) return;
+    options.onResult?.(result);
     await finalizeSuccessfulMutation(pid, compositionPath, selection, mutation, targetPath, result, options);
   }, [showToast, finalizeSuccessfulMutation]);
 
@@ -350,6 +351,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       mutateGsapScriptBatch(pid, targetPath, mutations),
     );
     if (!result) return;
+    options.onResult?.(result);
     await finalizeSuccessfulMutation(pid, compositionPath, last.selection, last.mutation, targetPath, result, options);
   }, [showToast, finalizeSuccessfulMutation]);
 

package/src/hooks/useGsapSelectionHandlers.test.tsx

@@ -2,7 +2,9 @@
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { describe, 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 { useGsapSelectionHandlers } from "./useGsapSelectionHandlers";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -37,8 +39,8 @@ function makeParams(overrides: Partial<Params> = {}): Params {
     addKeyframe: vi.fn(),
     addKeyframeBatch: resolved(),
     removeKeyframe: vi.fn(),
-    moveKeyframe: vi.fn(),
-    resizeKeyframedTween: vi.fn(),
+    moveKeyframe: vi.fn().mockResolvedValue(true),
+    resizeKeyframedTween: vi.fn().mockResolvedValue(true),
     convertToKeyframes: resolved(),
     removeAllKeyframes: resolved(),
     handleDomManualEditsReset: vi.fn(),
@@ -79,7 +81,11 @@ describe("useGsapSelectionHandlers save failures", () => {
       makeParams({ updateGsapMeta: vi.fn().mockRejectedValue(error), showToast }),
     );
 
-    act(() => rendered.handlers().handleGsapUpdateMeta("anim-1", { duration: 2 }));
+    // Braces, not a bare arrow: the handler returns its settlement promise now,
+    // and returning a thenable from act() turns it into an un-awaited async act.
+    act(() => {
+      void rendered.handlers().handleGsapUpdateMeta("anim-1", { duration: 2 });
+    });
     await flushRejection();
 
     expect(showToast).toHaveBeenCalledWith("Couldn't save animation: write failed", "error");
@@ -114,3 +120,63 @@ describe("useGsapSelectionHandlers save failures", () => {
     rendered.unmount();
   });
 });
+
+describe("useGsapSelectionHandlers selection override", () => {
+  it("aborts on an explicit null override instead of writing to the current selection", () => {
+    const removeKeyframe = vi.fn();
+    const rendered = renderHandlers(makeParams({ removeKeyframe }));
+
+    // Explicit null: the caller resolved a selection for its own element and
+    // found none, so the write must not land on the selected element.
+    rendered.handlers().handleGsapRemoveKeyframe("anim-1", 50, undefined, null);
+    expect(removeKeyframe).not.toHaveBeenCalled();
+
+    // Omitted override: falls back to the current selection as before.
+    rendered.handlers().handleGsapRemoveKeyframe("anim-1", 50);
+    expect(removeKeyframe).toHaveBeenCalledOnce();
+    rendered.unmount();
+  });
+
+  it("computes the playhead percentage from the passed animation, not the selection's", () => {
+    const moveKeyframe = vi.fn();
+    const selection = makeSelection();
+    // The passed tween runs 2s→6s, so the playhead at 3s is 25% into IT. Without
+    // the animation the handler falls back to the selection's own element window
+    // (0s→1s here), which reads the same playhead as 100%. Asserting the exact
+    // 25 is what separates the two; `expect.any(Number)` even accepts the NaN a
+    // missing window would produce.
+    const animation = {
+      id: "anim-1",
+      position: 2,
+      resolvedStart: 2,
+      duration: 4,
+      keyframes: { keyframes: [] },
+    } as unknown as GsapAnimation;
+    usePlayerStore.setState({ currentTime: 3 });
+    const rendered = renderHandlers(makeParams({ moveKeyframe, selectedGsapAnimations: [] }));
+
+    rendered.handlers().handleGsapMoveKeyframeToPlayhead("anim-1", 50, selection, animation);
+
+    expect(moveKeyframe).toHaveBeenCalledWith(selection, "anim-1", 50, 25);
+    rendered.unmount();
+  });
+});
+
+describe("useGsapSelectionHandlers retime settlement", () => {
+  it("returns false without a selection and forwards the mutation result with one", async () => {
+    const moveKeyframe = vi.fn().mockResolvedValue(true);
+    const withoutSelection = renderHandlers(makeParams({ domEditSelection: null, moveKeyframe }));
+    await expect(
+      withoutSelection.handlers().handleGsapMoveKeyframe("anim-1", 50, 75),
+    ).resolves.toBe(false);
+    expect(moveKeyframe).not.toHaveBeenCalled();
+    withoutSelection.unmount();
+
+    const withSelection = renderHandlers(makeParams({ moveKeyframe }));
+    await expect(withSelection.handlers().handleGsapMoveKeyframe("anim-1", 50, 75)).resolves.toBe(
+      true,
+    );
+    expect(moveKeyframe).toHaveBeenCalledOnce();
+    withSelection.unmount();
+  });
+});

package/src/hooks/useGsapSelectionHandlers.ts

@@ -94,14 +94,14 @@ export function useGsapSelectionHandlers({
     animId: string,
     fromPercentage: number,
     toPercentage: number,
-  ) => void;
+  ) => Promise<boolean>;
   resizeKeyframedTween: (
     sel: DomEditSelection,
     animId: string,
     position: number,
     duration: number,
     pctRemap: Array<{ from: number; to: number }>,
-  ) => void;
+  ) => Promise<boolean>;
   convertToKeyframes: (
     sel: DomEditSelection,
     animId: string,
@@ -118,6 +118,19 @@ export function useGsapSelectionHandlers({
   const lastSelectionRef = useRef<DomEditSelection | null>(null);
   if (domEditSelection) lastSelectionRef.current = domEditSelection;
 
+  // `undefined` means the caller passed no override and accepts the current
+  // selection. An explicit `null` means the caller RESOLVED a selection for the
+  // element it is editing and there is none: falling back to domEditSelection
+  // there commits the edit onto whichever element happens to be selected, which
+  // is a different element's file. Only `undefined` may fall back.
+  const resolveWriteSelection = useCallback(
+    (selectionOverride?: DomEditSelection | null): DomEditSelection | null =>
+      selectionOverride === undefined
+        ? (domEditSelection ?? lastSelectionRef.current)
+        : selectionOverride,
+    [domEditSelection],
+  );
+
   const trackGsapHandlerFailure = useCallback(
     (error: unknown, selection: DomEditSelection, mutationType: string, label: string) => {
       trackStudioSaveFailure({
@@ -137,12 +150,24 @@ export function useGsapSelectionHandlers({
     [showToast],
   );
 
+  // Resolves to whether the mutation landed. Callers that only fire-and-forget
+  // can ignore it (the rejection is always handled here), but a caller that
+  // reports a commit result to the UI has to await the real settlement instead
+  // of assuming success the moment it dispatched.
   const observeGsapMutation = useCallback(
-    (mutation: Promise<void>, selection: DomEditSelection, mutationType: string, label: string) => {
-      void mutation.catch((error) => {
-        trackGsapHandlerFailure(error, selection, mutationType, label);
-      });
-    },
+    (
+      mutation: Promise<void>,
+      selection: DomEditSelection,
+      mutationType: string,
+      label: string,
+    ): Promise<boolean> =>
+      mutation.then(
+        () => true,
+        (error: unknown) => {
+          trackGsapHandlerFailure(error, selection, mutationType, label);
+          return false;
+        },
+      ),
     [trackGsapHandlerFailure],
   );
 
@@ -160,25 +185,25 @@ export function useGsapSelectionHandlers({
       updates: { duration?: number; ease?: string; position?: number },
       selectionOverride?: DomEditSelection | null,
     ) => {
-      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
-      if (!sel) return;
-      observeGsapMutation(
+      const sel = resolveWriteSelection(selectionOverride);
+      if (!sel) return Promise.resolve(false);
+      return observeGsapMutation(
         updateGsapMeta(sel, animId, updates),
         sel,
         "update-meta",
         "Edit GSAP animation",
       );
     },
-    [domEditSelection, observeGsapMutation, updateGsapMeta],
+    [resolveWriteSelection, observeGsapMutation, updateGsapMeta],
   );
 
   const handleGsapDeleteAnimation = useCallback(
-    (animId: string) => {
-      const sel = domEditSelection ?? lastSelectionRef.current;
+    (animId: string, selectionOverride?: DomEditSelection | null) => {
+      const sel = resolveWriteSelection(selectionOverride);
       if (!sel) return;
       observeGsapMutation(deleteGsapAnimation(sel, animId), sel, "delete", "Delete GSAP animation");
     },
-    [domEditSelection, deleteGsapAnimation, observeGsapMutation],
+    [resolveWriteSelection, deleteGsapAnimation, observeGsapMutation],
   );
 
   const handleGsapDeleteAllForElement = useCallback(
@@ -284,12 +309,12 @@ export function useGsapSelectionHandlers({
       value: number | string,
       selectionOverride?: DomEditSelection | null,
     ) => {
-      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
+      const sel = resolveWriteSelection(selectionOverride);
       if (!sel) return;
       trackStudioEvent("keyframe", { action: "add", property });
       addKeyframe(sel, animId, percentage, property, value);
     },
-    [domEditSelection, addKeyframe],
+    [resolveWriteSelection, addKeyframe],
   );
 
   const handleGsapAddKeyframeBatch = useCallback(
@@ -298,19 +323,17 @@ export function useGsapSelectionHandlers({
       percentage: number,
       properties: Record<string, number | string>,
       commitOverrides?: Partial<CommitMutationOptions>,
+      selectionOverride?: DomEditSelection | null,
     ) => {
-      if (!domEditSelection) return Promise.resolve();
-      return addKeyframeBatch(
-        domEditSelection,
-        animId,
-        percentage,
-        properties,
-        commitOverrides,
-      ).catch((error) => {
-        trackGsapHandlerFailure(error, domEditSelection, "add-keyframe", "Add keyframe");
-      });
+      const sel = resolveWriteSelection(selectionOverride);
+      if (!sel) return Promise.resolve();
+      return addKeyframeBatch(sel, animId, percentage, properties, commitOverrides).catch(
+        (error) => {
+          trackGsapHandlerFailure(error, sel, "add-keyframe", "Add keyframe");
+        },
+      );
     },
-    [domEditSelection, addKeyframeBatch, trackGsapHandlerFailure],
+    [resolveWriteSelection, addKeyframeBatch, trackGsapHandlerFailure],
   );
   const handleGsapRemoveKeyframe = useCallback(
     (
@@ -319,26 +342,34 @@ export function useGsapSelectionHandlers({
       commitOverrides?: Partial<CommitMutationOptions>,
       selectionOverride?: DomEditSelection | null,
     ) => {
-      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
+      const sel = resolveWriteSelection(selectionOverride);
       if (!sel) return;
       trackStudioEvent("keyframe", { action: "remove" });
       removeKeyframe(sel, animId, percentage, commitOverrides);
     },
-    [domEditSelection, removeKeyframe],
+    [resolveWriteSelection, removeKeyframe],
   );
 
   const handleGsapMoveKeyframeToPlayhead = useCallback(
-    (animId: string, fromPercentage: number, selectionOverride?: DomEditSelection | null) => {
-      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
+    (
+      animId: string,
+      fromPercentage: number,
+      selectionOverride?: DomEditSelection | null,
+      animationOverride?: GsapAnimation,
+    ) => {
+      const sel = resolveWriteSelection(selectionOverride);
       if (!sel) return;
       // Retime the keyframe to the playhead, preserving its value + ease. The
-      // playhead's tween-relative percentage is the move target.
-      const anim = selectedGsapAnimations.find((a) => a.id === animId);
+      // playhead's tween-relative percentage is the move target, and it has to
+      // come from the SAME element the write lands on: reading the animation off
+      // the current selection while the percentage came from the clicked element
+      // computes the target against one tween and writes it into another.
+      const anim = animationOverride ?? selectedGsapAnimations.find((a) => a.id === animId);
       const toPercentage = computeCurrentPercentage(sel, anim);
       trackStudioEvent("keyframe", { action: "move_to_playhead" });
-      moveKeyframe(sel, animId, fromPercentage, toPercentage);
+      void moveKeyframe(sel, animId, fromPercentage, toPercentage);
     },
-    [domEditSelection, selectedGsapAnimations, moveKeyframe],
+    [resolveWriteSelection, selectedGsapAnimations, moveKeyframe],
   );
 
   const handleGsapMoveKeyframe = useCallback(
@@ -348,16 +379,16 @@ export function useGsapSelectionHandlers({
       toPercentage: number,
       selectionOverride?: DomEditSelection | null,
     ) => {
-      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
-      if (!sel) return;
+      const sel = resolveWriteSelection(selectionOverride);
+      if (!sel) return Promise.resolve(false);
       // Atomic retime: preserves the keyframe's value + per-keyframe ease. Both
       // percentages are tween-relative (the drag handler converts the drop
       // position before calling). No optimistic runtime hold — the soft-reload
       // re-keys the diamond from source.
       trackStudioEvent("keyframe", { action: "retime" });
-      moveKeyframe(sel, animId, fromPercentage, toPercentage);
+      return moveKeyframe(sel, animId, fromPercentage, toPercentage);
     },
-    [domEditSelection, moveKeyframe],
+    [resolveWriteSelection, moveKeyframe],
   );
 
   const handleGsapResizeKeyframedTween = useCallback(
@@ -368,14 +399,14 @@ export function useGsapSelectionHandlers({
       pctRemap: Array<{ from: number; to: number }>,
       selectionOverride?: DomEditSelection | null,
     ) => {
-      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
-      if (!sel) return;
+      const sel = resolveWriteSelection(selectionOverride);
+      if (!sel) return Promise.resolve(false);
       // Boundary drag-to-retime: grows/shifts the tween window + re-keys keyframes
       // in place. Distinct telemetry action so resize is separable from in-window move.
       trackStudioEvent("keyframe", { action: "retime_resize" });
-      resizeKeyframedTween(sel, animId, position, duration, pctRemap);
+      return resizeKeyframedTween(sel, animId, position, duration, pctRemap);
     },
-    [domEditSelection, resizeKeyframedTween],
+    [resolveWriteSelection, resizeKeyframedTween],
   );
 
   const handleGsapConvertToKeyframes = useCallback(
@@ -384,37 +415,31 @@ export function useGsapSelectionHandlers({
       resolvedFromValues?: Record<string, number | string>,
       duration?: number,
       commitOverrides?: Partial<CommitMutationOptions>,
+      selectionOverride?: DomEditSelection | null,
     ) => {
-      if (!domEditSelection) return Promise.resolve();
-      return convertToKeyframes(
-        domEditSelection,
-        animId,
-        resolvedFromValues,
-        duration,
-        commitOverrides,
-      ).catch((error) => {
-        trackGsapHandlerFailure(
-          error,
-          domEditSelection,
-          "convert-to-keyframes",
-          "Convert to keyframes",
-        );
-      });
+      const sel = resolveWriteSelection(selectionOverride);
+      if (!sel) return Promise.resolve();
+      return convertToKeyframes(sel, animId, resolvedFromValues, duration, commitOverrides).catch(
+        (error) => {
+          trackGsapHandlerFailure(error, sel, "convert-to-keyframes", "Convert to keyframes");
+        },
+      );
     },
-    [domEditSelection, convertToKeyframes, trackGsapHandlerFailure],
+    [resolveWriteSelection, convertToKeyframes, trackGsapHandlerFailure],
   );
 
   const handleGsapRemoveAllKeyframes = useCallback(
-    (animId: string) => {
-      if (!domEditSelection) return;
-      observeGsapMutation(
-        removeAllKeyframes(domEditSelection, animId),
-        domEditSelection,
+    (animId: string, selectionOverride?: DomEditSelection | null) => {
+      const selection = resolveWriteSelection(selectionOverride);
+      if (!selection) return Promise.resolve(false);
+      return observeGsapMutation(
+        removeAllKeyframes(selection, animId),
+        selection,
         "remove-all-keyframes",
         "Remove all keyframes",
       );
     },
-    [domEditSelection, observeGsapMutation, removeAllKeyframes],
+    [resolveWriteSelection, observeGsapMutation, removeAllKeyframes],
   );
 
   const handleResetSelectedElementKeyframes = useCallback((): boolean => {