Files
hyperframes/packages/cli/src/capture/captureCompositionFrame.ts
T
Miguel Ángel f7b49f1207 fix(core): free a preview clip's decoder when the playhead leaves it (#7679)
* fix(core): free a preview clip's decoder when the playhead leaves it

* fix(core): keep audio buffered when the playhead leaves it, free only video decoders

* fix(core): leave Safari's loaded video alone when the playhead leaves it
2026-11-14 01:54:54 +00:00

915 lines
33 KiB
TypeScript

import { oneProcessOverPipe } from "@hyperframes/engine";
import { SEEK_SETTLES_BEFORE_PROTOCOL_TIMEOUT_MS } from "./captureTimeout.js";
import {
rethrowAfterBrowserCleanup,
launchManagedBrowser,
resolveManagedGpuMode,
} from "../browser/launch.js";
import { spawn } from "node:child_process";
import type { Browser, Page } from "puppeteer-core";
import type { InProcessRequest, InProcessResponse } from "../utils/staticProjectServer.js";
import { c } from "../ui/colors.js";
import {
assertWebGpuAdapterAvailable,
compositionRequiresWebGpu,
resolveLocalBrowserGpuMode,
resolveLocalWebGpu,
type BrowserGpuMode,
} from "../browser/gpuPolicy.js";
import { windowsChromeCrashRemediation } from "../browser/windowsCrash.js";
import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { pageNavigationTimeoutMs } from "../utils/renderArgs.js";
import { gotoWhenSent } from "./navigateForCapture.js";
const SHADER_TRANSITIONS_TIMEOUT_MS = 90_000;
const CAPTURE_SETTLE_MS = 1500;
const NETWORK_IDLE_MS = 100;
const PREFERRED_SEEK_TARGET_WAIT_MS = 500;
const DEFAULT_POST_SEEK_FONT_WAIT_MS = 500;
// The audit-grade seek tuning shared by check and the deprecated inspect/layout:
// bridge+timeline fallback, ordered double-rAF settle, bounded font wait.
export const AUDIT_SEEK_OPTIONS = {
fallbackToBridgeAndTimelines: true,
animationFrameSettle: "double",
waitForFontsMs: 500,
} as const;
export const SCREENSHOT_IMAGE_WAIT_MS = 3_000;
export const SCREENSHOT_SEEK_OPTIONS = {
...AUDIT_SEEK_OPTIONS,
waitForImagesMs: SCREENSHOT_IMAGE_WAIT_MS,
} as const;
export interface UnsettledImages {
pending: string[];
failed: string[];
}
const ALL_IMAGES_SETTLED: UnsettledImages = { pending: [], failed: [] };
// Geometry-only seek for the dense content_overlap grid: getBoundingClientRect is valid synchronously after setTime, so drop all post-seek waits (rAF/font/sleep) that would multiply across the dense grid.
export const DENSE_GEOMETRY_SEEK_OPTIONS = {
...AUDIT_SEEK_OPTIONS,
animationFrameSettle: "none",
waitForFontsMs: 0,
settleMs: 0,
waitForVideoFrames: false,
skipWebglDraws: true,
} as const;
export interface SeekCompositionTimelineOptions {
fallbackToBridgeAndTimelines?: boolean;
exactTime?: boolean;
waitForPreferredSeekTargetMs?: number;
animationFrameSettle?: "race" | "double" | "none";
waitForFontsMs?: number;
settleMs?: number;
waitForImagesMs?: number;
waitForVideoFrames?: boolean;
seekSettleTimeoutMs?: number;
// Box-only reads: software GL spends about a second per frame on draws nothing here looks at.
skipWebglDraws?: boolean;
}
type SeekBarrierOptions = { videoFrames: boolean; timeoutMs: number };
type FontWaitOptions = { ms: number; frames: number };
type CompositionPageFunction =
| string
| (() => unknown)
| ((value: number) => unknown)
| ((barrier: SeekBarrierOptions) => unknown)
| ((wait: FontWaitOptions) => unknown)
| ((
value: number,
fallbackToBridgeAndTimelines: boolean,
exactTime: boolean,
skipWebglDraws: boolean,
) => unknown);
export interface CompositionEvaluationPage {
evaluate(
pageFunction: CompositionPageFunction,
value?: number | SeekBarrierOptions | FontWaitOptions,
fallbackToBridgeAndTimelines?: boolean,
exactTime?: boolean,
skipWebglDraws?: boolean,
): Promise<unknown>;
}
export interface CompositionSeekPage extends CompositionEvaluationPage {
waitForFunction?(pageFunction: () => boolean, options: { timeout: number }): Promise<unknown>;
}
export interface SettledCompositionPage {
browser: Browser;
page: Page;
// True when the runtime never signaled __renderReady within the timeout — the
// capture proceeds anyway (possibly mid-animation), so callers can surface it.
renderReadyTimedOut: boolean;
}
export interface OpenSettledCompositionPageOptions {
// Separate from the post-navigation render-ready budget; can only lengthen render's page-load budget.
navigationTimeoutMs?: number;
renderReadyTimeoutMs: number;
renderReadyWarningSuffix: string;
lateSubresourceTimeoutMs?: number;
browserGpuMode?: BrowserGpuMode;
signal?: AbortSignal;
onBrowser?: (browser: Browser) => void;
// Connected composition browser, before page creation or authored scripts.
onBrowserReady?: () => void;
// Runs after the page exists but before page.goto, so console/pageerror/
// request listeners can attach without missing load-time events.
beforeNavigate?: (page: Page) => void | Promise<void>;
// Runs after navigation and before the render-ready wait.
onLoaded?: (page: Page) => void | Promise<void>;
// Started before the project was bundled; used only if it was launched with the same arguments.
prelaunched?: PrelaunchedBrowser;
}
interface LaunchedBrowser {
browser: Browser;
softwareWebGpu: boolean;
}
export interface PrelaunchedBrowser {
launched: Promise<LaunchedBrowser | undefined>;
take(key: string): Promise<LaunchedBrowser | undefined>;
discard(): Promise<void>;
}
type LaunchOptions = Pick<
OpenSettledCompositionPageOptions,
"browserGpuMode" | "signal" | "onBrowser"
>;
function launchKey(html: string, noListen: boolean, options: LaunchOptions): string {
const viewport = resolveCompositionViewportFromHtml(html);
const gpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
return JSON.stringify([viewport, compositionRequiresWebGpu(html), noListen, gpuMode]);
}
export function prelaunchCompositionBrowser(
html: string,
browserGpuMode?: BrowserGpuMode,
): PrelaunchedBrowser {
const abort = new AbortController();
const options = { browserGpuMode, signal: abort.signal };
const key = launchKey(html, false, options);
const launched = launchCompositionBrowser(html, false, options).catch(() => undefined);
let taken = false;
const discard = async () => {
if (taken) return;
taken = true;
abort.abort();
await (await launched)?.browser.close().catch(() => undefined);
};
return {
launched,
take: async (wanted) => {
if (wanted !== key) return discard().then(() => undefined);
taken = true;
const result = await launched;
if (result?.browser.connected) return result;
await result?.browser.close().catch(() => undefined);
return undefined;
},
discard,
};
}
export interface FfmpegRunResult {
code: number | null;
stderr: string;
timedOut: boolean;
}
export function resolveCliChromeGpuMode(
envMode = process.env.PRODUCER_BROWSER_GPU_MODE,
): BrowserGpuMode {
return resolveLocalBrowserGpuMode(undefined, envMode);
}
function compositionRuntimeReadyInBrowser(): boolean {
return (
Boolean(Reflect.get(window, "__renderReady")) ||
typeof Reflect.get(window, "__hfStartupError") === "string"
);
}
function shaderTransitionsReadyInBrowser(): boolean {
function shaderTransitionRegistryReady(): boolean | undefined {
const hf = Reflect.get(window, "__hf");
if (typeof hf !== "object" || hf === null) return undefined;
const shaderTransitions = Reflect.get(hf, "shaderTransitions");
if (typeof shaderTransitions !== "object" || shaderTransitions === null) return undefined;
for (const key of Object.keys(shaderTransitions)) {
const entry = Reflect.get(shaderTransitions, key);
if (typeof entry !== "object" || entry === null) return false;
if (Reflect.get(entry, "ready") !== true) return false;
}
return true;
}
function shaderLoadingOverlayReady(): boolean {
const overlay = document.querySelector("[data-hyper-shader-loading]");
if (!overlay) return true;
if (!(overlay instanceof HTMLElement)) return true;
return window.getComputedStyle(overlay).display === "none";
}
return shaderTransitionRegistryReady() ?? shaderLoadingOverlayReady();
}
export async function waitForRuntimeReady(
page: Required<Pick<CompositionSeekPage, "waitForFunction" | "evaluate">>,
timeoutMs: number,
): Promise<boolean> {
const settled = await page
.waitForFunction(compositionRuntimeReadyInBrowser, { timeout: timeoutMs })
.then(() => true)
.catch(() => false);
const startupError = await page
.evaluate(() => Reflect.get(window, "__hfStartupError"))
.catch(() => undefined);
if (typeof startupError === "string") throw new Error(startupError);
return settled;
}
async function waitForCompositionSettle(
page: Page,
options: OpenSettledCompositionPageOptions,
): Promise<boolean> {
const runtimeReady = await waitForRuntimeReady(page, options.renderReadyTimeoutMs);
if (!runtimeReady) {
console.warn(
`\n ${c.warn("⚠")} Runtime did not become render-ready within ${options.renderReadyTimeoutMs}ms — ${options.renderReadyWarningSuffix}`,
);
}
await page
.waitForFunction(shaderTransitionsReadyInBrowser, {
timeout: SHADER_TRANSITIONS_TIMEOUT_MS,
})
.catch(() => {
console.warn(` ${c.warn("⚠")} Shader transitions did not finish pre-rendering`);
});
await waitForLateSubresources(page, options.lateSubresourceTimeoutMs ?? CAPTURE_SETTLE_MS);
const { resolveConfig, waitForImagesReady } = await import("@hyperframes/engine");
const imageTimeoutMs = resolveConfig().playerReadyTimeout;
await waitForImagesReady(page, imageTimeoutMs, (sources) =>
console.warn(
` ${c.warn("⚠")} Some images did not load within ${imageTimeoutMs}ms: ${sources}. They may show blank.`,
),
);
return runtimeReady;
}
async function waitForLateSubresources(page: Page, timeoutMs: number): Promise<void> {
let cap: ReturnType<typeof setTimeout> | undefined;
const deadline = Date.now() + timeoutMs;
const ready = (async () => {
await page.waitForFunction(() => document.readyState === "complete", {
timeout: timeoutMs,
});
await page.waitForNetworkIdle({
idleTime: NETWORK_IDLE_MS,
timeout: Math.max(1, deadline - Date.now()),
});
await page.evaluate(async () => {
await Promise.all(Array.from(document.images, (image) => image.decode().catch(() => {})));
await document.fonts.ready;
});
})();
try {
await Promise.race([
ready,
new Promise((resolveCap) => {
cap = setTimeout(resolveCap, timeoutMs);
}),
]);
} catch {
await new Promise((resolveCap) => setTimeout(resolveCap, Math.max(0, deadline - Date.now())));
} finally {
clearTimeout(cap);
ready.catch(() => {});
}
}
// tsx/esbuild-style dev transpilers run with keepNames, which rewrites named
// inner functions in serialized page closures into __name(...) calls — a
// helper that exists in the Node bundle but not in the browser realm, so any
// page.evaluate/waitForFunction whose closure defines a named function throws
// "__name is not defined" when the CLI runs from source. Defining a no-op in
// the page before any script runs immunizes every serialized closure, current
// and future, regardless of how the CLI was built.
export async function installPageFunctionGuard(page: {
evaluateOnNewDocument(source: string): Promise<unknown>;
}): Promise<void> {
await page.evaluateOnNewDocument("self.__name = self.__name || ((fn) => fn);");
}
export async function openSettledCompositionPage(
html: string,
url: string,
options: OpenSettledCompositionPageOptions,
): Promise<SettledCompositionPage> {
const viewport = resolveCompositionViewportFromHtml(html);
const requiresWebGpu = compositionRequiresWebGpu(html);
// Nothing may listen (a sandbox refused it): DevTools over a pipe, one process, pages answered in-process.
const answer = (await import("../utils/staticProjectServer.js")).inProcessAnswer(url);
const noListen = answer !== undefined;
let chromeBrowser: Browser | undefined;
try {
const launched =
(await options.prelaunched?.take(launchKey(html, noListen, options))) ??
(await launchCompositionBrowser(html, noListen, options));
chromeBrowser = launched.browser;
const softwareWebGpu = launched.softwareWebGpu;
options.onBrowser?.(chromeBrowser);
options.onBrowserReady?.();
const page = await chromeBrowser.newPage();
await installPageFunctionGuard(page);
const { installMediaRenderIdBridge, forcePreservedDrawingBuffer } =
await import("@hyperframes/engine");
await installMediaRenderIdBridge(page);
await page.evaluateOnNewDocument(forcePreservedDrawingBuffer);
await page.evaluateOnNewDocument("window.__HF_REPLAY_SKIPPED_FRAMES = true");
await page.setViewport(viewport);
if (answer) await answerPageInProcess(page, url, answer);
await options.beforeNavigate?.(page);
await gotoWhenSent(page, url, pageNavigationTimeoutMs(options.navigationTimeoutMs));
await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
await options.onLoaded?.(page);
const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
return { browser: chromeBrowser, page, renderReadyTimedOut };
} catch (err) {
return rethrowAfterBrowserCleanup(chromeBrowser, err);
}
}
async function launchCompositionBrowser(
html: string,
noListen: boolean,
options: LaunchOptions,
): Promise<LaunchedBrowser> {
const viewport = resolveCompositionViewportFromHtml(html);
const { ensureBrowser, findSystemBrowser } = await import("../browser/manager.js");
const browser = await ensureBrowser({ signal: options.signal });
const puppeteer = await import("puppeteer-core");
const { buildChromeArgs } = await import("@hyperframes/engine");
const requestedGpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
const requiresWebGpu = compositionRequiresWebGpu(html);
let softwareWebGpu = false;
const launch = async (executablePath: string): Promise<Browser> => {
options.signal?.throwIfAborted();
const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath, {
signal: options.signal,
onBrowser: options.onBrowser,
noListen,
});
options.signal?.throwIfAborted();
const webGpu = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);
softwareWebGpu = webGpu.softwareWebGpu;
const args = buildChromeArgs(
{ ...viewport, captureMode: "screenshot", requiresWebGpu },
webGpu.gpuConfig,
);
return launchManagedBrowser(puppeteer.default, {
headless: true,
signal: options.signal,
executablePath,
...(noListen ? oneProcessOverPipe({ args }) : { args }),
});
};
let chromeBrowser: Browser;
try {
chromeBrowser = await launch(browser.executablePath);
} catch (launchError) {
const message = normalizeErrorMessage(launchError);
const remediation = windowsChromeCrashRemediation(message);
if (!remediation) throw launchError;
const systemBrowser =
browser.source === "cache" || browser.source === "download" ? findSystemBrowser() : undefined;
if (!systemBrowser || systemBrowser.executablePath === browser.executablePath) {
throw new Error(`${message}\n\n${remediation}`, { cause: launchError });
}
console.warn(
`[hyperframes] Managed chrome-headless-shell crashed at launch; retrying once with system Chrome at ${systemBrowser.executablePath}.`,
);
try {
chromeBrowser = await launch(systemBrowser.executablePath);
} catch (fallbackError) {
throw new Error(
`System Chrome fallback also failed: ${normalizeErrorMessage(fallbackError)}\n\n${remediation}`,
{ cause: fallbackError },
);
}
}
return { browser: chromeBrowser, softwareWebGpu };
}
// Serialized into the page; the seek-target cascade must stay one function.
// fallow-ignore-next-line complexity
export function seekInPage(
t: number,
fallbackToBridgeAndTimelines: boolean,
exactTime: boolean,
skipDraws: boolean,
): void {
const getProperty = (target: unknown, key: string): unknown => {
if ((typeof target !== "object" || target === null) && typeof target !== "function") {
return undefined;
}
return Reflect.get(target, key);
};
const call = (fn: unknown, receiver: unknown, args: unknown[]): boolean => {
if (typeof fn !== "function") return false;
Reflect.apply(fn, receiver, args);
return true;
};
const player = Reflect.get(window, "__player");
if (!player && !fallbackToBridgeAndTimelines) return;
const safe = Math.max(0, Number(t) || 0);
const renderSeek = getProperty(player, "renderSeek");
const playerSeek = getProperty(player, "seek");
const hf = Reflect.get(window, "__hf");
const bridgeSeek = getProperty(hf, "seek");
const gsap = Reflect.get(window, "gsap");
const ticker = getProperty(gsap, "ticker");
// fallow-ignore-next-line complexity
const seekTo = (time: number): void => {
// Prefer renderSeek because it also runs the runtime's data-start/data-duration
// visibility sync; raw timeline seeks leave off-window clips visible to audits.
if (call(renderSeek, player, exactTime ? [time, { exact: true }] : [time])) {
// Preferred runtime target handled the seek.
} else if (fallbackToBridgeAndTimelines && call(bridgeSeek, hf, [time])) {
// Producer bridge handled the seek.
} else if (call(playerSeek, player, [time])) {
// Legacy player target handled the seek.
} else if (fallbackToBridgeAndTimelines) {
const timelines = Reflect.get(window, "__timelines");
if (typeof timelines === "object" && timelines !== null) {
for (const key of Object.keys(timelines)) {
const timeline = Reflect.get(timelines, key);
call(getProperty(timeline, "pause"), timeline, []);
call(getProperty(timeline, "seek"), timeline, [time]);
}
}
}
call(getProperty(ticker, "tick"), ticker, []);
};
const gateSlot = Symbol.for("hyperframes.webglDrawGate");
let gate = Reflect.get(window, gateSlot) as { skip: boolean; skipped: boolean } | undefined;
if (skipDraws && !gate) {
const installed = { skip: false, skipped: false };
for (const name of ["WebGLRenderingContext", "WebGL2RenderingContext"]) {
const proto = getProperty(Reflect.get(window, name), "prototype");
if (!proto) continue;
for (const method of [
"clear",
"drawArrays",
"drawElements",
"drawArraysInstanced",
"drawElementsInstanced",
"drawRangeElements",
"blitFramebuffer",
]) {
const draw = getProperty(proto, method);
if (typeof draw !== "function") continue;
Reflect.set(proto, method, function (this: unknown, ...args: unknown[]) {
if (!installed.skip) return Reflect.apply(draw, this, args);
installed.skipped = true;
return undefined;
});
}
}
Reflect.set(window, gateSlot, installed);
gate = installed;
}
const seekWithoutDraws = (time: number): void => {
if (!gate) return seekTo(time);
gate.skip = true;
try {
seekTo(time);
} finally {
gate.skip = false;
}
};
if (skipDraws) {
seekWithoutDraws(safe);
return;
}
// A skipped draw left the canvas stale and a same-time seek redraws nothing: step off first.
if (gate?.skipped) {
seekWithoutDraws(safe >= 0.001 ? safe - 0.001 : safe + 0.001);
gate.skipped = false;
}
seekTo(safe);
}
export async function seekCompositionTimeline(
page: CompositionSeekPage,
timeSeconds: number,
options: SeekCompositionTimelineOptions = {},
): Promise<void> {
await seekCompositionTimelineOnly(page, timeSeconds, options);
await settleCompositionSeek(page, options);
}
/** The seek alone; `settleCompositionSeek` must follow, which is what finishes a blurred frame. */
export async function seekCompositionTimelineOnly(
page: CompositionSeekPage,
timeSeconds: number,
options: SeekCompositionTimelineOptions = {},
): Promise<void> {
if (options.waitForPreferredSeekTargetMs !== undefined) {
await waitForPreferredSeekTarget(page, options.waitForPreferredSeekTargetMs);
}
await page.evaluate(
seekInPage,
timeSeconds,
options.fallbackToBridgeAndTimelines === true,
options.exactTime === true,
options.skipWebglDraws === true,
);
}
export async function settleCompositionSeek(
page: CompositionSeekPage,
options: SeekCompositionTimelineOptions = {},
): Promise<UnsettledImages> {
await page.evaluate(
async (barrier: SeekBarrierOptions) => {
const waitForCompletion = Reflect.get(window, "__hfWaitForSeekCompletion");
if (typeof waitForCompletion === "function") {
await Reflect.apply(waitForCompletion, window, [barrier]);
}
},
{
videoFrames: options.waitForVideoFrames !== false,
timeoutMs: Math.min(
options.seekSettleTimeoutMs ?? SEEK_SETTLES_BEFORE_PROTOCOL_TIMEOUT_MS,
SEEK_SETTLES_BEFORE_PROTOCOL_TIMEOUT_MS,
),
},
);
const animationFrameSettle = options.animationFrameSettle ?? "race";
const waitForFontsMs = options.waitForFontsMs ?? DEFAULT_POST_SEEK_FONT_WAIT_MS;
if (animationFrameSettle === "race") {
await page.evaluate(`new Promise(function(r) {
var settled = false;
function finish() { if (settled) return; settled = true; r(); }
window.setTimeout(finish, 100);
requestAnimationFrame(function() { requestAnimationFrame(finish); });
})`);
} else if (animationFrameSettle === "double" && !(waitForFontsMs > 0)) {
await page.evaluate(
() =>
new Promise<void>((resolveFrame) =>
requestAnimationFrame(() => requestAnimationFrame(() => resolveFrame())),
),
);
}
// On by default: every seek caller here is a visual-audit path (snapshot,
// check, compare, validate, layout) and a seek that reveals unrequested
// glyphs must not screenshot before their font subsets load. Costs one
// evaluate + one rAF when nothing is loading. Pass 0 to disable.
if (waitForFontsMs > 0) {
await waitForCompositionFonts(page, waitForFontsMs, animationFrameSettle === "double" ? 2 : 1);
}
const images = options.waitForImagesMs
? await waitForCompositionImages(page, options.waitForImagesMs)
: ALL_IMAGES_SETTLED;
if (options.settleMs !== undefined) {
const settleMs = Math.max(0, options.settleMs);
await new Promise((resolveSettle) => setTimeout(resolveSettle, settleMs));
}
return images;
}
export async function waitForPreferredSeekTarget(
page: Pick<CompositionSeekPage, "waitForFunction">,
timeoutMs = PREFERRED_SEEK_TARGET_WAIT_MS,
): Promise<void> {
if (!page.waitForFunction) return;
try {
await page.waitForFunction(
() => {
const player = Reflect.get(window, "__player");
const hf = Reflect.get(window, "__hf");
const renderSeek =
typeof player === "object" && player !== null
? Reflect.get(player, "renderSeek")
: undefined;
const bridgeSeek =
typeof hf === "object" && hf !== null ? Reflect.get(hf, "seek") : undefined;
return typeof renderSeek === "function" || typeof bridgeSeek === "function";
},
{ timeout: timeoutMs },
);
} catch {
// Legacy/static pages may only expose raw timelines; keep that fallback available.
}
}
/** Waits, up to `timeoutMs`, for every visible image layer (<img>, SVG <image>, CSS background-image url) to decode. */
async function waitForCompositionImages(
page: CompositionEvaluationPage,
timeoutMs: number,
): Promise<UnsettledImages> {
const unsettled = await page.evaluate(
// fallow-ignore-next-line complexity
async (ms: number) => {
const layers = new Map<string, HTMLImageElement>();
const add = (src: string, image?: HTMLImageElement): void => {
if (src && !layers.has(src)) layers.set(src, image ?? Object.assign(new Image(), { src }));
};
const absolute = (href: string): string => new URL(href, document.baseURI).href;
for (const element of document.querySelectorAll("*")) {
const style = getComputedStyle(element);
if (style.display === "none" || style.visibility === "hidden") continue;
if (element instanceof HTMLImageElement) add(element.currentSrc || element.src, element);
if (element instanceof SVGImageElement && element.href.baseVal) {
add(absolute(element.href.baseVal));
}
for (const match of style.backgroundImage.matchAll(
/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)]*))\s*\)/g,
)) {
const href = match[1] ?? match[2] ?? match[3];
if (href) add(absolute(href));
}
}
const state = new Map<string, "pending" | "ready" | "failed">();
const decodes = [...layers].map(([src, image]) => {
state.set(src, "pending");
return image.decode().then(
() => void state.set(src, "ready"),
() => void state.set(src, "failed"),
);
});
let timer: ReturnType<typeof setTimeout> | undefined;
await Promise.race([
Promise.all(decodes),
new Promise((resolveWait) => {
timer = setTimeout(resolveWait, ms);
}),
]);
clearTimeout(timer);
const named = (want: string): string[] =>
[...state]
.filter(([, value]) => value === want)
.map(([src]) => (src.startsWith("data:") ? `${src.slice(0, 40)}...` : src));
return { pending: named("pending"), failed: named("failed") };
},
timeoutMs,
);
return unsettled as UnsettledImages;
}
export async function waitForCompositionFonts(
page: CompositionEvaluationPage,
timeoutMs: number,
frames = 1,
): Promise<void> {
await page
.evaluate(
({ ms, frames: count }: FontWaitOptions) => {
const fonts = Reflect.get(document, "fonts");
// A seek can reveal glyphs whose unicode-range font subsets never loaded, and `fonts.ready`
// resolves before their load starts (blank CJK glyphs in snapshots). Force layout so they start,
// let the loader flip `fonts.status` over the given frames, then await readiness.
void document.body?.offsetHeight;
const afterFrames = (left: number, then: () => void): void => {
requestAnimationFrame(() => (left > 1 ? afterFrames(left - 1, then) : then()));
};
return new Promise<void>((resolveWait) => {
const deadline = setTimeout(resolveWait, ms);
afterFrames(count, () => {
const status = fonts ? Reflect.get(fonts, "status") : undefined;
const ready = fonts ? Reflect.get(fonts, "ready") : undefined;
if (status !== "loading" || !ready) {
clearTimeout(deadline);
resolveWait();
return;
}
Promise.resolve(ready).then(() => {
clearTimeout(deadline);
resolveWait();
});
});
});
},
{ ms: timeoutMs, frames },
)
.catch(() => {});
}
export interface CropRegion {
x: number;
y: number;
width: number;
height: number;
}
export interface CropCanvas {
width: number;
height: number;
}
export type ZoomTarget =
| { kind: "selector"; selector: string }
| { kind: "region"; region: CropRegion };
// Four bare comma-separated numbers is unambiguous — no valid CSS selector
// parses as that shape — so it always means "exact pixel region".
const ZOOM_REGION_PATTERN = /^-?\d+(?:\.\d+)?(?:,-?\d+(?:\.\d+)?){3}$/;
export const DEFAULT_ZOOM_PADDING_PX = 24;
// One knob for every zoom/crop consumer (snapshot --zoom-scale default, check's
// finding crops): density of the captured pixels relative to CSS pixels.
export const DEFAULT_ZOOM_SCALE = 3;
/** Parse `snapshot --zoom` into either a CSS selector or an exact pixel region "x,y,w,h". */
export function parseZoomTarget(value: string): ZoomTarget {
const trimmed = value.trim();
if (ZOOM_REGION_PATTERN.test(trimmed)) {
const [x, y, width, height] = trimmed.split(",").map(Number) as [
number,
number,
number,
number,
];
return { kind: "region", region: { x, y, width, height } };
}
return { kind: "selector", selector: trimmed };
}
/** Clamp a region to the canvas bounds — Puppeteer's clip screenshot rejects a
* region that spills outside the viewport. Keeps at least 1px on each side. */
export function clampCropRegion(region: CropRegion, canvas: CropCanvas): CropRegion {
const x = Math.max(0, Math.min(region.x, canvas.width));
const y = Math.max(0, Math.min(region.y, canvas.height));
const x2 = Math.max(x + 1, Math.min(region.x + region.width, canvas.width));
const y2 = Math.max(y + 1, Math.min(region.y + region.height, canvas.height));
return { x, y, width: x2 - x, height: y2 - y };
}
/** Pad a region on every side (context around a zoomed element), then clamp. */
export function padCropRegion(
region: CropRegion,
canvas: CropCanvas,
paddingPx: number,
): CropRegion {
return clampCropRegion(
{
x: region.x - paddingPx,
y: region.y - paddingPx,
width: region.width + paddingPx * 2,
height: region.height + paddingPx * 2,
},
canvas,
);
}
export interface ZoomSelectorPage {
evaluate(
pageFunction: (selector: string) => CropRegion | null,
selector: string,
): Promise<CropRegion | null>;
}
/**
* Resolve a `--zoom` target to a concrete crop region. A selector resolves to
* its live bbox (padded ~24px, then clamped); an explicit region is used
* as-is (clamped only, never padded — region form crops exactly). A selector
* matching nothing throws: a loud error beats a silent full-frame fallback.
*/
// A selector can match an element whose visible box is gone at the sampled
// time — collapsed (display:none mid-timeline) or animated off-canvas, where
// clamping leaves a pixel-wide remnant. Either way the crop would be a sliver
// that tells an agent nothing, so the final clamped region is what's guarded
// and callers skip the frame on null. Explicit x,y,w,h regions stay literal.
const MIN_CROP_REGION_PX = 8;
export async function resolveCropRegion(
page: ZoomSelectorPage,
target: ZoomTarget,
canvas: CropCanvas,
paddingPx = DEFAULT_ZOOM_PADDING_PX,
): Promise<CropRegion | null> {
if (target.kind === "region") return clampCropRegion(target.region, canvas);
const bbox = await page.evaluate((selector) => {
const element = document.querySelector(selector);
if (!element) return null;
const rect = element.getBoundingClientRect();
return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
}, target.selector);
if (!bbox) throw new Error(`--zoom selector matched no element: ${target.selector}`);
const region = padCropRegion(bbox, canvas, paddingPx);
if (region.width < MIN_CROP_REGION_PX || region.height < MIN_CROP_REGION_PX) return null;
return region;
}
export interface CropCapturePage {
viewport(): { width: number; height: number; deviceScaleFactor?: number } | null;
setViewport(viewport: {
width: number;
height: number;
deviceScaleFactor?: number;
}): Promise<void>;
screenshot(options: { clip: CropRegion; type: "png"; omitBackground: true }): Promise<Uint8Array>;
}
/**
* Capture a high-density crop of `region`: raise `deviceScaleFactor` to
* `scale`, take a clip screenshot, then restore the original viewport.
* Deliberately NOT CSS zoom or a viewport resize — DSF only changes how
* densely Chrome rasterizes the existing CSS-pixel layout, so the
* composition's layout (and its render determinism) is untouched. The PNG
* comes out at `region.width * scale` real device pixels, not an upscale.
*/
export async function captureRegionCrop(
page: CropCapturePage,
region: CropRegion,
scale: number,
): Promise<Buffer> {
const original = page.viewport();
if (original) await page.setViewport({ ...original, deviceScaleFactor: scale });
try {
const shot = await page.screenshot({ clip: region, type: "png", omitBackground: true });
return Buffer.isBuffer(shot) ? shot : Buffer.from(shot);
} finally {
if (original) await page.setViewport(original);
}
}
export async function runFfmpegOnce(
ffmpegPath: string,
args: readonly string[],
timeoutMs: number,
): Promise<FfmpegRunResult> {
return await new Promise((resolvePromise) => {
const ff = spawn(ffmpegPath, args, { windowsHide: true });
let stderr = "";
let timedOut = false;
const timer = setTimeout(() => {
timedOut = true;
ff.kill("SIGTERM");
}, timeoutMs);
ff.stderr.on("data", (data: Buffer) => {
stderr += data.toString();
});
ff.on("close", (code) => {
clearTimeout(timer);
resolvePromise({ code, stderr, timedOut });
});
ff.on("error", () => {
clearTimeout(timer);
resolvePromise({ code: null, stderr: "ffmpeg spawn failed", timedOut });
});
});
}
/** Requests to the in-process origin are answered here; any other request goes on as usual. */
async function answerPageInProcess(
page: Page,
url: string,
answer: (request: InProcessRequest) => Promise<InProcessResponse>,
): Promise<void> {
const origin = new URL(url).origin;
await page.setRequestInterception(true);
page.on("request", (request) => {
if (request.isInterceptResolutionHandled()) return;
const target = new URL(request.url());
if (target.origin !== origin) return void request.continue().catch(() => {});
answer({
method: request.method(),
path: target.pathname + target.search,
headers: request.headers(),
})
.then((response) => request.respond(response))
.catch(() => request.abort("failed").catch(() => {}));
});
}