Skip to content

Write HTML. Render video. Built for agents.

fix(cli): WebGPU compositions work in snapshot, check and layout like render (#5354)

Miguel Ángelf85614ecb222
diff --git a/packages/cli/src/browser/gpuPolicy.test.ts b/packages/cli/src/browser/gpuPolicy.test.ts
index e49a353dab..4672b24c37 100644
--- a/packages/cli/src/browser/gpuPolicy.test.ts
+++ b/packages/cli/src/browser/gpuPolicy.test.ts
@@ -1,5 +1,6 @@
-import { describe, expect, it } from "vitest";
-import { resolveLocalBrowserGpuMode } from "./gpuPolicy.js";
+import { buildChromeArgs } from "@hyperframes/engine";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveLocalBrowserGpuMode, resolveLocalWebGpu } from "./gpuPolicy.js";
// compositionRequiresWebGpu and assertWebGpuAdapterAvailable are implemented
// in @hyperframes/engine (browserManager.ts) and only re-exported here — see
@@ -13,3 +14,30 @@ describe("local browser GPU policy", () => {
expect(resolveLocalBrowserGpuMode(false, "hardware")).toBe("software");
});
});
+
+describe("resolveLocalWebGpu", () => {
+ afterEach(() => vi.unstubAllEnvs());
+ const launchArgs = (gpuConfig: ReturnType<typeof resolveLocalWebGpu>["gpuConfig"]) =>
+ buildChromeArgs(
+ { width: 640, height: 360, captureMode: "screenshot", requiresWebGpu: true },
+ gpuConfig,
+ );
+
+ it("runs a WebGPU composition on SwiftShader in software mode when render's opt-in is set", () => {
+ vi.stubEnv("PRODUCER_ALLOW_SOFTWARE_WEBGPU", "true");
+ const { gpuConfig, softwareWebGpu } = resolveLocalWebGpu("software", true);
+ expect(softwareWebGpu).toBe(true);
+ expect(launchArgs(gpuConfig)).toContain("--use-vulkan=swiftshader");
+ });
+
+ it("stays off without the opt-in, on a GPU, or for a composition that does not need WebGPU", () => {
+ vi.stubEnv("PRODUCER_ALLOW_SOFTWARE_WEBGPU", "");
+ expect(resolveLocalWebGpu("software", true).softwareWebGpu).toBe(false);
+ expect(launchArgs(resolveLocalWebGpu("software", true).gpuConfig)).not.toContain(
+ "--use-vulkan=swiftshader",
+ );
+ vi.stubEnv("PRODUCER_ALLOW_SOFTWARE_WEBGPU", "true");
+ expect(resolveLocalWebGpu("hardware", true).softwareWebGpu).toBe(false);
+ expect(resolveLocalWebGpu("software", false).softwareWebGpu).toBe(false);
+ });
+});
diff --git a/packages/cli/src/browser/gpuPolicy.ts b/packages/cli/src/browser/gpuPolicy.ts
index d9dff36d4f..aaa4774611 100644
--- a/packages/cli/src/browser/gpuPolicy.ts
+++ b/packages/cli/src/browser/gpuPolicy.ts
@@ -1,3 +1,5 @@
+import { resolveConfig, usesSoftwareWebGpu } from "@hyperframes/engine";
+
export type BrowserGpuMode = "auto" | "hardware" | "software";
export type ResolvedBrowserGpuMode = Exclude<BrowserGpuMode, "auto">;
@@ -24,3 +26,12 @@ export async function resolveCaptureBrowserGpuMode(
// buildChromeArgs caller goes through, CLI included. Re-exported here so
// existing CLI imports don't need to change their module path.
export { compositionRequiresWebGpu, assertWebGpuAdapterAvailable } from "@hyperframes/engine";
+
+/** The launch config and adapter check for a local capture, honouring PRODUCER_ALLOW_SOFTWARE_WEBGPU as render does. */
+export function resolveLocalWebGpu(
+ browserGpuMode: ResolvedBrowserGpuMode,
+ requiresWebGpu: boolean,
+) {
+ const gpuConfig = { browserGpuMode, allowSoftwareWebGpu: resolveConfig().allowSoftwareWebGpu };
+ return { gpuConfig, softwareWebGpu: usesSoftwareWebGpu(requiresWebGpu, gpuConfig) };
+}
diff --git a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts
index 41b611215c..7e954035b3 100644
--- a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts
@@ -9,6 +9,8 @@ const mocks = vi.hoisted(() => ({
resolveBrowserGpuMode: vi.fn(async () => "software" as const),
compositionRequiresWebGpu: vi.fn(() => false),
assertWebGpuAdapterAvailable: vi.fn(async () => undefined),
+ resolveConfig: vi.fn(),
+ usesSoftwareWebGpu: vi.fn(),
}));
vi.mock("../browser/manager.js", () => ({
@@ -26,6 +28,8 @@ vi.mock("@hyperframes/engine", () => ({
resolveBrowserGpuMode: mocks.resolveBrowserGpuMode,
compositionRequiresWebGpu: mocks.compositionRequiresWebGpu,
assertWebGpuAdapterAvailable: mocks.assertWebGpuAdapterAvailable,
+ resolveConfig: mocks.resolveConfig,
+ usesSoftwareWebGpu: mocks.usesSoftwareWebGpu,
}));
import { openSettledCompositionPage } from "./captureCompositionFrame.js";
@@ -71,6 +75,8 @@ describe("openSettledCompositionPage Windows bundled-browser recovery", () => {
mocks.findSystemBrowser.mockReturnValue({ executablePath: SYSTEM, source: "system" });
mocks.buildChromeArgs.mockReturnValue([]);
mocks.resolveBrowserGpuMode.mockResolvedValue("software");
+ mocks.resolveConfig.mockReturnValue({ allowSoftwareWebGpu: false });
+ mocks.usesSoftwareWebGpu.mockReturnValue(false);
});
afterEach(() => {
@@ -78,6 +84,24 @@ describe("openSettledCompositionPage Windows bundled-browser recovery", () => {
if (originalPlatform) Object.defineProperty(process, "platform", originalPlatform);
});
+ it("launches software WebGPU and accepts its adapter when render's opt-in is set", async () => {
+ const opened = fakeBrowser();
+ mocks.launch.mockResolvedValueOnce(opened.browser);
+ mocks.compositionRequiresWebGpu.mockReturnValue(true);
+ mocks.resolveConfig.mockReturnValue({ allowSoftwareWebGpu: true });
+ mocks.usesSoftwareWebGpu.mockReturnValue(true);
+
+ await openSettledCompositionPage(HTML, "http://127.0.0.1:3000", OPTIONS);
+
+ const gpuConfig = { browserGpuMode: "software", allowSoftwareWebGpu: true };
+ expect(mocks.buildChromeArgs).toHaveBeenCalledWith(
+ expect.objectContaining({ requiresWebGpu: true }),
+ gpuConfig,
+ );
+ expect(mocks.usesSoftwareWebGpu).toHaveBeenCalledWith(true, gpuConfig);
+ expect(mocks.assertWebGpuAdapterAvailable).toHaveBeenCalledWith(opened.page, true, true);
+ });
+
it("retries the known managed-shell crash once with system Chrome", async () => {
const fallback = fakeBrowser();
mocks.launch.mockRejectedValueOnce(launchCrash()).mockResolvedValueOnce(fallback.browser);
diff --git a/packages/cli/src/capture/captureCompositionFrame.test.ts b/packages/cli/src/capture/captureCompositionFrame.test.ts
index 76a0e34a99..bc1b9489f8 100644
--- a/packages/cli/src/capture/captureCompositionFrame.test.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.test.ts
@@ -272,9 +272,9 @@ describe("screenshot Chrome arguments", () => {
const layoutSource = readFileSync(new URL("../commands/layout.ts", import.meta.url), "utf8");
expect(captureSource).toContain("resolveManagedGpuMode(");
- expect(captureSource).toContain("{ browserGpuMode: resolvedGpuMode }");
+ expect(captureSource).toContain("resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu)");
expect(layoutSource).toContain("resolveManagedGpuMode(");
- expect(layoutSource).toContain("{ browserGpuMode: resolvedGpuMode }");
+ expect(layoutSource).toContain("resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu)");
});
});
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index 367081cd72..a44a6349c1 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -6,6 +6,7 @@ import {
assertWebGpuAdapterAvailable,
compositionRequiresWebGpu,
resolveLocalBrowserGpuMode,
+ resolveLocalWebGpu,
type BrowserGpuMode,
} from "../browser/gpuPolicy.js";
import { windowsChromeCrashRemediation } from "../browser/windowsCrash.js";
@@ -185,14 +186,17 @@ export async function openSettledCompositionPage(
const { buildChromeArgs } = await import("@hyperframes/engine");
const requestedGpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
const requiresWebGpu = compositionRequiresWebGpu(html);
+ let softwareWebGpu = false;
const launch = async (executablePath: string): Promise<Browser> => {
const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath);
+ const webGpu = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);
+ softwareWebGpu = webGpu.softwareWebGpu;
return launchManagedBrowser(puppeteer.default, {
headless: true,
executablePath,
args: buildChromeArgs(
{ ...viewport, captureMode: "screenshot", requiresWebGpu },
- { browserGpuMode: resolvedGpuMode },
+ webGpu.gpuConfig,
),
});
};
@@ -235,7 +239,7 @@ export async function openSettledCompositionPage(
waitUntil: "domcontentloaded",
timeout: resolveDiagnosticNavigationTimeoutMs(process.env, options.navigationTimeoutMs),
});
- await assertWebGpuAdapterAvailable(page, requiresWebGpu);
+ await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
return { browser: chromeBrowser, page, renderReadyTimedOut };
} catch (err) {
diff --git a/packages/cli/src/commands/layout.ts b/packages/cli/src/commands/layout.ts
index a6c0288996..d8c14e4b3b 100644
--- a/packages/cli/src/commands/layout.ts
+++ b/packages/cli/src/commands/layout.ts
@@ -205,8 +205,12 @@ async function runLayoutAudit(
const { ensureBrowser } = await import("../browser/manager.js");
const puppeteer = await import("puppeteer-core");
const { buildChromeArgs } = await import("@hyperframes/engine");
- const { assertWebGpuAdapterAvailable, compositionRequiresWebGpu, resolveLocalBrowserGpuMode } =
- await import("../browser/gpuPolicy.js");
+ const {
+ assertWebGpuAdapterAvailable,
+ compositionRequiresWebGpu,
+ resolveLocalBrowserGpuMode,
+ resolveLocalWebGpu,
+ } = await import("../browser/gpuPolicy.js");
const html = await bundleProjectHtml(projectDir);
const server = await serveStaticProjectHtml(
projectDir,
@@ -220,12 +224,13 @@ async function runLayoutAudit(
const requestedGpuMode = resolveLocalBrowserGpuMode();
const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, browser.executablePath);
const requiresWebGpu = compositionRequiresWebGpu(html);
+ const { gpuConfig, softwareWebGpu } = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);
chromeBrowser = await launchManagedBrowser(puppeteer.default, {
headless: true,
executablePath: browser.executablePath,
args: buildChromeArgs(
{ width: 1920, height: 1080, captureMode: "screenshot", requiresWebGpu },
- { browserGpuMode: resolvedGpuMode },
+ gpuConfig,
),
});
@@ -236,7 +241,7 @@ async function runLayoutAudit(
waitUntil: "domcontentloaded",
timeout: resolveDiagnosticNavigationTimeoutMs(),
});
- await assertWebGpuAdapterAvailable(page, requiresWebGpu);
+ await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
await alignViewportToComposition(page, server.url);
await waitForRuntimeReady(page, opts.timeout);
await waitForCompositionFonts(page, 750);
diff --git a/packages/cli/src/commands/motionShot.test.ts b/packages/cli/src/commands/motionShot.test.ts
index 2c3c35e6ba..45207ce150 100644
--- a/packages/cli/src/commands/motionShot.test.ts
+++ b/packages/cli/src/commands/motionShot.test.ts
@@ -84,8 +84,8 @@ describe("motion-shot adapter seeking", () => {
expect(source).toContain("resolveManagedGpuMode");
expect(source).toContain("compositionRequiresWebGpu(html)");
- expect(source).toContain("assertWebGpuAdapterAvailable(page, requiresWebGpu)");
- expect(source).toContain("{ browserGpuMode: resolvedGpuMode }");
+ expect(source).toContain("resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu)");
+ expect(source).toContain("assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu)");
expect(source).not.toContain('"--disable-gpu"');
});
diff --git a/packages/cli/src/commands/motionShot.ts b/packages/cli/src/commands/motionShot.ts
index a63f814866..fae2696daf 100644
--- a/packages/cli/src/commands/motionShot.ts
+++ b/packages/cli/src/commands/motionShot.ts
@@ -20,6 +20,7 @@ import {
assertWebGpuAdapterAvailable,
compositionRequiresWebGpu,
resolveLocalBrowserGpuMode,
+ resolveLocalWebGpu,
} from "../browser/gpuPolicy.js";
import {
buildOnionSvg,
@@ -403,19 +404,17 @@ async function openCompositionPage(
const requestedGpuMode = resolveLocalBrowserGpuMode();
const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath);
const requiresWebGpu = compositionRequiresWebGpu(html);
+ const { gpuConfig, softwareWebGpu } = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);
const browser = await launchManagedBrowser(puppeteer.default, {
headless: true,
executablePath,
- args: buildChromeArgs(
- { ...size, captureMode: "screenshot", requiresWebGpu },
- { browserGpuMode: resolvedGpuMode },
- ),
+ args: buildChromeArgs({ ...size, captureMode: "screenshot", requiresWebGpu }, gpuConfig),
});
const page = await browser.newPage();
const navigationTimeout = resolveDiagnosticNavigationTimeoutMs();
await page.setViewport(size);
await page.goto(url, { waitUntil: "domcontentloaded", timeout: navigationTimeout });
- await assertWebGpuAdapterAvailable(page, requiresWebGpu);
+ await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
await waitForRuntimeReady(page, 10000);
await page
.evaluate(async () => {
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
index 7c2497cb0d..35e63f1804 100644
--- a/packages/cli/src/commands/validate.ts
+++ b/packages/cli/src/commands/validate.ts
@@ -439,17 +439,15 @@ async function validateInBrowser(
const puppeteer = await import("puppeteer-core");
const { buildChromeArgs, analyzeClipMediaFit } = await import("@hyperframes/engine");
const requestedGpuMode = resolveCliChromeGpuMode();
- const { assertWebGpuAdapterAvailable, compositionRequiresWebGpu } =
+ const { assertWebGpuAdapterAvailable, compositionRequiresWebGpu, resolveLocalWebGpu } =
await import("../browser/gpuPolicy.js");
const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, browser.executablePath);
const requiresWebGpu = compositionRequiresWebGpu(html);
+ const { gpuConfig, softwareWebGpu } = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);
const chromeBrowser = await launchManagedBrowser(puppeteer.default, {
headless: true,
executablePath: browser.executablePath,
- args: buildChromeArgs(
- { ...viewport, captureMode: "screenshot", requiresWebGpu },
- { browserGpuMode: resolvedGpuMode },
- ),
+ args: buildChromeArgs({ ...viewport, captureMode: "screenshot", requiresWebGpu }, gpuConfig),
});
const page = await chromeBrowser.newPage();
@@ -508,7 +506,7 @@ async function validateInBrowser(
if (hinted) throw hinted;
throw err;
}
- await assertWebGpuAdapterAvailable(page, requiresWebGpu);
+ await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
await waitForRuntimeReady(page, opts.timeout ?? 3000);
await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));
diff --git a/packages/cli/src/server/studioServer.test.ts b/packages/cli/src/server/studioServer.test.ts
index 538b3203f4..339bf856c2 100644
--- a/packages/cli/src/server/studioServer.test.ts
+++ b/packages/cli/src/server/studioServer.test.ts
@@ -62,6 +62,10 @@ vi.mock("../browser/gpuPolicy.js", () => ({
resolveLocalBrowserGpuMode: () => "software",
compositionRequiresWebGpu: () => false,
assertWebGpuAdapterAvailable: async () => {},
+ resolveLocalWebGpu: (browserGpuMode: string) => ({
+ gpuConfig: { browserGpuMode, allowSoftwareWebGpu: false },
+ softwareWebGpu: false,
+ }),
}));
vi.mock("../browser/preflight.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../browser/preflight.js")>()),
@@ -135,8 +139,8 @@ describe("Studio thumbnail GPU capture plumbing", () => {
it("uses the shared auto probe, resolved launch mode, requirement guard, and completion-aware seek", () => {
const source = readFileSync(new URL("./studioServer.ts", import.meta.url), "utf8");
expect(source).toContain("resolveCaptureBrowserGpuMode");
- expect(source).toContain("{ browserGpuMode: resolvedGpuMode }");
- expect(source).toContain("assertWebGpuAdapterAvailable(page, requiresWebGpu)");
+ expect(source).toContain("resolveLocalWebGpu(resolvedGpuMode, true)");
+ expect(source).toContain("requiresWebGpu && session.softwareWebGpu");
expect(source).toContain("await seekCompositionTimeline(page, opts.seekTime");
});
});
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index 47e4567476..c03d2990b3 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -78,6 +78,7 @@ import {
compositionRequiresWebGpu,
resolveCaptureBrowserGpuMode,
resolveLocalBrowserGpuMode,
+ resolveLocalWebGpu,
type BrowserGpuMode,
type ResolvedBrowserGpuMode,
} from "../browser/gpuPolicy.js";
@@ -241,12 +242,14 @@ let _thumbnailBrowserInitializing: Promise<ThumbnailBrowserSession | null> | nul
let _thumbnailBrowserModes: {
requested: BrowserGpuMode;
resolved: ResolvedBrowserGpuMode;
+ softwareWebGpu: boolean;
} | null = null;
interface ThumbnailBrowserSession {
browser: import("puppeteer-core").Browser;
requestedGpuMode: BrowserGpuMode;
resolvedGpuMode: ResolvedBrowserGpuMode;
+ softwareWebGpu: boolean;
}
async function getThumbnailBrowser(
@@ -262,6 +265,7 @@ async function getThumbnailBrowser(
browser: _thumbnailBrowserLease.browser,
requestedGpuMode: _thumbnailBrowserModes.requested,
resolvedGpuMode: _thumbnailBrowserModes.resolved,
+ softwareWebGpu: _thumbnailBrowserModes.softwareWebGpu,
};
}
if (_thumbnailBrowserInitializing) {
@@ -288,22 +292,32 @@ async function getThumbnailBrowser(
}
const resolvedGpuMode = await resolveCaptureBrowserGpuMode(requestedGpuMode, executablePath);
+ const { gpuConfig, softwareWebGpu } = resolveLocalWebGpu(resolvedGpuMode, true);
const acquired = await acquireBrowser(
buildChromeArgs(
- { width: 1920, height: 1080, captureMode: "screenshot" },
- { browserGpuMode: resolvedGpuMode },
+ {
+ width: 1920,
+ height: 1080,
+ captureMode: "screenshot",
+ requiresWebGpu: softwareWebGpu,
+ },
+ gpuConfig,
),
{ forceScreenshot: true },
);
_thumbnailBrowserLease = acquired;
- _thumbnailBrowserModes = { requested: requestedGpuMode, resolved: resolvedGpuMode };
+ _thumbnailBrowserModes = {
+ requested: requestedGpuMode,
+ resolved: resolvedGpuMode,
+ softwareWebGpu,
+ };
acquired.browser.on("disconnected", () => {
if (_thumbnailBrowserLease !== acquired) return;
_thumbnailBrowserLease = null;
_thumbnailBrowserModes = null;
_thumbnailBrowserInitializing = null;
});
- return { browser: acquired.browser, requestedGpuMode, resolvedGpuMode };
+ return { browser: acquired.browser, requestedGpuMode, resolvedGpuMode, softwareWebGpu };
} catch (err) {
console.warn(
"[Studio] Failed to launch thumbnail browser:",
@@ -714,7 +728,11 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
async (page) => {
await page.setViewport(viewport);
await page.goto(opts.previewUrl, { waitUntil: "domcontentloaded", timeout: 10000 });
- await assertWebGpuAdapterAvailable(page, requiresWebGpu);
+ await assertWebGpuAdapterAvailable(
+ page,
+ requiresWebGpu,
+ requiresWebGpu && session.softwareWebGpu,
+ );
await page
.waitForFunction(
() => {
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 4fd3df11fa..7215f15732 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -88,6 +88,7 @@ export {
buildChromeArgs,
compositionRequiresWebGpu,
assertWebGpuAdapterAvailable,
+ usesSoftwareWebGpu,
WebGpuUnavailableError,
ENABLE_BROWSER_POOL,
BrowserLeasePool,
diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts
index a4c522529a..c31e429794 100644
--- a/packages/engine/src/services/browserManager.test.ts
+++ b/packages/engine/src/services/browserManager.test.ts
@@ -252,6 +252,16 @@ describe("compositionRequiresWebGpu", () => {
expect(compositionRequiresWebGpu('<div data-composition-id="dom"></div>')).toBe(false);
});
+ it("finds the root after an inlined script whose code holds '<' and the marker name", () => {
+ const runtime = `<script>if(n<32)q="[data-composition-id]";if(a>b)go()</script>`;
+ expect(
+ compositionRequiresWebGpu(`${runtime}<div data-composition-id="main" data-requires-webgpu>`),
+ ).toBe(true);
+ expect(
+ compositionRequiresWebGpu(`<div title="data-composition-id" data-requires-webgpu>`),
+ ).toBe(false);
+ });
+
it("reads only the composition root tag and stays linear on repeated '<'", () => {
expect(
compositionRequiresWebGpu('<p data-requires-webgpu></p><div data-composition-id="a"></div>'),
@@ -436,6 +446,32 @@ describe("resolveBrowserGpuMode", () => {
expect(warning).not.toContain("--gpus all");
});
+ it("falls back to 'software' within the probe budget when the probe page never answers", async () => {
+ vi.useFakeTimers();
+ try {
+ const kill = vi.fn();
+ const launch = vi.fn().mockResolvedValue({
+ newPage: vi.fn().mockResolvedValue({ evaluate: () => new Promise(() => {}) }),
+ close: () => new Promise(() => {}),
+ process: () => ({ kill }),
+ disconnect: vi.fn().mockResolvedValue(undefined),
+ });
+ _setPuppeteerForTests({ launch } as unknown as PuppeteerNode);
+ vi.spyOn(console, "log").mockImplementation(() => {});
+
+ const mode = resolveBrowserGpuMode("auto", { browserTimeout: 120_000 });
+ await vi.advanceTimersByTimeAsync(15_000 + 250);
+
+ await expect(mode).resolves.toBe("software");
+ expect(launch).toHaveBeenCalledWith(
+ expect.objectContaining({ timeout: 120_000, waitForInitialPage: false }),
+ );
+ expect(kill).toHaveBeenCalledWith("SIGKILL");
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
it("falls back to 'software' when the probe browser cannot launch", async () => {
// No chromePath, env unset, and (in the test env) no system Chrome to find
// → puppeteer.launch will throw → caller catches → software fallback.
diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts
index f4a4efe12e..aa150db3cc 100644
--- a/packages/engine/src/services/browserManager.ts
+++ b/packages/engine/src/services/browserManager.ts
@@ -6,6 +6,7 @@
* launch args, pooled browser acquisition/release.
*/
+import { scanHtmlOpeningTags } from "@hyperframes/parsers/html-attribute-spans";
import type { Browser, Page, PuppeteerNode } from "puppeteer-core";
import { execSync } from "child_process";
import { existsSync, readdirSync, statSync } from "fs";
@@ -72,6 +73,8 @@ async function getPuppeteer(): Promise<PuppeteerNode> {
return _puppeteer;
}
+const GPU_PROBE_TIMEOUT_MS = 15_000;
+
async function probeHardwareWebGlInfo(
ppt: PuppeteerNode,
options: {
@@ -89,39 +92,48 @@ async function probeHardwareWebGlInfo(
defaultViewport: { width: 64, height: 64 },
executablePath: options.executablePath,
timeout: options.browserTimeout,
+ waitForInitialPage: false,
});
- const page = await probeBrowser.newPage();
- return await page.evaluate(() => {
- const unavailable = { hasWebGL: false, vendor: "", renderer: "" };
- const c = document.createElement("canvas");
- let gl = c.getContext("webgl") as WebGLRenderingContext | null;
- if (gl === null) {
- gl = c.getContext("experimental-webgl") as WebGLRenderingContext | null;
- }
- if (gl === null) return unavailable;
- const ext = gl.getExtension("WEBGL_debug_renderer_info") as {
- UNMASKED_VENDOR_WEBGL: number;
- UNMASKED_RENDERER_WEBGL: number;
- } | null;
- let vendorParam: number = gl.VENDOR;
- let rendererParam: number = gl.RENDERER;
- if (ext !== null) {
- vendorParam = ext.UNMASKED_VENDOR_WEBGL;
- rendererParam = ext.UNMASKED_RENDERER_WEBGL;
- }
- const vendor = gl.getParameter(vendorParam);
- const renderer = gl.getParameter(rendererParam);
- return {
- hasWebGL: true,
- vendor: vendor == null ? "" : String(vendor),
- renderer: renderer == null ? "" : String(renderer),
- };
- });
+ return await rejectAfter(
+ readWebGlInfo(probeBrowser),
+ GPU_PROBE_TIMEOUT_MS,
+ `GPU probe page did not answer within ${GPU_PROBE_TIMEOUT_MS}ms`,
+ );
} finally {
- await probeBrowser?.close().catch(() => {});
+ if (probeBrowser) await closeBrowserAfterFailedProbe(probeBrowser);
}
}
+async function readWebGlInfo(browser: Browser): Promise<WebGlProbeInfo> {
+ const page = await browser.newPage();
+ return await page.evaluate(() => {
+ const unavailable = { hasWebGL: false, vendor: "", renderer: "" };
+ const c = document.createElement("canvas");
+ let gl = c.getContext("webgl") as WebGLRenderingContext | null;
+ if (gl === null) {
+ gl = c.getContext("experimental-webgl") as WebGLRenderingContext | null;
+ }
+ if (gl === null) return unavailable;
+ const ext = gl.getExtension("WEBGL_debug_renderer_info") as {
+ UNMASKED_VENDOR_WEBGL: number;
+ UNMASKED_RENDERER_WEBGL: number;
+ } | null;
+ let vendorParam: number = gl.VENDOR;
+ let rendererParam: number = gl.RENDERER;
+ if (ext !== null) {
+ vendorParam = ext.UNMASKED_VENDOR_WEBGL;
+ rendererParam = ext.UNMASKED_RENDERER_WEBGL;
+ }
+ const vendor = gl.getParameter(vendorParam);
+ const renderer = gl.getParameter(rendererParam);
+ return {
+ hasWebGL: true,
+ vendor: vendor == null ? "" : String(vendor),
+ renderer: renderer == null ? "" : String(renderer),
+ };
+ });
+}
+
export type AcquiredBrowser = BrowserLease;
function compareBrowserVersionsDescending(left: string, right: string): number {
@@ -284,15 +296,20 @@ async function awaitBeforeDeadline<T>(
if (remainingMs <= 0) {
throw new Error(`beginFrame probe timeout before ${label}`);
}
+ return rejectAfter(operation, remainingMs, `beginFrame probe timeout during ${label}`);
+}
+
+async function rejectAfter<T>(
+ operation: Promise<T>,
+ timeoutMs: number,
+ message: string,
+): Promise<T> {
let timeout: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
operation,
new Promise<never>((_, reject) => {
- timeout = setTimeout(
- () => reject(new Error(`beginFrame probe timeout during ${label}`)),
- remainingMs,
- );
+ timeout = setTimeout(() => reject(new Error(message)), timeoutMs);
}),
]);
} finally {
@@ -1013,9 +1030,9 @@ export function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuCon
/** Does the composition's root element declare `data-requires-webgpu`? */
export function compositionRequiresWebGpu(html: string): boolean {
- // Quoted values are consumed whole, so '<' or '>' inside one stays in the tag; no nested quantifier overlaps.
- for (const [tag] of html.matchAll(/<(?:[^<>"']|"[^"]*"|'[^']*')*>/g)) {
- if (/\bdata-composition-id\b/i.test(tag)) return /\bdata-requires-webgpu(?:\s|=|>)/i.test(tag);
+ for (const tag of scanHtmlOpeningTags(html)) {
+ const names = tag.attributes.map((attribute) => attribute.name);
+ if (names.includes("data-composition-id")) return names.includes("data-requires-webgpu");
}
return false;
}
diff --git a/packages/gcp-cloud-run/Dockerfile b/packages/gcp-cloud-run/Dockerfile
index 84417f2021..86992c2a7f 100644
--- a/packages/gcp-cloud-run/Dockerfile
+++ b/packages/gcp-cloud-run/Dockerfile
@@ -109,6 +109,7 @@ RUN timeout 300 bun install --frozen-lockfile \
# argument list with the production engine helper so a launcher-flag regression
# invalidates this layer and fails the contract instead of testing a duplicate
# hard-coded profile.
+COPY packages/parsers/ packages/parsers/
COPY packages/engine/ packages/engine/
COPY packages/aws-lambda/scripts/probe-beginframe.ts packages/aws-lambda/scripts/probe-beginframe.ts
RUN bun -e 'import { buildChromeArgs } from "./packages/engine/src/services/browserManager.ts"; await Bun.write("/tmp/hf-gcp-chrome-args.json", JSON.stringify(buildChromeArgs({ width: 800, height: 600, captureMode: "beginframe", platform: "linux" }, { browserGpuMode: "software" })))' \
diff --git a/packages/parsers/package-subpaths.json b/packages/parsers/package-subpaths.json
index 122a255878..18f6449836 100644
--- a/packages/parsers/package-subpaths.json
+++ b/packages/parsers/package-subpaths.json
@@ -122,6 +122,12 @@
"types": "./dist/assetResolution.d.ts",
"environments": ["bun", "node"]
},
+ "./html-attribute-spans": {
+ "source": "./src/htmlAttributeSpans.ts",
+ "runtime": "./dist/htmlAttributeSpans.js",
+ "types": "./dist/htmlAttributeSpans.d.ts",
+ "environments": ["browser", "bun", "node"]
+ },
"./composition-duration": {
"source": "./src/compositionDuration.ts",
"runtime": "./dist/compositionDuration.js",
diff --git a/packages/parsers/package.json b/packages/parsers/package.json
index 0e0e8e09ea..13fcc51acd 100644
--- a/packages/parsers/package.json
+++ b/packages/parsers/package.json
@@ -130,6 +130,12 @@
"import": "./src/assetResolution.ts",
"types": "./src/assetResolution.ts"
},
+ "./html-attribute-spans": {
+ "bun": "./src/htmlAttributeSpans.ts",
+ "node": "./dist/htmlAttributeSpans.js",
+ "import": "./src/htmlAttributeSpans.ts",
+ "types": "./src/htmlAttributeSpans.ts"
+ },
"./composition-duration": {
"bun": "./src/compositionDuration.ts",
"node": "./dist/compositionDuration.js",
@@ -217,6 +223,10 @@
"import": "./dist/assetResolution.js",
"types": "./dist/assetResolution.d.ts"
},
+ "./html-attribute-spans": {
+ "import": "./dist/htmlAttributeSpans.js",
+ "types": "./dist/htmlAttributeSpans.d.ts"
+ },
"./composition-duration": {
"import": "./dist/compositionDuration.js",
"types": "./dist/compositionDuration.d.ts"
diff --git a/packages/parsers/tsup.config.ts b/packages/parsers/tsup.config.ts
index dff60190b5..c286cb09a8 100644
--- a/packages/parsers/tsup.config.ts
+++ b/packages/parsers/tsup.config.ts
@@ -22,6 +22,7 @@ export default defineConfig({
subCompositionValidity: "src/subCompositionValidity.ts",
ffBinaries: "src/ffBinaries.ts",
assetResolution: "src/assetResolution.ts",
+ htmlAttributeSpans: "src/htmlAttributeSpans.ts",
},
format: ["esm"],
outDir: "dist",