Skip to content

Write HTML. Render video. Built for agents.

fix(engine): renders use the browser the CLI picked; Linux system Chrome is not beginframe (#5987)

Miguel Ángel0260c40e5685
diff --git a/packages/cli/src/browser/manager.ts b/packages/cli/src/browser/manager.ts
index 71a90bf6d6..cf59e7d1d5 100644
--- a/packages/cli/src/browser/manager.ts
+++ b/packages/cli/src/browser/manager.ts
@@ -15,7 +15,11 @@ import {
import { homedir } from "node:os";
import { debuglog } from "node:util";
import { basename, dirname, join, relative } from "node:path";
-import { managedChromeVersion, pickSharedShell } from "@hyperframes/engine/chrome-host-ceiling";
+import {
+ browserPathFromEnv,
+ managedChromeVersion,
+ pickSharedShell,
+} from "@hyperframes/engine/chrome-host-ceiling";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
@@ -293,26 +297,11 @@ function whichBinary(name: string): string | undefined {
}
}
-// Env-var aliases for a caller-supplied browser executable path. The CLI-native
-// name `HYPERFRAMES_BROWSER_PATH` is the canonical spelling (documented via the
-// download-failure hint added in #2443). `PRODUCER_HEADLESS_SHELL_PATH` is the
-// engine-side name that per-worker render launches already honor (see
-// `packages/engine/src/services/browserManager.ts` and `render.ts` which even
-// propagates the CLI-resolved executable into it). Docs in
-// `skills/hyperframes-animation/adapters/typegpu.md`,
-// `packages/gcp-cloud-run/Dockerfile`, and `examples/k8s-jobs/Dockerfile.example`
-// all instruct users to set `PRODUCER_HEADLESS_SHELL_PATH`, so field reports
-// (e.g. `#hyperframes-cli-feedback` ts=1784095034 on win32/x64) hit the case
-// where `render` completes via that env var while `check`, `snapshot`, and
-// `compare` all ignore it and crash on the cached headless-shell instead.
-// Alias them here so every consumer of `openSettledCompositionPage` (which
-// calls `ensureBrowser` → `findFromEnv`) picks up the same escape hatch.
-// Tiebreak: HYPERFRAMES_BROWSER_PATH wins when both are set, matching the
-// CLI-native canonicalization in `render.ts` (which only sets
-// `PRODUCER_HEADLESS_SHELL_PATH` if not already present).
+// 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.
function findFromEnv(): BrowserResult | undefined {
- const envPath =
- process.env["HYPERFRAMES_BROWSER_PATH"] ?? process.env["PRODUCER_HEADLESS_SHELL_PATH"];
+ const envPath = browserPathFromEnv()?.path;
if (envPath && existsSync(envPath)) {
return { executablePath: envPath, source: "env" };
}
diff --git a/packages/engine/src/config.ts b/packages/engine/src/config.ts
index 053889ab67..1c076fb510 100644
--- a/packages/engine/src/config.ts
+++ b/packages/engine/src/config.ts
@@ -852,7 +852,6 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
DEFAULT_CONFIG.largeRenderThreshold,
),
- chromePath: env("PRODUCER_HEADLESS_SHELL_PATH"),
disableGpu: envBool("PRODUCER_DISABLE_GPU", DEFAULT_CONFIG.disableGpu),
browserGpuMode: envBrowserGpuMode(),
allowSoftwareWebGpu: envBool(
diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts
index 2713565cc0..e9248ec5f5 100644
--- a/packages/engine/src/services/browserManager.test.ts
+++ b/packages/engine/src/services/browserManager.test.ts
@@ -9,6 +9,7 @@ import type { Browser, Page, PuppeteerNode } from "puppeteer-core";
import type { CaptureMode } from "./browserLeasePool.js";
import { managedChromeVersion } from "./chromeHostCeiling.js";
+import { resolveConfig } from "../config.js";
import {
_resetAutoBrowserGpuModeCacheForTests,
@@ -818,6 +819,12 @@ describe("resolveHeadlessShellPath", () => {
const originalHeadlessShellPath = process.env.PRODUCER_HEADLESS_SHELL_PATH;
const originalHyperframesBrowserPath = process.env.HYPERFRAMES_BROWSER_PATH;
+ // A runner may export either var (the Windows job sets HYPERFRAMES_BROWSER_PATH); each case sets its own.
+ beforeEach(() => {
+ delete process.env.PRODUCER_HEADLESS_SHELL_PATH;
+ delete process.env.HYPERFRAMES_BROWSER_PATH;
+ });
+
afterEach(() => {
if (originalHeadlessShellPath === undefined) delete process.env.PRODUCER_HEADLESS_SHELL_PATH;
else process.env.PRODUCER_HEADLESS_SHELL_PATH = originalHeadlessShellPath;
@@ -833,6 +840,38 @@ describe("resolveHeadlessShellPath", () => {
);
});
+ it("prefers HYPERFRAMES_BROWSER_PATH over PRODUCER_HEADLESS_SHELL_PATH, as the CLI does", () => {
+ const dir = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-env-"));
+ try {
+ const cliChoice = join(dir, "chosen-browser");
+ const other = join(dir, "other-browser");
+ writeFileSync(cliChoice, "");
+ writeFileSync(other, "");
+ process.env.HYPERFRAMES_BROWSER_PATH = cliChoice;
+ process.env.PRODUCER_HEADLESS_SHELL_PATH = other;
+
+ expect(resolveHeadlessShellPath({})).toBe(cliChoice);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it("keeps that precedence through a render's resolved engine config", () => {
+ const dir = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-env-"));
+ try {
+ const cliChoice = join(dir, "chosen-browser");
+ const other = join(dir, "other-browser");
+ writeFileSync(cliChoice, "");
+ writeFileSync(other, "");
+ process.env.HYPERFRAMES_BROWSER_PATH = cliChoice;
+ process.env.PRODUCER_HEADLESS_SHELL_PATH = other;
+
+ expect(resolveHeadlessShellPath(resolveConfig())).toBe(cliChoice);
+ } finally {
+ 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 d0e694042c..eb85e92dbe 100644
--- a/packages/engine/src/services/browserManager.ts
+++ b/packages/engine/src/services/browserManager.ts
@@ -13,6 +13,7 @@ import { existsSync, readdirSync, statSync } from "fs";
import { join } from "path";
import { homedir } from "os";
import {
+ browserPathFromEnv,
chromeMajorCeiling,
compareBrowserVersionsDescending,
exceedsChromeCeiling,
@@ -251,25 +252,15 @@ export function resolveHeadlessShellPath(
if (config?.chromePath) {
return config.chromePath;
}
- if (process.env.PRODUCER_HEADLESS_SHELL_PATH) {
- const envPath = process.env.PRODUCER_HEADLESS_SHELL_PATH;
- if (!existsSync(envPath)) {
+ const fromEnv = browserPathFromEnv();
+ if (fromEnv) {
+ if (!existsSync(fromEnv.path)) {
throw new Error(
- `[BrowserManager] Chrome binary not found at PRODUCER_HEADLESS_SHELL_PATH="${envPath}". ` +
+ `[BrowserManager] Chrome binary not found at ${fromEnv.name}="${fromEnv.path}". ` +
"Run `hyperframes browser ensure` to re-download.",
);
}
- return envPath;
- }
- if (process.env.HYPERFRAMES_BROWSER_PATH) {
- const envPath = process.env.HYPERFRAMES_BROWSER_PATH;
- if (!existsSync(envPath)) {
- throw new Error(
- `[BrowserManager] Chrome binary not found at HYPERFRAMES_BROWSER_PATH="${envPath}". ` +
- "Run `hyperframes browser ensure` to re-download.",
- );
- }
- return envPath;
+ return fromEnv.path;
}
const ours = join(homedir(), ".cache", "hyperframes", "chrome", "chrome-headless-shell");
const shared = join(homedir(), ".cache", "puppeteer", "chrome-headless-shell");
diff --git a/packages/engine/src/services/chromeHostCeiling.ts b/packages/engine/src/services/chromeHostCeiling.ts
index 322e45873f..b49308d1ac 100644
--- a/packages/engine/src/services/chromeHostCeiling.ts
+++ b/packages/engine/src/services/chromeHostCeiling.ts
@@ -92,3 +92,14 @@ 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) {
+ const path = env[name];
+ if (path) return { name, path };
+ }
+ return undefined;
+}
diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.ts
index 6af2f91518..e63a8ed078 100644
--- a/packages/producer/src/services/renderOrchestrator.test.ts
+++ b/packages/producer/src/services/renderOrchestrator.test.ts
@@ -3313,7 +3313,7 @@ describe("sequential capture stall recovery", () => {
describe("resolveParallelCaptureMode", () => {
const beginframe = {
platform: "linux" as NodeJS.Platform,
- headlessShell: true,
+ headlessShellPath: "/cache/chrome-headless-shell" as string | undefined,
forceScreenshot: false,
deviceScaleFactor: 1,
};
@@ -3328,7 +3328,9 @@ describe("resolveParallelCaptureMode", () => {
// System Chrome on linux: resolveObservedCaptureMode calls this beginframe,
// the engine launches screenshot. Getting this wrong would default-enable
// the router for a cohort whose real path is the screenshot one.
- expect(resolveParallelCaptureMode({ ...beginframe, headlessShell: false })).toBe("screenshot");
+ expect(resolveParallelCaptureMode({ ...beginframe, headlessShellPath: undefined })).toBe(
+ "screenshot",
+ );
expect(resolveParallelCaptureMode({ ...beginframe, forceScreenshot: true })).toBe("screenshot");
// Supersampling: BeginFrame ignores deviceScaleFactor, so preMode falls back.
expect(resolveParallelCaptureMode({ ...beginframe, deviceScaleFactor: 2 })).toBe("screenshot");
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index c67efe3c99..3043282743 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -2562,13 +2562,14 @@ export async function closeOrphanedProbeForRetry(
*/
export function resolveParallelCaptureMode(args: {
platform: NodeJS.Platform;
- /** A chrome-headless-shell binary was resolved for this render. */
- headlessShell: boolean;
+ /** The chrome-headless-shell binary resolved for this render, if any. */
+ headlessShellPath: string | undefined;
forceScreenshot: boolean;
deviceScaleFactor?: number;
}): "screenshot" | "beginframe" {
const supersampling = (args.deviceScaleFactor ?? 1) !== 1;
- return args.headlessShell && args.platform === "linux" && !args.forceScreenshot && !supersampling
+ const headlessShell = args.headlessShellPath !== undefined;
+ return headlessShell && args.platform === "linux" && !args.forceScreenshot && !supersampling
? "beginframe"
: "screenshot";
}
@@ -4070,7 +4071,7 @@ async function executeRenderPipeline(input: {
// capture mode this render will actually use.
const parallelCaptureMode = resolveParallelCaptureMode({
platform: process.platform,
- headlessShell: resolveHeadlessShellPath(cfg) !== null,
+ headlessShellPath: resolveHeadlessShellPath(cfg),
forceScreenshot: captureForceScreenshot,
deviceScaleFactor: captureOptions.deviceScaleFactor,
});