barebrowse 0.2.1 → 0.3.0

package/docs/03-logs/validation-log.md

@@ -0,0 +1,123 @@
+# Validation Log
+
+What's been tested against the real world. Updated when new sites or features are validated.
+
+---
+
+## Test suite (64 tests, 6 files)
+
+| File | Tests | Type | What it covers |
+|------|-------|------|----------------|
+| `test/unit/prune.test.js` | 16 | Unit | 9-step pruning pipeline in isolation |
+| `test/unit/auth.test.js` | 7 | Unit | Cookie extraction from Firefox/Chromium |
+| `test/unit/cdp.test.js` | 5 | Unit | Browser discovery, launch, CDP client, sessions |
+| `test/integration/browse.test.js` | 11 | Integration | Full `browse()` and `connect()` pipeline |
+| `test/integration/cli.test.js` | 10 | Integration | CLI session lifecycle: open/snapshot/goto/click/eval/console/network/close |
+| `test/integration/interact.test.js` | 15 | E2E | Real interactions on data: fixtures + live sites |
+
+Run all: `node --test test/unit/*.test.js test/integration/*.test.js`
+
+## Site validation matrix
+
+Tested across 16+ sites, 8 countries, 7 languages.
+
+| Site | Consent | Cookies | Interactions | Notes |
+|------|---------|---------|-------------|-------|
+| google.com | NL dialog dismissed | Firefox injection | Search (combobox + Enter) | Bot-blocks headless |
+| youtube.com | Bypassed via cookies | Firefox injection | Search + video playback | Full e2e demo, SPA nav |
+| bbc.com | SourcePoint dismissed | -- | -- | Button outside dialog |
+| wikipedia.org | -- | -- | Link click + navigation | Clean, no consent |
+| github.com | -- | -- | SPA navigation | Needs settle time |
+| duckduckgo.com | -- | -- | Search + results | Headless-friendly |
+| news.ycombinator.com | -- | -- | Story link click | Clean, simple DOM |
+| amazon.de | Banner dismissed | -- | -- | |
+| theguardian.com | CMP dismissed | -- | -- | |
+| spiegel.de | CMP dismissed | -- | -- | German |
+| lemonde.fr | CMP dismissed | -- | -- | French |
+| elpais.com | CMP dismissed | -- | -- | Spanish |
+| corriere.it | CMP dismissed | -- | -- | Italian |
+| nos.nl | CMP dismissed | -- | -- | Dutch |
+| bild.de | CMP dismissed | -- | -- | German |
+| nu.nl | CMP dismissed | -- | -- | Dutch |
+| booking.com | Banner dismissed | -- | -- | |
+| nytimes.com | -- | -- | -- | No consent wall |
+| stackoverflow.com | Footer link only | -- | -- | Not blocking |
+| cnn.com | -- | -- | -- | No consent wall |
+| reddit.com | -- | -- | Fallback to old.reddit | Bot-blocks headless |
+
+## Token reduction measurements
+
+| Page | Raw ARIA | 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% |
+
+---
+
+## CLI manual validation (v0.3.0)
+
+Full end-to-end validation of every CLI command against real websites.
+
+### Session lifecycle
+
+| Command | Result |
+|---------|--------|
+| `barebrowse open https://example.com` | Session started, pid+port printed, session.json created |
+| `barebrowse status` | Shows running pid, port, start time |
+| `barebrowse close` | "Session closed", session.json removed, daemon exited |
+| `status` after close | "No session found", exit code 1 |
+| `click 5` with no session | "No active session. Run `barebrowse open` first.", exit 1 |
+| double `open` | "Session already running. Use `barebrowse close` first.", exit 1 |
+
+### Navigation + snapshots (example.com, HN)
+
+| Command | Result |
+|---------|--------|
+| `snapshot` (example.com) | `.barebrowse/page-*.yml` created, clean formatting |
+| `snapshot --mode=read` | Read mode includes paragraphs, each node on own line |
+| `goto https://news.ycombinator.com` | "ok" |
+| `snapshot` (HN) | Clean ARIA tree with refs, proper newline separation |
+| `screenshot` | Valid 780x493 PNG file |
+
+### Interactions (DuckDuckGo search)
+
+| Command | Result |
+|---------|--------|
+| `type 12 barebrowse npm` | "ok", multi-word text correctly joined |
+| `press Enter` | "ok", search submitted |
+| `wait-idle` | "ok", waited for network settle |
+| `eval "document.title"` | `"barebrowse npm at DuckDuckGo"` |
+| `snapshot` | Search results page, clean formatting with refs |
+| `fill 2583 hello world` | "ok", cleared search box + typed new text |
+| `hover 2402` | "ok" |
+| `scroll 300` | "ok" |
+
+### Debugging commands
+
+| Command | Result |
+|---------|--------|
+| `eval "1 + 1"` | `2` |
+| `eval "document.location.href"` | `"https://news.ycombinator.com/news"` |
+| `eval "console.log('test'); console.error('err')"` | `ok` (undefined return) |
+| `console-logs` | `.json (2 entries)` — log + error captured with types and timestamps |
+| `network-log` | `.json (15 entries)` — all requests with URL, method, status |
+| `network-log --failed` | `.json (1 entries)` — filtered to failed/4xx+ only |
+
+### Legacy + install commands
+
+| Command | Result |
+|---------|--------|
+| `browse https://example.com` | One-shot snapshot to stdout |
+| `install` | "No MCP clients detected" + Claude Code hint |
+| `install --skill` | SKILL.md copied to `~/.config/claude/skills/barebrowse/` |
+| (no args) | Clean help output with all commands |
+
+### Bug found and fixed during validation
+
+**`src/aria.js` line 23**: ignored nodes joined children with `''` instead of `'\n'`, causing sibling subtrees to concatenate on one line (e.g. `[ref=15]- _promote`). Fixed to `.filter(Boolean).join('\n')`. All 64 tests pass with the fix.
+
+---
+
+*Add new validation entries when testing against new sites or features.*

package/docs/04-process/definition-of-done.md

@@ -0,0 +1,31 @@
+# Definition of Done
+
+A feature or change is "done" when ALL of these are true.
+
+## Code
+
+- [ ] Works end-to-end (not just the happy path)
+- [ ] No heavy dependencies added (vanilla -> stdlib -> external hierarchy respected)
+- [ ] Under reasonable line count -- no bloat
+- [ ] Clean process management -- no orphan browser processes
+- [ ] No security vulnerabilities introduced (command injection, XSS, etc.)
+
+## Tests
+
+- [ ] Existing tests still pass: `node --test test/unit/*.test.js test/integration/*.test.js`
+- [ ] New behavior has test coverage (integration preferred over unit)
+- [ ] Bug fixes include a regression test that fails before the fix
+
+## Documentation
+
+- [ ] `docs/00-context/system-state.md` updated if architecture changed
+- [ ] `docs/03-logs/decisions-log.md` updated if a design decision was made
+- [ ] `barebrowse.context.md` updated if public API changed
+- [ ] `CHANGELOG.md` updated with what changed
+
+## Not required (avoid over-engineering)
+
+- 100% code coverage
+- TypeScript types
+- Cross-platform testing (Linux first, others later)
+- Performance benchmarks (unless performance is the feature)

package/docs/04-process/dev-workflow.md

@@ -0,0 +1,68 @@
+# Development Workflow
+
+## 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:**
+1. Vanilla language -- write it yourself if <50 lines and not security-critical
+2. Standard library -- `node:test`, `node:fs`, `node:crypto`, `node:sqlite`
+3. External -- only when stdlib can't do it in <100 lines. Must be maintained, lightweight, 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.
+
+## Language and runtime
+
+- Vanilla JavaScript, ES modules, no build step
+- Node.js >= 22 (built-in WebSocket, built-in SQLite)
+- No TypeScript -- can add types later if needed
+
+## Running tests
+
+```bash
+# All 54 tests
+node --test test/unit/*.test.js test/integration/*.test.js
+
+# Unit only (fast, no network)
+node --test test/unit/prune.test.js
+node --test test/unit/auth.test.js
+node --test test/unit/cdp.test.js
+
+# Integration (needs Chromium + network)
+node --test test/integration/browse.test.js
+node --test test/integration/interact.test.js
+
+# Quick smoke test
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://example.com'))"
+```
+
+## Testing standards
+
+- **Test behavior, not implementation.** Call the public API, assert on observable output.
+- **Integration tests are the sweet spot.** Real components working together.
+- **No test framework deps.** `node:test` and `node:assert/strict` only.
+- **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.
+
+See `docs/04-process/testing.md` for the full test guide.
+
+## Git workflow
+
+- Main branch: `main`
+- Commit messages: conventional (`fix:`, `feat:`, `chore:`, `docs:`, `release:`)
+- No force pushes to main
+
+## Environment
+
+- OS: Fedora Linux, KDE Plasma, Wayland
+- Node: 22.22.0
+- Browser: `/usr/bin/chromium-browser`
+- Default browser: Firefox (cookies extracted from `~/.mozilla/firefox/*.default-release/cookies.sqlite`)
+- KWallet has Chromium Safe Storage key

package/docs/{testing.md → 04-process/testing.md}

@@ -6,14 +6,14 @@
 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.
+64 tests, 6 files, ~60s 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
+        / Integration \     21 tests — browse/connect pipeline + CLI session lifecycle
        /----------------\
       /      Unit        \  28 tests — pruning, cookie extraction, CDP client, browser launch
      /--------------------\
@@ -98,6 +98,25 @@ Tests the full `browse()` and `connect()` pipeline end-to-end against real pages
 | 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 |
 
+### `test/integration/cli.test.js` -- 10 tests
+
+Tests the full CLI session lifecycle: daemon spawn, command dispatch over HTTP, and cleanup. Uses a temp directory so tests don't pollute the project.
+
+| # | Test | What it validates |
+|---|------|-------------------|
+| 1 | open starts a daemon and creates session.json | `barebrowse open about:blank` spawns daemon, writes session.json with port+pid |
+| 2 | status shows running session | `barebrowse status` reports pid, port, start time |
+| 3 | snapshot creates a .yml file | `barebrowse snapshot` writes .barebrowse/page-*.yml |
+| 4 | goto navigates and snapshot shows new page content | `barebrowse goto example.com` + snapshot contains "Example Domain" + refs |
+| 5 | click sends click command | `barebrowse click <ref>` returns "ok" |
+| 6 | eval executes JS and returns result | `barebrowse eval 1+1` returns "2" |
+| 7 | console-logs creates a .json file | After eval with console.log, `console-logs` writes JSON |
+| 8 | network-log creates a .json file | `network-log` writes JSON with request entries |
+| 9 | close shuts down the daemon | `barebrowse close` removes session.json, daemon exits |
+| 10 | status after close shows no session | `barebrowse status` exits non-zero when no session |
+
+Note: Tests run sequentially within the suite (each depends on the session opened in test 1). The `after()` hook ensures daemon cleanup even if tests fail.
+
 ---
 
 ## E2E tests (15 tests)

package/docs/README.md

@@ -0,0 +1,55 @@
+# barebrowse -- Documentation
+
+## Navigation
+
+### 00-context/ -- Why and what exists
+
+| File | What's in it |
+|------|-------------|
+| [vision.md](00-context/vision.md) | What barebrowse is, what it's not, the core insight, success criteria |
+| [assumptions.md](00-context/assumptions.md) | Hard constraints, assumptions, known limitations, risks |
+| [system-state.md](00-context/system-state.md) | Current architecture, full pipeline, module table, capabilities, tested sites |
+
+### 01-product/ -- What the product must do
+
+| File | What's in it |
+|------|-------------|
+| [prd.md](01-product/prd.md) | Product requirements, API design, three modes, pruning strategy, future features |
+
+### 02-features/ -- How features are designed
+
+*Feature-specific docs go here as the project grows.*
+
+### 03-logs/ -- What changed over time
+
+| File | What's in it |
+|------|-------------|
+| [decisions-log.md](03-logs/decisions-log.md) | Settled design decisions with rationale (don't re-debate these) |
+| [implementation-log.md](03-logs/implementation-log.md) | What changed per version (summary of CHANGELOG) |
+| [bug-log.md](03-logs/bug-log.md) | Bugs: symptom, root cause, fix, regression test |
+| [validation-log.md](03-logs/validation-log.md) | Test suite results, site validation matrix, token reduction measurements |
+| [insights.md](03-logs/insights.md) | Lessons learned, repos studied, technical patterns |
+
+### 04-process/ -- How to work with this system
+
+| File | What's in it |
+|------|-------------|
+| [dev-workflow.md](04-process/dev-workflow.md) | Dev rules, dependency hierarchy, running tests, environment setup |
+| [definition-of-done.md](04-process/definition-of-done.md) | Checklist: when is a feature/fix actually done |
+| [testing.md](04-process/testing.md) | Test pyramid, all 64 tests documented, writing new tests, CI strategy |
+
+### archive/ -- Historical docs
+
+| File | Why archived |
+|------|-------------|
+| [poc-plan.md](archive/poc-plan.md) | All 4 POC phases completed. Useful bits migrated to system-state.md and testing.md. |
+
+## Also at project root
+
+| File | Purpose |
+|------|---------|
+| `README.md` | Public-facing project overview |
+| `barebrowse.context.md` | LLM-consumable integration guide (full API, gotchas, wiring) |
+| `.claude/skills/barebrowse/SKILL.md` | CLI command reference + Claude Code skill definition |
+| `CHANGELOG.md` | Detailed version-by-version changelog |
+| `CLAUDE.md` | AI agent instructions for this project |

package/docs/archive/poc-plan.md

@@ -0,0 +1,230 @@
+# barebrowse — POC Plan
+
+**Date:** 2026-02-22
+**Goal:** Prove that an autonomous agent can get an authenticated, pruned ARIA snapshot of any web page via CDP — no Playwright, no bundled browser.
+
+---
+
+## Repo Structure
+
+```
+barebrowse/
+├── src/
+│   ├── index.js          # Public API: browse(), connect()
+│   ├── chromium.js        # Find/launch/connect to Chromium browsers
+│   ├── cdp.js             # Vanilla WebSocket CDP client
+│   ├── aria.js            # Accessibility.getFullAXTree → structured tree
+│   ├── auth.js            # Cookie extraction + CDP Network.setCookie injection
+│   ├── prune.js           # ARIA tree pruning (ported from mcprune)
+│   ├── interact.js        # Click, type, scroll via CDP Input domain
+│   ├── consent.js         # Auto-dismiss cookie consent dialogs
+│   └── stealth.js         # Anti-detection patches via Runtime.evaluate (Phase 4)
+├── test/
+│   ├── integration/
+│   │   ├── browse.test.js     # End-to-end: URL → pruned snapshot
+│   │   ├── auth.test.js       # Cookie injection → authenticated page
+│   │   └── interact.test.js   # Click/type on a live page
+│   └── unit/
+│       ├── cdp.test.js        # CDP client message handling
+│       ├── aria.test.js       # ARIA tree formatting
+│       └── prune.test.js      # Pruning logic on sample trees
+├── docs/
+│   ├── prd.md             # Product requirements (comprehensive)
+│   └── poc-plan.md        # This file
+├── package.json
+└── CLAUDE.md
+```
+
+**No build step.** Vanilla JS, ES modules, runs directly with Node.js >= 22.
+
+---
+
+## Phases
+
+### Phase 1 — CDP + ARIA Foundation
+
+**Prove:** Get an ARIA tree from any page via CDP, no Playwright.
+
+**Files:**
+- `src/chromium.js` — Find installed Chromium browsers on the system (Chrome, Chromium, Brave, Edge). Launch headless with `--headless=new --remote-debugging-port=<port>`. Parse CDP WebSocket URL from stderr output.
+- `src/cdp.js` — Vanilla WebSocket client that speaks CDP. Send JSON commands, receive responses and events. Handle command IDs, promises, event subscriptions. ~100 lines.
+- `src/aria.js` — Call `Accessibility.getFullAXTree` via CDP. Transform the raw CDP response (flat array of AXNodes with parentId references) into a nested tree structure. Format as readable output.
+- `src/index.js` — Wire chromium → cdp → aria into `browse(url)` function. Minimal, just the pipeline.
+
+**Test:**
+```bash
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://example.com'))"
+```
+
+**DoD:**
+- [x] `chromium.js` finds and launches at least one Chromium browser on Fedora Linux
+- [x] `cdp.js` connects via WebSocket, sends commands, receives responses
+- [x] `aria.js` returns a structured ARIA tree for any public page
+- [x] `browse(url)` works end-to-end with zero external dependencies
+- [x] Headless Chrome process is cleaned up on close
+
+### Phase 2 — Auth + Prune
+
+**Prove:** Authenticated, pruned ARIA snapshot of a Cloudflare-protected page.
+
+**Files:**
+- `src/auth.js` — Extract cookies from user's browser profile (use sweet-cookie or implement minimal extraction from Chrome's Cookies SQLite DB + Linux keyring decryption via `secret-tool`). Inject via CDP `Network.setCookie` before navigation.
+- `src/prune.js` — Port mcprune's pruning logic as a pure function. Input: raw ARIA tree. Output: pruned ARIA tree. Role-based: keep landmarks + interactive elements, drop noise/structural wrappers.
+- Update `src/index.js` — Add cookie injection and pruning to the `browse()` pipeline.
+
+**Test:**
+```bash
+# Should return authenticated content, not a login wall or CF challenge
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://some-cf-protected-site.com'))"
+```
+
+**DoD:**
+- [x] `auth.js` extracts cookies from Firefox profile on Linux (also supports Chromium when installed)
+- [x] Cookies injected via CDP before navigation
+- [ ] CF-protected page returns real content, not challenge page (needs active session to test)
+- [x] `prune.js` reduces ARIA tree by 47%+ on HN (minimal site — heavier sites will see 70%+)
+- [x] Pruned output preserves all interactive elements and landmarks
+- [x] `browse(url)` returns pruned, authenticated snapshot by default
+
+### Phase 3 — Headed Mode + Interaction
+
+**Prove:** Connect to user's running browser and interact with a logged-in page.
+
+**Files:**
+- Update `src/chromium.js` — Add `connect()` mode: connect to an already-running browser's debug port instead of launching a new one. Detect running browsers with debug ports.
+- `src/interact.js` — Click (`Input.dispatchMouseEvent`), type (`Input.dispatchKeyEvent`), scroll. Resolve ARIA node IDs to DOM coordinates for click targets.
+- Update `src/index.js` — Add `connect()` export for long-lived sessions. Add `mode: 'headed'` option.
+
+**Prerequisite:** User must launch their browser with `--remote-debugging-port=9222` flag.
+
+**Test:**
+```bash
+# User has Chrome open with debug port, logged into GitHub
+node -e "
+  import { connect } from './src/index.js';
+  const page = await connect({ mode: 'headed' });
+  await page.goto('https://github.com/notifications');
+  console.log(await page.snapshot());
+"
+```
+
+**DoD:**
+- [x] `connect()` attaches to a running Chromium browser via CDP
+- [x] Same ARIA + prune pipeline works on headed browser
+- [x] `click()` and `type()` send real input events via CDP
+- [x] `press()` sends special keys (Enter, Tab, Escape, arrows) — triggers form submit
+- [x] `scrollIntoView` before click ensures off-screen elements are reachable
+- [x] `type({ clear: true })` replaces pre-filled input content
+- [x] `waitForNavigation()` waits for page load after link clicks
+- [x] Interactions tested against real sites: Wikipedia, GitHub, Google, Hacker News, DuckDuckGo, YouTube
+- [x] Browser stays open after barebrowse disconnects
+- [x] Cookie injection via `page.injectCookies()` for headed mode (Firefox → Chromium)
+- [x] Permission prompts suppressed via launch flags + CDP `Browser.setPermission`
+- [x] Cookie consent dialogs auto-dismissed across 16+ sites in 7 languages
+- [x] YouTube end-to-end: Firefox cookies → search → click → video playback in headed mode
+
+### Phase 4 — Hybrid + bareagent Integration
+
+**Prove:** Agent autonomously browses the web using barebrowse tools.
+
+**Files:**
+- Update `src/chromium.js` — Add `mode: 'hybrid'`. Try headless first. If navigation returns a CF challenge or 403, automatically retry in headed mode.
+- `src/stealth.js` — Basic anti-detection: patch `navigator.webdriver`, `navigator.plugins`, `window.chrome`. Applied via `Runtime.evaluate` on new page.
+- Update `src/index.js` — Final API surface: `browse()`, `connect()`.
+
+**Test:**
+```js
+import { Loop } from 'bare-agent';
+import { browse } from './src/index.js';
+
+const tools = [
+  { name: 'browse', execute: ({ url }) => browse(url) },
+];
+
+const loop = new Loop({ provider });
+await loop.run([
+  { role: 'user', content: 'Go to hacker news and tell me the top 3 stories' }
+], tools);
+```
+
+**DoD:**
+- [ ] Hybrid mode automatically falls back when headless is blocked
+- [ ] Stealth patches reduce headless detection on common sites
+- [ ] bareagent can use `browse()` as a tool in its think/act/observe loop
+- [ ] Agent successfully completes a multi-page research task autonomously
+
+---
+
+## Definition of Done — Full POC
+
+The POC is complete when ALL of these are true:
+
+1. **`browse(url)` works end-to-end** — URL in, pruned ARIA snapshot out, authenticated as the user
+2. **Zero heavy deps** — no Playwright, no Puppeteer. Only deps: `ws` (WebSocket client, if Node's built-in isn't sufficient) and optionally `sweet-cookie`
+3. **Three modes work** — headless (default), headed (connect to running browser), hybrid (auto-fallback)
+4. **Works on Fedora Linux** — finds Chrome/Chromium/Brave, launches headless, connects headed
+5. **Token-efficient output** — pruned ARIA tree is 70%+ smaller than raw tree
+6. **Clean process management** — headless browser spawned and killed cleanly, no orphan processes
+7. **Under 1,000 lines total** for core src/ (excluding tests)
+8. **Documented** — PRD captures all decisions, this file captures all phases
+
+## What the POC is NOT
+
+- Not production-ready. No error recovery, no retry logic, no edge case handling beyond happy path.
+- Not cross-platform tested. Linux first (Fedora). macOS/Windows later.
+- Not an MCP server. That's a future wrapper.
+- Not a published npm package. Local development only.
+
+---
+
+## Running Tests
+
+```bash
+# All tests (47+ tests)
+node --test test/unit/*.test.js test/integration/*.test.js
+
+# Unit tests only (fast, no network)
+node --test test/unit/prune.test.js    # 16 tests — pruning logic
+node --test test/unit/auth.test.js     # 7 tests — cookie extraction (2 fail when Chromium locked)
+node --test test/unit/cdp.test.js      # 5 tests — CDP client + browser launch
+
+# Integration tests (needs network + Chromium)
+node --test test/integration/browse.test.js    # 11 tests — end-to-end pipeline
+node --test test/integration/interact.test.js  # 15 tests — interactions on real sites
+
+# Quick smoke test
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://example.com'))"
+
+# Headed mode demos (requires: chromium-browser --remote-debugging-port=9222)
+node examples/headed-demo.js    # Wikipedia → DuckDuckGo search
+node examples/yt-demo.js        # YouTube: Firefox cookies → search → play video
+```
+
+---
+
+## Repos Studied — What We Borrowed vs Built
+
+| steipete repo | What we studied | What we used | Why not more |
+|---|---|---|---|
+| **sweet-cookie** | Cookie extraction (SQLite + keyring) | **Concept only** — wrote `auth.js` ourselves | Not on npm (different package). Our version is simpler, tailored, vanilla JS |
+| **sweetlink** | CDP dual-channel, selector discovery, daemon | **CDP-direct concept only** | Daemon + WebSocket bridge + in-page runtime = bloat. CDP direct is 100 lines vs ~2,000 |
+| **canvas** | Stealth/anti-detection patterns | **Noted for Phase 4** `stealth.js` | Not needed yet — headless + real cookies handles most cases |
+| **mcprune (own)** | ARIA pruning pipeline | **Full port** — `prune.js` (472 lines) | Proven code, adapted node format from Playwright YAML to CDP tree objects |
+
+### What to explore in later phases
+
+- **Selector discovery** (sweetlink) — crawl ARIA tree, score interactive elements, rank action targets. Phase 3/4.
+- **Stealth patches** (canvas) — `navigator.webdriver`, plugins, chrome object spoofing. Phase 4.
+- **In-page JS execution** (sweetlink) — `Runtime.evaluate` for complex interactions. Phase 3.
+- **Screenshot + visual grounding** — `Page.captureScreenshot` for multimodal agents. Post-POC.
+
+---
+
+## Dev Rules (from AGENT_RULES.md)
+
+- **Vanilla JS only.** No TypeScript, no build step, no transpilation.
+- **Dependency hierarchy:** vanilla → stdlib → external. Write it yourself if <50 lines.
+- **Simple > clever.** Readable code a junior can follow.
+- **POC first.** Validate logic before designing. Never ship the POC — rewrite it.
+- **Test behavior, not implementation.** Integration tests over unit tests.
+- **No speculative code.** Every line must have a purpose.

package/mcp-server.js

@@ -149,7 +149,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.2.1' },
+      serverInfo: { name: 'barebrowse', version: '0.2.2' },
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",

package/src/aria.js

@@ -20,7 +20,7 @@ export function formatTree(node, depth = 0) {
 
   // Skip ignored nodes but still process their children
   if (node.ignored) {
-    return node.children.map((c) => formatTree(c, depth)).join('');
+    return node.children.map((c) => formatTree(c, depth)).filter(Boolean).join('\n');
   }
 
   // Skip low-level rendering nodes that are noise for agents