@afixt/screenshot-utils 0.9.0

package/src/capture/page.js

@@ -0,0 +1,207 @@
+'use strict';
+
+const { CaptureTimeoutError, UnsupportedFormatError } = require('../errors/index.js');
+const { waitForStable } = require('./settle.js');
+
+/**
+ * Capture a full page (or just the viewport) via a `PageAdapter`.
+ *
+ * Implements `spec.md` § 8.1.1. Lazy-loads `sharp` only when the requested
+ * output format is one the browser can't produce directly (today: webp;
+ * Chromium emits png/jpeg natively).
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').CaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').CaptureResult>}
+ */
+async function capturePage(adapter, options = {}) {
+    const {
+        format = 'png',
+        quality = 90,
+        fullPage = true,
+        omitBackground = false,
+        encoding = 'buffer',
+        timeout = 30_000,
+        waitForStable: settleOpts = false,
+        events = null,
+    } = options;
+
+    validateFormat(format);
+
+    const start = nowMs();
+    emit(events, 'capture:start', { format, fullPage });
+
+    let settleMs = 0;
+    const 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`);
+        }
+    }
+
+    const metrics = await adapter.getMetrics();
+
+    // Decide whether to delegate the format to the browser or to re-encode.
+    const browserFormat = decideBrowserFormat(format);
+    const browserOpts = buildBrowserOpts({
+        format: browserFormat,
+        quality,
+        fullPage,
+        omitBackground,
+    });
+
+    const captureStart = nowMs();
+    const rawBuffer = await withTimeout(adapter.screenshot(browserOpts), timeout, {
+        operation: 'adapter.screenshot',
+    });
+    const captureMs = nowMs() - captureStart;
+
+    let bytes = rawBuffer;
+    let encodeMs = 0;
+    if (browserFormat !== format) {
+        const encodeStart = nowMs();
+        bytes = await reencode(rawBuffer, { format, quality });
+        encodeMs = nowMs() - encodeStart;
+    }
+
+    if (encoding === 'stream') {
+        bytes = bufferToStream(bytes);
+    }
+
+    const totalMs = nowMs() - start;
+
+    const result = {
+        format,
+        bytes,
+        page: metrics,
+        timing: { settleMs, captureMs, encodeMs, totalMs },
+        warnings,
+    };
+
+    emit(events, 'capture:complete', {
+        format,
+        bytes: typeof bytes === 'object' && Buffer.isBuffer(bytes) ? bytes.length : null,
+        totalMs,
+    });
+
+    return result;
+}
+
+/**
+ * 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
+ * re-encoding to a format the browser can't produce directly).
+ *
+ * @param {import('../types/index.d.ts').Format} format
+ * @returns {import('../types/index.d.ts').Format}
+ */
+function decideBrowserFormat(format) {
+    // Chromium produces png + jpeg natively; webp must be re-encoded by sharp.
+    return format === 'webp' ? 'png' : format;
+}
+
+/**
+ * Translate package options into the shape the adapter's `screenshot()`
+ * method expects (spec § 10 `ScreenshotOptions`).
+ *
+ * @param {{format: string, quality: number, fullPage: boolean, omitBackground: boolean}} opts
+ * @returns {import('../types/index.d.ts').ScreenshotOptions}
+ */
+function buildBrowserOpts({ format, quality, fullPage, omitBackground }) {
+    const out = { fullPage, omitBackground, type: format };
+    if (format === 'jpeg') {
+        out.quality = quality;
+    }
+    return out;
+}
+
+/**
+ * Re-encode a PNG buffer into the requested format using sharp.
+ * Lazy-loaded so consumers who never re-encode pay no startup cost.
+ *
+ * @param {Buffer} input
+ * @param {{format: import('../types/index.d.ts').Format, quality: number}} opts
+ * @returns {Promise<Buffer>}
+ */
+async function reencode(input, { format, quality }) {
+    const sharp = require('sharp');
+    let pipeline = sharp(input);
+    switch (format) {
+        case 'webp':
+            pipeline = pipeline.webp({ quality });
+            break;
+        case 'jpeg':
+            pipeline = pipeline.jpeg({ quality });
+            break;
+        case 'png':
+            pipeline = pipeline.png();
+            break;
+    }
+    return pipeline.toBuffer();
+}
+
+/**
+ * Wrap a promise with a timeout that throws CaptureTimeoutError.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {{operation: string}} ctx
+ * @returns {Promise<T>}
+ */
+function withTimeout(promise, ms, ctx) {
+    if (!Number.isFinite(ms) || ms <= 0) {
+        return promise;
+    }
+    let timer;
+    const timeoutPromise = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(
+                new CaptureTimeoutError(`${ctx.operation} exceeded ${ms}ms timeout`, {
+                    context: { operation: ctx.operation, timeoutMs: ms },
+                })
+            );
+        }, ms);
+        // Don't keep the event loop alive if the test process is exiting.
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+}
+
+function validateFormat(format) {
+    if (!['png', 'jpeg', 'webp'].includes(format)) {
+        throw new UnsupportedFormatError(
+            `format must be 'png', 'jpeg', or 'webp'; received ${JSON.stringify(format)}`,
+            { context: { received: format } }
+        );
+    }
+}
+
+function emit(events, name, payload) {
+    if (events && typeof events.emit === 'function') {
+        events.emit(name, payload);
+    }
+}
+
+function nowMs() {
+    return Number(process.hrtime.bigint() / 1_000_000n);
+}
+
+function bufferToStream(buf) {
+    const { Readable } = require('node:stream');
+    return Readable.from(buf);
+}
+
+module.exports = { capturePage };

package/src/capture/responsive.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const { capturePage } = require('./page.js');
+const { captureLongPage } = require('./long-page.js');
+const { captureViewport } = require('./viewport.js');
+
+/**
+ * Capture the same page at multiple viewport sizes in one orchestrated
+ * call. Useful for responsive accessibility audits.
+ *
+ * Implements `spec.md` § 8.1.5.
+ *
+ * - `parallelism: 1` (default) is the safe choice — driving viewport
+ *   changes against a single page in parallel produces non-deterministic
+ *   results. Consumers can bump it above 1 only if they hand over
+ *   distinct adapters via the (Phase 4) per-context capture API.
+ * - `reloadBetween: true` (default) reloads the page between viewport
+ *   changes so media queries and layout re-evaluate cleanly.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').ResponsiveCaptureOptions} options
+ * @returns {Promise<import('../types/index.d.ts').ResponsiveCaptureResult>}
+ */
+async function captureResponsive(adapter, options) {
+    if (!options || !Array.isArray(options.viewports) || options.viewports.length === 0) {
+        const { InvalidRectError } = require('../errors/index.js');
+        throw new InvalidRectError(
+            'captureResponsive requires options.viewports as a non-empty array',
+            { context: { received: options?.viewports } }
+        );
+    }
+    // parallelism is accepted in the options shape (per spec § 8.1.5) but
+    // ignored here: running viewport changes in parallel against one
+    // adapter is unsafe (shared viewport state). The Phase 4 per-context
+    // API will honor it. Pull it off the options object before destructure
+    // so it doesn't end up in captureOptions.
+    const { viewports, reloadBetween = true, captureMode = 'fullPage', ...rest } = options;
+    delete rest.parallelism;
+    const captureOptions = rest;
+
+    const start = nowMs();
+    const captures = [];
+
+    // Parallelism > 1 against a single adapter is unsafe (viewport state
+    // is shared). For now run strictly serial; Phase 4 will introduce a
+    // per-adapter mode that takes a factory.
+    for (const viewport of viewports) {
+        if (!viewport || typeof viewport.name !== 'string') {
+            const { InvalidRectError } = require('../errors/index.js');
+            throw new InvalidRectError('Each viewport must have a string name', {
+                context: { viewport },
+            });
+        }
+        await adapter.setViewport(viewport);
+        if (reloadBetween) {
+            await adapter.reload({ waitUntil: 'networkidle0' }).catch(() => adapter.reload());
+        }
+        const capture = await captureForMode(adapter, captureMode, captureOptions);
+        captures.push({ ...capture, viewportName: viewport.name });
+    }
+
+    return {
+        captures,
+        capturedAt: new Date().toISOString(),
+        totalMs: nowMs() - start,
+    };
+}
+
+/**
+ * Dispatch to the right capture function based on captureMode.
+ *
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {'fullPage' | 'viewport' | 'longPage'} mode
+ * @param {import('../types/index.d.ts').CaptureOptions} captureOptions
+ * @returns {Promise<import('../types/index.d.ts').CaptureResult>}
+ */
+async function captureForMode(adapter, mode, captureOptions) {
+    switch (mode) {
+        case 'viewport':
+            return captureViewport(adapter, captureOptions);
+        case 'longPage':
+            return captureLongPage(adapter, captureOptions);
+        default:
+            // 'fullPage' or anything unknown: full-page capture.
+            return capturePage(adapter, { ...captureOptions, fullPage: true });
+    }
+}
+
+function nowMs() {
+    return Number(process.hrtime.bigint() / 1_000_000n);
+}
+
+module.exports = { captureResponsive };

package/src/capture/settle.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * Wait for the page to reach a render-stable state before capture.
+ *
+ * Implements `spec.md` § 8.1.6. The whole settle logic runs inside the
+ * page context via a single `adapter.evaluate()` call to avoid Node ↔
+ * browser round-trips for each sub-check.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').WaitForStableOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').StabilityReport>}
+ */
+async function waitForStable(adapter, options = {}) {
+    const {
+        fonts = true,
+        images = true,
+        animations = 'reduce',
+        maxWait = 5000,
+        idleMs = 200,
+    } = options;
+
+    const start = nowMs();
+    const report = await adapter.evaluate(runInPage, {
+        fonts,
+        images,
+        animations,
+        maxWait,
+        idleMs,
+    });
+    const totalMs = nowMs() - start;
+    return { ...report, totalMs };
+}
+
+/**
+ * Page-context settle implementation. Serialized + executed by the
+ * adapter via the browser's evaluate primitive. Must be self-contained
+ * (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
+ * @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. */
+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 },
+        animations: 'skipped',
+    };
+
+    // All sub-checks are nested functions so the closure is one
+    // serializable unit when adapter.evaluate ships this to the browser.
+
+    const withTimeout = (promise, ms, label) =>
+        Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                setTimeout(() => reject(new Error(`${label} timeout`)), ms);
+            }),
+        ]);
+
+    const settleFonts = async () => {
+        if (!opts.fonts || !doc || !doc.fonts || !doc.fonts.ready) {
+            return;
+        }
+        try {
+            await withTimeout(doc.fonts.ready, opts.maxWait, 'fonts.ready');
+            report.fonts = 'ready';
+        } catch {
+            report.fonts = 'timeout';
+        }
+    };
+
+    const settleOneImage = img =>
+        new Promise(resolve => {
+            if (img.complete) {
+                if (img.naturalHeight > 0) {
+                    report.images.loaded += 1;
+                } else {
+                    report.images.failed += 1;
+                }
+                resolve();
+                return;
+            }
+            img.addEventListener(
+                'load',
+                () => {
+                    report.images.loaded += 1;
+                    resolve();
+                },
+                { once: true }
+            );
+            img.addEventListener(
+                'error',
+                () => {
+                    report.images.failed += 1;
+                    resolve();
+                },
+                { once: true }
+            );
+        });
+
+    const settleImages = async () => {
+        if (!opts.images || !doc) {
+            return;
+        }
+        const imgs = Array.from(doc.images || doc.querySelectorAll('img') || []);
+        report.images.total = imgs.length;
+        await Promise.all(imgs.map(settleOneImage));
+    };
+
+    const settleAnimations = async () => {
+        if (opts.animations === 'ignore' || !doc) {
+            return;
+        }
+        const reduced =
+            globalThis.matchMedia &&
+            globalThis.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        if (reduced) {
+            report.animations = 'reduced';
+            return;
+        }
+        const running = doc.getAnimations
+            ? doc.getAnimations().filter(a => a.playState === 'running')
+            : [];
+        if (opts.animations === 'reduce') {
+            report.animations = running.length > 0 ? 'timeout' : 'none';
+            return;
+        }
+        if (opts.animations === 'wait') {
+            if (running.length === 0) {
+                report.animations = 'none';
+                return;
+            }
+            try {
+                await withTimeout(
+                    Promise.all(running.map(a => a.finished.catch(() => {}))),
+                    opts.maxWait,
+                    'animations'
+                );
+                report.animations = 'settled';
+            } catch {
+                report.animations = 'timeout';
+            }
+        }
+    };
+
+    const settleIdle = async () => {
+        if (opts.idleMs <= 0) {
+            return;
+        }
+        if (typeof globalThis.requestIdleCallback === 'function') {
+            await new Promise(resolve => {
+                globalThis.requestIdleCallback(() => resolve(), {
+                    timeout: opts.idleMs * 2,
+                });
+            });
+        }
+        await new Promise(resolve => {
+            setTimeout(resolve, opts.idleMs);
+        });
+    };
+
+    await settleFonts();
+    await settleImages();
+    await settleAnimations();
+    await settleIdle();
+
+    return report;
+}
+/* v8 ignore stop */
+
+function nowMs() {
+    return Number(process.hrtime.bigint() / 1_000_000n);
+}
+
+module.exports = { waitForStable };

package/src/capture/viewport.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { capturePage } = require('./page.js');
+
+/**
+ * Capture only what is currently scrolled into view (no full-page scroll
+ * or stitching). Useful for AI evidence and above-the-fold checks.
+ *
+ * Implements `spec.md` § 8.1.2. Thin wrapper around `capturePage` that
+ * forces `fullPage: false` regardless of caller options.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').CaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').CaptureResult>}
+ */
+async function captureViewport(adapter, options = {}) {
+    return capturePage(adapter, { ...options, fullPage: false });
+}
+
+module.exports = { captureViewport };