Settling
After every action, BrowserControl waits for the page to finish reacting before it takes the screenshot. A single-page app that fetches data and then renders is captured complete, not half drawn, and the agent rarely needs to sleep.
The three stages
Load
Wait for the DOMContentLoaded event, which matters after a navigation.
Network quiet
Wait until no request has been in flight for 200 ms. Streams (WebSocket, EventSource, media) and requests open for more than 10 seconds, such as long polling, are ignored so they can't hold every action hostage.
DOM quiet
Wait until the page has gone 200 ms without a DOM change, for at most one second.
All three share one budget, BROWSER_SETTLE_TIMEOUT, 3 seconds by default. When the budget runs out, BrowserControl takes the screenshot anyway. Settling never fails an action.
Tune the budget for your sites: lower it on static pages for speed, raise it for slow apps.
When to wait longer
Some things take longer than any sensible budget: a report that renders after ten seconds, a payment that confirms asynchronously. Wait for the condition itself rather than for time.
| You're waiting for | Use |
|---|---|
| Text to appear | wait_for(text="Order confirmed") |
| An element to appear or go away | wait_for(selector=".spinner", state="hidden") |
| All network activity to stop | wait_for(network_idle=True) (500 ms with nothing in flight) |
| A specific API call | wait_for_response("/api/orders"), called right after the action that sends it |
| Nothing in particular | wait(seconds), as a last resort |
wait_for and wait_for_response time out after 10 seconds by default (timeout_seconds). A timeout isn't an error: the response says what timed out and still includes the screenshot.
→ click(12) # "Place order"
→ wait_for_response("/api/orders", status=201)
Response received: #57 POST https://shop.test/api/orders -> 201 (842ms)
Body: {"id": "ord_123", "status": "confirmed"}wait_for_response also counts responses that arrived during the previous tool call, so calling it right after the click never misses a fast response.
Things that happen while settling
A JS alert, confirm, or prompt can't be allowed to block the page, so BrowserControl answers it straight away. Alerts are acknowledged, confirms and prompts are dismissed, and beforeunload is accepted. Files the page downloads are saved. Both show up as Notice: lines at the top of the next response:
Notice: A JS dialog appeared: confirm('Delete this item?'), dismissed. Call handle_dialog() before the action to choose the answer.To answer differently, call handle_dialog(accept=True) and repeat the action.
