@afixt/screenshot-utils 0.9.0

package/src/types/index.d.ts

@@ -0,0 +1,432 @@
+/**
+ * @afixt/screenshot-utils — public TypeScript type definitions.
+ *
+ * Mirror of the contract in `spec.md` §§ 8, 9, 10, 11, 14. All coordinates
+ * are CSS pixels unless explicitly labelled "device pixels".
+ *
+ * Implementation files reference these via JSDoc `@typedef` import:
+ *
+ *     /** @typedef {import('./types').Rect} Rect *\/
+ */
+
+import type { Readable } from 'node:stream';
+
+// ─── Geometry & primitives ────────────────────────────────────────────────────
+
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export interface Point {
+    x: number;
+    y: number;
+}
+
+export interface Viewport {
+    width: number;
+    height: number;
+    /** Default 1. */
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+}
+
+export interface PageMetrics {
+    /** `document.documentElement.scrollWidth`. */
+    width: number;
+    /** `document.documentElement.scrollHeight`. */
+    height: number;
+    viewport: Viewport;
+    devicePixelRatio: number;
+    url: string;
+    /** ISO-8601 UTC. */
+    capturedAt: string;
+}
+
+export type Format = 'png' | 'jpeg' | 'webp';
+export type Severity = 'critical' | 'serious' | 'moderate' | 'minor';
+
+// ─── Capture ──────────────────────────────────────────────────────────────────
+
+export type Encoding = 'buffer' | 'stream';
+export type AnimationsPolicy = 'reduce' | 'wait' | 'ignore';
+
+export interface WaitForStableOptions {
+    fonts?: boolean;
+    images?: boolean;
+    animations?: AnimationsPolicy;
+    /** ms; default 5000. */
+    maxWait?: number;
+    /** ms; default 200. */
+    idleMs?: number;
+}
+
+export interface CaptureOptions {
+    format?: Format;
+    /** 1-100; ignored for png. */
+    quality?: number;
+    fullPage?: boolean;
+    omitBackground?: boolean;
+    encoding?: Encoding;
+    /** ms; default 30000. */
+    timeout?: number;
+    waitForStable?: WaitForStableOptions | false;
+    /** Optional EventEmitter-shaped sink for progress events. */
+    events?: { emit(name: string, payload?: unknown): void } | null;
+}
+
+export interface CaptureTiming {
+    settleMs: number;
+    captureMs: number;
+    encodeMs: number;
+    totalMs: number;
+}
+
+export interface CaptureResult {
+    format: Format;
+    bytes: Buffer | Readable;
+    page: PageMetrics;
+    timing: CaptureTiming;
+    /** Non-fatal warnings (e.g., font-load timeout). */
+    warnings: string[];
+}
+
+export interface ElementCaptureOptions extends CaptureOptions {
+    selector?: string;
+    xpath?: string;
+    /** Optional outerHTML verification snippet. */
+    snippet?: string;
+    /** Default 10. */
+    padding?: number;
+    maxDimensions?: { width: number; height: number };
+    scrollIntoView?: boolean;
+}
+
+export interface ElementCaptureResult extends CaptureResult {
+    element: {
+        selector: string;
+        xpath: string;
+        documentRect: Rect;
+        viewportRect: Rect;
+        verified: boolean;
+        verificationReason?: string;
+    };
+    /** Per spec § 8.1.3, failure mode: bytes=null + reason populated. */
+    reason?: string;
+}
+
+export interface LongPageCaptureOptions extends CaptureOptions {
+    /** null → use viewport height. */
+    stripHeight?: number | null;
+    overlap?: number;
+    maxHeight?: number;
+    /** Pause between scroll and capture, ms; default 100. */
+    scrollSettleMs?: number;
+}
+
+export type ResponsiveCaptureMode = 'fullPage' | 'viewport' | 'longPage';
+
+export interface NamedViewport extends Viewport {
+    name: string;
+}
+
+export interface ResponsiveCaptureOptions extends CaptureOptions {
+    viewports: NamedViewport[];
+    reloadBetween?: boolean;
+    captureMode?: ResponsiveCaptureMode;
+    /** Default 1. >1 requires multiple browser contexts. */
+    parallelism?: number;
+}
+
+export interface ResponsiveCaptureResult {
+    captures: Array<CaptureResult & { viewportName: string }>;
+    capturedAt: string;
+    totalMs: number;
+}
+
+export interface StabilityReport {
+    fonts: 'ready' | 'timeout' | 'skipped';
+    images: { total: number; loaded: number; failed: number };
+    animations: 'none' | 'reduced' | 'settled' | 'timeout' | 'skipped';
+    totalMs: number;
+}
+
+// ─── Transform ────────────────────────────────────────────────────────────────
+
+export interface CropOptions {
+    padding?: number;
+    format?: Format;
+    quality?: number;
+}
+
+export interface CropManyEntry {
+    id: string;
+    rect: Rect;
+}
+
+export type CropManyOptions = CropOptions & {
+    /** Default 4. */
+    parallelism?: number;
+};
+
+export interface ResizeOptions {
+    width?: number;
+    height?: number;
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    position?: string;
+    kernel?: 'nearest' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3';
+    withoutEnlargement?: boolean;
+    format?: Format;
+    quality?: number;
+}
+
+export interface ConvertOptions {
+    format: Format;
+    quality?: number;
+    lossless?: boolean;
+    /** sharp webp/avif effort, 0-6. */
+    effort?: number;
+}
+
+export interface NormalizeOptions {
+    /** Normalize from this DPR; default: image's intrinsic DPR. */
+    fromDpr?: number;
+    /** Target DPR; default 1 (CSS pixel space). */
+    toDpr?: number;
+}
+
+export interface NormalizeResult {
+    buffer: Buffer;
+    dimensions: { width: number; height: number };
+}
+
+// ─── Compose ──────────────────────────────────────────────────────────────────
+
+export interface AnnotationStyle {
+    stroke: string;
+    strokeWidth: number;
+    fill?: string;
+    badge?: { bg: string; fg: string };
+}
+
+export type AnnotationTheme = Record<string, AnnotationStyle>;
+
+export interface Annotation {
+    rect: Rect;
+    /** Theme key, e.g., 'severity-critical'. */
+    style: string;
+    /** Optional letter/number badge. */
+    label?: string;
+    /** Not rendered to raster; appears in SVG output only. */
+    tooltip?: string;
+}
+
+export interface AnnotateOptions {
+    theme?: AnnotationTheme;
+    output?: 'png' | 'svg';
+    legend?: 'none' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+
+export interface HeatmapPoint {
+    x: number;
+    y: number;
+    /** Default 1. */
+    weight?: number;
+}
+
+export interface HeatmapOptions {
+    /** Kernel radius in CSS px; default 40. */
+    radius?: number;
+    /** Alpha multiplier; default 0.7. */
+    intensity?: number;
+    colorScale?: 'viridis' | 'magma' | 'severity' | ((t: number) => [number, number, number]);
+    blendMode?: 'overlay' | 'screen' | 'multiply';
+}
+
+export interface DiffOptions {
+    /** pixelmatch threshold; default 0.1. */
+    threshold?: number;
+    includeAA?: boolean;
+    alpha?: number;
+    diffColor?: [number, number, number];
+    output?: 'overlay' | 'side-by-side' | 'mask-only';
+}
+
+export interface DiffResult {
+    diffBuffer: Buffer;
+    changedPixels: number;
+    totalPixels: number;
+    percentChanged: number;
+    bbox?: Rect;
+    /** Optional and expensive; per-cluster bboxes. */
+    regions?: Rect[];
+}
+
+// ─── Tile (DZI) ───────────────────────────────────────────────────────────────
+
+export type DziTileFormat = 'png' | 'jpeg' | 'webp';
+export type DziOutput = 'buffers' | 'directory' | 'stream';
+
+export interface TileDziOptions {
+    /** 256 or 512. Default 256. */
+    tileSize?: 256 | 512;
+    /** Px overlap between tiles; default 1. */
+    overlap?: number;
+    tileFormat?: DziTileFormat;
+    quality?: number;
+    output?: DziOutput;
+    /** When output: 'directory', subdir name in the temp dir. */
+    name?: string;
+}
+
+export interface DziTile {
+    level: number;
+    col: number;
+    row: number;
+    /** Relative path within the DZI tree. */
+    path: string;
+    bytes?: Buffer;
+    stream?: Readable;
+}
+
+export interface DziDescriptor {
+    /** Serialized .dzi XML. */
+    xml: string;
+    format: DziTileFormat;
+    width: number;
+    height: number;
+    tileSize: number;
+    overlap: number;
+}
+
+export interface DziResult {
+    descriptor: DziDescriptor;
+    tiles: DziTile[];
+    outputDir?: string;
+    totalBytes: number;
+    totalTiles: number;
+}
+
+// ─── Redaction ────────────────────────────────────────────────────────────────
+
+export type RedactMode = 'blur' | 'mask' | 'pixelate';
+
+export interface RedactRegion {
+    rect: Rect;
+    mode?: RedactMode;
+    /** For mode: 'blur'. */
+    radius?: number;
+    /** For mode: 'mask'. CSS color string. */
+    color?: string;
+    /** For mode: 'pixelate'. */
+    cellSize?: number;
+}
+
+export interface RedactOptions {
+    default?: RedactMode;
+    defaultRadius?: number;
+}
+
+export interface PiiPolicy {
+    inputTypes?: string[];
+    customSelectors?: string[];
+    mode: RedactMode;
+    radius?: number;
+    cellSize?: number;
+    color?: string;
+}
+
+// ─── Adapter contract (spec § 10) ─────────────────────────────────────────────
+
+export interface AdapterCapabilities {
+    /** Browser limit, e.g., 16384 for Chrome. */
+    screenshotMaxHeight: number;
+    supportsViewportEmulation: boolean;
+    supportsCDP: boolean;
+}
+
+export interface ScreenshotOptions {
+    fullPage?: boolean;
+    clip?: Rect;
+    format?: Format;
+    quality?: number;
+    omitBackground?: boolean;
+    encoding?: 'binary' | 'base64';
+}
+
+export interface PageAdapter {
+    screenshot(opts: ScreenshotOptions): Promise<Buffer>;
+    evaluate<T>(fn: (...args: unknown[]) => T, ...args: unknown[]): Promise<T>;
+    scrollTo(point: Point): Promise<void>;
+    getMetrics(): Promise<PageMetrics>;
+    setViewport(viewport: Viewport): Promise<void>;
+    reload(opts?: { waitUntil?: string; timeout?: number }): Promise<void>;
+    readonly capabilities: AdapterCapabilities;
+    readonly label?: string;
+}
+
+// ─── Defaults & utilities ─────────────────────────────────────────────────────
+
+export interface ScreenshotUtilsDefaults {
+    readonly format: Format;
+    readonly quality: number;
+    readonly fullPage: boolean;
+    readonly timeout: number;
+    readonly padding: number;
+    readonly stripHeight: number | null;
+    readonly tileSize: number;
+    readonly tileOverlap: number;
+    readonly tileFormat: DziTileFormat;
+    readonly tileQuality: number;
+    readonly waitForStable: Required<WaitForStableOptions>;
+}
+
+export declare const defaults: ScreenshotUtilsDefaults;
+export declare const version: string;
+
+// ─── Error shape (spec § 14.2) ────────────────────────────────────────────────
+
+export interface ScreenshotUtilsErrorShape extends Error {
+    name: string;
+    /** Stable, machine-readable. */
+    code: string;
+    /** Sub-classification enum. */
+    reason?: string;
+    cause?: Error;
+    /** Structured debug data — never includes PII. */
+    context?: Record<string, unknown>;
+    retriable: boolean;
+}
+
+// Concrete error class names. Importers may use these as type guards via instanceof.
+export type ScreenshotUtilsErrorName =
+    | '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';