glass_wait_for_region
Waits for a UI region to change or match a saved baseline, returning metrics like changed percentage and bounding box. Use 'matches' to confirm the UI reached an approved design without vision tokens.
Instructions
Block until a visual region changes (diverges from a reference) or matches (converges to a saved baseline), then return text metrics (no image unless include_image:true). until: "changes" (default) or "matches" (needs baseline); optional window-relative region; mode perceptual|exact with threshold/tolerance. Returns {matched,changed_pct,bbox,elapsed_ms}. Use "matches" to confirm the UI reached an approved design without spending vision tokens.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | "perceptual" (default) or "exact". | |
| until | No | "changes" (default; diverge from reference) or "matches" (converge to baseline). | |
| ignore | No | Window-relative rectangles to exclude from the comparison. Use for perpetually animating content — a blinking text caret, a clock, a spinner — which otherwise keeps `changed_pct` permanently non-zero. `changed_pct` is measured over the pixels that remain. Combines with `region`: rects are always window-relative and are intersected with it. A rect that falls partially or entirely outside the compared area — the frame, or the `region` sub-rectangle when one is set — is silently clamped or dropped, masking less than requested or nothing at all; the excluded count is reported as `ignored_pixels`, so a smaller-than- expected value flags a misplaced rect. | |
| region | No | Window-relative sub-rectangle to watch; omit for the whole window. | |
| baseline | No | Saved baseline name to compare against; omit to use the frame at call start. | |
| threshold | No | Perceptual sensitivity (default 0.1; smaller = stricter). | |
| tolerance | No | Exact per-channel tolerance (default 0). | |
| window_id | No | Capture/observe this window (id from `glass_list_windows`) instead of the active one, without changing which window subsequent ops target. Omit for the active window. | |
| timeout_ms | No | Give up after this long (default 10000ms); returns `{matched:false}`. | |
| interval_ms | No | Poll interval (default 100ms). | |
| include_image | No | On match, also return the watched region as an image (default false). |