@hyperframes/studio 0.8.85 → 0.8.87

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

package/src/player/store/liveTime.ts

@@ -1,9 +1,14 @@
 // ponytail: Playback RAF updates the playhead/time display without per-frame React renders.
 type TimeListener = (time: number) => void;
 const timeListeners = new Set<TimeListener>();
+let latestTime = 0;
 
 export const liveTime = {
-  notify: (time: number) => timeListeners.forEach((listener) => listener(time)),
+  notify: (time: number) => {
+    latestTime = time;
+    timeListeners.forEach((listener) => listener(time));
+  },
+  latest: () => latestTime,
   subscribe: (listener: TimeListener) => {
     timeListeners.add(listener);
     return () => timeListeners.delete(listener);