@browserbridge/bbx 1.7.3 → 1.7.5

package/packages/protocol/src/protocol.js

@@ -6,12 +6,14 @@ import {
   DEFAULT_A11Y_MAX_DEPTH,
   DEFAULT_A11Y_MAX_NODES,
   DEFAULT_CONSOLE_LIMIT,
+  DEFAULT_DEVICE_SCALE_FACTOR,
   DEFAULT_EVAL_TIMEOUT_MS,
   DEFAULT_LOG_TAIL_LIMIT,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_HTML_LENGTH,
   DEFAULT_MAX_NODES,
   DEFAULT_NAV_TIMEOUT_MS,
+  DEFAULT_NETWORK_INTERCEPT_ACTION,
   DEFAULT_NETWORK_LIMIT,
   DEFAULT_PAGE_TEXT_BUDGET,
   DEFAULT_TEXT_BUDGET,
@@ -42,6 +44,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').InputActionParams} InputActionParams */
 /** @typedef {import('./types.js').LogTailParams} LogTailParams */
 /** @typedef {import('./types.js').NavigationActionParams} NavigationActionParams */
+/** @typedef {import('./types.js').NetworkInterceptAddParams} NetworkInterceptAddParams */
 /** @typedef {import('./types.js').NetworkParams} NetworkParams */
 /** @typedef {import('./types.js').NormalizedAccessibilityTreeParams} NormalizedAccessibilityTreeParams */
 /** @typedef {import('./types.js').NormalizedCheckedAction} NormalizedCheckedAction */
@@ -58,6 +61,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').NormalizedInputAction} NormalizedInputAction */
 /** @typedef {import('./types.js').NormalizedLogTailParams} NormalizedLogTailParams */
 /** @typedef {import('./types.js').NormalizedNavigationAction} NormalizedNavigationAction */
+/** @typedef {import('./types.js').NormalizedNetworkInterceptAddParams} NormalizedNetworkInterceptAddParams */
 /** @typedef {import('./types.js').NormalizedNetworkParams} NormalizedNetworkParams */
 /** @typedef {import('./types.js').NormalizedPageTextParams} NormalizedPageTextParams */
 /** @typedef {import('./types.js').NormalizedPatchOperation} NormalizedPatchOperation */
@@ -151,6 +155,30 @@ function clampInt(value, min, max, fallback) {
   return Math.min(Math.max(integer, min), max);
 }
 
+/**
+ * Clamp a finite number without discarding its fractional component.
+ *
+ * @param {unknown} value
+ * @param {number} min
+ * @param {number} max
+ * @param {number} fallback
+ * @returns {number}
+ */
+function clampNumber(value, min, max, fallback) {
+  const numeric = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  return Math.min(Math.max(numeric, min), max);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
 /** @type {ReadonlyArray<BridgeMethod>} */
 export const METHODS = BRIDGE_METHODS;
 
@@ -336,6 +364,8 @@ function normalizeRequestParams(method, params) {
       return normalizePageTextParams(params);
     case 'page.get_network':
       return normalizeNetworkParams(params);
+    case 'network.intercept.add':
+      return normalizeNetworkInterceptAddParams(params);
     case 'navigation.navigate':
     case 'navigation.reload':
     case 'navigation.go_back':
@@ -361,6 +391,7 @@ function normalizeRequestParams(method, params) {
     case 'input.click':
     case 'input.focus':
     case 'input.type':
+    case 'input.fill':
     case 'input.press_key':
       return normalizeInputAction(params);
     case 'cdp.dispatch_key_event':
@@ -412,7 +443,7 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
     case 'page.evaluate':
       return normalizeEvaluateParams(params).timeoutMs;
     case 'dom.wait_for':
-      return normalizeWaitForParams(params).timeoutMs;
+      return clampInt(params.timeoutMs, 100, 30_000, 5_000);
     default:
       return null;
   }
@@ -423,11 +454,13 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
  * @returns {NormalizedDomQuery}
  */
 export function normalizeDomQuery(params = {}) {
+  const nestedBudget =
+    params.budget && typeof params.budget === 'object' ? params.budget : undefined;
   return {
     selector:
       typeof params.selector === 'string' && params.selector.trim() ? params.selector : 'body',
     withinRef: typeof params.withinRef === 'string' ? params.withinRef : null,
-    budget: applyBudget(params),
+    budget: applyBudget({ ...nestedBudget, ...params }),
   };
 }
 
@@ -640,7 +673,7 @@ export function normalizeNavigationAction(params = {}) {
   return {
     url,
     waitForLoad: params.waitForLoad !== false,
-    timeoutMs: clampInt(params.timeoutMs, 500, 120_000, 15_000),
+    timeoutMs: clampInt(params.timeoutMs, 500, 120_000, DEFAULT_NAV_TIMEOUT_MS),
   };
 }
 
@@ -679,11 +712,17 @@ export function normalizeEvaluateParams(params = {}) {
       `Expression too large (${expression.length} chars). Maximum is 100,000.`
     );
   }
+  if (params.returnByValue === false) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'returnByValue=false is not supported because remote CDP objects cannot be consumed.'
+    );
+  }
   return {
     expression,
     awaitPromise: Boolean(params.awaitPromise),
-    timeoutMs: clampInt(params.timeoutMs, 100, 30_000, 5_000),
-    returnByValue: params.returnByValue !== false,
+    timeoutMs: clampInt(params.timeoutMs, 100, 30_000, DEFAULT_EVAL_TIMEOUT_MS),
+    returnByValue: true,
   };
 }
 
@@ -706,9 +745,18 @@ export function normalizeConsoleParams(params = {}) {
  */
 export function normalizeWaitForParams(params = {}) {
   const validStates = ['attached', 'detached', 'visible', 'hidden'];
+  const selector =
+    typeof params.selector === 'string' && params.selector.trim() ? params.selector : '';
+  const text = typeof params.text === 'string' && params.text.trim() ? params.text : null;
+  if (!selector && text === null) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'selector or text is required for dom.wait_for.'
+    );
+  }
   return {
-    selector: typeof params.selector === 'string' && params.selector.trim() ? params.selector : '',
-    text: params.text != null ? String(params.text) : null,
+    selector: selector || '*',
+    text,
     state: validStates.includes(String(params.state ?? ''))
       ? /** @type {'attached' | 'detached' | 'visible' | 'hidden'} */ (String(params.state))
       : 'attached',
@@ -817,7 +865,7 @@ export function normalizeStorageParams(params = {}) {
 export function normalizeWaitForLoadStateParams(params = {}) {
   return {
     waitForLoad: params.waitForLoad !== false,
-    timeoutMs: clampInt(params.timeoutMs, 500, 120_000, 15_000),
+    timeoutMs: clampInt(params.timeoutMs, 500, 120_000, DEFAULT_NAV_TIMEOUT_MS),
   };
 }
 
@@ -886,6 +934,71 @@ export function normalizeNetworkParams(params = {}) {
   };
 }
 
+/**
+ * @param {NetworkInterceptAddParams} [params={}]
+ * @returns {NormalizedNetworkInterceptAddParams}
+ */
+export function normalizeNetworkInterceptAddParams(params = {}) {
+  if (typeof params.urlPattern !== 'string' || !params.urlPattern) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'urlPattern is required.');
+  }
+
+  const action = params.action ?? DEFAULT_NETWORK_INTERCEPT_ACTION;
+  if (action !== 'fulfill' && action !== 'continue' && action !== 'block') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'action must be one of fulfill, continue, or block.'
+    );
+  }
+  if (
+    params.statusCode !== undefined &&
+    (!Number.isInteger(params.statusCode) || params.statusCode < 100 || params.statusCode > 599)
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'statusCode must be an integer between 100 and 599.'
+    );
+  }
+  if (params.body !== undefined && typeof params.body !== 'string') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'body must be a string.');
+  }
+
+  /** @type {Record<string, string> | undefined} */
+  let headers;
+  if (params.headers !== undefined) {
+    if (!isPlainRecord(params.headers)) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        'headers must be an object containing string values.'
+      );
+    }
+    headers = {};
+    for (const [name, value] of Object.entries(params.headers)) {
+      if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)) {
+        throw new BridgeError(
+          ERROR_CODES.INVALID_REQUEST,
+          `Invalid header name: ${name || '(empty)'}.`
+        );
+      }
+      if (typeof value !== 'string' || /[\r\n]/.test(value)) {
+        throw new BridgeError(
+          ERROR_CODES.INVALID_REQUEST,
+          `Header ${name} must have a string value without newlines.`
+        );
+      }
+      headers[name] = value;
+    }
+  }
+
+  return {
+    urlPattern: params.urlPattern,
+    action,
+    ...(params.statusCode === undefined ? {} : { statusCode: params.statusCode }),
+    ...(params.body === undefined ? {} : { body: params.body }),
+    ...(headers === undefined ? {} : { headers }),
+  };
+}
+
 /**
  * @param {PageTextParams} [params={}]
  * @returns {NormalizedPageTextParams}
@@ -914,7 +1027,7 @@ export function normalizeViewportResizeParams(params = {}) {
   return {
     width: clampInt(params.width, 320, 7680, DEFAULT_VIEWPORT_WIDTH),
     height: clampInt(params.height, 200, 4320, DEFAULT_VIEWPORT_HEIGHT),
-    deviceScaleFactor: clampInt(params.deviceScaleFactor, 0, 4, 0),
+    deviceScaleFactor: clampNumber(params.deviceScaleFactor, 0, 4, DEFAULT_DEVICE_SCALE_FACTOR),
     reset: Boolean(params.reset),
   };
 }

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',
@@ -132,12 +132,12 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
   '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;
@@ -397,7 +408,7 @@ export interface NormalizedEvaluateParams extends BridgeParams {
   expression: string;
   awaitPromise: boolean;
   timeoutMs: number;
-  returnByValue: boolean;
+  returnByValue: true;
 }
 
 export interface ConsoleParams {
@@ -554,6 +565,24 @@ export interface NormalizedNetworkParams extends BridgeParams {
   urlPattern: string | null;
 }
 
+export type NetworkInterceptAction = 'fulfill' | 'continue' | 'block';
+
+export interface NetworkInterceptAddParams {
+  urlPattern?: string;
+  action?: NetworkInterceptAction;
+  statusCode?: number;
+  body?: string;
+  headers?: Record<string, string>;
+}
+
+export interface NormalizedNetworkInterceptAddParams extends BridgeParams {
+  urlPattern: string;
+  action: NetworkInterceptAction;
+  statusCode?: number;
+  body?: string;
+  headers?: Record<string, string>;
+}
+
 export interface PageTextParams {
   textBudget?: number;
 }

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.
 
@@ -21,7 +21,7 @@ For open-ended investigation, start with structured reads (`page.get_state`, `do
 bbx status                  # daemon + extension health
 bbx doctor                  # install/access readiness
 bbx access-request          # ask user to enable access for the focused window
-bbx restart                 # start/restart the local daemon non-interactively
+bbx restart                 # start/restart the daemon and running MCP servers
 bbx call <method> '{...}'   # any RPC method (raw output)
 bbx <method> '{...}'        # direct alias for an exact bridge method such as page.get_state
 bbx call --tab 123 <method> '{...}' # explicit tab override
@@ -235,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`                                                                                           |
@@ -291,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

@@ -195,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

@@ -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,7 @@ 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`.
 
@@ -182,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