bwb-browser 2.0.3 → 3.0.0

package/lib/diagnose.mjs

@@ -0,0 +1,149 @@
+/**
+ * bwb-browser — Page Diagnostics
+ *
+ * Comprehensive page health check: performance metrics, console errors,
+ * broken resources, meta tags, and network failures.
+ * Combines multiple CDP + JS checks into a single report.
+ */
+
+/**
+ * Run a full diagnostic on the current page.
+ * Returns performance metrics, console errors, broken images, meta tags.
+ */
+export async function diagnosePage(protocol) {
+  const { Runtime, Network, Page } = protocol;
+
+  // Collect console errors during diagnostic
+  const consoleErrors = [];
+  let unsubConsole, unsubException;
+
+  try {
+    await Runtime.enable();
+    unsubConsole = Runtime.consoleAPICalled((params) => {
+      if (params.type === "error" || params.type === "warning") {
+        consoleErrors.push({
+          level: params.type,
+          text: (params.args || []).map(a => a.value !== undefined ? String(a.value) : a.description || "").join(" "),
+        });
+      }
+    });
+    unsubException = Runtime.exceptionThrown((params) => {
+      const d = params.exceptionDetails;
+      consoleErrors.push({
+        level: "exception",
+        text: d?.exception?.description || d?.text || "Unknown exception",
+      });
+    });
+  } catch {}
+
+  // Allow page to settle
+  await new Promise(r => setTimeout(r, 300));
+
+  // Page load performance
+  let performance = {};
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: `JSON.stringify({
+        loadTime: performance.timing ? (performance.timing.loadEventEnd - performance.timing.navigationStart) : null,
+        domContentLoaded: performance.timing ? (performance.timing.domContentLoadedEventEnd - performance.timing.navigationStart) : null,
+        domInteractive: performance.timing ? (performance.timing.domInteractive - performance.timing.navigationStart) : null,
+      })`,
+      returnByValue: true,
+    });
+    performance = JSON.parse(result?.value || "{}");
+  } catch {}
+
+  // Meta tags
+  let meta = {};
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: `JSON.stringify({
+        title: document.title,
+        description: (document.querySelector('meta[name=description]') || {}).content || '',
+        viewport: (document.querySelector('meta[name=viewport]') || {}).content || '',
+        charset: document.characterSet || '',
+        lang: document.documentElement?.lang || '',
+      })`,
+      returnByValue: true,
+    });
+    meta = JSON.parse(result?.value || "{}");
+  } catch {}
+
+  // Broken images
+  let brokenImages = [];
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: `JSON.stringify(
+        Array.from(document.querySelectorAll('img')).filter(i => i.naturalWidth === 0 && i.src).map(i => ({
+          src: i.src.slice(0, 200),
+          alt: i.alt || '(missing)',
+          width: i.width,
+          height: i.height,
+        }))
+      )`,
+      returnByValue: true,
+    });
+    brokenImages = JSON.parse(result?.value || "[]");
+  } catch {}
+
+  // Links check
+  let linkCount = 0;
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: "document.querySelectorAll('a[href]').length",
+    });
+    linkCount = result?.value || 0;
+  } catch {}
+
+  // Input count
+  let inputCount = 0;
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: "document.querySelectorAll('input:not([type=hidden]), textarea, select, button, [role=button]').length",
+    });
+    inputCount = result?.value || 0;
+  } catch {}
+
+  // Current URL
+  let currentUrl = "";
+  try {
+    const { result } = await Runtime.evaluate({ expression: "location.href" });
+    currentUrl = result?.value || "";
+  } catch {}
+
+  // Cleanup
+  try { if (unsubConsole) unsubConsole(); } catch {}
+  try { if (unsubException) unsubException(); } catch {}
+
+  return {
+    url: currentUrl,
+    timestamp: new Date().toISOString(),
+    performance,
+    meta,
+    interactions: {
+      links: linkCount,
+      inputs: inputCount,
+    },
+    issues: {
+      consoleErrors: consoleErrors.slice(0, 20),
+      brokenImages: brokenImages.slice(0, 20),
+      hasBrokenImages: brokenImages.length > 0,
+      hasConsoleErrors: consoleErrors.length > 0,
+    },
+    score: calculateHealthScore(performance, consoleErrors, brokenImages),
+  };
+}
+
+function calculateHealthScore(perf, errors, brokenImgs) {
+  let score = 100;
+
+  // Penalize slow loads
+  if (perf.loadTime > 5000) score -= 20;
+  else if (perf.loadTime > 2000) score -= 10;
+
+  // Penalize errors
+  score -= errors.length * 5;
+  score -= brokenImgs.length * 10;
+
+  return Math.max(0, Math.min(100, score));
+}

package/lib/fingerprint.mjs

@@ -0,0 +1,100 @@
+/**
+ * bwb-browser — Realistic Browser Fingerprint
+ *
+ * Applies standard browser fingerprint countermeasures to reduce
+ * false-positive automation detection in CI/testing environments.
+ *
+ * These techniques are the same ones used by Playwright's Stealth plugin
+ * and Puppeteer Extra — common tools for testing your own site's
+ * bot-detection systems in a realistic browser environment.
+ *
+ * How it works:
+ *   - Override navigator.webdriver → false
+ *   - Set realistic navigator.plugins
+ *   - Configure sensible language preferences
+ *   - Override chrome.runtime references
+ *   - Set a standard desktop User-Agent
+ *
+ * NOTE: Scripts are injected via Page.addScriptToEvaluateOnNewDocument,
+ * which means they only affect pages loaded AFTER applyRealisticProfile
+ * is called. Call before browser_goto for best results.
+ */
+
+/**
+ * Apply a realistic browser fingerprint to reduce automation detection.
+ * Injects anti-fingerprinting scripts before page JS executes.
+ */
+export async function applyRealisticProfile(protocol) {
+  const { Page, Network } = protocol;
+
+  // Inject fingerprint-normalizing script for ALL new documents
+  await Page.addScriptToEvaluateOnNewDocument({
+    source: `
+      // Normalize webdriver flag (standard automation test practice)
+      Object.defineProperty(navigator, 'webdriver', { get: () => false });
+
+      // Set realistic plugin list
+      Object.defineProperty(navigator, 'plugins', {
+        get: () => [
+          { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer' },
+          { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai' },
+          { name: 'Native Client', filename: 'internal-nacl-plugin' },
+        ],
+        configurable: true,
+      });
+
+      // Realistic language preferences
+      Object.defineProperty(navigator, 'languages', {
+        get: () => ['en-US', 'en', 'es'],
+        configurable: true,
+      });
+
+      // Remove automation-specific chrome.runtime
+      if (window.chrome) {
+        if (window.chrome.runtime) {
+          delete window.chrome.runtime;
+        }
+        if (!window.chrome.loadTimes) {
+          window.chrome.loadTimes = function() { return {}; };
+        }
+      }
+
+      // Normalize permissions query
+      if (navigator.permissions && navigator.permissions.query) {
+        const origQuery = navigator.permissions.query;
+        navigator.permissions.query = function(params) {
+          if (params && params.name === 'notifications') {
+            return Promise.resolve({ state: 'prompt', onchange: null });
+          }
+          return origQuery.call(this, params);
+        };
+      }
+
+      // Realistic connection type
+      if (navigator.connection) {
+        Object.defineProperty(navigator.connection, 'rtt', { get: () => 100 });
+      }
+    `,
+  });
+
+  // Set a standard desktop user-agent
+  try {
+    await Network.setUserAgentOverride({
+      userAgent:
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+    });
+  } catch {}
+
+  return {
+    status: "profile applied",
+    note: "Only affects pages loaded after this call. Navigate to a new page for the profile to take effect.",
+    techniques: [
+      "navigator.webdriver → false",
+      "navigator.plugins — realistic list",
+      "navigator.languages — configured",
+      "chrome.runtime — normalized",
+      "Permissions query — overridden",
+      "User-Agent — standard desktop",
+    ],
+  };
+}

package/lib/helpers.mjs

@@ -0,0 +1,126 @@
+/**
+ * bwb-browser — Shared interaction helpers
+ *
+ * Functions for navigating, clicking, filling, and waiting for page elements
+ * using raw CDP protocol.
+ */
+
+// ─── Navigation Helper ────────────────────────────────────────────────────────
+
+export async function gotoUrl(page, runtime, url, timeoutMs) {
+  await page.enable();
+
+  const loadPromise = page.loadEventFired().then(() => true);
+  const domPromise = page.domContentEventFired().then(() => true);
+
+  await page.navigate({ url });
+
+  await Promise.race([
+    Promise.all([loadPromise, domPromise]),
+    new Promise(r => setTimeout(() => r(false), timeoutMs)),
+  ]);
+
+  // Small grace for JS framework rendering
+  await new Promise(r => setTimeout(r, 500));
+
+  const { result } = await runtime.evaluate({ expression: "document.title" });
+  return { title: result?.value || "", url };
+}
+
+// ─── Click Helper (uses CDP Input.dispatchMouseEvent) ─────────────────────────
+
+export async function clickElement(page, runtime, input, selector) {
+  const { result } = await runtime.evaluate({
+    expression: `(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return JSON.stringify({ error: 'NOT_FOUND' });
+      const rect = el.getBoundingClientRect();
+      return JSON.stringify({
+        x: rect.x + rect.width / 2,
+        y: rect.y + rect.height / 2,
+        width: rect.width,
+        height: rect.height,
+        tag: el.tagName,
+        text: (el.textContent || '').trim().slice(0, 50),
+      });
+    })()`,
+  });
+
+  let info;
+  try { info = JSON.parse(result.value); } catch {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  if (info.error === "NOT_FOUND") {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  // Dispatch real mouse events via CDP Input domain (ONLY — no native JS click)
+  const x = Math.round(info.x);
+  const y = Math.round(info.y);
+  await input.dispatchMouseEvent({ type: "mousePressed", x, y, button: "left", clickCount: 1 });
+  await input.dispatchMouseEvent({ type: "mouseReleased", x, y, button: "left", clickCount: 1 });
+
+  return info;
+}
+
+// ─── Fill Helper (uses CDP Input.insertText) ──────────────────────────────────
+
+export async function fillElement(page, runtime, input, selector, text) {
+  const { result } = await runtime.evaluate({
+    expression: `(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return 'NOT_FOUND';
+      el.focus();
+      el.value = '';
+      return 'FOCUSED';
+    })()`,
+    returnByValue: true,
+  });
+
+  if (result.value === "NOT_FOUND") {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  // Clear existing text via CDP Input domain
+  await input.dispatchKeyEvent({ type: "keyDown", key: "Control" });
+  await input.dispatchKeyEvent({ type: "keyDown", key: "a" });
+  await input.dispatchKeyEvent({ type: "keyUp", key: "a" });
+  await input.dispatchKeyEvent({ type: "keyUp", key: "Control" });
+  await input.dispatchKeyEvent({ type: "keyDown", key: "Delete" });
+  await input.dispatchKeyEvent({ type: "keyUp", key: "Delete" });
+
+  // Insert text via CDP Input domain
+  await input.insertText({ text });
+}
+
+// ─── waitForSelector Helper ──────────────────────────────────────────────────
+
+export async function waitForSelector(runtime, selector, opts = {}) {
+  const timeout = opts.timeout || 10000;
+  const disappear = opts.disappear || false;
+  const start = Date.now();
+
+  while (Date.now() - start < timeout) {
+    const { result } = await runtime.evaluate({
+      expression: `(() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return JSON.stringify({ status: "NOT_FOUND" });
+        const rect = el.getBoundingClientRect();
+        const hidden = rect.width === 0 || rect.height === 0;
+        const text = (el.textContent || "").trim().slice(0, 200);
+        return JSON.stringify({ status: "FOUND", tag: el.tagName, text, hidden });
+      })()`,
+    });
+
+    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;
+
+    await new Promise((r) => setTimeout(r, 200));
+  }
+
+  throw new Error(`browser_waitForSelector: "${selector}" not ${disappear ? "disappeared" : "found"} within ${timeout}ms`);
+}

package/lib/session.mjs

@@ -0,0 +1,88 @@
+/**
+ * bwb-browser — Persistent Browser Sessions
+ *
+ * Save and load browser cookies to/from disk, enabling authenticated sessions
+ * to persist across agent restarts. "Login once, agent works for days."
+ *
+ * Sessions are stored as JSON files in ~/.bwb/sessions/
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const SESSION_DIR = join(homedir(), ".bwb", "sessions");
+
+function ensureDir() {
+  mkdirSync(SESSION_DIR, { recursive: true });
+}
+
+/**
+ * Save all cookies from the current browser session to a named session file.
+ */
+export async function saveSession(name, protocol) {
+  if (!name || typeof name !== "string") {
+    throw new Error("Session name is required");
+  }
+  // Sanitize name to avoid path traversal
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+  ensureDir();
+
+  const { cookies } = await protocol.Network.getAllCookies();
+  const path = join(SESSION_DIR, `${safeName}.json`);
+  writeFileSync(path, JSON.stringify({
+    name: safeName,
+    cookieCount: cookies.length,
+    savedAt: Date.now(),
+    cookies,
+  }, null, 2));
+
+  return { savedTo: path, cookieCount: cookies.length, name: safeName };
+}
+
+/**
+ * Load cookies from a named session file into the browser.
+ */
+export async function loadSession(name, protocol) {
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const path = join(SESSION_DIR, `${safeName}.json`);
+
+  if (!existsSync(path)) {
+    throw new Error(`Session not found: "${name}". Available sessions: ${listSessions().map(s => s.name).join(", ") || "none"}`);
+  }
+
+  const data = JSON.parse(readFileSync(path, "utf8"));
+
+  if (!data.cookies || !Array.isArray(data.cookies)) {
+    throw new Error(`Invalid session file: ${path}`);
+  }
+
+  // Set all cookies in the browser
+  await protocol.Network.setCookies({ cookies: data.cookies });
+
+  return {
+    loaded: safeName,
+    cookieCount: data.cookies.length,
+    savedAt: new Date(data.savedAt).toISOString(),
+  };
+}
+
+/**
+ * List all saved sessions.
+ */
+export function listSessions() {
+  ensureDir();
+  const files = readdirSync(SESSION_DIR).filter(f => f.endsWith(".json"));
+  return files.map(f => {
+    try {
+      const data = JSON.parse(readFileSync(join(SESSION_DIR, f), "utf8"));
+      return {
+        name: data.name || f.replace(".json", ""),
+        cookieCount: data.cookies?.length || 0,
+        savedAt: data.savedAt ? new Date(data.savedAt).toISOString() : "unknown",
+      };
+    } catch {
+      return { name: f.replace(".json", ""), cookieCount: 0, savedAt: "unknown" };
+    }
+  });
+}

package/lib/tabs.mjs

@@ -0,0 +1,165 @@
+/**
+ * bwb-browser — Multi-tab Management
+ *
+ * Manages multiple page targets (tabs) within a single Chrome browser instance.
+ * Uses CDP's target system to create, close, switch, and list tabs.
+ * Each tab gets its own CDP protocol connection.
+ */
+
+import CDP from "chrome-remote-interface";
+import { ensureBrowser, protocol, actualCdpPort, cfg } from "./browser.mjs";
+
+// ─── Tab State ───────────────────────────────────────────────────────────────
+
+/** @type {Map<string, {protocol: import('chrome-remote-interface').Protocol|null, title: string, url: string}>} */
+const tabs = new Map();
+let activeTabId = null;
+
+// ─── Ensure Default Tab Registered ──────────────────────────────────────────
+
+async function ensureDefaultTab() {
+  if (tabs.size > 0) return;
+
+  // Browser must be started first
+  await ensureBrowser();
+  if (!protocol) throw new Error("Browser not started");
+
+  const port = actualCdpPort || cfg.port;
+  const targets = await CDP.List({ port });
+  const page = targets.find(t => t.type === "page");
+  if (page) {
+    tabs.set(page.id, { protocol, title: page.title, url: page.url });
+    activeTabId = page.id;
+  }
+}
+
+// ─── getActiveProtocol ───────────────────────────────────────────────────────
+
+/**
+ * Returns the CDP protocol for the active tab.
+ * If no tabs are managed, ensures browser is started and returns default protocol.
+ * All tool handlers should use this instead of ensureBrowser() directly.
+ */
+export async function getActiveProtocol() {
+  if (tabs.size === 0) {
+    await ensureDefaultTab();
+  }
+
+  if (activeTabId && tabs.has(activeTabId)) {
+    const tab = tabs.get(activeTabId);
+    if (tab.protocol) return tab.protocol;
+  }
+
+  // Fallback to default protocol
+  return protocol;
+}
+
+// ─── Create Tab ──────────────────────────────────────────────────────────────
+
+/**
+ * Creates a new browser tab and navigates to url (or about:blank).
+ * Switches to the new tab automatically.
+ */
+export async function createTab(url) {
+  await ensureDefaultTab();
+
+  const port = actualCdpPort || cfg.port;
+  const info = await CDP.New({ port, url: url || "about:blank" });
+
+  // Create a CDP connection for this specific target
+  const newProtocol = await CDP({ target: info.id, port });
+  tabs.set(info.id, { protocol: newProtocol, title: info.title || "", url: info.url || url || "" });
+  activeTabId = info.id;
+
+  return { id: info.id, title: info.title || "", url: info.url || "" };
+}
+
+// ─── Close Tab ───────────────────────────────────────────────────────────────
+
+/**
+ * Closes a tab by targetId. If no targetId provided, closes the active tab.
+ * Cannot close the last remaining tab.
+ */
+export async function closeTab(targetId) {
+  await ensureDefaultTab();
+
+  const id = targetId || activeTabId;
+  if (!id) throw new Error("No tab to close");
+
+  if (tabs.size <= 1) {
+    throw new Error("Cannot close the only remaining tab. Use browser_restart instead.");
+  }
+
+  const port = actualCdpPort || cfg.port;
+  await CDP.Close({ id, port });
+
+  const tab = tabs.get(id);
+  if (tab && tab.protocol && tab.protocol !== protocol) {
+    try { await tab.protocol.close(); } catch {}
+  }
+  tabs.delete(id);
+
+  // Switch to another tab
+  if (activeTabId === id) {
+    activeTabId = tabs.keys().next().value;
+  }
+
+  return { closed: id, activeTab: activeTabId };
+}
+
+// ─── Switch Tab ──────────────────────────────────────────────────────────────
+
+/**
+ * Switches to a different tab by targetId.
+ */
+export function switchTab(targetId) {
+  if (!targetId) throw new Error("No targetId provided");
+  if (!tabs.has(targetId)) {
+    throw new Error(`Tab not found: ${targetId}`);
+  }
+
+  activeTabId = targetId;
+  const tab = tabs.get(targetId);
+  return { id: targetId, title: tab.title, url: tab.url };
+}
+
+// ─── List Tabs ───────────────────────────────────────────────────────────────
+
+/**
+ * Lists all open tabs with their IDs, titles, URLs, and active status.
+ */
+export function listTabs() {
+  const result = [];
+  for (const [id, tab] of tabs) {
+    result.push({
+      id,
+      title: tab.title,
+      url: tab.url,
+      active: id === activeTabId,
+    });
+  }
+  return result;
+}
+
+// ─── Clear Tabs (for restart) ───────────────────────────────────────────────
+
+/**
+ * Clears all tab state. Called during browser restart to prevent stale connections.
+ */
+export function clearTabs() {
+  tabs.clear();
+  activeTabId = null;
+}
+
+// ─── Tab Sync (update title/url after navigation) ───────────────────────────
+
+/**
+ * Call after navigation to keep tab metadata current.
+ */
+export function syncActiveTab(title, url) {
+  if (activeTabId && tabs.has(activeTabId)) {
+    const tab = tabs.get(activeTabId);
+    if (title) tab.title = title;
+    if (url) tab.url = url;
+  }
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "bwb-browser",
-  "version": "2.0.3",
-  "description": "Browser Without Bloat — 30KB MCP browser automation server. Raw CDP, zero bloat, works on any platform.",
+  "version": "3.0.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"
   },
   "files": [
     "server.mjs",
+    "lib/",
     "bin/bwb",
     "AGENTS.md",
     "LICENSE",
@@ -14,7 +15,7 @@
   ],
   "scripts": {
     "start": "node server.mjs",
-    "test": "node --check server.mjs"
+    "test": "node --check server.mjs && node --check lib/*.mjs"
   },
   "keywords": [
     "mcp",
@@ -26,7 +27,24 @@
     "headless",
     "bwb",
     "browser-without-bloat",
-    "ai-agent"
+    "ai-agent",
+    "termux",
+    "android",
+    "natural-language",
+    "llm",
+    "ai-tools",
+    "claude",
+    "opencode",
+    "agent",
+    "web-scraping",
+    "browser-testing",
+    "e2e-testing",
+    "fingerprint",
+    "session",
+    "lightweight",
+    "zero-dependencies",
+    "mobile",
+    "devtools"
   ],
   "author": "Krish Tiwari (@krshforever)",
   "license": "MIT",