barebrowse 0.11.0 → 0.13.0

package/src/daemon.js

@@ -11,6 +11,7 @@ import { writeFileSync, mkdirSync, existsSync, readFileSync, unlinkSync } from '
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { join, resolve } from 'node:path';
 import { connect } from './index.js';
+import { formatReadable } from './readable.js';
 
 /** Owner-only file write helper — daemon artifacts can hold authenticated content. */
 function writeFilePrivate(path, data) {
@@ -191,6 +192,17 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       return { ok: true, file };
     },
 
+    async readable() {
+      const r = await page.readable();
+      // A non-article page is not an error — surface the hint so the agent
+      // knows to fall back to snapshot, rather than failing the command.
+      if (!r.ok) return { ok: true, value: r.hint };
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `article-${ts}.txt`);
+      writeFilePrivate(file, formatReadable(r));
+      return { ok: true, file };
+    },
+
     async screenshot({ format }) {
       const data = await page.screenshot({ format: format || 'png' });
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
@@ -361,8 +373,11 @@ export async function runDaemon(opts, outputDir, initialUrl) {
   // Start HTTP server on random port
   const server = createServer(async (req, res) => {
     if (req.method === 'GET' && req.url === '/status') {
+      // Liveness only — no pid. /status is the one pre-auth endpoint, and
+      // isAlive() just checks res.ok; the pid clients show comes from
+      // session.json (owner-only), so nothing consumes a pid here.
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, pid: process.pid }));
+      res.end(JSON.stringify({ ok: true }));
       return;
     }
 
@@ -380,8 +395,20 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       return;
     }
 
+    // Cap the request body. Post-auth, single local user, but an unbounded
+    // `body +=` is a needless memory-DoS foot-gun. 16 MB covers any realistic
+    // eval expression / typed text.
+    const MAX_BODY = 16 * 1024 * 1024;
     let body = '';
-    for await (const chunk of req) body += chunk;
+    for await (const chunk of req) {
+      body += chunk;
+      if (body.length > MAX_BODY) {
+        res.writeHead(413, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'Request body too large' }));
+        req.destroy();
+        return;
+      }
+    }
 
     let parsed;
     try {
@@ -416,11 +443,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

@@ -18,6 +18,7 @@ import { dismissConsent } from './consent.js';
 import { applyStealth } from './stealth.js';
 import { DEFAULT_BLOCKLIST } from './blocklist.js';
 import { waitForNetworkIdle } from './network-idle.js';
+import { readable as extractReadable } from './readable.js';
 import { assertNavigable, assertUploadAllowed } from './url-guard.js';
 import { join as pathJoin } from 'node:path';
 import { chmodSync } from 'node:fs';
@@ -37,6 +38,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 +181,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 +209,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 });
@@ -440,6 +460,13 @@ export async function connect(opts = {}) {
       return stats + '\n' + hint + warn + out;
     },
 
+    // Clean article text (Firefox Reader View engine), for reading/summarising
+    // — not for interacting. Returns { ok:false, hint } on non-article pages.
+    // See readable.js for why this never hard-gates on article detection.
+    async readable() {
+      return extractReadable(page.session);
+    },
+
     async click(ref) {
       const entry = refMap.get(ref);
       if (!entry) throw new Error(`No element found for ref "${ref}"`);

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/readable.js

@@ -0,0 +1,116 @@
+/**
+ * readable.js — extract the main article of a page as clean reading text.
+ *
+ * Companion to snapshot(): snapshot() yields an *actionable* ARIA tree for
+ * clicking/typing; readable() yields the *readable* article (title + body
+ * prose, nav/ads/sidebars stripped) for "read/summarise this" tasks, where
+ * snapshot() is both noisy and silently lossy on long prose.
+ *
+ * Runs Mozilla's Readability (the engine behind Firefox Reader View) inside
+ * the live page over CDP — so JS-rendered articles work, unlike a raw fetch.
+ * `isProbablyReaderable` gives an article-likelihood signal, but it is not
+ * reliable on its own (false negatives on minimally-marked-up essays, false
+ * positives on link-dense portals), so readable() never hard-gates: it always
+ * returns whatever Readability extracted plus an advisory `confidence`. A
+ * low-confidence result is the agent's cue to fall back to snapshot().
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// Read the self-contained browser builds once at module load and inject their
+// source into the page. Both define globals (Readability, isProbablyReaderable)
+// when evaluated in a non-module context; the `if (typeof module ...)` tails are
+// harmless no-ops in the page.
+const READABILITY_SRC = readFileSync(require.resolve('@mozilla/readability/Readability.js'), 'utf8');
+const READERABLE_SRC = readFileSync(require.resolve('@mozilla/readability/Readability-readerable.js'), 'utf8');
+
+/** Below this many characters of extracted text, treat as low confidence. */
+const MIN_ARTICLE_CHARS = 1500;
+
+// Fully static — interpolates only the two module-level source constants — so
+// it's built once at load, not rebuilt (~120 KB) on every readable() call.
+const EXTRACT_EXPRESSION = `(() => {
+  ${READERABLE_SRC}
+  ${READABILITY_SRC}
+  try {
+    const readerable = isProbablyReaderable(document);
+    // Readability mutates the document it parses — clone so the live page
+    // (and any later snapshot()/interaction) is untouched.
+    const art = new Readability(document.cloneNode(true)).parse();
+    if (!art || !art.textContent || !art.textContent.trim()) {
+      return { ok: false, readerable };
+    }
+    return {
+      ok: true,
+      readerable,
+      title: art.title || '',
+      byline: art.byline || '',
+      text: art.textContent.trim(),
+      length: art.length || art.textContent.length,
+    };
+  } catch (e) {
+    return { ok: false, err: String(e && e.message || e) };
+  }
+})()`;
+
+/**
+ * Render a readable() result as a text block: a short header (title / byline /
+ * confidence, with the fall-back hint inline when present) then the body. On a
+ * failed extraction it returns the hint. Shared by the MCP, bareagent, and
+ * CLI/daemon surfaces so their output can't drift apart.
+ * @param {object} r - a readable() result.
+ * @returns {string}
+ */
+export function formatReadable(r) {
+  if (!r.ok) return r.hint;
+  const header = `title: ${r.title}${r.byline ? `\nbyline: ${r.byline}` : ''}\n`
+    + `confidence: ${r.confidence}${r.hint ? ` (${r.hint})` : ''}\n\n`;
+  return header + r.text;
+}
+
+/**
+ * Extract the main article from the current page.
+ * @param {object} session - CDP session-scoped handle (.send()).
+ * @returns {Promise<object>} One of:
+ *   { ok: false, hint }                              — no article content found
+ *   { ok: true, title, byline, text, length,
+ *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ */
+export async function readable(session) {
+  const { result } = await session.send('Runtime.evaluate', {
+    expression: EXTRACT_EXPRESSION,
+    returnByValue: true,
+    awaitPromise: true,
+  });
+  const r = result.value || {};
+
+  if (!r.ok) {
+    return {
+      ok: false,
+      hint: r.err
+        ? `readable extraction failed (${r.err}); use snapshot()`
+        : 'no article content found on this page; use snapshot() instead',
+    };
+  }
+
+  // Advisory confidence: high only when the reader-view heuristic agrees AND
+  // there is a substantial amount of text. Low is not an error — the text is
+  // still returned; it just means "verify, or prefer snapshot()".
+  const confidence = r.readerable && r.length >= MIN_ARTICLE_CHARS ? 'high' : 'low';
+  const out = {
+    ok: true,
+    title: r.title,
+    byline: r.byline,
+    text: r.text,
+    length: r.length,
+    readerable: r.readerable,
+    confidence,
+  };
+  if (confidence === 'low') {
+    out.hint = 'low article confidence — this may not be an article; consider snapshot()';
+  }
+  return out;
+}

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,6 @@
+/**
+ * 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;