@afixt/screenshot-utils 0.9.0

package/src/compose/diff.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const {
+    BufferCorruptError,
+    DimensionMismatchError,
+    OptionalDependencyMissingError,
+} = require('../errors/index.js');
+
+/**
+ * Perceptual visual diff between two image buffers.
+ *
+ * Implements `spec.md` § 8.3.4. Requires the optional peer
+ * `pixelmatch` (≥ v7); throws `OptionalDependencyMissingError` if it
+ * isn't installed.
+ *
+ * @public
+ * @param {Buffer} bufferA
+ * @param {Buffer} bufferB
+ * @param {import('../types/index.d.ts').DiffOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').DiffResult>}
+ */
+async function diff(bufferA, bufferB, options = {}) {
+    assertBuffer(bufferA, 'bufferA');
+    assertBuffer(bufferB, 'bufferB');
+    const {
+        threshold = 0.1,
+        includeAA = false,
+        alpha = 0.5,
+        diffColor = [255, 0, 0],
+        output = 'overlay',
+    } = options;
+    if (!['overlay', 'side-by-side', 'mask-only'].includes(output)) {
+        throw new DimensionMismatchError(
+            `diff output must be 'overlay', 'side-by-side', or 'mask-only'; received ${output}`,
+            { context: { output } }
+        );
+    }
+
+    const pixelmatch = await loadPixelmatch();
+    const sharp = require('sharp');
+
+    const a = await rawRgba(sharp, bufferA);
+    const b = await rawRgba(sharp, bufferB);
+    if (a.width !== b.width || a.height !== b.height) {
+        throw new DimensionMismatchError(
+            `diff requires equal dimensions: bufferA is ${a.width}x${a.height}, bufferB is ${b.width}x${b.height}`,
+            {
+                context: {
+                    a: { width: a.width, height: a.height },
+                    b: { width: b.width, height: b.height },
+                },
+            }
+        );
+    }
+    const totalPixels = a.width * a.height;
+
+    const diffData = Buffer.alloc(a.data.length);
+    const changedPixels = pixelmatch(a.data, b.data, diffData, a.width, a.height, {
+        threshold,
+        includeAA,
+        alpha,
+        diffColor,
+    });
+
+    const diffBuffer = await renderOutput(sharp, output, {
+        a,
+        b,
+        diffData,
+        width: a.width,
+        height: a.height,
+    });
+
+    return {
+        diffBuffer,
+        changedPixels,
+        totalPixels,
+        percentChanged: totalPixels === 0 ? 0 : (changedPixels / totalPixels) * 100,
+    };
+}
+
+/**
+ * Dynamic-import pixelmatch so the package can be installed without it.
+ *
+ * @returns {Promise<Function>}
+ */
+async function loadPixelmatch() {
+    try {
+        // pixelmatch v7 is ESM-only. dynamic import returns the module
+        // namespace; default export is the function.
+        const mod = await import('pixelmatch');
+        return mod.default ?? mod;
+    } catch (error) {
+        throw new OptionalDependencyMissingError(
+            'diff() requires the optional peer dependency `pixelmatch`. Install it before calling diff().',
+            { packageName: 'pixelmatch', cause: error }
+        );
+    }
+}
+
+/**
+ * Decode a buffer to raw RGBA pixel data via sharp.
+ *
+ * @param {ReturnType<typeof require>} sharp
+ * @param {Buffer} buffer
+ * @returns {Promise<{data: Buffer, width: number, height: number}>}
+ */
+async function rawRgba(sharp, buffer) {
+    try {
+        const { data, info } = await sharp(buffer)
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        return { data, width: info.width, height: info.height };
+    } catch (error) {
+        throw new BufferCorruptError('sharp could not decode diff input buffer', {
+            cause: error,
+        });
+    }
+}
+
+/**
+ * Render the requested diff output mode.
+ *
+ * @param {ReturnType<typeof require>} sharp
+ * @param {string} mode 'overlay' | 'side-by-side' | 'mask-only'
+ * @param {{a: {data: Buffer, width: number, height: number}, b: {data: Buffer, width: number, height: number}, diffData: Buffer, width: number, height: number}} ctx
+ * @returns {Promise<Buffer>}
+ */
+async function renderOutput(sharp, mode, ctx) {
+    const diffPng = await sharp(ctx.diffData, {
+        raw: { width: ctx.width, height: ctx.height, channels: 4 },
+    })
+        .png()
+        .toBuffer();
+
+    if (mode === 'mask-only') {
+        return diffPng;
+    }
+    if (mode === 'side-by-side') {
+        const bImage = await sharp(ctx.b.data, {
+            raw: { width: ctx.b.width, height: ctx.b.height, channels: 4 },
+        })
+            .png()
+            .toBuffer();
+        return sharp({
+            create: {
+                width: ctx.width * 2,
+                height: ctx.height,
+                channels: 4,
+                background: { r: 0, g: 0, b: 0, alpha: 0 },
+            },
+        })
+            .composite([
+                { input: bImage, top: 0, left: 0 },
+                { input: diffPng, top: 0, left: ctx.width },
+            ])
+            .png()
+            .toBuffer();
+    }
+    // 'overlay' — the diff image already encodes the overlay because
+    // pixelmatch writes the b image with changed pixels highlighted.
+    return diffPng;
+}
+
+function assertBuffer(buffer, name) {
+    if (!Buffer.isBuffer(buffer)) {
+        throw new BufferCorruptError(`${name} must be a Buffer`, {
+            context: { received: typeof buffer, name },
+        });
+    }
+}
+
+module.exports = { diff };

package/src/compose/heatmap.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const { BufferCorruptError, ComposeError, HeatmapPointError } = require('../errors/index.js');
+
+const MAX_POINTS = 100_000;
+const VALID_BLEND_MODES = new Set(['overlay', 'screen', 'multiply']);
+
+/**
+ * Render a kernel-density heatmap over a screenshot.
+ *
+ * Implements `spec.md` § 8.3.3 with a simple SVG-circles + blur approach.
+ * Each point gets a circle whose radius scales with weight; the
+ * collection is then blurred to produce a smooth heatmap surface and
+ * composited onto the source using the requested blend mode.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<import('../types/index.d.ts').HeatmapPoint>} points
+ * @param {import('../types/index.d.ts').HeatmapOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+async function heatmap(input, points, options = {}) {
+    assertBuffer(input);
+    if (!Array.isArray(points)) {
+        throw new HeatmapPointError('points must be an array', {
+            context: { received: typeof points },
+        });
+    }
+    if (points.length > MAX_POINTS) {
+        throw new ComposeError(
+            `Cannot render a heatmap with more than ${MAX_POINTS} points in a single call`,
+            { context: { received: points.length, max: MAX_POINTS } }
+        );
+    }
+    const { radius = 40, intensity = 0.7, colorScale = 'viridis', blendMode = 'overlay' } = options;
+    if (!VALID_BLEND_MODES.has(blendMode)) {
+        throw new ComposeError(
+            `blendMode must be one of ${[...VALID_BLEND_MODES].join(', ')}; received ${blendMode}`,
+            { context: { received: blendMode } }
+        );
+    }
+    if (!Number.isFinite(radius) || radius <= 0) {
+        throw new HeatmapPointError('radius must be a positive number', {
+            context: { received: radius },
+        });
+    }
+
+    for (const [i, point] of points.entries()) {
+        if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+            throw new HeatmapPointError(`points[${i}] must have finite x and y`, {
+                context: { index: i, point },
+            });
+        }
+        if (point.weight !== undefined && !Number.isFinite(point.weight)) {
+            throw new HeatmapPointError(`points[${i}].weight must be a finite number`, {
+                context: { index: i, weight: point.weight },
+            });
+        }
+    }
+
+    const sharp = require('sharp');
+    const meta = await readMeta(sharp, input);
+
+    if (points.length === 0) {
+        return input;
+    }
+
+    const color = resolveColor(colorScale);
+    const svg = buildSvg(points, radius, intensity, color, meta);
+    const blurred = await sharp(Buffer.from(svg, 'utf8'))
+        .resize(meta.width, meta.height, { fit: 'fill' })
+        .blur(Math.min(50, radius / 2))
+        .toBuffer();
+
+    return sharp(input)
+        .composite([{ input: blurred, blend: blendMode }])
+        .toBuffer();
+}
+
+/**
+ * Build the SVG layer with one circle per point.
+ *
+ * @param {Array<import('../types/index.d.ts').HeatmapPoint>} points
+ * @param {number} radius
+ * @param {number} intensity
+ * @param {string} color CSS color for the dot fill.
+ * @param {{width: number, height: number}} meta
+ * @returns {string}
+ */
+function buildSvg(points, radius, intensity, color, meta) {
+    const opacity = Math.max(0, Math.min(1, intensity));
+    const circles = points
+        .map(p => {
+            const w = Math.max(0.1, Number(p.weight ?? 1));
+            const r = radius * Math.sqrt(w);
+            return `<circle cx="${p.x}" cy="${p.y}" r="${r}" fill="${color}" fill-opacity="${opacity}"/>`;
+        })
+        .join('');
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${meta.width}" height="${meta.height}"><g>${circles}</g></svg>`;
+}
+
+/**
+ * Resolve the colorScale option into a single CSS color used for every
+ * point. Full multi-stop color scales are deferred to v1.1; for v1.0
+ * we pick a representative warm color per built-in scale.
+ *
+ * @param {string | Function} colorScale
+ * @returns {string}
+ */
+function resolveColor(colorScale) {
+    if (typeof colorScale === 'function') {
+        // Sample at the high-intensity end (t=1).
+        try {
+            const result = colorScale(1);
+            if (Array.isArray(result) && result.length >= 3) {
+                return `rgb(${result[0]}, ${result[1]}, ${result[2]})`;
+            }
+        } catch {
+            // fall through to default
+        }
+        return '#FF0000';
+    }
+    switch (colorScale) {
+        case 'magma':
+            return '#FB8861';
+        case 'severity':
+            return '#D32F2F';
+        default:
+            // 'viridis' (default) or any unknown scale.
+            return '#FDE725';
+    }
+}
+
+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 heatmap input buffer', {
+            cause: error,
+        });
+    }
+}
+
+module.exports = { heatmap, MAX_POINTS };

package/src/compose/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { annotate } = require('./annotate.js');
+const { defaultTheme } = require('./theme.js');
+const { diff } = require('./diff.js');
+const { heatmap } = require('./heatmap.js');
+
+module.exports = { annotate, defaultTheme, diff, heatmap };

package/src/compose/theme.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Default annotation theme shipped with the package.
+ *
+ * Implements `spec.md` § 8.3.2. The four severity keys cover the standard
+ * accessibility-issue grading. Consumers can replace any subset by passing
+ * their own theme object to `annotate()`; the function shallow-merges over
+ * this default.
+ *
+ * Color choices target WCAG 2.2 AA when rendered against typical light or
+ * dark page backgrounds. Stroke widths are in CSS px and scale with the
+ * captured image's pixel space.
+ *
+ * @public
+ * @type {Readonly<import('../types/index.d.ts').AnnotationTheme>}
+ */
+const defaultTheme = Object.freeze({
+    'severity-critical': Object.freeze({
+        stroke: '#D32F2F',
+        strokeWidth: 3,
+        fill: '#D32F2F22',
+        badge: Object.freeze({ bg: '#D32F2F', fg: '#fff' }),
+    }),
+    'severity-serious': Object.freeze({
+        stroke: '#F57C00',
+        strokeWidth: 3,
+        fill: '#F57C0022',
+        badge: Object.freeze({ bg: '#F57C00', fg: '#fff' }),
+    }),
+    'severity-moderate': Object.freeze({
+        stroke: '#FBC02D',
+        strokeWidth: 2,
+        fill: '#FBC02D22',
+        badge: Object.freeze({ bg: '#FBC02D', fg: '#000' }),
+    }),
+    'severity-minor': Object.freeze({
+        stroke: '#1976D2',
+        strokeWidth: 2,
+        fill: '#1976D222',
+        badge: Object.freeze({ bg: '#1976D2', fg: '#fff' }),
+    }),
+});
+
+module.exports = { defaultTheme };

package/src/errors/adapter.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const { ScreenshotUtilsError } = require('./base.js');
+
+/**
+ * Base for errors arising at the `PageAdapter` boundary
+ * (third-party browser object integration).
+ *
+ * @public
+ */
+class AdapterError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'ADAPTER_ERROR';
+        this.retriable = false;
+    }
+}
+
+/**
+ * The wrapped third-party page object is missing a method required by the
+ * `PageAdapter` contract (spec § 10). Deterministic — the caller passed the
+ * wrong kind of object.
+ *
+ * @public
+ */
+class AdapterContractError extends AdapterError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'ADAPTER_CONTRACT';
+        this.retriable = false;
+    }
+}
+
+/**
+ * The underlying puppeteer / playwright / CDP call threw. Wrapped so consumers
+ * can rely on the package's error shape without sniffing browser-library
+ * internals. Retriable because most browser-API errors are transient.
+ *
+ * @public
+ */
+class BrowserApiError extends AdapterError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'BROWSER_API';
+        this.retriable = true;
+    }
+}
+
+module.exports = {
+    AdapterError,
+    AdapterContractError,
+    BrowserApiError,
+};

package/src/errors/base.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Abstract base class for all errors thrown by `@afixt/screenshot-utils`.
+ *
+ * Concrete subclasses must:
+ * - set a stable `code` string (machine-readable; never localized)
+ * - set `retriable: true` only when a consumer-side retry has a chance of succeeding
+ *   without operator intervention (transient browser timeouts, transport blips, etc.)
+ * - never include PII in `context`. The platform privacy rules in
+ *   the parent CLAUDE.md forbid logging user data; the same applies to
+ *   error payloads since they are commonly logged verbatim.
+ *
+ * See `spec.md` § 14 for the full error model.
+ *
+ * @public
+ */
+class ScreenshotUtilsError extends Error {
+    /**
+     * Construct an error. Subclasses set `code` and `retriable`; callers may
+     * supply `reason`, `cause`, and `context`.
+     *
+     * @param {string} message Human-readable summary. Should not include PII.
+     * @param {object} [options]
+     * @param {string} [options.reason] Sub-classification (enum string) — see spec § 14.3.
+     * @param {Error}  [options.cause]  Underlying error being wrapped, preserved for stack traces.
+     * @param {Record<string, unknown>} [options.context] Structured debug data. NO PII.
+     */
+    constructor(message, { reason, cause, context } = {}) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = new.target.name;
+        // Subclasses overwrite `code` and `retriable` after super().
+        // Defaults here keep base instances valid for testing the shape.
+        this.code = 'SCREENSHOT_UTILS_ERROR';
+        this.retriable = false;
+        if (reason !== undefined) {
+            this.reason = reason;
+        }
+        if (context !== undefined) {
+            this.context = context;
+        }
+        // Note: modern V8 automatically excludes the Error constructor
+        // from the stack trace when subclassing, so an explicit
+        // Error.captureStackTrace(this, new.target) is unnecessary.
+    }
+}
+
+module.exports = { ScreenshotUtilsError };

package/src/errors/capture.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const { ScreenshotUtilsError } = require('./base.js');
+
+/**
+ * Base for any error arising during the capture phase
+ * (browser interaction, scroll, settle, screenshot).
+ *
+ * @public
+ */
+class CaptureError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     * @param {string} [options.reason]
+     * @param {Error}  [options.cause]
+     * @param {Record<string, unknown>} [options.context]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'CAPTURE_ERROR';
+        this.retriable = false;
+    }
+}
+
+/**
+ * The browser context is unreachable (process crashed, pool exhausted, etc.).
+ * Retriable because the consumer may obtain a fresh browser context.
+ *
+ * @public
+ */
+class BrowserUnavailableError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'BROWSER_UNAVAILABLE';
+        this.retriable = true;
+    }
+}
+
+/**
+ * Document scrollHeight exceeds the configured `maxHeight` ceiling.
+ *
+ * @public
+ */
+class PageTooTallError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'PAGE_TOO_TALL';
+        this.retriable = false;
+    }
+}
+
+/**
+ * The requested selector / xpath returned no DOM node.
+ *
+ * @public
+ */
+class ElementNotFoundError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'ELEMENT_NOT_FOUND';
+        this.retriable = false;
+    }
+}
+
+/**
+ * The element exists but has zero size or is hidden from layout.
+ *
+ * @public
+ */
+class ElementNotVisibleError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'ELEMENT_NOT_VISIBLE';
+        this.retriable = false;
+    }
+}
+
+/**
+ * A verification snippet was provided but the live DOM did not match.
+ *
+ * @public
+ */
+class ElementMismatchError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'ELEMENT_MISMATCH';
+        this.retriable = false;
+    }
+}
+
+/**
+ * Element dimensions exceed `maxDimensions` (default 4000×4000 CSS px).
+ *
+ * @public
+ */
+class ElementTooLargeError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'ELEMENT_TOO_LARGE';
+        this.retriable = false;
+    }
+}
+
+/**
+ * `waitForStable` exceeded its `maxWait`. The page was still settling.
+ * Retriable because subsequent calls may catch a stable frame.
+ *
+ * @public
+ */
+class StabilityTimeoutError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'STABILITY_TIMEOUT';
+        this.retriable = true;
+    }
+}
+
+/**
+ * The underlying browser screenshot call exceeded the configured `timeout`.
+ * Retriable for the same reasons as StabilityTimeoutError.
+ *
+ * @public
+ */
+class CaptureTimeoutError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'CAPTURE_TIMEOUT';
+        this.retriable = true;
+    }
+}
+
+module.exports = {
+    CaptureError,
+    BrowserUnavailableError,
+    PageTooTallError,
+    ElementNotFoundError,
+    ElementNotVisibleError,
+    ElementMismatchError,
+    ElementTooLargeError,
+    StabilityTimeoutError,
+    CaptureTimeoutError,
+};