From cb30157ebbbcfedd3606b9d566d565f4412de45e Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Tue, 28 Jul 2026 00:00:21 -0700 Subject: [PATCH 1/2] feat(engine): open drawElement fast capture to Windows hardware GPU MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Widen the default-on drawElement clamp from darwin-only to darwin|win32 (still requiring a non-software-GPU browser). The darwin restriction was a validation envelope, not an architectural limit — the CanvasDrawElement Chrome flag ships on every platform, and every safety layer that made the macOS default-on release (v0.7.38) survivable is platform-neutral: compile-time gates, the SwiftShader init gate, per-render worker-encode self-verification with screenshot fallback, and the blank guard. Worst case on an unvalidated D3D11 backend is the same as on Metal: verify catches a bad frame and the render re-runs on the screenshot baseline. Why now: 30-day telemetry shows ~206k non-CI hardware-GPU Windows renders (~78% of the win32 fleet, 18k installs) held on the slow screenshot path by the clamp — the second-largest perf population after macOS, carrying ~1,550 capture-hours/month in the DE-eligible >=700-frame band alone at a measured ~2x speedup opportunity. Instrumentation for the new cohort: drawElement session init now records the raw WebGL UNMASKED_RENDERER_WEBGL string (detectSwiftShader generalized to detectGpuBackend — same single evaluate, the string was previously read and discarded) and threads it session -> CapturePerfSummary -> RenderPerfSummary -> render_complete as `gpu_renderer`. drawElement damage proved compositor-backend-specific throughout the macOS rollout, so D3D11-cohort failures must cluster by ANGLE backend + GPU vendor (NVIDIA/AMD/Intel), not just `os`. The two DE clamp branches are extracted into a pure, unit-tested `resolveDefaultDrawElement` (platform + GPU mode + worker-encode + explicit opt-in), which also drops resolveConfig's cyclomatic complexity. The win32 streaming-encode compound tests collapse onto one shared helper. Linux stays excluded: that fleet is headless/Docker SwiftShader, where DE has no speedup and known rendering defects. Kill switches unchanged: PRODUCER_EXPERIMENTAL_FAST_CAPTURE=false, --experimental-fast-capture=false. Co-Authored-By: Claude Opus 5 (1M context) --- packages/cli/src/commands/render.ts | 2 +- packages/cli/src/telemetry/events.ts | 3 + packages/engine/src/config.test.ts | 152 +++++++++++------- packages/engine/src/config.ts | 94 +++++++---- .../src/services/drawElementService.test.ts | 41 +++-- .../engine/src/services/drawElementService.ts | 41 +++-- packages/engine/src/services/frameCapture.ts | 14 +- packages/engine/src/types.ts | 8 + .../src/services/render/perfSummary.ts | 4 + .../src/services/renderOrchestrator.ts | 2 + 10 files changed, 251 insertions(+), 110 deletions(-) diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 9b3d067e4c..c70899cb4d 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -1102,7 +1102,6 @@ let deParallelRouterTrialFiredThisProcess = false; * resetting outside a test process where many independent test cases share * one imported module instance. */ -// fallow-ignore-next-line unused-export export function __resetDeParallelRouterTrialStateForTests(): void { deParallelRouterTrialManagedByUs = false; deParallelRouterTrialFiredThisProcess = false; @@ -1429,6 +1428,7 @@ function trackRenderMetrics( deParallelRouter: perf?.drawElement?.parallelRouter, dePreRouterWorkers: perf?.drawElement?.preRouterWorkers, deGateReason: perf?.drawElement?.gateReason, + gpuRenderer: perf?.drawElement?.gpuRenderer, deWorkerEncode: perf?.drawElement?.workerEncode, deVerifyArmed: perf?.drawElement?.verifyArmed, deVerifyChecked: perf?.drawElement?.verifyChecked, diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts index 8c67b88a4d..05a0bb50f4 100644 --- a/packages/cli/src/telemetry/events.ts +++ b/packages/cli/src/telemetry/events.ts @@ -183,6 +183,8 @@ export function trackRenderComplete( deParallelRouter?: string; dePreRouterWorkers?: number; deGateReason?: string; + /** Raw WebGL renderer string from DE session init (ANGLE backend + GPU vendor). */ + gpuRenderer?: string; deWorkerEncode?: boolean; deVerifyArmed?: number; deVerifyChecked?: number; @@ -280,6 +282,7 @@ export function trackRenderComplete( de_parallel_router: props.deParallelRouter, de_pre_router_workers: props.dePreRouterWorkers, de_gate_reason: props.deGateReason, + gpu_renderer: props.gpuRenderer, de_worker_encode: props.deWorkerEncode, de_verify_armed: props.deVerifyArmed, de_verify_checked: props.deVerifyChecked, diff --git a/packages/engine/src/config.test.ts b/packages/engine/src/config.test.ts index e917e3031a..ce683547e3 100644 --- a/packages/engine/src/config.test.ts +++ b/packages/engine/src/config.test.ts @@ -3,6 +3,7 @@ import { join } from "node:path"; import { tmpdir } from "node:os"; import { resolveConfig, + resolveDefaultDrawElement, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, @@ -232,6 +233,40 @@ describe("resolveConfig", () => { }); }); + describe("resolveDefaultDrawElement (pure host clamp)", () => { + const base = { + useDrawElement: true, + explicitOptIn: false, + browserGpuMode: "hardware" as const, + workerEncode: true, + }; + it("engages on darwin and win32, not linux", () => { + expect(resolveDefaultDrawElement({ ...base, platform: "darwin" })).toBe(true); + expect(resolveDefaultDrawElement({ ...base, platform: "win32" })).toBe(true); + expect(resolveDefaultDrawElement({ ...base, platform: "linux" })).toBe(false); + }); + it("software GPU clamps off even on supported platforms", () => { + expect( + resolveDefaultDrawElement({ ...base, platform: "win32", browserGpuMode: "software" }), + ).toBe(false); + }); + it("explicit opt-in overrides platform and GPU clamps", () => { + expect( + resolveDefaultDrawElement({ + ...base, + explicitOptIn: true, + platform: "linux", + browserGpuMode: "software", + }), + ).toBe(true); + }); + it("no worker-encode (no verify net) clamps the default off", () => { + expect(resolveDefaultDrawElement({ ...base, platform: "darwin", workerEncode: false })).toBe( + false, + ); + }); + }); + describe("useDrawElement (PRODUCER_EXPERIMENTAL_FAST_CAPTURE)", () => { it("default is clamped off on software-GPU hosts (page-side compositing preserved)", () => { setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); @@ -242,21 +277,20 @@ describe("resolveConfig", () => { expect(config.enablePageSideCompositing).toBe(true); }); - it("default engages on macOS with a hardware-GPU browser", () => { - setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware"); - unsetEnv("PRODUCER_EXPERIMENTAL_FAST_CAPTURE"); - unsetEnv("HF_DE_WORKER_ENCODE"); - const config = resolveConfig(); - expect(config.useDrawElement).toBe(process.platform === "darwin"); - }); - - it("default engages on macOS with auto GPU mode (the stock CLI path)", () => { - setEnv("PRODUCER_BROWSER_GPU_MODE", "auto"); - unsetEnv("PRODUCER_EXPERIMENTAL_FAST_CAPTURE"); - unsetEnv("HF_DE_WORKER_ENCODE"); - const config = resolveConfig(); - expect(config.useDrawElement).toBe(process.platform === "darwin"); - }); + // win32 opened 2026-07-27 (was darwin-only): ~206k non-CI hardware-GPU + // Windows renders / 30d sat on the screenshot path behind the old clamp. + // "auto" is the stock CLI path; both must pass the platform clamp. + for (const gpuMode of ["hardware", "auto"] as const) { + it(`default engages on macOS/Windows with ${gpuMode} GPU mode`, () => { + setEnv("PRODUCER_BROWSER_GPU_MODE", gpuMode); + unsetEnv("PRODUCER_EXPERIMENTAL_FAST_CAPTURE"); + unsetEnv("HF_DE_WORKER_ENCODE"); + const config = resolveConfig(); + expect(config.useDrawElement).toBe( + process.platform === "darwin" || process.platform === "win32", + ); + }); + } it("default requires worker-encode (the verified drain)", () => { setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware"); @@ -624,40 +658,58 @@ describe("resolveConfig", () => { Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true }); }); - it("auto-disables on win32 + software-GPU + workers=1 + no user opt-in", () => { - setPlatform("win32"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - setEnv("PRODUCER_MAX_WORKERS", "1"); + /** + * Shared setup/assert for the win32 software-GPU compound: fixed common + * env (low-memory on, no explicit streaming opt-in), variable platform / + * gpu / workers, then assert whether the auto-disable fired. + */ + function expectCompoundOutcome(opts: { + platform: NodeJS.Platform; + gpuMode?: string; + workers?: string; + autoDisabled: boolean; + }): void { + setPlatform(opts.platform); + if (opts.gpuMode === undefined) unsetEnv("PRODUCER_BROWSER_GPU_MODE"); + else setEnv("PRODUCER_BROWSER_GPU_MODE", opts.gpuMode); + if (opts.workers === undefined) unsetEnv("PRODUCER_MAX_WORKERS"); + else setEnv("PRODUCER_MAX_WORKERS", opts.workers); setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(false); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true); + expect(config.enableStreamingEncode).toBe(!opts.autoDisabled); + if (opts.autoDisabled) { + expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true); + } else { + expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + } + } + + it("auto-disables on win32 + software-GPU + workers=1 + no user opt-in", () => { + expectCompoundOutcome({ + platform: "win32", + gpuMode: "software", + workers: "1", + autoDisabled: true, + }); }); it("leaves streaming-encode on when platform is linux", () => { - setPlatform("linux"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - setEnv("PRODUCER_MAX_WORKERS", "1"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(true); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + expectCompoundOutcome({ + platform: "linux", + gpuMode: "software", + workers: "1", + autoDisabled: false, + }); }); it("leaves streaming-encode on when workers > 1", () => { - setPlatform("win32"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - setEnv("PRODUCER_MAX_WORKERS", "4"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(true); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + expectCompoundOutcome({ + platform: "win32", + gpuMode: "software", + workers: "4", + autoDisabled: false, + }); }); it("respects explicit env opt-in (PRODUCER_ENABLE_STREAMING_ENCODE=true) on the compound", () => { @@ -703,16 +755,8 @@ describe("resolveConfig", () => { // --low-memory-mode implies screenshot capture. Compound applies even // if browserGpuMode is not literal "software" (defense-in-depth: matches // the OR semantics in `softwareGpuForced`). - setPlatform("win32"); - unsetEnv("PRODUCER_BROWSER_GPU_MODE"); unsetEnv("PRODUCER_DISABLE_GPU"); - setEnv("PRODUCER_MAX_WORKERS", "1"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(false); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true); + expectCompoundOutcome({ platform: "win32", workers: "1", autoDisabled: true }); }); it("does not trigger when concurrency is 'auto' (workers not explicitly pinned)", () => { @@ -720,15 +764,7 @@ describe("resolveConfig", () => { // helper's numeric workers check treats NaN as "unknown, don't trigger". // Downstream workers may still resolve to 1 via lowMemoryMode, but the // config-time clamp is deliberately conservative. - setPlatform("win32"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - unsetEnv("PRODUCER_MAX_WORKERS"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(true); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + expectCompoundOutcome({ platform: "win32", gpuMode: "software", autoDisabled: false }); }); }); diff --git a/packages/engine/src/config.ts b/packages/engine/src/config.ts index b350f9e674..fb06796fe3 100644 --- a/packages/engine/src/config.ts +++ b/packages/engine/src/config.ts @@ -66,8 +66,8 @@ export interface EngineConfig { /** * Use drawElementImage for frame capture (requires the CanvasDrawElement * Chrome flag, added globally in buildChromeArgs). Default ON, clamped in - * `resolveConfig` to hosts where it can actually engage (macOS + hardware-GPU - * browser); compile/init gates and the runtime self-verification net route + * `resolveConfig` to hosts where it can actually engage (macOS or Windows + + * hardware-GPU browser); compile/init gates and the runtime self-verification net route * incompatible or damaged renders back to screenshot capture. * Kill switch: `PRODUCER_EXPERIMENTAL_FAST_CAPTURE=false` (or the CLI * `--experimental-fast-capture=false`). @@ -708,6 +708,39 @@ function memoryAdaptiveCacheBytesMb(): number { * Env vars provide backward compatibility during migration; explicit config * takes precedence over everything. */ +/** + * Platforms where default-on drawElement may engage: macOS (Metal-ANGLE, + * the original validated envelope) and Windows (D3D11-ANGLE, opened + * 2026-07-27 — see the clamp comment above resolveDefaultDrawElement's call + * site). Linux is excluded: that fleet is headless/Docker SwiftShader. + * Internal — the exported `resolveDefaultDrawElement` is the tested surface. + */ +function isDrawElementPlatform(platform: NodeJS.Platform): boolean { + return platform === "darwin" || platform === "win32"; +} + +/** + * Default-on drawElement host clamp. An explicit opt-in always wins (attempt + * DE, let the init-time gates route away — debugging relies on it). Otherwise + * DE stays on only where it can actually engage — a supported platform with a + * non-software-GPU browser — AND with worker-encode enabled: the runtime + * self-verification net lives in the worker-encode drain (the serial path has + * only the blank guard), so a default-on session without it would ship + * unverified drawElement frames. Pure; exported for tests. + */ +export function resolveDefaultDrawElement(args: { + useDrawElement: boolean; + explicitOptIn: boolean; + platform: NodeJS.Platform; + browserGpuMode: EngineConfig["browserGpuMode"]; + workerEncode: boolean; +}): boolean { + if (!args.useDrawElement) return false; + if (args.explicitOptIn) return true; + if (!isDrawElementPlatform(args.platform) || args.browserGpuMode === "software") return false; + return args.workerEncode; +} + export function resolveConfig(overrides?: Partial): EngineConfig { const env = (key: string): string | undefined => process.env[key]; const envNum = (key: string, fallback: number): number => { @@ -857,38 +890,45 @@ export function resolveConfig(overrides?: Partial): EngineConfig { }; // Default-on drawElement is clamped to hosts where it can actually engage - // (macOS with a non-software-GPU browser; SwiftShader drops transparent - // sub-layers — crbug 521434899). "auto" passes the clamp: the stock CLI - // resolves GPU mode to auto, which probes to hardware on real Macs — and if - // it resolves to software after all, the SwiftShader init-time gate still - // routes the session to the screenshot baseline. Without the clamp, the - // default would needlessly disable page-side shader compositing (below) on - // Linux/Docker hosts where DE never runs. An EXPLICIT opt-in (env or caller override) - // skips the clamp and keeps the old semantics — attempt DE, let the - // init-time gates route away — which debugging relies on. + // (macOS or Windows with a non-software-GPU browser; SwiftShader drops + // transparent sub-layers — crbug 521434899). "auto" passes the clamp: the + // stock CLI resolves GPU mode to auto, which probes to hardware on real + // Macs/PCs — and if it resolves to software after all, the SwiftShader + // init-time gate still routes the session to the screenshot baseline. + // Without the clamp, the default would needlessly disable page-side shader + // compositing (below) on Linux/Docker hosts where DE never runs. An + // EXPLICIT opt-in (env or caller override) skips the clamp and keeps the + // old semantics — attempt DE, let the init-time gates route away — which + // debugging relies on. + // + // win32 opened 2026-07-27: telemetry showed ~206k non-CI hardware-GPU + // Windows renders / 30d (~78% of the win32 fleet) held on the slow + // screenshot path by the darwin-only clamp — the second-largest perf + // population after macOS. The mechanism is platform-neutral (the Chrome + // flag ships everywhere); darwin-only was a validation envelope, not an + // architectural limit. Opening it rides the same per-render safety + // contract macOS shipped with in v0.7.38: compile/init gates + + // worker-encode self-verify + screenshot fallback catch damage per + // render, and `gpu_renderer` telemetry (captured at DE session init) + // segments the D3D11/ANGLE cohort by GPU vendor so backend-specific + // damage clusters are attributable. Kill switches unchanged + // (PRODUCER_EXPERIMENTAL_FAST_CAPTURE=false; per-render --workers). + // Linux stays excluded: the fleet there is headless/Docker SwiftShader. const explicitDrawElementOptIn = env("PRODUCER_EXPERIMENTAL_FAST_CAPTURE") === "true" || overrides?.useDrawElement === true; - if ( - merged.useDrawElement && - !explicitDrawElementOptIn && - !(process.platform === "darwin" && merged.browserGpuMode !== "software") - ) { - merged.useDrawElement = false; - } - // The runtime self-verification net lives in the worker-encode drain — the - // serial drawElement path has only the blank guard. Default-on drawElement - // therefore requires worker-encode; disabling HF_DE_WORKER_ENCODE without an - // explicit drawElement opt-in falls back to the screenshot baseline rather - // than shipping unverified drawElement frames. - if (merged.useDrawElement && !explicitDrawElementOptIn && !merged.enableDrawElementWorkerEncode) { - merged.useDrawElement = false; - } + merged.useDrawElement = resolveDefaultDrawElement({ + useDrawElement: merged.useDrawElement, + explicitOptIn: explicitDrawElementOptIn, + platform: process.platform, + browserGpuMode: merged.browserGpuMode, + workerEncode: merged.enableDrawElementWorkerEncode, + }); // Software GPU implies screenshot capture. // // Two existing platform gates already do most of the work: `browserManager` // only launches BeginFrame on Linux + chrome-headless-shell + !forceScreenshot, - // and the DE clamp above turns off `useDrawElement` on non-(darwin + + // and the DE clamp above turns off `useDrawElement` on non-((darwin|win32) + // non-software) hosts. Setting `forceScreenshot` here layers defense-in-depth // on top: // diff --git a/packages/engine/src/services/drawElementService.test.ts b/packages/engine/src/services/drawElementService.test.ts index d877c97a0d..a21f9602ed 100644 --- a/packages/engine/src/services/drawElementService.test.ts +++ b/packages/engine/src/services/drawElementService.test.ts @@ -1,34 +1,49 @@ import { describe, expect, it, vi } from "vitest"; import type { Page } from "puppeteer-core"; -import { detectSwiftShader, resolveDrawElementCaptureMode } from "./drawElementService.js"; +import { + detectGpuBackend, + detectSwiftShader, + resolveDrawElementCaptureMode, +} from "./drawElementService.js"; -// ── detectSwiftShader ────────────────────────────────────────────────────────── +// ── detectGpuBackend / detectSwiftShader ─────────────────────────────────────── -describe("detectSwiftShader", () => { +describe("detectGpuBackend", () => { function makePage(evaluateResult: unknown): Page { return { evaluate: vi.fn().mockResolvedValue(evaluateResult), } as unknown as Page; } - it("returns true when renderer includes 'swiftshader'", async () => { - const page = makePage(true); - expect(await detectSwiftShader(page)).toBe(true); + it("carries the raw renderer string alongside the SwiftShader verdict", async () => { + const page = makePage({ + isSwiftShader: false, + renderer: "ANGLE (NVIDIA, D3D11 vs_5_0 ps_5_0, D3D11)", + }); + expect(await detectGpuBackend(page)).toEqual({ + isSwiftShader: false, + renderer: "ANGLE (NVIDIA, D3D11 vs_5_0 ps_5_0, D3D11)", + }); }); - it("returns false for a standard GPU renderer string", async () => { - const page = makePage(false); - expect(await detectSwiftShader(page)).toBe(false); + it("reports null renderer when WebGL is unavailable", async () => { + const page = makePage({ isSwiftShader: false, renderer: null }); + expect(await detectGpuBackend(page)).toEqual({ isSwiftShader: false, renderer: null }); + }); + + it("detectSwiftShader wrapper returns true when renderer is SwiftShader", async () => { + const page = makePage({ isSwiftShader: true, renderer: "Google SwiftShader" }); + expect(await detectSwiftShader(page)).toBe(true); }); - it("returns false when WebGL is unavailable", async () => { - const page = makePage(false); + it("detectSwiftShader wrapper returns false for a hardware renderer", async () => { + const page = makePage({ isSwiftShader: false, renderer: "ANGLE (Apple, ANGLE Metal)" }); expect(await detectSwiftShader(page)).toBe(false); }); it("passes a function to page.evaluate", async () => { - const page = makePage(false); - await detectSwiftShader(page); + const page = makePage({ isSwiftShader: false, renderer: null }); + await detectGpuBackend(page); expect(page.evaluate).toHaveBeenCalledWith(expect.any(Function)); }); }); diff --git a/packages/engine/src/services/drawElementService.ts b/packages/engine/src/services/drawElementService.ts index 99b126424d..a5d08eb08b 100644 --- a/packages/engine/src/services/drawElementService.ts +++ b/packages/engine/src/services/drawElementService.ts @@ -105,27 +105,50 @@ export function instrumentAcceleratedCanvases(): void { }; } +export interface GpuBackendInfo { + /** SwiftShader (software rasterizer) — e.g. Docker headless-shell. */ + isSwiftShader: boolean; + /** + * Raw UNMASKED_RENDERER_WEBGL string (e.g. "ANGLE (Apple, ANGLE Metal + * Renderer: Apple M4 Pro, ...)", "ANGLE (NVIDIA, D3D11 ...)"), or null when + * WebGL / the debug extension is unavailable. Carried to render telemetry: + * drawElement failure modes proved compositor-backend-specific during the + * macOS rollout, so the win32/D3D11 cohort needs damage clusters + * attributable to a GPU vendor + ANGLE backend, not just `os`. + */ + renderer: string | null; +} + /** - * Detect whether the page is running on SwiftShader (software rasterizer). + * Detect the page's WebGL backend: SwiftShader vs a real GPU, plus the raw + * renderer string for telemetry. * - * Returns true inside Docker headless-shell with --use-angle=swiftshader. - * Returns false on macOS / Linux with a real GPU. - * Call once after window.__hf is ready; cache result on session. + * `isSwiftShader` is true inside Docker headless-shell with + * --use-angle=swiftshader. Call once after window.__hf is ready; cache the + * result on the session. */ -export async function detectSwiftShader(page: Page): Promise { - return page.evaluate(() => { +export async function detectGpuBackend(page: Page): Promise { + return page.evaluate((): GpuBackendInfo => { const canvas = document.createElement("canvas"); const gl = canvas.getContext("webgl") || (canvas.getContext("experimental-webgl") as WebGLRenderingContext | null); - if (!gl) return false; + if (!gl) return { isSwiftShader: false, renderer: null }; const ext = gl.getExtension("WEBGL_debug_renderer_info"); - if (!ext) return false; + if (!ext) return { isSwiftShader: false, renderer: null }; const renderer = gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) as string; - return renderer.toLowerCase().includes("swiftshader"); + return { isSwiftShader: renderer.toLowerCase().includes("swiftshader"), renderer }; }); } +/** + * Back-compat wrapper over {@link detectGpuBackend} for callers that only + * need the SwiftShader boolean. + */ +export async function detectSwiftShader(page: Page): Promise { + return (await detectGpuBackend(page)).isSwiftShader; +} + /** * Inject a `` around the composition root. * diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index af977c3a61..88e044cb47 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -34,7 +34,7 @@ import { shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js"; import { - detectSwiftShader, + detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, @@ -146,6 +146,13 @@ export interface CaptureSession { config?: Partial; /** True if running on SwiftShader (detected at init). Undefined before init. */ isSwiftShader?: boolean; + /** + * Raw WebGL UNMASKED_RENDERER_WEBGL string, captured alongside the + * SwiftShader probe at DE session init (e.g. "ANGLE (NVIDIA, D3D11 ...)"). + * Surfaces in CapturePerfSummary → render telemetry so backend-specific + * drawElement damage (Metal vs D3D11 vs GL) clusters attributably. + */ + gpuRenderer?: string; /** drawElementImage canvas was injected and is ready for capture. */ drawElementReady?: boolean; /** @@ -704,7 +711,9 @@ async function initDrawElementOrTransparentBackground( ); } if (useDrawElement) { - session.isSwiftShader = await detectSwiftShader(page); + const gpuBackend = await detectGpuBackend(page); + session.isSwiftShader = gpuBackend.isSwiftShader; + session.gpuRenderer = gpuBackend.renderer ?? undefined; const transparent = session.options.format === "png"; async function routeToFallback(): Promise { session.captureMode = session.launchCaptureMode; @@ -3784,6 +3793,7 @@ export function getCapturePerfSummary(session: CaptureSession): CapturePerfSumma beginFrameNoDamage: session.beginFrameNoDamageCount, beginFrameHasDamage: session.beginFrameHasDamageCount, captureMode: session.captureMode, + gpuRenderer: session.gpuRenderer, deGateReason: session.deGateReason, deFallbackTrigger: session.deFallbackTrigger, deWorkerEncode: session.workerEncodeEnabled ?? false, diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts index cc467c3289..9253e00df7 100644 --- a/packages/engine/src/types.ts +++ b/packages/engine/src/types.ts @@ -276,6 +276,14 @@ export interface CapturePerfSummary { // ── drawElement fast-capture outcome (default-on release visibility) ── /** Final capture mode this session used: "drawelement" | "screenshot" | "beginframe". */ captureMode: string; + /** + * Raw WebGL UNMASKED_RENDERER_WEBGL string from DE session init (ANGLE + * backend + GPU vendor, e.g. "ANGLE (Apple, ANGLE Metal Renderer: ...)"). + * Undefined when drawElement was never attempted. Lets telemetry cluster + * backend-specific damage now that DE engages on both Metal (darwin) and + * D3D11 (win32). + */ + gpuRenderer?: string; /** * Low-cardinality init-time gate that routed a drawElement-eligible session * to the baseline: `swiftshader` | `css_effect:` | `at_risk_timeline` | diff --git a/packages/producer/src/services/render/perfSummary.ts b/packages/producer/src/services/render/perfSummary.ts index 2e288edc4c..fe72e1e1c0 100644 --- a/packages/producer/src/services/render/perfSummary.ts +++ b/packages/producer/src/services/render/perfSummary.ts @@ -111,6 +111,9 @@ function aggregateDrawElement( const gateReasons = [ ...new Set(perfs.map((p) => p.deGateReason).filter((r): r is string => !!r)), ].sort(); + const gpuRenderers = [ + ...new Set(perfs.map((p) => p.gpuRenderer).filter((r): r is string => !!r)), + ].sort(); const drain = de.drainStats; return { mode: modes.join("|") || "unknown", @@ -121,6 +124,7 @@ function aggregateDrawElement( parallelRouter: de.parallelRouter ?? "none", preRouterWorkers: de.preRouterWorkers, gateReason: gateReasons.length > 0 ? gateReasons.join("|") : undefined, + gpuRenderer: gpuRenderers.length > 0 ? gpuRenderers.join("|") : undefined, workerEncode: perfs.some((p) => p.deWorkerEncode), verifyArmed: perfs.reduce((sum, p) => sum + (p.deVerifyArmed ?? 0), 0), verifyChecked: drain?.verifyChecked ?? 0, diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 504137f121..5417ef3fd5 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -498,6 +498,8 @@ export interface RenderPerfSummary { preRouterWorkers?: number; /** Engine init-time gate: swiftshader | css_effect:* | at_risk_timeline | 3d_init_failed | supersampling | render_mode_hint. */ gateReason?: string; + /** Raw WebGL renderer string from DE session init (ANGLE backend + GPU vendor); |-joined across parallel sessions. */ + gpuRenderer?: string; /** Worker-encode drain (the verified path) was active. */ workerEncode: boolean; /** Self-verification ground-truth samples armed at init. */ From 4520cd240b9a4ac20f77e6a2e8204866e549fd35 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Tue, 28 Jul 2026 00:55:10 -0700 Subject: [PATCH 2/2] fix(engine): bucket gpu_renderer + cover the failure cohort (review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three review findings on the win32 drawElement PR: 1. gpu_renderer shipped the raw UNMASKED_RENDERER_WEBGL string — unbounded, driver-authored, GPU-model-specific, and |-joined across parallel sessions, i.e. high cardinality by construction, against this file's own convention of sanitizing engine-sourced strings (deGateReason is a bucket; error messages go through redactTelemetryString). Now bucketed at the source by classifyGpuRenderer to / (metal/apple, d3d11/nvidia, swiftshader/other, ...), which is the whole analytic signal the win32 rollout needs and nothing else. The raw string never leaves the engine. 2. gpu_renderer reached render_complete only, so a crashed render — the cohort the field exists to attribute — carried no backend. It now rides RenderCaptureObservability (deGpuRenderer, sourced from the live probe session like the de_* counters), so both render_complete and render_error carry it and a hard failure still reports its GPU backend. On render_complete the perfSummary value still wins by spread order. 3. Restore the fallow-ignore-next-line suppression above __resetDeParallelRouterTrialStateForTests: CLI test files are not fallow entry points, so removing it fails the CI dead-code audit (local pre-commit passed only because of its changed-file scope). Co-Authored-By: Claude Opus 5 (1M context) --- packages/cli/src/commands/render.ts | 1 + packages/cli/src/telemetry/events.ts | 8 ++- .../cli/src/telemetry/renderObservability.ts | 1 + .../src/services/drawElementService.test.ts | 37 +++++++++++++ .../engine/src/services/drawElementService.ts | 53 +++++++++++++++++-- packages/engine/src/services/frameCapture.ts | 13 +++-- packages/engine/src/types.ts | 10 ++-- .../src/services/render/observability.ts | 7 +++ .../src/services/renderOrchestrator.ts | 7 ++- 9 files changed, 120 insertions(+), 17 deletions(-) diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index c70899cb4d..3fe44e20d2 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -1102,6 +1102,7 @@ let deParallelRouterTrialFiredThisProcess = false; * resetting outside a test process where many independent test cases share * one imported module instance. */ +// fallow-ignore-next-line unused-export export function __resetDeParallelRouterTrialStateForTests(): void { deParallelRouterTrialManagedByUs = false; deParallelRouterTrialFiredThisProcess = false; diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts index 05a0bb50f4..d7593d84f3 100644 --- a/packages/cli/src/telemetry/events.ts +++ b/packages/cli/src/telemetry/events.ts @@ -51,6 +51,7 @@ export interface RenderObservabilityTelemetryPayload { captureDeWorkerInversion?: string; captureDePreInversionWorkers?: number; captureDeParallelRouter?: string; + captureDeGpuRenderer?: string; captureDePreRouterWorkers?: number; captureDeSelfVerifyFallback?: boolean; captureDeFallbackReason?: string; @@ -108,6 +109,7 @@ function renderObservabilityEventProperties(props: RenderObservabilityTelemetryP de_worker_inversion: props.captureDeWorkerInversion, de_pre_inversion_workers: props.captureDePreInversionWorkers, de_parallel_router: props.captureDeParallelRouter, + gpu_renderer: props.captureDeGpuRenderer, de_pre_router_workers: props.captureDePreRouterWorkers, de_self_verify_fallback: props.captureDeSelfVerifyFallback, de_fallback_reason: props.captureDeFallbackReason, @@ -183,7 +185,7 @@ export function trackRenderComplete( deParallelRouter?: string; dePreRouterWorkers?: number; deGateReason?: string; - /** Raw WebGL renderer string from DE session init (ANGLE backend + GPU vendor). */ + /** Low-cardinality GPU bucket from DE session init (`/`, e.g. `d3d11/nvidia`). */ gpuRenderer?: string; deWorkerEncode?: boolean; deVerifyArmed?: number; @@ -377,6 +379,10 @@ export function trackRenderError( elapsed_ms: props.elapsedMs, peak_memory_mb: props.peakMemoryMb, memory_free_mb: props.memoryFreeMb, + // gpu_renderer arrives via renderObservabilityEventProperties below: + // on the failure path perfSummary is never built, so live capture + // observability is the only source. Backend attribution matters MOST + // here — a win32 D3D11 crash is what the rollout is watching for. ...renderObservabilityEventProperties(props), }, props.distinctId, diff --git a/packages/cli/src/telemetry/renderObservability.ts b/packages/cli/src/telemetry/renderObservability.ts index 3df009f4df..87554d6939 100644 --- a/packages/cli/src/telemetry/renderObservability.ts +++ b/packages/cli/src/telemetry/renderObservability.ts @@ -43,6 +43,7 @@ export function renderObservabilityTelemetryPayload( captureDeWorkerInversion: capture.deWorkerInversion, captureDePreInversionWorkers: capture.dePreInversionWorkers, captureDeParallelRouter: capture.deParallelRouter, + captureDeGpuRenderer: capture.deGpuRenderer, captureDePreRouterWorkers: capture.dePreRouterWorkers, captureDeSelfVerifyFallback: capture.deSelfVerifyFallback, captureDeFallbackReason: capture.deFallbackReason, diff --git a/packages/engine/src/services/drawElementService.test.ts b/packages/engine/src/services/drawElementService.test.ts index a21f9602ed..3645425079 100644 --- a/packages/engine/src/services/drawElementService.test.ts +++ b/packages/engine/src/services/drawElementService.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it, vi } from "vitest"; import type { Page } from "puppeteer-core"; import { + classifyGpuRenderer, detectGpuBackend, detectSwiftShader, resolveDrawElementCaptureMode, @@ -48,6 +49,42 @@ describe("detectGpuBackend", () => { }); }); +// ── classifyGpuRenderer ──────────────────────────────────────────────────────── + +describe("classifyGpuRenderer", () => { + it("buckets real ANGLE renderer strings to /", () => { + expect( + classifyGpuRenderer("ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Pro, Unspecified Version)"), + ).toBe("metal/apple"); + expect( + classifyGpuRenderer( + "ANGLE (NVIDIA, NVIDIA GeForce RTX 3080 Direct3D11 vs_5_0 ps_5_0, D3D11)", + ), + ).toBe("d3d11/nvidia"); + expect( + classifyGpuRenderer("ANGLE (Intel, Intel(R) UHD Graphics 630 Direct3D11 vs_5_0 ps_5_0)"), + ).toBe("d3d11/intel"); + expect(classifyGpuRenderer("ANGLE (AMD, AMD Radeon RX 6800 Direct3D11 vs_5_0 ps_5_0)")).toBe( + "d3d11/amd", + ); + expect(classifyGpuRenderer("Google SwiftShader")).toBe("swiftshader/other"); + }); + + it("drops the GPU model — the bucket must stay low cardinality", () => { + // Two different NVIDIA cards must collapse to ONE bucket, otherwise the + // property is unbounded and useless for aggregation. + expect(classifyGpuRenderer("ANGLE (NVIDIA, NVIDIA GeForce RTX 4090 Direct3D11)")).toBe( + classifyGpuRenderer("ANGLE (NVIDIA, NVIDIA GeForce GTX 1060 Direct3D11)"), + ); + }); + + it("returns undefined for missing input rather than a bogus bucket", () => { + expect(classifyGpuRenderer(null)).toBeUndefined(); + expect(classifyGpuRenderer(undefined)).toBeUndefined(); + expect(classifyGpuRenderer("")).toBeUndefined(); + }); +}); + // ── resolveDrawElementCaptureMode ────────────────────────────────────────────── describe("resolveDrawElementCaptureMode", () => { diff --git a/packages/engine/src/services/drawElementService.ts b/packages/engine/src/services/drawElementService.ts index a5d08eb08b..05f8ab8203 100644 --- a/packages/engine/src/services/drawElementService.ts +++ b/packages/engine/src/services/drawElementService.ts @@ -110,15 +110,58 @@ export interface GpuBackendInfo { isSwiftShader: boolean; /** * Raw UNMASKED_RENDERER_WEBGL string (e.g. "ANGLE (Apple, ANGLE Metal - * Renderer: Apple M4 Pro, ...)", "ANGLE (NVIDIA, D3D11 ...)"), or null when - * WebGL / the debug extension is unavailable. Carried to render telemetry: - * drawElement failure modes proved compositor-backend-specific during the - * macOS rollout, so the win32/D3D11 cohort needs damage clusters - * attributable to a GPU vendor + ANGLE backend, not just `os`. + * Renderer: Apple M4 Pro, ...)", "ANGLE (NVIDIA, GeForce RTX 3080 Direct3D11 + * vs_5_0 ps_5_0, D3D11)"), or null when WebGL / the debug extension is + * unavailable. LOCAL USE ONLY — this is unbounded driver-supplied text and + * must not be shipped to telemetry verbatim; send + * {@link classifyGpuRenderer}'s bucket instead. */ renderer: string | null; } +/** + * Low-cardinality bucket for a raw WebGL renderer string: `/` + * (e.g. `metal/apple`, `d3d11/nvidia`, `swiftshader/other`). + * + * drawElement failure modes proved compositor-backend-specific during the + * macOS rollout, so the win32/D3D11 cohort needs damage attributable to an + * ANGLE backend + GPU vendor. The raw string can't do that job in telemetry: + * it is unbounded, driver-authored, carries specific GPU model names, and is + * joined across parallel sessions — high cardinality by construction. The + * bucket keeps the analytic signal (which backend, which vendor) and drops + * everything else, matching how `deGateReason` is a sanitized bucket rather + * than the full fallback trigger. Pure; exported for tests. + */ +export function classifyGpuRenderer(renderer: string | null | undefined): string | undefined { + if (!renderer) return undefined; + const r = renderer.toLowerCase(); + const backend = r.includes("swiftshader") + ? "swiftshader" + : r.includes("metal") + ? "metal" + : r.includes("direct3d11") || r.includes("d3d11") + ? "d3d11" + : r.includes("direct3d9") || r.includes("d3d9") + ? "d3d9" + : r.includes("vulkan") + ? "vulkan" + : r.includes("opengl") || r.includes("angle") + ? "opengl" + : "other"; + const vendor = r.includes("apple") + ? "apple" + : r.includes("nvidia") + ? "nvidia" + : r.includes("amd") || r.includes("radeon") + ? "amd" + : r.includes("intel") + ? "intel" + : r.includes("microsoft") + ? "microsoft" + : "other"; + return `${backend}/${vendor}`; +} + /** * Detect the page's WebGL backend: SwiftShader vs a real GPU, plus the raw * renderer string for telemetry. diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index 88e044cb47..4751f7a053 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -34,6 +34,7 @@ import { shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js"; import { + classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, @@ -147,10 +148,12 @@ export interface CaptureSession { /** True if running on SwiftShader (detected at init). Undefined before init. */ isSwiftShader?: boolean; /** - * Raw WebGL UNMASKED_RENDERER_WEBGL string, captured alongside the - * SwiftShader probe at DE session init (e.g. "ANGLE (NVIDIA, D3D11 ...)"). - * Surfaces in CapturePerfSummary → render telemetry so backend-specific - * drawElement damage (Metal vs D3D11 vs GL) clusters attributably. + * Low-cardinality GPU bucket (`/`, e.g. `d3d11/nvidia`) + * derived from the WebGL renderer at DE session init. Surfaces in + * CapturePerfSummary → render telemetry so backend-specific drawElement + * damage (Metal vs D3D11 vs GL) clusters attributably. The raw + * driver-supplied string is deliberately NOT retained — see + * classifyGpuRenderer. */ gpuRenderer?: string; /** drawElementImage canvas was injected and is ready for capture. */ @@ -713,7 +716,7 @@ async function initDrawElementOrTransparentBackground( if (useDrawElement) { const gpuBackend = await detectGpuBackend(page); session.isSwiftShader = gpuBackend.isSwiftShader; - session.gpuRenderer = gpuBackend.renderer ?? undefined; + session.gpuRenderer = classifyGpuRenderer(gpuBackend.renderer); const transparent = session.options.format === "png"; async function routeToFallback(): Promise { session.captureMode = session.launchCaptureMode; diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts index 9253e00df7..4f30c1efba 100644 --- a/packages/engine/src/types.ts +++ b/packages/engine/src/types.ts @@ -277,11 +277,11 @@ export interface CapturePerfSummary { /** Final capture mode this session used: "drawelement" | "screenshot" | "beginframe". */ captureMode: string; /** - * Raw WebGL UNMASKED_RENDERER_WEBGL string from DE session init (ANGLE - * backend + GPU vendor, e.g. "ANGLE (Apple, ANGLE Metal Renderer: ...)"). - * Undefined when drawElement was never attempted. Lets telemetry cluster - * backend-specific damage now that DE engages on both Metal (darwin) and - * D3D11 (win32). + * Low-cardinality GPU bucket from DE session init: `/` + * (e.g. `metal/apple`, `d3d11/nvidia`). Undefined when drawElement was + * never attempted. Lets telemetry cluster backend-specific damage now that + * DE engages on both Metal (darwin) and D3D11 (win32). Bucketed, not raw — + * see `classifyGpuRenderer`. */ gpuRenderer?: string; /** diff --git a/packages/producer/src/services/render/observability.ts b/packages/producer/src/services/render/observability.ts index 23bc938143..39111960cd 100644 --- a/packages/producer/src/services/render/observability.ts +++ b/packages/producer/src/services/render/observability.ts @@ -72,6 +72,13 @@ export interface RenderCaptureObservability { dePreInversionWorkers?: number; /** DE parallel-router outcome: "routed" (fired, held) | "reverted" (fired, self-verify retry rolled back). */ deParallelRouter?: "routed" | "reverted"; + /** + * Low-cardinality GPU bucket (`/`) from the DE probe + * session. Lives on capture observability (not just perfSummary) so a hard + * failure — crash / OOM / timeout — still reports which GPU backend it hit: + * that is precisely the cohort the win32 D3D11 rollout must attribute. + */ + deGpuRenderer?: string; /** Worker count the resolver would have used absent the router; undefined if it never fired. */ dePreRouterWorkers?: number; /** diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 5417ef3fd5..b6bb80af22 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -498,7 +498,7 @@ export interface RenderPerfSummary { preRouterWorkers?: number; /** Engine init-time gate: swiftshader | css_effect:* | at_risk_timeline | 3d_init_failed | supersampling | render_mode_hint. */ gateReason?: string; - /** Raw WebGL renderer string from DE session init (ANGLE backend + GPU vendor); |-joined across parallel sessions. */ + /** Low-cardinality GPU bucket from DE session init (`/`, e.g. `d3d11/nvidia`); |-joined across parallel sessions (bounded: one bucket per distinct backend on the host). */ gpuRenderer?: string; /** Worker-encode drain (the verified path) was active. */ workerEncode: boolean; @@ -2644,6 +2644,11 @@ async function executeRenderPipeline(input: { // any resource-pressure failure unique to this cohort. dePreInversionWorkers: deWorkerInversion ? preRoutingWorkerCount : undefined, dePreRouterWorkers: deParallelRouter ? preRoutingWorkerCount : undefined, + // Same rationale as the counters above: carried on live capture + // observability, not only the success-path perfSummary, so a crash / + // OOM / timeout still reports which GPU backend it happened on. That + // is the cohort the win32 D3D11 rollout most needs to attribute. + deGpuRenderer: probeSession?.gpuRenderer, }); observability.checkpoint("worker_resolution", "resolved", { workerCount,