fix(engine): software-GPU browsers imply screenshot capture

When `browserGpuMode === "software"`, set `forceScreenshot = true` in
`resolveConfig`. Explicit opt-outs (`PRODUCER_FORCE_SCREENSHOT=false`
or `overrides.forceScreenshot === false`) are honored.

This is defense-in-depth on top of the existing platform gates:

1. Linux + software (SwiftShader host) skips BeginFrame, avoiding the
   compositor stall on shader-heavy frames under CPU raster (same
   motivation as the closed PR #822).
2. `renderOrchestrator`'s reported `captureMode` field is derived from
   `cfg.forceScreenshot ? "screenshot" : "beginframe"` — without this
   clamp it misreports `"beginframe"` for the actual screenshot capture
   on darwin + software.
3. Any new BeginFrame or drawElement entry point that forgets to gate
   on GPU mode still routes to screenshot here.

Does NOT fix SwiftShader-on-darwin text-rasterization artifacts (an
ANGLE-SwiftShader issue on macOS text — the fix there is to use
`--browser-gpu`, which routes to `--use-angle=metal`).
This commit is contained in:
Vance Ingalls
2026-07-13 21:38:10 +00:00
parent 9b71bc2103
commit ba5168293f
2 changed files with 78 additions and 0 deletions
+43
View File
@@ -296,6 +296,49 @@ describe("resolveConfig", () => {
});
});
describe("forceScreenshot (software-GPU clamp)", () => {
it("forces screenshot capture when browserGpuMode resolves to software", () => {
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
unsetEnv("PRODUCER_FORCE_SCREENSHOT");
const config = resolveConfig();
expect(config.forceScreenshot).toBe(true);
});
it("leaves forceScreenshot alone on hardware GPU (default off)", () => {
setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware");
unsetEnv("PRODUCER_FORCE_SCREENSHOT");
const config = resolveConfig();
expect(config.forceScreenshot).toBe(false);
});
it("does not force screenshot on auto (auto probes to hardware on real GPUs)", () => {
setEnv("PRODUCER_BROWSER_GPU_MODE", "auto");
unsetEnv("PRODUCER_FORCE_SCREENSHOT");
const config = resolveConfig();
expect(config.forceScreenshot).toBe(false);
});
it("explicit env opt-out (PRODUCER_FORCE_SCREENSHOT=false) is honored on software", () => {
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
setEnv("PRODUCER_FORCE_SCREENSHOT", "false");
const config = resolveConfig();
expect(config.forceScreenshot).toBe(false);
});
it("explicit programmatic opt-out is honored on software", () => {
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
unsetEnv("PRODUCER_FORCE_SCREENSHOT");
const config = resolveConfig({ forceScreenshot: false });
expect(config.forceScreenshot).toBe(false);
});
it("caller override forceScreenshot=true stays true regardless of GPU mode", () => {
setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware");
const config = resolveConfig({ forceScreenshot: true });
expect(config.forceScreenshot).toBe(true);
});
});
describe("lowMemoryMode", () => {
it("forces on for truthy PRODUCER_LOW_MEMORY_MODE values", () => {
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
+35
View File
@@ -554,6 +554,41 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
merged.useDrawElement = false;
}
// 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 +
// non-software) hosts. Setting `forceScreenshot` here layers defense-in-depth
// on top:
//
// 1. Linux + software (SwiftShader host): kicks the browser off BeginFrame,
// which stalls the compositor on shader-heavy frames under CPU raster
// (same motivation as the closed PR #822).
// 2. Observability truth: `renderOrchestrator`'s reported `captureMode`
// field is derived from `cfg.forceScreenshot ? "screenshot" : "beginframe"`
// — without this clamp it misreports `"beginframe"` for the actual
// screenshot capture on darwin + software.
// 3. Future-proofing: any new BeginFrame or drawElement entry point that
// forgets to gate on GPU mode still routes to screenshot here.
//
// Note this does NOT eliminate SwiftShader-on-darwin text-rasterization
// artifacts (an ANGLE-SwiftShader issue on macOS text — the fix there is to
// use `--browser-gpu`, which routes to `--use-angle=metal`). It only makes
// routing consistent + observability accurate.
//
// Explicit opt-out (env or programmatic override) is honored so BeginFrame-
// on-software debugging remains possible.
const explicitForceScreenshotOptOut =
env("PRODUCER_FORCE_SCREENSHOT") === "false" || overrides?.forceScreenshot === false;
if (
merged.browserGpuMode === "software" &&
!merged.forceScreenshot &&
!explicitForceScreenshotOptOut
) {
merged.forceScreenshot = true;
}
// drawElement capture and page-side shader compositing are mutually
// incompatible capture strategies (drawElement reads paint records directly
// and bypasses the page-side prepare→composite→resolve protocol). When