Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): bound checks of non-finishing compositions (#5537)
Miguel Ángelc96099d39a12
diff --git a/.github/workflows/windows-render.yml b/.github/workflows/windows-render.ymlindex 1bdbcec71d..d214a7458a 100644--- a/.github/workflows/windows-render.yml+++ b/.github/workflows/windows-render.yml@@ -494,6 +494,11 @@ jobs:bun run --filter '@hyperframes/{parsers,lint,studio-server}' buildbun run --cwd packages/core build+ - name: Prepare browser for process tests+ if: matrix.lane == 'engine-cli'+ shell: pwsh+ run: node --import tsx packages/cli/scripts/prepare-process-test-browser.mjs+- name: Run Studio shard ${{ matrix.studio_shard }}if: matrix.studio_shardshell: pwshdiff --git a/packages/cli/scripts/prepare-process-test-browser.mjs b/packages/cli/scripts/prepare-process-test-browser.mjsnew file mode 100644index 0000000000..ab033e6a33--- /dev/null+++ b/packages/cli/scripts/prepare-process-test-browser.mjs@@ -0,0 +1,22 @@+import { appendFileSync } from "node:fs";+import puppeteer from "puppeteer-core";+import { ensureBrowser } from "../src/browser/manager.ts";+import { launchManagedBrowser, closeManagedBrowser } from "../src/browser/launch.ts";++const envFile = process.env.GITHUB_ENV;+if (!envFile) throw new Error("Missing workflow environment file");++const { executablePath } = await ensureBrowser({ preferManagedChrome: true });+const browser = await launchManagedBrowser(puppeteer, {+ executablePath,+ headless: true,+ args: ["--no-sandbox"],+});+try {+ const page = await browser.newPage();+ await page.evaluate(() => 1);+} finally {+ await closeManagedBrowser(browser);+}+appendFileSync(envFile, `HYPERFRAMES_BROWSER_PATH=${executablePath}\n`);+console.log("Pinned process-test browser installed, connected, and stopped.");diff --git a/packages/cli/src/browser/gpuPolicy.ts b/packages/cli/src/browser/gpuPolicy.tsindex aaa4774611..fd19029bb6 100644--- a/packages/cli/src/browser/gpuPolicy.ts+++ b/packages/cli/src/browser/gpuPolicy.ts@@ -1,4 +1,4 @@-import { resolveConfig, usesSoftwareWebGpu } from "@hyperframes/engine";+import { resolveConfig, usesSoftwareWebGpu, type GpuProbeLifecycle } from "@hyperframes/engine";export type BrowserGpuMode = "auto" | "hardware" | "software";export type ResolvedBrowserGpuMode = Exclude<BrowserGpuMode, "auto">;@@ -16,9 +16,10 @@ export function resolveLocalBrowserGpuMode(export async function resolveCaptureBrowserGpuMode(requestedMode: BrowserGpuMode,chromePath?: string,+ probeLifecycle?: GpuProbeLifecycle,): Promise<ResolvedBrowserGpuMode> {const { resolveBrowserGpuMode } = await import("@hyperframes/engine");- return resolveBrowserGpuMode(requestedMode, { chromePath });+ return resolveBrowserGpuMode(requestedMode, { chromePath, probeLifecycle });}// `compositionRequiresWebGpu` and the launch-time WebGPU guard now live indiff --git a/packages/cli/src/browser/launch.ts b/packages/cli/src/browser/launch.tsindex f4b593b492..ceb994d0f8 100644--- a/packages/cli/src/browser/launch.ts+++ b/packages/cli/src/browser/launch.ts@@ -4,9 +4,13 @@ import {type BrowserGpuMode,type ResolvedBrowserGpuMode,} from "./gpuPolicy.js";+import { normalizeErrorMessage } from "../utils/errorMessage.js";import { requestCliExit } from "../utils/commandResult.js";+export class BrowserCleanupError extends AggregateError {}+const browsers = new Set<Browser>();+const closing = new WeakMap<Browser, Promise<void>>();const pending = new Map<Promise<Browser>, AbortController>();const CLOSE_GRACE_MS = 1_000;let listening = false;@@ -36,9 +40,22 @@ function ownSignals(): void {export async function resolveManagedGpuMode(requestedMode: BrowserGpuMode,chromePath?: string,+ context: { signal?: AbortSignal; onBrowser?: (browser: Browser) => void } = {},): Promise<ResolvedBrowserGpuMode> {ownSignals();- return resolveCaptureBrowserGpuMode(requestedMode, chromePath);+ return resolveCaptureBrowserGpuMode(requestedMode, chromePath, {+ launch: async (puppeteer, options) => {+ context.signal?.throwIfAborted();+ const browser = await launchManagedBrowser(puppeteer, { ...options, signal: context.signal });+ try {+ context.onBrowser?.(browser);+ } catch (error) {+ return rethrowAfterBrowserCleanup(browser, error);+ }+ return browser;+ },+ close: closeManagedBrowser,+ });}/** One owner for every CLI browser, including a launch cancelled before its connection is ready. */@@ -73,7 +90,33 @@ export async function launchManagedBrowser(async function closeManagedBrowsers(): Promise<void> {for (const abort of pending.values()) abort.abort();await Promise.allSettled(pending.keys());- await Promise.all([...browsers].map(closeBrowser));+ await Promise.all([...browsers].map(closeManagedBrowser));+}++/** Manual teardown and signal teardown share the same bounded close, exactly once. */+export function closeManagedBrowser(browser: Browser): Promise<void> {+ const existing = closing.get(browser);+ if (existing) return existing;+ const close = closeBrowser(browser);+ closing.set(browser, close);+ return close;+}++export async function rethrowAfterBrowserCleanup(+ browser: Browser | undefined,+ error: unknown,+): Promise<never> {+ if (browser) {+ try {+ await closeManagedBrowser(browser);+ } catch (cleanupError) {+ throw new BrowserCleanupError(+ [error, cleanupError],+ `${normalizeErrorMessage(error)}; browser cleanup failed: ${normalizeErrorMessage(cleanupError)}`,+ );+ }+ }+ throw error;}async function closeBrowser(browser: Browser): Promise<void> {@@ -91,7 +134,14 @@ async function closeBrowser(browser: Browser): Promise<void> {grace,]);if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");- await exited;+ clearTimeout(timer);+ const exitLimit = new Promise<never>((_, reject) => {+ timer = setTimeout(+ () => reject(new Error("Browser process did not exit after forced shutdown.")),+ CLOSE_GRACE_MS,+ );+ });+ await Promise.race([exited, exitLimit]);} finally {clearTimeout(timer);}diff --git a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.tsindex 7e954035b3..aa77cbef3f 100644--- a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts+++ b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts@@ -84,6 +84,45 @@ describe("openSettledCompositionPage Windows bundled-browser recovery", () => {if (originalPlatform) Object.defineProperty(process, "platform", originalPlatform);});+ it("cancels browser setup with the caller's signal before launching", async () => {+ const abort = new AbortController();+ const failure = new Error("browser setup cancelled");+ mocks.ensureBrowser.mockImplementation(async (options) => {+ if (options?.signal !== abort.signal) throw new Error("setup has no caller signal");+ abort.abort(failure);+ throw abort.signal.reason;+ });+ await expect(+ openSettledCompositionPage(HTML, "http://127.0.0.1:3000", {+ ...OPTIONS,+ signal: abort.signal,+ }),+ ).rejects.toBe(failure);+ expect(mocks.launch).not.toHaveBeenCalled();+ });++ it("starts the composition clock after browser launch and before page creation", async () => {+ const order: string[] = [];+ const opened = fakeBrowser();+ mocks.launch.mockImplementationOnce(async () => {+ order.push("launch");+ return opened.browser;+ });+ opened.browser.newPage.mockImplementationOnce(async () => {+ order.push("page");+ return opened.page;+ });+ const onBrowserReady = vi.fn(() => {+ order.push("ready");+ });+ await openSettledCompositionPage(HTML, "http://127.0.0.1:3000", {+ ...OPTIONS,+ onBrowserReady,+ });+ expect(order).toEqual(["launch", "ready", "page"]);+ expect(onBrowserReady).toHaveBeenCalledOnce();+ });+it("launches software WebGPU and accepts its adapter when render's opt-in is set", async () => {const opened = fakeBrowser();mocks.launch.mockResolvedValueOnce(opened.browser);diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.tsindex df64340db5..08c2abdafc 100644--- a/packages/cli/src/capture/captureCompositionFrame.ts+++ b/packages/cli/src/capture/captureCompositionFrame.ts@@ -1,4 +1,8 @@-import { launchManagedBrowser, resolveManagedGpuMode } from "../browser/launch.js";+import {+ rethrowAfterBrowserCleanup,+ launchManagedBrowser,+ resolveManagedGpuMode,+} from "../browser/launch.js";import { spawn } from "node:child_process";import type { Browser, Page } from "puppeteer-core";import { c } from "../ui/colors.js";@@ -79,6 +83,10 @@ export interface OpenSettledCompositionPageOptions {renderReadyTimeoutMs: number;renderReadyWarningSuffix: string;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>;@@ -189,18 +197,24 @@ export async function openSettledCompositionPage(): Promise<SettledCompositionPage> {const viewport = resolveCompositionViewportFromHtml(html);const { ensureBrowser, findSystemBrowser } = await import("../browser/manager.js");- const browser = await ensureBrowser();+ 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> => {- const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath);+ options.signal?.throwIfAborted();+ const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath, {+ signal: options.signal,+ onBrowser: options.onBrowser,+ });+ options.signal?.throwIfAborted();const webGpu = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);softwareWebGpu = webGpu.softwareWebGpu;return launchManagedBrowser(puppeteer.default, {headless: true,+ signal: options.signal,executablePath,args: buildChromeArgs({ ...viewport, captureMode: "screenshot", requiresWebGpu },@@ -239,6 +253,8 @@ export async function openSettledCompositionPage(}}+ options.onBrowser?.(chromeBrowser);+ options.onBrowserReady?.();const page = await chromeBrowser.newPage();await installPageFunctionGuard(page);await page.setViewport(viewport);@@ -251,8 +267,7 @@ export async function openSettledCompositionPage(const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));return { browser: chromeBrowser, page, renderReadyTimedOut };} catch (err) {- await chromeBrowser?.close().catch(() => {});- throw err;+ return rethrowAfterBrowserCleanup(chromeBrowser, err);}}diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.tsindex 9f29272905..a9c8f4473a 100644--- a/packages/cli/src/commands/check.test.ts+++ b/packages/cli/src/commands/check.test.ts@@ -12,6 +12,7 @@ vi.mock("../telemetry/events.js", () => ({import { contrastRatio, parseColorRGBA } from "./contrast-bg.js";import { createCheckCommand, parseCheckRange } from "./check.js";+import { CheckDeadlineError } from "../utils/checkDeadline.js";import { trackCommandFailures } from "../utils/command-failure-tracking.js";import type { CommandDef } from "citty";@@ -1552,6 +1553,28 @@ describe("check pipeline", () => {expect(noErrors).not.toHaveBeenCalled();});+ it("reports the total deadline during crops while retaining the audit failure", async () => {+ const { report } = await runScenario(+ fakeDriver({+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),+ }),+ { snapshots: true },+ {+ captureFindingCrops: async () => {+ throw new CheckDeadlineError();+ },+ },+ );+ expect(report.ok).toBe(false);+ expect(report.layout.errorCount).toBeGreaterThan(0);+ expect(report.runtime.findings).toContainEqual(+ expect.objectContaining({+ code: "check_runtime_failure",+ message: "Check did not finish within its deadline.",+ }),+ );+ });+it("--strict flips a warnings-only result from exit 0 to exit 1", async () => {const warningDriver = () =>fakeDriver({@@ -1888,6 +1911,7 @@ describe("sampled finding reporting", () => {bbox: { x: 500, y: 20, width: 300, height: 80 },},],+ expect.objectContaining({ signal: expect.any(AbortSignal) }),);});diff --git a/packages/cli/src/utils/checkBrowser.test.ts b/packages/cli/src/utils/checkBrowser.test.tsindex 307853dd97..e57a599ab5 100644--- a/packages/cli/src/utils/checkBrowser.test.ts+++ b/packages/cli/src/utils/checkBrowser.test.ts@@ -110,9 +110,12 @@ afterEach(() => {function installSessionMock(page: ReturnType<typeof fakePage>): void {const browser = Object.assign(Object.create(null), {close: vi.fn(async () => undefined),+ process: () => ({ exitCode: 0, signalCode: null }),});vi.mocked(openSettledCompositionPage).mockImplementation(async (_html: string, _url: string, options: OpenSettledCompositionPageOptions) => {+ options.onBrowser?.(browser);+ options.onBrowserReady?.();await options.beforeNavigate?.(page);return { page, browser, renderReadyTimedOut: false };},diff --git a/packages/cli/src/utils/checkBrowser.ts b/packages/cli/src/utils/checkBrowser.tsindex 1a154c99f4..d7c8bfb76c 100644--- a/packages/cli/src/utils/checkBrowser.ts+++ b/packages/cli/src/utils/checkBrowser.ts@@ -1,7 +1,9 @@+import type { CheckDeadline } from "./checkDeadline.js";+import { BrowserCleanupError, closeManagedBrowser } from "../browser/launch.js";import { checkSnapshotDirectory } from "./checkSnapshotDirectory.js";import { mkdirSync, writeFileSync } from "node:fs";import { join, resolve } from "node:path";-import type { Page } from "puppeteer-core";+import type { Browser, Page } from "puppeteer-core";import {AUDIT_SEEK_OPTIONS,DENSE_GEOMETRY_SEEK_OPTIONS,@@ -191,6 +193,7 @@ export async function runBrowserCheck(options: CheckOptions,motion: MotionSpecResolution,runGrid: RunAuditGrid,+ deadline?: CheckDeadline,): Promise<CheckBrowserResult> {const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");const html = await bundleWithLocalizedFonts(project.dir);@@ -207,6 +210,7 @@ export async function runBrowserCheck(options.autoProxy,);let currentTime = 0;+ let failure: { kind: "none" } | { kind: "failed"; error: unknown } = { kind: "none" };let chromeBrowser: import("puppeteer-core").Browser | undefined;try {@@ -216,7 +220,13 @@ export async function runBrowserCheck(renderReadyTimeoutMs: options.timeout,renderReadyWarningSuffix: "checking the current page state",browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),- beforeNavigate: (page) => wireRuntimeListeners(page, drafts, () => currentTime),+ signal: deadline?.signal,+ onBrowser: deadline?.ownBrowser,+ onBrowserReady: deadline?.start,+ beforeNavigate: async (page) => {+ wireRuntimeListeners(page, drafts, () => currentTime);+ await deadline?.preparePage(page);+ },});chromeBrowser = session.browser;const page = session.page;@@ -250,9 +260,11 @@ export async function runBrowserCheck(failedPaths,).map((draft) => runtimeFinding(draft, rootAnchor)),};+ } catch (error) {+ failure = { kind: "failed", error };+ throw error;} finally {- await chromeBrowser?.close().catch(() => undefined);- await server.close();+ await closeCheckResources(chromeBrowser, server, failure);}}@@ -266,6 +278,7 @@ export async function captureFindingCrops(project: ProjectDir,options: CheckOptions,requests: CheckFindingCropRequest[],+ deadline?: CheckDeadline,): Promise<string[]> {if (requests.length === 0) return [];const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");@@ -279,11 +292,16 @@ export async function captureFindingCrops();let chromeBrowser: import("puppeteer-core").Browser | undefined;const written: string[] = [];+ let failure: { kind: "none" } | { kind: "failed"; error: unknown } = { kind: "none" };try {const session = await openSettledCompositionPage(html, server.url, {navigationTimeoutMs: options.timeout,renderReadyTimeoutMs: options.timeout,renderReadyWarningSuffix: "capturing finding crops",+ signal: deadline?.signal,+ onBrowser: deadline?.ownBrowser,+ onBrowserReady: deadline?.start,+ beforeNavigate: (page) => deadline?.preparePage(page),browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),});chromeBrowser = session.browser;@@ -304,12 +322,31 @@ export async function captureFindingCrops(written.push(join(snapshotDir, request.filename));}return written;+ } catch (error) {+ failure = { kind: "failed", error };+ throw error;} finally {- await chromeBrowser?.close().catch(() => undefined);- await server.close();+ await closeCheckResources(chromeBrowser, server, failure);}}+async function closeCheckResources(+ browser: Browser | undefined,+ server: { close(): Promise<void> },+ failure: { kind: "none" } | { kind: "failed"; error: unknown },+): Promise<void> {+ const cleanup = await Promise.allSettled([+ browser ? closeManagedBrowser(browser) : Promise.resolve(),+ server.close(),+ ]);+ const errors = cleanup+ .filter((entry) => entry.status === "rejected")+ .map((entry) => entry.reason);+ if (errors.length === 0) return;+ if (failure.kind === "failed") errors.unshift(failure.error);+ throw new BrowserCleanupError(errors, errors.map(normalizeErrorMessage).join("; "));+}+// `swapToProxy` / `emitUnavailableDiagnostic` (packages/core/src/runtime/// mediaProxy.ts) embed their stable diagnostic codes in the console.info line// precisely so this scraper can match a token instead of prose. Matching thediff --git a/packages/cli/src/utils/checkDeadline.fixture.ts b/packages/cli/src/utils/checkDeadline.fixture.tsnew file mode 100644index 0000000000..a9c5dab4aa--- /dev/null+++ b/packages/cli/src/utils/checkDeadline.fixture.ts@@ -0,0 +1,104 @@+// fallow-ignore-file unused-file+import { existsSync, readFileSync, writeFileSync } from "node:fs";+import puppeteer from "puppeteer-core";+import { testProcessIsAlive, testProcessDescendants } from "./processTestUtils.js";++// Accelerate the hang after the independent authored marker confirms browser startup.+// Production still budgets startup; the unit test verifies that shared deadline.+const realSetTimeout = globalThis.setTimeout;+let armDeadline: (() => void) | undefined;+globalThis.setTimeout = ((+ callback: (...args: unknown[]) => void,+ delay?: number,+ ...args: unknown[]+) => {+ const timer = realSetTimeout(callback, delay, ...args);+ if (delay === 120_000) {+ armDeadline = () => {+ clearTimeout(timer);+ realSetTimeout(callback, 4_000, ...args);+ armDeadline = undefined;+ };+ }+ return timer;+}) as typeof setTimeout;+const pidFile = process.env.HF_TEST_BROWSER_PID_FILE;+if (!pidFile) throw new Error("Missing browser PID file");+// Observe cleanup when the command presents its report, before any exit hook runs.+const log = console.log.bind(console);+console.log = (...args: unknown[]) => {+ const [message] = args;+ if (typeof message === "string" && message.startsWith('{\n "ok"') && existsSync(pidFile)) {+ const pid = Number(readFileSync(pidFile, "utf8"));+ writeFileSync(`${pidFile}.report-browser-alive`, String(testProcessIsAlive(pid)));+ }+ log(...args);+};+const launch = puppeteer.launch.bind(puppeteer);+puppeteer.launch = async (options) => {+ const browser = await launch(options);+ const browserProcess = browser.process();+ const profile = browserProcess?.spawnargs.find((arg) => arg.startsWith("--user-data-dir="));+ if (!profile) throw new Error("Browser did not expose its profile");+ writeFileSync(`${pidFile}.profile`, profile.slice("--user-data-dir=".length));+ const pid = browserProcess?.pid;+ if (!pid) throw new Error("Browser did not expose its process");+ writeFileSync(pidFile, String(pid));+ const newPage = browser.newPage.bind(browser);+ browser.newPage = async () => {+ const page = await newPage();+ page.on("console", (message) => {+ if (message.text() === "HF_TEST_SCRIPT_START") {+ writeFileSync(`${pidFile}.script`, "started");+ if (process.platform === "linux") {+ writeFileSync(+ `${pidFile}.tree`,+ JSON.stringify({+ pid,+ alive: testProcessIsAlive(pid),+ descendants: testProcessDescendants(pid),+ }),+ );+ }+ armDeadline?.();+ }+ });+ return page;+ };+ return browser;+};+if (process.env.HF_TEST_DISTINCT_PROFILES === "1") {+ const { ensureBrowser } = await import("../browser/manager.js");+ const { launchManagedBrowser, closeManagedBrowser } = await import("../browser/launch.js");+ const { executablePath } = await ensureBrowser();+ const options = {+ executablePath,+ headless: true,+ args: ["--no-sandbox"],+ } as const;+ const first = await launchManagedBrowser(puppeteer, {+ ...options,+ args: [...options.args],+ });+ try {+ const firstProfile = readFileSync(`${pidFile}.profile`, "utf8");+ const firstPid = first.process()?.pid;+ if (!firstPid) throw new Error("First browser has no process");+ const second = await launchManagedBrowser(puppeteer, {+ ...options,+ args: [...options.args],+ });+ try {+ writeFileSync(`${pidFile}.first-alive`, String(testProcessIsAlive(firstPid)));+ writeFileSync(+ `${pidFile}.profiles`,+ JSON.stringify([firstProfile, readFileSync(`${pidFile}.profile`, "utf8")]),+ );+ } finally {+ await closeManagedBrowser(second);+ }+ } finally {+ await closeManagedBrowser(first);+ }+}+await import("../cli.js");diff --git a/packages/cli/src/utils/checkDeadline.process.test.ts b/packages/cli/src/utils/checkDeadline.process.test.tsnew file mode 100644index 0000000000..bf44972dfa--- /dev/null+++ b/packages/cli/src/utils/checkDeadline.process.test.ts@@ -0,0 +1,180 @@+import { spawn } from "node:child_process";+import { existsSync, mkdtempSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";+import { rm } from "node:fs/promises";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { fileURLToPath } from "node:url";+import { expect, it, onTestFinished } from "vitest";+import Ajv from "ajv/dist/jtd.js";+import type { JTDDataType } from "ajv/dist/jtd.js";+import { terminateProcessTree } from "./processTree.js";+import { stopTestProcesses, testProcessIsAlive } from "./processTestUtils.js";++const reportSchema = {+ properties: {+ ok: { type: "boolean" },+ runtime: {+ properties: { findings: { elements: {} } },+ additionalProperties: true,+ },+ },+ additionalProperties: true,+} as const;+const treeSchema = {+ properties: {+ pid: { type: "uint32" },+ alive: { type: "boolean" },+ descendants: { elements: { type: "uint32" } },+ },+} as const;+const profilesSchema = { elements: { type: "string" } } as const;+const parser = new Ajv();+const parseProfiles = parser.compileParser<JTDDataType<typeof profilesSchema>>(profilesSchema);+const parseReport = parser.compileParser<JTDDataType<typeof reportSchema>>(reportSchema);+const parseTree = parser.compileParser<JTDDataType<typeof treeSchema>>(treeSchema);++function readPid(path: string): number {+ const pid = Number(readFileSync(path, "utf8"));+ if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Invalid browser PID");+ return pid;+}++function readTree(path: string): JTDDataType<typeof treeSchema> {+ const tree = parseTree(readFileSync(path, "utf8"));+ if (!tree || tree.pid === 0 || tree.descendants.includes(0)) {+ throw new Error("Invalid process-tree snapshot");+ }+ return tree;+}++function writeHangProject(dir: string): void {+ mkdirSync(join(dir, "compositions"));+ writeFileSync(+ join(dir, "index.html"),+ `<!doctype html><html><body>+<div data-composition-id="main" data-width="320" data-height="180" data-duration="1">+<div data-composition-id="hang" data-composition-src="compositions/hang.html" data-start="0" data-duration="1"></div>+</div><script>window.__timelines.main={duration:()=>1,seek:()=>{},pause:()=>{}};</script></body></html>`,+ );+ writeFileSync(+ join(dir, "compositions/hang.html"),+ `<template id="hang">+<div data-composition-id="hang"><div id="box" style="width:1px;height:1px"></div>+<script>console.debug("HF_TEST_SCRIPT_START");const el=document.getElementById("box");while(el.offsetWidth<2){el.style.height="1px";}</script>+</div></template>`,+ );+}++it(+ "check returns file-specific JSON, exit 1, and a stopped browser",+ () => runWitness(false),+ 60_000,+);+// This extra witness reads Linux /proc and its zombie states, unavailable on Windows and macOS.+it.skipIf(process.platform !== "linux")(+ "Linux /proc records live descendants that check stops",+ () => runWitness(true),+ 60_000,+);++it(+ "managed launches own distinct profiles while the first browser is alive",+ () => runWitness(false, true),+ 60_000,+);++async function runWitness(inspectLinuxTree: boolean, inspectProfiles = false): Promise<void> {+ const dir = mkdtempSync(join(tmpdir(), "hf-check-deadline-"));+ const pidFile = join(dir, "browser.pid");+ writeHangProject(dir);+ const fixture = join(dirname(fileURLToPath(import.meta.url)), "checkDeadline.fixture.ts");+ const child = spawn(+ process.execPath,+ [+ "--import",+ "tsx",+ fixture,+ "check",+ "--json",+ "--no-browser-gpu",+ "--timeout=500",+ "--samples=1",+ dir,+ ],+ {+ env: {+ ...process.env,+ HF_TEST_BROWSER_PID_FILE: pidFile,+ HF_TEST_DISTINCT_PROFILES: inspectProfiles ? "1" : "0",+ },+ stdio: ["ignore", "pipe", "pipe"],+ },+ );+ let output = "";+ let stdout = "";+ child.stdout.on("data", (data: Buffer) => {+ output += data.toString();+ stdout += data.toString();+ });+ child.stderr.on("data", (data: Buffer) => {+ output += data.toString();+ });+ const done = new Promise<number | null>((resolve) => child.once("close", resolve));+ onTestFinished(async () => {+ const exited = () => child.exitCode !== null || child.signalCode !== null;+ let terminationFailure: unknown;+ try {+ if (child.pid && !exited()) {+ await terminateProcessTree(child.pid, {+ child,+ spawnProcess: (command, args, options) =>+ spawn(command, args, { ...options, timeout: 5_000 }),+ });+ }+ } catch (error) {+ if (!exited()) terminationFailure = error;+ } finally {+ const pid = existsSync(pidFile) ? readPid(pidFile) : undefined;+ const descendants = existsSync(`${pidFile}.tree`)+ ? readTree(`${pidFile}.tree`).descendants+ : [];+ await stopTestProcesses(child, [...descendants, ...(pid === undefined ? [] : [pid])]);+ }+ if (terminationFailure !== undefined) throw terminationFailure;+ await rm(dir, {+ recursive: true,+ force: true,+ maxRetries: 10,+ retryDelay: 100,+ });+ });+ expect(await done, output).toBe(1);+ const report = parseReport(stdout.slice(stdout.indexOf('{\n "ok"')));+ if (!report) throw new Error(`Invalid check JSON: ${output}`);+ expect(report.ok).toBe(false);+ expect(report.runtime.findings).toContainEqual(+ expect.objectContaining({+ severity: "error",+ sourceFile: "compositions/hang.html",+ message: expect.stringContaining("script did not finish"),+ }),+ );+ const browserPid = readPid(pidFile);+ expect(testProcessIsAlive(browserPid)).toBe(false);+ if (inspectProfiles) {+ expect(readFileSync(`${pidFile}.first-alive`, "utf8")).toBe("true");+ const profiles = parseProfiles(readFileSync(`${pidFile}.profiles`, "utf8"));+ expect(profiles).toHaveLength(2);+ expect(new Set(profiles).size).toBe(2);+ }+ expect(readFileSync(`${pidFile}.profile`, "utf8")).not.toBe(join(dir, "profile"));+ expect(readFileSync(`${pidFile}.report-browser-alive`, "utf8")).toBe("false");+ expect(readFileSync(`${pidFile}.script`, "utf8")).toBe("started");+ if (inspectLinuxTree) {+ const snapshot = readTree(`${pidFile}.tree`);+ expect(snapshot.pid).toBe(browserPid);+ expect(snapshot.alive).toBe(true);+ expect(snapshot.descendants.length).toBeGreaterThan(0);+ expect(snapshot.descendants.every((pid) => !testProcessIsAlive(pid))).toBe(true);+ }+}diff --git a/packages/cli/src/utils/checkDeadline.test.ts b/packages/cli/src/utils/checkDeadline.test.tsnew file mode 100644index 0000000000..b14a07894d--- /dev/null+++ b/packages/cli/src/utils/checkDeadline.test.ts@@ -0,0 +1,95 @@+import { afterEach, expect, it, vi } from "vitest";+import { CheckDeadline, CheckDeadlineError } from "./checkDeadline.js";++afterEach(() => vi.useRealTimers());++function rejectOnAbort(signal: AbortSignal): Promise<never> {+ return new Promise((_, reject) => {+ signal.addEventListener("abort", () => reject(signal.reason), {+ once: true,+ });+ });+}++it("readiness and later sampling spend one 120-second budget", async () => {+ vi.useFakeTimers();+ const deadline = new CheckDeadline();+ deadline.start();+ try {+ await deadline.run(async () => "ready");+ await vi.advanceTimersByTimeAsync(90_000);+ const sample = deadline.run(() => rejectOnAbort(deadline.signal));+ const failed = expect(sample).rejects.toBeInstanceOf(CheckDeadlineError);+ await vi.advanceTimersByTimeAsync(30_000);+ await failed;+ expect(deadline.signal.aborted).toBe(true);+ } finally {+ await deadline.close();+ }+});++it("an expired check does not start its crop browser", async () => {+ vi.useFakeTimers();+ const deadline = new CheckDeadline();+ deadline.start();+ try {+ const audit = deadline.run(() => rejectOnAbort(deadline.signal));+ const failed = expect(audit).rejects.toBeInstanceOf(CheckDeadlineError);+ await vi.advanceTimersByTimeAsync(120_000);+ await failed;+ const crop = vi.fn(async () => []);+ await expect(deadline.run(crop)).rejects.toBeInstanceOf(CheckDeadlineError);+ expect(crop).not.toHaveBeenCalled();+ } finally {+ await deadline.close();+ }+});++it("cleanup is bounded even when a losing operation ignores cancellation", async () => {+ vi.useFakeTimers();+ const deadline = new CheckDeadline();+ deadline.start();+ const audit = deadline.run(() => new Promise(() => {}));+ const failed = expect(audit).rejects.toBeInstanceOf(CheckDeadlineError);+ await vi.advanceTimersByTimeAsync(120_000);+ await failed;+ const closing = expect(deadline.close()).rejects.toThrow("draining check cleanup");+ await vi.advanceTimersByTimeAsync(1_000);+ await closing;+}, 2_000);++it("browser provisioning does not spend the check budget, which starts once when ready", async () => {+ vi.useFakeTimers();+ const deadline = new CheckDeadline();+ let complete!: () => void;+ const work = new Promise<void>((resolve) => {+ complete = resolve;+ });+ const outcome = deadline.run(() => work).catch((error: unknown) => error);+ try {+ await vi.advanceTimersByTimeAsync(150_000);+ expect(deadline.signal.aborted).toBe(false);+ deadline.start();+ await vi.advanceTimersByTimeAsync(90_000);+ deadline.start();+ await vi.advanceTimersByTimeAsync(29_999);+ expect(deadline.signal.aborted).toBe(false);+ await vi.advanceTimersByTimeAsync(1);+ expect(deadline.signal.aborted).toBe(true);+ expect(await outcome).toBeInstanceOf(CheckDeadlineError);+ } finally {+ complete();+ await outcome;+ await deadline.close();+ }+});++it("closing before browser readiness prevents a later clock from starting", async () => {+ vi.useFakeTimers();+ const deadline = new CheckDeadline();+ await deadline.close();+ deadline.start();+ await vi.advanceTimersByTimeAsync(150_000);+ expect(vi.getTimerCount()).toBe(0);+ expect(deadline.signal.aborted).toBe(false);+});diff --git a/packages/cli/src/utils/checkDeadline.ts b/packages/cli/src/utils/checkDeadline.tsnew file mode 100644index 0000000000..7ba94cae70--- /dev/null+++ b/packages/cli/src/utils/checkDeadline.ts@@ -0,0 +1,105 @@+import type { Browser, Page } from "puppeteer-core";+import { normalizeErrorMessage } from "./errorMessage.js";+import { withRemainingBudget } from "../capture/captureTimeout.js";+import { BrowserCleanupError, closeManagedBrowser } from "../browser/launch.js";++const CHECK_DEADLINE_MS = 120_000;+const SCRIPT_START = "[hyperframes:script:start] ";+const SCRIPT_FINISH = "[hyperframes:script:finish] ";++export class CheckDeadlineError extends Error {+ constructor(readonly sourceFile?: string) {+ super(+ sourceFile === undefined+ ? "Check did not finish within its deadline."+ : `${sourceFile}: its script did not finish within the check deadline.`,+ );+ }+}++/** One Node clock starts at the composition browser and spans readiness, sampling and crops. */+export class CheckDeadline {+ private readonly abort = new AbortController();+ private readonly operations = new Set<Promise<unknown>>();+ readonly signal = this.abort.signal;+ private readonly browsers = new Set<Browser>();+ private readonly scripts: string[] = [];+ private expired: CheckDeadlineError | undefined;+ private timer: NodeJS.Timeout | undefined;+ private readonly expiry: Promise<never>;+ private rejectExpiry!: (error: CheckDeadlineError) => void;+ private phase: "waiting" | "started" | "closed" = "waiting";++ constructor() {+ this.expiry = new Promise((_, reject) => {+ this.rejectExpiry = reject;+ });+ }++ start = (): void => {+ if (this.phase !== "waiting") return;+ this.phase = "started";+ this.timer = setTimeout(() => {+ this.expired = new CheckDeadlineError(this.scripts.at(-1));+ this.rejectExpiry(this.expired);+ this.abort.abort(this.expired);+ }, CHECK_DEADLINE_MS);+ };++ ownBrowser = (browser: Browser): void => {+ if (this.expired) throw this.expired;+ if (this.phase === "closed") throw new Error("Check has already finished.");+ this.browsers.add(browser);+ };++ async preparePage(page: Page): Promise<void> {+ page.on("console", (message) => {+ const text = message.text();+ if (text.startsWith(SCRIPT_START)) this.scripts.push(text.slice(SCRIPT_START.length));+ if (text.startsWith(SCRIPT_FINISH)) {+ const index = this.scripts.lastIndexOf(text.slice(SCRIPT_FINISH.length));+ if (index !== -1) this.scripts.splice(index, 1);+ }+ });+ await page.evaluateOnNewDocument(+ (start, finish) => {+ Reflect.set(window, "__hfScriptState", (phase: "start" | "finish", source: string) => {+ console.debug((phase === "start" ? start : finish) + source);+ });+ },+ SCRIPT_START,+ SCRIPT_FINISH,+ );+ }++ run<T>(operation: () => Promise<T>): Promise<T> {+ if (this.expired) return Promise.reject(this.expired);+ const pending = operation();+ this.operations.add(pending);+ return Promise.race([pending, this.expiry]);+ }++ async close(): Promise<void> {+ this.phase = "closed";+ clearTimeout(this.timer);+ const closes = await Promise.allSettled([...this.browsers].map(closeManagedBrowser));+ const errors = closes+ .filter((entry) => entry.status === "rejected")+ .map((entry) => entry.reason);+ try {+ const drained = await withRemainingBudget(+ Promise.allSettled(this.operations),+ 1_000,+ "draining check cleanup",+ );+ for (const entry of drained) {+ if (entry.status === "rejected" && entry.reason instanceof BrowserCleanupError)+ errors.push(entry.reason);+ }+ } catch (error) {+ errors.push(error);+ }+ if (errors.length > 0)+ throw new BrowserCleanupError(errors, errors.map(normalizeErrorMessage).join("; "));+ }+}diff --git a/packages/cli/src/utils/checkPipeline.ts b/packages/cli/src/utils/checkPipeline.tsindex 2ea601b752..e4d06f751f 100644--- a/packages/cli/src/utils/checkPipeline.ts+++ b/packages/cli/src/utils/checkPipeline.ts@@ -1,3 +1,5 @@+import { BrowserCleanupError } from "../browser/launch.js";+import { CheckDeadline, CheckDeadlineError } from "./checkDeadline.js";import { checkSnapshotDirectory } from "./checkSnapshotDirectory.js";import { findingElementKey, groupSampledFindings } from "./checkFindings.js";import { mkdirSync, writeFileSync } from "node:fs";@@ -1275,30 +1277,62 @@ export async function runCheckPipeline(]: [];- let browser: CheckBrowserResult;+ const deadline = new CheckDeadline();+ let outcome: { kind: "report"; report: CheckReport } | { kind: "failed"; error: unknown };try {- browser = await dependencies.runBrowserCheck(project, options, motion);+ let browser: CheckBrowserResult;+ try {+ browser = await deadline.run(() =>+ dependencies.runBrowserCheck(project, options, motion, deadline),+ );+ } catch (error) {+ browser = emptyBrowserResult();+ browser.runtimeFindings.push(runtimeFailure(error));+ }++ const snapshotFiles = options.snapshots+ ? await writeContrastSnapshots(dependencies, project.dir, browser)+ : [];+ const report = buildReport(+ options,+ lint,+ browser,+ motion,+ specFindings,+ snapshotFiles,+ hdrPromotion,+ hdrInspection,+ );+ outcome = {+ kind: "report",+ report: options.snapshots+ ? await withFindingCrops(dependencies, project, options, report, deadline)+ : report,+ };} catch (error) {- browser = emptyBrowserResult();- browser.runtimeFindings.push(runtimeFailure(error));+ outcome = { kind: "failed", error };}-- const snapshotFiles = options.snapshots- ? await writeContrastSnapshots(dependencies, project.dir, browser)- : [];- const report = buildReport(- options,- lint,- browser,- motion,- specFindings,- snapshotFiles,- hdrPromotion,- hdrInspection,- );- return options.snapshots- ? await withFindingCrops(dependencies, project, options, report)- : report;+ try {+ await deadline.close();+ } catch (error) {+ if (outcome.kind === "failed") {+ throw new BrowserCleanupError(+ [outcome.error, error],+ `${normalizeErrorMessage(outcome.error)}; ${normalizeErrorMessage(error)}`,+ );+ }+ const report = outcome.report;+ return {+ ...report,+ ok: false,+ runtime: section([+ ...report.runtime.findings,+ runtimeFailure(error, "check_cleanup_failure"),+ ]),+ };+ }+ if (outcome.kind === "failed") throw outcome.error;+ return outcome.report;}/** Persists the contrast pass's already-captured overview PNGs (or the@@ -1330,13 +1364,20 @@ async function withFindingCrops(project: ProjectDir,options: CheckOptions,report: CheckReport,+ deadline: CheckDeadline,): Promise<CheckReport> {const cropRequests = selectFindingCropRequests(report);if (cropRequests.length === 0) return report;try {- const findingFiles = await dependencies.captureFindingCrops(project, options, cropRequests);+ const findingFiles = await deadline.run(() =>+ dependencies.captureFindingCrops(project, options, cropRequests, deadline),+ );return { ...report, snapshots: { ...report.snapshots, findingFiles } };} catch (error) {+ if (error instanceof CheckDeadlineError) {+ const finding = runtimeFailure(error);+ return { ...report, ok: false, runtime: section([...report.runtime.findings, finding]) };+ }// Still non-gating, but observable: rollouts need the crop-failure rate// (a second Chrome launch failing/timing out) without failing the run.console.error(" finding crops skipped: " + normalizeErrorMessage(error));@@ -1682,7 +1723,12 @@ function emptyBrowserResult(): CheckBrowserResult {}function runtimeFailure(error: unknown, code = "check_runtime_failure"): CheckFinding {- return findingAtRoot(code, "error", normalizeErrorMessage(error), "index.html");+ return findingAtRoot(+ code,+ "error",+ normalizeErrorMessage(error),+ error instanceof CheckDeadlineError ? (error.sourceFile ?? "index.html") : "index.html",+ );}function findingAtRoot(@@ -1737,11 +1783,12 @@ async function runBrowserCheck(project: ProjectDir,options: CheckOptions,motion: MotionSpecResolution,+ deadline?: CheckDeadline,): Promise<CheckBrowserResult> {const module = await import("./checkBrowser.js");// runAuditGrid is handed over as a callback so checkBrowser never imports// this module back (no import cycle).- return module.runBrowserCheck(project, options, motion, runAuditGrid);+ return module.runBrowserCheck(project, options, motion, runAuditGrid, deadline);}async function writeSnapshot(@@ -1762,10 +1809,11 @@ async function captureFindingCrops(project: ProjectDir,options: CheckOptions,requests: CheckFindingCropRequest[],+ deadline?: CheckDeadline,): Promise<string[]> {const module = await import("./checkBrowser.js");// Handed over the same way runBrowserCheck is (checkBrowser never imports this module back).- return module.captureFindingCrops(project, options, requests);+ return module.captureFindingCrops(project, options, requests, deadline);}const DEFAULT_DEPENDENCIES: CheckDependencies = {diff --git a/packages/cli/src/utils/checkTypes.ts b/packages/cli/src/utils/checkTypes.tsindex 9bcc9e6b26..23bc2fd063 100644--- a/packages/cli/src/utils/checkTypes.ts+++ b/packages/cli/src/utils/checkTypes.ts@@ -1,3 +1,4 @@+import type { CheckDeadline } from "./checkDeadline.js";import type { ProjectLintResult } from "./lintProject.js";import type { LayoutIssue, LayoutOverflow, LayoutRect } from "./layoutAudit.js";import type { Canvas, MotionFrame } from "./motionAudit.js";@@ -313,6 +314,7 @@ export interface CheckDependencies {project: ProjectDir,options: CheckOptions,motion: MotionSpecResolution,+ deadline?: CheckDeadline,): Promise<CheckBrowserResult>;writeSnapshot(projectDir: string,@@ -324,6 +326,7 @@ export interface CheckDependencies {project: ProjectDir,options: CheckOptions,requests: CheckFindingCropRequest[],+ deadline?: CheckDeadline,): Promise<string[]>;inspectHdrAutoPromotion?(project: ProjectDir): Promise<CheckReport["hdr"]["autoPromotion"]>;}diff --git a/packages/cli/src/utils/processTestUtils.ts b/packages/cli/src/utils/processTestUtils.tsindex 7c3692d95b..19c5998ab0 100644--- a/packages/cli/src/utils/processTestUtils.ts+++ b/packages/cli/src/utils/processTestUtils.ts@@ -1,4 +1,5 @@-import { readFileSync } from "node:fs";+import type { ChildProcess } from "node:child_process";+import { readFileSync, readdirSync } from "node:fs";export function testProcessIsAlive(pid: number): boolean {if (process.platform === "linux") {@@ -25,3 +26,41 @@ export async function waitForTestCondition(check: () => boolean, timeoutMs: numbawait new Promise((resolve) => setTimeout(resolve, 20));}}++export function testProcessDescendants(parentPid: number): number[] {+ const parents = new Map<number, number>();+ for (const name of readdirSync("/proc")) {+ if (!/^\d+$/.test(name)) continue;+ try {+ const stat = readFileSync(`/proc/${name}/stat`, "utf8");+ parents.set(Number(name), Number(stat.slice(stat.lastIndexOf(") ") + 2).split(" ")[1]));+ } catch {}+ }+ const owned = new Set([parentPid]);+ for (const pid of owned) {+ for (const [child, parent] of parents) if (parent === pid) owned.add(child);+ }+ return [...owned].filter((pid) => pid !== parentPid);+}++export async function stopTestProcesses(+ root: ChildProcess,+ ownedPids: readonly number[],+): Promise<void> {+ const rootExited = () => root.exitCode !== null || root.signalCode !== null;+ if (!rootExited()) {+ root.kill("SIGTERM");+ await waitForTestCondition(rootExited, 5_000).catch(() => undefined);+ }+ try {+ for (const pid of ownedPids) {+ if (testProcessIsAlive(pid)) process.kill(pid, "SIGKILL");+ }+ await waitForTestCondition(() => ownedPids.every((pid) => !testProcessIsAlive(pid)), 5_000);+ } finally {+ if (!rootExited()) {+ root.kill("SIGKILL");+ await waitForTestCondition(rootExited, 5_000);+ }+ }+}diff --git a/packages/core/src/compiler/compositionScoping.test.ts b/packages/core/src/compiler/compositionScoping.test.tsindex 655e63dcda..dbca7a6916 100644--- a/packages/core/src/compiler/compositionScoping.test.ts+++ b/packages/core/src/compiler/compositionScoping.test.ts@@ -11,6 +11,38 @@ import {} from "./compositionScoping";describe("composition scoping", () => {+ it("reports the child source before authored code and finishes after a thrown script", () => {+ const { document } = parseHTML('<main data-composition-id="scene"></main>');+ const events: string[] = [];+ const fakeWindow = {+ document,+ __timelines: {},+ events,+ __hfScriptState: (phase: string, source: string) => events.push(`${phase}:${source}`),+ };+ const error = vi.spyOn(console, "error").mockImplementation(() => {});+ try {+ const wrapped = wrapScopedCompositionScript(+ 'window.events.push("body"); throw new Error("authored failure");',+ "scene",+ undefined,+ undefined,+ undefined,+ undefined,+ "compositions/scene.html",+ );+ new Function("window", wrapped)(fakeWindow);+ expect(events).toEqual([+ "start:compositions/scene.html",+ "body",+ "finish:compositions/scene.html",+ ]);+ expect(error).toHaveBeenCalledOnce();+ } finally {+ error.mockRestore();+ }+ });+it("scopes regular selectors while preserving global at-rules", () => {const scoped = scopeCssToComposition(`diff --git a/packages/core/src/compiler/compositionScoping.ts b/packages/core/src/compiler/compositionScoping.tsindex bb885231e2..703a6e5aaa 100644--- a/packages/core/src/compiler/compositionScoping.ts+++ b/packages/core/src/compiler/compositionScoping.ts@@ -571,12 +571,16 @@ export function wrapScopedCompositionScript(var __hfBaseHyperframes = window.__hyperframes;var __hfScopedHyperframes = ${SCOPED_HYPERFRAMES_EXPRESSION};var __hfRun = function() {+ var report = window.__hfScriptState;+ if (typeof report === "function") report("start", __hfCompositionSrc || "index.html");try {(function(document, gsap, window, __hyperframes) {${source.replace(/<\/(script)/gi, "<\\/$1")}}).call(window, __hfScopedDocument, __hfScopedGsap, __hfScopedWindow, __hfScopedHyperframes);} catch (_err) {console.error(__hfErrorLabel, __hfCompId, _err);+ } finally {+ if (typeof report === "function") report("finish", __hfCompositionSrc || "index.html");}};// What the script started on the global gsap timeline, by any route, for a scene swap to revert.diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.tsindex 49ff970f48..cd2325ed3c 100644--- a/packages/engine/src/index.ts+++ b/packages/engine/src/index.ts@@ -95,6 +95,7 @@ export {WebGpuUnavailableError,ENABLE_BROWSER_POOL,BrowserLeasePool,+ type GpuProbeLifecycle,type BuildChromeArgsOptions,type BrowserLaunchFingerprint,type BrowserLease,diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.tsindex c31e429794..50acb9a876 100644--- a/packages/engine/src/services/browserManager.test.ts+++ b/packages/engine/src/services/browserManager.test.ts@@ -379,6 +379,21 @@ describe("resolveBrowserGpuMode", () => {_resetAutoBrowserGpuModeCacheForTests();});+ it("lets a host own GPU probe launch and cleanup", async () => {+ const { launch } = setMockWebGlProbe({ hasWebGL: true, vendor: "NVIDIA", renderer: "NVIDIA" });+ const close = vi.fn(async (browser: Browser) => {+ await browser.close();+ });+ const managedLaunch = vi.fn(+ async (ppt: PuppeteerNode, options: Parameters<PuppeteerNode["launch"]>[0]) =>+ ppt.launch(options),+ );+ await resolveBrowserGpuMode("auto", { probeLifecycle: { launch: managedLaunch, close } });+ expect(managedLaunch).toHaveBeenCalledOnce();+ expect(launch).toHaveBeenCalledOnce();+ expect(close).toHaveBeenCalledOnce();+ });+it("passes 'software' through unchanged without probing", async () => {const mode = await resolveBrowserGpuMode("software");expect(mode).toBe("software");diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.tsindex f954af7002..c1cd877248 100644--- a/packages/engine/src/services/browserManager.ts+++ b/packages/engine/src/services/browserManager.ts@@ -7,7 +7,7 @@*/import { scanHtmlOpeningTags } from "@hyperframes/parsers/html-attribute-spans";-import type { Browser, Page, PuppeteerNode } from "puppeteer-core";+import type { Browser, LaunchOptions, Page, PuppeteerNode } from "puppeteer-core";import { execSync } from "child_process";import { existsSync, readdirSync, statSync } from "fs";import { join } from "path";@@ -73,6 +73,18 @@ async function getPuppeteer(): Promise<PuppeteerNode> {return _puppeteer;}+export interface GpuProbeLifecycle {+ launch(puppeteer: PuppeteerNode, options: LaunchOptions): Promise<Browser>;+ close(browser: Browser): Promise<void>;+}++interface GpuProbeOptions {+ chromePath?: string;+ browserTimeout?: number;+ platform?: NodeJS.Platform;+ probeLifecycle?: GpuProbeLifecycle;+}+const GPU_PROBE_TIMEOUT_MS = 15_000;async function probeHardwareWebGlInfo(@@ -81,11 +93,12 @@ async function probeHardwareWebGlInfo(args: string[];browserTimeout: number;executablePath: string | undefined;+ probeLifecycle?: GpuProbeLifecycle;},): Promise<WebGlProbeInfo> {let probeBrowser: Browser | undefined;try {- probeBrowser = await ppt.launch({+ const launchOptions: LaunchOptions = {...sigintLaunchOptions(),headless: true,args: options.args,@@ -93,14 +106,20 @@ async function probeHardwareWebGlInfo(executablePath: options.executablePath,timeout: options.browserTimeout,waitForInitialPage: false,- });+ };+ probeBrowser = options.probeLifecycle+ ? await options.probeLifecycle.launch(ppt, launchOptions)+ : await ppt.launch(launchOptions);return await rejectAfter(readWebGlInfo(probeBrowser),GPU_PROBE_TIMEOUT_MS,`GPU probe page did not answer within ${GPU_PROBE_TIMEOUT_MS}ms`,);} finally {- if (probeBrowser) await closeBrowserAfterFailedProbe(probeBrowser);+ if (probeBrowser) {+ if (options.probeLifecycle) await options.probeLifecycle.close(probeBrowser);+ else await closeBrowserAfterFailedProbe(probeBrowser);+ }}}@@ -531,11 +550,7 @@ function formatProbeFailure(err: unknown): string {return `probe failed (${err instanceof Error ? err.message : String(err)})`;}-async function probeAutoBrowserGpuMode(options: {- chromePath?: string;- browserTimeout?: number;- platform?: NodeJS.Platform;-}): Promise<GpuProbeOutcome> {+async function probeAutoBrowserGpuMode(options: GpuProbeOptions): Promise<GpuProbeOutcome> {const platform = options.platform ?? process.platform;const browserTimeout = options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout;const executablePath = options.chromePath ?? resolveHeadlessShellPath({});@@ -551,6 +566,7 @@ async function probeAutoBrowserGpuMode(options: {args: getHardwareGpuProbeArgs(platform),browserTimeout,executablePath,+ probeLifecycle: options.probeLifecycle,});const resolved = resolveWebGlProbeMode(info);logResolvedBrowserGpuMode(resolved, describeWebGlProbe(info));@@ -589,11 +605,7 @@ async function probeAutoBrowserGpuMode(options: {*/export function resolveBrowserGpuMode(mode: EngineConfig["browserGpuMode"],- options: {- chromePath?: string;- browserTimeout?: number;- platform?: NodeJS.Platform;- } = {},+ options: GpuProbeOptions = {},): Promise<"software" | "hardware"> {if (mode === "software") return Promise.resolve(mode);