Refine background screenshot compatibility

Author: esokullu

src/chrome/src/agent/agent.js

@@ -793,7 +793,13 @@ export class Agent extends LoopDetector {
     return this._retryBlankScreenshotCapture(
       await captureOnce(),
       captureOnce,
-      { probe },
+      {
+        probe,
+        // A full-page image is expected to reflect the whole scroll extent.
+        // Document length alone therefore cannot distinguish a legitimate
+        // uniform page from a blank background compositor frame.
+        includeDocumentLengthSignal: false,
+      },
     );
   }
 
@@ -5023,7 +5029,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
     }
   }
 
-  _pageSignalsContentBehindBlank(probe) {
+  _pageSignalsContentBehindBlank(probe, { includeDocumentLengthSignal = true } = {}) {
     if (!probe) return true;
     const textChars = Number(probe.documentTextChars || 0);
     const visibleTextChars = Number(probe.visibleTextChars || 0);
@@ -5037,15 +5043,26 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
       visibleTextChars > 20 ||
       imageCount > 0 ||
       domNodes > 150 ||
-      (innerHeight > 0 && scrollHeight > innerHeight + 200)
+      (
+        includeDocumentLengthSignal
+        && innerHeight > 0
+        && scrollHeight > innerHeight + 200
+      )
     );
   }
 
-  async _retryBlankScreenshotCapture(firstShot, captureOnce, { probe = null } = {}) {
+  async _retryBlankScreenshotCapture(
+    firstShot,
+    captureOnce,
+    { probe = null, includeDocumentLengthSignal = true } = {},
+  ) {
     if (!firstShot?.dataUrl || typeof captureOnce !== 'function') return firstShot;
     let shot = firstShot;
     let blankness = await this._analyzeScreenshotBlankness(shot.dataUrl);
-    if (!blankness?.blank || !this._pageSignalsContentBehindBlank(probe)) return shot;
+    if (
+      !blankness?.blank
+      || !this._pageSignalsContentBehindBlank(probe, { includeDocumentLengthSignal })
+    ) return shot;
 
     const meta = {
       detected: true,

src/firefox/ARCHITECTURE.md

@@ -7,7 +7,7 @@
 Firefox uses Manifest V2 (background page, not service worker) and has **no access to the Chrome DevTools Protocol (CDP)**. Starting with v3.6.x, the Firefox build has been brought to functional parity with Chrome for the accessibility-tree (AX) subsystem — the same tree builder, the same four AX tools (`get_accessibility_tree`, `click_ax`, `type_ax`, `set_field`), and the same ref_id registry. What Firefox still lacks:
 
 - **No trusted events** — clicks and key presses are synthetic (`el.click()`, `new KeyboardEvent()`), and some sites reject `event.isTrusted === false`. All AX-tool click/type paths use synthetic dispatch in Firefox; the CDP-backed trusted-event path in Chrome has no Firefox equivalent.
-- **No pixel-perfect / full-page screenshots** — uses `browser.tabs.captureTab()` instead of CDP `Page.captureScreenshot`; it can capture the run tab while that tab is inactive.
+- **No pixel-perfect / full-page screenshots** — uses `browser.tabs.captureTab()` instead of CDP `Page.captureScreenshot`; it can capture the run tab while that tab is inactive. Firefox has exposed `tabs.captureTab()` since Firefox 59, before WebBrain's Firefox 109 minimum, and the manifest declares the required `<all_urls>` permission.
 - **No shadow DOM piercing** — content script can read open shadow roots via `element.shadowRoot`, but cannot pierce closed roots.
 - **No offscreen document** — no HTTP fetch proxy for localhost LLM servers with Private Network Access / CORS issues. User must ensure their local LLM server sends permissive CORS headers.
 - **No duplicate-submit guard** — the per-tab submit-throttle (Chrome v3.6.5+) is still Chrome-only. Firefox's agent loop does not block rapid duplicate Create/Submit clicks. `blockedDone` and the ambiguous-click candidate payload were ported to Firefox in v4.0.1 (see "Overlay defenses" below).

src/firefox/src/agent/agent.js

@@ -4864,9 +4864,11 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
 
   /**
    * Capture a viewport screenshot for the run's tab without activating it.
-   * Firefox supports `scale: 1` on captureTab to force a CSS-pixel-aligned
-   * image (otherwise it captures at devicePixelRatio, causing the same
-   * coordinate-mismatch loop Chrome had pre-1.5.1). Returns
+   * `tabs.captureTab()` has been available since Firefox 59; WebBrain's
+   * minimum is Firefox 109 and its `<all_urls>` permission authorizes capture.
+   * Firefox supports `scale: 1` here to force a CSS-pixel-aligned image
+   * (otherwise it captures at devicePixelRatio, causing the same coordinate-
+   * mismatch loop Chrome had pre-1.5.1). Returns
    * { dataUrl, width, height } in (possibly budget-resized) pixels, or null.
    * `opts` accepted for Chrome call-site parity; capture is always CSS-locked.
    */

src/firefox/src/run-capture.js

@@ -54,6 +54,8 @@ export async function captureAndSaveRunScreenshot(api, tabId, filename) {
   if (!tab) {
     throw new Error('The run tab is no longer available.');
   }
+  // Firefox has supported arbitrary-tab capture since Firefox 59. WebBrain's
+  // declared minimum is 109 and the manifest includes the required <all_urls>.
   const dataUrl = await api.tabs.captureTab(tabId, { format: 'png' });
   filename = await filenameInConfiguredDownloadDirectory(api, filename);
   const downloadId = await api.downloads.download({

test/run.js

@@ -25572,6 +25572,65 @@ test('Chrome full-page screenshot paths reject blank background captures after r
   }
 });
 
+test('Chrome full-page blank guard ignores document length as the lone content signal', async () => {
+  const originalChrome = globalThis.chrome;
+  const originalAttach = cdpClientCh.attach;
+  const originalCapture = cdpClientCh.captureFullPageScreenshot;
+  let captureCalls = 0;
+  try {
+    globalThis.chrome = {
+      ...(originalChrome || {}),
+      tabs: {
+        ...(originalChrome?.tabs || {}),
+        get: async (tabId) => ({
+          id: tabId,
+          active: false,
+          url: 'https://example.test/uniform-long-page',
+        }),
+      },
+    };
+    cdpClientCh.attach = async () => ({ attached: true });
+    cdpClientCh.captureFullPageScreenshot = async () => {
+      captureCalls += 1;
+      return { data: 'dW5pZm9ybQ==' };
+    };
+
+    const agent = new AgentCh({});
+    agent._preparePageForCapture = async () => {};
+    agent._withIndicatorsHidden = async (_tabId, capture) => capture();
+    agent._captureViewportProbe = async () => ({
+      readyState: 'complete',
+      documentTextChars: 0,
+      visibleTextChars: 0,
+      domNodes: 20,
+      imageCount: 0,
+      scrollHeight: 5000,
+      innerHeight: 800,
+    });
+    agent._analyzeScreenshotBlankness = async () => ({
+      blank: true,
+      reason: 'near-all-white frame',
+      meanLuma: 255,
+      lumaStdDev: 0,
+      whiteRatio: 1,
+      blackRatio: 0,
+    });
+
+    const result = await agent.captureFullPageScreenshotForUser(42);
+    assert.deepEqual(result, {
+      ok: true,
+      dataUrl: 'data:image/png;base64,dW5pZm9ybQ==',
+      warning: null,
+    });
+    assert.equal(captureCalls, 1, 'a uniform long page should not retry from scroll length alone');
+  } finally {
+    cdpClientCh.attach = originalAttach;
+    cdpClientCh.captureFullPageScreenshot = originalCapture;
+    if (originalChrome === undefined) delete globalThis.chrome;
+    else globalThis.chrome = originalChrome;
+  }
+});
+
 test('user full-page screenshots apply adapter capture policy without LLM adapter injection', async () => {
   const originalChrome = globalThis.chrome;
   const originalAttach = cdpClientCh.attach;