@browserbridge/bbx 1.0.0 → 1.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 ![Browser Bridge: Connect AI Agent and Browsers](https://raw.githubusercontent.com/koltyakov/browser-bridge/main/assets/banner.jpg)
 
+> **Chrome Web Store status:** The extension is currently under review. Until the listing is live, use the unpacked install flow in [docs/unpacked-extension.md](https://github.com/koltyakov/browser-bridge/blob/main/docs/unpacked-extension.md).
+
 A local bridge between your coding agent and a real Chrome tab. Browser Bridge gives the agent structured access to DOM, styles, layout, console, network, and reversible patches - starting from the actual tab you already have open, with all its real state intact.
 
 See [Quickstart](https://github.com/koltyakov/browser-bridge/blob/main/docs/quickstart.md) to get started in another repo, or browse the rest of the guides in [docs/index.md](https://github.com/koltyakov/browser-bridge/blob/main/docs/index.md).
@@ -105,7 +107,7 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 
 1. Install [Browser Bridge from the Chrome Web Store](https://chrome.google.com/webstore/detail/jjjkmmcdkpcgamlopogicbnnhdgebhie) <!-- TODO: replace with final store link after publishing -->
 2. `npm install -g @browserbridge/bbx` - installs the CLI and native host
-3. In the extension side panel, install MCP or CLI (skill) for your agent of choice, or run the `bbx install-mcp` / `bbx install-skill` commands if you prefer terminal setup
+3. In the extension side panel, install MCP or CLI (skill) for your agent of choice
 4. Enable Browser Bridge for the Chrome window you want to inspect/control with the AI agent
 5. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the `browser-bridge` / `$bbx` skill in CLI mode
 

package/docs/api-reference.md

@@ -59,8 +59,8 @@ Send a bridge request and return the response.
 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
+  tabId: 123, // optional - required for tab-bound methods
+  timeoutMs: 10_000, // optional - overrides defaultTimeoutMs
 });
 
 if (response.ok) {
@@ -82,7 +82,7 @@ retry guidance:
 
 ```js
 if (!response.ok && response.error.recovery?.retry) {
-  await new Promise(r => setTimeout(r, response.error.recovery.retryAfterMs ?? 1000));
+  await new Promise((r) => setTimeout(r, response.error.recovery.retryAfterMs ?? 1000));
   // retry once
 }
 ```
@@ -110,39 +110,39 @@ client.on('reconnected', () => {
 
 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 |
+| 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 |
+| 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`
 

package/docs/mcp-vs-cli.md

@@ -11,12 +11,12 @@ Short version:
 
 ## Overview
 
-| Aspect | MCP | CLI Skill |
-|--------|-----|-----------|
-| **Integration Type** | Native tool protocol | Shell command execution |
-| **Primary Use Case** | Agents with MCP support | Shell-capable agents |
-| **Discovery** | Auto-discovered tools | Skill documentation |
-| **Invocation** | Tool calls | `bbx` commands |
+| Aspect                    | MCP                           | CLI Skill                        |
+| ------------------------- | ----------------------------- | -------------------------------- |
+| **Integration Type**      | Native tool protocol          | Shell command execution          |
+| **Primary Use Case**      | Agents with MCP support       | Shell-capable agents             |
+| **Discovery**             | Auto-discovered tools         | Skill documentation              |
+| **Invocation**            | Tool calls                    | `bbx` commands                   |
 | **Sandbox Compatibility** | Excellent (no shell required) | Variable (requires shell access) |
 
 ## Capability Matrix
@@ -34,95 +34,95 @@ Short version:
 
 ### Tab Management
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| List tabs | `browser_tabs` (list) | `bbx tabs` | Equivalent |
-| Create tab | `browser_tabs` (create) | `bbx tab-create [url]` | CLI shortcut |
-| Close tab | `browser_tabs` (close) | `bbx tab-close <tabId>` | CLI shortcut |
-| Tab activation | `browser_tabs` (active param) | `bbx call tabs.create` | CLI needs raw call for `active` param |
+| Capability     | MCP Tool                      | CLI Command             | Notes                                 |
+| -------------- | ----------------------------- | ----------------------- | ------------------------------------- |
+| List tabs      | `browser_tabs` (list)         | `bbx tabs`              | Equivalent                            |
+| Create tab     | `browser_tabs` (create)       | `bbx tab-create [url]`  | CLI shortcut                          |
+| Close tab      | `browser_tabs` (close)        | `bbx tab-close <tabId>` | CLI shortcut                          |
+| Tab activation | `browser_tabs` (active param) | `bbx call tabs.create`  | CLI needs raw call for `active` param |
 
 ### DOM Inspection
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Query DOM | `browser_dom` (query) | `bbx dom-query [selector]` | Equivalent |
-| Describe element | `browser_dom` (describe) | `bbx describe <ref>` | Equivalent |
-| Get text content | `browser_dom` (text) | `bbx text <ref>` | Equivalent |
-| Get HTML | `browser_dom` (html) | `bbx html <ref>` | Equivalent |
-| Get attributes | `browser_dom` (attributes) | `bbx attrs <ref> [attr1,...]` | CLI shortcut |
-| Wait for element | `browser_dom` (wait) | `bbx wait <selector>` | Equivalent |
-| Find by text | `browser_dom` (find_text) | `bbx find <text>` | Equivalent |
-| Find by ARIA role | `browser_dom` (find_role) | `bbx find-role <role>` | Equivalent |
-| Accessibility tree | `browser_dom` (accessibility_tree) | `bbx a11y-tree` | Equivalent |
+| Capability         | MCP Tool                           | CLI Command                   | Notes        |
+| ------------------ | ---------------------------------- | ----------------------------- | ------------ |
+| Query DOM          | `browser_dom` (query)              | `bbx dom-query [selector]`    | Equivalent   |
+| Describe element   | `browser_dom` (describe)           | `bbx describe <ref>`          | Equivalent   |
+| Get text content   | `browser_dom` (text)               | `bbx text <ref>`              | Equivalent   |
+| Get HTML           | `browser_dom` (html)               | `bbx html <ref>`              | Equivalent   |
+| Get attributes     | `browser_dom` (attributes)         | `bbx attrs <ref> [attr1,...]` | CLI shortcut |
+| Wait for element   | `browser_dom` (wait)               | `bbx wait <selector>`         | Equivalent   |
+| Find by text       | `browser_dom` (find_text)          | `bbx find <text>`             | Equivalent   |
+| Find by ARIA role  | `browser_dom` (find_role)          | `bbx find-role <role>`        | Equivalent   |
+| Accessibility tree | `browser_dom` (accessibility_tree) | `bbx a11y-tree`               | Equivalent   |
 
 ### Styles & Layout
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Computed styles | `browser_styles_layout` (computed) | `bbx styles <ref> [props]` | Equivalent |
-| Matched CSS rules | `browser_styles_layout` (matched_rules) | `bbx matched-rules <ref>` | CLI shortcut |
-| Box model | `browser_styles_layout` (box_model) | `bbx box <ref>` | Equivalent |
-| Hit test | `browser_styles_layout` (hit_test) | `bbx call layout.hit_test` | CLI uses raw call |
+| Capability        | MCP Tool                                | CLI Command                | Notes             |
+| ----------------- | --------------------------------------- | -------------------------- | ----------------- |
+| Computed styles   | `browser_styles_layout` (computed)      | `bbx styles <ref> [props]` | Equivalent        |
+| Matched CSS rules | `browser_styles_layout` (matched_rules) | `bbx matched-rules <ref>`  | CLI shortcut      |
+| Box model         | `browser_styles_layout` (box_model)     | `bbx box <ref>`            | Equivalent        |
+| Hit test          | `browser_styles_layout` (hit_test)      | `bbx call layout.hit_test` | CLI uses raw call |
 
 ### Page State
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Page state | `browser_page` (state) | `bbx call page.get_state` | CLI uses raw call |
-| JavaScript evaluate | `browser_page` (evaluate) | `bbx eval <expression>` | Equivalent |
-| Console output | `browser_page` (console) | `bbx console [level]` | Equivalent |
-| Wait for load | `browser_page` (wait_for_load) | `bbx call page.wait_for_load_state` | CLI uses raw call |
-| Browser storage | `browser_page` (storage) | `bbx storage [type] [keys]` | Equivalent |
-| Page text | `browser_page` (text) | `bbx page-text [budget]` | Equivalent |
-| Network requests | `browser_page` (network) | `bbx network [limit]` | Equivalent |
-| Performance metrics | `browser_page` (performance) | `bbx perf` | Equivalent |
+| Capability          | MCP Tool                       | CLI Command                         | Notes             |
+| ------------------- | ------------------------------ | ----------------------------------- | ----------------- |
+| Page state          | `browser_page` (state)         | `bbx call page.get_state`           | CLI uses raw call |
+| JavaScript evaluate | `browser_page` (evaluate)      | `bbx eval <expression>`             | Equivalent        |
+| Console output      | `browser_page` (console)       | `bbx console [level]`               | Equivalent        |
+| Wait for load       | `browser_page` (wait_for_load) | `bbx call page.wait_for_load_state` | CLI uses raw call |
+| Browser storage     | `browser_page` (storage)       | `bbx storage [type] [keys]`         | Equivalent        |
+| Page text           | `browser_page` (text)          | `bbx page-text [budget]`            | Equivalent        |
+| Network requests    | `browser_page` (network)       | `bbx network [limit]`               | Equivalent        |
+| Performance metrics | `browser_page` (performance)   | `bbx perf`                          | Equivalent        |
 
 ### Navigation
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Navigate to URL | `browser_navigation` (navigate) | `bbx navigate <url>` | Equivalent |
-| Reload page | `browser_navigation` (reload) | `bbx reload` | CLI shortcut |
-| Go back | `browser_navigation` (go_back) | `bbx back` | CLI shortcut |
-| Go forward | `browser_navigation` (go_forward) | `bbx forward` | CLI shortcut |
-| Scroll viewport | `browser_navigation` (scroll) | `bbx scroll <top> [left]` | CLI shortcut |
-| Resize viewport | `browser_navigation` (resize) | `bbx resize <w> <h>` | Equivalent |
+| Capability      | MCP Tool                          | CLI Command               | Notes        |
+| --------------- | --------------------------------- | ------------------------- | ------------ |
+| Navigate to URL | `browser_navigation` (navigate)   | `bbx navigate <url>`      | Equivalent   |
+| Reload page     | `browser_navigation` (reload)     | `bbx reload`              | CLI shortcut |
+| Go back         | `browser_navigation` (go_back)    | `bbx back`                | CLI shortcut |
+| Go forward      | `browser_navigation` (go_forward) | `bbx forward`             | CLI shortcut |
+| Scroll viewport | `browser_navigation` (scroll)     | `bbx scroll <top> [left]` | CLI shortcut |
+| Resize viewport | `browser_navigation` (resize)     | `bbx resize <w> <h>`      | Equivalent   |
 
 ### Input & Interaction
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Click element | `browser_input` (click) | `bbx click <ref> [button]` | Equivalent |
-| Focus element | `browser_input` (focus) | `bbx focus <ref>` | Equivalent |
-| Type text | `browser_input` (type) | `bbx type <ref> <text>` | Equivalent |
-| Press key | `browser_input` (press_key) | `bbx press-key <key> [ref]` | Equivalent |
-| Set checked | `browser_input` (set_checked) | `bbx call input.set_checked` | CLI uses raw call |
-| Select option | `browser_input` (select_option) | `bbx call input.select_option` | CLI uses raw call |
-| Hover | `browser_input` (hover) | `bbx hover <ref>` | Equivalent |
-| Drag | `browser_input` (drag) | `bbx call input.drag` | CLI uses raw call |
+| Capability              | MCP Tool                           | CLI Command                       | Notes             |
+| ----------------------- | ---------------------------------- | --------------------------------- | ----------------- |
+| Click element           | `browser_input` (click)            | `bbx click <ref> [button]`        | Equivalent        |
+| Focus element           | `browser_input` (focus)            | `bbx focus <ref>`                 | Equivalent        |
+| Type text               | `browser_input` (type)             | `bbx type <ref> <text>`           | Equivalent        |
+| Press key               | `browser_input` (press_key)        | `bbx press-key <key> [ref]`       | Equivalent        |
+| Set checked             | `browser_input` (set_checked)      | `bbx call input.set_checked`      | CLI uses raw call |
+| Select option           | `browser_input` (select_option)    | `bbx call input.select_option`    | CLI uses raw call |
+| Hover                   | `browser_input` (hover)            | `bbx hover <ref>`                 | Equivalent        |
+| Drag                    | `browser_input` (drag)             | `bbx call input.drag`             | CLI uses raw call |
 | Scroll target into view | `browser_input` (scroll_into_view) | `bbx call input.scroll_into_view` | CLI uses raw call |
 
 ### Patching
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Apply style patch | `browser_patch` (apply_styles) | `bbx patch-style <ref> prop=val...` | Equivalent |
-| Apply DOM patch | `browser_patch` (apply_dom) | `bbx patch-text <ref> <text>` | CLI has text-specific shortcut |
-| List patches | `browser_patch` (list) | `bbx patches` | Equivalent |
-| Rollback patch | `browser_patch` (rollback) | `bbx rollback <patchId>` | Equivalent |
-| Commit baseline | `browser_patch` (commit_baseline) | `bbx call patch.commit_baseline` | CLI uses raw call |
+| Capability        | MCP Tool                          | CLI Command                         | Notes                          |
+| ----------------- | --------------------------------- | ----------------------------------- | ------------------------------ |
+| Apply style patch | `browser_patch` (apply_styles)    | `bbx patch-style <ref> prop=val...` | Equivalent                     |
+| Apply DOM patch   | `browser_patch` (apply_dom)       | `bbx patch-text <ref> <text>`       | CLI has text-specific shortcut |
+| List patches      | `browser_patch` (list)            | `bbx patches`                       | Equivalent                     |
+| Rollback patch    | `browser_patch` (rollback)        | `bbx rollback <patchId>`            | Equivalent                     |
+| Commit baseline   | `browser_patch` (commit_baseline) | `bbx call patch.commit_baseline`    | CLI uses raw call              |
 
 ### Capture & Screenshots
 
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Element screenshot | `browser_capture` (element) | `bbx screenshot <ref> [outPath]` | Equivalent |
-| Region screenshot | `browser_capture` (region) | `bbx call screenshot.capture_region` | CLI uses raw call |
-| Full-page screenshot | `browser_capture` (full_page) | `bbx call screenshot.capture_full_page` | CLI uses raw call |
-| CDP document | `browser_capture` (cdp_document) | `bbx call cdp.get_document` | CLI uses raw call |
-| CDP DOM snapshot | `browser_capture` (cdp_dom_snapshot) | `bbx call cdp.get_dom_snapshot` | CLI uses raw call |
-| CDP box model | `browser_capture` (cdp_box_model) | `bbx call cdp.get_box_model` | CLI uses raw call |
-| CDP computed styles | `browser_capture` (cdp_computed_styles) | `bbx call cdp.get_computed_styles_for_node` | CLI uses raw call |
+| Capability           | MCP Tool                                | CLI Command                                 | Notes             |
+| -------------------- | --------------------------------------- | ------------------------------------------- | ----------------- |
+| Element screenshot   | `browser_capture` (element)             | `bbx screenshot <ref> [outPath]`            | Equivalent        |
+| Region screenshot    | `browser_capture` (region)              | `bbx call screenshot.capture_region`        | CLI uses raw call |
+| Full-page screenshot | `browser_capture` (full_page)           | `bbx call screenshot.capture_full_page`     | CLI uses raw call |
+| CDP document         | `browser_capture` (cdp_document)        | `bbx call cdp.get_document`                 | CLI uses raw call |
+| CDP DOM snapshot     | `browser_capture` (cdp_dom_snapshot)    | `bbx call cdp.get_dom_snapshot`             | CLI uses raw call |
+| CDP box model        | `browser_capture` (cdp_box_model)       | `bbx call cdp.get_box_model`                | CLI uses raw call |
+| CDP computed styles  | `browser_capture` (cdp_computed_styles) | `bbx call cdp.get_computed_styles_for_node` | CLI uses raw call |
 
 ### Advanced & Raw Protocol
 
@@ -140,31 +140,31 @@ Short version:
 
 ### MCP Advantages
 
-| Feature | Description |
-|---------|-------------|
-| **Auto-discovery** | Tools are automatically registered and discovered by MCP clients |
-| **Schema validation** | Input parameters validated via Zod schemas before execution |
-| **Structured responses** | Consistent tool result format with content blocks |
-| **No shell dependency** | Works in sandboxed environments without shell access |
-| **Tool grouping** | Related actions grouped logically (e.g., `browser_dom` with multiple actions) |
-| **Type safety** | Strong typing via input schemas |
-| **Client-native** | Integrated into agent's tool system natively |
-| **Delegation hints** | `browser_investigate` can tell orchestrators to use a smaller, cheaper subagent first |
+| Feature                  | Description                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| **Auto-discovery**       | Tools are automatically registered and discovered by MCP clients                      |
+| **Schema validation**    | Input parameters validated via Zod schemas before execution                           |
+| **Structured responses** | Consistent tool result format with content blocks                                     |
+| **No shell dependency**  | Works in sandboxed environments without shell access                                  |
+| **Tool grouping**        | Related actions grouped logically (e.g., `browser_dom` with multiple actions)         |
+| **Type safety**          | Strong typing via input schemas                                                       |
+| **Client-native**        | Integrated into agent's tool system natively                                          |
+| **Delegation hints**     | `browser_investigate` can tell orchestrators to use a smaller, cheaper subagent first |
 
 ### CLI Advantages
 
-| Feature | Description |
-|---------|-------------|
-| **Batch execution** | `bbx batch` executes multiple calls concurrently via Promise.all and reports per-call duration/token estimates |
-| **Request logging** | `bbx logs` shows recent bridge request history |
-| **Setup commands** | Built-in install, uninstall, doctor commands |
-| **Shell scripting** | Can be used in scripts, pipes, and CI workflows |
-| **Direct output** | JSON output can be piped to other tools |
-| **Shortcut commands** | Convenient aliases for common operations |
-| **Raw protocol access** | Direct `bbx call` for any method with full parameter control |
-| **Interactive flows** | `bbx doctor` for guided troubleshooting |
-| **Stdin support** | `bbx eval -` reads expression from stdin |
-| **Manual investigation loops** | `bbx batch` makes the same structured-first investigation pattern easy to script |
+| Feature                        | Description                                                                                                    |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| **Batch execution**            | `bbx batch` executes multiple calls concurrently via Promise.all and reports per-call duration/token estimates |
+| **Request logging**            | `bbx logs` shows recent bridge request history                                                                 |
+| **Setup commands**             | Built-in install, uninstall, doctor commands                                                                   |
+| **Shell scripting**            | Can be used in scripts, pipes, and CI workflows                                                                |
+| **Direct output**              | JSON output can be piped to other tools                                                                        |
+| **Shortcut commands**          | Convenient aliases for common operations                                                                       |
+| **Raw protocol access**        | Direct `bbx call` for any method with full parameter control                                                   |
+| **Interactive flows**          | `bbx doctor` for guided troubleshooting                                                                        |
+| **Stdin support**              | `bbx eval -` reads expression from stdin                                                                       |
+| **Manual investigation loops** | `bbx batch` makes the same structured-first investigation pattern easy to script                               |
 
 ## Ergonomics Comparison
 
@@ -233,15 +233,15 @@ Escalate to `bbx screenshot`, `screenshot.capture_region`, or `screenshot.captur
 
 ## Client Compatibility Matrix
 
-| Client | MCP Support | CLI Skill Support | Recommended Path |
-|--------|-------------|-------------------|------------------|
-| OpenAI Codex | Yes (TOML config) | Yes | MCP preferred |
-| Claude Code | Yes | Yes | MCP preferred |
-| Cursor | Yes | Yes | MCP preferred |
-| GitHub Copilot | Yes (VS Code) | Limited (sandbox) | **MCP required** |
-| OpenCode | Yes (local type) | Yes | MCP preferred |
-| Antigravity | Yes | Yes | MCP preferred |
-| Windsurf | Yes | Yes | MCP preferred |
+| Client         | MCP Support              | CLI Skill Support | Recommended Path             |
+| -------------- | ------------------------ | ----------------- | ---------------------------- |
+| OpenAI Codex   | Yes (TOML config)        | Yes               | MCP preferred                |
+| Claude Code    | Yes                      | Yes               | MCP preferred                |
+| Cursor         | Yes                      | Yes               | MCP preferred                |
+| GitHub Copilot | Yes (VS Code)            | Limited (sandbox) | **MCP required**             |
+| OpenCode       | Yes (local type)         | Yes               | MCP preferred                |
+| Antigravity    | Yes                      | Yes               | MCP preferred                |
+| Windsurf       | Yes                      | Yes               | MCP preferred                |
 | Generic agents | Yes (`.agents/mcp.json`) | `.agents/skills/` | MCP preferred when available |
 
 ## Summary

package/docs/publishing.md

@@ -13,7 +13,7 @@ The published npm package now embeds the Browser Bridge store extension ID, so e
 
 ## Release Checklist
 
-1. Bump the version in [package.json](../package.json) and [manifest.json](../manifest.json) together.
+1. Bump [package.json](../package.json) when releasing the CLI/npm package and [manifest.json](../manifest.json) when releasing the extension ZIP. They can advance independently.
 2. Run `npm install` if dependencies changed.
 3. Run `npm run release:check`.
 4. In npm package settings, add a GitHub Actions trusted publisher for this repository and workflow file `release.yml`.
@@ -71,14 +71,12 @@ Use one narrow sentence. Suggested draft:
 
 Use reviewer-facing explanations tied to the product purpose:
 
-- `activeTab`: used to bootstrap inspection against the tab the user explicitly enables
 - `debugger`: used for Chrome DevTools Protocol reads and page-context evaluation, such as DOM snapshots, computed styles, screenshots, accessibility data, and page inspection helpers
 - `nativeMessaging`: required to communicate with the local Browser Bridge daemon
 - `scripting`: used to inject and coordinate the scoped page instrumentation flow
 - `sidePanel`: provides the side panel control surface
 - `storage`: persists window approvals, session state, and recent UI state for the current browser session
 - `tabs`: enumerates tabs and validates that a request stays inside the enabled window
-- `offscreen`: used for screenshot cropping in the offscreen document
 - `host_permissions` on `<all_urls>`: needed because the tool is designed to inspect whichever site the user explicitly approves, not a fixed site list
 
 Reviewers will likely scrutinize `debugger`, `nativeMessaging`, and `<all_urls>`. Keep the listing language narrow and explicit about user approval and local-only operation.

package/docs/quickstart.md

@@ -75,15 +75,15 @@ Your agent can now inspect and patch the active tab in that enabled window, or o
 
 You can refer to it as `BB MCP` or `Browser Bridge MCP`; both should work.
 
-> *"Why is the sidebar layout broken on this page?"*
-> *"Use BB MCP to inspect why the sidebar layout is broken."*
-> *"Check the CSS on the hero section and fix the spacing."*
-> *"Does my latest change actually render correctly in the browser?"*
+> _"Why is the sidebar layout broken on this page?"_
+> _"Use BB MCP to inspect why the sidebar layout is broken."_
+> _"Check the CSS on the hero section and fix the spacing."_
+> _"Does my latest change actually render correctly in the browser?"_
 
 **Skill + CLI mode** - reference the skill explicitly so the agent knows to use `bbx`:
 
-> *"Use the browser-bridge skill to check why the sidebar layout is broken."*
-> *"Using browser-bridge skill, verify the hero section spacing and fix it."*
+> _"Use the browser-bridge skill to check why the sidebar layout is broken."_
+> _"Using browser-bridge skill, verify the hero section spacing and fix it."_
 
 For GitHub Copilot, invoke the skill by name, for example `/browser-bridge`.
 `bbx` is the Browser Bridge CLI command, not a guaranteed Copilot skill alias.

package/docs/unpacked-extension.md

@@ -0,0 +1,72 @@
+# Unpacked Extension Install
+
+Use this path while the Chrome Web Store listing is still pending, or anytime
+you want to run Browser Bridge without installing it from a marketplace.
+
+## 1. Install the CLI
+
+```bash
+npm install -g @browserbridge/bbx
+```
+
+## 2. Build the unpacked extension bundle
+
+From this repository, stage the extension files into `dist/`:
+
+```bash
+npm run package:extension
+```
+
+That writes the unpacked extension to:
+
+```text
+dist/browser-bridge-extension/
+```
+
+## 3. Load it into Chrome
+
+1. Open `chrome://extensions`.
+2. Enable **Developer mode**.
+3. Click **Load unpacked**.
+4. Select `dist/browser-bridge-extension`.
+
+## 4. Copy the extension ID
+
+After Chrome loads the unpacked extension, copy its extension ID from the
+Extensions page.
+
+## 5. Install the native host for that extension ID
+
+Unpacked builds do not use the published store ID, so install the native host
+manifest explicitly for the loaded extension:
+
+```bash
+bbx install <extension-id>
+```
+
+You can also provide the same value through the environment if needed:
+
+```bash
+BROWSER_BRIDGE_EXTENSION_ID=<extension-id> bbx install
+```
+
+## 6. Verify the local connection
+
+```bash
+bbx status
+bbx doctor
+```
+
+Then open the Browser Bridge side panel in Chrome, enable access for the target
+window, and verify the bridge is responding:
+
+```bash
+bbx call page.get_state
+```
+
+## Notes
+
+- Re-run `bbx install <extension-id>` if you switch to a different unpacked
+  extension build with a different ID.
+- For packaged store builds, plain `bbx install` is the intended path once the
+  Chrome Web Store release is live.

package/manifest.json

@@ -11,19 +11,15 @@
     "128": "packages/extension/assets/icon-128.png"
   },
   "permissions": [
-    "activeTab",
     "alarms",
     "debugger",
     "nativeMessaging",
     "scripting",
     "sidePanel",
     "storage",
-    "tabs",
-    "offscreen"
-  ],
-  "host_permissions": [
-    "<all_urls>"
+    "tabs"
   ],
+  "host_permissions": ["<all_urls>"],
   "background": {
     "service_worker": "packages/extension/src/background.js",
     "type": "module"
@@ -38,15 +34,5 @@
   },
   "side_panel": {
     "default_path": "packages/extension/ui/sidepanel.html"
-  },
-  "web_accessible_resources": [
-    {
-      "resources": [
-        "packages/extension/ui/ui.css"
-      ],
-      "matches": [
-        "<all_urls>"
-      ]
-    }
-  ]
+  }
 }