mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 23:47:33 +00:00
* fix(capture): never silently render a webgpu composition blank A composition declaring data-requires-webgpu only got the Chrome WebGPU flag when hardware GPU auto-detection succeeded. On a software-GPU host it launched without the flag and rendered blank with no error. compositionRequiresWebGpu (static declaration check) and assertWebGpuAdapterAvailable (live per-page adapter probe) now live once in packages/engine's browserManager, the shared choke point every launch site already goes through. All six launch sites (frame capture, the four CLI diagnostic commands, the studio thumbnail server, and the render pipeline's capture-options builder) route through those two functions; the old CLI-only static-heuristic guard is deleted, not kept alongside the new one. A software host that cannot obtain any WebGPU adapter now fails loudly naming the requirement instead of producing a blank frame. * fix(capture): thread requiresWebGpu through the distributed chunk-render path The distributed renderChunk() path built its CaptureOptions without requiresWebGpu, so it fell through to frameCapture's own fetch-based detection, whose failure path silently treats "requires webgpu" as "doesn't" if that fetch ever fails. Every other launch site (frame capture, all four CLI diagnostic commands, the studio thumbnail server, and the in-process render pipeline) already reads the value from HTML already in memory or on disk instead of relying on that fallback. Reads the compiled composition's index.html the same way probeStage already does and derives requiresWebGpu from it before building CaptureOptions. Adds a regression test that pins the exact path renderChunk() reads at render time, since the composition doesn't actually exercise WebGPU so an end-to-end render can't distinguish the two cases on this host. * test(producer): observe the real CaptureOptions renderChunk() builds The previous regression test called plan() and compositionRequiresWebGpu() directly, bypassing renderChunk() entirely, so it could not detect a regression to the wiring it was meant to protect (confirmed: it stayed green with the fix reverted). Exports the existing createCaptureSession dependency seam so a test can substitute a spy that delegates to the real implementation while capturing the CaptureOptions object renderChunk() actually constructs. Verified non-vacuous by reverting the fix and confirming the test fails. * fix(gcp-cloud-run): resolve puppeteer-core from a real file in the webgpu probe The image build's WebGPU adapter probe imported puppeteer-core from an inline `bun -e` eval string. The eval's synthetic /app/[eval] location can't resolve the workspace-hoisted dependency, so every build of this stage failed closed with "Cannot find package 'puppeteer-core'" before the probe itself ever ran. Moves the probe into a real script file next to probe-beginframe.ts, which already imports puppeteer-core dynamically the same way and resolves fine from its real workspace location. Verified locally against a cached chrome-headless-shell binary. * fix(engine): bound the webgpu adapter probe so a stuck driver can't hang the caller requestAdapter() has no native timeout. A broken software GPU driver that never settles it would hang assertWebGpuAdapterAvailable indefinitely, including inside the GCP image build's probe RUN step, producing an opaque build timeout instead of a clean probe failure. Races the in-page request against a bounded timeout so a stuck adapter reads as unavailable and fails the same way a genuinely absent one does. * test(cli): mock the engine's webgpu exports in the browser-fallback test * test(producer): run the typegpu adapter fixture only on hosts with a hardware WebGPU adapter The fixture declares data-requires-webgpu, so a software-only host now refuses it instead of silently rendering the shader blank. The old golden had no shader in it. Tag it webgpu, skip that tag in the CI image and the test scripts, and re-record the golden from a Metal render with the shader visible. * fix(engine): bound the composition fetch that decides the webgpu flag createCaptureSession fetched the served page with no timeout before launching the browser, so a hung server stalled a render forever and hung a fake-timer test. Give it a five second limit, and let that test say it has no WebGPU requirement the way the producer does. * fix(capture): refuse a software fallback WebGPU adapter instead of rendering on it swiftshader reports a WebGPU adapter but cannot render canvas WebGPU, so a data-requires-webgpu composition on a software-only host crashed on its first frame. Refuse fallback adapters with the same clear WebGPU-unavailable error. The GCP image probe now serves its page over http (file:// hides navigator.gpu) and reports a software-only host instead of failing the image build. * fix(engine): parse the composition root tag without a backtracking regex * fix(engine): keep quoted attribute values whole when reading the composition root tag
564 lines
21 KiB
TypeScript
564 lines
21 KiB
TypeScript
import { spawn } from "node:child_process";
|
|
import type { Browser, Page } from "puppeteer-core";
|
|
import { c } from "../ui/colors.js";
|
|
import {
|
|
assertWebGpuAdapterAvailable,
|
|
compositionRequiresWebGpu,
|
|
resolveCaptureBrowserGpuMode,
|
|
resolveLocalBrowserGpuMode,
|
|
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 { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";
|
|
|
|
const SHADER_TRANSITIONS_TIMEOUT_MS = 90_000;
|
|
const CAPTURE_SETTLE_MS = 1500;
|
|
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, sleep.
|
|
export const AUDIT_SEEK_OPTIONS = {
|
|
fallbackToBridgeAndTimelines: true,
|
|
animationFrameSettle: "double",
|
|
waitForFontsMs: 500,
|
|
settleMs: 120,
|
|
} as const;
|
|
|
|
// 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,
|
|
} as const;
|
|
|
|
export interface SeekCompositionTimelineOptions {
|
|
fallbackToBridgeAndTimelines?: boolean;
|
|
waitForPreferredSeekTargetMs?: number;
|
|
animationFrameSettle?: "race" | "double" | "none";
|
|
waitForFontsMs?: number;
|
|
settleMs?: number;
|
|
}
|
|
|
|
type CompositionPageFunction =
|
|
| string
|
|
| (() => unknown)
|
|
| ((value: number) => unknown)
|
|
| ((value: number, fallbackToBridgeAndTimelines: boolean) => unknown);
|
|
|
|
export interface CompositionEvaluationPage {
|
|
evaluate(
|
|
pageFunction: CompositionPageFunction,
|
|
value?: number,
|
|
fallbackToBridgeAndTimelines?: 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. Diagnostic callers
|
|
// without their own navigation knob keep the historical 10-second minimum.
|
|
navigationTimeoutMs?: number;
|
|
renderReadyTimeoutMs: number;
|
|
renderReadyWarningSuffix: string;
|
|
browserGpuMode?: BrowserGpuMode;
|
|
// 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>;
|
|
}
|
|
|
|
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"));
|
|
}
|
|
|
|
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();
|
|
}
|
|
|
|
async function waitForCompositionSettle(
|
|
page: Page,
|
|
options: OpenSettledCompositionPageOptions,
|
|
): Promise<boolean> {
|
|
const runtimeReady = await page
|
|
.waitForFunction(compositionRuntimeReadyInBrowser, { timeout: options.renderReadyTimeoutMs })
|
|
.then(() => true)
|
|
.catch(() => false);
|
|
|
|
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 page.evaluate(() => document.fonts.ready).catch(() => {});
|
|
await new Promise((resolveSettle) => setTimeout(resolveSettle, CAPTURE_SETTLE_MS));
|
|
return runtimeReady;
|
|
}
|
|
|
|
// 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 { ensureBrowser, findSystemBrowser } = await import("../browser/manager.js");
|
|
const browser = await ensureBrowser();
|
|
const puppeteer = await import("puppeteer-core");
|
|
const { buildChromeArgs } = await import("@hyperframes/engine");
|
|
const requestedGpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
|
|
const requiresWebGpu = compositionRequiresWebGpu(html);
|
|
const launch = async (executablePath: string): Promise<Browser> => {
|
|
const resolvedGpuMode = await resolveCaptureBrowserGpuMode(requestedGpuMode, executablePath);
|
|
return puppeteer.default.launch({
|
|
headless: true,
|
|
executablePath,
|
|
args: buildChromeArgs(
|
|
{ ...viewport, captureMode: "screenshot", requiresWebGpu },
|
|
{ browserGpuMode: resolvedGpuMode },
|
|
),
|
|
});
|
|
};
|
|
|
|
let chromeBrowser: Browser | undefined;
|
|
try {
|
|
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 },
|
|
);
|
|
}
|
|
}
|
|
|
|
const page = await chromeBrowser.newPage();
|
|
await installPageFunctionGuard(page);
|
|
await page.setViewport(viewport);
|
|
await options.beforeNavigate?.(page);
|
|
await page.goto(url, {
|
|
waitUntil: "domcontentloaded",
|
|
timeout: resolveDiagnosticNavigationTimeoutMs(process.env, options.navigationTimeoutMs),
|
|
});
|
|
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
|
|
const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
|
|
return { browser: chromeBrowser, page, renderReadyTimedOut };
|
|
} catch (err) {
|
|
await chromeBrowser?.close().catch(() => {});
|
|
throw err;
|
|
}
|
|
}
|
|
|
|
export async function seekCompositionTimeline(
|
|
page: CompositionSeekPage,
|
|
timeSeconds: number,
|
|
options: SeekCompositionTimelineOptions = {},
|
|
): Promise<void> {
|
|
if (options.waitForPreferredSeekTargetMs !== undefined) {
|
|
await waitForPreferredSeekTarget(page, options.waitForPreferredSeekTargetMs);
|
|
}
|
|
|
|
await page.evaluate(
|
|
// Serialized into the page; the seek-target cascade must stay one function.
|
|
// fallow-ignore-next-line complexity
|
|
(t: number, fallbackToBridgeAndTimelines: boolean) => {
|
|
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");
|
|
|
|
// 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, [safe])) {
|
|
// Preferred runtime target handled the seek.
|
|
} else if (fallbackToBridgeAndTimelines && call(bridgeSeek, hf, [safe])) {
|
|
// Producer bridge handled the seek.
|
|
} else if (call(playerSeek, player, [safe])) {
|
|
// 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, [safe]);
|
|
}
|
|
}
|
|
}
|
|
|
|
const gsap = Reflect.get(window, "gsap");
|
|
const ticker = getProperty(gsap, "ticker");
|
|
call(getProperty(ticker, "tick"), ticker, []);
|
|
},
|
|
timeSeconds,
|
|
options.fallbackToBridgeAndTimelines === true,
|
|
);
|
|
|
|
await page.evaluate(async () => {
|
|
const waitForCompletion = Reflect.get(window, "__hfWaitForSeekCompletion");
|
|
if (typeof waitForCompletion === "function") {
|
|
await Reflect.apply(waitForCompletion, window, []);
|
|
}
|
|
});
|
|
|
|
const animationFrameSettle = options.animationFrameSettle ?? "race";
|
|
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") {
|
|
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.
|
|
const waitForFontsMs = options.waitForFontsMs ?? DEFAULT_POST_SEEK_FONT_WAIT_MS;
|
|
if (waitForFontsMs > 0) {
|
|
await waitForCompositionFonts(page, waitForFontsMs);
|
|
}
|
|
if (options.settleMs !== undefined) {
|
|
const settleMs = Math.max(0, options.settleMs);
|
|
await new Promise((resolveSettle) => setTimeout(resolveSettle, settleMs));
|
|
}
|
|
}
|
|
|
|
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.
|
|
}
|
|
}
|
|
|
|
export async function waitForCompositionFonts(
|
|
page: CompositionEvaluationPage,
|
|
timeoutMs: number,
|
|
): Promise<void> {
|
|
await page
|
|
.evaluate((ms: number) => {
|
|
const fonts = Reflect.get(document, "fonts");
|
|
if (typeof fonts !== "object" || fonts === null) return Promise.resolve();
|
|
// A seek can reveal glyphs whose font faces were never requested —
|
|
// CJK @font-face splits into unicode-range subsets that only load when
|
|
// first laid out. `fonts.ready` is already-resolved at that moment, so
|
|
// awaiting it immediately races the load request and screenshots blank
|
|
// glyphs (wild reports: Traditional Chinese / Microsoft YaHei check
|
|
// snapshots). Force a synchronous layout so pending subsets actually
|
|
// start loading, give the loader one frame to flip `fonts.status`,
|
|
// THEN await readiness.
|
|
void document.body?.offsetHeight;
|
|
return new Promise<void>((resolveWait) => {
|
|
const deadline = setTimeout(resolveWait, ms);
|
|
requestAnimationFrame(() => {
|
|
const status = Reflect.get(fonts, "status");
|
|
const ready = Reflect.get(fonts, "ready");
|
|
if (status !== "loading" || !ready) {
|
|
clearTimeout(deadline);
|
|
resolveWait();
|
|
return;
|
|
}
|
|
Promise.resolve(ready).then(() => {
|
|
clearTimeout(deadline);
|
|
resolveWait();
|
|
});
|
|
});
|
|
});
|
|
}, timeoutMs)
|
|
.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 });
|
|
});
|
|
});
|
|
}
|