@hyperframes/studio 0.8.100 → 0.8.101

package/src/hooks/usePersistentEditHistory.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { HistoryListItem, HistoryResult } from "@hyperframes/studio-server";
 import { studioFileContentVersion, studioWriteHeaders } from "../utils/studioFileVersion";
+import type { RestoreFiles } from "../utils/gsapUndoRestore";
 
 interface RecordEditInput {
   label: string;
@@ -18,11 +19,6 @@ export interface UsePersistentEditHistoryOptions {
   projectId: string | null;
 }
 
-interface ApplyRestoredFile {
-  previous: string;
-  restored: string;
-}
-
 interface ApplyResult {
   ok: boolean;
   /** content-mismatch: `paths` changed after the step's entry. failed: `message` says why. */
@@ -30,7 +26,8 @@ interface ApplyResult {
   message?: string;
   label?: string;
   paths?: string[];
-  files?: Record<string, ApplyRestoredFile>;
+  undoes?: string;
+  files?: RestoreFiles;
 }
 
 interface NextStep {
@@ -47,6 +44,69 @@ interface HistoryView {
 }
 
 const EMPTY: HistoryView = { entries: [], back: null, forward: null };
+/** ponytail: the newest entries' content is kept; older ones step through the server only. */
+const OWN_ENTRIES_KEPT = 100;
+
+type OwnFiles = Record<string, { before: string; after: string }>;
+
+function createOwnHistory() {
+  const own = new Map<string, OwnFiles>();
+  let next: Record<"undo" | "redo", NextStep | null> | null = null;
+  let changes = 0;
+  const remember = (id: string, files: OwnFiles) => {
+    const known = own.get(id) ?? {};
+    for (const [path, { before, after }] of Object.entries(files)) {
+      known[path] = { before: known[path]?.before ?? before, after };
+    }
+    own.delete(id);
+    own.set(id, known);
+    if (own.size > OWN_ENTRIES_KEPT) own.delete(own.keys().next().value!);
+  };
+  return {
+    remember,
+    overtake: () => {
+      changes += 1;
+      next = null;
+      return changes;
+    },
+    offered: (seen: number, view: HistoryView) => {
+      if (seen === changes) next = { undo: view.back, redo: view.forward };
+    },
+    changes: () => changes,
+    stepped: (entry: { id: string; undoes?: string }) => {
+      const undone = entry.undoes ? own.get(entry.undoes) : undefined;
+      if (!undone) return;
+      const swapped = Object.entries(undone).map(([path, f]) => [
+        path,
+        { before: f.after, after: f.before },
+      ]);
+      remember(entry.id, Object.fromEntries(swapped));
+    },
+    afterOf: (id: string | undefined): Record<string, string> =>
+      Object.fromEntries(Object.entries((id && own.get(id)) || {}).map(([p, f]) => [p, f.after])),
+    predict: (direction: "undo" | "redo"): { id: string; files: RestoreFiles } | null => {
+      const step = next?.[direction];
+      const files = step ? own.get(step.id) : undefined;
+      const paths = files ? Object.keys(files) : [];
+      if (
+        !files ||
+        paths.length !== step!.paths.length ||
+        !paths.every((p) => step!.paths.includes(p))
+      )
+        return null;
+      const restore = paths.map((path) => [
+        path,
+        { previous: files[path]!.after, restored: files[path]!.before },
+      ]);
+      return { id: step!.id, files: Object.fromEntries(restore) };
+    },
+    clear: () => {
+      own.clear();
+      next = null;
+      changes += 1;
+    },
+  };
+}
 const DEFAULT_COALESCE_MS = 300;
 
 function historyUrl(projectId: string, path = ""): string {
@@ -71,12 +131,13 @@ async function post(
   return { ok: false, status: response.status, error: reply?.error ?? `HTTP ${response.status}` };
 }
 
-/** Whether a drag's claim is held open; a failed one is logged (its write lands as an outside change; 404: none). */
-function claimHeld(reply: Awaited<ReturnType<typeof post>>, label: string): boolean {
-  if (reply.ok) return Boolean((reply.body as { claimed: { id: string } | null } | null)?.claimed);
+/** The entry id a claim took, or null; a failed one is logged (its write lands as an outside change; 404: none). */
+function claimHeld(reply: Awaited<ReturnType<typeof post>>, label: string): string | null {
+  if (reply.ok)
+    return (reply.body as { claimed: { id: string } | null } | null)?.claimed?.id ?? null;
   if (reply.status !== 404)
     console.error(`"${label}" was not recorded as your edit: ${reply.error}`);
-  return false;
+  return null;
 }
 
 async function overwroteVersions(files: RecordEditInput["files"]): Promise<Record<string, string>> {
@@ -106,7 +167,7 @@ async function restoredFiles(
   paths: readonly string[],
   previous: Record<string, string> | null,
   readFile: (path: string) => Promise<string>,
-): Promise<Record<string, ApplyRestoredFile> | undefined> {
+): Promise<RestoreFiles | undefined> {
   if (!previous || paths.some((path) => !(path in previous))) return undefined;
   const restored = await readAll(paths, readFile);
   if (!restored) return undefined;
@@ -128,36 +189,43 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   const heldClaimRef = useRef<{ paths: string[]; at: number } | null>(null);
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
+  const [own] = useState(createOwnHistory);
 
   const refresh = useCallback(async () => {
     if (!projectId) return;
+    const seen = own.changes();
     const response = await fetch(historyUrl(projectId)).catch(() => null);
     const next = response?.ok ? ((await response.json()) as HistoryView) : EMPTY;
-    if (projectIdRef.current === projectId) setView(next);
-  }, [projectId]);
+    if (projectIdRef.current !== projectId) return;
+    setView(next);
+    own.offered(seen, next);
+  }, [projectId, own]);
 
   useEffect(() => {
     setView(EMPTY);
     setLoaded(false);
     heldClaimRef.current = null;
+    own.clear();
     void refresh().finally(() => setLoaded(true));
-  }, [refresh]);
+  }, [refresh, own]);
 
   const recordEdit = useCallback(
     async ({ label, coalesceKey, coalesceMs, files }: RecordEditInput) => {
       if (!projectId) return;
       const paths = Object.keys(files);
+      own.overtake();
       const reply = await post(historyUrl(projectId, "/claim"), {
         label,
         paths,
         overwrote: await overwroteVersions(files),
         ...(coalesceKey && { coalesceKey, idleMs: coalesceMs ?? DEFAULT_COALESCE_MS }),
       });
-      heldClaimRef.current =
-        claimHeld(reply, label) && coalesceKey ? { paths, at: Date.now() } : null;
+      const claimed = claimHeld(reply, label);
+      if (claimed) own.remember(claimed, files);
+      heldClaimRef.current = claimed && coalesceKey ? { paths, at: Date.now() } : null;
       void refresh();
     },
-    [projectId, refresh],
+    [projectId, refresh, own],
   );
 
   const step = useCallback(
@@ -165,6 +233,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
       if (!projectId) return { ok: false, reason: "empty" };
       const next = direction === "undo" ? view.back : view.forward;
       const paths = [...new Set([...(next?.paths ?? []), ...(heldClaimRef.current?.paths ?? [])])];
+      own.overtake();
       const run = async (): Promise<ApplyResult> => {
         const previous = await readAll(paths, callbacks.readFile);
         const posted = await post(
@@ -183,19 +252,30 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
           return { ok: false, reason: "content-mismatch", paths: files };
         }
         if (!reply.entry) return { ok: false, reason: "empty" };
+        own.stepped(reply.entry);
         const changed = reply.entry.files.map((file) => file.path);
         return {
           ok: true,
           label: reply.entry.label,
+          undoes: reply.entry.undoes,
           paths: changed,
-          files: await restoredFiles(changed, previous, callbacks.readFile),
+          files: await restoredFiles(
+            changed,
+            { ...own.afterOf(reply.entry.undoes), ...previous },
+            callbacks.readFile,
+          ),
         };
       };
       return callbacks.serialize ? callbacks.serialize(paths, run) : run();
     },
-    [projectId, view, refresh],
+    [projectId, view, refresh, own],
   );
 
+  const noteOutsideChange = useCallback(() => {
+    own.overtake();
+    void refresh();
+  }, [own, refresh]);
+
   const undo = useCallback((callbacks: ApplyCallbacks) => step("undo", callbacks), [step]);
   const redo = useCallback((callbacks: ApplyCallbacks) => step("redo", callbacks), [step]);
 
@@ -220,5 +300,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
     recordEdit,
     undo,
     redo,
+    predict: own.predict,
+    noteOutsideChange,
   };
 }

package/src/hooks/usePreviewPersistence.ts

@@ -8,17 +8,22 @@ import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import { createDomEditSaveQueue, type DomEditSaveDrainResult } from "../utils/domEditSaveQueue";
 import {
   flushStudioPendingEdits,
+  hasStudioPendingEdits,
   type StudioPendingEditsDrainResult,
 } from "../utils/studioPendingEdits";
 import { trackStudioEvent } from "../utils/studioTelemetry";
-import { applyUndoRestoreToPreview, type UndoRestoreFile } from "../utils/gsapUndoRestore";
+import {
+  applyUndoRestoreToPreview,
+  showRestoreInPlace,
+  type RestoreFiles,
+} from "../utils/gsapUndoRestore";
 import { usePlayerStore } from "../player";
 import { syncStoredAutomationFromPreview } from "../player/lib/automationStoreSync";
 
 /** The restore payload the undo/redo preview-sync consumes (from the history store). */
 interface HistoryPreviewRestore {
   paths?: string[];
-  files?: Record<string, UndoRestoreFile>;
+  files?: RestoreFiles;
 }
 
 // ── Types ──
@@ -217,6 +222,23 @@ export function usePreviewPersistence({
     [previewIframeRef, activeCompPathRef, reloadPreview],
   );
 
+  // 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;
+      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);
+        else void syncHistoryPreviewAfterApply({ paths: Object.keys(files) });
+      };
+    },
+    [previewIframeRef, activeCompPathRef, syncHistoryPreviewAfterApply],
+  );
+
   // ── Migrate legacy studio-motion.json ──
   // Projects that used the old JSON-file approach may still have a populated
   // `.hyperframes/studio-motion.json`. The studio no longer reads from it, but
@@ -239,5 +261,6 @@ export function usePreviewPersistence({
     applyCurrentStudioManualEditsToPreview,
     applyStudioManualEditsToPreview,
     syncHistoryPreviewAfterApply,
+    showHistoryRestoreNow,
   };
 }

package/src/hooks/useStudioExternalFileChanges.ts

@@ -36,6 +36,7 @@ interface UseStudioExternalFileChangesOptions {
   previewPersistence: PreviewPersistence;
   pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
   reloadPreview: () => void;
+  onOutsideChange?: () => void;
 }
 
 /** Connects the app's save queues, recovery storage, and reload surfaces to one owner. */
@@ -47,14 +48,17 @@ export function useStudioExternalFileChanges({
   previewPersistence,
   pendingTimelineEditPathRef,
   reloadPreview,
+  onOutsideChange,
 }: UseStudioExternalFileChangesOptions) {
   const { flushPendingSourceSave, discardPendingSourceSave } = fileManager;
   const { drainPendingDomEditSaves, resetDomEditSaveQueueBreaker } = previewPersistence;
   const bumpThumbnailRevisions = usePlayerStore((state) => state.bumpThumbnailRevisions);
   const onAcceptedPersistedFileChange = useCallback(
-    (_path: string, affectedCompositions: readonly string[] | null) =>
-      bumpThumbnailRevisions(affectedCompositions),
-    [bumpThumbnailRevisions],
+    (_path: string, affectedCompositions: readonly string[] | null) => {
+      onOutsideChange?.();
+      bumpThumbnailRevisions(affectedCompositions);
+    },
+    [bumpThumbnailRevisions, onOutsideChange],
   );
   const drainPendingChanges = useCallback(async () => {
     const source = await flushPendingSourceSave();

package/src/index.ts

@@ -12,6 +12,10 @@ export type { ShortcutHint, ShortcutSection } from "./player/components/studioSh
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
 export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
 export { useCompositionStack } from "./components/nle/useCompositionStack";
+export { Dock } from "./components/dock/Dock";
+export { useDockLayoutStore } from "./components/dock/dockLayoutStore";
+export type { DockController } from "./components/dock/dockLayoutStore";
+export type { PanelId } from "./components/dock/panelRegistry";
 
 // Player (preview, timeline, playback controls)
 export {

package/src/player/components/timelineDragDrop.test.tsx

@@ -4,7 +4,7 @@ import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
 import { TIMELINE_ASSET_MIME, TIMELINE_BLOCK_MIME } from "../../utils/timelineAssetDrop";
-import { usePlayerStore } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { createTimelineRowGeometry } from "./timelineLayout";
 import { resolveDropInsertRow, useTimelineAssetDrop } from "./timelineDragDrop";
 import { getTimelineRowTop, TRACK_H } from "./timelineLayout";
@@ -39,10 +39,19 @@ function assetTransfer(payload: string): DropTransfer {
   };
 }
 
+// One far-off clip per lane, so a drop keeps its pointer time instead of an empty lane's 0.
+const FAR_CLIPS: TimelineElement[] = Array.from({ length: 100 }, (_, track) => ({
+  id: `far-${track}`,
+  tag: "div",
+  start: 900,
+  duration: 1,
+  track,
+}));
+
 function renderHarness(
   onAssetDrop: Mock,
   sessionEpoch = 1,
-  options: { onBlockDrop?: Mock; strict?: boolean } = {},
+  options: { onBlockDrop?: Mock; strict?: boolean; elements?: TimelineElement[] } = {},
 ) {
   const tracks = Array.from({ length: 100 }, (_, index) => index);
   const geometry = createTimelineRowGeometry(
@@ -60,6 +69,7 @@ function renderHarness(
       scrollRef: { current: scroll },
       ppsRef: { current: 40 },
       trackOrderRef: { current: tracks },
+      elementsRef: { current: options.elements ?? FAR_CLIPS },
       rowGeometryRef: { current: geometry },
       contentOrigin: 0,
       sessionEpoch: epoch,
@@ -149,8 +159,8 @@ describe("useTimelineAssetDrop", () => {
     });
 
     expect(onAssetDrop).toHaveBeenCalledTimes(1);
-    // pps=40, clientX=400 -> 10s at the pointer, not the playhead.
-    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 10, track: 100 });
+    // The appended lane is empty, so the drop starts at 0.
+    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 0, track: 100 });
     expect(view.api.isDragOver).toBe(false);
     act(() => view.root.unmount());
   });
@@ -256,6 +266,52 @@ describe("useTimelineAssetDrop", () => {
   });
 });
 
+describe("useTimelineAssetDrop start", () => {
+  function dropAt(elements: TimelineElement[], clientX: number) {
+    const onAssetDrop = vi.fn();
+    const view = renderHarness(onAssetDrop, 1, { elements });
+    const transfer = assetTransfer(JSON.stringify({ path: "assets/a.mp4" }));
+    act(() => view.api.handleAssetDragOver(dragEvent(transfer, clientX, ROW0_MID_Y)));
+    const preview = view.api.dropPreview;
+    act(() => view.api.handleAssetDrop(dragEvent(transfer, clientX, ROW0_MID_Y)));
+    act(() => view.root.unmount());
+    return { preview, committed: onAssetDrop.mock.calls[0]?.[1] };
+  }
+
+  it("starts a drop on an empty timeline at 0, in the preview and the commit", () => {
+    // pps=40, clientX=80 -> 2s at the pointer.
+    const { preview, committed } = dropAt([], 80);
+    expect(preview).toEqual({ start: 0, track: 0 });
+    expect(committed).toEqual(preview);
+  });
+
+  it("starts a drop on an empty lane at 0 while other lanes hold clips", () => {
+    const { committed } = dropAt([{ id: "c", tag: "div", start: 0, duration: 5, track: 1 }], 80);
+    expect(committed).toEqual({ start: 0, track: 0 });
+  });
+
+  it("snaps a drop within TIMELINE_SNAP_PX of a clip edge onto that edge", () => {
+    const lane: TimelineElement[] = [{ id: "c", tag: "div", start: 0, duration: 5, track: 0 }];
+    // The clip ends at x=200; 6 px past it is 5.15s, inside the 8 px radius.
+    const { preview, committed } = dropAt(lane, 206);
+    expect(preview).toEqual({ start: 5, track: 0 });
+    expect(committed).toEqual(preview);
+    // 12 px past it is outside the radius and keeps the pointer time.
+    expect(dropAt(lane, 212).committed).toEqual({ start: 5.3, track: 0 });
+  });
+
+  it("keeps the pointer time with the magnet off, and still starts an empty lane at 0", () => {
+    usePlayerStore.getState().setTimelineSnapEnabled(false);
+    try {
+      const lane: TimelineElement[] = [{ id: "c", tag: "div", start: 0, duration: 5, track: 0 }];
+      expect(dropAt(lane, 206).committed).toEqual({ start: 5.15, track: 0 });
+      expect(dropAt([], 80).committed).toEqual({ start: 0, track: 0 });
+    } finally {
+      usePlayerStore.getState().setTimelineSnapEnabled(true);
+    }
+  });
+});
+
 describe("resolveDropInsertRow", () => {
   const rows = [TRACK_H, TRACK_H, TRACK_H];
   it("stays on the row at the boundary between two rows", () => {
@@ -302,7 +358,7 @@ describe("useTimelineAssetDrop new-track drops", () => {
     expect(onAssetDrop).toHaveBeenCalledWith(
       "assets/a.png",
       expect.objectContaining({
-        start: 10,
+        start: 0,
         insertRow: 0,
         trackOrder: Array.from({ length: 100 }, (_, index) => index),
       }),

package/src/player/components/timelineDragDrop.ts

@@ -10,6 +10,8 @@ import {
   type TimelineRowGeometry,
 } from "./timelineLayout";
 import { resolveInsertRow } from "./timelineCollision";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { collectTimelineSnapTargets, snapTimelineTime, TIMELINE_SNAP_PX } from "./timelineSnapping";
 import type { TimelineDropCallbacks, TimelineDropPlacement } from "./timelineCallbacks";
 import {
   applyTimelineAutoScrollStep,
@@ -20,6 +22,7 @@ interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   scrollRef: RefObject<HTMLDivElement | null>;
   ppsRef: RefObject<number>;
   trackOrderRef: RefObject<number[]>;
+  elementsRef: RefObject<readonly TimelineElement[]>;
   rowGeometryRef: RefObject<TimelineRowGeometry>;
   contentOrigin: number;
   sessionEpoch: number;
@@ -65,20 +68,36 @@ export function resolveDropInsertRow(
   return resolveInsertRow(rowFloat, trackCount);
 }
 
+function alignDropStart(
+  placement: TimelineDropPlacement,
+  elements: readonly TimelineElement[],
+  pixelsPerSecond: number,
+): TimelineDropPlacement {
+  const laneHasClips =
+    placement.insertRow == null && elements.some((el) => el.track === placement.track);
+  if (!laneHasClips) return { ...placement, start: 0 };
+  if (!usePlayerStore.getState().timelineSnapEnabled) return placement;
+  const targets = collectTimelineSnapTargets({ elements, playheadTime: null, beatTimes: [] });
+  const threshold = TIMELINE_SNAP_PX / Math.max(pixelsPerSecond, 1);
+  return { ...placement, start: snapTimelineTime(placement.start, targets, threshold).time };
+}
+
 function placeDrop(
   geometry: Parameters<typeof resolveTimelineAssetDrop>[0],
+  elements: readonly TimelineElement[],
   clientX: number,
   clientY: number,
   // Blocks and compositions are written by their own installers, which only take a track.
   canInsertTrack: boolean,
 ): TimelineDropPlacement {
   const placement = resolveTimelineAssetDrop(geometry, clientX, clientY);
-  if (!canInsertTrack) return placement;
   const contentY = clientY - geometry.rectTop + geometry.scrollTop;
-  const insertRow = resolveDropInsertRow(contentY, geometry.rowHeights, geometry.trackOrder.length);
-  return insertRow == null
-    ? placement
-    : { ...placement, insertRow, trackOrder: geometry.trackOrder };
+  const insertRow = canInsertTrack
+    ? resolveDropInsertRow(contentY, geometry.rowHeights, geometry.trackOrder.length)
+    : null;
+  const aimed =
+    insertRow == null ? placement : { ...placement, insertRow, trackOrder: geometry.trackOrder };
+  return alignDropStart(aimed, elements, geometry.pixelsPerSecond);
 }
 
 function invokeDropCallback(callback: () => Promise<void> | void): void {
@@ -118,14 +137,15 @@ function applyTypedJsonDrop(
 }
 
 /**
- * Dropping an asset/file/block/composition onto the timeline places it on the row
- * and at the time it was dropped on; an asset moves to that row's nearest free time.
+ * Dropping an asset/file/block/composition places it on the row at 0 on an empty lane, else at
+ * the pointer snapped to a near clip edge; an asset moves to that row's nearest free time.
  * Supersedes the prior playhead decision (#2291); see useAddAssetAtPlayhead.
  */
 export function useTimelineAssetDrop({
   scrollRef,
   ppsRef,
   trackOrderRef,
+  elementsRef,
   rowGeometryRef,
   contentOrigin,
   onFileDrop,
@@ -197,12 +217,13 @@ export function useTimelineAssetDrop({
           rowHeights: rowGeometryRef.current.rowHeights,
           trackOrder: trackOrderRef.current,
         },
+        elementsRef.current,
         clientX,
         clientY,
         canInsertTrack,
       );
     },
-    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
+    [scrollRef, ppsRef, trackOrderRef, elementsRef, rowGeometryRef, contentOrigin],
   );
 
   const handleAssetDragOver = useCallback(

package/src/player/components/useTimelineProviderState.tsx

@@ -229,6 +229,7 @@ export function useTimelineProviderState({
     scrollRef,
     ppsRef,
     trackOrderRef,
+    elementsRef: timelineElementsRef,
     rowGeometryRef,
     contentOrigin,
     onFileDrop: pinnedOnFileDrop,

package/src/utils/domEditSaveQueue.ts

@@ -20,6 +20,7 @@ interface DomEditSaveQueueOptions {
 export interface DomEditSaveQueue {
   enqueue: <T>(save: () => Promise<T>) => Promise<T>;
   waitForIdle: () => Promise<DomEditSaveDrainResult>;
+  isIdle: () => boolean;
   reset: () => void;
   destroy: () => void;
 }
@@ -39,6 +40,7 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
   const failureThreshold = options.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
 
   let tail = Promise.resolve();
+  let queuedCount = 0;
   let consecutiveFailures = 0;
   let breakerOpen = false;
   let drainError: unknown = null;
@@ -81,6 +83,7 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
   return {
     enqueue(save) {
       if (breakerOpen) return Promise.reject(new DomEditSaveQueueOpenError());
+      queuedCount += 1;
       const queued = tail
         .catch(() => undefined)
         .then(() => {
@@ -88,8 +91,8 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
           return run(save);
         });
       tail = queued.then(
-        () => undefined,
-        () => undefined,
+        () => void (queuedCount -= 1),
+        () => void (queuedCount -= 1),
       );
       return queued;
     },
@@ -103,6 +106,8 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
       return { status: "clean" };
     },
 
+    isIdle: () => queuedCount === 0,
+
     reset,
 
     destroy() {

package/src/utils/gsapSoftReload.ts

@@ -91,7 +91,7 @@ function isGsapScript(text: string): boolean {
   );
 }
 
-export function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
+export function findGsapScriptElements(doc: ParentNode): HTMLScriptElement[] {
   const results: HTMLScriptElement[] = [];
   const scripts = doc.querySelectorAll<HTMLScriptElement>("script:not([src])");
   for (const script of scripts) {

package/src/utils/gsapUndoRestore.test.ts

@@ -366,6 +366,52 @@ describe("applyUndoRestoreToPreview", () => {
     expect(meta.content).toBe(content);
   });
 
+  const SUB = "compositions/sub.html";
+  const sub = (style: string, rootAttrs = "") =>
+    `<template id="sub-template"><div data-hf-id="hf-root" id="sub" data-composition-id="sub"${rootAttrs}><div ${style} data-hf-id="hf-t" id="target"></div></div></template>`;
+  const host = (style: string) =>
+    `<div data-composition-file="${SUB}" data-hf-id="hf-host"><div data-hf-inner-root="true" data-hf-authored-id="sub" data-hf-id="hf-root"><div data-hf-id="hf-t" id="target" ${style}></div></div></div>`;
+
+  it("restores a sub-composition file in place, on every host that inlines it", () => {
+    const { iframe, doc } = buildLiveIframe(
+      host(`style="clip-path: inset(0px 40px 0px 0px);"`) +
+        host(`style="clip-path: inset(0px 40px 0px 0px);"`),
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [SUB]: { previous: sub(`style="clip-path: inset(0px 40px 0px 0px)"`), restored: sub("") },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    const targets = [...doc.querySelectorAll('[data-hf-id="hf-t"]')];
+    expect(targets.map((el) => el.getAttribute("style"))).toEqual([null, null]);
+  });
+
+  it("full-reloads a sub-composition restore that changes the file's own root", () => {
+    const { iframe } = buildLiveIframe(host(""));
+    const reloadPreview = vi.fn();
+    const files = { [SUB]: { previous: sub("", ' data-width="10"'), restored: sub("") } };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads a sub-composition restore whose file has a GSAP script", () => {
+    const { iframe, doc } = buildLiveIframe(host(`style="clip-path: inset(0px 40px 0px 0px);"`));
+    const reloadPreview = vi.fn();
+    const script = `<script>gsap.timeline().to("#target", { x: 10 });</script>`;
+    const scripted = (style: string) =>
+      sub(style).replace("</div></template>", `${script}</div></template>`);
+    const files = {
+      [SUB]: {
+        previous: scripted(`style="clip-path: inset(0px 40px 0px 0px)"`),
+        restored: scripted(""),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(doc.querySelector('[data-hf-id="hf-t"]')?.getAttribute("style")).toContain("clip-path");
+  });
+
   it("full-reloads when the restore touches a sub-comp, not the active comp", () => {
     const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
     const reloadPreview = vi.fn();