fix(studio): a preview reload survives its pane unmounting mid-load (#7590)

* fix(studio): a preview reload survives its pane unmounting mid-load

When the preview pane unmounted while a shadow reload was loading, its
Player removed the shadow frame but the reload kept timing it, so the
edit was dropped with "Its page had got to: no-page" and the previous
preview stayed. The reload now pauses while its frame is off the page
and starts its budgets again when the pane mounts a new frame.

The Player's comment on callback refs said the mutable-ref branch was
the only one in use; the shadow reload passes a callback ref, so the
comment now says why those are left alone.

* refactor(studio): name the left-page flag instead of explaining it in comments

* style(studio): format the shadow reattach guard
This commit is contained in:
Miguel Ángel
2026-11-12 07:31:21 +00:00
committed by GitHub
parent 32cacab74b
commit 5a3e46235f
5 changed files with 86 additions and 9 deletions
@@ -129,6 +129,21 @@ describe("preview errors", () => {
root = null;
});
it("leaves a callback ref alone on unmount, so a frame its owner made live since is kept", async () => {
// A shadow reload's promotion makes its frame the live one without calling the live Player's ref.
const ref = vi.fn();
const { player } = await mountPlayer({ ref } as Partial<PlayerProps>);
const frame = ref.mock.calls[0]?.[0] as HTMLIFrameElement;
player.shadowRoot!.append(frame); // where <hyperframes-player> keeps its frame
expect(frame.isConnected).toBe(true);
act(() => root?.unmount());
root = null;
expect(ref).toHaveBeenCalledTimes(1);
expect(frame.isConnected).toBe(false);
});
it("puts the preview on the player's once-a-second paused heartbeat", async () => {
const { player } = await mountPlayer();
expect(player.hasAttribute("low-power-idle")).toBe(true);
@@ -377,11 +377,11 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
// During crossfade refreshes the retiring Player unmounts after the
// new Player has already assigned its iframe to the same ref — blindly
// nulling it would break seeking in the new Player.
// Callback refs are skipped — we can't read back the current value to
// guard against clobbering a newer assignment. The mutable-ref branch
// (the only path used today) is guarded by identity check.
// Callback refs are left alone: a shadow reload's promotion repoints
// the live frame without calling them, so a null here would wipe it.
// Their owners check `isConnected` instead (useShadowPreviewReload).
if (typeof ref === "function") {
// no-op: can't safely guard callback refs
// no-op
} else if (ref) {
const mutableRef = ref as React.MutableRefObject<HTMLIFrameElement | null>;
if (mutableRef.current === iframe) {
@@ -67,6 +67,7 @@ export function makeFakeIframe(iframeWindow: Record<string, unknown>): HTMLIFram
value: document.implementation.createHTMLDocument("preview"),
configurable: true,
});
document.body.appendChild(iframe);
return iframe;
}
@@ -114,6 +114,7 @@ export function useShadowPreviewReload({
const budgetsSpentRef = useRef(0);
// The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible.
const budgetGenRef = useRef<number | null>(null);
const shadowFrameLeftPageRef = useRef(false);
const cancelPendingLoadRef = useRef<() => void>(() => {});
const stopHoldRef = useRef<() => void>(() => {});
const shadowUrlRef = useRef("");
@@ -127,6 +128,7 @@ export function useShadowPreviewReload({
const stopPendingShadow = useCallback(() => {
clearTimeout(readyTimerRef.current);
budgetGenRef.current = null;
shadowFrameLeftPageRef.current = false;
cancelPendingLoadRef.current();
stopHoldRef.current();
pendingCommitRef.current = null;
@@ -296,14 +298,10 @@ export function useShadowPreviewReload({
[promoteWhenReady],
);
const setShadowIframeNode = useCallback((node: HTMLIFrameElement | null) => {
shadowIframeRef.current = node;
}, []);
const armReadyTimer = useCallback(
(gen: number) => {
clearTimeout(readyTimerRef.current);
if (isDocumentHidden()) return;
if (isDocumentHidden() || shadowFrameLeftPageRef.current) return;
let drew = false;
let starved = false;
requestAnimationFrame(() => {
@@ -317,6 +315,12 @@ export function useShadowPreviewReload({
logReload("shadow-starved", { gen });
return;
}
const frame = shadowIframeRef.current;
if (frame && !frame.isConnected) {
shadowFrameLeftPageRef.current = true;
logReload("shadow-detached", { gen });
return;
}
budgetsSpentRef.current += 1;
if (budgetsSpentRef.current < SHADOW_READY_BUDGETS) {
logReload("shadow-slow", { budgetsSpent: budgetsSpentRef.current });
@@ -331,6 +335,17 @@ export function useShadowPreviewReload({
const armReadyTimerRef = useRef(armReadyTimer);
armReadyTimerRef.current = armReadyTimer;
const setShadowIframeNode = useCallback((node: HTMLIFrameElement | null) => {
shadowIframeRef.current = node;
const gen = budgetGenRef.current;
if (!node || !shadowFrameLeftPageRef.current || gen == null || gen !== shadowGenRef.current)
return;
shadowFrameLeftPageRef.current = false;
budgetsSpentRef.current = 0;
logReload("shadow-reattached", { gen });
armReadyTimerRef.current(gen);
}, []);
const beginShadowReload = useCallback(
(url: string) => {
retry.started();
@@ -533,6 +533,52 @@ describe("shadow reload readiness and failure", () => {
unmount(root);
});
it("keeps a reload whose frame left the page, and promotes it once a new frame mounts", () => {
vi.useFakeTimers();
const onPreviewReloadFailed = vi.fn();
const { getApi, gen, live, root } = beginReload({ onPreviewReloadFailed });
const first = makeShadowWithSpies();
act(() => getApi().setShadowIframeNode(first.iframe));
// The pane holding the preview unmounts mid-reload: its Players remove their frames.
act(() => first.iframe.remove());
act(() => void vi.advanceTimersByTime(FULL_WAIT_MS * 2));
expect(onPreviewReloadFailed).not.toHaveBeenCalled();
expect(getApi().iframeRef.current).toBe(live);
// The pane comes back: a new Player for the same slot mounts a new frame, which loads.
const again = makeShadowWithSpies();
act(() => {
getApi().setShadowIframeNode(again.iframe);
getApi().onShadowIframeLoad(gen);
});
act(() => getApi().onShadowReadyChange(gen, true));
expect(getApi().iframeRef.current).toBe(again.iframe);
expect(onPreviewReloadFailed).not.toHaveBeenCalled();
unmount(root);
});
it("gives a frame that mounts again its full budgets, then drops it if it stays silent", () => {
vi.useFakeTimers();
vi.spyOn(console, "error").mockImplementation(() => {});
const onPreviewReloadFailed = vi.fn();
const { getApi, live, root } = beginReload({ onPreviewReloadFailed });
const first = makeShadowWithSpies();
act(() => getApi().setShadowIframeNode(first.iframe));
act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS + 1000));
act(() => first.iframe.remove());
act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
expect(onPreviewReloadFailed).not.toHaveBeenCalled();
act(() => getApi().setShadowIframeNode(makeShadowWithSpies().iframe));
act(() => void vi.advanceTimersByTime(FULL_WAIT_MS - 1));
expect(onPreviewReloadFailed).not.toHaveBeenCalled();
act(() => void vi.advanceTimersByTime(1));
expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
expect(getApi().iframeRef.current).toBe(live);
unmount(root);
});
it("does not spend the budget while the tab is hidden, and promotes once it is visible", () => {
vi.useFakeTimers();
const onPreviewReloadFailed = vi.fn();