@vizzly-testing/honeydiff 0.2.0 → 0.2.1

package/README.md

@@ -4,205 +4,300 @@
 [![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?
+
+- **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 checking and color blindness simulation
+- **Flexible inputs** - Works with file paths or Buffers
+- **Full TypeScript support** - Complete type definitions included
+- **Advanced analytics** - SSIM perceptual scoring, spatial clustering, intensity stats
 
-Pre-built binaries included for macOS (ARM64), Linux (x64/ARM64), and Windows (x64). No compilation
-required.
+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 (0.0 = different, 1.0 = identical)
+
+  if (result.perceptualScore > 0.95) {
+    console.log('Images are perceptually very similar');
+  }
 }
-// Output: SSIM: 0.923
+```
+
+### 7. Tolerance & Color Spaces
+
+**RGB Mode (default)** - Exact matching with pixel tolerance:
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  pixelTolerance: 10  // Ignore differences below threshold (0-255)
+});
+```
+
+**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)
+});
+```
+
+**Brightness-only Mode** - Ignore color, compare structure:
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  ignoreColors: true  // Compare brightness/luminance only
+});
+```
+
+### 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);
+```
 
-// Intensity stats
-if (result.intensityStats) {
-  console.log(`Range: ${result.intensityStats.min}-${result.intensityStats.max}, Mean: ${result.intensityStats.mean.toFixed(1)}`);
+## Accessibility Features
+
+Built-in accessibility testing to catch WCAG compliance issues and color blindness visibility problems.
+
+### WCAG Contrast Checking
+
+Validate that visual changes meet WCAG AA/AAA contrast standards.
+
+```javascript
+const result = await compare('baseline.png', 'current.png', {
+  includeClusters: true,
+  includeAccessibilityData: true
+});
+
+if (result.diffClusters) {
+  result.diffClusters.forEach(cluster => {
+    if (cluster.accessibilityMetadata) {
+      let meta = cluster.accessibilityMetadata;
+
+      console.log(`Contrast ratio: ${meta.contrastRatio.toFixed(2)}:1`);
+      console.log(`Range: ${meta.minContrastRatio.toFixed(2)} - ${meta.maxContrastRatio.toFixed(2)}`);
+
+      // WCAG validation
+      if (meta.minContrastRatio < 4.5) {
+        console.log('⚠️  Below WCAG AA normal text (4.5:1)');
+      }
+      if (meta.minContrastRatio < 3.0) {
+        console.log('⚠️  Below WCAG AA large text (3.0:1)');
+      }
+      if (meta.minContrastRatio >= 7.0) {
+        console.log('✓ Meets WCAG AAA (7.0:1)');
+      }
+    }
+  });
 }
-// Output: Range: 12-255, Mean: 87.3
 ```
 
-**Accessibility Features**
+### RGB Channel Analysis
+
+Track which color channels changed - useful for debugging design changes.
 
 ```javascript
-// WCAG contrast checking and RGB analysis
-let result = await compare('baseline.png', 'current.png', {
+const result = await compare('baseline.png', 'current.png', {
   includeClusters: true,
   includeAccessibilityData: true
 });
@@ -211,31 +306,40 @@ 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');
-      }
+      console.log(`Luminance: baseline=${meta.avgBaselineLuminance.toFixed(3)}, current=${meta.avgCurrentLuminance.toFixed(3)}`);
     }
   });
 }
+// Output:
+// RGB diffs: R=45.2, G=12.3, B=8.7
+// Dominant channel: R
+// Luminance: baseline=0.234, current=0.567
+```
+
+### Color Blindness Simulation
+
+Test if visual changes are visible to users with color vision deficiencies.
 
-// Color blindness simulation
-let result = await compare('baseline.png', 'current.png', {
+```javascript
+const result = await compare('baseline.png', 'current.png', {
   includeClusters: true,
-  checkColorBlindness: true
+  checkColorBlindness: true,
+  colorBlindnessThreshold: 30.0  // Sensitivity threshold (0-255)
 });
 
 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 ? '✓' : '✗'}`);
+      console.log(`Deuteranopia (red-green, ~1% of population): ${impact.deuteranopiaVisible ? '✓' : '✗'}`);
+      console.log(`Protanopia (red-weak, ~0.5%): ${impact.protanopiaVisible ? '✓' : '✗'}`);
+      console.log(`Tritanopia (blue-yellow, rare): ${impact.tritanopiaVisible ? '✓' : '✗'}`);
+      console.log(`Achromatopsia (grayscale, very rare): ${impact.achromatopsiaVisible ? '✓' : '✗'}`);
 
       if (impact.visibilityScore < 0.5) {
         console.log('⚠️  May not be visible to colorblind users');
@@ -245,117 +349,229 @@ if (result.diffClusters) {
 }
 ```
 
-**Complete Result Example**
+**Real-world example:**
+
 ```javascript
-let result = await compare('baseline.png', 'current.png', {
-  pixelTolerance: 10,
-  includeClusters: true
-});
+test('button color change is accessible', async () => {
+  let result = await compare('button-baseline.png', 'button-hover.png', {
+    includeClusters: true,
+    checkColorBlindness: true
+  });
+
+  // Ensure button hover is visible to colorblind users
+  let lowestVisibility = Math.min(
+    ...result.diffClusters.map(c =>
+      c.accessibilityMetadata?.colorBlindnessImpact?.visibilityScore ?? 1
+    )
+  );
 
-console.log(JSON.stringify(result, null, 2));
+  expect(lowestVisibility).toBeGreaterThan(0.7);
+});
 ```
 
-<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
+## 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)
 }
 ```
-</details>
-```
 
-## 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');
 
-**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
+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
+  });
 
-**Variable Height Screenshots**
-Compare scrollable content with different heights. Overlapping regions are compared pixel-by-pixel,
-extra rows counted as differences.
+  if (result.isDifferent && result.diffPercentage > 1.0) {
+    console.error(`Visual regression: ${result.diffPercentage.toFixed(2)}% changed`);
+    process.exit(1);
+  }
+}
+```
 
-**Color Spaces**
-- RGB mode (default): Exact matching, fastest performance
-- YIQ mode: Perceptual matching weighted for human vision
+### Progressive Enhancement
 
-**Spatial Clustering**
-Group nearby differences into regions using 8-connectivity clustering. Useful for identifying distinct changed areas.
+```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'
+  });
+
+  // Detailed analysis and reporting
+  reportVisualRegression(result);
+}
+```
 
-**SSIM Scoring**
-Structural Similarity Index (0.0-1.0) provides perceptual similarity measurement beyond pixel differences.
+### Tolerance Thresholds
+
+```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/package.json

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