Capture frame
capture_frameRead-only
Capture a numbered PNG screenshot into a per-run frame series, incrementing the index automatically for step-by-step documentation of scripted edits.
Instructions
Capture the next numbered PNG screenshot in a per-run frame series.
When to use: documenting a scripted edit sequence step-by-step. For a one-off check use
`render_preview`; to gather a finished series use `list_frames`.
Key params: `series` (sanitized; defaults to `run`) groups frames into a folder under
`artifacts/frames/<series>/`; the index is derived from the filesystem (highest existing
`frame-NNN` + 1) — monotonic, survives a restart, never clobbers. `label` is folded into the
frame name. Renders the whole canvas exactly like `render_preview` (no UI chrome). INLINE RASTER
: the PNG is returned inline by default (gated by max_output_bytes); inline=False
returns only the structured result.
Return shape: `FrameResult` — `artifact_path` / `workspace_relative_path` (same value),
`format`, `width_px`/`height_px`, `series`, `frame_index` (1-based), `stale`. With an inline
image, a `ToolResult` carrying the same fields plus the image block.
Example: `capture_frame(doc_id, series="cleanup", label="after-simplify")`
Risk class: low (render to the managed artifacts dir; no original overwrite, no Operation
Record).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| doc_id | Yes | ||
| inline | No | ||
| series | No | ||
| width_px | No | ||
| max_output_bytes | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stale | No | ||
| doc_id | Yes | ||
| format | Yes | ||
| series | Yes | ||
| width_px | Yes | ||
| height_px | Yes | ||
| frame_index | Yes | ||
| artifact_path | Yes | ||
| workspace_relative_path | Yes |