Identified as the top "must have" gap from a broader QA-capability
review -- cheap and foundational, unlike accessibility/performance
auditing which are more specialized, separate-tool territory.

Confirmed directly by fetching the real tools/list from the live
proxy (16 tools, none viewport-related) and reading the engine's
actual installed source: there's no MCP-mode tool or env var for
window size at all. The capability exists on BrowserProfile
(window_size -> --window-size=W,H) but is only reachable by writing
into the engine's own internal $BROWSER_USE_CONFIG_DIR/config.json,
an undocumented DB-style file read fresh on every session init, whose
entries accept arbitrary extra fields.

BROWSERHUB_VIEWPORT_WIDTH/HEIGHT (both required together) in .env now
patch just the window_size field on that config's default profile
entry before every proxy launch, bootstrapping a fresh file if none
exists. Every other field is left exactly as-is. A config.json that
doesn't look like the engine's expected shape is left alone entirely,
and every failure path warns and returns rather than touching the
file, since this is an internal, not officially-stable mechanism --
a future engine version changing this format should degrade to
"viewport not applied," never a crash.

Verified end-to-end for real: set both vars, restarted the real
proxy, confirmed via a genuine navigate+get_state that the viewport
actually changed. Found a real nuance: configuring 1366x768 produced
1351x768 reported -- height exact, width ~15px narrower, since
--window-size sets the outer window including scrollbar/chrome
overhead, not the exact content viewport. Documented, not a bug.

Added a print-viewport-config testable subcommand and 5 isolated
regression tests (bootstrap, preserves unrelated fields, no-op when
unset, warns when asymmetric, unrecognized shape left alone). Full
e2e-test.sh (32 checks) and smoke-test.sh pass; plugin validates.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K3WdNS3ATW2ssvHrK9gJta