@afixt/screenshot-utils 0.9.0

package/package.json

@@ -0,0 +1,164 @@
+{
+    "name": "@afixt/screenshot-utils",
+    "version": "0.9.0",
+    "description": "Screenshot capture, transform, compose, tile, and redact utilities for the AFixt/Revenant accessibility platform",
+    "type": "commonjs",
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/types/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "bin",
+        "src",
+        "dist",
+        "CHANGELOG.md",
+        "README.md"
+    ],
+    "bin": {
+        "afixt-screenshot": "./bin/afixt-screenshot"
+    },
+    "scripts": {
+        "build": "npm-run-all -p build:bundle build:types",
+        "build:bundle": "tsup",
+        "build:types": "tsc -p tsconfig.json",
+        "build:clean": "rm -rf dist",
+        "prebuild": "npm run build:clean",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
+        "test:single": "vitest run --testNamePattern",
+        "test:perf": "vitest run --config vitest.perf.config.js",
+        "lint": "eslint . --max-warnings 0",
+        "lint:fix": "eslint . --fix --max-warnings 0",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "lint:md": "markdownlint '**/*.md' --ignore node_modules --ignore scratchpads --ignore dist --ignore docs --ignore CHANGELOG.md --ignore spec.md",
+        "lint:cpd": "jscpd . --config .jscpd.json",
+        "lint:cpd:ci": "jscpd . --config .jscpd.json --threshold 5",
+        "security:audit": "npm audit",
+        "security:check": "npm audit --audit-level=high",
+        "security:check:prod": "npm audit --omit=dev --audit-level=high",
+        "security:osv": "osv-scanner --config=.osv-scanner.toml --lockfile=package-lock.json",
+        "security:semgrep": "semgrep --config=p/javascript --config=p/nodejsscan --config=p/owasp-top-ten --config=p/secrets --error --metrics=off",
+        "security:secrets": "trufflehog git file://. --only-verified --fail --no-update",
+        "security:secrets:staged": "trufflehog git file://. --since-commit HEAD --only-verified --fail --no-update",
+        "license:check": "license-checker-rseidelsohn --production --onlyAllow 'MIT;ISC;Apache-2.0;BSD-2-Clause;BSD-3-Clause;0BSD;CC0-1.0;Unlicense;Python-2.0;WTFPL;BlueOak-1.0.0;LGPL-3.0-or-later;LGPL-3.0' --excludePackagesStartingWith '@afixt/' --summary",
+        "license:report": "license-checker-rseidelsohn --production --csv --out reports/licenses.csv --excludePackagesStartingWith '@afixt/'",
+        "links": "lychee --no-progress --exclude 'github\\.com/AFixt/' '**/*.md' --exclude-path 'node_modules/**' --exclude-path 'dist/**' --exclude-path 'docs/**' --exclude-path 'scratchpads/**'",
+        "docs": "jsdoc -c jsdoc.json",
+        "docs:serve": "npx http-server ./docs",
+        "check": "npm-run-all -p lint format:check lint:md lint:cpd:ci",
+        "check:all": "npm-run-all -s check test security:check:prod license:check",
+        "release": "standard-version",
+        "prepare": "husky"
+    },
+    "lint-staged": {
+        "*.{js,mjs,cjs}": [
+            "eslint --fix",
+            "prettier --write"
+        ],
+        "*.{json,md,yml,yaml}": [
+            "prettier --write"
+        ]
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+ssh://git@github.com/AFixt/screenshot-utils.git"
+    },
+    "bugs": {
+        "url": "https://github.com/AFixt/screenshot-utils/issues"
+    },
+    "homepage": "https://github.com/AFixt/screenshot-utils",
+    "author": "Karl Groves <karl.groves@afixt.com>",
+    "license": "UNLICENSED",
+    "publishConfig": {
+        "access": "restricted"
+    },
+    "engines": {
+        "node": ">=22.22.1"
+    },
+    "keywords": [
+        "screenshot",
+        "accessibility",
+        "puppeteer",
+        "playwright",
+        "sharp",
+        "dzi",
+        "tile",
+        "diff",
+        "annotate",
+        "redact",
+        "a11y",
+        "afixt",
+        "revenant"
+    ],
+    "dependencies": {
+        "sharp": "0.34.5"
+    },
+    "peerDependencies": {
+        "@napi-rs/canvas": "^0.1.0",
+        "pixelmatch": "^7.1.0",
+        "playwright": ">=1.40.0",
+        "pngjs": "^7.0.0",
+        "puppeteer": ">=23.0.0"
+    },
+    "peerDependenciesMeta": {
+        "@napi-rs/canvas": {
+            "optional": true
+        },
+        "pixelmatch": {
+            "optional": true
+        },
+        "playwright": {
+            "optional": true
+        },
+        "pngjs": {
+            "optional": true
+        },
+        "puppeteer": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@commitlint/cli": "20.5.3",
+        "@commitlint/config-conventional": "20.5.3",
+        "@eslint/js": "10.0.1",
+        "@types/node": "22.19.19",
+        "@vitest/coverage-v8": "4.1.5",
+        "clean-jsdoc-theme": "4.3.2",
+        "eslint": "10.3.0",
+        "eslint-plugin-import-x": "4.16.2",
+        "eslint-plugin-jsdoc": "62.9.0",
+        "eslint-plugin-n": "18.0.1",
+        "eslint-plugin-no-secrets": "2.3.3",
+        "eslint-plugin-promise": "7.3.0",
+        "eslint-plugin-security": "4.0.0",
+        "eslint-plugin-sonarjs": "4.0.3",
+        "eslint-plugin-unicorn": "64.0.0",
+        "globals": "17.6.0",
+        "husky": "9.1.7",
+        "jscpd": "4.0.9",
+        "jsdoc": "4.0.4",
+        "license-checker-rseidelsohn": "4.4.2",
+        "lint-staged": "17.0.2",
+        "markdownlint-cli": "0.48.0",
+        "npm-run-all2": "8.0.4",
+        "pixelmatch": "7.1.0",
+        "playwright": "1.60.0",
+        "pngjs": "7.0.0",
+        "prettier": "3.8.3",
+        "puppeteer": "25.0.2",
+        "standard-version": "9.5.0",
+        "tsup": "8.5.1",
+        "typescript": "6.0.3",
+        "vitest": "4.1.5"
+    }
+}

package/src/adapters/cdp.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const { AdapterContractError, BrowserApiError } = require('../errors/index.js');
+const { fromPuppeteerPage } = require('./puppeteer.js');
+
+/**
+ * Wrap a CDP (Chrome DevTools Protocol) session + Puppeteer page in the
+ * package's `PageAdapter` interface.
+ *
+ * Use this adapter when the consumer already holds a CDP session (e.g.
+ * the engine's CDP-attached runtime path described in spec § 10). The
+ * adapter routes `screenshot()` through CDP's `Page.captureScreenshot`
+ * — which avoids the page.screenshot() round-trip overhead — while
+ * delegating every other method to the supplied Puppeteer page.
+ *
+ * The Puppeteer page is required because CDP does not expose
+ * `Page.setViewport`, document scrollWidth/Height, or page reloads in a
+ * single coherent API; falling back to the Puppeteer page for those
+ * keeps the contract identical to `fromPuppeteerPage`.
+ *
+ * @public
+ * @param {object} session A CDP session (e.g. from `page.target().createCDPSession()`).
+ * @param {object} page The same Puppeteer Page the session is attached to.
+ * @param {object} [options]
+ * @param {string} [options.label]
+ * @param {number} [options.screenshotMaxHeight] Override Chromium's 16384 limit.
+ * @returns {import('../types/index.d.ts').PageAdapter}
+ */
+function fromCDPSession(session, page, options = {}) {
+    assertSession(session);
+    // assertPuppeteerPage validation runs inside fromPuppeteerPage.
+    const base = fromPuppeteerPage(page, options);
+    const label = options.label;
+    const screenshotMaxHeight = Number.isFinite(options.screenshotMaxHeight)
+        ? options.screenshotMaxHeight
+        : 16_384;
+
+    return {
+        async screenshot(opts) {
+            const cdpOpts = translateScreenshotOpts(opts);
+            try {
+                const response = await session.send('Page.captureScreenshot', cdpOpts);
+                return Buffer.from(response.data, 'base64');
+            } catch (error) {
+                throw new BrowserApiError('CDP Page.captureScreenshot failed', {
+                    cause: error,
+                    context: { operation: 'CDP.Page.captureScreenshot', label },
+                });
+            }
+        },
+        // Delegate every non-screenshot method to the wrapped Puppeteer adapter.
+        evaluate: base.evaluate.bind(base),
+        scrollTo: base.scrollTo.bind(base),
+        getMetrics: base.getMetrics.bind(base),
+        setViewport: base.setViewport.bind(base),
+        reload: base.reload.bind(base),
+        get capabilities() {
+            return {
+                screenshotMaxHeight,
+                supportsViewportEmulation: true,
+                supportsCDP: true,
+            };
+        },
+        get label() {
+            return label;
+        },
+    };
+}
+
+/**
+ * Translate the adapter's ScreenshotOptions into CDP's
+ * `Page.captureScreenshot` parameter shape.
+ *
+ * @param {import('../types/index.d.ts').ScreenshotOptions} [opts]
+ * @returns {object}
+ */
+function translateScreenshotOpts(opts = {}) {
+    const out = {
+        format: opts.type === 'jpeg' ? 'jpeg' : 'png',
+    };
+    if (opts.type === 'jpeg' && Number.isFinite(opts.quality)) {
+        out.quality = opts.quality;
+    }
+    if (opts.clip) {
+        out.clip = {
+            x: opts.clip.x,
+            y: opts.clip.y,
+            width: opts.clip.width,
+            height: opts.clip.height,
+            scale: 1,
+        };
+    }
+    if (opts.fullPage) {
+        out.captureBeyondViewport = true;
+    }
+    if (opts.omitBackground) {
+        out.optimizeForSpeed = false;
+    }
+    return out;
+}
+
+/**
+ * Validate the CDP session looks the part.
+ *
+ * @param {object} session
+ */
+function assertSession(session) {
+    if (session === null || typeof session !== 'object' || typeof session.send !== 'function') {
+        throw new AdapterContractError(
+            'fromCDPSession(session, page) requires a CDP session with a .send() method',
+            { context: { received: typeof session } }
+        );
+    }
+}
+
+module.exports = { fromCDPSession };

package/src/adapters/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * Barrel for `PageAdapter` factories. See `spec.md` § 10 for the contract.
+ *
+ * Adapter implementations live in sibling files (puppeteer, playwright,
+ * cdp). The corresponding peer dependency must be installed by the caller;
+ * the adapter modules themselves do not `require()` the peer.
+ *
+ * @module screenshot-utils/adapters
+ */
+
+const { fromPuppeteerPage } = require('./puppeteer.js');
+const { fromPlaywrightPage } = require('./playwright.js');
+const { fromCDPSession } = require('./cdp.js');
+
+module.exports = { fromPuppeteerPage, fromPlaywrightPage, fromCDPSession };

package/src/adapters/playwright.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const { AdapterContractError, BrowserApiError } = require('../errors/index.js');
+
+/**
+ * Wrap a Playwright `Page` object in the package's `PageAdapter` interface.
+ *
+ * Like `fromPuppeteerPage`, this adapter never imports `playwright` itself —
+ * the caller passes the `page` they already created. `playwright` remains
+ * an optional peer at the package level (spec § 10).
+ *
+ * Differences from Puppeteer's API (handled here so consumers don't have to):
+ * - Playwright uses `page.setViewportSize({ width, height })` instead of
+ *   `page.setViewport(...)`. The deviceScaleFactor on the Viewport type is
+ *   not settable post-hoc in Playwright — pass it at browser context
+ *   creation time.
+ * - Playwright's `page.screenshot()` accepts `type: 'png' | 'jpeg'` (no
+ *   webp). The adapter passes the type through; webp re-encode happens
+ *   one level up in capture functions.
+ *
+ * @public
+ * @param {object} page A Playwright Page instance (or compatible shim).
+ * @param {object} [options]
+ * @param {string} [options.label] Identifier for log lines.
+ * @param {number} [options.screenshotMaxHeight] Override Chromium's 16384 limit.
+ * @returns {import('../types/index.d.ts').PageAdapter}
+ */
+function fromPlaywrightPage(page, options = {}) {
+    assertPlaywrightPage(page);
+
+    const label = options.label;
+    const screenshotMaxHeight = Number.isFinite(options.screenshotMaxHeight)
+        ? options.screenshotMaxHeight
+        : 16_384;
+
+    return {
+        async screenshot(opts) {
+            return wrapBrowserCall('page.screenshot', () => page.screenshot(opts), label);
+        },
+        async evaluate(fn, ...args) {
+            return wrapBrowserCall(
+                'page.evaluate',
+                // Playwright expects evaluate(fn, arg) — single arg position.
+                // Forward exactly what the caller passed.
+                () => (args.length === 0 ? page.evaluate(fn) : page.evaluate(fn, ...args)),
+                label
+            );
+        },
+        async scrollTo(point) {
+            await wrapBrowserCall(
+                'page.evaluate(scrollTo)',
+                () => page.evaluate(({ x, y }) => globalThis.scrollTo(x, y), point),
+                label
+            );
+        },
+        async getMetrics() {
+            const metrics = await wrapBrowserCall(
+                'page.evaluate(getMetrics)',
+                () =>
+                    page.evaluate(() => {
+                        const doc = globalThis.document;
+                        return {
+                            width: doc.documentElement.scrollWidth,
+                            height: doc.documentElement.scrollHeight,
+                            viewport: {
+                                width: globalThis.innerWidth,
+                                height: globalThis.innerHeight,
+                            },
+                            devicePixelRatio: globalThis.devicePixelRatio,
+                            url: globalThis.location.href,
+                        };
+                    }),
+                label
+            );
+            return { ...metrics, capturedAt: new Date().toISOString() };
+        },
+        async setViewport(viewport) {
+            await wrapBrowserCall(
+                'page.setViewportSize',
+                () =>
+                    page.setViewportSize({
+                        width: viewport.width,
+                        height: viewport.height,
+                    }),
+                label
+            );
+            // deviceScaleFactor is intentionally NOT applied: Playwright
+            // sets it at context creation time. Adapter contract is
+            // "best-effort"; consumers that need DPR control should
+            // recreate the page in a new context.
+        },
+        async reload(opts) {
+            await wrapBrowserCall('page.reload', () => page.reload(opts), label);
+        },
+        get capabilities() {
+            return {
+                screenshotMaxHeight,
+                supportsViewportEmulation: true,
+                supportsCDP: false, // Playwright's CDP requires explicit session setup
+            };
+        },
+        get label() {
+            return label;
+        },
+    };
+}
+
+/**
+ * Validate the supplied object exposes the methods we use.
+ *
+ * @param {object} page
+ */
+function assertPlaywrightPage(page) {
+    if (page === null || typeof page !== 'object') {
+        throw new AdapterContractError(
+            'fromPlaywrightPage(page) requires a Playwright Page object',
+            { context: { received: typeof page } }
+        );
+    }
+    const required = ['screenshot', 'evaluate', 'setViewportSize', 'reload'];
+    const missing = required.filter(name => typeof page[name] !== 'function');
+    if (missing.length > 0) {
+        throw new AdapterContractError(
+            `The provided page object is missing required Playwright methods: ${missing.join(', ')}`,
+            { context: { missing } }
+        );
+    }
+}
+
+/**
+ * Race a browser call and translate any throw into BrowserApiError.
+ *
+ * @template T
+ * @param {string} operation
+ * @param {() => Promise<T>} fn
+ * @param {string|undefined} label
+ * @returns {Promise<T>}
+ */
+async function wrapBrowserCall(operation, fn, label) {
+    try {
+        return await fn();
+    } catch (error) {
+        throw new BrowserApiError(`Playwright call failed: ${operation}`, {
+            cause: error,
+            context: { operation, label },
+        });
+    }
+}
+
+module.exports = { fromPlaywrightPage };

package/src/adapters/puppeteer.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const { AdapterContractError, BrowserApiError } = require('../errors/index.js');
+
+/**
+ * Wrap a Puppeteer `Page` object in the package's `PageAdapter` interface.
+ *
+ * The adapter never imports `puppeteer` itself — the caller passes in the
+ * `page` they already created. This keeps `puppeteer` an optional peer
+ * dependency at the package level (per `spec.md` § 10) and means the same
+ * adapter works against any Puppeteer 23.x+ release without re-pinning.
+ *
+ * @public
+ * @param {object} page A Puppeteer Page instance (or compatible shim).
+ * @param {object} [options]
+ * @param {string} [options.label] Identifier for log lines (e.g. context id).
+ * @param {number} [options.screenshotMaxHeight] Override Chromium's 16384 limit.
+ * @returns {import('../types/index.d.ts').PageAdapter}
+ */
+function fromPuppeteerPage(page, options = {}) {
+    assertPuppeteerPage(page);
+
+    const label = options.label;
+    const screenshotMaxHeight = Number.isFinite(options.screenshotMaxHeight)
+        ? options.screenshotMaxHeight
+        : 16_384;
+
+    return {
+        async screenshot(opts) {
+            return wrapBrowserCall('page.screenshot', () => page.screenshot(opts), label);
+        },
+        async evaluate(fn, ...args) {
+            return wrapBrowserCall('page.evaluate', () => page.evaluate(fn, ...args), label);
+        },
+        async scrollTo(point) {
+            await wrapBrowserCall(
+                'page.evaluate(scrollTo)',
+                // Runs in the browser context; `globalThis` === window.
+                () => page.evaluate(({ x, y }) => globalThis.scrollTo(x, y), point),
+                label
+            );
+        },
+        async getMetrics() {
+            const metrics = await wrapBrowserCall(
+                'page.evaluate(getMetrics)',
+                () =>
+                    // Runs in the browser context; `globalThis` === window.
+                    page.evaluate(() => {
+                        const doc = globalThis.document;
+                        return {
+                            width: doc.documentElement.scrollWidth,
+                            height: doc.documentElement.scrollHeight,
+                            viewport: {
+                                width: globalThis.innerWidth,
+                                height: globalThis.innerHeight,
+                            },
+                            devicePixelRatio: globalThis.devicePixelRatio,
+                            url: globalThis.location.href,
+                        };
+                    }),
+                label
+            );
+            return { ...metrics, capturedAt: new Date().toISOString() };
+        },
+        async setViewport(viewport) {
+            await wrapBrowserCall('page.setViewport', () => page.setViewport(viewport), label);
+        },
+        async reload(opts) {
+            await wrapBrowserCall('page.reload', () => page.reload(opts), label);
+        },
+        get capabilities() {
+            return {
+                screenshotMaxHeight,
+                supportsViewportEmulation: true,
+                supportsCDP: true,
+            };
+        },
+        get label() {
+            return label;
+        },
+    };
+}
+
+/**
+ * Validates that the supplied object has the methods we require.
+ * Throws `AdapterContractError` (not a generic TypeError) so consumers can
+ * catch by error class without sniffing message strings.
+ *
+ * @param {object} page
+ */
+function assertPuppeteerPage(page) {
+    if (page === null || typeof page !== 'object') {
+        throw new AdapterContractError('fromPuppeteerPage(page) requires a Puppeteer Page object', {
+            context: { received: typeof page },
+        });
+    }
+    const required = ['screenshot', 'evaluate', 'setViewport', 'reload'];
+    const missing = required.filter(name => typeof page[name] !== 'function');
+    if (missing.length > 0) {
+        throw new AdapterContractError(
+            `The provided page object is missing required Puppeteer methods: ${missing.join(', ')}`,
+            { context: { missing } }
+        );
+    }
+}
+
+/**
+ * Catches errors thrown from the underlying browser library and re-wraps them
+ * as `BrowserApiError` so consumers can use a single `instanceof` check.
+ *
+ * @template T
+ * @param {string} operation Logical name (for context.operation).
+ * @param {() => Promise<T>} fn  Browser-bound call.
+ * @param {string|undefined} label Adapter label for context.
+ * @returns {Promise<T>}
+ */
+async function wrapBrowserCall(operation, fn, label) {
+    try {
+        return await fn();
+    } catch (error) {
+        throw new BrowserApiError(`Puppeteer call failed: ${operation}`, {
+            cause: error,
+            context: { operation, label },
+        });
+    }
+}
+
+module.exports = { fromPuppeteerPage };