@browserbridge/bbx 1.0.1 → 1.2.0

package/docs/api-reference.md

@@ -1,157 +0,0 @@
-# BridgeClient API Reference
-
-`BridgeClient` is the programmatic interface for agents and tools that want to
-communicate with the Browser Bridge daemon directly, without going through the
-CLI or MCP server.
-
-If you are setting up Browser Bridge for normal end-user agent usage, start with
-[quickstart](./quickstart.md) or [manual setup](./manual-setup.md) instead.
-
-## Install
-
-```bash
-npm install @browserbridge/bbx
-```
-
-## Quick start
-
-```js
-import { BridgeClient } from '@browserbridge/bbx/packages/agent-client/src/client.js';
-
-const client = new BridgeClient();
-await client.connect();
-
-const response = await client.request({ method: 'health.ping' });
-console.log(response.result); // { daemon: 'ok', extensionConnected: true, ... }
-
-await client.close();
-```
-
-## Constructor
-
-```js
-new BridgeClient(options?)
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `socketPath` | `string` | `~/.config/browser-bridge/bridge.sock` | Path to the daemon Unix socket |
-| `clientId` | `string` | `agent_<uuid>` | Identifies this client to the daemon |
-| `defaultTimeoutMs` | `number` | `8000` | Per-request timeout in ms |
-| `autoReconnect` | `boolean` | `false` | Reconnect automatically after daemon restarts and emit `reconnected` when the session is restored |
-
-## Methods
-
-### `connect()`
-
-Connect to the daemon and register as an agent. Performs a `health.ping` to
-establish protocol compatibility. Throws if the daemon is not running.
-
-```js
-await client.connect();
-```
-
-### `request(options)`
-
-Send a bridge request and return the response.
-
-```js
-const response = await client.request({
-  method: 'dom.query',
-  params: { selector: 'h1', maxNodes: 5 },
-  tabId: 123, // optional - required for tab-bound methods
-  timeoutMs: 10_000, // optional - overrides defaultTimeoutMs
-});
-
-if (response.ok) {
-  console.log(response.result);
-} else {
-  console.error(response.error.code, response.error.message);
-}
-```
-
-**Returns** a `BridgeResponse`:
-
-```ts
-{ id, ok: true, result: unknown, error: null, meta }
-| { id, ok: false, result: null, error: { code, message, details, recovery? }, meta }
-```
-
-When `ok` is `false`, `error.recovery` (if present) contains machine-readable
-retry guidance:
-
-```js
-if (!response.ok && response.error.recovery?.retry) {
-  await new Promise((r) => setTimeout(r, response.error.recovery.retryAfterMs ?? 1000));
-  // retry once
-}
-```
-
-### `close()`
-
-Gracefully close the connection (sends TCP FIN, waits for acknowledgement).
-
-```js
-await client.close();
-```
-
-### `reconnected` event
-
-When `autoReconnect: true` is enabled, `BridgeClient` emits `reconnected` after
-the socket is re-established and the agent is registered again.
-
-```js
-client.on('reconnected', () => {
-  console.log('Browser Bridge reconnected');
-});
-```
-
-## Available methods
-
-See [`packages/protocol/src/registry.js`](../packages/protocol/src/registry.js) for the full list. Common ones:
-
-| Method                       | Description                                    |
-| ---------------------------- | ---------------------------------------------- |
-| `access.request`             | Request window access (surfaces Enable prompt) |
-| `health.ping`                | Check daemon and extension connectivity        |
-| `tabs.list`                  | List tabs in the enabled window                |
-| `page.get_state`             | URL, title, readyState of the active tab       |
-| `dom.query`                  | Query DOM subtree with CSS selector            |
-| `dom.find_by_text`           | Find elements by visible text                  |
-| `page.evaluate`              | Run JavaScript in the page context             |
-| `page.get_console`           | Read buffered console output                   |
-| `page.get_network`           | Read intercepted fetch/XHR requests            |
-| `input.click`                | Click an element                               |
-| `input.type`                 | Type text into an element                      |
-| `navigation.navigate`        | Navigate to a URL                              |
-| `screenshot.capture_element` | Capture element as PNG (base64)                |
-| `patch.apply_styles`         | Apply reversible CSS overrides                 |
-
-## Error codes
-
-| Code                      | Retryable | Meaning                                           |
-| ------------------------- | --------- | ------------------------------------------------- |
-| `ACCESS_DENIED`           | No        | Browser Bridge is disabled for this window        |
-| `EXTENSION_DISCONNECTED`  | Yes (3 s) | Extension not connected to daemon                 |
-| `TIMEOUT`                 | Yes (1 s) | Extension did not respond in time                 |
-| `RATE_LIMITED`            | Yes (2 s) | Too many concurrent requests                      |
-| `ELEMENT_STALE`           | No        | Element was removed from the DOM                  |
-| `TAB_MISMATCH`            | No        | Tab closed or not found                           |
-| `INVALID_REQUEST`         | No        | Malformed method or params                        |
-| `INTERNAL_ERROR`          | Yes (1 s) | Unexpected extension-side error                   |
-| `DAEMON_OFFLINE`          | No        | Daemon not running — start with `bbx-daemon`      |
-| `CONNECTION_LOST`         | Yes       | Socket dropped mid-request — retry                |
-| `BRIDGE_TIMEOUT`          | Yes (1 s) | Extension took too long — retry with simpler call |
-| `NATIVE_HOST_UNAVAILABLE` | No        | Run `bbx doctor` to diagnose                      |
-
-## Using `withBridgeClient`
-
-For one-off calls, `withBridgeClient` handles connect/close automatically:
-
-```js
-import { withBridgeClient } from '@browserbridge/bbx/packages/agent-client/src/runtime.js';
-
-const result = await withBridgeClient(async (client) => {
-  return client.request({ method: 'page.get_state' });
-});
-```

package/docs/cli-guide.md

@@ -1,128 +0,0 @@
-# CLI Guide
-
-This is the practical day-to-day guide for the `bbx` command. For install and
-agent wiring, see [manual-setup.md](./manual-setup.md).
-
-## Setup and diagnostics
-
-```bash
-bbx install
-bbx status
-bbx doctor
-bbx logs
-bbx tabs
-bbx skill
-```
-
-Use these first when Browser Bridge is not connected, the wrong tab is routed,
-or you want to see the available runtime presets.
-
-## Inspect the page
-
-```bash
-bbx call page.get_state
-bbx dom-query main
-bbx describe .hero
-bbx text .hero-title medium
-bbx html .hero
-bbx attrs .hero id,class,data-state
-bbx a11y-tree 80 4
-```
-
-These commands are usually enough to understand what rendered without dumping a
-large screenshot or the whole DOM.
-
-`dom.query` responses include `registrySize` and may include `_registryPruned:
-true` when older element refs were evicted. If you see that flag, re-query
-instead of reusing old refs.
-
-## Inspect styles and layout
-
-```bash
-bbx styles .hero display,gap,padding,margin
-bbx matched-rules .hero
-bbx box .hero
-bbx call layout.hit_test '{"x":640,"y":280}'
-```
-
-Use `styles`, `matched-rules`, and `box` together when a layout bug is unclear.
-
-## Read runtime state
-
-```bash
-bbx console error
-bbx network 20
-bbx page-text medium
-bbx storage local authToken,featureFlag
-bbx perf
-bbx eval 'window.location.href'
-```
-
-Reach for `eval` only when the structured reads are not enough.
-
-## Navigate and interact
-
-```bash
-bbx navigate https://example.com
-bbx reload
-bbx back
-bbx forward
-bbx click button[type="submit"]
-bbx type input[name="email"] person@example.com
-bbx press-key Enter
-bbx hover .menu-trigger
-bbx call input.scroll_into_view '{"target":{"selector":".menu-trigger"}}'
-bbx scroll 800
-bbx resize 1440 900
-```
-
-Use `input.scroll_into_view` before a hover, click, or capture when the target
-is off-screen or inside a nested scroller.
-
-## Patch the live page
-
-```bash
-bbx patch-style .hero gap=24px padding=32px
-bbx patch-text .hero-title "Preview heading"
-bbx patches
-bbx rollback <patchId>
-```
-
-Patches are session-scoped and reversible. Use them to prove a fix visually
-before you edit source.
-
-## Use the raw RPC path
-
-Shortcuts cover the common cases. For exact methods or advanced parameters:
-
-```bash
-bbx call dom.query '{"selector":".card","maxNodes":5}'
-bbx call --tab 123 page.get_state
-bbx call input.scroll_into_view '{"target":{"selector":"[data-testid=\"checkout-summary\"]"}}'
-bbx call screenshot.capture_full_page '{}'
-bbx page.get_state
-bbx batch '[{"method":"page.get_state"},{"method":"page.get_console","params":{"level":"warn"}}]'
-```
-
-Use `bbx call` when you need the full protocol surface. Use `bbx batch` when
-you want parallel reads with one CLI round trip.
-
-`page.get_console` and `page.get_network` also return `dropped` when hot pages
-overflow their 200-entry buffers.
-
-## Investigate efficiently
-
-When the task is open-ended, treat CLI inspection as a structured-first
-investigation loop:
-
-```bash
-bbx batch '[
-  {"method":"page.get_state"},
-  {"method":"dom.query","params":{"selector":"main","maxNodes":20,"maxDepth":4,"textBudget":600}},
-  {"method":"page.get_text","params":{"textBudget":4000}}
-]'
-```
-
-Add `styles.get_computed`, `layout.get_box_model`, `page.get_console`, or
-`page.get_network` only when they directly help answer the question. Escalate
-to screenshots after that, not before.

package/docs/index.md

@@ -1,25 +0,0 @@
-# Documentation
-
-Browser Bridge has a few different audiences: end users wiring it into an agent,
-people using the `bbx` CLI directly, and maintainers publishing the project.
-This index keeps those paths separate.
-
-## Start here
-
-- [Quickstart](./quickstart.md): fastest path from install to first working tab
-- [MCP vs CLI](./mcp-vs-cli.md): which integration path to choose
-- [Manual setup](./manual-setup.md): exact config locations, project-local installs, and custom-agent setup
-
-## End-user guides
-
-- [Usage scenarios](./usage-scenarios.md): concrete workflows for debugging, verification, and live patching
-- [CLI guide](./cli-guide.md): day-to-day `bbx` commands with practical examples
-- [Troubleshooting](./troubleshooting.md): what to check when install, access, or routing fails
-
-## Reference
-
-- [BridgeClient API](./api-reference.md): programmatic client usage without MCP or CLI shortcuts
-
-## Maintainers
-
-- [Publishing](./publishing.md): npm and Chrome Web Store release flow

package/docs/manual-setup.md

@@ -1,140 +0,0 @@
-# Manual Setup
-
-Use this guide when the side panel setup flow is not enough, when you want
-project-local config instead of global config, or when you are wiring Browser
-Bridge into a custom agent.
-
-## Prerequisites
-
-- Google Chrome on the same machine as the agent
-- Node.js 18 or newer
-- The Browser Bridge extension installed in Chrome
-
-## 1. Install the CLI and native host
-
-```bash
-npm install -g @browserbridge/bbx
-bbx install
-```
-
-`bbx install` writes the native messaging manifest so the extension can talk to
-the local host. If you are connecting a packaged store build before the
-installer embeds a default extension ID, use `bbx install <extension-id>`.
-
-## 2. Verify the local bridge first
-
-Run these before involving an agent:
-
-```bash
-bbx status
-bbx doctor
-```
-
-Then open Chrome, enable Browser Bridge for the current window, and verify tab
-routing:
-
-```bash
-bbx tabs
-bbx call page.get_state
-```
-
-If these commands do not work locally, the agent setup will not work either.
-
-## 3. Managed setup for supported clients
-
-Supported managed targets are kept in this order across the project:
-`codex`, `claude`, `cursor`, `copilot`, `opencode`, `antigravity`,
-`windsurf`, `agents`.
-
-### MCP setup
-
-Use MCP when your agent supports it:
-
-```bash
-bbx install-mcp
-bbx install-mcp codex
-bbx install-mcp copilot --local
-```
-
-Managed MCP config paths:
-
-- `codex`: `~/.codex/config.toml` or `./.codex/config.toml`
-- `claude`: `~/.claude.json` or `./.mcp.json`
-- `cursor`: `~/.cursor/mcp.json` or `./.cursor/mcp.json`
-- `copilot`: `~/.copilot/mcp-config.json` or `./.vscode/mcp.json`
-- `opencode`: `~/.config/opencode/opencode.json` or `./opencode.json`
-- `antigravity`: `~/.gemini/antigravity/mcp_config.json` or `./.agents/mcp_config.json`
-- `windsurf`: `~/.codeium/windsurf/mcp_config.json` or `./.windsurf/mcp_config.json`
-- `agents`: `~/.agents/mcp.json` or `./.agents/mcp.json`
-
-### CLI skill setup
-
-Use the CLI skill when you want the agent to invoke `bbx` directly:
-
-```bash
-bbx install-skill
-bbx install-skill codex
-bbx install-skill agents --project .
-```
-
-Managed skill paths:
-
-- `codex`: `~/.codex/skills/browser-bridge` or `./.codex/skills/browser-bridge`
-- `claude`: `~/.claude/skills/browser-bridge` or `./.claude/skills/browser-bridge`
-- `cursor`: `~/.cursor/skills/browser-bridge` or `./.cursor/skills/browser-bridge`
-- `copilot`: `~/.copilot/skills/browser-bridge` or `./.github/skills/browser-bridge`
-- `opencode`: `~/.opencode/skills/browser-bridge` or `./.opencode/skills/browser-bridge`
-- `antigravity`: `~/.gemini/antigravity/skills/browser-bridge` or `./.agents/skills/browser-bridge`
-- `windsurf`: `~/.codeium/windsurf/skills/browser-bridge` or `./.windsurf/skills/browser-bridge`
-- `agents`: `~/.agents/skills/browser-bridge` or `./.agents/skills/browser-bridge`
-
-## 4. Custom-agent MCP wiring
-
-If your client supports MCP but is not one of the managed targets above, it
-must be able to launch:
-
-```bash
-bbx mcp serve
-```
-
-Most JSON-based MCP clients use a config block like this:
-
-```json
-{
-  "mcpServers": {
-    "browser-bridge": {
-      "type": "stdio",
-      "command": "bbx",
-      "args": ["mcp", "serve"],
-      "env": {}
-    }
-  }
-}
-```
-
-Two common exceptions:
-
-- Codex uses TOML with `[mcp_servers."browser-bridge"]`
-- OpenCode uses an `"mcp"` block with `"type": "local"` and a command array
-
-## 5. Custom-agent CLI skill wiring
-
-For generic agent runners that load skills from a project directory:
-
-```bash
-bbx install-skill agents --project .
-```
-
-That writes the Browser Bridge skill into `./.agents/skills/browser-bridge`.
-Your agent still needs shell access to run `bbx`.
-
-## 6. Recommended validation flow
-
-After wiring the agent, validate the smallest useful path:
-
-1. Ask the agent to check Browser Bridge status.
-2. Ask it to read page state from the current tab.
-3. Ask it to query one visible element.
-4. Ask it to read one computed style or console entry.
-
-If that works, the rest of the bridge surface is usually available too.