@skrillex1224/playwright-toolkit 2.1.226 → 2.1.227

package/README.md

@@ -102,10 +102,12 @@ await Actor.exit();
 | `Humanize`  | `initializeCursor(page)`                         | 初始化 Cursor (必须先调用)                                                           |
 | `Humanize`  | `jitterMs(base, jitterPercent?)`                 | 生成带抖动的毫秒数 (同步，返回 number)                                               |
 | `Humanize`  | `humanType(page, selector, text, options?)`      | 人类化输入 (baseDelay=180ms ±40%)                                                    |
+| `Humanize`  | `humanPress(page, target?, key, options?)`       | 人类化按键，支持当前焦点或先聚焦目标后按键                                           |
 | `Humanize`  | `humanClick(page, selector, options?)`           | 人类化点击 (reactionDelay=250ms ±40%)                                                |
 | `Humanize`  | `warmUpBrowsing(page, baseDuration?)`            | 页面预热 (3500ms ±40%)                                                               |
 | `Humanize`  | `simulateGaze(page, baseDurationMs?)`            | 模拟注视 (2500ms ±40%)                                                               |
 | `Humanize`  | `randomSleep(baseMs, jitterPercent?)`            | 随机延迟 (±30% 抖动)                                                                 |
+| `Humanize`  | `M.click/focus/fill/type/clickPoint(...)`        | Machine 机械化操作；用于必须保持非拟人化 click/focus/fill/type 的兼容路径            |
 | `Captcha`   | `useCaptchaMonitor(page, options)`               | 验证码监控                                                                           |
 
 ---

package/dist/index.cjs

@@ -2513,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
@@ -2601,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) => {
@@ -2930,6 +3102,49 @@ var scrollScrollableAncestor = async (element, deltaY) => {
     };
   }, 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 rawRect = options.rect || null;
@@ -3093,6 +3308,15 @@ var MobileHumanize = {
         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, status=${status.code}, direction=${status.direction || "unknown"}, fixed=${Boolean(status.isFixed)})`);
         return { element, didScroll, restore: null };
@@ -3224,7 +3448,7 @@ var MobileHumanize = {
         await MobileHumanize.humanScroll(page, element, { throwOnMissing });
       }
       const status = await checkElementVisibility(element).catch(() => null);
-      if (status && (status.code === "ZERO_DIMENSIONS" || status.code === "NOT_INTERACTABLE")) {
+      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`);
@@ -3284,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 });
@@ -3334,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);
   },
@@ -3371,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]);
   },