barebrowse 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.12.0] - 2026-05-29
+
+### Added
+- **Shipped TypeScript types, generated from JSDoc.** The package now ships
+  `.d.ts` declarations so adopters get autocomplete and type errors out of the
+  box — no `@types/barebrowse`. The `.js` we author is still the `.js` that
+  ships; there is **no build step for runtime code**. Types are generated by
+  `tsc` (`checkJs` + `strictNullChecks`), emitted to a git-ignored `types/`, and
+  built into the tarball at publish via `prepublishOnly`. Because they are
+  generated-and-never-committed, the JSDoc, the `.d.ts`, and CI cannot drift.
+  `exports` now carries a `types` condition on every subpath.
+- **`ci.yml` (push/PR gate):** `npm ci → typecheck → build:types → test`. A
+  JSDoc/code mismatch is now a type error that blocks merge. No lint step — `tsc`
+  covers the bug class that matters for a vanilla-ESM lib.
+- Dev-only tooling: `typescript` + `@types/node` (devDependencies; never
+  shipped), `tsconfig.json`, and `typecheck` / `build:types` / `prepublishOnly`
+  scripts.
+
+### Changed
+- **`publish.yml` is now manual-only (`workflow_dispatch`) — npm OIDC trusted publishing with provenance, idempotent, and verifies the registry end-state.**
+- **Packaging now uses a `files` allowlist** (`src/`, generated `types/`,
+  `cli.js`, `mcp-server.js`, and the doc set) instead of the old `.npmignore`
+  denylist, which was removed. Repo-only files (`test/`, `docs/`, `CLAUDE.md`)
+  are excluded from the tarball.
+
+### Fixed
+- **`auth.js`: cookie databases are now opened with `readOnly: true`.** The
+  previous `readonly` (lowercase) key is silently ignored by `node:sqlite`;
+  surfaced by the new `tsc` typecheck. Read-only was already enforced via the
+  `?immutable=1` connection URI, so observable behavior is unchanged — this
+  honors the intended option. Added minimal, behavior-preserving null/type
+  guards in a few spots (`server.address()`, SQLite row values) flagged by
+  `strictNullChecks`.
+
 ## 0.11.0
 
 ### Security hardening — audit findings fixed, safe-by-default

package/README.md

@@ -35,6 +35,8 @@ npm install barebrowse
 
 Requires Node.js >= 22 and any installed Chromium-based browser.
 
+Ships with TypeScript types (generated from JSDoc) — autocomplete and type-checking work out of the box, no `@types/barebrowse` needed. The library is vanilla JS with no build step.
+
 ## Three ways to use it
 
 ### 1. CLI session -- for coding agents and quick testing

package/barebrowse.context.md

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.11.0 | Node.js >= 22 | 0 required deps | Apache-2.0
+> v0.12.0 | Node.js >= 22 | 0 required deps | Apache-2.0
 
 ## What this is
 
@@ -13,6 +13,11 @@ No Playwright. No bundled browser. No build step. Vanilla JS, ES modules.
 npm install barebrowse
 ```
 
+**TypeScript:** ships with `.d.ts` types generated from the source JSDoc, so
+autocomplete and type-checking work out of the box — no `@types/barebrowse`
+needed. The library itself is vanilla JS with no build step; the types are a
+publish-time artifact.
+
 Three integration paths:
 1. **Library:** `import { browse, connect } from 'barebrowse'` -- one-shot or interactive session
 2. **MCP server:** `barebrowse mcp` -- JSON-RPC over stdio for Claude Desktop, Cursor, etc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "repository": {
     "type": "git",
@@ -10,18 +10,40 @@
   "bugs": "https://github.com/hamr0/barebrowse/issues",
   "type": "module",
   "main": "src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./bareagent": "./src/bareagent.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./bareagent": {
+      "types": "./types/bareagent.d.ts",
+      "default": "./src/bareagent.js"
+    }
   },
   "bin": {
     "barebrowse": "./cli.js"
   },
+  "files": [
+    "src/",
+    "types/",
+    "cli.js",
+    "mcp-server.js",
+    "barebrowse.context.md",
+    "README.md",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test test/unit/*.test.js test/integration/*.test.js"
+    "test": "node --test test/unit/*.test.js test/integration/*.test.js",
+    "test:unit": "node --test test/unit/*.test.js",
+    "test:integration": "node --test test/integration/*.test.js",
+    "typecheck": "tsc --noEmit",
+    "build:types": "tsc",
+    "prepublishOnly": "npm run build:types"
   },
   "keywords": [
     "browser",
@@ -37,5 +59,9 @@
   "optionalDependencies": {
     "wearehere": "1.0.0"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
 }

package/src/auth.js

@@ -126,7 +126,7 @@ function extractChromiumCookies(dbPath, domain) {
   const aesKey = deriveKey(password);
 
   // immutable=1 bypasses WAL lock on live databases
-  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readOnly: true });
 
   let sql = `SELECT host_key, name, value, encrypted_value, path,
     CAST(expires_utc AS TEXT) AS expires_utc, is_secure, is_httponly, samesite
@@ -144,7 +144,8 @@ function extractChromiumCookies(dbPath, domain) {
   const SAMESITE = { 0: 'None', 1: 'Lax', 2: 'Strict' };
 
   return rows.map((row) => {
-    const enc = Buffer.from(row.encrypted_value);
+    const rawEnc = row.encrypted_value;
+    const enc = rawEnc instanceof Uint8Array ? Buffer.from(rawEnc) : Buffer.alloc(0);
     let value;
     try {
       value = enc.length > 0 ? decryptCookie(enc, aesKey) : row.value;
@@ -154,7 +155,9 @@ function extractChromiumCookies(dbPath, domain) {
 
     // Chrome timestamp: microseconds since 1601-01-01
     const CHROME_EPOCH = 11644473600000000n;
-    const expiresUtc = row.expires_utc ? BigInt(row.expires_utc) : 0n;
+    const expiresUtc = typeof row.expires_utc === 'string' || typeof row.expires_utc === 'number'
+      ? BigInt(row.expires_utc)
+      : 0n;
     const expires = expiresUtc > 0n
       ? Number((expiresUtc - CHROME_EPOCH) / 1000000n)
       : -1;
@@ -179,7 +182,7 @@ function extractChromiumCookies(dbPath, domain) {
  * @returns {Array<object>} Cookies in CDP Network.setCookie format
  */
 function extractFirefoxCookies(dbPath, domain) {
-  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readOnly: true });
 
   let sql = `SELECT host, name, value, path, expiry, isSecure, isHttpOnly, sameSite
     FROM moz_cookies`;

package/src/bareagent.js

@@ -11,6 +11,8 @@
  * 300ms settle delay after actions for DOM updates.
  */
 
+/// <reference path="./wearehere.d.ts" />
+
 import { browse, connect } from './index.js';
 
 // Optional: privacy assessment via wearehere
@@ -22,6 +24,14 @@ try {
 const SETTLE_MS = 300;
 const settle = () => new Promise((r) => setTimeout(r, SETTLE_MS));
 
+/**
+ * @typedef {object} BrowseTool
+ * @property {string} name
+ * @property {string} description
+ * @property {object} parameters - JSON-schema-shaped parameter spec
+ * @property {(args?: any) => Promise<any>} execute
+ */
+
 /**
  * Create bareagent-compatible browse tools.
  * @param {object} [opts] - Options passed to connect() for session tools
@@ -42,6 +52,7 @@ export function createBrowseTools(opts = {}) {
     return await page.snapshot();
   }
 
+  /** @type {BrowseTool[]} */
   const tools = [
     {
       name: 'browse',
@@ -77,7 +88,7 @@ export function createBrowseTools(opts = {}) {
           pruneMode: { type: 'string', enum: ['act', 'read'], description: '"act" (default) for interactive elements only; "read" for paragraphs and long text (articles/docs).' },
         },
       },
-      execute: async ({ pruneMode } = {}) => {
+      execute: async (/** @type {{ pruneMode?: string }} */ { pruneMode } = {}) => {
         const page = await getPage();
         return await page.snapshot(pruneMode ? { mode: pruneMode } : undefined);
       },
@@ -231,7 +242,7 @@ export function createBrowseTools(opts = {}) {
           landscape: { type: 'boolean', description: 'Landscape orientation (default: false)' },
         },
       },
-      execute: async ({ landscape } = {}) => {
+      execute: async (/** @type {{ landscape?: boolean }} */ { landscape } = {}) => {
         const page = await getPage();
         return await page.pdf({ landscape });
       },
@@ -245,7 +256,7 @@ export function createBrowseTools(opts = {}) {
           format: { type: 'string', enum: ['png', 'jpeg', 'webp'], description: 'Image format (default: png)' },
         },
       },
-      execute: async ({ format } = {}) => {
+      execute: async (/** @type {{ format?: string }} */ { format } = {}) => {
         const page = await getPage();
         return await page.screenshot({ format });
       },
@@ -259,7 +270,7 @@ export function createBrowseTools(opts = {}) {
           ignoreCache: { type: 'boolean', description: 'Bypass HTTP cache (hard reload). Default: false.' },
         },
       },
-      execute: async ({ ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
+      execute: async (/** @type {{ ignoreCache?: boolean }} */ { ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
     },
     {
       name: 'wait_for',
@@ -272,7 +283,7 @@ export function createBrowseTools(opts = {}) {
           timeout: { type: 'number', description: 'Timeout in ms (default: 30000)' },
         },
       },
-      execute: async ({ text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
+      execute: async (/** @type {{ text?: string, selector?: string, timeout?: number }} */ { text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
     },
     {
       name: 'downloads',

package/src/cdp.js

@@ -12,7 +12,7 @@
 /**
  * Create a CDP client connected to the given WebSocket URL.
  * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)
- * @returns {Promise<CDPClient>}
+ * @returns {Promise<object>} CDP client ({ send, on, once, session, close })
  */
 export async function createCDP(wsUrl) {
   const ws = new WebSocket(wsUrl);
@@ -20,7 +20,8 @@ export async function createCDP(wsUrl) {
   const pending = new Map();   // id → { resolve, reject }
   const listeners = new Map(); // "method" or "sessionId:method" → Set<callback>
 
-  await new Promise((resolve, reject) => {
+  /** @type {Promise<void>} */
+  const connected = new Promise((resolve, reject) => {
     const timeout = setTimeout(() => reject(new Error('CDP connection timeout (5s)')), 5000);
     ws.onopen = () => { clearTimeout(timeout); resolve(); };
     ws.onerror = (e) => {
@@ -28,6 +29,7 @@ export async function createCDP(wsUrl) {
       reject(new Error(`CDP WebSocket connection failed: ${e.message || 'unknown error'}`));
     };
   });
+  await connected;
 
   ws.onmessage = (event) => {
     const msg = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());

package/src/chromium.js

@@ -112,7 +112,8 @@ export function findBrowser() {
  * @param {number} [opts.port=0] - CDP port (0 = random available port)
  * @param {string} [opts.userDataDir] - Browser profile directory
  * @param {boolean} [opts.headed=false] - Launch in headed mode (with visible window)
- * @returns {Promise<{wsUrl: string, process: ChildProcess, port: number}>}
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port')
+ * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number}>}
  */
 export async function launch(opts = {}) {
   const binary = opts.binary || findBrowser();
@@ -235,6 +236,7 @@ export async function cleanupBrowser(browser) {
   if (!browser) return;
   activeBrowsers.delete(browser);
   if (browser.process && !browser.process.killed && browser.process.exitCode === null) {
+    /** @type {Promise<void>} */
     const exited = new Promise((resolve) => {
       const timer = setTimeout(resolve, 2000);
       browser.process.once('exit', () => { clearTimeout(timer); resolve(); });
@@ -282,7 +284,10 @@ export async function cleanupBrowser(browser) {
 export async function getDebugUrl(port) {
   const res = await fetch(`http://127.0.0.1:${port}/json/version`);
   if (!res.ok) throw new Error(`Cannot reach browser debug port at ${port}: ${res.status}`);
-  const data = await res.json();
+  const data = /** @type {{ webSocketDebuggerUrl?: string }} */ (await res.json());
+  if (!data.webSocketDebuggerUrl) {
+    throw new Error(`Browser debug port at ${port} returned no webSocketDebuggerUrl`);
+  }
   return data.webSocketDebuggerUrl;
 }
 

package/src/daemon.js

@@ -416,11 +416,17 @@ export async function runDaemon(opts, outputDir, initialUrl) {
     }
   });
 
-  await new Promise((resolve) => {
+  /** @type {Promise<void>} */
+  const listening = new Promise((resolve) => {
     server.listen(0, '127.0.0.1', () => resolve());
   });
+  await listening;
 
-  const port = server.address().port;
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Daemon server failed to bind to a TCP port');
+  }
+  const port = address.port;
 
   // Write session.json so parent/clients can find us. Owner-only: it carries
   // the auth token that gates /command.

package/src/index.js

@@ -37,6 +37,17 @@ import { chmodSync } from 'node:fs';
  *   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 async function browse(url, opts = {}) {
@@ -169,6 +180,14 @@ export async function browse(url, opts = {}) {
  * @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 async function connect(opts = {}) {
@@ -189,7 +208,7 @@ export async function connect(opts = {}) {
     // Reuse the user's running browser — do not launch, do not own the
     // profile. cleanupBrowser() is a no-op on this shape (process: null,
     // ownedProfileDir: null), which is the whole point.
-    browser = await attach({ port: opts.port });
+    browser = await attach({ port: opts.port ?? 0 });
     cdp = await createCDP(browser.wsUrl);
   } else if (mode === 'headed') {
     browser = await launch({ ...launchOpts, headed: true });

package/src/network-idle.js

@@ -12,12 +12,14 @@
  * @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, opts = {}) {
   const timeout = opts.timeout || 30000;
   const idle = opts.idle || 500;
 
-  return new Promise((resolve, reject) => {
+  /** @type {Promise<void>} */
+  const settled = new Promise((resolve, reject) => {
     const pending = new Set();
     let timer = null;
     const unsubs = [];
@@ -59,4 +61,5 @@ export function waitForNetworkIdle(session, opts = {}) {
     // Start check immediately (might already be idle)
     check();
   });
+  return settled;
 }

package/src/prune.js

@@ -60,7 +60,7 @@ const SKIP_ROLES = new Set([
  *
  * @param {object} tree - Root node from buildTree() (CDP format)
  * @param {object} [options]
- * @param {'act'|'browse'|'navigate'|'full'} [options.mode='act'] - Pruning mode
+ * @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
  */

package/src/session-client.js

@@ -13,7 +13,7 @@ const SESSION_FILE = 'session.json';
 
 /**
  * Read session.json from the output directory.
- * @returns {{ port: number, pid: number, startedAt: string } | null}
+ * @returns {{ port: number, pid: number, token?: string, startedAt: string } | null}
  */
 export function readSession(outputDir) {
   const sessionPath = join(resolve(outputDir), SESSION_FILE);

package/src/wearehere.d.ts

@@ -0,0 +1,6 @@
+// Ambient shim for the optional 'wearehere' dependency.
+// It is dynamically imported and may not be installed; this declaration
+// satisfies the typechecker without pulling in a hard dependency.
+declare module 'wearehere' {
+  export function assess(...args: any[]): Promise<any>;
+}

package/types/aria.d.ts

@@ -0,0 +1,17 @@
+/**
+ * aria.js — Format ARIA accessibility tree nodes for agent consumption.
+ *
+ * Takes a nested tree (built from CDP's Accessibility.getFullAXTree)
+ * and formats it as readable YAML-like text, similar to Playwright's ariaSnapshot.
+ */
+/**
+ * Format a nested ARIA tree as readable text output.
+ *
+ * Output format (one node per line, indented):
+ *   - role "name" [props] [ref=nodeId]
+ *
+ * @param {object} node - Tree node { role, name, properties, children, ignored, nodeId }
+ * @param {number} [depth=0] - Current indentation depth
+ * @returns {string} Formatted ARIA tree text
+ */
+export function formatTree(node: object, depth?: number): string;

package/types/auth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Extract cookies from the user's browser, auto-detecting which browser to use.
+ * @param {object} [opts]
+ * @param {string} [opts.browser] - 'chromium', 'chrome', 'brave', 'edge', 'firefox', or 'auto'
+ * @param {string} [opts.domain] - Filter by domain
+ * @returns {Array<object>} Cookies in CDP-compatible format
+ */
+export function extractCookies(opts?: {
+    browser?: string | undefined;
+    domain?: string | undefined;
+}): Array<object>;
+/**
+ * Inject cookies into a CDP session via Network.setCookie.
+ * @param {object} session - CDP session handle (from cdp.session())
+ * @param {Array<object>} cookies - Cookies from extractCookies()
+ */
+export function injectCookies(session: object, cookies: Array<object>): Promise<void>;
+/**
+ * RFC 6265 domain-match: does `host` belong to a cookie declared for
+ * `cookieDomain`? Leading dot on the cookie domain is ignored (host-only
+ * vs domain cookies are matched the same here, intentionally — we want
+ * parent-domain cookies like .google.com to apply to mail.google.com).
+ * @param {string} host - target hostname (e.g. 'mail.google.com')
+ * @param {string} cookieDomain - cookie's host_key (e.g. '.google.com')
+ * @returns {boolean}
+ */
+export function cookieDomainMatch(host: string, cookieDomain: string): boolean;
+/**
+ * Extract cookies for a URL and inject them into a CDP session.
+ * Convenience function combining extractCookies + injectCookies.
+ * @param {object} session - CDP session handle
+ * @param {string} url - URL to extract cookies for
+ * @param {object} [opts] - Options passed to extractCookies
+ */
+export function authenticate(session: object, url: string, opts?: object): Promise<number>;

package/types/bareagent.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @typedef {object} BrowseTool
+ * @property {string} name
+ * @property {string} description
+ * @property {object} parameters - JSON-schema-shaped parameter spec
+ * @property {(args?: any) => Promise<any>} execute
+ */
+/**
+ * Create bareagent-compatible browse tools.
+ * @param {object} [opts] - Options passed to connect() for session tools
+ * @returns {{ tools: Array, close: () => Promise<void> }}
+ */
+export function createBrowseTools(opts?: object): {
+    tools: any[];
+    close: () => Promise<void>;
+};
+export type BrowseTool = {
+    name: string;
+    description: string;
+    /**
+     * - JSON-schema-shaped parameter spec
+     */
+    parameters: object;
+    execute: (args?: any) => Promise<any>;
+};

package/types/blocklist.d.ts

@@ -0,0 +1,21 @@
+/**
+ * blocklist.js — Ad/tracker URL patterns for CDP Network.setBlockedURLs.
+ *
+ * Curated by real-world frequency, not pulled wholesale from Peter Lowe /
+ * EasyList. CDP does linear pattern matching per request, so 3,000-entry
+ * lists add ~150ms cumulative cost on a typical page for ~5% extra coverage
+ * (long-tail regional networks the agent rarely encounters). The set below
+ * is ~120 patterns covering the trackers that actually show up in agent
+ * traffic: Google/FB/Amazon/MS/Adobe ad+analytics, the major SaaS analytics
+ * stacks (Segment/Amplitude/Mixpanel/HubSpot/Hotjar/FullStory/Heap/Mouseflow),
+ * session-replay (LogRocket/Crazy Egg/Optimizely/VWO), content-recommendation
+ * (Taboola/Outbrain/Criteo), and the consumer-pixel cluster (LinkedIn/Twitter/
+ * TikTok/Snap/Pinterest/Reddit).
+ *
+ * Patterns are CDP-format globs: '*' matches any character run.
+ *
+ * To extend at runtime, pass connect({ blockUrls: [...] }) — your patterns
+ * are merged with this default. To turn the default off entirely, pass
+ * { blockAds: false }.
+ */
+export const DEFAULT_BLOCKLIST: string[];

package/types/cdp.d.ts

@@ -0,0 +1,16 @@
+/**
+ * cdp.js — Minimal Chrome DevTools Protocol client over WebSocket.
+ *
+ * Sends JSON-RPC commands, receives responses and events.
+ * Uses Node 22's built-in WebSocket (no external deps).
+ *
+ * Supports flattened sessions: when a sessionId is provided,
+ * it's sent at the top level of the message (not inside params).
+ * Events from sessions are also dispatched by sessionId.
+ */
+/**
+ * Create a CDP client connected to the given WebSocket URL.
+ * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)
+ * @returns {Promise<object>} CDP client ({ send, on, once, session, close })
+ */
+export function createCDP(wsUrl: string): Promise<object>;

package/types/chromium.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Find the first available Chromium binary on the system.
+ * @returns {string} Path to the binary
+ * @throws {Error} If no Chromium browser is found
+ */
+export function findBrowser(): string;
+/**
+ * Launch a Chromium instance with CDP enabled.
+ * @param {object} [opts]
+ * @param {string} [opts.binary] - Path to browser binary (auto-detected if omitted)
+ * @param {number} [opts.port=0] - CDP port (0 = random available port)
+ * @param {string} [opts.userDataDir] - Browser profile directory
+ * @param {boolean} [opts.headed=false] - Launch in headed mode (with visible window)
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port')
+ * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number}>}
+ */
+export function launch(opts?: {
+    binary?: string | undefined;
+    port?: number | undefined;
+    userDataDir?: string | undefined;
+    headed?: boolean | undefined;
+    proxy?: string | undefined;
+}): Promise<{
+    wsUrl: string;
+    process: import("node:child_process").ChildProcess;
+    port: number;
+}>;
+/**
+ * Kill a launched browser and remove its temp profile dir (if we created one).
+ * Waits up to 2s for the process to actually exit before unlinking the dir —
+ * Chromium can still hold files briefly after SIGTERM, which races rmSync.
+ * Safe to call on partially-failed launches or already-dead processes.
+ * @returns {Promise<void>}
+ */
+export function cleanupBrowser(browser: any): Promise<void>;
+/**
+ * Get the CDP WebSocket URL for a browser already running with --remote-debugging-port.
+ * @param {number} port - The debug port
+ * @returns {Promise<string>} WebSocket URL
+ */
+export function getDebugUrl(port: number): Promise<string>;
+/**
+ * Attach to a Chromium already running with --remote-debugging-port=<port>.
+ * Returns the same shape as launch() but with process: null and
+ * ownedProfileDir: null — cleanupBrowser() becomes a no-op so we never
+ * kill a browser we did not start or remove a profile we do not own.
+ * @param {object} opts
+ * @param {number} opts.port - The debug port the running browser is listening on
+ * @returns {Promise<{wsUrl: string, process: null, port: number, ownedProfileDir: null}>}
+ */
+export function attach({ port }: {
+    port: number;
+}): Promise<{
+    wsUrl: string;
+    process: null;
+    port: number;
+    ownedProfileDir: null;
+}>;

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/.github/workflows/publish.yml

@@ -1,26 +0,0 @@
-name: Publish to npm
-
-# Trusted publishing via OIDC — no NPM_TOKEN needed.
-# Configure the trusted publisher at npmjs.com first (see repo notes).
-on:
-  workflow_dispatch:        # manual "Run workflow" button
-  release:
-    types: [published]      # also publishes when you cut a GitHub release
-
-permissions:
-  contents: read
-  id-token: write           # required: lets npm mint OIDC credentials
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: 'https://registry.npmjs.org'
-      - name: Upgrade npm (trusted publishing needs >= 11.5.1)
-        run: npm install -g npm@latest
-      - name: Publish
-        run: npm publish

package/commands/barebrowse/SKILL.md

@@ -1,137 +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
-- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
-- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
-
-> Security (v0.11.0): `file:`/`chrome:`/etc. navigation is blocked by default, and the daemon requires a per-session token (handled transparently by the CLI). Snapshots and saved state are written owner-only (`0600`).
-
-### 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,136 +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
-- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
-- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
-
-> Security (v0.11.0): `file:`/`chrome:`/etc. navigation is blocked by default, and the daemon requires a per-session token (handled transparently by the CLI). Snapshots and saved state are written owner-only (`0600`).
-
-### 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`)