@browserbridge/bbx 1.7.2 → 1.7.4

package/packages/protocol/src/registry.js

@@ -112,7 +112,7 @@ function createRegistryEntry(method, group, tab, params, complexity = 'low') {
 
 /** @type {Readonly<Record<import('./types.js').BridgeMethod, BridgeMethodRegistryEntry>>} */
 export const BRIDGE_METHOD_REGISTRY = Object.freeze({
-  // system — trivial
+  // system - trivial
   'access.request': createRegistryEntry('access.request', 'system', false, [], 'trivial'),
   'skill.get_runtime_context': createRegistryEntry(
     'skill.get_runtime_context',
@@ -126,18 +126,18 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'setup.install',
     'system',
     false,
-    ['kind', 'target'],
+    ['action', 'kind', 'target'],
     'trivial'
   ),
   'log.tail': createRegistryEntry('log.tail', 'system', false, ['limit'], 'trivial'),
   'health.ping': createRegistryEntry('health.ping', 'system', false, [], 'trivial'),
   'daemon.metrics': createRegistryEntry('daemon.metrics', 'system', false, [], 'trivial'),
-  // tabs — trivial
+  // tabs - trivial
   'tabs.list': createRegistryEntry('tabs.list', 'tabs', false, [], 'trivial'),
   'tabs.create': createRegistryEntry('tabs.create', 'tabs', false, ['url', 'active'], 'trivial'),
   'tabs.close': createRegistryEntry('tabs.close', 'tabs', false, ['tabId'], 'trivial'),
   'tabs.activate': createRegistryEntry('tabs.activate', 'tabs', false, ['tabId'], 'trivial'),
-  // page — low (basic reads), moderate (evaluate, debugger-backed)
+  // page - low (basic reads), moderate (evaluate, debugger-backed)
   'page.get_state': createRegistryEntry('page.get_state', 'page', true, [], 'low'),
   'page.evaluate': {
     ...createRegistryEntry(
@@ -177,7 +177,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['clear', 'limit', 'urlPattern'],
     'low'
   ),
-  // network intercept — moderate (holds debugger session)
+  // network intercept - moderate (holds debugger session)
   'network.intercept.add': createRegistryEntry(
     'network.intercept.add',
     'page',
@@ -206,7 +206,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     [],
     'low'
   ),
-  // navigation — low
+  // navigation - low
   'navigation.navigate': createRegistryEntry(
     'navigation.navigate',
     'navigate',
@@ -235,7 +235,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['waitForLoad', 'timeoutMs'],
     'low'
   ),
-  // dom — low (reads), moderate (accessibility tree)
+  // dom - low (reads), moderate (accessibility tree)
   'dom.query': {
     ...createRegistryEntry(
       'dom.query',
@@ -303,7 +303,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['maxNodes', 'maxDepth'],
     'moderate'
   ),
-  // layout — low
+  // layout - low
   'layout.get_box_model': createRegistryEntry(
     'layout.get_box_model',
     'inspect',
@@ -312,7 +312,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low'
   ),
   'layout.hit_test': createRegistryEntry('layout.hit_test', 'inspect', true, ['x', 'y'], 'low'),
-  // styles — low (computed), moderate (matched rules)
+  // styles - low (computed), moderate (matched rules)
   'styles.get_computed': createRegistryEntry(
     'styles.get_computed',
     'inspect',
@@ -327,7 +327,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['elementRef'],
     'moderate'
   ),
-  // viewport — low (scroll), moderate (resize, debugger-backed)
+  // viewport - low (scroll), moderate (resize, debugger-backed)
   'viewport.scroll': createRegistryEntry(
     'viewport.scroll',
     'navigate',
@@ -342,7 +342,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['width', 'height', 'deviceScaleFactor', 'reset'],
     'moderate'
   ),
-  // input — low (simple), moderate (drag)
+  // input - low (simple), moderate (drag)
   'input.click': createRegistryEntry(
     'input.click',
     'interact',
@@ -407,7 +407,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['target'],
     'low'
   ),
-  // capture — high (screenshots, CDP)
+  // capture - high (screenshots, CDP)
   'screenshot.capture_region': createRegistryEntry(
     'screenshot.capture_region',
     'capture',
@@ -429,7 +429,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     [],
     'high'
   ),
-  // patch — moderate (side effects)
+  // patch - moderate (side effects)
   'patch.apply_styles': createRegistryEntry(
     'patch.apply_styles',
     'patch',
@@ -453,7 +453,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     [],
     'low'
   ),
-  // cdp — high (raw protocol, large payloads)
+  // cdp - high (raw protocol, large payloads)
   'cdp.get_document': createRegistryEntry('cdp.get_document', 'cdp', true, [], 'high'),
   'cdp.get_dom_snapshot': createRegistryEntry('cdp.get_dom_snapshot', 'cdp', true, [], 'high'),
   'cdp.get_box_model': createRegistryEntry('cdp.get_box_model', 'cdp', true, ['nodeId'], 'high'),
@@ -471,7 +471,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['key', 'code', 'modifiers'],
     'moderate'
   ),
-  // performance — moderate (debugger-backed)
+  // performance - moderate (debugger-backed)
   'performance.get_metrics': createRegistryEntry(
     'performance.get_metrics',
     'performance',

package/packages/protocol/src/summary.js

@@ -2,6 +2,7 @@
 
 import {
   estimateSerializedPayloadCost,
+  getErrorRecovery,
   getCostClass,
   getProtocolVersion,
   serializeJsonPayload,
@@ -26,7 +27,8 @@ import {
  * @typedef {{
  *   ok: boolean,
  *   summary: string,
- *   evidence: unknown
+ *   evidence: unknown,
+ *   recovery?: import('./types.js').BridgeRecovery | null
  * }} BridgeSummary
  */
 
@@ -49,7 +51,7 @@ import {
  *   approxTokens: number,
  *   meta?: Record<string, unknown>,
  *   error: unknown,
- *   response: unknown
+ *   response?: unknown
  * }} BatchItemSummary
  */
 
@@ -164,14 +166,15 @@ function getMetaCostClass(meta, field) {
 export function summarizeBridgeResponse(response, method) {
   const protocolWarning = getProtocolWarning(response.meta);
   if (!response.ok) {
-    const hint = summarizeErrorHint(response.error.code);
+    const recovery = response.error.recovery ?? getErrorRecovery(response.error.code);
     return {
       ok: false,
       summary: appendProtocolWarning(
-        `${response.error.code}: ${response.error.message}${hint ? ` ${hint}` : ''}`,
+        `${response.error.code}: ${response.error.message}${recovery?.hint ? ` ${recovery.hint}` : ''}`,
         protocolWarning
       ),
       evidence: response.error.details ?? null,
+      recovery,
     };
   }
 
@@ -348,16 +351,38 @@ export function summarizeBridgeResponse(response, method) {
       }
       return entry;
     });
-    let label;
-    if (method === 'dom.find_by_text' || method === 'dom.find_by_role') {
-      label = 'Found';
-    } else {
-      label = 'DOM query returned';
+    const isFind = method === 'dom.find_by_text' || method === 'dom.find_by_role';
+    if (isFind) {
+      const count = typeof result.count === 'number' ? result.count : nodes.length;
+      const scanned = typeof result.scanned === 'number' ? result.scanned : null;
+      const truncated = result.truncated === true;
+      let summary;
+      if (count === 0) {
+        summary = truncated
+          ? `No matching elements returned; search stopped${scanned === null ? '' : ` after scanning ${scanned}`}.`
+          : 'No matching elements found.';
+      } else if (truncated) {
+        summary = `Found ${count} matching element(s); additional matches were omitted.`;
+      } else {
+        summary = `Found ${count} matching element(s)${scanned === null ? '' : ` after scanning ${scanned}`}.`;
+      }
+      return {
+        ok: true,
+        summary: appendProtocolWarning(summary, protocolWarning),
+        evidence: {
+          found: count > 0,
+          count,
+          scanned,
+          truncated,
+          truncationReason: result.truncationReason ?? null,
+          nodes: compact,
+        },
+      };
     }
     return {
       ok: true,
       summary: appendProtocolWarning(
-        `${label} ${nodes.length} element(s)${nodes.length > 15 ? '; showing first 15' : ''}.`,
+        `DOM query returned ${nodes.length} element(s)${nodes.length > 15 ? '; showing first 15' : ''}.`,
         protocolWarning
       ),
       evidence: compact,
@@ -666,9 +691,10 @@ export function summarizeBridgeResponse(response, method) {
 
 /**
  * @param {{ method: SummaryMethod, tabId: number | null, response: BridgeResponse, durationMs: number }} input
+ * @param {{ compact?: boolean }} [options]
  * @returns {BatchItemSummary}
  */
-export function summarizeBatchResponseItem({ method, tabId, response, durationMs }) {
+export function summarizeBatchResponseItem({ method, tabId, response, durationMs }, options = {}) {
   const summary = annotateBridgeSummary(summarizeBridgeResponse(response, method), response);
   return {
     method,
@@ -676,17 +702,18 @@ export function summarizeBatchResponseItem({ method, tabId, response, durationMs
     ...summary,
     durationMs,
     approxTokens: summary.transportTokens,
-    meta: response.meta,
+    meta: options.compact ? compactBatchMeta(response.meta) : response.meta,
     error: response.ok ? null : response.error,
-    response: response.ok ? response.result : null,
+    ...(options.compact ? {} : { response: response.ok ? response.result : null }),
   };
 }
 
 /**
  * @param {{ method: SummaryMethod, tabId: number | null, error: unknown, durationMs: number }} input
+ * @param {{ compact?: boolean }} [options]
  * @returns {BatchItemSummary}
  */
-export function summarizeBatchErrorItem({ method, tabId, error, durationMs }) {
+export function summarizeBatchErrorItem({ method, tabId, error, durationMs }, options = {}) {
   const message = error instanceof Error ? error.message : String(error);
   const response = /** @type {BridgeResponse} */ ({
     id: 'batch_error',
@@ -706,12 +733,30 @@ export function summarizeBatchErrorItem({ method, tabId, error, durationMs }) {
     ...summary,
     durationMs,
     approxTokens: 0,
-    meta: response.meta,
+    meta: options.compact ? compactBatchMeta(response.meta) : response.meta,
     error: response.error,
-    response: null,
+    ...(options.compact ? {} : { response: null }),
   };
 }
 
+/**
+ * @param {Record<string, unknown>} meta
+ * @returns {Record<string, unknown>}
+ */
+function compactBatchMeta(meta) {
+  /** @type {Record<string, unknown>} */
+  const compact = {};
+  for (const key of [
+    'protocol_version',
+    'protocol_warning',
+    'budget_truncated',
+    'continuation_hint',
+  ]) {
+    if (meta[key] !== undefined && meta[key] !== null) compact[key] = meta[key];
+  }
+  return compact;
+}
+
 /**
  * @param {unknown} value
  * @returns {Record<string, unknown>}
@@ -758,20 +803,6 @@ function truncateUrl(url) {
   }
 }
 
-/**
- * @param {string} code
- * @returns {string}
- */
-function summarizeErrorHint(code) {
-  if (code === 'ELEMENT_STALE') {
-    return 'Re-query the current page after navigation or DOM updates.';
-  }
-  if (code === 'RESULT_TRUNCATED') {
-    return 'Narrow the query or raise the relevant budget if more detail is required.';
-  }
-  return '';
-}
-
 /**
  * Check if an array looks like a list of patch entries.
  * Returns true for empty arrays when method context suggests patch.list.

package/packages/protocol/src/types.ts

@@ -140,6 +140,7 @@ export interface BridgeRecovery {
   hint: string;
   retry?: boolean;
   retryAfterMs?: number;
+  alternativeMethod?: string;
 }
 
 export interface BridgeFailure {
@@ -192,6 +193,7 @@ export interface TruncateResult {
 export interface DomQueryParams extends BudgetOptions {
   selector?: string;
   withinRef?: string | null;
+  budget?: BudgetOptions;
 }
 
 export interface NormalizedDomQuery extends BridgeParams {
@@ -200,6 +202,15 @@ export interface NormalizedDomQuery extends BridgeParams {
   budget: Budget;
 }
 
+export interface DomFindResult {
+  found: boolean;
+  nodes: Record<string, unknown>[];
+  count: number;
+  scanned: number;
+  truncated: boolean;
+  truncationReason: 'maxResults' | 'scanLimit' | null;
+}
+
 export interface StyleQueryParams {
   elementRef?: string;
   target?: InputTarget;

package/skills/browser-bridge/SKILL.md

@@ -5,7 +5,7 @@ description: 'Token-efficient Chrome tab inspection, interaction, and patching v
 
 # Browser Bridge
 
-Token-efficient Chrome tab inspection, interaction, and CSS/DOM patching through a local native-messaging bridge. Reads structured DOM, styles, layout, console, storage, network, and applies reversible patches — all from the real tab the user already has open.
+Token-efficient Chrome tab inspection, interaction, and CSS/DOM patching through a local native-messaging bridge. Reads structured DOM, styles, layout, console, storage, network, and applies reversible patches - all from the real tab the user already has open.
 
 This CLI skill is for agents that can run shell commands and where direct `bbx` control fits better than MCP tools: manual debugging, terminal reproduction, install/doctor flows, raw protocol access, or environments without MCP.
 
@@ -13,7 +13,7 @@ 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`, `bbx batch`) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient.
+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.
 
 ## CLI
 
@@ -154,12 +154,12 @@ Error responses now include a machine-readable `error.recovery` field with `retr
 6. **Rollback** - revert every patch before finishing unless user wants mutations kept.
 7. **Confirm scope** - `status` first; stop if no extension connection.
 8. **Screenshots last** - only when structured evidence is ambiguous; prefer `screenshot.capture_element`, then a tight `screenshot.capture_region`; use `screenshot.capture_full_page` only when document-level context matters.
-9. **Batch reads** - combine independent reads in one `batch` call (executes concurrently via Promise.all).
+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`.
-13. **Wait after change** - after editing source files or triggering navigation, use `dom.wait_for` or `page.wait_for_load_state` before inspecting.
-14. **Console after interaction** - call `page.get_console` after mutations to catch runtime errors early.
+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.
 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.
 17. **Network monitoring** - use `page.get_network` to inspect API calls; auto-installs interceptor.
@@ -218,8 +218,11 @@ bbx rollback patch_2                                # clean up
 ### Verify an API call
 
 ```bash
-bbx console error                                   # check for runtime errors
-bbx network 20                                      # inspect recent requests
+bbx call page.get_console '{"clear":true}'          # install + clear console capture
+bbx call page.get_network '{"clear":true}'          # install + clear network capture
+# reproduce the API action here
+bbx console error                                   # read newly captured runtime errors
+bbx network 20                                      # read newly captured requests
 bbx eval 'document.querySelector("#app").__vue__.$store.state.user'  # read framework state
 bbx page-text 2000                                  # extract page content
 ```
@@ -232,7 +235,7 @@ 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`) |
+| 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`) |
 | 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`                                                                                           |
@@ -249,7 +252,7 @@ When the user has a localhost dev server with watch/HMR:
 3. **Identify the problem** - use `styles.get_computed`, `dom.get_html`, or `page.get_console` for errors.
 4. **Prototype with patches** - `patch.apply_styles` / `patch.apply_dom` to verify the fix visually.
 5. **Edit source files** - modify the actual code in the agent's workspace.
-6. **Wait for HMR** - `dom.wait_for` with the selector that should change, or `page.wait_for_load_state`.
+6. **Wait for HMR** - use `dom.wait_for` for expected new text, a selector matching the changed attribute, or a detach/attach remount. Do not wait for `attached` on an unchanged selector that already exists.
 7. **Verify the change** - re-inspect the same area; compare with patch expectations.
 8. **Check for regressions** - `page.get_console` for new errors; scroll and inspect adjacent areas.
 9. **Rollback patches** - `patch.rollback` all temporary patches.
@@ -257,7 +260,8 @@ When the user has a localhost dev server with watch/HMR:
 ## Investigate-a-Bug Workflow
 
 ```
-page.get_state → page.get_console (check for errors)
+page.get_state → page.get_console(clear: true) + page.get_network(clear: true)
+  → reproduce the bug → page.get_console + page.get_network
   → dom.find_by_text('<error text>') or dom.query('<selector>')
   → styles.get_computed (check layout/visibility)
   → page.evaluate('document.querySelector(...).dataset') (read data attrs)
@@ -287,7 +291,7 @@ 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.
 
-> **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.
+> **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.
 

package/skills/browser-bridge/references/interaction.md

@@ -144,19 +144,22 @@ bbx call input.scroll_into_view '{"target":{"selector":"[data-testid=\"submit-bu
 ## Network Monitoring
 
 ```bash
-bbx network                     # recent requests
-bbx network 50                  # last 50
-bbx call page.get_network '{"limit":20,"clear":true}'
+bbx call page.get_console '{"clear":true}' # install capture and clear old console entries
+bbx call page.get_network '{"clear":true}' # install capture and clear old network entries
+# reproduce the interaction here
+bbx network 50                           # newly captured requests
+bbx console error                        # newly captured errors
 ```
 
 Each entry: `method`, `url`, `status`, `duration`, `initiator`.
 
 Typical workflow - debug API calls:
 
-1. `page.get_network` to see recent requests
-2. Filter by URL pattern or status code
-3. Cross-reference with `page.get_console` for errors
-4. Use `page.evaluate` to replay or inspect response data
+1. Prime and clear `page.get_console` and `page.get_network`
+2. Reproduce the interaction
+3. Read and filter `page.get_network` by URL pattern or status code
+4. Cross-reference with `page.get_console` for errors
+5. Use `page.evaluate` only if lighter evidence cannot expose the needed response state
 
 ## Network Interception
 
@@ -192,7 +195,7 @@ bbx call input.select_option '{"target":{"elementRef":"el_456"},"values":["us"]}
 
 Select by value, label, or index. Multiple values for multi-select.
 
-**Text fields — `fill` vs `type`:**
+**Text fields - `fill` vs `type`:**
 
 ```bash
 bbx fill el_123 hello@example.com        # set value instantly (preferred for forms)

package/skills/browser-bridge/references/protocol.md

@@ -27,7 +27,7 @@ The table below includes the legacy capability bucket for each method so agents
 - `-` means the method is global/system-scoped and was never gated by a former capability bucket.
 - Capability names are descriptive coverage labels only. Browser Bridge access is window-scoped now; there are no capability-scoped sessions.
 
-## All Methods (59)
+## All Methods (65)
 
 | #   | Method                             | Tab? | CDP? | Group       | Capability           | Notes                                                                   |
 | --- | ---------------------------------- | ---- | ---- | ----------- | -------------------- | ----------------------------------------------------------------------- |
@@ -44,7 +44,7 @@ The table below includes the legacy capability bucket for each method so agents
 | 11  | `page.get_state`                   | Yes  | -    | page        | `page.read`          | URL, readiness, focus, scroll, viewport                                 |
 | 12  | `page.evaluate`                    | Yes  | CDP  | page        | `page.evaluate`      | JS expression in page context; last resort                              |
 | 13  | `page.get_console`                 | Yes  | -    | page        | `page.read`          | Buffered console messages; filter by `level`, `limit`                   |
-| 14  | `page.wait_for_load_state`         | Yes  | -    | wait        | `page.read`          | Block until tab `complete`; `timeoutMs` capped 30 s                     |
+| 14  | `page.wait_for_load_state`         | Yes  | -    | wait        | `page.read`          | Block until tab `complete`; `timeoutMs` range 0.5-120 s                 |
 | 15  | `page.get_storage`                 | Yes  | -    | page        | `page.read`          | `localStorage`/`sessionStorage`; optional `keys`                        |
 | 16  | `page.get_text`                    | Yes  | -    | page        | `page.read`          | Full page text; `textBudget` limits size                                |
 | 17  | `page.get_network`                 | Yes  | -    | page        | `network.read`       | Intercepted fetch/XHR; `limit` entries                                  |
@@ -121,7 +121,7 @@ bbx access-request
 bbx call access.request
 ```
 
-If a tab-bound call returns `ACCESS_DENIED`, it also surfaces the Enable prompt automatically — so explicit `access.request` is optional but useful for proactive setup.
+If a tab-bound call returns `ACCESS_DENIED`, it also surfaces the Enable prompt automatically - so explicit `access.request` is optional but useful for proactive setup.
 
 If access is already pending for a window, do not call `access.request` again. Ask the user to click `Enable` for the requested window and wait for confirmation before continuing.
 
@@ -139,7 +139,9 @@ bbx call page.evaluate '{"expression":"await fetch(\"/api/health\").then(r=>r.js
 
 ### page.get_console
 
-Read buffered console output. The console interceptor is auto-installed on first call. Captures `log`, `warn`, `error`, `info`, `debug` plus uncaught exceptions and unhandled rejections.
+Read buffered console output. The console interceptor is auto-installed on first call. Captures `log`, `warn`, `error`, `info`, `debug` plus uncaught exceptions and unhandled rejections. `level` is a minimum severity, so `warn` includes errors, exceptions, and rejections; `exception` and `rejection` select only that exact stream.
+
+To capture a reproduction reliably, call it once with `clear: true` before triggering the event. This installs the interceptor and removes older entries. Reproduce the issue, then read again without `clear`.
 
 ```bash
 bbx console                    # all levels
@@ -180,7 +182,7 @@ If `_registryPruned` is true, refresh previously cached refs before reusing them
 
 ### dom.wait_for
 
-Wait for a DOM condition using MutationObserver + 250 ms polling fallback. Returns `{found, elementRef, duration}`.
+Wait for a DOM condition using MutationObserver + 250 ms polling fallback. A text-only wait searches all elements. `hidden` succeeds when no matching visible element remains, including when it is absent. Returns `{found, elementRef, duration}`.
 
 - `state`: `attached` (default), `detached`, `visible`, `hidden`
 - `text`: optional text content filter
@@ -285,6 +287,8 @@ bbx call page.get_text '{"textBudget":2000}'
 
 ### page.get_network
 
+The fetch/XHR interceptor is installed on the first call. Before reproducing a network issue, call `page.get_network` with `clear: true`, trigger the action, then read the buffer again without `clear` so the relevant request is not missed or erased.
+
 Read intercepted fetch/XHR requests. The interceptor is auto-installed on first call (via MAIN world script). Returns `{entries, count}` sorted newest-first.
 
 ```bash

package/skills/browser-bridge/references/token-efficiency.md

@@ -125,7 +125,7 @@ bbx network              # recent fetch/XHR entries
 bbx network 50           # last 50 entries
 ```
 
-The interceptor auto-installs on first call. Each entry shows `method`, `url`, `status`, `duration`. Use `clear: true` to reset the buffer.
+The interceptor auto-installs on first call. Before reproducing an event, call `page.get_network` once with `clear: true` to install capture and remove old entries. Trigger the action, then read again without `clear`. Each entry shows `method`, `url`, `status`, `duration`.
 
 ## Accessibility Tree for Semantic Discovery
 
@@ -151,12 +151,13 @@ bbx find-role navigation  # semantic, works regardless of classes
 
 ## HMR-Aware Waiting
 
-After modifying source code, the dev server hot-reloads. Always wait before inspecting:
+After modifying source code, the dev server hot-reloads. Wait for evidence of the change, not `attached` on a selector that already exists:
 
 ```bash
-bbx wait '[data-component="Header"]' 5000   # wait for component re-mount
+bbx call dom.wait_for '{"selector":"[data-component=\"Header\"][data-version=\"new\"]","state":"attached","timeoutMs":5000}'
+bbx call dom.wait_for '{"selector":"[data-component=\"Header\"]","text":"Expected new heading","timeoutMs":5000}'
+# For a known remount, wait for detached and then attached states.
 bbx console error                            # check for HMR errors
-bbx eval 'module.hot?.status?.()'            # check HMR status (webpack)
 ```
 
 ## Parent-Agent Response Policy

package/skills/browser-bridge/references/ui-workflows.md

@@ -9,7 +9,7 @@ Use when a dev server is already running and you want to prove a fix rendered.
 3. `styles.get_computed` or `layout.get_box_model`
 4. `patch.apply_styles` to prove the visual fix
 5. Edit source files
-6. `dom.wait_for` on the component selector
+6. `dom.wait_for` for expected new text, a selector matching a changed attribute, or a detach/attach remount; do not wait for `attached` on an unchanged selector
 7. `page.get_console`
 8. `patch.rollback`
 
@@ -23,12 +23,14 @@ Acceptance:
 
 Use when a submission flow fails silently or the UI state is inconsistent.
 
-1. `dom.find_by_role` for the form control
-2. `input.type` / `input.click`
-3. `page.get_network`
-4. `page.get_console`
-5. `dom.wait_for` for success or error state
-6. `dom.query` on the resulting panel or message
+1. `page.get_console` with `clear: true` to install and clear console capture
+2. `page.get_network` with `clear: true` to install and clear network capture
+3. `dom.find_by_role` for the form control
+4. `input.type` / `input.click` to reproduce the issue
+5. `page.get_network` without `clear`
+6. `page.get_console` without `clear`
+7. `dom.wait_for` for success or error state
+8. `dom.query` on the resulting panel or message
 
 Acceptance:
 
@@ -60,7 +62,7 @@ Use when a component only breaks at a specific breakpoint.
 
 1. `page.get_state`
 2. `viewport.resize`
-3. `dom.wait_for`
+3. `dom.wait_for` for the expected responsive text, attribute selector, visibility change, or remount
 4. `layout.get_box_model`
 5. `styles.get_computed`
 6. `page.get_console`
@@ -87,7 +89,7 @@ Drag:
 
 1. `dom.query` for source and destination
 2. `input.drag`
-3. `dom.wait_for`
+3. `dom.wait_for` for expected changed text, attribute selector, or a detach/attach remount
 4. `dom.query` to verify order or placement
 
 Acceptance: