Skip to content

Write HTML. Render video. Built for agents.

fix(engine): renders under WSL reach the GPU on Chrome 150 and later (#5591)

Miguel Ángel38cfcdd56cdc
diff --git a/docs/guides/troubleshooting.mdx b/docs/guides/troubleshooting.mdx
index 72a85ddcd9..cd7d696d23 100644
--- a/docs/guides/troubleshooting.mdx
+++ b/docs/guides/troubleshooting.mdx
@@ -249,18 +249,6 @@ 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/browserLeasePool.ts b/packages/engine/src/services/browserLeasePool.ts
index 8a4b9e8141..3ce7123a52 100644
--- a/packages/engine/src/services/browserLeasePool.ts
+++ b/packages/engine/src/services/browserLeasePool.ts
@@ -6,6 +6,7 @@ export type BrowserPoolState = "launching" | "ready" | "closing";
export interface BrowserLaunchFingerprint {
readonly args: readonly string[];
readonly executablePath?: string;
+ readonly withoutWaylandDisplay?: boolean;
readonly browserTimeoutMs: number;
readonly protocolTimeoutMs: number;
readonly requestedCaptureMode: CaptureMode;
@@ -55,6 +56,7 @@ function fingerprintKey(fingerprint: Readonly<BrowserLaunchFingerprint>): string
return JSON.stringify([
fingerprint.args,
fingerprint.executablePath ?? null,
+ fingerprint.withoutWaylandDisplay === true,
fingerprint.browserTimeoutMs,
fingerprint.protocolTimeoutMs,
fingerprint.requestedCaptureMode,
diff --git a/packages/engine/src/services/browserManager-wslEnv.test.ts b/packages/engine/src/services/browserManager-wslEnv.test.ts
new file mode 100644
index 0000000000..4850ac246c
--- /dev/null
+++ b/packages/engine/src/services/browserManager-wslEnv.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { LaunchOptions, PuppeteerNode } from "puppeteer-core";
+import {
+ _resetAutoBrowserGpuModeCacheForTests,
+ _resetBrowserPoolForTests,
+ _setPuppeteerForTests,
+ acquireBrowser,
+ captureWithoutWaylandDisplay,
+ drainBrowserPool,
+ resolveBrowserGpuMode,
+} from "./browserManager.js";
+
+const wsl = {
+ platform: "linux" as const,
+ release: "6.6.87.2-microsoft-standard-WSL2",
+ readProcVersion: () => "Linux version 6.6.87.2-microsoft-standard-WSL2",
+ renderNodeAccess: () => ({ state: "read-write" as const }),
+};
+const D3D12 = {
+ hasWebGL: true,
+ vendor: "Google Inc. (Microsoft Corporation)",
+ renderer: "ANGLE (Microsoft Corporation, D3D12 (NVIDIA GeForce RTX 4070 SUPER))",
+};
+const NO_WEBGL = { hasWebGL: false, vendor: "", renderer: "" };
+
+/** Chrome that reaches the GPU only when `reachesGpu(env)` holds for its launch env. */
+function fakeChrome(reachesGpu: (env: NodeJS.ProcessEnv | undefined) => boolean) {
+ const launch = vi.fn(async (options: LaunchOptions) => ({
+ connected: true,
+ newPage: vi.fn().mockResolvedValue({
+ evaluate: vi.fn().mockResolvedValue(reachesGpu(options.env) ? D3D12 : NO_WEBGL),
+ }),
+ version: vi.fn().mockResolvedValue("HeadlessChrome/152.0.7977.30"),
+ close: vi.fn().mockResolvedValue(undefined),
+ disconnect: vi.fn(),
+ process: () => ({ kill: vi.fn(), killed: false }),
+ }));
+ _setPuppeteerForTests({ launch } as unknown as PuppeteerNode);
+ return launch;
+}
+const offWayland = (env: NodeJS.ProcessEnv | undefined) =>
+ env !== undefined && env.WAYLAND_DISPLAY === undefined;
+
+// heygen-com/hyperframes#5548: Chrome 150+ under WSLg finds no GPU while WAYLAND_DISPLAY is set.
+describe("WSL GPU without WAYLAND_DISPLAY", () => {
+ const savedWayland = process.env.WAYLAND_DISPLAY;
+
+ beforeEach(() => {
+ process.env.WAYLAND_DISPLAY = "wayland-0";
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ vi.spyOn(console, "log").mockImplementation(() => {});
+ });
+
+ afterEach(async () => {
+ await drainBrowserPool();
+ _resetBrowserPoolForTests();
+ _resetAutoBrowserGpuModeCacheForTests();
+ _setPuppeteerForTests(undefined);
+ if (savedWayland === undefined) delete process.env.WAYLAND_DISPLAY;
+ else process.env.WAYLAND_DISPLAY = savedWayland;
+ vi.restoreAllMocks();
+ });
+
+ it("renders on the GPU without WAYLAND_DISPLAY when only that reaches it", async () => {
+ const launch = fakeChrome(offWayland);
+ expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost: wsl })).toBe(
+ "hardware",
+ );
+ const withoutWaylandDisplay = await captureWithoutWaylandDisplay("hardware");
+ expect(withoutWaylandDisplay).toBe(true);
+ const lease = await acquireBrowser(["--no-sandbox"], {
+ forceScreenshot: true,
+ withoutWaylandDisplay,
+ });
+ await lease.release();
+
+ const envs = launch.mock.calls.map(([options]) => options.env);
+ expect(envs[0]).toBeUndefined();
+ expect(envs[1]).toMatchObject({ PATH: process.env.PATH });
+ expect(envs[1]).not.toHaveProperty("WAYLAND_DISPLAY");
+ expect(envs[2]).not.toHaveProperty("WAYLAND_DISPLAY");
+ });
+
+ it("keeps the inherited environment when neither probe reaches the GPU", async () => {
+ const launch = fakeChrome(() => false);
+ expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost: wsl })).toBe(
+ "software",
+ );
+ expect(await captureWithoutWaylandDisplay("hardware")).toBe(false);
+ expect(launch).toHaveBeenCalledTimes(2);
+ });
+
+ it("keeps the inherited environment when the first probe reaches the GPU", async () => {
+ const launch = fakeChrome(() => true);
+ expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost: wsl })).toBe(
+ "hardware",
+ );
+ expect(await captureWithoutWaylandDisplay("hardware")).toBe(false);
+ expect(launch).toHaveBeenCalledTimes(1);
+ });
+
+ it("never drops WAYLAND_DISPLAY for a software render", async () => {
+ fakeChrome(offWayland);
+ await resolveBrowserGpuMode("auto", { platform: "linux", wslHost: wsl });
+ expect(await captureWithoutWaylandDisplay("software")).toBe(false);
+ });
+
+ it("tries only once outside WSL", async () => {
+ const launch = fakeChrome(offWayland);
+ const linux = { ...wsl, release: "6.8.0-45-generic", readProcVersion: () => "Linux 6.8.0" };
+ expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost: linux })).toBe(
+ "software",
+ );
+ expect(launch).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts
index 19206acf6f..0c0476e9ff 100644
--- a/packages/engine/src/services/browserManager.test.ts
+++ b/packages/engine/src/services/browserManager.test.ts
@@ -27,7 +27,6 @@ import {
releaseBrowser,
resolveHeadlessShellPath,
resolveBrowserGpuMode,
- resolveCaptureBrowserPath,
resolveFullChromePath,
} from "./browserManager.js";
@@ -483,88 +482,6 @@ 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(() => {}) }),
@@ -578,18 +495,8 @@ 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,
- findFullChrome: noFullChrome,
- }),
- ).toBe("software");
- await resolveBrowserGpuMode("auto", {
- platform: "linux",
- wslHost,
- findFullChrome: noFullChrome,
- });
+ expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("software");
+ await resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
const text = output(error);
expect(text).toContain("browserGpuMode probe → software (WebGL unavailable)");
expect(text).toContain(
@@ -605,11 +512,7 @@ describe("resolveBrowserGpuMode", () => {
try {
neverAnsweringProbe();
const error = vi.spyOn(console, "error").mockImplementation(() => {});
- const mode = resolveBrowserGpuMode("auto", {
- platform: "linux",
- wslHost,
- findFullChrome: noFullChrome,
- });
+ const mode = resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
await vi.advanceTimersByTimeAsync(15_000 + 250);
await expect(mode).resolves.toBe("software");
const text = output(error);
@@ -627,11 +530,7 @@ describe("resolveBrowserGpuMode", () => {
neverAnsweringProbe();
const error = vi.spyOn(console, "error").mockImplementation(() => {});
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
- const mode = resolveBrowserGpuMode("hardware", {
- platform: "linux",
- wslHost,
- findFullChrome: noFullChrome,
- });
+ const mode = resolveBrowserGpuMode("hardware", { platform: "linux", wslHost });
await vi.advanceTimersByTimeAsync(15_000 + 250);
await expect(mode).resolves.toBe("hardware");
const warning = output(warn);
@@ -651,13 +550,9 @@ 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,
- findFullChrome: noFullChrome,
- }),
- ).toBe("hardware");
+ expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
+ "hardware",
+ );
const warning = output(warn);
expect(warning).toContain("GPU probe could not run");
expect(warning).toContain("hyperframes doctor");
@@ -669,13 +564,9 @@ 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,
- findFullChrome: noFullChrome,
- }),
- ).toBe("hardware");
+ expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
+ "hardware",
+ );
const warning = output(warn);
expect(warning).toContain("sudo usermod -aG render $USER");
expect(warning).not.toContain("--gpus all");
@@ -689,13 +580,7 @@ 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,
- findFullChrome: noFullChrome,
- }),
- ).toBe("hardware");
+ expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("hardware");
expect(output(error)).not.toContain("WSL");
});
});
@@ -714,17 +599,6 @@ describe("resolveBrowserGpuMode", () => {
}
});
- 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 a00053e79f..d347e7aacc 100644
--- a/packages/engine/src/services/browserManager.ts
+++ b/packages/engine/src/services/browserManager.ts
@@ -15,12 +15,7 @@ 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,
- detectWsl,
- type FullChromeRoute,
- type WslHostFacts,
-} from "./wslHost.js";
+import { describeWslGpuAccess, detectWsl, type WslHostFacts } from "./wslHost.js";
import {
BrowserLeasePool,
type BrowserLaunchFingerprint,
@@ -90,8 +85,6 @@ 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;
@@ -103,6 +96,7 @@ async function probeHardwareWebGlInfo(
browserTimeout: number;
executablePath: string | undefined;
probeLifecycle?: GpuProbeLifecycle;
+ env?: NodeJS.ProcessEnv;
},
): Promise<WebGlProbeInfo> {
let probeBrowser: Browser | undefined;
@@ -113,6 +107,7 @@ async function probeHardwareWebGlInfo(
args: options.args,
defaultViewport: { width: 64, height: 64 },
executablePath: options.executablePath,
+ env: options.env,
timeout: options.browserTimeout,
waitForInitialPage: false,
};
@@ -545,8 +540,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;
+ /** Under WSL, Chrome reached the GPU only without WSLg's WAYLAND_DISPLAY. */
+ withoutWaylandDisplay?: boolean;
}
/**
@@ -604,7 +599,6 @@ function formatProbeFailure(err: unknown): string {
}
async function probeAutoBrowserGpuMode(options: GpuProbeOptions): Promise<GpuProbeOutcome> {
- const executablePath = options.chromePath ?? resolveHeadlessShellPath({});
const ppt = await getPuppeteerOrNull();
if (ppt === null) {
@@ -612,44 +606,30 @@ 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 };
+ const probed = await probeWebGlMode(ppt, options);
+ if (probed.mode === "hardware") return probed;
+ // Chrome 150+ uses WSLg Wayland EGL, which lacks offscreen configs: https://issues.chromium.org/issues/567222741
+ if (detectWsl(options.wslHost) && process.env.WAYLAND_DISPLAY !== undefined) {
+ const env = envWithoutWaylandDisplay();
+ const retried = await probeWebGlMode(ppt, options, env, "without WAYLAND_DISPLAY: ");
+ if (retried.mode === "hardware") return { mode: "hardware", withoutWaylandDisplay: true };
}
- return { ...shellOutcome, wslAccess: describeWslGpuAccess(options.wslHost, route) ?? undefined };
+ return { ...probed, ...wslAccess(options) };
}
async function probeWebGlMode(
ppt: PuppeteerNode,
- executablePath: string | undefined,
options: GpuProbeOptions,
+ env?: NodeJS.ProcessEnv,
label = "",
): Promise<GpuProbeOutcome> {
try {
const info = await probeHardwareWebGlInfo(ppt, {
args: getHardwareGpuProbeArgs(options.platform ?? process.platform),
browserTimeout: options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
- executablePath,
+ executablePath: options.chromePath ?? resolveHeadlessShellPath({}),
probeLifecycle: options.probeLifecycle,
+ env,
});
const resolved = resolveWebGlProbeMode(info);
logResolvedBrowserGpuMode(resolved, label + describeWebGlProbe(info));
@@ -660,16 +640,22 @@ async function probeWebGlMode(
}
}
-/**
- * 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(
+function envWithoutWaylandDisplay(): NodeJS.ProcessEnv {
+ const { WAYLAND_DISPLAY: _wslg, ...env } = process.env;
+ return env;
+}
+
+/** True when a `resolvedMode` render must launch without WAYLAND_DISPLAY to reach the GPU. */
+export async function captureWithoutWaylandDisplay(
resolvedMode: "software" | "hardware",
- config?: Partial<Pick<EngineConfig, "chromePath">>,
-): Promise<string | undefined> {
- const probed = resolvedMode === "hardware" ? await _autoBrowserGpuModeCache : undefined;
- return probed?.browserPath ?? resolveHeadlessShellPath(config);
+): Promise<boolean> {
+ if (resolvedMode !== "hardware") return false;
+ return (await _autoBrowserGpuModeCache)?.withoutWaylandDisplay === true;
+}
+
+function wslAccess(options: GpuProbeOptions): Pick<GpuProbeOutcome, "wslAccess"> {
+ const lines = describeWslGpuAccess(options.wslHost);
+ return lines ? { wslAccess: lines } : {};
}
/**
@@ -809,11 +795,13 @@ function logResolvedBrowserGpuMode(resolved: "hardware" | "software", reason: st
console.error(`[hyperframes] browserGpuMode probe → ${resolved} (${reason})`);
}
+type BrowserLaunchConfig = Partial<
+ Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">
+> & { withoutWaylandDisplay?: boolean };
+
function createBrowserLaunchFingerprint(
chromeArgs: string[],
- config?: Partial<
- Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">
- >,
+ config?: BrowserLaunchConfig,
): BrowserLaunchFingerprint {
const launchConfig = {
browserTimeout: DEFAULT_CONFIG.browserTimeout,
@@ -838,6 +826,7 @@ function createBrowserLaunchFingerprint(
return {
args: chromeArgs,
executablePath: headlessShell,
+ withoutWaylandDisplay: launchConfig.withoutWaylandDisplay === true,
browserTimeoutMs: launchConfig.browserTimeout,
protocolTimeoutMs: launchConfig.protocolTimeout,
requestedCaptureMode,
@@ -849,12 +838,7 @@ export const _createBrowserLaunchFingerprintForTests = createBrowserLaunchFinger
export async function acquireBrowser(
chromeArgs: string[],
- config?: Partial<
- Pick<
- EngineConfig,
- "browserTimeout" | "protocolTimeout" | "enableBrowserPool" | "chromePath" | "forceScreenshot"
- >
- >,
+ config?: BrowserLaunchConfig & Partial<Pick<EngineConfig, "enableBrowserPool">>,
): Promise<AcquiredBrowser> {
const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;
return browserLeasePool.acquire(createBrowserLaunchFingerprint(chromeArgs, config), enablePool);
@@ -865,6 +849,7 @@ async function launchBrowser(
fingerprint: Readonly<BrowserLaunchFingerprint>,
): Promise<{ browser: Browser; captureMode: CaptureMode }> {
const ppt = await getPuppeteer();
+ const env = fingerprint.withoutWaylandDisplay ? envWithoutWaylandDisplay() : undefined;
let captureMode = fingerprint.requestedCaptureMode;
let browser: Browser | undefined;
try {
@@ -874,6 +859,7 @@ async function launchBrowser(
args: [...fingerprint.args],
defaultViewport: null,
executablePath: fingerprint.executablePath,
+ env,
timeout: fingerprint.browserTimeoutMs,
protocolTimeout: fingerprint.protocolTimeoutMs,
});
@@ -906,6 +892,7 @@ async function launchBrowser(
args: stripBeginFrameFlags([...fingerprint.args]),
defaultViewport: null,
executablePath: fingerprint.executablePath,
+ env,
timeout: fingerprint.browserTimeoutMs,
protocolTimeout: fingerprint.protocolTimeoutMs,
});
diff --git a/packages/engine/src/services/frameCapture-wslFullChrome.test.ts b/packages/engine/src/services/frameCapture-wslFullChrome.test.ts
deleted file mode 100644
index 81a5a3a88d..0000000000
--- a/packages/engine/src/services/frameCapture-wslFullChrome.test.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-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-wslWayland.test.ts b/packages/engine/src/services/frameCapture-wslWayland.test.ts
new file mode 100644
index 0000000000..a3bb54005c
--- /dev/null
+++ b/packages/engine/src/services/frameCapture-wslWayland.test.ts
@@ -0,0 +1,52 @@
+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 launches: { withoutWaylandDisplay?: boolean }[] = [];
+let gpuNeedsNoWayland = false;
+
+vi.mock("./browserManager.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./browserManager.js")>()),
+ resolveBrowserGpuMode: async () => "hardware",
+ captureWithoutWaylandDisplay: async () => gpuNeedsNoWayland,
+ acquireBrowser: async (_args: string[], config?: { withoutWaylandDisplay?: boolean }) => {
+ launches.push({ withoutWaylandDisplay: config?.withoutWaylandDisplay });
+ throw new Error("launch recorded");
+ },
+}));
+
+const dirs: string[] = [];
+afterEach(() => {
+ launches.length = 0;
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+async function launchCapture() {
+ const dir = mkdtempSync(join(tmpdir(), "hf-wsl-wayland-"));
+ dirs.push(dir);
+ await expect(
+ createCaptureSession(
+ "http://localhost:0",
+ dir,
+ { width: 640, height: 360, fps: { num: 30, den: 1 }, format: "jpeg", requiresWebGpu: false },
+ null,
+ { browserGpuMode: "auto" },
+ ),
+ ).rejects.toThrow("launch recorded");
+ return launches.at(-1)!;
+}
+
+// heygen-com/hyperframes#5548: the render browser starts the way the GPU probe reached the GPU.
+describe("capture session under WSL", () => {
+ it("launches without WAYLAND_DISPLAY when the GPU probe needed that", async () => {
+ gpuNeedsNoWayland = true;
+ expect((await launchCapture()).withoutWaylandDisplay).toBe(true);
+ });
+
+ it("keeps the inherited environment otherwise", async () => {
+ gpuNeedsNoWayland = false;
+ expect((await launchCapture()).withoutWaylandDisplay).toBe(false);
+ });
+});
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index 9547335504..8e612944e9 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -49,7 +49,7 @@ import {
forceReleaseBrowser,
buildChromeArgs,
resolveBrowserGpuMode,
- resolveCaptureBrowserPath,
+ captureWithoutWaylandDisplay,
resolveHeadlessShellPath,
compositionRequiresWebGpu,
assertWebGpuAdapterAvailable,
@@ -1307,11 +1307,8 @@ export async function createCaptureSession(
resolvedGpuMode,
config,
);
- const browserPath = await resolveCaptureBrowserPath(resolvedGpuMode, config);
- const wslFullChromeHasNoBeginFrame = browserPath !== headlessShell;
const preMode: CaptureMode =
headlessShell &&
- !wslFullChromeHasNoBeginFrame &&
isLinux &&
!effectiveForceScreenshot &&
!supersampling &&
@@ -1334,7 +1331,8 @@ export async function createCaptureSession(
gpuConfig,
);
- const browserLease = await acquireBrowser(chromeArgs, { ...config, chromePath: browserPath });
+ const withoutWaylandDisplay = await captureWithoutWaylandDisplay(resolvedGpuMode);
+ const browserLease = await acquireBrowser(chromeArgs, { ...config, withoutWaylandDisplay });
return constructCaptureSessionWithRollback({
browserLease,
serverUrl,
diff --git a/packages/engine/src/services/parallelWorkerBrowsers.browser.test.ts b/packages/engine/src/services/parallelWorkerBrowsers.browser.test.ts
index f59d26459b..9fcc287e76 100644
--- a/packages/engine/src/services/parallelWorkerBrowsers.browser.test.ts
+++ b/packages/engine/src/services/parallelWorkerBrowsers.browser.test.ts
@@ -69,11 +69,11 @@ describe.skipIf(!hasBrowser)("parallel worker browsers", () => {
expect(openMedia.size).toBeGreaterThanOrEqual(6);
const page = await second.browser.newPage();
- await page.goto(`${origin}/worker`, { timeout: 5_000 });
+ await page.goto(`${origin}/worker`, { timeout: 20_000 });
expect(await page.evaluate(() => document.body.textContent)).toBe("worker");
} finally {
await first.release();
await second.release();
}
- }, 30_000);
+ }, 45_000);
});
diff --git a/packages/engine/src/services/wslHost.test.ts b/packages/engine/src/services/wslHost.test.ts
index be6c2bcee0..2e93608a81 100644
--- a/packages/engine/src/services/wslHost.test.ts
+++ b/packages/engine/src/services/wslHost.test.ts
@@ -84,28 +84,6 @@ 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 5f49ff40a7..db1d0a97b5 100644
--- a/packages/engine/src/services/wslHost.ts
+++ b/packages/engine/src/services/wslHost.ts
@@ -67,58 +67,36 @@ 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,
- fullChrome: FullChromeRoute = { state: "missing" },
-): string[] | null {
+export function describeWslGpuAccess(host: WslHostFacts = realHost): 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.`,
- ` 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),
+ ` Fix: run \`sudo usermod -aG ${access.group} $USER\`, then \`wsl --shutdown\` from ` +
+ "Windows, reopen WSL and render again.",
+ ` Or ${NATIVE_WINDOWS}`,
];
}
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}\`.`,
- ...routeToGpu(fullChrome),
+ ` Or ${NATIVE_WINDOWS}`,
];
}
const seen = access.state === "missing" ? "does not exist" : "is readable and writable";
return [
` ${RENDER_NODE} ${seen}, so file permissions are not the cause.`,
- ...routeToGpu(fullChrome),
+ ` To use the GPU, ${NATIVE_WINDOWS}`,
];
}
diff --git a/scripts/check-no-main-deletions.mjs b/scripts/check-no-main-deletions.mjs
index 38a34bf548..64970ee21d 100644
--- a/scripts/check-no-main-deletions.mjs
+++ b/scripts/check-no-main-deletions.mjs
@@ -1163,6 +1163,10 @@ export const ALLOWED_DELETIONS = new Map([
["docs/contracts/2026-10-02-thumbnail-document-lifetime.html", DESIGN_NOTES_REASON],
["docs/contracts/2026-10-05-transcribe-language-progress.html", DESIGN_NOTES_REASON],
["docs/plans/2026-09-26-image-thumbnails.md", DESIGN_NOTES_REASON],
+ [
+ "packages/engine/src/services/frameCapture-wslFullChrome.test.ts",
+ "tests the WSL full-Chrome GPU fallback, replaced by the probe without WAYLAND_DISPLAY (frameCapture-wslWayland.test.ts)",
+ ],
]);
export function parseBase(argv, fallback = "origin/main") {