@browserbridge/bbx 1.7.7 → 1.8.0

package/packages/protocol/src/types.ts

@@ -1,5 +1,15 @@
 export type BridgeRequestSource = 'cli' | 'mcp';
 
+export type AccessIntent = 'inspect' | 'interact' | 'capture' | 'navigate' | 'debugger' | 'general';
+
+export interface AccessRequestParams {
+  intent?: AccessIntent;
+}
+
+export interface NormalizedAccessRequestParams extends BridgeParams {
+  intent: AccessIntent;
+}
+
 export type Capability =
   | 'page.read'
   | 'page.evaluate'
@@ -25,6 +35,15 @@ export type ErrorCode =
   | 'ACCESS_DENIED'
   | 'TAB_MISMATCH'
   | 'ELEMENT_STALE'
+  | 'ELEMENT_AMBIGUOUS'
+  | 'ELEMENT_NOT_ACTIONABLE'
+  | 'ELEMENT_OBSCURED'
+  | 'ELEMENT_NOT_FOUND'
+  | 'INPUT_UNSUPPORTED'
+  | 'INPUT_INVALID_TARGET'
+  | 'INPUT_FOCUS_CHANGED'
+  | 'DIALOG_NOT_OPEN'
+  | 'DIALOG_ACTION_CONFLICT'
   | 'RESULT_TRUNCATED'
   | 'RATE_LIMITED'
   | 'INTERNAL_ERROR'
@@ -45,9 +64,11 @@ export type BridgeMethod =
   | 'page.get_state'
   | 'page.evaluate'
   | 'page.get_console'
+  | 'page.handle_dialog'
   | 'page.wait_for_load_state'
   | 'page.get_storage'
   | 'page.get_text'
+  | 'page.extract_content'
   | 'page.get_network'
   | 'network.intercept.add'
   | 'network.intercept.remove'
@@ -228,6 +249,29 @@ export interface InputTarget {
   selector?: string;
 }
 
+export type InputExecutionMode = 'dom' | 'cdp';
+
+export interface InputResolutionMetadata {
+  strategy: 'elementRef' | 'selector-first' | 'selector-ranked' | 'stale-recovery';
+  candidateCount: number;
+  evaluatedCount: number;
+  scrolled: boolean;
+  hitTest: 'target' | 'descendant' | 'none' | 'not-required';
+  recovered: boolean;
+  oldRef?: string;
+  newRef?: string;
+  matchedFields?: string[];
+  confidenceBasis?: string;
+}
+
+export interface InputExecutionMetadata {
+  requestedMode: InputExecutionMode;
+  actualMode: InputExecutionMode;
+  fallbackReason: null;
+  debuggerUsed: boolean;
+  targetCoordinates?: { x: number; y: number };
+}
+
 export interface InputActionParams {
   target?: InputTarget;
   button?: 'left' | 'middle' | 'right';
@@ -239,6 +283,8 @@ export interface InputActionParams {
   submit?: boolean;
   key?: string;
   modifiers?: string[];
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedInputAction extends BridgeParams {
@@ -252,6 +298,8 @@ export interface NormalizedInputAction extends BridgeParams {
   submit: boolean;
   key: string;
   modifiers: string[];
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface CdpDispatchKeyEventParams {
@@ -277,11 +325,15 @@ export interface NormalizedCdpNodeIdParams extends BridgeParams {
 export interface CheckedActionParams {
   target?: InputTarget;
   checked?: boolean;
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedCheckedAction extends BridgeParams {
   target: InputTarget;
   checked: boolean;
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface SelectActionParams {
@@ -289,6 +341,8 @@ export interface SelectActionParams {
   values?: string[];
   labels?: string[];
   indexes?: number[];
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedSelectAction extends BridgeParams {
@@ -296,6 +350,8 @@ export interface NormalizedSelectAction extends BridgeParams {
   values: string[];
   labels: string[];
   indexes: number[];
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface ViewportActionParams {
@@ -417,6 +473,21 @@ export interface ConsoleParams {
   limit?: number;
 }
 
+export type DialogAction = 'inspect' | 'accept' | 'dismiss';
+
+export interface HandleDialogParams {
+  action?: DialogAction;
+  promptText?: string;
+  /** Optional stale-decision check performed immediately before CDP dispatch. */
+  expectedDialogId?: string;
+}
+
+export interface NormalizedHandleDialogParams extends BridgeParams {
+  action: DialogAction;
+  promptText: string | null;
+  expectedDialogId: string | null;
+}
+
 export interface NormalizedConsoleParams extends BridgeParams {
   level: string;
   clear: boolean;
@@ -483,12 +554,16 @@ export interface HoverParams {
   target?: InputTarget;
   duration?: number;
   modifiers?: string[];
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedHoverParams extends BridgeParams {
   target: InputTarget;
   duration: number;
   modifiers: string[];
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface DragParams {
@@ -496,6 +571,8 @@ export interface DragParams {
   destination?: InputTarget;
   offsetX?: number;
   offsetY?: number;
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedDragParams extends BridgeParams {
@@ -503,6 +580,8 @@ export interface NormalizedDragParams extends BridgeParams {
   destination: InputTarget;
   offsetX: number;
   offsetY: number;
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface StorageParams {
@@ -515,14 +594,75 @@ export interface NormalizedStorageParams extends BridgeParams {
   keys: string[] | null;
 }
 
+export type ExtractContentFormat = 'text' | 'markdown';
+export type ExtractContentConsistency = 'best_effort' | 'settled';
+export type ExtractContentSource = 'readability' | 'semantic-root' | 'body';
+export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
+
+export interface ExtractContentParams {
+  format?: ExtractContentFormat;
+  selector?: string;
+  includeMetadata?: boolean;
+  consistency?: ExtractContentConsistency;
+  textBudget?: number;
+  settleTimeoutMs?: number;
+}
+
+export interface NormalizedExtractContentParams extends BridgeParams {
+  format: ExtractContentFormat;
+  selector: string | null;
+  includeMetadata: boolean;
+  consistency: ExtractContentConsistency;
+  textBudget: number;
+  settleTimeoutMs: number;
+}
+
+export interface ScreenshotParams extends BridgeParams {
+  format?: ScreenshotFormat;
+  quality?: number;
+}
+
+export interface NormalizedScreenshotParams extends BridgeParams {
+  format: ScreenshotFormat;
+  quality: number | null;
+}
+
+export interface ScreenshotResult {
+  image: string;
+  mimeType: `image/${ScreenshotFormat}`;
+  format: ScreenshotFormat;
+  rect: { x: number; y: number; width: number; height: number; scale: number };
+  complete: boolean;
+  clipped: boolean;
+}
+
+export interface ExtractContentResult {
+  format: ExtractContentFormat;
+  content: string;
+  title?: string;
+  byline?: string;
+  excerpt?: string;
+  siteName?: string;
+  source: ExtractContentSource;
+  root?: { tag: string; selector?: string };
+  length: number;
+  truncated: boolean;
+  omitted: number;
+  settlement?: { requested: boolean; quietMs: number; timedOut: boolean };
+}
+
 export interface WaitForLoadStateParams {
   waitForLoad?: boolean;
   timeoutMs?: number;
+  url?: string;
+  urlMatch?: 'exact' | 'contains' | 'regex';
 }
 
 export interface NormalizedWaitForLoadStateParams extends BridgeParams {
   waitForLoad: boolean;
   timeoutMs: number;
+  url: string | null;
+  urlMatch: 'exact' | 'contains' | 'regex' | null;
 }
 
 export interface TabCreateParams {
@@ -544,25 +684,119 @@ export interface NormalizedTabCloseParams extends BridgeParams {
 }
 
 export interface AccessibilityTreeParams {
+  selector?: string;
   maxDepth?: number;
   maxNodes?: number;
+  compact?: boolean;
+  interactiveOnly?: boolean;
 }
 
 export interface NormalizedAccessibilityTreeParams extends BridgeParams {
+  selector: string | null;
   maxDepth: number;
   maxNodes: number;
+  compact: boolean;
+  interactiveOnly: boolean;
 }
 
+export interface AccessibilityTreeNode {
+  nodeId: string;
+  role: string;
+  name: string;
+  description: string;
+  value: string;
+  focused: boolean;
+  required: boolean;
+  checked: 'true' | 'false' | 'mixed' | null;
+  disabled: boolean;
+  interactive: boolean;
+  semanticInteractive: boolean;
+  focusable: boolean;
+  focusableAndEnabled: boolean;
+  ignored: boolean;
+  childIds: string[];
+}
+
+export interface AccessibilityTreeResult {
+  nodes: AccessibilityTreeNode[];
+  rootIds: string[];
+  count: number;
+  total: number;
+  rawTotal: number;
+  source: 'cdp-accessibility';
+  compact: boolean;
+  interactiveOnly: boolean;
+  truncated: boolean;
+  truncation: {
+    reason: 'maxNodes' | 'maxDepth';
+    reasons: Array<'maxNodes' | 'maxDepth'>;
+    maxNodes: number;
+    maxDepth: number;
+    omitted: number;
+    missingChildCount: number;
+    partialTopology: true;
+  };
+  continuationHint: string;
+}
+
+export type NetworkSource = 'fetch-xhr' | 'cdp';
+export type NetworkCaptureAction = 'read' | 'start' | 'clear' | 'stop';
+
 export interface NetworkParams {
   clear?: boolean;
   limit?: number;
   urlPattern?: string;
+  source?: NetworkSource;
+  capture?: NetworkCaptureAction;
 }
 
 export interface NormalizedNetworkParams extends BridgeParams {
   clear: boolean;
   limit: number;
   urlPattern: string | null;
+  source: NetworkSource;
+  capture: NetworkCaptureAction;
+}
+
+export interface CdpNetworkEntry {
+  requestId: string;
+  url: string;
+  method: string;
+  resourceType: string;
+  status: number;
+  mimeType: string;
+  protocol: string;
+  fromCache: boolean;
+  fromDiskCache: boolean;
+  fromServiceWorker: boolean;
+  fromPrefetchCache: boolean;
+  redirect: {
+    count: number;
+    hops: Array<{ url: string; status: number }>;
+    truncated: boolean;
+  };
+  failureReason: string;
+  duration: number;
+  timestamp: number;
+}
+
+export interface NetworkResult {
+  entries: Array<CdpNetworkEntry | Record<string, unknown>>;
+  count: number;
+  total: number;
+  filteredTotal: number;
+  dropped: number;
+  abandoned: number;
+  source: NetworkSource;
+  capture: NetworkCaptureAction | null;
+  armed: boolean;
+  armedDuringCapture: boolean;
+  captureState: 'armed' | 'stop_failed' | 'stopped' | 'instrumented';
+  ownershipHeld: boolean;
+  startedAt: number | null;
+  inflight: number;
+  truncated: boolean;
+  truncation: { reason: 'limit' | null; limit: number; omitted: number };
 }
 
 export type NetworkInterceptAction = 'fulfill' | 'continue' | 'block';

package/skills/browser-bridge/SKILL.md

@@ -13,13 +13,13 @@ Permission prompts are controlled by the host agent, not by Browser Bridge. In p
 
 Skill name: `browser-bridge` (also known as `bbx`). In GitHub Copilot, invoke as `/browser-bridge`. `bbx` is the CLI command used throughout this skill.
 When the runtime supports subagents, delegate bridge inspection to a smaller, lower-cost worker and return only concise findings to the parent.
-For open-ended investigation, start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `styles.get_computed`, and `bbx batch` for CLI or `browser_batch` for MCP) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient. `browser_call` accepts one protocol method at a time; `batch` is not a valid `browser_call` method.
+For open-ended investigation, start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `page.extract_content`, `styles.get_computed`, and `bbx batch` for CLI or `browser_batch` for MCP) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient. `browser_call` accepts one protocol method at a time; `batch` is not a valid `browser_call` method.
 
 ## CLI
 
 ```bash
 bbx status                  # daemon + extension health
-bbx doctor                  # install/access readiness
+bbx doctor                  # consolidated local diagnostics (does not probe remotes)
 bbx access-request          # ask user to enable access for the focused window
 bbx restart                 # start/restart the daemon and running MCP servers
 bbx call <method> '{...}'   # any RPC method (raw output)
@@ -58,7 +58,7 @@ bbx a11y-tree [maxNodes] [maxDepth]  # accessibility tree
 ```bash
 bbx eval [--await] <expression>      # JS eval (--await for promises, - for stdin)
 bbx console [level]                  # console output
-bbx network [limit]                  # network requests
+bbx network [limit]                  # recent fetch/XHR requests
 bbx intercept add <pattern> [--respond <body>] [--status <code>] [--block]  # intercept matching requests
 bbx intercept list|remove <id>|clear # manage interception rules
 bbx page-text [budget]               # full page text
@@ -70,6 +70,8 @@ bbx back                             # navigate back
 bbx forward                          # navigate forward
 bbx scroll <top> [left]              # scroll viewport
 bbx resize <width> <height>          # resize viewport
+bbx call page.wait_for_load_state '{"url":"/dashboard","urlMatch":"contains","waitForLoad":false}'
+bbx call page.handle_dialog '{"action":"inspect"}' # inspect current JS dialog; never auto-accept
 ```
 
 ### Interact & Patch
@@ -83,11 +85,12 @@ bbx press-key <key> [ref]            # send key event
 bbx cdp-press-key --tab <id> Escape  # CDP key event without foreground focus
 bbx hover <ref>                      # hover over element
 bbx call input.scroll_into_view '{"target":{"elementRef":"el_123"}}' # ensure target is visible
+bbx call input.click '{"target":{"elementRef":"el_123"},"executionMode":"cdp"}' # optional native click
 bbx patch-style <ref> prop=val...    # apply style patch
 bbx patch-text <ref> <text...>       # apply text patch
 bbx patches                          # list active patches
 bbx rollback <patchId>               # rollback a patch
-bbx screenshot <ref> [outPath]       # capture partial element screenshot
+bbx screenshot [--format png|jpeg|webp] [--quality 0-100] <ref> [outPath] # complete element capture
 bbx call screenshot.capture_full_page '{}' # raw base64; avoid unless document context matters
 ```
 
@@ -104,6 +107,8 @@ bbx dom-query "#app" --remote <name>
 
 In MCP mode, pass `destinationId` on any browser tool call instead; `browser_status` lists all destinations with reachability. Only use remotes the user has configured; local remains the default.
 
+`bbx doctor` is intentionally local-only. It reports how many remotes are configured, but marks their status `not_probed_local_only` and credentials `unverified`; use `bbx remote test <name>` when the user wants a remote probe.
+
 ## Access Flow
 
 Browser Bridge access is window-scoped. The user turns it on once for the current browser window in the popup or side panel.
@@ -132,6 +137,12 @@ After access is enabled:
 | ------------------------- | -------- | ----------------------------------------------------------------------------------------- |
 | `ACCESS_DENIED`           | No       | Failed call already surfaced an `Enable` cue; ask user to click `Enable`, then retry once |
 | `ELEMENT_STALE`           | No       | Re-query with `dom.query` or `dom.find_by_text` to get a fresh ref                        |
+| `ELEMENT_AMBIGUOUS`       | No       | Narrow the selector or use an explicit `elementRef`; do not guess                         |
+| `ELEMENT_NOT_ACTIONABLE`  | No       | Inspect hidden/disabled/inert state with `dom.describe`                                   |
+| `ELEMENT_OBSCURED`        | No       | Inspect bounded blocker details or use `layout.hit_test`                                  |
+| `INPUT_FOCUS_CHANGED`     | No       | Inspect focus handlers; do not replay native text automatically                           |
+| `DIALOG_NOT_OPEN`         | No       | Trigger or inspect the dialog again                                                       |
+| `DIALOG_ACTION_CONFLICT`  | No       | Inspect current dialog state; never auto-repeat accept/dismiss                            |
 | `TAB_MISMATCH`            | No       | Tab closed or not found - use `tabs.list` to find an available tab                        |
 | `TIMEOUT`                 | Once     | Retry once; if still failing, simplify (smaller `maxNodes`, narrower selector)            |
 | `RATE_LIMITED`            | After 2s | Back off 2 seconds, then retry                                                            |
@@ -157,14 +168,18 @@ Error responses now include a machine-readable `error.recovery` field with `retr
 9. **Batch reads** - combine independent reads with `bbx batch` in CLI mode or `browser_batch` in MCP mode; do not pass `batch` as a `browser_call` method.
 10. **Avoid debugger first** - prefer DOM/content-script methods (`dom.*`, `styles.*`, `layout.get_box_model`, `page.get_console`, `page.get_text`, `page.get_storage`, `page.get_network`) before any debugger-backed method. Escalate to CDP only when those cannot answer the question.
 11. **Evaluate only when needed** - `page.evaluate` is powerful but debugger-backed; use it only when DOM, storage, console, network, or text reads cannot expose the needed state.
-12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `dom.get_accessibility_tree`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`.
+12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, `page.get_network` with `source: 'cdp'`, input with `executionMode: 'cdp'`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`.
 13. **Wait after change** - after editing source, wait for expected new text, a selector matching the changed attribute, or a detach/attach remount; waiting for `attached` on a selector that already exists does not prove HMR ran. Use `page.wait_for_load_state` for navigation, not HMR.
-14. **Prime event buffers** - before reproducing a console or network issue, call `page.get_console` and `page.get_network` once with `clear: true`; then reproduce the event and read each buffer without clearing it.
+14. **Prime event buffers** - before reproducing a console or fetch/XHR issue, call `page.get_console` and default `page.get_network` once with `clear: true`; then reproduce and read without clearing. CDP all-resource capture instead requires explicit `start`, reproduce, `read`, and `stop` calls.
 15. **Semantic finding** - use `dom.find_by_text` / `dom.find_by_role` when you know the label but not the selector.
-16. **Text extraction** - use `page.get_text` for full page text instead of `dom.query` on body.
+16. **Text extraction** - use `page.extract_content` for articles/documentation, or `page.get_text` for all visible UI text, instead of `dom.query` on body.
 17. **Network monitoring** - use `page.get_network` to inspect API calls; auto-installs interceptor.
 18. **Accessibility tree only when necessary** - `dom.get_accessibility_tree` is debugger-backed; use it when semantic structure cannot be inferred from DOM queries and role/text search.
 19. **Tailwind-aware** - when `page.get_state` returns `hints.tailwind: true`, load `references/tailwind.md`; avoid selecting by utility classes, prefer `find_by_text`/`find_by_role`; `dom.query` auto-escapes `[]` brackets.
+20. **Verify after input** - a dispatched DOM or CDP event does not prove application state changed. Follow it with the cheapest relevant wait or structured read.
+21. **Do not guess input targets** - for targeted click, focus, type, fill, press-key, checked-state, option-selection, hover, and drag calls, honor actionability errors and returned `resolution` metadata. `cdp_press_key` and `scroll_into_view` use separate contracts. `executionMode` is only `dom` or `cdp`; `input.fill.mode: auto` is a separate DOM setter/keystroke strategy.
+22. **Stale recovery stays opt-in** - prefer re-querying. Use `recoverStale: true` once only when the same document/URL and a strong unique semantic descriptor should still identify the target; inspect `recovered`, old/new refs, and matched fields. A scan with more than 100 same-tag candidates fails as `ELEMENT_AMBIGUOUS`/`scan_incomplete` because uniqueness is not provable.
+23. **Dialogs are explicit** - inspect first, then accept or dismiss only when intended. `expectedDialogId` is a pre-dispatch stale-decision check, not an atomic CDP binding; never auto-repeat `DIALOG_ACTION_CONFLICT`.
 
 ## Token Budget Quick Rules
 
@@ -172,7 +187,7 @@ Error responses now include a machine-readable `error.recovery` field with `retr
 2. **Use `attributeAllowlist`** - filter irrelevant attributes (e.g. `['class', 'href', 'data-testid']`)
 3. **Batch independent reads** - combine into a single `bbx batch` / `browser_batch` call
 4. **Refresh refs after pruning** - if `dom.query` returns `_registryPruned: true`, old refs may have been evicted; re-query before reusing them
-5. **Watch overflow counters** - `page.get_console` and `page.get_network` return `dropped` when hot pages overflow the 200-entry buffers
+5. **Watch overflow counters** - `page.get_console` and `page.get_network` return `dropped` when hot pages overflow the 200-entry buffers; CDP network also reports `abandoned` and capture lifecycle state
 
 ## Investigate Workflow
 
@@ -235,7 +250,8 @@ bbx page-text 2000                                  # extract page content
 | Inspect     | `dom.query`, `dom.describe`, `dom.get_html`, `styles.get_computed`, `layout.get_box_model`                                                          |
 | Find        | `dom.find_by_text`, `dom.find_by_role`, `dom.wait_for`, `dom.get_accessibility_tree`                                                                |
 | Page State  | `page.get_console`, `page.get_storage`, `page.get_text`, `page.wait_for_load_state`, `page.evaluate` (debugger-backed)                              |
-| Network     | `page.get_network`, `network.intercept.add/remove/list/clear` (debugger-backed; rules are in-memory and drop if the debugger detaches - verify with `list`) |
+| Dialogs     | `page.handle_dialog` (debugger-backed; explicit inspect/accept/dismiss only)                                                                  |
+| Network     | `page.get_network` (fetch/XHR default; optional CDP lifecycle), `network.intercept.add/remove/list/clear` (debugger-backed)                         |
 | Interact    | `input.click`, `input.type`, `input.fill`, `input.focus`, `input.press_key`, `cdp.dispatch_key_event`, `input.hover`, `input.drag`, `input.scroll_into_view` |
 | Tabs        | `tabs.list` (preferred), `tabs.create` (avoid unless necessary), `tabs.close`, `tabs.activate`                                                      |
 | Patch       | `patch.apply_styles`, `patch.apply_dom`, `patch.rollback`                                                                                           |
@@ -273,8 +289,8 @@ page.get_state → page.get_console(clear: true) + page.get_network(clear: true)
 
 ```
 dom.find_by_role('button', 'Login') → input.click
+  → page.wait_for_load_state({url: '/dashboard', urlMatch: 'contains', waitForLoad: false})
   → dom.wait_for('.dashboard', {state: 'visible', timeoutMs: 10000})
-  → page.get_state (verify URL changed)
   → page.get_console (check for errors)
   → dom.query('.dashboard', {maxNodes: 15}) (inspect result)
 ```
@@ -291,6 +307,8 @@ dom.find_by_role('button', 'Login') → input.click
 
 `bbx a11y-tree` and `dom.get_accessibility_tree` are sensitive to `maxDepth` and `maxNodes`. Shallow runs can undercount interactive nodes on real pages, so widen those limits before treating a low interactive count as a bug.
 
+For control discovery, prefer `compact: true` or `interactiveOnly: true`, then use role/name with `dom.find_by_role` to obtain an input ref. AX `interactive` means semantic/focusable, not currently visible, unobscured, or otherwise actionable; AX results are depth-limited partial topology and include truncation metadata even when `maxNodes` was not reached.
+
 > **MCP mode:** If Browser Bridge is connected via MCP (tools named `browser_dom`, `browser_capture`, etc.), use the MCP tools directly - do not shell out to `bbx`. The MCP tools map 1:1 to CLI capabilities. In prompts, `BB MCP` and `Browser Bridge MCP` both work. Do not treat `bbx-mcp` as a skill alias.
 >
 > For open-ended MCP inspection tasks, prefer `browser_investigate` first. It is read-only, designed for cheaper delegated investigation, and falls back to a deterministic sequence when the client cannot delegate. Escalate to `browser_capture` only when the structured investigation is not enough.
@@ -306,7 +324,7 @@ Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. U
 ## CLI Raw Params Gotchas
 
 - Use `selector`, not `scope`, to narrow `dom.find_by_text` and `dom.find_by_role`.
-- Wrap interaction targets as `target: { elementRef }` or `target: { selector }`; `viewport.scroll` also uses the `target` wrapper for element scrolling. **Do not pass `ref` or `elementRef` at the top level** -- interaction methods require the nested `target` wrapper:
+- Wrap targeted DOM input as `target: { elementRef }` or `target: { selector }`; `input.press_key` may omit the target to use the active element, `input.scroll_into_view` also accepts `target`, and `cdp.dispatch_key_event` targets the tab. **Do not pass `ref` or `elementRef` at the top level**:
   ```bash
   # CORRECT
   bbx call input.click '{"target":{"elementRef":"el_xxx"}}'
@@ -316,6 +334,9 @@ Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. U
   bbx call input.click '{"elementRef":"el_xxx"}'
   ```
 - `input.drag` uses `source`, `destination`, and optional destination offsets `offsetX` / `offsetY`.
+- `executionMode` accepts `dom` or `cdp` and defaults to `dom`; CDP supports only click, hover, drag, type, and fill. `input.fill.mode` (`auto`, `setter`, `keystrokes`) is a separate DOM strategy.
+- `page.get_network` defaults to low-cost fetch/XHR instrumentation. All-resource CDP capture must be armed before the activity with `source: "cdp", capture: "start"`, read later, and explicitly stopped.
+- `page.handle_dialog` mutations are not atomically bound to `expectedDialogId`; treat `commandDispatched` as dispatch evidence and verify follow-up state.
 - Raw `screenshot.capture_region` and `screenshot.capture_full_page` return base64 JSON; prefer `bbx screenshot <ref> [outPath]` when one element is enough.
 
 ## Response Shapes
@@ -324,7 +345,7 @@ The summarizer auto-detects response types and produces concise summaries:
 
 Shortcut commands intentionally expose only the common case. Use `bbx call <method> '{...}'` when you need method-specific fields that are not surfaced by a shortcut, such as `tabs.create.active`.
 
-`dom.query` results include `registrySize` and may include `_registryPruned: true` after element-ref eviction. `page.get_console` and `page.get_network` include `dropped` when older buffered entries were discarded.
+`dom.query` results include `registrySize` and may include `_registryPruned: true` after element-ref eviction. `page.get_console` and `page.get_network` include `dropped` when older buffered entries were discarded. Targeted click, focus, type, fill, press-key, checked-state, option-selection, hover, and drag results include bounded `resolution` and `execution` metadata; `cdp_press_key` and `scroll_into_view` use separate contracts.
 
 | Response Type    | Detection                        | Summary Format                                               |
 | ---------------- | -------------------------------- | ------------------------------------------------------------ |
@@ -338,7 +359,7 @@ Shortcut commands intentionally expose only the common case. Use `bbx call <meth
 | Element describe | `result.tag + elementRef + bbox` | `Element tag#id: text.`                                      |
 | Computed styles  | `result.properties + elementRef` | `Computed N style(s) for ref.`                               |
 | Box model        | `result.content + border`        | `Box model: W×H at (x, y).`                                  |
-| Network          | `entries[0].type=fetch/xhr`      | `Network: N requests.`                                       |
+| Network          | `result.source + entries`        | `Network: N requests.`                                       |
 | Console          | `entries` (no type field)        | `Console: N entries.`                                        |
 | Logs             | `entries[0].at + method`         | `Log: N entries.`                                            |
 | Patch apply      | `result.patchId`                 | `Patch id applied.`                                          |