Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.mdxindex cd7d696d23..72a85ddcd9 100644--- a/docs/guides/troubleshooting.mdx+++ b/docs/guides/troubleshooting.mdx@@ -249,6 +249,18 @@ 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/browserManager.test.ts b/packages/engine/src/services/browserManager.test.tsindex 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.tsindex 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<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 };+ }+ 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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),];}