fix(studio): route a GSAP-free move through the on-element writer and meet the file checks

Author: miguel-heygen

packages/studio/src/components/editor/PropertyPanel.tsx

@@ -210,7 +210,6 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
     manualSize.height > 0
       ? manualSize.height
       : (parsePxMetricValue(styles.height ?? "") ?? element.boundingBox.height);
-
   const manualRotation = readStudioRotation(element.element);
 
   const elStart = Number.parseFloat(element?.dataAttributes?.start ?? "0") || 0;

packages/studio/src/components/editor/manualOffsetDrag.ts

@@ -337,13 +337,11 @@ export function createManualOffsetDragMember(input: {
   selection: DomEditSelection;
   element: HTMLElement;
   rect: ManualOffsetDragRect;
-  /** A move or nudge; a resize's anchor member keeps the legacy offset channel. */
-  gesture?: "drag" | "nudge";
+  gesture?: "drag" | "nudge"; // a resize's anchor member keeps the legacy offset channel
 }): ManualOffsetDragMemberResult {
   const plainTranslate = !!input.gesture && !gsapWritesPosition(input.element);
-  // Base the drag on the offset ACTUALLY applied, never the raw (possibly dormant)
-  // var — see readAppliedStudioPathOffset. This keeps the commit purely relative
-  // (applied + delta) so a stale offset can't fling the element off-screen.
+  // Base the drag on the offset ACTUALLY applied, never a dormant var (readAppliedStudioPathOffset),
+  // so a stale offset can't fling the element off-screen.
   const initialOffset = plainTranslate
     ? readTranslatePx(input.element)
     : readAppliedStudioPathOffset(input.element);
@@ -479,7 +477,8 @@ function applyManualOffsetCommitValue(
   member: ManualOffsetDragMember,
   offset: { x: number; y: number },
 ): { x: number; y: number } {
-  if (!member.plainTranslate) stampGestureBase(member.element, member.initialOffset, member.baseGsap);
+  if (!member.plainTranslate)
+    stampGestureBase(member.element, member.initialOffset, member.baseGsap);
   drawMemberOffset(member, offset, true);
   return offset;
 }

packages/studio/src/components/editor/plainTranslate.ts

@@ -31,11 +31,10 @@ export function readTranslatePx(el: HTMLElement): Point {
 }
 
 /** Plain px only: GSAP's CSSPlugin splits `translate` on spaces and drops a calc(). */
-export function formatTranslatePx(p: Point): string {
+function formatTranslatePx(p: Point): string {
   return `${roundTo3(p.x)}px ${roundTo3(p.y)}px`;
 }
 
-/** The source patch that saves a move: the same literal the live element shows. */
 export function translatePatch(p: Point): PatchOperation & { value: string } {
   return { type: "inline-style", property: "translate", value: formatTranslatePx(p) };
 }

packages/studio/src/hooks/elementOffsetStager.ts

@@ -5,6 +5,8 @@ import {
 } from "../components/editor/elementPositionOffset";
 import { LAYER_REVEAL_PRIOR_POSITION_ATTR } from "../player/lib/timelineElementHelpers";
 import type { PatchOperation } from "../utils/sourcePatcher";
+import { translatePatch } from "../components/editor/plainTranslate";
+import { gsapWritesPosition } from "./gsapRuntimeKeyframes";
 
 const ELEMENT_OFFSET_REFUSED: Record<ElementOffsetRefusal, string> = {
   anchored: "This layer is anchored from its right or bottom edge. Move it in the Code tab.",
@@ -30,8 +32,34 @@ function settleGsapDraftAtGestureStart(el: HTMLElement): void {
   if (gsap && Number.isFinite(x) && Number.isFinite(y)) gsap.set(el, { x, y });
 }
 
-/** Applies a shared-tween element's move live now; `save` persists it as left/top on that
- *  element, `rollback` takes the live move back. Throws, after a toast, when it cannot. */
+let plainMoveCounter = 0;
+
+/** GSAP does not position the element: `next` is its whole translate, live now and saved as drawn. */
+function stagePlainTranslate(
+  commitPositionPatchToHtml: ElementOffsetStagerDeps["commitPositionPatchToHtml"],
+  selection: DomEditSelection,
+  next: { x: number; y: number },
+  coalesceKey?: string,
+): { save: () => Promise<void>; rollback: () => void } {
+  const style = selection.element.style;
+  const before = style.getPropertyValue("translate");
+  const patch = translatePatch(next);
+  style.setProperty("translate", patch.value);
+  const rollback = () => {
+    if (style.getPropertyValue("translate") === patch.value) style.setProperty("translate", before);
+  };
+  const key = coalesceKey ?? `move:${++plainMoveCounter}`;
+  const options = { label: "Move layer", coalesceKey: key, coalesceMs: Number.POSITIVE_INFINITY };
+  const save = () =>
+    commitPositionPatchToHtml(selection, [patch], options).catch((error) => {
+      rollback();
+      throw error;
+    });
+  return { save, rollback };
+}
+
+/** Applies a move on the element itself live now: its translate when GSAP does not position it,
+ *  else left/top for a shared-tween element. Throws, after a toast, when it cannot. */
 export function stageElementOffset(
   { commitPositionPatchToHtml, showToast, readOnlyPreview }: ElementOffsetStagerDeps,
   selection: DomEditSelection,
@@ -40,6 +68,9 @@ export function stageElementOffset(
 ): { save: () => Promise<void>; rollback: () => void } {
   const el = selection.element;
   if (readOnlyPreview) return { save: () => Promise.resolve(), rollback: () => undefined };
+  if (!gsapWritesPosition(el)) {
+    return stagePlainTranslate(commitPositionPatchToHtml, selection, next, coalesceKey);
+  }
   const previous = { position: el.style.position, left: el.style.left, top: el.style.top };
   const liftMarker = el.getAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
   const result = applyElementPositionOffset(el, next);

packages/studio/src/hooks/gsapRuntimeKeyframes.ts

@@ -405,33 +405,30 @@ export function hasNonHoldTweenForElement(
   return !!targetEl && hasNonHoldTween(timelinesOf(iframe), targetEl, channels, compositionId);
 }
 
-// Position channels — used to scope the "has a live position tween?" check so a
-// sibling rotation/scale animation never forces a static position hold into the
-// keyframe branch (which corrupts it into a frozen duration-0 keyframed tween).
+// A sibling rotation/scale tween must never push a static position hold into the keyframe branch.
 export const POSITION_CHANNELS: string[] = [
   "x",
   "y",
   "xPercent",
   "yPercent",
   "left",
   "top",
-  // GSAP normalizes translateX/Y to x/y at play time, but readTween reads the
-  // AUTHORED shape — include them so a hand-authored translateX/Y position tween
-  // still counts as a live position tween.
+  // readTween reads the authored translateX/Y; GSAP normalizes them to x/y only at play time.
   "translateX",
   "translateY",
 ];
 const MOVE_CHANNELS = [...POSITION_CHANNELS, "motionPath"];
 
 /** Whether a live timeline tween or hold writes any of `channels` on `el`. Sync, no fetch. */
-export function gsapWritesChannels(el: Element, channels: string[]): boolean {
+function gsapWritesChannels(el: Element, channels: string[]): boolean {
   const win = el.ownerDocument.defaultView as { __timelines?: Record<string, RuntimeTimeline> };
   return Object.values(win?.__timelines ?? {}).some((tl) =>
     (tl?.getChildren?.(true) ?? []).some(
       (tween) =>
         !!tween.vars &&
         matchesElement(tween, el) &&
-        (channels.some((ch) => ch in tween.vars!) || keyframeVarsCarryChannel(tween.vars, channels)),
+        (channels.some((ch) => ch in tween.vars!) ||
+          keyframeVarsCarryChannel(tween.vars, channels)),
     ),
   );
 }

packages/studio/src/hooks/useDomGeometryCommit.test.tsx

@@ -138,37 +138,56 @@ describe("useDomGeometryCommit, from the package entry", () => {
     unmount();
   });
 
-  it("saves a GSAP-free move as its inline translate, with no GSAP script and no animation read", async () => {
-    const urls: string[] = [];
-    const patches: unknown[] = [];
+  function stubPatchServer(patchStatus = 200) {
+    const calls = { urls: [] as string[], patches: [] as unknown[] };
     vi.stubGlobal(
       "fetch",
       vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
         const url = String(input instanceof Request ? input.url : input);
-        urls.push(url);
-        if (url.includes("/file-mutations/patch-element/")) patches.push(JSON.parse(String(init?.body)));
-        const body = url.includes("/files/")
-          ? { content: SOURCE }
-          : { ok: true, changed: true, matched: true, content: "AFTER", version: "v2" };
-        return new Response(JSON.stringify(body), { headers: { "content-type": "application/json" } });
+        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 body = url.includes("/files/") ? { content: SOURCE } : saved;
+        const status = url.includes("/patch-element/") ? patchStatus : 200;
+        return new Response(JSON.stringify(body), {
+          status,
+          headers: { "content-type": "application/json" },
+        });
       }),
     );
+    return calls;
+  }
+
+  it("saves a GSAP-free move as its inline translate, with no GSAP script and no animation read", async () => {
+    const calls = stubPatchServer();
     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 });
 
     expect(element.style.getPropertyValue("translate")).toBe("130.5px 90px");
-    expect(patches).toEqual([
+    expect(calls.patches).toEqual([
       expect.objectContaining({
         operations: [{ type: "inline-style", property: "translate", value: "130.5px 90px" }],
       }),
     ]);
-    expect(urls.filter((url) => url.includes("gsap"))).toEqual([]);
+    expect(calls.urls.filter((url) => url.includes("gsap"))).toEqual([]);
     expect(recordEdit).toHaveBeenCalledTimes(1);
     unmount();
   });
 
+  it("puts a GSAP-free element's translate back when its move cannot be saved", async () => {
+    stubPatchServer(500);
+    const { element, hook, unmount } = renderHost();
+    element.style.setProperty("translate", "40px 30px");
+
+    await expect(
+      hook().commitPathOffset(makeSelection("card", element), { x: 1, y: 2 }),
+    ).rejects.toThrow();
+    expect(element.style.getPropertyValue("translate")).toBe("40px 30px");
+    unmount();
+  });
+
   it("keeps the same commits across renders, so the overlay's handlers stay put", () => {
     stubServer();
     const { hook, rerender, unmount } = renderHost();

packages/studio/src/hooks/useDomGeometryCommits.test.tsx

@@ -147,8 +147,10 @@ describe("useDomGeometryCommits read-only preview", () => {
 });
 
 describe("useDomGeometryCommits element position offset", () => {
-  it("persists left/top on the element and no translate offset", async () => {
-    const element = document.createElement("span");
+  it("persists left/top on a word a shared tween positions, and no translate offset", async () => {
+    const element = Object.assign(document.createElement("span"), {
+      _gsap: { renderTransform: () => {} },
+    });
     Object.defineProperties(element, {
       offsetLeft: { get: () => 100 + (Number.parseFloat(element.style.left) || 0) },
       offsetTop: { get: () => 200 + (Number.parseFloat(element.style.top) || 0) },

packages/studio/src/hooks/useGsapAwareEditing.test.tsx

@@ -117,14 +117,8 @@ function mountGroupHandler({
   makeFetchFallback,
   trackGsapInteractionFailure = vi.fn(),
   stageElementPositionOffset = vi.fn(),
-  commitPositionPatchToHtml = vi.fn(),
 }: Pick<AwareEditingParams, "gsapCommitMutation" | "makeFetchFallback"> &
-  Partial<
-    Pick<
-      AwareEditingParams,
-      "trackGsapInteractionFailure" | "stageElementPositionOffset" | "commitPositionPatchToHtml"
-    >
-  >) {
+  Partial<Pick<AwareEditingParams, "trackGsapInteractionFailure" | "stageElementPositionOffset">>) {
   let groupCommit!: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
   let pathOffsetCommit!: (
     selection: DomEditSelection,
@@ -142,7 +136,7 @@ function mountGroupHandler({
       trackGsapInteractionFailure,
       stageElementPositionOffset,
       handleDomBoxSizeCommit: vi.fn(),
-      commitPositionPatchToHtml,
+      commitPositionPatchToHtml: vi.fn(),
       addGsapAnimation: vi.fn(),
       convertToKeyframes: vi.fn(),
       setArcPath: vi.fn(),
@@ -162,72 +156,25 @@ function mountGroupHandler({
 }
 
 describe("useGsapAwareEditing moves of an element GSAP does not position", () => {
-  const translatePatch = (value: string) => [{ type: "inline-style", property: "translate", value }];
-
-  it("writes its inline translate as drawn, with no GSAP write and no animation read", async () => {
-    const commitPositionPatchToHtml = vi.fn().mockResolvedValue(undefined);
+  it("saves the move on the element itself, with no GSAP write and no animation read", async () => {
+    const save = vi.fn().mockResolvedValue(undefined);
+    const stageElementPositionOffset = vi.fn(() => ({ save, rollback: vi.fn() }));
     const gsapCommitMutation = vi.fn();
     const makeFetchFallback = vi.fn();
     const { pathOffsetCommit, root } = mountGroupHandler({
       gsapCommitMutation,
       makeFetchFallback,
-      commitPositionPatchToHtml,
+      stageElementPositionOffset,
     });
     const box = { element: document.createElement("div"), id: "box", selector: "#box" };
     await act(() => pathOffsetCommit(box as unknown as DomEditSelection, { x: 130.25, y: 90 }));
-    expect(box.element.style.getPropertyValue("translate")).toBe("130.25px 90px");
-    expect(commitPositionPatchToHtml).toHaveBeenCalledWith(
-      box,
-      translatePatch("130.25px 90px"),
-      expect.objectContaining({ label: "Move layer" }),
-    );
+    expect(stageElementPositionOffset).toHaveBeenCalledWith(box, { x: 130.25, y: 90 });
+    expect(save).toHaveBeenCalledTimes(1);
     expect(gsapCommitMutation).not.toHaveBeenCalled();
     expect(makeFetchFallback).not.toHaveBeenCalled();
     expect(mocks.drag).not.toHaveBeenCalled();
     act(() => root.unmount());
   });
-
-  it("puts the live translate back when the save fails", async () => {
-    const commitPositionPatchToHtml = vi.fn().mockRejectedValue(new Error("offline"));
-    const gsapCommitMutation = vi.fn();
-    const { pathOffsetCommit, root } = mountGroupHandler({
-      gsapCommitMutation,
-      makeFetchFallback: vi.fn(),
-      commitPositionPatchToHtml,
-    });
-    const box = { element: document.createElement("div"), id: "box", selector: "#box" };
-    box.element.style.setProperty("translate", "40px 30px");
-    await expect(pathOffsetCommit(box as unknown as DomEditSelection, { x: 1, y: 2 })).rejects.toThrow(
-      "offline",
-    );
-    expect(box.element.style.getPropertyValue("translate")).toBe("40px 30px");
-    act(() => root.unmount());
-  });
-
-  it("writes a GSAP-free group member by translate under the group key, the rest through GSAP", async () => {
-    mocks.drag.mockResolvedValue({ status: "persisted" });
-    const commitPositionPatchToHtml = vi.fn().mockResolvedValue(undefined);
-    const { groupCommit, root } = mountGroupHandler({
-      gsapCommitMutation: vi.fn().mockResolvedValue(undefined),
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
-      commitPositionPatchToHtml,
-    });
-    const plain = { element: document.createElement("div"), id: "plain", selector: "#plain" };
-    const animated = { element: gsapPositioned("div"), id: "anim", selector: "#anim" };
-    await act(() =>
-      groupCommit([
-        { selection: plain, next: { x: 10, y: 20 } },
-        { selection: animated, next: { x: 10, y: 20 } },
-      ] as unknown as DomEditGroupPathOffsetCommit[]),
-    );
-    expect(commitPositionPatchToHtml).toHaveBeenCalledWith(
-      plain,
-      translatePatch("10px 20px"),
-      expect.objectContaining({ coalesceKey: expect.stringMatching(/^group-drag:\d+$/) }),
-    );
-    expect(mocks.drag.mock.calls.map((call) => call[0])).toEqual([animated, animated]);
-    act(() => root.unmount());
-  });
 });
 
 describe("useGsapAwareEditing shared-tween moves", () => {
@@ -249,7 +196,7 @@ describe("useGsapAwareEditing shared-tween moves", () => {
     act(() => root.unmount());
   });
 
-  it("saves a group member that shares a tween through its own offset, under the group key", async () => {
+  it("saves shared-tween and GSAP-free group members on themselves, under the group key", async () => {
     mocks.drag.mockImplementation(async (selection, _next, _a, _i, commit, _f, options) => {
       if (selection.hfId === "w0") return { status: "element-offset" };
       if (!options?.preflightOnly) await commit(selection, { type: "move" }, { label: "Move" });
@@ -264,17 +211,18 @@ describe("useGsapAwareEditing shared-tween moves", () => {
     });
     const word = { element: gsapPositioned("span"), hfId: "w0", selector: ".w" };
     const box = { element: gsapPositioned("div"), id: "box", selector: "#box" };
+    const plain = { element: document.createElement("div"), id: "plain", selector: "#plain" };
     await act(() =>
       groupCommit([
         { selection: word, next: { x: 40, y: 20 } },
         { selection: box, next: { x: 40, y: 20 } },
+        { selection: plain, next: { x: 40, y: 20 } },
       ] as unknown as DomEditGroupPathOffsetCommit[]),
     );
-    expect(stageElementPositionOffset).toHaveBeenCalledWith(
-      word,
-      { x: 40, y: 20 },
-      expect.stringMatching(/^group-drag:\d+$/),
-    );
+    const groupKey = expect.stringMatching(/^group-drag:\d+$/);
+    expect(stageElementPositionOffset).toHaveBeenCalledWith(word, { x: 40, y: 20 }, groupKey);
+    expect(stageElementPositionOffset).toHaveBeenCalledWith(plain, { x: 40, y: 20 }, groupKey);
+    expect(mocks.drag.mock.calls.some((call) => call[0] === plain)).toBe(false);
     act(() => root.unmount());
   });
 });