Name a rectangle of the screen to watch. Coordinates are in the global layout the capture tool uses (on a multi-monitor wlroots layout an output left of the primary has negative x). Masks are rects inside the region, in region-local pixels, that are ignored: put a clock or spinner there. Redefining a name replaces it and forgets its last sample.

Watch a window rather than a fixed rectangle: geometry is looked up from the window id before every capture, so the region follows the window when it moves. A resize counts as maximal change. Masks are window-local. The id is whatever your window-geometry command understands (a Hyprland address like 0x5f3a..., an X11 window id).

Ask the person at the screen to click the window to watch (visible windows are offered as boxes; Escape cancels). The region then follows that window. Prefer this over pir_define_window when a human is present.

Ask the person at the screen to draw the rectangle to watch (a selector such as slurp appears; Escape cancels). Prefer this over pir_define_region whenever a human is present: they choose what is sensed, and you get the geometry back. Blocks until they finish or the selector times out.

Ask the person to draw a rectangle inside an existing region that should be ignored (a clock, a spinner, a caret). Forgets the region's last sample, since masked grids are not comparable to unmasked ones.

The regions currently defined, with their geometry and masks.

Forget a region.

Capture the region once and score it against the previous sample of the same region (null on the first call). Cheap and non-blocking: use it to check the capture command works, to take a baseline before doing something, or to ask 'did anything happen there since I last looked?'.

Block until the region looks different from how it looked when this call started, or until timeout_ms. Returns changed=true with the score, or changed=false with the largest score seen. Use it as a doorbell: 'wake me when the build output moves', 'when the dialog closes', 'when the game loads'.

Block until consecutive samples have stayed below threshold for still_for_ms, or until timeout_ms. A short window means 'the page/animation has settled, safe to act'. A long window on something that should keep changing (a clock, a progress bar, a status bar) means it is frozen: still=true is then the alarm.