@web-auto/camo 0.1.21 → 0.1.22

package/README.md

@@ -186,6 +186,8 @@ 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.
+Set `CAMO_BRING_TO_FRONT_MODE=never` to keep protocol-level input and page lifecycle operations from forcing the browser window to front during headed runs.
+`CAMO_SKIP_BRING_TO_FRONT=1` remains supported as a legacy alias.
 
 ### Lifecycle & Cleanup
 

package/package.json

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

package/scripts/bump-version.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * Version bumper for camo CLI
- * Increments patch version maintaining 4-digit format (0.1.0001 -> 0.1.0002)
+ * Version bumper for camo CLI.
+ * Increments standard semver patch version (0.1.21 -> 0.1.22).
  */
 
 import { readFileSync, writeFileSync } from 'fs';
@@ -15,18 +15,14 @@ const packageJsonPath = join(__dirname, '..', 'package.json');
 function bumpVersion() {
   const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
   const currentVersion = pkg.version;
-  
-  // Parse version: 0.1.0001 -> [0, 1, 1]
   const parts = currentVersion.split('.');
   const major = parseInt(parts[0], 10);
   const minor = parseInt(parts[1], 10);
   let patch = parseInt(parts[2], 10);
-  
-  // Increment patch
+
   patch += 1;
-  
-  // Format with 4 digits
-  const newVersion = `${major}.${minor}.${patch.toString().padStart(4, '0')}`;
+
+  const newVersion = `${major}.${minor}.${patch}`;
   
   pkg.version = newVersion;
   writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n');

package/src/commands/browser.mjs

@@ -974,14 +974,32 @@ export async function handleScrollCommand(args) {
 
   const target = await callAPI('evaluate', {
     profileId,
-    script: buildScrollTargetScript({ selector, highlight }),
+    script: buildScrollTargetScript({ selector, highlight, requireVisibleContainer: Boolean(selector) }),
   }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
+  const scrollTarget = target?.result || null;
+  if (!scrollTarget?.ok || !scrollTarget?.center) {
+    throw new Error(scrollTarget?.error || 'visible scroll container not found');
+  }
   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 }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
+  await callAPI('mouse:click', {
+    profileId,
+    x: scrollTarget.center.x,
+    y: scrollTarget.center.y,
+    button: 'left',
+    clicks: 1,
+    delay: 30,
+  }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
+  const result = await callAPI('mouse:wheel', {
+    profileId,
+    deltaX,
+    deltaY,
+    anchorX: scrollTarget.center.x,
+    anchorY: scrollTarget.center.y,
+  }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
   console.log(JSON.stringify({
     ...result,
-    scrollTarget: target?.result || null,
+    scrollTarget,
     highlight,
   }, null, 2));
 }

package/src/container/runtime-core/operations/index.mjs

@@ -626,7 +626,24 @@ export async function executeOperation({ profileId, operation, context = {} }) {
         selector: anchorSelector,
         filterMode,
       });
-      const result = await callAPI('mouse:wheel', { profileId: resolvedProfile, deltaX, deltaY });
+      if (!anchor?.ok || !anchor?.center) {
+        return asErrorPayload('OPERATION_FAILED', 'visible scroll container not found');
+      }
+      await callAPI('mouse:click', {
+        profileId: resolvedProfile,
+        x: anchor.center.x,
+        y: anchor.center.y,
+        button: 'left',
+        clicks: 1,
+        delay: 30,
+      });
+      const result = await callAPI('mouse:wheel', {
+        profileId: resolvedProfile,
+        deltaX,
+        deltaY,
+        anchorX: anchor.center.x,
+        anchorY: anchor.center.y,
+      });
       return {
         ok: true,
         code: 'OPERATION_DONE',
@@ -638,6 +655,7 @@ export async function executeOperation({ profileId, operation, context = {} }) {
           deltaY,
           filterMode,
           anchorSource: String(anchor?.source || 'document'),
+          anchorCenter: anchor?.center || null,
           modalLocked: anchor?.modalLocked === true,
           result,
         },

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

@@ -159,11 +159,13 @@ export function buildSelectorTypeScript({ selector, highlight, text }) {
   })()`;
 }
 
-export function buildScrollTargetScript({ selector, highlight }) {
+export function buildScrollTargetScript({ selector, highlight, requireVisibleContainer = false }) {
   const selectorLiteral = JSON.stringify(String(selector || '').trim() || null);
   const highlightLiteral = asBoolLiteral(highlight);
+  const requireVisibleContainerLiteral = asBoolLiteral(requireVisibleContainer);
   return `(() => {
     const selector = ${selectorLiteral};
+    const requireVisibleContainer = ${requireVisibleContainerLiteral};
     const isVisible = (node) => {
       if (!(node instanceof Element)) return false;
       const rect = node.getBoundingClientRect?.();
@@ -183,11 +185,13 @@ export function buildScrollTargetScript({ selector, highlight }) {
       const style = window.getComputedStyle(node);
       const overflowY = String(style.overflowY || '');
       const overflowX = String(style.overflowX || '');
+      const scrollableSelectors = ['.comments-container', '.comment-list', '.comments-el', '.note-scroller'];
+      const selectorScrollable = scrollableSelectors.some((sel) => typeof node.matches === 'function' && node.matches(sel));
       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;
+      return yScrollable || xScrollable || selectorScrollable;
     };
     const findScrollableAncestor = (node) => {
       let cursor = node instanceof Element ? node : null;
@@ -203,9 +207,12 @@ export function buildScrollTargetScript({ selector, highlight }) {
     if (selector) {
       const list = Array.from(document.querySelectorAll(selector));
       target = list.find((node) => isVisible(node) && isScrollable(node))
-        || list.find((node) => isVisible(node))
+        || list.map((node) => findScrollableAncestor(node)).find((node) => isVisible(node))
         || null;
       if (target) source = 'selector';
+      if (!target && requireVisibleContainer) {
+        return { ok: false, error: 'visible_scroll_container_not_found', selector };
+      }
     }
     if (!target) {
       const active = document.activeElement instanceof Element ? document.activeElement : null;
@@ -250,9 +257,20 @@ export function buildScrollTargetScript({ selector, highlight }) {
       source,
       highlight: ${highlightLiteral},
       center: { x: centerX, y: centerY },
+      rect: {
+        left: Number(rect.left || 0),
+        top: Number(rect.top || 0),
+        width: Number(rect.width || 0),
+        height: Number(rect.height || 0)
+      },
       target: {
         tag: String(target.tagName || '').toLowerCase(),
-        id: target.id || null
+        id: target.id || null,
+        className: typeof target.className === 'string' ? target.className : null,
+        scrollHeight: Number(target.scrollHeight || 0),
+        clientHeight: Number(target.clientHeight || 0),
+        scrollWidth: Number(target.scrollWidth || 0),
+        clientWidth: Number(target.clientWidth || 0)
       }
     };
   })()`;

package/src/container/runtime-core/search.mjs

@@ -0,0 +1,190 @@
+import { buildSelectorCheck } from './utils.mjs';
+
+function normalizeQuery(raw) {
+  const text = String(raw || '').trim();
+  if (!text) return { query: '', queryLower: '' };
+  return { query: text, queryLower: text.toLowerCase() };
+}
+
+function normalizeDirection(raw) {
+  const text = String(raw || 'down').trim().toLowerCase();
+  if (text === 'up' || text === 'down' || text === 'both') return text;
+  return 'down';
+}
+
+function normalizeLimit(raw) {
+  const num = Number(raw);
+  if (!Number.isFinite(num) || num <= 0) return 1;
+  return Math.max(1, Math.floor(num));
+}
+
+function normalizeRect(node) {
+  const rect = node?.rect && typeof node.rect === 'object' ? node.rect : null;
+  if (!rect) return null;
+  const left = Number(rect.left ?? rect.x ?? 0);
+  const top = Number(rect.top ?? rect.y ?? 0);
+  const width = Number(rect.width ?? 0);
+  const height = Number(rect.height ?? 0);
+  if (!Number.isFinite(left) || !Number.isFinite(top) || !Number.isFinite(width) || !Number.isFinite(height)) return null;
+  if (width <= 0 || height <= 0) return null;
+  return { left, top, width, height, right: left + width, bottom: top + height };
+}
+
+function computeCenter(rect) {
+  if (!rect) return null;
+  return {
+    x: Math.round(rect.left + rect.width / 2),
+    y: Math.round(rect.top + rect.height / 2),
+  };
+}
+
+function buildSearchText(node) {
+  if (!node || typeof node !== 'object') return '';
+  const parts = [];
+  const snippet = typeof node.textSnippet === 'string' ? node.textSnippet : '';
+  if (snippet) parts.push(snippet);
+  const attrs = node.attrs && typeof node.attrs === 'object' ? node.attrs : null;
+  if (attrs) {
+    const candidates = [
+      attrs['aria-label'],
+      attrs['aria-label'.toLowerCase()],
+      attrs.title,
+      attrs.alt,
+      attrs.placeholder,
+    ];
+    for (const item of candidates) {
+      const text = typeof item === 'string' ? item.trim() : '';
+      if (text) parts.push(text);
+    }
+  }
+  return parts.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+function isPathWithin(path, parentPath) {
+  const child = String(path || '').trim();
+  const parent = String(parentPath || '').trim();
+  if (!child || !parent) return false;
+  return child === parent || child.startsWith(`${parent}/`);
+}
+
+function collectMatches(node, options, path = 'root', out = []) {
+  if (!node) return out;
+  const { queryLower, visibleOnly } = options;
+  const visible = node.visible === true;
+  if (visibleOnly && !visible) {
+    return out;
+  }
+  {
+    const searchText = buildSearchText(node);
+    if (searchText && searchText.toLowerCase().includes(queryLower)) {
+      out.push({ node, path, searchText });
+    }
+  }
+  if (Array.isArray(node.children)) {
+    for (let i = 0; i < node.children.length; i += 1) {
+      collectMatches(node.children[i], options, `${path}/${i}`, out);
+    }
+  }
+  return out;
+}
+
+function sortMatches(matches, direction) {
+  const sorted = [...matches].sort((a, b) => {
+    const ra = normalizeRect(a.targetNode);
+    const rb = normalizeRect(b.targetNode);
+    const ta = ra ? ra.top : Number.POSITIVE_INFINITY;
+    const tb = rb ? rb.top : Number.POSITIVE_INFINITY;
+    if (ta !== tb) return ta - tb;
+    const la = ra ? ra.left : Number.POSITIVE_INFINITY;
+    const lb = rb ? rb.left : Number.POSITIVE_INFINITY;
+    return la - lb;
+  });
+  if (direction === 'up') return sorted.reverse();
+  return sorted;
+}
+
+function applyStartAfter(matches, startAfterPath) {
+  if (!startAfterPath) return matches;
+  const idx = matches.findIndex((item) => item.targetPath === startAfterPath || item.matchPath === startAfterPath);
+  if (idx < 0) return matches;
+  return matches.slice(idx + 1);
+}
+
+export function searchSnapshot(snapshot, rawOptions = {}) {
+  const { query, queryLower } = normalizeQuery(rawOptions.query || rawOptions.keyword || rawOptions.text);
+  if (!query) {
+    return { ok: false, code: 'QUERY_REQUIRED', message: 'search requires query keyword', data: { query } };
+  }
+  const direction = normalizeDirection(rawOptions.direction || 'down');
+  const limit = normalizeLimit(rawOptions.limit ?? rawOptions.maxResults ?? 1);
+  const visibleOnly = rawOptions.visibleOnly !== false;
+  const containerSelector = String(rawOptions.containerSelector || rawOptions.selector || '').trim() || null;
+  const startAfterPath = String(rawOptions.startAfterPath || rawOptions.afterPath || '').trim() || null;
+
+  const containerNodes = containerSelector
+    ? buildSelectorCheck(snapshot, { css: containerSelector, visible: visibleOnly })
+    : [];
+  const containerPaths = containerNodes.map((node) => node.path).filter(Boolean);
+
+  const matches = collectMatches(snapshot, { queryLower, visibleOnly }, 'root', []);
+  const enriched = matches.map((match) => {
+    let containerNode = null;
+    let containerPath = null;
+    if (containerPaths.length > 0) {
+      for (const path of containerPaths) {
+        if (isPathWithin(match.path, path)) {
+          containerPath = path;
+          break;
+        }
+      }
+      if (containerPath) {
+        containerNode = containerNodes.find((node) => node.path === containerPath) || null;
+      }
+    }
+    const targetNode = containerNode || match.node;
+    const rect = normalizeRect(targetNode);
+    const center = computeCenter(rect);
+    return {
+      matchPath: match.path,
+      targetPath: containerPath || match.path,
+      targetNode,
+      matchNode: match.node,
+      containerPath,
+      rect,
+      center,
+      searchText: match.searchText,
+    };
+  });
+
+  const filtered = containerSelector
+    ? enriched.filter((item) => item.containerPath)
+    : enriched;
+  const ordered = sortMatches(filtered, direction);
+  const sliced = applyStartAfter(ordered, startAfterPath).slice(0, limit);
+  const results = sliced.map((item) => ({
+    matchPath: item.matchPath,
+    targetPath: item.targetPath,
+    containerPath: item.containerPath,
+    rect: item.rect,
+    center: item.center,
+    text: item.searchText,
+  }));
+  const nextCursor = results.length > 0 ? results[results.length - 1].targetPath : startAfterPath;
+
+  return {
+    ok: true,
+    code: 'SEARCH_OK',
+    message: 'search done',
+    data: {
+      query,
+      direction,
+      limit,
+      visibleOnly,
+      containerSelector,
+      totalMatches: filtered.length,
+      returned: results.length,
+      nextCursor,
+      results,
+    },
+  };
+}

package/src/services/browser-service/index.js

@@ -582,8 +582,14 @@ async function handleCommand(payload, manager, wsServer, options = {}) {
             const session = manager.getSession(profileId);
             if (!session)
                 throw new Error(`session for profile ${profileId} not started`);
-            const { deltaY, deltaX } = args;
-            await session.mouseWheel({ deltaY: Number(deltaY) || 0, deltaX: Number(deltaX) || 0 });
+            const { deltaY, deltaX, anchorX, anchorY } = args;
+            await session.mouseWheel({
+                deltaY: Number(deltaY) || 0,
+                deltaX: Number(deltaX) || 0,
+                ...(Number.isFinite(Number(anchorX)) && Number.isFinite(Number(anchorY))
+                    ? { anchorX: Number(anchorX), anchorY: Number(anchorY) }
+                    : {}),
+            });
             return { ok: true, body: { ok: true } };
         }
         case 'keyboard:type': {

package/src/services/browser-service/internal/BrowserSession.input.test.js

@@ -196,10 +196,38 @@ test('ensureInputReady brings page to front even when document reports focus', a
         isClosed: () => false,
     };
     const session = new BrowserSession({ profileId: `test-input-ready-${Date.now()}` });
-    await session.ensureInputReady(page);
+    await session.inputPipeline.ensureInputReady(page);
     assert.equal(page.bringToFrontCount, 1);
     assert.equal(page.waitCount, 1);
 });
+test('ensureInputReady skips bringToFront when CAMO_BRING_TO_FRONT_MODE=never', async () => {
+    const restoreSkip = setEnv('CAMO_BRING_TO_FRONT_MODE', 'never');
+    try {
+        const page = {
+            bringToFrontCount: 0,
+            waitCount: 0,
+            bringToFront: async function bringToFront() {
+                this.bringToFrontCount += 1;
+            },
+            waitForTimeout: async function waitForTimeout() {
+                this.waitCount += 1;
+            },
+            evaluate: async () => ({
+                hasFocus: false,
+                hidden: false,
+                visibilityState: 'visible',
+            }),
+            isClosed: () => false,
+        };
+        const session = new BrowserSession({ profileId: `test-input-ready-skip-${Date.now()}` });
+        await session.inputPipeline.ensureInputReady(page);
+        assert.equal(page.bringToFrontCount, 0);
+        assert.equal(page.waitCount, 1);
+    }
+    finally {
+        restoreSkip();
+    }
+});
 test('mouseWheel retries with refreshed active page after timeout', async () => {
     const restoreTimeout = setEnv('CAMO_INPUT_ACTION_TIMEOUT_MS', '80');
     const restoreAttempts = setEnv('CAMO_INPUT_ACTION_MAX_ATTEMPTS', '2');
@@ -210,17 +238,21 @@ test('mouseWheel retries with refreshed active page after timeout', async () =>
         const calls = [];
         const page1 = {
             isClosed: () => false,
+            viewportSize: () => ({ width: 1280, height: 720 }),
             bringToFront: async () => { },
             waitForTimeout: async () => { },
             mouse: {
+                move: async () => { },
                 wheel: async () => new Promise(() => { }),
             },
         };
         const page2 = {
             isClosed: () => false,
+            viewportSize: () => ({ width: 1280, height: 720 }),
             bringToFront: async () => { },
             waitForTimeout: async () => { },
             mouse: {
+                move: async () => { },
                 wheel: async () => {
                     calls.push('wheel_ok');
                 },
@@ -255,9 +287,11 @@ test('mouseWheel falls back to keyboard paging when wheel keeps timing out', asy
         const calls = [];
         const page = {
             isClosed: () => false,
+            viewportSize: () => ({ width: 1280, height: 720 }),
             bringToFront: async () => { },
             waitForTimeout: async () => { },
             mouse: {
+                move: async () => { },
                 wheel: async () => new Promise(() => { }),
             },
             keyboard: {
@@ -319,4 +353,4 @@ test('mouseWheel uses keyboard mode directly when CAMO_SCROLL_INPUT_MODE=keyboar
         restoreMode();
     }
 });
-//# sourceMappingURL=BrowserSession.input.test.js.map
+//# sourceMappingURL=BrowserSession.input.test.js.map

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

@@ -66,9 +66,11 @@ export class BrowserSessionInputOps {
         const page = await this.ensurePrimaryPage();
         await this.withInputActionLock(async () => {
             await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
-            const { deltaX = 0, deltaY } = opts;
+            const { deltaX = 0, deltaY, anchorX, anchorY } = opts;
             const normalizedDeltaX = Number(deltaX) || 0;
             const normalizedDeltaY = Number(deltaY) || 0;
+            const normalizedAnchorX = Number(anchorX);
+            const normalizedAnchorY = Number(anchorY);
             if (normalizedDeltaY === 0 && normalizedDeltaX === 0)
                 return;
             const keyboardKey = normalizedDeltaY > 0 ? 'PageDown' : 'PageUp';
@@ -88,8 +90,12 @@ export class BrowserSessionInputOps {
             try {
                 await this.runInputAction(page, 'mouse:wheel', async (activePage) => {
                     const viewport = activePage.viewportSize();
-                    const moveX = Math.max(1, Math.floor(((viewport?.width || 1280) * 0.5)));
-                    const moveY = Math.max(1, Math.floor(((viewport?.height || 720) * 0.5)));
+                    const moveX = Number.isFinite(normalizedAnchorX)
+                        ? Math.max(1, Math.min(Math.max(1, Number(viewport?.width || 1280) - 1), Math.round(normalizedAnchorX)))
+                        : Math.max(1, Math.floor(((viewport?.width || 1280) * 0.5)));
+                    const moveY = Number.isFinite(normalizedAnchorY)
+                        ? Math.max(1, Math.min(Math.max(1, Number(viewport?.height || 720) - 1), Math.round(normalizedAnchorY)))
+                        : Math.max(1, Math.floor(((viewport?.height || 720) * 0.5)));
                     await activePage.mouse.move(moveX, moveY, { steps: 1 }).catch(() => { });
                     await activePage.mouse.wheel(normalizedDeltaX, normalizedDeltaY);
                 });
@@ -124,4 +130,4 @@ export class BrowserSessionInputOps {
         });
     }
 }
-//# sourceMappingURL=input-ops.js.map
+//# sourceMappingURL=input-ops.js.map

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

@@ -1,4 +1,4 @@
-import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs } from './utils.js';
+import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs, shouldSkipBringToFront } from './utils.js';
 import { ensurePageRuntime } from '../pageRuntime.js';
 export class BrowserInputPipeline {
     ensurePrimaryPage;
@@ -11,6 +11,13 @@ export class BrowserInputPipeline {
     async ensureInputReady(page) {
         if (this.isHeadless())
             return;
+        if (shouldSkipBringToFront()) {
+            const settleMs = resolveInputReadySettleMs();
+            if (settleMs > 0) {
+                await page.waitForTimeout(settleMs).catch(() => { });
+            }
+            return;
+        }
         const bringToFrontTimeoutMs = resolveInputRecoveryBringToFrontTimeoutMs();
         let bringToFrontTimer = null;
         try {
@@ -67,6 +74,7 @@ export class BrowserInputPipeline {
     }
     async recoverInputPipeline(page) {
         const activePage = await this.resolveInputPage(page).catch(() => page);
+        if (!shouldSkipBringToFront()) {
         const bringToFrontTimeoutMs = resolveInputRecoveryBringToFrontTimeoutMs();
         let bringToFrontTimer = null;
         try {
@@ -86,6 +94,7 @@ export class BrowserInputPipeline {
             if (bringToFrontTimer)
                 clearTimeout(bringToFrontTimer);
         }
+        }
         const delayMs = resolveInputRecoveryDelayMs();
         if (delayMs > 0) {
             try {
@@ -130,4 +139,4 @@ export class BrowserInputPipeline {
         }
     }
 }
-//# sourceMappingURL=input-pipeline.js.map
+//# sourceMappingURL=input-pipeline.js.map

package/src/services/browser-service/internal/browser-session/page-management.js

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { ensurePageRuntime } from '../pageRuntime.js';
-import { resolveNavigationWaitUntil, normalizeUrl } from './utils.js';
+import { resolveNavigationWaitUntil, normalizeUrl, shouldSkipBringToFront } from './utils.js';
 export class BrowserSessionPageManagement {
     deps;
     constructor(deps) {
@@ -74,7 +74,9 @@ export class BrowserSessionPageManagement {
         const opener = this.deps.getActivePage() || ctx.pages()[0];
         if (!opener)
             throw new Error('no_opener_page');
-        await opener.bringToFront().catch(() => null);
+        if (!shouldSkipBringToFront()) {
+            await opener.bringToFront().catch(() => null);
+        }
         const before = ctx.pages().filter((p) => !p.isClosed()).length;
         for (let attempt = 1; attempt <= 3; attempt += 1) {
             const waitPage = ctx.waitForEvent('page', { timeout: 8000 }).catch(() => null);
@@ -136,11 +138,13 @@ export class BrowserSessionPageManagement {
         catch {
             /* ignore */
         }
-        try {
-            await page.bringToFront();
-        }
-        catch {
-            /* ignore */
+        if (!shouldSkipBringToFront()) {
+            try {
+                await page.bringToFront();
+            }
+            catch {
+                /* ignore */
+            }
         }
         if (url) {
             await page.goto(url, { waitUntil: resolveNavigationWaitUntil() });
@@ -165,11 +169,13 @@ export class BrowserSessionPageManagement {
         catch {
             /* ignore */
         }
-        try {
-            await page.bringToFront();
-        }
-        catch {
-            /* ignore */
+        if (!shouldSkipBringToFront()) {
+            try {
+                await page.bringToFront();
+            }
+            catch {
+                /* ignore */
+            }
         }
         await ensurePageRuntime(page, true).catch(() => { });
         this.deps.recordLastKnownUrl(page.url());
@@ -194,11 +200,13 @@ export class BrowserSessionPageManagement {
         if (nextIndex >= 0) {
             const nextPage = remaining[nextIndex];
             this.deps.setActivePage(nextPage);
-            try {
-                await nextPage.bringToFront();
-            }
-            catch {
-                /* ignore */
+            if (!shouldSkipBringToFront()) {
+                try {
+                    await nextPage.bringToFront();
+                }
+                catch {
+                    /* ignore */
+                }
             }
             await ensurePageRuntime(nextPage, true).catch(() => { });
             this.deps.recordLastKnownUrl(nextPage.url());
@@ -209,4 +217,4 @@ export class BrowserSessionPageManagement {
         return { closedIndex, activeIndex: nextIndex, total: remaining.length };
     }
 }
-//# sourceMappingURL=page-management.js.map
+//# sourceMappingURL=page-management.js.map

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

@@ -28,6 +28,20 @@ export function resolveInputReadySettleMs() {
     const raw = Number(process.env.CAMO_INPUT_READY_SETTLE_MS ?? 80);
     return Math.max(0, Number.isFinite(raw) ? Math.floor(raw) : 80);
 }
+export function resolveBringToFrontMode() {
+    const mode = String(process.env.CAMO_BRING_TO_FRONT_MODE ?? '').trim().toLowerCase();
+    if (mode === 'never' || mode === 'off' || mode === 'disabled')
+        return 'never';
+    if (mode === 'always' || mode === 'on' || mode === 'auto')
+        return 'auto';
+    const legacy = String(process.env.CAMO_SKIP_BRING_TO_FRONT ?? '').trim().toLowerCase();
+    if (legacy === '1' || legacy === 'true' || legacy === 'yes' || legacy === 'on')
+        return 'never';
+    return 'auto';
+}
+export function shouldSkipBringToFront() {
+    return resolveBringToFrontMode() === 'never';
+}
 export function isTimeoutLikeError(error) {
     const message = String(error?.message || error || '').toLowerCase();
     return message.includes('timed out') || message.includes('timeout');
@@ -44,6 +58,12 @@ export function normalizeUrl(raw) {
 export async function ensureInputReadyOnPage(page, headless, bringToFrontTimeoutMs, settleMs) {
     if (headless)
         return;
+    if (shouldSkipBringToFront()) {
+        if (settleMs > 0) {
+            await page.waitForTimeout(settleMs).catch(() => { });
+        }
+        return;
+    }
     let bringToFrontTimer = null;
     try {
         await Promise.race([
@@ -66,4 +86,4 @@ export async function ensureInputReadyOnPage(page, headless, bringToFrontTimeout
         await page.waitForTimeout(settleMs).catch(() => { });
     }
 }
-//# sourceMappingURL=utils.js.map
+//# sourceMappingURL=utils.js.map

package/src/utils/help.mjs

@@ -180,6 +180,8 @@ ENV:
   CAMO_ROOT                                  Legacy data root (auto-appends .camo if needed)
   CAMO_WS_URL                                Optional ws://host:port override
   CAMO_WS_HOST / CAMO_WS_PORT                WS host/port for browser-service
+  CAMO_BRING_TO_FRONT_MODE                   Bring-to-front policy: auto (default) | never
+  CAMO_SKIP_BRING_TO_FRONT                   Legacy alias for CAMO_BRING_TO_FRONT_MODE=never
   CAMO_PROGRESS_EVENTS_FILE                 Optional path override for progress jsonl
   CAMO_PROGRESS_WS_HOST / CAMO_PROGRESS_WS_PORT   Progress daemon host/port (defaults: 127.0.0.1:7788)
 `);