Skip to content

Write HTML. Render video. Built for agents.

fix: check, snapshot and renders use the pinned Chrome, not an older one another tool cached (#5900)

Miguel Ángel50e7a59aef59
diff --git a/packages/cli/src/browser/manager.test.ts b/packages/cli/src/browser/manager.test.ts
index 1bdf9fd452..1164d0ecd6 100644
--- a/packages/cli/src/browser/manager.test.ts
+++ b/packages/cli/src/browser/manager.test.ts
@@ -42,7 +42,7 @@ const HF_RECLAIM_LOCK = join(CACHE_ROOT, ".chrome.install.reclaim.lock");
const PUPPETEER_CACHE = join(FAKE_HOME, ".cache", "puppeteer", "chrome-headless-shell");
const PUPPETEER_BINARY = join(
PUPPETEER_CACHE,
- "linux-148.0.7778.97",
+ `linux-${CHROME_VERSION}`,
"chrome-headless-shell-linux64",
"chrome-headless-shell",
);
@@ -900,7 +900,7 @@ describe("findBrowser — cache resolution", () => {
// scenario from the hf#677 spike.
installFsMocks({
existing: new Set([PUPPETEER_CACHE, PUPPETEER_BINARY]),
- dirs: { [PUPPETEER_CACHE]: ["linux-148.0.7778.97"] },
+ dirs: { [PUPPETEER_CACHE]: [`linux-${CHROME_VERSION}`] },
});
installPuppeteerBrowsersMock();
@@ -955,7 +955,7 @@ describe("findBrowser — cache resolution", () => {
value: hostArch,
configurable: true,
});
- const version = "host-148.0.7778.97";
+ const version = `host-${CHROME_VERSION}`;
const candidates = [
["chrome-headless-shell-linux64", "chrome-headless-shell"],
["chrome-headless-shell-mac-arm64", "chrome-headless-shell"],
@@ -997,7 +997,7 @@ describe("findBrowser — cache resolution", () => {
value: hostArch,
configurable: true,
});
- const version = "host-148.0.7778.97";
+ const version = `host-${CHROME_VERSION}`;
const binaries = [
join(PUPPETEER_CACHE, version, "chrome-headless-shell-linux64", "chrome-headless-shell"),
join(PUPPETEER_CACHE, version, "chrome-headless-shell-win64", "chrome-headless-shell.exe"),
@@ -1016,7 +1016,7 @@ describe("findBrowser — cache resolution", () => {
it("skips an empty executable in the puppeteer cache", async () => {
installFsMocks({
existing: new Set([PUPPETEER_CACHE, PUPPETEER_BINARY]),
- dirs: { [PUPPETEER_CACHE]: ["linux-148.0.7778.97"] },
+ dirs: { [PUPPETEER_CACHE]: [`linux-${CHROME_VERSION}`] },
emptyFiles: new Set([PUPPETEER_BINARY]),
});
installPuppeteerBrowsersMock();
@@ -1027,75 +1027,90 @@ describe("findBrowser — cache resolution", () => {
expect(result?.executablePath).not.toBe(PUPPETEER_BINARY);
});
- it("prefers the puppeteer cache over the hyperframes cache when BOTH are populated", async () => {
- // The HF cache is pinned to `CHROME_VERSION` (131-era) which lags upstream
- // by many releases. The engine's `resolveHeadlessShellPath` scans the
- // puppeteer cache and selects newest-version-first; if the CLI handed
- // engine the older HF-cache binary while a newer puppeteer-cache binary
- // exists, the two would silently disagree on which binary to use.
- // This test pins the priority: puppeteer cache wins when both are populated.
+ it("prefers our pinned cache over the puppeteer cache when BOTH are populated", async () => {
installFsMocks({
existing: new Set([HF_CACHE, HF_BINARY, PUPPETEER_CACHE, PUPPETEER_BINARY]),
- dirs: { [PUPPETEER_CACHE]: ["linux-148.0.7778.97"] },
+ dirs: { [PUPPETEER_CACHE]: [`linux-${CHROME_VERSION}`] },
});
installPuppeteerBrowsersMock({
- installedInHfCache: [{ browser: "chrome-headless-shell", executablePath: HF_BINARY }],
+ installedInHfCache: [
+ { browser: "chrome-headless-shell", executablePath: HF_BINARY, buildId: CHROME_VERSION },
+ ],
});
const { findBrowser } = await import("./manager.js");
const result = await findBrowser();
- expect(result?.executablePath).toBe(PUPPETEER_BINARY);
- expect(result?.source).toBe("cache");
+ expect(result).toEqual({ executablePath: HF_BINARY, source: "cache" });
});
- it("picks the newest version when multiple chrome-headless-shell builds are cached", async () => {
- const olderBinary = join(
+ it("uses our pinned build, not another tool's older shell in the puppeteer cache", async () => {
+ // Field report: a Mac whose puppeteer cache held mac_arm-121 got that shell for check and snapshot, and it died.
+ const oldBinary = join(
PUPPETEER_CACHE,
- "linux-131.0.6778.85",
+ "linux-121.0.6167.85",
"chrome-headless-shell-linux64",
"chrome-headless-shell",
);
installFsMocks({
- existing: new Set([PUPPETEER_CACHE, PUPPETEER_BINARY, olderBinary]),
- dirs: {
- [PUPPETEER_CACHE]: ["linux-131.0.6778.85", "linux-148.0.7778.97"],
- },
+ existing: new Set([HF_CACHE, HF_BINARY, PUPPETEER_CACHE, oldBinary]),
+ dirs: { [PUPPETEER_CACHE]: ["linux-121.0.6167.85"] },
+ });
+ installPuppeteerBrowsersMock({
+ installedInHfCache: [
+ { browser: "chrome-headless-shell", executablePath: HF_BINARY, buildId: CHROME_VERSION },
+ ],
});
- installPuppeteerBrowsersMock();
const { findBrowser } = await import("./manager.js");
- const result = await findBrowser();
- expect(result?.executablePath).toBe(PUPPETEER_BINARY);
+ await expect(findBrowser()).resolves.toEqual({ executablePath: HF_BINARY, source: "cache" });
});
- it("uses numeric (not lexicographic) version ordering — linux-148 beats linux-99", async () => {
- // Regression guard for the lexicographic-sort bug: `"linux-99..."` sorts
- // after `"linux-148..."` character-by-character (because `'9' > '1'`),
- // which would have caused the CLI to hand engine an ancient 99-era binary
- // when a fresh 148 was sitting right next to it. Numeric semver-style
- // ordering is the only correct semantic.
- const linux99Binary = join(
+ it("skips another build in the puppeteer cache that does not start", async () => {
+ const oldBinary = join(
PUPPETEER_CACHE,
- "linux-99.0.6533.123",
+ "linux-121.0.6167.85",
"chrome-headless-shell-linux64",
"chrome-headless-shell",
);
installFsMocks({
- existing: new Set([PUPPETEER_CACHE, PUPPETEER_BINARY, linux99Binary]),
- // Intentionally list the entries in an order that would expose the bug
- // under naive `.sort().reverse()` (which puts `linux-99...` first).
- dirs: {
- [PUPPETEER_CACHE]: ["linux-99.0.6533.123", "linux-148.0.7778.97"],
- },
+ existing: new Set([PUPPETEER_CACHE, oldBinary]),
+ dirs: { [PUPPETEER_CACHE]: ["linux-121.0.6167.85"] },
});
installPuppeteerBrowsersMock();
const { findBrowser } = await import("./manager.js");
- const result = await findBrowser();
- expect(result?.executablePath).toBe(PUPPETEER_BINARY);
+ expect((await findBrowser())?.executablePath).not.toBe(oldBinary);
+ });
+
+ it("keeps the newest working shell in the puppeteer cache when the pinned build is absent", async () => {
+ const shared = (version: string) =>
+ join(
+ PUPPETEER_CACHE,
+ `linux-${version}`,
+ "chrome-headless-shell-linux64",
+ "chrome-headless-shell",
+ );
+ installFsMocks({
+ existing: new Set([PUPPETEER_CACHE, shared("99.0.6533.123"), shared("148.0.7778.97")]),
+ dirs: { [PUPPETEER_CACHE]: ["linux-99.0.6533.123", "linux-148.0.7778.97"] },
+ });
+ installPuppeteerBrowsersMock();
+ vi.doMock("node:child_process", () => ({
+ execSync: vi.fn(() => {
+ throw new Error("not found");
+ }),
+ spawnSync: vi.fn(() => ({ status: 0 })),
+ }));
+
+ const { findBrowser } = await import("./manager.js");
+
+ await expect(findBrowser()).resolves.toEqual({
+ executablePath: shared("148.0.7778.97"),
+ source: "cache",
+ });
});
it("falls back to system Chrome and warns on Linux when no cache has headless-shell", async () => {
@@ -1557,7 +1572,7 @@ describe("browser resolution on macOS 12 (Darwin < 22)", () => {
});
});
- it("keeps the newest puppeteer-cache build on macOS 13", async () => {
+ it("keeps the pinned puppeteer-cache build on macOS 13", async () => {
installFsMocks({
existing: new Set([
PUPPETEER_CACHE,
diff --git a/packages/cli/src/browser/manager.ts b/packages/cli/src/browser/manager.ts
index 163afcfeda..71a90bf6d6 100644
--- a/packages/cli/src/browser/manager.ts
+++ b/packages/cli/src/browser/manager.ts
@@ -15,7 +15,7 @@ import {
import { homedir } from "node:os";
import { debuglog } from "node:util";
import { basename, dirname, join, relative } from "node:path";
-import { chromeMajorCeiling, exceedsChromeCeiling } from "@hyperframes/engine/chrome-host-ceiling";
+import { managedChromeVersion, pickSharedShell } from "@hyperframes/engine/chrome-host-ceiling";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
@@ -33,30 +33,6 @@ async function loadPuppeteerBrowsers(): Promise<PuppeteerBrowsers> {
}
}
-// Bumped from 152.0.7928.2 on 2026-08-10 to pick up crbug 522872457's fix
-// (CL 8032671, "Force-merge PendingLayer for canvas child descendant", merged
-// 2026-07-07 — after the 152.0.7935.0 canary cut, so the old pin predated it).
-//
-// Measured on the shipping headless-shell binary, drawElementImage vs a CDP
-// screenshot of the identical state:
-// sibling content dropped from 3D captures — FIXED
-// background lost from 3D captures — FIXED
-// backface-visibility:hidden ignored — STILL BROKEN (1.4 dB -> 14.8 dB;
-// better, still far under the
-// 32 dB floor)
-// So the 3D compile gate must stay. See PRINFRA-486.
-//
-// Deliberately Beta, not Canary. 153.0.8000.0 measured identical to this build
-// on every probe variant, so crossing a major buys nothing measurable.
-const CHROME_VERSION = "152.0.7977.30";
-// Last headless-shell milestone that launches on macOS 12 (Darwin < 22); Chrome 151 dropped it.
-// Measured: this build exposes canvas.drawElementImage under --enable-features=CanvasDrawElement.
-const MACOS_12_CHROME_VERSION = "150.0.7871.124";
-
-/** The one place that decides which build HyperFrames installs and matches in its own cache. */
-function managedChromeVersion(): string {
- return chromeMajorCeiling() === undefined ? CHROME_VERSION : MACOS_12_CHROME_VERSION;
-}
const CACHE_ROOT_DIR = join(homedir(), ".cache", "hyperframes");
const CACHE_DIR = join(homedir(), ".cache", "hyperframes", "chrome");
// Puppeteer's managed cache — where `@puppeteer/browsers install
@@ -388,71 +364,11 @@ async function findFromHyperframesCache(): Promise<CacheLookupResult> {
}
async function findFromCache(): Promise<CacheLookupResult> {
- // 1) Puppeteer's managed cache — where `npx @puppeteer/browsers install
- // chrome-headless-shell` lands, and where `puppeteer install` from a project
- // depending on full `puppeteer` (not `puppeteer-core`) lands. The engine's
- // `resolveHeadlessShellPath` reads from here and selects newest-version-
- // first; the CLI must match that semantic or it will silently hand the
- // engine an older binary than the engine itself would pick.
- //
- // We intentionally check puppeteer BEFORE the hyperframes-managed cache:
- // this is the non-`preferManagedChrome` path, which exists so a user who
- // installed chrome-headless-shell separately (via `@puppeteer/browsers
- // install`) keeps using that binary instead of being silently switched to
- // the HF-pinned one. Note `CHROME_VERSION` (above) is a pre-Stable pin
- // that may be NEWER than a user's puppeteer-cache Stable build — this is
- // about respecting an explicit prior choice, not "newest wins".
+ // Our pinned build first, as the engine's resolveHeadlessShellPath reads it; then the shared cache's pick.
+ const ours = await findFromHyperframesCache();
+ if (ours.result) return ours;
const fromPuppeteer = findFromPuppeteerCache();
- if (fromPuppeteer) {
- return { result: fromPuppeteer };
- }
-
- // 2) Hyperframes-managed cache. This is the fallback path: only reached
- // when no puppeteer-cache binary exists.
- return findFromHyperframesCache();
-}
-
-/**
- * Parse a puppeteer-cache version directory name (`linux-148.0.7778.97`,
- * `mac_arm-131.0.6778.85`, etc.) into a numeric tuple for ordering.
- *
- * Lexicographic sort on these strings is buggy because `"99"` > `"148"` (the
- * `9` outranks the `1` character-wise), so a 99-era binary would beat a
- * 148-era binary in `.sort().reverse()`. We split on `-` to drop the platform
- * prefix, then on `.` to get integer segments. Returns `undefined` for names
- * that don't have at least one parseable numeric segment so they sort last.
- */
-function parseVersionSegments(versionDir: string): number[] | undefined {
- const dashIdx = versionDir.indexOf("-");
- const versionPart = dashIdx >= 0 ? versionDir.slice(dashIdx + 1) : versionDir;
- const segments = versionPart.split(".");
- const parsed: number[] = [];
- for (const seg of segments) {
- const n = parseInt(seg, 10);
- if (!Number.isFinite(n)) {
- // Stop at the first non-numeric segment but keep what we've collected.
- break;
- }
- parsed.push(n);
- }
- return parsed.length > 0 ? parsed : undefined;
-}
-
-/** Numeric semver-style descending comparator for puppeteer cache dirs. */
-function compareVersionDirsDescending(a: string, b: string): number {
- const pa = parseVersionSegments(a);
- const pb = parseVersionSegments(b);
- // Unparseable names sort after parseable ones (so we still try them, just last).
- if (!pa && !pb) return 0;
- if (!pa) return 1;
- if (!pb) return -1;
- const len = Math.max(pa.length, pb.length);
- for (let i = 0; i < len; i += 1) {
- const av = pa[i] ?? 0;
- const bv = pb[i] ?? 0;
- if (av !== bv) return bv - av; // descending (newest first)
- }
- return 0;
+ return fromPuppeteer ? { result: fromPuppeteer } : ours;
}
const CACHED_HEADLESS_SHELL_EXECUTABLES: Readonly<
@@ -484,26 +400,15 @@ function findFromPuppeteerCache(): BrowserResult | undefined {
if (!executable) return undefined;
let versions: string[];
try {
- // Numeric semver-style sort, newest first. Lexicographic `.sort().reverse()`
- // (the previous implementation, still in engine `resolveHeadlessShellPath`)
- // mis-orders `linux-99...` ahead of `linux-148...` because character `'9'`
- // outranks `'1'`. See `parseVersionSegments` above.
- versions = [...readdirSync(PUPPETEER_CACHE_DIR)].sort(compareVersionDirsDescending);
+ versions = readdirSync(PUPPETEER_CACHE_DIR);
} catch {
return undefined;
}
- const ceiling = chromeMajorCeiling();
- for (const version of versions) {
- if (exceedsChromeCeiling(version, ceiling)) continue;
- // Same shape as `resolveHeadlessShellPath` in engine/browserManager.ts —
- // keep them aligned. If puppeteer ever changes the on-disk layout the two
- // need to move together.
- const binary = join(PUPPETEER_CACHE_DIR, version, ...executable);
- if (isUsableExecutable(binary)) {
- return { executablePath: binary, source: "cache" };
- }
- }
- return undefined;
+ const binary = pickSharedShell(versions, (version) => {
+ const candidate = join(PUPPETEER_CACHE_DIR, version, ...executable);
+ return isUsableExecutable(candidate) ? candidate : undefined;
+ });
+ return binary ? { executablePath: binary, source: "cache" } : undefined;
}
/**
diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts
index 8f51e83c8f..2713565cc0 100644
--- a/packages/engine/src/services/browserManager.test.ts
+++ b/packages/engine/src/services/browserManager.test.ts
@@ -8,6 +8,7 @@ import { join } from "node:path";
import type { Browser, Page, PuppeteerNode } from "puppeteer-core";
import type { CaptureMode } from "./browserLeasePool.js";
+import { managedChromeVersion } from "./chromeHostCeiling.js";
import {
_resetAutoBrowserGpuModeCacheForTests,
@@ -887,7 +888,7 @@ describe("resolveHeadlessShellPath", () => {
".cache",
"puppeteer",
"chrome-headless-shell",
- "host-152.0.7928.2",
+ `host-${managedChromeVersion("linux", "24.0.0")}`,
);
const candidates = [
["chrome-headless-shell-linux64", "chrome-headless-shell"],
@@ -932,7 +933,7 @@ describe("resolveHeadlessShellPath", () => {
".cache",
"puppeteer",
"chrome-headless-shell",
- "host-152.0.7928.2",
+ `host-${managedChromeVersion("linux", "24.0.0")}`,
);
for (const [directory, executable] of [
["chrome-headless-shell-linux64", "chrome-headless-shell"],
@@ -959,6 +960,96 @@ describe("resolveHeadlessShellPath", () => {
},
);
+ it("never uses another tool's shell that does not start", () => {
+ // Field report: only mac_arm-121 in the shared cache, and that shell died at launch.
+ const home = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-shared-old-"));
+ try {
+ const old = join(home, ".cache", "puppeteer", "chrome-headless-shell", "linux-121.0.6167.85");
+ const binary = join(old, "chrome-headless-shell-linux64", "chrome-headless-shell");
+ mkdirSync(join(binary, ".."), { recursive: true });
+ writeFileSync(binary, "shell");
+ const env = { ...process.env, HOME: home, USERPROFILE: home };
+ delete env.PRODUCER_HEADLESS_SHELL_PATH;
+ delete env.HYPERFRAMES_BROWSER_PATH;
+
+ expect(resolveHeadlessShellInSubprocess(env, { platform: "linux", arch: "x64" })).toBe("");
+ } finally {
+ rmSync(home, { recursive: true, force: true });
+ }
+ });
+
+ it("prefers the managed build in the shared cache over an older build of ours", () => {
+ const home = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-shared-managed-"));
+ try {
+ const shell = (root: string, version: string) =>
+ join(
+ home,
+ ".cache",
+ ...root.split("/"),
+ `linux-${version}`,
+ "chrome-headless-shell-linux64",
+ "chrome-headless-shell",
+ );
+ const managed = shell(
+ "puppeteer/chrome-headless-shell",
+ managedChromeVersion("linux", "24.0.0"),
+ );
+ for (const binary of [
+ managed,
+ shell("puppeteer/chrome-headless-shell", "121.0.6167.85"),
+ shell("hyperframes/chrome/chrome-headless-shell", "150.0.7871.124"),
+ ]) {
+ mkdirSync(join(binary, ".."), { recursive: true });
+ writeFileSync(binary, "shell");
+ }
+ const env = { ...process.env, HOME: home, USERPROFILE: home };
+ delete env.PRODUCER_HEADLESS_SHELL_PATH;
+ delete env.HYPERFRAMES_BROWSER_PATH;
+
+ expect(resolveHeadlessShellInSubprocess(env, { platform: "linux", arch: "x64" })).toBe(
+ managed,
+ );
+ } finally {
+ rmSync(home, { recursive: true, force: true });
+ }
+ });
+
+ // Stand-in shells are shell scripts.
+ it.skipIf(process.platform === "win32")(
+ "keeps the newest shared shell that starts and skips one that dies",
+ () => {
+ const home = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-shared-starts-"));
+ try {
+ const shell = (version: string, script: string) => {
+ const binary = join(
+ home,
+ ".cache",
+ "puppeteer",
+ "chrome-headless-shell",
+ `linux-${version}`,
+ "chrome-headless-shell-linux64",
+ "chrome-headless-shell",
+ );
+ mkdirSync(join(binary, ".."), { recursive: true });
+ writeFileSync(binary, script, { mode: 0o755 });
+ return binary;
+ };
+ shell("149.0.7800.1", "#!/bin/sh\nkill -TRAP $$\n");
+ const working = shell("148.0.7778.97", "#!/bin/sh\nexit 0\n");
+ shell("99.0.6533.123", "#!/bin/sh\nexit 0\n");
+ const env = { ...process.env, HOME: home, USERPROFILE: home };
+ delete env.PRODUCER_HEADLESS_SHELL_PATH;
+ delete env.HYPERFRAMES_BROWSER_PATH;
+
+ expect(resolveHeadlessShellInSubprocess(env, { platform: "linux", arch: "x64" })).toBe(
+ working,
+ );
+ } finally {
+ rmSync(home, { recursive: true, force: true });
+ }
+ },
+ );
+
it("reuses chrome-headless-shell from the HyperFrames-managed cache", () => {
const home = mkdtempSync(join(tmpdir(), "hyperframes-engine-browser-cache-"));
try {
diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts
index 4952238161..d0e694042c 100644
--- a/packages/engine/src/services/browserManager.ts
+++ b/packages/engine/src/services/browserManager.ts
@@ -12,7 +12,13 @@ import { execSync } from "child_process";
import { existsSync, readdirSync, statSync } from "fs";
import { join } from "path";
import { homedir } from "os";
-import { chromeMajorCeiling, exceedsChromeCeiling } from "./chromeHostCeiling.js";
+import {
+ chromeMajorCeiling,
+ compareBrowserVersionsDescending,
+ exceedsChromeCeiling,
+ isManagedChromeDir,
+ pickSharedShell,
+} from "./chromeHostCeiling.js";
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
import { describeWslGpuAccess, detectWsl, type WslHostFacts } from "./wslHost.js";
@@ -159,27 +165,6 @@ async function readWebGlInfo(browser: Browser): Promise<WebGlProbeInfo> {
export type AcquiredBrowser = BrowserLease;
-function compareBrowserVersionsDescending(left: string, right: string): number {
- const parse = (value: string): number[] => {
- const version = value.slice(value.indexOf("-") + 1);
- const segments: number[] = [];
- for (const segment of version.split(".")) {
- const parsed = Number.parseInt(segment, 10);
- if (!Number.isFinite(parsed)) break;
- segments.push(parsed);
- }
- return segments;
- };
- const leftSegments = parse(left);
- const rightSegments = parse(right);
- const length = Math.max(leftSegments.length, rightSegments.length);
- for (let index = 0; index < length; index += 1) {
- const difference = (rightSegments[index] ?? 0) - (leftSegments[index] ?? 0);
- if (difference !== 0) return difference;
- }
- return 0;
-}
-
const CACHED_HEADLESS_SHELL_EXECUTABLES: Readonly<
Record<string, readonly [directory: string, executable: string]>
> = {
@@ -230,6 +215,31 @@ function findCachedHeadlessShell(baseDir: string): string | undefined {
return undefined;
}
+function findSharedHeadlessShell(baseDir: string): string | undefined {
+ const executable = cachedHeadlessShellExecutable();
+ if (!executable || !existsSync(baseDir)) return undefined;
+ try {
+ return pickSharedShell(readdirSync(baseDir), (version) => {
+ const binary = join(baseDir, version, ...executable);
+ return isNonEmptyFile(binary) ? binary : undefined;
+ });
+ } catch {
+ return undefined;
+ }
+}
+
+function findManagedHeadlessShell(baseDir: string): string | undefined {
+ const executable = cachedHeadlessShellExecutable();
+ if (!executable || !existsSync(baseDir)) return undefined;
+ try {
+ const version = readdirSync(baseDir).find(isManagedChromeDir);
+ const binary = version && join(baseDir, version, ...executable);
+ return binary && isNonEmptyFile(binary) ? binary : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
/**
* Resolve chrome-headless-shell binary for deterministic BeginFrame rendering.
* Checks config.chromePath, then PRODUCER_HEADLESS_SHELL_PATH env var,
@@ -261,11 +271,12 @@ export function resolveHeadlessShellPath(
}
return envPath;
}
- const home = homedir();
+ const ours = join(homedir(), ".cache", "hyperframes", "chrome", "chrome-headless-shell");
+ const shared = join(homedir(), ".cache", "puppeteer", "chrome-headless-shell");
return (
- findCachedHeadlessShell(
- join(home, ".cache", "hyperframes", "chrome", "chrome-headless-shell"),
- ) ?? findCachedHeadlessShell(join(home, ".cache", "puppeteer", "chrome-headless-shell"))
+ findManagedHeadlessShell(ours) ??
+ findSharedHeadlessShell(shared) ??
+ findCachedHeadlessShell(ours)
);
}
diff --git a/packages/engine/src/services/chromeHostCeiling.ts b/packages/engine/src/services/chromeHostCeiling.ts
index 55d93f267b..322e45873f 100644
--- a/packages/engine/src/services/chromeHostCeiling.ts
+++ b/packages/engine/src/services/chromeHostCeiling.ts
@@ -1,3 +1,5 @@
+import { spawnSync } from "node:child_process";
+import { debuglog } from "node:util";
import { release } from "node:os";
/** Chrome 151 dropped macOS 12 and older (Darwin < 22); 150 is the last major that launches there. */
@@ -18,3 +20,75 @@ export function exceedsChromeCeiling(versionName: string, ceiling: number | unde
const major = Number.parseInt(versionName.slice(versionName.indexOf("-") + 1), 10);
return major > ceiling;
}
+
+// Deliberately Beta, not Canary: 153.0.8000.0 measured identical to this build on every probe. macOS 12 gets 150,
+// the last headless shell that launches there; it exposes canvas.drawElementImage under CanvasDrawElement.
+const CHROME_VERSION = "152.0.7977.30";
+const MACOS_12_CHROME_VERSION = "150.0.7871.124";
+
+export function managedChromeVersion(
+ hostPlatform: string = process.platform,
+ hostRelease: string = release(),
+): string {
+ return chromeMajorCeiling(hostPlatform, hostRelease) === undefined
+ ? CHROME_VERSION
+ : MACOS_12_CHROME_VERSION;
+}
+
+export const isManagedChromeDir = (versionName: string): boolean =>
+ versionName.slice(versionName.indexOf("-") + 1) === managedChromeVersion();
+
+/** Newest first, by numeric build (`linux-148.0.1` before `linux-99.0.1`). */
+export function compareBrowserVersionsDescending(left: string, right: string): number {
+ const parse = (value: string): number[] => {
+ const version = value.slice(value.indexOf("-") + 1);
+ const segments: number[] = [];
+ for (const segment of version.split(".")) {
+ const parsed = Number.parseInt(segment, 10);
+ if (!Number.isFinite(parsed)) break;
+ segments.push(parsed);
+ }
+ return segments;
+ };
+ const leftSegments = parse(left);
+ const rightSegments = parse(right);
+ const length = Math.max(leftSegments.length, rightSegments.length);
+ for (let index = 0; index < length; index += 1) {
+ const difference = (rightSegments[index] ?? 0) - (leftSegments[index] ?? 0);
+ if (difference !== 0) return difference;
+ }
+ return 0;
+}
+
+const starts = new Map<string, boolean>();
+const debug = debuglog("hyperframes:browser");
+
+/** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
+export function shellStarts(binary: string): boolean {
+ let answer = starts.get(binary);
+ if (answer === undefined) {
+ const probe = ["--no-sandbox", "--dump-dom", "about:blank"];
+ answer = spawnSync(binary, probe, { stdio: "ignore", timeout: 10_000 })?.status === 0;
+ if (!answer) debug("skipping %s: it did not start", binary);
+ starts.set(binary, answer);
+ }
+ return answer;
+}
+
+/** The shared Puppeteer cache's shell: the managed build, else the newest under the host's ceiling that starts.
+ * `shell` names a version dir's executable, or undefined when it holds no usable file. */
+export function pickSharedShell(
+ versions: readonly string[],
+ shell: (version: string) => string | undefined,
+): string | undefined {
+ const managed = versions.find(isManagedChromeDir);
+ const pinned = managed && shell(managed);
+ if (pinned) return pinned;
+ const ceiling = chromeMajorCeiling();
+ for (const version of [...versions].sort(compareBrowserVersionsDescending)) {
+ if (version === managed || exceedsChromeCeiling(version, ceiling)) continue;
+ const binary = shell(version);
+ if (binary && shellStarts(binary)) return binary;
+ }
+ return undefined;
+}
diff --git a/skills-manifest.json b/skills-manifest.json
index e5dcbbe1f0..e774301b3f 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -2,8 +2,8 @@
"source": "heygen-com/hyperframes",
"skills": {
"embedded-captions": {
- "hash": "1dc7ec2fd4a6e3fc",
- "files": 145
+ "hash": "3310b3412bff68dd",
+ "files": 146
},
"faceless-explainer": {
"hash": "47a0783444abc45a",
diff --git a/skills/embedded-captions/scripts/check-overflow.cjs b/skills/embedded-captions/scripts/check-overflow.cjs
index 4acbaa5d9d..02e3ddcbb8 100644
--- a/skills/embedded-captions/scripts/check-overflow.cjs
+++ b/skills/embedded-captions/scripts/check-overflow.cjs
@@ -16,6 +16,7 @@
const path = require("path");
const fs = require("fs");
const os = require("os");
+const { hfBrowser } = require("./hf-cli.cjs");
const HF_ROOTS = [
process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
@@ -69,13 +70,9 @@ async function main() {
const H = num(/data-height="([0-9.]+)"/, 1080);
const DUR = num(/data-duration="([0-9.]+)"/, 8);
- const exe =
- process.platform === "darwin"
- ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
- : "/usr/bin/google-chrome";
const browser = await puppeteer.launch({
headless: "new",
- executablePath: fs.existsSync(exe) ? exe : undefined,
+ executablePath: hfBrowser(),
args: [
"--disable-web-security",
"--allow-file-access-from-files",
diff --git a/skills/embedded-captions/scripts/check-rail-climax.cjs b/skills/embedded-captions/scripts/check-rail-climax.cjs
index 0b921e2991..92330898ee 100644
--- a/skills/embedded-captions/scripts/check-rail-climax.cjs
+++ b/skills/embedded-captions/scripts/check-rail-climax.cjs
@@ -18,6 +18,7 @@
const path = require("path");
const fs = require("fs");
const os = require("os");
+const { hfBrowser } = require("./hf-cli.cjs");
const HF_ROOTS = [
process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
@@ -160,15 +161,11 @@ async function main() {
"[rail-climax] puppeteer unavailable — skipping (install project dependencies per embedded-captions SKILL.md Runtime prerequisites)",
);
- const exe =
- process.platform === "darwin"
- ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
- : "/usr/bin/google-chrome";
let browser;
try {
browser = await puppeteer.launch({
headless: "new",
- executablePath: fs.existsSync(exe) ? exe : undefined,
+ executablePath: hfBrowser(),
args: ["--disable-web-security", "--allow-file-access-from-files", "--disable-dev-shm-usage"],
});
} catch (e) {
diff --git a/skills/embedded-captions/scripts/hf-cli.cjs b/skills/embedded-captions/scripts/hf-cli.cjs
index 6786380365..c8799527fc 100644
--- a/skills/embedded-captions/scripts/hf-cli.cjs
+++ b/skills/embedded-captions/scripts/hf-cli.cjs
@@ -29,5 +29,30 @@ function hfCli(checkout) {
"HyperFrames CLI unavailable: install the full plugin or set HYPERFRAMES_ROOT to a built checkout.",
);
}
-module.exports = { hfCli };
+/** The browser the CLI launches (`hyperframes browser path`), so these scripts never pick their own; without a CLI,
+ * the system Chrome they used before. */
+function hfBrowser() {
+ const { execFileSync } = require("node:child_process");
+ const asks = [
+ () => [process.execPath, [hfCli(), "browser", "path"]],
+ () => ["hyperframes", ["browser", "path"]],
+ ];
+ for (const ask of asks) {
+ try {
+ const [command, args] = ask();
+ const out = execFileSync(command, args, {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ });
+ const found = out.trim().split("\n").pop();
+ if (found && fs.existsSync(found)) return found;
+ } catch {}
+ }
+ const chrome =
+ process.platform === "darwin"
+ ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+ : "/usr/bin/google-chrome";
+ return fs.existsSync(chrome) ? chrome : undefined;
+}
+module.exports = { hfCli, hfBrowser };
if (require.main === module) console.log(hfCli(process.argv[2]));
diff --git a/skills/embedded-captions/scripts/hf-cli.test.mjs b/skills/embedded-captions/scripts/hf-cli.test.mjs
new file mode 100644
index 0000000000..7c3be92ede
--- /dev/null
+++ b/skills/embedded-captions/scripts/hf-cli.test.mjs
@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+const { hfBrowser } = createRequire(import.meta.url)("./hf-cli.cjs");
+
+test("caption scripts launch the browser `hyperframes browser path` prints", (t) => {
+ const root = mkdtempSync(join(tmpdir(), "hf-browser-"));
+ t.after(() => rmSync(root, { recursive: true, force: true }));
+ const shell = join(root, "chrome-headless-shell");
+ writeFileSync(shell, "");
+ const cliDir = join(root, "hf/packages/cli/dist");
+ mkdirSync(cliDir, { recursive: true });
+ writeFileSync(
+ join(cliDir, "cli.js"),
+ `if (process.argv.slice(2).join(" ") === "browser path") console.log(${JSON.stringify(shell)});`,
+ );
+ const before = process.env.HYPERFRAMES_ROOT;
+ process.env.HYPERFRAMES_ROOT = join(root, "hf");
+ t.after(() => {
+ if (before === undefined) delete process.env.HYPERFRAMES_ROOT;
+ else process.env.HYPERFRAMES_ROOT = before;
+ });
+ assert.equal(hfBrowser(), shell);
+});
diff --git a/skills/embedded-captions/scripts/measure-layout.cjs b/skills/embedded-captions/scripts/measure-layout.cjs
index 422294bd38..8daf849383 100644
--- a/skills/embedded-captions/scripts/measure-layout.cjs
+++ b/skills/embedded-captions/scripts/measure-layout.cjs
@@ -17,6 +17,7 @@
const path = require("path");
const fs = require("fs");
const os = require("os");
+const { hfBrowser } = require("./hf-cli.cjs");
// Locate hyperframes' bundled puppeteer. render-and-composite.sh exports
// HYPERFRAMES_ROOT; standalone we also try the in-repo path + ~/Downloads, and
@@ -126,10 +127,6 @@ async function main() {
}
// Match render-and-composite's Chrome detection
- const exe =
- process.platform === "darwin"
- ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
- : "/usr/bin/google-chrome";
const W = plan?.width || 720;
const H = plan?.height || 1290;
@@ -137,7 +134,7 @@ async function main() {
const browser = await puppeteer.launch({
headless: "new",
- executablePath: fs.existsSync(exe) ? exe : undefined,
+ executablePath: hfBrowser(),
args: [
"--disable-web-security",
"--allow-file-access-from-files",
diff --git a/skills/embedded-captions/scripts/preview-frames.cjs b/skills/embedded-captions/scripts/preview-frames.cjs
index ee7c2e9180..29d8e31c6b 100644
--- a/skills/embedded-captions/scripts/preview-frames.cjs
+++ b/skills/embedded-captions/scripts/preview-frames.cjs
@@ -25,6 +25,7 @@ const fs = require("fs");
const os = require("os");
const crypto = require("crypto");
const { pathToFileURL } = require("url");
+const { hfBrowser } = require("./hf-cli.cjs");
function sriSha384(source) {
return `sha384-${crypto.createHash("sha384").update(source).digest("base64")}`;
@@ -223,13 +224,9 @@ async function main() {
const outDir = path.join(project, "preview");
fs.mkdirSync(outDir, { recursive: true });
- const exe =
- process.platform === "darwin"
- ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
- : "/usr/bin/google-chrome";
const browser = await puppeteer.launch({
headless: "new",
- executablePath: fs.existsSync(exe) ? exe : undefined,
+ executablePath: hfBrowser(),
args: ["--disable-web-security", "--allow-file-access-from-files", "--disable-dev-shm-usage"],
});
const outs = [];