@hira-core/sdk 1.0.6 → 1.0.8

package/dist/index.js

@@ -12453,6 +12453,7 @@ var BaseFlow = class {
         page,
         profile,
         index,
+        execution: params.execution,
         globalInput: params.globalInput || {},
         profileInput: profileData || {},
         output: outputObj,
@@ -16654,7 +16655,10 @@ var HidemiumStandaloneAdapter = class {
       const command = [
         `--window-position=${x},${y}`,
         `--window-size=${windowConfig.width},${windowConfig.height}`,
-        `--force-device-scale-factor=${windowConfig.scale}`
+        `--force-device-scale-factor=${windowConfig.scale}`,
+        `--disable-background-timer-throttling`,
+        `--disable-backgrounding-occluded-windows`,
+        `--disable-renderer-backgrounding`
       ].join(" ");
       try {
         await this.service.stopProfile(targetProfile.uuid);
@@ -16800,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,
@@ -16809,25 +16816,537 @@ 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) {
-    var _a;
+    /** Currently active iframe — null means main frame. Changed via activeIframe() */
+    this.activeFrame = null;
+    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 thinks tab is always focused, not throttled
+   * when user switches to another tab or clicks elsewhere.
+   */
+  async enableFocusEmulation(page) {
+    try {
+      const cdp = await page.createCDPSession();
+      await cdp.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    } 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.
+   *
+   * @param ms - Duration in milliseconds
+   * @example await utils.sleep(2000); // wait 2 seconds
+   */
   async sleep(ms) {
+    this.checkAbort();
     await this.log("debug", `\u23F3 Sleep ${ms}ms`);
     await this.rawSleep(ms);
   }
-  async waitForElement(selector, timeout = 1e4, scope) {
-    const target = scope != null ? scope : this.ctx.page;
+  /**
+   * Wait for an element to appear and become visible in the DOM.
+   * Returns null if not found (soft fail — does NOT throw).
+   * Supports CSS selectors and XPath (auto-detected by `//` or `(` prefix).
+   *
+   * @param selector - CSS selector or XPath expression
+   * @param timeout - Max wait time in ms (default: 8000)
+   * @param scope - Optional Frame to search within
+   * @returns The element handle, or null if not found
+   *
+   * @example
+   * const el = await utils.waitForElement("#my-btn");
+   * if (el) await el.click();
+   */
+  async waitForElement(selector, timeout = 8e3, scope) {
+    var _a;
+    const target = (_a = scope != null ? scope : this.activeFrame) != null ? _a : this.activePage;
     try {
       this.checkAbort();
       const options = { timeout, visible: true };
@@ -16844,7 +17363,57 @@ var BrowserUtils = class {
       return null;
     }
   }
+  /**
+   * Resolve an element: if waitTimeout > 0, wait for it; otherwise query directly with $().
+   */
+  async resolveElement(selector, waitTimeout, scope) {
+    var _a;
+    if (waitTimeout && waitTimeout > 0) {
+      return this.waitForElement(selector, waitTimeout, scope);
+    }
+    const target = (_a = scope != null ? scope : this.activeFrame) != null ? _a : this.activePage;
+    const resolved = selector.startsWith("//") || selector.startsWith("(") ? `xpath/${selector}` : selector;
+    return target.$(resolved);
+  }
+  /**
+   * 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, 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
+   * @returns true on success
+   *
+   * @example
+   * await utils.click("#submit-btn");
+   * await utils.click("#btn", { delay: 0 });             // click immediately
+   * 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, _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();
@@ -16853,82 +17422,239 @@ var BrowserUtils = class {
       if (typeof target === "string") {
         element = await this.waitForElement(
           target,
-          options == null ? void 0 : options.timeout,
+          (_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) {
-        await this.log(
-          "error",
-          `\u274C Click failed \u2014 element not found: ${this.shortSelector(label)}`
-        );
-        return false;
+        throw new Error(`Click failed \u2014 element not found: ${this.shortSelector(label)}`);
+      }
+      await this.smoothScrollToElement(element);
+      const clickDelay = (_e = options == null ? void 0 : options.delay) != null ? _e : 1e3;
+      if (clickDelay > 0) await this.sleep(clickDelay);
+      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 element.scrollIntoView();
-      if (options == null ? void 0 : options.delay) await this.sleep(options.delay);
-      await element.click();
       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: ${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(
-        "error",
-        `\u274C Click failed: ${this.shortSelector(label)} \u2014 ${msg}`
+        "info",
+        `\u{1F4CB} Select "${value}" \u2192 ${this.shortSelector(selector)}`
       );
-      return false;
+      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.
+   *
+   * @param selector - CSS selector or XPath of the input
+   * @param text - The text to type
+   * @param options.mode - Typing mode:
+   *   - `"replace"` (default): Clear existing text, then type new text
+   *   - `"append"`: Type without clearing — appends to existing text
+   *   - `"paste"`: Set value directly via JS (fast, no keystroke simulation)
+   * @param options.delay - Delay between keystrokes in ms (default: 50). Ignored in paste mode.
+   * @param options.waitTimeout - Max wait time for element to appear in ms (default: 0 — instant)
+   * @param options.frame - Optional Frame to search within
+   * @returns true on success
+   *
+   * @example
+   * await utils.type("#email", "user@example.com");                    // replace mode
+   * await utils.type("#input", " more text", { mode: "append" });      // append
+   * await utils.type("#address", "0x1234...abcd", { mode: "paste" });  // instant paste
+   */
   async type(selector, text, options) {
-    var _a;
+    var _a, _b, _c, _d;
+    const mode = (_a = options == null ? void 0 : options.mode) != null ? _a : "replace";
     const masked = text.length > 20 ? text.slice(0, 20) + "..." : text;
     try {
       this.checkAbort();
       await this.log(
         "info",
-        `\u2328\uFE0F Type "${masked}" \u2192 ${this.shortSelector(selector)}`
+        `\u2328\uFE0F Type [${mode}] "${masked}" \u2192 ${this.shortSelector(selector)}`
       );
-      const element = await this.waitForElement(
+      const element = await this.resolveElement(
         selector,
-        1e4,
+        options == null ? void 0 : options.waitTimeout,
         options == null ? void 0 : options.frame
       );
       if (!element) {
-        await this.log(
-          "error",
-          `\u274C Type failed \u2014 element not found: ${this.shortSelector(selector)}`
+        throw new Error(`Type failed \u2014 element not found: ${this.shortSelector(selector)}`);
+      }
+      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) => {
+            el.value = val;
+            el.dispatchEvent(new Event("input", { bubbles: true }));
+            el.dispatchEvent(new Event("change", { bubbles: true }));
+          },
+          element,
+          text
         );
-        return false;
+      } else if (mode === "append") {
+        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 {
+        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 });
       }
-      await element.scrollIntoView();
-      await element.click({ clickCount: 3 });
-      await element.press("Backspace");
-      await element.type(text, { delay: (_a = options == null ? void 0 : options.delay) != null ? _a : 50 });
       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(
-        "error",
-        `\u274C Type failed: ${this.shortSelector(selector)} \u2014 ${msg}`
-      );
-      return false;
+      throw new Error(`Type failed: ${this.shortSelector(selector)} \u2014 ${msg}`);
     }
   }
-  async getText(selector, frame) {
+  /**
+   * Get the text content of an element. Returns null if not found (soft fail).
+   *
+   * @param selector - CSS selector or XPath
+   * @param options.waitTimeout - Max wait time for element to appear in ms (default: 0 — instant)
+   * @param options.frame - Optional Frame to search within
+   * @returns Trimmed text content, or null if element not found
+   *
+   * @example
+   * const price = await utils.getText(".price");
+   * const el = await utils.getText(".lazy-el", { waitTimeout: 8000 });
+   */
+  async getText(selector, options) {
+    var _a, _b;
     try {
       this.checkAbort();
       await this.log("debug", `\u{1F4C4} getText: ${this.shortSelector(selector)}`);
-      const scope = frame != null ? frame : this.ctx.page;
-      const element = await this.waitForElement(selector, 1e4, frame);
+      const scope = (_b = (_a = options == null ? void 0 : options.frame) != null ? _a : this.activeFrame) != null ? _b : this.activePage;
+      const element = await this.resolveElement(selector, options == null ? void 0 : options.waitTimeout, options == null ? void 0 : options.frame);
       if (!element) return null;
       const text = await scope.evaluate(
         (el) => {
-          var _a;
-          return ((_a = el.textContent) == null ? void 0 : _a.trim()) || "";
+          var _a2;
+          return ((_a2 = el.textContent) == null ? void 0 : _a2.trim()) || "";
         },
         element
       );
@@ -16942,158 +17668,636 @@ var BrowserUtils = class {
       return null;
     }
   }
-  async exists(selector, timeout = 3e3, frame) {
+  /**
+   * Check if an element exists and is visible on the page.
+   * Returns false if not found (soft fail — does NOT throw).
+   *
+   * @param selector - CSS selector or XPath
+   * @param timeout - Max wait time in ms (default: 4000)
+   * @param frame - Optional Frame to search within
+   * @returns true if element exists and is visible
+   *
+   * @example
+   * if (await utils.exists("#popup-overlay")) {
+   *   await utils.click("#close-popup");
+   * }
+   */
+  async exists(selector, timeout = 4e3, frame) {
     this.checkAbort();
     const el = await this.waitForElement(selector, timeout, frame);
     return el !== null;
   }
+  /**
+   * Navigate the active page to a URL. Waits until the page fully loads.
+   * Throws on navigation failure or timeout.
+   *
+   * @param url - The URL to navigate to
+   * @param options.waitUntil - When to consider navigation complete (default: "load")
+   * @returns true on success
+   *
+   * @example
+   * await utils.goto("https://example.com");
+   * await utils.goto("https://app.com", { waitUntil: "networkidle0" });
+   */
   async goto(url2, options) {
     try {
       this.checkAbort();
       await this.log("info", `\u{1F310} Navigate \u2192 ${url2}`);
-      await this.ctx.page.goto(url2, {
-        waitUntil: (options == null ? void 0 : options.waitUntil) || "domcontentloaded",
-        timeout: 3e4
+      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;
+      const msg = error instanceof Error ? error.message : String(error);
+      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("error", `\u274C Navigate failed: ${url2} \u2014 ${msg}`);
+      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.
+   *
+   * @param options.timeout - Max wait time in ms (default: 60000)
+   * @param options.waitUntil - When to consider navigation complete (default: "load")
+   * @returns true on success
+   *
+   * @example
+   * await utils.click("#submit");
+   * await utils.waitForNavigation();
+   */
   async waitForNavigation(options) {
     try {
       this.checkAbort();
       await this.log("debug", "\u{1F504} Waiting for navigation...");
-      await this.ctx.page.waitForNavigation({
-        timeout: (options == null ? void 0 : options.timeout) || 3e4,
-        waitUntil: (options == null ? void 0 : options.waitUntil) || "domcontentloaded"
+      await this.activePage.waitForNavigation({
+        timeout: (options == null ? void 0 : options.timeout) || 16e3,
+        waitUntil: (options == null ? void 0 : options.waitUntil) || "load"
       });
       return true;
     } catch (err) {
       if (err instanceof Error && err.message === "cancelled") throw err;
-      await this.log("warn", "\u26A0\uFE0F Navigation timeout");
-      return false;
+      throw new Error("Navigation timeout");
     }
   }
+  /**
+   * Take a screenshot of the active page. Returns null on failure (soft fail).
+   *
+   * @param path - Optional file path to save the screenshot. If omitted, returns base64 string.
+   * @returns Screenshot buffer (if path given) or base64 string, or null on failure
+   *
+   * @example
+   * await utils.screenshot("./debug.png");        // save to file
+   * const base64 = await utils.screenshot();       // get base64
+   */
   async screenshot(path2) {
     try {
       this.checkAbort();
       await this.log("info", `\u{1F4F8} Screenshot${path2 ? `: ${path2}` : ""}`);
-      return path2 ? await this.ctx.page.screenshot({ path: path2 }) : await this.ctx.page.screenshot({ encoding: "base64" });
+      return path2 ? await this.activePage.screenshot({ path: path2 }) : await this.activePage.screenshot({ encoding: "base64" });
     } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
       const msg = error instanceof Error ? error.message : String(error);
-      await this.log("error", `\u274C Screenshot failed \u2014 ${msg}`);
+      await this.log("warn", `\u26A0\uFE0F Screenshot failed \u2014 ${msg}`);
       return null;
     }
   }
-  async switchToPopup(matcher, timeout = 1e4) {
-    const label = typeof matcher === "string" ? matcher : matcher.toString();
+  /**
+   * Switch scope into an iframe within the current page.
+   * After switching, all methods (click, type, exists...) operate inside the iframe.
+   * Use `activeMainFrame()` to exit back to the main page.
+   * Throws if the iframe is not found.
+   *
+   * @param selector - CSS selector or XPath of the iframe element
+   * @param options.waitTimeout - Max wait time for iframe element to appear in ms (default: 0 — instant)
+   * @returns The Frame handle
+   *
+   * @example
+   * await utils.activeIframe("#my-iframe");
+   * await utils.click("#btn-inside-iframe");
+   * await utils.activeMainFrame();
+   */
+  async activeIframe(selector, options) {
+    try {
+      this.checkAbort();
+      await this.log("info", `\u{1F5BC}\uFE0F Active iframe: ${this.shortSelector(selector)}`);
+      const resolved = selector.startsWith("//") || selector.startsWith("(") ? `xpath/${selector}` : selector;
+      const el = (options == null ? void 0 : options.waitTimeout) && options.waitTimeout > 0 ? await this.activePage.waitForSelector(resolved, { timeout: options.waitTimeout }) : await this.activePage.$(resolved);
+      if (!el) {
+        throw new Error(`Iframe not found: ${this.shortSelector(selector)}`);
+      }
+      const frame = await el.contentFrame();
+      if (!frame) {
+        throw new Error(`Cannot get contentFrame from: ${this.shortSelector(selector)}`);
+      }
+      this.activeFrame = frame;
+      return frame;
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`activeIframe failed: ${this.shortSelector(selector)} \u2014 ${msg}`);
+    }
+  }
+  /**
+   * Exit the current iframe and return to the main frame of the active page.
+   * After calling this, all methods operate on the main page (outside any iframe).
+   *
+   * @example
+   * await utils.activeIframe("#my-iframe");
+   * await utils.click("#btn-in-iframe");
+   * await utils.activeMainFrame();  // back to main page
+   */
+  async activeMainFrame() {
+    this.checkAbort();
+    this.activeFrame = null;
+    await this.log("info", `\u{1F5BC}\uFE0F Switched to main frame`);
+  }
+  // ── Internal: tìm tab mới ─────────────────────────────────
+  async _findNewTab(opts) {
+    const { matcher, timeout = 8e3 } = opts != null ? opts : {};
+    const label = matcher ? typeof matcher === "string" ? matcher : matcher.toString() : "(any)";
     this.checkAbort();
-    await this.log("info", `\u{1F504} Switching to popup: ${label}`);
+    await this.log("info", `\u23F3 Waiting for new tab ${label}... (${timeout}ms)`);
+    const isMatch = (text) => {
+      if (!matcher) return true;
+      if (!text) return false;
+      if (typeof matcher === "string") return text.includes(matcher);
+      return matcher.test(text);
+    };
     try {
+      const currentCount = (await this.ctx.browser.pages()).length;
+      const start = Date.now();
+      while (Date.now() - start < timeout) {
+        const pages = await this.ctx.browser.pages();
+        if (pages.length > currentCount) {
+          for (let i = pages.length - 1; i >= currentCount; i--) {
+            const p = pages[i];
+            try {
+              await p.waitForNavigation({
+                waitUntil: "domcontentloaded",
+                timeout: 3e3
+              }).catch(() => {
+              });
+            } catch {
+            }
+            if (!matcher) {
+              await this.log("success", `\u2705 New tab detected \u2014 tab[${i}]`);
+              return p;
+            }
+            try {
+              const title = await p.title();
+              const url2 = p.url();
+              if (isMatch(title) || isMatch(url2)) {
+                await this.log("success", `\u2705 New tab matched: ${label} \u2014 tab[${i}]`);
+                return p;
+              }
+            } catch {
+            }
+          }
+        }
+        await new Promise((r) => setTimeout(r, 300));
+      }
+      throw new Error(`New tab not found: ${label} (timeout: ${timeout}ms)`);
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`waitForNewTab failed \u2014 ${msg}`);
+    }
+  }
+  // ── Internal: tìm popup đã có (hoặc chờ xuất hiện) ──────
+  async _findPopup(opts) {
+    const { matcher, timeout = 8e3 } = opts != null ? opts : {};
+    const label = matcher ? typeof matcher === "string" ? matcher : matcher.toString() : "(any new)";
+    this.checkAbort();
+    await this.log("info", `\u23F3 Waiting for popup ${label}... (${timeout}ms)`);
+    const isMatch = (text) => {
+      if (!matcher) return true;
+      if (!text) return false;
+      if (typeof matcher === "string") return text.includes(matcher);
+      return matcher.test(text);
+    };
+    try {
+      const currentPages = new Set((await this.ctx.browser.pages()).map((p) => p));
       const start = Date.now();
-      const isMatch = (text) => {
-        if (!text) return false;
-        if (typeof matcher === "string") return text.includes(matcher);
-        return matcher.test(text);
-      };
       while (Date.now() - start < timeout) {
         const pages = await this.ctx.browser.pages();
         for (let i = pages.length - 1; i >= 0; i--) {
           const page = pages[i];
-          const title = await page.title();
-          const url2 = page.url();
-          if (isMatch(title) || isMatch(url2)) {
-            await page.bringToFront();
-            return page;
+          if (!matcher && currentPages.has(page)) continue;
+          try {
+            const title = await page.title();
+            const url2 = page.url();
+            if (isMatch(title) || isMatch(url2)) {
+              await this.log("success", `\u2705 Popup found: ${label} \u2014 tab[${i}]`);
+              return page;
+            }
+          } catch {
           }
         }
         await new Promise((r) => setTimeout(r, 500));
       }
-      await this.log(
-        "warn",
-        `\u26A0\uFE0F Popup not found: ${label} (timeout: ${timeout}ms)`
-      );
-      return null;
+      throw new Error(`Popup not found: ${label} (timeout: ${timeout}ms)`);
     } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
       const msg = error instanceof Error ? error.message : String(error);
-      await this.log("error", `\u274C switchToPopup failed: ${label} \u2014 ${msg}`);
-      return null;
+      throw new Error(`waitForPopup failed: ${label} \u2014 ${msg}`);
+    }
+  }
+  /**
+   * Wait for a new tab to appear, but do NOT switch to it.
+   * The active page remains unchanged. Throws if no new tab appears before timeout.
+   *
+   * @param opts.matcher - String or RegExp to match the new tab's title or URL. If omitted, any new tab matches.
+   * @param opts.timeout - Max wait time in ms (default: 8000)
+   * @returns The new Page handle (without switching)
+   *
+   * @example
+   * await utils.click("#open-link");
+   * const page = await utils.waitForNewTab();
+   * const page = await utils.waitForNewTab({ timeout: 20000 });
+   * const page = await utils.waitForNewTab({ matcher: "Google" });
+   */
+  async waitForNewTab(opts) {
+    return this._findNewTab(opts);
+  }
+  /**
+   * Switch to a new tab immediately (or wait if timeout is specified).
+   * After calling this, all methods operate on the new tab.
+   * Use `activeDefault()` to return to the original tab.
+   *
+   * @param opts.matcher - String or RegExp to match the new tab's title or URL
+   * @param opts.timeout - Max wait time in ms (default: 0 — instant, throws if not found)
+   * @returns The new Page handle (now active)
+   *
+   * @example
+   * await utils.click("#open-link");
+   * await utils.activeNewTab();                          // switch immediately
+   * await utils.activeNewTab({ timeout: 8000 });         // wait up to 8s
+   * await utils.type("#input", "hello");                  // types on the new tab
+   * await utils.activeDefault();                          // back to original tab
+   */
+  async activeNewTab(opts) {
+    var _a;
+    const page = await this._findNewTab({ ...opts, timeout: (_a = opts == null ? void 0 : opts.timeout) != null ? _a : 0 });
+    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;
+  }
+  /**
+   * Wait for a popup/tab matching the given criteria to appear, but do NOT switch to it.
+   * Throws if no matching popup appears before timeout.
+   *
+   * @param opts.matcher - String or RegExp to match title or URL. If omitted, any new popup matches.
+   * @param opts.timeout - Max wait time in ms (default: 8000)
+   * @returns The popup Page handle (without switching)
+   *
+   * @example
+   * await utils.click("#connect-wallet");
+   * const popup = await utils.waitForPopup({ matcher: "MetaMask" });
+   */
+  async waitForPopup(opts) {
+    return this._findPopup(opts);
+  }
+  /**
+   * Switch to a popup/tab immediately (or wait if timeout is specified).
+   * After calling this, all methods operate on the popup.
+   * Use `activeDefault()` to return to the original tab.
+   *
+   * @param opts.matcher - String or RegExp to match title or URL
+   * @param opts.timeout - Max wait time in ms (default: 0 — instant, throws if not found)
+   * @returns The popup Page handle (now active)
+   *
+   * @example
+   * await utils.click("#connect-wallet");
+   * await utils.activePopup({ matcher: "MetaMask" });
+   * await utils.click("#approve");         // clicks on the popup
+   * await utils.activeDefault();            // back to original tab
+   */
+  async activePopup(opts) {
+    var _a;
+    const page = await this._findPopup({ ...opts, timeout: (_a = opts == null ? void 0 : opts.timeout) != null ? _a : 0 });
+    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;
   }
-  async switchToTabIndex(index) {
+  /**
+   * Switch focus to a tab by its index (0-based, ordered by creation time).
+   * All subsequent methods (click, type, goto...) will operate on this tab.
+   * User interactions (opening tabs, clicking browser) do NOT affect the active tab.
+   * Throws if the index is out of range.
+   *
+   * @param index - Zero-based tab index
+   * @returns The Page handle of the activated tab
+   *
+   * @example
+   * await utils.activeTab(1);        // switch to second tab
+   * await utils.click("#btn");       // clicks on tab 1
+   * await utils.activeTab(0);        // back to first tab
+   */
+  async activeTab(index) {
     try {
       this.checkAbort();
-      await this.log("info", `\u{1F504} Switching to tab[${index}]...`);
+      await this.log("info", `\u{1F504} Active tab[${index}]...`);
       const pages = await this.ctx.browser.pages();
       if (index >= 0 && index < pages.length) {
         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;
       }
-      await this.log(
-        "warn",
-        `\u26A0\uFE0F Tab[${index}] not found (total: ${pages.length})`
-      );
-      return null;
-    } catch {
-      return null;
+      throw new Error(`Tab[${index}] not found (total: ${pages.length})`);
+    } catch (error) {
+      if (error instanceof Error && error.message === "cancelled") throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`activeTab failed \u2014 ${msg}`);
     }
   }
+  /**
+   * Close the currently active tab and switch back to the default page.
+   *
+   * @example
+   * await utils.activeTab(1);
+   * await utils.closeCurrentTab();  // closes tab 1, returns to tab 0
+   */
   async closeCurrentTab() {
-    try {
-      this.checkAbort();
-      if (!this.ctx.page.isClosed()) {
-        await this.log("info", `\u{1F5D1}\uFE0F Closing tab: ${this.ctx.page.url()}`);
-        await this.ctx.page.close();
-      }
-    } catch {
+    this.checkAbort();
+    if (!this.activePage.isClosed()) {
+      await this.log("info", `\u{1F5D1}\uFE0F Closing tab: ${this.activePage.url()}`);
+      await this.activePage.close();
+      this.activePage = this.defaultPage;
     }
   }
+  /**
+   * Close all tabs except the currently active one.
+   *
+   * @example
+   * await utils.closeOtherTabs();  // keeps only the active tab open
+   */
   async closeOtherTabs() {
-    try {
-      this.checkAbort();
-      const pages = await this.ctx.browser.pages();
-      const toClose = pages.filter((p) => p !== this.ctx.page && !p.isClosed());
-      await this.log("info", `\u{1F5D1}\uFE0F Closing ${toClose.length} other tab(s)...`);
-      await Promise.all(toClose.map((p) => p.close()));
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error);
-      await this.log("error", `\u274C closeOtherTabs failed \u2014 ${msg}`);
-    }
+    this.checkAbort();
+    const pages = await this.ctx.browser.pages();
+    const toClose = pages.filter((p) => p !== this.activePage && !p.isClosed());
+    await this.log("info", `\u{1F5D1}\uFE0F Closing ${toClose.length} other tab(s)...`);
+    await Promise.all(toClose.map((p) => p.close()));
   }
   /**
-   * Close ALL tabs (including the current one).
-   * Useful for full cleanup before flow ends.
+   * Close ALL tabs including the current one.
+   * Useful for full cleanup before a flow ends.
+   *
+   * @example
+   * await utils.closeAllTabs();
    */
   async closeAllTabs() {
-    try {
-      this.checkAbort();
-      const pages = await this.ctx.browser.pages();
-      const toClose = pages.filter((p) => !p.isClosed());
-      await this.log("info", `\u{1F5D1}\uFE0F Closing all ${toClose.length} tab(s)...`);
-      await Promise.all(toClose.map((p) => p.close()));
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error);
-      await this.log("error", `\u274C closeAllTabs failed \u2014 ${msg}`);
-    }
+    this.checkAbort();
+    const pages = await this.ctx.browser.pages();
+    const toClose = pages.filter((p) => !p.isClosed());
+    await this.log("info", `\u{1F5D1}\uFE0F Closing all ${toClose.length} tab(s)...`);
+    await Promise.all(toClose.map((p) => p.close()));
   }
   /**
-   * Switch back to the default (initial) page — the page stored in context.
-   * Typically used after switchToPopup() to return to the main tab.
+   * Switch back to the default (initial) tab — the first tab opened when the flow started.
+   * Resets both the active page and active frame (exits any iframe).
+   * Typically used after `activePopup()` or `activeTab()` to return to the main tab.
+   *
+   * @returns The default Page handle
+   *
+   * @example
+   * await utils.activePopup({ matcher: "MetaMask" });
+   * await utils.click("#approve");
+   * await utils.activeDefault();  // back to original tab
    */
-  async switchToDefault() {
+  async activeDefault() {
     this.checkAbort();
-    await this.log("info", `\u{1F504} Switching to default page: ${this.ctx.page.url()}`);
-    if (!this.ctx.page.isClosed()) {
-      await this.ctx.page.bringToFront();
+    await this.log("info", `\u{1F504} Switching to default page...`);
+    if (!this.defaultPage.isClosed()) {
+      await this.defaultPage.bringToFront();
+      await this.enableFocusEmulation(this.defaultPage);
     }
-    return this.ctx.page;
+    this.activePage = this.defaultPage;
+    this.activeFrame = null;
+    await this.hiraCursor.inject(this.activePage);
+    return this.activePage;
   }
+  /**
+   * Log a config object in a readable format.
+   *
+   * @param config - Key-value object to log
+   * @param label - Label for the log entry (default: "Config")
+   */
   async logConfig(config, label = "Config") {
     const lines = Object.entries(config).map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`).join(",\n");
     await this.log("info", `\u{1F4CB} ${label}:
@@ -17101,6 +18305,7 @@ var BrowserUtils = class {
 ${lines}
 }`);
   }
+  /** Log the current profile input values for debugging. */
   async logProfileInput() {
     await this.logConfig(
       this.ctx.profileInput,
@@ -17108,8 +18313,8 @@ ${lines}
     );
   }
   /**
-   * Log toàn bộ output hiện tại (bao gồm cả giá trị từ lần chạy trước và giá trị mới ghi).
-   * Dùng để debug — xem giá trị output hiện tại.
+   * Log all current output values (including values from previous runs and newly written values).
+   * Useful for debugging — see what outputs have been set.
    */
   async logProfileOutput() {
     const output = this.ctx.output;
@@ -17120,6 +18325,7 @@ ${lines}
     }
     await this.logConfig(output, "Profile Output");
   }
+  /** Log the current global input values for debugging. */
   async logGlobalInput() {
     await this.logConfig(
       this.ctx.globalInput,
@@ -17127,16 +18333,24 @@ ${lines}
     );
   }
   /**
-   * Ghi kết quả tự do cho profile đang chạy.
-   * Gửi qua kênh riêng (type: "profile_output") — không lẫn log.
-   * Đồng thời log ra console/UI để flow dev dễ debug.
+   * Write an output value for the current profile.
+   * Dispatched via a dedicated channel (type: "profile_output") — separate from logs.
+   * Also logs the value to console/UI for debugging.
+   *
+   * ⚠️ Key must be defined in `config.output[]` — throws Error if invalid.
    *
-   * ⚠️ Key phải được định nghĩa trong config.output[] — nếu không sẽ throw Error.
+   * Accepted value types:
+   * - `string | number | boolean`
+   * - `Array` (max 20 elements, each must be primitive)
+   * - `Object` (max 10 entries, values must be primitive)
    *
-   * value hợp lệ:
-   * - string | number | boolean
-   * - array tối đa 20 phần tử (primitive)
-   * - object 1 cấp tối đa 10 entry (value phải là primitive)
+   * @param key - Output key (must match config.output definition)
+   * @param value - The value to write
+   *
+   * @example
+   * await utils.writeOutput("status", "success");
+   * await utils.writeOutput("balance", 1234.56);
+   * await utils.writeOutput("tokens", ["ETH", "USDT"]);
    */
   async writeOutput(key, value) {
     this.checkAbort();
@@ -17157,9 +18371,16 @@ ${lines}
     });
   }
   /**
-   * Cập nhật lại một field trong profileInput của profile đang chạy.
-   * key phải là field đã được định nghĩa trong profileInput schema.
-   * Kết quả được gửi về server để update AgentFlowConfig sau khi execution xong.
+   * Update a profile input field for the currently running profile.
+   * The key must be defined in the profileInput schema.
+   * The updated value is sent to the server to persist in AgentFlowConfig after execution.
+   *
+   * @param key - Profile input key (must match schema definition)
+   * @param value - The new value (string, number, or boolean)
+   *
+   * @example
+   * await utils.writeProfileInput("lastLoginDate", "2024-01-15");
+   * await utils.writeProfileInput("retryCount", 3);
    */
   async writeProfileInput(key, value) {
     this.checkAbort();