feat(snapshot): add --wait-for flag for polling until element appears

[fuleinist]

Summary

Add a --wait-for flag to agent-device snapshot that polls the accessibility tree until a target element appears, with configurable timeout.

Motivation

AI agents frequently need to wait for UI state changes: a modal to appear, a loading spinner to disappear, a specific button to become available. Today agents must implement their own polling loop: snapshot, check, sleep, retry. This burns tokens, adds latency, and duplicates logic across every agent workflow.

Proposed shape

agent-device snapshot --wait-for "button:contains('Submit')" --timeout 15
agent-device snapshot --wait-for "window:contains('Settings')" --timeout 10
agent-device tap "button:contains('Save')" --wait-for "text:contains('Saved!')" --timeout 5

Key design points

• Polls the accessibility tree at a reasonable interval (e.g. 500ms)
• Returns the snapshot as soon as the target element appears
• Returns exit code 1 + last snapshot if timeout expires
• Reuses existing selector/filter infrastructure
• Works with any command that produces a snapshot: snapshot, tap, type, etc.
• Compact output: only the final snapshot (not intermediate polls)

Why small

The polling loop is straightforward, the selector infrastructure already exists, and this is purely a CLI orchestration feature - no new platform APIs or accessibility tree changes needed.

[thymikee]

Triage update: I no longer think this needs a new feature as proposed. The repo already has the core synchronization primitive via wait, which polls selector/text/ref state without forcing agents to hand-roll snapshot loops:

agent-device wait 'role="button" label="Submit"' 15000
agent-device wait text "Saved!" 5000
agent-device wait 'id="settings-title"' 10000

If the agent needs fresh refs or the final tree after the wait succeeds, the supported workaround is a second snapshot:

agent-device wait 'label="Settings"' 10000
agent-device snapshot -i

That is one extra command, but it keeps the command surface clearer: wait owns synchronization, snapshot owns tree capture. I would not add snapshot --wait-for, and I would definitely not spread --wait-for across mutating commands like press/fill/type. The proposed examples also use unsupported surface (tap, CSS-ish button:contains(...) selectors), so implementing them as-is would introduce parallel command/selector vocabulary.

Recommendation: close this as covered by existing wait plus snapshot -i, or narrow it to docs/help guidance that teaches agents to use wait <selector|text|@ref> [timeoutMs] instead of polling snapshots manually.