@afixt/screenshot-utils 0.9.0 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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
 
 First published release. Phases 0–4 of `PLAN.md` are complete: the full

package/README.md

@@ -2,7 +2,7 @@
 
 > Screenshot capture, transform, compose, tile, and redact utilities for the AFixt/Revenant accessibility platform.
 
-Status: **0.9.0** — Phases 0–4 of [`PLAN.md`](./PLAN.md) are complete; the full public API from [`spec.md`](./spec.md) § 8 is implemented and tested. Pre-1.0 while the v1.0.0 acceptance bar in `spec.md` § 23 is finished (OpenSeadragon e2e, 80% coverage, perf suite in CI). The API is expected to stay stable through to 1.0.0.
+Status: **0.9.0** — Phases 0–4 of [`PLAN.md`](./PLAN.md) are complete; the full public API from [`spec.md`](./spec.md) § 8 is implemented and tested (capture and transform at ≥90% line+branch coverage per § 23). Pre-1.0 while the remaining v1.0.0 acceptance items in `spec.md` § 23 land (a live CDP adapter test and the CI matrix running green). The API is expected to stay stable through to 1.0.0.
 
 This package owns **all** screenshot operations for the AFixt/Revenant platform: full-page, viewport, element, long-page strip-stitch, multi-viewport capture; crop / resize / convert / normalize transforms; annotate / heatmap / diff / composite; DZI tile pyramids; and PII redaction. It is being extracted from `@afixt/afixt-engine`; the engine will become a consumer.
 
@@ -40,27 +40,27 @@ Screenshot work was scattered across `afixt-engine`, `mortise`, and ad-hoc consu
 
 ## Install
 
-| Dependency          | Status                                         | Why you'd want it                      |
-| ------------------- | ---------------------------------------------- | -------------------------------------- |
-| `sharp`             | Required runtime dep — installed automatically | All raster operations                  |
-| `puppeteer` >=23    | Optional peer                                  | `fromPuppeteerPage` adapter            |
-| `playwright` >=1.40 | Optional peer                                  | `fromPlaywrightPage` adapter (Phase 2) |
-| `pixelmatch`        | Optional peer                                  | `diff()` function (Phase 4)            |
-| `pngjs`             | Optional peer                                  | `pixelmatch` co-dependency             |
-| `@napi-rs/canvas`   | Deferred to v1.1                               | Advanced annotation strokes            |
+| Dependency          | Status                                         | Why you'd want it            |
+| ------------------- | ---------------------------------------------- | ---------------------------- |
+| `sharp`             | Required runtime dep — installed automatically | All raster operations        |
+| `puppeteer` >=23    | Optional peer                                  | `fromPuppeteerPage` adapter  |
+| `playwright` >=1.40 | Optional peer                                  | `fromPlaywrightPage` adapter |
+| `pixelmatch`        | Optional peer                                  | `diff()` function            |
+| `pngjs`             | Optional peer                                  | `pixelmatch` co-dependency   |
+| `@napi-rs/canvas`   | Deferred to v1.1                               | Advanced annotation strokes  |
 
-Node `>=22.22.1` is required (`engine-strict=true`).
+Node `>=20.0.0` is required (`engine-strict=true`).
 
 ## PageAdapter
 
 The capture functions never import a browser. Consumers wrap their `Page`-like object:
 
 ```js
-const { fromPuppeteerPage } = require('@afixt/screenshot-utils/adapters/puppeteer');
+const { fromPuppeteerPage } = require('@afixt/screenshot-utils');
 const adapter = fromPuppeteerPage(page);
 ```
 
-Anything that satisfies the `PageAdapter` interface works — write your own for CDP-only runtimes. See `docs/adapters.md` (Phase 4) for the contract.
+Anything that satisfies the `PageAdapter` interface works — write your own for CDP-only runtimes. See `docs/adapters.md` for the contract.
 
 ## Capture functions
 
@@ -77,20 +77,20 @@ Anything that satisfies the `PageAdapter` interface works — write your own for
 - `convert(buffer, format, opts)` — re-encode
 - `resize(buffer, opts)` — fit, contain, cover
 - `normalize(buffer, opts)` — strip metadata, fix orientation
-- `annotate(buffer, annotations, opts)` — boxes, labels, severities (Phase 4)
-- `heatmap(buffer, points, opts)` — kernel-density overlay (Phase 4)
-- `diff(a, b, opts)` — pixelmatch-backed visual diff (Phase 4)
+- `annotate(buffer, annotations, opts)` — boxes, labels, severities
+- `heatmap(buffer, points, opts)` — kernel-density overlay
+- `diff(a, b, opts)` — pixelmatch-backed visual diff
 
 ## Tiling
 
-- `tileDzi(buffer, outDir | 'buffers', opts)` — produce a Deep Zoom Image pyramid (Phase 2)
+- `tileDzi(buffer, outDir | 'buffers', opts)` — produce a Deep Zoom Image pyramid
 
 ## Redaction
 
-- `redact(buffer, regions, mode, opts)` — blur, mask, or pixelate PII regions (Phase 4)
+- `redact(buffer, regions, mode, opts)` — blur, mask, or pixelate PII regions
 - `applyPiiPolicy(buffer, policy)` — apply a policy bundle for repeatable redaction
 
-## CLI (Phase 4)
+## CLI
 
 ```bash
 npx @afixt/screenshot-utils crop input.png --rect 0,0,400,300 --out thumb.png
@@ -103,11 +103,11 @@ npx @afixt/screenshot-utils diff before.png after.png --out diff.png
 - Pass `encoding: 'stream'` for memory-sensitive pipelines.
 - Use `cropMany` rather than calling `crop` in a loop — internally bounded parallelism is faster and uses less memory.
 - For long pages, prefer `captureLongPage` over a giant viewport — sharp handles strips better than 30 000-px-tall buffers.
-- See `docs/performance.md` (Phase 4) for ceilings.
+- See `docs/performance.md` for ceilings.
 
 ## Errors
 
-Every failure is a named class with a stable `code`, a structured `reason` enum, and a `retriable: boolean` hint. Hierarchy in `spec.md` § 14.1. Catalog in `docs/error-codes.md` (Phase 4).
+Every failure is a named class with a stable `code`, a structured `reason` enum, and a `retriable: boolean` hint. Hierarchy in `spec.md` § 14.1. Catalog in `docs/error-codes.md`.
 
 ## Versioning & non-goals
 

package/dist/index.js

@@ -16,7 +16,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",
@@ -99,7 +99,7 @@ var require_package = __commonJS({
         access: "restricted"
       },
       engines: {
-        node: ">=22.22.1"
+        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",
@@ -148,7 +148,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",
@@ -167,6 +167,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",
@@ -962,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;
@@ -970,7 +974,10 @@ var require_settle = __commonJS({
       const report = await adapter.evaluate(runInPage, {
         fonts,
         images,
+        backgroundImages,
         animations,
+        network,
+        layoutStableMs,
         maxWait,
         idleMs
       });
@@ -982,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([
@@ -1036,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;
@@ -1083,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;
     }
@@ -1116,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);
@@ -1169,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;
     }
@@ -1426,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,
@@ -1437,6 +1562,7 @@ var require_element = __commonJS({
         timeout = 5e3,
         format = "png",
         quality = 90,
+        waitForStable: settleOpts = false,
         events = null
       } = options;
       if (!selector && !xpath) {
@@ -1475,6 +1601,7 @@ var require_element = __commonJS({
         }
       }
       let viewportRect = lookup.viewportRect;
+      let documentRect = lookup.documentRect;
       if (scrollIntoView) {
         await adapter.scrollTo({
           x: 0,
@@ -1489,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)),
@@ -1510,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)
         }
@@ -1523,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;
@@ -2772,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
       })