@hyperframes/studio 0.8.126 → 0.8.128

package/src/hooks/useEnableKeyframes.test.ts

@@ -7,13 +7,13 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
   applyArcKeyframeAtPlayhead,
   animatedProps,
-  buildExtendedKeyframes,
   isPlayheadWithinTween,
   promoteSetToKeyframes,
   resolveNewTweenRange,
   useEnableKeyframes,
   type EnableKeyframesSession,
 } from "./useEnableKeyframes";
+import { buildExtendedKeyframes } from "./gsapDragPositionCommit";
 import { usePlayerStore } from "../player/store/playerStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -109,17 +109,11 @@ describe("isPlayheadWithinTween", () => {
     expect(isPlayheadWithinTween(anim({ position: "+=1" }), 99)).toBe(true);
   });
 
-  // The toolbar's "extends animation" tooltip has to agree with what the edit
-  // paths do. Those span a duration-less tween across its clip, so answering
-  // from GSAP's 0.5s default reported the playhead outside a window the click
-  // then treated as clip-wide.
-  it("spans the clip for a duration-less tween when given the selection", () => {
+  it("uses the window GSAP plays a duration-less tween in, not its clip", () => {
     const durationless = anim({ position: 0 });
-    const selection = { dataAttributes: { duration: "16" } } as unknown as DomEditSelection;
 
+    expect(isPlayheadWithinTween(durationless, 0.4)).toBe(true);
     expect(isPlayheadWithinTween(durationless, 5)).toBe(false);
-    expect(isPlayheadWithinTween(durationless, 5, selection)).toBe(true);
-    expect(isPlayheadWithinTween(durationless, 20, selection)).toBe(false);
   });
 });
 
@@ -238,6 +232,7 @@ describe("applyArcKeyframeAtPlayhead", () => {
     id: "#el-to-0-position",
     position: 0,
     duration: 10,
+    ease: "none",
     keyframes: {
       format: "object-array",
       keyframes: [
@@ -318,8 +313,8 @@ describe("applyArcKeyframeAtPlayhead", () => {
     );
   });
 
-  it("uses the owning clip duration when an arc omits its outer duration", async () => {
-    const fixture = arcFixture(25, 25);
+  it("extends a duration-less arc to a later playhead, keeping the other nodes' times", async () => {
+    const fixture = arcFixture(100, 0);
     const durationlessArc = { ...arcAnim, duration: undefined };
 
     await applyArcKeyframeAtPlayhead(
@@ -330,12 +325,22 @@ describe("applyArcKeyframeAtPlayhead", () => {
       fixture.iframe,
     );
 
+    // GSAP plays it 0-0.5 s, so the nodes stay at 0, 0.25 and 0.5 s.
     expect(fixture.commitMutation).toHaveBeenCalledWith(
-      expect.objectContaining({
+      {
         type: "replace-with-keyframes",
-        duration: 10,
-        keyframes: expect.arrayContaining([{ percentage: 25, properties: { x: 25, y: 25 } }]),
-      }),
+        animationId: arcAnim.id,
+        targetSelector: "#el",
+        position: 0,
+        duration: 2.5,
+        keyframes: [
+          { percentage: 0, properties: { x: 0, y: 0 } },
+          { percentage: 10, properties: { x: 50, y: 50 } },
+          { percentage: 20, properties: { x: 100, y: 0 } },
+          { percentage: 100, properties: { x: 100, y: 0 } },
+        ],
+        ease: "none",
+      },
       { label: "Add keyframe", softReload: true, keyframeAction: "add" },
     );
   });

package/src/hooks/useEnableKeyframes.ts

@@ -8,7 +8,7 @@
  * Reads GSAP runtime values only (no CSS offset — it applies separately via translate).
  */
 import { useCallback } from "react";
-import type { GsapAnimation, GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
@@ -18,19 +18,25 @@ import {
   keyframeEases,
   KEYFRAME_PCT_MATCH,
   isInstantHold,
-  resolveEditableTweenDuration,
+  playsNear,
   writeTargetSelector,
 } from "./gsapShared";
 import {
   absoluteToPercentage,
+  absoluteToPercentageForAnimation,
   resolveTweenStart,
   resolveTweenDuration,
   isTimeWithinTween,
 } from "../utils/globalTimeCompiler";
 import { POSITION_PROPS } from "./gsapRuntimeReaders";
+import { findParsedTween, withLiveTiming } from "./gsapParsedTween";
 import { roundTo3 } from "../utils/rounding";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
-import { buildTemporalArcKeyframes } from "./gsapDragPositionCommit";
+import {
+  buildExtendedKeyframes,
+  buildTemporalArcKeyframes,
+  linearArcKeyframes,
+} from "./gsapDragPositionCommit";
 
 let enableKeyframesTransactionCounter = 0;
 
@@ -80,58 +86,11 @@ export function animatedProps(anim: GsapAnimation | null): string[] {
  * Whether the playhead sits inside an animation's tween range. When the tween's
  * start can't be resolved we don't block (the percentage falls back to clip range,
  * preserving prior behavior for elements without explicit timing).
- *
- * Pass the selection whenever the caller has one: a duration-less tween spans
- * its clip, and answering from GSAP's 0.5s default reports the playhead outside
- * a window the edit paths treat as clip-wide.
  */
-export function isPlayheadWithinTween(
-  anim: GsapAnimation,
-  currentTime: number,
-  selection?: DomEditSelection | null,
-): boolean {
+export function isPlayheadWithinTween(anim: GsapAnimation, currentTime: number): boolean {
   const start = resolveTweenStart(anim);
   if (start === null) return true;
-  const duration = selection
-    ? resolveEditableTweenDuration(anim, selection)
-    : resolveTweenDuration(anim);
-  return isTimeWithinTween(currentTime, start, duration);
-}
-
-/**
- * Grow a keyframe tween's range to reach a playhead that sits outside it, and add a
- * keyframe there. Existing keyframes keep their *absolute* timing (percentages
- * rescale into the new range), so the current motion is preserved — the playhead
- * just becomes a new hold at the start or end. Used when "add keyframe at playhead"
- * fires beyond the tween instead of disabling the action.
- */
-export function buildExtendedKeyframes(
-  anim: GsapAnimation,
-  currentTime: number,
-  position: Record<string, number>,
-  sourceDuration = resolveTweenDuration(anim),
-): { position: number; duration: number; keyframes: GsapPercentageKeyframe[] } {
-  const oldStart = resolveTweenStart(anim) ?? 0;
-  const oldDuration = sourceDuration;
-  const newStart = Math.min(oldStart, currentTime);
-  const newEnd = Math.max(oldStart + oldDuration, currentTime);
-  const newDuration = roundTo3(newEnd - newStart);
-  const toPct = (absoluteTime: number) =>
-    newDuration > 0
-      ? Math.max(
-          0,
-          Math.min(100, Math.round(((absoluteTime - newStart) / newDuration) * 1000) / 10),
-        )
-      : 0;
-  const stops = anim.keyframes?.keyframes ?? [];
-  const rescaled: GsapPercentageKeyframe[] = stops.map((stop) => ({
-    percentage: toPct(oldStart + (stop.percentage / 100) * oldDuration),
-    properties: stop.properties,
-    ...(stop.ease ? { ease: stop.ease } : {}),
-  }));
-  const added: GsapPercentageKeyframe = { percentage: toPct(currentTime), properties: position };
-  const keyframes = [...rescaled, added].sort((a, b) => a.percentage - b.percentage);
-  return { position: roundTo3(newStart), duration: newDuration, keyframes };
+  return isTimeWithinTween(currentTime, start, resolveTweenDuration(anim));
 }
 
 async function replaceSetWithSingleKeyframe(
@@ -285,17 +244,24 @@ async function extendKeyframedTweenToPlayhead(
  * buildExtendedKeyframes). Shared by native keyframe tweens and flat tweens that
  * were just converted, so both behave identically.
  */
-async function applyKeyframeAtPlayhead(
+export async function applyKeyframeAtPlayhead(
   session: EnableKeyframesSession,
   sel: DomEditSelection,
   kfAnim: GsapAnimation,
   t: number,
   iframe: HTMLIFrameElement | null,
   commitOverrides?: Partial<CommitMutationOptions>,
+  liveTween?: ReturnType<typeof findParsedTween>,
 ): Promise<void> {
-  const duration = resolveEditableTweenDuration(kfAnim, sel);
+  const keepAuthoredDuration = kfAnim.durationUnresolved === true;
+  if (keepAuthoredDuration) {
+    kfAnim = withLiveTiming(kfAnim, liveTween ?? findParsedTween(iframe, sel.element, kfAnim));
+  }
+  if (keepAuthoredDuration && kfAnim.duration == null) return;
+  const duration = resolveTweenDuration(kfAnim);
   const start = resolveTweenStart(kfAnim);
   if (start !== null && !isTimeWithinTween(t, start, duration)) {
+    if (keepAuthoredDuration) return;
     await extendKeyframedTweenToPlayhead(
       session,
       sel,
@@ -308,10 +274,10 @@ async function applyKeyframeAtPlayhead(
     return;
   }
   const pct =
-    start === null ? computeElementPercentage(t, sel) : absoluteToPercentage(t, start, duration);
-  const existing = kfAnim.keyframes?.keyframes.find(
-    (k) => Math.abs(k.percentage - pct) <= KEYFRAME_PCT_MATCH,
-  );
+    start === null
+      ? computeElementPercentage(t, sel)
+      : (absoluteToPercentageForAnimation(t, kfAnim) ?? 0);
+  const existing = kfAnim.keyframes?.keyframes.find((k) => playsNear(kfAnim, k.percentage, pct));
   if (existing) {
     session.handleGsapRemoveKeyframe(kfAnim.id, existing.percentage);
     return;
@@ -404,21 +370,27 @@ export async function applyArcKeyframeAtPlayhead(
   const targetSelector = existingTweenTargetSelector(arcAnim, sel);
   if (!targetSelector) return;
   const start = resolveTweenStart(arcAnim) ?? 0;
-  const duration = resolveEditableTweenDuration(arcAnim, sel);
+  const duration = resolveTweenDuration(arcAnim);
   if (!isTimeWithinTween(t, start, duration)) {
-    if (t > start) {
-      await session.commitMutation(
-        {
-          type: "update-meta",
-          animationId: arcAnim.id,
-          updates: { duration: roundTo3(t - start) },
-        },
-        { label: "Extend motion path", softReload: true },
-      );
-    }
+    const held = readElementPosition(iframe, sel, arcAnim);
+    if (t <= start || typeof held.x !== "number" || typeof held.y !== "number") return;
+    const extended = buildExtendedKeyframes(arcAnim, t, { x: held.x, y: held.y }, duration, "none");
+    await session.commitMutation(
+      {
+        type: "replace-with-keyframes",
+        animationId: arcAnim.id,
+        targetSelector,
+        position: extended.position,
+        duration: extended.duration,
+        keyframes: extended.keyframes,
+        ease: "none",
+      },
+      { label: "Add keyframe", keyframeAction: "add", softReload: true },
+    );
     return;
   }
-  const nodes = arcAnim.keyframes?.keyframes ?? [];
+  // The arc is rewritten linear: compare and write at the times GSAP plays each node.
+  const nodes = linearArcKeyframes(arcAnim);
   const playheadPercentage = absoluteToPercentage(t, start, duration);
   const timedNodeIndex = nodes.findIndex(
     (node) => Math.abs(node.percentage - playheadPercentage) <= KEYFRAME_PCT_MATCH,
@@ -502,6 +474,9 @@ export function useEnableKeyframes(
       // resolvedFromValues, so the 0%/100% stops keep the real start→end motion
       // (passing the playhead value would flatten it). Then apply uniformly so an
       // out-of-range playhead extends the range just like a keyframe tween.
+      const flatLive = flatAnim.durationUnresolved
+        ? findParsedTween(iframe, sel.element, flatAnim)
+        : undefined;
       enableKeyframesTransactionCounter += 1;
       const coalesceKey = `enable-keyframes:${flatAnim.id}:${enableKeyframesTransactionCounter}`;
       const convertCommitOverrides: Partial<CommitMutationOptions> = {
@@ -527,7 +502,15 @@ export function useEnableKeyframes(
           // conversion splits into two undo entries under real latency.
           coalesceMs: Number.POSITIVE_INFINITY,
         };
-        await applyKeyframeAtPlayhead(session, sel, converted, t, iframe, applyCommitOverrides);
+        await applyKeyframeAtPlayhead(
+          session,
+          sel,
+          converted,
+          t,
+          iframe,
+          applyCommitOverrides,
+          flatLive,
+        );
       }
     } else {
       const position = readElementPosition(iframe, sel, null);

package/src/hooks/useGestureCommit.ts

@@ -8,6 +8,7 @@ import { simplifyGestureSamples } from "../utils/rdpSimplify";
 import { fitEasesFromVelocity } from "../utils/velocityEaseFitter";
 import { smoothGestureKeyframes } from "../utils/gestureSmoother";
 import { usePlayerStore } from "../player";
+import { resolveTweenDuration } from "../utils/globalTimeCompiler";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
@@ -258,7 +259,7 @@ export function useGestureCommit({
             );
           } else {
             const tweenStart = existingPositionTween.resolvedStart ?? 0;
-            const tweenDur = existingPositionTween.duration ?? duration;
+            const tweenDur = resolveTweenDuration(existingPositionTween);
             const tweenEnd = tweenStart + tweenDur;
             const recEnd = recStart + duration;
 

package/src/hooks/useGsapAwareEditing.groupPlan.test.tsx

@@ -127,6 +127,31 @@ describe("a group drag plans every member before its first write", () => {
     act(() => h.root.unmount());
   });
 
+  it("with auto-keyframe off, refuses the whole group when one member's step list holds a step delay", async () => {
+    usePlayerStore.setState({ autoKeyframeEnabled: false });
+    const steps = {
+      format: "object-array",
+      keyframes: [
+        { percentage: 50, properties: { x: 100, y: 0, delay: 0.5 } },
+        { percentage: 100, properties: { x: 200, y: 0 } },
+      ],
+    };
+    const h = mountGroup([
+      positionTween("a"),
+      positionTween("b", { keyframes: steps } as Partial<GsapAnimation>),
+      positionTween("c"),
+    ]);
+
+    await expect(h.groupCommit(h.updates)).rejects.toMatchObject({
+      reason: "keyframes-uneditable",
+      detail: "array-step-delay",
+    });
+
+    expect(h.written()).toEqual([]);
+    expect(trackStudioEditBlocked).toHaveBeenCalledWith(expect.objectContaining({ targetId: "b" }));
+    act(() => h.root.unmount());
+  });
+
   it("refuses members animated in two files, since the batch writes one file", async () => {
     const h = mountGroup(["a", "b", "c"].map((id) => positionTween(id)));
     const updates = h.updates.map((u, i) => ({

package/src/hooks/useGsapTweenCache.ts

@@ -11,7 +11,7 @@ import {
   publishKeyframeCache,
   writeGsapAnimationsForElement,
 } from "./gsapKeyframeCacheHelpers";
-import { resolveClipTimingBasis, toAbsoluteTime, toClipPercentage } from "./gsapShared";
+import { resolveClipTimingBasis, toClipKeyframes } from "./gsapShared";
 import {
   deduplicateKeyframes,
   isStaticPositionHold,
@@ -199,22 +199,7 @@ export function useGsapAnimationsForElement(
       if (isStaticPositionHold(anim)) continue;
       const kf = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
       if (!kf) continue;
-      // Convert tween-relative percentages to clip-relative so diamonds
-      // render at the correct position within the timeline clip.
-      const tweenPos =
-        anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
-      const tweenDur = anim.duration ?? elDuration;
-      for (const k of kf.keyframes) {
-        const absTime = toAbsoluteTime(tweenPos, tweenDur, k.percentage);
-        const clipPct = toClipPercentage(absTime, elStart, elDuration, k.percentage);
-        allKeyframes.push({
-          ...k,
-          percentage: clipPct,
-          tweenPercentage: k.percentage,
-          propertyGroup: anim.propertyGroup,
-          animationId: anim.id,
-        });
-      }
+      allKeyframes.push(...toClipKeyframes(kf.keyframes, anim, elStart, elDuration));
       format = kf.format;
       if (kf.ease) ease = kf.ease;
       if (kf.easeEach) easeEach = kf.easeEach;

package/src/hooks/usePersistentEditHistory.test.ts

@@ -14,6 +14,10 @@ import {
   type StudioApiAdapter,
 } from "@hyperframes/studio-server";
 import { consumeStudioWriteToken } from "../utils/studioFileVersion";
+import {
+  beginStudioPendingEdit,
+  paintBackNewestStudioPendingEdit,
+} from "../utils/studioPendingEdits";
 import { usePersistentEditHistory } from "./usePersistentEditHistory";
 
 const cleanup: Array<() => unknown> = [];
@@ -88,6 +92,22 @@ it("an edit Studio saved is undone and redone by the project's history, with the
   expect(file()).toBe("B");
 });
 
+it("gives an edit that begins the history's claim count, so undo can tell its claims from older ones", async () => {
+  const { hook, save } = await studio();
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  const saving = beginStudioPendingEdit(() => () => {});
+
+  expect(paintBackNewestStudioPendingEdit()?.claimsAtBegin).toBe(hook().claims());
+  expect(hook().claims()).toBe(1);
+  saving.settle();
+});
+
 it("undoes the edit claimed since the key, not a later edit the server took in first", async () => {
   const { dir, hook, file, save, readFile } = await studio();
   const atKey = hook().claims();
@@ -366,6 +386,31 @@ it("a drag's edits under one key undo as one step, even before the drag goes idl
   expect(file()).toBe("A");
 });
 
+it("a key one page holds does not join another page's edit under the same key", async () => {
+  const { hook, file, save, readFile } = await studio();
+  let reloaded!: ReturnType<typeof usePersistentEditHistory>;
+  function Reloaded() {
+    reloaded = usePersistentEditHistory({ projectId: "demo" });
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  await act(async () => root.render(createElement(Reloaded)));
+  cleanup.push(() => act(() => root.unmount()));
+  const held = { label: "Moved Title", coalesceKey: "timeline-move:1", coalesceMs: Infinity };
+  save("B");
+  await act(() =>
+    hook().recordEdit({ ...held, files: { "index.html": { before: "A", after: "B" } } }),
+  );
+  save("C");
+  await act(() =>
+    reloaded.recordEdit({ ...held, files: { "index.html": { before: "B", after: "C" } } }),
+  );
+
+  await act(() => reloaded.undo({ readFile }));
+
+  expect(file()).toBe("B");
+});
+
 it("an undo before the history view shows a drag's held claim still waits on the files it wrote", async () => {
   const { hook, save, readFile } = await studio();
   const server = globalThis.fetch;

package/src/hooks/usePersistentEditHistory.ts

@@ -3,7 +3,9 @@ import type { HistoryListItem, HistoryResult } from "@hyperframes/studio-server"
 import { studioFileContentVersion, studioWriteHeaders } from "../utils/studioFileVersion";
 import type { RestoreFiles } from "../utils/gsapUndoRestore";
 import { studioApiFetch } from "../utils/studioApiFetch";
+import { setStudioPendingEditClaimClock } from "../utils/studioPendingEdits";
 import type { RecordEditInput } from "../utils/studioFileHistory";
+import { generateId } from "../utils/generateId";
 
 interface ApplyCallbacks {
   readFile: (path: string) => Promise<string>;
@@ -206,6 +208,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
   const [own] = useState(createOwnHistory);
+  const [pageKeyScope] = useState(generateId);
 
   const refresh = useCallback(async () => {
     if (!projectId) return;
@@ -228,6 +231,11 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
     void refresh().finally(() => setLoaded(true));
   }, [refresh, own]);
 
+  useEffect(() => {
+    setStudioPendingEditClaimClock(own.claimCount);
+    return () => setStudioPendingEditClaimClock(null);
+  }, [own]);
+
   const recordEdit = useCallback(
     async ({ label, coalesceKey, coalesceMs, files, created = [] }: RecordEditInput) => {
       if (!projectId) return;
@@ -237,7 +245,10 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
         label,
         paths,
         overwrote: await overwroteVersions(files),
-        ...(coalesceKey && { coalesceKey, idleMs: coalesceMs ?? DEFAULT_COALESCE_MS }),
+        ...(coalesceKey && {
+          coalesceKey: `${pageKeyScope}:${coalesceKey}`,
+          idleMs: coalesceMs ?? DEFAULT_COALESCE_MS,
+        }),
       });
       const claimed = claimHeld(reply, label);
       if (claimed) {
@@ -247,7 +258,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
       heldClaimRef.current = claimed && coalesceKey ? { paths, at: Date.now() } : null;
       await refresh();
     },
-    [projectId, refresh, own],
+    [projectId, refresh, own, pageKeyScope],
   );
 
   const step = useCallback(

package/src/hooks/usePreviewPersistence.history.test.tsx

@@ -4,6 +4,10 @@ import React, { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../player/store/playerStore";
 import type { TimelineElement } from "../player/store/timelineElement";
+import {
+  beginStudioManualEditGesture,
+  endStudioManualEditGesture,
+} from "../components/editor/manualEdits";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import { usePreviewPersistence } from "./usePreviewPersistence";
 
@@ -132,3 +136,82 @@ describe("undo that re-runs the top-level script over an element of a nested com
     expect(nwid.getAttribute("style")).toBe("left: 40px; width: 337px");
   });
 });
+
+describe("undo that lands while a newer gesture holds an element", () => {
+  const page = (left: number) =>
+    `<html><body><div id="root" data-composition-id="root"><div id="box" data-hf-id="hf-b" style="left: ${left}px"></div></div></body></html>`;
+  const files = { "index.html": { previous: page(0), restored: page(200) } };
+
+  function heldPreview(held = true) {
+    const doc = document.implementation.createHTMLDocument("");
+    doc.head.innerHTML = `<meta name="hf-scene-parts" content='{"shared":"s1","scenes":{}}'>`;
+    doc.body.innerHTML = `<div id="root" data-composition-id="root"><div id="box" data-hf-id="hf-b" style="left: 90px"></div></div>`;
+    const box = doc.getElementById("box")!;
+    if (held) beginStudioManualEditGesture(box, "move");
+    const contentWindow = {
+      __hfForceTimelineRebind: vi.fn(),
+      __timelines: {},
+      __player: { getTime: () => 1, seek: vi.fn() },
+      __hfStudioManualEditsApply: vi.fn(),
+    };
+    const iframe = { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement;
+    const reloadPreview = vi.fn();
+    let hook: ReturnType<typeof usePreviewPersistence> | null = null;
+    function Harness() {
+      hook = usePreviewPersistence({
+        showToast: () => {},
+        readOptionalProjectFile: async () => "",
+        writeProjectFile: async () => {},
+        recordEdit: async () => {},
+        previewIframeRef: { current: iframe },
+        activeCompPathRef: { current: "index.html" },
+        reloadPreview,
+      });
+      return null;
+    }
+    mountReactHarness(<Harness />);
+    usePlayerStore.getState().setSelectedElementId("box");
+    const sharedPart = () =>
+      JSON.parse(doc.querySelector<HTMLMetaElement>('meta[name="hf-scene-parts"]')!.content).shared;
+    return { box, win: contentWindow, reloadPreview, sharedPart, hook: () => hook! };
+  }
+
+  it("leaves the held element where the gesture drew it and reloads the preview once it ends", async () => {
+    const { box, win, reloadPreview, sharedPart, hook } = heldPreview();
+
+    await act(async () => hook().syncHistoryPreviewAfterApply({ paths: ["index.html"], files }));
+
+    expect(box.style.left).toBe("90px");
+    expect(win.__player.seek).not.toHaveBeenCalled();
+    expect(win.__hfStudioManualEditsApply).not.toHaveBeenCalled();
+    expect(reloadPreview).not.toHaveBeenCalled();
+    endStudioManualEditGesture(box);
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    // The scene swap must load the restored file again, not keep the part it showed before the undo.
+    expect(sharedPart()).toBe("");
+    expect(usePlayerStore.getState().selectedElementId).toBe("box");
+  });
+
+  it("does not paint a predicted undo under the gesture", () => {
+    const { box, win, hook } = heldPreview();
+
+    expect(hook().showHistoryRestoreNow(files)).toBeNull();
+    expect(box.style.left).toBe("90px");
+    expect(win.__player.seek).not.toHaveBeenCalled();
+  });
+
+  it("puts a refused predicted undo back through the preview reload once a gesture took the element", async () => {
+    const { box, win, reloadPreview, hook } = heldPreview(false);
+    const putBack = hook().showHistoryRestoreNow(files)!;
+    beginStudioManualEditGesture(box, "move");
+    win.__player.seek.mockClear();
+
+    putBack();
+    await act(async () => {});
+    expect(reloadPreview).not.toHaveBeenCalled();
+    endStudioManualEditGesture(box);
+
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(win.__player.seek).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/usePreviewPersistence.ts

@@ -4,7 +4,12 @@ import {
   installStudioManualEditSeekReapply,
   reapplyPositionEditsAfterSeek,
 } from "../components/editor/manualEdits";
+import {
+  afterStudioManualEditGestures,
+  isStudioManualEditGestureLiveIn,
+} from "../components/editor/manualEditsDom";
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
+import { markScenesStale } from "../player/sceneSwap";
 import { createDomEditSaveQueue, type DomEditSaveDrainResult } from "../utils/domEditSaveQueue";
 import {
   flushStudioPendingEdits,
@@ -199,6 +204,12 @@ export function usePreviewPersistence({
 
   // ── Sync preview after undo/redo ──
 
+  // Undo never repaints under a live gesture; the preview reloads once the last one ends.
+  const heldPreviewDoc = useCallback(() => {
+    const doc = previewIframeRef.current?.contentDocument;
+    return doc && isStudioManualEditGestureLiveIn(doc) ? doc : null;
+  }, [previewIframeRef]);
+
   const syncHistoryPreviewAfterApply = useCallback(
     async (restore: HistoryPreviewRestore) => {
       // Prefer an in-place soft reload for a soft-reloadable restore (the change
@@ -220,6 +231,15 @@ export function usePreviewPersistence({
               : Promise.reject(new Error("No project is open to read nested files from.")),
         ),
       );
+      const held = heldPreviewDoc();
+      if (held) {
+        const paths = restore.paths ?? Object.keys(restore.files ?? {});
+        afterStudioManualEditGestures(held, () => {
+          markScenesStale(previewIframeRef.current, paths);
+          reloadPreview();
+        });
+        return;
+      }
       const strategy = applyUndoRestoreToPreview(
         previewIframeRef.current,
         activeCompPathRef.current,
@@ -238,24 +258,26 @@ export function usePreviewPersistence({
       // reload. The full path above waits for the reloaded preview to report instead.
       syncStoredAutomationFromPreview(previewIframeRef.current?.contentDocument ?? null);
     },
-    [previewIframeRef, activeCompPathRef, reloadPreview],
+    [previewIframeRef, activeCompPathRef, reloadPreview, heldPreviewDoc],
   );
 
   // A restore the server has not confirmed yet: in place now, or not at all. A GSAP script re-run is not
   // synchronous, and a pending save would land under it.
   const showHistoryRestoreNow = useCallback(
     (files: RestoreFiles): (() => void) | null => {
-      if (!domEditSaveQueueRef.current?.isIdle() || hasStudioPendingEdits()) return null;
+      if (!domEditSaveQueueRef.current?.isIdle() || hasStudioPendingEdits() || heldPreviewDoc())
+        return null;
       const iframe = previewIframeRef.current;
       const now = () => usePlayerStore.getState().currentTime;
       const putBack = showRestoreInPlace(iframe, activeCompPathRef.current, files, now());
       if (!putBack) return null;
       return () => {
-        if (putBack(now())) syncStoredAutomationFromPreview(iframe?.contentDocument ?? null);
+        if (!heldPreviewDoc() && putBack(now()))
+          syncStoredAutomationFromPreview(iframe?.contentDocument ?? null);
         else void syncHistoryPreviewAfterApply({ paths: Object.keys(files) });
       };
     },
-    [previewIframeRef, activeCompPathRef, syncHistoryPreviewAfterApply],
+    [previewIframeRef, activeCompPathRef, syncHistoryPreviewAfterApply, heldPreviewDoc],
   );
 
   // ── Migrate legacy studio-motion.json ──