@hyperframes/studio 0.8.56 → 0.8.57

package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts

@@ -0,0 +1,457 @@
+// @vitest-environment happy-dom
+// A full-reload edit must never hide the live iframe until the shadow has painted.
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload";
+import { usePlayerStore } from "../store/playerStore";
+import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
+import {
+  makeAdapterWindow,
+  makeFakeIframe,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock("../../utils/gsapSoftReload", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../utils/gsapSoftReload")>()),
+  ensureMotionPathPluginLoaded: vi.fn(),
+}));
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+function makeLiveIframe(): HTMLIFrameElement {
+  const iframe = makeFakeIframe(makeAdapterWindow().win);
+  iframe.src = "http://localhost/api/projects/demo/preview";
+  return iframe;
+}
+
+function makeShadowWithSpies() {
+  const { adapter, win } = makeAdapterWindow();
+  adapter.seek = vi.fn(adapter.seek);
+  const iframe = makeFakeIframe(win);
+  iframe.src = "http://localhost/api/projects/demo/preview?_t=1";
+  return { adapter, iframe };
+}
+
+describe("useTimelinePlayer shadow reload", () => {
+  it("never hides or removes the live iframe before the shadow signals it has painted", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const liveIframe = makeLiveIframe();
+
+    act(() => {
+      getApi().iframeRef.current = liveIframe;
+      getApi().onIframeLoad();
+    });
+
+    expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
+    expect(liveIframe.style.visibility).toBe("");
+
+    // A lane-move drop persists, then bumps refreshKey -> refreshPlayer().
+    act(() => {
+      getApi().refreshPlayer();
+    });
+
+    // The live iframe must be untouched: still the ref target, still visible,
+    // still in the slot list as "live". A shadow slot appears alongside it —
+    // this is the queued background reload, not a swap.
+    expect(getApi().iframeRef.current).toBe(liveIframe);
+    expect(liveIframe.style.visibility).toBe("");
+    expect(getApi().previewSlots).toHaveLength(2);
+    const liveSlot = getApi().previewSlots.find((s) => s.role === "live");
+    const shadowSlot = getApi().previewSlots.find((s) => s.role === "shadow");
+    expect(liveSlot).toEqual({ gen: 0, role: "live" });
+    expect(shadowSlot?.role).toBe("shadow");
+    expect(shadowSlot?.url).toBeTruthy();
+
+    // The shadow iframe loads and its restore-seek finds a ready adapter —
+    // the readiness signal this whole mechanism hangs off.
+    const shadowIframe = makeLiveIframe();
+    act(() => {
+      getApi().setShadowIframeNode(shadowIframe);
+    });
+
+    // Still untouched right up to the instant before the ready signal.
+    expect(getApi().iframeRef.current).toBe(liveIframe);
+    expect(liveIframe.style.visibility).toBe("");
+
+    act(() => {
+      getApi().onShadowIframeLoad(shadowSlot!.gen);
+      getApi().onShadowReadyChange(shadowSlot!.gen, true);
+    });
+
+    // Promotion: a single atomic swap. Exactly one live slot, pointing at the
+    // shadow's iframe; the old live slot is gone, not merely hidden.
+    expect(getApi().previewSlots).toEqual([
+      { gen: shadowSlot!.gen, role: "live", url: shadowSlot!.url },
+    ]);
+    expect(getApi().iframeRef.current).toBe(shadowIframe);
+
+    unmount(root);
+  });
+
+  it("replaces a superseded shadow rather than accumulating extra slots (repeated lane-moves)", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const liveIframe = makeLiveIframe();
+    act(() => {
+      getApi().iframeRef.current = liveIframe;
+      getApi().onIframeLoad();
+    });
+
+    act(() => {
+      getApi().refreshPlayer();
+    });
+    const firstShadowGen = getApi().previewSlots.find((s) => s.role === "shadow")?.gen;
+    expect(firstShadowGen).toBeDefined();
+
+    // The first shadow's iframe finishes loading and is fully adapter-ready
+    // (a real "would have painted correctly" candidate) before it is
+    // superseded.
+    const firstShadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(firstShadow.iframe);
+    });
+
+    // A second edit lands before the first shadow's readiness was consumed.
+    act(() => {
+      getApi().refreshPlayer();
+    });
+
+    // Never more than one extra (shadow) slot alive at a time.
+    expect(getApi().previewSlots).toHaveLength(2);
+    const secondShadow = getApi().previewSlots.find((s) => s.role === "shadow");
+    expect(secondShadow?.gen).not.toBe(firstShadowGen);
+
+    // The first shadow's readiness signal now arrives late (its own iframe is
+    // still referenced, fully ready). It must NOT promote — that content was
+    // replaced before it ever painted, and gen no longer matches the current
+    // pending shadow.
+    act(() => {
+      getApi().onShadowIframeLoad(firstShadowGen!);
+      getApi().onShadowReadyChange(firstShadowGen!, true);
+    });
+    expect(getApi().previewSlots.find((s) => s.role === "live")).toEqual({ gen: 0, role: "live" });
+    expect(getApi().iframeRef.current).toBe(liveIframe);
+    expect(firstShadow.adapter.seek).not.toHaveBeenCalled();
+
+    unmount(root);
+  });
+});
+
+describe("drop that removes a covered clip (reloadPreview -> refreshKey bump)", () => {
+  it("swaps in the reloaded document without ever hiding the live iframe", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("{}", { status: 404 })),
+    );
+    let ctx: NLEContextValue | null = null;
+    const Probe = () => {
+      ctx = useNLEContext();
+      return null;
+    };
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const render = (refreshKey: number) =>
+      act(async () => {
+        root.render(
+          React.createElement(
+            NLEProvider,
+            { projectId: "demo", refreshKey },
+            React.createElement(Probe),
+          ),
+        );
+        await Promise.resolve();
+      });
+    await render(0);
+    const live = makeLiveIframe();
+    await act(async () => {
+      ctx!.iframeRef.current = live;
+      ctx!.onIframeLoad();
+    });
+
+    // runPlacementSteps ends in exactly one reloadPreview: App bumps refreshKey.
+    await render(1);
+    expect(live.style.visibility).toBe("");
+    expect(ctx!.iframeRef.current).toBe(live);
+    const shadow = ctx!.previewSlots.find((s) => s.role === "shadow");
+    expect(shadow).toBeDefined();
+    expect(ctx!.previewSlots).toHaveLength(2);
+
+    const shadowIframe = makeLiveIframe();
+    await act(async () => {
+      ctx!.setShadowIframeNode(shadowIframe);
+      ctx!.onShadowIframeLoad(shadow!.gen);
+      ctx!.onShadowReadyChange(shadow!.gen, true);
+    });
+    expect(ctx!.previewSlots).toEqual([{ ...shadow!, role: "live" }]);
+    expect(ctx!.iframeRef.current).toBe(shadowIframe);
+
+    await act(async () => root.unmount());
+    vi.unstubAllGlobals();
+  });
+});
+
+describe("shadow reload readiness and failure", () => {
+  function beginReload(options: Parameters<typeof renderTimelinePlayerHarness>[0] = {}) {
+    const harness = renderTimelinePlayerHarness(options);
+    const { adapter, win } = makeAdapterWindow();
+    adapter.seek = vi.fn(adapter.seek);
+    const live = makeFakeIframe(win);
+    act(() => {
+      harness.getApi().iframeRef.current = live;
+      harness.getApi().onIframeLoad();
+    });
+    adapter.pause.mockClear();
+    act(() => harness.getApi().refreshPlayer());
+    const gen = harness.getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    return { ...harness, live, liveAdapter: adapter, gen };
+  }
+
+  it("pauses the live adapter when a reload starts", () => {
+    const { liveAdapter, root } = beginReload();
+    expect(liveAdapter.pause).toHaveBeenCalled();
+    unmount(root);
+  });
+
+  it("does not promote a shadow whose loader is still up, and promotes once it clears", () => {
+    const { getApi, live, gen, root } = beginReload();
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+    });
+    expect(getApi().iframeRef.current).toBe(live);
+    expect(getApi().previewSlots).toHaveLength(2);
+
+    act(() => getApi().onShadowReadyChange(gen, true));
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    expect(getApi().previewSlots).toEqual([{ gen, role: "live", url: expect.any(String) }]);
+    unmount(root);
+  });
+
+  it("promotes when the loader clears before the adapter is ready", () => {
+    const { getApi, gen, root } = beginReload();
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().previewSlots).toHaveLength(2);
+    act(() => getApi().onShadowIframeLoad(gen));
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    unmount(root);
+  });
+
+  it("drops a shadow that never becomes ready, keeps the live frame and reports why", () => {
+    vi.useFakeTimers();
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, live, root } = beginReload({ onPreviewReloadFailed });
+    expect(getApi().previewSlots).toHaveLength(2);
+
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS));
+
+    expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
+    expect(getApi().iframeRef.current).toBe(live);
+    expect(live.style.visibility).toBe("");
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    expect(consoleError).toHaveBeenCalled();
+    unmount(root);
+  });
+
+  it("keeps a slow shadow pending past 5s and fails it only at the single budget", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, gen, root } = beginReload({ onPreviewReloadFailed });
+    const silent = makeFakeIframe({});
+    act(() => {
+      getApi().setShadowIframeNode(silent);
+      getApi().onShadowIframeLoad(gen);
+    });
+
+    act(() => void vi.advanceTimersByTime(5001));
+    expect(getApi().previewSlots).toHaveLength(2);
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS));
+    expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    unmount(root);
+  });
+
+  it("drops a shadow whose document reports an error and reports the cause", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, live, gen, root } = beginReload({ onPreviewReloadFailed });
+
+    act(() => getApi().onShadowError(gen, "Composition timeline not found after 8s"));
+
+    expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
+    expect(getApi().iframeRef.current).toBe(live);
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(
+      expect.stringContaining("Composition timeline not found after 8s"),
+    );
+    unmount(root);
+  });
+
+  it("runs no load side effects for a superseded shadow", () => {
+    const { getApi, gen, root } = beginReload();
+    usePlayerStore.getState().setCurrentTime(7);
+    const stale = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(stale.iframe);
+      getApi().refreshPlayer();
+    });
+    act(() => getApi().onShadowIframeLoad(gen));
+    expect(stale.adapter.seek).not.toHaveBeenCalled();
+    unmount(root);
+  });
+});
+
+describe("shadow reload store ownership and readiness", () => {
+  function setup(options?: Parameters<typeof renderTimelinePlayerHarness>[0]) {
+    const harness = renderTimelinePlayerHarness(options);
+    const live = makeAdapterWindow({ duration: 10 });
+    const liveIframe = makeFakeIframe(live.win);
+    act(() => {
+      harness.getApi().iframeRef.current = liveIframe;
+      harness.getApi().onIframeLoad();
+    });
+    act(() => harness.getApi().refreshPlayer());
+    const gen = harness.getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeAdapterWindow({ duration: 42 });
+    const shadowIframe = makeFakeIframe(shadow.win);
+    act(() => harness.getApi().setShadowIframeNode(shadowIframe));
+    return { ...harness, gen, shadowIframe, liveIframe };
+  }
+
+  it("does not promote when the loader re-raises after it had cleared", () => {
+    const { getApi, gen, liveIframe, root } = setup();
+    act(() => {
+      getApi().onShadowReadyChange(gen, true);
+      getApi().onShadowReadyChange(gen, false);
+      getApi().onShadowIframeLoad(gen);
+    });
+    expect(getApi().iframeRef.current).toBe(liveIframe);
+    act(() => getApi().onShadowReadyChange(gen, true));
+    expect(getApi().iframeRef.current).not.toBe(liveIframe);
+    unmount(root);
+  });
+
+  it("keeps the old timeline in the store until the shadow is promoted", () => {
+    const { getApi, gen, root } = setup();
+    const before = usePlayerStore.getState().duration;
+    act(() => getApi().onShadowIframeLoad(gen));
+    expect(usePlayerStore.getState().duration).toBe(before);
+    act(() => getApi().onShadowReadyChange(gen, true));
+    expect(usePlayerStore.getState().duration).toBe(42);
+    unmount(root);
+  });
+
+  it("never writes a failed shadow's timeline into the store", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const { getApi, gen, root } = setup();
+    const before = usePlayerStore.getState().duration;
+    act(() => getApi().onShadowIframeLoad(gen));
+    act(() => getApi().onShadowError(gen, "boom"));
+    expect(usePlayerStore.getState().duration).toBe(before);
+    unmount(root);
+  });
+
+  it("a composition switch clears the refresh flags so the next load restores the store playhead", () => {
+    const { getApi, liveIframe, root } = setup();
+    const seek = vi.fn();
+    (liveIframe.contentWindow as unknown as { __player: { seek: unknown } }).__player.seek = seek;
+    usePlayerStore.getState().setCurrentTime(7);
+    act(() => getApi().resetPreviewSlots());
+    act(() => getApi().onIframeLoad());
+    expect(seek).toHaveBeenCalledWith(7);
+    unmount(root);
+  });
+
+  it("uses the latest failure callback for a timer armed before it changed", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const first = vi.fn();
+    const latest = vi.fn();
+    const { getApi, rerender, root } = setup({ onPreviewReloadFailed: first });
+    expect(getApi().previewSlots).toHaveLength(2);
+    rerender({ onPreviewReloadFailed: latest });
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS));
+    expect(latest).toHaveBeenCalled();
+    expect(first).not.toHaveBeenCalled();
+    unmount(root);
+  });
+});
+
+describe("NLEProvider iframe ref notifications", () => {
+  it("tells the consumer about the reloaded iframe once, on promotion", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("{}", { status: 404 })),
+    );
+    const { ensureMotionPathPluginLoaded } = await import("../../utils/gsapSoftReload");
+    const onIframeRef = vi.fn();
+    let ctx: NLEContextValue | null = null;
+    const Probe = () => {
+      ctx = useNLEContext();
+      return null;
+    };
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const render = (refreshKey: number) =>
+      act(async () => {
+        root.render(
+          React.createElement(
+            NLEProvider,
+            { projectId: "demo", refreshKey, onIframeRef },
+            React.createElement(Probe),
+          ),
+        );
+        await Promise.resolve();
+      });
+    await render(0);
+    const live = makeLiveIframe();
+    await act(async () => {
+      ctx!.iframeRef.current = live;
+      ctx!.onIframeLoad();
+    });
+    onIframeRef.mockClear();
+    vi.mocked(ensureMotionPathPluginLoaded).mockClear();
+
+    await render(1);
+    const callsAtBegin = onIframeRef.mock.calls.length;
+    expect(onIframeRef.mock.calls.every(([iframe]) => iframe === live)).toBe(true);
+
+    const shadow = ctx!.previewSlots.find((s) => s.role === "shadow")!;
+    const shadowIframe = makeLiveIframe();
+    await act(async () => {
+      ctx!.setShadowIframeNode(shadowIframe);
+      ctx!.onShadowIframeLoad(shadow.gen);
+      ctx!.onShadowReadyChange(shadow.gen, true);
+    });
+    expect(onIframeRef).toHaveBeenCalledTimes(callsAtBegin + 1);
+    expect(onIframeRef).toHaveBeenLastCalledWith(shadowIframe);
+    expect(ensureMotionPathPluginLoaded).toHaveBeenCalledWith(shadowIframe);
+
+    await act(async () => root.unmount());
+    vi.unstubAllGlobals();
+  });
+});
+
+function unmount(root: ReturnType<typeof createRoot>) {
+  act(() => {
+    root.unmount();
+  });
+}

package/src/player/hooks/useTimelinePlayer.ts

@@ -3,6 +3,8 @@ import { usePlayerStore, liveTime, type TimelineElement } from "../store/playerS
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
 import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
+import { useShadowPreviewReload } from "./useShadowPreviewReload";
+import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
 import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
 import { logReload } from "../../utils/reloadDebug";
 
@@ -24,18 +26,8 @@ export {
 } from "../lib/playbackShortcuts";
 
 import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
-import {
-  getAdapterDuration,
-  wrapTimeline,
-  getDefaultStaticSeekPlaybackClock,
-  releaseStaticSeekCache,
-  resolveStaticSeekFallback,
-  type StaticSeekCacheEntry,
-} from "../lib/playbackAdapter";
-import {
-  readTimelineDurationFromDocument,
-  mergeTimelineElementsPreservingDowngrades,
-} from "../lib/timelineDOM";
+import { releaseStaticSeekCache, type StaticSeekCacheEntry } from "../lib/playbackAdapter";
+import { mergeTimelineElementsPreservingDowngrades } from "../lib/timelineDOM";
 import { normalizeToZones } from "../components/timelineZones";
 import { applyPreviewAudioFlags, setPreviewPlaybackRate } from "../lib/timelineIframeHelpers";
 import { scrubMusicAtSeek, stopScrubPreviewAudio } from "../lib/playbackScrub";
@@ -47,7 +39,17 @@ import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
 import { safeContentDocument } from "./timelineSyncHydration";
 
-export function useTimelinePlayer() {
+export interface UseTimelinePlayerOptions {
+  /** Runs right after a reloaded preview becomes the live iframe. */
+  onShadowPromoted?: () => void;
+  /** A reload was abandoned (cause in the message); the previous preview is still showing. */
+  onPreviewReloadFailed?: (message: string) => void;
+}
+
+export function useTimelinePlayer({
+  onShadowPromoted,
+  onPreviewReloadFailed,
+}: UseTimelinePlayerOptions = {}) {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const rafRef = useRef<number>(0);
   const probeIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
@@ -128,84 +130,23 @@ export function useTimelinePlayer() {
     [setElements, requestTimelineReady, setDuration],
   );
 
-  // Pre-existing dispatcher complexity — surfaced by this PR's line shifts, not new logic.
-  // fallow-ignore-next-line complexity
-  const getAdapter = useCallback((): PlaybackAdapter | null => {
-    try {
-      const iframe = iframeRef.current;
-      const win = iframe?.contentWindow as IframeWindow | null;
-      if (!iframe || !win) return 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(staticSeekAdapterRef, staticSeekWarnedRef);
-        return playerAdapter;
-      }
-
-      let timelineAdapter: PlaybackAdapter | null = null;
-      if (win.__timeline) {
-        const adapter = wrapTimeline(win.__timeline);
-        const dur = getAdapterDuration(adapter);
-        if (dur > 0 && docDuration <= dur) {
-          releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-          return adapter;
-        }
-        if (dur > 0) timelineAdapter ??= adapter;
-      }
-
-      if (win.__timelines) {
-        const keys = Object.keys(win.__timelines);
-        if (keys.length > 0) {
-          // Resolve the root composition id from the DOM — the outermost [data-composition-id]
-          // is the master; otherwise Object.keys() order lets 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];
-          const adapter = wrapTimeline(win.__timelines[key]);
-          const dur = getAdapterDuration(adapter);
-          if (dur > 0 && docDuration <= dur) {
-            releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-            return adapter;
-          }
-          if (dur > 0) timelineAdapter ??= adapter;
-        }
-      }
-
-      // 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({
+  const getAdapter = useCallback(
+    (overrideIframe?: HTMLIFrameElement | null): PlaybackAdapter | null => {
+      try {
+        // undefined means "no override"; an explicit null override means "no adapter".
+        const iframe = overrideIframe !== undefined ? overrideIframe : iframeRef.current;
+        const win = iframe?.contentWindow as IframeWindow | null;
+        if (!iframe || !win) return null;
+        return resolvePlaybackAdapter(iframe, win, {
           cache: staticSeekAdapterRef,
           warned: staticSeekWarnedRef,
-          bestAdapter,
-          effectiveDuration,
-          docDuration,
-          clock: getDefaultStaticSeekPlaybackClock(win),
-          getPlaybackRate: () => usePlayerStore.getState().playbackRate,
         });
+      } catch {
+        return null;
       }
-
-      return bestAdapter;
-    } catch {
-      return null;
-    }
-  }, []);
+    },
+    [],
+  );
 
   const { startRAFLoop, stopRAFLoop, stopReverseLoop } = useTimelinePlayerLoop({
     rafRef,
@@ -435,6 +376,32 @@ export function useTimelinePlayer() {
       attachIframeShortcutListeners,
       applyPreviewAudioState,
     });
+
+  // Full-reload edits load behind a hidden shadow iframe (useShadowPreviewReload.ts).
+  const {
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    beginShadowReload,
+    resetPreviewSlots,
+  } = useShadowPreviewReload({
+    iframeRef,
+    getAdapter,
+    pendingSeekRef,
+    isRefreshingRef,
+    syncTimelineElements,
+    setDuration,
+    setCurrentTime,
+    requestTimelineReady,
+    setIsPlaying,
+    attachIframeShortcutListeners,
+    applyPreviewAudioState,
+    onPromoted: onShadowPromoted,
+    onReloadFailed: onPreviewReloadFailed,
+  });
+
   const saveSeekPosition = useCallback(() => {
     // Never DEGRADE the saved position. Overlapping reloads (e.g. an external
     // file drop = upload reload + insert reload back-to-back) call this while
@@ -464,22 +431,15 @@ export function useTimelinePlayer() {
     if (!iframe) return;
     logReload("refreshPlayer", () => ({ stack: new Error("refreshPlayer").stack }));
     saveSeekPosition();
-    // Hide the iframe across the full reload so the user never sees the reloading
-    // document's RAW DOM (every clip stacked and visible) in the window between the
-    // new document parsing and the runtime initializing + seeking. initializeAdapter
-    // reveals it again right after its restore seek renders the correct frame.
-    // Tradeoff: this shows the parent stage background (a brief "freeze"/blank, on
-    // the order of the reload time ~100-300ms) INSTEAD of the all-clips flash. A
-    // blank is far less jarring than a burst of every asset appearing at once.
-    // Only the FULL-reload edits (drops/inserts) hit this — timing edits now take
-    // the soft-reload path and never touch refreshPlayer.
-    iframe.style.visibility = "hidden";
+    // The old iframe is no longer navigated away, so stop its playback (and audio) here.
+    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);
     url.searchParams.set("_t", String(Date.now()));
     applyPreviewVariablesToUrl(url);
-    iframe.src = url.toString();
-  }, [saveSeekPosition]);
+    beginShadowReload(url.toString());
+  }, [saveSeekPosition, getAdapter, beginShadowReload]);
   const getAdapterRef = useRef(getAdapter);
   getAdapterRef.current = getAdapter;
 
@@ -557,5 +517,11 @@ export function useTimelinePlayer() {
     refreshPlayer,
     saveSeekPosition,
     resetPlayer,
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    resetPreviewSlots,
   };
 }