@hyperframes/engine 0.8.156 → 0.8.158

package/dist/services/browserLeasePool.d.ts

@@ -4,6 +4,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;

package/dist/services/browserLeasePool.js

@@ -8,6 +8,7 @@ function fingerprintKey(fingerprint) {
     return JSON.stringify([
         fingerprint.args,
         fingerprint.executablePath ?? null,
+        fingerprint.withoutWaylandDisplay === true,
         fingerprint.browserTimeoutMs,
         fingerprint.protocolTimeoutMs,
         fingerprint.requestedCaptureMode,

package/dist/services/browserManager.d.ts

@@ -25,8 +25,6 @@ interface GpuProbeOptions {
     platform?: NodeJS.Platform;
     probeLifecycle?: GpuProbeLifecycle;
     wslHost?: WslHostFacts;
-    /** Finds full Chrome for the WSL fallback; tests pass a fake. */
-    findFullChrome?: () => string | undefined;
 }
 export type AcquiredBrowser = BrowserLease;
 /**
@@ -59,11 +57,8 @@ export declare const _probeBeginFrameSupportForTests: typeof probeBeginFrameSupp
 export declare const _closeBrowserAfterFailedProbeForTests: typeof closeBrowserAfterFailedProbe;
 /** Test-only: reset the cached probe result. */
 export declare function _resetAutoBrowserGpuModeCacheForTests(): void;
-/**
- * The browser a render launches for `resolvedMode`: under WSL, the full Chrome
- * the GPU probe fell back to; otherwise the headless shell.
- */
-export declare function resolveCaptureBrowserPath(resolvedMode: "software" | "hardware", config?: Partial<Pick<EngineConfig, "chromePath">>): Promise<string | undefined>;
+/** True when a `resolvedMode` render must launch without WAYLAND_DISPLAY to reach the GPU. */
+export declare function captureWithoutWaylandDisplay(resolvedMode: "software" | "hardware"): Promise<boolean>;
 /**
  * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
  *
@@ -91,10 +86,13 @@ export declare function resolveCaptureBrowserPath(resolvedMode: "software" | "ha
  * render.
  */
 export declare function resolveBrowserGpuMode(mode: EngineConfig["browserGpuMode"], options?: GpuProbeOptions): Promise<"software" | "hardware">;
-declare function createBrowserLaunchFingerprint(chromeArgs: string[], config?: Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">>): BrowserLaunchFingerprint;
+type BrowserLaunchConfig = Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">> & {
+    withoutWaylandDisplay?: boolean;
+};
+declare function createBrowserLaunchFingerprint(chromeArgs: string[], config?: BrowserLaunchConfig): BrowserLaunchFingerprint;
 /** Test-only export for launch-argument/capture-mode agreement. */
 export declare const _createBrowserLaunchFingerprintForTests: typeof createBrowserLaunchFingerprint;
-export declare function acquireBrowser(chromeArgs: string[], config?: Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "enableBrowserPool" | "chromePath" | "forceScreenshot">>): Promise<AcquiredBrowser>;
+export declare function acquireBrowser(chromeArgs: string[], config?: BrowserLaunchConfig & Partial<Pick<EngineConfig, "enableBrowserPool">>): Promise<AcquiredBrowser>;
 export declare function releaseBrowser(browser: Browser, _config?: Partial<Pick<EngineConfig, "enableBrowserPool">>): Promise<void>;
 export declare function forceReleaseBrowser(browser: Browser): void;
 /**

package/dist/services/browserManager.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 import { chromeMajorCeiling, exceedsChromeCeiling } from "./chromeHostCeiling.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
-import { describeWslGpuAccess, detectWsl, } from "./wslHost.js";
+import { describeWslGpuAccess, detectWsl } from "./wslHost.js";
 import { BrowserLeasePool, } from "./browserLeasePool.js";
 export { BrowserLeasePool } from "./browserLeasePool.js";
 let _puppeteer;
@@ -58,6 +58,7 @@ async function probeHardwareWebGlInfo(ppt, options) {
             args: options.args,
             defaultViewport: { width: 64, height: 64 },
             executablePath: options.executablePath,
+            env: options.env,
             timeout: options.browserTimeout,
             waitForInitialPage: false,
         };
@@ -427,39 +428,31 @@ function formatProbeFailure(err) {
     return `probe failed (${err instanceof Error ? err.message : String(err)})`;
 }
 async function probeAutoBrowserGpuMode(options) {
-    const executablePath = options.chromePath ?? resolveHeadlessShellPath({});
     const ppt = await getPuppeteerOrNull();
     if (ppt === null) {
         logResolvedBrowserGpuMode("software", "puppeteer unavailable");
         return { mode: "software", cause: "probe-error" };
     }
-    const probed = await probeWebGlMode(ppt, executablePath, options);
-    if (probed.mode === "hardware" || !detectWsl(options.wslHost))
+    const probed = await probeWebGlMode(ppt, options);
+    if (probed.mode === "hardware")
         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, shellPath, options, shellOutcome) {
-    const fullChrome = (options.findFullChrome ?? resolveFullChromePath)();
-    let route = { 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, executablePath, options, label = "") {
+    // 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 { ...probed, ...wslAccess(options) };
+}
+async function probeWebGlMode(ppt, options, env, label = "") {
     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));
@@ -470,13 +463,19 @@ async function probeWebGlMode(ppt, executablePath, options, label = "") {
         return { mode: "software", cause: "probe-error" };
     }
 }
-/**
- * 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, config) {
-    const probed = resolvedMode === "hardware" ? await _autoBrowserGpuModeCache : undefined;
-    return probed?.browserPath ?? resolveHeadlessShellPath(config);
+function envWithoutWaylandDisplay() {
+    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) {
+    if (resolvedMode !== "hardware")
+        return false;
+    return (await _autoBrowserGpuModeCache)?.withoutWaylandDisplay === true;
+}
+function wslAccess(options) {
+    const lines = describeWslGpuAccess(options.wslHost);
+    return lines ? { wslAccess: lines } : {};
 }
 /**
  * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
@@ -620,6 +619,7 @@ function createBrowserLaunchFingerprint(chromeArgs, config) {
     return {
         args: chromeArgs,
         executablePath: headlessShell,
+        withoutWaylandDisplay: launchConfig.withoutWaylandDisplay === true,
         browserTimeoutMs: launchConfig.browserTimeout,
         protocolTimeoutMs: launchConfig.protocolTimeout,
         requestedCaptureMode,
@@ -634,6 +634,7 @@ export async function acquireBrowser(chromeArgs, config) {
 // fallow-ignore-next-line complexity
 async function launchBrowser(fingerprint) {
     const ppt = await getPuppeteer();
+    const env = fingerprint.withoutWaylandDisplay ? envWithoutWaylandDisplay() : undefined;
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
     try {
@@ -643,6 +644,7 @@ async function launchBrowser(fingerprint) {
             args: [...fingerprint.args],
             defaultViewport: null,
             executablePath: fingerprint.executablePath,
+            env,
             timeout: fingerprint.browserTimeoutMs,
             protocolTimeout: fingerprint.protocolTimeoutMs,
         });
@@ -667,6 +669,7 @@ async function launchBrowser(fingerprint) {
                     args: stripBeginFrameFlags([...fingerprint.args]),
                     defaultViewport: null,
                     executablePath: fingerprint.executablePath,
+                    env,
                     timeout: fingerprint.browserTimeoutMs,
                     protocolTimeout: fingerprint.protocolTimeoutMs,
                 });

package/dist/services/frameCapture.js

@@ -15,7 +15,7 @@ import { DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
-import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, resolveCaptureBrowserPath, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
+import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
 import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
@@ -786,10 +786,7 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     // boolean `forceScreenshot === false` is otherwise ambiguous between
     // default and explicit opt-out).
     const effectiveForceScreenshot = applyConcreteGpuScreenshotClamp(forceScreenshot, resolvedGpuMode, config);
-    const browserPath = await resolveCaptureBrowserPath(resolvedGpuMode, config);
-    const wslFullChromeHasNoBeginFrame = browserPath !== headlessShell;
     const preMode = headlessShell &&
-        !wslFullChromeHasNoBeginFrame &&
         isLinux &&
         !effectiveForceScreenshot &&
         !supersampling &&
@@ -807,7 +804,8 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
             .catch(() => false));
     const gpuConfig = { ...config, browserGpuMode: resolvedGpuMode };
     const chromeArgs = buildChromeArgs({ width: options.width, height: options.height, captureMode: preMode, requiresWebGpu }, 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,

package/dist/services/wslHost.d.ts

@@ -17,14 +17,8 @@ export interface WslHostFacts {
     renderNodeAccess(path: string): RenderNodeAccess;
 }
 export declare function detectWsl(host?: WslHostFacts): boolean;
-export type FullChromeRoute = {
-    state: "missing";
-} | {
-    state: "no-gpu" | "probe-error";
-    path: string;
-};
 /**
  * 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 declare function describeWslGpuAccess(host?: WslHostFacts, fullChrome?: FullChromeRoute): string[] | null;
+export declare function describeWslGpuAccess(host?: WslHostFacts): string[] | null;

package/dist/services/wslHost.js

@@ -57,24 +57,11 @@ export function detectWsl(host = realHost) {
 const RENDER_NODE = "/dev/dri/renderD128";
 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) {
-    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 = realHost, fullChrome = { state: "missing" }) {
+export function describeWslGpuAccess(host = realHost) {
     if (!detectWsl(host))
         return null;
     const access = host.renderNodeAccess(RENDER_NODE);
@@ -82,21 +69,21 @@ export function describeWslGpuAccess(host = realHost, fullChrome = { state: "mis
         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}`,
     ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.156",
+  "version": "0.8.158",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/parsers": "^0.8.156",
-    "@hyperframes/core": "^0.8.156"
+    "@hyperframes/parsers": "^0.8.158",
+    "@hyperframes/core": "^0.8.158"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",