@afixt/screenshot-utils 0.9.0 → 1.0.0

package/dist/types/adapters/cdp.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Wrap a CDP (Chrome DevTools Protocol) session + Puppeteer page in the
+ * package's `PageAdapter` interface.
+ *
+ * Use this adapter when the consumer already holds a CDP session (e.g.
+ * the engine's CDP-attached runtime path described in spec § 10). The
+ * adapter routes `screenshot()` through CDP's `Page.captureScreenshot`
+ * — which avoids the page.screenshot() round-trip overhead — while
+ * delegating every other method to the supplied Puppeteer page.
+ *
+ * The Puppeteer page is required because CDP does not expose
+ * `Page.setViewport`, document scrollWidth/Height, or page reloads in a
+ * single coherent API; falling back to the Puppeteer page for those
+ * keeps the contract identical to `fromPuppeteerPage`.
+ *
+ * @public
+ * @param {object} session A CDP session (e.g. from `page.target().createCDPSession()`).
+ * @param {object} page The same Puppeteer Page the session is attached to.
+ * @param {object} [options]
+ * @param {string} [options.label]
+ * @param {number} [options.screenshotMaxHeight] Override Chromium's 16384 limit.
+ * @returns {import('../types/index.d.ts').PageAdapter}
+ */
+export function fromCDPSession(session: object, page: object, options?: {
+    label?: string | undefined;
+    screenshotMaxHeight?: number | undefined;
+}): import("../types/index.d.ts").PageAdapter;
+//# sourceMappingURL=cdp.d.ts.map

package/dist/types/adapters/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../../src/adapters/cdp.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wCAPW,MAAM,QACN,MAAM,YAEd;IAAyB,KAAK;IACL,mBAAmB;CAC5C,GAAU,OAAO,qBAAqB,EAAE,WAAW,CAyCrD"}

package/dist/types/adapters/index.d.ts

@@ -0,0 +1,5 @@
+import { fromPuppeteerPage } from "./puppeteer.js";
+import { fromPlaywrightPage } from "./playwright.js";
+import { fromCDPSession } from "./cdp.js";
+export { fromPuppeteerPage, fromPlaywrightPage, fromCDPSession };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/index.js"],"names":[],"mappings":""}

package/dist/types/adapters/playwright.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Wrap a Playwright `Page` object in the package's `PageAdapter` interface.
+ *
+ * Like `fromPuppeteerPage`, this adapter never imports `playwright` itself —
+ * the caller passes the `page` they already created. `playwright` remains
+ * an optional peer at the package level (spec § 10).
+ *
+ * Differences from Puppeteer's API (handled here so consumers don't have to):
+ * - Playwright uses `page.setViewportSize({ width, height })` instead of
+ *   `page.setViewport(...)`. The deviceScaleFactor on the Viewport type is
+ *   not settable post-hoc in Playwright — pass it at browser context
+ *   creation time.
+ * - Playwright's `page.screenshot()` accepts `type: 'png' | 'jpeg'` (no
+ *   webp). The adapter passes the type through; webp re-encode happens
+ *   one level up in capture functions.
+ *
+ * @public
+ * @param {object} page A Playwright Page instance (or compatible shim).
+ * @param {object} [options]
+ * @param {string} [options.label] Identifier for log lines.
+ * @param {number} [options.screenshotMaxHeight] Override Chromium's 16384 limit.
+ * @returns {import('../types/index.d.ts').PageAdapter}
+ */
+export function fromPlaywrightPage(page: object, options?: {
+    label?: string | undefined;
+    screenshotMaxHeight?: number | undefined;
+}): import("../types/index.d.ts").PageAdapter;
+//# sourceMappingURL=playwright.d.ts.map

package/dist/types/adapters/playwright.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../../../src/adapters/playwright.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yCANW,MAAM,YAEd;IAAyB,KAAK;IACL,mBAAmB;CAC5C,GAAU,OAAO,qBAAqB,EAAE,WAAW,CAgFrD"}

package/dist/types/adapters/puppeteer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Wrap a Puppeteer `Page` object in the package's `PageAdapter` interface.
+ *
+ * The adapter never imports `puppeteer` itself — the caller passes in the
+ * `page` they already created. This keeps `puppeteer` an optional peer
+ * dependency at the package level (per `spec.md` § 10) and means the same
+ * adapter works against any Puppeteer 23.x+ release without re-pinning.
+ *
+ * @public
+ * @param {object} page A Puppeteer Page instance (or compatible shim).
+ * @param {object} [options]
+ * @param {string} [options.label] Identifier for log lines (e.g. context id).
+ * @param {number} [options.screenshotMaxHeight] Override Chromium's 16384 limit.
+ * @returns {import('../types/index.d.ts').PageAdapter}
+ */
+export function fromPuppeteerPage(page: object, options?: {
+    label?: string | undefined;
+    screenshotMaxHeight?: number | undefined;
+}): import("../types/index.d.ts").PageAdapter;
+//# sourceMappingURL=puppeteer.d.ts.map

package/dist/types/adapters/puppeteer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"puppeteer.d.ts","sourceRoot":"","sources":["../../../src/adapters/puppeteer.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,wCANW,MAAM,YAEd;IAAyB,KAAK;IACL,mBAAmB;CAC5C,GAAU,OAAO,qBAAqB,EAAE,WAAW,CAgErD"}

package/dist/types/capture/element.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Capture a single element by selector or xpath.
+ *
+ * Implements `spec.md` § 8.1.3. **Deprecated as the engine's primary path**
+ * — prefer `capturePage` + `cropMany`. Retained because (a) the engine
+ * needs a like-for-like replacement during the Phase 3 migration and
+ * (b) direct callers (Investigator, ad-hoc tooling) still want it.
+ *
+ * Failure modes return an ElementCaptureResult with `bytes === null` and
+ * `reason` populated rather than throwing. This matches the engine's
+ * current `{ screenshot, reason }` contract so consumers can swap
+ * implementations without changing control flow.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').ElementCaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').ElementCaptureResult>}
+ */
+export function captureElement(adapter: import("../types/index.d.ts").PageAdapter, options?: import("../types/index.d.ts").ElementCaptureOptions): Promise<import("../types/index.d.ts").ElementCaptureResult>;
+//# sourceMappingURL=element.d.ts.map

package/dist/types/capture/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../../src/capture/element.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,wCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,qBAAqB,GACjD,OAAO,CAAC,OAAO,qBAAqB,EAAE,oBAAoB,CAAC,CA+GvE"}

package/dist/types/capture/index.d.ts

@@ -0,0 +1,8 @@
+import { capturePage } from "./page.js";
+import { waitForStable } from "./settle.js";
+import { captureLongPage } from "./long-page.js";
+import { captureElement } from "./element.js";
+import { captureViewport } from "./viewport.js";
+import { captureResponsive } from "./responsive.js";
+export { capturePage, waitForStable, captureLongPage, captureElement, captureViewport, captureResponsive };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/capture/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/capture/index.js"],"names":[],"mappings":""}

package/dist/types/capture/long-page.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Capture a page taller than the browser's single-screenshot height limit
+ * by scrolling, capturing strips, and stitching them via `sharp`.
+ *
+ * Implements `spec.md` § 8.1.4. If the document height fits within the
+ * adapter's `screenshotMaxHeight` capability, delegates to the regular
+ * `adapter.screenshot({ fullPage: true })`. Otherwise iterates over
+ * viewport-height strips, scrolling between captures.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').LongPageCaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').CaptureResult>}
+ */
+export function captureLongPage(adapter: import("../types/index.d.ts").PageAdapter, options?: import("../types/index.d.ts").LongPageCaptureOptions): Promise<import("../types/index.d.ts").CaptureResult>;
+//# sourceMappingURL=long-page.d.ts.map

package/dist/types/capture/long-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"long-page.d.ts","sourceRoot":"","sources":["../../../src/capture/long-page.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,yCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,sBAAsB,GAClD,OAAO,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,CA8DhE"}

package/dist/types/capture/page.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Capture a full page (or just the viewport) via a `PageAdapter`.
+ *
+ * Implements `spec.md` § 8.1.1. Lazy-loads `sharp` only when the requested
+ * output format is one the browser can't produce directly (today: webp;
+ * Chromium emits png/jpeg natively).
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').CaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').CaptureResult>}
+ */
+export function capturePage(adapter: import("../types/index.d.ts").PageAdapter, options?: import("../types/index.d.ts").CaptureOptions): Promise<import("../types/index.d.ts").CaptureResult>;
+//# sourceMappingURL=page.d.ts.map

package/dist/types/capture/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../../src/capture/page.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,qCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,cAAc,GAC1C,OAAO,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAkFhE"}

package/dist/types/capture/responsive.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Capture the same page at multiple viewport sizes in one orchestrated
+ * call. Useful for responsive accessibility audits.
+ *
+ * Implements `spec.md` § 8.1.5.
+ *
+ * - `parallelism: 1` (default) is the safe choice — driving viewport
+ *   changes against a single page in parallel produces non-deterministic
+ *   results. Consumers can bump it above 1 only if they hand over
+ *   distinct adapters via the (Phase 4) per-context capture API.
+ * - `reloadBetween: true` (default) reloads the page between viewport
+ *   changes so media queries and layout re-evaluate cleanly.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').ResponsiveCaptureOptions} options
+ * @returns {Promise<import('../types/index.d.ts').ResponsiveCaptureResult>}
+ */
+export function captureResponsive(adapter: import("../types/index.d.ts").PageAdapter, options: import("../types/index.d.ts").ResponsiveCaptureOptions): Promise<import("../types/index.d.ts").ResponsiveCaptureResult>;
+//# sourceMappingURL=responsive.d.ts.map

package/dist/types/capture/responsive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responsive.d.ts","sourceRoot":"","sources":["../../../src/capture/responsive.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;GAiBG;AACH,2CAJW,OAAO,qBAAqB,EAAE,WAAW,WACzC,OAAO,qBAAqB,EAAE,wBAAwB,GACpD,OAAO,CAAC,OAAO,qBAAqB,EAAE,uBAAuB,CAAC,CA6C1E"}

package/dist/types/capture/settle.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Wait for the page to reach a render-stable state before capture.
+ *
+ * Implements `spec.md` § 8.1.6. The whole settle logic runs inside the
+ * page context via a single `adapter.evaluate()` call to avoid Node ↔
+ * browser round-trips for each sub-check.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').WaitForStableOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').StabilityReport>}
+ */
+export function waitForStable(adapter: import("../types/index.d.ts").PageAdapter, options?: import("../types/index.d.ts").WaitForStableOptions): Promise<import("../types/index.d.ts").StabilityReport>;
+//# sourceMappingURL=settle.d.ts.map

package/dist/types/capture/settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../../src/capture/settle.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,uCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,oBAAoB,GAChD,OAAO,CAAC,OAAO,qBAAqB,EAAE,eAAe,CAAC,CAqBlE"}

package/dist/types/capture/viewport.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Capture only what is currently scrolled into view (no full-page scroll
+ * or stitching). Useful for AI evidence and above-the-fold checks.
+ *
+ * Implements `spec.md` § 8.1.2. Thin wrapper around `capturePage` that
+ * forces `fullPage: false` regardless of caller options.
+ *
+ * @public
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {import('../types/index.d.ts').CaptureOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').CaptureResult>}
+ */
+export function captureViewport(adapter: import("../types/index.d.ts").PageAdapter, options?: import("../types/index.d.ts").CaptureOptions): Promise<import("../types/index.d.ts").CaptureResult>;
+//# sourceMappingURL=viewport.d.ts.map

package/dist/types/capture/viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../../../src/capture/viewport.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,yCAJW,OAAO,qBAAqB,EAAE,WAAW,YACzC,OAAO,qBAAqB,EAAE,cAAc,GAC1C,OAAO,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAIhE"}

package/dist/types/cli/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI entry. Returns the process exit code (0 = success).
+ *
+ * @public
+ * @param {string[]} argv The argv array minus the node binary + script path
+ *                        (i.e. process.argv.slice(2)).
+ * @returns {Promise<number>}
+ */
+export function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.js"],"names":[],"mappings":"AA2BA;;;;;;;GAOG;AACH,2BAJW,MAAM,EAAE,GAEN,OAAO,CAAC,MAAM,CAAC,CAoB3B"}

package/dist/types/compose/annotate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Render annotation overlays onto a screenshot buffer.
+ *
+ * Implements `spec.md` § 8.3.1 with pure-sharp rendering — annotations are
+ * serialized to an SVG layer and composited onto the source image. No
+ * `@napi-rs/canvas` dep in v1.0 (deferred to v1.1 per spec § 22).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<import('../types/index.d.ts').Annotation>} annotations
+ * @param {import('../types/index.d.ts').AnnotateOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+export function annotate(input: Buffer, annotations: Array<import("../types/index.d.ts").Annotation>, options?: import("../types/index.d.ts").AnnotateOptions): Promise<Buffer>;
+export const MAX_ANNOTATIONS: 5000;
+//# sourceMappingURL=annotate.d.ts.map

package/dist/types/compose/annotate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../../../src/compose/annotate.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;GAYG;AACH,gCALW,MAAM,eACN,KAAK,CAAC,OAAO,qBAAqB,EAAE,UAAU,CAAC,YAC/C,OAAO,qBAAqB,EAAE,eAAe,GAC3C,OAAO,CAAC,MAAM,CAAC,CA+C3B;AAnED,8BAAwB,IAAI,CAAC"}

package/dist/types/compose/diff.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Perceptual visual diff between two image buffers.
+ *
+ * Implements `spec.md` § 8.3.4. Requires the optional peer
+ * `pixelmatch` (≥ v7); throws `OptionalDependencyMissingError` if it
+ * isn't installed.
+ *
+ * @public
+ * @param {Buffer} bufferA
+ * @param {Buffer} bufferB
+ * @param {import('../types/index.d.ts').DiffOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').DiffResult>}
+ */
+export function diff(bufferA: Buffer, bufferB: Buffer, options?: import("../types/index.d.ts").DiffOptions): Promise<import("../types/index.d.ts").DiffResult>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/types/compose/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/compose/diff.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH,8BALW,MAAM,WACN,MAAM,YACN,OAAO,qBAAqB,EAAE,WAAW,GACvC,OAAO,CAAC,OAAO,qBAAqB,EAAE,UAAU,CAAC,CA2D7D"}

package/dist/types/compose/heatmap.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Render a kernel-density heatmap over a screenshot.
+ *
+ * Implements `spec.md` § 8.3.3 with a simple SVG-circles + blur approach.
+ * Each point gets a circle whose radius scales with weight; the
+ * collection is then blurred to produce a smooth heatmap surface and
+ * composited onto the source using the requested blend mode.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<import('../types/index.d.ts').HeatmapPoint>} points
+ * @param {import('../types/index.d.ts').HeatmapOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+export function heatmap(input: Buffer, points: Array<import("../types/index.d.ts").HeatmapPoint>, options?: import("../types/index.d.ts").HeatmapOptions): Promise<Buffer>;
+export const MAX_POINTS: 100000;
+//# sourceMappingURL=heatmap.d.ts.map

package/dist/types/compose/heatmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../../../src/compose/heatmap.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH,+BALW,MAAM,UACN,KAAK,CAAC,OAAO,qBAAqB,EAAE,YAAY,CAAC,YACjD,OAAO,qBAAqB,EAAE,cAAc,GAC1C,OAAO,CAAC,MAAM,CAAC,CA0D3B;AAzED,yBAAmB,MAAO,CAAC"}

package/dist/types/compose/index.d.ts

@@ -0,0 +1,6 @@
+import { annotate } from "./annotate.js";
+import { defaultTheme } from "./theme.js";
+import { diff } from "./diff.js";
+import { heatmap } from "./heatmap.js";
+export { annotate, defaultTheme, diff, heatmap };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/compose/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/compose/index.js"],"names":[],"mappings":""}

package/dist/types/compose/theme.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default annotation theme shipped with the package.
+ *
+ * Implements `spec.md` § 8.3.2. The four severity keys cover the standard
+ * accessibility-issue grading. Consumers can replace any subset by passing
+ * their own theme object to `annotate()`; the function shallow-merges over
+ * this default.
+ *
+ * Color choices target WCAG 2.2 AA when rendered against typical light or
+ * dark page backgrounds. Stroke widths are in CSS px and scale with the
+ * captured image's pixel space.
+ *
+ * @public
+ * @type {Readonly<import('../types/index.d.ts').AnnotationTheme>}
+ */
+export const defaultTheme: Readonly<import("../types/index.d.ts").AnnotationTheme>;
+//# sourceMappingURL=theme.d.ts.map

package/dist/types/compose/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../src/compose/theme.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,2BAFU,QAAQ,CAAC,OAAO,qBAAqB,EAAE,eAAe,CAAC,CA2B9D"}

package/dist/types/errors/adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Base for errors arising at the `PageAdapter` boundary
+ * (third-party browser object integration).
+ *
+ * @public
+ */
+export class AdapterError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * The wrapped third-party page object is missing a method required by the
+ * `PageAdapter` contract (spec § 10). Deterministic — the caller passed the
+ * wrong kind of object.
+ *
+ * @public
+ */
+export class AdapterContractError extends AdapterError {
+}
+/**
+ * The underlying puppeteer / playwright / CDP call threw. Wrapped so consumers
+ * can rely on the package's error shape without sniffing browser-library
+ * internals. Retriable because most browser-API errors are transient.
+ *
+ * @public
+ */
+export class BrowserApiError extends AdapterError {
+}
+import { ScreenshotUtilsError } from "./base.js";
+//# sourceMappingURL=adapter.d.ts.map

package/dist/types/errors/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/errors/adapter.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;;;GAMG;AACH;CAUC;AAED;;;;;;GAMG;AACH;CAUC"}

package/dist/types/errors/base.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Abstract base class for all errors thrown by `@afixt/screenshot-utils`.
+ *
+ * Concrete subclasses must:
+ * - set a stable `code` string (machine-readable; never localized)
+ * - set `retriable: true` only when a consumer-side retry has a chance of succeeding
+ *   without operator intervention (transient browser timeouts, transport blips, etc.)
+ * - never include PII in `context`. The platform privacy rules in
+ *   the parent CLAUDE.md forbid logging user data; the same applies to
+ *   error payloads since they are commonly logged verbatim.
+ *
+ * See `spec.md` § 14 for the full error model.
+ *
+ * @public
+ */
+export class ScreenshotUtilsError extends Error {
+    /**
+     * Construct an error. Subclasses set `code` and `retriable`; callers may
+     * supply `reason`, `cause`, and `context`.
+     *
+     * @param {string} message Human-readable summary. Should not include PII.
+     * @param {object} [options]
+     * @param {string} [options.reason] Sub-classification (enum string) — see spec § 14.3.
+     * @param {Error}  [options.cause]  Underlying error being wrapped, preserved for stack traces.
+     * @param {Record<string, unknown>} [options.context] Structured debug data. NO PII.
+     */
+    constructor(message: string, { reason, cause, context }?: {
+        reason?: string | undefined;
+        cause?: Error | undefined;
+        context?: Record<string, unknown> | undefined;
+    });
+    code: string;
+    retriable: boolean;
+    reason: string | undefined;
+    context: Record<string, unknown> | undefined;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/types/errors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/errors/base.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;;;;;;;OASG;IACH,qBANW,MAAM,+BAEd;QAAyB,MAAM;QACN,KAAK;QACY,OAAO;KACnD,EAiBA;IAXG,aAAoC;IACpC,mBAAsB;IAElB,2BAAoB;IAGpB,6CAAsB;CAMjC"}

package/dist/types/errors/capture.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Base for any error arising during the capture phase
+ * (browser interaction, scroll, settle, screenshot).
+ *
+ * @public
+ */
+export class CaptureError extends ScreenshotUtilsError {
+}
+/**
+ * The browser context is unreachable (process crashed, pool exhausted, etc.).
+ * Retriable because the consumer may obtain a fresh browser context.
+ *
+ * @public
+ */
+export class BrowserUnavailableError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * Document scrollHeight exceeds the configured `maxHeight` ceiling.
+ *
+ * @public
+ */
+export class PageTooTallError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * The requested selector / xpath returned no DOM node.
+ *
+ * @public
+ */
+export class ElementNotFoundError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * The element exists but has zero size or is hidden from layout.
+ *
+ * @public
+ */
+export class ElementNotVisibleError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * A verification snippet was provided but the live DOM did not match.
+ *
+ * @public
+ */
+export class ElementMismatchError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * Element dimensions exceed `maxDimensions` (default 4000×4000 CSS px).
+ *
+ * @public
+ */
+export class ElementTooLargeError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * `waitForStable` exceeded its `maxWait`. The page was still settling.
+ * Retriable because subsequent calls may catch a stable frame.
+ *
+ * @public
+ */
+export class StabilityTimeoutError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * The underlying browser screenshot call exceeded the configured `timeout`.
+ * Retriable for the same reasons as StabilityTimeoutError.
+ *
+ * @public
+ */
+export class CaptureTimeoutError extends CaptureError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+import { ScreenshotUtilsError } from "./base.js";
+//# sourceMappingURL=capture.d.ts.map

package/dist/types/errors/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/errors/capture.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;CAaC;AAED;;;;;GAKG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;;GAKG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;;GAKG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ"}

package/dist/types/errors/compose.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Base for errors arising during composition (annotate, heatmap, diff, composite).
+ *
+ * @public
+ */
+export class ComposeError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * `diff()` was called with two images whose dimensions don't match.
+ *
+ * @public
+ */
+export class DimensionMismatchError extends ComposeError {
+}
+/**
+ * An annotation theme is missing a required key or has invalid values.
+ *
+ * @public
+ */
+export class ThemeError extends ComposeError {
+}
+/**
+ * A heatmap point is malformed (e.g., missing x/y, negative weight, NaN).
+ *
+ * @public
+ */
+export class HeatmapPointError extends ComposeError {
+}
+import { ScreenshotUtilsError } from "./base.js";
+//# sourceMappingURL=compose.d.ts.map

package/dist/types/errors/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/errors/compose.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;CAUC;AAED;;;;GAIG;AACH;CAUC;AAED;;;;GAIG;AACH;CAUC"}

package/dist/types/errors/index.d.ts

@@ -0,0 +1,29 @@
+import { ScreenshotUtilsError } from "./base.js";
+import { CaptureError } from "./capture.js";
+import { BrowserUnavailableError } from "./capture.js";
+import { PageTooTallError } from "./capture.js";
+import { ElementNotFoundError } from "./capture.js";
+import { ElementNotVisibleError } from "./capture.js";
+import { ElementMismatchError } from "./capture.js";
+import { ElementTooLargeError } from "./capture.js";
+import { StabilityTimeoutError } from "./capture.js";
+import { CaptureTimeoutError } from "./capture.js";
+import { TransformError } from "./transform.js";
+import { InvalidRectError } from "./transform.js";
+import { UnsupportedFormatError } from "./transform.js";
+import { BufferCorruptError } from "./transform.js";
+import { ComposeError } from "./compose.js";
+import { DimensionMismatchError } from "./compose.js";
+import { ThemeError } from "./compose.js";
+import { HeatmapPointError } from "./compose.js";
+import { TileError } from "./tile.js";
+import { TileSizeError } from "./tile.js";
+import { TileWriteError } from "./tile.js";
+import { RedactionError } from "./redaction.js";
+import { PolicyError } from "./redaction.js";
+import { AdapterError } from "./adapter.js";
+import { AdapterContractError } from "./adapter.js";
+import { BrowserApiError } from "./adapter.js";
+import { OptionalDependencyMissingError } from "./optional.js";
+export { ScreenshotUtilsError, CaptureError, BrowserUnavailableError, PageTooTallError, ElementNotFoundError, ElementNotVisibleError, ElementMismatchError, ElementTooLargeError, StabilityTimeoutError, CaptureTimeoutError, TransformError, InvalidRectError, UnsupportedFormatError, BufferCorruptError, ComposeError, DimensionMismatchError, ThemeError, HeatmapPointError, TileError, TileSizeError, TileWriteError, RedactionError, PolicyError, AdapterError, AdapterContractError, BrowserApiError, OptionalDependencyMissingError };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/index.js"],"names":[],"mappings":""}