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
This commit is contained in:
Miguel Ángel
2026-11-16 05:21:00 +00:00
committed by GitHub
parent d42bbd67f4
commit dab8dc8070
4 changed files with 389 additions and 15 deletions
@@ -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<void> | 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<HTMLIFrameElement | null>(null);
const shadowProbeIntervalRef = useRef<ReturnType<typeof setInterval> | 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<PreviewIframeSlot[]>([{ gen: 0, role: "live" }]);
const slotsRef = useRef(previewSlots);
slotsRef.current = previewSlots;
const holdStillRef = useRef(holdStill);
holdStillRef.current = holdStill;
const heldRef = useRef<HeldStill | null>(null);
// The newest reload asked for while a still is being taken; it starts once the still is up.
const holdingUrlRef = useRef<string | null>(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,
};
}
@@ -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<typeof import("../../utils/gsapSoftReload")>()),
ensureMotionPathPluginLoaded: vi.fn(),
}));
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
document.body.innerHTML = "";
resetPlayerStore();
});
const unmount = (root: ReturnType<typeof createRoot>) => 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);
});
});
@@ -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<HTMLIFrameElement | null>(null);
const rafRef = useRef<number>(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,
@@ -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");