surfagent 1.1.2 → 1.2.1

package/AGENT.md

@@ -82,6 +82,12 @@ curl -X POST localhost:3456/type -H 'Content-Type: application/json' -d '{"tab":
 # Captcha detection and interaction (experimental)
 curl -X POST localhost:3456/captcha -H 'Content-Type: application/json' -d '{"tab":"0","action":"detect"}'
 
+# Dispatch DOM events — for React SPAs where /click or /fill submit fails
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"form[role=search]","event":"submit"}'
+
+# React debug — find event handlers on element and ancestors
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"[role=option]","reactDebug":true}'
+
 # List tabs
 curl localhost:3456/tabs
 
@@ -154,7 +160,7 @@ surfagent start
     └── Starts API Server (:3456)
         │
         ├── src/api/recon.ts    (page reconnaissance)
-        ├── src/api/act.ts      (fill, click, scroll, read, navigate, eval, captcha)
+        ├── src/api/act.ts      (fill, click, scroll, read, navigate, eval, dispatch, captcha)
         └── src/api/server.ts   (HTTP routing)
              │
              └── src/chrome/    (CDP connection layer)
@@ -183,6 +189,12 @@ surfagent start
 - Use the API `/fill` endpoint — it uses real CDP keystrokes
 - For SPAs, use `"submit": "enter"` instead of clicking submit buttons
 
+**React SPA — click/submit doesn't trigger navigation**
+- This happens when React event handlers are on ancestor elements, not the element you're clicking
+- Use `"submit": "form"` in `/fill` — dispatches a native submit event on the nearest `<form>`, which React picks up
+- For non-form cases, use `/dispatch` with `"reactDebug": true` to find which ancestor has the handler, then `/dispatch` the right event on it
+- Example (X.com search): `/fill` with `submit:"form"` works where `submit:"enter"` fails because the autocomplete combobox swallows the Enter key
+
 **Links opening new tabs instead of navigating**
 - The API `/click` handles `target="_blank"` automatically
 - It overrides the target and navigates in the same tab

package/API.md

@@ -324,6 +324,7 @@ Fill form fields using real CDP keyboard input. This simulates actual keystrokes
 
 **Submit options:**
 - `"enter"` — press Enter key via CDP. Best option for single-page apps (SPAs).
+- `"form"` — dispatch a native `submit` event on the nearest `<form>` ancestor. **Use this for React SPAs** where Enter is intercepted by autocomplete/combobox widgets (e.g. X.com search, GitHub search).
 - `"auto"` — finds and clicks the nearest `button[type="submit"]` or `input[type="submit"]`.
 - `"#my-button"` — clicks a specific selector.
 
@@ -447,6 +448,55 @@ Check if the API can connect to Chrome.
 
 ---
 
+### POST /dispatch
+
+Dispatch any DOM event on any element. Built to solve React/Vue/Angular SPAs where `.click()` and CDP key events don't trigger framework event handlers.
+
+**Dispatch an event:**
+```json
+{ "tab": "0", "selector": "form[role=search]", "event": "submit" }
+```
+
+**With options:**
+```json
+{ "tab": "0", "selector": "#my-input", "event": "keydown", "eventInit": { "key": "Enter", "code": "Enter" } }
+```
+
+**React debug mode** — find all React event handlers on an element and its ancestors:
+```json
+{ "tab": "0", "selector": "[role=option]", "reactDebug": true }
+```
+
+**Parameters:**
+- `selector` (string, required) — CSS selector for target element
+- `event` (string, required unless reactDebug) — Event type: `"submit"`, `"click"`, `"input"`, `"change"`, `"keydown"`, `"pointerdown"`, etc.
+- `bubbles` (boolean) — Default: `true`. Set to `false` to prevent event bubbling.
+- `cancelable` (boolean) — Default: `true`
+- `detail` (any) — Payload for CustomEvent
+- `eventInit` (object) — Extra properties merged into the event constructor (e.g. `{key: "Enter"}` for KeyboardEvent)
+- `reactDebug` (boolean) — Instead of dispatching, return all React event handlers found walking up the DOM tree from the selector
+
+**Event response:**
+```json
+{ "success": true, "dispatched": "submit on FORM[role=search]", "_dispatchMs": 25 }
+```
+
+**React debug response:**
+```json
+{
+  "success": true,
+  "reactHandlers": [
+    { "tag": "FORM", "role": "search", "testid": null, "className": "...", "handlers": ["onSubmit"] },
+    { "tag": "DIV", "role": null, "testid": null, "className": "...", "handlers": ["onKeyDown"] },
+    { "tag": "DIV", "role": null, "testid": null, "className": "...", "handlers": ["onClick"] }
+  ]
+}
+```
+
+**When to use:** When `/click` or `/fill` submit doesn't trigger navigation or actions on React SPAs. Use `reactDebug` first to find which ancestor has the handler, then dispatch the right event on it.
+
+---
+
 ### POST /type
 
 Raw CDP key typing without clearing the field first. Use this for apps like **Google Sheets**, contenteditable elements, or any context where `/fill`'s Ctrl+A clear step causes side effects (e.g., selecting all cells instead of clearing a field).
@@ -613,9 +663,32 @@ const CDP = require('chrome-remote-interface');
 
 **Using the menu search:** Google Sheets has a menu search box (`input[aria-label="Menus"]` or `input[aria-label="Menus (Option+/)"]`). Use `/fill` to type a command (e.g., "Insert chart"), then `/click` on the matching result.
 
+**Clearing/removing wrong cell entries:** You cannot send Delete or Backspace keys to Google Sheets via CDP — they don't reach the grid. Instead, overwrite the cell with a space:
+
+```
+1. POST /click    { "tab": "sheets", "selector": "#t-name-box" }
+2. POST /fill     { "tab": "sheets", "fields": [{ "selector": "#t-name-box", "value": "F1", "clear": true }], "submit": "enter" }
+   → Navigate to the cell you want to clear
+3. POST /type     { "tab": "sheets", "keys": " ", "submit": "enter" }
+   → Overwrite with a space (effectively blanks the cell)
+```
+
+Repeat for each cell. Do NOT try `Delete`, `Backspace`, or `Cmd+Z` via CDP key events — they are silently ignored by the Sheets grid. The `/type` space-overwrite is the only reliable method.
+
+**Avoiding wrong entries in the first place:** When entering rows of data, always navigate to the first cell of each new row via the name box. Pressing Enter after the last column does NOT return to column A — it moves down within the same column. So after completing a row with Tab across columns:
+
+```
+# Wrong: pressing Enter after last column stays in that column
+# Right: use name box to jump to start of next row
+POST /click  { "tab": "sheets", "selector": "#t-name-box" }
+POST /fill   { "tab": "sheets", "fields": [{ "selector": "#t-name-box", "value": "A3", "clear": true }], "submit": "enter" }
+```
+
 **Key gotchas:**
 - Never use `/fill` directly on Google Sheets cells — it will wipe data via Ctrl+A
 - Always navigate to a cell via the name box first, then `/type`
+- Always use the name box to navigate to the start of each new row — Tab+Enter does not wrap back to column A
+- CDP keyboard events (Delete, Backspace, Cmd+Z) do not work on the Sheets grid — use space-overwrite instead
 - Some buttons (Add Sheet, menu items) only respond to CDP mouse events, not DOM clicks
 - Navigating away from unsaved Sheets triggers a native Chrome dialog — see the "Native Chrome Dialogs" section below
 
@@ -758,6 +831,70 @@ if let windows = windowsRef as? [AXUIElement] {
 
 ---
 
+## React SPAs — When `/click` and `/fill` Submit Don't Work
+
+React, Vue, and Angular use synthetic event systems with event delegation. Sometimes `.click()` and CDP key events don't trigger framework handlers — especially on comboboxes, autocomplete widgets, and custom dropdowns.
+
+**Symptoms:**
+- `/click` returns `success: true` but nothing happens
+- `/fill` with `submit: "enter"` fills the input but doesn't navigate
+- CDP `Input.dispatchMouseEvent` / `Input.dispatchKeyEvent` are silently ignored
+
+**Diagnosis — use `/dispatch` with `reactDebug`:**
+
+```bash
+# Find which elements have React handlers and what events they listen for
+curl -X POST localhost:3456/dispatch -d '{"tab":"0","selector":"[role=option]","reactDebug":true}'
+```
+
+This walks up the DOM from your target element, inspecting `__reactProps$*` on each ancestor, and returns every React event handler it finds. The response tells you exactly which element to target and which event to dispatch.
+
+**Fix — dispatch the right event on the right element:**
+
+```bash
+# Dispatch a submit event on a form (most common fix for search boxes)
+curl -X POST localhost:3456/dispatch -d '{"tab":"0","selector":"form[role=search]","event":"submit"}'
+
+# Or dispatch a click on the ancestor that has the onClick handler
+curl -X POST localhost:3456/dispatch -d '{"tab":"0","selector":"div[data-testid=wrapper]","event":"click"}'
+```
+
+**Or use `/fill` with `submit: "form"` (one-step shortcut):**
+
+```bash
+curl -X POST localhost:3456/fill -d '{"tab":"0","fields":[{"selector":"input[aria-label=\"Search query\"]","value":"my query"}],"submit":"form"}'
+```
+
+### X.com (Twitter) Search — worked example
+
+X.com's search combobox is a textbook case. The `role="option"` autocomplete suggestions have **zero event handlers** — the `onClick` lives on a distant ancestor DIV, `onKeyDown` on a separate container, and `onSubmit` on the form.
+
+**What works:**
+```
+POST /fill  { "tab": "0", "fields": [{ "selector": "input[aria-label=\"Search query\"]", "value": "query" }], "submit": "form" }
+```
+
+**Fallback — URL navigation:**
+```
+POST /navigate  { "tab": "0", "url": "https://x.com/search?q=your%20query&src=typed_query&f=top" }
+```
+Query parameters: `q` (query), `f` (`top`, `latest`, `people`, `photos`, `videos`).
+
+### General debugging workflow for any React SPA
+
+```
+1. Try /click or /fill with submit:"enter" first — it works on most sites
+2. If it fails:
+   POST /dispatch  { "tab": "0", "selector": "THE_STUCK_ELEMENT", "reactDebug": true }
+   → Read the handler tree to find which ancestor has which handler
+3. Dispatch the right event:
+   POST /dispatch  { "tab": "0", "selector": "THE_ANCESTOR", "event": "THE_EVENT" }
+4. If it's a form with an input, use submit:"form" shortcut:
+   POST /fill      { "tab": "0", "fields": [...], "submit": "form" }
+```
+
+---
+
 ## Important Notes
 
 - **Always recon before acting.** The selectors you need come from the recon response.

package/CLAUDE.md

@@ -82,6 +82,12 @@ curl -X POST localhost:3456/type -H 'Content-Type: application/json' -d '{"tab":
 # Captcha detection and interaction (experimental)
 curl -X POST localhost:3456/captcha -H 'Content-Type: application/json' -d '{"tab":"0","action":"detect"}'
 
+# Dispatch DOM events (React SPA workaround when /click or /fill submit fails)
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"form[role=search]","event":"submit"}'
+
+# React debug — find event handlers on element ancestors
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"[role=option]","reactDebug":true}'
+
 # List tabs
 curl localhost:3456/tabs
 

package/dist/api/act.d.ts

@@ -99,3 +99,22 @@ export declare function typeKeys(tabPattern: string, keys: string, options: {
     typed: number;
     submitted?: boolean;
 }>;
+export interface DispatchRequest {
+    tab: string;
+    selector: string;
+    event: string;
+    bubbles?: boolean;
+    cancelable?: boolean;
+    detail?: any;
+    eventInit?: Record<string, any>;
+    reactDebug?: boolean;
+}
+export declare function dispatchEvent(request: DispatchRequest, options: {
+    port?: number;
+    host?: string;
+}): Promise<{
+    success: boolean;
+    dispatched?: string;
+    reactHandlers?: any[];
+    error?: string;
+}>;

package/dist/api/act.js

@@ -142,6 +142,29 @@ export async function fillFields(request, options) {
                 await cdp.Input.dispatchKeyEvent({ type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
                 await cdp.Input.dispatchKeyEvent({ type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
             }
+            else if (request.submit === 'form') {
+                // Dispatch native submit event on nearest form — works on React SPAs where Enter is intercepted
+                // (e.g. X.com search combobox, autocomplete widgets that swallow Enter key)
+                await client.Runtime.evaluate({
+                    expression: `
+            (function() {
+              // Find the last filled field and its nearest form ancestor
+              const lastSelector = ${JSON.stringify(request.fields.length > 0 ? request.fields[request.fields.length - 1].selector : null)};
+              let form;
+              if (lastSelector) {
+                const field = document.querySelector(lastSelector);
+                form = field ? field.closest('form') : null;
+              }
+              if (!form) {
+                form = document.querySelector('form');
+              }
+              if (!form) throw new Error('No form found');
+              form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            })()
+          `,
+                    returnByValue: true
+                });
+            }
             else {
                 const submitSelector = request.submit === 'auto'
                     ? 'button[type="submit"], input[type="submit"]'
@@ -707,3 +730,80 @@ export async function typeKeys(tabPattern, keys, options) {
         throw error;
     }
 }
+export async function dispatchEvent(request, options) {
+    const port = options.port || 9222;
+    const host = options.host || 'localhost';
+    const tab = await resolveTab(request.tab, port, host);
+    const client = await connectToTab(tab.id, port, host);
+    try {
+        const result = await client.Runtime.evaluate({
+            expression: `
+        (function() {
+          const selector = ${JSON.stringify(request.selector)};
+          const eventType = ${JSON.stringify(request.event)};
+          const bubbles = ${request.bubbles !== false};
+          const cancelable = ${request.cancelable !== false};
+          const detail = ${JSON.stringify(request.detail || null)};
+          const extraInit = ${JSON.stringify(request.eventInit || {})};
+          const reactDebug = ${JSON.stringify(!!request.reactDebug)};
+
+          const el = document.querySelector(selector);
+          if (!el) return { success: false, error: 'Element not found: ' + selector };
+
+          // React debug: walk up tree and find all React event handlers
+          if (reactDebug) {
+            const handlers = [];
+            let current = el;
+            while (current && current !== document.documentElement) {
+              const propsKey = Object.keys(current).find(k => k.startsWith('__reactProps'));
+              if (propsKey) {
+                const props = current[propsKey] || {};
+                const reactHandlers = Object.keys(props).filter(k => typeof props[k] === 'function' && k.startsWith('on'));
+                if (reactHandlers.length > 0) {
+                  handlers.push({
+                    tag: current.tagName,
+                    role: current.getAttribute('role'),
+                    testid: current.getAttribute('data-testid'),
+                    className: (current.className || '').toString().substring(0, 60),
+                    handlers: reactHandlers
+                  });
+                }
+              }
+              current = current.parentElement;
+            }
+            return { success: true, reactHandlers: handlers };
+          }
+
+          // Build the event object
+          let event;
+          const init = { bubbles, cancelable, ...extraInit };
+
+          // Use specific event constructors for better compatibility
+          if (eventType === 'click' || eventType === 'mousedown' || eventType === 'mouseup' || eventType === 'dblclick') {
+            event = new MouseEvent(eventType, init);
+          } else if (eventType === 'keydown' || eventType === 'keyup' || eventType === 'keypress') {
+            event = new KeyboardEvent(eventType, init);
+          } else if (eventType === 'input' || eventType === 'change') {
+            event = new Event(eventType, init);
+          } else if (eventType === 'pointerdown' || eventType === 'pointerup' || eventType === 'pointermove') {
+            event = new PointerEvent(eventType, init);
+          } else if (detail !== null) {
+            event = new CustomEvent(eventType, { ...init, detail });
+          } else {
+            event = new Event(eventType, init);
+          }
+
+          el.dispatchEvent(event);
+          return { success: true, dispatched: eventType + ' on ' + el.tagName + (el.getAttribute('role') ? '[role=' + el.getAttribute('role') + ']' : '') };
+        })()
+      `,
+            returnByValue: true
+        });
+        await client.close();
+        return result.result.value;
+    }
+    catch (error) {
+        await client.close();
+        throw error;
+    }
+}

package/dist/api/server.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import http from 'node:http';
 import { reconUrl, reconTab } from './recon.js';
-import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys } from './act.js';
+import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys, dispatchEvent } from './act.js';
 import { getAllTabs } from '../chrome/tabs.js';
 const PORT = parseInt(process.env.API_PORT || '3456', 10);
 const CDP_PORT = parseInt(process.env.CDP_PORT || '9222', 10);
@@ -150,6 +150,16 @@ const server = http.createServer(async (req, res) => {
             const result = await typeKeys(body.tab, body.keys, { port: CDP_PORT, host: CDP_HOST, submit: body.submit });
             return json(res, 200, result);
         }
+        // POST /dispatch — dispatch DOM events on elements (React SPA workaround)
+        if (path === '/dispatch' && req.method === 'POST') {
+            const body = parseBody(await readBody(req));
+            if (!body.tab || !body.selector || (!body.event && !body.reactDebug)) {
+                return json(res, 400, { error: 'Provide "tab", "selector", and "event" (e.g. "submit", "click"). Add "reactDebug":true to inspect React handlers instead.' });
+            }
+            const start = Date.now();
+            const result = await dispatchEvent(body, { port: CDP_PORT, host: CDP_HOST });
+            return json(res, 200, { ...result, _dispatchMs: Date.now() - start });
+        }
         // POST /navigate — go to url, back, or forward in same tab
         if (path === '/navigate' && req.method === 'POST') {
             const body = parseBody(await readBody(req));
@@ -180,7 +190,7 @@ const server = http.createServer(async (req, res) => {
                 return json(res, 503, { status: 'error', cdpConnected: false });
             }
         }
-        json(res, 404, { error: 'Not found. Endpoints: POST /recon, /read, /fill, /click, /type, /scroll, /navigate, /eval, /dismiss, /captcha, /focus | GET /tabs, /health' });
+        json(res, 404, { error: 'Not found. Endpoints: POST /recon, /read, /fill, /click, /type, /scroll, /navigate, /eval, /dispatch, /dismiss, /captcha, /focus | GET /tabs, /health' });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -212,6 +222,7 @@ server.listen(PORT, () => {
     console.log(`  POST /recon   — { url: "..." } or { tab: "0" }`);
     console.log(`  POST /fill    — { tab, fields: [{ selector, value }], submit? }`);
     console.log(`  POST /click   — { tab, selector? , text? }`);
+    console.log(`  POST /dispatch— { tab, selector, event, reactDebug? }`);
     console.log(`  GET  /tabs    — list open Chrome tabs`);
     console.log(`  GET  /health  — check CDP connection`);
 });

package/dist/cli.js

@@ -28,6 +28,12 @@ function detectOS() {
     return 'linux';
 }
 function getChromePath() {
+    if (process.env.BROWSER_PATH) {
+        if (fs.existsSync(process.env.BROWSER_PATH))
+            return process.env.BROWSER_PATH;
+        console.error(`[surfagent] BROWSER_PATH set but not found: ${process.env.BROWSER_PATH}`);
+        return null;
+    }
     const os = detectOS();
     const paths = {
         mac: [
@@ -118,6 +124,7 @@ Usage:
 Environment variables:
   CDP_PORT            Chrome debug port (default: 9222)
   API_PORT            API server port (default: 3456)
+  BROWSER_PATH          Path to any Chromium-based browser (Arc, Brave, Edge, etc.)
   CHROME_USER_DATA_DIR  Chrome profile directory (default: /tmp/surfagent-chrome)
 
 After starting, your AI agent can call http://localhost:3456
@@ -148,7 +155,7 @@ Full API docs: https://github.com/AllAboutAI-YT/surfagent#readme
         }
         const chromePath = getChromePath();
         if (!chromePath) {
-            console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+            console.error('[surfagent] Chrome not found. Install Google Chrome or set BROWSER_PATH to a Chromium-based browser.');
             process.exit(1);
         }
         startChrome(chromePath);
@@ -179,7 +186,7 @@ Full API docs: https://github.com/AllAboutAI-YT/surfagent#readme
         else {
             const chromePath = getChromePath();
             if (!chromePath) {
-                console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+                console.error('[surfagent] Chrome not found. Install Google Chrome or set BROWSER_PATH to a Chromium-based browser.');
                 process.exit(1);
             }
             startChrome(chromePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surfagent",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "Browser automation API for AI agents — structured page recon, form filling, clicking, and navigation via Chrome CDP",
   "keywords": [
     "ai-agent",

package/src/api/act.ts

@@ -163,6 +163,28 @@ export async function fillFields(
         // Press Enter via CDP — works on SPAs like YouTube
         await cdp.Input.dispatchKeyEvent({ type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
         await cdp.Input.dispatchKeyEvent({ type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
+      } else if (request.submit === 'form') {
+        // Dispatch native submit event on nearest form — works on React SPAs where Enter is intercepted
+        // (e.g. X.com search combobox, autocomplete widgets that swallow Enter key)
+        await client.Runtime.evaluate({
+          expression: `
+            (function() {
+              // Find the last filled field and its nearest form ancestor
+              const lastSelector = ${JSON.stringify(request.fields.length > 0 ? request.fields[request.fields.length - 1].selector : null)};
+              let form;
+              if (lastSelector) {
+                const field = document.querySelector(lastSelector);
+                form = field ? field.closest('form') : null;
+              }
+              if (!form) {
+                form = document.querySelector('form');
+              }
+              if (!form) throw new Error('No form found');
+              form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            })()
+          `,
+          returnByValue: true
+        });
       } else {
         const submitSelector = request.submit === 'auto'
           ? 'button[type="submit"], input[type="submit"]'
@@ -815,3 +837,99 @@ export async function typeKeys(
     throw error;
   }
 }
+
+// POST /dispatch — dispatch any DOM event on any element
+// Solves React SPAs where .click() and CDP key events don't trigger synthetic event handlers
+export interface DispatchRequest {
+  tab: string;
+  selector: string;          // CSS selector for target element
+  event: string;             // Event type: "submit", "click", "input", "change", "focus", "blur", etc.
+  bubbles?: boolean;         // Default: true
+  cancelable?: boolean;      // Default: true
+  detail?: any;              // For CustomEvent detail payload
+  eventInit?: Record<string, any>; // Extra event init properties (e.g. {key: "Enter"} for KeyboardEvent)
+  reactDebug?: boolean;      // If true, return React event handlers found on element and ancestors
+}
+
+export async function dispatchEvent(
+  request: DispatchRequest,
+  options: { port?: number; host?: string }
+): Promise<{ success: boolean; dispatched?: string; reactHandlers?: any[]; error?: string }> {
+  const port = options.port || 9222;
+  const host = options.host || 'localhost';
+
+  const tab = await resolveTab(request.tab, port, host);
+  const client = await connectToTab(tab.id, port, host);
+
+  try {
+    const result = await client.Runtime.evaluate({
+      expression: `
+        (function() {
+          const selector = ${JSON.stringify(request.selector)};
+          const eventType = ${JSON.stringify(request.event)};
+          const bubbles = ${request.bubbles !== false};
+          const cancelable = ${request.cancelable !== false};
+          const detail = ${JSON.stringify(request.detail || null)};
+          const extraInit = ${JSON.stringify(request.eventInit || {})};
+          const reactDebug = ${JSON.stringify(!!request.reactDebug)};
+
+          const el = document.querySelector(selector);
+          if (!el) return { success: false, error: 'Element not found: ' + selector };
+
+          // React debug: walk up tree and find all React event handlers
+          if (reactDebug) {
+            const handlers = [];
+            let current = el;
+            while (current && current !== document.documentElement) {
+              const propsKey = Object.keys(current).find(k => k.startsWith('__reactProps'));
+              if (propsKey) {
+                const props = current[propsKey] || {};
+                const reactHandlers = Object.keys(props).filter(k => typeof props[k] === 'function' && k.startsWith('on'));
+                if (reactHandlers.length > 0) {
+                  handlers.push({
+                    tag: current.tagName,
+                    role: current.getAttribute('role'),
+                    testid: current.getAttribute('data-testid'),
+                    className: (current.className || '').toString().substring(0, 60),
+                    handlers: reactHandlers
+                  });
+                }
+              }
+              current = current.parentElement;
+            }
+            return { success: true, reactHandlers: handlers };
+          }
+
+          // Build the event object
+          let event;
+          const init = { bubbles, cancelable, ...extraInit };
+
+          // Use specific event constructors for better compatibility
+          if (eventType === 'click' || eventType === 'mousedown' || eventType === 'mouseup' || eventType === 'dblclick') {
+            event = new MouseEvent(eventType, init);
+          } else if (eventType === 'keydown' || eventType === 'keyup' || eventType === 'keypress') {
+            event = new KeyboardEvent(eventType, init);
+          } else if (eventType === 'input' || eventType === 'change') {
+            event = new Event(eventType, init);
+          } else if (eventType === 'pointerdown' || eventType === 'pointerup' || eventType === 'pointermove') {
+            event = new PointerEvent(eventType, init);
+          } else if (detail !== null) {
+            event = new CustomEvent(eventType, { ...init, detail });
+          } else {
+            event = new Event(eventType, init);
+          }
+
+          el.dispatchEvent(event);
+          return { success: true, dispatched: eventType + ' on ' + el.tagName + (el.getAttribute('role') ? '[role=' + el.getAttribute('role') + ']' : '') };
+        })()
+      `,
+      returnByValue: true
+    });
+
+    await client.close();
+    return result.result.value as any;
+  } catch (error) {
+    await client.close();
+    throw error;
+  }
+}

package/src/api/server.ts

@@ -2,7 +2,7 @@
 
 import http from 'node:http';
 import { reconUrl, reconTab } from './recon.js';
-import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys } from './act.js';
+import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys, dispatchEvent } from './act.js';
 import { getAllTabs } from '../chrome/tabs.js';
 
 const PORT = parseInt(process.env.API_PORT || '3456', 10);
@@ -176,6 +176,17 @@ const server = http.createServer(async (req, res) => {
       return json(res, 200, result);
     }
 
+    // POST /dispatch — dispatch DOM events on elements (React SPA workaround)
+    if (path === '/dispatch' && req.method === 'POST') {
+      const body = parseBody(await readBody(req));
+      if (!body.tab || !body.selector || (!body.event && !body.reactDebug)) {
+        return json(res, 400, { error: 'Provide "tab", "selector", and "event" (e.g. "submit", "click"). Add "reactDebug":true to inspect React handlers instead.' });
+      }
+      const start = Date.now();
+      const result = await dispatchEvent(body, { port: CDP_PORT, host: CDP_HOST });
+      return json(res, 200, { ...result, _dispatchMs: Date.now() - start });
+    }
+
     // POST /navigate — go to url, back, or forward in same tab
     if (path === '/navigate' && req.method === 'POST') {
       const body = parseBody(await readBody(req));
@@ -208,7 +219,7 @@ const server = http.createServer(async (req, res) => {
       }
     }
 
-    json(res, 404, { error: 'Not found. Endpoints: POST /recon, /read, /fill, /click, /type, /scroll, /navigate, /eval, /dismiss, /captcha, /focus | GET /tabs, /health' });
+    json(res, 404, { error: 'Not found. Endpoints: POST /recon, /read, /fill, /click, /type, /scroll, /navigate, /eval, /dispatch, /dismiss, /captcha, /focus | GET /tabs, /health' });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`[${new Date().toISOString()}] Error:`, message);
@@ -242,6 +253,7 @@ server.listen(PORT, () => {
   console.log(`  POST /recon   — { url: "..." } or { tab: "0" }`);
   console.log(`  POST /fill    — { tab, fields: [{ selector, value }], submit? }`);
   console.log(`  POST /click   — { tab, selector? , text? }`);
+  console.log(`  POST /dispatch— { tab, selector, event, reactDebug? }`);
   console.log(`  GET  /tabs    — list open Chrome tabs`);
   console.log(`  GET  /health  — check CDP connection`);
 });

package/src/cli.ts

@@ -32,6 +32,11 @@ function detectOS(): 'mac' | 'linux' | 'windows' {
 }
 
 function getChromePath(): string | null {
+  if (process.env.BROWSER_PATH) {
+    if (fs.existsSync(process.env.BROWSER_PATH)) return process.env.BROWSER_PATH;
+    console.error(`[surfagent] BROWSER_PATH set but not found: ${process.env.BROWSER_PATH}`);
+    return null;
+  }
   const os = detectOS();
   const paths: Record<string, string[]> = {
     mac: [
@@ -127,6 +132,7 @@ Usage:
 Environment variables:
   CDP_PORT            Chrome debug port (default: 9222)
   API_PORT            API server port (default: 3456)
+  BROWSER_PATH          Path to any Chromium-based browser (Arc, Brave, Edge, etc.)
   CHROME_USER_DATA_DIR  Chrome profile directory (default: /tmp/surfagent-chrome)
 
 After starting, your AI agent can call http://localhost:3456
@@ -159,7 +165,7 @@ Full API docs: https://github.com/AllAboutAI-YT/surfagent#readme
 
     const chromePath = getChromePath();
     if (!chromePath) {
-      console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+      console.error('[surfagent] Chrome not found. Install Google Chrome or set BROWSER_PATH to a Chromium-based browser.');
       process.exit(1);
     }
 
@@ -193,7 +199,7 @@ Full API docs: https://github.com/AllAboutAI-YT/surfagent#readme
     } else {
       const chromePath = getChromePath();
       if (!chromePath) {
-        console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+        console.error('[surfagent] Chrome not found. Install Google Chrome or set BROWSER_PATH to a Chromium-based browser.');
         process.exit(1);
       }
       startChrome(chromePath);