@browserbridge/bbx 1.3.0 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/package.json +2 -2
- package/packages/agent-client/src/cli.js +45 -16
- package/packages/agent-client/src/client.js +74 -20
- package/packages/agent-client/src/command-registry.js +2 -3
- package/packages/agent-client/src/mcp-config.js +30 -27
- package/packages/agent-client/src/runtime.js +2 -10
- package/packages/agent-client/src/types.ts +10 -1
- package/packages/mcp-server/src/guidance.js +241 -0
- package/packages/mcp-server/src/handlers-capture.js +74 -11
- package/packages/mcp-server/src/handlers-dom.js +48 -0
- package/packages/mcp-server/src/handlers-navigation.js +22 -2
- package/packages/mcp-server/src/handlers-page.js +10 -9
- package/packages/mcp-server/src/handlers-utils.js +47 -1
- package/packages/mcp-server/src/server.js +111 -29
- package/packages/native-host/src/auth-token.js +92 -0
- package/packages/native-host/src/daemon-process.js +26 -4
- package/packages/native-host/src/daemon.js +174 -28
- package/packages/native-host/src/framing.js +7 -2
- package/packages/native-host/src/native-host.js +18 -2
- package/packages/protocol/src/defaults.js +3 -0
- package/packages/protocol/src/json-lines.js +29 -1
- package/packages/protocol/src/protocol.js +6 -1
- package/packages/protocol/src/types.ts +2 -0
- package/skills/browser-bridge/SKILL.md +21 -5
- package/skills/browser-bridge/agents/openai.yaml +1 -1
- package/skills/browser-bridge/references/interaction.md +6 -6
- package/skills/browser-bridge/references/protocol.md +57 -54
- package/skills/browser-bridge/references/ui-workflows.md +1 -1
|
@@ -32,7 +32,7 @@ bbx call navigation.go_forward
|
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
34
|
bbx call viewport.scroll '{"top":640,"behavior":"smooth"}'
|
|
35
|
-
bbx call viewport.scroll '{"elementRef":"el_123","top":200}'
|
|
35
|
+
bbx call viewport.scroll '{"target":{"elementRef":"el_123"},"top":200}'
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
Scrolls the window or a specific scrollable element.
|
|
@@ -125,10 +125,10 @@ bbx scroll 640 # scroll down 640px
|
|
|
125
125
|
bbx scroll 0 200 # scroll right 200px
|
|
126
126
|
bbx scroll 0 # scroll to top (top=0)
|
|
127
127
|
bbx call viewport.scroll '{"top":640,"behavior":"smooth"}'
|
|
128
|
-
bbx call viewport.scroll '{"elementRef":"el_123","top":200}'
|
|
128
|
+
bbx call viewport.scroll '{"target":{"elementRef":"el_123"},"top":200}'
|
|
129
129
|
```
|
|
130
130
|
|
|
131
|
-
Scrolls the window by default. Pass
|
|
131
|
+
Scrolls the window by default. Pass `target: { elementRef }` to scroll an inner scrollable container.
|
|
132
132
|
|
|
133
133
|
### Scroll target into view
|
|
134
134
|
|
|
@@ -205,7 +205,7 @@ bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRe
|
|
|
205
205
|
With pixel offsets for precise positioning:
|
|
206
206
|
|
|
207
207
|
```bash
|
|
208
|
-
bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"
|
|
208
|
+
bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"offsetX":5,"offsetY":5}'
|
|
209
209
|
```
|
|
210
210
|
|
|
211
211
|
Event sequence: `mousedown → dragstart → drag → dragenter → dragover → drop → dragend → mouseup`.
|
|
@@ -225,10 +225,10 @@ Find elements matching visible text. Faster than `dom.query` when you know the l
|
|
|
225
225
|
|
|
226
226
|
```bash
|
|
227
227
|
bbx find 'Submit Order'
|
|
228
|
-
bbx call dom.find_by_text '{"text":"Add to Cart","
|
|
228
|
+
bbx call dom.find_by_text '{"text":"Add to Cart","selector":"button","exact":false}'
|
|
229
229
|
```
|
|
230
230
|
|
|
231
|
-
- `
|
|
231
|
+
- `selector`: optional CSS selector to narrow search (e.g. `"button"`, `".sidebar"`)
|
|
232
232
|
- `exact`: `true` for exact match, `false` (default) for substring/case-insensitive
|
|
233
233
|
|
|
234
234
|
### By ARIA role
|
|
@@ -27,7 +27,7 @@ The table below includes the legacy capability bucket for each method so agents
|
|
|
27
27
|
- `-` means the method is global/system-scoped and was never gated by a former capability bucket.
|
|
28
28
|
- Capability names are descriptive coverage labels only. Browser Bridge access is window-scoped now; there are no capability-scoped sessions.
|
|
29
29
|
|
|
30
|
-
## All Methods (
|
|
30
|
+
## All Methods (59)
|
|
31
31
|
|
|
32
32
|
| # | Method | Tab? | CDP? | Group | Capability | Notes |
|
|
33
33
|
| --- | ---------------------------------- | ---- | ---- | ----------- | -------------------- | ----------------------------------------------------------------------- |
|
|
@@ -40,66 +40,67 @@ The table below includes the legacy capability bucket for each method so agents
|
|
|
40
40
|
| 7 | `setup.install` | No | - | system | `-` | Install or uninstall MCP/skill integration targets |
|
|
41
41
|
| 8 | `health.ping` | No | - | system | `-` | Connectivity check + access routing state |
|
|
42
42
|
| 9 | `log.tail` | No | - | system | `-` | Recent bridge logs |
|
|
43
|
-
| 10 | `
|
|
44
|
-
| 11 | `page.
|
|
45
|
-
| 12 | `page.
|
|
46
|
-
| 13 | `page.
|
|
47
|
-
| 14 | `page.
|
|
48
|
-
| 15 | `page.
|
|
49
|
-
| 16 | `page.
|
|
50
|
-
| 17 | `
|
|
51
|
-
| 18 | `navigation.
|
|
52
|
-
| 19 | `navigation.
|
|
53
|
-
| 20 | `navigation.
|
|
54
|
-
| 21 | `
|
|
55
|
-
| 22 | `dom.
|
|
56
|
-
| 23 | `dom.
|
|
57
|
-
| 24 | `dom.
|
|
58
|
-
| 25 | `dom.
|
|
59
|
-
| 26 | `dom.
|
|
60
|
-
| 27 | `dom.
|
|
61
|
-
| 28 | `dom.
|
|
62
|
-
| 29 | `dom.
|
|
63
|
-
| 30 | `
|
|
64
|
-
| 31 | `layout.
|
|
65
|
-
| 32 | `
|
|
66
|
-
| 33 | `styles.
|
|
67
|
-
| 34 | `
|
|
68
|
-
| 35 | `viewport.
|
|
69
|
-
| 36 | `
|
|
70
|
-
| 37 | `input.
|
|
71
|
-
| 38 | `input.
|
|
72
|
-
| 39 | `input.
|
|
73
|
-
| 40 | `input.
|
|
74
|
-
| 41 | `input.
|
|
75
|
-
| 42 | `input.
|
|
76
|
-
| 43 | `input.
|
|
77
|
-
| 44 | `input.
|
|
78
|
-
| 45 | `
|
|
79
|
-
| 46 | `screenshot.
|
|
80
|
-
| 47 | `screenshot.
|
|
81
|
-
| 48 | `
|
|
82
|
-
| 49 | `patch.
|
|
83
|
-
| 50 | `patch.
|
|
84
|
-
| 51 | `patch.
|
|
85
|
-
| 52 | `patch.
|
|
86
|
-
| 53 | `
|
|
87
|
-
| 54 | `
|
|
88
|
-
| 55 | `cdp.
|
|
89
|
-
| 56 | `cdp.
|
|
90
|
-
| 57 | `cdp.
|
|
91
|
-
| 58 | `cdp.
|
|
43
|
+
| 10 | `daemon.metrics` | No | - | system | `-` | Daemon health and performance metrics |
|
|
44
|
+
| 11 | `page.get_state` | Yes | - | page | `page.read` | URL, readiness, focus, scroll, viewport |
|
|
45
|
+
| 12 | `page.evaluate` | Yes | CDP | page | `page.evaluate` | JS expression in page context; last resort |
|
|
46
|
+
| 13 | `page.get_console` | Yes | - | page | `page.read` | Buffered console messages; filter by `level`, `limit` |
|
|
47
|
+
| 14 | `page.wait_for_load_state` | Yes | - | wait | `page.read` | Block until tab `complete`; `timeoutMs` capped 30 s |
|
|
48
|
+
| 15 | `page.get_storage` | Yes | - | page | `page.read` | `localStorage`/`sessionStorage`; optional `keys` |
|
|
49
|
+
| 16 | `page.get_text` | Yes | - | page | `page.read` | Full page text; `textBudget` limits size |
|
|
50
|
+
| 17 | `page.get_network` | Yes | - | page | `network.read` | Intercepted fetch/XHR; `limit` entries |
|
|
51
|
+
| 18 | `navigation.navigate` | Yes | - | navigate | `navigation.control` | Go to URL; `waitForLoad` default true |
|
|
52
|
+
| 19 | `navigation.reload` | Yes | - | navigate | `navigation.control` | Reload; `waitForLoad` default true |
|
|
53
|
+
| 20 | `navigation.go_back` | Yes | - | navigate | `navigation.control` | History back |
|
|
54
|
+
| 21 | `navigation.go_forward` | Yes | - | navigate | `navigation.control` | History forward |
|
|
55
|
+
| 22 | `dom.query` | Yes | - | inspect | `dom.read` | Query subtree with budget constraints |
|
|
56
|
+
| 23 | `dom.describe` | Yes | - | inspect | `dom.read` | Single element details via `elementRef` |
|
|
57
|
+
| 24 | `dom.get_text` | Yes | - | inspect | `dom.read` | Text content with `textBudget` |
|
|
58
|
+
| 25 | `dom.get_attributes` | Yes | - | inspect | `dom.read` | Targeted attribute read |
|
|
59
|
+
| 26 | `dom.wait_for` | Yes | - | wait | `dom.read` | Wait for DOM condition; MutationObserver + polling |
|
|
60
|
+
| 27 | `dom.find_by_text` | Yes | - | inspect | `dom.read` | Find by visible text; returns `{nodes, count}` |
|
|
61
|
+
| 28 | `dom.find_by_role` | Yes | - | inspect | `dom.read` | Find by ARIA role; optional `name` filter |
|
|
62
|
+
| 29 | `dom.get_html` | Yes | - | inspect | `dom.read` | `innerHTML`/`outerHTML`; `maxLength` truncation |
|
|
63
|
+
| 30 | `dom.get_accessibility_tree` | Yes | CDP | inspect | `dom.read` | Full a11y tree; `maxNodes`/`maxDepth` limits |
|
|
64
|
+
| 31 | `layout.get_box_model` | Yes | - | inspect | `layout.read` | Element geometry (no budget needed) |
|
|
65
|
+
| 32 | `layout.hit_test` | Yes | - | inspect | `layout.read` | Element at viewport point |
|
|
66
|
+
| 33 | `styles.get_computed` | Yes | - | inspect | `styles.read` | Computed CSS; always set `properties` |
|
|
67
|
+
| 34 | `styles.get_matched_rules` | Yes | - | inspect | `styles.read` | Matching CSS rules |
|
|
68
|
+
| 35 | `viewport.scroll` | Yes | - | navigate | `viewport.control` | Window or element scroll |
|
|
69
|
+
| 36 | `viewport.resize` | Yes | CDP | navigate | `viewport.control` | Set viewport via device emulation; `reset: true` |
|
|
70
|
+
| 37 | `input.click` | Yes | - | interact | `automation.input` | DOM-level click |
|
|
71
|
+
| 38 | `input.focus` | Yes | - | interact | `automation.input` | Focus element |
|
|
72
|
+
| 39 | `input.type` | Yes | - | interact | `automation.input` | Type into input/textarea/contenteditable |
|
|
73
|
+
| 40 | `input.press_key` | Yes | - | interact | `automation.input` | Single key event |
|
|
74
|
+
| 41 | `input.set_checked` | Yes | - | interact | `automation.input` | Checkbox/radio toggle |
|
|
75
|
+
| 42 | `input.select_option` | Yes | - | interact | `automation.input` | Native select by value/label/index |
|
|
76
|
+
| 43 | `input.hover` | Yes | - | interact | `automation.input` | mouseenter/mouseover/mousemove; optional `duration` |
|
|
77
|
+
| 44 | `input.drag` | Yes | - | interact | `automation.input` | Full drag-and-drop event sequence |
|
|
78
|
+
| 45 | `input.scroll_into_view` | Yes | - | interact | `automation.input` | Explicitly scroll target into view before inspect/capture |
|
|
79
|
+
| 46 | `screenshot.capture_element` | Yes | CDP | capture | `screenshot.partial` | Cropped element screenshot |
|
|
80
|
+
| 47 | `screenshot.capture_region` | Yes | CDP | capture | `screenshot.partial` | Cropped viewport region |
|
|
81
|
+
| 48 | `screenshot.capture_full_page` | Yes | CDP | capture | `screenshot.partial` | Full document screenshot; use only when page-level context is necessary |
|
|
82
|
+
| 49 | `patch.apply_styles` | Yes | - | patch | `patch.styles` | Reversible CSS patch; `verify` returns computed result |
|
|
83
|
+
| 50 | `patch.apply_dom` | Yes | - | patch | `patch.dom` | Reversible DOM mutation; `verify` returns result |
|
|
84
|
+
| 51 | `patch.list` | Yes | - | patch | `patch.dom` | Active patches |
|
|
85
|
+
| 52 | `patch.rollback` | Yes | - | patch | `patch.dom` | Revert one patch |
|
|
86
|
+
| 53 | `patch.commit_session_baseline` | Yes | - | patch | `patch.dom` | Accept current state as baseline |
|
|
87
|
+
| 54 | `performance.get_metrics` | Yes | CDP | performance | `performance.read` | Chrome performance counters |
|
|
88
|
+
| 55 | `cdp.get_document` | Yes | CDP | cdp | `cdp.dom_snapshot` | DevTools document tree |
|
|
89
|
+
| 56 | `cdp.get_dom_snapshot` | Yes | CDP | cdp | `cdp.dom_snapshot` | DevTools DOM snapshot |
|
|
90
|
+
| 57 | `cdp.get_box_model` | Yes | CDP | cdp | `cdp.box_model` | DevTools-backed element geometry |
|
|
91
|
+
| 58 | `cdp.get_computed_styles_for_node` | Yes | CDP | cdp | `cdp.styles` | DevTools-backed computed styles |
|
|
92
|
+
| 59 | `cdp.dispatch_key_event` | Yes | CDP | cdp | `cdp.input` | DevTools keyDown/keyUp without foreground focus |
|
|
92
93
|
|
|
93
94
|
## CLI
|
|
94
95
|
|
|
95
96
|
```bash
|
|
96
|
-
bbx status | logs | tabs | skill
|
|
97
|
+
bbx status | doctor | restart | logs | tabs | skill # no routed tab needed
|
|
97
98
|
bbx call <method> '{"key":"val"}' # generic RPC (routes to active tab in enabled window)
|
|
98
99
|
bbx call --tab 123 <method> '{...}' # explicit tab target inside enabled window
|
|
99
100
|
bbx batch '[{"method":"...","params":{}}]' # parallel calls
|
|
100
101
|
```
|
|
101
102
|
|
|
102
|
-
**Convenience shortcuts:** `access-request`, `dom-query`, `describe`, `text`, `styles`, `box`, `click`, `focus`, `type`, `press-key`, `cdp-press-key`, `patch-style`, `patch-text`, `patches`, `rollback`, `screenshot`, `eval`, `console`, `wait`, `find`, `find-role`, `html`, `hover`, `navigate`, `storage`, `tab-create`, `tab-close`, `page-text`, `network`, `a11y-tree`, `perf`, `resize`, `reload`, `back`, `forward`, `attrs`, `matched-rules`
|
|
103
|
+
**Convenience shortcuts:** `access-request`, `dom-query`, `describe`, `text`, `styles`, `box`, `click`, `focus`, `type`, `press-key`, `cdp-press-key`, `patch-style`, `patch-text`, `patches`, `rollback`, `screenshot`, `eval`, `console`, `wait`, `find`, `find-role`, `html`, `hover`, `navigate`, `storage`, `tab-create`, `tab-close`, `page-text`, `network`, `a11y-tree`, `perf`, `scroll`, `resize`, `reload`, `back`, `forward`, `attrs`, `matched-rules`
|
|
103
104
|
|
|
104
105
|
Newer bridge methods such as `input.scroll_into_view` and `screenshot.capture_full_page` currently use the raw path: `bbx call <method> '{...}'`.
|
|
105
106
|
|
|
@@ -190,7 +191,7 @@ Find elements matching visible text content. Like Playwright's `getByText`.
|
|
|
190
191
|
|
|
191
192
|
```bash
|
|
192
193
|
bbx find 'Submit Order'
|
|
193
|
-
bbx call dom.find_by_text '{"text":"Submit","
|
|
194
|
+
bbx call dom.find_by_text '{"text":"Submit","selector":"button","exact":false}'
|
|
194
195
|
```
|
|
195
196
|
|
|
196
197
|
### dom.find_by_role
|
|
@@ -226,7 +227,7 @@ Full drag-and-drop sequence: `mousedown → dragstart → drag → dragenter →
|
|
|
226
227
|
|
|
227
228
|
```bash
|
|
228
229
|
bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"}}'
|
|
229
|
-
bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"
|
|
230
|
+
bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"offsetX":10,"offsetY":10}'
|
|
230
231
|
```
|
|
231
232
|
|
|
232
233
|
### input.scroll_into_view
|
|
@@ -327,6 +328,8 @@ bbx call performance.get_metrics
|
|
|
327
328
|
|
|
328
329
|
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.
|
|
329
330
|
|
|
331
|
+
This raw call returns base64 JSON. Prefer `bbx screenshot <ref> [outPath]` when one element is enough.
|
|
332
|
+
|
|
330
333
|
```bash
|
|
331
334
|
bbx call screenshot.capture_full_page '{}'
|
|
332
335
|
```
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
Use when a dev server is already running and you want to prove a fix rendered.
|
|
6
6
|
|
|
7
7
|
1. `page.get_state`
|
|
8
|
-
2. `dom.query` on the target area with `
|
|
8
|
+
2. `dom.query` on the target area with explicit tight limits such as `maxNodes: 5`, `maxDepth: 2`, and `textBudget: 300`
|
|
9
9
|
3. `styles.get_computed` or `layout.get_box_model`
|
|
10
10
|
4. `patch.apply_styles` to prove the visual fix
|
|
11
11
|
5. Edit source files
|