ornold-mcp 1.3.2 → 1.3.3

package/executor/concurrency.ts

@@ -0,0 +1,118 @@
+/**
+ * Concurrency Management
+ * Утилиты для управления параллельным выполнением операций
+ */
+
+import * as os from 'os';
+
+/**
+ * Detect optimal concurrency based on system resources.
+ * Considers: free RAM, total RAM, CPU cores, and number of browsers.
+ */
+export function detectOptimalConcurrency(browserCount: number = 0): {
+  default: number;
+  heavy: number;
+  light: number;
+} {
+  const cpuCores = os.cpus().length;
+  const totalMemGB = os.totalmem() / (1024 ** 3);
+  const freeMemGB = os.freemem() / (1024 ** 3);
+
+  // Each browser operation needs ~200-500MB RAM headroom
+  // For heavy ops (screenshots) need more
+  const memPerHeavyOp = 0.5; // GB
+  const memPerLightOp = 0.2; // GB
+
+  // Calculate limits based on resources
+  // RAM is usually the bottleneck for browsers
+  const ramBasedHeavy = Math.floor(freeMemGB / memPerHeavyOp);
+  const ramBasedLight = Math.floor(freeMemGB / memPerLightOp);
+
+  // CPU-based limits (browsers are mostly I/O bound, so we can go higher)
+  const cpuBasedDefault = Math.max(2, Math.floor(cpuCores / 2));
+  const cpuBasedLight = Math.max(3, cpuCores);
+
+  // Final limits - take minimum of RAM and CPU based limits
+  // No hard limits for powerful servers
+  const heavyConcurrency = Math.max(2, Math.min(ramBasedHeavy, cpuBasedDefault));
+  const lightConcurrency = Math.max(3, Math.min(ramBasedLight, cpuBasedLight));
+  const defaultConcurrency = Math.max(2, Math.floor((heavyConcurrency + lightConcurrency) / 2));
+
+  // If we know browser count, don't exceed it
+  const effectiveHeavy = browserCount > 0 ? Math.min(heavyConcurrency, browserCount) : heavyConcurrency;
+  const effectiveLight = browserCount > 0 ? Math.min(lightConcurrency, browserCount) : lightConcurrency;
+  const effectiveDefault = browserCount > 0 ? Math.min(defaultConcurrency, browserCount) : defaultConcurrency;
+
+  console.error(`[Concurrency] System: ${cpuCores} cores, ${totalMemGB.toFixed(1)}GB total RAM, ${freeMemGB.toFixed(1)}GB free`);
+  console.error(`[Concurrency] Detected limits: default=${effectiveDefault}, heavy=${effectiveHeavy}, light=${effectiveLight}`);
+
+  return {
+    default: effectiveDefault,
+    heavy: effectiveHeavy,
+    light: effectiveLight,
+  };
+}
+
+/**
+ * Simple concurrency limiter to prevent overwhelming the system
+ * when operating on many browsers simultaneously.
+ * Note: In Node.js single-threaded event loop, synchronous operations
+ * before await are atomic, so this is safe.
+ */
+export class ConcurrencyLimiter {
+  private running = 0;
+  private queue: Array<() => void> = [];
+
+  constructor(private maxConcurrent: number) {
+    if (maxConcurrent < 1) {
+      throw new Error('maxConcurrent must be at least 1');
+    }
+  }
+
+  get limit(): number {
+    return this.maxConcurrent;
+  }
+
+  get active(): number {
+    return this.running;
+  }
+
+  get pending(): number {
+    return this.queue.length;
+  }
+
+  async acquire(): Promise<void> {
+    // Synchronous check and increment - safe in single-threaded Node.js
+    if (this.running < this.maxConcurrent) {
+      this.running++;
+      return;
+    }
+
+    return new Promise((resolve) => {
+      this.queue.push(() => {
+        this.running++;
+        resolve();
+      });
+    });
+  }
+
+  release(): void {
+    if (this.running <= 0) {
+      console.error('[ConcurrencyLimiter] Warning: release() called when running <= 0');
+      return;
+    }
+
+    this.running--;
+    const next = this.queue.shift();
+    if (next) next();
+  }
+
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+}

package/executor/human-like.ts

@@ -0,0 +1,523 @@
+/**
+ * Human-like interaction utilities for anti-detection
+ * Provides realistic mouse movement, typing, and visual cursor
+ */
+
+import type { Page, CDPSession } from 'patchright';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ==================== DEBUG LOGGER ====================
+
+const LOG_FILE = path.join(process.cwd(), 'logs', 'human-like-debug.log');
+
+function debugLog(category: string, message: string, data?: any): void {
+  try {
+    const dir = path.dirname(LOG_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const ts = new Date().toISOString();
+    let line = `[${ts}] [${category}] ${message}`;
+    if (data !== undefined) {
+      line += ` | ${JSON.stringify(data)}`;
+    }
+    fs.appendFileSync(LOG_FILE, line + '\n');
+  } catch {
+    // Logging should never break the main flow
+  }
+}
+
+// ==================== RANDOM UTILITIES ====================
+
+/** Gaussian-distributed random number (Box-Muller transform) */
+function gaussianRandom(mean: number, stddev: number): number {
+  const u1 = Math.random();
+  const u2 = Math.random();
+  const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  return mean + z * stddev;
+}
+
+/** Clamped random number */
+function clampedRandom(min: number, max: number): number {
+  return Math.min(max, Math.max(min, min + Math.random() * (max - min)));
+}
+
+/** Clamped gaussian */
+function clampedGaussian(mean: number, stddev: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, gaussianRandom(mean, stddev)));
+}
+
+/** Sleep for ms */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// ==================== PER-BROWSER PROFILE ====================
+
+export interface HumanProfile {
+  /** Base typing delay multiplier (0.8 - 1.2) */
+  typingSpeed: number;
+  /** Mouse speed multiplier (0.85 - 1.15) */
+  mouseSpeed: number;
+  /** Pre-action delay multiplier (0.7 - 1.3) */
+  actionDelay: number;
+}
+
+/** Generate a deterministic-ish but unique profile per browser */
+export function generateProfile(browserId: string): HumanProfile {
+  // Simple hash from browserId to get consistent but varied profiles
+  let hash = 0;
+  for (let i = 0; i < browserId.length; i++) {
+    hash = ((hash << 5) - hash + browserId.charCodeAt(i)) | 0;
+  }
+  const seed = Math.abs(hash);
+
+  return {
+    typingSpeed: 0.8 + ((seed % 100) / 100) * 0.4,       // 0.8 - 1.2
+    mouseSpeed: 0.85 + (((seed >> 8) % 100) / 100) * 0.3, // 0.85 - 1.15
+    actionDelay: 0.7 + (((seed >> 16) % 100) / 100) * 0.6, // 0.7 - 1.3
+  };
+}
+
+// ==================== DELAYS ====================
+
+/** Pre-action delay (100-400ms base, scaled by profile) */
+export async function preActionDelay(profile?: HumanProfile): Promise<void> {
+  const base = clampedGaussian(250, 80, 100, 400);
+  const ms = profile ? base * profile.actionDelay : base;
+  await sleep(ms);
+}
+
+/** Typing delay for a single character (40-180ms, with rare pauses) */
+export function typingDelay(profile?: HumanProfile): number {
+  // 5% chance of a "thinking" pause
+  if (Math.random() < 0.05) {
+    const pause = clampedGaussian(350, 100, 200, 600);
+    return profile ? pause * profile.typingSpeed : pause;
+  }
+  const base = clampedGaussian(80, 30, 40, 180);
+  return profile ? base * profile.typingSpeed : base;
+}
+
+/** Short delay between mouse actions */
+export async function humanDelay(min: number, max: number): Promise<void> {
+  await sleep(clampedRandom(min, max));
+}
+
+// ==================== BEZIER MOUSE MOVEMENT ====================
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+/** Cubic Bezier interpolation */
+function cubicBezier(t: number, p0: number, p1: number, p2: number, p3: number): number {
+  const t2 = t * t;
+  const t3 = t2 * t;
+  const mt = 1 - t;
+  const mt2 = mt * mt;
+  const mt3 = mt2 * mt;
+  return mt3 * p0 + 3 * mt2 * t * p1 + 3 * mt * t2 * p2 + t3 * p3;
+}
+
+/** Generate Bezier path between two points with random control points */
+function generateBezierPath(from: Point, to: Point, steps: number = 20): Point[] {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const distance = Math.sqrt(dx * dx + dy * dy);
+
+  // Control points: offset perpendicular to the line, scaled by distance
+  const spreadX = distance * 0.15;
+  const spreadY = distance * 0.15;
+
+  const cp1: Point = {
+    x: from.x + dx * 0.25 + (Math.random() - 0.5) * spreadX,
+    y: from.y + dy * 0.25 + (Math.random() - 0.5) * spreadY,
+  };
+  const cp2: Point = {
+    x: from.x + dx * 0.75 + (Math.random() - 0.5) * spreadX,
+    y: from.y + dy * 0.75 + (Math.random() - 0.5) * spreadY,
+  };
+
+  // More steps for longer distances
+  const actualSteps = Math.max(10, Math.min(40, Math.round(steps * (distance / 500))));
+
+  const points: Point[] = [];
+  for (let i = 0; i <= actualSteps; i++) {
+    const t = i / actualSteps;
+    // Ease in/out: slow start and end, fast middle
+    const eased = t < 0.5
+      ? 2 * t * t
+      : 1 - Math.pow(-2 * t + 2, 2) / 2;
+
+    points.push({
+      x: Math.round(cubicBezier(eased, from.x, cp1.x, cp2.x, to.x)),
+      y: Math.round(cubicBezier(eased, from.y, cp1.y, cp2.y, to.y)),
+    });
+  }
+
+  return points;
+}
+
+/** Move mouse along a human-like Bezier path */
+export async function humanMouseMove(
+  page: Page,
+  from: Point,
+  to: Point,
+  profile?: HumanProfile
+): Promise<void> {
+  debugLog('MOUSE_MOVE', `from=(${from.x},${from.y}) to=(${to.x},${to.y})`);
+  const path = generateBezierPath(from, to);
+  const speedMult = profile?.mouseSpeed ?? 1;
+  debugLog('MOUSE_MOVE', `bezier path generated: ${path.length} steps, speedMult=${speedMult.toFixed(2)}`);
+
+  // Create CDP session once for all cursor updates
+  let cdpSession: any = null;
+  try {
+    cdpSession = await page.context().newCDPSession(page);
+  } catch (err) {
+    debugLog('MOUSE_MOVE', `CDP session creation failed, cursor won't be visible in screencast`, String(err));
+  }
+
+  for (let i = 0; i < path.length; i++) {
+    const point = path[i];
+    const delay = clampedRandom(5, 15) * speedMult;
+    try {
+      await page.mouse.move(point.x, point.y);
+    } catch (err) {
+      debugLog('MOUSE_MOVE', `ERROR at step ${i}/${path.length}: page.mouse.move(${point.x},${point.y}) failed`, String(err));
+      throw err;
+    }
+
+    // Update cursor position for screencast on every step (smooth movement)
+    if (cdpSession) {
+      try {
+        await cdpSession.send('Runtime.evaluate', {
+          expression: `window.__cpSrv = {x:${Math.round(point.x)},y:${Math.round(point.y)}}`,
+          returnByValue: false, // no need to read back on every step
+        });
+      } catch (err) {
+        // Ignore errors during movement, don't break the flow
+      }
+    }
+
+    await sleep(delay);
+  }
+
+  // Detach CDP session
+  if (cdpSession) {
+    try {
+      await cdpSession.detach();
+    } catch (err) {
+      // Ignore detach errors
+    }
+  }
+
+  debugLog('MOUSE_MOVE', `movement complete at (${to.x},${to.y})`);
+  console.log(`[HumanLike] Mouse moved smoothly to (${to.x},${to.y}), ${path.length} steps`);
+
+  // Show final cursor position via CDP overlay
+  await showCursorOverlay(page, to.x, to.y);
+}
+
+// ==================== CLICK HELPERS ====================
+
+/** Random offset from element center for clicks */
+export function clickOffset(width: number, height: number): Point {
+  // Offset within ~30% of element dimensions, clamped to ±8px
+  const maxOffX = Math.min(8, width * 0.15);
+  const maxOffY = Math.min(5, height * 0.15);
+  return {
+    x: clampedGaussian(0, maxOffX * 0.5, -maxOffX, maxOffX),
+    y: clampedGaussian(0, maxOffY * 0.5, -maxOffY, maxOffY),
+  };
+}
+
+/** Human-like click: mouse move → down → delay → up */
+export async function humanClick(
+  page: Page,
+  target: Point,
+  fromPos: Point,
+  profile?: HumanProfile
+): Promise<void> {
+  debugLog('CLICK', `target=(${target.x},${target.y}) from=(${fromPos.x},${fromPos.y})`);
+  // Move to target
+  await humanMouseMove(page, fromPos, target, profile);
+
+  // Down → delay → up (real humans hold button for 50-120ms)
+  debugLog('CLICK', `mouse.down()`);
+  await page.mouse.down();
+  const holdDelay = clampedRandom(50, 120);
+  debugLog('CLICK', `holding for ${holdDelay.toFixed(0)}ms`);
+  await sleep(holdDelay);
+  debugLog('CLICK', `mouse.up()`);
+  await page.mouse.up();
+  debugLog('CLICK', `click complete`);
+}
+
+/** Get bounding box center + random offset for a locator */
+export async function getClickTarget(
+  page: Page,
+  locator: any // Locator type
+): Promise<{ target: Point; box: { width: number; height: number } }> {
+  debugLog('GET_TARGET', `getting bounding box for locator`);
+  const box = await locator.boundingBox();
+  if (!box) {
+    debugLog('GET_TARGET', `ERROR: no bounding box returned (element not visible)`);
+    throw new Error('Element is not visible — no bounding box');
+  }
+  debugLog('GET_TARGET', `boundingBox: x=${box.x} y=${box.y} w=${box.width} h=${box.height}`);
+
+  const offset = clickOffset(box.width, box.height);
+  const target = {
+    x: Math.round(box.x + box.width / 2 + offset.x),
+    y: Math.round(box.y + box.height / 2 + offset.y),
+  };
+  debugLog('GET_TARGET', `center=(${Math.round(box.x + box.width/2)},${Math.round(box.y + box.height/2)}) offset=(${offset.x.toFixed(1)},${offset.y.toFixed(1)}) final=(${target.x},${target.y})`);
+
+  return {
+    target,
+    box: { width: box.width, height: box.height },
+  };
+}
+
+// ==================== CDP KEYBOARD EVENTS ====================
+
+// Key code mapping for common characters
+const KEY_CODES: Record<string, { keyCode: number; code: string; key: string }> = {};
+
+// Populate a-z
+for (let i = 0; i < 26; i++) {
+  const lower = String.fromCharCode(97 + i);
+  const upper = String.fromCharCode(65 + i);
+  KEY_CODES[lower] = { keyCode: 65 + i, code: `Key${upper}`, key: lower };
+  KEY_CODES[upper] = { keyCode: 65 + i, code: `Key${upper}`, key: upper };
+}
+
+// 0-9
+for (let i = 0; i < 10; i++) {
+  const ch = String(i);
+  KEY_CODES[ch] = { keyCode: 48 + i, code: `Digit${i}`, key: ch };
+}
+
+// Common symbols
+const SYMBOLS: Record<string, { keyCode: number; code: string }> = {
+  ' ':  { keyCode: 32,  code: 'Space' },
+  '.':  { keyCode: 190, code: 'Period' },
+  ',':  { keyCode: 188, code: 'Comma' },
+  '/':  { keyCode: 191, code: 'Slash' },
+  '\\': { keyCode: 220, code: 'Backslash' },
+  '-':  { keyCode: 189, code: 'Minus' },
+  '=':  { keyCode: 187, code: 'Equal' },
+  '[':  { keyCode: 219, code: 'BracketLeft' },
+  ']':  { keyCode: 221, code: 'BracketRight' },
+  ';':  { keyCode: 186, code: 'Semicolon' },
+  "'":  { keyCode: 222, code: 'Quote' },
+  '`':  { keyCode: 192, code: 'Backquote' },
+  '@':  { keyCode: 50,  code: 'Digit2' },
+  '!':  { keyCode: 49,  code: 'Digit1' },
+  '#':  { keyCode: 51,  code: 'Digit3' },
+  '$':  { keyCode: 52,  code: 'Digit4' },
+  '%':  { keyCode: 53,  code: 'Digit5' },
+  '^':  { keyCode: 54,  code: 'Digit6' },
+  '&':  { keyCode: 55,  code: 'Digit7' },
+  '*':  { keyCode: 56,  code: 'Digit8' },
+  '(':  { keyCode: 57,  code: 'Digit9' },
+  ')':  { keyCode: 48,  code: 'Digit0' },
+  '_':  { keyCode: 189, code: 'Minus' },
+  '+':  { keyCode: 187, code: 'Equal' },
+  '{':  { keyCode: 219, code: 'BracketLeft' },
+  '}':  { keyCode: 221, code: 'BracketRight' },
+  ':':  { keyCode: 186, code: 'Semicolon' },
+  '"':  { keyCode: 222, code: 'Quote' },
+  '~':  { keyCode: 192, code: 'Backquote' },
+  '<':  { keyCode: 188, code: 'Comma' },
+  '>':  { keyCode: 190, code: 'Period' },
+  '?':  { keyCode: 191, code: 'Slash' },
+  '|':  { keyCode: 220, code: 'Backslash' },
+  '\n': { keyCode: 13,  code: 'Enter' },
+  '\t': { keyCode: 9,   code: 'Tab' },
+};
+for (const [ch, info] of Object.entries(SYMBOLS)) {
+  KEY_CODES[ch] = { ...info, key: ch };
+}
+
+/** Type a single character via CDP Input.dispatchKeyEvent */
+async function cdpTypeChar(cdp: CDPSession, char: string): Promise<void> {
+  const info = KEY_CODES[char];
+  const code = info?.code ?? '';
+  const keyCode = info?.keyCode ?? char.charCodeAt(0);
+
+  debugLog('TYPE_CHAR', `char="${char}" code=${code} keyCode=${keyCode} (has mapping: ${!!info})`);
+
+  // keyDown — no text field here, text insertion happens via the char event
+  try {
+    await cdp.send('Input.dispatchKeyEvent', {
+      type: 'keyDown',
+      key: char,
+      code,
+      windowsVirtualKeyCode: keyCode,
+      nativeVirtualKeyCode: keyCode,
+    });
+    debugLog('TYPE_CHAR', `keyDown sent OK`);
+  } catch (err) {
+    debugLog('TYPE_CHAR', `keyDown FAILED`, String(err));
+    throw err;
+  }
+
+  // char event — this is what actually inserts the character
+  try {
+    await cdp.send('Input.dispatchKeyEvent', {
+      type: 'char',
+      text: char,
+      unmodifiedText: char,
+    });
+    debugLog('TYPE_CHAR', `char event sent OK`);
+  } catch (err) {
+    debugLog('TYPE_CHAR', `char event FAILED`, String(err));
+    throw err;
+  }
+
+  // Small delay between down and up (real key press duration)
+  const pressDelay = clampedRandom(20, 60);
+  await sleep(pressDelay);
+
+  // keyUp
+  try {
+    await cdp.send('Input.dispatchKeyEvent', {
+      type: 'keyUp',
+      key: char,
+      code,
+      windowsVirtualKeyCode: keyCode,
+      nativeVirtualKeyCode: keyCode,
+    });
+    debugLog('TYPE_CHAR', `keyUp sent OK (pressDelay=${pressDelay.toFixed(0)}ms)`);
+  } catch (err) {
+    debugLog('TYPE_CHAR', `keyUp FAILED`, String(err));
+    throw err;
+  }
+}
+
+/** Type text with human-like delays via CDP events */
+export async function humanTypeText(
+  page: Page,
+  text: string,
+  profile?: HumanProfile
+): Promise<void> {
+  debugLog('TYPE_TEXT', `typing "${text}" (${text.length} chars)`);
+  let cdp: CDPSession;
+  try {
+    cdp = await page.context().newCDPSession(page);
+    debugLog('TYPE_TEXT', `CDP session created for typing`);
+  } catch (err) {
+    debugLog('TYPE_TEXT', `FAILED to create CDP session`, String(err));
+    throw err;
+  }
+  try {
+    for (let i = 0; i < text.length; i++) {
+      const char = text[i];
+      await cdpTypeChar(cdp, char);
+      const delay = typingDelay(profile);
+      debugLog('TYPE_TEXT', `char ${i+1}/${text.length} "${char}" typed, next delay=${delay.toFixed(0)}ms`);
+      await sleep(delay);
+    }
+    debugLog('TYPE_TEXT', `typing complete`);
+  } finally {
+    await cdp.detach().catch(() => {});
+    debugLog('TYPE_TEXT', `CDP session detached`);
+  }
+}
+
+// ==================== VISUAL CURSOR (CDP Overlay — zero DOM footprint) ====================
+
+// Persistent CDP session per page for Overlay (must stay alive for overlay to render)
+const overlaySessions = new WeakMap<Page, CDPSession>();
+
+/** Get or create a persistent CDP session with Overlay enabled */
+async function getOverlaySession(page: Page): Promise<CDPSession> {
+  let cdp = overlaySessions.get(page);
+  if (cdp) {
+    debugLog('OVERLAY', `reusing existing overlay session`);
+    return cdp;
+  }
+
+  debugLog('OVERLAY', `creating new overlay CDP session`);
+  cdp = await page.context().newCDPSession(page);
+
+  try {
+    // DOM must be enabled before Overlay
+    await cdp.send('DOM.enable');
+    debugLog('OVERLAY', `DOM.enable SUCCESS`);
+    await cdp.send('Overlay.enable');
+    debugLog('OVERLAY', `Overlay.enable SUCCESS`);
+  } catch (err) {
+    debugLog('OVERLAY', `Overlay.enable FAILED`, String(err));
+  }
+
+  overlaySessions.set(page, cdp);
+
+  // Clean up reference if session disconnects
+  cdp.on('detached' as any, () => {
+    debugLog('OVERLAY', `overlay session detached (cleanup)`);
+    overlaySessions.delete(page);
+  });
+
+  return cdp;
+}
+
+/** Show a cursor indicator at (x, y) via CDP Overlay — invisible to page JS */
+export async function showCursorOverlay(page: Page, x: number, y: number): Promise<void> {
+  debugLog('CURSOR', `showCursorOverlay called at (${x},${y})`);
+  try {
+    const cdp = await getOverlaySession(page);
+    const params = {
+      x: Math.round(x) - 4,
+      y: Math.round(y) - 4,
+      width: 8,
+      height: 8,
+      color: { r: 255, g: 69, b: 58, a: 0.7 },
+      outlineColor: { r: 255, g: 255, b: 255, a: 0.9 },
+    };
+    debugLog('CURSOR', `sending Overlay.highlightRect`, params);
+    await cdp.send('Overlay.highlightRect', params);
+    debugLog('CURSOR', `highlightRect SUCCESS`);
+  } catch (err) {
+    debugLog('CURSOR', `highlightRect FAILED (attempt 1), retrying...`, String(err));
+    // Session may have died — clear and retry once
+    overlaySessions.delete(page);
+    try {
+      const cdp = await getOverlaySession(page);
+      await cdp.send('Overlay.highlightRect', {
+        x: Math.round(x) - 4,
+        y: Math.round(y) - 4,
+        width: 8,
+        height: 8,
+        color: { r: 255, g: 69, b: 58, a: 0.7 },
+        outlineColor: { r: 255, g: 255, b: 255, a: 0.9 },
+      });
+      debugLog('CURSOR', `highlightRect SUCCESS (retry)`);
+    } catch (err2) {
+      debugLog('CURSOR', `highlightRect FAILED (retry), giving up`, String(err2));
+      // Overlay not supported, ignore
+    }
+  }
+}
+
+/** Hide the cursor overlay */
+export async function hideCursorOverlay(page: Page): Promise<void> {
+  debugLog('CURSOR', `hideCursorOverlay called`);
+  try {
+    const cdp = await getOverlaySession(page);
+    await cdp.send('Overlay.hideHighlight');
+    debugLog('CURSOR', `hideHighlight SUCCESS`);
+  } catch (err) {
+    debugLog('CURSOR', `hideHighlight FAILED`, String(err));
+  }
+}
+
+/** Ensure cursor overlay is ready (idempotent, no-op) */
+export async function ensureCursor(page: Page): Promise<void> {
+  // CDP Overlay doesn't need pre-injection — it's enabled on first use
+  // This is a no-op kept for API compatibility with executor.ts
+}