@browserbridge/bbx 1.5.2 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -69,15 +69,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/chrome": "^0.1.40",
-    "@types/node": "^25.5.2",
+    "@types/chrome": "^0.1.43",
+    "@types/node": "^25.9.2",
     "c8": "^11.0.0",
     "linkedom": "^0.18.12",
-    "oxfmt": "^0.47.0",
-    "oxlint": "^1.62.0",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
     "typescript": "^6.0.3"
   },
   "engines": {

package/packages/agent-client/src/cli.js

@@ -476,6 +476,23 @@ async function main() {
       return;
     }
 
+    if (command === 'tab-activate') {
+      const [tabId] = rest;
+      if (!tabId) {
+        throw new Error('Usage: tab-activate <tabId>');
+      }
+      const response = await requestBridge(
+        client,
+        'tabs.activate',
+        {
+          tabId: parseIntArg(tabId, 'tabId'),
+        },
+        { source: REQUEST_SOURCE }
+      );
+      await printSummary(response);
+      return;
+    }
+
     if (command === 'call') {
       const { tabId, method, params } = await parseCallCommand(rest);
       const response = await requestBridge(client, method, params, {
@@ -580,18 +597,47 @@ async function main() {
 
     const shortcutCmd = SHORTCUT_COMMANDS[command];
     if (shortcutCmd) {
-      let elementRef;
-      if (shortcutCmd.resolve) {
-        if (!rest[0]) throw new Error(`Usage: ${command} <ref|selector>`);
-        elementRef = await resolveRef(client, rest[0], null, REQUEST_SOURCE);
+      // Allow `bbx <shortcut> --tab <id> ...` to target a specific tab.
+      // Without this, --tab gets eaten as a positional argument and the
+      // request hits whatever tab the bridge route happens to be pointing
+      // at (typically the active tab). For element-resolving shortcuts
+      // the ref must be resolved against the SAME tab the action targets,
+      // so we pass tabId to both resolveRef and the subsequent request.
+      const { tabId, rest: shortcutArgs } = extractTabFlag(rest);
+      const selectorInput = shortcutCmd.resolve ? shortcutArgs[0] : null;
+      if (shortcutCmd.resolve && !selectorInput) {
+        throw new Error(`Usage: ${command} <ref|selector>`);
       }
-      const response = await requestBridge(
-        client,
-        shortcutCmd.method,
-        shortcutCmd.build(rest, elementRef),
-        { source: REQUEST_SOURCE }
-      );
-      await printSummary(response, shortcutCmd.printMethod);
+
+      // Retry-on-stale: if the action fails with ELEMENT_STALE and the
+      // original input was a selector (not an el_xxx ref), re-resolve the
+      // selector and retry once. This handles the common case where the
+      // agent resolved an element, then the page re-rendered (React
+      // reconciliation, SPA navigation) before the action was dispatched.
+      const canRetry = typeof selectorInput === 'string' && !selectorInput.startsWith('el_');
+      const maxAttempts = canRetry ? 2 : 1;
+      /** @type {import('./runtime.js').BridgeResponse | undefined} */
+      let response;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        let elementRef;
+        if (shortcutCmd.resolve && selectorInput) {
+          elementRef = await resolveRef(client, selectorInput, tabId, REQUEST_SOURCE);
+        }
+        response = await requestBridge(
+          client,
+          shortcutCmd.method,
+          shortcutCmd.build(shortcutArgs, elementRef),
+          { source: REQUEST_SOURCE, tabId }
+        );
+        const isStale = !response.ok && response.error?.code === 'ELEMENT_STALE';
+        if (isStale && attempt < maxAttempts) {
+          process.stderr.write(
+            `bbx: ELEMENT_STALE on "${selectorInput}", re-resolving and retrying...\n`
+          );
+        }
+        if (!isStale || attempt >= maxAttempts) break;
+      }
+      if (response) await printSummary(response, shortcutCmd.printMethod);
       return;
     }
 
@@ -664,19 +710,92 @@ async function main() {
       return;
     }
 
+    if (command === 'intercept') {
+      const { tabId, rest: iArgs } = extractTabFlag(rest);
+      const sub = iArgs[0];
+      if (sub === 'add') {
+        const pattern = iArgs[1];
+        if (!pattern)
+          throw new Error(
+            'Usage: intercept add <urlPattern> [--respond <body>] [--status <code>] [--block]'
+          );
+        const isBlock = iArgs.includes('--block');
+        const statusIdx = iArgs.indexOf('--status');
+        const statusCode = statusIdx !== -1 ? parseIntArg(iArgs[statusIdx + 1], 'status') : 200;
+        const respondIdx = iArgs.indexOf('--respond');
+        const body =
+          respondIdx !== -1
+            ? iArgs
+                .slice(respondIdx + 1)
+                .filter((a) => !a.startsWith('--'))
+                .join(' ')
+            : undefined;
+        const response = await requestBridge(
+          client,
+          'network.intercept.add',
+          {
+            urlPattern: pattern,
+            action: isBlock ? 'block' : body != null ? 'fulfill' : 'continue',
+            statusCode,
+            body,
+          },
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else if (sub === 'remove') {
+        const ruleId = iArgs[1];
+        if (!ruleId) throw new Error('Usage: intercept remove <ruleId>');
+        const response = await requestBridge(
+          client,
+          'network.intercept.remove',
+          { ruleId },
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else if (sub === 'list') {
+        const response = await requestBridge(
+          client,
+          'network.intercept.list',
+          {},
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else if (sub === 'clear') {
+        const response = await requestBridge(
+          client,
+          'network.intercept.clear',
+          {},
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else {
+        throw new Error('Usage: intercept <add|remove|list|clear> [args]');
+      }
+      return;
+    }
+
     if (command === 'eval') {
-      let expression = rest.join(' ');
+      const { tabId, rest: evalArgs } = extractTabFlag(rest);
+      // --await: wait for the result if the expression returns a Promise
+      const awaitIndex = evalArgs.indexOf('--await');
+      const awaitPromise = awaitIndex !== -1;
+      if (awaitIndex !== -1) evalArgs.splice(awaitIndex, 1);
+
+      let expression = evalArgs.join(' ');
       if (!expression || expression === '-') expression = await readStdin();
       if (!expression)
-        throw new Error('Usage: eval <expression>  (or pipe via stdin: echo "expr" | bbx eval -)');
+        throw new Error(
+          'Usage: eval [--tab <id>] [--await] <expression>  (or pipe via stdin: echo "expr" | bbx eval -)'
+        );
       const response = await requestBridge(
         client,
         'page.evaluate',
         {
           expression,
           returnByValue: true,
+          ...(awaitPromise ? { awaitPromise: true } : {}),
         },
-        { source: REQUEST_SOURCE }
+        { source: REQUEST_SOURCE, tabId }
       );
       await printSummary(response);
       return;

package/packages/agent-client/src/command-registry.js

@@ -76,6 +76,19 @@ export const SHORTCUT_COMMANDS = {
     (r, ref) => ({ target: { elementRef: ref }, text: r.slice(1).join(' ') }),
     { resolve: true }
   ),
+  fill: createShortcutCommand(
+    'input.fill',
+    'bbx fill <ref|selector> <value>',
+    (r, ref) => ({
+      target: { elementRef: ref },
+      value: r.slice(1).join(' '),
+      mode: 'auto',
+    }),
+    {
+      resolve: true,
+      description: 'Set input/textarea value (React/Vue/Angular-safe, auto fallback to keystrokes)',
+    }
+  ),
   hover: createShortcutCommand(
     'input.hover',
     'bbx hover <ref|selector>',
@@ -249,6 +262,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx tabs                                                           List available tabs',
       'bbx tab-create [url]                                               Create a new tab',
       'bbx tab-close <tabId>                                              Close a tab',
+      'bbx tab-activate <tabId>                                           Bring a tab to the foreground',
       'bbx skill                                                          Runtime budget presets and method groups',
       'bbx mcp serve                                                      Start Browser Bridge as an MCP stdio server',
     ],
@@ -261,6 +275,10 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       "bbx batch '[{method,params,tabId?},...]'                           Parallel method calls",
       'Advanced bridge params stay available through `bbx call`, even when shortcuts expose only the common case.',
       'For open-ended investigation, start with `bbx batch` on `page.get_state`, `dom.query`, and `page.get_text` before any screenshot or CDP call.',
+      '',
+      'Interaction methods need a target wrapper (not a bare ref):',
+      '  bbx call input.click \'{"target":{"elementRef":"el_xxx"}}\'',
+      '  bbx call input.type  \'{"target":{"elementRef":"el_xxx"},"text":"hello"}\'',
     ],
   },
   {
@@ -294,7 +312,11 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Page',
     lines: [
-      'bbx eval <expression>                                              Evaluate JS in page context (use - for stdin)',
+      'bbx intercept add <pattern> [--respond <body>] [--block]           Add a request interception rule',
+      'bbx intercept list                                                  List active interception rules',
+      'bbx intercept remove <ruleId>                                       Remove a rule',
+      'bbx intercept clear                                                 Remove all rules',
+      'bbx eval [--await] <expression>                                     Evaluate JS in page context (--await for async, - for stdin)',
       ...[
         'console',
         'network',
@@ -316,7 +338,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Interact',
     lines: [
-      ...['click', 'focus', 'type', 'hover'].map(
+      ...['click', 'focus', 'type', 'fill', 'hover'].map(
         (command) =>
           `${SHORTCUT_COMMANDS[command].usage.padEnd(64)} ${SHORTCUT_COMMANDS[command].description}`
       ),

package/packages/mcp-server/src/server.js

@@ -40,7 +40,7 @@ import {
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
-import { MCP_SERVER_INSTRUCTIONS, registerBridgeMcpGuidance } from './guidance.js';
+import { MCP_SERVER_INSTRUCTIONS } from './guidance.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
@@ -735,8 +735,6 @@ export function createBridgeMcpServer() {
     handleInvestigateTool
   );
 
-  registerBridgeMcpGuidance(server);
-
   return server;
 }
 

package/packages/protocol/src/capabilities.js

@@ -22,6 +22,7 @@ export const CAPABILITIES = Object.freeze({
   TABS_MANAGE: 'tabs.manage',
   PERFORMANCE_READ: 'performance.read',
   NETWORK_READ: 'network.read',
+  NETWORK_INTERCEPT: 'network.intercept',
 });
 
 export const DEFAULT_CAPABILITIES = Object.freeze([
@@ -43,6 +44,7 @@ export const DEFAULT_CAPABILITIES = Object.freeze([
   CAPABILITIES.TABS_MANAGE,
   CAPABILITIES.PERFORMANCE_READ,
   CAPABILITIES.NETWORK_READ,
+  CAPABILITIES.NETWORK_INTERCEPT,
 ]);
 
 /** @type {Readonly<Record<CapabilityMethod, Capability | null>>} */
@@ -51,6 +53,7 @@ export const METHOD_CAPABILITIES = Object.freeze({
   '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,
@@ -61,6 +64,12 @@ export const METHOD_CAPABILITIES = Object.freeze({
   '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,
@@ -83,6 +92,7 @@ export const METHOD_CAPABILITIES = Object.freeze({
   '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,

package/packages/protocol/src/protocol.js

@@ -380,6 +380,10 @@ function normalizeTarget(target) {
  */
 export function normalizeInputAction(params = {}) {
   const button = params.button === 'middle' || params.button === 'right' ? params.button : 'left';
+  const mode =
+    params.mode === 'setter' || params.mode === 'keystrokes' || params.mode === 'auto'
+      ? params.mode
+      : 'auto';
 
   return {
     target: normalizeTarget(
@@ -390,6 +394,8 @@ export function normalizeInputAction(params = {}) {
     button,
     clickCount: clampInt(params.clickCount, 1, 2, 1),
     text: typeof params.text === 'string' ? params.text : '',
+    value: typeof params.value === 'string' ? params.value : '',
+    mode,
     clear: Boolean(params.clear),
     submit: Boolean(params.submit),
     key: typeof params.key === 'string' ? params.key : '',

package/packages/protocol/src/registry.js

@@ -28,6 +28,7 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'tabs.list': 'List tabs in the enabled window.',
   'tabs.create': 'Create a new tab in the enabled window.',
   'tabs.close': 'Close a tab in the enabled window.',
+  'tabs.activate': 'Bring a tab to the foreground in the enabled window.',
   'skill.get_runtime_context': 'Return runtime method groups, budgets, and limits.',
   'setup.get_status': 'Return MCP and skill setup status.',
   'setup.install': 'Install or uninstall MCP or skill integration targets.',
@@ -38,6 +39,10 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   '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.',
+  '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.',
+  'network.intercept.clear': 'Remove all interception rules and disable interception.',
   'navigation.navigate': 'Navigate the current tab to a URL.',
   'navigation.reload': 'Reload the current tab.',
   'navigation.go_back': 'Navigate backward in tab history.',
@@ -60,6 +65,7 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   '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.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.',
@@ -130,6 +136,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
   '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.get_state': createRegistryEntry('page.get_state', 'page', true, [], 'low'),
   'page.evaluate': {
@@ -170,6 +177,35 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['clear', 'limit', 'urlPattern'],
     'low'
   ),
+  // network intercept — moderate (holds debugger session)
+  'network.intercept.add': createRegistryEntry(
+    'network.intercept.add',
+    'page',
+    true,
+    ['urlPattern', 'action', 'statusCode', 'body', 'headers'],
+    'moderate'
+  ),
+  'network.intercept.remove': createRegistryEntry(
+    'network.intercept.remove',
+    'page',
+    true,
+    ['ruleId'],
+    'trivial'
+  ),
+  'network.intercept.list': createRegistryEntry(
+    'network.intercept.list',
+    'page',
+    true,
+    [],
+    'trivial'
+  ),
+  'network.intercept.clear': createRegistryEntry(
+    'network.intercept.clear',
+    'page',
+    true,
+    [],
+    'low'
+  ),
   // navigation — low
   'navigation.navigate': createRegistryEntry(
     'navigation.navigate',
@@ -322,6 +358,13 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['target', 'text', 'clear', 'submit', 'modifiers'],
     'low'
   ),
+  'input.fill': createRegistryEntry(
+    'input.fill',
+    'interact',
+    true,
+    ['target', 'value', 'mode'],
+    'low'
+  ),
   'input.press_key': createRegistryEntry(
     'input.press_key',
     'interact',

package/packages/protocol/src/types.ts

@@ -18,7 +18,8 @@ export type Capability =
   | 'automation.input'
   | 'tabs.manage'
   | 'performance.read'
-  | 'network.read';
+  | 'network.read'
+  | 'network.intercept';
 
 export type ErrorCode =
   | 'ACCESS_DENIED'
@@ -37,6 +38,7 @@ export type BridgeMethod =
   | 'tabs.list'
   | 'tabs.create'
   | 'tabs.close'
+  | 'tabs.activate'
   | 'skill.get_runtime_context'
   | 'setup.get_status'
   | 'setup.install'
@@ -47,6 +49,10 @@ export type BridgeMethod =
   | 'page.get_storage'
   | 'page.get_text'
   | 'page.get_network'
+  | 'network.intercept.add'
+  | 'network.intercept.remove'
+  | 'network.intercept.list'
+  | 'network.intercept.clear'
   | 'navigation.navigate'
   | 'navigation.reload'
   | 'navigation.go_back'
@@ -69,6 +75,7 @@ export type BridgeMethod =
   | 'input.click'
   | 'input.focus'
   | 'input.type'
+  | 'input.fill'
   | 'input.press_key'
   | 'input.set_checked'
   | 'input.select_option'
@@ -215,6 +222,8 @@ export interface InputActionParams {
   button?: 'left' | 'middle' | 'right';
   clickCount?: number;
   text?: string;
+  value?: string;
+  mode?: 'auto' | 'setter' | 'keystrokes';
   clear?: boolean;
   submit?: boolean;
   key?: string;
@@ -226,6 +235,8 @@ export interface NormalizedInputAction extends BridgeParams {
   button: 'left' | 'middle' | 'right';
   clickCount: number;
   text: string;
+  value: string;
+  mode: 'auto' | 'setter' | 'keystrokes';
   clear: boolean;
   submit: boolean;
   key: string;

package/skills/browser-bridge/SKILL.md

@@ -30,6 +30,7 @@ bbx tabs                    # list available tabs (prefer this)
 bbx logs                    # recent bridge request log
 bbx tab-create [url]        # open a new tab (avoid unless necessary)
 bbx tab-close <tabId>       # close a tab
+bbx tab-activate <tabId>    # bring a tab to the foreground
 bbx skill                   # live runtime presets + limits
 ```
 
@@ -53,9 +54,11 @@ bbx a11y-tree [maxNodes] [maxDepth]  # accessibility tree
 ### Page & Evaluate
 
 ```bash
-bbx eval <expression>                # JS eval (- for stdin)
+bbx eval [--await] <expression>      # JS eval (--await for promises, - for stdin)
 bbx console [level]                  # console output
 bbx network [limit]                  # network requests
+bbx intercept add <pattern> [--respond <body>] [--status <code>] [--block]  # intercept matching requests
+bbx intercept list|remove <id>|clear # manage interception rules
 bbx page-text [budget]               # full page text
 bbx storage [local|session] [keys]   # browser storage
 bbx perf                             # performance metrics
@@ -73,6 +76,7 @@ bbx resize <width> <height>          # resize viewport
 bbx click <ref> [button]             # click element
 bbx focus <ref>                      # focus element
 bbx type <ref> <text...>             # type into element
+bbx fill <ref|selector> <value...>   # set input value (React/Vue/Angular-safe)
 bbx press-key <key> [ref]            # send key event
 bbx cdp-press-key --tab <id> Escape  # CDP key event without foreground focus
 bbx hover <ref>                      # hover over element
@@ -213,9 +217,9 @@ 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`                                                                                                                                  |
-| Interact    | `input.click`, `input.type`, `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`                                                                       |
+| 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`                                                                                           |
 | Navigate    | `navigation.navigate`, `viewport.scroll`, `viewport.resize`                                                                                         |
 | Performance | `performance.get_metrics` (debugger-backed)                                                                                                         |
@@ -283,7 +287,15 @@ Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. U
 ## CLI Raw Params Gotchas
 
 - Use `selector`, not `scope`, to narrow `dom.find_by_text` and `dom.find_by_role`.
-- Wrap interaction targets as `target: { elementRef }` or `target: { selector }`; `viewport.scroll` also uses the `target` wrapper for element scrolling.
+- Wrap interaction targets as `target: { elementRef }` or `target: { selector }`; `viewport.scroll` also uses the `target` wrapper for element scrolling. **Do not pass `ref` or `elementRef` at the top level** -- interaction methods require the nested `target` wrapper:
+  ```bash
+  # CORRECT
+  bbx call input.click '{"target":{"elementRef":"el_xxx"}}'
+  bbx call input.type  '{"target":{"elementRef":"el_xxx"},"text":"hello"}'
+  # WRONG -- will fail with "Target not found"
+  bbx call input.click '{"ref":"el_xxx"}'
+  bbx call input.click '{"elementRef":"el_xxx"}'
+  ```
 - `input.drag` uses `source`, `destination`, and optional destination offsets `offsetX` / `offsetY`.
 - Raw `screenshot.capture_region` and `screenshot.capture_full_page` return base64 JSON; prefer `bbx screenshot <ref> [outPath]` when one element is enough.
 

package/skills/browser-bridge/references/interaction.md

@@ -7,6 +7,7 @@
 | `input.click`            | `click <ref> [button]`                | DOM-level click                                             |
 | `input.focus`            | `focus <ref>`                         | Focus an element                                            |
 | `input.type`             | `type <ref> <text>`                   | Type into input/textarea/contenteditable                    |
+| `input.fill`             | `fill <ref> <value>`                  | Set field value via native setter (React/Vue/Angular-safe)  |
 | `input.press_key`        | `press-key <key> [ref]`               | Send keyboard key (Enter, Backspace, etc.)                  |
 | `cdp.dispatch_key_event` | `cdp-press-key --tab <id> <key>`      | CDP keyDown/keyUp without focusing the target tab           |
 | `input.set_checked`      | `call input.set_checked '{...}'`      | Toggle checkbox/radio                                       |
@@ -64,6 +65,7 @@ bbx tabs                                 # list available tabs (start here)
 bbx tab-create https://example.com       # open new tab (avoid unless necessary)
 bbx tab-create                           # open blank tab (avoid unless necessary)
 bbx tab-close 12345                      # close tab by ID
+bbx tab-activate 12345                   # bring a tab to the foreground
 bbx call tabs.create '{"url":"https://example.com","active":false}'
 ```
 
@@ -156,6 +158,24 @@ Typical workflow - debug API calls:
 3. Cross-reference with `page.get_console` for errors
 4. Use `page.evaluate` to replay or inspect response data
 
+## Network Interception
+
+Block, stub, or modify matching requests via CDP (debugger-backed). Patterns are globs: `*` matches any characters, `?` matches one character.
+
+```bash
+bbx intercept add 'https://api.example.com/users*' --respond '{"users":[]}' --status 200
+bbx intercept add '*analytics*' --block      # fail matching requests
+bbx intercept list                           # active rules
+bbx intercept remove intercept_1
+bbx intercept clear                          # remove all rules, detach debugger
+```
+
+Caveats:
+
+- Rules are **in-memory and per-tab**. They drop silently if the debugger detaches (user dismisses the infobar, tab closes, extension service worker restarts). Verify with `bbx intercept list` before relying on them.
+- Sessions auto-expire after 10 minutes as a safety net.
+- Always `bbx intercept clear` when finished so the page returns to normal traffic.
+
 ## Form Controls
 
 **Checkbox/radio:**
@@ -172,6 +192,15 @@ 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`:**
+
+```bash
+bbx fill el_123 hello@example.com        # set value instantly (preferred for forms)
+bbx type el_123 hello                    # simulate per-character keystrokes
+```
+
+Prefer `fill` for setting form values: it uses the native prototype setter plus `input`/`change`/`blur` events, which React, Vue, and Angular pick up reliably. `mode` defaults to `auto` (setter first, keystroke fallback if the value did not stick); pass `"mode":"keystrokes"` via `bbx call input.fill` for components that only react to per-key events. Use `type` when page logic depends on individual key events (autocomplete, masked inputs).
+
 ## Hover
 
 Dispatch mouse events to trigger CSS `:hover` rules, tooltip display, dropdown menus, etc.
@@ -263,6 +292,24 @@ bbx call page.wait_for_load_state '{"timeoutMs":10000}'
 
 Use after clicking navigation links.
 
+## Raw `bbx call` for Interaction Methods
+
+All interaction methods (`input.click`, `input.type`, `input.focus`, `input.hover`, etc.) require the target wrapped in a `target` object -- do not pass `ref` or `elementRef` at the top level:
+
+```bash
+# CORRECT
+bbx call input.click '{"target":{"elementRef":"el_xxx"}}'
+bbx call input.click '{"target":{"elementRef":"el_xxx"},"button":"right"}'
+bbx call input.type  '{"target":{"elementRef":"el_xxx"},"text":"hello"}'
+bbx call input.focus '{"target":{"selector":"#search-input"}}'
+
+# WRONG -- "Target not found"
+bbx call input.click '{"ref":"el_xxx"}'
+bbx call input.click '{"elementRef":"el_xxx"}'
+```
+
+The CLI shortcuts (`bbx click el_xxx`) handle this wrapping automatically, but `bbx call` passes params as-is.
+
 ## Interaction Flow
 
 1. **Find target**: `dom.find_by_text`, `dom.find_by_role`, or `dom.query` → get `elementRef`

package/skills/browser-bridge/references/protocol.md

@@ -90,6 +90,12 @@ The table below includes the legacy capability bucket for each method so agents
 | 57  | `cdp.get_box_model`                | Yes  | CDP  | cdp         | `cdp.box_model`      | DevTools-backed element geometry                                        |
 | 58  | `cdp.get_computed_styles_for_node` | Yes  | CDP  | cdp         | `cdp.styles`         | DevTools-backed computed styles                                         |
 | 59  | `cdp.dispatch_key_event`           | Yes  | CDP  | cdp         | `cdp.input`          | DevTools keyDown/keyUp without foreground focus                         |
+| 60  | `tabs.activate`                    | No   | -    | tabs        | `tabs.manage`        | Bring a tab to the foreground in the enabled window                     |
+| 61  | `input.fill`                       | Yes  | -    | interact    | `automation.input`   | Set field value via native setter; `mode`: auto/setter/keystrokes       |
+| 62  | `network.intercept.add`            | Yes  | CDP  | page        | `network.intercept`  | Add interception rule; action fulfill/continue/block                    |
+| 63  | `network.intercept.remove`         | Yes  | CDP  | page        | `network.intercept`  | Remove rule by `ruleId`                                                 |
+| 64  | `network.intercept.list`           | Yes  | CDP  | page        | `network.intercept`  | List active rules (rules drop on debugger detach)                       |
+| 65  | `network.intercept.clear`          | Yes  | CDP  | page        | `network.intercept`  | Remove all rules, detach debugger                                       |
 
 ## CLI