# Add segmented screenshots to BrowseWeb

> **Status: Implemented (2026-07-03).** 設計との主な差分は下記「Implementation notes」を参照。

## Implementation notes (設計との差分)

- **既定を分割に変更**: 当初案は `screenshotSegments: true` のオプトインだったが、実際のユーザー意図は「スクショは既定で 1 画面ぶんずつ区切る」だったため、**BrowseWeb では分割を既定挙動**にした。フルページ 1 枚が欲しい場合は `screenshotSegments: false`（基本モード）/ アクションの `segments: false` でオプトアウトする。
- **短ページは連番なし**: 1 画面に収まるページは連番を付けず `output/<name>.png` の 1 枚のまま（後方互換）。2 画面ぶん以上のときだけ `-001` / `-002` の連番になる。
- **分割単位・撮影方式**: ビューポート高さ（1 画面ぶん）を単位に、`fullPage: true` + `clip` でページを縦に切り出す。スクロールしないため、(1) `position:fixed`/`sticky` なヘッダーが各セグメント先頭に重複して本文を隠さない、(2) 撮影後にページのスクロール位置を変えないので後続アクション（ref/selector クリック等）に副作用が出ない。最後のセグメントは残り高さぶんだけ切り出し、下端に余白を作らない。
- **枚数の絶対上限**: `maxSegments` はユーザー（LLM）指定でも `ABSOLUTE_MAX_SEGMENTS`（50）を超えない。巨大な `scrollHeight` を返すページや極端な指定値による撮影ループの暴走（worker 時間・ディスク枯渇）を防ぐ最終防波堤。非有限値（NaN/Infinity）は既定値にフォールバック。
- **TestWorkspaceApp は現状維持**: 共通ハンドラ（`runPageActions`）の既定を分割にしたため、`TestWorkspaceApp` の screenshot アクションには `segments: false` を明示して単一フルページ撮影を維持（本 issue の scope 指示どおり）。
- **打ち切り通知**: `maxSegments`（既定 10）で打ち切った場合は戻り値にその旨を出力（無音打ち切りにしない）。
- 実装: `src/engine/tools/browser.ts`（`planScreenshotSegments` / `segmentFilename` / `captureScreenshots`）、テスト: `browser.screenshot-segments.test.ts`（純関数）・`browser.screenshot-capture.test.ts`（実ブラウザ、`CONTAINER=1` ゲート）。

## Summary

Long HTML pages are hard for agents to verify from a single screenshot. A full-page
capture can become extremely tall, causing image understanding to miss details or
compress important UI states. Viewport-only screenshots avoid giant images, but they
only show the first visible area.

Add a segmented screenshot mode to `BrowseWeb` so agents can capture a page as a
sequence of viewport-sized images.

## Problem

For generated HTML verification and UI review, agents often need to inspect the
whole rendered page. Current screenshot modes are not ideal:

- viewport screenshot: readable, but only captures one screen
- full-page screenshot: complete, but can be too tall and information-dense

This makes visual verification unreliable for long reports, dashboards, and other
HTML outputs.

## Proposed Design

Keep existing screenshot behavior and add an explicit segmented mode.

### Basic BrowseWeb mode

```js
BrowseWeb({
  url: "output/report.html",
  screenshot: "report.png",
  screenshotSegments: true
})
```

Expected output files:

```text
output/report-001.png
output/report-002.png
output/report-003.png
```

### Action mode

```js
BrowseWeb({
  actions: [
    { type: "goto", url: "output/report.html" },
    { type: "screenshot", value: "report.png", segments: true, maxSegments: 8 }
  ]
})
```

### Behavior

- Scroll the page from top to bottom and capture one viewport-sized screenshot
  per segment.
- Use stable generated names based on the requested screenshot filename:
  `name-001.ext`, `name-002.ext`, etc.
- Return the saved file list in the tool output.
- Default to a bounded number of segments, for example `maxSegments: 10`, to
  avoid runaway captures on infinite-scroll pages.
- Allow callers to override the cap with `maxSegments`.
- Preserve existing modes:
  - default screenshot remains a single viewport image
  - full-page screenshot remains available via the explicit full-page option
- Do not change `TestWorkspaceApp` iframe screenshots unless a separate need is
  identified.

## Files Likely Involved

- `src/engine/tools/browser.ts`
  - extend `BrowseWebAction` with `segments?: boolean` and `maxSegments?: number`
  - add basic-mode inputs `screenshotSegments` and `screenshotMaxSegments`
  - implement shared segmented capture helper

- `src/engine/tools/browser.runpageactions.test.ts`
  - add regression coverage for segmented screenshots on a tall local HTML page
  - assert filenames and image heights/counts

- `docs/tools/browseweb.md`
  - document segmented screenshot usage

- `ui/src/content/help/00-changelog.md`
  - add a user-facing changelog entry when implemented

- `ui/src/content/help/16-tools.md`
  - mention that browser screenshots can be captured as viewport, full-page, or
    segmented images

## Acceptance Criteria

- `BrowseWeb({ url, screenshot, screenshotSegments: true })` saves multiple
  viewport-sized screenshots for a tall page.
- Action-mode `screenshot` supports `segments: true`.
- The tool output lists all saved segment paths.
- Segment count is capped by default and configurable.
- Existing viewport and full-page screenshot behavior continues to work.
- Tests cover viewport, full-page, and segmented capture behavior.