feat(studio): single-source manual offset + rotation via the GSAP timeline

Dragging or rotating an element writes into the GSAP timeline (the single source of
truth) instead of a parallel --hf-studio-offset / --hf-studio-rotation CSS var: static
elements commit a tl.set (idempotent on re-edit), tweened elements edit keyframes, and
the live preview moves via gsap.set so what you see equals what is written and renders.
Removes the dual-channel CSS-var/transform reconciliation behind the
fling / disappear / runaway / double-stack / wrong-start bug class — for BOTH position
and rotation (gesture base read from the gsap transform, gsap.set live preview, tl.set/
keyframe commit, dropped the handleDom*Commit CSS fallbacks).

Subcompositions edit the same single-source way, which surfaced and fixes:
- resolve a subcomp element's source file via the composition-id map (the runtime drops
  the source linkage when inlining the subcomposition);
- a selected element's selection box AND motion path use basic visibility, not the
  occlusion heuristic (a backgroundless opacity-1 scene above it is not an opaque cover);
- soft reload rebuilds ONLY the committed composition's timeline, leaving other
  compositions' timelines intact (no cross-composition revert);
- read keyframes from the element's OWN composition timeline (scan all timelines, not
  the first unstable key);
- delete-all uses a soft reload too, so editing no longer hard-reloads the iframe.

Author: miguel-heygen

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

@@ -282,7 +282,6 @@ describe("DomEditOverlay", () => {
     };
 
     let currentSelection: DomEditSelection | null = selection;
-    const onToggleRecording = vi.fn();
     const iframeRef = { current: document.createElement("iframe") as HTMLIFrameElement | null };
     const originalPointerCapture = HTMLDivElement.prototype.setPointerCapture;
     HTMLDivElement.prototype.setPointerCapture = () => {};
@@ -298,8 +297,6 @@ describe("DomEditOverlay", () => {
           hoverSelection: null,
           onSelectionChange: (next: DomEditSelection) => setSelected(next),
         }),
-        recordingState: "idle",
-        onToggleRecording,
       });
     }
 
@@ -340,16 +337,6 @@ describe("DomEditOverlay", () => {
       "drag",
       expect.objectContaining({ button: 0 }),
     );
-    const recordButton = host.querySelector(
-      '[aria-label="Record gesture (R)"]',
-    ) as HTMLButtonElement;
-    expect(recordButton).toBeTruthy();
-
-    act(() => {
-      recordButton.click();
-    });
-
-    expect(onToggleRecording).toHaveBeenCalledTimes(1);
 
     act(() => {
       root.unmount();

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

@@ -14,7 +14,7 @@ import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
 import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
 import { GridOverlay } from "./GridOverlay";
-import { GestureRecordBadge, type GestureRecordingState } from "./GestureRecordControl";
+import type { GestureRecordingState } from "./GestureRecordControl";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -87,8 +87,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onGroupPathOffsetCommit,
   onBoxSizeCommit,
   onRotationCommit,
-  recordingState,
-  onToggleRecording,
 }: DomEditOverlayProps) {
   const overlayRef = useRef<HTMLDivElement | null>(null);
   const boxRef = useRef<HTMLDivElement | null>(null);
@@ -434,13 +432,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
               />
             </div>
           )}
-          {onToggleRecording && (
-            <GestureRecordBadge
-              rect={overlayRect}
-              recordingState={recordingState}
-              onToggleRecording={onToggleRecording}
-            />
-          )}
           <div
             key={selectionKey}
             ref={boxRef}

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

@@ -4,7 +4,7 @@ import { useDomEditContext } from "../../contexts/DomEditContext";
 import { usePlayerStore } from "../../player/store/playerStore";
 import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
 import { parkPlayheadOnKeyframe } from "../../hooks/gsapDragCommit";
-import { isElementVisibleInPreview } from "./domEditOverlayGeometry";
+import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
 import {
   buildMotionPathGeometry,
   nearestPointOnPath,
@@ -174,7 +174,11 @@ function useMotionPathData(
           /* cross-origin guard */
         }
         const live = isPreviewHtmlElement(target, el) ? target : null;
-        const vis = live ? isElementVisibleInPreview(live) : true;
+        // Basic visibility (display/visibility/opacity), NOT the occlusion heuristic:
+        // the motion path belongs to the explicitly-selected element, so an opacity-1
+        // backgroundless scene "covering" it must not suppress the path — same reason
+        // the selection overlay uses isElementVisibleForOverlay (see useDomEditOverlayRects).
+        const vis = live ? isElementVisibleForOverlay(live) : true;
         setVisibleInPreview((prev) => (prev === vis ? prev : vis));
         if (live) {
           const h = elementHome(live);
@@ -250,6 +254,9 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
   // modifies it rather than adding a keyframe.
   const activeKeyframePct = usePlayerStore((s) => s.activeKeyframePct);
   const dragRef = useRef<DragState | null>(null);
+  // Park-on-click is debounced so a double-click cancels the seek (see onUp).
+  const parkTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(() => () => clearTimeout(parkTimerRef.current), []);
 
   // Create mode: a selected element with no positional motion. A double-click on
   // the canvas authors a new motionPath from the element to that point.
@@ -373,6 +380,7 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     ref: MotionNodeRef,
   ) => {
     if (!interactive) return;
+    if (e.button !== 0) return; // primary button only — right-click is the context menu
     e.stopPropagation();
     (e.target as Element).setPointerCapture(e.pointerId);
     dragRef.current = {
@@ -412,8 +420,16 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
       // activeKeyframePct) instead of creating a new one.
       if (d.ref.type === "keyframe") {
         usePlayerStore.getState().setActiveKeyframePct(d.ref.pct);
-        const anim = selectedGsapAnimations?.find((a) => a.id === animId);
-        if (anim) parkPlayheadOnKeyframe(anim, d.ref.pct);
+        const ref = d.ref;
+        // Debounce the playhead seek: a double-click cancels it (e.detail >= 2),
+        // so only a lone single-click parks the playhead on the keyframe.
+        clearTimeout(parkTimerRef.current);
+        if (e.detail < 2) {
+          parkTimerRef.current = setTimeout(() => {
+            const anim = selectedGsapAnimations?.find((a) => a.id === animId);
+            if (anim) parkPlayheadOnKeyframe(anim, ref.pct);
+          }, 250);
+        }
       }
       return; // no commit
     }

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

@@ -5,6 +5,7 @@
 import { type DomEditSelection } from "./domEditing";
 import {
   createManualOffsetDragMember,
+  readGsapRotation,
   restoreManualOffsetDragMembers,
   type ManualOffsetDragMember,
 } from "./manualOffsetDrag";
@@ -115,7 +116,10 @@ export function startGesture(
     return false;
 
   const size = readStudioBoxSize(sel.element);
-  const rotation = readStudioRotation(sel.element);
+  // Single-source rotation base = the live GSAP transform rotation plus any legacy
+  // `--hf-studio-rotation` CSS var (old projects), so a rotate gesture starts from the
+  // element's actual visual angle and commits an absolute angle to the timeline.
+  const rotation = { angle: readGsapRotation(sel.element) + readStudioRotation(sel.element).angle };
   const actualWidth = size.width > 0 ? size.width : rect.width / rect.editScaleX;
   const actualHeight = size.height > 0 ? size.height : rect.height / rect.editScaleY;
   let initialPathOffset = captureStudioPathOffset(sel.element);

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

@@ -141,6 +141,31 @@ export function getElementDepth(el: HTMLElement): number {
 
 // ─── Composition source resolution ───────────────────────────────────────────
 
+// The runtime INLINES subcompositions and strips the source-file linkage from the
+// mounted root (it keeps `data-composition-id` but drops `data-composition-src`/
+// `-file`), so a subcomp element's DOM ancestors no longer say which file it came
+// from. This project-global map (composition-id → source file, built once from
+// index.html's clips — see NLELayout) recovers it. The studio loads one project at a
+// time, so module scope is the right lifetime; it's empty until set, in which case
+// resolution falls back to the historical attribute-only behavior.
+let compositionSourceMap: Map<string, string> = new Map();
+
+export function setCompositionSourceMap(map: Map<string, string>): void {
+  compositionSourceMap = map;
+}
+
+function sourceFromCompositionId(ownerRoot: HTMLElement | null): string | undefined {
+  if (!ownerRoot || compositionSourceMap.size === 0) return undefined;
+  // The runtime may rename the mounted id to a runtime-unique one, preserving the
+  // authored id on `data-hf-original-composition-id` — prefer that, then the current id.
+  const authored = ownerRoot.getAttribute("data-hf-original-composition-id");
+  const current = ownerRoot.getAttribute("data-composition-id");
+  return (
+    (authored ? compositionSourceMap.get(authored) : undefined) ??
+    (current ? compositionSourceMap.get(current) : undefined)
+  );
+}
+
 export function getSourceFileForElement(
   el: HTMLElement,
   activeCompositionPath: string | null,
@@ -152,6 +177,7 @@ export function getSourceFileForElement(
     sourceHost?.getAttribute("data-composition-src") ??
     ownerRoot?.getAttribute("data-composition-file") ??
     ownerRoot?.getAttribute("data-composition-src") ??
+    sourceFromCompositionId(ownerRoot) ??
     activeCompositionPath ??
     "index.html";
 

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

@@ -16,6 +16,7 @@ export {
   endStudioManualEditGesture,
   isStudioManualEditGestureCurrent,
   readStudioPathOffset,
+  readAppliedStudioPathOffset,
   readStudioBoxSize,
   readStudioRotation,
   applyStudioPathOffset,

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

@@ -70,6 +70,19 @@ export function readStudioPathOffset(element: HTMLElement): { x: number; y: numb
   };
 }
 
+/**
+ * The path offset ACTUALLY applied right now. The `--hf-studio-offset` vars can
+ * linger after GSAP re-bakes the element's transform (`translate:"none"`), so the
+ * raw var isn't a safe drag base — using it re-commits a phantom offset and flings
+ * the element off-screen. The offset only counts when the inline `translate` is the
+ * studio var-translate; otherwise it's dormant and the applied offset is zero.
+ */
+export function readAppliedStudioPathOffset(element: HTMLElement): { x: number; y: number } {
+  return (element.style.translate || "").includes(STUDIO_OFFSET_X_PROP)
+    ? readStudioPathOffset(element)
+    : { x: 0, y: 0 };
+}
+
 export function readStudioBoxSize(element: HTMLElement): { width: number; height: number } {
   return {
     width: readPxCustomProperty(element, STUDIO_WIDTH_PROP),

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

@@ -193,6 +193,12 @@ describe("createManualOffsetDragMember uses raw CSS var offset", () => {
 
     element.style.setProperty(STUDIO_OFFSET_X_PROP, "30px");
     element.style.setProperty(STUDIO_OFFSET_Y_PROP, "10px");
+    // Old projects bake the offset by referencing the vars in the inline
+    // `translate` longhand — that's what makes the offset "applied" and thus the
+    // valid drag base (readAppliedStudioPathOffset). A raw var with no applied
+    // translate is dormant and reads as zero. Assign the typed `.translate`
+    // accessor (happy-dom doesn't surface it via setProperty).
+    element.style.translate = `var(${STUDIO_OFFSET_X_PROP}, 0px) var(${STUDIO_OFFSET_Y_PROP}, 0px)`;
     element.style.setProperty("transform", "translate(50px, -15px)");
 
     element.getBoundingClientRect = () => {
@@ -228,6 +234,12 @@ describe("createManualOffsetDragMember uses raw CSS var offset", () => {
     // Simulate GSAP baking a translate into transform each cycle
     for (let cycle = 0; cycle < 3; cycle++) {
       element.style.setProperty("transform", `translate(${50 * (cycle + 1)}px, 0px)`);
+      // Mark the offset as APPLIED (the inline translate references the studio
+      // vars, the form an old project bakes) so readAppliedStudioPathOffset reads
+      // the var, not zero. Without this the var is dormant and reads as zero.
+      // Assign the typed `.translate` accessor (happy-dom doesn't surface it via
+      // setProperty).
+      element.style.translate = `var(${STUDIO_OFFSET_X_PROP}, 0px) var(${STUDIO_OFFSET_Y_PROP}, 0px)`;
 
       const result = createManualOffsetDragMember({
         key: "test",

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

@@ -5,10 +5,71 @@ import {
   beginStudioManualEditGesture,
   captureStudioPathOffset,
   endStudioManualEditGesture,
-  readStudioPathOffset,
+  readAppliedStudioPathOffset,
   restoreStudioPathOffset,
   type StudioPathOffsetSnapshot,
 } from "./manualEdits";
+import { computeDraggedGsapPosition } from "../../hooks/draggedGsapPosition";
+
+interface OffsetDragGsap {
+  set: (el: Element, vars: Record<string, number | string>) => void;
+  getProperty: (el: Element, prop: string) => number;
+}
+
+function getOffsetDragGsap(element: HTMLElement): OffsetDragGsap | null {
+  const win = element.ownerDocument.defaultView as
+    | (Window & { gsap?: Partial<OffsetDragGsap> })
+    | null;
+  const gsap = win?.gsap;
+  return gsap?.set && gsap.getProperty ? (gsap as OffsetDragGsap) : null;
+}
+
+/**
+ * Live drag preview through the GSAP channel — the SAME channel the commit
+ * lands in (a `tl.set`/keyframe on the timeline), so what the user sees while
+ * dragging equals what gets written (plan R3/R4). Reuses the commit's
+ * base+delta+rotation math so preview and commit agree by construction. Returns
+ * true when handled via gsap; false when gsap is unavailable (caller falls back
+ * to the CSS draft).
+ */
+function applyOffsetDragDraftViaGsap(
+  element: HTMLElement,
+  offset: { x: number; y: number },
+): boolean {
+  const gsap = getOffsetDragGsap(element);
+  if (!gsap) return false;
+  // GSAP owns the transform; neutralize the CSS translate longhand so the two
+  // channels can't compose into a doubled position.
+  element.style.setProperty("translate", "none");
+  const fallbackBase = {
+    x: Number(gsap.getProperty(element, "x")) || 0,
+    y: Number(gsap.getProperty(element, "y")) || 0,
+  };
+  const { newX, newY } = computeDraggedGsapPosition(element, offset, fallbackBase);
+  gsap.set(element, { x: newX, y: newY });
+  return true;
+}
+
+/**
+ * Live rotation preview through the GSAP channel — the SAME channel the commit
+ * lands in (a `tl.set`/keyframe rotation), mirroring `applyOffsetDragDraftViaGsap`.
+ * GSAP owns the transform rotation, so neutralize the CSS `rotate` longhand to keep
+ * the two channels from composing. `angle` is the absolute target rotation. Returns
+ * false when gsap is unavailable (caller falls back to the CSS draft).
+ */
+export function applyRotationDraftViaGsap(element: HTMLElement, angle: number): boolean {
+  const gsap = getOffsetDragGsap(element);
+  if (!gsap) return false;
+  element.style.setProperty("rotate", "none");
+  gsap.set(element, { rotation: angle });
+  return true;
+}
+
+/** Current GSAP transform rotation — the single-source rotation base. 0 if gsap is unavailable. */
+export function readGsapRotation(element: HTMLElement): number {
+  const gsap = getOffsetDragGsap(element);
+  return gsap ? Number(gsap.getProperty(element, "rotation")) || 0 : 0;
+}
 
 const DEFAULT_OFFSET_PROBE_PX = 100;
 const MIN_PROBE_VECTOR_LENGTH_PX = 0.01;
@@ -241,7 +302,10 @@ export function createManualOffsetDragMember(input: {
   element: HTMLElement;
   rect: ManualOffsetDragRect;
 }): ManualOffsetDragMemberResult {
-  const initialOffset = readStudioPathOffset(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.
+  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));
 
@@ -335,7 +399,12 @@ export function applyManualOffsetDragDraft(
   dy: number,
 ): { x: number; y: number } {
   const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
-  applyStudioPathOffsetDraft(member.element, offset);
+  // 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)) {
+    applyStudioPathOffsetDraft(member.element, offset);
+  }
   return offset;
 }
 
@@ -345,7 +414,13 @@ export function applyManualOffsetDragCommit(
   dy: number,
 ): { x: number; y: number } {
   const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
-  applyStudioPathOffset(member.element, offset);
+  // 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)) {
+    applyStudioPathOffset(member.element, offset);
+  }
   return offset;
 }