@afixt/screenshot-utils 0.9.0 → 1.1.0

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,17 +45,21 @@ 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'>>}
  */
-/* v8 ignore start -- runs in the browser via adapter.evaluate(); not
-   instrumentable by Node-side coverage. Exercised by settle-integration.test.js. */
+/* istanbul ignore next -- runs in the browser via adapter.evaluate(); must NOT
+   be instrumented (injected counters don't exist in the page context) and is
+   exercised by settle-integration.test.js. */
 async function runInPage(opts) {
     const doc = globalThis.document;
     /** @type {Omit<import('../types/index.d.ts').StabilityReport, 'totalMs'>} */
     const report = {
         fonts: 'skipped',
         images: { total: 0, loaded: 0, failed: 0 },
+        backgroundImages: 'skipped',
+        network: 'skipped',
+        layoutStable: 'skipped',
         animations: 'skipped',
     };
 
@@ -114,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;
@@ -166,14 +299,16 @@ async function runInPage(opts) {
         });
     };
 
+    await settleNetwork();
     await settleFonts();
     await settleImages();
+    await settleBackgroundImages();
     await settleAnimations();
+    await settleLayout();
     await settleIdle();
 
     return report;
 }
-/* v8 ignore stop */
 
 function nowMs() {
     return Number(process.hrtime.bigint() / 1_000_000n);

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;
 }