# Infra Screenshot Capabilities

Use `infra-screenshot` before writing ad-hoc screenshot runners, job batching loops, or local artifact persistence glue.

If you are in a repo that depends on `infra-screenshot`, start with:

```python
from screenshot.capabilities import CAPABILITIES, find_capabilities

for capability in find_capabilities("playwright timeout viewport"):
    print(capability.task, capability.preferred_import)
```

## Task Map

### Local CLI / JSONL batch capture

- Prefer: `screenshot local --input jobs.jsonl --output-dir ./out`
- Use this for: local runs, JSONL job specs, machine-readable summaries, and backend selection.
- Example: `screenshot local --input jobs.jsonl --output-dir ./out --summary-file summary.json`

### Programmatic Playwright capture

- Prefer: `from screenshot import capture_screenshots_async`
- Prefer: `from screenshot.models import CaptureOptions, MotionSnapshotRequest, ScreenshotArtifactsRequest, ScreenshotOptions`
- Use this for: the default async capture path, custom viewports, timeout budgets, HTML/GIF auxiliary artifacts, and partial-result handling.
- Example: `result = await capture_screenshots_async("job", url, store_dir=Path("out"), partition_date=None, options=options)`

### Programmatic Selenium capture

- Prefer: `from screenshot import capture_screenshots_async_selenium`
- Prefer: `from screenshot.models import CaptureOptions, ScreenshotOptions`
- Use this for: Chrome + Selenium parity, explicit driver-backed capture, or environments where Playwright is not the chosen backend.
- Example: `result = await capture_screenshots_async_selenium("job", url, store_dir=Path("out"), partition_date=None, options=options)`

### Batch orchestration with `ScreenshotService`

- Prefer: `from screenshot import ScreenshotService, ScreenshotJob, ScreenshotOptions`
- Prefer: `from screenshot.backends import build_local_screenshot_service`
- Use this for: ordered multi-job execution, cooperative cancellation, and aggregated batch outcomes.
- Example: `batch = await service.capture_async(jobs, concurrency=2)`

### Storage backend / batch summary integration

- Prefer: `from screenshot import LocalStorageBackend, CloudStorageBackend, AsyncStorageBackend`
- Prefer: `from screenshot.backends import build_local_screenshot_service`
- Use this for: artifact persistence, machine-readable summaries, and integrating stored outputs with batch results.
- Example: `summary_path = LocalStorageBackend().write_json(Path("summary.json"), batch.to_dict())`

## Preferred Usage

- Prefer `capture_screenshots_async()` for Playwright-backed programmatic capture.
- Prefer `capture_screenshots_async_selenium()` only when Selenium-specific browser behavior is needed.
- Prefer `ScreenshotService` or `build_local_screenshot_service()` from `screenshot.backends` over hand-rolled concurrency/cancellation loops.
- Prefer `ScreenshotBatchResult.to_dict()` for summary payloads and `result.outcome` for branching logic.
- Prefer `LocalStorageBackend` unless a caller provides a storage backend with upload semantics.

## Examples

Repository example scripts:

- [examples/cli_jsonl_batch_capture.py](examples/cli_jsonl_batch_capture.py)
- [examples/custom_viewport_and_html_snapshot.py](examples/custom_viewport_and_html_snapshot.py)
- [examples/playwright_motion_snapshot.py](examples/playwright_motion_snapshot.py)
- [examples/playwright_programmatic_capture.py](examples/playwright_programmatic_capture.py)
- [examples/playwright_scrolling_depth_capture.py](examples/playwright_scrolling_depth_capture.py)
- [examples/selenium_programmatic_capture.py](examples/selenium_programmatic_capture.py)
- [examples/service_batch_capture.py](examples/service_batch_capture.py)
- [examples/storage_summary_integration.py](examples/storage_summary_integration.py)

### Discover the right helper programmatically

```python
from screenshot.capabilities import find_capabilities

matches = find_capabilities("batch summary storage backend")
for capability in matches:
    print(capability.task, capability.preferred_import)
```
