Skip to content

Write HTML. Render video. Built for agents.

fix(cli): bound checks of non-finishing compositions (#5537)

Miguel Ángelc96099d39a12
diff --git a/.github/workflows/windows-render.yml b/.github/workflows/windows-render.yml
index 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}' build
bun 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_shard
shell: pwsh
diff --git a/packages/cli/scripts/prepare-process-test-browser.mjs b/packages/cli/scripts/prepare-process-test-browser.mjs
new file mode 100644
index 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.ts
index 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 in
diff --git a/packages/cli/src/browser/launch.ts b/packages/cli/src/browser/launch.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 the
diff --git a/packages/cli/src/utils/checkDeadline.fixture.ts b/packages/cli/src/utils/checkDeadline.fixture.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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: numb
await 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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);