Skip to content

Write HTML. Render video. Built for agents.

fix(studio): a stalled font or asset no longer leaves the preview empty or drops reloads (#5370)

Miguel Ángeld93b7697635c
diff --git a/packages/studio/src/components/editor/LayersPanel.test.ts b/packages/studio/src/components/editor/LayersPanel.test.ts
index e93e9c1e78..3bde10c9f9 100644
--- a/packages/studio/src/components/editor/LayersPanel.test.ts
+++ b/packages/studio/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);
diff --git a/packages/studio/src/components/editor/LayersPanel.tsx b/packages/studio/src/components/editor/LayersPanel.tsx
index 06ae66c3fe..793c9bb493 100644
--- a/packages/studio/src/components/editor/LayersPanel.tsx
+++ b/packages/studio/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"
diff --git a/packages/studio/src/components/editor/TopologyLens.test.tsx b/packages/studio/src/components/editor/TopologyLens.test.tsx
index 05f1ce866c..d5ee10faf4 100644
--- a/packages/studio/src/components/editor/TopologyLens.test.tsx
+++ b/packages/studio/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 });
});
diff --git a/packages/studio/src/hooks/useConsoleErrorCapture.test.tsx b/packages/studio/src/hooks/useConsoleErrorCapture.test.tsx
index ce7f2c3363..5543344797 100644
--- a/packages/studio/src/hooks/useConsoleErrorCapture.test.tsx
+++ b/packages/studio/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"]);
});
diff --git a/packages/studio/src/hooks/useConsoleErrorCapture.ts b/packages/studio/src/hooks/useConsoleErrorCapture.ts
index 8eb2f4ef48..f4d416927d 100644
--- a/packages/studio/src/hooks/useConsoleErrorCapture.ts
+++ b/packages/studio/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]);
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 519317c784..c7771dc229 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/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";
diff --git a/packages/studio/src/player/components/Player.test.ts b/packages/studio/src/player/components/Player.test.ts
index b120f6ed36..c211873331 100644
--- a/packages/studio/src/player/components/Player.test.ts
+++ b/packages/studio/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 });
diff --git a/packages/studio/src/player/components/Player.tsx b/packages/studio/src/player/components/Player.tsx
index 9bf9eb6fde..04b6133c85 100644
--- a/packages/studio/src/player/components/Player.tsx
+++ b/packages/studio/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
diff --git a/packages/studio/src/player/lib/playbackTypes.ts b/packages/studio/src/player/lib/playbackTypes.ts
index 707a3518b1..e94700e6db 100644
--- a/packages/studio/src/player/lib/playbackTypes.ts
+++ b/packages/studio/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;
diff --git a/packages/studio/src/player/sceneSwap.test.ts b/packages/studio/src/player/sceneSwap.test.ts
index 5898981241..62d882a0bb 100644
--- a/packages/studio/src/player/sceneSwap.test.ts
+++ b/packages/studio/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);
+ });
+});
diff --git a/packages/studio/src/player/sceneSwap.ts b/packages/studio/src/player/sceneSwap.ts
index 94bfda0ba2..bcabb4bf05 100644
--- a/packages/studio/src/player/sceneSwap.ts
+++ b/packages/studio/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);
};
}