@vizzly-testing/honeydiff 0.14.0 → 0.16.0

package/index.d.ts

@@ -1,878 +1,256 @@
-/**
- * TypeScript definitions for @vizzly-testing/honeydiff
- * High-performance image diffing for Node.js
- */
+/** Data-only Node.js API for Honeydiff image analysis. */
 
-// ============================================================================
-// Core Types
-// ============================================================================
+export type ImageInput = string | Buffer;
 
-export interface BoundingBox {
-  /** X coordinate of top-left corner */
-  x: number;
-  /** Y coordinate of top-left corner */
-  y: number;
-  /** Width of the bounding box */
+export interface ImageSize {
   width: number;
-  /** Height of the bounding box */
   height: number;
 }
 
-export interface HeightDiff {
-  /** Height of the first image in pixels */
-  height1: number;
-  /** Height of the second image in pixels */
-  height2: number;
-  /** Number of extra pixels due to height difference */
-  extraPixels: number;
+export interface BoundingBox extends ImageSize {
+  x: number;
+  y: number;
 }
 
-export interface DiffPixel {
-  /** X coordinate of the differing pixel */
+export interface Centroid {
   x: number;
-  /** Y coordinate of the differing pixel */
   y: number;
-  /** Intensity of the difference (0-255, higher = more different) */
-  intensity: number;
 }
 
-export interface IntensityStats {
-  /** Maximum difference intensity observed (0-255) */
-  max: number;
-  /** Minimum difference intensity observed (0-255) */
+export interface PopulationSummary {
+  count: number;
+  fraction: number;
+  bounds: BoundingBox | null;
+  centroid: Centroid | null;
+}
+
+export interface ComponentSizeSummary {
   min: number;
-  /** Mean (average) difference intensity */
+  max: number;
   mean: number;
-  /** Median difference intensity */
-  median: number;
-  /** Standard deviation of difference intensities */
-  stdDev: number;
+  standardDeviation: number;
 }
 
-export interface DiffCluster {
-  /** Number of pixels in this cluster */
-  pixelCount: number;
-  /** Center of mass [x, y] coordinates */
-  centerOfMass: [number, number];
-  /** Average intensity of differences in this cluster */
-  avgIntensity: number;
-  /** Bounding box containing this cluster */
-  boundingBox: BoundingBox;
+export interface SmallRegionSummary extends PopulationSummary {
+  componentCount: number;
+  componentSizes: ComponentSizeSummary | null;
 }
 
-export interface DiffMaskComponent {
-  /** Number of retained pixels in this exact 8-connected component */
-  pixelCount: number;
-  /** Bitmap-pixel bounds around the component */
-  boundingBox: BoundingBox;
+export interface PixelAnalysis {
+  total: number;
+  renderedEqual: number;
+  suppressed: {
+    belowThreshold: PopulationSummary;
+    antialiasing: PopulationSummary;
+    smallRegions: SmallRegionSummary;
+  };
+  changed: {
+    total: number;
+    visual: number;
+    structural: number;
+    added: number;
+    removed: number;
+  };
 }
 
-export interface DiffMaskEvidence {
-  /** Version of this evidence result shape */
-  contractVersion: string;
-  /** Native identity of normalized options that can change retained pixels */
-  analysisContractHash: string;
-  /** Version of Honeydiff's retained-pixel semantics */
-  semanticsVersion: string;
-  /** Version of the connected-component semantics */
-  componentSemanticsVersion: string;
-  /** Bitmap coordinate-space version */
-  coordinateSpaceVersion: string;
-  /** Diff-mask width in bitmap pixels */
-  width: number;
-  /** Diff-mask height in bitmap pixels */
-  height: number;
-  /** Number of retained pixels represented by the mask */
+export interface SpatialSummary {
+  bounds: BoundingBox;
   pixelCount: number;
-  /** False when maxDiffs stopped the comparison early */
-  complete: boolean;
-  /** Deterministically ordered exact connected components */
-  components: DiffMaskComponent[];
+  density: number;
+  centroid: Centroid;
+  perimeter: number;
 }
 
-export interface DiffResult {
-  /**
-   * Whether the images are different based on the comparison threshold
-   * Note: This respects minClusterSize filtering - small clusters may be filtered as noise
-   */
-  isDifferent: boolean;
-  /** Percentage of pixels that differ (0.0 - 100.0) */
-  diffPercentage: number;
-  /** Total number of pixels compared */
-  totalPixels: number;
-  /**
-   * Number of pixels that differ (raw count, unaffected by minClusterSize filtering)
-   * Note: This may be > 0 even when isDifferent is false if small clusters were filtered as noise
-   */
-  diffPixels: number;
-  /** Number of retained pixels represented by the diff mask */
-  diffMaskPixels: number;
-  /** False when maxDiffs stopped the scan before the full image was evaluated */
-  diffMaskComplete: boolean;
-  /** Version of the pixel-retention semantics used by the diff mask */
-  maskSemanticsVersion: string;
-  /** Authoritative diff-mask evidence (null unless includeDiffMaskEvidence is enabled) */
-  diffMaskEvidence: DiffMaskEvidence | null;
-  /** Number of pixels ignored due to anti-aliasing detection */
-  aaPixelsIgnored: number;
-  /** Percentage of pixels ignored as anti-aliasing (0.0 - 100.0) */
-  aaPercentage: number;
-  /** Bounding box containing all differences (null if identical) */
-  boundingBox: BoundingBox | null;
-  /** Height difference information (null if same height) */
-  heightDiff: HeightDiff | null;
-  /** List of differing pixels with positions and intensities (null unless includeDiffPixels is enabled) */
-  diffPixelsList: DiffPixel[] | null;
-  /** Clustered groups of connected differing pixels (null unless includeClusters is enabled) */
-  diffClusters: DiffCluster[] | null;
-  /** Statistical metrics about difference intensities (null unless includeDiffPixels is enabled) */
-  intensityStats: IntensityStats | null;
-  /** SSIM score, approximately -1.0 to 1.0 (null unless includeSSIM is enabled) */
-  perceptualScore: number | null;
-  /**
-   * GMSD (Gradient Magnitude Similarity Deviation) score (null unless includeGMSD is enabled)
-   * Lower values (closer to 0.0) indicate more similar images
-   * Typical range: 0.0 to ~0.3 for natural images
-   */
-  gmsdScore: number | null;
+export interface DeltaESummary {
+  sampleCount: number;
+  min: number;
+  max: number;
+  mean: number;
+  standardDeviation: number;
 }
 
-/** Installed @vizzly-testing/honeydiff package version */
-export const version: string;
-
-/** Native diff-mask semantics implemented by this package */
-export const maskSemanticsVersion: string;
-
-// ============================================================================
-// Options
-// ============================================================================
-
-/**
- * Options for merging nearby clusters
- *
- * These heuristics are designed to merge fragmented text regions (like individual
- * characters in a date string) into logical regions while avoiding merging
- * unrelated visual changes.
- *
- * Inspired by the Stroke Width Transform (SWT) text detection algorithm:
- * Epshtein, B., Ofek, E., & Wexler, Y. (2010). "Detecting Text in Natural Scenes
- * with Stroke Width Transform." CVPR 2010.
- */
-export interface ClusterMergeOptions {
-  /**
-   * Maximum horizontal distance to merge clusters in same Y-band (pixels)
-   *
-   * Clusters within this horizontal distance and overlapping Y-ranges
-   * will be merged. Suitable for merging characters in text.
-   * @default 15
-   */
-  horizontalDistance?: number;
+export interface DiffRegion {
+  spatial: SpatialSummary;
+  visualPixels: number;
+  addedPixels: number;
+  removedPixels: number;
+  appearance: DeltaESummary | null;
+}
 
-  /**
-   * Maximum vertical tolerance for "same Y-band" (pixels)
-   *
-   * Clusters with Y-ranges within this tolerance of each other are
-   * considered to be on the same line.
-   * @default 5
-   */
-  yBandTolerance?: number;
+export interface DiffAnalysis {
+  different: boolean;
+  settings: {
+    threshold: number;
+    antialiasing: boolean;
+    minimumRegionPixels: number;
+    alignHeightChanges: boolean;
+  };
+  images: {
+    baseline: ImageSize;
+    current: ImageSize;
+    canvas: ImageSize;
+  };
+  pixels: PixelAnalysis;
+  difference: {
+    fraction: number;
+    spatial: SpatialSummary | null;
+    appearance: DeltaESummary | null;
+    regions: DiffRegion[];
+  };
+  heightChange: {
+    direction: 'added' | 'removed';
+    rowCount: number;
+    startRow: number;
+    alignmentApplied: boolean;
+  } | null;
+}
 
-  /**
-   * Maximum height ratio between clusters to allow merging
-   *
-   * Prevents merging clusters of very different sizes (e.g., a word
-   * with a large image). Based on SWT heuristic.
-   * @default 2.0
-   */
-  maxHeightRatio?: number;
+export interface PerceptionAnalysis {
+  ssim: number;
+  msSsim: number;
+  gmsd: number;
+  measured: {
+    width: number;
+    pairedRows: number;
+    baselineExcludedRows: number;
+    currentExcludedRows: number;
+  };
+}
 
-  /**
-   * Maximum width ratio between clusters to allow merging
-   *
-   * Additional SWT-inspired heuristic to prevent merging dissimilar
-   * regions.
-   * @default 3.0
-   */
-  maxWidthRatio?: number;
+export interface ImageAnalysis {
+  comparison: DiffAnalysis;
+  perception: PerceptionAnalysis;
 }
 
 export interface CompareOptions {
-  /**
-   * Perceptual color difference threshold using CIEDE2000 (Delta E units)
-   *
-   * The CIEDE2000 standard provides intuitive, perceptually uniform thresholds:
-   * - 0.0 = No Delta E tolerance; AA and cluster filtering remain independent
-   * - 1.0 = Just Noticeable Difference (JND) - barely perceptible to trained observers
-   * - 2.0 = Recommended default - ignores sub-pixel rendering variance, catches real differences
-   * - 3.0+ = Permissive - high tolerance for rendering variations
-   *
-   * @default 2.0
-   */
+  /** CIEDE2000 threshold. Default: 2. */
   threshold?: number;
-
-  /**
-   * Enable anti-aliasing detection to ignore AA differences
-   *
-   * Suppression requires a luminance ramp plus strict cross-image evidence that
-   * raster coverage moved to a neighboring pixel. Stable edge recolors remain differences.
-   * @default true
-   */
+  /** Ignore detected raster anti-aliasing movement. Default: true. */
   antialiasing?: boolean;
+  /** Smallest retained 8-connected visual region. Default: 2. */
+  minimumRegionPixels?: number;
+  /** Detect and align one unambiguous inserted or removed row block. Default: false. */
+  alignHeightChanges?: boolean;
+}
 
-  /**
-   * Maximum number of differences to detect before stopping
-   * Capped comparisons classify from observed pixel evidence because early
-   * exit cannot determine whether a complete cluster meets minClusterSize.
-   * @default undefined (unlimited)
-   */
-  maxDiffs?: number;
-
-  /**
-   * Include list of differing pixels with positions and intensities
-   * WARNING: This can use significant memory for images with many differences
-   * @default false
-   */
-  includeDiffPixels?: boolean;
-
-  /**
-   * Include clustered groups of connected differing pixels
-   * Clusters are sorted by size (largest first)
-   * @default false
-   */
-  includeClusters?: boolean;
-
-  /**
-   * Include authoritative diff-mask dimensions, identity, and exact
-   * connected-component facts.
-   * @default false
-   */
-  includeDiffMaskEvidence?: boolean;
-
-  /**
-   * Calculate SSIM (Structural Similarity Index) perceptual score
-   * This metric measures the source images independently of threshold and AA
-   * filtering. Transparent inputs are evaluated over black and white mattes,
-   * keeping the more conservative score.
-   * WARNING: SSIM can use substantial memory on large images.
-   * @default false
-   */
-  includeSSIM?: boolean;
-
-  /**
-   * Calculate GMSD (Gradient Magnitude Similarity Deviation) score
-   *
-   * GMSD is very fast and highly sensitive to edge/structural changes.
-   * Useful for detecting border thickness changes, font weight shifts,
-   * and icon updates.
-   * A score of 0 does not prove image identity; uniform changes can have no
-   * spatial variation in gradient degradation.
-   *
-   * **Note:** For variable-height comparisons, GMSD is calculated on the
-   * overlapping region shared by both images.
-   *
-   * Reference: Xue et al. 2014 - "Gradient Magnitude Similarity Deviation:
-   * A Highly Efficient Perceptual Image Quality Index"
-   *
-   * @default false
-   */
-  includeGMSD?: boolean;
-
-  /**
-   * Minimum cluster size to count as a real difference
-   *
-   * Clusters smaller than this threshold are filtered out as noise.
-   * This helps ignore run-to-run rendering variance (scattered single pixels)
-   * while still catching real visual changes (grouped pixel differences).
-   *
-   * - 1 = Any surviving diff pixel counts
-   * - 2 = Default - filters single isolated pixels as noise
-   * - 3+ = More aggressive noise filtering
-   *
-   * When set to a value > 1, clustering is automatically enabled.
-   * @default 2
-   */
-  minClusterSize?: number;
-
-  /**
-   * Merge nearby clusters into logical regions
-   *
-   * When enabled, nearby clusters are merged using horizontal-biased heuristics
-   * that work well for text regions. This helps consolidate fragmented text
-   * changes (e.g., "2024-01-01" showing as 59 clusters) into logical regions.
-   *
-   * Automatically enables clustering when set.
-   *
-   * @default undefined (no merging)
-   *
-   * @example
-   * ```typescript
-   * // Simple: enable merging with sensible defaults
-   * { clusterMerge: true }
-   *
-   * // Advanced: tune the merging behavior
-   * { clusterMerge: { horizontalDistance: 20, yBandTolerance: 10 } }
-   * ```
-   */
-  clusterMerge?: boolean | ClusterMergeOptions;
-
-  /**
-   * Path to save the diff image (highlighted differences)
-   * @default undefined
-   */
+export interface ArtifactOutput {
   diffPath?: string;
-
-  /**
-   * Path to save the mask image (binary diff mask)
-   * @default undefined
-   */
   maskPath?: string;
-
-  /**
-   * Path to save the overlay image (side-by-side comparison)
-   * @default undefined
-   */
-  overlayPath?: string;
-
-  /**
-   * Whether to overwrite existing output files
-   * @default false
-   */
+  sideBySidePath?: string;
   overwrite?: boolean;
-
-  /**
-   * Color to use for highlighting differences in diff/mask output
-   *
-   * Accepts either:
-   * - Hex string: "ff0000", "#ff0000", "ff0000ff" (with alpha)
-   * - RGBA array: [255, 0, 0] or [255, 0, 0, 255]
-   *
-   * @default "ff0000" (red)
-   *
-   * @example
-   * ```typescript
-   * // Green highlight using hex
-   * { diffMaskColor: "00ff00" }
-   *
-   * // Blue with 50% transparency using RGBA array
-   * { diffMaskColor: [0, 0, 255, 128] }
-   *
-   * // Magenta using hex with #
-   * { diffMaskColor: "#ff00ff" }
-   * ```
-   */
-  diffMaskColor?: string | [number, number, number] | [number, number, number, number];
+  /** Opaque artifact color as six-digit hex or integer RGB channels. */
+  color?: string | [number, number, number];
 }
 
-// ============================================================================
-// Input Types
-// ============================================================================
-
-/** Image input can be a file path or a Buffer containing image data */
-export type ImageInput = string | Buffer;
-
-// ============================================================================
-// API Functions
-// ============================================================================
-
-/**
- * Compare two images asynchronously (recommended)
- * For large screenshots, prefer file path inputs. Buffer inputs are copied
- * before native worker processing begins.
- *
- * @param img1 - First image (file path or Buffer)
- * @param img2 - Second image (file path or Buffer)
- * @param options - Comparison options
- * @returns Promise resolving to detailed diff results
- *
- * @example
- * ```typescript
- * const result = await compare('baseline.png', 'current.png', {
- *   threshold: 2.0,  // CIEDE2000 Delta E (default)
- *   includeSSIM: true
- * });
- *
- * console.log(`Diff: ${result.diffPercentage.toFixed(2)}%`);
- * console.log(`SSIM: ${result.perceptualScore}`);
- * ```
- */
+export const version: string;
 export function compare(
-  img1: ImageInput,
-  img2: ImageInput,
-  options?: CompareOptions
-): Promise<DiffResult>;
-
-/**
- * Quick asynchronous comparison (returns only boolean)
- *
- * @param img1 - First image (file path or Buffer)
- * @param img2 - Second image (file path or Buffer)
- * @returns Promise resolving to true if different, false if identical
- *
- * @example
- * ```typescript
- * if (await quickCompare('baseline.png', 'current.png')) {
- *   console.log('Visual regression detected!');
- * }
- * ```
- */
-export function quickCompare(img1: ImageInput, img2: ImageInput): Promise<boolean>;
-
-/**
- * Compare two images synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- * For most cases, prefer the async compare() function.
- *
- * @param img1 - First image (file path or Buffer)
- * @param img2 - Second image (file path or Buffer)
- * @param options - Comparison options
- * @returns Detailed diff results
- *
- * @example
- * ```typescript
- * const result = compareSync('baseline.png', 'current.png', {
- *   threshold: 3.0,  // More lenient threshold
- *   includeClusters: true
- * });
- *
- * if (result.diffClusters) {
- *   console.log(`Found ${result.diffClusters.length} diff regions`);
- * }
- * ```
- */
+  baseline: ImageInput,
+  current: ImageInput,
+  options?: CompareOptions,
+  output?: ArtifactOutput
+): Promise<DiffAnalysis>;
 export function compareSync(
-  img1: ImageInput,
-  img2: ImageInput,
+  baseline: ImageInput,
+  current: ImageInput,
+  options?: CompareOptions,
+  output?: ArtifactOutput
+): DiffAnalysis;
+export function imagesDiffer(
+  baseline: ImageInput,
+  current: ImageInput,
   options?: CompareOptions
-): DiffResult;
-
-/**
- * Quick synchronous comparison (returns only boolean, blocks event loop)
- *
- * @param img1 - First image (file path or Buffer)
- * @param img2 - Second image (file path or Buffer)
- * @returns true if different, false if identical
- *
- * @example
- * ```typescript
- * if (quickCompareSync('baseline.png', 'current.png')) {
- *   console.log('Images differ');
- * }
- * ```
- */
-export function quickCompareSync(img1: ImageInput, img2: ImageInput): boolean;
-
-// ============================================================================
-// Dimensions API
-// ============================================================================
+): Promise<boolean>;
+export function imagesDifferSync(
+  baseline: ImageInput,
+  current: ImageInput,
+  options?: CompareOptions
+): boolean;
+export function analyze(
+  baseline: ImageInput,
+  current: ImageInput,
+  options?: CompareOptions,
+  output?: ArtifactOutput
+): Promise<ImageAnalysis>;
+export function analyzeSync(
+  baseline: ImageInput,
+  current: ImageInput,
+  options?: CompareOptions,
+  output?: ArtifactOutput
+): ImageAnalysis;
 
 export interface ImageDimensions {
-  /** Image width in pixels */
   width: number;
-  /** Image height in pixels */
   height: number;
 }
-
-export interface ImageMetadata {
-  /** Image width in pixels */
-  width: number;
-  /** Image height in pixels */
-  height: number;
-  /** Size of the image data in bytes */
+export interface ImageMetadata extends ImageDimensions {
   fileSizeBytes: number;
-  /** Detected image format (e.g., "png", "jpeg", "webp") or null if unknown */
   format: string | null;
 }
-
-/**
- * Get image dimensions asynchronously (recommended)
- *
- * Fast utility to retrieve image width and height without loading the full image data.
- * Useful for pre-flight checks before comparison.
- *
- * @param img - Image (file path or Buffer)
- * @returns Promise resolving to { width, height } in pixels
- *
- * @example
- * ```typescript
- * const dims = await getDimensions('screenshot.png');
- * console.log(`Image is ${dims.width}x${dims.height} pixels`);
- * // Output: Image is 1920x1080 pixels
- * ```
- */
-export function getDimensions(img: ImageInput): Promise<ImageDimensions>;
-
-/**
- * Get image dimensions synchronously (blocks event loop)
- *
- * Fast utility to retrieve image width and height without loading the full image data.
- * Use this only when you need blocking behavior.
- *
- * @param img - Image (file path or Buffer)
- * @returns { width, height } in pixels
- *
- * @example
- * ```typescript
- * const dims = getDimensionsSync('screenshot.png');
- * console.log(`Image is ${dims.width}x${dims.height} pixels`);
- * // Output: Image is 1920x1080 pixels
- * ```
- */
-export function getDimensionsSync(img: ImageInput): ImageDimensions;
-
-// ============================================================================
-// Image Metadata API
-// ============================================================================
-
-/**
- * Get image metadata asynchronously (recommended)
- *
- * Retrieves image dimensions, file size, and format detection.
- * Useful for storage tracking and billing purposes.
- *
- * @param img - Image Buffer
- * @returns Promise resolving to ImageMetadata
- *
- * @example
- * ```typescript
- * const buffer = fs.readFileSync('screenshot.png');
- * const metadata = await getImageMetadata(buffer);
- * console.log(`Image: ${metadata.width}x${metadata.height}`);
- * console.log(`Size: ${metadata.fileSizeBytes} bytes`);
- * console.log(`Format: ${metadata.format}`);
- * // Output: Image: 1920x1080
- * //         Size: 245760 bytes
- * //         Format: png
- * ```
- */
-export function getImageMetadata(img: Buffer): Promise<ImageMetadata>;
-
-/**
- * Get image metadata synchronously (blocks event loop)
- *
- * Retrieves image dimensions, file size, and format detection.
- * Use this only when you need blocking behavior.
- *
- * @param img - Image Buffer
- * @returns ImageMetadata
- *
- * @example
- * ```typescript
- * const buffer = fs.readFileSync('screenshot.png');
- * const metadata = getImageMetadataSync(buffer);
- * console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
- * ```
- */
-export function getImageMetadataSync(img: Buffer): ImageMetadata;
-
-/**
- * Get image metadata from file asynchronously (recommended)
- *
- * Retrieves image dimensions, file size (from disk), and format detection.
- * The file size is read from filesystem metadata for accuracy.
- *
- * @param path - Path to the image file
- * @returns Promise resolving to ImageMetadata
- *
- * @example
- * ```typescript
- * const metadata = await getImageMetadataFromFile('screenshot.png');
- * console.log(`Image: ${metadata.width}x${metadata.height}`);
- * console.log(`Size: ${metadata.fileSizeBytes} bytes`);
- * console.log(`Format: ${metadata.format}`);
- * ```
- */
+export function getDimensions(image: ImageInput): Promise<ImageDimensions>;
+export function getDimensionsSync(image: ImageInput): ImageDimensions;
+export function getImageMetadata(image: Buffer): Promise<ImageMetadata>;
+export function getImageMetadataSync(image: Buffer): ImageMetadata;
 export function getImageMetadataFromFile(path: string): Promise<ImageMetadata>;
-
-/**
- * Get image metadata from file synchronously (blocks event loop)
- *
- * Retrieves image dimensions, file size (from disk), and format detection.
- * Use this only when you need blocking behavior.
- *
- * @param path - Path to the image file
- * @returns ImageMetadata
- *
- * @example
- * ```typescript
- * const metadata = getImageMetadataFromFileSync('screenshot.png');
- * console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
- * ```
- */
 export function getImageMetadataFromFileSync(path: string): ImageMetadata;
 
-// ============================================================================
-// Screenshot Contrast Screening API
-// ============================================================================
-
-/**
- * Options for screenshot contrast screening with WCAG color-pair math.
- */
 export interface WcagOptions {
-  /**
-   * Edge detection threshold (0-255)
-   * Differences below this threshold are not considered edges
-   * @default 60
-   */
   edgeThreshold?: number;
-
-  /**
-   * Minimum region size (in pixels)
-   * Regions smaller than this are filtered out to reduce noise
-   * @default 50
-   */
   minRegionSize?: number;
-
-  /**
-   * Maximum contrast threshold
-   * Set above 0 to exclude regions with contrast above this ratio. 0 reports
-   * all detected failures.
-   * @default 0
-   */
   maxContrastThreshold?: number;
-
-  /**
-   * Check WCAG AA color-pair thresholds (4.5:1 for normal text, 3.0:1 for large text)
-   * @default true
-   */
   checkAA?: boolean;
-
-  /**
-   * Check WCAG AAA color-pair thresholds (7.0:1 for normal text, 4.5:1 for large text)
-   * @default false
-   */
   checkAAA?: boolean;
 }
-
-/**
- * A single screenshot contrast warning region.
- */
 export interface ContrastViolation {
-  /** Bounding box containing this warning region */
   boundingBox: BoundingBox;
-
-  /** List of pixel coordinates [x, y] in this warning region */
   pixels: [number, number][];
-
-  /** Center of mass [x, y] of the warning region */
   centerOfMass: [number, number];
-
-  /** Number of pixels in this warning region */
   pixelCount: number;
-
-  /** Foreground color [r, g, b, a] (0-255) */
   foregroundColor: [number, number, number, number];
-
-  /** Background color [r, g, b, a] (0-255) */
   backgroundColor: [number, number, number, number];
-
-  /** Foreground relative luminance (0.0-1.0, sRGB) */
   foregroundLuminance: number;
-
-  /** Background relative luminance (0.0-1.0, sRGB) */
   backgroundLuminance: number;
-
-  /** Average contrast ratio for this region (1.0-21.0) */
   contrastRatio: number;
-
-  /** Minimum contrast ratio in this region (worst case) */
   minContrastRatio: number;
-
-  /** Maximum contrast ratio in this region (best case) */
   maxContrastRatio: number;
-
-  /** Whether this region fails WCAG AA for normal text (< 4.5:1) */
   failsAaNormal: boolean;
-
-  /** Whether this region fails WCAG AA for large text (< 3.0:1) */
   failsAaLarge: boolean;
-
-  /** Whether this region fails WCAG AAA for normal text (< 7.0:1) */
   failsAaaNormal: boolean;
-
-  /** Whether this region fails WCAG AAA for large text (< 4.5:1) */
   failsAaaLarge: boolean;
 }
-
-/**
- * Complete screenshot contrast screening result.
- */
 export interface WcagAnalysis {
-  /** Total number of edges analyzed */
   totalEdges: number;
-
-  /** Number of edges passing WCAG AA for normal text */
   aaNormalPass: number;
-
-  /** Number of edges passing WCAG AA for large text */
   aaLargePass: number;
-
-  /** Number of edges passing WCAG AAA for normal text */
   aaaNormalPass: number;
-
-  /** Number of edges passing WCAG AAA for large text */
   aaaLargePass: number;
-
-  /** List of contrast warning regions found */
   violations: ContrastViolation[];
-
-  /** Percentage of edges passing WCAG AA for normal text (0.0-100.0) */
   aaNormalPassPercentage: number;
-
-  /** Percentage of edges passing WCAG AA for large text (0.0-100.0) */
   aaLargePassPercentage: number;
-
-  /** Percentage of edges passing WCAG AAA for normal text (0.0-100.0) */
   aaaNormalPassPercentage: number;
-
-  /** Percentage of edges passing WCAG AAA for large text (0.0-100.0) */
   aaaLargePassPercentage: number;
 }
-
-/**
- * Screen screenshot contrast warnings asynchronously (recommended)
- *
- * Detects color boundaries in an image and measures each color pair with the
- * WCAG contrast formula. Treat results as screening warnings, not full WCAG
- * conformance, because screenshots do not expose text size, boldness, DOM
- * foreground/background, compositing, or semantic roles.
- *
- * @param img - Image to analyze (file path or Buffer)
- * @param options - Screenshot contrast screening options
- * @returns Promise resolving to detailed screenshot contrast screening result
- *
- * @example
- * ```typescript
- * const analysis = await analyzeWcagContrast('screenshot.png', {
- *   edgeThreshold: 60,
- *   checkAA: true,
- *   checkAAA: true
- * });
- *
- * console.log(`Total edges: ${analysis.totalEdges}`);
- * console.log(`AA pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
- * console.log(`Found ${analysis.violations.length} violations`);
- *
- * for (let violation of analysis.violations.slice(0, 5)) {
- *   console.log(`Region at (${violation.boundingBox.x}, ${violation.boundingBox.y})`);
- *   console.log(`  Contrast: ${violation.contrastRatio.toFixed(2)}:1`);
- *   console.log(`  Fails AA: ${violation.failsAaNormal}`);
- * }
- * ```
- */
-export function analyzeWcagContrast(img: ImageInput, options?: WcagOptions): Promise<WcagAnalysis>;
-
-/**
- * Screen screenshot contrast warnings synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- * For most cases, prefer the async analyzeWcagContrast() function.
- *
- * @param img - Image to analyze (file path or Buffer)
- * @param options - Screenshot contrast screening options
- * @returns Detailed screenshot contrast screening result
- *
- * @example
- * ```typescript
- * const analysis = analyzeWcagContrastSync('screenshot.png', {
- *   minRegionSize: 50
- * });
- *
- * if (analysis.violations.length > 0) {
- *   console.log('Accessibility issues found!');
- * }
- * ```
- */
-export function analyzeWcagContrastSync(img: ImageInput, options?: WcagOptions): WcagAnalysis;
-
-/**
- * Options for saving WCAG overlay images
- */
 export interface WcagOutputOptions {
-  /**
-   * Highlight color for violations [r, g, b, a] (0-255)
-   * @default [255, 0, 0, 180] (semi-transparent red)
-   */
   highlightColor?: [number, number, number, number];
-
-  /**
-   * Whether to overwrite existing output file
-   * @default false
-   */
   overwrite?: boolean;
 }
-
-/**
- * Save WCAG violation overlay image asynchronously (recommended)
- *
- * Generates an image with contrast violations highlighted in red (or custom color).
- * Useful for visual debugging of accessibility issues.
- *
- * @param img - Original image (file path or Buffer)
- * @param analysis - Screenshot contrast screening result from analyzeWcagContrast()
- * @param outputPath - Path to save the overlay image
- * @param options - Output options
- * @returns Promise that resolves when the file is saved
- *
- * @example
- * ```typescript
- * const analysis = await analyzeWcagContrast('screenshot.png');
- *
- * await saveWcagOverlay(
- *   'screenshot.png',
- *   analysis,
- *   'violations-overlay.png',
- *   { highlightColor: [255, 0, 0, 180] }
- * );
- *
- * console.log('Overlay saved to violations-overlay.png');
- * ```
- */
+export function analyzeWcagContrast(
+  image: ImageInput,
+  options?: WcagOptions
+): Promise<WcagAnalysis>;
+export function analyzeWcagContrastSync(image: ImageInput, options?: WcagOptions): WcagAnalysis;
 export function saveWcagOverlay(
-  img: ImageInput,
+  image: ImageInput,
   analysis: WcagAnalysis,
   outputPath: string,
   options?: WcagOutputOptions
 ): Promise<void>;
-
-/**
- * Save WCAG violation overlay image synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- * For most cases, prefer the async saveWcagOverlay() function.
- *
- * @param img - Original image (file path or Buffer)
- * @param analysis - Screenshot contrast screening result from analyzeWcagContrastSync()
- * @param outputPath - Path to save the overlay image
- * @param options - Output options
- *
- * @example
- * ```typescript
- * const analysis = analyzeWcagContrastSync('screenshot.png');
- * saveWcagOverlaySync('screenshot.png', analysis, 'violations.png');
- * ```
- */
 export function saveWcagOverlaySync(
-  img: ImageInput,
+  image: ImageInput,
   analysis: WcagAnalysis,
   outputPath: string,
   options?: WcagOutputOptions
 ): void;
 
-// ============================================================================
-// Color Vision Deficiency (CVD) Simulation API
-// ============================================================================
-
-/**
- * Types of color vision deficiency (color blindness) that can be simulated.
- *
- * - `protanopia` - Red-blind (~1% of males). Reds appear dark/muddy, red-green confusion.
- * - `deuteranopia` - Green-blind (~1% of males, most common). Greens shift toward red/brown.
- * - `tritanopia` - Blue-blind (~0.003% of population). Blues appear greenish, yellow-purple confusion.
- * - `achromatopsia` - Complete color blindness (very rare). Only luminance is perceived.
- *
- * Short aliases are also accepted: `protan`, `deutan`, `tritan`, `achroma`, `monochromacy`
- */
 export type ColorBlindnessType =
   | 'protanopia'
   | 'deuteranopia'
@@ -883,456 +261,71 @@ export type ColorBlindnessType =
   | 'tritan'
   | 'achroma'
   | 'monochromacy';
-
-/**
- * Information about a color blindness type
- */
 export interface ColorBlindnessTypeInfo {
-  /** The canonical type identifier (e.g., "protanopia") */
   type: string;
-  /** Human-readable name (e.g., "Protanopia") */
   name: string;
-  /** Description of what colors are affected */
   description: string;
-  /** Approximate prevalence in the population */
   prevalence: string;
 }
-
-/**
- * Comprehensive screenshot contrast screening report for all color vision deficiency types.
- *
- * Contains contrast screening for normal vision and all three main types
- * of dichromatic color blindness (protanopia, deuteranopia, tritanopia).
- */
 export interface CvdWcagReport {
-  /** Contrast screening for normal (typical) color vision */
   normalVision: WcagAnalysis;
-
-  /** Contrast screening simulating protanopia (red-blind) */
   protanopia: WcagAnalysis;
-
-  /** Contrast screening simulating deuteranopia (green-blind) */
   deuteranopia: WcagAnalysis;
-
-  /** Contrast screening simulating tritanopia (blue-blind) */
   tritanopia: WcagAnalysis;
-
-  /** Whether any CVD type has violations */
   hasAnyViolations: boolean;
-
-  /** Total number of violations across all CVD types */
   totalViolations: number;
-
-  /**
-   * Estimated count of violations unique to colorblind users.
-   * These are violations present in CVD analysis but not in normal vision.
-   */
   cvdOnlyViolationCount: number;
 }
-
-/**
- * Simulate color blindness for an image asynchronously (recommended)
- *
- * Transforms the input image to show how it appears to someone with the
- * specified type of color vision deficiency. Complete dichromacy uses the
- * piecewise Brettel, Viénot & Mollon 1997 LMS projection model.
- *
- * @param img - Image to transform (file path or Buffer)
- * @param cvdType - Type of color blindness to simulate
- * @returns Promise resolving to a Buffer containing the simulated PNG image
- *
- * @example
- * ```typescript
- * import { simulateColorBlindness } from '@vizzly-testing/honeydiff';
- * import fs from 'fs';
- *
- * // Simulate how an image appears to someone with red-green color blindness
- * const simulated = await simulateColorBlindness('chart.png', 'deuteranopia');
- *
- * // Save the result
- * fs.writeFileSync('chart-deuteranopia.png', simulated);
- *
- * // Or use directly with image comparison
- * const result = await compare('chart.png', simulated);
- * ```
- */
 export function simulateColorBlindness(
-  img: ImageInput,
-  cvdType: ColorBlindnessType
+  image: ImageInput,
+  type: ColorBlindnessType
 ): Promise<Buffer>;
-
-/**
- * Simulate color blindness for an image synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- * For most cases, prefer the async simulateColorBlindness() function.
- *
- * @param img - Image to transform (file path or Buffer)
- * @param cvdType - Type of color blindness to simulate
- * @returns Buffer containing the simulated PNG image
- *
- * @example
- * ```typescript
- * const simulated = simulateColorBlindnessSync('button.png', 'protanopia');
- * fs.writeFileSync('button-protanopia.png', simulated);
- * ```
- */
-export function simulateColorBlindnessSync(img: ImageInput, cvdType: ColorBlindnessType): Buffer;
-
-/**
- * Simulate and save color blindness image to file asynchronously (recommended)
- *
- * Convenience function that simulates CVD and saves the output in one step.
- *
- * @param img - Image to transform (file path or Buffer)
- * @param cvdType - Type of color blindness to simulate
- * @param outputPath - Path where the simulated image should be saved
- * @returns Promise that resolves when the file is saved
- *
- * @example
- * ```typescript
- * // Save a single simulation
- * await saveColorBlindnessSimulation('ui.png', 'deuteranopia', 'ui-deutan.png');
- *
- * // Generate simulations for all types you care about
- * for (const type of ['protanopia', 'deuteranopia', 'tritanopia']) {
- *   await saveColorBlindnessSimulation('ui.png', type, `ui-${type}.png`);
- * }
- * ```
- */
+export function simulateColorBlindnessSync(image: ImageInput, type: ColorBlindnessType): Buffer;
 export function saveColorBlindnessSimulation(
-  img: ImageInput,
-  cvdType: ColorBlindnessType,
+  image: ImageInput,
+  type: ColorBlindnessType,
   outputPath: string
 ): Promise<void>;
-
-/**
- * Simulate and save color blindness image to file synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- *
- * @param img - Image to transform (file path or Buffer)
- * @param cvdType - Type of color blindness to simulate
- * @param outputPath - Path where the simulated image should be saved
- *
- * @example
- * ```typescript
- * saveColorBlindnessSimulationSync('chart.png', 'tritanopia', 'chart-tritan.png');
- * ```
- */
 export function saveColorBlindnessSimulationSync(
-  img: ImageInput,
-  cvdType: ColorBlindnessType,
+  image: ImageInput,
+  type: ColorBlindnessType,
   outputPath: string
 ): void;
-
-/**
- * Generate and save all CVD simulations to files asynchronously (recommended)
- *
- * Generates simulated images for all CVD types (protanopia, deuteranopia,
- * tritanopia, achromatopsia), saving each with a suffix indicating the type.
- *
- * @param img - Image to transform (file path or Buffer)
- * @param outputPrefix - Base path for output files (without extension)
- * @param extension - File extension to use (default: "png")
- * @returns Promise that resolves when all files are saved
- *
- * @example
- * ```typescript
- * // Creates: dashboard_protanopia.png, dashboard_deuteranopia.png,
- * //          dashboard_tritanopia.png, dashboard_achromatopsia.png
- * await saveAllColorBlindnessSimulations('dashboard.png', 'dashboard', 'png');
- *
- * // With different extension
- * await saveAllColorBlindnessSimulations('ui.png', './artifacts/ui', 'jpg');
- * ```
- */
 export function saveAllColorBlindnessSimulations(
-  img: ImageInput,
+  image: ImageInput,
   outputPrefix: string,
   extension?: string
 ): Promise<void>;
-
-/**
- * Generate and save all CVD simulations to files synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- *
- * @param img - Image to transform (file path or Buffer)
- * @param outputPrefix - Base path for output files (without extension)
- * @param extension - File extension to use (default: "png")
- *
- * @example
- * ```typescript
- * saveAllColorBlindnessSimulationsSync('button.png', 'button');
- * ```
- */
 export function saveAllColorBlindnessSimulationsSync(
-  img: ImageInput,
+  image: ImageInput,
   outputPrefix: string,
   extension?: string
 ): void;
-
-/**
- * Screen contrast for a specific color blindness type asynchronously (recommended)
- *
- * Simulates the image as seen by someone with the specified color vision
- * deficiency, then runs screenshot contrast screening with WCAG color-pair
- * math. This finds detected color-pair warnings that only appear for
- * colorblind users.
- *
- * @param img - Image to analyze (file path or Buffer)
- * @param cvdType - Type of color blindness to simulate
- * @param options - Screenshot contrast screening options
- * @returns Promise resolving to screening results for the simulated image
- *
- * @example
- * ```typescript
- * // Check if colors are distinguishable for deuteranopia users
- * const analysis = await analyzeWcagForCvd('ui.png', 'deuteranopia', {
- *   checkAA: true,
- *   checkAAA: false
- * });
- *
- * if (analysis.violations.length > 0) {
- *   console.log(`Found ${analysis.violations.length} contrast issues`);
- *   console.log('for users with red-green color blindness');
- * }
- * ```
- */
 export function analyzeWcagForCvd(
-  img: ImageInput,
-  cvdType: ColorBlindnessType,
+  image: ImageInput,
+  type: ColorBlindnessType,
   options?: WcagOptions
 ): Promise<WcagAnalysis>;
-
-/**
- * Screen contrast for a specific color blindness type synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- *
- * @param img - Image to analyze (file path or Buffer)
- * @param cvdType - Type of color blindness to simulate
- * @param options - Screenshot contrast screening options
- * @returns Screening results for the simulated image
- *
- * @example
- * ```typescript
- * const analysis = analyzeWcagForCvdSync('chart.png', 'protanopia');
- * console.log(`Pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
- * ```
- */
 export function analyzeWcagForCvdSync(
-  img: ImageInput,
-  cvdType: ColorBlindnessType,
+  image: ImageInput,
+  type: ColorBlindnessType,
   options?: WcagOptions
 ): WcagAnalysis;
-
-/**
- * Screen contrast for all CVD types asynchronously (recommended)
- *
- * Runs screenshot contrast screening for normal vision and all three main
- * types of dichromatic color blindness.
- *
- * @param img - Image to analyze (file path or Buffer)
- * @param options - Screenshot contrast screening options (same options used for all analyses)
- * @returns Promise resolving to a report containing screening results for each vision type
- *
- * @example
- * ```typescript
- * const report = await analyzeWcagAllCvd('dashboard.png', {
- *   checkAA: true,
- *   checkAAA: true
- * });
- *
- * console.log('Contrast Screening Report:');
- * console.log(`Normal vision warnings: ${report.normalVision.violations.length}`);
- * console.log(`Protanopia warnings: ${report.protanopia.violations.length}`);
- * console.log(`Deuteranopia warnings: ${report.deuteranopia.violations.length}`);
- * console.log(`Tritanopia warnings: ${report.tritanopia.violations.length}`);
- *
- * if (report.hasAnyViolations) {
- *   console.log(`\nTotal issues found: ${report.totalViolations}`);
- *   console.log(`Issues only affecting colorblind users: ~${report.cvdOnlyViolationCount}`);
- * }
- * ```
- */
-export function analyzeWcagAllCvd(img: ImageInput, options?: WcagOptions): Promise<CvdWcagReport>;
-
-/**
- * Screen contrast for all CVD types synchronously (blocks event loop)
- *
- * Use this only when you need blocking behavior.
- *
- * @param img - Image to analyze (file path or Buffer)
- * @param options - Screenshot contrast screening options
- * @returns Report containing screening results for each vision type
- *
- * @example
- * ```typescript
- * const report = analyzeWcagAllCvdSync('ui.png');
- *
- * if (report.hasAnyViolations) {
- *   console.log('Contrast warnings detected!');
- * }
- * ```
- */
-export function analyzeWcagAllCvdSync(img: ImageInput, options?: WcagOptions): CvdWcagReport;
-
-/**
- * Get metadata about all supported color blindness types
- *
- * Returns information about each CVD type including name, description,
- * and prevalence. Useful for building UI selectors or generating reports.
- *
- * @returns Array of color blindness type information
- *
- * @example
- * ```typescript
- * const types = getColorBlindnessTypes();
- *
- * for (const cvd of types) {
- *   console.log(`${cvd.name} (${cvd.type})`);
- *   console.log(`  ${cvd.description}`);
- *   console.log(`  Affects: ${cvd.prevalence}`);
- * }
- *
- * // Output:
- * // Protanopia (protanopia)
- * //   Red-blind: reds appear dark, red-green confusion
- * //   Affects: ~1% of males
- * // Deuteranopia (deuteranopia)
- * //   Green-blind: greens shift to brown, red-green confusion
- * //   Affects: ~1% of males
- * // ...
- * ```
- */
+export function analyzeWcagAllCvd(image: ImageInput, options?: WcagOptions): Promise<CvdWcagReport>;
+export function analyzeWcagAllCvdSync(image: ImageInput, options?: WcagOptions): CvdWcagReport;
 export function getColorBlindnessTypes(): ColorBlindnessTypeInfo[];
 
-// ============================================================================
-// Diff Fingerprint API
-// ============================================================================
-
-/**
- * Magnitude of a diff, bucketed into categories
- */
 export type DiffMagnitude = 'tiny' | 'small' | 'medium' | 'large' | 'massive';
-
-/**
- * A compact fingerprint representing a diff's key characteristics.
- * Used for grouping similar diffs across comparisons.
- */
 export interface DiffFingerprint {
-  /** Number of clusters (distinct change regions) */
-  clusterCount: number;
-
-  /** Normalized positions of cluster centers (0.0-1.0 relative to image dimensions) */
-  clusterPositions: [number, number][];
-
-  /** Normalized sizes of clusters (area as ratio of total image area) */
-  clusterSizes: number[];
-
-  /** Average intensity across all clusters (0-255 scale) */
-  avgIntensity: number;
-
-  /** Average cluster density (pixels / bounding_box_area) */
-  avgDensity: number;
-
-  /**
-   * Spatial distribution hash using a 4x4 grid (16 zones).
-   * Each bit represents whether that zone contains a cluster center.
-   */
+  regionCount: number;
+  regionPositions: [number, number][];
+  regionSizes: number[];
+  meanDeltaE: number | null;
+  averageDensity: number;
   zoneMask: number;
-
-  /** Overall diff percentage bucketed into categories */
   diffMagnitude: DiffMagnitude;
-
-  /** Pre-computed coarse hash for fast grouping (hex string) */
   hash: string;
 }
-
-/**
- * Compute a fingerprint from a diff result (synchronous)
- *
- * Creates a compact fingerprint that can be used to identify and group similar diffs
- * across different image comparisons. Requires that the diff result was computed with
- * `includeClusters: true`.
- *
- * @param diffResult - The result from a compare() call with clusters enabled
- * @param imageWidth - Width of the compared images in pixels
- * @param imageHeight - Height of the compared images in pixels
- * @returns A DiffFingerprint object, or null if no clusters are present
- *
- * @example
- * ```typescript
- * const result = await compare('baseline.png', 'current.png', {
- *   includeClusters: true
- * });
- *
- * const fingerprint = computeFingerprintSync(result, 1920, 1080);
- * if (fingerprint) {
- *   console.log(`Hash: ${fingerprint.hash}`);
- *   console.log(`Zones: ${fingerprint.zoneMask.toString(2).padStart(16, '0')}`);
- * }
- * ```
- */
-export function computeFingerprintSync(
-  diffResult: DiffResult,
-  imageWidth: number,
-  imageHeight: number
-): DiffFingerprint | null;
-
-/**
- * Compare two fingerprints and return a similarity score (synchronous)
- *
- * Returns a score from 0.0 (completely different) to 1.0 (identical).
- * The similarity is computed using weighted factors:
- * - Zone mask overlap (40%): Same regions affected
- * - Cluster count similarity (20%): Similar number of change regions
- * - Diff magnitude match (15%): Similar overall change size
- * - Density similarity (15%): Similar change patterns (solid vs scattered)
- * - Intensity similarity (10%): Similar change intensity
- *
- * @param fp1 - First fingerprint to compare
- * @param fp2 - Second fingerprint to compare
- * @returns Similarity score from 0.0 to 1.0
- *
- * @example
- * ```typescript
- * const similarity = fingerprintSimilaritySync(fp1, fp2);
- * if (similarity > 0.8) {
- *   console.log('These diffs are likely the same change!');
- * }
- * ```
- */
-export function fingerprintSimilaritySync(fp1: DiffFingerprint, fp2: DiffFingerprint): number;
-
-/**
- * Get the coarse hash of a fingerprint (synchronous)
- *
- * Returns a hex string that can be used for fast exact-match grouping.
- * Diffs with the same coarse hash are very likely to be the same visual change.
- *
- * The hash combines:
- * - Zone mask (16 bits): Which regions are affected
- * - Diff magnitude (3 bits): Overall change size
- * - Cluster count bucket (2 bits): Number of change regions
- *
- * @param fingerprint - The fingerprint to hash
- * @returns A 16-character hex string
- *
- * @example
- * ```typescript
- * const hash = fingerprintHashSync(fingerprint);
- * console.log(`Hash: ${hash}`); // e.g., "0000000000000021"
- *
- * // Use for grouping
- * const groups = new Map<string, DiffFingerprint[]>();
- * for (const fp of fingerprints) {
- *   const h = fingerprintHashSync(fp);
- *   if (!groups.has(h)) groups.set(h, []);
- *   groups.get(h)!.push(fp);
- * }
- * ```
- */
+export function computeFingerprintSync(analysis: DiffAnalysis): DiffFingerprint | null;
+export function fingerprintSimilaritySync(left: DiffFingerprint, right: DiffFingerprint): number;
 export function fingerprintHashSync(fingerprint: DiffFingerprint): string;