@afixt/screenshot-utils 0.9.0

package/src/cli/index.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+
+const { crop } = require('../transform/crop.js');
+const { convert } = require('../transform/convert.js');
+const { tileDzi } = require('../tile/dzi.js');
+const { diff } = require('../compose/diff.js');
+
+const COMMANDS = {
+    crop: cropCommand,
+    convert: convertCommand,
+    tile: tileCommand,
+    diff: diffCommand,
+};
+
+const HELP = `Usage: afixt-screenshot <command> [...args]
+
+Commands:
+  crop <input>     Extract a rectangle from an image.
+  convert <input>  Re-encode an image to png/jpeg/webp.
+  tile <input>     Generate a DZI tile pyramid from an image.
+  diff <a> <b>     Visual diff between two images (requires pixelmatch).
+
+Run "afixt-screenshot <command> --help" for command-specific options.
+`;
+
+/**
+ * CLI entry. Returns the process exit code (0 = success).
+ *
+ * @public
+ * @param {string[]} argv The argv array minus the node binary + script path
+ *                        (i.e. process.argv.slice(2)).
+ * @returns {Promise<number>}
+ */
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === '--help' || command === '-h') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (!Object.hasOwn(COMMANDS, command)) {
+        process.stderr.write(`Unknown command: ${command}\n${HELP}`);
+        return 2;
+    }
+    try {
+        await COMMANDS[command](rest);
+        return 0;
+    } catch (error) {
+        const code = error?.code ? ` [${error.code}]` : '';
+        process.stderr.write(`Error${code}: ${error?.message ?? String(error)}\n`);
+        return 1;
+    }
+}
+
+async function cropCommand(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            rect: { type: 'string' },
+            padding: { type: 'string' },
+            format: { type: 'string' },
+            quality: { type: 'string' },
+            out: { type: 'string', short: 'o' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        process.stdout.write(
+            'Usage: afixt-screenshot crop <input> --rect x,y,w,h [--padding N] [--format png|jpeg|webp] [--quality 1-100] [--out file]\n'
+        );
+        return;
+    }
+    const [input] = positionals;
+    if (!input) {
+        throw new Error('crop requires an input file path');
+    }
+    if (!values.rect) {
+        throw new Error('crop requires --rect x,y,width,height');
+    }
+    const rect = parseRect(values.rect);
+    const opts = {};
+    if (values.padding !== undefined) {
+        opts.padding = Number(values.padding);
+    }
+    if (values.format) {
+        opts.format = values.format;
+    }
+    if (values.quality !== undefined) {
+        opts.quality = Number(values.quality);
+    }
+    const buffer = await readBuffer(input);
+    const result = await crop(buffer, rect, opts);
+    await writeOutput(result, values.out);
+}
+
+async function convertCommand(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            format: { type: 'string' },
+            quality: { type: 'string' },
+            lossless: { type: 'boolean' },
+            out: { type: 'string', short: 'o' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        process.stdout.write(
+            'Usage: afixt-screenshot convert <input> --format png|jpeg|webp [--quality 1-100] [--lossless] [--out file]\n'
+        );
+        return;
+    }
+    const [input] = positionals;
+    if (!input) {
+        throw new Error('convert requires an input file path');
+    }
+    if (!values.format) {
+        throw new Error('convert requires --format png|jpeg|webp');
+    }
+    const opts = { format: values.format };
+    if (values.quality !== undefined) {
+        opts.quality = Number(values.quality);
+    }
+    if (values.lossless) {
+        opts.lossless = true;
+    }
+    const buffer = await readBuffer(input);
+    const result = await convert(buffer, opts);
+    await writeOutput(result, values.out);
+}
+
+async function tileCommand(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            'tile-size': { type: 'string' },
+            overlap: { type: 'string' },
+            format: { type: 'string' },
+            quality: { type: 'string' },
+            out: { type: 'string', short: 'o' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        process.stdout.write(
+            'Usage: afixt-screenshot tile <input> --out <directory> [--tile-size 256|512] [--overlap N] [--format png|jpeg|webp] [--quality 1-100]\n'
+        );
+        return;
+    }
+    const [input] = positionals;
+    if (!input) {
+        throw new Error('tile requires an input file path');
+    }
+    const opts = { output: 'directory' };
+    if (values['tile-size']) {
+        opts.tileSize = Number(values['tile-size']);
+    }
+    if (values.overlap !== undefined) {
+        opts.overlap = Number(values.overlap);
+    }
+    if (values.format) {
+        opts.tileFormat = values.format;
+    }
+    if (values.quality !== undefined) {
+        opts.quality = Number(values.quality);
+    }
+    const buffer = await readBuffer(input);
+    const result = await tileDzi(buffer, opts);
+    if (values.out) {
+        // Move the temp dir to the requested location.
+        const fs = require('node:fs/promises');
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        await fs.rename(result.outputDir, values.out);
+        process.stdout.write(`Wrote DZI tree to ${values.out} (${result.totalTiles} tiles)\n`);
+    } else {
+        process.stdout.write(
+            `Wrote DZI tree to ${result.outputDir} (${result.totalTiles} tiles)\n`
+        );
+    }
+}
+
+async function diffCommand(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            threshold: { type: 'string' },
+            out: { type: 'string', short: 'o' },
+            output: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        process.stdout.write(
+            'Usage: afixt-screenshot diff <a> <b> [--threshold N] [--output overlay|side-by-side|mask-only] [--out file]\n'
+        );
+        return;
+    }
+    const [a, b] = positionals;
+    if (!a || !b) {
+        throw new Error('diff requires two input file paths');
+    }
+    const opts = {};
+    if (values.threshold !== undefined) {
+        opts.threshold = Number(values.threshold);
+    }
+    if (values.output) {
+        opts.output = values.output;
+    }
+    const [bufferA, bufferB] = await Promise.all([readBuffer(a), readBuffer(b)]);
+    const result = await diff(bufferA, bufferB, opts);
+    process.stdout.write(
+        `${result.changedPixels} of ${result.totalPixels} pixels changed (${result.percentChanged.toFixed(2)}%)\n`
+    );
+    await writeOutput(result.diffBuffer, values.out);
+}
+
+/**
+ * Read a file's contents as a Buffer.
+ *
+ * @param {string} input
+ * @returns {Promise<Buffer>}
+ */
+async function readBuffer(input) {
+    const fs = require('node:fs/promises');
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    return fs.readFile(input);
+}
+
+/**
+ * Write the buffer to `out` if supplied; otherwise to stdout.
+ *
+ * @param {Buffer} buffer
+ * @param {string | undefined} out
+ */
+async function writeOutput(buffer, out) {
+    if (out) {
+        const fs = require('node:fs/promises');
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        await fs.writeFile(out, buffer);
+        return;
+    }
+    process.stdout.write(buffer);
+}
+
+/**
+ * Parse a comma-separated rect string into a Rect object.
+ *
+ * @param {string} s
+ * @returns {{x: number, y: number, width: number, height: number}}
+ */
+function parseRect(s) {
+    const parts = String(s).split(',').map(Number);
+    if (parts.length !== 4 || parts.some(n => !Number.isFinite(n))) {
+        throw new Error(
+            `--rect must be four comma-separated numbers; received ${JSON.stringify(s)}`
+        );
+    }
+    return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+}
+
+module.exports = { main };

package/src/compose/annotate.js

@@ -0,0 +1,283 @@
+'use strict';
+
+const {
+    BufferCorruptError,
+    ThemeError,
+    HeatmapPointError,
+    ComposeError,
+} = require('../errors/index.js');
+const { defaultTheme } = require('./theme.js');
+
+const MAX_ANNOTATIONS = 5000;
+const VALID_LEGEND_POSITIONS = new Set([
+    'none',
+    'top-left',
+    'top-right',
+    'bottom-left',
+    'bottom-right',
+]);
+
+/**
+ * Render annotation overlays onto a screenshot buffer.
+ *
+ * Implements `spec.md` § 8.3.1 with pure-sharp rendering — annotations are
+ * serialized to an SVG layer and composited onto the source image. No
+ * `@napi-rs/canvas` dep in v1.0 (deferred to v1.1 per spec § 22).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<import('../types/index.d.ts').Annotation>} annotations
+ * @param {import('../types/index.d.ts').AnnotateOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+async function annotate(input, annotations, options = {}) {
+    assertBuffer(input);
+    if (!Array.isArray(annotations)) {
+        throw new HeatmapPointError('annotations must be an array', {
+            context: { received: typeof annotations },
+        });
+    }
+    if (annotations.length > MAX_ANNOTATIONS) {
+        throw new ComposeError(
+            `Cannot annotate more than ${MAX_ANNOTATIONS} regions in a single call`,
+            { context: { received: annotations.length, max: MAX_ANNOTATIONS } }
+        );
+    }
+    const { theme: callerTheme, output = 'png', legend = 'none' } = options;
+    if (!VALID_LEGEND_POSITIONS.has(legend)) {
+        throw new ThemeError(
+            `legend must be one of ${[...VALID_LEGEND_POSITIONS].join(', ')}; received ${JSON.stringify(legend)}`,
+            { context: { received: legend } }
+        );
+    }
+    if (output !== 'png' && output !== 'svg') {
+        throw new ComposeError(
+            `annotate output must be 'png' or 'svg'; received ${JSON.stringify(output)}`,
+            { context: { received: output } }
+        );
+    }
+    const theme = mergeTheme(defaultTheme, callerTheme);
+
+    // Validate every annotation up-front so we fail fast.
+    for (const [i, ann] of annotations.entries()) {
+        assertAnnotation(ann, i, theme);
+    }
+
+    const sharp = require('sharp');
+    const meta = await readMeta(sharp, input);
+
+    const svg = buildSvg(meta, annotations, theme, legend);
+
+    if (output === 'svg') {
+        return Buffer.from(svg, 'utf8');
+    }
+
+    return sharp(input)
+        .composite([{ input: Buffer.from(svg, 'utf8'), top: 0, left: 0 }])
+        .toBuffer();
+}
+
+/**
+ * Shallow-merge a caller theme over the default. Missing keys fall back to
+ * the default; missing properties on a present key throw ThemeError so
+ * consumers can't silently render an invisible annotation.
+ *
+ * @param {import('../types/index.d.ts').AnnotationTheme} base
+ * @param {import('../types/index.d.ts').AnnotationTheme | undefined} extra
+ * @returns {import('../types/index.d.ts').AnnotationTheme}
+ */
+function mergeTheme(base, extra) {
+    if (!extra) {
+        return base;
+    }
+    const merged = { ...base };
+    for (const [key, style] of Object.entries(extra)) {
+        if (!style || typeof style !== 'object') {
+            throw new ThemeError(`Theme key '${key}' must be an object`, {
+                context: { key, received: typeof style },
+            });
+        }
+        if (typeof style.stroke !== 'string') {
+            throw new ThemeError(`Theme key '${key}' must have a 'stroke' color string`, {
+                context: { key },
+            });
+        }
+        merged[key] = { ...base[key], ...style };
+    }
+    return merged;
+}
+
+/**
+ * Validate one entry from the annotations array. Throws HeatmapPointError
+ * for shape problems and ThemeError when the style key is unknown.
+ *
+ * @param {unknown} ann
+ * @param {number} index
+ * @param {import('../types/index.d.ts').AnnotationTheme} theme
+ */
+function assertAnnotation(ann, index, theme) {
+    if (!ann || typeof ann !== 'object') {
+        throw new HeatmapPointError(`annotations[${index}] must be an object`, {
+            context: { index, received: typeof ann },
+        });
+    }
+    const a = /** @type {Record<string, unknown>} */ (ann);
+    const rect = /** @type {Record<string, unknown> | undefined} */ (a.rect);
+    if (
+        !rect ||
+        !Number.isFinite(rect.x) ||
+        !Number.isFinite(rect.y) ||
+        !Number.isFinite(rect.width) ||
+        !Number.isFinite(rect.height)
+    ) {
+        throw new HeatmapPointError(`annotations[${index}].rect must be a finite Rect`, {
+            context: { index, rect },
+        });
+    }
+    if (typeof a.style !== 'string') {
+        throw new HeatmapPointError(`annotations[${index}].style must be a theme key string`, {
+            context: { index, style: a.style },
+        });
+    }
+    if (!theme[a.style]) {
+        throw new ThemeError(
+            `annotations[${index}].style '${a.style}' has no matching theme entry`,
+            { context: { index, style: a.style, available: Object.keys(theme) } }
+        );
+    }
+}
+
+/**
+ * Build the SVG overlay covering the full image. The SVG is rendered into
+ * the same pixel space as the source so coordinates need no scaling.
+ *
+ * @param {{width: number, height: number}} meta
+ * @param {Array<import('../types/index.d.ts').Annotation>} annotations
+ * @param {import('../types/index.d.ts').AnnotationTheme} theme
+ * @param {string} legend
+ * @returns {string}
+ */
+function buildSvg(meta, annotations, theme, legend) {
+    const layers = annotations.map(ann => svgLayerForAnnotation(ann, theme[ann.style])).join('\n');
+    const legendSvg = legend === 'none' ? '' : svgLegend(meta, annotations, theme, legend);
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${meta.width}" height="${meta.height}" viewBox="0 0 ${meta.width} ${meta.height}">`,
+        '<g font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="14" font-weight="bold">',
+        layers,
+        legendSvg,
+        '</g>',
+        '</svg>',
+    ].join('\n');
+}
+
+function svgLayerForAnnotation(ann, style) {
+    const { x, y, width, height } = ann.rect;
+    const parts = [
+        `<rect x="${x}" y="${y}" width="${width}" height="${height}" stroke="${escapeAttr(style.stroke)}" stroke-width="${style.strokeWidth}" fill="${escapeAttr(style.fill ?? 'none')}"/>`,
+    ];
+    if (ann.label && style.badge) {
+        const badgeSize = 20;
+        const badgeX = x - badgeSize / 2;
+        const badgeY = y - badgeSize / 2;
+        parts.push(
+            `<rect x="${badgeX}" y="${badgeY}" width="${badgeSize}" height="${badgeSize}" rx="${badgeSize / 2}" fill="${escapeAttr(style.badge.bg)}"/>`,
+            `<text x="${badgeX + badgeSize / 2}" y="${badgeY + badgeSize / 2 + 4}" text-anchor="middle" fill="${escapeAttr(style.badge.fg)}">${escapeText(String(ann.label))}</text>`
+        );
+    }
+    return parts.join('');
+}
+
+/**
+ * Build a legend block listing each theme key that appears in the
+ * annotations.
+ *
+ * @param {{width: number, height: number}} meta
+ * @param {Array<import('../types/index.d.ts').Annotation>} annotations
+ * @param {import('../types/index.d.ts').AnnotationTheme} theme
+ * @param {string} position
+ * @returns {string}
+ */
+function svgLegend(meta, annotations, theme, position) {
+    const usedKeys = [...new Set(annotations.map(a => a.style))];
+    if (usedKeys.length === 0) {
+        return '';
+    }
+    const rowHeight = 22;
+    const padding = 10;
+    const swatchSize = 14;
+    const charWidth = 8;
+    const labelWidths = usedKeys.map(k => k.length * charWidth);
+    const width = padding * 2 + swatchSize + 6 + Math.max(...labelWidths);
+    const height = padding * 2 + usedKeys.length * rowHeight;
+    let x;
+    let y;
+    switch (position) {
+        case 'top-left':
+            x = padding;
+            y = padding;
+            break;
+        case 'top-right':
+            x = meta.width - width - padding;
+            y = padding;
+            break;
+        case 'bottom-left':
+            x = padding;
+            y = meta.height - height - padding;
+            break;
+        default:
+            // 'bottom-right' or anything unknown reaching this point.
+            x = meta.width - width - padding;
+            y = meta.height - height - padding;
+    }
+    const rows = usedKeys
+        .map((key, i) => {
+            const style = theme[key];
+            const rowY = y + padding + i * rowHeight;
+            return (
+                `<rect x="${x + padding}" y="${rowY}" width="${swatchSize}" height="${swatchSize}" ` +
+                `fill="${escapeAttr(style.fill ?? 'none')}" stroke="${escapeAttr(style.stroke)}" stroke-width="2"/>` +
+                `<text x="${x + padding + swatchSize + 6}" y="${rowY + swatchSize - 2}" fill="#222">${escapeText(key)}</text>`
+            );
+        })
+        .join('');
+    return (
+        `<g><rect x="${x}" y="${y}" width="${width}" height="${height}" fill="rgba(255,255,255,0.95)" stroke="#222" stroke-width="1"/>` +
+        rows +
+        '</g>'
+    );
+}
+
+function escapeAttr(s) {
+    return String(s).replaceAll('"', '&quot;').replaceAll('<', '&lt;');
+}
+
+function escapeText(s) {
+    return String(s).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+
+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 annotate input buffer', {
+            cause: error,
+        });
+    }
+}
+
+module.exports = { annotate, MAX_ANNOTATIONS };