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.

perf(screenshot): capture the viewport at the page's own pixel size unless the picture is being kept, which halves what each look costs

Shahriar1463af2eeb0f
diff --git a/docs/guide/features/screenshots.md b/docs/guide/features/screenshots.md
index 0f329e1..00dd912 100644
--- a/docs/guide/features/screenshots.md
+++ b/docs/guide/features/screenshots.md
@@ -45,9 +45,12 @@ Change where with `screenshotDir` in [config](../configuration.md).
## Format and size
-Defaults are JPEG at quality 80, downscaled so the longest side is at most 1600 px — far smaller
-and quicker than PNG, which matters because these go to a model. PNG is available when you need
-lossless or transparency.
+Defaults are JPEG at quality 80 — far smaller and quicker than PNG, which matters because these go
+to a model. A viewport capture the agent takes to look at the page comes back at the page's own
+CSS-pixel size, which on a high-density display is half the pixels and well under half the cost,
+and makes a position in the picture a usable click point. Full-page, element and saved captures
+are downscaled so the longest side is at most 1600 px. `maxLongSide` overrides either. PNG is
+available when you need lossless or transparency.
---
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
index 2af0ce0..9a44a29 100644
--- a/docs/reference/tools.md
+++ b/docs/reference/tools.md
@@ -234,7 +234,7 @@ fail with `DEBUGGER_UNAVAILABLE` while DevTools is open on it.
| `fullPage` | boolean | `false` | With no target: `false` captures the current viewport, `true` the entire scroll view by tiling |
| `format` | `"png"` \| `"jpeg"` | `"jpeg"` | JPEG is far smaller and quicker to encode; PNG is lossless and keeps transparency |
| `quality` | integer | `80` | JPEG quality, 1–100. Only valid when format is `"jpeg"` |
-| `maxLongSide` | integer | `1600` | Downscale so the longest side is at most this many pixels |
+| `maxLongSide` | integer | — | Downscale so the longest side is at most this many pixels. Left out, a viewport capture comes back at the page's CSS-pixel size, so a position in the image is a usable `point`; a full-page, element or saved capture is capped at `1600` |
| `save` | boolean | `false` | Write the image to disk (done by the daemon, which adds `savedTo`). Set it only when the user wants a file to keep |
| `filename` | string | — | Base filename when saving; defaults to `screenshot-<timestamp>.<ext>`. Sanitized before use |
diff --git a/src/lib/actions/page/screenshot.test.ts b/src/lib/actions/page/screenshot.test.ts
new file mode 100644
index 0000000..a13af0a
--- /dev/null
+++ b/src/lib/actions/page/screenshot.test.ts
@@ -0,0 +1,21 @@
+import { beforeEach, describe, expect, test } from 'vitest';
+import { screenshot } from './screenshot';
+
+const longSide = (input: Record<string, unknown> = {}) =>
+ (screenshot.execute(screenshot.input.parse(input)) as { maxLongSide: number }).maxLongSide;
+
+beforeEach(() => {
+ Object.assign(window, { innerWidth: 1084, innerHeight: 738, devicePixelRatio: 2 });
+});
+
+describe('how large a capture comes back when nobody says', () => {
+ test('a viewport capture to look at is one image pixel per page pixel; a kept, full-page or oversized one is capped at 1600', () => {
+ expect([longSide(), longSide({ save: true }), longSide({ fullPage: true })]).toEqual([1084, 1600, 1600]);
+ Object.assign(window, { innerWidth: 2560, innerHeight: 1300 });
+ expect(longSide()).toBe(1600);
+ });
+
+ test('an explicit size wins', () => {
+ expect([longSide({ maxLongSide: 800 }), longSide({ maxLongSide: 3000, save: true })]).toEqual([800, 3000]);
+ });
+});
diff --git a/src/lib/actions/page/screenshot.ts b/src/lib/actions/page/screenshot.ts
index 756bea7..1dbedc0 100644
--- a/src/lib/actions/page/screenshot.ts
+++ b/src/lib/actions/page/screenshot.ts
@@ -2,6 +2,8 @@ import { z } from 'zod';
import { ActionError, defineAction } from '../core';
import { documentBounds, resolveTarget, targetSchema } from './dom';
+const DEFAULT_LONG_SIDE = 1600;
+
export const screenshot = defineAction({
name: 'page.screenshot',
description:
@@ -33,9 +35,9 @@ export const screenshot = defineAction({
.number()
.int()
.positive()
- .default(1600)
+ .optional()
.describe(
- 'Downscale the result so its longest side is at most this many pixels. The default is sized for reading a page, not for pixel-level inspection — raise it when fine detail matters.',
+ 'Downscale the result so its longest side is at most this many pixels. Left out, a viewport capture you take to look at comes back at the page’s own CSS-pixel size — one image pixel per page pixel, so a position in the picture is a usable "point" — and anything else, a saved capture included, is capped at 1600. That is sized for reading a page, not for pixel-level inspection: raise it when fine detail matters.',
),
save: z
.boolean()
@@ -48,7 +50,7 @@ export const screenshot = defineAction({
.optional()
.describe('Base filename when saving; defaults to screenshot-<timestamp>.<ext>. Sanitized before use.'),
}),
- execute({ target, fullPage, format, quality, maxLongSide }) {
+ execute({ target, fullPage, format, quality, maxLongSide, save }) {
if (quality !== undefined && format !== 'jpeg') {
throw new ActionError('"quality" only applies when format is "jpeg"', 'INVALID_INPUT');
}
@@ -77,6 +79,9 @@ export const screenshot = defineAction({
const scroll = { x: Math.round(window.scrollX), y: Math.round(window.scrollY) };
- return { mode, dpr, viewport, page, region, scroll, format, quality, maxLongSide };
+ const longSide =
+ maxLongSide ?? (mode === 'viewport' && !save ? Math.min(DEFAULT_LONG_SIDE, Math.max(viewport.w, viewport.h)) : DEFAULT_LONG_SIDE);
+
+ return { mode, dpr, viewport, page, region, scroll, format, quality, maxLongSide: longSide };
},
});