@web-auto/camo 0.1.25 → 0.1.26

package/README.md

@@ -473,6 +473,7 @@ Condition types:
 
 ### Environment Variables
 
+- `CAMO_INPUT_MODE` - Input mode: `playwright` (default) or `cdp`. CDP mode uses `Input.dispatchMouseEvent` via Chrome DevTools Protocol, bypassing OS-level input system. Does not require window foreground. See [CDP Input Mode](#cdp-input-mode) below.
 - `CAMO_BROWSER_URL` - Browser service URL (default: `http://127.0.0.1:7704`)
 - `CAMO_INSTALL_DIR` - `@web-auto/camo` 安装目录（可选，首次安装兜底）
 - `CAMO_REPO_ROOT` - Camo repository root (optional, dev mode)
@@ -484,6 +485,51 @@ Condition types:
 - `CAMO_PROGRESS_WS_HOST` / `CAMO_PROGRESS_WS_PORT` - Progress websocket daemon bind address (default: `127.0.0.1:7788`)
 - `CAMO_DEFAULT_WINDOW_VERTICAL_RESERVE` - Reserved vertical pixels for default headful auto-size
 
+### CDP Input Mode
+
+By default, Camo uses Playwright's high-level input API (`page.mouse.click`), which goes through the OS input system and requires the browser window to be in the foreground. This can cause hangs (up to 30s timeout) on Windows when the window loses focus.
+
+CDP mode sends mouse events directly via the Chrome DevTools Protocol (`Input.dispatchMouseEvent`), which:
+
+- **Does not require window foreground** — works with minimized, background, or headless windows
+- **Does not depend on OS input system** — no `bringToFront`, no `ensureInputReady`
+- **Bypasses input pipeline checks** — no 30s timeout risk from `ensureInputReady` hanging
+
+#### How to enable
+
+```bash
+# Environment variable (recommended)
+CAMO_INPUT_MODE=cdp camo start xhs-qa-1 --url https://www.xiaohongshu.com
+
+# Or set in shell profile
+export CAMO_INPUT_MODE=cdp
+```
+
+#### Behavior differences
+
+| Feature | Playwright (default) | CDP mode |
+|---------|---------------------|----------|
+| Window foreground required | Yes | No |
+| OS input system | Yes | No |
+| Auto-scroll to element | Yes (via Playwright) | No (caller must ensure element in viewport) |
+| `ensureInputReady` check | Yes (can hang 30s) | Skipped |
+| `bringToFront` | Yes (default) | Skipped |
+| Nudge/recovery on timeout | Yes | No (fast fail) |
+| Input coordinate system | Viewport-relative | Viewport-relative (same) |
+
+#### Limitations
+
+- **Element must be in viewport**: CDP clicks at coordinates only. If the target element is scrolled out of view, the click will miss. Callers (like webauto's `clickPoint`) already resolve viewport-relative coordinates via `getBoundingClientRect`.
+- **No auto-scroll**: Unlike Playwright's `page.click(selector)`, CDP mode does not scroll to bring elements into view.
+- **keyboard operations still use Playwright**: `keyboard:press` and `keyboard:type` are not affected by CDP mode (they already work reliably in background via Playwright's keyboard API).
+
+#### Related environment variables
+
+- `CAMO_INPUT_ACTION_TIMEOUT_MS` — Max wait for input action (default: 30000)
+- `CAMO_INPUT_ACTION_MAX_ATTEMPTS` — Retry count on failure (default: 2)
+- `CAMO_INPUT_READY_SETTLE_MS` — Settle time after input ready (default: 80)
+- `CAMO_BRING_TO_FRONT_MODE` — `never` (skip) or `auto` (default, bring window to front)
+
 ## Session Persistence
 
 Camo CLI persists session information locally:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-auto/camo",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Camoufox Browser CLI - Cross-platform browser automation",
   "type": "module",
   "bin": {

package/src/services/browser-service/internal/browser-session/input-ops.js

@@ -1,4 +1,39 @@
 import { isTimeoutLikeError } from './utils.js';
+import { resolveInputMode } from './utils.js';
+
+async function createCDPSession(page) {
+    const context = page.context();
+    return context.newCDPSession(page);
+}
+
+async function cdpMouseClick(cdp, x, y, button = 'left', delay = 50) {
+    const normalizedButton = button === 'left' ? 'left' : button === 'right' ? 'right' : button === 'middle' ? 'middle' : 'left';
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mousePressed',
+        x: Math.round(x),
+        y: Math.round(y),
+        button: normalizedButton,
+        clickCount: 1
+    });
+    if (delay > 0) {
+        await new Promise(r => setTimeout(r, delay));
+    }
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mouseReleased',
+        x: Math.round(x),
+        y: Math.round(y),
+        button: normalizedButton,
+        clickCount: 1
+    });
+}
+
+async function cdpMouseMove(cdp, x, y) {
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mouseMoved',
+        x: Math.round(x),
+        y: Math.round(y)
+    });
+}
 
 async function readInteractiveViewport(page) {
     const fallback = page.viewportSize?.() || null;
@@ -39,9 +74,34 @@ export class BrowserSessionInputOps {
         this.withInputActionLock = withInputActionLock;
         const envMode = String(process.env.CAMO_SCROLL_INPUT_MODE || '').trim().toLowerCase();
         this.wheelMode = envMode === 'keyboard' ? 'keyboard' : 'wheel';
+        this.inputMode = resolveInputMode();
     }
     async mouseClick(opts) {
         const page = await this.ensurePrimaryPage();
+
+        if (this.inputMode === 'cdp') {
+            const { x, y, button = 'left', clicks = 1, delay = 50 } = opts;
+            let cdp = null;
+            try {
+                cdp = await createCDPSession(page);
+                for (let i = 0; i < clicks; i++) {
+                    if (i > 0) {
+                        await new Promise(r => setTimeout(r, 100 + Math.random() * 100));
+                    }
+                    await this.withInputActionLock(async () => {
+                        await this.runInputAction(page, 'mouse:click(cdp)', async () => {
+                            await cdpMouseClick(cdp, x, y, button, delay);
+                        });
+                    });
+                }
+            } finally {
+                if (cdp) {
+                    await cdp.detach().catch(() => {});
+                }
+            }
+            return;
+        }
+
         await this.withInputActionLock(async () => {
             await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
             const { x, y, button = 'left', clicks = 1, delay = 50, nudgeBefore = false } = opts;

package/src/services/browser-service/internal/browser-session/input-pipeline.js

@@ -1,4 +1,4 @@
-import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs, shouldSkipBringToFront } from './utils.js';
+import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputMode, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs, shouldSkipBringToFront } from './utils.js';
 import { ensurePageRuntime } from '../pageRuntime.js';
 export class BrowserInputPipeline {
     ensurePrimaryPage;
@@ -9,6 +9,8 @@ export class BrowserInputPipeline {
     }
     inputActionTail = Promise.resolve();
     async ensureInputReady(page) {
+        if (resolveInputMode() === 'cdp')
+            return;
         if (this.isHeadless())
             return;
         if (shouldSkipBringToFront()) {

package/src/services/browser-service/internal/browser-session/utils.js

@@ -46,6 +46,12 @@ export function isTimeoutLikeError(error) {
     const message = String(error?.message || error || '').toLowerCase();
     return message.includes('timed out') || message.includes('timeout');
 }
+
+export function resolveInputMode() {
+    const raw = String(process.env.CAMO_INPUT_MODE ?? '').trim().toLowerCase();
+    return raw === 'cdp' ? 'cdp' : 'playwright';
+}
+
 export function normalizeUrl(raw) {
     try {
         const url = new URL(raw);