feat(engine): assertSwiftShader chrome://gpu validator

[jrusso1020]

What

New utility packages/engine/src/utils/assertSwiftShader.ts that navigates a Puppeteer Page to chrome://gpu, parses the GL_VENDOR / GL_RENDERER rows, and throws SwiftShaderAssertionError (with code: "BROWSER_GPU_NOT_SOFTWARE") if the active WebGL backend is anything other than SwiftShader. Re-exported from packages/engine/src/index.ts.

Why

Part of Phase 2 of the distributed rendering plan (determinism hardening), §5.2 (browserGpuMode row) and §9.3 (BROWSER_GPU_NOT_SOFTWARE typed failure).

Distributed renders launch Chrome with --use-gl=swiftshader --use-angle=swiftshader so every worker has the same pure-software GL implementation. Those flags are advisory: a misconfigured base image, a missing SwiftShader library, or a chrome://gpu blocklist override can silently downgrade to system GL — and distributed retries would no longer be byte-identical. The validator catches the downgrade post-launch, before any frame is rendered.

How

• Exposed a default readWebGlVendorInfo(page) implementation that pulls structured browserBridge.gpuInfo_.graphics_info.basic_info rows from chrome://gpu (more stable across Chrome versions than the DOM layout of the GPU page).
• Required both an exact vendor match (Google Inc. (Google)) and a case-insensitive swiftshader substring in the renderer string. Either alone is insufficient.
• assertSwiftShader(page, readInfo?) accepts an injectable readInfo so unit tests can drive the assertion without spinning up real Chrome.
• SwiftShaderAssertionError carries the offending vendor + renderer strings on the error for diagnostic surfacing.

Test plan

• Unit tests added: assertSwiftShader.test.ts covers the canonical accept case, case/whitespace tolerance, the NVIDIA / Intel fallthrough rejects, empty-string failure, propagation of reader errors, and a third-party vendor + "SwiftShader compatible" renderer is still rejected.
• No caller invokes the new utility yet — Phase 3's renderChunk() will run it after browser launch.
• bun run --cwd packages/engine test — 9 new tests + all existing pass.
• bun run --cwd packages/engine typecheck clean.
• bunx oxlint + bunx oxfmt --check clean.

This is part of a stack of 10 PRs; this is PR 2 of 10. Stacked on top of #766.

🤖 Generated with Claude Code

[jrusso1020]

• feat(producer): fail-closed font fetch flag in deterministicFonts #775
• feat(producer): plan-time validator — reject system fonts #774
• feat(producer): plan-time validator — reject GPU encode #773
• feat(producer): audio post-pad/trim helper for assemble #772
• feat(engine): first-frame warmup capture helper for distributed chunks #771
• feat(producer): freezePlan snapshots PRODUCER_RUNTIME_* env vars #770
• feat(producer): seedable Math.random / crypto.getRandomValues shim, gated #769
• refactor(engine): clamp warmupTicks to fixed iteration count, gated #768
• feat(engine): assertSwiftShader chrome://gpu validator #767 👈 (View in Graphite)
• feat(engine): add lockGopForChunkConcat option to buildEncoderArgs #766
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

Clean utility with solid test coverage.

The dual-gate (exact vendor match + case-insensitive renderer substring) is the right call — vendor alone would false-positive on ANGLE backends that share the Google umbrella string. Injectable readInfo makes this fully testable without Chrome, and the SwiftShaderAssertionError.code field gives Temporal retry policies a clean classification target.

One small observation: readWebGlVendorInfo navigates to chrome://gpu with a 30s timeout, which is generous but fine for a post-launch one-shot. If this ever runs in a hot path, that timeout could be tightened — but for Phase 3's boot-time assertion it's appropriate.

Test matrix covers the important edge cases: empty strings, wrong vendor + right renderer, right vendor + wrong renderer, reader errors propagating unwrapped.

LGTM.

— Magi

[vanceingalls]

Strengths:

• Pulling structured browserBridge.gpuInfo_.graphics_info.basic_info from chrome://gpu (assertSwiftShader.ts:78) instead of scraping the DOM is the right call — the DOM layout has drifted across Chrome versions and the structured payload has been stable.
• Both-checks-required logic (assertSwiftShader.ts:101-102): exact vendor match "Google Inc. (Google)" AND case-insensitive swiftshader substring in renderer. The comment at assertSwiftShader.ts:46-50 correctly justifies why neither check alone is sufficient — a third-party renderer string with "SwiftShader compatible" would otherwise pass.
• readInfo injectable on assertSwiftShader(page, readInfo?) (assertSwiftShader.ts:111) cleanly separates the "what we check" from the "how we read it," so the 9 unit tests can drive failure cases without a real Chrome.
• SwiftShaderAssertionError.code is a typed literal (assertSwiftShader.ts:32) — Temporal/Step Functions retry policies key off it, matching the Phase-2 plan §9.3 contract.

Findings:

nit: assertSwiftShader.ts:78 page.goto("chrome://gpu", { waitUntil: "domcontentloaded", timeout: 30_000 }) — chrome://gpu populates browserBridge.gpuInfo_ asynchronously after DOMContentLoaded (Chrome posts the basic_info rows from a separate IPC). On a slow worker, the await page.evaluate(...) may run before basic_info is populated and return empty vendor/renderer strings — which the assertion already correctly treats as failure (good), but the error message would then claim "Chrome reported a non-SwiftShader WebGL backend" when in fact the info hadn't arrived. Consider polling browserBridge?.gpuInfo_?.graphics_info?.basic_info for non-empty rows up to a short timeout, or distinguishing the empty-string case in the error message. Caller will read the error in production logs and "vendor="" renderer=""" is harder to diagnose than "chrome://gpu info not populated within 5s." Not blocking — current behavior fails closed and tests pin the empty-string case.

nit: assertSwiftShader.ts:55 SWIFTSHADER_VENDOR_SIGNATURE = "Google Inc. (Google)" — Chrome occasionally emits this as "Google Inc." without the trailing (Google) on some platforms (older Linux builds). The literal pin will reject those. If hf supports old base images, worth a comment noting the pin is tight to current Chrome. If not, ignore.

Verdict: APPROVE
Reasoning: Validator is well-encapsulated, both-check-required logic is sound, tests cover the rejection matrix; the timing-on-page-load nit is a soft-edges concern that fails closed today.

— Vai

The base branch was changed.