@browserbridge/bbx 1.0.0 → 1.1.0

package/packages/protocol/src/types.js

@@ -7,7 +7,7 @@ export {};
  */
 
 /**
- * @typedef {'page.read' | 'page.evaluate' | 'dom.read' | 'styles.read' | 'layout.read' | 'viewport.control' | 'navigation.control' | 'screenshot.partial' | 'patch.dom' | 'patch.styles' | 'cdp.dom_snapshot' | 'cdp.box_model' | 'cdp.styles' | 'automation.input' | 'tabs.manage' | 'performance.read' | 'network.read'} Capability
+ * @typedef {'page.read' | 'page.evaluate' | 'dom.read' | 'styles.read' | 'layout.read' | 'viewport.control' | 'navigation.control' | 'screenshot.partial' | 'patch.dom' | 'patch.styles' | 'cdp.dom_snapshot' | 'cdp.box_model' | 'cdp.styles' | 'cdp.input' | 'automation.input' | 'tabs.manage' | 'performance.read' | 'network.read'} Capability
  */
 
 /**
@@ -15,7 +15,7 @@ export {};
  */
 
 /**
- * @typedef {'access.request' | 'tabs.list' | 'tabs.create' | 'tabs.close' | 'skill.get_runtime_context' | 'setup.get_status' | 'setup.install' | 'page.get_state' | 'page.evaluate' | 'page.get_console' | 'page.wait_for_load_state' | 'page.get_storage' | 'page.get_text' | 'page.get_network' | 'navigation.navigate' | 'navigation.reload' | 'navigation.go_back' | 'navigation.go_forward' | 'dom.query' | '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' | 'viewport.scroll' | 'viewport.resize' | 'input.click' | 'input.focus' | 'input.type' | 'input.press_key' | 'input.set_checked' | 'input.select_option' | 'input.hover' | 'input.drag' | 'input.scroll_into_view' | 'screenshot.capture_region' | 'screenshot.capture_element' | 'screenshot.capture_full_page' | 'patch.apply_styles' | 'patch.apply_dom' | 'patch.list' | 'patch.rollback' | 'patch.commit_session_baseline' | 'cdp.get_document' | 'cdp.get_dom_snapshot' | 'cdp.get_box_model' | 'cdp.get_computed_styles_for_node' | 'performance.get_metrics' | 'log.tail' | 'health.ping'} BridgeMethod
+ * @typedef {'access.request' | 'tabs.list' | 'tabs.create' | 'tabs.close' | 'skill.get_runtime_context' | 'setup.get_status' | 'setup.install' | 'page.get_state' | 'page.evaluate' | 'page.get_console' | 'page.wait_for_load_state' | 'page.get_storage' | 'page.get_text' | 'page.get_network' | 'navigation.navigate' | 'navigation.reload' | 'navigation.go_back' | 'navigation.go_forward' | 'dom.query' | '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' | 'viewport.scroll' | 'viewport.resize' | 'input.click' | 'input.focus' | 'input.type' | 'input.press_key' | 'input.set_checked' | 'input.select_option' | 'input.hover' | 'input.drag' | 'input.scroll_into_view' | 'screenshot.capture_region' | 'screenshot.capture_element' | 'screenshot.capture_full_page' | 'patch.apply_styles' | 'patch.apply_dom' | 'patch.list' | 'patch.rollback' | 'patch.commit_session_baseline' | 'cdp.get_document' | 'cdp.get_dom_snapshot' | 'cdp.get_box_model' | 'cdp.get_computed_styles_for_node' | 'cdp.dispatch_key_event' | 'performance.get_metrics' | 'log.tail' | 'health.ping'} BridgeMethod
  */
 
 /**
@@ -38,7 +38,7 @@ export {};
  *   budget_applied?: boolean,
  *   budget_truncated?: boolean,
  *   continuation_hint?: string | null,
-   *   [key: string]: unknown
+ *   [key: string]: unknown
  * }} BridgeMeta
  */
 
@@ -52,11 +52,20 @@ export {};
  * }} BridgeRequest
  */
 
+/**
+ * @typedef {{
+ *   hint: string,
+ *   retry?: boolean,
+ *   retryAfterMs?: number
+ * }} BridgeRecovery
+ */
+
 /**
  * @typedef {{
  *   code: ErrorCode,
  *   message: string,
- *   details: unknown
+ *   details: unknown,
+ *   recovery?: BridgeRecovery
  * }} BridgeFailure
  */
 
@@ -187,6 +196,22 @@ export {};
  * }} NormalizedInputAction
  */
 
+/**
+ * @typedef {{
+ *   key?: string,
+ *   code?: string,
+ *   modifiers?: string[] | number
+ * }} CdpDispatchKeyEventParams
+ */
+
+/**
+ * @typedef {{
+ *   key: string,
+ *   code: string,
+ *   modifiers: string[] | number
+ * }} NormalizedCdpDispatchKeyEventParams
+ */
+
 /**
  * @typedef {{
  *   target?: InputTarget,

package/skills/browser-bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-bridge
-description: "Token-efficient Chrome tab inspection, interaction, and patching via local bridge extension (CLI: bbx). Reads live DOM, styles, console, network, and storage from a real Chrome tab with lower token cost than screenshots."
+description: 'Token-efficient Chrome tab inspection, interaction, and patching via local bridge extension (CLI: bbx). Reads live DOM, styles, console, network, and storage from a real Chrome tab with lower token cost than screenshots.'
 ---
 
 # Browser Bridge
@@ -69,6 +69,7 @@ bbx click <ref> [button]             # click element
 bbx focus <ref>                      # focus element
 bbx type <ref> <text...>             # type into element
 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
 bbx call input.scroll_into_view '{"target":{"elementRef":"el_123"}}' # ensure target is visible
 bbx patch-style <ref> prop=val...    # apply style patch
@@ -202,7 +203,7 @@ bbx page-text 2000                                  # extract page content
 | 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`, `input.hover`, `input.drag`, `input.scroll_into_view`                                |
+| 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`                                                                       |
 | Patch       | `patch.apply_styles`, `patch.apply_dom`, `patch.rollback`                                                                                           |
 | Navigate    | `navigation.navigate`, `viewport.scroll`, `viewport.resize`                                                                                         |

package/skills/browser-bridge/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Browser Bridge"
-  short_description: "Token-efficient Chrome tab inspection, interaction, and patching via local bridge"
-  default_prompt: "Use the browser-bridge skill for Chrome tab inspection, interaction, and patching. Start with `bbx status` to confirm connectivity. If ACCESS_DENIED, ask the user to click Enable in the extension popup/side panel, then retry. Default routing follows the active tab; use `--tab` only for a different tab. Prefer structured reads (`dom.query`, `styles.get_computed`) over screenshots. Batch independent reads with `bbx batch`. Use `bbx skill` for runtime presets."
+  display_name: 'Browser Bridge'
+  short_description: 'Token-efficient Chrome tab inspection, interaction, and patching via local bridge'
+  default_prompt: 'Use the browser-bridge skill for Chrome tab inspection, interaction, and patching. Start with `bbx status` to confirm connectivity. If ACCESS_DENIED, ask the user to click Enable in the extension popup/side panel, then retry. Default routing follows the active tab; use `--tab` only for a different tab. Prefer structured reads (`dom.query`, `styles.get_computed`) over screenshots. Batch independent reads with `bbx batch`. Use `bbx skill` for runtime presets.'

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

@@ -2,17 +2,18 @@
 
 ## Input Methods
 
-| Method | CLI Shortcut | Purpose |
-|--------|-------------|---------|
-| `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.press_key` | `press-key <key> [ref]` | Send keyboard key (Enter, Backspace, etc.) |
-| `input.set_checked` | `call input.set_checked '{...}'` | Toggle checkbox/radio |
-| `input.select_option` | `call input.select_option '{...}'` | Select native `<select>` by value/label/index |
-| `input.hover` | `hover <ref>` | Trigger CSS `:hover` state (mouseenter/mouseover/mousemove) |
-| `input.drag` | `call input.drag '{...}'` | Full drag-and-drop event sequence |
-| `input.scroll_into_view` | `call input.scroll_into_view '{...}'` | Ensure a target is visible before inspect/capture |
+| Method                   | CLI Shortcut                          | Purpose                                                     |
+| ------------------------ | ------------------------------------- | ----------------------------------------------------------- |
+| `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.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                                       |
+| `input.select_option`    | `call input.select_option '{...}'`    | Select native `<select>` by value/label/index               |
+| `input.hover`            | `hover <ref>`                         | Trigger CSS `:hover` state (mouseenter/mouseover/mousemove) |
+| `input.drag`             | `call input.drag '{...}'`             | Full drag-and-drop event sequence                           |
+| `input.scroll_into_view` | `call input.scroll_into_view '{...}'` | Ensure a target is visible before inspect/capture           |
 
 ## Navigation
 
@@ -39,6 +40,7 @@ Scrolls the window or a specific scrollable element.
 ### Resize Viewport
 
 Set device viewport dimensions (useful for responsive testing):
+
 ```bash
 bbx resize 375 812                           # iPhone-size
 bbx resize 1024 768                          # tablet
@@ -50,6 +52,7 @@ Uses CDP device emulation - the page re-renders at the new size immediately.
 ## Tab Management
 
 **IMPORTANT: Prefer existing tabs.** Never create new tabs unless:
+
 - The user explicitly requests opening a new page
 - The task requires a clean/fresh page state (e.g., testing initial load)
 - You need to compare multiple pages simultaneously
@@ -65,6 +68,7 @@ bbx call tabs.create '{"url":"https://example.com","active":false}'
 ```
 
 Typical workflow - compare two pages (only when comparison is required):
+
 1. `tabs.list` to see current tabs
 2. `tabs.create` with second URL
 3. Inspect both tabs (`--tab <id>` or MCP `tabId` only when you need the non-active tab)
@@ -83,6 +87,7 @@ bbx call dom.get_accessibility_tree '{"maxNodes":100,"maxDepth":5}'
 Each node: `role`, `name`, `description`, `value`, `focused`, `required`, `checked`, `disabled`, `interactive`, `childIds`.
 
 Typical workflow - find interactive controls:
+
 1. `dom.get_accessibility_tree` with small `maxNodes`
 2. Scan for nodes with `interactive: true`
 3. Use role/name to identify the right control
@@ -103,6 +108,7 @@ bbx call --tab 200 dom.query '{"selector":"main"}'
 ```
 
 Open a new tab programmatically:
+
 ```bash
 bbx tab-create https://example.com   # creates a new tab in the enabled window
 bbx call --tab <new-tabId> page.get_state
@@ -127,6 +133,7 @@ Scrolls the window by default. Pass an `elementRef` to scroll an inner scrollabl
 ### Scroll target into view
 
 Use this when the page has nested containers or when you want the target centered before a screenshot or hover:
+
 ```bash
 bbx call input.scroll_into_view '{"target":{"elementRef":"el_123"}}'
 bbx call input.scroll_into_view '{"target":{"selector":"[data-testid=\"submit-button\"]"}}'
@@ -143,6 +150,7 @@ bbx call page.get_network '{"limit":20,"clear":true}'
 Each entry: `method`, `url`, `status`, `duration`, `initiator`.
 
 Typical workflow - debug API calls:
+
 1. `page.get_network` to see recent requests
 2. Filter by URL pattern or status code
 3. Cross-reference with `page.get_console` for errors
@@ -151,11 +159,13 @@ Typical workflow - debug API calls:
 ## Form Controls
 
 **Checkbox/radio:**
+
 ```bash
 bbx call input.set_checked '{"target":{"elementRef":"el_123"},"checked":true}'
 ```
 
 **Select dropdown:**
+
 ```bash
 bbx call input.select_option '{"target":{"elementRef":"el_456"},"values":["us"]}'
 ```
@@ -172,11 +182,13 @@ bbx call input.hover '{"target":{"elementRef":"el_abc123"}}'
 ```
 
 **Hold hover for inspection:** set `duration` (ms) to keep hover active before auto-releasing with `mouseleave`:
+
 ```bash
 bbx call input.hover '{"target":{"elementRef":"el_abc123"},"duration":2000}'
 ```
 
 Typical workflow - inspect a tooltip:
+
 1. `dom.query` to find the trigger element → `elementRef`
 2. `input.hover` with `duration: 2000`
 3. While hover holds, `dom.query` for tooltip content (e.g. `[role="tooltip"]`)
@@ -191,6 +203,7 @@ bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRe
 ```
 
 With pixel offsets for precise positioning:
+
 ```bash
 bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"sourceOffset":{"x":10,"y":10},"destinationOffset":{"x":5,"y":5}}'
 ```
@@ -198,6 +211,7 @@ bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRe
 Event sequence: `mousedown → dragstart → drag → dragenter → dragover → drop → dragend → mouseup`.
 
 Typical workflow - reorder a list:
+
 1. `dom.query` to find draggable items → get source and destination `elementRef` values
 2. `input.drag` from source to destination
 3. `dom.wait_for` to confirm the DOM updated
@@ -206,16 +220,21 @@ Typical workflow - reorder a list:
 ## Finding Elements
 
 ### By text content
+
 Find elements matching visible text. Faster than `dom.query` when you know the label:
+
 ```bash
 bbx find 'Submit Order'
 bbx call dom.find_by_text '{"text":"Add to Cart","scope":"button","exact":false}'
 ```
+
 - `scope`: optional CSS selector to narrow search (e.g. `"button"`, `".sidebar"`)
 - `exact`: `true` for exact match, `false` (default) for substring/case-insensitive
 
 ### By ARIA role
+
 Find elements by explicit `role` attribute or implicit HTML role (e.g. `<nav>` → `navigation`):
+
 ```bash
 bbx find-role button 'Save'
 bbx call dom.find_by_role '{"role":"navigation"}'
@@ -225,19 +244,23 @@ bbx call dom.find_by_role '{"role":"heading","name":"Dashboard"}'
 ## Waiting
 
 ### Wait for DOM condition
+
 ```bash
 bbx wait '.success-message' 10000
 bbx call dom.wait_for '{"selector":".modal","state":"visible","timeoutMs":10000}'
 bbx call dom.wait_for '{"selector":".spinner","state":"detached","timeoutMs":5000}'
 ```
+
 - `state`: `attached` (exists in DOM), `detached` (removed), `visible` (non-zero size), `hidden`
 - Uses MutationObserver + 250 ms polling fallback
 - Returns `{found, elementRef, duration}` - NOT an error on timeout
 
 ### Wait for page load
+
 ```bash
 bbx call page.wait_for_load_state '{"timeoutMs":10000}'
 ```
+
 Use after clicking navigation links.
 
 ## Interaction Flow

package/skills/browser-bridge/references/patch-workflow.md

@@ -12,6 +12,7 @@ Use this order for layout or styling issues:
 6. `patch.rollback`
 
 Prefer style patches for:
+
 - overflow fixes
 - spacing adjustments
 - flex or grid tuning
@@ -21,6 +22,7 @@ Prefer style patches for:
 ## DOM patch loop
 
 Use DOM patches for:
+
 - text replacement
 - setting or removing an attribute
 - toggling a class
@@ -30,6 +32,7 @@ Keep DOM patches minimal and reversible.
 ## Verification
 
 After any patch:
+
 - compare box metrics when geometry matters
 - compare computed styles when appearance matters
 - capture a cropped screenshot only when the visual outcome is still unclear