@skrillex1224/playwright-toolkit 2.1.37 → 2.1.39

package/dist/index.cjs

@@ -57,10 +57,220 @@ var Status = {
 var FAILED_KEY_SEPARATOR = "::<@>::";
 var PresetOfLiveViewKey = "LIVE_VIEW_SCREENSHOT";
 
-// src/internal/logger.js
+// src/logger.js
 var import_crawlee = require("crawlee");
+var formatLine = (prefix, icon, message) => {
+  const parts = [];
+  if (prefix) parts.push(`[${prefix}]`);
+  if (icon) parts.push(icon);
+  if (message) parts.push(message);
+  return parts.join(" ").trim();
+};
+var ANSI = {
+  reset: "\x1B[0m",
+  gray: "\x1B[90m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m"
+};
+var colorize = (text, color) => {
+  if (!text || !color) return text;
+  return `${color}${text}${ANSI.reset}`;
+};
+var createBaseLogger = (prefix = "") => {
+  const name = prefix ? String(prefix) : "";
+  return {
+    info: (message) => import_crawlee.log.info(colorize(formatLine(name, "\u{1F4D6}", message), ANSI.cyan)),
+    success: (message) => import_crawlee.log.info(colorize(formatLine(name, "\u2705", message), ANSI.green)),
+    warning: (message) => import_crawlee.log.warning(colorize(formatLine(name, "\u26A0\uFE0F", message), ANSI.yellow)),
+    error: (message) => import_crawlee.log.error(colorize(formatLine(name, "\u274C", message), ANSI.red)),
+    debug: (message) => import_crawlee.log.debug(colorize(formatLine(name, "\u{1F539}", message), ANSI.gray)),
+    start: (message) => import_crawlee.log.info(colorize(formatLine(name, "\u{1F537}", message), ANSI.blue))
+  };
+};
+var STEP_PREFIX = "\u6B65\u9AA4:";
+var STEP_SEPARATOR = " | ";
+var STEP_EMOJIS = [
+  { match: "\u4EFB\u52A1", emoji: "\u{1F9ED}" },
+  { match: "\u8FD0\u884C\u6A21\u5F0F", emoji: "\u{1F9E9}" },
+  { match: "\u767B\u5F55", emoji: "\u{1F510}" },
+  { match: "\u73AF\u5883", emoji: "\u{1F9EA}" },
+  { match: "\u8F93\u5165", emoji: "\u2328\uFE0F" },
+  { match: "\u53D1\u9001", emoji: "\u{1F4E4}" },
+  { match: "\u54CD\u5E94\u76D1\u542C", emoji: "\u{1F4E1}" },
+  { match: "\u7B49\u5F85\u54CD\u5E94", emoji: "\u23F3" },
+  { match: "\u6D41\u5F0F", emoji: "\u{1F9F5}" },
+  { match: "\u5F15\u7528", emoji: "\u{1F4CE}" },
+  { match: "\u622A\u56FE", emoji: "\u{1F5BC}\uFE0F" },
+  { match: "\u5206\u4EAB\u94FE\u63A5", emoji: "\u{1F517}" },
+  { match: "\u6570\u636E\u63A8\u9001", emoji: "\u{1F4E6}" },
+  { match: "\u5F39\u7A97", emoji: "\u{1FA9F}" }
+];
+var STATUS_EMOJIS = [
+  { match: "\u5F00\u59CB", emoji: "\u{1F680}" },
+  { match: "\u5B8C\u6210", emoji: "\u2705" },
+  { match: "\u6210\u529F", emoji: "\u2705" },
+  { match: "\u5931\u8D25", emoji: "\u274C" },
+  { match: "\u8DF3\u8FC7", emoji: "\u23ED\uFE0F" },
+  { match: "\u8D85\u65F6", emoji: "\u23F1\uFE0F" },
+  { match: "\u91CD\u8BD5", emoji: "\u{1F501}" },
+  { match: "\u7ED3\u675F", emoji: "\u{1F3C1}" },
+  { match: "\u5DF2\u914D\u7F6E", emoji: "\u{1F9F7}" },
+  { match: "\u5DF2\u68C0\u6D4B", emoji: "\u{1F50E}" }
+];
+var toErrorMessage = (error) => {
+  if (!error) return "";
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+};
+var decorateLabel = (label, mappings) => {
+  if (!label) return "";
+  const mapping = mappings.find((item) => label.includes(item.match));
+  if (!mapping) return label;
+  return `${mapping.emoji} ${label}`;
+};
+var normalizeSnippet = (snippet, maxLen = 120) => {
+  if (!snippet) return "";
+  const text = String(snippet).replace(/\s+/g, " ").trim();
+  if (!text) return "";
+  const cleaned = text.replace(/"/g, "'");
+  if (cleaned.length <= maxLen) return cleaned;
+  return `${cleaned.slice(0, maxLen)}...`;
+};
+var buildStepLine = (step, status, details = []) => {
+  const parts = [];
+  const decoratedStep = step ? decorateLabel(step, STEP_EMOJIS) : "";
+  const base = decoratedStep ? `${STEP_PREFIX} ${decoratedStep}` : STEP_PREFIX;
+  parts.push(base.trim());
+  if (status) parts.push(decorateLabel(status, STATUS_EMOJIS));
+  const detailParts = details.filter(Boolean);
+  if (detailParts.length > 0) {
+    parts.push(...detailParts);
+  }
+  return parts.join(STEP_SEPARATOR);
+};
+var createThrottle = () => {
+  const lastMap = /* @__PURE__ */ new Map();
+  return (key, intervalMs, fn) => {
+    const now = Date.now();
+    const last = lastMap.get(key) || 0;
+    if (now - last >= intervalMs) {
+      lastMap.set(key, now);
+      fn();
+    }
+  };
+};
+var createTemplateLogger = (baseLogger = createBaseLogger()) => {
+  const throttle = createThrottle();
+  const info = (line) => baseLogger.info(line);
+  const success = (line) => baseLogger.success(line);
+  const warning = (line) => baseLogger.warning(line);
+  const error = (line) => baseLogger.error(line);
+  const debug = (line) => baseLogger.debug(line);
+  const start = (line) => baseLogger.start(line);
+  const stepInfo = (step, status, details = []) => info(buildStepLine(step, status, details));
+  const stepSuccess = (step, status, details = []) => success(buildStepLine(step, status, details));
+  const stepWarn = (step, status, details = []) => warning(buildStepLine(step, status, details));
+  const stepError = (step, status, details = []) => error(buildStepLine(step, status, details));
+  const stepStart = (step, status, details = []) => start(buildStepLine(step, status, details));
+  return {
+    step: (step, status, details, level = "info") => {
+      if (level === "error") return stepError(step, status, details);
+      if (level === "warn" || level === "warning") return stepWarn(step, status, details);
+      return stepInfo(step, status, details);
+    },
+    taskStart: (url) => stepStart("\u4EFB\u52A1", "\u5F00\u59CB", [url ? `url=${url}` : ""]),
+    taskSuccess: () => stepSuccess("\u4EFB\u52A1", "\u5B8C\u6210"),
+    taskFail: (url, err) => stepError("\u4EFB\u52A1", "\u5931\u8D25", [
+      url ? `url=${url}` : "",
+      err ? `err=${toErrorMessage(err)}` : ""
+    ]),
+    runtimeHeadless: () => stepWarn("\u8FD0\u884C\u6A21\u5F0F", "Apify \u73AF\u5883\u5F3A\u5236\u65E0\u5934"),
+    loginInjectSuccess: (detail) => stepSuccess("\u767B\u5F55\u6001\u6CE8\u5165", "\u6210\u529F", [detail ? `detail=${detail}` : ""]),
+    loginInjectSkip: (reason) => stepWarn("\u767B\u5F55\u6001\u6CE8\u5165", "\u8DF3\u8FC7", [reason ? `\u539F\u56E0=${reason}` : ""]),
+    loginInjectFail: (err) => stepError("\u767B\u5F55\u6001\u6CE8\u5165", "\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    loginVerifySuccess: (detail) => stepSuccess("\u767B\u5F55\u9A8C\u8BC1", "\u6210\u529F", [detail ? `detail=${detail}` : ""]),
+    loginVerifySkip: (reason) => stepWarn("\u767B\u5F55\u9A8C\u8BC1", "\u8DF3\u8FC7", [reason ? `\u539F\u56E0=${reason}` : ""]),
+    loginVerifyFail: (err) => stepError("\u767B\u5F55\u9A8C\u8BC1", "\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    envCheckSuccess: (detail) => stepSuccess("\u73AF\u5883\u68C0\u67E5", "\u6210\u529F", [detail ? `detail=${detail}` : ""]),
+    envCheckFail: (err) => stepError("\u73AF\u5883\u68C0\u67E5", "\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    inputQuery: (query) => stepStart("\u8F93\u5165\u67E5\u8BE2", "\u5F00\u59CB", [query ? `query=${query}` : ""]),
+    sendAction: () => stepInfo("\u53D1\u9001\u8BF7\u6C42", "\u70B9\u51FB\u53D1\u9001"),
+    responseListenStart: (label, timeoutSec) => stepStart("\u54CD\u5E94\u76D1\u542C", "\u5F00\u59CB", [
+      label ? `\u76EE\u6807=${label}` : "",
+      timeoutSec ? `timeout=${timeoutSec}s` : ""
+    ]),
+    responseListenReady: (label) => stepInfo("\u54CD\u5E94\u76D1\u542C", "\u5DF2\u914D\u7F6E", [label ? `\u76EE\u6807=${label}` : ""]),
+    responseListenDetected: (label) => stepSuccess("\u54CD\u5E94\u76D1\u542C", "\u5DF2\u68C0\u6D4B", [label ? `\u76EE\u6807=${label}` : ""]),
+    responseListenTimeout: (label, err) => stepError("\u54CD\u5E94\u76D1\u542C", "\u8D85\u65F6", [
+      label ? `\u76EE\u6807=${label}` : "",
+      err ? `err=${toErrorMessage(err)}` : ""
+    ]),
+    responseListenEnd: (label) => stepInfo("\u54CD\u5E94\u76D1\u542C", "\u7ED3\u675F", [label ? `\u76EE\u6807=${label}` : ""]),
+    streamChunk: (length, snippet) => throttle(
+      "stream-chunk",
+      2e3,
+      () => stepInfo("\u6D41\u5F0F\u7247\u6BB5", "", [
+        length !== void 0 ? `len=${length}` : "",
+        snippet ? `preview="${normalizeSnippet(snippet)}"` : ""
+      ])
+    ),
+    streamEventsParsed: (count) => throttle(
+      "stream-events",
+      4e3,
+      () => stepInfo("\u6D41\u5F0F\u4E8B\u4EF6\u89E3\u6790", "\u5B8C\u6210", [count !== void 0 ? `count=${count}` : ""])
+    ),
+    streamCompleteEvent: () => stepSuccess("\u6D41\u5F0F\u4E8B\u4EF6", "\u5B8C\u6210\u4E8B\u4EF6\u5DF2\u6355\u83B7"),
+    streamEnd: () => stepInfo("\u6D41\u5F0F\u54CD\u5E94", "\u7ED3\u675F"),
+    responseWaitStart: (label) => stepStart("\u7B49\u5F85\u54CD\u5E94", "\u5F00\u59CB", [label ? `\u76EE\u6807=${label}` : ""]),
+    responseWaitSuccess: (label) => stepSuccess("\u7B49\u5F85\u54CD\u5E94", "\u5B8C\u6210", [label ? `\u76EE\u6807=${label}` : ""]),
+    responseWaitFail: (label, err) => stepWarn("\u7B49\u5F85\u54CD\u5E94", "\u5931\u8D25", [
+      label ? `\u76EE\u6807=${label}` : "",
+      err ? `err=${toErrorMessage(err)}` : ""
+    ]),
+    responseWaitRetry: (label, attempt) => stepWarn("\u7B49\u5F85\u54CD\u5E94", "\u91CD\u8BD5", [
+      label ? `\u76EE\u6807=${label}` : "",
+      attempt !== void 0 ? `\u5C1D\u8BD5=${attempt}` : ""
+    ]),
+    referenceExpandStart: (label) => stepStart("\u5F15\u7528\u5C55\u5F00", "\u5F00\u59CB", [label ? `\u76EE\u6807=${label}` : ""]),
+    referenceExpandFail: (err) => stepWarn("\u5F15\u7528\u5C55\u5F00", "\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    screenshotStart: () => stepStart("\u622A\u56FE", "\u5F00\u59CB"),
+    screenshotSuccess: () => stepSuccess("\u622A\u56FE", "\u6210\u529F"),
+    screenshotFail: (err) => stepWarn("\u622A\u56FE", "\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    shareStart: () => stepStart("\u5206\u4EAB\u94FE\u63A5", "\u5F00\u59CB"),
+    shareProgress: (label) => stepInfo("\u5206\u4EAB\u94FE\u63A5", "\u6B65\u9AA4", [label ? `\u6B65\u9AA4=${label}` : ""]),
+    shareSuccess: (link) => stepSuccess("\u5206\u4EAB\u94FE\u63A5", "\u6210\u529F", [link ? `\u94FE\u63A5=${link}` : ""]),
+    shareFail: (err) => stepWarn("\u5206\u4EAB\u94FE\u63A5", "\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    shareSkip: (reason) => stepWarn("\u5206\u4EAB\u94FE\u63A5", "\u8DF3\u8FC7", [reason ? `\u539F\u56E0=${reason}` : ""]),
+    dataPushSuccess: (label) => stepSuccess("\u6570\u636E\u63A8\u9001", "\u6210\u529F", [label ? `\u8BF4\u660E=${label}` : ""]),
+    dataPushFail: (err) => stepError("\u6570\u636E\u63A8\u9001", "\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    popupDetected: (detail) => stepWarn("\u5F39\u7A97\u5904\u7406", "\u68C0\u6D4B\u5230\u906E\u7F69", [detail ? `detail=${detail}` : ""]),
+    popupCloseAttempt: (detail) => stepInfo("\u5F39\u7A97\u5904\u7406", "\u5C1D\u8BD5\u5173\u95ED", [detail ? `detail=${detail}` : ""]),
+    popupCloseSuccess: () => stepSuccess("\u5F39\u7A97\u5904\u7406", "\u5173\u95ED\u5B8C\u6210"),
+    popupCloseFail: (err) => stepWarn("\u5F39\u7A97\u5904\u7406", "\u5173\u95ED\u5931\u8D25", [err ? `err=${toErrorMessage(err)}` : ""]),
+    info: (message) => info(message),
+    success: (message) => success(message),
+    warning: (message) => warning(message),
+    error: (message) => error(message),
+    debug: (message) => debug(message),
+    start: (message) => start(message)
+  };
+};
+var Logger = {
+  ...createBaseLogger(),
+  useTemplate: () => createTemplateLogger()
+};
+
+// src/internal/logger.js
 function createLogger(moduleName) {
-  const prefix = `[${moduleName}]`;
+  const baseLogger = createBaseLogger(moduleName);
   return {
     /**
      * 方法开始日志
@@ -69,7 +279,7 @@ function createLogger(moduleName) {
      */
     start(methodName, params = "") {
       const paramStr = params ? ` (${params})` : "";
-      import_crawlee.log.info(`${prefix} \u{1F537} ${methodName} \u5F00\u59CB${paramStr}`);
+      baseLogger.start(`${methodName} \u5F00\u59CB${paramStr}`);
     },
     /**
      * 方法成功日志
@@ -78,7 +288,7 @@ function createLogger(moduleName) {
      */
     success(methodName, result = "") {
       const resultStr = result ? ` (${result})` : "";
-      import_crawlee.log.info(`${prefix} \u2705 ${methodName} \u5B8C\u6210${resultStr}`);
+      baseLogger.success(`${methodName} \u5B8C\u6210${resultStr}`);
     },
     /**
      * 方法失败日志
@@ -87,28 +297,28 @@ function createLogger(moduleName) {
      */
     fail(methodName, error) {
       const message = error instanceof Error ? error.message : error;
-      import_crawlee.log.error(`${prefix} \u274C ${methodName} \u5931\u8D25: ${message}`);
+      baseLogger.error(`${methodName} \u5931\u8D25: ${message}`);
     },
     /**
      * 调试日志
      * @param {string} message - 详情
      */
     debug(message) {
-      import_crawlee.log.debug(`${prefix} \u{1F539} ${message}`);
+      baseLogger.debug(message);
     },
     /**
      * 警告日志
      * @param {string} message - 警告信息
      */
     warn(message) {
-      import_crawlee.log.warning(`${prefix} \u26A0\uFE0F ${message}`);
+      baseLogger.warning(message);
     },
     /**
      * 普通信息日志
      * @param {string} message - 信息
      */
     info(message) {
-      import_crawlee.log.info(`${prefix} \u{1F4D6} ${message}`);
+      baseLogger.info(message);
     }
   };
 }
@@ -357,6 +567,8 @@ var Utils = {
    * @param {import('playwright').Page} page - Playwright page 对象
    * @param {Object} [options] - 配置选项
    * @param {number} [options.buffer] - 额外缓冲高度 (默认: 视口高度的一半)
+   * @param {boolean} [options.restore] - 截图后是否恢复页面高度和样式 (默认: false)
+   * @param {number} [options.maxHeight] - 最大截图高度 (默认: 8000px)
    * @returns {Promise<string>} - base64 编码的 PNG 图片
    */
   async fullPageScreenshot(page, options = {}) {
@@ -364,15 +576,17 @@ var Utils = {
     const originalViewport = page.viewportSize();
     const defaultBuffer = Math.round((originalViewport?.height || 1080) / 2);
     const buffer = options.buffer ?? defaultBuffer;
+    const restore = options.restore ?? false;
+    const maxHeight = options.maxHeight ?? 8e3;
     try {
       const maxScrollHeight = await page.evaluate(() => {
-        let maxHeight = document.body.scrollHeight;
+        let maxHeight2 = document.body.scrollHeight;
         document.querySelectorAll("*").forEach((el) => {
           const style = window.getComputedStyle(el);
           const overflowY = style.overflowY;
           if ((overflowY === "auto" || overflowY === "scroll") && el.scrollHeight > el.clientHeight) {
-            if (el.scrollHeight > maxHeight) {
-              maxHeight = el.scrollHeight;
+            if (el.scrollHeight > maxHeight2) {
+              maxHeight2 = el.scrollHeight;
             }
             el.dataset.pkOrigOverflow = el.style.overflow;
             el.dataset.pkOrigHeight = el.style.height;
@@ -383,11 +597,12 @@ var Utils = {
             el.style.maxHeight = "none";
           }
         });
-        return maxHeight;
+        return maxHeight2;
       });
+      const targetHeight = Math.min(maxScrollHeight + buffer, maxHeight);
       await page.setViewportSize({
         width: originalViewport?.width || 1280,
-        height: maxScrollHeight + buffer
+        height: targetHeight
       });
       await (0, import_delay.default)(1e3);
       const buffer_ = await page.screenshot({
@@ -397,19 +612,21 @@ var Utils = {
       logger2.success("fullPageScreenshot", `captured ${Math.round(buffer_.length / 1024)} KB`);
       return buffer_.toString("base64");
     } finally {
-      await page.evaluate(() => {
-        document.querySelectorAll(".__pk_expanded__").forEach((el) => {
-          el.style.overflow = el.dataset.pkOrigOverflow || "";
-          el.style.height = el.dataset.pkOrigHeight || "";
-          el.style.maxHeight = el.dataset.pkOrigMaxHeight || "";
-          delete el.dataset.pkOrigOverflow;
-          delete el.dataset.pkOrigHeight;
-          delete el.dataset.pkOrigMaxHeight;
-          el.classList.remove("__pk_expanded__");
+      if (restore) {
+        await page.evaluate(() => {
+          document.querySelectorAll(".__pk_expanded__").forEach((el) => {
+            el.style.overflow = el.dataset.pkOrigOverflow || "";
+            el.style.height = el.dataset.pkOrigHeight || "";
+            el.style.maxHeight = el.dataset.pkOrigMaxHeight || "";
+            delete el.dataset.pkOrigOverflow;
+            delete el.dataset.pkOrigHeight;
+            delete el.dataset.pkOrigMaxHeight;
+            el.classList.remove("__pk_expanded__");
+          });
         });
-      });
-      if (originalViewport) {
-        await page.setViewportSize(originalViewport);
+        if (originalViewport) {
+          await page.setViewportSize(originalViewport);
+        }
       }
     }
   }
@@ -1532,6 +1749,181 @@ function isIgnorableError(error) {
   return msg.includes("already handled") || msg.includes("Target closed") || msg.includes("closed");
 }
 
+// src/mutation.js
+var import_uuid2 = require("uuid");
+var logger9 = createLogger("Mutation");
+function generateKey(prefix) {
+  return `__${prefix}_${(0, import_uuid2.v4)().replace(/-/g, "_")}`;
+}
+var Mutation = {
+  /**
+   * 等待 DOM 元素稳定（无变化）
+   * 使用 MutationObserver 监控指定元素，当元素持续一段时间无变化时 resolve
+   * 
+   * @param {import('playwright').Page} page - Playwright page 对象
+   * @param {string | string[]} selectors - 要监控的 CSS 选择器，单个或多个
+   * @param {Object} [options] - 配置选项
+   * @param {number} [options.stableTime] - 无变化持续时间后 resolve (毫秒, 默认: 5000)
+   * @param {number} [options.timeout] - 整体超时时间 (毫秒, 默认: 60000)
+   * @param {Function} [options.onMutation] - 变化时的回调钩子 (mutationCount: number) => void
+   * @returns {Promise<{ mutationCount: number, stableTime: number }>} - 返回变化次数和稳定时长
+   */
+  async waitForStable(page, selectors, options = {}) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    const stableTime = options.stableTime ?? 5e3;
+    const timeout = options.timeout ?? 6e4;
+    const onMutation = options.onMutation;
+    logger9.start("waitForStable", `\u76D1\u63A7 ${selectorList.length} \u4E2A\u9009\u62E9\u5668, \u7A33\u5B9A\u65F6\u95F4=${stableTime}ms`);
+    const eventName = generateKey("pk_mut_evt");
+    const callbackName = generateKey("pk_mut_cb");
+    if (onMutation) {
+      try {
+        await page.exposeFunction(callbackName, (count) => {
+          try {
+            onMutation(count);
+          } catch (e) {
+          }
+        });
+      } catch (e) {
+      }
+    }
+    const result = await page.evaluate(
+      async ({ selectorList: selectorList2, stableTime: stableTime2, timeout: timeout2, eventName: eventName2, callbackName: callbackName2, hasCallback }) => {
+        return new Promise((resolve, reject) => {
+          let mutationCount = 0;
+          let stableTimer = null;
+          let timeoutTimer = null;
+          const observers = [];
+          const cleanup = () => {
+            observers.forEach((obs) => obs.disconnect());
+            if (stableTimer) clearTimeout(stableTimer);
+            if (timeoutTimer) clearTimeout(timeoutTimer);
+          };
+          const resetStableTimer = () => {
+            if (stableTimer) clearTimeout(stableTimer);
+            stableTimer = setTimeout(() => {
+              cleanup();
+              resolve({ mutationCount, stableTime: stableTime2 });
+            }, stableTime2);
+          };
+          timeoutTimer = setTimeout(() => {
+            cleanup();
+            reject(new Error(`waitForStable \u8D85\u65F6 (${timeout2}ms), \u5DF2\u68C0\u6D4B\u5230 ${mutationCount} \u6B21\u53D8\u5316`));
+          }, timeout2);
+          selectorList2.forEach((selector) => {
+            const elements = document.querySelectorAll(selector);
+            elements.forEach((element) => {
+              const observer = new MutationObserver((mutations) => {
+                mutationCount += mutations.length;
+                if (hasCallback && window[callbackName2]) {
+                  window[callbackName2](mutationCount);
+                }
+                resetStableTimer();
+              });
+              observer.observe(element, {
+                childList: true,
+                subtree: true,
+                characterData: true,
+                attributes: true
+              });
+              observers.push(observer);
+            });
+          });
+          if (observers.length === 0) {
+            cleanup();
+            resolve({ mutationCount: 0, stableTime: 0 });
+            return;
+          }
+          resetStableTimer();
+        });
+      },
+      { selectorList, stableTime, timeout, eventName, callbackName, hasCallback: !!onMutation }
+    );
+    logger9.success("waitForStable", `DOM \u7A33\u5B9A, \u603B\u5171 ${result.mutationCount} \u6B21\u53D8\u5316`);
+    return result;
+  },
+  /**
+   * 创建一个持续监控 DOM 变化的监控器
+   * 
+   * @param {import('playwright').Page} page - Playwright page 对象
+   * @param {string | string[]} selectors - 要监控的 CSS 选择器
+   * @param {Object} [options] - 配置选项
+   * @param {Function} [options.onMutation] - 变化时的回调 (mutationCount: number) => void
+   * @returns {Promise<{ stop: () => Promise<{ totalMutations: number }> }>} - 返回停止函数
+   */
+  async createMonitor(page, selectors, options = {}) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    const onMutation = options.onMutation;
+    logger9.start("createMonitor", `\u76D1\u63A7 ${selectorList.length} \u4E2A\u9009\u62E9\u5668`);
+    const monitorKey = generateKey("pk_mon");
+    const callbackName = generateKey("pk_mon_cb");
+    const cleanerName = generateKey("pk_mon_clean");
+    if (onMutation) {
+      try {
+        await page.exposeFunction(callbackName, (count) => {
+          try {
+            onMutation(count);
+          } catch (e) {
+          }
+        });
+      } catch (e) {
+      }
+    }
+    await page.evaluate(({ selectorList: selectorList2, monitorKey: monitorKey2, callbackName: callbackName2, cleanerName: cleanerName2, hasCallback }) => {
+      const monitor = {
+        observers: [],
+        totalMutations: 0,
+        running: true
+      };
+      selectorList2.forEach((selector) => {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach((element) => {
+          const observer = new MutationObserver((mutations) => {
+            if (!monitor.running) return;
+            monitor.totalMutations += mutations.length;
+            if (hasCallback && window[callbackName2]) {
+              window[callbackName2](monitor.totalMutations);
+            }
+          });
+          observer.observe(element, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true
+          });
+          monitor.observers.push(observer);
+        });
+      });
+      window[monitorKey2] = monitor;
+      window[cleanerName2] = () => {
+        monitor.running = false;
+        monitor.observers.forEach((obs) => obs.disconnect());
+        const total = monitor.totalMutations;
+        delete window[monitorKey2];
+        delete window[cleanerName2];
+        return total;
+      };
+    }, { selectorList, monitorKey, callbackName, cleanerName, hasCallback: !!onMutation });
+    logger9.success("createMonitor", "\u76D1\u63A7\u5668\u5DF2\u542F\u52A8");
+    return {
+      stop: async () => {
+        let totalMutations = 0;
+        try {
+          totalMutations = await page.evaluate((cleanerName2) => {
+            if (window[cleanerName2]) {
+              return window[cleanerName2]();
+            }
+            return 0;
+          }, cleanerName);
+        } catch (e) {
+        }
+        logger9.success("createMonitor.stop", `\u76D1\u63A7\u5DF2\u505C\u6B62, \u5171 ${totalMutations} \u6B21\u53D8\u5316`);
+        return { totalMutations };
+      }
+    };
+  }
+};
+
 // index.js
 var usePlaywrightToolKit = () => {
   return {
@@ -1545,7 +1937,9 @@ var usePlaywrightToolKit = () => {
     Captcha,
     Sse,
     Errors: errors_exports,
-    Interception
+    Interception,
+    Mutation,
+    Logger
   };
 };
 // Annotate the CommonJS export names for ESM import in node: