@skrillex1224/playwright-toolkit 3.0.19 → 3.0.22

package/dist/index.cjs

@@ -495,6 +495,7 @@ function createInternalLogger(moduleName, explicitLogger) {
 
 // src/internals/screenshot.js
 var import_delay = __toESM(require("delay"), 1);
+var import_jimp = require("jimp");
 
 // src/internals/constants.js
 var PageRuntimeStateKey = "__playwright_toolkit_runtime_state__";
@@ -533,9 +534,19 @@ var FORCED_FULLPAGE_TYPE = "jpeg";
 var FORCED_FULLPAGE_QUALITY = 50;
 var SUPPORTED_TYPES = /* @__PURE__ */ new Set(["png", "jpeg", "webp"]);
 var EXPANDED_SCROLLABLE_CLASS = "__pk_expanded__";
+var STITCH_SCROLL_TARGET_ATTR = "data-pk-stitch-scroll-target";
 var DEFAULT_MAX_HEIGHT = 8e3;
 var DEFAULT_SETTLE_MS = 1e3;
 var DEFAULT_MOBILE_SETTLE_MS = 50;
+var DEFAULT_STITCH_SETTLE_MS = 120;
+var DEFAULT_STITCH_OVERLAP_PX = 24;
+var MIN_VIRTUALIZED_SCROLL_RATIO = 2.2;
+var MIN_SPARSE_SCROLL_RATIO = 4;
+var MOBILE_VIEWPORT_WIDTH_THRESHOLD = 520;
+var DEFAULT_QUALITY_RETRY_ATTEMPTS = 2;
+var DEFAULT_QUALITY_RETRY_DELAY_MS = 2500;
+var MIN_TRAILING_BLANK_GAP_PX = 320;
+var MIN_TRAILING_BLANK_GAP_RATIO = 0.12;
 var toPositiveNumber = (value, fallback = 0) => {
   const n = Number(value);
   if (!Number.isFinite(n) || n <= 0) return fallback;
@@ -558,7 +569,22 @@ var normalizeQuality = (value, type) => {
   if (rounded < 0 || rounded > 100) return void 0;
   return rounded;
 };
-var resolvePageDevice = (page) => normalizeDevice(page?.[PageRuntimeStateKey]?.device);
+var resolvePageDevice = async (page) => {
+  const declared = normalizeDevice(page?.[PageRuntimeStateKey]?.device);
+  if (declared === Device.Mobile) return Device.Mobile;
+  const viewport = await resolveCurrentViewportSize(page).catch(() => null);
+  const viewportWidth = Math.round(Number(viewport?.width) || 0);
+  if (viewportWidth > 0 && viewportWidth <= MOBILE_VIEWPORT_WIDTH_THRESHOLD) {
+    return Device.Mobile;
+  }
+  return declared;
+};
+var resolveStitchMode = (options = {}) => {
+  const raw = options.stitch ?? options.stitching ?? options.strategy;
+  if (raw === false || raw === "off" || raw === "none" || raw === "single") return "off";
+  if (raw === true || raw === "force" || raw === "stitched") return "force";
+  return "auto";
+};
 var buildFullPageClip = (metrics, viewport, maxClipHeight) => {
   const contentSize = metrics && typeof metrics === "object" ? metrics.contentSize || null : null;
   const width = Math.max(1, Math.ceil(viewport.width || contentSize?.width || 1));
@@ -905,10 +931,156 @@ var restoreAffixedElementsForExpandedScreenshot = async (page) => {
     });
   }, EXPANDED_SCROLLABLE_CLASS);
 };
+var measureMeaningfulContentBounds = async (page) => {
+  return await page.evaluate(() => {
+    const body = document.body;
+    if (!body) return null;
+    const viewportWidth = window.innerWidth || document.documentElement?.clientWidth || body.clientWidth || 0;
+    const viewportHeight = window.innerHeight || document.documentElement?.clientHeight || body.clientHeight || 0;
+    const scrollX = window.scrollX || window.pageXOffset || 0;
+    const scrollY = window.scrollY || window.pageYOffset || 0;
+    const bounds = {
+      left: Number.POSITIVE_INFINITY,
+      top: Number.POSITIVE_INFINITY,
+      right: 0,
+      bottom: 0,
+      nodes: 0
+    };
+    const isVisible = (el, style, rect) => {
+      if (!el || !style || !rect) return false;
+      if (style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse") return false;
+      if (Number(style.opacity) === 0) return false;
+      return rect.width > 1 && rect.height > 1;
+    };
+    const hasFixedAncestor = (el) => {
+      for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
+        const position = String(window.getComputedStyle(node).position || "").toLowerCase();
+        if (position === "fixed") {
+          return true;
+        }
+      }
+      return false;
+    };
+    const parseRgbColor = (value) => {
+      const raw = String(value || "").trim();
+      const match = raw.match(/rgba?\(([^)]+)\)/i);
+      if (!match) return null;
+      const parts = match[1].replace(/\//g, " ").split(/[,\s]+/).map((part) => part.trim()).filter(Boolean);
+      if (parts.length < 3) return null;
+      const normalizeChannel = (part) => {
+        if (part.endsWith("%")) {
+          return Math.max(0, Math.min(255, Number.parseFloat(part) * 2.55));
+        }
+        return Math.max(0, Math.min(255, Number.parseFloat(part)));
+      };
+      const alpha = parts.length >= 4 ? parts[3].endsWith("%") ? Number.parseFloat(parts[3]) / 100 : Number.parseFloat(parts[3]) : 1;
+      return {
+        r: normalizeChannel(parts[0]),
+        g: normalizeChannel(parts[1]),
+        b: normalizeChannel(parts[2]),
+        a: Number.isFinite(alpha) ? Math.max(0, Math.min(1, alpha)) : 1
+      };
+    };
+    const colorLuminance = (color) => {
+      const channel = (value) => {
+        const ratio = Math.max(0, Math.min(255, value)) / 255;
+        return ratio <= 0.03928 ? ratio / 12.92 : ((ratio + 0.055) / 1.055) ** 2.4;
+      };
+      return 0.2126 * channel(color.r) + 0.7152 * channel(color.g) + 0.0722 * channel(color.b);
+    };
+    const contrastRatio = (a, b) => {
+      const l1 = colorLuminance(a);
+      const l2 = colorLuminance(b);
+      const lighter = Math.max(l1, l2);
+      const darker = Math.min(l1, l2);
+      return (lighter + 0.05) / (darker + 0.05);
+    };
+    const resolveBackgroundColor = (el) => {
+      for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
+        const background = parseRgbColor(window.getComputedStyle(node).backgroundColor);
+        if (background && background.a > 0.2) {
+          return background;
+        }
+      }
+      return { r: 255, g: 255, b: 255, a: 1 };
+    };
+    const isLowInformationTextPaint = (el, style) => {
+      const color = parseRgbColor(style?.color);
+      if (!color) return false;
+      const opacity = Number(style.opacity);
+      if (color.a <= 0.08 || Number.isFinite(opacity) && opacity <= 0.18) {
+        return true;
+      }
+      const max = Math.max(color.r, color.g, color.b);
+      const min = Math.min(color.r, color.g, color.b);
+      if (!(min >= 224 && max - min <= 24 && color.a >= 0.85)) {
+        return false;
+      }
+      const background = resolveBackgroundColor(el);
+      return colorLuminance(background) > 0.76 && contrastRatio(color, background) < 1.35;
+    };
+    const addRect = (rect) => {
+      if (!rect || rect.width <= 1 || rect.height <= 1) return;
+      const left = Math.max(0, Math.floor(rect.left + scrollX));
+      const top = Math.max(0, Math.floor(rect.top + scrollY));
+      const right = Math.ceil(rect.right + scrollX);
+      const bottom = Math.ceil(rect.bottom + scrollY);
+      if (right <= left || bottom <= top) return;
+      bounds.left = Math.min(bounds.left, left);
+      bounds.top = Math.min(bounds.top, top);
+      bounds.right = Math.max(bounds.right, right);
+      bounds.bottom = Math.max(bounds.bottom, bottom);
+      bounds.nodes += 1;
+    };
+    const addElement = (el, { minArea = 12, text = false } = {}) => {
+      if (!el || el.nodeType !== 1 || hasFixedAncestor(el)) return;
+      const style = window.getComputedStyle(el);
+      if (text && isLowInformationTextPaint(el, style)) return;
+      const rects = Array.from(el.getClientRects ? el.getClientRects() : []);
+      rects.forEach((rect) => {
+        if (!isVisible(el, style, rect)) return;
+        if (rect.width * rect.height < minArea) return;
+        addRect(rect);
+      });
+    };
+    const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT);
+    let visitedTextNodes = 0;
+    while (walker.nextNode() && visitedTextNodes < 6e3) {
+      const node = walker.currentNode;
+      visitedTextNodes += 1;
+      const text = String(node.nodeValue || "").replace(/\s+/g, " ").trim();
+      if (text.length < 2) continue;
+      addElement(node.parentElement, { minArea: 8, text: true });
+    }
+    document.querySelectorAll("img,video,canvas,svg,picture").forEach((el) => {
+      addElement(el, { minArea: 900 });
+    });
+    if (!bounds.nodes || !Number.isFinite(bounds.left)) return null;
+    const paddingX = Math.max(16, Math.min(96, viewportWidth * 0.04));
+    const paddingY = Math.max(24, Math.min(160, viewportHeight * 0.18));
+    return {
+      left: Math.max(0, Math.floor(bounds.left - paddingX)),
+      top: Math.max(0, Math.floor(bounds.top - paddingY)),
+      right: Math.ceil(bounds.right + paddingX),
+      bottom: Math.ceil(bounds.bottom + paddingY),
+      width: Math.max(1, Math.ceil(bounds.right - bounds.left)),
+      height: Math.max(1, Math.ceil(bounds.bottom - bounds.top)),
+      nodes: bounds.nodes,
+      viewport: {
+        width: Math.max(1, Math.ceil(viewportWidth || 1)),
+        height: Math.max(1, Math.ceil(viewportHeight || 1))
+      }
+    };
+  }).catch((error) => {
+    logger.warning(`\u622A\u56FE\u5185\u5BB9\u8FB9\u754C\u6D4B\u91CF\u5931\u8D25: ${error?.message || error}`);
+    return null;
+  });
+};
 var prepareExpandedFullPageScreenshot = async (page, options = {}) => {
   const originalViewport = await resolveCurrentViewportSize(page);
   const maxHeight = toPositiveInteger(options.maxHeight, DEFAULT_MAX_HEIGHT);
-  const preserveViewport = options.preserveViewport ?? resolvePageDevice(page) === Device.Mobile;
+  const device = await resolvePageDevice(page);
+  const preserveViewport = options.preserveViewport ?? device === Device.Mobile;
   const defaultSettleMs = preserveViewport ? DEFAULT_MOBILE_SETTLE_MS : DEFAULT_SETTLE_MS;
   const requestedSettleMs = Math.max(0, Number(options.settleMs ?? defaultSettleMs) || 0);
   const settleMs = preserveViewport ? Math.min(requestedSettleMs, DEFAULT_MOBILE_SETTLE_MS) : requestedSettleMs;
@@ -917,7 +1089,21 @@ var prepareExpandedFullPageScreenshot = async (page, options = {}) => {
     visibleOnly: options.visibleOnly !== false,
     expandDocumentElements: preserveViewport
   });
-  const targetHeight = Math.min(maxScrollHeight, maxHeight);
+  const contentBounds = await measureMeaningfulContentBounds(page);
+  let targetHeight = Math.min(maxScrollHeight, maxHeight);
+  if (contentBounds?.bottom > 0) {
+    const contentBottom = Math.min(Math.ceil(contentBounds.bottom), maxHeight);
+    const trailingGap = targetHeight - contentBottom;
+    const minTrailingGap = Math.max(
+      MIN_TRAILING_BLANK_GAP_PX,
+      Math.floor(targetHeight * MIN_TRAILING_BLANK_GAP_RATIO),
+      Math.floor(originalViewport.height * 0.45)
+    );
+    if (trailingGap >= minTrailingGap && contentBottom >= originalViewport.height * 0.65) {
+      targetHeight = Math.max(1, contentBottom);
+      logger.info(`\u957F\u622A\u56FE\u88C1\u6389\u4F4E\u4FE1\u606F\u5C3E\u90E8: contentBottom=${contentBottom}, originalHeight=${Math.min(maxScrollHeight, maxHeight)}`);
+    }
+  }
   let viewportResized = false;
   if (!preserveViewport) {
     await page.setViewportSize({
@@ -937,6 +1123,7 @@ var prepareExpandedFullPageScreenshot = async (page, options = {}) => {
     originalViewport,
     maxScrollHeight,
     targetHeight,
+    contentBounds,
     preserveViewport,
     viewportResized
   };
@@ -969,6 +1156,411 @@ var restoreExpandedFullPageScreenshot = async (page, state2 = {}) => {
     await page.setViewportSize(state2.originalViewport);
   }
 };
+var resolveVirtualizedScrollTarget = async (page, options = {}) => {
+  const stitchMode = resolveStitchMode(options);
+  if (stitchMode === "off") return null;
+  const device = await resolvePageDevice(page);
+  if (stitchMode !== "force" && device !== Device.Mobile) {
+    return null;
+  }
+  return await page.evaluate((config) => {
+    const viewportWidth = window.innerWidth || document.documentElement?.clientWidth || document.body?.clientWidth || 0;
+    const viewportHeight = window.innerHeight || document.documentElement?.clientHeight || document.body?.clientHeight || 0;
+    const root = document.documentElement;
+    const body = document.body;
+    const scrollingElement = document.scrollingElement;
+    const candidates = [];
+    const seen = /* @__PURE__ */ new Set();
+    const scrollableOverflow = /* @__PURE__ */ new Set(["auto", "scroll", "overlay"]);
+    const clippingOverflow = /* @__PURE__ */ new Set(["hidden", "clip"]);
+    const pushCandidate = (el2) => {
+      if (!el2 || seen.has(el2)) return;
+      seen.add(el2);
+      candidates.push(el2);
+    };
+    pushCandidate(scrollingElement);
+    pushCandidate(root);
+    pushCandidate(body);
+    document.querySelectorAll("*").forEach(pushCandidate);
+    const isDocumentElement = (el2) => el2 === root || el2 === body || el2 === scrollingElement;
+    const isVisible = (el2, style, rect) => {
+      if (!el2 || !style || !rect) return false;
+      if (style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse") return false;
+      if (Number(style.opacity) === 0) return false;
+      return rect.width > 0 && rect.height > 0;
+    };
+    const hasOverflowValue = (style, values) => {
+      const overflowY = String(style?.overflowY || "").toLowerCase();
+      const overflow = String(style?.overflow || "").toLowerCase();
+      return values.has(overflowY) || values.has(overflow);
+    };
+    const looksScrollable = (el2, style) => {
+      if (!el2 || el2.scrollHeight <= el2.clientHeight + 1) return false;
+      if (isDocumentElement(el2)) return true;
+      return hasOverflowValue(style, scrollableOverflow) || hasOverflowValue(style, clippingOverflow);
+    };
+    const textHeightFor = (el2) => {
+      const nodes = isDocumentElement(el2) ? document.querySelectorAll("body *") : el2.querySelectorAll("*");
+      let textHeight = 0;
+      let textNodes = 0;
+      const maxNodes = 3500;
+      for (const node of nodes) {
+        if (textNodes >= maxNodes) break;
+        const text = String(node.textContent || "").replace(/\s+/g, " ").trim();
+        if (text.length < 2) continue;
+        let childHasText = false;
+        for (const child of node.children || []) {
+          if (String(child.textContent || "").replace(/\s+/g, " ").trim().length >= 2) {
+            childHasText = true;
+            break;
+          }
+        }
+        if (childHasText) continue;
+        const style = window.getComputedStyle(node);
+        const rect = node.getBoundingClientRect();
+        if (!isVisible(node, style, rect)) continue;
+        textNodes += 1;
+        textHeight += Math.min(Math.ceil(rect.height || 0), 900);
+      }
+      return { textHeight, textNodes };
+    };
+    const resolveEdgeOcclusion = () => {
+      let top = 0;
+      let bottom = 0;
+      const maxHeight = Math.max(48, viewportHeight * 0.45);
+      document.querySelectorAll("*").forEach((el2) => {
+        const style = window.getComputedStyle(el2);
+        const position = String(style.position || "").toLowerCase();
+        if (position !== "fixed" && position !== "sticky") return;
+        const rect = el2.getBoundingClientRect();
+        if (!isVisible(el2, style, rect)) return;
+        if (rect.height <= 0 || rect.height > maxHeight) return;
+        if (rect.width < viewportWidth * 0.35) return;
+        if (rect.top <= Math.max(16, viewportHeight * 0.08)) {
+          top = Math.max(top, Math.ceil(rect.bottom));
+        }
+        if (rect.bottom >= viewportHeight - Math.max(16, viewportHeight * 0.08)) {
+          bottom = Math.max(bottom, Math.ceil(viewportHeight - rect.top));
+        }
+      });
+      return {
+        top: Math.max(0, Math.min(Math.ceil(top), Math.floor(viewportHeight * 0.45))),
+        bottom: Math.max(0, Math.min(Math.ceil(bottom), Math.floor(viewportHeight * 0.45)))
+      };
+    };
+    let best = null;
+    candidates.forEach((el2) => {
+      const style = window.getComputedStyle(el2);
+      const rect = isDocumentElement(el2) ? {
+        top: 0,
+        bottom: viewportHeight,
+        left: 0,
+        right: viewportWidth,
+        width: viewportWidth,
+        height: viewportHeight
+      } : el2.getBoundingClientRect();
+      if (!isDocumentElement(el2) && !isVisible(el2, style, rect)) return;
+      if (!looksScrollable(el2, style)) return;
+      const scrollHeight = Math.ceil(el2.scrollHeight || 0);
+      const clientHeight = Math.ceil(el2.clientHeight || viewportHeight || 0);
+      if (scrollHeight < Math.max(900, clientHeight * config.minScrollRatio)) return;
+      const { textHeight, textNodes } = textHeightFor(el2);
+      const sparseRatio = scrollHeight / Math.max(1, textHeight);
+      const sparse = config.force || textNodes > 0 && sparseRatio >= config.minSparseRatio && scrollHeight - textHeight > clientHeight;
+      if (!sparse) return;
+      const visibleWidth = Math.max(1, Math.ceil(rect.width || viewportWidth || 1));
+      const score2 = scrollHeight * Math.min(visibleWidth, viewportWidth || visibleWidth);
+      if (!best || score2 > best.score) {
+        best = {
+          el: el2,
+          score: score2,
+          kind: isDocumentElement(el2) ? "document" : "element",
+          scrollHeight,
+          clientHeight,
+          scrollTop: Math.max(0, Math.round(el2.scrollTop || 0)),
+          rect: {
+            top: Math.max(0, Math.round(rect.top || 0)),
+            bottom: Math.min(viewportHeight, Math.round(rect.bottom || viewportHeight)),
+            left: Math.max(0, Math.round(rect.left || 0)),
+            width: Math.max(1, Math.round(rect.width || viewportWidth || 1)),
+            height: Math.max(1, Math.round(rect.height || viewportHeight || 1))
+          },
+          textHeight,
+          textNodes,
+          sparseRatio
+        };
+      }
+    });
+    if (!best) return null;
+    document.querySelectorAll(`[${config.attrName}="1"]`).forEach((node) => {
+      node.removeAttribute(config.attrName);
+    });
+    if (best.kind === "element") {
+      best.el.setAttribute(config.attrName, "1");
+    }
+    const { el, score, ...target } = best;
+    return {
+      ...target,
+      viewport: {
+        width: Math.max(1, Math.ceil(viewportWidth || best.rect.width || 1)),
+        height: Math.max(1, Math.ceil(viewportHeight || best.rect.height || 1))
+      },
+      edgeOcclusion: resolveEdgeOcclusion()
+    };
+  }, {
+    attrName: STITCH_SCROLL_TARGET_ATTR,
+    force: stitchMode === "force",
+    minScrollRatio: MIN_VIRTUALIZED_SCROLL_RATIO,
+    minSparseRatio: MIN_SPARSE_SCROLL_RATIO
+  }).catch((error) => {
+    logger.warning(`\u865A\u62DF\u6EDA\u52A8\u622A\u56FE\u63A2\u6D4B\u5931\u8D25: ${error?.message || error}`);
+    return null;
+  });
+};
+var setStitchScrollTop = async (page, target, scrollTop) => {
+  await page.evaluate(({ attrName, kind, top }) => {
+    const el = kind === "document" ? document.scrollingElement || document.documentElement || document.body : document.querySelector(`[${attrName}="1"]`);
+    if (!el) return;
+    el.scrollTop = Math.max(0, Math.round(Number(top) || 0));
+    el.dispatchEvent(new Event("scroll", { bubbles: true }));
+    window.dispatchEvent(new Event("scroll"));
+  }, {
+    attrName: STITCH_SCROLL_TARGET_ATTR,
+    kind: target.kind,
+    top: scrollTop
+  });
+};
+var cleanupStitchTarget = async (page) => {
+  await page.evaluate((attrName) => {
+    document.querySelectorAll(`[${attrName}="1"]`).forEach((node) => {
+      node.removeAttribute(attrName);
+    });
+  }, STITCH_SCROLL_TARGET_ATTR).catch(() => {
+  });
+};
+var cropImage = (image, crop) => image.clone().crop({
+  x: Math.max(0, Math.round(crop.x || 0)),
+  y: Math.max(0, Math.round(crop.y || 0)),
+  w: Math.max(1, Math.round(crop.w || 1)),
+  h: Math.max(1, Math.round(crop.h || 1))
+});
+var captureStitchedScrollableScreenshot = async (page, target, options = {}) => {
+  const maxHeight = toPositiveInteger(options.maxHeight, DEFAULT_MAX_HEIGHT);
+  const settleMs = Math.max(0, Number(options.stitchSettleMs ?? DEFAULT_STITCH_SETTLE_MS) || 0);
+  const overlapPx = Math.max(0, Math.round(Number(options.stitchOverlapPx ?? DEFAULT_STITCH_OVERLAP_PX) || 0));
+  const viewport = target.viewport || await resolveCurrentViewportSize(page);
+  const rect = target.rect || {
+    top: 0,
+    bottom: viewport.height,
+    left: 0,
+    width: viewport.width,
+    height: viewport.height
+  };
+  const edge = target.edgeOcclusion || { top: 0, bottom: 0 };
+  const topCrop = Math.max(0, Math.min(rect.top, viewport.height - 1));
+  const topOverlay = Math.max(topCrop, Math.min(edge.top || 0, viewport.height - 1));
+  const bottomOverlay = Math.max(0, Math.min(edge.bottom || 0, viewport.height - topOverlay - 1));
+  const middleCropY = Math.max(topCrop, topOverlay);
+  const middleCropBottom = Math.max(
+    middleCropY + 1,
+    Math.min(rect.bottom || viewport.height, viewport.height - bottomOverlay)
+  );
+  const middleCropHeight = Math.max(1, middleCropBottom - middleCropY);
+  const scrollStep = Math.max(120, middleCropHeight - overlapPx);
+  const maxScrollTop = Math.max(0, Math.ceil(target.scrollHeight - target.clientHeight));
+  const positions = [];
+  for (let top = 0; top < maxScrollTop; top += scrollStep) {
+    positions.push(Math.round(top));
+  }
+  if (!positions.includes(maxScrollTop)) {
+    positions.push(maxScrollTop);
+  }
+  if (positions.length === 0) {
+    positions.push(0);
+  }
+  const segments = [];
+  let totalHeight = 0;
+  let outputWidth = Math.max(1, Math.round(viewport.width || rect.width || 1));
+  try {
+    for (let index = 0; index < positions.length && totalHeight < maxHeight; index += 1) {
+      const isFirst = index === 0;
+      const isLast = index === positions.length - 1;
+      await setStitchScrollTop(page, target, positions[index]);
+      if (settleMs > 0) {
+        await (0, import_delay.default)(settleMs);
+      }
+      const buffer = await capturePageScreenshot(page, {
+        type: options.type || "png",
+        quality: options.quality,
+        timeout: options.timeout
+      });
+      const image = await import_jimp.Jimp.read(buffer);
+      outputWidth = Math.min(outputWidth, image.bitmap.width);
+      const cropY = isFirst ? 0 : middleCropY;
+      const cropBottom = isLast ? image.bitmap.height : middleCropBottom;
+      let cropHeight = Math.max(1, Math.min(image.bitmap.height, cropBottom) - cropY);
+      const remaining = maxHeight - totalHeight;
+      if (cropHeight > remaining) {
+        cropHeight = remaining;
+      }
+      segments.push(cropImage(image, {
+        x: 0,
+        y: cropY,
+        w: outputWidth,
+        h: cropHeight
+      }));
+      totalHeight += cropHeight;
+    }
+    const canvas = new import_jimp.Jimp({
+      width: outputWidth,
+      height: Math.max(1, totalHeight),
+      color: 4294967295
+    });
+    let y = 0;
+    for (const segment of segments) {
+      canvas.composite(segment, 0, y);
+      y += segment.bitmap.height;
+    }
+    logger.info(
+      `\u865A\u62DF\u6EDA\u52A8\u5206\u6BB5\u622A\u56FE: segments=${segments.length}, height=${totalHeight}, scrollHeight=${target.scrollHeight}, textNodes=${target.textNodes}, sparseRatio=${Number(target.sparseRatio || 0).toFixed(2)}`
+    );
+    return await canvas.getBuffer(import_jimp.JimpMime.png);
+  } finally {
+    await setStitchScrollTop(page, target, target.scrollTop || 0).catch(() => {
+    });
+    await cleanupStitchTarget(page);
+  }
+};
+var isLightBlankPixel = ({ r, g, b }) => {
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  return max >= 238 && max - min <= 18;
+};
+var isDarkBlankPixel = ({ r, g, b }) => {
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  return max <= 34 && max - min <= 10;
+};
+var isLowInfoPixel = ({ r, g, b }) => {
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  return max - min <= 12;
+};
+var analyzeScreenshotBuffer = async (buffer) => {
+  const image = await import_jimp.Jimp.read(buffer);
+  const width = image.bitmap.width;
+  const height = image.bitmap.height;
+  const stepY = Math.max(1, Math.floor(height / 900));
+  const stepX = Math.max(1, Math.floor(width / 420));
+  const rows = [];
+  let lightRows = 0;
+  let darkRows = 0;
+  let lowInfoRows = 0;
+  let loadingLikeRows = 0;
+  const rowFlags = [];
+  for (let y = 0; y < height; y += stepY) {
+    let light = 0;
+    let dark = 0;
+    let lowInfo = 0;
+    let edge = 0;
+    let count = 0;
+    let prev = null;
+    for (let x = 0; x < width; x += stepX) {
+      const rgba = (0, import_jimp.intToRGBA)(image.getPixelColor(x, y));
+      count += 1;
+      if (isLightBlankPixel(rgba)) light += 1;
+      if (isDarkBlankPixel(rgba)) dark += 1;
+      if (isLowInfoPixel(rgba)) lowInfo += 1;
+      if (prev) {
+        const diff = Math.abs(rgba.r - prev.r) + Math.abs(rgba.g - prev.g) + Math.abs(rgba.b - prev.b);
+        if (diff > 45) edge += 1;
+      }
+      prev = rgba;
+    }
+    const stat = {
+      y,
+      lightRatio: light / Math.max(1, count),
+      darkRatio: dark / Math.max(1, count),
+      lowInfoRatio: lowInfo / Math.max(1, count),
+      edgeRatio: edge / Math.max(1, count - 1)
+    };
+    rows.push(stat);
+    const lightBlank = stat.lightRatio >= 0.965 && stat.edgeRatio <= 0.015;
+    const darkBlank = stat.darkRatio >= 0.965 && stat.edgeRatio <= 0.012;
+    const lowInfoBlank = stat.lowInfoRatio >= 0.965 && stat.edgeRatio <= 0.012;
+    const loadingLike = stat.darkRatio >= 0.88 && stat.edgeRatio <= 0.025;
+    if (lightBlank) lightRows += 1;
+    if (darkBlank) darkRows += 1;
+    if (lowInfoBlank) lowInfoRows += 1;
+    if (loadingLike) loadingLikeRows += 1;
+    rowFlags.push({ lightBlank, darkBlank, lowInfoBlank, loadingLike });
+  }
+  const sampledRows = Math.max(1, rows.length);
+  return {
+    image,
+    width,
+    height,
+    lightBlankRowsRatio: lightRows / sampledRows,
+    darkBlankRowsRatio: darkRows / sampledRows,
+    lowInfoRowsRatio: lowInfoRows / sampledRows,
+    loadingLikeRowsRatio: loadingLikeRows / sampledRows,
+    rowFlags
+  };
+};
+var resolveScreenshotQualityIssue = (analysis) => {
+  if (!analysis) return null;
+  if (analysis.loadingLikeRowsRatio >= 0.92 || analysis.darkBlankRowsRatio >= 0.72) {
+    return "loading-like-dark-screenshot";
+  }
+  return null;
+};
+var cropBufferToContentBounds = async (buffer, bounds, options = {}) => {
+  if (!bounds || bounds.nodes <= 0) return buffer;
+  const image = options.image || await import_jimp.Jimp.read(buffer);
+  const width = image.bitmap.width;
+  const height = image.bitmap.height;
+  const safeLeft = Math.max(0, Math.min(width - 1, Math.floor(bounds.left || 0)));
+  const safeRight = Math.max(safeLeft + 1, Math.min(width, Math.ceil(bounds.right || width)));
+  const safeTop = Math.max(0, Math.min(height - 1, Math.floor(bounds.top || 0)));
+  const safeBottom = Math.max(safeTop + 1, Math.min(height, Math.ceil(bounds.bottom || height)));
+  const cropW = safeRight - safeLeft;
+  const cropH = safeBottom - safeTop;
+  const shouldCropX = cropW > 80 && cropW <= width * 0.82 && (safeLeft > width * 0.04 || width - safeRight > width * 0.04);
+  const shouldCropY = cropH > 160 && cropH <= height * 0.88 && height - safeBottom > Math.max(320, height * 0.1);
+  if (!shouldCropX && !shouldCropY) {
+    return buffer;
+  }
+  const x = shouldCropX ? safeLeft : 0;
+  const y = shouldCropY ? safeTop : 0;
+  const w = shouldCropX ? cropW : width;
+  const h = shouldCropY ? cropH : height;
+  logger.info(`\u5185\u5BB9\u611F\u77E5\u88C1\u526A\u622A\u56FE: x=${x}, y=${y}, w=${w}, h=${h}, original=${width}x${height}`);
+  return await cropImage(image, { x, y, w, h }).getBuffer(import_jimp.JimpMime.png);
+};
+var captureExpandedFullPageScreenshotOnce = async (page, options = {}) => {
+  const stitchedTarget = await resolveVirtualizedScrollTarget(page, options);
+  if (stitchedTarget) {
+    return await captureStitchedScrollableScreenshot(page, stitchedTarget, options);
+  }
+  const state2 = await prepareExpandedFullPageScreenshot(page, options);
+  try {
+    const buffer = await capturePageScreenshot(page, {
+      fullPage: true,
+      type: options.type || "png",
+      quality: options.quality,
+      timeout: options.timeout,
+      maxClipHeight: state2.targetHeight
+    });
+    return await cropBufferToContentBounds(buffer, state2.contentBounds);
+  } finally {
+    await restoreAffixedElementsForExpandedScreenshot(page).catch((error) => {
+      logger.warning(`\u79FB\u52A8\u7AEF\u5438\u9644\u5143\u7D20\u6062\u590D\u5931\u8D25: ${error?.message || error}`);
+    });
+    if (options.restore) {
+      await restoreExpandedFullPageScreenshot(page, state2);
+    }
+  }
+};
 var capturePageScreenshot = async (page, options = {}) => {
   const fullPage = Boolean(options.fullPage);
   const type = fullPage ? FORCED_FULLPAGE_TYPE : normalizeType(options.type);
@@ -1023,23 +1615,35 @@ var capturePageScreenshot = async (page, options = {}) => {
   }
 };
 var captureExpandedFullPageScreenshot = async (page, options = {}) => {
-  const state2 = await prepareExpandedFullPageScreenshot(page, options);
-  try {
-    return await capturePageScreenshot(page, {
-      fullPage: true,
-      type: options.type || "png",
-      quality: options.quality,
-      timeout: options.timeout,
-      maxClipHeight: state2.targetHeight
-    });
-  } finally {
-    await restoreAffixedElementsForExpandedScreenshot(page).catch((error) => {
-      logger.warning(`\u79FB\u52A8\u7AEF\u5438\u9644\u5143\u7D20\u6062\u590D\u5931\u8D25: ${error?.message || error}`);
+  const attempts = Math.max(1, toPositiveInteger(options.qualityRetryAttempts, DEFAULT_QUALITY_RETRY_ATTEMPTS));
+  const retryDelayMs = Math.max(0, Number(options.qualityRetryDelayMs ?? DEFAULT_QUALITY_RETRY_DELAY_MS) || 0);
+  let lastBuffer = null;
+  let lastAnalysis = null;
+  let lastIssue = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const buffer = await captureExpandedFullPageScreenshotOnce(page, options);
+    const analysis = await analyzeScreenshotBuffer(buffer).catch((error) => {
+      logger.warning(`\u622A\u56FE\u8D28\u91CF\u5206\u6790\u5931\u8D25: ${error?.message || error}`);
+      return null;
     });
-    if (options.restore) {
-      await restoreExpandedFullPageScreenshot(page, state2);
+    const issue = resolveScreenshotQualityIssue(analysis);
+    lastBuffer = buffer;
+    lastAnalysis = analysis;
+    lastIssue = issue;
+    if (!issue) {
+      return buffer;
+    }
+    if (attempt < attempts && retryDelayMs > 0) {
+      logger.warning(`\u622A\u56FE\u7591\u4F3C\u5F02\u5E38(${issue})\uFF0C\u7B49\u5F85\u540E\u91CD\u8BD5: attempt=${attempt}/${attempts}`);
+      await (0, import_delay.default)(retryDelayMs);
     }
   }
+  if (lastIssue && lastAnalysis) {
+    logger.warning(
+      `\u622A\u56FE\u8D28\u91CF\u4ECD\u5F02\u5E38(${lastIssue})\uFF0C\u8FD4\u56DE\u6700\u4F73\u53EF\u5F97\u7ED3\u679C: light=${lastAnalysis.lightBlankRowsRatio.toFixed(2)}, dark=${lastAnalysis.darkBlankRowsRatio.toFixed(2)}, loading=${lastAnalysis.loadingLikeRowsRatio.toFixed(2)}`
+    );
+  }
+  return lastBuffer;
 };
 
 // src/errors.js
@@ -9716,7 +10320,7 @@ var watermarkifyScreenshotBuffer = async (buffer, meta, page = null, options = {
 };
 
 // src/internals/compression.js
-var import_jimp = require("jimp");
+var import_jimp2 = require("jimp");
 var logger15 = createInternalLogger("Compression");
 var DEFAULT_SCREENSHOT_MAX_BYTES = 5 * 1024 * 1024;
 var DEFAULT_SCREENSHOT_OUTPUT_TYPE = "jpeg";
@@ -9783,10 +10387,10 @@ var encodeJpeg = async (sourceImage, compression, scale, quality) => {
     image.resize({
       w: width,
       h: height,
-      mode: import_jimp.ResizeStrategy.BILINEAR
+      mode: import_jimp2.ResizeStrategy.BILINEAR
     });
   }
-  const buffer = await image.getBuffer(import_jimp.JimpMime.jpeg, { quality });
+  const buffer = await image.getBuffer(import_jimp2.JimpMime.jpeg, { quality });
   return {
     buffer,
     bytes: getBase64BytesFromBuffer(buffer),
@@ -9798,7 +10402,7 @@ var encodeJpeg = async (sourceImage, compression, scale, quality) => {
   };
 };
 var compressImageBuffer = async (buffer, compression) => {
-  const sourceImage = await import_jimp.Jimp.read(buffer);
+  const sourceImage = await import_jimp2.Jimp.read(buffer);
   const maxQuality = toJpegQuality(compression.quality);
   const minQuality = Math.min(maxQuality, toJpegQuality(compression.minQuality));
   let quality = maxQuality;