@hira-core/sdk 1.0.5 → 1.0.7

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _packages_shared from '@packages/shared';
 import { ProfileOutputValue, IWorkerLogMessage, ProfileStatus, IWorkerOutputMessage } from '@packages/shared';
-import * as puppeteer from 'puppeteer-core';
+import * as puppeteer_core from 'puppeteer-core';
 import { Browser, Page, Frame, ElementHandle } from 'puppeteer-core';
 import { EventEmitter } from 'events';
 
@@ -521,8 +521,8 @@ declare class GpmStandaloneAdapter implements IBrowserAdapter {
     constructor(logger: ILogger);
     private getBoundLogger;
     open(profileName: string, index: number, windowConfig: IBrowserWindowConfig): Promise<{
-        browser: puppeteer.Browser;
-        page: puppeteer.Page;
+        browser: puppeteer_core.Browser;
+        page: puppeteer_core.Page;
         profile: IAntidetectProfile;
     }>;
     close(profileId: string): Promise<void>;
@@ -595,8 +595,8 @@ declare class HidemiumStandaloneAdapter implements IBrowserAdapter {
     constructor(logger: ILogger);
     private getBoundLogger;
     open(profileName: string, index: number, windowConfig: IBrowserWindowConfig): Promise<{
-        browser: puppeteer.Browser;
-        page: puppeteer.Page;
+        browser: puppeteer_core.Browser;
+        page: puppeteer_core.Page;
         profile: IAntidetectProfile;
     }>;
     close(profileId: string): Promise<void>;
@@ -606,72 +606,370 @@ declare class HidemiumStandaloneAdapter implements IBrowserAdapter {
 declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
     private ctx;
     private logger;
-    /** Output definitions từ flow config — dùng để validate writeOutput key */
+    /** Output definitions from flow config — used to validate writeOutput keys */
     private readonly outputDefs;
-    /** Set chứa các key hợp lệ — build 1 lần từ outputDefs */
+    /** Valid output keys set — built once from outputDefs */
     private readonly validOutputKeys;
+    /** The initial page when flow starts — activeDefault() returns here */
+    private readonly defaultPage;
+    /** The currently active page all methods operate on — changed via activeTab() */
+    private activePage;
+    /** Currently active iframe — null means main frame. Changed via activeIframe() */
+    private activeFrame;
     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.
+     */
+    private enableFocusEmulation;
     private checkAbort;
+    /**
+     * Pause execution for the given duration.
+     *
+     * @param ms - Duration in milliseconds
+     * @example await utils.sleep(2000); // wait 2 seconds
+     */
     sleep(ms: number): Promise<void>;
+    /**
+     * 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();
+     */
     waitForElement(selector: string, timeout?: number, scope?: Frame): Promise<ElementHandle | null>;
+    /**
+     * Resolve an element: if waitTimeout > 0, wait for it; otherwise query directly with $().
+     */
+    private resolveElement;
+    /**
+     * Click on an element. Scrolls the element into view before clicking.
+     * Throws if the element is not found.
+     *
+     * @param target - CSS selector, XPath, or an existing ElementHandle
+     * @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("#btn", { waitTimeout: 8000 });     // wait longer
+     */
     click(target: string | ElementHandle, options?: {
         delay?: number;
-        timeout?: number;
+        waitTimeout?: number;
         frame?: Frame;
     }): Promise<boolean>;
+    /**
+     * 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
+     */
     type(selector: string, text: string, options?: {
+        /** Typing mode: replace (default) = clear then type, append = type without clearing, paste = set value directly */
+        mode?: "replace" | "append" | "paste";
         delay?: number;
+        waitTimeout?: number;
         frame?: Frame;
     }): Promise<boolean>;
-    getText(selector: string, frame?: Frame): Promise<string | null>;
+    /**
+     * 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 });
+     */
+    getText(selector: string, options?: {
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<string | null>;
+    /**
+     * 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");
+     * }
+     */
     exists(selector: string, timeout?: number, frame?: Frame): Promise<boolean>;
+    /**
+     * 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" });
+     */
     goto(url: string, options?: {
         waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
     }): Promise<boolean>;
+    /**
+     * 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();
+     */
     waitForNavigation(options?: {
         timeout?: number;
         waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
     }): Promise<boolean>;
+    /**
+     * 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
+     */
     screenshot(path?: string): Promise<unknown>;
-    switchToPopup(matcher: string | RegExp, timeout?: number): Promise<puppeteer.Page | null>;
-    switchToTabIndex(index: number): Promise<puppeteer.Page | null>;
+    /**
+     * 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();
+     */
+    activeIframe(selector: string, options?: {
+        waitTimeout?: number;
+    }): Promise<Frame | null>;
+    /**
+     * 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
+     */
+    activeMainFrame(): Promise<void>;
+    private _findNewTab;
+    private _findPopup;
+    /**
+     * 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" });
+     */
+    waitForNewTab(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * 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
+     */
+    activeNewTab(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * 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" });
+     */
+    waitForPopup(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * 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
+     */
+    activePopup(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * 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
+     */
+    activeTab(index: number): Promise<puppeteer_core.Page | null>;
+    /**
+     * 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
+     */
     closeCurrentTab(): Promise<void>;
+    /**
+     * Close all tabs except the currently active one.
+     *
+     * @example
+     * await utils.closeOtherTabs();  // keeps only the active tab open
+     */
     closeOtherTabs(): Promise<void>;
     /**
-     * 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();
      */
     closeAllTabs(): Promise<void>;
     /**
-     * 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
+     */
+    activeDefault(): Promise<puppeteer_core.Page>;
+    /**
+     * Log a config object in a readable format.
+     *
+     * @param config - Key-value object to log
+     * @param label - Label for the log entry (default: "Config")
      */
-    switchToDefault(): Promise<puppeteer.Page>;
     logConfig(config: Record<string, unknown>, label?: string): Promise<void>;
+    /** Log the current profile input values for debugging. */
     logProfileInput(): Promise<void>;
     /**
-     * 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.
      */
     logProfileOutput(): Promise<void>;
+    /** Log the current global input values for debugging. */
     logGlobalInput(): Promise<void>;
     /**
-     * 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.
+     *
+     * Accepted value types:
+     * - `string | number | boolean`
+     * - `Array` (max 20 elements, each must be primitive)
+     * - `Object` (max 10 entries, values must be primitive)
      *
-     * ⚠️ Key phải được định nghĩa trong config.output[] — nếu không sẽ throw Error.
+     * @param key - Output key (must match config.output definition)
+     * @param value - The value to write
      *
-     * 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)
+     * @example
+     * await utils.writeOutput("status", "success");
+     * await utils.writeOutput("balance", 1234.56);
+     * await utils.writeOutput("tokens", ["ETH", "USDT"]);
      */
     writeOutput(key: InferOutputKeys<TConfig>, value: ProfileOutputValue): Promise<void>;
     /**
-     * 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);
      */
     writeProfileInput(key: InferProfileInputKeys<TConfig>, value: string | number | boolean): Promise<void>;
     private sanitizeOutputValue;

package/dist/index.js

@@ -16631,10 +16631,16 @@ var HidemiumStandaloneAdapter = class {
     profileLogger.info(`\u{1F310} Opening Hidemium profile: ${profileName}`);
     this.pendingProfiles.add(profileName);
     try {
-      const profiles = await this.service.getProfiles({
+      let profiles = await this.service.getProfiles({
         search: profileName
-      });
-      const targetProfile = profiles.find((p) => p.name === profileName);
+      }, true);
+      let targetProfile = profiles.find((p) => p.name === profileName);
+      if (!targetProfile) {
+        profiles = await this.service.getProfiles({
+          search: profileName
+        });
+        targetProfile = profiles.find((p) => p.name === profileName);
+      }
       if (!targetProfile) {
         throw new Error(`Profile not found: ${profileName}`);
       }
@@ -16648,7 +16654,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);
@@ -16712,8 +16721,14 @@ var HidemiumStandaloneAdapter = class {
           this.logger.log(`\u{1F512} Closing pending profile: ${profileName}`);
           const profiles = await this.service.getProfiles({
             search: profileName
-          });
-          const target = profiles.find((p) => p.name === profileName);
+          }, true);
+          let target = profiles.find((p) => p.name === profileName);
+          if (!target) {
+            const allProfiles = await this.service.getProfiles({
+              search: profileName
+            });
+            target = allProfiles.find((p) => p.name === profileName);
+          }
           if (target) {
             await this.service.stopProfile(target.uuid);
           }
@@ -16800,22 +16815,61 @@ function getSdkConfig() {
 // 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;
     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;
+    this.enableFocusEmulation(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.
+   */
+  async enableFocusEmulation(page) {
+    try {
+      const cdp = await page.createCDPSession();
+      await cdp.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    } catch {
+    }
   }
   checkAbort() {
     const signal = global.__HIRA_ABORT_SIGNAL__;
     if (signal == null ? void 0 : signal.aborted) throw new Error("cancelled");
   }
+  /**
+   * 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 };
@@ -16832,7 +16886,35 @@ 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. Scrolls the element into view before clicking.
+   * Throws if the element is not found.
+   *
+   * @param target - CSS selector, XPath, or an existing ElementHandle
+   * @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("#btn", { waitTimeout: 8000 });     // wait longer
+   */
   async click(target, options) {
+    var _a, _b;
     const label = typeof target === "string" ? target : "[ElementHandle]";
     try {
       this.checkAbort();
@@ -16841,82 +16923,116 @@ var BrowserUtils = class {
       if (typeof target === "string") {
         element = await this.waitForElement(
           target,
-          options == null ? void 0 : options.timeout,
+          (_a = options == null ? void 0 : options.waitTimeout) != null ? _a : 2e3,
           options == null ? void 0 : options.frame
         );
       } 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 element.scrollIntoView();
-      if (options == null ? void 0 : options.delay) await this.sleep(options.delay);
+      const clickDelay = (_b = options == null ? void 0 : options.delay) != null ? _b : 1e3;
+      if (clickDelay > 0) await this.sleep(clickDelay);
       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);
-      await this.log(
-        "error",
-        `\u274C Click failed: ${this.shortSelector(label)} \u2014 ${msg}`
-      );
-      return false;
+      throw new Error(`Click failed: ${this.shortSelector(label)} \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)}`
-        );
-        return false;
+        throw new Error(`Type failed \u2014 element not found: ${this.shortSelector(selector)}`);
       }
       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 });
+      if (mode === "paste") {
+        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
+        );
+      } else if (mode === "append") {
+        await element.click();
+        await element.type(text, { delay: (_c = options == null ? void 0 : options.delay) != null ? _c : 50 });
+      } else {
+        await element.click({ clickCount: 3 });
+        await element.press("Backspace");
+        await element.type(text, { delay: (_d = options == null ? void 0 : options.delay) != null ? _d : 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
       );
@@ -16930,158 +17046,432 @@ 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
+      await this.activePage.goto(url2, {
+        waitUntil: (options == null ? void 0 : options.waitUntil) || "load",
+        timeout: 6e4
       });
       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}`);
-      return false;
+      throw new Error(`Navigate failed: ${url2} \u2014 ${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);
+      this.activePage = page;
+      this.activeFrame = null;
+    }
+    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);
+      this.activePage = page;
+      this.activeFrame = null;
     }
+    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);
+        this.activePage = page;
+        this.activeFrame = null;
         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;
+    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}:
@@ -17089,6 +17479,7 @@ var BrowserUtils = class {
 ${lines}
 }`);
   }
+  /** Log the current profile input values for debugging. */
   async logProfileInput() {
     await this.logConfig(
       this.ctx.profileInput,
@@ -17096,8 +17487,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;
@@ -17108,6 +17499,7 @@ ${lines}
     }
     await this.logConfig(output, "Profile Output");
   }
+  /** Log the current global input values for debugging. */
   async logGlobalInput() {
     await this.logConfig(
       this.ctx.globalInput,
@@ -17115,16 +17507,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();
@@ -17145,9 +17545,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hira-core/sdk",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "SDK for building Hira automation flows with TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,10 +26,6 @@
   ],
   "author": "tttKiet",
   "homepage": "https://hira-sdk.vercel.app/",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tttKiet/hira-automation"
-  },
   "license": "ISC",
   "engines": {
     "node": ">=18.0.0"