v1.18.0.0 fix(browse): screenshot defaults to viewport, add --full-page

[gregario]

Summary

Fixes #1214 — browse screenshot defaulted to fullPage: true, so any page taller than ~2000px scroll height produced a PNG that exceeded the Anthropic vision API's per-side limit. Once a poison image landed in conversation history, every subsequent turn re-failed on the same envelope. Whole session bricked, not just one tool call.

Before

$ browse goto https://example.com/some-long-doc
$ browse screenshot /tmp/shot.png
Screenshot saved: /tmp/shot.png        # 1280×3700 PNG
# Claude tries to Read /tmp/shot.png:
# → \"image exceeds 2000 pixels on the longest edge\"
# → every following turn now fails on the same image

After

$ browse screenshot /tmp/shot.png
Screenshot saved: /tmp/shot.png        # 1280×720 viewport, safe

$ browse screenshot --full-page /tmp/long.png
[browse] warning: full-page screenshot is 1280x3695px — exceeds ~2000px Anthropic vision API limit. Consider --viewport (default), --clip x,y,w,h, or --selector for a smaller capture.
Screenshot saved (full-page): /tmp/long.png

Changes

1. Flip the default. Bare screenshot captures the visible viewport. Matches Playwright's own page.screenshot() default of fullPage: false.
2. Add --full-page opt-in. When used, the result is checked against an ~1800px ceiling (vision-API limit with headroom) and emits a one-line [browse] warning to stderr — agents see the boundary instead of silently shipping poison.
3. Keep --viewport as a back-compat no-op alias. Existing scripts that passed --viewport keep working; the output message just no longer carries (viewport) since viewport IS the default — only --full-page gets a (full-page) suffix.
4. PNG dimensions are read from the IHDR chunk (zero deps, ~10 lines).

Annotated/heatmap snapshot modes still default to fullPage — those are debug UI for humans, not images fed to agents via Read.

This goes with the issue author's vote: option 1 (post-capture warn) plus option 2 (flip the default). "Search before recommending" rubric: Playwright's API was already shipping the right default — gstack just wasn't matching it.

Test plan

• bun test browse/test/commands.test.ts — 228 pass (8 cases changed/added)
  • Regression for browse: full-page screenshots silently exceed Anthropic vision API 2000px limit, bricking sessions #1214: tall.html (~3000px) with bare screenshot produces PNG ≤ 800px tall (viewport)
  • --full-page on the same page produces > 2000px
  • --full-page on tall page emits the oversize warning (captured via console.warn patch)
  • --full-page + --clip and --full-page + selector reject mutually-exclusive flag combos
  • --viewport + --clip is now a no-op + clip (back-compat: was an error before; fine because clip is what runs)
  • Existing 220 tests unchanged
• bun test (full free suite) — green

Migration note

If any caller depended on the literal output \"Screenshot saved (viewport)\", that string changed to \"Screenshot saved\" (since viewport is now the default and not a special case). Only one test in this repo grepped for that exact string; no production callers found in grep -rn.

Files

• browse/src/meta-commands.ts — flag parsing + IHDR reader + warnIfOversize helper
• browse/src/commands.ts — usage docstring
• browse/test/commands.test.ts — 5 new tests, 1 updated, 1 inverted (back-compat)
• browse/test/fixtures/tall.html — new ~3000px fixture
• VERSION, CHANGELOG.md — release v1.15.2.0

🤖 Generated with Claude Code