@hyperframes/studio 0.8.133 → 0.8.134

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/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");
       }

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -424,6 +424,7 @@ describe("useGsapAwareEditing anchored resize", () => {
       expect.any(Function),
       undefined,
       expect.any(Function),
+      expect.objectContaining({ frozen: true }),
     );
     act(() => h.root.unmount());
   });

package/src/hooks/useGsapAwareEditing.ts

@@ -16,7 +16,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { tryGsapDragIntercept, tryGsapRotationIntercept } from "./gsapRuntimeBridge";
 import { tryGsapResizeIntercept } from "./gsapResizeIntercept";
-import { computeDraggedGsapPosition } from "./draggedGsapPosition";
+import { computeDraggedGsapPosition, freezeDragStamp } from "./draggedGsapPosition";
 import { readGsapPositionFromIframe } from "./gsapPositionDetection";
 import { selectorFromSelection } from "./gsapShared";
 import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
@@ -209,6 +209,7 @@ export function useGsapAwareEditing({
       restore: () => void = () => undefined,
       route?: { plainTranslate: boolean },
     ) => {
+      const stamp = freezeDragStamp(selection.element);
       const writes = observeGsapGesture(gsapCommitMutation);
       if (route?.plainTranslate ?? editsPlainCss(selection.element, "resize")) {
         const result = await handleDomBoxSizeCommit(selection, next, offset, restore);
@@ -256,6 +257,7 @@ export function useGsapAwareEditing({
             previewIframeRef.current,
             commitMutation,
             makeFetchFallback(selection),
+            { stamp },
           );
           // Saved after the size, under its undo key, so the two are one step.
           await saveMove(dragOutcome, async () => {
@@ -279,7 +281,12 @@ export function useGsapAwareEditing({
               x: 0,
               y: 0,
             };
-            const { newX, newY } = computeDraggedGsapPosition(selection.element, offset, gsapPos);
+            const { newX, newY } = computeDraggedGsapPosition(
+              selection.element,
+              offset,
+              gsapPos,
+              stamp,
+            );
             logResize("sync-settle", { gsapPos, offset, newX, newY });
             setElementGsapPosition(selection.element, newX, newY);
           });
@@ -297,6 +304,7 @@ export function useGsapAwareEditing({
                 makeFetchFallback(selection),
                 offset,
                 writes.drawKeepingUndone,
+                stamp,
               );
               assertGsapEditPersisted(outcome);
               // Saved before the buffered GSAP writes, so their reload stays the gesture's last render.

package/src/utils/elementGsap.ts

@@ -8,7 +8,6 @@
 type ElementGsapWindow = Window & {
   gsap?: {
     set?: (target: Element, vars: Record<string, number>) => void;
-    getProperty?: (target: Element, prop: string) => unknown;
   };
 };
 
@@ -38,10 +37,12 @@ export function setElementGsapScale(element: HTMLElement, x: number, y: number):
   return true;
 }
 
-/** The element's GSAP numeric property, or null when unreadable. */
-export function readElementGsapNumber(element: HTMLElement, prop: string): number | null {
-  const value = Number(gsapOf(element)?.getProperty?.(element, prop));
-  return Number.isFinite(value) ? value : null;
+/** Set the element's GSAP width/height. Returns false when no runtime is reachable. */
+export function setElementGsapSize(element: HTMLElement, width: number, height: number): boolean {
+  const gsap = gsapOf(element);
+  if (!gsap?.set) return false;
+  gsap.set(element, { width, height });
+  return true;
 }
 
 /** The targets CSSPlugin styles: not plain objects (the runtime's filler) or XML-namespace elements. */

package/src/utils/gsapUndoRestore.test.ts

@@ -21,6 +21,7 @@ import {
 } from "./gsapUndoRestore";
 import { applyPatch } from "./sourcePatcher";
 import { beginStudioManualEditGesture } from "../components/editor/manualEdits";
+import { studioManualEditSavesIn } from "../components/editor/manualEditsDom";
 import { writePlainMove, writeTranslatePx } from "../components/editor/plainTranslate";
 
 // ── Bug 2: undo/redo restore soft-apply ──────────────────────────────────────
@@ -281,6 +282,16 @@ describe("applyUndoRestoreToPreview", () => {
     expect(doc.getElementById("a")!.getAttribute("style")).toBe("z-index: 8");
   });
 
+  it("counts a script-only restore applied in place, so a reload requested before it loads again", () => {
+    const script = (x: number) => `window.__timelines["root"]=gsap.timeline().to("#a",{x:${x}});`;
+    const page = (x: number) => `<div id="a">t</div><script>${script(x)}</script>`;
+    const { iframe, doc } = buildLiveIframe(page(2));
+    const before = studioManualEditSavesIn(doc);
+    const files = { [ROOT]: { previous: wrap(page(2)), restored: wrap(page(1)) } };
+    applyUndoRestoreToPreview(iframe, ROOT, files, 3, vi.fn());
+    expect(studioManualEditSavesIn(doc)).toBeGreaterThan(before);
+  });
+
   it("does NOT re-run an UNCHANGED GSAP script for an attribute-only restore", () => {
     // The live doc holds a script element; a re-run would mutate/remove it
     // (applySoftReload removes stale script elements before re-running).
@@ -563,6 +574,17 @@ describe("an undo that lands while the layer is being dragged", () => {
     expect(el.style.getPropertyValue("width")).toBe("100px");
   });
 
+  it("counts an undo shown or applied in place, so a reload requested before it loads again", () => {
+    const { iframe, doc } = buildLiveIframe(undone);
+    const before = studioManualEditSavesIn(doc);
+
+    showRestoreInPlace(iframe, ROOT, files, 3);
+    expect(studioManualEditSavesIn(doc)).toBeGreaterThan(before);
+    const shown = studioManualEditSavesIn(doc);
+    applyUndoRestoreToPreview(iframe, ROOT, files, 3, vi.fn());
+    expect(studioManualEditSavesIn(doc)).toBeGreaterThan(shown);
+  });
+
   it("keeps a drag that started after the undo was shown when the undo is put back", () => {
     const { iframe, doc } = buildLiveIframe(undone);
     const el = doc.getElementById("a")!;

package/src/utils/gsapUndoRestore.ts

@@ -14,7 +14,7 @@ import { findAuthoredElement, parseSavedSource } from "./authoredSource";
 import { STUDIO_EDIT_ATTRS } from "../components/editor/manualEditsSeekReapply";
 import { markScenesStale } from "../player/sceneSwap";
 import { STUDIO_ORIGINAL_INLINE_TRANSLATE_ATTR } from "../components/editor/manualEditsTypes";
-import { studioGestureDraws } from "../components/editor/manualEditsDom";
+import { countStudioPreviewChange, studioGestureDraws } from "../components/editor/manualEditsDom";
 
 type PreviewWindow = Window & {
   __player?: { seek?: (t: number) => void };
@@ -312,7 +312,8 @@ export function showRestoreInPlace(
   const doc = iframe?.contentDocument;
   const win = iframe?.contentWindow as PreviewWindow | null;
   const plan = doc && win ? planRestoreTargets(doc, activeCompPath ?? "index.html", files) : null;
-  if (!iframe || !win || !plan || plan.scripted) return null;
+  if (!iframe || !doc || !win || !plan || plan.scripted) return null;
+  countStudioPreviewChange(doc);
   const before = plan.targets.map(
     ({ live, restored }) => [live, live.cloneNode(false) as Element, restored] as const,
   );
@@ -393,6 +394,7 @@ export function applyUndoRestoreToPreview(
     reloadPreview();
     return "full";
   }
+  countStudioPreviewChange(doc);
   // Sync each changed element's attributes onto the live DOM from the restored
   // markup, so the runtime's seek-reapply reads the reverted values.
   for (const target of plan.targets)

package/src/utils/studioPendingEdits.ts

@@ -66,8 +66,18 @@ export function hasStudioPendingEdits(): boolean {
   return pendingEdits.size > 0 || focusedField() !== null;
 }
 
+const shownRestores = new Set<Promise<void>>();
+
+export function beginStudioShownRestore(): () => void {
+  let end = () => {};
+  const landed = new Promise<void>((resolve) => (end = resolve));
+  shownRestores.add(landed);
+  void landed.then(() => shownRestores.delete(landed));
+  return end;
+}
+
 export function isStudioEditSaving(): boolean {
-  return pendingEdits.size > 0;
+  return pendingEdits.size > 0 || shownRestores.size > 0;
 }
 
 export function afterStudioPendingEdits(run: () => void): () => void {
@@ -75,7 +85,7 @@ export function afterStudioPendingEdits(run: () => void): () => void {
   const check = () => {
     if (!waiting) return;
     if (isStudioEditSaving()) {
-      void Promise.allSettled([...pendingEdits.keys()]).then(check);
+      void Promise.allSettled([...pendingEdits.keys(), ...shownRestores]).then(check);
       return;
     }
     waiting = false;