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; } export interface CompositionSeekPage extends CompositionEvaluationPage { waitForFunction?(pageFunction: () => boolean, options: { timeout: number }): Promise; } 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; // Runs after navigation and before the render-ready wait. onLoaded?: (page: Page) => void | Promise; // 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; take(key: string): Promise; discard(): Promise; } 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>, timeoutMs: number, ): Promise { 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 { 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 { let cap: ReturnType | 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; }): Promise { await page.evaluateOnNewDocument("self.__name = self.__name || ((fn) => fn);"); } export async function openSettledCompositionPage( html: string, url: string, options: OpenSettledCompositionPageOptions, ): Promise { 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.evaluateOnNewDocument("window.__HF_RELEASE_PASSED_MEDIA = 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 { 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 => { 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 { 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 { 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 { 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((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, timeoutMs = PREFERRED_SEEK_TARGET_WAIT_MS, ): Promise { 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 (, SVG , CSS background-image url) to decode. */ async function waitForCompositionImages( page: CompositionEvaluationPage, timeoutMs: number, ): Promise { const unsettled = await page.evaluate( // fallow-ignore-next-line complexity async (ms: number) => { const layers = new Map(); 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(); 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 | 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 { 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((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; } /** * 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 { 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; screenshot(options: { clip: CropRegion; type: "png"; omitBackground: true }): Promise; } /** * 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 { 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 { 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, ): Promise { 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(() => {})); }); }