@hyperframes/studio 0.8.55 → 0.8.57

package/src/hooks/useTimelineEditing.ts

@@ -25,7 +25,6 @@ import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
-import { useTimelineRowElements } from "../player/hooks/useTimelineRowElements";
 import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
 import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
@@ -77,10 +76,6 @@ export function useTimelineEditing({
   const checkEditable = useTimelineEditGate(canEdit, showToast);
   const checkEditableRef = useRef(checkEditable);
   checkEditableRef.current = checkEditable;
-  // Same expanded-row source the hide handlers themselves resolve against
-  // (timelineTrackVisibility.ts) — a virtual sub-comp child's track/key
-  // only exists here, not in the raw store list canEdit would otherwise miss.
-  const timelineRowElements = useTimelineRowElements();
   const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());
   // Refuses (no call, no write, no history entry) when any target is
   // blocked; otherwise runs fn as before. Cached by fn identity — like
@@ -514,14 +509,14 @@ export function useTimelineEditing({
     handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),
     handleToggleTrackHidden: track(
       guard(
-        (trackIndex) => timelineRowElements.filter((el) => el.track === trackIndex),
+        (trackIndex) => timelineElements.filter((el) => el.track === trackIndex),
         handleToggleTrackHidden,
       ),
     ),
     handleToggleElementHidden: track(
       guard((elementKey) => {
         const keys = new Set(Array.isArray(elementKey) ? elementKey : [elementKey]);
-        return timelineRowElements.filter((el) => keys.has(el.key ?? el.id));
+        return timelineElements.filter((el) => keys.has(el.key ?? el.id));
       }, handleToggleElementHidden),
     ),
     handleAutoGroupCarveSources: track(handleAutoGroupCarveSources),

package/src/index.ts

@@ -56,6 +56,18 @@ export type { TimelineElement, TimelineTimeRange } from "./player";
 // Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
 export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
 export type { PreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
+export {
+  PreviewOverlayProvider,
+  usePreviewOverlayContext,
+} from "./components/editor/PreviewOverlayProvider";
+export type {
+  PreviewOverlayProviderProps,
+  PreviewSnapPreferences,
+} from "./components/editor/PreviewOverlayProvider";
+export { PreviewGuides } from "./components/editor/PreviewGuides";
+export { GridOverlay } from "./components/editor/GridOverlay";
+export { SnapToolbar } from "./components/editor/SnapToolbar";
+export { usePreviewGuidesStore } from "./components/editor/previewGuidesStore";
 
 // Editor
 export { SourceEditor } from "./components/editor/SourceEditor";

package/src/player/components/Player.test.ts

@@ -54,26 +54,37 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
-async function mountPlayer() {
+type PlayerProps = Parameters<typeof Player>[0];
+
+async function mountPlayer(props: Partial<PlayerProps> = {}) {
   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 render = () =>
+    act(async () => {
+      root?.render(
+        createElement(Player, {
+          directUrl: "/api/projects/demo/preview",
+          onLoad: vi.fn(),
+          suppressLoadingOverlay: true,
+          ...props,
+        }),
+      );
+      await Promise.resolve();
+    });
+  await render();
 
   const player = host.querySelector<TestHyperframesPlayer>("hyperframes-player");
   if (!player) throw new Error("player did not mount");
-  return { host, player };
+  const rerender = (next: Partial<PlayerProps>) => {
+    Object.assign(props, next);
+    return render();
+  };
+  return { host, player, rerender };
 }
 
+const twoFrames = () => act(async () => void (await new Promise((r) => setTimeout(r, 80))));
+
 function createAudioIframe() {
   const iframe = document.createElement("iframe");
   document.body.appendChild(iframe);
@@ -123,6 +134,7 @@ describe("preview errors", () => {
       "player:click",
       "player:shadertransitionstate",
       "player:ready",
+      "player:painted",
       "player:error",
     ]) {
       expect(lifecycleLog.indexOf(listener)).toBeGreaterThan(-1);
@@ -131,7 +143,10 @@ describe("preview errors", () => {
   });
 
   it("retries a failed preview with a fresh player URL", async () => {
-    const { host, player } = await mountPlayer();
+    const onPainted = vi.fn();
+    const { host, player } = await mountPlayer({ onPainted });
+
+    act(() => void player.dispatchEvent(new Event("painted")));
 
     act(() => {
       player.dispatchEvent(
@@ -152,6 +167,119 @@ describe("preview errors", () => {
     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();
+
+    act(() => void player.dispatchEvent(new Event("painted")));
+    expect(onPainted.mock.calls.map(([details]) => details.loadId)).toEqual([1, 2]);
+  });
+});
+
+describe("callbacks after the player is already mounted", () => {
+  it("runs the latest onLoad on a later load, not the one captured at mount", async () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { player, rerender } = await mountPlayer({ onLoad: first });
+    await rerender({ onLoad: second });
+
+    act(
+      () => void (player as TestHyperframesPlayer).iframeElement.dispatchEvent(new Event("load")),
+    );
+
+    expect(second).toHaveBeenCalledTimes(1);
+    expect(first).not.toHaveBeenCalled();
+  });
+
+  it("reports the preview error cause", async () => {
+    const onPreviewError = vi.fn();
+    const { player } = await mountPlayer({ onPreviewError });
+    act(() => {
+      player.dispatchEvent(new CustomEvent("error", { detail: { message: "boom" } }));
+    });
+    expect(onPreviewError).toHaveBeenCalledWith("boom");
+  });
+});
+
+describe("ready to show", () => {
+  const loadAndReady = (player: TestHyperframesPlayer) =>
+    act(() => {
+      player.iframeElement.dispatchEvent(new Event("load"));
+      player.dispatchEvent(new Event("ready"));
+    });
+  const shaderState = (player: TestHyperframesPlayer, loading: boolean) =>
+    act(() => {
+      player.dispatchEvent(
+        new CustomEvent("shadertransitionstate", {
+          detail: { state: { loading, ready: !loading } },
+        }),
+      );
+    });
+
+  const painted = (player: TestHyperframesPlayer) =>
+    act(() => void player.dispatchEvent(new Event("painted")));
+
+  it("promotes only once the player reports painted, not at ready or assetsready", async () => {
+    const onReadyToShowChange = vi.fn();
+    const { player } = await mountPlayer({ onReadyToShowChange });
+    const el = player as TestHyperframesPlayer;
+
+    loadAndReady(el);
+    await twoFrames();
+    expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+
+    act(() => void el.dispatchEvent(new Event("assetsready")));
+    await twoFrames();
+    expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+
+    painted(el);
+    await twoFrames();
+    expect(onReadyToShowChange).toHaveBeenLastCalledWith(true);
+
+    act(() => void el.iframeElement.dispatchEvent(new Event("load")));
+    expect(onReadyToShowChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it("reports the document start time with the painted iframe", async () => {
+    const onPainted = vi.fn();
+    const now = vi.spyOn(performance, "now").mockReturnValue(100);
+    const { player } = await mountPlayer({ onPainted });
+
+    painted(player as TestHyperframesPlayer);
+
+    expect(onPainted).toHaveBeenCalledWith({
+      iframe: (player as TestHyperframesPlayer).iframeElement,
+      startedAt: 100,
+      loadId: 1,
+    });
+    now.mockRestore();
+  });
+
+  it("holds while the shader transition loader is up and fires once it clears", async () => {
+    const onReadyToShowChange = vi.fn();
+    const { player } = await mountPlayer({ onReadyToShowChange });
+    const el = player as TestHyperframesPlayer;
+
+    shaderState(el, true);
+    loadAndReady(el);
+    shaderState(el, true);
+    await twoFrames();
+    expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+
+    shaderState(el, false);
+    painted(el);
+    await twoFrames();
+    expect(onReadyToShowChange).toHaveBeenLastCalledWith(true);
+
+    shaderState(el, true);
+    expect(onReadyToShowChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it("does not fire for a document that failed to load", async () => {
+    const onReadyToShowChange = vi.fn();
+    const { player } = await mountPlayer({ onReadyToShowChange });
+    act(() => {
+      player.dispatchEvent(new CustomEvent("error", { detail: { message: "boom" } }));
+    });
+    await twoFrames();
+    expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
   });
 });
 

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}>