@afixt/screenshot-utils 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,8 +1,42 @@
 # Changelog
 
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+All notable changes to this project will be documented in this file.
 
-## [1.0.0](https://github.com/AFixt/screenshot-utils/compare/v0.9.0...v1.0.0) (2026-05-29)
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-05-29
+
+First v1.0.0 release. Every acceptance criterion in `spec.md` § 23 is now
+met — OpenSeadragon end-to-end integration, the ≥90% capture/transform
+coverage gates, the performance suite, and the live browser-adapter tests
+all run green. The public API surface in `src/index.js` is now
+semver-protected.
+
+### Changed
+
+- Coverage provider switched from `v8` to `istanbul`. The v8 provider did not union-merge per-file coverage across test files in this repo — a near-empty barrel import (`index.test.js`) clobbered a module's real coverage from its dedicated test (e.g. `page.js` read 80% alone, 32% in the full run) — which had forced thresholds down to a placeholder 60/50. istanbul merges correctly; browser-shipped code is excluded so its injected counters don't run in the page context (`src/adapters/**`, the `settle.runInPage` / `element.findElementInPage` page-context functions, and the `src/errors/**` barrel re-exports which are covered by `test/errors/*.test.js`).
+- Coverage thresholds raised from 60/50 to an 85/85/90/85 project floor, with per-glob gates requiring ≥90% line + branch on `src/capture/**` and `src/transform/**` (spec § 23). Capture now 92.3% line / 91.1% branch; transform 95.0% / 97.4%; overall 89.8%.
+- Minimum Node widened to `>=20.0.0` (was `>=22.22.1`) to match the spec § 23 / CI Node 20 + 22 matrix; with `engine-strict=true` the old floor would have failed the Node 20 jobs.
+
+### Added
+
+- `playwright` added as a dev dependency so its live-browser adapter contract suite actually runs in CI (was skipped whenever Playwright was absent). CI workflows now install the Chromium binary for the integration tests.
+- OpenSeadragon end-to-end integration test for `tileDzi` (spec § 23): generates a real DZI pyramid, serves it plus the OpenSeadragon UMD build over a local HTTP server, and asserts the viewer opens the `.dzi` and loads tiles with no failures in a headless browser — verifying the output is genuinely consumable by the de-facto DZI viewer, not just shaped like one. `openseadragon` added as a dev dependency.
+- Unit-test backfill across `resize`, `crop`, `normalize`, and `captureLongPage` to reach the § 23 capture + transform coverage bar.
+
+### Fixed
+
+- `npm run test:perf` was excluded down to zero test files by the shared Vitest `exclude` glob, so it exited non-zero and the weekly `performance.yml` workflow was effectively always failing. It now runs via a dedicated config; all six § 13.3 ceilings pass.
+- The 500-iteration memory-growth test silently `return`ed (passing vacuously) when `--expose-gc` was absent. The perf config now exposes gc and the test asserts its availability, so it genuinely runs.
+- Browser-teardown `afterAll` hooks no longer rely on the 10 s default timeout (which flaked under parallel Chromium contention, failing the suite as a file-level "Hook timed out"); they now allow 30 s.
+
+### Removed
+
+- Deprecated `always-auth=true` from `.npmrc` (npm warns it is going away; the per-registry `_authToken` covers publish auth).
+- Unused `@vitest/coverage-v8` dev dependency (provider is now istanbul).
 
 ## [0.9.0] - 2026-05-22
 

package/dist/index.js

@@ -99,7 +99,7 @@ var require_package = __commonJS({
         access: "restricted"
       },
       engines: {
-        node: ">=20.0.0"
+        node: ">=20.9.0"
       },
       keywords: [
         "screenshot",
@@ -117,7 +117,7 @@ var require_package = __commonJS({
         "revenant"
       ],
       dependencies: {
-        sharp: "0.34.5"
+        sharp: "^0.35.3"
       },
       peerDependencies: {
         "@napi-rs/canvas": "^0.1.0",
@@ -963,7 +963,10 @@ var require_settle = __commonJS({
       const {
         fonts = true,
         images = true,
+        backgroundImages = true,
         animations = "reduce",
+        network = "idle",
+        layoutStableMs = 250,
         maxWait = 5e3,
         idleMs = 200
       } = options;
@@ -971,7 +974,10 @@ var require_settle = __commonJS({
       const report = await adapter.evaluate(runInPage, {
         fonts,
         images,
+        backgroundImages,
         animations,
+        network,
+        layoutStableMs,
         maxWait,
         idleMs
       });
@@ -983,6 +989,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([
@@ -1037,6 +1046,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;
@@ -1084,9 +1190,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;
     }
@@ -1117,20 +1226,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);
@@ -1170,6 +1271,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;
     }
@@ -1427,6 +1550,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,
@@ -1438,6 +1562,7 @@ var require_element = __commonJS({
         timeout = 5e3,
         format = "png",
         quality = 90,
+        waitForStable: settleOpts = false,
         events = null
       } = options;
       if (!selector && !xpath) {
@@ -1476,6 +1601,7 @@ var require_element = __commonJS({
         }
       }
       let viewportRect = lookup.viewportRect;
+      let documentRect = lookup.documentRect;
       if (scrollIntoView) {
         await adapter.scrollTo({
           x: 0,
@@ -1490,6 +1616,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)),
@@ -1511,12 +1643,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)
         }
@@ -1524,6 +1656,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;
@@ -2773,7 +2925,10 @@ var require_index = __commonJS({
       waitForStable: Object.freeze({
         fonts: true,
         images: true,
+        backgroundImages: true,
         animations: "reduce",
+        network: "idle",
+        layoutStableMs: 250,
         maxWait: 5e3,
         idleMs: 200
       })