@browserbridge/bbx 1.7.7 → 1.8.0

package/packages/protocol/src/registry.js

@@ -41,6 +41,10 @@ const METHOD_POLICIES = Object.freeze({
     debuggerBacked: true,
   }),
   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 +106,16 @@ 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.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 values.',
   '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.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.',
@@ -122,22 +132,26 @@ 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.',
@@ -146,7 +160,8 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   '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.',
@@ -195,7 +210,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 +280,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
   ),
@@ -289,11 +312,19 @@ 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
   ),
@@ -384,7 +415,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.describe',
     'inspect',
     true,
-    ['elementRef'],
+    ['elementRef', 'target'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -392,7 +423,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.get_text',
     'inspect',
     true,
-    ['elementRef', 'textBudget'],
+    ['elementRef', 'target', 'textBudget'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -400,7 +431,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.get_attributes',
     'inspect',
     true,
-    ['elementRef', 'attributes'],
+    ['elementRef', 'target', 'attributes'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -432,7 +463,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 +471,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 +480,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'layout.get_box_model',
     'inspect',
     true,
-    ['elementRef'],
+    ['elementRef', 'target'],
     'low',
     METHOD_POLICIES.layoutRead
   ),
@@ -466,7 +497,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'styles.get_computed',
     'inspect',
     true,
-    ['elementRef', 'properties'],
+    ['elementRef', 'target', 'properties'],
     'low',
     METHOD_POLICIES.stylesRead
   ),
@@ -474,7 +505,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'styles.get_matched_rules',
     'inspect',
     true,
-    ['elementRef'],
+    ['elementRef', 'target'],
     'moderate',
     METHOD_POLICIES.stylesRead
   ),
@@ -500,7 +531,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 +539,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.focus',
     'interact',
     true,
-    ['target'],
+    ['target', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -516,7 +547,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 +555,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 +563,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 +571,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 +579,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 +587,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 +595,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 +612,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_region',
     'capture',
     true,
-    ['x', 'y', 'width', 'height'],
+    ['x', 'y', 'width', 'height', 'format', 'quality'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
@@ -589,7 +620,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_element',
     'capture',
     true,
-    ['elementRef'],
+    ['elementRef', 'format', 'quality'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
@@ -597,7 +628,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_full_page',
     'capture',
     true,
-    [],
+    ['format', 'quality'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),

package/packages/protocol/src/summary.js

@@ -68,16 +68,31 @@ const ACTION_SUMMARIES = {
   },
   closed: { text: (r) => `Tab ${r.tabId} closed.`, evidence: (r) => r },
   clicked: {
-    text: (r) => `Clicked ${r.elementRef ?? 'element'}.`,
-    evidence: (r) => ({ elementRef: r.elementRef }),
+    text: (r) => {
+      const mode = toRecord(r.execution).actualMode;
+      return `Clicked ${r.elementRef ?? 'element'}${typeof mode === 'string' ? ` via ${mode}` : ''}.`;
+    },
+    evidence: (r) => ({
+      elementRef: r.elementRef,
+      resolution: r.resolution,
+      execution: r.execution,
+    }),
   },
   focused: {
     text: (r) => `Focused ${r.elementRef ?? 'element'}.`,
-    evidence: (r) => ({ elementRef: r.elementRef }),
+    evidence: (r) => ({
+      elementRef: r.elementRef,
+      resolution: r.resolution,
+      execution: r.execution,
+    }),
   },
   typed: {
     text: (r) => `Typed into ${r.elementRef ?? 'element'}.`,
-    evidence: (r) => ({ elementRef: r.elementRef }),
+    evidence: (r) => ({
+      elementRef: r.elementRef,
+      resolution: r.resolution,
+      execution: r.execution,
+    }),
   },
   pressed: {
     text: (r) => `Key pressed${r.key ? ` (${r.key})` : ''}.`,
@@ -179,6 +194,29 @@ export function summarizeBridgeResponse(response, method) {
   }
 
   const result = toRecord(response.result);
+  if (method === 'page.handle_dialog') {
+    const action = typeof result.action === 'string' ? result.action : 'inspect';
+    return {
+      ok: true,
+      summary: appendProtocolWarning(
+        result.commandDispatched === true
+          ? `JavaScript dialog ${action} command dispatched to the current dialog; Chrome did not atomically bind it to the observation identifier.`
+          : `JavaScript ${result.type ?? 'unknown'} dialog is open.`,
+        protocolWarning
+      ),
+      evidence: result,
+    };
+  }
+  if (method === 'page.wait_for_load_state' && typeof result.finalUrl === 'string') {
+    return {
+      ok: true,
+      summary: appendProtocolWarning(
+        `URL matched via ${result.observedNavigationKind ?? 'unknown'} after ${result.elapsedMs ?? 0}ms.`,
+        protocolWarning
+      ),
+      evidence: result,
+    };
+  }
   if (typeof result.daemon === 'string') {
     const access =
       result.access && typeof result.access === 'object'
@@ -232,6 +270,23 @@ export function summarizeBridgeResponse(response, method) {
       evidence: result,
     };
   }
+  if (typeof result.content === 'string' && typeof result.source === 'string') {
+    return {
+      ok: true,
+      summary: appendProtocolWarning(
+        `Extracted ${result.source} ${result.format ?? 'text'}: ${result.length ?? result.content.length} chars${result.truncated ? ' (truncated)' : ''}.`,
+        protocolWarning
+      ),
+      evidence: {
+        content: result.content.slice(0, 500),
+        format: result.format,
+        source: result.source,
+        length: result.length,
+        truncated: result.truncated,
+        settlement: result.settlement,
+      },
+    };
+  }
   if (
     typeof result.url === 'string' &&
     typeof result.title === 'string' &&
@@ -466,7 +521,9 @@ export function summarizeBridgeResponse(response, method) {
   if (
     Array.isArray(result.entries) &&
     (result.entries.length > 0
-      ? result.entries[0]?.type === 'fetch' || result.entries[0]?.type === 'xhr'
+      ? result.entries[0]?.type === 'fetch' ||
+        result.entries[0]?.type === 'xhr' ||
+        typeof result.entries[0]?.resourceType === 'string'
       : method === 'page.get_network')
   ) {
     const entries = /** @type {Array<Record<string, unknown>>} */ (result.entries);
@@ -481,6 +538,10 @@ export function summarizeBridgeResponse(response, method) {
         url: truncateUrl(/** @type {string} */ (e.url)),
         status: e.status,
         duration: e.duration,
+        ...(typeof e.resourceType === 'string' ? { resourceType: e.resourceType } : {}),
+        ...(typeof e.failureReason === 'string' && e.failureReason
+          ? { failureReason: e.failureReason }
+          : {}),
       })),
     };
   }
@@ -524,6 +585,27 @@ export function summarizeBridgeResponse(response, method) {
       };
     }
   }
+  if (method?.startsWith('input.') && result.execution && typeof result.execution === 'object') {
+    const execution = toRecord(result.execution);
+    return {
+      ok: true,
+      summary: appendProtocolWarning(
+        `${method} completed via ${execution.actualMode ?? 'dom'}${result.elementRef ? ` on ${result.elementRef}` : ''}.`,
+        protocolWarning
+      ),
+      evidence: {
+        elementRef: result.elementRef ?? null,
+        sourceRef: result.sourceRef ?? null,
+        destinationRef: result.destinationRef ?? null,
+        typed: result.typed,
+        checked: result.checked,
+        selectedValues: result.selectedValues,
+        mode: result.mode,
+        resolution: result.resolution,
+        execution: result.execution,
+      },
+    };
+  }
   if (typeof result.tabId === 'number' && typeof result.url === 'string') {
     const actionMethod = typeof result.method === 'string' ? result.method : method;
     if (actionMethod === 'navigation.navigate') {