fix(studio,core): persist manual position edits for GSAP-owned elements

- sourceMutation: linkedom CSSStyleDeclaration silently drops CSS custom
  properties and transform longhands via setProperty; patch the style
  attribute string directly so --hf-studio-offset-* and translate survive
  the server round-trip (positions never reached disk before this)
- gsapAnimatesTransform(): GSAP owns the full transform stack when it tweens
  ANY transform prop (scale, rotation, ...), not just x/y — it folds CSS
  translate into its cache once at init, zeroes the longhand once, and never
  re-reads it
- applyStudioPathOffset: for GSAP-owned elements keep translate:none live and
  sync the offset into GSAP's cache via gsap.set; writing the longhand
  double-applied the offset (disappearing elements, scrub snap-back)
- buildPathOffsetPatches: emit the var() translate expression explicitly so
  the persisted file re-folds on reload (live inline is none)
- StudioPathOffsetSnapshot: capture/restore GSAP x/y — the drag-response
  probe mutates GSAP's cache, which inline-style restore cannot undo (click
  made elements jump by the probe distance)
- reapplyPathOffsets: skip GSAP-owned elements (was x/y-only) to stop
  seek-time double-apply
- STUDIO_GSAP_DRAG_INTERCEPT flag (default off): keyframe drag intercept is
  opt-in until its recording path is hardened; commits take the CSS persist
  path

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: vanceingalls

packages/core/src/studio-api/helpers/manualEditsRenderScript.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 export interface StudioManualEditsRenderScriptOptions {
   activeCompositionPath?: string | null;
 }

packages/core/src/studio-api/helpers/sourceMutation.ts

@@ -223,6 +223,33 @@ function isSafeAttributeValue(name: string, value: string): boolean {
   return true;
 }
 
+function patchStyleAttrString(style: string, property: string, value: string | null): string {
+  const props = new Map<string, string>();
+  const order: string[] = [];
+  for (const decl of style.split(";")) {
+    const colon = decl.indexOf(":");
+    if (colon < 0) continue;
+    const key = decl.slice(0, colon).trim();
+    const val = decl.slice(colon + 1).trim();
+    if (!key) continue;
+    if (!props.has(key)) order.push(key);
+    props.set(key, val);
+  }
+  if (value === null) {
+    props.delete(property);
+    const idx = order.indexOf(property);
+    if (idx >= 0) order.splice(idx, 1);
+  } else {
+    if (!props.has(property)) order.push(property);
+    props.set(property, value);
+  }
+  return order
+    .map((k) => `${k}: ${props.get(k) ?? ""}`)
+    .filter((d) => d.trim())
+    .join("; ");
+}
+
+// fallow-ignore-next-line complexity
 export function patchElementInHtml(
   source: string,
   target: SourceMutationTarget,
@@ -236,10 +263,14 @@ export function patchElementInHtml(
   for (const op of operations) {
     switch (op.type) {
       case "inline-style":
-        if (op.value != null) {
-          htmlEl.style.setProperty(op.property, op.value);
-        } else {
-          htmlEl.style.removeProperty(op.property);
+        // linkedom's CSSStyleDeclaration does not support CSS custom properties
+        // (--foo) or newer individual transform properties (translate, rotate,
+        // scale) via style.setProperty(). Manipulate the style attribute string
+        // directly so all property names survive the round-trip.
+        {
+          const raw = htmlEl.getAttribute("style") ?? "";
+          const patched = patchStyleAttrString(raw, op.property, op.value);
+          htmlEl.setAttribute("style", patched);
         }
         break;
       case "attribute":

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

@@ -1,7 +1,37 @@
+// GSAP's CSSPlugin takes ownership of the element's entire transform stack
+// when it tweens ANY of these — it bakes the CSS `translate` longhand into
+// style.transform at init and writes `translate: none` every tick. Position
+// reapply/strip logic must therefore stand down for all of them, not just x/y.
+const GSAP_TRANSFORM_PROPS = [
+  "x",
+  "y",
+  "xPercent",
+  "yPercent",
+  "scale",
+  "scaleX",
+  "scaleY",
+  "rotation",
+  "rotate",
+  "rotationX",
+  "rotationY",
+  "skewX",
+  "skewY",
+  "transform",
+];
+
+/**
+ * True when GSAP animates any transform-affecting property on the element,
+ * meaning GSAP owns `style.transform` and has neutralized CSS `translate`.
+ */
+export function gsapAnimatesTransform(el: HTMLElement): boolean {
+  return gsapAnimatesProperty(el, ...GSAP_TRANSFORM_PROPS);
+}
+
 /**
  * Checks whether GSAP actively animates one or more CSS/GSAP properties on
  * the given element by inspecting all registered `__timelines`.
  */
+// fallow-ignore-next-line complexity
 export function gsapAnimatesProperty(el: HTMLElement, ...props: string[]): boolean {
   const win = el.ownerDocument.defaultView as
     | (Window & {

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

@@ -83,6 +83,16 @@ export const STUDIO_RAZOR_TOOL_ENABLED = resolveStudioBooleanEnvFlag(
   false,
 );
 
+// When disabled (the default), drag/resize/rotate commits always take the CSS
+// persist path instead of being intercepted into GSAP script keyframe
+// mutations. The keyframe intercept rewrites timeline tweens from drag
+// gestures and is opt-in until its recording path is hardened.
+export const STUDIO_GSAP_DRAG_INTERCEPT_ENABLED = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_ENABLE_GSAP_DRAG_INTERCEPT", "VITE_STUDIO_GSAP_DRAG_INTERCEPT_ENABLED"],
+  false,
+);
+
 export const STUDIO_PREVIEW_SELECTION_ENABLED = STUDIO_INSPECTOR_PANELS_ENABLED;
 
 export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled";

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

@@ -32,7 +32,7 @@ import {
 } from "./manualEditsTypes";
 import { roundRotationAngle } from "./manualEditsParsing";
 import { applyStudioMotionFromDom } from "./studioMotion";
-import { gsapAnimatesProperty } from "./gsapAnimatesProperty";
+import { gsapAnimatesProperty, gsapAnimatesTransform } from "./gsapAnimatesProperty";
 
 /* ── Gesture tracking ─────────────────────────────────────────────── */
 let studioManualEditGestureId = 0;
@@ -223,6 +223,7 @@ function isIdentityAfterTranslateStrip(m: DOMMatrix): boolean {
   return m.is2D && m.a === 1 && m.b === 0 && m.c === 0 && m.d === 1;
 }
 
+// fallow-ignore-next-line complexity
 function stripGsapTranslateFromTransform(element: HTMLElement): void {
   if (element.hasAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR)) return;
   const transform = element.style.getPropertyValue("transform");
@@ -257,6 +258,18 @@ export function applyStudioPathOffset(
 ): void {
   promoteInlineForTransform(element);
   writeStudioPathOffsetVars(element, offset, { updateBase: options.updateBase ?? true });
+  if (gsapAnimatesTransform(element)) {
+    // GSAP folded the CSS translate into its transform cache at init and owns
+    // style.transform from then on — it zeroes the translate longhand exactly
+    // once (at fold time) and never re-reads it. Writing translate here would
+    // double-apply the offset on top of the baked transform. Keep translate
+    // neutral in the live DOM and push the offset into GSAP's cache instead;
+    // the var() expression is persisted to the source file by the patch
+    // builder, where a reload re-folds it.
+    element.style.setProperty("translate", "none");
+    syncGsapOwnedTransformPosition(element);
+    return;
+  }
   element.style.setProperty(
     "translate",
     composeTranslateValue(
@@ -268,18 +281,36 @@ export function applyStudioPathOffset(
   stripGsapTranslateFromTransform(element);
 }
 
+/**
+ * After committing a new path offset on an element whose transform GSAP owns,
+ * GSAP's internal cache still holds the pre-drag baked translate — the next
+ * seek re-renders from that cache and snaps the element back. Push the new
+ * offset into GSAP so live scrubbing matches what was persisted. (A page
+ * reload re-initializes GSAP from the persisted CSS translate, so this is
+ * only needed for the live session.)
+ */
+function syncGsapOwnedTransformPosition(element: HTMLElement): void {
+  if (!gsapAnimatesTransform(element)) return;
+  const win = element.ownerDocument.defaultView as
+    | (Window & { gsap?: { set: (el: Element, vars: Record<string, unknown>) => void } })
+    | null;
+  if (!win?.gsap?.set) return;
+  const { x, y } = readStudioPathOffset(element);
+  win.gsap.set(element, { x, y });
+}
+
 export function applyStudioPathOffsetDraft(
   element: HTMLElement,
   offset: { x: number; y: number },
 ): void {
   promoteInlineForTransform(element);
   writeStudioPathOffsetVars(element, offset, { updateBase: false });
 
-  const isGsapAnimated = gsapAnimatesProperty(element, "x", "y");
+  const isGsapAnimated = gsapAnimatesTransform(element);
   if (isGsapAnimated) {
-    // For GSAP-animated elements: use gsap.set for positioning (the timeline
-    // is paused during drag). Set translate:none explicitly to prevent
-    // double-counting with the transform.
+    // GSAP owns style.transform (see applyStudioPathOffset): position via
+    // gsap.set while the timeline is paused. Set translate:none explicitly to
+    // prevent double-counting with the baked transform.
     element.style.setProperty("translate", "none");
     const win = element.ownerDocument.defaultView as
       | (Window & { gsap?: { set: (el: Element, vars: Record<string, unknown>) => void } })
@@ -520,10 +551,14 @@ function queryStudioElements(doc: Document, attr: string): HTMLElement[] {
 
 function reapplyPathOffsets(doc: Document): void {
   for (const el of queryStudioElements(doc, STUDIO_PATH_OFFSET_ATTR)) {
-    const gsapSkip = gsapAnimatesProperty(el, "x", "y");
+    // Skip elements where GSAP owns the transform stack — GSAP bakes the
+    // CSS translate into its transform and sets translate: none every tick
+    // when it tweens ANY transform property (x/y, scale, rotation, ...).
+    // Stripping/restoring would oscillate against GSAP's rendering and
+    // double-apply the offset.
+    if (gsapAnimatesTransform(el)) continue;
     const x = el.style.getPropertyValue(STUDIO_OFFSET_X_PROP);
     const y = el.style.getPropertyValue(STUDIO_OFFSET_Y_PROP);
-    if (gsapSkip) continue;
     if (x || y) {
       applyStudioPathOffset(
         el,

packages/studio/src/components/editor/manualEditsDomPatches.test.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 // @vitest-environment happy-dom
 
 import { describe, it, expect } from "vitest";

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

@@ -72,7 +72,23 @@ function appendTransformDisplayOps(element: HTMLElement, ops: PatchOperation[]):
 
 export function buildPathOffsetPatches(element: HTMLElement): PatchOperation[] {
   const ops: PatchOperation[] = [];
-  collectInlineStyleOps(element, [STUDIO_OFFSET_X_PROP, STUDIO_OFFSET_Y_PROP, "translate"], ops);
+  collectInlineStyleOps(element, [STUDIO_OFFSET_X_PROP, STUDIO_OFFSET_Y_PROP], ops);
+  // When GSAP owns the element's transform, the live inline translate is kept
+  // at "none" (the offset lives in GSAP's cache — see applyStudioPathOffset).
+  // Persist the var() expression in that case, so a reload re-folds the offset.
+  const inlineTranslate = element.style.getPropertyValue("translate");
+  const hasOffsetVars =
+    element.style.getPropertyValue(STUDIO_OFFSET_X_PROP) ||
+    element.style.getPropertyValue(STUDIO_OFFSET_Y_PROP);
+  const translateValue =
+    inlineTranslate && inlineTranslate !== "none"
+      ? inlineTranslate
+      : hasOffsetVars
+        ? `var(${STUDIO_OFFSET_X_PROP}, 0px) var(${STUDIO_OFFSET_Y_PROP}, 0px)`
+        : null;
+  if (translateValue) {
+    ops.push({ type: "inline-style", property: "translate", value: translateValue });
+  }
   ops.push({ type: "attribute", property: STUDIO_PATH_OFFSET_ATTR, value: "true" });
   collectAttributeOps(
     element,

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

@@ -4,6 +4,7 @@ import {
   styleUsesStudioRotation,
   restoreInlineDisplay,
 } from "./manualEditsDom";
+import { gsapAnimatesTransform } from "./gsapAnimatesProperty";
 import {
   STUDIO_OFFSET_X_PROP,
   STUDIO_OFFSET_Y_PROP,
@@ -87,14 +88,32 @@ export function captureStudioRotation(element: HTMLElement): StudioRotationSnaps
   };
 }
 
+type GsapWindow = Window & {
+  gsap?: {
+    getProperty?: (el: Element, prop: string) => number | string;
+    set?: (el: Element, vars: Record<string, unknown>) => void;
+  };
+};
+
 export function captureStudioPathOffset(element: HTMLElement): StudioPathOffsetSnapshot {
+  let gsapX: number | null = null;
+  let gsapY: number | null = null;
+  if (gsapAnimatesTransform(element)) {
+    const win = element.ownerDocument.defaultView as GsapWindow | null;
+    if (win?.gsap?.getProperty) {
+      gsapX = Number(win.gsap.getProperty(element, "x")) || 0;
+      gsapY = Number(win.gsap.getProperty(element, "y")) || 0;
+    }
+  }
   return {
     translate: element.style.getPropertyValue("translate"),
     x: element.style.getPropertyValue(STUDIO_OFFSET_X_PROP),
     y: element.style.getPropertyValue(STUDIO_OFFSET_Y_PROP),
     marker: element.getAttribute(STUDIO_PATH_OFFSET_ATTR),
     originalTranslate: element.getAttribute(STUDIO_ORIGINAL_TRANSLATE_ATTR),
     originalInlineTranslate: element.getAttribute(STUDIO_ORIGINAL_INLINE_TRANSLATE_ATTR),
+    gsapX,
+    gsapY,
   };
 }
 
@@ -183,6 +202,13 @@ export function restoreStudioPathOffset(
     STUDIO_ORIGINAL_INLINE_TRANSLATE_ATTR,
     previous.originalInlineTranslate,
   );
+
+  // Draft positioning on GSAP-owned elements goes through gsap.set, which
+  // mutates GSAP's transform cache — restore it alongside the inline styles.
+  if (previous.gsapX != null || previous.gsapY != null) {
+    const win = element.ownerDocument.defaultView as GsapWindow | null;
+    win?.gsap?.set?.(element, { x: previous.gsapX ?? 0, y: previous.gsapY ?? 0 });
+  }
 }
 
 /* ── Clear functions ──────────────────────────────────────────────── */

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

@@ -101,4 +101,12 @@ export interface StudioPathOffsetSnapshot {
   marker: string | null;
   originalTranslate: string | null;
   originalInlineTranslate: string | null;
+  /**
+   * GSAP's cached x/y at capture time, for elements whose transform GSAP
+   * owns. Draft positioning mutates GSAP's cache (gsap.set), which inline
+   * style restoration alone cannot undo. Null when GSAP does not own the
+   * element's transform.
+   */
+  gsapX: number | null;
+  gsapY: number | null;
 }

packages/studio/src/contexts/DomEditContext.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { useDomEditSession } from "../hooks/useDomEditSession";