import { createRuntimeStartTimeResolver } from "./runtime/startResolver.js"; import { isRuntimeElementVisibleAt } from "./runtime/timeline.js"; import type { RuntimeTimelineLike } from "./runtime/types.js"; import { defersMediaIn } from "./studioPreviewMark.js"; /** A composition is "ready" once every declared input settles, not just once * its duration is known. Each input returns null (nothing to wait on) or a * promise that resolves once it settles, and must stop its own pending work * (timer, rAF, listener) once `signal` aborts — settleCompositionReadiness * aborts it the moment the race settles, win or timeout. */ export type CompositionReadinessInput = ( doc: Document, signal: AbortSignal, ) => Promise | null; export interface PendingCompositionAssets { pendingMedia: HTMLMediaElement[]; pendingImages: HTMLImageElement[]; fontsLoading: boolean; } export type CompositionReadinessScope = "all" | "first-frame"; export const FIRST_FRAME_READINESS_SCOPE: CompositionReadinessScope = "first-frame"; export interface CompositionReadinessOptions { scope?: CompositionReadinessScope; } // HTMLMediaElement.HAVE_FUTURE_DATA per spec, used as a literal because not // every DOM implementation defines the named static (e.g. happy-dom leaves // it undefined). const HAVE_FUTURE_DATA = 3; // `doc` is a foreign (same-origin) iframe document, so its elements belong to // that iframe's own realm — instanceof checks against this window's globals // would silently reject every one of them. Resolve the class from the node's // own defaultView first. export function isRealmElement(node: Node): node is Element { const view = node.ownerDocument?.defaultView; if (view && node instanceof view.Element) return true; return node instanceof Element; } export function isRealmHtmlMediaElement(node: Node): node is HTMLMediaElement { if (!isRealmElement(node)) return false; if (node.tagName !== "AUDIO" && node.tagName !== "VIDEO") return false; const view = node.ownerDocument?.defaultView; if (view && node instanceof view.HTMLMediaElement) return true; return node instanceof HTMLMediaElement; } function isTimedElement(element: Element): boolean { return element.hasAttribute("data-start") || element.hasAttribute("data-track-index"); } function isActiveAtFirstFrame( element: Element, resolver: ReturnType, timelineRegistry: Record, ): boolean { let current: Element | null = element; while (current) { if (isTimedElement(current)) { if ( !isRuntimeElementVisibleAt(current, { currentTime: 0, compositionDuration: Number.POSITIVE_INFINITY, canonicalFps: 30, timelineRegistry, resolver, }) ) return false; } current = current.parentElement; } return true; } function shouldIncludeAsset( element: Element, scope: CompositionReadinessScope, resolver: ReturnType, timelineRegistry: Record, ): boolean { if (scope === "all") return true; return isActiveAtFirstFrame(element, resolver, timelineRegistry); } /** One DOM pass for every declared-media asset not yet ready. */ export function scanPendingCompositionAssets( doc: Document, { scope = "all" }: CompositionReadinessOptions = {}, ): PendingCompositionAssets { const runtimeWindow = doc.defaultView as | (Window & { __timelines?: Record; }) | null; const resolver = createRuntimeStartTimeResolver({ documentRef: doc, timelineRegistry: runtimeWindow?.__timelines, includeAuthoredTimingAttrs: true, }); // Studio's preview and the player buffer a clip off the first frame only once it comes due, as with a lazy image. const defersMedia = defersMediaIn(doc); const pendingMedia = Array.from(doc.querySelectorAll("video, audio")) .filter(isRealmHtmlMediaElement) .filter((el) => shouldIncludeAsset( el, defersMedia && el.preload !== "auto" ? FIRST_FRAME_READINESS_SCOPE : scope, resolver, runtimeWindow?.__timelines ?? {}, ), ) .filter((el) => el.readyState < HAVE_FUTURE_DATA); // A lazy image off the first frame loads only once shown, so no scope can wait on it. const pendingImages = Array.from(doc.querySelectorAll("img")) .filter((img) => shouldIncludeAsset( img, img.getAttribute("loading")?.toLowerCase() === "lazy" ? FIRST_FRAME_READINESS_SCOPE : scope, resolver, runtimeWindow?.__timelines ?? {}, ), ) .filter((img) => !img.complete); const fontsLoading = doc.fonts?.status === "loading"; return { pendingMedia, pendingImages, fontsLoading }; } function collectPendingCompositionAssets( doc: Document, { pendingMedia, pendingImages, fontsLoading }: PendingCompositionAssets, signal: AbortSignal, ): Promise { const mediaReady = pendingMedia.map( (el) => new Promise((resolve) => { // init.ts's eager preload pass may have already errored this element // before this input ran; a DOM error event doesn't refire, so a // listener attached now would wait for the shared 8s timeout instead. if (el.error) { resolve(); return; } const onSettled = () => { el.removeEventListener("canplay", onSettled); el.removeEventListener("error", onSettled); signal.removeEventListener("abort", onSettled); resolve(); }; el.addEventListener("canplay", onSettled); el.addEventListener("error", onSettled); signal.addEventListener("abort", onSettled, { once: true }); }), ); const imagesReady = pendingImages.map((img) => img.decode ? img.decode().catch(() => {}) : Promise.resolve(), ); const fontsReady = fontsLoading && doc.fonts ? doc.fonts.ready.then(() => {}) : Promise.resolve(); return Promise.all([...mediaReady, ...imagesReady, fontsReady]).then(() => {}); } /** Declared-media readiness input: waits on the composition's own video, * audio, image and font-face loads. */ export function mediaReadinessInput( doc: Document, signal: AbortSignal, { scope = "all" }: CompositionReadinessOptions = {}, ): Promise | null { const scan = scanPendingCompositionAssets(doc, { scope }); if (scan.pendingMedia.length === 0 && scan.pendingImages.length === 0 && !scan.fontsLoading) { return null; } return collectPendingCompositionAssets(doc, scan, signal); } const RENDER_READY_POLL_MS = 50; // `window.__renderReady` is declared globally in runtime/window.d.ts, but that // file lives under src/runtime — excluded from this package's own build // program (see tsconfig.json) — so it isn't visible here. Same flag, declared // locally instead of depending on a global merge from outside this file's scope. // `__hf` is omitted from Window so the runtime program's strict shape can't conflict with `unknown`. interface RuntimeReadinessWindow extends Omit { __renderReady?: boolean; // __renderReady is only ever set by init.ts, which always sets __hf // first (`window.__hf = window.__hf || {}`) — a doc with no __hf can // never get __renderReady either, so this alone is enough to gate on // (unlike composition-probe.ts's hasRuntime, this doesn't need __player too). __hf?: unknown; } /** Declared-compute readiness input: waits on `window.__renderReady`. A * probe-only composition (no HyperFrames runtime injected) never sets * it — __hf absent means nothing to wait on, not an 8s poll for a flag * that was never going to flip. */ export function computeReadinessInput(doc: Document, signal: AbortSignal): Promise | null { const win = doc.defaultView as RuntimeReadinessWindow | null; if (!win) return null; if (win.__renderReady) return null; if (!win.__hf) return null; return new Promise((resolve) => { let timeoutId: ReturnType | undefined; const finish = () => { if (timeoutId !== undefined) clearTimeout(timeoutId); signal.removeEventListener("abort", finish); resolve(); }; if (signal.aborted) { finish(); return; } signal.addEventListener("abort", finish, { once: true }); const poll = () => { if (win.__renderReady) { finish(); return; } timeoutId = setTimeout(poll, RENDER_READY_POLL_MS); }; poll(); }); } // Gaps under this bound count as quiet on any document. const IDLE_FRAME_GAP_MS = 50; // Ordinary frame jitter can span 1.5x the document's shortest observed gap. const IDLE_FRAME_GAP_RATIO = 1.5; // Two consecutive quiet frames, not one: a single fast gap can follow // directly after the busy work finishes mid-frame and says nothing about // whether the next frame is also free. const IDLE_FRAMES_REQUIRED = 2; // Bounds continuing stalls. A backgrounded document with no frames still // rides the shared timeout; this budget only bounds frames that arrive. // ponytail: 1500ms is unmeasured; retune with frame traces. const MAX_PAINT_WAIT_MS = 1_500; // Resolves with -1 on abort instead of rejecting: every caller already // re-checks `signal.aborted` right after awaiting this, so a sentinel value // is enough and keeps the abort path a plain early-return, not a try/catch. function nextAnimationFrame(win: Window, signal: AbortSignal): Promise { return new Promise((resolve) => { if (signal.aborted) { resolve(-1); return; } let id = 0; const onAbort = () => { win.cancelAnimationFrame?.(id); resolve(-1); }; signal.addEventListener("abort", onAbort, { once: true }); // A host whose rAF calls back synchronously reaches onAbort in the // callback, so it must already be declared above. id = win.requestAnimationFrame((ts) => { signal.removeEventListener("abort", onAbort); resolve(ts); }); }); } /** Composition-agnostic readiness input: waits for a frame to paint, then * two consecutive quiet frame gaps — an early-out once the main thread is * free relative to its own frame cadence. See MAX_PAINT_WAIT_MS for * what this bound does and does not cover. Compute and media inputs own completion. */ export function paintAndIdleReadinessInput( doc: Document, signal: AbortSignal, ): Promise | null { const win = doc.defaultView; if (!win) return null; return (async () => { const firstTs = await nextAnimationFrame(win, signal); if (signal.aborted) return; let lastTs = await nextAnimationFrame(win, signal); let shortestGap = lastTs - firstTs; let quietStreak = 0; while (!signal.aborted && quietStreak < IDLE_FRAMES_REQUIRED) { if (lastTs - firstTs >= MAX_PAINT_WAIT_MS) return; const ts = await nextAnimationFrame(win, signal); if (signal.aborted) return; const gap = ts - lastTs; shortestGap = Math.min(shortestGap, gap); const quiet = gap < IDLE_FRAME_GAP_MS || gap <= shortestGap * IDLE_FRAME_GAP_RATIO; quietStreak = quiet ? quietStreak + 1 : 0; lastTs = ts; } })(); } const DEFAULT_TIMEOUT_MS = 8_000; export interface CompositionReadinessResult { timedOut: boolean; } /** Invokes `onSettled` once every input settles, or the timeout elapses. * Calls back synchronously, before returning, when nothing is pending — a * caller that plays right after this call sees the decision already * applied, same as before this gate existed. With the default inputs this * only happens for a document with no `defaultView`, since * paintAndIdleReadinessInput always has a frame to wait on otherwise. */ export function settleCompositionReadiness( doc: Document, onSettled: (result: CompositionReadinessResult) => void, opts: CompositionReadinessOptions & { inputs?: CompositionReadinessInput[]; timeoutMs?: number; } = {}, ): void { const inputs = opts.inputs ?? [ (inputDoc, signal) => mediaReadinessInput(inputDoc, signal, { scope: opts.scope }), computeReadinessInput, paintAndIdleReadinessInput, ]; const controller = new AbortController(); const pending = inputs .map((input) => input(doc, controller.signal)) .filter((p): p is Promise => p !== null); if (pending.length === 0) { onSettled({ timedOut: false }); return; } const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS; let timeoutId: ReturnType; const timeout = new Promise<"timed-out">((resolve) => { timeoutId = setTimeout(() => resolve("timed-out"), timeoutMs); }); // A timeout win leaves the losing inputs' promises pending forever unless // told to stop: this abort is what lets computeReadinessInput clear its // poll timer and paintAndIdleReadinessInput cancel its rAF chain instead // of running for the life of the page. Promise.race([Promise.all(pending).then(() => "done" as const), timeout]).then((result) => { clearTimeout(timeoutId); controller.abort(); onSettled({ timedOut: result === "timed-out" }); }); } export function settleFirstFrameCompositionReadiness( doc: Document, onSettled: (result: CompositionReadinessResult) => void, opts: Omit< CompositionReadinessOptions & { inputs?: CompositionReadinessInput[]; timeoutMs?: number; }, "scope" > = {}, ): void { settleCompositionReadiness(doc, onSettled, { ...opts, scope: FIRST_FRAME_READINESS_SCOPE, }); }