Repository navigation
web screenshots: expose viewport-size control; document --fullscreen=full-page; accept --full alias #864
Description
Summary
On --platform web, agent-device screenshot captures only the current viewport, with no option for a full-page capture. Pages taller than the viewport are silently cropped below the fold. The underlying agent-browser backend is Playwright-based (which supports fullPage), so this is about surfacing that capability through the agent-device command, not new browser plumbing.
Environment
- agent-device: 0.17.8
- agent-browser (managed backend): 0.27.1
- Node: 24.x (web backend requirement)
- Reproduced on macOS (local) and Ubuntu headless CI (GitHub Actions) — identical behavior.
Current behavior
agent-device screenshot exposes no full-page flag:
$ agent-device help screenshot
agent-device screenshot [path] [--out <path>] [--overlay-refs] [--fullscreen] [--max-size <px>] [--no-stabilize]
(--fullscreen is full desktop for macOS app sessions, not full page for web.)
A page taller than the viewport is cropped to the viewport. Minimal repro against a 1500px-tall page:
$ agent-device open http://localhost:9080/tall.html --platform web --session vp
$ agent-device screenshot ./shot.png --platform web --session vp
$ file shot.png
shot.png: PNG image data, 1280 x 577 # viewport only; the page is 1500px tall
The capture height tracks agent-browser's default headless viewport (observed ~1280x577, and ~1280x633 on a fresh daemon) rather than the document height. There is also no documented config-file key or env var to set the web viewport size (only AGENT_BROWSER_* flags unrelated to viewport; the viewport <w> <h> command is not exposed through agent-device --platform web's verb set in help web).
Proposed solution
Add a full-page option to the web screenshot path, e.g.:
agent-device screenshot ./shot.png --platform web --full-page
mapping to the agent-browser/Playwright fullPage: true capture. (Optionally, also expose a viewport-size knob — config key or AGENT_BROWSER_VIEWPORT env — so single-screen captures can be sized deterministically.)
Why / use case
We drive agent-device --platform web from CI to verify and screenshot a web app (Expensify NewDot) for PR evidence. snapshot correctly returns the full tree, so verification is unaffected — but the screenshot evidence posted back to reviewers is cropped to the fold, which misrepresents single-page screens and can't show below-the-fold UI in one image. A --full-page capture would make the visual evidence faithful (a true 1:1 app→screenshot) without scroll-and-stitch workarounds.
Notes
Verification correctness is not affected (we rely on snapshot/is/get, which read the full DOM/AX tree); this is specifically about full-page screenshot evidence.
Activity
kacper-mikolajczak commentedon Jun 24, 2026
Correction / update: full-page capture is already available on
--platform web- I missed it. agent-device's--fullscreenflag maps to agent-browser's full-page capture on web:So this is not a missing capability. The remaining, smaller asks are about discoverability/UX:
--fullscreenperforms a full-page capture on--platform web. Todayagent-device help screenshotdescribes--fullscreenas "capture the full screen instead of the app window" (a macOS-app framing), which doesn't read as "full page" for web - easy to miss.--full/-fas an alias on the agent-device web surface for parity with agent-browser (which uses--full). Currentlyagent-device screenshot --platform web --fullerrors withUnknown flag: --full, so users who know agent-browser's flag hit a dead end.Happy to send a small docs/alias PR if that'd help. Apologies for the original framing - the capability is there, just under a differently-named flag.
[-]feat: expose full-page screenshot for `--platform web` (currently viewport-only)[/-][+]docs/UX: full-page web screenshot via `--fullscreen` is undocumented; accept `--full` alias[/+]kacper-mikolajczak commentedon Jun 24, 2026
Follow-up — the bigger gap for fixed-layout SPAs is viewport-size control, not full-page.
Testing against a
100vhSPA (Expensify NewDot),--fullscreenand a plain viewport shot are identical because the document height equals the viewport:--fullscreenworks perfectly on screens that actually scroll (a 1500px test page captures 1280x1500). But for full-viewport app layouts, the app clips its own content to the viewport, so full-page == viewport and the only way to see more is a taller viewport.There appears to be no way to set the web viewport size today:
viewport/defaultViewport/width+heightkey in~/.agent-browser/config.jsonchanges it (tested on fresh daemons — all stay 1280x577).AGENT_BROWSER_*viewport env var.viewportverb for--platform web(agent-browser'sviewport <w> <h>isn't surfaced).Ask: expose a web viewport size — e.g. an
AGENT_BROWSER_VIEWPORT=1280x900env / config key honored at daemon launch, or surfaceviewport <w> <h>throughagent-device --platform web. That (not full-page) is what makes single-screen SPA captures faithful. The default headless height (~577) is also quite short for desktop-web evidence.[-]docs/UX: full-page web screenshot via `--fullscreen` is undocumented; accept `--full` alias[/-][+]web screenshots: expose viewport-size control; document `--fullscreen`=full-page; accept `--full` alias[/+]