@hira-core/sdk 1.0.7 → 1.0.8

package/README.md

@@ -188,17 +188,22 @@ const utils = new BrowserUtils(context);
 
 #### Navigation & Interaction
 
-| Method                                     | Description                   |
-| ------------------------------------------ | ----------------------------- |
-| `utils.goto(url)`                          | Navigate to URL               |
-| `utils.click(selector)`                    | Wait + scroll + click         |
-| `utils.type(selector, text)`               | Wait + clear + type           |
-| `utils.getText(selector)`                  | Get text content              |
-| `utils.exists(selector, timeout?)`         | Check element exists          |
-| `utils.waitForElement(selector, timeout?)` | Wait for element              |
-| `utils.waitForNavigation()`                | Wait for page navigation      |
-| `utils.screenshot(path?)`                  | Take screenshot               |
-| `utils.sleep(ms)`                          | Delay (respects abort signal) |
+| Method                                     | Description                            |
+| ------------------------------------------ | -------------------------------------- |
+| `utils.goto(url)`                          | Navigate to URL                        |
+| `utils.click(selector)`                    | Wait + scroll + click                  |
+| `utils.click({ x, y })`                    | Click at specific coordinates          |
+| `utils.type(selector, text)`               | Wait + clear + type                    |
+| `utils.select(selector, value)`            | Select dropdown option (native `<select>`) |
+| `utils.getText(selector)`                  | Get text content                       |
+| `utils.getPosition(selector)`              | Get element center coordinates         |
+| `utils.exists(selector, timeout?)`         | Check element exists                   |
+| `utils.waitForElement(selector, timeout?)` | Wait for element                       |
+| `utils.waitForNavigation()`                | Wait for page navigation               |
+| `utils.screenshot(path?)`                  | Take screenshot                        |
+| `utils.sleep(ms)`                          | Delay (respects abort signal)          |
+| `utils.scroll({ deltaY })`                 | Smooth 60fps scroll (ease-in-out)      |
+| `utils.scroll({ deltaY, container })`      | Smooth scroll inside overflow container|
 
 #### Tab Management
 
@@ -344,6 +349,22 @@ npx @hira-core/cli build
 
 ---
 
+## Virtual Cursor
+
+The SDK includes a **virtual cursor** — a visible SVG cursor overlay that shows mouse movement, clicks, and scrolling in real-time. This is enabled by default and can be toggled via `IExecutionConfig.virtualCursor`:
+
+```typescript
+// In flow runner params
+execution: {
+  virtualCursor: true,   // default — show cursor overlay
+  // virtualCursor: false,  // disable cursor overlay
+}
+```
+
+When enabled, `BrowserUtils.click()`, `scroll()`, and other interaction methods will show realistic Bézier curve mouse movement powered by [ghost-cursor](https://github.com/nicr9/ghost-cursor).
+
+---
+
 ## License
 
 ISC

package/dist/index.d.ts

@@ -237,6 +237,12 @@ interface IExecutionConfig {
      * Dev mode: dùng constructor `super(AntidetectProvider.GPM, ...)` trong flow class.
      */
     antidetectProvider?: 'gpm' | 'hidemium' | 'genlogin' | 'adspower';
+    /**
+     * Enable virtual cursor — SVG arrow with Bézier curve mouse movement.
+     * When true, click() and type() will move cursor naturally before interacting.
+     * Default: true
+     */
+    virtualCursor?: boolean;
 }
 interface IBrowserWindowConfig {
     width: number;
@@ -314,6 +320,8 @@ interface IScriptContext<TConfig extends IFlowConfig = IFlowConfig> {
     page: Page;
     profile: IAntidetectProfile;
     index: number;
+    /** Execution config — includes virtualCursor flag etc. */
+    execution: IExecutionConfig;
     globalInput: InferGlobalInput<TConfig>;
     profileInput: InferProfileInput<TConfig>;
     /**
@@ -616,13 +624,26 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
     private activePage;
     /** Currently active iframe — null means main frame. Changed via activeIframe() */
     private activeFrame;
+    /** Virtual cursor — Bézier movement + SVG visualization */
+    private readonly hiraCursor;
     constructor(context: IScriptContext<TConfig>);
     /**
-     * CDP trick — Chromium nghĩ tab luôn focused, không bị throttle
-     * khi user chuyển sang tab khác hoặc click vào trình duyệt.
+     * CDP trick — Chromium thinks tab is always focused, not throttled
+     * when user switches to another tab or clicks elsewhere.
      */
     private enableFocusEmulation;
+    /**
+     * Apply stealth scripts to remove automation fingerprints.
+     * Uses evaluateOnNewDocument — runs BEFORE any page scripts on every navigation.
+     * Persists across navigations on the same page instance.
+     */
+    private applyStealthScripts;
     private checkAbort;
+    /**
+     * Scroll element vào viewport mượt mà — segments + delay.
+     * Chỉ scroll nếu element nằm ngoài viewport.
+     */
+    private smoothScrollToElement;
     /**
      * Pause execution for the given duration.
      *
@@ -650,10 +671,11 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
      */
     private resolveElement;
     /**
-     * Click on an element. Scrolls the element into view before clicking.
+     * Click on an element or at specific coordinates.
+     * Scrolls the element into view before clicking.
      * Throws if the element is not found.
      *
-     * @param target - CSS selector, XPath, or an existing ElementHandle
+     * @param target - CSS selector, XPath, ElementHandle, or `{ x, y }` coordinates
      * @param options.delay - Delay in ms before clicking (default: 1000)
      * @param options.waitTimeout - Max wait time for element to appear (default: 2000)
      * @param options.frame - Optional Frame to search within
@@ -662,9 +684,58 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
      * @example
      * await utils.click("#submit-btn");
      * await utils.click("#btn", { delay: 0 });             // click immediately
-     * await utils.click("#btn", { waitTimeout: 8000 });     // wait longer
+     * await utils.click({ x: 500, y: 300 });               // click at coordinates
+     * const pos = await utils.getPosition("#btn", { randomXY: true });
+     * await utils.click(pos!);                              // click random point inside element
      */
-    click(target: string | ElementHandle, options?: {
+    click(target: string | ElementHandle | {
+        x: number;
+        y: number;
+    }, options?: {
+        delay?: number;
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<boolean>;
+    /**
+     * Get the position (x, y) of an element.
+     * Returns center point by default, or a random point within bounds with `randomXY`.
+     *
+     * @param selector - CSS selector or XPath
+     * @param options.randomXY - If true, returns random point within element (10% margin from edges)
+     * @param options.waitTimeout - Max wait time for element (default: 2000ms)
+     * @param options.frame - Optional Frame to search within
+     * @returns `{ x, y }` or null if element not found / no bounding box
+     *
+     * @example
+     * const center = await utils.getPosition("#btn");
+     * const rand = await utils.getPosition("#btn", { randomXY: true });
+     * if (rand) await utils.click(rand);
+     */
+    getPosition(selector: string, options?: {
+        randomXY?: boolean;
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<{
+        x: number;
+        y: number;
+    } | null>;
+    /**
+     * Select a value from a `<select>` dropdown.
+     * Human-like flow: cursor moves to select → click to open → page.select() → close.
+     *
+     * NOTE: Native `<option>` elements CAN NOT be clicked via Puppeteer
+     * ("Node is either not clickable or not an Element").
+     * `page.select()` is the ONLY reliable method.
+     *
+     * @param selector - CSS selector or XPath of the `<select>` element
+     * @param value - The `value` attribute of the option to select
+     * @param options.delay - Delay before clicking (default: 500ms)
+     * @param options.waitTimeout - Max wait for element (default: 2000ms)
+     *
+     * @example
+     * await utils.select("#country", "vn");
+     */
+    select(selector: string, value: string, options?: {
         delay?: number;
         waitTimeout?: number;
         frame?: Frame;
@@ -741,6 +812,78 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
     goto(url: string, options?: {
         waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
     }): Promise<boolean>;
+    /**
+     * Scroll the page or a container by a specific amount.
+     * Uses CDP mouseWheel events (human-like, not JS scrollBy).
+     *
+     * @param direction - "up" or "down"
+     * @param amount - Pixels to scroll
+     * @param options.container - CSS selector of scroll container
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     *
+     * @example
+     * await utils.scroll("down", 500);
+     * await utils.scroll("up", 200, { container: "#chat-messages" });
+     */
+    scroll(direction: "up" | "down", amount: number, options?: {
+        container?: string;
+        speed?: number;
+    }): Promise<void>;
+    /**
+     * Scroll to the top or bottom of the page.
+     * Scrolls in segments with pauses — giống người lướt dần đến đích.
+     *
+     * @param position - "top" or "bottom"
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     *
+     * @example
+     * await utils.scrollTo("bottom");
+     * await utils.scrollTo("top");
+     */
+    scrollTo(position: "top" | "bottom", options?: {
+        speed?: number;
+    }): Promise<void>;
+    /**
+     * Scroll an element into the viewport.
+     * Scrolls in segments with pauses — không nhảy tới đích.
+     *
+     * @param selector - CSS selector or XPath of the element
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     * @returns true if element found and scrolled
+     *
+     * @example
+     * await utils.scrollToElement("#footer");
+     * await utils.scrollToElement("//button[text()='Load more']");
+     */
+    scrollToElement(selector: string, options?: {
+        speed?: number;
+    }): Promise<boolean>;
+    /**
+     * Simulate natural browsing scroll — cuộn xuống xen kẽ lướt ngược, delay random.
+     * Giống người đang đọc/lướt web tự nhiên.
+     *
+     * @param options.duration - Thời gian scroll tính bằng giây (default: 5)
+     * @param options.direction - Main direction (default: "down")
+     * @param options.backChance - Chance to scroll back 0-1 (default: 0.15)
+     * @param options.backAmount - [min, max] px to scroll back (default: [50, 150])
+     * @param options.stepSize - [min, max] px per step (default: [200, 400])
+     * @param options.stepDelay - [min, max] ms delay between steps (default: [300, 800])
+     * @param options.container - CSS selector of scroll container
+     *
+     * @example
+     * await utils.randomScroll();                     // 5s lướt xuống
+     * await utils.randomScroll({ duration: 10 });     // 10s
+     * await utils.randomScroll({ backChance: 0.3, container: "#feed" });
+     */
+    randomScroll(options?: {
+        duration?: number;
+        direction?: "down" | "up";
+        backChance?: number;
+        backAmount?: [number, number];
+        stepSize?: [number, number];
+        stepDelay?: [number, number];
+        container?: string;
+    }): Promise<void>;
     /**
      * Wait for the current page to complete a navigation (e.g. after a form submit).
      * Throws on timeout.

package/dist/index.js

@@ -12453,6 +12453,7 @@ var BaseFlow = class {
         page,
         profile,
         index,
+        execution: params.execution,
         globalInput: params.globalInput || {},
         profileInput: profileData || {},
         output: outputObj,
@@ -16803,6 +16804,9 @@ var AntidetectBaseFlow = class extends BaseFlow {
   }
 };
 
+// src/utils/browser.utils.ts
+var import_puppeteer_core3 = require("puppeteer-core");
+
 // src/sdk-config.ts
 var SDK_CONFIG = {
   actionDelayMs: 1e3,
@@ -16812,24 +16816,439 @@ function getSdkConfig() {
   return SDK_CONFIG;
 }
 
+// src/utils/hira-cursor.ts
+var import_ghost_cursor = require("ghost-cursor");
+var CURSOR_SVG_NORMAL = `
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <defs>
+    <linearGradient id="hiraGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#FF3333"/>
+      <stop offset="100%" stop-color="#FF6B35"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="1" dy="1" stdDeviation="0.8" flood-color="#000" flood-opacity="0.3"/>
+    </filter>
+  </defs>
+  <path d="M 4 2 L 4 20 L 9 15 L 14 22 L 16 21 L 11 14 L 18 14 Z"
+        fill="url(#hiraGrad)" stroke="#FFFFFF" stroke-width="1.2" stroke-linejoin="round"
+        filter="url(#shadow)"/>
+</svg>`;
+var CURSOR_SVG_CLICK = `
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <defs>
+    <linearGradient id="hiraClickGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#FFD700"/>
+      <stop offset="100%" stop-color="#FFA500"/>
+    </linearGradient>
+    <filter id="shadowClick" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="1" dy="1" stdDeviation="0.8" flood-color="#000" flood-opacity="0.3"/>
+    </filter>
+  </defs>
+  <path d="M 4 2 L 4 20 L 9 15 L 14 22 L 16 21 L 11 14 L 18 14 Z"
+        fill="url(#hiraClickGrad)" stroke="#FFFFFF" stroke-width="1.2" stroke-linejoin="round"
+        filter="url(#shadowClick)"/>
+</svg>`;
+var _HiraCursor = class _HiraCursor {
+  constructor(enabled) {
+    /** ghost-cursor instances keyed by page — weak so GC cleans up when page closes */
+    this.cursorMap = /* @__PURE__ */ new WeakMap();
+    /** Track which pages already have SVG injected */
+    this.injectedPages = /* @__PURE__ */ new WeakSet();
+    this.enabled = enabled;
+  }
+  /** Whether virtual cursor is enabled */
+  get isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Inject SVG cursor + mousemove listener onto the page.
+   * Idempotent — calling multiple times on the same page will skip.
+   * Must be called after each page.goto() since navigation clears the DOM.
+   */
+  async inject(page) {
+    if (!this.enabled) return;
+    if (this.injectedPages.has(page)) return;
+    try {
+      if (page.isClosed()) return;
+      const svgNormal = `data:image/svg+xml;base64,${Buffer.from(CURSOR_SVG_NORMAL).toString("base64")}`;
+      const svgClick = `data:image/svg+xml;base64,${Buffer.from(CURSOR_SVG_CLICK).toString("base64")}`;
+      await page.evaluate(
+        (normalUri, clickUri) => {
+          const old = document.getElementById("hira-cursor");
+          if (old) old.remove();
+          const el = document.createElement("div");
+          el.id = "hira-cursor";
+          const img = document.createElement("img");
+          img.src = normalUri;
+          img.style.cssText = "width:24px;height:24px;pointer-events:none;";
+          el.appendChild(img);
+          el.style.cssText = `
+            position: fixed;
+            left: -30px; top: -30px;
+            z-index: 2147483647;
+            pointer-events: none;
+            transform: translate(-2px, -2px);
+          `;
+          document.body.appendChild(el);
+          document.documentElement.style.cursor = "none";
+          document.body.style.cursor = "none";
+          document.addEventListener(
+            "mousemove",
+            (e) => {
+              el.style.left = e.clientX + "px";
+              el.style.top = e.clientY + "px";
+            },
+            true
+          );
+          document.addEventListener(
+            "mousedown",
+            () => {
+              img.src = clickUri;
+              el.style.transform = "translate(-2px, -2px) scale(0.88)";
+            },
+            true
+          );
+          document.addEventListener(
+            "mouseup",
+            () => {
+              img.src = normalUri;
+              el.style.transform = "translate(-2px, -2px) scale(1)";
+            },
+            true
+          );
+        },
+        svgNormal,
+        svgClick
+      );
+      this.injectedPages.add(page);
+      this.getOrCreateCursor(page);
+      const viewport = await page.evaluate(() => ({
+        w: window.innerWidth,
+        h: window.innerHeight
+      }));
+      const startX = viewport.w * (0.3 + Math.random() * 0.4);
+      const startY = viewport.h * (0.3 + Math.random() * 0.4);
+      await page.mouse.move(startX, startY);
+    } catch {
+    }
+  }
+  /**
+   * Mark page as needing re-injection (after navigate).
+   * Next inject() call will re-create the SVG.
+   */
+  markDirty(page) {
+    this.injectedPages.delete(page);
+    this.cursorMap.delete(page);
+  }
+  /**
+   * Bézier move + click element — uses ghost-cursor click() native.
+   *
+   * ghost-cursor click() flow:
+   * 1. move(element) — Bézier curve + overshoot + scrollIntoView
+   * 2. delay(hesitate) — pause before pressing (simulates human thinking)
+   * 3. mouseDown via CDP
+   * 4. delay(waitForClick) — hold mouse button (simulates real press-and-hold)
+   * 5. mouseUp via CDP
+   *
+   * ⚠️ Default ghost-cursor: hesitate=0, waitForClick=0 (instant click = bot-like)
+   * → We override with random hesitate 80-250ms, waitForClick 30-120ms
+   *
+   * For long distances, segmentedMove runs first to create visible cursor travel,
+   * then ghost-cursor click handles the final short-range approach.
+   *
+   * @param options.clickCount - Number of clicks (e.g. 3 = select all text)
+   * @param options.hesitate - Override hesitate (ms). Default: random 80-250ms
+   * @param options.waitForClick - Override mousedown hold duration (ms). Default: random 30-120ms
+   */
+  async clickElement(page, element, options) {
+    var _a, _b, _c;
+    if (!this.enabled) return false;
+    try {
+      if (page.isClosed()) return false;
+      const cursor = this.getOrCreateCursor(page);
+      const box = await element.boundingBox();
+      if (box) {
+        const targetX = box.x + box.width / 2;
+        const targetY = box.y + box.height / 2;
+        await this.segmentedMove(page, cursor, targetX, targetY);
+      }
+      const hesitate = (_a = options == null ? void 0 : options.hesitate) != null ? _a : 80 + Math.random() * 170;
+      const waitForClick = (_b = options == null ? void 0 : options.waitForClick) != null ? _b : 30 + Math.random() * 90;
+      await cursor.click(element, {
+        hesitate,
+        waitForClick,
+        moveDelay: 0,
+        // SDK handles delay via actionDelay() after click
+        clickCount: (_c = options == null ? void 0 : options.clickCount) != null ? _c : 1
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Move cursor to coordinates via Bézier curve.
+   * For long distances (> SEGMENT_THRESHOLD), splits into segments with delays.
+   */
+  async moveTo(page, x, y) {
+    if (!this.enabled) return;
+    try {
+      if (page.isClosed()) return;
+      const cursor = this.getOrCreateCursor(page);
+      await this.segmentedMove(page, cursor, x, y);
+    } catch {
+    }
+  }
+  /**
+   * Move cursor through multiple small segments for long distances.
+   *
+   * Ghost-cursor dispatches all CDP mouseMoved events in a tight loop
+   * with NO delay between steps → cursor "teleports" on long moves.
+   *
+   * Fix: split long paths into ~SEGMENT_SIZE px segments, each segment
+   * is a single ghost-cursor moveTo (short Bézier curve), with
+   * SEGMENT_DELAY ms pause between each segment.
+   * → Cursor movement is visible and natural.
+   *
+   * The final segment always uses ghost-cursor moveTo directly for precision.
+   */
+  async segmentedMove(page, cursor, targetX, targetY) {
+    const currentPos = cursor.getLocation();
+    const dx = targetX - currentPos.x;
+    const dy = targetY - currentPos.y;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    if (distance <= _HiraCursor.SEGMENT_THRESHOLD) {
+      await cursor.moveTo({ x: targetX, y: targetY });
+      return;
+    }
+    const segCount = Math.ceil(distance / _HiraCursor.SEGMENT_SIZE);
+    const stepX = dx / segCount;
+    const stepY = dy / segCount;
+    for (let i = 1; i < segCount; i++) {
+      if (page.isClosed()) return;
+      const wx = currentPos.x + stepX * i + (Math.random() - 0.5) * 10;
+      const wy = currentPos.y + stepY * i + (Math.random() - 0.5) * 10;
+      await cursor.moveTo({ x: Math.max(0, wx), y: Math.max(0, wy) });
+      const [minDelay, maxDelay] = _HiraCursor.SEGMENT_DELAY;
+      const segDelay = minDelay + Math.random() * (maxDelay - minDelay);
+      await new Promise((r) => setTimeout(r, segDelay));
+    }
+    await cursor.moveTo({ x: targetX, y: targetY });
+  }
+  /**
+   * Smooth 60fps scroll — animation runs INSIDE browser via requestAnimationFrame.
+   *
+   * Behaves like native `scrollIntoView({ behavior: 'smooth' })`:
+   * - True 60fps (requestAnimationFrame, no Node.js setTimeout jitter)
+   * - Ease-in-out sine curve (accelerate → decelerate → smooth stop)
+   * - Browser generates natural scroll events
+   *
+   * @param deltaY - Positive = scroll down, Negative = scroll up
+   * @param speed - 1-100 (100 = instant, default: 50)
+   */
+  async scrollDelta(page, deltaY, speed = 50) {
+    try {
+      if (page.isClosed()) return;
+      const absDelta = Math.abs(deltaY);
+      if (speed >= 100 || absDelta <= 5) {
+        await page.evaluate((dy) => window.scrollBy(0, dy), deltaY);
+        return;
+      }
+      const durationMs = Math.max(150, 1e3 - speed * 10);
+      await page.evaluate((totalDelta, duration) => {
+        return new Promise((resolve) => {
+          let scrolled = 0;
+          const start = performance.now();
+          function frame(now) {
+            const elapsed = now - start;
+            const t = Math.min(elapsed / duration, 1);
+            const eased = -(Math.cos(Math.PI * t) - 1) / 2;
+            const target = eased * totalDelta;
+            const delta = target - scrolled;
+            scrolled = target;
+            if (Math.abs(delta) > 0.5) {
+              window.scrollBy(0, delta);
+            }
+            if (t < 1) {
+              requestAnimationFrame(frame);
+            } else {
+              resolve();
+            }
+          }
+          requestAnimationFrame(frame);
+        });
+      }, deltaY, durationMs);
+    } catch {
+    }
+  }
+  /**
+   * Scroll a container element (with overflow) — smooth 60fps inside browser.
+   * Requires a container selector instead of scrolling the window.
+   */
+  async scrollContainerDelta(page, containerSelector, deltaY, speed = 50) {
+    try {
+      if (page.isClosed()) return;
+      const durationMs = Math.max(150, 1e3 - speed * 10);
+      await page.evaluate((selector, totalDelta, duration) => {
+        return new Promise((resolve) => {
+          const el = document.querySelector(selector);
+          if (!el) {
+            resolve();
+            return;
+          }
+          let scrolled = 0;
+          const start = performance.now();
+          function frame(now) {
+            const elapsed = now - start;
+            const t = Math.min(elapsed / duration, 1);
+            const eased = -(Math.cos(Math.PI * t) - 1) / 2;
+            const target = eased * totalDelta;
+            const delta = target - scrolled;
+            scrolled = target;
+            if (Math.abs(delta) > 0.5) {
+              el.scrollBy(0, delta);
+            }
+            if (t < 1) {
+              requestAnimationFrame(frame);
+            } else {
+              resolve();
+            }
+          }
+          requestAnimationFrame(frame);
+        });
+      }, containerSelector, deltaY, durationMs);
+    } catch {
+    }
+  }
+  /**
+   * Scroll to top or bottom — calculates distance then uses scrollDelta (smooth).
+   */
+  async scrollToPosition(page, position, speed = 50) {
+    try {
+      if (page.isClosed()) return;
+      const { scrollY, scrollHeight, innerHeight } = await page.evaluate(() => ({
+        scrollY: window.scrollY,
+        scrollHeight: document.body.scrollHeight,
+        innerHeight: window.innerHeight
+      }));
+      let deltaY;
+      if (position === "top") {
+        deltaY = -scrollY;
+      } else {
+        deltaY = scrollHeight - innerHeight - scrollY;
+      }
+      if (Math.abs(deltaY) < 5) return;
+      await this.scrollDelta(page, deltaY, speed);
+    } catch {
+    }
+  }
+  /**
+   * Scroll element into viewport — calculates offset then uses scrollDelta (smooth).
+   */
+  async scrollElementIntoView(page, element, speed = 50) {
+    try {
+      if (page.isClosed()) return;
+      const box = await element.boundingBox();
+      if (!box) return;
+      const { innerHeight } = await page.evaluate(() => ({
+        innerHeight: window.innerHeight
+      }));
+      const elementCenter = box.y + box.height / 2;
+      const viewportCenter = innerHeight / 2;
+      const deltaY = elementCenter - viewportCenter;
+      if (Math.abs(deltaY) < 5) return;
+      await this.scrollDelta(page, deltaY, speed);
+    } catch {
+    }
+  }
+  /**
+   * Move cursor to center of a container — needed before scrolling a container.
+   * Cursor ON: Bézier move (visible)
+   * Cursor OFF: CDP mouse.move (hidden)
+   */
+  async moveToContainer(page, containerSelector) {
+    try {
+      if (page.isClosed()) return;
+      const el = await page.$(containerSelector);
+      if (!el) return;
+      const box = await el.boundingBox();
+      if (!box) return;
+      const x = box.x + box.width / 2 + (Math.random() - 0.5) * box.width * 0.3;
+      const y = box.y + box.height / 2 + (Math.random() - 0.5) * box.height * 0.3;
+      if (this.enabled) {
+        const cursor = this.getOrCreateCursor(page);
+        await cursor.moveTo({ x, y });
+      } else {
+        await page.mouse.move(x, y);
+      }
+    } catch {
+    }
+  }
+  /** Get or create ghost-cursor instance for the given page */
+  getOrCreateCursor(page) {
+    let cursor = this.cursorMap.get(page);
+    if (!cursor) {
+      cursor = new import_ghost_cursor.GhostCursor(page, {
+        defaultOptions: {
+          // Override defaults for all actions — human-like timing
+          click: {
+            hesitate: 120,
+            // default if not overridden per-call
+            waitForClick: 60,
+            // hold mouse button 60ms
+            moveDelay: 0
+            // SDK manages delay separately
+          },
+          move: {
+            moveDelay: 0
+            // SDK manages delay separately
+          },
+          moveTo: {
+            moveDelay: 0
+          }
+        }
+      });
+      this.cursorMap.set(page, cursor);
+    }
+    return cursor;
+  }
+};
+/**
+ * Minimum distance (px) to activate segmented move.
+ * Below threshold → ghost-cursor moves normally (fast enough, looks natural).
+ * Above threshold → split into small segments with delay between each.
+ */
+_HiraCursor.SEGMENT_THRESHOLD = 500;
+/** Length of each segment (px) when splitting long-distance moves */
+_HiraCursor.SEGMENT_SIZE = 650;
+/** Delay between segments (ms) — randomized within this range */
+_HiraCursor.SEGMENT_DELAY = [30, 60];
+var HiraCursor = _HiraCursor;
+
 // src/utils/browser.utils.ts
 var BrowserUtils = class {
   constructor(context) {
     /** Currently active iframe — null means main frame. Changed via activeIframe() */
     this.activeFrame = null;
-    var _a;
+    var _a, _b;
     this.ctx = context;
     this.logger = context.logger;
     this.outputDefs = (_a = context.outputDefinitions) != null ? _a : [];
     this.validOutputKeys = new Set(this.outputDefs.map((d) => d.key));
     this.defaultPage = context.page;
     this.activePage = context.page;
+    const cursorEnabled = ((_b = context.execution) == null ? void 0 : _b.virtualCursor) !== false;
+    this.hiraCursor = new HiraCursor(cursorEnabled);
     this.enableFocusEmulation(this.activePage).catch(() => {
     });
+    this.applyStealthScripts(this.activePage).catch(() => {
+    });
+    this.hiraCursor.inject(this.activePage).catch(() => {
+    });
   }
   /**
-   * CDP trick — Chromium nghĩ tab luôn focused, không bị throttle
-   * khi user chuyển sang tab khác hoặc click vào trình duyệt.
+   * CDP trick — Chromium thinks tab is always focused, not throttled
+   * when user switches to another tab or clicks elsewhere.
    */
   async enableFocusEmulation(page) {
     try {
@@ -16838,10 +17257,68 @@ var BrowserUtils = class {
     } catch {
     }
   }
+  /**
+   * Apply stealth scripts to remove automation fingerprints.
+   * Uses evaluateOnNewDocument — runs BEFORE any page scripts on every navigation.
+   * Persists across navigations on the same page instance.
+   */
+  async applyStealthScripts(page) {
+    try {
+      const stealthFn = () => {
+        Object.defineProperty(navigator, "webdriver", {
+          get: () => void 0
+        });
+        Object.defineProperty(navigator, "plugins", {
+          get: () => [1, 2, 3, 4, 5]
+        });
+        Object.defineProperty(navigator, "languages", {
+          get: () => ["en-US", "en"]
+        });
+        if (window.cdc_adoQpoasnfa76pfcZLmcfl_Array) {
+          delete window.cdc_adoQpoasnfa76pfcZLmcfl_Array;
+        }
+        if (window.cdc_adoQpoasnfa76pfcZLmcfl_Promise) {
+          delete window.cdc_adoQpoasnfa76pfcZLmcfl_Promise;
+        }
+        if (window.cdc_adoQpoasnfa76pfcZLmcfl_Symbol) {
+          delete window.cdc_adoQpoasnfa76pfcZLmcfl_Symbol;
+        }
+      };
+      await page.evaluate(stealthFn);
+      await page.evaluateOnNewDocument(stealthFn);
+    } catch {
+    }
+  }
   checkAbort() {
     const signal = global.__HIRA_ABORT_SIGNAL__;
     if (signal == null ? void 0 : signal.aborted) throw new Error("cancelled");
   }
+  /**
+   * Scroll element vào viewport mượt mà — segments + delay.
+   * Chỉ scroll nếu element nằm ngoài viewport.
+   */
+  async smoothScrollToElement(element) {
+    try {
+      for (let i = 0; i < 15; i++) {
+        const box = await element.boundingBox();
+        if (!box) return;
+        const vh = await this.activePage.evaluate(() => window.innerHeight);
+        const center = box.y + box.height / 2;
+        const margin = vh * 0.15;
+        if (center >= margin && center <= vh - margin) break;
+        const delta = center - vh / 2;
+        const maxSeg = 300 + Math.random() * 200;
+        const segment = Math.abs(delta) > maxSeg ? delta > 0 ? maxSeg : -maxSeg : delta;
+        await this.hiraCursor.scrollDelta(this.activePage, segment, 50);
+        await this.rawSleep(150 + Math.random() * 200);
+      }
+    } catch {
+      try {
+        await element.scrollIntoView();
+      } catch {
+      }
+    }
+  }
   /**
    * Pause execution for the given duration.
    *
@@ -16899,10 +17376,11 @@ var BrowserUtils = class {
     return target.$(resolved);
   }
   /**
-   * Click on an element. Scrolls the element into view before clicking.
+   * Click on an element or at specific coordinates.
+   * Scrolls the element into view before clicking.
    * Throws if the element is not found.
    *
-   * @param target - CSS selector, XPath, or an existing ElementHandle
+   * @param target - CSS selector, XPath, ElementHandle, or `{ x, y }` coordinates
    * @param options.delay - Delay in ms before clicking (default: 1000)
    * @param options.waitTimeout - Max wait time for element to appear (default: 2000)
    * @param options.frame - Optional Frame to search within
@@ -16911,10 +17389,31 @@ var BrowserUtils = class {
    * @example
    * await utils.click("#submit-btn");
    * await utils.click("#btn", { delay: 0 });             // click immediately
-   * await utils.click("#btn", { waitTimeout: 8000 });     // wait longer
+   * await utils.click({ x: 500, y: 300 });               // click at coordinates
+   * const pos = await utils.getPosition("#btn", { randomXY: true });
+   * await utils.click(pos!);                              // click random point inside element
    */
   async click(target, options) {
-    var _a, _b;
+    var _a, _b, _c, _d, _e;
+    if (typeof target === "object" && !(target instanceof import_puppeteer_core3.ElementHandle) && "x" in target && "y" in target) {
+      try {
+        this.checkAbort();
+        await this.log("info", `\u{1F5B1}\uFE0F Click: (${Math.round(target.x)}, ${Math.round(target.y)})`);
+        const clickDelay = (_a = options == null ? void 0 : options.delay) != null ? _a : 1e3;
+        if (clickDelay > 0) await this.sleep(clickDelay);
+        if (this.hiraCursor.isEnabled) {
+          await this.hiraCursor.moveTo(this.activePage, target.x, target.y);
+          await this.rawSleep(50 + Math.random() * 50);
+        }
+        await this.activePage.mouse.click(target.x, target.y);
+        await this.actionDelay();
+        return true;
+      } catch (error) {
+        if (error instanceof Error && error.message === "cancelled") throw error;
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Click failed: (${target.x}, ${target.y}) \u2014 ${msg}`);
+      }
+    }
     const label = typeof target === "string" ? target : "[ElementHandle]";
     try {
       this.checkAbort();
@@ -16923,19 +17422,32 @@ var BrowserUtils = class {
       if (typeof target === "string") {
         element = await this.waitForElement(
           target,
-          (_a = options == null ? void 0 : options.waitTimeout) != null ? _a : 2e3,
+          (_b = options == null ? void 0 : options.waitTimeout) != null ? _b : 2e3,
           options == null ? void 0 : options.frame
         );
+        if (!element) {
+          const scope = (_d = (_c = options == null ? void 0 : options.frame) != null ? _c : this.activeFrame) != null ? _d : this.activePage;
+          const resolved = target.startsWith("//") || target.startsWith("(") ? `xpath/${target}` : target;
+          element = await scope.$(resolved);
+        }
       } else {
         element = target;
       }
       if (!element) {
         throw new Error(`Click failed \u2014 element not found: ${this.shortSelector(label)}`);
       }
-      await element.scrollIntoView();
-      const clickDelay = (_b = options == null ? void 0 : options.delay) != null ? _b : 1e3;
+      await this.smoothScrollToElement(element);
+      const clickDelay = (_e = options == null ? void 0 : options.delay) != null ? _e : 1e3;
       if (clickDelay > 0) await this.sleep(clickDelay);
-      await element.click();
+      const box = await element.boundingBox();
+      if (this.hiraCursor.isEnabled && !this.activeFrame && !(options == null ? void 0 : options.frame) && box) {
+        const clicked = await this.hiraCursor.clickElement(this.activePage, element);
+        if (!clicked) {
+          await element.click();
+        }
+      } else {
+        await element.click();
+      }
       await this.actionDelay();
       return true;
     } catch (error) {
@@ -16944,6 +17456,95 @@ var BrowserUtils = class {
       throw new Error(`Click failed: ${this.shortSelector(label)} \u2014 ${msg}`);
     }
   }
+  /**
+   * Get the position (x, y) of an element.
+   * Returns center point by default, or a random point within bounds with `randomXY`.
+   *
+   * @param selector - CSS selector or XPath
+   * @param options.randomXY - If true, returns random point within element (10% margin from edges)
+   * @param options.waitTimeout - Max wait time for element (default: 2000ms)
+   * @param options.frame - Optional Frame to search within
+   * @returns `{ x, y }` or null if element not found / no bounding box
+   *
+   * @example
+   * const center = await utils.getPosition("#btn");
+   * const rand = await utils.getPosition("#btn", { randomXY: true });
+   * if (rand) await utils.click(rand);
+   */
+  async getPosition(selector, options) {
+    var _a;
+    try {
+      this.checkAbort();
+      const element = await this.waitForElement(
+        selector,
+        (_a = options == null ? void 0 : options.waitTimeout) != null ? _a : 2e3,
+        options == null ? void 0 : options.frame
+      );
+      if (!element) return null;
+      await this.smoothScrollToElement(element);
+      const box = await element.boundingBox();
+      if (!box) return null;
+      if (options == null ? void 0 : options.randomXY) {
+        const mx = box.width * 0.1;
+        const my = box.height * 0.1;
+        return {
+          x: box.x + mx + Math.random() * (box.width - 2 * mx),
+          y: box.y + my + Math.random() * (box.height - 2 * my)
+        };
+      }
+      return {
+        x: box.x + box.width / 2,
+        y: box.y + box.height / 2
+      };
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      await this.log("warn", `\u26A0\uFE0F getPosition failed: ${this.shortSelector(selector)}`);
+      return null;
+    }
+  }
+  /**
+   * Select a value from a `<select>` dropdown.
+   * Human-like flow: cursor moves to select → click to open → page.select() → close.
+   *
+   * NOTE: Native `<option>` elements CAN NOT be clicked via Puppeteer
+   * ("Node is either not clickable or not an Element").
+   * `page.select()` is the ONLY reliable method.
+   *
+   * @param selector - CSS selector or XPath of the `<select>` element
+   * @param value - The `value` attribute of the option to select
+   * @param options.delay - Delay before clicking (default: 500ms)
+   * @param options.waitTimeout - Max wait for element (default: 2000ms)
+   *
+   * @example
+   * await utils.select("#country", "vn");
+   */
+  async select(selector, value, options) {
+    var _a, _b, _c;
+    try {
+      this.checkAbort();
+      await this.log(
+        "info",
+        `\u{1F4CB} Select "${value}" \u2192 ${this.shortSelector(selector)}`
+      );
+      await this.click(selector, {
+        delay: (_a = options == null ? void 0 : options.delay) != null ? _a : 500,
+        waitTimeout: options == null ? void 0 : options.waitTimeout,
+        frame: options == null ? void 0 : options.frame
+      });
+      await this.rawSleep(300 + Math.random() * 200);
+      const target = (_c = (_b = options == null ? void 0 : options.frame) != null ? _b : this.activeFrame) != null ? _c : this.activePage;
+      const resolved = selector.startsWith("//") || selector.startsWith("(") ? `xpath/${selector}` : selector;
+      await target.select(resolved, value);
+      await this.rawSleep(100);
+      await this.activePage.keyboard.press("Escape");
+      await this.actionDelay();
+      return true;
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Select failed: ${this.shortSelector(selector)} \u2014 ${msg}`);
+    }
+  }
   /**
    * Type text into an input element. Throws if the element is not found.
    *
@@ -16981,8 +17582,15 @@ var BrowserUtils = class {
       if (!element) {
         throw new Error(`Type failed \u2014 element not found: ${this.shortSelector(selector)}`);
       }
-      await element.scrollIntoView();
+      await this.smoothScrollToElement(element);
       if (mode === "paste") {
+        if (this.hiraCursor.isEnabled && !this.activeFrame && !(options == null ? void 0 : options.frame)) {
+          const clicked = await this.hiraCursor.clickElement(this.activePage, element);
+          if (!clicked) await element.click();
+        } else {
+          await element.click();
+        }
+        await this.rawSleep(100 + Math.random() * 100);
         const target = (_b = this.activeFrame) != null ? _b : this.activePage;
         await target.evaluate(
           (el, val) => {
@@ -16994,10 +17602,24 @@ var BrowserUtils = class {
           text
         );
       } else if (mode === "append") {
-        await element.click();
+        if (this.hiraCursor.isEnabled && !this.activeFrame && !(options == null ? void 0 : options.frame)) {
+          const clicked = await this.hiraCursor.clickElement(this.activePage, element);
+          if (!clicked) await element.click();
+        } else {
+          await element.click();
+        }
+        await element.press("End");
         await element.type(text, { delay: (_c = options == null ? void 0 : options.delay) != null ? _c : 50 });
       } else {
-        await element.click({ clickCount: 3 });
+        if (this.hiraCursor.isEnabled && !this.activeFrame && !(options == null ? void 0 : options.frame)) {
+          const clicked = await this.hiraCursor.clickElement(this.activePage, element);
+          if (!clicked) await element.click();
+        } else {
+          await element.click();
+        }
+        await this.activePage.keyboard.down("Control");
+        await this.activePage.keyboard.press("a");
+        await this.activePage.keyboard.up("Control");
         await element.press("Backspace");
         await element.type(text, { delay: (_d = options == null ? void 0 : options.delay) != null ? _d : 50 });
       }
@@ -17081,11 +17703,13 @@ var BrowserUtils = class {
     try {
       this.checkAbort();
       await this.log("info", `\u{1F310} Navigate \u2192 ${url2}`);
+      this.hiraCursor.markDirty(this.activePage);
       await this.activePage.goto(url2, {
         waitUntil: (options == null ? void 0 : options.waitUntil) || "load",
         timeout: 6e4
       });
       await this.actionDelay();
+      await this.hiraCursor.inject(this.activePage);
       return true;
     } catch (error) {
       if (error instanceof Error && error.message === "cancelled") throw error;
@@ -17093,6 +17717,201 @@ var BrowserUtils = class {
       throw new Error(`Navigate failed: ${url2} \u2014 ${msg}`);
     }
   }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Scroll methods — CDP mouseWheel (cả cursor ON và OFF đều giống người)
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Scroll the page or a container by a specific amount.
+   * Uses CDP mouseWheel events (human-like, not JS scrollBy).
+   *
+   * @param direction - "up" or "down"
+   * @param amount - Pixels to scroll
+   * @param options.container - CSS selector of scroll container
+   * @param options.speed - Scroll speed 1-100 (default: 50)
+   *
+   * @example
+   * await utils.scroll("down", 500);
+   * await utils.scroll("up", 200, { container: "#chat-messages" });
+   */
+  async scroll(direction, amount, options) {
+    var _a, _b;
+    try {
+      this.checkAbort();
+      const arrow = direction === "down" ? "\u2193" : "\u2191";
+      const containerLabel = (options == null ? void 0 : options.container) ? ` (${this.shortSelector(options.container)})` : "";
+      await this.log("info", `\u{1F4DC} Scroll ${arrow} ${amount}px${containerLabel}`);
+      if (options == null ? void 0 : options.container) {
+        await this.hiraCursor.moveToContainer(this.activePage, options.container);
+      }
+      const deltaY = direction === "down" ? amount : -amount;
+      if (options == null ? void 0 : options.container) {
+        await this.hiraCursor.scrollContainerDelta(this.activePage, options.container, deltaY, (_a = options == null ? void 0 : options.speed) != null ? _a : 50);
+      } else {
+        await this.hiraCursor.scrollDelta(this.activePage, deltaY, (_b = options == null ? void 0 : options.speed) != null ? _b : 50);
+      }
+      await this.actionDelay();
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      await this.log("warn", `\u{1F4DC} Scroll failed: ${msg}`);
+    }
+  }
+  /**
+   * Scroll to the top or bottom of the page.
+   * Scrolls in segments with pauses — giống người lướt dần đến đích.
+   *
+   * @param position - "top" or "bottom"
+   * @param options.speed - Scroll speed 1-100 (default: 50)
+   *
+   * @example
+   * await utils.scrollTo("bottom");
+   * await utils.scrollTo("top");
+   */
+  async scrollTo(position, options) {
+    var _a;
+    try {
+      this.checkAbort();
+      await this.log("info", `\u{1F4DC} Scroll to ${position}`);
+      const speed = (_a = options == null ? void 0 : options.speed) != null ? _a : 50;
+      const { scrollY, scrollHeight, innerHeight } = await this.activePage.evaluate(() => ({
+        scrollY: window.scrollY,
+        scrollHeight: document.body.scrollHeight,
+        innerHeight: window.innerHeight
+      }));
+      let remaining = position === "top" ? scrollY : scrollHeight - innerHeight - scrollY;
+      if (remaining < 5) return;
+      const direction = position === "top" ? -1 : 1;
+      while (remaining > 5) {
+        this.checkAbort();
+        const segment = Math.min(300 + Math.random() * 300, remaining);
+        await this.hiraCursor.scrollDelta(this.activePage, direction * segment, speed);
+        remaining -= segment;
+        if (remaining > 5) {
+          await this.sleep(200 + Math.random() * 300);
+        }
+      }
+      await this.actionDelay();
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      await this.log("warn", `\u{1F4DC} Scroll to ${position} failed: ${msg}`);
+    }
+  }
+  /**
+   * Scroll an element into the viewport.
+   * Scrolls in segments with pauses — không nhảy tới đích.
+   *
+   * @param selector - CSS selector or XPath of the element
+   * @param options.speed - Scroll speed 1-100 (default: 50)
+   * @returns true if element found and scrolled
+   *
+   * @example
+   * await utils.scrollToElement("#footer");
+   * await utils.scrollToElement("//button[text()='Load more']");
+   */
+  async scrollToElement(selector, options) {
+    var _a;
+    try {
+      this.checkAbort();
+      await this.log("info", `\u{1F4DC} Scroll to element: ${this.shortSelector(selector)}`);
+      const element = await this.resolveElement(selector);
+      if (!element) {
+        await this.log("warn", `\u{1F4DC} Element not found: ${this.shortSelector(selector)}`);
+        return false;
+      }
+      const speed = (_a = options == null ? void 0 : options.speed) != null ? _a : 50;
+      for (let attempt = 0; attempt < 20; attempt++) {
+        this.checkAbort();
+        const box = await element.boundingBox();
+        if (!box) return false;
+        const viewportHeight = await this.activePage.evaluate(() => window.innerHeight);
+        const elementCenter = box.y + box.height / 2;
+        const viewportCenter = viewportHeight / 2;
+        const deltaY = elementCenter - viewportCenter;
+        if (Math.abs(deltaY) < 50) break;
+        const maxSegment = 300 + Math.random() * 200;
+        const segment = Math.abs(deltaY) > maxSegment ? deltaY > 0 ? maxSegment : -maxSegment : deltaY;
+        await this.hiraCursor.scrollDelta(this.activePage, segment, speed);
+        await this.sleep(200 + Math.random() * 300);
+      }
+      await this.actionDelay();
+      return true;
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      await this.log("warn", `\u{1F4DC} Scroll to element failed: ${msg}`);
+      return false;
+    }
+  }
+  /**
+   * Simulate natural browsing scroll — cuộn xuống xen kẽ lướt ngược, delay random.
+   * Giống người đang đọc/lướt web tự nhiên.
+   *
+   * @param options.duration - Thời gian scroll tính bằng giây (default: 5)
+   * @param options.direction - Main direction (default: "down")
+   * @param options.backChance - Chance to scroll back 0-1 (default: 0.15)
+   * @param options.backAmount - [min, max] px to scroll back (default: [50, 150])
+   * @param options.stepSize - [min, max] px per step (default: [200, 400])
+   * @param options.stepDelay - [min, max] ms delay between steps (default: [300, 800])
+   * @param options.container - CSS selector of scroll container
+   *
+   * @example
+   * await utils.randomScroll();                     // 5s lướt xuống
+   * await utils.randomScroll({ duration: 10 });     // 10s
+   * await utils.randomScroll({ backChance: 0.3, container: "#feed" });
+   */
+  async randomScroll(options) {
+    var _a, _b, _c, _d, _e, _f;
+    try {
+      this.checkAbort();
+      const duration = ((_a = options == null ? void 0 : options.duration) != null ? _a : 5) * 1e3;
+      const direction = (_b = options == null ? void 0 : options.direction) != null ? _b : "down";
+      const backChance = (_c = options == null ? void 0 : options.backChance) != null ? _c : 0.15;
+      const backAmount = (_d = options == null ? void 0 : options.backAmount) != null ? _d : [50, 150];
+      const stepSize = (_e = options == null ? void 0 : options.stepSize) != null ? _e : [200, 400];
+      const stepDelay = (_f = options == null ? void 0 : options.stepDelay) != null ? _f : [300, 800];
+      const arrow = direction === "down" ? "\u2193" : "\u2191";
+      const containerLabel = (options == null ? void 0 : options.container) ? ` (${this.shortSelector(options.container)})` : "";
+      const startTime = Date.now();
+      const sign = direction === "down" ? 1 : -1;
+      if (options == null ? void 0 : options.container) {
+        await this.hiraCursor.moveToContainer(this.activePage, options.container);
+      }
+      let steps = 0;
+      let totalScrolled = 0;
+      while (Date.now() - startTime < duration) {
+        this.checkAbort();
+        if (steps > 0 && Math.random() < backChance) {
+          const back = backAmount[0] + Math.random() * (backAmount[1] - backAmount[0]);
+          if (options == null ? void 0 : options.container) {
+            await this.hiraCursor.scrollContainerDelta(this.activePage, options.container, -sign * back, 40);
+          } else {
+            await this.hiraCursor.scrollDelta(this.activePage, -sign * back, 40);
+          }
+        } else {
+          const step = stepSize[0] + Math.random() * (stepSize[1] - stepSize[0]);
+          if (options == null ? void 0 : options.container) {
+            await this.hiraCursor.scrollContainerDelta(this.activePage, options.container, sign * step, 40);
+          } else {
+            await this.hiraCursor.scrollDelta(this.activePage, sign * step, 40);
+          }
+          totalScrolled += step;
+        }
+        steps++;
+        if (Date.now() - startTime < duration) {
+          const delay = stepDelay[0] + Math.random() * (stepDelay[1] - stepDelay[0]);
+          await this.sleep(delay);
+        }
+      }
+      const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
+      await this.log("info", `\u{1F5B1}\uFE0F Random scroll ${arrow} ~${Math.round(totalScrolled)}px${containerLabel} \u2014 ${steps} steps, ${elapsed}s`);
+      await this.actionDelay();
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      await this.log("warn", `\u{1F5B1}\uFE0F Random scroll failed: ${msg}`);
+    }
+  }
   /**
    * Wait for the current page to complete a navigation (e.g. after a form submit).
    * Throws on timeout.
@@ -17321,8 +18140,10 @@ var BrowserUtils = class {
     if (page) {
       await page.bringToFront();
       await this.enableFocusEmulation(page);
+      await this.applyStealthScripts(page);
       this.activePage = page;
       this.activeFrame = null;
+      await this.hiraCursor.inject(page);
     }
     return page;
   }
@@ -17362,8 +18183,10 @@ var BrowserUtils = class {
     if (page) {
       await page.bringToFront();
       await this.enableFocusEmulation(page);
+      await this.applyStealthScripts(page);
       this.activePage = page;
       this.activeFrame = null;
+      await this.hiraCursor.inject(page);
     }
     return page;
   }
@@ -17390,8 +18213,10 @@ var BrowserUtils = class {
         const page = pages[index];
         await page.bringToFront();
         await this.enableFocusEmulation(page);
+        await this.applyStealthScripts(page);
         this.activePage = page;
         this.activeFrame = null;
+        await this.hiraCursor.inject(page);
         return page;
       }
       throw new Error(`Tab[${index}] not found (total: ${pages.length})`);
@@ -17464,6 +18289,7 @@ var BrowserUtils = class {
     }
     this.activePage = this.defaultPage;
     this.activeFrame = null;
+    await this.hiraCursor.inject(this.activePage);
     return this.activePage;
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hira-core/sdk",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "SDK for building Hira automation flows with TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,6 +45,7 @@
   "dependencies": {
     "axios": "^1.13.4",
     "exceljs": "^4.4.0",
+    "ghost-cursor": "^1.4.2",
     "p-limit": "3.1.0"
   }
 }