Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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,});