barebrowse 0.5.9 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## 0.7.0
+
+MCP resilience: timeouts, auto-retry, LLM-friendly scroll, and click fallback for hidden elements.
+
+### Timeouts (`mcp-server.js`)
+- All MCP tool calls now have a hard timeout: 30s for session tools, 60s for `browse` and `assess`
+- Returns a structured error (`Tool "X" timed out after Ns`) instead of hanging silently
+- Previously: a hung browser or slow page caused `[Tool result missing due to internal error]` — opaque and unrecoverable
+
+### Auto-retry (`mcp-server.js`)
+- `withRetry()` wrapper on all session tools (goto, snapshot, click, type, press, scroll, back, forward, drag, upload, pdf)
+- On transient CDP failure (WebSocket closed, target/session closed), resets the session and retries once automatically
+- Non-CDP errors (validation, unknown tool) are not retried
+
+### LLM-friendly scroll (`mcp-server.js`, `src/bareagent.js`)
+- Scroll tool now accepts `direction: "up"/"down"` in addition to numeric `deltaY`
+- LLMs naturally say `scroll(direction: "down")` — this now works instead of crashing with `deltaX/deltaY expected for mouseWheel event`
+- `"down"` → `deltaY: 900`, `"up"` → `deltaY: -900`. Numeric `deltaY` still works and takes precedence.
+- Clear validation error if neither `direction` nor `deltaY` is provided
+
+### Click JS fallback (`src/interact.js`)
+- Click now falls back to JS `element.click()` when `DOM.scrollIntoViewIfNeeded` fails with "Node does not have a layout object"
+- This error occurs on elements that exist in the ARIA tree but have no visual layout (display:none, zero-size, collapsed sections, detached nodes)
+- Resolves the node via `DOM.requestNode` → `DOM.resolveNode` → `Runtime.callFunctionOn`
+- Other click errors still throw normally
+
+### Docs
+- Updated barebrowse.context.md, README.md, prd.md with resilience features
+- MCP server version string updated to 0.7.0
+
+### Tests
+- 71/71 passing — no test changes needed
+
+## 0.6.1
+
+Headed fallback is now a per-navigation escape hatch, not a permanent mode switch. Graceful degradation when headed is unavailable.
+
+### Switch-back to headless (`src/index.js`)
+- `connect().goto()` in hybrid mode: if currently headed from a previous fallback, kills the headed browser and launches fresh headless before navigating
+- New `currentlyHeaded` runtime state variable tracks actual browser mode (vs `mode` which is user config)
+- `createPage()` stealth decision uses runtime mode (`!currentlyHeaded`) instead of config mode (`mode !== 'headed'`)
+- `createTab()` also uses `currentlyHeaded` for correct stealth application
+
+### Graceful degradation (`src/index.js`)
+- `connect().goto()` hybrid fallback wrapped in try/catch — if `launch({ headed: true })` fails (no `$DISPLAY`, no Wayland, CI/Docker), keeps the headless result with `botBlocked: true` and `[BOT CHALLENGE DETECTED]` warning
+- `browse()` hybrid fallback also wrapped in try/catch — same graceful degradation for one-shot browsing
+- No crash on headless-only environments
+
+### Flow after changes
+```
+goto(url) in hybrid mode:
+  1. If currently headed → kill headed, launch headless, reset currentlyHeaded
+  2. Navigate to url
+  3. Check bot-blocked
+  4. If bot-blocked → TRY launch headed (set currentlyHeaded=true)
+                    → CATCH: headed unavailable, keep headless result
+```
+
+### Docs
+- Updated hybrid mode descriptions in barebrowse.context.md, system-state.md, prd.md
+
+### Tests
+- All existing tests pass (tests use headless mode, unaffected by hybrid logic)
+
+## 0.6.0
+
+Self-launching headed fallback. Headed and hybrid modes no longer require a manually-launched browser on port 9222 — barebrowse auto-launches a visible Chromium window via `launch({ headed: true })`.
+
+### Headed mode auto-launch (`src/chromium.js`)
+- `launch()` accepts `headed` option — skips `--headless=new` and `--hide-scrollbars` flags
+- Same temp profile, same random port, same CDP parsing, same process return
+
+### Hybrid fallback fix (`src/index.js`)
+- All 4 `getDebugUrl(port)` call sites replaced with `launch({ headed: true, proxy })` + `createCDP(browser.wsUrl)`
+- `browse()` headed branch, `browse()` hybrid fallback, `connect()` headed branch, `connect().goto()` hybrid fallback
+- `getDebugUrl` import removed from index.js (still exported from chromium.js for external use)
+- Hybrid mode now actually works — previously it tried to connect to port 9222 which nobody ran
+
+### Assess handler simplified (`mcp-server.js`)
+- Removed dual-path `runAssess(headed)` function (~60 lines of broken headed fallback)
+- Assess now uses the session's hybrid mode: if tab is bot-blocked, triggers headed fallback via main page `goto()`, then retries in a new tab
+- One flow, no separate `connect({ mode: 'headed' })` call
+
+### Docs
+- Removed all "launch browser with --remote-debugging-port=9222" instructions
+- Updated headed/hybrid mode descriptions across barebrowse.context.md, README.md, system-state.md, prd.md
+
+### Tests
+- 71/71 passing — no test changes needed (all tests use headless mode)
+
 ## 0.5.8
 
 Bot challenge detection for all browsing, not just assess.

package/README.md

@@ -87,7 +87,7 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
 }
 ```
 
-12 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `forward`, `drag`, `upload`, `pdf`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Session runs in hybrid mode with automatic cookie injection.
+12 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `forward`, `drag`, `upload`, `pdf`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Session runs in hybrid mode with automatic cookie injection. All tools have timeouts (30s/60s) and auto-retry on transient failures.
 
 ### 3. Library -- for agentic automation
 
@@ -100,8 +100,8 @@ For code examples, API reference, and wiring instructions, see **[barebrowse.con
 | Mode | What happens | Best for |
 |------|-------------|----------|
 | **Headless** (default) | Launches a fresh Chromium, no UI | Fast automation, scraping, reading pages |
-| **Headed** | Connects to your running browser on CDP port | Bot-detected sites, visual debugging, CAPTCHAs |
-| **Hybrid** | Tries headless first, falls back to headed if blocked | General-purpose agent browsing |
+| **Headed** | Auto-launches a visible Chromium window | Bot-detected sites, visual debugging, CAPTCHAs |
+| **Hybrid** | Tries headless first, auto-launches headed if blocked | General-purpose agent browsing |
 
 ## What it handles automatically
 
@@ -129,10 +129,10 @@ Everything the agent can do through barebrowse:
 | **Navigate** | Load a URL, wait for page load, auto-dismiss consent |
 | **Back / Forward** | Browser history navigation |
 | **Snapshot** | Pruned ARIA tree with `[ref=N]` markers. Two modes: `act` (buttons, links, inputs) and `read` (full text). 40-90% token reduction. |
-| **Click** | Scroll into view + mouse click at element center |
+| **Click** | Scroll into view + mouse click at element center, JS fallback for hidden elements |
 | **Type** | Focus + insert text, with option to clear existing content first |
 | **Press** | Special keys: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
-| **Scroll** | Mouse wheel up or down |
+| **Scroll** | Mouse wheel up or down (accepts direction or pixels) |
 | **Hover** | Move mouse to element center (triggers tooltips, hover states) |
 | **Select** | Set dropdown value (native select or custom dropdown) |
 | **Drag** | Drag one element to another (Kanban boards, sliders) |

package/barebrowse.context.md

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.5.8 | Node.js >= 22 | 0 required deps | MIT
+> v0.7.0 | Node.js >= 22 | 0 required deps | MIT
 
 ## What this is
 
@@ -23,10 +23,8 @@ Three integration paths:
 | Mode | What it does | When to use |
 |---|---|---|
 | `headless` (default) | Launches a fresh Chromium, no UI | Scraping, reading, fast automation |
-| `headed` | Connects to user's running browser on CDP port | Bot-detected sites, debugging, visual tasks |
-| `hybrid` | Tries headless first, falls back to headed if blocked | General-purpose agent browsing |
-
-Headed mode requires the browser to be launched with `--remote-debugging-port=9222`.
+| `headed` | Auto-launches a visible Chromium window | Bot-detected sites, debugging, visual tasks |
+| `hybrid` | Tries headless first, headed fallback per-navigation (switches back to headless next time) | General-purpose agent browsing |
 
 ## Minimal usage: one-shot browse
 
@@ -45,13 +43,12 @@ const snapshot = await browse('https://example.com', {
   pruneMode: 'act',      // 'act' (interactive elements) | 'read' (all content)
   consent: true,         // auto-dismiss cookie consent dialogs
   timeout: 30000,        // navigation timeout in ms
-  port: 9222,            // CDP port for headed/hybrid mode
 });
 ```
 
 ## connect() API
 
-`connect(opts)` returns a page handle for interactive sessions. Same opts as `browse()` for mode/port. Supports `hybrid` mode — starts headless, falls back to headed on bot detection (same as `browse()`).
+`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()`).
 
 | Method | Args | Returns | Notes |
 |---|---|---|---|
@@ -62,7 +59,7 @@ const snapshot = await browse('https://example.com', {
 | `click(ref)` | ref: string | void | Scroll into view + mouse press+release at center |
 | `type(ref, text, opts?)` | ref: string, text: string, opts: { clear?, keyEvents? } | void | Focus + insert text. `clear: true` replaces existing. |
 | `press(key)` | key: string | void | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Home, End, PageUp, PageDown, Space |
-| `scroll(deltaY)` | deltaY: number | void | Mouse wheel. Positive = down, negative = up. |
+| `scroll(deltaY)` | deltaY: number | void | Mouse wheel. Positive = down, negative = up. MCP/bareagent also accept `direction: "up"/"down"`. |
 | `hover(ref)` | ref: string | void | Move mouse to element center |
 | `select(ref, value)` | ref: string, value: string | void | Set `<select>` value or click custom dropdown option |
 | `drag(fromRef, toRef)` | fromRef: string, toRef: string | void | Drag from one element to another |
@@ -152,7 +149,7 @@ barebrowse can inject cookies from the user's real browser sessions, bypassing l
 | Media autoplay blocked | `--autoplay-policy=no-user-gesture-required` | Both |
 | Login walls | Cookie extraction from Firefox/Chromium + CDP injection | Both |
 | Pre-filled form inputs | `type({ clear: true })` selects all + deletes first | Both |
-| Off-screen elements | `DOM.scrollIntoViewIfNeeded` before every click | Both |
+| Off-screen elements | `DOM.scrollIntoViewIfNeeded` before every click, JS `.click()` fallback for no-layout elements | Both |
 | Form submission | `press('Enter')` triggers onsubmit | Both |
 | SPA navigation | `waitForNavigation()` uses loadEventFired + frameNavigated | Both |
 | Bot detection | ARIA node count (<50 = bot-blocked) + text heuristics. `botBlocked` flag set after every `goto()`. Hybrid fallback switches to headed. Snapshot shows `[BOT CHALLENGE DETECTED]` warning. | Hybrid |
@@ -244,7 +241,7 @@ Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe.
 
 Session runs in hybrid mode (headless with automatic headed fallback on bot detection). `goto` injects cookies from the user's browser before navigation for authenticated access.
 
-Session tools share a singleton page, lazy-created on first use. Assess tries headless first; if bot-blocked (score ≤5 with all zeros), retries with a separate headed session. Tabs dismissed for consent and closed after every scan. Max 3 concurrent. Browser OOM/crash auto-recovers (session resets, server stays alive).
+Session tools share a singleton page, lazy-created on first use. All session tools have auto-retry on transient CDP failures (browser crash, WebSocket close) — session resets and retries once automatically. 30s timeout on all tools (60s for `browse`/`assess`). Scroll accepts `direction: "up"/"down"` in addition to numeric `deltaY`. Click falls back to JS `.click()` when elements have no layout. Assess tries headless first; if bot-blocked, retries headed. Browser OOM/crash auto-recovers (session resets, server stays alive).
 
 ## Architecture
 
@@ -312,13 +309,13 @@ Useful for agent threshold decisions: "skip sites above score 40", "warn if term
 
 3. **Pruning modes matter.** `act` mode (default) keeps interactive elements + visible labels. `read` mode keeps all text content. Use `read` for content extraction, `act` for form filling and navigation.
 
-4. **Headed mode requires manual browser launch.** Start your browser with `--remote-debugging-port=9222`. barebrowse connects to it -- it does not launch it.
+4. **Headed mode auto-launches Chromium.** No need to start a browser manually — barebrowse launches a headed Chromium instance with CDP enabled automatically.
 
 5. **Cookie extraction needs unlocked profile.** Chromium cookies are AES-encrypted with a keyring key. If Chromium is running, the profile may be locked. Firefox cookies are plaintext and always accessible.
 
-6. **Hybrid mode kills and relaunches.** If headless is bot-blocked, hybrid mode kills the headless browser and connects to headed on port 9222. The headed browser must already be running.
+6. **Hybrid mode is per-navigation.** If headless is bot-blocked, hybrid kills headless and launches headed for that URL. On the next `goto()`, it switches back to headless automatically. If headed can't launch (no display — CI, Docker), it degrades gracefully with the headless result and a `[BOT CHALLENGE DETECTED]` warning.
 
-7. **One page per connect().** Each `connect()` call creates one page. For multiple tabs, call `connect()` multiple times.
+7. **One page per connect(), but tabs are supported.** Each `connect()` call creates one page. Use `createTab()` for additional tabs in the same browser.
 
 8. **Consent dismiss is best-effort.** It handles 16+ tested sites across 29 languages but novel consent implementations may need manual handling. Disable with `{ consent: false }`.
 

package/mcp-server.js

@@ -25,6 +25,18 @@ function isCdpDead(err) {
   return m.includes('WebSocket') || m.includes('Target closed') || m.includes('Session closed') || m.includes('CDP');
 }
 
+/** Retry-once wrapper for transient CDP failures. Resets session and retries. */
+async function withRetry(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!isCdpDead(err)) throw err;
+    // CDP died — reset session and retry once
+    _page = null;
+    return await fn();
+  }
+}
+
 const MAX_CHARS_DEFAULT = 30000;
 const OUTPUT_DIR = join(process.cwd(), '.barebrowse');
 
@@ -139,13 +151,13 @@ const TOOLS = [
   },
   {
     name: 'scroll',
-    description: 'Scroll the page. Positive deltaY scrolls down, negative scrolls up. Returns ok.',
+    description: 'Scroll the page up or down. Pass direction ("up"/"down") or a numeric deltaY. Returns ok.',
     inputSchema: {
       type: 'object',
       properties: {
-        deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up)' },
+        direction: { type: 'string', enum: ['up', 'down'], description: 'Scroll direction — "up" or "down" (scrolls ~3 screen-heights)' },
+        deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up). Overrides direction if both given.' },
       },
-      required: ['deltaY'],
     },
   },
   {
@@ -222,13 +234,13 @@ async function handleToolCall(name, args) {
       }
       return text;
     }
-    case 'goto': {
+    case 'goto': return withRetry(async () => {
       const page = await getPage();
       try { await page.injectCookies(args.url); } catch {}
       await page.goto(args.url);
       return 'ok';
-    }
-    case 'snapshot': {
+    });
+    case 'snapshot': return withRetry(async () => {
       const page = await getPage();
       const text = await page.snapshot();
       const limit = args.maxChars ?? MAX_CHARS_DEFAULT;
@@ -237,110 +249,101 @@ async function handleToolCall(name, args) {
         return `Snapshot (${text.length} chars) saved to ${file}`;
       }
       return text;
-    }
-    case 'click': {
+    });
+    case 'click': return withRetry(async () => {
       const page = await getPage();
       await page.click(args.ref);
       return 'ok';
-    }
-    case 'type': {
+    });
+    case 'type': return withRetry(async () => {
       const page = await getPage();
       await page.type(args.ref, args.text, { clear: args.clear });
       return 'ok';
-    }
-    case 'press': {
+    });
+    case 'press': return withRetry(async () => {
       const page = await getPage();
       await page.press(args.key);
       return 'ok';
-    }
-    case 'scroll': {
+    });
+    case 'scroll': return withRetry(async () => {
       const page = await getPage();
-      await page.scroll(args.deltaY);
+      let dy = args.deltaY;
+      if (dy == null && args.direction) {
+        dy = args.direction === 'up' ? -900 : 900;
+      }
+      if (dy == null || typeof dy !== 'number') {
+        throw new Error('scroll requires "direction" ("up"/"down") or numeric "deltaY"');
+      }
+      await page.scroll(dy);
       return 'ok';
-    }
-    case 'back': {
+    });
+    case 'back': return withRetry(async () => {
       const page = await getPage();
       await page.goBack();
       return 'ok';
-    }
-    case 'forward': {
+    });
+    case 'forward': return withRetry(async () => {
       const page = await getPage();
       await page.goForward();
       return 'ok';
-    }
-    case 'drag': {
+    });
+    case 'drag': return withRetry(async () => {
       const page = await getPage();
       await page.drag(args.fromRef, args.toRef);
       return 'ok';
-    }
-    case 'upload': {
+    });
+    case 'upload': return withRetry(async () => {
       const page = await getPage();
       await page.upload(args.ref, args.files);
       return 'ok';
-    }
-    case 'pdf': {
+    });
+    case 'pdf': return withRetry(async () => {
       const page = await getPage();
       return await page.pdf({ landscape: args.landscape });
-    }
+    });
     case 'assess': {
       if (!assessFn) throw new Error('wearehere is not installed. Run: npm install wearehere');
       const releaseSlot = await acquireAssessSlot();
       try {
-        const runAssess = async (headed) => {
-          let tab;
-          if (headed) {
-            tab = await connect({ mode: 'headed' });
-          } else {
-            const page = await getPage();
-            tab = await page.createTab();
-          }
-          let timer;
-          try {
-            const result = await Promise.race([
-              (async () => {
-                await tab.injectCookies(args.url).catch(() => {});
-                return await assessFn(tab, args.url, { timeout: args.timeout, settle: args.settle });
-              })(),
-              new Promise((_, reject) => {
-                timer = setTimeout(() => {
-                  tab.close().catch(() => {});
-                  reject(new Error('assess timeout'));
-                }, 30000);
-              }),
-            ]);
-            clearTimeout(timer);
-            const wasBotBlocked = tab.botBlocked;
-            await tab.close().catch(() => {});
-            return { result, botBlocked: wasBotBlocked };
-          } catch (err) {
-            clearTimeout(timer);
-            await tab.close().catch(() => {});
-            throw err;
-          }
-        };
-
-        // Try headless first
+        const page = await getPage();
+        const tab = await page.createTab();
+        let timer;
         try {
-          const { result, botBlocked } = await runAssess(false);
-          if (botBlocked) {
-            // Bot-blocked in headless — retry headed
+          await tab.injectCookies(args.url).catch(() => {});
+          const result = await Promise.race([
+            assessFn(tab, args.url, { timeout: args.timeout, settle: args.settle }),
+            new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('assess timeout')), 30000); }),
+          ]);
+          clearTimeout(timer);
+          if (tab.botBlocked) {
+            // Bot-blocked — trigger hybrid fallback via main page, retry in new tab
+            await tab.close().catch(() => {});
+            await page.goto(args.url);
+            const tab2 = await page.createTab();
+            let timer2;
             try {
-              const headed = await runAssess(true);
-              return JSON.stringify(headed.result, null, 2);
-            } catch {
-              return JSON.stringify(result, null, 2); // headed failed, return headless result
+              await tab2.injectCookies(args.url).catch(() => {});
+              const r2 = await Promise.race([
+                assessFn(tab2, args.url, { timeout: args.timeout, settle: args.settle }),
+                new Promise((_, rej) => { timer2 = setTimeout(() => rej(new Error('assess timeout')), 30000); }),
+              ]);
+              clearTimeout(timer2);
+              if (tab2.botBlocked) r2._warning = 'Bot-blocked in both modes. Score may be unreliable.';
+              await tab2.close().catch(() => {});
+              return JSON.stringify(r2, null, 2);
+            } catch (err2) {
+              clearTimeout(timer2);
+              await tab2.close().catch(() => {});
+              throw err2;
             }
           }
+          await tab.close().catch(() => {});
           return JSON.stringify(result, null, 2);
         } catch (err) {
+          clearTimeout(timer);
+          await tab.close().catch(() => {});
           if (isCdpDead(err)) _page = null;
-          // Headless crashed — try headed
-          try {
-            const headed = await runAssess(true);
-            return JSON.stringify(headed.result, null, 2);
-          } catch (retryErr) {
-            throw retryErr;
-          }
+          throw err;
         }
       } finally {
         releaseSlot();
@@ -366,7 +369,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.5.9' },
+      serverInfo: { name: 'barebrowse', version: '0.7.0' },
     });
   }
 
@@ -380,12 +383,19 @@ async function handleMessage(msg) {
 
   if (method === 'tools/call') {
     const { name, arguments: args } = params;
+    const TOOL_TIMEOUT = name === 'browse' || name === 'assess' ? 60000 : 30000;
     try {
-      const result = await handleToolCall(name, args || {});
+      let timer;
+      const result = await Promise.race([
+        handleToolCall(name, args || {}),
+        new Promise((_, rej) => { timer = setTimeout(() => rej(new Error(`Tool "${name}" timed out after ${TOOL_TIMEOUT / 1000}s`)), TOOL_TIMEOUT); }),
+      ]);
+      clearTimeout(timer);
       return jsonrpcResponse(id, {
         content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
       });
     } catch (err) {
+      if (isCdpDead(err)) _page = null;
       return jsonrpcResponse(id, {
         content: [{ type: 'text', text: `Error: ${err.message}` }],
         isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.5.9",
+  "version": "0.7.0",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",

package/src/bareagent.js

@@ -116,15 +116,20 @@ export function createBrowseTools(opts = {}) {
     },
     {
       name: 'scroll',
-      description: 'Scroll the page. Returns the updated snapshot.',
+      description: 'Scroll the page up or down. Pass direction ("up"/"down") or a numeric deltaY. Returns the updated snapshot.',
       parameters: {
         type: 'object',
         properties: {
-          deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up)' },
+          direction: { type: 'string', enum: ['up', 'down'], description: 'Scroll direction — "up" or "down" (scrolls ~3 screen-heights)' },
+          deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up). Overrides direction if both given.' },
         },
-        required: ['deltaY'],
       },
-      execute: async ({ deltaY }) => actionAndSnapshot((page) => page.scroll(deltaY)),
+      execute: async ({ direction, deltaY }) => {
+        let dy = deltaY;
+        if (dy == null && direction) dy = direction === 'up' ? -900 : 900;
+        if (dy == null || typeof dy !== 'number') throw new Error('scroll requires "direction" or numeric "deltaY"');
+        return actionAndSnapshot((page) => page.scroll(dy));
+      },
     },
     {
       name: 'select',

package/src/chromium.js

@@ -2,7 +2,7 @@
  * chromium.js — Find, launch, and connect to Chromium-based browsers.
  *
  * Supports: Chrome, Chromium, Brave, Edge, Vivaldi, Arc, Opera.
- * Modes: headless (launch new), headed (connect to running).
+ * Modes: headless (launch new, no UI), headed (launch new, visible window).
  */
 
 import { execSync, spawn } from 'node:child_process';
@@ -55,11 +55,12 @@ export function findBrowser() {
 }
 
 /**
- * Launch a headless Chromium instance with CDP enabled.
+ * 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)
  * @returns {Promise<{wsUrl: string, process: ChildProcess, port: number}>}
  */
 export async function launch(opts = {}) {
@@ -67,7 +68,6 @@ export async function launch(opts = {}) {
   const port = opts.port || 0;
 
   const args = [
-    '--headless=new',
     `--remote-debugging-port=${port}`,
     '--no-first-run',
     '--no-default-browser-check',
@@ -75,7 +75,8 @@ export async function launch(opts = {}) {
     '--disable-sync',
     '--disable-translate',
     '--mute-audio',
-    '--hide-scrollbars',
+    // Headless-only flags
+    ...(!opts.headed ? ['--headless=new', '--hide-scrollbars'] : []),
     // Suppress permission prompts (location, notifications, camera, mic, etc.)
     '--disable-notifications',
     '--autoplay-policy=no-user-gesture-required',

package/src/index.js

@@ -8,7 +8,7 @@
  *   const snapshot = await browse('https://example.com');
  */
 
-import { launch, getDebugUrl } from './chromium.js';
+import { launch } from './chromium.js';
 import { createCDP } from './cdp.js';
 import { formatTree } from './aria.js';
 import { authenticate } from './auth.js';
@@ -27,7 +27,6 @@ import { applyStealth } from './stealth.js';
  * @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 {number} [opts.port] - CDP port for headed mode
  * @returns {Promise<string>} ARIA snapshot text
  */
 export async function browse(url, opts = {}) {
@@ -40,9 +39,8 @@ export async function browse(url, opts = {}) {
   try {
     // Step 1: Get a CDP connection
     if (mode === 'headed') {
-      const port = opts.port || 9222;
-      const wsUrl = await getDebugUrl(port);
-      cdp = await createCDP(wsUrl);
+      browser = await launch({ headed: true, proxy: opts.proxy });
+      cdp = await createCDP(browser.wsUrl);
     } else {
       // headless or hybrid (start headless)
       browser = await launch({ proxy: opts.proxy });
@@ -81,17 +79,20 @@ export async function browse(url, opts = {}) {
       cdp.close();
       if (browser) { browser.process.kill(); browser = null; }
 
-      const port = opts.port || 9222;
-      const wsUrl = await getDebugUrl(port);
-      cdp = await createCDP(wsUrl);
-      page = await createPage(cdp, false, { viewport: opts.viewport });
-      await suppressPermissions(cdp);
-      if (opts.cookies !== false) {
-        try { await authenticate(page.session, url, { browser: opts.browser }); } catch {}
+      try {
+        browser = await launch({ headed: true, proxy: opts.proxy });
+        cdp = await createCDP(browser.wsUrl);
+        page = await createPage(cdp, false, { viewport: opts.viewport });
+        await suppressPermissions(cdp);
+        if (opts.cookies !== false) {
+          try { await authenticate(page.session, url, { browser: opts.browser }); } catch {}
+        }
+        await navigate(page, url, timeout);
+        if (opts.consent !== false) await dismissConsent(page.session);
+        ({ tree } = await ariaTree(page));
+      } catch {
+        // Headed launch failed (no display?) — return headless result as-is
       }
-      await navigate(page, url, timeout);
-      if (opts.consent !== false) await dismissConsent(page.session);
-      ({ tree } = await ariaTree(page));
     }
 
     // Step 6: Prune for agent consumption
@@ -121,7 +122,6 @@ export async function browse(url, opts = {}) {
  *
  * @param {object} [opts]
  * @param {'headless'|'headed'|'hybrid'} [opts.mode='headless'] - Browser mode
- * @param {number} [opts.port=9222] - CDP port for headed mode
  * @returns {Promise<object>} Page handle with goto, snapshot, close
  */
 export async function connect(opts = {}) {
@@ -130,15 +130,15 @@ export async function connect(opts = {}) {
   let cdp;
 
   if (mode === 'headed') {
-    const port = opts.port || 9222;
-    const wsUrl = await getDebugUrl(port);
-    cdp = await createCDP(wsUrl);
+    browser = await launch({ headed: true, proxy: opts.proxy });
+    cdp = await createCDP(browser.wsUrl);
   } else {
     browser = await launch({ proxy: opts.proxy });
     cdp = await createCDP(browser.wsUrl);
   }
 
-  let page = await createPage(cdp, mode !== 'headed', { viewport: opts.viewport });
+  let currentlyHeaded = (mode === 'headed');
+  let page = await createPage(cdp, !currentlyHeaded, { viewport: opts.viewport });
   let refMap = new Map();
   let botBlocked = false;
 
@@ -175,6 +175,20 @@ export async function connect(opts = {}) {
 
   return {
     async goto(url, timeout = 30000) {
+      // Switch back to headless if we fell back to headed previously
+      if (currentlyHeaded && mode === 'hybrid') {
+        await cdp.send('Target.closeTarget', { targetId: page.targetId });
+        cdp.close();
+        if (browser) { browser.process.kill(); browser = null; }
+
+        browser = await launch({ proxy: opts.proxy });
+        cdp = await createCDP(browser.wsUrl);
+        page = await createPage(cdp, true, { viewport: opts.viewport });
+        setupDialogHandler(page.session);
+        await suppressPermissions(cdp);
+        currentlyHeaded = false;
+      }
+
       await navigate(page, url, timeout);
       if (opts.consent !== false) {
         await dismissConsent(page.session);
@@ -190,18 +204,22 @@ export async function connect(opts = {}) {
         cdp.close();
         if (browser) { browser.process.kill(); browser = null; }
 
-        const port = opts.port || 9222;
-        const wsUrl = await getDebugUrl(port);
-        cdp = await createCDP(wsUrl);
-        page = await createPage(cdp, false, { viewport: opts.viewport });
-        setupDialogHandler(page.session);
-        await suppressPermissions(cdp);
-        await navigate(page, url, timeout);
-        if (opts.consent !== false) await dismissConsent(page.session);
-
-        // Re-check after headed fallback
-        const after = await ariaTree(page);
-        botBlocked = isChallengePage(after.tree, after.nodeCount);
+        try {
+          browser = await launch({ headed: true, proxy: opts.proxy });
+          cdp = await createCDP(browser.wsUrl);
+          page = await createPage(cdp, false, { viewport: opts.viewport });
+          setupDialogHandler(page.session);
+          await suppressPermissions(cdp);
+          await navigate(page, url, timeout);
+          if (opts.consent !== false) await dismissConsent(page.session);
+
+          // Re-check after headed fallback
+          const after = await ariaTree(page);
+          botBlocked = isChallengePage(after.tree, after.nodeCount);
+          currentlyHeaded = true;
+        } catch {
+          // Headed launch failed (no display?) — keep headless result, botBlocked stays true
+        }
       }
     },
 
@@ -375,7 +393,7 @@ export async function connect(opts = {}) {
     cdp: page.session,
 
     async createTab() {
-      const tab = await createPage(cdp, mode !== 'headed', { viewport: opts.viewport });
+      const tab = await createPage(cdp, !currentlyHeaded, { viewport: opts.viewport });
       await suppressPermissions(cdp);
       let tabBotBlocked = false;
       return {

package/src/interact.js

@@ -46,13 +46,27 @@ async function getCenter(session, backendNodeId) {
  * @param {number} backendNodeId - Backend DOM node ID
  */
 export async function click(session, backendNodeId) {
-  const { x, y } = await getCenter(session, backendNodeId);
-  await session.send('Input.dispatchMouseEvent', {
-    type: 'mousePressed', x, y, button: 'left', clickCount: 1,
-  });
-  await session.send('Input.dispatchMouseEvent', {
-    type: 'mouseReleased', x, y, button: 'left', clickCount: 1,
-  });
+  try {
+    const { x, y } = await getCenter(session, backendNodeId);
+    await session.send('Input.dispatchMouseEvent', {
+      type: 'mousePressed', x, y, button: 'left', clickCount: 1,
+    });
+    await session.send('Input.dispatchMouseEvent', {
+      type: 'mouseReleased', x, y, button: 'left', clickCount: 1,
+    });
+  } catch (err) {
+    // Element has no layout (display:none, zero-size, detached) — fall back to JS click
+    if (err.message && err.message.includes('layout object')) {
+      const { nodeId } = await session.send('DOM.requestNode', { backendNodeId });
+      const { object } = await session.send('DOM.resolveNode', { nodeId });
+      await session.send('Runtime.callFunctionOn', {
+        objectId: object.objectId,
+        functionDeclaration: 'function() { this.click(); }',
+      });
+    } else {
+      throw err;
+    }
+  }
 }
 
 /**