Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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 gpreviewWindow.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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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 hasdiff --git a/packages/studio/src/player/lib/playbackTypes.ts b/packages/studio/src/player/lib/playbackTypes.tsindex 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.tsindex 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-domimport { 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.tsindex 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);};}