@hyperframes/studio 0.8.56 → 0.8.57

package/src/player/components/Player.tsx

@@ -26,7 +26,11 @@ interface PlayerProps {
   projectId?: string;
   directUrl?: string;
   onLoad: () => void;
+  /** Fires once the loaded document is painted and every loader (shader, assets) has cleared. */
+  onReadyToShowChange?: (ready: boolean) => void;
+  onPreviewError?: (message: string) => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
+  onPainted?: (details: { iframe: HTMLIFrameElement; startedAt: number; loadId: number }) => void;
   portrait?: boolean;
   style?: React.CSSProperties;
   suppressLoadingOverlay?: boolean;
@@ -134,7 +138,10 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       projectId,
       directUrl,
       onLoad,
+      onReadyToShowChange,
+      onPreviewError,
       onCompositionLoadingChange,
+      onPainted,
       portrait,
       style,
       suppressLoadingOverlay,
@@ -146,13 +153,25 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
     const assetFadeRef = useRef<ReturnType<typeof setTimeout> | null>(null);
     const retryPreviewRef = useRef<(() => void) | null>(null);
+    const loadStartedAtRef = useRef(0);
+    const loadIdRef = useRef(0);
     const retryCountRef = useRef(0);
+    // Read at call time: this element outlives its first props (a shadow preview is
+    // promoted in place), so mount-time closures would go stale.
+    const onLoadRef = useRef(onLoad);
+    onLoadRef.current = onLoad;
+    const onReadyToShowChangeRef = useRef(onReadyToShowChange);
+    onReadyToShowChangeRef.current = onReadyToShowChange;
+    const onPreviewErrorRef = useRef(onPreviewError);
+    onPreviewErrorRef.current = onPreviewError;
+    const [loaded, setLoaded] = useState(false);
     const [assetsLoading, setAssetsLoading] = useState(false);
     const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
     const [assetOverlayFading, setAssetOverlayFading] = useState(false);
     const [assetWaitLong, setAssetWaitLong] = useState(false);
     const [shaderTransitionLoading, setShaderTransitionLoading] = useState(false);
     const [compositionLoading, setCompositionLoading] = useState(true);
+    const [painted, setPainted] = useState(false);
     const [compositionOverlayDeferred, setCompositionOverlayDeferred] = useState(true);
     const [previewError, setPreviewError] = useState<string | null>(null);
 
@@ -194,6 +213,8 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           retryUrl.searchParams.set("_hfStudioRetry", String(retryCountRef.current));
           setPreviewError(null);
           setCompositionLoading(true);
+          loadStartedAtRef.current = performance.now();
+          loadIdRef.current += 1;
           player.setAttribute("src", retryUrl.pathname + retryUrl.search);
         };
         retryPreviewRef.current = retryPreview;
@@ -207,15 +228,23 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           setPreviewError(null);
           setCompositionLoading(false);
         };
+        const handlePainted = () => {
+          setPainted(true);
+          onPainted?.({ iframe, startedAt: loadStartedAtRef.current, loadId: loadIdRef.current });
+        };
         const handleError = (event: Event) => {
-          setPreviewError(readPreviewErrorMessage(event));
+          const message = readPreviewErrorMessage(event);
+          onPreviewErrorRef.current?.(message);
+          setPreviewError(message);
           setCompositionLoading(false);
         };
         const handleLoad = () => {
           loadCountRef.current++;
+          setLoaded(true);
           setPreviewError(null);
           setShaderTransitionLoading(false);
           setCompositionLoading(true);
+          setPainted(false);
           // Reveal animation on reload (hot-reload, composition switch)
           if (loadCountRef.current > 1) {
             container.classList.remove("preview-revealing");
@@ -224,7 +253,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             const onEnd = () => container.classList.remove("preview-revealing");
             container.addEventListener("animationend", onEnd, { once: true });
           }
-          onLoad();
+          onLoadRef.current();
 
           // Show a loading overlay until every `<video>`/`<audio>` and Lottie
           // asset is ready. Without this users can click play before audio has
@@ -274,6 +303,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         player.addEventListener("click", preventToggle, { capture: true });
         player.addEventListener("shadertransitionstate", handleShaderTransitionState);
         player.addEventListener("ready", handleReady);
+        player.addEventListener("painted", handlePainted);
         player.addEventListener("error", handleError);
 
         // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
@@ -291,6 +321,8 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         player.style.height = "100%";
         player.style.display = "block";
         player.style.background = "transparent";
+        loadStartedAtRef.current = performance.now();
+        loadIdRef.current += 1;
         player.setAttribute("src", src);
         container.appendChild(player);
 
@@ -313,6 +345,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           player.removeEventListener("click", preventToggle, { capture: true });
           player.removeEventListener("shadertransitionstate", handleShaderTransitionState);
           player.removeEventListener("ready", handleReady);
+          player.removeEventListener("painted", handlePainted);
           player.removeEventListener("error", handleError);
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
@@ -394,6 +427,29 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       setAssetsLoading(false);
     };
 
+    const readyToShow =
+      loaded &&
+      painted &&
+      !compositionLoading &&
+      !shaderTransitionLoading &&
+      !assetsLoading &&
+      !previewError;
+    // `painted` means the player's own loader has finished fading; two frames of grace on top.
+    useEffect(() => {
+      if (!readyToShow) {
+        onReadyToShowChangeRef.current?.(false);
+        return;
+      }
+      let second = 0;
+      const first = requestAnimationFrame(() => {
+        second = requestAnimationFrame(() => onReadyToShowChangeRef.current?.(true));
+      });
+      return () => {
+        cancelAnimationFrame(first);
+        cancelAnimationFrame(second);
+      };
+    }, [readyToShow]);
+
     const showCompositionOverlay =
       !suppressLoadingOverlay &&
       !compositionOverlayDeferred &&

package/src/player/components/ShortcutsPanel.test.tsx

@@ -1,24 +1,18 @@
 // @vitest-environment happy-dom
 
 import React, { act, Profiler } from "react";
-import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { ShortcutsPanel } from "./ShortcutsPanel";
+import { createHappyDomRootHarness } from "./testRootHarness";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-const roots: Root[] = [];
-
-afterEach(() => {
-  for (const root of roots.splice(0)) act(() => root.unmount());
-  document.body.innerHTML = "";
-});
+const { mount } = createHappyDomRootHarness();
 
 function renderPanel(onRender = vi.fn()) {
   const host = document.createElement("div");
   document.body.append(host);
-  const root = createRoot(host);
-  roots.push(root);
+  const root = mount(host);
   act(() => {
     root.render(
       <Profiler id="shortcuts-panel" onRender={onRender}>