Skip to content

G6: add bounded region-scoped screenshot series #211

Description

@SarthakWade

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:cliCLI parser, help, capabilitiesarea:core-protocolHeadlessProtocol: wire protocol, validation, transportarea:linux-hostChromium host (LinuxHost/, CDP)backlogTracked in docs/roadmap/improvements-backlog.mdpriority:lowNice to havetype:featureNew capability or command

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions