@hyperframes/studio 0.8.124 → 0.8.126

package/src/components/editor/useMotionPathData.ts

@@ -1,31 +1,19 @@
 import { useEffect, useRef, useState, type RefObject } from "react";
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
 import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
 import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
-import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGeometry";
+import {
+  buildMotionPathGeometry,
+  type MotionPathGeometry,
+  type MotionPathHome,
+} from "./motionPathGeometry";
+import { elementHome } from "./motionPathHome";
 import { subscribeOverlayFrame } from "./overlayFrameLoop";
 import { usePlayerStore } from "../../player/store/playerStore";
 
 type Rect = { left: number; top: number; width: number; height: number };
 
-// The translate (e/f) components of an element's computed transform, in comp px.
-// A group wrapper dragged via GSAP carries its offset here, not in offsetLeft/Top.
-function transformTranslate(el: HTMLElement): { x: number; y: number } {
-  const t = el.ownerDocument?.defaultView?.getComputedStyle(el).transform;
-  if (!t || t === "none") return { x: 0, y: 0 };
-  const m3 = t.match(/matrix3d\(([^)]+)\)/);
-  if (m3) {
-    const v = m3[1].split(",").map(Number);
-    return { x: v[12] || 0, y: v[13] || 0 };
-  }
-  const m = t.match(/matrix\(([^)]+)\)/);
-  if (m) {
-    const v = m[1].split(",").map(Number);
-    return { x: v[4] || 0, y: v[5] || 0 };
-  }
-  return { x: 0, y: 0 };
-}
-
 // Perspective foreshortening of the element's OWN transform (matrix3d m44). A
 // depth element (translateZ toward the viewer) renders 1/m44× larger, so its
 // animated x/y offsets travel 1/m44× further on screen than the flat preview
@@ -40,43 +28,6 @@ export function transformWDivisor(el: HTMLElement): number {
   return Number.isFinite(w) && w > 0 ? w : 1;
 }
 
-export function elementHome(el: HTMLElement): { x: number; y: number } {
-  let left = 0;
-  let top = 0;
-  let node: HTMLElement | null = el;
-  while (node) {
-    left += node.offsetLeft;
-    top += node.offsetTop;
-    // Ancestor transforms (e.g. a group wrapper moved via GSAP) shift where the
-    // element actually renders, so the path must anchor on top of them. The element's
-    // OWN transform is excluded — that's the animated offset the path itself draws.
-    if (node !== el) {
-      const t = transformTranslate(node);
-      left += t.x;
-      top += t.y;
-    }
-    const parent = node.offsetParent as HTMLElement | null;
-    if (!parent || parent.hasAttribute("data-composition-id")) break;
-    node = parent;
-  }
-  let x = left + el.offsetWidth / 2;
-  let y = top + el.offsetHeight / 2;
-  if ((el.style.translate ?? "").includes("var(")) {
-    x += Number.parseFloat(el.style.getPropertyValue("--hf-studio-offset-x")) || 0;
-    y += Number.parseFloat(el.style.getPropertyValue("--hf-studio-offset-y")) || 0;
-  }
-  return { x, y };
-}
-
-export function isPreviewHtmlElement(
-  node: Element | null | undefined,
-  iframe: HTMLIFrameElement | null,
-): node is HTMLElement {
-  const Ctor = (iframe?.contentWindow as unknown as { HTMLElement?: typeof HTMLElement } | null)
-    ?.HTMLElement;
-  return Boolean(node && Ctor && node instanceof Ctor);
-}
-
 function rectsClose(a: Rect, b: Rect): boolean {
   return (
     Math.abs(a.left - b.left) < 0.5 &&
@@ -104,7 +55,7 @@ export function useMotionPathData(
   geometry: MotionPathGeometry | null;
   geometryResolved: boolean;
   visibleInPreview: boolean;
-  home: { x: number; y: number } | null;
+  home: MotionPathHome | null;
   pScale: number;
 } {
   const [rect, setRect] = useState<Rect | null>(null);
@@ -112,7 +63,7 @@ export function useMotionPathData(
   const resolvedForRef = useRef<string | null>(null);
   const geometryResolved = resolvedForRef.current === selector;
   const [visibleInPreview, setVisibleInPreview] = useState(true);
-  const [home, setHome] = useState<{ x: number; y: number } | null>(null);
+  const [home, setHome] = useState<MotionPathHome | null>(null);
   // Perspective magnification (1/m44) of the selected element — applied to the
   // path's offset points so depth (translateZ) elements' paths track on screen.
   const [pScale, setPScale] = useState(1);
@@ -146,13 +97,21 @@ export function useMotionPathData(
         } catch {
           /* cross-origin guard */
         }
-        const live = isPreviewHtmlElement(target, el) ? target : null;
+        const live = isHtmlElement(target) ? target : null;
         const vis = live ? isElementVisibleForOverlay(live) : true;
         setVisibleInPreview((prev) => (prev === vis ? prev : vis));
         if (live) {
           const h = elementHome(live);
           setHome((prev) =>
-            prev && Math.abs(prev.x - h.x) < 0.5 && Math.abs(prev.y - h.y) < 0.5 ? prev : h,
+            prev &&
+            Math.abs(prev.x - h.x) < 0.5 &&
+            Math.abs(prev.y - h.y) < 0.5 &&
+            prev.w === h.w &&
+            prev.h === h.h &&
+            prev.ax === h.ax &&
+            prev.ay === h.ay
+              ? prev
+              : h,
           );
           const ps = 1 / transformWDivisor(live);
           setPScale((p) => (Math.abs(p - ps) < 0.001 ? p : ps));
@@ -173,7 +132,10 @@ export function useMotionPathData(
       const base = read ? readGsapPositionFromIframe(iframeRef.current, selector) : null;
       const next = buildMotionPathGeometry(read, base ?? undefined);
       setGeometry((prev) =>
-        prev?.points === next?.points && prev?.kind === next?.kind ? prev : next,
+        prev?.kind === next?.kind &&
+        JSON.stringify([prev?.nodes, prev?.start]) === JSON.stringify([next?.nodes, next?.start])
+          ? prev
+          : next,
       );
       resolvedForRef.current = selector;
     };

package/src/components/sidebar/CompositionsTab.thumbnails.test.tsx

@@ -39,6 +39,7 @@ class ViewportObserver {
     const entry = { isIntersecting: true } as IntersectionObserverEntry;
     this.callback([entry], this as unknown as IntersectionObserver);
   }
+  unobserve() {}
   disconnect() {}
 }
 

package/src/hooks/gestureTransaction.test.ts

@@ -281,6 +281,66 @@ describe("runGestureTransaction", () => {
     log.mockRestore();
   });
 
+  it("measures a box undo painted back mid-save as the edit drew it, so it reports no change", async () => {
+    const element = document.createElement("div");
+    let undone = false;
+    vi.spyOn(element, "getBoundingClientRect").mockImplementation(() =>
+      undone ? rect(0, 0, 50, 40) : rect(10, 20, 100, 80),
+    );
+    const draw = <T>(run: () => T): T => {
+      undone = false;
+      try {
+        return run();
+      } finally {
+        undone = true;
+      }
+    };
+
+    await runGestureTransaction({
+      element,
+      label: "Resize layer",
+      settle: vi.fn(),
+      persist: async () => void (undone = true),
+      restore: vi.fn(),
+      draw,
+    });
+
+    expect(trackStudioEventMock).not.toHaveBeenCalledWith(
+      "commit_invariant_violation",
+      expect.anything(),
+    );
+  });
+
+  it("measures as the edit drew it when undo painted the box back before the transaction began", async () => {
+    const element = document.createElement("div");
+    let undone = true;
+    vi.spyOn(element, "getBoundingClientRect").mockImplementation(() =>
+      undone ? rect(0, 0, 50, 40) : rect(10, 20, 100, 80),
+    );
+    const draw = <T>(run: () => T): T => {
+      undone = false;
+      try {
+        return run();
+      } finally {
+        undone = true;
+      }
+    };
+
+    await runGestureTransaction({
+      element,
+      label: "Resize layer",
+      settle: vi.fn(),
+      persist: async () => undefined,
+      restore: vi.fn(),
+      draw,
+    });
+
+    expect(trackStudioEventMock).not.toHaveBeenCalledWith(
+      "commit_invariant_violation",
+      expect.anything(),
+    );
+  });
+
   it("skips the pixel assertion for live position tweens", async () => {
     const element = document.createElement("div");
     const getRect = vi.spyOn(element, "getBoundingClientRect");

package/src/hooks/gestureTransaction.ts

@@ -18,6 +18,7 @@ export interface GestureTransaction {
   afterBufferedCommitsSaved?(): Promise<void>;
   restore(): void;
   skipPixelAssert?: boolean;
+  draw?<T>(run: () => T): T;
 }
 
 let transactionCounter = 0;
@@ -126,7 +127,9 @@ export function runGestureTransaction(tx: GestureTransaction): Promise<void> {
   tx.settle();
   logCommit("settled", { label: tx.label, coalesceKey });
 
-  const before = !tx.skipPixelAssert ? readPixelRect(tx.element) : null;
+  const measure = () =>
+    tx.draw ? tx.draw(() => readPixelRect(tx.element)) : readPixelRect(tx.element);
+  const before = !tx.skipPixelAssert ? measure() : null;
   const commit: TxCommit = (commitMutation) => {
     const wrapped: CommitMutation = (selection, mutation, options) => {
       mutationCount += 1;
@@ -150,7 +153,7 @@ export function runGestureTransaction(tx: GestureTransaction): Promise<void> {
       const durationMs = Math.round(performance.now() - startedAt);
       logCommit("persisted", { label: tx.label, coalesceKey });
       if (before) {
-        const after = readPixelRect(tx.element);
+        const after = measure();
         const delta = pixelDelta(before, after);
         if (exceedsPixelTolerance(delta)) {
           logCommit("persist-changed-pixels", { label: tx.label, before, after, delta });

package/src/hooks/gsapGestureOutcome.ts

@@ -12,8 +12,11 @@ import {
   type KeyframeUsageAction,
 } from "../utils/keyframeUsage";
 import type { GeometryCommitResult } from "../utils/previewFeatureUsage";
+import { adoptingStudioPendingEdit } from "../utils/studioPendingEdits";
 
 export function observeGsapGesture(writer: CommitMutation | null) {
+  const edit = adoptingStudioPendingEdit();
+  const join = <T>(run: () => T): T => (edit ? edit.within(run) : run());
   let changed = false;
   let pendingResults = 0;
   const actions = new Set<KeyframeUsageAction>();
@@ -21,12 +24,14 @@ export function observeGsapGesture(writer: CommitMutation | null) {
     pendingResults += 1;
     return {
       ...options,
+      ...(edit && { pendingEdit: edit }),
       keyframeTelemetry: false,
       onResult: (result: MutationResult) => {
         pendingResults -= 1;
         options.onResult?.(result);
         if (!result.ok || result.changed !== true) return;
         changed = true;
+        edit?.markSaved();
         const members = changedMutationIndices(
           result,
           calls.length,
@@ -43,16 +48,18 @@ export function observeGsapGesture(writer: CommitMutation | null) {
   let commit: CommitMutation | null = null;
   if (writer) {
     commit = (selection, mutation, options) =>
-      writer(selection, mutation, observe([{ selection, mutation, options }], options));
+      join(() => writer(selection, mutation, observe([{ selection, mutation, options }], options)));
     if (writer.batch) {
       const batch = writer.batch;
-      commit.batch = (calls, options) => batch(calls, observe(calls, options));
+      commit.batch = (calls, options) => join(() => batch(calls, observe(calls, options)));
     }
   }
   return {
     commit,
+    drawKeepingUndone: <T>(draw: () => T): T => (edit ? edit.drawKeepingUndone(draw) : draw()),
     recordDomResult: (result: { changed: boolean } | undefined) => {
       changed ||= result?.changed === true;
+      if (result?.changed) edit?.markSaved();
     },
     finish: (domChanged = false): GeometryCommitResult => {
       if (pendingResults !== 0) return { ok: true, changed: false };

package/src/hooks/gsapParsedTween.ts

@@ -2,6 +2,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { elementTargets } from "../utils/elementGsap";
 import { resolveTweenStart } from "../utils/globalTimeCompiler";
 import type { ImplicitEndValue } from "./gsapValueAtPlayhead";
+import type { ReadTween } from "./gsapRuntimeKeyframes";
 
 // GSAP 3 internals: a property tween in a tween's `_pt` chain; CSSPlugin keeps its own under `d._pt`.
 interface PropTween {
@@ -57,6 +58,21 @@ function endsIn(tween: ParsedTween, prop: string): [number, number] | null {
   return tween._from ? [pair[1], pair[0]] : pair;
 }
 
+/** `read` plus GSAP's start for a step list or a first key past 0%, read per channel. */
+export function withParsedStart(read: ReadTween, live: unknown): ReadTween {
+  const tween = live as ParsedTween;
+  const first = read.keyframes[0];
+  if (!Array.isArray(tween.vars?.keyframes) && !((first?.percentage ?? 0) > 0)) return read;
+  const children = tween.timeline?.getChildren?.() ?? [tween];
+  const start: Record<string, number> = {};
+  for (const prop of ["x", "y", "width", "height"]) {
+    const ends = children.map((child) => endsIn(child, prop)).find(Boolean);
+    if (ends) start[prop] = ends[0];
+  }
+  const moved = Object.entries(start).some(([prop, value]) => value !== first?.properties[prop]);
+  return moved ? { ...read, start } : read;
+}
+
 /** The live tween GSAP built from `anim`: same element, start and channels, parsed. */
 // fallow-ignore-next-line complexity
 export function findParsedTween(

package/src/hooks/gsapResizeDropPoint.test.ts

@@ -75,6 +75,8 @@ interface ResizeCase {
   longhandTween?: boolean;
   /** What already writes this element's position. */
   positionWrite?: "static-set" | "keyframed-tween" | "none";
+  /** Undo paints the box back to its press look while the animations load. */
+  paintedBackWhileLoading?: boolean;
 }
 
 function createResizeElement(testCase: ResizeCase): HTMLElement {
@@ -241,6 +243,30 @@ async function runCase(testCase: ResizeCase) {
   } as unknown as HTMLIFrameElement;
 
   const dropPoint = el.getBoundingClientRect();
+  // A painted-back edit: undone on screen, shown again only inside a draw (as `drawKeepingUndone` does).
+  const look = () => ({
+    w: el.style.width,
+    h: el.style.height,
+    pos: { ...live.pos },
+    scale: { ...live.scale },
+  });
+  const show = (shown: ReturnType<typeof look>) => {
+    el.style.width = shown.w;
+    el.style.height = shown.h;
+    Object.assign(live, { pos: { ...shown.pos }, scale: { ...shown.scale } });
+  };
+  let shownEdit: ReturnType<typeof look> | null = null;
+  const paintBack = () => {
+    shownEdit = look();
+    show({ w: "", h: "", pos: { ...testCase.base }, scale: { ...testCase.liveScale } });
+  };
+  const draw = <T>(run: () => T): T => {
+    if (!shownEdit) return run();
+    show(shownEdit);
+    const drawn = run();
+    paintBack();
+    return drawn;
+  };
   const position = positionAnimation(testCase.positionWrite ?? "static-set", testCase.base);
   const animations = [scaleTween(!!testCase.longhandTween), ...(position ? [position] : [])];
   const commitMutation = vi.fn();
@@ -252,7 +278,12 @@ async function runCase(testCase: ResizeCase) {
     animations,
     iframe,
     commitMutation,
-    async () => animations,
+    async () => {
+      if (testCase.paintedBackWhileLoading) paintBack();
+      return animations;
+    },
+    undefined,
+    draw,
   );
 
   // Re-render what the file now says: the committed scale, the persisted
@@ -393,3 +424,10 @@ it("holds the drop point across a second drag", async () => {
   expect(second.settled.y).toBeCloseTo(second.dropPoint.y, 0);
   expect(second.settled.w).toBeCloseTo(second.dropPoint.w, 0);
 });
+
+it("lands on the drop point when undo paints the box back while its animations load", async () => {
+  const { dropPoint, settled } = await runCase({ ...CASES[0]!, paintedBackWhileLoading: true });
+  expect(settled.x).toBeCloseTo(dropPoint.x, 0);
+  expect(settled.y).toBeCloseTo(dropPoint.y, 0);
+  expect(settled.w).toBeCloseTo(dropPoint.w, 0);
+});

package/src/hooks/gsapResizeElementSize.test.tsx

@@ -5,6 +5,10 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { applyStudioBoxSizeDraft } from "../components/editor/manualEdits";
+import {
+  beginStudioPendingEdit,
+  paintBackNewestStudioPendingEdit,
+} from "../utils/studioPendingEdits";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useGsapAwareEditing } from "./useGsapAwareEditing";
@@ -134,4 +138,27 @@ describe("resizing an element GSAP positions", () => {
     expect(cssSize).toEqual([]);
     act(() => h.root.unmount());
   });
+
+  it("keeps a resize undo painted back drawn undone while its save lands, and draws it again on show again", async () => {
+    const h = mount([positionHold]);
+    const element = h.selection.element;
+    const edit = beginStudioPendingEdit(() => {
+      const shown = element.getAttribute("style");
+      element.setAttribute("style", "scale: none");
+      return () => element.setAttribute("style", shown ?? "");
+    });
+    const saved = edit.adopt(() => h.resize(h.selection, h.size, { x: -50, y: -33.5 }));
+    edit.settle(saved);
+    const shown = paintBackNewestStudioPendingEdit();
+
+    await act(() => saved);
+    expect(h.commitPatch.mock.calls.at(-1)![1]).toEqual(
+      expect.arrayContaining([{ type: "inline-style", property: "width", value: "340px" }]),
+    );
+    expect(element.getAttribute("style")).toBe("scale: none");
+
+    shown!.showAgain();
+    expect(element.getAttribute("style")).toContain("--hf-studio-width: 340px");
+    act(() => h.root.unmount());
+  });
 });

package/src/hooks/gsapResizeIntercept.ts

@@ -135,6 +135,7 @@ export async function tryGsapResizeIntercept(
   commitMutation: GsapDragCommitCallbacks["commitMutation"],
   fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
   dragOffset?: { x: number; y: number },
+  draw: <T>(run: () => T) => T = (run) => run(),
 ): Promise<GsapEditOutcome> {
   const fetchedAnimations = fetchFallbackAnimations ? await fetchFallbackAnimations() : [];
   const outcome = preflightGsapResizeIntercept(selection, animations, iframe, fetchedAnimations);
@@ -315,7 +316,7 @@ export async function tryGsapResizeIntercept(
     // difference and compensates, so release matches the drop pixel-for-pixel
     // regardless of live scale or repeat resizes.
     if (el) {
-      const dropRect = el.getBoundingClientRect();
+      const dropRect = draw(() => el.getBoundingClientRect());
       scaleDraftDropPoint = { x: dropRect.x, y: dropRect.y };
     }
   } else {
@@ -342,75 +343,61 @@ export async function tryGsapResizeIntercept(
     // resize took the size route and never moved anything: the drop point is
     // the drag's to settle, not ours.
     if (!scaleDraftEl) return false;
-    clearStudioBoxSize(scaleDraftEl);
-    if (!scaleDraftDropPoint || !selector) return false;
-    // Put the committed scale on the live element before measuring.
-    //
-    // This step reads where the commit lands the box and shifts the position
-    // hold by the difference. That only works if the commit has actually
-    // rendered, and whether it had was luck: on the FIRST resize of an element
-    // the timeline had not re-seeked yet, so this measured the element at its
-    // natural size, still sitting on the drop point, computed a residual of
-    // zero, and skipped the correction entirely. The scale then landed, GSAP
-    // rendered it around the element's centre, and the element jumped by the
-    // whole drag distance. Elements that had been resized before got a
-    // correction only because their PREVIOUS scale made the residual non-zero.
-    //
-    // Setting it here costs nothing when the commit has already rendered (same
-    // value) and makes the measurement below mean what it says either way.
-    if (committedScale) {
-      setElementGsapScale(scaleDraftEl, committedScale.x, committedScale.y);
-    }
-    // Measure from the pre-gesture position, not the draft one.
-    //
-    // The resize draft translates the element to keep the dragged corner under
-    // the cursor, but the scale route never persists that translation — the
-    // element renders back at its pre-gesture position as soon as the commit
-    // lands. Measuring while the draft translation was still applied made the
-    // residual carry the whole drag distance, and the position commit then
-    // composed that residual onto the pre-gesture base (it reads the gesture's
-    // own base attributes, not the live value), so the element landed a full
-    // drag away from the drop point on every scale resize.
-    const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
-    const { baseGsapX, baseGsapY } = computeDraggedGsapPosition(
-      selection.element,
-      { x: 0, y: 0 },
-      gsapPos,
-    );
-    const base = { x: baseGsapX, y: baseGsapY };
-    setElementGsapPosition(scaleDraftEl, base.x, base.y);
-    const post = scaleDraftEl.getBoundingClientRect();
-    const residual = { x: scaleDraftDropPoint.x - post.x, y: scaleDraftDropPoint.y - post.y };
-    if (!Number.isFinite(residual.x) || !Number.isFinite(residual.y)) return false;
-    if (Math.abs(residual.x) < 0.5 && Math.abs(residual.y) < 0.5) {
-      logResize("scale-finalize", { skipped: "already-on-drop-point", residual, base });
-      // Settled, with nothing to write. Still ours: forwarding the drag offset
-      // on top would move the box off the point it is already sitting on.
-      return true;
+    const draftEl = scaleDraftEl;
+    if (!scaleDraftDropPoint || !selector) {
+      draw(() => clearStudioBoxSize(draftEl));
+      return false;
     }
-    // The ONE corrected position — rounded once so the live runtime and the
-    // persisted file agree exactly (commitStaticGsapPosition composes the same
-    // rounded value from this delta).
-    const corrected = {
-      x: roundTo3(base.x + residual.x),
-      y: roundTo3(base.y + residual.y),
-    };
-    logResize("scale-finalize", {
-      dropPoint: scaleDraftDropPoint,
-      post: { x: post.x, y: post.y },
-      residual,
-      gsapPos,
-      base,
-      corrected,
+    const dropPoint = scaleDraftDropPoint;
+    const measured = draw(() => {
+      clearStudioBoxSize(draftEl);
+      // Draw the committed scale before measuring: on a first resize the timeline has not re-seeked yet,
+      // so the box would read at its natural size and the correction would be skipped.
+      if (committedScale) {
+        setElementGsapScale(draftEl, committedScale.x, committedScale.y);
+      }
+      // Measure from the pre-gesture position: the scale route never saves the draft's translation, and
+      // the position write composes the residual onto that same base.
+      const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
+      const { baseGsapX, baseGsapY } = computeDraggedGsapPosition(
+        selection.element,
+        { x: 0, y: 0 },
+        gsapPos,
+      );
+      const base = { x: baseGsapX, y: baseGsapY };
+      setElementGsapPosition(draftEl, base.x, base.y);
+      const post = draftEl.getBoundingClientRect();
+      const residual = { x: dropPoint.x - post.x, y: dropPoint.y - post.y };
+      if (!Number.isFinite(residual.x) || !Number.isFinite(residual.y)) return null;
+      if (Math.abs(residual.x) < 0.5 && Math.abs(residual.y) < 0.5) {
+        logResize("scale-finalize", { skipped: "already-on-drop-point", residual, base });
+        // Settled, with nothing to write. Still ours: forwarding the drag offset
+        // on top would move the box off the point it is already sitting on.
+        return "settled" as const;
+      }
+      // The ONE corrected position — rounded once so the live runtime and the
+      // persisted file agree exactly (commitStaticGsapPosition composes the same
+      // rounded value from this delta).
+      const corrected = {
+        x: roundTo3(base.x + residual.x),
+        y: roundTo3(base.y + residual.y),
+      };
+      logResize("scale-finalize", {
+        dropPoint,
+        post: { x: post.x, y: post.y },
+        residual,
+        gsapPos,
+        base,
+        corrected,
+      });
+      // Correct the live box in the same task as the measurement, so no frame shows it off the drop
+      // point while the position write is in flight.
+      setElementGsapPosition(draftEl, corrected.x, corrected.y);
+      return { base, corrected };
     });
-    // Correct the LIVE runtime NOW, synchronously: the soft reload above just
-    // rendered the committed scale around the element center — NOT at the drop
-    // point — and everything up to here runs in the same microtask chain as
-    // that reload, so no frame has painted the uncorrected position yet. The
-    // server persist below costs network round-trips; without this set, the
-    // element visibly sits at the wrong spot for those frames (the drop
-    // "jump"). The persisted commit re-applies the same values (idempotent).
-    setElementGsapPosition(scaleDraftEl, corrected.x, corrected.y);
+    if (measured === null) return false;
+    if (measured === "settled") return true;
+    const { base, corrected } = measured;
     // Re-fetch: the scale commit above just rewrote the script, so the caller's
     // animation list (and its ids) may be stale for the position lookup.
     const currentAnimations = fetchFallbackAnimations

package/src/hooks/gsapRuntimeKeyframes.realGsap.test.ts

@@ -0,0 +1,48 @@
+// @vitest-environment happy-dom
+import { gsap } from "gsap";
+import { expect, it } from "vitest";
+import { readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
+
+/** The edit bench's `keys` layer: GSAP starts it at x 40, 260 wide, and plays it to 1 s. */
+function read(keyframes: string) {
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  box.style.width = "260px";
+  gsap.set(box, { x: 40 });
+  const win = { __timelines: {} as Record<string, gsap.core.Timeline> };
+  new Function(
+    "gsap",
+    "window",
+    `var tl = gsap.timeline({ paused: true });
+tl.to("#x", { keyframes: ${keyframes} }, 0);
+window.__timelines["t"] = tl;`,
+  )(gsap, win);
+  const timeline = win.__timelines.t!;
+  timeline.progress(0.0001, true).seek(1);
+  const iframe = { contentWindow: { ...win, gsap }, contentDocument: document };
+  const got = readRuntimeKeyframes(iframe as unknown as HTMLIFrameElement, "#x");
+  timeline.kill();
+  box.remove();
+  return got;
+}
+
+it("reads where GSAP started a step list whose first keyframe comes later", () => {
+  const got = read(
+    `[{ x: 60, width: 280, duration: 2, ease: "none" }, { x: 120, width: 320, duration: 1, ease: "none" }]`,
+  );
+  expect(got?.start).toEqual({ x: 40, width: 260 });
+});
+
+it.each([
+  [`{ "50%": { x: 60, y: 20 }, "100%": { x: 120, y: 40 } }, duration: 2`, { x: 40, y: 0 }],
+  [
+    `{ "50%": { x: 60, width: 280 }, "100%": { x: 120, width: 320 } }, duration: 2`,
+    { x: 40, width: 260 },
+  ],
+])("reads every channel's start for a percentage list past 0%: %s", (keyframes, start) => {
+  expect(read(keyframes)?.start).toEqual(start);
+});
+
+it("reads no start for keyframes that begin at 0%, or a step list that begins where GSAP started", () => {
+  expect(read(`{ "0%": { x: 10 }, "100%": { x: 120 } }, duration: 3`)?.start).toBeUndefined();
+  expect(read(`[{ x: 40, duration: 0 }, { x: 120, duration: 1 }]`)?.start).toBeUndefined();
+});

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -11,6 +11,7 @@
 import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
 import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
+import { withParsedStart } from "./gsapParsedTween";
 import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
 import { gsapRendersTransform } from "../components/editor/gsapAnimatesProperty";
 
@@ -43,7 +44,13 @@ export interface RuntimeTimeline {
 }
 
 type Pct = { percentage: number; properties: Record<string, number | string> };
-export type ReadTween = { keyframes: Pct[]; easeEach?: string; arcPath?: ArcPathConfig };
+export type ReadTween = {
+  keyframes: Pct[];
+  easeEach?: string;
+  arcPath?: ArcPathConfig;
+  /** GSAP's start values when the first keyframe is after 0%. */
+  start?: Record<string, number>;
+};
 
 export interface RuntimeKeyframeEntry {
   keyframes: Pct[];
@@ -365,11 +372,11 @@ export function readRuntimeKeyframes(
       const read = readTween(tween.vars);
       if (!read) continue;
       if (requireChannels && !readCarriesChannel(read, requireChannels)) continue;
-      if (firstRead === null) firstRead = read;
+      if (firstRead === null) firstRead = withParsedStart(read, tween);
       // Prefer the tween whose [start, start+dur] contains the playhead.
       if (now != null) {
         const start = typeof tween.startTime === "function" ? tween.startTime() : 0;
-        if (now >= start - 1e-3 && now <= start + dur + 1e-3) return read;
+        if (now >= start - 1e-3 && now <= start + dur + 1e-3) return withParsedStart(read, tween);
       }
     }
   }