@afixt/screenshot-utils 0.9.0

package/src/redact/redact.js

@@ -0,0 +1,268 @@
+'use strict';
+
+const { BufferCorruptError, RedactionError, InvalidRectError } = require('../errors/index.js');
+
+const VALID_MODES = new Set(['blur', 'mask', 'pixelate']);
+
+/**
+ * Apply one of three redaction modes to specified regions of an image.
+ *
+ * Implements `spec.md` § 8.5.1.
+ *
+ * - `mode: 'blur'` — Gaussian blur with the given `radius`.
+ * - `mode: 'mask'` — solid-color fill (`color`, default `#000`).
+ * - `mode: 'pixelate'` — downscale-then-upscale with the given `cellSize`.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<import('../types/index.d.ts').RedactRegion>} regions
+ * @param {import('../types/index.d.ts').RedactOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+async function redact(input, regions, options = {}) {
+    if (process.env.AFIXT_SCREENSHOT_DISABLE_REDACTION === '1') {
+        // Spec § 11.3 escape hatch for test fixtures only.
+        return input;
+    }
+    assertBuffer(input);
+    if (!Array.isArray(regions)) {
+        throw new RedactionError('regions must be an array', {
+            context: { received: typeof regions },
+        });
+    }
+    const { default: defaultMode = 'blur', defaultRadius = 8 } = options;
+    if (!VALID_MODES.has(defaultMode)) {
+        throw new RedactionError(
+            `default mode must be one of ${[...VALID_MODES].join(', ')}; received ${defaultMode}`,
+            { context: { received: defaultMode } }
+        );
+    }
+
+    const sharp = require('sharp');
+    const meta = await readMeta(sharp, input);
+
+    if (regions.length === 0) {
+        return input;
+    }
+
+    // Build the composite layer list. Each region produces ONE overlay
+    // that sharp composites at the right offset. Tiny rects (< 1px) are
+    // silently dropped — they cannot produce useful output.
+    const overlays = [];
+    for (const [i, region] of regions.entries()) {
+        const overlay = await buildOverlay(sharp, input, region, {
+            index: i,
+            defaultMode,
+            defaultRadius,
+            meta,
+        });
+        if (overlay) {
+            overlays.push(overlay);
+        }
+    }
+
+    return sharp(input).composite(overlays).toBuffer();
+}
+
+/**
+ * Produce a single composite descriptor for one region. Returns null
+ * when the region clamps to a zero-area rect after image-bound clamping.
+ *
+ * @param {ReturnType<typeof require>} sharp
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').RedactRegion} region
+ * @param {{index: number, defaultMode: string, defaultRadius: number, meta: {width: number, height: number}}} ctx
+ * @returns {Promise<{input: Buffer, top: number, left: number} | null>}
+ */
+async function buildOverlay(sharp, input, region, ctx) {
+    assertRegion(region, ctx.index);
+    const mode = region.mode ?? ctx.defaultMode;
+    if (!VALID_MODES.has(mode)) {
+        throw new RedactionError(
+            `regions[${ctx.index}].mode must be 'blur', 'mask', or 'pixelate'; received ${mode}`,
+            { context: { index: ctx.index, mode } }
+        );
+    }
+    const clamped = clampRect(region.rect, ctx.meta);
+    if (clamped.width <= 0 || clamped.height <= 0) {
+        return null;
+    }
+
+    switch (mode) {
+        case 'blur':
+            return blurOverlay(sharp, input, clamped, region.radius ?? ctx.defaultRadius);
+        case 'mask':
+            return maskOverlay(sharp, clamped, region.color ?? '#000');
+        case 'pixelate':
+            return pixelateOverlay(sharp, input, clamped, region.cellSize ?? 16);
+        default:
+            return null;
+    }
+}
+
+/**
+ * Build a blurred crop overlay.
+ *
+ * @param {ReturnType<typeof require>} sharp
+ * @param {Buffer} input
+ * @param {{left: number, top: number, width: number, height: number}} rect
+ * @param {number} radius
+ * @returns {Promise<{input: Buffer, top: number, left: number}>}
+ */
+async function blurOverlay(sharp, input, rect, radius) {
+    const validRadius = Math.max(0.3, Math.min(1000, Number(radius) || 8));
+    const buffer = await sharp(input)
+        .extract({ left: rect.left, top: rect.top, width: rect.width, height: rect.height })
+        .blur(validRadius)
+        .toBuffer();
+    return { input: buffer, top: rect.top, left: rect.left };
+}
+
+/**
+ * Build a solid-color mask overlay.
+ *
+ * @param {ReturnType<typeof require>} sharp
+ * @param {{left: number, top: number, width: number, height: number}} rect
+ * @param {string} color CSS color string (#000 by default).
+ * @returns {Promise<{input: Buffer, top: number, left: number}>}
+ */
+async function maskOverlay(sharp, rect, color) {
+    const { r, g, b, alpha } = parseColor(color);
+    const buffer = await sharp({
+        create: {
+            width: rect.width,
+            height: rect.height,
+            channels: 4,
+            background: { r, g, b, alpha },
+        },
+    })
+        .png()
+        .toBuffer();
+    return { input: buffer, top: rect.top, left: rect.left };
+}
+
+/**
+ * Build a pixelated crop overlay (downsize then upsize, nearest-neighbour).
+ *
+ * @param {ReturnType<typeof require>} sharp
+ * @param {Buffer} input
+ * @param {{left: number, top: number, width: number, height: number}} rect
+ * @param {number} cellSize
+ * @returns {Promise<{input: Buffer, top: number, left: number}>}
+ */
+async function pixelateOverlay(sharp, input, rect, cellSize) {
+    const cs = Math.max(2, Math.round(cellSize) || 16);
+    const downW = Math.max(1, Math.floor(rect.width / cs));
+    const downH = Math.max(1, Math.floor(rect.height / cs));
+    const buffer = await sharp(input)
+        .extract({ left: rect.left, top: rect.top, width: rect.width, height: rect.height })
+        .resize({ width: downW, height: downH, kernel: 'nearest' })
+        .resize({ width: rect.width, height: rect.height, kernel: 'nearest' })
+        .toBuffer();
+    return { input: buffer, top: rect.top, left: rect.left };
+}
+
+/**
+ * Clamp a rect to image bounds and round to integers (sharp.extract needs ints).
+ *
+ * @param {import('../types/index.d.ts').Rect} rect
+ * @param {{width: number, height: number}} meta
+ * @returns {{left: number, top: number, width: number, height: number}}
+ */
+function clampRect(rect, meta) {
+    const left = Math.max(0, Math.min(meta.width, Math.round(rect.x)));
+    const top = Math.max(0, Math.min(meta.height, Math.round(rect.y)));
+    const right = Math.max(0, Math.min(meta.width, Math.round(rect.x + rect.width)));
+    const bottom = Math.max(0, Math.min(meta.height, Math.round(rect.y + rect.height)));
+    return {
+        left,
+        top,
+        width: Math.max(0, right - left),
+        height: Math.max(0, bottom - top),
+    };
+}
+
+function assertRegion(region, index) {
+    if (!region || typeof region !== 'object') {
+        throw new RedactionError(`regions[${index}] must be an object`, {
+            context: { index, received: typeof region },
+        });
+    }
+    const rect = region.rect;
+    if (
+        !rect ||
+        !Number.isFinite(rect.x) ||
+        !Number.isFinite(rect.y) ||
+        !Number.isFinite(rect.width) ||
+        !Number.isFinite(rect.height)
+    ) {
+        throw new InvalidRectError(`regions[${index}].rect must be a finite Rect`, {
+            context: { index, rect },
+        });
+    }
+}
+
+/**
+ * Parse a CSS color string (`#rgb`, `#rrggbb`, `#rrggbbaa`, or named black).
+ *
+ * @param {string} color
+ * @returns {{r: number, g: number, b: number, alpha: number}}
+ */
+function parseColor(color) {
+    if (typeof color !== 'string') {
+        return { r: 0, g: 0, b: 0, alpha: 1 };
+    }
+    const hex = color.trim().replace(/^#/, '');
+    if (hex.length === 3) {
+        return {
+            r: Number.parseInt(hex[0] + hex[0], 16),
+            g: Number.parseInt(hex[1] + hex[1], 16),
+            b: Number.parseInt(hex[2] + hex[2], 16),
+            alpha: 1,
+        };
+    }
+    if (hex.length === 6) {
+        return {
+            r: Number.parseInt(hex.slice(0, 2), 16),
+            g: Number.parseInt(hex.slice(2, 4), 16),
+            b: Number.parseInt(hex.slice(4, 6), 16),
+            alpha: 1,
+        };
+    }
+    if (hex.length === 8) {
+        return {
+            r: Number.parseInt(hex.slice(0, 2), 16),
+            g: Number.parseInt(hex.slice(2, 4), 16),
+            b: Number.parseInt(hex.slice(4, 6), 16),
+            alpha: Number.parseInt(hex.slice(6, 8), 16) / 255,
+        };
+    }
+    return { r: 0, g: 0, b: 0, alpha: 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 {
+        const meta = await sharp(input).metadata();
+        if (!meta.width || !meta.height) {
+            throw new BufferCorruptError('Image has no detectable dimensions');
+        }
+        return { width: meta.width, height: meta.height };
+    } catch (error) {
+        if (error instanceof BufferCorruptError) {
+            throw error;
+        }
+        throw new BufferCorruptError('sharp could not read redact input buffer', {
+            cause: error,
+        });
+    }
+}
+
+module.exports = { redact, parseColor };

package/src/tile/dzi.js

@@ -0,0 +1,268 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { randomUUID } = require('node:crypto');
+
+const { TileSizeError, TileWriteError, BufferCorruptError } = require('../errors/index.js');
+
+const MAX_TILES = 10_000;
+
+/**
+ * Generate a Deep Zoom Image pyramid from a source buffer using
+ * `sharp().tile({ layout: 'dz' })`.
+ *
+ * Implements `spec.md` § 8.4.1. Three output modes:
+ * - `'buffers'` (default): returns tile bytes in memory, cleans up the temp dir.
+ * - `'directory'`: returns the path to the temp dir; the caller is responsible
+ *   for moving / uploading / deleting it.
+ * - `'stream'`: NOT IMPLEMENTED in v1.0 (per spec § 22 — deferred to v1.1).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').TileDziOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').DziResult>}
+ */
+async function tileDzi(input, options = {}) {
+    assertBuffer(input);
+    const {
+        tileSize = 256,
+        overlap = 1,
+        tileFormat = 'webp',
+        quality = 80,
+        output = 'buffers',
+        name,
+    } = options;
+
+    if (tileSize !== 256 && tileSize !== 512) {
+        throw new TileSizeError(`tileSize must be 256 or 512; received ${tileSize}`, {
+            context: { tileSize },
+        });
+    }
+    if (output === 'stream') {
+        throw new TileSizeError(
+            "output: 'stream' is deferred to v1.1; use 'buffers' or 'directory'",
+            { context: { output } }
+        );
+    }
+    if (!['buffers', 'directory'].includes(output)) {
+        throw new TileSizeError(`output must be 'buffers' or 'directory'; received ${output}`, {
+            context: { output },
+        });
+    }
+
+    const sharp = require('sharp');
+
+    const meta = await readMeta(sharp, input);
+    const totalEstimate = estimateTileCount(meta.width, meta.height, tileSize);
+    if (totalEstimate > MAX_TILES) {
+        throw new TileSizeError(
+            `Estimated tile count ${totalEstimate} exceeds the ${MAX_TILES} ceiling for a single tileDzi() call`,
+            {
+                context: {
+                    width: meta.width,
+                    height: meta.height,
+                    tileSize,
+                    estimate: totalEstimate,
+                },
+            }
+        );
+    }
+
+    const dirName = name ?? `dzi-${randomUUID()}`;
+    let tempDir;
+    try {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'screenshot-utils-dzi-'));
+    } catch (error) {
+        throw new TileWriteError('Failed to create temp directory for DZI output', {
+            cause: error,
+        });
+    }
+
+    const outputBase = path.join(tempDir, dirName);
+    try {
+        await applyTileFormat(sharp(input), tileFormat, quality)
+            .tile({ size: tileSize, overlap, layout: 'dz' })
+            .toFile(outputBase);
+    } catch (error) {
+        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+        throw new TileWriteError('sharp().tile().toFile() failed', { cause: error });
+    }
+
+    const dziXml = await readDziXml(outputBase);
+    const tiles = await collectTiles({
+        outputBase,
+        dirName,
+        output,
+    });
+
+    if (output === 'buffers') {
+        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    }
+
+    return {
+        descriptor: {
+            xml: dziXml,
+            format: tileFormat,
+            width: meta.width,
+            height: meta.height,
+            tileSize,
+            overlap,
+        },
+        tiles,
+        outputDir: output === 'directory' ? tempDir : undefined,
+        totalBytes: tiles.reduce((sum, t) => sum + (t.bytes ? t.bytes.length : 0), 0),
+        totalTiles: tiles.length,
+    };
+}
+
+/**
+ * Estimate the total tile count across all pyramid levels for sanity-limit
+ * enforcement before invoking sharp. Each level halves the dimensions; the
+ * lowest level is always 1×1.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {number} tileSize
+ * @returns {number}
+ */
+function estimateTileCount(width, height, tileSize) {
+    let total = 0;
+    let w = width;
+    let h = height;
+    while (w >= 1 && h >= 1) {
+        const cols = Math.ceil(w / tileSize);
+        const rows = Math.ceil(h / tileSize);
+        total += cols * rows;
+        if (w === 1 && h === 1) {
+            break;
+        }
+        w = Math.max(1, Math.ceil(w / 2));
+        h = Math.max(1, Math.ceil(h / 2));
+    }
+    return total;
+}
+
+/**
+ * Apply the requested tile format on a sharp pipeline before .tile().
+ * Sharp uses the pipeline's selected format for emitted tile files.
+ *
+ * @template T
+ * @param {T} pipeline
+ * @param {string} format
+ * @param {number} quality
+ * @returns {T}
+ */
+function applyTileFormat(pipeline, format, quality) {
+    switch (format) {
+        case 'png':
+            return pipeline.png();
+        case 'jpeg':
+            return pipeline.jpeg({ quality });
+        case 'webp':
+            return pipeline.webp({ quality });
+        default:
+            throw new TileSizeError(`tileFormat must be png, jpeg, or webp; received ${format}`, {
+                context: { tileFormat: format },
+            });
+    }
+}
+
+/**
+ * Read the .dzi XML descriptor written by sharp.
+ *
+ * @param {string} outputBase Path without extension.
+ * @returns {Promise<string>}
+ */
+async function readDziXml(outputBase) {
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        return await fs.readFile(`${outputBase}.dzi`, 'utf8');
+    } catch (error) {
+        throw new TileWriteError('Sharp did not produce the .dzi descriptor file', {
+            cause: error,
+        });
+    }
+}
+
+/**
+ * Walk the `<base>_files/` tree and assemble the tile list. Each tile path
+ * is recorded relative to the DZI root (matching the DZI spec).
+ *
+ * @param {{outputBase: string, dirName: string, output: 'buffers'|'directory'}} args
+ * @returns {Promise<Array<import('../types/index.d.ts').DziTile>>}
+ */
+async function collectTiles({ outputBase, dirName, output }) {
+    const filesDir = `${outputBase}_files`;
+    const tiles = [];
+    /** @type {string[]} */
+    let levels;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        levels = await fs.readdir(filesDir);
+    } catch (error) {
+        throw new TileWriteError('Sharp did not produce the _files directory', {
+            cause: error,
+        });
+    }
+    const levelNums = levels
+        .map(Number)
+        .filter(n => Number.isFinite(n))
+        .toSorted((a, b) => a - b);
+
+    for (const level of levelNums) {
+        const levelDir = path.join(filesDir, String(level));
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        const dirEntries = await fs.readdir(levelDir);
+        const fileNames = dirEntries.toSorted();
+        for (const fileName of fileNames) {
+            const match = /^(\d+)_(\d+)\.\w+$/.exec(fileName);
+            if (!match) {
+                continue;
+            }
+            const col = Number(match[1]);
+            const row = Number(match[2]);
+            const relPath = `${dirName}_files/${level}/${fileName}`;
+            const entry = {
+                level,
+                col,
+                row,
+                path: relPath,
+            };
+            if (output === 'buffers') {
+                // eslint-disable-next-line security/detect-non-literal-fs-filename
+                entry.bytes = await fs.readFile(path.join(levelDir, fileName));
+            }
+            tiles.push(entry);
+        }
+    }
+    return tiles;
+}
+
+async function readMeta(sharp, input) {
+    try {
+        const meta = await sharp(input).metadata();
+        if (!meta.width || !meta.height) {
+            throw new BufferCorruptError('Input image has no detectable dimensions');
+        }
+        return { width: meta.width, height: meta.height };
+    } catch (error) {
+        if (error instanceof BufferCorruptError) {
+            throw error;
+        }
+        throw new BufferCorruptError('sharp could not read tile input buffer', {
+            cause: error,
+        });
+    }
+}
+
+function assertBuffer(input) {
+    if (!Buffer.isBuffer(input)) {
+        throw new BufferCorruptError('input must be a Buffer', {
+            context: { received: typeof input },
+        });
+    }
+}
+
+module.exports = { tileDzi, MAX_TILES };

package/src/tile/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { tileDzi } = require('./dzi.js');
+
+module.exports = { tileDzi };

package/src/transform/convert.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { BufferCorruptError, UnsupportedFormatError } = require('../errors/index.js');
+
+/**
+ * Re-encode a buffer to a different image format.
+ *
+ * Implements `spec.md` § 8.2.4. Thin wrapper over `sharp(buf).toFormat()`
+ * with safer defaults and the package's error contract.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').ConvertOptions} options
+ * @returns {Promise<Buffer>}
+ */
+async function convert(input, options) {
+    assertBuffer(input);
+    if (!options || typeof options !== 'object') {
+        throw new UnsupportedFormatError('convert requires an options object with a format', {
+            context: { received: typeof options },
+        });
+    }
+    const { format, quality = 90, lossless = false, effort = 4 } = options;
+    if (!['png', 'jpeg', 'webp'].includes(format)) {
+        throw new UnsupportedFormatError(
+            `format must be 'png', 'jpeg', or 'webp'; received ${JSON.stringify(format)}`,
+            { context: { received: format } }
+        );
+    }
+    const sharp = require('sharp');
+    let pipeline = sharp(input);
+    switch (format) {
+        case 'png':
+            pipeline = pipeline.png();
+            break;
+        case 'jpeg':
+            pipeline = pipeline.jpeg({ quality });
+            break;
+        case 'webp':
+            pipeline = pipeline.webp({ quality, lossless, effort });
+            break;
+    }
+    return pipeline.toBuffer();
+}
+
+function assertBuffer(input) {
+    if (!Buffer.isBuffer(input)) {
+        throw new BufferCorruptError('input must be a Buffer', {
+            context: { received: typeof input },
+        });
+    }
+}
+
+module.exports = { convert };