Live: wait for change
live_wait_for_changePause execution until the user edits the document, selection, or viewport, then return change flags. Prevents busy-waiting in live sessions.
Instructions
Block until the live state changes, or the bounded timeout elapses (read-only).
When to use: between live_session_step iterations so the loop reacts to the user's own GUI
edits instead of busy-rendering. To then re-perceive use live_get_scene.
Key params: timeout_s is clamped to at most 60s and poll_interval_s is floored, so the wait
never spins tightly nor blocks forever (it sleeps between cheap polls). Each poll pulls a CHEAP
state token (small revision marker + selection ids + coarse viewport — never the full doc or a
PNG; protocol v5), hashed + diffed against the last token. Requires a session; no
code/raw-Action path (ADR-003). NOTE: the socket helper runs on a snapshot, so within one call
it cannot observe later GUI edits; the token mechanism is transport-agnostic and detects user
edits on any transport that recomputes per poll.
Return shape: LiveChange — changed, timed_out, and the delta flags selection_changed /
document_changed / viewport_changed (more than one may fire).
Example: live_wait_for_change(timeout_s=10)
Risk class: low (read-only polling; no document mutation, no Operation Record).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout_s | No | ||
| poll_interval_s | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | The newest observed state token. | |
| changed | No | Whether any tracked component changed. | |
| timed_out | No | True when a bounded wait elapsed with no change. | |
| selection_ids | No | Current selection object ids at observation time. | |
| document_changed | No | Document revision marker changed. | |
| viewport_changed | No | Viewport (zoom/center) changed. | |
| selection_changed | No | Selection ids changed. |