@btraut/browser-bridge 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on "Keep a Changelog", and this project adheres to Semantic Versioning.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-02-06
+
+### Added
+
+- `browser-bridge install` interactive installer for skills and MCP.
+- `browser-bridge skill install` and `browser-bridge skill status`.
+- `browser-bridge mcp install` for Codex, Claude, and Cursor.
+- Skill version manifest (`skill.json`) to detect out-of-date installs.
+- `browser-bridge mcp serve` (while keeping `browser-bridge mcp` working).
+
+## [0.2.0] - 2026-02-05
+
+### Added
+
+- `browser-bridge inspect dom-snapshot --max-nodes <n>` (AX format only) to bound snapshot size for agent/LLM consumption.
+
+## [0.1.1] - 2026-02-05
+
+### Added
+
+- Initial release.

package/README.md

@@ -1,14 +1,16 @@
+<img src="docs/assets/readme-header.png" alt="Browser Bridge header graphic" width="720" />
+
+[![npm version](https://img.shields.io/npm/v/@btraut/browser-bridge.svg)](https://www.npmjs.com/package/@btraut/browser-bridge) [![CI](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/btraut/browser-bridge.svg)](LICENSE)
+
 # Browser Bridge
 
-Local Chrome control for coding agents. Browser Bridge provides a CLI and an
-optional MCP server that drive a real Chrome instance and read page state
-through a Chrome extension.
+Local Chrome control for coding agents. Browser Bridge provides a CLI and an optional MCP server that drive your real, local Chrome (not headless) and read page state through a Chrome extension. This keeps you in the loop, with your existing tabs and login state.
 
 ## Requirements
 
 - Node.js 20+
 - Chrome (stable)
-- Browser Bridge extension (Chrome Web Store; listing coming soon)
+- Browser Bridge extension (Chrome Web Store listing pending; see manual install below)
 - Local-only usage (all services bind to 127.0.0.1)
 
 ## Install
@@ -18,12 +20,24 @@ npm i -g @btraut/browser-bridge
 browser-bridge --help
 ```
 
+## Chrome Extension (Manual Install)
+
+Chrome Web Store listing is pending. For now, install the extension manually:
+
+1. Clone this repo.
+2. Install deps and build:
+
+```bash
+npm install
+npm run build
+```
+
+3. Open Chrome and navigate to `chrome://extensions`.
+4. Enable **Developer mode**, click **Load unpacked**, and select `packages/extension` (the folder with `manifest.json`).
+
 ## Quickstart
 
-1. Install the Chrome Web Store extension (listing coming soon). For local
-   testing without the store, you can load unpacked from:
-   - this repo: `packages/extension`
-   - npm install: `$(npm root -g)/@btraut/browser-bridge/extension`
+1. Install the extension (see "Chrome Extension (Manual Install)" above).
 2. Install the Browser Bridge skill (see below).
 3. (Optional) Add Browser Bridge to your MCP client (Codex or Claude Code below).
 4. Run a quick CLI check:
@@ -32,13 +46,23 @@ browser-bridge --help
 browser-bridge session create
 # Use the session_id from the output for the next commands.
 browser-bridge drive navigate --session-id <id> --url https://example.com
-browser-bridge inspect dom-snapshot --session-id <id>
+browser-bridge inspect dom-snapshot --session-id <id> --max-nodes 2000
 browser-bridge session close --session-id <id>
 ```
 
+Notes:
+
+- `inspect dom-snapshot` defaults to `--format ax`; `--max-nodes` is only supported for AX snapshots.
+
 ## Skills (Codex + Claude Code)
 
-Copy the Browser Bridge skill into your agent skills directory:
+Easiest option (recommended):
+
+```bash
+browser-bridge install
+```
+
+Or copy the Browser Bridge skill into your agent skills directory:
 
 ```bash
 # From this repo:
@@ -54,14 +78,11 @@ Restart your agent app if it does not pick up the new skill automatically.
 
 ## MCP Server (Optional)
 
-The MCP server runs over stdio and forwards tool calls to Core. It is optional,
-since you can use the CLI directly. MCP clients launch it automatically when
-needed, so you typically do not run it yourself.
+The MCP server runs over stdio and forwards tool calls to Core. It is optional, since you can use the CLI directly. MCP clients launch it automatically when needed, so you typically do not run it yourself.
 
 - Manual start (debugging): `browser-bridge mcp`
 - Use your MCP client to call `tools/list`, then `session.create`
-- Override Core host/port with `--host`, `--port`, or `BROWSER_BRIDGE_CORE_HOST` /
-  `BROWSER_BRIDGE_CORE_PORT`.
+- Override Core host/port with `--host`, `--port`, or `BROWSER_BRIDGE_CORE_HOST` / `BROWSER_BRIDGE_CORE_PORT`.
 
 ## Add MCP (Codex CLI)
 
@@ -98,6 +119,14 @@ claude mcp add --transport stdio browser-bridge \
 - CLI: `browser-bridge diagnostics doctor --session-id <id>`
 - Reports extension and debugger status alongside session state.
 
+## Changelog
+
+See `CHANGELOG.md`.
+
+## Releasing
+
+See `docs/releasing.md`.
+
 ## Security Model (v1)
 
 - Extension <-> Core WebSocket has no authentication; trust local machine only.
@@ -111,7 +140,6 @@ If you are contributing locally, load the extension unpacked:
 2. Enable **Developer mode**.
 3. Click **Load unpacked** and select `packages/extension` (repo).
 4. Confirm the extension's background service worker is running.
-5. Start the Core daemon (or run `browser-bridge session create`) so the
-   extension can connect to `127.0.0.1`.
+5. Start the Core daemon (or run `browser-bridge session create`) so the extension can connect to `127.0.0.1`.
 
 Additional manual test flows live in `docs/manual-test.md`.

package/dist/api.js

@@ -1237,6 +1237,9 @@ var InspectService = class {
         if (input.compact) {
           warnings.push("Compact filter is only supported for AX snapshots.");
         }
+        if (input.maxNodes !== void 0) {
+          warnings.push("max_nodes is only supported for AX snapshots.");
+        }
         if (input.selector && html === "") {
           warnings.push(`Selector not found: ${input.selector}`);
         }
@@ -1289,10 +1292,25 @@ var InspectService = class {
             {}
           );
         }
-        const snapshot = input.interactive || input.compact ? this.applyAxSnapshotFilters(result2, {
+        let snapshot = input.interactive || input.compact ? this.applyAxSnapshotFilters(result2, {
           interactiveOnly: input.interactive,
           compact: input.compact
         }) : result2;
+        let truncated = false;
+        const truncationWarnings = [];
+        if (input.maxNodes !== void 0) {
+          const truncatedResult = this.truncateAxSnapshot(
+            snapshot,
+            input.maxNodes
+          );
+          snapshot = truncatedResult.snapshot;
+          truncated = truncatedResult.truncated;
+          if (truncated) {
+            truncationWarnings.push(
+              `AX snapshot truncated to ${input.maxNodes} nodes.`
+            );
+          }
+        }
         const refMap = this.assignRefsToAxSnapshot(snapshot);
         const refWarnings = await this.applySnapshotRefs(
           selection.tabId,
@@ -1301,11 +1319,13 @@ var InspectService = class {
         const warnings = [
           ...selection.warnings ?? [],
           ...selectorWarnings,
+          ...truncationWarnings,
           ...refWarnings ?? []
         ];
         return {
           format: "ax",
           snapshot,
+          ...truncated ? { truncated: true } : {},
           ...warnings.length > 0 ? { warnings } : {}
         };
       } catch (error) {
@@ -1322,6 +1342,7 @@ var InspectService = class {
           const warnings = [
             ...selection.warnings ?? [],
             "AX snapshot failed; returned HTML instead.",
+            ...input.maxNodes !== void 0 ? ["max_nodes is only supported for AX snapshots."] : [],
             ...input.interactive ? ["Interactive filter is only supported for AX snapshots."] : [],
             ...input.compact ? ["Compact filter is only supported for AX snapshots."] : [],
             ...input.selector && html === "" ? [`Selector not found: ${input.selector}`] : []
@@ -1824,6 +1845,106 @@ var InspectService = class {
     }
     return filtered;
   }
+  truncateAxSnapshot(snapshot, maxNodes) {
+    const nodes = this.getAxNodes(snapshot);
+    if (!Number.isFinite(maxNodes) || maxNodes <= 0) {
+      return { snapshot, truncated: false };
+    }
+    if (nodes.length === 0 || nodes.length <= maxNodes) {
+      return { snapshot, truncated: false };
+    }
+    const nodeById = /* @__PURE__ */ new Map();
+    const parentCount = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      if (!node || typeof node !== "object" || typeof node.nodeId !== "string") {
+        continue;
+      }
+      nodeById.set(node.nodeId, node);
+      parentCount.set(node.nodeId, parentCount.get(node.nodeId) ?? 0);
+    }
+    if (nodeById.size === 0) {
+      const sliced = nodes.slice(0, maxNodes);
+      for (const node of sliced) {
+        if (node && typeof node === "object" && Array.isArray(node.childIds)) {
+          node.childIds = [];
+        }
+      }
+      return {
+        snapshot: this.replaceAxNodes(snapshot, sliced),
+        truncated: true
+      };
+    }
+    for (const node of nodes) {
+      if (!node || typeof node !== "object" || !Array.isArray(node.childIds)) {
+        continue;
+      }
+      for (const childId of node.childIds) {
+        if (typeof childId !== "string") {
+          continue;
+        }
+        parentCount.set(childId, (parentCount.get(childId) ?? 0) + 1);
+      }
+    }
+    let roots = Array.from(nodeById.keys()).filter(
+      (id) => (parentCount.get(id) ?? 0) === 0
+    );
+    if (roots.length === 0) {
+      const first = nodes.find(
+        (node) => node && typeof node.nodeId === "string"
+      )?.nodeId;
+      if (first) {
+        roots = [first];
+      }
+    }
+    const kept = /* @__PURE__ */ new Set();
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [...roots];
+    while (queue.length > 0 && kept.size < maxNodes) {
+      const id = queue.shift();
+      if (!id || visited.has(id)) {
+        continue;
+      }
+      visited.add(id);
+      const node = nodeById.get(id);
+      if (!node) {
+        continue;
+      }
+      kept.add(id);
+      if (Array.isArray(node.childIds)) {
+        for (const childId of node.childIds) {
+          if (typeof childId === "string" && !visited.has(childId)) {
+            queue.push(childId);
+          }
+        }
+      }
+    }
+    if (kept.size === 0) {
+      const fallback = [];
+      for (const node of nodes) {
+        if (fallback.length >= maxNodes) {
+          break;
+        }
+        if (node && typeof node.nodeId === "string") {
+          fallback.push(node.nodeId);
+        }
+      }
+      fallback.forEach((id) => kept.add(id));
+    }
+    const filtered = nodes.filter(
+      (node) => node && typeof node.nodeId === "string" && kept.has(node.nodeId)
+    );
+    for (const node of filtered) {
+      if (Array.isArray(node.childIds)) {
+        node.childIds = node.childIds.filter(
+          (id) => typeof id === "string" && kept.has(id)
+        );
+      }
+    }
+    return {
+      snapshot: this.replaceAxNodes(snapshot, filtered),
+      truncated: true
+    };
+  }
   filterAxSnapshot(snapshot, predicate) {
     const nodes = this.getAxNodes(snapshot);
     if (nodes.length === 0) {
@@ -2945,6 +3066,9 @@ var InspectDomSnapshotInputSchema = import_zod2.z.object({
   consistency: InspectConsistencySchema.default("best_effort"),
   interactive: import_zod2.z.boolean().default(false),
   compact: import_zod2.z.boolean().default(false),
+  // Used primarily to bound large AX trees for LLM/agent consumption.
+  // CLI passes this as a string, so coerce for convenience.
+  max_nodes: import_zod2.z.coerce.number().int().positive().max(5e4).optional(),
   selector: import_zod2.z.string().min(1).optional(),
   target: TargetHintSchema.optional()
 });
@@ -3642,6 +3766,7 @@ var registerInspectRoutes = (router, options) => {
         consistency: body.consistency,
         interactive: body.interactive,
         compact: body.compact,
+        maxNodes: body.max_nodes,
         selector: body.selector,
         targetHint: resolveTargetHint(body.target, options)
       });