Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.mdxindex 72a85ddcd9..cd7d696d23 100644--- a/docs/guides/troubleshooting.mdx+++ b/docs/guides/troubleshooting.mdx@@ -249,18 +249,6 @@ sudo usermod -aG render $USERwsl --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 toa Windows drive (for example `C:\Users\you\renders\my-video`) and run the samecommand 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.tsindex 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>): stringreturn 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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<GpuProreturn { 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: stconsole.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 = createBrowserLaunchFingerexport 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.tsdeleted file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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") {