@hyperframes/studio 0.8.56 → 0.8.58

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

@@ -1,105 +1,25 @@
 // @vitest-environment happy-dom
 
-import React, { act, useEffect } from "react";
-import { createRoot } from "react-dom/client";
+import { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { useTimelinePlayer } from "./useTimelinePlayer";
+import type { useTimelinePlayer } from "./useTimelinePlayer";
+import {
+  attachIframeAdapter,
+  attachIframeWindow,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
 import { liveTime, usePlayerStore } from "../store/playerStore";
 import { setTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
-function resetPlayerStore() {
-  usePlayerStore.getState().reset();
-  usePlayerStore.setState({ requestedSeekTime: null });
-}
-
-function TimelinePlayerHarness({
-  onValue,
-}: {
-  onValue: (value: ReturnType<typeof useTimelinePlayer>) => void;
-}) {
-  const value = useTimelinePlayer();
-  useEffect(() => {
-    onValue(value);
-  }, [onValue, value]);
-  return null;
-}
-
-function renderTimelinePlayerHarness() {
-  let api: ReturnType<typeof useTimelinePlayer> | null = null;
-  const host = document.createElement("div");
-  document.body.append(host);
-  const root = createRoot(host);
-
-  act(() => {
-    root.render(React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }));
-  });
-
-  if (!api) throw new Error("useTimelinePlayer did not mount");
-  return { api, root };
-}
-
 afterEach(() => {
   setTimelinePerformanceFixtureLease(false);
   document.body.innerHTML = "";
   resetPlayerStore();
 });
 
-function attachIframeWindow(
-  api: ReturnType<typeof useTimelinePlayer>,
-  iframeWindow: Record<string, unknown>,
-): void {
-  const iframe = document.createElement("iframe");
-  Object.defineProperty(iframe, "contentWindow", {
-    value: iframeWindow,
-    configurable: true,
-  });
-  Object.defineProperty(iframe, "contentDocument", {
-    value: document.implementation.createHTMLDocument("preview"),
-    configurable: true,
-  });
-  act(() => {
-    api.iframeRef.current = iframe;
-    api.onIframeLoad();
-  });
-}
-
-function attachIframeAdapter(
-  api: ReturnType<typeof useTimelinePlayer>,
-  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,
-  };
-  attachIframeWindow(api, {
-    __player: adapter,
-    __timelines: options.timelines,
-    postMessage: options.postMessage ?? (() => {}),
-    scrollTo: () => {},
-    addEventListener: () => {},
-    removeEventListener: () => {},
-  });
-  return adapter;
-}
-
 function renderAttachedTimelinePlayer() {
   const { api, root } = renderTimelinePlayerHarness();
   const adapter = attachIframeAdapter(api);

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