@hyperframes/studio 0.8.23 → 0.8.25

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -56,6 +56,7 @@ interface ExternalFileChangeCoordinatorOptions {
   readProjectFile: (path: string) => Promise<string>;
   onUseExternalFile?: (path: string, content: string) => void;
   resetSaveQueues?: () => void;
+  onAcceptedPersistedFileChange: (path: string) => void;
 }
 
 export interface ExternalFileChangeCoordinatorHandle {
@@ -126,6 +127,7 @@ export function useExternalFileChangeCoordinator({
   readProjectFile,
   onUseExternalFile,
   resetSaveQueues,
+  onAcceptedPersistedFileChange,
 }: ExternalFileChangeCoordinatorOptions): ExternalFileChangeCoordinatorHandle {
   const [blocked, setBlocked] = useState<ExternalFileChangeBlockedState | null>(null);
   const generationRef = useRef(0);
@@ -225,21 +227,24 @@ export function useExternalFileChangeCoordinator({
       const content = readFileChangeContent(payload);
       const token = readFileChangeWriteToken(payload);
       logReload("file-change", { path, token: token ?? null, hasContent: content != null });
-      if (consumeStudioWriteToken(token)) {
-        logReload("suppressed", { path, why: "own write token" });
-        return;
-      }
-      if (content != null && isSelfWriteEcho(path, content)) {
-        logReload("suppressed", { path, why: "own content echo" });
-        return;
-      }
-
       const identity = eventIdentity(path, payload);
       if (!allowDuplicate && identity != null && identity === lastEventIdentityRef.current) {
         logReload("suppressed", { path, why: "duplicate event" });
         return;
       }
       lastEventIdentityRef.current = identity;
+
+      const ownWriteToken = consumeStudioWriteToken(token);
+      const ownContentEcho = content != null && isSelfWriteEcho(path, content);
+      if (ownWriteToken || ownContentEcho) {
+        onAcceptedPersistedFileChange(path);
+        logReload("suppressed", {
+          path,
+          why: ownWriteToken ? "own write token" : "own content echo",
+        });
+        return;
+      }
+
       const generation = ++generationRef.current;
       const result = await drainPendingChanges();
       if (!mountedRef.current || generation !== generationRef.current) return;
@@ -258,6 +263,7 @@ export function useExternalFileChangeCoordinator({
         }
         if (!mountedRef.current || generation !== generationRef.current) return;
         setBlocked(null);
+        onAcceptedPersistedFileChange(path);
         reloadAcceptedGeneration(path);
         return;
       }
@@ -326,6 +332,7 @@ export function useExternalFileChangeCoordinator({
       persistFailureSnapshot,
       persistSnapshotInOrder,
       reloadAcceptedGeneration,
+      onAcceptedPersistedFileChange,
     ],
   );
 
@@ -369,12 +376,14 @@ export function useExternalFileChangeCoordinator({
       onUseExternalFile?.(path, external);
       await deleteConflictSnapshot?.(projectId, path);
       setBlocked(null);
+      onAcceptedPersistedFileChange(path);
       reloadAcceptedGeneration(path);
     },
     [
       deleteConflictSnapshot,
       discardPendingChanges,
       onUseExternalFile,
+      onAcceptedPersistedFileChange,
       projectId,
       readProjectFile,
       reloadAcceptedGeneration,

package/src/hooks/useGsapAnimationFetchFallback.test.ts

@@ -1,6 +1,18 @@
 import { describe, expect, it } from "vitest";
 import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
-import { selectElementAnimationsOrRetry } from "./useGsapAnimationFetchFallback";
+import {
+  gsapSourceFileForSelection,
+  selectElementAnimationsOrRetry,
+} from "./useGsapAnimationFetchFallback";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+
+describe("gsapSourceFileForSelection", () => {
+  it("uses the explicit target source instead of ambient selection state", () => {
+    expect(
+      gsapSourceFileForSelection({ sourceFile: "compositions/card.html" } as DomEditSelection),
+    ).toBe("compositions/card.html");
+  });
+});
 
 const anim = (targetSelector: string): GsapAnimation =>
   ({ id: targetSelector, targetSelector, properties: {} }) as unknown as GsapAnimation;

package/src/hooks/useGsapAnimationFetchFallback.ts

@@ -37,6 +37,10 @@ export interface GsapAnimationFetchOptions {
   fresh?: boolean;
 }
 
+export function gsapSourceFileForSelection(selection: DomEditSelection): string {
+  return selection.sourceFile || "index.html";
+}
+
 /**
  * Classify a parse result for one element. Differentiates a hard fetch failure
  * (`parsed === null`) from a warm-but-empty cold parse (`animations.length === 0`)
@@ -82,7 +86,7 @@ async function fetchElementAnimationsWithRetry(
   }
 }
 
-export function useGsapAnimationFetchFallback(projectId: string | null, gsapSourceFile: string) {
+export function useGsapAnimationFetchFallback(projectId: string | null) {
   return useCallback(
     (selection: DomEditSelection, options?: GsapAnimationFetchOptions) =>
       async (): Promise<GsapAnimation[]> => {
@@ -90,12 +94,12 @@ export function useGsapAnimationFetchFallback(projectId: string | null, gsapSour
         const target = { id: selection.id ?? null, selector: selection.selector ?? null };
         return fetchElementAnimationsWithRetry(
           projectId,
-          gsapSourceFile,
+          gsapSourceFileForSelection(selection),
           target,
           options?.failOnFetchError === true,
           options?.fresh === true,
         );
       },
-    [projectId, gsapSourceFile],
+    [projectId],
   );
 }

package/src/hooks/useGsapAnimationOps.test.tsx

@@ -0,0 +1,101 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { useGsapAnimationOps } from "./useGsapAnimationOps";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+type HookApi = ReturnType<typeof useGsapAnimationOps>;
+
+let cleanup: (() => void) | null = null;
+afterEach(() => {
+  cleanup?.();
+  cleanup = null;
+});
+
+const selection = { id: "box", selector: "#box" } as DomEditSelection;
+
+function renderOps(
+  commitMutationSafely: (...args: unknown[]) => Promise<void>,
+  commitMutation: (...args: unknown[]) => Promise<void> = vi.fn(async () => undefined),
+): HookApi {
+  const captured: { api: HookApi | null } = { api: null };
+  function Probe() {
+    captured.api = useGsapAnimationOps({
+      projectIdRef: { current: "project" },
+      activeCompPath: "index.html",
+      commitMutation,
+      commitMutationSafely,
+      showToast: vi.fn(),
+      sdkSession: null,
+      sdkDeps: null,
+    });
+    return null;
+  }
+
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(<Probe />));
+  cleanup = () => act(() => root.unmount());
+  if (!captured.api) throw new Error("hook did not initialize");
+  return captured.api;
+}
+
+function deferredCommit() {
+  let release!: () => void;
+  const promise = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  return { commitMutationSafely: vi.fn(() => promise), release };
+}
+
+describe("useGsapAnimationOps settlement", () => {
+  it.each([
+    ["update", (api: HookApi) => api.updateGsapMeta(selection, "anim-1", { duration: 2 })],
+    ["delete", (api: HookApi) => api.deleteGsapAnimation(selection, "anim-1")],
+  ])("keeps %s pending until the shared preview synchronizer settles", async (_name, run) => {
+    const deferred = deferredCommit();
+    const api = renderOps(deferred.commitMutationSafely);
+    let settled = false;
+
+    const resultPromise = run(api).then(() => {
+      settled = true;
+    });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+
+    deferred.release();
+    await resultPromise;
+    expect(settled).toBe(true);
+  });
+
+  it("soft-reloads the preview when adding an animation", async () => {
+    const commitMutation = vi.fn(async () => undefined);
+    const api = renderOps(
+      vi.fn(async () => undefined),
+      commitMutation,
+    );
+
+    await api.addGsapAnimation(selection, "from");
+
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      expect.objectContaining({ type: "add" }),
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+
+  it("soft-reloads the preview when deleting an animation", async () => {
+    const commitMutationSafely = vi.fn(async () => undefined);
+    const api = renderOps(commitMutationSafely);
+
+    await api.deleteGsapAnimation(selection, "anim-1");
+
+    expect(commitMutationSafely).toHaveBeenCalledWith(
+      selection,
+      expect.objectContaining({ type: "delete" }),
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+});

package/src/hooks/useGsapAnimationOps.ts

@@ -55,7 +55,7 @@ export function useGsapAnimationOps({
         );
         if (cutoverCommittedOrThrow(handled)) return;
       }
-      commitMutationSafely(
+      return commitMutationSafely(
         selection,
         { type: "update-meta", animationId, updates },
         { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta`, softReload: true },
@@ -77,10 +77,10 @@ export function useGsapAnimationOps({
         );
         if (cutoverCommittedOrThrow(handled)) return;
       }
-      commitMutationSafely(
+      return commitMutationSafely(
         selection,
         { type: "delete", animationId, stripStudioEdits: true },
-        { label: "Delete GSAP animation" },
+        { label: "Delete GSAP animation", softReload: true },
       );
     },
     [commitMutationSafely, activeCompPath, sdkSession, sdkDeps],
@@ -178,7 +178,7 @@ export function useGsapAnimationOps({
           properties: toDefaults[method] ?? { opacity: 1 },
           fromProperties: method === "fromTo" ? { opacity: 0 } : undefined,
         },
-        { label: `Add GSAP ${method} animation` },
+        { label: `Add GSAP ${method} animation`, softReload: true },
       );
     },
     [activeCompPath, commitMutation, projectIdRef, showToast, sdkSession, sdkDeps],

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -45,7 +45,10 @@ afterEach(() => {
   vi.clearAllMocks();
 });
 
-function mountResizeHandler(animations: GsapAnimation[]) {
+function mountResizeHandler(
+  animations: GsapAnimation[],
+  targetAnimations: GsapAnimation[] = animations,
+) {
   const element = document.createElement("div");
   const selection = { element, id: "clip", selector: "#clip" } as unknown as DomEditSelection;
   const fallback = vi.fn().mockResolvedValue(undefined);
@@ -66,7 +69,7 @@ function mountResizeHandler(animations: GsapAnimation[]) {
       previewIframeRef: { current: null },
       showToast: vi.fn(),
       bumpGsapCache: vi.fn(),
-      makeFetchFallback: () => vi.fn().mockResolvedValue(animations),
+      makeFetchFallback: () => vi.fn().mockResolvedValue(targetAnimations),
       trackGsapInteractionFailure: vi.fn(),
       handleDomBoxSizeCommit: fallback,
       addGsapAnimation: vi.fn(),
@@ -112,6 +115,31 @@ function mountGroupHandler({
 }
 
 describe("useGsapAwareEditing anchored resize", () => {
+  it("uses the explicit target's animations instead of the human selection cache", async () => {
+    const humanAnimation = { id: "human", propertyGroup: "scale" } as GsapAnimation;
+    const targetAnimation = { id: "target", propertyGroup: "size" } as GsapAnimation;
+    mocks.resize.mockResolvedValue({ status: "persisted" });
+    const h = mountResizeHandler([humanAnimation], [targetAnimation]);
+    const target = {
+      ...h.selection,
+      element: document.createElement("div"),
+      id: "agent-target",
+      selector: "#agent-target",
+    } as DomEditSelection;
+
+    await act(() => h.resize(target, { width: 300, height: 200 }));
+
+    expect(mocks.resize).toHaveBeenCalledWith(
+      target,
+      { width: 300, height: 200 },
+      [targetAnimation],
+      null,
+      expect.any(Function),
+      expect.any(Function),
+    );
+    act(() => h.root.unmount());
+  });
+
   it("rejects a blocked resize instead of falling through to a competing DOM write", async () => {
     mocks.resize.mockResolvedValue({ status: "blocked", reason: "source-uneditable" });
     const h = mountResizeHandler([]);

package/src/hooks/useGsapAwareEditing.ts

@@ -125,6 +125,14 @@ export function useGsapAwareEditing({
 }: UseGsapAwareEditingParams) {
   // ── GSAP-aware geometry commits ──
 
+  const getGsapAnimationsForSelection = useCallback(
+    (selection: DomEditSelection): GsapAnimation[] | Promise<GsapAnimation[]> => {
+      if (domEditSelection?.element === selection.element) return selectedGsapAnimations;
+      return makeFetchFallback(selection, { failOnFetchError: true })();
+    },
+    [domEditSelection, selectedGsapAnimations, makeFetchFallback],
+  );
+
   const handleGsapAwarePathOffsetCommit = useCallback(
     async (
       selection: DomEditSelection,
@@ -133,10 +141,14 @@ export function useGsapAwareEditing({
     ) => {
       if (gsapCommitMutation) {
         try {
+          const ownedAnimations = getGsapAnimationsForSelection(selection);
+          const targetAnimations = Array.isArray(ownedAnimations)
+            ? ownedAnimations
+            : await ownedAnimations;
           const outcome = await tryGsapDragIntercept(
             selection,
             next,
-            selectedGsapAnimations,
+            targetAnimations,
             previewIframeRef.current,
             gsapCommitMutation,
             makeFetchFallback(selection),
@@ -150,11 +162,11 @@ export function useGsapAwareEditing({
       }
     },
     [
-      selectedGsapAnimations,
       gsapCommitMutation,
       previewIframeRef,
       makeFetchFallback,
       trackGsapInteractionFailure,
+      getGsapAnimationsForSelection,
     ],
   );
 
@@ -286,7 +298,11 @@ export function useGsapAwareEditing({
       offset?: { x: number; y: number },
       restore: () => void = () => undefined,
     ) => {
-      const scaleRoute = selectedGsapAnimations.some((anim) => anim.propertyGroup === "scale");
+      const ownedAnimations = getGsapAnimationsForSelection(selection);
+      const targetAnimations = Array.isArray(ownedAnimations)
+        ? ownedAnimations
+        : await ownedAnimations;
+      const scaleRoute = targetAnimations.some((anim) => anim.propertyGroup === "scale");
       const selector = selectorFromSelection(selection);
       const hasLivePositionTween = selector
         ? hasNonHoldTweenForElement(
@@ -300,8 +316,8 @@ export function useGsapAwareEditing({
         next,
         offset: offset ?? null,
         scaleRoute,
-        animCount: selectedGsapAnimations.length,
-        animGroups: selectedGsapAnimations.map((a) => `${a.propertyGroup}:${a.method}`),
+        animCount: targetAnimations.length,
+        animGroups: targetAnimations.map((a) => `${a.propertyGroup}:${a.method}`),
       });
       return runGestureTransaction({
         element: selection.element,
@@ -325,7 +341,7 @@ export function useGsapAwareEditing({
               const outcome = await tryGsapResizeIntercept(
                 selection,
                 next,
-                selectedGsapAnimations,
+                targetAnimations,
                 previewIframeRef.current,
                 commitMutation,
                 makeFetchFallback(selection),
@@ -349,7 +365,7 @@ export function useGsapAwareEditing({
                 const dragOutcome = await tryGsapDragIntercept(
                   selection,
                   offset,
-                  selectedGsapAnimations,
+                  targetAnimations,
                   previewIframeRef.current,
                   commitMutation,
                   makeFetchFallback(selection),
@@ -377,11 +393,11 @@ export function useGsapAwareEditing({
     },
     [
       handleDomBoxSizeCommit,
-      selectedGsapAnimations,
       gsapCommitMutation,
       previewIframeRef,
       makeFetchFallback,
       trackGsapInteractionFailure,
+      getGsapAnimationsForSelection,
     ],
   );
 
@@ -389,6 +405,10 @@ export function useGsapAwareEditing({
     async (selection: DomEditSelection, next: { angle: number }) => {
       if (gsapCommitMutation) {
         try {
+          const ownedAnimations = getGsapAnimationsForSelection(selection);
+          const targetAnimations = Array.isArray(ownedAnimations)
+            ? ownedAnimations
+            : await ownedAnimations;
           // Single source of truth for rotation too: tryGsapRotationIntercept handles
           // tweened elements (keyframes) and static ones (a tl.set), so there's no
           // CSS-var fallback. Selectorless/computed source rejects so the gesture
@@ -396,7 +416,7 @@ export function useGsapAwareEditing({
           const outcome = await tryGsapRotationIntercept(
             selection,
             next.angle,
-            selectedGsapAnimations,
+            targetAnimations,
             previewIframeRef.current,
             gsapCommitMutation,
             makeFetchFallback(selection),
@@ -409,11 +429,11 @@ export function useGsapAwareEditing({
       }
     },
     [
-      selectedGsapAnimations,
       gsapCommitMutation,
       previewIframeRef,
       makeFetchFallback,
       trackGsapInteractionFailure,
+      getGsapAnimationsForSelection,
     ],
   );
 
@@ -507,6 +527,7 @@ export function useGsapAwareEditing({
   }, [commitMutation]);
 
   return {
+    getGsapAnimationsForSelection,
     handleGsapAwarePathOffsetCommit,
     handleGsapAwareGroupPathOffsetCommit,
     handleGsapAwareBoxSizeCommit,

package/src/hooks/useGsapSelectionHandlers.test.tsx

@@ -113,7 +113,9 @@ describe("useGsapSelectionHandlers save failures", () => {
       makeParams({ addGsapAnimation: vi.fn().mockRejectedValue(error), showToast }),
     );
 
-    act(() => rendered.handlers().handleGsapAddAnimation("to"));
+    act(() => {
+      void rendered.handlers().handleGsapAddAnimation("to");
+    });
     await flushRejection();
 
     expect(showToast).not.toHaveBeenCalled();

package/src/hooks/useGsapSelectionHandlers.ts

@@ -200,8 +200,13 @@ export function useGsapSelectionHandlers({
   const handleGsapDeleteAnimation = useCallback(
     (animId: string, selectionOverride?: DomEditSelection | null) => {
       const sel = resolveWriteSelection(selectionOverride);
-      if (!sel) return;
-      observeGsapMutation(deleteGsapAnimation(sel, animId), sel, "delete", "Delete GSAP animation");
+      if (!sel) return Promise.resolve(false);
+      return observeGsapMutation(
+        deleteGsapAnimation(sel, animId),
+        sel,
+        "delete",
+        "Delete GSAP animation",
+      );
     },
     [resolveWriteSelection, deleteGsapAnimation, observeGsapMutation],
   );
@@ -222,20 +227,25 @@ export function useGsapSelectionHandlers({
   );
 
   const handleGsapAddAnimation = useCallback(
-    (method: "to" | "from" | "set" | "fromTo") => {
-      if (!domEditSelection) return;
-      void addGsapAnimation(domEditSelection, method, usePlayerStore.getState().currentTime).catch(
-        (error) => {
-          trackGsapHandlerFailure(error, domEditSelection, "add", `Add GSAP ${method} animation`);
-        },
+    (method: "to" | "from" | "set" | "fromTo", selectionOverride?: DomEditSelection | null) => {
+      const selection = resolveWriteSelection(selectionOverride);
+      if (!selection) return Promise.resolve(false);
+      const landed = observeGsapMutation(
+        addGsapAnimation(selection, method, usePlayerStore.getState().currentTime),
+        selection,
+        "add",
+        `Add GSAP ${method} animation`,
       );
-      if (domEditSelection.element.hasAttribute("data-hf-studio-path-offset")) {
+      if (selection.element.hasAttribute("data-hf-studio-path-offset")) {
         // The reset owns rollback and the position commit already owns user and
         // telemetry reporting. This is only the fire-and-forget UI boundary.
-        void handleDomManualEditsReset(domEditSelection).catch(() => undefined);
+        void landed.then((didLand) => {
+          if (didLand) void handleDomManualEditsReset(selection).catch(() => undefined);
+        });
       }
+      return landed;
     },
-    [domEditSelection, addGsapAnimation, handleDomManualEditsReset, trackGsapHandlerFailure],
+    [resolveWriteSelection, addGsapAnimation, handleDomManualEditsReset, observeGsapMutation],
   );
 
   const handleGsapAddProperty = useCallback(

package/src/hooks/useRenderClipContent.test.ts

@@ -241,4 +241,31 @@ describe("useRenderClipContent", () => {
       });
     }
   });
+
+  it("forwards persisted content revision to mounted composition thumbnails", () => {
+    usePlayerStore.setState({
+      thumbnailMode: "adaptive",
+      timelineSessionEpoch: 7,
+      thumbnailContentRevision: 11,
+    });
+
+    const content = renderClipContent({
+      id: "nested",
+      tag: "div",
+      start: 0,
+      duration: 4,
+      track: 0,
+      compositionSrc: "compositions/nested.html",
+    });
+
+    expect(isValidElement(content)).toBe(true);
+    if (isValidElement(content)) {
+      expect(content.type).toBe(CompositionThumbnail);
+      expect(content.props).toMatchObject({
+        projectId: "my-project",
+        sessionEpoch: 7,
+        contentRevision: 11,
+      });
+    }
+  });
 });

package/src/hooks/useRenderClipContent.ts

@@ -110,6 +110,7 @@ export function useRenderClipContent({
   const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
   const effectiveMode = effectiveThumbnailMode(thumbnailMode);
   const sessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
+  const contentRevision = usePlayerStore((s) => s.thumbnailContentRevision);
   return useCallback(
     // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
     // fallow-ignore-next-line complexity
@@ -153,6 +154,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
+          contentRevision,
           priority: context.priority,
           rich: context.rich,
         });
@@ -179,6 +181,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
+          contentRevision,
           priority: context.priority,
           rich: context.rich,
         });
@@ -232,6 +235,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
+          contentRevision,
           priority: context.priority,
           rich: context.rich,
         });
@@ -246,6 +250,7 @@ export function useRenderClipContent({
       effectiveTimelineDuration,
       effectiveMode,
       sessionEpoch,
+      contentRevision,
     ],
   );
 }

package/src/hooks/useStudioExternalFileChanges.ts

@@ -1,4 +1,5 @@
 import { useCallback, type MutableRefObject } from "react";
+import { usePlayerStore } from "../player/store/playerStore";
 import {
   deleteExternalConflictSnapshot,
   loadExternalConflictSnapshot,
@@ -48,6 +49,9 @@ export function useStudioExternalFileChanges({
 }: UseStudioExternalFileChangesOptions) {
   const { flushPendingSourceSave, discardPendingSourceSave } = fileManager;
   const { drainPendingDomEditSaves, resetDomEditSaveQueueBreaker } = previewPersistence;
+  const bumpThumbnailContentRevision = usePlayerStore(
+    (state) => state.bumpThumbnailContentRevision,
+  );
   const drainPendingChanges = useCallback(async () => {
     const source = await flushPendingSourceSave();
     if (source.status !== "clean") return source;
@@ -77,5 +81,6 @@ export function useStudioExternalFileChanges({
     readProjectFile: fileManager.readProjectFile,
     onUseExternalFile: fileManager.updateEditingFileContent,
     resetSaveQueues: resetDomEditSaveQueueBreaker,
+    onAcceptedPersistedFileChange: bumpThumbnailContentRevision,
   });
 }