@hyperframes/studio 0.8.56 → 0.8.58

package/src/player/hooks/playbackAdapterResolution.ts

@@ -0,0 +1,98 @@
+// Picks the PlaybackAdapter an iframe's runtime exposes, wrapping it for static seek when needed.
+import type { MutableRefObject } from "react";
+import { usePlayerStore } from "../store/playerStore";
+import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
+import {
+  getAdapterDuration,
+  wrapTimeline,
+  getDefaultStaticSeekPlaybackClock,
+  releaseStaticSeekCache,
+  resolveStaticSeekFallback,
+  type StaticSeekCacheEntry,
+} from "../lib/playbackAdapter";
+import { readTimelineDurationFromDocument } from "../lib/timelineDOM";
+
+/**
+ * Timeline-based adapters (`__timeline`, then `__timelines`): `match` is the first that covers
+ * the document duration; otherwise `fallback` is the first with any duration.
+ */
+function pickTimelineAdapter(
+  iframe: HTMLIFrameElement,
+  win: IframeWindow,
+  docDuration: number,
+): { match: PlaybackAdapter | null; fallback: PlaybackAdapter | null } {
+  let fallback: PlaybackAdapter | null = null;
+  for (const adapter of timelineCandidates(iframe, win)) {
+    const dur = getAdapterDuration(adapter);
+    if (dur > 0 && docDuration <= dur) return { match: adapter, fallback };
+    if (dur > 0) fallback ??= adapter;
+  }
+  return { match: null, fallback };
+}
+
+function* timelineCandidates(
+  iframe: HTMLIFrameElement,
+  win: IframeWindow,
+): Generator<PlaybackAdapter> {
+  if (win.__timeline) yield wrapTimeline(win.__timeline);
+  const keys = win.__timelines ? Object.keys(win.__timelines) : [];
+  if (!win.__timelines || keys.length === 0) return;
+  // The outermost [data-composition-id] is the master; Object.keys() order would let a
+  // sub-composition hijack transport.
+  const rootId = iframe.contentDocument
+    ?.querySelector("[data-composition-id]")
+    ?.getAttribute("data-composition-id");
+  const key = rootId && rootId in win.__timelines ? rootId : keys[keys.length - 1];
+  yield wrapTimeline(win.__timelines[key]);
+}
+
+interface StaticSeekRefs {
+  cache: MutableRefObject<StaticSeekCacheEntry | null>;
+  warned: MutableRefObject<boolean>;
+}
+
+export function resolvePlaybackAdapter(
+  iframe: HTMLIFrameElement,
+  win: IframeWindow,
+  refs: StaticSeekRefs,
+): PlaybackAdapter | null {
+  const playerAdapter =
+    win.__player && typeof win.__player.play === "function" ? win.__player : null;
+  const docDuration = readTimelineDurationFromDocument(iframe.contentDocument);
+  const adapterDur = getAdapterDuration(playerAdapter);
+
+  if (adapterDur > 0 && docDuration <= adapterDur) {
+    releaseStaticSeekCache(refs.cache, refs.warned);
+    return playerAdapter;
+  }
+
+  const timelines = pickTimelineAdapter(iframe, win, docDuration);
+  if (timelines.match) {
+    releaseStaticSeekCache(refs.cache, refs.warned);
+    return timelines.match;
+  }
+  const timelineAdapter = timelines.fallback;
+
+  // The document timeline extends past every native adapter's duration.
+  // Wrap the best available adapter with the effective duration so the
+  // seek slider, seek clamping, and duration display cover the full range.
+  const bestAdapter = playerAdapter ?? timelineAdapter;
+  const effectiveDuration = Math.max(usePlayerStore.getState().duration, docDuration, adapterDur);
+  if (
+    bestAdapter &&
+    effectiveDuration > 0 &&
+    ("renderSeek" in bestAdapter || typeof bestAdapter.seek === "function")
+  ) {
+    return resolveStaticSeekFallback({
+      cache: refs.cache,
+      warned: refs.warned,
+      bestAdapter,
+      effectiveDuration,
+      docDuration,
+      clock: getDefaultStaticSeekPlaybackClock(win),
+      getPlaybackRate: () => usePlayerStore.getState().playbackRate,
+    });
+  }
+
+  return bestAdapter;
+}

package/src/player/hooks/timelinePlayerTestHarness.ts

@@ -0,0 +1,120 @@
+// Shared test harness: mounts the real useTimelinePlayer and fakes an iframe
+// whose window exposes a playback adapter.
+import React, { act, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { vi } from "vitest";
+import { useTimelinePlayer, type UseTimelinePlayerOptions } from "./useTimelinePlayer";
+import { usePlayerStore } from "../store/playerStore";
+
+export type TimelinePlayerApi = ReturnType<typeof useTimelinePlayer>;
+
+export function resetPlayerStore() {
+  usePlayerStore.getState().reset();
+  usePlayerStore.setState({ requestedSeekTime: null });
+}
+
+function TimelinePlayerHarness({
+  onValue,
+  options,
+}: {
+  onValue: (value: TimelinePlayerApi) => void;
+  options?: UseTimelinePlayerOptions;
+}) {
+  const value = useTimelinePlayer(options);
+  useEffect(() => {
+    onValue(value);
+  }, [onValue, value]);
+  return null;
+}
+
+/** `api` is the first render's snapshot; `getApi()` returns the latest render's value. */
+export function renderTimelinePlayerHarness(options?: UseTimelinePlayerOptions) {
+  let latest: TimelinePlayerApi | null = null;
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+
+  act(() => {
+    root.render(
+      React.createElement(TimelinePlayerHarness, { onValue: (value) => (latest = value), options }),
+    );
+  });
+
+  if (!latest) throw new Error("useTimelinePlayer did not mount");
+  const rerender = (next?: UseTimelinePlayerOptions) =>
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, {
+          onValue: (value) => (latest = value),
+          options: next,
+        }),
+      );
+    });
+  return {
+    api: latest as TimelinePlayerApi,
+    getApi: () => latest as TimelinePlayerApi,
+    root,
+    rerender,
+  };
+}
+
+export function makeFakeIframe(iframeWindow: Record<string, unknown>): HTMLIFrameElement {
+  const iframe = document.createElement("iframe");
+  Object.defineProperty(iframe, "contentWindow", { value: iframeWindow, configurable: true });
+  Object.defineProperty(iframe, "contentDocument", {
+    value: document.implementation.createHTMLDocument("preview"),
+    configurable: true,
+  });
+  return iframe;
+}
+
+export function attachIframeWindow(api: TimelinePlayerApi, iframeWindow: Record<string, unknown>) {
+  const iframe = makeFakeIframe(iframeWindow);
+  act(() => {
+    api.iframeRef.current = iframe;
+    api.onIframeLoad();
+  });
+}
+
+export function makeAdapterWindow(
+  options: {
+    postMessage?: (message: unknown, targetOrigin: string) => void;
+    timelines?: Record<string, unknown>;
+    duration?: number;
+  } = {},
+) {
+  let currentTime = 0;
+  let playing = false;
+  const adapter = {
+    play: vi.fn(() => {
+      playing = true;
+    }),
+    pause: vi.fn(() => {
+      playing = false;
+    }),
+    seek: (time: number) => {
+      currentTime = time;
+    },
+    getTime: () => currentTime,
+    getDuration: () => options.duration ?? 30,
+    isPlaying: () => playing,
+  };
+  const win = {
+    __player: adapter,
+    __timelines: options.timelines,
+    postMessage: options.postMessage ?? (() => {}),
+    scrollTo: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+  };
+  return { adapter, win };
+}
+
+export function attachIframeAdapter(
+  api: TimelinePlayerApi,
+  options: Parameters<typeof makeAdapterWindow>[0] = {},
+) {
+  const { adapter, win } = makeAdapterWindow(options);
+  attachIframeWindow(api, win);
+  return adapter;
+}

package/src/player/hooks/usePlayerHandle.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment happy-dom
+
+import React, { useEffect } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+import { makeAdapterWindow, makeFakeIframe } from "./timelinePlayerTestHarness";
+import { usePlayerHandle, type PlayerHandle } from "./usePlayerHandle";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+function renderHandle() {
+  let latest: PlayerHandle | null = null;
+  let context: NLEContextValue | null = null;
+  let renders = 0;
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(
+      <NLEProvider projectId="player-handle-test">
+        <HandleHarness
+          onContext={(value) => (context = value)}
+          onValue={(value) => (latest = value)}
+          onRender={() => renders++}
+        />
+      </NLEProvider>,
+    );
+  });
+  if (!latest || !context) throw new Error("usePlayerHandle did not mount");
+  return {
+    root,
+    getHandle: () => latest as PlayerHandle,
+    getContext: () => context as NLEContextValue,
+    getRenderCount: () => renders,
+  };
+}
+
+function HandleHarness({
+  onContext,
+  onValue,
+  onRender,
+}: {
+  onContext: (value: NLEContextValue) => void;
+  onValue: (value: PlayerHandle) => void;
+  onRender: () => void;
+}) {
+  onRender();
+  const context = useNLEContext();
+  const handle = usePlayerHandle();
+  useEffect(() => {
+    onContext(context);
+    onValue(handle);
+  }, [context, handle, onContext, onValue]);
+  return null;
+}
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+  document.body.innerHTML = "";
+});
+
+describe("usePlayerHandle", () => {
+  it("refuses seek before readiness and notifies structural changes independently", () => {
+    const { root, getHandle } = renderHandle();
+    const handle = getHandle();
+
+    expect(handle.ready).toBe(false);
+    expect(handle.seek(4)).toBe(false);
+
+    const structuralListener = vi.fn();
+    const unsubscribe = handle.subscribe(structuralListener);
+    act(() => usePlayerStore.setState({ timelineReady: true }));
+    expect(structuralListener).toHaveBeenCalledTimes(1);
+    act(() => usePlayerStore.setState({ duration: 8 }));
+    expect(structuralListener).toHaveBeenCalledTimes(2);
+    act(() =>
+      usePlayerStore.setState({
+        elements: [
+          {
+            id: "clip",
+            tag: "div",
+            start: 2,
+            duration: 3,
+            track: 0,
+            selector: "#clip",
+            sourceFile: "index.html",
+            compositionSrc: "compositions/intro.html",
+          },
+        ],
+      }),
+    );
+    expect(structuralListener).toHaveBeenCalledTimes(3);
+    expect(getHandle().elements).toEqual([
+      {
+        id: "clip",
+        start: 2,
+        end: 5,
+        selector: "#clip",
+        sourceFile: "index.html",
+        compositionSrc: "compositions/intro.html",
+      },
+    ]);
+
+    unsubscribe();
+    act(() => root.unmount());
+  });
+
+  it("uses the shell player to seek a real preview adapter after readiness", async () => {
+    const { root, getContext, getHandle } = renderHandle();
+    const { adapter, win } = makeAdapterWindow();
+    await act(async () => {
+      getContext().iframeRef.current = makeFakeIframe(win);
+      getContext().onIframeLoad();
+      await Promise.resolve();
+    });
+
+    expect(usePlayerStore.getState().timelineReady).toBe(true);
+    expect(getHandle().seek(4)).toBe(true);
+    expect(adapter.getTime()).toBe(4);
+    expect(usePlayerStore.getState().currentTime).toBe(4);
+    act(() => getHandle().play());
+    expect(getHandle().playing).toBe(true);
+
+    act(() => root.unmount());
+  });
+
+  it("keeps playback time out of React renders and forwards live time notifications", () => {
+    const { root, getHandle, getRenderCount } = renderHandle();
+    const initialRenderCount = getRenderCount();
+    const timeListener = vi.fn();
+    const structuralListener = vi.fn();
+    const unsubscribeTime = getHandle().subscribeTime(timeListener);
+    const unsubscribe = getHandle().subscribe(structuralListener);
+
+    act(() => {
+      usePlayerStore.setState({ currentTime: 2.5 });
+      liveTime.notify(7.25);
+    });
+
+    expect(getRenderCount()).toBe(initialRenderCount);
+    expect(getHandle().currentTime).toBe(2.5);
+    expect(timeListener).toHaveBeenCalledWith(7.25);
+    expect(structuralListener).not.toHaveBeenCalled();
+
+    unsubscribeTime();
+    unsubscribe();
+    act(() => root.unmount());
+  });
+});

package/src/player/hooks/usePlayerHandle.ts

@@ -0,0 +1,94 @@
+import { useCallback, useMemo } from "react";
+import { liveTime, usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { useNLEContext } from "../../components/nle/NLEContext";
+
+export interface PlayerHandleElement {
+  id: string;
+  start: number;
+  end: number;
+  selector?: string;
+  sourceFile?: string;
+  compositionSrc?: string;
+}
+
+export type PlayerHandleListener = () => void;
+export type PlayerHandleTimeListener = (time: number) => void;
+
+export interface PlayerHandle {
+  ready: boolean;
+  playing: boolean;
+  seek: (seconds: number) => boolean;
+  play: () => void;
+  pause: () => void;
+  togglePlay: () => void;
+  readonly currentTime: number;
+  duration: number;
+  elements: PlayerHandleElement[];
+  subscribe: (listener: PlayerHandleListener) => () => void;
+  subscribeTime: (listener: PlayerHandleTimeListener) => () => void;
+}
+
+function toHandleElement(element: TimelineElement): PlayerHandleElement {
+  return {
+    id: element.id,
+    start: element.start,
+    end: element.start + element.duration,
+    selector: element.selector,
+    sourceFile: element.sourceFile,
+    compositionSrc: element.compositionSrc,
+  };
+}
+
+/**
+ * Reads and controls the shell player. Call this under EditorShell/NLEProvider;
+ * the provider owns the mounted preview iframe and the single player instance.
+ */
+export function usePlayerHandle(): PlayerHandle {
+  const { play, pause, togglePlay, seek: seekPlayer } = useNLEContext();
+  const ready = usePlayerStore((state) => state.timelineReady);
+  const playing = usePlayerStore((state) => state.isPlaying);
+  const duration = usePlayerStore((state) => state.duration);
+  const elements = usePlayerStore((state) => state.elements);
+
+  const seek = useCallback(
+    (seconds: number) => {
+      if (!ready) return false;
+      return seekPlayer(seconds);
+    },
+    [ready, seekPlayer],
+  );
+
+  const subscribe = useCallback((listener: PlayerHandleListener) => {
+    let previous = usePlayerStore.getState();
+    return usePlayerStore.subscribe((state) => {
+      const structuralChange =
+        state.timelineReady !== previous.timelineReady ||
+        state.isPlaying !== previous.isPlaying ||
+        state.duration !== previous.duration ||
+        state.elements !== previous.elements;
+      previous = state;
+      if (structuralChange) listener();
+    });
+  }, []);
+
+  const subscribeTime = useCallback((listener: PlayerHandleTimeListener) => {
+    return liveTime.subscribe(listener);
+  }, []);
+  const handleElements = useMemo(() => elements.map(toHandleElement), [elements]);
+
+  return {
+    ready,
+    playing,
+    seek,
+    play,
+    pause,
+    togglePlay,
+    get currentTime() {
+      return usePlayerStore.getState().currentTime;
+    },
+    duration,
+    elements: handleElements,
+    subscribe,
+    subscribeTime,
+  };
+}

package/src/player/hooks/usePreviewFirstFrameTelemetry.ts

@@ -0,0 +1,51 @@
+import { useCallback, useRef } from "react";
+import { parseTimelineFromDOM } from "../lib/timelineDOM";
+import { readTimelineDurationFromDocument } from "../lib/timelineElementHelpers";
+import type { PreviewIframeSlot } from "./useTimelineSyncCallbacks";
+import { trackPreviewFirstFrame } from "../../telemetry/events";
+import { getBrowserSystemMeta } from "../../telemetry/system";
+
+export function readPreviewComplexity(doc: Document | null | undefined): {
+  clip_count: number;
+  media_clip_count: number;
+} {
+  if (!doc) return { clip_count: 0, media_clip_count: 0 };
+  const elements = parseTimelineFromDOM(doc, readTimelineDurationFromDocument(doc));
+  return {
+    clip_count: elements.length,
+    media_clip_count: elements.filter(({ tag }) => tag === "video" || tag === "audio").length,
+  };
+}
+
+export function usePreviewFirstFrameTelemetry(previewSlots: PreviewIframeSlot[]) {
+  const previewSlotsRef = useRef(previewSlots);
+  previewSlotsRef.current = previewSlots;
+  const reportedPaintsRef = useRef(new Set<string>());
+
+  return useCallback(
+    (
+      slot: PreviewIframeSlot,
+      {
+        iframe,
+        startedAt,
+        loadId,
+      }: { iframe: HTMLIFrameElement; startedAt: number; loadId: number },
+    ) => {
+      const currentSlot = previewSlotsRef.current.find(
+        (candidate) => candidate.gen === slot.gen && candidate.role === slot.role,
+      );
+      if (!currentSlot) return;
+      const reportKey = `${slot.role}:${slot.gen}:${loadId}`;
+      if (reportedPaintsRef.current.has(reportKey)) return;
+      reportedPaintsRef.current.add(reportKey);
+      const complexity = readPreviewComplexity(iframe.contentDocument);
+      trackPreviewFirstFrame({
+        duration_ms: Math.max(0, Math.round(performance.now() - startedAt)),
+        composition_seconds: readTimelineDurationFromDocument(iframe.contentDocument),
+        ...complexity,
+        studio_version: getBrowserSystemMeta().studio_version,
+      });
+    },
+    [],
+  );
+}

package/src/player/hooks/useShadowPreviewReload.ts

@@ -0,0 +1,183 @@
+// Loads a full-reload edit in a hidden shadow iframe and promotes it once painted,
+// so the live iframe never shows a blank frame.
+
+import { useCallback, useRef, useState } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { logReload } from "../../utils/reloadDebug";
+import {
+  useTimelineSyncCallbacks,
+  planShadowReload,
+  planShadowPromotion,
+  planShadowDiscard,
+  type PreviewIframeSlot,
+  type UseTimelineSyncCallbacksParams,
+} from "./useTimelineSyncCallbacks";
+import type { PlaybackAdapter } from "../lib/playbackTypes";
+
+// The single wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
+// leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
+export const SHADOW_READY_TIMEOUT_MS = 15_000;
+
+type UseShadowPreviewReloadParams = Omit<
+  UseTimelineSyncCallbacksParams,
+  "probeIntervalRef" | "onAdapterReady" | "getAdapter" | "isCurrent" | "onLoadGiveUp"
+> & {
+  getAdapter: (overrideIframe?: HTMLIFrameElement | null) => PlaybackAdapter | null;
+  /** Runs right after a shadow becomes the live iframe (iframeRef already points at it). */
+  onPromoted?: () => void;
+  /** A shadow that never became ready was dropped; the live preview is unchanged. */
+  onReloadFailed?: (message: string) => void;
+};
+
+export function useShadowPreviewReload({
+  iframeRef,
+  getAdapter,
+  pendingSeekRef,
+  isRefreshingRef,
+  syncTimelineElements,
+  setDuration,
+  setCurrentTime,
+  requestTimelineReady,
+  setIsPlaying,
+  attachIframeShortcutListeners,
+  applyPreviewAudioState,
+  onPromoted,
+  onReloadFailed,
+}: UseShadowPreviewReloadParams) {
+  const shadowIframeRef = useRef<HTMLIFrameElement | null>(null);
+  const shadowProbeIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
+  // Invalidation counter, separate from the live slot's key: bumping it never remounts the live Player.
+  const shadowGenRef = useRef(0);
+  const pendingCommitRef = useRef<{ gen: number; commit: () => void } | null>(null);
+  const visuallyReadyGenRef = useRef<number | null>(null);
+  const onPromotedRef = useRef(onPromoted);
+  onPromotedRef.current = onPromoted;
+  const onReloadFailedRef = useRef(onReloadFailed);
+  onReloadFailedRef.current = onReloadFailed;
+  const readyTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const cancelPendingLoadRef = useRef<() => void>(() => {});
+  const [previewSlots, setPreviewSlots] = useState<PreviewIframeSlot[]>([{ gen: 0, role: "live" }]);
+
+  const stopPendingShadow = useCallback(() => {
+    clearTimeout(readyTimerRef.current);
+    cancelPendingLoadRef.current();
+    pendingCommitRef.current = null;
+    visuallyReadyGenRef.current = null;
+  }, []);
+
+  const failShadow = useCallback(
+    (gen: number, cause: string) => {
+      if (gen !== shadowGenRef.current) return;
+      shadowGenRef.current += 1;
+      stopPendingShadow();
+      shadowIframeRef.current = null;
+      isRefreshingRef.current = false;
+      pendingSeekRef.current = null;
+      setPreviewSlots(planShadowDiscard);
+      const message = `The preview did not reload (${cause}). The previous preview is still showing.`;
+      logReload("shadow-failed", { cause });
+      console.error(`[studio] ${message}`);
+      onReloadFailedRef.current?.(message);
+    },
+    [stopPendingShadow, isRefreshingRef, pendingSeekRef],
+  );
+
+  const promoteWhenReady = useCallback(
+    (gen: number) => {
+      const shadow = shadowIframeRef.current;
+      const pending = pendingCommitRef.current;
+      const ready = pending?.gen === gen && visuallyReadyGenRef.current === gen;
+      if (!shadow || !pending || !ready || gen !== shadowGenRef.current) return;
+      stopPendingShadow();
+      // The store takes the new document's timeline only now that it is the one on screen.
+      pending.commit();
+      iframeRef.current = shadow;
+      shadowIframeRef.current = null;
+      attachIframeShortcutListeners();
+      applyPreviewAudioState();
+      setPreviewSlots((prev) => planShadowPromotion(prev, gen));
+      onPromotedRef.current?.();
+    },
+    [stopPendingShadow, iframeRef, attachIframeShortcutListeners, applyPreviewAudioState],
+  );
+
+  const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
+  const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);
+  const markAdapterReady = useCallback(
+    (_iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
+      if (gen == null || gen !== shadowGenRef.current) return;
+      pendingCommitRef.current = { gen, commit };
+      promoteWhenReady(gen);
+    },
+    [promoteWhenReady],
+  );
+
+  const { onIframeLoad: onShadowIframeLoad, cancelPendingLoad } = useTimelineSyncCallbacks({
+    iframeRef: shadowIframeRef,
+    probeIntervalRef: shadowProbeIntervalRef,
+    pendingSeekRef,
+    isRefreshingRef,
+    getAdapter: getShadowAdapter,
+    syncTimelineElements,
+    setDuration,
+    setCurrentTime,
+    requestTimelineReady,
+    setIsPlaying,
+    // A hidden shadow gets neither: shortcuts and audio state apply once it is promoted.
+    attachIframeShortcutListeners: () => {},
+    applyPreviewAudioState: () => {},
+    onAdapterReady: markAdapterReady,
+    isCurrent: isCurrentShadow,
+  });
+  cancelPendingLoadRef.current = cancelPendingLoad;
+
+  // The Player reports whether loaders (shader transition, assets) are cleared right now.
+  const onShadowReadyChange = useCallback(
+    (gen: number, ready: boolean) => {
+      if (gen !== shadowGenRef.current) return;
+      visuallyReadyGenRef.current = ready ? gen : null;
+      if (ready) promoteWhenReady(gen);
+    },
+    [promoteWhenReady],
+  );
+
+  const setShadowIframeNode = useCallback((node: HTMLIFrameElement | null) => {
+    shadowIframeRef.current = node;
+  }, []);
+
+  const beginShadowReload = useCallback(
+    (url: string) => {
+      shadowGenRef.current += 1;
+      const gen = shadowGenRef.current;
+      stopPendingShadow();
+      readyTimerRef.current = setTimeout(
+        () => failShadow(gen, "it took too long to load"),
+        SHADOW_READY_TIMEOUT_MS,
+      );
+      setPreviewSlots((prev) => planShadowReload(prev, gen, url));
+    },
+    [stopPendingShadow, failShadow],
+  );
+
+  // Composition switch (not an edit reload): drop any in-flight shadow.
+  const resetPreviewSlots = useCallback(() => {
+    shadowGenRef.current += 1;
+    stopPendingShadow();
+    shadowIframeRef.current = null;
+    isRefreshingRef.current = false;
+    pendingSeekRef.current = null;
+    setPreviewSlots(planShadowDiscard);
+  }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);
+
+  useMountEffect(() => stopPendingShadow);
+
+  return {
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError: failShadow,
+    setShadowIframeNode,
+    beginShadowReload,
+    resetPreviewSlots,
+  };
+}