@afixt/screenshot-utils 0.9.0

package/src/capture/element.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const { CaptureTimeoutError } = require('../errors/index.js');
+
+/**
+ * Capture a single element by selector or xpath.
+ *
+ * Implements `spec.md` § 8.1.3. **Deprecated as the engine's primary path**
+ * — prefer `capturePage` + `cropMany`. Retained because (a) the engine
+ * needs a like-for-like replacement during the Phase 3 migration and
+ * (b) direct callers (Investigator, ad-hoc tooling) still want it.
+ *
+ * Failure modes return an ElementCaptureResult with `bytes === null` and
+ * `reason` populated rather than throwing. This matches the engine's
+ * current `{ screenshot, reason }` contract so consumers can swap
+ * implementations without changing control flow.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').ElementCaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').ElementCaptureResult>}
+ */
+async function captureElement(adapter, options = {}) {
+    const {
+        selector,
+        xpath,
+        snippet,
+        padding = 10,
+        maxDimensions = { width: 4000, height: 4000 },
+        scrollIntoView = true,
+        timeout = 5000,
+        format = 'png',
+        quality = 90,
+        events = null,
+    } = options;
+
+    if (!selector && !xpath) {
+        return failure(
+            { selector, xpath, format },
+            'element_not_found',
+            null,
+            'No selector or xpath provided'
+        );
+    }
+
+    const start = nowMs();
+    emit(events, 'capture:start', { format, mode: 'element', selector, xpath });
+
+    const lookup = await withTimeout(
+        adapter.evaluate(findElementInPage, { selector, xpath }),
+        timeout,
+        { operation: 'adapter.evaluate(findElement)' }
+    );
+
+    if (!lookup || !lookup.found) {
+        return failure({ selector, xpath, format }, 'element_not_found', null, null);
+    }
+    if (lookup.documentRect.width === 0 || lookup.documentRect.height === 0) {
+        return failure({ selector, xpath, format }, 'element_not_visible', lookup, null);
+    }
+    if (
+        lookup.documentRect.width > maxDimensions.width ||
+        lookup.documentRect.height > maxDimensions.height
+    ) {
+        return failure({ selector, xpath, format }, 'element_too_large', lookup, null);
+    }
+    if (snippet) {
+        const normalize = s => String(s).replaceAll(/\s+/g, ' ').trim();
+        if (normalize(lookup.outerHTML) !== normalize(snippet)) {
+            return failure(
+                { selector, xpath, format },
+                'element_mismatch',
+                lookup,
+                'Provided snippet did not match element outerHTML'
+            );
+        }
+    }
+
+    let viewportRect = lookup.viewportRect;
+    if (scrollIntoView) {
+        await adapter.scrollTo({
+            x: 0,
+            y: Math.max(0, lookup.documentRect.y - padding),
+        });
+        // Re-evaluate to pick up the new viewport rect after scroll.
+        const reread = await withTimeout(
+            adapter.evaluate(findElementInPage, { selector, xpath }),
+            timeout,
+            { operation: 'adapter.evaluate(findElement after scroll)' }
+        );
+        if (reread && reread.found) {
+            viewportRect = reread.viewportRect;
+        }
+    }
+
+    const clip = {
+        x: Math.max(0, Math.round(viewportRect.x - padding)),
+        y: Math.max(0, Math.round(viewportRect.y - padding)),
+        width: Math.round(viewportRect.width + 2 * padding),
+        height: Math.round(viewportRect.height + 2 * padding),
+    };
+
+    const screenshotOpts = { fullPage: false, type: format, clip };
+    if (format === 'jpeg') {
+        screenshotOpts.quality = quality;
+    }
+    const captureStart = nowMs();
+    const bytes = await withTimeout(adapter.screenshot(screenshotOpts), timeout, {
+        operation: 'adapter.screenshot(element)',
+    });
+    const captureMs = nowMs() - captureStart;
+
+    const metrics = await adapter.getMetrics();
+    const totalMs = nowMs() - start;
+
+    const result = {
+        format,
+        bytes,
+        page: metrics,
+        timing: { settleMs: 0, captureMs, encodeMs: 0, totalMs },
+        warnings: [],
+        element: {
+            selector: selector ?? '',
+            xpath: xpath ?? '',
+            documentRect: lookup.documentRect,
+            viewportRect,
+            verified: Boolean(snippet),
+        },
+    };
+    emit(events, 'capture:complete', { format, totalMs, mode: 'element' });
+    return result;
+}
+
+/**
+ * Page-context element lookup. Shipped to the browser via adapter.evaluate.
+ * Coverage suppressed for the same reason as `settle.js#runInPage` —
+ * runs in the browser, not in Node.
+ *
+ * @param {{selector?: string, xpath?: string}} args
+ * @returns {{found: false} | {found: true, outerHTML: string, documentRect: import('../types/index.d.ts').Rect, viewportRect: import('../types/index.d.ts').Rect}}
+ */
+/* v8 ignore start -- runs in the browser via adapter.evaluate(); not
+   instrumentable by Node-side coverage. Exercised by the puppeteer/playwright
+   element-capture integration tests. */
+function findElementInPage(args) {
+    const doc = globalThis.document;
+    let element;
+    if (args.selector) {
+        try {
+            element = doc.querySelector(args.selector);
+        } catch {
+            element = null;
+        }
+    }
+    if (!element && args.xpath) {
+        try {
+            const FIRST = 9; // XPathResult.FIRST_ORDERED_NODE_TYPE
+            const res = doc.evaluate(args.xpath, doc, null, FIRST, null);
+            element = res.singleNodeValue;
+        } catch {
+            element = null;
+        }
+    }
+    if (!element) {
+        return { found: false };
+    }
+    const rect = element.getBoundingClientRect();
+    const sx = globalThis.scrollX || 0;
+    const sy = globalThis.scrollY || 0;
+    return {
+        found: true,
+        outerHTML: element.outerHTML,
+        documentRect: {
+            x: rect.x + sx,
+            y: rect.y + sy,
+            width: rect.width,
+            height: rect.height,
+        },
+        viewportRect: {
+            x: rect.x,
+            y: rect.y,
+            width: rect.width,
+            height: rect.height,
+        },
+    };
+}
+/* v8 ignore stop */
+
+/**
+ * Build a failure-shaped ElementCaptureResult that preserves the engine's
+ * `{ bytes: null, reason }` contract.
+ *
+ * @param {{selector?: string, xpath?: string, format: string}} input
+ * @param {string} reason
+ * @param {{outerHTML?: string, documentRect?: import('../types/index.d.ts').Rect, viewportRect?: import('../types/index.d.ts').Rect} | null} lookup
+ * @param {string | null} verificationReason
+ * @returns {import('../types/index.d.ts').ElementCaptureResult}
+ */
+function failure(input, reason, lookup, verificationReason) {
+    return {
+        format: input.format,
+        bytes: null,
+        page: null,
+        timing: { settleMs: 0, captureMs: 0, encodeMs: 0, totalMs: 0 },
+        warnings: [],
+        element: {
+            selector: input.selector ?? '',
+            xpath: input.xpath ?? '',
+            documentRect: lookup?.documentRect ?? { x: 0, y: 0, width: 0, height: 0 },
+            viewportRect: lookup?.viewportRect ?? { x: 0, y: 0, width: 0, height: 0 },
+            verified: false,
+            ...(verificationReason ? { verificationReason } : {}),
+        },
+        reason,
+    };
+}
+
+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);
+}
+
+/**
+ * Race a promise against a CaptureTimeoutError-throwing timer.
+ *
+ * @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);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+}
+
+module.exports = { captureElement };

package/src/capture/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { capturePage } = require('./page.js');
+const { waitForStable } = require('./settle.js');
+const { captureLongPage } = require('./long-page.js');
+const { captureElement } = require('./element.js');
+const { captureViewport } = require('./viewport.js');
+const { captureResponsive } = require('./responsive.js');
+
+module.exports = {
+    capturePage,
+    waitForStable,
+    captureLongPage,
+    captureElement,
+    captureViewport,
+    captureResponsive,
+};

package/src/capture/long-page.js

@@ -0,0 +1,267 @@
+'use strict';
+
+const { PageTooTallError, CaptureTimeoutError } = require('../errors/index.js');
+
+/**
+ * Capture a page taller than the browser's single-screenshot height limit
+ * by scrolling, capturing strips, and stitching them via `sharp`.
+ *
+ * Implements `spec.md` § 8.1.4. If the document height fits within the
+ * adapter's `screenshotMaxHeight` capability, delegates to the regular
+ * `adapter.screenshot({ fullPage: true })`. Otherwise iterates over
+ * viewport-height strips, scrolling between captures.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').LongPageCaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').CaptureResult>}
+ */
+async function captureLongPage(adapter, options = {}) {
+    const {
+        stripHeight = null,
+        overlap = 0,
+        maxHeight = 32_768,
+        format = 'png',
+        quality = 90,
+        omitBackground = false,
+        scrollSettleMs = 100,
+        timeout = 30_000,
+        events = null,
+    } = options;
+
+    const start = nowMs();
+    emit(events, 'capture:start', { format, fullPage: true, mode: 'long-page' });
+
+    const metrics = await adapter.getMetrics();
+    if (metrics.height > maxHeight) {
+        throw new PageTooTallError(
+            `Page height ${metrics.height}px exceeds maxHeight ${maxHeight}px`,
+            { context: { documentHeight: metrics.height, maxHeight } }
+        );
+    }
+
+    const capabilities = adapter.capabilities ?? { screenshotMaxHeight: 16_384 };
+    const browserMax = capabilities.screenshotMaxHeight;
+    const captureStart = nowMs();
+
+    const { bytes: stitched, encodeMs } =
+        metrics.height <= browserMax
+            ? await singleShotCapture(adapter, {
+                  format,
+                  quality,
+                  omitBackground,
+                  timeout,
+              })
+            : await stripCapture(adapter, {
+                  metrics,
+                  stripHeight,
+                  overlap,
+                  scrollSettleMs,
+                  timeout,
+                  format,
+                  quality,
+                  omitBackground,
+                  events,
+              });
+
+    const captureMs = nowMs() - captureStart - encodeMs;
+    const totalMs = nowMs() - start;
+
+    const result = {
+        format,
+        bytes: stitched,
+        page: metrics,
+        timing: { settleMs: 0, captureMs, encodeMs, totalMs },
+        warnings: [],
+    };
+    emit(events, 'capture:complete', { format, totalMs });
+    return result;
+}
+
+/**
+ * Single-shot path: the browser can produce the full document in one call.
+ *
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {{format: import('../types/index.d.ts').Format, quality: number, omitBackground: boolean, timeout: number}} opts
+ * @returns {Promise<{bytes: Buffer, encodeMs: number}>}
+ */
+async function singleShotCapture(adapter, opts) {
+    const { format, quality, omitBackground, timeout } = opts;
+    const bytes = await withTimeout(
+        adapter.screenshot({
+            fullPage: true,
+            type: format === 'webp' ? 'png' : format,
+            omitBackground,
+            ...(format === 'jpeg' ? { quality } : {}),
+        }),
+        timeout,
+        { operation: 'adapter.screenshot(fullPage)' }
+    );
+    return { bytes, encodeMs: 0 };
+}
+
+/**
+ * Strip-and-stitch path: scroll the page and capture viewport strips,
+ * then composite them via sharp.
+ *
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {{metrics: import('../types/index.d.ts').PageMetrics, stripHeight: number|null, overlap: number, scrollSettleMs: number, timeout: number, format: import('../types/index.d.ts').Format, quality: number, omitBackground: boolean, events: object|null}} opts
+ * @returns {Promise<{bytes: Buffer, encodeMs: number}>}
+ */
+async function stripCapture(adapter, opts) {
+    const {
+        metrics,
+        stripHeight,
+        overlap,
+        scrollSettleMs,
+        timeout,
+        format,
+        quality,
+        omitBackground,
+        events,
+    } = opts;
+
+    const sh = Math.max(1, stripHeight ?? metrics.viewport.height);
+    const stride = Math.max(1, sh - overlap);
+    const uniqueYs = planStripYs(metrics.height, sh, stride);
+
+    const strips = [];
+    for (let i = 0; i < uniqueYs.length; i += 1) {
+        const y = uniqueYs[i];
+        await adapter.scrollTo({ x: 0, y });
+        if (scrollSettleMs > 0) {
+            await sleep(scrollSettleMs);
+        }
+        const buffer = await withTimeout(
+            adapter.screenshot({ fullPage: false, type: 'png', omitBackground }),
+            timeout,
+            { operation: `adapter.screenshot(strip ${i + 1}/${uniqueYs.length})` }
+        );
+        strips.push({ y, buffer });
+        emit(events, 'strip:captured', { index: i, total: uniqueYs.length, y });
+    }
+
+    const stitchStart = nowMs();
+    const bytes = await stitchStrips(strips, {
+        width: metrics.viewport.width,
+        height: metrics.height,
+        format,
+        quality,
+    });
+    return { bytes, encodeMs: nowMs() - stitchStart };
+}
+
+/**
+ * Compute the scroll-y positions for strip capture. Each strip is `sh` px
+ * tall; we advance by `stride` (typically `sh - overlap`). The last strip
+ * is anchored at `height - sh` to avoid a partial trailing strip.
+ *
+ * @param {number} height
+ * @param {number} sh strip height
+ * @param {number} stride
+ * @returns {number[]}
+ */
+function planStripYs(height, sh, stride) {
+    const ys = [];
+    for (let y = 0; y < height; y += stride) {
+        ys.push(Math.min(y, height - sh));
+        if (y + sh >= height) {
+            break;
+        }
+    }
+    return Array.from(new Set(ys));
+}
+
+/**
+ * Vertically stitch strip buffers into one final image and re-encode to
+ * the requested format.
+ *
+ * @param {Array<{y: number, buffer: Buffer}>} strips
+ * @param {{width: number, height: number, format: import('../types/index.d.ts').Format, quality: number}} target
+ * @returns {Promise<Buffer>}
+ */
+async function stitchStrips(strips, { width, height, format, quality }) {
+    const sharp = require('sharp');
+    const canvas = sharp({
+        create: {
+            width: Math.round(width),
+            height: Math.round(height),
+            channels: 4,
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+        },
+    }).png();
+
+    const composites = strips.map(({ y, buffer }) => ({
+        input: buffer,
+        top: Math.round(y),
+        left: 0,
+    }));
+
+    let pipeline = canvas.composite(composites);
+    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();
+}
+
+/**
+ * Sleep for ms. Used between scroll and capture so the page has time to
+ * paint the newly-revealed region.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+
+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);
+}
+
+/**
+ * Race a promise against a CaptureTimeoutError-throwing timer.
+ *
+ * @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);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+}
+
+module.exports = { captureLongPage };