[Feature]: Replace the fixed post-action sleep with page-settling detection

Author: alectimison-makerCreated Jul 26, 2026Updated Jul 26, 2026

What problem does this solve?

NavigatorAgent currently waits for one second after every successful action:

https://github.com/nanobrowser/nanobrowser/blob/322384f8b4d48d8614343e51efca68c85e64f90b/chrome-extension/src/background/agent/agents/navigator.ts#L426-L431

This adds unconditional latency to multi-action tasks, including actions that settle immediately, while a fixed delay still cannot guarantee that slower navigations or DOM updates are ready.

This report is based on source analysis of 322384f8b4d48d8614343e51efca68c85e64f90b; I have not run a browser benchmark, so the performance impact should be measured before implementation.

Proposed solution

Introduce a bounded, cancellable post-action settling helper that:

  • returns quickly when the action does not trigger relevant page activity;
  • waits for navigation or DOM state to settle when needed;
  • retains a maximum timeout so tasks cannot hang;
  • respects the existing paused/stopped state.

The helper should be timer/event injectable so its behavior can be tested without a live browser.

Acceptance criteria

  • Non-navigating actions do not always pay the full one-second delay.
  • Navigation and DOM-changing actions wait until a relevant ready/settled signal or timeout.
  • Pause/stop cancels the wait promptly.
  • Deterministic tests cover immediate settle, delayed settle, timeout, and cancellation.

Alternatives considered

  • Making the one-second value configurable preserves the unnecessary wait.
  • Removing the wait entirely risks racing page updates.

If this direction fits the project, I would be happy to prepare a focused PR after maintainer guidance on the preferred settling signal.