Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

fix(screenshot): capture the tab the run is working in, not whichever one is in front

Shahriar00096b337b2f
diff --git a/docs/guide/features/screenshots.md b/docs/guide/features/screenshots.md
index 6b057ca..0f329e1 100644
--- a/docs/guide/features/screenshots.md
+++ b/docs/guide/features/screenshots.md
@@ -20,6 +20,17 @@ by default.
---
+## A capture follows the tab, not your eyes
+
+An agent working in one tab keeps photographing that tab after you move to another. While the tab
+is in front it is captured the ordinary way; once it is behind, Chrome renders it through its
+debugger instead, so the “started debugging this browser” bar appears for the moment the capture
+takes. Firefox captures a background tab directly and shows nothing. If DevTools is open on that
+tab the debugger cannot attach, and the capture fails with `DEBUGGER_UNAVAILABLE` until you close
+it.
+
+---
+
## Captures do not touch your disk unless you ask
This is the part worth knowing. The image is handed straight back to whoever called for it, so
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
index 6714518..404a203 100644
--- a/docs/reference/tools.md
+++ b/docs/reference/tools.md
@@ -222,6 +222,10 @@ to scroll the page in viewport-sized steps and wait out the browser's two-captur
between each, so it costs roughly a second per screenful; ask for it when you need what is below
the fold rather than by default.
+The capture is of the tab the call resolves to, whether or not it is the one in front. A tab that
+is behind another is rendered through Chrome's debugger (`tabs.captureTab` on Firefox), so it can
+fail with `DEBUGGER_UNAVAILABLE` while DevTools is open on it.
+
| Parameter | Type | Default | Purpose |
| --- | --- | --- | --- |
| `target` | [target](#element-targets) | — | Capture only this element's box. When set, `fullPage` is ignored |
diff --git a/src/lib/bridge/screenshot.ts b/src/lib/bridge/screenshot.ts
index 8537db5..7722eb7 100644
--- a/src/lib/bridge/screenshot.ts
+++ b/src/lib/bridge/screenshot.ts
@@ -2,6 +2,7 @@ import { browser } from 'wxt/browser';
import { invokeInFrame } from '@/lib/actions/client';
import { ActionError } from '@/lib/actions/core';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
+import { send, withDebugger, type DebuggerSession } from './cdp';
import { TOP_FRAME } from './frame-focus';
import { publishScreenshot } from './screenshot-preview';
@@ -22,24 +23,104 @@ const MAX_TILES = 48;
const MAX_CANVAS_SIDE = 16384;
const MAX_CANVAS_AREA = MAX_CANVAS_SIDE * MAX_CANVAS_SIDE;
+interface Frame {
+ dataUrl: string;
+ bitmap: ImageBitmap;
+}
+
+type Snap = (format: 'png' | 'jpeg', quality: number | undefined) => Promise<Frame>;
+
+type TabCapture = { captureTab: (tabId: number, options: { format: string; quality?: number }) => Promise<string> };
+
+const LEFT_THE_FRONT = 'TAB_LEFT_THE_FRONT';
+const DEBUGGER_CAPTURE_TIMEOUT_MS = 10_000;
+
+const FIREFOX_HINT = 'Capturing a background tab through the debugger is Chrome-only — Firefox captures it directly.';
+
export async function screenshotTab(
tab: { id: number; windowId?: number },
input?: unknown,
runId?: string,
): Promise<ActionResult> {
- const planned = await invokeInFrame(tab.id, TOP_FRAME, 'page.screenshot', input);
+ if (import.meta.env.FIREFOX) return shoot(tab.id, input, runId, snapFirefoxTab(tab.id));
+
+ if (await inFront(tab.id)) {
+ const shot = await shoot(tab.id, input, runId, snapWhileInFront(tab));
+ if (shot.ok || shot.error.code !== LEFT_THE_FRONT) return shot;
+ }
+ return withDebugger(tab.id, FIREFOX_HINT, (session) => shoot(tab.id, input, runId, snapThroughDebugger(session)));
+}
+
+async function inFront(tabId: number): Promise<boolean> {
+ const tab = await browser.tabs.get(tabId).catch(() => null);
+ return tab?.active === true;
+}
+
+function snapWhileInFront(tab: { id: number; windowId?: number }): Snap {
+ return async (format, quality) => {
+ const frame = await captureViewport(tab.windowId, format, quality);
+ if (await inFront(tab.id)) return frame;
+ frame.bitmap.close();
+ throw new ActionError('The tab went behind another one mid-capture', LEFT_THE_FRONT);
+ };
+}
+
+function snapThroughDebugger(session: DebuggerSession): Snap {
+ return async (format, quality) => {
+ const captured = send<{ data: string }>(session, 'Page.captureScreenshot', {
+ format,
+ ...(format === 'jpeg' ? { quality: quality ?? DEFAULT_JPEG_QUALITY } : {}),
+ });
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const stalled = new Promise<never>((_, reject) => {
+ timer = setTimeout(
+ () =>
+ reject(
+ new ActionError(
+ 'Chrome did not render the background tab in time — bring the tab to the front and retry',
+ 'CAPTURE_FAILED',
+ ),
+ ),
+ DEBUGGER_CAPTURE_TIMEOUT_MS,
+ );
+ });
+ const { data } = await Promise.race([captured, stalled]).finally(() => clearTimeout(timer));
+ return framed(`data:image/${format};base64,${data}`);
+ };
+}
+
+function snapFirefoxTab(tabId: number): Snap {
+ return async (format, quality) => {
+ const grade = format === 'jpeg' ? (quality ?? DEFAULT_JPEG_QUALITY) : undefined;
+ try {
+ return await framed(await (browser.tabs as unknown as TabCapture).captureTab(tabId, { format, quality: grade }));
+ } catch (error) {
+ throw new ActionError(cannotCapture(error), 'CAPTURE_UNSUPPORTED');
+ }
+ };
+}
+
+async function framed(dataUrl: string): Promise<Frame> {
+ return { dataUrl, bitmap: await createImageBitmap(await (await fetch(dataUrl)).blob()) };
+}
+
+const cannotCapture = (error: unknown) =>
+ `Cannot capture this tab (${error instanceof Error ? error.message : String(error)}) — it may be a chrome:// page, the Web Store, or a PDF, which browsers refuse to screenshot`;
+
+async function shoot(tabId: number, input: unknown, runId: string | undefined, snap: Snap): Promise<ActionResult> {
+ const planned = await invokeInFrame(tabId, TOP_FRAME, 'page.screenshot', input);
if (!planned.ok) return planned;
const plan = planned.data as CapturePlan;
try {
- const shot = await capture(tab, plan);
+ const shot = await capture(tabId, plan, snap);
void publishCapture(shot, runId);
return success(shot);
} catch (error) {
if (error instanceof ActionError) return failure(error.code, error.message);
return failure('CAPTURE_FAILED', error instanceof Error ? error.message : String(error));
} finally {
- void invokeInFrame(tab.id, TOP_FRAME, 'page.scrollTo', {
+ void invokeInFrame(tabId, TOP_FRAME, 'page.scrollTo', {
position: { x: plan.scroll.x, y: plan.scroll.y },
behavior: 'instant',
});
@@ -60,7 +141,7 @@ async function publishCapture(shot: Shot, runId?: string): Promise<void> {
} catch {}
}
-async function capture(tab: { id: number; windowId?: number }, plan: CapturePlan): Promise<Shot> {
+async function capture(tabId: number, plan: CapturePlan, snap: Snap): Promise<Shot> {
const { viewport, format, quality, maxLongSide } = plan;
const region = { ...plan.region };
@@ -89,7 +170,7 @@ async function capture(tab: { id: number; windowId?: number }, plan: CapturePlan
for (const y of ys) {
for (const x of xs) {
- const scrolled = await invokeInFrame(tab.id, TOP_FRAME, 'page.scrollTo', {
+ const scrolled = await invokeInFrame(tabId, TOP_FRAME, 'page.scrollTo', {
position: { x, y },
behavior: 'instant',
});
@@ -99,7 +180,7 @@ async function capture(tab: { id: number; windowId?: number }, plan: CapturePlan
const sinceLast = Date.now() - lastCaptureAt;
if (lastCaptureAt && sinceLast < CAPTURE_INTERVAL_MS) await delay(CAPTURE_INTERVAL_MS - sinceLast);
- const shot = await captureViewport(tab.windowId, format, quality);
+ const shot = await snap(format, quality);
lastCaptureAt = Date.now();
const bitmap = shot.bitmap;
@@ -187,7 +268,7 @@ export async function captureViewport(
windowId: number | undefined,
format: 'png' | 'jpeg',
quality: number | undefined,
-): Promise<{ dataUrl: string; bitmap: ImageBitmap }> {
+): Promise<Frame> {
const grade = format === 'jpeg' ? (quality ?? DEFAULT_JPEG_QUALITY) : undefined;
for (let attempt = 0; ; attempt++) {
try {
@@ -195,17 +276,14 @@ export async function captureViewport(
windowId == null
? await browser.tabs.captureVisibleTab({ format, quality: grade })
: await browser.tabs.captureVisibleTab(windowId, { format, quality: grade });
- return { dataUrl, bitmap: await createImageBitmap(await (await fetch(dataUrl)).blob()) };
+ return await framed(dataUrl);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
if (attempt < 2 && /MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND/i.test(message)) {
await delay(CAPTURE_INTERVAL_MS);
continue;
}
- throw new ActionError(
- `Cannot capture this tab (${message}) — it may be a chrome:// page, the Web Store, or a PDF, which browsers refuse to screenshot`,
- 'CAPTURE_UNSUPPORTED',
- );
+ throw new ActionError(cannotCapture(error), 'CAPTURE_UNSUPPORTED');
}
}
}