Skip to content

Commit 5e52e27

Browse files
fix(engine): auto-fall back to screenshot mode when chrome-headless-shell drops HeadlessExperimental.beginFrame (#296)
Closes #294. ## Summary Recent `chrome-headless-shell` builds (observed on 147) no longer expose `HeadlessExperimental.beginFrame`. The domain's `enable`/`disable` methods are deprecated upstream and appear to have been dropped alongside `beginFrame` in these builds, so on Linux with chrome-headless-shell the engine aborts with \`\`\` Protocol error (HeadlessExperimental.beginFrame): 'HeadlessExperimental.beginFrame' wasn't found \`\`\` and — because the browser was launched with `--enable-begin-frame-control` — the compositor waits for beginFrames the engine can no longer deliver, so every subsequent screenshot also comes back blank. Today users have to discover `PRODUCER_FORCE_SCREENSHOT=true` themselves (openclaw did exactly that — see the issue body). ## Fix One-time probe, right after the browser launches in beginframe mode: 1. Create a disposable CDP session. 2. `await client.send("HeadlessExperimental.enable")`. 3. Send one no-op `HeadlessExperimental.beginFrame` raced against a 2s timeout. 4. If anything throws / times out — missing method, protocol error, stuck call — close the browser, strip beginframe-only chrome flags, relaunch in screenshot mode, and set \`captureMode = "screenshot"\` for the returned session. Probing `beginFrame` directly rather than `enable` alone is important because some builds keep the domain registered (so `.enable()` succeeds) while dropping the method itself — that's exactly the failure shape in #294. Cost on happy path: one extra CDP round-trip per browser acquisition (≈ a few ms, since in beginframe-control mode the command returns as soon as the compositor acks). Cost on broken path: one extra launch, which is what the env-var escape hatch already forces manually. The beginframe-only flag set is enumerated in-module and matched by the stripper, so adding/removing flags stays in one place with `buildChromeArgs`. ## Test plan - [x] `bun run --filter=@hyperframes/engine test` — all 42 tests pass - [x] `bun run --filter=@hyperframes/engine build` — typechecks - [x] `bunx oxlint` + `bunx oxfmt --check` clean - [x] Manual: standalone test on Linux x86_64 with chrome-headless-shell 146 — probe returns `supported=true`, no fallback (happy path) - [x] Manual: same test with `--force-fail` simulating openclaw's missing-method condition — fallback triggers, flags stripped, relaunch succeeds, 6.8 KB PNG captured (broken path) - [ ] Verify on openclaw / real chrome-headless-shell 147 build that the fallback triggers automatically without `PRODUCER_FORCE_SCREENSHOT` ## Notes - `probeBeginFrameSupport` catches any failure generically; we trust that a working browser answers the no-op beginFrame in well under 2s. - Warning is logged once per browser acquisition, not per frame. - Browser pool interaction: pooled browsers cache the resolved `captureMode`, so subsequent acquires in the same process reuse the post-fallback mode without re-probing.
1 parent 96376c9 commit 5e52e27

1 file changed

Lines changed: 89 additions & 3 deletions

File tree

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

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,65 @@ 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+
*
103+
* Recent chrome-headless-shell builds (observed on 147) expose the domain
104+
* well enough that HeadlessExperimental.enable succeeds but drop the
105+
* beginFrame method itself — the capture loop then dies on first frame with
106+
* `'HeadlessExperimental.beginFrame' wasn't found`. So we probe BOTH: enable
107+
* + one cheap beginFrame raced against a 2s timeout. In beginframe-control
108+
* mode the command completes as soon as the compositor acks, so a real
109+
* supported browser returns well under the timeout.
110+
*
111+
* Any failure (method missing, timeout, protocol error) is treated as
112+
* unsupported. Real errors after launch would surface in the warmup loop and
113+
* fall out through the caller's try/catch.
114+
*/
115+
async function probeBeginFrameSupport(browser: Browser): Promise<boolean> {
116+
let page;
117+
try {
118+
page = await browser.newPage();
119+
const client = await page.createCDPSession();
120+
await client.send("HeadlessExperimental.enable");
121+
const beginFrame = client.send("HeadlessExperimental.beginFrame", {
122+
frameTimeTicks: 0,
123+
interval: 33,
124+
noDisplayUpdates: true,
125+
});
126+
const timeout = new Promise<never>((_, reject) =>
127+
setTimeout(() => reject(new Error("beginFrame probe timeout")), 2000),
128+
);
129+
await Promise.race([beginFrame, timeout]);
130+
await client.detach().catch(() => {});
131+
return true;
132+
} catch {
133+
return false;
134+
} finally {
135+
await page?.close().catch(() => {});
136+
}
137+
}
138+
80139
export async function acquireBrowser(
81140
chromeArgs: string[],
82141
config?: Partial<
@@ -112,14 +171,41 @@ export async function acquireBrowser(
112171
}
113172

114173
const ppt = await getPuppeteer();
115-
const browser = await ppt.launch({
174+
const browserTimeout = config?.browserTimeout ?? DEFAULT_CONFIG.browserTimeout;
175+
const protocolTimeout = config?.protocolTimeout ?? DEFAULT_CONFIG.protocolTimeout;
176+
let browser = await ppt.launch({
116177
headless: true,
117178
args: chromeArgs,
118179
defaultViewport: null,
119180
executablePath,
120-
timeout: config?.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
121-
protocolTimeout: config?.protocolTimeout ?? DEFAULT_CONFIG.protocolTimeout,
181+
timeout: browserTimeout,
182+
protocolTimeout,
122183
});
184+
185+
// Probe HeadlessExperimental.beginFrame — recent chrome-headless-shell
186+
// builds (observed on 147) dropped the method while keeping the flags
187+
// valid, so `--enable-begin-frame-control` leaves the compositor waiting
188+
// for beginFrames the engine can no longer send. Auto-fall back to
189+
// screenshot mode with the appropriate flags.
190+
if (captureMode === "beginframe") {
191+
const supported = await probeBeginFrameSupport(browser).catch(() => true);
192+
if (!supported) {
193+
await browser.close().catch(() => {});
194+
console.warn(
195+
"[BrowserManager] HeadlessExperimental.beginFrame unavailable in this Chromium build; falling back to screenshot mode.",
196+
);
197+
captureMode = "screenshot";
198+
browser = await ppt.launch({
199+
headless: true,
200+
args: stripBeginFrameFlags(chromeArgs),
201+
defaultViewport: null,
202+
executablePath,
203+
timeout: browserTimeout,
204+
protocolTimeout,
205+
});
206+
}
207+
}
208+
123209
if (enablePool) {
124210
pooledBrowser = browser;
125211
pooledBrowserRefCount = 1;

0 commit comments

Comments
 (0)