diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index dcfce67382..d2c2134aa5 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -1552,6 +1552,15 @@ npx hyperframes browser clear # remove the cached download `$(npx hyperframes browser path)`. Use `--force` when a download was interrupted and left a partial file behind. +A host can supply its own Chromium launcher instead. Set +`HYPERFRAMES_BROWSER_LAUNCHER` to an ES module that exports +`launch(options, puppeteer)` and returns a Puppeteer `Browser` whose `process()` +is the browser it started. Every render, check and snapshot then starts its +browser through that module, and nothing is downloaded. The launcher takes +precedence over `HYPERFRAMES_BROWSER_PATH` and `PRODUCER_HEADLESS_SHELL_PATH`. +Its browser is never headless-shell, so it does not use BeginFrame capture. +When the variable is unset, browsers start as they always have. + ### `docs` Read documentation in the terminal. diff --git a/packages/cli/src/browser/launch.ts b/packages/cli/src/browser/launch.ts index 2cda8a9388..d55f3b028d 100644 --- a/packages/cli/src/browser/launch.ts +++ b/packages/cli/src/browser/launch.ts @@ -1,4 +1,5 @@ import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core"; +import { launchRenderBrowser } from "@hyperframes/engine/chrome-host-ceiling"; import { resolveCaptureBrowserGpuMode, type BrowserGpuMode, @@ -117,7 +118,13 @@ async function launchOwnedBrowser( const signal = options.signal ? AbortSignal.any([options.signal, abort.signal]) : abort.signal; const launchedAt = Date.now(); const launch = untilLaunchOrAbort( - puppeteer.launch({ ...options, pipe: true, signal, handleSIGINT: false, handleSIGTERM: false }), + launchRenderBrowser(puppeteer, { + ...options, + pipe: true, + signal, + handleSIGINT: false, + handleSIGTERM: false, + }), signal, ); const limit = options.timeout ?? LAUNCH_TIMEOUT_MS; diff --git a/packages/cli/src/browser/manager.test.ts b/packages/cli/src/browser/manager.test.ts index 1164d0ecd6..510845e0a3 100644 --- a/packages/cli/src/browser/manager.test.ts +++ b/packages/cli/src/browser/manager.test.ts @@ -273,6 +273,7 @@ describe("findBrowser — cache resolution", () => { value: "x64", configurable: true, }); + delete process.env["HYPERFRAMES_BROWSER_LAUNCHER"]; delete process.env["HYPERFRAMES_BROWSER_PATH"]; delete process.env["PRODUCER_HEADLESS_SHELL_PATH"]; installChildProcessMocks(); @@ -1196,6 +1197,21 @@ describe("findBrowser — cache resolution", () => { expect(result?.source).toBe("env"); }); + it("returns a launcher module over both paths, with nothing looked up or downloaded", async () => { + const hfPath = "/opt/hf/chrome-headless-shell"; + installFsMocks({ existing: new Set([hfPath]) }); + installPuppeteerBrowsersMock(); + process.env["HYPERFRAMES_BROWSER_LAUNCHER"] = "/host/launcher.mjs"; + process.env["HYPERFRAMES_BROWSER_PATH"] = hfPath; + + const { ensureBrowser } = await import("./manager.js"); + + await expect(ensureBrowser({ preferManagedChrome: true })).resolves.toEqual({ + executablePath: "/host/launcher.mjs", + source: "launcher", + }); + }); + it("does NOT warn on macOS when falling back to system Chrome", async () => { // macOS Chrome still works fine for the screenshot path and the perf // claims around BeginFrame are Linux-only — keep the warning Linux-scoped diff --git a/packages/cli/src/browser/manager.ts b/packages/cli/src/browser/manager.ts index cf59e7d1d5..3b359174f1 100644 --- a/packages/cli/src/browser/manager.ts +++ b/packages/cli/src/browser/manager.ts @@ -216,7 +216,7 @@ function releaseBrowserInstallLock(ownerToken: string): void { rmSync(INSTALL_LOCK_DIR, { recursive: true, force: true }); } -export type BrowserSource = "env" | "cache" | "system" | "download"; +export type BrowserSource = "launcher" | "env" | "cache" | "system" | "download"; export interface BrowserResult { executablePath: string; @@ -299,11 +299,15 @@ function whichBinary(name: string): string | undefined { // A caller-supplied browser, named by HYPERFRAMES_BROWSER_PATH or PRODUCER_HEADLESS_SHELL_PATH (the engine's // and the deploy docs' name). check, snapshot and compare honour it as render does; which name wins is -// browserPathFromEnv's, so the engine launches what this resolved. +// browserPathFromEnv's, so the engine launches what this resolved. A HYPERFRAMES_BROWSER_LAUNCHER module starts +// the browser itself, so nothing is looked up or downloaded. function findFromEnv(): BrowserResult | undefined { - const envPath = browserPathFromEnv()?.path; - if (envPath && existsSync(envPath)) { - return { executablePath: envPath, source: "env" }; + const fromEnv = browserPathFromEnv(); + if (fromEnv?.name === "HYPERFRAMES_BROWSER_LAUNCHER") { + return { executablePath: fromEnv.path, source: "launcher" }; + } + if (fromEnv && existsSync(fromEnv.path)) { + return { executablePath: fromEnv.path, source: "env" }; } return undefined; } diff --git a/packages/cli/src/browser/preflight.test.ts b/packages/cli/src/browser/preflight.test.ts index 6c63a30de4..0a39b73c8e 100644 --- a/packages/cli/src/browser/preflight.test.ts +++ b/packages/cli/src/browser/preflight.test.ts @@ -354,6 +354,26 @@ describe("runEnvironmentChecks — Chrome shared libraries (Linux/WSL)", () => { expect(result.outcomes.find((o) => o.name === "Chrome")).toMatchObject({ ok: true }); }); + it("passes a launcher module without running it as a browser binary", async () => { + vi.spyOn(manager, "findBrowser").mockResolvedValue({ + executablePath: "/host/launcher.mjs", + source: "launcher", + }); + + const result = await runEnvironmentChecks({ includeBrowser: true }); + + expect(result.outcomes.find((o) => o.name === "Chrome")).toMatchObject({ + ok: true, + detail: "launcher: /host/launcher.mjs", + }); + expect(result.browser?.executablePath).toBe("/host/launcher.mjs"); + expect(runProcess).not.toHaveBeenCalledWith( + "/host/launcher.mjs", + expect.anything(), + expect.anything(), + ); + }); + it("resolveRenderBrowser returns the browser the render check found", async () => { vi.spyOn(manager, "findBrowser").mockResolvedValue({ executablePath: process.execPath, diff --git a/packages/cli/src/browser/preflight.ts b/packages/cli/src/browser/preflight.ts index 543f14cf57..f98204b538 100644 --- a/packages/cli/src/browser/preflight.ts +++ b/packages/cli/src/browser/preflight.ts @@ -286,6 +286,23 @@ async function chromeLaunchOutcome( } } +/** A launcher module is started by its host, so it has no binary to run `--version` on. */ +async function foundChromeOutcome( + info: BrowserResult, + signal?: AbortSignal, +): Promise { + const found: EnvironmentCheckOutcome = { + name: "Chrome", + ok: true, + level: "ok", + detail: `${info.source}: ${info.executablePath}`, + path: info.executablePath, + }; + return info.source === "launcher" + ? found + : chromeLaunchOutcome(info.executablePath, found, signal); +} + async function checkChrome( browserPath?: string, signal?: AbortSignal, @@ -330,19 +347,7 @@ async function checkChrome( info = undefined; failure = normalizeErrorMessage(error); } - if (info) { - return chromeLaunchOutcome( - info.executablePath, - { - name: "Chrome", - ok: true, - level: "ok", - detail: `${info.source}: ${info.executablePath}`, - path: info.executablePath, - }, - signal, - ); - } + if (info) return foundChromeOutcome(info, signal); return { name: "Chrome", diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts index e9248ec5f5..ca1ba7dec1 100644 --- a/packages/engine/src/services/browserManager.test.ts +++ b/packages/engine/src/services/browserManager.test.ts @@ -872,6 +872,21 @@ describe("resolveHeadlessShellPath", () => { } }); + it("resolves no headless shell when a launcher module starts the browser", () => { + const dir = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-env-")); + try { + const shell = join(dir, "chrome-headless-shell"); + writeFileSync(shell, ""); + process.env.PRODUCER_HEADLESS_SHELL_PATH = shell; + process.env.HYPERFRAMES_BROWSER_LAUNCHER = join(dir, "launcher.mjs"); + + expect(resolveHeadlessShellPath({})).toBeUndefined(); + } finally { + delete process.env.HYPERFRAMES_BROWSER_LAUNCHER; + rmSync(dir, { recursive: true, force: true }); + } + }); + it("uses HYPERFRAMES_BROWSER_PATH when the CLI resolved a browser explicitly", () => { const dir = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-env-")); try { diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts index eb85e92dbe..1db66f9a4b 100644 --- a/packages/engine/src/services/browserManager.ts +++ b/packages/engine/src/services/browserManager.ts @@ -18,6 +18,7 @@ import { compareBrowserVersionsDescending, exceedsChromeCeiling, isManagedChromeDir, + launchRenderBrowser, pickSharedShell, } from "./chromeHostCeiling.js"; import { DEFAULT_CONFIG, type EngineConfig } from "../config.js"; @@ -120,7 +121,7 @@ async function probeHardwareWebGlInfo( }; probeBrowser = options.probeLifecycle ? await options.probeLifecycle.launch(ppt, launchOptions) - : await ppt.launch(launchOptions); + : await launchRenderBrowser(ppt, launchOptions); return await rejectAfter( readWebGlInfo(probeBrowser), GPU_PROBE_TIMEOUT_MS, @@ -253,6 +254,7 @@ export function resolveHeadlessShellPath( return config.chromePath; } const fromEnv = browserPathFromEnv(); + if (fromEnv?.name === "HYPERFRAMES_BROWSER_LAUNCHER") return undefined; if (fromEnv) { if (!existsSync(fromEnv.path)) { throw new Error( @@ -855,7 +857,7 @@ async function launchBrowser( let captureMode = fingerprint.requestedCaptureMode; let browser: Browser | undefined; try { - browser = await ppt.launch({ + browser = await launchRenderBrowser(ppt, { ...sigintLaunchOptions(), headless: true, args: [...fingerprint.args], @@ -888,7 +890,7 @@ async function launchBrowser( `${probe.detail}; falling back to screenshot mode.`, ); captureMode = "screenshot"; - browser = await ppt.launch({ + browser = await launchRenderBrowser(ppt, { ...sigintLaunchOptions(), headless: true, args: stripBeginFrameFlags([...fingerprint.args]), diff --git a/packages/engine/src/services/chromeHostCeiling.test.ts b/packages/engine/src/services/chromeHostCeiling.test.ts index 76d16d3c17..436680a1f9 100644 --- a/packages/engine/src/services/chromeHostCeiling.test.ts +++ b/packages/engine/src/services/chromeHostCeiling.test.ts @@ -1,5 +1,14 @@ -import { describe, expect, it } from "vitest"; -import { chromeMajorCeiling, exceedsChromeCeiling } from "./chromeHostCeiling.js"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { + browserPathFromEnv, + chromeMajorCeiling, + exceedsChromeCeiling, + launchRenderBrowser, +} from "./chromeHostCeiling.js"; describe("chromeMajorCeiling", () => { it.each([ @@ -22,3 +31,65 @@ describe("exceedsChromeCeiling", () => { expect(exceedsChromeCeiling(name, ceiling)).toBe(expected); }); }); + +describe("browserPathFromEnv", () => { + it("names a launcher module before either browser binary", () => { + expect( + browserPathFromEnv({ + HYPERFRAMES_BROWSER_LAUNCHER: "/host/launcher.mjs", + HYPERFRAMES_BROWSER_PATH: "/opt/chrome", + PRODUCER_HEADLESS_SHELL_PATH: "/opt/shell", + }), + ).toEqual({ name: "HYPERFRAMES_BROWSER_LAUNCHER", path: "/host/launcher.mjs" }); + }); +}); + +describe("launchRenderBrowser", () => { + const dirs: string[] = []; + afterEach(() => { + for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }); + }); + const launcherModule = (source: string) => { + const dir = mkdtempSync(join(tmpdir(), "hyperframes-launcher-")); + dirs.push(dir); + const file = join(dir, "launcher.mjs"); + writeFileSync(file, source); + return file; + }; + const browser = { marker: "browser" } as unknown as Browser; + const options: LaunchOptions = { headless: true, args: ["--font-render-hinting=none"] }; + + it("calls puppeteer.launch with the options unchanged when no launcher is set", async () => { + const launch = vi.fn(async () => browser); + const puppeteer = { launch } as unknown as PuppeteerNode; + + await expect(launchRenderBrowser(puppeteer, options, {})).resolves.toBe(browser); + expect(launch).toHaveBeenCalledWith(options); + }); + + it("hands the options and puppeteer to the launcher module instead", async () => { + const file = launcherModule( + "export async function launch(options, puppeteer) { return { options, puppeteer }; }", + ); + const launch = vi.fn(); + const puppeteer = { launch } as unknown as PuppeteerNode; + + const result = await launchRenderBrowser(puppeteer, options, { + HYPERFRAMES_BROWSER_LAUNCHER: file, + }); + + expect(result).toEqual({ options, puppeteer }); + expect(launch).not.toHaveBeenCalled(); + }); + + it("says so when the module has no launch export", async () => { + const file = launcherModule("export const start = () => {};"); + const puppeteer = { launch: vi.fn() } as unknown as PuppeteerNode; + + await expect( + launchRenderBrowser(puppeteer, options, { HYPERFRAMES_BROWSER_LAUNCHER: file }), + ).rejects.toThrow( + `HYPERFRAMES_BROWSER_LAUNCHER="${file}" does not export launch(options, puppeteer).`, + ); + }); +}); diff --git a/packages/engine/src/services/chromeHostCeiling.ts b/packages/engine/src/services/chromeHostCeiling.ts index b49308d1ac..418eeb2727 100644 --- a/packages/engine/src/services/chromeHostCeiling.ts +++ b/packages/engine/src/services/chromeHostCeiling.ts @@ -1,6 +1,9 @@ import { spawnSync } from "node:child_process"; import { debuglog } from "node:util"; import { release } from "node:os"; +import { resolve } from "node:path"; +import { pathToFileURL } from "node:url"; +import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core"; /** Chrome 151 dropped macOS 12 and older (Darwin < 22); 150 is the last major that launches there. */ const MACOS_12_LAST_CHROME_MAJOR = 150; @@ -93,13 +96,42 @@ export function pickSharedShell( return undefined; } -/** The browser binary an env var names. The CLI and the engine both resolve it here, HYPERFRAMES_BROWSER_PATH first. */ -export function browserPathFromEnv( - env: NodeJS.ProcessEnv = process.env, -): { name: "HYPERFRAMES_BROWSER_PATH" | "PRODUCER_HEADLESS_SHELL_PATH"; path: string } | undefined { - for (const name of ["HYPERFRAMES_BROWSER_PATH", "PRODUCER_HEADLESS_SHELL_PATH"] as const) { +/** The browser an env var names. The CLI and the engine both resolve it here: a launcher module first, then a + * binary, HYPERFRAMES_BROWSER_PATH before PRODUCER_HEADLESS_SHELL_PATH. */ +export function browserPathFromEnv(env: NodeJS.ProcessEnv = process.env): + | { + name: + | "HYPERFRAMES_BROWSER_LAUNCHER" + | "HYPERFRAMES_BROWSER_PATH" + | "PRODUCER_HEADLESS_SHELL_PATH"; + path: string; + } + | undefined { + for (const name of [ + "HYPERFRAMES_BROWSER_LAUNCHER", + "HYPERFRAMES_BROWSER_PATH", + "PRODUCER_HEADLESS_SHELL_PATH", + ] as const) { const path = env[name]; if (path) return { name, path }; } return undefined; } + +/** Starts a render browser. With HYPERFRAMES_BROWSER_LAUNCHER set, the module it names starts it instead: + * `export async function launch(options, puppeteer)` returns a Browser whose `process()` is the browser it started. */ +export async function launchRenderBrowser( + puppeteer: PuppeteerNode, + options: LaunchOptions, + env: NodeJS.ProcessEnv = process.env, +): Promise { + const path = env.HYPERFRAMES_BROWSER_LAUNCHER; + if (!path) return puppeteer.launch(options); + const launcher: { launch?: unknown } = await import(pathToFileURL(resolve(path)).href); + if (typeof launcher.launch !== "function") { + throw new Error( + `HYPERFRAMES_BROWSER_LAUNCHER="${path}" does not export launch(options, puppeteer).`, + ); + } + return launcher.launch(options, puppeteer); +}