@skrillex1224/playwright-toolkit 2.1.58 → 2.1.60

package/README.md

@@ -82,24 +82,23 @@ await Actor.exit();
 
 ### API 一览
 
-| 模块        | 方法                                                 | 说明                                   |
-| ----------- | ---------------------------------------------------- | -------------------------------------- |
-| `Launch`    | `getAdvancedLaunchOptions()`                         | 增强版启动参数                         |
-| `Launch`    | `getLaunchOptions()`                                 | 基础启动参数                           |
-| `Launch`    | `getFingerprintGeneratorOptions()`                   | 指纹生成器选项                         |
-| `AntiCheat` | `applyPage(page, options?)`                          | 应用时区/语言/权限/视口                |
-| `AntiCheat` | `applyContext(context, options?)`                    | 仅应用 Context 设置                    |
-| `AntiCheat` | `syncViewportWithScreen(page)`                       | 同步视口与屏幕                         |
-| `AntiCheat` | `getTlsFingerprintOptions(userAgent?)`               | got-scraping TLS 指纹                  |
-| `Humanize`  | `initializeCursor(page)`                             | 初始化 Cursor (必须先调用)             |
-| `Humanize`  | `jitterMs(base, jitterPercent?)`                     | 生成带抖动的毫秒数 (同步，返回 number) |
-| `Humanize`  | `humanType(page, selector, text, options?)`          | 人类化输入 (baseDelay=180ms ±40%)      |
-| `Humanize`  | `humanClick(page, selector, options?)`               | 人类化点击 (reactionDelay=250ms ±40%)  |
-| `Humanize`  | `warmUpBrowsing(page, baseDuration?)`                | 页面预热 (3500ms ±40%)                 |
-| `Humanize`  | `naturalScroll(page, direction?, distance?, steps?)` | 自然滚动 (带惯性+抖动)                 |
-| `Humanize`  | `simulateGaze(page, baseDurationMs?)`                | 模拟注视 (2500ms ±40%)                 |
-| `Humanize`  | `randomSleep(baseMs, jitterPercent?)`                | 随机延迟 (±30% 抖动)                   |
-| `Captcha`   | `useCaptchaMonitor(page, options)`                   | 验证码监控                             |
+| 模块        | 方法                                        | 说明                                   |
+| ----------- | ------------------------------------------- | -------------------------------------- |
+| `Launch`    | `getAdvancedLaunchOptions()`                | 增强版启动参数                         |
+| `Launch`    | `getLaunchOptions()`                        | 基础启动参数                           |
+| `Launch`    | `getFingerprintGeneratorOptions()`          | 指纹生成器选项                         |
+| `AntiCheat` | `applyPage(page, options?)`                 | 应用时区/语言/权限/视口                |
+| `AntiCheat` | `applyContext(context, options?)`           | 仅应用 Context 设置                    |
+| `AntiCheat` | `syncViewportWithScreen(page)`              | 同步视口与屏幕                         |
+| `AntiCheat` | `getTlsFingerprintOptions(userAgent?)`      | got-scraping TLS 指纹                  |
+| `Humanize`  | `initializeCursor(page)`                    | 初始化 Cursor (必须先调用)             |
+| `Humanize`  | `jitterMs(base, jitterPercent?)`            | 生成带抖动的毫秒数 (同步，返回 number) |
+| `Humanize`  | `humanType(page, selector, text, options?)` | 人类化输入 (baseDelay=180ms ±40%)      |
+| `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% 抖动)                   |
+| `Captcha`   | `useCaptchaMonitor(page, options)`          | 验证码监控                             |
 
 ---
 

package/dist/index.cjs

@@ -534,6 +534,59 @@ var import_delay2 = __toESM(require("delay"), 1);
 var import_ghost_cursor_playwright = require("ghost-cursor-playwright");
 var logger5 = createInternalLogger("Humanize");
 var $CursorWeakMap = /* @__PURE__ */ new WeakMap();
+var VISIBILITY_CODE = {
+  VISIBLE: "VISIBLE",
+  OUT_OF_VIEWPORT: "OUT_OF_VIEWPORT",
+  OBSTRUCTED: "OBSTRUCTED",
+  ZERO_DIMENSIONS: "ZERO_DIMENSIONS",
+  HIDDEN: "HIDDEN",
+  DETACHED: "DETACHED"
+};
+var VISIBILITY_REASON = {
+  OUT_OF_VIEWPORT: "\u4E0D\u5728\u89C6\u53E3\u5185",
+  OBSTRUCTED: "\u88AB\u906E\u6321",
+  ZERO_DIMENSIONS: "\u5C3A\u5BF8\u4E3A\u96F6",
+  HIDDEN: "\u5143\u7D20\u4E0D\u53EF\u89C1",
+  DETACHED: "\u5143\u7D20\u5DF2\u88AB\u79FB\u9664"
+};
+var SCROLL_DIRECTION = {
+  UP: "up",
+  DOWN: "down",
+  UNKNOWN: "unknown"
+};
+var DEFAULT_SCROLL_OPTIONS = {
+  maxSteps: 20,
+  minStep: 150,
+  maxStep: 400,
+  maxDurationMs: 3500
+};
+var SAME_POSITION_THRESHOLD_PX = 2;
+var SAME_POSITION_LIMIT = 3;
+var SAFE_MOUSE_JITTER_PX = 100;
+var isElementHandleLike = (value) => value && typeof value.evaluate === "function" && typeof value.boundingBox === "function";
+var isLocatorLike = (value) => value && typeof value.elementHandle === "function";
+async function resolveElementHandle(page, target) {
+  if (!target) return { element: null, owned: false };
+  if (typeof target === "string") {
+    const element = await page.$(target);
+    return { element, owned: true };
+  }
+  if (isLocatorLike(target)) {
+    const element = await target.elementHandle();
+    return { element, owned: true };
+  }
+  if (isElementHandleLike(target)) {
+    return { element: target, owned: false };
+  }
+  return { element: null, owned: false };
+}
+async function disposeElementHandle(element, owned) {
+  if (!element || !owned || typeof element.dispose !== "function") return;
+  try {
+    await element.dispose();
+  } catch {
+  }
+}
 function $GetCursor(page) {
   const cursor = $CursorWeakMap.get(page);
   if (!cursor) {
@@ -614,99 +667,353 @@ var Humanize = {
    * 返回 restore 方法，用于将滚动容器恢复到原位置
    * 
    * @param {import('playwright').Page} page
-   * @param {string|import('playwright').ElementHandle} target - CSS 选择器或元素句柄
+   * @param {string|import('playwright').ElementHandle|import('playwright').Locator} target - CSS 选择器、元素句柄或 Locator
    * @param {Object} [options]
-   * @param {number} [options.maxSteps=25] - 最大滚动步数
-   * @param {number} [options.minStep=80] - 单次滚动最小步长
-   * @param {number} [options.maxStep=220] - 单次滚动最大步长
+   * @param {number} [options.maxSteps=20] - 最大滚动步数
+   * @param {number} [options.minStep=150] - 单次滚动最小步长
+   * @param {number} [options.maxStep=400] - 单次滚动最大步长
+   * @param {number} [options.maxDurationMs=3500] - 最大滚动耗时上限
    */
   async humanScroll(page, target, options = {}) {
-    const { maxSteps = 30, minStep = 150, maxStep = 400 } = options;
-    const targetDesc = typeof target === "string" ? target : "ElementHandle";
-    logger5.debug(`humanScroll | \u76EE\u6807=${targetDesc}`);
-    let element;
-    if (typeof target === "string") {
-      element = await page.$(target);
-      if (!element) {
-        logger5.warn(`humanScroll | \u5143\u7D20\u672A\u627E\u5230: ${target}`);
-        return { element: null, didScroll: false };
-      }
-    } else {
-      element = target;
+    const {
+      maxSteps = DEFAULT_SCROLL_OPTIONS.maxSteps,
+      minStep = DEFAULT_SCROLL_OPTIONS.minStep,
+      maxStep = DEFAULT_SCROLL_OPTIONS.maxStep,
+      maxDurationMs = DEFAULT_SCROLL_OPTIONS.maxDurationMs
+    } = options;
+    const targetDesc = typeof target === "string" ? target : isLocatorLike(target) ? "Locator" : "ElementHandle";
+    logger5.info(`humanScroll | \u5F00\u59CB\u6EDA\u52A8\u76EE\u6807: ${targetDesc}`);
+    const { element } = await resolveElementHandle(page, target);
+    if (!element) {
+      logger5.warn(`humanScroll | \u5143\u7D20\u672A\u627E\u5230: ${targetDesc}`);
+      return { element: null, didScroll: false, restore: null };
     }
     const cursor = $GetCursor(page);
     let didScroll = false;
+    let lastRect = null;
+    let samePositionCount = 0;
+    const startAt = Date.now();
+    const visibilityPayload = {
+      codes: VISIBILITY_CODE,
+      reasons: VISIBILITY_REASON,
+      directions: SCROLL_DIRECTION
+    };
+    const scrollDeltas = /* @__PURE__ */ new Map();
+    const scrollTargetRects = /* @__PURE__ */ new Map();
+    let windowIndex = null;
+    const moveMouseToRect = async (rect) => {
+      if (!rect || !Number.isFinite(rect.left) || !Number.isFinite(rect.top)) return false;
+      const width = Number.isFinite(rect.width) ? rect.width : Math.max(0, (rect.right ?? rect.left) - rect.left);
+      const height = Number.isFinite(rect.height) ? rect.height : Math.max(0, (rect.bottom ?? rect.top) - rect.top);
+      const viewSize = page.viewportSize();
+      const viewW = viewSize?.width ?? null;
+      const viewH = viewSize?.height ?? null;
+      if (viewW && viewH) {
+        const rectRight = rect.right ?? rect.left + width;
+        const rectBottom = rect.bottom ?? rect.top + height;
+        if (rectBottom < 0 || rect.top > viewH || rectRight < 0 || rect.left > viewW) {
+          return false;
+        }
+      }
+      const rawX = rect.left + width / 2;
+      const rawY = rect.top + height / 2;
+      if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) return false;
+      const padding = 6;
+      let x = rawX;
+      let y = rawY;
+      if (viewW && viewH) {
+        const maxX = Math.max(padding, viewW - padding);
+        const maxY = Math.max(padding, viewH - padding);
+        x = Math.min(Math.max(rawX, padding), maxX);
+        y = Math.min(Math.max(rawY, padding), maxY);
+      }
+      x += (Math.random() - 0.5) * 4;
+      y += (Math.random() - 0.5) * 4;
+      if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+      await page.mouse.move(x, y, { steps: 6 }).catch(() => {
+      });
+      return true;
+    };
+    const wheelByChunks = async (delta, rect, isWindowTarget) => {
+      let remaining = delta;
+      const stepBase = Math.min(maxStep, 400);
+      while (Math.abs(remaining) > 1) {
+        const step = Math.abs(remaining) > stepBase ? Math.sign(remaining) * stepBase : remaining;
+        if (!isWindowTarget) {
+          await moveMouseToRect(rect);
+        }
+        await page.mouse.wheel(0, step);
+        remaining -= step;
+        await (0, import_delay2.default)(this.jitterMs(60, 0.35));
+      }
+    };
+    const restore = async () => {
+      if (scrollDeltas.size === 0) return;
+      try {
+        for (const [index, delta] of scrollDeltas.entries()) {
+          if (!delta) continue;
+          const rect = scrollTargetRects.get(index);
+          const isWindowTarget = windowIndex !== null && index === windowIndex;
+          await wheelByChunks(-delta, rect, isWindowTarget);
+        }
+      } catch (err) {
+        logger5.warn(`humanScroll | restore failed: ${err?.message || err}`);
+      }
+    };
     const checkVisibility = async () => {
-      return await element.evaluate((el) => {
+      return await element.evaluate((el, payload) => {
+        const overflowRe = /(auto|scroll|overlay)/i;
+        const isScrollable = (node) => {
+          if (!node || node === document.body || node === document.documentElement) return false;
+          const style2 = window.getComputedStyle(node);
+          const overflowY = style2.overflowY;
+          return overflowRe.test(overflowY) && node.scrollHeight > node.clientHeight + 1;
+        };
+        const getScrollableAncestors = (node) => {
+          const list = [];
+          let current = node?.parentElement;
+          while (current && current !== document.body && current !== document.documentElement) {
+            if (isScrollable(current)) {
+              list.push(current);
+            }
+            current = current.parentElement;
+          }
+          return list;
+        };
+        if (!el || !el.isConnected) {
+          return { code: payload.codes.DETACHED, reason: payload.reasons.DETACHED };
+        }
+        const style = window.getComputedStyle(el);
+        if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) {
+          return { code: payload.codes.HIDDEN, reason: payload.reasons.HIDDEN };
+        }
         const rect = el.getBoundingClientRect();
         if (!rect || rect.width === 0 || rect.height === 0) {
-          return { code: "ZERO_DIMENSIONS", reason: "\u5C3A\u5BF8\u4E3A\u96F6" };
+          return { code: payload.codes.ZERO_DIMENSIONS, reason: payload.reasons.ZERO_DIMENSIONS };
         }
+        const hasFixedAncestor = (() => {
+          let node = el;
+          while (node && node !== document.body && node !== document.documentElement) {
+            const position = window.getComputedStyle(node).position;
+            if (position === "fixed") return true;
+            node = node.parentElement;
+          }
+          return false;
+        })();
+        const ancestors = getScrollableAncestors(el);
+        const targets = ancestors.map((node) => ({
+          isWindow: false,
+          rect: node.getBoundingClientRect(),
+          canScroll: node.scrollHeight > node.clientHeight + 1
+        }));
+        const windowTarget = {
+          isWindow: true,
+          rect: { top: 0, left: 0, right: window.innerWidth, bottom: window.innerHeight, width: window.innerWidth, height: window.innerHeight },
+          canScroll: document.documentElement.scrollHeight > window.innerHeight
+        };
+        targets.push(windowTarget);
+        const windowIndex2 = targets.length - 1;
         const cx = rect.left + rect.width / 2;
         const cy = rect.top + rect.height / 2;
-        const viewH = window.innerHeight;
-        const viewW = window.innerWidth;
-        if (cy < 0 || cy > viewH || cx < 0 || cx > viewW) {
-          const direction = cy < 0 ? "up" : cy > viewH ? "down" : "unknown";
-          return { code: "OUT_OF_VIEWPORT", reason: "\u4E0D\u5728\u89C6\u53E3\u5185", direction, cy, viewH };
+        const promoteToVisibleTarget = (index) => {
+          let idx = index;
+          while (idx < targets.length - 1) {
+            const current = targets[idx];
+            const parent = targets[idx + 1];
+            const c = current.rect;
+            const p = parent.rect;
+            const outOfParent = c.bottom < p.top || c.top > p.bottom || c.right < p.left || c.left > p.right;
+            if (outOfParent) {
+              idx += 1;
+              continue;
+            }
+            break;
+          }
+          return idx;
+        };
+        let outIndex = -1;
+        let direction = payload.directions.UNKNOWN;
+        for (let i = 0; i < targets.length; i += 1) {
+          const bounds = targets[i].rect;
+          if (cy < bounds.top) {
+            outIndex = i;
+            direction = payload.directions.UP;
+            break;
+          }
+          if (cy > bounds.bottom) {
+            outIndex = i;
+            direction = payload.directions.DOWN;
+            break;
+          }
+          if (cx < bounds.left || cx > bounds.right) {
+            outIndex = i;
+            direction = payload.directions.UNKNOWN;
+            break;
+          }
+        }
+        if (outIndex !== -1) {
+          let scrollTargetIndex = promoteToVisibleTarget(outIndex);
+          let target2 = targets[scrollTargetIndex];
+          if (!target2.isWindow) {
+            const targetRect = target2.rect;
+            const outOfWindow = targetRect.bottom < 0 || targetRect.top > window.innerHeight || targetRect.right < 0 || targetRect.left > window.innerWidth;
+            if (outOfWindow) {
+              scrollTargetIndex = windowIndex2;
+              target2 = windowTarget;
+            }
+          }
+          return {
+            code: payload.codes.OUT_OF_VIEWPORT,
+            reason: payload.reasons.OUT_OF_VIEWPORT,
+            direction,
+            rect,
+            viewH: target2.rect.height,
+            viewW: target2.rect.width,
+            cy,
+            cx,
+            scrollTargetIndex,
+            isWindow: target2.isWindow,
+            canScroll: target2.canScroll,
+            isFixed: hasFixedAncestor,
+            targetRect: target2.rect,
+            windowIndex: windowIndex2
+          };
         }
         const pointElement = document.elementFromPoint(cx, cy);
         if (pointElement && !el.contains(pointElement) && !pointElement.contains(el)) {
+          let fallbackIndex = promoteToVisibleTarget(targets.length > 1 ? 0 : targets.length - 1);
+          let target2 = targets[fallbackIndex];
+          if (!target2.isWindow) {
+            const targetRect = target2.rect;
+            const outOfWindow = targetRect.bottom < 0 || targetRect.top > window.innerHeight || targetRect.right < 0 || targetRect.left > window.innerWidth;
+            if (outOfWindow) {
+              fallbackIndex = windowIndex2;
+              target2 = windowTarget;
+            }
+          }
           return {
-            code: "OBSTRUCTED",
-            reason: "\u88AB\u906E\u6321",
+            code: payload.codes.OBSTRUCTED,
+            reason: payload.reasons.OBSTRUCTED,
             obstruction: {
               tag: pointElement.tagName,
               id: pointElement.id,
               className: pointElement.className
             },
+            rect,
+            viewH: target2.rect.height,
+            viewW: target2.rect.width,
             cy,
-            // Return Center Y for smart direction calculation
-            viewH
+            cx,
+            scrollTargetIndex: fallbackIndex,
+            isWindow: target2.isWindow,
+            canScroll: target2.canScroll,
+            isFixed: hasFixedAncestor,
+            targetRect: target2.rect,
+            windowIndex: windowIndex2
           };
         }
-        return { code: "VISIBLE" };
-      });
+        return {
+          code: payload.codes.VISIBLE,
+          rect,
+          viewH: windowTarget.rect.height,
+          viewW: windowTarget.rect.width,
+          cy,
+          cx,
+          scrollTargetIndex: targets.length - 1,
+          isWindow: true,
+          canScroll: windowTarget.canScroll,
+          isFixed: hasFixedAncestor,
+          targetRect: windowTarget.rect,
+          windowIndex: windowIndex2
+        };
+      }, visibilityPayload);
     };
     try {
       for (let i = 0; i < maxSteps; i++) {
+        if (Date.now() - startAt > maxDurationMs) {
+          logger5.warn(`humanScroll | \u26A0\uFE0F \u8D85\u8FC7\u6700\u5927\u8017\u65F6 ${maxDurationMs}ms\uFF0C\u63D0\u524D\u7ED3\u675F`);
+          return { element, didScroll, restore };
+        }
         const status = await checkVisibility();
-        if (status.code === "VISIBLE") {
-          logger5.debug("humanScroll | \u5143\u7D20\u53EF\u89C1\u4E14\u65E0\u906E\u6321");
-          return { element, didScroll };
+        if (windowIndex === null && typeof status.windowIndex === "number") {
+          windowIndex = status.windowIndex;
+        }
+        if (typeof status.scrollTargetIndex === "number" && status.targetRect) {
+          scrollTargetRects.set(status.scrollTargetIndex, status.targetRect);
+        }
+        if (status.code === VISIBILITY_CODE.VISIBLE) {
+          logger5.info("humanScroll | \u5143\u7D20\u5DF2\u53EF\u89C1\u4E14\u65E0\u906E\u6321");
+          return { element, didScroll, restore };
+        }
+        if (status.code === VISIBILITY_CODE.DETACHED || status.code === VISIBILITY_CODE.HIDDEN || status.code === VISIBILITY_CODE.ZERO_DIMENSIONS) {
+          logger5.warn(`humanScroll | ${status.reason || "\u5143\u7D20\u4E0D\u53EF\u7528"}`);
+          return { element, didScroll, restore };
+        }
+        const directionStr = status.direction ? `(${status.direction})` : "";
+        logger5.info(`humanScroll | \u6B65\u9AA4 ${i + 1}/${maxSteps}: ${status.reason} ${directionStr}`);
+        const currentRect = status.rect;
+        if (i > 0 && lastRect && currentRect) {
+          const dy = Math.abs(currentRect.top - lastRect.top);
+          const dx = Math.abs(currentRect.left - lastRect.left);
+          if (dy < SAME_POSITION_THRESHOLD_PX && dx < SAME_POSITION_THRESHOLD_PX) {
+            samePositionCount++;
+            logger5.info(`humanScroll | \u26A0\uFE0F \u8B66\u544A: \u6EDA\u52A8\u540E\u4F4D\u7F6E\u672A\u53D8 (${samePositionCount}/${SAME_POSITION_LIMIT}). dy=${dy}`);
+            if (samePositionCount >= SAME_POSITION_LIMIT) {
+              logger5.warn("humanScroll | \u26A0\uFE0F \u68C0\u6D4B\u5230\u65E0\u6548\u6EDA\u52A8 (\u5143\u7D20\u53EF\u80FD\u662F Fixed \u6216\u4F4D\u4E8E\u4E0D\u53EF\u6EDA\u52A8\u7684\u5BB9\u5668)\uFF0C\u5F3A\u5236\u505C\u6B62\uFF0C\u5C1D\u8BD5\u76F4\u63A5\u4EA4\u4E92");
+              return { element, didScroll, restore };
+            }
+          } else {
+            samePositionCount = 0;
+          }
+        }
+        if (currentRect) lastRect = currentRect;
+        if (status.code === VISIBILITY_CODE.OBSTRUCTED && status.obstruction) {
+          logger5.info(`humanScroll | \u88AB\u906E\u6321: <${status.obstruction.tag}.${status.obstruction.className}>`);
         }
-        logger5.debug(`humanScroll | \u6B65\u9AA4 ${i + 1}/${maxSteps}: ${status.reason} ${status.direction ? `(${status.direction})` : ""}`);
-        if (status.code === "OBSTRUCTED" && status.obstruction) {
-          logger5.debug(`humanScroll | \u88AB\u4EE5\u4E0B\u5143\u7D20\u906E\u6321 <${status.obstruction.tag} id="${status.obstruction.id}">`);
+        if (status.code === VISIBILITY_CODE.OBSTRUCTED && status.isFixed) {
+          logger5.warn("humanScroll | \u5143\u7D20\u4E3A Fixed \u4E14\u88AB\u906E\u6321\uFF0C\u505C\u6B62\u6EDA\u52A8\u5C1D\u8BD5");
+          return { element, didScroll, restore };
+        }
+        if (!status.canScroll) {
+          logger5.warn("humanScroll | \u5F53\u524D\u5BB9\u5668\u4E0D\u53EF\u6EDA\u52A8\uFF0C\u505C\u6B62\u6EDA\u52A8\u5C1D\u8BD5");
+          return { element, didScroll, restore };
         }
         let deltaY = 0;
-        if (status.code === "OUT_OF_VIEWPORT") {
-          if (status.direction === "down") {
+        if (status.code === VISIBILITY_CODE.OUT_OF_VIEWPORT) {
+          if (status.direction === SCROLL_DIRECTION.DOWN) {
             deltaY = minStep + Math.random() * (maxStep - minStep);
-          } else if (status.direction === "up") {
+          } else if (status.direction === SCROLL_DIRECTION.UP) {
             deltaY = -(minStep + Math.random() * (maxStep - minStep));
           } else {
             deltaY = 100;
           }
-        } else if (status.code === "OBSTRUCTED") {
+        } else if (status.code === VISIBILITY_CODE.OBSTRUCTED) {
           const isBottomHalf = status.cy > status.viewH / 2;
-          const direction = isBottomHalf ? 1 : -1;
-          deltaY = direction * (minStep + Math.random() * 50);
+          const dir = isBottomHalf ? 1 : -1;
+          deltaY = dir * (minStep + Math.random() * 50);
         }
         if (i === 0 || Math.random() < 0.2) {
           const viewSize = page.viewportSize();
           if (viewSize) {
-            const safeX = viewSize.width * 0.5 + (Math.random() - 0.5) * 100;
-            const safeY = viewSize.height * 0.5 + (Math.random() - 0.5) * 100;
-            await cursor.actions.move({ x: safeX, y: safeY });
+            const safeX = viewSize.width * 0.5 + (Math.random() - 0.5) * SAFE_MOUSE_JITTER_PX;
+            const safeY = viewSize.height * 0.5 + (Math.random() - 0.5) * SAFE_MOUSE_JITTER_PX;
+            await cursor.actions.move({ x: safeX, y: safeY }).catch(() => {
+            });
           }
         }
+        if (!status.isWindow) {
+          await moveMouseToRect(status.targetRect);
+        }
         await page.mouse.wheel(0, deltaY);
+        if (typeof status.scrollTargetIndex === "number") {
+          const prev = scrollDeltas.get(status.scrollTargetIndex) || 0;
+          scrollDeltas.set(status.scrollTargetIndex, prev + deltaY);
+        }
         didScroll = true;
-        await (0, import_delay2.default)(this.jitterMs(100 + Math.random() * 150, 0.2));
+        await (0, import_delay2.default)(this.jitterMs(150 + Math.random() * 100, 0.2));
       }
-      logger5.warn(`humanScroll | \u5728 ${maxSteps} \u6B65\u540E\u65E0\u6CD5\u786E\u4FDD\u53EF\u89C1\u6027`);
-      return { element, didScroll };
+      logger5.warn(`humanScroll | \u26A0\uFE0F \u8FBE\u5230\u6700\u5927\u6B65\u6570 (${maxSteps}) \u4ECD\u65E0\u6CD5\u5B8C\u5168\u53EF\u89C1\uFF0C\u653E\u5F03\u6EDA\u52A8`);
+      return { element, didScroll, restore };
     } catch (error) {
       logger5.fail("humanScroll", error);
       throw error;
@@ -716,7 +1023,7 @@ var Humanize = {
    * 人类化点击 - 使用 ghost-cursor 模拟人类鼠标移动轨迹并点击
    * 
    * @param {import('playwright').Page} page
-   * @param {string|import('playwright').ElementHandle} [target] - CSS 选择器或元素句柄。如果为空，则点击当前鼠标位置
+   * @param {string|import('playwright').ElementHandle|import('playwright').Locator} [target] - CSS 选择器、元素句柄或 Locator。如果为空，则点击当前鼠标位置
    * @param {Object} [options]
    * @param {number} [options.reactionDelay=250] - 反应延迟基础值 (ms)，实际 ±30% 抖动
    * @param {boolean} [options.throwOnMissing=true] - 元素不存在时是否抛出错误
@@ -725,8 +1032,10 @@ var Humanize = {
   async humanClick(page, target, options = {}) {
     const cursor = $GetCursor(page);
     const { reactionDelay = 250, throwOnMissing = true, scrollIfNeeded = true, restore = false } = options;
-    const targetDesc = target == null ? "Current Position" : typeof target === "string" ? target : "ElementHandle";
+    const targetDesc = target == null ? "Current Position" : typeof target === "string" ? target : isLocatorLike(target) ? "Locator" : "ElementHandle";
     logger5.start("humanClick", `target=${targetDesc}`);
+    let element = null;
+    let owned = false;
     const restoreOnce = async () => {
       if (restoreOnce.restored) return;
       restoreOnce.restored = true;
@@ -745,18 +1054,15 @@ var Humanize = {
         logger5.success("humanClick", "Clicked current position");
         return true;
       }
-      let element;
-      if (typeof target === "string") {
-        element = await page.$(target);
-        if (!element) {
-          if (throwOnMissing) {
-            throw new Error(`\u627E\u4E0D\u5230\u5143\u7D20 ${target}`);
-          }
-          logger5.warn(`humanClick: \u5143\u7D20\u4E0D\u5B58\u5728\uFF0C\u8DF3\u8FC7\u70B9\u51FB ${target}`);
-          return false;
+      const resolved = await resolveElementHandle(page, target);
+      element = resolved.element;
+      owned = resolved.owned;
+      if (!element) {
+        if (throwOnMissing) {
+          throw new Error(`\u627E\u4E0D\u5230\u5143\u7D20 ${targetDesc}`);
         }
-      } else {
-        element = target;
+        logger5.warn(`humanClick: \u5143\u7D20\u4E0D\u5B58\u5728\uFF0C\u8DF3\u8FC7\u70B9\u51FB ${targetDesc}`);
+        return false;
       }
       if (scrollIfNeeded) {
         const { restore: restoreFn, didScroll } = await this.humanScroll(page, element);
@@ -765,6 +1071,7 @@ var Humanize = {
       const box = await element.boundingBox();
       if (!box) {
         await restoreOnce();
+        await disposeElementHandle(element, owned);
         if (throwOnMissing) {
           throw new Error("\u65E0\u6CD5\u83B7\u53D6\u5143\u7D20\u4F4D\u7F6E");
         }
@@ -777,10 +1084,12 @@ var Humanize = {
       await (0, import_delay2.default)(this.jitterMs(reactionDelay, 0.4));
       await cursor.actions.click();
       await restoreOnce();
+      await disposeElementHandle(element, owned);
       logger5.success("humanClick");
       return true;
     } catch (error) {
       await restoreOnce();
+      await disposeElementHandle(element, owned);
       logger5.fail("humanClick", error);
       throw error;
     }
@@ -917,34 +1226,6 @@ var Humanize = {
       logger5.fail("warmUpBrowsing", error);
       throw error;
     }
-  },
-  /**
-   * 自然滚动 - 带惯性、减速效果和随机抖动
-   * @param {import('playwright').Page} page
-   * @param {'up' | 'down'} [direction='down'] - 滚动方向
-   * @param {number} [distance=300] - 总滚动距离基础值 (px)，±15% 抖动
-   * @param {number} [baseSteps=5] - 分几步完成基础值，±1 随机
-   */
-  async naturalScroll(page, direction = "down", distance = 300, baseSteps = 5) {
-    const steps = Math.max(3, baseSteps + Math.floor(Math.random() * 3) - 1);
-    const actualDistance = this.jitterMs(distance, 0.15);
-    logger5.start("naturalScroll", `dir=${direction}, dist=${actualDistance}, steps=${steps}`);
-    const sign = direction === "down" ? 1 : -1;
-    const stepDistance = actualDistance / steps;
-    try {
-      for (let i = 0; i < steps; i++) {
-        const factor = 1 - i / steps * 0.5;
-        const jitter = 0.9 + Math.random() * 0.2;
-        const scrollAmount = stepDistance * factor * sign * jitter;
-        await page.mouse.wheel(0, scrollAmount);
-        const baseDelay = 60 + i * 25;
-        await (0, import_delay2.default)(this.jitterMs(baseDelay, 0.3));
-      }
-      logger5.success("naturalScroll");
-    } catch (error) {
-      logger5.fail("naturalScroll", error);
-      throw error;
-    }
   }
 };