feat(studio): route static position/rotation set drags through instantPatch

Static-element position and rotation set commits now attach instantPatch{selector,
change:{kind:set}} so the drag updates in place with no reload. Structural ops (new
tween add, delete-all, convert/split/materialize) and keyframe edits deliberately omit
it and keep the soft reload — keyframe instant-patch needs object-form keyframe support
in patchRuntimeTweenInPlace (deferred).

Author: miguel-heygen

packages/studio/src/hooks/gsapDragCommit.test.ts

@@ -3,6 +3,8 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
   commitGsapPositionFromDrag,
+  commitStaticGsapPosition,
+  commitStaticGsapRotation,
   parkPlayheadOnKeyframe,
   type GsapDragCommitCallbacks,
 } from "./gsapDragCommit";
@@ -235,6 +237,142 @@ describe("commitGsapPositionFromDrag — from() tween dragged outside its range"
   });
 });
 
+// Captures the OPTIONS each commit carries (not just the mutation) so we can
+// assert which value-only commits attach the `instantPatch` fast path.
+type RecordedCommit = { mutation: Record<string, unknown>; options: Record<string, unknown> };
+function optionRecordingCallbacks(): {
+  commits: RecordedCommit[];
+  callbacks: GsapDragCommitCallbacks;
+} {
+  const commits: RecordedCommit[] = [];
+  return {
+    commits,
+    callbacks: {
+      commitMutation: async (_sel, mutation, options) => {
+        commits.push({ mutation, options: options as Record<string, unknown> });
+      },
+      fetchAnimations: async () => [convertedTween()],
+    },
+  };
+}
+
+const existingPositionSet = (): GsapAnimation =>
+  ({
+    id: "#puck-a-set",
+    targetSelector: "#puck-a",
+    method: "set",
+    properties: { x: 10, y: 20 },
+  }) as unknown as GsapAnimation;
+
+const existingRotationSet = (): GsapAnimation =>
+  ({
+    id: "#puck-a-rot-set",
+    targetSelector: "#puck-a",
+    method: "set",
+    properties: { rotation: 15 },
+  }) as unknown as GsapAnimation;
+
+describe("commitStaticGsapPosition — instantPatch (value-only set)", () => {
+  beforeEach(() => usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null }));
+
+  it("attaches instantPatch {kind:set, props:{x,y}} to the FINAL coalesced commit only", async () => {
+    const { commits, callbacks } = optionRecordingCallbacks();
+
+    await commitStaticGsapPosition(
+      selection(),
+      { x: -50, y: 30 }, // studioOffset → newX/newY off a zero base
+      { x: 0, y: 0 },
+      "#puck-a",
+      existingPositionSet(),
+      callbacks,
+    );
+
+    expect(commits).toHaveLength(2);
+    // First (x) commit is the intermediate skipReload one — NO instantPatch.
+    expect(commits[0].options.skipReload).toBe(true);
+    expect(commits[0].options.instantPatch).toBeUndefined();
+    // Final (y) commit triggers the reload and carries the full {x,y} patch.
+    expect(commits[1].options.softReload).toBe(true);
+    expect(commits[1].options.instantPatch).toEqual({
+      selector: "#puck-a",
+      change: { kind: "set", props: { x: -50, y: 30 } },
+    });
+  });
+
+  it("does NOT attach instantPatch when ADDING a new set (structural — new tween)", async () => {
+    const { commits, callbacks } = optionRecordingCallbacks();
+
+    await commitStaticGsapPosition(
+      selection(),
+      { x: -50, y: 30 },
+      { x: 0, y: 0 },
+      "#puck-a",
+      null, // no existing set → `add` a new tween
+      callbacks,
+    );
+
+    expect(commits).toHaveLength(1);
+    expect(commits[0].mutation.type).toBe("add");
+    expect(commits[0].options.instantPatch).toBeUndefined();
+  });
+});
+
+describe("commitStaticGsapRotation — instantPatch (value-only set)", () => {
+  beforeEach(() => usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null }));
+
+  it("attaches instantPatch {kind:set, props:{rotation}} when updating an existing rotation set", async () => {
+    const { commits, callbacks } = optionRecordingCallbacks();
+
+    await commitStaticGsapRotation(selection(), 42, "#puck-a", existingRotationSet(), callbacks);
+
+    expect(commits).toHaveLength(1);
+    expect(commits[0].mutation.type).toBe("update-property");
+    expect(commits[0].options.instantPatch).toEqual({
+      selector: "#puck-a",
+      change: { kind: "set", props: { rotation: 42 } },
+    });
+  });
+
+  it("does NOT attach instantPatch when ADDING a new rotation set (structural)", async () => {
+    const { commits, callbacks } = optionRecordingCallbacks();
+
+    await commitStaticGsapRotation(selection(), 42, "#puck-a", null, callbacks);
+
+    expect(commits).toHaveLength(1);
+    expect(commits[0].mutation.type).toBe("add");
+    expect(commits[0].options.instantPatch).toBeUndefined();
+  });
+});
+
+describe("commitGsapPositionFromDrag — keyframe/structural commits omit instantPatch", () => {
+  beforeEach(() => usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null }));
+
+  it("a structural keyframe drag (convert-to-keyframes → add-keyframe) sets no instantPatch", async () => {
+    usePlayerStore.setState({ currentTime: 2 }); // inside [1.2, 3.4] → convert + add-keyframe
+    const { commits, callbacks } = optionRecordingCallbacks();
+
+    await commitGsapPositionFromDrag(
+      selection(),
+      flatTween(),
+      { x: -100, y: 0 },
+      { x: 0, y: 0 },
+      null,
+      "#puck-a",
+      callbacks,
+    );
+
+    // The keyframe path is structural here (convert + add-keyframe) and must rely
+    // on the soft reload — none of its commits opt into the instant patch.
+    expect(commits.length).toBeGreaterThan(0);
+    for (const c of commits) {
+      expect(c.options.instantPatch).toBeUndefined();
+    }
+    const types = commits.map((c) => c.mutation.type);
+    expect(types).toContain("convert-to-keyframes");
+    expect(types).toContain("add-keyframe");
+  });
+});
+
 describe("parkPlayheadOnKeyframe", () => {
   beforeEach(() => usePlayerStore.setState({ requestedSeekTime: null }));
 

packages/studio/src/hooks/gsapDragCommit.ts

@@ -10,6 +10,7 @@ import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeComp
 import { roundTo3 } from "../utils/rounding";
 import { computeElementPercentage } from "./gsapShared";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
+import type { RuntimeTweenChange } from "./gsapRuntimePatch";
 export interface GsapDragCommitCallbacks {
   commitMutation: (
     selection: DomEditSelection,
@@ -20,6 +21,13 @@ export interface GsapDragCommitCallbacks {
       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>;
   fetchAnimations?: () => Promise<GsapAnimation[]>;
@@ -351,7 +359,15 @@ export async function commitStaticGsapPosition(
     await callbacks.commitMutation(
       selection,
       { type: "update-property", animationId: existingSet.id, property: "y", value: newY },
-      { label: "Move layer", softReload: true, coalesceKey },
+      {
+        label: "Move layer",
+        softReload: true,
+        coalesceKey,
+        // Final commit of the coalesced x/y pair: carry the full {x,y} so the
+        // runtime `tl.set` is patched in place instantly (skips the soft reload
+        // when the helper can confidently apply it).
+        instantPatch: { selector, change: { kind: "set", props: { x: newX, y: newY } } },
+      },
     );
     return;
   }
@@ -405,7 +421,12 @@ export async function commitStaticGsapRotation(
         property: "rotation",
         value: newRotation,
       },
-      { label: "Rotate layer", softReload: true },
+      {
+        label: "Rotate layer",
+        softReload: true,
+        // Value-only rotation set: patch the runtime `tl.set` rotation in place.
+        instantPatch: { selector, change: { kind: "set", props: { rotation: newRotation } } },
+      },
     );
     return;
   }

packages/studio/src/hooks/gsapRuntimeBridge.test.ts

@@ -89,6 +89,40 @@ describe("tryGsapDragIntercept — stale-parse guard (no resurrection after dele
     expect(mutation.type).not.toBe("add-keyframe");
   });
 
+  it("forwards instantPatch {kind:set,x,y} on the final commit when updating an existing static set", async () => {
+    const commitMutation = vi.fn();
+    const iframe = fakeIframe("puck-b", []); // runtime empty → STATIC path
+    // An existing position-hold `set` for the selector → update-in-place (not add).
+    const existingSet = {
+      id: "#puck-b-set",
+      targetSelector: "#puck-b",
+      method: "set",
+      // Tagged as a position group so resolveGroupTween returns it directly
+      // (no split commit), exercising the in-place update path cleanly.
+      propertyGroup: "position",
+      properties: { x: 0, y: 0 },
+    } as unknown as GsapAnimation;
+
+    const handled = await tryGsapDragIntercept(
+      selection,
+      { x: -50, y: 30 },
+      [existingSet],
+      iframe,
+      commitMutation,
+    );
+
+    expect(handled).toBe(true);
+    // The coalesced update-property pair: the x commit is skipReload (no patch),
+    // the final y commit triggers the reload and carries the full {x,y} patch.
+    const updates = commitMutation.mock.calls.filter(([, m]) => m.type === "update-property");
+    expect(updates).toHaveLength(2);
+    expect(updates[0][2].instantPatch).toBeUndefined();
+    expect(updates[1][2].instantPatch).toEqual({
+      selector: "#puck-b",
+      change: { kind: "set", props: { x: -50, y: 30 } },
+    });
+  });
+
   it("does not trip the stale-parse guard when the runtime still has the tween", async () => {
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
     const liveTween = {