fix(studio): a sealed preview shows its loading overlay while media still loads (#8184)

* test(studio): a sealed preview keeps its loading overlay while media buffers

* fix(studio): a sealed preview's loading overlay waits for its media through the editing port

* fix(studio): Studio never calls a preview ready before its asset check has answered

* refactor(studio): the preview asset wait lives outside the Player component

* refactor(studio): the preview asset wait moves to its own file, out of the Player

* refactor(studio): one asset-wait state; a sealed frame's first check is its own value

* fix(studio): a sealed preview's missing asset answer is asked again, never taken as ready

* fix(studio): a closed preview frees its editing-port client

* style(studio): keep the client comment under the line limit
This commit is contained in:
Miguel Ángel
2026-11-18 22:57:06 +00:00
committed by GitHub
parent 8ace95ce94
commit 81f89b8150
11 changed files with 263 additions and 85 deletions
+20
View File
@@ -13,3 +13,23 @@ export function isLottieAnimationLoaded(anim: unknown): boolean {
if (typeof maybe.totalFrames === "number" && maybe.totalFrames > 0) return true;
return false;
}
const MEDIA_HAVE_FUTURE_DATA = 3;
const MEDIA_NETWORK_NO_SOURCE = 3;
/** Whether a preview still waits on a `<video>`/`<audio>` that cannot play through, or a Lottie still loading. */
export function previewAssetsUnloaded(
doc: Document,
lotties: readonly unknown[] | undefined,
): boolean {
for (const el of doc.querySelectorAll("video, audio")) {
const media = el as HTMLMediaElement;
if (
!media.error &&
media.networkState !== MEDIA_NETWORK_NO_SOURCE &&
media.readyState < MEDIA_HAVE_FUTURE_DATA
)
return true;
}
return (lotties ?? []).some((anim) => !isLottieAnimationLoaded(anim));
}
@@ -203,6 +203,7 @@ describe("installEditingAgent", () => {
"gsap-set",
"patch-tweens",
"soft-reload",
"assets-unloaded",
],
},
});
@@ -42,6 +42,7 @@ import { cropLift } from "./editing/cropLift";
import { gsapSet } from "./editing/gsapSet";
import { patchTweens } from "./editing/patchTween";
import { softReload } from "./editing/softReload";
import { previewAssetsUnloaded } from "../lottieReadiness";
import {
getLogicalOpacity,
markedForStudio,
@@ -226,6 +227,7 @@ const HANDLERS: Handlers = {
"gsap-set": gsapSet,
"patch-tweens": patchTweens,
"soft-reload": softReload,
"assets-unloaded": () => ({ unloaded: previewAssetsUnloaded(document, window.__hfLottie) }),
};
function serve(port: MessagePort): void {
@@ -106,6 +106,7 @@ describe("createEditingPortClient", () => {
"gsap-set",
"patch-tweens",
"soft-reload",
"assets-unloaded",
],
});
} finally {
+3
View File
@@ -186,6 +186,7 @@ export const EDITING_REQUEST_KINDS = [
"gsap-set",
"patch-tweens",
"soft-reload",
"assets-unloaded",
] as const;
export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number];
@@ -323,6 +324,7 @@ export interface EditingRequests {
"gsap-set": { params: GsapSetParams; result: { applied: boolean } };
"patch-tweens": { params: PatchTweensParams; result: { patched: boolean } };
"soft-reload": { params: SoftReloadParams; result: { result: SoftReloadResult } };
"assets-unloaded": { params: NoParams; result: { unloaded: boolean } };
}
export type EditingParams<K extends EditingRequestKind> = EditingRequests[K]["params"];
export type EditingResult<K extends EditingRequestKind> = EditingRequests[K]["result"];
@@ -534,6 +536,7 @@ const PARAM_PARSERS: {
"gsap-set": parseGsapSet,
"patch-tweens": parsePatchTweens,
"soft-reload": parseSoftReload,
"assets-unloaded": noParams,
};
/** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */
@@ -0,0 +1,31 @@
// @vitest-environment happy-dom
import { afterEach, expect, it } from "vitest";
import { sealedPreviewFrame } from "../lib/sealedPreviewFrame.test-helpers";
import { previewAssetsUnloaded } from "../lib/previewChannel";
afterEach(() => {
document.body.innerHTML = "";
});
function bufferingAudio(): HTMLAudioElement {
const audio = document.createElement("audio");
Object.defineProperty(audio, "readyState", { value: 0, configurable: true });
Object.defineProperty(audio, "networkState", { value: 2, configurable: true });
document.body.append(audio);
return audio;
}
// fails without the fix: a sealed frame's document could not be read, so its buffering media counted as loaded.
it("keeps a sealed preview loading while its media still buffers", async () => {
bufferingAudio();
expect(await previewAssetsUnloaded(sealedPreviewFrame().iframe)).toBe(true);
});
it("lets a sealed preview go once its media can play through", async () => {
const audio = bufferingAudio();
Object.defineProperty(audio, "readyState", { value: 4, configurable: true });
expect(await previewAssetsUnloaded(sealedPreviewFrame().iframe)).toBe(false);
});
@@ -3,12 +3,9 @@
import { act, createElement } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
hasUnloadedAssets,
Player,
readPreviewErrorMessage,
shouldShowCompositionLoadingOverlay,
} from "./Player";
import { Player, readPreviewErrorMessage, shouldShowCompositionLoadingOverlay } from "./Player";
import { hasUnloadedAssets } from "./previewAssetWait";
import { previewEditingClient } from "../lib/previewChannel";
import { usePlayerStore } from "../store/playerStore";
import { onPreviewDocumentLoaded } from "../sceneSwap";
@@ -131,6 +128,26 @@ describe("preview errors", () => {
root = null;
});
// fails without the fix: a frame whose agent never answered kept its client, and its window listener held the
// retired frame, until a load that never comes.
it("disposes the frame's editing-port client when it unmounts", async () => {
const ref = vi.fn();
await mountPlayer({ ref } as Partial<PlayerProps>);
const client = previewEditingClient(ref.mock.calls[0]?.[0] as HTMLIFrameElement);
act(() => root?.unmount());
root = null;
const outcome = await Promise.race([
client.request("assets-unloaded", {}).then(
() => "answered",
(error: { code?: string }) => error.code,
),
new Promise((resolve) => setTimeout(() => resolve("pending"), 50)),
]);
expect(outcome).toBe("disposed");
});
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();
@@ -1,6 +1,5 @@
import { buildProjectApiPath } from "../../utils/projectRouting";
import { forwardRef, useEffect, useRef, useState } from "react";
import { isLottieAnimationLoaded } from "@hyperframes/core/runtime/lottie-readiness";
import { installAcceleratedCanvasTracker } from "@hyperframes/core/page-motion-blur";
import { useMountEffect } from "../../hooks/useMountEffect";
import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
@@ -10,6 +9,8 @@ import { announcePreviewDocumentLoaded } from "../sceneSwap";
import type { IframeWindow } from "../lib/playbackTypes";
import { watchPreviewFrame } from "../lib/bridgePlayback";
import { previewUnderFrameToken } from "../lib/frameToken";
import { retirePreviewEditingClient } from "../lib/previewChannel";
import { type AssetWaitState, waitForPreviewAssets } from "./previewAssetWait";
// Importing "@hyperframes/player" registers a class extending HTMLElement at
// module load, which throws under SSR, hence the dynamic import behind a
// `typeof window` guard. Kicking it here rather than in the mount effect puts
@@ -53,9 +54,6 @@ interface HyperframesPlayerElement extends HTMLElement {
painted?: boolean;
}
const MEDIA_HAVE_FUTURE_DATA = 3;
const MEDIA_NETWORK_NO_SOURCE = 3;
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
@@ -98,49 +96,6 @@ function enableInteractiveIframe(player: HyperframesPlayerElement): void {
const studioDraws = (wait: boolean, loadingUi: PlayerProps["loadingUi"]) =>
wait && loadingUi !== "host";
function isPreviewMediaElement(el: Element): el is HTMLMediaElement {
const tagName = el.tagName.toLowerCase();
return tagName === "video" || tagName === "audio";
}
// Assets are considered ready when every `<video>`/`<audio>` has enough data
// to play through without buffering, and every registered Lottie animation has
// finished loading.
//
// Returns whichever value was returned last on cross-origin / transient DOM
// races so a brief access failure (e.g. an iframe that just swapped src)
// doesn't flicker the overlay state — we keep showing whatever was most
// recently true.
export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
try {
const win = iframe.contentWindow as unknown as (Window & { __hfLottie?: unknown[] }) | null;
const doc = iframe.contentDocument;
if (!win || !doc) return lastResult;
for (const el of doc.querySelectorAll("video, audio")) {
if (
isPreviewMediaElement(el) &&
!el.error &&
el.networkState !== MEDIA_NETWORK_NO_SOURCE &&
el.readyState < MEDIA_HAVE_FUTURE_DATA
) {
return true;
}
}
const lotties = win.__hfLottie;
if (lotties?.length) {
for (const anim of lotties) {
if (!isLottieAnimationLoaded(anim)) return true;
}
}
return false;
} catch {
return lastResult;
}
}
async function playerSrc(previewSource: string, opaque: boolean): Promise<string> {
const url = new URL(previewSource, window.location.origin);
applyPreviewVariablesToUrl(url);
@@ -194,7 +149,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
const onPreviewErrorRef = useRef(onPreviewError);
onPreviewErrorRef.current = onPreviewError;
const [loaded, setLoaded] = useState(false);
const [assetsLoading, setAssetsLoading] = useState(false);
const [assetsLoading, setAssetsLoading] = useState<AssetWaitState>(false);
const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
const [assetOverlayFading, setAssetOverlayFading] = useState(false);
const [assetWaitLong, setAssetWaitLong] = useState(false);
@@ -307,28 +262,14 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
// cold video or a broken asset can legitimately exceed 10 s on a
// slow network.
if (assetPollRef.current) clearInterval(assetPollRef.current);
const isContentRefresh = loadCountRef.current > 1;
let lastUnloaded = isContentRefresh ? false : hasUnloadedAssets(iframe, false);
if (lastUnloaded) {
setAssetsLoading(true);
let attempts = 0;
assetPollRef.current = setInterval(() => {
attempts += 1;
lastUnloaded = hasUnloadedAssets(iframe, lastUnloaded);
if (!lastUnloaded || attempts > 100) {
if (lastUnloaded && attempts > 100) {
console.debug(
"[studio] asset readiness poll hit the 10s cap, continuing with unloaded assets",
);
}
if (assetPollRef.current) clearInterval(assetPollRef.current);
assetPollRef.current = null;
setAssetsLoading(false);
}
}, 100);
} else {
setAssetsLoading(false);
}
assetPollRef.current = null;
const load = loadCountRef.current;
waitForPreviewAssets(iframe, {
refresh: load > 1,
pollRef: assetPollRef,
isCurrent: () => loadCountRef.current === load,
setLoading: setAssetsLoading,
});
};
// Attach lifecycle listeners before assigning src or connecting the
@@ -376,6 +317,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
player.removeEventListener("error", handleError);
if (assetPollRef.current) clearInterval(assetPollRef.current);
assetPollRef.current = null;
retirePreviewEditingClient(iframe);
// `remove()` rather than `container.removeChild(player)`: by the time
// this cleanup runs the element may already be detached — React can
// re-render the container, a crossfade refresh can swap it, or a
@@ -411,7 +353,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
// Surface a "Continue anyway" escape hatch once the asset wait drags on.
// eslint-disable-next-line no-restricted-syntax
useEffect(() => {
if (!assetsLoading) {
if (assetsLoading !== true) {
setAssetWaitLong(false);
return;
}
@@ -425,7 +367,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
assetFadeRef.current = null;
}
if (assetsLoading) {
if (assetsLoading === true) {
setAssetOverlayVisible(true);
setAssetOverlayFading(false);
return;
@@ -0,0 +1,71 @@
// @vitest-environment happy-dom
import { afterEach, beforeEach, expect, it, vi } from "vitest";
type Answer = boolean | null | Promise<boolean | null>;
const channel = vi.hoisted(() => ({ answers: [] as Answer[], asked: 0 }));
vi.mock("../lib/previewChannel", () => ({
previewFrameOpaque: () => true,
previewAssetsUnloaded: () => {
channel.asked += 1;
return Promise.resolve(channel.answers.shift() ?? null);
},
}));
import { type AssetWaitState, waitForPreviewAssets } from "./previewAssetWait";
function startSealedWait() {
const states: AssetWaitState[] = [];
const pollRef: { current: ReturnType<typeof setInterval> | null } = { current: null };
waitForPreviewAssets(document.createElement("iframe"), {
refresh: false,
pollRef,
isCurrent: () => true,
setLoading: (state) => states.push(state),
});
return { states, pollRef };
}
beforeEach(() => {
vi.useFakeTimers();
channel.answers = [];
channel.asked = 0;
});
afterEach(() => {
vi.useRealTimers();
});
// fails without the fix: a sealed frame's missing first answer (a port the load replaced) was taken as ready.
it("asks a sealed frame again when its first answer is missing, and is not ready meanwhile", async () => {
channel.answers = [null, true];
const { states } = startSealedWait();
await vi.advanceTimersByTimeAsync(250);
expect(states).toEqual(["checking", true]);
});
it("counts a sealed frame's first answer inside the 10 s cap", async () => {
channel.answers = [new Promise<null>(() => {})];
const { states } = startSealedWait();
await vi.advanceTimersByTimeAsync(10_200);
expect(states.at(-1)).toBe(false);
});
it("asks nothing more once the wait is torn down during the first request", async () => {
let answer: (unloaded: boolean) => void = () => {};
channel.answers = [new Promise<boolean>((resolve) => (answer = resolve))];
const { states, pollRef } = startSealedWait();
clearInterval(pollRef.current ?? undefined);
pollRef.current = null;
answer(true);
await vi.advanceTimersByTimeAsync(1_000);
expect(channel.asked).toBe(1);
expect(states).toEqual(["checking"]);
});
@@ -0,0 +1,80 @@
import { previewAssetsUnloaded } from "@hyperframes/core/runtime/lottie-readiness";
import {
previewAssetsUnloaded as askAssetsUnloaded,
previewFrameOpaque,
} from "../lib/previewChannel";
// Returns whichever value was returned last on cross-origin / transient DOM
// races so a brief access failure (e.g. an iframe that just swapped src)
// doesn't flicker the overlay state — we keep showing whatever was most
// recently true.
export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
try {
const win = iframe.contentWindow as unknown as (Window & { __hfLottie?: unknown[] }) | null;
const doc = iframe.contentDocument;
if (!win || !doc) return lastResult;
return previewAssetsUnloaded(doc, win.__hfLottie);
} catch {
return lastResult;
}
}
/** "checking": not ready yet, but no overlay, until a sealed frame first answers. */
export type AssetWaitState = boolean | "checking";
interface AssetWait {
refresh: boolean;
pollRef: { current: ReturnType<typeof setInterval> | null };
isCurrent: () => boolean;
setLoading: (state: AssetWaitState) => void;
}
const POLL_MS = 100;
const MAX_POLLS = 100;
/** Keeps the asset overlay up while the preview's media cannot play through, for at most 10 s. A sealed frame that
* gives no answer (its port not up yet, or replaced by the load) is asked again, never taken as ready. */
export function waitForPreviewAssets(iframe: HTMLIFrameElement, wait: AssetWait): void {
if (wait.refresh) {
wait.setLoading(false);
return;
}
const sealed = previewFrameOpaque(iframe);
let state: AssetWaitState = sealed ? "checking" : hasUnloadedAssets(iframe, false);
wait.setLoading(state);
if (state === false) return;
let polls = 0;
let asking = false;
const handle = setInterval(() => tick(), POLL_MS);
wait.pollRef.current = handle;
const live = () => wait.pollRef.current === handle && wait.isCurrent();
const stop = () => {
clearInterval(handle);
wait.pollRef.current = null;
wait.setLoading(false);
};
const ask = async (): Promise<boolean | null> =>
sealed ? askAssetsUnloaded(iframe) : hasUnloadedAssets(iframe, state === true);
const tick = () => {
if (!live()) return clearInterval(handle);
polls += 1;
if (polls > MAX_POLLS) {
console.debug(
"[studio] asset readiness poll hit the 10s cap, continuing with unloaded assets",
);
return stop();
}
if (asking) return;
asking = true;
void ask().then((unloaded) => {
asking = false;
if (!live() || unloaded === null) return;
if (!unloaded) return stop();
if (state === true) return;
state = true;
wait.setLoading(true);
});
};
if (sealed) tick();
}
@@ -8,7 +8,7 @@ import {
} from "@hyperframes/core/runtime/editing-port";
import type { ClipManifest, IframeWindow } from "./playbackTypes";
const clients = new WeakMap<HTMLIFrameElement, EditingPortClient>();
const clients = new WeakMap<HTMLIFrameElement, { client: EditingPortClient; retire: () => void }>();
const loopStarts = new WeakMap<EditingPortClient, number | null>();
/** A frame whose window refuses Studio's reads; one with no window has nothing to reach either way. */
@@ -23,20 +23,25 @@ export function previewFrameOpaque(iframe: HTMLIFrameElement): boolean {
}
}
/** One client per frame load: the frame's next load disposes it. */
/** One client per frame load: its next load disposes it, or `retirePreviewEditingClient` when the frame goes. */
export function previewEditingClient(iframe: HTMLIFrameElement): EditingPortClient {
const open = clients.get(iframe);
if (open) return open;
if (open) return open.client;
const client = createEditingPortClient({ iframe });
clients.set(iframe, client);
const onLoad = () => {
const retire = () => {
iframe.removeEventListener("load", retire);
client.dispose();
if (clients.get(iframe) === client) clients.delete(iframe);
if (clients.get(iframe)?.client === client) clients.delete(iframe);
};
iframe.addEventListener("load", onLoad, { once: true });
clients.set(iframe, { client, retire });
iframe.addEventListener("load", retire, { once: true });
return client;
}
export function retirePreviewEditingClient(iframe: HTMLIFrameElement): void {
clients.get(iframe)?.retire();
}
export function setFrameLoopStart(iframe: HTMLIFrameElement, seconds: number | null): void {
if (!previewFrameOpaque(iframe)) {
try {
@@ -146,6 +151,11 @@ export async function previewComputedStyles(
return read;
}
export async function previewAssetsUnloaded(iframe: HTMLIFrameElement): Promise<boolean | null> {
const reply = await previewRequest(iframe, "assets-unloaded", {});
return typeof reply?.unloaded === "boolean" ? reply.unloaded : null;
}
export async function previewDocumentCopy(iframe: HTMLIFrameElement): Promise<Document | null> {
const reply = await previewRequest(iframe, "document-markup", {});
if (typeof reply?.html !== "string" || typeof reply.baseURI !== "string") return null;