Skip to content

Commit 46cf81a

Browse files
committed
fix(engine): auto-fall back to screenshot mode on Chromium >= 132
Chromium 132+ removed the HeadlessExperimental domain. On Linux with chrome-headless-shell we default to beginframe capture, which silently produces blank frames on newer Chromium because `--enable-begin-frame-control` leaves the compositor waiting for beginFrames the code can no longer send. Users had to discover PRODUCER_FORCE_SCREENSHOT=true themselves. Probe HeadlessExperimental.enable() on a disposable page right after launch. If the domain isn't there, close the browser, relaunch with the beginframe- only chrome flags stripped, and mark the session as screenshot mode. Users on supported Chromium versions are unaffected — the probe adds one CDP round-trip to browser acquisition and nothing else. Closes #294.
1 parent 96376c9 commit 46cf81a

1 file changed

Lines changed: 73 additions & 3 deletions

File tree

‎packages/engine/src/services/browserManager.ts‎

Lines changed: 73 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,50 @@ let pooledCaptureMode: CaptureMode = "screenshot";
7777
// Preserve the producer-era export so re-export shims keep the same public API.
7878
export const ENABLE_BROWSER_POOL = DEFAULT_CONFIG.enableBrowserPool;
7979

80+
// Flags only meaningful when Chrome's compositor is driven by
81+
// HeadlessExperimental.beginFrame. If we fall back to screenshot mode they
82+
// must be stripped — `--enable-begin-frame-control` in particular makes the
83+
// compositor wait for frames we'll never send, producing blank screenshots.
84+
const BEGINFRAME_ONLY_FLAGS = new Set([
85+
"--deterministic-mode",
86+
"--enable-begin-frame-control",
87+
"--disable-new-content-rendering-timeout",
88+
"--run-all-compositor-stages-before-draw",
89+
"--disable-threaded-animation",
90+
"--disable-threaded-scrolling",
91+
"--disable-checker-imaging",
92+
"--disable-image-animation-resync",
93+
"--enable-surface-synchronization",
94+
]);
95+
96+
function stripBeginFrameFlags(args: string[]): string[] {
97+
return args.filter((a) => !BEGINFRAME_ONLY_FLAGS.has(a));
98+
}
99+
100+
/**
101+
* Probe whether the browser still speaks HeadlessExperimental.beginFrame.
102+
* Chromium 132+ removed the domain; calling enable() on a fresh page throws
103+
* "'HeadlessExperimental.enable' wasn't found". Returns true if supported.
104+
*/
105+
async function probeBeginFrameSupport(browser: Browser): Promise<boolean> {
106+
let page;
107+
try {
108+
page = await browser.newPage();
109+
const client = await page.createCDPSession();
110+
await client.send("HeadlessExperimental.enable");
111+
await client.detach().catch(() => {});
112+
return true;
113+
} catch (err) {
114+
const msg = err instanceof Error ? err.message : String(err);
115+
if (/HeadlessExperimental\b.*(wasn't found|not found|not enabled)/i.test(msg)) {
116+
return false;
117+
}
118+
throw err;
119+
} finally {
120+
await page?.close().catch(() => {});
121+
}
122+
}
123+
80124
export async function acquireBrowser(
81125
chromeArgs: string[],
82126
config?: Partial<
@@ -112,14 +156,40 @@ export async function acquireBrowser(
112156
}
113157

114158
const ppt = await getPuppeteer();
115-
const browser = await ppt.launch({
159+
const browserTimeout = config?.browserTimeout ?? DEFAULT_CONFIG.browserTimeout;
160+
const protocolTimeout = config?.protocolTimeout ?? DEFAULT_CONFIG.protocolTimeout;
161+
let browser = await ppt.launch({
116162
headless: true,
117163
args: chromeArgs,
118164
defaultViewport: null,
119165
executablePath,
120-
timeout: config?.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
121-
protocolTimeout: config?.protocolTimeout ?? DEFAULT_CONFIG.protocolTimeout,
166+
timeout: browserTimeout,
167+
protocolTimeout,
122168
});
169+
170+
// Probe HeadlessExperimental availability — Chromium 132+ removed it and
171+
// we'd otherwise render blank frames because `--enable-begin-frame-control`
172+
// leaves the compositor waiting for beginFrames we can't send. Auto-fall
173+
// back to screenshot mode with the appropriate flags.
174+
if (captureMode === "beginframe") {
175+
const supported = await probeBeginFrameSupport(browser).catch(() => true);
176+
if (!supported) {
177+
await browser.close().catch(() => {});
178+
console.warn(
179+
"[BrowserManager] HeadlessExperimental.beginFrame unavailable in this Chromium build; falling back to screenshot mode.",
180+
);
181+
captureMode = "screenshot";
182+
browser = await ppt.launch({
183+
headless: true,
184+
args: stripBeginFrameFlags(chromeArgs),
185+
defaultViewport: null,
186+
executablePath,
187+
timeout: browserTimeout,
188+
protocolTimeout,
189+
});
190+
}
191+
}
192+
123193
if (enablePool) {
124194
pooledBrowser = browser;
125195
pooledBrowserRefCount = 1;

0 commit comments

Comments
 (0)