barebrowse 0.19.2 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,104 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.21.0] - 2026-09-17
4
+
5
+ ### Added
6
+
7
+ - **`connect()` falls back to Firefox when no Chromium is installed.** With no
8
+ `engine` passed, it prefers Chromium but uses Firefox (over WebDriver BiDi)
9
+ if only Firefox is present, warning once to stderr; if neither is installed it
10
+ throws naming both. An explicit `engine` is still honored exactly — it errors
11
+ on a missing binary rather than silently switching — and attach mode (`port`)
12
+ stays Chromium-only. The decision is a pure, unit-tested `resolveEngine()`.
13
+ (`browse()` remains Chromium-only — separate.)
14
+ - **The MCP surface now advertises the active engine.** Firefox is selectable
15
+ only at server launch (`BAREBROWSE_ENGINE`), which a running agent can't see —
16
+ so agents concluded only Chromium existed. Three surfaces now expose it: the
17
+ `initialize` response carries `instructions` naming the active engine + that
18
+ both engines are supported; the `browse` tool description gets the active
19
+ engine appended at `tools/list` time; and a new **`capabilities`** MCP tool
20
+ reports the active engine, mode, both available engines, how to switch (a
21
+ server restart — the engine is fixed for a running session), and the live
22
+ capability flags if a page is open. `capabilities` is pure introspection: it
23
+ never launches a browser.
24
+ - **Session introspection: `page.engine` + `page.capabilities`.** Both engine
25
+ shapes now carry `page.engine` (`'chromium'` | `'firefox'`) and a
26
+ `page.capabilities` object (`engine`, `mode`, `attach`, `escapeHatch`,
27
+ `reloadIgnoreCache`, `downloads`, `stealth`, `cookieInjection`), so a caller
28
+ can ask "which engine am I on and what can it do?" without probing for a
29
+ `cdp`/`bidi` escape hatch. `engine` is a typed literal in each arm, so it also
30
+ works as a discriminant (`if (page.engine === 'firefox') …`) — cleaner than
31
+ the previous `'cdp' in page`. The CLI daemon persists both into
32
+ `session.json`, so `status`/`doctor` report the live session's feature set.
33
+ - **`barebrowse doctor` now reports the runtime environment**, not just MCP
34
+ config scope conflicts: the default engine/mode (incl. the `BAREBROWSE_ENGINE`
35
+ / `BAREBROWSE_MODE` / `BAREBROWSE_INCOGNITO` overrides that pick the engine at
36
+ launch), which Chromium and Firefox binaries are installed, which cookie
37
+ sources exist, and any live session's engine + capabilities. This closes the
38
+ discoverability gap where the Firefox engine — selectable only via a
39
+ server-launch env var — was invisible to a running session.
40
+ - **AX-fidelity harness (`test/integration/ax-fidelity.test.js`).** Drives the
41
+ same fixture pages through both engines and asserts the Firefox/BiDi
42
+ reconstruction never drops a semantic (role + name) node the CDP baseline
43
+ found — making repeatable the by-hand comparison that originally caught four
44
+ reconstruction bugs. Compares role+name only; property brackets and
45
+ `StaticText` echoes legitimately differ between engines.
46
+
47
+ ### Fixed
48
+
49
+ - **`page.capabilities.stealth` now correctly reflects live headed/headless
50
+ state.** It was computed once at `connect()`; after a hybrid bot-challenge
51
+ fallback relaunched a headed browser, `capabilities.stealth` (and the MCP
52
+ `capabilities` tool, and the CLI daemon's persisted `session.json`) kept
53
+ reporting the launch-time value. Now a getter on both engines that reads the
54
+ live state. JSDoc on both engine arms corrected to mark `stealth` live vs
55
+ the other launch-fixed fields, and a regression test asserts it is a real
56
+ getter (property descriptor has `get`), not a value captured at `connect()`
57
+ — a frozen field would have passed the previous test.
58
+ - **Corrected a stale doc line claiming Firefox "is not yet implemented."**
59
+ `barebrowse.context.md` note #10 still said the library was Chromium-only;
60
+ Firefox/BiDi has shipped since v0.15.0 (parity reached across v0.16–0.19).
61
+ The line now documents both engines and how to select Firefox — the same
62
+ false claim had led a session to conclude Firefox wasn't supported.
63
+ - **Adopter type-check gate no longer runs dependency install scripts next to the publish credential.** The gate installs the packed tarball into a throwaway consumer project, and that install ran inside the job holding `id-token: write` — the OIDC credential that can publish this package — with install scripts enabled, so any install script in the tarball's transitive dependency tree executed beside a live publish capability. Now `--ignore-scripts`. The gate only ever runs `tsc`, which reads `.d.ts` and nothing else, so nothing needs building: verified on a native-addon package that the addon is *not* compiled and the type check still passes green, while a broken dereference still fails it. `typescript` is also pinned to `@5` for the same reason `@types/node` is pinned — an unpinned compiler silently becomes a new major and fails the gate on its own schedule rather than on the commit's merits. CI only — no runtime or published-artifact change.
64
+
65
+ ## [0.20.0] - 2026-08-30
66
+
67
+ ### Added
68
+
69
+ - **Publish workflow gates on the types being usable BY AN ADOPTER, not just internally.** `npm run typecheck` (`tsc --noEmit`) checks the *source*; it cannot see the generated `.d.ts` as an adopter resolves it from inside `node_modules`, which is the one thing consumers actually get. The publish workflow now packs the tarball, installs it into a clean consumer project, and compiles a quickstart against it, so a release whose published types are broken cannot reach the registry. The consumer pins `@types/node` to the major this package builds against instead of floating to the newest, so a stricter DefinitelyTyped release cannot turn the publish gate red for reasons unrelated to the commit being published. Verified locally: the quickstart compiles green against a packed tarball, and a deliberately broken dereference fails it. CI only — no runtime or published-artifact change.
70
+
71
+ ### Fixed
72
+
73
+ - **`connect()` now returns a typed page handle instead of bare `object`.** Its
74
+ JSDoc `@returns` was `Promise<object>`, so a TypeScript adopter could not
75
+ dereference `page.goto` / `page.snapshot` / `page.click` / `page.close` off the
76
+ returned handle without casting — the whole interactive surface was unusable
77
+ from types. The return is now inferred structurally from the returned object
78
+ literals and re-exported as a named `Page` type (`import type { Page } from
79
+ 'barebrowse'`), so there is no hand-maintained interface to drift. `Page` is a
80
+ union of the two engine shapes (Chromium/CDP and Firefox/BiDi): every shared
81
+ interaction method dereferences without narrowing, while an engine-specific
82
+ escape hatch (`cdp` on Chromium, `bidi` on Firefox) is exposed by narrowing
83
+ (`if ('cdp' in page) …`) — the union is sound where an intersection would falsely
84
+ claim a page carries both engines' hatches. The commonly-omitted option
85
+ parameters on `snapshot()`, `type()`, and `injectCookies()` are now typed
86
+ optional (they always were at runtime), so `page.snapshot()` and
87
+ `page.type(ref, text)` compile — and carry named, member-checked shapes
88
+ (`SnapshotOptions`, `TypeOptions`, `CookieOptions`, all exported), so a typo
89
+ like `snapshot({ mdoe: 'read' })` is now a compile error instead of a silent
90
+ no-op. `browse()` → `Promise<string>` is unchanged.
91
+ Validated by packing the tarball and compiling a strict (`nodenext`,
92
+ `skipLibCheck:false`) consumer quickstart that dereferences the real page
93
+ methods — green after, red before. The publish adopter gate missed this because
94
+ its quickstart only exercises `browse()`'s snapshot string, never the
95
+ `connect()` handle.
96
+ - **Publish workflow pinned to `npm@11` — npm 12.0.0's `npm publish --provenance` is broken.** The job ran `npm install -g npm@latest`, which started resolving to npm 12.0.0 (released 2026-07-09) on the Node 22 runner. npm 12's `libnpmpublish` provenance code does `require('sigstore')`, but the tarball bundles only the `@sigstore/*` scoped packages — so `--provenance` dies with `MODULE_NOT_FOUND` and the publish fails outright. npm@11 bundles `sigstore` and publishes fine. Pinned to the major rather than floating on `@latest`. Revisit once npm ships a provenance fix. CI only — no runtime or published-artifact change.
97
+
98
+ ### Changed
99
+
100
+ - **Agent/IDE scratch is gitignored and de-tracked (`.claude/`, `.litectx/`, `.idea/`).** Per-machine agent and IDE state is no part of the package — it regenerates locally and only added noise and churn. Now ignored, and any already-committed copies removed from tracking (local files kept on disk). Functional dot-paths (`.github/`, `.gitignore`, `.npmignore`, `.mcp.json`) stay tracked. Repo hygiene only.
101
+
3
102
  ## [0.19.2] - 2026-07-11
4
103
 
5
104
  ### Fixed
package/README.md CHANGED
@@ -58,7 +58,7 @@ Outputs go to `.barebrowse/` as files -- agents read them with their file tools,
58
58
 
59
59
  **Other agents:** Copy `commands/barebrowse.md` to your agent's command/skill directory.
60
60
 
61
- For writing your own skill files for other CLI tools: [docs/skill-template.md](docs/skill-template.md).
61
+ For writing your own skill files for other CLI tools: [docs/product/skill-template.md](docs/product/skill-template.md).
62
62
 
63
63
  ### 2. MCP server -- for Claude Desktop, Cursor, and other MCP clients
64
64
 
@@ -96,11 +96,11 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
96
96
  }
97
97
  ```
98
98
 
99
- MCP tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
99
+ MCP tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`, `capabilities` (reports the active engine — chromium or firefox — and what the session can do; no side effects). Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
100
100
 
101
101
  `browse` and `snapshot` accept `pruneMode: 'act'|'read'`. `act` (default) keeps interactive elements — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If act-mode collapses a content-heavy page near-totally, the snapshot includes a `hint: …` line suggesting `pruneMode='read'` so the agent doesn't bail to a separate HTTP fetch.
102
102
 
103
- Troubleshooting MCP setup: `npx barebrowse doctor` scans every known config location and flags scope conflicts. `npx barebrowse install --force` overwrites an existing entry pointing at a different endpoint.
103
+ `npx barebrowse doctor` reports the runtime environment first — default engine/mode, installed Chromium/Firefox binaries, cookie sources, and any live session's engine + capabilities — then scans every known MCP config location and flags scope conflicts. `npx barebrowse install --force` overwrites an existing entry pointing at a different endpoint.
104
104
 
105
105
  ### 3. Library -- for agentic automation
106
106
 
@@ -152,7 +152,11 @@ Firefox is at practical parity with Chromium: stealth, consent auto-dismiss,
152
152
  ad/tracker blocking, JS dialogs, console/network capture, hybrid fallback,
153
153
  `saveState`, `waitForNavigation`, and download tracking all work the same way.
154
154
  Chromium (CDP) stays the default; the only remaining gap is
155
- `reload({ignoreCache})` (upstream BiDi limitation).
155
+ `reload({ignoreCache})` (upstream BiDi limitation). With no explicit `engine`,
156
+ `connect()` falls back to Firefox (warning once to stderr) if no Chromium
157
+ browser is installed, and throws naming both if neither is; an explicit
158
+ `engine` is always honored and errors on a missing binary instead of silently
159
+ switching.
156
160
 
157
161
  ### Incognito (clean session)
158
162
 
@@ -61,6 +61,8 @@ const snapshot = await browse('https://example.com', {
61
61
 
62
62
  `connect(opts)` returns a page handle for interactive sessions. Same opts as `browse()` for mode. Supports `hybrid` mode — starts headless, auto-launches headed on bot detection (same as `browse()`).
63
63
 
64
+ **TypeScript:** the handle is the exported `Page` type — `import type { Page } from 'barebrowse'`. It's a union of the Chromium and Firefox page shapes: every method in the table below is available directly, while an engine-specific escape hatch (`cdp` on Chromium, `bidi` on Firefox) is reached by narrowing, e.g. `if ('cdp' in page) page.cdp.send(...)`.
65
+
64
66
  | Method | Args | Returns | Notes |
65
67
  |---|---|---|---|
66
68
  | `goto(url, timeout?)` | url: string, timeout: number (default 30000) | void | Navigate + wait for load + dismiss consent |
@@ -92,10 +94,12 @@ const snapshot = await browse('https://example.com', {
92
94
  | `downloads` | -- | Array<{guid, url, suggestedFilename, savedPath, state, totalBytes, receivedBytes}> | Live array of every `Content-Disposition: attachment` download captured during this session. `state`: `inProgress` → `completed` \| `canceled`. |
93
95
  | `cdp` | -- | object | Raw CDP session (getter — survives hybrid fallback and switchTab) for escape hatch: `page.cdp.send(method, params)` |
94
96
  | `createTab()` | -- | tab handle | New tab in same browser. Returns `{ goto, botBlocked, injectCookies, waitForNetworkIdle, cdp, close }`. Tab close doesn't affect session. |
97
+ | `engine` | -- | `'chromium'`\|`'firefox'` | Which engine drives this session. Always readable (both shapes carry it); a typed literal, so it also narrows the union: `if (page.engine === 'firefox') page.bidi.…`. |
98
+ | `capabilities` | -- | object | Feature introspection: `{ engine, mode, attach, escapeHatch, reloadIgnoreCache, downloads, stealth, cookieInjection }`. Ask "what can this session do?" without probing for `cdp`/`bidi`. All fields are launch-fixed except `stealth`, which is a live getter reflecting the session's current headed/headless state (it can flip mid-session after a hybrid bot-challenge relaunch). `reloadIgnoreCache` is false on Firefox (upstream BiDi gap); `downloads`/`stealth`/`cookieInjection` reflect mode + attach + incognito. |
95
99
  | `close()` | -- | void | Close page, disconnect CDP, kill browser (if headless) |
96
100
 
97
101
  **connect() options** (in addition to mode/port/consent):
98
- - `engine: 'chromium'|'firefox'` — Browser engine. Default `chromium` (CDP). `firefox` drives Firefox over WebDriver BiDi (CDP is deprecated there) — a separate transport with the same `page.*` API; the ARIA snapshot is reconstructed in-page since BiDi has no `getFullAXTree`. Consent auto-dismiss and stealth (headless anti-detection) work on Firefox as of v0.16.0; the CLI daemon's console/network capture and `waitForNetworkIdle` work as of v0.17.0; ad/tracker blocking (`blockAds`/`blockUrls`) and JS dialog handling (`dialogLog`/`onDialog`) work as of Phase 3; `hybrid` mode, `saveState`, `waitForNavigation`, and download tracking (`page.downloads`) work as of Phase 4. The only remaining Firefox gap is `reload()` ignoring `ignoreCache` (upstream BiDi limitation).
102
+ - `engine: 'chromium'|'firefox'` — Browser engine. Default `chromium` (CDP). When you don't pass `engine`, `connect()` prefers Chromium but **falls back to Firefox** (with a one-line `console.warn` to stderr) if no Chromium browser is installed; if neither engine is installed it throws naming both. An **explicit** `engine` is always honored — it errors if that engine's binary is missing rather than silently switching. Attach mode (`port`) is Chromium/CDP-only and never falls back. `firefox` drives Firefox over WebDriver BiDi (CDP is deprecated there) — a separate transport with the same `page.*` API; the ARIA snapshot is reconstructed in-page since BiDi has no `getFullAXTree`. Consent auto-dismiss and stealth (headless anti-detection) work on Firefox as of v0.16.0; the CLI daemon's console/network capture and `waitForNetworkIdle` work as of v0.17.0; ad/tracker blocking (`blockAds`/`blockUrls`) and JS dialog handling (`dialogLog`/`onDialog`) work as of Phase 3; `hybrid` mode, `saveState`, `waitForNavigation`, and download tracking (`page.downloads`) work as of Phase 4. The only remaining Firefox gap is `reload()` ignoring `ignoreCache` (upstream BiDi limitation).
99
103
  - `port: 9222` — Attach to a Chromium already running with `--remote-debugging-port=N` instead of spawning one. The browser keeps running on `close()`. Stealth + permission denial + download capture are skipped to avoid mutating the user's running browser.
100
104
  - `proxy: 'http://...'` — HTTP/SOCKS proxy for browser
101
105
  - `viewport: '1280x720'` — Set viewport dimensions
@@ -380,7 +384,7 @@ Useful for agent threshold decisions: "skip sites above score 40", "warn if term
380
384
 
381
385
  9. **Screenshot returns base64.** Write to file with `fs.writeFileSync('shot.png', Buffer.from(base64, 'base64'))` or pass directly to a vision model.
382
386
 
383
- 10. **Chromium-only.** CDP protocol limits us to Chrome, Chromium, Edge, Brave, Vivaldi (~80% desktop share). Firefox support via WebDriver BiDi is not yet implemented.
387
+ 10. **Two engines.** The default is CDP, which drives Chrome, Chromium, Edge, Brave, Vivaldi (~80% desktop share). Firefox is driven over WebDriver BiDi (CDP is deprecated there) — select it with `connect({ engine: 'firefox' })`, CLI `--engine firefox`, or MCP `BAREBROWSE_ENGINE=firefox`. Same `page.*` API on both; feature parity reached in v0.19.x, with the only remaining gap being `reload()` ignoring `ignoreCache` (upstream BiDi limitation). Note the engine is chosen at launch, not per-call. See the `engine` connect() option below for the full parity timeline.
384
388
 
385
389
  11. **`--site-per-process` is on by default (v0.9.0).** Required for iframe support — without it, same-origin iframes stay in the parent process and `Input.dispatchMouseEvent` coords don't match `DOM.getBoxModel` coords for iframe-internal elements. Memory cost: +50-150MB per cross-origin frame. Real Chrome does this for cross-origin by default; we just extend it to all iframes. If you attach via `connect({port})`, the user's browser is whatever they launched it as — for iframe interaction reliability, start it with `--site-per-process` too.
386
390
 
package/cli.js CHANGED
@@ -25,7 +25,7 @@ if (args.includes('--daemon-internal')) {
25
25
  } else if (cmd === 'install') {
26
26
  install();
27
27
  } else if (cmd === 'doctor') {
28
- doctor();
28
+ await doctor();
29
29
  } else if (cmd === 'browse' && args[1]) {
30
30
  await oneShot();
31
31
  } else if (cmd === 'open') {
@@ -411,7 +411,75 @@ function readJsonOrEmpty(path) {
411
411
  * absolute endpoints across scopes — OAuth tokens are stored per-endpoint
412
412
  * so a split silently breaks auth.
413
413
  */
414
- function doctor() {
414
+ async function doctor() {
415
+ await doctorEnvironment();
416
+ doctorMcpConfig();
417
+ }
418
+
419
+ /**
420
+ * Report the runtime environment: which engine/mode a session would use, which
421
+ * browsers and cookie sources are actually installed, and whether a session is
422
+ * live in this directory. This is the "which engine am I on and what can it do?"
423
+ * answer — the gap that led a peer session to conclude Firefox wasn't supported
424
+ * when it is (selected via BAREBROWSE_ENGINE / --engine, not a per-tool flag).
425
+ */
426
+ async function doctorEnvironment() {
427
+ const { findBrowser } = await import('./src/chromium.js');
428
+ const { findFirefox } = await import('./src/firefox.js');
429
+ const { findChromiumCookieDb, findFirefoxCookieDb } = await import('./src/auth.js');
430
+
431
+ console.log('barebrowse doctor — runtime environment:\n');
432
+ console.log(` Node ${process.version} on ${platform()}`);
433
+
434
+ // Configured engine/mode/incognito. MCP selects the engine at server launch
435
+ // via these env vars (mcp-server.js), which a running session can't see —
436
+ // surfacing them here is the whole point.
437
+ const engine = process.env.BAREBROWSE_ENGINE === 'firefox' ? 'firefox' : 'chromium';
438
+ const modeEnv = process.env.BAREBROWSE_MODE;
439
+ const incognito = process.env.BAREBROWSE_INCOGNITO === '1';
440
+ console.log(` Default engine: ${engine} (override: BAREBROWSE_ENGINE=firefox | --engine firefox | connect({engine}))`);
441
+ // Mode default differs by surface: CLI `open` → headless, MCP → hybrid.
442
+ // BAREBROWSE_MODE overrides both, so report it directly when set.
443
+ console.log(` Default mode: ${modeEnv ? `${modeEnv} (BAREBROWSE_MODE)` : 'headless (CLI open) / hybrid (MCP)'}`);
444
+ console.log(` Incognito: ${incognito ? 'on (BAREBROWSE_INCOGNITO=1) — no cookie injection' : 'off'}`);
445
+
446
+ // Installed browsers — both engines. A missing one explains why an --engine
447
+ // choice would fail before it launches.
448
+ console.log('\n Installed browsers:');
449
+ let chromiumPath = null, firefoxPath = null;
450
+ try { chromiumPath = findBrowser(); } catch { /* none */ }
451
+ try { firefoxPath = findFirefox(); } catch { /* none */ }
452
+ console.log(` Chromium/CDP: ${chromiumPath || 'NOT FOUND — install chrome/chromium/brave/edge'}`);
453
+ console.log(` Firefox/BiDi: ${firefoxPath || 'NOT FOUND — install firefox (>= 121 for stable BiDi)'}`);
454
+
455
+ // Cookie sources — where authenticated sessions come from (skipped in incognito).
456
+ console.log('\n Cookie sources:');
457
+ const chromiumCookies = findChromiumCookieDb();
458
+ const firefoxCookies = findFirefoxCookieDb();
459
+ console.log(` Chromium: ${chromiumCookies ? `${chromiumCookies.browser} (${chromiumCookies.path})` : 'none found'}`);
460
+ console.log(` Firefox: ${firefoxCookies || 'none found'}`);
461
+
462
+ // Live session in this directory, if any — reports its actual engine +
463
+ // capabilities (persisted into session.json by the daemon).
464
+ const { readSession, isAlive } = await import('./src/session-client.js');
465
+ const outputDir = resolve('.barebrowse');
466
+ const session = readSession(outputDir);
467
+ console.log('\n Active session (this directory):');
468
+ if (!session) {
469
+ console.log(' none — run `barebrowse open [url]` to start one');
470
+ } else if (!(await isAlive(outputDir))) {
471
+ console.log(` stale (pid ${session.pid} not responding) — run \`barebrowse close\` to clean up`);
472
+ } else {
473
+ console.log(` running (pid ${session.pid}, port ${session.port}, engine ${session.engine || 'chromium'})`);
474
+ if (session.capabilities) {
475
+ const c = session.capabilities;
476
+ console.log(` mode=${c.mode} attach=${c.attach} downloads=${c.downloads} stealth=${c.stealth} cookies=${c.cookieInjection} reloadIgnoreCache=${c.reloadIgnoreCache}`);
477
+ }
478
+ }
479
+ console.log('');
480
+ }
481
+
482
+ function doctorMcpConfig() {
415
483
  const home = homedir();
416
484
  const cwd = process.cwd();
417
485
  const os = platform();
@@ -553,7 +621,8 @@ MCP:
553
621
  barebrowse mcp Start MCP server (JSON-RPC over stdio)
554
622
  barebrowse install [--force] Add barebrowse to detected MCP clients (--force replaces stale entries)
555
623
  barebrowse install --skill Install Claude Code skill file
556
- barebrowse doctor Scan MCP config locations for barebrowse entries + flag scope conflicts
624
+ barebrowse doctor Report engine/mode/browsers/cookie sources + active session,
625
+ then scan MCP config locations + flag scope conflicts
557
626
  barebrowse install Auto-configure MCP for Claude Desktop / Cursor
558
627
  barebrowse install --skill Install SKILL.md for Claude Code
559
628
 
package/mcp-server.js CHANGED
@@ -118,6 +118,31 @@ export function saveSnapshot(text, { prefix = 'page', ext = 'yml' } = {}) {
118
118
  let _page = null;
119
119
  let _pageConnecting = null;
120
120
 
121
+ /**
122
+ * The engine + mode this server is configured to use, derived from env WITHOUT
123
+ * launching a browser. Both engines ship in the library; which one this server
124
+ * drives is fixed at launch by BAREBROWSE_ENGINE and cannot change mid-session
125
+ * (one browser is connected and reused across tool calls). Surfaced to the
126
+ * agent via `initialize.instructions`, the `capabilities` tool, and the `browse`
127
+ * tool description so the Firefox engine is discoverable — it was invisible
128
+ * before, and a session concluded (wrongly) that only Chromium was supported.
129
+ */
130
+ function engineInfo() {
131
+ const engine = process.env.BAREBROWSE_ENGINE === 'firefox' ? 'firefox' : 'chromium';
132
+ const mode = process.env.BAREBROWSE_MODE || 'hybrid';
133
+ const incognito = process.env.BAREBROWSE_INCOGNITO === '1';
134
+ return {
135
+ activeEngine: engine,
136
+ mode,
137
+ incognito,
138
+ availableEngines: ['chromium', 'firefox'],
139
+ // Engine is chosen once at server launch — the agent cannot switch it.
140
+ switchEngine:
141
+ "To use the other engine, restart the MCP server with BAREBROWSE_ENGINE=firefox "
142
+ + "(or unset it for the chromium default). It cannot be changed during a session.",
143
+ };
144
+ }
145
+
121
146
  async function getPage() {
122
147
  if (_page) return _page;
123
148
  if (_pageConnecting) return _pageConnecting;
@@ -363,6 +388,11 @@ export const TOOLS = [
363
388
  required: ['ref'],
364
389
  },
365
390
  },
391
+ {
392
+ name: 'capabilities',
393
+ description: 'Report which browser engine this session drives (chromium or firefox) and what it can do — no navigation, no side effects. Use it to answer "can this drive Firefox?" or "is this an authenticated session?". Returns the active engine + mode, that both engines are supported, how to switch (a server-restart env var; the engine is fixed for a running session), and, if a page is already open, its live capability flags.',
394
+ inputSchema: { type: 'object', properties: {} },
395
+ },
366
396
  ];
367
397
 
368
398
  // Powerful escape hatch — guarded behind an explicit env-var opt-in.
@@ -402,6 +432,19 @@ if (assessFn) {
402
432
 
403
433
  async function handleToolCall(name, args) {
404
434
  switch (name) {
435
+ case 'capabilities': {
436
+ // Introspection only — must NOT launch a browser. Report the configured
437
+ // engine from env; if a page is already connected, attach its live flags.
438
+ const info = engineInfo();
439
+ if (_page) {
440
+ info.connected = true;
441
+ info.capabilities = _page.capabilities;
442
+ } else {
443
+ info.connected = false;
444
+ info.capabilities = null; // populated on first navigation
445
+ }
446
+ return info;
447
+ }
405
448
  case 'browse': {
406
449
  let timer;
407
450
  const text = await Promise.race([
@@ -620,10 +663,17 @@ async function handleMessage(msg) {
620
663
  const { id, method, params } = msg;
621
664
 
622
665
  if (method === 'initialize') {
666
+ const e = engineInfo();
623
667
  return jsonrpcResponse(id, {
624
668
  protocolVersion: '2024-11-05',
625
669
  capabilities: { tools: {} },
626
670
  serverInfo: { name: 'barebrowse', version: PKG_VERSION },
671
+ // Tell the agent which engine is live + that the other exists. `instructions`
672
+ // is a standard MCP field clients may show to the model.
673
+ instructions:
674
+ `barebrowse drives a real browser. Active engine: ${e.activeEngine} (mode: ${e.mode}). `
675
+ + `Both chromium and firefox are supported; ${e.switchEngine} `
676
+ + `Call the "capabilities" tool for the live engine + feature set.`,
627
677
  });
628
678
  }
629
679
 
@@ -632,7 +682,13 @@ async function handleMessage(msg) {
632
682
  }
633
683
 
634
684
  if (method === 'tools/list') {
635
- return jsonrpcResponse(id, { tools: TOOLS });
685
+ // Append the live engine note to the `browse` entry-point description so the
686
+ // active engine (and that both are supported) is visible without a call.
687
+ const e = engineInfo();
688
+ const note = ` [Active engine: ${e.activeEngine}; chromium + firefox both supported — ${e.switchEngine}]`;
689
+ const tools = TOOLS.map((t) =>
690
+ t.name === 'browse' ? { ...t, description: t.description + note } : t);
691
+ return jsonrpcResponse(id, { tools });
636
692
  }
637
693
 
638
694
  if (method === 'tools/call') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "barebrowse",
3
- "version": "0.19.2",
3
+ "version": "0.21.0",
4
4
  "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
5
5
  "repository": {
6
6
  "type": "git",
package/src/auth.js CHANGED
@@ -30,7 +30,7 @@ const CHROMIUM_PATHS = {
30
30
  * Find first available Chromium cookie database.
31
31
  * @returns {{ path: string, browser: string } | null}
32
32
  */
33
- function findChromiumCookieDb() {
33
+ export function findChromiumCookieDb() {
34
34
  for (const [browser, path] of Object.entries(CHROMIUM_PATHS)) {
35
35
  if (existsSync(path)) return { path, browser };
36
36
  }
@@ -41,7 +41,7 @@ function findChromiumCookieDb() {
41
41
  * Find Firefox default profile cookies.
42
42
  * @returns {string | null} Path to cookies.sqlite
43
43
  */
44
- function findFirefoxCookieDb() {
44
+ export function findFirefoxCookieDb() {
45
45
  const base = `${HOME}/.mozilla/firefox`;
46
46
  try {
47
47
  for (const entry of readdirSync(base)) {
package/src/daemon.js CHANGED
@@ -610,6 +610,10 @@ export async function runDaemon(opts, outputDir, initialUrl) {
610
610
  pid: process.pid,
611
611
  token: authToken,
612
612
  startedAt: new Date().toISOString(),
613
+ // Persisted so `status`/`doctor` can report the live engine + feature set
614
+ // without an HTTP round-trip (page.engine/capabilities, added in v0.21.0).
615
+ engine: page.engine,
616
+ capabilities: page.capabilities,
613
617
  }));
614
618
 
615
619
  // Handle SIGTERM gracefully
@@ -46,7 +46,6 @@ const BIDI_KEYS = {
46
46
  * @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
47
47
  * @param {boolean} [opts.headed=false] - Whether the browser was launched headed (skips hybrid fallback).
48
48
  * @param {?function(): Promise<{bidi: object, topContext: string}>} [opts.relaunchHeaded] - Hybrid relaunch hook (from connectFirefox).
49
- * @returns {Promise<object>} page object
50
49
  */
51
50
  export async function createFirefoxPage(bidi, opts = {}) {
52
51
  const defaultPruneMode = opts.pruneMode || 'act';
@@ -286,6 +285,28 @@ export async function createFirefoxPage(bidi, opts = {}) {
286
285
  /** Whether the last goto() landed on a bot-challenge page (parity w/ CDP). */
287
286
  get botBlocked() { return botBlocked; },
288
287
 
288
+ /** @type {'firefox'} Engine driving this session (see also `capabilities`). */
289
+ engine: 'firefox',
290
+
291
+ /**
292
+ * Introspection of this session's engine, mode, and feature support —
293
+ * mirrors connect()'s Chromium `page.capabilities`. Fields are launch-fixed
294
+ * except `stealth`, a live getter tracking the current headed/headless
295
+ * state. `reloadIgnoreCache` is false here (upstream BiDi gap); Firefox is
296
+ * never attach mode.
297
+ * @type {import('./index.js').Capabilities}
298
+ */
299
+ capabilities: {
300
+ engine: 'firefox',
301
+ mode: hybrid ? 'hybrid' : (opts.headed ? 'headed' : 'headless'),
302
+ attach: false,
303
+ escapeHatch: 'bidi',
304
+ reloadIgnoreCache: false,
305
+ downloads: true,
306
+ get stealth() { return !currentlyHeaded; },
307
+ cookieInjection: !incognito,
308
+ },
309
+
289
310
  async goto(url, timeout = 30000) {
290
311
  // Same navigation guard the CDP path enforces — block file:/chrome:/
291
312
  // view-source: and (optionally) private-network hosts before navigating.
@@ -326,7 +347,8 @@ export async function createFirefoxPage(bidi, opts = {}) {
326
347
  }
327
348
  },
328
349
 
329
- async snapshot(pruneOpts) {
350
+ /** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
351
+ async snapshot(pruneOpts = {}) {
330
352
  const root = await buildTree();
331
353
  if (!root) return '';
332
354
 
@@ -349,6 +371,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
349
371
 
350
372
  async click(ref) { await pointerClick(ref); },
351
373
 
374
+ /** @param {string} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
352
375
  async type(ref, text, typeOpts = {}) {
353
376
  const { context, sharedId } = await resolveRef(ref);
354
377
  // Focus the field (and optionally clear it) in-page, then send real key
@@ -391,7 +414,8 @@ export async function createFirefoxPage(bidi, opts = {}) {
391
414
  * via BiDi storage.setCookie. Scoped to the URL host via the SHARED
392
415
  * scopedCookiesForUrl (same as the CDP path) — never the whole jar.
393
416
  */
394
- async injectCookies(url, cookieOpts) {
417
+ /** @param {string} url @param {import('./index.js').CookieOptions} [cookieOpts] */
418
+ async injectCookies(url, cookieOpts = {}) {
395
419
  if (incognito) return 0;
396
420
  lastInject = { url, cookieOpts }; // remember for a hybrid re-inject
397
421
  const cookies = scopedCookiesForUrl(url, { browser: cookieOpts?.browser });
package/src/index.js CHANGED
@@ -8,8 +8,8 @@
8
8
  * const snapshot = await browse('https://example.com');
9
9
  */
10
10
 
11
- import { launch, attach, cleanupBrowser } from './chromium.js';
12
- import { launchFirefox, cleanupFirefox } from './firefox.js';
11
+ import { launch, attach, cleanupBrowser, findBrowser } from './chromium.js';
12
+ import { launchFirefox, cleanupFirefox, findFirefox } from './firefox.js';
13
13
  import { createCDP } from './cdp.js';
14
14
  import { createBiDi } from './bidi.js';
15
15
  import { createFirefoxPage } from './firefox-page.js';
@@ -162,6 +162,60 @@ export async function browse(url, opts = {}) {
162
162
  }
163
163
  }
164
164
 
165
+ /**
166
+ * The interactive page handle returned by {@link connect}. Inferred structurally
167
+ * from the returned object literals — no hand-maintained interface to drift.
168
+ *
169
+ * It is a union of the two engine page shapes (Chromium/CDP and Firefox/BiDi),
170
+ * which share every interaction method (`goto`, `snapshot`, `click`, `type`,
171
+ * `close`, …) but differ in their escape hatches — `cdp`/`createTab`/`dialogLog`
172
+ * on Chromium, `bidi`/`context` on Firefox. The shared methods dereference
173
+ * without narrowing; an engine-specific hatch requires knowing the engine
174
+ * (the default is Chromium), e.g. `if ('cdp' in page) page.cdp.send(...)`.
175
+ * Both shapes carry `page.engine` (`'chromium'`|`'firefox'`) and a
176
+ * `page.capabilities` object so a caller can introspect which engine drives
177
+ * the session and what it supports without probing for an escape hatch.
178
+ * @typedef {Awaited<ReturnType<typeof connect>>} Page
179
+ */
180
+
181
+ /**
182
+ * Description of what the current session can do — engine, mode, and the
183
+ * mode/engine-derived feature flags that actually differ between sessions. Read
184
+ * it via `page.capabilities` instead of inferring from the engine name. All
185
+ * fields are launch-fixed engine/mode facts except `stealth`, which reflects
186
+ * the CURRENT headed/headless state and can flip mid-session after a hybrid
187
+ * bot-challenge fallback relaunches a headed browser. `attach` is Chromium
188
+ * `connect({port})` (no stealth/downloads); `reloadIgnoreCache` is false on
189
+ * Firefox (upstream BiDi gap). Each remaining flag has its own driver:
190
+ * `downloads` is off when attached, `stealth` off when attached or headed,
191
+ * `cookieInjection` off in incognito.
192
+ * @typedef {object} Capabilities
193
+ * @property {'chromium'|'firefox'} engine - Engine driving this session
194
+ * @property {'headless'|'headed'|'hybrid'} mode - Launch mode
195
+ * @property {boolean} attach - Attached to a user-launched browser (Chromium only)
196
+ * @property {'cdp'|'bidi'} escapeHatch - Name of the raw-protocol escape-hatch property
197
+ * @property {boolean} reloadIgnoreCache - `reload({ignoreCache})` is honored
198
+ * @property {boolean} downloads - `page.downloads` is populated
199
+ * @property {boolean} stealth - Headless anti-detection is currently active (live — reflects present headed/headless state, not just launch mode)
200
+ * @property {boolean} cookieInjection - Cookie extraction/injection is active (off in incognito)
201
+ */
202
+
203
+ /**
204
+ * Options for `page.snapshot()`. Pass `false` instead of an object to skip
205
+ * pruning and return the raw ARIA tree.
206
+ * @typedef {{ mode?: 'act'|'browse'|'navigate'|'full'|'read' }} SnapshotOptions
207
+ */
208
+
209
+ /**
210
+ * Options for `page.type()`.
211
+ * @typedef {{ clear?: boolean, keyEvents?: boolean }} TypeOptions
212
+ */
213
+
214
+ /**
215
+ * Options for `page.injectCookies()`.
216
+ * @typedef {{ browser?: string }} CookieOptions
217
+ */
218
+
165
219
  /**
166
220
  * Connect to a browser for a long-lived interactive session.
167
221
  *
@@ -206,14 +260,57 @@ export async function browse(url, opts = {}) {
206
260
  * @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
207
261
  * 'firefox' drives over WebDriver BiDi (a separate transport / page object);
208
262
  * 'chromium' (default) uses CDP.
209
- * @returns {Promise<object>} Page handle with goto, snapshot, close
263
+ * @returns The interactive page handle — see the exported `Page` typedef. The
264
+ * return type is left uninferred here (no `{...}` tag) so tsc derives it
265
+ * structurally from the returned object literals; annotating it as `Page`
266
+ * would be a self-reference, since `Page` is `ReturnType<typeof connect>`.
267
+ */
268
+ /** True if a browser finder resolves a binary; false if it throws (none found). */
269
+ function canFind(finder) {
270
+ try { finder(); return true; } catch { return false; }
271
+ }
272
+
273
+ /**
274
+ * Decide which engine connect() should use. Pure — the caller passes lazy
275
+ * probe thunks so this is unit-testable without launching a browser.
276
+ * An explicit `opts.engine` is always honored (existence is checked downstream
277
+ * by launch()/connectFirefox(), which throw a clear install message if missing).
278
+ * Attach mode (`opts.port`) is CDP/Chromium-only. Otherwise (no engine picked)
279
+ * prefer Chromium, fall back to Firefox, and if neither is installed throw.
280
+ * @param {{engine?: string, port?: number}} opts
281
+ * @param {{hasChromium: () => boolean, hasFirefox: () => boolean}} probe
282
+ * @returns {{engine: 'chromium'|'firefox', fellBack: boolean}}
210
283
  */
284
+ export function resolveEngine(opts, probe) {
285
+ if (opts.engine === 'firefox') return { engine: 'firefox', fellBack: false };
286
+ if (opts.engine === 'chromium') return { engine: 'chromium', fellBack: false };
287
+ if (opts.port) return { engine: 'chromium', fellBack: false };
288
+ if (probe.hasChromium()) return { engine: 'chromium', fellBack: false };
289
+ if (probe.hasFirefox()) return { engine: 'firefox', fellBack: true };
290
+ throw new Error(
291
+ 'No supported browser found. Install a Chromium browser (chrome, chromium, '
292
+ + 'brave, or edge) or Firefox (>= 121 for stable WebDriver BiDi).',
293
+ );
294
+ }
295
+
211
296
  export async function connect(opts = {}) {
212
297
  // Firefox is driven over WebDriver BiDi (CDP is deprecated there) — a
213
298
  // separate transport with its own page object. It reuses prune.js/aria.js/
214
299
  // readable.js but none of the CDP page machinery below, so branch early.
215
- if (opts.engine === 'firefox') {
216
- return connectFirefox(opts);
300
+ const { engine: resolvedEngine, fellBack } = resolveEngine(opts, {
301
+ hasChromium: () => canFind(findBrowser),
302
+ hasFirefox: () => canFind(findFirefox),
303
+ });
304
+ if (resolvedEngine === 'firefox') {
305
+ if (fellBack) {
306
+ // Loud, to stderr (stdout is data on CLI/MCP). Only fires on the default
307
+ // path — an explicit engine never falls back, so never warns.
308
+ console.warn(
309
+ 'barebrowse: no Chromium browser found — falling back to Firefox over '
310
+ + 'WebDriver BiDi. Pass engine explicitly to silence this.',
311
+ );
312
+ }
313
+ return connectFirefox({ ...opts, engine: 'firefox' });
217
314
  }
218
315
 
219
316
  const mode = opts.mode || 'headless';
@@ -452,14 +549,16 @@ export async function connect(opts = {}) {
452
549
  refMap = new Map(); // refs from the pre-reload page are invalid
453
550
  },
454
551
 
455
- async injectCookies(url, cookieOpts) {
552
+ /** @param {string} url @param {CookieOptions} [cookieOpts] */
553
+ async injectCookies(url, cookieOpts = {}) {
456
554
  // No-op under incognito: callers (MCP goto, daemon) inject unconditionally,
457
555
  // so the gate has to live here, not just at the call site.
458
556
  if (incognito) return 0;
459
557
  return authenticate(page.session, url, { browser: cookieOpts?.browser });
460
558
  },
461
559
 
462
- async snapshot(pruneOpts) {
560
+ /** @param {SnapshotOptions|false} [pruneOpts] */
561
+ async snapshot(pruneOpts = {}) {
463
562
  const result = await ariaTree(page);
464
563
  refMap = result.refMap;
465
564
  const raw = formatTree(result.tree);
@@ -490,7 +589,8 @@ export async function connect(opts = {}) {
490
589
  await cdpClick(entry.session, entry.backendNodeId);
491
590
  },
492
591
 
493
- async type(ref, text, typeOpts) {
592
+ /** @param {string} ref @param {string} text @param {TypeOptions} [typeOpts] */
593
+ async type(ref, text, typeOpts = {}) {
494
594
  const entry = refMap.get(ref);
495
595
  if (!entry) throw new Error(`No element found for ref "${ref}"`);
496
596
  await cdpType(entry.session, entry.backendNodeId, text, typeOpts);
@@ -612,6 +712,28 @@ export async function connect(opts = {}) {
612
712
 
613
713
  get botBlocked() { return botBlocked; },
614
714
 
715
+ /** @type {'chromium'} Engine driving this session (see also `capabilities`) */
716
+ engine: 'chromium',
717
+
718
+ /**
719
+ * Introspection of this session's engine, mode, and feature support — see
720
+ * the `Capabilities` typedef. Fields are launch-fixed except `stealth`,
721
+ * which is a live getter tracking the current headed/headless state (flips
722
+ * after a hybrid headed relaunch). Lets a caller ask "which engine am I on
723
+ * and what can it do?" without probing for `cdp`/`bidi`.
724
+ * @type {Capabilities}
725
+ */
726
+ capabilities: {
727
+ engine: 'chromium',
728
+ mode,
729
+ attach: attachMode,
730
+ escapeHatch: 'cdp',
731
+ reloadIgnoreCache: true,
732
+ downloads: !attachMode,
733
+ get stealth() { return !attachMode && !currentlyHeaded; },
734
+ cookieInjection: !incognito,
735
+ },
736
+
615
737
  dialogLog,
616
738
 
617
739
  /**
@@ -671,7 +793,8 @@ export async function connect(opts = {}) {
671
793
  tabBotBlocked = isChallengePage(tree, nodeCount);
672
794
  },
673
795
  get botBlocked() { return tabBotBlocked; },
674
- async injectCookies(url, cookieOpts) {
796
+ /** @param {string} url @param {CookieOptions} [cookieOpts] */
797
+ async injectCookies(url, cookieOpts = {}) {
675
798
  if (incognito) return 0;
676
799
  return authenticate(tab.session, url, { browser: cookieOpts?.browser });
677
800
  },
@@ -743,7 +866,6 @@ async function suppressPermissions(cdp) {
743
866
  * The navigation guard (`allowLocalUrls`/`blockPrivateNetwork`), `uploadDir`
744
867
  * sandbox, `incognito`, `proxy`, `viewport`, and `pruneMode` all apply.
745
868
  * @param {object} opts - connect() options ({ mode, proxy, binary, viewport, pruneMode, urlGuard, uploadDir, incognito, downloadPath, blockAds, blockUrls })
746
- * @returns {Promise<object>} Firefox page object
747
869
  */
748
870
  async function connectFirefox(opts) {
749
871
  const hybrid = opts.mode === 'hybrid';
package/types/auth.d.ts CHANGED
@@ -1,3 +1,16 @@
1
+ /**
2
+ * Find first available Chromium cookie database.
3
+ * @returns {{ path: string, browser: string } | null}
4
+ */
5
+ export function findChromiumCookieDb(): {
6
+ path: string;
7
+ browser: string;
8
+ } | null;
9
+ /**
10
+ * Find Firefox default profile cookies.
11
+ * @returns {string | null} Path to cookies.sqlite
12
+ */
13
+ export function findFirefoxCookieDb(): string | null;
1
14
  /**
2
15
  * Extract cookies from the user's browser, auto-detecting which browser to use.
3
16
  * @param {object} [opts]
@@ -10,7 +10,6 @@
10
10
  * @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
11
11
  * @param {boolean} [opts.headed=false] - Whether the browser was launched headed (skips hybrid fallback).
12
12
  * @param {?function(): Promise<{bidi: object, topContext: string}>} [opts.relaunchHeaded] - Hybrid relaunch hook (from connectFirefox).
13
- * @returns {Promise<object>} page object
14
13
  */
15
14
  export function createFirefoxPage(bidi: object, opts?: {
16
15
  pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
@@ -27,4 +26,86 @@ export function createFirefoxPage(bidi: object, opts?: {
27
26
  bidi: object;
28
27
  topContext: string;
29
28
  }>) | null | undefined;
30
- }): Promise<object>;
29
+ }): Promise<{
30
+ /** The BiDi escape hatch, analogous to connect()'s page.cdp. */
31
+ readonly bidi: any;
32
+ /** The active browsing-context id (getter so it tracks switchTab). */
33
+ readonly context: any;
34
+ /** Whether the last goto() landed on a bot-challenge page (parity w/ CDP). */
35
+ readonly botBlocked: boolean;
36
+ /** @type {'firefox'} Engine driving this session (see also `capabilities`). */
37
+ engine: "firefox";
38
+ /**
39
+ * Introspection of this session's engine, mode, and feature support —
40
+ * mirrors connect()'s Chromium `page.capabilities`. Fields are launch-fixed
41
+ * except `stealth`, a live getter tracking the current headed/headless
42
+ * state. `reloadIgnoreCache` is false here (upstream BiDi gap); Firefox is
43
+ * never attach mode.
44
+ * @type {import('./index.js').Capabilities}
45
+ */
46
+ capabilities: import("./index.js").Capabilities;
47
+ goto(url: any, timeout?: number): Promise<void>;
48
+ /** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
49
+ snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
50
+ readable(): Promise<any>;
51
+ click(ref: any): Promise<void>;
52
+ /** @param {string} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
53
+ type(ref: string, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
54
+ press(key: any): Promise<void>;
55
+ scroll(deltaY: any): Promise<void>;
56
+ hover(ref: any): Promise<void>;
57
+ /**
58
+ * Inject cookies from the user's real browser into this Firefox session,
59
+ * via BiDi storage.setCookie. Scoped to the URL host via the SHARED
60
+ * scopedCookiesForUrl (same as the CDP path) — never the whole jar.
61
+ */
62
+ /** @param {string} url @param {import('./index.js').CookieOptions} [cookieOpts] */
63
+ injectCookies(url: string, cookieOpts?: import("./index.js").CookieOptions): Promise<number>;
64
+ select(ref: any, value: any): Promise<void>;
65
+ drag(fromRef: any, toRef: any): Promise<void>;
66
+ upload(ref: any, files: any): Promise<void>;
67
+ goBack(): Promise<void>;
68
+ goForward(): Promise<void>;
69
+ reload(): Promise<void>;
70
+ screenshot(screenshotOpts?: {}): Promise<any>;
71
+ pdf(pdfOpts?: {}): Promise<any>;
72
+ tabs(): Promise<{
73
+ index: number;
74
+ url: any;
75
+ title: any;
76
+ context: any;
77
+ }[]>;
78
+ switchTab(index: any): Promise<void>;
79
+ waitFor(waitOpts?: {}): Promise<void>;
80
+ /**
81
+ * Wait until the network has been idle for `idle` ms, over BiDi
82
+ * network.* events. Parity with the CDP page.waitForNetworkIdle (Phase 2).
83
+ */
84
+ waitForNetworkIdle(idleOpts?: {}): Promise<void>;
85
+ /** Downloads that began in this session (Phase 4 — see setupDownloads). */
86
+ readonly downloads: any[];
87
+ dialogLog: any[];
88
+ /**
89
+ * Install a custom JS dialog handler, mirroring connect()'s page.onDialog.
90
+ * Called with `{ type, message, defaultPrompt }`; may return (sync or async)
91
+ * `{ accept: bool, promptText: string }` to override the auto-accept
92
+ * default. Pass null to restore default behavior.
93
+ */
94
+ onDialog(handler: any): void;
95
+ /**
96
+ * Persist cookies + localStorage to a JSON file (parity with the CDP
97
+ * saveState). Cookies come from BiDi storage.getCookies (whose value is a
98
+ * `{type,value}` object) and are flattened to the CDP-symmetric shape so the
99
+ * file format matches across engines. Written 0600 — it holds session
100
+ * tokens, so a multi-user host must not be able to read another user's.
101
+ */
102
+ saveState(filePath: any): Promise<void>;
103
+ /**
104
+ * Resolve when the active tab fires its next load event (parity with the
105
+ * CDP waitForNavigation → Page.loadEventFired). Scoped to topContext so a
106
+ * subframe load can't resolve it early. Falls back to a short settle delay
107
+ * for SPA navigations that fire no load event.
108
+ */
109
+ waitForNavigation(timeout?: number): Promise<void>;
110
+ close(): Promise<void>;
111
+ }>;
package/types/index.d.ts CHANGED
@@ -29,7 +29,7 @@
29
29
  * @returns {Promise<string>} ARIA snapshot text
30
30
  */
31
31
  export function browse(url: string, opts?: {
32
- mode?: "headed" | "headless" | "hybrid" | undefined;
32
+ mode?: "headed" | "hybrid" | "headless" | undefined;
33
33
  cookies?: boolean | undefined;
34
34
  incognito?: boolean | undefined;
35
35
  prune?: boolean | undefined;
@@ -50,73 +50,125 @@ export function browse(url: string, opts?: {
50
50
  pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
51
51
  }): Promise<string>;
52
52
  /**
53
- * Connect to a browser for a long-lived interactive session.
54
- *
55
- * @param {object} [opts]
56
- * @param {'headless'|'headed'|'hybrid'} [opts.mode='headless'] - Browser mode
57
- * @param {number} [opts.port] - Attach to an already-running Chromium at this
58
- * CDP port instead of launching a new one. The browser keeps running on
59
- * close(); only the tab we created is torn down. Use this to drive a
60
- * user's logged-in session (start Chromium with --remote-debugging-port=N).
61
- * @param {string} [opts.downloadPath] - Directory to save downloaded files.
62
- * Default: a per-session subdirectory under the OS temp dir. Downloads
63
- * land here as <guid>; check `page.downloads` for { url, suggestedFilename,
64
- * savedPath, state, totalBytes, receivedBytes } per file.
65
- * @param {boolean} [opts.blockAds] - Block ~120 common ad/tracker URL
66
- * patterns via CDP. Defaults to true for launched browsers, false in
67
- * attach mode (would affect any tab attached to the user's running
68
- * session). Setting blockAds:true explicitly in attach mode honors the
69
- * request — blocking applies to whichever tab the session is currently
70
- * attached to and follows the session across switchTab() until close.
71
- * @param {string[]} [opts.blockUrls] - Extra URL glob patterns to block,
72
- * merged with the default unless blockAds is false.
73
- * @param {boolean} [opts.allowLocalUrls=false] - Permit navigation to local-
74
- * resource schemes (file:, view-source:, chrome:, …). Blocked by default
75
- * because a prompt-injected agent could use them to read local files.
76
- * @param {boolean} [opts.blockPrivateNetwork=false] - Reject navigation to
77
- * loopback / RFC-1918 / link-local / cloud-metadata hosts (SSRF guard).
78
- * Off by default so localhost dev-server browsing keeps working.
79
- * @param {string} [opts.uploadDir] - When set, upload() rejects any file that
80
- * does not resolve (symlinks included) inside this directory. Sandboxes the
81
- * agent's file-upload capability. Default: no restriction.
82
- * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port').
83
- * @param {string} [opts.binary] - Path to browser binary (auto-detected if omitted).
84
- * @param {string} [opts.userDataDir] - Browser profile directory.
85
- * @param {{width: number, height: number}} [opts.viewport] - Viewport dimensions.
86
- * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
87
- * @param {string} [opts.storageState] - Path to a storage-state JSON file
88
- * (cookies + localStorage) to load before navigation.
89
- * @param {boolean} [opts.incognito=false] - Clean, unauthenticated session:
90
- * skip storageState loading and make injectCookies() a no-op, so no auth
91
- * ever enters the session even if a caller injects unconditionally.
92
- * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
93
- * @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
94
- * 'firefox' drives over WebDriver BiDi (a separate transport / page object);
95
- * 'chromium' (default) uses CDP.
96
- * @returns {Promise<object>} Page handle with goto, snapshot, close
53
+ * Decide which engine connect() should use. Pure — the caller passes lazy
54
+ * probe thunks so this is unit-testable without launching a browser.
55
+ * An explicit `opts.engine` is always honored (existence is checked downstream
56
+ * by launch()/connectFirefox(), which throw a clear install message if missing).
57
+ * Attach mode (`opts.port`) is CDP/Chromium-only. Otherwise (no engine picked)
58
+ * prefer Chromium, fall back to Firefox, and if neither is installed throw.
59
+ * @param {{engine?: string, port?: number}} opts
60
+ * @param {{hasChromium: () => boolean, hasFirefox: () => boolean}} probe
61
+ * @returns {{engine: 'chromium'|'firefox', fellBack: boolean}}
97
62
  */
98
- export function connect(opts?: {
99
- mode?: "headed" | "headless" | "hybrid" | undefined;
100
- port?: number | undefined;
101
- downloadPath?: string | undefined;
102
- blockAds?: boolean | undefined;
103
- blockUrls?: string[] | undefined;
104
- allowLocalUrls?: boolean | undefined;
105
- blockPrivateNetwork?: boolean | undefined;
106
- uploadDir?: string | undefined;
107
- proxy?: string | undefined;
108
- binary?: string | undefined;
109
- userDataDir?: string | undefined;
110
- viewport?: {
111
- width: number;
112
- height: number;
113
- } | undefined;
114
- consent?: boolean | undefined;
115
- storageState?: string | undefined;
116
- incognito?: boolean | undefined;
117
- pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
118
- engine?: "chromium" | "firefox" | undefined;
119
- }): Promise<object>;
63
+ export function resolveEngine(opts: {
64
+ engine?: string;
65
+ port?: number;
66
+ }, probe: {
67
+ hasChromium: () => boolean;
68
+ hasFirefox: () => boolean;
69
+ }): {
70
+ engine: "chromium" | "firefox";
71
+ fellBack: boolean;
72
+ };
73
+ export function connect(opts?: {}): Promise<{
74
+ readonly bidi: any;
75
+ readonly context: any;
76
+ readonly botBlocked: boolean;
77
+ engine: "firefox";
78
+ capabilities: import("./index.js").Capabilities;
79
+ goto(url: any, timeout?: number): Promise<void>;
80
+ snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
81
+ readable(): Promise<any>;
82
+ click(ref: any): Promise<void>;
83
+ type(ref: string, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
84
+ press(key: any): Promise<void>;
85
+ scroll(deltaY: any): Promise<void>;
86
+ hover(ref: any): Promise<void>;
87
+ injectCookies(url: string, cookieOpts?: import("./index.js").CookieOptions): Promise<number>;
88
+ select(ref: any, value: any): Promise<void>;
89
+ drag(fromRef: any, toRef: any): Promise<void>;
90
+ upload(ref: any, files: any): Promise<void>;
91
+ goBack(): Promise<void>;
92
+ goForward(): Promise<void>;
93
+ reload(): Promise<void>;
94
+ screenshot(screenshotOpts?: {}): Promise<any>;
95
+ pdf(pdfOpts?: {}): Promise<any>;
96
+ tabs(): Promise<{
97
+ index: number;
98
+ url: any;
99
+ title: any;
100
+ context: any;
101
+ }[]>;
102
+ switchTab(index: any): Promise<void>;
103
+ waitFor(waitOpts?: {}): Promise<void>;
104
+ waitForNetworkIdle(idleOpts?: {}): Promise<void>;
105
+ readonly downloads: any[];
106
+ dialogLog: any[];
107
+ onDialog(handler: any): void;
108
+ saveState(filePath: any): Promise<void>;
109
+ waitForNavigation(timeout?: number): Promise<void>;
110
+ close(): Promise<void>;
111
+ } | {
112
+ goto(url: any, timeout?: number): Promise<void>;
113
+ goBack(): Promise<void>;
114
+ goForward(): Promise<void>;
115
+ reload(reloadOpts?: {}): Promise<void>;
116
+ /** @param {string} url @param {CookieOptions} [cookieOpts] */
117
+ injectCookies(url: string, cookieOpts?: CookieOptions): Promise<number>;
118
+ /** @param {SnapshotOptions|false} [pruneOpts] */
119
+ snapshot(pruneOpts?: SnapshotOptions | false): Promise<string>;
120
+ readable(): Promise<any>;
121
+ click(ref: any): Promise<void>;
122
+ /** @param {string} ref @param {string} text @param {TypeOptions} [typeOpts] */
123
+ type(ref: string, text: string, typeOpts?: TypeOptions): Promise<void>;
124
+ scroll(deltaY: any): Promise<void>;
125
+ press(key: any): Promise<void>;
126
+ hover(ref: any): Promise<void>;
127
+ select(ref: any, value: any): Promise<void>;
128
+ drag(fromRef: any, toRef: any): Promise<void>;
129
+ upload(ref: any, files: any): Promise<void>;
130
+ pdf(pdfOpts?: {}): Promise<any>;
131
+ tabs(): Promise<any>;
132
+ switchTab(index: any): Promise<void>;
133
+ waitFor(waitOpts?: {}): Promise<void>;
134
+ saveState(filePath: any): Promise<void>;
135
+ readonly botBlocked: boolean;
136
+ /** @type {'chromium'} Engine driving this session (see also `capabilities`) */
137
+ engine: "chromium";
138
+ /**
139
+ * Introspection of this session's engine, mode, and feature support — see
140
+ * the `Capabilities` typedef. Fields are launch-fixed except `stealth`,
141
+ * which is a live getter tracking the current headed/headless state (flips
142
+ * after a hybrid headed relaunch). Lets a caller ask "which engine am I on
143
+ * and what can it do?" without probing for `cdp`/`bidi`.
144
+ * @type {Capabilities}
145
+ */
146
+ capabilities: Capabilities;
147
+ dialogLog: any[];
148
+ /**
149
+ * Install a custom JS dialog handler. The handler is called with
150
+ * `{ type, message, defaultPrompt }` and may return (sync or async)
151
+ * `{ accept: bool, promptText: string }` to override the auto-accept
152
+ * default. Pass null to restore the default behavior.
153
+ */
154
+ onDialog(handler: any): void;
155
+ downloads: any[];
156
+ screenshot(screenshotOpts?: {}): Promise<any>;
157
+ waitForNavigation(timeout?: number): Promise<void>;
158
+ waitForNetworkIdle(idleOpts?: {}): Promise<void>;
159
+ /** Raw CDP session for escape hatch — getter so it survives hybrid fallback / tab swaps */
160
+ readonly cdp: any;
161
+ createTab(): Promise<{
162
+ goto(url: any, timeout?: number): Promise<void>;
163
+ readonly botBlocked: boolean;
164
+ /** @param {string} url @param {CookieOptions} [cookieOpts] */
165
+ injectCookies(url: string, cookieOpts?: CookieOptions): Promise<number>;
166
+ waitForNetworkIdle(idleOpts?: {}): Promise<void>;
167
+ cdp: any;
168
+ close(): Promise<void>;
169
+ }>;
170
+ close(): Promise<void>;
171
+ }>;
120
172
  /**
121
173
  * Apply Network.setBlockedURLs for ad/tracker blocking on a session.
122
174
  * Default list is on; pass blockAds:false to skip, blockUrls:[] to extend.
@@ -130,4 +182,85 @@ export function applyBlocklist(session: any, pageOpts: any): Promise<void>;
130
182
  /** Test-only: reset the warn-once flag. Not part of the public API. */
131
183
  export function _resetBlocklistWarning(): void;
132
184
  export { isChallengePage };
185
+ /**
186
+ * The interactive page handle returned by {@link connect}. Inferred structurally
187
+ * from the returned object literals — no hand-maintained interface to drift.
188
+ *
189
+ * It is a union of the two engine page shapes (Chromium/CDP and Firefox/BiDi),
190
+ * which share every interaction method (`goto`, `snapshot`, `click`, `type`,
191
+ * `close`, …) but differ in their escape hatches — `cdp`/`createTab`/`dialogLog`
192
+ * on Chromium, `bidi`/`context` on Firefox. The shared methods dereference
193
+ * without narrowing; an engine-specific hatch requires knowing the engine
194
+ * (the default is Chromium), e.g. `if ('cdp' in page) page.cdp.send(...)`.
195
+ * Both shapes carry `page.engine` (`'chromium'`|`'firefox'`) and a
196
+ * `page.capabilities` object so a caller can introspect which engine drives
197
+ * the session and what it supports without probing for an escape hatch.
198
+ */
199
+ export type Page = Awaited<ReturnType<typeof connect>>;
200
+ /**
201
+ * Description of what the current session can do — engine, mode, and the
202
+ * mode/engine-derived feature flags that actually differ between sessions. Read
203
+ * it via `page.capabilities` instead of inferring from the engine name. All
204
+ * fields are launch-fixed engine/mode facts except `stealth`, which reflects
205
+ * the CURRENT headed/headless state and can flip mid-session after a hybrid
206
+ * bot-challenge fallback relaunches a headed browser. `attach` is Chromium
207
+ * `connect({port})` (no stealth/downloads); `reloadIgnoreCache` is false on
208
+ * Firefox (upstream BiDi gap). Each remaining flag has its own driver:
209
+ * `downloads` is off when attached, `stealth` off when attached or headed,
210
+ * `cookieInjection` off in incognito.
211
+ */
212
+ export type Capabilities = {
213
+ /**
214
+ * - Engine driving this session
215
+ */
216
+ engine: "chromium" | "firefox";
217
+ /**
218
+ * - Launch mode
219
+ */
220
+ mode: "headless" | "headed" | "hybrid";
221
+ /**
222
+ * - Attached to a user-launched browser (Chromium only)
223
+ */
224
+ attach: boolean;
225
+ /**
226
+ * - Name of the raw-protocol escape-hatch property
227
+ */
228
+ escapeHatch: "cdp" | "bidi";
229
+ /**
230
+ * - `reload({ignoreCache})` is honored
231
+ */
232
+ reloadIgnoreCache: boolean;
233
+ /**
234
+ * - `page.downloads` is populated
235
+ */
236
+ downloads: boolean;
237
+ /**
238
+ * - Headless anti-detection is currently active (live — reflects present headed/headless state, not just launch mode)
239
+ */
240
+ stealth: boolean;
241
+ /**
242
+ * - Cookie extraction/injection is active (off in incognito)
243
+ */
244
+ cookieInjection: boolean;
245
+ };
246
+ /**
247
+ * Options for `page.snapshot()`. Pass `false` instead of an object to skip
248
+ * pruning and return the raw ARIA tree.
249
+ */
250
+ export type SnapshotOptions = {
251
+ mode?: "act" | "browse" | "navigate" | "full" | "read";
252
+ };
253
+ /**
254
+ * Options for `page.type()`.
255
+ */
256
+ export type TypeOptions = {
257
+ clear?: boolean;
258
+ keyEvents?: boolean;
259
+ };
260
+ /**
261
+ * Options for `page.injectCookies()`.
262
+ */
263
+ export type CookieOptions = {
264
+ browser?: string;
265
+ };
133
266
  import { isChallengePage } from './challenge.js';