@hyperframes/studio 0.8.86 → 0.8.87

package/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;
 

package/src/player/lib/runtimeProtocol.test.ts

@@ -20,6 +20,7 @@ describe("Studio runtime protocol", () => {
         "seek-keep-playing",
         "composition-manifest-v1",
         "runtime-data",
+        "play-range",
       ],
       fps: { numerator: 60, denominator: 1 },
       timeSeconds: 1.25,

package/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());
+  });
+});

package/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));
+  };
+}