@skrillex1224/playwright-toolkit 2.1.225 → 2.1.227

package/dist/index.cjs

@@ -2148,7 +2148,7 @@ var Humanize = {
   },
   /**
    * 初始化页面的 Ghost Cursor（必须在使用其他 cursor 相关方法前调用）
-   * 
+   *
    * @param {import('playwright').Page} page
    * @returns {Promise<void>}
    */
@@ -2164,7 +2164,7 @@ var Humanize = {
   },
   /**
    * 人类化鼠标移动 - 使用 ghost-cursor 移动到指定位置或元素
-   * 
+   *
    * @param {import('playwright').Page} page
    * @param {string|{x: number, y: number}|import('playwright').ElementHandle} target - CSS选择器、坐标对象或元素句柄
    */
@@ -2206,7 +2206,7 @@ var Humanize = {
   /**
    * 渐进式滚动到元素可见（仅处理 Y 轴滚动）
    * 返回 restore 方法，用于将滚动容器恢复到原位置
-   * 
+   *
    * @param {import('playwright').Page} page
    * @param {string|import('playwright').ElementHandle} target - CSS 选择器或元素句柄
    * @param {Object} [options]
@@ -2277,7 +2277,7 @@ var Humanize = {
         return { code: "VISIBLE", isFixed };
       });
     };
-    const getScrollableRect = async () => {
+    const getScrollableRect2 = async () => {
       return await element.evaluate((el) => {
         const isScrollable = (node) => {
           const style = window.getComputedStyle(node);
@@ -2320,7 +2320,7 @@ var Humanize = {
         if (status.code === "OBSTRUCTED" && status.obstruction) {
           logger6.debug(`humanScroll | \u88AB\u4EE5\u4E0B\u5143\u7D20\u906E\u6321 <${status.obstruction.tag} id="${status.obstruction.id}">`);
         }
-        const scrollRect = await getScrollableRect();
+        const scrollRect = await getScrollableRect2();
         if (!scrollRect && status.isFixed) {
           logger6.warn("humanScroll | fixed \u5BB9\u5668\u5185\u4E14\u65E0\u53EF\u6EDA\u52A8\u7956\u5148\uFF0C\u8DF3\u8FC7\u6EDA\u52A8");
           return { element, didScroll };
@@ -2367,7 +2367,7 @@ var Humanize = {
   },
   /**
    * 人类化点击 - 使用 ghost-cursor 模拟人类鼠标移动轨迹并点击
-   * 
+   *
    * @param {import('playwright').Page} page
    * @param {string|import('playwright').ElementHandle} [target] - CSS 选择器或元素句柄。如果为空，则点击当前鼠标位置
    * @param {Object} [options]
@@ -2428,9 +2428,7 @@ var Humanize = {
       const y = box.y + box.height / 2 + (Math.random() - 0.5) * box.height * 0.3;
       await cursor.actions.move({ x, y });
       await (0, import_delay.default)(this.jitterMs(reactionDelay, 0.4));
-      await page.mouse.click(x, y, {
-        delay: this.jitterMs(45, 0.45)
-      });
+      await cursor.actions.click();
       await restoreOnce();
       logger6.success("humanClick");
       return true;
@@ -2475,7 +2473,7 @@ var Humanize = {
    * @param {import('playwright').Page} page
    * @param {string} selector - 输入框选择器
    * @param {string} text - 要输入的文本
-   * @param {Object} [options]     
+   * @param {Object} [options]
    * @param {number} [options.baseDelay=180] - 基础按键延迟 (ms)，实际 ±40% 抖动
    * @param {number} [options.pauseProbability=0.08] - 停顿概率 (0-1)
    * @param {number} [options.pauseBase=800] - 停顿时长基础值 (ms)，实际 ±50% 抖动
@@ -2515,6 +2513,43 @@ var Humanize = {
       throw error;
     }
   },
+  /**
+   * 人类化按键 - 模拟用户在当前焦点或指定目标上按下一次键。
+   * @param {import('playwright').Page} page
+   * @param {string|import('playwright').ElementHandle|import('playwright').Locator} targetOrKey - 目标或按键
+   * @param {string|Object} [maybeKey] - 按键或选项
+   * @param {Object} [options]
+   */
+  async humanPress(page, targetOrKey, maybeKey, options = {}) {
+    const hasTarget = typeof maybeKey === "string";
+    const key = hasTarget ? maybeKey : targetOrKey;
+    const pressOptions = hasTarget ? options : maybeKey || options;
+    const {
+      reactionDelay = 180,
+      holdDelay = 45,
+      focusDelay = 180,
+      scrollIfNeeded = true,
+      throwOnMissing = true,
+      keyboardOptions = {}
+    } = pressOptions || {};
+    const targetDesc = hasTarget ? typeof targetOrKey === "string" ? targetOrKey : "ElementHandle" : "current focus";
+    logger6.start("humanPress", `key=${key}, target=${targetDesc}`);
+    try {
+      if (hasTarget) {
+        await this.humanClick(page, targetOrKey, { reactionDelay: focusDelay, scrollIfNeeded, throwOnMissing });
+      }
+      await (0, import_delay.default)(this.jitterMs(reactionDelay, 0.45));
+      await page.keyboard.press(key, {
+        ...keyboardOptions,
+        delay: this.jitterMs(holdDelay, 0.5)
+      });
+      logger6.success("humanPress");
+      return true;
+    } catch (error) {
+      logger6.fail("humanPress", error);
+      throw error;
+    }
+  },
   /**
    * 人类化清空输入框 - 模拟人类删除文本的行为
    * @param {import('playwright').Page} page
@@ -2603,6 +2638,141 @@ var Humanize = {
   }
 };
 
+// src/internals/humanize/machine.js
+var resolveDeviceFromPage = (page) => normalizeDevice(page?.[PageRuntimeStateKey]?.device);
+var isPoint = (value) => value && typeof value === "object" && Number.isFinite(Number(value.x)) && Number.isFinite(Number(value.y));
+var resolveNativeTarget = (page, target) => {
+  if (!target) return null;
+  if (typeof target === "string") {
+    return page.locator(target);
+  }
+  return target;
+};
+var normalizeSelectorOptions = (options = {}) => ({
+  targetParent: Boolean(options.targetParent ?? options.parent ?? false),
+  pick: options.pick === "last" || options.last ? "last" : "first",
+  visibleOnly: options.visibleOnly !== false,
+  fallbackDomClick: Boolean(options.fallbackDomClick),
+  forceMouse: Boolean(options.forceMouse)
+});
+var MachineHumanize = {
+  async clickPoint(page, pointOrX, maybeY, options = {}) {
+    const clickOptions = isPoint(pointOrX) && maybeY && typeof maybeY === "object" ? maybeY : options;
+    const point = isPoint(pointOrX) ? pointOrX : { x: pointOrX, y: maybeY };
+    const x = Number(point.x);
+    const y = Number(point.y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      throw new Error(`Invalid click point: ${JSON.stringify(point)}`);
+    }
+    const resolvedDevice = resolveDeviceFromPage(page);
+    if (resolvedDevice === Device.Mobile && !clickOptions.forceMouse && page.touchscreen && typeof page.touchscreen.tap === "function") {
+      await page.touchscreen.tap(x, y);
+      return true;
+    }
+    await page.mouse.click(x, y, clickOptions.mouseOptions || {});
+    return true;
+  },
+  async click(page, target, options = {}) {
+    if (isPoint(target)) {
+      return MachineHumanize.clickPoint(page, target, void 0, options);
+    }
+    const nativeTarget = resolveNativeTarget(page, target);
+    if (!nativeTarget || typeof nativeTarget.click !== "function") {
+      throw new Error("Machine click target does not expose click()");
+    }
+    await nativeTarget.click(options.clickOptions || options);
+    return true;
+  },
+  async focus(page, target, options = {}) {
+    const nativeTarget = resolveNativeTarget(page, target);
+    if (!nativeTarget || typeof nativeTarget.focus !== "function") {
+      throw new Error("Machine focus target does not expose focus()");
+    }
+    await nativeTarget.focus(options);
+    return true;
+  },
+  async fill(page, target, value, options = {}) {
+    const nativeTarget = resolveNativeTarget(page, target);
+    if (!nativeTarget || typeof nativeTarget.fill !== "function") {
+      throw new Error("Machine fill target does not expose fill()");
+    }
+    await nativeTarget.fill(value, options);
+    return true;
+  },
+  async keyboardType(page, text, options = {}) {
+    await page.keyboard.type(text, options);
+    return true;
+  },
+  async type(page, targetOrText, maybeText, options = {}) {
+    if (maybeText == null || typeof maybeText === "object" && !Array.isArray(maybeText)) {
+      return MachineHumanize.keyboardType(page, targetOrText, maybeText || options);
+    }
+    const nativeTarget = resolveNativeTarget(page, targetOrText);
+    if (!nativeTarget || typeof nativeTarget.type !== "function") {
+      throw new Error("Machine type target does not expose type()");
+    }
+    await nativeTarget.type(maybeText, options);
+    return true;
+  },
+  async selectorCenterPoint(page, selector, options = {}) {
+    const normalizedOptions = normalizeSelectorOptions(options);
+    return page.evaluate(({ innerSelector, innerOptions }) => {
+      const nodes = Array.from(document.querySelectorAll(innerSelector));
+      const ordered = innerOptions.pick === "last" ? nodes.reverse() : nodes;
+      let rect = null;
+      for (const node of ordered) {
+        if (!node) continue;
+        const target = innerOptions.targetParent ? node.parentElement || node : node;
+        rect = target.getBoundingClientRect?.() || null;
+        const isVisible = Boolean(rect && rect.width > 0 && rect.height > 0);
+        if (innerOptions.visibleOnly && !isVisible) continue;
+        break;
+      }
+      if (!rect || rect.width <= 0 || rect.height <= 0) return null;
+      return {
+        x: rect.left + rect.width / 2,
+        y: rect.top + rect.height / 2
+      };
+    }, { innerSelector: selector, innerOptions: normalizedOptions });
+  },
+  async domClick(page, selector, options = {}) {
+    const normalizedOptions = normalizeSelectorOptions(options);
+    return page.evaluate(({ innerSelector, innerOptions }) => {
+      const nodes = Array.from(document.querySelectorAll(innerSelector));
+      const ordered = innerOptions.pick === "last" ? nodes.reverse() : nodes;
+      let target = null;
+      for (const node of ordered) {
+        if (!node) continue;
+        const candidate = innerOptions.targetParent ? node.parentElement || node : node;
+        const rect = candidate.getBoundingClientRect?.() || null;
+        const isVisible = Boolean(rect && rect.width > 0 && rect.height > 0);
+        if (innerOptions.visibleOnly && !isVisible) continue;
+        target = candidate;
+        break;
+      }
+      if (!target || typeof target.click !== "function") return false;
+      target.click();
+      return true;
+    }, { innerSelector: selector, innerOptions: normalizedOptions });
+  },
+  async clickSelectorCenter(page, selector, options = {}) {
+    const normalizedOptions = normalizeSelectorOptions(options);
+    try {
+      const point = await MachineHumanize.selectorCenterPoint(page, selector, normalizedOptions);
+      if (point) {
+        await MachineHumanize.clickPoint(page, point, void 0, normalizedOptions);
+        return true;
+      }
+    } catch (error) {
+      if (!normalizedOptions.fallbackDomClick) throw error;
+    }
+    if (normalizedOptions.fallbackDomClick) {
+      return MachineHumanize.domClick(page, selector, normalizedOptions);
+    }
+    return false;
+  }
+};
+
 // src/internals/humanize/shared.js
 var import_delay2 = __toESM(require("delay"), 1);
 var jitterMs = (base, jitterPercent = 0.3) => {
@@ -2637,16 +2807,43 @@ var logger7 = createInternalLogger("Humanize.Mobile");
 var initializedPages = /* @__PURE__ */ new WeakSet();
 var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
 var resolveViewport = (page) => page?.viewportSize?.() || { width: 390, height: 844 };
+var describeTarget = (target) => {
+  if (target == null) return "Current Position";
+  return typeof target === "string" ? target : "ElementHandle";
+};
+var clipBoxToViewport = (box, viewport) => {
+  if (!box || !viewport) return box;
+  const left = clamp(box.x, 0, viewport.width);
+  const top = clamp(box.y, 0, viewport.height);
+  const right = clamp(box.x + box.width, 0, viewport.width);
+  const bottom = clamp(box.y + box.height, 0, viewport.height);
+  if (right - left > 1 && bottom - top > 1) {
+    return {
+      x: left,
+      y: top,
+      width: right - left,
+      height: bottom - top
+    };
+  }
+  return box;
+};
 var checkElementVisibility = async (element) => {
   return element.evaluate((el) => {
+    const targetStyle = window.getComputedStyle(el);
+    if (!targetStyle || targetStyle.display === "none" || targetStyle.visibility === "hidden" || targetStyle.visibility === "collapse") {
+      return { code: "NOT_INTERACTABLE", reason: "\u5143\u7D20\u4E0D\u53EF\u89C1", direction: "down" };
+    }
     const rect = el.getBoundingClientRect();
     if (!rect || rect.width <= 0 || rect.height <= 0) {
-      return { code: "ZERO_DIMENSIONS", direction: "down" };
+      return { code: "ZERO_DIMENSIONS", reason: "\u5C3A\u5BF8\u4E3A\u96F6", direction: "down" };
     }
     const viewW = window.innerWidth;
     const viewH = window.innerHeight;
-    const cx = rect.left + rect.width / 2;
-    const cy = rect.top + rect.height / 2;
+    const centerY = rect.top + rect.height / 2;
+    let clipLeft = 0;
+    let clipRight = viewW;
+    let clipTop = 0;
+    let clipBottom = viewH;
     let isFixed = false;
     for (let node = el; node && node !== document.body; node = node.parentElement) {
       const style = window.getComputedStyle(node);
@@ -2655,20 +2852,101 @@ var checkElementVisibility = async (element) => {
         break;
       }
     }
-    if ((isFixed ? cy < 0 || cy > viewH : cy < 12 || cy > viewH - 12) || cx < 0 || cx > viewW) {
+    for (let node = el.parentElement; node && node !== document.body; node = node.parentElement) {
+      const style = window.getComputedStyle(node);
+      if (!style) continue;
+      const clipsY = ["auto", "scroll", "overlay", "hidden", "clip"].includes(style.overflowY);
+      const clipsX = ["auto", "scroll", "overlay", "hidden", "clip"].includes(style.overflowX);
+      if (!clipsX && !clipsY) continue;
+      const nodeRect = node.getBoundingClientRect();
+      if (!nodeRect || nodeRect.width <= 0 || nodeRect.height <= 0) continue;
+      if (clipsX) {
+        clipLeft = Math.max(clipLeft, nodeRect.left);
+        clipRight = Math.min(clipRight, nodeRect.right);
+      }
+      if (clipsY) {
+        clipTop = Math.max(clipTop, nodeRect.top);
+        clipBottom = Math.min(clipBottom, nodeRect.bottom);
+      }
+    }
+    const visibleLeft = Math.max(clipLeft, Math.min(clipRight, rect.left));
+    const visibleRight = Math.max(clipLeft, Math.min(clipRight, rect.right));
+    const visibleTop = Math.max(clipTop, Math.min(clipBottom, rect.top));
+    const visibleBottom = Math.max(clipTop, Math.min(clipBottom, rect.bottom));
+    const visibleWidth = visibleRight - visibleLeft;
+    const visibleHeight = visibleBottom - visibleTop;
+    const cx = visibleLeft + visibleWidth / 2;
+    const cy = visibleTop + visibleHeight / 2;
+    if (visibleWidth <= 1 || visibleHeight <= 1) {
       return {
         code: "OUT_OF_VIEWPORT",
-        direction: cy < viewH / 2 ? "up" : "down",
-        cy,
+        reason: "\u4E0D\u5728\u89C6\u53E3\u5185",
+        direction: centerY < clipTop ? "up" : "down",
+        cy: centerY,
         viewH,
         isFixed
       };
     }
-    const pointElement = document.elementFromPoint(cx, cy);
-    if (pointElement && !el.contains(pointElement) && !pointElement.contains(el)) {
+    const interactiveSelector = [
+      "button",
+      '[role="button"]',
+      "a[href]",
+      "label",
+      "input",
+      "textarea",
+      "select",
+      "summary",
+      '[contenteditable="true"]',
+      '[tabindex]:not([tabindex="-1"])'
+    ].join(",");
+    const targetInteractive = typeof el.closest === "function" ? el.closest(interactiveSelector) : null;
+    const sameInteractiveTarget = (pointElement) => {
+      if (!pointElement) return false;
+      if (pointElement === el || el.contains(pointElement) || pointElement.contains(el)) {
+        return true;
+      }
+      if (!targetInteractive || typeof pointElement.closest !== "function") {
+        return false;
+      }
+      return pointElement.closest(interactiveSelector) === targetInteractive;
+    };
+    const describeElement = (node) => {
+      if (!node) return null;
+      const className = typeof node.className === "string" ? node.className : node.className && typeof node.className.baseVal === "string" ? node.className.baseVal : "";
+      const rect2 = node.getBoundingClientRect?.();
+      const style = window.getComputedStyle(node);
+      return {
+        tag: node.tagName,
+        id: node.id || "",
+        className,
+        isFixed: Boolean(style && (style.position === "fixed" || style.position === "sticky")),
+        top: rect2 ? rect2.top : null,
+        bottom: rect2 ? rect2.bottom : null,
+        left: rect2 ? rect2.left : null,
+        right: rect2 ? rect2.right : null
+      };
+    };
+    const samplePoints = [
+      { x: cx, y: cy },
+      { x: visibleLeft + Math.min(8, Math.max(1, visibleWidth * 0.25)), y: cy },
+      { x: visibleRight - Math.min(8, Math.max(1, visibleWidth * 0.25)), y: cy },
+      { x: cx, y: visibleTop + Math.min(8, Math.max(1, visibleHeight * 0.25)) },
+      { x: cx, y: visibleBottom - Math.min(8, Math.max(1, visibleHeight * 0.25)) }
+    ];
+    let obstruction = null;
+    for (const point of samplePoints) {
+      const pointElement = document.elementFromPoint(point.x, point.y);
+      if (sameInteractiveTarget(pointElement)) {
+        return { code: "VISIBLE", isFixed };
+      }
+      obstruction = obstruction || describeElement(pointElement);
+    }
+    if (obstruction) {
       return {
         code: "OBSTRUCTED",
+        reason: "\u88AB\u906E\u6321",
         direction: cy > viewH / 2 ? "down" : "up",
+        obstruction,
         cy,
         viewH,
         isFixed
@@ -2677,17 +2955,228 @@ var checkElementVisibility = async (element) => {
     return { code: "VISIBLE", isFixed };
   });
 };
+var resolveSafeTapPoint = async (element) => {
+  return element.evaluate((el) => {
+    const rect = el.getBoundingClientRect();
+    if (!rect || rect.width <= 0 || rect.height <= 0) {
+      return null;
+    }
+    const viewW = window.innerWidth;
+    const viewH = window.innerHeight;
+    let clipLeft = 0;
+    let clipRight = viewW;
+    let clipTop = 0;
+    let clipBottom = viewH;
+    for (let node = el.parentElement; node && node !== document.body; node = node.parentElement) {
+      const style = window.getComputedStyle(node);
+      if (!style) continue;
+      const clipsX = ["auto", "scroll", "overlay", "hidden", "clip"].includes(style.overflowX);
+      const clipsY = ["auto", "scroll", "overlay", "hidden", "clip"].includes(style.overflowY);
+      if (!clipsX && !clipsY) continue;
+      const nodeRect = node.getBoundingClientRect();
+      if (!nodeRect || nodeRect.width <= 0 || nodeRect.height <= 0) continue;
+      if (clipsX) {
+        clipLeft = Math.max(clipLeft, nodeRect.left);
+        clipRight = Math.min(clipRight, nodeRect.right);
+      }
+      if (clipsY) {
+        clipTop = Math.max(clipTop, nodeRect.top);
+        clipBottom = Math.min(clipBottom, nodeRect.bottom);
+      }
+    }
+    const visibleLeft = Math.max(clipLeft, Math.min(clipRight, rect.left));
+    const visibleRight = Math.max(clipLeft, Math.min(clipRight, rect.right));
+    const visibleTop = Math.max(clipTop, Math.min(clipBottom, rect.top));
+    const visibleBottom = Math.max(clipTop, Math.min(clipBottom, rect.bottom));
+    const visibleWidth = visibleRight - visibleLeft;
+    const visibleHeight = visibleBottom - visibleTop;
+    if (visibleWidth <= 1 || visibleHeight <= 1) {
+      return null;
+    }
+    const interactiveSelector = [
+      "button",
+      '[role="button"]',
+      "a[href]",
+      "label",
+      "input",
+      "textarea",
+      "select",
+      "summary",
+      '[contenteditable="true"]',
+      '[tabindex]:not([tabindex="-1"])'
+    ].join(",");
+    const targetInteractive = typeof el.closest === "function" ? el.closest(interactiveSelector) : null;
+    const sameInteractiveTarget = (pointElement) => {
+      if (!pointElement) return false;
+      if (pointElement === el || el.contains(pointElement) || pointElement.contains(el)) {
+        return true;
+      }
+      if (!targetInteractive || typeof pointElement.closest !== "function") {
+        return false;
+      }
+      return pointElement.closest(interactiveSelector) === targetInteractive;
+    };
+    const cx = visibleLeft + visibleWidth / 2;
+    const cy = visibleTop + visibleHeight / 2;
+    const smallX = Math.min(12, Math.max(2, visibleWidth * 0.18));
+    const smallY = Math.min(12, Math.max(2, visibleHeight * 0.18));
+    const points = [
+      { x: cx, y: cy },
+      { x: visibleLeft + smallX, y: visibleTop + smallY },
+      { x: visibleRight - smallX, y: visibleTop + smallY },
+      { x: visibleLeft + smallX, y: visibleBottom - smallY },
+      { x: visibleRight - smallX, y: visibleBottom - smallY },
+      { x: cx, y: visibleTop + Math.min(10, Math.max(2, visibleHeight * 0.2)) },
+      { x: cx, y: visibleBottom - Math.min(10, Math.max(2, visibleHeight * 0.2)) },
+      { x: visibleLeft + Math.min(10, Math.max(2, visibleWidth * 0.2)), y: cy },
+      { x: visibleRight - Math.min(10, Math.max(2, visibleWidth * 0.2)), y: cy }
+    ];
+    const safePoints = points.filter((point) => {
+      const pointElement = document.elementFromPoint(point.x, point.y);
+      return sameInteractiveTarget(pointElement);
+    });
+    const candidates = safePoints.length ? safePoints : points;
+    const chosen = candidates[Math.floor(Math.random() * candidates.length)];
+    if (!chosen) return null;
+    return {
+      x: chosen.x,
+      y: chosen.y
+    };
+  });
+};
+var getScrollableRect = async (element) => {
+  return element.evaluate((el) => {
+    const isScrollable = (node) => {
+      const style = window.getComputedStyle(node);
+      if (!style) return false;
+      const overflowY = style.overflowY;
+      if (!["auto", "scroll", "overlay"].includes(overflowY)) return false;
+      return node.scrollHeight > node.clientHeight + 1;
+    };
+    let current = el;
+    while (current && current !== document.body) {
+      if (isScrollable(current)) {
+        const rect = current.getBoundingClientRect();
+        if (rect && rect.width > 0 && rect.height > 0) {
+          return {
+            x: rect.x,
+            y: rect.y,
+            width: rect.width,
+            height: rect.height
+          };
+        }
+      }
+      current = current.parentElement;
+    }
+    return null;
+  });
+};
+var scrollScrollableAncestor = async (element, deltaY) => {
+  return element.evaluate((el, amount) => {
+    const isScrollable = (node) => {
+      const style = window.getComputedStyle(node);
+      if (!style) return false;
+      const overflowY = style.overflowY;
+      if (!["auto", "scroll", "overlay"].includes(overflowY)) return false;
+      return node.scrollHeight > node.clientHeight + 1;
+    };
+    let current = el;
+    while (current && current !== document.body) {
+      if (isScrollable(current)) {
+        const beforeTop2 = current.scrollTop;
+        current.scrollTop = beforeTop2 + amount;
+        return {
+          scroller: true,
+          moved: current.scrollTop !== beforeTop2,
+          scrollTop: current.scrollTop
+        };
+      }
+      current = current.parentElement;
+    }
+    const beforeTop = window.scrollY;
+    window.scrollBy(0, amount);
+    return {
+      scroller: null,
+      moved: window.scrollY !== beforeTop,
+      scrollTop: window.scrollY
+    };
+  }, deltaY);
+};
+var scrollAwayFromObstruction = async (element, status) => {
+  return element.evaluate((el, innerStatus) => {
+    const isScrollable = (node) => {
+      const style = window.getComputedStyle(node);
+      if (!style) return false;
+      const overflowY = style.overflowY;
+      if (!["auto", "scroll", "overlay"].includes(overflowY)) return false;
+      return node.scrollHeight > node.clientHeight + 1;
+    };
+    let scroller = el;
+    while (scroller && scroller !== document.body) {
+      if (isScrollable(scroller)) break;
+      scroller = scroller.parentElement;
+    }
+    if (!scroller || scroller === document.body) {
+      return { moved: false, scrollTop: 0, deltaY: 0 };
+    }
+    const rect = el.getBoundingClientRect();
+    const scrollerRect = scroller.getBoundingClientRect();
+    const obstruction = innerStatus?.obstruction || {};
+    const obstructionTop = Number(obstruction.top);
+    const obstructionBottom = Number(obstruction.bottom);
+    const obstructionMiddle = Number.isFinite(obstructionTop) && Number.isFinite(obstructionBottom) ? (obstructionTop + obstructionBottom) / 2 : scrollerRect.top + scrollerRect.height / 2;
+    const scrollerMiddle = scrollerRect.top + scrollerRect.height / 2;
+    const padding = 18;
+    let deltaY = 0;
+    if (Number.isFinite(obstructionTop) && rect.bottom > obstructionTop && obstructionTop >= scrollerRect.top && obstructionTop <= scrollerRect.bottom && obstructionMiddle >= scrollerMiddle) {
+      deltaY = rect.bottom - obstructionTop + padding;
+    } else if (Number.isFinite(obstructionBottom) && rect.top < obstructionBottom && obstructionBottom >= scrollerRect.top && obstructionBottom <= scrollerRect.bottom && obstructionMiddle < scrollerMiddle) {
+      deltaY = rect.top - obstructionBottom - padding;
+    } else {
+      const fallbackDistance = Math.max(48, Math.min(180, scrollerRect.height * 0.45));
+      deltaY = obstructionMiddle >= scrollerMiddle ? fallbackDistance : -fallbackDistance;
+    }
+    const beforeTop = scroller.scrollTop;
+    scroller.scrollTop = beforeTop + deltaY;
+    return {
+      moved: Math.abs(scroller.scrollTop - beforeTop) > 2,
+      scrollTop: scroller.scrollTop,
+      deltaY
+    };
+  }, status);
+};
 var dispatchTouchSwipe = async (page, deltaY, options = {}) => {
   const viewport = resolveViewport(page);
-  const distance = clamp(Math.abs(deltaY), 80, Math.max(120, viewport.height * 0.72));
+  const rawRect = options.rect || null;
+  const rect = rawRect ? {
+    x: clamp(rawRect.x, 0, viewport.width),
+    y: clamp(rawRect.y, 0, viewport.height),
+    width: clamp(rawRect.width, 0, viewport.width),
+    height: clamp(rawRect.height, 0, viewport.height)
+  } : null;
+  const area = rect && rect.width > 24 && rect.height > 48 ? {
+    left: rect.x,
+    right: Math.min(viewport.width, rect.x + rect.width),
+    top: rect.y,
+    bottom: Math.min(viewport.height, rect.y + rect.height)
+  } : {
+    left: 0,
+    right: viewport.width,
+    top: 0,
+    bottom: viewport.height
+  };
+  const areaWidth = Math.max(1, area.right - area.left);
+  const areaHeight = Math.max(1, area.bottom - area.top);
+  const maxDistance = rect ? Math.max(60, areaHeight * 0.72) : Math.max(120, viewport.height * 0.72);
+  const distance = clamp(Math.abs(deltaY), Math.min(80, maxDistance), maxDistance);
   const direction = deltaY >= 0 ? 1 : -1;
   const startX = clamp(
-    viewport.width * (0.45 + Math.random() * 0.1),
+    area.left + areaWidth * (0.45 + Math.random() * 0.1),
     24,
     viewport.width - 24
   );
-  const startY = direction > 0 ? clamp(viewport.height * (0.72 + Math.random() * 0.1), 80, viewport.height - 32) : clamp(viewport.height * (0.28 + Math.random() * 0.1), 32, viewport.height - 80);
-  const endY = clamp(startY - direction * distance, 24, viewport.height - 24);
+  const startY = direction > 0 ? clamp(area.top + areaHeight * (0.72 + Math.random() * 0.1), area.top + 24, area.bottom - 16) : clamp(area.top + areaHeight * (0.28 + Math.random() * 0.1), area.top + 16, area.bottom - 24);
+  const endY = clamp(startY - direction * distance, Math.max(16, area.top + 12), Math.min(viewport.height - 16, area.bottom - 12));
   const steps = Math.max(4, Math.round(Number(options.steps || 6)));
   const durationMs = jitterMs(options.durationMs || 320, 0.35);
   let client = null;
@@ -2790,8 +3279,11 @@ var MobileHumanize = {
       maxDurationMs = maxSteps * 280 + 1200,
       throwOnMissing = false
     } = options;
+    const targetDesc = describeTarget(target);
+    logger7.start("humanScroll", `target=${targetDesc}`);
     const element = await resolveElement(page, target, { throwOnMissing });
     if (!element) {
+      logger7.warn(`humanScroll | \u5143\u7D20\u672A\u627E\u5230: ${targetDesc}`);
       return { element: null, didScroll: false, restore: null };
     }
     const startTime = Date.now();
@@ -2799,17 +3291,133 @@ var MobileHumanize = {
     for (let i = 0; i < maxSteps; i += 1) {
       const status = await checkElementVisibility(element);
       if (status.code === "VISIBLE") {
+        if (status.isFixed) {
+          logger7.info("humanScroll | fixed/sticky \u5BB9\u5668\u5185\uFF0C\u8DF3\u8FC7\u6EDA\u52A8");
+        } else {
+          logger7.debug("humanScroll | \u5143\u7D20\u53EF\u89C1\u4E14\u65E0\u906E\u6321");
+        }
+        logger7.success("humanScroll", didScroll ? "\u5DF2\u6EDA\u52A8" : "\u65E0\u9700\u6EDA\u52A8");
+        return { element, didScroll, restore: null };
+      }
+      if (status.code === "ZERO_DIMENSIONS" || status.code === "NOT_INTERACTABLE") {
+        logger7.warn(`humanScroll | \u5143\u7D20\u4E0D\u53EF\u6EDA\u52A8\u81F3\u53EF\u70B9\u51FB\u72B6\u6001: ${status.reason || status.code}`);
         return { element, didScroll, restore: null };
       }
+      const scrollRect = await getScrollableRect(element);
+      if (!scrollRect && status.isFixed && status.code === "OBSTRUCTED") {
+        logger7.warn(`humanScroll | fixed/sticky \u76EE\u6807\u88AB\u906E\u6321\uFF0C\u6EDA\u52A8\u65E0\u6CD5\u89E3\u9664 (${status.obstruction?.tag || "unknown"})`);
+        return { element, didScroll, restore: null };
+      }
+      if (scrollRect && status.code === "OBSTRUCTED" && status.obstruction?.isFixed) {
+        const moved = await scrollAwayFromObstruction(element, status);
+        if (moved.moved) {
+          logger7.debug(`humanScroll | sticky/fixed \u906E\u6321\u8865\u507F\u6EDA\u52A8 top=${Math.round(moved.scrollTop || 0)}`);
+          await waitJitter(90, 0.3);
+          didScroll = true;
+          continue;
+        }
+      }
       if (Date.now() - startTime > maxDurationMs) {
-        logger7.warn(`humanScroll | mobile timeout (${maxDurationMs}ms)`);
+        logger7.warn(`humanScroll | mobile timeout (${maxDurationMs}ms, status=${status.code}, direction=${status.direction || "unknown"}, fixed=${Boolean(status.isFixed)})`);
         return { element, didScroll, restore: null };
       }
-      const distance = minStep + Math.random() * Math.max(1, maxStep - minStep);
-      const deltaY = status.direction === "up" ? -distance : distance;
-      await dispatchTouchSwipe(page, deltaY);
+      const stepMin = scrollRect ? Math.min(minStep, Math.max(60, scrollRect.height * 0.4)) : minStep;
+      const stepMax = scrollRect ? Math.min(maxStep, Math.max(stepMin + 40, scrollRect.height * 0.8)) : maxStep;
+      logger7.debug(`humanScroll | \u6B65\u9AA4 ${i + 1}/${maxSteps}: ${status.reason || status.code} ${status.direction ? `(${status.direction})` : ""}`);
+      const distance = stepMin + Math.random() * Math.max(1, stepMax - stepMin);
+      let deltaY = status.direction === "up" ? -distance : distance;
+      if (status.code === "OBSTRUCTED") {
+        if (status.obstruction?.isFixed && status.obstruction.top != null) {
+          const obstructionMiddle = (Number(status.obstruction.top || 0) + Number(status.obstruction.bottom || status.obstruction.top || 0)) / 2;
+          const visibleMiddle = scrollRect ? scrollRect.y + scrollRect.height / 2 : status.viewH / 2;
+          deltaY = obstructionMiddle < visibleMiddle ? -distance : distance;
+        } else {
+          const halfY = scrollRect ? scrollRect.y + scrollRect.height / 2 : status.viewH / 2;
+          deltaY = status.cy > halfY ? distance : -distance;
+        }
+      }
+      const beforeWindowState = scrollRect ? await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY })) : null;
+      const beforeState = scrollRect ? await element.evaluate((el) => {
+        const isScrollable = (node) => {
+          const style = window.getComputedStyle(node);
+          if (!style) return false;
+          const overflowY = style.overflowY;
+          if (!["auto", "scroll", "overlay"].includes(overflowY)) return false;
+          return node.scrollHeight > node.clientHeight + 1;
+        };
+        let current = el;
+        while (current && current !== document.body) {
+          if (isScrollable(current)) {
+            return {
+              kind: "element",
+              top: current.scrollTop,
+              left: current.scrollLeft
+            };
+          }
+          current = current.parentElement;
+        }
+        return { kind: "window", top: window.scrollY, left: window.scrollX };
+      }) : null;
+      await dispatchTouchSwipe(page, deltaY, { rect: scrollRect });
+      if (scrollRect && beforeWindowState) {
+        const afterWindowState = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
+        if (Math.abs(afterWindowState.x - beforeWindowState.x) > 2 || Math.abs(afterWindowState.y - beforeWindowState.y) > 2) {
+          await page.evaluate((state) => window.scrollTo(state.x, state.y), beforeWindowState);
+          logger7.debug(`humanScroll | \u7A97\u53E3\u6EDA\u52A8\u56DE\u6536 from=${Math.round(afterWindowState.y)} to=${Math.round(beforeWindowState.y)}`);
+        }
+      }
+      if (scrollRect && beforeState) {
+        const afterState = await element.evaluate((el) => {
+          const isScrollable = (node) => {
+            const style = window.getComputedStyle(node);
+            if (!style) return false;
+            const overflowY = style.overflowY;
+            if (!["auto", "scroll", "overlay"].includes(overflowY)) return false;
+            return node.scrollHeight > node.clientHeight + 1;
+          };
+          let current = el;
+          while (current && current !== document.body) {
+            if (isScrollable(current)) {
+              return {
+                kind: "element",
+                top: current.scrollTop,
+                left: current.scrollLeft
+              };
+            }
+            current = current.parentElement;
+          }
+          return { kind: "window", top: window.scrollY, left: window.scrollX };
+        });
+        const topDelta = Number(afterState.top || 0) - Number(beforeState.top || 0);
+        const leftDelta = Number(afterState.left || 0) - Number(beforeState.left || 0);
+        const expectedDelta = Number(deltaY || 0);
+        const moved = beforeState.kind !== afterState.kind || Math.abs(topDelta) > 2 || Math.abs(leftDelta) > 2;
+        if (!moved) {
+          const fallback = await scrollScrollableAncestor(element, deltaY);
+          logger7.debug(`humanScroll | \u5BB9\u5668\u89E6\u6478\u65E0\u6548\uFF0C\u76F4\u63A5\u6EDA\u52A8 fallback=${fallback.scroller ? "ancestor" : "window"} top=${Math.round(fallback.scrollTop || 0)}`);
+        } else if (beforeState.kind === afterState.kind && Math.abs(expectedDelta) > 24 && Math.sign(topDelta || expectedDelta) === Math.sign(expectedDelta) && Math.abs(topDelta) < Math.min(Math.abs(expectedDelta) * 0.45, 96)) {
+          const residualDelta = expectedDelta - topDelta;
+          if (Math.sign(residualDelta) === Math.sign(expectedDelta) && Math.abs(residualDelta) > 24) {
+            const fallback = await scrollScrollableAncestor(element, residualDelta);
+            logger7.debug(`humanScroll | \u5BB9\u5668\u89E6\u6478\u8DDD\u79BB\u4E0D\u8DB3\uFF0C\u8865\u507F\u6EDA\u52A8 fallback=${fallback.scroller ? "ancestor" : "window"} top=${Math.round(fallback.scrollTop || 0)}`);
+          }
+        }
+      }
       didScroll = true;
     }
+    try {
+      await element.scrollIntoViewIfNeeded?.();
+      await waitJitter(80, 0.3);
+      const finalStatus = await checkElementVisibility(element);
+      if (finalStatus.code === "VISIBLE") {
+        logger7.info("humanScroll | \u539F\u751F scrollIntoViewIfNeeded \u515C\u5E95\u6210\u529F");
+        logger7.success("humanScroll", didScroll ? "\u5DF2\u6EDA\u52A8" : "\u65E0\u9700\u6EDA\u52A8");
+        return { element, didScroll: true, restore: null };
+      }
+    } catch (fallbackError) {
+      logger7.debug(`humanScroll | native fallback failed: ${fallbackError?.message || fallbackError}`);
+    }
+    logger7.warn(`humanScroll | \u5728 ${maxSteps} \u6B65\u540E\u65E0\u6CD5\u786E\u4FDD\u53EF\u89C1\u6027`);
     return { element, didScroll, restore: null };
   },
   async humanClick(page, target, options = {}) {
@@ -2818,29 +3426,51 @@ var MobileHumanize = {
       throwOnMissing = true,
       scrollIfNeeded = true
     } = options;
-    if (target == null) {
-      const viewport = resolveViewport(page);
+    const targetDesc = describeTarget(target);
+    logger7.start("humanClick", `target=${targetDesc}`);
+    try {
+      if (target == null) {
+        const viewport = resolveViewport(page);
+        await waitJitter(reactionDelay, 0.45);
+        await tapPoint(page, {
+          x: viewport.width * (0.45 + Math.random() * 0.1),
+          y: viewport.height * (0.48 + Math.random() * 0.12)
+        });
+        logger7.success("humanClick", "Tapped current position");
+        return true;
+      }
+      const element = await resolveElement(page, target, { throwOnMissing });
+      if (!element) {
+        logger7.warn(`humanClick: \u5143\u7D20\u4E0D\u5B58\u5728\uFF0C\u8DF3\u8FC7\u70B9\u51FB ${targetDesc}`);
+        return false;
+      }
+      if (scrollIfNeeded) {
+        await MobileHumanize.humanScroll(page, element, { throwOnMissing });
+      }
+      const status = await checkElementVisibility(element).catch(() => null);
+      if (status && status.code !== "VISIBLE") {
+        const message = `\u5143\u7D20\u4E0D\u53EF\u70B9\u51FB: ${status.reason || status.code}`;
+        if (throwOnMissing) throw new Error(message);
+        logger7.warn(`humanClick: ${message}\uFF0C\u8DF3\u8FC7\u70B9\u51FB`);
+        return false;
+      }
+      const box = await element.boundingBox();
+      if (!box) {
+        if (throwOnMissing) throw new Error("\u65E0\u6CD5\u83B7\u53D6\u5143\u7D20\u4F4D\u7F6E");
+        logger7.warn("humanClick: \u65E0\u6CD5\u83B7\u53D6\u4F4D\u7F6E\uFF0C\u8DF3\u8FC7\u70B9\u51FB");
+        return false;
+      }
       await waitJitter(reactionDelay, 0.45);
-      await tapPoint(page, {
-        x: viewport.width * (0.45 + Math.random() * 0.1),
-        y: viewport.height * (0.48 + Math.random() * 0.12)
-      });
+      const safePoint = await resolveSafeTapPoint(element).catch(() => null);
+      const tapTarget = safePoint || randomPointInBox(clipBoxToViewport(box, resolveViewport(page)), 0.2);
+      await tapPoint(page, tapTarget);
+      await waitJitter(120, 0.35);
+      logger7.success("humanClick");
       return true;
+    } catch (error) {
+      logger7.fail("humanClick", error);
+      throw error;
     }
-    const element = await resolveElement(page, target, { throwOnMissing });
-    if (!element) return false;
-    if (scrollIfNeeded) {
-      await MobileHumanize.humanScroll(page, element, { throwOnMissing });
-    }
-    const box = await element.boundingBox();
-    if (!box) {
-      if (throwOnMissing) throw new Error("\u65E0\u6CD5\u83B7\u53D6\u5143\u7D20\u4F4D\u7F6E");
-      return false;
-    }
-    await waitJitter(reactionDelay, 0.45);
-    await tapPoint(page, randomPointInBox(box, 0.2));
-    await waitJitter(120, 0.35);
-    return true;
   },
   async randomSleep(baseMs, jitterPercent = 0.3) {
     await waitJitter(baseMs, jitterPercent);
@@ -2878,6 +3508,40 @@ var MobileHumanize = {
       }
     }
   },
+  async humanPress(page, targetOrKey, maybeKey, options = {}) {
+    const hasTarget = typeof maybeKey === "string";
+    const key = hasTarget ? maybeKey : targetOrKey;
+    const pressOptions = hasTarget ? options : maybeKey || options;
+    const {
+      reactionDelay = 170,
+      holdDelay = 42,
+      focusDelay = 180,
+      scrollIfNeeded = true,
+      throwOnMissing = true,
+      keyboardOptions = {}
+    } = pressOptions || {};
+    const targetDesc = hasTarget ? describeTarget(targetOrKey) : "current focus";
+    logger7.start("humanPress", `key=${key}, target=${targetDesc}`);
+    try {
+      if (hasTarget) {
+        await MobileHumanize.humanClick(page, targetOrKey, {
+          reactionDelay: focusDelay,
+          scrollIfNeeded,
+          throwOnMissing
+        });
+      }
+      await waitJitter(reactionDelay, 0.45);
+      await page.keyboard.press(key, {
+        ...keyboardOptions,
+        delay: jitterMs(holdDelay, 0.5)
+      });
+      logger7.success("humanPress");
+      return true;
+    } catch (error) {
+      logger7.fail("humanPress", error);
+      throw error;
+    }
+  },
   async humanClear(page, selector) {
     const locator = page.locator(selector);
     await MobileHumanize.humanClick(page, locator, { scrollIfNeeded: true });
@@ -2928,15 +3592,18 @@ var MobileHumanize = {
 };
 
 // src/humanize.js
-var resolveDeviceFromPage = (page) => normalizeDevice(page?.[PageRuntimeStateKey]?.device);
+var resolveDeviceFromPage2 = (page) => normalizeDevice(page?.[PageRuntimeStateKey]?.device);
 var resolveDelegate = (page) => {
-  return resolveDeviceFromPage(page) === Device.Mobile ? MobileHumanize : Humanize;
+  return resolveDeviceFromPage2(page) === Device.Mobile ? MobileHumanize : Humanize;
 };
 var callDelegate = (method, page, args) => {
   const delegate = resolveDelegate(page);
   return delegate[method](page, ...args);
 };
 var Humanize2 = {
+  // M = Machine: native/mechanical operations for compatibility paths.
+  // These APIs intentionally do not humanize timing, motion, or intent.
+  M: MachineHumanize,
   jitterMs(base, jitterPercent = 0.3) {
     return Humanize.jitterMs(base, jitterPercent);
   },
@@ -2965,6 +3632,12 @@ var Humanize2 = {
   humanType(page, selector, text, options = {}) {
     return callDelegate("humanType", page, [selector, text, options]);
   },
+  humanPress(page, targetOrKey, maybeKey, options = {}) {
+    if (typeof maybeKey === "string") {
+      return callDelegate("humanPress", page, [targetOrKey, maybeKey, options]);
+    }
+    return callDelegate("humanPress", page, [targetOrKey, maybeKey || options]);
+  },
   humanClear(page, selector) {
     return callDelegate("humanClear", page, [selector]);
   },