Parent: #54, roadmap backlog G6.
Goal
Let an agent turn an outline region reference into a bounded screenshot series without selectors or unbounded full-page capture. The original backlog names Linux, but the existing portable series pipeline makes cross-engine behavior the safer contract.
headless --session qa inspect --context outline
headless --session qa screenshot --by-region @r4 --output checkout
Contract
- Add
screenshot --by-region @rN as a third series mode alongside --every-viewport and --by-section.
- Accept only a region reference issued by the current page runtime. Do not accept selectors, element refs, roles, or names in this mode.
- Capture only the region bounds. Split a tall region into deterministic vertical image slices and include the final extent. Do not include pixels outside the region.
- Preserve the current PNG/JPEG formats, private artifact store, exclusive creation, numbered output prefixes, 80-image cap,
truncated, and totalPoints reporting. PDF and clipboard remain unsupported for series.
- Revalidate the region before each slice. Unknown, expired, detached, hidden, non-intersecting, or invalid geometry fails closed with
REGION_NOT_FOUND or the existing bounded-capture error.
- Reserve the complete artifact set before capture and discard every reservation on failure. Never return a partial successful series.
- Restore the original scroll position after success or failure.
- Apply the shared screenshot dimension and pixel bounds to every slice.
- Mark series metadata containing page-derived labels as untrusted. Do not add page text, selectors, HTML, coordinates from the runtime map, or region contents to logs or flows.
- Advertise region series explicitly in capabilities and generated SDK metadata. Keep protocol version
0.5 if the change remains additive.
Required implementation surfaces
- Architecture decision before behavior changes.
- CLI parser/help, protocol validation, Rust protocol mirror, canonical schema and fixtures.
- Isolated runtime region planning and per-slice bounds.
- Shared series orchestration and both WebKit and Chromium adapters.
- TypeScript and Python generated SDK contracts and validators.
- README, command reference, phase contract, skill docs, and G6 backlog status.
Acceptance criteria
- Parser and protocol tests cover valid refs plus unknown, malformed, conflicting, PDF, clipboard, single-output, full-page, element-target, and mixed-series cases.
- Runtime tests cover short and tall regions, final-slice coverage, the 80-image cap, stale/detached/hidden refs, invalid geometry, and layout changes during capture.
- Shared tests prove atomic reservation cleanup and scroll restoration on success and failure.
- Linux and macOS E2E each prove a real region series contains only region pixels and produces deterministic bounded artifacts.
- Existing single, full-page, viewport, and section screenshots remain unchanged.
- Protocol, runtime, SDK, Rust, build, and both engine E2E gates pass.
Parent: #54, roadmap backlog G6.
Goal
Let an agent turn an outline region reference into a bounded screenshot series without selectors or unbounded full-page capture. The original backlog names Linux, but the existing portable series pipeline makes cross-engine behavior the safer contract.
Contract
screenshot --by-region @rNas a third series mode alongside--every-viewportand--by-section.truncated, andtotalPointsreporting. PDF and clipboard remain unsupported for series.REGION_NOT_FOUNDor the existing bounded-capture error.0.5if the change remains additive.Required implementation surfaces
Acceptance criteria