@hyperframes/studio 0.8.144 → 0.8.145

package/dist/player.js

@@ -1,8 +1,8 @@
 import {
   Player
-} from "./chunk-G3EDKRZH.js";
+} from "./chunk-NZPJUZKT.js";
 import "./chunk-Y2OHHNM2.js";
-import "./chunk-3GHTHPZD.js";
+import "./chunk-6JY3MTIX.js";
 import "./chunk-PZ5AY32C.js";
 export {
   Player

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.144",
+  "version": "0.8.145",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.144",
-    "@hyperframes/parsers": "0.8.144",
-    "@hyperframes/sdk": "0.8.144",
-    "@hyperframes/player": "0.8.144",
-    "@hyperframes/shader-transitions": "0.8.144",
-    "@hyperframes/studio-server": "0.8.144"
+    "@hyperframes/core": "0.8.145",
+    "@hyperframes/sdk": "0.8.145",
+    "@hyperframes/player": "0.8.145",
+    "@hyperframes/shader-transitions": "0.8.145",
+    "@hyperframes/parsers": "0.8.145",
+    "@hyperframes/studio-server": "0.8.145"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -82,7 +82,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.144"
+    "@hyperframes/producer": "0.8.145"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/StudioLeftPanels.tsx

@@ -75,8 +75,8 @@ export const StudioLeftPanels = memo(function StudioLeftPanels({
         return;
       }
       await waitForPendingDomEditSaves();
-      const { format, quality, fps } = getPersistedRenderSettings();
-      await renderQueue.startRender({ composition: comp, format, quality, fps });
+      const { format, quality, fps, gpu } = getPersistedRenderSettings();
+      await renderQueue.startRender({ composition: comp, format, quality, fps, gpu });
     },
     [renderQueue, waitForPendingDomEditSaves],
   );

package/src/components/editor/LayersPanel.test.ts

@@ -9,7 +9,7 @@ import type { DomEditLayerItem } from "./domEditingTypes";
 import { createRafThrottle, LayersPanel, sortLayersByZIndex } from "./LayersPanel";
 import { isLayerDraggable } from "./useLayerDrag";
 import { liveTime } from "../../player";
-import { sceneSwapFor } from "../../player/sceneSwap";
+import { announcePreviewDocumentLoaded, sceneSwapFor } from "../../player/sceneSwap";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -284,12 +284,12 @@ describe("LayersPanel preview promotion", () => {
     mocks.collect.mockClear();
 
     act(() => {
-      a.dispatchEvent(new Event("load"));
+      announcePreviewDocumentLoaded(a);
     });
     expect(mocks.collect).not.toHaveBeenCalled();
 
     act(() => {
-      b.dispatchEvent(new Event("load"));
+      announcePreviewDocumentLoaded(b);
     });
     expect(collectedRootIds()).toEqual(["b"]);
   });
@@ -325,7 +325,7 @@ describe("LayersPanel preview promotion", () => {
     mocks.previewIframeRef.current = iframe;
     usePreviewIframeStore.setState({ iframe });
     act(() => root.render(createElement(LayersPanel)));
-    act(() => void iframe.dispatchEvent(new Event("load")));
+    act(() => void announcePreviewDocumentLoaded(iframe));
 
     const rows = [...host.querySelectorAll("[data-layer-index]")];
     expect(rows).toHaveLength(2);

package/src/components/editor/LayersPanel.tsx

@@ -89,8 +89,8 @@ interface CollapsedState {
   [key: string]: boolean;
 }
 
-/** Studio state the panel reads; passed by hosts outside Studio's providers. Keep previewIframeRef stable,
- * and bump refreshKey when the preview document is rebuilt without an iframe load. */
+/** Studio state the panel reads; passed by hosts outside Studio's providers. Keep previewIframeRef stable;
+ * a host with its own player calls announcePreviewDocumentLoaded on each new page, or bumps refreshKey. */
 export type LayersPanelHost = Pick<
   StudioShellValue,
   "previewIframeRef" | "activeCompPath" | "showToast"

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

@@ -5,6 +5,7 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { studioEditLifecycle, type StudioWriteResult } from "../../webmcp/writeCoordinator";
 import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import { announcePreviewDocumentLoaded } from "../../player/sceneSwap";
 import { TopologyLens } from "./TopologyLens";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -259,7 +260,7 @@ describe("TopologyLens", () => {
     mount();
     begin();
 
-    act(() => iframe?.dispatchEvent(new Event("load")));
+    act(() => announcePreviewDocumentLoaded(iframe!));
     expect(host?.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
 
     begin();
@@ -286,7 +287,7 @@ describe("TopologyLens", () => {
     root = null;
 
     expect(vi.getTimerCount()).toBe(1);
-    expect(removeListener).toHaveBeenCalledWith("load", expect.any(Function));
+    expect(removeListener).toHaveBeenCalledWith("hf-preview-document-loaded", expect.any(Function));
     expect(studioEditLifecycle.getSnapshot()).toMatchObject({ phase: "dispatching" });
     act(() => vi.advanceTimersByTime(0));
     expect(vi.getTimerCount()).toBe(0);
@@ -312,10 +313,10 @@ describe("TopologyLens", () => {
       ref.current = b;
       usePreviewIframeStore.getState().setIframe(b);
     });
-    act(() => a.dispatchEvent(new Event("load")));
+    act(() => announcePreviewDocumentLoaded(a));
     expect(host.querySelector('[data-topology-lens="hidden"]')).toBeNull();
 
-    act(() => b.dispatchEvent(new Event("load")));
+    act(() => announcePreviewDocumentLoaded(b));
     expect(host.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
     usePreviewIframeStore.setState({ iframe: null });
   });

package/src/components/renders/GpuEncodingToggle.tsx

@@ -0,0 +1,28 @@
+export function GpuEncodingToggle({
+  format,
+  checked,
+  disabled,
+  onToggle,
+}: {
+  format: "mp4" | "webm" | "mov";
+  checked: boolean;
+  disabled: boolean;
+  onToggle: () => void;
+}) {
+  // GPU encoders exist for H.264/H.265 only, so only MP4 can use one.
+  if (format !== "mp4") return null;
+  return (
+    <label
+      className={`flex items-center gap-2 text-step-10 text-text-4 ${disabled ? "opacity-40 cursor-not-allowed" : "cursor-pointer"}`}
+    >
+      <input
+        type="checkbox"
+        checked={checked}
+        disabled={disabled}
+        onChange={onToggle}
+        className="accent-studio-accent"
+      />
+      <span>Use GPU encoding</span>
+    </label>
+  );
+}

package/src/components/renders/RenderQueue.test.tsx

@@ -142,7 +142,7 @@ describe("RenderQueue controls", () => {
       exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
     });
 
-    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "landscape-4k", 30);
+    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "landscape-4k", 30, false);
   });
 
   it("refuses a resolution the composition cannot reach, and says why", async () => {
@@ -172,7 +172,23 @@ describe("RenderQueue controls", () => {
       exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
     });
 
-    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30);
+    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30, false);
+  });
+
+  it("exports with GPU encoding once the box is ticked, and remembers it", () => {
+    const onStartRender: Mock<StartRenderHandler> = vi.fn();
+    const host = mountRenderQueue(onStartRender);
+    const gpu = [...host.querySelectorAll("label")].find((label) =>
+      label.textContent?.includes("Use GPU encoding"),
+    );
+
+    act(() => gpu?.querySelector("input")?.click());
+    act(() => {
+      exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30, true);
+    expect(getPersistedRenderSettings().gpu).toBe(true);
   });
 
   it("persists a changed format as the literal union value", async () => {
@@ -185,7 +201,9 @@ describe("RenderQueue controls", () => {
       format: "mov",
       quality: "standard",
       fps: 30,
+      gpu: false,
     });
+    expect(host.textContent).not.toContain("Use GPU encoding");
   });
 });
 

package/src/components/renders/RenderQueue.tsx

@@ -11,6 +11,7 @@ import { Tooltip } from "../ui/Tooltip";
 import { resolveFloatingPanelPosition, type FloatingPosition } from "../editor/floatingPanel";
 import type { RenderJob, ResolutionPreset } from "./useRenderQueue";
 import { getPersistedRenderSettings, persistRenderSettings } from "./renderSettings";
+import { GpuEncodingToggle } from "./GpuEncodingToggle";
 import { trackStudioEvent } from "../../utils/studioTelemetry";
 
 export interface CompositionDimensions {
@@ -23,6 +24,7 @@ export type StartRenderHandler = (
   quality: "draft" | "standard" | "high",
   resolution: ResolutionPreset | "auto",
   fps: 24 | 30 | 60,
+  gpu?: boolean,
 ) => void | Promise<void>;
 
 export interface RenderQueueProps {
@@ -303,6 +305,7 @@ function FormatExportButton({
   const [quality, setQuality] = useState<"draft" | "standard" | "high">(persisted.quality);
   const [resolution, setResolution] = useState<RenderScale>("auto");
   const [fps, setFps] = useState<24 | 30 | 60>(persisted.fps);
+  const [gpu, setGpu] = useState(persisted.gpu);
 
   // Only a definite "not installed" blocks Export. A null status means the
   // probe gave no answer, and refusing to export on no answer would break
@@ -385,6 +388,15 @@ function FormatExportButton({
           </div>
         )}
       </div>
+      <GpuEncodingToggle
+        format={format}
+        checked={gpu}
+        disabled={isRendering}
+        onToggle={() => {
+          setGpu(!gpu);
+          persistRenderSettings(format, quality, fps, !gpu);
+        }}
+      />
       <Button
         variant="primary"
         size="md"
@@ -398,7 +410,7 @@ function FormatExportButton({
           if (isRendering || missingFfmpeg) return;
           const outputResolution = resolveResolution(resolution, compositionDimensions);
           trackStudioEvent("render_start", { format, quality, resolution: outputResolution, fps });
-          void onStartRender(format, quality, outputResolution, fps);
+          void onStartRender(format, quality, outputResolution, fps, gpu);
         }}
         // Width only. A type size or a weight here would win the merge against
         // the size recipe and leave this Export a step away from the header's

package/src/components/renders/RenderQueuePanel.tsx

@@ -29,7 +29,7 @@ export const RenderQueuePanel = memo(function RenderQueuePanel() {
       ffmpeg={renderQueue.ffmpeg}
       ffmpegChecking={renderQueue.ffmpegChecking}
       onRecheckFfmpeg={renderQueue.recheckFfmpeg}
-      onStartRender={async (format, quality, resolution, fps) => {
+      onStartRender={async (format, quality, resolution, fps, gpu) => {
         await waitForPendingDomEditSaves();
         // No `composition`: startRender targets the active one by default.
         await renderQueue.startRender({
@@ -37,6 +37,7 @@ export const RenderQueuePanel = memo(function RenderQueuePanel() {
           quality,
           format,
           resolution,
+          gpu,
           // Render what the user is previewing: active variable overrides
           // from the Variables panel ride along (undefined = defaults).
           variables: usePreviewVariablesStore.getState().values ?? undefined,

package/src/components/renders/renderSettings.ts

@@ -4,6 +4,7 @@ export interface PersistedRenderSettings {
   format: "mp4" | "webm" | "mov";
   quality: "draft" | "standard" | "high";
   fps: 24 | 30 | 60;
+  gpu: boolean;
 }
 
 export function getPersistedRenderSettings(): PersistedRenderSettings {
@@ -17,21 +18,23 @@ export function getPersistedRenderSettings(): PersistedRenderSettings {
           ? parsed.quality
           : "standard",
         fps: [24, 30, 60].includes(parsed.fps) ? parsed.fps : 30,
+        gpu: parsed.gpu === true,
       };
     }
   } catch {
     /* ignore */
   }
-  return { format: "mp4", quality: "standard", fps: 30 };
+  return { format: "mp4", quality: "standard", fps: 30, gpu: false };
 }
 
 export function persistRenderSettings(
   format: PersistedRenderSettings["format"],
   quality: PersistedRenderSettings["quality"],
   fps: PersistedRenderSettings["fps"],
+  gpu: boolean = getPersistedRenderSettings().gpu,
 ): void {
   try {
-    localStorage.setItem(RENDER_SETTINGS_KEY, JSON.stringify({ format, quality, fps }));
+    localStorage.setItem(RENDER_SETTINGS_KEY, JSON.stringify({ format, quality, fps, gpu }));
   } catch {
     /* ignore */
   }

package/src/components/renders/useRenderQueue.ts

@@ -32,6 +32,7 @@ export interface StartRenderOptions {
   format?: "mp4" | "webm" | "mov";
   /** `"auto"` (default) renders at the composition's authored dimensions. */
   resolution?: ResolutionPreset | "auto";
+  gpu?: boolean;
   /**
    * Render a specific composition file. Omit it to render the composition the
    * user currently has open — only the sidebar's per-composition Render button
@@ -234,6 +235,7 @@ export function useRenderQueue(
         resolution?: string;
         composition?: string;
         variables?: Record<string, unknown>;
+        gpu?: boolean;
         telemetryDistinctId?: string;
         telemetryOptOut?: boolean;
       } = {
@@ -258,6 +260,7 @@ export function useRenderQueue(
       }
       if (resolution && resolution !== "auto") body.resolution = resolution;
       if (composition) body.composition = composition;
+      if (opts.gpu) body.gpu = true;
       if (opts.variables && Object.keys(opts.variables).length > 0) {
         body.variables = opts.variables;
       }

package/src/components/renders/useRenderQueueComposition.test.tsx

@@ -53,3 +53,15 @@ describe("render target composition", () => {
     expect(body["composition"]).toBeUndefined();
   });
 });
+
+describe("GPU encoding", () => {
+  it("asks the server for GPU encoding when the export asks for it", async () => {
+    const body = await renderBody(null, { format: "mp4", gpu: true });
+    expect(body["gpu"]).toBe(true);
+  });
+
+  it("leaves GPU encoding off by default", async () => {
+    const body = await renderBody(null, { format: "mp4" });
+    expect(body["gpu"]).toBeUndefined();
+  });
+});

package/src/hooks/useConsoleErrorCapture.test.tsx

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, expect, it } from "vitest";
 import { STUDIO_PREVIEW_ERRORS } from "@hyperframes/core/studio-preview-mark";
+import { announcePreviewDocumentLoaded } from "../player/sceneSwap";
 import { useConsoleErrorCapture } from "./useConsoleErrorCapture";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
@@ -36,7 +37,7 @@ it("shows the errors a preview raised before its load, once each", async () => {
   root = createRoot(document.createElement("div"));
   await act(async () => root?.render(React.createElement(Harness, { iframe })));
   Object.assign(previewWindow, { [STUDIO_PREVIEW_ERRORS]: [raisedBeforeLoad] });
-  await act(async () => iframe.dispatchEvent(new Event("load")));
+  await act(async () => announcePreviewDocumentLoaded(iframe));
 
   expect(shown()).toEqual([raisedBeforeLoad]);
 });
@@ -79,9 +80,27 @@ it("clears a document's errors when its load replaces it, and when the preview g
     previewWindow.dispatchEvent(new ErrorEvent("error", { message: "Uncaught Error: old" })),
   );
   Object.assign(previewWindow, { [STUDIO_PREVIEW_ERRORS]: ["Uncaught Error: new"] });
-  await act(async () => iframe.dispatchEvent(new Event("load")));
+  await act(async () => announcePreviewDocumentLoaded(iframe));
   expect(shown()).toEqual(["Uncaught Error: new"]);
 
   await act(async () => root?.render(React.createElement(NullableHarness, { frame: null })));
   expect(capture.consoleErrors).toBeNull();
+  await act(async () => announcePreviewDocumentLoaded(iframe));
+  expect(capture.consoleErrors).toBeNull();
+});
+
+it("keeps a page's errors through its own late load, and clears them for the next announced page", async () => {
+  const { iframe, previewWindow } = previewFrame();
+  root = createRoot(document.createElement("div"));
+  await act(async () => root?.render(React.createElement(Harness, { iframe })));
+  await act(async () =>
+    previewWindow.dispatchEvent(new ErrorEvent("error", { message: "Uncaught Error: kept" })),
+  );
+
+  await act(async () => iframe.dispatchEvent(new Event("load")));
+  expect(shown()).toEqual(["Uncaught Error: kept"]);
+
+  Object.assign(previewWindow, { [STUDIO_PREVIEW_ERRORS]: ["Uncaught Error: new page"] });
+  await act(async () => announcePreviewDocumentLoaded(iframe));
+  expect(shown()).toEqual(["Uncaught Error: new page"]);
 });

package/src/hooks/useConsoleErrorCapture.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { STUDIO_PREVIEW_ERRORS } from "@hyperframes/core/studio-preview-mark";
+import { onPreviewDocumentLoaded } from "../player/sceneSwap";
 import type { LintFinding } from "../components/LintModal";
 
 /**
@@ -73,9 +74,9 @@ export function useConsoleErrorCapture(previewIframe: HTMLIFrameElement | null)
     };
 
     attachErrorCapture();
-    previewIframe.addEventListener("load", attachErrorCapture);
+    const stopLoaded = onPreviewDocumentLoaded(previewIframe, attachErrorCapture);
     return () => {
-      previewIframe.removeEventListener("load", attachErrorCapture);
+      stopLoaded();
       detachErrorCapture();
     };
   }, [previewIframe, resetErrors]);

package/src/index.ts

@@ -202,6 +202,7 @@ export type { UseClipboardOptions } from "./hooks/useClipboard";
 export { useDomEditSession } from "./hooks/useDomEditSession";
 export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
 export { useLivePreviewIframe } from "./hooks/useLivePreviewIframe";
+export { announcePreviewDocumentLoaded } from "./player/sceneSwap";
 export type { PreviewPromotion } from "./player/sceneSwap";
 export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 export type { UsePreviewPersistenceParams } from "./hooks/usePreviewPersistence";

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

@@ -10,6 +10,7 @@ import {
   shouldShowCompositionLoadingOverlay,
 } from "./Player";
 import { usePlayerStore } from "../store/playerStore";
+import { onPreviewDocumentLoaded } from "../sceneSwap";
 
 vi.mock("@hyperframes/player", () => ({}));
 
@@ -196,6 +197,49 @@ describe("callbacks after the player is already mounted", () => {
     expect(first).not.toHaveBeenCalled();
   });
 
+  it("loads the preview on the runtime's ready while a stalled font holds the window's load", async () => {
+    const onLoad = vi.fn();
+    const { player } = await mountPlayer({ onLoad });
+    const iframe = (player as TestHyperframesPlayer).iframeElement;
+    let page = {};
+    Object.defineProperty(iframe, "contentDocument", { get: () => page });
+    Object.defineProperty(iframe, "contentWindow", { get: () => ({ __playerReady: true }) });
+    const announced = vi.fn();
+    onPreviewDocumentLoaded(iframe, announced);
+
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    act(() => void iframe.dispatchEvent(new Event("load")));
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    page = {};
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(2);
+    expect(announced).toHaveBeenCalledTimes(2);
+  });
+
+  it("leaves a ready that arrives before the page's runtime boots to the page's own load", async () => {
+    const onLoad = vi.fn();
+    const { player } = await mountPlayer({ onLoad });
+    const iframe = (player as TestHyperframesPlayer).iframeElement;
+    const page = {};
+    let runtime: { __playerReady?: boolean } = {};
+    Object.defineProperty(iframe, "contentDocument", { get: () => page });
+    Object.defineProperty(iframe, "contentWindow", { get: () => runtime });
+
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).not.toHaveBeenCalled();
+
+    act(() => void iframe.dispatchEvent(new Event("load")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    runtime = { __playerReady: true };
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+  });
+
   it("reports the preview error cause", async () => {
     const onPreviewError = vi.fn();
     const { player } = await mountPlayer({ onPreviewError });

package/src/player/components/Player.tsx

@@ -5,6 +5,8 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { HyperframesLoader } from "../../components/ui";
 import { usePlayerStore } from "../store/playerStore";
+import { announcePreviewDocumentLoaded } from "../sceneSwap";
+import type { IframeWindow } from "../lib/playbackTypes";
 // Importing "@hyperframes/player" registers a class extending HTMLElement at
 // module load, which throws under SSR, hence the dynamic import behind a
 // `typeof window` guard. Kicking it here rather than in the mount effect puts
@@ -128,6 +130,9 @@ export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean
   }
 }
 
+const runtimeBootedIn = (iframe: HTMLIFrameElement) =>
+  (iframe.contentWindow as IframeWindow | null)?.__playerReady === true;
+
 /**
  * Renders a composition preview using the <hyperframes-player> web component.
  *
@@ -228,9 +233,11 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           const loading = getShaderTransitionLoading(event);
           if (loading !== null) setShaderTransitionLoading(loading);
         };
+        let loadedDocument: Document | null = null;
         const handleReady = () => {
           setPreviewError(null);
           setCompositionLoading(false);
+          if (iframe.contentDocument && runtimeBootedIn(iframe)) handleLoad();
         };
         const handlePainted = () => {
           setPainted(true);
@@ -243,6 +250,9 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           setCompositionLoading(false);
         };
         const handleLoad = () => {
+          const doc = iframe.contentDocument;
+          if (doc && doc === loadedDocument) return;
+          loadedDocument = doc;
           loadCountRef.current++;
           setLoaded(true);
           setPreviewError(null);
@@ -258,6 +268,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             container.addEventListener("animationend", onEnd, { once: true });
           }
           onLoadRef.current();
+          announcePreviewDocumentLoaded(iframe);
 
           // Show a loading overlay until every `<video>`/`<audio>` and Lottie
           // asset is ready. Without this users can click play before audio has

package/src/player/lib/playbackTypes.ts

@@ -59,6 +59,7 @@ export interface ClipManifest {
 
 export type IframeWindow = Window & {
   __player?: RuntimePlaybackAdapter;
+  __playerReady?: boolean;
   __timeline?: TimelineLike;
   __timelines?: Record<string, TimelineLike>;
   __clipManifest?: ClipManifest;

package/src/player/sceneSwap.test.ts

@@ -1,6 +1,11 @@
 // @vitest-environment happy-dom
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { SCENE_SWAP_MS, sceneSwapFor } from "./sceneSwap";
+import {
+  SCENE_SWAP_MS,
+  announcePreviewDocumentLoaded,
+  onPreviewContentReplaced,
+  sceneSwapFor,
+} from "./sceneSwap";
 
 afterEach(() => {
   vi.useRealTimers();
@@ -93,3 +98,24 @@ describe("sceneSwapFor", () => {
     expect(swap).toHaveBeenCalledWith("<html></html>", expect.anything());
   });
 });
+
+describe("onPreviewContentReplaced", () => {
+  it("reports Player's document-loaded announcement and a scene swap, never a raw load", () => {
+    const iframe = document.createElement("iframe");
+    const replaced = vi.fn();
+    const stop = onPreviewContentReplaced(iframe, replaced);
+
+    iframe.dispatchEvent(new Event("load"));
+    expect(replaced).not.toHaveBeenCalled();
+
+    announcePreviewDocumentLoaded(iframe);
+    expect(replaced).toHaveBeenCalledTimes(1);
+
+    iframe.dispatchEvent(new Event("hf-scenes-swapped"));
+    expect(replaced).toHaveBeenCalledTimes(2);
+
+    stop();
+    announcePreviewDocumentLoaded(iframe);
+    expect(replaced).toHaveBeenCalledTimes(2);
+  });
+});

package/src/player/sceneSwap.ts

@@ -6,14 +6,28 @@ type SwapWindow = Window & {
 const SCENES_SWAPPED = "hf-scenes-swapped";
 export const SCENE_SWAP_MS = 5000;
 
+const PREVIEW_DOCUMENT_LOADED = "hf-preview-document-loaded";
+
+export function announcePreviewDocumentLoaded(iframe: HTMLIFrameElement): void {
+  iframe.dispatchEvent(new Event(PREVIEW_DOCUMENT_LOADED));
+}
+
+export function onPreviewDocumentLoaded(
+  iframe: HTMLIFrameElement,
+  onLoaded: () => void,
+): () => void {
+  iframe.addEventListener(PREVIEW_DOCUMENT_LOADED, onLoaded);
+  return () => iframe.removeEventListener(PREVIEW_DOCUMENT_LOADED, onLoaded);
+}
+
 export function onPreviewContentReplaced(
   iframe: HTMLIFrameElement,
   onReplaced: () => void,
 ): () => void {
-  iframe.addEventListener("load", onReplaced);
+  const stopLoaded = onPreviewDocumentLoaded(iframe, onReplaced);
   iframe.addEventListener(SCENES_SWAPPED, onReplaced);
   return () => {
-    iframe.removeEventListener("load", onReplaced);
+    stopLoaded();
     iframe.removeEventListener(SCENES_SWAPPED, onReplaced);
   };
 }