From dab8dc80701f7c50aa5eba3ec77f3091f1bfd754 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 16 Nov 2026 05:21:00 +0000 Subject: [PATCH] fix(studio): a host that shows a still gets a preview reload with one page at a time (#7905) * fix(studio): a host that shows a still gets a preview reload with one page at a time A full reload kept the live page beside the reload's own until it was promoted, so a heavy project held two whole pages at once. A host that can show the live frame as a still (holdPreviewStill) now has the live page dropped behind it while the reload's page loads alone; the still goes once the new page shows the live time, and a reload that gives up brings the live page back at its time. With no still, nothing changes. * fix(studio): keep the reload hook's comment share at the base * fix(studio): pause before the still so a held reload resumes from the frame it shows * fix(studio): drop a give-up's still on the live page's own load, not a polled load event * fix(studio): a host that throws while taking the still falls back to the two-page reload --- .../player/hooks/useShadowPreviewReload.ts | 145 ++++++++++- .../useTimelinePlayer.reloadStill.test.ts | 241 ++++++++++++++++++ .../src/player/hooks/useTimelinePlayer.ts | 14 +- .../player/hooks/useTimelineSyncCallbacks.ts | 4 + 4 files changed, 389 insertions(+), 15 deletions(-) create mode 100644 packages/studio/src/player/hooks/useTimelinePlayer.reloadStill.test.ts diff --git a/packages/studio/src/player/hooks/useShadowPreviewReload.ts b/packages/studio/src/player/hooks/useShadowPreviewReload.ts index f3f90bae83..21cf21f661 100644 --- a/packages/studio/src/player/hooks/useShadowPreviewReload.ts +++ b/packages/studio/src/player/hooks/useShadowPreviewReload.ts @@ -12,6 +12,7 @@ import { refusedPreviewStatus } from "@hyperframes/core/studio-preview-mark"; import { logReload } from "../../utils/reloadDebug"; import { useTimelineSyncCallbacks, + planShadowAlone, planShadowReload, planShadowPromotion, planShadowDiscard, @@ -33,6 +34,28 @@ import { READY_TIMEOUT_CAUSE, useShadowReloadRetry } from "./useShadowReloadRetr export const SHADOW_READY_TIMEOUT_MS = 15_000; // A busy machine can need more than one budget; the shadow keeps loading for this many before it is dropped. export const SHADOW_READY_BUDGETS = 3; +const STILL_RELEASE_MAX_MS = 3_000; + +type HeldStill = { + release: () => void; + time: number | null; + playing: boolean; + liveSlot: PreviewIframeSlot; + liveIframe: HTMLIFrameElement; +}; + +function releaseAfterPaint(iframe: HTMLIFrameElement | null, release: () => void) { + let done = false; + const go = () => { + if (done) return; + done = true; + release(); + }; + setTimeout(go, STILL_RELEASE_MAX_MS); + void (restoreSeekPainted(iframe) ?? Promise.resolve()).then(() => + requestAnimationFrame(() => requestAnimationFrame(go)), + ); +} function restoreSeekPainted(iframe: HTMLIFrameElement | null): Promise | undefined { if (!iframe) return undefined; @@ -83,6 +106,8 @@ type UseShadowPreviewReloadParams = Omit< onReloadFailed?: (message: string) => void; /** Puts the promoted document at the live frame's time, playing if the live frame was. */ handOverPlayback: (time: number, playing: boolean) => void; + /** Covers the stage with the live frame so a reload holds one page; returns what drops it, null keeps two pages. */ + holdStill?: (live: HTMLIFrameElement) => Promise<(() => void) | null>; }; export function useShadowPreviewReload({ @@ -100,6 +125,7 @@ export function useShadowPreviewReload({ onPromoted, onReloadFailed, handOverPlayback, + holdStill, }: UseShadowPreviewReloadParams) { const shadowIframeRef = useRef(null); const shadowProbeIntervalRef = useRef | undefined>(undefined); @@ -127,6 +153,38 @@ export function useShadowPreviewReload({ const retry = useShadowReloadRetry(shadowGenRef, shadowUrlRef, beginShadowReloadRef); const promoteWhenReadyRef = useRef<(gen: number) => void>(() => {}); const [previewSlots, setPreviewSlots] = useState([{ gen: 0, role: "live" }]); + const slotsRef = useRef(previewSlots); + slotsRef.current = previewSlots; + const holdStillRef = useRef(holdStill); + holdStillRef.current = holdStill; + const heldRef = useRef(null); + // The newest reload asked for while a still is being taken; it starts once the still is up. + const holdingUrlRef = useRef(null); + const holdTokenRef = useRef(0); + + const restoringRef = useRef<(() => void) | null>(null); + const dropRestoring = useCallback(() => { + const release = restoringRef.current; + restoringRef.current = null; + release?.(); + }, []); + const restoreLive = useCallback( + (held: HeldStill) => { + dropRestoring(); + setPreviewSlots([held.liveSlot]); + pendingSeekRef.current = held.time; + restoringRef.current = held.release; + setTimeout(() => { + if (restoringRef.current === held.release) dropRestoring(); + }, SHADOW_READY_TIMEOUT_MS); + }, + [pendingSeekRef, dropRestoring], + ); + const onLiveLoaded = useCallback(() => { + const release = restoringRef.current; + restoringRef.current = null; + if (release) releaseAfterPaint(iframeRef.current, release); + }, [iframeRef]); const stopPendingShadow = useCallback(() => { clearTimeout(readyTimerRef.current); @@ -153,7 +211,10 @@ export function useShadowPreviewReload({ shadowIframeRef.current = null; isRefreshingRef.current = false; pendingSeekRef.current = null; - setPreviewSlots(planShadowDiscard); + const held = heldRef.current; + heldRef.current = null; + if (held) restoreLive(held); + else setPreviewSlots(planShadowDiscard); setPreviewReloading(false); const message = `The preview did not reload (${cause}). It was still waiting for ${waitingFor}.${got} The previous preview is still showing.`; logReload("shadow-failed", { cause, waitingFor }); @@ -163,7 +224,7 @@ export function useShadowPreviewReload({ onReloadFailedRef.current?.(message); retry.afterFailure(cause, failedGen); }, - [stopPendingShadow, retry, isRefreshingRef, pendingSeekRef], + [stopPendingShadow, retry, isRefreshingRef, pendingSeekRef, restoreLive], ); const gestureSavesOnScreen = useCallback(() => { @@ -195,11 +256,10 @@ export function useShadowPreviewReload({ return waitThenRetry(gen, "gesture", (retry) => afterStudioManualEditGestures(liveDoc, retry), ); - if ( - gestureSavesOnScreen() === savesAtRequestRef.current && - studioFileRevision() === revisionAtRequestRef.current - ) - return false; + // Behind a still the live page is gone, so it has no saves to count; only the file revision tells. + const savesSame = + heldRef.current !== null || gestureSavesOnScreen() === savesAtRequestRef.current; + if (savesSame && studioFileRevision() === revisionAtRequestRef.current) return false; if (isStudioEditSaving()) return waitThenRetry(gen, "save", afterStudioPendingEdits); logReload("shadow-reloaded-after-gesture-save", { gen }); const url = new URL(shadowUrlRef.current, window.location.origin); @@ -224,9 +284,11 @@ export function useShadowPreviewReload({ const { shadow, pending } = promotable; stopPendingShadow(); // The live frame kept playing, stopped at the end or was seeked while the shadow loaded. + const held = heldRef.current; + heldRef.current = null; const live = getAdapter(); - const liveTime = live?.getTime(); - const playing = usePlayerStore.getState().isPlaying; + const liveTime = held ? held.time : live?.getTime(); + const playing = held ? held.playing : usePlayerStore.getState().isPlaying; live?.pause(); // The store takes the new document's timeline only now that it is the one on screen, and reads it there. const retired = iframeRef.current; @@ -237,6 +299,7 @@ export function useShadowPreviewReload({ applyPreviewAudioState(); setPreviewSlots((prev) => planShadowPromotion(prev, gen)); if (liveTime != null) handOverPlaybackRef.current(liveTime, playing); + if (held) releaseAfterPaint(shadow, held.release); announcePreviewPromoted({ retired, live: shadow }); onPromotedRef.current?.(); setPreviewReloading(false); @@ -349,8 +412,8 @@ export function useShadowPreviewReload({ armReadyTimerRef.current(gen); }, []); - const beginShadowReload = useCallback( - (url: string) => { + const startShadowReload = useCallback( + (url: string, alone: boolean) => { retry.started(); shadowGenRef.current += 1; const gen = shadowGenRef.current; @@ -361,12 +424,55 @@ export function useShadowPreviewReload({ savesAtRequestRef.current = gestureSavesOnScreen(); revisionAtRequestRef.current = studioFileRevision(); armReadyTimer(gen); - setPreviewSlots((prev) => planShadowReload(prev, gen, url)); + setPreviewSlots((prev) => + alone ? planShadowAlone(gen, url) : planShadowReload(prev, gen, url), + ); // Thumbnails of the edit wait for the new preview instead of competing with it. setPreviewReloading(true); }, [retry, stopPendingShadow, armReadyTimer, gestureSavesOnScreen], ); + + const beginShadowReload = useCallback( + (url: string) => { + const live = iframeRef.current; + const take = holdStillRef.current; + if (heldRef.current || !take || !live?.isConnected) { + startShadowReload(url, heldRef.current !== null); + return; + } + if (holdingUrlRef.current !== null) { + holdingUrlRef.current = url; + return; + } + holdingUrlRef.current = url; + const token = ++holdTokenRef.current; + // Paused first, so the still is the frame the reload resumes from. + const playing = usePlayerStore.getState().isPlaying; + getAdapter()?.pause(); + const time = getAdapter()?.getTime() ?? null; + const liveSlot = slotsRef.current.find((slot) => slot.role === "live"); + void new Promise<(() => void) | null>((resolve) => resolve(take(live))) + // expected: a still that cannot be taken keeps both pages for this reload, as before + .catch(() => null) + .then((release) => { + if (token !== holdTokenRef.current) { + release?.(); + return; + } + const latest = holdingUrlRef.current ?? url; + holdingUrlRef.current = null; + if (release && liveSlot && iframeRef.current === live) { + heldRef.current = { release, time, playing, liveSlot, liveIframe: live }; + } else { + release?.(); + if (playing) getAdapter()?.play(); + } + startShadowReload(latest, heldRef.current !== null); + }); + }, + [iframeRef, getAdapter, startShadowReload], + ); beginShadowReloadRef.current = beginShadowReload; // Composition switch (not an edit reload): drop any in-flight shadow. @@ -378,9 +484,15 @@ export function useShadowPreviewReload({ isRefreshingRef.current = false; pendingSeekRef.current = null; usePlayerStore.getState().setTimelineReady(false); - setPreviewSlots(planShadowDiscard); + const held = heldRef.current; + heldRef.current = null; + holdingUrlRef.current = null; + holdTokenRef.current += 1; + dropRestoring(); + setPreviewSlots(held ? [held.liveSlot] : planShadowDiscard); + held?.release(); setPreviewReloading(false); - }, [retry, stopPendingShadow, isRefreshingRef, pendingSeekRef]); + }, [retry, stopPendingShadow, isRefreshingRef, pendingSeekRef, dropRestoring]); // Hiding the tab pauses the budget; showing it again restarts the full budget for a pending shadow. useMountEffect(() => { @@ -397,6 +509,10 @@ export function useShadowPreviewReload({ document.removeEventListener("visibilitychange", onVisibilityChange); retry.cancel(); stopPendingShadow(); + heldRef.current?.release(); + heldRef.current = null; + holdTokenRef.current += 1; + dropRestoring(); setPreviewReloading(false); }; }); @@ -410,5 +526,6 @@ export function useShadowPreviewReload({ beginShadowReload, resetPreviewSlots, previewGeneration, + onLiveLoaded, }; } diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.reloadStill.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.reloadStill.test.ts new file mode 100644 index 0000000000..630cec2479 --- /dev/null +++ b/packages/studio/src/player/hooks/useTimelinePlayer.reloadStill.test.ts @@ -0,0 +1,241 @@ +// @vitest-environment happy-dom +// fails without the fix: a reload kept the live page beside its own until promotion, so a heavy project held two whole +// pages (1.7x the app's resident memory) and ran out of memory. A host that can show the live +// frame as a still now gets one page at a time. + +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { SHADOW_READY_BUDGETS, SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload"; +import { usePlayerStore } from "../store/playerStore"; +import { + makeAdapterWindow, + makeFakeIframe, + renderTimelinePlayerHarness, + resetPlayerStore, +} from "./timelinePlayerTestHarness"; + +globalThis.IS_REACT_ACT_ENVIRONMENT = true; + +vi.mock("../../utils/gsapSoftReload", async (importOriginal) => ({ + ...(await importOriginal()), + ensureMotionPathPluginLoaded: vi.fn(), +})); + +afterEach(() => { + vi.useRealTimers(); + vi.restoreAllMocks(); + document.body.innerHTML = ""; + resetPlayerStore(); +}); + +const unmount = (root: ReturnType) => act(() => root.unmount()); + +/** A loaded live preview at 3 s, and a reload asked for with `hold` as the host's still. */ +async function reloadWithStill( + hold: (live: HTMLIFrameElement) => Promise<(() => void) | null>, + { playing = false } = {}, +) { + const harness = renderTimelinePlayerHarness({ holdPreviewStill: hold }); + const { adapter, win } = makeAdapterWindow(); + adapter.getTime = vi.fn(() => 3); + const live = makeFakeIframe(win); + act(() => { + harness.getApi().iframeRef.current = live; + harness.getApi().onIframeLoad(); + }); + if (playing) act(() => usePlayerStore.getState().setIsPlaying(true)); + await act(async () => { + harness.getApi().refreshPlayer(); + await Promise.resolve(); + }); + return { ...harness, live, liveAdapter: adapter }; +} + +describe("a reload behind the host's still", () => { + it("drops the live page before the reload's page loads, and the still once the new page shows the live time", async () => { + const release = vi.fn(); + const hold = vi.fn(async () => release); + const { getApi, root, live } = await reloadWithStill(hold); + + expect(hold).toHaveBeenCalledWith(live); + const slots = getApi().previewSlots; + expect(slots.map((slot) => slot.role)).toEqual(["shadow"]); + expect(release).not.toHaveBeenCalled(); + + const { adapter, win } = makeAdapterWindow(); + adapter.seek = vi.fn(adapter.seek); + const next = makeFakeIframe(win); + const gen = slots[0]!.gen; + act(() => { + getApi().setShadowIframeNode(next); + getApi().onShadowIframeLoad(gen); + getApi().onShadowReadyChange(gen, true); + }); + + expect(getApi().previewSlots).toEqual([{ gen, role: "live", url: slots[0]!.url }]); + expect(getApi().iframeRef.current).toBe(next); + expect(adapter.seek).toHaveBeenCalledWith(3); + await vi.waitFor(() => expect(release).toHaveBeenCalledTimes(1)); + unmount(root); + }); + + it("resumes a playing preview from where the still was taken", async () => { + const { getApi, root } = await reloadWithStill(async () => () => {}, { playing: true }); + const gen = getApi().previewSlots[0]!.gen; + const { adapter, win } = makeAdapterWindow(); + adapter.getDuration = vi.fn(() => 10); + adapter.seek = vi.fn(adapter.seek); + adapter.play = vi.fn(adapter.play); + act(() => { + getApi().setShadowIframeNode(makeFakeIframe(win)); + getApi().onShadowIframeLoad(gen); + getApi().onShadowReadyChange(gen, true); + }); + expect(adapter.seek).toHaveBeenCalledWith(3); + expect(adapter.play).toHaveBeenCalled(); + unmount(root); + }); + + it("brings the live page back at its time when the reload gives up, and drops the still once it loads", async () => { + vi.useFakeTimers(); + vi.spyOn(console, "error").mockImplementation(() => {}); + const release = vi.fn(); + const onPreviewReloadFailed = vi.fn(); + const harness = renderTimelinePlayerHarness({ + holdPreviewStill: async () => release, + onPreviewReloadFailed, + }); + const { adapter, win } = makeAdapterWindow(); + adapter.getTime = vi.fn(() => 3); + const live = makeFakeIframe(win); + act(() => { + harness.getApi().iframeRef.current = live; + harness.getApi().onIframeLoad(); + }); + await act(async () => { + harness.getApi().refreshPlayer(); + await Promise.resolve(); + }); + + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS * SHADOW_READY_BUDGETS)); + expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long")); + expect(harness.getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]); + expect(release).not.toHaveBeenCalled(); + + // The live slot mounts again and loads at once, as a cached page does: that load drops the still. + act(() => { + harness.getApi().iframeRef.current = makeFakeIframe(makeAdapterWindow().win); + harness.getApi().onIframeLoad(); + vi.advanceTimersByTime(3_000); + }); + expect(release).toHaveBeenCalledTimes(1); + unmount(harness.root); + }); + + it("drops a still kept for a give-up even if the live page never loads again", async () => { + vi.useFakeTimers(); + vi.spyOn(console, "error").mockImplementation(() => {}); + const release = vi.fn(); + const harness = renderTimelinePlayerHarness({ holdPreviewStill: async () => release }); + act(() => { + harness.getApi().iframeRef.current = makeFakeIframe(makeAdapterWindow().win); + harness.getApi().onIframeLoad(); + }); + await act(async () => { + harness.getApi().refreshPlayer(); + await Promise.resolve(); + }); + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS * SHADOW_READY_BUDGETS)); + expect(release).not.toHaveBeenCalled(); + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS)); + expect(release).toHaveBeenCalledTimes(1); + unmount(harness.root); + }); + + it("drops a still that answers after the composition switched, and starts no reload for the old one", async () => { + let answer: (release: () => void) => void = () => {}; + const release = vi.fn(); + const harness = renderTimelinePlayerHarness({ + holdPreviewStill: () => new Promise((resolve) => (answer = resolve)), + }); + const live = makeFakeIframe(makeAdapterWindow().win); + act(() => { + harness.getApi().iframeRef.current = live; + harness.getApi().onIframeLoad(); + }); + act(() => harness.getApi().refreshPlayer()); + act(() => harness.getApi().resetPreviewSlots()); + await act(async () => { + answer(release); + await Promise.resolve(); + }); + expect(release).toHaveBeenCalledTimes(1); + expect(harness.getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]); + unmount(harness.root); + }); + + it("keeps both pages for a reload when the host has no still to show, and a playing preview plays on", async () => { + const harness = renderTimelinePlayerHarness({ holdPreviewStill: async () => null }); + const { adapter, win } = makeAdapterWindow(); + adapter.play = vi.fn(adapter.play); + act(() => { + harness.getApi().iframeRef.current = makeFakeIframe(win); + harness.getApi().onIframeLoad(); + }); + act(() => usePlayerStore.getState().setIsPlaying(true)); + await act(async () => { + harness.getApi().refreshPlayer(); + await Promise.resolve(); + }); + expect(harness.getApi().previewSlots.map((slot) => slot.role)).toEqual(["live", "shadow"]); + expect(adapter.play).toHaveBeenCalled(); + unmount(harness.root); + }); + + it("a host that throws while taking the still keeps both pages and a playing preview plays on", async () => { + const harness = renderTimelinePlayerHarness({ + holdPreviewStill: () => { + throw new Error("capture unavailable"); + }, + }); + const { adapter, win } = makeAdapterWindow(); + adapter.play = vi.fn(adapter.play); + act(() => { + harness.getApi().iframeRef.current = makeFakeIframe(win); + harness.getApi().onIframeLoad(); + }); + act(() => usePlayerStore.getState().setIsPlaying(true)); + await act(async () => { + expect(() => harness.getApi().refreshPlayer()).not.toThrow(); + await Promise.resolve(); + await Promise.resolve(); + }); + expect(harness.getApi().previewSlots.map((slot) => slot.role)).toEqual(["live", "shadow"]); + expect(adapter.play).toHaveBeenCalled(); + unmount(harness.root); + }); + + it("pauses a playing preview before the still is taken, so the reload resumes from the frame it shows", async () => { + const order: string[] = []; + const harness = renderTimelinePlayerHarness({ + holdPreviewStill: async () => { + order.push("still"); + return () => {}; + }, + }); + const { adapter, win } = makeAdapterWindow(); + act(() => { + harness.getApi().iframeRef.current = makeFakeIframe(win); + harness.getApi().onIframeLoad(); + }); + act(() => usePlayerStore.getState().setIsPlaying(true)); + adapter.pause = vi.fn(() => void order.push("pause")); + await act(async () => { + harness.getApi().refreshPlayer(); + await Promise.resolve(); + }); + expect(order).toEqual(["pause", "still"]); + unmount(harness.root); + }); +}); diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.ts b/packages/studio/src/player/hooks/useTimelinePlayer.ts index aea248d14c..f4e43564ed 100644 --- a/packages/studio/src/player/hooks/useTimelinePlayer.ts +++ b/packages/studio/src/player/hooks/useTimelinePlayer.ts @@ -51,6 +51,7 @@ export interface UseTimelinePlayerOptions { onShadowPromoted?: () => void; /** A reload was abandoned (cause in the message); the previous preview is still showing. */ onPreviewReloadFailed?: (message: string) => void; + holdPreviewStill?: (live: HTMLIFrameElement) => Promise<(() => void) | null>; } const publishSeek = (time: number, options?: { follow?: boolean }) => @@ -60,6 +61,7 @@ const publishSeek = (time: number, options?: { follow?: boolean }) => export function useTimelinePlayer({ onShadowPromoted, onPreviewReloadFailed, + holdPreviewStill, }: UseTimelinePlayerOptions = {}) { const iframeRef = useRef(null); const rafRef = useRef(0); @@ -420,6 +422,7 @@ export function useTimelinePlayer({ beginShadowReload, resetPreviewSlots, previewGeneration, + onLiveLoaded, } = useShadowPreviewReload({ iframeRef, getAdapter, @@ -434,6 +437,7 @@ export function useTimelinePlayer({ applyPreviewAudioState, onPromoted: onShadowPromoted, onReloadFailed: onPreviewReloadFailed, + holdStill: holdPreviewStill, handOverPlayback: (time, playing) => { // keepPlaying: move the playhead without the paused-seek audio scrub. seek(time, { keepPlaying: true, follow: false }); @@ -566,13 +570,21 @@ export function useTimelinePlayer({ }); }, [applyPlaybackRate, applyPreviewAudioState]); + const onLiveIframeLoad = useCallback( + (context?: number) => { + onIframeLoad(context); + onLiveLoaded(); + }, + [onIframeLoad, onLiveLoaded], + ); + return { iframeRef, play, pause, togglePlay, seek, - onIframeLoad, + onIframeLoad: onLiveIframeLoad, refreshPlayer, saveSeekPosition, resetPlayer, diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts index 1157007b67..7361641288 100644 --- a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts +++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts @@ -111,6 +111,10 @@ export function planShadowReload( return live ? [live, { gen: nextGen, role: "shadow", url }] : [{ gen: nextGen, role: "live" }]; } +export function planShadowAlone(nextGen: number, url: string): PreviewIframeSlot[] { + return [{ gen: nextGen, role: "shadow", url }]; +} + /** Drop any pending shadow; the live slot (and its key) is untouched. */ export function planShadowDiscard(slots: PreviewIframeSlot[]): PreviewIframeSlot[] { return slots.filter((slot) => slot.role === "live");