@afixt/screenshot-utils 0.9.0

package/src/errors/compose.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { ScreenshotUtilsError } = require('./base.js');
+
+/**
+ * Base for errors arising during composition (annotate, heatmap, diff, composite).
+ *
+ * @public
+ */
+class ComposeError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'COMPOSE_ERROR';
+        this.retriable = false;
+    }
+}
+
+/**
+ * `diff()` was called with two images whose dimensions don't match.
+ *
+ * @public
+ */
+class DimensionMismatchError extends ComposeError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'DIMENSION_MISMATCH';
+        this.retriable = false;
+    }
+}
+
+/**
+ * An annotation theme is missing a required key or has invalid values.
+ *
+ * @public
+ */
+class ThemeError extends ComposeError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'THEME_ERROR';
+        this.retriable = false;
+    }
+}
+
+/**
+ * A heatmap point is malformed (e.g., missing x/y, negative weight, NaN).
+ *
+ * @public
+ */
+class HeatmapPointError extends ComposeError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'HEATMAP_POINT';
+        this.retriable = false;
+    }
+}
+
+module.exports = {
+    ComposeError,
+    DimensionMismatchError,
+    ThemeError,
+    HeatmapPointError,
+};

package/src/errors/index.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * Barrel for the public error hierarchy. Import from here, not from the
+ * individual files — the indirection keeps instanceof chains stable when
+ * the package is consumed via either CJS or ESM.
+ *
+ * @module screenshot-utils/errors
+ */
+
+const { ScreenshotUtilsError } = require('./base.js');
+const {
+    CaptureError,
+    BrowserUnavailableError,
+    PageTooTallError,
+    ElementNotFoundError,
+    ElementNotVisibleError,
+    ElementMismatchError,
+    ElementTooLargeError,
+    StabilityTimeoutError,
+    CaptureTimeoutError,
+} = require('./capture.js');
+const {
+    TransformError,
+    InvalidRectError,
+    UnsupportedFormatError,
+    BufferCorruptError,
+} = require('./transform.js');
+const {
+    ComposeError,
+    DimensionMismatchError,
+    ThemeError,
+    HeatmapPointError,
+} = require('./compose.js');
+const { TileError, TileSizeError, TileWriteError } = require('./tile.js');
+const { RedactionError, PolicyError } = require('./redaction.js');
+const { AdapterError, AdapterContractError, BrowserApiError } = require('./adapter.js');
+const { OptionalDependencyMissingError } = require('./optional.js');
+
+module.exports = {
+    ScreenshotUtilsError,
+    // capture
+    CaptureError,
+    BrowserUnavailableError,
+    PageTooTallError,
+    ElementNotFoundError,
+    ElementNotVisibleError,
+    ElementMismatchError,
+    ElementTooLargeError,
+    StabilityTimeoutError,
+    CaptureTimeoutError,
+    // transform
+    TransformError,
+    InvalidRectError,
+    UnsupportedFormatError,
+    BufferCorruptError,
+    // compose
+    ComposeError,
+    DimensionMismatchError,
+    ThemeError,
+    HeatmapPointError,
+    // tile
+    TileError,
+    TileSizeError,
+    TileWriteError,
+    // redaction
+    RedactionError,
+    PolicyError,
+    // adapter
+    AdapterError,
+    AdapterContractError,
+    BrowserApiError,
+    // optional peers
+    OptionalDependencyMissingError,
+};

package/src/errors/optional.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { ScreenshotUtilsError } = require('./base.js');
+
+/**
+ * An operation needs an optional peer dependency that isn't installed
+ * (e.g., calling `diff()` without `pixelmatch`). The error message MUST
+ * include the install command for the missing package.
+ *
+ * @public
+ */
+class OptionalDependencyMissingError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     * @param {string} [options.packageName] The npm package the caller must install.
+     * @param {string} [options.installCommand] Suggested install command (default: derived).
+     */
+    constructor(message, options = {}) {
+        const { packageName, installCommand, ...rest } = options;
+        super(message, rest);
+        this.code = 'OPTIONAL_DEPENDENCY_MISSING';
+        this.retriable = false;
+        if (packageName !== undefined) {
+            this.packageName = packageName;
+        }
+        if (installCommand !== undefined) {
+            this.installCommand = installCommand;
+        } else if (packageName !== undefined) {
+            this.installCommand = `npm install ${packageName}`;
+        }
+    }
+}
+
+module.exports = {
+    OptionalDependencyMissingError,
+};

package/src/errors/redaction.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { ScreenshotUtilsError } = require('./base.js');
+
+/**
+ * Base for errors arising during redaction (blur / mask / pixelate, PII policies).
+ *
+ * @public
+ */
+class RedactionError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'REDACTION_ERROR';
+        this.retriable = false;
+    }
+}
+
+/**
+ * A PII policy object is malformed or references unknown rule keys.
+ *
+ * @public
+ */
+class PolicyError extends RedactionError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'POLICY_ERROR';
+        this.retriable = false;
+    }
+}
+
+module.exports = {
+    RedactionError,
+    PolicyError,
+};

package/src/errors/tile.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { ScreenshotUtilsError } = require('./base.js');
+
+/**
+ * Base for errors arising during DZI tile generation.
+ *
+ * @public
+ */
+class TileError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'TILE_ERROR';
+        this.retriable = false;
+    }
+}
+
+/**
+ * `tileSize` is invalid (must be 256 or 512 per spec § 8.4.1).
+ *
+ * @public
+ */
+class TileSizeError extends TileError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'TILE_SIZE';
+        this.retriable = false;
+    }
+}
+
+/**
+ * Writing tiles to the output directory failed (only in `output: 'directory'` mode).
+ * Retriable because the underlying cause is usually transient (disk full, permissions race).
+ *
+ * @public
+ */
+class TileWriteError extends TileError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'TILE_WRITE';
+        this.retriable = true;
+    }
+}
+
+module.exports = {
+    TileError,
+    TileSizeError,
+    TileWriteError,
+};

package/src/errors/transform.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { ScreenshotUtilsError } = require('./base.js');
+
+/**
+ * Base for errors arising during image-buffer transforms (crop, resize, convert, normalize).
+ *
+ * @public
+ */
+class TransformError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'TRANSFORM_ERROR';
+        this.retriable = false;
+    }
+}
+
+/**
+ * A rect is malformed or lies outside the source image bounds.
+ *
+ * @public
+ */
+class InvalidRectError extends TransformError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'INVALID_RECT';
+        this.retriable = false;
+    }
+}
+
+/**
+ * The requested output format is not supported (e.g., AVIF in v1.0).
+ *
+ * @public
+ */
+class UnsupportedFormatError extends TransformError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'UNSUPPORTED_FORMAT';
+        this.retriable = false;
+    }
+}
+
+/**
+ * Sharp could not decode the input buffer (truncated, wrong format, corrupt).
+ *
+ * @public
+ */
+class BufferCorruptError extends TransformError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'BUFFER_CORRUPT';
+        this.retriable = false;
+    }
+}
+
+module.exports = {
+    TransformError,
+    InvalidRectError,
+    UnsupportedFormatError,
+    BufferCorruptError,
+};

package/src/index.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Public entrypoint for `@afixt/screenshot-utils`.
+ *
+ * This is the only semver-protected surface. Deep imports
+ * (e.g. `require('@afixt/screenshot-utils/src/...')`) are internal and
+ * may change without a major version bump.
+ *
+ * @module screenshot-utils
+ */
+
+const pkg = require('../package.json');
+const errors = require('./errors/index.js');
+const adapters = require('./adapters/index.js');
+const capture = require('./capture/index.js');
+const transform = require('./transform/index.js');
+const tile = require('./tile/index.js');
+const compose = require('./compose/index.js');
+
+/**
+ * Library defaults. Per-call options shallow-merge over this object.
+ * Frozen — never mutate at runtime.
+ *
+ * Mirrors `spec.md` § 11.1 exactly.
+ *
+ * @public
+ * @type {Readonly<import('./types/index.d.ts').ScreenshotUtilsDefaults>}
+ */
+const defaults = Object.freeze({
+    format: 'png',
+    quality: 90,
+    fullPage: true,
+    timeout: 30_000,
+    padding: 10,
+    stripHeight: null,
+    tileSize: 256,
+    tileOverlap: 1,
+    tileFormat: 'webp',
+    tileQuality: 80,
+    waitForStable: Object.freeze({
+        fonts: true,
+        images: true,
+        animations: 'reduce',
+        maxWait: 5000,
+        idleMs: 200,
+    }),
+});
+
+/**
+ * Resolved package version from package.json. Useful for diagnostic logging
+ * by consumers; never use for feature gating (consumers should pin the range
+ * they need via semver).
+ *
+ * @public
+ * @type {string}
+ */
+const version = pkg.version;
+
+module.exports = {
+    defaults,
+    version,
+    ...errors,
+    ...adapters,
+    ...capture,
+    ...transform,
+    ...tile,
+    ...compose,
+};

package/src/redact/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { redact } = require('./redact.js');
+const { applyPiiPolicy, defaultPiiPolicy } = require('./policy.js');
+
+module.exports = { redact, applyPiiPolicy, defaultPiiPolicy };

package/src/redact/policy.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const { PolicyError } = require('../errors/index.js');
+const { redact } = require('./redact.js');
+
+/**
+ * Default PII policy bundled with the package. Consumers tighten it per
+ * their privacy posture; this is the conservative starting point per
+ * `spec.md` § 8.5.2.
+ *
+ * @public
+ * @type {Readonly<import('../types/index.d.ts').PiiPolicy>}
+ */
+const defaultPiiPolicy = Object.freeze({
+    inputTypes: Object.freeze(['email', 'password', 'tel', 'ssn-pattern']),
+    customSelectors: Object.freeze(['[data-pii="true"]', '[data-sensitive]']),
+    mode: 'blur',
+    radius: 12,
+});
+
+/**
+ * Apply a PII policy to a screenshot using a pre-collected list of element
+ * rects + classification metadata.
+ *
+ * Implements `spec.md` § 8.5.2. The function does NOT inspect a DOM
+ * directly — callers run a page-context evaluator that produces the
+ * `regions` array (an array of `{ rect, classification? }` objects) and
+ * pass it here. This keeps the package DOM-agnostic.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<{rect: import('../types/index.d.ts').Rect, classification?: string}>} regions
+ * @param {import('../types/index.d.ts').PiiPolicy} [policy]
+ * @returns {Promise<Buffer>}
+ */
+async function applyPiiPolicy(input, regions, policy = defaultPiiPolicy) {
+    if (!policy || typeof policy !== 'object') {
+        throw new PolicyError('policy must be an object', {
+            context: { received: typeof policy },
+        });
+    }
+    if (typeof policy.mode !== 'string') {
+        throw new PolicyError('policy.mode is required', { context: { policy } });
+    }
+    if (!Array.isArray(regions)) {
+        throw new PolicyError('regions must be an array', {
+            context: { received: typeof regions },
+        });
+    }
+
+    const redactRegions = regions.map(r => ({
+        rect: r.rect,
+        mode: policy.mode,
+        ...(policy.radius !== undefined && policy.mode === 'blur' ? { radius: policy.radius } : {}),
+        ...(policy.cellSize !== undefined && policy.mode === 'pixelate'
+            ? { cellSize: policy.cellSize }
+            : {}),
+        ...(policy.color !== undefined && policy.mode === 'mask' ? { color: policy.color } : {}),
+    }));
+
+    return redact(input, redactRegions, {
+        default: policy.mode,
+        defaultRadius: policy.radius ?? 8,
+    });
+}
+
+module.exports = { applyPiiPolicy, defaultPiiPolicy };