From 18b9acac12269899b0bfacb289d9bde3e1b065e4 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 27 Jul 2026 22:14:23 -0700
Subject: [PATCH 1/4] fix(studio): improve preview loading reliability

---
 .../studio/src/components/nle/NLEContext.tsx  |  21 +--
 .../studio/src/components/nle/NLEPreview.tsx  |   6 +-
 .../sidebar/CompositionsTab.drag.test.tsx     |  27 ++++
 .../components/sidebar/CompositionsTab.tsx    |  80 +++++++----
 .../src/player/components/Player.test.ts      |  24 +++-
 .../studio/src/player/components/Player.tsx   | 134 ++++++++++++------
 .../hooks/useTimelinePlayer.seek.test.ts      |  33 +++++
 .../player/hooks/useTimelineSyncCallbacks.ts  |  91 ++++++------
 8 files changed, 288 insertions(+), 128 deletions(-)

diff --git a/packages/studio/src/components/nle/NLEContext.tsx b/packages/studio/src/components/nle/NLEContext.tsx
index 5bdece645..55b96a092 100644
--- a/packages/studio/src/components/nle/NLEContext.tsx
+++ b/packages/studio/src/components/nle/NLEContext.tsx
@@ -32,7 +32,7 @@ export interface NLEContextValue {
   togglePlay: () => void;
   seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
   refreshPlayer: () => void;
-  onIframeLoad: () => void;
+  onIframeLoad: (reportError?: (message: string) => void) => void;
   // composition stack (from useCompositionStack)
   compositionStack: CompositionLevel[];
   updateCompositionStack: React.Dispatch<React.SetStateAction<CompositionLevel[]>>;
@@ -122,14 +122,17 @@ export function NLEProvider({
     refreshPlayer();
   }, [refreshKey, refreshPlayer]);
 
-  const onIframeLoad = useCallback(() => {
-    baseOnIframeLoad();
-    // Pre-load + register MotionPathPlugin once so adding a motion path in the
-    // studio doesn't take the async plugin-load flash path on the first soft
-    // reload (the comp may not ship the plugin until it actually uses one).
-    ensureMotionPathPluginLoaded(iframeRef.current);
-    onIframeRef?.(iframeRef.current);
-  }, [baseOnIframeLoad, iframeRef, onIframeRef]);
+  const onIframeLoad = useCallback(
+    (reportError?: (message: string) => void) => {
+      baseOnIframeLoad(reportError);
+      // Pre-load + register MotionPathPlugin once so adding a motion path in the
+      // studio doesn't take the async plugin-load flash path on the first soft
+      // reload (the comp may not ship the plugin until it actually uses one).
+      ensureMotionPathPluginLoaded(iframeRef.current);
+      onIframeRef?.(iframeRef.current);
+    },
+    [baseOnIframeLoad, iframeRef, onIframeRef],
+  );
 
   const {
     compositionStack,
diff --git a/packages/studio/src/components/nle/NLEPreview.tsx b/packages/studio/src/components/nle/NLEPreview.tsx
index 8e634f767..a11d062e9 100644
--- a/packages/studio/src/components/nle/NLEPreview.tsx
+++ b/packages/studio/src/components/nle/NLEPreview.tsx
@@ -15,7 +15,7 @@ import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/s
 interface NLEPreviewProps {
   projectId: string;
   iframeRef: RefObject<HTMLIFrameElement | null>;
-  onIframeLoad: () => void;
+  onIframeLoad: (reportError?: (message: string) => void) => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   directUrl?: string;
@@ -491,9 +491,9 @@ export const NLEPreview = memo(function NLEPreview({
               ref={setPreviewIframeRef}
               projectId={directUrl ? undefined : projectId}
               directUrl={directUrl}
-              onLoad={() => {
+              onLoad={(reportError) => {
                 updateCompositionSizeFromPreview();
-                onIframeLoad();
+                onIframeLoad(reportError);
                 applyInitialZoom();
               }}
               onCompositionLoadingChange={onCompositionLoadingChange}
diff --git a/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx b/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx
index dbe9727e1..1a5dcd2d1 100644
--- a/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx
+++ b/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx
@@ -40,6 +40,33 @@ function mount(onSelect = vi.fn(), onAddToTimeline = vi.fn()) {
 }
 
 describe("composition card drag", () => {
+  it("uses a cached image instead of eagerly mounting a live preview iframe", () => {
+    const { host } = mount();
+    expect(host.querySelector('img[src*="/thumbnail/"]')).not.toBeNull();
+    expect(host.querySelector("iframe")).toBeNull();
+  });
+
+  it("mounts one live preview only after sustained hover and removes it on leave", () => {
+    vi.useFakeTimers();
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const { host, card } = mount();
+      act(() => {
+        card.dispatchEvent(new Event("pointerover", { bubbles: true }));
+        vi.advanceTimersByTime(300);
+      });
+      expect(host.querySelectorAll("iframe")).toHaveLength(1);
+
+      act(() => {
+        card.dispatchEvent(new Event("pointerout", { bubbles: true }));
+      });
+      expect(host.querySelector("iframe")).toBeNull();
+    } finally {
+      consoleError.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
   it("keeps ordinary click navigation", () => {
     const { card, onSelect } = mount();
     act(() => card.click());
diff --git a/packages/studio/src/components/sidebar/CompositionsTab.tsx b/packages/studio/src/components/sidebar/CompositionsTab.tsx
index f5fb0099e..d061fd600 100644
--- a/packages/studio/src/components/sidebar/CompositionsTab.tsx
+++ b/packages/studio/src/components/sidebar/CompositionsTab.tsx
@@ -1,5 +1,6 @@
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { setPreviewMediaMuted } from "../../player/lib/timelineIframeHelpers";
+import { buildCompositionThumbnailUrl } from "../../player/components/CompositionThumbnail";
 import { TIMELINE_COMPOSITION_MIME } from "../../utils/timelineCompositionDrop";
 
 interface CompositionsTabProps {
@@ -130,6 +131,7 @@ function CompCard({
 }) {
   const [hovered, setHovered] = useState(false);
   const [stageSize, setStageSize] = useState(DEFAULT_PREVIEW_STAGE);
+  const [livePreviewLoaded, setLivePreviewLoaded] = useState(false);
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const syncTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -159,9 +161,16 @@ function CompCard({
       hoverTimer.current = null;
     }
     setHovered(false);
+    setLivePreviewLoaded(false);
   };
   const name = comp.replace(/^compositions\//, "").replace(/\.html$/, "");
   const previewUrl = `/api/projects/${projectId}/preview/comp/${comp}`;
+  const thumbnailUrl = buildCompositionThumbnailUrl({
+    previewUrl,
+    seekTime: 0,
+    duration: THUMBNAIL_SEEK_TIME_SECONDS * 2,
+    origin: window.location.origin,
+  });
   const previewScale = resolveCompositionPreviewScale({
     cardWidth: CARD_W,
     cardHeight: CARD_H,
@@ -172,7 +181,7 @@ function CompCard({
   const thumbnailOffsetY = (CARD_H - stageSize.height * previewScale) / 2;
 
   useEffect(() => {
-    requestIframePlaybackSync(hovered);
+    if (hovered) requestIframePlaybackSync(true);
   }, [hovered, requestIframePlaybackSync]);
 
   useEffect(() => {
@@ -216,36 +225,49 @@ function CompCard({
       }`}
     >
       <div className="w-20 h-[45px] rounded overflow-hidden bg-neutral-900 flex-shrink-0 relative">
-        <iframe
-          ref={iframeRef}
-          src={previewUrl}
-          sandbox="allow-scripts allow-same-origin"
+        <img
+          src={thumbnailUrl}
+          alt=""
+          draggable={false}
           loading="lazy"
-          className="absolute border-none pointer-events-none"
-          style={{
-            transformOrigin: "0 0",
-            width: stageSize.width,
-            height: stageSize.height,
-            left: thumbnailOffsetX,
-            top: thumbnailOffsetY,
-            transform: `scale(${previewScale})`,
-          }}
-          onLoad={(e) => {
-            try {
-              const iframe = e.currentTarget;
-              const root = iframe.contentDocument?.querySelector("[data-composition-id]");
-              const width = Number(root?.getAttribute("data-width")) || DEFAULT_PREVIEW_STAGE.width;
-              const height =
-                Number(root?.getAttribute("data-height")) || DEFAULT_PREVIEW_STAGE.height;
-              setStageSize({ width, height });
-              requestIframePlaybackSync(hovered);
-            } catch {
-              setStageSize(DEFAULT_PREVIEW_STAGE);
-            }
-          }}
-          title={`${name} preview`}
-          tabIndex={-1}
+          decoding="async"
+          className={`absolute inset-0 h-full w-full object-contain transition-opacity ${
+            livePreviewLoaded ? "opacity-0" : "opacity-100"
+          }`}
         />
+        {hovered && (
+          <iframe
+            ref={iframeRef}
+            src={previewUrl}
+            sandbox="allow-scripts allow-same-origin"
+            className="absolute border-none pointer-events-none"
+            style={{
+              transformOrigin: "0 0",
+              width: stageSize.width,
+              height: stageSize.height,
+              left: thumbnailOffsetX,
+              top: thumbnailOffsetY,
+              transform: `scale(${previewScale})`,
+            }}
+            onLoad={(e) => {
+              try {
+                const iframe = e.currentTarget;
+                const root = iframe.contentDocument?.querySelector("[data-composition-id]");
+                const width =
+                  Number(root?.getAttribute("data-width")) || DEFAULT_PREVIEW_STAGE.width;
+                const height =
+                  Number(root?.getAttribute("data-height")) || DEFAULT_PREVIEW_STAGE.height;
+                setStageSize({ width, height });
+                setLivePreviewLoaded(true);
+                requestIframePlaybackSync(true);
+              } catch {
+                setStageSize(DEFAULT_PREVIEW_STAGE);
+              }
+            }}
+            title={`${name} preview`}
+            tabIndex={-1}
+          />
+        )}
       </div>
       <div
         className="min-w-0 flex-1"
diff --git a/packages/studio/src/player/components/Player.test.ts b/packages/studio/src/player/components/Player.test.ts
index 32e106971..4516a166a 100644
--- a/packages/studio/src/player/components/Player.test.ts
+++ b/packages/studio/src/player/components/Player.test.ts
@@ -1,7 +1,29 @@
 // @vitest-environment happy-dom
 
 import { describe, expect, it } from "vitest";
-import { hasUnloadedAssets, shouldShowCompositionLoadingOverlay } from "./Player";
+import {
+  hasUnloadedAssets,
+  readPreviewErrorMessage,
+  shouldShowCompositionLoadingOverlay,
+} from "./Player";
+
+describe("preview errors", () => {
+  it("reads the player probe error for the visible retry state", () => {
+    expect(
+      readPreviewErrorMessage(
+        new CustomEvent("error", {
+          detail: { message: "Composition timeline not found after 8s" },
+        }),
+      ),
+    ).toBe("Composition timeline not found after 8s");
+  });
+
+  it("falls back when the player emits an unstructured error", () => {
+    expect(readPreviewErrorMessage(new Event("error"))).toBe(
+      "The composition preview did not become ready.",
+    );
+  });
+});
 
 describe("composition loading overlay", () => {
   it("shows while the composition is loading", () => {
diff --git a/packages/studio/src/player/components/Player.tsx b/packages/studio/src/player/components/Player.tsx
index 6c26b4bf9..584d35001 100644
--- a/packages/studio/src/player/components/Player.tsx
+++ b/packages/studio/src/player/components/Player.tsx
@@ -10,7 +10,7 @@ import { HyperframesLoader } from "../../components/ui";
 interface PlayerProps {
   projectId?: string;
   directUrl?: string;
-  onLoad: () => void;
+  onLoad: (reportError: (message: string) => void) => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   style?: React.CSSProperties;
@@ -38,11 +38,19 @@ function getShaderTransitionLoading(event: Event): boolean | null {
 }
 
 const COMPOSITION_LOADING_OVERLAY_DELAY_MS = 400;
+const DEFAULT_PREVIEW_ERROR = "The composition preview did not become ready.";
 
 export function shouldShowCompositionLoadingOverlay(compositionLoading: boolean): boolean {
   return compositionLoading;
 }
 
+export function readPreviewErrorMessage(event: Event): string {
+  if (!(event instanceof CustomEvent) || !isRecord(event.detail)) return DEFAULT_PREVIEW_ERROR;
+  return typeof event.detail.message === "string" && event.detail.message.trim()
+    ? event.detail.message
+    : DEFAULT_PREVIEW_ERROR;
+}
+
 function enableInteractiveIframe(player: HyperframesPlayerElement): void {
   const root = player.shadowRoot;
   if (!root) return;
@@ -122,12 +130,15 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
     const assetFadeRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const retryPreviewRef = useRef<(() => void) | null>(null);
+    const retryCountRef = useRef(0);
     const [assetsLoading, setAssetsLoading] = useState(false);
     const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
     const [assetOverlayFading, setAssetOverlayFading] = useState(false);
     const [shaderTransitionLoading, setShaderTransitionLoading] = useState(false);
     const [compositionLoading, setCompositionLoading] = useState(true);
     const [compositionOverlayDeferred, setCompositionOverlayDeferred] = useState(true);
+    const [previewError, setPreviewError] = useState<string | null>(null);
 
     // eslint-disable-next-line no-restricted-syntax
     useEffect(() => {
@@ -161,62 +172,32 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         );
         applyPreviewVariablesToUrl(srcUrl);
         const src = srcUrl.pathname + srcUrl.search;
-        player.setAttribute("shader-capture-scale", "1");
-        player.setAttribute("shader-loading", "player");
-        player.setAttribute("src", src);
-        player.setAttribute("width", String(portrait ? 1080 : 1920));
-        player.setAttribute("height", String(portrait ? 1920 : 1080));
-        player.style.width = "100%";
-        player.style.height = "100%";
-        player.style.display = "block";
-        player.style.background = "transparent";
-        container.appendChild(player);
-
-        // Inject pasteboard shadow: let the shadow around the canvas bleed
-        // into the surrounding pasteboard area (overflow: visible on the container)
-        // and add a subtle outline + drop-shadow so the canvas boundary reads
-        // against the gray pasteboard, consistent with professional editors.
-        if (player.shadowRoot) {
-          const pasteboardStyle = document.createElement("style");
-          pasteboardStyle.textContent =
-            ".hfp-container{overflow:visible}" +
-            ".hfp-iframe{box-shadow:0 0 0 1px rgba(255,255,255,0.08),0 4px 32px rgba(0,0,0,.7)}";
-          player.shadowRoot.appendChild(pasteboardStyle);
-        }
-
-        enableInteractiveIframe(player);
-
-        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
+        const retryPreview = () => {
+          retryCountRef.current += 1;
+          const retryUrl = new URL(src, window.location.origin);
+          retryUrl.searchParams.set("_hfStudioRetry", String(retryCountRef.current));
+          setPreviewError(null);
+          setCompositionLoading(true);
+          player.setAttribute("src", retryUrl.pathname + retryUrl.search);
+        };
+        retryPreviewRef.current = retryPreview;
         const iframe = player.iframeElement;
-        if (typeof ref === "function") {
-          ref(iframe);
-        } else if (ref) {
-          (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
-        }
-
-        // Prevent the web component's built-in click-to-toggle behavior.
-        // The studio manages playback exclusively via useTimelinePlayer.
         const preventToggle = (e: Event) => e.stopImmediatePropagation();
-        player.addEventListener("click", preventToggle, { capture: true });
-
         const handleShaderTransitionState = (event: Event) => {
           const loading = getShaderTransitionLoading(event);
           if (loading !== null) setShaderTransitionLoading(loading);
         };
-        player.addEventListener("shadertransitionstate", handleShaderTransitionState);
-
         const handleReady = () => {
+          setPreviewError(null);
           setCompositionLoading(false);
         };
-        const handleError = () => {
+        const handleError = (event: Event) => {
+          setPreviewError(readPreviewErrorMessage(event));
           setCompositionLoading(false);
         };
-        player.addEventListener("ready", handleReady);
-        player.addEventListener("error", handleError);
-
-        // Forward the iframe's native load event to the studio's onIframeLoad.
         const handleLoad = () => {
           loadCountRef.current++;
+          setPreviewError(null);
           setShaderTransitionLoading(false);
           setCompositionLoading(true);
           // Reveal animation on reload (hot-reload, composition switch)
@@ -227,7 +208,10 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             const onEnd = () => container.classList.remove("preview-revealing");
             container.addEventListener("animationend", onEnd, { once: true });
           }
-          onLoad();
+          onLoad((message) => {
+            setPreviewError(message);
+            setCompositionLoading(false);
+          });
 
           // Show a loading overlay until every `<video>`/`<audio>` and Lottie
           // asset is ready. Without this users can click play before audio has
@@ -264,7 +248,47 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             setAssetsLoading(false);
           }
         };
+
+        // Attach lifecycle listeners before assigning src or connecting the
+        // custom element. A warm local iframe can otherwise finish before
+        // Studio observes its load and never initialize the timeline.
         iframe.addEventListener("load", handleLoad);
+        player.addEventListener("click", preventToggle, { capture: true });
+        player.addEventListener("shadertransitionstate", handleShaderTransitionState);
+        player.addEventListener("ready", handleReady);
+        player.addEventListener("error", handleError);
+
+        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
+        if (typeof ref === "function") {
+          ref(iframe);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
+        }
+
+        player.setAttribute("shader-capture-scale", "1");
+        player.setAttribute("shader-loading", "player");
+        player.setAttribute("width", String(portrait ? 1080 : 1920));
+        player.setAttribute("height", String(portrait ? 1920 : 1080));
+        player.style.width = "100%";
+        player.style.height = "100%";
+        player.style.display = "block";
+        player.style.background = "transparent";
+        player.setAttribute("src", src);
+        container.appendChild(player);
+
+        // Inject pasteboard shadow: let the shadow around the canvas bleed
+        // into the surrounding pasteboard area (overflow: visible on the container)
+        // and add a subtle outline + drop-shadow so the canvas boundary reads
+        // against the gray pasteboard, consistent with professional editors.
+        if (player.shadowRoot) {
+          const pasteboardStyle = document.createElement("style");
+          pasteboardStyle.textContent =
+            ".hfp-container{overflow:visible}" +
+            ".hfp-iframe{box-shadow:0 0 0 1px rgba(255,255,255,0.08),0 4px 32px rgba(0,0,0,.7)}";
+          player.shadowRoot.appendChild(pasteboardStyle);
+        }
+
+        enableInteractiveIframe(player);
 
         cleanup = () => {
           iframe.removeEventListener("load", handleLoad);
@@ -275,6 +299,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
           container.removeChild(player);
+          if (retryPreviewRef.current === retryPreview) retryPreviewRef.current = null;
           // Clear the forwarded ref only if it still points to THIS iframe.
           // During crossfade refreshes the retiring Player unmounts after the
           // new Player has already assigned its iframe to the same ref — blindly
@@ -381,6 +406,25 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             />
           </div>
         )}
+        {previewError && (
+          <div
+            className="absolute inset-0 z-40 flex items-center justify-center bg-black/90 px-6 text-center"
+            data-hyperframes-ignore=""
+            data-testid="composition-preview-error"
+          >
+            <div className="max-w-sm">
+              <p className="text-sm font-semibold text-white">Preview failed to load</p>
+              <p className="mt-1 text-xs text-neutral-400">{previewError}</p>
+              <button
+                type="button"
+                className="mt-4 rounded-md bg-white px-3 py-1.5 text-xs font-semibold text-black transition-colors hover:bg-neutral-200"
+                onClick={() => retryPreviewRef.current?.()}
+              >
+                Retry preview
+              </button>
+            </div>
+          </div>
+        )}
       </div>
     );
   },
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
index cdafb4596..5b3200fd7 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
@@ -129,6 +129,39 @@ function expectStorePlaybackState(
 }
 
 describe("useTimelinePlayer seek hydration", () => {
+  it("reports when Studio cannot initialize a timeline after iframe load", () => {
+    vi.useFakeTimers();
+    const { api, root } = renderTimelinePlayerHarness();
+    const iframe = document.createElement("iframe");
+    const iframeWindow = {
+      postMessage: vi.fn(),
+      scrollTo: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+    Object.defineProperty(iframe, "contentWindow", {
+      value: iframeWindow,
+      configurable: true,
+    });
+    Object.defineProperty(iframe, "contentDocument", {
+      value: document.implementation.createHTMLDocument("preview"),
+      configurable: true,
+    });
+    const reportError = vi.fn();
+
+    act(() => {
+      api.iframeRef.current = iframe;
+      api.onIframeLoad(reportError);
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(reportError).toHaveBeenCalledWith(
+      "Studio could not initialize the composition timeline.",
+    );
+    unmountWithAct(root);
+    vi.useRealTimers();
+  });
+
   it("keeps an external seek request until the iframe adapter is ready", () => {
     const observedTimes: number[] = [];
     const unsubscribe = liveTime.subscribe((time) => {
diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
index c4526e260..3b7d28b66 100644
--- a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
+++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
@@ -399,51 +399,60 @@ export function useTimelineSyncCallbacks({
     pendingSeekRef,
   ]);
 
-  const onIframeLoad = useCallback(() => {
-    applyPreviewAudioState();
-    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+  const onIframeLoad = useCallback(
+    (reportError?: (message: string) => void) => {
+      applyPreviewAudioState();
+      if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
 
-    // Fast path: adapter already available (in-place reloads, cached compositions)
-    if (initializeAdapter()) return;
+      // Fast path: adapter already available (in-place reloads, cached compositions)
+      if (initializeAdapter()) return;
 
-    // The runtime posts "state" or "timeline" messages once ready.
-    // Listen for those instead of polling.
-    const iframe = iframeRef.current;
-    let settled = false;
+      // The runtime posts "state" or "timeline" messages once ready.
+      // Listen for those instead of polling.
+      const iframe = iframeRef.current;
+      let settled = false;
 
-    const trySettle = () => {
-      if (settled) return;
-      if (initializeAdapter()) {
-        settled = true;
+      const trySettle = () => {
+        if (settled) return;
+        if (initializeAdapter()) {
+          settled = true;
+          window.removeEventListener("message", onMessage);
+          if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+        }
+      };
+
+      const onMessage = (e: MessageEvent) => {
+        if (e.source && iframe && e.source !== iframe.contentWindow) return;
+        const data = e.data;
+        if (
+          data?.source === "hf-preview" &&
+          (data?.type === "state" || data?.type === "timeline")
+        ) {
+          // The main message handler owns protocol-error diagnostics. This readiness-only
+          // listener mirrors its acceptance gate without dispatching a duplicate event:
+          // an unsupported runtime must not make the iframe appear successfully settled.
+          if (inspectStudioRuntimeMessage(data).status === "unsupported") return;
+          trySettle();
+        }
+      };
+      window.addEventListener("message", onMessage);
+
+      // Safety net: if no message arrives within 5s, try one last time then give up.
+      probeIntervalRef.current = setTimeout(() => {
+        if (!settled) {
+          trySettle();
+          if (!settled) {
+            reportError?.("Studio could not initialize the composition timeline.");
+          }
+        }
         window.removeEventListener("message", onMessage);
-        if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
-      }
-    };
-
-    const onMessage = (e: MessageEvent) => {
-      if (e.source && iframe && e.source !== iframe.contentWindow) return;
-      const data = e.data;
-      if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
-        // The main message handler owns protocol-error diagnostics. This readiness-only
-        // listener mirrors its acceptance gate without dispatching a duplicate event:
-        // an unsupported runtime must not make the iframe appear successfully settled.
-        if (inspectStudioRuntimeMessage(data).status === "unsupported") return;
-        trySettle();
-      }
-    };
-    window.addEventListener("message", onMessage);
-
-    // Safety net: if no message arrives within 5s, try one last time then give up.
-    probeIntervalRef.current = setTimeout(() => {
-      if (!settled) {
-        trySettle();
-      }
-      window.removeEventListener("message", onMessage);
-      // Never leave the preview stuck invisible if the runtime never settled
-      // (initializeAdapter reveals on success; this covers the give-up case).
-      revealIframe(iframeRef.current);
-    }, 5000) as unknown as ReturnType<typeof setInterval>;
-  }, [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState]);
+        // Never leave the preview stuck invisible if the runtime never settled
+        // (initializeAdapter reveals on success; this covers the give-up case).
+        revealIframe(iframeRef.current);
+      }, 5000) as unknown as ReturnType<typeof setInterval>;
+    },
+    [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState],
+  );
 
   // Stable refs so mount-effect closures always call the latest version
   const processTimelineMessageRef = { current: processTimelineMessage };

From 0faeb42f86e20c5503e0827fa18b89050663bad7 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 27 Jul 2026 22:25:27 -0700
Subject: [PATCH 2/4] test(studio): mock composition thumbnails in smoke

---
 scripts/studio-runtime-smoke.mjs      | 8 ++++++++
 scripts/studio-runtime-smoke.test.mjs | 9 +++++++++
 2 files changed, 17 insertions(+)

diff --git a/scripts/studio-runtime-smoke.mjs b/scripts/studio-runtime-smoke.mjs
index bfe0640e0..eb1c1a401 100644
--- a/scripts/studio-runtime-smoke.mjs
+++ b/scripts/studio-runtime-smoke.mjs
@@ -10,6 +10,8 @@ export const SMOKE_COMPOSITION_HTML =
   '<!doctype html><html><body><div data-composition-id="root" data-width="1920" ' +
   'data-height="1080" data-duration="1" data-start="0"><div class="clip" ' +
   'data-hf-id="title" data-start="0" data-duration="1">Test</div></div></body></html>';
+const SMOKE_THUMBNAIL_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="9"><rect width="16" height="9"/></svg>';
 
 function json(body, status = 200) {
   return { status, contentType: "application/json", body: JSON.stringify(body) };
@@ -75,6 +77,11 @@ function projectPreviewResponse(pathname) {
     : text(SMOKE_COMPOSITION_HTML, "text/html");
 }
 
+function projectThumbnailResponse(pathname) {
+  if (!pathname.startsWith(`${PROJECT_PATH}/thumbnail/`)) return undefined;
+  return text(SMOKE_THUMBNAIL_SVG, "image/svg+xml");
+}
+
 function gsapAnimationsResponse(pathname) {
   if (!pathname.startsWith(`${PROJECT_PATH}/gsap-animations/`)) return undefined;
   return json({ animations: [], timelineVar: "tl", preamble: "", postamble: "" });
@@ -85,6 +92,7 @@ function getStudioSmokeResponse(pathname) {
     GET_RESPONSES.get(pathname) ??
     projectFileResponse(pathname) ??
     projectPreviewResponse(pathname) ??
+    projectThumbnailResponse(pathname) ??
     gsapAnimationsResponse(pathname)
   );
 }
diff --git a/scripts/studio-runtime-smoke.test.mjs b/scripts/studio-runtime-smoke.test.mjs
index a686b48e9..adf1991db 100644
--- a/scripts/studio-runtime-smoke.test.mjs
+++ b/scripts/studio-runtime-smoke.test.mjs
@@ -44,6 +44,15 @@ describe("Studio runtime smoke fixtures", () => {
     assert.deepEqual(bodyOf("GET", "/api/projects/smoke-test/lint"), { findings: [] });
   });
 
+  it("returns an image for composition thumbnail requests", () => {
+    const response = studioSmokeApiResponse(
+      "GET",
+      "http://localhost:5199/api/projects/smoke-test/thumbnail/index.html?t=3",
+    );
+    assert.ok(response && response !== null);
+    assert.equal(response.contentType, "image/svg+xml");
+  });
+
   it("marks unknown API requests as fixture failures", () => {
     assert.equal(studioSmokeApiResponse("GET", "http://localhost:5199/api/new-endpoint"), null);
     assert.equal(studioSmokeApiResponse("GET", "http://localhost:5199/src/main.tsx"), undefined);

From 3af9a7df2d687ec018f7d0705d25b5416c8dfa78 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 27 Jul 2026 22:35:09 -0700
Subject: [PATCH 3/4] refactor(studio): reuse player probe errors

---
 .../studio/src/components/nle/NLEContext.tsx  | 21 ++---
 .../studio/src/components/nle/NLEPreview.tsx  |  6 +-
 .../src/player/components/Player.test.ts      | 21 +++--
 .../studio/src/player/components/Player.tsx   |  7 +-
 .../hooks/useTimelinePlayer.seek.test.ts      | 33 -------
 .../player/hooks/useTimelineSyncCallbacks.ts  | 91 +++++++++----------
 scripts/studio-runtime-smoke.mjs              |  7 +-
 7 files changed, 67 insertions(+), 119 deletions(-)

diff --git a/packages/studio/src/components/nle/NLEContext.tsx b/packages/studio/src/components/nle/NLEContext.tsx
index 55b96a092..5bdece645 100644
--- a/packages/studio/src/components/nle/NLEContext.tsx
+++ b/packages/studio/src/components/nle/NLEContext.tsx
@@ -32,7 +32,7 @@ export interface NLEContextValue {
   togglePlay: () => void;
   seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
   refreshPlayer: () => void;
-  onIframeLoad: (reportError?: (message: string) => void) => void;
+  onIframeLoad: () => void;
   // composition stack (from useCompositionStack)
   compositionStack: CompositionLevel[];
   updateCompositionStack: React.Dispatch<React.SetStateAction<CompositionLevel[]>>;
@@ -122,17 +122,14 @@ export function NLEProvider({
     refreshPlayer();
   }, [refreshKey, refreshPlayer]);
 
-  const onIframeLoad = useCallback(
-    (reportError?: (message: string) => void) => {
-      baseOnIframeLoad(reportError);
-      // Pre-load + register MotionPathPlugin once so adding a motion path in the
-      // studio doesn't take the async plugin-load flash path on the first soft
-      // reload (the comp may not ship the plugin until it actually uses one).
-      ensureMotionPathPluginLoaded(iframeRef.current);
-      onIframeRef?.(iframeRef.current);
-    },
-    [baseOnIframeLoad, iframeRef, onIframeRef],
-  );
+  const onIframeLoad = useCallback(() => {
+    baseOnIframeLoad();
+    // Pre-load + register MotionPathPlugin once so adding a motion path in the
+    // studio doesn't take the async plugin-load flash path on the first soft
+    // reload (the comp may not ship the plugin until it actually uses one).
+    ensureMotionPathPluginLoaded(iframeRef.current);
+    onIframeRef?.(iframeRef.current);
+  }, [baseOnIframeLoad, iframeRef, onIframeRef]);
 
   const {
     compositionStack,
diff --git a/packages/studio/src/components/nle/NLEPreview.tsx b/packages/studio/src/components/nle/NLEPreview.tsx
index a11d062e9..8e634f767 100644
--- a/packages/studio/src/components/nle/NLEPreview.tsx
+++ b/packages/studio/src/components/nle/NLEPreview.tsx
@@ -15,7 +15,7 @@ import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/s
 interface NLEPreviewProps {
   projectId: string;
   iframeRef: RefObject<HTMLIFrameElement | null>;
-  onIframeLoad: (reportError?: (message: string) => void) => void;
+  onIframeLoad: () => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   directUrl?: string;
@@ -491,9 +491,9 @@ export const NLEPreview = memo(function NLEPreview({
               ref={setPreviewIframeRef}
               projectId={directUrl ? undefined : projectId}
               directUrl={directUrl}
-              onLoad={(reportError) => {
+              onLoad={() => {
                 updateCompositionSizeFromPreview();
-                onIframeLoad(reportError);
+                onIframeLoad();
                 applyInitialZoom();
               }}
               onCompositionLoadingChange={onCompositionLoadingChange}
diff --git a/packages/studio/src/player/components/Player.test.ts b/packages/studio/src/player/components/Player.test.ts
index 4516a166a..516b80795 100644
--- a/packages/studio/src/player/components/Player.test.ts
+++ b/packages/studio/src/player/components/Player.test.ts
@@ -7,6 +7,15 @@ import {
   shouldShowCompositionLoadingOverlay,
 } from "./Player";
 
+function createAudioIframe() {
+  const iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  const audio = iframe.contentDocument?.createElement("audio");
+  expect(audio).toBeDefined();
+  iframe.contentDocument?.body.appendChild(audio!);
+  return { audio: audio!, iframe };
+}
+
 describe("preview errors", () => {
   it("reads the player probe error for the visible retry state", () => {
     expect(
@@ -35,10 +44,7 @@ describe("composition loading overlay", () => {
   });
 
   it("keeps the asset overlay up while media is still buffering", () => {
-    const iframe = document.createElement("iframe");
-    document.body.appendChild(iframe);
-    const audio = iframe.contentDocument?.createElement("audio");
-    expect(audio).toBeDefined();
+    const { audio, iframe } = createAudioIframe();
     Object.defineProperty(audio, "readyState", {
       value: 0,
       configurable: true,
@@ -47,7 +53,6 @@ describe("composition loading overlay", () => {
       value: 2,
       configurable: true,
     });
-    iframe.contentDocument?.body.appendChild(audio!);
 
     expect(hasUnloadedAssets(iframe, false)).toBe(true);
 
@@ -55,10 +60,7 @@ describe("composition loading overlay", () => {
   });
 
   it("does not keep the asset overlay stuck on failed media sources", () => {
-    const iframe = document.createElement("iframe");
-    document.body.appendChild(iframe);
-    const audio = iframe.contentDocument?.createElement("audio");
-    expect(audio).toBeDefined();
+    const { audio, iframe } = createAudioIframe();
     Object.defineProperty(audio, "error", {
       value: { code: 4, message: "format error" },
       configurable: true,
@@ -71,7 +73,6 @@ describe("composition loading overlay", () => {
       value: 3,
       configurable: true,
     });
-    iframe.contentDocument?.body.appendChild(audio!);
 
     expect(hasUnloadedAssets(iframe, false)).toBe(false);
 
diff --git a/packages/studio/src/player/components/Player.tsx b/packages/studio/src/player/components/Player.tsx
index 584d35001..15602f07b 100644
--- a/packages/studio/src/player/components/Player.tsx
+++ b/packages/studio/src/player/components/Player.tsx
@@ -10,7 +10,7 @@ import { HyperframesLoader } from "../../components/ui";
 interface PlayerProps {
   projectId?: string;
   directUrl?: string;
-  onLoad: (reportError: (message: string) => void) => void;
+  onLoad: () => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   style?: React.CSSProperties;
@@ -208,10 +208,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             const onEnd = () => container.classList.remove("preview-revealing");
             container.addEventListener("animationend", onEnd, { once: true });
           }
-          onLoad((message) => {
-            setPreviewError(message);
-            setCompositionLoading(false);
-          });
+          onLoad();
 
           // Show a loading overlay until every `<video>`/`<audio>` and Lottie
           // asset is ready. Without this users can click play before audio has
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
index 5b3200fd7..cdafb4596 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
@@ -129,39 +129,6 @@ function expectStorePlaybackState(
 }
 
 describe("useTimelinePlayer seek hydration", () => {
-  it("reports when Studio cannot initialize a timeline after iframe load", () => {
-    vi.useFakeTimers();
-    const { api, root } = renderTimelinePlayerHarness();
-    const iframe = document.createElement("iframe");
-    const iframeWindow = {
-      postMessage: vi.fn(),
-      scrollTo: vi.fn(),
-      addEventListener: vi.fn(),
-      removeEventListener: vi.fn(),
-    };
-    Object.defineProperty(iframe, "contentWindow", {
-      value: iframeWindow,
-      configurable: true,
-    });
-    Object.defineProperty(iframe, "contentDocument", {
-      value: document.implementation.createHTMLDocument("preview"),
-      configurable: true,
-    });
-    const reportError = vi.fn();
-
-    act(() => {
-      api.iframeRef.current = iframe;
-      api.onIframeLoad(reportError);
-      vi.advanceTimersByTime(5000);
-    });
-
-    expect(reportError).toHaveBeenCalledWith(
-      "Studio could not initialize the composition timeline.",
-    );
-    unmountWithAct(root);
-    vi.useRealTimers();
-  });
-
   it("keeps an external seek request until the iframe adapter is ready", () => {
     const observedTimes: number[] = [];
     const unsubscribe = liveTime.subscribe((time) => {
diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
index 3b7d28b66..c4526e260 100644
--- a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
+++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
@@ -399,60 +399,51 @@ export function useTimelineSyncCallbacks({
     pendingSeekRef,
   ]);
 
-  const onIframeLoad = useCallback(
-    (reportError?: (message: string) => void) => {
-      applyPreviewAudioState();
-      if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+  const onIframeLoad = useCallback(() => {
+    applyPreviewAudioState();
+    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
 
-      // Fast path: adapter already available (in-place reloads, cached compositions)
-      if (initializeAdapter()) return;
+    // Fast path: adapter already available (in-place reloads, cached compositions)
+    if (initializeAdapter()) return;
 
-      // The runtime posts "state" or "timeline" messages once ready.
-      // Listen for those instead of polling.
-      const iframe = iframeRef.current;
-      let settled = false;
+    // The runtime posts "state" or "timeline" messages once ready.
+    // Listen for those instead of polling.
+    const iframe = iframeRef.current;
+    let settled = false;
 
-      const trySettle = () => {
-        if (settled) return;
-        if (initializeAdapter()) {
-          settled = true;
-          window.removeEventListener("message", onMessage);
-          if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
-        }
-      };
-
-      const onMessage = (e: MessageEvent) => {
-        if (e.source && iframe && e.source !== iframe.contentWindow) return;
-        const data = e.data;
-        if (
-          data?.source === "hf-preview" &&
-          (data?.type === "state" || data?.type === "timeline")
-        ) {
-          // The main message handler owns protocol-error diagnostics. This readiness-only
-          // listener mirrors its acceptance gate without dispatching a duplicate event:
-          // an unsupported runtime must not make the iframe appear successfully settled.
-          if (inspectStudioRuntimeMessage(data).status === "unsupported") return;
-          trySettle();
-        }
-      };
-      window.addEventListener("message", onMessage);
-
-      // Safety net: if no message arrives within 5s, try one last time then give up.
-      probeIntervalRef.current = setTimeout(() => {
-        if (!settled) {
-          trySettle();
-          if (!settled) {
-            reportError?.("Studio could not initialize the composition timeline.");
-          }
-        }
+    const trySettle = () => {
+      if (settled) return;
+      if (initializeAdapter()) {
+        settled = true;
         window.removeEventListener("message", onMessage);
-        // Never leave the preview stuck invisible if the runtime never settled
-        // (initializeAdapter reveals on success; this covers the give-up case).
-        revealIframe(iframeRef.current);
-      }, 5000) as unknown as ReturnType<typeof setInterval>;
-    },
-    [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState],
-  );
+        if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      }
+    };
+
+    const onMessage = (e: MessageEvent) => {
+      if (e.source && iframe && e.source !== iframe.contentWindow) return;
+      const data = e.data;
+      if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        // The main message handler owns protocol-error diagnostics. This readiness-only
+        // listener mirrors its acceptance gate without dispatching a duplicate event:
+        // an unsupported runtime must not make the iframe appear successfully settled.
+        if (inspectStudioRuntimeMessage(data).status === "unsupported") return;
+        trySettle();
+      }
+    };
+    window.addEventListener("message", onMessage);
+
+    // Safety net: if no message arrives within 5s, try one last time then give up.
+    probeIntervalRef.current = setTimeout(() => {
+      if (!settled) {
+        trySettle();
+      }
+      window.removeEventListener("message", onMessage);
+      // Never leave the preview stuck invisible if the runtime never settled
+      // (initializeAdapter reveals on success; this covers the give-up case).
+      revealIframe(iframeRef.current);
+    }, 5000) as unknown as ReturnType<typeof setInterval>;
+  }, [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState]);
 
   // Stable refs so mount-effect closures always call the latest version
   const processTimelineMessageRef = { current: processTimelineMessage };
diff --git a/scripts/studio-runtime-smoke.mjs b/scripts/studio-runtime-smoke.mjs
index eb1c1a401..1a8f0e480 100644
--- a/scripts/studio-runtime-smoke.mjs
+++ b/scripts/studio-runtime-smoke.mjs
@@ -38,6 +38,7 @@ const GET_RESPONSES = new Map([
     }),
   ],
   [`${PROJECT_PATH}/preview`, text(SMOKE_COMPOSITION_HTML, "text/html")],
+  [`${PROJECT_PATH}/thumbnail/index.html`, text(SMOKE_THUMBNAIL_SVG, "image/svg+xml")],
   [`${PROJECT_PATH}/renders`, json({ renders: [] })],
   [`${PROJECT_PATH}/lint`, json({ findings: [] })],
   [
@@ -77,11 +78,6 @@ function projectPreviewResponse(pathname) {
     : text(SMOKE_COMPOSITION_HTML, "text/html");
 }
 
-function projectThumbnailResponse(pathname) {
-  if (!pathname.startsWith(`${PROJECT_PATH}/thumbnail/`)) return undefined;
-  return text(SMOKE_THUMBNAIL_SVG, "image/svg+xml");
-}
-
 function gsapAnimationsResponse(pathname) {
   if (!pathname.startsWith(`${PROJECT_PATH}/gsap-animations/`)) return undefined;
   return json({ animations: [], timelineVar: "tl", preamble: "", postamble: "" });
@@ -92,7 +88,6 @@ function getStudioSmokeResponse(pathname) {
     GET_RESPONSES.get(pathname) ??
     projectFileResponse(pathname) ??
     projectPreviewResponse(pathname) ??
-    projectThumbnailResponse(pathname) ??
     gsapAnimationsResponse(pathname)
   );
 }

From c62bd4c454d7a53aac39e03b10da8eeb2a93d77e Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 27 Jul 2026 23:55:06 -0700
Subject: [PATCH 4/4] fix(studio): harden preview recovery

---
 .../sidebar/CompositionsTab.drag.test.tsx     |  16 ++-
 .../components/sidebar/CompositionsTab.tsx    |  38 +++---
 .../src/player/components/Player.test.ts      | 110 +++++++++++++++++-
 scripts/studio-runtime-smoke.test.mjs         |   4 +-
 4 files changed, 151 insertions(+), 17 deletions(-)

diff --git a/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx b/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx
index 1a5dcd2d1..862a35722 100644
--- a/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx
+++ b/packages/studio/src/components/sidebar/CompositionsTab.drag.test.tsx
@@ -42,10 +42,23 @@ function mount(onSelect = vi.fn(), onAddToTimeline = vi.fn()) {
 describe("composition card drag", () => {
   it("uses a cached image instead of eagerly mounting a live preview iframe", () => {
     const { host } = mount();
-    expect(host.querySelector('img[src*="/thumbnail/"]')).not.toBeNull();
+    const thumbnail = host.querySelector<HTMLImageElement>('img[src*="/thumbnail/"]');
+    expect(thumbnail).not.toBeNull();
+    expect(new URL(thumbnail?.src ?? "").searchParams.get("t")).toBe("3.00");
     expect(host.querySelector("iframe")).toBeNull();
   });
 
+  it("shows a fallback when the cached thumbnail fails", () => {
+    const { host } = mount();
+    const thumbnail = host.querySelector<HTMLImageElement>('img[src*="/thumbnail/"]');
+    if (!thumbnail) throw new Error("composition thumbnail did not render");
+
+    act(() => thumbnail.dispatchEvent(new Event("error")));
+
+    expect(host.textContent).toContain("Preview unavailable");
+    expect(host.querySelector('img[src*="/thumbnail/"]')).toBeNull();
+  });
+
   it("mounts one live preview only after sustained hover and removes it on leave", () => {
     vi.useFakeTimers();
     const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
@@ -61,6 +74,7 @@ describe("composition card drag", () => {
         card.dispatchEvent(new Event("pointerout", { bubbles: true }));
       });
       expect(host.querySelector("iframe")).toBeNull();
+      expect(vi.getTimerCount()).toBe(0);
     } finally {
       consoleError.mockRestore();
       vi.useRealTimers();
diff --git a/packages/studio/src/components/sidebar/CompositionsTab.tsx b/packages/studio/src/components/sidebar/CompositionsTab.tsx
index d061fd600..5de9703db 100644
--- a/packages/studio/src/components/sidebar/CompositionsTab.tsx
+++ b/packages/studio/src/components/sidebar/CompositionsTab.tsx
@@ -132,6 +132,7 @@ function CompCard({
   const [hovered, setHovered] = useState(false);
   const [stageSize, setStageSize] = useState(DEFAULT_PREVIEW_STAGE);
   const [livePreviewLoaded, setLivePreviewLoaded] = useState(false);
+  const [thumbnailFailed, setThumbnailFailed] = useState(false);
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const syncTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -160,6 +161,10 @@ function CompCard({
       clearTimeout(hoverTimer.current);
       hoverTimer.current = null;
     }
+    if (syncTimer.current) {
+      clearTimeout(syncTimer.current);
+      syncTimer.current = null;
+    }
     setHovered(false);
     setLivePreviewLoaded(false);
   };
@@ -167,8 +172,8 @@ function CompCard({
   const previewUrl = `/api/projects/${projectId}/preview/comp/${comp}`;
   const thumbnailUrl = buildCompositionThumbnailUrl({
     previewUrl,
-    seekTime: 0,
-    duration: THUMBNAIL_SEEK_TIME_SECONDS * 2,
+    seekTime: THUMBNAIL_SEEK_TIME_SECONDS,
+    duration: 0,
     origin: window.location.origin,
   });
   const previewScale = resolveCompositionPreviewScale({
@@ -225,16 +230,23 @@ function CompCard({
       }`}
     >
       <div className="w-20 h-[45px] rounded overflow-hidden bg-neutral-900 flex-shrink-0 relative">
-        <img
-          src={thumbnailUrl}
-          alt=""
-          draggable={false}
-          loading="lazy"
-          decoding="async"
-          className={`absolute inset-0 h-full w-full object-contain transition-opacity ${
-            livePreviewLoaded ? "opacity-0" : "opacity-100"
-          }`}
-        />
+        {thumbnailFailed ? (
+          <div className="absolute inset-0 flex items-center justify-center px-1 text-center text-[8px] leading-tight text-neutral-600">
+            Preview unavailable
+          </div>
+        ) : (
+          <img
+            src={thumbnailUrl}
+            alt=""
+            draggable={false}
+            loading="lazy"
+            decoding="async"
+            onError={() => setThumbnailFailed(true)}
+            className={`absolute inset-0 h-full w-full object-contain transition-opacity ${
+              livePreviewLoaded ? "opacity-0" : "opacity-100"
+            }`}
+          />
+        )}
         {hovered && (
           <iframe
             ref={iframeRef}
@@ -353,7 +365,7 @@ export const CompositionsTab = memo(function CompositionsTab({
     <div className="flex-1 overflow-y-auto">
       {compositions.map((comp) => (
         <CompCard
-          key={comp}
+          key={`${projectId}:${comp}`}
           projectId={projectId}
           comp={comp}
           isActive={activeComposition === comp}
diff --git a/packages/studio/src/player/components/Player.test.ts b/packages/studio/src/player/components/Player.test.ts
index 516b80795..444f0199d 100644
--- a/packages/studio/src/player/components/Player.test.ts
+++ b/packages/studio/src/player/components/Player.test.ts
@@ -1,12 +1,79 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it } from "vitest";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   hasUnloadedAssets,
+  Player,
   readPreviewErrorMessage,
   shouldShowCompositionLoadingOverlay,
 } from "./Player";
 
+vi.mock("@hyperframes/player", () => ({}));
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let root: Root | null = null;
+let lifecycleLog: string[] = [];
+
+class TestHyperframesPlayer extends HTMLElement {
+  readonly iframeElement = document.createElement("iframe");
+
+  constructor() {
+    super();
+
+    const addIframeListener = this.iframeElement.addEventListener.bind(this.iframeElement);
+    this.iframeElement.addEventListener = ((type, listener, options) => {
+      lifecycleLog.push(`iframe:${type}`);
+      addIframeListener(type, listener, options);
+    }) as typeof this.iframeElement.addEventListener;
+
+    const addPlayerListener = this.addEventListener.bind(this);
+    this.addEventListener = ((type, listener, options) => {
+      lifecycleLog.push(`player:${type}`);
+      addPlayerListener(type, listener, options);
+    }) as typeof this.addEventListener;
+
+    const setPlayerAttribute = this.setAttribute.bind(this);
+    this.setAttribute = (name, value) => {
+      if (name === "src") lifecycleLog.push("src");
+      setPlayerAttribute(name, value);
+    };
+  }
+}
+
+if (!customElements.get("hyperframes-player")) {
+  customElements.define("hyperframes-player", TestHyperframesPlayer);
+}
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  lifecycleLog = [];
+  document.body.innerHTML = "";
+});
+
+async function mountPlayer() {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () => {
+    root?.render(
+      createElement(Player, {
+        directUrl: "/api/projects/demo/preview",
+        onLoad: vi.fn(),
+        suppressLoadingOverlay: true,
+      }),
+    );
+    await Promise.resolve();
+  });
+
+  const player = host.querySelector<TestHyperframesPlayer>("hyperframes-player");
+  if (!player) throw new Error("player did not mount");
+  return { host, player };
+}
+
 function createAudioIframe() {
   const iframe = document.createElement("iframe");
   document.body.appendChild(iframe);
@@ -32,6 +99,47 @@ describe("preview errors", () => {
       "The composition preview did not become ready.",
     );
   });
+
+  it("attaches lifecycle listeners before navigating the player", async () => {
+    await mountPlayer();
+    const srcIndex = lifecycleLog.indexOf("src");
+
+    expect(srcIndex).toBeGreaterThan(-1);
+    for (const listener of [
+      "iframe:load",
+      "player:click",
+      "player:shadertransitionstate",
+      "player:ready",
+      "player:error",
+    ]) {
+      expect(lifecycleLog.indexOf(listener)).toBeGreaterThan(-1);
+      expect(lifecycleLog.indexOf(listener)).toBeLessThan(srcIndex);
+    }
+  });
+
+  it("retries a failed preview with a fresh player URL", async () => {
+    const { host, player } = await mountPlayer();
+
+    act(() => {
+      player.dispatchEvent(
+        new CustomEvent("error", {
+          detail: { message: "Composition timeline not found after 8s" },
+        }),
+      );
+    });
+
+    expect(host.querySelector('[data-testid="composition-preview-error"]')).not.toBeNull();
+    const retry = Array.from(host.querySelectorAll("button")).find(
+      (button) => button.textContent === "Retry preview",
+    );
+    if (!retry) throw new Error("retry action did not render");
+
+    act(() => retry.click());
+
+    const retryUrl = new URL(player.getAttribute("src") ?? "", window.location.origin);
+    expect(retryUrl.searchParams.get("_hfStudioRetry")).toBe("1");
+    expect(host.querySelector('[data-testid="composition-preview-error"]')).toBeNull();
+  });
 });
 
 describe("composition loading overlay", () => {
diff --git a/scripts/studio-runtime-smoke.test.mjs b/scripts/studio-runtime-smoke.test.mjs
index adf1991db..3b687069b 100644
--- a/scripts/studio-runtime-smoke.test.mjs
+++ b/scripts/studio-runtime-smoke.test.mjs
@@ -8,7 +8,7 @@ import {
 
 function bodyOf(method, path) {
   const response = studioSmokeApiResponse(method, `http://localhost:5199${path}`);
-  assert.ok(response && response !== null);
+  assert.ok(response);
   return JSON.parse(response.body);
 }
 
@@ -49,7 +49,7 @@ describe("Studio runtime smoke fixtures", () => {
       "GET",
       "http://localhost:5199/api/projects/smoke-test/thumbnail/index.html?t=3",
     );
-    assert.ok(response && response !== null);
+    assert.ok(response);
     assert.equal(response.contentType, "image/svg+xml");
   });