barebrowse 0.10.1 → 0.12.0

package/types/consent.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Try to dismiss a cookie consent dialog on the current page.
+ * Inspects the ARIA tree for dialog elements with consent-related content,
+ * then clicks the "accept" button.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @returns {Promise<boolean>} true if a consent dialog was dismissed
+ */
+export function dismissConsent(session: object): Promise<boolean>;

package/types/daemon.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Spawn a detached child process that runs the daemon.
+ * Parent polls for session.json, then exits.
+ */
+export function startDaemon(opts: any, outputDir: any, initialUrl: any): Promise<any>;
+/**
+ * Run the daemon HTTP server. Called by cli.js --daemon-internal.
+ * Holds a connect() session and serves commands over HTTP.
+ */
+export function runDaemon(opts: any, outputDir: any, initialUrl: any): Promise<void>;

package/types/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Browse a URL and return an ARIA snapshot.
+ * This is the primary API — URL in, agent-ready snapshot out.
+ *
+ * @param {string} url - The URL to browse
+ * @param {object} [opts]
+ * @param {'headless'|'headed'|'hybrid'} [opts.mode='headless'] - Browser mode
+ * @param {boolean} [opts.cookies=true] - Inject user's cookies (Phase 2)
+ * @param {boolean} [opts.prune=true] - Apply ARIA pruning (Phase 2)
+ * @param {number} [opts.timeout=30000] - Navigation timeout in ms
+ * @param {boolean} [opts.blockAds=true] - Block ~120 common ad/tracker
+ *   URL patterns via CDP. Shrinks ARIA snapshots and speeds page loads.
+ *   See src/blocklist.js for the default set. Set false to disable.
+ * @param {string[]} [opts.blockUrls] - Extra URL glob patterns to block,
+ *   merged with the default unless blockAds:false.
+ * @param {boolean} [opts.allowLocalUrls=false] - Permit navigation to local-
+ *   resource schemes (file:, view-source:, chrome:, …). Blocked by default.
+ * @param {boolean} [opts.blockPrivateNetwork=false] - Reject navigation to
+ *   loopback / RFC-1918 / link-local / cloud-metadata hosts (SSRF guard).
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port').
+ * @param {string} [opts.binary] - Path to browser binary (auto-detected if omitted).
+ * @param {string} [opts.userDataDir] - Browser profile directory.
+ * @param {{width: number, height: number}} [opts.viewport] - Viewport dimensions.
+ * @param {string} [opts.browser] - Source browser for cookie extraction.
+ * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
+ * @returns {Promise<string>} ARIA snapshot text
+ */
+export function browse(url: string, opts?: {
+    mode?: "headless" | "headed" | "hybrid" | undefined;
+    cookies?: boolean | undefined;
+    prune?: boolean | undefined;
+    timeout?: number | undefined;
+    blockAds?: boolean | undefined;
+    blockUrls?: string[] | undefined;
+    allowLocalUrls?: boolean | undefined;
+    blockPrivateNetwork?: boolean | undefined;
+    proxy?: string | undefined;
+    binary?: string | undefined;
+    userDataDir?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    browser?: string | undefined;
+    consent?: boolean | undefined;
+    pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
+}): Promise<string>;
+/**
+ * Connect to a browser for a long-lived interactive session.
+ *
+ * @param {object} [opts]
+ * @param {'headless'|'headed'|'hybrid'} [opts.mode='headless'] - Browser mode
+ * @param {number} [opts.port] - Attach to an already-running Chromium at this
+ *   CDP port instead of launching a new one. The browser keeps running on
+ *   close(); only the tab we created is torn down. Use this to drive a
+ *   user's logged-in session (start Chromium with --remote-debugging-port=N).
+ * @param {string} [opts.downloadPath] - Directory to save downloaded files.
+ *   Default: a per-session subdirectory under the OS temp dir. Downloads
+ *   land here as <guid>; check `page.downloads` for { url, suggestedFilename,
+ *   savedPath, state, totalBytes, receivedBytes } per file.
+ * @param {boolean} [opts.blockAds] - Block ~120 common ad/tracker URL
+ *   patterns via CDP. Defaults to true for launched browsers, false in
+ *   attach mode (would affect any tab attached to the user's running
+ *   session). Setting blockAds:true explicitly in attach mode honors the
+ *   request — blocking applies to whichever tab the session is currently
+ *   attached to and follows the session across switchTab() until close.
+ * @param {string[]} [opts.blockUrls] - Extra URL glob patterns to block,
+ *   merged with the default unless blockAds is false.
+ * @param {boolean} [opts.allowLocalUrls=false] - Permit navigation to local-
+ *   resource schemes (file:, view-source:, chrome:, …). Blocked by default
+ *   because a prompt-injected agent could use them to read local files.
+ * @param {boolean} [opts.blockPrivateNetwork=false] - Reject navigation to
+ *   loopback / RFC-1918 / link-local / cloud-metadata hosts (SSRF guard).
+ *   Off by default so localhost dev-server browsing keeps working.
+ * @param {string} [opts.uploadDir] - When set, upload() rejects any file that
+ *   does not resolve (symlinks included) inside this directory. Sandboxes the
+ *   agent's file-upload capability. Default: no restriction.
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port').
+ * @param {string} [opts.binary] - Path to browser binary (auto-detected if omitted).
+ * @param {string} [opts.userDataDir] - Browser profile directory.
+ * @param {{width: number, height: number}} [opts.viewport] - Viewport dimensions.
+ * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
+ * @param {string} [opts.storageState] - Path to a storage-state JSON file
+ *   (cookies + localStorage) to load before navigation.
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
+ * @returns {Promise<object>} Page handle with goto, snapshot, close
+ */
+export function connect(opts?: {
+    mode?: "headless" | "headed" | "hybrid" | undefined;
+    port?: number | undefined;
+    downloadPath?: string | undefined;
+    blockAds?: boolean | undefined;
+    blockUrls?: string[] | undefined;
+    allowLocalUrls?: boolean | undefined;
+    blockPrivateNetwork?: boolean | undefined;
+    uploadDir?: string | undefined;
+    proxy?: string | undefined;
+    binary?: string | undefined;
+    userDataDir?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    consent?: boolean | undefined;
+    storageState?: string | undefined;
+    pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
+}): Promise<object>;
+/**
+ * Apply Network.setBlockedURLs for ad/tracker blocking on a session.
+ * Default list is on; pass blockAds:false to skip, blockUrls:[] to extend.
+ * On failure (legacy Chrome lacking the method) warns once and continues —
+ * blocking is an enhancement, not a hard requirement.
+ *
+ * Exported for unit testing of the warn-once behavior; not part of the public
+ * API surface.
+ */
+export function applyBlocklist(session: any, pageOpts: any): Promise<void>;
+/** Test-only: reset the warn-once flag. Not part of the public API. */
+export function _resetBlocklistWarning(): void;
+/**
+ * Detect if a page is a bot-challenge page (Cloudflare, hCaptcha, etc.).
+ *
+ * Pre-H9 this was over-aggressive: `nodeCount < 50` alone fired on any
+ * legitimate small page (404s, simple landings, error pages), and generic
+ * phrases like "access denied" / "unknown error" / "permission denied"
+ * triggered on real HTTP 4xx/5xx pages, kicking hybrid mode into a costly
+ * headed fallback for nothing.
+ *
+ * H9 split: STRONG_PHRASES are essentially-unambiguous challenge UI and
+ * fire regardless of page size; WEAK_PHRASES only fire when the page is
+ * ALSO tiny (so a legitimate-looking error page with "access denied" in
+ * its body doesn't trip the fallback).
+ *
+ * @param {object} tree - Nested ARIA tree (from buildTree)
+ * @param {number} [nodeCount] - Raw CDP node count (from Accessibility.getFullAXTree)
+ */
+export function isChallengePage(tree: object, nodeCount?: number): boolean;

package/types/interact.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Click an element by its backendDOMNodeId.
+ * Scrolls into view, resolves coordinates, then dispatches mousePressed + mouseReleased.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID
+ */
+export function click(session: object, backendNodeId: number): Promise<void>;
+/**
+ * Type text into an element by its backendDOMNodeId.
+ * Default: DOM.focus + Input.insertText (fast, no key events).
+ * With { keyEvents: true }: dispatches keyDown/keyUp per character (triggers handlers).
+ * With { clear: true }: selects all existing text and deletes it before typing.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID
+ * @param {string} text - Text to type
+ * @param {object} [opts]
+ * @param {boolean} [opts.keyEvents=false] - Use char-by-char key events
+ * @param {boolean} [opts.clear=false] - Clear existing content before typing
+ */
+export function type(session: object, backendNodeId: number, text: string, opts?: {
+    keyEvents?: boolean | undefined;
+    clear?: boolean | undefined;
+}): Promise<void>;
+/**
+ * Press a special key (Enter, Tab, Escape, etc.).
+ * Dispatches keyDown + keyUp for the named key.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {string} key - Key name (e.g. 'Enter', 'Tab', 'Escape', 'ArrowDown')
+ */
+export function press(session: object, key: string): Promise<void>;
+/**
+ * Scroll the page via mouseWheel event.
+ * Dispatches at viewport center by default, or at given coordinates.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} deltaY - Pixels to scroll (positive = down, negative = up)
+ * @param {number} [x=400] - X coordinate for scroll event
+ * @param {number} [y=300] - Y coordinate for scroll event
+ */
+export function scroll(session: object, deltaY: number, x?: number, y?: number): Promise<void>;
+/**
+ * Hover over an element by its backendDOMNodeId.
+ * Scrolls into view, then dispatches mouseMoved at center.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID
+ */
+export function hover(session: object, backendNodeId: number): Promise<void>;
+/**
+ * Select a value in a <select> element or custom dropdown.
+ *
+ * Strategy 1: Native <select> — set .value + dispatch 'change' event.
+ * Strategy 2: Custom dropdown — click to open, find matching option, click it.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID of the select/combobox
+ * @param {string} value - Value or visible text to select
+ */
+export function select(session: object, backendNodeId: number, value: string): Promise<void>;
+/**
+ * Drag one element to another.
+ * Scrolls source into view, mouse down, move to target center, mouse up.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} fromNodeId - Source element backendDOMNodeId
+ * @param {number} toNodeId - Target element backendDOMNodeId
+ */
+export function drag(session: object, fromNodeId: number, toNodeId: number): Promise<void>;
+/**
+ * Upload files to a file input element.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID of the file input
+ * @param {string[]} files - Absolute paths to files to upload
+ */
+export function upload(session: object, backendNodeId: number, files: string[]): Promise<void>;

package/types/network-idle.d.ts

@@ -0,0 +1,19 @@
+/**
+ * network-idle.js — wait until the page's network has been idle for N ms.
+ *
+ * Tracks in-flight requests by requestId in a Set, so an orphan
+ * loadingFinished/Failed (event for a request whose requestWillBeSent
+ * arrived before our listener attached) is a harmless no-op instead of
+ * driving a counter negative and resolving prematurely.
+ */
+/**
+ * @param {object} session - CDP session-scoped handle with .on() returning unsub
+ * @param {object} [opts]
+ * @param {number} [opts.timeout=30000] - Max wait time before reject
+ * @param {number} [opts.idle=500] - Required idle duration before resolve
+ * @returns {Promise<void>}
+ */
+export function waitForNetworkIdle(session: object, opts?: {
+    timeout?: number | undefined;
+    idle?: number | undefined;
+}): Promise<void>;

package/types/prune.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Prune an ARIA tree for agent consumption.
+ *
+ * @param {object} tree - Root node from buildTree() (CDP format)
+ * @param {object} [options]
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
+ * @param {string} [options.context=''] - Search context for relevance filtering
+ * @returns {object|null} Pruned tree
+ */
+export function prune(tree: object, options?: {
+    mode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
+    context?: string | undefined;
+}): object | null;

package/types/session-client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Read session.json from the output directory.
+ * @returns {{ port: number, pid: number, token?: string, startedAt: string } | null}
+ */
+export function readSession(outputDir: any): {
+    port: number;
+    pid: number;
+    token?: string;
+    startedAt: string;
+} | null;
+/**
+ * Check if the daemon is alive by hitting GET /status.
+ */
+export function isAlive(outputDir: any): Promise<boolean>;
+/**
+ * Send a command to the running daemon.
+ * @returns {Promise<object>} The daemon's response
+ */
+export function sendCommand(command: any, args: any, outputDir: any): Promise<object>;

package/types/stealth.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Apply stealth patches to a CDP session.
+ * Must be called before any navigation.
+ *
+ * Splits into two layers:
+ *   1. Network.setUserAgentOverride strips "HeadlessChrome" from the UA
+ *      that ships in HTTP request headers AND that navigator.userAgent
+ *      reports — `--headless=new` leaves "HeadlessChrome" in there.
+ *   2. Page.addScriptToEvaluateOnNewDocument injects the JS-level patches
+ *      before any page script runs.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ */
+export function applyStealth(session: object): Promise<void>;

package/types/url-guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Throw if `url` is unsafe to navigate to under the given policy.
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowLocalUrls=false] - permit file:/chrome:/etc.
+ * @param {boolean} [opts.blockPrivateNetwork=false] - reject loopback/RFC-1918/metadata.
+ */
+export function assertNavigable(url: string, opts?: {
+    allowLocalUrls?: boolean | undefined;
+    blockPrivateNetwork?: boolean | undefined;
+}): void;
+/**
+ * Throw if any file in `files` resolves outside `uploadDir`. Both the base
+ * dir and each file are resolved through realpath, so symlinks (in either the
+ * base path — e.g. macOS /tmp → /private/tmp — or the file) can't be used to
+ * escape the sandbox or to false-reject a legitimate file.
+ * No-op when `uploadDir` is falsy (no restriction configured).
+ * @param {string|string[]} files
+ * @param {string|null} uploadDir
+ */
+export function assertUploadAllowed(files: string | string[], uploadDir: string | null): void;
+/**
+ * @param {string} host - hostname (no brackets for IPv6)
+ * @returns {boolean} true if it names a private/loopback/link-local/internal host
+ */
+export function isPrivateHost(host: string): boolean;

package/commands/barebrowse/SKILL.md

@@ -1,133 +0,0 @@
----
-name: barebrowse
-description: Browser automation using the user's real browser with real cookies. Handles consent walls, login sessions, and bot detection automatically.
-allowed-tools: Bash(barebrowse:*)
----
-
-# barebrowse CLI — Browser Automation for Agents
-
-Browse any URL using the user's real browser with real cookies. Returns pruned ARIA snapshots (40-90% smaller than raw) with `[ref=N]` markers for interaction. Handles cookie consent, login sessions, JS dialogs, and bot detection automatically.
-
-## Quick Start
-
-```bash
-barebrowse open https://example.com    # Start session + navigate
-barebrowse snapshot                    # Get ARIA snapshot → .barebrowse/page-*.yml
-barebrowse click 8                     # Click element with ref=8
-barebrowse snapshot                    # See result
-barebrowse close                       # End session
-```
-
-All output files go to `.barebrowse/` in the current directory. Read them with the Read tool when needed.
-
-## Commands
-
-### Session Lifecycle
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse open [url] [flags]` | Start browser session. Optionally navigate to URL. |
-| `barebrowse close` | Close session and kill browser. |
-| `barebrowse status` | Check if session is running. |
-
-**Open flags:**
-- `--mode=headless|headed|hybrid` — Browser mode (default: headless)
-- `--no-cookies` — Skip cookie injection
-- `--browser=firefox|chromium` — Cookie source
-- `--prune-mode=act|read` — Default pruning mode
-- `--timeout=N` — Navigation timeout in ms
-- `--proxy=URL` — HTTP/SOCKS proxy server
-- `--viewport=WxH` — Viewport size (e.g. 1280x720)
-- `--storage-state=FILE` — Load cookies/localStorage from JSON file
-
-### Navigation
-
-| Command | Output |
-|---------|--------|
-| `barebrowse goto <url>` | Navigates, waits for load, dismisses consent. Prints "ok". |
-| `barebrowse back` | Go back in browser history. |
-| `barebrowse forward` | Go forward in browser history. |
-| `barebrowse snapshot` | ARIA snapshot → `.barebrowse/page-<timestamp>.yml` |
-| `barebrowse snapshot --mode=read` | Read mode: keeps all text (for content extraction) |
-| `barebrowse screenshot` | Screenshot → `.barebrowse/screenshot-<timestamp>.png` |
-| `barebrowse pdf [--landscape]` | PDF export → `.barebrowse/page-<timestamp>.pdf` |
-
-### Interaction
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse click <ref>` | Click element (scrolls into view first) |
-| `barebrowse type <ref> <text>` | Type text into element |
-| `barebrowse fill <ref> <text>` | Clear existing content + type new text |
-| `barebrowse press <key>` | Press key: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
-| `barebrowse scroll <deltaY>` | Scroll page (positive=down, negative=up) |
-| `barebrowse hover <ref>` | Hover over element (triggers tooltips) |
-| `barebrowse select <ref> <value>` | Select dropdown option |
-| `barebrowse drag <fromRef> <toRef>` | Drag element to another element |
-| `barebrowse upload <ref> <files..>` | Upload file(s) to a file input element |
-
-### Tabs
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse tabs` | List open tabs (index, url, title) |
-| `barebrowse tab <index>` | Switch to tab by index |
-
-### Debugging
-
-| Command | Output |
-|---------|--------|
-| `barebrowse eval <expression>` | Evaluate JS in page, print result |
-| `barebrowse wait-idle` | Wait for network idle (no requests for 500ms) |
-| `barebrowse wait-for [opts]` | Wait for content to appear on page |
-| `barebrowse console-logs` | Console logs → `.barebrowse/console-<timestamp>.json` |
-| `barebrowse network-log` | Network log → `.barebrowse/network-<timestamp>.json` |
-| `barebrowse network-log --failed` | Only failed/4xx/5xx requests |
-| `barebrowse dialog-log` | JS dialog log → `.barebrowse/dialogs-<timestamp>.json` |
-| `barebrowse save-state` | Cookies + localStorage → `.barebrowse/state-<timestamp>.json` |
-
-**wait-for flags:**
-- `--text=STRING` — Wait for text to appear in page body
-- `--selector=CSS` — Wait for CSS selector to match
-- `--timeout=N` — Max wait time in ms (default: 30000)
-
-## Snapshot Format
-
-The snapshot is a YAML-like ARIA tree. Each line is one node:
-
-```
-# https://example.com/
-# 379 chars → 45 chars (88% pruned)
-- heading "Example Domain" [level=1] [ref=3]
-```
-
-- `[ref=N]` — Use this number with click, type, fill, hover, select, drag, upload
-- Refs change on every snapshot — always take a fresh snapshot before interacting
-- **act mode** (default): interactive elements + labels — for clicking, typing, navigating
-- **read mode**: all text content — for reading articles, extracting data
-
-## Workflow Pattern
-
-1. `barebrowse open <url>` — start session
-2. `barebrowse snapshot` — observe page (read the .yml file)
-3. Decide action based on snapshot content
-4. `barebrowse click/type/fill/press/scroll/drag/upload <ref>` — act
-5. `barebrowse snapshot` — observe result (refs are now different!)
-6. Repeat 3-5 until goal achieved
-7. `barebrowse close` — clean up
-
-## Tips
-
-- **Always snapshot before interacting** — refs are ephemeral and change every time
-- **Use `fill` instead of `type`** when replacing existing text in input fields
-- **Use `--mode=read`** for snapshot when you need to extract article content or data
-- **Use `back`/`forward`** to navigate browser history instead of re-entering URLs
-- **Use `upload`** for file inputs — pass absolute paths to the files
-- **Use `wait-for`** when content loads asynchronously — more reliable than `wait-idle`
-- **Check `dialog-log`** if JS alerts/confirms were auto-dismissed during your session
-- **Use `save-state`** to persist cookies/localStorage for later sessions via `--storage-state`
-- **Check `console-logs`** when page behavior seems wrong — JS errors show up there
-- **Check `network-log --failed`** to debug missing content or broken API calls
-- **Use `eval`** as an escape hatch when ARIA tree doesn't show what you need
-- **One session per project** — `.barebrowse/` is project-scoped
-- For bot-detected sites, use `--mode=headed` (requires browser with `--remote-debugging-port=9222`)

package/commands/barebrowse.md

@@ -1,132 +0,0 @@
----
-name: barebrowse
-description: Browser automation using the user's real browser with real cookies. Handles consent walls, login sessions, and bot detection automatically.
-allowed-tools: Bash(barebrowse:*)
----
-# barebrowse CLI — Browser Automation for Agents
-
-Browse any URL using the user's real browser with real cookies. Returns pruned ARIA snapshots (40-90% smaller than raw) with `[ref=N]` markers for interaction. Handles cookie consent, login sessions, JS dialogs, and bot detection automatically.
-
-## Quick Start
-
-```bash
-barebrowse open https://example.com    # Start session + navigate
-barebrowse snapshot                    # Get ARIA snapshot → .barebrowse/page-*.yml
-barebrowse click 8                     # Click element with ref=8
-barebrowse snapshot                    # See result
-barebrowse close                       # End session
-```
-
-All output files go to `.barebrowse/` in the current directory. Read them with the Read tool when needed.
-
-## Commands
-
-### Session Lifecycle
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse open [url] [flags]` | Start browser session. Optionally navigate to URL. |
-| `barebrowse close` | Close session and kill browser. |
-| `barebrowse status` | Check if session is running. |
-
-**Open flags:**
-- `--mode=headless|headed|hybrid` — Browser mode (default: headless)
-- `--no-cookies` — Skip cookie injection
-- `--browser=firefox|chromium` — Cookie source
-- `--prune-mode=act|read` — Default pruning mode
-- `--timeout=N` — Navigation timeout in ms
-- `--proxy=URL` — HTTP/SOCKS proxy server
-- `--viewport=WxH` — Viewport size (e.g. 1280x720)
-- `--storage-state=FILE` — Load cookies/localStorage from JSON file
-
-### Navigation
-
-| Command | Output |
-|---------|--------|
-| `barebrowse goto <url>` | Navigates, waits for load, dismisses consent. Prints "ok". |
-| `barebrowse back` | Go back in browser history. |
-| `barebrowse forward` | Go forward in browser history. |
-| `barebrowse snapshot` | ARIA snapshot → `.barebrowse/page-<timestamp>.yml` |
-| `barebrowse snapshot --mode=read` | Read mode: keeps all text (for content extraction) |
-| `barebrowse screenshot` | Screenshot → `.barebrowse/screenshot-<timestamp>.png` |
-| `barebrowse pdf [--landscape]` | PDF export → `.barebrowse/page-<timestamp>.pdf` |
-
-### Interaction
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse click <ref>` | Click element (scrolls into view first) |
-| `barebrowse type <ref> <text>` | Type text into element |
-| `barebrowse fill <ref> <text>` | Clear existing content + type new text |
-| `barebrowse press <key>` | Press key: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
-| `barebrowse scroll <deltaY>` | Scroll page (positive=down, negative=up) |
-| `barebrowse hover <ref>` | Hover over element (triggers tooltips) |
-| `barebrowse select <ref> <value>` | Select dropdown option |
-| `barebrowse drag <fromRef> <toRef>` | Drag element to another element |
-| `barebrowse upload <ref> <files..>` | Upload file(s) to a file input element |
-
-### Tabs
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse tabs` | List open tabs (index, url, title) |
-| `barebrowse tab <index>` | Switch to tab by index |
-
-### Debugging
-
-| Command | Output |
-|---------|--------|
-| `barebrowse eval <expression>` | Evaluate JS in page, print result |
-| `barebrowse wait-idle` | Wait for network idle (no requests for 500ms) |
-| `barebrowse wait-for [opts]` | Wait for content to appear on page |
-| `barebrowse console-logs` | Console logs → `.barebrowse/console-<timestamp>.json` |
-| `barebrowse network-log` | Network log → `.barebrowse/network-<timestamp>.json` |
-| `barebrowse network-log --failed` | Only failed/4xx/5xx requests |
-| `barebrowse dialog-log` | JS dialog log → `.barebrowse/dialogs-<timestamp>.json` |
-| `barebrowse save-state` | Cookies + localStorage → `.barebrowse/state-<timestamp>.json` |
-
-**wait-for flags:**
-- `--text=STRING` — Wait for text to appear in page body
-- `--selector=CSS` — Wait for CSS selector to match
-- `--timeout=N` — Max wait time in ms (default: 30000)
-
-## Snapshot Format
-
-The snapshot is a YAML-like ARIA tree. Each line is one node:
-
-```
-# https://example.com/
-# 379 chars → 45 chars (88% pruned)
-- heading "Example Domain" [level=1] [ref=3]
-```
-
-- `[ref=N]` — Use this number with click, type, fill, hover, select, drag, upload
-- Refs change on every snapshot — always take a fresh snapshot before interacting
-- **act mode** (default): interactive elements + labels — for clicking, typing, navigating
-- **read mode**: all text content — for reading articles, extracting data
-
-## Workflow Pattern
-
-1. `barebrowse open <url>` — start session
-2. `barebrowse snapshot` — observe page (read the .yml file)
-3. Decide action based on snapshot content
-4. `barebrowse click/type/fill/press/scroll/drag/upload <ref>` — act
-5. `barebrowse snapshot` — observe result (refs are now different!)
-6. Repeat 3-5 until goal achieved
-7. `barebrowse close` — clean up
-
-## Tips
-
-- **Always snapshot before interacting** — refs are ephemeral and change every time
-- **Use `fill` instead of `type`** when replacing existing text in input fields
-- **Use `--mode=read`** for snapshot when you need to extract article content or data
-- **Use `back`/`forward`** to navigate browser history instead of re-entering URLs
-- **Use `upload`** for file inputs — pass absolute paths to the files
-- **Use `wait-for`** when content loads asynchronously — more reliable than `wait-idle`
-- **Check `dialog-log`** if JS alerts/confirms were auto-dismissed during your session
-- **Use `save-state`** to persist cookies/localStorage for later sessions via `--storage-state`
-- **Check `console-logs`** when page behavior seems wrong — JS errors show up there
-- **Check `network-log --failed`** to debug missing content or broken API calls
-- **Use `eval`** as an escape hatch when ARIA tree doesn't show what you need
-- **One session per project** — `.barebrowse/` is project-scoped
-- For bot-detected sites, use `--mode=headed` (requires browser with `--remote-debugging-port=9222`)