@vizzly-testing/honeydiff 0.2.0 → 0.3.0

package/README.md

@@ -4,358 +4,513 @@
 [![npm downloads](https://img.shields.io/npm/dm/@vizzly-testing/honeydiff.svg)](https://www.npmjs.com/package/@vizzly-testing/honeydiff)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/vizzly-testing/honeydiff/blob/main/LICENSE)
 
-Blazingly fast image comparison for Node.js. Perfect for visual regression testing, screenshot
-validation, and detecting visual changes.
-
-**Why Honeydiff?**
-- **Fast:** Native performance processing 230M+ pixels/sec
-- **Smart:** Intelligent anti-aliasing detection filters rendering artifacts
-- **Accessible:** Built-in WCAG contrast checking and color blindness simulation
-- **Flexible:** File paths or Buffers, async or sync APIs
-- **Complete:** TypeScript types, pre-built binaries for all platforms
-- **Advanced:** SSIM perceptual scoring, spatial clustering, variable-height screenshots
-
-## Installation
+**Blazingly fast image comparison for visual regression testing in Node.js.** Built with Rust for native performance.
 
 ```bash
 npm install @vizzly-testing/honeydiff
 ```
 
-**Requirements:** Node.js 22+
+Requires Node.js 22+. Pre-built binaries included for macOS (ARM64), Linux (x64/ARM64), and Windows (x64).
+
+## Why Honeydiff?
 
-Pre-built binaries included for macOS (ARM64), Linux (x64/ARM64), and Windows (x64). No compilation
-required.
+- **6x faster than odiff** - Processes 230M+ pixels/sec with multi-core parallelization
+- **Smart anti-aliasing** - Filters out rendering artifacts, not actual changes
+- **Accessibility built-in** - WCAG contrast analysis for catching accessibility violations
+- **Flexible inputs** - Works with file paths or Buffers
+- **Full TypeScript support** - Complete type definitions included
+- **Advanced analytics** - SSIM perceptual scoring, spatial clustering, intensity stats
+
+Built for production visual regression testing at scale.
 
 ## Quick Start
 
-**JavaScript**
+### Basic Comparison
+
 ```javascript
 const { compare, quickCompare } = require('@vizzly-testing/honeydiff');
 
-// Quick check
+// Quick boolean check - are these images different?
 if (await quickCompare('baseline.png', 'current.png')) {
   console.log('Visual regression detected!');
 }
 
-// Detailed comparison
+// Detailed comparison with tolerance
 const result = await compare('baseline.png', 'current.png', {
-  pixelTolerance: 10,
-  includeSSIM: true
+  pixelTolerance: 10,  // Ignore tiny differences
+  includeSSIM: true    // Perceptual similarity score
 });
 
-console.log(`Diff: ${result.diffPercentage.toFixed(2)}%, SSIM: ${result.perceptualScore}`);
+console.log(`Diff: ${result.diffPercentage.toFixed(2)}%`);
+console.log(`SSIM: ${result.perceptualScore}`);
 // Output: Diff: 3.55%, SSIM: 0.9234
 ```
 
-**TypeScript**
+### TypeScript
 
 ```typescript
 import { compare, CompareOptions, DiffResult } from '@vizzly-testing/honeydiff';
 
-const result: DiffResult = await compare('img1.png', 'img2.png', {
+const options: CompareOptions = {
   pixelTolerance: 5,
   includeSSIM: true,
   includeClusters: true
-});
+};
+
+const result: DiffResult = await compare('img1.png', 'img2.png', options);
 
 if (result.diffClusters) {
-  console.log(`Found ${result.diffClusters.length} diff regions`);
+  console.log(`Found ${result.diffClusters.length} different regions`);
 }
-// Output: Found 3 diff regions
 ```
 
-## API
+### Test Integration
 
-**Async (recommended)**
-- `compare(img1, img2, options?): Promise<DiffResult>` - Full comparison
-- `quickCompare(img1, img2): Promise<boolean>` - Quick check
-- `getDimensions(img): Promise<{ width: number, height: number }>` - Get image dimensions
+**Jest/Vitest**
+```javascript
+import { quickCompare } from '@vizzly-testing/honeydiff';
 
-**Sync (blocks event loop)**
-- `compareSync(img1, img2, options?): DiffResult`
-- `quickCompareSync(img1, img2): boolean`
-- `getDimensionsSync(img): { width: number, height: number }` - Get image dimensions
+test('homepage should match baseline', async () => {
+  let screenshot = await page.screenshot();
+  let isDifferent = await quickCompare('baseline.png', screenshot);
+  expect(isDifferent).toBe(false);
+});
+```
 
-Inputs: `string` (file path) or `Buffer`
+**Playwright**
+```javascript
+const { compare } = require('@vizzly-testing/honeydiff');
 
-## Options & Results
+test('button hover state', async () => {
+  await page.hover('[data-testid="submit-button"]');
+  let screenshot = await page.screenshot();
 
-<details>
-<summary><strong>CompareOptions</strong></summary>
+  let result = await compare('baseline.png', screenshot, {
+    pixelTolerance: 10,
+    diffPath: './artifacts/diff.png'
+  });
 
-```typescript
-interface CompareOptions {
-  pixelTolerance?: number;        // 0-255 (default: 0)
-  colorThreshold?: number;        // 0.0-1.0 for YIQ mode (default: 0.0 = RGB)
-  antialiasing?: boolean;         // Enable AA detection (default: true)
-  ignoreColors?: boolean;         // Brightness only (default: false)
-  maxDiffs?: number;              // Stop after N diffs (default: unlimited)
-  includeDiffPixels?: boolean;    // Detailed pixel list (default: false)
-  includeClusters?: boolean;      // Spatial clusters (default: false)
-  includeSSIM?: boolean;          // SSIM score (default: false)
-  includeAccessibilityData?: boolean;  // RGB, luminance, WCAG (default: false)
-  checkColorBlindness?: boolean;  // Color blindness simulation (default: false)
-  colorBlindnessThreshold?: number;  // Visibility threshold 0-255 (default: 30)
-  diffPath?: string;              // Save diff image
-  maskPath?: string;              // Save mask image
-  overlayPath?: string;           // Save overlay image
-  overwrite?: boolean;            // Overwrite files (default: false)
-}
+  expect(result.diffPercentage).toBeLessThan(1.0);
+});
 ```
-</details>
 
-<details>
-<summary><strong>DiffResult</strong></summary>
+## Core Features
 
-```typescript
-interface DiffResult {
-  isDifferent: boolean;
-  diffPercentage: number;
-  totalPixels: number;
-  diffPixels: number;
-  aaPixelsIgnored: number;
-  aaPercentage: number;
-  boundingBox: BoundingBox | null;
-  heightDiff: HeightDiff | null;
-  diffPixelsList: DiffPixel[] | null;
-  diffClusters: DiffCluster[] | null;
-  intensityStats: IntensityStats | null;
-  perceptualScore: number | null;  // SSIM 0.0-1.0
-}
-```
-</details>
+### 1. Performance at Scale
 
-## Examples
+Process 230M pixels/second with automatic multi-core parallelization. Perfect for CI/CD pipelines.
 
-**Get Image Dimensions**
 ```javascript
-const { getDimensions, getDimensionsSync } = require('@vizzly-testing/honeydiff');
+// 18.3M pixel screenshot compared in ~79ms
+const result = await compare('full-page-baseline.png', 'full-page-current.png');
+```
 
-// Async
-let dims = await getDimensions('screenshot.png');
-console.log(`Image is ${dims.width}x${dims.height} pixels`);
-// Output: Image is 1920x1080 pixels
+### 2. Smart Anti-Aliasing Detection
 
-// Sync
-let dims = getDimensionsSync('screenshot.png');
-console.log(`Image is ${dims.width}x${dims.height} pixels`);
+Automatically filters out rendering artifacts (font smoothing, sub-pixel differences) while catching real visual changes.
 
-// Works with buffers too
-let buffer = fs.readFileSync('image.png');
-let dims = await getDimensions(buffer);
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  antialiasing: true  // Default: true
+});
+
+console.log(`Ignored ${result.aaPixelsIgnored} AA pixels`);
+// Output: Ignored 1952904 AA pixels
 ```
 
-**Buffers**
+Disable for pixel-perfect matching:
 ```javascript
-const fs = require('fs');
-const { compare } = require('@vizzly-testing/honeydiff');
+const result = await compare('img1.png', 'img2.png', {
+  antialiasing: false  // Strict pixel matching
+});
+```
 
-let img1 = fs.readFileSync('image1.png');
-let img2 = fs.readFileSync('image2.png');
-let result = await compare(img1, img2, { pixelTolerance: 5 });
+### 3. Variable Height Screenshots
+
+Perfect for scrollable content - compare full-page screenshots with different heights.
+
+```javascript
+// 24,162px vs 24,412px tall images
+const result = await compare('full-page-v1.png', 'full-page-v2.png');
+
+if (result.heightDiff) {
+  console.log(`Height difference: ${result.heightDiff.height1} vs ${result.heightDiff.height2}`);
+  console.log(`Extra pixels: ${result.heightDiff.extraPixels}`);
+}
 ```
 
-**Diff Images**
+### 4. Visual Diff Artifacts
+
+Generate highlighted diff images, binary masks, and overlays for debugging.
 
 ```javascript
-let result = await compare('baseline.png', 'current.png', {
-  diffPath: './diff.png',
-  maskPath: './mask.png',
-  overlayPath: './overlay.png',
+const result = await compare('baseline.png', 'current.png', {
+  diffPath: './artifacts/diff.png',      // Highlighted differences
+  maskPath: './artifacts/mask.png',      // Binary diff mask
+  overlayPath: './artifacts/overlay.png', // Side-by-side comparison
   overwrite: true
 });
+
+console.log('Artifacts saved to ./artifacts/');
 ```
 
-**Clustering & Metrics**
+### 5. Spatial Clustering
+
+Group nearby differences into regions to identify distinct changed areas.
+
 ```javascript
-let result = await compare('img1.png', 'img2.png', {
-  includeClusters: true,
-  includeSSIM: true,
-  includeDiffPixels: true
+const result = await compare('img1.png', 'img2.png', {
+  includeClusters: true
 });
 
-// Spatial clusters
 if (result.diffClusters) {
-  result.diffClusters.forEach((c, i) => {
-    console.log(`Region ${i + 1}: ${c.pixelCount} pixels at (${c.centerOfMass[0]}, ${c.centerOfMass[1]})`);
+  result.diffClusters.forEach((cluster, i) => {
+    console.log(`Region ${i + 1}:`);
+    console.log(`  - ${cluster.pixelCount} pixels changed`);
+    console.log(`  - Center at (${cluster.centerOfMass[0]}, ${cluster.centerOfMass[1]})`);
+    console.log(`  - Bounding box: ${cluster.boundingBox.width}x${cluster.boundingBox.height}`);
+    console.log(`  - Average intensity: ${cluster.avgIntensity}`);
   });
 }
 // Output:
-// Region 1: 12450 pixels at (245, 189)
-// Region 2: 3891 pixels at (672, 401)
-// Region 3: 1023 pixels at (1156, 823)
+// Region 1:
+//   - 12450 pixels changed
+//   - Center at (245, 189)
+//   - Bounding box: 124x89
+//   - Average intensity: 127.3
+```
+
+### 6. Perceptual Similarity (SSIM)
+
+Beyond pixel counting - measure structural similarity from a human perception perspective.
+
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  includeSSIM: true  // Note: Can be slow on large images
+});
 
-// SSIM score
 if (result.perceptualScore !== null) {
   console.log(`SSIM: ${result.perceptualScore.toFixed(3)}`);
-}
-// Output: SSIM: 0.923
+  // Output: SSIM: 0.923 (0.0 = different, 1.0 = identical)
 
-// Intensity stats
-if (result.intensityStats) {
-  console.log(`Range: ${result.intensityStats.min}-${result.intensityStats.max}, Mean: ${result.intensityStats.mean.toFixed(1)}`);
+  if (result.perceptualScore > 0.95) {
+    console.log('Images are perceptually very similar');
+  }
 }
-// Output: Range: 12-255, Mean: 87.3
 ```
 
-**Accessibility Features**
+### 7. Tolerance & Color Spaces
 
+**RGB Mode (default)** - Exact matching with pixel tolerance:
 ```javascript
-// WCAG contrast checking and RGB analysis
-let result = await compare('baseline.png', 'current.png', {
-  includeClusters: true,
-  includeAccessibilityData: true
+const result = await compare('img1.png', 'img2.png', {
+  pixelTolerance: 10  // Ignore differences below threshold (0-255)
 });
+```
 
-if (result.diffClusters) {
-  result.diffClusters.forEach(cluster => {
-    if (cluster.accessibilityMetadata) {
-      let meta = cluster.accessibilityMetadata;
-      console.log(`RGB diffs: R=${meta.avgRDiff}, G=${meta.avgGDiff}, B=${meta.avgBDiff}`);
-      console.log(`Dominant channel: ${meta.dominantChannel}`);
-      console.log(`WCAG contrast: ${meta.contrastRatio.toFixed(2)}:1`);
-
-      if (meta.contrastRatio < 4.5) {
-        console.log('⚠️  Below WCAG AA threshold');
-      }
-    }
-  });
-}
+**YIQ Mode** - Perceptual color matching weighted for human vision:
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  colorThreshold: 0.1  // YIQ mode (odiff-compatible)
+});
+```
 
-// Color blindness simulation
-let result = await compare('baseline.png', 'current.png', {
-  includeClusters: true,
-  checkColorBlindness: true
+**Brightness-only Mode** - Ignore color, compare structure:
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  ignoreColors: true  // Compare brightness/luminance only
 });
+```
 
-if (result.diffClusters) {
-  result.diffClusters.forEach(cluster => {
-    if (cluster.accessibilityMetadata?.colorBlindnessImpact) {
-      let impact = cluster.accessibilityMetadata.colorBlindnessImpact;
-      console.log(`Visibility score: ${(impact.visibilityScore * 100).toFixed(0)}%`);
-      console.log(`Deuteranopia (red-green): ${impact.deuteranopiaVisible ? '✓' : '✗'}`);
-      console.log(`Protanopia (red-weak): ${impact.protanopiaVisible ? '✓' : '✗'}`);
-      console.log(`Tritanopia (blue-yellow): ${impact.tritanopiaVisible ? '✓' : '✗'}`);
-
-      if (impact.visibilityScore < 0.5) {
-        console.log('⚠️  May not be visible to colorblind users');
-      }
-    }
-  });
-}
+### 8. Buffer Support
+
+Work with in-memory images from screenshots or API responses.
+
+```javascript
+const fs = require('fs');
+
+// Compare buffers directly
+let img1 = fs.readFileSync('image1.png');
+let img2 = fs.readFileSync('image2.png');
+let result = await compare(img1, img2, { pixelTolerance: 5 });
+
+// Mix paths and buffers
+let screenshot = await page.screenshot();  // Returns Buffer
+let result = await compare('baseline.png', screenshot);
+```
+
+### 9. Image Dimensions
+
+Fast utility to get image dimensions without loading full image data.
+
+```javascript
+const { getDimensions } = require('@vizzly-testing/honeydiff');
+
+let dims = await getDimensions('screenshot.png');
+console.log(`Image is ${dims.width}x${dims.height} pixels`);
+// Output: Image is 1920x1080 pixels
+
+// Works with buffers too
+let buffer = fs.readFileSync('image.png');
+let dims = await getDimensions(buffer);
 ```
 
-**Complete Result Example**
+## Accessibility Features
+
+Built-in WCAG color contrast analysis to catch accessibility violations in screenshots and UI designs.
+
+### WCAG Contrast Analysis
+
+Analyze entire images for WCAG color contrast violations - perfect for catching accessibility issues in screenshots and UI designs.
+
 ```javascript
-let result = await compare('baseline.png', 'current.png', {
-  pixelTolerance: 10,
-  includeClusters: true
+const { analyzeWcagContrast, saveWcagOverlay } = require('@vizzly-testing/honeydiff');
+
+// Analyze a screenshot for accessibility violations
+let analysis = await analyzeWcagContrast('screenshot.png', {
+  edgeThreshold: 60,      // Edge detection sensitivity (0-255)
+  minRegionSize: 50,      // Minimum violation region size (pixels)
+  checkAA: true,          // Check WCAG AA (4.5:1 normal, 3.0:1 large)
+  checkAAA: true          // Check WCAG AAA (7.0:1 normal, 4.5:1 large)
 });
 
-console.log(JSON.stringify(result, null, 2));
+console.log(`Total edges analyzed: ${analysis.totalEdges}`);
+console.log(`AA normal text pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
+console.log(`Found ${analysis.violations.length} violations`);
+
+// Examine violations
+analysis.violations.forEach((violation, i) => {
+  console.log(`\nViolation ${i + 1}:`);
+  console.log(`  Location: (${violation.boundingBox.x}, ${violation.boundingBox.y})`);
+  console.log(`  Contrast ratio: ${violation.contrastRatio.toFixed(2)}:1`);
+  console.log(`  Foreground: rgb(${violation.foregroundColor.slice(0,3).join(', ')})`);
+  console.log(`  Background: rgb(${violation.backgroundColor.slice(0,3).join(', ')})`);
+  console.log(`  Fails AA normal: ${violation.failsAaNormal}`);
+  console.log(`  Fails AAA normal: ${violation.failsAaaNormal}`);
+});
+
+// Generate visual overlay showing violations
+await saveWcagOverlay('screenshot.png', analysis, 'violations.png', {
+  highlightColor: [255, 0, 0, 180]  // Semi-transparent red
+});
 ```
 
-<details>
-<summary>Example output (click to expand)</summary>
-
-```json
-{
-  "isDifferent": true,
-  "diffPercentage": 3.55,
-  "totalPixels": 18309000,
-  "diffPixels": 650086,
-  "aaPixelsIgnored": 1952904,
-  "aaPercentage": 10.67,
-  "boundingBox": {
-    "x": 124,
-    "y": 89,
-    "width": 1456,
-    "height": 2301
-  },
-  "heightDiff": {
-    "height1": 24162,
-    "height2": 24412,
-    "extraPixels": 187500
-  },
-  "diffPixelsList": null,
-  "diffClusters": [
-    {
-      "pixelCount": 12450,
-      "centerOfMass": [245, 189]
-    },
-    {
-      "pixelCount": 3891,
-      "centerOfMass": [672, 401]
-    }
-  ],
-  "intensityStats": {
-    "min": 12,
-    "max": 255,
-    "mean": 87.3,
-    "median": 76,
-    "stdDev": 45.2
-  },
-  "perceptualScore": null
-}
+**Advanced filtering:**
+```javascript
+let analysis = await analyzeWcagContrast('screenshot.png', {
+  edgeThreshold: 80,           // Higher = fewer false positives
+  minRegionSize: 100,          // Ignore tiny regions
+  maxContrastThreshold: 3.5,   // Only flag severe violations
+  checkAA: true,
+  checkAAA: false
+});
+
+console.log(`AA pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
 ```
-</details>
+
+## Complete API Reference
+
+### Async Functions (Recommended)
+
+**`compare(img1, img2, options?): Promise<DiffResult>`**
+
+Full comparison with detailed results.
+
+**`quickCompare(img1, img2): Promise<boolean>`**
+
+Fast boolean check - returns true if different, false if identical.
+
+**`getDimensions(img): Promise<{ width: number, height: number }>`**
+
+Get image dimensions without loading full image data.
+
+### Sync Functions (Blocks Event Loop)
+
+**`compareSync(img1, img2, options?): DiffResult`**
+
+Synchronous comparison. Use only when blocking behavior is required.
+
+**`quickCompareSync(img1, img2): boolean`**
+
+Synchronous boolean check.
+
+**`getDimensionsSync(img): { width: number, height: number }`**
+
+Synchronous dimension retrieval.
+
+### Input Types
+
+All functions accept:
+- `string` - File path to PNG image
+- `Buffer` - Image data in memory
+
+### CompareOptions
+
+```typescript
+interface CompareOptions {
+  // Basic options
+  pixelTolerance?: number;              // 0-255, ignore diffs below threshold (default: 0)
+  colorThreshold?: number;              // 0.0-1.0, YIQ mode threshold (default: 0.0 = RGB)
+  antialiasing?: boolean;               // Ignore AA artifacts (default: true)
+  ignoreColors?: boolean;               // Brightness only (default: false)
+  maxDiffs?: number;                    // Stop after N diffs (default: unlimited)
+
+  // Analysis options
+  includeDiffPixels?: boolean;          // List all diff pixels (memory intensive, default: false)
+  includeClusters?: boolean;            // Spatial clustering (default: false)
+  includeSSIM?: boolean;                // SSIM perceptual score (slow, default: false)
+
+  // Accessibility options
+  includeAccessibilityData?: boolean;   // RGB, luminance, WCAG (default: false)
+  checkColorBlindness?: boolean;        // Color blindness simulation (default: false)
+  colorBlindnessThreshold?: number;     // Visibility threshold 0-255 (default: 30.0)
+
+  // Output options
+  diffPath?: string;                    // Save diff image path
+  maskPath?: string;                    // Save mask image path
+  overlayPath?: string;                 // Save overlay image path
+  overwrite?: boolean;                  // Overwrite existing files (default: false)
+}
 ```
 
-## Use Cases
+### DiffResult
 
-- **Visual Regression Testing:** Detect unintended UI changes in your test suite
-- **Screenshot Validation:** Compare generated screenshots against baselines
-- **Accessibility Testing:** Validate WCAG contrast ratios and color blindness visibility
-- **Design QA:** Validate UI implementations match designs
-- **Cross-browser Testing:** Detect rendering differences across browsers
-- **Scrollable Content:** Compare full-page screenshots with variable heights
+```typescript
+interface DiffResult {
+  // Basic metrics
+  isDifferent: boolean;                 // Are images different?
+  diffPercentage: number;               // 0.0-100.0
+  totalPixels: number;
+  diffPixels: number;
+
+  // Anti-aliasing
+  aaPixelsIgnored: number;
+  aaPercentage: number;                 // 0.0-100.0
+
+  // Spatial info
+  boundingBox: BoundingBox | null;      // Rectangle containing all diffs
+  heightDiff: HeightDiff | null;        // Height difference info
+
+  // Advanced analysis
+  diffPixelsList: DiffPixel[] | null;   // Null unless includeDiffPixels enabled
+  diffClusters: DiffCluster[] | null;   // Null unless includeClusters enabled
+  intensityStats: IntensityStats | null; // Null unless includeDiffPixels enabled
+  perceptualScore: number | null;       // 0.0-1.0, null unless includeSSIM enabled
+}
+```
+
+See [index.d.ts](./index.d.ts) for complete type definitions.
 
 ## Performance
 
-Tested on real-world tall screenshots (750 x 24,162 pixels = 18.3M pixels):
+Benchmarked on 18.3M pixel screenshots (750 x 24,162 px):
 
 | Operation | Time | Throughput |
 |-----------|------|------------|
-| Basic comparison | ~79ms | 231.8M pixels/sec |
+| Basic RGB comparison | ~79ms | 231.8M pixels/sec |
+| With anti-aliasing | ~88ms | 208M pixels/sec |
+| YIQ color space | ~89ms | 206M pixels/sec |
 | With artifacts (diff/mask/overlay) | ~432ms | 42.4M pixels/sec |
 
-**6x faster than odiff** on large screenshots with excellent multi-core parallelization.
+**vs odiff:** 6.0x faster (79ms vs 474ms)
+
+Multi-core parallelization: 215-309% CPU utilization across cores.
 
 *Benchmarked on Apple M-series Mac.*
 
-## Advanced Features
+## Common Patterns
+
+### CI/CD Integration
+
+```javascript
+const { compare } = require('@vizzly-testing/honeydiff');
+
+async function visualRegressionTest() {
+  let result = await compare('baseline.png', 'current.png', {
+    pixelTolerance: 10,
+    maxDiffs: 1000,  // Early exit for fast failure
+    diffPath: process.env.CI ? './artifacts/diff.png' : undefined
+  });
+
+  if (result.isDifferent && result.diffPercentage > 1.0) {
+    console.error(`Visual regression: ${result.diffPercentage.toFixed(2)}% changed`);
+    process.exit(1);
+  }
+}
+```
 
-**Accessibility Testing**
-- **RGB Channel Analysis:** Track which color channels changed (R/G/B)
-- **Luminance Tracking:** Measure perceived brightness using sRGB relative luminance
-- **WCAG Contrast Ratios:** Validate contrast meets AA (4.5:1) and AAA (7:1) standards
-- **Color Blindness Simulation:** Test visibility for deuteranopia, protanopia, tritanopia, and achromatopsia
-- **Visibility Scoring:** 0-100% score indicating how visible changes are to colorblind users
+### Progressive Enhancement
 
-**Variable Height Screenshots**
-Compare scrollable content with different heights. Overlapping regions are compared pixel-by-pixel,
-extra rows counted as differences.
+```javascript
+// Start with quick check
+if (await quickCompare('baseline.png', 'current.png')) {
+  // Only run expensive analysis if different
+  let result = await compare('baseline.png', 'current.png', {
+    includeClusters: true,
+    includeSSIM: true,
+    diffPath: './diff.png'
+  });
 
-**Color Spaces**
-- RGB mode (default): Exact matching, fastest performance
-- YIQ mode: Perceptual matching weighted for human vision
+  // Detailed analysis and reporting
+  reportVisualRegression(result);
+}
+```
 
-**Spatial Clustering**
-Group nearby differences into regions using 8-connectivity clustering. Useful for identifying distinct changed areas.
+### Tolerance Thresholds
 
-**SSIM Scoring**
-Structural Similarity Index (0.0-1.0) provides perceptual similarity measurement beyond pixel differences.
+```javascript
+const result = await compare('baseline.png', 'current.png', {
+  pixelTolerance: 10
+});
+
+if (result.diffPercentage > 5.0) {
+  console.error('FAIL: Major visual regression');
+  process.exit(1);
+} else if (result.diffPercentage > 1.0) {
+  console.warn('WARN: Minor visual changes detected');
+} else {
+  console.log('PASS: Visual test passed');
+}
+```
 
 ## Troubleshooting
 
 **Module not found errors**
-Ensure you're on Node.js 22+ and your platform is supported (macOS ARM64, Linux x64/ARM64, Windows x64).
+- Ensure Node.js 22+ is installed
+- Verify your platform is supported (macOS ARM64, Linux x64/ARM64, Windows x64)
+- Try `npm install` again to download pre-built binaries
 
 **Large memory usage with `includeDiffPixels`**
-This option stores every different pixel's position and intensity. Disable for large images with many differences.
+- This option stores every different pixel's position and intensity
+- Disable for large images with many differences
+- Only enable if you need detailed pixel-level data
 
 **Slow performance with `includeSSIM`**
-SSIM calculation is O(width × height × window²). Only enable when perceptual scoring is needed.
+- SSIM calculation is O(width × height × window²)
+- Only enable when perceptual scoring is needed
+- Consider running SSIM only on failed comparisons
+
+**Anti-aliasing too aggressive**
+- Set `antialiasing: false` for stricter pixel matching
+- Adjust `pixelTolerance` instead for controlled flexibility
+
+## Use Cases
+
+- **Visual Regression Testing** - Catch unintended UI changes in CI/CD
+- **Screenshot Validation** - Compare generated screenshots against baselines
+- **Accessibility Testing** - Validate WCAG contrast and color blindness visibility
+- **Design QA** - Ensure implementations match design specifications
+- **Cross-browser Testing** - Detect rendering differences across browsers
+- **A/B Testing** - Measure visual differences between variants
+- **Responsive Design** - Compare layouts across viewports
+
+## Examples
+
+See [examples/](./examples/) directory:
+- [basic.js](./examples/basic.js) - Core features and accessibility
+- [buffers.js](./examples/buffers.js) - Working with in-memory images
+- [typescript.ts](./examples/typescript.ts) - TypeScript integration
+- [accessibility.js](./examples/accessibility.js) - WCAG and color blindness
 
 ## License
 

package/index.d.ts

@@ -49,42 +49,6 @@ export interface IntensityStats {
   stdDev: number;
 }
 
-export interface ColorBlindnessImpact {
-  /** Whether the difference is visible to people with deuteranopia (red-green color blindness) */
-  deuteranopiaVisible: boolean;
-  /** Whether the difference is visible to people with protanopia (red-weak color blindness) */
-  protanopiaVisible: boolean;
-  /** Whether the difference is visible to people with tritanopia (blue-yellow color blindness) */
-  tritanopiaVisible: boolean;
-  /** Whether the difference is visible to people with achromatopsia (complete color blindness) */
-  achromatopsiaVisible: boolean;
-  /** Overall visibility score (0.0-1.0, higher = more visible) */
-  visibilityScore: number;
-}
-
-export interface AccessibilityMetadata {
-  /** Average difference in red channel (0-255) */
-  avgRDiff: number;
-  /** Average difference in green channel (0-255) */
-  avgGDiff: number;
-  /** Average difference in blue channel (0-255) */
-  avgBDiff: number;
-  /** Dominant color channel ('R', 'G', or 'B') */
-  dominantChannel: string;
-  /** Average relative luminance of baseline pixels (0.0-1.0, sRGB) */
-  avgBaselineLuminance: number;
-  /** Average relative luminance of current pixels (0.0-1.0, sRGB) */
-  avgCurrentLuminance: number;
-  /** WCAG contrast ratio between average colors (1.0-21.0, values below 4.5 may fail WCAG AA) */
-  contrastRatio: number;
-  /** Minimum WCAG contrast ratio in this cluster (worst case) */
-  minContrastRatio: number;
-  /** Maximum WCAG contrast ratio in this cluster (best case) */
-  maxContrastRatio: number;
-  /** Color blindness visibility analysis (null unless checkColorBlindness is enabled) */
-  colorBlindnessImpact: ColorBlindnessImpact | null;
-}
-
 export interface DiffCluster {
   /** Number of pixels in this cluster */
   pixelCount: number;
@@ -94,8 +58,6 @@ export interface DiffCluster {
   avgIntensity: number;
   /** Bounding box containing this cluster */
   boundingBox: BoundingBox;
-  /** Accessibility metadata (null unless includeAccessibilityData is enabled) */
-  accessibilityMetadata: AccessibilityMetadata | null;
 }
 
 export interface DiffResult {
@@ -208,28 +170,6 @@ export interface CompareOptions {
    * @default false
    */
   overwrite?: boolean;
-
-  /**
-   * Include accessibility metadata (RGB channels, luminance, WCAG contrast)
-   * When enabled, each cluster will include detailed color and brightness analysis
-   * @default false
-   */
-  includeAccessibilityData?: boolean;
-
-  /**
-   * Check if differences are visible to color blind users
-   * Automatically enables includeAccessibilityData if not already enabled
-   * Tests visibility for deuteranopia, protanopia, tritanopia, and achromatopsia
-   * @default false
-   */
-  checkColorBlindness?: boolean;
-
-  /**
-   * Threshold for color blindness visibility detection (0-255)
-   * Differences below this threshold after color blindness simulation are considered invisible
-   * @default 30.0
-   */
-  colorBlindnessThreshold?: number;
 }
 
 // ============================================================================
@@ -381,3 +321,264 @@ export function getDimensions(img: ImageInput): Promise<ImageDimensions>;
  * ```
  */
 export function getDimensionsSync(img: ImageInput): ImageDimensions;
+
+// ============================================================================
+// WCAG Accessibility API
+// ============================================================================
+
+/**
+ * Options for WCAG color contrast analysis
+ */
+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
+   * Regions with contrast above this are excluded (gradient filtering)
+   * @default 3.5
+   */
+  maxContrastThreshold?: number;
+
+  /**
+   * Check WCAG AA compliance (4.5:1 for normal text, 3.0:1 for large text)
+   * @default true
+   */
+  checkAA?: boolean;
+
+  /**
+   * Check WCAG AAA compliance (7.0:1 for normal text, 4.5:1 for large text)
+   * @default false
+   */
+  checkAAA?: boolean;
+}
+
+/**
+ * A single WCAG color contrast violation region
+ */
+export interface ContrastViolation {
+  /** Bounding box containing this violation region */
+  boundingBox: BoundingBox;
+
+  /** List of pixel coordinates [x, y] in this violation */
+  pixels: [number, number][];
+
+  /** Center of mass [x, y] of the violation region */
+  centerOfMass: [number, number];
+
+  /** Number of pixels in this violation */
+  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 WCAG accessibility analysis 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 violations 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;
+}
+
+/**
+ * Analyze WCAG color contrast accessibility asynchronously (recommended)
+ *
+ * Detects text/content edges in an image and checks if they meet WCAG contrast requirements.
+ * This is useful for catching accessibility issues in screenshots and UI designs.
+ *
+ * @param img - Image to analyze (file path or Buffer)
+ * @param options - WCAG analysis options
+ * @returns Promise resolving to detailed accessibility analysis
+ *
+ * @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>;
+
+/**
+ * Analyze WCAG color contrast accessibility 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 - WCAG analysis options
+ * @returns Detailed accessibility analysis
+ *
+ * @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 - WCAG analysis 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 saveWcagOverlay(
+  img: 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 - WCAG analysis 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,
+  analysis: WcagAnalysis,
+  outputPath: string,
+  options?: WcagOutputOptions
+): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "main": "index.js",
   "types": "index.d.ts",
@@ -65,6 +65,16 @@
     "index.d.ts",
     "load-platform.js",
     "platforms/*.node",
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.js",
+    "platforms/*.node",
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.js",
+    "platforms/*.node",
     "README.md"
   ],
   "engines": {