@afixt/screenshot-utils 0.9.0 → 1.1.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@afixt/screenshot-utils",
-      version: "0.9.0",
+      version: "1.0.0",
       description: "Screenshot capture, transform, compose, tile, and redact utilities for the AFixt/Revenant accessibility platform",
       type: "commonjs",
       main: "./dist/index.js",
@@ -97,7 +97,7 @@ var require_package = __commonJS({
         access: "restricted"
       },
       engines: {
-        node: ">=22.22.1"
+        node: ">=20.9.0"
       },
       keywords: [
         "screenshot",
@@ -115,7 +115,7 @@ var require_package = __commonJS({
         "revenant"
       ],
       dependencies: {
-        sharp: "0.34.5"
+        sharp: "^0.35.3"
       },
       peerDependencies: {
         "@napi-rs/canvas": "^0.1.0",
@@ -146,7 +146,7 @@ var require_package = __commonJS({
         "@commitlint/config-conventional": "20.5.3",
         "@eslint/js": "10.0.1",
         "@types/node": "22.19.19",
-        "@vitest/coverage-v8": "4.1.5",
+        "@vitest/coverage-istanbul": "4.1.5",
         "clean-jsdoc-theme": "4.3.2",
         eslint: "10.3.0",
         "eslint-plugin-import-x": "4.16.2",
@@ -165,6 +165,7 @@ var require_package = __commonJS({
         "lint-staged": "17.0.2",
         "markdownlint-cli": "0.48.0",
         "npm-run-all2": "8.0.4",
+        openseadragon: "6.0.2",
         pixelmatch: "7.1.0",
         playwright: "1.60.0",
         pngjs: "7.0.0",
@@ -960,7 +961,10 @@ var require_settle = __commonJS({
       const {
         fonts = true,
         images = true,
+        backgroundImages = true,
         animations = "reduce",
+        network = "idle",
+        layoutStableMs = 250,
         maxWait = 5e3,
         idleMs = 200
       } = options;
@@ -968,7 +972,10 @@ var require_settle = __commonJS({
       const report = await adapter.evaluate(runInPage, {
         fonts,
         images,
+        backgroundImages,
         animations,
+        network,
+        layoutStableMs,
         maxWait,
         idleMs
       });
@@ -980,6 +987,9 @@ var require_settle = __commonJS({
       const report = {
         fonts: "skipped",
         images: { total: 0, loaded: 0, failed: 0 },
+        backgroundImages: "skipped",
+        network: "skipped",
+        layoutStable: "skipped",
         animations: "skipped"
       };
       const withTimeout = (promise, ms, label) => Promise.race([
@@ -1034,6 +1044,103 @@ var require_settle = __commonJS({
         report.images.total = imgs.length;
         await Promise.all(imgs.map(settleOneImage));
       };
+      const collectBackgroundUrls = () => {
+        const CAP = 200;
+        const urls = /* @__PURE__ */ new Set();
+        const els = doc.querySelectorAll("*");
+        for (let i = 0; i < els.length && urls.size < CAP; i += 1) {
+          const bg = globalThis.getComputedStyle(els[i]).backgroundImage;
+          if (!bg || bg === "none") {
+            continue;
+          }
+          for (const match of bg.matchAll(/url\((['"]?)([^'")]+)\1\)/g)) {
+            const url = match[2];
+            if (url && !url.startsWith("data:")) {
+              urls.add(url);
+            }
+          }
+        }
+        return Array.from(urls).slice(0, CAP);
+      };
+      const settleOneBackgroundUrl = (url) => new Promise((resolve) => {
+        const img = new globalThis.Image();
+        const onload = () => {
+          report.backgroundImages.loaded += 1;
+          resolve();
+        };
+        const onerror = () => {
+          report.backgroundImages.failed += 1;
+          resolve();
+        };
+        img.addEventListener("load", onload, { once: true });
+        img.addEventListener("error", onerror, { once: true });
+        img.src = url;
+      });
+      const settleBackgroundImages = async () => {
+        if (!opts.backgroundImages || !doc) {
+          return;
+        }
+        const list = collectBackgroundUrls();
+        report.backgroundImages = { total: list.length, loaded: 0, failed: 0 };
+        if (list.length === 0) {
+          return;
+        }
+        await withTimeout(
+          Promise.all(list.map(settleOneBackgroundUrl)),
+          opts.maxWait,
+          "backgroundImages"
+        ).catch(() => {
+        });
+      };
+      const settleNetwork = async () => {
+        if (opts.network !== "idle" || !doc) {
+          return;
+        }
+        const perf = globalThis.performance;
+        const countResources = () => perf && perf.getEntriesByType ? perf.getEntriesByType("resource").length : 0;
+        const quietMs = 200;
+        const deadline = Date.now() + opts.maxWait;
+        let lastCount = countResources();
+        let lastChange = Date.now();
+        while (Date.now() < deadline) {
+          const count = countResources();
+          if (count !== lastCount) {
+            lastCount = count;
+            lastChange = Date.now();
+          }
+          if (doc.readyState === "complete" && Date.now() - lastChange >= quietMs) {
+            report.network = "idle";
+            return;
+          }
+          await new Promise((resolve) => {
+            setTimeout(resolve, 50);
+          });
+        }
+        report.network = "timeout";
+      };
+      const settleLayout = async () => {
+        if (!opts.layoutStableMs || opts.layoutStableMs <= 0 || !doc) {
+          return;
+        }
+        const el = doc.documentElement;
+        const deadline = Date.now() + opts.maxWait;
+        let lastHeight = el.scrollHeight;
+        let stableSince = Date.now();
+        while (Date.now() < deadline) {
+          await new Promise((resolve) => {
+            setTimeout(resolve, 50);
+          });
+          const height = el.scrollHeight;
+          if (height !== lastHeight) {
+            lastHeight = height;
+            stableSince = Date.now();
+          } else if (Date.now() - stableSince >= opts.layoutStableMs) {
+            report.layoutStable = "stable";
+            return;
+          }
+        }
+        report.layoutStable = "timeout";
+      };
       const settleAnimations = async () => {
         if (opts.animations === "ignore" || !doc) {
           return;
@@ -1081,9 +1188,12 @@ var require_settle = __commonJS({
           setTimeout(resolve, opts.idleMs);
         });
       };
+      await settleNetwork();
       await settleFonts();
       await settleImages();
+      await settleBackgroundImages();
       await settleAnimations();
+      await settleLayout();
       await settleIdle();
       return report;
     }
@@ -1114,20 +1224,12 @@ var require_page = __commonJS({
       const start = nowMs();
       emit(events, "capture:start", { format, fullPage });
       let settleMs = 0;
-      const warnings = [];
+      let warnings = [];
       if (settleOpts) {
         const settleStart = nowMs();
         const report = await waitForStable(adapter, settleOpts === true ? {} : settleOpts);
         settleMs = nowMs() - settleStart;
-        if (report.fonts === "timeout") {
-          warnings.push("fonts did not settle within maxWait");
-        }
-        if (report.animations === "timeout") {
-          warnings.push("animations did not settle within maxWait");
-        }
-        if (report.images.failed > 0) {
-          warnings.push(`${report.images.failed} image(s) failed to load`);
-        }
+        warnings = settleWarnings(report);
       }
       const metrics = await adapter.getMetrics();
       const browserFormat = decideBrowserFormat(format);
@@ -1167,6 +1269,28 @@ var require_page = __commonJS({
       });
       return result;
     }
+    function settleWarnings(report) {
+      const warnings = [];
+      if (report.fonts === "timeout") {
+        warnings.push("fonts did not settle within maxWait");
+      }
+      if (report.animations === "timeout") {
+        warnings.push("animations did not settle within maxWait");
+      }
+      if (report.images.failed > 0) {
+        warnings.push(`${report.images.failed} image(s) failed to load`);
+      }
+      if (report.backgroundImages && report.backgroundImages.failed > 0) {
+        warnings.push(`${report.backgroundImages.failed} background image(s) failed to load`);
+      }
+      if (report.network === "timeout") {
+        warnings.push("network did not reach idle within maxWait");
+      }
+      if (report.layoutStable === "timeout") {
+        warnings.push("layout did not stabilize within maxWait");
+      }
+      return warnings;
+    }
     function decideBrowserFormat(format) {
       return format === "webp" ? "png" : format;
     }
@@ -1424,6 +1548,7 @@ var require_long_page = __commonJS({
 var require_element = __commonJS({
   "src/capture/element.js"(exports, module) {
     var { CaptureTimeoutError } = require_errors();
+    var { waitForStable } = require_settle();
     async function captureElement(adapter, options = {}) {
       const {
         selector,
@@ -1435,6 +1560,7 @@ var require_element = __commonJS({
         timeout = 5e3,
         format = "png",
         quality = 90,
+        waitForStable: settleOpts = false,
         events = null
       } = options;
       if (!selector && !xpath) {
@@ -1473,6 +1599,7 @@ var require_element = __commonJS({
         }
       }
       let viewportRect = lookup.viewportRect;
+      let documentRect = lookup.documentRect;
       if (scrollIntoView) {
         await adapter.scrollTo({
           x: 0,
@@ -1487,6 +1614,12 @@ var require_element = __commonJS({
           viewportRect = reread.viewportRect;
         }
       }
+      const settled = await settleAndReread(adapter, { selector, xpath, timeout, settleOpts });
+      const settleMs = settled.settleMs;
+      if (settled.rect) {
+        viewportRect = settled.rect.viewportRect;
+        documentRect = settled.rect.documentRect;
+      }
       const clip = {
         x: Math.max(0, Math.round(viewportRect.x - padding)),
         y: Math.max(0, Math.round(viewportRect.y - padding)),
@@ -1508,12 +1641,12 @@ var require_element = __commonJS({
         format,
         bytes,
         page: metrics,
-        timing: { settleMs: 0, captureMs, encodeMs: 0, totalMs },
+        timing: { settleMs, captureMs, encodeMs: 0, totalMs },
         warnings: [],
         element: {
           selector: selector ?? "",
           xpath: xpath ?? "",
-          documentRect: lookup.documentRect,
+          documentRect,
           viewportRect,
           verified: Boolean(snippet)
         }
@@ -1521,6 +1654,26 @@ var require_element = __commonJS({
       emit(events, "capture:complete", { format, totalMs, mode: "element" });
       return result;
     }
+    async function settleAndReread(adapter, { selector, xpath, timeout, settleOpts }) {
+      if (!settleOpts) {
+        return { settleMs: 0, rect: null };
+      }
+      const settleStart = nowMs();
+      await waitForStable(adapter, settleOpts === true ? {} : settleOpts);
+      const settleMs = nowMs() - settleStart;
+      const reread = await withTimeout(
+        adapter.evaluate(findElementInPage, { selector, xpath }),
+        timeout,
+        { operation: "adapter.evaluate(findElement after settle)" }
+      );
+      if (reread && reread.found) {
+        return {
+          settleMs,
+          rect: { viewportRect: reread.viewportRect, documentRect: reread.documentRect }
+        };
+      }
+      return { settleMs, rect: null };
+    }
     function findElementInPage(args) {
       const doc = globalThis.document;
       let element;
@@ -2770,7 +2923,10 @@ var require_index = __commonJS({
       waitForStable: Object.freeze({
         fonts: true,
         images: true,
+        backgroundImages: true,
         animations: "reduce",
+        network: "idle",
+        layoutStableMs: 250,
         maxWait: 5e3,
         idleMs: 200
       })