fix: add web viewport control and screenshot aliases

[thymikee]

Summary

Keeps the existing web --fullscreen screenshot behavior and makes it discoverable by documenting that --platform web uses it for full-page capture.
Adds --full and -f as screenshot aliases for parity with agent-browser, and adds a new web viewport <width> <height> command for fixed-layout or 100vh apps where changing the viewport is the real missing control.
Threads the new viewport command through the public command surface, daemon routing, web interactor/provider path, docs/help, and regression coverage. Closes #864.
Touched files: 34. Scope expanded from the original screenshot command family to one additional web-only management command.

Validation

GitHub CI is green on 7bdccdc23: Lint & Format, Unit Tests, Typecheck, Integration Tests, Smoke Tests, Web Platform Smoke, Coverage, Fallow Code Quality, Bundle Size, CodeQL, and related guards passed.
node --test test/integration/smoke-web-platform.test.ts passed locally with AGENT_DEVICE_WEB_E2E=1.
Manual built-CLI verification passed against /private/tmp/issue-864-fixed-layout.html using state dir /private/tmp/agent-device-issue-864: screenshot --full produced /private/tmp/issue-864-before.png at 1280x577, viewport 1280 900 succeeded, and screenshot -f then produced /private/tmp/issue-864-after.png at 1280x900 with below-fold content visible only after the viewport resize.
node scripts/sync-mcp-metadata.mjs --check, git diff --check, node --experimental-strip-types src/bin.ts help screenshot, and node --experimental-strip-types src/bin.ts help viewport passed locally.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-24 17:35 UTC

[thymikee]

Marking this draft for now: issue #864 was updated after this work started. The current ask is no longer missing full-page capture; --fullscreen already does full-page on web. Please rework this toward documenting that behavior, accepting --full/-f aliases where appropriate, and addressing viewport-size control for fixed-layout SPAs if feasible. Do not remove the existing --fullscreen web full-page behavior.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.3 MB	1.3 MB	+2.2 kB
JS gzip	430.3 kB	431.0 kB	+654 B
npm tarball	566.5 kB	567.3 kB	+731 B
npm unpacked	1.9 MB	1.9 MB	+2.6 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.7 ms	29.7 ms	+1.0 ms
CLI --help	50.8 ms	49.8 ms	-1.1 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/2948.js	+1.1 kB	+347 B
dist/src/9722.js	+775 B	+234 B
dist/src/cli-help.js	+258 B	+38 B
dist/src/9919.js	+40 B	+12 B

[thymikee]

Post-merge second-pass note: no blocker found, but there are two small follow-ups now on main:

• viewport is web-only by contract, but src/core/capabilities.ts still advertises it for native platforms, so native requests pass capability/admission and fail later with a generic backend unsupported error. Restrict the capability to web.
• Web help examples include agent-device viewport 1280 900 --platform web, but the “Supported in agent-device web sessions” list omits viewport. Add it there for internal help consistency.

These are P3 cleanup items after merge, not a reason to revert #865.