@hyperframes/studio 0.8.86 → 0.8.88

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

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

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

package/src/player/store/playerStore.ts

@@ -23,6 +23,7 @@ import { createRangeSelectionSlice, type RangeSelectionSlice } from "./rangeSele
 import { createTimelineResetState } from "./timelineResetState";
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
+import { liveTime } from "./liveTime";
 export { createTimelineResetState };
 
 import type {
@@ -96,6 +97,8 @@ interface PlayerState extends PlayerStoreSlices {
 
   activeTool: TimelineTool;
   setActiveTool: (tool: TimelineTool) => void;
+  selectLeftward: () => void;
+  selectRightward: () => void;
 
   /** Tween-relative percentage of the last-clicked keyframe diamond. Operations
    *  (drag, resize, rotate) target this instead of recomputing from playhead. */
@@ -250,6 +253,17 @@ interface BeatHistoryEntry {
   label: string;
 }
 
+/** Selects like the marquee: the primary first, so its resets run, then the whole set. */
+function selectAroundPlayhead(
+  state: PlayerState,
+  keep: (start: number, playhead: number) => boolean,
+): void {
+  const playhead = state.isPlaying ? liveTime.latest() : state.currentTime;
+  const ids = state.elements.filter((el) => keep(el.start, playhead)).map((el) => el.key ?? el.id);
+  state.setSelectedElementId(ids[0] ?? null);
+  state.setSelectedElementIds(new Set(ids));
+}
+
 export const usePlayerStore = create<PlayerState>((set, get) => ({
   isPlaying: false,
   currentTime: 0,
@@ -273,6 +287,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
 
   activeTool: "select",
   setActiveTool: (tool) => set({ activeTool: tool }),
+  selectLeftward: () => selectAroundPlayhead(get(), (start, playhead) => start < playhead),
+  selectRightward: () => selectAroundPlayhead(get(), (start, playhead) => start >= playhead),
 
   ...createKeyframeSlice(set, () => ({
     timelineProjectId: get().timelineProjectId,