@hyperframes/studio 0.8.99 → 0.8.101

package/src/components/editor/manualOffsetDrag.test.ts

@@ -5,6 +5,7 @@ import {
   resumeGsapTimelines,
   applyManualOffsetDragDraft,
   applyManualOffsetDragMatrix,
+  applyManualOffsetNudgeDraft,
   createManualOffsetDragMember,
   endManualOffsetDragMembers,
   invertManualOffsetDragMatrix,
@@ -566,3 +567,72 @@ describe("resumeGsapTimelines", () => {
     expect(() => resumeGsapTimelines(element)).not.toThrow();
   });
 });
+
+describe("a move of an element GSAP does not position", () => {
+  function plainBox(options: { gsapLoaded?: boolean } = {}) {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    window.document.body.append(element);
+    element.style.setProperty("translate", "40px 30px");
+    // A rect that never moves: the probe falls back to the 1:1 preview-scale mapping.
+    element.getBoundingClientRect = () => new window.DOMRect(10, 20, 100, 50);
+    const gsapCalls: string[] = [];
+    if (options.gsapLoaded) {
+      Object.assign(window, {
+        gsap: { set: () => gsapCalls.push("set"), getProperty: () => gsapCalls.push("read") },
+      });
+    }
+    const member = (gesture: "drag" | "nudge" = "drag") => {
+      const result = createManualOffsetDragMember({
+        key: "box",
+        selection: { element } as never,
+        element,
+        rect: { left: 10, top: 20, width: 100, height: 50, editScaleX: 1, editScaleY: 1 },
+        gesture,
+      });
+      if (!result.ok) throw new Error(result.reason);
+      return result.member;
+    };
+    return { window, element, gsapCalls, member };
+  }
+
+  it("drafts and drops the element's own translate in plain px, never touching GSAP", () => {
+    const { element, gsapCalls, member } = plainBox({ gsapLoaded: true });
+    const m = member();
+    expect(m.plainTranslate).toBe(true);
+    applyManualOffsetDragDraft(m, 90.25, 60);
+    expect(element.style.getPropertyValue("translate")).toBe("130.25px 90px");
+    expect(applyManualOffsetDragCommit(m, 90.25, 60)).toEqual({ x: 130.25, y: 90 });
+    endManualOffsetDragMembers([m]);
+    expect(element.style.getPropertyValue("translate")).toBe("130.25px 90px");
+    expect(gsapCalls).toEqual([]);
+    expect(element.hasAttribute("data-hf-drag-gsap-base-x")).toBe(false);
+  });
+
+  it("starts a second move where the first dropped, while the first save is still in flight", () => {
+    const { member } = plainBox();
+    const first = member();
+    applyManualOffsetDragCommit(first, 90, 60);
+    const second = member();
+    expect(second.initialOffset).toEqual({ x: 130, y: 90 });
+    expect(applyManualOffsetDragCommit(second, 40, 0)).toEqual({ x: 170, y: 90 });
+  });
+
+  it("nudges from the element's translate", () => {
+    const { member } = plainBox();
+    expect(applyManualOffsetNudgeDraft(member("nudge"), { x: 5, y: -1 })).toEqual({ x: 45, y: 29 });
+  });
+
+  it("keeps the GSAP writer once GSAP renders the element's transform", () => {
+    const { element, member } = plainBox({ gsapLoaded: true });
+    Object.assign(element, { _gsap: { renderTransform: () => {} } });
+    expect(member().plainTranslate).toBe(false);
+  });
+
+  it("keeps the GSAP writer for an element a timeline hold positions", () => {
+    const { window, element, member } = plainBox();
+    const hold = { targets: () => [element], vars: { x: 40 }, duration: () => 0 };
+    Object.assign(window, { __timelines: { main: { getChildren: () => [hold] } } });
+    expect(member().plainTranslate).toBe(false);
+  });
+});

package/src/components/editor/manualOffsetDrag.ts

@@ -11,6 +11,8 @@ import {
   type StudioPathOffsetSnapshot,
 } from "./manualEdits";
 import { computeDraggedGsapPosition } from "../../hooks/draggedGsapPosition";
+import { gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { readTranslatePx, writeTranslatePx } from "./plainTranslate";
 
 interface OffsetDragGsap {
   set: (el: Element, vars: Record<string, number | string>) => void;
@@ -97,6 +99,8 @@ export interface ManualOffsetDragMember {
   selection: DomEditSelection;
   element: HTMLElement;
   initialOffset: { x: number; y: number };
+  /** The move writes the element's own inline `translate`; offsets are then absolute translate px. */
+  plainTranslate: boolean;
   /**
    * The element's GSAP x/y at gesture start, captured in JS so a mid-drag
    * re-render (which reverts inline style + wipes the `data-hf-drag-gsap-base-*`
@@ -242,22 +246,23 @@ function readTransformWDivisor(element: HTMLElement): number {
 export function measureManualOffsetDragScreenToOffsetMatrix(
   element: HTMLElement,
   initialOffset: { x: number; y: number },
-  options: { probeSize?: number; scaleX?: number; scaleY?: number } = {},
+  options: { probeSize?: number; scaleX?: number; scaleY?: number; plainTranslate?: boolean } = {},
 ): { ok: true; matrix: ManualOffsetDragMatrix } | { ok: false; reason: string } {
   const probeSize = options.probeSize ?? DEFAULT_OFFSET_PROBE_PX;
   if (!Number.isFinite(probeSize) || probeSize <= 0) {
     return { ok: false, reason: "Invalid movement probe size." };
   }
 
+  const draw = options.plainTranslate ? writeTranslatePx : applyStudioPathOffsetDraft;
   const snapshot = captureStudioPathOffset(element);
   try {
-    applyStudioPathOffsetDraft(element, initialOffset);
+    draw(element, initialOffset);
     const origin = getRectCenter(element);
     if (!origin) {
       return { ok: false, reason: "Element has no measurable box." };
     }
 
-    applyStudioPathOffsetDraft(element, {
+    draw(element, {
       x: initialOffset.x + probeSize,
       y: initialOffset.y,
     });
@@ -266,7 +271,7 @@ export function measureManualOffsetDragScreenToOffsetMatrix(
       return { ok: false, reason: "Element X movement could not be measured." };
     }
 
-    applyStudioPathOffsetDraft(element, {
+    draw(element, {
       x: initialOffset.x,
       y: initialOffset.y + probeSize,
     });
@@ -332,24 +337,25 @@ export function createManualOffsetDragMember(input: {
   selection: DomEditSelection;
   element: HTMLElement;
   rect: ManualOffsetDragRect;
+  gesture?: "drag" | "nudge"; // a resize's anchor member keeps the legacy offset channel
 }): ManualOffsetDragMemberResult {
-  // 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.
-  const initialOffset = readAppliedStudioPathOffset(input.element);
-  input.element.setAttribute("data-hf-drag-initial-offset-x", String(initialOffset.x));
-  input.element.setAttribute("data-hf-drag-initial-offset-y", String(initialOffset.y));
-
+  const plainTranslate = !!input.gesture && !gsapWritesPosition(input.element);
+  // 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);
   const win = input.element.ownerDocument.defaultView as
     | (Window & {
         gsap?: { getProperty?: (el: Element, prop: string) => number };
         __timelines?: Record<string, { pause?: () => void; paused?: () => boolean }>;
       })
     | null;
-  const gsapX = win?.gsap?.getProperty?.(input.element, "x") || 0;
-  const gsapY = win?.gsap?.getProperty?.(input.element, "y") || 0;
-  input.element.setAttribute("data-hf-drag-gsap-base-x", String(gsapX));
-  input.element.setAttribute("data-hf-drag-gsap-base-y", String(gsapY));
+  // getProperty makes GSAP bake the CSS translate into its transform, so a plain move never reads it.
+  const gsapX = (!plainTranslate && win?.gsap?.getProperty?.(input.element, "x")) || 0;
+  const gsapY = (!plainTranslate && win?.gsap?.getProperty?.(input.element, "y")) || 0;
+  const baseGsap = { x: gsapX, y: gsapY };
+  if (!plainTranslate) stampGestureBase(input.element, initialOffset, baseGsap);
 
   if (win?.__timelines) {
     const paused: string[] = [];
@@ -373,8 +379,8 @@ export function createManualOffsetDragMember(input: {
   const measured = measureManualOffsetDragScreenToOffsetMatrix(input.element, initialOffset, {
     scaleX: input.rect.editScaleX,
     scaleY: input.rect.editScaleY,
+    plainTranslate,
   });
-  const baseGsap = { x: gsapX, y: gsapY };
   if (!measured.ok) {
     // Fallback: when GSAP transforms interfere with probe measurement, use
     // the preview scale as an approximation. The commit path reads the actual
@@ -390,6 +396,7 @@ export function createManualOffsetDragMember(input: {
         selection: input.selection,
         element: input.element,
         initialOffset,
+        plainTranslate,
         baseGsap,
         initialPathOffset,
         gestureToken,
@@ -406,6 +413,7 @@ export function createManualOffsetDragMember(input: {
       selection: input.selection,
       element: input.element,
       initialOffset,
+      plainTranslate,
       baseGsap,
       initialPathOffset,
       gestureToken,
@@ -428,18 +436,25 @@ function resolveManualOffsetDragMemberOffset(
   });
 }
 
+/** Draws the offset where the commit writes it: the inline translate, else GSAP, else the legacy var. */
+function drawMemberOffset(
+  member: ManualOffsetDragMember,
+  offset: { x: number; y: number },
+  commit: boolean,
+): void {
+  if (member.plainTranslate) writeTranslatePx(member.element, offset);
+  else if (applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) return;
+  else if (commit) applyStudioPathOffset(member.element, offset);
+  else applyStudioPathOffsetDraft(member.element, offset);
+}
+
 export function applyManualOffsetDragDraft(
   member: ManualOffsetDragMember,
   dx: number,
   dy: number,
 ): { x: number; y: number } {
   const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
-  // Position is single-sourced on the GSAP timeline; preview through gsap.set so
-  // the live draft matches the committed `tl.set`/keyframe. CSS draft only when
-  // gsap is unavailable (no preview iframe runtime).
-  if (!applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) {
-    applyStudioPathOffsetDraft(member.element, offset);
-  }
+  drawMemberOffset(member, offset, false);
   return offset;
 }
 
@@ -451,25 +466,20 @@ export function applyManualOffsetDragDraft(
  * the element flies off-screen the instant you drop it. The member holds the
  * true gesture-start values in JS, immune to the re-render.
  */
-function restampManualOffsetDragGestureBase(member: ManualOffsetDragMember): void {
-  member.element.setAttribute("data-hf-drag-gsap-base-x", String(member.baseGsap.x));
-  member.element.setAttribute("data-hf-drag-gsap-base-y", String(member.baseGsap.y));
-  member.element.setAttribute("data-hf-drag-initial-offset-x", String(member.initialOffset.x));
-  member.element.setAttribute("data-hf-drag-initial-offset-y", String(member.initialOffset.y));
+function stampGestureBase(el: HTMLElement, initialOffset: Point, baseGsap: Point): void {
+  el.setAttribute("data-hf-drag-gsap-base-x", String(baseGsap.x));
+  el.setAttribute("data-hf-drag-gsap-base-y", String(baseGsap.y));
+  el.setAttribute("data-hf-drag-initial-offset-x", String(initialOffset.x));
+  el.setAttribute("data-hf-drag-initial-offset-y", String(initialOffset.y));
 }
 
 function applyManualOffsetCommitValue(
   member: ManualOffsetDragMember,
   offset: { x: number; y: number },
 ): { x: number; y: number } {
-  restampManualOffsetDragGestureBase(member);
-  // Optimistic visual through the GSAP channel (same as the live draft and the
-  // committed `tl.set`), so the element holds its dropped position until the
-  // source mutation soft-reloads — no transient CSS `--hf-studio-offset` write.
-  // CSS apply only when gsap is unavailable.
-  if (!applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) {
-    applyStudioPathOffset(member.element, offset);
-  }
+  if (!member.plainTranslate)
+    stampGestureBase(member.element, member.initialOffset, member.baseGsap);
+  drawMemberOffset(member, offset, true);
   return offset;
 }
 
@@ -496,9 +506,7 @@ export function applyManualOffsetNudgeDraft(
     x: member.initialOffset.x + delta.x,
     y: member.initialOffset.y + delta.y,
   };
-  if (!applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) {
-    applyStudioPathOffsetDraft(member.element, offset);
-  }
+  drawMemberOffset(member, offset, false);
   return offset;
 }
 
@@ -514,7 +522,9 @@ export function applyManualOffsetNudgeCommit(
 
 function restoreManualOffsetDragMember(member: ManualOffsetDragMember): void {
   restoreStudioPathOffset(member.element, member.initialPathOffset);
-  getOffsetDragGsap(member.element)?.set(member.element, { ...member.baseGsap });
+  if (!member.plainTranslate) {
+    getOffsetDragGsap(member.element)?.set(member.element, { ...member.baseGsap });
+  }
   endStudioManualEditGesture(member.element, member.gestureToken);
 }
 
@@ -548,7 +558,7 @@ export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): v
     member.element.removeAttribute("data-hf-drag-gsap-base-y");
     // Do NOT clearProps:"transform" — that nukes the committed GSAP position
     // and causes a visual snap-back before the soft reload re-applies it.
-    const gsapOwnsPosition = Boolean(getOffsetDragGsap(member.element));
+    const gsapOwnsPosition = !member.plainTranslate && Boolean(getOffsetDragGsap(member.element));
     // Migration: when GSAP owns the position (the committed value lives in the
     // GSAP transform), the legacy `--hf-studio-offset` CSS channel is obsolete.
     // Clear it on the LIVE element — otherwise the leftover `translate:

package/src/components/editor/plainTranslate.test.ts

@@ -0,0 +1,62 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { readTranslatePx } from "./plainTranslate";
+
+function box(style: string): HTMLElement {
+  const element = document.createElement("div");
+  element.style.cssText = `position: absolute; width: 240px; height: 160px; ${style}`;
+  document.body.append(element);
+  return element;
+}
+
+describe("readTranslatePx", () => {
+  it.each([
+    ["40px 30px", { x: 40, y: 30 }],
+    ["-50% -50%", { x: -120, y: -80 }],
+    ["25% 25%", { x: 60, y: 40 }],
+    ["calc(-50% + 12px) calc(10% - 6px)", { x: -108, y: 10 }],
+    ["30px", { x: 30, y: 0 }],
+  ])("reads %s against the border box, in px", (translate, want) => {
+    expect(readTranslatePx(box(`translate: ${translate}`))).toEqual(want);
+  });
+
+  it.each([
+    ["calc(50% - 20px) 0px", { x: 100, y: 0 }],
+    ["calc(50% + 20px) calc(50% - 20px)", { x: 140, y: 60 }],
+  ])("adds and subtracts the terms of %s", (translate, want) => {
+    expect(readTranslatePx(box(`translate: ${translate}`))).toEqual(want);
+  });
+
+  it.each([
+    "min(10px, 5%) 0px",
+    "calc(2 * 10px) 0px",
+    "calc(10px +) 0px",
+    "clamp(0px, 10%, 30px) 5px",
+  ])("hands %s to Chrome's own resolution and puts the element's style back", (translate) => {
+    const element = box(`translate: ${translate}; transform: rotate(5deg)`);
+    const before = element.getAttribute("style");
+    const read = readTranslatePx(element);
+    expect(Number.isFinite(read.x) && Number.isFinite(read.y)).toBe(true);
+    expect(element.getAttribute("style")).toBe(before);
+  });
+
+  it("counts padding and border in the box a percent resolves against", () => {
+    const element = box(
+      "translate: 50% 50%; padding: 10px; border: 5px solid; box-sizing: content-box",
+    );
+    expect(readTranslatePx(element)).toEqual({ x: 135, y: 95 });
+  });
+
+  it("writes nothing to the element it reads", () => {
+    const element = box("translate: -50% -50%");
+    const before = element.getAttribute("style");
+    const writes: MutationRecord[] = [];
+    const observer = new MutationObserver((records) => writes.push(...records));
+    observer.observe(element, { attributes: true });
+    readTranslatePx(element);
+    writes.push(...observer.takeRecords());
+    observer.disconnect();
+    expect(writes).toEqual([]);
+    expect(element.getAttribute("style")).toBe(before);
+  });
+});

package/src/components/editor/plainTranslate.ts

@@ -0,0 +1,85 @@
+import { roundTo3 } from "../../utils/rounding";
+import { gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { readStudioPathOffset } from "./manualEditsDom";
+import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
+import type { PatchOperation } from "../../utils/sourcePatcher";
+
+type Point = { x: number; y: number };
+
+const TERM = /^(-?\d*\.?\d+(?:e[-+]?\d+)?)(px|%)$/i;
+
+const SIGN: Record<string, number> = { "+": 1, "-": -1 };
+
+function termPx(term: string | undefined, side: number): number | null {
+  const match = TERM.exec(term ?? "");
+  return match ? Number(match[1]) * (match[2] === "%" ? side / 100 : 1) : null;
+}
+
+/** px, %, or Chrome's computed `calc(P% + Lpx)`, against the border-box side; null for min()/max()/clamp(). */
+function resolveLength(value: string, side: number): number | null {
+  const parts = (/^calc\((.*)\)$/.exec(value)?.[1] ?? value).split(" ");
+  if (parts.length % 2 === 0) return null;
+  let total = termPx(parts[0], side);
+  for (let i = 1; i < parts.length && total !== null; i += 2) {
+    const term = termPx(parts[i + 1], side);
+    const sign = SIGN[parts[i] ?? ""];
+    total = term === null || !sign ? null : total + sign * term;
+  }
+  return total;
+}
+
+function borderBox(
+  cs: CSSStyleDeclaration,
+  size: "width" | "height",
+  a: string,
+  b: string,
+): number {
+  const n = (prop: string) => Number.parseFloat(cs.getPropertyValue(prop)) || 0;
+  const pad =
+    n(`padding-${a}`) + n(`padding-${b}`) + n(`border-${a}-width`) + n(`border-${b}-width`);
+  return n(size) + (cs.boxSizing === "border-box" ? 0 : pad);
+}
+
+// Chrome resolves min()/max()/clamp() inside a transform function to a matrix; an unrendered box has none.
+function resolveInTransform(el: HTMLElement, x: string, y: string): Point {
+  const style = el.style;
+  const saved = [style.getPropertyValue("transform"), style.getPropertyPriority("transform")];
+  style.setProperty("transform", `translate(${x}, ${y})`, "important");
+  try {
+    const resolved = el.ownerDocument.defaultView?.getComputedStyle(el).transform ?? "";
+    const matrix = new DOMMatrixReadOnly(resolved.startsWith("matrix") ? resolved : undefined);
+    return { x: matrix.m41, y: matrix.m42 };
+  } finally {
+    style.setProperty("transform", saved[0] ?? "", saved[1] ?? "");
+  }
+}
+
+/** The element's CSS `translate` in px, as it renders now. */
+// ponytail: a 3-value translate loses its z on the next move; keep z when a fixture needs it.
+export function readTranslatePx(el: HTMLElement): Point {
+  const cs = el.ownerDocument.defaultView?.getComputedStyle(el);
+  const value = el.style.getPropertyValue("translate") || cs?.translate || "none";
+  if (value === "none") return { x: 0, y: 0 };
+  const [x = "0px", y = "0px"] = splitTopLevelWhitespace(value);
+  const px = cs && resolveLength(x, borderBox(cs, "width", "left", "right"));
+  const py = cs && resolveLength(y, borderBox(cs, "height", "top", "bottom"));
+  return px != null && py != null ? { x: px, y: py } : resolveInTransform(el, x, y);
+}
+
+/** Plain px only: GSAP's CSSPlugin splits `translate` on spaces and drops a calc(). */
+function formatTranslatePx(p: Point): string {
+  return `${roundTo3(p.x)}px ${roundTo3(p.y)}px`;
+}
+
+export function translatePatch(p: Point): PatchOperation & { value: string } {
+  return { type: "inline-style", property: "translate", value: formatTranslatePx(p) };
+}
+
+export function writeTranslatePx(el: HTMLElement, p: Point): void {
+  el.style.setProperty("translate", formatTranslatePx(p));
+}
+
+/** The position the panel shows and edits: the translate a move writes, unless GSAP positions it. */
+export function readMoveOffset(el: HTMLElement): Point {
+  return gsapWritesPosition(el) ? readStudioPathOffset(el) : readTranslatePx(el);
+}

package/src/components/editor/propertyPanelTransformCommit.ts

@@ -1,5 +1,6 @@
 import type { DomEditSelection } from "./domEditingTypes";
-import { readStudioBoxSize, readStudioPathOffset } from "./manualEdits";
+import { readStudioBoxSize } from "./manualEdits";
+import { readMoveOffset } from "./plainTranslate";
 import { parsePxMetricValue, type PropertyPanelProps } from "./propertyPanelHelpers";
 
 interface TransformCommitDeps {
@@ -73,7 +74,7 @@ export function createTransformCommitHandlers({
       )
     )
       return;
-    const current = readStudioPathOffset(element.element);
+    const current = readMoveOffset(element.element);
     await Promise.resolve(
       onSetManualOffset(element, {
         x: axis === "x" ? parsed : current.x,

package/src/components/editor/useDomEditNudge.ts

@@ -189,7 +189,7 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
     if (!targets) return null;
     const members: ManualOffsetDragMember[] = [];
     for (const target of targets) {
-      const result = createManualOffsetDragMember(target);
+      const result = createManualOffsetDragMember({ ...target, gesture: "nudge" });
       if (!result.ok) {
         restoreManualOffsetDragMembers(members);
         return null;

package/src/hooks/appHotkeysDispatch.ts

@@ -14,13 +14,7 @@ import { STUDIO_PLAIN_KEYS } from "../player/components/studioShortcuts";
 // following useTimelineDeleteOps's precedent. Pure functions, no hooks — the
 // hook still owns the actual keydown listeners and calls into these.
 
-/** Exported so useAppHotkeys's own history-only preview listener can reuse
- *  the same undo/redo key arbitration without duplicating it. */
-export function handleUndoRedoKey(
-  event: KeyboardEvent,
-  onUndo: () => void,
-  onRedo: () => void,
-): boolean {
+function handleUndoRedoKey(event: KeyboardEvent, onUndo: () => void, onRedo: () => void): boolean {
   const key = event.key.toLowerCase();
   if (key === "z" && !event.shiftKey) {
     event.preventDefault();

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

package/src/hooks/gsapRuntimeBridge.ts

@@ -35,7 +35,7 @@ import {
   pickClosestToPlayhead,
   readGsapPositionFromIframe,
 } from "./gsapPositionDetection";
-import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
+import { hasNonHoldTweenForElement, POSITION_CHANNELS } from "./gsapRuntimeKeyframes";
 import { getAnimationsForElement } from "./gsapElementMatch";
 import {
   animationWritesAnyProperty,
@@ -43,22 +43,6 @@ import {
   type GsapEditOutcome,
 } from "./gsapEditOutcome";
 
-// 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).
-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.
-  "translateX",
-  "translateY",
-];
 const POSITION_CHANNEL_SET = new Set<string>(POSITION_CHANNELS);
 
 const ROTATION_CHANNELS: string[] = ["rotation", "rotationX", "rotationY", "rotationZ"];

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -405,6 +405,41 @@ export function hasNonHoldTweenForElement(
   return !!targetEl && hasNonHoldTween(timelinesOf(iframe), targetEl, channels, compositionId);
 }
 
+// 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",
+  // 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. */
+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)),
+    ),
+  );
+}
+
+/** GSAP owns this element's position: a tween or hold writes it, or GSAP already renders its
+ *  transform (a CSS translate would then apply twice). Everything else moves by plain CSS. */
+export function gsapWritesPosition(el: Element): boolean {
+  const cache = (el as { _gsap?: { renderTransform?: unknown } })._gsap;
+  return !!cache?.renderTransform || gsapWritesChannels(el, MOVE_CHANNELS);
+}
+
 /** `hasNonHoldTweenForElement` for an element in hand, read from its own window's timelines. */
 export function elementHasNonHoldTween(el: Element, channels?: string[]): boolean {
   const win = el.ownerDocument.defaultView as {