@browserbridge/bbx 1.7.8 → 1.9.0

package/packages/protocol/src/registry.js

@@ -40,7 +40,12 @@ const METHOD_POLICIES = Object.freeze({
     capability: CAPABILITIES.NETWORK_INTERCEPT,
     debuggerBacked: true,
   }),
+  sensitiveRead: Object.freeze({ capability: CAPABILITIES.SENSITIVE_READ }),
   navigationControl: Object.freeze({ capability: CAPABILITIES.NAVIGATION_CONTROL }),
+  navigationControlDebugger: Object.freeze({
+    capability: CAPABILITIES.NAVIGATION_CONTROL,
+    debuggerBacked: true,
+  }),
   domRead: Object.freeze({ capability: CAPABILITIES.DOM_READ }),
   domReadDebugger: Object.freeze({
     capability: CAPABILITIES.DOM_READ,
@@ -102,10 +107,19 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'page.get_state': 'Get URL, title, origin, and ready-state for the active page.',
   'page.evaluate': 'Evaluate JavaScript in the page context.',
   'page.get_console': 'Read buffered console output from the page.',
-  'page.wait_for_load_state': 'Wait for the page to finish loading.',
-  'page.get_storage': 'Read local or session storage values.',
+  'page.handle_dialog':
+    'Inspect or explicitly act on the current JavaScript dialog. expectedDialogId is only a stale-decision check immediately before dispatch; Chrome cannot bind the CDP command atomically to that identifier.',
+  'page.wait_for_load_state':
+    'Wait for truthful tab-complete state and/or an event-aware URL condition.',
+  'page.get_storage': 'Read local or session storage key metadata without values.',
+  'sensitive.read': 'Deliberately read one exact local or session storage value.',
   'page.get_text': 'Read bounded visible text from the page.',
-  'page.get_network': 'Read buffered fetch and XHR network activity.',
+  'page.extract_content':
+    'Extract bounded semantic page content as text or Markdown without returning source HTML.',
+  'page.get_network':
+    'Read buffered fetch/XHR activity or explicitly manage bounded all-resource CDP capture.',
+  'network.export_har':
+    'Export bounded captured network evidence as a HAR 1.2 document, inline or as a daemon-owned artifact.',
   'network.intercept.add': 'Add a request interception rule (CDP Fetch domain).',
   'network.intercept.remove': 'Remove a request interception rule by ID.',
   'network.intercept.list': 'List active interception rules.',
@@ -115,6 +129,10 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'navigation.go_back': 'Navigate backward in tab history.',
   'navigation.go_forward': 'Navigate forward in tab history.',
   'dom.query': 'Query a DOM subtree and return compact node summaries.',
+  'dom.baseline.create': 'Create a short-lived compact semantic DOM baseline for later comparison.',
+  'dom.baseline.compare': 'Compare the current DOM with a retained semantic baseline.',
+  'dom.baseline.describe': 'Describe a retained semantic DOM baseline and its scope.',
+  'dom.baseline.release': 'Release a retained semantic DOM baseline.',
   'dom.describe': 'Describe one element by elementRef.',
   'dom.get_text': 'Read bounded text for one element.',
   'dom.get_attributes': 'Read selected attributes for one element.',
@@ -122,37 +140,45 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'dom.find_by_text': 'Find elements by visible text.',
   'dom.find_by_role': 'Find elements by ARIA role and optional name.',
   'dom.get_html': 'Read inner or outer HTML for one element.',
-  'dom.get_accessibility_tree': 'Read a pruned accessibility tree for the tab.',
+  'dom.get_accessibility_tree':
+    'Read a depth-limited accessibility tree with optional compact or interactive filtering.',
   'layout.get_box_model': 'Read the box model for one element.',
   'layout.hit_test': 'Resolve the topmost element at a viewport point.',
-  'styles.get_computed': 'Read computed style properties for one element.',
-  'styles.get_matched_rules': 'Read matched CSS rule context for one element.',
+  'styles.get_computed':
+    'Read requested computed styles; omission returns display, position, width, height, and color.',
+  'styles.get_matched_rules':
+    'Read element classes and inline style context (not stylesheet cascade data).',
   'viewport.scroll': 'Scroll the viewport or a scrollable element.',
   'viewport.resize': 'Resize or reset the tab viewport.',
-  'input.click': 'Click an element.',
-  'input.focus': 'Focus an element.',
-  'input.type': 'Type text into an element.',
-  'input.fill': 'Set value of an input/textarea element (React/Vue/Angular-safe).',
+  'input.click': 'Actionability-check and click an element through DOM or optional CDP input.',
+  'input.focus': 'Actionability-check and focus an element through DOM input.',
+  'input.type': 'Actionability-check and type through DOM or optional CDP text input.',
+  'input.fill':
+    'Fill an editable target using a DOM strategy or optional CDP text input; verify afterward.',
   'input.press_key': 'Send a key press to the page or an element.',
   'input.set_checked': 'Set checkbox or radio checked state.',
   'input.select_option': 'Select options in a select element.',
-  'input.hover': 'Hover over an element.',
-  'input.drag': 'Drag from one element to another.',
+  'input.hover': 'Actionability-check and hover through DOM or optional CDP pointer input.',
+  'input.drag': 'Actionability-check and drag through DOM or optional CDP pointer input.',
   'input.scroll_into_view': 'Scroll an element into the visible viewport.',
   'screenshot.capture_region': 'Capture a screenshot of a viewport region.',
   'screenshot.capture_element': 'Capture a screenshot of one element.',
   'screenshot.capture_full_page': 'Capture a full-page screenshot beyond the viewport.',
+  'artifact.read': 'Read one bounded chunk from a daemon-owned artifact.',
+  'artifact.delete': 'Delete one daemon-owned artifact.',
   'patch.apply_styles': 'Apply a reversible inline style patch.',
   'patch.apply_dom': 'Apply a reversible DOM patch.',
   'patch.list': 'List active reversible patches.',
   'patch.rollback': 'Rollback one reversible patch.',
-  'patch.commit_session_baseline': 'Commit the current patch session baseline.',
+  'patch.commit_session_baseline':
+    'Keep current document mutations and discard their rollback history.',
   'cdp.get_document': 'Read the CDP DOM document tree.',
   'cdp.get_dom_snapshot': 'Read a CDP DOM snapshot.',
   'cdp.get_box_model': 'Read a CDP box model for a node.',
   'cdp.get_computed_styles_for_node': 'Read CDP computed styles for a node.',
   'cdp.dispatch_key_event': 'Dispatch a key press through Chrome DevTools Protocol input.',
-  'performance.get_metrics': 'Read browser performance metrics.',
+  'performance.get_metrics':
+    'Read a raw Chrome/CDP counter point sample; names and units vary, and BBX measures no navigation window, LCP, CLS, or INP.',
   'log.tail': 'Tail recent bridge log entries.',
   'health.ping': 'Check daemon, extension, and access-routing health.',
   'daemon.metrics': 'Daemon health and performance metrics.',
@@ -195,7 +221,7 @@ function createRegistryEntry(
 /** @type {Readonly<Record<import('./types.js').BridgeMethod, BridgeMethodRegistryEntry>>} */
 export const BRIDGE_METHOD_REGISTRY = Object.freeze({
   // system - trivial
-  'access.request': createRegistryEntry('access.request', 'system', false, [], 'trivial'),
+  'access.request': createRegistryEntry('access.request', 'system', false, ['intent'], 'trivial'),
   'skill.get_runtime_context': createRegistryEntry(
     'skill.get_runtime_context',
     'system',
@@ -265,11 +291,19 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low',
     METHOD_POLICIES.pageRead
   ),
+  'page.handle_dialog': createRegistryEntry(
+    'page.handle_dialog',
+    'page',
+    true,
+    ['action', 'promptText', 'expectedDialogId'],
+    'low',
+    METHOD_POLICIES.navigationControlDebugger
+  ),
   'page.wait_for_load_state': createRegistryEntry(
     'page.wait_for_load_state',
     'wait',
     true,
-    ['timeoutMs'],
+    ['waitForLoad', 'timeoutMs', 'url', 'urlMatch'],
     'low',
     METHOD_POLICIES.pageRead
   ),
@@ -281,6 +315,14 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low',
     METHOD_POLICIES.pageRead
   ),
+  'sensitive.read': createRegistryEntry(
+    'sensitive.read',
+    'sensitive',
+    true,
+    ['source', 'key'],
+    'low',
+    METHOD_POLICIES.sensitiveRead
+  ),
   'page.get_text': createRegistryEntry(
     'page.get_text',
     'page',
@@ -289,14 +331,30 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low',
     METHOD_POLICIES.pageRead
   ),
+  'page.extract_content': createRegistryEntry(
+    'page.extract_content',
+    'page',
+    true,
+    ['format', 'selector', 'includeMetadata', 'consistency', 'textBudget', 'settleTimeoutMs'],
+    'moderate',
+    METHOD_POLICIES.pageRead
+  ),
   'page.get_network': createRegistryEntry(
     'page.get_network',
     'page',
     true,
-    ['clear', 'limit', 'urlPattern'],
+    ['clear', 'limit', 'urlPattern', 'source', 'capture'],
     'low',
     METHOD_POLICIES.networkRead
   ),
+  'network.export_har': createRegistryEntry(
+    'network.export_har',
+    'page',
+    true,
+    ['limit', 'urlPattern', 'delivery'],
+    'moderate',
+    METHOD_POLICIES.networkRead
+  ),
   // network intercept - moderate (holds debugger session)
   'network.intercept.add': createRegistryEntry(
     'network.intercept.add',
@@ -380,11 +438,43 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low',
     METHOD_POLICIES.domRead
   ),
+  'dom.baseline.create': createRegistryEntry(
+    'dom.baseline.create',
+    'inspect',
+    true,
+    ['selector', 'maxNodes', 'maxDepth', 'textBudget', 'attributeAllowlist'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
+  'dom.baseline.compare': createRegistryEntry(
+    'dom.baseline.compare',
+    'inspect',
+    true,
+    ['baselineId', 'maxChanges'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
+  'dom.baseline.describe': createRegistryEntry(
+    'dom.baseline.describe',
+    'inspect',
+    true,
+    ['baselineId'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
+  'dom.baseline.release': createRegistryEntry(
+    'dom.baseline.release',
+    'inspect',
+    true,
+    ['baselineId'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
   'dom.describe': createRegistryEntry(
     'dom.describe',
     'inspect',
     true,
-    ['elementRef'],
+    ['elementRef', 'target'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -392,7 +482,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.get_text',
     'inspect',
     true,
-    ['elementRef', 'textBudget'],
+    ['elementRef', 'target', 'textBudget'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -400,7 +490,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.get_attributes',
     'inspect',
     true,
-    ['elementRef', 'attributes'],
+    ['elementRef', 'target', 'attributes'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -432,7 +522,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.get_html',
     'inspect',
     true,
-    ['elementRef', 'outer', 'maxLength'],
+    ['elementRef', 'target', 'outer', 'maxLength'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -440,7 +530,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.get_accessibility_tree',
     'inspect',
     true,
-    ['maxNodes', 'maxDepth'],
+    ['selector', 'maxNodes', 'maxDepth', 'compact', 'interactiveOnly'],
     'moderate',
     METHOD_POLICIES.domReadDebugger
   ),
@@ -449,7 +539,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'layout.get_box_model',
     'inspect',
     true,
-    ['elementRef'],
+    ['elementRef', 'target'],
     'low',
     METHOD_POLICIES.layoutRead
   ),
@@ -466,7 +556,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'styles.get_computed',
     'inspect',
     true,
-    ['elementRef', 'properties'],
+    ['elementRef', 'target', 'properties'],
     'low',
     METHOD_POLICIES.stylesRead
   ),
@@ -474,7 +564,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'styles.get_matched_rules',
     'inspect',
     true,
-    ['elementRef'],
+    ['elementRef', 'target'],
     'moderate',
     METHOD_POLICIES.stylesRead
   ),
@@ -500,7 +590,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.click',
     'interact',
     true,
-    ['target', 'button', 'clickCount', 'modifiers'],
+    ['target', 'button', 'clickCount', 'modifiers', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -508,7 +598,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.focus',
     'interact',
     true,
-    ['target'],
+    ['target', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -516,7 +606,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.type',
     'interact',
     true,
-    ['target', 'text', 'clear', 'submit', 'modifiers'],
+    ['target', 'text', 'clear', 'submit', 'modifiers', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -524,7 +614,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.fill',
     'interact',
     true,
-    ['target', 'value', 'mode'],
+    ['target', 'value', 'mode', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -532,7 +622,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.press_key',
     'interact',
     true,
-    ['target', 'key', 'modifiers'],
+    ['target', 'key', 'modifiers', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -540,7 +630,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.set_checked',
     'interact',
     true,
-    ['target', 'checked'],
+    ['target', 'checked', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -548,7 +638,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.select_option',
     'interact',
     true,
-    ['target', 'values', 'labels', 'indexes'],
+    ['target', 'values', 'labels', 'indexes', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -556,7 +646,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.hover',
     'interact',
     true,
-    ['target', 'duration', 'modifiers'],
+    ['target', 'duration', 'modifiers', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -564,7 +654,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.drag',
     'interact',
     true,
-    ['source', 'destination', 'offsetX', 'offsetY'],
+    ['source', 'destination', 'offsetX', 'offsetY', 'executionMode', 'recoverStale'],
     'moderate',
     METHOD_POLICIES.automationInput
   ),
@@ -581,7 +671,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_region',
     'capture',
     true,
-    ['x', 'y', 'width', 'height'],
+    ['x', 'y', 'width', 'height', 'format', 'quality', 'delivery', 'scale'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
@@ -589,7 +679,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_element',
     'capture',
     true,
-    ['elementRef'],
+    ['elementRef', 'format', 'quality', 'delivery', 'scale'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
@@ -597,10 +687,24 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_full_page',
     'capture',
     true,
-    [],
+    ['format', 'quality', 'delivery', 'scale'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
+  'artifact.read': createRegistryEntry(
+    'artifact.read',
+    'artifact',
+    false,
+    ['artifactId', 'offset', 'maxBytes'],
+    'low'
+  ),
+  'artifact.delete': createRegistryEntry(
+    'artifact.delete',
+    'artifact',
+    false,
+    ['artifactId'],
+    'low'
+  ),
   // patch - moderate (side effects)
   'patch.apply_styles': createRegistryEntry(
     'patch.apply_styles',
@@ -655,7 +759,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'cdp.get_dom_snapshot',
     'cdp',
     true,
-    [],
+    ['computedStyles'],
     'high',
     METHOD_POLICIES.cdpDomSnapshotDebugger
   ),
@@ -702,6 +806,70 @@ export const BRIDGE_METHODS = Object.freeze(
 /** @type {ReadonlySet<import('./types.js').BridgeMethod>} */
 export const METHOD_SET = new Set(BRIDGE_METHODS);
 
+/** Methods whose read-only forms may run concurrently without side effects. */
+const BATCH_SAFE_METHODS = new Set([
+  'health.ping',
+  'daemon.metrics',
+  'tabs.list',
+  'skill.get_runtime_context',
+  'setup.get_status',
+  'log.tail',
+  'page.get_state',
+  'page.get_console',
+  'page.wait_for_load_state',
+  'page.get_storage',
+  'page.get_text',
+  'page.extract_content',
+  'page.get_network',
+  'dom.query',
+  'dom.baseline.compare',
+  'dom.baseline.describe',
+  'dom.describe',
+  'dom.get_text',
+  'dom.get_attributes',
+  'dom.wait_for',
+  'dom.find_by_text',
+  'dom.find_by_role',
+  'dom.get_html',
+  'dom.get_accessibility_tree',
+  'layout.get_box_model',
+  'layout.hit_test',
+  'styles.get_computed',
+  'styles.get_matched_rules',
+  'network.intercept.list',
+  'patch.list',
+  'performance.get_metrics',
+]);
+
+/**
+ * Classify a normalized or raw bridge call for parallel read-only execution.
+ * Parameter checks deliberately reject malformed truthy mutation flags before
+ * protocol normalization can coerce them.
+ *
+ * @param {import('./types.js').BridgeMethod} method
+ * @param {Record<string, unknown>} [params]
+ * @returns {boolean}
+ */
+export function isBatchSafeBridgeCall(method, params = {}) {
+  if (!BATCH_SAFE_METHODS.has(method)) return false;
+  if (
+    (method === 'page.get_console' || method === 'page.get_network') &&
+    params.clear !== undefined &&
+    params.clear !== false
+  ) {
+    return false;
+  }
+  if (
+    method === 'page.get_network' &&
+    params.source === 'cdp' &&
+    params.capture !== undefined &&
+    params.capture !== 'read'
+  ) {
+    return false;
+  }
+  return true;
+}
+
 /**
  * @returns {Record<string, import('./types.js').BridgeMethod[]>}
  */