web screenshots: expose viewport-size control; document `--fullscreen`=full-page; accept `--full` alias

[kacper-mikolajczak]

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.

[kacper-mikolajczak]

Correction / update: full-page capture is already available on --platform web - I missed it. agent-device's --fullscreen flag maps to agent-browser's full-page capture on web:

$ agent-device screenshot ./full.png --platform web --fullscreen
$ file full.png
full.png: PNG image data, 1280 x 1500     # full page (1500px-tall test page), not the 1280x577 viewport

So this is not a missing capability. The remaining, smaller asks are about discoverability/UX:

1. Document that --fullscreen performs a full-page capture on --platform web. Today agent-device help screenshot describes --fullscreen as "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.
2. Accept --full / -f as an alias on the agent-device web surface for parity with agent-browser (which uses --full). Currently agent-device screenshot --platform web --full errors with Unknown 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.

[kacper-mikolajczak]

Follow-up — the bigger gap for fixed-layout SPAs is viewport-size control, not full-page.

Testing against a 100vh SPA (Expensify NewDot), --fullscreen and a plain viewport shot are identical because the document height equals the viewport:

$ agent-device open https://new.expensify.com --platform web
$ agent-device screenshot ./vp.png   --platform web              # 1280 x 577
$ agent-device screenshot ./full.png --platform web --fullscreen # 1280 x 577 (same)
# document.scrollHeight === window.innerHeight  -> the page never extends past the viewport

--fullscreen works 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:

• No viewport/defaultViewport/width+height key in ~/.agent-browser/config.json changes it (tested on fresh daemons — all stay 1280x577).
• No AGENT_BROWSER_* viewport env var.
• agent-device exposes no viewport verb for --platform web (agent-browser's viewport <w> <h> isn't surfaced).

Ask: expose a web viewport size — e.g. an AGENT_BROWSER_VIEWPORT=1280x900 env / config key honored at daemon launch, or surface viewport <w> <h> through agent-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.