@browserbridge/bbx 1.0.1 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
-# Browser Bridge
+# Browser Bridge (BBX)
 
-![Browser Bridge: Connect AI Agent and Browsers](https://raw.githubusercontent.com/koltyakov/browser-bridge/main/assets/banner.jpg)
+![Browser Bridge (BBX): 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).
+> **Chrome Web Store:** Install `Browser Bridge (BBX)` from the [Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie). For local or custom builds, 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.
 
@@ -105,7 +105,7 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 
 ## Setup
 
-1. Install [Browser Bridge from the Chrome Web Store](https://chrome.google.com/webstore/detail/jjjkmmcdkpcgamlopogicbnnhdgebhie) <!-- TODO: replace with final store link after publishing -->
+1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie)
 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
 4. Enable Browser Bridge for the Chrome window you want to inspect/control with the AI agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -32,21 +32,17 @@
     "bbx-mcp": "packages/mcp-server/src/bin.js"
   },
   "files": [
-    "assets",
-    "CHANGELOG.md",
     "LICENSE",
     "README.md",
-    "docs",
-    "manifest.json",
     "packages/agent-client/src",
-    "packages/extension/assets",
-    "packages/extension/src",
-    "packages/extension/ui",
     "packages/mcp-server/src",
     "packages/native-host/bin",
     "packages/native-host/src",
     "packages/protocol/src",
-    "skills/browser-bridge"
+    "skills/browser-bridge",
+    "!**/test/**",
+    "!**/*.test.*",
+    "!**/*.spec.*"
   ],
   "type": "module",
   "publishConfig": {
@@ -56,16 +52,17 @@
     "lint": "oxlint . && oxfmt --check .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
-    "test:runtime": "node --test packages/protocol/test/*.test.js packages/native-host/test/*.test.js packages/agent-client/test/*.test.js packages/mcp-server/test/*.test.js packages/extension/test/*.test.js",
-    "test": "c8 node --test packages/protocol/test/*.test.js packages/native-host/test/*.test.js packages/agent-client/test/*.test.js packages/mcp-server/test/*.test.js packages/extension/test/*.test.js",
+    "test:runtime": "node --test",
+    "test": "c8 node --test",
     "coverage": "c8 report --reporter=text --reporter=text-summary",
-    "coverage:check": "c8 check-coverage --lines 70",
+    "coverage:review": "c8 report --reporter=json-summary && node scripts/review-coverage.mjs",
+    "coverage:check": "c8 check-coverage --lines 80 --branches 75",
     "typecheck": "tsc --noEmit",
     "postinstall": "node packages/native-host/bin/postinstall.js",
     "package:extension": "node scripts/package-extension.mjs",
     "check:extension-zip": "node scripts/check-extension-zip.mjs",
     "release:check": "npm run lint && npm run typecheck && npm test && npm run coverage:check && npm run package:extension && npm pack --dry-run",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm test",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run coverage:check",
     "status": "node packages/agent-client/src/cli.js status",
     "daemon": "node packages/native-host/bin/bridge-daemon.js",
     "install-manifest": "node packages/native-host/bin/install-manifest.js"
@@ -78,6 +75,7 @@
     "@types/chrome": "^0.1.40",
     "@types/node": "^25.5.2",
     "c8": "^11.0.0",
+    "linkedom": "^0.18.12",
     "oxfmt": "^0.47.0",
     "oxlint": "^1.62.0",
     "typescript": "^6.0.3"

package/packages/agent-client/src/cli-helpers.js

@@ -3,6 +3,39 @@
 import readline from 'node:readline';
 import { bridgeMethodNeedsTab } from '../../protocol/src/index.js';
 
+/**
+ * Strip ANSI escape sequences from a string to prevent terminal injection
+ * from malicious page content (e.g. DOM text, console output, eval results).
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function stripAnsi(str) {
+  // oxlint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').replace(/\x1b[^[]/g, '');
+}
+
+/**
+ * Recursively sanitize all string values in a value tree by stripping ANSI
+ * escape sequences. Only strings are touched; structure is preserved.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function sanitizeOutput(value) {
+  if (typeof value === 'string') return stripAnsi(value);
+  if (Array.isArray(value)) return value.map(sanitizeOutput);
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(/** @type {Record<string, unknown>} */ (value)).map(([k, v]) => [
+        k,
+        sanitizeOutput(v),
+      ])
+    );
+  }
+  return value;
+}
+
 /**
  * @param {string[]} values
  * @returns {Record<string, string>}

package/packages/agent-client/src/cli.js

@@ -6,7 +6,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { SUPPORTED_BROWSERS } from '../../native-host/src/config.js';
+import {
+  applyWindowsTcpTransportDefaults,
+  SUPPORTED_BROWSERS,
+} from '../../native-host/src/config.js';
+import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 import { uninstallNativeManifest } from '../../native-host/src/install-manifest.js';
 import {
   createRuntimeContext,
@@ -23,8 +27,8 @@ import {
   methodNeedsTab,
   parseIntArg,
   parseJsonObject,
+  sanitizeOutput,
 } from './cli-helpers.js';
-import { detectMcpClients, detectSkillTargets } from './detect.js';
 import {
   findInstalledManagedTargets,
   installAgentFiles,
@@ -50,39 +54,8 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
 /** @typedef {{ image: string, rect: Record<string, unknown> }} ScreenshotResult */
 
 const REQUEST_SOURCE = 'cli';
-
-/**
- * Strip ANSI escape sequences from a string to prevent terminal injection
- * from malicious page content (e.g. DOM text, console output, eval results).
- *
- * @param {string} str
- * @returns {string}
- */
-function stripAnsi(str) {
-  // oxlint-disable-next-line no-control-regex
-  return str.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').replace(/\x1b[^[]/g, '');
-}
-
-/**
- * Recursively sanitize all string values in a value tree by stripping ANSI
- * escape sequences. Only strings are touched; structure is preserved.
- *
- * @param {unknown} value
- * @returns {unknown}
- */
-function sanitizeOutput(value) {
-  if (typeof value === 'string') return stripAnsi(value);
-  if (Array.isArray(value)) return value.map(sanitizeOutput);
-  if (value !== null && typeof value === 'object') {
-    return Object.fromEntries(
-      Object.entries(/** @type {Record<string, unknown>} */ (value)).map(([k, v]) => [
-        k,
-        sanitizeOutput(v),
-      ])
-    );
-  }
-  return value;
-}
+const TEST_TIMEOUT_ENV = 'BBX_CLIENT_REQUEST_TIMEOUT_MS';
+const TEST_DETECTED_MCP_CLIENTS_ENV = 'BBX_TEST_DETECTED_MCP_CLIENTS';
 
 /**
  * Read all of stdin as UTF-8 text. Resolves once stdin closes.
@@ -164,9 +137,12 @@ if (command === 'install-skill') {
       global: isGlobal,
       cwd: process.cwd(),
       projectPath: isGlobal ? os.homedir() : process.cwd(),
+      ...getSetupStatusTestOverrides(),
     });
     /** @type {import('./install.js').SupportedTarget[]} */
-    const detected = detectSkillTargets();
+    const detected = /** @type {import('./install.js').SupportedTarget[]} */ (
+      setupStatus.skillTargets.filter((entry) => entry.detected).map((entry) => entry.key)
+    );
     const installedManagedTargets = new Set(
       setupStatus.skillTargets
         .filter((entry) => entry.installed && entry.managed)
@@ -274,8 +250,11 @@ if (command === 'install-mcp') {
       global: isGlobal,
       cwd: process.cwd(),
       projectPath: process.cwd(),
+      ...getSetupStatusTestOverrides(),
     });
-    const detected = detectMcpClients();
+    const detected = /** @type {import('./mcp-config.js').McpClientName[]} */ (
+      setupStatus.mcpClients.filter((entry) => entry.detected).map((entry) => entry.key)
+    );
     const configuredClients = new Set(
       setupStatus.mcpClients.filter((entry) => entry.configured).map((entry) => entry.key)
     );
@@ -386,7 +365,11 @@ if (command === 'mcp') {
   process.exit(1);
 }
 
-const client = new BridgeClient();
+const clientTimeoutMs = getClientTimeoutOverride();
+applyWindowsTcpTransportDefaults();
+const client = new BridgeClient(
+  clientTimeoutMs ? { defaultTimeoutMs: clientTimeoutMs } : undefined
+);
 
 await main();
 
@@ -423,6 +406,18 @@ async function main() {
       return;
     }
 
+    if (command === 'restart') {
+      const result = await restartBridgeDaemon();
+      printJson({
+        ok: true,
+        summary: result.previouslyRunning
+          ? 'Browser Bridge daemon restarted.'
+          : 'Browser Bridge daemon started.',
+        evidence: result,
+      });
+      return;
+    }
+
     if (command === 'logs') {
       await printSummary(await requestBridge(client, 'log.tail', {}, { source: REQUEST_SOURCE }));
       return;
@@ -470,7 +465,7 @@ async function main() {
         tabId,
         source: REQUEST_SOURCE,
       });
-      printJson(response.ok ? response.result : response);
+      printCallResponse(response);
       return;
     }
 
@@ -557,7 +552,7 @@ async function main() {
         tabId,
         source: REQUEST_SOURCE,
       });
-      printJson(response.ok ? response.result : response);
+      printCallResponse(response);
       return;
     }
 
@@ -597,6 +592,26 @@ async function main() {
       return;
     }
 
+    if (command === 'cdp-press-key') {
+      const parsed = extractTabFlag(rest);
+      const [key, code] = parsed.rest;
+      if (!key) throw new Error('Usage: cdp-press-key [--tab <tabId>] <key> [code]');
+      const response = await requestBridge(
+        client,
+        'cdp.dispatch_key_event',
+        {
+          key,
+          code,
+        },
+        {
+          tabId: parsed.tabId,
+          source: REQUEST_SOURCE,
+        }
+      );
+      await printSummary(response, 'cdp.dispatch_key_event');
+      return;
+    }
+
     if (command === 'screenshot') {
       const [refOrSelector, outputPath] = rest;
       if (!refOrSelector) throw new Error('Usage: screenshot <ref|selector> [path]');
@@ -650,7 +665,7 @@ async function main() {
     const message = error instanceof Error ? error.message : String(error);
     const raw = error instanceof Error && 'code' in error ? /** @type {any} */ (error).code : '';
     let code = 'ERROR';
-    if (raw === 'ENOENT' || raw === 'ECONNREFUSED') {
+    if (raw === 'ENOENT' || raw === 'ECONNREFUSED' || raw === 'EINVAL') {
       code = 'DAEMON_OFFLINE';
     } else if (raw === 'BRIDGE_TIMEOUT') {
       code = 'BRIDGE_TIMEOUT';
@@ -670,6 +685,48 @@ async function main() {
   }
 }
 
+/**
+ * Allow tests to shrink request timeouts without changing the shared default.
+ *
+ * @returns {number | undefined}
+ */
+function getClientTimeoutOverride() {
+  const raw = process.env[TEST_TIMEOUT_ENV];
+  if (!raw) {
+    return undefined;
+  }
+
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/**
+ * Allow CLI tests to provide deterministic MCP client detection without relying
+ * on whatever tools happen to be installed on the host machine.
+ *
+ * @returns {{
+ *   mcpDetectors?: Record<string, () => boolean>,
+ * }}
+ */
+function getSetupStatusTestOverrides() {
+  if (!(TEST_DETECTED_MCP_CLIENTS_ENV in process.env)) {
+    return {};
+  }
+
+  const detectedClients = new Set(
+    (process.env[TEST_DETECTED_MCP_CLIENTS_ENV] || '')
+      .split(',')
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean)
+  );
+
+  return {
+    mcpDetectors: Object.fromEntries(
+      MCP_CLIENT_NAMES.map((clientName) => [clientName, () => detectedClients.has(clientName)])
+    ),
+  };
+}
+
 /**
  * @param {{ detected: boolean, installed: boolean }} options
  * @returns {string | undefined}
@@ -714,6 +771,24 @@ function printJson(value) {
   );
 }
 
+/**
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @returns {void}
+ */
+function printCallResponse(response) {
+  if (response.ok) {
+    printJson(response.result);
+    return;
+  }
+
+  process.exitCode = 1;
+  const errorText = `${response.error.code}: ${response.error.message}`;
+  process.stderr.write(
+    `${process.stderr.isTTY ? `\u001b[31m${sanitizeOutput(errorText)}\u001b[0m` : sanitizeOutput(errorText)}\n`
+  );
+  printJson(response);
+}
+
 function printUsage() {
   const blocks = ['Usage: bbx <command> [args]'];
   for (const section of CLI_HELP_SECTIONS) {

package/packages/agent-client/src/client.js

@@ -10,7 +10,13 @@ import {
   PROTOCOL_VERSION,
   parseJsonLines,
 } from '../../protocol/src/index.js';
-import { getSocketPath } from '../../native-host/src/config.js';
+import {
+  createSocketBridgeTransport,
+  getBridgeTransport,
+  getSocketPath,
+} from '../../native-host/src/config.js';
+
+/** @typedef {import('../../native-host/src/config.js').BridgeTransport} BridgeTransport */
 
 /** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('../../protocol/src/types.js').BridgeMeta} BridgeMeta */
@@ -42,6 +48,16 @@ import { getSocketPath } from '../../native-host/src/config.js';
  * }} PendingRequest
  */
 
+/**
+ * @typedef {{
+ *   transport?: BridgeTransport,
+ *   socketPath?: string,
+ *   clientId?: string,
+ *   defaultTimeoutMs?: number,
+ *   autoReconnect?: boolean,
+ * }} BridgeClientOptions
+ */
+
 /**
  * @param {string} method
  * @param {number} timeoutMs
@@ -56,14 +72,20 @@ function createTimeoutError(method, timeoutMs) {
 }
 
 export class BridgeClient extends EventEmitter {
+  /**
+   * @param {BridgeClientOptions} [options={}]
+   */
   constructor({
-    socketPath = getSocketPath(),
+    transport = getBridgeTransport(),
+    socketPath = undefined,
     clientId = `agent_${randomUUID()}`,
     defaultTimeoutMs = DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
     autoReconnect = false,
   } = {}) {
     super();
-    this.socketPath = socketPath;
+    this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
+    this.socketPath =
+      this.transport.type === 'socket' ? this.transport.socketPath : getSocketPath();
     this.clientId = clientId;
     this.defaultTimeoutMs = defaultTimeoutMs;
     this.autoReconnect = autoReconnect;
@@ -83,7 +105,10 @@ export class BridgeClient extends EventEmitter {
     if (this.socket) {
       throw new Error('BridgeClient is already connected.');
     }
-    const socket = net.createConnection(this.socketPath);
+    const socket =
+      this.transport.type === 'tcp'
+        ? net.createConnection({ host: this.transport.host, port: this.transport.port })
+        : net.createConnection(this.transport.socketPath);
     this.socket = socket;
     try {
       await new Promise((resolve, reject) => {

package/packages/agent-client/src/command-registry.js

@@ -237,6 +237,7 @@ export const CLI_METHOD_BINDINGS = Object.freeze({
   ),
   ...Object.fromEntries(BRIDGE_METHODS.map((method) => [method, method])),
   'press-key': 'input.press_key',
+  'cdp-press-key': 'cdp.dispatch_key_event',
   screenshot: 'screenshot.capture_element',
   eval: 'page.evaluate',
 });
@@ -253,6 +254,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf',
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Diagnose install, daemon, extension, and access readiness',
+      'bbx restart                                                        Restart the local Browser Bridge daemon',
       'bbx access-request                                                 Request Browser Bridge access for the focused window',
       'bbx logs                                                           Recent bridge logs',
       'bbx tabs                                                           List available tabs',
@@ -330,6 +332,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
           `${SHORTCUT_COMMANDS[command].usage.padEnd(64)} ${SHORTCUT_COMMANDS[command].description}`
       ),
       'bbx press-key <key> [ref|selector]                                 Send key event',
+      'bbx cdp-press-key [--tab <tabId>] <key> [code]                      Dispatch CDP keyDown/keyUp without focusing the tab',
     ],
   },
   {