barebrowse 0.1.0 → 0.2.0

package/docs/prd.md

@@ -0,0 +1,284 @@
+# barebrowse — Product Requirements Document
+
+**Version:** 1.0
+**Date:** 2026-02-22
+**Status:** POC
+
+---
+
+## What barebrowse is
+
+A standalone vanilla JavaScript library that gives autonomous agents authenticated access to the web through the user's own Chromium browser. One package, one import, three modes.
+
+```js
+import { browse } from 'barebrowse';
+const snapshot = await browse('https://any-page.com');
+```
+
+barebrowse handles: finding the browser, connecting via CDP, injecting cookies, navigating, extracting the ARIA accessibility tree, and pruning it down to what an agent actually needs. The output is a clean, token-efficient snapshot of any web page — authenticated as the real user.
+
+## What barebrowse is NOT
+
+- **Not a framework.** No plugin system, no config files, no lifecycle hooks.
+- **Not an MCP server.** But trivially wrappable as one (~30 lines).
+- **Not Playwright.** No bundled browser, no cross-engine abstraction, no 200MB download.
+- **Not an agent.** No LLM, no planning, no orchestration — that's bareagent's job.
+- **Not a scraper.** It browses as the user, not as a bot harvesting data.
+
+---
+
+## The Problem
+
+Every AI agent that needs to read or interact with the web hits the same walls:
+
+1. **Cloudflare / bot detection** — headless browsers get blocked
+2. **Authentication** — sites require login, OAuth, session cookies
+3. **Token bloat** — raw DOM is 100K+ tokens; agents need ~5K
+4. **Two consumers, same need** — research agents (read pages) and personal assistants (click/type) both need an authenticated browser, but existing tools force you to choose one path
+
+Existing solutions (Playwright MCP, sweetlink, open-operator, browser-use) are either too heavy, too opinionated, or solve only half the problem.
+
+## The Insight
+
+The user already has a browser. It's already logged in. It already passes Cloudflare. Instead of fighting the web with headless stealth tricks, **use what's already there**.
+
+CDP (Chrome DevTools Protocol) lets us connect to any Chromium-based browser — the same one the user browses with daily. We get their cookies, their sessions, their anti-detection posture, for free.
+
+---
+
+## Core Architecture
+
+### CDP-Direct (Why No Playwright)
+
+**Decision:** Use CDP over WebSocket directly. No Playwright dependency.
+
+**Why:**
+- Playwright downloads a bundled Chromium (~200MB). barebrowse uses the browser already installed on the user's machine.
+- Playwright abstracts CDP, but we need CDP directly for all three modes (headless, headed, hybrid) against the user's real browser.
+- Every Playwright API call maps 1:1 to a CDP method. The abstraction adds weight without adding capability for our use case.
+- CDP gives us everything: `Accessibility.getFullAXTree`, `Page.navigate`, `Runtime.evaluate`, `Input.dispatch*Event`, `Network.setCookie`, `Page.captureScreenshot`.
+- The CDP WebSocket client is ~100 lines of vanilla JS. Playwright is ~50,000.
+
+**What we lose:** Cross-engine support (Firefox, WebKit). CDP only works with Chromium-family browsers (Chrome, Chromium, Edge, Brave, Vivaldi, Arc, Opera). This covers ~80% of desktop browsers. Firefox support could come later via WebDriver BiDi.
+
+**What we gain:** Zero heavy deps, uses the user's real browser, same code path for headless/headed/hybrid, drastically simpler codebase.
+
+### ARIA-First (Why Not DOM)
+
+**Decision:** Use `Accessibility.getFullAXTree` (ARIA/accessibility tree) as the primary page representation, not DOM.
+
+**Why:**
+- The accessibility tree is the semantic structure of the page — roles, names, states, interactive elements. It's what screen readers see. It's also what agents need.
+- DOM is bloated: wrapper divs, styling, tracking pixels, ad scripts. An agent doesn't need any of that.
+- mcprune already proved this: ARIA snapshots pruned by role achieve 75-95% token reduction on typical pages while preserving all actionable information.
+- CDP's `Accessibility.getFullAXTree` returns the tree directly. No parsing HTML, no building a DOM tree, no traversing nodes.
+- ARIA refs map directly to CDP interaction targets — the agent reads a button in the tree and can click it via the same CDP connection.
+
+**The pipeline:** CDP connect → authenticate → navigate → ARIA tree → prune → agent gets clean snapshot.
+
+### Three Modes (Why All Three)
+
+**Decision:** Headless, headed, and hybrid — not as separate packages or optional features, but as a single flag on the same API.
+
+**Why they're not bloat:** The CDP conversation is identical regardless of mode. The only difference is how you get a browser process with a debug port. It's one code path with a different entry point:
+
+```
+headless: spawn chromium --headless=new --remote-debugging-port=N
+headed:   connect to user's already-running browser on debug port
+hybrid:   try headless → detect failure → fall back to headed
+```
+
+After connection, every CDP command is the same. Three modes = ~20 extra lines in `chromium.js`, not three implementations.
+
+**When to use each:**
+
+| Mode | Use case | Example |
+|---|---|---|
+| `headless` | Agent research, background tasks, CI | "Read this article and summarize it" |
+| `headed` | Personal assistant, interactive tasks, auth flows | "Book me a flight on this page" |
+| `hybrid` | Default for autonomous agents | Try headless; if CF-blocked, fall back to headed |
+
+**Headless is the default.** Most agent tasks are "go read this page." Headed is the escape hatch for when headless fails or the task requires user-visible interaction.
+
+### Cookie Authentication
+
+**Decision:** Extract cookies from the user's browser profile and inject via CDP `Network.setCookie`.
+
+**Why:**
+- The user's browser has active sessions for every site they use. We reuse those sessions instead of building new auth flows.
+- sweet-cookie (npm package) already extracts cookies from Chrome/Firefox/Safari SQLite databases with OS keychain decryption. We use it or vendor the relevant parts.
+- For headed mode, cookies are already present in the browser — no extraction needed.
+- For headless mode, we extract from the user's profile and inject into the headless instance.
+
+**Limitation:** Cookies expire. This works for existing sessions, not new logins. For sites requiring fresh auth, headed mode with user interaction is the fallback.
+
+### Pruning (Absorbed from mcprune)
+
+**Decision:** Port mcprune's role-based ARIA tree pruning into barebrowse as a built-in step, not an optional module.
+
+**Why:**
+- Pruning is not optional for agent consumption. A raw ARIA tree is still too large for most LLM context windows. Pruning is part of the pipeline, not an afterthought.
+- mcprune's pruning logic is a pure function: takes an ARIA tree, returns a smaller ARIA tree. No browser dependency, no Playwright coupling. It's ~300 lines of role-based tree surgery.
+- By absorbing it, barebrowse becomes a complete "URL in, agent-ready snapshot out" solution. No second package needed.
+
+**What we port from mcprune:**
+- Role taxonomy (landmarks, interactive, structural, noise)
+- Landmark extraction (main, nav, banner, etc.)
+- Noise removal (ads, tracking, legal boilerplate)
+- Interactive element preservation (buttons, links, inputs)
+- Wrapper collapsing (nested generics, empty groups)
+- Context-aware filtering (search relevance, dedup)
+
+**What stays in mcprune:** The Playwright MCP proxy architecture. mcprune can continue to exist as a Playwright-based MCP server for users who want that path. But for barebrowse consumers, pruning is built in.
+
+---
+
+## API Design
+
+### Public API
+
+```js
+import { browse, connect } from 'barebrowse';
+
+// One-shot: URL in, pruned ARIA snapshot out
+const tree = await browse('https://example.com');
+
+// With options
+const tree = await browse('https://example.com', {
+  mode: 'hybrid',        // 'headless' (default) | 'headed' | 'hybrid'
+  cookies: true,          // inject user's cookies (default: true)
+  prune: true,            // apply ARIA pruning (default: true)
+  browser: 'chrome',      // which browser profile for cookies
+  timeout: 30000,         // navigation timeout ms
+});
+
+// Long-lived session for interaction
+const page = await connect({ mode: 'headed' });
+await page.goto('https://amazon.com/cart');
+await page.click('[data-action="checkout"]');
+await page.type('#gift-message', 'Happy birthday!');
+const tree = await page.snapshot();  // ARIA + prune
+await page.close();
+```
+
+### Design Principles
+
+1. **One package, one import.** No picking pieces. `browse()` does everything. Power users get `connect()` for long-lived sessions.
+2. **Batteries included.** Cookies, ARIA, pruning — all happen inside by default. Disable with flags if you want raw access.
+3. **Escape hatches.** `connect()` returns an object with the raw CDP connection accessible. If you need something we don't wrap, you can send CDP commands directly.
+4. **Progressive complexity.** `browse(url)` for 90% of use cases. Options object for the rest. `connect()` for interactive sessions.
+
+---
+
+## The bare- Ecosystem
+
+```
+bareagent   = the brain  (orchestration, planning, memory, retries, tool loop)
+barebrowse  = the eyes + hands  (browse, read, interact with the web)
+```
+
+**Integration with bareagent:**
+
+```js
+import { Loop } from 'bare-agent';
+import { browse } from 'barebrowse';
+
+const tools = [
+  { name: 'browse', execute: ({ url }) => browse(url) },
+];
+
+const loop = new Loop({ provider });
+await loop.run([{ role: 'user', content: 'Find the cheapest flight to Tokyo' }], tools);
+```
+
+bareagent handles the think/act/observe loop. barebrowse handles "see the web and act on it." Neither is opinionated about the other. Tools are plain functions.
+
+**Integration with multis:**
+
+multis (personal assistant) uses barebrowse in headed mode for interactive tasks. The multis proxy is already running, providing a desktop session. barebrowse connects to the user's Chrome and drives it on behalf of the assistant.
+
+**MCP server wrapper (future):**
+
+barebrowse is not an MCP server, but wrapping it as one is ~30 lines. This would replace Playwright MCP + mcprune proxy with a single, lighter MCP server.
+
+---
+
+## Decisions Log — Why We Chose Each
+
+This section exists so we don't re-debate settled decisions.
+
+| Decision | Choice | Why | Alternative considered | Why not |
+|---|---|---|---|---|
+| Browser protocol | CDP direct | Uses user's browser, ~100 lines, all 3 modes | Playwright | 200MB download, bundles its own Chromium, abstracts what we need raw |
+| Page representation | ARIA tree | Semantic, token-efficient, what agents need | DOM/HTML | Bloated, noisy, needs heavy parsing |
+| Pruning | Built-in | Agents always need pruned output | Optional/separate | Two deps for one job, pruning isn't optional |
+| Cookie auth | Own auth.js + CDP inject | User's existing sessions (Firefox or Chromium), cross-browser injection into headless Chromium | OAuth/credential storage | Complex, security liability, reinventing what the browser already solved |
+| Three modes | One flag | Same CDP code, ~20 lines difference | Separate packages | Same code, artificial separation |
+| Chromium only | CDP constraint | ~80% browser share, user's real browser | Cross-browser (Playwright) | Requires Playwright, loses "use your own browser" benefit |
+| Anti-detection | Runtime.evaluate patches | Minimal stealth for headless mode | Full stealth framework | Over-engineering; headless + real cookies handles 90% |
+| Daemon/server | None | CDP is direct, no intermediary needed | sweetlink daemon pattern | Unnecessary complexity for local agent→browser |
+| Framework | None (vanilla JS) | Matches bare- philosophy, zero deps | Express/Fastify wrapper | Not a server, not needed |
+| Language | Vanilla JavaScript | Node.js ecosystem, same as bareagent, CDP libs available | TypeScript | Added build step, not needed for POC; can add types later |
+| Naming | chromium.js | Covers all Chromium-family browsers, not just Chrome | chrome.js | Too specific; Brave/Edge/Arc are also targets |
+| mcprune integration | Absorb pruning logic | One package does it all, mcprune pruning is a pure function | Keep separate | Agents shouldn't need two packages to browse |
+| openclaw lesson | Single bridge protocol | One CDP connection vs many API integrations | Direct multi-API | openclaw proved this fails — bloat, maintenance, fragility |
+
+---
+
+## Future Features (Post-POC)
+
+### Near-term
+- **Screenshot capture** — `Page.captureScreenshot` via CDP. Useful for visual verification and multimodal agents.
+- **Network interception** — `Network.requestWillBeSent` / `Network.responseReceived` for monitoring page loads. Detect redirects, blocked resources, API calls.
+- **Wait strategies** — `waitForNavigation()` done (Page.loadEventFired). Still needed: network idle, element presence polling.
+- **Tab management** — Multiple pages in one browser session. CDP `Target.createTarget` / `Target.attachToTarget`.
+- **MCP server wrapper** — Expose browse/click/type as MCP tools. Replaces Playwright MCP + mcprune combo.
+
+### Medium-term
+- **Firefox support** — Via WebDriver BiDi protocol (cross-browser standard, still maturing). Second protocol adapter alongside CDP.
+- **Cookie sync** — In hybrid mode, extract fresh cookies from headed session and cache for future headless use. Self-refreshing auth.
+- **Selector discovery** — Port sweetlink's `discoverSelectors` — crawl ARIA tree, score interactive elements, return ranked action targets.
+- **Form understanding** — Detect forms in ARIA tree, map fields to semantic purposes, enable agents to fill forms intelligently.
+- **Proxy/Tor support** — Route headless browser through proxy for geo-restricted content.
+
+### Long-term
+- **Profile management** — Multiple browser profiles for different identities/accounts.
+- **Session recording/replay** — Record browsing sessions as CDP commands, replay for testing.
+- **Visual grounding** — Combine ARIA tree with screenshot regions for multimodal agents.
+- **Agent memory integration** — Remember visited pages, cache snapshots, track which sites need headed mode.
+
+---
+
+## Repos Studied — What We Borrowed and Why
+
+| Repo | What we took | What we skipped |
+|---|---|---|
+| **steipete/sweet-cookie** | Cookie extraction from browser profiles, OS keychain decryption | Nothing — clean, focused library |
+| **steipete/sweetlink** | CDP dual-channel concept, selector discovery scoring, click/command patterns | Daemon architecture, WebSocket bridge, in-page runtime injection, HMAC auth |
+| **steipete/canvas** | Stealth/anti-detection config patterns | Go implementation (we're JS) |
+| **nichochar/open-operator** | AI agent web automation patterns | Full framework, too opinionated |
+| **AntlerClaw/playwright-mcp** | How to expose browser as MCP tools | Playwright dependency |
+| **AntlerClaw/mcp-browser-use** | MCP-native browser patterns | Heavy deps |
+| **AitchKay/chromancer** | Accessibility tree extraction approach | Different stack |
+| **mcprune (own)** | ARIA pruning logic — role taxonomy, landmark extraction, noise removal, wrapper collapsing | Playwright dependency, MCP proxy architecture |
+| **openclaw (own)** | Lesson learned: multi-API direct integration = bloat. Use a single bridge protocol | Everything — the architecture was the cautionary tale |
+
+### The openclaw lesson
+
+openclaw tried to integrate 10+ messaging APIs directly — each with its own auth, format, quirks. It became a maintenance nightmare. multis solved the same problem by using Beeper/Matrix as a single bridge.
+
+barebrowse applies the same lesson: instead of integrating Playwright + Puppeteer + WebDriver + stealth plugins + cookie libraries + proxy managers, we use **one protocol (CDP) to one browser (the user's)**. Everything else is unnecessary.
+
+---
+
+## Success Criteria
+
+barebrowse succeeds when:
+
+1. `browse(url)` returns a pruned ARIA snapshot of any page, authenticated as the user
+2. Zero heavy dependencies — no Playwright, no Puppeteer, no bundled browser
+3. Works with any installed Chromium-based browser
+4. Headless for research, headed for interaction, hybrid for autonomous agents
+5. Plugs into bareagent as plain tool functions
+6. Total source under 1,000 lines for core functionality
+7. An agent using barebrowse + bareagent can autonomously research the web and act on pages

package/docs/testing.md

@@ -0,0 +1,202 @@
+# barebrowse -- Testing Guide
+
+## Run all tests
+
+```bash
+node --test test/unit/*.test.js test/integration/*.test.js
+```
+
+54 tests, 5 files, ~45s on a typical machine. No test framework -- uses Node's built-in `node:test` runner.
+
+## Test pyramid
+
+```
+          /  E2E  \         15 tests — real websites (Google, Wikipedia, GitHub, etc.)
+         /----------\
+        / Integration \     11 tests — full browse/connect pipeline against example.com, HN
+       /----------------\
+      /      Unit        \  28 tests — pruning, cookie extraction, CDP client, browser launch
+     /--------------------\
+```
+
+Unit tests are fast and isolated. Integration tests launch a real headless Chromium. E2E tests (part of interact.test.js) hit live websites — they require internet and may be slower or flaky on CI.
+
+---
+
+## Unit tests (28 tests)
+
+### `test/unit/prune.test.js` -- 16 tests
+
+Tests the 9-step ARIA pruning pipeline in isolation. No browser, no network.
+
+| # | Test | What it validates |
+|---|------|-------------------|
+| 1 | returns null for empty tree | prune(null) returns null |
+| 2 | unwraps RootWebArea | Root container node stripped from output |
+| 3 | keeps interactive elements in act mode | Buttons, links, textboxes survive pruning |
+| 4 | drops paragraphs in act mode | Non-interactive text removed in act mode |
+| 5 | keeps paragraphs in browse mode | Text content preserved in browse/read mode |
+| 6 | drops InlineTextBox noise | Low-level rendering nodes always filtered |
+| 7 | keeps headings | h1/h2 headings preserved in browse mode |
+| 8 | drops description headings in act mode | Only primary h1 kept, secondary headings removed |
+| 9 | collapses unnamed structural wrappers | Nested generic divs flattened, children promoted |
+| 10 | keeps named groups | Radiogroup/radio elements preserved |
+| 11 | drops separators | Separator/hr nodes always removed |
+| 12 | drops images in act mode, keeps named in browse | Act strips all images, browse keeps named ones |
+| 13 | trims combobox to just name + selected value | Combobox children (options list) stripped |
+| 14 | uses context keywords to condense non-matching cards | Context filtering collapses irrelevant list items |
+| 15 | extracts main landmark when present | Act mode keeps only main content area |
+| 16 | handles pages without landmarks (HN-style) | Pruning works on flat, landmark-less pages |
+
+### `test/unit/auth.test.js` -- 7 tests
+
+Tests cookie extraction from the local filesystem. Reads real browser cookie databases.
+
+| # | Test | What it validates |
+|---|------|-------------------|
+| 1 | auto-detects a browser and returns cookies | extractCookies() finds Firefox or Chromium and returns array |
+| 2 | returns cookies with correct shape | Each cookie has name, value, domain, path, secure, httpOnly, sameSite, expires |
+| 3 | filters by domain | Domain filter parameter restricts results |
+| 4 | extracts from firefox explicitly | `{ browser: 'firefox' }` parameter works |
+| 5 | throws for non-existent browser | Error thrown for unknown browser string |
+| 6 | cookies have non-empty values | All returned cookies have non-empty value strings |
+| 7 | sameSite is a valid value | sameSite is one of 'None', 'Lax', or 'Strict' |
+
+Note: 2 tests may skip when Chromium profile is locked by a running instance (AES decryption needs keyring access).
+
+### `test/unit/cdp.test.js` -- 5 tests
+
+Tests browser discovery, launch, CDP WebSocket client, and session handling.
+
+| # | Test | What it validates |
+|---|------|-------------------|
+| 1 | finds a Chromium-based browser | findBrowser() returns path to chromium/chrome/brave/edge |
+| 2 | launches headless Chromium and returns WebSocket URL | launch() returns valid ws:// URL, port, and live process |
+| 3 | connects to browser and sends commands | createCDP() connects, Browser.getVersion responds |
+| 4 | creates session-scoped handles | Target.createTarget + session() dispatches to correct target |
+| 5 | gets accessibility tree from a page | Accessibility.getFullAXTree returns nodes with role/name |
+
+---
+
+## Integration tests (11 tests)
+
+### `test/integration/browse.test.js` -- 11 tests
+
+Tests the full `browse()` and `connect()` pipeline end-to-end against real pages.
+
+| # | Suite | Test | What it validates |
+|---|-------|------|-------------------|
+| 1 | browse() | returns ARIA snapshot for a public page | browse('example.com') returns non-empty snapshot with title |
+| 2 | browse() | includes heading and ref markers | Snapshot contains roles and [ref=N] markers |
+| 3 | browse() | prunes by default (act mode) | Pruned output smaller than raw ARIA tree |
+| 4 | browse() | browse mode preserves paragraphs | pruneMode: 'browse' keeps text content |
+| 5 | browse() | act mode drops paragraphs | pruneMode: 'act' removes non-interactive text |
+| 6 | browse() | handles complex pages with significant reduction | Hacker News pruned by at least 20% |
+| 7 | browse() | can disable cookies | cookies: false works without error |
+| 8 | browse() | can disable pruning | prune: false keeps raw RootWebArea |
+| 9 | connect() | creates a long-lived session and navigates | connect() + goto() + snapshot() works |
+| 10 | connect() | supports multiple navigations in one session | Multiple goto() calls on same page |
+| 11 | connect() | snapshot accepts prune: false for raw output | snapshot(false) preserves full tree |
+
+---
+
+## E2E tests (15 tests)
+
+### `test/integration/interact.test.js` -- 15 tests
+
+Tests real interactions: clicking, typing, scrolling, form submission, and navigation. Uses a local `data:` URL fixture for deterministic tests, plus live websites for real-world coverage.
+
+#### Data URL fixture tests (7 tests)
+
+| # | Test | What it validates |
+|---|------|-------------------|
+| 1 | click sets button result text | page.click(ref) triggers onclick handler |
+| 2 | type fills an empty input | page.type(ref, text) fills empty textbox |
+| 3 | type with clear replaces existing text | { clear: true } replaces prefilled input |
+| 4 | click on offscreen element scrolls into view first | Auto-scroll before click on element at 3000px |
+| 5 | press Enter submits a form | page.press('Enter') triggers form onsubmit |
+| 6 | press throws on unknown key | Error thrown for unrecognized key names |
+| 7 | link click + waitForNavigation navigates | Cross-page navigation via click + waitForNavigation |
+
+#### Live website tests (8 tests)
+
+| # | Site | Test | What it validates |
+|---|------|------|-------------------|
+| 1 | Google | search and navigate results | type() + press('Enter') + waitForNavigation() on Google |
+| 2 | Wikipedia | navigate article links | click() + waitForNavigation() on Wikipedia article links |
+| 3 | GitHub | navigate SPA repo links | click() works for SPA navigation (no loadEventFired) |
+| 4 | DuckDuckGo | search query and verify results | type() + press('Enter') + navigation on DDG |
+| 5 | Hacker News | load homepage and navigate to a story | click() + waitForNavigation() on HN story links |
+| 6 | Reddit (old) | load and navigate to a post | Page navigation with fallback to www.reddit.com |
+| 7 | Firefox cookies | extract and inject into CDP session | extractCookies() + injectCookies() workflow |
+| 8 | Firefox cookies | extractCookies with firefox returns array | Explicit browser parameter returns proper array |
+
+---
+
+## Writing new tests
+
+Follow the existing pattern:
+
+```javascript
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { connect } from '../../src/index.js';
+
+describe('my feature', () => {
+  it('does the thing', async () => {
+    const page = await connect();
+    try {
+      await page.goto('https://example.com');
+      const snap = await page.snapshot();
+      assert.ok(snap.includes('Example Domain'));
+    } finally {
+      await page.close();
+    }
+  });
+});
+```
+
+Key conventions:
+- Always `page.close()` in a `finally` block to avoid leaked browser processes
+- Use `data:` URL fixtures for deterministic tests (no network dependency)
+- Real-site tests go in interact.test.js, grouped by site in `describe()` blocks
+- Use `assert.ok()` and `assert.strictEqual()` from `node:assert/strict`
+- No test framework dependencies -- `node:test` only
+
+### Data URL fixture pattern
+
+For testing interactions without network:
+
+```javascript
+const FIXTURE = `data:text/html,${encodeURIComponent(`
+<html><body>
+  <button onclick="document.getElementById('r').textContent='clicked'">Click Me</button>
+  <div id="r"></div>
+</body></html>
+`)}`;
+
+it('clicks the button', async () => {
+  const page = await connect();
+  try {
+    await page.goto(FIXTURE);
+    const snap = await page.snapshot({ mode: 'browse' });
+    const ref = findRef(snap, 'button', 'Click Me');
+    await page.click(ref);
+    const snap2 = await page.snapshot({ mode: 'browse' });
+    assert.ok(snap2.includes('clicked'));
+  } finally {
+    await page.close();
+  }
+});
+```
+
+---
+
+## CI considerations
+
+- Unit tests: fast, no network, always safe to run
+- Integration tests: need Chromium installed, no network (uses example.com/HN but tolerates failures)
+- E2E tests: need internet, may be flaky (sites change, rate limits, geo-blocks)
+- Recommended CI split: run unit + integration always, E2E on manual trigger or nightly
+- Each test launches/kills its own browser instance -- no shared state between tests
+- Auth tests may skip when Chromium profile is locked by a running instance

package/examples/headed-demo.js

@@ -0,0 +1,157 @@
+/**
+ * barebrowse headed-mode demo
+ *
+ * This script demonstrates interactive browsing with a VISIBLE browser window.
+ * You watch the browser while barebrowse navigates, clicks, and types.
+ *
+ * SETUP — run this command first in a separate terminal:
+ *
+ *   chromium-browser --remote-debugging-port=9222
+ *
+ * Then run this script:
+ *
+ *   node examples/headed-demo.js
+ *
+ * The script connects to the already-running browser via CDP on port 9222.
+ * You will see each action happen in real time.
+ */
+
+import { connect } from '../src/index.js';
+
+// --- Helpers ---
+
+/** Small delay so you can watch the browser between steps. */
+function wait(ms = 1500) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Find a ref by matching role and name in the snapshot text. */
+function findRoleRef(snapshot, role, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`${role} "${escaped}".*?\\[ref=([^\\]]+)\\]`);
+  const m = snapshot.match(re);
+  return m ? m[1] : null;
+}
+
+/** Find a ref by partial name match (case-insensitive). */
+function findRoleRefPartial(snapshot, role, nameFragment) {
+  const escaped = nameFragment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`${role} "[^"]*${escaped}[^"]*".*?\\[ref=([^\\]]+)\\]`, 'i');
+  const m = snapshot.match(re);
+  return m ? m[1] : null;
+}
+
+/** Print a snapshot truncated to a character limit. */
+function printSnapshot(snapshot, limit = 500) {
+  const truncated = snapshot.length > limit
+    ? snapshot.slice(0, limit) + `\n... (${snapshot.length - limit} more chars)`
+    : snapshot;
+  console.log(truncated);
+}
+
+// --- Demo ---
+
+async function main() {
+  console.log('=== barebrowse headed-mode demo ===\n');
+  console.log('Connecting to Chromium on port 9222...');
+  console.log('(Make sure you ran: chromium-browser --remote-debugging-port=9222)\n');
+
+  const page = await connect({ mode: 'headed', port: 9222 });
+
+  try {
+    // Step 1: Navigate to Wikipedia
+    console.log('[Step 1] Navigating to Wikipedia "JavaScript" article...');
+    await page.goto('https://en.wikipedia.org/wiki/JavaScript');
+    await wait();
+
+    // Step 2: Take a snapshot
+    console.log('[Step 2] Taking ARIA snapshot of the page...\n');
+    let snap = await page.snapshot();
+    printSnapshot(snap);
+    console.log();
+
+    // Step 3: Find and click a link
+    console.log('[Step 3] Looking for a link to click...');
+    // Try to find the "ECMAScript" link — a common one in the JS article
+    let linkRef = findRoleRefPartial(snap, 'link', 'ECMAScript');
+    if (!linkRef) {
+      // Fallback: find any link
+      linkRef = findRoleRefPartial(snap, 'link', 'programming');
+    }
+    if (linkRef) {
+      console.log(`  Found link ref=${linkRef}, clicking it...`);
+      const navPromise = page.waitForNavigation();
+      await page.click(linkRef);
+
+      // Step 4: Wait for navigation
+      console.log('[Step 4] Waiting for navigation to complete...');
+      await navPromise;
+      await wait();
+    } else {
+      console.log('  No matching link found, skipping click step.');
+    }
+
+    // Step 5: New snapshot after navigation
+    console.log('[Step 5] Taking snapshot of the new page...\n');
+    snap = await page.snapshot();
+    printSnapshot(snap);
+    console.log();
+
+    // Step 6: Navigate to DuckDuckGo
+    console.log('[Step 6] Navigating to DuckDuckGo...');
+    await page.goto('https://duckduckgo.com');
+    await wait();
+
+    // Step 7: Find search box and type a query
+    console.log('[Step 7] Taking snapshot to find the search box...');
+    snap = await page.snapshot();
+    let searchRef = findRoleRefPartial(snap, 'textbox', 'search')
+      || findRoleRefPartial(snap, 'searchbox', 'search')
+      || findRoleRefPartial(snap, 'combobox', 'search');
+
+    if (searchRef) {
+      console.log(`  Found search box ref=${searchRef}, typing query...`);
+      await page.click(searchRef);
+      await wait(500);
+      await page.type(searchRef, 'barebrowse CDP browser automation');
+      await wait();
+    } else {
+      console.log('  Could not find search box. Snapshot preview:');
+      printSnapshot(snap, 300);
+      console.log('  Skipping search steps.');
+      return;
+    }
+
+    // Step 8: Press Enter
+    console.log('[Step 8] Pressing Enter to search...');
+    const resultsNav = page.waitForNavigation();
+    await page.press('Enter');
+
+    // Step 9: Wait for results
+    console.log('[Step 9] Waiting for search results...');
+    await resultsNav;
+    await wait(2000);
+
+    // Step 10: Snapshot the results
+    console.log('[Step 10] Taking snapshot of search results...\n');
+    snap = await page.snapshot();
+    printSnapshot(snap, 800);
+    console.log();
+
+    console.log('=== Demo complete ===');
+  } finally {
+    console.log('Closing session...');
+    await page.close();
+  }
+}
+
+main().catch((err) => {
+  if (err.message?.includes('ECONNREFUSED') || err.message?.includes('connect')) {
+    console.error('\nError: Could not connect to Chromium on port 9222.');
+    console.error('Make sure you have Chromium running with remote debugging:');
+    console.error('\n  chromium-browser --remote-debugging-port=9222\n');
+  } else {
+    console.error('\nError:', err.message || err);
+  }
+  process.exit(1);
+});