@afixt/screenshot-utils 0.9.0

package/dist/index.mjs

@@ -0,0 +1,2795 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports, module) {
+    module.exports = {
+      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"
+      }
+    };
+  }
+});
+
+// src/errors/base.js
+var require_base = __commonJS({
+  "src/errors/base.js"(exports, module) {
+    var ScreenshotUtilsError = class 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 === void 0 ? void 0 : { cause });
+        this.name = new.target.name;
+        this.code = "SCREENSHOT_UTILS_ERROR";
+        this.retriable = false;
+        if (reason !== void 0) {
+          this.reason = reason;
+        }
+        if (context !== void 0) {
+          this.context = context;
+        }
+      }
+    };
+    module.exports = { ScreenshotUtilsError };
+  }
+});
+
+// src/errors/capture.js
+var require_capture = __commonJS({
+  "src/errors/capture.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var CaptureError = class 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;
+      }
+    };
+    var BrowserUnavailableError = class extends CaptureError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "BROWSER_UNAVAILABLE";
+        this.retriable = true;
+      }
+    };
+    var PageTooTallError = class extends CaptureError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "PAGE_TOO_TALL";
+        this.retriable = false;
+      }
+    };
+    var ElementNotFoundError = class extends CaptureError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "ELEMENT_NOT_FOUND";
+        this.retriable = false;
+      }
+    };
+    var ElementNotVisibleError = class extends CaptureError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "ELEMENT_NOT_VISIBLE";
+        this.retriable = false;
+      }
+    };
+    var ElementMismatchError = class extends CaptureError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "ELEMENT_MISMATCH";
+        this.retriable = false;
+      }
+    };
+    var ElementTooLargeError = class extends CaptureError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "ELEMENT_TOO_LARGE";
+        this.retriable = false;
+      }
+    };
+    var StabilityTimeoutError = class extends CaptureError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "STABILITY_TIMEOUT";
+        this.retriable = true;
+      }
+    };
+    var CaptureTimeoutError = class 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
+    };
+  }
+});
+
+// src/errors/transform.js
+var require_transform = __commonJS({
+  "src/errors/transform.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var TransformError = class extends ScreenshotUtilsError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "TRANSFORM_ERROR";
+        this.retriable = false;
+      }
+    };
+    var InvalidRectError = class extends TransformError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "INVALID_RECT";
+        this.retriable = false;
+      }
+    };
+    var UnsupportedFormatError = class extends TransformError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "UNSUPPORTED_FORMAT";
+        this.retriable = false;
+      }
+    };
+    var BufferCorruptError = class 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
+    };
+  }
+});
+
+// src/errors/compose.js
+var require_compose = __commonJS({
+  "src/errors/compose.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var ComposeError = class extends ScreenshotUtilsError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "COMPOSE_ERROR";
+        this.retriable = false;
+      }
+    };
+    var DimensionMismatchError = class extends ComposeError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "DIMENSION_MISMATCH";
+        this.retriable = false;
+      }
+    };
+    var ThemeError = class extends ComposeError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "THEME_ERROR";
+        this.retriable = false;
+      }
+    };
+    var HeatmapPointError = class 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
+    };
+  }
+});
+
+// src/errors/tile.js
+var require_tile = __commonJS({
+  "src/errors/tile.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var TileError = class extends ScreenshotUtilsError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "TILE_ERROR";
+        this.retriable = false;
+      }
+    };
+    var TileSizeError = class extends TileError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "TILE_SIZE";
+        this.retriable = false;
+      }
+    };
+    var TileWriteError = class 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
+    };
+  }
+});
+
+// src/errors/redaction.js
+var require_redaction = __commonJS({
+  "src/errors/redaction.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var RedactionError = class extends ScreenshotUtilsError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "REDACTION_ERROR";
+        this.retriable = false;
+      }
+    };
+    var PolicyError = class 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
+    };
+  }
+});
+
+// src/errors/adapter.js
+var require_adapter = __commonJS({
+  "src/errors/adapter.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var AdapterError = class extends ScreenshotUtilsError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "ADAPTER_ERROR";
+        this.retriable = false;
+      }
+    };
+    var AdapterContractError = class extends AdapterError {
+      /**
+       * @param {string} message
+       * @param {object} [options]
+       */
+      constructor(message, options) {
+        super(message, options);
+        this.code = "ADAPTER_CONTRACT";
+        this.retriable = false;
+      }
+    };
+    var BrowserApiError = class 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
+    };
+  }
+});
+
+// src/errors/optional.js
+var require_optional = __commonJS({
+  "src/errors/optional.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var OptionalDependencyMissingError = class 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 !== void 0) {
+          this.packageName = packageName;
+        }
+        if (installCommand !== void 0) {
+          this.installCommand = installCommand;
+        } else if (packageName !== void 0) {
+          this.installCommand = `npm install ${packageName}`;
+        }
+      }
+    };
+    module.exports = {
+      OptionalDependencyMissingError
+    };
+  }
+});
+
+// src/errors/index.js
+var require_errors = __commonJS({
+  "src/errors/index.js"(exports, module) {
+    var { ScreenshotUtilsError } = require_base();
+    var {
+      CaptureError,
+      BrowserUnavailableError,
+      PageTooTallError,
+      ElementNotFoundError,
+      ElementNotVisibleError,
+      ElementMismatchError,
+      ElementTooLargeError,
+      StabilityTimeoutError,
+      CaptureTimeoutError
+    } = require_capture();
+    var {
+      TransformError,
+      InvalidRectError,
+      UnsupportedFormatError,
+      BufferCorruptError
+    } = require_transform();
+    var {
+      ComposeError,
+      DimensionMismatchError,
+      ThemeError,
+      HeatmapPointError
+    } = require_compose();
+    var { TileError, TileSizeError, TileWriteError } = require_tile();
+    var { RedactionError, PolicyError } = require_redaction();
+    var { AdapterError, AdapterContractError, BrowserApiError } = require_adapter();
+    var { OptionalDependencyMissingError } = require_optional();
+    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
+    };
+  }
+});
+
+// src/adapters/puppeteer.js
+var require_puppeteer = __commonJS({
+  "src/adapters/puppeteer.js"(exports, module) {
+    var { AdapterContractError, BrowserApiError } = require_errors();
+    function fromPuppeteerPage(page, options = {}) {
+      assertPuppeteerPage(page);
+      const label = options.label;
+      const screenshotMaxHeight = Number.isFinite(options.screenshotMaxHeight) ? options.screenshotMaxHeight : 16384;
+      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: (/* @__PURE__ */ 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;
+        }
+      };
+    }
+    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 } }
+        );
+      }
+    }
+    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 };
+  }
+});
+
+// src/adapters/playwright.js
+var require_playwright = __commonJS({
+  "src/adapters/playwright.js"(exports, module) {
+    var { AdapterContractError, BrowserApiError } = require_errors();
+    function fromPlaywrightPage(page, options = {}) {
+      assertPlaywrightPage(page);
+      const label = options.label;
+      const screenshotMaxHeight = Number.isFinite(options.screenshotMaxHeight) ? options.screenshotMaxHeight : 16384;
+      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: (/* @__PURE__ */ new Date()).toISOString() };
+        },
+        async setViewport(viewport) {
+          await wrapBrowserCall(
+            "page.setViewportSize",
+            () => page.setViewportSize({
+              width: viewport.width,
+              height: viewport.height
+            }),
+            label
+          );
+        },
+        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;
+        }
+      };
+    }
+    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 } }
+        );
+      }
+    }
+    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 };
+  }
+});
+
+// src/adapters/cdp.js
+var require_cdp = __commonJS({
+  "src/adapters/cdp.js"(exports, module) {
+    var { AdapterContractError, BrowserApiError } = require_errors();
+    var { fromPuppeteerPage } = require_puppeteer();
+    function fromCDPSession(session, page, options = {}) {
+      assertSession(session);
+      const base = fromPuppeteerPage(page, options);
+      const label = options.label;
+      const screenshotMaxHeight = Number.isFinite(options.screenshotMaxHeight) ? options.screenshotMaxHeight : 16384;
+      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;
+        }
+      };
+    }
+    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;
+    }
+    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 };
+  }
+});
+
+// src/adapters/index.js
+var require_adapters = __commonJS({
+  "src/adapters/index.js"(exports, module) {
+    var { fromPuppeteerPage } = require_puppeteer();
+    var { fromPlaywrightPage } = require_playwright();
+    var { fromCDPSession } = require_cdp();
+    module.exports = { fromPuppeteerPage, fromPlaywrightPage, fromCDPSession };
+  }
+});
+
+// src/capture/settle.js
+var require_settle = __commonJS({
+  "src/capture/settle.js"(exports, module) {
+    async function waitForStable(adapter, options = {}) {
+      const {
+        fonts = true,
+        images = true,
+        animations = "reduce",
+        maxWait = 5e3,
+        idleMs = 200
+      } = options;
+      const start = nowMs();
+      const report = await adapter.evaluate(runInPage, {
+        fonts,
+        images,
+        animations,
+        maxWait,
+        idleMs
+      });
+      const totalMs = nowMs() - start;
+      return { ...report, totalMs };
+    }
+    async function runInPage(opts) {
+      const doc = globalThis.document;
+      const report = {
+        fonts: "skipped",
+        images: { total: 0, loaded: 0, failed: 0 },
+        animations: "skipped"
+      };
+      const withTimeout = (promise, ms, label) => Promise.race([
+        promise,
+        new Promise((_resolve, reject) => {
+          setTimeout(() => reject(new Error(`${label} timeout`)), ms);
+        })
+      ]);
+      const settleFonts = async () => {
+        if (!opts.fonts || !doc || !doc.fonts || !doc.fonts.ready) {
+          return;
+        }
+        try {
+          await withTimeout(doc.fonts.ready, opts.maxWait, "fonts.ready");
+          report.fonts = "ready";
+        } catch {
+          report.fonts = "timeout";
+        }
+      };
+      const settleOneImage = (img) => new Promise((resolve) => {
+        if (img.complete) {
+          if (img.naturalHeight > 0) {
+            report.images.loaded += 1;
+          } else {
+            report.images.failed += 1;
+          }
+          resolve();
+          return;
+        }
+        img.addEventListener(
+          "load",
+          () => {
+            report.images.loaded += 1;
+            resolve();
+          },
+          { once: true }
+        );
+        img.addEventListener(
+          "error",
+          () => {
+            report.images.failed += 1;
+            resolve();
+          },
+          { once: true }
+        );
+      });
+      const settleImages = async () => {
+        if (!opts.images || !doc) {
+          return;
+        }
+        const imgs = Array.from(doc.images || doc.querySelectorAll("img") || []);
+        report.images.total = imgs.length;
+        await Promise.all(imgs.map(settleOneImage));
+      };
+      const settleAnimations = async () => {
+        if (opts.animations === "ignore" || !doc) {
+          return;
+        }
+        const reduced = globalThis.matchMedia && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
+        if (reduced) {
+          report.animations = "reduced";
+          return;
+        }
+        const running = doc.getAnimations ? doc.getAnimations().filter((a) => a.playState === "running") : [];
+        if (opts.animations === "reduce") {
+          report.animations = running.length > 0 ? "timeout" : "none";
+          return;
+        }
+        if (opts.animations === "wait") {
+          if (running.length === 0) {
+            report.animations = "none";
+            return;
+          }
+          try {
+            await withTimeout(
+              Promise.all(running.map((a) => a.finished.catch(() => {
+              }))),
+              opts.maxWait,
+              "animations"
+            );
+            report.animations = "settled";
+          } catch {
+            report.animations = "timeout";
+          }
+        }
+      };
+      const settleIdle = async () => {
+        if (opts.idleMs <= 0) {
+          return;
+        }
+        if (typeof globalThis.requestIdleCallback === "function") {
+          await new Promise((resolve) => {
+            globalThis.requestIdleCallback(() => resolve(), {
+              timeout: opts.idleMs * 2
+            });
+          });
+        }
+        await new Promise((resolve) => {
+          setTimeout(resolve, opts.idleMs);
+        });
+      };
+      await settleFonts();
+      await settleImages();
+      await settleAnimations();
+      await settleIdle();
+      return report;
+    }
+    function nowMs() {
+      return Number(process.hrtime.bigint() / 1000000n);
+    }
+    module.exports = { waitForStable };
+  }
+});
+
+// src/capture/page.js
+var require_page = __commonJS({
+  "src/capture/page.js"(exports, module) {
+    var { CaptureTimeoutError, UnsupportedFormatError } = require_errors();
+    var { waitForStable } = require_settle();
+    async function capturePage(adapter, options = {}) {
+      const {
+        format = "png",
+        quality = 90,
+        fullPage = true,
+        omitBackground = false,
+        encoding = "buffer",
+        timeout = 3e4,
+        waitForStable: settleOpts = false,
+        events = null
+      } = options;
+      validateFormat(format);
+      const start = nowMs();
+      emit(events, "capture:start", { format, fullPage });
+      let settleMs = 0;
+      const warnings = [];
+      if (settleOpts) {
+        const settleStart = nowMs();
+        const report = await waitForStable(adapter, settleOpts === true ? {} : settleOpts);
+        settleMs = nowMs() - settleStart;
+        if (report.fonts === "timeout") {
+          warnings.push("fonts did not settle within maxWait");
+        }
+        if (report.animations === "timeout") {
+          warnings.push("animations did not settle within maxWait");
+        }
+        if (report.images.failed > 0) {
+          warnings.push(`${report.images.failed} image(s) failed to load`);
+        }
+      }
+      const metrics = await adapter.getMetrics();
+      const browserFormat = decideBrowserFormat(format);
+      const browserOpts = buildBrowserOpts({
+        format: browserFormat,
+        quality,
+        fullPage,
+        omitBackground
+      });
+      const captureStart = nowMs();
+      const rawBuffer = await withTimeout(adapter.screenshot(browserOpts), timeout, {
+        operation: "adapter.screenshot"
+      });
+      const captureMs = nowMs() - captureStart;
+      let bytes = rawBuffer;
+      let encodeMs = 0;
+      if (browserFormat !== format) {
+        const encodeStart = nowMs();
+        bytes = await reencode(rawBuffer, { format, quality });
+        encodeMs = nowMs() - encodeStart;
+      }
+      if (encoding === "stream") {
+        bytes = bufferToStream(bytes);
+      }
+      const totalMs = nowMs() - start;
+      const result = {
+        format,
+        bytes,
+        page: metrics,
+        timing: { settleMs, captureMs, encodeMs, totalMs },
+        warnings
+      };
+      emit(events, "capture:complete", {
+        format,
+        bytes: typeof bytes === "object" && Buffer.isBuffer(bytes) ? bytes.length : null,
+        totalMs
+      });
+      return result;
+    }
+    function decideBrowserFormat(format) {
+      return format === "webp" ? "png" : format;
+    }
+    function buildBrowserOpts({ format, quality, fullPage, omitBackground }) {
+      const out = { fullPage, omitBackground, type: format };
+      if (format === "jpeg") {
+        out.quality = quality;
+      }
+      return out;
+    }
+    async function reencode(input, { format, quality }) {
+      const sharp = __require("sharp");
+      let pipeline = sharp(input);
+      switch (format) {
+        case "webp":
+          pipeline = pipeline.webp({ quality });
+          break;
+        case "jpeg":
+          pipeline = pipeline.jpeg({ quality });
+          break;
+        case "png":
+          pipeline = pipeline.png();
+          break;
+      }
+      return pipeline.toBuffer();
+    }
+    function withTimeout(promise, ms, ctx) {
+      if (!Number.isFinite(ms) || ms <= 0) {
+        return promise;
+      }
+      let timer;
+      const timeoutPromise = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new CaptureTimeoutError(`${ctx.operation} exceeded ${ms}ms timeout`, {
+              context: { operation: ctx.operation, timeoutMs: ms }
+            })
+          );
+        }, ms);
+        if (typeof timer.unref === "function") {
+          timer.unref();
+        }
+      });
+      return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+    }
+    function validateFormat(format) {
+      if (!["png", "jpeg", "webp"].includes(format)) {
+        throw new UnsupportedFormatError(
+          `format must be 'png', 'jpeg', or 'webp'; received ${JSON.stringify(format)}`,
+          { context: { received: format } }
+        );
+      }
+    }
+    function emit(events, name, payload) {
+      if (events && typeof events.emit === "function") {
+        events.emit(name, payload);
+      }
+    }
+    function nowMs() {
+      return Number(process.hrtime.bigint() / 1000000n);
+    }
+    function bufferToStream(buf) {
+      const { Readable } = __require("stream");
+      return Readable.from(buf);
+    }
+    module.exports = { capturePage };
+  }
+});
+
+// src/capture/long-page.js
+var require_long_page = __commonJS({
+  "src/capture/long-page.js"(exports, module) {
+    var { PageTooTallError, CaptureTimeoutError } = require_errors();
+    async function captureLongPage(adapter, options = {}) {
+      const {
+        stripHeight = null,
+        overlap = 0,
+        maxHeight = 32768,
+        format = "png",
+        quality = 90,
+        omitBackground = false,
+        scrollSettleMs = 100,
+        timeout = 3e4,
+        events = null
+      } = options;
+      const start = nowMs();
+      emit(events, "capture:start", { format, fullPage: true, mode: "long-page" });
+      const metrics = await adapter.getMetrics();
+      if (metrics.height > maxHeight) {
+        throw new PageTooTallError(
+          `Page height ${metrics.height}px exceeds maxHeight ${maxHeight}px`,
+          { context: { documentHeight: metrics.height, maxHeight } }
+        );
+      }
+      const capabilities = adapter.capabilities ?? { screenshotMaxHeight: 16384 };
+      const browserMax = capabilities.screenshotMaxHeight;
+      const captureStart = nowMs();
+      const { bytes: stitched, encodeMs } = metrics.height <= browserMax ? await singleShotCapture(adapter, {
+        format,
+        quality,
+        omitBackground,
+        timeout
+      }) : await stripCapture(adapter, {
+        metrics,
+        stripHeight,
+        overlap,
+        scrollSettleMs,
+        timeout,
+        format,
+        quality,
+        omitBackground,
+        events
+      });
+      const captureMs = nowMs() - captureStart - encodeMs;
+      const totalMs = nowMs() - start;
+      const result = {
+        format,
+        bytes: stitched,
+        page: metrics,
+        timing: { settleMs: 0, captureMs, encodeMs, totalMs },
+        warnings: []
+      };
+      emit(events, "capture:complete", { format, totalMs });
+      return result;
+    }
+    async function singleShotCapture(adapter, opts) {
+      const { format, quality, omitBackground, timeout } = opts;
+      const bytes = await withTimeout(
+        adapter.screenshot({
+          fullPage: true,
+          type: format === "webp" ? "png" : format,
+          omitBackground,
+          ...format === "jpeg" ? { quality } : {}
+        }),
+        timeout,
+        { operation: "adapter.screenshot(fullPage)" }
+      );
+      return { bytes, encodeMs: 0 };
+    }
+    async function stripCapture(adapter, opts) {
+      const {
+        metrics,
+        stripHeight,
+        overlap,
+        scrollSettleMs,
+        timeout,
+        format,
+        quality,
+        omitBackground,
+        events
+      } = opts;
+      const sh = Math.max(1, stripHeight ?? metrics.viewport.height);
+      const stride = Math.max(1, sh - overlap);
+      const uniqueYs = planStripYs(metrics.height, sh, stride);
+      const strips = [];
+      for (let i = 0; i < uniqueYs.length; i += 1) {
+        const y = uniqueYs[i];
+        await adapter.scrollTo({ x: 0, y });
+        if (scrollSettleMs > 0) {
+          await sleep(scrollSettleMs);
+        }
+        const buffer = await withTimeout(
+          adapter.screenshot({ fullPage: false, type: "png", omitBackground }),
+          timeout,
+          { operation: `adapter.screenshot(strip ${i + 1}/${uniqueYs.length})` }
+        );
+        strips.push({ y, buffer });
+        emit(events, "strip:captured", { index: i, total: uniqueYs.length, y });
+      }
+      const stitchStart = nowMs();
+      const bytes = await stitchStrips(strips, {
+        width: metrics.viewport.width,
+        height: metrics.height,
+        format,
+        quality
+      });
+      return { bytes, encodeMs: nowMs() - stitchStart };
+    }
+    function planStripYs(height, sh, stride) {
+      const ys = [];
+      for (let y = 0; y < height; y += stride) {
+        ys.push(Math.min(y, height - sh));
+        if (y + sh >= height) {
+          break;
+        }
+      }
+      return Array.from(new Set(ys));
+    }
+    async function stitchStrips(strips, { width, height, format, quality }) {
+      const sharp = __require("sharp");
+      const canvas = sharp({
+        create: {
+          width: Math.round(width),
+          height: Math.round(height),
+          channels: 4,
+          background: { r: 0, g: 0, b: 0, alpha: 0 }
+        }
+      }).png();
+      const composites = strips.map(({ y, buffer }) => ({
+        input: buffer,
+        top: Math.round(y),
+        left: 0
+      }));
+      let pipeline = canvas.composite(composites);
+      switch (format) {
+        case "webp":
+          pipeline = pipeline.webp({ quality });
+          break;
+        case "jpeg":
+          pipeline = pipeline.jpeg({ quality });
+          break;
+        case "png":
+          pipeline = pipeline.png();
+          break;
+      }
+      return pipeline.toBuffer();
+    }
+    function sleep(ms) {
+      return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+      });
+    }
+    function emit(events, name, payload) {
+      if (events && typeof events.emit === "function") {
+        events.emit(name, payload);
+      }
+    }
+    function nowMs() {
+      return Number(process.hrtime.bigint() / 1000000n);
+    }
+    function withTimeout(promise, ms, ctx) {
+      if (!Number.isFinite(ms) || ms <= 0) {
+        return promise;
+      }
+      let timer;
+      const timeoutPromise = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new CaptureTimeoutError(`${ctx.operation} exceeded ${ms}ms timeout`, {
+              context: { operation: ctx.operation, timeoutMs: ms }
+            })
+          );
+        }, ms);
+        if (typeof timer.unref === "function") {
+          timer.unref();
+        }
+      });
+      return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+    }
+    module.exports = { captureLongPage };
+  }
+});
+
+// src/capture/element.js
+var require_element = __commonJS({
+  "src/capture/element.js"(exports, module) {
+    var { CaptureTimeoutError } = require_errors();
+    async function captureElement(adapter, options = {}) {
+      const {
+        selector,
+        xpath,
+        snippet,
+        padding = 10,
+        maxDimensions = { width: 4e3, height: 4e3 },
+        scrollIntoView = true,
+        timeout = 5e3,
+        format = "png",
+        quality = 90,
+        events = null
+      } = options;
+      if (!selector && !xpath) {
+        return failure(
+          { selector, xpath, format },
+          "element_not_found",
+          null,
+          "No selector or xpath provided"
+        );
+      }
+      const start = nowMs();
+      emit(events, "capture:start", { format, mode: "element", selector, xpath });
+      const lookup = await withTimeout(
+        adapter.evaluate(findElementInPage, { selector, xpath }),
+        timeout,
+        { operation: "adapter.evaluate(findElement)" }
+      );
+      if (!lookup || !lookup.found) {
+        return failure({ selector, xpath, format }, "element_not_found", null, null);
+      }
+      if (lookup.documentRect.width === 0 || lookup.documentRect.height === 0) {
+        return failure({ selector, xpath, format }, "element_not_visible", lookup, null);
+      }
+      if (lookup.documentRect.width > maxDimensions.width || lookup.documentRect.height > maxDimensions.height) {
+        return failure({ selector, xpath, format }, "element_too_large", lookup, null);
+      }
+      if (snippet) {
+        const normalize = (s) => String(s).replaceAll(/\s+/g, " ").trim();
+        if (normalize(lookup.outerHTML) !== normalize(snippet)) {
+          return failure(
+            { selector, xpath, format },
+            "element_mismatch",
+            lookup,
+            "Provided snippet did not match element outerHTML"
+          );
+        }
+      }
+      let viewportRect = lookup.viewportRect;
+      if (scrollIntoView) {
+        await adapter.scrollTo({
+          x: 0,
+          y: Math.max(0, lookup.documentRect.y - padding)
+        });
+        const reread = await withTimeout(
+          adapter.evaluate(findElementInPage, { selector, xpath }),
+          timeout,
+          { operation: "adapter.evaluate(findElement after scroll)" }
+        );
+        if (reread && reread.found) {
+          viewportRect = reread.viewportRect;
+        }
+      }
+      const clip = {
+        x: Math.max(0, Math.round(viewportRect.x - padding)),
+        y: Math.max(0, Math.round(viewportRect.y - padding)),
+        width: Math.round(viewportRect.width + 2 * padding),
+        height: Math.round(viewportRect.height + 2 * padding)
+      };
+      const screenshotOpts = { fullPage: false, type: format, clip };
+      if (format === "jpeg") {
+        screenshotOpts.quality = quality;
+      }
+      const captureStart = nowMs();
+      const bytes = await withTimeout(adapter.screenshot(screenshotOpts), timeout, {
+        operation: "adapter.screenshot(element)"
+      });
+      const captureMs = nowMs() - captureStart;
+      const metrics = await adapter.getMetrics();
+      const totalMs = nowMs() - start;
+      const result = {
+        format,
+        bytes,
+        page: metrics,
+        timing: { settleMs: 0, captureMs, encodeMs: 0, totalMs },
+        warnings: [],
+        element: {
+          selector: selector ?? "",
+          xpath: xpath ?? "",
+          documentRect: lookup.documentRect,
+          viewportRect,
+          verified: Boolean(snippet)
+        }
+      };
+      emit(events, "capture:complete", { format, totalMs, mode: "element" });
+      return result;
+    }
+    function findElementInPage(args) {
+      const doc = globalThis.document;
+      let element;
+      if (args.selector) {
+        try {
+          element = doc.querySelector(args.selector);
+        } catch {
+          element = null;
+        }
+      }
+      if (!element && args.xpath) {
+        try {
+          const FIRST = 9;
+          const res = doc.evaluate(args.xpath, doc, null, FIRST, null);
+          element = res.singleNodeValue;
+        } catch {
+          element = null;
+        }
+      }
+      if (!element) {
+        return { found: false };
+      }
+      const rect = element.getBoundingClientRect();
+      const sx = globalThis.scrollX || 0;
+      const sy = globalThis.scrollY || 0;
+      return {
+        found: true,
+        outerHTML: element.outerHTML,
+        documentRect: {
+          x: rect.x + sx,
+          y: rect.y + sy,
+          width: rect.width,
+          height: rect.height
+        },
+        viewportRect: {
+          x: rect.x,
+          y: rect.y,
+          width: rect.width,
+          height: rect.height
+        }
+      };
+    }
+    function failure(input, reason, lookup, verificationReason) {
+      return {
+        format: input.format,
+        bytes: null,
+        page: null,
+        timing: { settleMs: 0, captureMs: 0, encodeMs: 0, totalMs: 0 },
+        warnings: [],
+        element: {
+          selector: input.selector ?? "",
+          xpath: input.xpath ?? "",
+          documentRect: lookup?.documentRect ?? { x: 0, y: 0, width: 0, height: 0 },
+          viewportRect: lookup?.viewportRect ?? { x: 0, y: 0, width: 0, height: 0 },
+          verified: false,
+          ...verificationReason ? { verificationReason } : {}
+        },
+        reason
+      };
+    }
+    function emit(events, name, payload) {
+      if (events && typeof events.emit === "function") {
+        events.emit(name, payload);
+      }
+    }
+    function nowMs() {
+      return Number(process.hrtime.bigint() / 1000000n);
+    }
+    function withTimeout(promise, ms, ctx) {
+      if (!Number.isFinite(ms) || ms <= 0) {
+        return promise;
+      }
+      let timer;
+      const timeoutPromise = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new CaptureTimeoutError(`${ctx.operation} exceeded ${ms}ms timeout`, {
+              context: { operation: ctx.operation, timeoutMs: ms }
+            })
+          );
+        }, ms);
+        if (typeof timer.unref === "function") {
+          timer.unref();
+        }
+      });
+      return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+    }
+    module.exports = { captureElement };
+  }
+});
+
+// src/capture/viewport.js
+var require_viewport = __commonJS({
+  "src/capture/viewport.js"(exports, module) {
+    var { capturePage } = require_page();
+    async function captureViewport(adapter, options = {}) {
+      return capturePage(adapter, { ...options, fullPage: false });
+    }
+    module.exports = { captureViewport };
+  }
+});
+
+// src/capture/responsive.js
+var require_responsive = __commonJS({
+  "src/capture/responsive.js"(exports, module) {
+    var { capturePage } = require_page();
+    var { captureLongPage } = require_long_page();
+    var { captureViewport } = require_viewport();
+    async function captureResponsive(adapter, options) {
+      if (!options || !Array.isArray(options.viewports) || options.viewports.length === 0) {
+        const { InvalidRectError } = require_errors();
+        throw new InvalidRectError(
+          "captureResponsive requires options.viewports as a non-empty array",
+          { context: { received: options?.viewports } }
+        );
+      }
+      const { viewports, reloadBetween = true, captureMode = "fullPage", ...rest } = options;
+      delete rest.parallelism;
+      const captureOptions = rest;
+      const start = nowMs();
+      const captures = [];
+      for (const viewport of viewports) {
+        if (!viewport || typeof viewport.name !== "string") {
+          const { InvalidRectError } = require_errors();
+          throw new InvalidRectError("Each viewport must have a string name", {
+            context: { viewport }
+          });
+        }
+        await adapter.setViewport(viewport);
+        if (reloadBetween) {
+          await adapter.reload({ waitUntil: "networkidle0" }).catch(() => adapter.reload());
+        }
+        const capture = await captureForMode(adapter, captureMode, captureOptions);
+        captures.push({ ...capture, viewportName: viewport.name });
+      }
+      return {
+        captures,
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        totalMs: nowMs() - start
+      };
+    }
+    async function captureForMode(adapter, mode, captureOptions) {
+      switch (mode) {
+        case "viewport":
+          return captureViewport(adapter, captureOptions);
+        case "longPage":
+          return captureLongPage(adapter, captureOptions);
+        default:
+          return capturePage(adapter, { ...captureOptions, fullPage: true });
+      }
+    }
+    function nowMs() {
+      return Number(process.hrtime.bigint() / 1000000n);
+    }
+    module.exports = { captureResponsive };
+  }
+});
+
+// src/capture/index.js
+var require_capture2 = __commonJS({
+  "src/capture/index.js"(exports, module) {
+    var { capturePage } = require_page();
+    var { waitForStable } = require_settle();
+    var { captureLongPage } = require_long_page();
+    var { captureElement } = require_element();
+    var { captureViewport } = require_viewport();
+    var { captureResponsive } = require_responsive();
+    module.exports = {
+      capturePage,
+      waitForStable,
+      captureLongPage,
+      captureElement,
+      captureViewport,
+      captureResponsive
+    };
+  }
+});
+
+// src/transform/crop.js
+var require_crop = __commonJS({
+  "src/transform/crop.js"(exports, module) {
+    var { InvalidRectError, BufferCorruptError } = require_errors();
+    async function crop(input, rect, options = {}) {
+      assertBuffer(input);
+      assertRect(rect);
+      const { padding = 0, format, quality = 90 } = options;
+      const sharp = __require("sharp");
+      const meta = await readMeta(sharp, input);
+      const extract = computeExtract(rect, padding, meta);
+      if (extract.width <= 0 || extract.height <= 0) {
+        throw new InvalidRectError(
+          `Rect resolves to 0\xD70 after clamping to image bounds (${meta.width}\xD7${meta.height})`,
+          { context: { rect, padding, imageWidth: meta.width, imageHeight: meta.height } }
+        );
+      }
+      let pipeline = sharp(input).extract(extract);
+      pipeline = applyFormat(pipeline, format, quality);
+      return pipeline.toBuffer();
+    }
+    async function cropMany(input, entries, options = {}) {
+      assertBuffer(input);
+      if (!Array.isArray(entries)) {
+        throw new InvalidRectError("cropMany entries must be an array", {
+          context: { received: typeof entries }
+        });
+      }
+      const { padding = 0, format, quality = 90, parallelism = 4 } = options;
+      const sharp = __require("sharp");
+      const meta = await readMeta(sharp, input);
+      const planned = entries.map((entry) => {
+        if (!entry || typeof entry.id !== "string") {
+          throw new InvalidRectError("Each cropMany entry must have a string id and a rect", {
+            context: { entry }
+          });
+        }
+        assertRect(entry.rect);
+        const extract = computeExtract(entry.rect, padding, meta);
+        if (extract.width <= 0 || extract.height <= 0) {
+          throw new InvalidRectError(
+            `Rect for id ${JSON.stringify(entry.id)} resolves to 0\xD70 after clamping`,
+            {
+              context: {
+                id: entry.id,
+                rect: entry.rect,
+                padding,
+                imageWidth: meta.width,
+                imageHeight: meta.height
+              }
+            }
+          );
+        }
+        return { id: entry.id, extract };
+      });
+      const results = /* @__PURE__ */ new Map();
+      await parallelEach(
+        planned,
+        async ({ id, extract }) => {
+          let pipeline = sharp(input).extract(extract);
+          pipeline = applyFormat(pipeline, format, quality);
+          const buffer = await pipeline.toBuffer();
+          results.set(id, buffer);
+        },
+        Math.max(1, parallelism)
+      );
+      return results;
+    }
+    async function parallelEach(items, fn, limit) {
+      let cursor = 0;
+      const workers = Array.from({ length: Math.min(limit, items.length || 1) }, async () => {
+        while (cursor < items.length) {
+          const i = cursor;
+          cursor += 1;
+          await fn(items[i], i);
+        }
+      });
+      await Promise.all(workers);
+    }
+    function assertRect(rect) {
+      if (rect === null || typeof rect !== "object") {
+        throw new InvalidRectError("rect must be an object", {
+          context: { received: typeof rect }
+        });
+      }
+      const { x, y, width, height } = (
+        /** @type {Record<string, unknown>} */
+        rect
+      );
+      for (const [key, value] of [
+        ["x", x],
+        ["y", y],
+        ["width", width],
+        ["height", height]
+      ]) {
+        if (!Number.isFinite(value)) {
+          throw new InvalidRectError(`rect.${key} must be a finite number`, {
+            context: { rect }
+          });
+        }
+      }
+      if (width <= 0 || height <= 0) {
+        throw new InvalidRectError("rect.width and rect.height must be > 0", {
+          context: { rect }
+        });
+      }
+    }
+    function assertBuffer(input) {
+      if (!Buffer.isBuffer(input)) {
+        throw new BufferCorruptError("input must be a Buffer", {
+          context: { received: typeof input }
+        });
+      }
+    }
+    function computeExtract(rect, padding, meta) {
+      const left = clamp(Math.round(rect.x - padding), 0, meta.width);
+      const top = clamp(Math.round(rect.y - padding), 0, meta.height);
+      const right = clamp(Math.round(rect.x + rect.width + padding), 0, meta.width);
+      const bottom = clamp(Math.round(rect.y + rect.height + padding), 0, meta.height);
+      return {
+        left,
+        top,
+        width: Math.max(0, right - left),
+        height: Math.max(0, bottom - top)
+      };
+    }
+    function clamp(n, lo, hi) {
+      if (n < lo) {
+        return lo;
+      }
+      if (n > hi) {
+        return hi;
+      }
+      return n;
+    }
+    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", {
+            context: { meta }
+          });
+        }
+        return { width: meta.width, height: meta.height };
+      } catch (error) {
+        if (error instanceof BufferCorruptError) {
+          throw error;
+        }
+        throw new BufferCorruptError("sharp could not read input buffer metadata", {
+          cause: error
+        });
+      }
+    }
+    function applyFormat(pipeline, format, quality) {
+      if (!format) {
+        return pipeline;
+      }
+      switch (format) {
+        case "png":
+          return pipeline.png();
+        case "jpeg":
+          return pipeline.jpeg({ quality });
+        case "webp":
+          return pipeline.webp({ quality });
+        default:
+          return pipeline;
+      }
+    }
+    module.exports = { crop, cropMany };
+  }
+});
+
+// src/transform/convert.js
+var require_convert = __commonJS({
+  "src/transform/convert.js"(exports, module) {
+    var { BufferCorruptError, UnsupportedFormatError } = require_errors();
+    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 };
+  }
+});
+
+// src/transform/resize.js
+var require_resize = __commonJS({
+  "src/transform/resize.js"(exports, module) {
+    var { BufferCorruptError, InvalidRectError } = require_errors();
+    async function resize(input, options) {
+      assertBuffer(input);
+      if (!options || typeof options !== "object") {
+        throw new InvalidRectError("resize requires an options object", {
+          context: { received: typeof options }
+        });
+      }
+      const {
+        width,
+        height,
+        fit,
+        position,
+        kernel,
+        withoutEnlargement,
+        format,
+        quality = 90
+      } = options;
+      if (width === void 0 && height === void 0) {
+        throw new InvalidRectError("resize requires at least one of width or height", {
+          context: { options }
+        });
+      }
+      if (width !== void 0 && (!Number.isFinite(width) || width <= 0)) {
+        throw new InvalidRectError("resize.width must be a positive finite number", {
+          context: { width }
+        });
+      }
+      if (height !== void 0 && (!Number.isFinite(height) || height <= 0)) {
+        throw new InvalidRectError("resize.height must be a positive finite number", {
+          context: { height }
+        });
+      }
+      const sharp = __require("sharp");
+      const resizeOpts = {};
+      if (width !== void 0) {
+        resizeOpts.width = Math.round(width);
+      }
+      if (height !== void 0) {
+        resizeOpts.height = Math.round(height);
+      }
+      if (fit) {
+        resizeOpts.fit = fit;
+      }
+      if (position) {
+        resizeOpts.position = position;
+      }
+      if (kernel) {
+        resizeOpts.kernel = kernel;
+      }
+      if (withoutEnlargement !== void 0) {
+        resizeOpts.withoutEnlargement = withoutEnlargement;
+      }
+      let pipeline = sharp(input).resize(resizeOpts);
+      switch (format) {
+        case "png":
+          pipeline = pipeline.png();
+          break;
+        case "jpeg":
+          pipeline = pipeline.jpeg({ quality });
+          break;
+        case "webp":
+          pipeline = pipeline.webp({ quality });
+          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 = { resize };
+  }
+});
+
+// src/transform/normalize.js
+var require_normalize = __commonJS({
+  "src/transform/normalize.js"(exports, module) {
+    var { BufferCorruptError } = require_errors();
+    async function normalize(input, options = {}) {
+      assertBuffer(input);
+      const sharp = __require("sharp");
+      const meta = await readMeta(sharp, input);
+      const { fromDpr = inferDpr(meta), toDpr = 1 } = options;
+      if (!Number.isFinite(fromDpr) || fromDpr <= 0) {
+        throw new BufferCorruptError("Could not infer source DPR and no fromDpr supplied", {
+          context: { meta, fromDpr }
+        });
+      }
+      const scale = toDpr / fromDpr;
+      if (scale === 1) {
+        return {
+          buffer: input,
+          dimensions: {
+            width: Math.round(meta.width / fromDpr),
+            height: Math.round(meta.height / fromDpr)
+          }
+        };
+      }
+      const targetWidth = Math.max(1, Math.round(meta.width * scale));
+      const targetHeight = Math.max(1, Math.round(meta.height * scale));
+      const buffer = await sharp(input).resize({ width: targetWidth, height: targetHeight }).toBuffer();
+      return {
+        buffer,
+        dimensions: { width: targetWidth, height: targetHeight }
+      };
+    }
+    function inferDpr(meta) {
+      if (meta && Number.isFinite(meta.density) && meta.density > 0) {
+        return meta.density / 96;
+      }
+      return 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 {
+        return await sharp(input).metadata();
+      } catch (error) {
+        throw new BufferCorruptError("sharp could not read input buffer metadata", {
+          cause: error
+        });
+      }
+    }
+    module.exports = { normalize };
+  }
+});
+
+// src/transform/index.js
+var require_transform2 = __commonJS({
+  "src/transform/index.js"(exports, module) {
+    var { crop, cropMany } = require_crop();
+    var { convert } = require_convert();
+    var { resize } = require_resize();
+    var { normalize } = require_normalize();
+    module.exports = { crop, cropMany, convert, resize, normalize };
+  }
+});
+
+// src/tile/dzi.js
+var require_dzi = __commonJS({
+  "src/tile/dzi.js"(exports, module) {
+    var fs = __require("fs/promises");
+    var path = __require("path");
+    var os = __require("os");
+    var { randomUUID } = __require("crypto");
+    var { TileSizeError, TileWriteError, BufferCorruptError } = require_errors();
+    var MAX_TILES = 1e4;
+    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 : void 0,
+        totalBytes: tiles.reduce((sum, t) => sum + (t.bytes ? t.bytes.length : 0), 0),
+        totalTiles: tiles.length
+      };
+    }
+    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;
+    }
+    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 }
+          });
+      }
+    }
+    async function readDziXml(outputBase) {
+      try {
+        return await fs.readFile(`${outputBase}.dzi`, "utf8");
+      } catch (error) {
+        throw new TileWriteError("Sharp did not produce the .dzi descriptor file", {
+          cause: error
+        });
+      }
+    }
+    async function collectTiles({ outputBase, dirName, output }) {
+      const filesDir = `${outputBase}_files`;
+      const tiles = [];
+      let levels;
+      try {
+        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));
+        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") {
+            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 };
+  }
+});
+
+// src/tile/index.js
+var require_tile2 = __commonJS({
+  "src/tile/index.js"(exports, module) {
+    var { tileDzi } = require_dzi();
+    module.exports = { tileDzi };
+  }
+});
+
+// src/compose/theme.js
+var require_theme = __commonJS({
+  "src/compose/theme.js"(exports, module) {
+    var 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 };
+  }
+});
+
+// src/compose/annotate.js
+var require_annotate = __commonJS({
+  "src/compose/annotate.js"(exports, module) {
+    var {
+      BufferCorruptError,
+      ThemeError,
+      HeatmapPointError,
+      ComposeError
+    } = require_errors();
+    var { defaultTheme } = require_theme();
+    var MAX_ANNOTATIONS = 5e3;
+    var VALID_LEGEND_POSITIONS = /* @__PURE__ */ new Set([
+      "none",
+      "top-left",
+      "top-right",
+      "bottom-left",
+      "bottom-right"
+    ]);
+    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);
+      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();
+    }
+    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;
+    }
+    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) } }
+        );
+      }
+    }
+    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("");
+    }
+    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:
+          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 };
+  }
+});
+
+// src/compose/diff.js
+var require_diff = __commonJS({
+  "src/compose/diff.js"(exports, module) {
+    var {
+      BufferCorruptError,
+      DimensionMismatchError,
+      OptionalDependencyMissingError
+    } = require_errors();
+    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, {
+        b,
+        diffData,
+        width: a.width,
+        height: a.height
+      });
+      return {
+        diffBuffer,
+        changedPixels,
+        totalPixels,
+        percentChanged: totalPixels === 0 ? 0 : changedPixels / totalPixels * 100
+      };
+    }
+    async function loadPixelmatch() {
+      try {
+        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 }
+        );
+      }
+    }
+    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
+        });
+      }
+    }
+    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();
+      }
+      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 };
+  }
+});
+
+// src/compose/heatmap.js
+var require_heatmap = __commonJS({
+  "src/compose/heatmap.js"(exports, module) {
+    var { BufferCorruptError, ComposeError, HeatmapPointError } = require_errors();
+    var MAX_POINTS = 1e5;
+    var VALID_BLEND_MODES = /* @__PURE__ */ new Set(["overlay", "screen", "multiply"]);
+    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 !== void 0 && !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();
+    }
+    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>`;
+    }
+    function resolveColor(colorScale) {
+      if (typeof colorScale === "function") {
+        try {
+          const result = colorScale(1);
+          if (Array.isArray(result) && result.length >= 3) {
+            return `rgb(${result[0]}, ${result[1]}, ${result[2]})`;
+          }
+        } catch {
+        }
+        return "#FF0000";
+      }
+      switch (colorScale) {
+        case "magma":
+          return "#FB8861";
+        case "severity":
+          return "#D32F2F";
+        default:
+          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 };
+  }
+});
+
+// src/compose/index.js
+var require_compose2 = __commonJS({
+  "src/compose/index.js"(exports, module) {
+    var { annotate } = require_annotate();
+    var { defaultTheme } = require_theme();
+    var { diff } = require_diff();
+    var { heatmap } = require_heatmap();
+    module.exports = { annotate, defaultTheme, diff, heatmap };
+  }
+});
+
+// src/index.js
+var require_index = __commonJS({
+  "src/index.js"(exports, module) {
+    var pkg = require_package();
+    var errors = require_errors();
+    var adapters = require_adapters();
+    var capture = require_capture2();
+    var transform = require_transform2();
+    var tile = require_tile2();
+    var compose = require_compose2();
+    var defaults = Object.freeze({
+      format: "png",
+      quality: 90,
+      fullPage: true,
+      timeout: 3e4,
+      padding: 10,
+      stripHeight: null,
+      tileSize: 256,
+      tileOverlap: 1,
+      tileFormat: "webp",
+      tileQuality: 80,
+      waitForStable: Object.freeze({
+        fonts: true,
+        images: true,
+        animations: "reduce",
+        maxWait: 5e3,
+        idleMs: 200
+      })
+    });
+    var version = pkg.version;
+    module.exports = {
+      defaults,
+      version,
+      ...errors,
+      ...adapters,
+      ...capture,
+      ...transform,
+      ...tile,
+      ...compose
+    };
+  }
+});
+var index = require_index();
+
+export { index as default };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map