@browserbridge/bbx 1.0.0 → 1.0.1

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

@@ -2,17 +2,17 @@
 
 ## 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.)                  |
+| `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 +39,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 +51,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 +67,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 +86,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 +107,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 +132,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 +149,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 +158,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 +181,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 +202,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 +210,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 +219,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 +243,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

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

@@ -29,65 +29,65 @@ The table below includes the legacy capability bucket for each method so agents
 
 ## All Methods (57)
 
-| # | Method | Tab? | CDP? | Group | Capability | Notes |
-|---|--------|------|------|-------|------------|-------|
-| 1 | `access.request` | No | - | system | `-` | Request window access; surfaces Enable prompt in extension UI |
-| 2 | `tabs.list` | No | - | tabs | `-` | Discover available tabs |
-| 3 | `tabs.create` | No | - | tabs | `tabs.manage` | Open a new tab; optional `url` and `active` |
-| 4 | `tabs.close` | No | - | tabs | `tabs.manage` | Close a tab by `tabId` |
-| 5 | `skill.get_runtime_context` | No | - | system | `-` | Live budget presets + method groups |
-| 6 | `setup.get_status` | No | - | system | `-` | Global MCP config + CLI skill install status |
-| 7 | `setup.install` | No | - | system | `-` | Install or uninstall MCP/skill integration targets |
-| 8 | `health.ping` | No | - | system | `-` | Connectivity check + access routing state |
-| 9 | `log.tail` | No | - | system | `-` | Recent bridge logs |
-| 10 | `page.get_state` | Yes | - | page | `page.read` | URL, readiness, focus, scroll, viewport |
-| 11 | `page.evaluate` | Yes | CDP | page | `page.evaluate` | JS expression in page context; last resort |
-| 12 | `page.get_console` | Yes | - | page | `page.read` | Buffered console messages; filter by `level`, `limit` |
-| 13 | `page.wait_for_load_state` | Yes | - | wait | `page.read` | Block until tab `complete`; `timeoutMs` capped 30 s |
-| 14 | `page.get_storage` | Yes | - | page | `page.read` | `localStorage`/`sessionStorage`; optional `keys` |
-| 15 | `page.get_text` | Yes | - | page | `page.read` | Full page text; `textBudget` limits size |
-| 16 | `page.get_network` | Yes | - | page | `network.read` | Intercepted fetch/XHR; `limit` entries |
-| 17 | `navigation.navigate` | Yes | - | navigate | `navigation.control` | Go to URL; `waitForLoad` default true |
-| 18 | `navigation.reload` | Yes | - | navigate | `navigation.control` | Reload; `waitForLoad` default true |
-| 19 | `navigation.go_back` | Yes | - | navigate | `navigation.control` | History back |
-| 20 | `navigation.go_forward` | Yes | - | navigate | `navigation.control` | History forward |
-| 21 | `dom.query` | Yes | - | inspect | `dom.read` | Query subtree with budget constraints |
-| 22 | `dom.describe` | Yes | - | inspect | `dom.read` | Single element details via `elementRef` |
-| 23 | `dom.get_text` | Yes | - | inspect | `dom.read` | Text content with `textBudget` |
-| 24 | `dom.get_attributes` | Yes | - | inspect | `dom.read` | Targeted attribute read |
-| 25 | `dom.wait_for` | Yes | - | wait | `dom.read` | Wait for DOM condition; MutationObserver + polling |
-| 26 | `dom.find_by_text` | Yes | - | inspect | `dom.read` | Find by visible text; returns `{nodes, count}` |
-| 27 | `dom.find_by_role` | Yes | - | inspect | `dom.read` | Find by ARIA role; optional `name` filter |
-| 28 | `dom.get_html` | Yes | - | inspect | `dom.read` | `innerHTML`/`outerHTML`; `maxLength` truncation |
-| 29 | `dom.get_accessibility_tree` | Yes | CDP | inspect | `dom.read` | Full a11y tree; `maxNodes`/`maxDepth` limits |
-| 30 | `layout.get_box_model` | Yes | - | inspect | `layout.read` | Element geometry (no budget needed) |
-| 31 | `layout.hit_test` | Yes | - | inspect | `layout.read` | Element at viewport point |
-| 32 | `styles.get_computed` | Yes | - | inspect | `styles.read` | Computed CSS; always set `properties` |
-| 33 | `styles.get_matched_rules` | Yes | - | inspect | `styles.read` | Matching CSS rules |
-| 34 | `viewport.scroll` | Yes | - | navigate | `viewport.control` | Window or element scroll |
-| 35 | `viewport.resize` | Yes | CDP | navigate | `viewport.control` | Set viewport via device emulation; `reset: true` |
-| 36 | `input.click` | Yes | - | interact | `automation.input` | DOM-level click |
-| 37 | `input.focus` | Yes | - | interact | `automation.input` | Focus element |
-| 38 | `input.type` | Yes | - | interact | `automation.input` | Type into input/textarea/contenteditable |
-| 39 | `input.press_key` | Yes | - | interact | `automation.input` | Single key event |
-| 40 | `input.set_checked` | Yes | - | interact | `automation.input` | Checkbox/radio toggle |
-| 41 | `input.select_option` | Yes | - | interact | `automation.input` | Native select by value/label/index |
-| 42 | `input.hover` | Yes | - | interact | `automation.input` | mouseenter/mouseover/mousemove; optional `duration` |
-| 43 | `input.drag` | Yes | - | interact | `automation.input` | Full drag-and-drop event sequence |
-| 44 | `input.scroll_into_view` | Yes | - | interact | `automation.input` | Explicitly scroll target into view before inspect/capture |
-| 45 | `screenshot.capture_element` | Yes | CDP | capture | `screenshot.partial` | Cropped element screenshot |
-| 46 | `screenshot.capture_region` | Yes | CDP | capture | `screenshot.partial` | Cropped viewport region |
-| 47 | `screenshot.capture_full_page` | Yes | CDP | capture | `screenshot.partial` | Full document screenshot; use only when page-level context is necessary |
-| 48 | `patch.apply_styles` | Yes | - | patch | `patch.styles` | Reversible CSS patch; `verify` returns computed result |
-| 49 | `patch.apply_dom` | Yes | - | patch | `patch.dom` | Reversible DOM mutation; `verify` returns result |
-| 50 | `patch.list` | Yes | - | patch | `patch.dom` | Active patches |
-| 51 | `patch.rollback` | Yes | - | patch | `patch.dom` | Revert one patch |
-| 52 | `patch.commit_session_baseline` | Yes | - | patch | `patch.dom` | Accept current state as baseline |
-| 53 | `performance.get_metrics` | Yes | CDP | performance | `performance.read` | Chrome performance counters |
-| 54 | `cdp.get_document` | Yes | CDP | cdp | `cdp.dom_snapshot` | DevTools document tree |
-| 55 | `cdp.get_dom_snapshot` | Yes | CDP | cdp | `cdp.dom_snapshot` | DevTools DOM snapshot |
-| 56 | `cdp.get_box_model` | Yes | CDP | cdp | `cdp.box_model` | DevTools-backed element geometry |
-| 57 | `cdp.get_computed_styles_for_node` | Yes | CDP | cdp | `cdp.styles` | DevTools-backed computed styles |
+| #   | Method                             | Tab? | CDP? | Group       | Capability           | Notes                                                                   |
+| --- | ---------------------------------- | ---- | ---- | ----------- | -------------------- | ----------------------------------------------------------------------- |
+| 1   | `access.request`                   | No   | -    | system      | `-`                  | Request window access; surfaces Enable prompt in extension UI           |
+| 2   | `tabs.list`                        | No   | -    | tabs        | `-`                  | Discover available tabs                                                 |
+| 3   | `tabs.create`                      | No   | -    | tabs        | `tabs.manage`        | Open a new tab; optional `url` and `active`                             |
+| 4   | `tabs.close`                       | No   | -    | tabs        | `tabs.manage`        | Close a tab by `tabId`                                                  |
+| 5   | `skill.get_runtime_context`        | No   | -    | system      | `-`                  | Live budget presets + method groups                                     |
+| 6   | `setup.get_status`                 | No   | -    | system      | `-`                  | Global MCP config + CLI skill install status                            |
+| 7   | `setup.install`                    | No   | -    | system      | `-`                  | Install or uninstall MCP/skill integration targets                      |
+| 8   | `health.ping`                      | No   | -    | system      | `-`                  | Connectivity check + access routing state                               |
+| 9   | `log.tail`                         | No   | -    | system      | `-`                  | Recent bridge logs                                                      |
+| 10  | `page.get_state`                   | Yes  | -    | page        | `page.read`          | URL, readiness, focus, scroll, viewport                                 |
+| 11  | `page.evaluate`                    | Yes  | CDP  | page        | `page.evaluate`      | JS expression in page context; last resort                              |
+| 12  | `page.get_console`                 | Yes  | -    | page        | `page.read`          | Buffered console messages; filter by `level`, `limit`                   |
+| 13  | `page.wait_for_load_state`         | Yes  | -    | wait        | `page.read`          | Block until tab `complete`; `timeoutMs` capped 30 s                     |
+| 14  | `page.get_storage`                 | Yes  | -    | page        | `page.read`          | `localStorage`/`sessionStorage`; optional `keys`                        |
+| 15  | `page.get_text`                    | Yes  | -    | page        | `page.read`          | Full page text; `textBudget` limits size                                |
+| 16  | `page.get_network`                 | Yes  | -    | page        | `network.read`       | Intercepted fetch/XHR; `limit` entries                                  |
+| 17  | `navigation.navigate`              | Yes  | -    | navigate    | `navigation.control` | Go to URL; `waitForLoad` default true                                   |
+| 18  | `navigation.reload`                | Yes  | -    | navigate    | `navigation.control` | Reload; `waitForLoad` default true                                      |
+| 19  | `navigation.go_back`               | Yes  | -    | navigate    | `navigation.control` | History back                                                            |
+| 20  | `navigation.go_forward`            | Yes  | -    | navigate    | `navigation.control` | History forward                                                         |
+| 21  | `dom.query`                        | Yes  | -    | inspect     | `dom.read`           | Query subtree with budget constraints                                   |
+| 22  | `dom.describe`                     | Yes  | -    | inspect     | `dom.read`           | Single element details via `elementRef`                                 |
+| 23  | `dom.get_text`                     | Yes  | -    | inspect     | `dom.read`           | Text content with `textBudget`                                          |
+| 24  | `dom.get_attributes`               | Yes  | -    | inspect     | `dom.read`           | Targeted attribute read                                                 |
+| 25  | `dom.wait_for`                     | Yes  | -    | wait        | `dom.read`           | Wait for DOM condition; MutationObserver + polling                      |
+| 26  | `dom.find_by_text`                 | Yes  | -    | inspect     | `dom.read`           | Find by visible text; returns `{nodes, count}`                          |
+| 27  | `dom.find_by_role`                 | Yes  | -    | inspect     | `dom.read`           | Find by ARIA role; optional `name` filter                               |
+| 28  | `dom.get_html`                     | Yes  | -    | inspect     | `dom.read`           | `innerHTML`/`outerHTML`; `maxLength` truncation                         |
+| 29  | `dom.get_accessibility_tree`       | Yes  | CDP  | inspect     | `dom.read`           | Full a11y tree; `maxNodes`/`maxDepth` limits                            |
+| 30  | `layout.get_box_model`             | Yes  | -    | inspect     | `layout.read`        | Element geometry (no budget needed)                                     |
+| 31  | `layout.hit_test`                  | Yes  | -    | inspect     | `layout.read`        | Element at viewport point                                               |
+| 32  | `styles.get_computed`              | Yes  | -    | inspect     | `styles.read`        | Computed CSS; always set `properties`                                   |
+| 33  | `styles.get_matched_rules`         | Yes  | -    | inspect     | `styles.read`        | Matching CSS rules                                                      |
+| 34  | `viewport.scroll`                  | Yes  | -    | navigate    | `viewport.control`   | Window or element scroll                                                |
+| 35  | `viewport.resize`                  | Yes  | CDP  | navigate    | `viewport.control`   | Set viewport via device emulation; `reset: true`                        |
+| 36  | `input.click`                      | Yes  | -    | interact    | `automation.input`   | DOM-level click                                                         |
+| 37  | `input.focus`                      | Yes  | -    | interact    | `automation.input`   | Focus element                                                           |
+| 38  | `input.type`                       | Yes  | -    | interact    | `automation.input`   | Type into input/textarea/contenteditable                                |
+| 39  | `input.press_key`                  | Yes  | -    | interact    | `automation.input`   | Single key event                                                        |
+| 40  | `input.set_checked`                | Yes  | -    | interact    | `automation.input`   | Checkbox/radio toggle                                                   |
+| 41  | `input.select_option`              | Yes  | -    | interact    | `automation.input`   | Native select by value/label/index                                      |
+| 42  | `input.hover`                      | Yes  | -    | interact    | `automation.input`   | mouseenter/mouseover/mousemove; optional `duration`                     |
+| 43  | `input.drag`                       | Yes  | -    | interact    | `automation.input`   | Full drag-and-drop event sequence                                       |
+| 44  | `input.scroll_into_view`           | Yes  | -    | interact    | `automation.input`   | Explicitly scroll target into view before inspect/capture               |
+| 45  | `screenshot.capture_element`       | Yes  | CDP  | capture     | `screenshot.partial` | Cropped element screenshot                                              |
+| 46  | `screenshot.capture_region`        | Yes  | CDP  | capture     | `screenshot.partial` | Cropped viewport region                                                 |
+| 47  | `screenshot.capture_full_page`     | Yes  | CDP  | capture     | `screenshot.partial` | Full document screenshot; use only when page-level context is necessary |
+| 48  | `patch.apply_styles`               | Yes  | -    | patch       | `patch.styles`       | Reversible CSS patch; `verify` returns computed result                  |
+| 49  | `patch.apply_dom`                  | Yes  | -    | patch       | `patch.dom`          | Reversible DOM mutation; `verify` returns result                        |
+| 50  | `patch.list`                       | Yes  | -    | patch       | `patch.dom`          | Active patches                                                          |
+| 51  | `patch.rollback`                   | Yes  | -    | patch       | `patch.dom`          | Revert one patch                                                        |
+| 52  | `patch.commit_session_baseline`    | Yes  | -    | patch       | `patch.dom`          | Accept current state as baseline                                        |
+| 53  | `performance.get_metrics`          | Yes  | CDP  | performance | `performance.read`   | Chrome performance counters                                             |
+| 54  | `cdp.get_document`                 | Yes  | CDP  | cdp         | `cdp.dom_snapshot`   | DevTools document tree                                                  |
+| 55  | `cdp.get_dom_snapshot`             | Yes  | CDP  | cdp         | `cdp.dom_snapshot`   | DevTools DOM snapshot                                                   |
+| 56  | `cdp.get_box_model`                | Yes  | CDP  | cdp         | `cdp.box_model`      | DevTools-backed element geometry                                        |
+| 57  | `cdp.get_computed_styles_for_node` | Yes  | CDP  | cdp         | `cdp.styles`         | DevTools-backed computed styles                                         |
 
 ## CLI
 
@@ -105,19 +105,24 @@ Newer bridge methods such as `input.scroll_into_view` and `screenshot.capture_fu
 ## Method Details
 
 ### access.request
+
 Request Browser Bridge access for the focused browser window. Surfaces an Enable prompt in the extension popup or side panel so the user can grant access. Does not require an existing session.
+
 ```bash
 bbx access-request
 bbx call access.request
 ```
+
 If a tab-bound call returns `ACCESS_DENIED`, it also surfaces the Enable prompt automatically — so explicit `access.request` is optional but useful for proactive setup.
 
 If access is already pending for a window, do not call `access.request` again. Ask the user to click `Enable` for the requested window and wait for confirmation before continuing.
 
 ### page.evaluate
+
 Run a JS expression in the page context via CDP `Runtime.evaluate`. Expression is evaluated as a statement and the return value is serialized. Supports `awaitPromise` for async expressions.
 
 Use only when non-debugger reads are insufficient. Prefer `page.get_storage`, `page.get_text`, `page.get_console`, `page.get_network`, or DOM methods first.
+
 ```bash
 bbx eval 'document.title'
 bbx eval 'window.__NEXT_DATA__.props'
@@ -125,22 +130,29 @@ bbx call page.evaluate '{"expression":"await fetch(\"/api/health\").then(r=>r.js
 ```
 
 ### page.get_console
+
 Read buffered console output. The console interceptor is auto-installed on first call. Captures `log`, `warn`, `error`, `info`, `debug` plus uncaught exceptions and unhandled rejections.
+
 ```bash
 bbx console                    # all levels
 bbx console error              # errors only
 bbx call page.get_console '{"level":"error","limit":20,"clear":true}'
 ```
+
 Responses include `dropped` when older buffered entries were discarded on noisy pages.
 
 ### page.wait_for_load_state
+
 Block until the tab reaches `complete` status. Useful after `input.click` on a navigation link.
+
 ```bash
 bbx call page.wait_for_load_state '{"timeoutMs":10000}'
 ```
 
 ### page.get_storage
+
 Read `localStorage` or `sessionStorage` entries. Values truncated at 500 chars each.
+
 ```bash
 bbx storage                        # all localStorage
 bbx storage session token,user     # specific sessionStorage keys
@@ -148,67 +160,87 @@ bbx call page.get_storage '{"type":"session","keys":["token"]}'
 ```
 
 ### dom.query
+
 Run a bounded breadth-first DOM summary rooted at a selector or existing ref. Returns `{nodes, revision, truncated, registrySize}` and may also include `_registryPruned: true` when the element registry evicted older refs.
+
 ```bash
 bbx dom-query main
 bbx call dom.query '{"selector":"main","maxNodes":10,"attributeAllowlist":["class","data-testid"]}'
 ```
+
 If `_registryPruned` is true, refresh previously cached refs before reusing them.
 
 ### dom.wait_for
+
 Wait for a DOM condition using MutationObserver + 250 ms polling fallback. Returns `{found, elementRef, duration}`.
+
 - `state`: `attached` (default), `detached`, `visible`, `hidden`
 - `text`: optional text content filter
 - `timeoutMs`: 100–30000 (default 5000)
+
 ```bash
 bbx wait '.toast-success' 5000
 bbx call dom.wait_for '{"selector":".modal","state":"visible","timeoutMs":10000}'
 ```
 
 ### dom.find_by_text
+
 Find elements matching visible text content. Like Playwright's `getByText`.
+
 ```bash
 bbx find 'Submit Order'
 bbx call dom.find_by_text '{"text":"Submit","scope":"button","exact":false}'
 ```
 
 ### dom.find_by_role
+
 Find elements by ARIA role (explicit `role` attribute or implicit from HTML tag). Covers 25+ implicit role mappings.
+
 ```bash
 bbx find-role button 'Save'
 bbx call dom.find_by_role '{"role":"navigation"}'
 ```
 
 ### dom.get_html
+
 Get raw HTML of an element. Defaults to `innerHTML`; set `outer: true` for `outerHTML`.
+
 ```bash
 bbx html el_abc123
 bbx call dom.get_html '{"elementRef":"el_abc123","outer":true,"maxLength":2000}'
 ```
 
 ### input.hover
+
 Trigger CSS `:hover` state by dispatching `mouseenter`, `mouseover`, `mousemove`. Optional `duration` to hold hover before auto-releasing.
+
 ```bash
 bbx hover el_abc123
 bbx call input.hover '{"target":{"elementRef":"el_abc123"},"duration":1000}'
 ```
 
 ### input.drag
+
 Full drag-and-drop sequence: `mousedown → dragstart → drag → dragenter → dragover → drop → dragend → mouseup`. Accepts source target, destination target, and optional pixel offsets.
+
 ```bash
 bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"}}'
 bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"sourceOffset":{"x":10,"y":10}}'
 ```
 
 ### input.scroll_into_view
+
 Explicitly scroll an element into the visible viewport before inspecting, hovering, or capturing it.
+
 ```bash
 bbx call input.scroll_into_view '{"target":{"elementRef":"el_abc123"}}'
 bbx call input.scroll_into_view '{"target":{"selector":"[data-testid=\\"checkout-summary\\"]"}}'
 ```
 
 ### tabs.create
+
 Open a new browser tab. Optional `url` (defaults to `about:blank`) and `active` flag (defaults to `true`). Does not require a session.
+
 ```bash
 bbx tab-create https://example.com
 bbx call tabs.create '{"url":"https://example.com","active":false}'
@@ -217,20 +249,26 @@ bbx call tabs.create '{"url":"https://example.com","active":false}'
 The `bbx tab-create` shortcut intentionally covers the common case. Use `bbx call tabs.create ...` when you need advanced fields such as `active:false`.
 
 ### setup.get_status
+
 Inspect the host-side Browser Bridge setup. Returns global MCP config status for supported clients and global CLI skill install status for supported targets.
+
 ```bash
 bbx call setup.get_status
 ```
 
 ### tabs.close
+
 Close a tab by its `tabId`. Does not require a session.
+
 ```bash
 bbx tab-close 12345
 bbx call tabs.close '{"tabId":12345}'
 ```
 
 ### page.get_text
+
 Extract the full visible text content of the page (`document.body.innerText`). Truncated to `textBudget` (default 8000 chars). Lighter than `dom.query` on `body` when you only need text.
+
 ```bash
 bbx page-text
 bbx page-text 8000
@@ -238,18 +276,23 @@ bbx call page.get_text '{"textBudget":2000}'
 ```
 
 ### page.get_network
+
 Read intercepted fetch/XHR requests. The interceptor is auto-installed on first call (via MAIN world script). Returns `{entries, count}` sorted newest-first.
+
 ```bash
 bbx network
 bbx network 50
 bbx call page.get_network '{"limit":20,"clear":true}'
 ```
+
 Each entry: `{method, url, status, duration, initiator}`. Responses include `dropped` when older buffered entries were discarded.
 
 ### dom.get_accessibility_tree
+
 Retrieve the page's accessibility tree via CDP `Accessibility.getFullAXTree`. Each node is simplified to: `role`, `name`, `description`, `value`, `focused`, `required`, `checked`, `disabled`, `interactive`, `childIds`. Use `maxNodes` and `maxDepth` to control size.
 
 This is debugger-backed. Prefer `dom.find_by_role`, `dom.find_by_text`, and targeted `dom.query`/`dom.describe` first.
+
 ```bash
 bbx a11y-tree
 bbx a11y-tree 50 3
@@ -257,9 +300,11 @@ bbx call dom.get_accessibility_tree '{"maxNodes":100,"maxDepth":5}'
 ```
 
 ### viewport.resize
+
 Set the browser viewport to specific dimensions using CDP device emulation. Pass `reset: true` to clear the override.
 
 Debugger-backed. Use only when an exact viewport override is required for responsive verification.
+
 ```bash
 bbx resize 375 812
 bbx call viewport.resize '{"width":1024,"height":768}'
@@ -267,16 +312,20 @@ bbx call viewport.resize '{"reset":true}'
 ```
 
 ### performance.get_metrics
+
 Read Chrome performance counters via CDP `Performance.getMetrics`. Returns a flat `{metrics}` object with keys like `JSHeapUsedSize`, `LayoutCount`, `TaskDuration`, etc.
 
 Debugger-backed. Use after lighter reads fail to explain a performance symptom.
+
 ```bash
 bbx perf
 bbx call performance.get_metrics
 ```
 
 ### screenshot.capture_full_page
+
 Capture a full-document screenshot beyond the current viewport. Use only when element or tight region captures cannot express the issue. Chrome capture limits still apply on very large pages.
+
 ```bash
 bbx call screenshot.capture_full_page '{}'
 ```
@@ -284,21 +333,27 @@ bbx call screenshot.capture_full_page '{}'
 ## Request Envelope
 
 ```json
-{"id":"req_1","tab_id":123,"method":"dom.query","params":{},"meta":{"protocol_version":"1.0","token_budget":1200}}
+{
+  "id": "req_1",
+  "tab_id": 123,
+  "method": "dom.query",
+  "params": {},
+  "meta": { "protocol_version": "1.0", "token_budget": 1200 }
+}
 ```
 
 ## Error Codes
 
-| Code | Action | Recovery |
-|------|--------|----------|
-| `ACCESS_DENIED` | Turn on Browser Bridge for the target window | `retry: false` |
-| `TAB_MISMATCH` | Explicit `tabId` is missing, closed, or outside enabled window | `retry: false`, use `tabs.list` |
-| `ELEMENT_STALE` | Re-query DOM for fresh `elementRef` | `retry: false`, use `dom.query` |
-| `CONTENT_SCRIPT_UNAVAILABLE` | Page is restricted (chrome://, extensions, etc.) | `retry: false` |
-| `NATIVE_HOST_UNAVAILABLE` | Check daemon: `bbx status` | `retry: false` |
-| `EXTENSION_DISCONNECTED` | Extension not connected to daemon | `retry: true` after 3 s, check `health.ping` |
-| `TIMEOUT` | Wait/evaluate exceeded `timeoutMs` | `retry: true` after 1 s |
-| `RATE_LIMITED` | Too many requests | `retry: true` after 2 s |
+| Code                         | Action                                                         | Recovery                                     |
+| ---------------------------- | -------------------------------------------------------------- | -------------------------------------------- |
+| `ACCESS_DENIED`              | Turn on Browser Bridge for the target window                   | `retry: false`                               |
+| `TAB_MISMATCH`               | Explicit `tabId` is missing, closed, or outside enabled window | `retry: false`, use `tabs.list`              |
+| `ELEMENT_STALE`              | Re-query DOM for fresh `elementRef`                            | `retry: false`, use `dom.query`              |
+| `CONTENT_SCRIPT_UNAVAILABLE` | Page is restricted (chrome://, extensions, etc.)               | `retry: false`                               |
+| `NATIVE_HOST_UNAVAILABLE`    | Check daemon: `bbx status`                                     | `retry: false`                               |
+| `EXTENSION_DISCONNECTED`     | Extension not connected to daemon                              | `retry: true` after 3 s, check `health.ping` |
+| `TIMEOUT`                    | Wait/evaluate exceeded `timeoutMs`                             | `retry: true` after 1 s                      |
+| `RATE_LIMITED`               | Too many requests                                              | `retry: true` after 2 s                      |
 
 Timeout on content-script request → use narrower `dom.query` or CDP fallback.
 Timeout on navigation → increase `timeoutMs`, set `waitForLoad:false`, or check `page.get_state`.