Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
perf(studio): swap an edited scene into the live preview instead of reloading (#4499)
Miguel Ángel303c8e922f89
diff --git a/packages/studio/src/components/editor/LayersPanel.test.ts b/packages/studio/src/components/editor/LayersPanel.test.tsindex 6005764f42..3b12b6c66e 100644--- a/packages/studio/src/components/editor/LayersPanel.test.ts+++ b/packages/studio/src/components/editor/LayersPanel.test.ts@@ -9,6 +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";(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;@@ -292,4 +293,17 @@ describe("LayersPanel preview promotion", () => {});expect(collectedRootIds()).toEqual(["b"]);});+ it("recollects layers when edited scenes are swapped into the live document", async () => {+ const a = makeIframe("a");+ Object.defineProperty(a, "contentWindow", { value: { __hfSwapScenes: async () => {} } });+ const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html></html>"));+ mocks.previewIframeRef.current = a;+ usePreviewIframeStore.setState({ iframe: a });+ act(() => root.render(createElement(LayersPanel)));+ mocks.collect.mockClear();++ await act(() => sceneSwapFor(a)!("/preview", () => true));+ expect(collectedRootIds()).toEqual(["a"]);+ fetchSpy.mockRestore();+ });});diff --git a/packages/studio/src/components/editor/LayersPanel.tsx b/packages/studio/src/components/editor/LayersPanel.tsxindex f465c03326..a2b7119d4c 100644--- a/packages/studio/src/components/editor/LayersPanel.tsx+++ b/packages/studio/src/components/editor/LayersPanel.tsx@@ -1,4 +1,5 @@import { useLivePreviewIframe } from "../../player/store/previewIframeStore";+import { onPreviewContentReplaced } from "../../player/sceneSwap";import { memo, useState, useCallback, useEffect, useRef } from "react";import {collectDomEditLayerItems,@@ -164,8 +165,7 @@ export const LayersPanel = memo(function LayersPanel() {prevDocVersionRef.current += 1;collectLayers();};- iframe.addEventListener("load", handleLoad);- return () => iframe.removeEventListener("load", handleLoad);+ return onPreviewContentReplaced(iframe, handleLoad);}, [previewIframeRef, livePreviewIframe, collectLayers]);useEffect(() => {diff --git a/packages/studio/src/components/editor/TopologyLens.tsx b/packages/studio/src/components/editor/TopologyLens.tsxindex 79b2864971..9bea4420f3 100644--- a/packages/studio/src/components/editor/TopologyLens.tsx+++ b/packages/studio/src/components/editor/TopologyLens.tsx@@ -1,4 +1,5 @@import { useLivePreviewIframe } from "../../player/store/previewIframeStore";+import { onPreviewContentReplaced } from "../../player/sceneSwap";import {useEffect,useLayoutEffect,@@ -119,8 +120,7 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensPconst iframe = iframeRef.current;if (!iframe || !callId) return;const dismiss = () => studioEditLifecycle.dismiss(callId);- iframe.addEventListener("load", dismiss);- return () => iframe.removeEventListener("load", dismiss);+ return onPreviewContentReplaced(iframe, dismiss);}, [callId, iframeRef, livePreviewIframe]);useEffect(() => {diff --git a/packages/studio/src/components/editor/useColorGradingController.test.ts b/packages/studio/src/components/editor/useColorGradingController.test.tsindex 2c3c68b3e3..d86796dbde 100644--- a/packages/studio/src/components/editor/useColorGradingController.test.ts+++ b/packages/studio/src/components/editor/useColorGradingController.test.ts@@ -7,6 +7,7 @@ import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";import { usePreviewIframeStore } from "../../player/store/previewIframeStore";import { useColorGradingController } from "./useColorGradingController";+import { sceneSwapFor } from "../../player/sceneSwap";import type { DomEditSelection } from "./domEditing";function brightPopGrading() {@@ -390,6 +391,29 @@ describe("useColorGradingController", () => {vi.useRealTimers();});+ it("re-sends the grade to the preview after edited scenes are swapped in", async () => {+ vi.useFakeTimers();+ const { contentWindow, iframe } = createPreviewFrame();+ (contentWindow as unknown as { __hfSwapScenes: () => Promise<void> }).__hfSwapScenes =+ async () => {};+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html></html>"));+ const postMessage = vi.spyOn(contentWindow, "postMessage");+ const { root, getState } = renderHook(vi.fn(), makeElement(), { current: iframe });+ act(() => getState().commitColorGrading(brightPopGrading()));+ await act(async () => {+ vi.advanceTimersByTime(100);+ await vi.runAllTimersAsync();+ });+ postMessage.mockClear();++ await act(() => sceneSwapFor(iframe)!("/preview", () => true));+ const replayed = colorGradingMessages(postMessage.mock.calls);+ expect(replayed.at(-1)?.grading).toMatchObject({ preset: "bright-pop" });++ act(() => root.unmount());+ vi.useRealTimers();+ });+it("animates only the selected video card without starting the project player", async () => {vi.useFakeTimers();const { contentWindow, iframe } = createPreviewFrame();diff --git a/packages/studio/src/components/editor/useColorGradingController.ts b/packages/studio/src/components/editor/useColorGradingController.tsindex dae5bb51aa..3d69c99250 100644--- a/packages/studio/src/components/editor/useColorGradingController.ts+++ b/packages/studio/src/components/editor/useColorGradingController.ts@@ -1,5 +1,6 @@import { mediaMetadataUrl } from "../../utils/studioHelpers";import { useLivePreviewIframe } from "../../player/store/previewIframeStore";+import { onPreviewContentReplaced } from "../../player/sceneSwap";import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";import {HF_COLOR_GRADING_ATTR,@@ -445,11 +446,11 @@ export function useColorGradingController({if (!acceptStudioRuntimeMessage(data)) return;refreshAndReplay();};- iframe.addEventListener("load", refreshAndReplay);window.addEventListener("message", onMessage);const timer = window.setTimeout(refreshAndReplay, 80);+ const stopReplay = onPreviewContentReplaced(iframe, refreshAndReplay);return () => {- iframe.removeEventListener("load", refreshAndReplay);+ stopReplay();window.removeEventListener("message", onMessage);window.clearTimeout(timer);};diff --git a/packages/studio/src/hooks/useDomEditPreviewSync.test.ts b/packages/studio/src/hooks/useDomEditPreviewSync.test.tsnew file mode 100644index 0000000000..d7783e6493--- /dev/null+++ b/packages/studio/src/hooks/useDomEditPreviewSync.test.ts@@ -0,0 +1,58 @@+// @vitest-environment happy-dom++import { createElement, act } from "react";+import { createRoot } from "react-dom/client";+import { describe, expect, it, vi } from "vitest";+import { useDomEditPreviewSync } from "./useDomEditPreviewSync";+import { sceneSwapFor } from "../player/sceneSwap";++(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;++describe("useDomEditPreviewSync", () => {+ it("re-syncs the preview when edited scenes are swapped in, and not when the swap is refused", async () => {+ const iframe = document.createElement("iframe");+ let refuse = false;+ Object.defineProperty(iframe, "contentWindow", {+ value: {+ __hfSwapScenes: async () => {+ if (refuse) throw new Error("the film changed outside its scenes");+ },+ },+ });+ const fetchSpy = vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response(""));+ const applyManualEdits = vi.fn(async () => {});+ const refreshVersion = vi.fn();+ function Harness() {+ useDomEditPreviewSync({+ previewIframe: iframe,+ activeCompPath: null,+ captionEditMode: false,+ domEditSelectionRef: { current: null },+ domEditGroupSelectionsRef: { current: [] },+ domEditSelection: null,+ refreshDomEditGroupSelectionsFromPreview: async () => {},+ applyDomSelection: () => {},+ buildDomSelectionFromTarget: async () => null,+ refreshPreviewDocumentVersion: refreshVersion,+ syncPreviewHotkeys: () => {},+ applyStudioManualEditsToPreviewRef: { current: applyManualEdits },+ });+ return null;+ }+ const root = createRoot(document.createElement("div"));+ act(() => root.render(createElement(Harness)));+ applyManualEdits.mockClear();+ refreshVersion.mockClear();++ refuse = true;+ await act(() => sceneSwapFor(iframe)!("/preview", () => true).catch(() => {}));+ expect(refreshVersion).not.toHaveBeenCalled();++ refuse = false;+ await act(() => sceneSwapFor(iframe)!("/preview", () => true));+ expect(applyManualEdits).toHaveBeenCalledWith(iframe);+ expect(refreshVersion).toHaveBeenCalledTimes(1);+ act(() => root.unmount());+ fetchSpy.mockRestore();+ });+});diff --git a/packages/studio/src/hooks/useDomEditPreviewSync.ts b/packages/studio/src/hooks/useDomEditPreviewSync.tsindex c36e3b8b45..b0b6b8eda1 100644--- a/packages/studio/src/hooks/useDomEditPreviewSync.ts+++ b/packages/studio/src/hooks/useDomEditPreviewSync.ts@@ -9,6 +9,7 @@ import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits"import { useDockLayoutStore } from "../components/dock/dockLayoutStore";import type { PatchTarget } from "../utils/sourcePatcher";import { logSelect } from "../utils/selectDebug";+import { onPreviewContentReplaced } from "../player/sceneSwap";interface UseDomEditPreviewSyncParams {previewIframe: HTMLIFrameElement | null;@@ -113,10 +114,7 @@ export function useDomEditPreviewSync({refreshPreviewDocumentVersion();};- previewIframe.addEventListener("load", handleLoad);- return () => {- previewIframe.removeEventListener("load", handleLoad);- };+ return onPreviewContentReplaced(previewIframe, handleLoad);}, [activeCompPath,applyDomSelection,diff --git a/packages/studio/src/player/hooks/useShadowPreviewReload.ts b/packages/studio/src/player/hooks/useShadowPreviewReload.tsindex 45b9a449f3..3dde8546b4 100644--- a/packages/studio/src/player/hooks/useShadowPreviewReload.ts+++ b/packages/studio/src/player/hooks/useShadowPreviewReload.ts@@ -140,6 +140,7 @@ export function useShadowPreviewReload({const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);+ const previewGeneration = useCallback(() => shadowGenRef.current, []);const markAdapterReady = useCallback((iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {if (gen == null || gen !== shadowGenRef.current) return;@@ -261,5 +262,6 @@ export function useShadowPreviewReload({setShadowIframeNode,beginShadowReload,resetPreviewSlots,+ previewGeneration,};}diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.tsindex c51646fd7b..ef1885383e 100644--- a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts+++ b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts@@ -649,3 +649,194 @@ function stubVisibility(initial: DocumentVisibilityState) {document.dispatchEvent(new Event("visibilitychange"));};}++describe("useTimelinePlayer scene swap", () => {+ function liveFilm(swap?: (html: string) => Promise<void>) {+ const { adapter, win } = makeAdapterWindow();+ const iframe = makeFakeIframe(swap ? { ...win, __hfSwapScenes: swap } : win);+ iframe.src = "http://localhost/api/projects/demo/preview";+ const harness = renderTimelinePlayerHarness();+ act(() => {+ harness.getApi().iframeRef.current = iframe;+ harness.getApi().onIframeLoad();+ });+ return { ...harness, adapter };+ }+ function playingFilm(swap: (html: string) => Promise<void>) {+ const film = liveFilm(swap);+ usePlayerStore.setState({ timelineReady: true });+ act(() => film.getApi().play());+ film.adapter.pause.mockClear();+ return film;+ }+ const roles = (api: ReturnType<ReturnType<typeof liveFilm>["getApi"]>) =>+ api.previewSlots.map((slot) => slot.role);+ const settle = () => act(async () => void (await new Promise((r) => setTimeout(r, 0))));++ it("swaps the rebuilt preview's scenes into the live preview with no shadow reload", async () => {+ const swap = vi.fn(async () => {});+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));+ const { getApi } = liveFilm(swap);+ act(() => getApi().refreshPlayer());+ await settle();+ expect(swap).toHaveBeenCalledWith("<html>v2</html>", expect.anything());+ expect(roles(getApi())).toEqual(["live"]);+ });++ it("falls back to the full reload when the preview refuses the swap", async () => {+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));+ const { getApi } = liveFilm(async () => {+ throw new Error("the film changed outside its scenes");+ });+ act(() => getApi().refreshPlayer());+ await settle();+ expect(roles(getApi())).toEqual(["live", "shadow"]);+ });++ it("reloads the whole film at once when the preview cannot swap", () => {+ const fetchSpy = vi.spyOn(globalThis, "fetch");+ const { getApi } = liveFilm();+ act(() => getApi().refreshPlayer());+ expect(fetchSpy).not.toHaveBeenCalled();+ expect(roles(getApi())).toEqual(["live", "shadow"]);+ });++ it("never swaps in an older document that arrives after a newer reload started", async () => {+ const swap = vi.fn(async () => {});+ const replies: Array<(r: Response) => void> = [];+ vi.spyOn(globalThis, "fetch").mockImplementation(+ () => new Promise<Response>((resolve) => replies.push(resolve)),+ );+ const { getApi } = liveFilm(swap);+ act(() => getApi().refreshPlayer());+ act(() => getApi().refreshPlayer());+ replies[1]!(new Response("<html>v3</html>"));+ await settle();+ replies[0]!(new Response("<html>v2</html>"));+ await settle();+ expect(swap.mock.calls).toEqual([["<html>v3</html>", expect.anything()]]);+ expect(roles(getApi())).toEqual(["live"]);+ });++ it("cancels an older swap still waiting when a newer edit starts, so it cannot land after that edit's reload", async () => {+ vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("<html>v</html>"));+ let captionsArrive = () => {};+ const captions = new Promise<void>((resolve) => (captionsArrive = resolve));+ const landed: string[] = [];+ let calls = 0;+ // As the runtime does: the first waits for caption overrides, then refuses if cancelled; the second is refused.+ const swap = async (_html: string, signal?: AbortSignal) => {+ if (++calls > 1) throw new Error("the film changed outside its scenes");+ await captions;+ if (signal?.aborted) throw new Error("the swap was cancelled");+ landed.push("edit 1");+ };+ const { getApi } = liveFilm(swap);+ act(() => getApi().refreshPlayer());+ await settle();+ act(() => getApi().refreshPlayer());+ await settle();+ expect(roles(getApi())).toContain("shadow");+ captionsArrive();+ await settle();+ expect(landed).toEqual([]);+ });++ it("drops a pending swap's fallback once the preview was replaced, e.g. by a composition switch", async () => {+ let refuse!: (e: Error) => void;+ const swap = vi.fn(() => new Promise<void>((_, reject) => (refuse = reject)));+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));+ const { getApi } = liveFilm(swap);+ act(() => getApi().refreshPlayer());+ await settle();+ expect(swap).toHaveBeenCalledTimes(1);+ act(() => getApi().resetPreviewSlots());+ const next = makeFakeIframe(makeAdapterWindow().win);+ next.src = "http://localhost/api/projects/demo/preview/comp/compositions/intro.html";+ act(() => {+ getApi().iframeRef.current = next;+ getApi().onIframeLoad();+ });+ refuse(new Error("the preview was torn down during the swap"));+ await settle();+ expect(roles(getApi())).toEqual(["live"]);+ });++ it("skips the swap for an edit made while a full reload is in flight", async () => {+ const fetchSpy = vi+ .spyOn(globalThis, "fetch")+ .mockResolvedValue(new Response("<html>v2</html>"));+ const { getApi } = liveFilm(async () => {+ throw new Error("the film changed outside its scenes");+ });+ act(() => getApi().refreshPlayer());+ await settle();+ expect(roles(getApi())).toEqual(["live", "shadow"]);+ const firstShadow = getApi().previewSlots[1]!.gen;+ fetchSpy.mockClear();+ act(() => getApi().refreshPlayer());+ expect(fetchSpy).not.toHaveBeenCalled();+ expect(getApi().previewSlots[1]!.gen).toBeGreaterThan(firstShadow);+ });++ it("keeps a playing film playing through a swap, ready to swap the next edit", async () => {+ const fetchSpy = vi+ .spyOn(globalThis, "fetch")+ .mockImplementation(async () => new Response("<html>v2</html>"));+ const swap = vi.fn(async () => {});+ const { getApi, adapter } = playingFilm(swap);+ act(() => getApi().refreshPlayer());+ await settle();+ expect(adapter.pause).not.toHaveBeenCalled();+ expect(usePlayerStore.getState().isPlaying).toBe(true);+ expect(roles(getApi())).toEqual(["live"]);+ act(() => getApi().refreshPlayer());+ await settle();+ expect(fetchSpy).toHaveBeenCalledTimes(2);+ expect(swap).toHaveBeenCalledTimes(2);+ });++ it("shows a playing film stopped at its new end when a swap cuts it short of the playhead", async () => {+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));+ let length = 6;+ // As the runtime's swap does when the edit ends the film at or before the playhead.+ const cutShort = async () => {+ length = 5;+ adapter.pause();+ adapter.seek(5);+ };+ const { getApi, adapter } = playingFilm(cutShort);+ adapter.getDuration = () => length;+ adapter.seek(5.5);+ act(() => getApi().refreshPlayer());+ await settle();+ await act(async () => void (await new Promise((r) => setTimeout(r, 50))));+ expect(usePlayerStore.getState().isPlaying).toBe(false);+ expect(usePlayerStore.getState().currentTime).toBe(5);+ expect(adapter.play).toHaveBeenCalledTimes(1);+ expect(roles(getApi())).toEqual(["live"]);+ });++ it("keeps a playing film playing through a refused swap, from where the live frame had reached", async () => {+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));+ const { getApi, adapter } = playingFilm(async () => {+ throw new Error("the film changed outside its scenes");+ });+ adapter.seek(3);+ act(() => getApi().refreshPlayer());+ // The live frame plays on while the swap is tried; the fallback reload starts from here.+ adapter.seek(4.5);+ await settle();+ expect(adapter.pause).not.toHaveBeenCalled();+ expect(usePlayerStore.getState().isPlaying).toBe(true);+ const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;+ const shadow = makeShadowWithSpies();+ act(() => {+ getApi().setShadowIframeNode(shadow.iframe);+ getApi().onShadowIframeLoad(gen);+ getApi().onShadowReadyChange(gen, true);+ });+ expect(shadow.adapter.getTime()).toBe(4.5);+ expect(shadow.adapter.isPlaying()).toBe(true);+ });+});diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.ts b/packages/studio/src/player/hooks/useTimelinePlayer.tsindex 5b2f06d3c8..421ad84607 100644--- a/packages/studio/src/player/hooks/useTimelinePlayer.ts+++ b/packages/studio/src/player/hooks/useTimelinePlayer.ts@@ -38,6 +38,7 @@ import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";import { createPreviewMessageHandler } from "./previewMessageRouter";import { timelineElementsChanged } from "./timelinePlayerSync";import { safeContentDocument } from "./timelineSyncHydration";+import { sceneSwapFor } from "../sceneSwap";export interface UseTimelinePlayerOptions {/** Runs right after a reloaded preview becomes the live iframe. */@@ -391,6 +392,7 @@ export function useTimelinePlayer({setShadowIframeNode,beginShadowReload,resetPreviewSlots,+ previewGeneration,} = useShadowPreviewReload({iframeRef,getAdapter,@@ -443,19 +445,39 @@ export function useTimelinePlayer({setIsPlaying(false);return false;}, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);+ const reloadWholeFilm = useCallback(+ (url: string) => {+ // The old iframe is no longer navigated away, so stop its playback (and audio) here.+ if (!saveSeekPosition()) getAdapter()?.pause();+ // The live iframe is never hidden; the reload loads in a shadow and is promoted once painted.+ beginShadowReload(url);+ },+ [saveSeekPosition, getAdapter, beginShadowReload],+ );+ const refreshGenRef = useRef(0);+ const swapCancelRef = useRef<AbortController | null>(null);const refreshPlayer = useCallback(() => {const iframe = iframeRef.current;if (!iframe) return;+ swapCancelRef.current?.abort(new Error("superseded by a newer edit"));+ const cancel = new AbortController();+ swapCancelRef.current = cancel;logReload("refreshPlayer", () => ({ stack: new Error("refreshPlayer").stack }));- // The old iframe is no longer navigated away, so stop its playback (and audio) here.- if (!saveSeekPosition()) getAdapter()?.pause();- // The live iframe is never hidden; the reload loads in a shadow and is promoted once painted.- const src = iframe.src;- const url = new URL(src, window.location.origin);+ const url = new URL(iframe.src, window.location.origin);url.searchParams.set("_t", String(Date.now()));applyPreviewVariablesToUrl(url);- beginShadowReload(url.toString());- }, [saveSeekPosition, getAdapter, beginShadowReload]);+ const gen = ++refreshGenRef.current;+ const slot = previewGeneration();+ // A newer edit, or anything replacing the live preview (a reload, a composition switch), wins.+ const isCurrent = () => gen === refreshGenRef.current && slot === previewGeneration();+ const swap = sceneSwapFor(iframe);+ if (!swap || isRefreshingRef.current) return reloadWholeFilm(url.toString());+ swap(url.toString(), isCurrent, cancel.signal).catch((error: unknown) => {+ if (!isCurrent()) return;+ logReload("scene-swap-refused", { reason: String(error) });+ reloadWholeFilm(url.toString());+ });+ }, [reloadWholeFilm, previewGeneration]);const pauseRef = useRef(pause);pauseRef.current = pause;diff --git a/packages/studio/src/player/sceneSwap.test.ts b/packages/studio/src/player/sceneSwap.test.tsnew file mode 100644index 0000000000..5898981241--- /dev/null+++ b/packages/studio/src/player/sceneSwap.test.ts@@ -0,0 +1,95 @@+// @vitest-environment happy-dom+import { afterEach, describe, expect, it, vi } from "vitest";+import { SCENE_SWAP_MS, sceneSwapFor } from "./sceneSwap";++afterEach(() => {+ vi.useRealTimers();+ vi.restoreAllMocks();+});++type Swap = (html: string, signal?: AbortSignal) => Promise<void>;++function swappableIframe(swap: Swap = vi.fn(async () => {})) {+ const iframe = document.createElement("iframe");+ document.body.append(iframe);+ Object.assign(iframe.contentWindow as object, { __hfSwapScenes: swap });+ return { iframe, swap };+}++describe("sceneSwapFor", () => {+ it("gives up on a preview download that never finishes, so the caller can reload", async () => {+ vi.useFakeTimers();+ vi.spyOn(globalThis, "fetch").mockImplementation(+ (_url, init) =>+ new Promise((_resolve, reject) =>+ init?.signal?.addEventListener("abort", () => reject(init.signal?.reason)),+ ),+ );+ const { iframe, swap } = swappableIframe();+ const swapping = sceneSwapFor(iframe)!("/preview", () => true);+ const outcome = expect(swapping).rejects.toThrow("took too long");+ await vi.advanceTimersByTimeAsync(SCENE_SWAP_MS);+ await outcome;+ expect(swap).not.toHaveBeenCalled();+ });++ it.each([+ ["a body that never finishes", async () => new Response(new ReadableStream())],+ ["a runtime swap that never finishes", async () => new Response("<html></html>")],+ ])("gives up on %s, so the caller can reload", async (_stall, respond) => {+ vi.useFakeTimers();+ vi.spyOn(globalThis, "fetch").mockImplementation(respond);+ const { iframe } = swappableIframe(vi.fn(() => new Promise<void>(() => {})));+ const swapped = vi.fn();+ iframe.addEventListener("hf-scenes-swapped", swapped);+ const outcome = expect(sceneSwapFor(iframe)!("/preview", () => true)).rejects.toThrow(+ "took too long",+ );+ await vi.advanceTimersByTimeAsync(SCENE_SWAP_MS);+ await outcome;+ expect(swapped).not.toHaveBeenCalled();+ });++ it("cancels the runtime's swap as it gives up, so captions arriving later replace nothing", async () => {+ vi.useFakeTimers();+ vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("<html></html>"));+ let captionsArrive = () => {};+ const captions = new Promise<void>((resolve) => (captionsArrive = resolve));+ let replaced = false;+ // As the runtime does: it waits for the caption overrides, then refuses a cancelled swap.+ const { iframe } = swappableIframe(async (_html, signal) => {+ await captions;+ if (signal?.aborted) throw new Error("the swap was cancelled");+ replaced = true;+ });+ const outcome = expect(sceneSwapFor(iframe)!("/preview", () => true)).rejects.toThrow(+ "took too long",+ );+ await vi.advanceTimersByTimeAsync(SCENE_SWAP_MS);+ await outcome;+ captionsArrive();+ await vi.advanceTimersByTimeAsync(0);+ expect(replaced).toBe(false);+ });++ it("does not start a swap whose cancel signal was aborted before the call", async () => {+ const fetchSpy = vi+ .spyOn(globalThis, "fetch")+ .mockImplementation(async () => new Response("<html></html>"));+ const { iframe, swap } = swappableIframe();+ const cancel = new AbortController();+ cancel.abort(new Error("superseded by a newer edit"));+ await expect(sceneSwapFor(iframe)!("/preview", () => true, cancel.signal)).rejects.toThrow(+ "superseded",+ );+ expect(fetchSpy).not.toHaveBeenCalled();+ expect(swap).not.toHaveBeenCalled();+ });++ it("swaps a document that arrives in time", async () => {+ vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("<html></html>"));+ const { iframe, swap } = swappableIframe();+ await sceneSwapFor(iframe)!("/preview", () => true);+ expect(swap).toHaveBeenCalledWith("<html></html>", expect.anything());+ });+});diff --git a/packages/studio/src/player/sceneSwap.ts b/packages/studio/src/player/sceneSwap.tsnew file mode 100644index 0000000000..9928eff119--- /dev/null+++ b/packages/studio/src/player/sceneSwap.ts@@ -0,0 +1,53 @@+type SwapWindow = Window & {+ __hfSwapScenes?: (html: string, signal?: AbortSignal) => Promise<void>;+};++const SCENES_SWAPPED = "hf-scenes-swapped";+export const SCENE_SWAP_MS = 5000;++export function onPreviewContentReplaced(+ iframe: HTMLIFrameElement,+ onReplaced: () => void,+): () => void {+ iframe.addEventListener("load", onReplaced);+ iframe.addEventListener(SCENES_SWAPPED, onReplaced);+ return () => {+ iframe.removeEventListener("load", onReplaced);+ iframe.removeEventListener(SCENES_SWAPPED, onReplaced);+ };+}++/** Null when the preview cannot swap; rejects when superseded, cancelled or a full reload is needed. */+export function sceneSwapFor(+ iframe: HTMLIFrameElement,+): ((url: string, isCurrent: () => boolean, cancel?: AbortSignal) => Promise<void>) | null {+ const win = iframe.contentWindow as SwapWindow | null;+ const swap = win?.__hfSwapScenes;+ if (typeof swap !== "function") return null;+ return async (url, isCurrent, cancel) => {+ if (cancel?.aborted) throw cancel.reason;+ const deadline = new AbortController();+ const timer = setTimeout(+ () => deadline.abort(new Error("the preview took too long to swap")),+ SCENE_SWAP_MS,+ );+ cancel?.addEventListener("abort", () => deadline.abort(cancel.reason), { once: true });+ const swapping = (async () => {+ const response = await fetch(url, { signal: deadline.signal });+ if (!response.ok) throw new Error(`preview request failed with ${response.status}`);+ const html = await response.text();+ if (!isCurrent()) throw new Error("superseded by a newer reload");+ // Aborted with the deadline, so a swap still waiting cannot land after the reload has begun.+ await swap.call(win, html, deadline.signal);+ })();+ const expired = new Promise<never>((_resolve, reject) =>+ deadline.signal.addEventListener("abort", () => reject(deadline.signal.reason)),+ );+ try {+ await Promise.race([swapping, expired]);+ } finally {+ clearTimeout(timer);+ }+ iframe.dispatchEvent(new Event(SCENES_SWAPPED));+ };+}