@hyperframes/studio 0.8.97 → 0.8.99

package/src/hooks/timelineTimingSync.ts

@@ -3,7 +3,11 @@
 // edit's undo history, and swapping the rewritten script into the live preview
 // without a full iframe reload when possible.
 import { type TimelineElement, usePlayerStore } from "../player/store/playerStore";
-import { applySoftReload, applySoftReloadFinalization } from "../utils/gsapSoftReload";
+import {
+  applySoftReload,
+  applySoftReloadFinalization,
+  extractGsapScriptText,
+} from "../utils/gsapSoftReload";
 import { furthestClipEndFromDocument } from "../player/lib/timelineElementHelpers";
 import type { RecordEditInput } from "../utils/studioFileHistory";
 import { patchDocumentRootDuration } from "./timelineEditingGsap";
@@ -15,6 +19,9 @@ import {
   rollbackOwnedMutation,
   type GsapMutationStatus,
 } from "./gsapMutationClient";
+import type { CutoverResult } from "../utils/sdkEditTransaction";
+import { findTimelineScript } from "@hyperframes/core/gsap-parser-acorn";
+import { walkCompositionDescendants } from "@hyperframes/parsers/hf-ids";
 import {
   serializeStudioFileMutations,
   type StudioProjectFileWriter,
@@ -365,6 +372,21 @@ export async function scaleGsapPositions(
   );
 }
 
+/** The GSAP sync a committed SDK timing write made, or null when its timeline script is unchanged. */
+export function sdkTimingGsapSync(
+  result: Extract<CutoverResult, { status: "committed" }>,
+): GsapMutationStatus | null {
+  const timelineText = (html: string) => {
+    const scripts: Element[] = [];
+    walkCompositionDescendants(new DOMParser().parseFromString(html, "text/html"), (el) => {
+      if (el.tagName.toLowerCase() === "script") scripts.push(el);
+    });
+    return findTimelineScript(scripts)?.textContent ?? null;
+  };
+  if (timelineText(result.before) === timelineText(result.after)) return null;
+  return { mutated: true, scriptText: extractGsapScriptText(result.after) };
+}
+
 /** Timing delta a single-clip edit applies to its GSAP tweens. */
 export type SingleClipGsapEdit =
   | { kind: "shift"; delta: number }
@@ -395,8 +417,9 @@ export function finishClipTimingFallback(input: {
   recordEdit: (edit: RecordEditInput) => Promise<void>;
   writeProjectFile: StudioProjectFileWriter;
   edit: SingleClipGsapEdit;
+  sdkGsap?: GsapMutationStatus | null;
 }): Promise<void> {
-  const { projectId, targetPath, domId, edit } = input;
+  const { projectId, targetPath, domId, edit, sdkGsap } = input;
   const timingChanged =
     edit.kind === "shift"
       ? edit.delta !== 0
@@ -418,8 +441,9 @@ export function finishClipTimingFallback(input: {
   return finishTimelineTimingFallback({
     iframe: input.iframe,
     reloadPreview: input.reloadPreview,
-    gsapMutation:
-      timingChanged && domId && projectId
+    gsapMutation: sdkGsap
+      ? () => Promise.resolve(sdkGsap)
+      : timingChanged && domId && projectId
         ? () =>
             foldGsapMutationIntoHistory({
               writeFile: input.writeProjectFile,
@@ -463,12 +487,24 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
   resolveChangePath: (element: TimelineElement) => string;
   /** Per-change GSAP mutation; return null to skip a change with no timing delta. */
   mutateChange: (change: C, changePath: string) => Promise<GsapMutationStatus> | null;
+  sdkGsap?: GsapMutationStatus | null;
 }): Promise<void> {
   const activePath = input.activeCompPath || "index.html";
   const otherFileChanged = input.changes.some(
     (change) => input.resolveChangePath(change.element) !== activePath,
   );
   const onGsapError = (err: unknown) => console.error(`[Timeline] ${input.errorLabel}`, err);
+  const { sdkGsap } = input;
+  if (sdkGsap) {
+    await finishTimelineTimingFallback({
+      iframe: input.iframe,
+      reloadPreview: input.reloadPreview,
+      gsapMutation: () => Promise.resolve(sdkGsap),
+      onGsapError,
+      rebindWhenUnmutated: !otherFileChanged,
+    });
+    return;
+  }
   await finishTimelineTimingFallback({
     iframe: input.iframe,
     reloadPreview: input.reloadPreview,

package/src/hooks/useAnimatedPropertyCommit.test.tsx

@@ -6,7 +6,9 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
-import { mountReactHarness } from "./domSelectionTestHarness";
+import { mountReactHarness, withInlineLayoutBox } from "./domSelectionTestHarness";
+import { writeSizeWithCrop } from "../components/editor/cropResize";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -362,3 +364,40 @@ describe("commitStaticSet group routing", () => {
     act(() => root.unmount());
   });
 });
+
+describe("useAnimatedPropertyCommit — a size write and its crop are one undo step", () => {
+  it.each([[{ width: 450 }], [{ x: 10, width: 450 }]])("%o on a static element", async (props) => {
+    const element = withInlineLayoutBox(document.createElement("div"));
+    element.id = "box";
+    element.style.cssText = "width: 300px; height: 200px; clip-path: inset(0px 60px 0px 0px)";
+    document.body.append(element);
+    const sel = { ...selection, element } as DomEditSelection;
+    const keys: unknown[] = [];
+    const land = async (options: { coalesceKey?: string }) => {
+      keys.push(options.coalesceKey);
+      element.style.width = "450px";
+    };
+    const mutation: CommitMutation = (_s, _m, options) => land(options);
+    mutation.batch = (_calls, options) => land(options);
+    let raw!: ReturnType<typeof useAnimatedPropertyCommit>["commitAnimatedProperties"];
+    function Harness() {
+      raw = useAnimatedPropertyCommit({
+        selectedGsapAnimations: [],
+        gsapCommitMutation: mutation,
+        addGsapAnimation: vi.fn(),
+        convertToKeyframes: vi.fn(),
+        previewIframeRef: { current: null },
+        bumpGsapCache: vi.fn(),
+      }).commitAnimatedProperties;
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+    const patch = vi.fn().mockResolvedValue(undefined);
+    await writeSizeWithCrop(sel, props, mutation, patch, (keyed) => raw(sel, props, keyed));
+
+    const cropKey = patch.mock.calls[0]![2].coalesceKey;
+    expect(patch.mock.calls[0]![1][0]).toMatchObject({ value: "inset(0px 90px 0px 0px)" });
+    expect(keys).toEqual([cropKey]);
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -431,8 +431,12 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
   const commitAnimatedProperties = useCallback(
     // This is the single routing boundary for set, keyframe, whole-tween, and first-group writes.
     // fallow-ignore-next-line complexity
-    async (selection: DomEditSelection, props: Record<string, number | string>): Promise<void> => {
-      if (!gsapCommitMutation) return;
+    async (
+      selection: DomEditSelection,
+      props: Record<string, number | string>,
+      commit: CommitMutation | null = gsapCommitMutation,
+    ): Promise<void> => {
+      if (!commit) return;
       const propEntries = Object.entries(props);
       if (propEntries.length === 0) return;
       const primaryProp = propEntries[0]![0];
@@ -490,7 +494,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
               ),
               pct,
               iframe,
-              { commitMutation: gsapCommitMutation },
+              { commitMutation: commit },
               `Edit ${primaryProp} (whole animation)`,
             );
             return;
@@ -503,7 +507,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
             primaryProp,
             selector,
             iframe,
-            gsapCommitMutation,
+            commit,
           );
           return;
         }
@@ -515,13 +519,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
         // must update the position set AND create a size set atomically rather
         // than contaminating the first set with a foreign property group.
         if (!elementHasKeyframes) {
-          await commitStaticSet(
-            selection,
-            propEntries,
-            selector,
-            selectedGsapAnimations,
-            gsapCommitMutation,
-          );
+          await commitStaticSet(selection, propEntries, selector, selectedGsapAnimations, commit);
           return;
         }
 
@@ -534,7 +532,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
             propEntries,
             selector,
             selectedGsapAnimations,
-            gsapCommitMutation,
+            commit,
           );
           return;
         }
@@ -566,7 +564,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
                   { percentage: 0, properties: { ...newProps, _auto: 1 } },
                   { percentage: pct, properties: newProps },
                 ];
-          await gsapCommitMutation(
+          await commit(
             selection,
             {
               type: "add-with-keyframes",

package/src/hooks/useCommitPreflightCapabilities.ts

@@ -5,10 +5,8 @@ import { dragEditOutcome, preflightGsapRotationIntercept } from "./gsapRuntimeBr
 import { preflightGsapResizeIntercept } from "./gsapResizePreflight";
 import { GSAP_EDIT_BLOCK_COPY, type GsapEditOutcome } from "./gsapEditOutcome";
 import { fetchParsedAnimations, parseCacheKey } from "./keyframeCacheAstLoad";
-import {
-  gsapSourceFileForSelection,
-  selectElementAnimationsOrRetry,
-} from "./useGsapAnimationFetchFallback";
+import { getAnimationsForElement } from "./gsapElementMatch";
+import { gsapSourceFileForSelection } from "./useGsapAnimationFetchFallback";
 
 interface CommitPreflight {
   offset: GsapEditOutcome;
@@ -23,13 +21,7 @@ function runCommitPreflights(
   group: boolean,
 ): CommitPreflight {
   const target = { id: selection.id ?? null, selector: selection.selector ?? null };
-  const matched = selectElementAnimationsOrRetry(
-    { animations: fileAnimations },
-    target,
-    selection.element,
-  );
-  // A file the server parsed with no tweens at all is a definitive answer here.
-  const animations = matched.kind === "resolved" ? matched.animations : [];
+  const animations = getAnimationsForElement(fileAnimations, target, selection.element);
   return {
     offset: dragEditOutcome(selection, animations, iframe, [], group),
     size: preflightGsapResizeIntercept(selection, animations, iframe),

package/src/hooks/useCropOverlay.ts

@@ -1,6 +1,9 @@
 import type { OverlayRect } from "../components/editor/domEditOverlayGeometry";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import { readElementCropInsets } from "../components/editor/domEditOverlayCrop";
+import {
+  isElementCropLifted,
+  readElementCropInsets,
+} from "../components/editor/domEditOverlayCrop";
 
 /** Selection-box crop hug: the outline that makes the selection box hug the
  *  element's committed inset crop. Crop is always-on (no mode) — the draggable
@@ -13,7 +16,10 @@ export function useCropOverlay(params: {
 }) {
   const { selection, overlayRect } = params;
 
-  const cropInsets = selection ? readElementCropInsets(selection.element) : null;
+  const cropInsets =
+    selection && !isElementCropLifted(selection.element)
+      ? readElementCropInsets(selection.element)
+      : null;
   const hasCropInsets = Boolean(
     cropInsets &&
     (cropInsets.top > 0 || cropInsets.right > 0 || cropInsets.bottom > 0 || cropInsets.left > 0),

package/src/hooks/useDomEditCommits.test.tsx

@@ -1204,7 +1204,12 @@ describe("useDomEditCommits style persist handling", () => {
     const fetchMock = stubPatchFetch({ ok: true, changed: true, matched: true });
     const { iframe, element } = createPreviewElement();
     const rendered = renderDomEditCommits(createSelection(element), iframe, {
-      onTrySdkPersist: async () => ({ status: "committed", version: "sdk-version-2" }),
+      onTrySdkPersist: async () => ({
+        status: "committed",
+        version: "sdk-version-2",
+        before: "",
+        after: "",
+      }),
     });
 
     try {

package/src/hooks/useDomEditCommits.ts

@@ -314,6 +314,7 @@ export function useDomEditCommits({
     handleDomAddTextField,
     handleDomRemoveTextField,
     stageElementPositionOffset,
+    commitPositionPatchToHtml,
     handleDomPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,

package/src/hooks/useDomEditPositionPatchCommit.ts

@@ -12,12 +12,12 @@ interface UseDomEditPositionPatchCommitParams {
   showToast: (message: string, tone?: "error" | "info") => void;
 }
 
-interface PositionPatchOptions {
+type PositionPatchOptions = {
   label: string;
   coalesceKey: string;
   coalesceMs?: number;
   skipRefresh?: boolean;
-}
+};
 
 export function useDomEditPositionPatchCommit({
   activeCompPath,

package/src/hooks/useDomEditSession.ts

@@ -230,6 +230,7 @@ export function useDomEditSession({
     handleDomAddTextField,
     handleDomRemoveTextField,
     stageElementPositionOffset,
+    commitPositionPatchToHtml,
     handleDomBoxSizeCommit,
     handleDomManualEditsReset,
     handleDomEditElementsDelete,
@@ -490,6 +491,7 @@ export function useDomEditSession({
     trackGsapInteractionFailure,
     stageElementPositionOffset,
     handleDomBoxSizeCommit,
+    commitPositionPatchToHtml,
     addGsapAnimation,
     convertToKeyframes,
     setArcPath,

package/src/hooks/useDomGeometryCommit.ts

@@ -136,6 +136,7 @@ export function useDomGeometryCommit({
     trackGsapInteractionFailure,
     stageElementPositionOffset,
     handleDomBoxSizeCommit: noDomBoxSizeRoute,
+    commitPositionPatchToHtml: commitWithFreshQueue,
     addGsapAnimation: gsap.addGsapAnimation,
     convertToKeyframes: gsap.convertToKeyframes,
     setArcPath: gsap.setArcPath,

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -13,6 +13,8 @@ import {
   readStudioRotation,
 } from "../components/editor/manualEdits";
 import { useDomGeometryCommits, type UseDomGeometryCommitsParams } from "./useDomGeometryCommits";
+import { DomEditCropHandles } from "../components/editor/DomEditCropHandles";
+import { withInlineLayoutBox } from "./domSelectionTestHarness";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -170,3 +172,113 @@ describe("useDomGeometryCommits element position offset", () => {
     unmount();
   });
 });
+
+describe("useDomGeometryCommits resize of a cropped element", () => {
+  it("saves the crop scaled per axis with the box in the resize's own commit", async () => {
+    const element = withInlineLayoutBox(document.createElement("div"));
+    element.id = "cropped";
+    element.style.cssText = "width: 300px; height: 200px; clip-path: inset(8px 60px 16px 30px)";
+    document.body.append(element);
+    const selection = {
+      id: "cropped",
+      selector: "#cropped",
+      element,
+    } as unknown as DomEditSelection;
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
+    const rect = { left: 0, top: 0, width: 300, height: 200, editScaleX: 1, editScaleY: 1 };
+    const host = document.createElement("div");
+    const crop = createRoot(host);
+    act(() =>
+      crop.render(
+        <DomEditCropHandles selection={selection} overlayRect={rect} onStyleCommit={vi.fn()} />,
+      ),
+    );
+
+    await commits().handleDomBoxSizeCommit(selection, { width: 450, height: 250 });
+
+    const scaled = "inset(10px 90px 20px 45px)";
+    expect(commitPositionPatchToHtml).toHaveBeenCalledTimes(1);
+    expect(commitPositionPatchToHtml.mock.calls[0]![1]).toContainEqual({
+      type: "inline-style",
+      property: "clip-path",
+      value: scaled,
+    });
+    act(() => crop.unmount());
+    expect(element.style.getPropertyValue("clip-path")).toBe(scaled);
+    unmount();
+  });
+
+  function mountCroppedSelection(id: string, authored: string) {
+    const element = withInlineLayoutBox(document.createElement("div"));
+    element.id = id;
+    element.style.cssText = authored;
+    document.body.append(element);
+    const selection = { id, selector: `#${id}`, element } as unknown as DomEditSelection;
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const mounted = mountCommits(commitPositionPatchToHtml);
+    const onStyleCommit = vi.fn((property: string, value: string) => {
+      element.style.setProperty(property, value);
+    });
+    const rect = { left: 0, top: 0, width: 300, height: 200, editScaleX: 1, editScaleY: 1 };
+    const crop = createRoot(document.body.appendChild(document.createElement("div")));
+    const draw = () =>
+      act(() =>
+        crop.render(
+          <DomEditCropHandles
+            selection={selection}
+            overlayRect={rect}
+            onStyleCommit={onStyleCommit}
+          />,
+        ),
+      );
+    draw();
+    const dragRightEdge = (by: number) => {
+      const handle = document.querySelector<HTMLButtonElement>('[aria-label="Crop right"]')!;
+      const press = (type: string, clientX: number) =>
+        act(() =>
+          handle.dispatchEvent(new PointerEvent(type, { bubbles: true, pointerId: 3, clientX })),
+        );
+      press("pointerdown", 100);
+      press("pointermove", 100 - by);
+      press("pointerup", 100 - by);
+    };
+    const resize = () =>
+      mounted.commits().handleDomBoxSizeCommit(selection, { width: 450, height: 300 });
+    const done = () => {
+      act(() => crop.unmount());
+      mounted.unmount();
+    };
+    return { element, onStyleCommit, draw, dragRightEdge, resize, done };
+  }
+
+  it("after an undo while still selected, the next crop drag starts from the undone crop", async () => {
+    const authored = "width: 300px; height: 200px; clip-path: inset(0px 60px 0px 0px)";
+    const h = mountCroppedSelection("undone", authored);
+    await h.resize();
+    // Undo writes the file's style attribute back onto the same live element.
+    h.element.setAttribute("style", authored);
+    h.draw();
+    h.dragRightEdge(20);
+
+    expect(h.onStyleCommit).toHaveBeenCalledWith("clip-path", "inset(0px 80px 0px 0px)");
+    h.done();
+    expect(h.element.style.getPropertyValue("clip-path")).toBe("inset(0px 80px 0px 0px)");
+  });
+
+  it("a crop drag right after a resize, with no render between, starts from the scaled crop", async () => {
+    const h = mountCroppedSelection(
+      "resized",
+      "width: 300px; height: 200px; clip-path: inset(0px 60px 0px 0px)",
+    );
+    await h.resize();
+    h.dragRightEdge(20);
+
+    expect(h.onStyleCommit).toHaveBeenCalledWith("clip-path", "inset(0px 110px 0px 0px)");
+    h.done();
+  });
+});

package/src/hooks/useDomGeometryCommits.ts

@@ -15,6 +15,7 @@ import {
   clearStudioRotation,
 } from "../components/editor/manualEdits";
 import { stageElementOffset } from "./elementOffsetStager";
+import { prepareCropResize } from "../components/editor/cropResize";
 import {
   buildPathOffsetPatches,
   buildBoxSizePatches,
@@ -103,7 +104,9 @@ export function useDomGeometryCommits({
       if (gsapFallback) return gsapFallback;
       const beforeSize = captureStudioBoxSize(selection.element);
       const beforeOffset = offset ? captureStudioPathOffset(selection.element) : null;
+      const stageCrop = prepareCropResize(selection.element);
       applyStudioBoxSize(selection.element, next);
+      const crop = stageCrop();
       // Anchored-corner resize (NW/NE/SW) also moves the element to keep the
       // opposite corner fixed. Apply the offset and emit BOTH patch sets in a
       // SINGLE commit: one persist = one undo entry, and there is no
@@ -111,6 +114,7 @@ export function useDomGeometryCommits({
       // offset is not (that frame was the release "jump"). Both builders read
       // the already-mutated live element, so concatenation is safe.
       const patches = buildBoxSizePatches(selection.element);
+      if (crop) patches.push(crop.patch);
       if (offset) {
         applyStudioPathOffset(selection.element, offset);
         patches.push(...buildPathOffsetPatches(selection.element));
@@ -121,6 +125,7 @@ export function useDomGeometryCommits({
       }).catch((error) => {
         restoreStudioBoxSize(selection.element, beforeSize);
         if (beforeOffset) restoreStudioPathOffset(selection.element, beforeOffset);
+        crop?.revert();
         throw error;
       });
     },

package/src/hooks/useElementLifecycleOps.multiDelete.test.tsx

@@ -92,7 +92,9 @@ describe("useElementLifecycleOps — deleting a canvas multi-selection", () => {
   it("reports a successful SDK delete as landed", async () => {
     const ops = mountDeleteOps({
       projectIdRef: { current: "p1" },
-      onTrySdkDelete: vi.fn(async () => ({ status: "committed", version: "v1" }) as const),
+      onTrySdkDelete: vi.fn(
+        async () => ({ status: "committed", version: "v1", before: "", after: "" }) as const,
+      ),
     });
 
     const target = { ...selectionFor("a"), hfId: "hf-a" };

package/src/hooks/useGsapAnimationFetchFallback.test.ts

@@ -1,13 +1,24 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it } from "vitest";
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
 import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
 import {
   gsapSourceFileForSelection,
   selectElementAnimationsOrRetry,
+  useGsapAnimationFetchFallback,
 } from "./useGsapAnimationFetchFallback";
+import { fetchParsedAnimations } from "./useGsapTweenCache";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 
+vi.mock("./useGsapTweenCache", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./useGsapTweenCache")>()),
+  fetchParsedAnimations: vi.fn(),
+}));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
 describe("gsapSourceFileForSelection", () => {
   it("uses the explicit target source instead of ambient selection state", () => {
     expect(
@@ -28,8 +39,11 @@ describe("selectElementAnimationsOrRetry", () => {
     expect(selectElementAnimationsOrRetry(null, target)).toEqual({ kind: "fetch-error" });
   });
 
-  it("signals cold (full retry budget) when the parse is reachable but has zero total animations", () => {
-    expect(selectElementAnimationsOrRetry(parsed([]), target)).toEqual({ kind: "cold" });
+  it("resolves to [] for a file with no tweens at all: the endpoint parses the file per request", () => {
+    expect(selectElementAnimationsOrRetry(parsed([]), target)).toEqual({
+      kind: "resolved",
+      animations: [],
+    });
   });
 
   it("resolves the matching animations from a warm parse", () => {
@@ -58,3 +72,30 @@ describe("selectElementAnimationsOrRetry", () => {
     expect(outcome).toEqual({ kind: "resolved", animations: [] });
   });
 });
+
+describe("useGsapAnimationFetchFallback", () => {
+  const fetchFor = (projectId: string) => {
+    let fetcher: ReturnType<typeof useGsapAnimationFetchFallback> | null = null;
+    function Probe() {
+      fetcher = useGsapAnimationFetchFallback(projectId);
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    act(() => root.unmount());
+    const element = document.createElement("div");
+    return fetcher!({ id: "puck-a", selector: "#puck-a", element } as unknown as DomEditSelection);
+  };
+
+  it("answers a GSAP-free file with one parse request, no retries", async () => {
+    vi.mocked(fetchParsedAnimations).mockReset().mockResolvedValue(parsed([]));
+    await expect(fetchFor("demo")()).resolves.toEqual([]);
+    expect(fetchParsedAnimations).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries a failed fetch once, then reports no animation", async () => {
+    vi.mocked(fetchParsedAnimations).mockReset().mockResolvedValue(null);
+    await expect(fetchFor("demo")()).resolves.toEqual([]);
+    expect(fetchParsedAnimations).toHaveBeenCalledTimes(2);
+  });
+});

package/src/hooks/useGsapAnimationFetchFallback.ts

@@ -3,13 +3,8 @@ import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
 
-// A cold parse is the initial-load race: the endpoint is reachable but its parse
-// isn't warm yet (zero total animations). It's worth waiting out (~600ms).
-const COLD_PARSE_RETRIES = 5;
-const COLD_PARSE_DELAY_MS = 120;
 // A hard fetch error (404/403/network/JSON failure → `fetchParsedAnimations`
-// returns null) is NOT a parse-warming race, so it shouldn't burn the full
-// cold-parse budget. One short retry covers a transient blip; beyond that the
+// returns null) gets one short retry for a transient blip; beyond that the
 // endpoint genuinely isn't serving this file, so fall through to "no animation".
 const FETCH_ERROR_RETRIES = 1;
 const FETCH_ERROR_DELAY_MS = 120;
@@ -18,17 +13,14 @@ const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve,
 
 /**
  * Outcome of resolving an element's animations from a single parse result.
- * - `resolved`: a definitive answer (matched animations, or `[]` when the parse
- *   is warm but this element has no animation — create a new one, don't retry).
+ * - `resolved`: a definitive answer. The endpoint parses the file on disk per request,
+ *   so no match, or a file with no tweens at all, means the element has no animation.
  * - `fetch-error`: `fetchParsedAnimations` returned null (HTTP/network/JSON
- *   failure) — retry briefly, not for the full cold-parse budget.
- * - `cold`: the parse came back reachable but with zero total animations — the
- *   initial-load warming race, worth the full cold-parse retry budget.
+ *   failure) — retry briefly.
  */
 export type ElementAnimationsOutcome =
   | { kind: "resolved"; animations: GsapAnimation[] }
-  | { kind: "fetch-error" }
-  | { kind: "cold" };
+  | { kind: "fetch-error" };
 
 export interface GsapAnimationFetchOptions {
   /** Refuse the edit when the parse endpoint is unavailable instead of treating it as no motion. */
@@ -41,26 +33,19 @@ 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`)
- * so the caller can apply the right retry budget to each.
- */
+/** Classify a parse result for one element: a hard fetch failure (`parsed === null`) or its animations. */
 export function selectElementAnimationsOrRetry(
   parsed: Pick<ParsedGsap, "animations"> | null,
   target: { id: string | null; selector: string | null },
   element?: Element | null,
 ): ElementAnimationsOutcome {
   if (!parsed) return { kind: "fetch-error" };
-  if (parsed.animations.length === 0) return { kind: "cold" };
   return {
     kind: "resolved",
     animations: getAnimationsForElement(parsed.animations, target, element),
   };
 }
 
-// Retry policy deliberately distinguishes cold parses from hard fetch errors.
-// fallow-ignore-next-line complexity
 async function fetchElementAnimationsWithRetry(
   projectId: string,
   gsapSourceFile: string,
@@ -69,25 +54,16 @@ async function fetchElementAnimationsWithRetry(
   failOnFetchError: boolean,
   fresh: boolean,
 ): Promise<GsapAnimation[]> {
-  let coldAttempts = 0;
-  let errorAttempts = 0;
-  for (;;) {
+  for (let errorAttempts = 0; ; errorAttempts++) {
     const parsed = await fetchParsedAnimations(projectId, gsapSourceFile, { fresh });
     fresh = false;
     const outcome = selectElementAnimationsOrRetry(parsed, target, element);
     if (outcome.kind === "resolved") return outcome.animations;
-    if (outcome.kind === "fetch-error") {
-      if (errorAttempts >= FETCH_ERROR_RETRIES) {
-        if (failOnFetchError) throw new Error("GSAP animation ownership could not be verified");
-        return [];
-      }
-      errorAttempts++;
-      await delay(FETCH_ERROR_DELAY_MS);
-      continue;
+    if (errorAttempts >= FETCH_ERROR_RETRIES) {
+      if (failOnFetchError) throw new Error("GSAP animation ownership could not be verified");
+      return [];
     }
-    if (coldAttempts >= COLD_PARSE_RETRIES) return [];
-    coldAttempts++;
-    await delay(COLD_PARSE_DELAY_MS);
+    await delay(FETCH_ERROR_DELAY_MS);
   }
 }