bwb-browser 3.1.1 → 4.0.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) · ~136KB source · 26 tools · static-first (v4)
+> **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. ~136KB source. 26 tools. Static-first: plain pages never spawn Chromium. Zero native 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 lightweight 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:
+bwb is Browser Without Bloat. Static-first: plain pages are fetched + extracted with zero Chromium; JS pages escalate automatically. It uses raw Chrome DevTools Protocol (no Playwright, no Puppeteer) only when rendering is actually needed.
+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
@@ -116,20 +116,22 @@ Created by Krish Tiwari (@krshforever) from a phone on a train in India. npm: bw
 
 5. Verify the config is valid JSON and the file has proper syntax.
 
-6. Test the integration by calling `browser_status` tool — it should return `connected: true` 
-   (it starts Chromium automatically on first call).
+6. Test the integration by calling `browser_status` tool — it should return `connected: true`
+   (static-first: plain pages never start Chromium; JS pages start it on first CDP call).
 
 ## Skill: I Know How to Use bwb
 
 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_goto({url: "https://example.com"})` — navigate (static-first: `mode: "static"` needs no browser; `mode: "browser"` escalated to CDP)
 - `browser_text()` — get page text content
+- `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_html()` — get page HTML
 - `browser_elements({kind: "links"|"buttons"|"inputs"|"headings"})` — find interactive elements
+- `browser_status()` — page title/URL live in `targets`, plus resource readings and active profile
+
+Every tool response ends with a `[bwb resources]` footer (MCP + Chromium MB, tabs, ok/watch/critical). On critical, bwb sheds load itself and says so — read the footer before spawning more work.
 
 ### Interaction
 - `browser_fill({selector: "#search", text: "query"})` — fill input fields
@@ -167,14 +169,14 @@ 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) |
 | `browser_fill` | Fill an input field (native CDP keyboard events) |
 | `browser_elements` | List interactive elements by kind |
-| `browser_title` | Get page title |
-| `browser_url` | Get current URL |
+| `browser_download` | Download media (needs system yt-dlp, consent-gated) |
+| `browser_export` | Export md/txt/html (pdf/docx/pptx need pip libs, consent-gated) |
 | `browser_back` | Go back in history |
 | `browser_eval` | Execute JavaScript (with exception capture) |
 | `browser_setViewport` | Change viewport size |

package/README.md

@@ -1,8 +1,21 @@
 # bwb-browser
 
-**Browser Without Bloat** — 76KB. 25 tools. Zero dependencies. Runs on your phone.
+**Browser Without Bloat** — 136KB source. 26 tools. Static-first. Runs on your phone, survives it too.
 
-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."
+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" — then rewritten when Android kept killing those tools mid-run.
+
+---
+
+## v4: The Browser Starts Only When It Must
+
+v1–v3 made the server light but spawned Chromium for everything — including reading a README. Android's out-of-memory killer ate whole Termux sessions for that. v4 inverts the default:
+
+- **Static-first fetch ladder** — plain pages are fetched + extracted with zero Chromium. `browser_goto` returns `mode: "static"` in milliseconds. JS pages escalate to CDP automatically (`mode: "browser"` + reason). Dead URLs error without spawning anything.
+- **Vigilance system** — every tool response carries a `[bwb resources]` footer. On critical pressure bwb hibernates tabs itself, tears down at one tab, journals everything, and tells the agent what it did.
+- **Survival profile** — `--lean` auto-enables on Termux (capped renderers, 3-tab cap, 5-minute mayfly teardown, 256MB JS heap). Runs on a 1GB VPS. Your tabs resurrect from the journal after any kill.
+- **On-demand capabilities** — `browser_download` / `browser_export` ship as verbs, not weight. Missing backends (yt-dlp, reportlab) prompt for consent install. Nothing heavy is ever bundled.
+
+Measured on-device: a single YouTube tab costs **746MB** of Chromium tree. That's why the ladder exists.
 
 ---
 
@@ -12,17 +25,20 @@ Every other MCP browser tool ships a full browser binary. Playwright MCP? ~250MB
 
 bwb uses **raw Chrome DevTools Protocol (CDP)** — the same protocol Chrome speaks natively. It auto-detects the browser already on your system. No downloads. No binary mismatches. No "why is my disk full" panic.
 
-| Factor | bwb | Playwright MCP | Puppeteer MCP |
+| Factor | bwb v4 | Playwright MCP | Puppeteer MCP |
 |--------|-----|----------------|---------------|
-| Source size | **76KB** | ~50MB+ | ~100MB+ |
-| Total install | **~1MB** | ~250MB | ~400MB |
+| Source size | **~136KB** | ~50MB+ | ~100MB+ |
+| Published tarball | **38.8 kB** | — | — |
+| Total install (npm) | **~62MB, zero browsers** | ~250MB | ~400MB |
 | Bundled browser | **None** | Chromium (~200MB) | Chromium (~300MB) |
+| Chromium spawns for plain pages | **Never (static-first)** | Always | Always |
 | Works on Termux/Android | **✅ Yes** | ❌ | ❌ |
-| Zero deps (no node_modules hell) | **✅ Yes** | ❌ | ❌ |
+| Survives 1GB RAM / phone OOM | **✅ Lean profile + vigilance** | ❌ | ❌ |
+| Zero native deps | **✅ Yes** | ❌ | ❌ |
 | Live event streaming | **✅** | ❌ | ❌ |
 | Natural language interaction | **✅** | ❌ | ❌ |
 | Persistent sessions | **✅** | ❌ | ❌ |
-| CPU profile at idle | Basically nothing | 🐌 | 🐌 |
+| CPU profile at idle | Mayfly teardown (Termux) | 🐌 | 🐌 |
 
 ---
 
@@ -74,6 +90,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 +127,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 +143,7 @@ bwb
 
 ---
 
-## All 25 Tools
+## All 26 Tools
 
 | Tool | Description |
 |------|-------------|
@@ -106,7 +152,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

@@ -31,8 +31,48 @@ export const cfg = {
   screenshotsDir: "",
   navTimeout: 30000,
   browserPath: null,
+  lean: null, // null = auto (Termux/1GB heuristics); true/false forces
+  nuclear: false, // --single-process: max RAM saving, min stability. Opt-in only.
+  idleMs: null, // null = auto (5min lean, off desktop); 0 = never teardown
+  tabMax: null, // null = auto (3 lean, unlimited desktop); 0 = unlimited
 };
 
+// ─── Environment ─────────────────────────────────────────────────────────────
+
+export function isTermux() {
+  return Boolean(
+    process.env.TERMUX_VERSION ||
+    process.env.PREFIX?.includes("com.termux") ||
+    process.env.HOME?.includes("com.termux")
+  );
+}
+
+// ─── Idle Mayfly (auto-teardown) ─────────────────────────────────────────────
+
+let idleTimer = null;
+let idleSuppressed = false; // true while browser_watch is recording
+
+export function setIdleSuppressed(suppressed) {
+  idleSuppressed = suppressed;
+  if (suppressed) disarmIdle();
+  else pokeActivity();
+}
+
+export function disarmIdle() {
+  if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+}
+
+/** Reset the mayfly timer. Called after every tool call via the server wrapper. */
+export function pokeActivity() {
+  disarmIdle();
+  if (!cfg.idleMs || idleSuppressed || !browser || browserExited) return;
+  idleTimer = setTimeout(() => {
+    idleTimer = null;
+    if (!idleSuppressed) stopBrowser("idle-timeout").catch(() => {});
+  }, cfg.idleMs);
+  if (idleTimer.unref) idleTimer.unref(); // never hold the MCP process open
+}
+
 // ─── Kill Orphaned Chrome (Termux-safe) ────────────────────────────────────────
 
 // `fuser -k` and `lsof` can't read /proc/net/tcp on Termux/Android (permission denied).
@@ -41,8 +81,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 {}
@@ -145,6 +195,7 @@ export async function ensureBrowser() {
         "--disable-software-rasterizer",
         "--remote-debugging-port=" + debugPort,
         "--user-data-dir=" + cfg.userDataDir,
+        ...leanArgs(),
       ];
 
       if (!cfg.headless) args.shift();
@@ -189,7 +240,13 @@ export async function ensureBrowser() {
           CDP({ port: actualCdpPort })
             .then((cdp) => {
               protocol = cdp;
-              startResolve(cdp);
+              // Awaited, not fire-and-forget: callers must see the restored
+              // working set, not a blank tab that later jumps. Capped + fast.
+              (async () => {
+                try { await restoreJournalTabs(); } catch {}
+                startResolve(cdp);
+                pokeActivity();
+              })();
             })
             .catch((err) => {
               try { browser.kill("SIGKILL"); } catch {}
@@ -208,6 +265,56 @@ export async function ensureBrowser() {
   return browserStartup;
 }
 
+// ─── Lean Flags (v4 survival profile) ─────────────────────────────────────────
+// Compat flags above make Chromium RUN on Termux. These make it SURVIVE:
+// capped renderers, silenced background services, bounded cache + JS heap.
+// --single-process stays behind --nuclear: biggest saving, weakest stability.
+
+function leanArgs() {
+  if (!cfg.lean) return [];
+  const flags = [
+    "--renderer-process-limit=1",
+    "--disable-background-networking",
+    "--disable-component-update",
+    "--disable-sync",
+    "--mute-audio",
+    "--disable-features=Translate",
+    "--disk-cache-size=67108864",
+    "--js-flags=--max-old-space-size=256",
+  ];
+  if (cfg.nuclear) flags.push("--single-process", "--no-zygote");
+  return flags;
+}
+
+// ─── Stop (graceful mayfly teardown — journal keeps the working set) ─────────
+
+export async function stopBrowser(reason = "manual") {
+  if (cleaningUp) return { status: "busy" };
+  cleaningUp = true;
+  disarmIdle();
+  try {
+    if (protocol) {
+      try { await protocol.close(); } catch {}
+      protocol = null;
+    }
+    if (browser) {
+      try { browser.kill("SIGTERM"); } catch {}
+      await new Promise(r => setTimeout(r, 1500));
+      try { browser.kill("SIGKILL"); } catch {}
+      browser = null;
+    }
+  } catch {}
+  browserExited = true; // next ensureBrowser() respawns fresh + restores journal
+  actualCdpPort = null;
+  browserStartup = null;
+  cleaningUp = false;
+  try {
+    const { clearTabs } = await import("./tabs.mjs");
+    clearTabs();
+  } catch {}
+  return { status: "stopped", reason };
+}
+
 // ─── Restart ──────────────────────────────────────────────────────────────────
 
 export async function restartBrowser() {
@@ -236,6 +343,18 @@ export async function restartBrowser() {
   return { status: "restarted" };
 }
 
+// ─── Journal Restore (post-kill resurrection — lazy, capped) ─────────────────
+// Reopens the journaled working set after a fresh spawn (LMK kill, mayfly
+// teardown, restart). First entry navigates now; the rest become placeholders
+// woken on switchTab. Never re-spikes memory at startup to "restore".
+
+async function restoreJournalTabs() {
+  try {
+    const tabs = await import("./tabs.mjs");
+    await tabs.restoreJournal();
+  } catch {}
+}
+
 // ─── Screenshot Helper ────────────────────────────────────────────────────────
 
 export function saveScreenshot(base64Data) {

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/fetch.mjs

@@ -0,0 +1,127 @@
+/**
+ * bwb-browser — Static-first fetch (v4 fetch ladder, rung 1)
+ *
+ * Plain HTTP + Readability extraction. Zero Chromium, zero new persistent RAM:
+ * heavy deps are lazy-imported inside the function, so the MCP process pays
+ * nothing until the first static fetch. Called by browser_goto before CDP.
+ */
+
+const FETCH_MAX_BYTES = 2_000_000; // never buffer more than 2MB per page
+const MIN_TEXT_CHARS = 500; // below this + JS markers => probably a JS shell
+
+// Framework shells / client-rendered markers — presence + thin text = escalate
+const JS_MARKERS = [
+  'id="root"', "id='root'", 'id="app"', "id='app'",
+  "__NEXT_DATA__", "ng-app", "ng-version", "data-reactroot",
+  "__NUXT__", "ember-view", "data-svelte", "_astro",
+];
+// Login / auth walls — static fetch can't pass, but the browser (sessions) might
+const AUTH_MARKERS = ["password", "sign in", "log in", "login", "captcha"];
+
+const TEXT_TYPES = ["text/html", "text/plain", "application/xhtml+xml"];
+
+/**
+ * Fetch + extract without Chromium.
+ * @returns {mode:'static',...} | {mode:'escalate', reason} | {mode:'error', error}
+ */
+export async function staticFetch(url, { timeout = 15000 } = {}) {
+  let res;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeout);
+    try {
+      res = await fetch(url, {
+        signal: ctrl.signal,
+        redirect: "follow",
+        headers: {
+          "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 bwb-static/4.0",
+          Accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.1",
+        },
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    // Network-level failure — CDP shares the same network, but surfaces
+    // better diagnostics (diagnosePage). Escalate rather than hard-fail.
+    return { mode: "escalate", reason: `static fetch failed (${err.name}): ${err.message}` };
+  }
+
+  // Auth walls: the browser (with sessions/cookies) may pass where fetch can't
+  if (res.status === 401 || res.status === 403 || res.status === 429) {
+    return { mode: "escalate", reason: `HTTP ${res.status} — possible auth wall / rate limit` };
+  }
+  if (!res.ok) {
+    // Dead URL — CDP won't resurrect it. Don't spawn Chromium for a 404.
+    return { mode: "error", error: `HTTP ${res.status} ${res.statusText} for ${url}` };
+  }
+
+  const contentType = (res.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+  if (contentType && !TEXT_TYPES.some((t) => contentType.startsWith(t))) {
+    return { mode: "escalate", reason: `non-text content (${contentType || "unknown"})` };
+  }
+
+  // Bounded body read — never buffer a whole ISO / stream
+  let html = "";
+  try {
+    const reader = res.body.getReader();
+    let received = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.length;
+      if (received > FETCH_MAX_BYTES) {
+        try { await reader.cancel(); } catch {}
+        return { mode: "escalate", reason: "page exceeds 2MB static cap — needs browser" };
+      }
+      html += Buffer.from(value).toString("utf8");
+    }
+  } catch (err) {
+    return { mode: "escalate", reason: `body read failed: ${err.message}` };
+  }
+
+  if (contentType.startsWith("text/plain")) {
+    const text = html.trim();
+    if (text.length < MIN_TEXT_CHARS) {
+      return { mode: "escalate", reason: "plain-text body too thin to trust" };
+    }
+    return { mode: "static", title: "", text, finalUrl: res.url, bytes: html.length, confidence: "high" };
+  }
+
+  // HTML → Readability (lazy deps: zero cost until first use)
+  let article;
+  try {
+    const { parseHTML } = await import("linkedom");
+    const { Readability } = await import("@mozilla/readability");
+    const { document } = parseHTML(html);
+    article = new Readability(document).parse();
+  } catch (err) {
+    return { mode: "escalate", reason: `extraction crashed: ${err.message}` };
+  }
+  if (!article || !(article.textContent || "").trim()) {
+    return { mode: "escalate", reason: "no readable article found" };
+  }
+
+  const text = article.textContent.trim().replace(/\n{3,}/g, "\n\n");
+  const lower = html.toLowerCase();
+  const hasJsShell = JS_MARKERS.some((m) => lower.includes(m.toLowerCase()));
+  const looksAuthed = AUTH_MARKERS.some((m) => lower.includes(m)) && text.length < MIN_TEXT_CHARS;
+
+  if (text.length < MIN_TEXT_CHARS && (hasJsShell || looksAuthed)) {
+    return {
+      mode: "escalate",
+      reason: looksAuthed && !hasJsShell
+        ? "thin text behind possible login wall"
+        : "thin text + JS shell markers — needs rendering",
+    };
+  }
+
+  return {
+    mode: "static",
+    title: article.title || "",
+    text,
+    finalUrl: res.url,
+    bytes: html.length,
+    confidence: text.length >= MIN_TEXT_CHARS ? "high" : "medium",
+  };
+}

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/lib/setup.mjs

@@ -305,9 +305,32 @@ export function runSetup() {
   }
 
   console.log('  🚀 Ready to go! Try: browser_status\n');
+  printSurvivalGuide();
   return { configured: configured.length, alreadyDone: alreadyDone.length, errors: errors.length };
 }
 
+// ─── Survival Guide (v4: OOM is the enemy, not setup) ───────────────────────
+// WakeLock + battery exemption don't stop LMK — footprint does. One-time notes.
+
+function printSurvivalGuide() {
+  const termux = Boolean(process.env.TERMUX_VERSION
+    || process.env.PREFIX?.includes('com.termux')
+    || process.env.HOME?.includes('com.termux'));
+  console.log('  ─── Survival guide (read once) ───────────────────────');
+  console.log('  v4 is static-first: plain pages never spawn Chromium.');
+  console.log('  Lean profile auto-enables on Termux (cap 3 tabs, 5-min mayfly).');
+  console.log('  Every tool response carries a [bwb resources] footer —');
+  console.log('  when it reads critical, bwb sheds tabs itself and says so.');
+  if (termux) {
+    console.log('  Termux overnight runs:');
+    console.log('    • termux-wake-lock (keeps CPU awake, does NOT stop LMK)');
+    console.log('    • Exempt Termux from battery optimization (Android Settings)');
+    console.log('    • The rest is footprint: fewer tabs, static-first,');
+    console.log('      journal restores your working set if Android still kills.');
+  }
+  console.log();
+}
+
 function getVersion() {
   try {
     const pkg = path.resolve(__dirname, '..', 'package.json');