docs(CDPBrowser): describe waitForAction's new event-aware-by-default behavior

The waitForAction config prop's doc text still described the old
always-a-fixed-sleep behavior after the event-aware settle landed
(perf(CDPBrowser): event-aware action settle, 1c976b1) -- this is the one
place a user learns what the option does, and a config default change is
exactly the kind of thing that must be documented accurately. Also
strengthens _waitForAction's own docblock: its no-arg fallback path (used if
a call site forgets to arm first) can only arm after the action, which is
precisely the race the arm-before-dispatch design exists to avoid -- flagged
so a future call site doesn't reach for the no-arg form thinking it's a safe
default.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DavertMik

docs/helpers/CDPBrowser.md

@@ -51,7 +51,7 @@ Type: [object][5]
 *   `xpathPolyfill` **([string][2] | [boolean][7])?** whether to inject the bundled XPath polyfill before installing the in-page client. `auto` probes the page and only injects when `document.evaluate` is unavailable or broken; `true`/`false` force the behavior.
 *   `capabilities` **[object][5]?** pre-seed detected browser capabilities (`layout`, `xpath`, `screenshot`, `innerText`) to skip runtime probing. Values set here are never overwritten by `_probeCapabilities`/`_ensureClient`.
 *   `waitForTimeout` **[number][8]?** default wait* timeout in seconds, used by helpers built on top of this class.
-*   `waitForAction` **[number][8]?** how long to wait in milliseconds after click, type, or other interactions, mirroring the pacing pause other browser helpers apply between actions.
+*   `waitForAction` **[number][8]?** only takes effect when set explicitly: a literal fixed pacing sleep (in milliseconds) after click, type, or other interactions, mirroring other browser helpers. Left unset, actions settle in an event-aware way instead — near-instant when nothing navigates, waiting for the navigation to actually finish (not a guessed fixed delay) when one does.
 *   `pollInterval` **[number][8]?** interval in milliseconds between retries while polling for a condition (e.g. page ready state, `waitFor*`). Distinct from `waitForAction`.
 *   `getPageTimeout` **[number][8]?** maximum time in seconds to wait for a page to finish loading after navigation or reload; also used as the CDP command timeout (in ms, x1000).
 *   `waitForNavigation` **[string][2]?** when to consider a navigation finished: `load`, `domcontentloaded`, or `networkidle`. Mirrors the Puppeteer helper's option name. `networkidle` waits for the CDP `networkIdle` lifecycle event, which on a busy page can lag `load` by a second or more — only opt in if the extra wait is actually needed.

lib/helper/CDPBrowser.js

@@ -35,7 +35,7 @@ import { assembleApng, isPng } from './extras/apngAssembler.js'
  * @prop {string|boolean} [xpathPolyfill=auto] - whether to inject the bundled XPath polyfill before installing the in-page client. `auto` probes the page and only injects when `document.evaluate` is unavailable or broken; `true`/`false` force the behavior.
  * @prop {object} [capabilities={}] - pre-seed detected browser capabilities (`layout`, `xpath`, `screenshot`, `innerText`) to skip runtime probing. Values set here are never overwritten by `_probeCapabilities`/`_ensureClient`.
  * @prop {number} [waitForTimeout=5] - default wait* timeout in seconds, used by helpers built on top of this class.
- * @prop {number} [waitForAction=100] - how long to wait in milliseconds after click, type, or other interactions, mirroring the pacing pause other browser helpers apply between actions.
+ * @prop {number} [waitForAction=100] - only takes effect when set explicitly: a literal fixed pacing sleep (in milliseconds) after click, type, or other interactions, mirroring other browser helpers. Left unset, actions settle in an event-aware way instead — near-instant when nothing navigates, waiting for the navigation to actually finish (not a guessed fixed delay) when one does.
  * @prop {number} [pollInterval=25] - interval in milliseconds between retries while polling for a condition (e.g. page ready state, `waitFor*`). Distinct from `waitForAction`.
  * @prop {number} [getPageTimeout=30] - maximum time in seconds to wait for a page to finish loading after navigation or reload; also used as the CDP command timeout (in ms, x1000).
  * @prop {string} [waitForNavigation=load] - when to consider a navigation finished: `load`, `domcontentloaded`, or `networkidle`. Mirrors the Puppeteer helper's option name. `networkidle` waits for the CDP `networkIdle` lifecycle event, which on a busy page can lag `load` by a second or more — only opt in if the extra wait is actually needed.
@@ -1494,7 +1494,10 @@ class CDPBrowser extends Helper {
   /**
    * Settles after an interaction (click, key press, etc.) before the next step runs, using the
    * listener `_armActionSettle` started *before* the interaction was dispatched (`armed`; a fresh
-   * one is armed here too, as a safety net, if a call site forgot to).
+   * one is armed here too, as a safety net, if a call site forgot to — but arming this late can
+   * only miss a navigation that already started during the action's own dispatch, exactly the race
+   * this design exists to avoid, so every call site should pass its own pre-armed `armed`, not rely
+   * on this fallback).
    *
    * If `options.waitForAction` was set explicitly in the config, honors it literally as a fixed
    * pacing sleep, exactly as before this round — an explicit value is a deliberate choice