feat(screenshot)!: default to a 1024px JPEG for agent-facing captures

[yhc509]

Closes #127

Why

A screenshot is the heaviest single response an agent can request. A 1920×1080 PNG bills at roughly 2,040 image tokens; the same frame capped at 1024px is about 576. --format jpg, --quality and --max-width already existed, but they were opt-in, so the default caller paid full price for fidelity no vision model can use.

What changed

screenshot now defaults to JPEG quality 75, capped at 1024px wide. Three rules keep the new default from surprising anyone:

situation	result
--format png|jpg|jpeg given	wins outright
no --format, --path ends in .png	PNG — writing JPEG bytes into a file the caller named .png is worse than the tokens saved
--width and/or --height given	cap suppressed entirely (this gate predates the change)
--max-width 0	cap off, size still auto-detected

--max-width 0 was previously rejected (minimum 1); it is now the documented opt-out and travels as a -1 wire sentinel, because maxWidth == 0 already means "unspecified" and the wire model cannot carry a nullable int.

QA coordinates are unaffected: qa tap / ui-dump / world-dump scale from LastCapturedWidth/Height, so a downscaled capture's coordinates still land.

Structure

ScreenshotDefaults lives in Runtime/Protocol/ so the CLI and the bridge resolve the defaults from one place and the resolution is unit-testable (Editor/*.cs is not compiled by dotnet). Resolving the cap once in Handle also collapses the ShouldApplyMaxWidth gate that was repeated at every capture site — that is most of the −59/+? churn in the handler.

Protocol 7 → 8

The default output of an existing command changed and maxWidth gained a sentinel. Bumping means a CLI that does not know the new defaults is routed to a matching install instead of silently returning different images. No response shape changed.

Verification

dotnet test — 1087 passed (17 new). check-unity-meta.sh passes; the new .cs has a Unity-generated .meta. DocGen --check clean.

Live against the sample project (Unity 6000.3.13f1, headless launch):

case	result
no options	1024x600 jpg — cap fired on a 3600×2110 Game View
same frame, --format png --max-width 0	3600x2110 png
file size	104 KB → 10 KB
--path x.png, no --format	png
--format jpeg --quality 40	jpg
--width 1600 --height 900	1600x900, cap suppressed
--max-width -1	CLI_USAGE rejection

Release note

This is a breaking default change plus a protocol bump, so it wants a minor version (0.6.0), and the CLI binary must be published before main moves — a user on #main with no CLI speaking protocol 8 would have nothing to dispatch to.

🤖 Generated with Claude Code