barebrowse 0.5.1 → 0.5.2

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

@@ -1,269 +0,0 @@
-# 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.
-
----
-
-## New features manual validation (v0.4.0)
-
-All tested against live sites via CLI session from `/tmp`.
-
-### Navigation: back/forward
-
-| Command | Result |
-|---------|--------|
-| `open https://example.com` | Session started |
-| `goto https://wikipedia.org` | "ok" |
-| `back` | "ok" — returned to example.com |
-| `forward` | "ok" — returned to wikipedia.org |
-
-### File upload
-
-| Command | Result |
-|---------|--------|
-| `goto 'data:text/html,<input type="file" id="f"><script>...</script>'` | "ok" |
-| `snapshot` | `button "Choose File" [ref=7]` |
-| `upload 7 /tmp/test-upload.txt` | "ok" |
-| `eval 'document.title'` | `"uploaded"` — onchange fired, confirmed working |
-
-### PDF export
-
-| Command | Result |
-|---------|--------|
-| (on wikipedia.org) `pdf` | `.barebrowse/page-*.pdf` — 200,716 bytes |
-
-### Tabs
-
-| Command | Result |
-|---------|--------|
-| `tabs` | `[{"index":0,"url":"https://www.wikipedia.org/","title":"Wikipedia",...}, {"index":1,"url":"about:blank",...}]` |
-
-### Wait-for
-
-| Command | Result |
-|---------|--------|
-| `wait-for --text=Wikipedia` | "ok" — found text immediately |
-| `wait-for --selector=body` | "ok" — found selector immediately |
-
-### JS dialog auto-dismiss
-
-| Command | Result |
-|---------|--------|
-| `eval 'alert("hello from dialog"); "done"'` | `"done"` — alert auto-dismissed, eval continued |
-| `dialog-log` | `.barebrowse/dialogs-*.json (1 entries)` — dialog logged with type, message, timestamp |
-
-### Save state
-
-| Command | Result |
-|---------|--------|
-| `save-state` | `.barebrowse/state-*.json` — 2,836 bytes (cookies + localStorage) |
-
-### Viewport flag
-
-| Command | Result |
-|---------|--------|
-| `open https://example.com --viewport=800x600` | Session started |
-| `eval 'window.innerWidth + "x" + window.innerHeight'` | `"800x600"` — confirmed |
-
-### Drag (wired, needs drag-and-drop UI for visual test)
-
-Wired through interact.js → index.js → daemon.js → cli.js. Mouse event sequence: mousePressed at source → mouseMoved to midpoint → mouseMoved to target → mouseReleased at target. Requires a drag-and-drop UI to validate visually.
-
-### Proxy flag
-
-Wired through cli.js → daemon.js → chromium.js → `--proxy-server` Chromium launch arg. Requires a proxy server to validate.
-
-### Storage-state flag
-
-Wired through cli.js → daemon.js → connect() → `Network.setCookies` on startup. Loads from JSON file produced by `save-state`.
-
----
-
-## MCP server validation (v0.4.1)
-
-All 12 MCP tools tested live via Claude Code MCP integration. Stats line (`# X chars → Y chars (N% pruned)`) confirmed on every snapshot.
-
-### Tools tested successfully (10/12)
-
-| Tool | Test | Result |
-|------|------|--------|
-| `browse` | One-shot HN | `51,397 → 26,983 (48% pruned)` — stats line present |
-| `goto` | DDG, Wikipedia, data: URLs | All navigated successfully |
-| `snapshot` | Multiple pages | Stats line on every snapshot, pruning working |
-| `click` | Wikipedia "About Wikipedia" link | Navigated to target page |
-| `type` | DDG search box `barebrowse npm` | Text entered correctly |
-| `press` | Enter to submit DDG search | Search submitted (CAPTCHA returned — expected headless) |
-| `scroll` | 500px down on Wikipedia:About | Scrolled successfully |
-| `back` | After Wikipedia:About → CDP page | Returned to previous page |
-| `forward` | After back | Returned to Wikipedia:About |
-| `pdf` | Wikipedia:About | 380K base64 PDF generated |
-
-### Tools tested with known limitations (2/12)
-
-| Tool | Test | Result |
-|------|------|--------|
-| `upload` | data: page with file input | `ok` returned, file set via DOM.setFileInputFiles. onchange fires but result text pruned in act mode (non-interactive content). Works in integration tests. |
-| `drag` | data: page with draggable divs | Mouse events dispatched but HTML5 drag/drop dataTransfer not populated via CDP synthetic events. Known CDP limitation (same as Playwright). |
-
-### Observations
-
-- DDG returned CAPTCHA in headless ("Select all squares containing a duck") — expected, hybrid mode handles this
-- Stats line format: `# 42,367 chars → 5,453 chars (87% pruned)` — present on all pruned snapshots
-- Token reduction ranges observed: 37% (Wikipedia) to 88% (example.com)
-
----
-
-## MCP cookies + hybrid fallback validation (v0.4.2)
-
-Three changes tested: all-browser cookie merge in auth.js, hybrid mode for connect(), cookie injection + hybrid in MCP goto.
-
-### Cookie injection — login-walled sites via MCP goto
-
-| Site | Logged In? | Details |
-|------|-----------|---------|
-| **Gmail** | Yes | Full inbox visible: Compose, labels, 4 emails. Required domain-stripping fix (`mail.google.com` → `google.com`) to capture parent-domain cookies (SID, HSID, etc.). 47 cookies merged from Firefox + Chromium. |
-| **YouTube** | Yes | Personalized feed: tabs for Linux, AI, Electrical Engineering. Recommendations include Claude Code videos, KDE Plasma. Account buttons visible. |
-| **LinkedIn** | Yes | Full feed as Amr Hassan: Home, My Network, Jobs, Messaging, Notifications. Posts visible. Stealth patches + cookies bypassed LinkedIn's aggressive bot detection. |
-| **Amazon.nl** | No (expected) | Not logged in but consent dismissed, search + product pages worked. Cookie injection had no effect (no Amazon session in Firefox). |
-| **GitHub** | No | Shows generic homepage with "Sign in". No GitHub session cookies in Firefox. |
-
-### Bot detection — hybrid fallback
-
-| Site | Headless Result | Hybrid Fallback | Final Result |
-|------|----------------|-----------------|--------------|
-| **Google Search** | Full results, no CAPTCHA | Not triggered (stealth sufficient) | Pass — logged in as Amr Hassan |
-| **Reddit** | "Prove your humanity" + reCAPTCHA | Triggered → connected to headed Chromium on 9222 | Pass — full feed with posts, logged in |
-| **LinkedIn** | Loaded fine with stealth + cookies | Not triggered | Pass |
-
-### Bug fixes discovered during validation
-
-1. **Domain stripping in authenticate()**: `mail.google.com` extracted only 9 cookies (subdomain-specific). Fix: strip to registrable domain (`google.com`) → 47 cookies including all auth cookies (SID, HSID, SSID, APISID, SAPISID).
-2. **Reddit challenge detection**: Block page shows "Prove your humanity" and "File a ticket" — neither matched existing challenge phrases. Added both to `isChallengePage()`.
-
-### connect() hybrid mode
-
-Tested `connect({ mode: 'hybrid' })` with Reddit: headless detected challenge → killed browser → connected to headed Chromium → Reddit loaded with full content. Same code path as MCP session.
-
-### All-browser cookie merge
-
-`extractCookies({ domain: 'google.com' })` in auto mode: Chromium cookies merged first, then Firefox cookies (last-write-wins by `name@domain`). 47 cookies total for google.com. Previous behavior: stopped at first browser found (Chromium only, missed Firefox session).
-
----
-
-*Add new validation entries when testing against new sites or features.*

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

@@ -1,31 +0,0 @@
-# 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

@@ -1,68 +0,0 @@
-# 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/04-process/testing.md

@@ -1,242 +0,0 @@
-# barebrowse -- Testing Guide
-
-## Run all tests
-
-```bash
-node --test test/unit/*.test.js test/integration/*.test.js
-```
-
-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 \     21 tests — browse/connect pipeline + CLI session lifecycle
-       /----------------\
-      /      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 |
-
-### `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)
-
-### `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 |
-
----
-
-## Manual validation (v0.4.0 features)
-
-Features added in v0.4.0 are manually validated but not yet in the automated test suite. See `docs/03-logs/validation-log.md` for full results.
-
-| Feature | Validation method | Result |
-|---------|-------------------|--------|
-| `back` / `forward` | example.com → wikipedia → back → forward | ok |
-| `upload <ref> <files..>` | data: URL with file input, verified onchange fired | ok |
-| `pdf` | Wikipedia export, 200KB PDF | ok |
-| `tabs` | Listed 2 tabs with urls/titles | ok |
-| `wait-for --text` | Found "Wikipedia" text | ok |
-| `wait-for --selector` | Found `body` selector | ok |
-| `dialog-log` | alert() auto-dismissed, 1 entry logged | ok |
-| `save-state` | 2.8KB cookies + localStorage JSON | ok |
-| `--viewport=WxH` | 800x600, confirmed via innerWidth/innerHeight | ok |
-| `drag` | Wired through all layers, needs drag UI to visually test |
-| `--proxy` | Wired to Chromium launch arg, needs proxy to test |
-| `--storage-state` | Wired to Network.setCookies, loads from save-state output |
-
----
-
-## 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/docs/README.md

@@ -1,56 +0,0 @@
-# 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) |
-| `commands/barebrowse.md` | CLI command reference for any agent (same as SKILL.md without frontmatter) |
-| `commands/barebrowse/SKILL.md` | CLI command reference for Claude Code (copy to `.claude/skills/`) |
-| `CHANGELOG.md` | Detailed version-by-version changelog |
-| `CLAUDE.md` | AI agent instructions for this project |