@afixt/screenshot-utils 1.0.0 → 1.1.0

package/dist/types/capture/element.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../../src/capture/element.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,wCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,qBAAqB,GACjD,OAAO,CAAC,OAAO,qBAAqB,EAAE,oBAAoB,CAAC,CA+GvE"}
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../../src/capture/element.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,wCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,qBAAqB,GACjD,OAAO,CAAC,OAAO,qBAAqB,EAAE,oBAAoB,CAAC,CA4HvE"}

package/dist/types/capture/page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../../src/capture/page.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,qCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,cAAc,GAC1C,OAAO,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAkFhE"}
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../../src/capture/page.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,qCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,cAAc,GAC1C,OAAO,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,CA0EhE"}

package/dist/types/capture/settle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../../src/capture/settle.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,uCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,oBAAoB,GAChD,OAAO,CAAC,OAAO,qBAAqB,EAAE,eAAe,CAAC,CAqBlE"}
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../../src/capture/settle.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,uCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,oBAAoB,GAChD,OAAO,CAAC,OAAO,qBAAqB,EAAE,eAAe,CAAC,CA2BlE"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/screenshot-utils",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Screenshot capture, transform, compose, tile, and redact utilities for the AFixt/Revenant accessibility platform",
     "type": "commonjs",
     "main": "./dist/index.js",
@@ -83,7 +83,7 @@
         "access": "restricted"
     },
     "engines": {
-        "node": ">=20.0.0"
+        "node": ">=20.9.0"
     },
     "keywords": [
         "screenshot",
@@ -101,7 +101,7 @@
         "revenant"
     ],
     "dependencies": {
-        "sharp": "0.34.5"
+        "sharp": "^0.35.3"
     },
     "peerDependencies": {
         "@napi-rs/canvas": "^0.1.0",

package/src/capture/element.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { CaptureTimeoutError } = require('../errors/index.js');
+const { waitForStable } = require('./settle.js');
 
 /**
  * Capture a single element by selector or xpath.
@@ -31,6 +32,7 @@ async function captureElement(adapter, options = {}) {
         timeout = 5000,
         format = 'png',
         quality = 90,
+        waitForStable: settleOpts = false,
         events = null,
     } = options;
 
@@ -77,6 +79,7 @@ async function captureElement(adapter, options = {}) {
     }
 
     let viewportRect = lookup.viewportRect;
+    let documentRect = lookup.documentRect;
     if (scrollIntoView) {
         await adapter.scrollTo({
             x: 0,
@@ -93,6 +96,17 @@ async function captureElement(adapter, options = {}) {
         }
     }
 
+    // Optional render-stability wait. Critically, we re-read the element rect
+    // *after* settling: late reflow (lazy images, web fonts, JS layout) is the
+    // cause of blank/wrong-region element crops, so coordinates captured before
+    // settle cannot be trusted for the clip.
+    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)),
@@ -117,12 +131,12 @@ async function captureElement(adapter, options = {}) {
         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),
         },
@@ -131,6 +145,35 @@ async function captureElement(adapter, options = {}) {
     return result;
 }
 
+/**
+ * Run waitForStable (when requested) and re-read the element rect afterwards.
+ * Kept out of `captureElement` so the main flow stays flat.
+ *
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {{selector?: string, xpath?: string, timeout: number, settleOpts: import('../types/index.d.ts').WaitForStableOptions|boolean}} ctx
+ * @returns {Promise<{settleMs: number, rect: {viewportRect: import('../types/index.d.ts').Rect, documentRect: import('../types/index.d.ts').Rect}|null}>}
+ */
+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 };
+}
+
 /**
  * Page-context element lookup. Shipped to the browser via adapter.evaluate.
  * Coverage suppressed for the same reason as `settle.js#runInPage` —

package/src/capture/page.js

@@ -33,20 +33,12 @@ async function capturePage(adapter, options = {}) {
     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();
@@ -97,6 +89,35 @@ async function capturePage(adapter, options = {}) {
     return result;
 }
 
+/**
+ * Translate a StabilityReport into non-fatal warning strings.
+ *
+ * @param {import('../types/index.d.ts').StabilityReport} report
+ * @returns {string[]}
+ */
+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;
+}
+
 /**
  * Map the user's desired output format to the format the browser should
  * produce. Returns either the same format (no re-encode) or 'png' (when

package/src/capture/settle.js

@@ -16,7 +16,10 @@ async function waitForStable(adapter, options = {}) {
     const {
         fonts = true,
         images = true,
+        backgroundImages = true,
         animations = 'reduce',
+        network = 'idle',
+        layoutStableMs = 250,
         maxWait = 5000,
         idleMs = 200,
     } = options;
@@ -25,7 +28,10 @@ async function waitForStable(adapter, options = {}) {
     const report = await adapter.evaluate(runInPage, {
         fonts,
         images,
+        backgroundImages,
         animations,
+        network,
+        layoutStableMs,
         maxWait,
         idleMs,
     });
@@ -39,7 +45,7 @@ async function waitForStable(adapter, options = {}) {
  * (no closures over Node-side state) and only use `globalThis.*` so
  * eslint's no-undef passes.
  *
- * @param {{fonts: boolean, images: boolean, animations: 'reduce'|'wait'|'ignore', maxWait: number, idleMs: number}} opts
+ * @param {{fonts: boolean, images: boolean, backgroundImages: boolean, animations: 'reduce'|'wait'|'ignore', network: 'idle'|'ignore', layoutStableMs: number, maxWait: number, idleMs: number}} opts
  * @returns {Promise<Omit<import('../types/index.d.ts').StabilityReport, 'totalMs'>>}
  */
 /* istanbul ignore next -- runs in the browser via adapter.evaluate(); must NOT
@@ -51,6 +57,9 @@ async function runInPage(opts) {
     const report = {
         fonts: 'skipped',
         images: { total: 0, loaded: 0, failed: 0 },
+        backgroundImages: 'skipped',
+        network: 'skipped',
+        layoutStable: 'skipped',
         animations: 'skipped',
     };
 
@@ -115,6 +124,129 @@ async function runInPage(opts) {
         await Promise.all(imgs.map(settleOneImage));
     };
 
+    // Collect unique, non-data CSS background-image URLs, bounded for perf.
+    const collectBackgroundUrls = () => {
+        const CAP = 200; // large DOMs otherwise scan tens of thousands of nodes
+        const urls = 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);
+    };
+
+    // Load one URL and tally it. Listeners are attached before `src` is set, so
+    // even a cached resource fires 'load' on a freshly-created Image — no
+    // synchronous complete-branch is needed (which would risk a double count).
+    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;
+        });
+
+    // Heroes and section backgrounds are commonly CSS background-images, not
+    // <img>. A capture taken before they paint reads as blank even though
+    // fonts.ready has resolved — this check waits for those URLs to load.
+    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(() => {
+            // timeout: leave loaded/failed at whatever completed so far
+        });
+    };
+
+    // Approximate a networkidle gate without owning navigation: wait until the
+    // document is 'complete' and no new resource-timing entries appear for a
+    // short quiet window. Bounded by maxWait.
+    //
+    // Known limitation: getEntriesByType('resource') is capped by the resource
+    // timing buffer (default 250 entries). On a page with >250 resources the
+    // count plateaus and this can report 'idle' early. It errs toward idle
+    // (settle is less thorough, never a hang), and the image/background/layout
+    // checks still run, so the practical impact is small.
+    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';
+    };
+
+    // Late reflow is what leaves element crops on stale coordinates. Require the
+    // document height to hold steady for layoutStableMs before declaring stable.
+    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;
@@ -167,9 +299,12 @@ async function runInPage(opts) {
         });
     };
 
+    await settleNetwork();
     await settleFonts();
     await settleImages();
+    await settleBackgroundImages();
     await settleAnimations();
+    await settleLayout();
     await settleIdle();
 
     return report;

package/src/index.js

@@ -41,7 +41,10 @@ const defaults = Object.freeze({
     waitForStable: Object.freeze({
         fonts: true,
         images: true,
+        backgroundImages: true,
         animations: 'reduce',
+        network: 'idle',
+        layoutStableMs: 250,
         maxWait: 5000,
         idleMs: 200,
     }),

package/src/types/index.d.ts

@@ -53,11 +53,18 @@ export type Severity = 'critical' | 'serious' | 'moderate' | 'minor';
 
 export type Encoding = 'buffer' | 'stream';
 export type AnimationsPolicy = 'reduce' | 'wait' | 'ignore';
+export type NetworkPolicy = 'idle' | 'ignore';
 
 export interface WaitForStableOptions {
     fonts?: boolean;
     images?: boolean;
+    /** Wait for CSS background-image URLs to load; default true. */
+    backgroundImages?: boolean;
     animations?: AnimationsPolicy;
+    /** Resource-timing quiescence gate; default 'idle'. */
+    network?: NetworkPolicy;
+    /** Require scrollHeight/target-rect steady for this long; 0 disables. Default 250. */
+    layoutStableMs?: number;
     /** ms; default 5000. */
     maxWait?: number;
     /** ms; default 200. */
@@ -150,6 +157,9 @@ export interface ResponsiveCaptureResult {
 export interface StabilityReport {
     fonts: 'ready' | 'timeout' | 'skipped';
     images: { total: number; loaded: number; failed: number };
+    backgroundImages: { total: number; loaded: number; failed: number } | 'skipped';
+    network: 'idle' | 'timeout' | 'skipped';
+    layoutStable: 'stable' | 'timeout' | 'skipped';
     animations: 'none' | 'reduced' | 'settled' | 'timeout' | 'skipped';
     totalMs: number;
 }