Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(studio): keep a preview reload waiting while a slow project boots (#5823)
Miguel Ángel2b9009ab520a
diff --git a/docs/packages/player.mdx b/docs/packages/player.mdxindex 60d435fadb..c9cbd76bbf 100644--- a/docs/packages/player.mdx+++ b/docs/packages/player.mdx@@ -64,6 +64,7 @@ Set `autoplay muted` only when playback should start without a user gesture.| `assets-loading-ui` | `player` or `none` | `player` | `none` hides the loading-assets card; asset events still fire || `low-power-idle` | boolean | false | While paused, check in once a second, not every 80 ms (many-player pages) || `disable-click-to-play` | boolean | false | A click on the player no longer plays or pauses, so the page can handle it |+| `no-load-timeout` | boolean | false | A slow load never fails at 8 s, so the page owns the deadline; script and runtime errors still fail at once || `range-start` | number | — | Film second where playback starts, loops back to and parks when paused (`rangeStart`) || `range-end` | number | — | Film second the range ends before: it stops or loops on the frame before it (`rangeEnd`) |diff --git a/packages/player/README.md b/packages/player/README.mdindex 329c6e54db..2358ab2b83 100644--- a/packages/player/README.md+++ b/packages/player/README.md@@ -84,6 +84,7 @@ Show a static image before playback starts:| `assets-loading-ui` | `player \| none` | `player` | `none` never shows the loading-assets card; asset events still fire || `low-power-idle` | boolean | false | While paused, check in once a second, not every 80 ms (many-player pages) || `disable-click-to-play` | boolean | false | A click on the player no longer plays or pauses (host overlays own clicks) |+| `no-load-timeout` | boolean | false | Slow loads never fail at 8 s; the page owns the deadline. Errors still fail || `range-start` | number | — | Film second where playback starts, loops back to and parks when paused || `range-end` | number | — | Film second the range ends before: it stops or loops on the frame before it |diff --git a/packages/player/src/composition-probe.ts b/packages/player/src/composition-probe.tsindex 3ccf3f1f05..f5630146c2 100644--- a/packages/player/src/composition-probe.ts+++ b/packages/player/src/composition-probe.ts@@ -4,7 +4,7 @@** The probe interval polls every 200 ms until one of:* - An adapter or the document resolves with a positive duration, or- * - 40 attempts (~8 s) expire without a result.+ * - 40 attempts (~8 s) expire without a result, unless the host owns the deadline.** The `CompositionProbe` class owns the interval; the caller must call* `stop()` on disconnect or src change.@@ -38,6 +38,7 @@ export interface ProbeCallbacks {/** Called when runtime is successfully injected (informational). */onRuntimeInjected?: () => void;resolveRuntimeUrl?: () => string;+ hostOwnsDeadline?: () => boolean;}/**@@ -121,22 +122,22 @@ export class CompositionProbe {};}}+ outcome ??= this._deadlineOutcome(attempts);if (outcome) {this.stop();if (outcome.kind === "error") {this._failure = { document: this._iframe.contentDocument };this._callbacks.onError(outcome.message);} else this._callbacks.onReady(outcome.result);- return;- }- if (attempts >= 40) {- this.stop();- this._failure = { document: this._iframe.contentDocument };- this._callbacks.onError("Composition timeline not found after 8s");}}, 200);}+ private _deadlineOutcome(attempts: number): ProbeOutcome {+ if (attempts < 40 || this._callbacks.hostOwnsDeadline?.()) return null;+ return { kind: "error", message: "Composition timeline not found after 8s" };+ }+private _poll(attempts: number): ProbeOutcome {const win = this._iframe.contentWindow;if (!win) return null;diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.tsindex e6f753797d..0b7f78e790 100644--- a/packages/player/src/hyperframes-player.ts+++ b/packages/player/src/hyperframes-player.ts@@ -206,6 +206,7 @@ class HyperframesPlayer extends HTMLElement {this.probe = new CompositionProbe(this.iframe, {resolveRuntimeUrl: () => runtimeSrcFromElement(this),+ hostOwnsDeadline: () => this.hasAttribute("no-load-timeout"),onReady: (result) => this._onProbeReady(result),onError: (message) => this._emit(new CustomEvent("error", { detail: { message } })),});diff --git a/packages/player/src/probeTerminalReadiness.test.ts b/packages/player/src/probeTerminalReadiness.test.tsindex fbc0f13ba3..6064647314 100644--- a/packages/player/src/probeTerminalReadiness.test.ts+++ b/packages/player/src/probeTerminalReadiness.test.ts@@ -61,6 +61,24 @@ describe("terminal probe readiness", () => {expectUnready(player, onReady);});+ it("waits past 8 s for a slow runtime when the host owns the deadline", () => {+ const { player, iframe, onError, onReady } = mountPlayer();+ player.setAttribute("no-load-timeout", "");+ vi.advanceTimersByTime(20_000);+ expect(onError).not.toHaveBeenCalled();+ Object.assign(iframe.contentWindow!, { __player: { getDuration: () => 9 } });+ vi.advanceTimersByTime(200);+ expectTimelineReady(player, onReady);+ });++ it("still fails an author error at once when the host owns the deadline", () => {+ const { player, iframe, onError } = mountPlayer();+ player.setAttribute("no-load-timeout", "");+ Object.assign(iframe.contentWindow!, { __hfPreviewErrors: ["Uncaught Error: author failed"] });+ vi.advanceTimersByTime(200);+ expect(onError.mock.calls[0][0].detail.message).toBe("Uncaught Error: author failed");+ });+it("rejects the failed document while its replacement is still navigating", () => {const { player, iframe, onReady } = mountPlayer();vi.advanceTimersByTime(8000);diff --git a/packages/studio/src/components/nle/NLEPreview.slowBoot.test.ts b/packages/studio/src/components/nle/NLEPreview.slowBoot.test.tsnew file mode 100644index 0000000000..f5d3e5524e--- /dev/null+++ b/packages/studio/src/components/nle/NLEPreview.slowBoot.test.ts@@ -0,0 +1,63 @@+// @vitest-environment happy-dom+// @vitest-environment-options {"happyDOM":{"settings":{"disableIframePageLoading":true}}}++import React, { act, createRef } from "react";+import { createRoot } from "react-dom/client";+import { afterEach, expect, it, vi } from "vitest";+import { NLEPreview } from "./NLEPreview";++globalThis.IS_REACT_ACT_ENVIRONMENT = true;++afterEach(() => {+ vi.useRealTimers();+ document.body.innerHTML = "";+});++it("keeps a shadow reload whose runtime boots after 8 s, and its player comes ready", async () => {+ await import("@hyperframes/player");+ vi.useFakeTimers();+ const onShadowError = vi.fn();+ const host = document.createElement("div");+ document.body.append(host);+ const root = createRoot(host);+ await act(async () => {+ root.render(+ React.createElement(NLEPreview, {+ projectId: "p",+ iframeRef: createRef<HTMLIFrameElement>(),+ onIframeLoad: () => {},+ previewSlots: [+ { gen: 0, role: "live" },+ { gen: 1, role: "shadow", url: "/api/projects/p/preview?_t=1" },+ ],+ onShadowIframeLoad: () => {},+ onShadowReadyChange: () => {},+ onShadowError,+ setShadowIframeNode: () => {},+ resetPreviewSlots: () => {},+ }),+ );+ });++ const shadow = host.querySelectorAll<+ HTMLElement & { iframeElement: HTMLIFrameElement; ready: boolean }+ >("hyperframes-player")[1];+ const iframe = shadow.iframeElement;+ act(() => {+ iframe.dispatchEvent(new Event("load"));+ });+ act(() => {+ vi.advanceTimersByTime(10_000);+ });+ expect(onShadowError).not.toHaveBeenCalled();++ Object.assign(iframe.contentWindow!, { __player: { getDuration: () => 9 } });+ act(() => {+ vi.advanceTimersByTime(1_000);+ });+ expect(onShadowError).not.toHaveBeenCalled();+ expect(shadow.ready).toBe(true);+ // The live slot keeps the player's own 8 s deadline.+ expect(host.querySelector("hyperframes-player")?.hasAttribute("no-load-timeout")).toBe(false);+ act(() => root.unmount());+});diff --git a/packages/studio/src/components/nle/NLEPreview.tsx b/packages/studio/src/components/nle/NLEPreview.tsxindex 8cb82c9dc0..be4831bd4e 100644--- a/packages/studio/src/components/nle/NLEPreview.tsx+++ b/packages/studio/src/components/nle/NLEPreview.tsx@@ -209,8 +209,7 @@ export const NLEPreview = memo(function NLEPreview({const updateCompositionSizeFromPreview = useCallback(() => {const next = readPreviewCompositionSize(previewIframeRef.current);- // Pure updater — the parent notification happens in the effect below- // (updaters may run more than once under Strict Mode / concurrent React).+ // Pure updater; the effect below notifies the parent (Strict Mode may run updaters twice).setCompositionSize((prev) =>prev?.width === next?.width && prev?.height === next?.height ? prev : next,);@@ -563,6 +562,7 @@ export const NLEPreview = memo(function NLEPreview({onPreviewError={(message) => onShadowError(slot.gen, message)}portrait={portrait}suppressLoadingOverlay+ noLoadTimeoutstyle={SHADOW_IFRAME_STYLE}/>),diff --git a/packages/studio/src/player/components/Player.tsx b/packages/studio/src/player/components/Player.tsxindex ea441c2028..cc74e665b6 100644--- a/packages/studio/src/player/components/Player.tsx+++ b/packages/studio/src/player/components/Player.tsx@@ -37,6 +37,7 @@ interface PlayerProps {portrait?: boolean;style?: React.CSSProperties;suppressLoadingOverlay?: boolean;+ noLoadTimeout?: boolean;}interface HyperframesPlayerElement extends HTMLElement {@@ -154,6 +155,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(portrait,style,suppressLoadingOverlay,+ noLoadTimeout,},ref,) => {@@ -224,6 +226,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(setCompositionLoading(true);loadStartedAtRef.current = performance.now();loadIdRef.current += 1;+ player.removeAttribute("no-load-timeout");player.setAttribute("src", retryUrl.pathname + retryUrl.search);};retryPreviewRef.current = retryPreview;@@ -331,6 +334,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(player.setAttribute("shader-capture-scale", "1");player.setAttribute("shader-loading", "player");player.setAttribute("low-power-idle", "");+ player.toggleAttribute("no-load-timeout", noLoadTimeout === true);player.setAttribute("width", String(portrait ? 1080 : 1920));player.setAttribute("height", String(portrait ? 1920 : 1080));player.style.width = "100%";diff --git a/packages/studio/src/player/hooks/useShadowPreviewReload.ts b/packages/studio/src/player/hooks/useShadowPreviewReload.tsindex 7233c2a6c6..39e114649d 100644--- a/packages/studio/src/player/hooks/useShadowPreviewReload.ts+++ b/packages/studio/src/player/hooks/useShadowPreviewReload.ts@@ -49,7 +49,12 @@ function isDocumentHidden(): boolean {type UseShadowPreviewReloadParams = Omit<UseTimelineSyncCallbacksParams,- "probeIntervalRef" | "onAdapterReady" | "getAdapter" | "isCurrent" | "onLoadGiveUp"+ | "probeIntervalRef"+ | "onAdapterReady"+ | "getAdapter"+ | "isCurrent"+ | "onLoadGiveUp"+ | "hostOwnsDeadline"> & {getAdapter: (overrideIframe?: HTMLIFrameElement | null) => PlaybackAdapter | null;/** Runs right after a shadow becomes the live iframe (iframeRef already points at it). */@@ -249,6 +254,7 @@ export function useShadowPreviewReload({applyPreviewAudioState: () => {},onAdapterReady: markAdapterReady,isCurrent: isCurrentShadow,+ hostOwnsDeadline: true,});cancelPendingLoadRef.current = cancelPendingLoad;diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.tsindex a1006cafe8..6770367ddc 100644--- a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts+++ b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts@@ -461,6 +461,31 @@ describe("shadow reload readiness and failure", () => {unmount(root);});+ it("promotes a shadow whose runtime boots after Studio's own 5 s readiness wait", () => {+ vi.useFakeTimers();+ const onPreviewReloadFailed = vi.fn();+ const { getApi, gen, root } = beginReload({ onPreviewReloadFailed });+ const { win } = makeAdapterWindow();+ const booting: Record<string, unknown> = { ...win, __player: undefined };+ const iframe = makeFakeIframe(booting);+ act(() => {+ getApi().setShadowIframeNode(iframe);+ getApi().onShadowIframeLoad(gen);+ });++ act(() => void vi.advanceTimersByTime(10_000));+ booting.__player = win.__player;+ act(() => {+ window.dispatchEvent(+ new MessageEvent("message", { data: { source: "hf-preview", type: "state" } }),+ );+ getApi().onShadowReadyChange(gen, true);+ });+ expect(getApi().iframeRef.current).toBe(iframe);+ expect(onPreviewReloadFailed).not.toHaveBeenCalled();+ unmount(root);+ });+it("gives a reload that replaces a slow one its own full set of budgets", () => {vi.useFakeTimers();vi.spyOn(console, "error").mockImplementation(() => {});diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.tsindex e0231bf32b..1157007b67 100644--- a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts+++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts@@ -60,6 +60,7 @@ export interface UseTimelineSyncCallbacksParams {isCurrent?: (context?: number) => boolean;/** Fires when no adapter appeared within the wait window. */onLoadGiveUp?: (context?: number) => void;+ hostOwnsDeadline?: boolean;}/**@@ -163,6 +164,7 @@ export function useTimelineSyncCallbacks({onAdapterReady = revealAndCommit,isCurrent,onLoadGiveUp,+ hostOwnsDeadline,}: UseTimelineSyncCallbacksParams) {// Convert a runtime timeline message (from iframe postMessage) into TimelineElementsconst processTimelineMessage = useCallback(@@ -335,6 +337,7 @@ export function useTimelineSyncCallbacks({};window.addEventListener("message", onMessage);stopWaitingRef.current = stopWaiting;+ if (hostOwnsDeadline) return;// Safety net: if no message arrives within 5s, try one last time then give up.probeIntervalRef.current = setTimeout(() => {@@ -346,7 +349,14 @@ export function useTimelineSyncCallbacks({revealIframe(iframeRef.current);}, 5000) as unknown as ReturnType<typeof setInterval>;},- [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState, onLoadGiveUp],+ [+ initializeAdapter,+ iframeRef,+ probeIntervalRef,+ applyPreviewAudioState,+ onLoadGiveUp,+ hostOwnsDeadline,+ ],);const cancelPendingLoad = useCallback(() => {