@afixt/screenshot-utils 0.9.0

package/src/transform/crop.js

@@ -0,0 +1,251 @@
+'use strict';
+
+const { InvalidRectError, BufferCorruptError } = require('../errors/index.js');
+
+/**
+ * Extract a single rectangle from a source image buffer.
+ *
+ * Implements `spec.md` § 8.2.1. All coordinates are CSS pixels. Padding
+ * expands the rect in all four directions and is then clamped to the
+ * image bounds (we never error on padding causing under/overflow — the
+ * caller asked for slack, not arithmetic).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').Rect} rect
+ * @param {import('../types/index.d.ts').CropOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+async function crop(input, rect, options = {}) {
+    assertBuffer(input);
+    assertRect(rect);
+    const { padding = 0, format, quality = 90 } = options;
+    const sharp = require('sharp');
+
+    const meta = await readMeta(sharp, input);
+    const extract = computeExtract(rect, padding, meta);
+    if (extract.width <= 0 || extract.height <= 0) {
+        throw new InvalidRectError(
+            `Rect resolves to 0×0 after clamping to image bounds (${meta.width}×${meta.height})`,
+            { context: { rect, padding, imageWidth: meta.width, imageHeight: meta.height } }
+        );
+    }
+
+    let pipeline = sharp(input).extract(extract);
+    pipeline = applyFormat(pipeline, format, quality);
+    return pipeline.toBuffer();
+}
+
+/**
+ * Extract many rectangles in parallel from one source. Used by the engine's
+ * `_captureIssueScreenshots` migration path (one full-page capture + many
+ * crops beats N per-element captures by ~20×).
+ *
+ * Implements `spec.md` § 8.2.2.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<{ id: string, rect: import('../types/index.d.ts').Rect }>} entries
+ * @param {import('../types/index.d.ts').CropManyOptions} [options]
+ * @returns {Promise<Map<string, Buffer>>}
+ */
+async function cropMany(input, entries, options = {}) {
+    assertBuffer(input);
+    if (!Array.isArray(entries)) {
+        throw new InvalidRectError('cropMany entries must be an array', {
+            context: { received: typeof entries },
+        });
+    }
+    const { padding = 0, format, quality = 90, parallelism = 4 } = options;
+    const sharp = require('sharp');
+    const meta = await readMeta(sharp, input);
+
+    // Validate all rects up front so we fail fast (and uniformly) before
+    // doing any work, rather than partially producing crops then erroring.
+    const planned = entries.map(entry => {
+        if (!entry || typeof entry.id !== 'string') {
+            throw new InvalidRectError('Each cropMany entry must have a string id and a rect', {
+                context: { entry },
+            });
+        }
+        assertRect(entry.rect);
+        const extract = computeExtract(entry.rect, padding, meta);
+        if (extract.width <= 0 || extract.height <= 0) {
+            throw new InvalidRectError(
+                `Rect for id ${JSON.stringify(entry.id)} resolves to 0×0 after clamping`,
+                {
+                    context: {
+                        id: entry.id,
+                        rect: entry.rect,
+                        padding,
+                        imageWidth: meta.width,
+                        imageHeight: meta.height,
+                    },
+                }
+            );
+        }
+        return { id: entry.id, extract };
+    });
+
+    const results = new Map();
+    await parallelEach(
+        planned,
+        async ({ id, extract }) => {
+            let pipeline = sharp(input).extract(extract);
+            pipeline = applyFormat(pipeline, format, quality);
+            const buffer = await pipeline.toBuffer();
+            results.set(id, buffer);
+        },
+        Math.max(1, parallelism)
+    );
+    return results;
+}
+
+/**
+ * Run `fn(item)` over every item with at most `limit` in flight at once.
+ * Order of completion is irrelevant; the caller stores results by id.
+ *
+ * @template T
+ * @param {readonly T[]} items
+ * @param {(item: T, index: number) => Promise<void>} fn
+ * @param {number} limit
+ * @returns {Promise<void>}
+ */
+async function parallelEach(items, fn, limit) {
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length || 1) }, async () => {
+        while (cursor < items.length) {
+            const i = cursor;
+            cursor += 1;
+            await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+}
+
+/**
+ * Validate a rect has the right shape and finite, non-negative dimensions.
+ *
+ * @param {unknown} rect
+ */
+function assertRect(rect) {
+    if (rect === null || typeof rect !== 'object') {
+        throw new InvalidRectError('rect must be an object', {
+            context: { received: typeof rect },
+        });
+    }
+    const { x, y, width, height } = /** @type {Record<string, unknown>} */ (rect);
+    for (const [key, value] of [
+        ['x', x],
+        ['y', y],
+        ['width', width],
+        ['height', height],
+    ]) {
+        if (!Number.isFinite(value)) {
+            throw new InvalidRectError(`rect.${key} must be a finite number`, {
+                context: { rect },
+            });
+        }
+    }
+    if (width <= 0 || height <= 0) {
+        throw new InvalidRectError('rect.width and rect.height must be > 0', {
+            context: { rect },
+        });
+    }
+}
+
+function assertBuffer(input) {
+    if (!Buffer.isBuffer(input)) {
+        throw new BufferCorruptError('input must be a Buffer', {
+            context: { received: typeof input },
+        });
+    }
+}
+
+/**
+ * Compute the integer rect that sharp.extract expects after applying
+ * padding and clamping to image bounds. Padding is symmetric; clamping
+ * never throws — we just shrink the requested area.
+ *
+ * @param {import('../types/index.d.ts').Rect} rect
+ * @param {number} padding
+ * @param {{width: number, height: number}} meta
+ * @returns {{left: number, top: number, width: number, height: number}}
+ */
+function computeExtract(rect, padding, meta) {
+    const left = clamp(Math.round(rect.x - padding), 0, meta.width);
+    const top = clamp(Math.round(rect.y - padding), 0, meta.height);
+    const right = clamp(Math.round(rect.x + rect.width + padding), 0, meta.width);
+    const bottom = clamp(Math.round(rect.y + rect.height + padding), 0, meta.height);
+    return {
+        left,
+        top,
+        width: Math.max(0, right - left),
+        height: Math.max(0, bottom - top),
+    };
+}
+
+function clamp(n, lo, hi) {
+    if (n < lo) {
+        return lo;
+    }
+    if (n > hi) {
+        return hi;
+    }
+    return n;
+}
+
+/**
+ * Read image dimensions via sharp.metadata(). Wraps sharp-thrown errors
+ * as BufferCorruptError so callers see the package's error contract.
+ *
+ * @param {ReturnType<typeof require>} sharp
+ * @param {Buffer} input
+ * @returns {Promise<{width: number, height: number}>}
+ */
+async function readMeta(sharp, input) {
+    try {
+        const meta = await sharp(input).metadata();
+        if (!meta.width || !meta.height) {
+            throw new BufferCorruptError('Image has no detectable dimensions', {
+                context: { meta },
+            });
+        }
+        return { width: meta.width, height: meta.height };
+    } catch (error) {
+        if (error instanceof BufferCorruptError) {
+            throw error;
+        }
+        throw new BufferCorruptError('sharp could not read input buffer metadata', {
+            cause: error,
+        });
+    }
+}
+
+/**
+ * Apply the requested output format to a sharp pipeline. When `format` is
+ * undefined the pipeline keeps its native format (input format inferred).
+ *
+ * @template T
+ * @param {T} pipeline
+ * @param {string | undefined} format
+ * @param {number} quality
+ * @returns {T}
+ */
+function applyFormat(pipeline, format, quality) {
+    if (!format) {
+        return pipeline;
+    }
+    switch (format) {
+        case 'png':
+            return pipeline.png();
+        case 'jpeg':
+            return pipeline.jpeg({ quality });
+        case 'webp':
+            return pipeline.webp({ quality });
+        default:
+            return pipeline;
+    }
+}
+
+module.exports = { crop, cropMany };

package/src/transform/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { crop, cropMany } = require('./crop.js');
+const { convert } = require('./convert.js');
+const { resize } = require('./resize.js');
+const { normalize } = require('./normalize.js');
+
+module.exports = { crop, cropMany, convert, resize, normalize };

package/src/transform/normalize.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const { BufferCorruptError } = require('../errors/index.js');
+
+/**
+ * Normalize an image buffer to a target device-pixel ratio so its coordinate
+ * space is CSS pixels regardless of the source DPR.
+ *
+ * Implements `spec.md` § 8.2.5. Default behavior preserves the image's
+ * intrinsic DPR (caller opts in to normalization for cross-DPR comparison).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').NormalizeOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').NormalizeResult>}
+ */
+async function normalize(input, options = {}) {
+    assertBuffer(input);
+    const sharp = require('sharp');
+    const meta = await readMeta(sharp, input);
+
+    const { fromDpr = inferDpr(meta), toDpr = 1 } = options;
+    if (!Number.isFinite(fromDpr) || fromDpr <= 0) {
+        throw new BufferCorruptError('Could not infer source DPR and no fromDpr supplied', {
+            context: { meta, fromDpr },
+        });
+    }
+    const scale = toDpr / fromDpr;
+    if (scale === 1) {
+        // No-op: keep the input buffer; report its current CSS dimensions.
+        return {
+            buffer: input,
+            dimensions: {
+                width: Math.round(meta.width / fromDpr),
+                height: Math.round(meta.height / fromDpr),
+            },
+        };
+    }
+    const targetWidth = Math.max(1, Math.round(meta.width * scale));
+    const targetHeight = Math.max(1, Math.round(meta.height * scale));
+    const buffer = await sharp(input)
+        .resize({ width: targetWidth, height: targetHeight })
+        .toBuffer();
+    return {
+        buffer,
+        dimensions: { width: targetWidth, height: targetHeight },
+    };
+}
+
+/**
+ * Infer the source image's DPR from metadata. Sharp doesn't expose a
+ * direct devicePixelRatio so we use the density hint when present
+ * (DPI / 96), otherwise assume 1.
+ *
+ * @param {Awaited<ReturnType<import('sharp').Sharp['metadata']>>} meta
+ * @returns {number}
+ */
+function inferDpr(meta) {
+    if (meta && Number.isFinite(meta.density) && meta.density > 0) {
+        return meta.density / 96;
+    }
+    return 1;
+}
+
+function assertBuffer(input) {
+    if (!Buffer.isBuffer(input)) {
+        throw new BufferCorruptError('input must be a Buffer', {
+            context: { received: typeof input },
+        });
+    }
+}
+
+async function readMeta(sharp, input) {
+    try {
+        return await sharp(input).metadata();
+    } catch (error) {
+        throw new BufferCorruptError('sharp could not read input buffer metadata', {
+            cause: error,
+        });
+    }
+}
+
+module.exports = { normalize };

package/src/transform/resize.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const { BufferCorruptError, InvalidRectError } = require('../errors/index.js');
+
+/**
+ * Resize an image buffer with sharp-native semantics.
+ *
+ * Implements `spec.md` § 8.2.3. Honors `width`, `height`, `fit`, `position`,
+ * `kernel`, and `withoutEnlargement`. At least one of `width` or `height`
+ * must be supplied.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').ResizeOptions} options
+ * @returns {Promise<Buffer>}
+ */
+async function resize(input, options) {
+    assertBuffer(input);
+    if (!options || typeof options !== 'object') {
+        throw new InvalidRectError('resize requires an options object', {
+            context: { received: typeof options },
+        });
+    }
+    const {
+        width,
+        height,
+        fit,
+        position,
+        kernel,
+        withoutEnlargement,
+        format,
+        quality = 90,
+    } = options;
+    if (width === undefined && height === undefined) {
+        throw new InvalidRectError('resize requires at least one of width or height', {
+            context: { options },
+        });
+    }
+    if (width !== undefined && (!Number.isFinite(width) || width <= 0)) {
+        throw new InvalidRectError('resize.width must be a positive finite number', {
+            context: { width },
+        });
+    }
+    if (height !== undefined && (!Number.isFinite(height) || height <= 0)) {
+        throw new InvalidRectError('resize.height must be a positive finite number', {
+            context: { height },
+        });
+    }
+    const sharp = require('sharp');
+    const resizeOpts = {};
+    if (width !== undefined) {
+        resizeOpts.width = Math.round(width);
+    }
+    if (height !== undefined) {
+        resizeOpts.height = Math.round(height);
+    }
+    if (fit) {
+        resizeOpts.fit = fit;
+    }
+    if (position) {
+        resizeOpts.position = position;
+    }
+    if (kernel) {
+        resizeOpts.kernel = kernel;
+    }
+    if (withoutEnlargement !== undefined) {
+        resizeOpts.withoutEnlargement = withoutEnlargement;
+    }
+    let pipeline = sharp(input).resize(resizeOpts);
+    switch (format) {
+        case 'png':
+            pipeline = pipeline.png();
+
+            break;
+
+        case 'jpeg':
+            pipeline = pipeline.jpeg({ quality });
+
+            break;
+
+        case 'webp':
+            pipeline = pipeline.webp({ quality });
+
+            break;
+
+        // No default
+    }
+    return pipeline.toBuffer();
+}
+
+function assertBuffer(input) {
+    if (!Buffer.isBuffer(input)) {
+        throw new BufferCorruptError('input must be a Buffer', {
+            context: { received: typeof input },
+        });
+    }
+}
+
+module.exports = { resize };