@hyperframes/studio 0.8.133 → 0.8.135

package/src/hooks/gsapResizeIntercept.ts

@@ -5,14 +5,18 @@
  * frame can't jump. Split from gsapRuntimeBridge, which owns the shared
  * group-tween resolution used by the drag/resize/rotate intercepts.
  */
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { clearStudioBoxSize } from "../components/editor/manualEdits";
 import {
   STUDIO_ORIGINAL_BOX_HEIGHT_ATTR,
   STUDIO_ORIGINAL_BOX_WIDTH_ATTR,
 } from "../components/editor/manualEditsTypes";
-import { setElementGsapPosition, setElementGsapScale } from "../utils/elementGsap";
+import {
+  setElementGsapPosition,
+  setElementGsapScale,
+  setElementGsapSize,
+} from "../utils/elementGsap";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readGsapProperty } from "./gsapRuntimeReaders";
 import {
@@ -23,7 +27,11 @@ import {
   findSizeSetAnimation,
 } from "./gsapDragCommit";
 import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
-import { computeDraggedGsapPosition, restoreDragOffset } from "./draggedGsapPosition";
+import {
+  computeDraggedGsapPosition,
+  restoreDragOffset,
+  type DragStamp,
+} from "./draggedGsapPosition";
 import { pickClosestToPlayhead, readGsapPositionFromIframe } from "./gsapPositionDetection";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 import { commitGsapPositionFromDrag } from "./gsapDragPositionCommit";
@@ -39,9 +47,11 @@ import {
 } from "./gsapEditOutcome";
 import { commitValueAtPlayhead } from "./gsapValueAtPlayhead";
 import { preflightGsapResizeIntercept, resizeRoute } from "./gsapResizePreflight";
+import { singleKeyTweenMutation } from "./useEnableKeyframes";
 
 const SIZE_PROPS = new Set(["width", "height"]);
 const POSITION_XY = new Set(["x", "y"]);
+const MOVED_OR_SIZED = new Set(["x", "y", "xPercent", "yPercent", "width", "height"]);
 
 /**
  * The element's box before the resize draft ran, in CSS pixels.
@@ -88,6 +98,7 @@ export async function commitSizeAtPlayhead(
           selection.element,
           dragOffset,
           readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 },
+          callbacks.stamp,
         )
       : null;
   const written = await commitValueAtPlayhead(
@@ -102,12 +113,43 @@ export async function commitSizeAtPlayhead(
         ...preGestureBoxSize(selection.element),
         ...(anchor && { x: anchor.baseGsapX, y: anchor.baseGsapY }),
       },
-      ...(anchor && { beforeReload: () => restoreDragOffset(selection.element) }),
+      ...(anchor && { beforeReload: () => restoreDragOffset(selection.element, callbacks.stamp) }),
     },
   );
   return written.status === "persisted" && anchor ? { ...written, ownsDragOffset: true } : written;
 }
 
+/** A keyed size is GSAP's at every time; the gesture's draft, re-applied after each seek, would pin it there. */
+function handOverDraftSize(
+  selection: DomEditSelection,
+  written: GsapEditOutcome,
+  size: Record<string, number>,
+  draw: <T>(run: () => T) => T,
+): GsapEditOutcome {
+  const { width, height } = size;
+  if (written.status !== "persisted" || width == null || height == null) return written;
+  draw(() => {
+    clearStudioBoxSize(selection.element);
+    setElementGsapSize(selection.element, width, height);
+  });
+  return written;
+}
+
+/** Under auto-record, a keyframed element's first resize is a size key at the playhead, held at all times. */
+function firstSizeKey(
+  selection: DomEditSelection,
+  size: { width: number; height: number },
+  resizeGroup: PropertyGroupName,
+  animations: GsapAnimation[],
+): Record<string, unknown> | null {
+  const { autoKeyframeEnabled, currentTime } = usePlayerStore.getState();
+  const keyframed = animations.some(
+    (a) => a.keyframes && animationWritesAnyProperty(a, MOVED_OR_SIZED),
+  );
+  if (resizeGroup !== "size" || !autoKeyframeEnabled || !keyframed) return null;
+  return singleKeyTweenMutation(selection, size, currentTime);
+}
+
 /**
  * Whether this tween already states scale as `scaleX`/`scaleY`.
  *
@@ -136,6 +178,7 @@ export async function tryGsapResizeIntercept(
   fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
   dragOffset?: { x: number; y: number },
   draw: <T>(run: () => T) => T = (run) => run(),
+  stamp?: DragStamp,
 ): Promise<GsapEditOutcome> {
   const fetchedAnimations = fetchFallbackAnimations ? await fetchFallbackAnimations() : [];
   const outcome = preflightGsapResizeIntercept(selection, animations, iframe, fetchedAnimations);
@@ -170,10 +213,16 @@ export async function tryGsapResizeIntercept(
     size,
   });
   if (!anim || isInstantHold(anim)) {
+    const sized = { width: roundToLayoutPx(size.width), height: roundToLayoutPx(size.height) };
     const scriptWritesSize = allKnownAnimations.some((a) =>
       animationWritesAnyProperty(a, SIZE_PROPS),
     );
-    if (!scriptWritesSize) return { status: "element-size" };
+    if (!scriptWritesSize) {
+      const firstKey = firstSizeKey(selection, sized, resizeGroup, workingAnimations);
+      if (!firstKey) return { status: "element-size" };
+      await commitMutation(selection, firstKey, { label: "Resize", softReload: true });
+      return handOverDraftSize(selection, { status: "persisted" }, sized, draw);
+    }
     const sel = selectorFromSelection(selection) ?? writeTargetSelector(selection);
     if (!sel) return { status: "blocked", reason: "no-selector" };
     // A scale hold is not a size hold.
@@ -191,8 +240,7 @@ export async function tryGsapResizeIntercept(
         ? (anim ?? findSizeSetAnimation(workingAnimations, sel, selection.element))
         : findSizeSetAnimation(workingAnimations, sel, selection.element);
 
-    // Keyframe the size only when a real tween already animates it, as move and
-    // rotate do; a fade or a slide on the element gets a plain size.
+    // Keyframe the size when a real tween already animates it; a static size set stays a set.
     if (resizeGroup === "size") {
       const animatedTween = pickClosestToPlayhead(
         workingAnimations.filter(
@@ -204,11 +252,19 @@ export async function tryGsapResizeIntercept(
       );
       if (animatedTween) {
         logResize("intercept-route", { route: "keyframed-size", tweenId: animatedTween.id });
-        const sized = { width: roundToLayoutPx(size.width), height: roundToLayoutPx(size.height) };
-        return commitSizeAtPlayhead(selection, animatedTween, sized, iframe, dragOffset, {
-          commitMutation,
-          fetchAnimations: fetchFallbackAnimations,
-        });
+        const written = await commitSizeAtPlayhead(
+          selection,
+          animatedTween,
+          sized,
+          iframe,
+          dragOffset,
+          {
+            commitMutation,
+            fetchAnimations: fetchFallbackAnimations,
+            stamp,
+          },
+        );
+        return handOverDraftSize(selection, written, sized, draw);
       }
     }
 
@@ -333,8 +389,7 @@ export async function tryGsapResizeIntercept(
   // it lands back on the drop point. The compensation only applies to a STATIC
   // position (a `tl.set` hold or none) — a keyframed position path has no
   // single anchor to preserve, so it keeps the plain center-scale behavior.
-  // The size route commits the same width/height channels the draft wrote, so
-  // it needs none of this.
+  // The size route hands its draft to GSAP itself (handOverDraftSize).
   // ponytail: for a 3D-rotated element the rects are AABBs, so the anchor is
   // approximate rather than corner-exact.
   // fallow-ignore-next-line complexity
@@ -363,6 +418,7 @@ export async function tryGsapResizeIntercept(
         selection.element,
         { x: 0, y: 0 },
         gsapPos,
+        stamp,
       );
       const base = { x: baseGsapX, y: baseGsapY };
       setElementGsapPosition(draftEl, base.x, base.y);
@@ -424,6 +480,7 @@ export async function tryGsapResizeIntercept(
         await commitGsapPositionFromDrag(selection, positionTween, delta, base, iframe, {
           commitMutation,
           fetchAnimations: fetchFallbackAnimations,
+          stamp,
         }),
       );
       return true;
@@ -432,6 +489,7 @@ export async function tryGsapResizeIntercept(
     await commitStaticGsapPosition(selection, delta, base, selector, existingSet, {
       commitMutation,
       fetchAnimations: fetchFallbackAnimations,
+      stamp,
     });
     return true;
   };
@@ -453,9 +511,18 @@ export async function tryGsapResizeIntercept(
     return { status: "persisted", ownsDragOffset: await finalizeScaleResizeCommit() };
   }
 
-  const callbacks = { commitMutation, fetchAnimations: fetchFallbackAnimations };
-  if (resizeGroup === "size")
-    return commitSizeAtPlayhead(selection, anim, resizeProps, iframe, dragOffset, callbacks);
+  const callbacks = { commitMutation, fetchAnimations: fetchFallbackAnimations, stamp };
+  if (resizeGroup === "size") {
+    const written = await commitSizeAtPlayhead(
+      selection,
+      anim,
+      resizeProps,
+      iframe,
+      dragOffset,
+      callbacks,
+    );
+    return handOverDraftSize(selection, written, resizeProps, draw);
+  }
   const written = await commitValueAtPlayhead(selection, anim, resizeProps, iframe, callbacks, {
     label: "Resize",
     backfill: resizeBackfill,

package/src/hooks/gsapRuntimeBridge.ts

@@ -31,6 +31,7 @@ import { tweenReach, tweensForThisElement } from "./gsapTweenReach";
 import { resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
 import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
+import type { DragStamp } from "./draggedGsapPosition";
 import { isInstantHold, selectorFromSelection, writeTargetSelector } from "./gsapShared";
 import {
   findGsapPositionAnimation,
@@ -243,6 +244,7 @@ export async function tryGsapDragIntercept(
     preflightOnly?: boolean;
     preflightPassed?: boolean;
     group?: boolean;
+    stamp?: DragStamp;
   },
 ): Promise<GsapEditOutcome> {
   if (!options?.preflightPassed) {
@@ -323,6 +325,7 @@ export async function tryGsapDragIntercept(
     await commitStaticGsapPosition(selection, offset, gsapPos, selector, existingSet, {
       commitMutation,
       fetchAnimations: fetchFallbackAnimations,
+      stamp: options?.stamp,
     });
     return { status: "persisted" };
   }
@@ -352,7 +355,7 @@ export async function tryGsapDragIntercept(
     }
   }
 
-  const cbs = { commitMutation, fetchAnimations: fetchFallbackAnimations };
+  const cbs = { commitMutation, fetchAnimations: fetchFallbackAnimations, stamp: options?.stamp };
   if (route === "whole-path") {
     await commitWholePathOffset(selection, posAnim, offset, gsapPos, iframe, selector, cbs);
   } else {

package/src/hooks/gsapRuntimePatch.ts

@@ -19,6 +19,7 @@ import {
   type RuntimeTween,
   type RuntimeTimeline,
 } from "./gsapRuntimeKeyframes";
+import { recordLiveSet } from "../utils/softReloadTargets";
 
 /** Value-only channels a `tl.set(...)` patch may touch. */
 export interface SetPatchProps {
@@ -34,6 +35,8 @@ export interface SetPatchProps {
   scaleY?: number;
   scale?: number;
   opacity?: number;
+  width?: number;
+  height?: number;
 }
 
 /** A single keyframe step's numeric channels (the GSAP array-keyframe form). */
@@ -101,6 +104,7 @@ function applyGlobalSet(
     const numeric = finiteNumericProps(props);
     if (!gsapLib?.set || !el || !numeric) return false;
     gsapLib.set(el, numeric);
+    recordLiveSet(el, numeric);
     return true;
   } catch {
     return false;

package/src/hooks/gsapShared.test.ts

@@ -4,6 +4,7 @@ import {
   idFromSelector,
   idSelector,
   isInstantHold,
+  keyframeEases,
   parsePercentageKeyframes,
   resolveClipTimingBasis,
   playsNear,
@@ -11,6 +12,16 @@ import {
   toClipPercentage,
 } from "./gsapShared";
 
+describe("keyframeEases", () => {
+  it("carries the keyframes' own ease into the tween ease, which GSAP plays the same", () => {
+    const anim = {
+      ease: "back.out",
+      keyframes: { keyframes: [], ease: "sine.inOut", easeEach: "power2.out" },
+    } as unknown as GsapAnimation;
+    expect(keyframeEases(anim)).toEqual({ ease: "sine.inOut", easeEach: "power2.out" });
+  });
+});
+
 describe("isInstantHold", () => {
   const animation = (method: GsapAnimation["method"], duration?: number) =>
     ({ method, duration }) as unknown as GsapAnimation;

package/src/hooks/gsapShared.ts

@@ -41,7 +41,7 @@ export const PROPERTY_DEFAULTS: Record<string, number> = {
  *  since GSAP eases each percentage segment power1.inOut whatever the tween-level ease says. */
 export function keyframeEases(anim: GsapAnimation): { ease?: string; easeEach?: string } {
   if (!anim.keyframes) return { easeEach: anim.ease };
-  return { ease: anim.ease, easeEach: anim.keyframes.easeEach };
+  return { ease: runEaseOf(anim), easeEach: anim.keyframes.easeEach };
 }
 
 /**

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

@@ -0,0 +1,44 @@
+import { trimTrailingKeyframeSpans } from "@hyperframes/parsers/gsap-writer-acorn";
+import { gsap } from "gsap";
+import { describe, expect, it } from "vitest";
+
+const timeline = `const tl = gsap.timeline({ paused: true });\n`;
+
+// What Studio saved for a plain element keyed at 1, 2 and 3 s, and for its size keyed at 3 s then 2 s.
+const saved = {
+  position:
+    `tl.set("#target", { x: 299.893, data: "hf-hold" }, 0);\n` +
+    `tl.to("#target", { keyframes: { "0%": { x: 299.893 }, "33.333%": { x: 297.086 }, "66.667%": { x: 47.754 } }, duration: 3 }, 1);`,
+  size:
+    `tl.set("#target", { width: 440, data: "hf-hold" }, 0);\n` +
+    `tl.to("#target", { keyframes: { "0%": { width: 440 }, "50%": { width: 340, ease: "none" } }, duration: 2 }, 2);`,
+};
+
+function valueAt(script: string, prop: "x" | "width", seeks: number[]) {
+  const target: Record<string, number> = { x: 0, width: 240 };
+  const run = new Function(
+    "gsap",
+    "target",
+    `${script.replaceAll('"#target"', "target")}\nreturn tl;`,
+  );
+  const tl = run(gsap, target) as gsap.core.Timeline;
+  for (const time of seeks) tl.seek(time);
+  return target[prop];
+}
+
+describe.each([
+  ["position", "x", 47.754],
+  ["size", "width", 340],
+] as const)("a %s tween Studio keyed short of its end", (name, prop, atThree) => {
+  it("plays and seeks to the same value once its tail is trimmed", () => {
+    const script = trimTrailingKeyframeSpans(timeline, timeline + saved[name]);
+    expect(valueAt(script, prop, [3])).toBeCloseTo(atThree, 3);
+    expect(valueAt(script, prop, [1, 2, 3])).toBeCloseTo(atThree, 3);
+  });
+
+  it("is what GSAP 3.15 gets wrong on a direct seek without the trim", () => {
+    const script = timeline + saved[name];
+    expect(valueAt(script, prop, [1, 2, 3])).toBeCloseTo(atThree, 3);
+    expect(valueAt(script, prop, [3])).not.toBeCloseTo(atThree, 0);
+  });
+});

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

@@ -0,0 +1,37 @@
+// Real gsap: the ease the parser reports for keyframes must be the one GSAP plays.
+import { parseGsapScriptAcorn } from "@hyperframes/core/gsap-parser-acorn";
+import { gsap } from "gsap";
+import { describe, expect, it } from "vitest";
+
+const STEPS = { "0%": { x: 0 }, "100%": { x: 10 } };
+
+function xAt(vars: gsap.TweenVars, time = 0.3): number {
+  const target = { x: 0 };
+  gsap
+    .timeline({ paused: true })
+    .to(target, { duration: 1, ...vars }, 0)
+    .seek(time);
+  return target.x;
+}
+
+const parsedEaseEach = (vars: string) =>
+  parseGsapScriptAcorn(`const tl = gsap.timeline({ paused: true });
+tl.to("#a", { duration: 1, ${vars} }, 0);`).animations[0]!.keyframes?.easeEach;
+
+describe("the keyframes ease the parser reports", () => {
+  it("is not a tween-level easeEach, which GSAP ignores", () => {
+    expect(xAt({ keyframes: STEPS, easeEach: "power4.in" })).toBe(xAt({ keyframes: STEPS }));
+    expect(
+      parsedEaseEach('keyframes: { "0%": { x: 0 }, "100%": { x: 10 } }, easeEach: "power4.in"'),
+    ).toBeUndefined();
+  });
+
+  it("is an easeEach inside the keyframes, which GSAP plays", () => {
+    expect(xAt({ keyframes: { ...STEPS, easeEach: "power4.in" } })).not.toBe(
+      xAt({ keyframes: STEPS }),
+    );
+    expect(
+      parsedEaseEach('keyframes: { "0%": { x: 0 }, "100%": { x: 10 }, easeEach: "power4.in" }'),
+    ).toBe("power4.in");
+  });
+});

package/src/hooks/useAnimatedPropertyCommit.test.tsx

@@ -10,6 +10,7 @@ import { mountReactHarness, withInlineLayoutBox } from "./domSelectionTestHarnes
 import { writeSizeWithCrop } from "../components/editor/cropResize";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { trackKeyframeCommit } from "../utils/keyframeUsage";
+import { xAtTime } from "./gsapPlaybackTestHarness";
 import type { CommitMutationOptions, CommitMutation } from "./gsapScriptCommitTypes";
 
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
@@ -205,6 +206,38 @@ function renderCommitHook(
 // canvas nudge exercises (not the raw drag intercept) — with auto-keyframe
 // off, it must shift the whole tween instead of adding/updating a keyframe
 // at the playhead.
+describe("useAnimatedPropertyCommit — extending a keyframed tween to the playhead", () => {
+  it("keeps the tween's eases and each keyframe's own ease", async () => {
+    usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 3, activeKeyframePct: null });
+    const eased = {
+      ...keyframedAnim,
+      ease: "power2.inOut",
+      keyframes: {
+        easeEach: "power2.out",
+        keyframes: [
+          { percentage: 0, properties: { x: 0, y: 0 }, ease: "expo.in" },
+          { percentage: 100, properties: { x: 100, y: 0 } },
+        ],
+      },
+    } as unknown as GsapAnimation;
+    const mutations: Array<Record<string, unknown>> = [];
+    let commit!: Commit;
+    const root = renderHookWith(
+      [eased],
+      (mutation) => mutations.push(mutation),
+      (ready) => (commit = ready),
+    );
+    await act(async () => commit(selection, { x: 50 }));
+    act(() => root.unmount());
+
+    const replace = mutations.find((m) => m.type === "replace-with-keyframes")!;
+    expect(replace).toMatchObject({ ease: "power2.inOut", easeEach: "power2.out" });
+    expect((replace.keyframes as Array<{ ease?: string }>)[0]!.ease).toBe("expo.in");
+    // The old end keyframe still plays at 2 s once the tween runs to the playhead at 3 s.
+    expect(xAtTime(replace as unknown as Parameters<typeof xAtTime>[0], 2)).toBeCloseTo(100, 0);
+  });
+});
+
 describe("useAnimatedPropertyCommit — autoKeyframeEnabled toggle (#1808)", () => {
   async function runCommitWithAutoKeyframe(enabled: boolean) {
     usePlayerStore.setState({ autoKeyframeEnabled: enabled, currentTime: 0 });

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -18,6 +18,7 @@ import {
   selectorFromSelection,
   computeElementPercentage,
   isInstantHold,
+  keyframeEases,
   writeTargetSelector,
   tweenTargetsElement,
 } from "./gsapShared";
@@ -375,7 +376,7 @@ async function commitKeyframeProps(
       for (const k of Object.keys(properties)) {
         if (!(k in p) && backfillDefaults[k] != null) p[k] = backfillDefaults[k];
       }
-      return { percentage: newPct, properties: p };
+      return { percentage: newPct, properties: p, ...(kf.ease ? { ease: kf.ease } : {}) };
     });
     remapped.push({ percentage: toNewPct(ct), properties });
     remapped.sort((a, b) => a.percentage - b.percentage);
@@ -388,6 +389,7 @@ async function commitKeyframeProps(
         position: roundTo3(newStart),
         duration: roundTo3(newDuration),
         keyframes: remapped,
+        ...keyframeEases(anim),
       },
       { label: `Edit ${primaryProp} (extended keyframe)`, keyframeAction: "add", softReload: true },
     );

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -376,6 +376,27 @@ describe("Reset after a plain move puts the author's translate back", () => {
   });
 });
 
+describe("useDomGeometryCommits undo steps", () => {
+  it("never merges a resize with the next size edit of the same element", async () => {
+    const element = document.createElement("div");
+    element.id = "box";
+    document.body.append(element);
+    const selection = { id: "box", selector: "#box", element } as unknown as DomEditSelection;
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
+
+    await commits().handleDomBoxSizeCommit(selection, { width: 418, height: 200 });
+    await commits().handleDomBoxSizeCommit(selection, { width: 280, height: 200 });
+
+    const [resize, field] = commitPositionPatchToHtml.mock.calls.map(([, , options]) => options);
+    expect(resize!.coalesceKey).not.toBe(field!.coalesceKey);
+    unmount();
+    element.remove();
+  });
+});
+
 describe("useDomGeometryCommits resize of a cropped element", () => {
   it("saves the crop scaled per axis with the box in the resize's own commit", async () => {
     const element = withInlineLayoutBox(document.createElement("div"));

package/src/hooks/useDomGeometryCommits.ts

@@ -26,6 +26,8 @@ import {
 } from "../components/editor/manualEditsDomPatches";
 import type { PatchOperation } from "../utils/sourcePatcher";
 
+let boxSizeCommitCounter = 0;
+
 // ── Hook ──
 
 export interface UseDomGeometryCommitsParams {
@@ -90,7 +92,10 @@ export function useDomGeometryCommits({
         label: "Resize layer box",
         ...(undoKey
           ? { coalesceKey: undoKey, coalesceMs: Number.POSITIVE_INFINITY, deferRender: true }
-          : { coalesceKey: `box-size:${getDomEditTargetKey(selection)}` }),
+          : {
+              coalesceKey: `box-size:${++boxSizeCommitCounter}`,
+              coalesceMs: Number.POSITIVE_INFINITY,
+            }),
       }).catch((error) => {
         restoreStudioBoxSize(element, beforeSize);
         if (offset) restoreStudioPathOffset(element, beforeOffset);

package/src/hooks/useEditHistoryActions.test.tsx

@@ -7,6 +7,7 @@ import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import { useEditHistoryActions, type EditHistoryHandle } from "./useEditHistoryActions";
 import {
   beginStudioPendingEdit,
+  isStudioEditSaving,
   setStudioPendingEditClaimClock,
   trackStudioPendingEdit,
 } from "../utils/studioPendingEdits";
@@ -97,6 +98,25 @@ describe("useEditHistoryActions", () => {
     });
   });
 
+  it("counts a shown step as saving until the server takes it, so a preview reload waits for its write", async () => {
+    const { deps, actions } = mount(
+      { ok: true, label: "Undid: Move", paths: ["index.html"], undoes: "e1", files: SERVER_FILES },
+      PREDICTED,
+    );
+    let step!: () => void;
+    const stepped = new Promise<void>((resolve) => (step = resolve));
+    const undo = deps.editHistory.undo.getMockImplementation()!;
+    deps.editHistory.undo.mockImplementation(async (cb) => (await stepped, undo(cb)));
+
+    const undone = actions.undo();
+    expect(deps.showHistoryRestoreNow).toHaveBeenCalledWith(PREDICTED.files);
+    expect(isStudioEditSaving()).toBe(true);
+    step();
+    await act(() => undone);
+    await Promise.resolve();
+    expect(isStudioEditSaving()).toBe(false);
+  });
+
   it("puts a shown step back and applies the server's own restore when it stepped another entry", async () => {
     const { deps, actions } = mount(
       {

package/src/hooks/useEditHistoryActions.ts

@@ -4,6 +4,7 @@ import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
 import type { RestoreFiles } from "../utils/gsapUndoRestore";
 import {
+  beginStudioShownRestore,
   hasStudioPendingEdits,
   paintBackNewestStudioPendingEdit,
 } from "../utils/studioPendingEdits";
@@ -82,6 +83,7 @@ export function useEditHistoryActions({
       const pendingEditShown = direction === "undo" ? paintBackNewestStudioPendingEdit() : null;
       const predicted = pendingEditShown ? null : (editHistory.predict?.(direction) ?? null);
       const predictedShown = predicted ? (showHistoryRestoreNow?.(predicted.files) ?? null) : null;
+      const shownLanded = predictedShown ? beginStudioShownRestore() : null;
       const putBack = predictedShown ?? pendingEditShown?.showAgain;
       const claimedAfter =
         pendingEditShown?.claimsAtBegin ??
@@ -107,6 +109,7 @@ export function useEditHistoryActions({
           : stepped && editClaimed;
       } finally {
         if (putBack && !serverSteppedShown && !revertIsTheUndo) putBack();
+        shownLanded?.();
       }
       if (!result.ok && result.reason === "content-mismatch") {
         showToast(

package/src/hooks/useEnableKeyframes.ts

@@ -31,6 +31,7 @@ import {
 import { POSITION_PROPS } from "./gsapRuntimeReaders";
 import { findParsedTween, withLiveTiming } from "./gsapParsedTween";
 import { roundTo3 } from "../utils/rounding";
+import { readTranslatePxLeavingPercent } from "../components/editor/plainTranslate";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
 import {
   buildExtendedKeyframes,
@@ -180,6 +181,32 @@ export function resolveNewTweenRange(
   return { start: clampedStart, duration: Math.max(0.5, roundTo3(end - clampedStart)) };
 }
 
+export function singleKeyTweenMutation(
+  sel: DomEditSelection,
+  properties: Record<string, number>,
+  currentTime: number,
+): Record<string, unknown> | null {
+  // A brand-new tween: author it against the one element the user selected.
+  // The bare class selectorFromSelection hands back for an id-less element
+  // animates every sibling sharing the class (see writeTargetSelector).
+  const targetSelector = writeTargetSelector(sel);
+  if (!targetSelector) return null;
+  const { start, duration } = resolveNewTweenRange(
+    sel.dataAttributes?.start,
+    sel.dataAttributes?.duration,
+    currentTime,
+  );
+  // One keyframe at the playhead, a single diamond capturing the current value;
+  // motion comes from the keyframes the user adds or drags later.
+  return {
+    type: "add-with-keyframes",
+    targetSelector,
+    position: roundTo3(start),
+    duration: roundTo3(duration),
+    keyframes: [{ percentage: 0, properties }],
+  };
+}
+
 // Authoritative parse of the current source for `sel`. Returns `null` when the
 // fetch can't run (no projectId / request failed) so callers can distinguish
 // "unavailable" from a genuine empty result (e.g. after a delete-all). An empty
@@ -514,43 +541,11 @@ export function useEnableKeyframes(
       }
     } else {
       const position = readElementPosition(iframe, sel, null);
-      const { start: elStart, duration: elDuration } = resolveNewTweenRange(
-        sel.dataAttributes?.start,
-        sel.dataAttributes?.duration,
-        t,
-      );
-      // A brand-new tween: author it against the one element the user selected.
-      // The bare class selectorFromSelection hands back for an id-less element
-      // animates every sibling sharing the class (see writeTargetSelector).
-      const selector = writeTargetSelector(sel);
-
-      if (!selector) {
-        session.handleGsapAddAnimation("to");
-        return;
-      }
-
-      if (Object.keys(position).length === 0) {
-        position.x = 0;
-        position.y = 0;
-      }
-
-      // One keyframe at the playhead — a single diamond capturing the current
-      // value. Motion comes from the user adding/dragging more keyframes later;
-      // creating 0%+100% up front showed two diamonds for a single "add keyframe".
-      const keyframes: Array<{ percentage: number; properties: Record<string, number | string> }> =
-        [{ percentage: 0, properties: { ...position } }];
-
-      if (session.commitMutation) {
-        await session.commitMutation(
-          {
-            type: "add-with-keyframes",
-            targetSelector: selector,
-            position: roundTo3(elStart),
-            duration: roundTo3(elDuration),
-            keyframes,
-          },
-          { label: "Enable keyframes", softReload: true },
-        );
+      if (Object.keys(position).length === 0)
+        Object.assign(position, readTranslatePxLeavingPercent(sel.element));
+      const mutation = singleKeyTweenMutation(sel, position, t);
+      if (mutation && session.commitMutation) {
+        await session.commitMutation(mutation, { label: "Enable keyframes", softReload: true });
       } else {
         session.handleGsapAddAnimation("to");
       }