@browserbridge/bbx 1.7.4 → 1.7.6

package/packages/protocol/src/capabilities.js

@@ -1,122 +1,45 @@
 // @ts-check
 
+import { CAPABILITIES, DEFAULT_CAPABILITIES } from './capability-values.js';
+import { BRIDGE_METHODS, BRIDGE_METHOD_REGISTRY } from './registry.js';
+
 /** @typedef {import('./types.js').BridgeMethod} CapabilityMethod */
 /** @typedef {import('./types.js').Capability} Capability */
 
-export const CAPABILITIES = Object.freeze({
-  PAGE_READ: 'page.read',
-  PAGE_EVALUATE: 'page.evaluate',
-  DOM_READ: 'dom.read',
-  STYLES_READ: 'styles.read',
-  LAYOUT_READ: 'layout.read',
-  VIEWPORT_CONTROL: 'viewport.control',
-  NAVIGATION_CONTROL: 'navigation.control',
-  SCREENSHOT_PARTIAL: 'screenshot.partial',
-  PATCH_DOM: 'patch.dom',
-  PATCH_STYLES: 'patch.styles',
-  CDP_DOM_SNAPSHOT: 'cdp.dom_snapshot',
-  CDP_BOX_MODEL: 'cdp.box_model',
-  CDP_STYLES: 'cdp.styles',
-  CDP_INPUT: 'cdp.input',
-  AUTOMATION_INPUT: 'automation.input',
-  TABS_MANAGE: 'tabs.manage',
-  PERFORMANCE_READ: 'performance.read',
-  NETWORK_READ: 'network.read',
-  NETWORK_INTERCEPT: 'network.intercept',
-});
+export { CAPABILITIES, DEFAULT_CAPABILITIES };
+
+/** @type {readonly CapabilityMethod[]} */
+const LEGACY_METHOD_CAPABILITY_PREFIX = [
+  'access.request',
+  'tabs.list',
+  'tabs.create',
+  'tabs.close',
+  'tabs.activate',
+  'skill.get_runtime_context',
+  'setup.get_status',
+  'setup.install',
+];
+
+/** @type {readonly CapabilityMethod[]} */
+const LEGACY_METHOD_CAPABILITY_SUFFIX = ['log.tail', 'health.ping', 'daemon.metrics'];
 
-export const DEFAULT_CAPABILITIES = Object.freeze([
-  CAPABILITIES.PAGE_READ,
-  CAPABILITIES.PAGE_EVALUATE,
-  CAPABILITIES.DOM_READ,
-  CAPABILITIES.STYLES_READ,
-  CAPABILITIES.LAYOUT_READ,
-  CAPABILITIES.VIEWPORT_CONTROL,
-  CAPABILITIES.NAVIGATION_CONTROL,
-  CAPABILITIES.SCREENSHOT_PARTIAL,
-  CAPABILITIES.PATCH_DOM,
-  CAPABILITIES.PATCH_STYLES,
-  CAPABILITIES.AUTOMATION_INPUT,
-  CAPABILITIES.CDP_DOM_SNAPSHOT,
-  CAPABILITIES.CDP_BOX_MODEL,
-  CAPABILITIES.CDP_STYLES,
-  CAPABILITIES.CDP_INPUT,
-  CAPABILITIES.TABS_MANAGE,
-  CAPABILITIES.PERFORMANCE_READ,
-  CAPABILITIES.NETWORK_READ,
-  CAPABILITIES.NETWORK_INTERCEPT,
+const LEGACY_POSITIONED_METHODS = new Set([
+  ...LEGACY_METHOD_CAPABILITY_PREFIX,
+  ...LEGACY_METHOD_CAPABILITY_SUFFIX,
 ]);
 
 /** @type {Readonly<Record<CapabilityMethod, Capability | null>>} */
-export const METHOD_CAPABILITIES = Object.freeze({
-  'access.request': null,
-  'tabs.list': null,
-  'tabs.create': CAPABILITIES.TABS_MANAGE,
-  'tabs.close': CAPABILITIES.TABS_MANAGE,
-  'tabs.activate': CAPABILITIES.TABS_MANAGE,
-  'skill.get_runtime_context': null,
-  'setup.get_status': null,
-  'setup.install': null,
-  'page.get_state': CAPABILITIES.PAGE_READ,
-  'page.evaluate': CAPABILITIES.PAGE_EVALUATE,
-  'page.get_console': CAPABILITIES.PAGE_READ,
-  'page.wait_for_load_state': CAPABILITIES.PAGE_READ,
-  'page.get_storage': CAPABILITIES.PAGE_READ,
-  'page.get_text': CAPABILITIES.PAGE_READ,
-  'page.get_network': CAPABILITIES.NETWORK_READ,
-  // Interception mutates traffic (block/forge responses) - distinct from
-  // passive network reads so hosts can gate it independently.
-  'network.intercept.add': CAPABILITIES.NETWORK_INTERCEPT,
-  'network.intercept.remove': CAPABILITIES.NETWORK_INTERCEPT,
-  'network.intercept.list': CAPABILITIES.NETWORK_INTERCEPT,
-  'network.intercept.clear': CAPABILITIES.NETWORK_INTERCEPT,
-  'navigation.navigate': CAPABILITIES.NAVIGATION_CONTROL,
-  'navigation.reload': CAPABILITIES.NAVIGATION_CONTROL,
-  'navigation.go_back': CAPABILITIES.NAVIGATION_CONTROL,
-  'navigation.go_forward': CAPABILITIES.NAVIGATION_CONTROL,
-  'dom.query': CAPABILITIES.DOM_READ,
-  'dom.describe': CAPABILITIES.DOM_READ,
-  'dom.get_text': CAPABILITIES.DOM_READ,
-  'dom.get_attributes': CAPABILITIES.DOM_READ,
-  'dom.wait_for': CAPABILITIES.DOM_READ,
-  'dom.find_by_text': CAPABILITIES.DOM_READ,
-  'dom.find_by_role': CAPABILITIES.DOM_READ,
-  'dom.get_html': CAPABILITIES.DOM_READ,
-  'dom.get_accessibility_tree': CAPABILITIES.DOM_READ,
-  'layout.get_box_model': CAPABILITIES.LAYOUT_READ,
-  'layout.hit_test': CAPABILITIES.LAYOUT_READ,
-  'styles.get_computed': CAPABILITIES.STYLES_READ,
-  'styles.get_matched_rules': CAPABILITIES.STYLES_READ,
-  'viewport.scroll': CAPABILITIES.VIEWPORT_CONTROL,
-  'viewport.resize': CAPABILITIES.VIEWPORT_CONTROL,
-  'input.click': CAPABILITIES.AUTOMATION_INPUT,
-  'input.focus': CAPABILITIES.AUTOMATION_INPUT,
-  'input.type': CAPABILITIES.AUTOMATION_INPUT,
-  'input.fill': CAPABILITIES.AUTOMATION_INPUT,
-  'input.press_key': CAPABILITIES.AUTOMATION_INPUT,
-  'input.set_checked': CAPABILITIES.AUTOMATION_INPUT,
-  'input.select_option': CAPABILITIES.AUTOMATION_INPUT,
-  'input.hover': CAPABILITIES.AUTOMATION_INPUT,
-  'input.drag': CAPABILITIES.AUTOMATION_INPUT,
-  'input.scroll_into_view': CAPABILITIES.AUTOMATION_INPUT,
-  'screenshot.capture_region': CAPABILITIES.SCREENSHOT_PARTIAL,
-  'screenshot.capture_element': CAPABILITIES.SCREENSHOT_PARTIAL,
-  'screenshot.capture_full_page': CAPABILITIES.SCREENSHOT_PARTIAL,
-  'patch.apply_styles': CAPABILITIES.PATCH_STYLES,
-  'patch.apply_dom': CAPABILITIES.PATCH_DOM,
-  'patch.list': CAPABILITIES.PATCH_DOM,
-  'patch.rollback': CAPABILITIES.PATCH_DOM,
-  'patch.commit_session_baseline': CAPABILITIES.PATCH_DOM,
-  'cdp.get_document': CAPABILITIES.CDP_DOM_SNAPSHOT,
-  'cdp.get_dom_snapshot': CAPABILITIES.CDP_DOM_SNAPSHOT,
-  'cdp.get_box_model': CAPABILITIES.CDP_BOX_MODEL,
-  'cdp.get_computed_styles_for_node': CAPABILITIES.CDP_STYLES,
-  'cdp.dispatch_key_event': CAPABILITIES.CDP_INPUT,
-  'performance.get_metrics': CAPABILITIES.PERFORMANCE_READ,
-  'log.tail': null,
-  'health.ping': null,
-  'daemon.metrics': null,
-});
+export const METHOD_CAPABILITIES = Object.freeze(
+  /** @type {Record<CapabilityMethod, Capability | null>} */ (
+    Object.fromEntries(
+      [
+        ...LEGACY_METHOD_CAPABILITY_PREFIX,
+        ...BRIDGE_METHODS.filter((method) => !LEGACY_POSITIONED_METHODS.has(method)),
+        ...LEGACY_METHOD_CAPABILITY_SUFFIX,
+      ].map((method) => [method, BRIDGE_METHOD_REGISTRY[method].capability])
+    )
+  )
+);
 
 /**
  * @param {unknown} value

package/packages/protocol/src/capability-values.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+export const CAPABILITIES = Object.freeze({
+  PAGE_READ: 'page.read',
+  PAGE_EVALUATE: 'page.evaluate',
+  DOM_READ: 'dom.read',
+  STYLES_READ: 'styles.read',
+  LAYOUT_READ: 'layout.read',
+  VIEWPORT_CONTROL: 'viewport.control',
+  NAVIGATION_CONTROL: 'navigation.control',
+  SCREENSHOT_PARTIAL: 'screenshot.partial',
+  PATCH_DOM: 'patch.dom',
+  PATCH_STYLES: 'patch.styles',
+  CDP_DOM_SNAPSHOT: 'cdp.dom_snapshot',
+  CDP_BOX_MODEL: 'cdp.box_model',
+  CDP_STYLES: 'cdp.styles',
+  CDP_INPUT: 'cdp.input',
+  AUTOMATION_INPUT: 'automation.input',
+  TABS_MANAGE: 'tabs.manage',
+  PERFORMANCE_READ: 'performance.read',
+  NETWORK_READ: 'network.read',
+  NETWORK_INTERCEPT: 'network.intercept',
+});
+
+export const DEFAULT_CAPABILITIES = Object.freeze([
+  CAPABILITIES.PAGE_READ,
+  CAPABILITIES.PAGE_EVALUATE,
+  CAPABILITIES.DOM_READ,
+  CAPABILITIES.STYLES_READ,
+  CAPABILITIES.LAYOUT_READ,
+  CAPABILITIES.VIEWPORT_CONTROL,
+  CAPABILITIES.NAVIGATION_CONTROL,
+  CAPABILITIES.SCREENSHOT_PARTIAL,
+  CAPABILITIES.PATCH_DOM,
+  CAPABILITIES.PATCH_STYLES,
+  CAPABILITIES.AUTOMATION_INPUT,
+  CAPABILITIES.CDP_DOM_SNAPSHOT,
+  CAPABILITIES.CDP_BOX_MODEL,
+  CAPABILITIES.CDP_STYLES,
+  CAPABILITIES.CDP_INPUT,
+  CAPABILITIES.TABS_MANAGE,
+  CAPABILITIES.PERFORMANCE_READ,
+  CAPABILITIES.NETWORK_READ,
+  CAPABILITIES.NETWORK_INTERCEPT,
+]);

package/packages/protocol/src/defaults.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import { BRIDGE_METHODS, BRIDGE_METHOD_REGISTRY } from './registry.js';
+
 /**
  * Shared Browser Bridge defaults used by the protocol, MCP layer, and runtime
  * guidance. Keep this as the source of truth for default limits and presets.
@@ -20,6 +22,8 @@ export const DEFAULT_CONSOLE_LIMIT = 50;
 export const DEFAULT_VIEWPORT_WIDTH = 1280;
 export const DEFAULT_VIEWPORT_HEIGHT = 720;
 export const DEFAULT_DEVICE_SCALE_FACTOR = 0;
+/** @type {'continue'} */
+export const DEFAULT_NETWORK_INTERCEPT_ACTION = 'continue';
 
 /** Maximum size of a Chrome native messaging message in bytes. */
 export const MAX_NATIVE_MESSAGE_BYTES = 1_048_576;
@@ -68,8 +72,8 @@ export const BUDGET_PRESETS = Object.freeze({
   deep: { maxNodes: 100, maxDepth: 8, textBudget: 2000, tokenBudget: 4000 },
 });
 
-/** @type {ReadonlySet<string>} */
-export const DEBUGGER_BACKED_METHODS = new Set([
+/** @type {readonly import('./types.js').BridgeMethod[]} */
+const LEGACY_DEBUGGER_BACKED_METHOD_ORDER = [
   'page.evaluate',
   'dom.get_accessibility_tree',
   'viewport.resize',
@@ -86,6 +90,19 @@ export const DEBUGGER_BACKED_METHODS = new Set([
   'cdp.get_box_model',
   'cdp.get_computed_styles_for_node',
   'cdp.dispatch_key_event',
+];
+
+const LEGACY_DEBUGGER_BACKED_METHODS = new Set(LEGACY_DEBUGGER_BACKED_METHOD_ORDER);
+
+/** @type {ReadonlySet<string>} */
+export const DEBUGGER_BACKED_METHODS = new Set([
+  ...LEGACY_DEBUGGER_BACKED_METHOD_ORDER.filter(
+    (method) => BRIDGE_METHOD_REGISTRY[method].debuggerBacked
+  ),
+  ...BRIDGE_METHODS.filter(
+    (method) =>
+      BRIDGE_METHOD_REGISTRY[method].debuggerBacked && !LEGACY_DEBUGGER_BACKED_METHODS.has(method)
+  ),
 ]);
 
 /**

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':
@@ -643,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),
   };
 }
 
@@ -682,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,
   };
 }
 
@@ -829,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),
   };
 }
 
@@ -898,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}
@@ -926,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),
   };
 }