Skip to content

Write HTML. Render video. Built for agents.

fix(engine): renders under WSL use the GPU through full Chrome when the headless shell cannot (#5574)

Miguel Ángel9b996059af65
diff --git a/docs/guides/troubleshooting.mdx b/docs/guides/troubleshooting.mdx
index cd7d696d23..72a85ddcd9 100644
--- a/docs/guides/troubleshooting.mdx
+++ b/docs/guides/troubleshooting.mdx
@@ -249,6 +249,18 @@ sudo usermod -aG render $USER
wsl --shutdown
```
+That alone may not be enough: on some drivers Chrome's headless shell, which
+HyperFrames installs, cannot reach the GPU under WSL while full Chrome can.
+Install full Chrome once; when the headless shell finds no GPU, HyperFrames tries
+it and renders with it if it reaches the GPU:
+
+```bash
+npx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer
+```
+
+The log then shows `browserGpuMode probe → hardware (full Chrome: ...)`. To pick a
+full Chrome yourself, set `HYPERFRAMES_BROWSER_PATH` to its path.
+
If the GPU is still not used, render from Windows instead. Copy the project to
a Windows drive (for example `C:\Users\you\renders\my-video`) and run the same
command from PowerShell, where Chrome uses the graphics card through Direct3D:
diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts
index 97ed0c5201..19206acf6f 100644
--- a/packages/engine/src/services/browserManager.test.ts
+++ b/packages/engine/src/services/browserManager.test.ts
@@ -27,6 +27,8 @@ import {
releaseBrowser,
resolveHeadlessShellPath,
resolveBrowserGpuMode,
+ resolveCaptureBrowserPath,
+ resolveFullChromePath,
} from "./browserManager.js";
describe("BeginFrame capability probe", () => {
@@ -481,6 +483,88 @@ describe("resolveBrowserGpuMode", () => {
};
const output = (spy: { mock: { calls: unknown[][] } }) =>
spy.mock.calls.map((call) => String(call[0])).join("\n");
+ const noFullChrome = () => undefined;
+ const FULL_CHROME = "/home/u/.cache/puppeteer/chrome/linux-152/chrome-linux64/chrome";
+ const SHELL_RENDERER = {
+ hasWebGL: false,
+ vendor: "",
+ renderer: "",
+ };
+ const D3D12_RENDERER = {
+ hasWebGL: true,
+ vendor: "Google Inc. (Microsoft Corporation)",
+ renderer:
+ "ANGLE (Microsoft Corporation, D3D12 (NVIDIA GeForce RTX 4070 SUPER), OpenGL ES 3.1)",
+ };
+ /** The headless shell finds no GPU; full Chrome answers with `fullChromeInfo`. */
+ const shellWithoutGpu = (fullChromeInfo: typeof D3D12_RENDERER) => {
+ const launch = vi.fn(async (options: { executablePath?: string }) => ({
+ newPage: vi.fn().mockResolvedValue({
+ evaluate: vi
+ .fn()
+ .mockResolvedValue(
+ options.executablePath === FULL_CHROME ? fullChromeInfo : SHELL_RENDERER,
+ ),
+ }),
+ close: vi.fn().mockResolvedValue(undefined),
+ }));
+ _setPuppeteerForTests({ launch } as unknown as PuppeteerNode);
+ return launch;
+ };
+ const withFullChrome = {
+ platform: "linux" as const,
+ wslHost,
+ chromePath: "/home/u/.cache/hyperframes/chrome/chrome-headless-shell",
+ findFullChrome: () => FULL_CHROME,
+ };
+
+ it("renders on full Chrome when the headless shell finds no GPU", async () => {
+ const launch = shellWithoutGpu(D3D12_RENDERER);
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
+ expect(await resolveBrowserGpuMode("auto", withFullChrome)).toBe("hardware");
+ expect(await resolveCaptureBrowserPath("hardware", { chromePath: "/shell" })).toBe(
+ FULL_CHROME,
+ );
+ expect(launch.mock.calls.map(([options]) => options.executablePath)).toEqual([
+ withFullChrome.chromePath,
+ FULL_CHROME,
+ ]);
+ const text = output(error);
+ expect(text).toContain("browserGpuMode probe → hardware (full Chrome: WebGL renderer");
+ expect(text).not.toContain("uses software");
+ });
+
+ it("explicit 'hardware' takes the full Chrome route without warning", async () => {
+ shellWithoutGpu(D3D12_RENDERER);
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ expect(await resolveBrowserGpuMode("hardware", withFullChrome)).toBe("hardware");
+ expect(await resolveCaptureBrowserPath("hardware")).toBe(FULL_CHROME);
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it("says full Chrome found no GPU either, and names native Windows", async () => {
+ shellWithoutGpu(SHELL_RENDERER);
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
+ expect(await resolveBrowserGpuMode("auto", withFullChrome)).toBe("software");
+ expect(await resolveCaptureBrowserPath("software", { chromePath: "/shell" })).toBe("/shell");
+ const text = output(error);
+ expect(text).toContain(`Full Chrome (${FULL_CHROME}) found no hardware GPU either.`);
+ expect(text).toContain("native Windows");
+ expect(text).not.toContain("@puppeteer/browsers install chrome");
+ });
+
+ it("without full Chrome, says how to install it", async () => {
+ shellWithoutGpu(D3D12_RENDERER);
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
+ expect(
+ await resolveBrowserGpuMode("auto", { ...withFullChrome, findFullChrome: noFullChrome }),
+ ).toBe("software");
+ expect(await resolveCaptureBrowserPath("hardware", { chromePath: "/shell" })).toBe("/shell");
+ expect(output(error)).toContain(
+ "npx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer",
+ );
+ });
const neverAnsweringProbe = () => {
const launch = vi.fn().mockResolvedValue({
newPage: vi.fn().mockResolvedValue({ evaluate: () => new Promise(() => {}) }),
@@ -494,8 +578,18 @@ describe("resolveBrowserGpuMode", () => {
it("auto mode says it fell back to software, why, and the fix, once", async () => {
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
const error = vi.spyOn(console, "error").mockImplementation(() => {});
- expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("software");
- await resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
+ expect(
+ await resolveBrowserGpuMode("auto", {
+ platform: "linux",
+ wslHost,
+ findFullChrome: noFullChrome,
+ }),
+ ).toBe("software");
+ await resolveBrowserGpuMode("auto", {
+ platform: "linux",
+ wslHost,
+ findFullChrome: noFullChrome,
+ });
const text = output(error);
expect(text).toContain("browserGpuMode probe → software (WebGL unavailable)");
expect(text).toContain(
@@ -511,7 +605,11 @@ describe("resolveBrowserGpuMode", () => {
try {
neverAnsweringProbe();
const error = vi.spyOn(console, "error").mockImplementation(() => {});
- const mode = resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
+ const mode = resolveBrowserGpuMode("auto", {
+ platform: "linux",
+ wslHost,
+ findFullChrome: noFullChrome,
+ });
await vi.advanceTimersByTimeAsync(15_000 + 250);
await expect(mode).resolves.toBe("software");
const text = output(error);
@@ -529,7 +627,11 @@ describe("resolveBrowserGpuMode", () => {
neverAnsweringProbe();
const error = vi.spyOn(console, "error").mockImplementation(() => {});
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
- const mode = resolveBrowserGpuMode("hardware", { platform: "linux", wslHost });
+ const mode = resolveBrowserGpuMode("hardware", {
+ platform: "linux",
+ wslHost,
+ findFullChrome: noFullChrome,
+ });
await vi.advanceTimersByTimeAsync(15_000 + 250);
await expect(mode).resolves.toBe("hardware");
const warning = output(warn);
@@ -549,9 +651,13 @@ describe("resolveBrowserGpuMode", () => {
} as unknown as PuppeteerNode);
const error = vi.spyOn(console, "error").mockImplementation(() => {});
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
- expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
- "hardware",
- );
+ expect(
+ await resolveBrowserGpuMode("hardware", {
+ platform: "linux",
+ wslHost,
+ findFullChrome: noFullChrome,
+ }),
+ ).toBe("hardware");
const warning = output(warn);
expect(warning).toContain("GPU probe could not run");
expect(warning).toContain("hyperframes doctor");
@@ -563,9 +669,13 @@ describe("resolveBrowserGpuMode", () => {
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
const error = vi.spyOn(console, "error").mockImplementation(() => {});
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
- expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
- "hardware",
- );
+ expect(
+ await resolveBrowserGpuMode("hardware", {
+ platform: "linux",
+ wslHost,
+ findFullChrome: noFullChrome,
+ }),
+ ).toBe("hardware");
const warning = output(warn);
expect(warning).toContain("sudo usermod -aG render $USER");
expect(warning).not.toContain("--gpus all");
@@ -579,11 +689,42 @@ describe("resolveBrowserGpuMode", () => {
renderer: "ANGLE (Microsoft Corporation, D3D12 (Intel(R) Graphics), OpenGL ES 3.0)",
});
const error = vi.spyOn(console, "error").mockImplementation(() => {});
- expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("hardware");
+ expect(
+ await resolveBrowserGpuMode("auto", {
+ platform: "linux",
+ wslHost,
+ findFullChrome: noFullChrome,
+ }),
+ ).toBe("hardware");
expect(output(error)).not.toContain("WSL");
});
});
+ it("finds no full Chrome, without throwing, when its cache cannot be read", () => {
+ const home = mkdtempSync(join(tmpdir(), "hf-full-chrome-cache-"));
+ const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE };
+ try {
+ mkdirSync(join(home, ".cache", "puppeteer"), { recursive: true });
+ writeFileSync(join(home, ".cache", "puppeteer", "chrome"), "not a folder");
+ Object.assign(process.env, { HOME: home, USERPROFILE: home });
+ expect(resolveFullChromePath()).toBeUndefined();
+ } finally {
+ Object.assign(process.env, saved);
+ rmSync(home, { recursive: true, force: true });
+ }
+ });
+
+ it("never swaps the browser outside WSL", async () => {
+ setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ const findFullChrome = vi.fn(() => "/full/chrome");
+ expect(
+ await resolveBrowserGpuMode("auto", { platform: "linux", wslHost: notWsl, findFullChrome }),
+ ).toBe("software");
+ expect(findFullChrome).not.toHaveBeenCalled();
+ expect(await resolveCaptureBrowserPath("hardware", { chromePath: "/shell" })).toBe("/shell");
+ });
+
it("falls back to 'software' within the probe budget when the probe page never answers", async () => {
vi.useFakeTimers();
try {
diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts
index d02899c22a..a00053e79f 100644
--- a/packages/engine/src/services/browserManager.ts
+++ b/packages/engine/src/services/browserManager.ts
@@ -15,7 +15,12 @@ import { homedir } from "os";
import { chromeMajorCeiling, exceedsChromeCeiling } from "./chromeHostCeiling.js";
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
-import { describeWslGpuAccess, type WslHostFacts } from "./wslHost.js";
+import {
+ describeWslGpuAccess,
+ detectWsl,
+ type FullChromeRoute,
+ type WslHostFacts,
+} from "./wslHost.js";
import {
BrowserLeasePool,
type BrowserLaunchFingerprint,
@@ -85,6 +90,8 @@ interface GpuProbeOptions {
platform?: NodeJS.Platform;
probeLifecycle?: GpuProbeLifecycle;
wslHost?: WslHostFacts;
+ /** Finds full Chrome for the WSL fallback; tests pass a fake. */
+ findFullChrome?: () => string | undefined;
}
const GPU_PROBE_TIMEOUT_MS = 15_000;
@@ -267,6 +274,45 @@ export function resolveHeadlessShellPath(
);
}
+/** Full Chrome for Testing in Puppeteer's cache (`@puppeteer/browsers install chrome@...`), newest first. */
+export function resolveFullChromePath(): string | undefined {
+ const baseDir = join(homedir(), ".cache", "puppeteer", "chrome");
+ let versions: string[];
+ try {
+ versions = readdirSync(baseDir).sort(compareBrowserVersionsDescending);
+ } catch {
+ return undefined;
+ }
+ for (const version of versions) {
+ const candidates = [
+ join(
+ baseDir,
+ version,
+ "chrome-mac-arm64",
+ "Google Chrome for Testing.app",
+ "Contents",
+ "MacOS",
+ "Google Chrome for Testing",
+ ),
+ join(
+ baseDir,
+ version,
+ "chrome-mac-x64",
+ "Google Chrome for Testing.app",
+ "Contents",
+ "MacOS",
+ "Google Chrome for Testing",
+ ),
+ join(baseDir, version, "chrome-linux64", "chrome"),
+ join(baseDir, version, "chrome-win64", "chrome.exe"),
+ ];
+ for (const binary of candidates) {
+ if (existsSync(binary)) return binary;
+ }
+ }
+ return undefined;
+}
+
// Preserve the producer-era export so re-export shims keep the same public API.
export const ENABLE_BROWSER_POOL = DEFAULT_CONFIG.enableBrowserPool;
@@ -499,6 +545,8 @@ interface GpuProbeOutcome {
cause?: "no-gpu" | "probe-error";
/** Under WSL, what we checked on its GPU path (see describeWslGpuAccess). */
wslAccess?: string[];
+ /** Under WSL, the full Chrome that reached the GPU after the headless shell did not. */
+ browserPath?: string;
}
/**
@@ -556,8 +604,6 @@ function formatProbeFailure(err: unknown): string {
}
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({});
const ppt = await getPuppeteerOrNull();
@@ -566,26 +612,64 @@ async function probeAutoBrowserGpuMode(options: GpuProbeOptions): Promise<GpuPro
return { mode: "software", cause: "probe-error" };
}
+ const probed = await probeWebGlMode(ppt, executablePath, options);
+ if (probed.mode === "hardware" || !detectWsl(options.wslHost)) return probed;
+ return probeWslFullChrome(ppt, executablePath, options, probed);
+}
+
+// heygen-com/hyperframes#5548: under WSL, chrome-headless-shell can fail EGL
+// setup on Mesa's D3D12 driver while full Chrome (--headless=new) gets the GPU.
+async function probeWslFullChrome(
+ ppt: PuppeteerNode,
+ shellPath: string | undefined,
+ options: GpuProbeOptions,
+ shellOutcome: GpuProbeOutcome,
+): Promise<GpuProbeOutcome> {
+ const fullChrome = (options.findFullChrome ?? resolveFullChromePath)();
+ let route: FullChromeRoute = { state: "missing" };
+ if (fullChrome) {
+ const viaFullChrome =
+ fullChrome === shellPath
+ ? shellOutcome
+ : await probeWebGlMode(ppt, fullChrome, options, "full Chrome: ");
+ if (viaFullChrome.mode === "hardware") return { mode: "hardware", browserPath: fullChrome };
+ route = { state: viaFullChrome.cause ?? "no-gpu", path: fullChrome };
+ }
+ return { ...shellOutcome, wslAccess: describeWslGpuAccess(options.wslHost, route) ?? undefined };
+}
+
+async function probeWebGlMode(
+ ppt: PuppeteerNode,
+ executablePath: string | undefined,
+ options: GpuProbeOptions,
+ label = "",
+): Promise<GpuProbeOutcome> {
try {
const info = await probeHardwareWebGlInfo(ppt, {
- args: getHardwareGpuProbeArgs(platform),
- browserTimeout,
+ args: getHardwareGpuProbeArgs(options.platform ?? process.platform),
+ browserTimeout: options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
executablePath,
probeLifecycle: options.probeLifecycle,
});
const resolved = resolveWebGlProbeMode(info);
- logResolvedBrowserGpuMode(resolved, describeWebGlProbe(info));
- if (resolved === "hardware") return { mode: "hardware" };
- return { mode: "software", cause: "no-gpu", ...wslAccess(options) };
+ logResolvedBrowserGpuMode(resolved, label + describeWebGlProbe(info));
+ return resolved === "hardware" ? { mode: "hardware" } : { mode: "software", cause: "no-gpu" };
} catch (err) {
- logResolvedBrowserGpuMode("software", formatProbeFailure(err));
- return { mode: "software", cause: "probe-error", ...wslAccess(options) };
+ logResolvedBrowserGpuMode("software", label + formatProbeFailure(err));
+ return { mode: "software", cause: "probe-error" };
}
}
-function wslAccess(options: GpuProbeOptions): Pick<GpuProbeOutcome, "wslAccess"> {
- const lines = describeWslGpuAccess(options.wslHost);
- return lines ? { wslAccess: lines } : {};
+/**
+ * The browser a render launches for `resolvedMode`: under WSL, the full Chrome
+ * the GPU probe fell back to; otherwise the headless shell.
+ */
+export async function resolveCaptureBrowserPath(
+ resolvedMode: "software" | "hardware",
+ config?: Partial<Pick<EngineConfig, "chromePath">>,
+): Promise<string | undefined> {
+ const probed = resolvedMode === "hardware" ? await _autoBrowserGpuModeCache : undefined;
+ return probed?.browserPath ?? resolveHeadlessShellPath(config);
}
/**
diff --git a/packages/engine/src/services/frameCapture-wslFullChrome.test.ts b/packages/engine/src/services/frameCapture-wslFullChrome.test.ts
new file mode 100644
index 0000000000..81a5a3a88d
--- /dev/null
+++ b/packages/engine/src/services/frameCapture-wslFullChrome.test.ts
@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createCaptureSession } from "./frameCapture.js";
+
+const SHELL = "/cache/chrome-headless-shell";
+const FULL_CHROME = "/cache/puppeteer/chrome/linux-152/chrome-linux64/chrome";
+const launches: { args: string[]; chromePath?: string }[] = [];
+let captureBrowser = SHELL;
+
+vi.mock("./browserManager.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./browserManager.js")>()),
+ resolveHeadlessShellPath: () => SHELL,
+ resolveBrowserGpuMode: async () => "hardware",
+ resolveCaptureBrowserPath: async () => captureBrowser,
+ acquireBrowser: async (args: string[], config?: { chromePath?: string }) => {
+ launches.push({ args, chromePath: config?.chromePath });
+ throw new Error("launch recorded");
+ },
+}));
+
+const dirs: string[] = [];
+const platform = process.platform;
+afterEach(() => {
+ launches.length = 0;
+ Object.defineProperty(process, "platform", { value: platform });
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+async function launchOnLinux() {
+ Object.defineProperty(process, "platform", { value: "linux" });
+ const dir = mkdtempSync(join(tmpdir(), "hf-wsl-full-chrome-"));
+ dirs.push(dir);
+ await expect(
+ createCaptureSession(
+ "http://localhost:0",
+ dir,
+ { width: 640, height: 360, fps: { num: 30, den: 1 }, format: "jpeg", requiresWebGpu: false },
+ null,
+ { forceScreenshot: false, browserGpuMode: "auto" },
+ ),
+ ).rejects.toThrow("launch recorded");
+ return launches.at(-1)!;
+}
+
+describe("capture session under the WSL full-Chrome GPU route (#5548)", () => {
+ it("launches the full Chrome the GPU probe chose, by screenshot", async () => {
+ captureBrowser = FULL_CHROME;
+ const launch = await launchOnLinux();
+ expect(launch.chromePath).toBe(FULL_CHROME);
+ expect(launch.args).not.toContain("--enable-begin-frame-control");
+ });
+
+ it("keeps BeginFrame on the headless shell", async () => {
+ captureBrowser = SHELL;
+ const launch = await launchOnLinux();
+ expect(launch.chromePath).toBe(SHELL);
+ expect(launch.args).toContain("--enable-begin-frame-control");
+ });
+});
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index 0ffe036bee..9547335504 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -49,6 +49,7 @@ import {
forceReleaseBrowser,
buildChromeArgs,
resolveBrowserGpuMode,
+ resolveCaptureBrowserPath,
resolveHeadlessShellPath,
compositionRequiresWebGpu,
assertWebGpuAdapterAvailable,
@@ -1306,8 +1307,11 @@ export async function createCaptureSession(
resolvedGpuMode,
config,
);
+ const browserPath = await resolveCaptureBrowserPath(resolvedGpuMode, config);
+ const wslFullChromeHasNoBeginFrame = browserPath !== headlessShell;
const preMode: CaptureMode =
headlessShell &&
+ !wslFullChromeHasNoBeginFrame &&
isLinux &&
!effectiveForceScreenshot &&
!supersampling &&
@@ -1330,7 +1334,7 @@ export async function createCaptureSession(
gpuConfig,
);
- const browserLease = await acquireBrowser(chromeArgs, config);
+ const browserLease = await acquireBrowser(chromeArgs, { ...config, chromePath: browserPath });
return constructCaptureSessionWithRollback({
browserLease,
serverUrl,
diff --git a/packages/engine/src/services/hdrCapture.ts b/packages/engine/src/services/hdrCapture.ts
index 6a1867ae8b..d71a7a9a78 100644
--- a/packages/engine/src/services/hdrCapture.ts
+++ b/packages/engine/src/services/hdrCapture.ts
@@ -20,10 +20,7 @@
*/
import type { Page, Browser, PuppeteerNode } from "puppeteer-core";
-import { existsSync, readdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-import { sigintLaunchOptions } from "./browserManager.js";
+import { resolveFullChromePath, sigintLaunchOptions } from "./browserManager.js";
// ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
@@ -220,40 +217,6 @@ export function float16ToPqRgb(
// ── Chrome launch ─────────────────────────────────────────────────────────────
-function resolveHeadedChromePath(): string | undefined {
- const baseDir = join(homedir(), ".cache", "puppeteer", "chrome");
- if (!existsSync(baseDir)) return undefined;
- const versions = readdirSync(baseDir).sort().reverse();
- for (const version of versions) {
- const candidates = [
- join(
- baseDir,
- version,
- "chrome-mac-arm64",
- "Google Chrome for Testing.app",
- "Contents",
- "MacOS",
- "Google Chrome for Testing",
- ),
- join(
- baseDir,
- version,
- "chrome-mac-x64",
- "Google Chrome for Testing.app",
- "Contents",
- "MacOS",
- "Google Chrome for Testing",
- ),
- join(baseDir, version, "chrome-linux64", "chrome"),
- join(baseDir, version, "chrome-win64", "chrome.exe"),
- ];
- for (const binary of candidates) {
- if (existsSync(binary)) return binary;
- }
- }
- return undefined;
-}
-
/**
* Launch a headed Chrome browser with WebGPU enabled.
*/
@@ -275,7 +238,7 @@ export async function launchHdrBrowser(
}
if (!ppt) throw new Error("Neither puppeteer nor puppeteer-core found");
- const chromePath = resolveHeadedChromePath();
+ const chromePath = resolveFullChromePath();
if (!chromePath) {
throw new Error(
"[HDR] No Chrome binary found. Install: npx @puppeteer/browsers install chrome@stable",
diff --git a/packages/engine/src/services/wslHost.test.ts b/packages/engine/src/services/wslHost.test.ts
index 2e93608a81..be6c2bcee0 100644
--- a/packages/engine/src/services/wslHost.test.ts
+++ b/packages/engine/src/services/wslHost.test.ts
@@ -84,6 +84,28 @@ describe("describeWslGpuAccess", () => {
expect(missing).not.toContain("usermod");
});
+ it("does not promise the group change alone gets the GPU", () => {
+ const text = note(fakeHost());
+ expect(text).toContain("On its own that may not be enough");
+ expect(text).toContain(
+ "npx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer",
+ );
+ expect(text).toContain("HYPERFRAMES_BROWSER_PATH");
+ });
+
+ it("names full Chrome and native Windows as routes once permissions are fine", () => {
+ const host = fakeHost({ renderNodeAccess: () => ({ state: "read-write" }) });
+ const missing = describeWslGpuAccess(host, { state: "missing" })?.join("\n");
+ expect(missing).toContain("full Chrome can");
+ expect(missing).toContain("native Windows");
+ const tried = describeWslGpuAccess(host, { state: "no-gpu", path: "/c/chrome" })?.join("\n");
+ expect(tried).toContain("Full Chrome (/c/chrome) found no hardware GPU either.");
+ expect(tried).not.toContain("@puppeteer/browsers install");
+ expect(tried).toContain("native Windows");
+ const timedOut = describeWslGpuAccess(host, { state: "probe-error", path: "/c/chrome" });
+ expect(timedOut?.join("\n")).toContain("could not finish its GPU check either");
+ });
+
it("returns null outside WSL", () => {
expect(describeWslGpuAccess(fakeHost({ platform: "darwin" }))).toBeNull();
});
diff --git a/packages/engine/src/services/wslHost.ts b/packages/engine/src/services/wslHost.ts
index db1d0a97b5..5f49ff40a7 100644
--- a/packages/engine/src/services/wslHost.ts
+++ b/packages/engine/src/services/wslHost.ts
@@ -67,36 +67,58 @@ export function detectWsl(host: WslHostFacts = realHost): boolean {
const RENDER_NODE = "/dev/dri/renderD128";
+export type FullChromeRoute =
+ | { state: "missing" }
+ | { state: "no-gpu" | "probe-error"; path: string };
+
const NATIVE_WINDOWS =
"render from native Windows (project copied to a Windows drive, run from PowerShell), " +
"where Chrome uses the GPU through Direct3D.";
+function routeToGpu(fullChrome: FullChromeRoute): string[] {
+ const viaFullChrome =
+ fullChrome.state === "missing"
+ ? [
+ " Under WSL, Chrome's headless shell often cannot reach the GPU while full Chrome can. " +
+ "Install full Chrome with `npx @puppeteer/browsers install chrome@stable --path " +
+ "~/.cache/puppeteer` and HyperFrames will try it when the headless shell finds no GPU " +
+ "(or point HYPERFRAMES_BROWSER_PATH at a full Chrome).",
+ ]
+ : fullChrome.state === "no-gpu"
+ ? [` Full Chrome (${fullChrome.path}) found no hardware GPU either.`]
+ : [` Full Chrome (${fullChrome.path}) could not finish its GPU check either.`];
+ return [...viaFullChrome, ` Or ${NATIVE_WINDOWS}`];
+}
+
/**
* Indented lines saying what we checked on the WSL GPU path and what to try,
* or null outside WSL. Says nothing about the render mode: callers own that.
*/
-export function describeWslGpuAccess(host: WslHostFacts = realHost): string[] | null {
+export function describeWslGpuAccess(
+ host: WslHostFacts = realHost,
+ fullChrome: FullChromeRoute = { state: "missing" },
+): string[] | null {
if (!detectWsl(host)) return null;
const access = host.renderNodeAccess(RENDER_NODE);
if (access.state === "denied" && !access.userInGroup) {
return [
` Your Linux user cannot read and write ${RENDER_NODE} and is not in its group ` +
`("${access.group}"), which can stop Mesa from reaching the GPU.`,
- ` Fix: run \`sudo usermod -aG ${access.group} $USER\`, then \`wsl --shutdown\` from ` +
- "Windows, reopen WSL and render again.",
- ` Or ${NATIVE_WINDOWS}`,
+ ` First run \`sudo usermod -aG ${access.group} $USER\`, then \`wsl --shutdown\` from ` +
+ "Windows and reopen WSL. On its own that may not be enough:",
+ ...routeToGpu(fullChrome),
];
}
if (access.state === "denied") {
return [
` Your Linux user is in the "${access.group}" group but still cannot read and write ` +
`${RENDER_NODE}; check its permissions with \`ls -l ${RENDER_NODE}\`.`,
- ` Or ${NATIVE_WINDOWS}`,
+ ...routeToGpu(fullChrome),
];
}
const seen = access.state === "missing" ? "does not exist" : "is readable and writable";
return [
` ${RENDER_NODE} ${seen}, so file permissions are not the cause.`,
- ` To use the GPU, ${NATIVE_WINDOWS}`,
+ ...routeToGpu(fullChrome),
];
}