barebrowse 0.1.0 → 0.2.1

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## 0.2.1
+
+- README rewritten: no code blocks, full obstacle course table with mode column, two usage paths (MCP vs framework), mcprune credited, measured token savings, context.md as code reference
+- MCP auto-installer: `npx barebrowse install` detects Claude Desktop, Cursor, Claude Code and writes config
+- MCP config uses `npx barebrowse mcp` instead of local file paths (works for npm consumers)
+- CLI help updated with install command
+
+## 0.2.0
+
+Agent integration release. MCP server, bareagent adapter, and interaction features that make barebrowse usable as a standalone tool or embedded browsing layer.
+
+### New: MCP server
+- Raw JSON-RPC 2.0 over stdio, zero SDK dependencies
+- 7 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`
+- Singleton session page, lazy-created on first session tool call
+- `npx barebrowse mcp` to start, `npx barebrowse install` to auto-configure
+
+### New: MCP auto-installer
+- `npx barebrowse install` detects Claude Desktop, Cursor, and Claude Code
+- Writes MCP config automatically -- no manual JSON editing
+- Reports status for each detected client
+
+### New: bareagent tool adapter
+- `import { createBrowseTools } from 'barebrowse/bareagent'`
+- Returns `{ tools, close }` with 9 bareagent-compatible tools
+- Action tools auto-return fresh snapshot after each action (300ms settle)
+- Tools: browse, goto, snapshot, click, type, press, scroll, select, screenshot
+
+### New: stealth patches
+- `src/stealth.js` -- anti-detection for headless mode
+- Uses `Page.addScriptToEvaluateOnNewDocument` (runs before page scripts)
+- Patches: `navigator.webdriver`, `navigator.plugins`, `navigator.languages`, `window.chrome`, `Permissions.prototype.query`
+- Auto-applied in headless mode
+
+### New: interactions
+- `page.hover(ref)` -- mouse move to element center, triggers hover styles/tooltips
+- `page.select(ref, value)` -- native `<select>` (set value + change event) or custom dropdown (click + find option)
+- `page.screenshot(opts)` -- `Page.captureScreenshot`, returns base64 (png/jpeg/webp)
+
+### New: wait strategies
+- `page.waitForNetworkIdle(opts)` -- resolve when no pending requests for N ms (default 500)
+- `page.waitForNavigation()` now SPA-aware -- falls back gracefully when no `loadEventFired` fires
+
+### New: hybrid mode
+- `mode: 'hybrid'` in `browse()` -- tries headless, detects challenge pages (Cloudflare, etc.), falls back to headed
+- Challenge detection via ARIA tree heuristic ("Just a moment", "Checking your browser", etc.)
+
+### New: CLI
+- `npx barebrowse mcp` -- start MCP server
+- `npx barebrowse install` -- auto-configure MCP clients
+- `npx barebrowse browse <url>` -- one-shot browse, print snapshot to stdout
+
+### New: documentation
+- `README.md` -- complete guide: idea, token savings, modes, library vs MCP, bareagent wiring
+- `barebrowse.context.md` -- LLM-consumable integration guide for AI assistants
+- `docs/testing.md` -- test pyramid, all 54 tests documented, CI guidance
+- `docs/blueprint.md` -- updated with full 10-step pipeline, module table, integration sections
+
+### Changed
+- `package.json` -- subpath exports (`./bareagent`), `bin` entry, keywords
+- `src/index.js` -- stealth auto-applied in headless via `createPage()`, `type()` param renamed to avoid shadowing
+- `src/interact.js` -- `getCenter()` reused by new `hover()` function
+
+### Tests
+- 54 tests passing (was 47 in 0.1.0)
+- All existing tests unchanged and passing
+
+---
+
+## 0.1.0
+
+Initial release. CDP-direct browsing with ARIA snapshots.
+
+### Core
+- `browse(url, opts)` -- one-shot: URL in, pruned ARIA snapshot out
+- `connect(opts)` -- session: navigate, interact, observe across pages
+- Three modes: headless (default), headed (connect to running browser)
+- Zero required dependencies, vanilla JS, ES modules, Node >= 22
+
+### Modules
+- `src/cdp.js` -- WebSocket CDP client with flattened session support
+- `src/chromium.js` -- find/launch any installed Chromium browser
+- `src/aria.js` -- format ARIA tree as YAML-like text
+- `src/auth.js` -- cookie extraction from Firefox (SQLite) and Chromium (AES + keyring)
+- `src/prune.js` -- 9-step ARIA pruning pipeline (47-95% token reduction)
+- `src/interact.js` -- click, type (with clear), press (14 special keys), scroll
+- `src/consent.js` -- auto-dismiss cookie consent dialogs (7 languages, 16+ sites tested)
+
+### Features
+- Cookie injection from Firefox/Chromium into headless CDP sessions
+- Permission suppression (notifications, geolocation, camera, mic) via launch flags + CDP
+- Cookie consent auto-dismiss across EN, NL, DE, FR, ES, IT, PT
+- `waitForNavigation()` for post-click page loads
+- Unique temp dirs per headless instance to avoid profile locking
+
+### Tests
+- 47 tests across 5 files (unit: prune, auth, cdp; integration: browse, interact)
+- Real-site testing: Google, Wikipedia, GitHub, DuckDuckGo, YouTube, HN, Reddit

package/CLAUDE.md

@@ -0,0 +1,22 @@
+## Dev Rules
+
+**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC.
+
+**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
+
+**Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
+
+**Lightweight over complex.** Fewer moving parts, fewer deps, less config. Simple > clever. Readable > elegant.
+
+**Open-source only.** No vendor lock-in. Every line of code must have a purpose — no speculative code, no premature abstractions.
+
+## Project Specifics
+
+- **Language:** Vanilla JavaScript, ES modules, no build step
+- **Runtime:** Node.js >= 22 (built-in WebSocket, sqlite)
+- **Protocol:** CDP (Chrome DevTools Protocol) direct — no Playwright
+- **Browser:** Any installed Chromium-based browser (chromium, chrome, brave, edge)
+- **Key files:** `src/index.js` (API), `src/cdp.js` (CDP client), `src/chromium.js` (browser launch), `src/aria.js` (ARIA formatting)
+- **Docs:** `docs/prd.md` (decisions + rationale), `docs/poc-plan.md` (phases + DoD)
+
+For full development and testing standards, see `.claude/memory/AGENT_RULES.md`.

package/README.md

@@ -1,69 +1,149 @@
-# barebrowse
+```
+  ~~~~~~~~~~~~~~~~~~~~
+  ~~~ .---------. ~~~
+  ~~~ | · clear | ~~~
+  ~~~ | · focus | ~~~
+  ~~~ '---------' ~~~
+  ~~~~~~~~~~~~~~~~~~~~
+
+  barebrowse
+```
+
+> Your agent browses like you do -- same browser, same logins, same cookies.
+> Prunes pages down to what matters. 40-90% fewer tokens, zero wasted context.
+
+---
 
-Vanilla JS library. CDP-direct. URL in, pruned ARIA snapshot out.
-No Playwright, no bundled browser, no build step.
+## What this is
 
-## What It Does
+barebrowse is agentic browsing stripped to the bone. It gives your AI agent eyes and hands on the web -- navigate any page, see what's there, click buttons, fill forms, scroll, and move on. It uses your installed Chromium browser (Chrome, Brave, Edge -- whatever you have), reuses your existing login sessions, and handles all the friction automatically: cookie consent walls, permission prompts, bot detection, GDPR dialogs.
 
-Gives autonomous agents authenticated access to the web through the user's own Chromium browser.
+Instead of dumping raw DOM or taking screenshots, barebrowse returns a **pruned ARIA snapshot** -- a compact semantic view of what's on the page and what the agent can interact with. Buttons, links, inputs, headings -- labeled with `[ref=N]` markers the agent uses to act. The pruning pipeline is ported from [mcprune](https://github.com/nickvdyck/mcprune) and cuts 40-90% of tokens compared to raw page output. Every token your agent reads is meaningful.
 
-```js
-import { browse, connect } from 'barebrowse';
+No Playwright. No bundled browser. No 200MB download. No broken dependencies. Zero deps. Just CDP over a WebSocket to whatever Chromium you already have.
 
-// One-shot: read a page
-const snapshot = await browse('https://any-page.com');
+## Install
 
-// Session: navigate, interact, observe
-const page = await connect();
-await page.goto('https://any-page.com');
-console.log(await page.snapshot());
-await page.click('8');      // ref from snapshot
-await page.type('3', 'hello');
-await page.scroll(500);
-await page.close();
+```
+npm install barebrowse
 ```
 
-## Features
+Requires Node.js >= 22 and any installed Chromium-based browser.
 
-- **CDP direct** — no Playwright, no 200MB download, uses your installed Chromium
-- **ARIA snapshots** — semantic, token-efficient output for LLMs
-- **Built-in pruning** — 47-95% token reduction via 9-step pipeline
-- **Cookie extraction** — authenticated browsing from your existing sessions (Chromium + Firefox)
-- **Interactions** — click, type, scroll via CDP Input domain
-- **Three modes** — headless (default), headed (connect to running browser), hybrid (planned)
+## Two ways to use it
 
-## Architecture
+### 1. MCP server -- for Claude Desktop, Cursor, Claude Code
 
 ```
-URL → chromium.js (find/launch browser)
-    → cdp.js (WebSocket CDP client)
-    → auth.js (extract cookies → inject via CDP)
-    → Page.navigate
-    → aria.js (Accessibility.getFullAXTree → nested tree)
-    → prune.js (9-step role-based pruning)
-    → interact.js (click/type/scroll via Input domain)
-    → agent-ready snapshot
+npm install -g barebrowse
+npx barebrowse install
 ```
 
-Seven modules, ~1,400 lines, zero required dependencies.
+That's it. `install` auto-detects your MCP client and writes the config. No manual JSON editing. Restart your client and you have 7 browsing tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`.
 
-## Requirements
+### 2. Framework -- for agentic automation
+
+Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (9 tools, auto-snapshot after every action).
+
+For code examples, API reference, and wiring instructions, see **[barebrowse.context.md](barebrowse.context.md)** -- the full integration guide.
+
+## Three modes
+
+| Mode | What happens | Best for |
+|------|-------------|----------|
+| **Headless** (default) | Launches a fresh Chromium, no UI | Fast automation, scraping, reading pages |
+| **Headed** | Connects to your running browser on CDP port | Bot-detected sites, visual debugging, CAPTCHAs |
+| **Hybrid** | Tries headless first, falls back to headed if blocked | General-purpose agent browsing |
+
+## What it handles automatically
+
+This is the obstacle course your agent doesn't have to think about:
+
+| Obstacle | How it's handled | Mode |
+|----------|-----------------|------|
+| **Cookie consent walls** (GDPR) | ARIA tree scan + jsClick accept button, 7 languages (EN, NL, DE, FR, ES, IT, PT) | Both |
+| **Consent in dialog role** | Detect `dialog`/`alertdialog` with consent hints, click accept inside | Both |
+| **Consent outside dialog** (BBC SourcePoint) | Fallback global button scan when dialog has no accept button | Both |
+| **Consent behind iframe overlay** | JS click via DOM.resolveNode bypasses z-index/overlay issues | Both |
+| **Permission prompts** (location, camera, mic) | Launch flags + CDP Browser.setPermission auto-deny | Both |
+| **Media autoplay blocked** | Autoplay policy flag on launch | Both |
+| **Login walls** | Cookie extraction from Firefox/Chromium, injected via CDP | Both |
+| **Pre-filled form inputs** | Select-all + delete before typing | Both |
+| **Off-screen elements** | Scrolled into view before every click | Both |
+| **Form submission** | Enter key triggers onsubmit | Both |
+| **Tab between fields** | Tab key moves focus correctly | Both |
+| **SPA navigation** (YouTube, GitHub) | SPA-aware wait: frameNavigated + loadEventFired | Both |
+| **Bot detection** (Google, Reddit) | Stealth patches (headless) + headed fallback with real cookies | Both |
+| **navigator.webdriver leak** | Patched before page scripts run: webdriver, plugins, languages, chrome object | Headless |
+| **Profile locking** | Unique temp dir per headless instance | Headless |
+| **ARIA noise** | 9-step pruning pipeline (ported from mcprune): wrapper collapse, noise removal, landmark promotion | Both |
 
-- Node.js >= 22
-- Any installed Chromium-based browser (Chrome, Chromium, Brave, Edge, Vivaldi, Arc, Opera)
+## What the agent sees
 
-## Ecosystem
+Raw ARIA output from a page is noisy -- decorative wrappers, hidden elements, structural junk. The pruning pipeline (ported from [mcprune](https://github.com/nickvdyck/mcprune)) strips it down to what matters.
+
+| Page | Raw | Pruned | Reduction |
+|------|-----|--------|-----------|
+| example.com | 377 chars | 45 chars | 88% |
+| Hacker News | 51,726 chars | 27,197 chars | 47% |
+| Wikipedia (article) | 109,479 chars | 40,566 chars | 63% |
+| DuckDuckGo | 42,254 chars | 5,407 chars | 87% |
+
+Two pruning modes: **act** (default) keeps interactive elements and visible labels -- for clicking, typing, navigating. **read** keeps all text content -- for reading articles and extracting information.
+
+## Actions
+
+Everything the agent can do through barebrowse:
+
+| Action | What it does |
+|--------|-------------|
+| **Navigate** | Load a URL, wait for page load, auto-dismiss consent |
+| **Snapshot** | Pruned ARIA tree with `[ref=N]` markers (40-90% token reduction) |
+| **Click** | Scroll into view + mouse click at element center |
+| **Type** | Focus + insert text, with option to clear existing content first |
+| **Press** | Special keys: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
+| **Scroll** | Mouse wheel up or down |
+| **Hover** | Move mouse to element center (triggers tooltips, hover states) |
+| **Select** | Set dropdown value (native select or custom dropdown) |
+| **Screenshot** | Page capture as base64 PNG/JPEG/WebP |
+| **Wait for navigation** | SPA-aware: works for full page loads and pushState |
+| **Wait for network idle** | Resolve when no pending requests for 500ms |
+| **Inject cookies** | Extract from Firefox/Chromium and inject via CDP |
+| **Raw CDP** | Escape hatch for any Chrome DevTools Protocol command |
+
+## Tested against
+
+16+ sites across 8 countries, all consent dialogs dismissed, all interactions working:
+
+Google, YouTube, BBC, Wikipedia, GitHub, DuckDuckGo, Hacker News, Amazon DE, The Guardian, Spiegel, Le Monde, El Pais, Corriere, NOS, Bild, Nu.nl, Booking, NYT, Stack Overflow, CNN, Reddit
+
+## Context file
+
+**[barebrowse.context.md](barebrowse.context.md)** is the full integration guide. Feed it to an AI assistant or read it yourself -- it covers the complete API, snapshot format, interaction loop, auth options, bareagent wiring, MCP setup, and gotchas. Everything you need to wire barebrowse into a project.
+
+## How it works
 
 ```
-bareagent  = the brain  (orchestration, LLM loop, memory, retries)
-barebrowse = the eyes + hands  (browse, read, interact with the web)
+URL -> find/launch browser (chromium.js)
+    -> WebSocket CDP connection (cdp.js)
+    -> stealth patches before page scripts (stealth.js, headless only)
+    -> suppress all permission prompts (Browser.setPermission)
+    -> extract + inject cookies from your browser (auth.js)
+    -> navigate to URL, wait for load
+    -> detect + dismiss cookie consent dialogs (consent.js)
+    -> get full ARIA accessibility tree (aria.js)
+    -> 9-step pruning pipeline from mcprune (prune.js)
+    -> dispatch real input events: click/type/scroll (interact.js)
+    -> agent-ready snapshot with [ref=N] markers
 ```
 
-barebrowse is a library. bareagent imports it as a capability.
+11 modules, 2,400 lines, zero dependencies.
 
-## Status
+## Requirements
 
-Early development. API may change.
+- Node.js >= 22 (built-in WebSocket, built-in SQLite)
+- Any Chromium-based browser installed (Chrome, Chromium, Brave, Edge, Vivaldi)
+- Linux tested (Fedora/KDE). macOS/Windows cookie paths exist but untested.
 
 ## License
 

package/barebrowse.context.md

@@ -0,0 +1,261 @@
+# barebrowse -- Integration Guide
+
+> For AI assistants and developers wiring barebrowse into a project.
+> v0.1.0 | Node.js >= 22 | 0 required deps | MIT
+
+## What this is
+
+barebrowse is a CDP-direct browsing library for autonomous agents (~1,800 lines). URL in, pruned ARIA snapshot out. It launches the user's installed Chromium browser, navigates, handles consent/permissions/cookies, and returns a token-efficient ARIA tree with `[ref=N]` markers for interaction.
+
+No Playwright. No bundled browser. No build step. Vanilla JS, ES modules.
+
+```
+npm install barebrowse
+```
+
+Two entry points:
+- `import { browse } from 'barebrowse'` -- one-shot: URL in, snapshot out
+- `import { connect } from 'barebrowse'` -- session: navigate, interact, observe
+
+## Which mode do I need?
+
+| Mode | What it does | When to use |
+|---|---|---|
+| `headless` (default) | Launches a fresh Chromium, no UI | Scraping, reading, fast automation |
+| `headed` | Connects to user's running browser on CDP port | Bot-detected sites, debugging, visual tasks |
+| `hybrid` | Tries headless first, falls back to headed if blocked | General-purpose agent browsing |
+
+Headed mode requires the browser to be launched with `--remote-debugging-port=9222`.
+
+## Minimal usage: one-shot browse
+
+```javascript
+import { browse } from 'barebrowse';
+
+// Defaults: headless, cookies injected, pruned, consent dismissed
+const snapshot = await browse('https://example.com');
+
+// All options
+const snapshot = await browse('https://example.com', {
+  mode: 'headless',      // 'headless' | 'headed' | 'hybrid'
+  cookies: true,         // inject user's browser cookies
+  browser: 'firefox',    // cookie source: 'firefox' | 'chromium' (auto-detected)
+  prune: true,           // apply ARIA pruning (47-95% token reduction)
+  pruneMode: 'act',      // 'act' (interactive elements) | 'read' (all content)
+  consent: true,         // auto-dismiss cookie consent dialogs
+  timeout: 30000,        // navigation timeout in ms
+  port: 9222,            // CDP port for headed/hybrid mode
+});
+```
+
+## connect() API
+
+`connect(opts)` returns a page handle for interactive sessions. Same opts as `browse()` for mode/port.
+
+| Method | Args | Returns | Notes |
+|---|---|---|---|
+| `goto(url, timeout?)` | url: string, timeout: number (default 30000) | void | Navigate + wait for load + dismiss consent |
+| `snapshot(pruneOpts?)` | false or { mode: 'act'\|'read' } | string | ARIA tree with `[ref=N]` markers. Pass `false` for raw. |
+| `click(ref)` | ref: string | void | Scroll into view + mouse press+release at center |
+| `type(ref, text, opts?)` | ref: string, text: string, opts: { clear?, keyEvents? } | void | Focus + insert text. `clear: true` replaces existing. |
+| `press(key)` | key: string | void | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Home, End, PageUp, PageDown, Space |
+| `scroll(deltaY)` | deltaY: number | void | Mouse wheel. Positive = down, negative = up. |
+| `hover(ref)` | ref: string | void | Move mouse to element center |
+| `select(ref, value)` | ref: string, value: string | void | Set `<select>` value or click custom dropdown option |
+| `screenshot(opts?)` | { format?: 'png'\|'jpeg'\|'webp', quality?: number } | string (base64) | Page screenshot |
+| `waitForNavigation(timeout?)` | timeout: number (default 30000) | void | Wait for page load or frame navigation |
+| `waitForNetworkIdle(opts?)` | { timeout?: number, idle?: number } | void | Wait until no pending requests for `idle` ms (default 500) |
+| `injectCookies(url, opts?)` | url: string, { browser?: string } | void | Extract cookies from user's browser and inject via CDP |
+| `cdp` | -- | object | Raw CDP session for escape hatch: `page.cdp.send(method, params)` |
+| `close()` | -- | void | Close page, disconnect CDP, kill browser (if headless) |
+
+## Snapshot format
+
+The snapshot is a YAML-like ARIA tree. Each line is one node:
+
+```
+- WebArea "Example Domain" [ref=1]
+  - heading "Example Domain" [level=1] [ref=3]
+  - paragraph [ref=5]
+    - StaticText "This domain is for use in illustrative examples." [ref=6]
+  - link "More information..." [ref=8]
+```
+
+Key rules:
+- `[ref=N]` markers appear on interactive and named elements
+- Refs are **ephemeral** -- they change on every `snapshot()` call
+- Always call `snapshot()` to get fresh refs before interacting
+- `click(ref)` / `type(ref, text)` / `hover(ref)` / `select(ref, value)` use these ref strings
+- Pruning removes noise (~47-95% token reduction) while keeping all interactive elements
+
+## Interaction loop: observe, think, act
+
+```javascript
+import { connect } from 'barebrowse';
+
+const page = await connect();
+await page.goto('https://example.com');
+
+// 1. Observe
+let snap = await page.snapshot();
+
+// 2. Think (LLM decides what to do based on snapshot)
+// 3. Act
+await page.click('8');         // click the "More information..." link
+await page.waitForNavigation();
+
+// 4. Observe again (refs are now different)
+snap = await page.snapshot();
+
+// ... repeat until goal is achieved
+
+await page.close();
+```
+
+## Auth / cookie options
+
+barebrowse can inject cookies from the user's real browser sessions, bypassing login walls.
+
+| Source | How | Notes |
+|---|---|---|
+| Firefox (default) | SQLite `cookies.sqlite`, plaintext | Works on Linux. Auto-detected default profile. |
+| Chromium | SQLite `Cookies` + AES decryption via keyring | Linux: KWallet or GNOME Keyring. Profile must not be locked. |
+| Manual | `page.injectCookies(url, { browser: 'firefox' })` | Explicit injection on connect() sessions |
+| Disabled | `{ cookies: false }` | No cookie injection |
+
+`browse()` auto-injects cookies before navigation. `connect()` exposes `injectCookies()` for manual control.
+
+## Obstacle course -- what barebrowse handles automatically
+
+| Obstacle | How | Mode |
+|---|---|---|
+| Cookie consent (GDPR) | ARIA scan + jsClick accept button, 7 languages | Both |
+| Consent behind iframes | JS `.click()` via DOM.resolveNode bypasses overlays | Both |
+| Permission prompts | Launch flags + CDP Browser.setPermission auto-deny | Both |
+| Media autoplay blocked | `--autoplay-policy=no-user-gesture-required` | Both |
+| Login walls | Cookie extraction from Firefox/Chromium + CDP injection | Both |
+| Pre-filled form inputs | `type({ clear: true })` selects all + deletes first | Both |
+| Off-screen elements | `DOM.scrollIntoViewIfNeeded` before every click | Both |
+| Form submission | `press('Enter')` triggers onsubmit | Both |
+| SPA navigation | `waitForNavigation()` uses loadEventFired + frameNavigated | Both |
+| Bot detection | Headed mode with real cookies bypasses most checks | Headed |
+| `navigator.webdriver` | Stealth patches in headless (webdriver, plugins, chrome obj) | Headless |
+| Profile locking | Unique temp dir per headless instance | Headless |
+| ARIA noise | 9-step pruning: wrapper collapse, noise removal, landmark promotion | Both |
+
+## bareagent wiring
+
+barebrowse provides a tool adapter for bareagent's Loop:
+
+```javascript
+import { Loop } from 'bare-agent';
+import { Anthropic } from 'bare-agent/providers';
+import { createBrowseTools } from 'barebrowse/src/bareagent.js';
+
+const provider = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+const loop = new Loop({ provider });
+
+const { tools, close } = createBrowseTools();
+
+try {
+  const result = await loop.run(
+    [{ role: 'user', content: 'Search for "barebrowse" on DuckDuckGo and tell me the first result' }],
+    tools
+  );
+  console.log(result.text);
+} finally {
+  await close();
+}
+```
+
+`createBrowseTools(opts)` returns:
+- `tools` -- array of bareagent-compatible tool objects (browse, goto, snapshot, click, type, press, scroll, select, screenshot)
+- `close()` -- cleanup function, call when done
+
+Action tools (click, type, press, scroll, goto) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates.
+
+## MCP wrapper
+
+barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or any MCP client.
+
+```bash
+npm install barebrowse       # or npm install -g barebrowse
+```
+
+Add to your MCP client config (`.mcp.json`, `claude_desktop_config.json`, etc.):
+```json
+{
+  "mcpServers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}
+```
+
+7 tools exposed: `browse` (one-shot), `goto`, `snapshot`, `click`, `type`, `press`, `scroll`.
+
+Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe. This avoids double-token output since MCP tool calls are cheap to chain.
+
+Session tools (goto, snapshot, click, type, press, scroll) share a singleton page, lazy-created on first use.
+
+## Architecture
+
+```
+URL -> chromium.js (find/launch browser, permission flags)
+    -> cdp.js (WebSocket CDP client)
+    -> stealth.js (navigator.webdriver patches, headless only)
+    -> Browser.setPermission (suppress prompts)
+    -> auth.js (extract cookies -> inject via CDP)
+    -> Page.navigate
+    -> consent.js (detect + dismiss cookie dialogs)
+    -> aria.js (Accessibility.getFullAXTree -> nested tree)
+    -> prune.js (9-step role-based pruning)
+    -> interact.js (click/type/scroll/hover/select via Input domain)
+    -> agent-ready snapshot
+```
+
+| Module | Lines | Purpose |
+|---|---|---|
+| `src/index.js` | ~370 | Public API: `browse()`, `connect()`, screenshot, network idle, hybrid |
+| `src/cdp.js` | 148 | WebSocket CDP client, flattened sessions |
+| `src/chromium.js` | 148 | Find/launch Chromium browsers, permission-suppressing flags |
+| `src/aria.js` | 69 | Format ARIA tree as text |
+| `src/auth.js` | 279 | Cookie extraction (Chromium AES + keyring, Firefox), CDP injection |
+| `src/prune.js` | 472 | ARIA pruning pipeline (ported from mcprune) |
+| `src/interact.js` | ~170 | Click, type, press, scroll, hover, select |
+| `src/consent.js` | 200 | Auto-dismiss cookie consent dialogs across languages |
+| `src/stealth.js` | ~40 | Navigator patches for headless anti-detection |
+| `src/bareagent.js` | ~120 | Tool adapter for bareagent Loop |
+| `mcp-server.js` | ~170 | MCP server (JSON-RPC over stdio) |
+
+## Gotchas
+
+1. **Refs are ephemeral.** Every `snapshot()` call generates new refs. Always snapshot before interacting. Never cache refs across snapshots.
+
+2. **SPA navigation has no loadEventFired.** For single-page apps (React, YouTube, GitHub), use `waitForNetworkIdle()` or a timed wait after click instead of `waitForNavigation()`.
+
+3. **Pruning modes matter.** `act` mode (default) keeps interactive elements + visible labels. `read` mode keeps all text content. Use `read` for content extraction, `act` for form filling and navigation.
+
+4. **Headed mode requires manual browser launch.** Start your browser with `--remote-debugging-port=9222`. barebrowse connects to it -- it does not launch it.
+
+5. **Cookie extraction needs unlocked profile.** Chromium cookies are AES-encrypted with a keyring key. If Chromium is running, the profile may be locked. Firefox cookies are plaintext and always accessible.
+
+6. **Hybrid mode kills and relaunches.** If headless is bot-blocked, hybrid mode kills the headless browser and connects to headed on port 9222. The headed browser must already be running.
+
+7. **One page per connect().** Each `connect()` call creates one page. For multiple tabs, call `connect()` multiple times.
+
+8. **Consent dismiss is best-effort.** It handles 16+ tested sites across 7 languages but novel consent implementations may need manual handling. Disable with `{ consent: false }`.
+
+9. **Screenshot returns base64.** Write to file with `fs.writeFileSync('shot.png', Buffer.from(base64, 'base64'))` or pass directly to a vision model.
+
+10. **Chromium-only.** CDP protocol limits us to Chrome, Chromium, Edge, Brave, Vivaldi (~80% desktop share). Firefox support via WebDriver BiDi is not yet implemented.
+
+## Constraints
+
+- **Node >= 22** -- built-in WebSocket, built-in SQLite
+- **Chromium-only** -- CDP protocol
+- **Linux first** -- tested on Fedora/KDE, macOS/Windows cookie paths exist but untested
+- **Not a server** -- library that agents import. Wrap as MCP (included) or HTTP if needed.
+- **Zero required deps** -- everything uses Node stdlib