bwb-browser 3.1.0 → 3.2.0

package/AGENTS.md

@@ -1,12 +1,12 @@
 # bwb-browser — Agent Integration Guide
 
 > **Author:** Krish Tiwari ([@krshforever](https://github.com/krshforever))
-> **Package:** [`bwb-browser`](https://www.npmjs.com/package/bwb-browser) · 76KB source · 25 tools
-> **Last updated:** 2026-07-28
+> **Package:** [`bwb-browser`](https://www.npmjs.com/package/bwb-browser) · 76KB source · 26 tools
+> **Last updated:** 2026-08-06
 
 ## What is bwb?
 
-**Browser Without Bloat** — a lightweight MCP server that gives any AI agent browser superpowers. 76KB. 25 tools. Zero heavy dependencies.
+**Browser Without Bloat** — a lightweight MCP server that gives any AI agent browser superpowers. 76KB. 26 tools. Zero heavy dependencies.
 
 While other MCP browser tools ship a full browser binary (Playwright MCP = ~250MB, Puppeteer MCP = ~400MB), bwb uses **raw Chrome DevTools Protocol (CDP)** — the protocol Chrome speaks natively. It auto-detects the browser already on your system.
 
@@ -52,7 +52,7 @@ npm install -g bwb-browser
 
 # 2. Verify it works
 bwb --version
-# → bwb-browser 3.0.0
+# → bwb-browser 3.2.0
 
 # 3. Add to your AI agent's MCP config
 ```
@@ -64,10 +64,10 @@ bwb --version
 Give this to any AI agent (Claude, OpenCode, Gemini, etc.) to auto-install and configure bwb:
 
 ```
-I want you to install and use bwb-browser — a 76KB MCP browser automation server with 25 tools.
+I want you to install and use bwb-browser — a 76KB MCP browser automation server with 26 tools.
 
 bwb is Browser Without Bloat. It uses raw Chrome DevTools Protocol (no Playwright, no Puppeteer).
-It has 25 tools including:
+It has 26 tools including:
 
 - `browser_act` — natural language interaction ("search for X", "click the button", "what's on this page")
 - `browser_watch` — live capture of console messages, network requests, JS exceptions, page navigations
@@ -126,7 +126,7 @@ When using bwb for web tasks, follow these patterns:
 ### Basic Browsing
 - `browser_goto({url: "https://example.com"})` — navigate to a page
 - `browser_title()` — check page title
-- `browser_screenshot()` — take a screenshot (also saves to /storage/emulated/0/Download/bwb-screenshots/ on Android or ~/bwb-screenshots/ on desktop)
+- `browser_screenshot({selector: "#chart"})` — take a screenshot (whole page, viewport, or one element; saves to /storage/emulated/0/Download/bwb-screenshots/ on Android or ~/bwb-screenshots/ on desktop)
 - `browser_text()` — get page text content
 - `browser_html()` — get page HTML
 - `browser_elements({kind: "links"|"buttons"|"inputs"|"headings"})` — find interactive elements
@@ -167,7 +167,7 @@ internally — not just what it looks like.
 | **`browser_diagnose`** | 🔥 Full page health check — perf, errors, broken images, score |
 | **`browser_fingerprint`** | 🔥 Realistic browser profile for testing |
 | `browser_goto` | Navigate to a URL |
-| `browser_screenshot` | Take a screenshot (saves to disk + returns base64) |
+| `browser_screenshot` | Take a screenshot — full page, viewport, or a single element via `selector` (saves to disk + returns base64) |
 | `browser_html` | Get page/selector HTML |
 | `browser_text` | Get page/selector visible text |
 | `browser_click` | Click an element (native CDP mouse events) |

package/README.md

@@ -1,6 +1,6 @@
 # bwb-browser
 
-**Browser Without Bloat** — 76KB. 25 tools. Zero dependencies. Runs on your phone.
+**Browser Without Bloat** — 76KB. 26 tools. Zero dependencies. Runs on your phone.
 
 A lightweight MCP server that gives any AI agent browser superpowers. Written by a guy in India on Termux because the existing tools were 200MB of "why."
 
@@ -74,6 +74,36 @@ Create tabs, close them, switch between them, save cookies, load them back. Like
 
 Normalizes `navigator.webdriver`, plugins, languages, and user-agent for testing environments. Not "stealth mode" — just honest fingerprint normalization so your tests actually match real user conditions.
 
+### 7. Element Screenshots (new in 3.2.0)
+
+Capture just one element — a login form, a chart, a product card — not the whole page:
+
+```javascript
+browser_screenshot({selector: "#price-chart"})
+browser_screenshot({selector: "h1"})           // The headline, cropped
+browser_screenshot({fullPage: true})            // The whole page
+browser_screenshot({})                          // Just the viewport
+```
+
+Every screenshot is saved to disk (Android: `/storage/emulated/0/Download/bwb-screenshots/`, desktop: `~/bwb-screenshots/`) **and** returned to your agent as a base64 image.
+
+---
+
+## What's New in 3.2.0
+
+### New
+- **`browser_screenshot({ selector })`** — element-level capture. Grab just the login form, the chart, the product card — not the whole page.
+- **Screenshot directory auto-detect** — Termux/Android → `/storage/emulated/0/Download/bwb-screenshots/`, desktop → `~/bwb-screenshots/`. Override with `BWB_SCREENSHOTS_DIR`.
+
+### Bug Fixes
+- **`browser_back` rewritten** — native CDP history navigation (the `Page.goBack` call doesn't exist in bundled CDP 1.3; the old `history.back()` JS hack is gone). Verified with real two-step back navigation.
+- **`browser_act` precision fixes** — navigation regex no longer swallows compound instructions ("go to X and read the title" works), "fill X with Y" vs "type Y in X" no longer swap target/text, and `search` can't hijack "fill search with X"
+- **`killOrphanedChrome` safety** — graceful SIGTERM→SIGKILL, now scoped to bwb's own profile so it never kills another agent's browser
+- **`browser_restart` hygiene** — watch listeners can't outlive the dying protocol
+- **`browser_status` accuracy** — uses the real bound port, no more hardcoded 9222 poke
+
+*Fixes from the PR #1 code review by @netzro (Hermes Agent) are incorporated and credited in the [changelog](./CHANGELOG.md).*
+
 ---
 
 ## Quick Install
@@ -81,7 +111,7 @@ Normalizes `navigator.webdriver`, plugins, languages, and user-agent for testing
 ```bash
 npm install -g bwb-browser
 bwb --version
-# → bwb-browser 3.0.0
+# → bwb-browser 3.2.0
 ```
 
 Done. If you have Chrome/Chromium anywhere on your system, bwb finds it. No config files. No environment variables. Just works.
@@ -97,7 +127,7 @@ bwb
 
 ---
 
-## All 25 Tools
+## All 26 Tools
 
 | Tool | Description |
 |------|-------------|
@@ -106,7 +136,7 @@ bwb
 | **`browser_diagnose`** | 🔥 Full page health check — perf, errors, broken images, score |
 | **`browser_fingerprint`** | 🔥 Realistic browser profile for testing |
 | `browser_goto` | Navigate to a URL |
-| `browser_screenshot` | Take a screenshot |
+| `browser_screenshot` | Take a screenshot — whole page, viewport, or a single element via `selector` |
 | `browser_html` | Get page/selector HTML |
 | `browser_text` | Get page/selector text |
 | `browser_title` | Get page title |

package/lib/act.mjs

@@ -165,7 +165,10 @@ export async function executeInstruction(protocol, instruction) {
   const lower = instruction.trim().toLowerCase();
 
   // ─── Pattern: "go to URL" / "navigate to URL" / "open URL" ──────────────
-  const navMatch = lower.match(/^(?:go to|navigate to|open|visit|take me to)\s+(.+)/);
+  // Capture only the URL token — stop at natural instruction boundaries so
+  // compound instructions ("go to X and tell me the title") don't swallow
+  // the whole sentence into the URL.
+  const navMatch = lower.match(/^(?:go to|navigate to|open|visit|take me to)\s+([^\s,]+(?:\.[^\s,]+)*)(?=\s|$)/);
   if (navMatch) {
     const url = normalizeUrl(navMatch[1]);
     if (url) {
@@ -187,7 +190,9 @@ export async function executeInstruction(protocol, instruction) {
   // If navMatch but URL was invalid (normalizeUrl returned null), fall through to search
 
   // ─── Pattern: "search for X" / "search X" ───────────────────────────────
-  const searchMatch = lower.match(/search\s+(?:for\s+)?(.+)/);
+  // Anchored to string start: unanchored, "fill search with X" would be
+  // hijacked by this pattern before fill could handle it.
+  const searchMatch = lower.match(/^search\s+(?:for\s+)?(.+)/);
   if (searchMatch) {
     const query = searchMatch[1];
     let inputInfo = await findInput(Runtime, "search");
@@ -263,7 +268,25 @@ export async function executeInstruction(protocol, instruction) {
   }
 
   // ─── Pattern: "fill X with Y" / "type Y in X" / "enter Y into X" ──────
-  const fillMatch = lower.match(/(?:fill|type|enter)\s+(.+?)\s+(?:in|into|with)\s+(.+)/);
+  // NOTE: "fill X with Y" puts the VALUE in X ("fill email with foo@bar.com"),
+  // while "type Y in X" puts the TEXT in X ("type hello in search").
+  const fillWithMatch = lower.match(/fill\s+(.+?)\s+with\s+(.+)/);
+  if (fillWithMatch) {
+    const target = fillWithMatch[1];
+    const text = fillWithMatch[2];
+    const inputInfo = await findInput(Runtime, target);
+    if (inputInfo.found && inputInfo.selector) {
+      await Runtime.evaluate({
+        expression: `document.querySelector(${JSON.stringify(inputInfo.selector)})?.focus()`,
+      });
+      await Input.insertText({ text });
+      await new Promise(r => setTimeout(r, 200));
+      return { action: "fill", target, text, inputTag: inputInfo.tag };
+    }
+    return { action: "fill_error", target, error: `Could not find input matching "${target}"` };
+  }
+
+  const fillMatch = lower.match(/(?:type|enter)\s+(.+?)\s+(?:in|into)\s+(.+)/);
   if (fillMatch) {
     const text = fillMatch[1];
     const target = fillMatch[2];

package/lib/browser.mjs

@@ -41,8 +41,18 @@ export const cfg = {
 // NOT the user's normal Chrome browser.
 export function killOrphanedChrome() {
   try {
+    // Only touch Chromes using OUR user-data-dir — never another agent's browser.
+    const scopedMatch = cfg.userDataDir
+      ? `grep "remote-debugging-port" | grep "${String(cfg.userDataDir).replace(/["\\]/g, "\\$&")}" | grep -v grep`
+      : `grep "remote-debugging-port" | grep -v grep`;
+    // SIGTERM first for clean shutdown
     execSync(
-      `ps aux | grep "remote-debugging-port" | grep -v grep | awk '{print $2}' | xargs -r kill -9 2>/dev/null; true`,
+      `ps aux | ${scopedMatch} | awk '{print $2}' | xargs -r kill -15 2>/dev/null; true`,
+      { encoding: "utf8", timeout: 5000 }
+    );
+    // Give them a moment to exit cleanly, then SIGKILL survivors
+    execSync(
+      `sleep 1 && ps aux | ${scopedMatch} | awk '{print $2}' | xargs -r kill -9 2>/dev/null; true`,
       { encoding: "utf8", timeout: 5000 }
     );
   } catch {}

package/lib/diagnose.mjs

@@ -16,9 +16,16 @@ export async function diagnosePage(protocol) {
   // Collect console errors during diagnostic
   const consoleErrors = [];
   let unsubConsole, unsubException;
+  let runtimeWasAlreadyEnabled = false;
 
   try {
-    await Runtime.enable();
+    // Check if Runtime is already enabled; if not, enable it
+    try {
+      await Runtime.enable();
+    } catch {
+      // Already enabled — that's fine, but don't disable it later
+      runtimeWasAlreadyEnabled = true;
+    }
     unsubConsole = Runtime.consoleAPICalled((params) => {
       if (params.type === "error" || params.type === "warning") {
         consoleErrors.push({
@@ -114,6 +121,9 @@ export async function diagnosePage(protocol) {
   // Cleanup
   try { if (unsubConsole) unsubConsole(); } catch {}
   try { if (unsubException) unsubException(); } catch {}
+  if (!runtimeWasAlreadyEnabled) {
+    try { await Runtime.disable(); } catch {}
+  }
 
   return {
     url: currentUrl,

package/lib/fingerprint.mjs

@@ -49,11 +49,16 @@ export async function applyRealisticProfile(protocol) {
         configurable: true,
       });
 
-      // Remove automation-specific chrome.runtime
+      // Remove automation-specific chrome.runtime (strict-mode safe:
+      // delete on a non-configurable prop throws, defineProperty with a
+      // getter is legal even in strict mode)
       if (window.chrome) {
-        if (window.chrome.runtime) {
-          delete window.chrome.runtime;
-        }
+        try {
+          Object.defineProperty(window.chrome, 'runtime', {
+            get: () => undefined,
+            configurable: true,
+          });
+        } catch {}
         if (!window.chrome.loadTimes) {
           window.chrome.loadTimes = function() { return {}; };
         }

package/lib/helpers.mjs

@@ -116,8 +116,7 @@ export async function waitForSelector(runtime, selector, opts = {}) {
     const info = JSON.parse(result?.value || "{}");
 
     if (disappear && info.status === "NOT_FOUND") return true;
-    if (!disappear && info.status === "FOUND" && !info.hidden) return true;
-    if (!disappear && info.status === "FOUND" && !opts.visible) return true;
+    if (!disappear && info.status === "FOUND" && (!opts.visible || !info.hidden)) return true;
 
     await new Promise((r) => setTimeout(r, 200));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bwb-browser",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Browser Without Bloat — 76KB MCP server that gives AI agents browser superpowers. Natural language interaction, live event watching, persistent sessions, multi-tab. Runs on Termux/Android, desktop, and CI. Zero heavy dependencies.",
   "bin": {
     "bwb": "bin/bwb"

package/server.mjs

@@ -18,8 +18,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import CDP from "chrome-remote-interface";
-import { mkdirSync } from "fs";
-import { homedir } from "os";
+import { mkdirSync, readFileSync, existsSync } from "fs";
+import { homedir, platform } from "os";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
@@ -52,6 +52,11 @@ import { executeInstruction } from "./lib/act.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// Read version from package.json — single source of truth
+const { version: BWB_VERSION } = JSON.parse(
+  readFileSync(join(__dirname, 'package.json'), 'utf8')
+);
+
 function parseArgs() {
   const args = process.argv.slice(2);
   const cliCfg = {};
@@ -63,7 +68,7 @@ function parseArgs() {
       case "--headless": cliCfg.headless = args[++i] !== "false"; break;
       case "--screenshots-dir": cliCfg.screenshotsDir = args[++i]; break;
       case "--timeout": cliCfg.navTimeout = parseInt(args[++i], 10); break;
-      case "--version": console.log("bwb-browser 3.0.0"); process.exit(0);
+      case "--version": console.log(`bwb-browser ${BWB_VERSION}`); process.exit(0);
       case "--help": printHelp(); process.exit(0);
     }
   }
@@ -72,9 +77,9 @@ function parseArgs() {
 
 function printHelp() {
   console.log(`
-bwb-browser v3.0.0 — Browser Without Bloat
+bwb-browser v${BWB_VERSION} — Browser Without Bloat
 
-Browser automation for AI agents. 76KB. 25 tools. Zero heavy dependencies.
+Browser automation for AI agents. 76KB. 26 tools. Zero heavy dependencies.
 Uses raw CDP — no Playwright, no Puppeteer, no 400MB downloads.
 
 Built on Termux/Android. Runs everywhere. Weighs nothing.
@@ -92,7 +97,7 @@ OPTIONS:
   --version                Print version
   --help                   Show this help
 
-TOOLS (25):
+TOOLS (26):
   CORE BROWSING:
     browser_goto              Navigate to a URL
     browser_screenshot        Take a screenshot
@@ -169,7 +174,14 @@ Object.assign(cfg, parseArgs());
 cfg.port = cfg.port || parseInt(process.env.BWB_CDP_PORT || "0", 10);
 cfg.headless = cfg.headless !== undefined ? cfg.headless : (process.env.BWB_HEADLESS !== "false");
 cfg.userDataDir = cfg.userDataDir || process.env.BWB_USER_DATA_DIR || join(homedir(), ".cache", "bwb-browser");
-cfg.screenshotsDir = cfg.screenshotsDir || process.env.BWB_SCREENSHOTS_DIR || "/storage/emulated/0/Download/bwb-screenshots";
+cfg.screenshotsDir = cfg.screenshotsDir || process.env.BWB_SCREENSHOTS_DIR || (() => {
+  // Auto-detect: Termux/Android path if available, else ~/bwb-screenshots/
+  const androidPath = "/storage/emulated/0/Download/bwb-screenshots";
+  if (platform() === "android" && existsSync("/storage/emulated/0/Download")) return androidPath;
+  if (process.env.HOME?.includes("com.termux")) return androidPath;
+  if (process.env.TERMUX_VERSION) return androidPath;
+  return join(homedir(), "bwb-screenshots");
+})();
 cfg.navTimeout = cfg.navTimeout || parseInt(process.env.BWB_NAV_TIMEOUT || "30000", 10);
 
 try { mkdirSync(cfg.screenshotsDir, { recursive: true }); } catch {}
@@ -224,7 +236,7 @@ function setupWatch(events, cdp) {
 
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
-const server = new McpServer({ name: "bwb-browser", version: "3.0.0" });
+const server = new McpServer({ name: "bwb-browser", version: BWB_VERSION });
 
 // Tool implementations
 const tools = {
@@ -243,16 +255,43 @@ const tools = {
   },
 
   browser_screenshot: {
-    description: "Take a screenshot of the current page.",
+    description: "Take a screenshot of the current page. Pass a CSS selector to capture just that element.",
     schema: {
       fullPage: z.boolean().describe("Full page screenshot (default false)").optional(),
       quality: z.number().describe("JPEG quality 0-100 (default 80)").optional(),
+      selector: z.string().describe("CSS selector to capture only that element (optional)").optional(),
     },
-    handler: async ({ fullPage = false, quality = 80 }) => {
-      const { Page } = await getActiveProtocol();
-      const { data } = await Page.captureScreenshot({ format: "jpeg", quality, captureBeyondViewport: fullPage });
+    handler: async ({ fullPage = false, quality = 80, selector }) => {
+      const { Page, Runtime } = await getActiveProtocol();
+      let clip;
+      if (selector) {
+        // Element capture: compute bounding rect in page coords, then clip
+        const { result } = await Runtime.evaluate({
+          expression: `(() => {
+            const el = document.querySelector(${JSON.stringify(selector)});
+            if (!el) return null;
+            const r = el.getBoundingClientRect();
+            const sx = window.scrollX || document.documentElement.scrollLeft;
+            const sy = window.scrollY || document.documentElement.scrollTop;
+            return JSON.stringify({ x: r.x + sx, y: r.y + sy, width: r.width, height: r.height });
+          })()`,
+          returnByValue: true,
+        });
+        const rect = result?.value ? JSON.parse(result.value) : null;
+        if (!rect || !rect.width || !rect.height) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: `Element not found or not visible: ${selector}` }) }] };
+        }
+        clip = { ...rect, scale: 1 };
+      }
+      // captureBeyondViewport=false keeps clip math in viewport space; a 0-size clip
+      // would be rejected by CDP, so guard against degenerate rects above.
+      const { data } = await Page.captureScreenshot({
+        format: "jpeg", quality,
+        captureBeyondViewport: fullPage || !!clip,
+        ...(clip ? { clip } : {}),
+      });
       const savedPath = saveScreenshot(data);
-      const response = { screenshot: `data:image/jpeg;base64,${data.slice(0, 40)}...` };
+      const response = { screenshot: `data:image/jpeg;base64,${data.slice(0, 40)}...`, captured: clip ? selector : (fullPage ? "full page" : "viewport") };
       if (savedPath) response.savedTo = savedPath;
       return { content: [
         { type: "image", data, mimeType: "image/jpeg" },
@@ -312,8 +351,17 @@ const tools = {
     schema: {},
     handler: async () => {
       const { Page, Runtime } = await getActiveProtocol();
-      await Page.navigate({ url: "javascript:history.back()" });
-      await new Promise(r => setTimeout(r, 500));
+      // Native CDP back: walk history via navigation entries.
+      // NOTE: Page.goBack doesn't exist in the bundled CDP 1.3 protocol —
+      // getNavigationHistory + navigateToHistoryEntry is the native equivalent.
+      // The wrapper returns history FLAT ({currentIndex, entries}), not {result:{...}}.
+      const hist = await Page.getNavigationHistory();
+      const entries = hist?.entries || [];
+      const currentIdx = hist?.currentIndex ?? -1;
+      if (currentIdx > 0 && entries[currentIdx - 1]) {
+        await Page.navigateToHistoryEntry({ entryId: entries[currentIdx - 1].id });
+      }
+      await new Promise(r => setTimeout(r, Math.min(cfg.navTimeout, 1000)));
       const { result } = await Runtime.evaluate({ expression: "document.title" });
       syncActiveTab(result?.value, undefined);
       return { content: [{ type: "text", text: JSON.stringify({ title: result?.value || "" }) }] };
@@ -550,18 +598,17 @@ const tools = {
         status.running = true;
         status.pid = browser.pid;
         status.tabs = listTabs();
-        try {
-          if (actualCdpPort) {
-            status.actualPort = actualCdpPort;
-            const targets = await CDP.List({ port: actualCdpPort });
-            status.connected = true;
-            status.targets = targets.map(t => ({ type: t.type, url: t.url, title: t.title }));
-          } else {
-            const targets = await CDP.List({ port: cfg.port || 9222 });
+        // actualCdpPort is the real bound port; cfg.port may be 0 (random).
+        // Never fall back to a hardcoded 9222 — that could be another tool's browser.
+        const listPort = actualCdpPort || cfg.port;
+        if (listPort) {
+          try {
+            status.actualPort = actualCdpPort || cfg.port;
+            const targets = await CDP.List({ port: listPort });
             status.connected = true;
             status.targets = targets.map(t => ({ type: t.type, url: t.url, title: t.title }));
-          }
-        } catch { status.connected = false; }
+          } catch { status.connected = false; }
+        }
       }
       return { content: [{ type: "text", text: JSON.stringify(status) }] };
     },
@@ -572,6 +619,7 @@ const tools = {
     schema: {},
     handler: async () => {
       clearTabs(); // Kill stale tab connections before restart
+      cleanupWatch(); // Detach event listeners from the dying protocol before it's gone
       const result = await restartBrowser();
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     },