@web-auto/camo 0.1.8 → 0.1.9

package/README.md

@@ -5,6 +5,17 @@
 
 A cross-platform command-line interface for Camoufox browser automation.
 
+## What Camo Provides
+
+- Browser lifecycle management: start/stop/list sessions, idle cleanup, lock cleanup.
+- Profile-first automation: persistent profile dirs, fingerprint support, remembered window size.
+- Browser control primitives: navigation, tabs, viewport/window, mouse and keyboard actions.
+- Devtools debugging helpers: open devtools, evaluate JS quickly, collect browser console logs.
+- Session recorder: JSONL interaction capture (click/input/scroll/keyboard + page visits) with runtime toggle.
+- Container subscription layer: selector registration, filter/list/watch in viewport.
+- Autoscript runtime: validate/explain/run/resume/mock-run with snapshot and replay.
+- Progress stream: local websocket daemon (`/events`) with tail/recent/emit commands.
+
 ## Installation
 
 ### npm (Recommended)
@@ -48,13 +59,66 @@ camo devtools eval worker-1 "document.title"
 # Read captured console entries
 camo devtools logs worker-1 --levels error,warn --limit 50
 
+# Start recording into JSONL (with in-page toggle)
+camo record start worker-1 --name run-a --output ./logs/run-a.jsonl --overlay
+
 # Navigate
 camo goto https://www.xiaohongshu.com
 
 # Interact
+camo highlight-mode on
+camo click "#search-input" --highlight
+camo type "#search-input" "hello world" --highlight
+camo scroll --down --amount 500 --selector ".feed-list"
+```
+
+## Core Workflows
+
+### 1) Interactive browser session
+
+```bash
+camo init
+camo profile create myprofile
+camo profile default myprofile
+camo start --url https://example.com --alias main
 camo click "#search-input"
 camo type "#search-input" "hello world"
-camo scroll --down --amount 500
+```
+
+### 2) Headless worker with idle auto-stop
+
+```bash
+camo start worker-1 --headless --alias shard1 --idle-timeout 30m
+camo instances
+camo stop idle
+```
+
+### 3) Devtools-style debugging
+
+```bash
+camo start myprofile --devtools
+camo devtools eval myprofile "document.title"
+camo devtools eval myprofile "(console.error('check-error'), location.href)"
+camo devtools logs myprofile --levels error,warn --limit 50
+camo devtools clear myprofile
+```
+
+### 4) Run autoscript with live progress
+
+```bash
+camo autoscript validate ./autoscripts/xhs.autoscript.json
+camo autoscript run ./autoscripts/xhs.autoscript.json --profile myprofile \
+  --jsonl-file ./runs/xhs/run.jsonl \
+  --summary-file ./runs/xhs/summary.json
+camo events tail --profile myprofile --mode autoscript
+```
+
+### 5) Record manual interactions as JSONL
+
+```bash
+camo start myprofile --record --record-name xhs-debug --record-output ./logs/xhs-debug.jsonl --record-overlay
+camo record status myprofile
+camo record stop myprofile
 ```
 
 ## Commands
@@ -77,10 +141,17 @@ camo init list                         # List available OS and regions
 camo create fingerprint --os <os> --region <region>
 ```
 
+### Config
+
+```bash
+camo config repo-root [path]           # Get/set persisted webauto repo root
+camo highlight-mode [status|on|off]    # Global highlight mode for click/type/scroll
+```
+
 ### Browser Control
 
 ```bash
-camo start [profileId] [--url <url>] [--headless] [--devtools] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]
+camo start [profileId] [--url <url>] [--headless] [--devtools] [--record] [--record-name <name>] [--record-output <path>] [--record-overlay|--no-record-overlay] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]
 camo stop [profileId]
 camo stop --id <instanceId>
 camo stop --alias <alias>
@@ -95,6 +166,7 @@ If no saved size exists, it defaults to near-fullscreen (full width, slight vert
 Use `--width/--height` to override and update the saved profile size.
 For headless sessions, default idle timeout is `30m` (auto-stop on inactivity). Use `--idle-timeout` (e.g. `45m`, `1800s`, `0`) to customize.
 Use `--devtools` to open browser developer tools in headed mode (cannot be combined with `--headless`).
+Use `--record` to auto-enable JSONL recording at startup; `--record-name`, `--record-output`, and `--record-overlay` customize file naming/output and floating toggle UI.
 
 ### Lifecycle & Cleanup
 
@@ -106,7 +178,6 @@ camo cleanup all                       # Cleanup all active sessions
 camo cleanup locks                     # Cleanup stale lock files
 camo force-stop [profileId]            # Force stop session (for stuck sessions)
 camo lock list                         # List active session locks
-camo recover [profileId]               # Recover orphaned session
 ```
 
 ### Navigation
@@ -120,9 +191,9 @@ camo screenshot [profileId] [--output <file>] [--full]
 ### Interaction
 
 ```bash
-camo scroll [profileId] [--down|--up|--left|--right] [--amount <px>]
-camo click [profileId] <selector>              # Click element by CSS selector
-camo type [profileId] <selector> <text>        # Type text into element
+camo scroll [profileId] [--down|--up|--left|--right] [--amount <px>] [--selector <css>] [--highlight|--no-highlight]
+camo click [profileId] <selector> [--highlight|--no-highlight]  # Click visible element by CSS selector
+camo type [profileId] <selector> <text> [--highlight|--no-highlight]  # Type into visible input element
 camo highlight [profileId] <selector>          # Highlight element (red border, 2s)
 camo clear-highlight [profileId]               # Clear all highlights
 camo viewport [profileId] --width <w> --height <h>
@@ -136,6 +207,26 @@ camo devtools eval [profileId] <expression> [--profile <id>]
 camo devtools clear [profileId]
 ```
 
+`devtools logs` reads entries from an injected in-page console collector.
+Supported levels: `log`, `info`, `warn`, `error`, `debug`.
+
+### Recording
+
+```bash
+camo record start [profileId] [--name <name>] [--output <file>] [--overlay|--no-overlay]
+camo record stop [profileId] [--reason <text>]
+camo record status [profileId]
+```
+
+Recorder JSONL events include:
+- `page.visit`
+- `interaction.click`
+- `interaction.keydown`
+- `interaction.input`
+- `interaction.wheel`
+- `interaction.scroll`
+- `recording.start|stop|toggled|runtime_ready`
+
 ### Pages
 
 ```bash
@@ -353,6 +444,7 @@ Condition types:
 - `WEBAUTO_CONTAINER_ROOT` - User container root override (default: `~/.webauto/container-lib`)
 - `CAMO_PROGRESS_EVENTS_FILE` - Optional progress event JSONL path override
 - `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
 
 ## Session Persistence
 
@@ -360,7 +452,6 @@ Camo CLI persists session information locally:
 
 - Sessions are registered in `~/.webauto/sessions/`
 - On restart, `camo sessions` / `camo instances` shows live + orphaned sessions
-- Use `camo recover <profileId>` to reconnect or cleanup orphaned sessions
 - Stale sessions (>7 days) are automatically cleaned up
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-auto/camo",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Camoufox Browser CLI - Cross-platform browser automation",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "check:file-size": "node scripts/check-file-size.mjs",
     "test": "node --test 'tests/**/*.test.mjs'",
     "test:coverage": "c8 --reporter=text --reporter=lcov node --test 'tests/**/*.test.mjs'",
+    "test:coverage:modes": "c8 --all --check-coverage --lines 90 --functions 90 --branches 90 --statements 90 --include src/commands/record.mjs --include src/commands/highlight-mode.mjs --include src/container/runtime-core/operations/selector-scripts.mjs node --test tests/unit/commands/record.test.mjs tests/unit/commands/highlight-mode.test.mjs tests/unit/container/selector-scripts.test.mjs tests/unit/commands/browser.test.mjs",
     "version:bump": "node scripts/bump-version.mjs",
     "install:global": "npm run build && npm install -g .",
     "uninstall:global": "npm uninstall -g @web-auto/camo",

package/src/autoscript/action-providers/xhs/comments.mjs

@@ -86,43 +86,6 @@ export function buildCommentsHarvestScript(params = {}) {
       }
       return null;
     };
-    const normalizeInlineText = (value) => String(value || '').replace(/\\s+/g, ' ').trim();
-    const sanitizeAuthorText = (raw, commentText = '') => {
-      const text = normalizeInlineText(raw);
-      if (!text) return '';
-      if (commentText && text === commentText) return '';
-      if (text.length > 40) return '';
-      if (/^(回复|展开|收起|查看更多|评论|赞|分享|发送)$/.test(text)) return '';
-      return text;
-    };
-    const readAuthor = (item, commentText = '') => {
-      const attrNames = ['data-user-name', 'data-username', 'data-user_nickname', 'data-nickname'];
-      for (const attr of attrNames) {
-        const value = sanitizeAuthorText(item.getAttribute?.(attr), commentText);
-        if (value) return value;
-      }
-      const selectors = [
-        '.comment-user .name',
-        '.comment-user .username',
-        '.comment-user .user-name',
-        '.author .name',
-        '.author',
-        '.user-name',
-        '.username',
-        '.name',
-        'a[href*="/user/profile/"]',
-        'a[href*="/user/"]',
-      ];
-      for (const selector of selectors) {
-        const node = item.querySelector(selector);
-        if (!node) continue;
-        const title = sanitizeAuthorText(node.getAttribute?.('title'), commentText);
-        if (title) return title;
-        const text = sanitizeAuthorText(node.textContent, commentText);
-        if (text) return text;
-      }
-      return '';
-    };
 
     const scroller = document.querySelector('.note-scroller')
       || document.querySelector('.comments-el')
@@ -142,8 +105,9 @@ export function buildCommentsHarvestScript(params = {}) {
       const nodes = Array.from(document.querySelectorAll('.comment-item, [class*="comment-item"]'));
       for (const item of nodes) {
         const textNode = item.querySelector('.content, .comment-content, p');
+        const authorNode = item.querySelector('.name, .author, .user-name, [class*="author"], [class*="name"]');
         const text = String((textNode && textNode.textContent) || '').trim();
-        const author = readAuthor(item, text);
+        const author = String((authorNode && authorNode.textContent) || '').trim();
         if (!text) continue;
         const key = author + '::' + text;
         if (commentMap.has(key)) continue;

package/src/autoscript/action-providers/xhs/interaction.mjs

@@ -74,42 +74,6 @@ function buildCollectLikeTargetsScript() {
       }
       return '';
     };
-    const sanitizeUserName = (raw, commentText = '') => {
-      const text = String(raw || '').replace(/\\s+/g, ' ').trim();
-      if (!text) return '';
-      if (commentText && text === commentText) return '';
-      if (text.length > 40) return '';
-      if (/^(回复|展开|收起|查看更多|评论|赞|分享|发送)$/.test(text)) return '';
-      return text;
-    };
-    const readUserName = (item, commentText = '') => {
-      const attrNames = ['data-user-name', 'data-username', 'data-user_nickname', 'data-nickname'];
-      for (const attr of attrNames) {
-        const value = sanitizeUserName(item.getAttribute?.(attr), commentText);
-        if (value) return value;
-      }
-      const selectors = [
-        '.comment-user .name',
-        '.comment-user .username',
-        '.comment-user .user-name',
-        '.author .name',
-        '.author',
-        '.user-name',
-        '.username',
-        '.name',
-        'a[href*="/user/profile/"]',
-        'a[href*="/user/"]',
-      ];
-      for (const selector of selectors) {
-        const node = item.querySelector(selector);
-        if (!node) continue;
-        const title = sanitizeUserName(node.getAttribute?.('title'), commentText);
-        if (title) return title;
-        const text = sanitizeUserName(node.textContent, commentText);
-        if (text) return text;
-      }
-      return '';
-    };
     const readAttr = (item, attrNames) => {
       for (const attr of attrNames) {
         const value = String(item.getAttribute?.(attr) || '').trim();
@@ -117,15 +81,6 @@ function buildCollectLikeTargetsScript() {
       }
       return '';
     };
-    const readUserId = (item) => {
-      const value = readAttr(item, ['data-user-id', 'data-userid', 'data-user_id']);
-      if (value) return value;
-      const anchor = item.querySelector('a[href*="/user/profile/"], a[href*="/user/"]');
-      const href = String(anchor?.getAttribute?.('href') || '').trim();
-      if (!href) return '';
-      const matched = href.match(/\\/user\\/(?:profile\\/)?([a-zA-Z0-9_-]+)/);
-      return matched && matched[1] ? matched[1] : '';
-    };
 
     const matchedSet = new Set(
       Array.isArray(state.matchedComments)
@@ -137,8 +92,8 @@ function buildCollectLikeTargetsScript() {
       const item = items[index];
       const text = readText(item, ['.content', '.comment-content', 'p']);
       if (!text) continue;
-      const userName = readUserName(item, text);
-      const userId = readUserId(item);
+      const userName = readText(item, ['.name', '.author', '.user-name', '.username', '[class*="author"]', '[class*="name"]']);
+      const userId = readAttr(item, ['data-user-id', 'data-userid', 'data-user_id']);
       const timestamp = readText(item, ['.date', '.time', '.timestamp', '[class*="time"]']);
       const likeControl = findLikeControl(item);
       rows.push({

package/src/cli.mjs

@@ -14,6 +14,8 @@ import { handleContainerCommand } from './commands/container.mjs';
 import { handleAutoscriptCommand } from './commands/autoscript.mjs';
 import { handleEventsCommand } from './commands/events.mjs';
 import { handleDevtoolsCommand } from './commands/devtools.mjs';
+import { handleRecordCommand } from './commands/record.mjs';
+import { handleHighlightModeCommand } from './commands/highlight-mode.mjs';
 import {
   handleStartCommand, handleStopCommand, handleStatusCommand,
   handleGotoCommand, handleBackCommand, handleScreenshotCommand,
@@ -72,6 +74,23 @@ function inferProfileId(cmd, args) {
     }
   }
 
+  if (cmd === 'record') {
+    const explicit = readFlagValue(args, ['--profile', '-p']);
+    if (explicit) return explicit;
+    const sub = positionals[0] || null;
+    const values = [];
+    for (let i = 2; i < args.length; i += 1) {
+      const token = args[i];
+      if (!token || String(token).startsWith('-')) continue;
+      const prev = args[i - 1];
+      if (prev && ['--name', '--output', '--reason'].includes(prev)) continue;
+      values.push(String(token));
+    }
+    if (sub === 'start' || sub === 'stop' || sub === 'status') {
+      return values[0] || null;
+    }
+  }
+
   if (cmd === 'autoscript' && positionals[0] === 'run') {
     return explicitProfile || null;
   }
@@ -205,6 +224,16 @@ async function main() {
     return;
   }
 
+  if (cmd === 'record') {
+    await runTrackedCommand(cmd, args, () => handleRecordCommand(args));
+    return;
+  }
+
+  if (cmd === 'highlight-mode') {
+    await runTrackedCommand(cmd, args, () => handleHighlightModeCommand(args));
+    return;
+  }
+
   // Lifecycle commands
   if (cmd === 'cleanup') {
     await runTrackedCommand(cmd, args, () => handleCleanupCommand(args));
@@ -250,7 +279,7 @@ async function main() {
     'start', 'stop', 'close', 'status', 'list', 'goto', 'navigate', 'back', 'screenshot',
     'new-page', 'close-page', 'switch-page', 'list-pages', 'shutdown',
     'scroll', 'click', 'type', 'highlight', 'clear-highlight', 'viewport',
-    'cookies', 'window', 'mouse', 'system', 'container', 'autoscript', 'events', 'devtools',
+    'cookies', 'window', 'mouse', 'system', 'container', 'autoscript', 'events', 'devtools', 'record', 'highlight-mode',
   ]);
 
   if (!serviceCommands.has(cmd)) {
@@ -325,6 +354,12 @@ async function main() {
       case 'system':
         await handleSystemCommand(args);
         break;
+      case 'record':
+        await handleRecordCommand(args);
+        break;
+      case 'highlight-mode':
+        await handleHighlightModeCommand(args);
+        break;
     }
   });
 }

package/src/commands/browser.mjs

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import {
   listProfiles,
   getDefaultProfile,
+  getHighlightMode,
   getProfileWindowSize,
   setProfileWindowSize,
 } from '../utils/config.mjs';
@@ -10,6 +12,7 @@ import { resolveProfileId, ensureUrlScheme, looksLikeUrlToken, getPositionals }
 import { acquireLock, releaseLock, cleanupStaleLocks } from '../lifecycle/lock.mjs';
 import {
   buildSelectorClickScript,
+  buildScrollTargetScript,
   buildSelectorTypeScript,
 } from '../container/runtime-core/operations/selector-scripts.mjs';
 import {
@@ -83,6 +86,12 @@ function validateAlias(alias) {
   return text.slice(0, 64);
 }
 
+function resolveHighlightEnabled(args) {
+  if (args.includes('--highlight')) return true;
+  if (args.includes('--no-highlight')) return false;
+  return getHighlightMode();
+}
+
 function formatDurationMs(ms) {
   const value = Number(ms);
   if (!Number.isFinite(value) || value <= 0) return 'disabled';
@@ -319,12 +328,27 @@ export async function handleStartCommand(args) {
   const idleTimeoutRaw = readFlagValue(args, ['--idle-timeout']);
   const parsedIdleTimeoutMs = parseDurationMs(idleTimeoutRaw, DEFAULT_HEADLESS_IDLE_TIMEOUT_MS);
   const wantsDevtools = args.includes('--devtools');
+  const wantsRecord = args.includes('--record');
+  const recordName = readFlagValue(args, ['--record-name']);
+  const recordOutputRaw = readFlagValue(args, ['--record-output']);
+  const recordOverlay = args.includes('--no-record-overlay')
+    ? false
+    : args.includes('--record-overlay')
+      ? true
+      : null;
   if (hasExplicitWidth !== hasExplicitHeight) {
-    throw new Error('Usage: camo start [profileId] [--url <url>] [--headless] [--devtools] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]');
+    throw new Error('Usage: camo start [profileId] [--url <url>] [--headless] [--devtools] [--record] [--record-name <name>] [--record-output <path>] [--record-overlay|--no-record-overlay] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]');
   }
   if ((hasExplicitWidth && explicitWidth < START_WINDOW_MIN_WIDTH) || (hasExplicitHeight && explicitHeight < START_WINDOW_MIN_HEIGHT)) {
     throw new Error(`Window size too small. Minimum is ${START_WINDOW_MIN_WIDTH}x${START_WINDOW_MIN_HEIGHT}`);
   }
+  if (args.includes('--record-name') && !recordName) {
+    throw new Error('Usage: camo start [profileId] --record-name <name>');
+  }
+  if (args.includes('--record-output') && !recordOutputRaw) {
+    throw new Error('Usage: camo start [profileId] --record-output <path>');
+  }
+  const recordOutput = recordOutputRaw ? path.resolve(recordOutputRaw) : null;
   const hasExplicitWindowSize = hasExplicitWidth && hasExplicitHeight;
   const profileSet = new Set(listProfiles());
   let implicitUrl;
@@ -334,8 +358,9 @@ export async function handleStartCommand(args) {
     const arg = args[i];
     if (arg === '--url') { i++; continue; }
     if (arg === '--width' || arg === '--height') { i++; continue; }
-    if (arg === '--alias' || arg === '--idle-timeout') { i++; continue; }
+    if (arg === '--alias' || arg === '--idle-timeout' || arg === '--record-name' || arg === '--record-output') { i++; continue; }
     if (arg === '--headless') continue;
+    if (arg === '--record' || arg === '--record-overlay' || arg === '--no-record-overlay') continue;
     if (arg.startsWith('--')) continue;
 
     if (looksLikeUrlToken(arg) && !profileSet.has(arg)) {
@@ -398,6 +423,14 @@ export async function handleStartCommand(args) {
     if (!existingHeadless && wantsDevtools) {
       payload.devtools = await requestDevtoolsOpen(profileId);
     }
+    if (wantsRecord) {
+      payload.recording = await callAPI('record:start', {
+        profileId,
+        ...(recordName ? { name: recordName } : {}),
+        ...(recordOutput ? { outputPath: recordOutput } : {}),
+        ...(recordOverlay !== null ? { overlay: recordOverlay } : {}),
+      });
+    }
     console.log(JSON.stringify(payload, null, 2));
     startSessionWatchdog(profileId);
     return;
@@ -423,6 +456,10 @@ export async function handleStartCommand(args) {
     url: targetUrl ? ensureUrlScheme(targetUrl) : undefined,
     headless,
     devtools: wantsDevtools,
+    ...(wantsRecord ? { record: true } : {}),
+    ...(recordName ? { recordName } : {}),
+    ...(recordOutput ? { recordOutput } : {}),
+    ...(recordOverlay !== null ? { recordOverlay } : {}),
   });
   
   if (result?.ok) {
@@ -729,32 +766,55 @@ export async function handleScrollCommand(args) {
   await ensureBrowserService();
   const directionFlags = new Set(['--up', '--down', '--left', '--right']);
   const isFlag = (arg) => arg?.startsWith('--');
+  const selectorIdx = args.indexOf('--selector');
+  const selector = selectorIdx >= 0 ? String(args[selectorIdx + 1] || '').trim() : null;
+  const highlight = resolveHighlightEnabled(args);
 
   let profileId = null;
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (directionFlags.has(arg)) continue;
     if (arg === '--amount') { i++; continue; }
+    if (arg === '--selector') { i++; continue; }
+    if (arg === '--highlight' || arg === '--no-highlight') continue;
     if (isFlag(arg)) continue;
     profileId = arg;
     break;
   }
   if (!profileId) profileId = getDefaultProfile();
-  if (!profileId) throw new Error('Usage: camo scroll [profileId] [--down|--up|--left|--right] [--amount <px>]');
+  if (!profileId) throw new Error('Usage: camo scroll [profileId] [--down|--up|--left|--right] [--amount <px>] [--selector <css>] [--highlight|--no-highlight]');
+  if (selectorIdx >= 0 && !selector) {
+    throw new Error('Usage: camo scroll [profileId] --selector <css>');
+  }
 
   const direction = args.includes('--up') ? 'up' : args.includes('--left') ? 'left' : args.includes('--right') ? 'right' : 'down';
   const amountIdx = args.indexOf('--amount');
   const amount = amountIdx >= 0 ? Number(args[amountIdx + 1]) || 300 : 300;
 
+  const target = await callAPI('evaluate', {
+    profileId,
+    script: buildScrollTargetScript({ selector, highlight }),
+  });
+  const centerX = Number(target?.result?.center?.x);
+  const centerY = Number(target?.result?.center?.y);
+  if (Number.isFinite(centerX) && Number.isFinite(centerY)) {
+    await callAPI('mouse:move', { profileId, x: centerX, y: centerY, steps: 2 });
+  }
+
   const deltaX = direction === 'left' ? -amount : direction === 'right' ? amount : 0;
   const deltaY = direction === 'up' ? -amount : direction === 'down' ? amount : 0;
   const result = await callAPI('mouse:wheel', { profileId, deltaX, deltaY });
-  console.log(JSON.stringify(result, null, 2));
+  console.log(JSON.stringify({
+    ...result,
+    scrollTarget: target?.result || null,
+    highlight,
+  }, null, 2));
 }
 
 export async function handleClickCommand(args) {
   await ensureBrowserService();
   const positionals = getPositionals(args);
+  const highlight = resolveHighlightEnabled(args);
   let profileId;
   let selector;
 
@@ -766,12 +826,12 @@ export async function handleClickCommand(args) {
     selector = positionals[1];
   }
 
-  if (!profileId) throw new Error('Usage: camo click [profileId] <selector>');
-  if (!selector) throw new Error('Usage: camo click [profileId] <selector>');
+  if (!profileId) throw new Error('Usage: camo click [profileId] <selector> [--highlight|--no-highlight]');
+  if (!selector) throw new Error('Usage: camo click [profileId] <selector> [--highlight|--no-highlight]');
 
   const result = await callAPI('evaluate', {
     profileId,
-    script: buildSelectorClickScript({ selector, highlight: false }),
+    script: buildSelectorClickScript({ selector, highlight }),
   });
   console.log(JSON.stringify(result, null, 2));
 }
@@ -779,6 +839,7 @@ export async function handleClickCommand(args) {
 export async function handleTypeCommand(args) {
   await ensureBrowserService();
   const positionals = getPositionals(args);
+  const highlight = resolveHighlightEnabled(args);
   let profileId;
   let selector;
   let text;
@@ -793,12 +854,12 @@ export async function handleTypeCommand(args) {
     text = positionals[2];
   }
 
-  if (!profileId) throw new Error('Usage: camo type [profileId] <selector> <text>');
-  if (!selector || text === undefined) throw new Error('Usage: camo type [profileId] <selector> <text>');
+  if (!profileId) throw new Error('Usage: camo type [profileId] <selector> <text> [--highlight|--no-highlight]');
+  if (!selector || text === undefined) throw new Error('Usage: camo type [profileId] <selector> <text> [--highlight|--no-highlight]');
 
   const result = await callAPI('evaluate', {
     profileId,
-    script: buildSelectorTypeScript({ selector, highlight: false, text }),
+    script: buildSelectorTypeScript({ selector, highlight, text }),
   });
   console.log(JSON.stringify(result, null, 2));
 }

package/src/commands/highlight-mode.mjs

@@ -0,0 +1,24 @@
+import { getHighlightMode, setHighlightMode } from '../utils/config.mjs';
+
+export async function handleHighlightModeCommand(args) {
+  const sub = String(args[1] || 'status').trim().toLowerCase();
+
+  if (sub === 'status') {
+    console.log(JSON.stringify({ ok: true, highlightMode: getHighlightMode() }, null, 2));
+    return;
+  }
+
+  if (sub === 'on' || sub === 'enable') {
+    const next = setHighlightMode(true);
+    console.log(JSON.stringify({ ok: true, highlightMode: next }, null, 2));
+    return;
+  }
+
+  if (sub === 'off' || sub === 'disable') {
+    const next = setHighlightMode(false);
+    console.log(JSON.stringify({ ok: true, highlightMode: next }, null, 2));
+    return;
+  }
+
+  throw new Error('Usage: camo highlight-mode [status|on|off]');
+}

package/src/commands/record.mjs

@@ -0,0 +1,115 @@
+import path from 'node:path';
+import { getDefaultProfile } from '../utils/config.mjs';
+import { callAPI, ensureBrowserService } from '../utils/browser-service.mjs';
+
+function readFlagValue(args, names) {
+  for (let i = 0; i < args.length; i += 1) {
+    if (!names.includes(args[i])) continue;
+    const value = args[i + 1];
+    if (!value || String(value).startsWith('-')) return null;
+    return value;
+  }
+  return null;
+}
+
+function collectPositionals(args, startIndex = 2) {
+  const values = [];
+  for (let i = startIndex; i < args.length; i += 1) {
+    const token = args[i];
+    if (!token || String(token).startsWith('-')) continue;
+    const prev = args[i - 1];
+    if (prev && ['--profile', '-p', '--name', '--output', '--reason'].includes(prev)) {
+      continue;
+    }
+    values.push(String(token));
+  }
+  return values;
+}
+
+function resolveProfileId(args, startIndex = 2) {
+  const explicit = readFlagValue(args, ['--profile', '-p']);
+  if (explicit) return explicit;
+  const positionals = collectPositionals(args, startIndex);
+  if (positionals.length > 0) return positionals[0];
+  return getDefaultProfile();
+}
+
+function parseOverlayFlag(args) {
+  if (args.includes('--no-overlay')) return false;
+  if (args.includes('--overlay')) return true;
+  return null;
+}
+
+async function handleRecordStart(args) {
+  await ensureBrowserService();
+  const profileId = resolveProfileId(args, 2);
+  if (!profileId) {
+    throw new Error('Usage: camo record start [profileId] [--name <name>] [--output <file>] [--overlay|--no-overlay]');
+  }
+  if (args.includes('--name') && !readFlagValue(args, ['--name'])) {
+    throw new Error('Usage: camo record start [profileId] --name <name>');
+  }
+  if (args.includes('--output') && !readFlagValue(args, ['--output'])) {
+    throw new Error('Usage: camo record start [profileId] --output <file>');
+  }
+  const name = readFlagValue(args, ['--name']);
+  const output = readFlagValue(args, ['--output']);
+  const overlay = parseOverlayFlag(args);
+  const result = await callAPI('record:start', {
+    profileId,
+    ...(name ? { name } : {}),
+    ...(output ? { outputPath: path.resolve(output) } : {}),
+    ...(overlay !== null ? { overlay } : {}),
+  });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function handleRecordStop(args) {
+  await ensureBrowserService();
+  const profileId = resolveProfileId(args, 2);
+  if (!profileId) {
+    throw new Error('Usage: camo record stop [profileId]');
+  }
+  const reason = readFlagValue(args, ['--reason']) || 'manual';
+  const result = await callAPI('record:stop', { profileId, reason });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function handleRecordStatus(args) {
+  await ensureBrowserService();
+  const profileId = resolveProfileId(args, 2);
+  if (!profileId) {
+    throw new Error('Usage: camo record status [profileId]');
+  }
+  const result = await callAPI('record:status', { profileId });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+export async function handleRecordCommand(args) {
+  const sub = String(args[1] || '').trim().toLowerCase();
+  if (!sub) {
+    console.log(`Usage: camo record <start|stop|status> [options]
+  camo record start [profileId] [--name <name>] [--output <file>] [--overlay|--no-overlay]
+  camo record stop [profileId] [--reason <text>]
+  camo record status [profileId]
+`);
+    return;
+  }
+  switch (sub) {
+    case 'start':
+      await handleRecordStart(args);
+      return;
+    case 'stop':
+      await handleRecordStop(args);
+      return;
+    case 'status':
+      await handleRecordStatus(args);
+      return;
+    default:
+      console.log(`Usage: camo record <start|stop|status> [options]
+  camo record start [profileId] [--name <name>] [--output <file>] [--overlay|--no-overlay]
+  camo record stop [profileId] [--reason <text>]
+  camo record status [profileId]
+`);
+  }
+}

package/src/container/runtime-core/operations/selector-scripts.mjs

@@ -2,12 +2,54 @@ function asBoolLiteral(value) {
   return value ? 'true' : 'false';
 }
 
+function buildVisibleElementResolverLiteral(selector) {
+  return `
+    const selector = ${JSON.stringify(selector)};
+    const candidates = Array.from(document.querySelectorAll(selector));
+    const isVisible = (node) => {
+      if (!(node instanceof Element)) return false;
+      const rect = node.getBoundingClientRect?.();
+      if (!rect || rect.width <= 0 || rect.height <= 0) return false;
+      try {
+        const style = window.getComputedStyle(node);
+        if (!style) return false;
+        if (style.display === 'none') return false;
+        if (style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+        const opacity = Number.parseFloat(String(style.opacity || '1'));
+        if (Number.isFinite(opacity) && opacity <= 0.01) return false;
+      } catch {
+        return false;
+      }
+      return true;
+    };
+    const hitVisible = (node) => {
+      if (!(node instanceof Element)) return false;
+      const rect = node.getBoundingClientRect?.();
+      if (!rect) return false;
+      const x = Math.max(0, Math.min((window.innerWidth || 1) - 1, rect.left + rect.width / 2));
+      const y = Math.max(0, Math.min((window.innerHeight || 1) - 1, rect.top + rect.height / 2));
+      const top = document.elementFromPoint(x, y);
+      if (!top) return false;
+      return top === node || node.contains(top) || top.contains(node);
+    };
+    const pick = () => {
+      if (!candidates.length) return null;
+      const strict = candidates.find((node) => isVisible(node) && hitVisible(node));
+      if (strict) return strict;
+      const visible = candidates.find((node) => isVisible(node));
+      if (visible) return visible;
+      return candidates[0] || null;
+    };
+    const el = pick();
+    if (!el) throw new Error('Element not found: ' + selector);
+    const matchedIndex = Math.max(0, candidates.indexOf(el));
+  `;
+}
+
 export function buildSelectorScrollIntoViewScript({ selector, highlight }) {
-  const selectorLiteral = JSON.stringify(selector);
   const highlightLiteral = asBoolLiteral(highlight);
   return `(async () => {
-    const el = document.querySelector(${selectorLiteral});
-    if (!el) throw new Error('Element not found: ' + ${selectorLiteral});
+    ${buildVisibleElementResolverLiteral(selector)}
     const restoreOutline = el instanceof HTMLElement ? el.style.outline : '';
     if (${highlightLiteral} && el instanceof HTMLElement) {
       el.style.outline = '2px solid #ff4d4f';
@@ -17,119 +59,190 @@ export function buildSelectorScrollIntoViewScript({ selector, highlight }) {
     if (${highlightLiteral} && el instanceof HTMLElement) {
       el.style.outline = restoreOutline;
     }
-    return { ok: true, selector: ${selectorLiteral} };
+    return {
+      ok: true,
+      selector,
+      matchedIndex,
+      action: 'scrollIntoView',
+      highlight: ${highlightLiteral},
+      target: { tag: String(el.tagName || '').toLowerCase(), id: el.id || null }
+    };
   })()`;
 }
 
 export function buildSelectorClickScript({ selector, highlight }) {
-  const selectorLiteral = JSON.stringify(selector);
   const highlightLiteral = asBoolLiteral(highlight);
   return `(async () => {
-    const el = document.querySelector(${selectorLiteral});
-    if (!el) throw new Error('Element not found: ' + ${selectorLiteral});
+    ${buildVisibleElementResolverLiteral(selector)}
     const restoreOutline = el instanceof HTMLElement ? el.style.outline : '';
     if (${highlightLiteral} && el instanceof HTMLElement) {
       el.style.outline = '2px solid #ff4d4f';
     }
     el.scrollIntoView({ behavior: 'smooth', block: 'center' });
     await new Promise((r) => setTimeout(r, 150));
-    if (el instanceof HTMLElement) {
-      try { el.focus({ preventScroll: true }); } catch {}
-      const common = { bubbles: true, cancelable: true, view: window };
-      try {
-        if (typeof PointerEvent === 'function') {
-          el.dispatchEvent(new PointerEvent('pointerdown', { ...common, pointerType: 'mouse', button: 0 }));
-          el.dispatchEvent(new PointerEvent('pointerup', { ...common, pointerType: 'mouse', button: 0 }));
-        }
-      } catch {}
-      try { el.dispatchEvent(new MouseEvent('mousedown', { ...common, button: 0 })); } catch {}
-      try { el.dispatchEvent(new MouseEvent('mouseup', { ...common, button: 0 })); } catch {}
-    }
-    if (typeof el.click === 'function') el.click();
-    else el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: window, button: 0 }));
+    if (el instanceof HTMLElement && typeof el.click === 'function') {
+      el.click();
+    } else {
+      throw new Error('Target element is not clickable');
+    }
     if (${highlightLiteral} && el instanceof HTMLElement) {
       setTimeout(() => { el.style.outline = restoreOutline; }, 260);
     }
-    return { ok: true, selector: ${selectorLiteral}, action: 'click', highlight: ${highlightLiteral} };
+    return {
+      ok: true,
+      selector,
+      matchedIndex,
+      action: 'click',
+      highlight: ${highlightLiteral},
+      target: { tag: String(el.tagName || '').toLowerCase(), id: el.id || null }
+    };
   })()`;
 }
 
 export function buildSelectorTypeScript({ selector, highlight, text }) {
-  const selectorLiteral = JSON.stringify(selector);
   const highlightLiteral = asBoolLiteral(highlight);
   const textLiteral = JSON.stringify(String(text || ''));
   const textLength = String(text || '').length;
 
   return `(async () => {
-    const el = document.querySelector(${selectorLiteral});
-    if (!el) throw new Error('Element not found: ' + ${selectorLiteral});
+    ${buildVisibleElementResolverLiteral(selector)}
+    const isTypeable = (node) => {
+      if (!node) return false;
+      if (node instanceof HTMLInputElement) return !node.disabled && !node.readOnly;
+      if (node instanceof HTMLTextAreaElement) return !node.disabled && !node.readOnly;
+      return node instanceof HTMLElement && node.isContentEditable;
+    };
+    if (!isTypeable(el)) {
+      throw new Error('Target element is not typeable: ' + selector);
+    }
     const restoreOutline = el instanceof HTMLElement ? el.style.outline : '';
     if (${highlightLiteral} && el instanceof HTMLElement) {
       el.style.outline = '2px solid #ff4d4f';
     }
     el.scrollIntoView({ behavior: 'smooth', block: 'center' });
     await new Promise((r) => setTimeout(r, 150));
-    if (el instanceof HTMLElement) {
-      try { el.focus({ preventScroll: true }); } catch {}
-      if (typeof el.click === 'function') el.click();
+    if (el instanceof HTMLElement && typeof el.focus === 'function') {
+      el.focus();
     }
-    const value = ${textLiteral};
-    const fireInputEvent = (target, name, init) => {
-      try {
-        if (typeof InputEvent === 'function') {
-          target.dispatchEvent(new InputEvent(name, init));
-          return;
-        }
-      } catch {}
-      target.dispatchEvent(new Event(name, { bubbles: true, cancelable: init?.cancelable === true }));
+
+    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+      el.value = ${textLiteral};
+    } else if (el instanceof HTMLElement && el.isContentEditable) {
+      el.textContent = ${textLiteral};
+    }
+
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    if (${highlightLiteral} && el instanceof HTMLElement) {
+      setTimeout(() => { el.style.outline = restoreOutline; }, 260);
+    }
+    return {
+      ok: true,
+      selector,
+      matchedIndex,
+      action: 'type',
+      length: ${textLength},
+      highlight: ${highlightLiteral},
+      target: { tag: String(el.tagName || '').toLowerCase(), id: el.id || null }
     };
-    const assignControlValue = (target, next) => {
-      if (target instanceof HTMLInputElement) {
-        const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
-        if (setter) setter.call(target, next);
-        else target.value = next;
-        if (typeof target.setSelectionRange === 'function') {
-          const cursor = String(next).length;
-          try { target.setSelectionRange(cursor, cursor); } catch {}
-        }
-        return true;
-      }
-      if (target instanceof HTMLTextAreaElement) {
-        const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
-        if (setter) setter.call(target, next);
-        else target.value = next;
-        if (typeof target.setSelectionRange === 'function') {
-          const cursor = String(next).length;
-          try { target.setSelectionRange(cursor, cursor); } catch {}
-        }
-        return true;
+  })()`;
+}
+
+export function buildScrollTargetScript({ selector, highlight }) {
+  const selectorLiteral = JSON.stringify(String(selector || '').trim() || null);
+  const highlightLiteral = asBoolLiteral(highlight);
+  return `(() => {
+    const selector = ${selectorLiteral};
+    const isVisible = (node) => {
+      if (!(node instanceof Element)) return false;
+      const rect = node.getBoundingClientRect?.();
+      if (!rect || rect.width <= 0 || rect.height <= 0) return false;
+      try {
+        const style = window.getComputedStyle(node);
+        if (!style) return false;
+        if (style.display === 'none') return false;
+        if (style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+      } catch {
+        return false;
       }
-      return false;
+      return true;
+    };
+    const isScrollable = (node) => {
+      if (!(node instanceof Element)) return false;
+      const style = window.getComputedStyle(node);
+      const overflowY = String(style.overflowY || '');
+      const overflowX = String(style.overflowX || '');
+      const yScrollable = (overflowY.includes('auto') || overflowY.includes('scroll') || overflowY.includes('overlay'))
+        && (node.scrollHeight - node.clientHeight > 2);
+      const xScrollable = (overflowX.includes('auto') || overflowX.includes('scroll') || overflowX.includes('overlay'))
+        && (node.scrollWidth - node.clientWidth > 2);
+      return yScrollable || xScrollable;
     };
-    const editableAssigned = assignControlValue(el, value);
-    if (!editableAssigned) {
-      if (el instanceof HTMLElement && el.isContentEditable) {
-        el.textContent = value;
-      } else {
-        throw new Error('Element not editable: ' + ${selectorLiteral});
+    const findScrollableAncestor = (node) => {
+      let cursor = node instanceof Element ? node : null;
+      while (cursor) {
+        if (isVisible(cursor) && isScrollable(cursor)) return cursor;
+        cursor = cursor.parentElement;
       }
+      return null;
+    };
+
+    let target = null;
+    let source = 'document';
+    if (selector) {
+      const list = Array.from(document.querySelectorAll(selector));
+      target = list.find((node) => isVisible(node) && isScrollable(node))
+        || list.find((node) => isVisible(node))
+        || null;
+      if (target) source = 'selector';
     }
-    fireInputEvent(el, 'beforeinput', {
-      bubbles: true,
-      cancelable: true,
-      data: value,
-      inputType: 'insertText',
-    });
-    fireInputEvent(el, 'input', {
-      bubbles: true,
-      cancelable: false,
-      data: value,
-      inputType: 'insertText',
-    });
-    el.dispatchEvent(new Event('change', { bubbles: true }));
-    if (${highlightLiteral} && el instanceof HTMLElement) {
-      setTimeout(() => { el.style.outline = restoreOutline; }, 260);
+    if (!target) {
+      const active = document.activeElement instanceof Element ? document.activeElement : null;
+      target = findScrollableAncestor(active);
+      if (target) source = 'active';
     }
-    return { ok: true, selector: ${selectorLiteral}, action: 'type', length: ${textLength}, highlight: ${highlightLiteral} };
+    if (!target) {
+      const cx = Math.max(1, Math.floor((window.innerWidth || 1) / 2));
+      const cy = Math.max(1, Math.floor((window.innerHeight || 1) / 2));
+      const point = document.elementFromPoint(cx, cy);
+      target = findScrollableAncestor(point);
+      if (target) source = 'center';
+    }
+    if (!target) {
+      target = document.scrollingElement || document.documentElement || document.body;
+      source = 'document';
+    }
+    if (!target) {
+      throw new Error('No scroll target available');
+    }
+
+    const rect = target.getBoundingClientRect?.() || {
+      left: 0,
+      top: 0,
+      width: window.innerWidth || 1,
+      height: window.innerHeight || 1,
+    };
+    const centerX = Math.max(1, Math.min((window.innerWidth || 1) - 1, Math.round(rect.left + Math.max(1, rect.width / 2))));
+    const centerY = Math.max(1, Math.min((window.innerHeight || 1) - 1, Math.round(rect.top + Math.max(1, rect.height / 2))));
+
+    const restoreOutline = target instanceof HTMLElement ? target.style.outline : '';
+    if (${highlightLiteral} && target instanceof HTMLElement) {
+      target.style.outline = '2px solid #ff4d4f';
+      setTimeout(() => {
+        target.style.outline = restoreOutline;
+      }, 320);
+    }
+
+    return {
+      ok: true,
+      selector,
+      source,
+      highlight: ${highlightLiteral},
+      center: { x: centerX, y: centerY },
+      target: {
+        tag: String(target.tagName || '').toLowerCase(),
+        id: target.id || null
+      }
+    };
   })()`;
 }

package/src/utils/config.mjs

@@ -32,6 +32,7 @@ export function loadConfig() {
   return {
     defaultProfile: typeof raw.defaultProfile === 'string' ? raw.defaultProfile : null,
     repoRoot: typeof raw.repoRoot === 'string' ? raw.repoRoot : null,
+    highlightMode: typeof raw.highlightMode === 'boolean' ? raw.highlightMode : true,
   };
 }
 
@@ -83,6 +84,17 @@ export function getDefaultProfile() {
   return loadConfig().defaultProfile;
 }
 
+export function getHighlightMode() {
+  return loadConfig().highlightMode !== false;
+}
+
+export function setHighlightMode(enabled) {
+  const cfg = loadConfig();
+  cfg.highlightMode = enabled !== false;
+  saveConfig(cfg);
+  return cfg.highlightMode;
+}
+
 export function getProfileDir(profileId) {
   return path.join(PROFILES_DIR, String(profileId || '').trim());
 }

package/src/utils/help.mjs

@@ -21,10 +21,11 @@ INITIALIZATION:
 
 CONFIG:
   config repo-root [path]                   Get or set persisted webauto repo root
+  highlight-mode [status|on|off]            Global highlight mode for click/type/scroll (default: on)
 
 BROWSER CONTROL:
   init                                      Ensure camoufox + ensure browser-service daemon
-  start [profileId] [--url <url>] [--headless] [--devtools] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]
+  start [profileId] [--url <url>] [--headless] [--devtools] [--record] [--record-name <name>] [--record-output <path>] [--record-overlay|--no-record-overlay] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]
   stop [profileId]
   stop --id <instanceId>                    Stop by instance id
   stop --alias <alias>                      Stop by alias
@@ -50,9 +51,9 @@ NAVIGATION:
   screenshot [profileId] [--output <file>] [--full]
 
 INTERACTION:
-  scroll [profileId] [--down|--up|--left|--right] [--amount <px>]
-  click [profileId] <selector>              Click element by CSS selector
-  type [profileId] <selector> <text>        Type text into element
+  scroll [profileId] [--down|--up|--left|--right] [--amount <px>] [--selector <css>] [--highlight|--no-highlight]
+  click [profileId] <selector> [--highlight|--no-highlight]  Click visible element by CSS selector
+  type [profileId] <selector> <text> [--highlight|--no-highlight]  Type into visible input element
   highlight [profileId] <selector>          Highlight element (red border, 2s)
   clear-highlight [profileId]               Clear all highlights
   viewport [profileId] --width <w> --height <h>
@@ -68,6 +69,11 @@ DEVTOOLS:
   devtools eval [profileId] <expression> [--profile <id>]
   devtools clear [profileId]
 
+RECORDING:
+  record start [profileId] [--name <name>] [--output <file>] [--overlay|--no-overlay]
+  record stop [profileId] [--reason <text>]
+  record status [profileId]
+
 COOKIES:
   cookies get [profileId]                          Get all cookies for profile
   cookies save [profileId] --path <file>           Save cookies to file
@@ -103,17 +109,22 @@ EXAMPLES:
   camo start --url https://example.com --alias main
   camo start worker-1 --headless --alias shard1 --idle-timeout 45m
   camo start worker-1 --devtools
+  camo start worker-1 --record --record-name xhs-debug --record-output ./logs/xhs-debug.jsonl --record-overlay
   camo start myprofile --width 1920 --height 1020
+  camo highlight-mode on
   camo devtools eval myprofile "document.title"
   camo devtools logs myprofile --levels error,warn --limit 50
+  camo record start myprofile --name session-a --output ./logs/session-a.jsonl
+  camo record status myprofile
+  camo record stop myprofile
   camo stop --id inst_xxxxxxxx
   camo stop --alias shard1
   camo stop idle
   camo close all
   camo goto https://www.xiaohongshu.com
-  camo scroll --down --amount 500
-  camo click "#search-input"
-  camo type "#search-input" "hello world"
+  camo scroll --down --amount 500 --selector ".feed-list"
+  camo click "#search-input" --highlight
+  camo type "#search-input" "hello world" --highlight
   camo highlight ".post-card"
   camo viewport --width 1920 --height 1080
   camo cookies get