@browserbridge/bbx 1.7.7 → 1.8.0

package/packages/protocol/src/protocol.js

@@ -8,6 +8,7 @@ import {
   DEFAULT_CONSOLE_LIMIT,
   DEFAULT_DEVICE_SCALE_FACTOR,
   DEFAULT_EVAL_TIMEOUT_MS,
+  DEFAULT_EXTRACT_SETTLE_TIMEOUT_MS,
   DEFAULT_LOG_TAIL_LIMIT,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_HTML_LENGTH,
@@ -20,11 +21,13 @@ import {
   DEFAULT_VIEWPORT_HEIGHT,
   DEFAULT_VIEWPORT_WIDTH,
   DEFAULT_WAIT_TIMEOUT_MS,
+  MAX_EXTRACT_SETTLE_TIMEOUT_MS,
 } from './defaults.js';
 import { BridgeError, ERROR_CODES, getErrorRecovery } from './errors.js';
 import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry.js';
 
 /** @typedef {import('./types.js').AccessibilityTreeParams} AccessibilityTreeParams */
+/** @typedef {import('./types.js').AccessRequestParams} AccessRequestParams */
 /** @typedef {import('./types.js').BridgeFailureResponse} BridgeFailureResponse */
 /** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
@@ -37,16 +40,19 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').DomQueryParams} DomQueryParams */
 /** @typedef {import('./types.js').DragParams} DragParams */
 /** @typedef {import('./types.js').EvaluateParams} EvaluateParams */
+/** @typedef {import('./types.js').ExtractContentParams} ExtractContentParams */
 /** @typedef {import('./types.js').FindByRoleParams} FindByRoleParams */
 /** @typedef {import('./types.js').FindByTextParams} FindByTextParams */
 /** @typedef {import('./types.js').GetHtmlParams} GetHtmlParams */
 /** @typedef {import('./types.js').HoverParams} HoverParams */
+/** @typedef {import('./types.js').HandleDialogParams} HandleDialogParams */
 /** @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').NormalizedAccessRequestParams} NormalizedAccessRequestParams */
 /** @typedef {import('./types.js').NormalizedCheckedAction} NormalizedCheckedAction */
 /** @typedef {import('./types.js').NormalizedCdpDispatchKeyEventParams} NormalizedCdpDispatchKeyEventParams */
 /** @typedef {import('./types.js').NormalizedCdpNodeIdParams} NormalizedCdpNodeIdParams */
@@ -54,10 +60,12 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').NormalizedDomQuery} NormalizedDomQuery */
 /** @typedef {import('./types.js').NormalizedDragParams} NormalizedDragParams */
 /** @typedef {import('./types.js').NormalizedEvaluateParams} NormalizedEvaluateParams */
+/** @typedef {import('./types.js').NormalizedExtractContentParams} NormalizedExtractContentParams */
 /** @typedef {import('./types.js').NormalizedFindByRoleParams} NormalizedFindByRoleParams */
 /** @typedef {import('./types.js').NormalizedFindByTextParams} NormalizedFindByTextParams */
 /** @typedef {import('./types.js').NormalizedGetHtmlParams} NormalizedGetHtmlParams */
 /** @typedef {import('./types.js').NormalizedHoverParams} NormalizedHoverParams */
+/** @typedef {import('./types.js').NormalizedHandleDialogParams} NormalizedHandleDialogParams */
 /** @typedef {import('./types.js').NormalizedInputAction} NormalizedInputAction */
 /** @typedef {import('./types.js').NormalizedLogTailParams} NormalizedLogTailParams */
 /** @typedef {import('./types.js').NormalizedNavigationAction} NormalizedNavigationAction */
@@ -66,6 +74,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').NormalizedPageTextParams} NormalizedPageTextParams */
 /** @typedef {import('./types.js').NormalizedPatchOperation} NormalizedPatchOperation */
 /** @typedef {import('./types.js').NormalizedSelectAction} NormalizedSelectAction */
+/** @typedef {import('./types.js').NormalizedScreenshotParams} NormalizedScreenshotParams */
 /** @typedef {import('./types.js').NormalizedStorageParams} NormalizedStorageParams */
 /** @typedef {import('./types.js').NormalizedStyleQuery} NormalizedStyleQuery */
 /** @typedef {import('./types.js').NormalizedTabCloseParams} NormalizedTabCloseParams */
@@ -77,6 +86,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').PageTextParams} PageTextParams */
 /** @typedef {import('./types.js').PatchOperationParams} PatchOperationParams */
 /** @typedef {import('./types.js').SelectActionParams} SelectActionParams */
+/** @typedef {import('./types.js').ScreenshotParams} ScreenshotParams */
 /** @typedef {import('./types.js').StorageParams} StorageParams */
 /** @typedef {import('./types.js').StyleQueryParams} StyleQueryParams */
 /** @typedef {import('./types.js').TabCloseParams} TabCloseParams */
@@ -348,6 +358,8 @@ export function validateBridgeRequest(request) {
  */
 function normalizeRequestParams(method, params) {
   switch (method) {
+    case 'access.request':
+      return normalizeAccessRequestParams(params);
     case 'log.tail':
       return normalizeLogTailParams(params);
     case 'dom.query':
@@ -356,12 +368,16 @@ function normalizeRequestParams(method, params) {
       return normalizeEvaluateParams(params);
     case 'page.get_console':
       return normalizeConsoleParams(params);
+    case 'page.handle_dialog':
+      return normalizeHandleDialogParams(params);
     case 'page.wait_for_load_state':
       return normalizeWaitForLoadStateParams(params);
     case 'page.get_storage':
       return normalizeStorageParams(params);
     case 'page.get_text':
       return normalizePageTextParams(params);
+    case 'page.extract_content':
+      return normalizeExtractContentParams(params);
     case 'page.get_network':
       return normalizeNetworkParams(params);
     case 'network.intercept.add':
@@ -407,6 +423,10 @@ function normalizeRequestParams(method, params) {
       return normalizeHoverParams(params);
     case 'input.drag':
       return normalizeDragParams(params);
+    case 'screenshot.capture_region':
+    case 'screenshot.capture_element':
+    case 'screenshot.capture_full_page':
+      return { ...params, ...normalizeScreenshotParams(params) };
     case 'patch.apply_styles':
     case 'patch.apply_dom':
     case 'patch.list':
@@ -422,6 +442,28 @@ function normalizeRequestParams(method, params) {
   }
 }
 
+/**
+ * @param {AccessRequestParams} [params={}]
+ * @returns {NormalizedAccessRequestParams}
+ */
+export function normalizeAccessRequestParams(params = {}) {
+  const intent = params.intent ?? 'general';
+  if (
+    intent !== 'inspect' &&
+    intent !== 'interact' &&
+    intent !== 'capture' &&
+    intent !== 'navigate' &&
+    intent !== 'debugger' &&
+    intent !== 'general'
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'intent must be one of inspect, interact, capture, navigate, debugger, or general.'
+    );
+  }
+  return { intent };
+}
+
 /**
  * Return the browser-operation timeout for methods that wait asynchronously.
  * This lets clients and the daemon keep transport deadlines outside the
@@ -442,6 +484,10 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
       return normalizeWaitForLoadStateParams(params).timeoutMs;
     case 'page.evaluate':
       return normalizeEvaluateParams(params).timeoutMs;
+    case 'page.extract_content': {
+      const normalized = normalizeExtractContentParams(params);
+      return normalized.consistency === 'settled' ? normalized.settleTimeoutMs : null;
+    }
     case 'dom.wait_for':
       return clampInt(params.timeoutMs, 100, 30_000, 5_000);
     default:
@@ -499,6 +545,17 @@ function normalizeTarget(target) {
   };
 }
 
+/**
+ * @param {unknown} value
+ * @returns {import('./types.js').InputExecutionMode}
+ */
+function normalizeInputExecutionMode(value) {
+  if (value !== undefined && value !== 'dom' && value !== 'cdp') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'executionMode must be either dom or cdp.');
+  }
+  return value === 'cdp' ? 'cdp' : 'dom';
+}
+
 /**
  * @param {InputActionParams} [params={}]
  * @returns {NormalizedInputAction}
@@ -527,6 +584,8 @@ export function normalizeInputAction(params = {}) {
     modifiers: Array.isArray(params.modifiers)
       ? params.modifiers.filter((modifier) => typeof modifier === 'string' && modifier.trim())
       : [],
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -604,6 +663,8 @@ export function normalizeCheckedAction(params = {}) {
         : undefined
     ),
     checked: params.checked !== false,
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -629,6 +690,8 @@ export function normalizeSelectAction(params = {}) {
           .map((index) => Number(index))
           .filter((index) => Number.isInteger(index) && index >= 0)
       : [],
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -739,6 +802,62 @@ export function normalizeConsoleParams(params = {}) {
   };
 }
 
+/**
+ * @param {HandleDialogParams} [params={}]
+ * @returns {NormalizedHandleDialogParams}
+ */
+export function normalizeHandleDialogParams(params = {}) {
+  const action = params.action ?? 'inspect';
+  if (action !== 'inspect' && action !== 'accept' && action !== 'dismiss') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'action must be one of inspect, accept, or dismiss.'
+    );
+  }
+  if (
+    params.promptText !== undefined &&
+    params.promptText !== null &&
+    typeof params.promptText !== 'string'
+  ) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'promptText must be a string.');
+  }
+  if (typeof params.promptText === 'string' && params.promptText.length > 10_000) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'promptText must not exceed 10,000 characters.'
+    );
+  }
+  if (params.promptText !== undefined && params.promptText !== null && action !== 'accept') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'promptText is only valid when action is accept.'
+    );
+  }
+  if (
+    params.expectedDialogId !== undefined &&
+    params.expectedDialogId !== null &&
+    (typeof params.expectedDialogId !== 'string' ||
+      params.expectedDialogId.length === 0 ||
+      params.expectedDialogId.length > 128)
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'expectedDialogId must be a non-empty string of at most 128 characters.'
+    );
+  }
+  if (action === 'inspect' && params.expectedDialogId != null) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'expectedDialogId is only valid when action is accept or dismiss.'
+    );
+  }
+  return {
+    action,
+    promptText: typeof params.promptText === 'string' ? params.promptText : null,
+    expectedDialogId: typeof params.expectedDialogId === 'string' ? params.expectedDialogId : null,
+  };
+}
+
 /**
  * @param {WaitForParams} [params={}]
  * @returns {NormalizedWaitForParams}
@@ -823,6 +942,8 @@ export function normalizeHoverParams(params = {}) {
     modifiers: Array.isArray(params.modifiers)
       ? params.modifiers.filter((modifier) => typeof modifier === 'string' && modifier.trim())
       : [],
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -844,6 +965,8 @@ export function normalizeDragParams(params = {}) {
     ),
     offsetX: Number.isFinite(Number(params.offsetX)) ? Number(params.offsetX) : 0,
     offsetY: Number.isFinite(Number(params.offsetY)) ? Number(params.offsetY) : 0,
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -863,12 +986,98 @@ export function normalizeStorageParams(params = {}) {
  * @returns {NormalizedWaitForLoadStateParams}
  */
 export function normalizeWaitForLoadStateParams(params = {}) {
+  const url = typeof params.url === 'string' && params.url.length > 0 ? params.url : null;
+  const requestedMatch = params.urlMatch ?? (url ? 'exact' : null);
+  if (params.url !== undefined && params.url !== null && typeof params.url !== 'string') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'url must be a string.');
+  }
+  if (params.urlMatch !== undefined && params.urlMatch !== null && !url) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'url is required when urlMatch is set.');
+  }
+  if (
+    requestedMatch !== null &&
+    requestedMatch !== 'exact' &&
+    requestedMatch !== 'contains' &&
+    requestedMatch !== 'regex'
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'urlMatch must be one of exact, contains, or regex.'
+    );
+  }
+  if (url && url.length > 2_048) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'url condition must not exceed 2,048 characters.'
+    );
+  }
+  if (requestedMatch === 'regex' && url) {
+    validateSafeUrlRegex(url);
+  }
   return {
     waitForLoad: params.waitForLoad !== false,
     timeoutMs: clampInt(params.timeoutMs, 500, 120_000, DEFAULT_NAV_TIMEOUT_MS),
+    url,
+    urlMatch: requestedMatch,
   };
 }
 
+/**
+ * URL waits accept a deliberately linear regular-expression subset. Patterns
+ * may contain literals, escapes, anchors, dots, and character classes, but no
+ * grouping, alternation, or quantifiers. With both pattern and input bounded,
+ * the accepted subset cannot trigger backtracking through repeated matches.
+ *
+ * @param {string} pattern
+ * @returns {void}
+ */
+function validateSafeUrlRegex(pattern) {
+  if (pattern.length > 256) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'Regex URL condition must not exceed 256 characters.'
+    );
+  }
+  let escaped = false;
+  let inCharacterClass = false;
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (escaped) {
+      if (!inCharacterClass && /[1-9]/.test(character)) {
+        throw new BridgeError(
+          ERROR_CODES.INVALID_REQUEST,
+          'Regex URL condition uses an unsupported backreference.'
+        );
+      }
+      escaped = false;
+      continue;
+    }
+    if (character === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (character === '[' && !inCharacterClass) {
+      inCharacterClass = true;
+      continue;
+    }
+    if (character === ']' && inCharacterClass) {
+      inCharacterClass = false;
+      continue;
+    }
+    if (!inCharacterClass && '(){}*+?|'.includes(character)) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        'Regex URL condition uses unsupported grouping, alternation, or quantifiers.'
+      );
+    }
+  }
+  try {
+    new RegExp(pattern);
+  } catch {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Regex URL condition is invalid.');
+  }
+}
+
 /**
  * @param {TabCreateParams} [params={}]
  * @returns {NormalizedTabCreateParams}
@@ -914,8 +1123,33 @@ export function normalizeTabCloseParams(params = {}) {
  */
 export function normalizeAccessibilityTreeParams(params = {}) {
   return {
+    selector:
+      typeof params.selector === 'string' && params.selector.trim() ? params.selector.trim() : null,
     maxDepth: clampInt(params.maxDepth, 1, 20, DEFAULT_A11Y_MAX_DEPTH),
     maxNodes: clampInt(params.maxNodes, 10, 5000, DEFAULT_A11Y_MAX_NODES),
+    compact: params.compact === true,
+    interactiveOnly: params.interactiveOnly === true,
+  };
+}
+
+/**
+ * @param {ScreenshotParams} [params={}]
+ * @returns {NormalizedScreenshotParams}
+ */
+export function normalizeScreenshotParams(params = {}) {
+  const format = params.format ?? 'png';
+  if (format !== 'png' && format !== 'jpeg' && format !== 'webp') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'format must be png, jpeg, or webp.');
+  }
+  const numericQuality = Number(params.quality);
+  return {
+    format,
+    quality:
+      format === 'png' || params.quality === undefined
+        ? null
+        : Number.isFinite(numericQuality)
+          ? Math.min(100, Math.max(0, Math.trunc(numericQuality)))
+          : 80,
   };
 }
 
@@ -924,6 +1158,20 @@ export function normalizeAccessibilityTreeParams(params = {}) {
  * @returns {NormalizedNetworkParams}
  */
 export function normalizeNetworkParams(params = {}) {
+  const source = params.source ?? 'fetch-xhr';
+  if (source !== 'fetch-xhr' && source !== 'cdp') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'source must be fetch-xhr or cdp.');
+  }
+  const capture = params.capture ?? 'read';
+  if (capture !== 'read' && capture !== 'start' && capture !== 'clear' && capture !== 'stop') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'capture must be read, start, clear, or stop.'
+    );
+  }
+  if (source !== 'cdp' && params.capture !== undefined && params.capture !== 'read') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'capture is only valid with source "cdp".');
+  }
   return {
     clear: Boolean(params.clear),
     limit: clampInt(params.limit, 1, 500, DEFAULT_NETWORK_LIMIT),
@@ -931,6 +1179,8 @@ export function normalizeNetworkParams(params = {}) {
       typeof params.urlPattern === 'string' && params.urlPattern.trim()
         ? params.urlPattern.trim()
         : null,
+    source,
+    capture,
   };
 }
 
@@ -1009,6 +1259,44 @@ export function normalizePageTextParams(params = {}) {
   };
 }
 
+/**
+ * @param {ExtractContentParams} [params={}]
+ * @returns {NormalizedExtractContentParams}
+ */
+export function normalizeExtractContentParams(params = {}) {
+  const format = params.format ?? 'text';
+  if (format !== 'text' && format !== 'markdown') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'format must be text or markdown.');
+  }
+  const consistency = params.consistency ?? 'best_effort';
+  if (consistency !== 'best_effort' && consistency !== 'settled') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'consistency must be best_effort or settled.'
+    );
+  }
+  const selector = typeof params.selector === 'string' ? params.selector.trim() : '';
+  if (selector.length > 2048) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'selector must not exceed 2,048 characters.'
+    );
+  }
+  return {
+    format,
+    selector: selector || null,
+    includeMetadata: params.includeMetadata !== false,
+    consistency,
+    textBudget: clampInt(params.textBudget, 100, 100_000, DEFAULT_PAGE_TEXT_BUDGET),
+    settleTimeoutMs: clampInt(
+      params.settleTimeoutMs,
+      100,
+      MAX_EXTRACT_SETTLE_TIMEOUT_MS,
+      DEFAULT_EXTRACT_SETTLE_TIMEOUT_MS
+    ),
+  };
+}
+
 /**
  * @param {LogTailParams} [params={}]
  * @returns {NormalizedLogTailParams}
@@ -1071,6 +1359,14 @@ export function createRuntimeContext() {
         'Browser Bridge is off for this window or the page is restricted; if access is off, the first denied call surfaces an Enable cue in the extension UI',
       TAB_MISMATCH: 'Tab closed or not found',
       ELEMENT_STALE: 'Element removed from DOM - re-query',
+      ELEMENT_AMBIGUOUS: 'Input selector matched equally actionable elements - narrow selector',
+      ELEMENT_NOT_ACTIONABLE: 'Input target is hidden, disabled, inert, or not rendered',
+      ELEMENT_OBSCURED: 'Pointer target is blocked by an unrelated element',
+      ELEMENT_NOT_FOUND: 'Input selector did not match an element',
+      INPUT_UNSUPPORTED: 'Execution mode does not support this input operation',
+      INPUT_INVALID_TARGET: 'Input target is incompatible with the requested operation',
+      INPUT_FOCUS_CHANGED: 'Focus moved before native text dispatch',
+      DIALOG_NOT_OPEN: 'No JavaScript dialog is currently observable',
       INVALID_REQUEST: 'Malformed method or params',
       TIMEOUT: 'Operation exceeded time limit',
       RATE_LIMITED: 'Too many requests - back off',
@@ -1091,7 +1387,7 @@ export function createRuntimeContext() {
       'If a tab-bound call returns ACCESS_DENIED because access is off, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once',
       'dom.wait_for after HMR / navigation to detect page updates',
       'page.get_console to catch runtime errors after interactions',
-      'page.get_network to inspect XHR/fetch API calls',
+      'page.get_network for fetch/XHR reads or explicit all-resource CDP capture',
       'page.get_text for full-page content extraction',
       'input.hover before screenshot to inspect hover states',
       'performance.get_metrics for Core Web Vitals and load timing',