@hyperframes/studio 0.8.121 → 0.8.123

package/src/player/components/useTimelineClipDrag.ts

@@ -12,6 +12,8 @@ import {
   type TimelineGroupResizeSession,
 } from "./timelineGroupEditing";
 import { collectTimelineSnapTargets, type TimelineSnapTarget } from "./timelineSnapping";
+import { getTimelineGridStep, rulerFrameRate } from "./timelineRulerGeometry";
+import { setPreviewFrame } from "../store/previewFrameStore";
 import type { StackingPatch } from "./timelineStackingSync";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import {
@@ -76,8 +78,6 @@ interface UseTimelineClipDragInput {
   onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;
   onLinkEdit?: TimelineEditCallbacks["onLinkEdit"];
-  /** Seeks the preview; a trim shows the frame at its dragged edge. */
-  onSeek?: (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => void;
   setShowPopover: (show: boolean) => void;
   /** Stable ref to the range selection setter — wired after mount to break circular dependency. */
   setRangeSelectionRef: React.RefObject<((sel: null) => void) | null>;
@@ -108,7 +108,6 @@ export function useTimelineClipDrag({
   onResizeElements,
   onBlockedEditAttempt,
   onLinkEdit,
-  onSeek,
   setShowPopover,
   setRangeSelectionRef,
   readZIndex,
@@ -165,15 +164,11 @@ export function useTimelineClipDrag({
   const dragAudioTracksRef = useRef<ReadonlySet<number> | null>(null);
 
   const buildSnapTargets = useCallback(
-    (
-      excludeElementKey: string | null,
-      includeBeats: boolean,
-      includePlayhead = true,
-    ): TimelineSnapTarget[] => {
+    (excludeElementKey: string | null, includeBeats: boolean): TimelineSnapTarget[] => {
       // Magnet off ⇒ no targets and no scan; do NOT cache so a mid-gesture toggle
       // back on starts scanning immediately (preserves the existing skip).
       if (!snapContextRef.current.enabled) return [];
-      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}|${includePlayhead ? 1 : 0}`;
+      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}`;
       const cached = snapTargetsCacheRef.current.get(cacheKey);
       if (cached) return cached;
       const targets = collectTimelineSnapTargets({
@@ -181,13 +176,18 @@ export function useTimelineClipDrag({
         playheadTime: usePlayerStore.getState().currentTime,
         beatTimes: includeBeats ? snapContextRef.current.beatTimes : [],
         excludeElementKey,
-        includePlayhead,
       });
       snapTargetsCacheRef.current.set(cacheKey, targets);
       return targets;
     },
     [],
   );
+  // The ruler's line spacing at the current zoom; 0 with the magnet off, like the targets.
+  const snapGridStep = useCallback(() => {
+    if (!snapContextRef.current.enabled) return 0;
+    const frameRate = rulerFrameRate(usePlayerStore.getState().timeDisplayMode);
+    return getTimelineGridStep(durationRef.current, ppsRef.current, frameRate);
+  }, [durationRef, ppsRef]);
 
   const [draggedClip, setDraggedClipState] = useState<DraggedClipState | null>(null);
   const draggedClipRef = useRef<DraggedClipState | null>(null);
@@ -285,10 +285,6 @@ export function useTimelineClipDrag({
   onResizeElementRef.current = onResizeElement;
   const onResizeElementsRef = useRef(onResizeElements);
   onResizeElementsRef.current = onResizeElements;
-  const onSeekRef = useRef(onSeek);
-  onSeekRef.current = onSeek;
-  // Playhead time before the first trim preview seek; restored when the gesture ends.
-  const trimSeekOriginRef = useRef<number | null>(null);
   const readZIndexRef = useRef(readZIndex);
   readZIndexRef.current = readZIndex;
   const onStackingPatchesRef = useRef(onStackingPatches);
@@ -325,6 +321,7 @@ export function useTimelineClipDrag({
         selectedKeys: gestureSelectedKeysRef.current,
         buildSnapTargets,
         audioTracks: dragAudioTracksRef.current,
+        gridStep: snapGridStep(),
       });
     },
     [
@@ -335,6 +332,7 @@ export function useTimelineClipDrag({
       trackInsertLayoutRef,
       rowGeometryRef,
       buildSnapTargets,
+      snapGridStep,
     ],
   );
 
@@ -349,15 +347,11 @@ export function useTimelineClipDrag({
         buildSnapTargets,
         elements: elementsRef.current,
         gestureKeys: gestureSelectedKeysRef.current,
+        gridStep: snapGridStep(),
       });
-      trimSeekOriginRef.current ??= usePlayerStore.getState().currentTime;
       const setResizeState = (v: ResizePreviewResult) => {
-        // A trim never changes the play state: keepPlaying lets seek() decide,
-        // and it only resumes playback if it was already playing.
-        onSeekRef.current?.(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration), {
-          keepPlaying: true,
-          follow: false,
-        });
+        // The preview shows the dragged edge's frame; the playhead stays where it was.
+        setPreviewFrame(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration));
         publishResizingClip(
           resizingClipRef.current ? { ...resizingClipRef.current, started: true, ...v } : null,
         );
@@ -393,7 +387,7 @@ export function useTimelineClipDrag({
       }
       previewGroupResize(session, next, setResizeState);
     },
-    [scrollRef, ppsRef, buildSnapTargets, publishResizingClip],
+    [scrollRef, ppsRef, buildSnapTargets, snapGridStep, publishResizingClip],
   );
   const applyResizePointerRef = useRef(applyResizePointer);
   applyResizePointerRef.current = applyResizePointer;
@@ -404,13 +398,7 @@ export function useTimelineClipDrag({
       cancelAnimationFrame(clipDragScrollRaf.current);
       clipDragScrollRaf.current = 0;
     }
-    if (trimSeekOriginRef.current != null) {
-      // Paused: put the playhead back. Playing: leave it, a backward jump would rewind live playback.
-      if (!usePlayerStore.getState().isPlaying) {
-        onSeekRef.current?.(trimSeekOriginRef.current, { keepPlaying: true, follow: false });
-      }
-      trimSeekOriginRef.current = null;
-    }
+    setPreviewFrame(null);
     // Gesture teardown: drop frozen caches so the next gesture reads fresh state.
     snapTargetsCacheRef.current.clear();
     dragAudioTracksRef.current = null;

package/src/player/components/useTimelineProviderState.tsx

@@ -223,7 +223,6 @@ export function useTimelineProviderState({
     onResizeElements: pinnedOnResizeElements,
     onBlockedEditAttempt: oneShotEdits.onBlockedEditAttempt,
     onLinkEdit: oneShotEdits.onLinkEdit,
-    onSeek,
     setShowPopover,
     setRangeSelectionRef,
     readZIndex: zSyncEnabled ? readClipZIndex : undefined,

package/src/player/components/useTimelineTicks.ts

@@ -1,8 +1,11 @@
 import { useMemo } from "react";
-import { STUDIO_PREVIEW_FPS } from "../lib/time";
 import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
 import type { TimelineTimeRange } from "../lib/timelineClipIndex";
-import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+import {
+  generateTicks,
+  getTimelineMajorTickInterval,
+  rulerFrameRate,
+} from "./timelineRulerGeometry";
 
 export function useTimelineTicks(
   duration: number,
@@ -10,7 +13,7 @@ export function useTimelineTicks(
   timeDisplayMode: TimelineTimeDisplayMode,
   renderTimeRange?: TimelineTimeRange,
 ) {
-  const frameRate = timeDisplayMode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
+  const frameRate = rulerFrameRate(timeDisplayMode);
   const ticks = useMemo(
     () => generateTicks(duration, pixelsPerSecond, frameRate, renderTimeRange),
     [duration, frameRate, pixelsPerSecond, renderTimeRange],

package/src/player/hooks/timelinePlayerTestHarness.ts

@@ -5,12 +5,14 @@ import { createRoot } from "react-dom/client";
 import { vi } from "vitest";
 import { useTimelinePlayer, type UseTimelinePlayerOptions } from "./useTimelinePlayer";
 import { usePlayerStore } from "../store/playerStore";
+import { setPreviewFrame } from "../store/previewFrameStore";
 
 export type TimelinePlayerApi = ReturnType<typeof useTimelinePlayer>;
 
 export function resetPlayerStore() {
   usePlayerStore.getState().reset();
   usePlayerStore.setState({ requestedSeekTime: null });
+  setPreviewFrame(null);
 }
 
 function TimelinePlayerHarness({

package/src/player/hooks/useTimelinePlayer.seek.test.ts

@@ -12,6 +12,7 @@ import {
   resetPlayerStore,
 } from "./timelinePlayerTestHarness";
 import { liveTime, usePlayerStore } from "../store/playerStore";
+import { setPreviewFrame } from "../store/previewFrameStore";
 import { setTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -350,6 +351,71 @@ describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
   });
 });
 
+describe("useTimelinePlayer preview frame (a trim's dragged edge)", () => {
+  function previewFrame(time: number | null) {
+    act(() => setPreviewFrame(time));
+  }
+
+  it("shows the frame without moving the playhead, then puts the playhead's frame back", () => {
+    const { api, root, adapter } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 1.25);
+    const seeks = liveTime.seekCount();
+    previewFrame(3.4);
+    expect(adapter.getTime()).toBe(3.4);
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
+    expect(liveTime.latest()).toBe(1.25);
+    previewFrame(null);
+    expect(adapter.getTime()).toBe(1.25);
+    expect(liveTime.seekCount()).toBe(seeks);
+    unmountWithAct(root);
+  });
+
+  it("keeps the playhead's time when paused, played or reloaded over the frame", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    attachIframeWindow(getApi(), makeAdapterWindow().win);
+    seekWithAct(getApi(), 1.25);
+    previewFrame(3.4);
+    act(() => getApi().pause());
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
+    act(() => getApi().refreshPlayer());
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeFakeIframe(makeAdapterWindow().win);
+    shadow.src = "http://localhost/api/projects/demo/preview?_t=1";
+    act(() => {
+      getApi().setShadowIframeNode(shadow);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(shadow);
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
+    previewFrame(3.5);
+    const live = (shadow.contentWindow as unknown as { __player: { getTime(): number } }).__player;
+    expect(live.getTime()).toBe(3.5);
+    act(() => getApi().play());
+    expect(live.getTime()).toBe(1.25);
+    unmountWithAct(root);
+  });
+
+  it("plays from the in-point when play rewinds from the end over the frame", () => {
+    const { api, root, adapter } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 30);
+    act(() => usePlayerStore.setState({ inPoint: 3 }));
+    previewFrame(12);
+    act(() => api.play());
+    expect(adapter.getTime()).toBe(3);
+    unmountWithAct(root);
+  });
+
+  it("leaves live playback alone", () => {
+    const { api, root, adapter } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 2);
+    setStorePlaying();
+    previewFrame(5);
+    expect(adapter.getTime()).toBe(2);
+    unmountWithAct(root);
+  });
+});
+
 describe("useTimelinePlayer RAF loop wrap-around", () => {
   type SeekCall = { time: number; options?: { keepPlaying?: boolean } };
 

package/src/player/hooks/useTimelinePlayer.ts

@@ -5,6 +5,8 @@ import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
 import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
 import { useShadowPreviewReload } from "./useShadowPreviewReload";
 import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
+import { subscribePreviewFrame, transportAdapter } from "../store/previewFrameStore";
+import { clampToDuration } from "../lib/time";
 import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
 import { logReload } from "../../utils/reloadDebug";
 
@@ -148,10 +150,11 @@ export function useTimelinePlayer({
         const iframe = overrideIframe !== undefined ? overrideIframe : iframeRef.current;
         const win = iframe?.contentWindow as IframeWindow | null;
         if (!iframe || !win) return null;
-        return resolvePlaybackAdapter(iframe, win, {
+        const adapter = resolvePlaybackAdapter(iframe, win, {
           cache: staticSeekAdapterRef,
           warned: staticSeekWarnedRef,
         });
+        return transportAdapter(adapter);
       } catch {
         return null;
       }
@@ -301,7 +304,7 @@ export function useTimelinePlayer({
         return false;
       }
       const duration = Math.max(0, adapter.getDuration());
-      const nextTime = Math.max(0, duration > 0 ? Math.min(duration, time) : time);
+      const nextTime = clampToDuration(time, duration);
       const keepPlaying = options?.keepPlaying === true;
       const shouldResumeAfterSeek = shouldResumeForwardPlaybackAfterSeek({
         keepPlaying,
@@ -366,6 +369,7 @@ export function useTimelinePlayer({
       }
     });
   }, [seek, play, pause]);
+  useEffect(() => subscribePreviewFrame(getAdapter), [getAdapter]);
   const { playbackKeyDownRef, playbackKeyUpRef, attachIframeShortcutListeners, togglePlay } =
     usePlaybackKeyboard({
       iframeRef,

package/src/player/lib/time.ts

@@ -1,5 +1,8 @@
 export const STUDIO_PREVIEW_FPS = 30;
 
+export const clampToDuration = (time: number, duration: number) =>
+  Math.max(0, duration > 0 ? Math.min(duration, time) : time);
+
 export function formatTime(time: number): string {
   if (!Number.isFinite(time) || time < 0) return "00:00";
   const mins = Math.floor(time / 60);

package/src/player/store/previewFrameStore.ts

@@ -0,0 +1,48 @@
+import { create } from "zustand";
+import type { PlaybackAdapter } from "../lib/playbackTypes";
+import { clampToDuration } from "../lib/time";
+import { usePlayerStore } from "./playerStore";
+
+/** A frame the preview shows without moving the playhead (a trim's dragged edge); null shows the playhead's. */
+export const usePreviewFrameStore = create<{ time: number | null }>(() => ({ time: null }));
+
+export const setPreviewFrame = (time: number | null) => usePreviewFrameStore.setState({ time });
+
+// A trim's edge frame is on screen, not the transport's time: pause, play and a reload's
+// hand-over read the playhead's time, and play starts from it unless the caller seeked first.
+function showingPreviewFrame(adapter: PlaybackAdapter): PlaybackAdapter {
+  let seeked = false;
+  const time = () => (seeked ? adapter.getTime() : usePlayerStore.getState().currentTime);
+  return {
+    play: () => {
+      adapter.seek(time());
+      adapter.play();
+    },
+    pause: () => adapter.pause(),
+    seek: (t, options) => {
+      seeked = true;
+      adapter.seek(t, options);
+    },
+    getTime: time,
+    getDuration: () => adapter.getDuration(),
+    isPlaying: () => adapter.isPlaying(),
+  };
+}
+
+/** The adapter as the transport must see it while a paused preview frame is on screen. */
+export function transportAdapter(adapter: PlaybackAdapter | null): PlaybackAdapter | null {
+  const showing = usePreviewFrameStore.getState().time !== null;
+  return adapter && showing && !usePlayerStore.getState().isPlaying
+    ? showingPreviewFrame(adapter)
+    : adapter;
+}
+
+/** Puts each preview frame on screen while paused, and the playhead's frame back when it clears. */
+export function subscribePreviewFrame(getAdapter: () => PlaybackAdapter | null): () => void {
+  return usePreviewFrameStore.subscribe((state, prev) => {
+    if (state.time === prev.time || usePlayerStore.getState().isPlaying) return;
+    const adapter = getAdapter();
+    const time = state.time ?? usePlayerStore.getState().currentTime;
+    adapter?.seek(clampToDuration(time, adapter.getDuration()));
+  });
+}

package/src/player/store/timelineElement.ts

@@ -8,6 +8,7 @@
  */
 
 import type { ClipManifestClip } from "../lib/playbackTypes";
+import { roundToCenti } from "../../utils/rounding";
 
 export interface TimelineElement {
   id: string;
@@ -112,9 +113,20 @@ type RowClock = Pick<
   TimelineElement,
   "start" | "parentCompositionStart" | "authoredStartIsMasterTime"
 >;
+type SavedClip = RowClock & Pick<TimelineElement, "duration">;
 const authoredOffset = (element: RowClock) =>
   element.authoredStartIsMasterTime ? 0 : (element.parentCompositionStart ?? 0);
 
+/**
+ * Where a clip's edges sit once saved: its file stores the local start to the centisecond, and the
+ * duration too when a resize writes it; a move keeps the authored duration.
+ */
+export function savedClipEdges(element: SavedClip, start: number, resizedDuration?: number) {
+  const savedStart = authoredOffset(element) + roundToCenti(toAuthoredStart(element, start));
+  const duration = resizedDuration === undefined ? element.duration : roundToCenti(resizedDuration);
+  return { start: savedStart, end: savedStart + duration };
+}
+
 /** The earliest master start this row can take: its host's start, or its own if already earlier. */
 export function clampToHostStart(element: RowClock, masterTime: number): number {
   return Math.max(Math.min(authoredOffset(element), element.start), masterTime);

package/src/styles/components.css

@@ -935,3 +935,54 @@
     transform: scaleY(1);
   }
 }
+
+/* Framey on the header's "Edit with Framey" (OpenInDesktopButton.tsx): a wiggle on hover, a flight towards
+ * the app while it opens. The eye follows the pointer from script. */
+@keyframes hf-framey-wiggle {
+  0%,
+  100% {
+    transform: rotate(0deg);
+  }
+  25% {
+    transform: rotate(-14deg);
+  }
+  60% {
+    transform: rotate(10deg);
+  }
+}
+
+@keyframes hf-framey-fly {
+  70% {
+    opacity: 1;
+  }
+  100% {
+    transform: translate(48px, -28px) rotate(25deg) scale(0.6);
+    opacity: 0;
+  }
+}
+
+.hf-framey {
+  transform-origin: 30% 30%;
+}
+
+.hf-framey-eye {
+  transition: transform 80ms linear;
+}
+
+.hf-framey-trigger:hover .hf-framey {
+  animation: hf-framey-wiggle 0.5s ease-in-out;
+}
+
+.hf-framey-trigger[data-opening] .hf-framey {
+  animation: hf-framey-fly 0.9s ease-in forwards;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-framey-trigger:hover .hf-framey,
+  .hf-framey-trigger[data-opening] .hf-framey {
+    animation: none;
+  }
+  .hf-framey-eye {
+    transition: none;
+  }
+}

package/src/styles/theme.css

@@ -436,6 +436,9 @@
   --color-violet-400: oklch(70.2% 0.183 293.541);
   --color-violet-500: oklch(60.6% 0.25 292.717);
   --color-white: #fff;
+  /* Framey, the desktop app's cursor mascot (hyperframes-internal packages/nib): the same in both themes. */
+  --color-framey: #3ce6ac;
+  --color-framey-ink: #16121a;
 }
 
 /* The colour-scheme picks each token's light or dark half: dark unless the document element

package/src/timelineChromeExports.test.tsx

@@ -4,6 +4,7 @@ import { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   AudioMeterStrip,
+  dispatchLinkShortcut,
   TimelineHistoryButtons,
   TimelineToolbar,
   useAudioMetersVisible as exportedAudioMetersVisible,
@@ -13,6 +14,7 @@ import {
 } from "@hyperframes/studio";
 import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
 import { useAudioMetersVisible } from "./utils/audioMeterVisibility";
+import { dispatchLinkShortcut as localDispatchLinkShortcut } from "./hooks/linkShortcuts";
 
 installReactActEnvironment();
 
@@ -52,6 +54,10 @@ describe("timeline chrome package exports, outside Studio's shell", () => {
     await act(async () => root.unmount());
   });
 
+  it("exports the clip menu's link shortcuts for a host's own key handler", () => {
+    expect(dispatchLinkShortcut).toBe(localDispatchLinkShortcut);
+  });
+
   it("exports the meter visibility store a host toggles", () => {
     expect(exportedAudioMetersVisible).toBe(useAudioMetersVisible);
     exportedAudioMetersVisible.getState().setVisible(true);

package/src/utils/gsapSoftReload.test.ts

@@ -384,6 +384,56 @@ describe("ensureMotionPathPluginLoaded", () => {
     expect(appendedScripts).toHaveLength(0);
   });
 
+  describe("when gsap is not there yet at load", () => {
+    const post = (source: unknown, type = "ready") => {
+      const event = new MessageEvent("message", { data: { source: "hf-preview", type } });
+      Object.defineProperty(event, "source", { value: source });
+      window.dispatchEvent(event);
+    };
+
+    it("loads the plugin once that iframe's runtime is ready", () => {
+      const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe({ gsap: undefined });
+      ensureMotionPathPluginLoaded(iframe);
+      contentWindow.gsap = { registerPlugin: vi.fn() };
+      post({});
+      post(contentWindow, "timeline");
+      expect(appendedScripts).toHaveLength(0);
+      post(contentWindow);
+      post(contentWindow);
+      expect(appendedScripts).toHaveLength(1);
+      expect(appendedScripts[0]!.src).toContain("MotionPathPlugin");
+    });
+
+    it("stops listening at the first ready, even when it brought no gsap", () => {
+      const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe({ gsap: undefined });
+      ensureMotionPathPluginLoaded(iframe);
+      post(contentWindow);
+      contentWindow.gsap = { registerPlugin: vi.fn() };
+      post(contentWindow);
+      expect(appendedScripts).toHaveLength(0);
+    });
+
+    it("drops a preview that never became ready once a newer one loads", () => {
+      const stale = buildBootstrapIframe({ gsap: undefined });
+      ensureMotionPathPluginLoaded(stale.iframe);
+      ensureMotionPathPluginLoaded(buildBootstrapIframe({ gsap: undefined }).iframe);
+      stale.contentWindow.gsap = { registerPlugin: vi.fn() };
+      post(stale.contentWindow);
+      expect(stale.appendedScripts).toHaveLength(0);
+    });
+
+    it("does not wait when the runtime already booted, since its ready has gone out", () => {
+      const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe({
+        gsap: undefined,
+        __playerReady: true,
+      });
+      ensureMotionPathPluginLoaded(iframe);
+      contentWindow.gsap = { registerPlugin: vi.fn() };
+      post(contentWindow);
+      expect(appendedScripts).toHaveLength(0);
+    });
+  });
+
   it("loads the plugin at the composition's own gsap version", () => {
     const { iframe, appendedScripts } = buildBootstrapIframe({
       gsap: { version: "3.14.2", registerPlugin: vi.fn() },

package/src/utils/gsapSoftReload.ts

@@ -14,6 +14,7 @@ type IframeWindow = Window & {
   // reloads (each needing the plugin) don't queue duplicate plugin scripts that
   // re-flash the iframe. Cleared once the plugin loads or errors.
   __hfMotionPathPluginLoading?: boolean;
+  __playerReady?: boolean;
   gsap?: {
     version?: string;
     timeline?: (...args: unknown[]) => unknown;
@@ -37,10 +38,15 @@ type IframeWindow = Window & {
  * studio edits.
  *
  * Idempotent (no-ops once the plugin is present or already loading) and
- * defensive: no-ops without gsap/registerPlugin and tolerates a CDN failure
+ * defensive: without gsap it waits for the runtime's ready, and it tolerates a CDN failure
  * (the soft-reload async fallback in applySoftReload still covers that case).
  */
+// At most one preview waits for its runtime; a newer load replaces it, so a frame that never boots is not kept alive.
+let pendingReadyRetry: ((event: MessageEvent) => void) | null = null;
+
 export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null): void {
+  if (pendingReadyRetry) window.removeEventListener("message", pendingReadyRetry);
+  pendingReadyRetry = null;
   if (!iframe?.contentWindow || !iframe.contentDocument) return;
   const win = iframe.contentWindow as IframeWindow;
   const doc = iframe.contentDocument;
@@ -53,7 +59,21 @@ export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null):
     } catch {}
     return;
   }
-  if (!win.gsap?.registerPlugin) return;
+  // A body gsap runs after web fonts, which can be after the iframe's load: retry once the runtime is ready.
+  // A booted runtime (`__playerReady`, set in the same task it posts ready) has nothing left to wait for.
+  if (!win.gsap?.registerPlugin) {
+    if (win.__playerReady) return;
+    const retry = (event: MessageEvent) => {
+      const data = event.data as { source?: unknown; type?: unknown } | null;
+      if (event.source !== win || data?.source !== "hf-preview" || data.type !== "ready") return;
+      window.removeEventListener("message", retry);
+      pendingReadyRetry = null;
+      if (win.gsap?.registerPlugin) ensureMotionPathPluginLoaded(iframe);
+    };
+    pendingReadyRetry = retry;
+    window.addEventListener("message", retry);
+    return;
+  }
   // A load is already in flight for this iframe — don't queue a second script.
   if (win.__hfMotionPathPluginLoading) return;