Skip to content

Commit 9981d9a

Browse files
fix(capture): never silently render a webgpu composition blank (#4091)
* fix(capture): never silently render a webgpu composition blank A composition declaring data-requires-webgpu only got the Chrome WebGPU flag when hardware GPU auto-detection succeeded. On a software-GPU host it launched without the flag and rendered blank with no error. compositionRequiresWebGpu (static declaration check) and assertWebGpuAdapterAvailable (live per-page adapter probe) now live once in packages/engine's browserManager, the shared choke point every launch site already goes through. All six launch sites (frame capture, the four CLI diagnostic commands, the studio thumbnail server, and the render pipeline's capture-options builder) route through those two functions; the old CLI-only static-heuristic guard is deleted, not kept alongside the new one. A software host that cannot obtain any WebGPU adapter now fails loudly naming the requirement instead of producing a blank frame. * fix(capture): thread requiresWebGpu through the distributed chunk-render path The distributed renderChunk() path built its CaptureOptions without requiresWebGpu, so it fell through to frameCapture's own fetch-based detection, whose failure path silently treats "requires webgpu" as "doesn't" if that fetch ever fails. Every other launch site (frame capture, all four CLI diagnostic commands, the studio thumbnail server, and the in-process render pipeline) already reads the value from HTML already in memory or on disk instead of relying on that fallback. Reads the compiled composition's index.html the same way probeStage already does and derives requiresWebGpu from it before building CaptureOptions. Adds a regression test that pins the exact path renderChunk() reads at render time, since the composition doesn't actually exercise WebGPU so an end-to-end render can't distinguish the two cases on this host. * test(producer): observe the real CaptureOptions renderChunk() builds The previous regression test called plan() and compositionRequiresWebGpu() directly, bypassing renderChunk() entirely, so it could not detect a regression to the wiring it was meant to protect (confirmed: it stayed green with the fix reverted). Exports the existing createCaptureSession dependency seam so a test can substitute a spy that delegates to the real implementation while capturing the CaptureOptions object renderChunk() actually constructs. Verified non-vacuous by reverting the fix and confirming the test fails. * fix(gcp-cloud-run): resolve puppeteer-core from a real file in the webgpu probe The image build's WebGPU adapter probe imported puppeteer-core from an inline `bun -e` eval string. The eval's synthetic /app/[eval] location can't resolve the workspace-hoisted dependency, so every build of this stage failed closed with "Cannot find package 'puppeteer-core'" before the probe itself ever ran. Moves the probe into a real script file next to probe-beginframe.ts, which already imports puppeteer-core dynamically the same way and resolves fine from its real workspace location. Verified locally against a cached chrome-headless-shell binary. * fix(engine): bound the webgpu adapter probe so a stuck driver can't hang the caller requestAdapter() has no native timeout. A broken software GPU driver that never settles it would hang assertWebGpuAdapterAvailable indefinitely, including inside the GCP image build's probe RUN step, producing an opaque build timeout instead of a clean probe failure. Races the in-page request against a bounded timeout so a stuck adapter reads as unavailable and fails the same way a genuinely absent one does. * test(cli): mock the engine's webgpu exports in the browser-fallback test * test(producer): run the typegpu adapter fixture only on hosts with a hardware WebGPU adapter The fixture declares data-requires-webgpu, so a software-only host now refuses it instead of silently rendering the shader blank. The old golden had no shader in it. Tag it webgpu, skip that tag in the CI image and the test scripts, and re-record the golden from a Metal render with the shader visible. * fix(engine): bound the composition fetch that decides the webgpu flag createCaptureSession fetched the served page with no timeout before launching the browser, so a hung server stalled a render forever and hung a fake-timer test. Give it a five second limit, and let that test say it has no WebGPU requirement the way the producer does. * fix(capture): refuse a software fallback WebGPU adapter instead of rendering on it swiftshader reports a WebGPU adapter but cannot render canvas WebGPU, so a data-requires-webgpu composition on a software-only host crashed on its first frame. Refuse fallback adapters with the same clear WebGPU-unavailable error. The GCP image probe now serves its page over http (file:// hides navigator.gpu) and reports a software-only host instead of failing the image build. * fix(engine): parse the composition root tag without a backtracking regex * fix(engine): keep quoted attribute values whole when reading the composition root tag
1 parent cb9ca4f commit 9981d9a

26 files changed

Lines changed: 409 additions & 86 deletions

‎Dockerfile.test‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,9 @@ RUN cd packages/producer && bunx tsx scripts/generate-font-data.ts
124124
WORKDIR /app/packages/producer
125125

126126
# Skip fixtures tagged `transparency` (Chrome alpha-channel PSNR quirks not
127-
# reproducible on the CI image) and `field-signal-reproducer` (known-broken
127+
# reproducible on the CI image), `webgpu` (needs a hardware adapter; CI has
128+
# only swiftshader, which cannot render canvas WebGPU) and
129+
# `field-signal-reproducer` (known-broken
128130
# fixture per PR #2512 — codifies a real bug awaiting a fix). Mirrors the
129131
# `--exclude-tags` in the local `test:regression*` scripts in
130132
# packages/producer/package.json so `bun run docker:test*` and the aws-lambda
@@ -133,4 +135,4 @@ WORKDIR /app/packages/producer
133135
# `hdr-regression style-5-prod ...` in .github/workflows/regression.yml) still
134136
# resolve normally; the harness applies excludeTags whether testNames is empty
135137
# or non-empty (see discoverTestSuites in src/regression-harness.ts).
136-
ENTRYPOINT ["bunx", "tsx", "src/regression-harness.ts", "--", "--sequential", "--exclude-tags", "transparency,field-signal-reproducer"]
138+
ENTRYPOINT ["bunx", "tsx", "src/regression-harness.ts", "--", "--sequential", "--exclude-tags", "transparency,field-signal-reproducer,webgpu"]
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
#!/usr/bin/env tsx
2+
/** Reports whether the pinned Linux Chromium gets a hardware WebGPU adapter; software-only is not a failure. */
3+
// Dynamic `puppeteer-core` import from a real file, same as probe-beginframe.ts —
4+
// an inline `bun -e` eval's synthetic `/app/[eval]` path can't see the hoisted dep.
5+
// Usage: bun probe-webgpu-adapter.ts --executable-path /opt/chrome/chrome-headless-shell
6+
7+
import { createServer } from "node:http";
8+
import type { AddressInfo } from "node:net";
9+
import { resolve } from "node:path";
10+
import { fileURLToPath } from "node:url";
11+
import {
12+
buildChromeArgs,
13+
assertWebGpuAdapterAvailable,
14+
WebGpuUnavailableError,
15+
} from "../../engine/src/services/browserManager.ts";
16+
17+
const PROBE_HTML = '<div data-composition-id="probe" data-requires-webgpu></div>';
18+
19+
function parseExecutablePath(args: string[]): string {
20+
for (let i = 0; i < args.length; i += 1) {
21+
if (args[i] === "--executable-path") return resolve(args[i + 1]);
22+
if (args[i].startsWith("--executable-path=")) {
23+
return resolve(args[i].slice("--executable-path=".length));
24+
}
25+
}
26+
throw new Error("--executable-path is required");
27+
}
28+
29+
async function main(): Promise<void> {
30+
const executablePath = parseExecutablePath(process.argv.slice(2));
31+
const puppeteer = await import("puppeteer-core");
32+
33+
// navigator.gpu only exists on a secure-context origin; file:// is not one, http://127.0.0.1 is.
34+
const server = createServer((_req, res) => res.end(PROBE_HTML));
35+
await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
36+
try {
37+
const args = buildChromeArgs(
38+
{
39+
width: 800,
40+
height: 600,
41+
captureMode: "screenshot",
42+
platform: "linux",
43+
requiresWebGpu: true,
44+
},
45+
{ browserGpuMode: "software" },
46+
);
47+
const browser = await puppeteer.launch({ executablePath, headless: true, args });
48+
try {
49+
const page = await browser.newPage();
50+
await page.goto(`http://127.0.0.1:${(server.address() as AddressInfo).port}/`);
51+
await assertWebGpuAdapterAvailable(page, true);
52+
console.log("WebGPU adapter probe: hardware adapter available");
53+
} catch (err) {
54+
if (!(err instanceof WebGpuUnavailableError)) throw err;
55+
console.log(
56+
"WebGPU adapter probe: no usable adapter; data-requires-webgpu compositions will not render on this host",
57+
);
58+
} finally {
59+
await browser.close();
60+
}
61+
} finally {
62+
server.close();
63+
}
64+
}
65+
66+
const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";
67+
if (invokedPath === fileURLToPath(import.meta.url)) {
68+
void main().catch((err) => {
69+
console.error("[probe-webgpu-adapter] FAIL —", err instanceof Error ? err.message : err);
70+
process.exit(1);
71+
});
72+
}
Lines changed: 4 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
import { describe, expect, it } from "vitest";
2-
import {
3-
assertWebGpuRequirement,
4-
compositionRequiresWebGpu,
5-
resolveLocalBrowserGpuMode,
6-
} from "./gpuPolicy.js";
2+
import { resolveLocalBrowserGpuMode } from "./gpuPolicy.js";
73

4+
// compositionRequiresWebGpu and assertWebGpuAdapterAvailable are implemented
5+
// in @hyperframes/engine (browserManager.ts) and only re-exported here — see
6+
// that package's browserManager.test.ts for their coverage.
87
describe("local browser GPU policy", () => {
98
it("defaults to auto and preserves explicit CLI/env overrides", () => {
109
expect(resolveLocalBrowserGpuMode(undefined, undefined)).toBe("auto");
@@ -13,22 +12,4 @@ describe("local browser GPU policy", () => {
1312
expect(resolveLocalBrowserGpuMode(true, "software")).toBe("hardware");
1413
expect(resolveLocalBrowserGpuMode(false, "hardware")).toBe("software");
1514
});
16-
17-
it("detects the explicit WebGPU capability marker on the composition root", () => {
18-
expect(
19-
compositionRequiresWebGpu(
20-
'<div data-requires-webgpu data-composition-id="gpu" data-duration="2"></div>',
21-
),
22-
).toBe(true);
23-
expect(compositionRequiresWebGpu('<div data-composition-id="dom"></div>')).toBe(false);
24-
});
25-
26-
it("rejects an auto software fallback for required WebGPU compositions", () => {
27-
const html = '<div data-composition-id="gpu" data-requires-webgpu></div>';
28-
expect(() => assertWebGpuRequirement(html, "auto", "software")).toThrow(
29-
"PRODUCER_BROWSER_GPU_MODE=hardware",
30-
);
31-
expect(() => assertWebGpuRequirement(html, "hardware", "hardware")).not.toThrow();
32-
expect(() => assertWebGpuRequirement(html, "software", "software")).not.toThrow();
33-
});
3415
});

‎packages/cli/src/browser/gpuPolicy.ts‎

Lines changed: 5 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -19,25 +19,8 @@ export async function resolveCaptureBrowserGpuMode(
1919
return resolveBrowserGpuMode(requestedMode, { chromePath });
2020
}
2121

22-
export function compositionRequiresWebGpu(html: string): boolean {
23-
const compositionRoot = html.match(
24-
/<[^>]*\bdata-composition-id(?:\s*=\s*("[^"]*"|'[^']*'|[^\s>]+))?[^>]*>/i,
25-
);
26-
return compositionRoot ? /\bdata-requires-webgpu(?:\s|=|>)/i.test(compositionRoot[0]) : false;
27-
}
28-
29-
export function assertWebGpuRequirement(
30-
html: string,
31-
requestedMode: BrowserGpuMode,
32-
resolvedMode: ResolvedBrowserGpuMode,
33-
): void {
34-
if (requestedMode !== "auto" || resolvedMode !== "software" || !compositionRequiresWebGpu(html)) {
35-
return;
36-
}
37-
throw new Error(
38-
"This composition declares data-requires-webgpu, but browser GPU auto-detection found no hardware GPU. " +
39-
"Run on a WebGPU-capable host or set PRODUCER_BROWSER_GPU_MODE=hardware " +
40-
"(or pass --browser-gpu on commands that support it) to require hardware explicitly; " +
41-
"use --no-browser-gpu only when intentionally testing the composition's software fallback.",
42-
);
43-
}
22+
// `compositionRequiresWebGpu` and the launch-time WebGPU guard now live in
23+
// @hyperframes/engine (browserManager.ts) — the shared choke point every
24+
// buildChromeArgs caller goes through, CLI included. Re-exported here so
25+
// existing CLI imports don't need to change their module path.
26+
export { compositionRequiresWebGpu, assertWebGpuAdapterAvailable } from "@hyperframes/engine";

‎packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ const mocks = vi.hoisted(() => ({
66
launch: vi.fn(),
77
buildChromeArgs: vi.fn(() => []),
88
resolveBrowserGpuMode: vi.fn(async () => "software" as const),
9+
compositionRequiresWebGpu: vi.fn(() => false),
10+
assertWebGpuAdapterAvailable: vi.fn(async () => undefined),
911
}));
1012

1113
vi.mock("../browser/manager.js", () => ({
@@ -15,9 +17,14 @@ vi.mock("../browser/manager.js", () => ({
1517

1618
vi.mock("puppeteer-core", () => ({ default: { launch: mocks.launch } }));
1719

20+
// captureCompositionFrame.js imports these two from ../browser/gpuPolicy.js,
21+
// which re-exports them from this mocked module — unmocked here, they'd read
22+
// undefined and throw as soon as openSettledCompositionPage calls them.
1823
vi.mock("@hyperframes/engine", () => ({
1924
buildChromeArgs: mocks.buildChromeArgs,
2025
resolveBrowserGpuMode: mocks.resolveBrowserGpuMode,
26+
compositionRequiresWebGpu: mocks.compositionRequiresWebGpu,
27+
assertWebGpuAdapterAvailable: mocks.assertWebGpuAdapterAvailable,
2128
}));
2229

2330
import { openSettledCompositionPage } from "./captureCompositionFrame.js";

‎packages/cli/src/capture/captureCompositionFrame.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@ import { spawn } from "node:child_process";
22
import type { Browser, Page } from "puppeteer-core";
33
import { c } from "../ui/colors.js";
44
import {
5-
assertWebGpuRequirement,
5+
assertWebGpuAdapterAvailable,
6+
compositionRequiresWebGpu,
67
resolveCaptureBrowserGpuMode,
78
resolveLocalBrowserGpuMode,
89
type BrowserGpuMode,
@@ -174,14 +175,14 @@ export async function openSettledCompositionPage(
174175
const puppeteer = await import("puppeteer-core");
175176
const { buildChromeArgs } = await import("@hyperframes/engine");
176177
const requestedGpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
178+
const requiresWebGpu = compositionRequiresWebGpu(html);
177179
const launch = async (executablePath: string): Promise<Browser> => {
178180
const resolvedGpuMode = await resolveCaptureBrowserGpuMode(requestedGpuMode, executablePath);
179-
assertWebGpuRequirement(html, requestedGpuMode, resolvedGpuMode);
180181
return puppeteer.default.launch({
181182
headless: true,
182183
executablePath,
183184
args: buildChromeArgs(
184-
{ ...viewport, captureMode: "screenshot" },
185+
{ ...viewport, captureMode: "screenshot", requiresWebGpu },
185186
{ browserGpuMode: resolvedGpuMode },
186187
),
187188
});
@@ -225,6 +226,7 @@ export async function openSettledCompositionPage(
225226
waitUntil: "domcontentloaded",
226227
timeout: resolveDiagnosticNavigationTimeoutMs(process.env, options.navigationTimeoutMs),
227228
});
229+
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
228230
const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
229231
return { browser: chromeBrowser, page, renderReadyTimedOut };
230232
} catch (err) {

‎packages/cli/src/commands/layout.ts‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -203,8 +203,12 @@ async function runLayoutAudit(
203203
const { ensureBrowser } = await import("../browser/manager.js");
204204
const puppeteer = await import("puppeteer-core");
205205
const { buildChromeArgs } = await import("@hyperframes/engine");
206-
const { assertWebGpuRequirement, resolveCaptureBrowserGpuMode, resolveLocalBrowserGpuMode } =
207-
await import("../browser/gpuPolicy.js");
206+
const {
207+
assertWebGpuAdapterAvailable,
208+
compositionRequiresWebGpu,
209+
resolveCaptureBrowserGpuMode,
210+
resolveLocalBrowserGpuMode,
211+
} = await import("../browser/gpuPolicy.js");
208212
const html = await bundleProjectHtml(projectDir);
209213
const server = await serveStaticProjectHtml(
210214
projectDir,
@@ -220,12 +224,12 @@ async function runLayoutAudit(
220224
requestedGpuMode,
221225
browser.executablePath,
222226
);
223-
assertWebGpuRequirement(html, requestedGpuMode, resolvedGpuMode);
227+
const requiresWebGpu = compositionRequiresWebGpu(html);
224228
chromeBrowser = await puppeteer.default.launch({
225229
headless: true,
226230
executablePath: browser.executablePath,
227231
args: buildChromeArgs(
228-
{ width: 1920, height: 1080, captureMode: "screenshot" },
232+
{ width: 1920, height: 1080, captureMode: "screenshot", requiresWebGpu },
229233
{ browserGpuMode: resolvedGpuMode },
230234
),
231235
});
@@ -237,6 +241,7 @@ async function runLayoutAudit(
237241
waitUntil: "domcontentloaded",
238242
timeout: resolveDiagnosticNavigationTimeoutMs(),
239243
});
244+
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
240245
await alignViewportToComposition(page, server.url);
241246
await page
242247
.waitForFunction(() => !!(window as unknown as { __timelines?: unknown }).__timelines, {

‎packages/cli/src/commands/motionShot.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,8 @@ describe("motion-shot adapter seeking", () => {
8383
const source = readFileSync(motionShotSourcePath, "utf8");
8484

8585
expect(source).toContain("resolveCaptureBrowserGpuMode");
86-
expect(source).toContain("assertWebGpuRequirement(html");
86+
expect(source).toContain("compositionRequiresWebGpu(html)");
87+
expect(source).toContain("assertWebGpuAdapterAvailable(page, requiresWebGpu)");
8788
expect(source).toContain("{ browserGpuMode: resolvedGpuMode }");
8889
expect(source).not.toContain('"--disable-gpu"');
8990
});

‎packages/cli/src/commands/motionShot.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ import { dirname, resolve } from "node:path";
1515
import { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";
1616
import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
1717
import {
18-
assertWebGpuRequirement,
18+
assertWebGpuAdapterAvailable,
19+
compositionRequiresWebGpu,
1920
resolveCaptureBrowserGpuMode,
2021
resolveLocalBrowserGpuMode,
2122
} from "../browser/gpuPolicy.js";
@@ -400,19 +401,20 @@ async function openCompositionPage(
400401
const size = resolveCompositionViewportFromHtml(html);
401402
const requestedGpuMode = resolveLocalBrowserGpuMode();
402403
const resolvedGpuMode = await resolveCaptureBrowserGpuMode(requestedGpuMode, executablePath);
403-
assertWebGpuRequirement(html, requestedGpuMode, resolvedGpuMode);
404+
const requiresWebGpu = compositionRequiresWebGpu(html);
404405
const browser = await puppeteer.default.launch({
405406
headless: true,
406407
executablePath,
407408
args: buildChromeArgs(
408-
{ ...size, captureMode: "screenshot" },
409+
{ ...size, captureMode: "screenshot", requiresWebGpu },
409410
{ browserGpuMode: resolvedGpuMode },
410411
),
411412
});
412413
const page = await browser.newPage();
413414
const navigationTimeout = resolveDiagnosticNavigationTimeoutMs();
414415
await page.setViewport(size);
415416
await page.goto(url, { waitUntil: "domcontentloaded", timeout: navigationTimeout });
417+
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
416418
await page
417419
.waitForFunction(() => !!(window as unknown as { __timelines?: unknown }).__timelines, {
418420
timeout: 10000,

‎packages/cli/src/commands/validate.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -432,18 +432,21 @@ async function validateInBrowser(
432432
const puppeteer = await import("puppeteer-core");
433433
const { buildChromeArgs, analyzeClipMediaFit } = await import("@hyperframes/engine");
434434
const requestedGpuMode = resolveCliChromeGpuMode();
435-
const { assertWebGpuRequirement, resolveCaptureBrowserGpuMode } =
436-
await import("../browser/gpuPolicy.js");
435+
const {
436+
assertWebGpuAdapterAvailable,
437+
compositionRequiresWebGpu,
438+
resolveCaptureBrowserGpuMode,
439+
} = await import("../browser/gpuPolicy.js");
437440
const resolvedGpuMode = await resolveCaptureBrowserGpuMode(
438441
requestedGpuMode,
439442
browser.executablePath,
440443
);
441-
assertWebGpuRequirement(html, requestedGpuMode, resolvedGpuMode);
444+
const requiresWebGpu = compositionRequiresWebGpu(html);
442445
const chromeBrowser = await puppeteer.default.launch({
443446
headless: true,
444447
executablePath: browser.executablePath,
445448
args: buildChromeArgs(
446-
{ ...viewport, captureMode: "screenshot" },
449+
{ ...viewport, captureMode: "screenshot", requiresWebGpu },
447450
{ browserGpuMode: resolvedGpuMode },
448451
),
449452
});
@@ -504,6 +507,7 @@ async function validateInBrowser(
504507
if (hinted) throw hinted;
505508
throw err;
506509
}
510+
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
507511
await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));
508512

509513
for (const w of await auditClipDurations(page, analyzeClipMediaFit, opts.timeout ?? 3000)) {

0 commit comments

Comments
 (0)