@browserbridge/bbx 1.7.1 → 1.7.3

package/packages/native-host/src/daemon.js

@@ -20,12 +20,14 @@ import {
   createFailure,
   createSuccess,
   DAEMON_EXISTING_SOCKET_PING_TIMEOUT_MS,
+  DAEMON_PENDING_TIMEOUT_MARGIN_MS,
   DAEMON_RECENT_LOG_LIMIT,
   DEFAULT_DAEMON_PENDING_TIMEOUT_MS,
   DEFAULT_LOG_TAIL_LIMIT,
   ERROR_CODES,
   getProtocolVersion,
   getSupportedProtocolVersions,
+  MAX_DAEMON_PENDING_TIMEOUT_MS,
   parseJsonLines,
   setProtocolPackageVersion,
   validateBridgeRequest,
@@ -54,7 +56,8 @@ setProtocolPackageVersion(DAEMON_VERSION);
 /** @typedef {import('../../protocol/src/types.js').SetupStatus} SetupStatus */
 /** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
 /** @typedef {import('./daemon-logger.js').DaemonLoggerLike} DaemonLoggerLike */
-/** @typedef {import('node:net').Socket & { __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __accessEnabled?: boolean, __lastActiveAt?: number, __authenticated?: boolean }} ClientSocket */
+/** @typedef {'agent' | 'extension'} SocketRole */
+/** @typedef {import('node:net').Socket & { readonly __role?: SocketRole, __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __accessEnabled?: boolean, __lastActiveAt?: number }} ClientSocket */
 /** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, method?: string, protocolVersion?: string, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
 /**
  * @typedef {{
@@ -327,6 +330,17 @@ export class BridgeDaemon {
    * @returns {void}
    */
   registerSocket(socket, message) {
+    if (socket.__role) {
+      void writeJsonLine(socket, {
+        type: 'registration_failed',
+        error: {
+          code: ERROR_CODES.INVALID_REQUEST,
+          message: `Socket is already registered as ${socket.__role}.`,
+        },
+      });
+      return;
+    }
+
     if (this.isAuthRequired() && normalizeBridgeAuthToken(message.authToken) !== this.authToken) {
       this.logger.error('socket registration rejected', { role: message.role ?? null });
       void writeJsonLine(socket, {
@@ -339,8 +353,24 @@ export class BridgeDaemon {
       return;
     }
 
+    if (message.role !== 'extension' && message.role !== 'agent') {
+      void writeJsonLine(socket, {
+        type: 'registration_failed',
+        error: {
+          code: ERROR_CODES.INVALID_REQUEST,
+          message: 'Socket role must be "agent" or "extension".',
+        },
+      });
+      return;
+    }
+
+    Object.defineProperty(socket, '__role', {
+      value: message.role,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
     if (message.role === 'extension') {
-      socket.__authenticated = true;
       const extensionId = randomUUID();
       socket.__extensionId = extensionId;
       socket.__browserName =
@@ -360,7 +390,6 @@ export class BridgeDaemon {
     }
 
     if (message.role === 'agent') {
-      socket.__authenticated = true;
       const clientId = message.clientId || randomUUID();
       this.agentSockets.set(clientId, socket);
       socket.__clientId = clientId;
@@ -524,36 +553,59 @@ export class BridgeDaemon {
       return this.registerSocket(socket, message);
     }
 
-    if (this.isAuthRequired() && !socket.__authenticated) {
-      return this.rejectUnauthenticatedMessage(socket, message);
+    if (!socket.__role) {
+      return this.rejectUnregisteredMessage(socket, message);
     }
 
     if (message?.type === 'log') {
+      if (socket.__role !== 'extension') {
+        return this.rejectMessageForRole(socket, message);
+      }
       this.pushLog(message.entry ?? {});
       return;
     }
 
     if (message?.type === 'extension.response') {
+      if (socket.__role !== 'extension') {
+        return this.rejectMessageForRole(socket, message);
+      }
       return this.handleExtensionResponse(socket, message);
     }
 
     if (message?.type === 'extension.identity') {
+      if (socket.__role !== 'extension') {
+        return this.rejectMessageForRole(socket, message);
+      }
       return this.handleExtensionIdentity(socket, message);
     }
 
     if (message?.type === 'extension.access_update') {
+      if (socket.__role !== 'extension') {
+        return this.rejectMessageForRole(socket, message);
+      }
       return this.handleExtensionAccessUpdate(socket, message);
     }
 
     if (message?.type === 'extension.activity') {
+      if (socket.__role !== 'extension') {
+        return this.rejectMessageForRole(socket, message);
+      }
       return this.handleExtensionActivity(socket, message);
     }
 
     if (message?.type === 'extension.setup_status.request') {
+      if (socket.__role !== 'extension') {
+        return this.rejectMessageForRole(socket, message);
+      }
       return this.handleExtensionSetupStatus(socket, message);
     }
 
     if (message?.type === 'agent.request') {
+      const isExtensionSetupRequest =
+        socket.__role === 'extension' && message.request?.method === 'setup.install';
+      if (socket.__role !== 'agent' && !isExtensionSetupRequest) {
+        return this.rejectMessageForRole(socket, message);
+      }
       return this.handleAgentRequest(socket, message);
     }
 
@@ -571,7 +623,8 @@ export class BridgeDaemon {
    * @param {DaemonMessage} message
    * @returns {Promise<void>}
    */
-  async rejectUnauthenticatedMessage(socket, message) {
+  async rejectUnregisteredMessage(socket, message) {
+    const authRequired = this.isAuthRequired();
     if (message?.type === 'agent.request') {
       const candidate =
         message.request && typeof message.request === 'object'
@@ -579,8 +632,10 @@ export class BridgeDaemon {
           : {};
       const response = createFailure(
         typeof candidate.id === 'string' && candidate.id.trim() ? candidate.id : 'unauthenticated',
-        ERROR_CODES.ACCESS_DENIED,
-        'Register with the daemon auth token before sending bridge requests.',
+        authRequired ? ERROR_CODES.ACCESS_DENIED : ERROR_CODES.INVALID_REQUEST,
+        authRequired
+          ? 'Register with the daemon auth token before sending bridge requests.'
+          : 'Register the socket before sending bridge requests.',
         null,
         typeof candidate.method === 'string' ? { method: candidate.method } : {}
       );
@@ -591,8 +646,25 @@ export class BridgeDaemon {
     await writeJsonLine(socket, {
       type: 'error',
       error: {
-        code: ERROR_CODES.ACCESS_DENIED,
-        message: 'Register with the daemon auth token before sending bridge messages.',
+        code: authRequired ? ERROR_CODES.ACCESS_DENIED : ERROR_CODES.INVALID_REQUEST,
+        message: authRequired
+          ? 'Register with the daemon auth token before sending bridge messages.'
+          : 'Register the socket before sending bridge messages.',
+      },
+    });
+  }
+
+  /**
+   * @param {ClientSocket} socket
+   * @param {DaemonMessage} message
+   * @returns {Promise<void>}
+   */
+  async rejectMessageForRole(socket, message) {
+    await writeJsonLine(socket, {
+      type: 'error',
+      error: {
+        code: ERROR_CODES.INVALID_REQUEST,
+        message: `Message type ${JSON.stringify(message.type ?? null)} is not allowed for ${socket.__role} sockets.`,
       },
     });
   }
@@ -690,6 +762,17 @@ export class BridgeDaemon {
     }
 
     if (request.method === 'setup.install') {
+      if (socket.__role === 'agent' && !this.isLocalSocket(socket)) {
+        const response = createFailure(
+          request.id,
+          ERROR_CODES.ACCESS_DENIED,
+          'setup.install is restricted to local Browser Bridge clients.',
+          null,
+          { method: request.method }
+        );
+        await writeJsonLine(socket, { type: 'agent.response', response });
+        return;
+      }
       try {
         const response = createSuccess(
           request.id,
@@ -718,40 +801,9 @@ export class BridgeDaemon {
       typeof request.meta?.target_profile === 'string' ? request.meta.target_profile : null;
     const hasExplicitTarget = Boolean(targetBrowser || targetProfile);
 
-    /** @type {ClientSocket[]} */
-    const targets = [];
-    /** @type {ClientSocket | null} */
-    let mostRecent = null;
-    for (const extSocket of this.extensionSockets.values()) {
-      if (targetBrowser || targetProfile) {
-        if (targetBrowser && extSocket.__browserName !== targetBrowser) {
-          continue;
-        }
-        if (targetProfile && extSocket.__profileLabel !== targetProfile) {
-          continue;
-        }
-        targets.push(extSocket);
-        continue;
-      }
-
-      if (extSocket.__accessEnabled) {
-        targets.push(extSocket);
-        continue;
-      }
-
-      if (
-        !mostRecent ||
-        (typeof extSocket.__lastActiveAt === 'number' ? extSocket.__lastActiveAt : 0) >
-          (typeof mostRecent.__lastActiveAt === 'number' ? mostRecent.__lastActiveAt : 0)
-      ) {
-        mostRecent = extSocket;
-      }
-    }
-    if (!hasExplicitTarget && targets.length === 0 && mostRecent) {
-      targets.push(mostRecent);
-    }
+    const target = this.selectExtensionTarget(targetBrowser, targetProfile);
 
-    if (targets.length === 0) {
+    if (!target) {
       const response = createFailure(
         request.id,
         ERROR_CODES.EXTENSION_DISCONNECTED,
@@ -768,7 +820,7 @@ export class BridgeDaemon {
       method: request.method,
       protocolVersion: request.meta?.protocol_version,
       source: typeof request.meta?.source === 'string' ? request.meta.source : '',
-      targets: new Set(targets),
+      targets: new Set([target]),
       timeoutId: setTimeout(() => {
         const pending = this.pendingRequests.get(request.id);
         if (!pending) return;
@@ -789,38 +841,101 @@ export class BridgeDaemon {
             message: error instanceof Error ? error.message : String(error),
           });
         });
-      }, this.pendingTimeoutMs),
+      }, this.getPendingTimeoutMs(request)),
     });
     this.logger.info('request routed', {
       requestId: request.id,
       method: request.method,
       clientId: socket.__clientId ?? null,
-      targetCount: targets.length,
+      targetCount: 1,
     });
-    const broadcastPayload = { type: 'extension.request', request };
-    await Promise.all(
-      targets.map(async (extSocket) => {
-        try {
-          await writeJsonLine(extSocket, broadcastPayload);
-        } catch (error) {
-          this.logger.error('request route failed', {
-            requestId: request.id,
-            method: request.method,
-            message: error instanceof Error ? error.message : String(error),
-          });
-          const pending = this.pendingRequests.get(request.id);
-          if (!pending) {
-            return;
-          }
-          this.removePendingTarget(request.id, pending, extSocket);
-          if (extSocket.__extensionId) {
-            this.extensionSockets.delete(extSocket.__extensionId);
-            this.invalidateConnectedExtensionsCache();
-          }
-          extSocket.destroy(error instanceof Error ? error : undefined);
-          await this.finishPendingRequestIfExhausted(request.id, pending);
-        }
-      })
+    try {
+      await writeJsonLine(target, { type: 'extension.request', request });
+    } catch (error) {
+      this.logger.error('request route failed', {
+        requestId: request.id,
+        method: request.method,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      const pending = this.pendingRequests.get(request.id);
+      if (!pending) {
+        return;
+      }
+      this.removePendingTarget(request.id, pending, target);
+      if (target.__extensionId && this.extensionSockets.get(target.__extensionId) === target) {
+        this.extensionSockets.delete(target.__extensionId);
+        this.invalidateConnectedExtensionsCache();
+      }
+      target.destroy(error instanceof Error ? error : undefined);
+      await this.finishPendingRequestIfExhausted(request.id, pending);
+    }
+  }
+
+  /**
+   * @param {ClientSocket} socket
+   * @returns {boolean}
+   */
+  isLocalSocket(socket) {
+    if (this.transport.type === 'socket') {
+      return true;
+    }
+    const address = socket.remoteAddress ?? '';
+    return (
+      address === '127.0.0.1' ||
+      address === '::1' ||
+      address === 'localhost' ||
+      address === '::ffff:127.0.0.1'
+    );
+  }
+
+  /**
+   * Select from a snapshot so routing neither mutates nor observes mutations to
+   * the live extension map while candidates are ordered.
+   *
+   * @param {string | null} targetBrowser
+   * @param {string | null} targetProfile
+   * @returns {ClientSocket | null}
+   */
+  selectExtensionTarget(targetBrowser, targetProfile) {
+    const candidates = Array.from(this.extensionSockets.entries()).filter(([, extSocket]) => {
+      return (
+        (!targetBrowser || extSocket.__browserName === targetBrowser) &&
+        (!targetProfile || extSocket.__profileLabel === targetProfile)
+      );
+    });
+    candidates.sort(([leftId, left], [rightId, right]) => {
+      const accessDelta =
+        Number(Boolean(right.__accessEnabled)) - Number(Boolean(left.__accessEnabled));
+      if (accessDelta !== 0) {
+        return accessDelta;
+      }
+      const activityDelta =
+        (typeof right.__lastActiveAt === 'number' ? right.__lastActiveAt : 0) -
+        (typeof left.__lastActiveAt === 'number' ? left.__lastActiveAt : 0);
+      if (activityDelta !== 0) {
+        return activityDelta;
+      }
+      return leftId < rightId ? -1 : leftId > rightId ? 1 : 0;
+    });
+    return candidates[0]?.[1] ?? null;
+  }
+
+  /**
+   * @param {BridgeRequest} request
+   * @returns {number}
+   */
+  getPendingTimeoutMs(request) {
+    const configuredBase = Math.min(
+      MAX_DAEMON_PENDING_TIMEOUT_MS,
+      Math.max(1, this.pendingTimeoutMs)
+    );
+    const operationTimeout = request.params.timeoutMs;
+    if (typeof operationTimeout !== 'number' || !Number.isFinite(operationTimeout)) {
+      return configuredBase;
+    }
+    return Math.min(
+      MAX_DAEMON_PENDING_TIMEOUT_MS,
+      Math.max(configuredBase, operationTimeout + DAEMON_PENDING_TIMEOUT_MARGIN_MS)
     );
   }
 
@@ -922,7 +1037,7 @@ export class BridgeDaemon {
     }
 
     const pending = this.pendingRequests.get(responseMessage.id);
-    if (!pending) {
+    if (!pending || !pending.targets.has(socket)) {
       return;
     }
 
@@ -968,7 +1083,7 @@ export class BridgeDaemon {
       return;
     }
 
-    // Error response — wait for other extensions before forwarding.
+    // A routed request has one target, so its error is final.
     pending.lastErrorResponse = responseMessage;
 
     await this.finishPendingRequestIfExhausted(responseMessage.id, pending);
@@ -981,8 +1096,10 @@ export class BridgeDaemon {
   handleSocketClose(socket) {
     if (socket.__extensionId) {
       this.logger.info('extension disconnected', { extensionId: socket.__extensionId });
-      this.extensionSockets.delete(socket.__extensionId);
-      this.invalidateConnectedExtensionsCache();
+      if (this.extensionSockets.get(socket.__extensionId) === socket) {
+        this.extensionSockets.delete(socket.__extensionId);
+        this.invalidateConnectedExtensionsCache();
+      }
     }
 
     if (socket.__clientId) {
@@ -1151,11 +1268,14 @@ export async function pingExistingDaemon(transport) {
     });
 
     socket.once('connect', () => {
-      if (authToken) {
-        socket.write(
-          `${JSON.stringify({ type: 'register', role: 'agent', clientId: 'ping_probe', authToken })}\n`
-        );
-      }
+      socket.write(
+        `${JSON.stringify({
+          type: 'register',
+          role: 'agent',
+          clientId: 'ping_probe',
+          ...(authToken ? { authToken } : {}),
+        })}\n`
+      );
       socket.write(
         `${JSON.stringify({
           type: 'agent.request',

package/packages/protocol/src/defaults.js

@@ -30,9 +30,21 @@ export const MAX_JSON_LINE_BYTES = MAX_NATIVE_MESSAGE_BYTES;
 /** Default timeout for a bridge request awaiting an extension response (ms). */
 export const DEFAULT_DAEMON_PENDING_TIMEOUT_MS = 30_000;
 
+/** Transport allowance added after an operation's own normalized timeout. */
+export const DAEMON_PENDING_TIMEOUT_MARGIN_MS = 2_000;
+
+/** Upper bound for a daemon request awaiting an extension response. */
+export const MAX_DAEMON_PENDING_TIMEOUT_MS = 122_000;
+
 /** Default timeout for a BridgeClient request (ms). */
 export const DEFAULT_CLIENT_REQUEST_TIMEOUT_MS = 8_000;
 
+/** Transport allowance added after an operation timeout on the client side. */
+export const CLIENT_REQUEST_TIMEOUT_MARGIN_MS = 4_000;
+
+/** Upper bound for a client request, kept beyond the daemon's maximum deadline. */
+export const MAX_CLIENT_REQUEST_TIMEOUT_MS = 124_000;
+
 /** Maximum number of recent log entries retained by the daemon. */
 export const DAEMON_RECENT_LOG_LIMIT = 200;
 
@@ -64,6 +76,11 @@ export const DEBUGGER_BACKED_METHODS = new Set([
   'performance.get_metrics',
   'screenshot.capture_element',
   'screenshot.capture_region',
+  'screenshot.capture_full_page',
+  'network.intercept.add',
+  'network.intercept.remove',
+  'network.intercept.list',
+  'network.intercept.clear',
   'cdp.get_document',
   'cdp.get_dom_snapshot',
   'cdp.get_box_model',

package/packages/protocol/src/protocol.js

@@ -271,7 +271,23 @@ export function validateBridgeRequest(request) {
   ) {
     throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Request params must be an object.');
   }
-  const parsedTabId = Number(candidate.tab_id);
+  const hasTabId = Object.hasOwn(candidate, 'tab_id');
+  const candidateTabId = candidate.tab_id;
+  /** @type {number | null} */
+  let tabId = null;
+  if (hasTabId && candidateTabId !== null) {
+    if (
+      typeof candidateTabId !== 'number' ||
+      !Number.isSafeInteger(candidateTabId) ||
+      candidateTabId <= 0
+    ) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        'Request tab_id must be null or a positive safe integer.'
+      );
+    }
+    tabId = candidateTabId;
+  }
 
   const method = /** @type {BridgeMethod} */ (candidate.method);
   const params =
@@ -282,7 +298,7 @@ export function validateBridgeRequest(request) {
   return {
     id: candidate.id,
     method,
-    tab_id: Number.isFinite(parsedTabId) && parsedTabId > 0 ? parsedTabId : null,
+    tab_id: tabId,
     params: normalizeRequestParams(method, params),
     meta: {
       ...meta,
@@ -375,6 +391,33 @@ function normalizeRequestParams(method, params) {
   }
 }
 
+/**
+ * Return the browser-operation timeout for methods that wait asynchronously.
+ * This lets clients and the daemon keep transport deadlines outside the
+ * normalized operation deadline, including when callers omit timeoutMs.
+ *
+ * @param {BridgeMethod} method
+ * @param {Record<string, unknown>} [params={}]
+ * @returns {number | null}
+ */
+export function getBridgeOperationTimeoutMs(method, params = {}) {
+  switch (method) {
+    case 'navigation.navigate':
+    case 'navigation.reload':
+    case 'navigation.go_back':
+    case 'navigation.go_forward':
+      return normalizeNavigationAction(params).timeoutMs;
+    case 'page.wait_for_load_state':
+      return normalizeWaitForLoadStateParams(params).timeoutMs;
+    case 'page.evaluate':
+      return normalizeEvaluateParams(params).timeoutMs;
+    case 'dom.wait_for':
+      return normalizeWaitForParams(params).timeoutMs;
+    default:
+      return null;
+  }
+}
+
 /**
  * @param {DomQueryParams} [params={}]
  * @returns {NormalizedDomQuery}

package/packages/protocol/src/registry.js

@@ -126,7 +126,7 @@ 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'),

package/skills/browser-bridge/SKILL.md

@@ -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
 ```
@@ -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)

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