@hyperframes/studio 0.8.97 → 0.8.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.97",
+  "version": "0.8.98",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.97",
-    "@hyperframes/parsers": "0.8.97",
-    "@hyperframes/player": "0.8.97",
-    "@hyperframes/shader-transitions": "0.8.97",
-    "@hyperframes/sdk": "0.8.97",
-    "@hyperframes/studio-server": "0.8.97"
+    "@hyperframes/core": "0.8.98",
+    "@hyperframes/parsers": "0.8.98",
+    "@hyperframes/player": "0.8.98",
+    "@hyperframes/sdk": "0.8.98",
+    "@hyperframes/shader-transitions": "0.8.98",
+    "@hyperframes/studio-server": "0.8.98"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.97"
+    "@hyperframes/producer": "0.8.98"
   },
   "peerDependencies": {
     "react": "19",
@@ -93,6 +93,7 @@
     "build": "vite build && tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:edit-accuracy": "bun tests/e2e/edit-accuracy/run.mjs",
     "test:webmcp-edit-loop": "node tests/e2e/webmcp-edit-loop.mjs",
     "test:timeline-virtualization": "TIMELINE_ROW_VIRTUALIZATION=on TIMELINE_ELEMENT_COUNT=50000 node tests/e2e/timeline-virtualization.mjs",
     "test:watch": "vitest",

package/src/components/EditorShell.tsx

@@ -18,6 +18,7 @@ import type { GestureRecordingState } from "./editor/GestureRecordControl";
 import { useTimelineSelectionPreviewSync } from "../hooks/useTimelineSelectionPreviewSync";
 import { StudioAgentTools } from "../webmcp/StudioAgentTools";
 import type { TimelineDropPlacement } from "../player/components/timelineCallbacks";
+import type { TimelineProps } from "../player/components/TimelineTypes";
 import { Dock } from "./dock/Dock";
 
 type RenderClipContent = (
@@ -57,6 +58,7 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
   onPasteClip: () => Promise<void>;
   onDuplicateClip: () => Promise<boolean>;
   canPasteClip: () => boolean;
+  clipMenuItems?: TimelineProps["clipMenuItems"];
   setCompIdToSrc: (map: Map<string, string>) => void;
   setCompositionLoading: (loading: boolean) => void;
   shouldShowMotionPath: boolean;
@@ -105,6 +107,7 @@ export function EditorShell({
   onPasteClip,
   onDuplicateClip,
   canPasteClip,
+  clipMenuItems,
   setCompIdToSrc,
   setCompositionLoading,
   shouldShowMotionPath,
@@ -201,6 +204,7 @@ export function EditorShell({
               onPasteClip={onPasteClip}
               onDuplicateClip={onDuplicateClip}
               canPasteClip={canPasteClip}
+              clipMenuItems={clipMenuItems}
               previewOverlay={
                 <PreviewOverlays
                   shouldShowMotionPath={shouldShowMotionPath}
@@ -244,6 +248,7 @@ interface EditorShellBodyProps {
   onPasteClip: () => Promise<void>;
   onDuplicateClip: () => Promise<boolean>;
   canPasteClip: () => boolean;
+  clipMenuItems?: TimelineProps["clipMenuItems"];
 }
 
 function EditorShellBody({
@@ -264,6 +269,7 @@ function EditorShellBody({
   onPasteClip,
   onDuplicateClip,
   canPasteClip,
+  clipMenuItems,
 }: EditorShellBodyProps) {
   const { compositionStack, updateCompositionStack, containerRef } = useNLEContext();
 
@@ -316,6 +322,7 @@ function EditorShellBody({
             onPasteClip={onPasteClip}
             onDuplicateClip={onDuplicateClip}
             canPasteClip={canPasteClip}
+            clipMenuItems={clipMenuItems}
             onSelectTimelineElement={onSelectTimelineElement}
             timelineFooter={
               captionEditMode ? (

package/src/components/editor/DomEditOverlay.tsx

@@ -161,8 +161,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const groupGestureRef = useRef<GroupGestureState | null>(null);
   const blockedMoveRef = useRef<BlockedMoveState | null>(null);
   const suppressNextBoxClickRef = useRef(false);
-  const suppressNextBoxMouseDownRef = useRef(false);
-  const suppressNextOverlayMouseDownRef = useRef(false);
   const snapGuidesRef = useRef<SnapGuidesState | null>(null);
   const rafPausedRef = useRef(false);
 
@@ -329,15 +327,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
 
   const handleOverlayMouseDown = (event: React.MouseEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement) return;
-    if (suppressNextOverlayMouseDownRef.current) {
-      logSelect("mousedown-suppressed", { shift: event.shiftKey });
-      suppressNextOverlayMouseDownRef.current = false;
-      suppressNextBoxMouseDownRef.current = false;
-      suppressNextBoxClickRef.current = false;
-      event.preventDefault();
-      event.stopPropagation();
-      return;
-    }
     const target = event.target as HTMLElement | null;
     const onBox = Boolean(target?.closest('[data-dom-edit-selection-box="true"]'));
     logSelect("mousedown", { shift: event.shiftKey, onBox });
@@ -346,10 +335,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     // extend beyond the composition rect into the gray zone, and users need
     // to select/deselect them by clicking there.
     onCanvasMouseDown(event, { hoverSelection: hoverSelectionRef.current });
-    if (event.shiftKey) {
-      suppressNextBoxMouseDownRef.current = true;
-      suppressNextBoxClickRef.current = true;
-    }
   };
 
   // fallow-ignore-next-line complexity
@@ -373,8 +358,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       if (!candidate) return;
       event.preventDefault();
       event.stopPropagation();
-      suppressNextOverlayMouseDownRef.current = true;
-      suppressNextBoxMouseDownRef.current = true;
       suppressNextBoxClickRef.current = true;
       onSelectionChangeRef.current(candidate, { additive: true });
       return;
@@ -419,7 +402,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
         // so those elements were always selectable once the band could begin.
         event.preventDefault();
         event.stopPropagation();
-        suppressNextOverlayMouseDownRef.current = true;
         marquee.begin(event);
         return;
       }
@@ -437,13 +419,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     onCanvasMouseDown(event, { hoverSelection: hoverSelectionRef.current });
   };
 
-  const suppressBoxMouseDown = (e: React.MouseEvent) => {
-    if (!suppressNextBoxMouseDownRef.current) return;
-    suppressNextBoxMouseDownRef.current = false;
-    e.preventDefault();
-    e.stopPropagation();
-  };
-
   // Right-click state + handler: select the element under the pointer (if
   // needed), then open the menu; closes when the selection moves off-target.
   const { contextMenu, closeContextMenu, handleContextMenu } = useCanvasContextMenuState({
@@ -509,7 +484,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           allowBodyDrag={bodyDrag}
           groupCanMove={groupCanMove}
           gestures={gestures}
-          onBoxMouseDown={suppressBoxMouseDown}
           onBoxClick={handleBoxClick}
         />
       )}
@@ -528,7 +502,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           groupSelectionCount={groupSelections.length}
           gestures={gestures}
           onStyleCommit={onStyleCommitRef.current}
-          onBoxMouseDown={suppressBoxMouseDown}
           onBoxClick={handleBoxClick}
         />
       )}

package/src/components/editor/DomEditSelectionChrome.test.tsx

@@ -56,7 +56,6 @@ describe("DomEditSelectionChrome crop composition", () => {
           groupSelectionCount={0}
           gestures={{ startGesture: vi.fn() } as never}
           onStyleCommit={vi.fn()}
-          onBoxMouseDown={vi.fn()}
           onBoxClick={vi.fn()}
         />,
       );
@@ -112,7 +111,6 @@ describe("DomEditSelectionChrome crop composition", () => {
           groupSelectionCount={0}
           gestures={{ startGesture: vi.fn() } as never}
           onStyleCommit={vi.fn()}
-          onBoxMouseDown={vi.fn()}
           onBoxClick={vi.fn()}
         />,
       );
@@ -173,7 +171,6 @@ describe("DomEditSelectionChrome while editing text", () => {
           groupSelectionCount={0}
           gestures={{ startGesture: vi.fn() } as never}
           onStyleCommit={vi.fn()}
-          onBoxMouseDown={vi.fn()}
           onBoxClick={vi.fn()}
           inlineText={{ editing, startFromPress: vi.fn() }}
         />,
@@ -258,7 +255,6 @@ describe("DomEditSelectionChrome with body drag off", () => {
           selectionKey="box"
           groupSelectionCount={0}
           gestures={gestures as never}
-          onBoxMouseDown={vi.fn()}
           onBoxClick={vi.fn()}
         />,
       );
@@ -313,7 +309,6 @@ describe("DomEditSelectionChrome with body drag off", () => {
           allowBodyDrag={false}
           groupCanMove
           gestures={gestures as never}
-          onBoxMouseDown={vi.fn()}
           onBoxClick={vi.fn()}
         />,
       );

package/src/components/editor/DomEditSelectionChrome.tsx

@@ -62,7 +62,6 @@ interface DomEditGroupChromeProps {
   allowBodyDrag: boolean;
   groupCanMove: boolean;
   gestures: GestureHandlers;
-  onBoxMouseDown: (e: React.MouseEvent) => void;
   onBoxClick: (event: React.MouseEvent<HTMLDivElement>) => void;
 }
 
@@ -75,7 +74,6 @@ export function DomEditGroupChrome({
   allowBodyDrag,
   groupCanMove,
   gestures,
-  onBoxMouseDown,
   onBoxClick,
 }: DomEditGroupChromeProps) {
   const canManipulate = allowCanvasMovement && !usePreviewReadOnly();
@@ -108,7 +106,6 @@ export function DomEditGroupChrome({
           if (!canManipulate || !allowBodyDrag || (e.shiftKey && !groupCanMove)) return;
           gestures.startGroupDrag(e);
         }}
-        onMouseDown={onBoxMouseDown}
         onClick={onBoxClick}
       />
     </>
@@ -128,7 +125,6 @@ interface DomEditSelectionChromeProps {
   groupSelectionCount: number;
   gestures: GestureHandlers;
   onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
-  onBoxMouseDown: (e: React.MouseEvent) => void;
   onBoxClick: (event: React.MouseEvent<HTMLDivElement>) => void;
   /** The canvas' text-editing session: what opens one, and whether one is open. */
   inlineText?: {
@@ -157,7 +153,6 @@ export function DomEditSelectionChrome({
   groupSelectionCount,
   gestures,
   onStyleCommit,
-  onBoxMouseDown,
   onBoxClick,
   inlineText,
 }: DomEditSelectionChromeProps) {
@@ -225,7 +220,6 @@ export function DomEditSelectionChrome({
             }
             if (!e.shiftKey) gestures.startBlockedMove(e, selection);
           }}
-          onMouseDown={onBoxMouseDown}
           onClick={onBoxClick}
         >
           {cropOutlineInsetPx && (

package/src/components/editor/clickAfterPreventedPress.test.tsx

@@ -0,0 +1,122 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, expect, it, vi } from "vitest";
+import { makeSelection } from "../../hooks/domSelectionTestHarness";
+import type { DomEditSelection } from "./domEditing";
+import "./domEditOverlayTestMocks";
+import { DomEditOverlay } from "./DomEditOverlay";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+HTMLElement.prototype.setPointerCapture ??= () => {};
+HTMLElement.prototype.releasePointerCapture ??= () => {};
+
+const pointTarget = vi.hoisted(() => ({ current: null as HTMLElement | null }));
+const rect = vi.hoisted(() => ({ current: null as Record<string, number> | null }));
+vi.mock("../../utils/studioPreviewHelpers", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../utils/studioPreviewHelpers")>()),
+  getPreviewTargetFromPointer: () => pointTarget.current,
+}));
+vi.mock("./useDomEditOverlayRects", () => ({
+  useDomEditOverlayRects: () => ({
+    overlayRect: rect.current,
+    overlayRectRef: rect,
+    setOverlayRect: () => undefined,
+    hoverRect: null,
+    groupOverlayItems: [],
+    groupOverlayItemsRef: { current: [] },
+    setGroupOverlayItems: () => undefined,
+    childRects: [],
+  }),
+}));
+
+let root: Root;
+const onCanvasMouseDown = vi.fn();
+const onSelectionChange = vi.fn();
+
+function mount() {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  const element = document.createElement("h1");
+  document.body.append(element);
+  return { host, element, hover: makeSelection("Title", element) };
+}
+
+function render(
+  hoverSelection: DomEditSelection | null,
+  selection: DomEditSelection | null = null,
+) {
+  act(() =>
+    root.render(
+      <DomEditOverlay
+        iframeRef={{ current: document.createElement("iframe") }}
+        activeCompositionPath={null}
+        selection={selection}
+        hoverSelection={hoverSelection}
+        onCanvasMouseDown={onCanvasMouseDown}
+        onCanvasPointerMove={() => Promise.resolve(null)}
+        onCanvasPointerLeave={() => undefined}
+        onSelectionChange={onSelectionChange}
+        onBlockedMove={() => undefined}
+        onPathOffsetCommit={() => undefined}
+        onGroupPathOffsetCommit={() => undefined}
+        onBoxSizeCommit={() => undefined}
+        onRotationCommit={() => undefined}
+        onMarqueeSelect={() => undefined}
+      />,
+    ),
+  );
+}
+
+// Like Chrome: a default-prevented pointerdown sends no compatibility mousedown.
+function press(target: Element, shiftKey = false) {
+  const init = { bubbles: true, cancelable: true, button: 0, pointerId: 1, shiftKey };
+  const down = new PointerEvent("pointerdown", init);
+  act(() => void target.dispatchEvent(down));
+  if (!down.defaultPrevented)
+    act(() => void target.dispatchEvent(new MouseEvent("mousedown", init)));
+  act(() => void target.dispatchEvent(new PointerEvent("pointerup", init)));
+  act(() => void target.dispatchEvent(new MouseEvent("click", init)));
+}
+
+afterEach(() => {
+  act(() => root.unmount());
+  onCanvasMouseDown.mockClear();
+  onSelectionChange.mockClear();
+  pointTarget.current = null;
+  rect.current = null;
+  document.body.innerHTML = "";
+});
+
+it.each([
+  ["a press on empty canvas", false],
+  ["a shift+click add", true],
+])("after %s, the next click on an element selects it", (_, shiftFirst) => {
+  const { host, element, hover } = mount();
+  const overlay = () => host.firstElementChild!;
+
+  pointTarget.current = shiftFirst ? element : null;
+  render(shiftFirst ? hover : null);
+  press(overlay(), shiftFirst);
+  expect(onCanvasMouseDown).not.toHaveBeenCalled();
+
+  pointTarget.current = element;
+  render(hover);
+  press(overlay());
+  expect(onCanvasMouseDown).toHaveBeenCalledTimes(1);
+});
+
+it("a shift+click on a selected box that cannot move toggles it once", () => {
+  const { host, element, hover } = mount();
+  hover.capabilities.canApplyManualOffset = false;
+  rect.current = { left: 20, top: 30, width: 100, height: 40, editScaleX: 1, editScaleY: 1 };
+  pointTarget.current = element;
+  render(hover, hover);
+
+  press(host.querySelector('[data-dom-edit-selection-box="true"]')!, true);
+
+  expect(onSelectionChange).toHaveBeenCalledTimes(1);
+  expect(onCanvasMouseDown).not.toHaveBeenCalled();
+});

package/src/components/editor/propertyPanelFont.test.tsx

@@ -2,13 +2,32 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { FontFamilyField } from "./propertyPanelFont";
+import { sortFontOptions } from "./propertyPanelHelpers";
+
+vi.mock("./propertyPanelHelpers", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./propertyPanelHelpers")>();
+  return { ...actual, sortFontOptions: vi.fn(actual.sortFontOptions) };
+});
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+// The font APIs are stubbed and every family is off the Google lists, so no test reaches the network.
+beforeEach(() => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => ({
+      ok: true,
+      json: async () => ({ fonts: url.includes("google") ? ["Roboto Slab"] : ["Arial"] }),
+    })),
+  );
+});
+
 afterEach(() => {
   document.body.innerHTML = "";
+  document.head.innerHTML = "";
+  vi.unstubAllGlobals();
 });
 
 describe("FontFamilyField flat trigger", () => {
@@ -17,14 +36,38 @@ describe("FontFamilyField flat trigger", () => {
     document.body.append(host);
     const root = createRoot(host);
     act(() => {
-      root.render(
-        <FontFamilyField flat value="JetBrains Mono" importedFonts={[]} onCommit={vi.fn()} />,
-      );
+      root.render(<FontFamilyField flat value="Georgia" importedFonts={[]} onCommit={vi.fn()} />);
     });
     const trigger = host.querySelector<HTMLButtonElement>('[data-flat-font-trigger="true"]');
     expect(trigger).not.toBeNull();
     expect(trigger?.className).not.toContain("border-neutral-800");
-    expect(host.textContent).toContain("JetBrains Mono");
+    expect(host.textContent).toContain("Georgia");
     act(() => root.unmount());
   });
 });
+
+describe("FontFamilyField font list", () => {
+  it("builds the list only while the dropdown is open", async () => {
+    vi.mocked(sortFontOptions).mockClear();
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const render = (value: string) =>
+      root.render(<FontFamilyField flat value={value} importedFonts={[]} onCommit={vi.fn()} />);
+    try {
+      await act(async () => render("Arial"));
+      // The font lists arrive and the value changes while the dropdown is closed, as during a drag.
+      await act(async () => render("Georgia"));
+      expect(sortFontOptions).not.toHaveBeenCalled();
+
+      const trigger = host.querySelector<HTMLButtonElement>('[data-flat-font-trigger="true"]');
+      await act(async () => trigger?.click());
+      expect(sortFontOptions).toHaveBeenCalledTimes(1);
+      expect(host.textContent).toContain("Roboto Slab");
+      expect(document.head.querySelector('link[href*="fonts.googleapis.com"]')).toBeNull();
+    } finally {
+      act(() => root.unmount());
+      host.remove();
+    }
+  });
+});

package/src/components/editor/propertyPanelFont.tsx

@@ -276,6 +276,7 @@ export function FontFamilyField({
   );
 
   const options = useMemo(() => {
+    if (!open) return [];
     const documentFonts = collectDocumentFontFamilies();
     const googleSet = new Set(googleFonts.map((f) => f.toLowerCase()));
     const taggedLocal = localFonts.map(
@@ -294,7 +295,7 @@ export function FontFamilyField({
         ...DEFAULT_FONT_FAMILIES.map((f): FontOption => ({ family: f, source: "System" })),
       ]),
     );
-  }, [currentFamily, googleFonts, localFonts, projectFontAssets]);
+  }, [open, currentFamily, googleFonts, localFonts, projectFontAssets]);
 
   const filteredOptions = useMemo(() => {
     const matches = options.filter((o) => fontMatchesQuery(o.family, query));

package/src/components/editor/shiftDragAxisLock.test.tsx

@@ -193,7 +193,6 @@ describe("a shift press on a selected box starts the drag", () => {
         selectionKey="box"
         groupSelectionCount={0}
         gestures={spies as never}
-        onBoxMouseDown={vi.fn()}
         onBoxClick={vi.fn()}
       />
     ));
@@ -207,7 +206,6 @@ describe("a shift press on a selected box starts the drag", () => {
         allowBodyDrag
         groupCanMove={groupCanMove}
         gestures={spies as never}
-        onBoxMouseDown={vi.fn()}
         onBoxClick={vi.fn()}
       />
     ));

package/src/components/nle/TimelinePane.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import { Timeline } from "../../player";
 import type { TimelineElement, TimelineTimeRange } from "../../player";
+import type { TimelineProps } from "../../player/components/TimelineTypes";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { AudioMeterStrip } from "./AudioMeterStrip";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
@@ -45,6 +46,7 @@ export interface TimelinePaneProps {
   onPasteClip?: () => Promise<void>;
   onDuplicateClip?: () => Promise<boolean>;
   canPasteClip?: () => boolean;
+  clipMenuItems?: TimelineProps["clipMenuItems"];
 }
 
 export function TimelinePane({
@@ -64,6 +66,7 @@ export function TimelinePane({
   onPasteClip,
   onDuplicateClip,
   canPasteClip,
+  clipMenuItems,
 }: TimelinePaneProps) {
   const {
     seek,
@@ -119,6 +122,7 @@ export function TimelinePane({
               onPasteClip={onPasteClip}
               onDuplicateClip={onDuplicateClip}
               canPasteClip={canPasteClip}
+              clipMenuItems={clipMenuItems}
             />
           </div>
           <AudioMeterStrip />

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